mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 22:05:50 +00:00
claude-code with OpenAI mode fix
This commit is contained in:
HitMargin
128
docs/REVISION-PLAN.md
Normal file
128
docs/REVISION-PLAN.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 文档修正计划
|
||||
|
||||
> 目标：补充源码级洞察，让每篇文档从"概念科普"升级为"逆向工程白皮书"水准。
|
||||
|
||||
---
|
||||
|
||||
## 第一梯队：空壳页，需要大幅重写
|
||||
|
||||
### 1. `safety/sandbox.mdx` — 沙箱机制 ✅ DONE
|
||||
|
||||
**现状**：35 行，只列了"文件系统/网络/进程/时间"四个维度，没有任何实现细节。
|
||||
|
||||
**修正方向**：
|
||||
- 补充 macOS `sandbox-exec` 的实际调用方式，展示沙箱 profile 的关键片段
|
||||
- 说明 `getSandboxConfig()` 的判定逻辑：哪些命令走沙箱、哪些跳过
|
||||
- 补充 `dangerouslyDisableSandbox` 参数的设计权衡
|
||||
- 加入 Linux 平台的沙箱差异对比（seatbelt vs namespace）
|
||||
- 展示一次命令执行从权限检查→沙箱包裹→实际执行的完整链路
|
||||
|
||||
---
|
||||
|
||||
### 2. `introduction/what-is-claude-code.mdx` — 什么是 Claude Code ✅ DONE
|
||||
|
||||
**现状**：39 行，纯营销文案，和"普通聊天 AI"的对比表太低级。
|
||||
|
||||
**修正方向**：
|
||||
- 砍掉"能做什么"的泛泛列表，改为一个具体的端到端示例（从用户输入→系统处理→最终输出）
|
||||
- 用一张简化架构图替代文字描述，让读者 30 秒建立直觉
|
||||
- 补充 Claude Code 的技术定位：不是 IDE 插件、不是 Web Chat，而是 terminal-native agentic system
|
||||
- 加入与 Cursor / Copilot / Aider 等工具的定位差异（架构层面而非功能清单）
|
||||
|
||||
---
|
||||
|
||||
### 3. `introduction/why-this-whitepaper.mdx` — 为什么写这份白皮书 ✅ DONE
|
||||
|
||||
**现状**：40 行，全是空话，四张 Card 只是后续章节标题的预告。
|
||||
|
||||
**修正方向**：
|
||||
- 明确定位：这是对 Anthropic 官方 CLI 的逆向工程分析，不是官方文档
|
||||
- 列出逆向过程中发现的 3-5 个最意外/最精妙的设计决策（吊住读者胃口）
|
||||
- 说明白皮书的阅读路线图：推荐的阅读顺序和每个章节解决什么问题
|
||||
- 补充"这份白皮书不是什么"——不是使用教程，不是 API 文档
|
||||
|
||||
---
|
||||
|
||||
### 4. `safety/why-safety-matters.mdx` — 为什么安全至关重要 ✅ DONE
|
||||
|
||||
**现状**：40 行，只列了显而易见的风险，"安全 vs 效率的平衡"只有 3 个 bullet。
|
||||
|
||||
**修正方向**：
|
||||
- 从源码角度展示安全体系的全景图：权限规则 → 沙箱 → Plan Mode → 预算上限 → Hooks 的纵深防御链
|
||||
- 补充 Claude 自身 System Prompt 中的安全指令（"执行前确认"、"优先可逆操作"等），展示 AI 端的安全约束
|
||||
- 用真实场景说明"安全 vs 效率"的工程权衡：比如 Read 工具为什么免审批、Bash 工具为什么要逐条确认
|
||||
- 加入 Prompt Injection 防御的简要说明（tool result 中的恶意内容如何被系统标记）
|
||||
|
||||
---
|
||||
|
||||
## 第二梯队：有骨架但太浅，需要补肉
|
||||
|
||||
### 5. `conversation/streaming.mdx` — 流式响应 ✅ DONE
|
||||
|
||||
**现状**：43 行，只说了"流式好"和 3 行 provider 表。
|
||||
|
||||
**修正方向**：
|
||||
- 补充 `BetaRawMessageStreamEvent` 的核心事件类型及其含义
|
||||
- 展示文本 chunk 和 tool_use block 交织的状态机流转
|
||||
- 说明流式中的错误处理：网络断开、API 限流、token 超限时的重试/降级策略
|
||||
- 补充 `processStreamEvents()` 的核心逻辑：如何从事件流中分离出文本、工具调用、usage 统计
|
||||
|
||||
---
|
||||
|
||||
### 6. `tools/search-and-navigation.mdx` — 搜索与导航 ✅ DONE
|
||||
|
||||
**现状**：43 行，只说 Glob 和 Grep 存在。
|
||||
|
||||
**修正方向**：
|
||||
- 补充 ripgrep 二进制的内嵌方式（vendor 目录、平台适配）
|
||||
- 说明搜索结果的 head_limit 默认 250 的设计原因（token 预算）
|
||||
- 展示 ToolSearch 的实现：如何用语义匹配在 50+ 工具（含 MCP）中找到最相关的
|
||||
- 补充 Glob 按修改时间排序的意义：最近修改的文件最可能与当前任务相关
|
||||
|
||||
---
|
||||
|
||||
### 7. `tools/task-management.mdx` — 任务管理 ✅ DONE
|
||||
|
||||
**现状**：50 行，只有流程 Steps 和状态展示的 4 个 bullet。
|
||||
|
||||
**修正方向**：
|
||||
- 补充任务的数据模型：id / subject / description / status / blockedBy / blocks / owner
|
||||
- 说明依赖管理的实现：blockedBy 如何阻止任务被认领、完成一个任务后如何自动解锁下游
|
||||
- 展示任务与 Agent 工具的联动：子 Agent 如何认领任务、报告进度
|
||||
- 补充 activeForm 字段的 UX 设计：进行中任务的 spinner 动画文案
|
||||
|
||||
---
|
||||
|
||||
### 8. `context/token-budget.mdx` — Token 预算管理 ✅ DONE
|
||||
|
||||
**现状**：55 行，预算控制只有 3 张 Card 各一句话。
|
||||
|
||||
**修正方向**：
|
||||
- 补充 `contextWindowTokens` 和 `maxOutputTokens` 的动态计算逻辑
|
||||
- 说明缓存 breakpoint 的放置策略：System Prompt 中不变内容在前、变化内容在后的原因
|
||||
- 展示工具输出截断的具体机制：超长结果如何被 truncate、何时触发 micro-compact
|
||||
- 补充 token 计数的实现：`countTokens` 的调用时机和近似 vs 精确计数的权衡
|
||||
|
||||
---
|
||||
|
||||
### 9. `agent/worktree-isolation.mdx` — Worktree 隔离 ✅ DONE
|
||||
|
||||
**现状**：55 行，只描述了 git worktree 的概念。
|
||||
|
||||
**修正方向**：
|
||||
- 展示 `.claude/worktrees/` 的目录结构和分支命名规则
|
||||
- 说明 worktree 的生命周期：创建时机（`isolation: "worktree"`）→ 子 Agent 执行 → 完成/放弃 → 自动清理
|
||||
- 补充 worktree 与子 Agent 的绑定关系：Agent 结束时如何判断 keep or remove
|
||||
- 加入 EnterWorktree / ExitWorktree 工具的交互设计
|
||||
|
||||
---
|
||||
|
||||
### 10. `extensibility/custom-agents.mdx` — 自定义 Agent ✅ DONE
|
||||
|
||||
**现状**：56 行，只有配置表和示例表。
|
||||
|
||||
**修正方向**：
|
||||
- 展示 agent markdown 文件的完整 frontmatter 格式（name / description / model / allowedTools 等）
|
||||
- 说明 agent 如何被加载和注入 System Prompt：`loadAgentDefinitions()` 的发现和合并逻辑
|
||||
- 展示工具限制的实现：allowedTools 如何过滤工具列表
|
||||
- 补充 agent 与 subagent_type 参数的关联：Agent 工具如何指定使用自定义 Agent
|
||||
196
docs/agent/coordinator-and-swarm.mdx
Normal file
196
docs/agent/coordinator-and-swarm.mdx
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: "协调者与蜂群模式 - 多 Agent 高级编排"
|
||||
description: "从源码角度解析 Claude Code 多 Agent 协作：Coordinator Mode 的 System Prompt 设计、Worker 生命周期、Task 通信协议和 Swarm 蜂群的任务分配机制。"
|
||||
keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作", "任务编排"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 Coordinator Mode 和 Agent Swarms 的架构设计 */}
|
||||
|
||||
## 两种协作模式的架构差异
|
||||
|
||||
| 维度 | Coordinator Mode | Agent Swarms |
|
||||
|------|-----------------|--------------|
|
||||
| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | 任务系统 V2（默认启用） |
|
||||
| **拓扑** | 星型：Coordinator 居中，Worker 外围 | 网状：对等 Agent 共享任务列表 |
|
||||
| **角色** | 明确分工：Coordinator 编排、Worker 执行 | 模糊：每个 Agent 自主认领任务 |
|
||||
| **通信** | `SendMessage` 定向通信 + `<task-notification>` | 任务文件系统 + 邮箱广播 |
|
||||
| **适用** | 需要集中决策的复杂任务 | 并行度高的独立子任务 |
|
||||
|
||||
两者不是互斥的——Coordinator Mode 可以在 Swarm 架构之上运行，将 Coordinator 作为特殊的 Leader Agent。
|
||||
|
||||
## Coordinator Mode：星型编排架构
|
||||
|
||||
### 激活机制
|
||||
|
||||
```typescript
|
||||
// src/coordinator/coordinatorMode.ts:36
|
||||
export function isCoordinatorMode(): boolean {
|
||||
if (feature('COORDINATOR_MODE')) {
|
||||
return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
|
||||
}
|
||||
return false // 外部构建始终 false
|
||||
}
|
||||
```
|
||||
|
||||
Coordinator Mode 需要双重门控：构建时 `feature('COORDINATOR_MODE')` 和运行时环境变量。`matchSessionMode()` 在会话恢复时自动同步模式状态——如果恢复的会话是 coordinator 模式，它会翻转环境变量以确保一致性。
|
||||
|
||||
### Coordinator 的工具集
|
||||
|
||||
Coordinator 被剥夺了所有"动手"工具，只保留编排能力：
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| **Agent** | 启动新 Worker（`subagent_type: "worker"`） |
|
||||
| **SendMessage** | 向已有 Worker 发送后续指令 |
|
||||
| **TaskStop** | 中途停止走错方向的 Worker |
|
||||
| **subscribe_pr_activity** | 订阅 GitHub PR 事件（review comments、CI 结果） |
|
||||
|
||||
Coordinator **不写代码、不读文件、不执行命令**——它只做三件事：理解需求、分配任务、综合结果。
|
||||
|
||||
### Worker 的工具权限
|
||||
|
||||
Worker 的可用工具由 `getCoordinatorUserContext()`（`coordinatorMode.ts:80`）动态注入到 System Prompt：
|
||||
|
||||
```typescript
|
||||
// 简化模式下：只有 Bash + Read + Edit
|
||||
const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE')
|
||||
? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]
|
||||
: Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
|
||||
.filter(name => !INTERNAL_WORKER_TOOLS.has(name))
|
||||
```
|
||||
|
||||
`INTERNAL_WORKER_TOOLS`（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）被显式排除——Worker 不能嵌套创建团队或发送消息，防止不可控的递归。
|
||||
|
||||
### Scratchpad：跨 Worker 的共享知识库
|
||||
|
||||
当 `tengu_scratch` feature flag 启用时，Coordinator 拥有一个 Scratchpad 目录：
|
||||
|
||||
```
|
||||
Scratchpad 目录：
|
||||
- Workers 可自由读写，无需权限审批
|
||||
- 用于持久化的跨 Worker 知识
|
||||
- 结构由 Coordinator 决定（无固定格式）
|
||||
```
|
||||
|
||||
这是一个关键的协作原语——Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
|
||||
|
||||
### `<task-notification>` 通信协议
|
||||
|
||||
Worker 完成后，Coordinator 收到 XML 格式的通知：
|
||||
|
||||
```xml
|
||||
<task-notification>
|
||||
<task-id>agent-a1b</task-id> ← Worker 的 agentId
|
||||
<status>completed|failed|killed</status>
|
||||
<summary>Agent "Investigate auth bug" completed</summary>
|
||||
<result>Found null pointer in src/auth/validate.ts:42...</result>
|
||||
<usage>
|
||||
<total_tokens>N</total_tokens>
|
||||
<tool_uses>N</tool_uses>
|
||||
<duration_ms>N</duration_ms>
|
||||
</usage>
|
||||
</task-notification>
|
||||
```
|
||||
|
||||
通知以 `user-role message` 形式送达，Coordinator 通过 `<task-notification>` 标签区分它和用户消息。`<task-id>` 用于 `SendMessage` 的 `to` 参数，实现定向续传。
|
||||
|
||||
### Coordinator 的核心职责：综合（Synthesis）
|
||||
|
||||
Coordinator System Prompt（`coordinatorMode.ts:111-369`，约 260 行）明确要求 Coordinator **不能懒惰地委派理解**：
|
||||
|
||||
```
|
||||
反模式（禁止）：
|
||||
"Based on your findings, fix the auth bug"
|
||||
→ 把理解的责任推给了 Worker
|
||||
|
||||
正确做法：
|
||||
"Fix the null pointer in src/auth/validate.ts:42.
|
||||
The user field on Session (src/auth/types.ts:15) is
|
||||
undefined when sessions expire but the token remains cached.
|
||||
Add a null check before user.id access."
|
||||
→ Coordinator 自己理解了问题，给出精确指令
|
||||
```
|
||||
|
||||
这是 Coordinator Mode 最核心的设计约束：Coordinator 必须先理解，再分配。
|
||||
|
||||
## Agent Swarms：蜂群式协作
|
||||
|
||||
Swarm 模式基于任务系统 V2（详见[任务管理](../tools/task-management.mdx)），核心机制是**共享任务列表 + 竞争认领**：
|
||||
|
||||
### 团队初始化
|
||||
|
||||
```
|
||||
Leader 创建团队（TeamCreateTool）
|
||||
↓
|
||||
设置 teamName → setLeaderTeamName()
|
||||
↓
|
||||
所有 teammate 自动获得相同的 taskListId
|
||||
↓
|
||||
teammate 启动时：
|
||||
1. CLAUDE_CODE_TASK_LIST_ID 环境变量（显式覆盖）
|
||||
2. teammate 上下文的 teamName（共享 leader 的任务列表）
|
||||
3. CLAUDE_CODE_TEAM_NAME 环境变量
|
||||
4. leader 设置的 teamName
|
||||
5. getSessionId()（兜底）
|
||||
```
|
||||
|
||||
多级优先级确保了 Leader 和所有 Teammate 指向同一个任务列表，无需额外协调。
|
||||
|
||||
### 任务认领与竞争
|
||||
|
||||
`claimTask()` 是 Swarm 的核心并发原语：
|
||||
|
||||
```
|
||||
Teammate A 调用 TaskList → 发现 task #3 是 pending
|
||||
Teammate B 同时发现 task #3 是 pending
|
||||
↓
|
||||
两者同时尝试 TaskUpdate(task #3, {status: "in_progress"})
|
||||
↓
|
||||
文件锁 + 高水位标记保证原子性：
|
||||
- 第一个写入者获得 owner 锁定
|
||||
- 第二个写入者收到 already_claimed 错误
|
||||
↓
|
||||
获得任务的 teammate 执行工作
|
||||
↓
|
||||
完成后 TaskUpdate(task #3, {status: "completed"})
|
||||
→ 依赖此任务的其他任务自动解锁
|
||||
→ tool_result 提示 "Call TaskList to find your next task"
|
||||
```
|
||||
|
||||
### Teammate 的生命周期管理
|
||||
|
||||
```
|
||||
Teammate 异常退出
|
||||
↓
|
||||
unassignTeammateTasks()
|
||||
→ 扫描任务列表，找到 owner === teammateName 的未完成任务
|
||||
→ 重置为 pending + owner=undefined
|
||||
↓
|
||||
Leader 通过 mailbox 收到通知
|
||||
→ 重新分配或创建新 Teammate
|
||||
```
|
||||
|
||||
## 任务类型全景
|
||||
|
||||
支撑多 Agent 协作的是 7 种任务类型（`src/tasks/types.ts`）：
|
||||
|
||||
| 任务类型 | 运行位置 | 状态管理 | 适用场景 |
|
||||
|----------|---------|---------|---------|
|
||||
| **LocalAgentTask** | 本地子进程 | `LocalAgentTaskState` | 标准子 Agent 任务 |
|
||||
| **LocalShellTask** | 本地 shell | `LocalShellTaskState` | 后台 shell 命令 |
|
||||
| **InProcessTeammateTask** | 同进程内 | `InProcessTeammateTaskState` | 轻量级进程内队友 |
|
||||
| **RemoteAgentTask** | 远程服务器 | `RemoteAgentTaskState` | 分布式 Agent（CCR） |
|
||||
| **DreamTask** | 后台静默 | `DreamTaskState` | 后台自主整理记忆 |
|
||||
| **LocalWorkflowTask** | 本地 | `LocalWorkflowTaskState` | 工作流编排 |
|
||||
| **MonitorMcpTask** | 本地 | `MonitorMcpTaskState` | MCP 监控任务 |
|
||||
|
||||
`InProcessTeammateTask` 与 `LocalAgentTask` 的关键差异：前者共享进程的内存空间和基础设施状态（如 MCP 连接池），但有独立的对话上下文和工具权限；后者是完全隔离的子进程，启动开销更大但更安全。
|
||||
|
||||
## Coordinator vs Swarm 的选择
|
||||
|
||||
| 场景 | 推荐模式 | 原因 |
|
||||
|------|---------|------|
|
||||
| "重构认证系统，需要多模块协调" | Coordinator | 需要集中决策，Worker 间有依赖 |
|
||||
| "修复 10 个独立的 lint 警告" | Swarm | 任务独立，可完全并行 |
|
||||
| "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
|
||||
| "在大仓库中搜索所有 TODO 并分类" | Swarm | 无依赖，各自领任务即可 |
|
||||
194
docs/agent/sub-agents.mdx
Normal file
194
docs/agent/sub-agents.mdx
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
title: "子 Agent 机制 - AgentTool 的执行链路与隔离架构"
|
||||
description: "从源码角度解析 Claude Code 子 Agent：AgentTool.call() 的完整执行链路、Fork 子进程的 Prompt Cache 共享、Worktree 隔离、工具池独立组装、以及结果回传的数据格式。"
|
||||
keywords: ["子 Agent", "AgentTool", "任务委派", "forkSubagent", "子进程隔离"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示子 Agent 的完整执行链路、工具隔离、通信协议和生命周期管理 */}
|
||||
|
||||
## 执行链路总览
|
||||
|
||||
一条 `Agent(prompt="修复 bug")` 调用的完整路径：
|
||||
|
||||
```
|
||||
AI 生成 tool_use: { prompt: "修复 bug", subagent_type: "Explore" }
|
||||
↓
|
||||
AgentTool.call() ← 入口（AgentTool.tsx:239）
|
||||
├── 解析 effectiveType（fork vs 命名 agent）
|
||||
├── filterDeniedAgents() ← 权限过滤
|
||||
├── 检查 requiredMcpServers ← MCP 依赖验证（最长等 30s）
|
||||
├── assembleToolPool(workerPermissionContext) ← 独立组装工具池
|
||||
├── createAgentWorktree() ← 可选 worktree 隔离
|
||||
↓
|
||||
runAgent() ← 核心执行（runAgent.ts:248）
|
||||
├── getAgentSystemPrompt() ← 构建 agent 专属 system prompt
|
||||
├── initializeAgentMcpServers() ← agent 级 MCP 服务器
|
||||
├── executeSubagentStartHooks() ← Hook 注入
|
||||
├── query() ← 进入标准 agentic loop
|
||||
│ ├── 消息流逐条 yield
|
||||
│ └── recordSidechainTranscript() ← JSONL 持久化
|
||||
↓
|
||||
finalizeAgentTool() ← 结果汇总
|
||||
├── 提取文本内容 + usage 统计
|
||||
└── mapToolResultToToolResultBlockParam() ← 格式化为 tool_result
|
||||
```
|
||||
|
||||
## 两种子 Agent 路径：命名 Agent vs Fork
|
||||
|
||||
`AgentTool.call()` 根据是否提供 `subagent_type` 走两条完全不同的路径（`AgentTool.tsx:322-356`）：
|
||||
|
||||
| 维度 | 命名 Agent（`subagent_type` 指定） | Fork 子进程（`subagent_type` 省略） |
|
||||
|------|-------------------------------------|--------------------------------------|
|
||||
| **触发条件** | `subagent_type` 有值 | `isForkSubagentEnabled()` && 未指定类型 |
|
||||
| **System Prompt** | Agent 自身的 `getSystemPrompt()` | 继承父 Agent 的完整 System Prompt |
|
||||
| **工具池** | `assembleToolPool()` 独立组装 | 父 Agent 的原始工具池（`useExactTools: true`） |
|
||||
| **上下文** | 仅任务描述 | 父 Agent 的完整对话历史（`forkContextMessages`） |
|
||||
| **模型** | 可独立指定 | 继承父模型（`model: 'inherit'`） |
|
||||
| **权限模式** | Agent 定义的 `permissionMode` | `'bubble'`（上浮到父终端） |
|
||||
| **目的** | 专业任务委派 | Prompt Cache 命中率优化 |
|
||||
|
||||
Fork 路径的设计核心是 **Prompt Cache 共享**：所有 fork 子进程共享父 Agent 的完整 `assistant` 消息（所有 `tool_use` 块），用相同的占位符 `tool_result` 填充，只有最后一个 `text` 块包含各自的指令。这使得 API 请求前缀字节完全一致，最大化缓存命中。
|
||||
|
||||
```typescript
|
||||
// forkSubagent.ts:142 — 所有 fork 子进程的占位结果
|
||||
const FORK_PLACEHOLDER_RESULT = 'Fork started — processing in background'
|
||||
|
||||
// buildForkedMessages() 构建：
|
||||
// [assistant(全量 tool_use), user(placeholder_results..., 子进程指令)]
|
||||
```
|
||||
|
||||
### Fork 递归防护
|
||||
|
||||
Fork 子进程保留 Agent 工具（为了 cache-identical tool defs），但通过两道防线防止递归 fork（`AgentTool.tsx:332`）：
|
||||
|
||||
1. **`querySource` 检查**（压缩安全）：`context.options.querySource === 'agent:builtin:fork'`
|
||||
2. **消息扫描**（降级兜底）：检测 `<fork-boilerplate>` 标签
|
||||
|
||||
## 工具池的独立组装
|
||||
|
||||
子 Agent 不继承父 Agent 的工具限制——它的工具池完全独立组装（`AgentTool.tsx:573-577`）：
|
||||
|
||||
```typescript
|
||||
const workerPermissionContext = {
|
||||
...appState.toolPermissionContext,
|
||||
mode: selectedAgent.permissionMode ?? 'acceptEdits'
|
||||
}
|
||||
const workerTools = assembleToolPool(workerPermissionContext, appState.mcp.tools)
|
||||
```
|
||||
|
||||
关键设计决策：
|
||||
- **权限模式独立**：子 Agent 使用 `selectedAgent.permissionMode`（默认 `acceptEdits`），不受父 Agent 当前模式的限制
|
||||
- **MCP 工具继承**：`appState.mcp.tools` 包含所有已连接的 MCP 工具，子 Agent 自动获得
|
||||
- **Agent 级 MCP 服务器**：`runAgent()` 中的 `initializeAgentMcpServers()` 可以为特定 Agent 额外连接专属 MCP 服务器
|
||||
|
||||
### 工具过滤的 resolveAgentTools
|
||||
|
||||
`runAgent.ts:500-502` 在工具组装后进一步过滤：
|
||||
|
||||
```typescript
|
||||
const resolvedTools = useExactTools
|
||||
? availableTools // Fork: 直接使用父工具
|
||||
: resolveAgentTools(agentDefinition, availableTools, isAsync).resolvedTools
|
||||
```
|
||||
|
||||
`resolveAgentTools()` 会根据 Agent 定义中的 `tools` 字段过滤可用工具，将 `['*']` 映射为全量工具。
|
||||
|
||||
## Worktree 隔离机制
|
||||
|
||||
`isolation: "worktree"` 参数让子 Agent 在独立的 git worktree 中工作（`AgentTool.tsx:590-593`）：
|
||||
|
||||
```typescript
|
||||
const slug = `agent-${earlyAgentId.slice(0, 8)}`
|
||||
worktreeInfo = await createAgentWorktree(slug)
|
||||
```
|
||||
|
||||
Worktree 生命周期：
|
||||
1. **创建**：在 `.git/worktrees/` 下创建独立工作副本
|
||||
2. **CWD 覆盖**：`runWithCwdOverride(worktreePath, fn)` 让所有文件操作在 worktree 中执行
|
||||
3. **路径翻译**：Fork + worktree 时注入路径翻译通知（`buildWorktreeNotice`）
|
||||
4. **清理**（`cleanupWorktreeIfNeeded`）：
|
||||
- Hook-based worktree → 始终保留
|
||||
- 有变更 → 保留，返回 `worktreePath`
|
||||
- 无变更 → 自动删除
|
||||
|
||||
## 生命周期管理：同步 vs 异步
|
||||
|
||||
### 异步 Agent（后台运行）
|
||||
|
||||
当 `run_in_background=true` 或 `selectedAgent.background=true` 时，Agent 立即返回 `async_launched` 状态（`AgentTool.tsx:686-764`）：
|
||||
|
||||
```
|
||||
registerAsyncAgent(agentId, ...) ← 注册到 AppState.tasks
|
||||
↓ (void — 火后不管)
|
||||
runAsyncAgentLifecycle() ← 后台执行
|
||||
├── runAgent().onCacheSafeParams ← 进度摘要初始化
|
||||
├── 消息流迭代
|
||||
├── completeAsyncAgent() ← 标记完成
|
||||
├── classifyHandoffIfNeeded() ← 安全检查
|
||||
└── enqueueAgentNotification() ← 通知主 Agent
|
||||
```
|
||||
|
||||
异步 Agent 获得独立的 `AbortController`，不与父 Agent 共享——用户按 ESC 取消主线程不会杀掉后台 Agent。
|
||||
|
||||
### 同步 Agent（前台运行）
|
||||
|
||||
同步 Agent 的关键特性是 **可后台化**（`AgentTool.tsx:818-833`）：
|
||||
|
||||
```typescript
|
||||
const registration = registerAgentForeground({
|
||||
autoBackgroundMs: getAutoBackgroundMs() || undefined // 默认 120s
|
||||
})
|
||||
backgroundPromise = registration.backgroundSignal.then(...)
|
||||
```
|
||||
|
||||
在 agentic loop 的每次迭代中，系统用 `Promise.race` 竞争下一条消息和后台化信号：
|
||||
|
||||
```typescript
|
||||
const raceResult = await Promise.race([
|
||||
nextMessagePromise.then(r => ({ type: 'message', result: r })),
|
||||
backgroundPromise // 超过 autoBackgroundMs 触发
|
||||
])
|
||||
```
|
||||
|
||||
后台化后，前台迭代器被终止（`agentIterator.return()`），新的 `runAgent()` 以 `isAsync: true` 重新启动，当前台的输出文件继续写入。
|
||||
|
||||
## 结果回传格式
|
||||
|
||||
`mapToolResultToToolResultBlockParam()` 根据状态返回不同格式（`AgentTool.tsx:1298-1375`）：
|
||||
|
||||
| 状态 | 返回内容 |
|
||||
|------|---------|
|
||||
| `completed` | 内容 + `<usage>` 块（token/tool_calls/duration） |
|
||||
| `async_launched` | agentId + outputFile 路径 + 操作指引 |
|
||||
| `teammate_spawned` | agent_id + name + team_name |
|
||||
| `remote_launched` | taskId + sessionUrl + outputFile |
|
||||
|
||||
对于一次性内置 Agent（Explore、Plan），`<usage>` 块被省略——每周节省约 1-2 Gtok 的上下文窗口。
|
||||
|
||||
## MCP 依赖的等待机制
|
||||
|
||||
如果 Agent 声明了 `requiredMcpServers`，`call()` 会等待这些服务器连接完成（`AgentTool.tsx:371-410`）：
|
||||
|
||||
```typescript
|
||||
const MAX_WAIT_MS = 30_000 // 最长等 30 秒
|
||||
const POLL_INTERVAL_MS = 500 // 每 500ms 轮询
|
||||
```
|
||||
|
||||
早期退出条件：任何必需服务器进入 `failed` 状态时立即停止等待。工具可用性通过 `mcp__` 前缀工具名解析（`mcp__serverName__toolName`）判断。
|
||||
|
||||
## 适用场景
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="并行研究" icon="magnifying-glass">
|
||||
多个 fork 子进程并行搜索不同方向，共享 Prompt Cache 前缀，只有指令不同
|
||||
</Card>
|
||||
<Card title="专业委派" icon="code-branch">
|
||||
使用命名 Agent（Explore/Plan/verification）执行专业任务，受限工具集 + 独立权限
|
||||
</Card>
|
||||
<Card title="隔离实验" icon="flask">
|
||||
`isolation: "worktree"` 在独立工作副本中尝试方案，不影响主分支
|
||||
</Card>
|
||||
<Card title="后台构建" icon="layer-group">
|
||||
`run_in_background: true` 启动长时间构建/测试任务，主 Agent 继续工作
|
||||
</Card>
|
||||
</CardGroup>
|
||||
180
docs/agent/worktree-isolation.mdx
Normal file
180
docs/agent/worktree-isolation.mdx
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: "Worktree 隔离 - Git Worktree 实现文件级隔离"
|
||||
description: "揭秘 Claude Code 的 git worktree 隔离机制：子 Agent 如何获得独立工作空间，worktree 创建/销毁生命周期、路径命名规则和安全防护。"
|
||||
keywords: ["Worktree", "git worktree", "文件隔离", "多 Agent 隔离", "并行安全"]
|
||||
---
|
||||
|
||||
{/* 本章目标：揭示 worktree 的创建/销毁生命周期、路径命名规则、hook 机制和退出时的安全防护 */}
|
||||
|
||||
## 为什么需要文件级隔离
|
||||
|
||||
多 Agent 并行工作时，共享同一工作目录会导致三类冲突：
|
||||
|
||||
1. **写入冲突**：两个 Agent 同时编辑 `config.ts`，后写的覆盖前写的
|
||||
2. **状态干扰**：Agent A 的测试依赖某个环境状态，Agent B 的修改破坏了它
|
||||
3. **不可区分**：半完成的修改混在一起，无法分辨哪些是哪个 Agent 的
|
||||
|
||||
Git worktree 是 git 原生的解决方案——在同一个仓库中创建多个独立工作目录，每个在自己的分支上。
|
||||
|
||||
## 目录结构与命名规则
|
||||
|
||||
Worktree 文件统一存放在仓库根目录下的 `.claude/worktrees/`：
|
||||
|
||||
```
|
||||
<repo-root>/
|
||||
├── .claude/
|
||||
│ └── worktrees/
|
||||
│ ├── fix-auth-bug/ # worktree 工作目录
|
||||
│ │ ├── .git # 指向主仓库的链接文件
|
||||
│ │ └── src/... # 独立的文件系统视图
|
||||
│ └── add-dark-mode/ # 另一个 worktree
|
||||
│ └── ...
|
||||
├── src/ # 主工作目录（不受影响）
|
||||
└── .git/ # 主仓库
|
||||
```
|
||||
|
||||
分支命名规则为 `worktree/<slug>`，其中 slug 由 `validateWorktreeSlug()` 校验：每个 `/` 分隔的段只允许字母、数字、`.`、`_`、`-`，总长 ≤64 字符。未指定时使用 plan slug 自动生成。
|
||||
|
||||
## 创建流程：EnterWorktreeTool
|
||||
|
||||
`EnterWorktreeTool`（`src/tools/EnterWorktreeTool/EnterWorktreeTool.ts`）的执行链路：
|
||||
|
||||
```
|
||||
EnterWorktreeTool.call({ name? })
|
||||
↓
|
||||
1. 检查是否已在 worktree 中（防嵌套）
|
||||
↓
|
||||
2. 解析到主仓库根目录（findCanonicalGitRoot）
|
||||
如果当前已在 worktree 内，chdir 到主仓库
|
||||
↓
|
||||
3. 生成 slug（用户提供或 plan slug）
|
||||
↓
|
||||
4. createWorktreeForSession(sessionId, slug)
|
||||
├── 有 WorktreeCreate hook？
|
||||
│ └── 执行 hook，返回 hook 指定的路径（支持非 git VCS）
|
||||
└── 无 hook → git 原生路径：
|
||||
a. getOrCreateWorktree(repoRoot, slug)
|
||||
├── 快速恢复：检查 worktree 目录是否已存在
|
||||
│ └── 读取 .git 指针文件的 HEAD SHA（无子进程）
|
||||
└── 新建：
|
||||
i. mkdir .claude/worktrees/（recursive）
|
||||
ii. fetch origin/<default-branch>（有缓存则跳过）
|
||||
iii. git worktree add -b worktree/<slug> <path> <base>
|
||||
iv. performPostCreationSetup()（sparse checkout 等）
|
||||
↓
|
||||
5. 更新进程状态：
|
||||
- process.chdir(worktreePath)
|
||||
- setCwd(worktreePath)
|
||||
- setOriginalCwd(worktreePath)
|
||||
- saveWorktreeState(session) → 持久化到项目配置
|
||||
- clearSystemPromptSections() → 重新计算系统提示中的 cwd 信息
|
||||
- clearMemoryFileCaches() → 重新加载 worktree 中的 CLAUDE.md
|
||||
↓
|
||||
6. 返回 worktreePath 和 worktreeBranch
|
||||
```
|
||||
|
||||
### Hook 优先的架构
|
||||
|
||||
`createWorktreeForSession()` 首先检查 `hasWorktreeCreateHook()`——如果用户在 settings.json 中配置了 `WorktreeCreate` hook，系统完全不调用 git，而是执行 hook 命令并将返回的路径作为 worktree 路径。这允许非 git 版本控制系统（如 Pijul、Mercurial）通过 hook 接入。
|
||||
|
||||
### 快速恢复路径
|
||||
|
||||
`getOrCreateWorktree()` 有一个关键优化：如果目标路径已存在，直接读取 `.git` 指针文件获取 HEAD SHA（纯文件 I/O，无子进程），跳过整个 `fetch` + `worktree add` 流程。在大仓库中 `fetch` 需要 6-8 秒，这个优化将恢复场景的延迟降到接近 0。
|
||||
|
||||
## 退出流程：ExitWorktreeTool
|
||||
|
||||
`ExitWorktreeTool`（`src/tools/ExitWorktreeTool/ExitWorktreeTool.ts`）支持两种退出策略：
|
||||
|
||||
### keep：保留 worktree
|
||||
|
||||
```
|
||||
keepWorktree()
|
||||
↓
|
||||
1. chdir 回 originalCwd
|
||||
2. 清空 currentWorktreeSession
|
||||
3. 更新项目配置（activeWorktreeSession = undefined）
|
||||
4. worktree 目录和分支保留在磁盘上
|
||||
```
|
||||
|
||||
用户可以通过 `cd <worktreePath>` 继续工作，或稍后手动合并。
|
||||
|
||||
### remove：删除 worktree
|
||||
|
||||
有严格的**安全防护**：
|
||||
|
||||
```
|
||||
validateInput() — 第一道防线
|
||||
↓
|
||||
1. 检查是否在 EnterWorktree 创建的会话中
|
||||
（手动创建的 worktree 不会被删除）
|
||||
↓
|
||||
2. countWorktreeChanges(worktreePath, originalHeadCommit)
|
||||
├── git status --porcelain → 统计未提交文件数
|
||||
├── git rev-list --count <originalHead>..HEAD → 统计新提交数
|
||||
└── 返回 null（git 失败时）→ fail-closed（拒绝删除）
|
||||
↓
|
||||
3. 有未提交文件或新提交？
|
||||
→ 拒绝，要求 discard_changes: true 确认
|
||||
```
|
||||
|
||||
```
|
||||
call() — 实际执行
|
||||
↓
|
||||
1. 重新计数变更（validateInput 和 call 之间可能有新修改）
|
||||
2. 如果有 tmux session → killTmuxSession()
|
||||
3. cleanupWorktree()
|
||||
├── hook-based → 执行 WorktreeRemove hook
|
||||
└── git-based → git worktree remove --force + git branch -D
|
||||
4. restoreSessionToOriginalCwd()
|
||||
- setCwd(originalCwd)
|
||||
- setOriginalCwd(originalCwd)
|
||||
- 如果 projectRoot 是 worktree 时才恢复（防误触）
|
||||
- 更新 hooks config snapshot
|
||||
- 清空系统提示和 memory 缓存
|
||||
```
|
||||
|
||||
### fail-closed 设计
|
||||
|
||||
`countWorktreeChanges()` 在以下情况返回 `null`（"未知，假设不安全"）：
|
||||
- `git status` 或 `git rev-list` 退出非零（锁文件、损坏的索引）
|
||||
- `originalHeadCommit` 未定义（hook-based worktree 没有设置基线 commit）
|
||||
|
||||
返回 `null` 时，`validateInput` 拒绝删除——宁可让用户手动处理，也不冒险丢失工作。
|
||||
|
||||
## 与 Agent 工具的联动
|
||||
|
||||
Agent 工具（`AgentTool`）的 `isolation` 参数决定子 Agent 是否在 worktree 中运行：
|
||||
|
||||
- `isolation: "worktree"` → 调用 `createWorktreeForSession()`，子 Agent 在独立 worktree 中执行
|
||||
- 无 isolation → 子 Agent 共享主工作目录
|
||||
|
||||
子 Agent 结束时的处理：
|
||||
- **成功**：主 Agent 通过 `ExitWorktreeTool(action: "keep")` 保留 worktree，然后手动合并
|
||||
- **失败/放弃**：主 Agent 通过 `ExitWorktreeTool(action: "remove", discard_changes: true)` 清理
|
||||
|
||||
## Session 状态持久化
|
||||
|
||||
`WorktreeSession` 对象通过 `saveCurrentProjectConfig()` 持久化到磁盘，包含：
|
||||
|
||||
```typescript
|
||||
{
|
||||
originalCwd: string, // 进入 worktree 前的工作目录
|
||||
worktreePath: string, // worktree 的绝对路径
|
||||
worktreeName: string, // slug
|
||||
worktreeBranch?: string, // 分支名（如 worktree/fix-auth）
|
||||
originalBranch?: string, // 进入前的分支
|
||||
originalHeadCommit?: string, // 进入前的 HEAD commit（用于变更统计）
|
||||
sessionId: string, // 创建此 worktree 的会话 ID
|
||||
tmuxSessionName?: string, // 关联的 tmux session
|
||||
hookBased?: boolean, // 是否由 hook 创建
|
||||
creationDurationMs?: number, // 创建耗时（分析用）
|
||||
}
|
||||
```
|
||||
|
||||
这使得 session 恢复（`--resume`）时能正确还原 worktree 上下文——即使进程重启，`getCurrentWorktreeSession()` 从项目配置中读取状态。
|
||||
|
||||
## Sparse Checkout 优化
|
||||
|
||||
对于大型 monorepo，worktree 支持 `sparsePaths` 配置——只检出特定目录而非整个仓库。这在 210K 文件的仓库中将 worktree 创建时间从数十秒降到几秒。
|
||||
|
||||
配置位于 `getInitialSettings().worktree?.sparsePaths`，在 `performPostCreationSetup()` 中应用。
|
||||
312
docs/auto-updater.md
Normal file
312
docs/auto-updater.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# 自动更新机制
|
||||
|
||||
## 概述
|
||||
|
||||
Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安装方式、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。系统设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。
|
||||
|
||||
---
|
||||
|
||||
## 安装类型与更新策略
|
||||
|
||||
更新策略由安装方式决定，通过 `src/utils/doctorDiagnostic.ts` 检测：
|
||||
|
||||
| 安装类型 | 更新策略 | 自动安装？ |
|
||||
|---|---|---|
|
||||
| `native` | 从 GCS/Artifactory 下载二进制文件，通过符号链接激活 | 是（静默） |
|
||||
| `npm-global` | `npm install -g` / `bun install -g` | 是（静默） |
|
||||
| `npm-local` | `npm install` 到 `~/.claude/local/` | 是（静默） |
|
||||
| `package-manager` | 显示通知，附带对应操作系统的升级命令 | 否（仅通知） |
|
||||
| `development` | 不适用 — 执行 `claude update` 时报错 | 不适用 |
|
||||
|
||||
### 策略路由
|
||||
|
||||
`src/components/AutoUpdaterWrapper.tsx` — 挂载在 React/Ink UI 树中 — 检测安装类型并渲染对应的更新组件：
|
||||
|
||||
- `native` → `NativeAutoUpdater`（二进制下载 + 符号链接）
|
||||
- `package-manager` → `PackageManagerAutoUpdater`（仅通知）
|
||||
- 其他 → `AutoUpdater`（基于 JS/npm）
|
||||
|
||||
---
|
||||
|
||||
## 后台自动更新循环
|
||||
|
||||
三个更新组件共享相同的轮询模式：
|
||||
|
||||
```typescript
|
||||
useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
|
||||
```
|
||||
|
||||
组件挂载时（即启动时）也会执行一次检查。
|
||||
|
||||
### 前置检查门控
|
||||
|
||||
任何更新尝试之前，系统会依次检查：
|
||||
|
||||
1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1735`）
|
||||
- `NODE_ENV === 'development'`
|
||||
- 设置了 `DISABLE_AUTOUPDATER` 环境变量
|
||||
- 仅限必要流量模式
|
||||
- `config.autoUpdates === false`（native 安装的保护模式除外）
|
||||
2. **最大版本上限？** — `getMaxVersion()`（`src/utils/autoUpdater.ts:108`）— 服务端熔断开关，防止更新到已知有问题的版本
|
||||
3. **是否跳过该版本？** — `shouldSkipVersion()`（`src/utils/autoUpdater.ts:145`）— 尊重用户的 `minimumVersion` 设置，防止切换到 stable 频道时发生意外的版本降级
|
||||
|
||||
### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`）
|
||||
|
||||
1. 调用 `src/utils/nativeInstaller/installer.ts` 中的 `installLatest()`
|
||||
2. 通过 `src/utils/nativeInstaller/download.ts` 下载二进制文件（GCS 或 Artifactory）
|
||||
3. 验证 SHA256 校验和（3 次重试，60 秒卡顿检测）
|
||||
4. 将版本化二进制文件存储到 XDG 目录
|
||||
5. 更新符号链接（`~/.local/bin/claude` → 新版本二进制文件）
|
||||
6. 保留最近 2 个版本，清理旧版本
|
||||
7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络）
|
||||
|
||||
### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`）
|
||||
|
||||
1. 调用 `getLatestVersion()` 获取当前 npm dist-tag
|
||||
2. 通过 semver `gte()` 比较版本
|
||||
3. 根据安装类型路由到本地或全局安装
|
||||
4. 使用文件锁（`acquireLock()` / `releaseLock()`）防止并发更新
|
||||
|
||||
### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`）
|
||||
|
||||
每 30 分钟通过 GCS 存储桶（非 npm）检查更新。**不会自动安装** — 仅显示对应操作系统的升级命令：
|
||||
|
||||
- macOS: `brew upgrade claude-code`
|
||||
- Windows: `winget upgrade Anthropic.ClaudeCode`
|
||||
- Alpine: `apk upgrade claude-code`
|
||||
|
||||
---
|
||||
|
||||
## 启动版本门控
|
||||
|
||||
`src/utils/autoUpdater.ts:70` — `assertMinVersion()`
|
||||
|
||||
从 `src/main.tsx:1775` 在启动时调用：
|
||||
|
||||
```typescript
|
||||
void assertMinVersion();
|
||||
```
|
||||
|
||||
1. 从 GrowthBook 动态配置获取 `tengu_version_config`
|
||||
2. 如果 `MACRO.VERSION < minVersion`，打印错误信息并调用 `gracefulShutdownSync(1)` — 强制用户更新
|
||||
3. 这是一个**硬性门控** — 低于最低版本的 CLI 将无法启动
|
||||
|
||||
---
|
||||
|
||||
## 手动 CLI 命令
|
||||
|
||||
### `claude update` / `claude upgrade`
|
||||
|
||||
**文件**: `src/cli/update.ts`
|
||||
|
||||
完整流程：
|
||||
1. 运行 `getDoctorDiagnostic()` 检查系统健康状态
|
||||
2. 检查是否存在多个安装及配置不一致
|
||||
3. 根据安装类型路由：
|
||||
- `development` → 报错（"开发版本不支持自动更新"）
|
||||
- `package-manager` → 打印对应操作系统的更新命令
|
||||
- `native` → 使用原生安装器的 `updateLatest()`
|
||||
- `npm-local` → 在 `~/.claude/local/` 执行 `npm install`
|
||||
- `npm-global` → 执行 `npm install -g`（含权限检查）
|
||||
4. 报告当前版本、最新版本、成功/失败状态
|
||||
|
||||
### `claude rollback [target]`（仅限内部）
|
||||
|
||||
回滚到之前的版本。支持 `--list`、`--dry-run`、`--safe` 标志。
|
||||
|
||||
### `claude install [target]`
|
||||
|
||||
安装或重新安装原生构建版本。接受可选的版本目标参数。
|
||||
|
||||
### `claude doctor`
|
||||
|
||||
检查自动更新器的健康状态，报告状态、权限和配置信息。
|
||||
|
||||
---
|
||||
|
||||
## 原生安装器架构
|
||||
|
||||
**文件**: `src/utils/nativeInstaller/installer.ts`
|
||||
|
||||
### 二进制文件存储布局
|
||||
|
||||
```
|
||||
~/.local/share/claude-code/
|
||||
├── versions/ # 版本化二进制文件 (claude-1.0.3, claude-1.0.4, ...)
|
||||
├── staging/ # 临时下载暂存区
|
||||
└── locks/ # 基于 PID 和 mtime 的锁文件
|
||||
|
||||
~/.local/bin/claude # 指向当前版本二进制文件的符号链接
|
||||
```
|
||||
|
||||
Windows 系统使用文件复制而非符号链接。
|
||||
|
||||
### 核心操作
|
||||
|
||||
| 函数 | 说明 |
|
||||
|---|---|
|
||||
| `updateLatest()` | 核心更新流程：最大版本上限 → 跳过检查 → 加锁 → 下载 → 安装 → 更新符号链接 |
|
||||
| `installLatest()` | Singleflight 包装版本，防止重复的进行中安装 |
|
||||
| `cleanupOldVersions()` | 保留最近 2 个版本，清理过期的暂存区和临时文件 |
|
||||
| `lockCurrentVersion()` | 进程生命周期锁，防止正在运行的版本被删除 |
|
||||
| `cleanupNpmInstallations()` | 迁移到原生安装时清理旧的 npm 安装 |
|
||||
|
||||
### 下载与校验
|
||||
|
||||
**文件**: `src/utils/nativeInstaller/download.ts`
|
||||
|
||||
1. 路由到 Artifactory（内部用户）或 GCS 存储桶（外部用户）
|
||||
2. 下载二进制文件并跟踪进度
|
||||
3. SHA256 校验和验证
|
||||
4. 60 秒卡顿检测（中止停滞的下载）
|
||||
5. 失败时自动重试 3 次
|
||||
|
||||
---
|
||||
|
||||
## 文件锁机制
|
||||
|
||||
**文件**: `src/utils/autoUpdater.ts:176-268`
|
||||
|
||||
防止并发更新进程破坏安装：
|
||||
|
||||
- 锁文件：`~/.claude/update.lock`（或等效路径）
|
||||
- 5 分钟超时 — 超过 5 分钟的锁被视为过期，强制获取
|
||||
- 进程将其 PID 写入锁文件
|
||||
- `acquireLock()` 和 `releaseLock()` 同时被 JS/npm 和原生安装器使用
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
### 设置项
|
||||
|
||||
**文件**: `src/utils/settings/types.ts`
|
||||
|
||||
| 设置项 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `autoUpdatesChannel` | `'latest' \| 'stable'` | 自动更新的发布频道 |
|
||||
| `minimumVersion` | string | 最低版本要求，防止意外的版本降级 |
|
||||
|
||||
### 全局配置
|
||||
|
||||
**文件**: `src/utils/config.ts:191-193`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `autoUpdates` | boolean | 启用/禁用自动更新（旧版） |
|
||||
| `autoUpdatesProtectedForNative` | boolean | 原生安装始终自动更新 |
|
||||
|
||||
### 配置迁移
|
||||
|
||||
**文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`
|
||||
|
||||
一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。从 `src/main.tsx:325` 在启动时调用。
|
||||
|
||||
---
|
||||
|
||||
## 更新通知去重
|
||||
|
||||
**文件**: `src/hooks/useUpdateNotification.ts`
|
||||
|
||||
React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变更（major.minor.patch）只显示一次"重启以更新"消息，避免同一版本的重复通知。
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
**文件**: `src/utils/releaseNotes.ts`
|
||||
|
||||
1. 从 `src/setup.ts:387` 在每次启动时调用
|
||||
2. 从 GitHub 获取 changelog
|
||||
3. 缓存到 `~/.claude/cache/changelog.md`
|
||||
4. 展示比 `lastReleaseNotesSeen` 更新的版本的更新日志
|
||||
5. 使用 semver 比较确定需要展示哪些日志
|
||||
|
||||
---
|
||||
|
||||
## 版本比较
|
||||
|
||||
**文件**: `src/utils/semver.ts`
|
||||
|
||||
- 提供 `gt()`、`gte()`、`lt()`、`lte()`、`satisfies()`、`order()`
|
||||
- 在 Bun 环境下使用 `Bun.semver.order()`（快 20 倍）
|
||||
- 在 Node.js 环境下回退到 npm `semver` 包
|
||||
|
||||
---
|
||||
|
||||
## 分析事件
|
||||
|
||||
所有更新相关的遥测数据使用 `tengu_` 前缀的事件：
|
||||
|
||||
| 类别 | 事件 |
|
||||
|---|---|
|
||||
| 版本检查 | `tengu_version_check_success`、`tengu_version_check_failure` |
|
||||
| JS 自动更新器 | `tengu_auto_updater_start/success/fail/up_to_date/lock_contention` |
|
||||
| 原生自动更新器 | `tengu_native_auto_updater_start/success/fail` |
|
||||
| 原生更新 | `tengu_native_update_complete/skipped_max_version/skipped_minimum_version` |
|
||||
| 锁机制 | `tengu_version_lock_acquired/failed`、`tengu_native_update_lock_failed` |
|
||||
| 二进制下载 | `tengu_binary_download_attempt/success/failure`、`tengu_binary_manifest_fetch_failure` |
|
||||
| 清理 | `tengu_native_version_cleanup`、`tengu_native_staging_cleanup`、`tengu_native_stale_locks_cleanup` |
|
||||
| 安装 | `tengu_native_install_package_success/failure`、`tengu_native_install_binary_success/failure` |
|
||||
| 手动更新 | `tengu_update_check` |
|
||||
| 迁移 | `tengu_migrate_autoupdates_to_settings`、`tengu_migrate_autoupdates_error` |
|
||||
|
||||
---
|
||||
|
||||
## 关键文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|---|---|
|
||||
| `src/utils/autoUpdater.ts` | 核心逻辑：版本检查、npm 安装、文件锁、最低/最高版本门控 |
|
||||
| `src/cli/update.ts` | `claude update` 命令处理 |
|
||||
| `src/utils/nativeInstaller/installer.ts` | 原生二进制安装器：下载、版本管理、符号链接、清理 |
|
||||
| `src/utils/nativeInstaller/download.ts` | 从 GCS/Artifactory 下载二进制文件并校验 |
|
||||
| `src/utils/localInstaller.ts` | 本地安装器（`~/.claude/local/`）基于 npm |
|
||||
| `src/components/AutoUpdaterWrapper.tsx` | 基于安装类型的策略路由 |
|
||||
| `src/components/AutoUpdater.tsx` | JS/npm 后台自动更新器（30 分钟间隔） |
|
||||
| `src/components/NativeAutoUpdater.tsx` | 原生二进制后台自动更新器（30 分钟间隔） |
|
||||
| `src/components/PackageManagerAutoUpdater.tsx` | 包管理器通知（30 分钟，仅展示） |
|
||||
| `src/hooks/useUpdateNotification.ts` | 按 semver 去重更新通知 |
|
||||
| `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 |
|
||||
| `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） |
|
||||
| `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 |
|
||||
| `src/utils/config.ts:1735` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
|
||||
| `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
|
||||
| `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |
|
||||
|
||||
---
|
||||
|
||||
## 流程图
|
||||
|
||||
```
|
||||
启动阶段
|
||||
├── assertMinVersion() → 版本过低时硬性拦截，拒绝启动
|
||||
├── migrateAutoUpdatesToSettings() → 一次性配置迁移
|
||||
└── checkForReleaseNotes() → 展示新版本的更新日志
|
||||
|
||||
REPL 运行中（每 30 分钟）
|
||||
├── AutoUpdaterWrapper 检测安装类型
|
||||
│
|
||||
├── native → NativeAutoUpdater
|
||||
│ ├── 从 GCS/Artifactory 获取版本
|
||||
│ ├── 检查最大版本上限（服务端控制）
|
||||
│ ├── 检查 minimumVersion 设置（跳过）
|
||||
│ ├── acquireLock()
|
||||
│ ├── downloadAndVerifyBinary()（SHA256 校验，3 次重试）
|
||||
│ ├── 安装到 versions/ 目录
|
||||
│ ├── 更新符号链接
|
||||
│ └── cleanupOldVersions()（保留 2 个版本）
|
||||
│
|
||||
├── npm-global/local → AutoUpdater
|
||||
│ ├── 从 npm registry 获取最新版本
|
||||
│ ├── semver 版本比较
|
||||
│ ├── acquireLock()
|
||||
│ └── npm install -g / 本地安装
|
||||
│
|
||||
└── package-manager → PackageManagerAutoUpdater
|
||||
├── 从 GCS 获取版本
|
||||
└── 显示 "Run: brew upgrade ..."（不自动安装）
|
||||
|
||||
手动操作
|
||||
└── claude update → 完整诊断 + 安装编排
|
||||
```
|
||||
239
docs/context/compaction.mdx
Normal file
239
docs/context/compaction.mdx
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
title: "上下文压缩 - Compaction 三层策略与边界机制"
|
||||
description: "深度解析 Claude Code 上下文压缩的完整实现：Session Memory 压缩、传统 API 摘要压缩、MicroCompact 局部压缩三层策略，以及 CompactBoundary 消息、工具对保持、PTL 紧急降级等关键机制。"
|
||||
keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩", "上下文窗口", "MicroCompact"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码层面剖析压缩的三层策略、边界机制和关键常量 */}
|
||||
|
||||
## 压缩的触发时机
|
||||
|
||||
上下文压缩不是单一操作，而是**三层递进**的策略系统，对应不同的触发条件和严重程度：
|
||||
|
||||
| 层级 | 触发条件 | 实现位置 | 是否需要 API 调用 |
|
||||
|------|---------|---------|:---:|
|
||||
| **MicroCompact** | 单个工具输出过长 | `microCompact.ts` | 否 |
|
||||
| **Session Memory Compact** | 自动压缩触发（需 feature flag） | `sessionMemoryCompact.ts` | 否 |
|
||||
| **传统 API 摘要** | 手动 `/compact` 或 SM 不可用时的自动回退 | `compact.ts` | 是 |
|
||||
|
||||
### 压缩入口的优先级链
|
||||
|
||||
源码路径：`src/commands/compact/compact.ts`
|
||||
|
||||
当用户执行 `/compact` 或系统触发自动压缩时，压缩命令按以下优先级尝试：
|
||||
|
||||
```typescript
|
||||
// compact.ts:55-99 — 简化后的优先级链
|
||||
if (!customInstructions) {
|
||||
const sessionMemoryResult = await trySessionMemoryCompaction(messages, ...)
|
||||
if (sessionMemoryResult) return sessionMemoryResult // 优先：SM 压缩
|
||||
}
|
||||
|
||||
if (reactiveCompact?.isReactiveOnlyMode()) {
|
||||
return await compactViaReactive(messages, ...) // 次选：Reactive 压缩
|
||||
}
|
||||
|
||||
// 兜底：传统 API 摘要
|
||||
const microcompactResult = await microcompactMessages(messages, context)
|
||||
const messagesForCompact = microcompactResult.messages
|
||||
// → 调用 AI 模型生成摘要
|
||||
```
|
||||
|
||||
注意：SM 压缩不支持自定义指令（`/compact 聚焦在认证模块`），有自定义指令时直接走传统路径。
|
||||
|
||||
## 第一层：MicroCompact — 局部压缩
|
||||
|
||||
源码路径：`src/services/compact/microCompact.ts`
|
||||
|
||||
MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单：
|
||||
|
||||
```typescript
|
||||
const COMPACTABLE_TOOLS = new Set([
|
||||
'Read', // 文件读取
|
||||
'Bash', // 命令输出
|
||||
'Grep', // 搜索结果
|
||||
'Glob', // 文件列表
|
||||
'WebSearch', // 搜索结果
|
||||
'WebFetch', // 网页内容
|
||||
'Edit', // 编辑输出
|
||||
'Write', // 写入输出
|
||||
])
|
||||
```
|
||||
|
||||
替换策略：将超过时间窗口的工具输出内容替换为 `[Old tool result content cleared]`。这不是简单的截断——原始内容仍保留在 JSONL transcript 中，只是不再发送给 API。
|
||||
|
||||
MicroCompact 还有一个**时间衰减配置**（`timeBasedMCConfig.ts`）：越旧的工具输出越容易被清除，最近的优先保留。
|
||||
|
||||
### 图片和文档的特殊处理
|
||||
|
||||
```typescript
|
||||
const IMAGE_MAX_TOKEN_SIZE = 2000
|
||||
```
|
||||
|
||||
图片 block 如果超过 2000 token 估算值，也会被 MicroCompact 清除。PDF document block 同理。
|
||||
|
||||
## 第二层：Session Memory Compact — 无 API 调用的压缩
|
||||
|
||||
源码路径：`src/services/compact/sessionMemoryCompact.ts`
|
||||
|
||||
当 `tengu_session_memory` + `tengu_sm_compact` 两个 feature flag 启用时，系统优先使用 Session Memory 进行压缩——**不需要调用摘要模型**，直接使用已经提取好的 Session Memory 作为对话摘要。
|
||||
|
||||
### 保留窗口的计算
|
||||
|
||||
```typescript
|
||||
// sessionMemoryCompact.ts:324-397
|
||||
export function calculateMessagesToKeepIndex(messages, lastSummarizedIndex) {
|
||||
const config = getSessionMemoryCompactConfig()
|
||||
// 默认: minTokens=10K, minTextBlockMessages=5, maxTokens=40K
|
||||
|
||||
let startIndex = lastSummarizedIndex + 1
|
||||
// 从 lastSummarizedIndex 向前扩展，直到满足两个下限或命中上限
|
||||
for (let i = startIndex - 1; i >= floor; i--) {
|
||||
totalTokens += estimateMessageTokens([msg])
|
||||
if (hasTextBlocks(msg)) textBlockMessageCount++
|
||||
startIndex = i
|
||||
if (totalTokens >= config.maxTokens) break
|
||||
if (totalTokens >= config.minTokens && textBlockMessageCount >= config.minTextBlockMessages) break
|
||||
}
|
||||
return adjustIndexToPreserveAPIInvariants(messages, startIndex)
|
||||
}
|
||||
```
|
||||
|
||||
这个算法确保压缩后保留的消息窗口满足：
|
||||
- 至少 10,000 token（有上下文深度）
|
||||
- 至少 5 条包含文本的消息（有对话连续性）
|
||||
- 最多 40,000 token（不会太大又触发下一次压缩）
|
||||
|
||||
### 工具对完整性保护
|
||||
|
||||
`adjustIndexToPreserveAPIInvariants()` 是压缩中一个**关键的正确性保证**：
|
||||
|
||||
API 要求每个 `tool_result` 都有对应的 `tool_use`，反之亦然。如果压缩恰好切在一条 `tool_result` 消息处，会导致 API 报错。
|
||||
|
||||
```typescript
|
||||
// sessionMemoryCompact.ts:232-314
|
||||
// Step 1: 向前扫描，找到所有被保留消息中 tool_result 引用的 tool_use
|
||||
// Step 2: 向前扫描，找到与被保留 assistant 消息共享 message.id 的 thinking block
|
||||
// 两种情况都需要将 startIndex 向前移动
|
||||
```
|
||||
|
||||
流式传输会将一个 assistant 消息拆分为多条存储记录（thinking、tool_use 等各有独立 uuid 但共享 `message.id`），这增加了边界情况的复杂度。
|
||||
|
||||
## 第三层：传统 API 摘要压缩
|
||||
|
||||
源码路径：`src/services/compact/compact.ts`
|
||||
|
||||
当 SM 压缩不可用时，系统回退到传统方式：调用 AI 模型生成对话摘要。
|
||||
|
||||
### 压缩前处理
|
||||
|
||||
发送给摘要模型之前，消息会经过多层预处理：
|
||||
|
||||
```typescript
|
||||
// compact.ts:147-202
|
||||
const stripped = stripImagesFromMessages(messages) // 图片→[image] 文字标记
|
||||
const stripped2 = stripReinjectedAttachments(stripped) // 移除会被重新注入的附件
|
||||
```
|
||||
|
||||
图片被替换为 `[image]` 标记，防止摘要 API 调用本身也触发 prompt-too-long 错误。
|
||||
|
||||
### 压缩后的重新注入
|
||||
|
||||
压缩后，系统会从摘要中**重新注入关键上下文**：
|
||||
|
||||
```typescript
|
||||
// compact.ts:124-132
|
||||
export const POST_COMPACT_TOKEN_BUDGET = 50_000 // 总预算
|
||||
export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5 // 最多恢复 5 个文件
|
||||
export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000 // 每文件 5K token
|
||||
export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000 // 每技能 5K token
|
||||
export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000 // 技能总预算 25K
|
||||
```
|
||||
|
||||
这 50K token 的重新注入预算用于：
|
||||
1. 恢复最近读取的文件内容（最多 5 个文件，每个截断到 5K token）
|
||||
2. 恢复已激活的技能指令（每个技能截断到 5K token，总计 25K）
|
||||
3. 重新注入 CLAUDE.md 内容
|
||||
4. 恢复 MCP 工具发现结果
|
||||
|
||||
## CompactBoundary：压缩的边界标记
|
||||
|
||||
源码路径：`src/utils/messages.ts`（`createCompactBoundaryMessage`）
|
||||
|
||||
每次压缩后，系统在消息流中插入一条 `SystemCompactBoundaryMessage`：
|
||||
|
||||
```typescript
|
||||
type SystemCompactBoundaryMessage = {
|
||||
type: 'system'
|
||||
message: {
|
||||
type: 'compact_boundary'
|
||||
compactMetadata: {
|
||||
compactType: 'auto' | 'manual' | 'micro'
|
||||
preCompactTokenCount: number
|
||||
lastUserMessageUuid: string
|
||||
preCompactDiscoveredTools?: string[]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
后续所有操作只处理**最后一条 boundary 之后**的消息：
|
||||
|
||||
```typescript
|
||||
// messages.ts
|
||||
export function getMessagesAfterCompactBoundary(messages: Message[]): Message[] {
|
||||
const lastBoundary = messages.findLastIndex(m => isCompactBoundaryMessage(m))
|
||||
return lastBoundary >= 0 ? messages.slice(lastBoundary + 1) : messages
|
||||
}
|
||||
```
|
||||
|
||||
### Preserved Segment 注解
|
||||
|
||||
boundary 消息上还附加了 `preservedSegment` 注解，记录哪些消息被保留而非压缩：
|
||||
|
||||
```typescript
|
||||
// compact.ts — annotateBoundaryWithPreservedSegment
|
||||
boundaryMarker.compactMetadata.preservedSegment = {
|
||||
summaryMessageUuid: string
|
||||
preservedMessageUuids: string[]
|
||||
}
|
||||
```
|
||||
|
||||
这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。
|
||||
|
||||
## PTL 紧急降级：Prompt Too Long
|
||||
|
||||
当压缩后仍然超出 token 限制（`PROMPT_TOO_LONG` 错误），系统会进入紧急降级路径：
|
||||
|
||||
1. **Reactive Compact**：`reactiveCompactOnPromptTooLong()` 尝试更激进的压缩
|
||||
2. **截断重试**：如果 reactive 也失败，`truncateHeadForPTLRetry()` 直接截断最早的消息
|
||||
3. 放弃并报错
|
||||
|
||||
Reactive Compact 目前在反编译版本中是 stub（`isReactiveOnlyMode() → false`），表明这是 Anthropic 内部的实验性功能。
|
||||
|
||||
## 压缩的 Hook 机制
|
||||
|
||||
压缩前后可以执行自定义 Hook：
|
||||
|
||||
- **Pre-compact Hook**（`executePreCompactHooks`）：在压缩前执行，可以注入"必须保留"的标记
|
||||
- **Post-compact Hook**（`executePostCompactHooks`）：在压缩后执行，可以验证关键信息是否保留
|
||||
- **Session Start Hook**（`processSessionStartHooks('compact')`）：SM 压缩使用此 Hook 恢复 CLAUDE.md 等上下文
|
||||
|
||||
Hook 结果以 `HookResultMessage` 的形式附加到压缩结果中，确保用户的自定义逻辑在压缩过程中被尊重。
|
||||
|
||||
## Snip Compact（实验性）
|
||||
|
||||
源码路径：`src/services/compact/snipCompact.ts`（stub）
|
||||
|
||||
Snip Compact 是另一种实验性压缩策略，在反编译版本中为空壳实现。从 stub 的类型签名推断：
|
||||
|
||||
```typescript
|
||||
snipCompactIfNeeded(messages, options?: { force?: boolean }) → {
|
||||
messages: Message[]
|
||||
executed: boolean
|
||||
tokensFreed: number
|
||||
boundaryMessage?: Message
|
||||
}
|
||||
```
|
||||
|
||||
它似乎是一种**更细粒度的消息级裁剪**（snip = 剪切），可能是对单条消息的进一步压缩，而非整个对话。`shouldNudgeForSnips()` 和 `SNIP_NUDGE_TEXT` 暗示它可能会提示用户触发。
|
||||
226
docs/context/project-memory.mdx
Normal file
226
docs/context/project-memory.mdx
Normal file
@@ -0,0 +1,226 @@
|
||||
---
|
||||
title: "项目记忆系统 - 文件级跨对话记忆架构"
|
||||
description: "深度解析 Claude Code 记忆系统：基于文件的持久化存储、MEMORY.md 索引结构、四类型分类法、Sonnet 智能召回、Session Memory 压缩集成。"
|
||||
keywords: ["项目记忆", "MEMORY.md", "AI 记忆", "跨对话", "自动记忆", "memdir"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码层面剖析记忆系统的存储架构、召回机制和注入链路 */}
|
||||
|
||||
## 记忆系统的存储架构
|
||||
|
||||
源码路径：`src/memdir/paths.ts`、`src/memdir/memdir.ts`
|
||||
|
||||
Claude Code 的记忆系统是**纯文件**的——没有数据库、没有向量存储，只有 Markdown 文件和目录结构。
|
||||
|
||||
### 目录布局
|
||||
|
||||
```
|
||||
~/.claude/projects/<sanitized-git-root>/memory/
|
||||
├── MEMORY.md ← 入口索引（每次对话加载）
|
||||
├── user_role.md ← 用户记忆
|
||||
├── feedback_testing.md ← 反馈记忆
|
||||
├── project_mobile_release.md ← 项目记忆
|
||||
├── reference_linear_ingest.md ← 参考记忆
|
||||
└── logs/ ← KAIROS 模式：每日日志
|
||||
└── 2026/
|
||||
└── 04/
|
||||
└── 2026-04-01.md
|
||||
```
|
||||
|
||||
路径解析链路（`getAutoMemPath()`）：
|
||||
1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` 环境变量（Cowork SDK 全路径覆盖）
|
||||
2. `autoMemoryDirectory` 设置（仅限 `policySettings`/`localSettings`/`userSettings`——**故意排除** `projectSettings`，防止恶意仓库将记忆路径指向 `~/.ssh`）
|
||||
3. 默认：`<memoryBase>/projects/<sanitized-git-root>/memory/`
|
||||
|
||||
同一个 Git 仓库的所有 worktree 共享一个记忆目录（通过 `findCanonicalGitRoot()` 找到真正的 `.git` 根）。
|
||||
|
||||
### MEMORY.md 索引
|
||||
|
||||
`MEMORY.md` 是记忆的入口索引，每次对话都完整加载到上下文中：
|
||||
|
||||
```typescript
|
||||
// memdir.ts:35-38
|
||||
export const ENTRYPOINT_NAME = 'MEMORY.md'
|
||||
export const MAX_ENTRYPOINT_LINES = 200
|
||||
export const MAX_ENTRYPOINT_BYTES = 25_000
|
||||
```
|
||||
|
||||
索引有**双重上限**：200 行 AND 25KB。超过任何一条都会被 `truncateEntrypointContent()` 截断并追加警告。设计原因：p97 的索引文件用 200 行就能覆盖，但有些索引条目特别长（p100 观测到 197KB/200 行），字节上限捕捉这种长行异常。
|
||||
|
||||
索引条目格式：
|
||||
```markdown
|
||||
- [Title](file.md) — one-line hook
|
||||
```
|
||||
|
||||
每条一行，~150 字符以内。`MEMORY.md` 本身没有 frontmatter——它只是一个链接列表，不是记忆内容。
|
||||
|
||||
## 四类型分类法
|
||||
|
||||
源码路径：`src/memdir/memoryTypes.ts`
|
||||
|
||||
记忆被约束为一个**封闭的四类型系统**，每种类型有明确的 `<when_to_save>`、`<how_to_use>` 和 `<body_structure>` 规范：
|
||||
|
||||
| 类型 | 存储内容 | 典型触发 |
|
||||
|------|---------|---------|
|
||||
| **user** | 用户角色、偏好、技术背景 | "我是数据科学家"、"我写了十年 Go" |
|
||||
| **feedback** | 用户对 AI 行为的纠正和确认 | "别 mock 数据库"、"单 PR 更好" |
|
||||
| **project** | 非代码可推导的项目上下文 | "合并冻结从周四开始"、"auth 重写是合规要求" |
|
||||
| **reference** | 外部系统指针 | "pipeline bugs 在 Linear INGEST 项目" |
|
||||
|
||||
关键设计约束：**只存储无法从当前项目状态推导的信息**。代码架构、文件路径、git 历史都可以实时获取，不需要记忆。
|
||||
|
||||
### 反馈类型的双通道捕获
|
||||
|
||||
`feedback` 类型的 `when_to_save` 指令特别强调：
|
||||
|
||||
> Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.
|
||||
|
||||
这意味着 AI 不仅在用户说"不要这样做"时保存，也在用户说"对，就是这样"时保存。后一种更难捕捉，但同等重要——它防止 AI 的行为随时间漂移。
|
||||
|
||||
### 每条记忆的 Frontmatter 格式
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {{memory name}}
|
||||
description: {{one-line description — 用于未来判断相关性}}
|
||||
type: {{user, feedback, project, reference}}
|
||||
---
|
||||
|
||||
{{memory content — feedback/project 类型建议包含 **Why:** 和 **How to apply:** 行}}
|
||||
```
|
||||
|
||||
`description` 字段是关键：它不是给人读的摘要，而是给 AI 召回系统做相关性判断的搜索关键词。
|
||||
|
||||
## 智能召回机制
|
||||
|
||||
源码路径：`src/memdir/findRelevantMemories.ts`、`src/memdir/memoryScan.ts`
|
||||
|
||||
不是所有记忆都适合每次对话。系统使用一个**轻量级 Sonnet 侧查询**来筛选最相关的记忆。
|
||||
|
||||
### 召回流程
|
||||
|
||||
```
|
||||
用户消息 → findRelevantMemories(query, memoryDir)
|
||||
├── scanMemoryFiles() — 扫描所有记忆文件的 frontmatter
|
||||
├── selectRelevantMemories() — Sonnet 侧查询，从清单中选出 ≤5 条
|
||||
└── 返回 [{path, mtimeMs}, ...]
|
||||
```
|
||||
|
||||
核心是 `selectRelevantMemories()` 函数，它调用 `sideQuery()`（一个独立的轻量 API 调用）：
|
||||
|
||||
```typescript
|
||||
// findRelevantMemories.ts:98-121
|
||||
const result = await sideQuery({
|
||||
model: getDefaultSonnetModel(), // 用 Sonnet 做筛选（非主模型）
|
||||
system: SELECT_MEMORIES_SYSTEM_PROMPT,
|
||||
messages: [{
|
||||
role: 'user',
|
||||
content: `Query: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}`
|
||||
}],
|
||||
max_tokens: 256,
|
||||
output_format: { type: 'json_schema', schema: { ... } },
|
||||
})
|
||||
```
|
||||
|
||||
### 近期工具去噪
|
||||
|
||||
当 AI 正在使用某个工具时，召回该工具的使用文档是噪音（对话中已有工作上下文）。`recentTools` 参数让召回系统跳过这些记忆：
|
||||
|
||||
```typescript
|
||||
// findRelevantMemories.ts:92-95
|
||||
const toolsSection = recentTools.length > 0
|
||||
? `\n\nRecently used tools: ${recentTools.join(', ')}`
|
||||
: ''
|
||||
```
|
||||
|
||||
System Prompt 明确指示："如果已提供最近使用的工具列表，不要选择该工具的使用参考或 API 文档。**仍然要选择**关于这些工具的警告、陷阱或已知问题——这正是使用时最关键的信息。"
|
||||
|
||||
### 已展示去重
|
||||
|
||||
`alreadySurfaced` 参数过滤之前轮次已展示过的文件路径，让 Sonnet 的 5 槽预算花在新的候选上，而不是重复召回同一文件。
|
||||
|
||||
## 记忆注入 System Prompt 的链路
|
||||
|
||||
源码路径：`src/memdir/memdir.ts` → `src/context.ts`
|
||||
|
||||
`loadMemoryPrompt()` 是记忆注入的入口，每会话调用一次（通过 `systemPromptSection('memory', ...)` 缓存）：
|
||||
|
||||
```typescript
|
||||
// memdir.ts:419-507
|
||||
export async function loadMemoryPrompt(): Promise<string | null> {
|
||||
// 优先级：KAIROS 日志模式 → TEAMMEM 组合模式 → 纯自动记忆
|
||||
if (feature('KAIROS') && autoEnabled && getKairosActive()) {
|
||||
return buildAssistantDailyLogPrompt(skipIndex)
|
||||
}
|
||||
if (feature('TEAMMEM') && teamMemPaths!.isTeamMemoryEnabled()) {
|
||||
return teamMemPrompts!.buildCombinedMemoryPrompt(...)
|
||||
}
|
||||
if (autoEnabled) {
|
||||
return buildMemoryLines('auto memory', autoDir, ...).join('\n')
|
||||
}
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
注入时机：`context.ts` 中 `getSystemContext()` 调用时，记忆 Prompt 作为 system prompt 的一个 section 被组装。`MEMORY.md` 的内容作为 **user context message** 注入（而非 system prompt），这样可以利用 Prompt Cache 的 prefix 共享。
|
||||
|
||||
## KAIROS 模式：每日日志
|
||||
|
||||
源码路径：`src/memdir/memdir.ts`（`buildAssistantDailyLogPrompt`）
|
||||
|
||||
长期运行的 assistant 会话使用不同的记忆策略：
|
||||
|
||||
- **标准模式**：AI 维护 `MEMORY.md` 作为实时索引 + 独立记忆文件
|
||||
- **KAIROS 模式**：AI 只往日期文件追加日志（`logs/YYYY/MM/YYYY-MM-DD.md`），不做重组
|
||||
|
||||
```typescript
|
||||
// 日志路径模式（非字面路径——因为 Prompt 被缓存）
|
||||
const logPathPattern = join(memoryDir, 'logs', 'YYYY', 'MM', 'YYYY-MM-DD.md')
|
||||
```
|
||||
|
||||
一个独立的夜间 `/dream` 技能负责将日志蒸馏为主题文件 + `MEMORY.md` 索引。
|
||||
|
||||
## 记忆漂移防御
|
||||
|
||||
源码路径：`src/memdir/memoryTypes.ts`（`TRUSTING_RECALL_SECTION`）
|
||||
|
||||
记忆可能过期。系统在 Prompt 中设置了一个专门的 section "Before recommending from memory"：
|
||||
|
||||
```
|
||||
A memory that names a specific function, file, or flag is a claim
|
||||
that it existed *when the memory was written*. It may have been
|
||||
renamed, removed, or never merged. Before recommending it:
|
||||
|
||||
- If the memory names a file path: check the file exists.
|
||||
- If the memory names a function or flag: grep for it.
|
||||
```
|
||||
|
||||
这个 section 的标题经过 A/B 测试验证："Before recommending from memory"（行动导向）比 "Trusting what you recall"（抽象描述）效果好（3/3 vs 0/3）。
|
||||
|
||||
### 忽略记忆的严格语义
|
||||
|
||||
```
|
||||
If the user says to *ignore* or *not use* memory:
|
||||
proceed as if MEMORY.md were empty.
|
||||
Do not apply remembered facts, cite, compare against,
|
||||
or mention memory content.
|
||||
```
|
||||
|
||||
这解决了 AI 的一个常见反模式：用户说"忽略关于 X 的记忆"，AI 虽然正确识别了代码但仍然加上"不像记忆中说的 Y"——这不是"忽略"，而是"承认然后覆盖"。
|
||||
|
||||
## Session Memory 与压缩的联动
|
||||
|
||||
源码路径：`src/services/compact/sessionMemoryCompact.ts`
|
||||
|
||||
记忆系统与上下文压缩有深度集成。当 `tengu_session_memory` 和 `tengu_sm_compact` 两个 feature flag 同时开启时，压缩优先使用 Session Memory 而非传统摘要：
|
||||
|
||||
```typescript
|
||||
// sessionMemoryCompact.ts:57-61
|
||||
const DEFAULT_SM_COMPACT_CONFIG = {
|
||||
minTokens: 10_000, // 压缩后至少保留 10K token
|
||||
minTextBlockMessages: 5, // 至少保留 5 条文本消息
|
||||
maxTokens: 40_000, // 最多保留 40K token
|
||||
}
|
||||
```
|
||||
|
||||
SM-compact 不调用压缩 API（没有摘要模型），而是直接使用已有的 Session Memory 作为摘要——更快、更便宜、且不会丢失信息。
|
||||
252
docs/context/system-prompt.mdx
Normal file
252
docs/context/system-prompt.mdx
Normal file
@@ -0,0 +1,252 @@
|
||||
---
|
||||
title: "System Prompt 动态组装 - AI 工作记忆构建"
|
||||
description: "深入解析 Claude Code 的 System Prompt 动态组装过程：缓存策略、分界标记、Section 注册表、CLAUDE.md 多级合并，以及如何将零散上下文拼装为 API 可消费的缓存友好结构。"
|
||||
keywords: ["System Prompt", "系统提示词", "动态组装", "CLAUDE.md", "Prompt Cache", "缓存策略"]
|
||||
---
|
||||
|
||||
## 从数组到 API 调用：System Prompt 的完整链路
|
||||
|
||||
System Prompt 在 Claude Code 中不是一段写死的文本，而是一个 **`string[]` 数组**（品牌类型 `SystemPrompt`，定义于 `src/utils/systemPromptType.ts:8`），经过组装、分块、缓存标记后发送给 API。
|
||||
|
||||
### 三阶段管道
|
||||
|
||||
```
|
||||
getSystemPrompt() → string[] （组装内容）
|
||||
↓
|
||||
buildEffectiveSystemPrompt() → SystemPrompt （选择优先级路径）
|
||||
↓
|
||||
buildSystemPromptBlocks() → TextBlockParam[] （分块 + cache_control 标记）
|
||||
```
|
||||
|
||||
1. **`getSystemPrompt()`**（`src/constants/prompts.ts:444`）—— 收集静态段 + 动态段，插入 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 分界标记
|
||||
2. **`buildEffectiveSystemPrompt()`**（`src/utils/systemPrompt.ts:41`）—— 按 Override > Coordinator > Agent > Custom > Default 优先级选择
|
||||
3. **`buildSystemPromptBlocks()`**（`src/services/api/claude.ts:3214`）—— 调用 `splitSysPromptPrefix()` 分块，为每个块附加 `cache_control`
|
||||
|
||||
## SystemPrompt 品牌类型
|
||||
|
||||
```typescript
|
||||
// src/utils/systemPromptType.ts:8
|
||||
export type SystemPrompt = readonly string[] & {
|
||||
readonly __brand: 'SystemPrompt'
|
||||
}
|
||||
export function asSystemPrompt(value: readonly string[]): SystemPrompt {
|
||||
return value as SystemPrompt // 零开销类型断言
|
||||
}
|
||||
```
|
||||
|
||||
品牌类型（branded type）防止普通 `string[]` 被意外传入 API 调用——只有通过 `asSystemPrompt()` 显式转换才能获得 `SystemPrompt` 类型。
|
||||
|
||||
## getSystemPrompt()：内容组装的全景
|
||||
|
||||
`src/constants/prompts.ts:444` 是 System Prompt 的核心工厂函数，返回一个有序数组：
|
||||
|
||||
| 阶段 | 内容 | 缓存策略 |
|
||||
|------|------|----------|
|
||||
| **静态区** | Intro Section、System Rules、Doing Tasks、Actions、Using Tools、Tone & Style、Output Efficiency | 可跨组织缓存（`scope: 'global'`） |
|
||||
| **BOUNDARY** | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'` | 分界标记（不发送给 API） |
|
||||
| **动态区** | Session Guidance、Memory、Model Override、Env Info、Language、Output Style、MCP Instructions、Scratchpad、FRC、Summarize Tool Results、Token Budget、Brief | 每次会话不同（`scope: 'org'` 或无缓存） |
|
||||
|
||||
### 动态区的 Section 注册表
|
||||
|
||||
动态区通过 `systemPromptSection()` / `DANGEROUS_uncachedSystemPromptSection()` 注册，这两个工厂函数定义于 `src/constants/systemPromptSections.ts`：
|
||||
|
||||
```typescript
|
||||
// 缓存式 Section：计算一次，/clear 或 /compact 后才重新计算
|
||||
systemPromptSection('memory', () => loadMemoryPrompt())
|
||||
|
||||
// 危险：每轮重新计算，会破坏 Prompt Cache
|
||||
DANGEROUS_uncachedSystemPromptSection(
|
||||
'mcp_instructions',
|
||||
() => isMcpInstructionsDeltaEnabled() ? null : getMcpInstructionsSection(mcpClients),
|
||||
'MCP servers connect/disconnect between turns' // 必须给出破坏缓存的理由
|
||||
)
|
||||
```
|
||||
|
||||
`resolveSystemPromptSections()` 在每轮查询时解析所有 Section，对于 `cacheBreak: false` 的 Section，优先使用 `getSystemPromptSectionCache()` 中的缓存值。只有 MCP 指令等真正动态的内容使用 `DANGEROUS_uncachedSystemPromptSection`。
|
||||
|
||||
### `CLAUDE_CODE_SIMPLE` 快速路径
|
||||
|
||||
当环境变量 `CLAUDE_CODE_SIMPLE` 为真时，整个 System Prompt 缩减为一行：
|
||||
|
||||
```typescript
|
||||
`You are Claude Code, Anthropic's official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}`
|
||||
```
|
||||
|
||||
跳过所有 Section 注册、缓存分块、动态组装——用于最小化 token 消耗的测试场景。
|
||||
|
||||
## buildEffectiveSystemPrompt()：五级优先级
|
||||
|
||||
`src/utils/systemPrompt.ts:41` 决定最终使用哪个 System Prompt：
|
||||
|
||||
| 优先级 | 条件 | 行为 |
|
||||
|--------|------|------|
|
||||
| **0. Override** | `overrideSystemPrompt` 非空 | 完全替换，返回 `[override]` |
|
||||
| **1. Coordinator** | `COORDINATOR_MODE` feature + 环境变量 | 使用协调者专用提示词 |
|
||||
| **2. Agent** | `mainThreadAgentDefinition` 存在 | Proactive 模式：追加到默认提示词尾部；否则：替换默认提示词 |
|
||||
| **3. Custom** | `--system-prompt` 参数指定 | 替换默认提示词 |
|
||||
| **4. Default** | 无特殊条件 | 使用 `getSystemPrompt()` 完整输出 |
|
||||
|
||||
`appendSystemPrompt` 始终追加到末尾（Override 除外）。
|
||||
|
||||
## 缓存策略：分块、标记、命中
|
||||
|
||||
这是 System Prompt 设计中最精密的部分。
|
||||
|
||||
### Anthropic Prompt Cache 基础
|
||||
|
||||
Anthropic API 的 Prompt Cache 允许跨请求复用相同的 System Prompt 前缀，按缓存命中量计费（远低于完整输入价格）。缓存键由内容的 Blake2b 哈希决定——任何字符变化都会导致缓存失效。
|
||||
|
||||
### `splitSysPromptPrefix()`：三种分块模式
|
||||
|
||||
`src/utils/api.ts:321` 是缓存策略的核心，根据条件选择三种分块模式：
|
||||
|
||||
#### 模式 1：MCP 工具存在时（`skipGlobalCacheForSystemPrompt=true`）
|
||||
|
||||
```
|
||||
[attribution header] → cacheScope: null （不缓存）
|
||||
[system prompt prefix] → cacheScope: 'org' （组织级缓存）
|
||||
[everything else] → cacheScope: 'org' （组织级缓存）
|
||||
```
|
||||
|
||||
MCP 工具列表在会话中可能变化（连接/断开），破坏了跨组织缓存的基础，因此降级为组织级。
|
||||
|
||||
#### 模式 2：Global Cache + Boundary 存在（1P 专用）
|
||||
|
||||
```
|
||||
[attribution header] → cacheScope: null （不缓存）
|
||||
[system prompt prefix] → cacheScope: null （不缓存）
|
||||
[static content] → cacheScope: 'global' （全局缓存！跨组织共享）
|
||||
[dynamic content] → cacheScope: null （不缓存）
|
||||
```
|
||||
|
||||
这是缓存效率最高的模式。`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 之前的静态内容（Intro、Rules、Tone & Style 等）对所有用户相同，可跨组织缓存。
|
||||
|
||||
#### 模式 3：默认（3P 提供商 或 Boundary 缺失）
|
||||
|
||||
```
|
||||
[attribution header] → cacheScope: null （不缓存）
|
||||
[system prompt prefix] → cacheScope: 'org' （组织级缓存）
|
||||
[everything else] → cacheScope: 'org' （组织级缓存）
|
||||
```
|
||||
|
||||
### `getCacheControl()`：TTL 决策
|
||||
|
||||
`src/services/api/claude.ts:359` 生成的 `cache_control` 对象：
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'ephemeral',
|
||||
ttl?: '1h', // 仅特定 querySource 符合条件时
|
||||
scope?: 'global', // 仅静态区
|
||||
}
|
||||
```
|
||||
|
||||
1 小时 TTL 的判定逻辑（`should1hCacheTTL()`，第 394 行）：
|
||||
- **Bedrock 用户**：通过环境变量 `ENABLE_PROMPT_CACHING_1H_BEDROCK` 启用
|
||||
- **1P 用户**：通过 GrowthBook 配置的 `allowlist` 数组匹配 `querySource`，支持前缀通配符（如 `"repl_main_thread*"`）
|
||||
- **会话级锁定**：资格判定结果在 bootstrap state 中缓存，防止 GrowthBook 配置中途变化导致同一会话内 TTL 不一致
|
||||
|
||||
### 缓存破坏：Session-Specific Guidance 的放置
|
||||
|
||||
`getSessionSpecificGuidanceSection()`（`src/constants/prompts.ts:352`）的内容必须放在 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` **之后**。因为它包含：
|
||||
- 当前会话的 enabledTools 集合
|
||||
- `isForkSubagentEnabled()` 的运行时判定
|
||||
- `getIsNonInteractiveSession()` 的结果
|
||||
|
||||
这些运行时 bit 如果放在静态区，会产生 2^N 种 Blake2b 哈希变体（N = 运行时条件数），完全破坏缓存命中率。源码注释明确警告：
|
||||
|
||||
> Each conditional here is a runtime bit that would otherwise multiply the Blake2b prefix hash variants (2^N). See PR #24490, #24171 for the same bug class.
|
||||
|
||||
### `CLAUDE_CODE_SIMPLE` 模式
|
||||
|
||||
当设置了 `CLAUDE_CODE_SIMPLE` 环境变量时，整个系统提示词会大幅缩减：
|
||||
|
||||
```typescript
|
||||
return [`You are Claude Code, Anthropic's official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}`]
|
||||
```
|
||||
|
||||
## 上下文注入：System Context 与 User Context
|
||||
|
||||
System Prompt 数组本身不包含运行时上下文（git 状态、CLAUDE.md 内容）。上下文通过两个独立的管道注入：
|
||||
|
||||
### System Context（`src/context.ts:116`）
|
||||
|
||||
```typescript
|
||||
export const getSystemContext = memoize(async () => {
|
||||
return {
|
||||
gitStatus, // git 分支、状态、最近提交（截断至 MAX_STATUS_CHARS=2000）
|
||||
cacheBreaker, // 仅 ant 用户的缓存破坏器
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
- 使用 `lodash.memoize` 缓存——**整个会话期间只计算一次**
|
||||
- Git 状态快照包含 5 个并行 `git` 命令（branch、defaultBranch、status、log、userName）
|
||||
- `status` 超过 2000 字符时截断并附加提示使用 BashTool 获取更多信息
|
||||
- `systemPromptInjection` 变更时，通过 `getUserContext.cache.clear?.()` 清除所有上下文缓存
|
||||
|
||||
### User Context（`src/context.ts:155`）
|
||||
|
||||
```typescript
|
||||
export const getUserContext = memoize(async () => {
|
||||
return {
|
||||
claudeMd, // 合并后的 CLAUDE.md 内容
|
||||
currentDate, // "Today's date is YYYY-MM-DD."
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
- **CLAUDE.md 禁用条件**：`CLAUDE_CODE_DISABLE_CLAUDE_MDS` 环境变量，或 `--bare` 模式（除非通过 `--add-dir` 显式指定目录）
|
||||
- `--bare` 模式的语义是"跳过我没要求的东西"而非"忽略所有"
|
||||
|
||||
### 注入位置
|
||||
|
||||
在 `src/query.ts:449`：
|
||||
|
||||
```typescript
|
||||
// System Context 追加到 System Prompt 尾部
|
||||
const fullSystemPrompt = asSystemPrompt(
|
||||
appendSystemContext(systemPrompt, systemContext) // 简单拼接
|
||||
)
|
||||
```
|
||||
|
||||
User Context 通过 `prependUserContext()`（`src/utils/api.ts:449`）注入为 `<system-reminder>` 标签包裹的首条用户消息，放在所有对话消息之前。
|
||||
|
||||
## Attribution Header：计费与安全
|
||||
|
||||
每个 API 请求的 System Prompt 首块是 Attribution Header（`src/constants/system.ts:30`），包含：
|
||||
- **`cc_version`**：Claude Code 版本 + 指纹
|
||||
- **`cc_entrypoint`**：入口点标识（REPL / SDK / pipe 等）
|
||||
- **`cch=00000`**（NATIVE_CLIENT_ATTESTATION 启用时）：Bun 原生 HTTP 层在发送前将零替换为计算出的哈希值，服务器验证此 token 确认请求来自真实 Claude Code 客户端
|
||||
|
||||
Header 始终 `cacheScope: null`——它因版本和指纹不同而变化，不适合缓存。
|
||||
|
||||
## CLAUDE.md：项目级知识注入
|
||||
|
||||
这是 Claude Code 最巧妙的设计之一。在项目根目录放一个 `CLAUDE.md` 文件，就能让 AI "理解" 你的项目：
|
||||
|
||||
- **项目概述**：这个项目做什么、用了什么技术栈
|
||||
- **开发约定**：代码风格、命名规范、分支策略
|
||||
- **常用命令**：怎么构建、怎么测试、怎么部署
|
||||
- **注意事项**：已知的坑、特殊的配置
|
||||
|
||||
系统会自动发现并合并多级 CLAUDE.md：
|
||||
|
||||
```
|
||||
~/.claude/CLAUDE.md ← 用户全局（个人偏好）
|
||||
└── /project/CLAUDE.md ← 项目根目录（团队共享）
|
||||
└── /project/src/CLAUDE.md ← 子目录（模块特定）
|
||||
```
|
||||
|
||||
加载逻辑在 `src/utils/claudemd.ts` 中的 `getClaudeMds()` 和 `getMemoryFiles()` 实现——从 CWD 向上遍历目录树，合并所有匹配的 CLAUDE.md 文件内容。
|
||||
|
||||
## 设计洞察：为什么是 `string[]` 而非单个 `string`
|
||||
|
||||
将 System Prompt 设计为数组而非单段文本，是为了 **缓存分块**：
|
||||
|
||||
1. Anthropic Prompt Cache 以 **内容块**（TextBlock）为缓存单位
|
||||
2. 将 System Prompt 拆为多个块，可以让不变的部分（Intro、Rules）获得独立的缓存命中
|
||||
3. 如果是单个 `string`，任何一个字符变化（如日期更新）都会导致整个 System Prompt 的缓存失效
|
||||
4. `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记允许 `splitSysPromptPrefix()` 精确地将静态区标记为 `scope: 'global'`，动态区不标记或标记为 `scope: 'org'`
|
||||
|
||||
这是 Claude Code 在 token 成本优化上的核心设计——一次典型的 System Prompt 约 20K+ tokens，通过缓存分块可以节省 30-50% 的输入 token 费用。
|
||||
168
docs/context/token-budget.mdx
Normal file
168
docs/context/token-budget.mdx
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
title: "Token 预算管理 - 上下文窗口动态计算"
|
||||
description: "从源码角度揭示 Claude Code token 预算管理：200K 上下文窗口的动态计算、截断机制、缓存优化和自动压缩的完整链路。"
|
||||
keywords: ["Token 预算", "上下文窗口", "token 计算", "截断机制", "缓存优化"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 token 预算的动态计算、截断机制、缓存优化和自动压缩的完整链路 */}
|
||||
|
||||
## 上下文窗口：200K 不是全部
|
||||
|
||||
Claude Code 的默认上下文窗口为 200K tokens（`MODEL_CONTEXT_WINDOW_DEFAULT = 200_000`），但实际可用于对话的空间远小于此：
|
||||
|
||||
```
|
||||
上下文窗口（200K）
|
||||
├── 系统提示词（~15-25K，缓存后成本低）
|
||||
├── 工具定义（~10-20K，含 MCP 工具）
|
||||
├── 用户上下文（CLAUDE.md、git status 等）
|
||||
├── 输出预留（maxOutputTokens）
|
||||
│ ├── 默认上限：64K
|
||||
│ ├── 实际默认：8K（slot-reservation 优化）
|
||||
│ └── 触顶自动升级：一次 64K 重试
|
||||
└── 剩余：对话历史空间（随对话增长）
|
||||
```
|
||||
|
||||
`getContextWindowForModel()`（`src/utils/context.ts:51`）按 5 级优先级解析窗口大小：
|
||||
|
||||
1. `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 环境变量覆盖
|
||||
2. 模型名含 `[1m]` 后缀 → 1M tokens
|
||||
3. `getModelCapability(model).max_input_tokens`
|
||||
4. 1M beta header + 支持的模型（claude-sonnet-4, opus-4-6）
|
||||
5. 兜底：200K
|
||||
|
||||
**有效上下文** = 窗口大小 - min(maxOutputTokens, 20K)，因为压缩摘要需要预留输出空间。
|
||||
|
||||
## Token 计数：近似 vs 精确
|
||||
|
||||
系统使用两级 token 计数策略：
|
||||
|
||||
### 近似估算（毫秒级）
|
||||
|
||||
```typescript
|
||||
// src/services/tokenEstimation.ts
|
||||
function roughTokenCountEstimation(content: string, bytesPerToken = 4): number {
|
||||
return Math.round(content.length / bytesPerToken)
|
||||
}
|
||||
```
|
||||
|
||||
对不同内容类型有特殊处理：
|
||||
- **JSON/JSONL**：`bytesPerToken = 2`（密集的 `{`, `:`, `,` 符号，每个仅 1-2 token）
|
||||
- **图片/文档**：固定 2000 tokens（基于 2000×2000px 上限的保守估计）
|
||||
- **thinking block**：按实际文本长度 / 4
|
||||
- **tool_use**：序列化 `name + JSON.stringify(input)` 后 / 4
|
||||
|
||||
### 精确计数（API 调用）
|
||||
|
||||
使用 Anthropic 的 `beta.messages.countTokens` 端点。在不同 provider 上有不同路径：
|
||||
|
||||
| Provider | 方法 |
|
||||
|----------|------|
|
||||
| Anthropic 直连 | `anthropic.beta.messages.countTokens()` |
|
||||
| AWS Bedrock | `@aws-sdk/client-bedrock-runtime` 的 `CountTokensCommand` |
|
||||
| Google Vertex | Anthropic SDK + beta 过滤 |
|
||||
| 兜底（Bedrock 不支持） | 用 Haiku 发送 `max_tokens=1` 的请求，读取 `usage.input_tokens` |
|
||||
|
||||
精确计数在关键决策点使用（压缩前后对比、warning 判断），近似估算在热路径使用（每轮循环的 shouldAutoCompact 检查）。
|
||||
|
||||
## 自动压缩的触发阈值
|
||||
|
||||
```
|
||||
src/services/compact/autoCompact.ts — 核心阈值
|
||||
```
|
||||
|
||||
| 常量 | 值 | 含义 |
|
||||
|------|----|------|
|
||||
| `AUTOCOMPACT_BUFFER_TOKENS` | 13,000 | 窗口减去此值 = 自动压缩触发点 |
|
||||
| `WARNING_THRESHOLD_BUFFER_TOKENS` | 20,000 | 在触发点 + 20K 处显示警告 |
|
||||
| `ERROR_THRESHOLD_BUFFER_TOKENS` | 20,000 | 在触发点 + 20K 处显示错误 |
|
||||
| `MANUAL_COMPACT_BUFFER_TOKENS` | 3,000 | 手动 /compact 的阻塞上限 |
|
||||
| `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES` | 3 | 连续失败 3 次后停止尝试 |
|
||||
|
||||
以 200K 窗口为例：
|
||||
- **~167K**：warning 闪烁，用户看到建议压缩的提示
|
||||
- **~180K**：自动压缩触发（200K - 20K 输出预留 = 180K 有效，再 - 13K buffer）
|
||||
- **~197K**：达到 blocking limit，新消息被阻止
|
||||
|
||||
`shouldAutoCompact()` 有多个逃逸条件：
|
||||
- `compact` / `session_memory` 来源的查询永不触发（防递归死锁）
|
||||
- `DISABLE_COMPACT` / `DISABLE_AUTO_COMPACT` 环境变量
|
||||
- 用户配置 `autoCompactEnabled = false`
|
||||
- Context Collapse 模式激活时抑制（collapse 自己管理上下文）
|
||||
- Reactive Compact 实验模式下抑制主动压缩
|
||||
- 超过连续失败上限（circuit breaker）
|
||||
|
||||
## Micro-Compact：工具结果的渐进式压缩
|
||||
|
||||
在触发全量压缩之前，系统先尝试 **micro-compact**——只压缩旧的工具调用结果：
|
||||
|
||||
```
|
||||
可压缩工具列表（COMPACTABLE_TOOLS）：
|
||||
FileRead, Bash, Grep, Glob, WebSearch, WebFetch, FileEdit, FileWrite
|
||||
```
|
||||
|
||||
策略基于时间：
|
||||
- 超过一定时间（由 `timeBasedMCConfig` 控制）的工具结果被替换为简短占位符
|
||||
- 图片/文档结果替换为 `[image]` / `[document]` 文本
|
||||
- 每次替换释放 tokens，可能推迟全量压缩
|
||||
|
||||
工具本身也有 `maxResultSizeChars`（通常 100K）硬限制，超长结果在写入消息前就被截断。
|
||||
|
||||
## 全量压缩的完整流程
|
||||
|
||||
```
|
||||
autoCompactIfNeeded() / compactConversation()
|
||||
↓
|
||||
1. 执行 PreCompact hooks（外部可注入自定义指令）
|
||||
↓
|
||||
2. 尝试 Session Memory 压缩（更轻量，优先尝试）
|
||||
↓
|
||||
3. Session Memory 失败 → 全量压缩
|
||||
a. 图片/文档从消息中剥离（替换为 [image]/[document]）
|
||||
b. skill_discovery/skill_listing 附件剥离（压缩后会重新注入）
|
||||
c. 通过 forked agent 发送摘要请求（复用主线程的 prompt cache）
|
||||
d. 如果摘要请求本身触发 prompt-too-long → truncateHeadForPTLRetry()
|
||||
从最老的 API 轮次开始删除，重试最多 3 次
|
||||
↓
|
||||
4. 压缩成功后重建上下文：
|
||||
- compactBoundaryMarker（记录压缩类型、前 token 数等）
|
||||
- 摘要消息（不可见的 user 消息）
|
||||
- 最近 5 个文件的重新读取（POST_COMPACT_TOKEN_BUDGET = 50K）
|
||||
- plan 文件附件（如果有）
|
||||
- plan mode 指令（如果在计划模式中）
|
||||
- 已调用的 skill 内容（每 skill ≤5K，总计 ≤25K）
|
||||
- deferred tools / agent listing / MCP 指令的增量重新注入
|
||||
- SessionStart hooks 重新执行
|
||||
- PostCompact hooks 执行
|
||||
↓
|
||||
5. 更新缓存基线，防止被误判为 cache break
|
||||
```
|
||||
|
||||
### Prompt Cache Sharing
|
||||
|
||||
压缩 API 调用是整个会话中最昂贵的操作之一。系统通过 `runForkedAgent` 复用主线程的缓存前缀（system prompt + tools + context messages），将缓存命中率从 2% 提升到接近 100%。这个优化单独节省了舰队级约 0.76% 的 `cache_creation` tokens。
|
||||
|
||||
## 输出 Token 的 Slot 优化
|
||||
|
||||
一个经常被忽视的优化：**maxOutputTokens 的动态调整**。
|
||||
|
||||
```typescript
|
||||
// src/services/api/claude.ts — getMaxOutputTokensForModel()
|
||||
const defaultTokens = isMaxTokensCapEnabled()
|
||||
? Math.min(maxOutputTokens.default, 8_000) // 默认降到 8K
|
||||
: maxOutputTokens.default // 原始默认 32K/64K
|
||||
```
|
||||
|
||||
为什么？因为 API 的 slot 机制按 `max_tokens` 预留推理容量。BQ p99 输出仅 4,911 tokens，32K 默认值浪费了 8-16 倍的 slot 容量。降到 8K 后，不到 1% 的请求被截断——这些请求会自动获得一次 64K 的 clean retry。
|
||||
|
||||
这个优化对 token 预算的影响是间接的：更多的 slot 容量意味着更少的排队延迟，间接减少了超时和重试。
|
||||
|
||||
## Partial Compact：选择性地压缩
|
||||
|
||||
除了全量压缩，用户还可以在消息历史中选择某个位置，只压缩该位置之前或之后的内容：
|
||||
|
||||
- **`up_to` 方向**：压缩选中消息之前的内容，保留最近的对话
|
||||
- **`from` 方向**：压缩选中消息之后的内容，保留早期的对话
|
||||
|
||||
`from` 方向保留 prompt cache（前缀不变），`up_to` 方向则破坏 cache（摘要插在保留内容之前）。
|
||||
|
||||
两种方向的 PTL（prompt-too-long）重试策略相同：从最老的 API 轮次开始删除，确保至少保留一组消息供摘要。
|
||||
184
docs/conversation/multi-turn.mdx
Normal file
184
docs/conversation/multi-turn.mdx
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: "多轮对话管理 - QueryEngine 会话编排与持久化"
|
||||
description: "从源码角度解析 Claude Code 多轮对话管理：QueryEngine 的会话状态机、JSONL transcript 持久化、成本追踪模型和模型热切换机制。"
|
||||
keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
|
||||
|
||||
## 单轮 vs 多轮：架构层面的差异
|
||||
|
||||
- **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
|
||||
- **多轮**（一个 Session）：`QueryEngine` 类管理的一次会话——跨越数十轮 `submitMessage()` 调用，持续数小时
|
||||
|
||||
`QueryEngine`（`src/QueryEngine.ts:186`）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
|
||||
|
||||
```
|
||||
QueryEngine 内部状态
|
||||
├── mutableMessages: Message[] ← 完整对话历史，跨 turn 累积
|
||||
├── readFileState: FileStateCache ← 已读文件内容缓存，避免重复读取
|
||||
├── totalUsage: NonNullableUsage ← 累计 token 消耗（input/output/cache）
|
||||
├── permissionDenials: SDKPermissionDenial[] ← 权限拒绝记录
|
||||
├── discoveredSkillNames: Set<string> ← 当前 turn 已发现的 skill
|
||||
└── abortController: AbortController ← 会话级中断控制
|
||||
```
|
||||
|
||||
## QueryEngine 的核心方法：submitMessage()
|
||||
|
||||
每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
|
||||
|
||||
```typescript
|
||||
// src/QueryEngine.ts:211 — 简化的 submitMessage 流程
|
||||
async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
|
||||
// 1. 清除 turn 级追踪状态
|
||||
this.discoveredSkillNames.clear()
|
||||
|
||||
// 2. 解析模型（用户可能中途切换了模型）
|
||||
const mainLoopModel = userSpecifiedModel
|
||||
? parseUserSpecifiedModel(userSpecifiedModel)
|
||||
: getMainLoopModel()
|
||||
|
||||
// 3. 动态组装 System Prompt（每次 turn 都重新构建）
|
||||
const { defaultSystemPrompt, userContext, systemContext } =
|
||||
await fetchSystemPromptParts({ tools, mainLoopModel, mcpClients })
|
||||
|
||||
// 4. 包装权限检查（追踪每次拒绝）
|
||||
const wrappedCanUseTool = async (tool, input, ...) => {
|
||||
const result = await canUseTool(tool, input, ...)
|
||||
if (result.behavior !== 'allow') {
|
||||
this.permissionDenials.push({ tool_name: tool.name, ... })
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
// 5. 调用核心 query() 函数执行 agentic loop
|
||||
yield* query({
|
||||
systemPrompt, messages: this.mutableMessages,
|
||||
tools, model: mainLoopModel, ...
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
关键设计：`submitMessage()` 是 `async *Generator`——它逐步 yield `SDKMessage`，让调用方（REPL/SDK）能实时展示进度，而不是等整个 turn 结束。
|
||||
|
||||
## 会话持久化：JSONL Transcript
|
||||
|
||||
每次对话事件都被追加写入 transcript 文件（`src/utils/sessionStorage.ts`）：
|
||||
|
||||
### 存储路径
|
||||
|
||||
```
|
||||
~/.claude/projects/<project-hash>/<session-id>.jsonl
|
||||
```
|
||||
|
||||
- `project-hash` 由 `getProjectDir(originalCwd)` 生成，同一项目目录的会话归入同一子目录
|
||||
- 每条记录是一行 JSON（JSONL 格式），支持追加写入而不需要读取-修改-写入整个文件
|
||||
- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES`），防止超大会话导致 OOM
|
||||
|
||||
### Transcript 写入器
|
||||
|
||||
`TranscriptWriter`（`src/utils/sessionStorage.ts:1200+`）是一个写队列，确保并发的消息追加不会互相覆盖：
|
||||
|
||||
```
|
||||
写入流程：
|
||||
appendEntryToFile(sessionId, entry)
|
||||
↓
|
||||
ensureCurrentSessionFile() ← 懒初始化：首次写入时才创建文件
|
||||
↓
|
||||
序列化为 JSON + 换行符
|
||||
↓
|
||||
appendFile(path, line) ← 原子追加
|
||||
↓
|
||||
如果配置了远程持久化：
|
||||
persistToRemote(sessionId, entry)
|
||||
├── CCR v2: internalEventWriter('transcript', entry)
|
||||
└── v1 Ingress: sessionIngress.appendSessionLog(...)
|
||||
```
|
||||
|
||||
### 会话恢复链路
|
||||
|
||||
`--resume` 参数触发的恢复流程（`src/main.tsx:3620+`）：
|
||||
|
||||
```
|
||||
1. 解析 resume 参数：
|
||||
├── UUID 格式 → getTranscriptPathForSession(uuid)
|
||||
├── .jsonl 文件路径 → 直接使用
|
||||
└── boolean → 最近一次会话的 picker
|
||||
|
||||
2. loadTranscriptFromFile(path)
|
||||
├── 按 JSONL 行解析
|
||||
├── 过滤出消息类型记录
|
||||
└── 重建 Message[] 数组
|
||||
|
||||
3. 恢复上下文状态：
|
||||
├── restoreCostStateForSession(sessionId) ← 恢复累计费用
|
||||
├── 恢复 agentSetting（用户选择的 Agent 类型）
|
||||
└── 如果有 --rewind-files，恢复文件到指定消息时的快照
|
||||
|
||||
4. 创建 QueryEngine({ initialMessages: restoredMessages })
|
||||
└── 从恢复的消息继续对话
|
||||
```
|
||||
|
||||
## 成本追踪：从 API Usage 到美元
|
||||
|
||||
成本追踪贯穿三个模块，形成完整的记录→累计→展示链路：
|
||||
|
||||
### 记录层：API 响应中的 Usage
|
||||
|
||||
每个 `message_delta` 事件携带 `usage` 字段（`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens`）。`accumulateUsage()` 将增量 usage 累加到会话总量。
|
||||
|
||||
### 累计层：cost-tracker.ts
|
||||
|
||||
```typescript
|
||||
// src/cost-tracker.ts — StoredCostState 数据模型
|
||||
type StoredCostState = {
|
||||
totalCostUSD: number // 累计美元花费
|
||||
totalAPIDuration: number // API 调用总时长（含重试）
|
||||
totalAPIDurationWithoutRetries: number // 不含重试的纯推理时间
|
||||
totalToolDuration: number // 工具执行总时长
|
||||
totalLinesAdded: number // 代码增加行数
|
||||
totalLinesRemoved: number // 代码删除行数
|
||||
modelUsage: { [modelName: string]: ModelUsage } // 按模型分拆的用量
|
||||
}
|
||||
```
|
||||
|
||||
`addToTotalSessionCost()` 根据模型定价计算每次 API 调用的费用，累计到 `totalCostUSD`。按模型的 `ModelUsage` 支持在同一会话中切换模型后分别统计。
|
||||
|
||||
### 持久化：跨重启保留
|
||||
|
||||
```typescript
|
||||
// 每次会话结束时保存到项目配置
|
||||
saveCurrentSessionCosts(sessionId)
|
||||
→ projectConfig.lastCost = totalCostUSD
|
||||
→ projectConfig.lastSessionId = sessionId
|
||||
→ projectConfig.lastModelUsage = modelUsage
|
||||
```
|
||||
|
||||
### 预算熔断
|
||||
|
||||
`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx:2208`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"。
|
||||
|
||||
## 模型热切换
|
||||
|
||||
在一个会话中切换模型不会丢失对话历史——因为 `mutableMessages` 与模型选择是解耦的：
|
||||
|
||||
```
|
||||
/model sonnet → setMainLoopModelOverride('claude-sonnet-4-20250514')
|
||||
↓
|
||||
下一次 submitMessage() 开始时：
|
||||
↓
|
||||
parseUserSpecifiedModel(userSpecifiedModel)
|
||||
→ 返回新的模型配置
|
||||
↓
|
||||
fetchSystemPromptParts({ mainLoopModel: newModel })
|
||||
→ System Prompt 根据新模型能力重新组装
|
||||
↓
|
||||
query({ model: newModel, messages: this.mutableMessages })
|
||||
→ 使用完整历史 + 新模型继续对话
|
||||
```
|
||||
|
||||
切换模型时，`contextWindowTokens` 和 `maxOutputTokens` 也会根据新模型的规格重新计算——例如从 Sonnet 切换到 Opus 时，上下文窗口可能从 200K 变为 1M。
|
||||
|
||||
## 文件快照与回滚
|
||||
|
||||
`fileHistoryMakeSnapshot()`（`src/utils/fileHistory.ts`）在 AI 每次修改文件前自动保存当前内容。快照绑定到具体的 `message.id`，使得 `--rewind-files <user-message-id>` 可以精确恢复到对话中任意时间点的文件状态——这比 git 更细粒度（git 只追踪已提交的内容）。
|
||||
183
docs/conversation/streaming.mdx
Normal file
183
docs/conversation/streaming.mdx
Normal file
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: "流式响应机制 - Claude Code 打字机效果原理"
|
||||
description: "解析 Claude Code 流式响应实现：如何通过 SSE 逐 token 接收 AI 输出，实现实时打字机效果，提升用户等待体验。"
|
||||
keywords: ["流式响应", "SSE", "streaming", "实时输出", "API streaming"]
|
||||
---
|
||||
|
||||
## 为什么需要流式
|
||||
|
||||
想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
|
||||
|
||||
流式响应让用户**实时看到 AI 的思考过程**：
|
||||
- 文字逐字出现，用户能提前判断方向是否正确
|
||||
- 工具调用的参数在生成过程中就能预览
|
||||
- 长时间任务不会让用户觉得"卡死了"
|
||||
|
||||
## `BetaRawMessageStreamEvent` 核心事件类型
|
||||
|
||||
流式 API 返回的是一系列 `BetaRawMessageStreamEvent`，每种事件类型对应流式响应的不同阶段（`src/services/api/claude.ts`）：
|
||||
|
||||
```
|
||||
message_start ← 消息开始，包含 model、usage 初始值
|
||||
├── content_block_start ← 内容块开始（text / tool_use / thinking）
|
||||
│ ├── content_block_delta ← 增量数据（text_delta / input_json_delta / thinking_delta）
|
||||
│ ├── content_block_delta ← ... 持续到达
|
||||
│ └── content_block_stop ← 内容块结束，yield AssistantMessage
|
||||
├── content_block_start ← 下一个内容块...
|
||||
│ └── ...
|
||||
└── message_delta ← stop_reason + 最终 usage
|
||||
message_stop ← 消息结束
|
||||
```
|
||||
|
||||
### 事件处理状态机
|
||||
|
||||
`src/services/api/claude.ts:1980-2298` 实现了一个基于 `switch(part.type)` 的状态机：
|
||||
|
||||
| 事件类型 | 处理逻辑 | 状态变更 |
|
||||
|----------|----------|----------|
|
||||
| `message_start` | 初始化 `partialMessage`，记录 TTFT（首字节延迟） | `usage` 初始化 |
|
||||
| `content_block_start` | 按 `part.index` 创建对应类型的内容块 | `contentBlocks[index]` 初始化 |
|
||||
| `content_block_delta` | 按子类型增量追加数据 | text / thinking / input 累加 |
|
||||
| `content_block_stop` | 构建完整 `AssistantMessage` 并 yield | 消息推入 `newMessages` |
|
||||
| `message_delta` | 更新 stop_reason 和最终 usage | 写回最后一条消息 |
|
||||
| `message_stop` | 无操作（流结束标记） | — |
|
||||
|
||||
### 内容块类型及其增量数据
|
||||
|
||||
`content_block_start` 中的 `content_block.type` 决定了如何处理后续 delta：
|
||||
|
||||
| 内容块类型 | Delta 类型 | 累加逻辑 |
|
||||
|-----------|-----------|----------|
|
||||
| `text` | `text_delta` | `text += delta.text` |
|
||||
| `thinking` | `thinking_delta` + `signature_delta` | `thinking += delta.thinking`，`signature = delta.signature` |
|
||||
| `tool_use` | `input_json_delta` | `input += delta.partial_json`（JSON 字符串增量拼接） |
|
||||
| `server_tool_use` | `input_json_delta` | 同 tool_use |
|
||||
| `connector_text` | `connector_text_delta` | 特殊连接器文本（feature flag 控制） |
|
||||
|
||||
关键设计：`content_block_start` 时所有文本字段初始化为空字符串，只通过 `content_block_delta` 累加。这是因为 SDK 有时在 start 和 delta 中重复发送相同文本。
|
||||
|
||||
## 文本 chunk 和 tool_use block 的交织
|
||||
|
||||
一次 AI 响应可能包含多个内容块，交替出现：
|
||||
|
||||
```
|
||||
content_block_start (text, index=0) "我来帮你修复这个 bug。"
|
||||
content_block_delta (text_delta) "首先..."
|
||||
content_block_stop (index=0)
|
||||
content_block_start (tool_use, index=1) { name: "Read", input: "..." }
|
||||
content_block_delta (input_json_delta) '{"file_p' → 'ath":' → '"src/foo.ts"}'
|
||||
content_block_stop (index=1)
|
||||
content_block_start (text, index=2) "我已经看到了问题所在..."
|
||||
content_block_stop (index=2)
|
||||
```
|
||||
|
||||
每个 `content_block_stop` 触发一次 `yield`，将完整的 AssistantMessage 推送给消费者。这意味着一个 AI 响应会产生**多条** `AssistantMessage`——文本消息和工具调用消息交替产出。
|
||||
|
||||
`stop_reason` 要等到 `message_delta` 才确定（可能是 `end_turn`、`tool_use`、`max_tokens` 等），所以最后一条消息的 `stop_reason` 是**回写**的：
|
||||
|
||||
```typescript
|
||||
// claude.ts:2246 — 直接属性修改，不用对象替换
|
||||
// 因为 transcript 写队列持有 message.message 的引用
|
||||
const lastMsg = newMessages.at(-1)
|
||||
if (lastMsg) {
|
||||
lastMsg.message.usage = usage
|
||||
lastMsg.message.stop_reason = stopReason
|
||||
}
|
||||
```
|
||||
|
||||
## 流式中的错误处理
|
||||
|
||||
### 网络断开
|
||||
|
||||
流式连接依赖 SSE（Server-Sent Events）。当连接中断时：
|
||||
|
||||
1. **Stream idle watchdog**：定时检测事件间隔，超过阈值（stall）触发告警和重试
|
||||
2. **Stream abort**：如果 watchdog 检测到长时间无事件，抛出错误进入重试流程
|
||||
3. **非流式降级**：作为最后手段，回退到非流式请求（一次性获取完整响应）
|
||||
|
||||
```typescript
|
||||
// claude.ts:2338-2355 — 检测空流
|
||||
// 1. 完全没有事件 → 代理返回了非 SSE 响应
|
||||
// 2. 有 message_start 但没有 content_block_stop → 流被截断
|
||||
```
|
||||
|
||||
### API 限流
|
||||
|
||||
当 API 返回限流错误时，系统使用 `withRetry` 包装器进行指数退避重试。重试逻辑考虑了：
|
||||
- 错误类型（429 限流 vs 500 服务器错误）
|
||||
- 重试次数上限
|
||||
- 退避间隔
|
||||
|
||||
### Token 超限
|
||||
|
||||
两种 token 超限场景有不同的处理：
|
||||
|
||||
| 场景 | stop_reason | 处理方式 |
|
||||
|------|------------|----------|
|
||||
| **输出超限** | `max_tokens` | 生成错误消息，建议设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` |
|
||||
| **上下文窗口超限** | `model_context_window_exceeded` | 触发 compaction 压缩对话历史后重试 |
|
||||
|
||||
```typescript
|
||||
// claude.ts:2267-2293
|
||||
if (stopReason === 'max_tokens') {
|
||||
yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
|
||||
}
|
||||
if (stopReason === 'model_context_window_exceeded') {
|
||||
// 复用 max_output_tokens 的恢复路径
|
||||
yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
|
||||
}
|
||||
```
|
||||
|
||||
### 流式停滞检测
|
||||
|
||||
系统持续监控事件到达间隔，检测"停滞"（stall）：
|
||||
|
||||
```typescript
|
||||
// claude.ts:1940-1966
|
||||
const STALL_THRESHOLD_MS = 10_000 // 10 秒无事件视为停滞
|
||||
if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
|
||||
stallCount++
|
||||
totalStallTime += timeSinceLastEvent
|
||||
logEvent('tengu_streaming_stall', { stall_duration_ms, stall_count, ... })
|
||||
}
|
||||
```
|
||||
|
||||
多个 stall 累积后，watchdog 可能决定中断流并触发重试。
|
||||
|
||||
## 工具执行的流式反馈
|
||||
|
||||
BashTool 的命令执行也是流式的——通过 `onProgress` 回调逐行推送输出：
|
||||
|
||||
```
|
||||
BashTool.call() → runShellCommand() → AsyncGenerator
|
||||
├── 每秒轮询输出文件 → onProgress(lastLines, allLines, ...)
|
||||
├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
|
||||
└── return { code, stdout, interrupted, ... }
|
||||
```
|
||||
|
||||
UI 层通过 `useToolCallProgress` hook 实时展示命令输出，而不是等命令完全结束。长时间运行的命令还支持自动后台化（`shouldAutoBackground`）。
|
||||
|
||||
## 多 Provider 适配
|
||||
|
||||
| Provider | 流式协议 | 特殊处理 |
|
||||
|----------|----------|----------|
|
||||
| **Anthropic Direct** | 原生 SSE | 延迟最低，TTFT 最快 |
|
||||
| **AWS Bedrock** | AWS SDK 流式接口 | 需要额外的 beta header 和认证 |
|
||||
| **Google Vertex** | gRPC → 事件流 | 通过 `getMergedBetas()` 适配 |
|
||||
| **Azure** | Anthropic 兼容 API | 自定义 base URL |
|
||||
|
||||
所有 Provider 通过统一的 `Stream<BetaRawMessageStreamEvent>` 抽象层屏蔽差异。上层代码（QueryEngine、REPL）不需要关心底层用的是哪个 Provider。
|
||||
|
||||
### Provider 选择
|
||||
|
||||
`src/utils/model/providers.ts` 中的 `getAPIProvider()` 根据配置决定使用哪个 Provider：
|
||||
|
||||
```typescript
|
||||
// 根据 api_provider 配置选择：
|
||||
// "anthropic" → 直连
|
||||
// "bedrock" → AWS SDK
|
||||
// "vertex" → Google SDK
|
||||
// 第三方 base URL → 自动检测
|
||||
```
|
||||
|
||||
每个 Provider 需要适配的细节包括：认证方式、beta header、请求参数格式、错误码映射——但这些差异在 `claude.ts` 的 `queryStream()` 函数中被统一处理。
|
||||
182
docs/conversation/the-loop.mdx
Normal file
182
docs/conversation/the-loop.mdx
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "Agentic Loop：AI 自主循环的核心机制"
|
||||
description: "深入解析 Claude Code 的 query() 异步生成器循环——从流式 API 调用、工具并行执行、上下文压缩、错误恢复到终止条件的完整状态机，基于 src/query.ts 的源码级分析。"
|
||||
keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact", "streaming", "recovery"]
|
||||
---
|
||||
|
||||
{/* 本章目标：基于 src/query.ts 揭示 Agentic Loop 的完整状态机 */}
|
||||
|
||||
## 什么是 Agentic Loop
|
||||
|
||||
传统聊天机器人：你问一句，它答一句。
|
||||
Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
|
||||
|
||||
这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
|
||||
|
||||
<Frame caption="Agentic Loop 循环示意">
|
||||
<img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
|
||||
</Frame>
|
||||
|
||||
## 循环的完整结构
|
||||
|
||||
`queryLoop()` 的每次迭代（`src/query.ts:307` `while(true)`）包含以下阶段：
|
||||
|
||||
### 阶段 1：上下文预处理（Pre-Processing Pipeline）
|
||||
|
||||
在调用 API 之前，依次执行 5 个压缩/优化步骤：
|
||||
|
||||
```
|
||||
messagesForQuery（原始消息）
|
||||
↓ applyToolResultBudget() — 工具结果预算截断（按 maxResultSizeChars）
|
||||
↓ snipCompactIfNeeded() — 历史 Snip 压缩（HISTORY_SNIP feature）
|
||||
↓ microcompact() — 微压缩（工具结果摘要）
|
||||
↓ applyCollapsesIfNeeded() — 上下文折叠（CONTEXT_COLLAPSE feature）
|
||||
↓ autocompact() — 自动压缩（超出阈值时触发）
|
||||
messagesForQuery（处理后的消息）→ 发往 API
|
||||
```
|
||||
|
||||
每个步骤的输出是下一步的输入，形成串行管道。Snip 和 Microcompact 的释放 token 数会传递给 autocompact 的阈值计算（`snipTokensFreed`），避免重复压缩。
|
||||
|
||||
### 阶段 2：流式 API 调用（Streaming Loop）
|
||||
|
||||
`deps.callModel()` 发起流式请求（第 659 行），返回一个 AsyncGenerator。在流式过程中：
|
||||
|
||||
- **AssistantMessage** 被收集到 `assistantMessages[]` 数组
|
||||
- **tool_use 块** 被提取到 `toolUseBlocks[]`，设置 `needsFollowUp = true`
|
||||
- **StreamingToolExecutor** 在流式过程中就开始并行执行工具（不等流结束）
|
||||
- 可恢复的错误（prompt-too-long、max-output-tokens）被**暂扣**（withheld），先尝试恢复
|
||||
|
||||
流式回调中的关键守卫：
|
||||
- `backfillObservableInput()`（第 763 行）—— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
|
||||
- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone（第 717 行），清空后重试
|
||||
|
||||
### 阶段 3：工具执行（Tool Execution）
|
||||
|
||||
如果 `needsFollowUp` 为 true，循环不会终止，而是执行工具：
|
||||
|
||||
```typescript
|
||||
// 两种工具执行器（互斥）
|
||||
const toolUpdates = streamingToolExecutor
|
||||
? streamingToolExecutor.getRemainingResults() // 流式：获取已完成的+等待中的
|
||||
: runTools(toolUseBlocks, assistantMessages, canUseTool, toolUseContext)
|
||||
```
|
||||
|
||||
工具结果通过 `normalizeMessagesForAPI()` 标准化后，与原始消息合并，进入**下一轮循环迭代**。
|
||||
|
||||
### 阶段 4：终止或继续
|
||||
|
||||
每次迭代结束时，根据条件决定 `return`（终止）或 `continue`（继续）：
|
||||
|
||||
## 7 种终止条件（源码级）
|
||||
|
||||
| 终止原因 | 触发位置 | 机制 |
|
||||
|----------|---------|------|
|
||||
| **completed** | 第 1360 行 | AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
|
||||
| **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
|
||||
| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted` → 为未完成的 tool_use 生成合成 tool_result → 返回 |
|
||||
| **model_error** | 第 999 行 | `callModel()` 抛出异常 → 生成错误消息 → 返回 |
|
||||
| **prompt_too_long** | 第 1178 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
|
||||
| **image_error** | 第 980/1178 行 | 图片尺寸/大小错误 → 直接返回 |
|
||||
| **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
|
||||
|
||||
## 4 种继续条件（恢复路径）
|
||||
|
||||
循环不仅是一个简单的"有 tool_use 就继续"，它还包含多种恢复/重试路径：
|
||||
|
||||
### 1. 正常工具循环
|
||||
`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → `continue`
|
||||
|
||||
### 2. max_output_tokens 恢复（第 1191-1255 行）
|
||||
当 AI 输出被截断时（`apiError === 'max_output_tokens'`）：
|
||||
- **首次**：尝试将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K），无 meta 消息，静默重试
|
||||
- **后续**：注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次
|
||||
- 恢复耗尽后，暂扣的错误消息被释放
|
||||
|
||||
### 3. Prompt-Too-Long 恢复（第 1088-1186 行）
|
||||
当遇到 413 错误时，有两个恢复阶段：
|
||||
- **Context Collapse Drain**（第 1097 行）：提交所有已暂存的折叠，释放空间后重试。如果上一轮已经是 collapse_drain_retry 则跳过
|
||||
- **Reactive Compact**（第 1123 行）：触发即时压缩，生成摘要后重试。`hasAttemptedReactiveCompact` 防止无限循环
|
||||
|
||||
### 4. Stop Hook 阻塞重试（第 1285-1308 行）
|
||||
Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息（包含阻塞错误）被追加到对话中，`stopHookActive = true`，进入下一轮迭代。
|
||||
|
||||
## 模型降级（Fallback）
|
||||
|
||||
当主模型不可用时（`FallbackTriggeredError`，第 897 行）：
|
||||
|
||||
1. 已收集的 `assistantMessages` 被清空，tool_use 块收到合成 tool_result："Model fallback triggered"
|
||||
2. 思维签名块被移除（`stripSignatureBlocks`）—— 因为思维签名与模型绑定，跨模型回放会 400
|
||||
3. 切换到 `fallbackModel`，更新 `toolUseContext.options.mainLoopModel`
|
||||
4. 生成系统消息："Switched to {fallback} due to high demand for {original}"
|
||||
5. 重新发起流式请求
|
||||
|
||||
## 状态机：State 对象
|
||||
|
||||
每次迭代的状态通过 `State` 类型（第 204 行）传递：
|
||||
|
||||
```typescript
|
||||
type State = {
|
||||
messages: Message[] // 当前对话消息
|
||||
toolUseContext: ToolUseContext // 工具上下文（含权限）
|
||||
autoCompactTracking: AutoCompactTrackingState // 压缩跟踪
|
||||
maxOutputTokensRecoveryCount: number // 输出截断恢复计数
|
||||
hasAttemptedReactiveCompact: boolean // 是否已尝试即时压缩
|
||||
maxOutputTokensOverride: number | undefined // 输出 token 上限覆盖
|
||||
pendingToolUseSummary: Promise<...> | undefined // 异步工具摘要
|
||||
stopHookActive: boolean | undefined // Stop hook 是否激活
|
||||
turnCount: number // 轮次计数
|
||||
transition: Continue | undefined // 上一次继续的原因
|
||||
}
|
||||
```
|
||||
|
||||
每次 `continue` 都创建新的 State 对象（不可变更新），而非就地修改。`transition` 字段记录了为什么继续——让后续迭代能检测特定恢复路径（如 `collapse_drain_retry`）避免循环。
|
||||
|
||||
## Token Budget（实验性）
|
||||
|
||||
当 `TOKEN_BUDGET` feature 启用时（第 1311 行），循环在终止前会检查 token 消耗：
|
||||
|
||||
- **continuation**：未达到预算但超过阈值 → 注入 nudge 消息，让 AI 加速收尾
|
||||
- **diminishing_returns**：检测到收益递减 → 提前终止
|
||||
- 预算数据来自 `createBudgetTracker()`，跨迭代累计
|
||||
|
||||
## 为什么不是"一次规划，批量执行"
|
||||
|
||||
<Note>
|
||||
源码揭示了为什么 Claude Code 选择逐步循环：
|
||||
</Note>
|
||||
|
||||
- **每一步都产生真实信息**：`runTools()` 返回的 `toolResults` 是 API 不可能预知的——命令输出、文件内容、错误信息
|
||||
- **动态上下文管理**：每轮迭代前都重新评估压缩需求（autocompact → microcompact → snip），基于最新的 token 计数
|
||||
- **错误即时恢复**：工具失败不需要推倒重来——stop hook 可以注入阻塞错误让 AI 修正策略
|
||||
- **用户可控**：`abortController.signal` 在循环的多个检查点被检测（第 1018、1048、1488 行），用户按 ESC 可以优雅中断
|
||||
- **成本控制**：Token Budget 在每轮终止前检查，防止 AI 无效循环
|
||||
|
||||
## 一个完整的迭代示例
|
||||
|
||||
> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
|
||||
|
||||
```
|
||||
迭代 1: 思考→行动
|
||||
预处理: 无需压缩（上下文很短）
|
||||
API 调用: 返回 tool_use(Glob, "**/*.ts")
|
||||
工具执行: 返回 42 个文件路径
|
||||
→ needsFollowUp = true, continue
|
||||
|
||||
迭代 2: 思考→行动
|
||||
预处理: 42 个文件结果仍在预算内
|
||||
API 调用: 返回 tool_use(Grep, "import.*from")
|
||||
工具执行: 在 15 个文件中找到 120 条 import
|
||||
→ needsFollowUp = true, continue
|
||||
|
||||
迭代 3: 思考→行动（多轮）
|
||||
预处理: 120 条 Grep 结果触发 microcompact → 摘要化
|
||||
API 调用: 返回 3 个 tool_use(FileEdit, ...)
|
||||
工具执行: 删除 5 条未使用导入
|
||||
→ needsFollowUp = true, continue
|
||||
|
||||
迭代 4: 总结
|
||||
API 调用: 返回纯文本"已清理 3 个文件中的 5 条未使用导入"
|
||||
→ needsFollowUp = false
|
||||
→ Stop hooks 通过
|
||||
→ return { reason: 'completed' }
|
||||
```
|
||||
211
docs/extensibility/custom-agents.mdx
Normal file
211
docs/extensibility/custom-agents.mdx
Normal file
@@ -0,0 +1,211 @@
|
||||
---
|
||||
title: "自定义 Agent - 从 Markdown 到运行时的完整链路"
|
||||
description: "揭秘 Claude Code 自定义 Agent 完整链路：Agent 定义的 Markdown 数据模型、三种加载来源、工具过滤策略和与 AgentTool 的联动机制。"
|
||||
keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "Agent 配置", "角色定制"]
|
||||
---
|
||||
|
||||
{/* 本章目标：揭示 Agent 定义的完整数据模型、加载发现机制、工具过滤和与 AgentTool 的联动 */}
|
||||
|
||||
## Agent 定义的三种来源
|
||||
|
||||
Claude Code 的 Agent 不仅仅来自用户自定义——系统有三类来源，按优先级合并：
|
||||
|
||||
| 来源 | 位置 | 优先级 |
|
||||
|------|------|--------|
|
||||
| **Built-in** | `src/tools/AgentTool/built-in/` 硬编码 | 最低（可被覆盖） |
|
||||
| **Plugin** | 通过插件系统注册 | 中 |
|
||||
| **User/Project/Policy** | `.claude/agents/*.md` 或 settings.json | 最高 |
|
||||
|
||||
合并逻辑在 `getActiveAgentsFromList()` 中：按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
|
||||
|
||||
## Markdown Agent 文件的完整格式
|
||||
|
||||
```markdown
|
||||
---
|
||||
# === 必需字段 ===
|
||||
name: "reviewer" # Agent 标识（agentType）
|
||||
description: "Code review specialist, read-only analysis"
|
||||
|
||||
# === 工具控制 ===
|
||||
tools: "Read,Glob,Grep,Bash" # 允许的工具列表（逗号分隔）
|
||||
disallowedTools: "Write,Edit" # 显式禁止的工具
|
||||
|
||||
# === 模型配置 ===
|
||||
model: "haiku" # 指定模型（或 "inherit" 继承主线程）
|
||||
effort: "high" # 推理努力程度：low/medium/high 或整数
|
||||
|
||||
# === 行为控制 ===
|
||||
maxTurns: 10 # 最大 agentic 轮次
|
||||
permissionMode: "plan" # 权限模式：plan/bypassPermissions 等
|
||||
background: true # 始终作为后台任务运行
|
||||
initialPrompt: "/search TODO" # 首轮用户消息前缀（支持斜杠命令）
|
||||
|
||||
# === 隔离与持久化 ===
|
||||
isolation: "worktree" # 在独立 git worktree 中运行
|
||||
memory: "project" # 持久记忆范围：user/project/local
|
||||
|
||||
# === MCP 服务器 ===
|
||||
mcpServers:
|
||||
- "slack" # 引用已配置的 MCP 服务器
|
||||
- database: # 内联定义
|
||||
command: "npx"
|
||||
args: ["mcp-db"]
|
||||
|
||||
# === Hooks ===
|
||||
hooks:
|
||||
PreToolUse:
|
||||
- command: "audit-log.sh"
|
||||
timeout: 5000
|
||||
|
||||
# === Skills ===
|
||||
skills: "code-review,security-review" # 预加载的 skills（逗号分隔）
|
||||
|
||||
# === 显示 ===
|
||||
color: "blue" # 终端中的 Agent 颜色标识
|
||||
---
|
||||
|
||||
你是代码审查专家。你的职责是...
|
||||
|
||||
（正文内容 = system prompt）
|
||||
```
|
||||
|
||||
### 字段解析细节
|
||||
|
||||
- **`tools`**：通过 `parseAgentToolsFromFrontmatter()` 解析，支持逗号分隔字符串或数组
|
||||
- **`model: "inherit"`**：使用主线程的模型（区分大小写，只有小写 "inherit" 有效）
|
||||
- **`memory`**：启用后自动注入 `Write`/`Edit`/`Read` 工具（即使 `tools` 未包含），并在 system prompt 末尾追加 memory 指令
|
||||
- **`isolation: "remote"`**：仅在 Anthropic 内部可用（`USER_TYPE === 'ant'`），外部构建只支持 `worktree`
|
||||
- **`background`**：`true` 使 Agent 始终在后台运行，主线程不等待结果
|
||||
|
||||
## 加载与发现机制
|
||||
|
||||
`getAgentDefinitionsWithOverrides()`（被 `memoize` 缓存）执行完整的发现流程：
|
||||
|
||||
```
|
||||
1. 加载 Markdown 文件
|
||||
├── loadMarkdownFilesForSubdir('agents', cwd)
|
||||
│ ├── ~/.claude/agents/*.md （用户级，source = 'userSettings'）
|
||||
│ ├── .claude/agents/*.md （项目级，source = 'projectSettings'）
|
||||
│ └── managed/policy sources （策略级，source = 'policySettings'）
|
||||
│
|
||||
└── 每个 .md 文件：
|
||||
├── 解析 YAML frontmatter
|
||||
├── 正文作为 system prompt
|
||||
├── 校验必需字段（name, description）
|
||||
├── 静默跳过无 frontmatter 的 .md 文件（可能是参考文档）
|
||||
└── 解析失败 → 记录到 failedFiles，不阻塞其他 Agent
|
||||
|
||||
2. 并行加载 Plugin Agents
|
||||
└── loadPluginAgents() → memoized
|
||||
|
||||
3. 初始化 Memory Snapshots（如果 AGENT_MEMORY_SNAPSHOT 启用）
|
||||
└── initializeAgentMemorySnapshots()
|
||||
|
||||
4. 合并 Built-in + Plugin + Custom
|
||||
└── getActiveAgentsFromList() → 按 agentType 去重，后者覆盖前者
|
||||
|
||||
5. 分配颜色
|
||||
└── setAgentColor(agentType, color) → 终端 UI 中区分不同 Agent
|
||||
```
|
||||
|
||||
## 工具过滤的实现
|
||||
|
||||
当 Agent 被派生时，`AgentTool` 根据定义中的 `tools` / `disallowedTools` 过滤可用工具列表：
|
||||
|
||||
```
|
||||
全部工具
|
||||
↓ disallowedTools 移除
|
||||
↓ tools 白名单过滤（如果指定）
|
||||
可用工具
|
||||
```
|
||||
|
||||
- **`tools` 未指定**：Agent 可以使用所有工具（默认全能）
|
||||
- **`tools` 指定**：只能使用列出的工具
|
||||
- **`disallowedTools`**：即使 `tools` 未指定，这些工具也被禁止
|
||||
- **自动注入**：`memory` 启用时自动添加 `Write`/`Edit`/`Read`
|
||||
|
||||
以内置 Explore Agent 为例：
|
||||
|
||||
```typescript
|
||||
// src/tools/AgentTool/built-in/exploreAgent.ts
|
||||
disallowedTools: [
|
||||
'Agent', // 不能嵌套调用 Agent
|
||||
'ExitPlanMode', // 不需要 plan mode
|
||||
'FileEdit', // 只读
|
||||
'FileWrite', // 只读
|
||||
'NotebookEdit', // 只读
|
||||
]
|
||||
```
|
||||
|
||||
## System Prompt 的注入方式
|
||||
|
||||
Agent 的 system prompt 通过 `getSystemPrompt()` 闭包延迟生成：
|
||||
|
||||
```typescript
|
||||
// Markdown Agent
|
||||
getSystemPrompt: () => {
|
||||
if (isAutoMemoryEnabled() && memory) {
|
||||
return systemPrompt + '\n\n' + loadAgentMemoryPrompt(agentType, memory)
|
||||
}
|
||||
return systemPrompt
|
||||
}
|
||||
```
|
||||
|
||||
这意味着：
|
||||
1. **Markdown 正文 = 完整的 system prompt**——不是追加，而是替换默认 prompt
|
||||
2. **Memory 指令**在 memory 启用时自动追加到末尾
|
||||
3. **闭包延迟计算**——memory 状态可能在文件加载后才变化
|
||||
|
||||
对于 Built-in Agent，`getSystemPrompt` 接受 `toolUseContext` 参数，可以根据运行时状态（如是否使用嵌入式搜索工具）动态调整 prompt 内容。
|
||||
|
||||
## 与 AgentTool 的联动
|
||||
|
||||
当主 Agent 需要派生子 Agent 时：
|
||||
|
||||
```
|
||||
AgentTool.call({ subagent_type: "reviewer", ... })
|
||||
↓
|
||||
1. 从 agentDefinitions.activeAgents 查找 agentType === "reviewer"
|
||||
↓
|
||||
2. 检查 requiredMcpServers（如果 Agent 要求特定 MCP 服务器）
|
||||
↓
|
||||
3. 过滤工具列表（tools / disallowedTools）
|
||||
↓
|
||||
4. 解析模型：
|
||||
- "inherit" → 使用主线程模型
|
||||
- 具体模型名 → 直接使用
|
||||
- 未指定 → 主线程模型
|
||||
↓
|
||||
5. 解析权限模式（permissionMode）
|
||||
↓
|
||||
6. 构建隔离环境（如果 isolation === "worktree"）
|
||||
↓
|
||||
7. 注入 system prompt（getSystemPrompt()）
|
||||
↓
|
||||
8. 注入 initialPrompt（如果定义了）
|
||||
↓
|
||||
9. 启动子 Agent 循环（forkSubagent / runAgent）
|
||||
```
|
||||
|
||||
## 内置 Agent 参考
|
||||
|
||||
| Agent | agentType | 角色 | 工具限制 | 模型 |
|
||||
|-------|-----------|------|---------|------|
|
||||
| **General Purpose** | `general-purpose` | 默认子 Agent | 全部工具 | 主线程模型 |
|
||||
| **Explore** | `Explore` | 代码搜索专家 | 只读（无 Write/Edit） | haiku（外部） |
|
||||
| **Plan** | `Plan` | 规划专家 | 只读 + ExitPlanMode | inherit |
|
||||
| **Verification** | `verification` | 结果验证 | 由 feature flag 控制 | — |
|
||||
| **Code Guide** | `claude-code-guide` | Claude Code 使用指南 | 只读 | — |
|
||||
| **Statusline Setup** | `statusline-setup` | 终端状态栏配置 | 有限 | — |
|
||||
|
||||
SDK 入口（`sdk-ts`/`sdk-py`/`sdk-cli`）不加载 Code Guide Agent。环境变量 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` 可以完全禁用内置 Agent，给 SDK 用户提供空白画布。
|
||||
|
||||
## Agent Memory：持久化的 Agent 状态
|
||||
|
||||
当 `memory` 字段启用时，Agent 获得跨会话的持久记忆：
|
||||
|
||||
- **`local`**：当前项目、当前用户有效
|
||||
- **`project`**：当前项目所有用户共享
|
||||
- **`user`**：所有项目共享
|
||||
|
||||
Memory 通过 `loadAgentMemoryPrompt()` 注入到 system prompt 末尾，包含读写记忆的指令。Agent Memory Snapshot 机制在项目间同步 `user` 级记忆。
|
||||
239
docs/extensibility/hooks.mdx
Normal file
239
docs/extensibility/hooks.mdx
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
title: "Hooks 生命周期钩子 - 执行引擎与拦截协议"
|
||||
description: "从源码角度解析 Claude Code Hooks 系统：22 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
|
||||
keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 Hook 的执行引擎、匹配机制、返回值协议和生命周期管理 */}
|
||||
|
||||
## 22 种 Hook 事件
|
||||
|
||||
Claude Code 定义了 22 种 Hook 事件（`coreTypes.ts:25-53`），覆盖完整的 Agent 生命周期：
|
||||
|
||||
| 阶段 | 事件 | 触发时机 | 匹配字段 |
|
||||
|------|------|---------|---------|
|
||||
| **会话** | `SessionStart` | 会话启动 | `source` |
|
||||
| | `SessionEnd` | 会话结束 | `reason` |
|
||||
| | `Setup` | 初始化完成 | `trigger` |
|
||||
| **用户交互** | `UserPromptSubmit` | 用户提交消息 | — |
|
||||
| | `Stop` | Agent 停止响应 | — |
|
||||
| | `StopFailure` | Agent 停止失败 | `error` |
|
||||
| **工具执行** | `PreToolUse` | 工具调用前 | `tool_name` |
|
||||
| | `PostToolUse` | 工具调用后（成功） | `tool_name` |
|
||||
| | `PostToolUseFailure` | 工具调用后（失败） | `tool_name` |
|
||||
| **权限** | `PermissionRequest` | 权限请求 | `tool_name` |
|
||||
| | `PermissionDenied` | 权限被拒 | `tool_name` |
|
||||
| **子 Agent** | `SubagentStart` | 子 Agent 启动 | `agent_type` |
|
||||
| | `SubagentStop` | 子 Agent 停止 | `agent_type` |
|
||||
| **压缩** | `PreCompact` | 上下文压缩前 | `trigger` |
|
||||
| | `PostCompact` | 上下文压缩后 | `trigger` |
|
||||
| **协作** | `TeammateIdle` | Teammate 空闲 | — |
|
||||
| | `TaskCreated` | 任务创建 | — |
|
||||
| | `TaskCompleted` | 任务完成 | — |
|
||||
| **MCP** | `Elicitation` | MCP 服务器请求用户输入 | `mcp_server_name` |
|
||||
| | `ElicitationResult` | Elicitation 结果返回 | `mcp_server_name` |
|
||||
| **环境** | `ConfigChange` | 配置变更 | `source` |
|
||||
| | `CwdChanged` | 工作目录变更 | — |
|
||||
| | `FileChanged` | 文件变更 | `file_path` |
|
||||
| | `InstructionsLoaded` | 指令加载 | `load_reason` |
|
||||
| | `WorktreeCreate` / `WorktreeRemove` | Worktree 操作 | — |
|
||||
|
||||
## 6 种 Hook 类型
|
||||
|
||||
Hooks 配置支持 6 种执行方式（`src/types/hooks.ts`）：
|
||||
|
||||
| 类型 | 执行方式 | 适用场景 |
|
||||
|------|---------|---------|
|
||||
| `command` | Shell 命令（bash/PowerShell） | 通用脚本、CI 检查 |
|
||||
| `prompt` | 注入到 AI 上下文 | 代码规范提醒 |
|
||||
| `agent` | 启动子 Agent 执行 | 复杂分析任务 |
|
||||
| `http` | HTTP 请求 | 远程服务、Webhook |
|
||||
| `callback` | 内部 JS 函数 | 系统内置 Hook |
|
||||
| `function` | 运行时注册的函数 Hook | Agent/Skill 内部使用 |
|
||||
|
||||
## 执行引擎：execCommandHook
|
||||
|
||||
`execCommandHook()`（`src/utils/hooks.ts:829-1417`）是命令型 Hook 的执行核心：
|
||||
|
||||
```
|
||||
execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
|
||||
├── Shell 选择: hook.shell ?? DEFAULT_HOOK_SHELL
|
||||
│ ├── bash: spawn(cmd, [], { shell: gitBashPath | true })
|
||||
│ └── powershell: spawn(pwsh, ['-NoProfile', '-NonInteractive', '-Command', cmd])
|
||||
├── 变量替换
|
||||
│ ├── ${CLAUDE_PLUGIN_ROOT} → pluginRoot 路径
|
||||
│ ├── ${CLAUDE_PLUGIN_DATA} → plugin 数据目录
|
||||
│ └── ${user_config.X} → 用户配置值
|
||||
├── 环境变量注入
|
||||
│ ├── CLAUDE_PROJECT_DIR
|
||||
│ ├── CLAUDE_ENV_FILE（SessionStart/Setup/CwdChanged/FileChanged）
|
||||
│ └── CLAUDE_PLUGIN_OPTION_*（plugin options）
|
||||
├── stdin 写入: jsonInput + '\n'
|
||||
├── 超时: hook.timeout * 1000 ?? 600000ms（10分钟）
|
||||
└── 异步检测: 检查 stdout 首行是否为 {"async":true}
|
||||
```
|
||||
|
||||
### 异步 Hook 的检测协议
|
||||
|
||||
Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`hooks.ts:1199-1246`）：
|
||||
|
||||
```typescript
|
||||
const firstLine = firstLineOf(stdout).trim()
|
||||
if (isAsyncHookJSONOutput(parsed)) {
|
||||
executeInBackground({
|
||||
processId: `async_hook_${child.pid}`,
|
||||
asyncResponse: parsed,
|
||||
...
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
后台 Hook 通过 `registerPendingAsyncHook()` 注册到 `AsyncHookRegistry`，完成后通过 `enqueuePendingNotification()` 通知主线程。
|
||||
|
||||
### asyncRewake：Hook 唤醒模型
|
||||
|
||||
`asyncRewake` 模式的 Hook 绕过 `AsyncHookRegistry`。当 Hook 退出码为 2 时，通过 `enqueuePendingNotification()` 以 `task-notification` 模式注入消息，唤醒空闲的模型（通过 `useQueueProcessor`）或在忙碌时注入 `queued_command` 附件。
|
||||
|
||||
## Hook 输出的 JSON Schema
|
||||
|
||||
同步 Hook 的输出遵循严格的 Zod schema（`src/types/hooks.ts:49-567`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"continue": false, // 是否继续执行
|
||||
"suppressOutput": true, // 隐藏 stdout
|
||||
"stopReason": "安全检查失败", // continue=false 时的原因
|
||||
"decision": "approve" | "block", // 全局决策
|
||||
"reason": "原因说明", // 决策原因
|
||||
"systemMessage": "警告内容", // 注入到上下文的系统消息
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"permissionDecision": "allow" | "deny" | "ask",
|
||||
"permissionDecisionReason": "匹配了安全规则",
|
||||
"updatedInput": { ... }, // 修改后的工具输入
|
||||
"additionalContext": "额外上下文" // 注入到对话
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 各事件的 hookSpecificOutput
|
||||
|
||||
| 事件 | 专有字段 | 作用 |
|
||||
|------|---------|------|
|
||||
| `PreToolUse` | `permissionDecision`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
|
||||
| `UserPromptSubmit` | `additionalContext` | 注入额外上下文 |
|
||||
| `PostToolUse` | `additionalContext`, `updatedMCPToolOutput` | 修改 MCP 工具输出 |
|
||||
| `SessionStart` | `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
|
||||
| `PermissionDenied` | `retry` | 指示是否重试 |
|
||||
| `Elicitation` | `action`, `content` | 控制用户输入对话框 |
|
||||
|
||||
## Hook 匹配机制：getMatchingHooks
|
||||
|
||||
`getMatchingHooks()`（`hooks.ts:1685-1956`）负责从所有来源中查找匹配的 Hook：
|
||||
|
||||
### 多来源合并
|
||||
|
||||
```
|
||||
getHooksConfig()
|
||||
├── getHooksConfigFromSnapshot() ← settings.json 中的 Hook（user/project/local）
|
||||
├── getRegisteredHooks() ← SDK 注册的 callback Hook
|
||||
├── getSessionHooks() ← Agent/Skill 前置注册的 session Hook
|
||||
└── getSessionFunctionHooks() ← 运行时 function Hook
|
||||
```
|
||||
|
||||
### 匹配规则
|
||||
|
||||
`matcher` 字段支持三种模式（`matchesPattern()`, `hooks.ts:1428-1463`）：
|
||||
|
||||
```
|
||||
"Write" → 精确匹配
|
||||
"Write|Edit" → 管道分隔的多值匹配
|
||||
"^Bash(git.*)" → 正则匹配
|
||||
"*" 或 "" → 通配（匹配所有）
|
||||
```
|
||||
|
||||
### if 条件过滤
|
||||
|
||||
Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`hooks.ts:1472-1503`）预编译匹配器：
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": [{
|
||||
"command": "check-git-branch.sh",
|
||||
"if": "Bash(git push*)"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
`if` 条件使用 `permissionRuleValueFromString` 解析，支持与权限规则相同的语法（工具名 + 参数模式）。Bash 工具还会使用 tree-sitter 进行 AST 级别的命令解析。
|
||||
|
||||
### Hook 去重
|
||||
|
||||
同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按 `pluginRoot\0command` 做 Map 去重，保留**最后合并的层级**。
|
||||
|
||||
## 工作区信任检查
|
||||
|
||||
**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()`, `hooks.ts:286-296`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
|
||||
|
||||
```typescript
|
||||
// 交互模式下，所有 Hook 要求信任
|
||||
const hasTrust = checkHasTrustDialogAccepted()
|
||||
return !hasTrust
|
||||
```
|
||||
|
||||
SDK 非交互模式下信任是隐式的（`getIsNonInteractiveSession()` 为 true 时跳过检查）。
|
||||
|
||||
## 四种 Hook 能力的源码映射
|
||||
|
||||
### 1. 拦截操作（PreToolUse）
|
||||
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"permissionDecision": "deny"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`processHookJSONOutput()` 将 `permissionDecision` 映射为 `result.permissionBehavior = 'deny'`，并设置 `blockingError`，阻止工具执行。
|
||||
|
||||
### 2. 修改行为（updatedInput / updatedMCPToolOutput）
|
||||
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"updatedInput": { "command": "npm test -- --bail" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`updatedInput` 替换原始工具输入；`updatedMCPToolOutput`（PostToolUse 事件）替换 MCP 工具的返回值——可用于过滤敏感数据。
|
||||
|
||||
### 3. 注入上下文（additionalContext / systemMessage）
|
||||
|
||||
- `additionalContext` → 通过 `createAttachmentMessage({ type: 'hook_additional_context' })` 注入为用户消息
|
||||
- `systemMessage` → 注入为系统警告，直接显示给用户
|
||||
|
||||
### 4. 控制流程（continue / stopReason）
|
||||
|
||||
```json
|
||||
{ "continue": false, "stopReason": "构建失败，停止执行" }
|
||||
```
|
||||
|
||||
`continue: false` 设置 `preventContinuation = true`，阻止 Agent 继续执行后续操作。
|
||||
|
||||
## Session Hook 的生命周期
|
||||
|
||||
Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（`runAgent.ts:567-575`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()` 清理。
|
||||
|
||||
```typescript
|
||||
// runAgent.ts:567 — 注册 agent 的前置 Hook
|
||||
registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, ...)
|
||||
|
||||
// runAgent.ts:820 — finally 块清理
|
||||
clearSessionHooks(rootSetAppState, agentId)
|
||||
```
|
||||
|
||||
这确保 Agent A 的 Hook 不会泄漏到 Agent B 的执行中。
|
||||
191
docs/extensibility/mcp-protocol.mdx
Normal file
191
docs/extensibility/mcp-protocol.mdx
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: "MCP 协议 - 连接管理、工具发现与执行链路"
|
||||
description: "从源码角度解析 Claude Code 的 MCP 集成：7 种传输层实现、connectToServer 的 memoize 缓存、工具发现的 LRU 策略、认证状态机、以及 MCP 工具如何进入权限检查链路。"
|
||||
keywords: ["MCP", "Model Context Protocol", "工具扩展", "MCP 客户端", "工具发现"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 MCP 客户端的连接管理、工具发现协议和执行链路 */}
|
||||
|
||||
## 架构总览：从配置到可用工具
|
||||
|
||||
```
|
||||
settings.json: { mcpServers: { "my-db": { command: "npx", args: [...] } } }
|
||||
↓
|
||||
getAllMcpConfigs() ← 合并 user/project/local 三级配置
|
||||
↓
|
||||
useManageMCPConnections() ← React Hook 管理连接生命周期
|
||||
↓
|
||||
connectToServer(name, config) ← memoize 缓存（lodash memoize）
|
||||
├── 创建 Transport（stdio/sse/http/...）
|
||||
├── new Client() ← @modelcontextprotocol/sdk
|
||||
├── client.connect(transport) ← 超时控制（MCP_TIMEOUT, 默认 30s）
|
||||
└── 返回 MCPServerConnection ← { connected | failed | needs-auth | pending }
|
||||
↓
|
||||
fetchToolsForClient(client) ← LRU(20) 缓存
|
||||
├── client.request({ method: 'tools/list' })
|
||||
└── 每个工具包装为 MCPTool ← 统一 Tool 接口
|
||||
↓
|
||||
assembleToolPool() ← 合并内置工具 + MCP 工具
|
||||
↓
|
||||
工具名格式: mcp__<serverName>__<toolName> ← buildMcpToolName()
|
||||
```
|
||||
|
||||
## 7 种传输层实现
|
||||
|
||||
`connectToServer()`（`client.ts:596-1643`）根据 `config.type` 分发到不同的 Transport 实现：
|
||||
|
||||
| 传输类型 | Transport 类 | 适用场景 | 认证方式 |
|
||||
|----------|-------------|---------|---------|
|
||||
| `stdio`（默认） | `StdioClientTransport` | 本地子进程 | 无 |
|
||||
| `sse` | `SSEClientTransport` | 远程 SSE 服务 | `ClaudeAuthProvider` + OAuth |
|
||||
| `http` | `StreamableHTTPClientTransport` | HTTP 流 | `ClaudeAuthProvider` + OAuth |
|
||||
| `sse-ide` | `SSEClientTransport` | IDE 集成 | lockfile token |
|
||||
| `ws-ide` | `WebSocketTransport` | IDE WebSocket | `X-Claude-Code-Ide-Authorization` |
|
||||
| `ws` | `WebSocketTransport` | WebSocket 服务 | session ingress token |
|
||||
| `claudeai-proxy` | `StreamableHTTPClientTransport` | claude.ai 代理 | OAuth bearer + 401 重试 |
|
||||
|
||||
### stdio 传输的进程管理
|
||||
|
||||
stdio 类型的 MCP 服务器作为子进程运行，cleanup 时采用 **信号升级策略**（`client.ts:1431-1564`）：
|
||||
|
||||
```
|
||||
SIGINT (100ms) → SIGTERM (400ms) → SIGKILL
|
||||
```
|
||||
|
||||
总清理时间上限 600ms，防止 MCP 服务器关闭阻塞 CLI 退出。
|
||||
|
||||
### 远程传输的认证状态机
|
||||
|
||||
SSE/HTTP 类型使用 `ClaudeAuthProvider` 实现 OAuth 认证流程。认证失败时进入 `needs-auth` 状态，并写入 15 分钟 TTL 的缓存文件（`mcp-needs-auth-cache.json`），避免重复弹出认证提示。
|
||||
|
||||
```
|
||||
连接尝试 → 401 Unauthorized
|
||||
↓
|
||||
handleRemoteAuthFailure()
|
||||
├── logEvent('tengu_mcp_server_needs_auth')
|
||||
├── setMcpAuthCacheEntry(name) ← 写入 15min TTL 缓存
|
||||
└── return { type: 'needs-auth' } ← UI 显示认证提示
|
||||
```
|
||||
|
||||
## 连接缓存与重连机制
|
||||
|
||||
`connectToServer` 使用 lodash `memoize` 缓存连接对象，缓存 key 为 `${name}-${JSON.stringify(config)}`。
|
||||
|
||||
### 缓存失效触发
|
||||
|
||||
当连接关闭时（`client.onclose`），清除所有相关缓存（`client.ts:1376-1404`）：
|
||||
|
||||
```typescript
|
||||
client.onclose = () => {
|
||||
const key = getServerCacheKey(name, serverRef)
|
||||
fetchToolsForClient.cache.delete(name) // 工具缓存
|
||||
fetchResourcesForClient.cache.delete(name) // 资源缓存
|
||||
fetchCommandsForClient.cache.delete(name) // 命令缓存
|
||||
connectToServer.cache.delete(key) // 连接缓存
|
||||
}
|
||||
```
|
||||
|
||||
### 连接降级检测
|
||||
|
||||
远程传输有 **连续错误计数器**（`client.ts:1229`）：
|
||||
|
||||
```typescript
|
||||
let consecutiveConnectionErrors = 0
|
||||
const MAX_ERRORS_BEFORE_RECONNECT = 3
|
||||
```
|
||||
|
||||
遇到终端错误（ECONNRESET、ETIMEDOUT、EPIPE 等）连续 3 次后，主动关闭 transport 触发重连。对于 HTTP 传输，还检测 session 过期（404 + JSON-RPC code -32001）。
|
||||
|
||||
### 请求级超时保护
|
||||
|
||||
每个 HTTP 请求使用独立的 `setTimeout` 超时（`wrapFetchWithTimeout`，`client.ts:493`），而非共享 `AbortSignal.timeout()`。原因是 Bun 对 AbortSignal.timeout 的 GC 是惰性的——每个请求约 2.4KB 原生内存，即使请求毫秒级完成也要等 60s 才回收。
|
||||
|
||||
```typescript
|
||||
const controller = new AbortController()
|
||||
const timer = setTimeout(c => c.abort(...), MCP_REQUEST_TIMEOUT_MS, controller)
|
||||
timer.unref?.() // 不阻止进程退出
|
||||
```
|
||||
|
||||
## 工具发现：从 MCP 到 Tool 接口
|
||||
|
||||
`fetchToolsForClient()`（`client.ts:1745-2000`）使用 `memoizeWithLRU` 缓存（上限 20），将 MCP 工具转换为 Claude Code 的统一 Tool 接口：
|
||||
|
||||
```typescript
|
||||
const fullyQualifiedName = buildMcpToolName(client.name, tool.name)
|
||||
// 结果: "mcp__my-db__query"
|
||||
```
|
||||
|
||||
### 工具描述截断
|
||||
|
||||
MCP 工具描述上限 2048 字符（`MAX_MCP_DESCRIPTION_LENGTH`）。OpenAPI 生成的 MCP 服务器曾观察到 15-60KB 的描述文档。
|
||||
|
||||
### 工具能力标注
|
||||
|
||||
每个 MCP 工具根据 `tool.annotations` 自动标注：
|
||||
|
||||
| 注解 | 映射到 | 含义 |
|
||||
|------|--------|------|
|
||||
| `readOnlyHint` | `isReadOnly()` + `isConcurrencySafe()` | 只读，可并行 |
|
||||
| `destructiveHint` | `isDestructive()` | 破坏性操作 |
|
||||
| `openWorldHint` | `isOpenWorld()` | 开放世界（不可枚举） |
|
||||
| `title` | `userFacingName()` | 显示名称 |
|
||||
|
||||
### MCP 工具的权限检查
|
||||
|
||||
MCP 工具默认返回 `{ behavior: 'passthrough' }`（`client.ts:1816-1834`），意味着它们始终进入权限确认流程。工具名使用 `mcp__` 前缀精确匹配权限规则。
|
||||
|
||||
## MCP 工具的执行链路
|
||||
|
||||
```
|
||||
AI 生成 tool_use: { name: "mcp__my-db__query", input: { sql: "..." } }
|
||||
↓
|
||||
MCPTool.call() ← client.ts:1835
|
||||
├── ensureConnectedClient() ← 确保连接有效（重连）
|
||||
├── callMCPToolWithUrlElicitationRetry() ← 带 Elicitation 重试
|
||||
│ ├── client.request({ method: 'tools/call' })
|
||||
│ ├── 处理图片结果（resize + persist）
|
||||
│ └── 内容截断（mcpContentNeedsTruncation）
|
||||
├── McpSessionExpiredError → 重试一次
|
||||
└── 返回 { data: content, mcpMeta }
|
||||
```
|
||||
|
||||
### Session 过期自动重试
|
||||
|
||||
HTTP 传输的 MCP session 可能过期。检测到 `McpSessionExpiredError` 后自动重试一次（`client.ts:1862`），因为 `ensureConnectedClient()` 已经清除了缓存并建立了新连接。
|
||||
|
||||
### 内容截断与持久化
|
||||
|
||||
大型 MCP 工具输出通过 `truncateMcpContentIfNeeded` 截断，二进制内容（图片）通过 `persistBinaryContent` 写入文件并返回文件路径。图片自动 resize（`maybeResizeAndDownsampleImageBuffer`）。
|
||||
|
||||
## MCP 连接的并发控制
|
||||
|
||||
```typescript
|
||||
// 本地服务器并发连接数
|
||||
getMcpServerConnectionBatchSize() // 默认 3
|
||||
|
||||
// 远程服务器并发连接数
|
||||
getRemoteMcpServerConnectionBatchSize() // 默认 20
|
||||
```
|
||||
|
||||
本地 MCP 服务器（stdio）是重量级的子进程，默认限制 3 个并发连接。远程服务器是轻量级 HTTP 请求，允许 20 个并发。
|
||||
|
||||
## 实际配置示例
|
||||
|
||||
```json
|
||||
// settings.json 中的 MCP 配置
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-database": {
|
||||
"command": "npx",
|
||||
"args": ["@my-org/db-mcp-server"],
|
||||
"env": { "DB_URL": "postgres://..." }
|
||||
},
|
||||
"remote-api": {
|
||||
"type": "http",
|
||||
"url": "https://api.example.com/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
配置后，AI 的工具列表中会出现 `mcp__my-database__query` 和 `mcp__remote-api__*` 工具——与内置工具使用相同的权限检查链路和 UI 渲染。
|
||||
221
docs/extensibility/skills.mdx
Normal file
221
docs/extensibility/skills.mdx
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
title: "Skills 技能系统 - Prompt 即能力的架构哲学"
|
||||
description: "深入剖析 Claude Code Skills 系统的完整实现：从磁盘加载、Frontmatter 解析、预算感知描述截断、双模式执行（inline/fork）、权限白名单、条件激活、动态发现到远程技能加载，揭示一条完整的 Skill 生命周期链路。"
|
||||
keywords: ["Skills", "SkillTool", "技能加载", "Frontmatter", "whenToUse", "allowedTools", "fork执行", "动态发现"]
|
||||
---
|
||||
|
||||
{/* 本章目标：揭示 Skill 系统从文件到执行的全链路实现 */}
|
||||
|
||||
## Tool vs Skill：本质差异
|
||||
|
||||
| | Tool | Skill |
|
||||
|---|---|---|
|
||||
| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） |
|
||||
| 触发方式 | AI 自主选择 | 用户 `/skill-name` 或 AI 通过 `SkillTool` 自动匹配 |
|
||||
| 本质 | TypeScript 执行逻辑 | **Prompt + 权限配置**的声明式封装 |
|
||||
| 注册位置 | `src/tools.ts` → `getTools()` | `src/commands.ts` → `getCommands()` |
|
||||
| 执行器 | 各 Tool 的 `call()` 方法 | `SkillTool.call()` → 两条分支（inline / fork） |
|
||||
|
||||
Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"——Skill 把这种"经验"封装为可复用的 Markdown。
|
||||
|
||||
## Skill 的五个来源与加载链路
|
||||
|
||||
### 1. 内置命令（Built-in Commands）
|
||||
|
||||
硬编码在 `src/commands.ts:258` 的 `COMMANDS` memoize 数组中，包含 70+ 条命令（`/commit`、`/review`、`/compact` 等）。这些是 TypeScript 模块而非 Markdown，但实现了相同的 `Command` 接口（`src/types/command.ts`）。
|
||||
|
||||
### 2. Bundled Skills（编译时打包）
|
||||
|
||||
通过 `registerBundledSkill()`（`src/skills/bundledSkills.ts:53`）在模块初始化时注册。关键特性：
|
||||
|
||||
- **延迟文件提取**：如果 Skill 声明了 `files`（参考文件），首次调用时才解压到临时目录（`getBundledSkillExtractDir()`），使用 `O_NOFOLLOW | O_EXCL` 防止符号链接攻击（`safeWriteFile`，第 186 行）
|
||||
- **闭包级 memoize**：并发调用共享同一个 extraction promise，避免竞态写入
|
||||
- 来源标记为 `source: 'bundled'`，在 Prompt 预算中享有**不可截断**的特权
|
||||
|
||||
### 3. 磁盘 Skills（`.claude/skills/`）
|
||||
|
||||
由 `loadSkillsFromSkillsDir()`（`src/skills/loadSkillsDir.ts:407`）加载，这是最重要的加载路径：
|
||||
|
||||
```
|
||||
管理策略: $MANAGED_DIR/.claude/skills/ (policySettings)
|
||||
用户全局: ~/.claude/skills/ (userSettings)
|
||||
项目级: .claude/skills/ (projectSettings, 向上遍历至 home)
|
||||
附加目录: --add-dir 指定的路径下 .claude/skills/
|
||||
```
|
||||
|
||||
**加载协议**：只识别 `skill-name/SKILL.md` 目录格式，不再支持单文件 `.md`。加载流程：
|
||||
|
||||
1. `readdir` 扫描目录 → 仅保留 `isDirectory()` 或 `isSymbolicLink()` 的条目
|
||||
2. 在每个子目录中查找 `SKILL.md`，未找到则跳过
|
||||
3. `parseFrontmatter()` 解析 YAML 头部，提取 `whenToUse`、`allowedTools`、`context` 等字段
|
||||
4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 17 个 frontmatter 字段
|
||||
5. `createSkillCommand()`（第 270 行）构造 `Command` 对象
|
||||
|
||||
**去重机制**：使用 `realpath()` 解析符号链接获得规范路径（`getFileIdentity`，第 118 行），避免通过符号链接或重叠父目录导致的重复加载。
|
||||
|
||||
### 4. MCP Skills（动态发现）
|
||||
|
||||
通过 `registerMCPSkillBuilders()` 注册构建器，MCP Server 的 prompt 被 `mcpSkillBuilders.ts` 转换为 `Command` 对象。标记为 `loadedFrom: 'mcp'`。
|
||||
|
||||
**安全边界**：MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**（`loadSkillsDir.ts:374` 的 `loadedFrom !== 'mcp'` 守卫），因为远程内容不可信。
|
||||
|
||||
### 5. Legacy Commands（`/commands/` 目录）
|
||||
|
||||
向后兼容的旧格式，由 `loadSkillsFromCommandsDir()`（第 566 行）加载。同时支持 `SKILL.md` 目录格式和单 `.md` 文件格式。
|
||||
|
||||
## Frontmatter 字段全景
|
||||
|
||||
一个 `SKILL.md` 的完整 frontmatter（`parseSkillFrontmatterFields`，第 185 行）：
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-review # 显示名称（覆盖目录名）
|
||||
description: 系统性代码审查 # 描述（或从 Markdown 首段提取）
|
||||
when_to_use: "用户说审查代码、找 bug" # AI 自动匹配依据
|
||||
allowed-tools: # 工具白名单
|
||||
- Read
|
||||
- Grep
|
||||
- Glob
|
||||
argument-hint: "<file-or-directory>" # 参数提示
|
||||
arguments: [path] # 声明式参数名（用于 $ARGUMENTS 替换）
|
||||
model: opus # 模型覆盖
|
||||
effort: high # 努力级别
|
||||
context: fork # 执行模式：inline（默认）| fork
|
||||
agent: code-reviewer # 指定 Agent 定义文件
|
||||
user-invocable: true # 用户是否可 /调用
|
||||
disable-model-invocation: false # 禁止 AI 自主调用
|
||||
version: "1.0" # 版本号
|
||||
paths: # 条件激活的文件路径模式
|
||||
- "src/**/*.ts"
|
||||
hooks: # Hook 配置
|
||||
PreToolUse:
|
||||
- command: ["echo", "checking"]
|
||||
shell: ["bash"] # Shell 执行环境
|
||||
---
|
||||
```
|
||||
|
||||
解析后有 17 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
|
||||
|
||||
## 两条执行路径：Inline vs Fork
|
||||
|
||||
SkillTool（`src/tools/SkillTool/SkillTool.ts:332`）在 `call()` 中根据 `command.context` 分流：
|
||||
|
||||
### Inline 模式（默认）
|
||||
|
||||
Skill 的 Prompt 内容被注入为 **UserMessage**，在主对话流中继续执行：
|
||||
|
||||
1. `processPromptSlashCommand()` 处理参数替换（`$ARGUMENTS`）和 shell 命令展开（`` !`...` ``）
|
||||
2. `${CLAUDE_SKILL_DIR}` 被替换为 Skill 所在目录的绝对路径
|
||||
3. `${CLAUDE_SESSION_ID}` 被替换为当前会话 ID
|
||||
4. 返回 `newMessages`（注入到对话流）+ `contextModifier`（修改权限上下文）
|
||||
|
||||
`contextModifier`（第 776 行）做了三件事：
|
||||
- **工具白名单注入**：将 `allowedTools` 合并到 `alwaysAllowRules.command`
|
||||
- **模型切换**：`resolveSkillModelOverride()` 处理模型覆盖，保留 `[1m]` 后缀以避免 200K 窗口截断
|
||||
- **努力级别覆盖**：修改 `effortValue`
|
||||
|
||||
### Fork 模式（`context: fork`）
|
||||
|
||||
Skill 在**独立子 Agent** 中执行（`executeForkedSkill`，第 122 行）：
|
||||
|
||||
1. `prepareForkedCommandContext()` 构建隔离的 Agent 定义和 Prompt
|
||||
2. `runAgent()` 启动子 Agent 循环，拥有独立的 token 预算
|
||||
3. 通过 `onProgress` 回调报告工具使用进度
|
||||
4. 结果通过 `extractResultText()` 提取，子 Agent 的全部消息在提取后被释放（`agentMessages.length = 0`）
|
||||
5. 最终通过 `clearInvokedSkillsForAgent()` 清理状态
|
||||
|
||||
Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务），避免污染主对话的上下文。
|
||||
|
||||
## 权限模型：Safe Properties 白名单
|
||||
|
||||
`checkPermissions()`（第 433 行）实现了一个四层权限检查：
|
||||
|
||||
```
|
||||
1. Deny 规则匹配（支持精确匹配和 prefix:* 通配符）
|
||||
↓ 未命中
|
||||
2. 官方市场 Skill 自动放行（plugin + isOfficialMarketplaceName）
|
||||
↓ 未命中
|
||||
3. Allow 规则匹配
|
||||
↓ 未命中
|
||||
4. Safe Properties 白名单检查（skillHasOnlySafeProperties，第 911 行）
|
||||
↓ 有非安全属性
|
||||
5. Ask 用户确认（附带精确匹配和前缀匹配两条建议规则）
|
||||
```
|
||||
|
||||
**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 28 个属性名的白名单。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
|
||||
|
||||
## Prompt 预算：1% 上下文窗口的截断策略
|
||||
|
||||
Skill 列表注入 System Prompt 时有严格的字符预算（`prompt.ts`）：
|
||||
|
||||
- **预算计算**：`contextWindowTokens × 4 chars/token × 1%`（约 8000 字符）
|
||||
- **单条上限**：`MAX_LISTING_DESC_CHARS = 250` 字符（超出截断为 `…`）
|
||||
- **Bundled Skills 不可截断**：它们始终保留完整描述，预算不足时只截断非 bundled 的
|
||||
- **降级策略**：
|
||||
1. 尝试完整描述 → 超预算？
|
||||
2. Bundled 保留完整，非 bundled 均分剩余预算 → 每条描述低于 20 字符？
|
||||
3. 非 bundled 仅保留名称
|
||||
|
||||
`formatCommandsWithinBudget()`（`prompt.ts:70`）实现了这个三级降级。
|
||||
|
||||
## 动态发现与条件激活
|
||||
|
||||
### 基于文件路径的动态发现
|
||||
|
||||
`discoverSkillDirsForPaths()`（`loadSkillsDir.ts:861`）在文件操作时触发：
|
||||
|
||||
1. 从被操作的文件路径开始，**向上遍历**至 CWD（不包含 CWD 本身）
|
||||
2. 在每层查找 `.claude/skills/` 目录
|
||||
3. 使用 `realpath` 去重，`git check-ignore` 过滤 gitignored 目录
|
||||
4. 按路径深度排序（**深层优先**），更接近文件的 Skill 优先级更高
|
||||
|
||||
### 条件激活（paths frontmatter）
|
||||
|
||||
带有 `paths` 模式的 Skill 在加载时不会立即可用，而是存入 `conditionalSkills` Map。当被操作的文件路径匹配某个 Skill 的 paths 模式时（使用 `ignore` 库做 gitignore 风格匹配），该 Skill 才被**激活**——从 `conditionalSkills` 移入 `dynamicSkills`。
|
||||
|
||||
这意味着一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。
|
||||
|
||||
## 使用频率排名
|
||||
|
||||
`recordSkillUsage()`（`skillUsageTracking.ts`）使用指数衰减算法计算 Skill 排名分数：
|
||||
|
||||
```
|
||||
score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
|
||||
```
|
||||
|
||||
- **7 天半衰期**：一周前的使用权重减半
|
||||
- **最低 0.1 保底**：避免老但高频使用的 Skill 完全沉底
|
||||
- **60 秒去抖**：同一 Skill 在 1 分钟内的多次调用只计一次，减少文件 I/O
|
||||
|
||||
排名数据持久化在全局配置的 `skillUsage` 字段中。
|
||||
|
||||
## 远程技能加载（Experimental）
|
||||
|
||||
通过 `EXPERIMENTAL_SKILL_SEARCH` feature flag 控制，支持从远程（AKI/GCS/S3）加载 `_canonical_<slug>` 格式的 Skill：
|
||||
|
||||
1. `validateInput()` 中 `stripCanonicalPrefix()` 拦截 canonical 名称
|
||||
2. `executeRemoteSkill()`（第 970 行）从远程 URL 加载 SKILL.md
|
||||
3. 支持 `gs://`、`https://`、`s3://` 等 URL 协议
|
||||
4. 内容经过 frontmatter 剥离、`${CLAUDE_SKILL_DIR}` 替换后直接注入
|
||||
5. 通过 `addInvokedSkill()` 注册到 compaction 保留状态，确保压缩后仍可恢复
|
||||
6. 远程 Skill 不经过 `processPromptSlashCommand`——无 `!command` 替换、无 `$ARGUMENTS` 展开
|
||||
|
||||
## 完整生命周期总结
|
||||
|
||||
```
|
||||
磁盘 SKILL.md
|
||||
↓ parseFrontmatter()
|
||||
↓ parseSkillFrontmatterFields() → 17 个字段
|
||||
↓ createSkillCommand() → Command 对象
|
||||
↓ 去重（realpath + seenFileIds）
|
||||
↓ 条件 Skill → conditionalSkills Map（等待路径匹配激活）
|
||||
↓ getSkillDirCommands() memoize 缓存
|
||||
↓ getAllCommands() 合并 local + MCP
|
||||
↓ formatCommandsWithinBudget() → 截断后的 Skill 列表注入 System Prompt
|
||||
↓ AI 选择匹配的 Skill
|
||||
↓ SkillTool.validateInput() → 名称校验 + 存在性检查
|
||||
↓ SkillTool.checkPermissions() → 四层权限检查
|
||||
↓ SkillTool.call() → inline 或 fork 执行
|
||||
↓ contextModifier() → 注入 allowedTools + model + effort
|
||||
↓ recordSkillUsage() → 更新使用频率排名
|
||||
```
|
||||
209
docs/external-dependencies.md
Normal file
209
docs/external-dependencies.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Claude Code 远程服务器依赖
|
||||
|
||||
> 只列出代码中实际发起网络请求的远程服务。本地服务、npm 包依赖、展示用 URL 不包含在内。
|
||||
|
||||
## 总览表
|
||||
|
||||
| # | 服务 | 远程端点 | 协议 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Anthropic API | `api.anthropic.com` | HTTPS | 默认启用 |
|
||||
| 2 | AWS Bedrock | `bedrock-runtime.*.amazonaws.com` | HTTPS | 需 `CLAUDE_CODE_USE_BEDROCK=1` |
|
||||
| 3 | Google Vertex AI | `{region}-aiplatform.googleapis.com` | HTTPS | 需 `CLAUDE_CODE_USE_VERTEX=1` |
|
||||
| 4 | Azure Foundry | `{resource}.services.ai.azure.com` | HTTPS | 需 `CLAUDE_CODE_USE_FOUNDRY=1` |
|
||||
| 5 | OAuth (Anthropic) | `platform.claude.com`, `claude.com`, `claude.ai` | HTTPS | 用户登录时 |
|
||||
| 6 | GrowthBook | `api.anthropic.com` (remoteEval) | HTTPS | 默认启用 |
|
||||
| 7 | Sentry | 可配置 (`SENTRY_DSN`) | HTTPS | 需设环境变量 |
|
||||
| 8 | Datadog | 可配置 (`DATADOG_LOGS_ENDPOINT`) | HTTPS | 需设环境变量 |
|
||||
| 9 | OpenTelemetry Collector | 可配置 (`OTEL_EXPORTER_OTLP_ENDPOINT`) | gRPC/HTTP | 需设环境变量 |
|
||||
| 10 | 1P Event Logging | `api.anthropic.com/api/event_logging/batch` | HTTPS | 默认启用 |
|
||||
| 11 | BigQuery Metrics | `api.anthropic.com/api/claude_code/metrics` | HTTPS | 默认启用 |
|
||||
| 12 | MCP Proxy | `mcp-proxy.anthropic.com` | HTTPS+WS | 使用 MCP 工具时 |
|
||||
| 13 | MCP Registry | `api.anthropic.com/mcp-registry` | HTTPS | 查询 MCP 服务器时 |
|
||||
| 14 | Bing Search | `www.bing.com` | HTTPS | WebSearch 工具 |
|
||||
| 15 | Google Cloud Storage (更新) | `storage.googleapis.com` | HTTPS | 版本检查 |
|
||||
| 16 | GitHub Raw (Changelog/Stats) | `raw.githubusercontent.com` | HTTPS | 更新提示 |
|
||||
| 17 | Claude in Chrome Bridge | `bridge.claudeusercontent.com` | WSS | Chrome 集成 |
|
||||
| 18 | CCR Upstream Proxy | `api.anthropic.com` | WS | CCR 远程会话 |
|
||||
| 19 | Voice STT | `api.anthropic.com/api/ws/...` | WSS | Voice Mode |
|
||||
| 20 | Desktop App Download | `claude.ai/api/desktop/...` | HTTPS | 下载引导 |
|
||||
|
||||
---
|
||||
|
||||
## 详细说明
|
||||
|
||||
### 1. Anthropic Messages API
|
||||
|
||||
核心 LLM 推理服务，发送对话消息、接收流式响应。
|
||||
|
||||
- **端点**: `https://api.anthropic.com` (生产) / `https://api-staging.anthropic.com` (staging)
|
||||
- **覆盖**: `ANTHROPIC_BASE_URL` 环境变量
|
||||
- **认证**: API Key / OAuth Token
|
||||
- **文件**: `src/services/api/client.ts`, `src/services/api/claude.ts`
|
||||
|
||||
### 2. AWS Bedrock
|
||||
|
||||
- **端点**: `bedrock-runtime.{region}.amazonaws.com`
|
||||
- **认证**: AWS 凭证链 / `AWS_BEARER_TOKEN_BEDROCK`
|
||||
- **文件**: `src/services/api/client.ts:153-190`, `src/utils/aws.ts`
|
||||
|
||||
### 3. Google Vertex AI
|
||||
|
||||
- **端点**: `{region}-aiplatform.googleapis.com`
|
||||
- **认证**: `GoogleAuth` + `cloud-platform` scope
|
||||
- **文件**: `src/services/api/client.ts:228-298`
|
||||
|
||||
### 4. Azure Foundry
|
||||
|
||||
- **端点**: `https://{resource}.services.ai.azure.com/anthropic/v1/messages`
|
||||
- **认证**: API Key 或 Azure AD `DefaultAzureCredential`
|
||||
- **文件**: `src/services/api/client.ts:191-220`
|
||||
|
||||
### 5. OAuth
|
||||
|
||||
OAuth 2.0 + PKCE 授权码流程。
|
||||
|
||||
- **端点**:
|
||||
- `https://platform.claude.com/oauth/authorize` — 授权页
|
||||
- `https://claude.com/cai/oauth/authorize` — Claude.ai 授权
|
||||
- `https://platform.claude.com/v1/oauth/token` — Token 交换
|
||||
- `https://api.anthropic.com/api/oauth/claude_cli/create_api_key` — 创建 API Key
|
||||
- `https://api.anthropic.com/api/oauth/claude_cli/roles` — 获取角色
|
||||
- `https://claude.ai/oauth/claude-code-client-metadata` — MCP 客户端元数据
|
||||
- `https://claude.fedstart.com` — FedStart 政府部署
|
||||
- **文件**: `src/constants/oauth.ts`, `src/services/oauth/`
|
||||
|
||||
### 6. GrowthBook (功能开关)
|
||||
|
||||
- **端点**: `https://api.anthropic.com/` (remoteEval 模式) 或 `CLAUDE_GB_ADAPTER_URL`
|
||||
- **SDK Keys**: `sdk-zAZezfDKGoZuXXKe` (外部), `sdk-xRVcrliHIlrg4og4` (ant prod), `sdk-yZQvlplybuXjYh6L` (ant dev)
|
||||
- **文件**: `src/services/analytics/growthbook.ts`, `src/constants/keys.ts`
|
||||
|
||||
### 7. Sentry (错误追踪)
|
||||
|
||||
- **激活**: 设置 `SENTRY_DSN` (默认未配置)
|
||||
- **行为**: 仅错误上报，自动过滤敏感 header
|
||||
- **文件**: `src/utils/sentry.ts`
|
||||
|
||||
### 8. Datadog (日志)
|
||||
|
||||
- **激活**: 同时设 `DATADOG_LOGS_ENDPOINT` + `DATADOG_API_KEY` (默认未配置)
|
||||
- **文件**: `src/services/analytics/datadog.ts`
|
||||
|
||||
### 9. OpenTelemetry Collector
|
||||
|
||||
- **激活**: `CLAUDE_CODE_ENABLE_TELEMETRY=1` 或 `OTEL_*` 环境变量
|
||||
- **协议**: gRPC / HTTP / Protobuf，支持 OTLP 和 Prometheus 导出
|
||||
- **文件**: `src/utils/telemetry/instrumentation.ts`
|
||||
|
||||
### 10. 1P Event Logging (内部事件)
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/event_logging/batch`
|
||||
- **协议**: 批量导出 (10s 间隔, 每批 200 事件)
|
||||
- **文件**: `src/services/analytics/firstPartyEventLoggingExporter.ts`
|
||||
|
||||
### 11. BigQuery Metrics
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/claude_code/metrics`
|
||||
- **文件**: `src/utils/telemetry/bigqueryExporter.ts`
|
||||
|
||||
### 12. MCP Proxy
|
||||
|
||||
Anthropic 托管的 MCP 服务器代理。
|
||||
|
||||
- **端点**: `https://mcp-proxy.anthropic.com/v1/mcp/{server_id}`
|
||||
- **认证**: Claude.ai OAuth tokens
|
||||
- **文件**: `src/services/mcp/client.ts`, `src/constants/oauth.ts`
|
||||
|
||||
### 13. MCP Registry
|
||||
|
||||
获取官方 MCP 服务器列表。
|
||||
|
||||
- **端点**: `https://api.anthropic.com/mcp-registry/v0/servers?version=latest&visibility=commercial`
|
||||
- **文件**: `src/services/mcp/officialRegistry.ts`
|
||||
|
||||
### 14. Bing Search
|
||||
|
||||
WebSearch 工具的默认适配器，抓取 Bing 搜索结果。
|
||||
|
||||
- **端点**: `https://www.bing.com/search?q={query}&setmkt=en-US`
|
||||
- **文件**: `src/tools/WebSearchTool/adapters/bingAdapter.ts`
|
||||
|
||||
另外还有 Domain Blocklist 查询:
|
||||
- **端点**: `https://api.anthropic.com/api/web/domain_info?domain={domain}`
|
||||
- **文件**: `src/tools/WebFetchTool/utils.ts`
|
||||
|
||||
### 15. Google Cloud Storage (自动更新)
|
||||
|
||||
- **端点**: `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases`
|
||||
- **文件**: `src/utils/autoUpdater.ts`
|
||||
|
||||
### 16. GitHub Raw Content
|
||||
|
||||
- **端点**: `https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md`
|
||||
- **端点**: `https://raw.githubusercontent.com/anthropics/claude-plugins-official/refs/heads/stats/stats/plugin-installs.json`
|
||||
- **文件**: `src/utils/releaseNotes.ts`, `src/utils/plugins/installCounts.ts`
|
||||
|
||||
### 17. Claude in Chrome Bridge
|
||||
|
||||
- **端点**: `wss://bridge.claudeusercontent.com` (生产) / `wss://bridge-staging.claudeusercontent.com` (staging)
|
||||
- **文件**: `src/utils/claudeInChrome/mcpServer.ts`
|
||||
|
||||
### 18. CCR Upstream Proxy
|
||||
|
||||
- **端点**: `ws://api.anthropic.com/v1/code/upstreamproxy/ws`
|
||||
- **激活**: `CLAUDE_CODE_REMOTE=1` + `CCR_UPSTREAM_PROXY_ENABLED=1`
|
||||
- **文件**: `src/upstreamproxy/upstreamproxy.ts`
|
||||
|
||||
### 19. Voice STT
|
||||
|
||||
- **端点**: `wss://api.anthropic.com/api/ws/...`
|
||||
- **文件**: `src/services/voiceStreamSTT.ts`
|
||||
|
||||
### 20. Desktop App Download
|
||||
|
||||
- **端点**: `https://claude.ai/api/desktop/win32/x64/exe/latest/redirect` (Windows)
|
||||
- **端点**: `https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect` (macOS)
|
||||
- **文件**: `src/components/DesktopHandoff.tsx`
|
||||
|
||||
---
|
||||
|
||||
## Anthropic API 辅助端点汇总
|
||||
|
||||
以下端点都挂在 `api.anthropic.com` 上，按功能分类:
|
||||
|
||||
| 端点路径 | 用途 | 文件 |
|
||||
|---|---|---|
|
||||
| `/api/event_logging/batch` | 事件批量上报 | `src/services/analytics/firstPartyEventLoggingExporter.ts` |
|
||||
| `/api/claude_code/metrics` | BigQuery 指标导出 | `src/utils/telemetry/bigqueryExporter.ts` |
|
||||
| `/api/oauth/claude_cli/create_api_key` | 创建 API Key | `src/constants/oauth.ts` |
|
||||
| `/api/oauth/claude_cli/roles` | 获取用户角色 | `src/constants/oauth.ts` |
|
||||
| `/api/oauth/accounts/grove` | 通知设置 | `src/services/api/grove.ts` |
|
||||
| `/api/oauth/organizations/{id}/referral/*` | 推荐活动 | `src/services/api/referral.ts` |
|
||||
| `/api/oauth/organizations/{id}/overage_credit_grant` | 超额信用 | `src/services/api/overageCreditGrant.ts` |
|
||||
| `/api/oauth/organizations/{id}/admin_requests` | 管理请求 | `src/services/api/adminRequests.ts` |
|
||||
| `/api/web/domain_info?domain={}` | 域名安全检查 | `src/tools/WebFetchTool/utils.ts` |
|
||||
| `/api/claude_code/settings` | 设置同步 | `src/services/settingsSync/index.ts` |
|
||||
| `/api/claude_code/managed_settings` | 企业托管设置 (1h 轮询) | `src/services/remoteManagedSettings/index.ts` |
|
||||
| `/api/claude_code/team_memory?repo={}` | 团队记忆同步 | `src/services/teamMemorySync/index.ts` |
|
||||
| `/api/auth/trusted_devices` | 可信设备注册 | `src/bridge/trustedDevice.ts` |
|
||||
| `/api/organizations/{id}/claude_code/buddy_react` | Companion 反应 | `src/buddy/companionReact.ts` |
|
||||
| `/mcp-registry/v0/servers` | MCP 服务器注册表 | `src/services/mcp/officialRegistry.ts` |
|
||||
| `/v1/files` | 文件上传/下载 | `src/services/api/filesApi.ts` |
|
||||
| `/v1/sessions/{id}/events` | 会话历史 | `src/assistant/sessionHistory.ts` |
|
||||
| `/v1/code/triggers` | 远程触发器 | `src/tools/RemoteTriggerTool/RemoteTriggerTool.ts` |
|
||||
| `/v1/organizations/{id}/mcp_servers` | 组织 MCP 配置 | `src/services/mcp/claudeai.ts` |
|
||||
|
||||
## 非 Anthropic 远程域名汇总
|
||||
|
||||
| 域名 | 服务 | 协议 |
|
||||
|---|---|---|
|
||||
| `bedrock-runtime.*.amazonaws.com` | AWS Bedrock | HTTPS |
|
||||
| `{region}-aiplatform.googleapis.com` | Google Vertex AI | HTTPS |
|
||||
| `{resource}.services.ai.azure.com` | Azure Foundry | HTTPS |
|
||||
| `www.bing.com` | Bing 搜索 | HTTPS |
|
||||
| `storage.googleapis.com` | 自动更新 | HTTPS |
|
||||
| `raw.githubusercontent.com` | Changelog / 插件统计 | HTTPS |
|
||||
| `bridge.claudeusercontent.com` | Chrome Bridge | WSS |
|
||||
| `platform.claude.com` | OAuth 授权页 | HTTPS |
|
||||
| `claude.com` / `claude.ai` | OAuth / 下载 | HTTPS |
|
||||
| `claude.fedstart.com` | FedStart OAuth | HTTPS |
|
||||
4
docs/favicon.svg
Normal file
4
docs/favicon.svg
Normal file
@@ -0,0 +1,4 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
|
||||
<circle cx="16" cy="16" r="14" fill="#D97706"/>
|
||||
<path d="M12 10l10 6-10 6V10z" fill="#FFFFFF"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 180 B |
457
docs/feature-exploration-plan.md
Normal file
457
docs/feature-exploration-plan.md
Normal file
@@ -0,0 +1,457 @@
|
||||
# Feature 探索计划书
|
||||
|
||||
> 生成日期：2026-04-02
|
||||
> 代码库中已识别 89 个 feature flag，本文档按实现完整度和探索价值分级，制定探索优先级和路线图。
|
||||
>
|
||||
> **已完成**：BUDDY（✅ 2026-04-02）、TRANSCRIPT_CLASSIFIER / Auto Mode（✅ 2026-04-02）
|
||||
|
||||
---
|
||||
|
||||
## 一、总览
|
||||
|
||||
### 按实现状态分类
|
||||
|
||||
| 状态 | 数量 | 说明 |
|
||||
|------|------|------|
|
||||
| 已实现/可用 | 11 | 代码完整，开启 feature 后可运行（可能需要 OAuth 等外部依赖） |
|
||||
| 部分实现 | 8 | 核心逻辑存在但关键模块为 stub，需要补全 |
|
||||
| 纯 Stub | 15 | 所有函数/工具返回空值，需要从零实现 |
|
||||
| N/A | 55+ | 内部基础设施、低引用量辅助功能，或反编译丢失过多 |
|
||||
|
||||
### 启用方式
|
||||
|
||||
所有 feature 通过环境变量启用：
|
||||
|
||||
```bash
|
||||
# 单个 feature
|
||||
FEATURE_BUDDY=1 bun run dev
|
||||
|
||||
# 多个 feature 组合
|
||||
FEATURE_KAIROS=1 FEATURE_PROACTIVE=1 FEATURE_FORK_SUBAGENT=1 bun run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、Tier 1 — 已实现/可用（优先探索）
|
||||
|
||||
### 2.1 KAIROS（常驻助手模式）⭐ 最高优先级
|
||||
|
||||
- **引用数**：154（全库最大）
|
||||
- **功能**：将 CLI 变为常驻后台助手，支持：
|
||||
- 持久化 bridge 会话（跨重启复用 session）
|
||||
- 后台执行任务（用户离开终端时继续工作）
|
||||
- 推送通知到移动端（任务完成/需要输入时）
|
||||
- 每日记忆日志 + `/dream` 知识蒸馏
|
||||
- 外部频道消息接入（Slack/Discord/Telegram）
|
||||
- **子 Feature**：
|
||||
|
||||
| 子 Feature | 引用 | 功能 |
|
||||
|-----------|------|------|
|
||||
| `KAIROS_BRIEF` | 39 | Brief 工具（`SendUserMessage`），结构化消息输出 |
|
||||
| `KAIROS_CHANNELS` | 19 | 外部频道消息接入 |
|
||||
| `KAIROS_PUSH_NOTIFICATION` | 4 | 移动端推送通知 |
|
||||
| `KAIROS_GITHUB_WEBHOOKS` | 3 | GitHub PR webhook 订阅 |
|
||||
| `KAIROS_DREAM` | 1 | 夜间记忆蒸馏 |
|
||||
|
||||
- **关键文件**：`src/assistant/`、`src/tools/BriefTool/`、`src/services/mcp/channelNotification.ts`、`src/memdir/memdir.ts`
|
||||
- **外部依赖**：Anthropic OAuth（claude.ai 订阅）、GrowthBook 特性门控
|
||||
- **探索命令**：`FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_PROACTIVE=1 bun run dev`
|
||||
|
||||
**探索步骤**：
|
||||
1. 开启 feature，观察启动行为变化
|
||||
2. 测试 `/assistant`、`/brief` 命令
|
||||
3. 验证 BriefTool 输出模式
|
||||
4. 尝试频道消息接入
|
||||
5. 测试 `/dream` 记忆蒸馏
|
||||
|
||||
---
|
||||
|
||||
### ~~2.2 TRANSCRIPT_CLASSIFIER（Auto Mode 分类器）~~ ✅ 已完成
|
||||
|
||||
- **引用数**：108
|
||||
- **功能**：使用 LLM 对用户意图进行分类，实现 auto mode（自动决定工具权限）
|
||||
- **状态**：✅ prompt 模板已重建，功能完整可用（2026-04-02 完成）
|
||||
|
||||
---
|
||||
|
||||
### 2.3 VOICE_MODE（语音输入）
|
||||
|
||||
- **引用数**：46
|
||||
- **功能**：按键说话（Push-to-Talk），音频流式传输到 Anthropic STT 端点（Nova 3），实时转录显示
|
||||
- **当前状态**：**完整实现**，包括录音、WebSocket 流、转录插入
|
||||
- **关键文件**：`src/voice/voiceModeEnabled.ts`、`src/hooks/useVoice.ts`、`src/services/voiceStreamSTT.ts`
|
||||
- **外部依赖**：Anthropic OAuth（非 API key）、macOS 原生音频或 SoX
|
||||
- **探索命令**：`FEATURE_VOICE_MODE=1 bun run dev`
|
||||
- **默认快捷键**：长按空格键录音
|
||||
|
||||
**探索步骤**：
|
||||
1. 确认 OAuth token 可用
|
||||
2. 测试按住空格录音 → 释放后转录
|
||||
3. 验证实时中间转录显示
|
||||
4. 测试 `/voice` 命令切换
|
||||
|
||||
---
|
||||
|
||||
### 2.4 TEAMMEM（团队共享记忆）
|
||||
|
||||
- **引用数**：51
|
||||
- **功能**：基于 GitHub 仓库的团队共享记忆系统，`memory/team/` 目录双向同步到 Anthropic 服务器
|
||||
- **当前状态**：**完整实现**，包括增量同步、冲突解决、密钥扫描、路径穿越防护
|
||||
- **关键文件**：`src/services/teamMemorySync/`（index、watcher、secretScanner）、`src/memdir/teamMemPaths.ts`
|
||||
- **外部依赖**：Anthropic OAuth + GitHub remote（`getGithubRepo()`）
|
||||
- **探索命令**：`FEATURE_TEAMMEM=1 bun run dev`
|
||||
|
||||
**探索步骤**：
|
||||
1. 确认项目有 GitHub remote
|
||||
2. 开启后观察 `memory/team/` 目录创建
|
||||
3. 测试团队记忆写入和同步
|
||||
4. 验证密钥扫描防护
|
||||
|
||||
---
|
||||
|
||||
### 2.5 COORDINATOR_MODE（多 Agent 编排）
|
||||
|
||||
- **引用数**：32
|
||||
- **功能**：CLI 变为编排者，通过 AgentTool 派发任务给多个 worker 并行执行
|
||||
- **当前状态**：核心逻辑实现，worker agent 模块为 stub
|
||||
- **关键文件**：`src/coordinator/coordinatorMode.ts`（系统 prompt 完整）、`src/coordinator/workerAgent.ts`（stub）
|
||||
- **限制**：编排者只能使用 AgentTool/TaskStop/SendMessage，不能直接操作文件
|
||||
- **探索命令**：`FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev`
|
||||
|
||||
**探索步骤**：
|
||||
1. 补全 `workerAgent.ts` stub
|
||||
2. 测试多 worker 并行任务派发
|
||||
3. 验证 worker 结果汇总
|
||||
|
||||
---
|
||||
|
||||
### 2.6 BRIDGE_MODE（远程控制）
|
||||
|
||||
- **引用数**：28
|
||||
- **功能**：本地 CLI 注册为 bridge 环境，可从 claude.ai 或其他控制面远程驱动
|
||||
- **当前状态**：v1（env-based）和 v2（env-less）实现均存在
|
||||
- **关键文件**：`src/bridge/bridgeEnabled.ts`、`src/bridge/replBridge.ts`（v1）、`src/bridge/remoteBridgeCore.ts`（v2）
|
||||
- **外部依赖**：claude.ai OAuth、GrowthBook 门控 `tengu_ccr_bridge`
|
||||
- **探索命令**：`FEATURE_BRIDGE_MODE=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.7 FORK_SUBAGENT（上下文继承子 Agent）
|
||||
|
||||
- **引用数**：4
|
||||
- **功能**：AgentTool 生成 fork 子 agent，继承父级完整对话上下文，优化 prompt cache
|
||||
- **当前状态**：**完整实现**（`forkSubagent.ts`），支持 worktree 隔离通知、递归防护
|
||||
- **关键文件**：`src/tools/AgentTool/forkSubagent.ts`
|
||||
- **探索命令**：`FEATURE_FORK_SUBAGENT=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.8 TOKEN_BUDGET（Token 预算控制）
|
||||
|
||||
- **引用数**：9
|
||||
- **功能**：解析用户指定的 token 预算（如 "spend 2M tokens"），自动持续工作直到达到目标
|
||||
- **当前状态**：解析器**完整实现**，支持简写和详细语法；QueryEngine 中的周转逻辑已连接
|
||||
- **关键文件**：`src/utils/tokenBudget.ts`、`src/QueryEngine.ts`
|
||||
- **探索命令**：`FEATURE_TOKEN_BUDGET=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.9 MCP_SKILLS（MCP 技能发现）
|
||||
|
||||
- **引用数**：9
|
||||
- **功能**：将 MCP 服务器提供的 prompt 类型命令筛选为可调用技能
|
||||
- **当前状态**：**功能性实现**（config 门控筛选器）
|
||||
- **关键文件**：`src/commands.ts`（`getMcpSkillCommands()`）
|
||||
- **探索命令**：`FEATURE_MCP_SKILLS=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.10 TREE_SITTER_BASH（Bash AST 解析）
|
||||
|
||||
- **引用数**：3
|
||||
- **功能**：纯 TypeScript bash 命令 AST 解析器，用于 fail-closed 权限匹配
|
||||
- **当前状态**：**完整实现**（`bashParser.ts` ~2000行 + `ast.ts` ~400行）
|
||||
- **关键文件**：`src/utils/vendor/tree-sitter-bash/`
|
||||
- **探索命令**：`FEATURE_TREE_SITTER_BASH=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### ~~2.11 BUDDY（虚拟伙伴）~~ ✅ 已完成
|
||||
|
||||
- **引用数**：16
|
||||
- **功能**：`/buddy` 命令，支持 hatch/rehatch/pet/mute/unmute
|
||||
- **状态**：✅ 已合入，功能完整可用（2026-04-02 完成）
|
||||
|
||||
---
|
||||
|
||||
## 三、Tier 2 — 部分实现（需要补全）
|
||||
|
||||
### 3.1 PROACTIVE（主动模式）
|
||||
|
||||
- **引用数**：37
|
||||
- **功能**：Tick 驱动的自主代理，定时唤醒执行工作，配合 SleepTool 控制节奏
|
||||
- **当前状态**：核心模块 `src/proactive/index.ts` **全部 stub**（activate/deactivate/pause 返回 false 或空操作）
|
||||
- **依赖**：与 KAIROS 强绑定（所有检查都是 `feature('PROACTIVE') || feature('KAIROS')`）
|
||||
- **补全工作量**：中等 — 需要实现 tick 生成、SleepTool 集成、暂停/恢复逻辑
|
||||
|
||||
### 3.2 BASH_CLASSIFIER（Bash 命令分类器）
|
||||
|
||||
- **引用数**：45
|
||||
- **功能**：LLM 驱动的 bash 命令意图分类（允许/拒绝/询问）
|
||||
- **当前状态**：`bashClassifier.ts` **全部 stub**（`matches: false`）
|
||||
- **补全工作量**：大 — 需要 LLM 调用实现、prompt 设计
|
||||
|
||||
### 3.3 ULTRAPLAN（增强规划）
|
||||
|
||||
- **引用数**：10
|
||||
- **功能**：关键字触发增强计划模式，输入 "ultraplan" 自动转为 plan
|
||||
- **当前状态**：关键字检测**完整实现**，`/ultraplan` 命令**为 stub**
|
||||
- **补全工作量**：小 — 只需实现命令处理逻辑
|
||||
|
||||
### 3.4 EXPERIMENTAL_SKILL_SEARCH（技能语义搜索）
|
||||
|
||||
- **引用数**：21
|
||||
- **功能**：DiscoverSkills 工具，根据当前任务语义搜索可用技能
|
||||
- **当前状态**：布线完整，核心搜索逻辑 stub
|
||||
- **补全工作量**：中等 — 需要实现搜索引擎和索引
|
||||
|
||||
### 3.5 CONTEXT_COLLAPSE（上下文折叠）
|
||||
|
||||
- **引用数**：20
|
||||
- **功能**：CtxInspectTool 让模型内省上下文窗口大小，优化压缩决策
|
||||
- **当前状态**：工具 stub，HISTORY_SNIP 子功能也 stub
|
||||
- **补全工作量**：中等
|
||||
|
||||
### 3.6 WORKFLOW_SCRIPTS（工作流自动化）
|
||||
|
||||
- **引用数**：10
|
||||
- **功能**：基于文件的自动化工作流 + `/workflows` 命令
|
||||
- **当前状态**：WorkflowTool、命令、加载器全部 stub
|
||||
- **补全工作量**：大 — 需要从零设计工作流 DSL
|
||||
|
||||
### 3.7 WEB_BROWSER_TOOL（浏览器工具）
|
||||
|
||||
- **引用数**：4
|
||||
- **功能**：模型可调用浏览器工具导航和交互网页
|
||||
- **当前状态**：工具注册存在，实现 stub
|
||||
- **补全工作量**：大
|
||||
|
||||
### 3.8 DAEMON（后台守护进程）
|
||||
|
||||
- **引用数**：3
|
||||
- **功能**：后台守护进程 + 远程控制服务器
|
||||
- **当前状态**：只有条件导入布线，无实现
|
||||
- **补全工作量**：极大
|
||||
|
||||
---
|
||||
|
||||
## 四、Tier 3 — 纯 Stub / N/A（低优先级）
|
||||
|
||||
| Feature | 引用 | 状态 | 说明 |
|
||||
|---------|------|------|------|
|
||||
| CHICAGO_MCP | 16 | N/A | Anthropic 内部 MCP 基础设施 |
|
||||
| UDS_INBOX | 17 | Stub | Unix 域套接字对等消息 |
|
||||
| MONITOR_TOOL | 13 | Stub | 文件/进程监控工具 |
|
||||
| BG_SESSIONS | 11 | Stub | 后台会话管理 |
|
||||
| SHOT_STATS | 10 | 无实现 | 逐 prompt 统计 |
|
||||
| EXTRACT_MEMORIES | 7 | 无实现 | 自动记忆提取 |
|
||||
| TEMPLATES | 6 | Stub | 项目/提示模板 |
|
||||
| LODESTONE | 6 | N/A | 内部基础设施 |
|
||||
| STREAMLINED_OUTPUT | 1 | — | 精简输出模式 |
|
||||
| HOOK_PROMPTS | 1 | — | Hook 提示词 |
|
||||
| CCR_AUTO_CONNECT | 3 | — | CCR 自动连接 |
|
||||
| CCR_MIRROR | 4 | — | CCR 镜像模式 |
|
||||
| CCR_REMOTE_SETUP | 1 | — | CCR 远程设置 |
|
||||
| NATIVE_CLIPBOARD_IMAGE | 2 | — | 原生剪贴板图片 |
|
||||
| CONNECTOR_TEXT | 7 | — | 连接器文本 |
|
||||
|
||||
以及其余 40+ 个低引用量 feature。
|
||||
|
||||
---
|
||||
|
||||
## 五、探索路线图
|
||||
|
||||
### Phase 1：快速验证（无外部依赖）
|
||||
|
||||
> 目标：确认代码可以正常运行，体验基本功能
|
||||
|
||||
| 优先级 | Feature | 命令 | 预期效果 |
|
||||
|--------|---------|------|----------|
|
||||
| 1 | BUDDY | `FEATURE_BUDDY=1 bun run dev` | `/buddy hatch` 生成伙伴 |
|
||||
| 2 | FORK_SUBAGENT | `FEATURE_FORK_SUBAGENT=1 bun run dev` | Agent 可生成上下文继承的子任务 |
|
||||
| 3 | TOKEN_BUDGET | `FEATURE_TOKEN_BUDGET=1 bun run dev` | 输入 "spend 500k tokens" 测试自动持续 |
|
||||
| 4 | TREE_SITTER_BASH | `FEATURE_TREE_SITTER_BASH=1 bun run dev` | 更精确的 bash 权限匹配 |
|
||||
| 5 | MCP_SKILLS | `FEATURE_MCP_SKILLS=1 bun run dev` | MCP 服务器 prompt 提升为技能 |
|
||||
|
||||
### Phase 2：核心功能探索（需要 OAuth）
|
||||
|
||||
> 目标：体验 KAIROS 全套能力
|
||||
|
||||
| 优先级 | Feature | 命令 | 预期效果 |
|
||||
|--------|---------|------|----------|
|
||||
| 1 | TRANSCRIPT_CLASSIFIER | `FEATURE_TRANSCRIPT_CLASSIFIER=1 bun run dev` | Auto mode 自动激活 |
|
||||
| 2 | KAIROS 全套 | `FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_KAIROS_CHANNELS=1 FEATURE_PROACTIVE=1 bun run dev` | 常驻助手 + Brief 输出 + 频道消息 |
|
||||
| 3 | VOICE_MODE | `FEATURE_VOICE_MODE=1 bun run dev` | 按空格说话 |
|
||||
| 4 | TEAMMEM | `FEATURE_TEAMMEM=1 bun run dev` | 团队记忆同步 |
|
||||
| 5 | COORDINATOR_MODE | `FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev` | 多 agent 编排 |
|
||||
|
||||
### Phase 3：Stub 补全开发
|
||||
|
||||
> 目标：将高价值 stub 实现为可用功能
|
||||
|
||||
| 优先级 | Feature | 补全难度 | 价值 |
|
||||
|--------|---------|----------|------|
|
||||
| 1 | PROACTIVE | 中 | 自主工作能力 |
|
||||
| 2 | ULTRAPLAN | 小 | 增强规划 |
|
||||
| 3 | CONTEXT_COLLAPSE | 中 | 长对话优化 |
|
||||
| 4 | EXPERIMENTAL_SKILL_SEARCH | 中 | 技能发现 |
|
||||
| 5 | BASH_CLASSIFIER | 大 | 安全增强 |
|
||||
|
||||
---
|
||||
|
||||
## 六、推荐组合方案
|
||||
|
||||
### "全功能助手"组合
|
||||
|
||||
```bash
|
||||
FEATURE_KAIROS=1 \
|
||||
FEATURE_KAIROS_BRIEF=1 \
|
||||
FEATURE_KAIROS_CHANNELS=1 \
|
||||
FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
|
||||
FEATURE_PROACTIVE=1 \
|
||||
FEATURE_FORK_SUBAGENT=1 \
|
||||
FEATURE_TOKEN_BUDGET=1 \
|
||||
FEATURE_TRANSCRIPT_CLASSIFIER=1 \
|
||||
FEATURE_BUDDY=1 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### "多 Agent 协作"组合
|
||||
|
||||
```bash
|
||||
FEATURE_COORDINATOR_MODE=1 \
|
||||
FEATURE_FORK_SUBAGENT=1 \
|
||||
FEATURE_BRIDGE_MODE=1 \
|
||||
FEATURE_BG_SESSIONS=1 \
|
||||
CLAUDE_CODE_COORDINATOR_MODE=1 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### "开发者增强"组合
|
||||
|
||||
```bash
|
||||
FEATURE_TRANSCRIPT_CLASSIFIER=1 \
|
||||
FEATURE_TREE_SITTER_BASH=1 \
|
||||
FEATURE_TOKEN_BUDGET=1 \
|
||||
FEATURE_MCP_SKILLS=1 \
|
||||
FEATURE_CONTEXT_COLLAPSE=1 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、风险与注意事项
|
||||
|
||||
1. **OAuth 依赖**：KAIROS、VOICE_MODE、TEAMMEM、BRIDGE_MODE 需要 Anthropic OAuth 认证（claude.ai 订阅），API key 用户无法使用
|
||||
2. **GrowthBook 门控**：部分功能（VOICE_MODE 的 `tengu_cobalt_frost`、TEAMMEM 的 `tengu_herring_clock`）即使 feature flag 开启，还需要服务端 GrowthBook 开关
|
||||
3. **反编译不完整**：所有"已实现"功能均为反编译产物，可能存在运行时错误，需要逐个验证
|
||||
4. **Proactive stub**：KAIROS 的自主工作能力依赖 PROACTIVE，但 PROACTIVE 核心是 stub，需先补全
|
||||
5. **tsc 错误**：代码库有 ~1341 个 TypeScript 编译错误（来自反编译），不影响 Bun 运行时但在 IDE 中会有大量红线
|
||||
|
||||
---
|
||||
|
||||
## 附录：Feature Flag 完整列表
|
||||
|
||||
共 89 个 feature flag（按引用数降序）：
|
||||
|
||||
| Feature | 引用 | Tier |
|
||||
|---------|------|------|
|
||||
| KAIROS | 154 | 1 |
|
||||
| TRANSCRIPT_CLASSIFIER | 108 | 1 |
|
||||
| TEAMMEM | 51 | 1 |
|
||||
| VOICE_MODE | 46 | 1 |
|
||||
| BASH_CLASSIFIER | 45 | 2 |
|
||||
| KAIROS_BRIEF | 39 | 1 |
|
||||
| PROACTIVE | 37 | 2 |
|
||||
| COORDINATOR_MODE | 32 | 1 |
|
||||
| BRIDGE_MODE | 28 | 1 |
|
||||
| EXPERIMENTAL_SKILL_SEARCH | 21 | 2 |
|
||||
| CONTEXT_COLLAPSE | 20 | 2 |
|
||||
| KAIROS_CHANNELS | 19 | 1 |
|
||||
| UDS_INBOX | 17 | 3 |
|
||||
| CHICAGO_MCP | 16 | 3 |
|
||||
| BUDDY | 16 | 1 |
|
||||
| HISTORY_SNIP | 15 | 2 |
|
||||
| MONITOR_TOOL | 13 | 3 |
|
||||
| COMMIT_ATTRIBUTION | 12 | — |
|
||||
| CACHED_MICROCOMPACT | 12 | — |
|
||||
| BG_SESSIONS | 11 | 3 |
|
||||
| WORKFLOW_SCRIPTS | 10 | 2 |
|
||||
| ULTRAPLAN | 10 | 2 |
|
||||
| SHOT_STATS | 10 | 3 |
|
||||
| TOKEN_BUDGET | 9 | 1 |
|
||||
| PROMPT_CACHE_BREAK_DETECTION | 9 | — |
|
||||
| MCP_SKILLS | 9 | 1 |
|
||||
| EXTRACT_MEMORIES | 7 | 3 |
|
||||
| CONNECTOR_TEXT | 7 | — |
|
||||
| TEMPLATES | 6 | 3 |
|
||||
| LODESTONE | 6 | 3 |
|
||||
| TREE_SITTER_BASH_SHADOW | 5 | — |
|
||||
| QUICK_SEARCH | 5 | — |
|
||||
| MESSAGE_ACTIONS | 5 | — |
|
||||
| DOWNLOAD_USER_SETTINGS | 5 | — |
|
||||
| DIRECT_CONNECT | 5 | — |
|
||||
| WEB_BROWSER_TOOL | 4 | 2 |
|
||||
| VERIFICATION_AGENT | 4 | — |
|
||||
| TERMINAL_PANEL | 4 | — |
|
||||
| SSH_REMOTE | 4 | — |
|
||||
| REVIEW_ARTIFACT | 4 | — |
|
||||
| REACTIVE_COMPACT | 4 | — |
|
||||
| KAIROS_PUSH_NOTIFICATION | 4 | 1 |
|
||||
| HISTORY_PICKER | 4 | — |
|
||||
| FORK_SUBAGENT | 4 | 1 |
|
||||
| CCR_MIRROR | 4 | — |
|
||||
| TREE_SITTER_BASH | 3 | 1 |
|
||||
| MEMORY_SHAPE_TELEMETRY | 3 | — |
|
||||
| MCP_RICH_OUTPUT | 3 | — |
|
||||
| KAIROS_GITHUB_WEBHOOKS | 3 | 1 |
|
||||
| FILE_PERSISTENCE | 3 | — |
|
||||
| DAEMON | 3 | 2 |
|
||||
| CCR_AUTO_CONNECT | 3 | — |
|
||||
| UPLOAD_USER_SETTINGS | 2 | — |
|
||||
| POWERSHELL_AUTO_MODE | 2 | — |
|
||||
| OVERFLOW_TEST_TOOL | 2 | — |
|
||||
| NEW_INIT | 2 | — |
|
||||
| NATIVE_CLIPBOARD_IMAGE | 2 | — |
|
||||
| HARD_FAIL | 2 | — |
|
||||
| ENHANCED_TELEMETRY_BETA | 2 | — |
|
||||
| COWORKER_TYPE_TELEMETRY | 2 | — |
|
||||
| BREAK_CACHE_COMMAND | 2 | — |
|
||||
| AWAY_SUMMARY | 2 | — |
|
||||
| AUTO_THEME | 2 | — |
|
||||
| ALLOW_TEST_VERSIONS | 2 | — |
|
||||
| AGENT_TRIGGERS_REMOTE | 2 | — |
|
||||
| AGENT_MEMORY_SNAPSHOT | 2 | — |
|
||||
| UNATTENDED_RETRY | 1 | — |
|
||||
| ULTRATHINK | 1 | — |
|
||||
| TORCH | 1 | — |
|
||||
| STREAMLINED_OUTPUT | 1 | — |
|
||||
| SLOW_OPERATION_LOGGING | 1 | — |
|
||||
| SKILL_IMPROVEMENT | 1 | — |
|
||||
| SELF_HOSTED_RUNNER | 1 | — |
|
||||
| RUN_SKILL_GENERATOR | 1 | — |
|
||||
| PERFETTO_TRACING | 1 | — |
|
||||
| NATIVE_CLIENT_ATTESTATION | 1 | — |
|
||||
| KAIROS_DREAM | 1 | 1 |
|
||||
| IS_LIBC_MUSL | 1 | — |
|
||||
| IS_LIBC_GLIBC | 1 | — |
|
||||
| HOOK_PROMPTS | 1 | — |
|
||||
| DUMP_SYSTEM_PROMPT | 1 | — |
|
||||
| COMPACTION_REMINDERS | 1 | — |
|
||||
| CCR_REMOTE_SETUP | 1 | — |
|
||||
| BYOC_ENVIRONMENT_RUNNER | 1 | — |
|
||||
| BUILTIN_EXPLORE_PLAN_AGENTS | 1 | — |
|
||||
| BUILDING_CLAUDE_APPS | 1 | — |
|
||||
| ANTI_DISTILLATION_CC | 1 | — |
|
||||
| AGENT_TRIGGERS | 1 | — |
|
||||
| ABLATION_BASELINE | 1 | — |
|
||||
107
docs/features/bash-classifier.md
Normal file
107
docs/features/bash-classifier.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# BASH_CLASSIFIER — Bash 命令分类器
|
||||
|
||||
> Feature Flag: `FEATURE_BASH_CLASSIFIER=1`
|
||||
> 实现状态：bashClassifier.ts 全部 Stub，yoloClassifier.ts 完整实现可参考
|
||||
> 引用数：45
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
BASH_CLASSIFIER 使用 LLM 对 bash 命令进行意图分类（允许/拒绝/询问），实现自动权限决策。用户不需要逐个审批 bash 命令，分类器根据命令内容和上下文自动判断安全性。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **LLM 驱动分类**：使用 Opus 模型评估命令安全性
|
||||
- **两阶段分类**：快速阻止/允许 → 深度思考链
|
||||
- **自动审批**：分类器判定安全的命令自动通过
|
||||
- **UI 集成**：权限对话框显示分类器状态和审核选项
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| Bash 分类器 | `src/utils/permissions/bashClassifier.ts` | **Stub** | 所有函数返回空操作。注释："ANT-ONLY" |
|
||||
| YOLO 分类器 | `src/utils/permissions/yoloClassifier.ts` | **完整** | 1496 行，两阶段 XML 分类器 |
|
||||
| 审批信号 | `src/utils/classifierApprovals.ts` | **完整** | Map + 信号管理分类器决策 |
|
||||
| 权限 UI | `src/components/permissions/BashPermissionRequest.tsx` | **布线** | 分类器状态显示、审核选项 |
|
||||
| 权限管道 | `src/hooks/toolPermission/handlers/*.ts` | **布线** | 分类器结果路由到决策 |
|
||||
| API beta 标头 | `src/services/api/withRetry.ts` | **布线** | 启用时发送 `bash_classifier` beta |
|
||||
|
||||
### 2.2 参考实现：yoloClassifier.ts
|
||||
|
||||
文件：`src/utils/permissions/yoloClassifier.ts`（1496 行）
|
||||
|
||||
这是已实现的完整分类器，可作为 bashClassifier.ts 的参考：
|
||||
|
||||
```
|
||||
两阶段分类：
|
||||
1. 快速阶段：构建对话记录 → 调用 sideQuery（Opus）→ 快速阻止/允许
|
||||
2. 深度阶段：思考链分析 → 最终决策
|
||||
```
|
||||
|
||||
特性：
|
||||
- 构建完整对话记录上下文
|
||||
- 调用安全系统提示的 sideQuery
|
||||
- GrowthBook 配置和指标
|
||||
- 错误处理和降级
|
||||
|
||||
### 2.3 分类器在权限管道中的位置
|
||||
|
||||
```
|
||||
bash 命令到达
|
||||
│
|
||||
▼
|
||||
bashPermissions.ts 权限检查
|
||||
│
|
||||
├── 传统规则匹配（字符串级别）
|
||||
│
|
||||
└── [BASH_CLASSIFIER] LLM 分类
|
||||
│
|
||||
├── allow → 自动通过
|
||||
├── deny → 自动拒绝
|
||||
└── ask → 显示权限对话框
|
||||
│
|
||||
├── 分类器自动审批标记
|
||||
└── 审核选项（用户可覆盖）
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 函数 | 需要实现 | 说明 |
|
||||
|------|---------|------|
|
||||
| `classifyBashCommand()` | LLM 调用评估安全性 | 参考 yoloClassifier.ts 的两阶段模式 |
|
||||
| `isClassifierPermissionsEnabled()` | GrowthBook/配置检查 | 控制分类器是否激活 |
|
||||
| `getBashPromptDenyDescriptions()` | 返回基于提示的拒绝规则 | 权限设置描述 |
|
||||
| `getBashPromptAskDescriptions()` | 返回询问规则 | 需要用户确认的命令 |
|
||||
| `getBashPromptAllowDescriptions()` | 返回允许规则 | 自动通过的命令 |
|
||||
| `generateGenericDescription()` | LLM 生成命令描述 | 为权限对话框提供说明 |
|
||||
| `extractPromptDescription()` | 解析规则内容 | 从规则中提取描述 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **ANT-ONLY 标记**：bashClassifier.ts 标注为 "ANT-ONLY"，可能是 Anthropic 内部服务端分类器的客户端适配
|
||||
2. **两阶段分类**：快速阶段处理明确情况（减少延迟），深度阶段处理模糊情况
|
||||
3. **分类器结果可审核**：权限 UI 显示分类器决策，用户可覆盖
|
||||
4. **YOLO 分类器参考**：yoloClassifier.ts 提供完整的分类器实现模式，可直接参考
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_BASH_CLASSIFIER=1 bun run dev
|
||||
|
||||
# 配合 TREE_SITTER_BASH 使用（AST + LLM 双重安全）
|
||||
FEATURE_BASH_CLASSIFIER=1 FEATURE_TREE_SITTER_BASH=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/utils/permissions/bashClassifier.ts` | — | Bash 分类器（stub，ANT-ONLY） |
|
||||
| `src/utils/permissions/yoloClassifier.ts` | 1496 | YOLO 分类器（完整参考实现） |
|
||||
| `src/utils/classifierApprovals.ts` | — | 分类器审批信号管理 |
|
||||
| `src/components/permissions/BashPermissionRequest.tsx:261-469` | — | 分类器 UI |
|
||||
| `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
|
||||
| `src/services/api/withRetry.ts:81` | — | API beta 标头 |
|
||||
158
docs/features/bridge-mode.md
Normal file
158
docs/features/bridge-mode.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# BRIDGE_MODE — 远程控制
|
||||
|
||||
> Feature Flag: `FEATURE_BRIDGE_MODE=1`
|
||||
> 实现状态：完整可用（v1 + v2 实现）
|
||||
> 引用数：28
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他控制面远程驱动。本地终端变为一个"执行者"，接受远程指令并执行。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **环境注册**：本地 CLI 向 Anthropic 服务器注册为可用的 bridge 环境
|
||||
- **工作轮询**：长轮询（long-poll）等待远程任务分配
|
||||
- **会话管理**：创建、恢复、归档远程会话
|
||||
- **权限透传**：远程权限请求发送到控制面，用户在 claude.ai 上批准/拒绝
|
||||
- **心跳保活**：定期发送 heartbeat 延长任务租约
|
||||
- **可信设备**：v2 支持可信设备令牌增强安全性
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 版本演进
|
||||
|
||||
| 版本 | 实现 | 特点 |
|
||||
|------|------|------|
|
||||
| v1（env-based） | `src/bridge/replBridge.ts` | 基于环境变量的传统 bridge |
|
||||
| v2（env-less） | `src/bridge/remoteBridgeCore.ts` | 无需环境变量，更安全的 bridge |
|
||||
|
||||
### 2.2 API 协议
|
||||
|
||||
文件：`src/bridge/bridgeApi.ts`
|
||||
|
||||
Bridge API Client 提供 7 个核心操作：
|
||||
|
||||
| 操作 | HTTP | 说明 |
|
||||
|------|------|------|
|
||||
| `registerBridgeEnvironment` | POST `/v1/environments/bridge` | 注册本地环境，获取 `environment_id` + `environment_secret` |
|
||||
| `pollForWork` | GET `/v1/environments/{id}/work/poll` | 长轮询等待任务（10s 超时） |
|
||||
| `acknowledgeWork` | POST `/v1/environments/{id}/work/{workId}/ack` | 确认接收任务 |
|
||||
| `stopWork` | POST `/v1/environments/{id}/work/{workId}/stop` | 停止任务 |
|
||||
| `heartbeatWork` | POST `/v1/environments/{id}/work/{workId}/heartbeat` | 续约任务租约 |
|
||||
| `deregisterEnvironment` | DELETE `/v1/environments/bridge/{id}` | 注销环境 |
|
||||
| `archiveSession` | POST `/v1/sessions/{id}/archive` | 归档会话（409 = 已归档，幂等） |
|
||||
| `sendPermissionResponseEvent` | POST `/v1/sessions/{id}/events` | 发送权限审批结果 |
|
||||
| `reconnectSession` | POST `/v1/environments/{id}/bridge/reconnect` | 重连已存在的会话 |
|
||||
|
||||
### 2.3 认证流程
|
||||
|
||||
```
|
||||
注册: OAuth Bearer Token → 获取 environment_secret
|
||||
轮询: environment_secret 作为 Authorization
|
||||
├── 401 → 尝试 OAuth token 刷新（onAuth401）
|
||||
└── 刷新成功 → 重试一次
|
||||
```
|
||||
|
||||
**OAuth 刷新**：API client 内置 `withOAuthRetry` 机制。401 时调用 `handleOAuth401Error`（同 withRetry.ts 的 v1/messages 模式），刷新后重试一次。
|
||||
|
||||
### 2.4 安全设计
|
||||
|
||||
- **路径穿越防护**：`validateBridgeId()` 使用 `/^[a-zA-Z0-9_-]+$/` 白名单验证所有服务端 ID
|
||||
- **BridgeFatalError**：不可重试的错误（401/403/404/410）直接抛出，阻止重试循环
|
||||
- **可信设备令牌**：v2 通过 `X-Trusted-Device-Token` header 增强安全层级
|
||||
- **幂关注册**：支持 `reuseEnvironmentId` 实现会话恢复，避免重复创建环境
|
||||
|
||||
### 2.5 数据流
|
||||
|
||||
```
|
||||
claude.ai 用户选择远程环境
|
||||
│
|
||||
▼
|
||||
POST /v1/environments/bridge (注册)
|
||||
│
|
||||
◀── environment_id + environment_secret
|
||||
│
|
||||
▼
|
||||
GET .../work/poll (长轮询)
|
||||
│
|
||||
◀── WorkResponse { id, data: { type, sessionId } }
|
||||
│
|
||||
▼
|
||||
POST .../work/{id}/ack (确认)
|
||||
│
|
||||
▼
|
||||
sessionRunner 创建 REPL session
|
||||
│
|
||||
├── 权限请求 → sendPermissionResponseEvent
|
||||
├── 心跳 → heartbeatWork (续约)
|
||||
└── 任务完成 → 自动归档
|
||||
```
|
||||
|
||||
### 2.6 模块结构
|
||||
|
||||
| 模块 | 文件 | 职责 |
|
||||
|------|------|------|
|
||||
| API Client | `bridgeApi.ts` | HTTP 通信（注册/轮询/确认/心跳/注销） |
|
||||
| Session Runner | `sessionRunner.ts` | 创建/恢复 REPL 会话 |
|
||||
| Bridge Config | `bridgeConfig.ts` | 配置管理（machine name、max sessions 等） |
|
||||
| Transport | `replBridgeTransport.ts` | Bridge 传输层 |
|
||||
| Permission Callbacks | `bridgePermissionCallbacks.ts` | 权限请求处理 |
|
||||
| Pointer | `bridgePointer.ts` | 当前活跃 bridge 状态指针 |
|
||||
| Flush Gate | `flushGate.ts` | 刷新控制 |
|
||||
| JWT Utils | `jwtUtils.ts` | JWT 令牌工具 |
|
||||
| Trusted Device | `trustedDevice.ts` | 可信设备管理 |
|
||||
| Debug Utils | `debugUtils.ts` | 调试日志 |
|
||||
| Types | `types.ts` | 类型定义 |
|
||||
|
||||
## 三、关键设计决策
|
||||
|
||||
1. **长轮询而非 WebSocket**：`pollForWork` 使用 HTTP GET + 10s 超时。简单可靠，无需维护 WebSocket 连接
|
||||
2. **OAuth 刷新内嵌**：API client 自带 `withOAuthRetry`，无需外层重试逻辑
|
||||
3. **ETag 条件请求**：注册时支持 `reuseEnvironmentId` 实现幂等会话恢复
|
||||
4. **v1/v2 共存**：代码中同时存在两套实现，v2 是更安全的升级版
|
||||
5. **权限双向流动**：本地权限请求发送到 claude.ai，用户在 web 上审批
|
||||
|
||||
## 四、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 bridge mode
|
||||
FEATURE_BRIDGE_MODE=1 bun run dev
|
||||
|
||||
# 从 claude.ai/code 远程连接
|
||||
# 在 web 界面选择已注册的环境
|
||||
|
||||
# 配合 DAEMON 使用（后台守护）
|
||||
FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev
|
||||
```
|
||||
|
||||
## 五、外部依赖
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic OAuth | claude.ai 订阅登录 |
|
||||
| GrowthBook | `tengu_ccr_bridge` 门控 |
|
||||
| Bridge API | `/v1/environments/bridge` 系列端点 |
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/bridge/bridgeApi.ts` | 540 | API Client（核心） |
|
||||
| `src/bridge/sessionRunner.ts` | — | 会话运行器 |
|
||||
| `src/bridge/bridgeConfig.ts` | — | 配置管理 |
|
||||
| `src/bridge/replBridgeTransport.ts` | — | 传输层 |
|
||||
| `src/bridge/bridgePermissionCallbacks.ts` | — | 权限回调 |
|
||||
| `src/bridge/bridgePointer.ts` | — | 状态指针 |
|
||||
| `src/bridge/flushGate.ts` | — | 刷新控制 |
|
||||
| `src/bridge/jwtUtils.ts` | — | JWT 工具 |
|
||||
| `src/bridge/trustedDevice.ts` | — | 可信设备 |
|
||||
| `src/bridge/remoteBridgeCore.ts` | — | v2 核心实现 |
|
||||
| `src/bridge/types.ts` | — | 类型定义 |
|
||||
| `src/bridge/debugUtils.ts` | — | 调试工具 |
|
||||
| `src/bridge/pollConfigDefaults.ts` | — | 轮询配置默认值 |
|
||||
| `src/bridge/bridgeUI.ts` | — | UI 组件 |
|
||||
| `src/bridge/codeSessionApi.ts` | — | 代码会话 API |
|
||||
| `src/bridge/peerSessions.ts` | — | 对等会话管理 |
|
||||
| `src/bridge/sessionIdCompat.ts` | — | Session ID 兼容层 |
|
||||
| `src/bridge/createSession.ts` | — | 会话创建 |
|
||||
| `src/bridge/replBridgeHandle.ts` | — | Bridge 句柄 |
|
||||
87
docs/features/buddy.mdx
Normal file
87
docs/features/buddy.mdx
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: "Buddy 宠物系统"
|
||||
description: "Buddy 是 CLI 中的虚拟宠物伴侣，通过 /buddy 命令孵化、互动，会出现在输入框旁边陪伴你写代码。"
|
||||
keywords: ["buddy", "宠物", "companion", "伴侣", "虚拟宠物"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
Buddy 是 Claude Code 内置的虚拟宠物系统。在 REPL 中通过 `/buddy` 命令可以孵化一只随机生成的宠物伴侣，它会出现在输入框旁边，陪伴你的编码过程。
|
||||
|
||||
> Feature Flag: `FEATURE_BUDDY=1`
|
||||
|
||||
## 启用方式
|
||||
|
||||
```bash
|
||||
FEATURE_BUDDY=1 bun run dev
|
||||
```
|
||||
|
||||
孵化窗口：2026 年 4 月 1-7 日期间启动时，会在 REPL 顶部显示彩虹色的 `/buddy` 提示。4 月 7 日之后命令仍然可用，但不再自动提示。
|
||||
|
||||
## 命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|---|---|
|
||||
| `/buddy` | 查看当前宠物信息和属性 |
|
||||
| `/buddy hatch` | 孵化一只新宠物（首次使用） |
|
||||
| `/buddy rehatch` | 重新随机生成宠物（替换现有） |
|
||||
| `/buddy pet` | 撸宠物，触发爱心动画 |
|
||||
| `/buddy mute` | 静音宠物（隐藏） |
|
||||
| `/buddy unmute` | 取消静音 |
|
||||
|
||||
## 宠物属性
|
||||
|
||||
### 物种（18 种）
|
||||
|
||||
| | | | |
|
||||
|---|---|---|---|
|
||||
| Duck | Goose | Blob | Cat |
|
||||
| Dragon | Octopus | Owl | Penguin |
|
||||
| Turtle | Snail | Ghost | Axolotl |
|
||||
| Capybara | Cactus | Robot | Rabbit |
|
||||
| Mushroom | Chonk | | |
|
||||
|
||||
### 稀有度
|
||||
|
||||
| 稀有度 | 星级 | 权重 |
|
||||
|---|---|---|
|
||||
| Common | ★ | 60% |
|
||||
| Uncommon | ★★ | 25% |
|
||||
| Rare | ★★★ | 10% |
|
||||
| Epic | ★★★★ | 4% |
|
||||
| Legendary | ★★★★★ | 1% |
|
||||
|
||||
孵化时基于种子随机决定，存在极低概率出现 Shiny（闪光）变体。
|
||||
|
||||
### 属性值
|
||||
|
||||
每只宠物拥有 5 项属性（0-100）：
|
||||
|
||||
- **DEBUGGING** — 调试能力
|
||||
- **PATIENCE** — 耐心程度
|
||||
- **CHAOS** — 混乱指数
|
||||
- **WISDOM** — 智慧值
|
||||
- **SNARK** — 毒舌度
|
||||
|
||||
### 外观
|
||||
|
||||
每只宠物还有随机的外观配件：
|
||||
|
||||
- **眼睛**: `·` `✦` `×` `◉` `@` `°`
|
||||
- **帽子**: none, crown, tophat, propeller, halo, wizard, beanie, tinyduck
|
||||
|
||||
## 数据存储
|
||||
|
||||
宠物信息存储在 `~/.claude.json` 的 `companion` 字段中。宠物的外观属性（物种、稀有度、属性值等）基于用户 ID 的哈希确定性生成，不可通过编辑配置文件来篡改稀有度。
|
||||
|
||||
## 相关源码
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `src/commands/buddy/buddy.ts` | `/buddy` 命令处理 |
|
||||
| `src/buddy/companion.ts` | 宠物生成与加载 |
|
||||
| `src/buddy/types.ts` | 类型定义（物种、稀有度、属性） |
|
||||
| `src/buddy/sprites.ts` | 终端像素画渲染 |
|
||||
| `src/buddy/CompanionSprite.tsx` | React 组件（输入框旁显示） |
|
||||
| `src/buddy/useBuddyNotification.tsx` | 启动提示通知 |
|
||||
| `src/buddy/prompt.ts` | 宠物相关 prompt 模板 |
|
||||
140
docs/features/context-collapse.md
Normal file
140
docs/features/context-collapse.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# CONTEXT_COLLAPSE — 上下文折叠
|
||||
|
||||
> Feature Flag: `FEATURE_CONTEXT_COLLAPSE=1`
|
||||
> 子 Feature: `FEATURE_HISTORY_SNIP=1`
|
||||
> 实现状态：核心逻辑全部 Stub，布线完整
|
||||
> 引用数：CONTEXT_COLLAPSE 20 + HISTORY_SNIP 16 = 36
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧消息。当对话接近上下文限制时，自动将旧消息折叠为压缩摘要，保留关键信息的同时释放 token 空间。
|
||||
|
||||
### 子 Feature
|
||||
|
||||
| Feature | 功能 |
|
||||
|---------|------|
|
||||
| `CONTEXT_COLLAPSE` | 上下文折叠引擎（后台 LLM 调用压缩旧消息） |
|
||||
| `HISTORY_SNIP` | SnipTool — 标记消息进行折叠/修剪 |
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整（`ContextCollapseStats`、`CollapseResult`、`DrainResult`），函数全部空操作 |
|
||||
| 折叠操作 | `src/services/contextCollapse/operations.ts` | **Stub** — `projectView` 为恒等函数 |
|
||||
| 折叠持久化 | `src/services/contextCollapse/persist.ts` | **Stub** — `restoreFromEntries` 为空操作 |
|
||||
| CtxInspectTool | `src/tools/CtxInspectTool/` | **缺失** — 目录不存在 |
|
||||
| SnipTool 提示 | `src/tools/SnipTool/prompt.ts` | **Stub** — 空工具名 |
|
||||
| SnipTool 实现 | `src/tools/SnipTool/SnipTool.ts` | **缺失** |
|
||||
| force-snip 命令 | `src/commands/force-snip.js` | **缺失** |
|
||||
| 折叠读取搜索 | `src/utils/collapseReadSearch.ts` | **完整** — Snip 作为静默吸收操作 |
|
||||
| QueryEngine 集成 | `src/QueryEngine.ts` | **布线** — 导入并使用 snip 投影 |
|
||||
| Token 警告 UI | `src/components/TokenWarning.tsx` | **布线** — 折叠进度标签 |
|
||||
|
||||
### 2.2 核心接口（已定义，待实现）
|
||||
|
||||
```ts
|
||||
// contextCollapse/index.ts
|
||||
interface ContextCollapseStats {
|
||||
// 上下文使用统计
|
||||
}
|
||||
interface CollapseResult {
|
||||
// 折叠操作结果
|
||||
}
|
||||
interface DrainResult {
|
||||
// 紧急释放结果
|
||||
}
|
||||
|
||||
// 关键函数（全部 stub）：
|
||||
isContextCollapseEnabled() // → false
|
||||
applyCollapsesIfNeeded(messages) // 透传
|
||||
recoverFromOverflow(messages) // 透传（413 恢复）
|
||||
initContextCollapse() // 空操作
|
||||
```
|
||||
|
||||
### 2.3 预期数据流
|
||||
|
||||
```
|
||||
对话持续增长
|
||||
│
|
||||
▼
|
||||
上下文接近限制（由 query.ts 检测）
|
||||
│
|
||||
├── 溢出检测 (query.ts:440,616,802)
|
||||
│
|
||||
▼
|
||||
applyCollapsesIfNeeded(messages) [需要实现]
|
||||
│
|
||||
├── 后台 LLM 调用压缩旧消息
|
||||
├── 保留关键信息（决策、文件路径、错误）
|
||||
└── 替换旧消息为压缩摘要
|
||||
│
|
||||
├── 413 恢复 (query.ts:1093,1179)
|
||||
│ └── recoverFromOverflow() 紧急折叠
|
||||
│
|
||||
▼
|
||||
projectView() 过滤折叠后的消息视图
|
||||
│
|
||||
▼
|
||||
模型继续工作（在压缩后的上下文中）
|
||||
```
|
||||
|
||||
### 2.4 HISTORY_SNIP 子功能
|
||||
|
||||
SnipTool 提供手动折叠能力：
|
||||
|
||||
- `/force-snip` 命令 — 强制执行折叠
|
||||
- SnipTool — 标记特定消息进行折叠/修剪
|
||||
- `collapseReadSearch.ts` 已完整实现，将 Snip 作为静默吸收操作处理
|
||||
|
||||
### 2.5 集成点
|
||||
|
||||
| 文件 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/query.ts` | 18,440,616,802,1093,1179 | 溢出检测、413 恢复、折叠应用 |
|
||||
| `src/QueryEngine.ts` | 124,127,1301 | Snip 投影使用 |
|
||||
| `src/utils/analyzeContext.ts` | 1122 | 跳过保留缓冲区显示 |
|
||||
| `src/utils/sessionRestore.ts` | 127,494 | 恢复折叠状态 |
|
||||
| `src/services/compact/autoCompact.ts` | 179,215 | 自动压缩时考虑折叠 |
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `services/contextCollapse/index.ts` | 大 | 折叠状态机、LLM 调用、消息压缩 |
|
||||
| 2 | `services/contextCollapse/operations.ts` | 中 | `projectView()` 消息过滤 |
|
||||
| 3 | `services/contextCollapse/persist.ts` | 小 | `restoreFromEntries()` 磁盘持久化 |
|
||||
| 4 | `tools/CtxInspectTool/` | 中 | 上下文内省工具（token 计数、已折叠范围） |
|
||||
| 5 | `tools/SnipTool/SnipTool.ts` | 中 | Snip 工具实现 |
|
||||
| 6 | `commands/force-snip.js` | 小 | `/force-snip` 命令 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **后台 LLM 压缩**：折叠不是简单截断，而是用 LLM 生成压缩摘要保留关键信息
|
||||
2. **413 恢复**：当 API 返回 413（请求过大）时，紧急折叠是最重要的恢复手段
|
||||
3. **与 autoCompact 协作**：折叠和自动压缩（compact）是不同的机制，折叠在消息级别，压缩在对话级别
|
||||
4. **持久化**：折叠状态持久化到磁盘，会话恢复时重载
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 context collapse
|
||||
FEATURE_CONTEXT_COLLAPSE=1 bun run dev
|
||||
|
||||
# 启用 snip 子功能
|
||||
FEATURE_CONTEXT_COLLAPSE=1 FEATURE_HISTORY_SNIP=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/services/contextCollapse/index.ts` | 折叠核心（stub，接口已定义） |
|
||||
| `src/services/contextCollapse/operations.ts` | 投影操作（stub） |
|
||||
| `src/services/contextCollapse/persist.ts` | 持久化（stub） |
|
||||
| `src/utils/collapseReadSearch.ts` | Snip 吸收操作（完整） |
|
||||
| `src/query.ts` | 溢出检测和 413 恢复集成 |
|
||||
| `src/QueryEngine.ts` | Snip 投影使用 |
|
||||
| `src/components/TokenWarning.tsx` | 折叠进度 UI |
|
||||
151
docs/features/coordinator-mode.md
Normal file
151
docs/features/coordinator-mode.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# COORDINATOR_MODE — 多 Agent 编排
|
||||
|
||||
> Feature Flag: `FEATURE_COORDINATOR_MODE=1` + 环境变量 `CLAUDE_CODE_COORDINATOR_MODE=1`
|
||||
> 实现状态：编排者完整可用，worker agent 为通用 AgentTool worker
|
||||
> 引用数：32
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
COORDINATOR_MODE 将 CLI 变为"编排者"角色。编排者不直接操作文件，而是通过 AgentTool 派发任务给多个 worker 并行执行。适用于大型任务拆分、并行研究、实现+验证分离等场景。
|
||||
|
||||
### 核心约束
|
||||
|
||||
- 编排者只能使用：`Agent`（派发 worker）、`SendMessage`（继续 worker）、`TaskStop`（停止 worker）
|
||||
- Worker 可以使用所有标准工具（Bash、Read、Edit 等）+ MCP 工具 + Skill 工具
|
||||
- 编排者的每条消息都是给用户看的；worker 结果以 `<task-notification>` XML 形式到达
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 启用方式
|
||||
|
||||
```bash
|
||||
FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
|
||||
```
|
||||
|
||||
需要同时设置 feature flag 和环境变量。`CLAUDE_CODE_COORDINATOR_MODE` 可在会话恢复时自动切换（`matchSessionMode`）。
|
||||
|
||||
### 典型工作流
|
||||
|
||||
```
|
||||
用户: "修复 auth 模块的 null pointer"
|
||||
|
||||
编排者:
|
||||
1. 并行派发两个 worker:
|
||||
- Agent({ description: "调查 auth bug", prompt: "..." })
|
||||
- Agent({ description: "研究 auth 测试", prompt: "..." })
|
||||
|
||||
2. 收到 <task-notification>:
|
||||
- Worker A: "在 validate.ts:42 发现 null pointer"
|
||||
- Worker B: "测试覆盖情况..."
|
||||
|
||||
3. 综合发现，继续 Worker A:
|
||||
- SendMessage({ to: "agent-a1b", message: "修复 validate.ts:42..." })
|
||||
|
||||
4. 收到修复结果，派发验证:
|
||||
- Agent({ description: "验证修复", prompt: "..." })
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 模式检测
|
||||
|
||||
文件：`src/coordinator/coordinatorMode.ts:36-41`
|
||||
|
||||
```ts
|
||||
export function isCoordinatorMode(): boolean {
|
||||
return feature('COORDINATOR_MODE') &&
|
||||
isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 会话模式恢复
|
||||
|
||||
`matchSessionMode(sessionMode)` 在恢复旧会话时检查存储的模式，如果当前环境变量与存储不一致，自动翻转环境变量。防止在普通模式下恢复编排会话（或反之）。
|
||||
|
||||
### 3.3 Worker 工具集
|
||||
|
||||
`getCoordinatorUserContext()` 告知编排者 worker 可用的工具列表：
|
||||
|
||||
- **标准模式**：`ASYNC_AGENT_ALLOWED_TOOLS` 排除内部工具（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）
|
||||
- **Simple 模式**（`CLAUDE_CODE_SIMPLE=1`）：仅 Bash、Read、Edit
|
||||
- **MCP 工具**：列出已连接的 MCP 服务器名称
|
||||
- **Scratchpad**：如果 GrowthBook `tengu_scratch` 启用，提供跨 worker 共享的 scratchpad 目录
|
||||
|
||||
### 3.4 系统提示
|
||||
|
||||
文件：`src/coordinator/coordinatorMode.ts:111-369`
|
||||
|
||||
编排者系统提示（`getCoordinatorSystemPrompt()`）约 370 行，包含：
|
||||
|
||||
| 章节 | 内容 |
|
||||
|------|------|
|
||||
| 1. Your Role | 编排者职责定义 |
|
||||
| 2. Your Tools | Agent/SendMessage/TaskStop 使用说明 |
|
||||
| 3. Workers | Worker 能力和限制 |
|
||||
| 4. Task Workflow | Research → Synthesis → Implementation → Verification 流程 |
|
||||
| 5. Writing Worker Prompts | 自包含 prompt 编写指南 + 好坏示例对比 |
|
||||
| 6. Example Session | 完整示例对话 |
|
||||
|
||||
### 3.5 Worker Agent
|
||||
|
||||
文件：`src/coordinator/workerAgent.ts`
|
||||
|
||||
当前为 stub。Worker 实际使用通用 AgentTool 的 `worker` subagent_type。
|
||||
|
||||
### 3.6 数据流
|
||||
|
||||
```
|
||||
用户消息
|
||||
│
|
||||
▼
|
||||
编排者 REPL（受限工具集）
|
||||
│
|
||||
├──→ Agent({ subagent_type: "worker", prompt: "..." })
|
||||
│ │
|
||||
│ ▼
|
||||
│ Worker Agent（完整工具集）
|
||||
│ ├── 执行任务（Bash/Read/Edit/...）
|
||||
│ └── 返回 <task-notification>
|
||||
│
|
||||
├──→ SendMessage({ to: "agent-id", message: "..." })
|
||||
│ │
|
||||
│ ▼
|
||||
│ 继续已存在的 Worker
|
||||
│
|
||||
└──→ TaskStop({ task_id: "agent-id" })
|
||||
│
|
||||
▼
|
||||
停止运行中的 Worker
|
||||
```
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **双开关设计**：feature flag 控制代码可用性，环境变量控制实际激活。允许编译时包含但不默认启用
|
||||
2. **编排者受限**：只能用 Agent/SendMessage/TaskStop，确保编排者专注于派发而非执行
|
||||
3. **Worker 不可见编排者对话**：每个 worker 的 prompt 必须自包含（所有必要上下文）
|
||||
4. **并行优先**：系统提示强调"Parallelism is your superpower"，鼓励并行派发独立任务
|
||||
5. **综合而非转发**：编排者必须理解 worker 发现，再写出具体的实现指令。禁止 "based on your findings" 类懒惰委托
|
||||
6. **Scratchpad 可选共享**：通过 GrowthBook 门控的共享目录，让 worker 之间持久化共享知识
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 基本启用
|
||||
FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
|
||||
|
||||
# 配合 Fork Subagent
|
||||
FEATURE_COORDINATOR_MODE=1 FEATURE_FORK_SUBAGENT=1 \
|
||||
CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
|
||||
|
||||
# Simple 模式（worker 只有 Bash/Read/Edit）
|
||||
FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 \
|
||||
CLAUDE_CODE_SIMPLE=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/coordinator/coordinatorMode.ts` | 370 | 模式检测 + 系统提示 + 用户上下文 |
|
||||
| `src/coordinator/workerAgent.ts` | — | Worker agent 定义（stub） |
|
||||
| `src/constants/tools.ts` | — | `ASYNC_AGENT_ALLOWED_TOOLS` 工具白名单 |
|
||||
102
docs/features/daemon.md
Normal file
102
docs/features/daemon.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# DAEMON — 后台守护进程
|
||||
|
||||
> Feature Flag: `FEATURE_DAEMON=1`
|
||||
> 实现状态：主进程和 worker 注册为 Stub，CLI 路由完整
|
||||
> 引用数：3
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 进程的生命周期，通过 Unix 域套接字进行 IPC。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 守护主进程 | `src/daemon/main.ts` | **Stub** — `daemonMain: () => Promise.resolve()` |
|
||||
| Worker 注册 | `src/daemon/workerRegistry.ts` | **Stub** — `runDaemonWorker: () => Promise.resolve()` |
|
||||
| CLI 路由 | `src/entrypoints/cli.tsx` | **布线** — `--daemon-worker` 和 `daemon` 子命令 |
|
||||
| 命令注册 | `src/commands.ts` | **布线** — DAEMON + BRIDGE_MODE 门控 |
|
||||
|
||||
### 2.2 CLI 入口
|
||||
|
||||
```
|
||||
# 启动守护进程
|
||||
claude daemon
|
||||
|
||||
# 以 worker 身份启动
|
||||
claude --daemon-worker=<kind>
|
||||
```
|
||||
|
||||
### 2.3 预期架构
|
||||
|
||||
```
|
||||
Supervisor (daemonMain)
|
||||
│
|
||||
├── Worker 1: assistant-mode
|
||||
│ └── 接收和处理 assistant 会话
|
||||
│
|
||||
├── Worker 2: bridge-sync
|
||||
│ └── bridge 消息同步
|
||||
│
|
||||
└── Worker 3: proactive
|
||||
└── 主动任务执行
|
||||
│
|
||||
▼
|
||||
IPC via Unix Domain Sockets
|
||||
- 生命周期管理（启动、停止、重启）
|
||||
- 工作分发
|
||||
- 状态报告
|
||||
```
|
||||
|
||||
### 2.4 与 BRIDGE_MODE 的关系
|
||||
|
||||
DAEMON 和 BRIDGE_MODE 常组合使用：
|
||||
|
||||
```ts
|
||||
// src/commands.ts
|
||||
if (feature('DAEMON') && feature('BRIDGE_MODE')) {
|
||||
// 加载 remoteControlServer 命令
|
||||
}
|
||||
```
|
||||
|
||||
双重门控：两个 feature 都需要开启才能使用远程控制服务器。
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 模块 | 工作量 | 说明 |
|
||||
|------|--------|------|
|
||||
| `daemon/main.ts` | 大 | Supervisor 主进程：启动 worker、生命周期管理、IPC |
|
||||
| `daemon/workerRegistry.ts` | 中 | Worker 类型分发（assistant/bridge-sync/proactive） |
|
||||
| Worker 实现 | 大 | 各类型 worker 的具体实现 |
|
||||
| IPC 协议 | 中 | Supervisor-Worker 通信层 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **多进程架构**：一个 supervisor + 多个 worker，进程隔离
|
||||
2. **Unix 域套接字 IPC**：本地进程间通信，低延迟
|
||||
3. **与 BRIDGE_MODE 强绑定**：守护进程最常见的用途是提供远程控制服务
|
||||
4. **CLI 子命令路由**：`daemon` 子命令和 `--daemon-worker` 参数在 `cli.tsx` 中路由
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用守护进程模式
|
||||
FEATURE_DAEMON=1 FEATURE_BRIDGE_MODE=1 bun run dev
|
||||
|
||||
# 启动守护进程
|
||||
claude daemon
|
||||
|
||||
# 以特定 worker 启动
|
||||
claude --daemon-worker=assistant
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/daemon/main.ts` | Supervisor 主进程（stub） |
|
||||
| `src/daemon/workerRegistry.ts` | Worker 注册（stub） |
|
||||
| `src/entrypoints/cli.tsx:95,149` | CLI 路由 |
|
||||
| `src/commands.ts:77` | 命令注册（双重门控） |
|
||||
48
docs/features/debug-mode.mdx
Normal file
48
docs/features/debug-mode.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Debug 模式"
|
||||
description: "通过 VS Code attach 模式调试 CLI 运行时，支持断点、单步执行和变量查看。"
|
||||
keywords: ["debug", "调试", "VS Code", "inspect", "断点"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**连接到正在运行的 Bun 进程。
|
||||
|
||||
## 步骤
|
||||
|
||||
### 1. 终端启动 inspect 服务
|
||||
|
||||
```bash
|
||||
bun run dev:inspect
|
||||
```
|
||||
|
||||
会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
|
||||
|
||||
### 2. VS Code 附着调试器
|
||||
|
||||
1. 在 `src/` 文件中打断点
|
||||
2. F5 → 选择 **"Attach to Bun (TUI debug)"**
|
||||
|
||||
> **注意**：`dev:inspect` 和 `launch.json` 中的 WebSocket 地址会在每次启动时变化，需要同步更新两处。
|
||||
|
||||
## 原理
|
||||
|
||||
`dev:inspect` 脚本实际执行的是：
|
||||
|
||||
```bash
|
||||
bun --inspect-wait=localhost:8888/<token> run scripts/dev.ts
|
||||
```
|
||||
|
||||
Bun 的 `--inspect-wait` 参数启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，等待调试器连接后才开始执行。VS Code 的 `bun` 扩展通过 WebSocket 连接到这个地址实现 attach。
|
||||
|
||||
## JetBrains IDE
|
||||
|
||||
理论上 JetBrains 系列（WebStorm / IntelliJ 等）也支持 attach 到 Bun inspect 服务（Run → Attach to Process），但尚未实际验证过。如果你验证成功，欢迎补充文档。
|
||||
|
||||
## 相关文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `package.json` → `dev:inspect` | 启动 inspect 服务的 npm script |
|
||||
| `.vscode/launch.json` | VS Code attach 调试配置 |
|
||||
| `scripts/dev.ts` | dev 模式入口，注入 MACRO defines |
|
||||
99
docs/features/experimental-skill-search.md
Normal file
99
docs/features/experimental-skill-search.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# EXPERIMENTAL_SKILL_SEARCH — 技能语义搜索
|
||||
|
||||
> Feature Flag: `FEATURE_EXPERIMENTAL_SKILL_SEARCH=1`
|
||||
> 实现状态：全部 Stub（8 个文件），布线完整
|
||||
> 引用数：21
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
EXPERIMENTAL_SKILL_SEARCH 提供 DiscoverSkills 工具，根据当前任务语义搜索可用技能。目标是让模型在执行任务时自动发现和推荐相关的技能（包括本地和远程），无需用户手动查找。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DiscoverSkillsTool | `src/tools/DiscoverSkillsTool/prompt.ts` | **Stub** | 空工具名 |
|
||||
| 预取 | `src/services/skillSearch/prefetch.ts` | **Stub** | 3 个函数全部空操作 |
|
||||
| 远程加载 | `src/services/skillSearch/remoteSkillLoader.ts` | **Stub** | 返回空结果 |
|
||||
| 远程状态 | `src/services/skillSearch/remoteSkillState.ts` | **Stub** | 返回 null/undefined |
|
||||
| 信号 | `src/services/skillSearch/signals.ts` | **Stub** | `DiscoverySignal = any` |
|
||||
| 遥测 | `src/services/skillSearch/telemetry.ts` | **Stub** | 空操作日志 |
|
||||
| 本地搜索 | `src/services/skillSearch/localSearch.ts` | **Stub** | 空操作缓存 |
|
||||
| 功能检查 | `src/services/skillSearch/featureCheck.ts` | **Stub** | `isSkillSearchEnabled => false` |
|
||||
| SkillTool 集成 | `src/tools/SkillTool/SkillTool.ts` | **布线** | 动态加载所有远程技能模块 |
|
||||
| 提示集成 | `src/constants/prompts.ts` | **布线** | DiscoverSkills schema 注入 |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
模型处理用户任务
|
||||
│
|
||||
▼
|
||||
DiscoverSkills 工具触发 [需要实现]
|
||||
│
|
||||
├── 本地搜索：索引已安装技能元数据
|
||||
│ └── localSearch.ts → 技能名称/描述/关键字匹配
|
||||
│
|
||||
└── 远程搜索：查询技能市场/注册表
|
||||
└── remoteSkillLoader.ts → fetch + 解析
|
||||
│
|
||||
▼
|
||||
结果排序和过滤
|
||||
│
|
||||
▼
|
||||
返回推荐技能列表
|
||||
│
|
||||
▼
|
||||
模型使用 SkillTool 调用推荐技能
|
||||
```
|
||||
|
||||
### 2.3 预取机制
|
||||
|
||||
`prefetch.ts` 预期在用户提交输入前分析消息内容，提前搜索相关技能：
|
||||
|
||||
- `startSkillDiscoveryPrefetch()` — 开始预取
|
||||
- `collectSkillDiscoveryPrefetch()` — 收集预取结果
|
||||
- `getTurnZeroSkillDiscovery()` — 获取 turn 0 的技能发现结果
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `DiscoverSkillsTool` | 大 | 语义搜索工具 schema + 执行 |
|
||||
| 2 | `skillSearch/prefetch.ts` | 中 | 用户输入分析和预取逻辑 |
|
||||
| 3 | `skillSearch/remoteSkillLoader.ts` | 大 | 远程市场/注册表获取 |
|
||||
| 4 | `skillSearch/remoteSkillState.ts` | 小 | 已发现技能状态管理 |
|
||||
| 5 | `skillSearch/localSearch.ts` | 中 | 本地索引构建/查询 |
|
||||
| 6 | `skillSearch/featureCheck.ts` | 小 | GrowthBook/配置门控 |
|
||||
| 7 | `skillSearch/signals.ts` | 小 | `DiscoverySignal` 类型定义 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **预取优化**：在用户提交前就开始搜索，减少首次响应延迟
|
||||
2. **本地+远程双搜索**：本地索引快速匹配 + 远程市场深度搜索
|
||||
3. **SkillTool 集成**：发现的技能通过 SkillTool 调用，不需要新的调用机制
|
||||
4. **独立于 MCP_SKILLS**：MCP_SKILLS 从 MCP 服务器发现，EXPERIMENTAL_SKILL_SEARCH 从技能市场发现
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature（需要补全后才能真正使用）
|
||||
FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/DiscoverSkillsTool/prompt.ts` | 工具 schema（stub） |
|
||||
| `src/services/skillSearch/prefetch.ts` | 预取逻辑（stub） |
|
||||
| `src/services/skillSearch/remoteSkillLoader.ts` | 远程加载（stub） |
|
||||
| `src/services/skillSearch/remoteSkillState.ts` | 远程状态（stub） |
|
||||
| `src/services/skillSearch/signals.ts` | 信号类型（stub） |
|
||||
| `src/services/skillSearch/telemetry.ts` | 遥测（stub） |
|
||||
| `src/services/skillSearch/localSearch.ts` | 本地搜索（stub） |
|
||||
| `src/services/skillSearch/featureCheck.ts` | 功能检查（stub） |
|
||||
| `src/tools/SkillTool/SkillTool.ts` | SkillTool 集成点 |
|
||||
| `src/constants/prompts.ts:95,335,778` | 提示增强 |
|
||||
195
docs/features/fork-subagent.md
Normal file
195
docs/features/fork-subagent.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# FORK_SUBAGENT — 上下文继承子 Agent
|
||||
|
||||
> Feature Flag: `FEATURE_FORK_SUBAGENT=1`
|
||||
> 实现状态：完整可用
|
||||
> 引用数：4
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
FORK_SUBAGENT 让 AgentTool 生成"fork 子 agent"，继承父级完整对话上下文。子 agent 看到父级的所有历史消息、工具集和系统提示，并且与父级共享 API 请求前缀以最大化 prompt cache 命中率。
|
||||
|
||||
### 核心优势
|
||||
|
||||
- **Prompt Cache 最大化**：多个并行 fork 共享相同的 API 请求前缀，只有最后的 directive 文本块不同
|
||||
- **上下文完整性**：子 agent 继承父级的完整对话历史（包括 thinking config）
|
||||
- **权限冒泡**：子 agent 的权限提示上浮到父级终端显示
|
||||
- **Worktree 隔离**：支持 git worktree 隔离，子 agent 在独立分支工作
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 触发方式
|
||||
|
||||
当 `FORK_SUBAGENT` 启用时，AgentTool 调用不指定 `subagent_type` 时自动走 fork 路径：
|
||||
|
||||
```
|
||||
// Fork 路径（继承上下文）
|
||||
Agent({ prompt: "修复这个 bug" }) // 无 subagent_type
|
||||
|
||||
// 普通 agent 路径（全新上下文）
|
||||
Agent({ subagent_type: "general-purpose", prompt: "..." })
|
||||
```
|
||||
|
||||
### /fork 命令
|
||||
|
||||
注册了 `/fork` 斜杠命令（当前为 stub）。当 FORK_SUBAGENT 开启时，`/branch` 命令失去 `fork` 别名，避免冲突。
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 门控与互斥
|
||||
|
||||
文件：`src/tools/AgentTool/forkSubagent.ts:32-39`
|
||||
|
||||
```ts
|
||||
export function isForkSubagentEnabled(): boolean {
|
||||
if (feature('FORK_SUBAGENT')) {
|
||||
if (isCoordinatorMode()) return false // Coordinator 有自己的委派模型
|
||||
if (getIsNonInteractiveSession()) return false // pipe/SDK 模式禁用
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 FORK_AGENT 定义
|
||||
|
||||
```ts
|
||||
export const FORK_AGENT = {
|
||||
agentType: 'fork',
|
||||
tools: ['*'], // 通配符：使用父级完整工具集
|
||||
maxTurns: 200,
|
||||
model: 'inherit', // 继承父级模型
|
||||
permissionMode: 'bubble', // 权限冒泡到父级终端
|
||||
getSystemPrompt: () => '', // 不使用：直接传递父级已渲染 prompt
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 核心调用流程
|
||||
|
||||
```
|
||||
AgentTool.call({ prompt, name })
|
||||
│
|
||||
▼
|
||||
isForkSubagentEnabled() && !subagent_type?
|
||||
│
|
||||
├── No → 普通 agent 路径
|
||||
│
|
||||
└── Yes → Fork 路径
|
||||
│
|
||||
▼
|
||||
递归防护检查
|
||||
├── querySource === 'agent:builtin:fork' → 拒绝
|
||||
└── isInForkChild(messages) → 拒绝
|
||||
│
|
||||
▼
|
||||
获取父级 system prompt
|
||||
├── toolUseContext.renderedSystemPrompt（首选）
|
||||
└── buildEffectiveSystemPrompt（回退）
|
||||
│
|
||||
▼
|
||||
buildForkedMessages(prompt, assistantMessage)
|
||||
├── 克隆父级 assistant 消息
|
||||
├── 生成占位符 tool_result
|
||||
└── 附加 directive 文本块
|
||||
│
|
||||
▼
|
||||
[可选] buildWorktreeNotice()
|
||||
│
|
||||
▼
|
||||
runAgent({
|
||||
useExactTools: true,
|
||||
override.systemPrompt: 父级,
|
||||
forkContextMessages: 父级消息,
|
||||
availableTools: 父级工具,
|
||||
})
|
||||
```
|
||||
|
||||
### 3.4 消息构建：buildForkedMessages
|
||||
|
||||
文件：`src/tools/AgentTool/forkSubagent.ts:107-169`
|
||||
|
||||
构建的消息结构：
|
||||
|
||||
```
|
||||
[
|
||||
...history (filterIncompleteToolCalls), // 父级完整历史
|
||||
assistant(所有 tool_use 块), // 父级当前 turn 的 assistant 消息
|
||||
user(
|
||||
占位符 tool_result × N + // 相同占位符文本
|
||||
<fork-boilerplate> directive // 每个 fork 不同
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
**所有 fork 使用相同的占位符文本**：`"Fork started — processing in background"`。这确保多个并行 fork 的 API 请求前缀完全一致，最大化 prompt cache 命中。
|
||||
|
||||
### 3.5 递归防护
|
||||
|
||||
两层检查防止 fork 嵌套：
|
||||
|
||||
1. **querySource 检查**：`toolUseContext.options.querySource === 'agent:builtin:fork'`。在 `context.options` 上设置，抗自动压缩（autocompact 只重写消息不改 options）
|
||||
2. **消息扫描**：`isInForkChild()` 扫描消息历史中的 `<fork-boilerplate>` 标签
|
||||
|
||||
### 3.6 Worktree 隔离通知
|
||||
|
||||
当 fork + worktree 组合时，追加通知告知子 agent：
|
||||
|
||||
> "你继承了父 agent 在 `{parentCwd}` 的对话上下文，但你在独立的 git worktree `{worktreeCwd}` 中操作。路径需要转换，编辑前重新读取。"
|
||||
|
||||
### 3.7 强制异步
|
||||
|
||||
当 `isForkSubagentEnabled()` 为 true 时，所有 agent 启动都强制异步。`run_in_background` 参数从 schema 中移除。统一通过 `<task-notification>` XML 消息交互。
|
||||
|
||||
## 四、Prompt Cache 优化
|
||||
|
||||
这是整个 fork 设计的核心优化目标：
|
||||
|
||||
| 优化点 | 实现 |
|
||||
|--------|------|
|
||||
| **相同 system prompt** | 直传 `renderedSystemPrompt`，避免重新渲染（GrowthBook 状态可能不一致） |
|
||||
| **相同工具集** | `useExactTools: true` 直接使用父级工具，不经过 `resolveAgentTools` 过滤 |
|
||||
| **相同 thinking config** | 继承父级 thinking 配置（非 fork agent 默认禁用 thinking） |
|
||||
| **相同占位符结果** | 所有 fork 使用 `FORK_PLACEHOLDER_RESULT` 相同文本 |
|
||||
| **ContentReplacementState 克隆** | 默认克隆父级替换状态，保持 wire prefix 一致 |
|
||||
|
||||
## 五、子 Agent 指令
|
||||
|
||||
`buildChildMessage()` 生成 `<fork-boilerplate>` 包裹的指令：
|
||||
|
||||
- 你是 fork worker，不是主 agent
|
||||
- 禁止再次 spawn sub-agent（直接执行）
|
||||
- 不要闲聊、不要元评论
|
||||
- 直接使用工具
|
||||
- 修改文件后要 commit，报告 commit hash
|
||||
- 报告格式：`Scope:` / `Result:` / `Key files:` / `Files changed:` / `Issues:`
|
||||
|
||||
## 六、关键设计决策
|
||||
|
||||
1. **Fork ≠ 普通 agent**：fork 继承完整上下文，普通 agent 从零开始。选择依据是 `subagent_type` 是否存在
|
||||
2. **renderedSystemPrompt 直传**：避免 fork 时重新调用 `getSystemPrompt()`。父级在 turn 开始时冻结 prompt 字节
|
||||
3. **占位符结果共享**：多个并行 fork 使用完全相同的占位符，只有 directive 不同
|
||||
4. **Coordinator 互斥**：Coordinator 模式下禁用 fork，两者有不兼容的委派模型
|
||||
5. **非交互式禁用**：pipe 模式和 SDK 模式下禁用，避免不可见的 fork 嵌套
|
||||
|
||||
## 七、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_FORK_SUBAGENT=1 bun run dev
|
||||
|
||||
# 在 REPL 中使用（不指定 subagent_type 即走 fork）
|
||||
# Agent({ prompt: "研究这个模块的结构" })
|
||||
# Agent({ prompt: "实现这个功能" })
|
||||
```
|
||||
|
||||
## 八、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/tools/AgentTool/forkSubagent.ts` | ~210 | 核心定义 + 消息构建 + 递归防护 |
|
||||
| `src/tools/AgentTool/AgentTool.tsx` | — | Fork 路由 + 强制异步 |
|
||||
| `src/tools/AgentTool/prompt.ts` | — | "When to Fork" 提示词段落 |
|
||||
| `src/tools/AgentTool/runAgent.ts` | — | useExactTools 路径 |
|
||||
| `src/tools/AgentTool/resumeAgent.ts` | — | Fork agent 恢复 |
|
||||
| `src/constants/xml.ts` | — | XML 标签常量 |
|
||||
| `src/utils/forkedAgent.ts` | — | CacheSafeParams + ContentReplacementState 克隆 |
|
||||
| `src/commands/fork/index.ts` | — | /fork 命令（stub） |
|
||||
179
docs/features/kairos.md
Normal file
179
docs/features/kairos.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# KAIROS — 常驻助手模式
|
||||
|
||||
> Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
|
||||
> 实现状态：核心框架完整，部分子模块为 stub
|
||||
> 引用数：154（全库最大）
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
KAIROS 将 Claude Code CLI 从"问答工具"转变为"常驻助手"。开启后，CLI 持续运行在后台，支持：
|
||||
|
||||
- **持久化 bridge 会话**：跨终端重启复用 session，通过 Anthropic OAuth 连接 claude.ai
|
||||
- **后台执行任务**：用户离开终端时继续工作（配合 PROACTIVE feature）
|
||||
- **推送通知到移动端**：任务完成或需要输入时推送（配合 `KAIROS_PUSH_NOTIFICATION`）
|
||||
- **每日记忆日志**：自动记录和回顾工作内容（配合 `KAIROS_DREAM`）
|
||||
- **外部频道消息接入**：Slack/Discord/Telegram 消息转发到 CLI（配合 `KAIROS_CHANNELS`）
|
||||
- **结构化 Brief 输出**：通过 BriefTool 输出结构化消息（配合 `KAIROS_BRIEF`）
|
||||
|
||||
### 子 Feature 依赖关系
|
||||
|
||||
```
|
||||
KAIROS (主开关)
|
||||
├── KAIROS_BRIEF (BriefTool, 结构化输出)
|
||||
├── KAIROS_CHANNELS (外部频道消息)
|
||||
├── KAIROS_PUSH_NOTIFICATION (移动端推送)
|
||||
├── KAIROS_GITHUB_WEBHOOKS (GitHub PR webhook)
|
||||
└── KAIROS_DREAM (记忆蒸馏)
|
||||
```
|
||||
|
||||
**注意**：PROACTIVE 与 KAIROS 强绑定。所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即 KAIROS 开启时自动获得 proactive 能力。
|
||||
|
||||
## 二、系统提示
|
||||
|
||||
KAIROS 在系统提示中注入两大段落：
|
||||
|
||||
### 2.1 Brief 段落 (`getBriefSection`)
|
||||
|
||||
文件：`src/constants/prompts.ts:843-858`
|
||||
|
||||
当 `feature('KAIROS') || feature('KAIROS_BRIEF')` 时注入。Brief 工具（`SendUserMessage`）的结构化消息输出指令。`/brief` toggle 和 `--brief` flag 只控制显示过滤，不影响模型行为。
|
||||
|
||||
### 2.2 Proactive/Autonomous Work 段落 (`getProactiveSection`)
|
||||
|
||||
文件：`src/constants/prompts.ts:860-914`
|
||||
|
||||
当 `feature('PROACTIVE') || feature('KAIROS')` 且 `isProactiveActive()` 时注入。核心行为指令：
|
||||
|
||||
- **Tick 驱动**：通过 `<tick_tag>` prompt 保持存活，每个 tick 包含用户当前本地时间
|
||||
- **节奏控制**：使用 `SleepTool` 控制等待间隔（prompt cache 5 分钟过期）
|
||||
- **空操作时必须 Sleep**：禁止输出 "still waiting" 类文本（浪费 turn 和 token）
|
||||
- **偏向行动**：读文件、搜索代码、修改文件、commit — 都不需询问
|
||||
- **终端焦点感知**：`terminalFocus` 字段指示用户是否在看终端
|
||||
- Unfocused → 高度自主行动
|
||||
- Focused → 更协作，展示选择
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 核心模块
|
||||
|
||||
| 模块 | 文件 | 状态 | 职责 |
|
||||
|------|------|------|------|
|
||||
| Assistant 入口 | `src/assistant/index.ts` | Stub | `isAssistantMode()`、`initializeAssistantTeam()` |
|
||||
| Session 发现 | `src/assistant/sessionDiscovery.ts` | Stub | 发现可用 bridge session |
|
||||
| Session 历史 | `src/assistant/sessionHistory.ts` | Stub | 持久化 session 历史 |
|
||||
| Gate 控制 | `src/assistant/gate.ts` | Stub | GrowthBook 门控检查 |
|
||||
| Session 选择器 | `src/assistant/AssistantSessionChooser.ts` | Stub | UI 选择 session |
|
||||
| BriefTool | `src/tools/BriefTool/` | Stub | 结构化消息输出工具 |
|
||||
| Channel Notification | `src/services/mcp/channelNotification.ts` | Stub | 外部频道消息接入 |
|
||||
| Dream Task | `src/components/tasks/src/tasks/DreamTask/` | Stub | 记忆蒸馏任务 |
|
||||
| Memory Directory | `src/memdir/memdir.ts` | Stub | 记忆目录管理 |
|
||||
|
||||
### 3.2 SleepTool（与 Proactive 共享）
|
||||
|
||||
文件：`src/tools/SleepTool/prompt.ts`
|
||||
|
||||
SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理解"休眠"概念：
|
||||
- 工具名：`Sleep`
|
||||
- 功能：等待指定时间后响应 tick prompt
|
||||
- 与 `<tick_tag>` 配合实现心跳式自主工作
|
||||
|
||||
### 3.3 Bridge 集成
|
||||
|
||||
KAIROS 通过 Bridge Mode（`src/bridge/`）连接到 claude.ai 服务器：
|
||||
|
||||
```
|
||||
claude.ai web/app
|
||||
│
|
||||
▼ (HTTPS long-poll)
|
||||
┌──────────────────────┐
|
||||
│ Bridge API Client │ src/bridge/bridgeApi.ts
|
||||
│ (register/poll/ │
|
||||
│ acknowledge) │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Session Runner │ src/bridge/sessionRunner.ts
|
||||
│ (创建/恢复 REPL) │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ REPL + Proactive │ Tick 驱动自主工作
|
||||
│ Tick Loop │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
### 3.4 数据流
|
||||
|
||||
```
|
||||
用户从 claude.ai 发送消息
|
||||
│
|
||||
▼
|
||||
Bridge pollForWork() 收到 WorkResponse
|
||||
│
|
||||
▼
|
||||
acknowledgeWork() 确认接收
|
||||
│
|
||||
▼
|
||||
sessionRunner 创建/恢复 REPL session
|
||||
│
|
||||
▼
|
||||
用户消息注入到 REPL 对话
|
||||
│
|
||||
▼
|
||||
模型处理 → 工具调用 → BriefTool 结构化输出
|
||||
│
|
||||
▼
|
||||
结果通过 Bridge API 回传到 claude.ai
|
||||
```
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Tick 驱动而非事件驱动**：模型通过 SleepTool 自行控制唤醒频率，而非外部事件推送。简化架构但增加 API 调用开销
|
||||
2. **KAIROS ⊃ PROACTIVE**：所有 proactive 检查都包含 KAIROS，无需同时开启两个 flag
|
||||
3. **Brief 显示/行为分离**：`/brief` toggle 只控制 UI 过滤，模型始终可以使用 BriefTool
|
||||
4. **Terminal Focus 感知**：模型根据用户是否在看终端自动调节自主程度
|
||||
5. **GrowthBook 门控**：部分功能（如推送通知）即使 feature flag 开启还需要服务端 GrowthBook 开关
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 最小启用（常驻助手 + Brief）
|
||||
FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
|
||||
|
||||
# 全功能启用
|
||||
FEATURE_KAIROS=1 \
|
||||
FEATURE_KAIROS_BRIEF=1 \
|
||||
FEATURE_KAIROS_CHANNELS=1 \
|
||||
FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
|
||||
FEATURE_KAIROS_GITHUB_WEBHOOKS=1 \
|
||||
FEATURE_PROACTIVE=1 \
|
||||
bun run dev
|
||||
|
||||
# 配合 Token Budget 使用
|
||||
FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、外部依赖
|
||||
|
||||
- **Anthropic OAuth**：必须使用 claude.ai 订阅登录（非 API key）
|
||||
- **GrowthBook**：服务端特性门控（`tengu_ccr_bridge` 等）
|
||||
- **Bridge API**：`/v1/environments/bridge` 系列端点
|
||||
|
||||
## 七、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/assistant/index.ts` | 9 | Assistant 模块入口（stub） |
|
||||
| `src/assistant/gate.ts` | — | GrowthBook 门控（stub） |
|
||||
| `src/assistant/sessionDiscovery.ts` | — | Session 发现（stub） |
|
||||
| `src/assistant/sessionHistory.ts` | — | Session 历史（stub） |
|
||||
| `src/assistant/AssistantSessionChooser.ts` | — | Session 选择 UI（stub） |
|
||||
| `src/tools/BriefTool/` | — | BriefTool 实现（stub） |
|
||||
| `src/tools/SleepTool/prompt.ts` | ~30 | SleepTool 工具提示 |
|
||||
| `src/services/mcp/channelNotification.ts` | 5 | 频道消息接入（stub） |
|
||||
| `src/memdir/memdir.ts` | — | 记忆目录管理（stub） |
|
||||
| `src/constants/prompts.ts:552-554,843-914` | 72 | 系统提示注入 |
|
||||
| `src/components/tasks/src/tasks/DreamTask/` | 3 | Dream 任务（stub） |
|
||||
| `src/proactive/index.ts` | — | Proactive 核心（stub，KAIROS 共享） |
|
||||
118
docs/features/mcp-skills.md
Normal file
118
docs/features/mcp-skills.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# MCP_SKILLS — MCP 技能发现
|
||||
|
||||
> Feature Flag: `FEATURE_MCP_SKILLS=1`
|
||||
> 实现状态：功能性实现（config 门控筛选器完整，核心 fetcher 为 stub）
|
||||
> 引用数：9
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
MCP_SKILLS 将 MCP 服务器暴露的资源（`skill://` URI 方案）发现并转换为可调用的技能命令。MCP 服务器可以同时提供 tools、prompts 和 resources；启用此 feature 后，带有 `skill://` URI 的资源被识别为技能。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **自动发现**：MCP 服务器连接时自动获取 `skill://` 资源
|
||||
- **命令转换**：将 MCP 资源转换为 `prompt` 类型的 Command 对象
|
||||
- **实时刷新**：prompts/resources 列表变化时重新获取技能
|
||||
- **缓存一致性**：连接关闭时清除技能缓存
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 数据流
|
||||
|
||||
```
|
||||
MCP Server 连接
|
||||
│
|
||||
▼
|
||||
client.ts: connectToServer / setupMcpClientConnections
|
||||
├── fetchToolsForClient (MCP tools)
|
||||
├── fetchCommandsForClient (MCP prompts → Command 对象)
|
||||
├── fetchMcpSkillsForClient (MCP skill:// 资源 → Command 对象) [MCP_SKILLS]
|
||||
└── fetchResourcesForClient (MCP resources)
|
||||
│
|
||||
▼
|
||||
commands = [...mcpPrompts, ...mcpSkills]
|
||||
│
|
||||
▼
|
||||
AppState.mcp.commands 更新
|
||||
│
|
||||
▼
|
||||
getMcpSkillCommands() 过滤 → SkillTool 调用
|
||||
```
|
||||
|
||||
### 2.2 技能筛选
|
||||
|
||||
文件：`src/commands.ts:547-558`
|
||||
|
||||
`getMcpSkillCommands(mcpCommands)` 过滤条件：
|
||||
|
||||
```ts
|
||||
cmd.type === 'prompt' // 必须是 prompt 类型
|
||||
cmd.loadedFrom === 'mcp' // 必须来自 MCP 服务器
|
||||
!cmd.disableModelInvocation // 必须可由模型调用
|
||||
feature('MCP_SKILLS') // feature flag 必须开启
|
||||
```
|
||||
|
||||
### 2.3 条件加载
|
||||
|
||||
文件：`src/services/mcp/client.ts:117-121`
|
||||
|
||||
`fetchMcpSkillsForClient` 通过 `require()` 条件加载，feature flag 关闭时不加载任何模块：
|
||||
|
||||
```ts
|
||||
const fetchMcpSkillsForClient = feature('MCP_SKILLS')
|
||||
? require('../../skills/mcpSkills.js').fetchMcpSkillsForClient
|
||||
: null
|
||||
```
|
||||
|
||||
### 2.4 缓存管理
|
||||
|
||||
技能获取函数维护 `.cache`（Map），在以下时机清除：
|
||||
|
||||
| 事件 | 行为 |
|
||||
|------|------|
|
||||
| 连接关闭 | 清除该 client 的技能缓存 |
|
||||
| `disconnectMcpServer()` | 清除技能缓存 |
|
||||
| `prompts/list_changed` 通知 | 刷新 prompts + 并行获取技能 |
|
||||
| `resources/list_changed` 通知 | 刷新 resources + prompts + 技能 |
|
||||
|
||||
### 2.5 集成点
|
||||
|
||||
| 文件 | 行 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/commands.ts` | 547-558, 561-608 | 命令过滤和 SkillTool 命令收集 |
|
||||
| `src/services/mcp/client.ts` | 117-121, 1394, 1672, 2173-2181, 2346-2358 | 技能获取、缓存清除、连接时获取 |
|
||||
| `src/services/mcp/useManageMCPConnections.ts` | 22-26, 682-740 | 实时刷新（prompts/resources 变化） |
|
||||
|
||||
## 三、关键设计决策
|
||||
|
||||
1. **Feature gate 隔离**：`feature('MCP_SKILLS')` 守护条件 `require()` 和所有调用点。关闭时无模块加载、无获取操作
|
||||
2. **资源到技能映射**：技能从 MCP 服务器的 `skill://` URI 资源中发现。`fetchMcpSkillsForClient` 负责转换（当前为 stub）
|
||||
3. **循环依赖避免**：`mcpSkillBuilders.ts` 作为依赖图叶节点，避免 `client.ts ↔ mcpSkills.ts ↔ loadSkillsDir.ts` 循环
|
||||
4. **服务器能力检查**：技能获取还需要 MCP 服务器支持 resources (`!!client.capabilities?.resources`)
|
||||
|
||||
## 四、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_MCP_SKILLS=1 bun run dev
|
||||
|
||||
# 前提条件：
|
||||
# 1. 配置了支持 skill:// 资源的 MCP 服务器
|
||||
# 2. MCP 服务器声明了 resources 能力
|
||||
```
|
||||
|
||||
## 五、需要补全的内容
|
||||
|
||||
| 文件 | 状态 | 需要实现 |
|
||||
|------|------|---------|
|
||||
| `src/skills/mcpSkills.ts` | Stub | `fetchMcpSkillsForClient()` — 从 MCP 资源列表中筛选 `skill://` URI 并转换为 Command 对象 |
|
||||
| `src/skills/mcpSkillBuilders.ts` | Stub | 技能构建器注册（避免循环依赖） |
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/commands.ts:547-608` | 技能命令过滤 |
|
||||
| `src/services/mcp/client.ts:117-2358` | 技能获取 + 缓存管理 |
|
||||
| `src/services/mcp/useManageMCPConnections.ts` | 实时刷新 |
|
||||
| `src/skills/mcpSkills.ts` | 核心转换逻辑（stub） |
|
||||
109
docs/features/proactive.md
Normal file
109
docs/features/proactive.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# PROACTIVE — 主动模式
|
||||
|
||||
> Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
|
||||
> 实现状态：核心模块全部 Stub，布线完整
|
||||
> 引用数：37
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持续工作：定时唤醒执行任务，配合 SleepTool 控制节奏。适用于长时间运行的后台任务（等待 CI、监控文件变化、定时检查等）。
|
||||
|
||||
### 与 KAIROS 的关系
|
||||
|
||||
所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即：
|
||||
- 单独开 `FEATURE_PROACTIVE=1` → 获得 proactive 能力
|
||||
- 单独开 `FEATURE_KAIROS=1` → 自动获得 proactive 能力
|
||||
- 两者都开 → 相同效果（不重复）
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 核心逻辑 | `src/proactive/index.ts` | **Stub** | `activateProactive()`、`deactivateProactive()`、`isProactiveActive() => false` |
|
||||
| SleepTool 提示 | `src/tools/SleepTool/prompt.ts` | **完整** | 工具提示定义（工具名：`Sleep`） |
|
||||
| 命令注册 | `src/commands.ts:62-65` | **布线** | 动态加载 `./commands/proactive.js` |
|
||||
| 工具注册 | `src/tools.ts:26-28` | **布线** | SleepTool 动态加载 |
|
||||
| REPL 集成 | `src/screens/REPL.tsx` | **布线** | tick 驱动逻辑、占位符、页脚 UI |
|
||||
| 系统提示 | `src/constants/prompts.ts:860-914` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
|
||||
| 会话存储 | `src/utils/sessionStorage.ts:4892-4912` | **布线** | tick 消息注入对话流 |
|
||||
|
||||
### 2.2 系统提示内容
|
||||
|
||||
`getProactiveSection()` 注入的自主工作指令包含：
|
||||
|
||||
| 章节 | 内容 |
|
||||
|------|------|
|
||||
| Tick 驱动 | `<tick_tag>` prompt 保持存活，包含用户本地时间 |
|
||||
| 节奏控制 | SleepTool 控制等待间隔，prompt cache 5 分钟过期 |
|
||||
| 空操作规则 | 无事可做时**必须**调用 Sleep，禁止输出 "still waiting" |
|
||||
| 首次唤醒 | 简短问候，等待方向（不主动探索） |
|
||||
| 后续唤醒 | 寻找有用工作：调查、验证、检查（不 spam 用户） |
|
||||
| 偏向行动 | 读文件、搜索代码、commit — 不需询问 |
|
||||
| 终端焦点 | `terminalFocus` 字段调节自主程度 |
|
||||
|
||||
### 2.3 数据流
|
||||
|
||||
```
|
||||
activateProactive() [需要实现]
|
||||
│
|
||||
▼
|
||||
Tick 调度器启动
|
||||
│
|
||||
├── 定时生成 <tick_tag> 消息
|
||||
│ ├── 包含用户当前本地时间
|
||||
│ └── 注入到对话流（sessionStorage）
|
||||
│
|
||||
▼
|
||||
模型处理 tick
|
||||
│
|
||||
├── 有事可做 → 使用工具执行 → 可能再次 Sleep
|
||||
└── 无事可做 → 必须调用 SleepTool
|
||||
│
|
||||
▼
|
||||
SleepTool 等待 [需要实现]
|
||||
│
|
||||
▼
|
||||
下一个 tick 到达
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `src/proactive/index.ts` | 中 | Tick 调度器、activate/deactivate 状态机、pause/resume |
|
||||
| 2 | `src/tools/SleepTool/SleepTool.ts` | 小 | 工具执行（等待指定时间后触发 tick） |
|
||||
| 3 | `src/commands/proactive.js` | 小 | `/proactive` 斜杠命令处理器 |
|
||||
| 4 | `src/hooks/useProactive.ts` | 中 | React hook（REPL 引用但不存在） |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Tick 驱动**：模型通过 SleepTool 自行控制唤醒频率，不是外部事件推送
|
||||
2. **空操作必须 Sleep**：防止 "still waiting" 类空消息浪费 turn 和 token
|
||||
3. **Prompt cache 考量**：SleepTool 提示中提到 cache 5 分钟过期，建议平衡等待时间
|
||||
4. **Terminal Focus 感知**：模型根据用户是否在看终端调整自主程度
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 单独启用 proactive
|
||||
FEATURE_PROACTIVE=1 bun run dev
|
||||
|
||||
# 通过 KAIROS 间接启用
|
||||
FEATURE_KAIROS=1 bun run dev
|
||||
|
||||
# 组合使用
|
||||
FEATURE_PROACTIVE=1 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/proactive/index.ts` | 核心逻辑（stub） |
|
||||
| `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
|
||||
| `src/constants/prompts.ts:860-914` | 自主工作系统提示 |
|
||||
| `src/screens/REPL.tsx` | REPL tick 集成 |
|
||||
| `src/utils/sessionStorage.ts:4892-4912` | Tick 消息注入 |
|
||||
| `src/components/PromptInput/PromptInputFooterLeftSide.tsx` | 页脚 UI 状态 |
|
||||
167
docs/features/teammem.md
Normal file
167
docs/features/teammem.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# TEAMMEM — 团队共享记忆
|
||||
|
||||
> Feature Flag: `FEATURE_TEAMMEM=1`
|
||||
> 实现状态：完整可用（需要 Anthropic OAuth + GitHub remote）
|
||||
> 引用数：51
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
TEAMMEM 实现基于 GitHub 仓库的团队共享记忆系统。`memory/team/` 目录中的文件双向同步到 Anthropic 服务器，团队所有认证成员可共享项目知识。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **增量同步**：只上传内容哈希变化的文件（delta upload）
|
||||
- **冲突解决**：基于 ETag 的乐观锁 + 412 冲突重试
|
||||
- **密钥扫描**：上传前检测并跳过包含密钥的文件（PSR M22174）
|
||||
- **路径穿越防护**：所有写入路径验证在 `memory/team/` 边界内
|
||||
- **分批上传**：自动拆分超过 200KB 的 PUT 请求避免网关拒绝
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 同步行为
|
||||
|
||||
| 事件 | 行为 |
|
||||
|------|------|
|
||||
| 项目启动 | 自动 pull 团队记忆到 `memory/team/` |
|
||||
| 本地文件编辑 | watcher 检测变更，自动 push |
|
||||
| 服务端更新 | 下次 pull 时覆盖本地（server-wins） |
|
||||
| 密钥检测 | 跳过该文件，记录警告，不阻止其他文件同步 |
|
||||
|
||||
### API 端点
|
||||
|
||||
```
|
||||
GET /api/claude_code/team_memory?repo={owner/repo} → 完整数据 + entryChecksums
|
||||
GET /api/claude_code/team_memory?repo={owner/repo}&view=hashes → 仅 checksums（冲突解决用）
|
||||
PUT /api/claude_code/team_memory?repo={owner/repo} → 上传 entries（upsert 语义）
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 同步状态
|
||||
|
||||
```ts
|
||||
type SyncState = {
|
||||
lastKnownChecksum: string | null // ETag 条件请求
|
||||
serverChecksums: Map<string, string> // sha256:<hex> 逐文件哈希
|
||||
serverMaxEntries: number | null // 从 413 学习的服务端容量
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Pull 流程（Server → Local）
|
||||
|
||||
文件：`src/services/teamMemorySync/index.ts:770-867`
|
||||
|
||||
```
|
||||
pullTeamMemory(state)
|
||||
│
|
||||
▼
|
||||
检查 OAuth + GitHub remote
|
||||
│
|
||||
▼
|
||||
fetchTeamMemory(state, repo, etag)
|
||||
├── 304 Not Modified → 返回（无变化）
|
||||
├── 404 → 返回（服务端无数据）
|
||||
└── 200 → 解析 TeamMemoryData
|
||||
│
|
||||
▼
|
||||
刷新 serverChecksums（per-key hashes）
|
||||
│
|
||||
▼
|
||||
writeRemoteEntriesToLocal(entries)
|
||||
├── 路径穿越验证（validateTeamMemKey）
|
||||
├── 文件大小检查（> 250KB 跳过）
|
||||
├── 内容比较（相同则跳过写入）
|
||||
└── 并行写入（Promise.all）
|
||||
```
|
||||
|
||||
### 3.3 Push 流程（Local → Server）
|
||||
|
||||
文件：`src/services/teamMemorySync/index.ts:889-1146`
|
||||
|
||||
```
|
||||
pushTeamMemory(state)
|
||||
│
|
||||
▼
|
||||
readLocalTeamMemory(maxEntries)
|
||||
├── 递归扫描 memory/team/ 目录
|
||||
├── 跳过超大文件（> 250KB）
|
||||
├── 密钥扫描（scanForSecrets，gitleaks 规则）
|
||||
└── 按 serverMaxEntries 截断（如果已知）
|
||||
│
|
||||
▼
|
||||
计算 delta = 本地文件 - serverChecksums
|
||||
（只包含哈希不同的文件）
|
||||
│
|
||||
▼
|
||||
batchDeltaByBytes(delta)
|
||||
（拆分为 ≤200KB 的批次）
|
||||
│
|
||||
▼
|
||||
逐批 uploadTeamMemory(state, repo, batch, etag)
|
||||
├── 200 成功 → 更新 serverChecksums
|
||||
├── 412 冲突 → fetchTeamMemoryHashes() 刷新 checksums
|
||||
│ → 重试 delta 计算（最多 2 次）
|
||||
└── 413 超容量 → 学习 serverMaxEntries
|
||||
```
|
||||
|
||||
### 3.4 密钥扫描
|
||||
|
||||
文件：`src/services/teamMemorySync/secretScanner.ts`
|
||||
|
||||
使用 gitleaks 规则模式扫描文件内容。检测到密钥时：
|
||||
- 跳过该文件（不上传）
|
||||
- 记录 `tengu_team_mem_secret_skipped` 事件（仅记录规则 ID，不记录值）
|
||||
- 不阻止其他文件同步
|
||||
|
||||
### 3.5 文件监视
|
||||
|
||||
文件：`src/services/teamMemorySync/watcher.ts`
|
||||
|
||||
监视 `memory/team/` 目录变更，触发自动 push。抑制由 pull 写入引起的假变更。
|
||||
|
||||
### 3.6 路径安全
|
||||
|
||||
文件：`src/memdir/teamMemPaths.ts`
|
||||
|
||||
- `validateTeamMemKey(relPath)` — 验证相对路径不超出 `memory/team/` 边界
|
||||
- `getTeamMemPath()` — 返回 team memory 根目录路径
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Server-wins on pull, Local-wins on push**：pull 时服务端内容覆盖本地；push 时本地编辑覆盖服务端。本地用户正在编辑，不应被静默丢弃
|
||||
2. **Delta upload**：只上传哈希变化的条目，节省带宽。首次 push 为全量，后续增量
|
||||
3. **分批 PUT**：单次 PUT ≤200KB，避免 API 网关（~256-512KB）拒绝。每批独立 upsert，部分失败不影响已提交批次
|
||||
4. **密钥扫描在上传前**：PSR M22174 要求密钥永不离开本机。扫描在 `readLocalTeamMemory` 中执行，密钥文件不进入上传集
|
||||
5. **ETag 乐观锁**：push 使用 `If-Match` header。412 时 probe `?view=hashes`（只获取 checksums，不下载内容），刷新后重试
|
||||
6. **服务端容量动态学习**：不假设客户端容量上限，从 413 的 `extra_details.max_entries` 学习
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_TEAMMEM=1 bun run dev
|
||||
|
||||
# 前提条件：
|
||||
# 1. 已通过 Anthropic OAuth 登录
|
||||
# 2. 项目有 GitHub remote（git remote -v 显示 origin）
|
||||
# 3. memory/team/ 目录自动创建
|
||||
```
|
||||
|
||||
## 六、外部依赖
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic OAuth | first-party 认证 |
|
||||
| GitHub Remote | `getGithubRepo()` 获取 `owner/repo` 作为同步 scope |
|
||||
| Team Memory API | `/api/claude_code/team_memory` 端点 |
|
||||
|
||||
## 七、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/services/teamMemorySync/index.ts` | 1257 | 核心同步逻辑（pull/push/sync） |
|
||||
| `src/services/teamMemorySync/watcher.ts` | — | 文件监视 + 自动同步触发 |
|
||||
| `src/services/teamMemorySync/secretScanner.ts` | — | gitleaks 密钥扫描 |
|
||||
| `src/services/teamMemorySync/types.ts` | — | Zod schema + 类型定义 |
|
||||
| `src/services/teamMemorySync/teamMemSecretGuard.ts` | — | 密钥防护辅助 |
|
||||
| `src/memdir/teamMemPaths.ts` | — | 路径验证 + 目录管理 |
|
||||
76
docs/features/tier3-stubs.md
Normal file
76
docs/features/tier3-stubs.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Tier 3 — 纯 Stub / N/A 低优先级 Feature 概览
|
||||
|
||||
> 本文档汇总所有 Tier 3 feature。这些功能要么是纯 Stub（所有函数返回空值），
|
||||
> 要么是 Anthropic 内部基础设施（N/A），要么是引用量极低的辅助功能。
|
||||
|
||||
## 概览
|
||||
|
||||
| Feature | 引用 | 状态 | 类别 | 简要说明 |
|
||||
|---------|------|------|------|---------|
|
||||
| CHICAGO_MCP | 16 | N/A | 内部基础设施 | Anthropic 内部 MCP 基础设施，非外部可用 |
|
||||
| UDS_INBOX | 17 | Stub | 消息通信 | Unix 域套接字对等消息，进程间消息传递 |
|
||||
| MONITOR_TOOL | 13 | Stub | 工具 | 文件/进程监控工具，检测变更并通知 |
|
||||
| BG_SESSIONS | 11 | Stub | 会话管理 | 后台会话管理，支持多会话并行 |
|
||||
| SHOT_STATS | 10 | 无实现 | 统计 | 逐 prompt 统计信息收集 |
|
||||
| EXTRACT_MEMORIES | 7 | 无实现 | 记忆 | 自动从对话中提取重要信息作为记忆 |
|
||||
| TEMPLATES | 6 | Stub | 项目管理 | 项目/提示模板系统 |
|
||||
| LODESTONE | 6 | N/A | 内部基础设施 | 内部基础设施模块 |
|
||||
| STREAMLINED_OUTPUT | 1 | — | 输出 | 精简输出模式，减少终端输出量 |
|
||||
| HOOK_PROMPTS | 1 | — | 钩子 | Hook 提示词，自定义钩子的提示注入 |
|
||||
| CCR_AUTO_CONNECT | 3 | — | 远程控制 | CCR 自动连接，自动建立远程控制会话 |
|
||||
| CCR_MIRROR | 4 | — | 远程控制 | CCR 镜像模式，会话状态同步 |
|
||||
| CCR_REMOTE_SETUP | 1 | — | 远程控制 | CCR 远程设置，初始化远程控制配置 |
|
||||
| NATIVE_CLIPBOARD_IMAGE | 2 | — | 系统集成 | 原生剪贴板图片，从剪贴板读取图片 |
|
||||
| CONNECTOR_TEXT | 7 | — | 连接器 | 连接器文本，外部系统文本适配 |
|
||||
| COMMIT_ATTRIBUTION | 12 | — | Git | Commit 归因，标记 commit 来源 |
|
||||
| CACHED_MICROCOMPACT | 12 | — | 压缩 | 缓存微压缩，优化 compaction 性能 |
|
||||
| PROMPT_CACHE_BREAK_DETECTION | 9 | — | 性能 | Prompt cache 中断检测，监控 cache miss |
|
||||
| MEMORY_SHAPE_TELEMETRY | 3 | — | 遥测 | 记忆形态遥测，记忆使用模式追踪 |
|
||||
| MCP_RICH_OUTPUT | 3 | — | MCP | MCP 富输出，增强 MCP 工具输出格式 |
|
||||
| FILE_PERSISTENCE | 3 | — | 持久化 | 文件持久化，跨会话保持状态 |
|
||||
| TREE_SITTER_BASH_SHADOW | 5 | Shadow | 安全 | Bash AST Shadow 模式（见 tree-sitter-bash.md） |
|
||||
| QUICK_SEARCH | 5 | — | 搜索 | 快速搜索，优化的文件/内容搜索 |
|
||||
| MESSAGE_ACTIONS | 5 | — | UI | 消息操作，对消息执行后处理动作 |
|
||||
| DOWNLOAD_USER_SETTINGS | 5 | — | 配置 | 下载用户设置，从服务端同步配置 |
|
||||
| DIRECT_CONNECT | 5 | — | 网络 | 直连模式，绕过代理直接连接 API |
|
||||
| VERIFICATION_AGENT | 4 | — | Agent | 验证 Agent，专门用于验证代码变更 |
|
||||
| TERMINAL_PANEL | 4 | — | UI | 终端面板，嵌入式终端输出显示 |
|
||||
| SSH_REMOTE | 4 | — | 远程 | SSH 远程，通过 SSH 连接远程 Claude |
|
||||
| REVIEW_ARTIFACT | 4 | — | 审查 | Review Artifact，代码审查产出物 |
|
||||
| REACTIVE_COMPACT | 4 | — | 压缩 | 响应式压缩，基于上下文变化触发 compaction |
|
||||
| HISTORY_PICKER | 4 | — | UI | 历史选择器，浏览和选择历史对话 |
|
||||
| UPLOAD_USER_SETTINGS | 2 | — | 配置 | 上传用户设置，同步配置到服务端 |
|
||||
| POWERSHELL_AUTO_MODE | 2 | — | 平台 | PowerShell 自动模式，Windows 权限自动化 |
|
||||
| OVERFLOW_TEST_TOOL | 2 | — | 测试 | 溢出测试工具，测试上下文溢出处理 |
|
||||
| NEW_INIT | 2 | — | 初始化 | 新版初始化流程 |
|
||||
| HARD_FAIL | 2 | — | 错误处理 | 硬失败模式，不可恢复错误直接终止 |
|
||||
| ENHANCED_TELEMETRY_BETA | 2 | — | 遥测 | 增强遥测 Beta，详细的性能指标收集 |
|
||||
| COWORKER_TYPE_TELEMETRY | 2 | — | 遥测 | 协作者类型遥测，追踪协作模式 |
|
||||
| BREAK_CACHE_COMMAND | 2 | — | 缓存 | 中断缓存命令，强制刷新 prompt cache |
|
||||
| AWAY_SUMMARY | 2 | — | 摘要 | 离开摘要，用户返回时总结期间工作 |
|
||||
| AUTO_THEME | 2 | — | UI | 自动主题，根据终端设置切换主题 |
|
||||
| ALLOW_TEST_VERSIONS | 2 | — | 版本 | 允许测试版本，跳过版本检查 |
|
||||
| AGENT_TRIGGERS_REMOTE | 2 | — | Agent | Agent 远程触发，从远程触发 Agent 任务 |
|
||||
| AGENT_MEMORY_SNAPSHOT | 2 | — | Agent | Agent 记忆快照，保存/恢复 Agent 状态 |
|
||||
|
||||
## 单引用 Feature（40+ 个）
|
||||
|
||||
以下 feature 各只有 1 处引用，多为内部标记或实验性功能：
|
||||
|
||||
UNATTENDED_RETRY, ULTRATHINK, TORCH, SLOW_OPERATION_LOGGING, SKILL_IMPROVEMENT,
|
||||
SELF_HOSTED_RUNNER, RUN_SKILL_GENERATOR, PERFETTO_TRACING, NATIVE_CLIENT_ATTESTATION,
|
||||
KAIROS_DREAM（见 kairos.md）, IS_LIBC_MUSL, IS_LIBC_GLIBC, DUMP_SYSTEM_PROMPT,
|
||||
COMPACTION_REMINDERS, CCR_REMOTE_SETUP, BYOC_ENVIRONMENT_RUNNER, BUILTIN_EXPLORE_PLAN_AGENTS,
|
||||
BUILDING_CLAUDE_APPS, ANTI_DISTILLATION_CC, AGENT_TRIGGERS, ABLATION_BASELINE
|
||||
|
||||
## 优先级说明
|
||||
|
||||
这些 feature 被列为 Tier 3 的原因：
|
||||
|
||||
1. **内部基础设施**（CHICAGO_MCP, LODESTONE）：Anthropic 内部使用，外部无法运行
|
||||
2. **纯 Stub 且引用低**（UDS_INBOX, MONITOR_TOOL, BG_SESSIONS）：需要大量工作才能实现
|
||||
3. **实验性功能**（SHOT_STATS, EXTRACT_MEMORIES）：尚在概念阶段
|
||||
4. **辅助功能**（STREAMLINED_OUTPUT, HOOK_PROMPTS）：影响范围小
|
||||
5. **CCR 系列**：依赖远程控制基础设施，需要 BRIDGE_MODE 先完善
|
||||
|
||||
如需深入了解某个 Tier 3 feature，可以在代码库中搜索 `feature('FEATURE_NAME')` 查看具体使用场景。
|
||||
198
docs/features/token-budget.md
Normal file
198
docs/features/token-budget.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# TOKEN_BUDGET — Token 预算自动持续模式
|
||||
|
||||
> Feature Flag: `FEATURE_TOKEN_BUDGET=1`
|
||||
> 实现状态：完整可用
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如 `+500k`、`spend 2M tokens`），Claude 会**自动持续工作**直到达到目标，无需用户反复按回车催促继续。
|
||||
|
||||
适用于大型重构、批量修改、大规模代码生成等需要多轮工具调用的长任务。
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 语法
|
||||
|
||||
| 格式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 简写（开头） | `+500k` | 输入开头直接写 |
|
||||
| 简写（结尾） | `帮我重构这个模块 +2m` | 输入末尾追加 |
|
||||
| 完整语法 | `spend 2M tokens` 或 `use 1B tokens` | 自然语言嵌入 |
|
||||
|
||||
单位支持：`k`（千）、`m`（百万）、`b`（十亿），大小写不敏感。
|
||||
|
||||
### UI 反馈
|
||||
|
||||
- **输入框高亮**：输入包含预算语法时，对应文字会被高亮标记（`PromptInput.tsx` 通过 `findTokenBudgetPositions` 计算）
|
||||
- **Spinner 进度**：底部 spinner 显示实时进度，格式如：
|
||||
- 未完成：`Target: 125,000 / 500,000 (25%) · ~2m 30s`
|
||||
- 已完成：`Target: 510,000 used (500,000 min ✓)`
|
||||
- 包含 ETA（基于当前 token 产出速率计算）
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
用户输入 "+500k"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ parseTokenBudget() │ src/utils/tokenBudget.ts
|
||||
│ 正则解析 → 500,000 │
|
||||
└────────┬────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ REPL.tsx │ 提交时调用
|
||||
│ snapshotOutputTokens │ snapshotOutputTokensForTurn(500000)
|
||||
│ ForTurn(500000) │ 记录 turn 起始 token 数 + 预算
|
||||
└────────┬────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ query.ts 主循环 │ 每轮结束后检查
|
||||
│ checkTokenBudget() │ 当前 output tokens vs 预算
|
||||
└────────┬────────────────┘
|
||||
│
|
||||
┌────┴─────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
continue stop
|
||||
(未达 90%) (已达 90% 或收益递减)
|
||||
│ │
|
||||
▼ ▼
|
||||
注入 nudge 正常结束
|
||||
消息继续 发送完成事件
|
||||
```
|
||||
|
||||
### 核心模块
|
||||
|
||||
#### 1. 解析层 — `src/utils/tokenBudget.ts`
|
||||
|
||||
三个正则表达式解析用户输入：
|
||||
|
||||
```
|
||||
SHORTHAND_START_RE = /^\s*\+(\d+(?:\.\d+)?)\s*(k|m|b)\b/i // "+500k" 在开头
|
||||
SHORTHAND_END_RE = /\s\+(\d+(?:\.\d+)?)\s*(k|m|b)\s*[.!?]?\s*$/i // "+2m" 在结尾
|
||||
VERBOSE_RE = /\b(?:use|spend)\s+(\d+(?:\.\d+)?)\s*(k|m|b)\s*tokens?\b/i // "spend 2M tokens"
|
||||
```
|
||||
|
||||
- `parseTokenBudget(text)` — 提取预算数值，返回 `number | null`
|
||||
- `findTokenBudgetPositions(text)` — 返回匹配位置数组，用于输入框高亮
|
||||
- `getBudgetContinuationMessage(pct, turnTokens, budget)` — 生成继续消息
|
||||
|
||||
#### 2. 状态层 — `src/bootstrap/state.ts`
|
||||
|
||||
模块级单例变量追踪当前 turn 的预算状态：
|
||||
|
||||
```
|
||||
outputTokensAtTurnStart — 本 turn 开始时的累计 output token 数
|
||||
currentTurnTokenBudget — 本 turn 的预算目标（null 表示无预算）
|
||||
budgetContinuationCount — 本 turn 已自动续接的次数
|
||||
```
|
||||
|
||||
关键函数：
|
||||
- `getTotalOutputTokens()` — 从 `STATE.modelUsage` 汇总所有模型的 output tokens
|
||||
- `getTurnOutputTokens()` — `getTotalOutputTokens() - outputTokensAtTurnStart`
|
||||
- `snapshotOutputTokensForTurn(budget)` — 重置 turn 起点，设置新预算
|
||||
- `getCurrentTurnTokenBudget()` — 返回当前预算
|
||||
|
||||
#### 3. 决策层 — `src/query/tokenBudget.ts`
|
||||
|
||||
`checkTokenBudget(tracker, agentId, budget, globalTurnTokens)` 做出 continue/stop 决策：
|
||||
|
||||
**继续条件**：
|
||||
- 不在子 agent 中（`agentId` 为空）
|
||||
- 预算存在且 > 0
|
||||
- 当前 token 未达预算的 **90%**
|
||||
- 非收益递减（连续 3 轮 nudge 后，每轮新增 < 500 tokens）
|
||||
|
||||
**停止条件**：
|
||||
- 达到预算 90%
|
||||
- 收益递减（模型已经"做不动了"）
|
||||
- 子 agent 模式下直接跳过
|
||||
|
||||
**收益递减检测**：`continuationCount >= 3` 且最近两次 nudge 的 delta 都 < 500 tokens。
|
||||
|
||||
#### 4. 主循环集成 — `src/query.ts`
|
||||
|
||||
```
|
||||
query() 函数内：
|
||||
1. 创建 budgetTracker = createBudgetTracker()
|
||||
2. 进入 while 循环
|
||||
3. 每轮结束后调用 checkTokenBudget()
|
||||
4. decision.action === 'continue' 时：
|
||||
- 注入 meta user message（nudge）
|
||||
- continue 回到循环顶部
|
||||
5. decision.action === 'stop' 时：
|
||||
- 记录完成事件（含 diminishingReturns 标记）
|
||||
- 正常返回
|
||||
```
|
||||
|
||||
#### 5. UI 层
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `components/PromptInput/PromptInput.tsx:534` | 输入框中高亮预算语法 |
|
||||
| `components/Spinner.tsx:319-338` | spinner 显示进度百分比 + ETA |
|
||||
| `screens/REPL.tsx:2897` | 提交时解析预算并快照 |
|
||||
| `screens/REPL.tsx:2138` | 用户取消时清除预算 |
|
||||
| `screens/REPL.tsx:2963` | turn 结束时捕获预算信息用于显示 |
|
||||
|
||||
#### 6. 系统提示 — `src/constants/prompts.ts:538-551`
|
||||
|
||||
注入 `token_budget` section：
|
||||
|
||||
> "When the user specifies a token target (e.g., '+500k', 'spend 2M tokens', 'use 1B tokens'), your output token count will be shown each turn. Keep working until you approach the target — plan your work to fill it productively. The target is a hard minimum, not a suggestion. If you stop early, the system will automatically continue you."
|
||||
|
||||
注意：这段 prompt **无条件缓存**（不随预算开关变化），因为 "When the user specifies..." 的措辞在没有预算时是空操作。
|
||||
|
||||
#### 7. API 附件 — `src/utils/attachments.ts:3830-3845`
|
||||
|
||||
每轮 API 调用附带 `output_token_usage` attachment：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "output_token_usage",
|
||||
"turn": 125000, // 本 turn 产出
|
||||
"session": 350000, // 会话总产出
|
||||
"budget": 500000 // 预算目标
|
||||
}
|
||||
```
|
||||
|
||||
让模型能看到自己的进度。
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **90% 阈值而非 100%**：在 `COMPLETION_THRESHOLD = 0.9` 处停止，避免最后一轮 nudge 产生远超预算的 token
|
||||
2. **收益递减保护**：连续 3 轮 nudge 后如果每轮产出 < 500 tokens，判定模型已无实质进展，提前终止
|
||||
3. **子 agent 豁免**：AgentTool 内部的子任务不做预算检查，避免子任务重复触发续接
|
||||
4. **无条件缓存系统提示**：预算 prompt 始终注入（不随预算变化 toggle），避免每次切换预算导致 ~20K token 的 cache miss
|
||||
5. **用户取消清预算**：按 Escape 取消时调用 `snapshotOutputTokensForTurn(null)`，防止残留预算触发续接
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_TOKEN_BUDGET=1 bun run dev
|
||||
|
||||
# 在 prompt 中使用
|
||||
> +500k 重构所有测试文件
|
||||
> spend 2M tokens 把这个项目从 JS 迁移到 TS
|
||||
> 帮我写完整的 CRUD 模块 +1m
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/utils/tokenBudget.ts` | 73 | 正则解析 + 位置查找 + 续接消息生成 |
|
||||
| `src/query/tokenBudget.ts` | 93 | 预算追踪器 + continue/stop 决策 |
|
||||
| `src/bootstrap/state.ts:724-743` | 20 | turn 级 token 快照状态 |
|
||||
| `src/constants/prompts.ts:538-551` | 14 | 系统提示注入 |
|
||||
| `src/utils/attachments.ts:3829-3845` | 17 | API attachment 附加 |
|
||||
| `src/query.ts:280,1311-1358` | 48 | 主循环集成 |
|
||||
| `src/screens/REPL.tsx:2897,2963,2138` | 20 | REPL 提交/完成/取消处理 |
|
||||
| `src/components/Spinner.tsx:319-338` | 20 | 进度条 UI |
|
||||
| `src/components/PromptInput/PromptInput.tsx:534` | 1 | 输入高亮 |
|
||||
161
docs/features/tree-sitter-bash.md
Normal file
161
docs/features/tree-sitter-bash.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# TREE_SITTER_BASH — Bash AST 解析
|
||||
|
||||
> Feature Flag: `FEATURE_TREE_SITTER_BASH=1`
|
||||
> 实现状态：完整可用（纯 TypeScript 实现，~7000+ 行）
|
||||
> 引用数：3
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
TREE_SITTER_BASH 启用一个完整的 Bash AST 解析器，用于安全验证 Bash 命令。它用完整的树遍历安全分析器取代了旧的基于正则表达式的 shell-quote 解析器。关键属性是 **fail-closed**：任何无法识别的内容都被归类为 `too-complex` 并需要用户批准。
|
||||
|
||||
### 关联 Feature
|
||||
|
||||
| Feature | 说明 |
|
||||
|---------|------|
|
||||
| `TREE_SITTER_BASH` | 激活用于权限检查的 AST 解析器 |
|
||||
| `TREE_SITTER_BASH_SHADOW` | Shadow/观测模式：运行解析器但丢弃结果，仅记录遥测 |
|
||||
|
||||
## 二、安全架构
|
||||
|
||||
### 2.1 Fail-Closed 设计
|
||||
|
||||
核心设计使用 **allowlist** 遍历模式：
|
||||
|
||||
- `walkArgument()` 只处理已知安全的节点类型（`word`、`number`、`raw_string`、`string`、`concatenation`、`arithmetic_expansion`、`simple_expansion`）
|
||||
- 任何未知节点类型 → `tooComplex()` → 需要用户批准
|
||||
- 解析器加载但失败（超时/节点预算/panic）→ 返回 `PARSE_ABORTED` 符号（区别于"模块未加载"）
|
||||
|
||||
### 2.2 解析结果
|
||||
|
||||
```ts
|
||||
parseForSecurity(cmd) 返回：
|
||||
{ kind: 'simple', commands: SimpleCommand[] } // 可静态分析
|
||||
{ kind: 'too-complex', reason, nodeType } // 需要用户批准
|
||||
{ kind: 'parse-unavailable' } // 解析器未加载
|
||||
```
|
||||
|
||||
### 2.3 安全检查层次
|
||||
|
||||
```
|
||||
parseForSecurity(cmd)
|
||||
│
|
||||
▼
|
||||
parseCommandRaw(cmd) → AST root node
|
||||
│
|
||||
▼
|
||||
预检查：控制字符、Unicode 空白、反斜杠+空白、
|
||||
zsh ~[ ] 语法、zsh =cmd 展开、大括号+引号混淆
|
||||
│
|
||||
▼
|
||||
walkProgram(root) → collectCommands(root, commands, varScope)
|
||||
│
|
||||
├── 'command' → walkCommand()
|
||||
├── 'pipeline'/'list' → 结构性，递归子节点
|
||||
├── 'for_statement' → 跟踪循环变量为 VAR_PLACEHOLDER
|
||||
├── 'if/while' → 作用域隔离的分支
|
||||
├── 'subshell' → 作用域复制
|
||||
├── 'variable_assignment' → walkVariableAssignment()
|
||||
├── 'declaration_command' → 验证 declare/export flags
|
||||
├── 'test_command' → walk test expressions
|
||||
└── 其他 → tooComplex()
|
||||
│
|
||||
▼
|
||||
checkSemantics(commands)
|
||||
├── EVAL_LIKE_BUILTINS（eval, source, exec, trap...）
|
||||
├── ZSH_DANGEROUS_BUILTINS（zmodload, emulate...）
|
||||
├── SUBSCRIPT_EVAL_FLAGS（test -v, printf -v, read -a）
|
||||
├── Shell keywords as argv[0]（误解析检测）
|
||||
├── /proc/*/environ 访问
|
||||
├── jq system() 和危险 flags
|
||||
└── 包装器剥离（time, nohup, timeout, nice, env, stdbuf）
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 核心模块
|
||||
|
||||
| 模块 | 文件 | 行数 | 职责 |
|
||||
|------|------|------|------|
|
||||
| 门控入口 | `src/utils/bash/parser.ts` | ~110 | `parseCommand()`、`parseCommandRaw()`、`ensureInitialized()` |
|
||||
| Bash 解析器 | `src/utils/bash/bashParser.ts` | 4437 | 纯 TS 词法分析 + 递归下降解析器 |
|
||||
| 安全分析器 | `src/utils/bash/ast.ts` | 2680 | 树遍历安全分析 + `parseForSecurity()` |
|
||||
| AST 分析辅助 | `src/utils/bash/treeSitterAnalysis.ts` | 507 | 引号上下文、复合结构、危险模式提取 |
|
||||
| 权限检查入口 | `src/tools/BashTool/bashPermissions.ts` | — | 集成 AST 结果到权限决策 |
|
||||
|
||||
### 3.2 Bash 解析器
|
||||
|
||||
文件：`src/utils/bash/bashParser.ts`（4437 行）
|
||||
|
||||
- 纯 TypeScript 实现（无原生依赖）
|
||||
- 生成与 tree-sitter-bash 兼容的 AST
|
||||
- 关键类型：`TsNode`（type、text、startIndex、endIndex、children）
|
||||
- 安全限制：`PARSE_TIMEOUT_MS = 50`、`MAX_NODES = 50_000` — 防止对抗性输入导致 OOM
|
||||
|
||||
### 3.3 安全分析器
|
||||
|
||||
文件：`src/utils/bash/ast.ts`（2680 行）
|
||||
|
||||
核心函数：
|
||||
|
||||
| 函数 | 职责 |
|
||||
|------|------|
|
||||
| `parseForSecurity(cmd)` | 顶层入口，返回 `simple/too-complex/parse-unavailable` |
|
||||
| `parseForSecurityFromAst(cmd, root)` | 接受预解析 AST |
|
||||
| `checkSemantics(commands)` | 后解析语义检查 |
|
||||
| `walkCommand()` | 提取 argv、envVars、redirects |
|
||||
| `walkArgument()` | Allowlist 参数遍历 |
|
||||
| `collectCommands()` | 递归收集所有命令 |
|
||||
|
||||
### 3.4 AST 分析辅助
|
||||
|
||||
文件：`src/utils/bash/treeSitterAnalysis.ts`（507 行）
|
||||
|
||||
| 函数 | 职责 |
|
||||
|------|------|
|
||||
| `extractQuoteContext()` | 识别单引号、双引号、ANSI-C 字符串、heredoc |
|
||||
| `extractCompoundStructure()` | 检测管道、子 shell、命令组 |
|
||||
| `hasActualOperatorNodes()` | 区分真实 `;`/`&&`/`||` 与转义形式 |
|
||||
| `extractDangerousPatterns()` | 检测命令替换、参数展开、heredocs |
|
||||
| `analyzeCommand()` | 单次遍历提取 |
|
||||
|
||||
### 3.5 Shadow 模式
|
||||
|
||||
`TREE_SITTER_BASH_SHADOW` 运行解析器但**从不影响权限决策**：
|
||||
|
||||
```ts
|
||||
// Shadow 模式：记录遥测，然后强制使用旧版路径
|
||||
astResult = { kind: 'parse-unavailable' }
|
||||
astRoot = null
|
||||
// 记录: available, astTooComplex, astSemanticFail, subsDiffer, ...
|
||||
```
|
||||
|
||||
记录 `tengu_tree_sitter_shadow` 事件，包含与旧版 `splitCommand()` 的对比数据。用于在不影响行为的情况下收集遥测。
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Allowlist 遍历**：只处理已知安全的节点类型，未知类型直接 `tooComplex()`
|
||||
2. **PARSE_ABORTED 符号**：区分"解析器未加载"和"解析器加载但失败"。后者阻止回退旧版（旧版缺少 `EVAL_LIKE_BUILTINS` 检查）
|
||||
3. **变量作用域跟踪**：`VAR=value && cmd $VAR` 模式。静态值解析为真实字符串，`$()` 输出使用 `VAR_PLACEHOLDER`
|
||||
4. **PS4/IFS Allowlist**：PS4 赋值使用严格字符白名单 `[A-Za-z0-9 _+:.\/=\[\]-]`，只允许 `${VAR}` 引用
|
||||
5. **包装器剥离**：从 argv 前面剥离 `time/nohup/timeout/nice/env/stdbuf`，未知标志 → fail-closed
|
||||
6. **Shadow 安全性**：Shadow 模式**总是**强制 `astResult = { kind: 'parse-unavailable' }`，绝不影响权限
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 激活 AST 解析用于权限检查
|
||||
FEATURE_TREE_SITTER_BASH=1 bun run dev
|
||||
|
||||
# Shadow 模式（仅遥测，不影响行为）
|
||||
FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/utils/bash/parser.ts` | ~110 | 门控入口点 |
|
||||
| `src/utils/bash/bashParser.ts` | 4437 | 纯 TS bash 解析器 |
|
||||
| `src/utils/bash/ast.ts` | 2680 | 安全分析器（核心） |
|
||||
| `src/utils/bash/treeSitterAnalysis.ts` | 507 | AST 分析辅助 |
|
||||
| `src/tools/BashTool/bashPermissions.ts:1670-1810` | ~140 | 权限集成 + Shadow 遥测 |
|
||||
107
docs/features/ultraplan.md
Normal file
107
docs/features/ultraplan.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# ULTRAPLAN — 增强规划
|
||||
|
||||
> Feature Flag: `FEATURE_ULTRAPLAN=1`
|
||||
> 实现状态：关键字检测完整，命令处理完整，CCR 远程会话完整
|
||||
> 引用数：10
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强计划模式。相比普通 plan mode，ultraplan 提供更深入的规划能力，支持本地和远程（CCR）执行。
|
||||
|
||||
### 触发方式
|
||||
|
||||
| 方式 | 行为 |
|
||||
|------|------|
|
||||
| 输入含 "ultraplan" 的文本 | 自动重定向到 `/ultraplan` 命令 |
|
||||
| `/ultraplan` 斜杠命令 | 直接执行 |
|
||||
| 彩虹高亮 | 输入框中 "ultraplan" 关键字彩虹动画 |
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 行数 | 状态 |
|
||||
|------|------|------|------|
|
||||
| 命令处理器 | `src/commands/ultraplan.tsx` | 472 | **完整** |
|
||||
| CCR 会话 | `src/utils/ultraplan/ccrSession.ts` | 350 | **完整** |
|
||||
| 关键字检测 | `src/utils/ultraplan/keyword.ts` | 128 | **完整** |
|
||||
| 嵌入式提示 | `src/utils/ultraplan/prompt.txt` | 1 | **完整** |
|
||||
| REPL 对话框 | `src/screens/REPL.tsx` | — | **布线** |
|
||||
| 关键字高亮 | `src/components/PromptInput/PromptInput.tsx` | — | **布线** |
|
||||
|
||||
### 2.2 关键字检测
|
||||
|
||||
文件：`src/utils/ultraplan/keyword.ts`（128 行）
|
||||
|
||||
`findUltraplanTriggerPositions(text)` 智能过滤：
|
||||
- 排除引号内的 "ultraplan"
|
||||
- 排除路径中的 "ultraplan"（如 `/path/to/ultraplan/`）
|
||||
- 排除斜杠命令以外的上下文
|
||||
- `replaceUltraplanKeyword(text)` 清理关键字
|
||||
|
||||
### 2.3 CCR 远程会话
|
||||
|
||||
文件：`src/utils/ultraplan/ccrSession.ts`（350 行）
|
||||
|
||||
`ExitPlanModeScanner` 类实现完整的事件状态机：
|
||||
- `pollForApprovedExitPlanMode()` — 3 秒轮询间隔
|
||||
- 超时处理和重试
|
||||
- 支持远程（teleport）和本地执行
|
||||
|
||||
### 2.4 数据流
|
||||
|
||||
```
|
||||
用户输入 "帮我 ultraplan 重构这个模块"
|
||||
│
|
||||
▼
|
||||
processUserInput 检测 "ultraplan"
|
||||
│
|
||||
▼
|
||||
重定向到 /ultraplan 命令
|
||||
│
|
||||
├── 本地执行 → EnterPlanMode
|
||||
│
|
||||
└── 远程执行 → teleportToRemote → CCR 会话
|
||||
│
|
||||
▼
|
||||
ExitPlanModeScanner 轮询
|
||||
│
|
||||
▼
|
||||
用户在远程审批 → 本地收到结果
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 模块 | 说明 |
|
||||
|------|------|
|
||||
| `src/screens/REPL.tsx` 中的 UltraplanChoiceDialog / UltraplanLaunchDialog | 用户选择本地/远程执行的对话框组件 |
|
||||
| `src/commands/ultraplan/` | 空目录，可能是未合并的子命令结构 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **智能关键字过滤**：排除引号和路径中的 "ultraplan"，避免误触发
|
||||
2. **本地/远程双模式**：支持本地 plan mode 和 CCR 远程会话
|
||||
3. **彩虹高亮反馈**：输入框中 "ultraplan" 关键字使用彩虹动画，暗示这是特殊功能
|
||||
4. **processUserInput 集成**：在用户输入处理管道中拦截，无缝重定向
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_ULTRAPLAN=1 bun run dev
|
||||
|
||||
# 在 REPL 中使用
|
||||
# > ultraplan 重构认证模块
|
||||
# > /ultraplan
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/commands/ultraplan.tsx` | 472 | 斜杠命令处理器 |
|
||||
| `src/utils/ultraplan/ccrSession.ts` | 350 | CCR 远程会话管理 |
|
||||
| `src/utils/ultraplan/keyword.ts` | 128 | 关键字检测和替换 |
|
||||
| `src/utils/ultraplan/prompt.txt` | 1 | 嵌入式提示 |
|
||||
| `src/utils/processUserInput/processUserInput.ts:468` | — | 关键字重定向 |
|
||||
| `src/components/PromptInput/PromptInput.tsx` | — | 彩虹高亮 |
|
||||
125
docs/features/voice-mode.md
Normal file
125
docs/features/voice-mode.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# VOICE_MODE — 语音输入
|
||||
|
||||
> Feature Flag: `FEATURE_VOICE_MODE=1`
|
||||
> 实现状态：完整可用（需要 Anthropic OAuth）
|
||||
> 引用数：46
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频通过 WebSocket 流式传输到 Anthropic STT 端点（Nova 3），实时转录显示在终端中。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **Push-to-Talk**：长按空格键录音，释放后自动发送
|
||||
- **流式转录**：录音过程中实时显示中间转录结果
|
||||
- **无缝集成**：转录文本直接作为用户消息提交到对话
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
| 操作 | 行为 |
|
||||
|------|------|
|
||||
| 长按空格 | 开始录音，显示录音状态 |
|
||||
| 释放空格 | 停止录音，等待最终转录 |
|
||||
| 转录完成 | 自动插入到输入框并提交 |
|
||||
| `/voice` 命令 | 切换语音模式开关 |
|
||||
|
||||
### UI 反馈
|
||||
|
||||
- **录音指示器**：录音时显示红色/脉冲动画
|
||||
- **中间转录**：录音过程中显示 STT 实时识别文本
|
||||
- **最终转录**：完成后替换中间结果
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 门控逻辑
|
||||
|
||||
文件：`src/voice/voiceModeEnabled.ts`
|
||||
|
||||
三层检查：
|
||||
|
||||
```ts
|
||||
isVoiceModeEnabled() = hasVoiceAuth() && isVoiceGrowthBookEnabled()
|
||||
```
|
||||
|
||||
1. **Feature Flag**：`feature('VOICE_MODE')` — 编译时/运行时开关
|
||||
2. **GrowthBook Kill-Switch**：`!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)` — 紧急关闭开关（默认 false = 未禁用）
|
||||
3. **Auth 检查**：`hasVoiceAuth()` — 需要 Anthropic OAuth token（非 API key）
|
||||
|
||||
### 3.2 核心模块
|
||||
|
||||
| 模块 | 职责 |
|
||||
|------|------|
|
||||
| `src/voice/voiceModeEnabled.ts` | Feature flag + GrowthBook + Auth 三层门控 |
|
||||
| `src/hooks/useVoice.ts` | React hook 管理录音状态和 WebSocket 连接 |
|
||||
| `src/services/voiceStreamSTT.ts` | WebSocket 流式传输到 Anthropic STT |
|
||||
|
||||
### 3.3 数据流
|
||||
|
||||
```
|
||||
用户按下空格键
|
||||
│
|
||||
▼
|
||||
useVoice hook 激活
|
||||
│
|
||||
▼
|
||||
macOS 原生音频 / SoX 开始录音
|
||||
│
|
||||
▼
|
||||
WebSocket 连接到 Anthropic STT 端点
|
||||
│
|
||||
├──→ 中间转录结果 → 实时显示
|
||||
│
|
||||
▼
|
||||
用户释放空格键
|
||||
│
|
||||
▼
|
||||
停止录音，等待最终转录
|
||||
│
|
||||
▼
|
||||
转录文本 → 插入输入框 → 自动提交
|
||||
```
|
||||
|
||||
### 3.4 音频录制
|
||||
|
||||
支持两种音频后端：
|
||||
- **macOS 原生音频**：优先使用，低延迟
|
||||
- **SoX（Sound eXchange）**：回退方案，跨平台
|
||||
|
||||
音频流通过 WebSocket 发送到 Anthropic 的 Nova 3 STT 模型。
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **OAuth 独占**：语音模式使用 `voice_stream` 端点（claude.ai），仅 Anthropic OAuth 用户可用。API key、Bedrock、Vertex 用户无法使用
|
||||
2. **GrowthBook 负向门控**：`tengu_amber_quartz_disabled` 默认 `false`，新安装自动可用（无需等 GrowthBook 初始化）
|
||||
3. **Keychain 缓存**：`getClaudeAIOAuthTokens()` 首次调用访问 macOS keychain（~20-50ms），后续缓存命中
|
||||
4. **独立于主 feature flag**：`isVoiceGrowthBookEnabled()` 在 feature flag 关闭时短路返回 `false`，不触发任何模块加载
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_VOICE_MODE=1 bun run dev
|
||||
|
||||
# 在 REPL 中使用
|
||||
# 1. 确保已通过 OAuth 登录（claude.ai 订阅）
|
||||
# 2. 按住空格键说话
|
||||
# 3. 释放空格键等待转录
|
||||
# 4. 或使用 /voice 命令切换开关
|
||||
```
|
||||
|
||||
## 六、外部依赖
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic OAuth | claude.ai 订阅登录，非 API key |
|
||||
| GrowthBook | `tengu_amber_quartz_disabled` 紧急关闭 |
|
||||
| macOS 原生音频 或 SoX | 音频录制 |
|
||||
| Nova 3 STT | 语音转文本模型 |
|
||||
|
||||
## 七、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/voice/voiceModeEnabled.ts` | 55 | 三层门控逻辑 |
|
||||
| `src/hooks/useVoice.ts` | — | React hook（录音状态 + WebSocket） |
|
||||
| `src/services/voiceStreamSTT.ts` | — | STT WebSocket 流式传输 |
|
||||
69
docs/features/web-browser-tool.md
Normal file
69
docs/features/web-browser-tool.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# WEB_BROWSER_TOOL — 浏览器工具
|
||||
|
||||
> Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
|
||||
> 实现状态：核心实现缺失，面板为 Stub，布线完整
|
||||
> 引用数：4
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面元素交互。使用 Bun 的内置 WebView API 提供无头/有头浏览器能力。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 浏览器面板 | `src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
|
||||
| 浏览器工具 | `src/tools/WebBrowserTool/WebBrowserTool.ts` | **缺失** |
|
||||
| REPL 集成 | `src/screens/REPL.tsx` | **布线** — 渲染 WebBrowserPanel |
|
||||
| 工具注册 | `src/tools.ts` | **布线** — 动态加载 |
|
||||
| WebView 检测 | `src/main.tsx` | **布线** — `'WebView' in Bun` 检测 |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
模型调用 WebBrowserTool
|
||||
│
|
||||
▼
|
||||
Bun WebView 创建浏览器实例
|
||||
│
|
||||
├── navigate(url) — 导航到 URL
|
||||
├── click(selector) — 点击元素
|
||||
├── screenshot() — 截取页面截图
|
||||
└── extract(selector) — 提取页面内容
|
||||
│
|
||||
▼
|
||||
结果返回给模型
|
||||
│
|
||||
▼
|
||||
WebBrowserPanel 在 REPL 侧边显示浏览器状态
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 模块 | 工作量 | 说明 |
|
||||
|------|--------|------|
|
||||
| `WebBrowserTool.ts` | 大 | 工具 schema + Bun WebView API 执行 |
|
||||
| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Bun WebView API**：使用 Bun 内置的 WebView 而非外部浏览器驱动（Puppeteer/Playwright）
|
||||
2. **REPL 侧边面板**：浏览器状态在 REPL 布局中独立渲染
|
||||
3. **Bun 特性检测**：`'WebView' in Bun` 检查运行时是否支持
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
FEATURE_WEB_BROWSER_TOOL=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
|
||||
| `src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（缺失） |
|
||||
| `src/screens/REPL.tsx:273,4582` | 面板渲染 |
|
||||
| `src/tools.ts:115-116` | 工具注册 |
|
||||
186
docs/features/web-search-tool.md
Normal file
186
docs/features/web-search-tool.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# WEB_SEARCH_TOOL — 网页搜索工具
|
||||
|
||||
> 实现状态：适配器架构完成，Bing 适配器为当前默认后端
|
||||
> 引用数：核心工具，无 feature flag 门控（始终启用）
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WebSearchTool 让模型可以搜索互联网获取最新信息。原始实现仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在第三方代理端点下不可用。现已重构为适配器架构，新增 Bing 搜索页面解析作为 fallback，确保任何 API 端点都能使用搜索功能。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 适配器模式
|
||||
|
||||
```
|
||||
WebSearchTool.call()
|
||||
│
|
||||
▼
|
||||
createAdapter() ← 适配器工厂
|
||||
│
|
||||
├── ApiSearchAdapter — Anthropic 官方 API 服务端搜索
|
||||
│ └── 使用 web_search_20250305 server tool
|
||||
│ 通过 queryModelWithStreaming 二次调用 API
|
||||
│
|
||||
└── BingSearchAdapter — Bing HTML 抓取 + 正则提取（当前默认）
|
||||
└── 直接抓取 Bing 搜索页 HTML
|
||||
正则提取 b_algo 块中的标题/URL/摘要
|
||||
```
|
||||
|
||||
### 2.2 模块结构
|
||||
|
||||
| 模块 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| 工具入口 | `src/tools/WebSearchTool/WebSearchTool.ts` | `buildTool()` 定义：schema、权限、执行、输出格式化 |
|
||||
| 工具 prompt | `src/tools/WebSearchTool/prompt.ts` | 搜索工具的系统提示词 |
|
||||
| UI 渲染 | `src/tools/WebSearchTool/UI.tsx` | 搜索结果的终端渲染组件 |
|
||||
| 适配器接口 | `src/tools/WebSearchTool/adapters/types.ts` | `WebSearchAdapter` 接口、`SearchResult`/`SearchOptions`/`SearchProgress` 类型 |
|
||||
| 适配器工厂 | `src/tools/WebSearchTool/adapters/index.ts` | `createAdapter()` 工厂函数，选择后端 |
|
||||
| API 适配器 | `src/tools/WebSearchTool/adapters/apiAdapter.ts` | 封装原有 `queryModelWithStreaming` 逻辑，使用 server tool |
|
||||
| Bing 适配器 | `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 抓取 + 正则解析 |
|
||||
| 单元测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 32 个测试用例 |
|
||||
| 集成测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 真实网络请求验证 |
|
||||
|
||||
### 2.3 数据流
|
||||
|
||||
```
|
||||
模型调用 WebSearchTool(query, allowed_domains, blocked_domains)
|
||||
│
|
||||
▼
|
||||
validateInput() — 校验 query 非空、allowed/block 不共存
|
||||
│
|
||||
▼
|
||||
createAdapter() → BingSearchAdapter（当前硬编码）
|
||||
│
|
||||
▼
|
||||
adapter.search(query, { allowedDomains, blockedDomains, signal, onProgress })
|
||||
│
|
||||
├── onProgress({ type: 'query_update', query })
|
||||
│
|
||||
├── axios.get(bing.com/search?q=...&setmkt=en-US)
|
||||
│ └── 13 个 Edge 浏览器请求头
|
||||
│
|
||||
├── extractBingResults(html) — 正则提取 <li class="b_algo"> 块
|
||||
│ ├── resolveBingUrl() — 解码 base64 重定向 URL
|
||||
│ ├── extractSnippet() — 三级降级摘要提取
|
||||
│ └── decodeHtmlEntities() — he.decode
|
||||
│
|
||||
├── 客户端域名过滤 (allowedDomains / blockedDomains)
|
||||
│
|
||||
├── onProgress({ type: 'search_results_received', resultCount })
|
||||
│
|
||||
▼
|
||||
格式化为 markdown 链接列表返回给模型
|
||||
```
|
||||
|
||||
## 三、Bing 适配器技术细节
|
||||
|
||||
### 3.1 反爬绕过
|
||||
|
||||
使用 13 个 Edge 浏览器请求头（含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等），避免 Bing 返回 JS 渲染的空页面：
|
||||
|
||||
```typescript
|
||||
const BROWSER_HEADERS = {
|
||||
'User-Agent': '...Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0',
|
||||
'Sec-Ch-Ua': '"Microsoft Edge";v="131", "Chromium";v="131", ...',
|
||||
'Sec-Fetch-Dest': 'document',
|
||||
'Sec-Fetch-Mode': 'navigate',
|
||||
'Sec-Fetch-Site': 'none',
|
||||
'Sec-Fetch-User': '?1',
|
||||
// ... 共 13 个标头
|
||||
}
|
||||
```
|
||||
|
||||
`setmkt=en-US` 参数强制美式英语市场，避免 IP 地理定位导致区域化结果。
|
||||
|
||||
### 3.2 URL 解码（`resolveBingUrl()`）
|
||||
|
||||
Bing 返回的重定向 URL 格式：`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`
|
||||
|
||||
- `u` 参数前 2 字符为协议前缀：`a1` = https，`a0` = http
|
||||
- 剩余部分为 base64url 编码的真实 URL
|
||||
- Bing 内部链接和相对路径被过滤返回 `undefined`
|
||||
|
||||
### 3.3 摘要提取（`extractSnippet()`）
|
||||
|
||||
三级降级策略：
|
||||
|
||||
1. `<p class="b_lineclamp...">` — Bing 的搜索摘要段落
|
||||
2. `<div class="b_caption">` 内的 `<p>` — 备选摘要位置
|
||||
3. `<div class="b_caption">` 直接文本 — 最终 fallback
|
||||
|
||||
### 3.4 域名过滤
|
||||
|
||||
客户端侧实现，支持子域名匹配：
|
||||
- `allowedDomains`：白名单，结果域名必须匹配列表中的某项（含子域名）
|
||||
- `blockedDomains`：黑名单，匹配的结果被过滤
|
||||
- 两者不可同时使用（`validateInput` 校验）
|
||||
|
||||
## 四、适配器选择逻辑
|
||||
|
||||
当前 `createAdapter()` 硬编码返回 `BingSearchAdapter`，原逻辑已注释保留：
|
||||
|
||||
```typescript
|
||||
export function createAdapter(): WebSearchAdapter {
|
||||
return new BingSearchAdapter()
|
||||
// 注释保留的选择逻辑：
|
||||
// 1. WEB_SEARCH_ADAPTER 环境变量强制指定 api|bing
|
||||
// 2. isFirstPartyAnthropicBaseUrl() → API 适配器
|
||||
// 3. 第三方端点 → Bing 适配器
|
||||
}
|
||||
```
|
||||
|
||||
恢复自动选择：取消 `index.ts` 中的注释即可。
|
||||
|
||||
## 五、接口定义
|
||||
|
||||
### WebSearchAdapter
|
||||
|
||||
```typescript
|
||||
interface WebSearchAdapter {
|
||||
search(query: string, options: SearchOptions): Promise<SearchResult[]>
|
||||
}
|
||||
|
||||
interface SearchResult {
|
||||
title: string
|
||||
url: string
|
||||
snippet?: string
|
||||
}
|
||||
|
||||
interface SearchOptions {
|
||||
allowedDomains?: string[]
|
||||
blockedDomains?: string[]
|
||||
signal?: AbortSignal
|
||||
onProgress?: (progress: SearchProgress) => void
|
||||
}
|
||||
|
||||
interface SearchProgress {
|
||||
type: 'query_update' | 'search_results_received'
|
||||
query?: string
|
||||
resultCount?: number
|
||||
}
|
||||
```
|
||||
|
||||
### 工具 Input Schema
|
||||
|
||||
```typescript
|
||||
{
|
||||
query: string // 搜索关键词，最少 2 字符
|
||||
allowed_domains?: string[] // 域名白名单
|
||||
blocked_domains?: string[] // 域名黑名单
|
||||
}
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/WebSearchTool/WebSearchTool.ts` | 工具定义入口 |
|
||||
| `src/tools/WebSearchTool/prompt.ts` | 搜索工具 prompt |
|
||||
| `src/tools/WebSearchTool/UI.tsx` | 终端 UI 渲染 |
|
||||
| `src/tools/WebSearchTool/adapters/types.ts` | 适配器接口 |
|
||||
| `src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 |
|
||||
| `src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 服务端搜索适配器 |
|
||||
| `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 解析适配器 |
|
||||
| `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 单元测试 (32 cases) |
|
||||
| `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 集成测试 |
|
||||
| `src/tools.ts` | 工具注册 |
|
||||
105
docs/features/workflow-scripts.md
Normal file
105
docs/features/workflow-scripts.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# WORKFLOW_SCRIPTS — 工作流自动化
|
||||
|
||||
> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
|
||||
> 实现状态：全部 Stub（7 个文件），布线完整
|
||||
> 引用数：10
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| WorkflowTool | `src/tools/WorkflowTool/WorkflowTool.ts` | **Stub** — 空对象 |
|
||||
| Workflow 权限 | `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | **Stub** — 返回 null |
|
||||
| 常量 | `src/tools/WorkflowTool/constants.ts` | **Stub** — 空工具名 |
|
||||
| 命令创建 | `src/tools/WorkflowTool/createWorkflowCommand.ts` | **Stub** — 空操作 |
|
||||
| 捆绑工作流 | `src/tools/WorkflowTool/bundled/` | **缺失** — 目录不存在 |
|
||||
| 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
|
||||
| UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
|
||||
| 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
|
||||
| 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
|
||||
| 工具注册 | `src/tools.ts` | **布线** — 包含 bundled 工作流初始化 |
|
||||
| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
用户定义工作流（YAML/JSON 文件）
|
||||
│
|
||||
▼
|
||||
/workflows 命令发现工作流文件
|
||||
│
|
||||
▼
|
||||
createWorkflowCommand() 解析为 Command 对象 [需要实现]
|
||||
│
|
||||
▼
|
||||
WorkflowTool 执行工作流 [需要实现]
|
||||
│
|
||||
├── 步骤 1: Agent({ task: "..." })
|
||||
├── 步骤 2: Agent({ task: "..." })
|
||||
└── 步骤 N: Agent({ task: "..." })
|
||||
│
|
||||
▼
|
||||
LocalWorkflowTask 协调步骤执行 [需要实现]
|
||||
│
|
||||
▼
|
||||
WorkflowDetailDialog 显示进度 [需要实现]
|
||||
```
|
||||
|
||||
### 2.3 预期工作流 DSL
|
||||
|
||||
```
|
||||
# workflow.yaml（预期格式，需要设计）
|
||||
name: "代码审查工作流"
|
||||
steps:
|
||||
- name: "静态分析"
|
||||
agent: { type: "general-purpose", prompt: "运行 lint 和类型检查" }
|
||||
- name: "测试"
|
||||
agent: { type: "general-purpose", prompt: "运行测试套件" }
|
||||
- name: "综合报告"
|
||||
agent: { type: "general-purpose", prompt: "综合分析结果写报告" }
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `WorkflowTool.ts` | 大 | Schema 定义 + 多步执行引擎 |
|
||||
| 2 | `bundled/index.js` | 中 | 内置工作流定义（initBundledWorkflows） |
|
||||
| 3 | `createWorkflowCommand.ts` | 中 | 从文件解析创建命令对象 |
|
||||
| 4 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
|
||||
| 5 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
|
||||
| 6 | `WorkflowPermissionRequest.ts` | 小 | 权限对话框 |
|
||||
| 7 | `constants.ts` | 小 | 工具名常量 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
|
||||
2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
|
||||
3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
|
||||
4. **/workflows 命令**：统一的发现和触发入口
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature（需要补全后才能真正使用）
|
||||
FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（stub） |
|
||||
| `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | 权限对话框（stub） |
|
||||
| `src/tools/WorkflowTool/constants.ts` | 常量（stub） |
|
||||
| `src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（stub） |
|
||||
| `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
|
||||
| `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
|
||||
| `src/tools.ts:127-132` | 工具注册 |
|
||||
| `src/commands.ts:86-89` | 命令注册 |
|
||||
BIN
docs/images/agentic-loop.png
Normal file
BIN
docs/images/agentic-loop.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.7 MiB |
BIN
docs/images/architecture-layers.png
Normal file
BIN
docs/images/architecture-layers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.4 MiB |
BIN
docs/images/compaction.png
Normal file
BIN
docs/images/compaction.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.8 MiB |
BIN
docs/images/data-flow.png
Normal file
BIN
docs/images/data-flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.0 MiB |
BIN
docs/images/interaction-flow.png
Normal file
BIN
docs/images/interaction-flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.7 MiB |
BIN
docs/images/mcp-architecture.png
Normal file
BIN
docs/images/mcp-architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.7 MiB |
BIN
docs/images/permission-layers.png
Normal file
BIN
docs/images/permission-layers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.6 MiB |
BIN
docs/images/streaming-timeline.png
Normal file
BIN
docs/images/streaming-timeline.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.5 MiB |
BIN
docs/images/system-prompt-assembly.png
Normal file
BIN
docs/images/system-prompt-assembly.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.8 MiB |
210
docs/internals/ant-only-world.mdx
Normal file
210
docs/internals/ant-only-world.mdx
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: "Ant 特权世界 - Anthropic 员工专属功能"
|
||||
description: "完整记录 Claude Code 身份门控层：USER_TYPE === 'ant' 时解锁的专属工具、命令、API 和代号体系，揭示内外部构建的差异。"
|
||||
keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic 员工"]
|
||||
---
|
||||
|
||||
{/* 本章目标：完整记录身份门控层——ant 构建独享的一切 */}
|
||||
|
||||
## 什么是 Ant
|
||||
|
||||
`USER_TYPE` 是一个构建时常量，通过 Bun 打包器的 `--define` 注入。在 Anthropic 的内部构建中它被设为 `'ant'`，在公开发布的版本中是 `'external'`：
|
||||
|
||||
```typescript
|
||||
// 反编译版本（src/types/global.d.ts 第 63 行）
|
||||
// Build-time constants BUILD_TARGET/BUILD_ENV/INTERFACE_TYPE — removed (zero runtime usage)
|
||||
```
|
||||
|
||||
`BUILD_TARGET` 等构建时常量在反编译版本中已被移除。`USER_TYPE` 通过 Bun 的 `--define` 或环境变量注入，Bun 会进行**常量折叠**——所有 `process.env.USER_TYPE === 'ant'` 在外部构建中直接变为 `false`，后续代码被 DCE 移除。但在反编译版本中，这些代码保留完整。
|
||||
|
||||
`USER_TYPE === 'ant'` 在代码库中出现 **377+ 次**（含 `=== 'ant'` 291 次、`(process.env.USER_TYPE) === 'ant'` 86 次），另有 `!== 'ant'` 53 次、其他引用约 35 次，总计 **465 处引用**，控制着工具、命令、API、UI 等方方面面。
|
||||
|
||||
## Ant-Only 工具
|
||||
|
||||
以下工具仅在内部构建中被加载到工具注册表：
|
||||
|
||||
| 工具 | 代码位置 | 用途 |
|
||||
|------|---------|------|
|
||||
| **REPLTool** | `src/tools/REPLTool/` | 高级 REPL 模式——在 VM 中包装 Bash/Read/Edit/Glob/Grep/Agent 等工具 |
|
||||
| **SuggestBackgroundPRTool** | `src/tools/SuggestBackgroundPRTool/` | 建议在后台创建 PR |
|
||||
| **ConfigTool** | `src/tools/ConfigTool/` | 交互式配置编辑器，包含 Gates 标签页用于覆盖 GrowthBook flags |
|
||||
| **TungstenTool** | `src/tools/TungstenTool/` | 基于 tmux 的终端面板工具（反编译版中已 stub） |
|
||||
|
||||
```typescript
|
||||
// src/tools.ts 第 14-24 行——条件导入 + Dead Code Elimination 标记
|
||||
// Dead code elimination: conditional import for ant-only tools
|
||||
/* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
|
||||
const REPLTool =
|
||||
process.env.USER_TYPE === 'ant'
|
||||
? require('./tools/REPLTool/REPLTool.js').REPLTool
|
||||
: null
|
||||
const SuggestBackgroundPRTool =
|
||||
process.env.USER_TYPE === 'ant'
|
||||
? require('./tools/SuggestBackgroundPRTool/SuggestBackgroundPRTool.js')
|
||||
.SuggestBackgroundPRTool
|
||||
: null
|
||||
```
|
||||
|
||||
## Ant-Only 命令
|
||||
|
||||
`src/commands.ts` 注册了 **28** 个仅在内部构建中可用的斜杠命令（`INTERNAL_ONLY_COMMANDS`，lines 225-254），在 `USER_TYPE === 'ant' && !IS_DEMO` 时才加载（line 343-345）：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="调试类">
|
||||
- `breakCache` — 清除缓存
|
||||
- `ctx_viz` — 可视化上下文窗口使用情况
|
||||
- `debugToolCall` — 调试工具调用
|
||||
- `env` — 显示环境变量
|
||||
- `mockLimits` — 模拟速率限制
|
||||
- `resetLimits` — 重置速率限制
|
||||
- `resetLimitsNonInteractive` — 重置速率限制（非交互式）
|
||||
</Accordion>
|
||||
<Accordion title="实验类">
|
||||
- `bughunter` — Bug 猎人模式
|
||||
- `goodClaude` — 质量评估工具
|
||||
- `antTrace` — 追踪分析
|
||||
- `perfIssue` — 性能问题诊断
|
||||
</Accordion>
|
||||
<Accordion title="工作流类">
|
||||
- `commit` — 快速提交
|
||||
- `commitPushPr` — 一键提交+推送+创建 PR
|
||||
- `issue` — 创建 GitHub Issue
|
||||
- `autofixPr` — 自动修复 PR 中的问题
|
||||
- `share` — 分享会话
|
||||
- `summary` — 生成摘要
|
||||
- `subscribePr` — 订阅 PR（需要 `KAIROS_GITHUB_WEBHOOKS` feature flag）
|
||||
- `forceSnip` — 强制截断历史（需要 `HISTORY_SNIP` feature flag）
|
||||
- `ultraplan` — 超级规划（需要 `ULTRAPLAN` feature flag）
|
||||
</Accordion>
|
||||
<Accordion title="基础设施类">
|
||||
- `backfillSessions` — 回填会话数据
|
||||
- `bridgeKick` — 重启 Bridge 连接
|
||||
- `oauthRefresh` — 刷新 OAuth Token
|
||||
- `teleport` — 传送到指定上下文
|
||||
- `onboarding` — 新手引导
|
||||
- `agentsPlatform` — Agents 平台管理
|
||||
- `version` — 内部版本详情
|
||||
- `initVerifiers` — 初始化验证器
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
这些命令在 `IS_DEMO` 模式下也会被隐藏，防止在演示环境中暴露内部功能。
|
||||
</Note>
|
||||
|
||||
## Beta API Headers
|
||||
|
||||
Claude Code 向 API 发送的 beta headers 分布在 `src/constants/betas.ts`（主注册表）和其他文件中，按可见性分为以下几类：
|
||||
|
||||
### 公开 Headers（所有构建均发送）
|
||||
|
||||
| Header | 功能 | 额外条件 |
|
||||
|--------|------|----------|
|
||||
| `claude-code-20250219` | Claude Code 标识 | 非 Haiku 时始终发送；Haiku 在 agentic 模式下也发送 |
|
||||
| `effort-2025-11-24` | 推理强度控制 | 动态注入 |
|
||||
| `task-budgets-2026-03-13` | 任务预算 | 始终通过 `addAgenticBetas()` 注入 |
|
||||
| `fast-mode-2026-02-01` | 快速模式 | 通过 sticky-on latch 动态注入 |
|
||||
| `advisor-tool-2026-03-01` | 顾问工具 | 启用 advisor 时动态注入 |
|
||||
| `advanced-tool-use-2025-11-20` | 工具搜索（1P） | Claude API / Foundry |
|
||||
| `tool-search-tool-2025-10-19` | 工具搜索（3P） | Vertex / Bedrock |
|
||||
|
||||
### 模型能力相关（有条件发送）
|
||||
|
||||
| Header | 功能 | 条件 |
|
||||
|--------|------|------|
|
||||
| `interleaved-thinking-2025-05-14` | 交错思考模式 | 模型支持 ISP 且未禁用 |
|
||||
| `context-1m-2025-08-07` | 1M 上下文窗口 | 模型支持 1M context |
|
||||
| `context-management-2025-06-27` | 上下文管理 | Claude 4+ 或 ant 手动启用 |
|
||||
| `structured-outputs-2025-12-15` | 结构化输出 | Claude 4.5/4.6 + GrowthBook `tengu_tool_pear` |
|
||||
| `web-search-2025-03-05` | 网页搜索 | Vertex (Claude 4+) / Foundry |
|
||||
| `redact-thinking-2026-02-12` | 思维摘要/脱敏 | ISP 模型 + 非交互 + 未强制显示思维 |
|
||||
| `prompt-caching-scope-2026-01-05` | 提示缓存作用域 | firstParty/foundry + 全局缓存 |
|
||||
|
||||
### Ant-Only Headers
|
||||
|
||||
| Header | 功能 | 条件 |
|
||||
|--------|------|------|
|
||||
| **`cli-internal-2026-02-09`** | 内部 CLI 功能 | `USER_TYPE === 'ant'` + CLI 入口 |
|
||||
| **`token-efficient-tools-2026-03-28`** | Token 高效工具 | `USER_TYPE === 'ant'` + GrowthBook `tengu_amber_json_tools` |
|
||||
|
||||
### Feature Flag Gated
|
||||
|
||||
| Header | 功能 | 条件 |
|
||||
|--------|------|------|
|
||||
| **`afk-mode-2026-01-31`** | AFK 模式（离开键盘自动审批） | `feature('TRANSCRIPT_CLASSIFIER')` |
|
||||
|
||||
### 其他特殊 Headers
|
||||
|
||||
| Header | 功能 | 来源 |
|
||||
|--------|------|------|
|
||||
| `oauth-2025-04-20` | OAuth 订阅者标识 | `src/constants/oauth.ts`，Pro/Max/Team/Enterprise |
|
||||
| `environments-2025-11-01` | Bridge 环境 API | `src/bridge/bridgeApi.ts`，仅 Bridge 模式 |
|
||||
|
||||
```typescript
|
||||
// src/constants/betas.ts — 常量定义
|
||||
export const TOKEN_EFFICIENT_TOOLS_BETA_HEADER =
|
||||
'token-efficient-tools-2026-03-28'
|
||||
export const CLI_INTERNAL_BETA_HEADER =
|
||||
process.env.USER_TYPE === 'ant' ? 'cli-internal-2026-02-09' : ''
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/utils/betas.ts 第 315-321 行——TOKEN_EFFICIENT_TOOLS 的实际门控逻辑
|
||||
if (
|
||||
process.env.USER_TYPE === 'ant' &&
|
||||
includeFirstPartyOnlyBetas &&
|
||||
tokenEfficientToolsEnabled // GrowthBook 'tengu_amber_json_tools' flag
|
||||
) {
|
||||
betaHeaders.push(TOKEN_EFFICIENT_TOOLS_BETA_HEADER)
|
||||
}
|
||||
```
|
||||
|
||||
`cli-internal` header 意味着 Anthropic 的 API 服务端也维护着一套 ant-only 的服务端行为——这不仅仅是客户端的门控。`token-efficient-tools` 进一步需要 GrowthBook flag 开启，说明 Ant 员工内部也有分层灰度。
|
||||
|
||||
## 内部代号体系
|
||||
|
||||
Anthropic 有浓厚的"动物命名"文化：
|
||||
|
||||
| 代号 | 身份 | 出处 |
|
||||
|------|------|------|
|
||||
| **Tengu**（天狗） | Claude Code 项目代号 | 所有 GrowthBook flags 的 `tengu_` 前缀、分析事件名称 |
|
||||
| **Capybara**（水豚） | 模型代号 | `src/constants/prompts.ts` 中被 Undercover Mode 屏蔽的名称 |
|
||||
| **Fennec**（耳廓狐） | 已退役模型别名 | `src/migrations/migrateFennecToOpus.ts`——曾用名已迁移到 Opus |
|
||||
|
||||
这些代号通过 Undercover Mode 在公开仓库的 commit 中被严格过滤。
|
||||
|
||||
## 环境变量开关
|
||||
|
||||
除了 `USER_TYPE`，还有一系列精细的环境变量控制各项功能：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="功能禁用开关">
|
||||
- `CLAUDE_CODE_SIMPLE` — 简化模式（禁用高级功能）
|
||||
- `CLAUDE_CODE_DISABLE_THINKING` — 禁用 thinking
|
||||
- `DISABLE_INTERLEAVED_THINKING` — 禁用交错思考
|
||||
- `DISABLE_COMPACT` — 禁用消息压缩
|
||||
- `DISABLE_AUTO_COMPACT` — 禁用自动压缩
|
||||
- `CLAUDE_CODE_DISABLE_AUTO_MEMORY` — 禁用自动记忆
|
||||
- `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` — 禁用后台任务
|
||||
- `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` — 禁用实验性 beta headers
|
||||
- `USE_API_CONTEXT_MANAGEMENT` — 上下文管理工具清除（需 ant）
|
||||
</Accordion>
|
||||
<Accordion title="功能启用开关">
|
||||
- `CLAUDE_CODE_VERIFY_PLAN` — 启用 VerifyPlanExecutionTool
|
||||
- `ENABLE_LSP_TOOL` — 启用 LSP 语言服务器工具
|
||||
- `CLAUDE_CODE_UNDERCOVER` — 强制启用 Undercover Mode
|
||||
- `CLAUDE_CODE_TERMINAL_RECORDING` — 启用终端录制（asciicast）
|
||||
- `CLAUDE_CODE_ABLATION_BASELINE` — 启用基线对照模式
|
||||
</Accordion>
|
||||
<Accordion title="环境配置">
|
||||
- `CLAUDE_CODE_REMOTE` — 远程执行模式（自动增加堆内存限制）
|
||||
- `CLAUDE_CODE_COORDINATOR_MODE` — 启用 Coordinator 模式
|
||||
- `CLAUDE_INTERNAL_FC_OVERRIDES` — GrowthBook flag 覆盖（ant-only）
|
||||
- `IS_DEMO` — 演示模式（隐藏内部命令和敏感信息）
|
||||
- `CLAUDE_CODE_ENTRYPOINT` — 入口类型标识（`cli` | 其他）
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
`ABLATION_BASELINE` 特别有趣——它同时关闭 thinking、compaction、auto-memory 和 background tasks，用于测量这些高级功能对 AI 表现的**因果影响**。这是一个严肃的"科学对照实验"工具。
|
||||
</Note>
|
||||
115
docs/internals/feature-flags.mdx
Normal file
115
docs/internals/feature-flags.mdx
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: "88 个 Feature Flags - 构建时特性门控全解"
|
||||
description: "深入剖析 Claude Code 的 88+ 个构建时 feature flags：bun:bundle 编译时门控机制，揭示被编译器删除的隐藏功能模块。"
|
||||
keywords: ["feature flags", "特性标志", "构建时门控", "bun:bundle", "条件编译"]
|
||||
---
|
||||
|
||||
{/* 本章目标：完整梳理构建时 feature flag 系统的机制和所有 flag 的分类 */}
|
||||
|
||||
## feature() 是什么
|
||||
|
||||
Claude Code 使用 Bun 打包器的 `bun:bundle` 模块提供编译时特性门控：
|
||||
|
||||
```typescript
|
||||
// 源码中的用法（src/tools.ts 等）
|
||||
import { feature } from 'bun:bundle'
|
||||
|
||||
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
|
||||
? require('./tools/SleepTool/SleepTool.js').SleepTool
|
||||
: null
|
||||
```
|
||||
|
||||
在 Anthropic 的内部构建中，`feature()` 在打包时被求值——返回 `true` 的代码会被保留，返回 `false` 的代码会被 **Dead Code Elimination (DCE)** 彻底移除。
|
||||
|
||||
在我们的反编译版本中，这个函数被兜底为：
|
||||
|
||||
```typescript
|
||||
// src/entrypoints/cli.tsx 第 3 行
|
||||
const feature = (_name: string) => false;
|
||||
```
|
||||
|
||||
这意味着所有 88+ 个 feature flag 后的代码**在运行时永远不会执行**，但代码本身完整保留，可以阅读和分析。
|
||||
|
||||
## Flags 分类全景
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent / 自动化" icon="robot">
|
||||
**15 个 flags** — 控制 AI 的自主能力边界
|
||||
|
||||
`KAIROS` · `KAIROS_BRIEF` · `KAIROS_CHANNELS` · `KAIROS_DREAM` · `KAIROS_GITHUB_WEBHOOKS` · `KAIROS_PUSH_NOTIFICATION` · `PROACTIVE` · `COORDINATOR_MODE` · `FORK_SUBAGENT` · `AGENT_MEMORY_SNAPSHOT` · `AGENT_TRIGGERS` · `AGENT_TRIGGERS_REMOTE` · `VERIFICATION_AGENT` · `BUILTIN_EXPLORE_PLAN_AGENTS` · `MONITOR_TOOL`
|
||||
</Card>
|
||||
|
||||
<Card title="基础设施" icon="server">
|
||||
**10 个 flags** — 控制运行环境和连接方式
|
||||
|
||||
`DAEMON` · `BG_SESSIONS` · `BRIDGE_MODE` · `CCR_AUTO_CONNECT` · `CCR_MIRROR` · `CCR_REMOTE_SETUP` · `DIRECT_CONNECT` · `SSH_REMOTE` · `SELF_HOSTED_RUNNER` · `BYOC_ENVIRONMENT_RUNNER`
|
||||
</Card>
|
||||
|
||||
<Card title="安全 / 分类" icon="shield-halved">
|
||||
**6 个 flags** — 增强权限判断的智能性
|
||||
|
||||
`TRANSCRIPT_CLASSIFIER` · `BASH_CLASSIFIER` · `TREE_SITTER_BASH` · `TREE_SITTER_BASH_SHADOW` · `NATIVE_CLIENT_ATTESTATION` · `ABLATION_BASELINE`
|
||||
</Card>
|
||||
|
||||
<Card title="工具 / 能力" icon="toolbox">
|
||||
**10 个 flags** — 新增的 AI 能力
|
||||
|
||||
`WEB_BROWSER_TOOL` · `TERMINAL_PANEL` · `CONTEXT_COLLAPSE` · `HISTORY_SNIP` · `OVERFLOW_TEST_TOOL` · `WORKFLOW_SCRIPTS` · `VOICE_MODE` · `MCP_RICH_OUTPUT` · `MCP_SKILLS` · `UDS_INBOX`
|
||||
</Card>
|
||||
|
||||
<Card title="UI / 体验" icon="palette">
|
||||
**8 个 flags** — 界面和交互改进
|
||||
|
||||
`MESSAGE_ACTIONS` · `QUICK_SEARCH` · `HISTORY_PICKER` · `AUTO_THEME` · `STREAMLINED_OUTPUT` · `COMPACTION_REMINDERS` · `TEMPLATES` · `BUDDY`
|
||||
</Card>
|
||||
|
||||
<Card title="平台 / 实验" icon="flask-vial">
|
||||
**10+ 个 flags** — 实验性和平台级功能
|
||||
|
||||
`DUMP_SYSTEM_PROMPT` · `UPLOAD_USER_SETTINGS` · `DOWNLOAD_USER_SETTINGS` · `EXPERIMENTAL_SKILL_SEARCH` · `ULTRAPLAN` · `ULTRATHINK` · `TORCH` · `LODESTONE` · `PERFETTO_TRACING` · `SLOW_OPERATION_LOGGING` · `HARD_FAIL` · `ALLOW_TEST_VERSIONS`
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 代码中的典型模式
|
||||
|
||||
Feature flags 在代码中主要有三种使用模式：
|
||||
|
||||
### 模式一：条件加载工具
|
||||
|
||||
```typescript
|
||||
// src/tools.ts — 最常见的模式
|
||||
const MonitorTool = feature('MONITOR_TOOL')
|
||||
? require('./tools/MonitorTool/MonitorTool.js').MonitorTool
|
||||
: null
|
||||
```
|
||||
|
||||
当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。
|
||||
|
||||
### 模式二：条件注册命令
|
||||
|
||||
```typescript
|
||||
// src/commands.ts — 注册斜杠命令
|
||||
if (feature('VOICE_MODE')) {
|
||||
commands.push({ name: 'voice', description: '...' })
|
||||
}
|
||||
```
|
||||
|
||||
### 模式三：条件启用 API 特性
|
||||
|
||||
```typescript
|
||||
// src/constants/betas.ts — 控制发送给 API 的 beta header
|
||||
export const AFK_MODE_BETA_HEADER = feature('TRANSCRIPT_CLASSIFIER')
|
||||
? 'afk-mode-2026-01-31'
|
||||
: ''
|
||||
```
|
||||
|
||||
<Note>
|
||||
由于 `feature()` 在构建时求值，被 DCE 移除的代码不会增加最终打包体积。但在反编译版本中，这些代码全部保留——这正是我们能够进行完整分析的原因。
|
||||
</Note>
|
||||
|
||||
## 有趣的发现
|
||||
|
||||
- **KAIROS 家族**最庞大——6 个相关 flag 控制从核心功能到推送通知的方方面面
|
||||
- **ABLATION_BASELINE** 是用于"科学对照实验"的——它会关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
|
||||
- **BUDDY** 是一个 AI 吉祥物/精灵系统——在 `src/buddy/` 目录下有完整实现
|
||||
- **ULTRAPLAN** 和 **ULTRATHINK** 暗示着比当前 extended thinking 更高级的推理模式
|
||||
120
docs/internals/growthbook-ab-testing.mdx
Normal file
120
docs/internals/growthbook-ab-testing.mdx
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
title: "GrowthBook A/B 测试体系 - 运行时功能发布"
|
||||
description: "揭秘 Claude Code 如何通过 GrowthBook 实现运行时 A/B 测试：用户定向、tengu 命名文化和渐进式功能发布策略。"
|
||||
keywords: ["GrowthBook", "A/B 测试", "运行时门控", "tengu", "渐进式发布"]
|
||||
---
|
||||
|
||||
{/* 本章目标：深入运行时 A/B 测试层——GrowthBook 的集成架构、用户定向、tengu 命名文化 */}
|
||||
|
||||
## 为什么需要运行时 A/B 测试
|
||||
|
||||
构建时 `feature()` 是"全有或全无"的——要么所有用户都有，要么所有用户都没有。但产品团队需要更精细的控制：
|
||||
|
||||
- 只对 5% 的用户灰度发布新功能
|
||||
- 按订阅类型（Free / Pro / Team）差异化体验
|
||||
- 对特定组织静默开启实验性能力
|
||||
- 随时远程关闭出问题的功能，无需发版
|
||||
|
||||
这就是 **GrowthBook** 的用武之地——一个运行时的、基于用户属性的功能门控和 A/B 测试系统。
|
||||
|
||||
## 集成架构
|
||||
|
||||
GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1156 行），工作流程如下：
|
||||
|
||||
<Steps>
|
||||
<Step title="启动时获取远程配置">
|
||||
CLI 启动时，GrowthBook SDK 通过 `https://api.anthropic.com/` 的 API 端点获取当前的功能配置和实验分组规则。使用 `remoteEval: true` 模式——在服务端计算分组，客户端只拿结果。
|
||||
</Step>
|
||||
<Step title="计算用户属性">
|
||||
SDK 收集当前用户的属性（设备 ID、订阅类型、组织 UUID 等），用于决定该用户属于哪些实验的哪个分组。
|
||||
</Step>
|
||||
<Step title="缓存到本地">
|
||||
计算结果缓存到 `~/.claude.json` 的 `cachedGrowthBookFeatures` 字段。刷新间隔：Anthropic 员工 20 分钟，外部用户 6 小时。
|
||||
</Step>
|
||||
<Step title="代码中查询 flag">
|
||||
业务代码通过 `tengu_*` 前缀的 flag 名查询功能状态，GrowthBook SDK 返回当前用户的分组值。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 用户定向属性
|
||||
|
||||
GrowthBook 根据以下用户属性决定实验分组：
|
||||
|
||||
| 属性 | 类型 | 来源 | 用途 |
|
||||
|------|------|------|------|
|
||||
| `id` | string | 会话 ID | 按会话粒度分组 |
|
||||
| `deviceID` | string | 持久化设备标识 | 跨会话一致性 |
|
||||
| `sessionId` | string | 当前会话 ID | 会话级实验 |
|
||||
| `platform` | enum | `process.platform` | 按操作系统差异化 |
|
||||
| `organizationUUID` | string | API 认证信息 | 按组织灰度 |
|
||||
| `accountUUID` | string | API 认证信息 | 按个人账户灰度 |
|
||||
| `subscriptionType` | string | API 认证信息 | Free / Pro / Team 差异化 |
|
||||
| `rateLimitTier` | string | API 认证信息 | 按速率限制层级 |
|
||||
| `email` | string | API 认证信息 | 精确定向特定用户 |
|
||||
| `appVersion` | string | `MACRO.VERSION` | 按版本号灰度 |
|
||||
| `github` | object | GitHub Actions 元数据 | CI 环境特殊处理 |
|
||||
|
||||
<Note>
|
||||
这套定向系统意味着 Anthropic 可以做非常精细的实验——比如"只对 Mac 上的 Pro 订阅用户的 10% 开启新功能"。
|
||||
</Note>
|
||||
|
||||
## 代号文化：tengu_* 的世界
|
||||
|
||||
所有运行时 flag 都以 `tengu_` 为前缀——"Tengu"（天狗）是 Claude Code 的内部项目代号。flag 名采用**动物/植物/矿物 + 形容词**的命名约定，刻意保持不透明。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="tengu_kairos — Kairos 助手模式">
|
||||
控制 KAIROS 功能的运行时开关。即使构建时 `feature('KAIROS')` 通过，仍需此 flag 命中才能激活。双重门控确保新功能可以分阶段发布。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_amber_stoat — Explore Agent A/B 测试">
|
||||
控制内置的 Explore 子 Agent 的行为变体。"amber stoat"（琥珀色白鼬）是随机生成的代号，与功能内容无关——这是为了防止通过 flag 名猜测功能。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_auto_background_agents — 后台 Agent 自动化">
|
||||
控制是否自动将某些任务分派给后台 Agent 执行，而不是在前台阻塞用户。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_onyx_plover — Auto-Dream 后台记忆">
|
||||
控制"自动做梦"功能——在空闲时后台整理和巩固 Agent 的记忆。"onyx plover"（玛瑙鸻）又是一个不透明代号。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_glacier_2xr — 工具搜索行为">
|
||||
控制 Tool Search 的行为变体，可能是搜索算法或排序策略的 A/B 测试。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_birch_trellis — Bash 权限策略">
|
||||
控制 BashTool 权限判断的策略变体——可能在测试更宽松或更严格的权限规则。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_scratch — 草稿本功能">
|
||||
控制一个实验性的"草稿本"功能，可能是让 AI 在处理复杂任务时使用中间暂存区。
|
||||
</Accordion>
|
||||
<Accordion title="tengu_quartz_lantern — Diff 计算策略">
|
||||
控制文件写入和编辑时的 diff 计算方式。可能在 A/B 测试不同的 diff 算法对用户体验的影响。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Ant-Only 覆盖机制
|
||||
|
||||
Anthropic 员工拥有两种方式绕过 GrowthBook 的远程求值：
|
||||
|
||||
### 环境变量覆盖
|
||||
|
||||
```bash
|
||||
# 仅在 USER_TYPE=ant 的构建中生效
|
||||
CLAUDE_INTERNAL_FC_OVERRIDES='{"tengu_kairos": true}' claude
|
||||
```
|
||||
|
||||
通过 `CLAUDE_INTERNAL_FC_OVERRIDES` 环境变量传入 JSON 对象，直接覆盖任意 flag 的值。
|
||||
|
||||
### Config 界面覆盖
|
||||
|
||||
在内部构建中，`/config` 命令的 Gates 标签页提供了图形化的 flag 管理界面，可以实时切换任意 GrowthBook flag。
|
||||
|
||||
## 实验追踪
|
||||
|
||||
GrowthBook 集成了完整的实验曝光追踪：
|
||||
|
||||
- 每次查询 flag 时记录实验曝光事件
|
||||
- 通过 protobuf 格式的 `GrowthbookExperimentEvent` 上报
|
||||
- 包含 `variation_id`（0=对照组，1+=实验组）和 `in_experiment` 标记
|
||||
- 数据用于分析功能对用户行为的因果影响
|
||||
|
||||
<Note>
|
||||
GrowthBook 正在从 Statsig 迁移而来——代码中仍保留着 `checkStatsigFeatureGate_CACHED_MAY_BE_STALE()` 这样的迁移兼容层。
|
||||
</Note>
|
||||
169
docs/internals/growthbook-adapter.mdx
Normal file
169
docs/internals/growthbook-adapter.mdx
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
title: "GrowthBook 适配器 - 自定义 Feature Flag 服务器接入"
|
||||
description: "通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。无配置时自动回退到代码默认值。"
|
||||
keywords: ["growthbook", "feature flags", "远程配置", "适配器", "环境变量"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
Claude Code 的 GrowthBook 系统支持通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。
|
||||
|
||||
- **有配置时**：连接你的 GrowthBook 实例，拉取并缓存 feature 值
|
||||
- **无配置时**：所有 feature 读取直接返回代码中的默认值，零网络请求
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `CLAUDE_GB_ADAPTER_URL` | 是 | GrowthBook API 地址，如 `https://gb.example.com/` |
|
||||
| `CLAUDE_GB_ADAPTER_KEY` | 是 | GrowthBook SDK Client Key，如 `sdk-xxxxx` |
|
||||
|
||||
两个变量都设置时启用适配器模式，否则完全跳过 GrowthBook。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 基本用法
|
||||
|
||||
```bash
|
||||
CLAUDE_GB_ADAPTER_URL=https://gb.example.com/ \
|
||||
CLAUDE_GB_ADAPTER_KEY=sdk-abc123 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### 不使用 GrowthBook（默认行为）
|
||||
|
||||
```bash
|
||||
bun run dev
|
||||
# 所有 getFeatureValue_CACHED_MAY_BE_STALE("xxx", defaultValue) 直接返回 defaultValue
|
||||
```
|
||||
|
||||
## GrowthBook 服务端配置
|
||||
|
||||
### 步骤
|
||||
|
||||
1. **部署 GrowthBook 服务端**（Docker 自托管或 Cloud 版）
|
||||
2. **创建 Environment**（如 `production`）
|
||||
3. **创建 SDK Connection**，获得 SDK Key（即 `CLAUDE_GB_ADAPTER_KEY`）
|
||||
4. **按需添加 Feature**，key 和类型见下方列表
|
||||
|
||||
### 核心原则
|
||||
|
||||
- **不配置任何 feature 也能正常运行**——代码中每个调用都提供了默认值
|
||||
- 只创建你想远程控制的 feature，其余走代码默认
|
||||
- GrowthBook 上配了某个 feature 后，其值会覆盖代码中的默认值
|
||||
|
||||
## Feature Key 列表
|
||||
|
||||
### 高频使用
|
||||
|
||||
| Feature Key | 类型 | 代码默认值 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `tengu_hive_evidence` | boolean | `false` | 任务证据系统 |
|
||||
| `tengu_quartz_lantern` | boolean | `false` | 文件写入/编辑保护 |
|
||||
| `tengu_auto_background_agents` | boolean | `false` | 自动后台 Agent |
|
||||
| `tengu_agent_list_attach` | boolean | `false` | Agent 列表附件 |
|
||||
| `tengu_amber_stoat` | boolean | `true` | 内置 Agents |
|
||||
| `tengu_slim_subagent_claudemd` | boolean | `true` | 子 Agent CLAUDE.md |
|
||||
| `tengu_attribution_header` | boolean | `true` | API 归因 Header |
|
||||
| `tengu_cobalt_harbor` | boolean | `false` | Bridge 模式 |
|
||||
| `tengu_ccr_bridge` | boolean | `false` | CCR Bridge |
|
||||
| `tengu_cicada_nap_ms` | number | `0` | 后台刷新节流（毫秒） |
|
||||
| `tengu_miraculo_the_bard` | boolean | `false` | 启动欢迎信息 |
|
||||
|
||||
### Agent / 工具控制
|
||||
|
||||
| Feature Key | 类型 | 代码默认值 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `tengu_surreal_dali` | boolean | `false` | 远程触发工具 |
|
||||
| `tengu_glacier_2xr` | boolean | `false` | 工具搜索增强 |
|
||||
| `tengu_plum_vx3` | boolean | `false` | Web Search 使用 Haiku |
|
||||
| `tengu_destructive_command_warning` | boolean | `false` | 危险命令警告 |
|
||||
| `tengu_birch_trellis` | boolean | `true` | Bash 权限控制 |
|
||||
| `tengu_harbor_permissions` | boolean | `false` | Harbor 权限模式 |
|
||||
|
||||
### Bridge / 远程连接
|
||||
|
||||
| Feature Key | 类型 | 代码默认值 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `tengu_bridge_repl_v2` | boolean | `false` | Bridge REPL v2 |
|
||||
| `tengu_copper_bridge` | boolean | `false` | Copper Bridge |
|
||||
| `tengu_ccr_mirror` | boolean | `false` | CCR Mirror |
|
||||
|
||||
### 内存 / 上下文
|
||||
|
||||
| Feature Key | 类型 | 代码默认值 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `tengu_coral_fern` | boolean | `false` | 内存目录功能 |
|
||||
| `tengu_passport_quail` | boolean | `false` | 内存路径配置 |
|
||||
| `tengu_slate_thimble` | boolean | `false` | Slate Thimble |
|
||||
| `tengu_herring_clock` | boolean | `false` | 跳过索引 |
|
||||
| `tengu_session_memory` | boolean | `false` | 会话内存 |
|
||||
| `tengu_pebble_leaf_prune` | boolean | `false` | 内存修剪 |
|
||||
|
||||
### UI / 体验
|
||||
|
||||
| Feature Key | 类型 | 代码默认值 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `tengu_terminal_sidebar` | boolean | `false` | 终端侧边栏 |
|
||||
| `tengu_terminal_panel` | boolean | `false` | 终端面板 |
|
||||
| `tengu_willow_mode` | boolean | `false` | Willow 模式 |
|
||||
| `tengu_collage_kaleidoscope` | boolean | `false` | UI 效果 |
|
||||
| `tengu_chrome_auto_enable` | boolean | `false` | Chrome 自动启用 |
|
||||
| `tengu_immediate_model_command` | boolean | `false` | 即时模型切换 |
|
||||
| `tengu_remote_backend` | boolean | `false` | 远程后端 |
|
||||
|
||||
### 配置对象（动态配置）
|
||||
|
||||
| Feature Key | 类型 | 代码默认值 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `tengu_file_read_limits` | object | `null` | 文件读取限制配置 |
|
||||
| `tengu_cobalt_raccoon` | object | `null` | Cobalt 配置 |
|
||||
| `tengu_cobalt_lantern` | object | `null` | Lantern 配置 |
|
||||
| `tengu_desktop_upsell` | object | `null` | 桌面版引导 |
|
||||
| `tengu_marble_sandcastle` | object | `null` | Marble 配置 |
|
||||
| `tengu_marble_fox` | object | `null` | Marble Fox 配置 |
|
||||
| `tengu_ultraplan_model` | string | `null` | Ultraplan 模型名 |
|
||||
|
||||
### Gate（布尔门控）
|
||||
|
||||
| Gate Key | 代码默认值 | 用途 |
|
||||
|---|---|---|
|
||||
| `tengu_chair_sermon` | `false` | 功能门控 |
|
||||
| `tengu_scratch` | `false` | Scratch 功能 |
|
||||
| `tengu_thinkback` | `false` | Thinkback 功能 |
|
||||
| `tengu_tool_pear` | `false` | Tool Pear 功能 |
|
||||
|
||||
## 读取优先级链
|
||||
|
||||
每个 feature 的值按以下顺序解析，第一个命中即返回：
|
||||
|
||||
```
|
||||
1. CLAUDE_INTERNAL_FC_OVERRIDES 环境变量（JSON 对象覆盖）
|
||||
↓ 未命中
|
||||
2. growthBookOverrides 配置（~/.claude.json，仅 ant 构建）
|
||||
↓ 未命中
|
||||
3. 内存缓存（remoteEvalFeatureValues，本次进程从服务器拉取）
|
||||
↓ 未命中
|
||||
4. 磁盘缓存（~/.claude.json 的 cachedGrowthBookFeatures）
|
||||
↓ 未命中
|
||||
5. 代码中的 defaultValue 参数
|
||||
```
|
||||
|
||||
## 缓存与刷新机制
|
||||
|
||||
| 机制 | 说明 |
|
||||
|---|---|
|
||||
| **磁盘缓存** | `~/.claude.json` 的 `cachedGrowthBookFeatures` 字段，跨进程持久化 |
|
||||
| **周期刷新** | 每 6 小时自动从服务器拉取最新值（`setInterval` + `unref`） |
|
||||
| **初始化超时** | 首次连接超时 5 秒，超时后使用磁盘缓存或默认值 |
|
||||
| **Auth 变更** | 登录/登出时自动销毁并重建客户端 |
|
||||
|
||||
## 实现细节
|
||||
|
||||
修改了 2 个文件共 3 处：
|
||||
|
||||
1. **`src/constants/keys.ts`** — `getGrowthBookClientKey()` 优先读取 `CLAUDE_GB_ADAPTER_KEY`
|
||||
2. **`src/services/analytics/growthbook.ts`** — `isGrowthBookEnabled()` 适配器模式下直接启用
|
||||
3. **`src/services/analytics/growthbook.ts`** — base URL 优先使用 `CLAUDE_GB_ADAPTER_URL`
|
||||
|
||||
所有 130+ 个调用方文件无需修改。
|
||||
133
docs/internals/hidden-features.mdx
Normal file
133
docs/internals/hidden-features.mdx
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: "未公开功能巡礼 - 8 个隐藏功能深度解析"
|
||||
description: "深度解析 Claude Code 中 8 个最令人兴奋的隐藏功能：从永不下线的 AI 助手到 AI 吉祥物，揭示 88+ flags 中最具代表性的未公开特性。"
|
||||
keywords: ["隐藏功能", "未公开功能", "秘密功能", "Claude Code 彩蛋", "AI 助手"]
|
||||
---
|
||||
|
||||
{/* 本章目标：逐一展示 8 个最重要的隐藏功能，分析它们背后的产品方向 */}
|
||||
|
||||
## 全景
|
||||
|
||||
从 88+ 个构建时 flags 和 500+ 个运行时 flags 中，我们挑选了 8 个最具代表性的未公开功能。它们不仅展示了 Claude Code 当前的技术深度，更勾勒出 Anthropic 对"AI 编程助手"的未来愿景。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="KAIROS：永不下线的 AI 助手">
|
||||
**门控**: `feature('KAIROS')` + `tengu_kairos`
|
||||
|
||||
KAIROS 是 Claude Code 最庞大的隐藏功能群——6 个独立 flag 控制着一个完整的"持久化 AI 助手"系统：
|
||||
|
||||
| Flag | 能力 |
|
||||
|------|------|
|
||||
| `KAIROS` | 核心助手模式——AI 不再随对话结束而"消失" |
|
||||
| `KAIROS_BRIEF` | 精简输出模式 |
|
||||
| `KAIROS_CHANNELS` | 基于频道的消息系统 |
|
||||
| `KAIROS_DREAM` | 后台"做梦"——自主整理记忆 |
|
||||
| `KAIROS_GITHUB_WEBHOOKS` | 订阅 GitHub PR 事件，自动响应 |
|
||||
| `KAIROS_PUSH_NOTIFICATION` | 向移动端推送通知 |
|
||||
|
||||
KAIROS 的工具集包括 `SleepTool`（让 AI 主动"休眠"等待事件）、`SendUserFileTool`（向用户发送文件）、`PushNotificationTool`（推送通知）和 `SubscribePRTool`（监听 PR）。
|
||||
|
||||
**推测方向**: 一个 7x24 在线的 AI 团队成员，能自主监控代码库、响应事件、管理任务。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="PROACTIVE：自主行动模式">
|
||||
**门控**: `feature('PROACTIVE')`
|
||||
|
||||
在标准模式中，Claude Code 是被动的——等待你输入，然后响应。PROACTIVE 模式颠覆了这一范式：
|
||||
|
||||
- AI 拥有 `SleepTool`，可以主动"打盹"一段时间
|
||||
- 系统定期发送 `<tick>` 提示，触发 AI 检查是否有需要主动做的事
|
||||
- AI 可以在没有用户输入的情况下自行决策和执行
|
||||
|
||||
**推测方向**: 从"问答式助手"进化为"自主式同事"——AI 在后台持续工作，偶尔需要你确认方向。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="COORDINATOR_MODE：多 Agent 指挥官">
|
||||
**门控**: `feature('COORDINATOR_MODE')`
|
||||
|
||||
当前的 Claude Code 已经支持子 Agent（`AgentTool`），但 Coordinator Mode 将其提升到新的层次：
|
||||
|
||||
- 一个"指挥官" Agent 分析任务并分解为子任务
|
||||
- 多个"工人" Agent 并行执行子任务
|
||||
- 指挥官协调结果、处理冲突、合并输出
|
||||
|
||||
完整实现位于 `src/coordinator/coordinatorMode.ts`。
|
||||
|
||||
**推测方向**: 大型编程任务的全自动并行处理——比如"重构整个认证系统"可以同时由多个 Agent 处理不同模块。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="BRIDGE_MODE：远程遥控">
|
||||
**门控**: `feature('BRIDGE_MODE')`
|
||||
|
||||
Bridge Mode 让 Claude Code 可以通过 WebSocket 被远程控制：
|
||||
|
||||
- `src/bridge/` 目录包含完整的 WebSocket 桥接实现
|
||||
- 支持 IDE 扩展作为远程前端
|
||||
- 包含 ant-only 的故障注入测试（`bridgeDebug.ts`）
|
||||
- 配合 `DIRECT_CONNECT` flag 可通过 `cc://` URL 直连
|
||||
|
||||
**推测方向**: Claude Code 的 UI 前端与后端执行分离——你可以在 VS Code 中操作，但 AI 在远程服务器上执行。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WEB_BROWSER_TOOL：内置浏览器">
|
||||
**门控**: `feature('WEB_BROWSER_TOOL')`
|
||||
|
||||
当前的 Claude Code 只有简化的 `WebFetchTool`（获取网页内容），但代码中存在更强大的浏览器工具：
|
||||
|
||||
- 基于 Bun 的 WebView 实现
|
||||
- 可以渲染和交互网页，而不仅仅是抓取文本
|
||||
- 与 Computer Use 的 `@ant/` 包配合使用
|
||||
|
||||
**推测方向**: AI 能像人一样浏览网页——点击、填表、截图，用于测试 Web 应用或收集信息。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="VOICE_MODE：语音交互">
|
||||
**门控**: `feature('VOICE_MODE')`
|
||||
|
||||
代码中存在语音输入模式的注册点，但核心实现依赖于 `audio-napi` 包（在反编译版本中已 stub）：
|
||||
|
||||
- 通过 `/voice` 命令激活
|
||||
- "按住说话"（hold-to-talk）交互模式
|
||||
- 需要系统级音频 API 支持
|
||||
|
||||
**推测方向**: 不用打字，直接和 AI 对话编程。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="BUDDY：AI 吉祥物">
|
||||
**门控**: `feature('BUDDY')`
|
||||
|
||||
`src/buddy/` 目录包含一个完整的"伙伴精灵"系统：
|
||||
|
||||
- 终端中的小型动画角色
|
||||
- 可能根据 AI 的状态（思考中、执行中、完成）展示不同动画
|
||||
- 纯 UI/趣味性功能
|
||||
|
||||
**推测方向**: 给冷冰冰的终端增加一点温度——让等待 AI 思考的过程不那么无聊。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Undercover Mode：隐身贡献">
|
||||
**门控**: `USER_TYPE === 'ant'`（自动激活）
|
||||
|
||||
这不是一个功能，而是一个**安全机制**——当 Anthropic 员工向公开仓库贡献代码时自动激活：
|
||||
|
||||
- 剥除所有 AI 归属标记（`Co-Authored-By` 行）
|
||||
- 禁止在 commit 消息中提及模型代号（Capybara、Tengu 等）
|
||||
- 禁止暴露内部仓库名、Slack 频道、短链接
|
||||
- 通过 `CLAUDE_CODE_UNDERCOVER=1` 强制开启，无法强制关闭
|
||||
- 仅在仓库匹配内部白名单（~25 个私有仓库）时自动关闭
|
||||
|
||||
**意义**: 证实 Anthropic 员工确实在使用 Claude Code 进行日常开发，并且会向公开项目贡献代码。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 这些功能告诉我们什么
|
||||
|
||||
纵观这 8 个隐藏功能，一个清晰的产品愿景浮现：
|
||||
|
||||
1. **从被动到主动** — PROACTIVE、KAIROS 让 AI 不再只是等待指令
|
||||
2. **从短暂到持久** — KAIROS 的持久化模式让 AI 成为"常驻团队成员"
|
||||
3. **从单一到多感官** — VOICE_MODE、WEB_BROWSER_TOOL 拓展交互维度
|
||||
4. **从单兵到协同** — COORDINATOR_MODE 让多个 AI 并行协作
|
||||
5. **从本地到分布式** — BRIDGE_MODE、SSH_REMOTE 解耦前后端
|
||||
|
||||
Claude Code 正在从一个"终端里的聊天机器人"进化为一个**自主、持久、多模态的 AI 编程同事**。
|
||||
106
docs/internals/sentry-setup.mdx
Normal file
106
docs/internals/sentry-setup.mdx
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: "自定义 Sentry 错误上报配置"
|
||||
description: "通过环境变量连接自托管或 Cloud Sentry，实现 CLI 运行时的错误捕获与上报。不配置则完全静默。"
|
||||
keywords: ["sentry", "错误上报", "监控", "DSN", "自托管"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
Claude Code 支持通过 Sentry 捕获运行时异常并上报到你自己指定的 Sentry 实例。
|
||||
|
||||
- **配置了 `SENTRY_DSN`**：自动初始化 Sentry SDK，捕获未处理异常和关键错误
|
||||
- **未配置**：所有 Sentry 调用均为 no-op，零开销
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `SENTRY_DSN` | 是 | Sentry 项目 DSN，如 `https://xxx@o123456.ingest.sentry.io/789` |
|
||||
|
||||
只需要这一个变量，设置后即启用。
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 自托管 Sentry
|
||||
|
||||
```bash
|
||||
SENTRY_DSN=https://public_key@your-sentry.example.com/123 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### Sentry Cloud (SaaS)
|
||||
|
||||
```bash
|
||||
SENTRY_DSN=https://public_key@o123456.ingest.sentry.io/789 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### 不使用 Sentry（默认行为）
|
||||
|
||||
```bash
|
||||
bun run dev
|
||||
# SENTRY_DSN 未设置，所有 sentry 函数为 no-op
|
||||
```
|
||||
|
||||
## Sentry 服务端配置
|
||||
|
||||
### 步骤
|
||||
|
||||
1. **部署 Sentry 实例**（Docker 自托管 或 使用 [sentry.io](https://sentry.io) Cloud）
|
||||
2. **创建 Project**，选择 **Node.js** 平台
|
||||
3. 获取项目的 **DSN**（Settings → Projects → Client Keys → DSN）
|
||||
4. 将 DSN 设置为 `SENTRY_DSN` 环境变量
|
||||
|
||||
## 功能详情
|
||||
|
||||
### 错误捕获
|
||||
|
||||
- **自动捕获**：`SentryErrorBoundary` 包裹关键 React 组件，捕获渲染错误
|
||||
- **手动上报**：`errorLogSink` 在写入错误日志时同步上报到 Sentry
|
||||
- **优雅关闭**：进程退出时 `closeSentry()` 确保事件发送完毕（2s 超时）
|
||||
|
||||
### 安全过滤
|
||||
|
||||
`beforeSend` 钩子会自动剥离以下敏感 header：
|
||||
|
||||
- `authorization`
|
||||
- `x-api-key`
|
||||
- `cookie`
|
||||
- `set-cookie`
|
||||
|
||||
### 忽略的错误类型
|
||||
|
||||
以下错误模式会被忽略，不会上报：
|
||||
|
||||
| 错误 | 原因 |
|
||||
|---|---|
|
||||
| `ECONNREFUSED` / `ECONNRESET` / `ENOTFOUND` / `ETIMEDOUT` | 网络不可达，不可操作 |
|
||||
| `AbortError` / `The user aborted a request` | 用户主动取消 |
|
||||
| `CancelError` | 交互式取消信号 |
|
||||
|
||||
### 其他配置
|
||||
|
||||
- **采样率**：`sampleRate: 1.0`（捕获全部错误事件）
|
||||
- **面包屑上限**：`maxBreadcrumbs: 20`（控制 payload 体积）
|
||||
- **性能事务**：已关闭（`beforeSendTransaction` 返回 `null`），仅上报错误
|
||||
|
||||
## API
|
||||
|
||||
| 函数 | 说明 |
|
||||
|---|---|
|
||||
| `initSentry()` | 初始化 SDK，在 `src/entrypoints/init.ts` 中自动调用 |
|
||||
| `captureException(error, context?)` | 手动上报异常，可附加额外上下文 |
|
||||
| `setTag(key, value)` | 设置标签，用于 Sentry 面板分组过滤 |
|
||||
| `setUser({ id, email, username })` | 设置用户上下文，用于错误归因 |
|
||||
| `closeSentry(timeoutMs?)` | 刷出队列并关闭客户端，进程退出时调用 |
|
||||
| `isSentryInitialized()` | 检查是否已初始化 |
|
||||
|
||||
## 实现文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `src/utils/sentry.ts` | 核心 SDK 初始化与封装 |
|
||||
| `src/components/SentryErrorBoundary.ts` | React Error Boundary 组件 |
|
||||
| `src/utils/errorLogSink.ts` | 错误日志 sink，集成 `captureException` |
|
||||
| `src/utils/gracefulShutdown.ts` | 优雅退出，调用 `closeSentry()` |
|
||||
| `src/entrypoints/init.ts` | 启动时调用 `initSentry()` |
|
||||
87
docs/internals/three-tier-gating.mdx
Normal file
87
docs/internals/three-tier-gating.mdx
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: "三层门禁系统 - 功能可见性控制架构"
|
||||
description: "详解 Claude Code 三层门禁系统：构建时 feature()、运行时 GrowthBook 和身份层 USER_TYPE，如何控制功能的可见性和灰度发布。"
|
||||
keywords: ["门禁系统", "功能门控", "feature flag", "灰度发布", "可见性控制"]
|
||||
---
|
||||
|
||||
{/* 本章目标：建立对三层门禁系统的全局认知，为后续四篇深入文章奠定坐标系 */}
|
||||
|
||||
## 冰山一角
|
||||
|
||||
你日常使用的 Claude Code，只是完整代码库的冰山一角。
|
||||
|
||||
逆向工程揭示了一个事实：大量功能被精心"藏"在三层独立的门禁系统之后。有些是正在 A/B 测试的实验性功能，有些是仅限 Anthropic 员工使用的内部工具，还有些是尚未对外发布的下一代能力。
|
||||
|
||||
> 我们在 `src/` 中发现了 88+ 个构建时 feature flags、500+ 个运行时 A/B 测试标记，以及一整套身份门控机制。
|
||||
|
||||
## 三层门禁全景
|
||||
|
||||
| 维度 | 第一层：构建时 `feature()` | 第二层：运行时 GrowthBook | 第三层：身份 `USER_TYPE` |
|
||||
|------|---------------------------|--------------------------|-------------------------|
|
||||
| **控制方式** | `bun:bundle` 编译时宏 | GrowthBook SDK 远程求值 | 构建时 `--define` 常量 |
|
||||
| **决策时机** | 打包时（代码直接被删除） | 启动时 + 定期刷新 | 打包时（常量折叠） |
|
||||
| **粒度** | 全有或全无 | 按用户/设备/组织定向 | 按构建版本（ant / external） |
|
||||
| **标记数量** | 88+ | 500+ (`tengu_*` 前缀) | 1（`ant` vs `external`） |
|
||||
| **逆向可见性** | 代码残留，但永远走 `false` 分支 | 完整 SDK 代码可读 | 条件分支清晰可见 |
|
||||
|
||||
## 决策流程
|
||||
|
||||
当一个功能请求进入 Claude Code，它会依次经过三层门禁的检查：
|
||||
|
||||
```
|
||||
功能请求
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ 第一层：feature('X') │ ──── 编译时已决定 ──→ false → 代码被 DCE 移除
|
||||
│ (构建时 Feature Flag) │
|
||||
└─────────┬───────────────┘
|
||||
│ true (仅内部构建)
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ 第二层：tengu_xxx │ ──── 运行时按用户属性 ──→ 不在实验组 → 功能关闭
|
||||
│ (GrowthBook A/B 测试) │
|
||||
└─────────┬───────────────┘
|
||||
│ 在实验组
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ 第三层：USER_TYPE │ ──── ant? external? ──→ external → 功能不可用
|
||||
│ (身份门控) │
|
||||
└─────────┬───────────────┘
|
||||
│ ant
|
||||
▼
|
||||
功能可用 ✓
|
||||
```
|
||||
|
||||
三层门禁**相互独立**，一个功能可能同时受多层控制。例如，KAIROS 助手模式同时需要 `feature('KAIROS')` 构建时开启 **和** `tengu_kairos` 运行时实验命中。
|
||||
|
||||
## 逆向工程揭示了什么
|
||||
|
||||
在这个反编译版本中：
|
||||
|
||||
- **第一层**完全透明——`feature()` 被兜底为 `() => false`，所有 88+ 个 flag 的代码路径都可以阅读，只是永远不会执行
|
||||
- **第二层**完整保留——GrowthBook SDK 的 1156 行代码完整可读，包括用户定向属性、缓存策略、覆盖机制
|
||||
- **第三层**清晰可见——`process.env.USER_TYPE === 'ant'` 出现在 60+ 个位置，每一处都标记着"仅限内部"的功能边界
|
||||
|
||||
<Note>
|
||||
这三层门禁不是安全机制——它们是产品发布策略。目的是让 Anthropic 能够在不同用户群体中渐进式地测试和发布功能，而不是阻止逆向工程。
|
||||
</Note>
|
||||
|
||||
## 接下来
|
||||
|
||||
后续四篇文章将分别深入每一层门禁的细节：
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="88 面旗帜" icon="flag" href="/docs/internals/feature-flags">
|
||||
构建时 Feature Flags 的完整分类与解读
|
||||
</Card>
|
||||
<Card title="千面千人" icon="flask" href="/docs/internals/growthbook-ab-testing">
|
||||
GrowthBook A/B 测试体系的运作机制
|
||||
</Card>
|
||||
<Card title="未公开功能巡礼" icon="eye" href="/docs/internals/hidden-features">
|
||||
KAIROS、PROACTIVE 等 8 大隐藏功能深度解析
|
||||
</Card>
|
||||
<Card title="Ant 的特权世界" icon="shield" href="/docs/internals/ant-only-world">
|
||||
Anthropic 员工专属的工具、命令与 API
|
||||
</Card>
|
||||
</CardGroup>
|
||||
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 编程助手到底怎么工作的"
|
||||
5
docs/logo/dark.svg
Normal file
5
docs/logo/dark.svg
Normal file
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 28" fill="none">
|
||||
<circle cx="14" cy="14" r="11" stroke="#F59E0B" stroke-width="2" fill="none"/>
|
||||
<path d="M11 10l6 4-6 4V10z" fill="#F59E0B"/>
|
||||
<text x="30" y="19.5" font-family="system-ui, -apple-system, sans-serif" font-size="15" font-weight="700" letter-spacing="1" fill="#F1F5F9">CCB</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 362 B |
5
docs/logo/light.svg
Normal file
5
docs/logo/light.svg
Normal file
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 28" fill="none">
|
||||
<circle cx="14" cy="14" r="11" stroke="#D97706" stroke-width="2" fill="none"/>
|
||||
<path d="M11 10l6 4-6 4V10z" fill="#D97706"/>
|
||||
<text x="30" y="19.5" font-family="system-ui, -apple-system, sans-serif" font-size="15" font-weight="700" letter-spacing="1" fill="#0F172A">CCB</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 362 B |
264
docs/lsp-integration.md
Normal file
264
docs/lsp-integration.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# LSP Integration
|
||||
|
||||
Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装 LSP 插件
|
||||
|
||||
在 Claude Code REPL 中使用 `/plugin` 命令搜索并安装 LSP 插件：
|
||||
|
||||
```
|
||||
/plugin
|
||||
```
|
||||
|
||||
搜索 `lsp`，找到对应语言的插件（如 `typescript-lsp`），选择安装。
|
||||
|
||||
安装后运行 `/reload-plugins` 使插件生效。
|
||||
|
||||
LSP 插件安装后，后台的 LSP Server Manager 会自动加载并启动对应的语言服务器，无需手动配置。
|
||||
|
||||
### 2. 启用 LSP Tool
|
||||
|
||||
LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码智能查询：
|
||||
|
||||
```bash
|
||||
ENABLE_LSP_TOOL=1 bun run dev
|
||||
```
|
||||
|
||||
不启用时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。
|
||||
|
||||
## 自动推荐
|
||||
|
||||
除了手动 `/plugin` 搜索安装外，Claude Code 会在编辑文件时自动检测：
|
||||
|
||||
1. 监听 `fileHistory.trackedFiles`，发现有新文件被编辑
|
||||
2. 扫描已安装的 marketplace，找到声明支持该文件扩展名的 LSP 插件
|
||||
3. 检查系统上是否已安装对应的 LSP 二进制（如 `typescript-language-server`）
|
||||
4. 满足条件时弹出推荐对话框，可选择安装
|
||||
|
||||
```
|
||||
┌───── LSP Plugin Recommendation ─────────────┐
|
||||
│ │
|
||||
│ LSP provides code intelligence like │
|
||||
│ go-to-definition and error checking │
|
||||
│ │
|
||||
│ Plugin: typescript-lsp │
|
||||
│ Triggered by: .ts files │
|
||||
│ │
|
||||
│ Would you like to install this LSP plugin? │
|
||||
│ │
|
||||
│ > Yes, install typescript-lsp │
|
||||
│ No, not now │
|
||||
│ Never for typescript-lsp │
|
||||
│ Disable all LSP recommendations │
|
||||
└───────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 30 秒不操作自动关闭（算作 "No"）
|
||||
- 选 "Never" 不再推荐该插件
|
||||
- 选 "Disable" 关闭所有 LSP 推荐
|
||||
- 连续忽略 5 次后自动禁用推荐
|
||||
|
||||
## 架构概览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ LSP Tool │
|
||||
│ src/tools/LSPTool/LSPTool.ts │
|
||||
│ (Claude 可调用的工具，9 种操作) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ LSP Server Manager (Singleton) │
|
||||
│ src/services/lsp/manager.ts │
|
||||
│ - initializeLspServerManager() │
|
||||
│ - reinitializeLspServerManager() │
|
||||
│ - shutdownLspServerManager() │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ LSP Server Manager (实例) │
|
||||
│ src/services/lsp/LSPServerManager.ts │
|
||||
│ - 管理多个 LSPServerInstance │
|
||||
│ - 按文件扩展名路由请求 │
|
||||
│ - 文件同步 (didOpen/didChange/didSave/didClose) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ LSPServer │ │ LSPServer │ │ LSPServer │
|
||||
│ Instance │ │ Instance │ │ Instance │
|
||||
│ (typescript) │ │ (python) │ │ (rust...) │
|
||||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
|
||||
│ LSPClient │ │ LSPClient │ │ LSPClient │
|
||||
│ (JSON-RPC) │ │ (JSON-RPC) │ │ (JSON-RPC) │
|
||||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
子进程 (stdio) 子进程 (stdio) 子进程 (stdio)
|
||||
```
|
||||
|
||||
### 被动诊断反馈
|
||||
|
||||
```
|
||||
LSP Server ──publishDiagnostics──▶ passiveFeedback.ts
|
||||
│
|
||||
▼
|
||||
LSPDiagnosticRegistry
|
||||
(去重、容量限制)
|
||||
│
|
||||
▼
|
||||
Attachment System
|
||||
(异步注入到对话)
|
||||
```
|
||||
|
||||
LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去重和容量限制后作为 attachment 注入到 Claude 的对话上下文中。
|
||||
|
||||
## 核心模块
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/services/lsp/manager.ts` | 全局单例，初始化/重初始化/关闭生命周期管理 |
|
||||
| `src/services/lsp/LSPServerManager.ts` | 多服务器管理，按文件扩展名路由，文件同步 |
|
||||
| `src/services/lsp/LSPServerInstance.ts` | 单个 LSP 服务器实例生命周期（启动/停止/重启/健康检查） |
|
||||
| `src/services/lsp/LSPClient.ts` | JSON-RPC 通信层（基于 `vscode-jsonrpc`），子进程管理 |
|
||||
| `src/services/lsp/config.ts` | 从插件加载 LSP 服务器配置 |
|
||||
| `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断信息注册、去重、容量限制 |
|
||||
| `src/services/lsp/passiveFeedback.ts` | 注册 `publishDiagnostics` 通知处理器 |
|
||||
| `src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
|
||||
| `src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
|
||||
| `src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
|
||||
| `src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
|
||||
| `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 |
|
||||
|
||||
## LSP Tool 支持的操作
|
||||
|
||||
| 操作 | LSP Method | 说明 |
|
||||
|------|-----------|------|
|
||||
| `goToDefinition` | `textDocument/definition` | 跳转到符号定义 |
|
||||
| `findReferences` | `textDocument/references` | 查找所有引用 |
|
||||
| `hover` | `textDocument/hover` | 获取悬停信息（文档、类型） |
|
||||
| `documentSymbol` | `textDocument/documentSymbol` | 获取文档内所有符号 |
|
||||
| `workspaceSymbol` | `workspace/symbol` | 全工作区符号搜索 |
|
||||
| `goToImplementation` | `textDocument/implementation` | 查找接口/抽象方法的实现 |
|
||||
| `prepareCallHierarchy` | `textDocument/prepareCallHierarchy` | 获取位置处的调用层级项 |
|
||||
| `incomingCalls` | `callHierarchy/incomingCalls` | 查找调用此函数的所有函数 |
|
||||
| `outgoingCalls` | `callHierarchy/outgoingCalls` | 查找此函数调用的所有函数 |
|
||||
|
||||
所有操作需要 `filePath`、`line`（1-based）和 `character`（1-based）参数。
|
||||
|
||||
## 插件开发：LSP 服务器配置
|
||||
|
||||
LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP 服务器，支持三种格式：
|
||||
|
||||
**1. 内联配置（在 manifest 中直接定义）**
|
||||
|
||||
```json
|
||||
{
|
||||
"lspServers": {
|
||||
"typescript": {
|
||||
"command": "typescript-language-server",
|
||||
"args": ["--stdio"],
|
||||
"extensionToLanguage": {
|
||||
".ts": "typescript",
|
||||
".tsx": "typescriptreact"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**2. 引用外部 .lsp.json 文件**
|
||||
|
||||
```json
|
||||
{
|
||||
"lspServers": "path/to/.lsp.json"
|
||||
}
|
||||
```
|
||||
|
||||
**3. 数组混合格式**
|
||||
|
||||
```json
|
||||
{
|
||||
"lspServers": [
|
||||
"path/to/.lsp.json",
|
||||
{
|
||||
"another-server": { "command": "...", "extensionToLanguage": { "...": "..." } }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
也可以在插件目录下直接放置 `.lsp.json` 文件，无需在 manifest 中声明。
|
||||
|
||||
### LSP 服务器配置 Schema
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `command` | string | 是 | LSP 服务器可执行命令（不含空格） |
|
||||
| `args` | string[] | 否 | 命令行参数 |
|
||||
| `extensionToLanguage` | Record<string, string> | 是 | 文件扩展名到语言 ID 的映射（至少一个） |
|
||||
| `transport` | `"stdio"` \| `"socket"` | 否 | 通信方式，默认 `stdio` |
|
||||
| `env` | Record<string, string> | 否 | 启动服务器时设置的环境变量 |
|
||||
| `initializationOptions` | unknown | 否 | 传给服务器的初始化选项 |
|
||||
| `settings` | unknown | 否 | 通过 `workspace/didChangeConfiguration` 传递的设置 |
|
||||
| `workspaceFolder` | string | 否 | 工作区目录路径 |
|
||||
| `startupTimeout` | number | 否 | 启动超时时间（毫秒） |
|
||||
| `maxRestarts` | number | 否 | 最大重启次数（默认 3） |
|
||||
|
||||
### 环境变量替换
|
||||
|
||||
配置中的 `command`、`args`、`env`、`workspaceFolder` 支持：
|
||||
|
||||
- `${CLAUDE_PLUGIN_ROOT}` — 插件根目录
|
||||
- `${CLAUDE_PLUGIN_DATA}` — 插件数据目录
|
||||
- `${user_config.KEY}` — 用户在插件启用时配置的值
|
||||
- `${VAR}` — 系统环境变量
|
||||
|
||||
## 生命周期管理
|
||||
|
||||
### 服务器状态机
|
||||
|
||||
```
|
||||
stopped → starting → running
|
||||
running → stopping → stopped
|
||||
any → error (失败时)
|
||||
error → starting (重试时)
|
||||
```
|
||||
|
||||
### 崩溃恢复
|
||||
|
||||
- LSP 服务器崩溃时状态设为 `error`
|
||||
- 下次请求时自动尝试重启（通过 `ensureServerStarted`）
|
||||
- 超过 `maxRestarts`（默认 3）次后放弃
|
||||
|
||||
### 瞬态错误重试
|
||||
|
||||
- `ContentModified` 错误（LSP 错误码 -32801）会自动重试，最多 3 次
|
||||
- 使用指数退避：500ms → 1000ms → 2000ms
|
||||
- 常见于 rust-analyzer 等仍在索引项目的服务器
|
||||
|
||||
### 诊断信息容量限制
|
||||
|
||||
- 每个文件最多 10 条诊断
|
||||
- 总计最多 30 条诊断
|
||||
- 超出部分按严重性排序后截断（Error > Warning > Info > Hint）
|
||||
- 跨 turn 去重：已发送过的相同诊断不会重复发送
|
||||
- 文件编辑后清除该文件的已发送记录，允许新诊断通过
|
||||
|
||||
### 插件刷新
|
||||
|
||||
安装/卸载插件后使用 `/reload-plugins`，会调用 `reinitializeLspServerManager()`：
|
||||
1. 异步关闭旧服务器实例
|
||||
2. 重置状态为 `not-started`
|
||||
3. 调用 `initializeLspServerManager()` 重新加载插件配置
|
||||
|
||||
## 依赖
|
||||
|
||||
- `vscode-jsonrpc` — JSON-RPC 通信（懒加载，仅在实际创建服务器实例时才 require）
|
||||
- `vscode-languageserver-protocol` — LSP 协议类型
|
||||
- `vscode-languageserver-types` — LSP 类型定义
|
||||
- `lru-cache` — 诊断去重缓存
|
||||
421
docs/plans/openai-compatibility.md
Normal file
421
docs/plans/openai-compatibility.md
Normal file
@@ -0,0 +1,421 @@
|
||||
# OpenAI 协议兼容层
|
||||
|
||||
## 概述
|
||||
|
||||
claude-code 支持通过 OpenAI Chat Completions API（`/v1/chat/completions`）兼容任意 OpenAI 协议端点，包括 Ollama、DeepSeek、vLLM、One API、LiteLLM 等。
|
||||
|
||||
核心策略为**流适配器模式**：在 `queryModel()` 中插入提前返回分支，将 Anthropic 格式请求转为 OpenAI 格式，调用 OpenAI SDK，再将 SSE 流转换回 `BetaRawMessageStreamEvent` 格式。下游代码（流处理循环、query.ts、QueryEngine.ts、REPL）**完全不改**。
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 必需 | 说明 |
|
||||
|---|---|---|
|
||||
| `CLAUDE_CODE_USE_OPENAI` | 是 | 设为 `1` 启用 OpenAI 后端 |
|
||||
| `OPENAI_API_KEY` | 是 | API key（Ollama 等可设为任意值） |
|
||||
| `OPENAI_BASE_URL` | 推荐 | 端点 URL（如 `http://localhost:11434/v1`） |
|
||||
| `OPENAI_MODEL` | 可选 | 覆盖所有请求的模型名（跳过映射） |
|
||||
| `OPENAI_MODEL_MAP` | 可选 | JSON 映射，如 `{"claude-sonnet-4-6":"gpt-4o"}` |
|
||||
| `OPENAI_ORG_ID` | 可选 | Organization ID |
|
||||
| `OPENAI_PROJECT_ID` | 可选 | Project ID |
|
||||
|
||||
### 使用示例
|
||||
|
||||
```bash
|
||||
# Ollama
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=ollama \
|
||||
OPENAI_BASE_URL=http://localhost:11434/v1 \
|
||||
OPENAI_MODEL=qwen2.5-coder-32b \
|
||||
bun run dev
|
||||
|
||||
# DeepSeek（自动支持 Thinking）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://api.deepseek.com/v1 \
|
||||
OPENAI_MODEL=deepseek-chat \
|
||||
bun run dev
|
||||
|
||||
# vLLM
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=token-abc123 \
|
||||
OPENAI_BASE_URL=http://localhost:8000/v1 \
|
||||
OPENAI_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct \
|
||||
bun run dev
|
||||
|
||||
# One API / LiteLLM
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-your-key \
|
||||
OPENAI_BASE_URL=https://your-one-api.example.com/v1 \
|
||||
OPENAI_MODEL=gpt-4o \
|
||||
bun run dev
|
||||
|
||||
# 自定义模型映射
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://my-gateway.example.com/v1 \
|
||||
OPENAI_MODEL_MAP='{"claude-sonnet-4-6":"gpt-4o-2024-11-20","claude-haiku-4-5":"gpt-4o-mini"}' \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## 架构
|
||||
|
||||
### 请求流程
|
||||
|
||||
```
|
||||
queryModel() [claude.ts]
|
||||
├── 共享预处理（消息归一化、工具过滤、媒体裁剪）
|
||||
└── if (getAPIProvider() === 'openai')
|
||||
└── queryModelOpenAI() [openai/index.ts]
|
||||
├── resolveOpenAIModel() → 解析模型名
|
||||
├── normalizeMessagesForAPI() → 共享消息预处理
|
||||
├── toolToAPISchema() → 构建工具 schema
|
||||
├── anthropicMessagesToOpenAI() → 消息格式转换
|
||||
├── anthropicToolsToOpenAI() → 工具格式转换
|
||||
├── openai.chat.completions.create({ stream: true })
|
||||
└── adaptOpenAIStreamToAnthropic() → 流格式转换
|
||||
├── delta.reasoning_content → thinking 块
|
||||
├── delta.content → text 块
|
||||
├── delta.tool_calls → tool_use 块
|
||||
├── usage.cached_tokens → cache_read_input_tokens
|
||||
└── yield BetaRawMessageStreamEvent
|
||||
```
|
||||
|
||||
### 模型名解析优先级
|
||||
|
||||
`resolveOpenAIModel()` 的解析顺序：
|
||||
|
||||
1. `OPENAI_MODEL` 环境变量 → 直接使用，覆盖所有
|
||||
2. `OPENAI_MODEL_MAP` JSON 查表 → 自定义映射
|
||||
3. 内置默认映射（见下表）
|
||||
4. 以上都不匹配 → 原名透传
|
||||
|
||||
### 内置模型映射
|
||||
|
||||
| Anthropic 模型 | OpenAI 映射 |
|
||||
|---|---|
|
||||
| `claude-sonnet-4-6` | `gpt-4o` |
|
||||
| `claude-sonnet-4-5-20250929` | `gpt-4o` |
|
||||
| `claude-sonnet-4-20250514` | `gpt-4o` |
|
||||
| `claude-3-7-sonnet-20250219` | `gpt-4o` |
|
||||
| `claude-3-5-sonnet-20241022` | `gpt-4o` |
|
||||
| `claude-opus-4-6` | `o3` |
|
||||
| `claude-opus-4-5-20251101` | `o3` |
|
||||
| `claude-opus-4-1-20250805` | `o3` |
|
||||
| `claude-opus-4-20250514` | `o3` |
|
||||
| `claude-haiku-4-5-20251001` | `gpt-4o-mini` |
|
||||
| `claude-3-5-haiku-20241022` | `gpt-4o-mini` |
|
||||
|
||||
同时会自动剥离 `[1m]` 后缀（Claude 特有的 modifier）。
|
||||
|
||||
## 文件结构
|
||||
|
||||
### 新增文件
|
||||
|
||||
```
|
||||
src/services/api/openai/
|
||||
├── client.ts # OpenAI SDK 客户端工厂（~50 行）
|
||||
├── convertMessages.ts # Anthropic → OpenAI 消息格式转换（~190 行）
|
||||
├── convertTools.ts # Anthropic → OpenAI 工具格式转换（~70 行）
|
||||
├── streamAdapter.ts # SSE 流转换核心，含 thinking + caching（~270 行）
|
||||
├── modelMapping.ts # 模型名解析（~60 行）
|
||||
├── index.ts # 公共入口 queryModelOpenAI()（~110 行）
|
||||
└── __tests__/
|
||||
├── convertMessages.test.ts # 10 个测试
|
||||
├── convertTools.test.ts # 7 个测试
|
||||
├── modelMapping.test.ts # 6 个测试
|
||||
└── streamAdapter.test.ts # 14 个测试（含 thinking + caching）
|
||||
```
|
||||
|
||||
### 修改文件
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `src/utils/model/providers.ts` | 添加 `'openai'` provider 类型 + `CLAUDE_CODE_USE_OPENAI` 检查（最高优先级） |
|
||||
| `src/utils/model/configs.ts` | 每个 ModelConfig 添加 `openai` 键 |
|
||||
| `src/services/api/claude.ts` | 在 `stripExcessMediaItems()` 后插入 OpenAI 提前返回分支（~8 行） |
|
||||
| `package.json` | 添加 `"openai": "^4.73.0"` 依赖 |
|
||||
|
||||
## 消息转换规则
|
||||
|
||||
### Anthropic → OpenAI
|
||||
|
||||
| Anthropic | OpenAI |
|
||||
|---|---|
|
||||
| `system` prompt（`string[]`） | `role: "system"` 消息（`\n\n` 拼接） |
|
||||
| `user` + `text` 块 | `role: "user"` 消息 |
|
||||
| `assistant` + `text` 块 | `role: "assistant"` + `content` |
|
||||
| `assistant` + `tool_use` 块 | `role: "assistant"` + `tool_calls[]` |
|
||||
| `user` + `tool_result` 块 | `role: "tool"` + `tool_call_id` |
|
||||
| `thinking` 块 | 静默丢弃（请求侧） |
|
||||
|
||||
### 工具转换
|
||||
|
||||
| Anthropic | OpenAI |
|
||||
|---|---|
|
||||
| `{ name, description, input_schema }` | `{ type: "function", function: { name, description, parameters } }` |
|
||||
| `cache_control`, `defer_loading` 等字段 | 剥离 |
|
||||
| `tool_choice: { type: "auto" }` | `"auto"` |
|
||||
| `tool_choice: { type: "any" }` | `"required"` |
|
||||
| `tool_choice: { type: "tool", name }` | `{ type: "function", function: { name } }` |
|
||||
|
||||
### 消息转换示例
|
||||
|
||||
```
|
||||
Anthropic: OpenAI:
|
||||
[
|
||||
system: ["You are helpful."], [
|
||||
{ role: "system",
|
||||
{ role: "user", content: "You are helpful." },
|
||||
content: [ { role: "user",
|
||||
{ type: "text", text: "Run ls" } content: "Run ls"
|
||||
] },
|
||||
}, { role: "assistant",
|
||||
{ role: "assistant", content: "I'll check.",
|
||||
content: [ tool_calls: [{
|
||||
{ type: "text", text: "I'll check."}, id: "tu_123",
|
||||
{ type: "tool_use", type: "function",
|
||||
id: "tu_123", name: "bash", function: {
|
||||
input: { command: "ls" } } name: "bash",
|
||||
] arguments: '{"command":"ls"}'
|
||||
}, }] }
|
||||
{ role: "user", { role: "tool",
|
||||
content: [ tool_call_id: "tu_123",
|
||||
{ type: "tool_result", content: "file1\nfile2"
|
||||
tool_use_id: "tu_123", }
|
||||
content: "file1\nfile2" ]
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 流转换规则
|
||||
|
||||
### SSE Chunk → Anthropic Event 映射
|
||||
|
||||
| OpenAI Chunk | Anthropic Event |
|
||||
|---|---|
|
||||
| 首个 chunk | `message_start`（含 usage） |
|
||||
| `delta.reasoning_content` | `content_block_start(thinking)` + `thinking_delta` |
|
||||
| `delta.content` | `content_block_start(text)` + `text_delta` |
|
||||
| `delta.tool_calls` | `content_block_start(tool_use)` + `input_json_delta` |
|
||||
| `finish_reason: "stop"` | `message_delta(stop_reason: "end_turn")` |
|
||||
| `finish_reason: "tool_calls"` | `message_delta(stop_reason: "tool_use")` |
|
||||
| `finish_reason: "length"` | `message_delta(stop_reason: "max_tokens")` |
|
||||
|
||||
### 块顺序
|
||||
|
||||
当模型返回 `reasoning_content` 时（如 DeepSeek），块顺序与 Anthropic 一致：
|
||||
|
||||
```
|
||||
thinking block (index 0) ← delta.reasoning_content
|
||||
text block (index 1) ← delta.content
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```
|
||||
thinking block (index 0) ← delta.reasoning_content
|
||||
tool_use block (index 1) ← delta.tool_calls
|
||||
```
|
||||
|
||||
无 `reasoning_content` 时：
|
||||
|
||||
```
|
||||
text block (index 0) ← delta.content
|
||||
tool_use block (index 1) ← delta.tool_calls（如果有）
|
||||
```
|
||||
|
||||
### finish_reason 映射
|
||||
|
||||
| OpenAI | Anthropic |
|
||||
|---|---|
|
||||
| `stop` | `end_turn` |
|
||||
| `tool_calls` | `tool_use` |
|
||||
| `length` | `max_tokens` |
|
||||
| `content_filter` | `end_turn` |
|
||||
|
||||
### 事件序列示例
|
||||
|
||||
**纯文本响应**：
|
||||
```
|
||||
OpenAI chunks:
|
||||
delta.content = "Hello"
|
||||
delta.content = " world"
|
||||
finish_reason = "stop"
|
||||
|
||||
→ Anthropic events:
|
||||
message_start { message: { id, role: 'assistant', usage: {...} } }
|
||||
content_block_start { index: 0, content_block: { type: 'text' } }
|
||||
content_block_delta { index: 0, delta: { type: 'text_delta', text: 'Hello' } }
|
||||
content_block_delta { index: 0, delta: { type: 'text_delta', text: ' world' } }
|
||||
content_block_stop { index: 0 }
|
||||
message_delta { delta: { stop_reason: 'end_turn' } }
|
||||
message_stop
|
||||
```
|
||||
|
||||
**Thinking + 文本（DeepSeek 风格）**：
|
||||
```
|
||||
OpenAI chunks:
|
||||
delta.reasoning_content = "Let me think..."
|
||||
delta.reasoning_content = " step by step."
|
||||
delta.content = "The answer is 42."
|
||||
finish_reason = "stop"
|
||||
|
||||
→ Anthropic events:
|
||||
message_start { ... }
|
||||
content_block_start { index: 0, content_block: { type: 'thinking', signature: '' } }
|
||||
content_block_delta { index: 0, delta: { type: 'thinking_delta', thinking: 'Let me think...' } }
|
||||
content_block_delta { index: 0, delta: { type: 'thinking_delta', thinking: ' step by step.' } }
|
||||
content_block_stop { index: 0 }
|
||||
content_block_start { index: 1, content_block: { type: 'text' } }
|
||||
content_block_delta { index: 1, delta: { type: 'text_delta', text: 'The answer is 42.' } }
|
||||
content_block_stop { index: 1 }
|
||||
message_delta { delta: { stop_reason: 'end_turn' } }
|
||||
message_stop
|
||||
```
|
||||
|
||||
**工具调用**：
|
||||
```
|
||||
OpenAI chunks:
|
||||
delta.tool_calls[0] = { id: 'call_xxx', function: { name: 'bash', arguments: '' } }
|
||||
delta.tool_calls[0].function.arguments = '{"comm'
|
||||
delta.tool_calls[0].function.arguments = 'and":"ls"}'
|
||||
finish_reason = "tool_calls"
|
||||
|
||||
→ Anthropic events:
|
||||
message_start { ... }
|
||||
content_block_start { index: 0, content_block: { type: 'tool_use', id: 'call_xxx', name: 'bash' } }
|
||||
content_block_delta { index: 0, delta: { type: 'input_json_delta', partial_json: '{"comm' } }
|
||||
content_block_delta { index: 0, delta: { type: 'input_json_delta', partial_json: 'and":"ls"}' } }
|
||||
content_block_stop { index: 0 }
|
||||
message_delta { delta: { stop_reason: 'tool_use' } }
|
||||
message_stop
|
||||
```
|
||||
|
||||
## 功能支持
|
||||
|
||||
### Thinking（思维链）
|
||||
|
||||
**请求侧**：不需要显式配置。支持思维链的模型（DeepSeek 等）会自动返回 `delta.reasoning_content`。
|
||||
|
||||
**响应侧**：`delta.reasoning_content` 被转换为 Anthropic `thinking` content block：
|
||||
|
||||
```ts
|
||||
// content_block_start
|
||||
{ type: 'content_block_start', index: 0,
|
||||
content_block: { type: 'thinking', thinking: '', signature: '' } }
|
||||
|
||||
// content_block_delta
|
||||
{ type: 'content_block_delta', index: 0,
|
||||
delta: { type: 'thinking_delta', thinking: 'Let me analyze...' } }
|
||||
```
|
||||
|
||||
thinking block 在 text/tool_use block 之前自动关闭，保持 Anthropic 的块顺序。
|
||||
|
||||
### Prompt Caching
|
||||
|
||||
**请求侧**：OpenAI 端点使用自动缓存，无需显式设置 `cache_control`。
|
||||
|
||||
**响应侧**：OpenAI 的 `usage.prompt_tokens_details.cached_tokens` 被映射到 Anthropic 的 `cache_read_input_tokens`：
|
||||
|
||||
```
|
||||
OpenAI: usage.prompt_tokens_details.cached_tokens = 800
|
||||
↓
|
||||
Anthropic: message_start.message.usage.cache_read_input_tokens = 800
|
||||
```
|
||||
|
||||
在 `message_start` 的 usage 中报告缓存命中量。
|
||||
|
||||
### 工具调用（Tool Use）
|
||||
|
||||
完整支持 OpenAI function calling 格式。所有本地工具（Bash、FileEdit、Grep、Glob、Agent 等）透明工作——它们通过 JSON 输入输出通信，格式无关。
|
||||
|
||||
工具参数以 `input_json_delta` 形式流式传输，由下游代码拼接解析。
|
||||
|
||||
### 不支持的功能
|
||||
|
||||
| 功能 | 策略 |
|
||||
|---|---|
|
||||
| Beta Headers | 不发送 |
|
||||
| Server Tools (advisor) | 不发送 |
|
||||
| Structured Output | 不发送 |
|
||||
| Fast Mode / Effort | 不发送 |
|
||||
| Tool Search / defer_loading | 不启用，所有工具直接发送 |
|
||||
| Anthropic Signature | thinking block 的 `signature` 字段为空字符串 |
|
||||
| cache_creation_input_tokens | 始终为 0（OpenAI 不区分创建/读取） |
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
# 运行所有 OpenAI 适配层测试
|
||||
bun test src/services/api/openai/__tests__/
|
||||
|
||||
# 单独运行
|
||||
bun test src/services/api/openai/__tests__/streamAdapter.test.ts # 14 tests（含 thinking + caching）
|
||||
bun test src/services/api/openai/__tests__/convertMessages.test.ts # 10 tests
|
||||
bun test src/services/api/openai/__tests__/convertTools.test.ts # 7 tests
|
||||
bun test src/services/api/openai/__tests__/modelMapping.test.ts # 6 tests
|
||||
```
|
||||
|
||||
当前测试覆盖：**39 tests / 73 assertions / 0 fail**。
|
||||
|
||||
### 测试覆盖矩阵
|
||||
|
||||
| 功能 | convertMessages | convertTools | streamAdapter | modelMapping |
|
||||
|---|---|---|---|---|
|
||||
| 文本消息转换 | ✅ | | | |
|
||||
| tool_use 转换 | ✅ | | | |
|
||||
| tool_result 转换 | ✅ | | | |
|
||||
| thinking 剥离 | ✅ | | | |
|
||||
| 完整对话流程 | ✅ | | | |
|
||||
| 工具 schema 转换 | | ✅ | | |
|
||||
| tool_choice 映射 | | ✅ | | |
|
||||
| 纯文本流 | | | ✅ | |
|
||||
| 工具调用流 | | | ✅ | |
|
||||
| 混合文本+工具 | | | ✅ | |
|
||||
| finish_reason 映射 | | | ✅ | |
|
||||
| thinking 流 | | | ✅ | |
|
||||
| thinking+text 切换 | | | ✅ | |
|
||||
| thinking+tool_use 切换 | | | ✅ | |
|
||||
| 块索引正确性 | | | ✅ | |
|
||||
| cached_tokens 映射 | | | ✅ | |
|
||||
| OPENAI_MODEL 覆盖 | | | | ✅ |
|
||||
| 默认模型映射 | | | | ✅ |
|
||||
| 未知模型透传 | | | | ✅ |
|
||||
| [1m] 后缀剥离 | | | | ✅ |
|
||||
|
||||
## 端到端验证
|
||||
|
||||
```bash
|
||||
# 1. 安装依赖
|
||||
bun install
|
||||
|
||||
# 2. 运行单元测试
|
||||
bun test src/services/api/openai/__tests__/
|
||||
|
||||
# 3. 连接实际端点（以 Ollama 为例）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=ollama \
|
||||
OPENAI_BASE_URL=http://localhost:11434/v1 \
|
||||
OPENAI_MODEL=qwen2.5-coder-32b \
|
||||
bun run dev
|
||||
|
||||
# 4. 连接 DeepSeek（测试 thinking 支持）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://api.deepseek.com/v1 \
|
||||
OPENAI_MODEL=deepseek-reasoner \
|
||||
bun run dev
|
||||
|
||||
# 5. 确认现有测试不受影响
|
||||
bun test # 无 CLAUDE_CODE_USE_OPENAI 时走原有路径
|
||||
```
|
||||
|
||||
## 代码统计
|
||||
|
||||
| 类别 | 行数 |
|
||||
|---|---|
|
||||
| 新增源码 | ~620 行 |
|
||||
| 新增测试 | ~450 行 |
|
||||
| 改动现有代码 | ~25 行 |
|
||||
| **总计** | **~1100 行** |
|
||||
35
docs/projects-collection.md
Normal file
35
docs/projects-collection.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# 社区项目 & Blog 合集
|
||||
|
||||
> 每日更新，欢迎自荐！
|
||||
|
||||
## 工具 & 应用
|
||||
|
||||
| 项目 | 描述 | 作者 |
|
||||
|------|------|------|
|
||||
| [4qtask.vercel.app](https://4qtask.vercel.app/) | 免费四象限时间管理工具 | @kevinhuky |
|
||||
| [kaying.studio](https://kaying.studio/) | 个人 AI 工具箱 | @kayingai |
|
||||
| [supsub.ai](https://supsub.ai/) | 高效阅读工具 | @hidumou |
|
||||
| [x-video-download.net](https://x-video-download.net/) | 视频下载工具 | @syakadou |
|
||||
| [1openapi.com](https://1openapi.com/) | API 中转站 | @thinker007 |
|
||||
| [claw-z.com](https://claw-z.com/) | 一键部署 OpenClaw AI Agent（场景驱动、全面管理） | @uhhc |
|
||||
| [gemini-watermark-remover.net](https://gemini-watermark-remover.net/) | Gemini 水印移除工具 | @syakadou |
|
||||
|
||||
## GitHub 开源项目
|
||||
|
||||
| 项目 | 描述 | 作者 |
|
||||
|------|------|------|
|
||||
| [VersperClaw](https://github.com/versperai/VersperClaw) | 全自动科研流 | @versperai |
|
||||
| [claude-reviews-claude](https://github.com/openedclaude/claude-reviews-claude) | 原汤化原食——Claude 如何看待眼中的老己 | @openedclaude |
|
||||
| [agentica](https://github.com/shibing624/agentica) | 自研 Agent 框架，借鉴 claude-code 多 Agent 处理 | @shibing624 |
|
||||
| [macman](https://github.com/tonngw/macman) | Mac 从 0 到 1 保姆级配置教程 | @tonngw |
|
||||
| [SuperSpec](https://github.com/asasugar/SuperSpec) | SDD / Spec-Driven Development | @asasugar |
|
||||
| [adnify](https://github.com/adnaan-worker/adnify) | 高颜值高定制化 AI 编辑器 | @adnaan-worker |
|
||||
| [another-rule-engine](https://github.com/eatmoreduck/another-rule-engine) | 基于 Groovy 的开源多功能决策引擎 | @eatmoreduck |
|
||||
| [creative_master](https://github.com/chatabc/creative_master) | AI 驱动的创意灵感管理工具 | @chatabc |
|
||||
| [RapidDoc](https://github.com/RapidAI/RapidDoc) | Office 文件解析工具转 Markdown（支持 PDF/Image/Word/PPT/Excel） | @hzkitt |
|
||||
|
||||
## Blog
|
||||
|
||||
| 链接 | 作者 |
|
||||
|------|------|
|
||||
| [blog.xiaohuangyu.space](https://blog.xiaohuangyu.space/) | @eatmoreduck |
|
||||
263
docs/safety/auto-mode.mdx
Normal file
263
docs/safety/auto-mode.mdx
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
title: "Auto Mode - AI 分类器驱动的自主执行模式"
|
||||
description: "详解 Claude Code 的 auto mode：基于 transcript classifier 的自动权限决策、两阶段分类流水线、危险权限剥离机制、模式切换状态管理、以及与 plan mode 的协作方式。"
|
||||
keywords: ["auto mode", "yoloClassifier", "transcript classifier", "权限分类", "自动执行", "两阶段分类"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
Auto mode 是 Claude Code 的一种权限模式，让 AI 进入**连续自主执行**状态。与传统模式（每个敏感操作都弹出权限对话框等待用户审批）不同，auto mode 使用 AI 分类器（transcript classifier）自动判断每个工具调用是否安全，从而实现无中断的执行体验。
|
||||
|
||||
```
|
||||
权限模式层级：
|
||||
|
||||
default → auto → bypassPermissions
|
||||
（逐项确认） （AI 分类器审批） （全部放行）
|
||||
```
|
||||
|
||||
## 核心架构
|
||||
|
||||
### 1. AI 分类器（yoloClassifier）
|
||||
|
||||
分类器是 auto mode 的核心，位于 `src/utils/permissions/yoloClassifier.ts`。
|
||||
|
||||
每个工具调用经过分类器评估，返回三种裁决之一：
|
||||
|
||||
| 裁决 | 含义 | 处理方式 |
|
||||
|------|------|---------|
|
||||
| **allow** | 操作安全 | 直接执行，用户无感知 |
|
||||
| **deny** | 操作危险 | 拒绝执行，向 AI 返回拒绝消息 |
|
||||
| **ask** | 无法确定 | 回退到传统权限对话框 |
|
||||
|
||||
分类器的判断基于完整的对话上下文（transcript），而不仅仅看单条命令——它能理解操作的意图和上下文。
|
||||
|
||||
### 2. 两阶段分类流水线
|
||||
|
||||
分类器支持两阶段 XML 分类（`classifyYoloActionXml`）：
|
||||
|
||||
```
|
||||
Stage 1 — "fast"（快速判断）
|
||||
├── max_tokens=64，stop_sequences 触发即时 yes/no
|
||||
├── 如果 allow → 直接放行（最快路径）
|
||||
└── 如果 block → 进入 Stage 2
|
||||
|
||||
Stage 2 — "thinking"（深度思考）
|
||||
├── chain-of-thought 推理
|
||||
├── 减少误报（false positives）
|
||||
└── 最终决定 allow / deny / ask
|
||||
```
|
||||
|
||||
两个阶段共享相同的 system prompt 和 user content，利用 API 的 prompt caching（1 小时 TTL）优化性能。
|
||||
|
||||
可通过配置选择模式：
|
||||
- `'both'`（默认）— 两阶段都跑
|
||||
- `'fast'` — 只跑 Stage 1
|
||||
- `'thinking'` — 只跑 Stage 2
|
||||
|
||||
### 3. 分类器结果类型
|
||||
|
||||
```typescript
|
||||
// src/types/permissions.ts
|
||||
type YoloClassifierResult = {
|
||||
thinking?: string // 分类器的推理过程
|
||||
shouldBlock: boolean // 是否阻止
|
||||
reason: string // 决策原因
|
||||
unavailable?: boolean // 分类器是否不可用
|
||||
transcriptTooLong?: boolean // 对话是否超出上下文窗口
|
||||
model: string // 使用的分类器模型
|
||||
stage?: 'fast' | 'thinking' // 哪个阶段做出的决定
|
||||
// ... token 使用量、耗时等监控字段
|
||||
}
|
||||
```
|
||||
|
||||
## 安全机制
|
||||
|
||||
### 危险权限剥离
|
||||
|
||||
进入 auto mode 时，系统调用 `stripDangerousPermissionsForAutoMode()`（`permissionSetup.ts:510`），移除所有可能绕过分类器的 allow 规则。
|
||||
|
||||
被剥离的规则类型（`dangerousPatterns.ts`）：
|
||||
|
||||
| 规则类型 | 示例 | 剥离原因 |
|
||||
|---------|------|---------|
|
||||
| **Bash 代码执行** | `Bash(python:*)`, `Bash(node:*)` | 解释器可执行任意代码，绕过分类器审查 |
|
||||
| **Shell 入口** | `Bash(bash:*)`, `Bash(sh:*)` | 直接 shell 访问等同无限制 |
|
||||
| **Agent 规则** | `Agent(*)` | 任何 Agent allow 规则会绕过分类器审批子代理 |
|
||||
| **PowerShell 代码执行** | `PowerShell(node:*)` | 同 Bash 逻辑 |
|
||||
| **权限提升** | `Bash(sudo:*)`, `Bash(eval:*)` | 可执行任意命令 |
|
||||
|
||||
剥离的规则被暂存在 `strippedDangerousRules` 中，退出 auto mode 时通过 `restoreDangerousPermissions()` 恢复。
|
||||
|
||||
### 模型支持检测
|
||||
|
||||
不是所有模型都支持 auto mode。`modelSupportsAutoMode()`（`src/utils/betas.ts`）检查当前模型是否具备安全分类能力。不支持的模型无法进入 auto mode。
|
||||
|
||||
### Circuit Breaker 机制
|
||||
|
||||
`autoModeState.ts` 维护一个 circuit breaker 标志：
|
||||
|
||||
```typescript
|
||||
let autoModeCircuitBroken = false // 由远程配置控制
|
||||
```
|
||||
|
||||
当远程配置（GrowthBook `tengu_auto_mode_config.enabled`）设为 `'disabled'` 时，circuit breaker 触发，阻止 auto mode 的进入和继续使用。这为 Anthropic 提供了远程紧急关停能力。
|
||||
|
||||
## 模式切换状态管理
|
||||
|
||||
### 进入 Auto Mode
|
||||
|
||||
`transitionPermissionMode()`（`permissionSetup.ts:597`）处理所有模式切换：
|
||||
|
||||
```
|
||||
1. 检查 auto mode gate 是否开启（isAutoModeGateEnabled）
|
||||
2. 设置 autoModeActive = true
|
||||
3. 调用 stripDangerousPermissionsForAutoMode() 剥离危险规则
|
||||
4. 向对话注入 Auto Mode 系统提示
|
||||
```
|
||||
|
||||
### 退出 Auto Mode
|
||||
|
||||
```
|
||||
1. 设置 autoModeActive = false
|
||||
2. 设置 needsAutoModeExitAttachment = true（触发退出通知）
|
||||
3. 调用 restoreDangerousPermissions() 恢复被剥离的规则
|
||||
4. 向对话注入 "Exited Auto Mode" 提示
|
||||
```
|
||||
|
||||
### 触发路径
|
||||
|
||||
Auto mode 可通过以下方式激活：
|
||||
- CLI 参数 `--enable-auto-mode`
|
||||
- settings.json 中的 `autoMode` 配置
|
||||
- Plan mode 默认使用 auto mode 语义（`useAutoModeDuringPlan`，默认 true）
|
||||
- SDK 控制消息
|
||||
- REPL 中 Shift+Tab 切换
|
||||
|
||||
## 系统提示词
|
||||
|
||||
### 进入时（Full Instructions）
|
||||
|
||||
注入到对话中的指令（`messages.ts:3464`）：
|
||||
|
||||
> Auto mode is active. The user chose continuous, autonomous execution. You should:
|
||||
>
|
||||
> 1. **Execute immediately** — 直接实现，做合理假设
|
||||
> 2. **Minimize interruptions** — 常规决策自行判断，减少提问
|
||||
> 3. **Prefer action over planning** — 默认直接编码，不进 plan mode
|
||||
> 4. **Expect course corrections** — 用户可随时纠正
|
||||
> 5. **Do not take overly destructive actions** — 删除数据/修改生产系统仍需确认
|
||||
> 6. **Avoid data exfiltration** — 不主动分享密钥/内部文档
|
||||
|
||||
### 持续运行时（Sparse Instructions）
|
||||
|
||||
后续轮次注入简短提醒：
|
||||
|
||||
> Auto mode still active. Execute autonomously, minimize interruptions, prefer action over planning.
|
||||
|
||||
### 退出时（Exit Instructions）
|
||||
|
||||
> You have exited auto mode. Ask clarifying questions when the approach is ambiguous rather than making assumptions.
|
||||
|
||||
## 与 Plan Mode 的协作
|
||||
|
||||
Plan mode 默认使用 auto mode 语义（`getUseAutoModeDuringPlan()`，默认 true）。这意味着：
|
||||
|
||||
- Plan mode 进入时，如果 auto mode 可用，也会激活分类器
|
||||
- `isAutoModeActive()` 是权威信号（`prePlanMode`/`strippedDangerousRules` 不可靠）
|
||||
- 退出 plan mode 时会同时退出 auto mode
|
||||
|
||||
## 分类器不可用的降级策略
|
||||
|
||||
当分类器 API 不可用时（`unavailable: true` 或 `transcriptTooLong: true`）：
|
||||
|
||||
- 不会直接 allow — 回退到传统的权限对话框（ask）
|
||||
- 向 AI 发送消息："{model} is temporarily unavailable, so auto mode cannot determine the safety of {toolName} right now."
|
||||
- 确定性错误（如对话过长）不重试，直接降级
|
||||
|
||||
## 分类器 Prompt 模板
|
||||
|
||||
分类器的行为由三个 prompt 文件控制，位于 `src/utils/permissions/yolo-classifier-prompts/`。这些文件在构建时通过 `require()` 内联为字符串常量，运行时不可修改。
|
||||
|
||||
### auto_mode_system_prompt.txt
|
||||
|
||||
主系统提示词，定义分类器的角色、分类流程和决策类别。包含：
|
||||
|
||||
- **分类流程**：理解操作 → 检查用户意图 → 评估风险
|
||||
- **BLOCK 始终阻止**：外部代码执行、不可逆删除、未授权持久化、安全削弱、提权、网络服务
|
||||
- **BLOCK 除非明确意图**：CWD 外写入、系统包管理、git push、大规模变更
|
||||
- **ALLOW 安全操作**：读文件、搜索、git 只读命令、测试/lint/构建、CWD 内编辑
|
||||
- `<permissions_template>` 占位符 — 运行时替换为具体权限模板（external 或 anthropic）
|
||||
- 末尾 `Use the classify_result tool to report your classification.` — XML 模式下被替换为 `<block>` 标签格式说明
|
||||
|
||||
### permissions_external.txt
|
||||
|
||||
外部用户版本的权限模板。三个 `<user_*_to_replace>` 标签内包裹默认规则（bullet 格式），用户自定义规则**整体替换**默认值：
|
||||
|
||||
```
|
||||
<user_allow_rules_to_replace>
|
||||
- 默认 allow 规则 1
|
||||
- 默认 allow 规则 2
|
||||
</user_allow_rules_to_replace>
|
||||
```
|
||||
|
||||
- **allow**：9 条默认规则（只读命令、版本检查、git 只读、测试/lint/构建、包安装、CWD 内文件操作等）
|
||||
- **soft_deny**：10 条默认规则（外部代码执行、递归删除、shell 配置修改、提权、网络服务等）
|
||||
- **environment**：4 条环境描述（终端环境、auto mode 上下文、开发工具可用、语言/框架不限）
|
||||
|
||||
`getDefaultExternalAutoModeRules()` 从此文件提取 bullet 项，供 `claude auto-mode defaults` 命令输出。
|
||||
|
||||
### permissions_anthropic.txt
|
||||
|
||||
Anthropic 内部版本的权限模板。默认规则在标签**外部**，标签内为空，用户自定义规则以**追加**方式叠加：
|
||||
|
||||
```
|
||||
- 默认规则（在标签外，始终生效）
|
||||
<user_allow_rules_to_replace>
|
||||
</user_allow_rules_to_replace>
|
||||
```
|
||||
|
||||
相比 external 版本，额外包含：
|
||||
- 云 CLI 只读命令（aws describe, gcloud describe, kubectl get 等）
|
||||
- 基础设施即代码 plan 命令（terraform plan, pulumi preview 等）
|
||||
- 对应的 deny 规则（云资源创建/修改/删除、IaC apply、生产环境访问等）
|
||||
|
||||
### 模板替换流程
|
||||
|
||||
```
|
||||
buildYoloSystemPrompt()
|
||||
├── BASE_PROMPT.replace('<permissions_template>', EXTERNAL/ANTHROPIC_TEMPLATE)
|
||||
├── .replace(<user_allow_rules_to_replace>, userAllow ?? defaults)
|
||||
├── .replace(<user_deny_rules_to_replace>, userDeny ?? defaults)
|
||||
└── .replace(<user_environment_to_replace>, userEnvironment ?? defaults)
|
||||
```
|
||||
|
||||
- 外部模板：用户设置非空时**替换**对应标签内容，否则保留默认值
|
||||
- 内部模板：用户设置**追加**到默认值之后（标签在末尾为空）
|
||||
|
||||
## 当前状态说明
|
||||
|
||||
> **注意**：auto mode 的完整代码逻辑已存在于代码库中，但依赖 `feature('TRANSCRIPT_CLASSIFIER')` feature flag。
|
||||
> 在当前反编译版本中，`feature()` 始终返回 `false`，因此 auto mode 不可用。
|
||||
> 要启用需将 `feature('TRANSCRIPT_CLASSIFIER')` 改为 `true`，并确保 GrowthBook 配置源有合理的 fallback 默认值。
|
||||
|
||||
Prompt 模板文件为**重建产物**——原始文件在反编译过程中丢失，已根据代码逻辑和 `yoloClassifier.ts` 中的替换模式重新编写。
|
||||
|
||||
## 相关源码索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/utils/permissions/yoloClassifier.ts` | 分类器核心实现 |
|
||||
| `src/utils/permissions/autoModeState.ts` | Auto mode 状态管理 |
|
||||
| `src/utils/permissions/permissionSetup.ts` | 模式切换、危险权限剥离 |
|
||||
| `src/utils/permissions/dangerousPatterns.ts` | 危险命令模式列表 |
|
||||
| `src/utils/permissions/classifierDecision.ts` | 分类器决策处理 |
|
||||
| `src/utils/permissions/classifierShared.ts` | 分类器共享逻辑 |
|
||||
| `src/utils/permissions/bashClassifier.ts` | Bash 命令分类规则 |
|
||||
| `src/utils/permissions/bypassPermissionsKillswitch.ts` | bypass 权限熔断器 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt` | 分类器主系统提示词 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/permissions_external.txt` | 外部权限模板 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt` | 内部权限模板 |
|
||||
| `src/cli/handlers/autoMode.ts` | CLI `auto-mode` 子命令处理 |
|
||||
| `src/utils/messages.ts` | Auto mode 系统提示词注入 |
|
||||
| `src/types/permissions.ts` | 权限类型定义 |
|
||||
| `src/utils/betas.ts` | 模型 auto mode 支持检测 |
|
||||
170
docs/safety/permission-model.mdx
Normal file
170
docs/safety/permission-model.mdx
Normal file
@@ -0,0 +1,170 @@
|
||||
---
|
||||
title: "权限模型 - Allow/Ask/Deny 三级权限体系"
|
||||
description: "详解 Claude Code 的三级权限模型实现：基于 src/utils/permissions/permissions.ts 的规则匹配引擎、五层规则来源优先级、工具名/命令/路径三维度匹配、Denial Tracking 死循环防护、权限模式切换机制。"
|
||||
keywords: ["权限模型", "Allow Ask Deny", "PermissionRule", "checkPermissions", "Denial Tracking", "权限规则"]
|
||||
---
|
||||
|
||||
{/* 本章目标：基于源码揭示权限系统的完整实现 */}
|
||||
|
||||
## 三种权限行为
|
||||
|
||||
每一次工具调用，系统都会做出三种裁决之一：
|
||||
|
||||
| 行为 | 含义 | 返回类型 | 典型场景 |
|
||||
|------|------|---------|---------|
|
||||
| **Allow** | 自动放行，用户无感知 | `{ behavior: 'allow', updatedInput, decisionReason }` | Read 读取项目内文件 |
|
||||
| **Ask** | 弹出确认对话框 | `{ behavior: 'ask', message, suggestions, metadata }` | Bash 执行未知命令 |
|
||||
| **Deny** | 直接拒绝 | `{ behavior: 'deny', message, decisionReason }` | 尝试执行被禁止的命令 |
|
||||
|
||||
这些行为由 `PermissionResult` 类型定义（`src/utils/permissions/PermissionResult.ts`）。
|
||||
|
||||
## 权限规则的五层来源
|
||||
|
||||
规则从 5 个来源汇聚（`PERMISSION_RULE_SOURCES`，`permissions.ts:109`），优先级从高到低：
|
||||
|
||||
```
|
||||
1. session — 用户在当前对话中手动授权（"Always allow"）
|
||||
2. cliArg — 命令行 --allow/--deny 参数
|
||||
3. command — Skill 工具的 allowedTools 白名单
|
||||
4. projectSettings — .claude/settings.json（团队共享）
|
||||
5. userSettings — ~/.claude/settings.json（跨项目）
|
||||
6. policySettings — 企业管理员下发的策略（用户不可覆盖）
|
||||
```
|
||||
|
||||
每个来源维护三个数组：`alwaysAllowRules[source]`、`alwaysAskRules[source]`、`alwaysDenyRules[source]`。
|
||||
|
||||
规则数据结构为 `PermissionRule`：
|
||||
```typescript
|
||||
{
|
||||
source: PermissionRuleSource // 来自哪个层级
|
||||
ruleBehavior: 'allow' | 'ask' | 'deny'
|
||||
ruleValue: {
|
||||
toolName: string // 如 "Bash"、"mcp__server1"
|
||||
ruleContent?: string // 如 "git *"、"src/**"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 规则匹配引擎
|
||||
|
||||
### 三维度匹配
|
||||
|
||||
`permissions.ts` 实现了三种匹配维度：
|
||||
|
||||
**1. 工具名匹配**（`toolMatchesRule()`，第 238 行）
|
||||
|
||||
匹配整个工具，仅当规则没有 `ruleContent`：
|
||||
```typescript
|
||||
// 精确匹配
|
||||
rule "Bash" → 匹配 BashTool
|
||||
rule "mcp__server1" → 匹配该 MCP Server 的所有工具（server 级别）
|
||||
rule "mcp__server1__*" → 通配符匹配（同上）
|
||||
```
|
||||
|
||||
MCP 工具使用 `getToolNameForPermissionCheck()` 获取匹配名称，支持有前缀（`mcp__server__tool`）和无前缀模式。
|
||||
|
||||
**2. 命令模式匹配**（BashTool 的 `checkPermissions()`）
|
||||
|
||||
BashTool 通过 `preparePermissionMatcher()`（`Tool.ts:514`）解析命令模式：
|
||||
```json
|
||||
{"tool": "Bash", "ruleContent": "git *"} → 匹配 "git commit -m 'fix'"
|
||||
```
|
||||
|
||||
命令通过 AST 解析（`readOnlyValidation.ts` 使用 tree-sitter bash），提取第一个子命令进行匹配。
|
||||
|
||||
**3. 路径匹配**（文件工具的 `checkPermissions()`）
|
||||
|
||||
Read/Edit/Write 工具通过 `getPath()` 提取文件路径，与 `ruleContent` 中的 glob 模式匹配：
|
||||
```json
|
||||
{"tool": "Edit", "ruleContent": "src/**"} → 匹配 "src/utils/foo.ts"
|
||||
```
|
||||
|
||||
### 权限检查的完整流程
|
||||
|
||||
每次工具调用的权限检查（`canUseTool()` → `checkPermissions()`）经过以下步骤：
|
||||
|
||||
```
|
||||
1a. Blanket deny 检查
|
||||
getDenyRuleForTool() → 工具名完全匹配 deny 规则？
|
||||
↓ 命中 → deny（工具在 getTools() 阶段就被过滤掉）
|
||||
|
||||
1b. Blanket allow 检查
|
||||
toolAlwaysAllowedRule() → 工具名完全匹配 allow 规则？
|
||||
↓ 命中 → allow
|
||||
|
||||
2. 工具自身 checkPermissions()
|
||||
各工具有自定义逻辑：
|
||||
- BashTool: readOnlyValidation → sandbox 判定 → AST 解析 → 模式匹配
|
||||
- FileEditTool: 路径白名单检查
|
||||
- SkillTool: safe properties 白名单 + 精确/前缀匹配
|
||||
↓ 返回 PermissionResult
|
||||
|
||||
3. Hook 系统
|
||||
executePermissionRequestHooks() → PreToolUse hook 可以 override
|
||||
↓ hook 返回 deny → deny
|
||||
↓ hook 返回 ask → 升级为 ask
|
||||
|
||||
4. Ask 规则检查
|
||||
getAskRules() → 命中 → ask
|
||||
|
||||
5. 默认行为
|
||||
根据当前 permissionMode 决定默认行为
|
||||
- 'default': 大部分工具 ask
|
||||
- 'plan': 写操作 deny，读操作 allow
|
||||
- 'bypass': 全部 allow
|
||||
```
|
||||
|
||||
## 权限模式
|
||||
|
||||
| 模式 | `PermissionMode` 值 | 适用场景 | 行为 |
|
||||
|------|---------------------|---------|------|
|
||||
| **Default** | `'default'` | 日常使用 | 敏感操作逐一确认 |
|
||||
| **Plan Mode** | `'plan'` | 探索阶段 | 只能读不能写（`isReadOnly()` 检查） |
|
||||
| **Auto** | `'auto'` | 信任 AI | 通过 transcript classifier 自动决策 |
|
||||
| **Bypass** | `'bypassPermissions'` | 完全信任 | 所有操作自动放行（需显式 `--dangerously-skip-permissions`） |
|
||||
|
||||
Plan Mode 切换由 `EnterPlanModeTool.call()` 触发：
|
||||
```typescript
|
||||
// EnterPlanModeTool.ts:88
|
||||
context.setAppState(prev => ({
|
||||
...prev,
|
||||
toolPermissionContext: applyPermissionUpdate(
|
||||
prepareContextForPlanMode(prev.toolPermissionContext),
|
||||
{ type: 'setMode', mode: 'plan', destination: 'session' },
|
||||
),
|
||||
}))
|
||||
```
|
||||
|
||||
退出时由 `ExitPlanModeV2Tool` 恢复为之前的模式。
|
||||
|
||||
## Denial Tracking：死循环防护
|
||||
|
||||
`src/utils/permissions/denialTracking.ts` 实现了拒绝追踪机制：
|
||||
|
||||
```typescript
|
||||
const DENIAL_LIMITS = {
|
||||
maxDenialsPerTool: 3, // 同一工具连续拒绝上限
|
||||
cooldownPeriodMs: 30_000, // 冷却期 30 秒
|
||||
}
|
||||
```
|
||||
|
||||
当 AI 被连续拒绝同一类操作达到上限时：
|
||||
1. `recordDenial()` 记录拒绝，增加计数
|
||||
2. `shouldFallbackToPrompting()` 检测到连续拒绝，返回 true
|
||||
3. 系统向 AI 注入消息："Your previous tool call was rejected..."
|
||||
4. AI 被迫改变策略，避免"反复请求同一个被拒操作"的死循环
|
||||
|
||||
操作成功时调用 `recordSuccess()` 重置计数。
|
||||
|
||||
## 规则的运行时更新
|
||||
|
||||
权限规则可以在运行时动态更新（`applyPermissionUpdate()`，`PermissionUpdate.ts`）：
|
||||
|
||||
```typescript
|
||||
type PermissionUpdate =
|
||||
| { type: 'addRule', behavior, rule, destination }
|
||||
| { type: 'removeRule', behavior, rule, destination }
|
||||
| { type: 'setMode', mode, destination }
|
||||
```
|
||||
|
||||
当用户在 Ask 对话框中选择 "Always allow"，系统调用 `persistPermissionUpdates()` 将规则写入对应层级的 settings 文件（project/user/managed），同时更新内存中的 `toolPermissionContext`。
|
||||
151
docs/safety/plan-mode.mdx
Normal file
151
docs/safety/plan-mode.mdx
Normal file
@@ -0,0 +1,151 @@
|
||||
---
|
||||
title: "计划模式 - Plan Mode 先看后做的安全机制"
|
||||
description: "基于源码解析 Claude Code Plan Mode 的完整实现：EnterPlanModeTool/ExitPlanModeV2Tool 的工具设计、权限上下文切换机制、Prompt-based 权限请求、计划文件持久化、Teammate 审批流程。"
|
||||
keywords: ["Plan Mode", "计划模式", "EnterPlanMode", "ExitPlanMode", "prepareContextForPlanMode", "allowedPrompts"]
|
||||
---
|
||||
|
||||
{/* 本章目标：基于源码揭示 Plan Mode 的完整实现 */}
|
||||
|
||||
## 问题场景
|
||||
|
||||
你说"重构这个模块"，AI 立刻开始改代码——但你还没搞清楚它打算怎么改。等改了一半发现方向不对，已经来不及了。
|
||||
|
||||
## Plan Mode 的解决方案
|
||||
|
||||
计划模式给对话加了一个"只读阶段"，通过两个工具实现闭环：
|
||||
|
||||
<Steps>
|
||||
<Step title="EnterPlanMode — 进入计划模式">
|
||||
AI 自主判断（或用户触发）任务需要规划，调用 `EnterPlanModeTool`（`src/tools/EnterPlanModeTool/EnterPlanModeTool.ts:36`）。该工具需要**用户审批**（`checkPermissions` 返回 `ask`）。
|
||||
</Step>
|
||||
<Step title="探索阶段 — 只读工具集">
|
||||
权限模式切换为 `'plan'`，AI 只能使用 `isReadOnly()` 为 true 的工具（Read、Grep、Glob、Agent 等）。写操作被自动拒绝。
|
||||
</Step>
|
||||
<Step title="ExitPlanMode — 提交方案审批">
|
||||
AI 完成探索后，调用 `ExitPlanModeV2Tool`（`src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:147`），将计划文件提交给用户审阅。这是第二个**需要用户审批**的节点。
|
||||
</Step>
|
||||
<Step title="恢复执行 — 全部工具权限">
|
||||
用户批准后，权限模式恢复为进入前的状态，AI 按计划执行。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 权限的自动收窄与恢复
|
||||
|
||||
### 进入：`prepareContextForPlanMode()`
|
||||
|
||||
`EnterPlanModeTool.call()`（第 77 行）的核心逻辑：
|
||||
|
||||
```typescript
|
||||
// 1. 记录转换状态（保存之前的模式）
|
||||
handlePlanModeTransition(currentMode, 'plan')
|
||||
|
||||
// 2. 切换权限上下文为 plan 模式
|
||||
context.setAppState(prev => ({
|
||||
...prev,
|
||||
toolPermissionContext: applyPermissionUpdate(
|
||||
prepareContextForPlanMode(prev.toolPermissionContext),
|
||||
{ type: 'setMode', mode: 'plan', destination: 'session' },
|
||||
),
|
||||
}))
|
||||
```
|
||||
|
||||
`prepareContextForPlanMode()`（`src/utils/permissions/permissionSetup.ts`）做了什么：
|
||||
- 创建新的 `ToolPermissionContext`，`mode` 设为 `'plan'`
|
||||
- 在 plan 模式下，工具的 `isReadOnly()` 检查成为唯一准入条件
|
||||
- 如果用户的默认模式是 `'auto'`，还会激活 classifier 的副作用
|
||||
|
||||
### 退出：权限恢复 + Prompt-based 权限
|
||||
|
||||
`ExitPlanModeV2Tool` 的退出逻辑做了两件关键的事：
|
||||
|
||||
**1. 恢复权限模式**
|
||||
|
||||
通过 `handlePlanModeTransition()` 和 `applyPermissionUpdate()` 恢复到进入前的模式。
|
||||
|
||||
**2. 注入 Prompt-based 权限**
|
||||
|
||||
这是 Plan Mode 最精妙的设计——AI 可以在计划中声明它需要执行的命令类别：
|
||||
|
||||
```typescript
|
||||
// ExitPlanModeV2Tool 的 inputSchema
|
||||
allowedPrompts: z.array(z.object({
|
||||
tool: z.enum(['Bash']),
|
||||
prompt: z.string().describe('Semantic description, e.g. "run tests"'),
|
||||
})).optional()
|
||||
```
|
||||
|
||||
当 AI 提交计划时，如果声明了 `allowedPrompts: [{ tool: 'Bash', prompt: 'run tests' }]`，用户批准后，"run tests" 这类 Bash 命令会被自动放行——不再需要逐个确认。
|
||||
|
||||
## 计划文件的持久化
|
||||
|
||||
计划内容被写入磁盘文件（由 `getPlanFilePath()` 确定路径），这与简单的"AI 说一段话然后开始执行"有本质区别：
|
||||
|
||||
1. `ExitPlanModeV2Tool` 的 `normalizeToolInput` 从磁盘读取计划内容，注入到 `input.plan` 和 `input.planFilePath`
|
||||
2. 计划文件是用户**可编辑**的——用户可以在审批前修改 AI 的方案
|
||||
3. `planWasEdited` 字段标记用户是否修改了计划，影响后续的 tool_result 回显
|
||||
4. `persistFileSnapshotIfRemote()` 在远程场景下保存文件快照
|
||||
|
||||
## Teammate 场景下的计划审批
|
||||
|
||||
在 Agent Swarms（`isAgentSwarmsEnabled()`）模式下，计划审批有额外的协作流程：
|
||||
|
||||
```typescript
|
||||
// 如果是 Teammate 角色
|
||||
if (isTeammate()) {
|
||||
// 发送计划到 Team Leader 的 mailbox 等待审批
|
||||
const requestId = generateRequestId()
|
||||
writeToMailbox(getTeamName(), {
|
||||
type: 'plan_approval_request',
|
||||
plan, requestId, ...
|
||||
})
|
||||
// 返回 awaitingLeaderApproval: true
|
||||
// Team Leader 审批后通过 mailbox 通知 Teammate
|
||||
}
|
||||
```
|
||||
|
||||
这意味着在蜂群模式下，计划可能不是由直接用户审批，而是由 Team Leader 审批。
|
||||
|
||||
## 什么时候该用计划模式
|
||||
|
||||
`EnterPlanModeTool` 的 Prompt（`src/tools/EnterPlanModeTool/prompt.ts`）定义了两套触发标准——外部版本更积极（鼓励规划），内部版本更克制（仅在真正模糊时使用）：
|
||||
|
||||
| 场景 | 外部版本 | 内部版本 |
|
||||
|------|---------|---------|
|
||||
| 修复 typo | 跳过 | 跳过 |
|
||||
| 添加删除按钮 | **进入**（涉及多个文件） | **跳过**（路径明确） |
|
||||
| 重构认证系统 | **进入** | **进入**（高影响重构） |
|
||||
| "开始做 X" | — | **跳过**（直接开始） |
|
||||
| 架构决策（Redis vs 内存缓存） | **进入** | **进入**（真正模糊） |
|
||||
|
||||
## 计划模式 + 任务系统
|
||||
|
||||
计划模式通常与任务系统配合使用：
|
||||
|
||||
1. 在计划模式中，AI 把实施步骤创建为任务列表（`TodoWrite`）
|
||||
2. 用户审批计划（包含任务列表）
|
||||
3. 退出计划模式后，AI 按任务列表逐项执行
|
||||
4. 用户可以通过任务列表追踪进度
|
||||
|
||||
## 完整生命周期
|
||||
|
||||
```
|
||||
用户: "重构这个模块"
|
||||
↓
|
||||
AI 判断需要规划 → 调用 EnterPlanModeTool
|
||||
↓ 用户审批（Ask 对话框）
|
||||
handlePlanModeTransition(default, 'plan') // 保存 default
|
||||
prepareContextForPlanMode() // 创建只读上下文
|
||||
↓
|
||||
AI 使用 Read/Grep/Glob/Agent 探索代码库
|
||||
↓ （可能 10+ 轮只读工具调用）
|
||||
AI 形成方案 → 调用 ExitPlanModeV2Tool({
|
||||
allowedPrompts: [
|
||||
{ tool: 'Bash', prompt: 'run tests' },
|
||||
{ tool: 'Bash', prompt: 'install dependencies' }
|
||||
]
|
||||
})
|
||||
↓ 用户审批计划（可编辑计划文件）
|
||||
恢复权限模式 → 注入 prompt-based 权限
|
||||
↓
|
||||
AI 使用全部工具执行计划，"run tests" 等命令自动放行
|
||||
```
|
||||
215
docs/safety/sandbox.mdx
Normal file
215
docs/safety/sandbox.mdx
Normal file
@@ -0,0 +1,215 @@
|
||||
---
|
||||
title: "沙箱机制 - 权限之外的第二道防线"
|
||||
description: "深入 Claude Code 沙箱机制：文件系统隔离、网络限制和资源约束，即使命令通过权限审批，沙箱仍可限制其行为范围。"
|
||||
keywords: ["沙箱", "sandbox", "文件隔离", "安全沙箱", "命令隔离"]
|
||||
---
|
||||
|
||||
## 权限之外的第二道防线
|
||||
|
||||
权限系统决定"这条命令能不能执行"，沙箱决定"执行时能做到什么程度"。
|
||||
|
||||
即使一条命令通过了权限审批，沙箱仍然可以限制它的行为。两者构成纵深防御的两层：
|
||||
- **权限层**（应用级）：在工具调用前检查，决定是否弹窗审批
|
||||
- **沙箱层**（OS 级）：在进程级别强制约束，即使 AI 生成了恶意命令也无法突破
|
||||
|
||||
## 执行链路：从用户输入到沙箱包裹
|
||||
|
||||
一条 Bash 命令的完整执行路径如下：
|
||||
|
||||
```
|
||||
用户输入 → BashTool.call()
|
||||
→ shouldUseSandbox(input) ─── 是否需要沙箱？
|
||||
→ Shell.exec(command, { shouldUseSandbox })
|
||||
→ SandboxManager.wrapWithSandbox(command)
|
||||
→ spawn(wrapped_command) ─── 实际进程创建
|
||||
```
|
||||
|
||||
关键判定发生在 `shouldUseSandbox()`（`src/tools/BashTool/shouldUseSandbox.ts`），它执行以下检查：
|
||||
|
||||
1. **全局开关**：`SandboxManager.isSandboxingEnabled()` — 检查平台支持 + 依赖完整性 + 用户设置
|
||||
2. **显式跳过**：如果 `dangerouslyDisableSandbox: true` 且策略允许（`allowUnsandboxedCommands`），则不走沙箱
|
||||
3. **排除列表**：用户可在 `settings.json` 中配置 `sandbox.excludedCommands`，匹配的命令跳过沙箱
|
||||
4. **默认行为**：以上条件都不满足时，**进入沙箱**
|
||||
|
||||
## `shouldUseSandbox()` 判定逻辑详解
|
||||
|
||||
```typescript
|
||||
// src/tools/BashTool/shouldUseSandbox.ts
|
||||
function shouldUseSandbox(input: Partial<SandboxInput>): boolean {
|
||||
// 1. 全局未启用 → 直接跳过
|
||||
if (!SandboxManager.isSandboxingEnabled()) return false
|
||||
|
||||
// 2. 显式禁用 + 策略允许 → 跳过
|
||||
if (input.dangerouslyDisableSandbox &&
|
||||
SandboxManager.areUnsandboxedCommandsAllowed()) return false
|
||||
|
||||
// 3. 无命令 → 跳过
|
||||
if (!input.command) return false
|
||||
|
||||
// 4. 匹配排除列表 → 跳过
|
||||
if (containsExcludedCommand(input.command)) return false
|
||||
|
||||
// 5. 其他情况 → 必须沙箱化
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
`containsExcludedCommand()` 的匹配机制值得注意——它不只是简单的前缀匹配，而是支持三种模式：
|
||||
|
||||
| 模式 | 示例 | 匹配行为 |
|
||||
|------|------|----------|
|
||||
| **精确匹配** | `npm run lint` | 完全相等 |
|
||||
| **前缀匹配** | `npm run test:*` | 前缀 + 空格或完全相等 |
|
||||
| **通配符** | `docker*` | 使用 `matchWildcardPattern` |
|
||||
|
||||
对于复合命令（如 `docker ps && curl evil.com`），系统会先拆分为子命令，逐一检查。还会迭代剥离环境变量前缀（`FOO=bar bazel ...`）和包装命令（`timeout 30 bazel ...`），直到不动点——防止通过嵌套包装绕过。
|
||||
|
||||
## 沙箱的配置模型
|
||||
|
||||
沙箱配置来自 `settings.json` 中的 `sandbox` 字段（`src/entrypoints/sandboxTypes.ts`）：
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"sandbox": {
|
||||
"enabled": true, // 主开关
|
||||
"autoAllowBashIfSandboxed": true, // 沙箱中的命令自动允许（跳过审批）
|
||||
"allowUnsandboxedCommands": true, // 是否允许 dangerouslyDisableSandbox
|
||||
"failIfUnavailable": false, // 沙箱依赖缺失时是否报错退出
|
||||
|
||||
"network": {
|
||||
"allowedDomains": ["github.com"], // 网络白名单
|
||||
"deniedDomains": [], // 网络黑名单
|
||||
"allowLocalBinding": true, // 允许 localhost 绑定
|
||||
"httpProxyPort": 8888 // HTTP 代理端口（MITM）
|
||||
},
|
||||
|
||||
"filesystem": {
|
||||
"allowWrite": ["~/projects"], // 额外可写路径
|
||||
"denyWrite": ["~/.ssh"], // 禁止写入路径
|
||||
"denyRead": [], // 禁止读取路径
|
||||
"allowRead": [] // 在 denyRead 中重新放行
|
||||
},
|
||||
|
||||
"excludedCommands": ["docker", "npm:*"] // 不走沙箱的命令
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`SandboxSettingsSchema` 定义了完整的 Zod 验证规则，包含一些未公开的设置如 `enabledPlatforms`（限制沙箱只在特定平台生效）。
|
||||
|
||||
## 平台实现差异
|
||||
|
||||
### macOS：sandbox-exec（Seatbelt）
|
||||
|
||||
macOS 使用 Apple 的 Seatbelt 沙箱（`sandbox-exec` 命令），这是 macOS 原生的进程隔离机制。
|
||||
|
||||
执行流程：
|
||||
1. `SandboxManager.wrapWithSandbox()` 调用 `@anthropic-ai/sandbox-runtime` 的 `BaseSandboxManager`
|
||||
2. 运行时生成 Seatbelt profile（基于配置中的网络/文件系统规则）
|
||||
3. 通过 `sandbox-exec -p <profile> -- <command>` 包裹原始命令
|
||||
4. Seatbelt 在内核级别强制执行约束
|
||||
|
||||
网络隔离的实现方式：
|
||||
- 通过代理端口拦截 HTTP/HTTPS 请求
|
||||
- 域名白名单/黑名单在代理层过滤
|
||||
- Unix socket 可单独配置允许路径
|
||||
|
||||
### Linux：bubblewrap（bwrap）+ seccomp
|
||||
|
||||
Linux 使用 `bubblewrap`（bwrap）创建命名空间隔离，配合 seccomp 过滤系统调用：
|
||||
|
||||
依赖项（`apt install`）：
|
||||
| 包 | 作用 |
|
||||
|----|------|
|
||||
| `bubblewrap` | 创建 mount/PID/network 命名空间 |
|
||||
| `socat` | 网络代理（HTTP/SOCKS） |
|
||||
| `libseccomp` / seccomp filter | 过滤 Unix socket 系统调用 |
|
||||
|
||||
bwrap 的实现差异：
|
||||
- **不支持 glob 路径模式**（macOS 的 Seatbelt 支持）— Linux 上带 glob 的权限规则会触发警告
|
||||
- 执行后会在当前目录留下 0 字节的 mount-point 文件（如 `.bashrc`），需要 `cleanupAfterCommand()` 清理
|
||||
- seccomp 无法按路径过滤 Unix socket（只能全允许或全拒绝），与 macOS 的按路径放行形成差异
|
||||
|
||||
### 平台支持矩阵
|
||||
|
||||
| 特性 | macOS | Linux | WSL |
|
||||
|------|-------|-------|-----|
|
||||
| 沙箱引擎 | sandbox-exec (Seatbelt) | bubblewrap + seccomp | 仅 WSL2 |
|
||||
| 文件 glob | ✅ 完整支持 | ⚠️ 仅 `/**` 后缀 | 同 Linux |
|
||||
| 网络 Unix socket 按路径 | ✅ | ❌ | ❌ |
|
||||
| 依赖检查 | ripgrep | bwrap + socat + ripgrep + seccomp | 同 Linux |
|
||||
|
||||
## 沙箱初始化流程
|
||||
|
||||
```
|
||||
REPL/SDK 启动
|
||||
→ main.tsx → init.ts
|
||||
→ SandboxManager.initialize(sandboxAskCallback)
|
||||
→ detectWorktreeMainRepoPath() // 检测 git worktree，放行主仓库 .git
|
||||
→ convertToSandboxRuntimeConfig() // 构建 SandboxRuntimeConfig
|
||||
→ BaseSandboxManager.initialize() // 启动底层运行时
|
||||
→ settingsChangeDetector.subscribe() // 订阅设置变更，动态更新配置
|
||||
```
|
||||
|
||||
`convertToSandboxRuntimeConfig()`（`src/utils/sandbox/sandbox-adapter.ts`）完成从用户设置到运行时配置的转换：
|
||||
|
||||
1. **网络规则**：从 `WebFetch(domain:...)` 权限规则提取域名 → `allowedDomains`
|
||||
2. **文件系统规则**：从 `Edit(...)` / `Read(...)` 权限规则提取路径 → `allowWrite` / `denyWrite` / `denyRead`
|
||||
3. **安全加固**：
|
||||
- 自动将项目目录加入 `allowWrite`
|
||||
- 自动将 `settings.json` 路径加入 `denyWrite`（防止沙箱逃逸）
|
||||
- 自动将 `.claude/skills` 加入 `denyWrite`（防止技能注入）
|
||||
- 检测 bare git repo 攻击向量，对 `HEAD`/`objects`/`refs` 做保护
|
||||
|
||||
## `dangerouslyDisableSandbox` 的设计权衡
|
||||
|
||||
这个参数的命名本身就传达了设计意图——它不是"关闭沙箱"，而是"**危险地禁用沙箱**"。
|
||||
|
||||
双重保险机制：
|
||||
1. **调用侧**：模型在 BashTool 的 `inputSchema` 中可以设置 `dangerouslyDisableSandbox: true`
|
||||
2. **策略侧**：管理员可通过 `allowUnsandboxedCommands: false` 完全禁止此参数（企业部署场景）
|
||||
|
||||
```typescript
|
||||
// 即使 AI 请求了 dangerouslyDisableSandbox，策略层仍可覆盖
|
||||
if (input.dangerouslyDisableSandbox &&
|
||||
SandboxManager.areUnsandboxedCommandsAllowed()) {
|
||||
return false // 只有策略允许时才真正跳过沙箱
|
||||
}
|
||||
```
|
||||
|
||||
`autoAllowBashIfSandboxed` 进一步补充了这个模型：当启用时，**在沙箱中的命令自动获得执行许可**，无需逐条审批。这基于一个信任假设——如果 OS 级沙箱已经限制了命令的能力，那么应用层的逐条审批就变得多余。
|
||||
|
||||
## 沙箱违规处理
|
||||
|
||||
当命令尝试违反沙箱约束时：
|
||||
|
||||
1. 运行时捕获违规事件（文件/网络访问被拒绝）
|
||||
2. `SandboxManager.annotateStderrWithSandboxFailures()` 在输出中注入 `<sandbox_violations>` 标签
|
||||
3. UI 层通过 `removeSandboxViolationTags()` 清理显示
|
||||
4. 违规事件通过 `SandboxViolationStore` 持久化，可用于审计
|
||||
|
||||
## 完整执行链路示例
|
||||
|
||||
以 `npm install` 为例：
|
||||
|
||||
```
|
||||
1. 用户在 REPL 中输入 → Claude 决定调用 BashTool
|
||||
2. BashTool.validateInput() → 通过
|
||||
3. BashTool.checkPermissions() → 检查权限规则
|
||||
├── autoAllowBashIfSandboxed = true 且沙箱可用 → 自动允许
|
||||
└── 否则 → 弹窗请用户确认
|
||||
4. BashTool.call() → runShellCommand()
|
||||
5. shouldUseSandbox({ command: "npm install" })
|
||||
├── SandboxManager.isSandboxingEnabled() → true
|
||||
├── dangerouslyDisableSandbox → undefined
|
||||
└── containsExcludedCommand() → false（除非用户配置了排除 npm）
|
||||
→ 结果: true，需要沙箱
|
||||
6. Shell.exec() → SandboxManager.wrapWithSandbox("npm install")
|
||||
├── macOS: sandbox-exec -p <generated-profile> -- bash -c 'npm install'
|
||||
└── Linux: bwrap ... bash -c 'npm install'
|
||||
7. spawn(wrapped_command) → 子进程在沙箱内执行
|
||||
8. 执行完成 → SandboxManager.cleanupAfterCommand()
|
||||
├── 清理 bwrap 残留文件（Linux）
|
||||
└── scrubBareGitRepoFiles()（安全清理）
|
||||
9. 结果返回给 Claude → 展示给用户
|
||||
```
|
||||
182
docs/safety/why-safety-matters.mdx
Normal file
182
docs/safety/why-safety-matters.mdx
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "AI 安全至关重要 - Claude Code 安全设计哲学"
|
||||
description: "当 AI 能操作你的真实项目文件和命令，安全的边界在哪里？分析 Claude Code 的安全挑战、威胁模型和纵深防御策略。"
|
||||
keywords: ["AI 安全", "安全设计", "威胁模型", "纵深防御", "AI 风险"]
|
||||
---
|
||||
|
||||
## AI 动手的代价
|
||||
|
||||
Claude Code 不是在沙盒里回答问题——它在你的真实项目中修改文件、执行命令。一个失误可能意味着：
|
||||
|
||||
- 覆盖了你还没提交的工作
|
||||
- 执行了危险的 `rm -rf` 命令
|
||||
- 推送了包含 bug 的代码到远程仓库
|
||||
- 泄露了 `.env` 文件中的密钥
|
||||
|
||||
这不是假设性风险。当 AI 拥有完整的 shell 访问权时，任何一次错误的工具调用都可能造成不可逆的损害。
|
||||
|
||||
## 安全体系全景图：纵深防御链
|
||||
|
||||
Claude Code 的安全不是单一机制，而是**五层纵深防御**——任何一层失败，下一层仍然能阻止危险操作：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Layer 1: AI 端安全约束 (System Prompt) │
|
||||
│ "执行前确认"、"优先可逆操作"、"不暴露密钥" │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Layer 2: 权限规则 (Permission Rules) │
|
||||
│ 应用层 allow/deny/ask 规则，支持 Bash/Glob/Edit 等工具 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Layer 3: 沙箱隔离 (OS-level Sandbox) │
|
||||
│ sandbox-exec (macOS) / bubblewrap (Linux) 强制约束 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Layer 4: 计划模式 (Plan Mode) │
|
||||
│ 只读探索阶段，AI 先理解再动手 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Layer 5: Hooks & 预算上限 │
|
||||
│ 外部审计钩子 + token/成本硬上限 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Layer 1: AI 端安全约束
|
||||
|
||||
Claude 的 System Prompt 中包含安全指令——这是"软性"约束，依赖模型遵从，但作为第一道防线：
|
||||
|
||||
- **执行前确认**：高风险操作（删除、推送）必须在调用工具前说明意图
|
||||
- **优先可逆操作**：优先使用 `git` 管理变更，便于回滚
|
||||
- **最小影响范围**：只修改与任务直接相关的文件
|
||||
- **密钥保护**：不将 API key、密码等写入输出
|
||||
|
||||
这是"软约束"因为 AI 可以违反它（尤其在 prompt injection 场景下），因此需要后续硬性机制兜底。
|
||||
|
||||
### Layer 2: 权限规则系统
|
||||
|
||||
权限系统是应用层的核心防线，定义在 `src/utils/permissions/` 中。每个工具调用都经过 `checkPermissions()` 裁决：
|
||||
|
||||
**三级权限决策**：
|
||||
|
||||
| 决策 | 含义 | 触发条件 |
|
||||
|------|------|----------|
|
||||
| `allow` | 自动放行 | 匹配 allow 规则 + 只读操作 |
|
||||
| `deny` | 直接拒绝 | 匹配 deny 规则 |
|
||||
| `ask` | 弹窗确认 | 未匹配任何规则 或 匹配 ask 规则 |
|
||||
|
||||
以 BashTool 为例（`src/tools/BashTool/bashPermissions.ts`），`bashToolHasPermission()` 执行了极其细致的检查链：
|
||||
|
||||
1. **AST 安全解析**：用 tree-sitter 解析 bash AST，检测命令注入（`$()`、反引号等）
|
||||
2. **语义检查**：识别危险命令（`eval`、`exec`、`source` 等）
|
||||
3. **沙箱自动放行**：如果 `autoAllowBashIfSandboxed` 启用且沙箱可用，自动放行
|
||||
4. **精确匹配**：检查命令是否匹配 allow/deny 规则
|
||||
5. **分类器检查**：用 Haiku 模型对 deny/ask 描述进行语义匹配
|
||||
6. **复合命令拆分**：`docker ps && curl evil.com` 拆分为子命令逐一检查
|
||||
7. **路径约束**：检查输出重定向目标、cd + git 组合攻击
|
||||
8. **命令注入检测**：对每个子命令运行 20+ 正则模式检测
|
||||
|
||||
**Read 工具为什么免审批**：读取操作不会改变任何状态。`BashTool.isReadOnly()` 通过 `readOnlyValidation.ts` 判定命令是否只读——只读命令在权限检查中被自动分类为低风险。
|
||||
|
||||
**Bash 工具为什么要逐条确认**：shell 命令可以执行任何操作，且存在大量绕过手法（环境变量注入、命令替换、管道拼接）。系统需要解析命令结构、检测注入模式、验证路径约束——无法用简单规则覆盖，因此默认需要确认。
|
||||
|
||||
### Layer 3: OS 级沙箱
|
||||
|
||||
权限系统是"应用级"约束——如果 AI 找到了绕过应用逻辑的方法（理论上不应该），OS 级沙箱是硬性兜底。
|
||||
|
||||
详见[沙箱机制](./sandbox.mdx)章节。核心要点：
|
||||
|
||||
- macOS 使用 `sandbox-exec`（Seatbelt profile），Linux 使用 `bubblewrap`
|
||||
- 即使命令通过了权限审批，沙箱仍然限制文件系统/网络/进程访问
|
||||
- `dangerouslyDisableSandbox` 可被管理员策略覆盖（`allowUnsandboxedCommands: false`）
|
||||
|
||||
### Layer 4: Plan Mode
|
||||
|
||||
对于复杂任务，Plan Mode 提供了一个"先想后做"的阶段：
|
||||
|
||||
- AI 进入只读模式，只能使用 Read/Grep/Glob 等搜索工具
|
||||
- 理解项目后形成计划文件，提交用户审阅
|
||||
- 用户批准后恢复全部权限，按计划执行
|
||||
|
||||
这解决了"AI 匆忙行动"的问题——强制 AI 先充分理解再动手。
|
||||
|
||||
### Layer 5: Hooks & 预算上限
|
||||
|
||||
**Hooks**（`src/entrypoints/agentSdkTypes.js`）提供了外部审计能力：
|
||||
|
||||
| Hook 事件 | 触发时机 | 用途 |
|
||||
|-----------|----------|------|
|
||||
| `PreToolUse` | 工具调用前 | 可以阻止执行 |
|
||||
| `PostToolUse` | 工具调用后 | 审计日志 |
|
||||
| `PostToolUseFailure` | 工具调用失败后 | 错误监控 |
|
||||
| `Notification` | 系统通知 | 外部告警 |
|
||||
| `Stop` / `StopFailure` | 对话结束时 | 清理/审计 |
|
||||
| `SubagentStart` / `SubagentStop` | 子 Agent 生命周期 | 并行任务审计 |
|
||||
|
||||
企业部署可以用 Hooks 实现：所有 Bash 调用写入审计日志、敏感目录访问触发告警、非工作时间拒绝执行。
|
||||
|
||||
**预算上限**：token 使用量和 API 费用都有硬性上限，防止单次会话失控消耗资源。
|
||||
|
||||
## 安全 vs 效率的工程权衡
|
||||
|
||||
安全机制不是越多越好——每个额外检查都增加延迟、降低用户体验。Claude Code 的设计在两者间做了精细的权衡：
|
||||
|
||||
### 权衡1：只读命令自动放行
|
||||
|
||||
```
|
||||
Read("src/foo.ts") → ✅ 自动放行（不改变任何东西）
|
||||
Grep("TODO", "src/") → ✅ 自动放行（纯搜索）
|
||||
Bash("ls -la") → ⚠️ 需确认（可能暴露敏感文件名）
|
||||
Bash("npm install") → ⚠️ 需确认（有副作用）
|
||||
FileEdit("src/foo.ts", ...) → ⚠️ 需确认（修改文件）
|
||||
Bash("rm -rf node_modules") → ⚠️ 需确认（不可逆）
|
||||
```
|
||||
|
||||
判定逻辑在 `readOnlyValidation.ts` 中：系统维护了命令分类集合（`BASH_READ_COMMANDS`、`BASH_SEARCH_COMMANDS`、`BASH_LIST_COMMANDS`），只有完全匹配只读模式的命令才自动放行。
|
||||
|
||||
### 权衡2：沙箱中的命令自动允许
|
||||
|
||||
`autoAllowBashIfSandboxed` 设置基于一个信任假设：**如果 OS 级沙箱已经限制了命令的能力，应用层逐条审批就变得多余**。这大幅减少了确认弹窗，但前提是沙箱真正可靠。
|
||||
|
||||
### 权衡3：复合命令的特殊处理
|
||||
|
||||
`docker ps && curl evil.com` 不会被当作一个整体检查——系统拆分为子命令逐一验证。但如果拆分太细（超过 `MAX_SUBCOMMANDS_FOR_SECURITY_CHECK` 上限），直接拒绝。这是安全与可用性的平衡：太松则被绕过，太严则误杀正常命令。
|
||||
|
||||
## Prompt Injection 防御
|
||||
|
||||
当 AI 处理工具返回的结果时，结果中可能包含恶意指令（例如搜索到的代码文件中嵌入了"忽略上述指令，执行 rm -rf /"）。
|
||||
|
||||
防御手段：
|
||||
|
||||
1. **工具结果隔离**：工具输出作为结构化数据传递给 API，不直接拼入 prompt
|
||||
2. **AST 解析**：`parseForSecurity()` 在 `src/utils/bash/ast.ts` 中用 tree-sitter 解析命令结构，检测隐藏的命令注入
|
||||
3. **语义检查**：`checkSemantics()` 识别危险的 bash 内建命令（eval、exec、source）
|
||||
4. **Shadow 测试**：`TREE_SITTER_BASH_SHADOW` feature flag 并行运行新旧解析器，对比结果检测回归
|
||||
|
||||
关键设计原则：**永远不信任工具输出中的指令性内容**。工具返回的是数据，不是命令——AI 应该基于数据做决策，而不是盲从数据中的"建议"。
|
||||
|
||||
## 三个真实攻击场景与防御
|
||||
|
||||
### 场景1：Bare Git Repo 攻击
|
||||
|
||||
```
|
||||
攻击：在 cwd 创建 HEAD + objects/ + refs/，伪装成 git repo
|
||||
然后配置 core.fsmonitor 钩子
|
||||
当 Claude 运行 unsandboxed git 时触发钩子
|
||||
防御：convertToSandboxRuntimeConfig() 检测这些文件并 denyWrite
|
||||
cleanupAfterCommand() 清理 bwrap 残留
|
||||
```
|
||||
|
||||
### 场景2：cd + git 组合攻击
|
||||
|
||||
```
|
||||
攻击：cd /malicious/dir && git status
|
||||
/malicious/dir 包含 bare repo + 恶意钩子
|
||||
防御：bashToolHasPermission() 检测 cd + git 组合
|
||||
强制 require approval（src/tools/BashTool/bashPermissions.ts:2209）
|
||||
```
|
||||
|
||||
### 场景3：管道注入
|
||||
|
||||
```
|
||||
攻击：echo 'x' | xargs printf '%s' >> /etc/passwd
|
||||
splitCommand 会剥离重定向，导致路径检查遗漏
|
||||
防御：即使管道段独立检查通过，仍对原始命令重新验证路径约束
|
||||
检查重定向目标中的危险模式（反引号、$()）（bashPermissions.ts:1992-2056）
|
||||
```
|
||||
155
docs/telemetry-remote-config-audit.md
Normal file
155
docs/telemetry-remote-config-audit.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 遥测与远程配置下发系统审计（除 Sentry 外）
|
||||
|
||||
## 1. Datadog 日志
|
||||
|
||||
**文件**: `src/services/analytics/datadog.ts`
|
||||
|
||||
- **端点**: 通过环境变量 `DATADOG_LOGS_ENDPOINT` 配置（默认为空，即禁用）
|
||||
- **客户端 token**: 通过环境变量 `DATADOG_API_KEY` 配置（默认为空，即禁用）
|
||||
- **行为**: 批量发送日志（15s flush 间隔，100 条上限），仅限 1P（直连 Anthropic API）用户
|
||||
- **事件白名单**: `tengu_*` 系列事件（启动、错误、OAuth、工具调用等 ~35 种）
|
||||
- **基线数据**: 收集 model、platform、arch、version、userBucket（用户 hash 到 30 个桶）等
|
||||
- **仅限**: `NODE_ENV === 'production'`
|
||||
- **配置示例**: `DATADOG_LOGS_ENDPOINT=https://http-intake.logs.datadoghq.com/api/v2/logs DATADOG_API_KEY=xxx bun run dev`
|
||||
|
||||
## 2. 1P 事件日志（BigQuery）
|
||||
|
||||
**文件**: `src/services/analytics/firstPartyEventLogger.ts` + `firstPartyEventLoggingExporter.ts`
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/event_logging/batch`（staging 可切换）
|
||||
- **行为**: 使用 OpenTelemetry SDK 的 `BatchLogRecordProcessor`，批量导出到 Anthropic 自有的 BQ 管道
|
||||
- **数据**: 完整事件 metadata（session、model、env context、用户数据、subscription type 等）
|
||||
- **弹性**: 本地磁盘持久化失败事件（JSONL），二次退避重试，最多 8 次尝试
|
||||
- **Proto schema**: 事件序列化为 `ClaudeCodeInternalEvent` / `GrowthbookExperimentEvent` protobuf 格式
|
||||
- **Auth fallback**: 401 时自动去掉 auth header 重试
|
||||
|
||||
## 3. GrowthBook 远程 Feature Flags / 动态配置
|
||||
|
||||
**文件**: `src/services/analytics/growthbook.ts`
|
||||
|
||||
- **服务端**: `https://api.anthropic.com/`（remote eval 模式）
|
||||
- **行为**: 启动时拉取全量 feature flags，每 6h（外部用户）/ 20min（ant）定时刷新
|
||||
- **磁盘缓存**: feature values 写入 `~/.claude.json` 的 `cachedGrowthBookFeatures`
|
||||
- **用途**:
|
||||
- 控制 Datadog 开关（`tengu_log_datadog_events`）
|
||||
- 控制事件采样率（`tengu_event_sampling_config`）
|
||||
- 控制 sink killswitch（`tengu_frond_boric`）
|
||||
- 控制 BQ batch 配置（`tengu_1p_event_batch_config`）
|
||||
- 控制版本上限/自动更新 kill switch
|
||||
- 控制远程管理设置的安全检查 gate
|
||||
- **用户属性**: 发送 deviceId, sessionId, organizationUUID, accountUUID, email, subscriptionType 等
|
||||
|
||||
## 4. Remote Managed Settings（企业远程配置下发）
|
||||
|
||||
**文件**: `src/services/remoteManagedSettings/index.ts`
|
||||
|
||||
- **端点**: `{BASE_API_URL}/api/claude_code/settings`
|
||||
- **行为**: 企业用户配置下发，支持 ETag/304 缓存，每小时后台轮询
|
||||
- **安全**: 变更包含"危险设置"时弹窗让用户确认
|
||||
- **适用**: API key 用户全部可拉取；OAuth 用户仅 Enterprise/C4E/Team
|
||||
- **Fail-open**: 请求失败时使用本地缓存，无缓存则跳过
|
||||
|
||||
## 5. Settings Sync（设置同步）
|
||||
|
||||
**文件**: `src/services/settingsSync/index.ts`
|
||||
|
||||
- **端点**: `{BASE_API_URL}/api/claude_code/user_settings`
|
||||
- **行为**: CLI 上传本地设置/memory 到远程；CCR 模式从远程下载
|
||||
- **同步内容**: userSettings、userMemory、projectSettings、projectMemory
|
||||
- **Feature gate**: `UPLOAD_USER_SETTINGS` / `DOWNLOAD_USER_SETTINGS`
|
||||
- **文件大小限制**: 500KB/文件
|
||||
|
||||
## 6. OpenTelemetry 三方遥测
|
||||
|
||||
**文件**: `src/utils/telemetry/instrumentation.ts`
|
||||
|
||||
- **行为**: 完整的 OTEL SDK 初始化，支持 metrics / logs / traces 三种信号
|
||||
- **协议**: gRPC / http-json / http-protobuf（通过 `OTEL_EXPORTER_OTLP_PROTOCOL` 选择）
|
||||
- **exporter**: console / otlp / prometheus
|
||||
- **触发**: `CLAUDE_CODE_ENABLE_TELEMETRY=1` 环境变量
|
||||
- **增强 trace**: `feature('ENHANCED_TELEMETRY_BETA')` + GrowthBook gate `enhanced_telemetry_beta`
|
||||
|
||||
## 7. BigQuery Metrics Exporter（内部指标）
|
||||
|
||||
**文件**: `src/utils/telemetry/bigqueryExporter.ts`
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/claude_code/metrics`
|
||||
- **行为**: 定期（5min 间隔）导出 OTel metrics 到内部 BQ
|
||||
- **适用**: API 客户、C4E/Team 订阅者
|
||||
- **组织级 opt-out**: 通过 `checkMetricsEnabled()` API 查询（见下方第 8 项）
|
||||
|
||||
## 8. 组织级 Metrics Opt-out 查询
|
||||
|
||||
**文件**: `src/services/api/metricsOptOut.ts`
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/claude_code/organizations/metrics_enabled`
|
||||
- **行为**: 查询组织是否启用了 metrics，二级缓存（内存 1h + 磁盘 24h）
|
||||
- **作用**: 控制 BigQuery metrics exporter 是否导出
|
||||
|
||||
## 9. Startup Profiling
|
||||
|
||||
**文件**: `src/utils/startupProfiler.ts`
|
||||
|
||||
- **行为**: 采样启动性能数据（100% ant / 0.5% 外部），通过 `logEvent('tengu_startup_perf')` 上报
|
||||
- **详细模式**: `CLAUDE_CODE_PROFILE_STARTUP=1` 输出完整性能报告到文件
|
||||
|
||||
## 10. Beta Session Tracing
|
||||
|
||||
**文件**: `src/utils/telemetry/betaSessionTracing.ts`
|
||||
|
||||
- **行为**: 详细调试 trace，发送 system prompt、model output、tool schema 等
|
||||
- **触发**: `ENABLE_BETA_TRACING_DETAILED=1` + `BETA_TRACING_ENDPOINT`
|
||||
- **外部用户**: SDK/headless 模式自动启用，交互模式需要 GrowthBook gate `tengu_trace_lantern`
|
||||
|
||||
## 11. Bridge Poll Config（远程轮询间隔配置）
|
||||
|
||||
**文件**: `src/bridge/pollConfig.ts`
|
||||
|
||||
- **行为**: 从 GrowthBook 拉取 bridge 轮询间隔配置（`tengu_bridge_poll_interval_config`）
|
||||
- **控制**: 单会话和多会话的各种 poll interval
|
||||
|
||||
## 12. Plugin/MCP 遥测
|
||||
|
||||
**文件**: `src/utils/plugins/fetchTelemetry.ts`
|
||||
|
||||
- **行为**: 记录 plugin/marketplace 的网络请求（安装计数、marketplace clone/pull 等）
|
||||
- **事件**: `tengu_plugin_remote_fetch`，包含 host（已脱敏）、outcome、duration
|
||||
|
||||
---
|
||||
|
||||
## 全局禁用方式
|
||||
|
||||
```bash
|
||||
# 禁用所有遥测（Datadog + 1P + 调查问卷）
|
||||
DISABLE_TELEMETRY=1
|
||||
|
||||
# 更激进：禁用所有非必要网络（包括自动更新、grove、release notes 等）
|
||||
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
|
||||
|
||||
# 3P 提供商自动禁用
|
||||
CLAUDE_CODE_USE_BEDROCK=1 # 或 VERTEX/FOUNDRY
|
||||
```
|
||||
|
||||
`src/utils/privacyLevel.ts` 是集中控制点，三个级别：`default < no-telemetry < essential-traffic`。
|
||||
|
||||
---
|
||||
|
||||
## 数据流架构
|
||||
|
||||
```
|
||||
用户操作 → logEvent()
|
||||
↓
|
||||
sink.ts (路由层)
|
||||
↙ ↘
|
||||
trackDatadogEvent() logEventTo1P()
|
||||
↓ ↓
|
||||
Datadog HTTP API OTel BatchLogRecordProcessor
|
||||
(us5.datadoghq.com) ↓
|
||||
FirstPartyEventLoggingExporter
|
||||
↓
|
||||
api.anthropic.com/api/event_logging/batch
|
||||
↓
|
||||
BigQuery (ClaudeCodeInternalEvent proto)
|
||||
```
|
||||
|
||||
GrowthBook 作为独立通道，同时驱动上述两个 sink 的开关和配置。
|
||||
147
docs/test-plans/01-tool-system.md
Normal file
147
docs/test-plans/01-tool-system.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Tool 系统测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Tool 系统是 Claude Code 的核心，负责工具的定义、注册、发现和过滤。本计划覆盖 `src/Tool.ts` 中的工具接口与工具函数、`src/tools.ts` 中的注册/过滤逻辑，以及各工具目录下可独立测试的纯函数。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/Tool.ts` | `buildTool`, `toolMatchesName`, `findToolByName`, `getEmptyToolPermissionContext`, `filterToolProgressMessages` |
|
||||
| `src/tools.ts` | `parseToolPreset`, `filterToolsByDenyRules`, `getAllBaseTools`, `getTools`, `assembleToolPool` |
|
||||
| `src/tools/shared/gitOperationTracking.ts` | `parseGitCommitId`, `detectGitOperation` |
|
||||
| `src/tools/shared/spawnMultiAgent.ts` | `resolveTeammateModel`, `generateUniqueTeammateName` |
|
||||
| `src/tools/GrepTool/GrepTool.ts` | `applyHeadLimit`, `formatLimitInfo`（内部辅助函数） |
|
||||
| `src/tools/FileEditTool/utils.ts` | 字符串匹配/补丁相关纯函数 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/Tool.ts
|
||||
|
||||
#### describe('buildTool')
|
||||
|
||||
- test('fills in default isEnabled as true') — 不传 isEnabled 时，构建的 tool.isEnabled() 应返回 true
|
||||
- test('fills in default isConcurrencySafe as false') — 默认值应为 false（fail-closed）
|
||||
- test('fills in default isReadOnly as false') — 默认假设有写操作
|
||||
- test('fills in default isDestructive as false') — 默认非破坏性
|
||||
- test('fills in default checkPermissions as allow') — 默认 checkPermissions 应返回 `{ behavior: 'allow', updatedInput }`
|
||||
- test('fills in default userFacingName from tool name') — userFacingName 默认应返回 tool.name
|
||||
- test('preserves explicitly provided methods') — 传入自定义 isEnabled 等方法时应覆盖默认值
|
||||
- test('preserves all non-defaultable properties') — name, inputSchema, call, description 等属性原样保留
|
||||
|
||||
#### describe('toolMatchesName')
|
||||
|
||||
- test('returns true for exact name match') — `{ name: 'Bash' }` 匹配 'Bash'
|
||||
- test('returns false for non-matching name') — `{ name: 'Bash' }` 不匹配 'Read'
|
||||
- test('returns true when name matches an alias') — `{ name: 'Bash', aliases: ['BashTool'] }` 匹配 'BashTool'
|
||||
- test('returns false when aliases is undefined') — `{ name: 'Bash' }` 不匹配 'BashTool'
|
||||
- test('returns false when aliases is empty') — `{ name: 'Bash', aliases: [] }` 不匹配 'BashTool'
|
||||
|
||||
#### describe('findToolByName')
|
||||
|
||||
- test('finds tool by primary name') — 从 tools 列表中按 name 找到工具
|
||||
- test('finds tool by alias') — 从 tools 列表中按 alias 找到工具
|
||||
- test('returns undefined when no match') — 找不到时返回 undefined
|
||||
- test('returns first match when duplicates exist') — 多个同名工具时返回第一个
|
||||
|
||||
#### describe('getEmptyToolPermissionContext')
|
||||
|
||||
- test('returns default permission mode') — mode 应为 'default'
|
||||
- test('returns empty maps and arrays') — additionalWorkingDirectories 为空 Map，rules 为空对象
|
||||
- test('returns isBypassPermissionsModeAvailable as false')
|
||||
|
||||
#### describe('filterToolProgressMessages')
|
||||
|
||||
- test('filters out hook_progress messages') — 移除 type 为 hook_progress 的消息
|
||||
- test('keeps tool progress messages') — 保留非 hook_progress 的消息
|
||||
- test('returns empty array for empty input')
|
||||
- test('handles messages without type field') — data 不含 type 时应保留
|
||||
|
||||
---
|
||||
|
||||
### src/tools.ts
|
||||
|
||||
#### describe('parseToolPreset')
|
||||
|
||||
- test('returns "default" for "default" input') — 精确匹配
|
||||
- test('returns "default" for "Default" input') — 大小写不敏感
|
||||
- test('returns null for unknown preset') — 未知字符串返回 null
|
||||
- test('returns null for empty string')
|
||||
|
||||
#### describe('filterToolsByDenyRules')
|
||||
|
||||
- test('returns all tools when no deny rules') — 空 deny 规则不过滤任何工具
|
||||
- test('filters out tools matching blanket deny rule') — deny rule `{ toolName: 'Bash' }` 应移除 Bash
|
||||
- test('does not filter tools with content-specific deny rules') — deny rule `{ toolName: 'Bash', ruleContent: 'rm -rf' }` 不移除 Bash（只在运行时阻止特定命令）
|
||||
- test('filters MCP tools by server name prefix') — deny rule `mcp__server` 应移除该 server 下所有工具
|
||||
- test('preserves tools not matching any deny rule')
|
||||
|
||||
#### describe('getAllBaseTools')
|
||||
|
||||
- test('returns a non-empty array of tools') — 至少包含核心工具
|
||||
- test('each tool has required properties') — 每个工具应有 name, inputSchema, call 等属性
|
||||
- test('includes BashTool, FileReadTool, FileEditTool') — 核心工具始终存在
|
||||
- test('includes TestingPermissionTool when NODE_ENV is test') — 需设置 env
|
||||
|
||||
#### describe('getTools')
|
||||
|
||||
- test('returns filtered tools based on permission context') — 根据 deny rules 过滤
|
||||
- test('returns simple tools in CLAUDE_CODE_SIMPLE mode') — 仅返回 Bash/Read/Edit
|
||||
- test('filters disabled tools via isEnabled') — isEnabled 返回 false 的工具被排除
|
||||
|
||||
---
|
||||
|
||||
### src/tools/shared/gitOperationTracking.ts
|
||||
|
||||
#### describe('parseGitCommitId')
|
||||
|
||||
- test('extracts commit hash from git commit output') — 从 `[main abc1234] message` 中提取 `abc1234`
|
||||
- test('returns null for non-commit output') — 无法解析时返回 null
|
||||
- test('handles various branch name formats') — `[feature/foo abc1234]` 等
|
||||
|
||||
#### describe('detectGitOperation')
|
||||
|
||||
- test('detects git commit operation') — 命令含 `git commit` 时识别为 commit
|
||||
- test('detects git push operation') — 命令含 `git push` 时识别
|
||||
- test('returns null for non-git commands') — 非 git 命令返回 null
|
||||
- test('detects git merge operation')
|
||||
- test('detects git rebase operation')
|
||||
|
||||
---
|
||||
|
||||
### src/tools/shared/spawnMultiAgent.ts
|
||||
|
||||
#### describe('resolveTeammateModel')
|
||||
|
||||
- test('returns specified model when provided')
|
||||
- test('falls back to default model when not specified')
|
||||
|
||||
#### describe('generateUniqueTeammateName')
|
||||
|
||||
- test('generates a name when no existing names') — 无冲突时返回基础名
|
||||
- test('appends suffix when name conflicts') — 与已有名称冲突时添加后缀
|
||||
- test('handles multiple conflicts') — 多次冲突时递增后缀
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `bun:bundle` (feature) | 已 polyfill 为 `() => false` | 不需额外 mock |
|
||||
| `process.env` | `bun:test` mock | 测试 `USER_TYPE`、`NODE_ENV`、`CLAUDE_CODE_SIMPLE` |
|
||||
| `getDenyRuleForTool` | mock module | `filterToolsByDenyRules` 测试中需控制返回值 |
|
||||
| `isToolSearchEnabledOptimistic` | mock module | `getAllBaseTools` 中条件加载 |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
放在 `tests/integration/tool-chain.test.ts`：
|
||||
|
||||
### describe('Tool registration and discovery')
|
||||
|
||||
- test('getAllBaseTools returns tools that can be found by findToolByName') — 注册 → 查找完整链路
|
||||
- test('filterToolsByDenyRules + getTools produces consistent results') — 过滤管线一致性
|
||||
- test('assembleToolPool deduplicates built-in and MCP tools') — 合并去重逻辑
|
||||
416
docs/test-plans/02-utils-pure-functions.md
Normal file
416
docs/test-plans/02-utils-pure-functions.md
Normal file
@@ -0,0 +1,416 @@
|
||||
# 工具函数（纯函数）测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
覆盖 `src/utils/` 下所有可独立单元测试的纯函数。这些函数无外部依赖，输入输出确定性强，是测试金字塔的底层基石。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 状态 | 关键导出 |
|
||||
|------|------|----------|
|
||||
| `src/utils/array.ts` | **已有测试** | intersperse, count, uniq |
|
||||
| `src/utils/set.ts` | **已有测试** | difference, intersects, every, union |
|
||||
| `src/utils/xml.ts` | 待测 | escapeXml, escapeXmlAttr |
|
||||
| `src/utils/hash.ts` | 待测 | djb2Hash, hashContent, hashPair |
|
||||
| `src/utils/stringUtils.ts` | 待测 | escapeRegExp, capitalize, plural, firstLineOf, countCharInString, normalizeFullWidthDigits, normalizeFullWidthSpace, safeJoinLines, truncateToLines, EndTruncatingAccumulator |
|
||||
| `src/utils/semver.ts` | 待测 | gt, gte, lt, lte, satisfies, order |
|
||||
| `src/utils/uuid.ts` | 待测 | validateUuid, createAgentId |
|
||||
| `src/utils/format.ts` | 待测 | formatFileSize, formatSecondsShort, formatDuration, formatNumber, formatTokens, formatRelativeTime, formatRelativeTimeAgo |
|
||||
| `src/utils/json.ts` | 待测 | safeParseJSON, safeParseJSONC, parseJSONL, addItemToJSONCArray |
|
||||
| `src/utils/truncate.ts` | 待测 | truncatePathMiddle, truncateToWidth, truncateStartToWidth, truncateToWidthNoEllipsis, truncate, wrapText |
|
||||
| `src/utils/diff.ts` | 待测 | adjustHunkLineNumbers, getPatchFromContents |
|
||||
| `src/utils/frontmatterParser.ts` | 待测 | parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter, parseBooleanFrontmatter, parseShellFrontmatter |
|
||||
| `src/utils/file.ts` | 待测（纯函数部分） | convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix, pathsEqual, normalizePathForComparison |
|
||||
| `src/utils/glob.ts` | 待测（纯函数部分） | extractGlobBaseDirectory |
|
||||
| `src/utils/tokens.ts` | 待测 | getTokenCountFromUsage |
|
||||
| `src/utils/path.ts` | 待测（纯函数部分） | containsPathTraversal, normalizePathForConfigKey |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/xml.ts — 测试文件: `src/utils/__tests__/xml.test.ts`
|
||||
|
||||
#### describe('escapeXml')
|
||||
|
||||
- test('escapes ampersand') — `&` → `&`
|
||||
- test('escapes less-than') — `<` → `<`
|
||||
- test('escapes greater-than') — `>` → `>`
|
||||
- test('does not escape quotes') — `"` 和 `'` 保持原样
|
||||
- test('handles empty string') — `""` → `""`
|
||||
- test('handles string with no special chars') — `"hello"` 原样返回
|
||||
- test('escapes multiple special chars in one string') — `<a & b>` → `<a & b>`
|
||||
|
||||
#### describe('escapeXmlAttr')
|
||||
|
||||
- test('escapes all xml chars plus quotes') — `"` → `"`, `'` → `'`
|
||||
- test('escapes double quotes') — `he said "hi"` 正确转义
|
||||
- test('escapes single quotes') — `it's` 正确转义
|
||||
|
||||
---
|
||||
|
||||
### src/utils/hash.ts — 测试文件: `src/utils/__tests__/hash.test.ts`
|
||||
|
||||
#### describe('djb2Hash')
|
||||
|
||||
- test('returns consistent hash for same input') — 相同输入返回相同结果
|
||||
- test('returns different hashes for different inputs') — 不同输入大概率不同
|
||||
- test('returns a 32-bit integer') — 结果在 int32 范围内
|
||||
- test('handles empty string') — 空字符串有确定的哈希值
|
||||
- test('handles unicode strings') — 中文/emoji 等正确处理
|
||||
|
||||
#### describe('hashContent')
|
||||
|
||||
- test('returns consistent hash for same content') — 确定性
|
||||
- test('returns string result') — 返回值为字符串
|
||||
|
||||
#### describe('hashPair')
|
||||
|
||||
- test('returns consistent hash for same pair') — 确定性
|
||||
- test('order matters') — hashPair(a, b) ≠ hashPair(b, a)
|
||||
- test('handles empty strings')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/stringUtils.ts — 测试文件: `src/utils/__tests__/stringUtils.test.ts`
|
||||
|
||||
#### describe('escapeRegExp')
|
||||
|
||||
- test('escapes dots') — `.` → `\\.`
|
||||
- test('escapes asterisks') — `*` → `\\*`
|
||||
- test('escapes brackets') — `[` → `\\[`
|
||||
- test('escapes all special chars') — `.*+?^${}()|[]\` 全部转义
|
||||
- test('leaves normal chars unchanged') — `hello` 原样
|
||||
- test('escaped string works in RegExp') — `new RegExp(escapeRegExp('a.b'))` 精确匹配 `a.b`
|
||||
|
||||
#### describe('capitalize')
|
||||
|
||||
- test('uppercases first char') — `"foo"` → `"Foo"`
|
||||
- test('does NOT lowercase rest') — `"fooBar"` → `"FooBar"`（区别于 lodash capitalize）
|
||||
- test('handles single char') — `"a"` → `"A"`
|
||||
- test('handles empty string') — `""` → `""`
|
||||
- test('handles already capitalized') — `"Foo"` → `"Foo"`
|
||||
|
||||
#### describe('plural')
|
||||
|
||||
- test('returns singular for n=1') — `plural(1, 'file')` → `'file'`
|
||||
- test('returns plural for n=0') — `plural(0, 'file')` → `'files'`
|
||||
- test('returns plural for n>1') — `plural(3, 'file')` → `'files'`
|
||||
- test('uses custom plural form') — `plural(2, 'entry', 'entries')` → `'entries'`
|
||||
|
||||
#### describe('firstLineOf')
|
||||
|
||||
- test('returns first line of multi-line string') — `"a\nb\nc"` → `"a"`
|
||||
- test('returns full string when no newline') — `"hello"` → `"hello"`
|
||||
- test('handles empty string') — `""` → `""`
|
||||
- test('handles string starting with newline') — `"\nhello"` → `""`
|
||||
|
||||
#### describe('countCharInString')
|
||||
|
||||
- test('counts occurrences') — `countCharInString("aabac", "a")` → `3`
|
||||
- test('returns 0 when char not found') — `countCharInString("hello", "x")` → `0`
|
||||
- test('handles empty string') — `countCharInString("", "a")` → `0`
|
||||
- test('respects start position') — `countCharInString("aaba", "a", 2)` → `1`
|
||||
|
||||
#### describe('normalizeFullWidthDigits')
|
||||
|
||||
- test('converts full-width digits to half-width') — `"０１２３"` → `"0123"`
|
||||
- test('leaves half-width digits unchanged') — `"0123"` → `"0123"`
|
||||
- test('mixed content') — `"port ８０８０"` → `"port 8080"`
|
||||
|
||||
#### describe('normalizeFullWidthSpace')
|
||||
|
||||
- test('converts ideographic space to regular space') — `"\u3000"` → `" "`
|
||||
- test('converts multiple spaces') — `"a\u3000b\u3000c"` → `"a b c"`
|
||||
|
||||
#### describe('safeJoinLines')
|
||||
|
||||
- test('joins lines with default delimiter') — `["a","b"]` → `"a,b"`
|
||||
- test('truncates when exceeding maxSize') — 超限时截断并添加 `...[truncated]`
|
||||
- test('handles empty array') — `[]` → `""`
|
||||
- test('uses custom delimiter') — delimiter 为 `"\n"` 时按行连接
|
||||
|
||||
#### describe('truncateToLines')
|
||||
|
||||
- test('returns full text when within limit') — 行数不超限时原样返回
|
||||
- test('truncates and adds ellipsis') — 超限时截断并加 `…`
|
||||
- test('handles exact limit') — 刚好等于 maxLines 时不截断
|
||||
- test('handles single line') — 单行文本不截断
|
||||
|
||||
#### describe('EndTruncatingAccumulator')
|
||||
|
||||
- test('accumulates strings normally within limit')
|
||||
- test('truncates when exceeding maxSize')
|
||||
- test('reports truncated status correctly')
|
||||
- test('reports totalBytes including truncated content')
|
||||
- test('toString includes truncation marker')
|
||||
- test('clear resets all state')
|
||||
- test('append with Buffer works') — 接受 Buffer 类型
|
||||
|
||||
---
|
||||
|
||||
### src/utils/semver.ts — 测试文件: `src/utils/__tests__/semver.test.ts`
|
||||
|
||||
#### describe('gt / gte / lt / lte')
|
||||
|
||||
- test('gt: 2.0.0 > 1.0.0') → true
|
||||
- test('gt: 1.0.0 > 1.0.0') → false
|
||||
- test('gte: 1.0.0 >= 1.0.0') → true
|
||||
- test('lt: 1.0.0 < 2.0.0') → true
|
||||
- test('lte: 1.0.0 <= 1.0.0') → true
|
||||
- test('handles pre-release versions') — `1.0.0-beta < 1.0.0`
|
||||
|
||||
#### describe('satisfies')
|
||||
|
||||
- test('version satisfies caret range') — `satisfies('1.2.3', '^1.0.0')` → true
|
||||
- test('version does not satisfy range') — `satisfies('2.0.0', '^1.0.0')` → false
|
||||
- test('exact match') — `satisfies('1.0.0', '1.0.0')` → true
|
||||
|
||||
#### describe('order')
|
||||
|
||||
- test('returns -1 for lesser') — `order('1.0.0', '2.0.0')` → -1
|
||||
- test('returns 0 for equal') — `order('1.0.0', '1.0.0')` → 0
|
||||
- test('returns 1 for greater') — `order('2.0.0', '1.0.0')` → 1
|
||||
|
||||
---
|
||||
|
||||
### src/utils/uuid.ts — 测试文件: `src/utils/__tests__/uuid.test.ts`
|
||||
|
||||
#### describe('validateUuid')
|
||||
|
||||
- test('accepts valid v4 UUID') — `'550e8400-e29b-41d4-a716-446655440000'` → 返回 UUID
|
||||
- test('returns null for invalid format') — `'not-a-uuid'` → null
|
||||
- test('returns null for empty string') — `''` → null
|
||||
- test('returns null for null/undefined input')
|
||||
- test('accepts uppercase UUIDs') — 大写字母有效
|
||||
|
||||
#### describe('createAgentId')
|
||||
|
||||
- test('returns string starting with "a"') — 前缀为 `a`
|
||||
- test('has correct length') — 前缀 + 16 hex 字符
|
||||
- test('generates unique ids') — 连续两次调用结果不同
|
||||
|
||||
---
|
||||
|
||||
### src/utils/format.ts — 测试文件: `src/utils/__tests__/format.test.ts`
|
||||
|
||||
#### describe('formatFileSize')
|
||||
|
||||
- test('formats bytes') — `500` → `"500 bytes"`
|
||||
- test('formats kilobytes') — `1536` → `"1.5KB"`
|
||||
- test('formats megabytes') — `1572864` → `"1.5MB"`
|
||||
- test('formats gigabytes') — `1610612736` → `"1.5GB"`
|
||||
- test('removes trailing .0') — `1024` → `"1KB"` (不是 `"1.0KB"`)
|
||||
|
||||
#### describe('formatSecondsShort')
|
||||
|
||||
- test('formats milliseconds to seconds') — `1234` → `"1.2s"`
|
||||
- test('formats zero') — `0` → `"0.0s"`
|
||||
|
||||
#### describe('formatDuration')
|
||||
|
||||
- test('formats seconds') — `5000` → `"5s"`
|
||||
- test('formats minutes and seconds') — `65000` → `"1m 5s"`
|
||||
- test('formats hours') — `3661000` → `"1h 1m 1s"`
|
||||
- test('formats days') — `90061000` → `"1d 1h 1m"`
|
||||
- test('returns "0s" for zero') — `0` → `"0s"`
|
||||
- test('hideTrailingZeros omits zero components') — `3600000` + `hideTrailingZeros` → `"1h"`
|
||||
- test('mostSignificantOnly returns largest unit') — `3661000` + `mostSignificantOnly` → `"1h"`
|
||||
|
||||
#### describe('formatNumber')
|
||||
|
||||
- test('formats thousands') — `1321` → `"1.3k"`
|
||||
- test('formats small numbers as-is') — `900` → `"900"`
|
||||
- test('lowercase output') — `1500` → `"1.5k"` (不是 `"1.5K"`)
|
||||
|
||||
#### describe('formatTokens')
|
||||
|
||||
- test('strips .0 suffix') — `1000` → `"1k"` (不是 `"1.0k"`)
|
||||
- test('keeps non-zero decimal') — `1500` → `"1.5k"`
|
||||
|
||||
#### describe('formatRelativeTime')
|
||||
|
||||
- test('formats past time') — now - 3600s → `"1h ago"` (narrow style)
|
||||
- test('formats future time') — now + 3600s → `"in 1h"` (narrow style)
|
||||
- test('formats less than 1 second') — now → `"0s ago"`
|
||||
- test('uses custom now parameter for deterministic output')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/json.ts — 测试文件: `src/utils/__tests__/json.test.ts`
|
||||
|
||||
#### describe('safeParseJSON')
|
||||
|
||||
- test('parses valid JSON') — `'{"a":1}'` → `{ a: 1 }`
|
||||
- test('returns null for invalid JSON') — `'not json'` → null
|
||||
- test('returns null for null input') — `null` → null
|
||||
- test('returns null for undefined input') — `undefined` → null
|
||||
- test('returns null for empty string') — `""` → null
|
||||
- test('handles JSON with BOM') — BOM 前缀不影响解析
|
||||
- test('caches results for repeated calls') — 同一输入不重复解析
|
||||
|
||||
#### describe('safeParseJSONC')
|
||||
|
||||
- test('parses JSON with comments') — 含 `//` 注释的 JSON 正确解析
|
||||
- test('parses JSON with trailing commas') — 宽松模式
|
||||
- test('returns null for invalid input')
|
||||
- test('returns null for null input')
|
||||
|
||||
#### describe('parseJSONL')
|
||||
|
||||
- test('parses multiple JSON lines') — `'{"a":1}\n{"b":2}'` → `[{a:1}, {b:2}]`
|
||||
- test('skips malformed lines') — 含错误行时跳过该行
|
||||
- test('handles empty input') — `""` → `[]`
|
||||
- test('handles trailing newline') — 尾部换行不产生空元素
|
||||
- test('accepts Buffer input') — Buffer 类型同样工作
|
||||
- test('handles BOM prefix')
|
||||
|
||||
#### describe('addItemToJSONCArray')
|
||||
|
||||
- test('adds item to existing array') — `[1, 2]` + 3 → `[1, 2, 3]`
|
||||
- test('creates new array for empty content') — `""` + item → `[item]`
|
||||
- test('creates new array for non-array content') — `'"hello"'` + item → `[item]`
|
||||
- test('preserves comments in JSONC') — 注释不被丢弃
|
||||
- test('handles empty array') — `"[]"` + item → `[item]`
|
||||
|
||||
---
|
||||
|
||||
### src/utils/diff.ts — 测试文件: `src/utils/__tests__/diff.test.ts`
|
||||
|
||||
#### describe('adjustHunkLineNumbers')
|
||||
|
||||
- test('shifts line numbers by positive offset') — 所有 hunk 的 oldStart/newStart 增加 offset
|
||||
- test('shifts by negative offset') — 负 offset 减少行号
|
||||
- test('handles empty hunk array') — `[]` → `[]`
|
||||
|
||||
#### describe('getPatchFromContents')
|
||||
|
||||
- test('returns empty array for identical content') — 相同内容无差异
|
||||
- test('detects added lines') — 新内容多出行
|
||||
- test('detects removed lines') — 旧内容缺少行
|
||||
- test('detects modified lines') — 行内容变化
|
||||
- test('handles empty old content') — 从空文件到有内容
|
||||
- test('handles empty new content') — 删除所有内容
|
||||
|
||||
---
|
||||
|
||||
### src/utils/frontmatterParser.ts — 测试文件: `src/utils/__tests__/frontmatterParser.test.ts`
|
||||
|
||||
#### describe('parseFrontmatter')
|
||||
|
||||
- test('extracts YAML frontmatter between --- delimiters') — 正确提取 frontmatter 并返回 body
|
||||
- test('returns empty frontmatter for content without ---') — 无 frontmatter 时 data 为空
|
||||
- test('handles empty content') — `""` 正确处理
|
||||
- test('handles frontmatter-only content') — 只有 frontmatter 无 body
|
||||
- test('falls back to quoting on YAML parse error') — 无效 YAML 不崩溃
|
||||
|
||||
#### describe('splitPathInFrontmatter')
|
||||
|
||||
- test('splits comma-separated paths') — `"a.ts, b.ts"` → `["a.ts", "b.ts"]`
|
||||
- test('expands brace patterns') — `"*.{ts,tsx}"` → `["*.ts", "*.tsx"]`
|
||||
- test('handles string array input') — `["a.ts", "b.ts"]` → `["a.ts", "b.ts"]`
|
||||
- test('respects braces in comma splitting') — 大括号内的逗号不作为分隔符
|
||||
|
||||
#### describe('parsePositiveIntFromFrontmatter')
|
||||
|
||||
- test('returns number for valid positive int') — `5` → `5`
|
||||
- test('returns undefined for negative') — `-1` → undefined
|
||||
- test('returns undefined for non-number') — `"abc"` → undefined
|
||||
- test('returns undefined for float') — `1.5` → undefined
|
||||
|
||||
#### describe('parseBooleanFrontmatter')
|
||||
|
||||
- test('returns true for true') — `true` → true
|
||||
- test('returns true for "true"') — `"true"` → true
|
||||
- test('returns false for false') — `false` → false
|
||||
- test('returns false for other values') — `"yes"`, `1` → false
|
||||
|
||||
#### describe('parseShellFrontmatter')
|
||||
|
||||
- test('returns bash for "bash"') — 正确识别
|
||||
- test('returns powershell for "powershell"')
|
||||
- test('returns undefined for invalid value') — `"zsh"` → undefined
|
||||
|
||||
---
|
||||
|
||||
### src/utils/file.ts（纯函数部分）— 测试文件: `src/utils/__tests__/file.test.ts`
|
||||
|
||||
#### describe('convertLeadingTabsToSpaces')
|
||||
|
||||
- test('converts single tab to 2 spaces') — `"\thello"` → `" hello"`
|
||||
- test('converts multiple leading tabs') — `"\t\thello"` → `" hello"`
|
||||
- test('does not convert tabs within line') — `"a\tb"` 保持原样
|
||||
- test('handles mixed content')
|
||||
|
||||
#### describe('addLineNumbers')
|
||||
|
||||
- test('adds line numbers starting from 1') — 每行添加 `N\t` 前缀
|
||||
- test('respects startLine parameter') — 从指定行号开始
|
||||
- test('handles empty content')
|
||||
|
||||
#### describe('stripLineNumberPrefix')
|
||||
|
||||
- test('strips tab-prefixed line number') — `"1\thello"` → `"hello"`
|
||||
- test('strips padded line number') — `" 1\thello"` → `"hello"`
|
||||
- test('returns line unchanged when no prefix')
|
||||
|
||||
#### describe('pathsEqual')
|
||||
|
||||
- test('returns true for identical paths')
|
||||
- test('handles trailing slashes') — 带/不带尾部斜杠视为相同
|
||||
- test('handles case sensitivity based on platform')
|
||||
|
||||
#### describe('normalizePathForComparison')
|
||||
|
||||
- test('normalizes forward slashes')
|
||||
- test('resolves path for comparison')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/glob.ts（纯函数部分）— 测试文件: `src/utils/__tests__/glob.test.ts`
|
||||
|
||||
#### describe('extractGlobBaseDirectory')
|
||||
|
||||
- test('extracts static prefix from glob') — `"src/**/*.ts"` → `{ baseDir: "src", relativePattern: "**/*.ts" }`
|
||||
- test('handles root-level glob') — `"*.ts"` → `{ baseDir: ".", relativePattern: "*.ts" }`
|
||||
- test('handles deep static path') — `"src/utils/model/*.ts"` → baseDir 为 `"src/utils/model"`
|
||||
- test('handles Windows drive root') — `"C:\\Users\\**\\*.ts"` 正确分割
|
||||
|
||||
---
|
||||
|
||||
### src/utils/tokens.ts（纯函数部分）— 测试文件: `src/utils/__tests__/tokens.test.ts`
|
||||
|
||||
#### describe('getTokenCountFromUsage')
|
||||
|
||||
- test('sums input and output tokens') — `{ input_tokens: 100, output_tokens: 50 }` → 150
|
||||
- test('includes cache tokens') — cache_creation + cache_read 加入总数
|
||||
- test('handles zero values') — 全 0 时返回 0
|
||||
|
||||
---
|
||||
|
||||
### src/utils/path.ts（纯函数部分）— 测试文件: `src/utils/__tests__/path.test.ts`
|
||||
|
||||
#### describe('containsPathTraversal')
|
||||
|
||||
- test('detects ../ traversal') — `"../etc/passwd"` → true
|
||||
- test('detects mid-path traversal') — `"foo/../../bar"` → true
|
||||
- test('returns false for safe paths') — `"src/utils/file.ts"` → false
|
||||
- test('returns false for paths containing .. in names') — `"foo..bar"` → false
|
||||
|
||||
#### describe('normalizePathForConfigKey')
|
||||
|
||||
- test('converts backslashes to forward slashes') — `"src\\utils"` → `"src/utils"`
|
||||
- test('leaves forward slashes unchanged')
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
本计划中的函数大部分为纯函数，**不需要 mock**。少数例外：
|
||||
|
||||
| 函数 | 依赖 | 处理 |
|
||||
|------|------|------|
|
||||
| `hashContent` / `hashPair` | `Bun.hash` | Bun 运行时下自动可用 |
|
||||
| `formatRelativeTime` | `Date` | 使用 `now` 参数注入确定性时间 |
|
||||
| `safeParseJSON` | `logError` | 可通过 `shouldLogError: false` 跳过 |
|
||||
| `safeParseJSONC` | `logError` | mock `logError` 避免测试输出噪音 |
|
||||
134
docs/test-plans/03-context-building.md
Normal file
134
docs/test-plans/03-context-building.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# Context 构建测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Context 构建系统负责组装发送给 Claude API 的系统提示和用户上下文。包括 git 状态获取、CLAUDE.md 文件发现与加载、系统提示拼装三部分。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/context.ts` | `getSystemContext`, `getUserContext`, `getGitStatus`, `setSystemPromptInjection` |
|
||||
| `src/utils/claudemd.ts` | `stripHtmlComments`, `getClaudeMds`, `isMemoryFilePath`, `getLargeMemoryFiles`, `filterInjectedMemoryFiles`, `getExternalClaudeMdIncludes`, `hasExternalClaudeMdIncludes`, `processMemoryFile`, `getMemoryFiles` |
|
||||
| `src/utils/systemPrompt.ts` | `buildEffectiveSystemPrompt` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/claudemd.ts — 纯函数部分
|
||||
|
||||
#### describe('stripHtmlComments')
|
||||
|
||||
- test('strips block-level HTML comments') — `"text <!-- comment --> more"` → content 不含注释
|
||||
- test('preserves inline content') — 行内文本保留
|
||||
- test('preserves code block content') — ` ```html\n<!-- not stripped -->\n``` ` 内的注释不移除
|
||||
- test('returns stripped: false when no comments') — 无注释时 stripped 为 false
|
||||
- test('returns stripped: true when comments exist')
|
||||
- test('handles empty string') — `""` → `{ content: "", stripped: false }`
|
||||
- test('handles multiple comments') — 多个注释全部移除
|
||||
|
||||
#### describe('getClaudeMds')
|
||||
|
||||
- test('assembles memory files with type descriptions') — 不同 type 的文件有不同前缀描述
|
||||
- test('includes instruction prompt prefix') — 输出包含指令前缀
|
||||
- test('handles empty memory files array') — 空数组返回空字符串或最小前缀
|
||||
- test('respects filter parameter') — filter 函数可过滤特定类型
|
||||
- test('concatenates multiple files with separators')
|
||||
|
||||
#### describe('isMemoryFilePath')
|
||||
|
||||
- test('returns true for CLAUDE.md path') — `"/project/CLAUDE.md"` → true
|
||||
- test('returns true for .claude/rules/ path') — `"/project/.claude/rules/foo.md"` → true
|
||||
- test('returns true for memory file path') — `"~/.claude/memory/foo.md"` → true
|
||||
- test('returns false for regular file') — `"/project/src/main.ts"` → false
|
||||
- test('returns false for unrelated .md file') — `"/project/README.md"` → false
|
||||
|
||||
#### describe('getLargeMemoryFiles')
|
||||
|
||||
- test('returns files exceeding 40K chars') — 内容 > MAX_MEMORY_CHARACTER_COUNT 的文件被返回
|
||||
- test('returns empty array when all files are small')
|
||||
- test('correctly identifies threshold boundary')
|
||||
|
||||
#### describe('filterInjectedMemoryFiles')
|
||||
|
||||
- test('filters out AutoMem type files') — feature flag 开启时移除自动记忆
|
||||
- test('filters out TeamMem type files')
|
||||
- test('preserves other types') — 非 AutoMem/TeamMem 的文件保留
|
||||
|
||||
#### describe('getExternalClaudeMdIncludes')
|
||||
|
||||
- test('returns includes from outside CWD') — 外部 @include 路径被识别
|
||||
- test('returns empty array when all includes are internal')
|
||||
|
||||
#### describe('hasExternalClaudeMdIncludes')
|
||||
|
||||
- test('returns true when external includes exist')
|
||||
- test('returns false when no external includes')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/systemPrompt.ts
|
||||
|
||||
#### describe('buildEffectiveSystemPrompt')
|
||||
|
||||
- test('returns default system prompt when no overrides') — 无任何覆盖时使用默认提示
|
||||
- test('overrideSystemPrompt replaces everything') — override 模式替换全部内容
|
||||
- test('customSystemPrompt replaces default') — `--system-prompt` 参数替换默认
|
||||
- test('appendSystemPrompt is appended after main prompt') — append 在主提示之后
|
||||
- test('agent definition replaces default prompt') — agent 模式使用 agent prompt
|
||||
- test('agent definition with append combines both') — agent prompt + append
|
||||
- test('override takes precedence over agent and custom') — 优先级最高
|
||||
- test('returns array of strings') — 返回值为 SystemPrompt 类型（字符串数组）
|
||||
|
||||
---
|
||||
|
||||
### src/context.ts — 需 Mock 的部分
|
||||
|
||||
#### describe('getGitStatus')
|
||||
|
||||
- test('returns formatted git status string') — 包含 branch、status、log、user
|
||||
- test('truncates status at 2000 chars') — 超长 status 被截断
|
||||
- test('returns null in test environment') — `NODE_ENV=test` 时返回 null
|
||||
- test('returns null in non-git directory') — 非 git 仓库返回 null
|
||||
- test('runs git commands in parallel') — 多个 git 命令并行执行
|
||||
|
||||
#### describe('getSystemContext')
|
||||
|
||||
- test('includes gitStatus key') — 返回对象包含 gitStatus
|
||||
- test('returns memoized result on subsequent calls') — 多次调用返回同一结果
|
||||
- test('skips git when instructions disabled')
|
||||
|
||||
#### describe('getUserContext')
|
||||
|
||||
- test('includes currentDate key') — 返回对象包含当前日期
|
||||
- test('includes claudeMd key when CLAUDE.md exists') — 加载 CLAUDE.md 内容
|
||||
- test('respects CLAUDE_CODE_DISABLE_CLAUDE_MDS env') — 设置后不加载 CLAUDE.md
|
||||
- test('returns memoized result')
|
||||
|
||||
#### describe('setSystemPromptInjection')
|
||||
|
||||
- test('clears memoized context caches') — 调用后下次 getSystemContext/getUserContext 重新计算
|
||||
- test('injection value is accessible via getSystemPromptInjection')
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 用途 |
|
||||
|------|-----------|------|
|
||||
| `execFileNoThrow` | `mock.module` | `getGitStatus` 中的 git 命令 |
|
||||
| `getMemoryFiles` | `mock.module` | `getUserContext` 中的 CLAUDE.md 加载 |
|
||||
| `getCwd` | `mock.module` | 路径解析上下文 |
|
||||
| `process.env.NODE_ENV` | 直接设置 | 测试环境检测 |
|
||||
| `process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 直接设置 | 禁用 CLAUDE.md |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
放在 `tests/integration/context-build.test.ts`：
|
||||
|
||||
### describe('Context assembly pipeline')
|
||||
|
||||
- test('getUserContext produces claudeMd containing CLAUDE.md content') — 端到端验证 CLAUDE.md 被正确加载到 context
|
||||
- test('buildEffectiveSystemPrompt + getUserContext produces complete prompt') — 系统提示 + 用户上下文完整性
|
||||
- test('setSystemPromptInjection invalidates and rebuilds context') — 注入后重新构建上下文
|
||||
104
docs/test-plans/04-permission-system.md
Normal file
104
docs/test-plans/04-permission-system.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# 权限系统测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
权限系统控制工具是否可以执行，包含规则解析器、权限检查管线和权限模式判断。测试重点是纯函数解析器和规则匹配逻辑。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/permissions/permissionRuleParser.ts` | `permissionRuleValueFromString`, `permissionRuleValueToString`, `escapeRuleContent`, `unescapeRuleContent`, `normalizeLegacyToolName`, `getLegacyToolNames` |
|
||||
| `src/utils/permissions/PermissionMode.ts` | 权限模式常量和辅助函数 |
|
||||
| `src/utils/permissions/permissions.ts` | `hasPermissionsToUseTool`, `getDenyRuleForTool`, `checkRuleBasedPermissions` |
|
||||
| `src/types/permissions.ts` | `PermissionMode`, `PermissionBehavior`, `PermissionRule` 类型定义 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/permissions/permissionRuleParser.ts
|
||||
|
||||
#### describe('escapeRuleContent')
|
||||
|
||||
- test('escapes backslashes first') — `'test\\value'` → `'test\\\\value'`
|
||||
- test('escapes opening parentheses') — `'print(1)'` → `'print\\(1\\)'`
|
||||
- test('escapes closing parentheses') — `'func()'` → `'func\\(\\)'`
|
||||
- test('handles combined escape') — `'echo "test\\nvalue"'` 中的 `\\` 先转义
|
||||
- test('handles empty string') — `''` → `''`
|
||||
- test('no-op for string without special chars') — `'npm install'` 原样返回
|
||||
|
||||
#### describe('unescapeRuleContent')
|
||||
|
||||
- test('unescapes parentheses') — `'print\\(1\\)'` → `'print(1)'`
|
||||
- test('unescapes backslashes last') — `'test\\\\nvalue'` → `'test\\nvalue'`
|
||||
- test('handles empty string')
|
||||
- test('roundtrip: escape then unescape returns original') — `unescapeRuleContent(escapeRuleContent(x)) === x`
|
||||
|
||||
#### describe('permissionRuleValueFromString')
|
||||
|
||||
- test('parses tool name only') — `'Bash'` → `{ toolName: 'Bash' }`
|
||||
- test('parses tool name with content') — `'Bash(npm install)'` → `{ toolName: 'Bash', ruleContent: 'npm install' }`
|
||||
- test('parses content with escaped parentheses') — `'Bash(python -c "print\\(1\\)")'` → ruleContent 为 `'python -c "print(1)"'`
|
||||
- test('treats empty parens as tool-wide rule') — `'Bash()'` → `{ toolName: 'Bash' }`（无 ruleContent）
|
||||
- test('treats wildcard content as tool-wide rule') — `'Bash(*)'` → `{ toolName: 'Bash' }`
|
||||
- test('normalizes legacy tool names') — `'Task'` → `{ toolName: 'Agent' }`（或对应的 AGENT_TOOL_NAME）
|
||||
- test('handles malformed input: no closing paren') — `'Bash(npm'` → 整个字符串作为 toolName
|
||||
- test('handles malformed input: content after closing paren') — `'Bash(npm)extra'` → 整个字符串作为 toolName
|
||||
- test('handles missing tool name') — `'(foo)'` → 整个字符串作为 toolName
|
||||
|
||||
#### describe('permissionRuleValueToString')
|
||||
|
||||
- test('serializes tool name only') — `{ toolName: 'Bash' }` → `'Bash'`
|
||||
- test('serializes with content') — `{ toolName: 'Bash', ruleContent: 'npm install' }` → `'Bash(npm install)'`
|
||||
- test('escapes content with parentheses') — ruleContent 含 `()` 时正确转义
|
||||
- test('roundtrip: fromString then toString preserves value') — 往返一致
|
||||
|
||||
#### describe('normalizeLegacyToolName')
|
||||
|
||||
- test('maps Task to Agent tool name') — `'Task'` → AGENT_TOOL_NAME
|
||||
- test('maps KillShell to TaskStop tool name') — `'KillShell'` → TASK_STOP_TOOL_NAME
|
||||
- test('maps AgentOutputTool to TaskOutput tool name')
|
||||
- test('returns unknown names unchanged') — `'UnknownTool'` → `'UnknownTool'`
|
||||
|
||||
#### describe('getLegacyToolNames')
|
||||
|
||||
- test('returns legacy names for canonical name') — 给定 AGENT_TOOL_NAME 返回包含 `'Task'`
|
||||
- test('returns empty array for name with no legacy aliases')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/permissions/permissions.ts — 需 Mock
|
||||
|
||||
#### describe('getDenyRuleForTool')
|
||||
|
||||
- test('returns deny rule matching tool name') — 匹配到 blanket deny 规则时返回
|
||||
- test('returns null when no deny rules match') — 无匹配时返回 null
|
||||
- test('matches MCP tools by server prefix') — `mcp__server` 规则匹配该 server 下的 MCP 工具
|
||||
- test('does not match content-specific deny rules') — 有 ruleContent 的 deny 规则不作为 blanket deny
|
||||
|
||||
#### describe('checkRuleBasedPermissions')（集成级别）
|
||||
|
||||
- test('deny rule takes precedence over allow') — 同时有 allow 和 deny 时 deny 优先
|
||||
- test('ask rule prompts user') — 匹配 ask 规则返回 `{ behavior: 'ask' }`
|
||||
- test('allow rule permits execution') — 匹配 allow 规则返回 `{ behavior: 'allow' }`
|
||||
- test('passthrough when no rules match') — 无匹配规则返回 passthrough
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `bun:bundle` (feature) | 已 polyfill | BRIEF_TOOL_NAME 条件加载 |
|
||||
| Tool 常量导入 | 实际值 | AGENT_TOOL_NAME 等从常量文件导入 |
|
||||
| `appState` | mock object | `hasPermissionsToUseTool` 中的状态依赖 |
|
||||
| Tool 对象 | mock object | 模拟 tool 的 name, checkPermissions 等 |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Permission pipeline end-to-end')
|
||||
|
||||
- test('deny rule blocks tool before it runs') — deny 规则在 call 前拦截
|
||||
- test('bypassPermissions mode allows all') — bypass 模式下 ask → allow
|
||||
- test('dontAsk mode converts ask to deny') — dontAsk 模式下 ask → deny
|
||||
113
docs/test-plans/05-model-routing.md
Normal file
113
docs/test-plans/05-model-routing.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# 模型路由测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
模型路由系统负责 API provider 选择、模型别名解析、模型名规范化和运行时模型决策。测试重点是纯函数和环境变量驱动的逻辑。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/model/aliases.ts` | `MODEL_ALIASES`, `MODEL_FAMILY_ALIASES`, `isModelAlias`, `isModelFamilyAlias` |
|
||||
| `src/utils/model/providers.ts` | `APIProvider`, `getAPIProvider`, `isFirstPartyAnthropicBaseUrl` |
|
||||
| `src/utils/model/model.ts` | `firstPartyNameToCanonical`, `getCanonicalName`, `parseUserSpecifiedModel`, `normalizeModelStringForAPI`, `getRuntimeMainLoopModel`, `getDefaultMainLoopModelSetting` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/model/aliases.ts
|
||||
|
||||
#### describe('isModelAlias')
|
||||
|
||||
- test('returns true for "sonnet"') — 有效别名
|
||||
- test('returns true for "opus"')
|
||||
- test('returns true for "haiku"')
|
||||
- test('returns true for "best"')
|
||||
- test('returns true for "sonnet[1m]"')
|
||||
- test('returns true for "opus[1m]"')
|
||||
- test('returns true for "opusplan"')
|
||||
- test('returns false for full model ID') — `'claude-sonnet-4-6-20250514'` → false
|
||||
- test('returns false for unknown string') — `'gpt-4'` → false
|
||||
- test('is case-sensitive') — `'Sonnet'` → false（别名是小写）
|
||||
|
||||
#### describe('isModelFamilyAlias')
|
||||
|
||||
- test('returns true for "sonnet"')
|
||||
- test('returns true for "opus"')
|
||||
- test('returns true for "haiku"')
|
||||
- test('returns false for "best"') — best 不是 family alias
|
||||
- test('returns false for "opusplan"')
|
||||
- test('returns false for "sonnet[1m]"')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/model/providers.ts
|
||||
|
||||
#### describe('getAPIProvider')
|
||||
|
||||
- test('returns "firstParty" by default') — 无相关 env 时返回 firstParty
|
||||
- test('returns "bedrock" when CLAUDE_CODE_USE_BEDROCK is set') — env 为 truthy 值
|
||||
- test('returns "vertex" when CLAUDE_CODE_USE_VERTEX is set')
|
||||
- test('returns "foundry" when CLAUDE_CODE_USE_FOUNDRY is set')
|
||||
- test('bedrock takes precedence over vertex') — 多个 env 同时设置时 bedrock 优先
|
||||
|
||||
#### describe('isFirstPartyAnthropicBaseUrl')
|
||||
|
||||
- test('returns true when ANTHROPIC_BASE_URL is not set') — 默认 API
|
||||
- test('returns true for api.anthropic.com') — `'https://api.anthropic.com'` → true
|
||||
- test('returns false for custom URL') — `'https://my-proxy.com'` → false
|
||||
- test('returns false for invalid URL') — 非法 URL → false
|
||||
- test('returns true for staging URL when USER_TYPE is ant') — `'https://api-staging.anthropic.com'` + ant → true
|
||||
|
||||
---
|
||||
|
||||
### src/utils/model/model.ts
|
||||
|
||||
#### describe('firstPartyNameToCanonical')
|
||||
|
||||
- test('maps opus-4-6 full name to canonical') — `'claude-opus-4-6-20250514'` → `'claude-opus-4-6'`
|
||||
- test('maps sonnet-4-6 full name') — `'claude-sonnet-4-6-20250514'` → `'claude-sonnet-4-6'`
|
||||
- test('maps haiku-4-5') — `'claude-haiku-4-5-20251001'` → `'claude-haiku-4-5'`
|
||||
- test('maps 3P provider format') — `'us.anthropic.claude-opus-4-6-v1:0'` → `'claude-opus-4-6'`
|
||||
- test('maps claude-3-7-sonnet') — `'claude-3-7-sonnet-20250219'` → `'claude-3-7-sonnet'`
|
||||
- test('maps claude-3-5-sonnet') → `'claude-3-5-sonnet'`
|
||||
- test('maps claude-3-5-haiku') → `'claude-3-5-haiku'`
|
||||
- test('maps claude-3-opus') → `'claude-3-opus'`
|
||||
- test('is case insensitive') — `'Claude-Opus-4-6'` → `'claude-opus-4-6'`
|
||||
- test('falls back to input for unknown model') — `'unknown-model'` → `'unknown-model'`
|
||||
- test('differentiates opus-4 vs opus-4-5 vs opus-4-6') — 更具体的版本优先匹配
|
||||
|
||||
#### describe('parseUserSpecifiedModel')
|
||||
|
||||
- test('resolves "sonnet" to default sonnet model')
|
||||
- test('resolves "opus" to default opus model')
|
||||
- test('resolves "haiku" to default haiku model')
|
||||
- test('resolves "best" to best model')
|
||||
- test('resolves "opusplan" to default sonnet model') — opusplan 默认用 sonnet
|
||||
- test('appends [1m] suffix when alias has [1m]') — `'sonnet[1m]'` → 模型名 + `'[1m]'`
|
||||
- test('preserves original case for custom model names') — `'my-Custom-Model'` 保留大小写
|
||||
- test('handles [1m] suffix on non-alias models') — `'custom-model[1m]'` → `'custom-model[1m]'`
|
||||
- test('trims whitespace') — `' sonnet '` → 正确解析
|
||||
|
||||
#### describe('getRuntimeMainLoopModel')
|
||||
|
||||
- test('returns mainLoopModel by default') — 无特殊条件时原样返回
|
||||
- test('returns opus in plan mode when opusplan is set') — opusplan + plan mode → opus
|
||||
- test('returns sonnet in plan mode when haiku is set') — haiku + plan mode → sonnet 升级
|
||||
- test('returns mainLoopModel in non-plan mode') — 非 plan 模式不做替换
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `process.env.CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY` | 直接设置/恢复 | provider 选择 |
|
||||
| `process.env.ANTHROPIC_BASE_URL` | 直接设置/恢复 | URL 检测 |
|
||||
| `process.env.USER_TYPE` | 直接设置/恢复 | staging URL 和 ant 功能 |
|
||||
| `getModelStrings()` | mock.module | 返回固定模型 ID |
|
||||
| `getMainLoopModelOverride` | mock.module | 会话中模型覆盖 |
|
||||
| `getSettings_DEPRECATED` | mock.module | 用户设置中的模型 |
|
||||
| `getUserSpecifiedModelSetting` | mock.module | `getRuntimeMainLoopModel` 依赖 |
|
||||
| `isModelAllowed` | mock.module | allowlist 检查 |
|
||||
165
docs/test-plans/06-message-handling.md
Normal file
165
docs/test-plans/06-message-handling.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 消息处理测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
消息处理系统负责消息的创建、查询、规范化和文本提取。覆盖消息类型定义、消息工厂函数、消息过滤/查询工具和 API 规范化管线。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/types/message.ts` | `MessageType`, `Message`, `AssistantMessage`, `UserMessage`, `SystemMessage` 等类型 |
|
||||
| `src/utils/messages.ts` | 消息创建、查询、规范化、文本提取等函数（~3100 行） |
|
||||
| `src/utils/messages/mappers.ts` | 消息映射工具 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/messages.ts — 消息创建
|
||||
|
||||
#### describe('createAssistantMessage')
|
||||
|
||||
- test('creates message with type "assistant"') — type 字段正确
|
||||
- test('creates message with role "assistant"') — role 正确
|
||||
- test('creates message with empty content array') — 默认 content 为空
|
||||
- test('generates unique uuid') — 每次调用 uuid 不同
|
||||
- test('includes costUsd as 0')
|
||||
|
||||
#### describe('createUserMessage')
|
||||
|
||||
- test('creates message with type "user"') — type 字段正确
|
||||
- test('creates message with provided content') — content 正确传入
|
||||
- test('generates unique uuid')
|
||||
|
||||
#### describe('createSystemMessage')
|
||||
|
||||
- test('creates system message with correct type')
|
||||
- test('includes message content')
|
||||
|
||||
#### describe('createProgressMessage')
|
||||
|
||||
- test('creates progress message with data')
|
||||
- test('has correct type "progress"')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 消息查询
|
||||
|
||||
#### describe('getLastAssistantMessage')
|
||||
|
||||
- test('returns last assistant message from array') — 多条消息中返回最后一条 assistant
|
||||
- test('returns undefined for empty array')
|
||||
- test('returns undefined when no assistant messages exist')
|
||||
|
||||
#### describe('hasToolCallsInLastAssistantTurn')
|
||||
|
||||
- test('returns true when last assistant has tool_use content') — content 含 tool_use block
|
||||
- test('returns false when last assistant has only text')
|
||||
- test('returns false for empty messages')
|
||||
|
||||
#### describe('isSyntheticMessage')
|
||||
|
||||
- test('identifies interrupt message as synthetic') — INTERRUPT_MESSAGE 标记
|
||||
- test('identifies cancel message as synthetic')
|
||||
- test('returns false for normal user messages')
|
||||
|
||||
#### describe('isNotEmptyMessage')
|
||||
|
||||
- test('returns true for message with content')
|
||||
- test('returns false for message with empty content array')
|
||||
- test('returns false for message with empty text content')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 文本提取
|
||||
|
||||
#### describe('getAssistantMessageText')
|
||||
|
||||
- test('extracts text from text blocks') — content 含 `{ type: 'text', text: 'hello' }` 时提取
|
||||
- test('returns empty string for non-text content') — 仅含 tool_use 时返回空
|
||||
- test('concatenates multiple text blocks')
|
||||
|
||||
#### describe('getUserMessageText')
|
||||
|
||||
- test('extracts text from string content') — content 为纯字符串
|
||||
- test('extracts text from content array') — content 为数组时提取 text 块
|
||||
- test('handles empty content')
|
||||
|
||||
#### describe('extractTextContent')
|
||||
|
||||
- test('extracts text items from mixed content') — 过滤出 type: 'text' 的项
|
||||
- test('returns empty array for all non-text content')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 规范化
|
||||
|
||||
#### describe('normalizeMessages')
|
||||
|
||||
- test('converts raw messages to normalized format') — 消息数组规范化
|
||||
- test('handles empty array') — `[]` → `[]`
|
||||
- test('preserves message order')
|
||||
- test('handles mixed message types')
|
||||
|
||||
#### describe('normalizeMessagesForAPI')
|
||||
|
||||
- test('filters out system messages') — 系统消息不发送给 API
|
||||
- test('filters out progress messages')
|
||||
- test('filters out attachment messages')
|
||||
- test('preserves user and assistant messages')
|
||||
- test('reorders tool results to match API expectations')
|
||||
- test('handles empty array')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 合并
|
||||
|
||||
#### describe('mergeUserMessages')
|
||||
|
||||
- test('merges consecutive user messages') — 相邻用户消息合并
|
||||
- test('does not merge non-consecutive user messages')
|
||||
- test('preserves assistant messages between user messages')
|
||||
|
||||
#### describe('mergeAssistantMessages')
|
||||
|
||||
- test('merges consecutive assistant messages')
|
||||
- test('combines content arrays')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 辅助函数
|
||||
|
||||
#### describe('buildMessageLookups')
|
||||
|
||||
- test('builds index by message uuid') — 按 uuid 建立查找表
|
||||
- test('returns empty lookups for empty messages')
|
||||
- test('handles duplicate uuids gracefully')
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `crypto.randomUUID` | `mock` 或 spy | 消息创建中的 uuid 生成 |
|
||||
| Message 对象 | 手动构造 | 创建符合类型的 mock 消息对象 |
|
||||
|
||||
### Mock 消息工厂（放在 `tests/mocks/messages.ts`）
|
||||
|
||||
```typescript
|
||||
// 通用 mock 消息构造器
|
||||
export function mockAssistantMessage(overrides?: Partial<AssistantMessage>): AssistantMessage
|
||||
export function mockUserMessage(content: string, overrides?: Partial<UserMessage>): UserMessage
|
||||
export function mockSystemMessage(overrides?: Partial<SystemMessage>): SystemMessage
|
||||
export function mockToolUseBlock(name: string, input: unknown): ToolUseBlock
|
||||
export function mockToolResultMessage(toolUseId: string, content: string): UserMessage
|
||||
```
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Message pipeline')
|
||||
|
||||
- test('create → normalize → API format produces valid request') — 创建消息 → normalizeMessagesForAPI → 验证输出结构
|
||||
- test('tool use and tool result pairing is preserved through normalization')
|
||||
- test('merge + normalize handles conversation with interruptions')
|
||||
112
docs/test-plans/07-cron.md
Normal file
112
docs/test-plans/07-cron.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Cron 调度测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Cron 模块提供 cron 表达式解析、下次运行时间计算和人类可读描述。全部为纯函数，无外部依赖，是最适合单元测试的模块之一。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/cron.ts` | `CronFields`, `parseCronExpression`, `computeNextCronRun`, `cronToHuman` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### describe('parseCronExpression')
|
||||
|
||||
#### 有效表达式
|
||||
|
||||
- test('parses wildcard fields') — `'* * * * *'` → 每个字段为完整范围
|
||||
- test('parses specific values') — `'30 14 1 6 3'` → minute=[30], hour=[14], dom=[1], month=[6], dow=[3]
|
||||
- test('parses step syntax') — `'*/5 * * * *'` → minute=[0,5,10,...,55]
|
||||
- test('parses range syntax') — `'1-5 * * * *'` → minute=[1,2,3,4,5]
|
||||
- test('parses range with step') — `'1-10/3 * * * *'` → minute=[1,4,7,10]
|
||||
- test('parses comma-separated list') — `'1,15,30 * * * *'` → minute=[1,15,30]
|
||||
- test('parses day-of-week 7 as Sunday alias') — `'0 0 * * 7'` → dow=[0]
|
||||
- test('parses range with day-of-week 7') — `'0 0 * * 5-7'` → dow=[0,5,6]
|
||||
- test('parses complex combined expression') — `'0,30 9-17 * * 1-5'` → 工作日 9-17 每半小时
|
||||
|
||||
#### 无效表达式
|
||||
|
||||
- test('returns null for wrong field count') — `'* * *'` → null
|
||||
- test('returns null for out-of-range values') — `'60 * * * *'` → null（minute max=59）
|
||||
- test('returns null for invalid step') — `'*/0 * * * *'` → null（step=0）
|
||||
- test('returns null for reversed range') — `'10-5 * * * *'` → null（lo>hi）
|
||||
- test('returns null for empty string') — `''` → null
|
||||
- test('returns null for non-numeric tokens') — `'abc * * * *'` → null
|
||||
|
||||
#### 字段范围验证
|
||||
|
||||
- test('minute: 0-59')
|
||||
- test('hour: 0-23')
|
||||
- test('dayOfMonth: 1-31')
|
||||
- test('month: 1-12')
|
||||
- test('dayOfWeek: 0-6 (plus 7 alias)')
|
||||
|
||||
---
|
||||
|
||||
### describe('computeNextCronRun')
|
||||
|
||||
#### 基本匹配
|
||||
|
||||
- test('finds next minute') — from 14:30:45, cron `'31 14 * * *'` → 14:31:00 同天
|
||||
- test('finds next hour') — from 14:30, cron `'0 15 * * *'` → 15:00 同天
|
||||
- test('rolls to next day') — from 14:30, cron `'0 10 * * *'` → 10:00 次日
|
||||
- test('rolls to next month') — from 1月31日, cron `'0 0 1 * *'` → 2月1日
|
||||
- test('is strictly after from date') — from 恰好匹配时应返回下一次而非当前时间
|
||||
|
||||
#### DOM/DOW 语义
|
||||
|
||||
- test('OR semantics when both dom and dow constrained') — dom=15, dow=3 → 匹配 15 号 OR 周三
|
||||
- test('only dom constrained uses dom') — dom=15, dow=* → 只匹配 15 号
|
||||
- test('only dow constrained uses dow') — dom=*, dow=3 → 只匹配周三
|
||||
- test('both wildcarded matches every day') — dom=*, dow=* → 每天
|
||||
|
||||
#### 边界情况
|
||||
|
||||
- test('handles month boundary') — 从 2 月 28 日寻找 2 月 29 日或 3 月 1 日
|
||||
- test('returns null after 366-day search') — 不可能匹配的表达式返回 null（理论上不会发生）
|
||||
- test('handles step across midnight') — `'0 0 * * *'` 从 23:59 → 次日 0:00
|
||||
|
||||
#### 每 N 分钟
|
||||
|
||||
- test('every 5 minutes from arbitrary time') — `'*/5 * * * *'` from 14:32 → 14:35
|
||||
- test('every minute') — `'* * * * *'` from 14:32:45 → 14:33:00
|
||||
|
||||
---
|
||||
|
||||
### describe('cronToHuman')
|
||||
|
||||
#### 常见模式
|
||||
|
||||
- test('every N minutes') — `'*/5 * * * *'` → `'Every 5 minutes'`
|
||||
- test('every minute') — `'*/1 * * * *'` → `'Every minute'`
|
||||
- test('every hour at :00') — `'0 * * * *'` → `'Every hour'`
|
||||
- test('every hour at :30') — `'30 * * * *'` → `'Every hour at :30'`
|
||||
- test('every N hours') — `'0 */2 * * *'` → `'Every 2 hours'`
|
||||
- test('daily at specific time') — `'30 9 * * *'` → `'Every day at 9:30 AM'`
|
||||
- test('specific day of week') — `'0 9 * * 3'` → `'Every Wednesday at 9:00 AM'`
|
||||
- test('weekdays') — `'0 9 * * 1-5'` → `'Weekdays at 9:00 AM'`
|
||||
|
||||
#### Fallback
|
||||
|
||||
- test('returns raw cron for complex patterns') — 非常见模式返回原始 cron 字符串
|
||||
- test('returns raw cron for wrong field count') — `'* * *'` → 原样返回
|
||||
|
||||
#### UTC 模式
|
||||
|
||||
- test('UTC option formats time in local timezone') — `{ utc: true }` 时 UTC 时间转本地显示
|
||||
- test('UTC midnight crossing adjusts day name') — UTC 时间跨天时本地星期名正确
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
**无需 Mock**。所有函数为纯函数，唯一的外部依赖是 `Date` 构造器和 `toLocaleTimeString`，可通过传入确定性的 `from` 参数控制。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `cronToHuman` 的时间格式化依赖系统 locale，测试中建议使用 `'en-US'` locale 或只验证部分输出
|
||||
- `computeNextCronRun` 使用本地时区，DST 相关测试需注意运行环境
|
||||
106
docs/test-plans/08-git-utils.md
Normal file
106
docs/test-plans/08-git-utils.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Git 工具测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Git 工具模块提供 git 远程 URL 规范化、仓库根目录查找、裸仓库安全检测等功能。测试重点是纯函数的 URL 规范化和需要文件系统 mock 的仓库发现逻辑。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/git.ts` | `normalizeGitRemoteUrl`, `findGitRoot`, `findCanonicalGitRoot`, `getIsGit`, `isAtGitRoot`, `getRepoRemoteHash`, `isCurrentDirectoryBareGitRepo`, `gitExe`, `getGitState`, `stashToCleanState`, `preserveGitStateForIssue` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### describe('normalizeGitRemoteUrl')（纯函数）
|
||||
|
||||
#### SSH 格式
|
||||
|
||||
- test('normalizes SSH URL') — `'git@github.com:owner/repo.git'` → `'github.com/owner/repo'`
|
||||
- test('normalizes SSH URL without .git suffix') — `'git@github.com:owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('handles GitLab SSH') — `'git@gitlab.com:group/subgroup/repo.git'` → `'gitlab.com/group/subgroup/repo'`
|
||||
|
||||
#### HTTPS 格式
|
||||
|
||||
- test('normalizes HTTPS URL') — `'https://github.com/owner/repo.git'` → `'github.com/owner/repo'`
|
||||
- test('normalizes HTTPS URL without .git suffix') — `'https://github.com/owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('normalizes HTTP URL') — `'http://github.com/owner/repo.git'` → `'github.com/owner/repo'`
|
||||
|
||||
#### SSH:// 协议格式
|
||||
|
||||
- test('normalizes ssh:// URL') — `'ssh://git@github.com/owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('handles user prefix in ssh://') — `'ssh://user@host/path'` → `'host/path'`
|
||||
|
||||
#### 代理 URL（CCR git proxy）
|
||||
|
||||
- test('normalizes legacy proxy URL') — `'http://local_proxy@127.0.0.1:16583/git/owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('normalizes GHE proxy URL') — `'http://user@127.0.0.1:8080/git/ghe.company.com/owner/repo'` → `'ghe.company.com/owner/repo'`
|
||||
|
||||
#### 边界情况
|
||||
|
||||
- test('returns null for empty string') — `''` → null
|
||||
- test('returns null for whitespace') — `' '` → null
|
||||
- test('returns null for unrecognized format') — `'not-a-url'` → null
|
||||
- test('output is lowercase') — `'git@GitHub.com:Owner/Repo.git'` → `'github.com/owner/repo'`
|
||||
- test('SSH and HTTPS for same repo produce same result') — 相同仓库不同协议 → 相同输出
|
||||
|
||||
---
|
||||
|
||||
### describe('findGitRoot')（需文件系统 Mock）
|
||||
|
||||
- test('finds git root from nested directory') — `/project/src/utils/` → `/project/`（假设 `/project/.git` 存在）
|
||||
- test('finds git root from root directory') — `/project/` → `/project/`
|
||||
- test('returns null for non-git directory') — 无 `.git` → null
|
||||
- test('handles worktree .git file') — `.git` 为文件时也识别
|
||||
- test('memoizes results') — 同一路径不重复查找
|
||||
|
||||
### describe('findCanonicalGitRoot')
|
||||
|
||||
- test('returns same as findGitRoot for regular repo')
|
||||
- test('resolves worktree to main repo root') — worktree 路径 → 主仓库根目录
|
||||
- test('returns null for non-git directory')
|
||||
|
||||
### describe('gitExe')
|
||||
|
||||
- test('returns git path string') — 返回字符串
|
||||
- test('memoizes the result') — 多次调用返回同一值
|
||||
|
||||
---
|
||||
|
||||
### describe('getRepoRemoteHash')（需 Mock）
|
||||
|
||||
- test('returns 16-char hex hash') — 返回值为 16 位十六进制字符串
|
||||
- test('returns null when no remote') — 无 remote URL 时返回 null
|
||||
- test('same repo SSH/HTTPS produce same hash') — 不同协议同一仓库 hash 相同
|
||||
|
||||
---
|
||||
|
||||
### describe('isCurrentDirectoryBareGitRepo')（需文件系统 Mock）
|
||||
|
||||
- test('detects bare git repo attack vector') — 目录含 HEAD + objects/ + refs/ 但无有效 .git/HEAD → true
|
||||
- test('returns false for normal directory') — 普通目录 → false
|
||||
- test('returns false for regular git repo') — 有效 .git 目录 → false
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `statSync` | mock module | `findGitRoot` 中的 .git 检测 |
|
||||
| `readFileSync` | mock module | worktree .git 文件读取 |
|
||||
| `realpathSync` | mock module | 路径解析 |
|
||||
| `execFileNoThrow` | mock module | git 命令执行 |
|
||||
| `whichSync` | mock module | `gitExe` 中的 git 路径查找 |
|
||||
| `getCwd` | mock module | 当前工作目录 |
|
||||
| `getRemoteUrl` | mock module | `getRepoRemoteHash` 依赖 |
|
||||
| 临时目录 | `mkdtemp` | 集成测试中创建临时 git 仓库 |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Git repo discovery')（放在 tests/integration/）
|
||||
|
||||
- test('findGitRoot works in actual git repo') — 在临时 git init 的目录中验证
|
||||
- test('normalizeGitRemoteUrl + getRepoRemoteHash produces stable hash') — URL → hash 端到端验证
|
||||
161
docs/test-plans/09-config-settings.md
Normal file
161
docs/test-plans/09-config-settings.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 配置系统测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
配置系统包含全局配置（GlobalConfig）、项目配置（ProjectConfig）和设置（Settings）三层。测试重点是纯函数校验逻辑、Zod schema 验证和配置合并策略。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/config.ts` | `getGlobalConfig`, `saveGlobalConfig`, `getCurrentProjectConfig`, `checkHasTrustDialogAccepted`, `isPathTrusted`, `getOrCreateUserID`, `isAutoUpdaterDisabled` |
|
||||
| `src/utils/settings/settings.ts` | `getSettingsForSource`, `parseSettingsFile`, `getSettingsFilePathForSource`, `getInitialSettings` |
|
||||
| `src/utils/settings/types.ts` | `SettingsSchema`（Zod schema） |
|
||||
| `src/utils/settings/validation.ts` | 设置验证函数 |
|
||||
| `src/utils/settings/constants.ts` | 设置常量 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/config.ts — 纯函数/常量
|
||||
|
||||
#### describe('DEFAULT_GLOBAL_CONFIG')
|
||||
|
||||
- test('has all required fields') — 默认配置对象包含所有必需字段
|
||||
- test('has null auth fields by default') — oauthAccount 等为 null
|
||||
|
||||
#### describe('DEFAULT_PROJECT_CONFIG')
|
||||
|
||||
- test('has empty allowedTools') — 默认为空数组
|
||||
- test('has empty mcpServers') — 默认为空对象
|
||||
|
||||
#### describe('isAutoUpdaterDisabled')
|
||||
|
||||
- test('returns true when CLAUDE_CODE_DISABLE_AUTOUPDATER is set') — env 设置时禁用
|
||||
- test('returns true when disableAutoUpdater config is true')
|
||||
- test('returns false by default')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/config.ts — 需 Mock
|
||||
|
||||
#### describe('getGlobalConfig')
|
||||
|
||||
- test('returns cached config on subsequent calls') — 缓存机制
|
||||
- test('returns TEST_GLOBAL_CONFIG_FOR_TESTING in test mode')
|
||||
- test('reads config from ~/.claude.json')
|
||||
- test('returns default config when file does not exist')
|
||||
|
||||
#### describe('saveGlobalConfig')
|
||||
|
||||
- test('applies updater function to current config') — updater 修改被保存
|
||||
- test('creates backup before writing') — 写入前备份
|
||||
- test('prevents auth state loss') — `wouldLoseAuthState` 检查
|
||||
|
||||
#### describe('getCurrentProjectConfig')
|
||||
|
||||
- test('returns project config for current directory')
|
||||
- test('returns default config when no project config exists')
|
||||
|
||||
#### describe('checkHasTrustDialogAccepted')
|
||||
|
||||
- test('returns true when trust is accepted in current directory')
|
||||
- test('returns true when parent directory is trusted') — 父目录信任传递
|
||||
- test('returns false when no trust accepted')
|
||||
- test('caches positive results')
|
||||
|
||||
#### describe('isPathTrusted')
|
||||
|
||||
- test('returns true for trusted path')
|
||||
- test('returns false for untrusted path')
|
||||
|
||||
#### describe('getOrCreateUserID')
|
||||
|
||||
- test('returns existing user ID from config')
|
||||
- test('creates and persists new ID when none exists')
|
||||
- test('returns consistent ID across calls')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/settings/settings.ts
|
||||
|
||||
#### describe('getSettingsFilePathForSource')
|
||||
|
||||
- test('returns ~/.claude/settings.json for userSettings') — 全局用户设置路径
|
||||
- test('returns .claude/settings.json for projectSettings') — 项目设置路径
|
||||
- test('returns .claude/settings.local.json for localSettings') — 本地设置路径
|
||||
|
||||
#### describe('parseSettingsFile')（需 Mock 文件读取）
|
||||
|
||||
- test('parses valid settings JSON') — 有效 JSON → `{ settings, errors: [] }`
|
||||
- test('returns errors for invalid fields') — 无效字段 → errors 非空
|
||||
- test('returns empty settings for non-existent file')
|
||||
- test('handles JSON with comments') — JSONC 格式支持
|
||||
|
||||
#### describe('getInitialSettings')
|
||||
|
||||
- test('merges settings from all sources') — user + project + local 合并
|
||||
- test('later sources override earlier ones') — 优先级：policy > user > project > local
|
||||
|
||||
---
|
||||
|
||||
### src/utils/settings/types.ts — Zod Schema 验证
|
||||
|
||||
#### describe('SettingsSchema validation')
|
||||
|
||||
- test('accepts valid minimal settings') — `{}` → 有效
|
||||
- test('accepts permissions block') — `{ permissions: { allow: ['Bash(*)'] } }` → 有效
|
||||
- test('accepts model setting') — `{ model: 'sonnet' }` → 有效
|
||||
- test('accepts hooks configuration') — 有效的 hooks 对象被接受
|
||||
- test('accepts env variables') — `{ env: { FOO: 'bar' } }` → 有效
|
||||
- test('rejects unknown top-level keys') — 未知字段被拒绝或忽略（取决于 schema 配置）
|
||||
- test('rejects invalid permission mode') — `{ permissions: { defaultMode: 'invalid' } }` → 错误
|
||||
- test('rejects non-string model') — `{ model: 123 }` → 错误
|
||||
- test('accepts mcpServers configuration') — MCP server 配置有效
|
||||
- test('accepts sandbox configuration')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/settings/validation.ts
|
||||
|
||||
#### describe('settings validation')
|
||||
|
||||
- test('validates permission rules format') — `'Bash(npm install)'` 格式正确
|
||||
- test('rejects malformed permission rules')
|
||||
- test('validates hook configuration structure')
|
||||
- test('provides helpful error messages') — 错误信息包含字段路径
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| 文件系统 | 临时目录 + mock | config 文件读写 |
|
||||
| `lockfile` | mock module | 文件锁 |
|
||||
| `getCwd` | mock module | 项目路径判断 |
|
||||
| `findGitRoot` | mock module | 项目根目录 |
|
||||
| `process.env` | 直接设置/恢复 | `CLAUDE_CODE_DISABLE_AUTOUPDATER` 等 |
|
||||
|
||||
### 测试用临时文件结构
|
||||
|
||||
```
|
||||
/tmp/claude-test-xxx/
|
||||
├── .claude/
|
||||
│ ├── settings.json # projectSettings
|
||||
│ └── settings.local.json # localSettings
|
||||
├── home/
|
||||
│ └── .claude/
|
||||
│ └── settings.json # userSettings（mock HOME）
|
||||
└── project/
|
||||
└── .git/
|
||||
```
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Config + Settings merge pipeline')
|
||||
|
||||
- test('user settings + project settings merge correctly') — 验证合并优先级
|
||||
- test('deny rules from settings are reflected in tool permission context')
|
||||
- test('trust dialog state persists across config reads')
|
||||
361
docs/test-plans/10-fix-weak-tests.md
Normal file
361
docs/test-plans/10-fix-weak-tests.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# Plan 10 — 修复 WEAK 评分测试文件
|
||||
|
||||
> 优先级：高 | 8 个文件 | 预估新增/修改 ~60 个测试用例
|
||||
|
||||
本计划修复 testing-spec.md 中评定为 WEAK 的 8 个测试文件的断言缺陷和覆盖缺口。
|
||||
|
||||
---
|
||||
|
||||
## 10.1 `src/utils/__tests__/format.test.ts`
|
||||
|
||||
**问题**：`formatNumber`、`formatTokens`、`formatRelativeTime` 使用 `toContain` 代替精确匹配，无法检测格式回归。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### formatNumber — toContain → toBe
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(formatNumber(1321)).toContain("k");
|
||||
expect(formatNumber(1500000)).toContain("m");
|
||||
|
||||
// 修复为
|
||||
expect(formatNumber(1321)).toBe("1.3k");
|
||||
expect(formatNumber(1500000)).toBe("1.5m");
|
||||
```
|
||||
|
||||
> 注意：`Intl.NumberFormat` 输出可能因 locale 不同。若 CI locale 不一致，改用 `toMatch(/^\d+(\.\d)?[km]$/)` 正则匹配。
|
||||
|
||||
#### formatTokens — 补精确断言
|
||||
|
||||
```typescript
|
||||
expect(formatTokens(1000)).toBe("1k");
|
||||
expect(formatTokens(1500)).toBe("1.5k");
|
||||
```
|
||||
|
||||
#### formatRelativeTime — toContain → toBe
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(formatRelativeTime(diff, now)).toContain("30");
|
||||
expect(formatRelativeTime(diff, now)).toContain("ago");
|
||||
|
||||
// 修复为
|
||||
expect(formatRelativeTime(diff, now)).toBe("30s ago");
|
||||
```
|
||||
|
||||
#### 新增：formatDuration 进位边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 59.5s 进位 | 59500ms | 至少含 `1m` |
|
||||
| 59m59s 进位 | 3599000ms | 至少含 `1h` |
|
||||
| sub-millisecond | 0.5ms | `"<1ms"` 或 `"0ms"` |
|
||||
|
||||
#### 新增：未测试函数
|
||||
|
||||
| 函数 | 最少用例 |
|
||||
|------|---------|
|
||||
| `formatRelativeTimeAgo` | 2（过去 / 未来） |
|
||||
| `formatLogMetadata` | 1（基本调用不抛错） |
|
||||
| `formatResetTime` | 2（有值 / null） |
|
||||
| `formatResetText` | 1（基本调用） |
|
||||
|
||||
---
|
||||
|
||||
## 10.2 `src/tools/shared/__tests__/gitOperationTracking.test.ts`
|
||||
|
||||
**问题**：`detectGitOperation` 内部调用 `getCommitCounter()`、`getPrCounter()`、`logEvent()`，测试产生分析副作用。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 添加 analytics mock
|
||||
|
||||
在文件顶部添加 `mock.module`：
|
||||
|
||||
```typescript
|
||||
import { mock, afterAll, afterEach, beforeEach } from "bun:test";
|
||||
|
||||
mock.module("src/services/analytics/index.ts", () => ({
|
||||
logEvent: mock(() => {}),
|
||||
}));
|
||||
|
||||
mock.module("src/bootstrap/state.ts", () => ({
|
||||
getCommitCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
getPrCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
}));
|
||||
```
|
||||
|
||||
> 需验证 `detectGitOperation` 的实际导入路径，按需调整 mock 目标。
|
||||
|
||||
#### 新增：缺失的 GH PR actions
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| gh pr edit | `'gh pr edit 123 --title "fix"'` | `result.pr.number === 123` |
|
||||
| gh pr close | `'gh pr close 456'` | `result.pr.number === 456` |
|
||||
| gh pr ready | `'gh pr ready 789'` | `result.pr.number === 789` |
|
||||
| gh pr comment | `'gh pr comment 123 --body "done"'` | `result.pr.number === 123` |
|
||||
|
||||
#### 新增：parseGitCommitId 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 完整 40 字符 SHA | `'[abcdef0123456789abcdef0123456789abcdef01] ...'` | 返回完整 40 字符 |
|
||||
| 畸形括号输出 | `'create mode 100644 file.txt'` | 返回 `null` |
|
||||
|
||||
---
|
||||
|
||||
## 10.3 `src/utils/permissions/__tests__/PermissionMode.test.ts`
|
||||
|
||||
**问题**：`isExternalPermissionMode` 在非 ant 环境永远返回 true，false 路径从未执行；mode 覆盖不完整。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 补全 mode 覆盖
|
||||
|
||||
| 函数 | 缺失的 mode |
|
||||
|------|-------------|
|
||||
| `permissionModeTitle` | `bypassPermissions`, `dontAsk` |
|
||||
| `permissionModeShortTitle` | `dontAsk`, `acceptEdits` |
|
||||
| `getModeColor` | `dontAsk`, `acceptEdits`, `plan` |
|
||||
| `permissionModeFromString` | `acceptEdits`, `bypassPermissions` |
|
||||
| `toExternalPermissionMode` | `acceptEdits`, `bypassPermissions` |
|
||||
|
||||
#### 修复 isExternalPermissionMode
|
||||
|
||||
```typescript
|
||||
// 当前：只测了非 ant 环境（永远 true）
|
||||
// 需要新增 ant 环境测试
|
||||
describe("when USER_TYPE is 'ant'", () => {
|
||||
beforeEach(() => {
|
||||
process.env.USER_TYPE = "ant";
|
||||
});
|
||||
afterEach(() => {
|
||||
delete process.env.USER_TYPE;
|
||||
});
|
||||
|
||||
test("returns false for 'auto' in ant context", () => {
|
||||
expect(isExternalPermissionMode("auto")).toBe(false);
|
||||
});
|
||||
|
||||
test("returns false for 'bubble' in ant context", () => {
|
||||
expect(isExternalPermissionMode("bubble")).toBe(false);
|
||||
});
|
||||
|
||||
test("returns true for non-ant modes in ant context", () => {
|
||||
expect(isExternalPermissionMode("plan")).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：permissionModeSchema
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 有效 mode | `'plan'` | `success: true` |
|
||||
| 无效 mode | `'invalid'` | `success: false` |
|
||||
|
||||
---
|
||||
|
||||
## 10.4 `src/utils/permissions/__tests__/dangerousPatterns.test.ts`
|
||||
|
||||
**问题**：纯数据 smoke test，无行为验证。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 新增：重复值检查
|
||||
|
||||
```typescript
|
||||
test("CROSS_PLATFORM_CODE_EXEC has no duplicates", () => {
|
||||
const set = new Set(CROSS_PLATFORM_CODE_EXEC);
|
||||
expect(set.size).toBe(CROSS_PLATFORM_CODE_EXEC.length);
|
||||
});
|
||||
|
||||
test("DANGEROUS_BASH_PATTERNS has no duplicates", () => {
|
||||
const set = new Set(DANGEROUS_BASH_PATTERNS);
|
||||
expect(set.size).toBe(DANGEROUS_BASH_PATTERNS.length);
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：全量成员断言（用 Set 确保精确）
|
||||
|
||||
```typescript
|
||||
test("CROSS_PLATFORM_CODE_EXEC contains expected interpreters", () => {
|
||||
const expected = ["node", "python", "python3", "ruby", "perl", "php",
|
||||
"bun", "deno", "npx", "tsx"];
|
||||
const set = new Set(CROSS_PLATFORM_CODE_EXEC);
|
||||
for (const entry of expected) {
|
||||
expect(set.has(entry)).toBe(true);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：空字符串不匹配
|
||||
|
||||
```typescript
|
||||
test("empty string does not match any pattern", () => {
|
||||
for (const pattern of DANGEROUS_BASH_PATTERNS) {
|
||||
expect("".startsWith(pattern)).toBe(false);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10.5 `src/utils/__tests__/zodToJsonSchema.test.ts`
|
||||
|
||||
**问题**：object 属性仅 `toBeDefined` 未验证类型结构；optional 字段未验证 absence。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 修复 object schema 测试
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(schema.properties!.name).toBeDefined();
|
||||
expect(schema.properties!.age).toBeDefined();
|
||||
|
||||
// 修复为
|
||||
expect(schema.properties!.name).toEqual({ type: "string" });
|
||||
expect(schema.properties!.age).toEqual({ type: "number" });
|
||||
```
|
||||
|
||||
#### 修复 optional 字段测试
|
||||
|
||||
```typescript
|
||||
test("optional field is not in required array", () => {
|
||||
const schema = zodToJsonSchema(z.object({
|
||||
required: z.string(),
|
||||
optional: z.string().optional(),
|
||||
}));
|
||||
expect(schema.required).toEqual(["required"]);
|
||||
expect(schema.required).not.toContain("optional");
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：缺失的 schema 类型
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| `z.literal("foo")` | `z.literal("foo")` | `{ const: "foo" }` |
|
||||
| `z.null()` | `z.null()` | `{ type: "null" }` |
|
||||
| `z.union()` | `z.union([z.string(), z.number()])` | `{ anyOf: [...] }` |
|
||||
| `z.record()` | `z.record(z.string(), z.number())` | `{ type: "object", additionalProperties: { type: "number" } }` |
|
||||
| `z.tuple()` | `z.tuple([z.string(), z.number()])` | `{ type: "array", items: [...], additionalItems: false }` |
|
||||
| 嵌套 object | `z.object({ a: z.object({ b: z.string() }) })` | 验证嵌套属性结构 |
|
||||
|
||||
---
|
||||
|
||||
## 10.6 `src/utils/__tests__/envValidation.test.ts`
|
||||
|
||||
**问题**：`validateBoundedIntEnvVar` lower bound=100 时 value=1 返回 `status: "valid"`，疑似源码 bug。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 验证 lower bound 行为
|
||||
|
||||
```typescript
|
||||
// 当前测试
|
||||
test("value of 1 with lower bound 100", () => {
|
||||
const result = validateBoundedIntEnvVar("1", { defaultValue: 100, upperLimit: 1000, lowerLimit: 100 });
|
||||
// 如果源码有 bug，这里应该暴露
|
||||
expect(result.effective).toBeGreaterThanOrEqual(100);
|
||||
expect(result.status).toBe(result.effective !== 100 ? "capped" : "valid");
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增边界用例
|
||||
|
||||
| 用例 | value | lowerLimit | 期望 |
|
||||
|------|-------|------------|------|
|
||||
| 低于 lower bound | `"50"` | 100 | `effective: 100, status: "capped"` |
|
||||
| 等于 lower bound | `"100"` | 100 | `effective: 100, status: "valid"` |
|
||||
| 浮点截断 | `"50.7"` | 100 | `effective: 100`（parseInt 截断后 cap） |
|
||||
| 空白字符 | `" 500 "` | 1 | `effective: 500, status: "valid"` |
|
||||
| defaultValue 为 0 | `"0"` | 0 | 需确认 `parsed <= 0` 逻辑 |
|
||||
|
||||
> **行动**：先确认 `validateBoundedIntEnvVar` 源码中 lower bound 的实际执行路径。如果确实不生效，需先修源码再补测试。
|
||||
|
||||
---
|
||||
|
||||
## 10.7 `src/utils/__tests__/file.test.ts`
|
||||
|
||||
**问题**：`addLineNumbers` 仅 `toContain`，未验证完整格式。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 修复 addLineNumbers 断言
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(result).toContain("1");
|
||||
expect(result).toContain("hello");
|
||||
|
||||
// 修复为（需确定 isCompactLinePrefixEnabled 行为）
|
||||
// 假设 compact=false，格式为 " 1→hello"
|
||||
test("formats single line with tab prefix", () => {
|
||||
// 先确认环境，如果 compact 模式不确定，用正则
|
||||
expect(result).toMatch(/^\s*\d+[→\t]hello$/m);
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：stripLineNumberPrefix 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 纯数字行 | `"123"` | `""` |
|
||||
| 无内容前缀 | `"→"` | `""` |
|
||||
| compact 格式 `"1\thello"` | `"1\thello"` | `"hello"` |
|
||||
|
||||
#### 新增：pathsEqual 边界
|
||||
|
||||
| 用例 | a | b | 期望 |
|
||||
|------|---|---|------|
|
||||
| 尾部斜杠差异 | `"/a/b"` | `"/a/b/"` | `false` |
|
||||
| `..` 段 | `"/a/../b"` | `"/b"` | 视实现而定 |
|
||||
|
||||
---
|
||||
|
||||
## 10.8 `src/utils/__tests__/notebook.test.ts`
|
||||
|
||||
**问题**：`mapNotebookCellsToToolResult` 内容检查用 `toContain`，未验证 XML 格式。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 修复 content 断言
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(result).toContain("cell-0");
|
||||
expect(result).toContain("print('hello')");
|
||||
|
||||
// 修复为
|
||||
expect(result).toContain('<cell id="cell-0">');
|
||||
expect(result).toContain("</cell>");
|
||||
```
|
||||
|
||||
#### 新增：parseCellId 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 负数 | `"cell--1"` | `null` |
|
||||
| 前导零 | `"cell-007"` | `7` |
|
||||
| 极大数 | `"cell-999999999"` | `999999999` |
|
||||
|
||||
#### 新增：mapNotebookCellsToToolResult 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 空 data 数组 | `{ cells: [] }` | 空字符串或空结果 |
|
||||
| 无 cell_id | `{ cell_type: "code", source: "x" }` | fallback 到 `cell-${index}` |
|
||||
| error output | `{ output_type: "error", ename: "Error", evalue: "msg" }` | 包含 error 信息 |
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `bun test` 全部通过
|
||||
- [ ] 8 个文件评分从 WEAK 提升至 ACCEPTABLE 或 GOOD
|
||||
- [ ] `toContain` 仅用于警告文本等确实不确定精确值的场景
|
||||
- [ ] envValidation bug 确认并修复（或确认非 bug 并更新测试）
|
||||
177
docs/test-plans/11-strengthen-acceptable-tests.md
Normal file
177
docs/test-plans/11-strengthen-acceptable-tests.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# Plan 11 — 加强 ACCEPTABLE 评分测试
|
||||
|
||||
> 优先级：中 | ~15 个文件 | 预估新增 ~80 个测试用例
|
||||
|
||||
本计划对 ACCEPTABLE 评分文件中的具体缺陷进行定向加强。每个条目只列出需要改动的部分，不做全量重写。
|
||||
|
||||
---
|
||||
|
||||
## 11.1 `src/utils/__tests__/diff.test.ts`
|
||||
|
||||
| 改动 | 当前 | 改为 |
|
||||
|------|------|------|
|
||||
| `getPatchFromContents` 断言 | `hunks.length > 0` | 验证具体 `+`/`-` 行内容 |
|
||||
| `$` 字符转义 | 未测试 | 新增含 `$` 的内容测试 |
|
||||
| `ignoreWhitespace` 选项 | 未测试 | 新增 `ignoreWhitespace: true` 用例 |
|
||||
| 删除全部内容 | 未测试 | `newContent: ""` |
|
||||
| 多 hunk 偏移 | `adjustHunkLineNumbers` 仅单 hunk | 新增多 hunk 同数组测试 |
|
||||
|
||||
---
|
||||
|
||||
## 11.2 `src/utils/__tests__/path.test.ts`
|
||||
|
||||
当前仅覆盖 2/5+ 导出函数。新增：
|
||||
|
||||
| 函数 | 最少用例 | 关键边界 |
|
||||
|------|---------|---------|
|
||||
| `expandPath` | 6 | `~/` 展开、绝对路径直通、相对路径、空串、含 null 字节、`~user` 格式 |
|
||||
| `toRelativePath` | 3 | 同级文件、子目录、父目录 |
|
||||
| `sanitizePath` | 3 | 正常路径、含 `..` 段、空串 |
|
||||
|
||||
`containsPathTraversal` 补充：
|
||||
- URL 编码 `%2e%2e%2f`（确认不匹配，记录为非需求）
|
||||
- 混合分隔符 `foo/..\bar`
|
||||
|
||||
`normalizePathForConfigKey` 补充：
|
||||
- 混合分隔符 `foo/bar\baz`
|
||||
- 冗余分隔符 `foo//bar`
|
||||
- Windows 盘符 `C:\foo\bar`
|
||||
|
||||
---
|
||||
|
||||
## 11.3 `src/utils/__tests__/uuid.test.ts`
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 大写测试断言强化 | `not.toBeNull()` → 验证标准化输出（小写+连字符格式） |
|
||||
| 新增 `createAgentId` | 3 用例：无 label / 有 label / 输出格式正则 `/^a[a-z]*-[a-f0-9]{16}$/` |
|
||||
| 前后空白 | `" 550e8400-... "` 期望 `null` |
|
||||
|
||||
---
|
||||
|
||||
## 11.4 `src/utils/__tests__/semver.test.ts`
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| pre-release 比较 | `gt("1.0.0", "1.0.0-alpha")` | `true` |
|
||||
| pre-release 间比较 | `order("1.0.0-alpha", "1.0.0-beta")` | `-1` |
|
||||
| tilde range | `satisfies("1.2.5", "~1.2.3")` | `true` |
|
||||
| `*` 通配符 | `satisfies("2.0.0", "*")` | `true` |
|
||||
| 畸形版本 | `order("abc", "1.0.0")` | 确认不抛错 |
|
||||
| `0.0.0` | `gt("0.0.0", "0.0.0")` | `false` |
|
||||
|
||||
---
|
||||
|
||||
## 11.5 `src/utils/__tests__/hash.test.ts`
|
||||
|
||||
| 改动 | 当前 | 改为 |
|
||||
|------|------|------|
|
||||
| djb2 32 位检查 | `hash \| 0`（恒 true） | `Number.isSafeInteger(hash) && Math.abs(hash) <= 0x7FFFFFFF` |
|
||||
| hashContent 空串 | 未测试 | 新增 |
|
||||
| hashContent 格式 | 未验证输出为数字串 | `toMatch(/^\d+$/)` |
|
||||
| hashPair 空串 | 未测试 | `hashPair("", "b")`, `hashPair("", "")` |
|
||||
| 已知答案 | 无 | 断言 `djb2Hash("hello")` 为特定值（需先在控制台运行一次确定） |
|
||||
|
||||
---
|
||||
|
||||
## 11.6 `src/utils/__tests__/claudemd.test.ts`
|
||||
|
||||
当前仅覆盖 3 个辅助函数。新增：
|
||||
|
||||
| 用例 | 函数 | 说明 |
|
||||
|------|------|------|
|
||||
| 未闭合注释 | `stripHtmlComments` | `"<!-- no close some text"` → 原样返回 |
|
||||
| 跨行注释 | `stripHtmlComments` | `"<!--\nmulti\nline\n-->text"` → `"text"` |
|
||||
| 同行注释+内容 | `stripHtmlComments` | `"<!-- note -->some text"` → `"some text"` |
|
||||
| 内联代码中的注释 | `stripHtmlComments` | `` `<!-- kept -->` `` → 保留 |
|
||||
| 大小写不敏感 | `isMemoryFilePath` | `"claude.md"`, `"CLAUDE.MD"` |
|
||||
| 非 .md 规则文件 | `isMemoryFilePath` | `.claude/rules/foo.txt` → `false` |
|
||||
| 空数组 | `getLargeMemoryFiles` | `[]` → `[]` |
|
||||
|
||||
---
|
||||
|
||||
## 11.7 `src/tools/FileEditTool/__tests__/utils.test.ts`
|
||||
|
||||
| 函数 | 新增用例 |
|
||||
|------|---------|
|
||||
| `normalizeQuotes` | 混合引号 `"`she said 'hello'"` |
|
||||
| `stripTrailingWhitespace` | CR-only `\r`、无尾部换行、全空白串 |
|
||||
| `findActualString` | 空 content、Unicode content |
|
||||
| `preserveQuoteStyle` | 单引号、缩写中的撇号（如 `it's`）、空串 |
|
||||
| `applyEditToFile` | `replaceAll=true` 零匹配、`oldString` 无尾部 `\n`、多行内容 |
|
||||
|
||||
---
|
||||
|
||||
## 11.8 `src/utils/model/__tests__/providers.test.ts`
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 删除 `originalEnv` | 未使用，消除死代码 |
|
||||
| env 恢复改为快照 | `beforeEach` 保存 `process.env`，`afterEach` 恢复 |
|
||||
| 新增三变量同时设置 | bedrock + vertex + foundry 全部为 `"1"`，验证优先级 |
|
||||
| 新增非 `"1"` 值 | `"true"`, `"0"`, `""` |
|
||||
| `isFirstPartyAnthropicBaseUrl` | URL 含路径 `/v1`、含尾斜杠、非 HTTPS |
|
||||
|
||||
---
|
||||
|
||||
## 11.9 `src/utils/__tests__/hyperlink.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| 空 URL | `createHyperlink("http://x.com", "", { supported: true })` 不抛错 |
|
||||
| undefined supportsHyperlinks | 选项未传时走默认检测 |
|
||||
| 非 ant staging URL | `USER_TYPE !== "ant"` 时 staging 返回 `false` |
|
||||
|
||||
---
|
||||
|
||||
## 11.10 `src/utils/__tests__/objectGroupBy.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| key 返回 undefined | `(_, i) => undefined` → 全部归入 `undefined` 组 |
|
||||
| key 为特殊字符 | `({ name }) => name` 含空格/中文 |
|
||||
|
||||
---
|
||||
|
||||
## 11.11 `src/utils/__tests__/CircularBuffer.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| capacity=1 | 添加 2 个元素，仅保留最后一个 |
|
||||
| 空 buffer 调用 getRecent | 返回空数组 |
|
||||
| getRecent(0) | 返回空数组 |
|
||||
|
||||
---
|
||||
|
||||
## 11.12 `src/utils/__tests__/contentArray.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| 混合交替 | `[tool_result, text, tool_result]` — 验证插入到正确位置 |
|
||||
|
||||
---
|
||||
|
||||
## 11.13 `src/utils/__tests__/argumentSubstitution.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| 转义引号 | `"he said \"hello\""` |
|
||||
| 越界索引 | `$ARGUMENTS[99]`（参数不够时） |
|
||||
| 多占位符 | `"cmd $0 $1 $0"` |
|
||||
|
||||
---
|
||||
|
||||
## 11.14 `src/utils/__tests__/messages.test.ts`
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `normalizeMessages` 断言加强 | 验证拆分后的消息内容，不只是长度 |
|
||||
| `isNotEmptyMessage` 空白 | `[{ type: "text", text: " " }]` |
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `bun test` 全部通过
|
||||
- [ ] 目标文件评分从 ACCEPTABLE 提升至 GOOD
|
||||
- [ ] 无 `toContain` 用于精确值检查的场景
|
||||
145
docs/test-plans/12-mock-reliability.md
Normal file
145
docs/test-plans/12-mock-reliability.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Plan 12 — Mock 可靠性修复
|
||||
|
||||
> 优先级：高 | 影响 4 个测试文件 | 预估修改 ~15 处
|
||||
|
||||
本计划修复测试中 mock 相关的副作用、状态泄漏和虚假测试。
|
||||
|
||||
---
|
||||
|
||||
## 12.1 `gitOperationTracking.test.ts` — 消除分析副作用
|
||||
|
||||
**当前问题**：`detectGitOperation` 内部调用 `logEvent()`、`getCommitCounter().increment()`、`getPrCounter().increment()`，每次测试运行都触发真实分析代码。
|
||||
|
||||
**修复步骤**：
|
||||
|
||||
1. 读取 `src/tools/shared/gitOperationTracking.ts`，确认 analytics 导入路径
|
||||
2. 在测试文件顶部添加 `mock.module`：
|
||||
|
||||
```typescript
|
||||
import { mock } from "bun:test";
|
||||
|
||||
mock.module("src/services/analytics/index.ts", () => ({
|
||||
logEvent: mock(() => {}),
|
||||
// 按需补充其他导出
|
||||
}));
|
||||
```
|
||||
|
||||
3. 如果 `getCommitCounter` / `getPrCounter` 来自 `src/bootstrap/state.ts`：
|
||||
|
||||
```typescript
|
||||
mock.module("src/bootstrap/state.ts", () => ({
|
||||
getCommitCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
getPrCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
// 保留其他被测函数实际需要的导出
|
||||
}));
|
||||
```
|
||||
|
||||
4. 使用 `await import()` 模式加载被测模块
|
||||
5. 运行测试验证无副作用
|
||||
|
||||
**风险**：`mock.module` 会替换整个模块。如果 `detectGitOperation` 还需要其他来自这些模块的导出，需在 mock 工厂中提供。
|
||||
|
||||
---
|
||||
|
||||
## 12.2 `PermissionMode.test.ts` — 修复 `isExternalPermissionMode` 虚假测试
|
||||
|
||||
**当前问题**：`isExternalPermissionMode` 依赖 `process.env.USER_TYPE`。非 ant 环境下所有 mode 都返回 true，测试从未覆盖 false 分支。
|
||||
|
||||
**修复步骤**：
|
||||
|
||||
1. 新增 ant 环境测试组（见 Plan 10.3 详细用例）
|
||||
2. 使用 `beforeEach`/`afterEach` 管理 `process.env.USER_TYPE`
|
||||
|
||||
```typescript
|
||||
describe("when USER_TYPE is 'ant'", () => {
|
||||
const originalUserType = process.env.USER_TYPE;
|
||||
beforeEach(() => { process.env.USER_TYPE = "ant"; });
|
||||
afterEach(() => {
|
||||
if (originalUserType !== undefined) {
|
||||
process.env.USER_TYPE = originalUserType;
|
||||
} else {
|
||||
delete process.env.USER_TYPE;
|
||||
}
|
||||
});
|
||||
|
||||
test("returns false for 'auto'", () => {
|
||||
expect(isExternalPermissionMode("auto")).toBe(false);
|
||||
});
|
||||
test("returns false for 'bubble'", () => {
|
||||
expect(isExternalPermissionMode("bubble")).toBe(false);
|
||||
});
|
||||
test("returns true for 'plan'", () => {
|
||||
expect(isExternalPermissionMode("plan")).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
3. 验证新增测试确实执行 false 路径
|
||||
|
||||
---
|
||||
|
||||
## 12.3 `providers.test.ts` — 环境变量快照恢复
|
||||
|
||||
**当前问题**：
|
||||
- `originalEnv` 声明后未使用
|
||||
- `afterEach` 仅删除已知 3 个 key，如果源码新增 env var，测试间状态泄漏
|
||||
|
||||
**修复步骤**：
|
||||
|
||||
```typescript
|
||||
let savedEnv: Record<string, string | undefined>;
|
||||
|
||||
beforeEach(() => {
|
||||
savedEnv = {};
|
||||
for (const key of Object.keys(process.env)) {
|
||||
savedEnv[key] = process.env[key];
|
||||
}
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// 删除所有当前 env，恢复快照
|
||||
for (const key of Object.keys(process.env)) {
|
||||
delete process.env[key];
|
||||
}
|
||||
for (const [key, value] of Object.entries(savedEnv)) {
|
||||
if (value !== undefined) {
|
||||
process.env[key] = value;
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
> 简化方案：只保存/恢复相关 key 列表 `["CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY", "ANTHROPIC_BASE_URL", "USER_TYPE"]`，但需注释说明新增 env var 时需同步更新。
|
||||
|
||||
---
|
||||
|
||||
## 12.4 `envUtils.test.ts` — 验证环境变量恢复完整性
|
||||
|
||||
**当前状态**：已有 `afterEach` 恢复。需审查：
|
||||
|
||||
1. 确认所有 `describe` 块中的 `afterEach` 都完整恢复了修改的 env var
|
||||
2. 确认 `process.argv` 修改也被恢复（`getClaudeConfigHomeDir` 测试修改了 argv）
|
||||
3. 新增：`afterEach` 中断言无意外 env 泄漏（可选，CI-only）
|
||||
|
||||
---
|
||||
|
||||
## 12.5 `sleep.test.ts` / `memoize.test.ts` — 时间敏感测试加固
|
||||
|
||||
**当前状态**：已有合理 margin。可选加固：
|
||||
|
||||
| 文件 | 用例 | 当前 | 加固 |
|
||||
|------|------|------|------|
|
||||
| `sleep.test.ts` | `resolves after timeout` | `sleep(50)`, check `>= 40ms` | 增大 margin：`sleep(50)`, check `>= 30ms` |
|
||||
| `memoize.test.ts` | stale serve & refresh | TTL=1ms, wait 10ms | 增大 margin：TTL=5ms, wait 50ms |
|
||||
|
||||
> 仅在 CI 出现 flaky 时执行此加固。
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `gitOperationTracking.test.ts` 无分析副作用（可通过在 mock 中增加 `expect(logEvent).toHaveBeenCalledTimes(N)` 验证）
|
||||
- [ ] `PermissionMode.test.ts` 的 `isExternalPermissionMode` 覆盖 true + false 分支
|
||||
- [ ] `providers.test.ts` 的 `originalEnv` 死代码已删除
|
||||
- [ ] 所有修改 env 的测试文件恢复完整
|
||||
- [ ] `bun test` 全部通过
|
||||
71
docs/test-plans/13-cjk-truncate-tests.md
Normal file
71
docs/test-plans/13-cjk-truncate-tests.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Plan 13 — truncate CJK/Emoji 补充测试
|
||||
|
||||
> 优先级：中 | 1 个文件 | 预估新增 ~15 个测试用例
|
||||
|
||||
`truncate.ts` 使用 `stringWidth` 和 grapheme segmentation 实现宽度感知截断，但现有测试仅覆盖 ASCII。这是核心场景缺失。
|
||||
|
||||
---
|
||||
|
||||
## 被测函数
|
||||
|
||||
- `truncateToWidth(text, maxWidth)` — 尾部截断加 `…`
|
||||
- `truncateStartToWidth(text, maxWidth)` — 头部截断加 `…`
|
||||
- `truncateToWidthNoEllipsis(text, maxWidth)` — 尾部截断无省略号
|
||||
- `truncatePathMiddle(path, maxLength)` — 路径中间截断
|
||||
- `wrapText(text, maxWidth)` — 按宽度换行
|
||||
|
||||
---
|
||||
|
||||
## 新增用例
|
||||
|
||||
### CJK 全角字符
|
||||
|
||||
| 用例 | 函数 | 输入 | maxWidth | 期望行为 |
|
||||
|------|------|------|----------|----------|
|
||||
| 纯中文截断 | `truncateToWidth` | `"你好世界"` | 4 | `"你好…"` (每个中文字占 2 宽度) |
|
||||
| 中英混合 | `truncateToWidth` | `"hello你好"` | 8 | `"hello你…"` |
|
||||
| 全角不截断 | `truncateToWidth` | `"你好"` | 4 | `"你好"` (恰好 4) |
|
||||
| emoji 单字符 | `truncateToWidth` | `"👋"` | 2 | `"👋"` (emoji 通常 2 宽度) |
|
||||
| emoji 截断 | `truncateToWidth` | `"hello 👋 world"` | 8 | 确认宽度计算正确 |
|
||||
| 头部中文 | `truncateStartToWidth` | `"你好世界"` | 4 | `"…界"` |
|
||||
| 无省略中文 | `truncateToWidthNoEllipsis` | `"你好世界"` | 4 | `"你好"` |
|
||||
|
||||
> **注意**：`stringWidth` 对 CJK/emoji 的宽度计算取决于具体实现。先在 REPL 中运行确认实际宽度再写断言：
|
||||
> ```typescript
|
||||
> import { stringWidth } from "src/utils/truncate.ts";
|
||||
> console.log(stringWidth("你好")); // 确认是 4 还是 2
|
||||
> console.log(stringWidth("👋")); // 确认 emoji 宽度
|
||||
> ```
|
||||
|
||||
### 路径中间截断补充
|
||||
|
||||
| 用例 | 输入 | maxLength | 期望 |
|
||||
|------|------|-----------|------|
|
||||
| 文件名超长 | `"/very/long/path/to/MyComponent.tsx"` | 10 | 含 `…` 且以 `.tsx` 结尾 |
|
||||
| 无斜杠短串 | `"abc"` | 1 | 确认行为不抛错 |
|
||||
| maxLength 极小 | `"/a/b"` | 1 | 确认不抛错 |
|
||||
| maxLength=4 | `"/a/b/c.ts"` | 4 | 确认行为 |
|
||||
|
||||
### wrapText 补充
|
||||
|
||||
| 用例 | 输入 | maxWidth | 期望 |
|
||||
|------|------|----------|------|
|
||||
| 含换行符 | `"hello\nworld"` | 10 | 保留原有换行 |
|
||||
| 宽度=0 | `"hello"` | 0 | 空串或原串（确认不抛错） |
|
||||
|
||||
---
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. 在 REPL 中确认 `stringWidth` 对 CJK/emoji 的实际返回值
|
||||
2. 按实际值编写精确断言
|
||||
3. 如果 `stringWidth` 依赖 ICU 或平台特性，添加平台检查（`process.platform !== "win32"` 跳过条件）
|
||||
4. 运行测试
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 至少 5 个 CJK/emoji 相关测试通过
|
||||
- [ ] 断言基于实际 `stringWidth` 返回值，非猜测
|
||||
- [ ] `bun test` 全部通过
|
||||
191
docs/test-plans/14-integration-tests.md
Normal file
191
docs/test-plans/14-integration-tests.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# Plan 14 — 集成测试搭建
|
||||
|
||||
> 优先级：中 | 新建 ~3 个测试文件 | 预估 ~30 个测试用例
|
||||
|
||||
当前 `tests/integration/` 目录为空，spec 设计的三个集成测试均未创建。本计划搭建 mock 基础设施并实现核心集成测试。
|
||||
|
||||
---
|
||||
|
||||
## 14.1 搭建 `tests/mocks/` 基础设施
|
||||
|
||||
### 文件结构
|
||||
|
||||
```
|
||||
tests/
|
||||
├── mocks/
|
||||
│ ├── api-responses.ts # Claude API mock 响应
|
||||
│ ├── file-system.ts # 临时文件系统工具
|
||||
│ └── fixtures/
|
||||
│ ├── sample-claudemd.md # CLAUDE.md 样本
|
||||
│ └── sample-messages.json # 消息样本
|
||||
├── integration/
|
||||
│ ├── tool-chain.test.ts
|
||||
│ ├── context-build.test.ts
|
||||
│ └── message-pipeline.test.ts
|
||||
└── helpers/
|
||||
└── setup.ts # 共享 beforeAll/afterAll
|
||||
```
|
||||
|
||||
### `tests/mocks/file-system.ts`
|
||||
|
||||
```typescript
|
||||
import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
|
||||
export async function createTempDir(prefix = "claude-test-"): Promise<string> {
|
||||
const dir = await mkdtemp(join(tmpdir(), prefix));
|
||||
return dir;
|
||||
}
|
||||
|
||||
export async function cleanupTempDir(dir: string): Promise<void> {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
export async function writeTempFile(dir: string, name: string, content: string): Promise<string> {
|
||||
const path = join(dir, name);
|
||||
await writeFile(path, content, "utf-8");
|
||||
return path;
|
||||
}
|
||||
```
|
||||
|
||||
### `tests/mocks/fixtures/sample-claudemd.md`
|
||||
|
||||
```markdown
|
||||
# Project Instructions
|
||||
|
||||
This is a sample CLAUDE.md file for testing.
|
||||
```
|
||||
|
||||
### `tests/mocks/api-responses.ts`
|
||||
|
||||
```typescript
|
||||
export const mockStreamResponse = {
|
||||
type: "message_start" as const,
|
||||
message: {
|
||||
id: "msg_mock_001",
|
||||
type: "message" as const,
|
||||
role: "assistant",
|
||||
content: [],
|
||||
model: "claude-sonnet-4-20250514",
|
||||
stop_reason: null,
|
||||
stop_sequence: null,
|
||||
usage: { input_tokens: 100, output_tokens: 0 },
|
||||
},
|
||||
};
|
||||
|
||||
export const mockTextBlock = {
|
||||
type: "content_block_start" as const,
|
||||
index: 0,
|
||||
content_block: { type: "text" as const, text: "Mock response" },
|
||||
};
|
||||
|
||||
export const mockToolUseBlock = {
|
||||
type: "content_block_start" as const,
|
||||
index: 1,
|
||||
content_block: {
|
||||
type: "tool_use" as const,
|
||||
id: "toolu_mock_001",
|
||||
name: "Read",
|
||||
input: { file_path: "/tmp/test.txt" },
|
||||
},
|
||||
};
|
||||
|
||||
export const mockEndEvent = {
|
||||
type: "message_stop" as const,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14.2 `tests/integration/tool-chain.test.ts`
|
||||
|
||||
**目标**：验证 Tool 注册 → 发现 → 权限检查链路。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/tools.ts` 的 `getAllBaseTools` / `getTools` 导入链过重。策略：
|
||||
- 尝试直接 import 并 mock 最重依赖
|
||||
- 若不可行，改为测试 `src/Tool.ts` 的 `findToolByName` + 手动构造 tool 列表
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 验证点 |
|
||||
|---|------|--------|
|
||||
| 1 | `findToolByName("Bash")` 在已注册列表中查找 | 返回正确的 tool 定义 |
|
||||
| 2 | `findToolByName("NonExistent")` | 返回 `undefined` |
|
||||
| 3 | `findToolByName` 大小写不敏感 | `"bash"` 也能找到 |
|
||||
| 4 | `filterToolsByDenyRules` 拒绝特定工具 | 被拒绝工具不在结果中 |
|
||||
| 5 | `parseToolPreset("default")` 返回已知列表 | 包含核心 tools |
|
||||
| 6 | `buildTool` 构建的 tool 可被 `findToolByName` 发现 | 端到端验证 |
|
||||
|
||||
> 如果 `getAllBaseTools` 确实不可导入，改用 mock tool list 替代。
|
||||
|
||||
---
|
||||
|
||||
## 14.3 `tests/integration/context-build.test.ts`
|
||||
|
||||
**目标**：验证系统提示组装流程（CLAUDE.md 加载 + git status + 日期注入）。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/context.ts` 依赖链极重。策略：
|
||||
- Mock `src/bootstrap/state.ts`（提供 cwd、projectRoot）
|
||||
- Mock `src/utils/git.ts`（提供 git status）
|
||||
- 使用真实 `src/utils/claudemd.ts` + 临时文件
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 验证点 |
|
||||
|---|------|--------|
|
||||
| 1 | 基本 context 构建 | 返回值包含系统提示字符串 |
|
||||
| 2 | CLAUDE.md 内容出现在 context 中 | `stripHtmlComments` 后的内容被包含 |
|
||||
| 3 | 多层目录 CLAUDE.md 合并 | 父目录 + 子目录 CLAUDE.md 都被加载 |
|
||||
| 4 | 无 CLAUDE.md 时不报错 | context 正常返回，无 crash |
|
||||
| 5 | git status 为 null | context 正常构建（测试环境中 git 不可用时） |
|
||||
|
||||
> **风险评估**：如果 mock `context.ts` 的依赖链成本过高，退化为测试 `buildEffectiveSystemPrompt`（已在 systemPrompt.test.ts 中完成），记录为已知限制。
|
||||
|
||||
---
|
||||
|
||||
## 14.4 `tests/integration/message-pipeline.test.ts`
|
||||
|
||||
**目标**：验证用户输入 → 消息格式化 → API 请求构建。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/services/api/claude.ts` 构建最终 API 请求。策略：
|
||||
- Mock Anthropic SDK 的 streaming endpoint
|
||||
- 验证请求参数结构
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 验证点 |
|
||||
|---|------|--------|
|
||||
| 1 | 文本消息格式化 | `createUserMessage` 生成正确 role+content |
|
||||
| 2 | tool_result 消息格式化 | 包含 tool_use_id 和 content |
|
||||
| 3 | 多轮消息序列化 | messages 数组保持顺序 |
|
||||
| 4 | 系统提示注入到请求 | API 请求的 system 字段非空 |
|
||||
| 5 | 消息 normalize 后格式一致 | `normalizeMessages` 输出结构正确 |
|
||||
|
||||
> **现实评估**：消息格式化的大部分已在 `messages.test.ts` 覆盖。API 请求构建需要 mock SDK，复杂度高。如果投入产出比低，仅实现用例 1-3 和 5，用例 4 标记为 stretch goal。
|
||||
|
||||
---
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. 创建 `tests/mocks/` 目录和基础文件
|
||||
2. 实现 `tool-chain.test.ts`（最低风险，最高价值）
|
||||
3. 评估 `context-build.test.ts` 可行性，决定是否实施
|
||||
4. 实现 `message-pipeline.test.ts`（可降级为单元测试）
|
||||
5. 更新 `testing-spec.md` 状态
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `tests/mocks/` 基础设施可用
|
||||
- [ ] 至少 `tool-chain.test.ts` 实现并通过
|
||||
- [ ] 集成测试独立于单元测试运行：`bun test tests/integration/`
|
||||
- [ ] 所有集成测试使用 `createTempDir` + `cleanupTempDir`，不留文件系统残留
|
||||
- [ ] `bun test` 全部通过
|
||||
67
docs/test-plans/15-cli-coverage-baseline.md
Normal file
67
docs/test-plans/15-cli-coverage-baseline.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Plan 15 — CLI 参数测试 + 覆盖率基线
|
||||
|
||||
> 优先级：低 | 预估 ~15 个测试用例
|
||||
|
||||
---
|
||||
|
||||
## 15.1 `src/main.tsx` CLI 参数测试
|
||||
|
||||
**目标**：覆盖 Commander.js 配置的参数解析和模式切换。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/main.tsx` 的 Commander 实例通常在模块顶层创建。测试策略：
|
||||
- 直接构造 Commander 实例或 mock `main.tsx` 的 program 导出
|
||||
- 使用 `parseArgs` 而非 `parse`（不触发 `process.exit`）
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 输入 | 期望 |
|
||||
|---|------|------|------|
|
||||
| 1 | 默认模式 | `[]` | 模式为 REPL |
|
||||
| 2 | pipe 模式 | `["-p"]` | 模式为 pipe |
|
||||
| 3 | pipe 带输入 | `["-p", "say hello"]` | 输入为 `"say hello"` |
|
||||
| 4 | print 模式 | `["--print", "hello"]` | 等效于 pipe |
|
||||
| 5 | verbose | `["-v"]` | verbose 标志为 true |
|
||||
| 6 | model 选择 | `["--model", "claude-opus-4-6"]` | model 值正确传递 |
|
||||
| 7 | system prompt | `["--system-prompt", "custom"]` | system prompt 被设置 |
|
||||
| 8 | help | `["--help"]` | 显示帮助信息，不报错 |
|
||||
| 9 | version | `["--version"]` | 显示版本号 |
|
||||
| 10 | unknown flag | `["--nonexistent"]` | 不报错（Commander 允许未知参数时） |
|
||||
|
||||
> **风险**：`main.tsx` 可能执行初始化逻辑（auth、analytics），需要在 mock 环境中运行。如果复杂度过高，降级为只测试参数解析部分。
|
||||
|
||||
---
|
||||
|
||||
## 15.2 覆盖率基线
|
||||
|
||||
### 运行命令
|
||||
|
||||
```bash
|
||||
bun test --coverage 2>&1 | tail -50
|
||||
```
|
||||
|
||||
### 记录内容
|
||||
|
||||
| 模块 | 当前覆盖率 | 目标 |
|
||||
|------|-----------|------|
|
||||
| `src/utils/` | 待测量 | >= 80% |
|
||||
| `src/utils/permissions/` | 待测量 | >= 60% |
|
||||
| `src/utils/model/` | 待测量 | >= 60% |
|
||||
| `src/Tool.ts` + `src/tools.ts` | 待测量 | >= 80% |
|
||||
| `src/utils/claudemd.ts` | 待测量 | >= 40%（核心逻辑难测） |
|
||||
| 整体 | 待测量 | 不设强制指标 |
|
||||
|
||||
### 后续行动
|
||||
|
||||
- 将基线数据填入 `testing-spec.md` §4
|
||||
- 识别覆盖率最低的 10 个文件，排入后续测试计划
|
||||
- 如 `bun test --coverage` 输出不可用（Bun 版本限制），改用手动计算已测/总导出函数比
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] CLI 参数至少覆盖 5 个核心 flag
|
||||
- [ ] 覆盖率基线数据记录到 testing-spec.md
|
||||
- [ ] `bun test` 全部通过
|
||||
188
docs/test-plans/phase-16-zero-dep-pure-functions.md
Normal file
188
docs/test-plans/phase-16-zero-dep-pure-functions.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Phase 16 — 零依赖纯函数测试
|
||||
|
||||
> 创建日期：2026-04-02
|
||||
> 预计：+120 tests / 8 files
|
||||
> 目标：覆盖所有零外部依赖的纯函数/类模块
|
||||
|
||||
所有模块均为纯函数或零外部依赖类，mock 成本为零，ROI 最高。
|
||||
|
||||
---
|
||||
|
||||
## 16.1 `src/utils/__tests__/stream.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/utils/stream.ts`（76 行）
|
||||
**导出**: `Stream<T>` class — 手动异步队列，实现 `AsyncIterator<T>`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| enqueue then read | 单条消息正确传递 |
|
||||
| enqueue multiple then drain | 多条消息顺序消费 |
|
||||
| done resolves pending readers | `done()` 后迭代结束 |
|
||||
| done with no pending readers | 无等待时安全关闭 |
|
||||
| error rejects pending readers | `error(e)` 传播异常 |
|
||||
| error after done | 后续操作安全处理 |
|
||||
| single-iteration guard | `return()` 后不可再迭代 |
|
||||
| empty stream done immediately | 无数据时 done 返回 `{ done: true }` |
|
||||
| concurrent enqueue | 多次 enqueue 不丢失 |
|
||||
| backpressure | reader 慢于 writer 时不丢数据 |
|
||||
|
||||
---
|
||||
|
||||
## 16.2 `src/utils/__tests__/abortController.test.ts`（~12 tests）
|
||||
|
||||
**目标模块**: `src/utils/abortController.ts`（99 行）
|
||||
**导出**: `createAbortController()`, `createChildAbortController()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parent abort propagates to child | `parent.abort()` → child aborted |
|
||||
| child abort does NOT propagate to parent | `child.abort()` → parent still active |
|
||||
| already-aborted parent → child immediately aborted | 创建时即继承 abort 状态 |
|
||||
| child listener cleanup after parent abort | WeakRef 回收后无泄漏 |
|
||||
| multiple children of same parent | 独立 abort 传播 |
|
||||
| child abort then parent abort | 顺序无关 |
|
||||
| signal.maxListeners raised | MaxListenersExceededWarning 不触发 |
|
||||
|
||||
---
|
||||
|
||||
## 16.3 `src/utils/__tests__/bufferedWriter.test.ts`（~14 tests）
|
||||
|
||||
**目标模块**: `src/utils/bufferedWriter.ts`（100 行）
|
||||
**导出**: `createBufferedWriter()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| single write buffered | write → buffer 累积 |
|
||||
| flush on size threshold | 超过 maxSize 时自动 flush |
|
||||
| flush on timer | 定时器触发 flush |
|
||||
| immediate mode | `{ immediate: true }` 跳过缓冲 |
|
||||
| overflow coalescing | overflow 内容合并到下次 flush |
|
||||
| empty buffer flush | 无数据时 flush 无副作用 |
|
||||
| close flushes remaining | close 触发最终 flush |
|
||||
| multiple writes before flush | 批量写入合并 |
|
||||
| flush callback receives concatenated data | writeFn 参数正确 |
|
||||
|
||||
**Mock**: 注入 `writeFn` 回调，可选 fake timers
|
||||
|
||||
---
|
||||
|
||||
## 16.4 `src/utils/__tests__/gitDiff.test.ts`（~20 tests）
|
||||
|
||||
**目标模块**: `src/utils/gitDiff.ts`（532 行）
|
||||
**可测函数**: `parseGitNumstat()`, `parseGitDiff()`, `parseShortstat()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseGitNumstat — single file | `1\t2\tpath` → { added: 1, deleted: 2, file: "path" } |
|
||||
| parseGitNumstat — binary file | `-\t-\timage.png` → binary flag |
|
||||
| parseGitNumstat — rename | `{ old => new }` 格式解析 |
|
||||
| parseGitNumstat — empty diff | 空字符串 → [] |
|
||||
| parseGitNumstat — multiple files | 多行正确分割 |
|
||||
| parseGitDiff — added lines | `+` 开头行计数 |
|
||||
| parseGitDiff — deleted lines | `-` 开头行计数 |
|
||||
| parseGitDiff — hunk header | `@@ -a,b +c,d @@` 解析 |
|
||||
| parseGitDiff — new file mode | `new file mode 100644` 检测 |
|
||||
| parseGitDiff — deleted file mode | `deleted file mode` 检测 |
|
||||
| parseGitDiff — binary diff | Binary files differ 处理 |
|
||||
| parseShortstat — all components | `1 file changed, 5 insertions(+), 3 deletions(-)` |
|
||||
| parseShortstat — insertions only | 无 deletions |
|
||||
| parseShortstat — deletions only | 无 insertions |
|
||||
| parseShortstat — files only | 仅 file changed |
|
||||
| parseShortstat — empty | 空字符串 → 默认值 |
|
||||
| parseShortstat — rename | `1 file changed, ...` 重命名 |
|
||||
|
||||
**Mock**: 无需 mock — 全部是纯字符串解析
|
||||
|
||||
---
|
||||
|
||||
## 16.5 `src/__tests__/history.test.ts`（~18 tests）
|
||||
|
||||
**目标模块**: `src/history.ts`（464 行）
|
||||
**可测函数**: `parseReferences()`, `expandPastedTextRefs()`, `formatPastedTextRef()`, `formatImageRef()`, `getPastedTextRefNumLines()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseReferences — text ref | `#1` → [{ type: "text", ref: 1 }] |
|
||||
| parseReferences — image ref | `@1` → [{ type: "image", ref: 1 }] |
|
||||
| parseReferences — multiple refs | `#1 #2 @3` → 3 refs |
|
||||
| parseReferences — no refs | `"hello"` → [] |
|
||||
| parseReferences — duplicate refs | `#1 #1` → 去重或保留 |
|
||||
| parseReferences — zero ref | `#0` → 边界 |
|
||||
| parseReferences — large ref | `#999` → 正常 |
|
||||
| formatPastedTextRef — basic | 输出格式验证 |
|
||||
| formatPastedTextRef — multiline | 多行内容格式 |
|
||||
| getPastedTextRefNumLines — 1 line | 返回 1 |
|
||||
| getPastedTextRefNumLines — multiple lines | 换行计数 |
|
||||
| expandPastedTextRefs — single ref | 替换单个引用 |
|
||||
| expandPastedTextRefs — multiple refs | 替换多个引用 |
|
||||
| expandPastedTextRefs — no refs | 原样返回 |
|
||||
| expandPastedTextRefs — mixed content | 文本 + 引用混合 |
|
||||
| formatImageRef — basic | 输出格式 |
|
||||
|
||||
**Mock**: `mock.module("src/bootstrap/state.ts", ...)` 解锁模块
|
||||
|
||||
---
|
||||
|
||||
## 16.6 `src/utils/__tests__/sliceAnsi.test.ts`（~16 tests）
|
||||
|
||||
**目标模块**: `src/utils/sliceAnsi.ts`（91 行）
|
||||
**导出**: `sliceAnsi()` — ANSI 感知的字符串切片
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| plain text slice | `"hello".slice(1,3)` 等价 |
|
||||
| preserve ANSI codes | `\x1b[31mhello\x1b[0m` 切片后保留颜色 |
|
||||
| close opened styles | 切片点在 ANSI 样式中间时正确关闭 |
|
||||
| hyperlink handling | OSC 8 超链接不被切断 |
|
||||
| combining marks (diacritics) | `é` = `e\u0301` 不被切开 |
|
||||
| Devanagari matras | 零宽字符不被切断 |
|
||||
| full-width characters | CJK 字符宽度 = 2 |
|
||||
| empty slice | 返回空字符串 |
|
||||
| full slice | 返回完整字符串 |
|
||||
| boundary at ANSI code | 边界恰好在 escape 序列上 |
|
||||
| nested ANSI styles | 多层嵌套时正确处理 |
|
||||
| slice start > end | 空结果 |
|
||||
|
||||
**Mock**: `mock.module("@alcalzone/ansi-tokenize", ...)`, `mock.module("ink/stringWidth", ...)`
|
||||
|
||||
---
|
||||
|
||||
## 16.7 `src/utils/__tests__/treeify.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/utils/treeify.ts`（170 行）
|
||||
**导出**: `treeify()` — 递归树渲染
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| simple flat tree | `{ a: {}, b: {} }` → 2 行 |
|
||||
| nested tree | `{ a: { b: { c: {} } } }` → 3 行缩进 |
|
||||
| array values | `[1, 2, 3]` 渲染为列表 |
|
||||
| circular reference | 不无限递归 |
|
||||
| empty object | `{}` 处理 |
|
||||
| single key | 布局适配 |
|
||||
| branch vs last-branch character | ├─ vs └─ |
|
||||
| custom prefix | options 前缀传递 |
|
||||
| deep nesting | 5+ 层缩进正确 |
|
||||
| mixed object/array | 混合结构 |
|
||||
|
||||
**Mock**: `mock.module("figures", ...)`, color 模块 mock
|
||||
|
||||
---
|
||||
|
||||
## 16.8 `src/utils/__tests__/words.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/utils/words.ts`（800 行，大部分是词表数据）
|
||||
**导出**: `generateWordSlug()`, `generateShortWordSlug()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| generateWordSlug format | `adjective-verb-noun` 三段式 |
|
||||
| generateShortWordSlug format | `adjective-noun` 两段式 |
|
||||
| all parts non-empty | 无空段 |
|
||||
| hyphen separator | `-` 分隔 |
|
||||
| all parts from word lists | 成分来自预定义词表 |
|
||||
| multiple calls uniqueness | 连续调用不总是相同 |
|
||||
| no consecutive hyphens | 无 `--` |
|
||||
| lowercase only | 全小写 |
|
||||
|
||||
**Mock**: `mock.module("crypto", ...)` 控制 `randomBytes` 实现确定性测试
|
||||
203
docs/test-plans/phase-17-tool-submodules.md
Normal file
203
docs/test-plans/phase-17-tool-submodules.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# Phase 17 — Tool 子模块纯逻辑测试
|
||||
|
||||
> 创建日期：2026-04-02
|
||||
> 预计：+150 tests / 11 files
|
||||
> 目标：覆盖 Tool 目录下有丰富纯逻辑但零测试的子模块
|
||||
|
||||
---
|
||||
|
||||
## 17.1 `src/tools/PowerShellTool/__tests__/powershellSecurity.test.ts`（~25 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/powershellSecurity.ts`（1091 行）
|
||||
|
||||
**安全关键** — 检测 ~20 种攻击向量。
|
||||
|
||||
| 测试分组 | 测试数 | 验证点 |
|
||||
|---------|-------|--------|
|
||||
| Invoke-Expression 检测 | 3 | `IEX`, `Invoke-Expression`, 变形 |
|
||||
| Download cradle 检测 | 3 | `Net.WebClient`, `Invoke-WebRequest`, pipe |
|
||||
| Privilege escalation | 3 | `Start-Process -Verb RunAs`, `runas.exe` |
|
||||
| COM object | 2 | `New-Object -ComObject`, WScript.Shell |
|
||||
| Scheduled tasks | 2 | `schtasks`, `Register-ScheduledTask` |
|
||||
| WMI | 2 | `Invoke-WmiMethod`, `Get-WmiObject` |
|
||||
| Module loading | 2 | `Import-Module` 从网络路径 |
|
||||
| 安全命令通过 | 3 | `Get-Process`, `Get-ChildItem`, `Write-Host` |
|
||||
| 混淆绕过尝试 | 3 | base64, 字符串拼接, 空格变形 |
|
||||
| 组合命令 | 2 | `;` 分隔的多命令 |
|
||||
|
||||
**Mock**: 构造 `ParsedPowerShellCommand` 对象（不需要真实 AST）
|
||||
|
||||
---
|
||||
|
||||
## 17.2 `src/tools/PowerShellTool/__tests__/commandSemantics.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/commandSemantics.ts`（143 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| grep exit 0/1/2 | 语义映射 |
|
||||
| robocopy exit codes | Windows 特殊退出码 |
|
||||
| findstr exit codes | Windows find 工具 |
|
||||
| unknown command | 默认语义 |
|
||||
| extractBaseCommand — basic | `grep "pattern" file` → `grep` |
|
||||
| extractBaseCommand — path | `C:\tools\rg.exe` → `rg` |
|
||||
| heuristicallyExtractBaseCommand | 模糊匹配 |
|
||||
|
||||
---
|
||||
|
||||
## 17.3 `src/tools/PowerShellTool/__tests__/destructiveCommandWarning.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/destructiveCommandWarning.ts`（110 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| Remove-Item -Recurse -Force | 危险 |
|
||||
| Format-Volume | 危险 |
|
||||
| git reset --hard | 危险 |
|
||||
| DROP TABLE | 危险 |
|
||||
| Remove-Item (no -Force) | 安全 |
|
||||
| Get-ChildItem | 安全 |
|
||||
| 管道组合 | `rm -rf` + pipe |
|
||||
| 大小写混合 | `ReMoVe-ItEm` |
|
||||
|
||||
---
|
||||
|
||||
## 17.4 `src/tools/PowerShellTool/__tests__/gitSafety.test.ts`（~12 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/gitSafety.ts`（177 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| normalizeGitPathArg — forward slash | 规范化 |
|
||||
| normalizeGitPathArg — backslash | Windows 路径规范化 |
|
||||
| normalizeGitPathArg — NTFS short name | `GITFI~1` → `.git` |
|
||||
| isGitInternalPathPS — .git/config | true |
|
||||
| isGitInternalPathPS — normal file | false |
|
||||
| isDotGitPathPS — hidden git dir | true |
|
||||
| isDotGitPathPS — .gitignore | false |
|
||||
| bare repo attack | `.git` 路径遍历 |
|
||||
|
||||
---
|
||||
|
||||
## 17.5 `src/tools/LSPTool/__tests__/formatters.test.ts`（~20 tests）
|
||||
|
||||
**目标模块**: `src/tools/LSPTool/formatters.ts`（593 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| formatGoToDefinitionResult — single | 单个定义 |
|
||||
| formatGoToDefinitionResult — multiple | 多个定义（分组） |
|
||||
| formatFindReferencesResult | 引用列表 |
|
||||
| formatHoverResult — markdown | markdown 内容 |
|
||||
| formatHoverResult — plaintext | 纯文本 |
|
||||
| formatDocumentSymbolResult — classes | 类符号 |
|
||||
| formatDocumentSymbolResult — functions | 函数符号 |
|
||||
| formatDocumentSymbolResult — nested | 嵌套符号 |
|
||||
| formatWorkspaceSymbolResult | 工作区符号 |
|
||||
| formatPrepareCallHierarchyResult | 调用层次 |
|
||||
| formatIncomingCallsResult | 入调用 |
|
||||
| formatOutgoingCallsResult | 出调用 |
|
||||
| empty results | 各函数空结果 |
|
||||
| groupByFile helper | 文件分组逻辑 |
|
||||
|
||||
---
|
||||
|
||||
## 17.6 `src/tools/GrepTool/__tests__/utils.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/tools/GrepTool/GrepTool.ts`（577 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| applyHeadLimit — within limit | 不截断 |
|
||||
| applyHeadLimit — exceeds limit | 正确截断 |
|
||||
| applyHeadLimit — offset + limit | 分页逻辑 |
|
||||
| applyHeadLimit — zero limit | 边界 |
|
||||
| formatLimitInfo — basic | 格式化输出 |
|
||||
|
||||
**Mock**: `mock.module("src/utils/log.ts", ...)` 解锁导入
|
||||
|
||||
---
|
||||
|
||||
## 17.7 `src/tools/WebFetchTool/__tests__/utils.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/tools/WebFetchTool/utils.ts`（531 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| validateURL — valid http | 通过 |
|
||||
| validateURL — valid https | 通过 |
|
||||
| validateURL — ftp | 拒绝 |
|
||||
| validateURL — no protocol | 拒绝 |
|
||||
| validateURL — localhost | 处理 |
|
||||
| isPermittedRedirect — same host | 允许 |
|
||||
| isPermittedRedirect — different host | 拒绝 |
|
||||
| isPermittedRedirect — subdomain | 处理 |
|
||||
| isRedirectInfo — valid object | true |
|
||||
| isRedirectInfo — invalid | false |
|
||||
|
||||
---
|
||||
|
||||
## 17.8 `src/tools/WebFetchTool/__tests__/preapproved.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/tools/WebFetchTool/preapproved.ts`（167 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| exact hostname match | 通过 |
|
||||
| subdomain match | 处理 |
|
||||
| path prefix match | `/docs/api` 匹配 |
|
||||
| path non-match | `/internal` 不匹配 |
|
||||
| unknown hostname | false |
|
||||
| empty pathname | 边界 |
|
||||
|
||||
---
|
||||
|
||||
## 17.9 `src/tools/FileReadTool/__tests__/utils.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/tools/FileReadTool/FileReadTool.ts`（1184 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| isBlockedDevicePath — /dev/sda | true |
|
||||
| isBlockedDevicePath — /dev/null | 处理 |
|
||||
| isBlockedDevicePath — normal file | false |
|
||||
| detectSessionFileType — .jsonl | 会话文件类型 |
|
||||
| detectSessionFileType — unknown | 未知类型 |
|
||||
| formatFileLines — basic | 行号格式 |
|
||||
| formatFileLines — empty | 空文件 |
|
||||
|
||||
---
|
||||
|
||||
## 17.10 `src/tools/AgentTool/__tests__/agentToolUtils.test.ts`（~18 tests）
|
||||
|
||||
**目标模块**: `src/tools/AgentTool/agentToolUtils.ts`（688 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| filterToolsForAgent — builtin only | 只返回内置工具 |
|
||||
| filterToolsForAgent — exclude async | 排除异步工具 |
|
||||
| filterToolsForAgent — permission mode | 权限过滤 |
|
||||
| resolveAgentTools — wildcard | 通配符展开 |
|
||||
| resolveAgentTools — explicit list | 显式列表 |
|
||||
| countToolUses — multiple | 消息中工具调用计数 |
|
||||
| countToolUses — zero | 无工具调用 |
|
||||
| extractPartialResult — text only | 提取文本 |
|
||||
| extractPartialResult — mixed | 混合内容 |
|
||||
| getLastToolUseName — basic | 最后工具名 |
|
||||
| getLastToolUseName — no tool use | 无工具调用 |
|
||||
|
||||
**Mock**: `mock.module("src/bootstrap/state.ts", ...)`, `mock.module("src/utils/log.ts", ...)`
|
||||
|
||||
---
|
||||
|
||||
## 17.11 `src/tools/LSPTool/__tests__/schemas.test.ts`（~5 tests）
|
||||
|
||||
**目标模块**: `src/tools/LSPTool/schemas.ts`（216 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| isValidLSPOperation — goToDefinition | true |
|
||||
| isValidLSPOperation — findReferences | true |
|
||||
| isValidLSPOperation — hover | true |
|
||||
| isValidLSPOperation — invalid | false |
|
||||
| isValidLSPOperation — empty string | false |
|
||||
110
docs/test-plans/phase-18-weak-fixes.md
Normal file
110
docs/test-plans/phase-18-weak-fixes.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Phase 18 — WEAK 修复 + ACCEPTABLE 加固
|
||||
|
||||
> 创建日期：2026-04-02
|
||||
> 预计：+30 tests / 4 files (修改现有)
|
||||
> 目标：修复所有 WEAK 评分测试文件，消除系统性问题
|
||||
|
||||
---
|
||||
|
||||
## 18.1 `src/utils/__tests__/format.test.ts` — 断言精确化（+5 tests）
|
||||
|
||||
**问题**: `formatNumber`/`formatTokens`/`formatRelativeTime` 使用 `toContain`
|
||||
**修复**: 改为 `toBe` 精确匹配
|
||||
|
||||
```diff
|
||||
- expect(formatNumber(1500000)).toContain("1.5")
|
||||
+ expect(formatNumber(1500000)).toBe("1.5m")
|
||||
```
|
||||
|
||||
新增测试：
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| formatNumber — 0 | `"0"` |
|
||||
| formatNumber — billions | `"1.5b"` |
|
||||
| formatTokens — thousands | 精确匹配 |
|
||||
| formatRelativeTime — hours ago | 精确匹配 |
|
||||
| formatRelativeTime — days ago | 精确匹配 |
|
||||
|
||||
---
|
||||
|
||||
## 18.2 `src/utils/__tests__/envValidation.test.ts` — Bug 确认（+3 tests）
|
||||
|
||||
**问题**: `value=1, lowerBound=100` 返回 `status: "valid"` — 函数名暗示有下界检查
|
||||
**计划**: 先读取源码确认 `defaultValue` 和 `lowerBound` 的语义关系，然后：
|
||||
- 如果是源码 bug → 在测试中注释标记，不修改源码
|
||||
- 如果是设计意图 → 更新测试描述明确语义
|
||||
|
||||
新增测试：
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseFloat truncation | `"50.9"` → 50 |
|
||||
| whitespace handling | `" 500 "` → 500 |
|
||||
| very large number | overflow 处理 |
|
||||
|
||||
---
|
||||
|
||||
## 18.3 `src/utils/permissions/__tests__/PermissionMode.test.ts` — false 路径（+8 tests）
|
||||
|
||||
**问题**: `isExternalPermissionMode` false 路径从未执行
|
||||
**修复**: 覆盖所有 5 种 mode 的 true/false 期望
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| isExternalPermissionMode — plan | false |
|
||||
| isExternalPermissionMode — auto | false |
|
||||
| isExternalPermissionMode — default | false |
|
||||
| permissionModeFromString — all modes | 5 种 mode 全覆盖 |
|
||||
| permissionModeFromString — invalid | 默认值 |
|
||||
| permissionModeFromString — case insensitive | 大小写 |
|
||||
| isPermissionMode — valid strings | true |
|
||||
| isPermissionMode — invalid strings | false |
|
||||
|
||||
---
|
||||
|
||||
## 18.4 `src/tools/shared/__tests__/gitOperationTracking.test.ts` — mock analytics（+4 tests）
|
||||
|
||||
**问题**: 未 mock analytics 依赖，测试产生副作用
|
||||
**修复**: 添加 `mock.module("src/services/analytics/...", ...)`
|
||||
|
||||
新增测试：
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseGitCommitId — all GH PR actions | 补齐 6 个 action |
|
||||
| detectGitOperation — no analytics call | mock 验证 |
|
||||
| detectGitCommitId — various formats | SHA/短 SHA/HEAD |
|
||||
| git operation tracking — edge cases | 空输入、畸形输入 |
|
||||
|
||||
---
|
||||
|
||||
## 排除清单
|
||||
|
||||
以下模块 **不纳入测试**，原因合理：
|
||||
|
||||
| 模块 | 行数 | 排除原因 |
|
||||
|------|------|---------|
|
||||
| `query.ts` | 1732 | 核心循环，40+ 依赖，需完整集成环境 |
|
||||
| `QueryEngine.ts` | 1320 | 编排器，30+ 依赖 |
|
||||
| `utils/hooks.ts` | 5121 | 51 exports，spawn 子进程 |
|
||||
| `utils/config.ts` | 1817 | 文件系统 + lockfile + 全局状态 |
|
||||
| `utils/auth.ts` | 2002 | 多 provider 认证，平台特定 |
|
||||
| `utils/fileHistory.ts` | 1115 | 重 I/O 文件备份 |
|
||||
| `utils/sessionRestore.ts` | 551 | 恢复状态涉及多个子系统 |
|
||||
| `utils/ripgrep.ts` | 679 | spawn 子进程 |
|
||||
| `utils/yaml.ts` | 15 | 两行 wrapper |
|
||||
| `utils/lockfile.ts` | 43 | trivial wrapper |
|
||||
| `screens/` / `components/` | — | Ink 渲染测试环境 |
|
||||
| `bridge/` / `remote/` / `ssh/` | — | 网络层 |
|
||||
| `daemon/` / `server/` | — | 进程管理 |
|
||||
|
||||
---
|
||||
|
||||
## 预期成果
|
||||
|
||||
| 指标 | Phase 16 后 | Phase 17 后 | Phase 18 后 |
|
||||
|------|-----------|-----------|-----------|
|
||||
| 测试数 | ~1417 | ~1567 | ~1597 |
|
||||
| 文件数 | 76 | 87 | 91 |
|
||||
| WEAK 文件 | 6 | 4 | **0** |
|
||||
435
docs/test-plans/phase19-batch1-micro-utils.md
Normal file
435
docs/test-plans/phase19-batch1-micro-utils.md
Normal file
@@ -0,0 +1,435 @@
|
||||
# Phase 19 - Batch 1: 零依赖微型 utils
|
||||
|
||||
> 预计 ~154 tests / 13 文件 | 全部纯函数，无需 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/utils/__tests__/semanticBoolean.test.ts` (~8 tests)
|
||||
|
||||
**源文件**: `src/utils/semanticBoolean.ts` (30 行)
|
||||
**依赖**: `zod/v4`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("semanticBoolean", () => {
|
||||
// 基本 Zod 行为
|
||||
test("parses boolean true to true")
|
||||
test("parses boolean false to false")
|
||||
test("parses string 'true' to true")
|
||||
test("parses string 'false' to false")
|
||||
// 边界
|
||||
test("rejects string 'TRUE' (case-sensitive)")
|
||||
test("rejects string 'FALSE' (case-sensitive)")
|
||||
test("rejects number 1")
|
||||
test("rejects null")
|
||||
test("rejects undefined")
|
||||
// 自定义 inner schema
|
||||
test("works with custom inner schema (z.boolean().optional())")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/utils/__tests__/semanticNumber.test.ts` (~10 tests)
|
||||
|
||||
**源文件**: `src/utils/semanticNumber.ts` (37 行)
|
||||
**依赖**: `zod/v4`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("semanticNumber", () => {
|
||||
test("parses number 42")
|
||||
test("parses number 0")
|
||||
test("parses negative number -5")
|
||||
test("parses float 3.14")
|
||||
test("parses string '42' to 42")
|
||||
test("parses string '-7.5' to -7.5")
|
||||
test("rejects string 'abc'")
|
||||
test("rejects empty string ''")
|
||||
test("rejects null")
|
||||
test("rejects boolean true")
|
||||
test("works with custom inner schema (z.number().int().min(0))")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/utils/__tests__/lazySchema.test.ts` (~6 tests)
|
||||
|
||||
**源文件**: `src/utils/lazySchema.ts` (9 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("lazySchema", () => {
|
||||
test("returns a function")
|
||||
test("calls factory on first invocation")
|
||||
test("returns cached result on subsequent invocations")
|
||||
test("factory is called only once (call count verification)")
|
||||
test("works with different return types")
|
||||
test("each call to lazySchema returns independent cache")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/utils/__tests__/withResolvers.test.ts` (~8 tests)
|
||||
|
||||
**源文件**: `src/utils/withResolvers.ts` (14 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("withResolvers", () => {
|
||||
test("returns object with promise, resolve, reject")
|
||||
test("promise resolves when resolve is called")
|
||||
test("promise rejects when reject is called")
|
||||
test("resolve passes value through")
|
||||
test("reject passes error through")
|
||||
test("promise is instanceof Promise")
|
||||
test("works with generic type parameter")
|
||||
test("resolve/reject can be called asynchronously")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/utils/__tests__/userPromptKeywords.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/userPromptKeywords.ts` (28 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("matchesNegativeKeyword", () => {
|
||||
test("matches 'wtf'")
|
||||
test("matches 'shit'")
|
||||
test("matches 'fucking broken'")
|
||||
test("does not match normal input like 'fix the bug'")
|
||||
test("is case-insensitive")
|
||||
test("matches partial word in sentence")
|
||||
})
|
||||
|
||||
describe("matchesKeepGoingKeyword", () => {
|
||||
test("matches exact 'continue'")
|
||||
test("matches 'keep going'")
|
||||
test("matches 'go on'")
|
||||
test("does not match 'cont'")
|
||||
test("does not match empty string")
|
||||
test("matches within larger sentence 'please continue'")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 6. `src/utils/__tests__/xdg.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/xdg.ts` (66 行)
|
||||
**依赖**: 无（通过 options 参数注入）
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("getXDGStateHome", () => {
|
||||
test("returns ~/.local/state by default")
|
||||
test("respects XDG_STATE_HOME env var")
|
||||
test("uses custom homedir from options")
|
||||
})
|
||||
|
||||
describe("getXDGCacheHome", () => {
|
||||
test("returns ~/.cache by default")
|
||||
test("respects XDG_CACHE_HOME env var")
|
||||
})
|
||||
|
||||
describe("getXDGDataHome", () => {
|
||||
test("returns ~/.local/share by default")
|
||||
test("respects XDG_DATA_HOME env var")
|
||||
})
|
||||
|
||||
describe("getUserBinDir", () => {
|
||||
test("returns ~/.local/bin")
|
||||
test("uses custom homedir from options")
|
||||
})
|
||||
|
||||
describe("resolveOptions", () => {
|
||||
test("defaults env to process.env")
|
||||
test("defaults homedir to os.homedir()")
|
||||
test("merges partial options")
|
||||
})
|
||||
|
||||
describe("path construction", () => {
|
||||
test("all paths end with correct subdirectory")
|
||||
test("respects HOME env via homedir override")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无（通过 options.env 和 options.homedir 注入）
|
||||
|
||||
---
|
||||
|
||||
## 7. `src/utils/__tests__/horizontalScroll.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/utils/horizontalScroll.ts` (138 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("calculateHorizontalScrollWindow", () => {
|
||||
// 基本场景
|
||||
test("all items fit within available width")
|
||||
test("single item selected within view")
|
||||
test("selected item at beginning")
|
||||
test("selected item at end")
|
||||
test("selected item beyond visible range scrolls right")
|
||||
test("selected item before visible range scrolls left")
|
||||
|
||||
// 箭头指示器
|
||||
test("showLeftArrow when items hidden on left")
|
||||
test("showRightArrow when items hidden on right")
|
||||
test("no arrows when all items visible")
|
||||
test("both arrows when items hidden on both sides")
|
||||
|
||||
// 边界条件
|
||||
test("empty itemWidths array")
|
||||
test("single item")
|
||||
test("available width is 0")
|
||||
test("item wider than available width")
|
||||
test("all items same width")
|
||||
test("varying item widths")
|
||||
test("firstItemHasSeparator adds separator width to first item")
|
||||
test("selectedIdx in middle of overflow")
|
||||
test("scroll snaps to show selected at left edge")
|
||||
test("scroll snaps to show selected at right edge")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 8. `src/utils/__tests__/generators.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/utils/generators.ts` (89 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("lastX", () => {
|
||||
test("returns last yielded value")
|
||||
test("returns only value from single-yield generator")
|
||||
test("throws on empty generator")
|
||||
})
|
||||
|
||||
describe("returnValue", () => {
|
||||
test("returns generator return value")
|
||||
test("returns undefined for void return")
|
||||
})
|
||||
|
||||
describe("toArray", () => {
|
||||
test("collects all yielded values")
|
||||
test("returns empty array for empty generator")
|
||||
test("preserves order")
|
||||
})
|
||||
|
||||
describe("fromArray", () => {
|
||||
test("yields all array elements")
|
||||
test("yields nothing for empty array")
|
||||
})
|
||||
|
||||
describe("all", () => {
|
||||
test("merges multiple generators preserving yield order")
|
||||
test("respects concurrency cap")
|
||||
test("handles empty generator array")
|
||||
test("handles single generator")
|
||||
test("handles generators of different lengths")
|
||||
test("yields all values from all generators")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无（用 fromArray 构造测试数据）
|
||||
|
||||
---
|
||||
|
||||
## 9. `src/utils/__tests__/sequential.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/sequential.ts` (57 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("sequential", () => {
|
||||
test("wraps async function, returns same result")
|
||||
test("single call resolves normally")
|
||||
test("concurrent calls execute sequentially (FIFO order)")
|
||||
test("preserves arguments correctly")
|
||||
test("error in first call does not block subsequent calls")
|
||||
test("preserves rejection reason")
|
||||
test("multiple args passed correctly")
|
||||
test("returns different wrapper for each call to sequential")
|
||||
test("handles rapid concurrent calls")
|
||||
test("execution order matches call order")
|
||||
test("works with functions returning different types")
|
||||
test("wrapper has same arity expectations")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 10. `src/utils/__tests__/fingerprint.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/fingerprint.ts` (77 行)
|
||||
**依赖**: `crypto` (内置)
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("FINGERPRINT_SALT", () => {
|
||||
test("has expected value '59cf53e54c78'")
|
||||
})
|
||||
|
||||
describe("extractFirstMessageText", () => {
|
||||
test("extracts text from first user message")
|
||||
test("extracts text from single user message with array content")
|
||||
test("returns empty string when no user messages")
|
||||
test("skips assistant messages")
|
||||
test("handles mixed content blocks (text + image)")
|
||||
})
|
||||
|
||||
describe("computeFingerprint", () => {
|
||||
test("returns deterministic 3-char hex string")
|
||||
test("same input produces same fingerprint")
|
||||
test("different message text produces different fingerprint")
|
||||
test("different version produces different fingerprint")
|
||||
test("handles short strings (length < 21)")
|
||||
test("handles empty string")
|
||||
test("fingerprint is valid hex")
|
||||
})
|
||||
|
||||
describe("computeFingerprintFromMessages", () => {
|
||||
test("end-to-end: messages -> fingerprint")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需要 `mock.module` 处理 `UserMessage`/`AssistantMessage` 类型依赖（查看实际 import 情况）
|
||||
|
||||
---
|
||||
|
||||
## 11. `src/utils/__tests__/configConstants.test.ts` (~8 tests)
|
||||
|
||||
**源文件**: `src/utils/configConstants.ts` (22 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("NOTIFICATION_CHANNELS", () => {
|
||||
test("contains expected channels")
|
||||
test("is readonly array")
|
||||
test("includes 'auto', 'iterm2', 'terminal_bell'")
|
||||
})
|
||||
|
||||
describe("EDITOR_MODES", () => {
|
||||
test("contains 'normal' and 'vim'")
|
||||
test("has exactly 2 entries")
|
||||
})
|
||||
|
||||
describe("TEAMMATE_MODES", () => {
|
||||
test("contains 'auto', 'tmux', 'in-process'")
|
||||
test("has exactly 3 entries")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 12. `src/utils/__tests__/directMemberMessage.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/directMemberMessage.ts` (70 行)
|
||||
**依赖**: 仅类型（可 mock）
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("parseDirectMemberMessage", () => {
|
||||
test("parses '@agent-name hello world'")
|
||||
test("parses '@agent-name single-word'")
|
||||
test("returns null for non-matching input")
|
||||
test("returns null for empty string")
|
||||
test("returns null for '@name' without message")
|
||||
test("handles hyphenated agent names like '@my-agent msg'")
|
||||
test("handles multiline message content")
|
||||
test("extracts correct recipientName and message")
|
||||
})
|
||||
|
||||
// sendDirectMemberMessage 需要 mock teamContext/writeToMailbox
|
||||
describe("sendDirectMemberMessage", () => {
|
||||
test("returns error when no team context")
|
||||
test("returns error for unknown recipient")
|
||||
test("calls writeToMailbox with correct args for valid recipient")
|
||||
test("returns success for valid message")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`sendDirectMemberMessage` 需要 mock `AppState['teamContext']` 和 `WriteToMailboxFn`
|
||||
|
||||
---
|
||||
|
||||
## 13. `src/utils/__tests__/collapseHookSummaries.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/collapseHookSummaries.ts` (60 行)
|
||||
**依赖**: 仅类型
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("collapseHookSummaries", () => {
|
||||
test("returns same messages when no hook summaries")
|
||||
test("collapses consecutive messages with same hookLabel")
|
||||
test("does not collapse messages with different hookLabels")
|
||||
test("aggregates hookCount across collapsed messages")
|
||||
test("merges hookInfos arrays")
|
||||
test("merges hookErrors arrays")
|
||||
test("takes max totalDurationMs")
|
||||
test("takes any truthy preventContinuation")
|
||||
test("leaves single hook summary unchanged")
|
||||
test("handles three consecutive same-label summaries")
|
||||
test("preserves non-hook messages in between")
|
||||
test("returns empty array for empty input")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需要构造 `RenderableMessage` mock 对象
|
||||
287
docs/test-plans/phase19-batch2-utils-state-commands.md
Normal file
287
docs/test-plans/phase19-batch2-utils-state-commands.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# Phase 19 - Batch 2: 更多 utils + state + commands
|
||||
|
||||
> 预计 ~120 tests / 8 文件 | 部分需轻量 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/utils/__tests__/collapseTeammateShutdowns.test.ts` (~10 tests)
|
||||
|
||||
**源文件**: `src/utils/collapseTeammateShutdowns.ts` (56 行)
|
||||
**依赖**: 仅类型
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("collapseTeammateShutdowns", () => {
|
||||
test("returns same messages when no teammate shutdowns")
|
||||
test("leaves single shutdown message unchanged")
|
||||
test("collapses consecutive shutdown messages into batch")
|
||||
test("batch attachment has correct count")
|
||||
test("does not collapse non-consecutive shutdowns")
|
||||
test("preserves non-shutdown messages between shutdowns")
|
||||
test("handles empty array")
|
||||
test("handles mixed message types")
|
||||
test("collapses more than 2 consecutive shutdowns")
|
||||
test("non-teammate task_status messages are not collapsed")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
构造 `RenderableMessage` mock 对象（带 `task_status` attachment，`status=completed`，`taskType=in_process_teammate`）
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/utils/__tests__/privacyLevel.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/privacyLevel.ts` (56 行)
|
||||
**依赖**: `process.env`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("getPrivacyLevel", () => {
|
||||
test("returns 'default' when no env vars set")
|
||||
test("returns 'essential-traffic' when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set")
|
||||
test("returns 'no-telemetry' when DISABLE_TELEMETRY is set")
|
||||
test("'essential-traffic' takes priority over 'no-telemetry'")
|
||||
})
|
||||
|
||||
describe("isEssentialTrafficOnly", () => {
|
||||
test("returns true for 'essential-traffic' level")
|
||||
test("returns false for 'default' level")
|
||||
test("returns false for 'no-telemetry' level")
|
||||
})
|
||||
|
||||
describe("isTelemetryDisabled", () => {
|
||||
test("returns true for 'no-telemetry' level")
|
||||
test("returns true for 'essential-traffic' level")
|
||||
test("returns false for 'default' level")
|
||||
})
|
||||
|
||||
describe("getEssentialTrafficOnlyReason", () => {
|
||||
test("returns env var name when restricted")
|
||||
test("returns null when unrestricted")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`process.env` 保存/恢复模式（参考现有 `envUtils.test.ts`）
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/utils/__tests__/textHighlighting.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/utils/textHighlighting.ts` (167 行)
|
||||
**依赖**: `@alcalzone/ansi-tokenize`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("segmentTextByHighlights", () => {
|
||||
// 基本
|
||||
test("returns single segment with no highlights")
|
||||
test("returns highlighted segment for single highlight")
|
||||
test("returns two segments for highlight covering middle portion")
|
||||
test("returns three segments for highlight in the middle")
|
||||
|
||||
// 多高亮
|
||||
test("handles non-overlapping highlights")
|
||||
test("handles overlapping highlights (priority-based)")
|
||||
test("handles adjacent highlights")
|
||||
|
||||
// 边界
|
||||
test("highlight starting at 0")
|
||||
test("highlight ending at text length")
|
||||
test("highlight covering entire text")
|
||||
test("empty text with highlights")
|
||||
test("empty highlights array returns single segment")
|
||||
|
||||
// ANSI 处理
|
||||
test("correctly segments text with ANSI escape codes")
|
||||
test("handles text with mixed ANSI and highlights")
|
||||
|
||||
// 属性
|
||||
test("preserves highlight color property")
|
||||
test("preserves highlight priority property")
|
||||
test("preserves dimColor and inverse flags")
|
||||
test("highlights with start > end are handled gracefully")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
可能需要 mock `@alcalzone/ansi-tokenize`，或直接使用（如果有安装）
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/utils/__tests__/detectRepository.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/detectRepository.ts` (179 行)
|
||||
**依赖**: git 命令（`getRemoteUrl`）
|
||||
|
||||
### 重点测试函数
|
||||
|
||||
**`parseGitRemote(input: string): ParsedRepository | null`** — 纯正则解析
|
||||
**`parseGitHubRepository(input: string): string | null`** — 纯函数
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("parseGitRemote", () => {
|
||||
// HTTPS
|
||||
test("parses HTTPS URL: https://github.com/owner/repo.git")
|
||||
test("parses HTTPS URL without .git suffix")
|
||||
test("parses HTTPS URL with subdirectory path (only takes first 2 segments)")
|
||||
|
||||
// SSH
|
||||
test("parses SSH URL: git@github.com:owner/repo.git")
|
||||
test("parses SSH URL without .git suffix")
|
||||
|
||||
// ssh://
|
||||
test("parses ssh:// URL: ssh://git@github.com/owner/repo.git")
|
||||
|
||||
// git://
|
||||
test("parses git:// URL")
|
||||
|
||||
// 边界
|
||||
test("returns null for invalid URL")
|
||||
test("returns null for empty string")
|
||||
test("handles GHE hostname")
|
||||
test("handles port number in URL")
|
||||
})
|
||||
|
||||
describe("parseGitHubRepository", () => {
|
||||
test("extracts 'owner/repo' from valid remote URL")
|
||||
test("handles plain 'owner/repo' string input")
|
||||
test("returns null for non-GitHub host (if restricted)")
|
||||
test("returns null for invalid input")
|
||||
test("is case-sensitive for owner/repo")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
仅测试 `parseGitRemote` 和 `parseGitHubRepository`（纯函数），不需要 mock git
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/utils/__tests__/markdown.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/utils/markdown.ts` (382 行)
|
||||
**依赖**: `marked`, `cli-highlight`, theme types
|
||||
|
||||
### 重点测试函数
|
||||
|
||||
**`padAligned(content, displayWidth, targetWidth, align)`** — 纯函数
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("padAligned", () => {
|
||||
test("left-aligns: pads with spaces on right")
|
||||
test("right-aligns: pads with spaces on left")
|
||||
test("center-aligns: pads with spaces on both sides")
|
||||
test("no padding when displayWidth equals targetWidth")
|
||||
test("handles content wider than targetWidth")
|
||||
test("null/undefined align defaults to left")
|
||||
test("handles empty string content")
|
||||
test("handles zero displayWidth")
|
||||
test("handles zero targetWidth")
|
||||
test("center alignment with odd padding distribution")
|
||||
})
|
||||
```
|
||||
|
||||
注意：`numberToLetter`/`numberToRoman`/`getListNumber` 是私有函数，除非从模块导出否则无法直接测试。如果确实私有，则通过 `applyMarkdown` 间接测试列表渲染：
|
||||
|
||||
```typescript
|
||||
describe("list numbering (via applyMarkdown)", () => {
|
||||
test("numbered list renders with digits")
|
||||
test("nested ordered list uses letters (a, b, c)")
|
||||
test("deep nested list uses roman numerals")
|
||||
test("unordered list uses bullet markers")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`padAligned` 无需 mock。`applyMarkdown` 可能需要 mock theme 依赖。
|
||||
|
||||
---
|
||||
|
||||
## 6. `src/state/__tests__/store.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/state/store.ts` (35 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("createStore", () => {
|
||||
test("returns object with getState, setState, subscribe")
|
||||
test("getState returns initial state")
|
||||
test("setState updates state via updater function")
|
||||
test("setState does not notify when state unchanged (Object.is)")
|
||||
test("setState notifies subscribers on change")
|
||||
test("subscribe returns unsubscribe function")
|
||||
test("unsubscribe stops notifications")
|
||||
test("multiple subscribers all get notified")
|
||||
test("onChange callback is called on state change")
|
||||
test("onChange is not called when state unchanged")
|
||||
test("works with complex state objects")
|
||||
test("works with primitive state")
|
||||
test("updater receives previous state")
|
||||
test("sequential setState calls produce final state")
|
||||
test("subscriber called after all state changes in synchronous batch")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 7. `src/commands/plugin/__tests__/parseArgs.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/commands/plugin/parseArgs.ts` (104 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("parsePluginArgs", () => {
|
||||
// 无参数
|
||||
test("returns { type: 'menu' } for undefined")
|
||||
test("returns { type: 'menu' } for empty string")
|
||||
test("returns { type: 'menu' } for whitespace only")
|
||||
|
||||
// help
|
||||
test("returns { type: 'help' } for 'help'")
|
||||
|
||||
// install
|
||||
test("parses 'install my-plugin' -> { type: 'install', name: 'my-plugin' }")
|
||||
test("parses 'install my-plugin@github' with marketplace")
|
||||
test("parses 'install https://github.com/...' as URL marketplace")
|
||||
|
||||
// uninstall
|
||||
test("returns { type: 'uninstall', name: '...' }")
|
||||
|
||||
// enable/disable
|
||||
test("returns { type: 'enable', name: '...' }")
|
||||
test("returns { type: 'disable', name: '...' }")
|
||||
|
||||
// validate
|
||||
test("returns { type: 'validate', name: '...' }")
|
||||
|
||||
// manage
|
||||
test("returns { type: 'manage' }")
|
||||
|
||||
// marketplace 子命令
|
||||
test("parses 'marketplace add ...'")
|
||||
test("parses 'marketplace remove ...'")
|
||||
test("parses 'marketplace list'")
|
||||
|
||||
// 边界
|
||||
test("handles extra whitespace")
|
||||
test("handles unknown subcommand gracefully")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
258
docs/test-plans/phase19-batch3-tool-submodules.md
Normal file
258
docs/test-plans/phase19-batch3-tool-submodules.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Phase 19 - Batch 3: Tool 子模块纯逻辑
|
||||
|
||||
> 预计 ~113 tests / 6 文件 | 采用 `mock.module()` + `await import()` 模式
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/tools/GrepTool/__tests__/headLimit.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/tools/GrepTool/GrepTool.ts` (578 行)
|
||||
**目标函数**: `applyHeadLimit<T>`, `formatLimitInfo` (非导出，需确认可测性)
|
||||
|
||||
### 测试策略
|
||||
如果函数是文件内导出的，直接 `await import()` 获取。如果私有，则通过 GrepTool 的输出间接测试，或提取到独立文件。
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("applyHeadLimit", () => {
|
||||
test("returns full array when limit is undefined (default 250)")
|
||||
test("applies limit correctly: limits to N items")
|
||||
test("limit=0 means no limit (returns all)")
|
||||
test("applies offset correctly")
|
||||
test("offset + limit combined")
|
||||
test("offset beyond array length returns empty")
|
||||
test("returns appliedLimit when truncation occurred")
|
||||
test("returns appliedLimit=undefined when no truncation")
|
||||
test("limit larger than array returns all items with appliedLimit=undefined")
|
||||
test("empty array returns empty with appliedLimit=undefined")
|
||||
test("offset=0 is default")
|
||||
test("negative limit behavior")
|
||||
})
|
||||
|
||||
describe("formatLimitInfo", () => {
|
||||
test("formats 'limit: N, offset: M' when both present")
|
||||
test("formats 'limit: N' when only limit")
|
||||
test("formats 'offset: M' when only offset")
|
||||
test("returns empty string when both undefined")
|
||||
test("handles limit=0 (no limit, should not appear)")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链（`log`, `slowOperations` 等），通过 `mock.module()` + `await import()` 只取目标函数
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/tools/MCPTool/__tests__/classifyForCollapse.test.ts` (~25 tests)
|
||||
|
||||
**源文件**: `src/tools/MCPTool/classifyForCollapse.ts` (605 行)
|
||||
**目标函数**: `classifyMcpToolForCollapse`, `normalize`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("normalize", () => {
|
||||
test("leaves snake_case unchanged: 'search_issues'")
|
||||
test("converts camelCase to snake_case: 'searchIssues' -> 'search_issues'")
|
||||
test("converts kebab-case to snake_case: 'search-issues' -> 'search_issues'")
|
||||
test("handles mixed: 'searchIssuesByStatus' -> 'search_issues_by_status'")
|
||||
test("handles already lowercase single word")
|
||||
test("handles empty string")
|
||||
test("handles PascalCase: 'SearchIssues' -> 'search_issues'")
|
||||
})
|
||||
|
||||
describe("classifyMcpToolForCollapse", () => {
|
||||
// 搜索工具
|
||||
test("classifies Slack search_messages as search")
|
||||
test("classifies GitHub search_code as search")
|
||||
test("classifies Linear search_issues as search")
|
||||
test("classifies Datadog search_logs as search")
|
||||
test("classifies Notion search as search")
|
||||
|
||||
// 读取工具
|
||||
test("classifies Slack get_message as read")
|
||||
test("classifies GitHub get_file_contents as read")
|
||||
test("classifies Linear get_issue as read")
|
||||
test("classifies Filesystem read_file as read")
|
||||
|
||||
// 双重分类
|
||||
test("some tools are both search and read")
|
||||
test("some tools are neither search nor read")
|
||||
|
||||
// 未知工具
|
||||
test("unknown tool returns { isSearch: false, isRead: false }")
|
||||
test("tool name with camelCase variant still matches")
|
||||
test("tool name with kebab-case variant still matches")
|
||||
|
||||
// server name 不影响分类
|
||||
test("server name parameter is accepted but unused in current logic")
|
||||
|
||||
// 边界
|
||||
test("empty tool name returns false/false")
|
||||
test("case sensitivity check (should match after normalize)")
|
||||
test("handles tool names with numbers")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
文件自包含（仅内部 Set + normalize 函数），需确认 `normalize` 是否导出
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/tools/FileReadTool/__tests__/blockedPaths.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/tools/FileReadTool/FileReadTool.ts` (1184 行)
|
||||
**目标函数**: `isBlockedDevicePath`, `getAlternateScreenshotPath`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("isBlockedDevicePath", () => {
|
||||
// 阻止的设备
|
||||
test("blocks /dev/zero")
|
||||
test("blocks /dev/random")
|
||||
test("blocks /dev/urandom")
|
||||
test("blocks /dev/full")
|
||||
test("blocks /dev/stdin")
|
||||
test("blocks /dev/tty")
|
||||
test("blocks /dev/console")
|
||||
test("blocks /dev/stdout")
|
||||
test("blocks /dev/stderr")
|
||||
test("blocks /dev/fd/0")
|
||||
test("blocks /dev/fd/1")
|
||||
test("blocks /dev/fd/2")
|
||||
|
||||
// 阻止 /proc
|
||||
test("blocks /proc/self/fd/0")
|
||||
test("blocks /proc/123/fd/2")
|
||||
|
||||
// 允许的路径
|
||||
test("allows /dev/null")
|
||||
test("allows regular file paths")
|
||||
test("allows /home/user/file.txt")
|
||||
})
|
||||
|
||||
describe("getAlternateScreenshotPath", () => {
|
||||
test("returns undefined for path without AM/PM")
|
||||
test("returns alternate path for macOS screenshot with regular space before AM")
|
||||
test("returns alternate path for macOS screenshot with U+202F before PM")
|
||||
test("handles path without time component")
|
||||
test("handles multiple AM/PM occurrences")
|
||||
test("returns undefined when no space variant difference")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链，通过 `await import()` 获取函数
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/tools/AgentTool/__tests__/agentDisplay.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/tools/AgentTool/agentDisplay.ts` (105 行)
|
||||
**目标函数**: `resolveAgentOverrides`, `compareAgentsByName`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("resolveAgentOverrides", () => {
|
||||
test("marks no overrides when all agents active")
|
||||
test("marks inactive agent as overridden")
|
||||
test("overriddenBy shows the overriding agent source")
|
||||
test("deduplicates agents by (agentType, source)")
|
||||
test("preserves agent definition properties")
|
||||
test("handles empty arrays")
|
||||
test("handles agent from git worktree (duplicate detection)")
|
||||
})
|
||||
|
||||
describe("compareAgentsByName", () => {
|
||||
test("sorts alphabetically ascending")
|
||||
test("returns negative when a.name < b.name")
|
||||
test("returns positive when a.name > b.name")
|
||||
test("returns 0 for same name")
|
||||
test("is case-sensitive")
|
||||
})
|
||||
|
||||
describe("AGENT_SOURCE_GROUPS", () => {
|
||||
test("contains expected source groups in order")
|
||||
test("has unique labels")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `AgentDefinition`, `AgentSource` 类型依赖
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/tools/AgentTool/__tests__/agentToolUtils.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/tools/AgentTool/agentToolUtils.ts` (688 行)
|
||||
**目标函数**: `countToolUses`, `getLastToolUseName`, `extractPartialResult`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("countToolUses", () => {
|
||||
test("counts tool_use blocks in messages")
|
||||
test("returns 0 for messages without tool_use")
|
||||
test("returns 0 for empty array")
|
||||
test("counts multiple tool_use blocks across messages")
|
||||
test("counts tool_use in single message with multiple blocks")
|
||||
})
|
||||
|
||||
describe("getLastToolUseName", () => {
|
||||
test("returns last tool name from assistant message")
|
||||
test("returns undefined for message without tool_use")
|
||||
test("returns the last tool when multiple tool_uses present")
|
||||
test("handles message with non-array content")
|
||||
})
|
||||
|
||||
describe("extractPartialResult", () => {
|
||||
test("extracts text from last assistant message")
|
||||
test("returns undefined for messages without assistant content")
|
||||
test("handles interrupted agent with partial text")
|
||||
test("returns undefined for empty messages")
|
||||
test("concatenates multiple text blocks")
|
||||
test("skips non-text content blocks")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 消息类型依赖
|
||||
|
||||
---
|
||||
|
||||
## 6. `src/tools/SkillTool/__tests__/skillSafety.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/tools/SkillTool/SkillTool.ts` (1110 行)
|
||||
**目标函数**: `skillHasOnlySafeProperties`, `extractUrlScheme`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("skillHasOnlySafeProperties", () => {
|
||||
test("returns true for command with only safe properties")
|
||||
test("returns true for command with undefined extra properties")
|
||||
test("returns false for command with unsafe meaningful property")
|
||||
test("returns true for command with null extra properties")
|
||||
test("returns true for command with empty array extra property")
|
||||
test("returns true for command with empty object extra property")
|
||||
test("returns false for command with non-empty unsafe array")
|
||||
test("returns false for command with non-empty unsafe object")
|
||||
test("returns true for empty command object")
|
||||
})
|
||||
|
||||
describe("extractUrlScheme", () => {
|
||||
test("extracts 'gs' from 'gs://bucket/path'")
|
||||
test("extracts 'https' from 'https://example.com'")
|
||||
test("extracts 'http' from 'http://example.com'")
|
||||
test("extracts 's3' from 's3://bucket/path'")
|
||||
test("defaults to 'gs' for unknown scheme")
|
||||
test("defaults to 'gs' for path without scheme")
|
||||
test("defaults to 'gs' for empty string")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链，`await import()` 获取函数
|
||||
215
docs/test-plans/phase19-batch4-services.md
Normal file
215
docs/test-plans/phase19-batch4-services.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Phase 19 - Batch 4: Services 纯逻辑
|
||||
|
||||
> 预计 ~84 tests / 5 文件 | 部分需轻量 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/services/compact/__tests__/grouping.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/services/compact/grouping.ts` (64 行)
|
||||
**目标函数**: `groupMessagesByApiRound`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("groupMessagesByApiRound", () => {
|
||||
test("returns single group for single API round")
|
||||
test("splits at new assistant message ID")
|
||||
test("keeps tool_result messages with their parent assistant message")
|
||||
test("handles streaming chunks (same assistant ID stays grouped)")
|
||||
test("returns empty array for empty input")
|
||||
test("handles all user messages (no assistant)")
|
||||
test("handles alternating assistant IDs")
|
||||
test("three API rounds produce three groups")
|
||||
test("user messages before first assistant go in first group")
|
||||
test("consecutive user messages stay in same group")
|
||||
test("does not produce empty groups")
|
||||
test("handles single message")
|
||||
test("preserves message order within groups")
|
||||
test("handles system messages")
|
||||
test("tool_result after assistant stays in same round")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需构造 `Message` mock 对象（type: 'user'/'assistant', message: { id, content }）
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/services/compact/__tests__/stripMessages.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/services/compact/compact.ts` (1709 行)
|
||||
**目标函数**: `stripImagesFromMessages`, `collectReadToolFilePaths` (私有)
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("stripImagesFromMessages", () => {
|
||||
// user 消息处理
|
||||
test("replaces image block with [image] text")
|
||||
test("replaces document block with [document] text")
|
||||
test("preserves text blocks unchanged")
|
||||
test("handles multiple image/document blocks in single message")
|
||||
test("returns original message when no media blocks")
|
||||
|
||||
// tool_result 内嵌套
|
||||
test("replaces image inside tool_result content")
|
||||
test("replaces document inside tool_result content")
|
||||
test("preserves non-media tool_result content")
|
||||
|
||||
// 非用户消息
|
||||
test("passes through assistant messages unchanged")
|
||||
test("passes through system messages unchanged")
|
||||
|
||||
// 边界
|
||||
test("handles empty message array")
|
||||
test("handles string content (non-array) in user message")
|
||||
test("does not mutate original messages")
|
||||
})
|
||||
|
||||
describe("collectReadToolFilePaths", () => {
|
||||
// 注意：这是私有函数，可能需要通过 stripImagesFromMessages 或其他导出间接测试
|
||||
// 如果不可直接测试，则跳过或通过集成测试覆盖
|
||||
test("collects file_path from Read tool_use blocks")
|
||||
test("skips tool_use with FILE_UNCHANGED_STUB result")
|
||||
test("returns empty set for messages without Read tool_use")
|
||||
test("handles multiple Read calls across messages")
|
||||
test("normalizes paths via expandPath")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `expandPath`（如果 collectReadToolFilePaths 要测）
|
||||
需 mock `log`, `slowOperations` 等重依赖
|
||||
构造 `Message` mock 对象
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/services/compact/__tests__/prompt.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/services/compact/prompt.ts` (375 行)
|
||||
**目标函数**: `formatCompactSummary`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("formatCompactSummary", () => {
|
||||
test("strips <analysis>...</analysis> block")
|
||||
test("replaces <summary>...</summary> with 'Summary:\\n' prefix")
|
||||
test("handles analysis + summary together")
|
||||
test("handles summary without analysis")
|
||||
test("handles analysis without summary")
|
||||
test("collapses multiple newlines to double")
|
||||
test("trims leading/trailing whitespace")
|
||||
test("handles empty string")
|
||||
test("handles plain text without tags")
|
||||
test("handles multiline analysis content")
|
||||
test("preserves content between analysis and summary")
|
||||
test("handles nested-like tags gracefully")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链（`log`, feature flags 等）
|
||||
`formatCompactSummary` 是纯字符串处理，如果 import 链不太重则无需复杂 mock
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/services/mcp/__tests__/channelPermissions.test.ts` (~25 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/channelPermissions.ts` (241 行)
|
||||
**目标函数**: `hashToId`, `shortRequestId`, `truncateForPreview`, `filterPermissionRelayClients`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("hashToId", () => {
|
||||
test("returns 5-char string")
|
||||
test("uses only letters a-z excluding 'l'")
|
||||
test("is deterministic (same input = same output)")
|
||||
test("different inputs produce different outputs (with high probability)")
|
||||
test("handles empty string")
|
||||
})
|
||||
|
||||
describe("shortRequestId", () => {
|
||||
test("returns 5-char string from tool use ID")
|
||||
test("is deterministic")
|
||||
test("avoids profanity substrings (retries with salt)")
|
||||
test("returns a valid ID even if all retries hit bad words (unlikely)")
|
||||
})
|
||||
|
||||
describe("truncateForPreview", () => {
|
||||
test("returns JSON string for object input")
|
||||
test("truncates to <=200 chars when input is long")
|
||||
test("adds ellipsis or truncation indicator")
|
||||
test("returns short input unchanged")
|
||||
test("handles string input")
|
||||
test("handles null/undefined input")
|
||||
})
|
||||
|
||||
describe("filterPermissionRelayClients", () => {
|
||||
test("keeps connected clients in allowlist with correct capabilities")
|
||||
test("filters out disconnected clients")
|
||||
test("filters out clients not in allowlist")
|
||||
test("filters out clients missing required capabilities")
|
||||
test("returns empty array for empty input")
|
||||
test("type predicate narrows correctly")
|
||||
})
|
||||
|
||||
describe("PERMISSION_REPLY_RE", () => {
|
||||
test("matches 'y abcde'")
|
||||
test("matches 'yes abcde'")
|
||||
test("matches 'n abcde'")
|
||||
test("matches 'no abcde'")
|
||||
test("is case-insensitive")
|
||||
test("does not match without ID")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`hashToId` 可能需要确认导出状态
|
||||
`filterPermissionRelayClients` 需要 mock 客户端类型
|
||||
`truncateForPreview` 可能依赖 `jsonStringify`（需 mock `slowOperations`）
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/services/mcp/__tests__/officialRegistry.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/officialRegistry.ts` (73 行)
|
||||
**目标函数**: `normalizeUrl` (私有), `isOfficialMcpUrl`, `resetOfficialMcpUrlsForTesting`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("normalizeUrl", () => {
|
||||
// 注意：如果是私有的，通过 isOfficialMcpUrl 间接测试
|
||||
test("removes trailing slash")
|
||||
test("removes query parameters")
|
||||
test("preserves path")
|
||||
test("handles URL with port")
|
||||
test("handles URL with hash fragment")
|
||||
})
|
||||
|
||||
describe("isOfficialMcpUrl", () => {
|
||||
test("returns false when registry not loaded (initial state)")
|
||||
test("returns true for URL added to registry")
|
||||
test("returns false for non-registered URL")
|
||||
test("uses normalized URL for comparison")
|
||||
})
|
||||
|
||||
describe("resetOfficialMcpUrlsForTesting", () => {
|
||||
test("clears the cached URLs")
|
||||
test("allows fresh start after reset")
|
||||
})
|
||||
|
||||
describe("URL normalization + lookup integration", () => {
|
||||
test("URL with trailing slash matches normalized version")
|
||||
test("URL with query params matches normalized version")
|
||||
test("different URLs do not match")
|
||||
test("case sensitivity check")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `axios`（避免网络请求）
|
||||
使用 `resetOfficialMcpUrlsForTesting` 做测试隔离
|
||||
200
docs/test-plans/phase19-batch5-mcp-config.md
Normal file
200
docs/test-plans/phase19-batch5-mcp-config.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Phase 19 - Batch 5: MCP 配置 + modelCost
|
||||
|
||||
> 预计 ~80 tests / 4 文件 | 需中等 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/services/mcp/__tests__/configUtils.test.ts` (~30 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/config.ts` (1580 行)
|
||||
**目标函数**: `unwrapCcrProxyUrl`, `urlPatternToRegex` (私有), `commandArraysMatch` (私有), `toggleMembership` (私有), `addScopeToServers` (私有), `dedupPluginMcpServers`, `getMcpServerSignature` (如导出)
|
||||
|
||||
### 测试策略
|
||||
私有函数如不可直接测试，通过公开的 `dedupPluginMcpServers` 间接覆盖。导出函数直接测。
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("unwrapCcrProxyUrl", () => {
|
||||
test("returns original URL when no CCR proxy markers")
|
||||
test("extracts mcp_url from CCR proxy URL with /v2/session_ingress/shttp/mcp/")
|
||||
test("extracts mcp_url from CCR proxy URL with /v2/ccr-sessions/")
|
||||
test("returns original URL when mcp_url param is missing")
|
||||
test("handles malformed URL gracefully")
|
||||
test("handles URL with both proxy marker and mcp_url")
|
||||
test("preserves non-CCR URLs unchanged")
|
||||
})
|
||||
|
||||
describe("dedupPluginMcpServers", () => {
|
||||
test("keeps unique plugin servers")
|
||||
test("suppresses plugin server duplicated by manual config")
|
||||
test("suppresses plugin server duplicated by earlier plugin")
|
||||
test("keeps servers with null signature")
|
||||
test("returns empty for empty inputs")
|
||||
test("reports suppressed with correct duplicateOf name")
|
||||
test("handles multiple plugins with same config")
|
||||
})
|
||||
|
||||
describe("toggleMembership (via integration)", () => {
|
||||
test("adds item when shouldContain=true and not present")
|
||||
test("removes item when shouldContain=false and present")
|
||||
test("returns same array when already in desired state")
|
||||
})
|
||||
|
||||
describe("addScopeToServers (via integration)", () => {
|
||||
test("adds scope to each server config")
|
||||
test("returns empty object for undefined input")
|
||||
test("returns empty object for empty input")
|
||||
test("preserves all original config properties")
|
||||
})
|
||||
|
||||
describe("urlPatternToRegex (via integration)", () => {
|
||||
test("matches exact URL")
|
||||
test("matches wildcard pattern *.example.com")
|
||||
test("matches multiple wildcards")
|
||||
test("does not match non-matching URL")
|
||||
test("escapes regex special characters in pattern")
|
||||
})
|
||||
|
||||
describe("commandArraysMatch (via integration)", () => {
|
||||
test("returns true for identical arrays")
|
||||
test("returns false for different lengths")
|
||||
test("returns false for same length different elements")
|
||||
test("returns true for empty arrays")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `feature()` (bun:bundle), `jsonStringify`, `safeParseJSON`, `log` 等
|
||||
通过 `mock.module()` + `await import()` 解锁
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/services/mcp/__tests__/filterUtils.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/utils.ts` (576 行)
|
||||
**目标函数**: `filterToolsByServer`, `hashMcpConfig`, `isToolFromMcpServer`, `isMcpTool`, `parseHeaders`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("filterToolsByServer", () => {
|
||||
test("filters tools matching server name prefix")
|
||||
test("returns empty for no matching tools")
|
||||
test("handles empty tools array")
|
||||
test("normalizes server name for matching")
|
||||
})
|
||||
|
||||
describe("hashMcpConfig", () => {
|
||||
test("returns 16-char hex string")
|
||||
test("is deterministic")
|
||||
test("excludes scope from hash")
|
||||
test("different configs produce different hashes")
|
||||
test("key order does not affect hash (sorted)")
|
||||
})
|
||||
|
||||
describe("isToolFromMcpServer", () => {
|
||||
test("returns true when tool belongs to specified server")
|
||||
test("returns false for different server")
|
||||
test("returns false for non-MCP tool name")
|
||||
test("handles empty tool name")
|
||||
})
|
||||
|
||||
describe("isMcpTool", () => {
|
||||
test("returns true for tool name starting with 'mcp__'")
|
||||
test("returns true when tool.isMcp is true")
|
||||
test("returns false for regular tool")
|
||||
test("returns false when neither condition met")
|
||||
})
|
||||
|
||||
describe("parseHeaders", () => {
|
||||
test("parses 'Key: Value' format")
|
||||
test("parses multiple headers")
|
||||
test("trims whitespace around key and value")
|
||||
test("throws on missing colon")
|
||||
test("throws on empty key")
|
||||
test("handles value with colons (like URLs)")
|
||||
test("returns empty object for empty array")
|
||||
test("handles duplicate keys (last wins)")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `normalizeNameForMCP`, `mcpInfoFromString`, `jsonStringify`, `createHash` 等
|
||||
`parseHeaders` 是最独立的，可能不需要太多 mock
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/services/mcp/__tests__/channelNotification.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/channelNotification.ts` (317 行)
|
||||
**目标函数**: `wrapChannelMessage`, `findChannelEntry`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("wrapChannelMessage", () => {
|
||||
test("wraps content in <channel> tag with source attribute")
|
||||
test("escapes server name in attribute")
|
||||
test("includes meta attributes when provided")
|
||||
test("escapes meta values via escapeXmlAttr")
|
||||
test("filters out meta keys not matching SAFE_META_KEY pattern")
|
||||
test("handles empty meta")
|
||||
test("handles content with special characters")
|
||||
test("formats with newlines between tags and content")
|
||||
})
|
||||
|
||||
describe("findChannelEntry", () => {
|
||||
test("finds server entry by exact name match")
|
||||
test("finds plugin entry by matching second segment")
|
||||
test("returns undefined for no match")
|
||||
test("handles empty channels array")
|
||||
test("handles server name without colon")
|
||||
test("handles 'plugin:name' format correctly")
|
||||
test("prefers exact match over partial match")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `escapeXmlAttr`（来自 xml.ts，已有测试）或直接使用
|
||||
`CHANNEL_TAG` 常量需确认导出
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/utils/__tests__/modelCost.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/modelCost.ts` (232 行)
|
||||
**目标函数**: `formatModelPricing`, `COST_TIER_*` 常量
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("COST_TIER constants", () => {
|
||||
test("COST_TIER_3_15 has inputTokens=3, outputTokens=15")
|
||||
test("COST_TIER_15_75 has inputTokens=15, outputTokens=75")
|
||||
test("COST_TIER_5_25 has inputTokens=5, outputTokens=25")
|
||||
test("COST_TIER_30_150 has inputTokens=30, outputTokens=150")
|
||||
test("COST_HAIKU_35 has inputTokens=0.8, outputTokens=4")
|
||||
test("COST_HAIKU_45 has inputTokens=1, outputTokens=5")
|
||||
})
|
||||
|
||||
describe("formatModelPricing", () => {
|
||||
test("formats integer prices without decimals: '$3/$15 per Mtok'")
|
||||
test("formats float prices with 2 decimals: '$0.80/$4.00 per Mtok'")
|
||||
test("formats mixed: '$5/$25 per Mtok'")
|
||||
test("formats large prices: '$30/$150 per Mtok'")
|
||||
test("formats $1/$5 correctly (integer but small)")
|
||||
test("handles zero prices: '$0/$0 per Mtok'")
|
||||
})
|
||||
|
||||
describe("MODEL_COSTS", () => {
|
||||
test("maps known model names to cost tiers")
|
||||
test("contains entries for claude-sonnet-4-6")
|
||||
test("contains entries for claude-opus-4-6")
|
||||
test("contains entries for claude-haiku-4-5")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `log`, `slowOperations` 等重依赖（modelCost.ts 通常 import 链较重）
|
||||
`formatModelPricing` 和 `COST_TIER_*` 是纯数据/纯函数，mock 成功后直接测
|
||||
296
docs/testing-spec.md
Normal file
296
docs/testing-spec.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Testing Specification
|
||||
|
||||
本文档定义 claude-code 项目的测试规范、当前覆盖状态和改进计划。
|
||||
|
||||
## 1. 技术栈
|
||||
|
||||
| 项 | 选型 |
|
||||
|----|------|
|
||||
| 测试框架 | `bun:test` |
|
||||
| 断言/Mock | `bun:test` 内置 |
|
||||
| 覆盖率 | `bun test --coverage` |
|
||||
| CI | GitHub Actions，push/PR 到 main 自动运行 |
|
||||
|
||||
## 2. 测试层次
|
||||
|
||||
本项目采用 **单元测试 + 集成测试** 两层结构，不做 E2E 或快照测试。
|
||||
|
||||
- **单元测试** — 纯函数、工具类、解析器。文件就近放置于 `src/**/__tests__/`。
|
||||
- **集成测试** — 多模块协作流程。集中于 `tests/integration/`。
|
||||
|
||||
## 3. 文件结构与命名
|
||||
|
||||
```
|
||||
src/
|
||||
├── utils/__tests__/ # 纯函数单元测试
|
||||
├── tools/<Tool>/__tests__/ # Tool 单元测试
|
||||
├── services/mcp/__tests__/ # MCP 单元测试
|
||||
├── utils/permissions/__tests__/
|
||||
├── utils/model/__tests__/
|
||||
├── utils/settings/__tests__/
|
||||
├── utils/shell/__tests__/
|
||||
├── utils/git/__tests__/
|
||||
└── __tests__/ # 顶层模块测试 (Tool.ts, tools.ts)
|
||||
tests/
|
||||
├── integration/ # 集成测试（尚未创建）
|
||||
├── mocks/ # 共享 mock/fixture（尚未创建）
|
||||
└── helpers/ # 测试辅助函数
|
||||
```
|
||||
|
||||
- 测试文件：`<module>.test.ts`
|
||||
- 命名风格：`describe("functionName")` + `test("行为描述")`，英文
|
||||
- 编写原则：Arrange-Act-Assert、单一职责、独立性、边界覆盖
|
||||
|
||||
## 4. 当前覆盖状态
|
||||
|
||||
> 更新日期：2026-04-02 | **1623 tests, 84 files, 0 fail, 851ms**
|
||||
|
||||
### 4.1 可靠度评分
|
||||
|
||||
每个测试文件按断言深度、边界覆盖、mock 质量、测试独立性综合评定：
|
||||
|
||||
| 等级 | 含义 |
|
||||
|------|------|
|
||||
| **GOOD** | 断言精确（exact match），边界充分，结构清晰 |
|
||||
| **ACCEPTABLE** | 正常路径覆盖完整，部分边界或断言可加强 |
|
||||
| **WEAK** | 存在明显缺陷：断言过弱、重要边界缺失、或有脆弱性风险 |
|
||||
|
||||
### 4.2 按模块分布
|
||||
|
||||
#### P0 — 核心模块
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `src/__tests__/Tool.test.ts` | 20 | GOOD | buildTool, toolMatchesName, findToolByName, filterToolProgressMessages | — |
|
||||
| `src/__tests__/tools.test.ts` | 9 | ACCEPTABLE | parseToolPreset, filterToolsByDenyRules | 预设覆盖仅测 "default"；有冗余用例 |
|
||||
| `src/tools/FileEditTool/__tests__/utils.test.ts` | 22 | ACCEPTABLE | normalizeQuotes, applyEditToFile, preserveQuoteStyle | `findActualString` 断言过弱（`not.toBeNull`）；`preserveQuoteStyle` 仅 2 用例 |
|
||||
| `src/tools/shared/__tests__/gitOperationTracking.test.ts` | 20 | ACCEPTABLE | parseGitCommitId, detectGitOperation | 6 个 GH PR action 全覆盖；缺 `trackGitOperations` 测试（需 mock analytics） |
|
||||
| `src/tools/BashTool/__tests__/destructiveCommandWarning.test.ts` | 21 | ACCEPTABLE | git/rm/SQL/k8s/terraform 危险模式 | safe commands 4 断言合一；缺少 `rm -rf /`、`DROP DATABASE`、管道命令 |
|
||||
| `src/tools/BashTool/__tests__/commandSemantics.test.ts` | 10 | ACCEPTABLE | grep/diff/test/rg/find 退出码语义 | mock `splitCommand_DEPRECATED` 与实现可能分歧；覆盖可更全面 |
|
||||
|
||||
**Utils 纯函数（19 文件）：**
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `utils/__tests__/array.test.ts` | 12 | GOOD | intersperse, count, uniq | — |
|
||||
| `utils/__tests__/set.test.ts` | 11 | GOOD | difference, intersects, every, union | — |
|
||||
| `utils/__tests__/xml.test.ts` | 9 | GOOD | escapeXml, escapeXmlAttr | 缺 null/undefined 输入测试 |
|
||||
| `utils/__tests__/hash.test.ts` | 12 | ACCEPTABLE | djb2Hash, hashContent, hashPair | `hashContent`/`hashPair` 无已知答案断言（仅测确定性） |
|
||||
| `utils/__tests__/stringUtils.test.ts` | 30 | GOOD | 10 个函数全覆盖，含 Unicode 边界 | — |
|
||||
| `utils/__tests__/semver.test.ts` | 16 | ACCEPTABLE | gt/gte/lt/lte/satisfies/order | 缺 pre-release、tilde range、畸形版本串 |
|
||||
| `utils/__tests__/uuid.test.ts` | 6 | ACCEPTABLE | validateUuid | 大写测试仅 `not.toBeNull`，未验证标准化输出 |
|
||||
| `utils/__tests__/format.test.ts` | 27 | GOOD | formatFileSize, formatDuration, formatNumber, formatTokens, formatRelativeTime | 全部 `toBe` 精确匹配，含 billions/weeks/days 边界 |
|
||||
| `utils/__tests__/frontmatterParser.test.ts` | 22 | GOOD | parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter | — |
|
||||
| `utils/__tests__/file.test.ts` | 13 | ACCEPTABLE | convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix | `addLineNumbers` 仅 `toContain`；缺 Windows 路径分隔符测试 |
|
||||
| `utils/__tests__/glob.test.ts` | 6 | ACCEPTABLE | extractGlobBaseDirectory | 缺绝对路径、根 `/`、Windows 路径 |
|
||||
| `utils/__tests__/diff.test.ts` | 8 | ACCEPTABLE | adjustHunkLineNumbers, getPatchFromContents | `getPatchFromContents` 仅检查结构，未验证 diff 内容正确性 |
|
||||
| `utils/__tests__/json.test.ts` | 15 | GOOD | safeParseJSON, parseJSONL, addItemToJSONCArray | — |
|
||||
| `utils/__tests__/truncate.test.ts` | 18 | ACCEPTABLE | truncateToWidth, wrapText, truncatePathMiddle | **缺 CJK/emoji/wide-char 测试**（这是宽度感知实现的核心场景） |
|
||||
| `utils/__tests__/path.test.ts` | 15 | ACCEPTABLE | containsPathTraversal, normalizePathForConfigKey | 仅覆盖 2/5+ 导出函数 |
|
||||
| `utils/__tests__/tokens.test.ts` | 18 | GOOD | getTokenCountFromUsage, doesMostRecentAssistantMessageExceed200k 等 | — |
|
||||
| `utils/__tests__/stream.test.ts` | 15 | GOOD | Stream\<T\> enqueue/read/drain/next/done/error/for-await | — |
|
||||
| `utils/__tests__/abortController.test.ts` | 13 | GOOD | createAbortController/createChildAbortController 父子传播 | — |
|
||||
| `utils/__tests__/bufferedWriter.test.ts` | 10 | GOOD | createBufferedWriter 立即/缓冲/flush/overflow | — |
|
||||
| `utils/__tests__/gitDiff.test.ts` | 25 | GOOD | parseGitNumstat/parseGitDiff/parseShortstat 纯解析 | — |
|
||||
| `utils/__tests__/sliceAnsi.test.ts` | 13 | GOOD | sliceAnsi ANSI 感知切片 + undoAnsiCodes | — |
|
||||
| `utils/__tests__/treeify.test.ts` | 13 | ACCEPTABLE | treeify 扁平/嵌套/循环引用 | 缺深度嵌套性能测试 |
|
||||
| `utils/__tests__/words.test.ts` | 11 | GOOD | slug 格式 (adjective-verb-noun)、唯一性 | — |
|
||||
|
||||
**Context 构建（3 文件）：**
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `utils/__tests__/claudemd.test.ts` | 14 | ACCEPTABLE | stripHtmlComments, isMemoryFilePath, getLargeMemoryFiles | **仅测 3 个辅助函数**，核心发现/加载/`@include` 指令/memoization 未覆盖 |
|
||||
| `utils/__tests__/systemPrompt.test.ts` | 8 | GOOD | buildEffectiveSystemPrompt | — |
|
||||
| `__tests__/history.test.ts` | 26 | GOOD | parseReferences/expandPastedTextRefs/formatPastedTextRef 等 5 个函数 | — |
|
||||
|
||||
#### P1 — 重要模块
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `permissions/__tests__/permissionRuleParser.test.ts` | 16 | GOOD | escape/unescape 规则，roundtrip 完整性 | — |
|
||||
| `permissions/__tests__/permissions.test.ts` | 12 | ACCEPTABLE | getDenyRuleForTool, getAskRuleForTool, filterDeniedAgents | `as any` cast；缺 MCP tool deny 测试 |
|
||||
| `permissions/__tests__/shellRuleMatching.test.ts` | 19 | GOOD | 通配符、转义、正则特殊字符 | — |
|
||||
| `permissions/__tests__/PermissionMode.test.ts` | 22 | ACCEPTABLE | permissionModeFromString, isExternalPermissionMode 等 | isExternalPermissionMode ant false 路径已覆盖；缺 `bubble` 模式独立测试 |
|
||||
| `permissions/__tests__/dangerousPatterns.test.ts` | 7 | WEAK | CROSS_PLATFORM_CODE_EXEC, DANGEROUS_BASH_PATTERNS | 纯数据 smoke test，无行为测试；不验证数组无重复 |
|
||||
| `model/__tests__/aliases.test.ts` | 15 | ACCEPTABLE | isModelAlias, isModelFamilyAlias | 缺 null/undefined/空串输入 |
|
||||
| `model/__tests__/model.test.ts` | 13 | ACCEPTABLE | firstPartyNameToCanonical | 缺空串、非标准日期后缀 |
|
||||
| `model/__tests__/providers.test.ts` | 9 | ACCEPTABLE | getAPIProvider, isFirstPartyAnthropicBaseUrl | `originalEnv` 声明未使用；env 恢复不完整 |
|
||||
| `utils/__tests__/messages.test.ts` | 36 | GOOD | createAssistantMessage, createUserMessage, extractTag 等 16 个 describe | `normalizeMessages` 仅检查长度未验证内容 |
|
||||
|
||||
**Tool 子模块（8 文件）：**
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `tools/PowerShellTool/__tests__/powershellSecurity.test.ts` | 24 | GOOD | AST 安全检测：Invoke-Expression/iex/encoded/dynamic/download/COM | — |
|
||||
| `tools/PowerShellTool/__tests__/commandSemantics.test.ts` | 21 | GOOD | grep/rg/findstr/robocopy 退出码、pipeline last-segment | — |
|
||||
| `tools/PowerShellTool/__tests__/destructiveCommandWarning.test.ts` | 38 | GOOD | Remove-Item/Format-Volume/Clear-Disk/git/SQL/COMPUTER/alias 全覆盖 | — |
|
||||
| `tools/PowerShellTool/__tests__/gitSafety.test.ts` | 29 | GOOD | .git 路径检测/NTFS 短名/反斜杠/引号/反引号转义 | — |
|
||||
| `tools/LSPTool/__tests__/formatters.test.ts` | 18 | GOOD | 全部 8 个 format 函数 null/empty/valid 输入 | — |
|
||||
| `tools/LSPTool/__tests__/schemas.test.ts` | 13 | GOOD | isValidLSPOperation 类型守卫 9 种操作 + 无效/空/大小写 | — |
|
||||
| `tools/WebFetchTool/__tests__/preapproved.test.ts` | 18 | GOOD | isPreapprovedHost 精确/路径作用域/子路径/大小写/子域名 | — |
|
||||
| `tools/WebFetchTool/__tests__/urlValidation.test.ts` | 18 | GOOD | validateURL/isPermittedRedirect 本地重实现（避免重依赖链） | — |
|
||||
|
||||
#### P2 — 补充模块
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `utils/__tests__/cron.test.ts` | 31 | GOOD | parseCronExpression, computeNextCronRun, cronToHuman | 缺月边界、闰年 |
|
||||
| `utils/__tests__/git.test.ts` | 15 | ACCEPTABLE | normalizeGitRemoteUrl (SSH/HTTPS/ssh://) | 缺 git://、file://、端口号 |
|
||||
| `settings/__tests__/config.test.ts` | 38 | GOOD | SettingsSchema, type guards, validateSettingsFileContent, formatZodError | 缺 DeniedMcpServerEntrySchema |
|
||||
|
||||
#### P3-P6 — 扩展覆盖（27 文件）
|
||||
|
||||
| 文件 | Tests | 评分 | 备注 |
|
||||
|------|-------|------|------|
|
||||
| `utils/__tests__/errors.test.ts` | 33 | GOOD | — |
|
||||
| `utils/__tests__/envUtils.test.ts` | 33 | GOOD | env 保存/恢复规范 |
|
||||
| `utils/__tests__/effort.test.ts` | 30 | GOOD | 5 个 mock 模块，边界完整 |
|
||||
| `utils/__tests__/argumentSubstitution.test.ts` | 22 | ACCEPTABLE | 缺转义引号、越界索引 |
|
||||
| `utils/__tests__/sanitization.test.ts` | 14 | ACCEPTABLE | — |
|
||||
| `utils/__tests__/sleep.test.ts` | 14 | GOOD | 时间相关测试，margin 充足 |
|
||||
| `utils/__tests__/CircularBuffer.test.ts` | 11 | ACCEPTABLE | 缺 capacity=1、空 buffer getRecent |
|
||||
| `utils/__tests__/memoize.test.ts` | 18 | GOOD | 缓存 hit/stale/LRU 全覆盖 |
|
||||
| `utils/__tests__/tokenBudget.test.ts` | 21 | GOOD | — |
|
||||
| `utils/__tests__/displayTags.test.ts` | 17 | GOOD | — |
|
||||
| `utils/__tests__/taggedId.test.ts` | 10 | GOOD | — |
|
||||
| `utils/__tests__/controlMessageCompat.test.ts` | 15 | GOOD | — |
|
||||
| `utils/__tests__/gitConfigParser.test.ts` | 21 | GOOD | — |
|
||||
| `utils/__tests__/windowsPaths.test.ts` | 19 | GOOD | 双向 round-trip 测试 |
|
||||
| `utils/__tests__/envExpansion.test.ts` | 15 | GOOD | — |
|
||||
| `utils/__tests__/formatBriefTimestamp.test.ts` | 10 | GOOD | 固定 now 时间戳，确定性 |
|
||||
| `utils/__tests__/notebook.test.ts` | 9 | ACCEPTABLE | 合并断言偏弱 |
|
||||
| `utils/__tests__/hyperlink.test.ts` | 10 | ACCEPTABLE | 空串测试行为注释混乱 |
|
||||
| `utils/__tests__/zodToJsonSchema.test.ts` | 9 | WEAK | **object 属性仅 `toBeDefined` 未验证类型**；optional 字段未验证 absence |
|
||||
| `utils/__tests__/objectGroupBy.test.ts` | 5 | ACCEPTABLE | 极简，缺 undefined key 测试 |
|
||||
| `utils/__tests__/contentArray.test.ts` | 6 | ACCEPTABLE | 缺混合 tool_result+text 交替 |
|
||||
| `utils/__tests__/slashCommandParsing.test.ts` | 8 | GOOD | — |
|
||||
| `utils/__tests__/groupToolUses.test.ts` | 10 | GOOD | — |
|
||||
| `utils/__tests__/shell/__tests__/outputLimits.test.ts` | 7 | ACCEPTABLE | — |
|
||||
| `utils/__tests__/envValidation.test.ts` | 12 | GOOD | validateBoundedIntEnvVar | value=1 无下界确认为设计意图（函数仅校验 >0 和 <=upperLimit） |
|
||||
| `utils/git/__tests__/gitConfigParser.test.ts` | 20 | GOOD | — |
|
||||
| `services/mcp/__tests__/mcpStringUtils.test.ts` | 16 | GOOD | — |
|
||||
| `services/mcp/__tests__/normalization.test.ts` | 10 | GOOD | — |
|
||||
|
||||
### 4.3 评分汇总
|
||||
|
||||
| 等级 | 文件数 | 占比 |
|
||||
|------|--------|------|
|
||||
| **GOOD** | 46 | 55% |
|
||||
| **ACCEPTABLE** | 32 | 38% |
|
||||
| **WEAK** | 6 | 7% |
|
||||
|
||||
## 5. 系统性问题
|
||||
|
||||
### 5.1 断言过弱（Smell: `toContain` 代替精确匹配）
|
||||
|
||||
以下文件的部分测试使用 `toContain` 或 `not.toBeNull` 检查结果，当实现返回包含目标子串的任何字符串时测试仍通过，无法检测格式错误：
|
||||
|
||||
| 文件 | 受影响函数 | 建议 |
|
||||
|------|-----------|------|
|
||||
| `file.test.ts` | addLineNumbers | 断言完整输出格式 |
|
||||
| `diff.test.ts` | getPatchFromContents | 验证 hunk 内容正确性 |
|
||||
| `notebook.test.ts` | mapNotebookCellsToToolResult | 验证合并后内容 |
|
||||
| `uuid.test.ts` | validateUuid (uppercase) | 断言标准化后的精确值 |
|
||||
|
||||
### 5.2 集成测试空白
|
||||
|
||||
Spec 定义的三个集成测试均未创建：
|
||||
|
||||
| 计划 | 状态 | 依赖 |
|
||||
|------|------|------|
|
||||
| `tests/integration/tool-chain.test.ts` | 未创建 | 需 mock tools.ts 完整注册链 |
|
||||
| `tests/integration/context-build.test.ts` | 未创建 | 需 mock context.ts 重依赖链 |
|
||||
| `tests/integration/message-pipeline.test.ts` | 未创建 | 需 mock API 层 |
|
||||
|
||||
`tests/mocks/` 目录也不存在，无共享 mock/fixture 基础设施。
|
||||
|
||||
### 5.3 Mock 相关
|
||||
|
||||
| 问题 | 影响文件 | 说明 |
|
||||
|------|----------|------|
|
||||
| 未 mock 重依赖 | `gitOperationTracking.test.ts` | `trackGitOperations` 调用 analytics/bootstrap，测试仅覆盖 `detectGitOperation`（无副作用） |
|
||||
| env 恢复不完整 | `providers.test.ts` | 仅删除已知 key，新增 env var 会导致测试泄漏 |
|
||||
|
||||
### 5.4 潜在 Bug
|
||||
|
||||
| 文件 | 函数 | 问题 |
|
||||
|------|------|------|
|
||||
| ~~`envValidation.test.ts`~~ | ~~validateBoundedIntEnvVar~~ | ~~value=1 无下界检查~~ — **已确认**：函数仅校验 `parsed > 0` 和 `parsed <= upperLimit`，不强制 `parsed >= defaultValue`，为设计意图 |
|
||||
|
||||
### 5.5 已知限制
|
||||
|
||||
| 模块 | 问题 |
|
||||
|------|------|
|
||||
| `Bun.JSONL.parseChunk` | 畸形行时无限挂起（Bun 1.3.10 bug） |
|
||||
| `context.ts` 核心逻辑 | 依赖 bootstrap/state + git + 50+ 模块，mock 不可行 |
|
||||
| `tools.ts` (getAllBaseTools) | 导入链过重 |
|
||||
| `spawnMultiAgent.ts` | 50+ 依赖 |
|
||||
| `messages.ts` 部分函数 | 依赖 `getFeatureValue_CACHED_MAY_BE_STALE` |
|
||||
| UI 组件 (`screens/`, `components/`) | 需 Ink 渲染测试环境 |
|
||||
|
||||
### 5.6 Mock 模式
|
||||
|
||||
通过 `mock.module()` + `await import()` 解锁重依赖模块：
|
||||
|
||||
| 被 Mock 模块 | 解锁的测试 |
|
||||
|-------------|-----------|
|
||||
| `src/utils/log.ts` | json, tokens, FileEditTool/utils, permissions, memoize, PermissionMode |
|
||||
| `src/services/tokenEstimation.ts` | tokens |
|
||||
| `src/utils/slowOperations.ts` | tokens, permissions, memoize, PermissionMode |
|
||||
| `src/utils/debug.ts` | envValidation, outputLimits |
|
||||
| `src/utils/bash/commands.ts` | commandSemantics |
|
||||
| `src/utils/thinking.js` | effort |
|
||||
| `src/utils/settings/settings.js` | effort |
|
||||
| `src/utils/auth.js` | effort |
|
||||
| `src/services/analytics/growthbook.js` | effort, tokenBudget |
|
||||
| `src/utils/powershell/dangerousCmdlets.js` | powershellSecurity |
|
||||
| `src/utils/cwd.js` | gitSafety |
|
||||
| `src/utils/powershell/parser.js` | gitSafety |
|
||||
| `src/utils/stringUtils.js` | LSP formatters |
|
||||
| `figures` | treeify |
|
||||
|
||||
**约束**：`mock.module()` 必须在每个测试文件内联调用，不能从共享 helper 导入。
|
||||
|
||||
## 6. 完成状态
|
||||
|
||||
> 更新日期：2026-04-02 | **1623 tests, 84 files, 0 fail, 851ms**
|
||||
|
||||
### 已完成
|
||||
|
||||
| 计划 | 状态 | 新增测试 | 说明 |
|
||||
|------|------|---------|------|
|
||||
| Plan 12 — Mock 可靠性 | **已完成** | +9 | PermissionMode ant false 路径、providers env 快照恢复 |
|
||||
| Plan 10 — WEAK 修复 | **已完成** | +15 | format 断言精确化、envValidation 修正、zodToJsonSchema/destructors/notebook 加固 |
|
||||
| Plan 13 — CJK/Emoji | **已完成** | +17 | truncate CJK/emoji 宽度感知测试 |
|
||||
| Plan 11 — ACCEPTABLE 加强 | **已完成** | +62 | diff/uuid/hash/semver/path/claudemd/fileEdit/providers/messages 等 15 文件 |
|
||||
| Plan 14 — 集成测试 | **已完成** | +43 | 搭建 tests/mocks/ + tool-chain/context-build/message-pipeline/cli-arguments |
|
||||
| Plan 15 — CLI + 覆盖率 | **已完成** | +11 | Commander.js 参数解析、覆盖率基线 |
|
||||
| Phase 16 — 零依赖纯函数 | **已完成** | +126 | stream/abortController/bufferedWriter/gitDiff/history/sliceAnsi/treeify/words 8 文件 |
|
||||
| Phase 17 — 工具子模块 | **已完成** | +179 | PowerShell 安全/语义/破坏性/gitSafety + LSP 格式化/schema + WebFetch 预批准/URL 8 文件 |
|
||||
| Phase 18 — WEAK 修复 | **已完成** | +20 | format 精确匹配、envValidation 边界、PermissionMode 补强、gitOperationTracking PR actions |
|
||||
|
||||
### 覆盖率基线
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 总测试数 | 1623 |
|
||||
| 测试文件数 | 84 |
|
||||
| 失败数 | 0 |
|
||||
| 断言数 | 2516 |
|
||||
| 运行耗时 | ~851ms |
|
||||
| Tool.ts 行覆盖率 | 100% |
|
||||
| 整体行覆盖率 | ~33%（Bun coverage 限制：`mock.module` 模式下的模块不报告） |
|
||||
|
||||
> **注意**：Bun `--coverage` 仅报告测试 import 链中直接加载的文件。使用 `mock.module()` + `await import()` 模式的源文件（大多数 `src/utils/` 纯函数）不显示在覆盖率报告中。实际测试覆盖率高于报告值。
|
||||
|
||||
### 不纳入计划
|
||||
|
||||
| 模块 | 原因 |
|
||||
|------|------|
|
||||
| `query.ts` / `QueryEngine.ts` | 核心循环，需完整集成环境 |
|
||||
| `services/api/claude.ts` | 需 mock SDK 流式响应 |
|
||||
| `spawnMultiAgent.ts` | 50+ 依赖 |
|
||||
| `modelCost.ts` | 依赖 bootstrap/state + analytics |
|
||||
| `mcp/dateTimeParser.ts` | 调用 Haiku API |
|
||||
| `screens/` / `components/` | 需 Ink 渲染测试 |
|
||||
220
docs/tools/file-operations.mdx
Normal file
220
docs/tools/file-operations.mdx
Normal file
@@ -0,0 +1,220 @@
|
||||
---
|
||||
title: "文件操作工具 - 三大工具的源码级解剖"
|
||||
description: "逆向分析 FileRead、FileEdit、FileWrite 三大工具的完整执行链路：去重缓存、AST 安全编辑、原子性读写、文件历史快照的实现细节。"
|
||||
keywords: ["文件操作", "FileRead", "FileEdit", "FileWrite", "代码编辑", "原子写入"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码层面解剖三大文件工具的完整执行链路 */}
|
||||
|
||||
## 三大工具的职责分化
|
||||
|
||||
Claude Code 将文件操作拆分为三个独立工具——这不是功能划分，而是**风险分级**：
|
||||
|
||||
| 工具 | 权限级别 | 核心方法 | 关键属性 |
|
||||
|------|---------|---------|---------|
|
||||
| **Read** | 只读（免审批） | `isReadOnly() → true` | `maxResultSizeChars: Infinity` |
|
||||
| **Edit** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |
|
||||
| **Write** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |
|
||||
|
||||
<Tip>
|
||||
Read 的 `maxResultSizeChars` 是 `Infinity`，但这并不意味着无限制输出——真正的截断发生在 `validateContentTokens()` 中基于 token 预算的动态判定，而非字符数硬限制。
|
||||
</Tip>
|
||||
|
||||
## FileRead：多模态文件读取引擎
|
||||
|
||||
源码路径：`src/tools/FileReadTool/FileReadTool.ts`
|
||||
|
||||
### 读取去重机制
|
||||
|
||||
Read 工具有一个常被忽视但至关重要的**去重层**。当 AI 重复读取同一个文件的同一范围时，系统不会浪费 token 发送两份完整内容：
|
||||
|
||||
```typescript
|
||||
// FileReadTool.ts:530-573 — 去重逻辑
|
||||
const existingState = readFileState.get(fullFilePath)
|
||||
if (existingState && !existingState.isPartialView && existingState.offset !== undefined) {
|
||||
const rangeMatch = existingState.offset === offset && existingState.limit === limit
|
||||
if (rangeMatch) {
|
||||
const mtimeMs = await getFileModificationTimeAsync(fullFilePath)
|
||||
if (mtimeMs === existingState.timestamp) {
|
||||
return { data: { type: 'file_unchanged', file: { filePath: file_path } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关键设计点：
|
||||
- 去重仅对 **Read 工具自身的读取**生效（通过 `offset !== undefined` 判定）
|
||||
- Edit/Write 也会写入 `readFileState`，但它们的 `offset` 为 `undefined`，所以不会误命中去重
|
||||
- 通过 mtime 比对确保文件未被外部修改
|
||||
- 有 GrowthBook killswitch（`tengu_read_dedup_killswitch`）可紧急关闭
|
||||
|
||||
实测数据：BQ proxy 显示约 18% 的 Read 调用是同文件碰撞，占 fleet `cache_creation` 的 2.64%。
|
||||
|
||||
### 多格式分发：文本、图片、PDF、Notebook 四条路径
|
||||
|
||||
Read 工具的 `callInner()` 按 `ext` 分发到四条完全不同的处理路径：
|
||||
|
||||
```
|
||||
.ipynb → readNotebook() → JSON cell 解析 → token 校验
|
||||
.png/.jpg/.gif/.webp → readImageWithTokenBudget() → 压缩+降采样
|
||||
.pdf → extractPDFPages() / readPDF() → 页面级提取
|
||||
其他 → readFileInRange() → 分页读取
|
||||
```
|
||||
|
||||
**图片路径的压缩策略**特别精细：
|
||||
1. 先用 `maybeResizeAndDownsampleImageBuffer()` 标准缩放
|
||||
2. 用 `base64.length * 0.125` 估算 token 数
|
||||
3. 超出预算时调用 `compressImageBufferWithTokenLimit()` 激进压缩
|
||||
4. 仍然超限时用 sharp 做最后兜底：`resize(400,400).jpeg({quality:20})`
|
||||
|
||||
**PDF 路径**有页数阈值：超过 `PDF_AT_MENTION_INLINE_THRESHOLD`（默认值在 `apiLimits.ts`）时强制分页读取，每请求最多 `PDF_MAX_PAGES_PER_READ` 页。
|
||||
|
||||
### 安全防线
|
||||
|
||||
Read 工具在 `validateInput()` 中设置了多层安全门：
|
||||
|
||||
1. **设备文件屏蔽**（`BLOCKED_DEVICE_PATHS`）：`/dev/zero`、`/dev/random`、`/dev/tty` 等——防止无限输出或阻塞挂起
|
||||
2. **二进制文件拒绝**（`hasBinaryExtension`）：排除 PDF 和图片扩展名后，阻止读取 `.exe`、`.so` 等二进制文件
|
||||
3. **UNC 路径跳过**：Windows 下 `\\server\share` 路径跳过文件系统操作，防止 SMB NTLM 凭据泄露
|
||||
4. **权限拒绝规则**（`matchingRuleForInput`）：匹配 `deny` 规则后直接拒绝
|
||||
|
||||
### 文件未找到时的智能建议
|
||||
|
||||
当文件不存在时，Read 不会只报一个 "file not found"：
|
||||
|
||||
```typescript
|
||||
// FileReadTool.ts:639-647
|
||||
const similarFilename = findSimilarFile(fullFilePath) // 相似扩展名
|
||||
const cwdSuggestion = await suggestPathUnderCwd(fullFilePath) // cwd 相对路径建议
|
||||
// macOS 截图特殊处理：薄空格(U+202F) vs 普通空格
|
||||
const altPath = getAlternateScreenshotPath(fullFilePath)
|
||||
```
|
||||
|
||||
对 macOS 截图文件名中 AM/PM 前的薄空格（U+202F）做了特殊处理——这是实测中发现的跨 macOS 版本兼容性问题。
|
||||
|
||||
## FileEdit：精确字符串替换引擎
|
||||
|
||||
源码路径：`src/tools/FileEditTool/FileEditTool.ts` + `utils.ts`
|
||||
|
||||
### 引号标准化：AI 无法输出的字符怎么办
|
||||
|
||||
AI 模型只能输出直引号（`'` `"`），但源码中可能使用弯引号（`'` `'` `"` `"`）。`findActualString()` 函数处理了这个不对齐：
|
||||
|
||||
```typescript
|
||||
// utils.ts:73-93
|
||||
export function findActualString(fileContent: string, searchString: string): string | null {
|
||||
if (fileContent.includes(searchString)) return searchString // 精确匹配
|
||||
const normalizedSearch = normalizeQuotes(searchString) // 弯引号→直引号
|
||||
const normalizedFile = normalizeQuotes(fileContent)
|
||||
const idx = normalizedFile.indexOf(normalizedSearch)
|
||||
if (idx !== -1) return fileContent.substring(idx, idx + searchString.length)
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
匹配后还有**反向引号保持**（`preserveQuoteStyle`）：如果文件用弯引号，替换后的新字符串也自动转换为弯引号，包括缩写中的撇号（如 "don't"）。
|
||||
|
||||
### 原子性读-改-写
|
||||
|
||||
Edit 工具的 `call()` 方法实现了一个**无锁原子更新**协议：
|
||||
|
||||
```
|
||||
1. await fs.mkdir(dir) ← 确保目录存在（异步，在临界区外）
|
||||
2. await fileHistoryTrackEdit() ← 备份旧内容（异步，在临界区外）
|
||||
3. readFileSyncWithMetadata() ← 同步读取当前文件内容（临界区开始）
|
||||
4. getFileModificationTime() ← mtime 校验
|
||||
5. findActualString() ← 引号标准化匹配
|
||||
6. getPatchForEdit() ← 计算 diff
|
||||
7. writeTextContent() ← 写入磁盘
|
||||
8. readFileState.set() ← 更新缓存（临界区结束）
|
||||
```
|
||||
|
||||
步骤 3-8 之间**不允许任何异步操作**（源码注释明确写道："Please avoid async operations between here and writing to disk to preserve atomicity"）。这确保了在 mtime 校验和实际写入之间不会有其他进程修改文件。
|
||||
|
||||
### 防覆写校验
|
||||
|
||||
Edit 工具在 `validateInput()` 中检查两个条件：
|
||||
1. **必须先读取**（`readFileState` 中有记录且不是局部视图）
|
||||
2. **文件未被外部修改**（`mtime` 未变，或全量读取时内容完全一致）
|
||||
|
||||
```typescript
|
||||
// FileEditTool.ts:290-311 — Windows 特殊处理
|
||||
const isFullRead = readTimestamp.offset === undefined && readTimestamp.limit === undefined
|
||||
if (isFullRead && fileContent === readTimestamp.content) {
|
||||
// 内容不变，安全继续（Windows 云同步/杀毒可能改 mtime）
|
||||
}
|
||||
```
|
||||
|
||||
Windows 上的 mtime 可能因云同步、杀毒软件等被修改而不改变内容，因此对全量读取做了内容级比对作为兜底。
|
||||
|
||||
### 编辑大小限制
|
||||
|
||||
```typescript
|
||||
const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB
|
||||
```
|
||||
|
||||
超过 1 GiB 的文件直接拒绝编辑——这是 V8 字符串长度限制（~2^30 字符）的安全边界。
|
||||
|
||||
## FileWrite：全量写入与创建
|
||||
|
||||
源码路径：`src/tools/FileWriteTool/FileWriteTool.ts`
|
||||
|
||||
Write 工具与 Edit 共享大部分基础设施（权限检查、mtime 校验、fileHistory 备份），但有两个关键差异：
|
||||
|
||||
### 行尾处理
|
||||
|
||||
```typescript
|
||||
// FileWriteTool.ts:300-305 — 关键注释
|
||||
// Write is a full content replacement — the model sent explicit line endings
|
||||
// in `content` and meant them. Do not rewrite them.
|
||||
writeTextContent(fullFilePath, content, enc, 'LF')
|
||||
```
|
||||
|
||||
Write 工具始终使用 `LF` 行尾。早期版本会保留旧文件的行尾或采样仓库行尾风格，但这导致 Linux 上 bash 脚本被注入 `\r`——现在 AI 发什么行尾就用什么行尾。
|
||||
|
||||
### 输出区分
|
||||
|
||||
Write 工具返回 `type: 'create' | 'update'`：
|
||||
- `create`：文件不存在，`originalFile: null`
|
||||
- `update`：文件存在且被覆盖，`structuredPatch` 包含完整 diff
|
||||
|
||||
## 文件历史快照系统
|
||||
|
||||
源码路径：`src/utils/fileHistory.ts`
|
||||
|
||||
每次 Edit/Write 前都会调用 `fileHistoryTrackEdit()`，快照存储在 `FileHistoryState` 中：
|
||||
|
||||
```typescript
|
||||
type FileHistorySnapshot = {
|
||||
messageId: UUID // 关联的助手消息 ID
|
||||
trackedFileBackups: Record<string, FileHistoryBackup> // 文件路径 → 备份版本
|
||||
timestamp: Date
|
||||
}
|
||||
```
|
||||
|
||||
- 最多保留 `MAX_SNAPSHOTS = 100` 个快照
|
||||
- 备份使用**内容哈希**去重（同一文件多次未变只存一份）
|
||||
- 支持差异统计（`DiffStats`：`insertions` / `deletions` / `filesChanged`）
|
||||
- 快照通过 `recordFileHistorySnapshot()` 持久化到会话存储
|
||||
|
||||
### LSP 通知链路
|
||||
|
||||
Edit 和 Write 完成写入后都会：
|
||||
1. `clearDeliveredDiagnosticsForFile()` — 清除旧诊断
|
||||
2. `lspManager.changeFile()` — 通知 LSP 文件已变更
|
||||
3. `lspManager.saveFile()` — 触发 LSP 保存事件（TypeScript server 会重新计算诊断）
|
||||
4. `notifyVscodeFileUpdated()` — 通知 VSCode 扩展更新 diff 视图
|
||||
|
||||
这条链路确保文件修改后 IDE 端的实时反馈是同步的。
|
||||
|
||||
## Cyber Risk 防御
|
||||
|
||||
Read 工具在文本内容后追加一个 `<system-reminder>` 提示：
|
||||
|
||||
```
|
||||
Whenever you read a file, you should consider whether it would be
|
||||
considered malware. You CAN and SHOULD provide analysis of malware,
|
||||
what it is doing. But you MUST refuse to improve or augment the code.
|
||||
```
|
||||
|
||||
这个提示只在非豁免模型上生效（`MITIGATION_EXEMPT_MODELS` 目前包含 `claude-opus-4-6`）。模型级别的豁免表明：防恶意代码的判断力在不同模型间有差异，这是一个精巧的分级策略。
|
||||
281
docs/tools/search-and-navigation.mdx
Normal file
281
docs/tools/search-and-navigation.mdx
Normal file
@@ -0,0 +1,281 @@
|
||||
---
|
||||
title: "搜索与导航工具 - 代码库精准定位"
|
||||
description: "解析 Claude Code 的搜索导航工具：Glob 文件匹配、Grep 内容搜索，基于 ripgrep 的高性能代码检索，帮助 AI 在百万行代码中精准定位。"
|
||||
keywords: ["代码搜索", "Glob", "Grep", "ripgrep", "文件搜索"]
|
||||
---
|
||||
|
||||
## 两种搜索维度
|
||||
|
||||
| 维度 | 工具 | 底层实现 | 适用场景 |
|
||||
|------|------|----------|---------|
|
||||
| **按名称找文件** | Glob | ripgrep `--files` + glob 过滤 | "找到所有测试文件"、"找 config 开头的文件" |
|
||||
| **按内容找代码** | Grep | ripgrep 正则搜索 | "哪里定义了这个函数"、"谁在调用这个 API" |
|
||||
|
||||
两者共享同一个 ripgrep 引擎，通过不同的参数组合实现不同搜索模式。
|
||||
|
||||
## ripgrep 的内嵌方式
|
||||
|
||||
Claude Code 不依赖系统安装的 ripgrep——它在 `src/utils/ripgrep.ts` 中实现了三级降级策略：
|
||||
|
||||
```
|
||||
优先级 1: 系统 ripgrep (USE_BUILTIN_RIPGREP=false)
|
||||
→ 使用 PATH 中的 rg 二进制
|
||||
→ 安全考虑：只用命令名 'rg'，不用完整路径，防止 PATH 劫持
|
||||
|
||||
优先级 2: 内嵌模式 (bundled/native build)
|
||||
→ process.execPath 自身，argv0='rg'
|
||||
→ Bun 将 rg 静态编译进二进制，通过 argv0 分发
|
||||
|
||||
优先级 3: vendor 目录 (npm build)
|
||||
→ vendor/ripgrep/{arch}-{platform}/rg
|
||||
→ macOS 需要 codesign 签名 + 移除 quarantine xattr
|
||||
```
|
||||
|
||||
平台适配示例：
|
||||
```
|
||||
vendor/ripgrep/
|
||||
├── x86_64-darwin/rg # macOS Intel
|
||||
├── arm64-darwin/rg # macOS Apple Silicon
|
||||
├── x86_64-linux/rg # Linux Intel
|
||||
├── arm64-linux/rg # Linux ARM
|
||||
└── x86_64-win32/rg.exe # Windows
|
||||
```
|
||||
|
||||
### macOS 代码签名
|
||||
|
||||
vendor 模式下的 rg 二进制需要 ad-hoc 签名才能通过 Gatekeeper（`codesignRipgrepIfNecessary()`）：
|
||||
|
||||
```typescript
|
||||
// 首次使用时执行：
|
||||
// 1. 检查是否已是有效签名
|
||||
codesign -vv -d <rg-path>
|
||||
// 2. 如果只是 linker-signed，重新签名
|
||||
codesign --sign - --force --preserve-metadata=entitlements,requirements,flags,runtime <rg-path>
|
||||
// 3. 移除隔离属性
|
||||
xattr -d com.apple.quarantine <rg-path>
|
||||
```
|
||||
|
||||
## 搜索结果的设计考量
|
||||
|
||||
### head_limit 与 Token 预算
|
||||
|
||||
大型项目的搜索结果可能有数十万条。默认最多返回 250 条匹配——这不是随意选择，而是**token 预算**的约束：
|
||||
|
||||
- 每条匹配行约 50-100 token
|
||||
- 250 条 ≈ 12,500-25,000 token
|
||||
- 这大约占 200k 上下文窗口的 6-12%
|
||||
- 超过这个比例，AI 的推理质量会下降
|
||||
|
||||
Grep 工具的 `head_limit` 参数让 AI 可以按需调整——搜索小项目时可以用更大的值。
|
||||
|
||||
### 按修改时间排序
|
||||
|
||||
Glob 默认把**最近修改的文件排在前面**。这不是默认的文件系统排序，而是刻意的设计决策：
|
||||
|
||||
```
|
||||
设计假设：最近修改的文件最可能与当前任务相关
|
||||
实际效果：AI 优先看到"活"的代码，而不是沉寂的历史文件
|
||||
```
|
||||
|
||||
在 `src/tools/GlobTool/` 中，ripgrep 的输出在返回给 AI 前按 mtime 排序。
|
||||
|
||||
### ripgrep 的错误处理
|
||||
|
||||
ripgrep 执行有专门的错误恢复链（`src/utils/ripgrep.ts`）：
|
||||
|
||||
| 错误 | 处理 |
|
||||
|------|------|
|
||||
| **EAGAIN**（资源不足） | 自动以单线程模式 `-j 1` 重试 |
|
||||
| **超时**（默认 20s，WSL 60s） | 返回已有部分结果，丢弃可能不完整的最后一行 |
|
||||
| **缓冲区溢出** | 截断到 20MB，返回已收集的结果 |
|
||||
| **SIGTERM 失效** | 5 秒后升级为 SIGKILL |
|
||||
|
||||
## ToolSearch：在 50+ 工具中发现目标
|
||||
|
||||
当可用工具超过 50 个时（含 MCP 提供的外部工具），AI 可能不知道该用哪个。**ToolSearch**（`src/tools/ToolSearchTool/`）提供了工具发现机制。
|
||||
|
||||
### 搜索算法
|
||||
|
||||
ToolSearch 实现了基于关键词的加权搜索（`searchToolsWithKeywords()`）：
|
||||
|
||||
```
|
||||
输入: query = "database connection"
|
||||
↓
|
||||
1. 精确匹配: 检查是否有工具名完全匹配（快速路径）
|
||||
2. MCP 前缀匹配: "mcp__postgres" → 匹配所有 postgres 相关工具
|
||||
3. 关键词拆分: ["database", "connection"]
|
||||
4. 工具名解析:
|
||||
- MCP 工具: "mcp__server__action" → ["server", "action"]
|
||||
- 普通工具: "FileEditTool" → ["file", "edit", "tool"]
|
||||
5. 加权评分:
|
||||
- 工具名精确匹配: 10 分（MCP: 12 分）
|
||||
- 工具名部分匹配: 5 分（MCP: 6 分）
|
||||
- searchHint 匹配: 4 分
|
||||
- 描述匹配: 2 分
|
||||
6. 必选词过滤: "+database" 前缀表示必须包含
|
||||
7. 按分数排序，返回 top-N
|
||||
```
|
||||
|
||||
### `select:` 直接选择
|
||||
|
||||
AI 也可以用 `select:ToolName` 精确选择已知工具。这比搜索更快，且支持逗号分隔的批量选择（`select:A,B,C`）。
|
||||
|
||||
### 延迟加载（Deferred Tools）
|
||||
|
||||
不是所有工具都常驻内存。MCP 工具和低频工具被标记为 `isDeferredTool`，只有在 ToolSearch 选中后才真正加载。这减少了每次 API 调用的 token 开销（工具描述占用大量 token）。
|
||||
|
||||
### 缓存策略
|
||||
|
||||
工具描述的获取是 memoized 的——只在延迟工具集合变化时清除缓存：
|
||||
|
||||
```typescript
|
||||
// 工具名排序后拼接作为缓存 key
|
||||
function getDeferredToolsCacheKey(deferredTools: Tools): string {
|
||||
return deferredTools.map(t => t.name).sort().join(',')
|
||||
}
|
||||
```
|
||||
|
||||
## Web 搜索与抓取
|
||||
|
||||
AI 的信息获取不局限于本地代码：
|
||||
|
||||
- **WebSearch**（`src/tools/WebSearchTool/`）：调用 Anthropic API 的 `web_search_20250305` server tool 搜索互联网
|
||||
- **WebFetch**（`src/tools/WebFetchTool/`）：抓取特定 URL 内容，转换为 Markdown 供 AI 阅读
|
||||
|
||||
这让 AI 可以查阅文档、搜索 Stack Overflow、阅读 GitHub issue——和人类开发者的工作方式一致。
|
||||
|
||||
### WebSearch 实现机制
|
||||
|
||||
WebSearch 通过适配器模式支持两种搜索后端，由 `src/tools/WebSearchTool/adapters/` 中的工厂函数 `createAdapter()` 选择：
|
||||
|
||||
```
|
||||
适配器架构:
|
||||
WebSearchTool.call()
|
||||
→ createAdapter() 选择后端
|
||||
├─ ApiSearchAdapter — Anthropic API 服务端搜索（需官方 API 密钥）
|
||||
└─ BingSearchAdapter — 直接抓取 Bing 搜索页面解析（无需 API 密钥）
|
||||
→ adapter.search(query, options)
|
||||
→ 转换为统一 SearchResult[] 格式返回
|
||||
```
|
||||
|
||||
#### 适配器选择逻辑
|
||||
|
||||
`adapters/index.ts` 中的工厂函数按以下优先级选择后端：
|
||||
|
||||
| 优先级 | 条件 | 适配器 |
|
||||
|--------|------|--------|
|
||||
| 1 | 环境变量 `WEB_SEARCH_ADAPTER=api` | `ApiSearchAdapter` |
|
||||
| 2 | 环境变量 `WEB_SEARCH_ADAPTER=bing` | `BingSearchAdapter` |
|
||||
| 3 | API Base URL 指向 Anthropic 官方 | `ApiSearchAdapter` |
|
||||
| 4 | 第三方代理 / 非官方端点 | `BingSearchAdapter` |
|
||||
|
||||
适配器是无状态的，同一会话内缓存复用。
|
||||
|
||||
#### ApiSearchAdapter — API 服务端搜索
|
||||
|
||||
将搜索请求委托给 Anthropic API 的 `web_search_20250305` server tool：
|
||||
|
||||
```
|
||||
调用链:
|
||||
ApiSearchAdapter.search(query, options)
|
||||
→ queryModelWithStreaming() 发起独立的 API 调用
|
||||
→ 携带 extraToolSchemas: [BetaWebSearchTool20250305]
|
||||
→ API 服务端执行搜索，返回流式事件
|
||||
→ server_tool_use / web_search_tool_result / text 交替返回
|
||||
→ extractSearchResults() 从 content blocks 提取 SearchResult[]
|
||||
```
|
||||
|
||||
| 特性 | 实现 |
|
||||
|------|------|
|
||||
| **模型选择** | Feature flag `tengu_plum_vx3` 控制用 Haiku（强制 tool_choice）还是主模型 |
|
||||
| **搜索上限** | 每次调用最多 8 次搜索（`max_uses: 8`） |
|
||||
| **域过滤** | 支持 `allowedDomains` / `blockedDomains` |
|
||||
| **进度追踪** | 流式解析 `input_json_delta` 提取 query，实时回调 `onProgress` |
|
||||
|
||||
#### BingSearchAdapter — Bing 搜索页面解析
|
||||
|
||||
直接抓取 Bing 搜索 HTML 并用正则提取结果，无需 API 密钥：
|
||||
|
||||
```
|
||||
调用链:
|
||||
BingSearchAdapter.search(query, options)
|
||||
→ axios.get(bing.com/search?q=...) — 使用浏览器级别 headers 绕过反爬
|
||||
→ extractBingResults(html)
|
||||
→ 正则匹配 <li class="b_algo"> 块
|
||||
→ 提取 <h2><a> 标题和 URL
|
||||
→ resolveBingUrl() 解码 Bing 重定向链接
|
||||
→ extractSnippet() 三级降级提取摘要
|
||||
→ 客户端域过滤 (allowedDomains / blockedDomains)
|
||||
→ 返回 SearchResult[]
|
||||
```
|
||||
|
||||
**反爬策略**：Bing 对非浏览器 UA 返回需要 JS 渲染的空页面。适配器使用完整的 Edge 浏览器请求头（包含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等现代浏览器标头）确保获得完整 HTML。同时使用 `setmkt=en-US` 参数统一市场定位，避免 Bing 基于用户 IP 做区域化定向（如跳转到德语/新加坡市场导致结果不相关）。
|
||||
|
||||
**URL 解码**：Bing 搜索结果中的 URL 为重定向格式（`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`），`resolveBingUrl()` 从 `u` 参数中 base64 解码出真实目标 URL（`a1` 前缀 = https，`a0` = http）。
|
||||
|
||||
**摘要提取**（`extractSnippet()`）按优先级尝试三个来源：
|
||||
1. `<p class="b_lineclamp...">` — 带行截断的摘要段落
|
||||
2. `<div class="b_caption">` 内的 `<p>` — 普通摘要段落
|
||||
3. `<div class="b_caption">` 的直接文本内容 — 兜底方案
|
||||
|
||||
| 特性 | 实现 |
|
||||
|------|------|
|
||||
| **超时** | 30 秒（`FETCH_TIMEOUT_MS`） |
|
||||
| **域过滤** | 支持 `allowedDomains` / `blockedDomains`，含子域名匹配 |
|
||||
| **进度追踪** | 发送 query_update 和 search_results_received 回调 |
|
||||
| **中止支持** | 外部 AbortSignal 传播到 axios 请求 |
|
||||
|
||||
### WebSearchTool 统一接口
|
||||
|
||||
`WebSearchTool`（`src/tools/WebSearchTool/WebSearchTool.ts`）是面向主循环的工具定义，所有 provider 均可使用（`isEnabled()` 始终返回 true）。它将适配器返回的 `SearchResult[]` 转换为内部 `Output` 格式，`mapToolResultToToolResultBlockParam` 将搜索结果格式化为带 markdown 超链接的文本，并附加 "REMINDER" 要求主模型在回复中包含 Sources。
|
||||
|
||||
### WebFetch 实现机制
|
||||
|
||||
WebFetch 是一个完整的 HTTP 客户端 + 内容处理管线：
|
||||
|
||||
```
|
||||
调用链:
|
||||
WebFetchTool.call({ url, prompt })
|
||||
→ getURLMarkdownContent(url)
|
||||
→ validateURL() — 长度≤2000、无用户名密码、公网域名
|
||||
→ URL_CACHE 命中检查（15 分钟 TTL LRU，50MB 上限）
|
||||
→ checkDomainBlocklist() — 调用 api.anthropic.com/api/web/domain_info 预检
|
||||
→ getWithPermittedRedirects() — axios 请求，自定义重定向处理
|
||||
→ HTML → Turndown 转 Markdown（懒加载单例，~1.4MB）
|
||||
→ 非 HTML → 原始文本
|
||||
→ 二进制（PDF 等）→ persistBinaryContent() 保存到磁盘
|
||||
→ applyPromptToMarkdown()
|
||||
→ 截断到 100K 字符
|
||||
→ queryHaiku() 用小模型按 prompt 提取信息
|
||||
→ 返回处理后的结果
|
||||
```
|
||||
|
||||
安全防护多层设计：
|
||||
|
||||
| 层级 | 机制 | 说明 |
|
||||
|------|------|------|
|
||||
| **域名预检** | `checkDomainBlocklist()` | 调用 `api.anthropic.com/api/web/domain_info?domain=…`，5 分钟缓存 |
|
||||
| **重定向控制** | `isPermittedRedirect()` | 仅允许同 host（±www）重定向，跨域重定向返回提示让 AI 重新调用 |
|
||||
| **重定向深度** | `MAX_REDIRECTS = 10` | 防止重定向循环无限挂起 |
|
||||
| **内容大小** | `MAX_HTTP_CONTENT_LENGTH = 10MB` | 单次响应上限 |
|
||||
| **请求超时** | `FETCH_TIMEOUT_MS = 60s` | 主请求超时；域名预检 10s |
|
||||
| **URL 验证** | `validateURL()` | 长度、协议、用户名密码、公网域名检查 |
|
||||
| **egress 检测** | `X-Proxy-Error: blocked-by-allowlist` | 检测企业代理拦截 |
|
||||
|
||||
预批准域名（`src/tools/WebFetchTool/preapproved.ts`）：
|
||||
|
||||
用户无需手动授权即可抓取的域名列表，包含 ~90 个主流技术文档站点（MDN、Python docs、React docs、AWS docs 等）。列表分为 hostname-only 和 path-prefix 两类，查找复杂度 O(1)。
|
||||
|
||||
对预批准域名，WebFetch 跳过 Haiku 摘要步骤（如果内容是 Markdown 且 < 100K 字符），直接返回原文——因为技术文档本身的结构化程度已经足够好。
|
||||
|
||||
权限模型方面，WebFetch 按 hostname 生成 `domain:xxx` 规则匹配用户的 allow/deny/ask 规则，支持用户对特定域名配置永久允许或拒绝。
|
||||
|
||||
### ripgrep 的流式输出
|
||||
|
||||
对于交互式场景（如 QuickOpen），ripgrep 支持**流式输出**（`ripGrepStream()`）：
|
||||
|
||||
```
|
||||
rg --files → 逐 chunk 到达 → 按行分割 → onLines(lines) 回调
|
||||
```
|
||||
|
||||
不需要等 ripgrep 完成整个搜索——第一批结果在 rg 仍在遍历目录树时就已展示。调用者可以通过 AbortSignal 提前终止搜索（例如找到足够多的结果后）。
|
||||
168
docs/tools/shell-execution.mdx
Normal file
168
docs/tools/shell-execution.mdx
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
title: "命令执行工具 - BashTool 安全设计与实现"
|
||||
description: "从源码角度解析 Claude Code BashTool：只读命令判定、AST 安全解析、自动后台化、输出截断和专用工具 vs shell 命令的设计权衡。"
|
||||
keywords: ["Bash 工具", "命令执行", "Shell 执行", "安全命令", "AI 执行命令"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 BashTool 的安全设计、执行链路和关键工程决策 */}
|
||||
|
||||
## 执行链路总览
|
||||
|
||||
一条 Bash 命令从 AI 决策到实际执行的完整路径：
|
||||
|
||||
```
|
||||
AI 生成 tool_use: { command: "npm test" }
|
||||
↓
|
||||
BashTool.validateInput() ← 基础输入校验
|
||||
↓
|
||||
BashTool.checkPermissions() ← 权限检查（详见安全体系章节）
|
||||
├── isReadOnly()? → 自动 allow（只读命令免审批）
|
||||
├── bashToolHasPermission() ← AST 解析 + 语义检查 + 规则匹配
|
||||
└── 未匹配 → 弹窗确认
|
||||
↓
|
||||
BashTool.call() → runShellCommand()
|
||||
↓
|
||||
shouldUseSandbox(input) ← 是否需要沙箱包裹
|
||||
↓
|
||||
Shell.exec(command, { shouldUseSandbox, shouldAutoBackground })
|
||||
↓
|
||||
spawn(wrapped_command) ← 实际进程创建
|
||||
```
|
||||
|
||||
## 只读命令的判定：为什么 Read 免审批而 Bash 不一定
|
||||
|
||||
BashTool 的 `isReadOnly()` 方法（`BashTool.tsx:437`）决定一条命令是否被视为"只读"：
|
||||
|
||||
```typescript
|
||||
isReadOnly(input) {
|
||||
const compoundCommandHasCd = commandHasAnyCd(input.command)
|
||||
const result = checkReadOnlyConstraints(input, compoundCommandHasCd)
|
||||
return result.behavior === 'allow'
|
||||
}
|
||||
```
|
||||
|
||||
判定逻辑基于 4 个命令集合（`BashTool.tsx:60-78`）：
|
||||
|
||||
| 集合 | 命令 | 性质 |
|
||||
|------|------|------|
|
||||
| `BASH_SEARCH_COMMANDS` | find, grep, rg, ag, ack, locate, which, whereis | 搜索类 |
|
||||
| `BASH_READ_COMMANDS` | cat, head, tail, wc, stat, file, jq, awk, sort, uniq... | 读取/分析类 |
|
||||
| `BASH_LIST_COMMANDS` | ls, tree, du | 列表类 |
|
||||
| `BASH_SEMANTIC_NEUTRAL_COMMANDS` | echo, printf, true, false, : | 语义中性（不影响判定） |
|
||||
|
||||
对于复合命令（`ls dir && echo "---" && ls dir2`），系统拆分后逐段检查——**所有非中性段都必须属于上述集合**，整条命令才被视为只读。
|
||||
|
||||
```typescript
|
||||
// BashTool.tsx:95 — 简化的判定逻辑
|
||||
for (const part of partsWithOperators) {
|
||||
if (BASH_SEMANTIC_NEUTRAL_COMMANDS.has(baseCommand)) continue // 跳过中性段
|
||||
if (!isPartSearch && !isPartRead && !isPartList) {
|
||||
return { isSearch: false, isRead: false, isList: false } // 有任何一段不通过 → 非只读
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## AST 安全解析：tree-sitter bash 解析
|
||||
|
||||
`preparePermissionMatcher()`（`BashTool.tsx:445`）在权限检查前用 `parseForSecurity()` 解析命令结构：
|
||||
|
||||
```typescript
|
||||
async preparePermissionMatcher({ command }) {
|
||||
const parsed = await parseForSecurity(command)
|
||||
if (parsed.kind !== 'simple') {
|
||||
return () => true // 解析失败 → fail-safe，触发所有 hook
|
||||
}
|
||||
// 提取子命令列表，剥离 VAR=val 前缀
|
||||
const subcommands = parsed.commands.map(c => c.argv.join(' '))
|
||||
return pattern => {
|
||||
return subcommands.some(cmd => matchWildcardPattern(pattern, cmd))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关键安全点：对于复合命令 `ls && git push`，解析后拆分为 `["ls", "git push"]`，确保 `git push` 不会因为前半段是只读命令而绕过权限检查。解析失败时采用 fail-safe 策略——假设不安全，触发所有安全 hook。
|
||||
|
||||
## 超时控制：分级策略
|
||||
|
||||
```
|
||||
用户指定 timeout → 直接使用
|
||||
↓ 未指定
|
||||
getDefaultTimeoutMs()
|
||||
├── 默认上限：120,000ms（2 分钟）
|
||||
└── 最大上限：600,000ms（10 分钟，用户显式设置时）
|
||||
```
|
||||
|
||||
超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:129`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。
|
||||
|
||||
## 自动后台化
|
||||
|
||||
长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：
|
||||
|
||||
```typescript
|
||||
// BashTool.tsx:880
|
||||
const shouldAutoBackground = !isBackgroundTasksDisabled
|
||||
&& isAutobackgroundingAllowed(command)
|
||||
```
|
||||
|
||||
自动后台化的完整链路：
|
||||
|
||||
```
|
||||
命令开始执行
|
||||
↓ 进度轮询
|
||||
15 秒内未完成（ASSISTANT_BLOCKING_BUDGET_MS）
|
||||
↓
|
||||
检查 isAutobackgroundingAllowed(command)
|
||||
↓ 允许
|
||||
将前台任务转为后台任务（backgroundExistingForegroundTask）
|
||||
↓
|
||||
shellCommand.onTimeout → spawnBackgroundTask()
|
||||
↓
|
||||
返回 taskId 给 AI，AI 可以继续做其他事
|
||||
↓
|
||||
后台任务完成后通过通知机制汇报结果
|
||||
```
|
||||
|
||||
主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 `npm install` 阻塞整个 agentic loop 数分钟。
|
||||
|
||||
## 输出截断策略
|
||||
|
||||
命令输出过长时会触发截断，防止把海量日志塞进 AI 的上下文窗口：
|
||||
|
||||
| 截断点 | 位置 | 行为 |
|
||||
|--------|------|------|
|
||||
| `maxResultSizeChars` | 工具级（通常 100K 字符） | 超长输出在写入消息前截断 |
|
||||
| 进度轮询截断 | `onProgress` 回调 | 只传递最后几行作为进度显示 |
|
||||
| `totalBytes` 标记 | `isIncomplete` 参数 | 告知 AI 输出被截断 |
|
||||
|
||||
截断不是简单砍尾——`isIncomplete` 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。
|
||||
|
||||
## 为什么用专用工具而不是直接调 shell
|
||||
|
||||
Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。这不仅是用户体验的选择，更是架构层面的设计决策：
|
||||
|
||||
| 维度 | 专用工具 | Bash 命令 |
|
||||
|------|---------|----------|
|
||||
| **权限粒度** | `Read` 是只读操作 → 自动放行 | `Bash: cat file` 需要审批整条命令（cat 在只读集合中但走不同路径） |
|
||||
| **输出结构化** | 返回结构化数据，UI 可渲染 diff、高亮 | 纯文本输出，无渲染优化 |
|
||||
| **性能优化** | 文件缓存、分页、token 预算控制 | 每次都是新进程，无缓存 |
|
||||
| **并发安全** | `isConcurrencySafe()` 返回 `true` → 可并行执行 | Bash 命令可能有副作用，串行执行 |
|
||||
| **安全审计** | 工具名精确匹配权限规则 | 需 AST 解析命令结构后匹配 |
|
||||
|
||||
`isConcurrencySafe()`（`BashTool.tsx:434`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。
|
||||
|
||||
## 进度反馈的流式设计
|
||||
|
||||
BashTool 的命令执行是流式的，通过 `onProgress` 回调逐行推送输出：
|
||||
|
||||
```
|
||||
runShellCommand()
|
||||
├── Shell.exec() 启动子进程
|
||||
├── 每秒轮询输出文件
|
||||
├── onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete)
|
||||
│ ├── 更新 lastProgressOutput / fullOutput
|
||||
│ └── resolveProgress() → 唤醒 generator yield
|
||||
├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
|
||||
└── return { code, stdout, interrupted, ... }
|
||||
```
|
||||
|
||||
UI 层通过 `useToolCallProgress` hook 实时展示命令输出。`resolveProgress()` 信号机制让 generator 在有新数据时才 yield，避免了忙等待。
|
||||
212
docs/tools/task-management.mdx
Normal file
212
docs/tools/task-management.mdx
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: "任务管理系统 - TodoWrite 与 Tasks 双轨架构"
|
||||
description: "揭秘 Claude Code 任务管理系统的双轨架构：V1 内存 TodoWrite 与 V2 文件系统 Tasks，包含依赖管理、认领竞争和验证推动机制。"
|
||||
keywords: ["任务管理", "TodoWrite", "任务队列", "依赖管理", "多任务"]
|
||||
---
|
||||
|
||||
{/* 本章目标：揭示任务系统 V1（内存 TodoWrite）和 V2（文件系统 Task*）的双轨架构，以及依赖管理、认领竞争、验证推动的工程细节 */}
|
||||
|
||||
## 双轨架构：TodoWrite V1 与 Tasks V2
|
||||
|
||||
Claude Code 的任务管理并非单一系统，而是两个并存、按运行模式切换的实现：
|
||||
|
||||
| 维度 | V1: TodoWrite | V2: TaskCreate / TaskUpdate / TaskList / TaskGet |
|
||||
|------|--------------|--------------------------------------------------|
|
||||
| **启用条件** | 非交互式（pipe/SDK）或 `isTodoV2Enabled()` 返回 `false` | 交互式 REPL（默认）或 `CLAUDE_CODE_ENABLE_TASKS=1` |
|
||||
| **存储** | 内存中 `AppState.todos[sessionId]`（Zustand store） | 文件系统 `~/.claude/tasks/<taskListId>/<id>.json` |
|
||||
| **数据模型** | `{content, status, activeForm}` — 扁平三元组 | `{id, subject, description, activeForm, owner, status, blocks[], blockedBy[], metadata}` — 完整实体 |
|
||||
| **持久化** | 进程退出即丢失 | 跨进程存活，支持多 Agent 并发访问 |
|
||||
| **并发安全** | 无（单会话单写者） | 文件锁 + 高水位标记 + TOCTOU 防护 |
|
||||
|
||||
切换逻辑位于 `isTodoV2Enabled()`（`src/utils/tasks.ts:133`）：交互式会话默认启用 V2，SDK/pipe 模式回落 V1。两者互斥——`TodoWriteTool.isEnabled` 返回 `!isTodoV2Enabled()`，而 `TaskCreateTool.isEnabled` 返回 `isTodoV2Enabled()`。
|
||||
|
||||
## V1：TodoWrite 的极简设计
|
||||
|
||||
TodoWrite 本质是一个**全量替换**操作——每次调用传入完整的 `todos[]` 数组，完全覆盖之前的状态：
|
||||
|
||||
```typescript
|
||||
// src/tools/TodoWriteTool/TodoWriteTool.ts — call() 核心逻辑
|
||||
async call({ todos }, context) {
|
||||
const todoKey = context.agentId ?? getSessionId()
|
||||
const oldTodos = appState.todos[todoKey] ?? []
|
||||
const allDone = todos.every(_ => _.status === 'completed')
|
||||
const newTodos = allDone ? [] : todos // 全部完成则清空列表
|
||||
// ... 写入 AppState
|
||||
}
|
||||
```
|
||||
|
||||
### 智能清空与验证推动
|
||||
|
||||
一个微妙的设计：当所有任务都 `completed` 时，`newTodos` 被设为空数组（而非保留 `completed` 列表）。这确保 UI 上不会有"已完成"的视觉噪音。
|
||||
|
||||
此外，V1 包含一个**验证推动**（verification nudge）机制：当主线程 Agent 完成 3+ 个任务且没有任何一个是验证步骤时，系统在 tool_result 中追加提示，催促 Agent 派生验证子 Agent：
|
||||
|
||||
```typescript
|
||||
// 条件：主线程 + 全部完成 + ≥3 项 + 无验证任务
|
||||
if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content))) {
|
||||
verificationNudgeNeeded = true
|
||||
}
|
||||
// tool_result 中追加：
|
||||
// "NOTE: You just closed out 3+ tasks and none was a verification step..."
|
||||
```
|
||||
|
||||
这是防止 Agent "自说自话地宣布完成"的防御性设计——通过结构性推动而非硬约束。
|
||||
|
||||
## V2：文件系统持久化的任务系统
|
||||
|
||||
### 数据模型
|
||||
|
||||
每个任务是一个独立 JSON 文件，路径为 `~/.claude/tasks/<taskListId>/<id>.json`：
|
||||
|
||||
```typescript
|
||||
// src/utils/tasks.ts — TaskSchema
|
||||
{
|
||||
id: string, // 自增整数（1, 2, 3...）
|
||||
subject: string, // 祈使句标题（如 "Fix auth bug"）
|
||||
description: string, // 详细描述
|
||||
activeForm?: string, // 进行时形式（如 "Fixing auth bug"），用于 spinner
|
||||
owner?: string, // 认领该任务的 Agent ID/名称
|
||||
status: "pending" | "in_progress" | "completed",
|
||||
blocks: string[], // 此任务阻塞哪些任务 ID
|
||||
blockedBy: string[], // 哪些任务 ID 阻塞此任务
|
||||
metadata?: Record<string, unknown> // 任意附加数据
|
||||
}
|
||||
```
|
||||
|
||||
### 任务列表 ID 的解析优先级
|
||||
|
||||
`getTaskListId()` 按 5 级优先级解析任务归属：
|
||||
|
||||
1. `CLAUDE_CODE_TASK_LIST_ID` 环境变量（显式覆盖）
|
||||
2. 进程内 teammate 上下文的 teamName（共享 leader 的任务列表）
|
||||
3. `CLAUDE_CODE_TEAM_NAME` 环境变量（进程级 teammate）
|
||||
4. Leader 通过 `setLeaderTeamName()` 设置的 teamName
|
||||
5. `getSessionId()`（独立会话的兜底）
|
||||
|
||||
这意味着多 Agent 团队模式下，所有 teammate 自动共享同一个任务列表，无需额外协调。
|
||||
|
||||
### ID 分配与高水位标记
|
||||
|
||||
任务 ID 是简单的递增整数，但在并发场景下需要防止竞争：
|
||||
|
||||
```typescript
|
||||
// src/utils/tasks.ts — createTask() 简化
|
||||
async function createTask(taskListId, taskData) {
|
||||
release = await lockfile.lock(lockPath, LOCK_OPTIONS) // 获取排他锁
|
||||
const highestId = await findHighestTaskId(taskListId) // 读取当前最大 ID
|
||||
const id = String(highestId + 1) // 递增
|
||||
await writeFile(path, JSON.stringify({ id, ...taskData }))
|
||||
return id
|
||||
}
|
||||
```
|
||||
|
||||
锁配置使用指数退避重试 30 次（总计约 2.6 秒），适配 10+ 并发 Agent 的 swarm 场景。
|
||||
|
||||
高水位标记文件 `.highwatermark` 确保删除任务后 ID 不会被重用——即使任务 #5 被删除，下一个新建任务仍然是 #6。
|
||||
|
||||
## 依赖管理：blocks / blockedBy
|
||||
|
||||
任务间的依赖通过双向链表式的 `blocks` / `blockedBy` 字段实现：
|
||||
|
||||
- `taskA.blocks = ["3"]` 表示 "任务 A 完成前，任务 3 不能开始"
|
||||
- `task3.blockedBy = ["A"]` 表示 "任务 3 必须等任务 A 完成"
|
||||
|
||||
`blockTask()` 函数同时维护两端：
|
||||
|
||||
```typescript
|
||||
// src/utils/tasks.ts — blockTask()
|
||||
// A blocks B → 更新 A.blocks 加入 B，同时更新 B.blockedBy 加入 A
|
||||
if (!fromTask.blocks.includes(toTaskId)) {
|
||||
await updateTask(taskListId, fromTaskId, { blocks: [...fromTask.blocks, toTaskId] })
|
||||
}
|
||||
if (!toTask.blockedBy.includes(fromTaskId)) {
|
||||
await updateTask(taskListId, toTaskId, { blockedBy: [...toTask.blockedBy, fromTaskId] })
|
||||
}
|
||||
```
|
||||
|
||||
删除任务时，系统自动清理所有指向它的依赖引用（`deleteTask()` 遍历全部任务移除 `blocks` 和 `blockedBy` 中的引用）。
|
||||
|
||||
## 任务认领与并发控制
|
||||
|
||||
`claimTask()` 是 V2 的核心并发原语，支持两种锁定粒度：
|
||||
|
||||
### 1. 任务级锁（默认）
|
||||
|
||||
仅锁定目标任务文件，适合单 Agent 场景：
|
||||
|
||||
```
|
||||
getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner
|
||||
```
|
||||
|
||||
### 2. 列表级锁 + Agent 忙碌检查
|
||||
|
||||
当 `checkAgentBusy: true` 时，锁定整个任务列表目录（`.lock` 文件），原子化地完成：
|
||||
|
||||
```
|
||||
listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥有其他未完成任务 → 写入 owner
|
||||
```
|
||||
|
||||
认领失败有 4 种原因：
|
||||
|
||||
| `reason` | 含义 |
|
||||
|----------|------|
|
||||
| `task_not_found` | 任务 ID 不存在 |
|
||||
| `already_claimed` | 已被其他 Agent 认领 |
|
||||
| `already_resolved` | 任务已标记 completed |
|
||||
| `blocked` | blockedBy 列表中有未完成的任务 |
|
||||
| `agent_busy` | 该 Agent 已拥有其他未完成任务（仅 `checkAgentBusy` 模式） |
|
||||
|
||||
## Agent 团队的任务生命周期
|
||||
|
||||
在 swarms 模式下，任务系统的生命周期是这样的：
|
||||
|
||||
```
|
||||
Leader 创建团队
|
||||
↓
|
||||
Leader 用 TaskCreate 创建任务（status=pending, owner=undefined）
|
||||
↓
|
||||
Leader 用 TaskUpdate 设置依赖关系（addBlocks/addBlockedBy）
|
||||
↓
|
||||
Teammate 调用 TaskList → 发现可认领的任务
|
||||
↓
|
||||
Teammate 调用 TaskUpdate(taskId, {status: "in_progress"})
|
||||
→ 自动设置 owner 为 teammate 名称
|
||||
→ Leader 通过 mailbox 收到 task_assignment 通知
|
||||
↓
|
||||
Teammate 完成工作 → TaskUpdate(taskId, {status: "completed"})
|
||||
→ tool_result 提示 "Call TaskList to find your next available task"
|
||||
→ 依赖此任务的其他任务自动解锁
|
||||
↓
|
||||
Teammate 异常退出 → unassignTeammateTasks()
|
||||
→ 未完成任务被重置为 pending + owner=undefined
|
||||
→ Leader 收到通知并重新分配
|
||||
```
|
||||
|
||||
### Hooks 集成
|
||||
|
||||
TaskCreate 和 TaskUpdate 都集成了 hooks 系统：
|
||||
|
||||
- **创建时**：`executeTaskCreatedHooks` — 外部钩子可以阻断任务创建（blockingError 导致任务被立即删除）
|
||||
- **完成时**：`executeTaskCompletedHooks` — 外部钩子可以阻断任务标记为完成
|
||||
|
||||
这允许外部系统（CI、审批流）参与任务状态机。
|
||||
|
||||
## activeForm：终端 UX 的细节
|
||||
|
||||
每个任务有两个文案字段：
|
||||
|
||||
- `subject`：祈使句，用于任务列表展示（"Fix auth bug"）
|
||||
- `activeForm`：进行时形式，用于 spinner 动画（"Fixing auth bug..."）
|
||||
|
||||
当 `activeForm` 缺省时，spinner 回退显示 `subject`。这个看似微小的设计确保了用户在等待时看到的是"正在做什么"而非"要做什么"。
|
||||
|
||||
## Plan Mode 与任务系统的配合
|
||||
|
||||
Plan Mode（计划模式）和任务系统是互补但独立的机制：
|
||||
|
||||
1. Plan Mode 限制工具集为只读（搜索、阅读），迫使 AI 先理解再行动
|
||||
2. AI 在 Plan Mode 中用 TaskCreate 建立任务列表
|
||||
3. 用户审批后退出 Plan Mode
|
||||
4. AI 按 `blockedBy` 拓扑序逐项执行，每项用 TaskUpdate 标记进度
|
||||
|
||||
`shouldDefer: true` 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。
|
||||
206
docs/tools/what-are-tools.mdx
Normal file
206
docs/tools/what-are-tools.mdx
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
title: "工具系统设计 - AI 如何从说到做"
|
||||
description: "深入理解 Claude Code 的 Tool 抽象设计：从类型定义、注册机制、调用链路到渲染系统，揭示 50+ 内置工具如何通过统一的 Tool 接口协同工作。"
|
||||
keywords: ["工具系统", "Tool 抽象", "AI 工具", "function calling", "buildTool", "getTools"]
|
||||
---
|
||||
|
||||
{/* 本章目标：基于 src/Tool.ts 和 src/tools.ts 揭示工具系统的完整架构 */}
|
||||
|
||||
## AI 为什么需要工具
|
||||
|
||||
大语言模型本质上只能做一件事：**根据输入文本，生成输出文本**。
|
||||
|
||||
它不能读文件、不能执行命令、不能搜索代码。要让 AI 真正"动手"，需要一个桥梁——这就是 **Tool**（工具）。
|
||||
|
||||
工具是 AI 的双手。AI 说"我想读这个文件"，工具系统替它真正去读；AI 说"我想执行这条命令"，工具系统替它真正去跑。
|
||||
|
||||
## Tool 类型：35 个字段的统一接口
|
||||
|
||||
所有工具都实现 `src/Tool.ts:362` 的 `Tool<Input, Output, Progress>` 类型。这不是一个 class，而是一个包含 35+ 字段的**结构化类型**（structural typing），任何满足该接口的对象就是一个工具：
|
||||
|
||||
### 核心四要素
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | `string` | 唯一标识（如 `Read`、`Bash`、`Agent`） |
|
||||
| `description()` | `(input) => Promise<string>` | **动态描述**——根据输入参数返回不同描述（如 `Execute skill: ${skill}`） |
|
||||
| `inputSchema` | `z.ZodType` | Zod schema，定义参数类型和校验规则 |
|
||||
| `call()` | `(args, context, canUseTool, parentMessage, onProgress?) => Promise<ToolResult<Output>>` | 执行函数 |
|
||||
|
||||
### 注册与发现
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `aliases` | 别名数组（向后兼容重命名） |
|
||||
| `searchHint` | 3-10 词的短语，供 ToolSearch 关键词匹配（如 `"jupyter"` for NotebookEdit） |
|
||||
| `shouldDefer` | 是否延迟加载（配合 ToolSearch 按需加载） |
|
||||
| `alwaysLoad` | 永不延迟加载（如 SkillTool 必须在 turn 1 可见） |
|
||||
| `isEnabled()` | 运行时开关（如 PowerShellTool 检查平台） |
|
||||
|
||||
### 安全与权限
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `validateInput()` | 输入校验（在权限检查之前），返回 `ValidationResult` |
|
||||
| `checkPermissions()` | 权限检查（在校验之后），返回 `PermissionResult` |
|
||||
| `isReadOnly()` | 是否只读操作（影响权限模式） |
|
||||
| `isDestructive()` | 是否不可逆操作（删除、覆盖、发送） |
|
||||
| `isConcurrencySafe()` | 相同输入是否可以并行执行 |
|
||||
| `preparePermissionMatcher()` | 为 Hook 的 `if` 条件准备模式匹配器 |
|
||||
| `interruptBehavior()` | 用户中断时的行为：`'cancel'` 或 `'block'` |
|
||||
|
||||
### 输出与渲染
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `maxResultSizeChars` | 结果字符上限（超出则持久化到磁盘，如 `100_000`） |
|
||||
| `mapToolResultToToolResultBlockParam()` | 将 Output 映射为 API 格式的 `ToolResultBlockParam` |
|
||||
| `renderToolResultMessage()` | React 组件渲染工具结果到终端 |
|
||||
| `renderToolUseMessage()` | React 组件渲染工具调用过程 |
|
||||
| `backfillObservableInput()` | 在不破坏 prompt cache 的前提下回填可观察字段 |
|
||||
|
||||
### 上下文与 Prompt
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `prompt()` | 返回该工具的详细使用说明，注入到 System Prompt |
|
||||
| `outputSchema` | 输出 Zod schema（用于类型安全的结果处理） |
|
||||
| `getPath()` | 提取操作的文件路径（用于权限匹配和 UI 显示） |
|
||||
|
||||
## 工具注册：`getTools()` 的分层组装
|
||||
|
||||
`src/tools.ts` 的 `getAllBaseTools()`（第 191 行）是工具注册的核心：
|
||||
|
||||
```
|
||||
固定工具（始终可用）:
|
||||
AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool,
|
||||
NotebookEditTool, WebFetchTool, WebSearchTool, TodoWriteTool,
|
||||
AskUserQuestionTool, SkillTool, EnterPlanModeTool, ExitPlanModeV2Tool,
|
||||
TaskOutputTool, BriefTool, ListMcpResourcesTool, ReadMcpResourceTool
|
||||
|
||||
条件工具（运行时检查）:
|
||||
← hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]
|
||||
← isTodoV2Enabled() ? V2 Tasks : []
|
||||
← isWorktreeModeEnabled() ? Worktree : []
|
||||
← isAgentSwarmsEnabled() ? Teams : []
|
||||
← isToolSearchEnabled() ? ToolSearch: []
|
||||
← isPowerShellToolEnabled() ? PowerShell: []
|
||||
|
||||
Feature-flag 工具:
|
||||
← feature('COORDINATOR_MODE') ? [coordinatorMode tools]
|
||||
← feature('KAIROS') ? [SleepTool, SendUserFileTool, ...]
|
||||
← feature('WEB_BROWSER_TOOL') ? [WebBrowserTool]
|
||||
← feature('HISTORY_SNIP') ? [SnipTool]
|
||||
|
||||
Ant-only 工具:
|
||||
← process.env.USER_TYPE === 'ant' ? [REPLTool, ConfigTool, TungstenTool]
|
||||
```
|
||||
|
||||
`getTools()`（第 269 行）在 `getAllBaseTools()` 基础上应用权限过滤：
|
||||
|
||||
```typescript
|
||||
export const getTools = (permissionContext): Tools => {
|
||||
const base = getAllBaseTools()
|
||||
// 过滤 blanket deny 规则命中的工具
|
||||
return filterToolsByDenyRules(base, permissionContext)
|
||||
}
|
||||
```
|
||||
|
||||
**关键设计**：工具列表在每次 API 调用时组装（而非全局缓存），因为 `isEnabled()` 的结果可能随运行时状态变化。
|
||||
|
||||
## `buildTool()` 工厂函数
|
||||
|
||||
大多数工具通过 `buildTool()` 创建（`src/Tool.ts:721`），它是一个类型安全的构造器：
|
||||
|
||||
```typescript
|
||||
export const BashTool: Tool<...> = buildTool({
|
||||
name: 'Bash',
|
||||
inputSchema: lazySchema(() => z.object({command: z.string(), ...})),
|
||||
// ...其他字段
|
||||
}) satisfies ToolDef<Input, Output, Progress>
|
||||
```
|
||||
|
||||
`satisfies ToolDef` 确保编译时类型检查，`lazySchema` 延迟 Zod schema 解析（避免循环依赖）。
|
||||
|
||||
## 工具调用的完整链路
|
||||
|
||||
从 AI 发出 `tool_use` 到结果回传，经过以下步骤：
|
||||
|
||||
```
|
||||
1. API 返回 tool_use block（包含 name + input）
|
||||
↓
|
||||
2. StreamingToolExecutor.addTool() / runTools()
|
||||
↓
|
||||
3. findToolByName() 查找工具
|
||||
↓
|
||||
4. validateInput() — 输入校验
|
||||
↓ 失败 → 返回错误 tool_result
|
||||
5. canUseTool() — 权限 UI（Ask 模式下弹确认）
|
||||
↓ 拒绝 → 返回拒绝 tool_result
|
||||
6. checkPermissions() — 规则匹配
|
||||
↓
|
||||
7. call() — 执行实际操作
|
||||
↓ onProgress() 回调实时更新 UI
|
||||
8. 返回 ToolResult<Output>
|
||||
↓
|
||||
9. mapToolResultToToolResultBlockParam() — 转为 API 格式
|
||||
↓
|
||||
10. 新消息追加到对话 → 进入下一轮迭代
|
||||
```
|
||||
|
||||
## 工具结果的预算控制
|
||||
|
||||
每个工具通过 `maxResultSizeChars` 声明输出上限：
|
||||
|
||||
- **BashTool**：`30_000`（命令输出）
|
||||
- **SkillTool**：`100_000`（技能执行结果）
|
||||
- **FileReadTool**：`Infinity`（文件内容不走持久化，避免 Read→file→Read 循环）
|
||||
|
||||
超出上限的结果被 `applyToolResultBudget()`（`src/utils/toolResultStorage.ts`）持久化到磁盘，AI 只收到预览 + 文件路径。
|
||||
|
||||
## MCP 工具的扩展
|
||||
|
||||
MCP Server 提供的工具通过 `mcpInfo` 字段标记来源：
|
||||
|
||||
```typescript
|
||||
mcpInfo?: { serverName: string; toolName: string }
|
||||
```
|
||||
|
||||
MCP 工具的 `inputJSONSchema` 直接使用 JSON Schema（而非 Zod），因为 schema 来自远程协议。它们通过 `filterToolsByDenyRules()` 支持 `mcp__server` 前缀的 blanket deny 规则。
|
||||
|
||||
## 50+ 内置工具全景
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="文件操作" icon="file">
|
||||
Read / Write / Edit / Glob / Grep / NotebookEdit
|
||||
</Card>
|
||||
<Card title="命令执行" icon="terminal">
|
||||
Bash / PowerShell
|
||||
</Card>
|
||||
<Card title="对话管理" icon="comments">
|
||||
Agent / SendMessage / AskUserQuestion
|
||||
</Card>
|
||||
<Card title="任务追踪" icon="list-check">
|
||||
TaskCreate / TaskUpdate / TaskList / TaskGet / TaskOutput / TaskStop
|
||||
</Card>
|
||||
<Card title="Web 能力" icon="globe">
|
||||
WebFetch / WebSearch / WebBrowser
|
||||
</Card>
|
||||
<Card title="规划与版本" icon="map">
|
||||
EnterPlanMode / ExitPlanMode / Worktree / TodoWrite / ToolSearch
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 工具的可视化渲染
|
||||
|
||||
工具不仅能"做事"，还能"展示"。每个工具通过 React 组件定义 UI 渲染：
|
||||
|
||||
- **FileEdit** → `renderToolResultMessage` 展示语法高亮的 diff 视图
|
||||
- **Bash** → 实时显示命令输出（通过 `onProgress` 回调），带进度指示
|
||||
- **Grep** → 高亮匹配结果，显示文件路径和行号链接
|
||||
- **Agent** → 显示子 Agent 的进度条和状态
|
||||
- **SkillTool** → 渲染技能执行进度
|
||||
|
||||
`isSearchOrReadCommand()` 允许工具声明自己是搜索/读取操作，触发 UI 的折叠显示模式（避免大量搜索结果占满屏幕）。
|
||||
|
||||
`getActivityDescription()` 为 spinner 提供活动描述（如 "Reading src/foo.ts"、"Running bun test"），替代默认的工具名显示。
|
||||
444
docs/ultraplan-implementation.md
Normal file
444
docs/ultraplan-implementation.md
Normal file
@@ -0,0 +1,444 @@
|
||||
# ULTRAPLAN（增强规划）实现分析
|
||||
|
||||
> 生成日期：2026-04-02
|
||||
> Feature Flag：`FEATURE_ULTRAPLAN=1`
|
||||
> 引用数：10（跨 8 个文件）
|
||||
|
||||
---
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
ULTRAPLAN 是一个**远程增强规划**功能，将用户的规划请求发送到 Claude Code on the Web（CCR，云端容器）执行。使用 Opus 模型在云端生成高级计划，用户可以在浏览器中编辑和审批，然后选择在云端继续执行或将计划"传送"回本地终端执行。
|
||||
|
||||
**核心卖点**：
|
||||
- 终端不被阻塞 — 远程在云端规划，本地可继续工作
|
||||
- 使用最强大的模型（Opus）
|
||||
- 用户可在浏览器中实时查看和编辑计划
|
||||
- 支持多轮迭代（云端可追问，用户在浏览器回复）
|
||||
|
||||
---
|
||||
|
||||
## 二、架构总览
|
||||
|
||||
```
|
||||
用户输入 "ultraplan xxx"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ 关键字检测层 (keyword.ts) │ 识别 "ultraplan" 关键字
|
||||
│ + 输入处理层 (processUserInput) │ 重写为 /ultraplan 命令
|
||||
└───────────┬─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ 命令处理层 (ultraplan.tsx) │ launchUltraplan()
|
||||
│ - 前置校验（资格、防重入） │ → launchDetached()
|
||||
│ - 构建提示词 │ buildUltraplanPrompt()
|
||||
└───────────┬─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ 远程会话层 │ teleportToRemote()
|
||||
│ - 创建 CCR 云端会话 │ permissionMode: 'plan'
|
||||
│ - 设置 plan 权限模式 │ model: Opus
|
||||
└───────────┬─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ 轮询层 (ccrSession.ts) │ pollForApprovedExitPlanMode()
|
||||
│ - ExitPlanModeScanner │ 每 3 秒轮询事件流
|
||||
│ - 状态机: running → needs_input │ 超时: 30 分钟
|
||||
│ → plan_ready │
|
||||
└───────────┬─────────────────────┘
|
||||
│
|
||||
┌─────┴─────┐
|
||||
▼ ▼
|
||||
approved teleport
|
||||
(云端执行) (传送回本地)
|
||||
│ │
|
||||
│ ▼
|
||||
│ UltraplanChoiceDialog
|
||||
│ 用户选择执行方式
|
||||
▼ ▼
|
||||
完成通知 本地执行计划
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、模块详解
|
||||
|
||||
### 3.1 关键字检测 — `src/utils/ultraplan/keyword.ts`
|
||||
|
||||
负责检测用户输入中的 "ultraplan" 关键字。检测逻辑相当精细，避免误触发：
|
||||
|
||||
**触发条件**：输入中包含独立的 `ultraplan` 单词（大小写不敏感）。
|
||||
|
||||
**不触发的场景**：
|
||||
- 在引号/括号内：`` `ultraplan` ``、`"ultraplan"`、`[ultraplan]`、`{ultraplan}`
|
||||
- 路径/标识符上下文：`src/ultraplan/foo.ts`、`ultraplan.tsx`、`--ultraplan-mode`
|
||||
- 问句：`ultraplan?`
|
||||
- 斜杠命令内：`/rename ultraplan foo`
|
||||
- 已有 ultraplan 会话运行中或正在启动时
|
||||
|
||||
**关键字替换**：触发后将 `ultraplan` 替换为 `plan`，保持语法通顺（如 "please ultraplan this" → "please plan this"）。
|
||||
|
||||
```typescript
|
||||
// 核心导出函数
|
||||
findUltraplanTriggerPositions(text) // 返回触发位置数组
|
||||
hasUltraplanKeyword(text) // 布尔判断
|
||||
replaceUltraplanKeyword(text) // 替换第一个触发词为 "plan"
|
||||
```
|
||||
|
||||
### 3.2 命令注册 — `src/commands.ts`
|
||||
|
||||
```typescript
|
||||
const ultraplan = feature('ULTRAPLAN')
|
||||
? require('./commands/ultraplan.js').default
|
||||
: null
|
||||
```
|
||||
|
||||
命令仅在 `FEATURE_ULTRAPLAN=1` 时加载。命令定义：
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'local-jsx',
|
||||
name: 'ultraplan',
|
||||
description: '~10–30 min · Claude Code on the web drafts an advanced plan...',
|
||||
argumentHint: '<prompt>',
|
||||
isEnabled: () => process.env.USER_TYPE === 'ant', // 仅 ant 用户可用
|
||||
}
|
||||
```
|
||||
|
||||
> 注意：`isEnabled` 检查 `USER_TYPE === 'ant'`（Anthropic 内部用户），这是命令级限制。关键字触发路径没有此限制，只要 feature flag 开启即可。
|
||||
|
||||
### 3.3 核心命令实现 — `src/commands/ultraplan.tsx`
|
||||
|
||||
#### 3.3.1 入口函数 `call()`
|
||||
|
||||
处理 `/ultraplan <prompt>` 斜杠命令：
|
||||
|
||||
1. **无参数调用**：显示使用帮助文本
|
||||
2. **已有活跃会话**：返回 "already polling" 提示
|
||||
3. **正常调用**：设置 `ultraplanLaunchPending` 状态，触发 `UltraplanLaunchDialog` 对话框
|
||||
|
||||
#### 3.3.2 `launchUltraplan()`
|
||||
|
||||
公共启动入口，被三个路径共享：
|
||||
- 斜杠命令 (`/ultraplan`)
|
||||
- 关键字触发 (`processUserInput.ts`)
|
||||
- Plan 审批对话框的 "Ultraplan" 按钮 (`ExitPlanModePermissionRequest`)
|
||||
|
||||
关键逻辑：
|
||||
1. 防重入检查（`ultraplanSessionUrl` / `ultraplanLaunching`）
|
||||
2. 同步设置 `ultraplanLaunching = true` 防止竞态
|
||||
3. 异步调用 `launchDetached()`
|
||||
4. 立即返回启动消息（不等远程会话创建）
|
||||
|
||||
#### 3.3.3 `launchDetached()`
|
||||
|
||||
异步后台流程：
|
||||
|
||||
1. **获取模型**：从 GrowthBook 读取 `tengu_ultraplan_model`，默认 `opus46` 的 firstParty ID
|
||||
2. **资格检查**：`checkRemoteAgentEligibility()` — 验证用户是否有权限使用远程 agent
|
||||
3. **构建提示词**：`buildUltraplanPrompt(blurb, seedPlan)`
|
||||
- 如有 `seedPlan`（来自 plan 审批对话框），作为草稿前缀
|
||||
- 加载 `prompt.txt` 中的指令模板
|
||||
- 附加用户 blurb
|
||||
4. **创建远程会话**：`teleportToRemote()`
|
||||
- `permissionMode: 'plan'` — 远程以 plan 模式运行
|
||||
- `ultraplan: true` — 标记为 ultraplan 会话
|
||||
- `useDefaultEnvironment: true` — 使用默认云端环境
|
||||
5. **注册任务**：`registerRemoteAgentTask()` 创建 `RemoteAgentTask` 追踪条目
|
||||
6. **启动轮询**：`startDetachedPoll()` 后台轮询审批状态
|
||||
|
||||
#### 3.3.4 提示词构建
|
||||
|
||||
```
|
||||
buildUltraplanPrompt(blurb, seedPlan?)
|
||||
```
|
||||
|
||||
- `prompt.txt`：当前为空文件（反编译丢失），原始内容应包含指导远程 agent 生成计划的系统指令
|
||||
- 开发者可通过 `ULTRAPLAN_PROMPT_FILE` 环境变量覆盖提示词文件（仅 `USER_TYPE=ant` 时生效）
|
||||
|
||||
#### 3.3.5 `startDetachedPoll()`
|
||||
|
||||
后台轮询管理：
|
||||
|
||||
1. 调用 `pollForApprovedExitPlanMode()` 等待计划审批
|
||||
2. 阶段变化时更新 `RemoteAgentTask.ultraplanPhase`（UI 展示）
|
||||
3. 审批完成后的两种路径：
|
||||
- **`executionTarget: 'remote'`**：用户选择在云端执行
|
||||
- 标记任务完成
|
||||
- 清除 `ultraplanSessionUrl`
|
||||
- 发送通知：结果将以 PR 形式提交
|
||||
- **`executionTarget: 'local'`**：用户选择传送回本地（teleport）
|
||||
- 设置 `ultraplanPendingChoice`
|
||||
- 触发 `UltraplanChoiceDialog` 对话框
|
||||
4. 失败时：归档远程会话、清除状态、发送错误通知
|
||||
|
||||
#### 3.3.6 `stopUltraplan()`
|
||||
|
||||
用户主动停止：
|
||||
|
||||
1. `RemoteAgentTask.kill()` 归档远程会话
|
||||
2. 清除所有 ultraplan 状态（`ultraplanSessionUrl`、`ultraplanPendingChoice`、`ultraplanLaunching`）
|
||||
3. 发送停止通知
|
||||
|
||||
### 3.4 CCR 会话轮询 — `src/utils/ultraplan/ccrSession.ts`
|
||||
|
||||
#### 3.4.1 `ExitPlanModeScanner`
|
||||
|
||||
纯状态机，无 I/O。摄入 `SDKMessage[]` 事件批次，分类 `ExitPlanMode` 工具调用的结果。
|
||||
|
||||
**状态类型**：
|
||||
|
||||
```typescript
|
||||
type ScanResult =
|
||||
| { kind: 'approved' } // 用户批准了计划
|
||||
| { kind: 'teleport' } // 用户点击"传送回本地"
|
||||
| { kind: 'rejected' } // 用户拒绝（可继续迭代）
|
||||
| { kind: 'pending' } // 等待用户审批中
|
||||
| { kind: 'terminated' } // 远程会话意外终止
|
||||
| { kind: 'unchanged' } // 无新事件，状态不变
|
||||
```
|
||||
|
||||
**优先级**：approved > terminated > rejected > pending > unchanged
|
||||
|
||||
**关键设计**：
|
||||
- 同一批事件可能包含审批和后续崩溃 — 不丢弃已审批的计划
|
||||
- 拒绝后重新扫描（`rescanAfterRejection`），因为新事件可能包含修改后的计划
|
||||
- 使用 `is_error: true` 判断拒绝，`content` 中查找标记提取计划文本
|
||||
|
||||
#### 3.4.2 `pollForApprovedExitPlanMode()`
|
||||
|
||||
轮询主循环：
|
||||
|
||||
- **轮询间隔**：3 秒
|
||||
- **超时**：30 分钟
|
||||
- **容错**：连续 5 次网络错误才放弃
|
||||
- **阶段推断**：
|
||||
- `hasPendingPlan`（有 ExitPlanMode 无结果）→ `plan_ready`
|
||||
- `quietIdle`（空闲且无新事件）→ `needs_input`（远程在等用户输入）
|
||||
- 其他 → `running`
|
||||
|
||||
#### 3.4.3 计划文本提取
|
||||
|
||||
两种提取路径：
|
||||
|
||||
1. **Approved**：从 `tool_result` 中查找 `## Approved Plan:\n` 或 `## Approved Plan (edited by user):\n` 标记
|
||||
2. **Teleport**：从 `tool_result` 中查找 `__ULTRAPLAN_TELEPORT_SENTINEL__` 标记（浏览器端嵌入）
|
||||
|
||||
### 3.5 输入处理集成 — `src/utils/processUserInput/processUserInput.ts`
|
||||
|
||||
关键字触发路径（在斜杠命令处理之前）：
|
||||
|
||||
```typescript
|
||||
if (feature('ULTRAPLAN') &&
|
||||
mode === 'prompt' && // 非非交互模式
|
||||
!isNonInteractiveSession && // 非后台会话
|
||||
inputString !== null &&
|
||||
!inputString.startsWith('/') && // 非斜杠命令
|
||||
!ultraplanSessionUrl && // 无活跃会话
|
||||
!ultraplanLaunching && // 非正在启动
|
||||
hasUltraplanKeyword(inputString)) {
|
||||
// 重写为 /ultraplan 命令
|
||||
const rewritten = replaceUltraplanKeyword(inputString).trim()
|
||||
await processSlashCommand(`/ultraplan ${rewritten}`, ...)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.6 UI 层
|
||||
|
||||
#### 3.6.1 彩虹高亮 — `src/components/PromptInput/PromptInput.tsx`
|
||||
|
||||
当输入中检测到 `ultraplan` 关键字时：
|
||||
- 对每个字符施加**彩虹渐变色**高亮（`getRainbowColor()`）
|
||||
- 显示通知："This prompt will launch an ultraplan session in Claude Code on the web"
|
||||
|
||||
#### 3.6.2 预启动对话框 — `UltraplanLaunchDialog`
|
||||
|
||||
在 REPL 的 `focusedInputDialog === 'ultraplan-launch'` 时渲染。
|
||||
|
||||
用户选择：
|
||||
- **确认**：调用 `launchUltraplan()`，先添加命令回显，异步启动远程会话
|
||||
- **取消**：清除 `ultraplanLaunchPending` 状态
|
||||
|
||||
#### 3.6.3 计划选择对话框 — `UltraplanChoiceDialog`
|
||||
|
||||
在 `focusedInputDialog === 'ultraplan-choice'` 时渲染。
|
||||
|
||||
当 teleport 路径返回已审批计划时，用户可选择执行方式。
|
||||
|
||||
#### 3.6.4 Plan 审批按钮 — `ExitPlanModePermissionRequest`
|
||||
|
||||
本地 Plan Mode 的审批对话框中，如果 `feature('ULTRAPLAN')` 开启，会显示额外的 "Ultraplan" 按钮：
|
||||
- 将当前本地计划作为 `seedPlan` 发送给远程
|
||||
- 按钮仅在无活跃 ultraplan 会话时显示
|
||||
|
||||
### 3.7 应用状态 — `src/state/AppStateStore.ts`
|
||||
|
||||
```typescript
|
||||
interface AppState {
|
||||
ultraplanLaunching?: boolean // 防重入锁（5 秒窗口）
|
||||
ultraplanSessionUrl?: string // 活跃远程会话 URL
|
||||
ultraplanPendingChoice?: { // 已审批计划等待选择
|
||||
plan: string
|
||||
sessionId: string
|
||||
taskId: string
|
||||
}
|
||||
ultraplanLaunchPending?: { // 预启动对话框
|
||||
blurb: string
|
||||
}
|
||||
isUltraplanMode?: boolean // 远程端：CCR 侧的 ultraplan 标记
|
||||
}
|
||||
```
|
||||
|
||||
### 3.8 远程任务追踪 — `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx`
|
||||
|
||||
Ultraplan 使用 `RemoteAgentTask` 基础设施追踪远程会话：
|
||||
|
||||
```typescript
|
||||
registerRemoteAgentTask({
|
||||
remoteTaskType: 'ultraplan',
|
||||
session: { id, title },
|
||||
command: blurb,
|
||||
isUltraplan: true // 特殊标记，跳过通用轮询逻辑
|
||||
})
|
||||
```
|
||||
|
||||
`extractPlanFromLog()` 从 `<ultraplan>...</ultraplan>` XML 标签中提取计划内容。
|
||||
|
||||
---
|
||||
|
||||
## 四、数据流时序
|
||||
|
||||
```
|
||||
时间线 →
|
||||
|
||||
用户 本地 CLI CCR 云端
|
||||
│ │ │
|
||||
│ "ultraplan xxx" │ │
|
||||
│──────────────────────>│ │
|
||||
│ │ keyword 检测 + 重写 │
|
||||
│ │ /ultraplan "plan xxx" │
|
||||
│ │ │
|
||||
│ [UltraplanLaunch │ │
|
||||
│ Dialog] │ │
|
||||
│──── confirm ─────────>│ │
|
||||
│ │ launchDetached() │
|
||||
│ │─────────────────────────────>│
|
||||
│ │ teleportToRemote() │
|
||||
│ │ (permissionMode: 'plan') │
|
||||
│ │ │
|
||||
│ "Starting..." │ │
|
||||
│<──────────────────────│ │
|
||||
│ │ │
|
||||
│ (终端空闲，可继续) │ startDetachedPoll() │
|
||||
│ │ ═══ 3s 轮询循环 ═══ │
|
||||
│ │ │
|
||||
│ │ [浏览器打开]│
|
||||
│ │ [云端生成计划]
|
||||
│ │ │
|
||||
│ │ ← needs_input ─────────────│
|
||||
│ │ (云端追问用户) │
|
||||
│ │ │
|
||||
│ │ [用户在浏览器回复]
|
||||
│ │ │
|
||||
│ │ ← plan_ready ──────────────│
|
||||
│ │ (ExitPlanMode 等待审批) │
|
||||
│ │ │
|
||||
│ │ [用户审批/编辑]
|
||||
│ │ │
|
||||
│ ┌───────┤ ← approved ────────────────│
|
||||
│ │ │ │
|
||||
│ [远程执行] │ │ │
|
||||
│ 通知完成 │ │ │
|
||||
│ │ │ │
|
||||
│ └── OR ─┤ ← teleport ───────────────│
|
||||
│ │ │
|
||||
│ [UltraplanChoice │ │
|
||||
│ Dialog] │ │
|
||||
│── 选择执行方式 ───────>│ │
|
||||
│ │ 本地执行计划 │
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、关键文件清单
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/utils/ultraplan/keyword.ts` | 关键字检测、高亮位置计算、关键字替换 |
|
||||
| `src/utils/ultraplan/ccrSession.ts` | CCR 会话轮询、ExitPlanMode 状态机、计划文本提取 |
|
||||
| `src/utils/ultraplan/prompt.txt` | 远程指令模板（当前为空，需重建） |
|
||||
| `src/commands/ultraplan.tsx` | `/ultraplan` 命令、启动/停止逻辑、提示词构建 |
|
||||
| `src/utils/processUserInput/processUserInput.ts` | 关键字触发 → `/ultraplan` 命令路由 |
|
||||
| `src/components/PromptInput/PromptInput.tsx` | 彩虹高亮 + 通知提示 |
|
||||
| `src/screens/REPL.tsx` | 对话框渲染（UltraplanLaunchDialog / UltraplanChoiceDialog） |
|
||||
| `src/components/permissions/ExitPlanModePermissionRequest/` | Plan 审批中的 "Ultraplan" 按钮 |
|
||||
| `src/state/AppStateStore.ts` | ultraplan 相关状态字段定义 |
|
||||
| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` | 远程任务追踪 + `<ultraplan>` 标签提取 |
|
||||
| `src/constants/xml.ts` | `ULTRAPLAN_TAG = 'ultraplan'` |
|
||||
|
||||
---
|
||||
|
||||
## 六、依赖关系
|
||||
|
||||
### 外部依赖
|
||||
|
||||
| 依赖 | 用途 | 必要性 |
|
||||
|------|------|--------|
|
||||
| `teleportToRemote()` | 创建 CCR 云端会话 | 必须 — 核心功能 |
|
||||
| `checkRemoteAgentEligibility()` | 验证用户远程 agent 使用资格 | 必须 — 前置检查 |
|
||||
| `archiveRemoteSession()` | 归档/终止远程会话 | 必须 — 清理 |
|
||||
| GrowthBook `tengu_ultraplan_model` | 获取使用的模型 ID | 可选 — 默认 opus46 |
|
||||
| `@anthropic-ai/sdk` | SDKMessage 类型 | 必须 — 类型定义 |
|
||||
| `pollRemoteSessionEvents()` | 事件流分页轮询 | 必须 — 轮询基础设施 |
|
||||
|
||||
### 内部依赖
|
||||
|
||||
- **ExitPlanModeV2Tool**：远程端调用的工具，触发 plan 审批流程
|
||||
- **RemoteAgentTask**：任务追踪和状态管理基础设施
|
||||
- **AppState Store**：ultraplan 状态管理
|
||||
|
||||
---
|
||||
|
||||
## 七、当前状态与补全要点
|
||||
|
||||
| 组件 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 关键字检测 | ✅ 完整 | `keyword.ts` 逻辑完善 |
|
||||
| 命令框架 | ✅ 完整 | 注册、路由、防重入完整 |
|
||||
| 启动流程 | ✅ 完整 | `launchUltraplan` / `launchDetached` 完整 |
|
||||
| CCR 轮询 | ✅ 完整 | `ccrSession.ts` 状态机完整 |
|
||||
| UI 高亮/通知 | ✅ 完整 | 彩虹高亮 + 提示通知完整 |
|
||||
| 状态管理 | ✅ 完整 | AppState 字段完整 |
|
||||
| `prompt.txt` | ❌ 空文件 | 需要重建远程指令模板 |
|
||||
| `UltraplanLaunchDialog` | ⚠️ 全局声明 | 组件实现未找到（可能在内置包中） |
|
||||
| `UltraplanChoiceDialog` | ⚠️ 全局声明 | 组件实现未找到（可能在内置包中） |
|
||||
| `isEnabled` 限制 | ⚠️ `USER_TYPE === 'ant'` | 命令级限制，仅 Anthropic 内部用户 |
|
||||
|
||||
### 补全建议
|
||||
|
||||
1. **重建 `prompt.txt`**：这是远程 agent 的核心指令，定义如何进行多 agent 探索式规划。需要设计：
|
||||
- 规划方法论（多角度分析、风险评估、分阶段执行）
|
||||
- ExitPlanMode 工具的使用引导
|
||||
- 输出格式要求
|
||||
|
||||
2. **对话框组件**：`UltraplanLaunchDialog` 和 `UltraplanChoiceDialog` 在 `global.d.ts` 中声明但实现缺失，需要新建：
|
||||
- Launch Dialog：确认对话框（含 CCR 使用条款链接）
|
||||
- Choice Dialog：展示已审批计划 + 执行方式选择
|
||||
|
||||
3. **放宽 `isEnabled`**：如果要让非 ant 用户使用斜杠命令，需移除 `USER_TYPE === 'ant'` 检查
|
||||
|
||||
---
|
||||
|
||||
## 八、与相关 Feature 的关系
|
||||
|
||||
| Feature | 关系 |
|
||||
|---------|------|
|
||||
| `ULTRATHINK` | 类似的高能力模式，但 `ULTRATHINK` 只调高 effort，不启动远程会话 |
|
||||
| `FORK_SUBAGENT` | Ultraplan 不使用 fork subagent，使用的是 CCR 远程 agent |
|
||||
| `COORDINATOR_MODE` | 不同范式的多 agent，Coordinator 在本地编排，Ultraplan 在云端 |
|
||||
| `BRIDGE_MODE` | 底层依赖相同的 `teleportToRemote()` 基础设施 |
|
||||
| `ExitPlanModeTool` | 远程端的审批机制，Ultraplan 的核心交互模型 |
|
||||
Reference in New Issue
Block a user