Spec Client Store

Vue3 reactive store for spec client state management.

安装

npm install @codewave/spec-client-store
# 或
pnpm add @codewave/spec-client-store
# 或
yarn add @codewave/spec-client-store

功能特性

• 文件管理 (files): 文件系统状态管理，支持增量同步和文件监听
• 沙箱管理 (sandbox): 沙箱连接和状态管理
• 聊天管理 (chat): 会话和消息管理，支持历史消息加载
• 编辑器管理 (editor): 文档编辑状态管理，支持自动保存和冲突检测
• 需求管理 (spec): 需求文档和技术文档管理，支持文件解析和状态同步

使用

在 Vue 组件中使用（推荐）

<script setup lang="ts">
import { createStore, useStore, type FileAPI, type SandboxAPI } from '@codewave/spec-client-store';

// 在根组件中创建 store
// createStore 会自动通过 provide 向下传递 store
// 并在 onBeforeMount 时自动初始化所有 stores
const store = createStore({
  fileAPI,
  sandboxAPI,
  sandboxCallbacks: {
    onConnect: () => console.log('沙箱已连接'),
    onDisconnect: () => console.log('沙箱已断开'),
  },
  editorCallbacks: {
    onBeforeSave: (filePath, content) => {
      console.log('保存前:', filePath);
    },
    onAfterSave: (filePath, content) => {
      console.log('保存后:', filePath);
    },
    onSaveConflict: (filePath, documentLastModified, fileLastModified) => {
      console.warn('保存冲突:', filePath);
    },
  },
});

// 在子组件中使用 useStore 获取 store
const store = useStore();

// 访问 state
store.files.state.files; // 文件列表
store.sandbox.state.status; // 'close' | 'connected' | 'connecting' | 'disconnect'
store.chat.state.sessions; // 会话列表
store.editor.state.documents; // 文档列表
store.spec.state.specs; // 需求列表

// 调用 actions
await store.files.saveFile('path/to/file', 'content');
await store.chat.sendMessage('sessionId', 'message');
await store.editor.loadDocument('path/to/file');
await store.spec.addSpec('需求名称');
</script>

直接使用（非组件环境）

import { createStore, type FileAPI, type SandboxAPI, type Logger } from '@codewave/spec-client-store';

// 实现 FileAPI 接口
const fileAPI: FileAPI = {
  async getAppFiles() {
    // 实现获取应用文件的逻辑
    return {};
  },
  async getFile(path: string) {
    // 实现获取指定文件的逻辑
    return null;
  },
  async instruct(actions) {
    // 实现写入文件的逻辑
    return { lastModified: Date.now() };
  },
};

// 实现 SandboxAPI 接口
const sandboxAPI: SandboxAPI = {
  async createSandbox() {
    // 实现创建沙箱的逻辑
    return { url: 'http://localhost:3030', sandboxId: 'sandbox-id' };
  },
  async checkSandboxReady(url: string, sandboxId?: string) {
    // 实现检查沙箱就绪状态的逻辑
    return true;
  },
};

// 可选：自定义 logger
const logger: Logger = {
  debug: (...args) => console.debug('[DEBUG]', ...args),
  info: (...args) => console.info('[INFO]', ...args),
  warn: (...args) => console.warn('[WARN]', ...args),
  error: (...args) => console.error('[ERROR]', ...args),
};

// 创建 store 实例
// 注意：在非组件环境中，需要手动调用各个 store 的 init 方法
const store = createStore({ 
  fileAPI, 
  sandboxAPI,
  logger, // 可选，默认为 console
});

// 手动初始化所有 stores（在组件环境中会自动执行）
await store.files.init();
await store.spec.init();
await store.chat.init(store.spec.state.specs); // 需要传入 specs 数组
await store.sandbox.init();

API 说明

createStore(options: CreateStoreOptions): Store

创建并初始化所有的 store。

特性：

• 自动通过 Vue 的 provide 向下传递 store
• 自动在 onBeforeMount 时初始化所有 stores（按顺序：files → spec → chat → sandbox）
• 必须在 Vue 组件的 setup 函数中调用

参数：

• fileAPI: FileAPI - 文件 API 接口
• sandboxAPI: SandboxAPI - 沙箱 API 接口
• logger?: Logger - 日志接口（可选，默认为 console）
• sandboxCallbacks?: SandboxSocketCallbacks - 沙箱连接事件回调（可选）
• editorCallbacks?: EditorCallbacks - 编辑器事件回调（可选）

useStore(): Store

在子组件中获取 store 实例。

注意：

• 必须在 createStore 的子组件中使用
• 必须在 Vue 组件的 setup 函数中调用
• 如果找不到 store，会抛出错误

Store 说明

Files Store

文件系统状态管理，支持：

• 文件增删改查
• 增量同步（通过 sandbox 文件监听）
• 批量操作

Sandbox Store

沙箱连接和状态管理，支持：

• 自动连接和重连
• 连接状态监听
• 沙箱客户端实例管理

Chat Store

会话和消息管理，支持：

• 会话创建和管理
• 消息发送和接收
• 历史消息加载（支持异步加载）
• 消息中止功能

Editor Store

文档编辑状态管理，支持：

• 文档加载和同步
• 自动保存（60秒防抖）
• 保存冲突检测
• 未保存文件追踪

Spec Store

需求文档和技术文档管理，支持：

• 需求创建和管理
• 文件系统解析（requirements、plan、tasks）
• 状态同步（500ms 防抖）
• 增量更新

开发

# 安装依赖
pnpm install

# 类型检查
pnpm type-check

# 构建
pnpm build

# 开发模式（watch）
pnpm dev

项目结构

src/
  ├── types/          # 类型定义
  │   ├── files.ts    # 文件相关类型
  │   ├── sandbox.ts  # 沙箱相关类型
  │   ├── chat.ts     # 聊天相关类型
  │   ├── editor.ts   # 编辑器相关类型
  │   ├── spec.ts     # 需求相关类型
  │   └── store.ts    # Store 配置类型
  ├── stores/         # Store 实现
  │   ├── files.ts    # 文件状态管理
  │   ├── sandbox.ts  # 沙箱状态管理
  │   ├── chat.ts     # 聊天状态管理
  │   ├── editor.ts   # 编辑器状态管理
  │   └── spec.ts     # 需求状态管理
  ├── utils/          # 工具函数
  │   ├── parse.ts    # 解析相关工具
  │   └── spec.ts     # 需求相关工具
  └── index.ts        # 主入口文件