AI Research 技术调研

Claude Code (Anthropic)：无公开源码，经 sourcemap 泄露还原的一手 agent harness

52分钟阅读

Claude Code (Anthropic)

一句话定位

Claude Code 没有公开源码——Anthropic 只通过 npm 分发打包后的 cli.js；本 dossier 基于一份非官方泄露的还原源码（来自 cli.js.map sourcemap 的 sourcesContent 字段，2026-03-31 由第三方公开）加上 6 篇官方工程博客交叉验证写成。核心特征：显式声明”stop_reason==='tool_use' 不可信”、只用”是否流出了 tool_use block”判断继续/停止的单一权威信号；四层级联的上下文压缩（HISTORY_SNIP → microcompact → context-collapse → autocompact/reactive-compact）；系统提示里硬编码了一条强制性对抗式验证契约（非平凡改动必须派生 verification-agent 子 agent 审核，实现者不能自评通过）；OS 级沙箱（bubblewrap/Seatbelt）与”auto mode”两阶段 transcript 分类器并行、互补而非替代关系。

核心架构总览（目录结构关键路径 + 引用的 commit）

  • 来源与置信度声明（务必先读）：真实一手源码不可得。本 dossier 引用的所有文件路径均来自本地非官方提取目录 /Users/zhao/projects/chatgptprojects-claude-code（其自身 README 声明：从官方 npm 包内 cli.js.map 的 sourcesContent 字段解包而得——这是真实的、未混淆的原始 .ts/.tsx 文件泄露，不是逆向猜测/重构）。该提取无 git 历史/commit SHA，版本锚点是 package.json 里的 "version": "2.1.88"，并在 src/utils/sessionStorage.ts:99 的 MACRO.VERSION 引用处独立确认。泄露者：@Fried_rice (Chaofan Shou)，公开时间 2026-03-31。全篇统一以 npm v2.1.88 作为版本锚点，等价于其他 dossier 里的”commit”字段。
  • 官方一手信源作为交叉验证补充：6 篇 Anthropic 工程博客（2025-04 至 2026-05，覆盖 context engineering / agent skills / sandboxing / auto mode / containment / best practices），本地存档见文末”一手源存档”。
  • 目录结构（据提取源码的文件树，未逐目录全读，标注”读取深度”）：
src/
├── query.ts                    — 主 agent 循环 queryLoop()（1729 行，全文读完）
├── QueryEngine.ts               — 会话/turn 生命周期封装，SDK/headless 消费入口（1296 行，全文读完）
├── Tool.ts                      — Tool 规范类型 + buildTool() 默认值（793 行，全文读完）
├── Task.ts                      — 后台任务簿记（126 行，全文读完）
├── query/deps.ts                 — query() 的依赖注入 seam（测试用）
├── constants/prompts.ts          — 系统提示装配（914 行，按 section 边界抓读，非线性通读）
├── coordinator/coordinatorMode.ts — 协调者模式（仅表层引用，未深读）
├── tools/                        — ~40 个内置工具目录
│   ├── AgentTool/AgentTool.tsx    — Task/子 agent 工具（部分读，约 250/更长 行）
│   ├── SkillTool/SkillTool.ts     — Skill 工具（1109 行，全文读完）
│   ├── BashTool/{bashSecurity,shouldUseSandbox,bashPermissions,bashClassifier}.ts — 仅结构 grep
│   └── shared/spawnMultiAgent.js  — "teams" 多 agent 生成（未深读）
├── skills/
│   ├── loadSkillsDir.ts           — skill 目录扫描/frontmatter 解析（部分读，~150 行）
│   └── bundled/*.ts               — 内置一等公民 skill（batch/claudeApi/verify/simplify/updateConfig 等）
├── services/
│   ├── compact/{autoCompact,microCompact,reactiveCompact,snipCompact}.ts — 压缩四件套（autoCompact 部分读 ~120 行，其余仅 grep）
│   ├── extractMemories/extractMemories.ts — 会后台自动记忆抽取（616 行，全文读完）
│   ├── SessionMemory/*            — 另一独立的"会话记忆"压缩子系统（仅文件列表，未深读，标记为待补）
│   ├── analytics/index.ts         — 一方遥测事件队列（部分读 ~100 行）
│   ├── AgentSummary/agentSummary.ts — 子 agent 进度周期性摘要（部分读 ~80 行）
│   ├── contextCollapse/index.js   — 上下文"折叠"分级机制（未直接读，凭调用点推断）
│   └── PromptSuggestion/          — 疑似 prompt/skill 改进反馈闭环（未读，flag 待补）
├── memdir/*                       — 自动记忆子系统（findRelevantMemories/memoryScan 等，仅文件列表）
├── utils/
│   ├── permissions/{permissions,yoloClassifier,PermissionMode}.ts — 权限引擎 + auto-mode 分类器（permissions.ts 部分读 ~200 行；yoloClassifier.ts 已 grep 确认核心函数）
│   ├── sandbox/sandbox-adapter.ts — Claude Code 对 @anthropic-ai/sandbox-runtime 的封装（986 行，全文读完）
│   ├── hooks.ts, hooks/*          — hook 事件类型与执行器（仅结构 grep，含 skillImprovement.ts 未深读）
│   ├── queryContext.ts            — 系统提示 cache-key 前缀装配（部分读 ~150 行）
│   └── sessionStorage.ts          — 会话 JSONL 持久化（部分读 ~100 行）
├── entrypoints/agentSdkTypes.ts   — 公开 Agent SDK 消息类型（未打开，flag 待补）
├── coordinator/, plugins/, schemas/, bridge/, components/ — 目录级侦察，未逐文件读

Agent Loop（主循环 / 何时继续何时停）

  • 核心实现：src/query.ts 的 queryLoop()（async function* 生成器），外层薄壳 query()（query.ts:219-239）只负责 loop 结束后清理 consumedCommandUuids 簿记。
  • 结构：while (true) { 流式调模型 → 跑工具 → 决定继续或返回 }；状态经由带显式 transition 原因字符串的 State 对象传递（如 next_turn、stop_hook_blocking、collapse_drain_retry、reactive_compact_retry、max_output_tokens_escalate、token_budget_continuation，query.ts:204-217 类型定义，贯穿全文使用）——每次 loop 重入都记录”为什么继续”。
  • 继续条件：唯一权威信号是流式过程中是否出现过 tool_use block（needsFollowUp 标志，在 msgToolUseBlocks.length > 0 时于 query.ts:834 置位）。代码注释明确指出 stop_reason === 'tool_use' 不可信（query.ts:554：“Note: stop_reason === ‘tool_use’ is unreliable”）。
  • 停止条件：!needsFollowUp 分支（query.ts:1062 起）——在真正 return { reason: 'completed' }（query.ts:1357）之前，loop 还可能因为以下工程化理由继续跑：
    • prompt-too-long 恢复：先 context-collapse drain，再 reactive-compact 重试（query.ts:1085-1183）
    • max_output_tokens 恢复：先”把 cap 升到 64k 同请求重试”一次（ESCALATED_MAX_TOKENS，约 query.ts:1195-1221），再最多 MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3（query.ts:164）次注入合成”直接续写”用户消息并循环
    • Stop-hooks（handleStopHooks，来自 src/query/stopHooks.ts）可通过 blockingErrors 强制再跑一轮（query.ts:1282-1306）——这是 hook 驱动”你还没做完”行为的实现点
    • Token-budget 续跑提醒（feature('TOKEN_BUDGET') 开关，query.ts:1308-1355）——预算未耗尽时注入”nudge message”并继续循环，否则记录 tengu_token_budget_completed 完成事件
  • 轮次计数：turnCount 每次带新工具结果的递归续接加一（query.ts:1679，nextTurnCount = turnCount + 1）；maxTurns 硬顶（query.ts:1705-1712，命中后 yield max_turns_reached 附件再返回）。
  • 模型中途降级：FallbackTriggeredError 捕获（query.ts:893-953）会作废（tombstone）当前部分 assistant 消息（清掉失效的 thinking-signature block），切换 currentModel = fallbackModel，通过一个独立于主 turn loop 的外层 attemptWithFallback while 循环重试。
  • 流式工具执行由 StreamingToolExecutor（src/services/tools/StreamingToolExecutor.js）在 config.gates.streamingToolExecution 开关打开时接管，否则退回 runTools()（src/services/tools/toolOrchestration.js）——工具可以在模型仍在流式输出后续内容块时就开始执行（query.ts:561-568, 851-862）。
  • QueryEngine.submitMessage()（src/QueryEngine.ts:209-1156）是每 turn 的外层封装：装配一次系统提示、驱动 query() 跑到完成、把内部 Message 类型翻译成对外的 SDKMessage 类型（供 Agent SDK/headless 消费方使用）、发出终态 result 消息（success / error_max_turns / error_max_budget_usd / error_max_structured_output_retries / error_during_execution）。

记忆与上下文管理（压缩、长期记忆、会话持久化）

  • 自动压缩（src/services/compact/autoCompact.ts）：触发阈值为 getAutoCompactThreshold(model) = 模型有效上下文窗口 − AUTOCOMPACT_BUFFER_TOKENS（13,000，line 62）。getEffectiveContextWindowSize() 为压缩摘要自身输出预留 min(maxOutputTokensForModel, 20_000) tokens（lines 30-48）。熔断器 MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3（line 70）——注释引用真实故障：“BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures … wasting ~250K API calls/day globally”（lines 68-70）。
  • 据官方博客（“Effective context engineering…“）：压缩”把消息历史交给模型总结压缩最关键细节。模型保留架构决策、未解决的 bug 和实现细节，丢弃冗余的工具输出……agent 随后带着压缩后的上下文加上最近访问的 5 个文件继续”（“最近 5 个文件”这一细节只在博客出现，未在读到的代码里直接确认，但结合 Tool.ts 里的 readFileState/FileStateCache 机制来看是合理的）。
  • 压缩与其他几种上下文缩减机制分层叠加，都在 query.ts 内可见，均受 feature() 开关控制（bun:bundle 编译期特性开关——意味着部分机制可能不在每个 build/channel 中启用）：
    • HISTORY_SNIP（services/compact/snipCompact.ts）——在 microcompact 之前清除”僵尸消息”/失效标记
    • microcompact（services/compact/microCompact.ts，经 deps.microcompact 始终启用）——更细粒度的压缩，先于完整 autocompact 运行，含一个”cached microcompact”变体，直接编辑 prompt cache 并上报 API 实际返回的 cache_deleted_input_tokens（query.ts:866-892）
    • CONTEXT_COLLAPSE（services/contextCollapse/index.js）——一个分阶段”折叠”机制，自带 413（prompt-too-long）错误的 drain/恢复路径，在 autocompact 之前应用，若折叠本身已让 token 数低于阈值，autocompact 就变成 no-op（query.ts:428-447）
    • REACTIVE_COMPACT（services/compact/reactiveCompact.ts）——一种反应式（413 真正发生之后的事后）压缩路径，区别于每次 API 调用前运行的主动式 autocompact
  • 会话持久化/恢复：transcript 为 JSONL，经 recordTranscript() / src/utils/sessionStorage.ts 写入（JSONL 追加，路径解析在 ~/.claude/projects/<sanitized-cwd>/... 下）。压缩边界是显式消息类型（system/compact_boundary），compactMetadata.preservedSegment.tailUuid 用于在恢复时从持久化 transcript 里裁剪掉压缩前的消息（QueryEngine.ts:701-715、query.ts:918-933）。
  • 长期/自动记忆：src/services/extractMemories/extractMemories.ts ——一个后台分叉子 agent进程，在每次完整 query loop 结束时（经 handleStopHooks）运行，把持久化笔记写入 ~/.claude/projects/<path>/memory/（“自动记忆目录”，受 isAutoMemoryEnabled() 及 GrowthBook 开关 tengu_passport_quail 控制）。它使用一个受限的 canUseTool（createAutoMemCanUseTool，lines 171-222）——只无条件允许 Read/Grep/Glob、只读 Bash，以及仅限于自动记忆目录内的 Edit/Write——即写记忆的子 agent 碰不到用户的真实代码。互斥保护：若主 agent 本轮已写过记忆目录，分叉的抽取器就跳过（避免重复/竞争写入，hasMemoryWritesSince()，lines 121-148）。基于游标（lastMemoryMessageUuid）只处理新消息；节流由 GrowthBook tengu_bramble_lintel 控制（每 N 轮，默认 1）。
  • 存在独立的 src/services/SessionMemory/ 子系统（sessionMemoryCompact.ts、sessionMemoryUtils.ts）——与 CLAUDE.md/自动记忆系统是不同的”会话记忆”压缩路径；未深读，标记为待补。
  • CLAUDE.md：据 context-engineering 博客，“CLAUDE.md 文件在会话开始时被直接塞进上下文，而 glob/grep 等原语让它可以按需导航环境、即时检索文件”——一种预加载 + 按需检索的混合策略。代码里，嵌套 CLAUDE.md 的加载通过 loadedNestedMemoryPaths（ToolUseContext 上的去重 set，Tool.ts:216-222）追踪，避免同一 session 内重复注入同一文件（否则 readFileState 这个 LRU 缓存被驱逐后会导致重复注入）。

工具体系（定义/调用协议/注册/权限）

  • 规范 Tool<Input, Output, Progress> 类型定义在 src/Tool.ts:362-695。每个工具经 buildTool()（lines 783-792）构建，填充安全默认值（isEnabled→true、isConcurrencySafe→false、checkPermissions→allow 等，TOOL_DEFAULTS 见 lines 757-769）——文档注释称之为”在紧要处 fail-closed”。
  • 每个工具声明：Zod inputSchema（MCP 工具可选带原始 JSON-schema）、outputSchema、call()、checkPermissions()、validateInput()、isReadOnly/isDestructive/isConcurrencySafe 谓词，以及一大批渲染钩子（renderToolUseMessage、renderToolResultMessage、renderToolUseRejectedMessage、renderGroupedToolUse 等）——工具自己负责终端 UI 渲染，而非走通用渲染器。
  • 延迟工具/懒加载协议：shouldDefer / alwaysLoad 字段（Tool.ts:438-449）——工具可以带 defer_loading: true 发给模型，只有通过 ToolSearch 工具调用才完全解析，与本 dossier 编写过程中所在这个 session 自身的 “ToolSearch” 机制完全对应；searchHint（Tool.ts:372-378）是搜索时使用的关键词字符串。
  • 约 40 个内置工具实现位于 src/tools/ 下（仅目录名，未逐个读）：AgentTool（子 agent/Task）、SkillTool、BashTool、PowerShellTool、FileReadTool、FileEditTool、FileWriteTool、GlobTool、GrepTool、NotebookEditTool、LSPTool、MCPTool、McpAuthTool、ListMcpResourcesTool、ReadMcpResourceTool、WebFetchTool、WebSearchTool、TodoWriteTool、AskUserQuestionTool、EnterPlanModeTool/ExitPlanModeTool、EnterWorktreeTool/ExitWorktreeTool、TaskCreateTool/TaskGetTool/TaskListTool/TaskOutputTool/TaskStopTool/TaskUpdateTool（后台任务管理）、TeamCreateTool/TeamDeleteTool/SendMessageTool（多 agent “teams”）、ScheduleCronTool、RemoteTriggerTool、SleepTool、ToolSearchTool、SyntheticOutputTool、BriefTool、REPLTool、ConfigTool。
  • MCP 作为工具来源：所有 MCP 来源的工具都带 mcpInfo 字段（{serverName, toolName}），不论命名前缀模式如何；CLAUDE_AGENT_SDK_MCP_NO_PREFIX 环境变量控制 MCP 工具名是否加 mcp__server__tool 前缀（Tool.ts:450-455）。
  • 权限协议：checkPermissions(input, context) → PermissionResult（behavior: 'allow'|'ask'|'deny'，附 updatedInput、decisionReason、可选 suggestions 用于持久化一条”总是允许”规则）。核心引擎 src/utils/permissions/permissions.ts 从带标签的 decisionReason 联合类型构建人类可读的 createPermissionRequestMessage()：hook、rule、subcommandResults（针对复合 Bash 命令——审批粒度可细到子命令级）、permissionPromptTool、sandboxOverride、workingDir、safetyCheck、mode、classifier（受 BASH_CLASSIFIER/TRANSCRIPT_CLASSIFIER 开关控制）、other。
  • 规则来源与优先级：PERMISSION_RULE_SOURCES = 标准设置来源（SETTING_SOURCES）加上 cliArg、command、session（permissions.ts:109-114）——即规则可来自策略/托管设置、用户设置、项目设置、CLI 参数、会话内斜杠命令，或临时的单会话授权。
  • 并发安全性（isConcurrencySafe）决定一个 assistant turn 内多个工具调用能否并行执行；interruptBehavior()（'cancel'|'block'）决定用户在工具运行中提交新消息时如何处理正在跑的工具。

Prompt 设计（系统提示结构、动态组装）

  • 由 src/constants/prompts.ts 的 getSystemPrompt() 构建（全文 914 行，按 section 边界抓读，非线性通读）。由许多小的 section-builder 函数组成，根据会话状态条件式装配——是真正的动态组装，不是静态模板：
    • getSimpleIntroSection() —— 开场白：“You are an interactive agent that helps users {according to Output Style | with software engineering tasks}. …”（line 180）——随 Output Style 变化措辞。
    • getSimpleSystemSection()、getSimpleDoingTasksSection() —— 含字面帮助文本如 /help: Get help with using Claude Code（line 217）及 /issue、/share 元 bug 上报的斜杠命令自引用（line 245）。
    • getUsingYourToolsSection(enabledTools) —— 工具使用指导，按本会话实际启用的工具参数化（line 269）。
    • getAgentToolSection()、getDiscoverSkillsGuidance() —— 仅在子 agent/skill 可用时才条件性纳入（lines 316, 333）。
    • getSessionSpecificGuidanceSection() —— 包含一条极其详细的强制性对抗式验证契约（line 394）：“当本轮出现非平凡实现改动时，必须先经过独立对抗式验证再报告完成……’非平凡’指：3+ 文件编辑、后端/API 改动、或基础设施改动。派生 [Agent] 工具，subagent_type=‘verification-agent’……只有验证者能给出裁决，你不能自评 PARTIAL。“——这是硬编码在系统提示里的非可选治理规则，不只是建议。
    • getOutputEfficiencySection()、getSimpleToneAndStyleSection() —— 输出长度/风格校准。
    • getProactiveSection()（line 860）—— 用于自主/“proactive”模式，注入：“You are running autonomously. You will receive <tick> prompts that keep you alive between turns — just treat them as ‘you’re awake, what now?‘”——确认了一个用于无人值守运行的心跳/tick 机制。
    • getMcpInstructions(mcpClients)（line 579）—— 仅在有 MCP server 连接时追加。
    • computeEnvInfo() / computeSimpleEnvInfo()（lines 606, 651）—— 注入实时环境事实：CWD、日期、模型营销名+精确模型 ID（“You are powered by the model named {name}. The exact model ID is {id}.”，line 626）、平台可用性说明、Fast Mode 解释（“使用同一个 {model} 但输出更快……不会切换到不同模型”，line 702）。
    • getKnowledgeCutoff(modelId)（line 713）、getShellInfoLine() / getUnameSR()（lines 732, 745）—— shell + OS/uname 指纹注入上下文。
    • DEFAULT_AGENT_PROMPT（line 758）—— 通用子 agent 系统提示：“You are an agent for Claude Code… Complete the task fully—don’t gold-plate, but don’t leave it half-done… respond with a concise report…”——注意每个子 agent 都带的显式反过度工程（“don’t gold-plate”）指令。
    • getScratchpadInstructions()（line 797）—— 暂存目录指引（与本 session 自身的 scratchpad 约定对应）。
    • getFunctionResultClearingSection(model)（line 821）—— 特定模型的上下文清理指导。
  • 装配顺序（QueryEngine.ts:321-325）：[...customPrompt-或-defaultSystemPrompt, ...memoryMechanicsPrompt-若存在, ...appendSystemPrompt-若存在] 经 asSystemPrompt() 拼接。customSystemPrompt（SDK 参数）会完全替换默认装配，而非在其基础上追加。
  • 缓存键纪律：fetchSystemPromptParts()（src/utils/queryContext.ts:44-74）专门用于产出稳定的 (systemPrompt, userContext, systemContext) 三元组作为 Anthropic prompt-cache 前缀——注释明确将其定位为跨 turn/fork 共享 API prompt cache（renderedSystemPrompt 在 turn 开始时对分叉子 agent 冻结，Tool.ts:293-299，避免 GrowthBook 开关中途翻转导致 cache 失效）。

Router / 编排（任务分解、多 agent、子 agent）

  • AgentTool（Task 工具） —— src/tools/AgentTool/AgentTool.tsx —— 是子 agent 生成原语。输入 schema（lines 82-102）：description、prompt、subagent_type（可选）、model（sonnet/opus/haiku 覆盖，优先级高于 agent-definition frontmatter，否则回退到 definition 或继承父级）、run_in_background（bool）。受开关控制的”多 agent”扩展（fullInputSchema）新增 name（可经 SendMessageTool 寻址）、team_name、mode（生成的 teammate 权限模式，如 "plan"）、isolation（"worktree" = 临时 git worktree；"remote" = 在远程 CCR 沙箱中启动，据代码注释为 ant/内部专用）、以及 cwd 覆盖。
  • 内置 agent 类型位于 src/tools/AgentTool/built-in/ 下：general-purpose（generalPurposeAgent.ts，agentType: 'general-purpose'）、explore（exploreAgent.ts）、plan（planAgent.ts）、verification-agent（verificationAgent.ts —— 上文系统提示中提到的强制验证者）、claudeCodeGuideAgent.ts、statuslineSetup.ts。builtInAgents.ts 暴露 getBuiltInAgents()，受 areExplorePlanAgentsEnabled() 控制。
  • 异步/后台 agent：run_in_background: true 经 LocalAgentTask 机制生成（registerAsyncAgent、updateAgentProgress、completeAgentTask/failAgentTask、killAsyncAgent，均来自 src/tasks/LocalAgentTask/LocalAgentTask.js，AgentTool.tsx:14）。120 秒后自动转后台可通过环境变量（CLAUDE_AUTO_BACKGROUND_TASKS）或 GrowthBook 开关 tengu_auto_background_agents 启用（AgentTool.tsx:72-77），即长耗时子 agent 调用可在用户无操作的情况下被静默提升为后台任务。
  • 分叉子 agent 模式（forkSubagent.ts，全文多处引用）：一种缓存共享的分叉机制，区别于通用 Task 工具——用于廉价的”旁支”工作（记忆抽取、agent 进度摘要、context: 'fork' 模式下的 skill 调用），复用父级已渲染的系统提示/prompt cache 而非重新渲染。显式经 CacheSafeParams（utils/forkedAgent.ts）传递。
  • 远程隔离/CCR：isolation: 'remote' 路径检查 checkRemoteAgentEligibility() / registerRemoteAgentTask()（src/tasks/RemoteAgentTask/RemoteAgentTask.js）——一个独立的远程执行环境（“CCR”缩写，读到的代码中未展开），用于不该本地跑的 agent 任务。
  • Worktree 隔离：isolation: 'worktree' 创建一个真实的临时 git worktree（createAgentWorktree/removeAgentWorktree、hasWorktreeChanges、src/utils/worktree.js），让子 agent 编辑独立的工作副本——一种轻量级、git 原生的沙箱机制，独立于 OS 级沙箱。还有一个”worktree notice”（buildWorktreeNotice，forkSubagent.ts）大概率会呈现给模型。
  • “Teams”：TeamCreateTool/TeamDeleteTool/SendMessageTool 加上 spawnTeammate()（src/tools/shared/spawnMultiAgent.js）以及 in_process_teammate 作为 TaskType（Task.ts:10）——一种命名、可寻址的多 agent 模式（“teammates”），叠加在基础子 agent 原语之上；受 isAgentSwarmsEnabled() 控制。未深入探索，标记为待补。
  • 协调者模式：src/coordinator/coordinatorMode.ts（文件存在，未深读）——激活时向 userContext 注入 getCoordinatorUserContext()（QueryEngine.ts:304-308），暗示存在一个区别于默认 REPL 驱动 Task 工具的独立”协调者”编排模式。isCoordinatorMode() 在 SkillTool.ts 的导入列表中被引用。
  • Agent 进度上报：AgentSummary/agentSummary.ts 每 30 秒分叉一次子 agent 自身的 transcript，生成 1-2 句现在时进度描述供 UI 显示（例如”Reading runAgent.ts”而非”Analyzed the branch diff”——prompt 中直接内置了这类显式 few-shot 示例，lines 33-43）——这是 UI 打磨，非功能性编排负载，但体现了子 agent 可观测性的深度。
  • 本轮未发现独立”planner 模型”或与模型自身工具调用分离的显式 DAG 任务分解引擎——任务分解看起来完全是模型自主选择调用 AgentTool 加子提示时”涌现”出来的，而非独立的规划组件。

Skill / 插件体系

  • Skill = 带 SKILL.md 的目录（frontmatter 必需字段：name、description）——代码（src/skills/loadSkillsDir.ts、parseFrontmatter）与官方博客均确认。渐进式披露（progressive disclosure），3 级以上：(1) 每个已安装 skill 的 name+description 在启动时预加载进系统提示；(2) 仅当 Claude 判断该 skill 相关时才把完整 SKILL.md 正文载入上下文；(3)+ 打包的辅助文件（如 reference.md、forms.md）只在需要时按 SKILL.md 中的引用按需读取。据博客：“打包进 skill 的上下文量实际上不受限”，因为大部分内容永远不会被加载。
  • Skill 可以打包可执行代码（如 Python 脚本），Claude 将其作为工具运行，“既不把脚本也不把[数据]载入上下文”——把确定性操作从 token 生成中卸载（博客原文）。
  • SkillTool（src/tools/SkillTool/SkillTool.ts）是调用界面：inputSchema = {skill: string, args?: string}。两种执行模式：
    • inline（默认）：通过 processPromptSlashCommand() 展开进当前对话——与用户手打 /skill-name 走同一代码路径，支持 !command shell 替换和 $ARGUMENTS 插值（SkillTool.ts:634-647）。
    • forked（command.context === 'fork'）：在隔离的分叉子 agent 中运行技能（executeForkedSkill()，lines 122-289），有自己的 token 预算，经 prepareForkedCommandContext() 共享父级 prompt cache。
    • 第三种远程/canonical 路径（_canonical_<slug> 命名）为 ant/内部专用，受 feature('EXPERIMENTAL_SKILL_SEARCH') + process.env.USER_TYPE === 'ant' 双重开关，从远程存储（GCS/HTTP/S3，按 extractUrlScheme() 判断）加载 SKILL.md 并本地缓存（lines 969-1108）。此路径为 Anthropic 内部专用，不应描述为通用 Claude Code 功能。
    • Skill 权限模型：allow/deny 规则按精确 skill 名或前缀匹配（"review:*"）；一份”安全” PromptCommand 属性白名单（SAFE_SKILL_PROPERTIES，lines 875-908）——若 skill 定义只包含安全元数据字段，可自动授权执行不弹审批；任何未识别字段都强制走 ask 决策（面向未来 schema 新增字段的 fail-closed 设计，lines 910-933）。
  • Skill 来源/加载优先级：getSkillsPath()（loadSkillsDir.ts:78-94）按来源解析路径——policySettings → 托管目录，userSettings → ~/.claude/skills，projectSettings → .claude/skills，plugin → 插件内置 skill。LoadedFrom 联合类型：commands_DEPRECATED | skills | plugin | managed | bundled | mcp —— 确认MCP server 本身也能暴露”skills”（MCP prompts，在 SkillTool.getAllCommands() 中被过滤为 loadedFrom === 'mcp' 且类型为 'prompt'，lines 81-94），与基于文件系统的 skill 并存。
  • 内置 skill：src/skills/bundled/ 以代码（非 markdown）形式打包一方 skill：batch.ts、claudeApi.ts、claudeInChrome.ts、debug.ts、keybindings.ts、loop.ts、remember.ts、scheduleRemoteAgents.ts、simplify.ts、skillify.ts、stuck.ts、updateConfig.ts、verify.ts —— 其中多个名字与本次任务所在这个 session 自身的 skill 列表一一对应（update-config、verify、simplify），确认 Claude Code 把自己的部分元工具能力打包为内置 skill，而非硬编码命令。
  • 插件系统：与 skill 分离但有重叠——src/plugins/、src/commands/plugin/*（marketplace 浏览/添加/管理 UI 组件）、isOfficialMarketplaceName()/parsePluginIdentifier()——插件可打包 skill（command.source === 'plugin'、pluginInfo.repository），且对”官方 marketplace”插件与第三方插件有一等区分（用于遥测/信任目的：非官方 marketplace 来源的 skill 调用事件记录 plugin_name: 'third-party'，隐去真实名字——SkillTool.ts:718-724）。
  • 安全指引（博客 “Equipping agents…“）：“只从可信来源安装 skill……彻底审查……特别关注代码依赖和打包资源……skill 内是否有指令或代码引导 Claude 连接到潜在不可信的外部网络来源”——Anthropic 自己对 skill 的威胁模型基本等同于对待任何第三方代码依赖。
  • Skill 发现遥测：ToolUseContext 上的 discoveredSkillNames 集合（Tool.ts:225）驱动一个 was_discovered 分析字段——区分”模型通过主动发现/搜索找到”与”模型已从静态系统提示列表中得知”。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

  • 本 harness 代码中未发现权重级自我改进或微调闭环（符合预期——那属于 Anthropic 内部模型训练范畴，超出 CLI 代码库的范围）。存在的是若干会话/行为级自我纠错机制：
    • 对抗式验证契约（见”Prompt 设计”节）——系统提示强制要求独立验证子 agent（verification-agent）在主 agent 报告完成之前审核任何非平凡改动，且明确禁止实现者（或其分叉出的帮手）自评通过。这是发现的最具体的”eval 驱动纠错”机制——它内置于每个会话，非可选项。
    • 自动记忆抽取（见”记忆与上下文管理”节）——harness 在每轮结束时从 transcript 中提炼”持久记忆”写入文件，供未来会话重新注入（findRelevantMemories.ts、memoryScan.ts）——一种粗糙但真实的跨会话学习型上下文累积（非权重更新，而是持久化的行为上下文）。
    • skillImprovement.ts（src/utils/hooks/skillImprovement.ts）与一个 SkillImprovementSurvey.tsx 组件（src/components/）存在——名字强烈暗示”基于观察到的失败标记/改进 skill”的机制，但本轮未读取文件内容（标记为待补，很可能是”自进化”叙事最有前景的线索）。
    • hooks/skillImprovement.ts、PromptSuggestion 服务（src/services/PromptSuggestion/）、FeedbackSurvey/usePostCompactSurvey.tsx / useMemorySurvey.tsx 组件名暗示还有额外的”询问用户确认有效方案”反馈闭环，反哺 skill/prompt 调优——同样本轮未深读。
    • getStuck 内置 skill（src/skills/bundled/stuck.ts）——一个命名为”我卡住了”的 skill，暗示存在自诊断失败恢复路径（未深读）。
  • 明确不存在的：无实时梯度更新、无本地微调、CLI 内部无 RLHF 风格奖励闭环。任何”学习”都是 prompt/上下文/记忆层面，而非模型权重层面，且存活于客户端文件（~/.claude/ 下）而非按用户集中聚合（训练数据的聚合发生在独立的分析/遥测管道，见”可观测性”与”轨迹利用”节）。

可观测性（日志 / trace 格式）

  • 一方分析管道：src/services/analytics/index.ts——一个无依赖的事件队列（logEvent(eventName, metadata)），在启动时 attachAnalyticsSink() 运行前先缓冲事件，之后扇出到 AnalyticsSink（Datadog + “1P”/一方 BigQuery 风格事件记录，据 firstPartyEventLoggingExporter.ts 文件名）。类型系统内置强 PII 纪律：AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 与 AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED 是 never 类型标记，强制每个调用点显式 as 断言——即利用类型系统强制人工核实记录的字符串不是代码/文件路径/PII（index.ts:11-33）。_PROTO_* 前缀的字段路由到具备访问控制的特权 BQ 列，在到达 Datadog 等通用访问 sink 前被剥离（stripProtoFields()，lines 45-58）。
    • 全代码库可见数百个命名事件，均以 tengu_* 为前缀（Claude Code 内部代号）——如 tengu_auto_compact_succeeded、tengu_query_error、tengu_model_fallback_triggered、tengu_skill_tool_invocation、tengu_extract_memories_extraction、tengu_token_budget_completed、tengu_streaming_tool_execution_used。每个事件携带 queryChainId/queryDepth 对（QueryChainTracking 类型，Tool.ts:90-93），使得嵌套/递归的 query 调用（子 agent、分叉、重试）即使是独立的 query() 调用也能在分析数据中被关联起来。
  • 会话 transcript 格式：JSONL，每行一个 Entry，经 recordTranscript()（src/utils/sessionStorage.ts）写入，存储在 ~/.claude/projects/<sanitized-cwd>/... 下。消息类型包括 assistant、user、system（子类型如 compact_boundary、api_error、local_command）、progress、attachment、tombstone（显式移除标记，例如模型降级后失效的孤立 thinking block）、tool_use_summary。SDKMessage 类型（src/entrypoints/agentSdkTypes.ts，未打开）是这些消息面向 Agent SDK/headless 消费方的公开投影。
  • 内存内错误环形缓冲区：getInMemoryErrors()（src/utils/log.ts）——一个有界（约 100 条）缓冲区，用于 error_during_execution 结果的 turn 级诊断转储（query.ts / QueryEngine.ts:1106-1115）；使用”水位线”索引（turn 开始时的最后一条错误）而非长度偏移，专门是因为环形缓冲区的 shift() 会使朴素索引失效（QueryEngine.ts:665-669 注释）。
  • Headless profiler：散落在 QueryEngine.ts/query.ts 中的 headlessProfilerCheckpoint() 调用（before_getSystemPrompt、after_getSystemPrompt、system_message_yielded、query_started 等）——一种轻量级内部延迟追踪仪表，服务于 headless/SDK 会话，独立于上述分析事件。
  • 仅诊断用日志：logForDebugging() / logForDiagnosticsNoPII()（src/utils/debug.ts、src/utils/diagLogs.ts）——独立于 transcript 与分析管道之外，据推测写入本地调试/诊断日志文件（未深读）。

安全与权限（审批门、密钥管理）

  • 三层权限体系，代码与官方 auto-mode 博客一致确认：
    1. 内置安全工具白名单 + 用户”总是允许”规则——只读工具（Read/Grep/Glob/导航/todo）从不弹审批。
    2. 项目内文件写入——项目目录内的编辑无需逐次审批（可经 git 审阅）。
    3. 其他一切都需询问——shell 命令、网络抓取、项目目录外的文件系统操作、子 agent 生成、MCP 工具调用。
  • 权限模式（PermissionMode 类型，src/utils/permissions/PermissionMode.ts）：至少包括 default、plan（全文多处引用，如 query.ts:576 模型选择逻辑按 permissionMode === 'plan' 分支），以及一个绕过模式（BypassPermissionsModeDialog.tsx、bypassPermissionsKillswitch.ts——即据博客所述的 --dangerously-skip-permissions）。prePlanMode 字段保存进入 plan 模式前的模式，供 plan 模式干净退出（Tool.ts:136）。
  • “Auto mode”（2026 年 3 月发布）——叠加在上述之上的第四种模式：一个运行在 Sonnet 4.6 上的两阶段 transcript 分类器，对 Tier-3 动作把关。阶段一是快速单 token 是/否过滤（偏向拦截）；只有阶段一标记后才运行阶段二的完整思维链重新评估——“推理 token 只花在需要的地方”。分类器设计上对推理内容盲：它只看得到用户消息 + agent 自己的工具调用，Claude 的 assistant 文本和工具输出被剥离，专门为了防止被注入到工具结果里的内容进行社会工程攻击。代码确认：src/utils/permissions/yoloClassifier.ts 实现了 classifyYoloActionXml()、buildTranscriptForClassifier()、getDefaultExternalAutoModeRules()、buildDefaultExternalSystemPrompt()——与博客描述高度吻合（分类器 prompt = 固定模板 + 3 个可定制槽位：可信环境、超过 20 类默认拦截规则、允许例外）。
    • 一个独立的输入层防御：服务端 prompt-injection 探测器扫描工具输出（文件读取、网页抓取、shell stdout）在其进入上下文之前，用警告标注可疑内容而非直接拦截（博客）。
    • 量化结果（博客自报，未经我独立验证）：单独的沙箱化让权限弹窗减少 84%；用户历史上手动批准约 93% 的弹窗；auto-mode”在执行前捕获约 83% 的过度行为”（containment 博客）；Gray Swan Agent Red Teaming 对 Opus 4.7 的攻击成功率 ≈0.1%（单次尝试）/ 5-6%（100 次自适应尝试）。
    • Auto mode 在进入时剥离某些”总是允许”规则——笼统的 shell 访问、通配的解释器（python/node/ruby）、包管理器运行命令，会从继承的白名单中被显式移除，因为若保留，分类器就永远看不到风险最高的命令（博客，“Tier 1”）。
  • 沙箱化（2025 年 10 月发布；适配代码 src/utils/sandbox/sandbox-adapter.ts）是一种独立的、与分类器互补的机制——OS 级强制执行，非模型判断：
    • 建立在外部包 @anthropic-ai/sandbox-runtime 之上（据博客另行开源为 anthropic-experimental/sandbox-runtime）；Claude Code 的适配层（本文件）把自己的 settings.json schema（权限规则、sandbox.filesystem.*、sandbox.network.*）翻译成该运行时的 SandboxRuntimeConfig。
    • 通过 Linux bubblewrap 与 macOS Seatbelt 强制执行（sandbox-adapter.ts 头部注释 + 博客）；网络隔离经一个 Unix domain socket 连接的、沙箱外的代理，强制执行域名允许/拒绝列表，可对新请求的域名弹窗询问。
    • 无论用户设置如何都硬编码的防御性拒绝写入规则（convertToSandboxRuntimeConfig()）：始终拒绝写入所有 settings.json/settings.local.json 路径及托管设置 drop-in 目录（防止通过配置编辑逃逸沙箱，lines 230-245）；始终拒绝写入原始 cwd 和当前 cwd 下的 .claude/skills（注释指出底层 sandbox-runtime 保护 .claude/commands/.claude/agents 但不保护 .claude/skills，所以 Claude Code 自己额外加了这层，lines 247-255）；一个针对命名的 CVE 风格裸 git 仓库攻击的特定防御（在 cwd 植入 HEAD/objects/refs/hooks/config 诱使 is_git_directory() 把 cwd 当作裸仓库处理，从而在 Claude 未沙箱化的 git 运行时逃逸沙箱——代码引用 anthropics/claude-code#29316，lines 257-280），并有主动的事后清理（scrubBareGitRepoFiles()）。
    • 可通过一个未文档化的 enabledPlatforms 设置将功能限定到特定平台（line 505，注释为”为解锁 NVIDIA 企业部署”而加）。
    • isAutoAllowBashIfSandboxedEnabled()——沙箱化时，Bash 命令可以完全绕过常规审批弹窗（默认 true），因为 OS 沙箱本身被认为是充分的隔离。
  • 责任范围事件历史（博客自报，日期为发布日期）：
    • 3 起负责任披露漏洞（2025 年中 - 2026 年 1 月）利用了在”是否信任此文件夹？“提示之前就运行的代码——例如恶意 .claude/settings.json hook 在克隆仓库时自动执行。修复方式：把所有项目本地配置解析/执行推迟到信任提示之后。
    • 2026 年 2 月内部红队测试：一名被钓鱼的员工运行了一个 Claude Code 提示，读取 ~/.aws/credentials、编码、POST 到外部——24/25 次成功。这被定性为仅靠模型层防御无法修复（用户本身就是注入向量，分类器没有什么”异常”可标记）——只有环境控制（出站流量白名单、对 ~/.aws 的文件系统拒绝访问）才能阻止。
  • 密钥/凭证管理：沙箱配置默认通过路径限定把 ~/.aws、SSH key 等排除在可达范围外；Claude Code on the web（云沙箱变体）走得更远——git 凭证/签名密钥”从不进入 Claude Code 的沙箱内部”；一个自定义代理代表 Claude Code 使用范围受限的凭证认证 git 操作，在附加真实 GitHub token 前先校验目标分支/仓库。
  • Bash 专项加固：src/tools/BashTool/bashSecurity.ts 实现了数十个命名验证器，针对 shell 注入/混淆手法（基于 zsh zmodload 的攻击、heredoc 走私、基于 jq 的文件读取、IFS 注入、畸形 token 注入、绕过负向先行断言正则的混淆 flag、/proc/environ 访问、IFS/回车符诡计）——未逐行读取，但仅函数名清单就显示出一个深度的、经过对抗性测试的 Bash 参数解析威胁模型，区别于沙箱/分类器层。

沙箱与执行隔离

（与”安全与权限”节内容大量重叠，按要求的十二维结构在此单列一节，不重复展开细节。）

  • 主要机制：@anthropic-ai/sandbox-runtime（外部包，另行开源），由 src/utils/sandbox/sandbox-adapter.ts 封装。OS 级，非容器级——此路径无 Docker/VM 抽象；依赖 Linux bubblewrap + macOS Seatbelt 作为强制执行原语。支持平台：macOS、Linux、WSL2+（WSL1 明确不支持，isSupportedPlatform()/getSandboxUnavailableReason()，sandbox-adapter.ts:487-592）。
    • 需要外部依赖 ripgrep（经 checkDependencies() 检查，有记忆化）及（Linux 上）bubblewrap + socat——缺依赖时沙箱显式降级为不可用并给出用户可见的原因字符串，而非静默 no-op（明确称为对 issue #34044 的修复：“此前……依赖缺失时静默返回 false，用户毫无反馈”）。
    • 文件系统：默认允许写 = ['.', <claude-临时目录>]；显式拒绝写入列表始终包含所有 settings.json 变体、托管设置目录、.claude/skills，以及（防御性地）cwd 下任何裸 git 仓库标记文件。Git worktree 主仓库路径在初始化时自动检测一次并加入允许写列表（worktree 需要对主仓库 .git 的写权限，用于索引锁等，lines 282-288）。
    • 网络：允许/拒绝域名列表来自 WebFetch 权限规则（domain: 规则内容）加上 sandbox.network.allowedDomains/deniedDomains 设置；可选的 allowManagedDomainsOnly 策略设置无视用户配置、只允许策略定义的域名（企业/托管设备锁定杠杆）。
    • 配置可热重载：订阅 settingsChangeDetector，任何设置变更时调用 BaseSandboxManager.updateConfig()（sandbox-adapter.ts:775-781）——无需重启即可生效新的允许/拒绝规则。
  • Git 原生隔离（worktree）：独立于 OS 沙箱——AgentTool 的 isolation: 'worktree' 选项为每次子 agent 调用创建一个临时 git worktree（src/utils/worktree.js），让该子 agent 拥有隔离的工作副本，完全不涉及 OS 级沙箱。
  • 远程隔离：isolation: 'remote'（据代码为 ant/内部专用，ONE_SHOT_BUILTIN_AGENT_TYPES/CCR 引用）将子 agent 整体启动在远程沙箱环境中，总是后台化。
  • 云产品隔离（“Claude Code on the web”）：每个 web 会话运行在独立的云沙箱中；凭证从不进入沙箱（代理中介 git 认证）。
  • 与 claude.ai 代码执行containment 的对比（博客，供背景对比，非 Claude Code CLI 自身的一部分）：claude.ai 使用临时性 gVisor 容器，每会话独立文件系统——一种更强的、完全服务端的隔离模型，不适用于 CLI 的本机执行模型。值得在 dossier 里指出：“同一家公司针对 agent 文件系统所在位置的不同，用了不同的方案解决同一个问题。“

与模型的协同设计

  • Fast Mode：系统提示自身明确声明不是模型切换——“Fast mode for Claude Code uses the same {FRONTIER_MODEL_NAME} model with faster output. It does NOT switch to a different model.”（prompts.ts 约 line 702）——暗示这是一个与 Anthropic 推理服务基础设施协同设计的速度/质量杠杆，向 harness 暴露为一个简单布尔值（appState.fastMode），贯穿 callModel() 选项传递（query.ts:671-673）。
    • getFastModeState() 计算一个 fast_mode_state 字段，包含在每条 result SDK 消息中（QueryEngine.ts:632-635 等处）——harness 把 fast-mode 状态作为一等信号回报给调用方。
  • 模型别名/降级：fallbackModel 参数贯穿整个 loop；FallbackTriggeredError（在 query.ts:893 捕获）在主模型过载时触发同轮自动切换到备用模型——通过合成的 system “warning” 消息呈现给用户（“Switched to {fallback} due to high demand for {original}“，query.ts:945-948）并记录日志（tengu_model_fallback_triggered）。这是一个围绕真实容量限制协同设计的产品级可靠性特性，不是纯 harness 层决策。
  • Thinking block / 扩展思考：ThinkingConfig（adaptive vs disabled，utils/thinking.ts）是会话级的；query.ts 详尽的头部注释（lines 151-163）记录了 harness 必须遵守的硬性模型 API 契约规则：thinking/redacted_thinking block 要求 max_thinking_length > 0；thinking block 不能是消息序列中的最后一条；thinking block 必须在整个 assistant 轨迹（本轮 + 其 tool_result + 后续 assistant 消息）期间完整保留——违反这些规则会导致真实 API 报错（“用作者自己的话说，‘花了一整天调试掉头发’”）。这是 harness 消息装配逻辑与 Claude API 特定的交错思考语义之间的紧密耦合。
    • 降级时的 thinking-signature 剥离：由于 thinking block 是逐模型加密签名的，把一个模型签名的 thinking block 重放给降级后的模型会导致 400 错误——harness 在降级重试前显式剥离签名块（query.ts:924-929，此 build 中受 USER_TYPE === 'ant' 门控，但底层约束是模型 API 层面的，非内部专属）。
  • task_budget（beta API 特性）：taskBudget: {total, remaining} 传给 callModel()（query.ts:196-198, 699-706）——一个 Anthropic API beta 特性（output_config.task_budget，据注释为 “task-budgets-2026-03-13”），让服务端为整个 agentic turn（跨工具调用往返）追踪并强制执行 token 预算；harness 在压缩事件发生后手动计算 remaining（因为服务端在压缩后已看不到压缩前的上下文）——一个真实的协同设计案例：模型服务端特性（服务端追踪的任务预算）需要客户端簿记才能在 harness 自身的压缩行为下保持正确。
  • Effort 等级：appState.effortValue 传给 callModel()（query.ts:694）与 EffortIndicator.ts 组件——一个同时暴露给模型和 UI 的推理强度旋钮，可按 skill 单独调整（resolveSkillModelOverride，SkillTool.ts:815-819）。
  • 贯穿全文的prompt-cache 感知工程：renderedSystemPrompt 对分叉子 agent 冻结，专门避免 GrowthBook 开关中途翻转导致 cache 失效（Tool.ts:293-299）；skipCacheWrite 参数（query.ts:192, 261）；直接编辑 prompt cache 并等待 API 实际返回的 cache_deleted_input_tokens（而非客户端估算）的 cached-microcompact 变体（query.ts:866-892）——harness 明确围绕 Anthropic 特定的 prompt-caching 计费/延迟模型工程化，而非通用 LLM API。

轨迹利用（session/trajectory 是否反哺训练/评测）

  • 本代码库中未发现直接证据证明会话 transcript 被反馈进模型训练——这属于 Anthropic 内部数据管道，超出 CLI 自身源码范围；CLI 本身只展示了这个故事客户端发射的那一半。
  • 客户端可见、可信能反哺此类管道的部分：
    • 完整的分析/遥测管道（见”可观测性”节）——tengu_* 事件几乎为每个有意义的动作记录（压缩、工具调用、skill 调用、错误、降级），_PROTO_* 标记的字段专门路由到有访问控制的特权 BigQuery 列（注释：“目标 BQ 列有特权访问控制，因此未脱敏的值是可接受的——不同于通用访问后端”，analytics/index.ts:26-33）——即存在一个明确的、比通用 Datadog 指标更高信任级别的内部数据目的地，与（但不能证明）训练/评测数据采集一致。
    • /share 与 /issue 斜杠命令（系统提示中引用，prompts.ts line 245）上传完整会话 transcript（“ccshare link”）用于产品 bug 上报——一个显式的、经用户同意的 transcript 分享路径，但定位为支持/调试而非训练。
    • feedback/ 组件树（FeedbackSurvey.tsx、useMemorySurvey.tsx、usePostCompactSurvey.tsx、submitTranscriptShare.ts）——压缩后及记忆相关的用户调查存在，专门用于征集与特定 transcript 时刻绑定的结构化反馈，这是一个合理的评测/训练信号采集点（未深读，仅文件名）。
    • 内部事件日志（博客）：Anthropic 明确声明他们”维护一份专注于 agentic 不当行为的内部事件日志”，用于推导 auto-mode 分类器的拦截规则并构建带标签的评测集（“Real overeager actions (n=52)。从员工拒绝该动作或事后被标记的会话中整理而来。”）——这是最清晰的有文档记载（尽管是高层级的）会话轨迹被采集进评测数据集的例子，特指用于内部（ant）使用，且特指用于安全分类器调优而非通用能力训练。此说法来自博客，未在代码中验证。
    • 全代码库存在 ant-only 分支（process.env.USER_TYPE === 'ant'），为分析事件门控额外字段（如 SkillTool.ts:171-184，未脱敏的 skill_name、skill_source）——确认 Anthropic 自己对 Claude Code 的内部（“dogfooding”）使用比外部用户被更丰富地打点，这与”内部轨迹是比通用客户遥测更丰富的数据源”一致，但同样只是从字段门控推断，而非直接声明这些数据用于训练模型。
  • 本维度结论：会话轨迹反哺模型训练是合理推测但源码未证实；具体证实的是 (a) 一个丰富、结构化、带特权内部数据层级的分析管道，以及 (b) Anthropic 自己的博客声明——一份显然源自真实会话轨迹（至少对 ant/内部用户而言）的内部事件日志被用于构建评测集并调优 auto-mode 安全分类器。不应在 dossier 中过度声称”训练模型”——准确说法是”据 Anthropic 自己的博客，反哺内部评测/安全分类器调优；客户端源码中未发现 RLHF/微调反馈闭环的证据”。

与同类 harness 的关键差异（1-3 条，可以先留一句概述，后续 synthesis 阶段会做跨 harness 对比）

  • 概述（留待 synthesis 阶段展开）：Claude Code 在三点上区别于目前已调研的其他 harness——(1) 系统提示里硬编码的强制对抗式验证契约（非平凡改动必须经独立 verification-agent 子 agent 审核，实现者不能自评通过），把”self-correction”直接做成了不可关闭的治理规则，而不是可选的最佳实践建议；(2) OS 级沙箱与 LLM 判断式分类器（auto mode）并行、互补而非二选一——沙箱防”环境能不能做”，分类器防”模型该不该做”，两层威胁模型分离清晰；(3) 四层级联的上下文压缩（HISTORY_SNIP/microcompact/context-collapse/autocompact-reactive-compact）比大多数 harness 常见的”单一摘要压缩”要精细得多，且带有实际生产故障驱动的熔断阈值（注释直接引用了具体故障数字）。跨 harness 的系统性对比留给 synthesis 阶段。

原始源码定位

  • repo: 无公开源码。npm 包 @anthropic-ai/claude-code，homepage 字段指向 github.com/anthropics/claude-code（该仓库本身不发布源码，只发布打包后的 cli.js）。本 dossier 引用的所有源码路径来自本地非官方提取目录 /Users/zhao/projects/chatgptprojects-claude-code（源自 cli.js.map sourcemap 的 sourcesContent 字段泄露，2026-03-31 公开，无 git 历史/commit SHA）。
  • commit/version analyzed: npm v2.1.88（package.json 直接确认，独立经 src/utils/sessionStorage.ts:99 的 MACRO.VERSION 引用交叉核实）。
  • 关键文件列表（相对路径，均相对于 /Users/zhao/projects/chatgptprojects-claude-code/）：
    • src/query.ts（1729 行，全文读完）—— 主 agent 循环
    • src/QueryEngine.ts（1296 行，全文读完）—— turn/会话生命周期
    • src/Tool.ts（793 行，全文读完）—— Tool 类型 + 默认值
    • src/Task.ts（126 行，全文读完）—— 后台任务簿记
    • src/query/deps.ts —— query() 依赖注入
    • src/tools/AgentTool/AgentTool.tsx（部分读，约 250 行）—— Task/子 agent 工具
    • src/tools/SkillTool/SkillTool.ts（1109 行，全文读完）—— Skill 工具
    • src/skills/loadSkillsDir.ts（部分读，~150 行）—— skill 目录扫描
    • src/utils/permissions/permissions.ts（部分读，~200 行）—— 权限规则引擎
    • src/utils/sandbox/sandbox-adapter.ts（986 行，全文读完）—— 沙箱适配层
    • src/tools/BashTool/bashSecurity.ts（结构 grep）—— Bash 安全校验
    • src/utils/permissions/yoloClassifier.ts（结构 grep）—— auto-mode transcript 分类器
    • src/utils/queryContext.ts（部分读，~150 行）—— 系统提示 cache-key 装配
    • src/constants/prompts.ts（914 行，按 section 边界抓读）—— 系统提示构建
    • src/services/compact/autoCompact.ts（部分读，~120 行）—— 自动压缩阈值
    • src/services/extractMemories/extractMemories.ts（616 行，全文读完）—— 自动记忆抽取
    • src/utils/sessionStorage.ts（部分读，~100 行）—— 会话 JSONL 持久化
    • src/services/analytics/index.ts（部分读，~100 行）—— 一方分析事件
    • src/services/AgentSummary/agentSummary.ts（部分读，~80 行）—— 子 agent 进度摘要
    • src/utils/hooks.ts（结构 grep）—— hook 事件类型

一手源存档（sources/）

存档目录：/Users/zhao/projects/self-wiki/ai-research/sources/harness/claude-code/

  • NOTES.md（625 行）—— 本次调研的完整过程笔记（provenance 声明、逐文件读取清单、十二维逐维发现、stage-2 待补 gap 列表）
  • src-excerpts/（12 个源文件节选，约 612KB）：
    • query.ts —— agent 主循环全文
    • QueryEngine.ts —— turn/会话生命周期
    • Tool.ts —— Tool 类型规范
    • Task.ts —— 后台任务类型
    • AgentTool.tsx —— 子 agent/Task 工具
    • SkillTool.ts —— Skill 调用工具
    • sandbox-adapter.ts —— 沙箱适配层
    • prompts.ts —— 系统提示构建
    • autoCompact.ts —— 自动压缩
    • extractMemories.ts —— 自动记忆抽取
    • permissions.ts —— 权限规则引擎
    • query-deps.ts —— query() 依赖注入
  • official-blog/（6 篇官方博客存档，约 176KB）：
    • 2025-04-18-claude-code-best-practices.md
    • 2025-09-29-effective-context-engineering-for-ai-agents.md
    • 2025-10-16-equipping-agents-for-the-real-world-with-agent-skills.md
    • 2025-10-20-claude-code-sandboxing.md
    • 2026-03-25-claude-code-auto-mode.md
    • 2026-05-25-how-we-contain-claude.md

关系图谱

反向链接