mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 06:15:51 +00:00
claude-code with OpenAI mode fix
This commit is contained in:
HitMargin
112
docs/introduction/architecture-overview.mdx
Normal file
112
docs/introduction/architecture-overview.mdx
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: "架构全景 - Claude Code 五层架构详解"
|
||||
description: "从交互层到基础设施层，详解 Claude Code 的五层架构设计。基于 src/main.tsx、src/QueryEngine.ts、src/query.ts、src/tools.ts、src/services/api/claude.ts 的源码级数据流分析。"
|
||||
keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop", "数据流"]
|
||||
---
|
||||
|
||||
{/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
|
||||
|
||||
## 五层架构
|
||||
|
||||
Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
|
||||
|
||||
<Frame caption="Claude Code 五层架构">
|
||||
<img src="/docs/images/architecture-layers.png" alt="Claude Code 五层架构图" />
|
||||
</Frame>
|
||||
|
||||
| 层次 | 职责 | 入口源码 | 关键词 |
|
||||
|------|------|---------|--------|
|
||||
| **交互层** | 终端 UI、用户输入、消息展示 | `src/screens/REPL.tsx` | React/Ink、PromptInput |
|
||||
| **编排层** | 多轮对话、会话持久化、成本追踪 | `src/QueryEngine.ts` | QueryEngine、transcript |
|
||||
| **核心循环层** | 单轮：发请求 → 拿响应 → 执行工具 → 循环 | `src/query.ts` | Agentic Loop、State |
|
||||
| **工具层** | AI 的"双手"——读写文件、执行命令 | `src/tools.ts` → `src/Tool.ts` | Tool 接口、MCP |
|
||||
| **通信层** | 与 Claude API 的流式通信 | `src/services/api/claude.ts` | Streaming、Provider |
|
||||
|
||||
## 一条主数据流的源码追踪
|
||||
|
||||
<Frame caption="核心数据流">
|
||||
<img src="/docs/images/data-flow.png" alt="Claude Code 核心数据流" />
|
||||
</Frame>
|
||||
|
||||
整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：
|
||||
|
||||
### 1. 用户输入 → REPL
|
||||
|
||||
`src/screens/REPL.tsx` 是基于 React/Ink 的终端 UI 组件。用户输入经 `processUserInput()`（`src/utils/processUserInput/processUserInput.ts`）处理，支持斜杠命令、文件附件、图片等。
|
||||
|
||||
### 2. QueryEngine 编排
|
||||
|
||||
`src/QueryEngine.ts` 是 REPL 与 `query()` 之间的中间层，管理：
|
||||
- **会话状态**：消息数组、工具权限上下文（`ToolPermissionContext`）、文件历史快照
|
||||
- **成本追踪**：`accumulateUsage()` / `getTotalCost()` 累计 token 用量
|
||||
- **Transcript 持久化**：`recordTranscript()` 将对话序列化到磁盘，支持 `--resume`
|
||||
- **文件历史**：`fileHistoryMakeSnapshot()` 在修改前创建快照，支持 undo
|
||||
|
||||
关键方法：`queryEngine.query()` 构造 `QueryParams`，调用 `query()` 异步生成器。
|
||||
|
||||
### 3. Agentic Loop（`src/query.ts`）
|
||||
|
||||
`query()` 是一个 `AsyncGenerator`，`while(true)` 循环的每次迭代包含：
|
||||
|
||||
```
|
||||
① 上下文预处理管道：
|
||||
applyToolResultBudget → snipCompact → microcompact → contextCollapse → autocompact
|
||||
|
||||
② 流式 API 调用：
|
||||
deps.callModel() → AsyncGenerator<StreamEvent | Message>
|
||||
收集 assistantMessages[]、toolUseBlocks[]
|
||||
|
||||
③ 工具执行：
|
||||
StreamingToolExecutor（并行） 或 runTools（串行）
|
||||
→ toolResults[]
|
||||
|
||||
④ 终止/继续判定：
|
||||
needsFollowUp ? continue : return { reason }
|
||||
```
|
||||
|
||||
完整的状态机通过 `State` 类型（`src/query.ts:204`）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。
|
||||
|
||||
### 4. 工具层（`src/tools.ts` → `src/Tool.ts`）
|
||||
|
||||
`getAllBaseTools()`（`src/tools.ts:191`）组装 50+ 工具列表，经过 `filterToolsByDenyRules()` 权限过滤后传给 API。
|
||||
|
||||
每个工具实现 `Tool<Input, Output, Progress>` 接口（`src/Tool.ts:362`），核心方法链：
|
||||
```
|
||||
validateInput() → canUseTool()（UI 层）→ checkPermissions() → call() → ToolResult
|
||||
```
|
||||
|
||||
### 5. 通信层（`src/services/api/claude.ts`）
|
||||
|
||||
API 客户端支持 4 种 Provider：
|
||||
- **Anthropic Direct**：默认
|
||||
- **AWS Bedrock**：`ANTHROPIC_BEDROCK_BASE_URL`
|
||||
- **Google Vertex**：`ANTHROPIC_VERTEX_PROJECT_ID`
|
||||
- **Azure**：通过自定义 base URL
|
||||
|
||||
`deps.callModel()` 发起流式请求，返回 `BetaRawMessageStreamEvent` 事件流。支持 Prompt Cache（`cache_control`）、thinking blocks、multi-turn tool use。
|
||||
|
||||
## 四个核心设计原则
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="流式优先 (Streaming-first)">
|
||||
所有 API 通信都是流式的——`deps.callModel()` 返回 AsyncGenerator，用户看到 AI "逐字打出"回答。StreamingToolExecutor 在流式过程中就开始并行执行工具，不等流结束。模型降级（Fallback）时，已收集的 assistantMessages 被标记为 tombstone 并清空，重试整个流式请求。
|
||||
</Accordion>
|
||||
<Accordion title="工具即能力 (Tool as Capability)">
|
||||
每个工具是 `Tool<Input, Output, Progress>` 结构化类型，通过 `buildTool()` 工厂创建。`getTools()` 在每次 API 调用时组装（非全局缓存），因为 `isEnabled()` 可能随运行时状态变化。MCP 工具通过 `mcpInfo` 字段标记来源，支持 server 级别的 blanket deny。
|
||||
</Accordion>
|
||||
<Accordion title="权限即边界 (Permission as Boundary)">
|
||||
每次工具调用经过 `validateInput() → checkPermissions()` 双重检查。权限规则从 5 个来源汇聚（session → project → user → managed → default），支持工具名、命令模式、路径前缀等匹配方式。Plan Mode 通过 `prepareContextForPlanMode()` 切换为只读模式，退出时自动恢复。
|
||||
</Accordion>
|
||||
<Accordion title="上下文即记忆 (Context as Memory)">
|
||||
System Prompt 由 `fetchSystemPromptParts()` 动态组装，包含 CLAUDE.md、git 状态、日期、MCP 服务器列表。Auto-compact 在每轮迭代前评估 token 阈值，超出时触发压缩。压缩后的摘要通过 `buildPostCompactMessages()` 替换原始消息，`taskBudgetRemaining` 跨压缩边界累计。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 入口与引导
|
||||
|
||||
| 入口 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| CLI 启动 | `src/entrypoints/cli.tsx` | 注入 `feature()` polyfill（始终返回 false）、MACRO 全局变量 |
|
||||
| 命令定义 | `src/main.tsx` | Commander.js 解析参数，初始化 auth/analytics/policy |
|
||||
| 一次性初始化 | `src/entrypoints/init.ts` | 遥测配置、信任对话框 |
|
||||
| 管道模式 | `src/main.tsx` `-p` flag | `echo "say hello" \| bun run dev -p` |
|
||||
111
docs/introduction/what-is-claude-code.mdx
Normal file
111
docs/introduction/what-is-claude-code.mdx
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: "什么是 Claude Code - Terminal Native Agentic Coding System"
|
||||
description: "Claude Code 是运行在终端中的 agentic coding system，直接在你的项目目录中读代码、改文件、跑命令、调试程序。了解它的技术定位、架构差异和核心能力。"
|
||||
keywords: ["Claude Code", "AI 编程助手", "Agentic Coding", "终端 AI", "CLI AI"]
|
||||
og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
|
||||
---
|
||||
|
||||
## 一句话定义
|
||||
|
||||
Claude Code 是一个**运行在本地终端中的 agentic coding system**。它不是给建议的聊天机器人——它直接在你的项目目录中读代码、改文件、跑命令、调试程序，拥有完整的 shell 能力。
|
||||
|
||||
## 技术定位：terminal-native agentic system
|
||||
|
||||
理解 Claude Code 的关键在于三个词：
|
||||
|
||||
| 定位关键词 | 含义 |
|
||||
|-----------|------|
|
||||
| **Terminal-native** | 原生 CLI 应用，不是 IDE 插件、不是 Web 界面、不是 API wrapper |
|
||||
| **Agentic** | AI 自主决策工具调用链，不是"一问一答"的聊天模式 |
|
||||
| **Coding system** | 面向软件工程全流程，不是通用问答工具 |
|
||||
|
||||
与同类工具的**架构层面**差异（不是功能清单）：
|
||||
|
||||
| 工具 | 架构模式 | 运行位置 | 工具执行 |
|
||||
|------|----------|----------|----------|
|
||||
| **Claude Code** | Terminal-native agentic loop | 本地进程 | 直接 shell 执行 |
|
||||
| Cursor / Copilot | IDE-integrated autocomplete + chat | IDE 进程内 | LSP / IDE API |
|
||||
| Aider | CLI chat → git patch | 本地进程 | 文件操作为主 |
|
||||
| ChatGPT / Claude.ai | Cloud chat + artifacts | 浏览器/云端 | 沙箱容器 |
|
||||
|
||||
核心差异：Claude Code 拥有**完整的 shell 访问权**——这意味着它可以做任何你在终端里能做的事，但也需要对应的安全机制来约束这个能力。
|
||||
|
||||
## 端到端示例：从输入到输出
|
||||
|
||||
当你在终端中输入 `bun run dev 有个 TypeScript 报错，帮我修一下` 时，系统发生了什么？
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 1. 入口层 (cli.tsx → main.tsx) │
|
||||
│ feature() = false, MACRO 注入, 启动 Commander.js CLI │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 2. 交互层 (REPL.tsx — React/Ink) │
|
||||
│ PromptInput 捕获用户输入 → UserMessage 加入会话 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 3. 编排层 (QueryEngine.ts) │
|
||||
│ 管理 turn 生命周期、token 预算、compaction 触发 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 4. 核心循环 (query.ts — Agentic Loop) │
|
||||
│ 组装上下文 → 调 API → 收流式响应 → 解析工具调用 │
|
||||
│ → 权限检查 → 执行工具 → 结果回传 → 再次调 API → 循环 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 5. 工具执行 (BashTool.call / FileEditTool.call / ...) │
|
||||
│ 实际执行: 读文件、运行命令、搜索代码... │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 6. 通信层 (claude.ts → Anthropic API) │
|
||||
│ 流式 HTTP, 支持 Bedrock/Vertex/Azure 多 provider │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
具体到这个报错修复场景，一次典型的 agentic loop 可能包含多轮工具调用：
|
||||
|
||||
| Turn | AI 决策 | 工具调用 | 结果 |
|
||||
|------|---------|----------|------|
|
||||
| 1 | 先看报错信息 | `Bash("bun run dev 2>&1 | head -30")` | TypeScript 错误输出 |
|
||||
| 2 | 定位到文件 | `Read("src/utils/foo.ts")` | 源代码内容 |
|
||||
| 3 | 搜索相关类型定义 | `Grep("interface Foo", "src/")` | 类型定义位置 |
|
||||
| 4 | 修复代码 | `FileEdit(old, new)` | 代码已修改 |
|
||||
| 5 | 验证修复 | `Bash("bun run dev 2>&1 | head -10")` | 编译通过 |
|
||||
|
||||
每一步都是 AI 自主决策的——它决定用哪个工具、传什么参数、何时停止。这就是 "agentic" 的含义。
|
||||
|
||||
## 它不是什么
|
||||
|
||||
- **不是 IDE 插件**：没有图形界面，不依赖 VS Code 或任何 IDE
|
||||
- **不是 API wrapper**：它有自己的工具系统、权限模型、上下文工程、会话管理
|
||||
- **不是聊天机器人**：输出不是纯文本，而是实际的文件修改、命令执行
|
||||
- **不是无脑执行器**：每个敏感操作都有权限检查和用户确认环节
|
||||
|
||||
## 启动入口解剖
|
||||
|
||||
真正的代码入口是 `src/entrypoints/cli.tsx`，它做了三件关键的事：
|
||||
|
||||
```typescript
|
||||
// 1. 注入运行时 polyfill —— feature() 永远返回 false
|
||||
const feature = (_name: string) => false;
|
||||
|
||||
// 2. 注入构建时宏
|
||||
globalThis.MACRO = { VERSION: "2.1.888", BUILD_TIME: ..., };
|
||||
|
||||
// 3. 声明构建目标
|
||||
globalThis.BUILD_TARGET = "external"; // 外部构建（非 Anthropic 内部）
|
||||
globalThis.BUILD_ENV = "production";
|
||||
globalThis.INTERFACE_TYPE = "stdio"; // 标准 I/O 交互
|
||||
```
|
||||
|
||||
然后控制流传递到 `src/main.tsx`：
|
||||
1. Commander.js 解析命令行参数
|
||||
2. 初始化认证、遥测、策略限制
|
||||
3. 加载工具列表（`getTools()`）
|
||||
4. 启动 REPL（`launchRepl()`）或管道模式（`-p`）
|
||||
|
||||
## 为什么选择终端
|
||||
|
||||
终端不是限制，而是选择。它带来了独特的能力：
|
||||
|
||||
- **完整的 shell 访问**：可以运行任何命令行工具，无需为每个能力写插件
|
||||
- **项目原生**：直接在项目目录工作，理解文件系统结构、git 状态
|
||||
- **可组合性**：管道模式（`echo "..." | claude -p`）允许嵌入 CI/CD 和自动化流程
|
||||
- **低延迟**：没有 Electron 开销，React/Ink 渲染的 TUI 响应极快
|
||||
|
||||
代价是用户需要适应命令行界面——但也正因如此，它吸引的是需要**真正掌控开发环境**的开发者。
|
||||
121
docs/introduction/why-this-whitepaper.mdx
Normal file
121
docs/introduction/why-this-whitepaper.mdx
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
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. 工具系统的权限双轨制
|
||||
|
||||
`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 编程助手到底怎么工作的"
|
||||
Reference in New Issue
Block a user