# Claude Code 架构学习与研究 > **导读**：本项目是一个关于 CLI Agent 架构的学习研究仓库。所有内容均基于互联网上公开的资料与讨论整理而成，特别参考了目前非常受欢迎的 CLI Agent `claude-code` 的相关公开信息。我们的初衷是帮助大家更好地理解和使用 Agent 技术，未来也会持续推出更多关于 Agent 架构解析与实践的探讨内容，感谢各位的关注与支持！ > **免责声明**: 本仓库内容仅用于技术研究和科研爱好者交流学习参考，**严禁任何个人、机构及组织将其用于商业用途、盈利性活动、非法用途及其他未经授权的场景。** 若内容涉及侵犯您的合法权益、知识产权或存在其他侵权问题，请及时联系我们，我们将第一时间核实并予以删除处理。 **语言**: [English](README.md) | **中文** | [한국어](README_KR.md) | [日本語](README_JA.md) --- ## 目录 - [深度分析文档 (`docs/`)](#深度分析文档-docs) — 遥测、模型代号、卧底模式、远程控制、未来路线图 - [目录参考](#目录参考) — 代码结构树 - [架构概览](#架构概览) — 入口 → 查询引擎 → 工具/服务/状态 - [工具系统与权限架构](#工具系统与权限架构) — 40+ 工具、权限流、子代理 - [12 个渐进式安全带机制](#12-个渐进式安全带机制-harness-mechanisms) — Claude Code 如何在代理循环上构建生产特性 --- ## 深度分析文档 (`docs/`) 基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告，中英双语。 ``` docs/ ├── en/ # English │ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out │ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external │ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos │ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides │ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools │ └── zh/ # 中文 ├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出 ├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异 ├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份 ├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖 └── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具 ``` > 点击文件名即可跳转到对应报告。 | # | 主题 | 核心发现 | 链接 | |---|------|---------|------| | 01 | **遥测与隐私** | 双层分析管道（1P, Datadog）。环境指纹、进程指标、每个事件携带会话/用户 ID。**没有面向用户的退出开关**。`OTEL_LOG_TOOL_DETAILS=1` 可记录完整工具输入。 | [EN](docs/en/01-telemetry-and-privacy.md) · [中文](docs/zh/01-遥测与隐私分析.md) | | 02 | **隐藏功能与代号** | 动物代号体系（Capybara v8, Tengu, Fennec→Opus 4.6, **Numbat** 下一代）。Feature flag 用随机词对掩盖用途。内部用户获得更好的 prompt 和验证代理。隐藏命令：`/btw`、`/stickers`。 | [EN](docs/en/02-hidden-features-and-codenames.md) · [中文](docs/zh/02-隐藏功能与模型代号.md) | | 03 | **卧底模式** | 官方员工在公开仓库自动进入卧底模式。模型指令："**不要暴露你的掩护身份**" — 剥离所有 AI 归属，commit 看起来像人类写的。**没有强制关闭选项。** | [EN](docs/en/03-undercover-mode.md) · [中文](docs/zh/03-卧底模式分析.md) | | 04 | **远程控制与 Killswitch** | 每小时轮询 `/api/claude_code/settings`。危险变更弹出阻塞对话框 — **拒绝 = 程序退出**。6+ 紧急开关（绕过权限、快速模式、语音模式、分析 sink）。GrowthBook 可无同意改变任何用户行为。 | [EN](docs/en/04-remote-control-and-killswitches.md) · [中文](docs/zh/04-远程控制与紧急开关.md) | | 05 | **未来路线图** | **Numbat** 代号确认。Opus 4.7 / Sonnet 4.8 开发中。**KAIROS** = 完全自主代理模式，心跳 ``、推送通知、PR 订阅。语音模式（push-to-talk）已就绪。发现 17 个未上线工具。 | [EN](docs/en/05-future-roadmap.md) · [中文](docs/zh/05-未来路线图.md) | --- ## 版权与免责声明 ``` 本仓库仅用于技术研究和教育目的。严禁商业使用。 如果您是版权所有者并认为本仓库内容侵犯了您的权利， 请联系仓库所有者立即删除。 ``` --- ## 统计数据 | 项目 | 数量 | |------|------| | 文件 (.ts/.tsx) | ~1,884 | | 行数 | ~512,664 | | 最大单文件 | `query.ts` (~785KB) | | 内置工具 | ~40+ | | 斜杠命令 | ~80+ | | 依赖 (node_modules) | ~192 个包 | | 运行时 | Bun（编译为 Node.js >= 18 bundle）| --- ## 代理模式 ```text 核心循环 ======== 用户 --> messages[] --> Claude API --> 响应 | stop_reason == "tool_use"? / \ 是 否 | | 执行工具 返回文本 追加 tool_result 循环回退 -----------------> messages[] 这就是最小的代理循环。Claude Code 在此循环上 包裹了生产级线束：权限、流式传输、并发、 压缩、子代理、持久化和 MCP。 ``` --- ## 目录参考 ```text src/ ├── main.tsx # REPL 引导程序，4,683 行 ├── QueryEngine.ts # SDK/headless 查询生命周期引擎 ├── query.ts # 主代理循环 (785KB，最大文件) ├── Tool.ts # 工具接口 + buildTool 工厂 ├── Task.ts # 任务类型、ID、状态基类 ├── tools.ts # 工具注册、预设、过滤 ├── commands.ts # 斜杠命令定义 ├── context.ts # 用户输入上下文 ├── cost-tracker.ts # API 成本累积 ├── setup.ts # 首次运行设置流程 │ ├── bridge/ # Claude Desktop / 远程桥接 │ ├── bridgeMain.ts # 会话生命周期管理器 │ ├── bridgeApi.ts # HTTP 客户端 │ ├── bridgeConfig.ts # 连接配置 │ ├── bridgeMessaging.ts # 消息中继 │ ├── sessionRunner.ts # 进程生成 │ ├── jwtUtils.ts # JWT 刷新 │ ├── workSecret.ts # 认证令牌 │ └── capacityWake.ts # 基于容量的唤醒 │ ├── cli/ # CLI 基础设施 │ ├── handlers/ # 命令处理器 │ └── transports/ # I/O 传输 (stdio, structured) │ ├── commands/ # ~80 个斜杠命令 │ ├── agents/ # 代理管理 │ ├── compact/ # 上下文压缩 │ ├── config/ # 设置管理 │ ├── help/ # 帮助显示 │ ├── login/ # 身份验证 │ ├── mcp/ # MCP 服务器管理 │ ├── memory/ # 记忆系统 │ ├── plan/ # 计划模式 │ ├── resume/ # 会话恢复 │ ├── review/ # 代码审查 │ └── ... # 还有 70+ 个命令 │ ├── components/ # React/Ink 终端 UI │ ├── design-system/ # 可重用 UI 原语 │ ├── messages/ # 消息渲染 │ ├── permissions/ # 权限对话框 │ ├── PromptInput/ # 输入字段 + 建议 │ ├── LogoV2/ # 品牌 + 欢迎屏幕 │ ├── Settings/ # 设置面板 │ ├── Spinner.tsx # 加载指示器 │ └── ... # 还有 40+ 个组件组 │ ├── entrypoints/ # 应用入口点 │ ├── cli.tsx # CLI 主程序 (版本、帮助、守护进程) │ ├── sdk/ # Agent SDK (类型、会话) │ └── mcp.ts # MCP 服务器入口 │ ├── hooks/ # React hooks │ ├── useCanUseTool.tsx # 权限检查 │ ├── useReplBridge.tsx # 网桥连接 │ ├── notifs/ # 通知 hooks │ └── toolPermission/ # 工具权限处理程序 │ ├── services/ # 业务逻辑层 │ ├── api/ # Claude API 客户端 │ │ ├── claude.ts # 流式 API 调用 │ │ ├── errors.ts # 错误分类 │ │ └── withRetry.ts # 重试逻辑 │ ├── analytics/ # 遥测 + GrowthBook │ ├── compact/ # 上下文压缩 │ ├── mcp/ # MCP 连接管理 │ ├── tools/ # 工具执行引擎 │ │ ├── StreamingToolExecutor.ts # 并行工具运行器 │ │ └── toolOrchestration.ts # 批处理编排 │ ├── plugins/ # 插件加载器 │ └── settingsSync/ # 跨设备设置同步 │ ├── state/ # 应用状态 │ ├── AppStateStore.ts # Store 定义 │ └── AppState.tsx # React provider + hooks │ ├── tasks/ # 任务实现 │ ├── LocalShellTask/ # Bash 命令执行 │ ├── LocalAgentTask/ # 子代理执行 │ ├── RemoteAgentTask/ # 通过网桥连接远程代理 │ ├── InProcessTeammateTask/ # 进程内队友 │ └── DreamTask/ # 后台思考 │ ├── tools/ # 40+ 工具实现 │ ├── AgentTool/ # 子代理生成 + fork │ ├── BashTool/ # Shell 命令执行 │ ├── FileReadTool/ # 文件读取 (PDF, 图像等) │ ├── FileEditTool/ # 字符串替换编辑 │ ├── FileWriteTool/ # 完整文件创建 │ ├── GlobTool/ # 文件模式搜索 │ ├── GrepTool/ # 内容搜索 (ripgrep) │ ├── WebFetchTool/ # HTTP 获取 │ ├── WebSearchTool/ # Web 搜索 │ ├── MCPTool/ # MCP 工具包装器 │ ├── SkillTool/ # 技能调用 │ ├── AskUserQuestionTool/ # 用户交互 │ └── ... # 还有 30+ 个工具 │ ├── types/ # 类型定义 │ ├── message.ts # 消息辨识联合类型 │ ├── permissions.ts # 权限类型 │ ├── tools.ts # 工具进度类型 │ └── ids.ts # 带有品牌的 ID 类型 │ ├── utils/ # 工具函数（最大目录） │ ├── permissions/ # 权限规则引擎 │ ├── messages/ # 消息格式化 │ ├── model/ # 模型选择逻辑 │ ├── settings/ # 设置管理 │ ├── sandbox/ # 沙盒运行时适配器 │ ├── hooks/ # Hook 执行 │ ├── memory/ # 记忆系统工具 │ ├── git/ # Git 操作 │ ├── github/ # GitHub API │ ├── bash/ # Bash 执行辅助函数 │ ├── swarm/ # 多代理集群 │ ├── telemetry/ # 遥测报告 │ └── ... # 还有 30+ 个工具组 │ └── vendor/ # 原生模块存根 ├── audio-capture-src/ # 音频输入 ├── image-processor-src/ # 图像处理 ├── modifiers-napi-src/ # 原生修饰符 └── url-handler-src/ # URL 处理 ``` --- ## 架构概览 ```text ┌─────────────────────────────────────────────────────────────────────┐ │ 入口层 │ │ cli.tsx ──> main.tsx ──> REPL.tsx (交互式) │ │ └──> QueryEngine.ts (headless/SDK) │ └──────────────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ 查询引擎 │ │ submitMessage(prompt) ──> AsyncGenerator │ │ │ │ │ ├── fetchSystemPromptParts() ──> 组装系统提示词 │ │ ├── processUserInput() ──> 处理 /命令 │ │ ├── query() ──> 主代理循环 │ │ │ ├── StreamingToolExecutor ──> 并行工具执行 │ │ │ ├── autoCompact() ──> 上下文压缩 │ │ │ └── runTools() ──> 工具编排 │ │ └── yield SDKMessage ──> 流式传输给消费者 │ └──────────────────────────────┬──────────────────────────────────────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ 工具系统 │ │ 服务层 │ │ 状态层 │ │ │ │ │ │ │ │ 工具接口 │ │ api/claude.ts │ │ AppState Store │ │ ├─ call() │ │ API 客户端 │ │ ├─ permissions │ │ ├─ validate() │ │ compact/ │ │ ├─ fileHistory │ │ ├─ checkPerms() │ │ 自动压缩 │ │ ├─ agents │ │ ├─ render() │ │ mcp/ │ │ └─ fastMode │ │ └─ prompt() │ │ MCP 协议 │ │ │ │ │ │ analytics/ │ │ React Context │ │ 40+ 内置工具: │ │ 遥测 │ │ ├─ useAppState │ │ ├─ BashTool │ │ tools/ │ │ └─ useSetState │ │ ├─ FileRead │ │ 执行器 │ │ │ │ ├─ FileEdit │ │ plugins/ │ └──────────────────┘ │ ├─ Glob/Grep │ │ 加载器 │ │ ├─ AgentTool │ │ settingsSync/ │ │ ├─ WebFetch │ │ 跨设备同步 │ │ └─ MCPTool │ │ oauth/ │ │ │ │ 认证流程 │ └──────────────────┘ └─────────────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ │ 任务系统 │ │ 桥接层 │ │ │ │ │ │ 任务类型: │ │ bridgeMain.ts │ │ ├─ local_bash │ │ 会话管理 │ │ ├─ local_agent │ │ bridgeApi.ts │ │ ├─ remote_agent │ │ HTTP 客户端 │ │ ├─ in_process │ │ workSecret.ts │ │ ├─ dream │ │ 认证令牌 │ │ └─ workflow │ │ sessionRunner │ │ │ │ 进程生成 │ │ ID: 前缀+8字符 │ └─────────────────┘ │ b=bash a=agent │ │ r=remote t=team │ └──────────────────┘ ``` --- ## 数据流：单个查询生命周期 ```text 用户输入 (提示词 / 斜杠命令) │ ▼ processUserInput() ← 解析 /命令，构建 UserMessage │ ▼ fetchSystemPromptParts() ← 工具 → 提示词部分，CLAUDE.md 记忆 │ ▼ recordTranscript() ← 将用户消息持久化到磁盘 (JSONL) │ ▼ ┌─→ normalizeMessagesForAPI() ← 剥离仅 UI 使用的字段，需要时进行压缩 │ │ │ ▼ │ Claude API (流式) ← 带有工具 + 系统提示词的 POST /v1/messages │ │ │ ▼ │ 流事件 ← message_start → content_block_delta → message_stop │ │ │ ├─ 文本块 ──────────────────→ 传递给消费者 (SDK / REPL) │ │ │ └─ tool_use 块? │ │ │ ▼ │ StreamingToolExecutor ← 划分：并发安全 vs 串行 │ │ │ ▼ │ canUseTool() ← 权限检查 (钩子 + 规则 + UI 提示) │ │ │ ├─ 拒绝 ────────────────→ 追加 tool_result(error)，继续循环 │ │ │ └─ 允许 │ │ │ ▼ │ tool.call() ← 执行工具 (Bash, Read, Edit 等) │ │ │ ▼ │ 追加 tool_result ← 推入 messages[]，recordTranscript() │ │ └─────────┘ ← 循环回到 API 调用 │ ▼ (stop_reason != "tool_use") 生成结果消息 ← 最终文本、使用情况、成本、session_id ``` --- ## 工具系统与权限架构 ```text 工具接口 ============== buildTool(definition) ──> Tool 每个工具都实现： ┌────────────────────────────────────────────────────────┐ │ 生命周期 │ │ ├── validateInput() → 尽早拒绝无效参数 │ │ ├── checkPermissions() → 工具特定的授权检查 │ │ └── call() → 执行并返回结果 │ │ │ │ 能力特性 │ │ ├── isEnabled() → 功能开关检查 │ │ ├── isConcurrencySafe() → 是否可并行运行？ │ │ ├── isReadOnly() → 是否无副作用？ │ │ ├── isDestructive() → 是否为不可逆操作？ │ │ └── interruptBehavior() → 拦截还是阻塞等待用户？ │ │ │ │ 渲染 (React/Ink) │ │ ├── renderToolUseMessage() → 输入显示 │ │ ├── renderToolResultMessage() → 输出显示 │ │ ├── renderToolUseProgressMessage() → 加载状态/进度 │ │ └── renderGroupedToolUse() → 并行工具组显示 │ │ │ │ 面向 AI │ │ ├── prompt() → 提供给 LLM 的工具描述 │ │ ├── description() → 动态描述 │ │ └── mapToolResultToAPI() → 格式化为 API 响应 │ └────────────────────────────────────────────────────────┘ ``` ### 完整工具清单 ```text 文件操作 搜索与发现 执行 ═════════════════ ══════════════════════ ══════════ FileReadTool GlobTool BashTool FileEditTool GrepTool PowerShellTool FileWriteTool ToolSearchTool NotebookEditTool 交互 ═══════════ 网络与请求 代理与任务 AskUserQuestionTool ════════════════ ══════════════════ BriefTool WebFetchTool AgentTool WebSearchTool SendMessageTool 计划与工作流 TeamCreateTool ════════════════════ MCP 协议 TeamDeleteTool EnterPlanModeTool ══════════════ TaskCreateTool ExitPlanModeTool MCPTool TaskGetTool EnterWorktreeTool ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool ReadMcpResourceTool TaskListTool TodoWriteTool TaskStopTool TaskOutputTool 系统 ════════ 技能与扩展 ConfigTool ═════════════════════ SkillTool SkillTool ScheduleCronTool LSPTool SleepTool TungstenTool ``` --- ## 权限系统 ```text 工具调用请求 │ ▼ ┌─ validateInput() ──────────────────────────────────┐ │ 在任何权限检查之前拒绝无效的输入 │ └────────────────────┬───────────────────────────────┘ │ ▼ ┌─ PreToolUse Hooks (调用前钩子) ────────────────────┐ │ 用户定义的 shell 命令 (settings.json hooks) │ │ 可以：批准、拒绝或修改输入 │ └────────────────────┬───────────────────────────────┘ │ ▼ ┌─ 权限规则 (Permission Rules) ──────────────────────┐ │ alwaysAllowRules: 匹配工具名/模式 → 自动允许 │ │ alwaysDenyRules: 匹配工具名/模式 → 自动拒绝 │ │ alwaysAskRules: 匹配工具名/模式 → 总是询问 │ │ 来源：设置、CLI 参数、会话决策 │ └────────────────────┬───────────────────────────────┘ │ 没有规则匹配？ │ ▼ ┌─ 交互式提示 (Interactive Prompt) ──────────────────┐ │ 用户看到工具名称 + 输入参数 │ │ 选项：允许一次 / 总是允许 / 拒绝 │ └────────────────────┬───────────────────────────────┘ │ ▼ ┌─ checkPermissions() ───────────────────────────────┐ │ 工具特定的逻辑 (例如：路径沙盒检查) │ └────────────────────┬───────────────────────────────┘ │ 已批准 → tool.call() ``` --- ## 子代理与多代理架构 ```text 主代理 (MAIN AGENT) ========== │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────┐ ┌──────────────┐ │ FORK 代理 │ │ 远程代理 │ │ 进程内队友 │ │ │ │ │ │ │ │ Fork 进程 │ │ 网桥会话 │ │ 同一进程 │ │ 共享缓存 │ │ 完全隔离 │ │ 异步上下文 │ │ 全新 msgs[] │ │ │ │ 共享状态 │ └──────────────┘ └──────────┘ └──────────────┘ 生成模式 (SPAWN MODES): ├─ default → 进程内，共享对话 ├─ fork → 子进程，全新的 messages[]，共享文件缓存 ├─ worktree → 隔离的 git worktree + fork └─ remote → 通过网桥连接到 Claude Code Remote / 容器 通信机制: ├─ SendMessageTool → 代理间消息传递 ├─ TaskCreate/Update → 共享任务看板 └─ TeamCreate/Delete → 团队生命周期管理 集群模式 (SWARM MODE，特性受限): ┌─────────────────────────────────────────────┐ │ 领导代理 (Lead Agent) │ │ ├── 队友 A ──> 认领任务 1 │ │ ├── 队友 B ──> 认领任务 2 │ │ └── 队友 C ──> 认领任务 3 │ │ │ │ 共享：任务看板、消息收件箱 │ │ 隔离：messages[]、文件缓存、cwd │ └─────────────────────────────────────────────┘ ``` --- ## 上下文管理 (压缩系统) ```text 上下文窗口预算 ═════════════════════ ┌─────────────────────────────────────────────────────┐ │ 系统提示词 (工具、权限、CLAUDE.md) │ │ ══════════════════════════════════════════════ │ │ │ │ 对话历史 │ │ ┌─────────────────────────────────────────────┐ │ │ │ [旧消息的压缩摘要] │ │ │ │ ═══════════════════════════════════════════ │ │ │ │ [compact_boundary 标记] │ │ │ │ ─────────────────────────────────────────── │ │ │ │ [最近的消息 — 完整保真度] │ │ │ │ user → assistant → tool_use → tool_result │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ 当前轮次 (用户 + 助手响应) │ └─────────────────────────────────────────────────────┘ 三种压缩策略: ├─ autoCompact → 当 token 数量超过阈值时触发 │ 通过紧凑的 API 调用总结旧消息 ├─ snipCompact → 移除僵尸消息和过时标记 │ (HISTORY_SNIP feature flag) └─ contextCollapse → 重构上下文以提高效率 (CONTEXT_COLLAPSE feature flag) 压缩流程: messages[] ──> getMessagesAfterCompactBoundary() │ ▼ 旧消息 ──> Claude API (总结) ──> 压缩摘要 │ ▼ [摘要] + [compact_boundary] + [最近的消息] ``` --- ## MCP (模型上下文协议) 集成 ```text ┌─────────────────────────────────────────────────────────┐ │ MCP 架构 │ │ │ │ MCPConnectionManager.tsx │ │ ├── 服务器发现 (来自 settings.json 的配置) │ │ │ ├── stdio → 生成子进程 │ │ │ ├── sse → HTTP EventSource │ │ │ ├── http → 流式 HTTP │ │ │ ├── ws → WebSocket │ │ │ └── sdk → 进程内传输 │ │ │ │ │ ├── 客户端生命周期 │ │ │ ├── connect → initialize → list tools │ │ │ ├── 通过 MCPTool 包装器调用工具 │ │ │ └── disconnect / 带有退避的重连 │ │ │ │ │ ├── 身份验证 │ │ │ ├── OAuth 2.0 流程 (McpOAuthConfig) │ │ │ ├── 跨应用访问 (XAA / SEP-990) │ │ │ └── 通过 headers 传递 API key │ │ │ │ │ └── 工具注册 │ │ ├── mcp____ 命名约定 │ │ ├── 来自 MCP 服务器的动态 schema │ │ ├── 权限透传给 Claude Code │ │ └── 资源列表 (ListMcpResourcesTool) │ │ │ └─────────────────────────────────────────────────────────┘ ``` --- ## 桥接层 (Claude Desktop / Remote) ```text Claude Desktop / Web / Cowork Claude Code CLI ══════════════════════════ ═════════════════ ┌───────────────────┐ ┌──────────────────┐ │ 桥接客户端 │ ←─ HTTP ──→ │ bridgeMain.ts │ │ (Desktop App) │ │ │ └───────────────────┘ │ 会话管理器 │ │ ├── 生成 CLI │ 协议: │ ├── 轮询状态 │ ├─ JWT 身份验证 │ ├── 中继消息 │ ├─ 工作密钥交换 │ └── 容量唤醒 │ ├─ 会话生命周期 │ │ │ ├── create │ 退避策略: │ │ ├── run │ ├─ 连接: 2s→2m │ │ └─ stop │ └─ 生成: 500ms→30s│ └─ 令牌刷新调度器 └──────────────────┘ ``` --- ## 会话持久化 ```text 会话存储 ══════════════ ~/.claude/projects//sessions/ └── .jsonl ← 仅追加日志 ├── {"type":"user",...} ├── {"type":"assistant",...} ├── {"type":"progress",...} └── {"type":"system","subtype":"compact_boundary",...} 恢复流程: getLastSessionLog() ──> 解析 JSONL ──> 重建 messages[] │ ├── --continue → cwd 中的最后一次会话 ├── --resume → 特定会话 └── --fork-session → 新 ID，复制历史记录 持久化策略: ├─ 用户消息 → 阻塞等待写入 (用于崩溃恢复) ├─ 助手消息 → 即发即弃 (保持顺序的队列) ├─ 进度 → 内联写入 (在下一次查询时去重) └─ 刷新 → 在生成结果时 / cowork 急切刷新 ``` --- ## 功能开关系统 (Feature Flag) ```text 死代码消除 (Bun 编译时) ══════════════════════════════════════════ feature('FLAG_NAME') ──→ true → 包含在包中 ──→ false → 从包中剥离 标志 (在源码中观察到): ├─ COORDINATOR_MODE → 多代理协调器 ├─ HISTORY_SNIP → 激进的历史修剪 ├─ CONTEXT_COLLAPSE → 上下文重构 ├─ DAEMON → 后台守护进程 worker ├─ AGENT_TRIGGERS → cron/远程触发器 ├─ AGENT_TRIGGERS_REMOTE → 远程触发器支持 ├─ MONITOR_TOOL → MCP 监控工具 ├─ WEB_BROWSER_TOOL → 浏览器自动化 ├─ VOICE_MODE → 语音输入/输出 ├─ TEMPLATES → 任务分类器 ├─ EXPERIMENTAL_SKILL_SEARCH → 技能发现 ├─ KAIROS → 推送通知、文件发送 ├─ PROACTIVE → 睡眠工具、主动行为 ├─ OVERFLOW_TEST_TOOL → 测试工具 ├─ TERMINAL_PANEL → 终端捕获 ├─ WORKFLOW_SCRIPTS → 工作流工具 ├─ CHICAGO_MCP → 计算机使用 MCP ├─ DUMP_SYSTEM_PROMPT → 提示词提取 (仅限 ant) ├─ UDS_INBOX → 对等发现 ├─ ABLATION_BASELINE → 实验消融 └─ UPGRADE_NOTICE → 升级通知 运行时门控: ├─ process.env.USER_TYPE === 'ant' → 内部功能 └─ GrowthBook feature flags → 运行时的 A/B 实验 ``` --- ## 状态管理 ```text ┌──────────────────────────────────────────────────────────┐ │ AppState Store │ │ │ │ AppState { │ │ toolPermissionContext: { │ │ mode: PermissionMode, ← default/plan等 │ │ additionalWorkingDirectories, │ │ alwaysAllowRules, ← 自动批准 │ │ alwaysDenyRules, ← 自动拒绝 │ │ alwaysAskRules, ← 总是提示 │ │ isBypassPermissionsModeAvailable │ │ }, │ │ fileHistory: FileHistoryState, ← 撤销快照 │ │ attribution: AttributionState, ← 提交跟踪 │ │ verbose: boolean, │ │ mainLoopModel: string, ← 活动模型 │ │ fastMode: FastModeState, │ │ speculation: SpeculationState │ │ } │ │ │ │ React 集成: │ │ ├── AppStateProvider → 通过 createContext 创建 store │ │ ├── useAppState(sel) → 基于选择器的订阅 │ │ └── useSetAppState() → immer 风格的更新函数 │ └──────────────────────────────────────────────────────────┘ ``` --- ## 12 个渐进式安全带机制 (Harness Mechanisms) 该架构展示了生产级 AI 代理除了基本循环之外，所需的 12 层渐进式机制： ```text s01 核心循环 (THE LOOP) "一个循环 + Bash 就是你所需要的全部" query.ts: 调用 Claude API 的 while-true 循环， 检查 stop_reason，执行工具，追加结果。 s02 工具调度 (TOOL DISPATCH) "添加一个工具 = 添加一个处理程序" Tool.ts + tools.ts: 每个工具都注册到调度映射中。 循环保持不变。buildTool() 工厂提供安全的默认值。 s03 计划 (PLANNING) "没有计划的代理会迷失方向" EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool: 先列出步骤，然后执行。使完成率翻倍。 s04 子代理 (SUB-AGENTS) "拆分大任务；每个子任务清理上下文" AgentTool + forkSubagent.ts: 每个子代获得全新的 messages[]， 保持主对话的干净。 s05 按需知识 (KNOWLEDGE) "需要时加载知识" SkillTool + memdir/: 通过 tool_result 注入，而不是系统提示词。 按目录延迟加载 CLAUDE.md 文件。 s06 上下文压缩 (COMPRESSION) "上下文满了；腾出空间" services/compact/: 三层策略： autoCompact (总结) + snipCompact (修剪) + contextCollapse s07 持久化任务 (TASKS) "大目标 → 小任务 → 磁盘" TaskCreate/Update/Get/List: 基于文件的任务图， 具有状态跟踪、依赖关系和持久性。 s08 后台任务 (BACKGROUND) "后台执行慢操作；代理继续思考" DreamTask + LocalShellTask: 守护线程运行命令， 完成后注入通知。 s09 代理团队 (TEAMS) "一个人做太大 → 委派给队友" TeamCreate/Delete + InProcessTeammateTask: 具有异步邮箱的持久队友。 s10 团队协议 (PROTOCOLS) "共享通信规则" SendMessageTool: 一种请求-响应模式驱动 代理之间的所有协商。 s11 自主代理 (AUTONOMOUS) "队友自己扫描并认领任务" coordinator/coordinatorMode.ts: 空闲循环 + 自动认领， 不需要领导来分配每个任务。 s12 工作树隔离 (WORKTREE) "每个人在自己的目录中工作" EnterWorktreeTool/ExitWorktreeTool: 任务管理目标， 工作树管理目录，由 ID 绑定。 ``` --- ## 关键设计模式 | 模式 | 位置 | 目的 | |---------|-------|---------| | **AsyncGenerator 流式传输** | `QueryEngine`, `query()` | 从 API 到消费者的全链路流式传输 | | **构建器 + 工厂 (Builder + Factory)** | `buildTool()` | 为工具定义提供安全的默认值 | | **品牌类型 (Branded Types)** | `SystemPrompt`, `asSystemPrompt()` | 防止字符串/数组混淆 | | **功能开关 + DCE** | 来自 `bun:bundle` 的 `feature()` | 编译时死代码消除 | | **辨识联合 (Discriminated Unions)** | `Message` 类型 | 类型安全的消息处理 | | **观察者 + 状态机** | `StreamingToolExecutor` | 工具执行生命周期跟踪 | | **快照状态 (Snapshot State)** | `FileHistoryState` | 文件操作的撤销/重做 | | **环形缓冲区 (Ring Buffer)** | 错误日志 | 长会话的有限内存 | | **即发即弃写入 (Fire-and-Forget)** | `recordTranscript()` | 保持顺序的非阻塞持久化 | | **延迟 Schema (Lazy Schema)** | `lazySchema()` | 延迟 Zod schema 评估以提高性能 | | **上下文隔离 (Context Isolation)** | `AsyncLocalStorage` | 共享进程中每个代理的上下文 | --- ## 许可证 本仓库内容仅用于技术研究和教育目的。知识产权归原公司所有，若有侵权请联系删除。