Add project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-05 09:33:11 +08:00
parent 4b9d30f795
commit 9074aabe1c
9 changed files with 1987 additions and 0 deletions
@@ -0,0 +1,363 @@
+# 类型系统、工具函数与状态管理分析
+
+## 类型系统
+
+### 类型定义目录结构
+
+```mermaid
+graph TB
+    subgraph types/
+        CMD[command.ts<br/>命令类型]
+        GEN[generated/<br/>生成类型]
+        HOOKS[hooks.ts<br/>Hook 类型]
+        IDS[ids.ts<br/>ID 类型]
+        LOGS[logs.ts<br/>日志类型]
+        PERM[permissions.ts<br/>权限类型]
+        PLUGIN[plugin.ts<br/>插件类型]
+        TEXT[textInputTypes.ts<br/>文本输入类型]
+    end
+
+    subgraph 核心类型定义
+        TOOL_TYPE[Tool.ts<br/>工具类型]
+        MSG[types/message.ts<br/>消息类型]
+        TOOL_TYPES[types/tools.ts<br/>工具进度类型]
+    end
+
+    subgraph Schema 验证
+        SCHEMAS[schemas/<br/>Zod Schema]
+    end
+```
+
+### 关键类型定义
+
+#### 权限类型 (`types/permissions.ts`)
+```typescript
+// 权限模式
+type PermissionMode =
+  | 'default'      // 默认：提示用户
+  | 'plan'         // 计划：只读操作
+  | 'bypassPermissions'  // 绕过所有权限
+  | 'auto'         // 自动允许
+  | 'dontAsk'      // 不询问
+
+// 权限结果
+type PermissionResult =
+  | { allowed: true }
+  | { allowed: false; reason: string }
+```
+
+#### 工具进度类型 (`types/tools.ts`)
+```typescript
+type ToolProgressData =
+  | BashProgress
+  | AgentToolProgress
+  | MCPProgress
+  | REPLToolProgress
+  | SkillToolProgress
+  | TaskOutputProgress
+  | WebSearchProgress
+```
+
+#### 消息类型 (`types/message.ts`)
+```typescript
+type Message =
+  | UserMessage
+  | AssistantMessage
+  | SystemMessage
+  | ProgressMessage
+  | AttachmentMessage
+  | SystemLocalCommandMessage
+```
+
+## 状态管理
+
+```mermaid
+flowchart TD
+    A[state/] --> B[AppState.tsx<br/>应用状态]
+    A --> C[AppStateStore.ts<br/>状态存储]
+    A --> D[store.ts<br/>Store 定义]
+    A --> E[onChangeAppState.ts<br/>状态变更监听]
+    A --> F[selectors.ts<br/>状态选择器]
+    A --> G[teammateViewHelpers.ts<br/>队友视图辅助]
+
+    B --> H[全局应用状态]
+    H --> I[当前会话]
+    H --> J[MCP 连接]
+    H --> K[工具列表]
+    H --> L[消息历史]
+    H --> M[设置状态]
+    H --> N[代理状态]
+    H --> O[权限上下文]
+```
+
+### AppState 核心状态
+
+```mermaid
+classDiagram
+    class AppState {
+        +Session currentSession
+        +MCPState mcp
+        +ToolsState tools
+        +MessagesState messages
+        +SettingsState settings
+        +AgentState agents
+        +PermissionContext permissions
+        +BridgeState bridge
+        +UIState ui
+    }
+
+    class Session {
+        +string id
+        +string model
+        +Message[] messages
+        +number totalCost
+        +number totalTokens
+    }
+
+    class MCPState {
+        +MCPServerConnection[] connections
+        +Tool[] tools
+    }
+
+    class AgentState {
+        +AgentInfo[] activeAgents
+        +TeamInfo[] teams
+        +TaskInfo[] tasks
+    }
+
+    AppState --> Session
+    AppState --> MCPState
+    AppState --> AgentState
+```
+
+## 工具函数 (utils/)
+
+```mermaid
+graph TB
+    subgraph 核心工具
+        PERM_UTILS[permissions/<br/>权限工具函数]
+        FILE_CACHE[fileStateCache.ts<br/>文件状态缓存]
+        ENV[envUtils.ts<br/>环境工具]
+        SYSTEM[systemPromptType.ts<br/>系统提示类型]
+    end
+
+    subgraph 文件操作
+        FILE_HISTORY[fileHistory.ts<br/>文件历史]
+        FILE_STATE[fileStateCache.ts<br/>文件状态缓存]
+    end
+
+    subgraph 代理工具
+        AGENT_SWARM[agentSwarmsEnabled.ts<br/>代理集群开关]
+        WORKTREE[worktreeModeEnabled.ts<br/>Worktree 模式开关]
+        TOOL_SEARCH[toolSearch.ts<br/>工具搜索]
+        TASKS[tasks.ts<br/>任务工具]
+    end
+
+    subgraph Shell 工具
+        SHELL[shell/<br/>Shell 相关工具]
+    end
+
+    subgraph 其他工具
+        THEME[theme.ts<br/>主题管理]
+        THINK[thinking.ts<br/>思考模式]
+        TOKEN[tokenEstimation<br/>Token 估算]
+        COMMIT[commitAttribution.ts<br/>提交归因]
+        TOOL_RESULT[toolResultStorage.ts<br/>工具结果存储]
+        DENIAL[denialTracking.ts<br/>拒绝追踪]
+        EMBEDDED[embeddedTools.ts<br/>内嵌工具]
+    end
+```
+
+## Schema 验证体系
+
+使用 Zod v4 进行配置验证。
+
+```mermaid
+flowchart TD
+    A[schemas/<br/>Zod Schema 定义] --> B[配置验证]
+    B --> C[settings.json<br/>设置文件]
+    B --> D[CLAUDE.md<br/>项目指令]
+    B --> E[plugins/<br/>插件配置]
+    B --> F[keybindings<br/>快捷键配置]
+```
+
+## 上下文管理
+
+```mermaid
+flowchart TD
+    A[context.ts] --> B[系统上下文收集]
+    A --> C[用户上下文收集]
+
+    B --> D[操作系统信息]
+    B --> E[Shell 环境]
+    B --> F[工作目录信息]
+    B --> G[Git 状态]
+
+    C --> H[CLAUDE.md 指令]
+    C --> I[项目文件结构]
+    C --> J[对话历史]
+    C --> K[工具结果]
+
+    subgraph context/ 子模块
+        L[notifications.ts<br/>通知]
+        M[其他上下文模块]
+    end
+```
+
+## 任务管理
+
+```mermaid
+flowchart TD
+    A[tasks.ts] --> B[Task.ts<br/>任务类型定义]
+    A --> C[tasks/<br/>任务实现]
+
+    D[TaskCreateTool] --> E[创建任务]
+    F[TaskUpdateTool] --> G[更新任务状态]
+    H[TaskGetTool] --> I[获取任务详情]
+    J[TaskListTool] --> K[列出所有任务]
+    L[TaskOutputTool] --> M[获取后台任务输出]
+    N[TaskStopTool] --> O[停止任务]
+
+    E --> P[状态: pending]
+    P --> Q[状态: in_progress]
+    Q --> R[状态: completed]
+    Q --> S[状态: deleted]
+
+    subgraph 任务依赖
+        T[addBlocks<br/>设置阻塞关系]
+        U[addBlockedBy<br/>设置被阻塞关系]
+    end
+```
+
+## 成本追踪
+
+```mermaid
+flowchart TD
+    A[cost-tracker.ts] --> B[Token 计数]
+    A --> C[成本估算]
+    A --> D[阈值监控]
+
+    B --> E[输入 Token]
+    B --> F[输出 Token]
+    B --> G[缓存读取 Token]
+    B --> H[缓存写入 Token]
+
+    D --> I[成本阈值提醒]
+    D --> J[用量限制检查]
+
+    K[costHook.ts] --> L[成本 Hook<br/>每次查询后更新]
+```
+
+## 历史记录管理
+
+```mermaid
+flowchart TD
+    A[history.ts] --> B[会话历史存储]
+    A --> C[消息历史]
+    A --> D[命令历史]
+
+    B --> E[会话恢复<br/>/resume]
+    C --> F[上下文压缩<br/>/compact]
+    D --> G[命令补全<br/>useArrowKeyHistory]
+```
+
+## 配置迁移
+
+```mermaid
+flowchart LR
+    A[migrations/] --> B[配置版本检测]
+    B --> C{版本匹配?}
+    C -->|需要迁移| D[执行迁移脚本]
+    C -->|已是最新| E[跳过]
+    D --> F[更新配置格式]
+```
+
+## Bash 解析器 (utils/bash/)
+
+Claude Code 实现了一个完整的 Bash 语法解析器，用于分析和理解 Shell 命令：
+
+```mermaid
+flowchart TD
+    A[utils/bash/<br/>Bash 解析系统] --> B[parser.ts<br/>语法解析器]
+    A --> C[ast.ts<br/>抽象语法树]
+    A --> D[commands.ts<br/>命令解析]
+    A --> E[shellQuoting.ts<br/>Shell 引用处理]
+
+    B --> F[管道链解析<br/>识别管道操作]
+    B --> G[重定向解析<br/>识别重定向操作]
+    B --> H[变量展开<br/>识别环境变量]
+    B --> I[子 Shell 解析<br/>识别嵌套命令]
+
+    subgraph 用途
+        J[BashTool 命令语义分析<br/>commandSemantics.ts]
+        K[破坏性命令检测<br/>destructiveCommandWarning.ts]
+        L[只读验证<br/>readOnlyValidation.ts]
+        L2[sed 命令验证<br/>sedValidation.ts]
+    end
+```
+
+## 内存目录系统 (memdir/)
+
+```mermaid
+flowchart TD
+    A[memdir/<br/>持久化内存目录] --> B[memdir.ts<br/>内存目录管理]
+    A --> C[memoryTypes.ts<br/>记忆类型定义]
+    A --> D[memoryScan.ts<br/>记忆扫描]
+    A --> E[paths.ts<br/>路径管理]
+
+    B --> F[自动记忆<br/>auto memory]
+    B --> G[团队记忆<br/>team memory]
+
+    subgraph 记忆存储结构
+        H[MEMORY.md<br/>索引文件<br/>~150字/行]
+        I[*.md<br/>记忆文件<br/>frontmatter 格式]
+    end
+
+    F --> H
+    G --> H
+    H --> I
+```
+
+## 任务类型体系
+
+```mermaid
+classDiagram
+    class TaskBase {
+        +string id
+        +string subject
+        +string description
+        +TaskStatus status
+    }
+
+    class LocalShellTask {
+        +后台 Shell 执行
+    }
+
+    class LocalAgentTask {
+        +本地代理任务
+    }
+
+    class RemoteAgentTask {
+        +远程代理任务
+    }
+
+    class DreamTask {
+        +AI 规划任务
+    }
+
+    class LocalWorkflowTask {
+        +工作流脚本任务
+    }
+
+    class MonitorMcpTask {
+        +MCP 监控任务
+    }
+
+    TaskBase <|-- LocalShellTask
+    TaskBase <|-- LocalAgentTask
+    TaskBase <|-- RemoteAgentTask
+    TaskBase <|-- DreamTask
+    TaskBase <|-- LocalWorkflowTask
+    TaskBase <|-- MonitorMcpTask
+```
+```