142 lines
7.6 KiB
Plaintext
142 lines
7.6 KiB
Plaintext
# 项目需求文档：Web端 Claude Code 多会话管理平台（增强版）
|
||
|
||
## 1. 项目概述
|
||
本项目旨在构建一个基于 Web 的集成开发环境，让用户能够通过浏览器同时管理多个独立的 Claude Code 会话。平台将结合两个核心工具：
|
||
- **[`@instantlyeasy/claude-code-sdk-ts`](https://www.npmjs.com/package/@instantlyeasy/claude-code-sdk-ts)**：用于与本地 Claude Code CLI 交互，执行代码任务、控制会话模式、管理工具权限。
|
||
- **[`claude-code-config-manager`](https://www.npmjs.com/package/claude-code-config-manager)**：用于查看和管理 Claude Code 的本地配置（MCP 服务器、Skills、Subagents、Hooks 等）。
|
||
|
||
平台核心特色是支持**多分页（Tabs）并行运行**，每个分页代表一个独立的会话组，组内可以包含多个并行窗格。用户可以在任意窗格中恢复之前的会话，并灵活切换工作模式。
|
||
|
||
## 2. 目标用户
|
||
- 需要同时处理多个代码库或任务的开发者。
|
||
- 希望直观管理 Claude Code 配置（MCP、Skills）的用户。
|
||
- 需要对比不同 Claude 会话输出的研究人员或测试者。
|
||
- 需要并行监控多个 AI 任务进度的技术负责人。
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 多会话管理
|
||
- **分页式基础**：主界面顶部提供标签栏，每个标签对应一个**会话组**（Session Group），一个组内可以包含多个并行窗格。
|
||
- **会话隔离**：每个**窗格**（Pane）代表一个独立的 Claude Code 会话，拥有独立的：
|
||
- 对话历史（输入/输出）
|
||
- 会话 ID（用于 SDK 的 `.withSessionId()`）
|
||
- 工作目录
|
||
- 模式设置（plan/ask/auto）
|
||
- 工具权限（允许/禁止的工具列表）
|
||
- **会话持久化**：所有窗格的会话状态（历史记录、元数据、布局信息）保存到本地数据库（如 SQLite），浏览器刷新后自动恢复所有标签及其窗格布局。
|
||
|
||
### 3.2 多窗格布局与并行监控
|
||
- **动态布局切换**：用户可通过工具栏按钮快速切换当前标签页内的窗格布局模式，至少支持：
|
||
- **单窗格**（聚焦一个会话）
|
||
- **双窗格**（左右或上下并排）
|
||
- **四窗格**（2x2 网格）
|
||
- **自定义**：允许拖拽调整窗格大小，甚至创建更多窗格（如 1+2 混合布局）。
|
||
- **窗格独立运行**：每个窗格实时显示其关联会话的输入/输出流，互不干扰。用户可以在不同窗格中同时输入指令，并行观察 AI 响应。
|
||
- **布局记忆**：每个标签页的布局模式（窗格数量、大小比例）随会话状态一起保存，恢复时还原。
|
||
- **焦点与操作**：当前活动窗格（正在输入或最后交互的窗格）应有视觉高亮；全局命令（如“停止所有”）可作用于所有窗格。
|
||
|
||
### 3.3 Claude Code 交互能力（基于 SDK）
|
||
- **输入/输出流**：每个窗格提供类似终端的输入框和输出区域，支持流式输出（打字机效果）。
|
||
- **模式控制**：
|
||
- **Plan 模式**：通过 `.denyTools` 限制所有写操作，仅输出计划文本。
|
||
- **Ask 模式**：允许写工具，但不调用 `.skipPermissions()`，每次文件操作前弹出确认对话框（确认框与对应窗格绑定）。
|
||
- **Auto 模式**：调用 `.skipPermissions()`，自动执行所有允许的操作。
|
||
- **工具权限管理**：用户可在窗格侧边栏勾选允许/禁止的工具（如 Read、Write、Grep、Bash 等），实时影响后续请求。
|
||
- **工作目录设置**：每个窗格可指定本地项目路径（通过文件选择器或手动输入）。
|
||
- **会话 ID 管理**：窗格自动保存 SDK 返回的会话 ID，用于保持上下文连续。
|
||
|
||
### 3.4 配置管理（基于 Config Manager）
|
||
- **配置查看器**：集成 Config Manager 的查看功能，在一个独立面板（或弹出窗口）中显示：
|
||
- 所有发现的 Claude Code 项目（来自 `~/.claude.json`）。
|
||
- 每个项目下的 Agents、Slash Commands、Skills、Hooks、MCP 服务器配置。
|
||
- 用户级配置（`~/.claude/` 下）。
|
||
- **配置操作**（可选）：支持复制、删除配置（参考 Config Manager 的功能），未来可扩展编辑。
|
||
- **实时同步**：当用户在 Config Manager 中修改配置后，SDK 会话能够感知变化（例如重新加载工具列表）。
|
||
|
||
### 3.5 历史日志与审计
|
||
- **本地存储**：所有窗格的完整交互日志（时间戳、角色、内容、工具调用）保存到数据库。
|
||
- **日志搜索**：支持按会话、关键词、时间范围搜索历史记录。
|
||
- **导出功能**：允许导出单个会话或全部日志为 JSON/Markdown。
|
||
|
||
### 3.6 用户界面要求
|
||
- **布局**：
|
||
- 顶部：标签栏 + 新建标签按钮 + **布局切换控件（单/双/四网格）** + 全局设置。
|
||
- 主区域：当前标签页的**动态网格布局**，每个网格单元格为一个独立的对话窗格。
|
||
- 右侧可折叠侧边栏：当前**焦点窗格**的模式/工具设置、工作目录选择、会话信息（点击窗格时更新）。
|
||
- 底部（或独立面板）：配置管理器视图。
|
||
- **响应式设计**：在桌面端保证 1920x1080 下的多窗格体验，平板等小屏设备可自动降级为单窗格。
|
||
- **拖拽调整**：支持拖拽窗格分隔线调整大小（类似 IDE 分屏）。
|
||
- **实时反馈**：每个窗格内显示各自的加载状态、错误提示（Toast 通知）。
|
||
|
||
## 4. 技术栈建议
|
||
- **前端框架**：Vue 3 + Vite（利用 Vue 的响应式系统管理多个窗格状态）。
|
||
- **布局组件**：使用 **`vue-grid-layout`** 或 **`golden-layout`**（Vue 适配版）实现可拖拽、可动态增减的网格布局。
|
||
- **UI 组件库**：PrimeVue（与 Config Manager 保持一致）提供按钮、标签页、弹窗等。
|
||
- **状态管理**：Pinia，设计如下 store 结构：
|
||
```ts
|
||
interface Pane {
|
||
id: string;
|
||
sessionId: string;
|
||
name: string;
|
||
mode: Mode;
|
||
allowedTools: string[];
|
||
deniedTools: string[];
|
||
workingDirectory: string;
|
||
messages: Message[];
|
||
layout: { x: number; y: number; w: number; h: number };
|
||
}
|
||
|
||
interface Tab {
|
||
id: string;
|
||
name: string;
|
||
panes: Pane[];
|
||
layoutConfig: any;
|
||
}
|
||
```
|
||
后端：Node.js + Express + Socket.IO，为每个窗格维护独立的 WebSocket 通道。
|
||
|
||
数据库：SQLite，存储窗格元数据及历史消息。
|
||
|
||
与 Claude Code 交互：使用 @instantlyeasy/claude-code-sdk-ts 管理子进程和会话。
|
||
|
||
5. 数据流与架构
|
||
graph TD
|
||
A[前端多窗格] -->|WebSocket| B(后端服务)
|
||
A -->|HTTP| B
|
||
B --> C[SQLite 数据库]
|
||
B --> D[文件系统]
|
||
B --> E[Claude Code 子进程池]
|
||
E --> F[本地项目]
|
||
D --> G[配置文件 ~/.claude.json]
|
||
B --> H[Config Manager 解析器]
|
||
|
||
6. 详细功能点
|
||
多窗格布局实现：使用 vue-grid-layout 管理每个窗格的坐标和尺寸。
|
||
|
||
模式与权限映射：每个窗格独立设置 mode 和 allowedTools，构建 SDK 请求时动态应用。
|
||
|
||
上下文恢复：通过后端存储的 sessionId 恢复 SDK 会话，并拉取历史消息。
|
||
|
||
配置管理集成：复用 Config Manager 的文件扫描逻辑，提供 REST API 供前端调用。
|
||
|
||
7. 非功能需求
|
||
最大并发窗格数可配置（默认 6）。
|
||
|
||
流式输出延迟 < 500ms。
|
||
|
||
关闭窗格时立即终止对应子进程。
|
||
|
||
所有文件操作限制在沙盒目录内。
|
||
|
||
8. 开发阶段规划
|
||
基础框架与单窗格 (Vue+Express+SDK 集成)
|
||
|
||
多窗格布局实现 (vue-grid-layout + 并行通信)
|
||
|
||
会话持久化与恢复 (SQLite + 布局记忆)
|
||
|
||
Ask 模式与工具确认 (弹窗绑定窗格)
|
||
|
||
配置管理集成 (Config Manager 后端复用)
|
||
|
||
优化与测试 (压力测试、内存泄漏) |