# 项目需求文档：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 后端复用)

优化与测试 (压力测试、内存泄漏)