mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
c5edee431f
* docs: 修复文档巡检发现的 4 处错误 - daemon.md: 反映实际实现状态（supervisor/worker 已实现而非 stub） - bridge-mode.md: API 操作数量从 7 修正为 9 - web-search-tool.md: 文件路径从 src/tools/ 修正为 packages/builtin-tools/src/tools/ - remote-control-self-hosting.md: 补充缺失的 RCS_WS_IDLE_TIMEOUT 和 RCS_WS_KEEPALIVE_INTERVAL 配置项 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 Safety 和 Context 文档中的代码引用和类型错误 - permission-model: 修正规则来源从"五层"到八层，优先级顺序对齐代码 - permission-model: PermissionUpdate 类型改为实际的 addRules/replaceRules 等 - permission-model: 补充 acceptEdits 和 dontAsk 两种权限模式 - permission-model: DENIAL_LIMITS 字段名对齐实际代码 - plan-mode: 工具路径从 src/tools/ 改为 packages/builtin-tools/src/tools/ - compaction: 修正 COMPACTABLE_TOOLS 和 POST_COMPACT_* 的行号 - project-memory: 修正 ENTRYPOINT_NAME 常量的行号 - system-prompt: 修正 SystemPrompt 类型定义文件路径和多个行号引用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修复 introduction 文档中的错误路径和行号引用 - why-this-whitepaper.mdx: BashTool 路径从 src/tools/ 修正为 packages/builtin-tools/src/tools/ - what-is-claude-code.mdx: 移除不存在的 Azure provider，改为实际的 7 种 provider - architecture-overview.mdx: State 类型行号从 204 修正为 207 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修复 conversation/features 文档中的错误 - streaming.mdx: queryStreamRaw → queryModelWithStreaming 函数名修正 - streaming.mdx: Azure 提供商不存在，替换为实际 7 个提供商 - debug-mode.mdx: --inspect-wait 描述错误，实际使用 BUN_INSPECT 环境变量 - buddy.mdx: 补充缺失的 companionReact.ts、CompanionCard.tsx、index.ts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修复文档巡检中的源码引用错误 - feature-flags.mdx: 修正 feature() 兜底描述，实际从 bun:bundle 导入而非 cli.tsx:3 内联 - feature-flags.mdx: 修正工具 require 路径为 @claude-code-best/builtin-tools 包路径 - ant-only-world.mdx: 修正 tools.ts 中 require 路径为包路径 - ant-only-world.mdx: 修正 INTERNAL_ONLY_COMMANDS 行号 (267-295) 和数量 (24+) - skills.mdx: 修正 COMMANDS memoize 行号 258 → 299 - mcp-protocol.mdx: 修正 fetchToolsForClient LRU 缓存上限 20 → 100 - streaming.mdx: 修正流式事件引用 - file-operations.mdx: 修正工具路径引用 - search-and-navigation.mdx: 修正搜索工具引用 - shell-execution.mdx: 修正 shell 工具引用 - buddy.mdx: 补充缺失的 frontmatter 字段 - debug-mode.mdx: 修正调试模式描述 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 tools/agent 文档中的文件路径和行号引用 - 修正 TodoWriteTool、AgentTool、ToolSearchTool 等工具路径 src/tools/ → packages/builtin-tools/src/tools/ - 更新 Tool.ts、tools.ts、BashTool.tsx 中过时的行号引用 - 修正 WebSearchTool/WebFetchTool/EnterWorktreeTool/ExitWorktreeTool 路径 - 修正 AgentTool.tsx 中多行行号引用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 feature 文档中的文件路径和行号引用 - ultraplan.md: 更新文件行数（525/349/127） - fork-subagent.md: 路径迁移 src/tools/ → packages/builtin-tools/ - mcp-skills.md: 修正 getMcpSkillCommands 行号 547→604，client.ts 行号 117→129 - kairos.md: 修正 getBriefSection/getProactiveSection 行号 - proactive.md: 修正 getProactiveSection 行号 860→864 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正顶层文档中的路径迁移和行号引用 - auto-updater.md: config.ts 行号 1735→1737，标注未接入启动流程的函数 - external-dependencies.md: WebSearchTool/WebFetchTool 路径迁移到 builtin-tools 包，Vertex 行号修正 - lsp-integration.md: LSPTool 路径从 src/tools/ 迁移到 packages/builtin-tools/ - stub-recovery-design-1-4.md: 修正 Windows 绝对路径链接为标准代码引用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 task 文档中的文件扩展名和路径引用 - task-004: AssistantSessionChooser.ts → .tsx, assistant.ts → .tsx - task-003: cli.tsx 行号 249→272, markdownConfigLoader.ts 行号 29→35 - lan-pipes: SendMessageTool 路径迁移到 packages/builtin-tools/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 补充 computer-use-tools-reference 缺失的 Windows 工具 添加遗漏的 open_terminal 和 activate_window 两个 Windows 专属工具， 修正工具总数 37→39，Windows 工具数 10→12。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 audit/bash-classifier/token-budget/tree-sitter 文档 - feature-flags-audit: ScheduleCronTool 路径迁移、DAEMON 状态更新为 COMPLETE、assistant 文件标记已补全、UDS 标记已实现 - bash-classifier: BashPermissionRequest 文件路径修正、withRetry 行号移除 - token-budget: attachments.ts 行号范围修正 - tree-sitter-bash: bashPermissions.ts 路径迁移到 packages/builtin-tools Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 langfuse-monitoring AgentTool 路径迁移 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 bridgeApi 行号和 Tool.ts 行号引用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 Safety/Extensibility 文档中的工具路径迁移和行号引用 - sandbox.mdx: shouldUseSandbox.ts 和 bashPermissions.ts 路径迁移至 packages/builtin-tools - why-safety-matters.mdx: bashPermissions.ts 路径迁移（3 处） - plan-mode.mdx: EnterPlanModeTool/prompt.ts 路径迁移 - auto-mode.mdx: Auto mode 指令行号 3464→3481 - hooks.mdx: AgentTool/runAgent.ts 路径迁移 - skills.mdx: SkillTool.ts 路径迁移 - custom-agents.mdx: Agent built-in 目录和 exploreAgent.ts 路径迁移 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 internals 文档引用计数和路径 - ant-only-world: USER_TYPE 引用计数 465→410+，工具路径迁移到 builtin-tools - growthbook-ab-testing: growthbook.ts 行数 1156→1258 - hidden-features: 语音模式状态更新（audio-napi 已恢复） Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正工具文档中的行号引用 - sub-agents: AgentTool.call 入口行号 340→387 - shell-execution: ShellCommand onTimeout 行号 129→144 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 feature 文档中的状态、路径和计数 - all-features-guide: 修正 feature flag 启用范围（dev only vs dev+build） - tier3-stubs: 大量状态修正（stub→已实现），缩减过时条目 - workflow-scripts: 路径迁移到 builtin-tools，状态更新 - web-browser-tool: 工具状态缺失→已实现，路径迁移 - context-collapse: CtxInspectTool 状态缺失→已实现 - computer-use: 行号引用更新，平台分发描述修正 - computer-use-tools-reference: 工具数 39→38 - voice-mode: voiceModeEnabled 行数 55→54 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 更新 the-loop 查询循环行号引用 query.ts 代码变更后终止原因行号整体偏移约 40 行 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 补充 feature-flags-audit 完整 build 默认 feature 列表 添加 ULTRATHINK/LODESTONE/ACP/DAEMON 等 19 个缺失的 build 默认 feature， 修正 dev-only 特征标注（UDS_INBOX/LAN_PIPES/BG_SESSIONS/TEMPLATES） Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 feature-flags-audit ConfigTool 路径迁移 ConfigTool 路径从 src/tools/ 迁移到 packages/builtin-tools/src/tools/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 feature-flags-audit BashTool 路径迁移 BashTool 路径从 src/tools/ 迁移到 packages/builtin-tools/src/tools/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 修正 feature-flags-audit SkillTool 路径迁移 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: 更新 feature-flags-audit WorkflowTool 状态为已实现 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
5.8 KiB
Plaintext
122 lines
5.8 KiB
Plaintext
---
|
||
title: "为什么写这份白皮书 - Claude Code 逆向工程分析"
|
||
description: "对 Anthropic 官方 Claude Code CLI 的逆向工程分析白皮书。通过反编译 TypeScript 单文件 bundle，深入解析运行时行为与源码结构。"
|
||
keywords: ["Claude Code", "逆向工程", "白皮书", "反编译", "TypeScript"]
|
||
---
|
||
|
||
## 这份白皮书是什么
|
||
|
||
这是对 Anthropic 官方发布的 **Claude Code CLI** 的**逆向工程分析**。
|
||
|
||
源码经过反编译处理（TypeScript 单文件 bundle 逆向），保留了核心功能模块，但包含大量 `unknown`/`never`/`{}` 类型错误——这些不影响 Bun 运行时执行，但意味着我们的分析基于运行时行为 + 残留源码结构，而非原始源码。
|
||
|
||
**这不是：**
|
||
- 官方文档或使用教程
|
||
- API 参考手册
|
||
- Claude Code 的功能推销
|
||
|
||
**这是：**
|
||
- 一个生产级 agentic system 的架构解构
|
||
- 每个设计决策背后的"为什么"
|
||
- 可复用的工程模式：agentic loop、工具抽象、上下文工程、安全纵深防御
|
||
|
||
## 逆向过程中最精妙的设计决策
|
||
|
||
### 1. Agentic Loop 的自愈能力
|
||
|
||
`src/query.ts` 实现的核心循环不是简单的"发请求→收响应"。它是一个**自愈的状态机**：
|
||
|
||
- API 返回错误（限流、token 超限）→ 自动重试/降级
|
||
- 工具执行超时 → 后台化 + 通知机制
|
||
- 对话过长触发 compaction → 压缩历史后无缝继续
|
||
- 用户中断 → 生成 `UserInterruptionMessage` 让 AI 理解发生了什么
|
||
|
||
这不是"if-else 堆叠"，而是让 AI 自己根据上下文决定下一步——即使发生了意外。
|
||
|
||
### 2. 上下文工程的分层策略
|
||
|
||
AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉：
|
||
|
||
| 层 | 机制 | 持久性 |
|
||
|----|------|--------|
|
||
| **System Prompt** | 项目结构、git 状态、CLAUDE.md | 每轮重建 |
|
||
| **对话历史** | 完整的 User/Assistant/Tool 消息 | 会话内 |
|
||
| **Compaction** | 自动压缩过长对话为摘要 | 压缩后替代原始消息 |
|
||
| **Memory 文件** | 跨会话持久化的笔记 | 永久（用户可控） |
|
||
| **File History** | 文件修改时间戳快照 | 会话内 |
|
||
|
||
`src/context.ts` 组装 System Prompt 时的策略是：**不变内容在前、变化内容在后**——这利用了 API 的缓存机制，前缀不变时可以复用缓存 token。
|
||
|
||
### 3. 工具系统的权限双轨制
|
||
|
||
`packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：
|
||
|
||
- **应用层**：权限规则决定"能不能执行"（白名单/黑名单/用户确认）
|
||
- **OS 层**：沙箱决定"执行时能做什么"（文件系统/网络/进程隔离）
|
||
|
||
两层的信任假设不同：应用层信任用户配置，OS 层不信任任何东西。即使 AI 绕过了应用层权限（理论上不可能，但纵深防御），OS 层沙箱仍然限制实际危害。
|
||
|
||
### 4. Feature Flag 的全局开关
|
||
|
||
`src/entrypoints/cli.tsx` 中一行代码决定了整个系统的行为：
|
||
|
||
```typescript
|
||
const feature = (_name: string) => false;
|
||
```
|
||
|
||
所有 `feature('FLAG_NAME')` 调用返回 `false`——这意味着 Anthropic 内部的实验功能（COORDINATOR_MODE、KAIROS、PROACTIVE 等）全部禁用。在官方构建中，这些 flag 通过 Bun 的 `bun:bundle` 在编译时注入，不同用户群体看到不同功能。
|
||
|
||
这是一个**渐进式发布架构**：同一个代码库，通过 feature flag 控制功能可见性，而不需要维护多个分支。
|
||
|
||
### 5. Compaction 的分档策略
|
||
|
||
`src/services/compact/` 实现了三种压缩策略：
|
||
|
||
- **Micro-compact**：单次工具输出过长时，截断结果
|
||
- **Auto-compact**：对话 token 接近上限时，自动压缩历史
|
||
- **Reactive-compact**：API 返回 token 超限错误时，紧急压缩后重试
|
||
|
||
这不是简单的"砍掉旧消息"——而是用 AI 自身来总结之前的对话，保留语义信息。压缩后插入一条 `TombstoneMessage` 标记边界。
|
||
|
||
## 阅读路线图
|
||
|
||
推荐的阅读顺序，每章解决一个核心问题：
|
||
|
||
```
|
||
什么是 Claude Code (你在读的) ← 建立直觉
|
||
│
|
||
├── 架构全景 ← 五层架构 + 数据流
|
||
│
|
||
├── 安全体系 ← 信任与控制
|
||
│ ├── 权限模型 ← 应用层安全
|
||
│ ├── 沙箱机制 ← OS 层安全
|
||
│ └── Plan Mode ← 用户主导模式
|
||
│
|
||
├── 对话引擎 ← AI 如何思考
|
||
│ ├── Agentic Loop ← 核心循环
|
||
│ ├── 流式响应 ← 实时通信
|
||
│ └── 多轮对话 ← 上下文管理
|
||
│
|
||
├── 上下文工程 ← 记忆与预算
|
||
│ ├── System Prompt ← 上下文组装
|
||
│ ├── Token 预算 ← 预算管理
|
||
│ └── 项目记忆 ← 跨会话持久化
|
||
│
|
||
├── 工具系统 ← AI 的双手
|
||
│ ├── 工具概览 ← 统一接口
|
||
│ ├── Shell 执行 ← Bash 工具
|
||
│ └── 搜索与导航 ← Glob/Grep
|
||
│
|
||
└── Agent 与扩展 ← 能力扩展
|
||
├── 子 Agent ← 并行任务
|
||
├── 自定义 Agent ← 用户定义
|
||
└── MCP 协议 ← 外部工具接入
|
||
```
|
||
|
||
## 适合谁读
|
||
|
||
- **AI Agent 开发者**：想理解生产级 agentic system 的架构模式
|
||
- **安全工程师**：对 AI 操作真实环境时的信任模型感兴趣
|
||
- **工具构建者**：正在构建类似的 coding assistant 或 CLI 工具
|
||
- **好奇心驱动的开发者**：想知道"AI 编程助手到底怎么工作的"
|