Claude Code 源码拆解
Book 第三十二章：现在的文档体系还缺什么
第六部分：迁移与附录

第三十二章：现在的文档体系还缺什么

把当前文档体系真正还缺的章节、源码证据和下一轮最值钱的选题列清楚。

1. 先说结论

前面这批文档，已经把 Claude Code 最核心的 agent runtime 主骨架拆出来了：

  • 启动与模式分流
  • turn loop / query 状态机
  • 工具运行时与权限
  • 本地文件工具、搜索工具、Web 工具
  • agent / skill / task / MCP / LSP / REPL
  • transcript / resume / compact / overflow recovery
  • remote / managed settings / policy / settings sync
  • 第一版 C# runtime blueprint

如果目标只是“看懂 Claude Code 大体怎么工作”，现在这套文档已经够了。

但如果目标是：

尽可能把这份源码里能迁到 C#、能复用到别的 agent runtime、能指导产品化的价值继续榨出来，

那当时还差几块很关键的横切系统。

它们的共同特点是：

  • 不是某一个具体工具
  • 也不是单个 feature
  • 而是会影响整个 runtime 边界和产品能力的底层组织方式

2. 这一轮补齐了什么

2026-04-07 这轮已经把当时最值得补的七块横切系统补齐了，对应专题如下：

下面这七块，保留的是“当时为什么必须补”和“为什么它们对 C# 抽象值钱”的判断。

2.1 AppState 与 UI/runtime 边界

建议单开：

  • src/state/AppStateStore.ts
  • src/state/AppState.tsx
  • src/state/onChangeAppState.ts
  • src/state/selectors.ts
  • src/screens/REPL.tsx
  • src/components/*

为什么还差这章：

  • 现在很多文档已经反复提到 AppState
  • 但还没有一篇把它当“状态边界设计”来拆
  • AppStateStore.ts 里这个对象已经不是普通 UI state 了

从源码上看，AppState 至少混了这些东西：

  • 会话 runtime 状态
  • task / agent / MCP / plugin 状态
  • remote bridge / viewer 状态
  • footer、选中态、panel 显示态这类 UI projection

这块最值钱的地方，不是“它有哪些字段”，而是：

  • Claude Code 到底把哪些状态放在核心层
  • 哪些状态其实只是宿主投影
  • 现有实现里哪些地方是历史演化留下来的混合层

如果后面要做 C# 版，这一章会直接决定你是不是会抄出一个巨大的 God Object。

2.2 认证 / Token / 登录运行时

建议单开：

  • src/utils/auth.ts
  • src/utils/authPortable.ts
  • src/utils/authFileDescriptor.ts
  • src/services/oauth/*
  • src/commands/login/*
  • src/commands/logout/*

为什么还差这章：

  • 现在文档里已经提到 auth 会影响 managed settings、remote、provider、组织限制
  • 但还没有一篇把整条 auth runtime 串起来

这块源码很值钱，尤其是这几个判断：

  • isManagedOAuthContext() 明确阻止 managed session 回退到用户本地 CLI 的 API key
  • isAnthropicAuthEnabled() 不是简单开关，而是把 bare mode、3P provider、external key、managed context 一起判断
  • getAuthTokenSource() 和 getAnthropicApiKeyWithSource() 说明 auth source hierarchy 本身就是一套运行时协议

这章最值得提炼的问题：

  • Claude Code 的 auth source 优先级到底怎么排
  • first-party OAuth 和 3P provider 的边界怎么切
  • 为什么远端、桌面、CLI 要故意隔离各自的认证来源
  • org / trust / policy 是怎么压进 auth 判定链路的

2.3 Telemetry / analytics / attribution

建议单开：

  • src/services/analytics/*
  • src/utils/telemetry/*
  • src/utils/commitAttribution.ts

为什么还差这章：

  • 目前文档里经常提到 telemetry
  • 但基本都只是“某个模块会打点”
  • 还没有一篇说明 Claude Code 怎么把观测能力做成正式基础设施

从源码能确认几件很值钱的事：

  • services/analytics/index.ts 故意保持“零依赖入口”，避免 import cycle
  • sink 没挂上前，事件先排队，不阻塞启动
  • metadata 类型故意限制 string，逼调用方显式声明“这不是代码、不是路径”
  • _PROTO_* 字段会统一剥离，防止 PII 被误扔到通用后端
  • sink.ts 把 Datadog、1P logging、sampling、killswitch、gate 都统一收在一个路由层

这不是“埋点实现细节”，而是产品级 runtime 的可观测性设计。

如果以后 C# 版想做成长期演化的系统，这章非常值钱。

2.4 Memory 全景：memdir、session memory、team memory、autoDream

建议单开：

  • src/memdir/*
  • src/services/SessionMemory/*
  • src/services/teamMemorySync/*
  • src/services/autoDream/*
  • src/commands/memory/*

为什么还差这章：

  • 现在书里已经写了 attachment、context、settings sync、session persistence
  • 但 memory 还分散在不同专题里，没有合成一张完整地图

这块源码其实至少有四层：

  1. memdir
    • 文件型长期记忆目录
    • 有类型约束、索引文件、字节/行数限制
  2. session memory
    • post-sampling hook 触发
    • 阈值满足后用 forked subagent 维护会话摘要文件
  3. team memory sync
    • repo 级共享记忆
    • OAuth、ETag、checksum、delta upload、413 学习 server limit
  4. autoDream
    • 背景 consolidation
    • 按时间门槛、session 数量、锁文件做调度

这几层放在一起看，才能真正看明白 Claude Code 的 memory strategy：

  • 哪些记忆是当前 session 的
  • 哪些记忆是 project scoped 的
  • 哪些记忆是 team scoped 的
  • 哪些记忆是自动沉淀出来的

这块对 C# 第一版不一定最先实现，但对产品路线非常值钱。

2.5 插件系统 / Marketplace / 扩展治理

建议单开：

  • src/utils/plugins/*
  • src/services/plugins/*
  • src/commands/plugin/*

为什么还差这章：

  • 我们已经拆了 MCP 和 skill
  • 但 plugin 这条线还没有像 MCP 一样被完整收束

从源码看，这套系统明显不只是“装个插件”：

  • pluginLoader.ts 里区分了 declaration、cache、seed、versioned install path、legacy path
  • marketplaceManager.ts 明确把 marketplace 分成 intent layer 和 materialized state layer
  • loadPluginHooks.ts 说明插件不只加命令，还会热插 hook，而且作者专门修过“clear 后 stop hook 静默失效”的边界问题
  • PluginInstallationManager.ts 则把后台 reconcile、AppState 安装进度、auto-refresh、needsRefresh 都接到了 UI/runtime 之间
  • pluginPolicy.ts 说明插件还受 managed settings 的组织级策略约束

这章的价值，不只是给以后做插件系统，而是让你看清：

  • 扩展生态怎么进 runtime
  • 扩展什么时候能热更新
  • 组织治理怎么卡在扩展入口
  • marketplace 和 runtime state 为什么要分层

2.6 Hooks 运行时总览

建议单开：

  • src/utils/hooks/*
  • src/query/stopHooks.ts
  • src/utils/plugins/loadPluginHooks.ts
  • src/state/sessionHooks* 相关入口

为什么还差这章：

  • 现在很多文档都提到 hook
  • 但 hook 仍然是“散着出现”
  • 还没有一篇把 Claude Code 的 hook runtime 当成一个正式子系统来写

而从源码上看，它其实已经是一套比较完整的 lifecycle system：

  • PreToolUse / PostToolUse / PermissionRequest
  • SessionStart / SessionEnd
  • Stop / StopFailure
  • PreCompact / PostCompact
  • Elicitation / ElicitationResult
  • 插件 hook、session hook、内部 post-sampling hook 还会叠在一起

尤其是 SessionMemory 和 autoDream 都说明：

Claude Code 不是只把 hook 当外部扩展点，也会把内部后台能力挂在 hook runtime 上。

这章单开以后，前面很多文档里的 hook 线索才会真正闭环。

2.7 模型 / Provider / Capability 路由

建议单开：

  • src/utils/model/*
  • src/utils/auth.ts
  • src/commands/model/*
  • 若干按 provider gate 的工具实现

为什么还差这章：

  • 现在文档里已经提到过 Web 工具会看 provider / model 能力
  • managed settings、auth、remote 也都跟 provider 有关系
  • 但我们还没有系统写“Claude Code 怎么做模型与 provider 路由”

这块现在看起来不像最核心，但其实很值得提炼：

  • first-party / Bedrock / Vertex / Foundry 的边界怎么做
  • model capability 怎么影响工具可用性
  • context window 升档和 provider routing 有没有耦合
  • model alias、allowlist、deprecation 怎么进入运行时

如果以后 C# 版要支持多 provider，这章会很实用。

3. 现在最该补的，不是更多工具文档

这次复查之后，我更确定一件事：

后面最值钱的工作，不是继续横向扫更多工具，而是把这些横切系统补成“运行时控制面”文档。

原因很简单：

  • 工具层的大骨架已经够清楚了
  • 再继续加一个个工具专题，收益会开始变小
  • 但上面这几块横切层，直接决定 Claude Code 为什么像一个产品级 runtime，而不是一个会调工具的 CLI

换句话说，后面的重点应该从：

  • “这个工具怎么实现”

慢慢切到：

  • “这个系统怎么治理状态、身份、记忆、扩展、观测和宿主边界”

4. 如果按“榨价值”的角度排优先级，我会这么排

4.1 第一梯队：最该马上补

  1. AppState 与 UI/runtime 边界
  2. 认证 / Token / 登录运行时
  3. Telemetry / analytics / attribution

这一梯队的共同点是：

  • 都会直接影响 C# 核心边界设计
  • 不补的话，C# 版很容易从第一天就分层失真

4.2 第二梯队：Claude Code 的差异化深水区

  1. Memory 全景
  2. 插件系统 / Marketplace / 扩展治理
  3. Hooks 运行时总览

这一梯队的共同点是：

  • 更偏 Claude Code 的产品味和工程味
  • 不一定要在 C# 第一版马上实现
  • 但它们决定这套 runtime 后面能不能长成完整产品

4.3 第三梯队：决定多 provider 和产品外延

  1. 模型 / Provider / Capability 路由

这块排在后面，不是因为不重要，而是因为：

  • 它跟 auth、settings、tool gating 都耦合
  • 前面几章补完之后，再写它会更稳

5. 哪些地方已经能确认“真的有料”，不是凭感觉

这里把这次复查看到的几个强信号记一下，避免后面选题时只靠印象。

5.1 AppState 确实已经大到值得单拆

src/state/AppStateStore.ts 里同时装了：

  • remote session status
  • repl bridge status
  • tasks / foregroundedTaskId / viewingAgentTaskId
  • MCP clients / tools / commands / resources
  • plugin enabled/disabled/errors/install state
  • notifications / elicitation / sessionHooks
  • footer、panel、selection 这类 UI 态

这已经不是一个普通 React store 了。

5.2 auth 不是简单的“登录功能”

src/utils/auth.ts 里能明确看到：

  • managed OAuth context
  • bare mode
  • 3P provider
  • env var / file descriptor / keychain / apiKeyHelper / claude.ai token
  • org / profile / scope

这些都不是 UI 登录流程，而是运行时的身份路由层。

5.3 analytics 不是“补点日志”

src/services/analytics/index.ts 和 sink.ts 说明它至少在认真处理：

  • 启动早期事件不丢
  • 依赖环问题
  • PII 隔离
  • sink killswitch
  • gate / sampling
  • Datadog 和 1P backend 分流

这套东西已经有平台基础设施的味道了。

5.4 memory 确实是一整套系统，不是一个目录

从这次复查看到的文件就能确认：

  • src/memdir/*
  • src/services/SessionMemory/sessionMemory.ts
  • src/services/teamMemorySync/index.ts
  • src/services/autoDream/autoDream.ts

而且几层之间的策略明显不同，不适合再分散地写在别的章节里。

5.5 plugin 也不是“插件菜单”

这次看到的关键证据包括：

  • marketplace 的声明层 / 落地层分离
  • seed cache / versioned cache
  • managed settings 的 plugin policy
  • hook hot reload 的原子 clear-register
  • 后台 reconcile 与 needsRefresh

这已经是完整的扩展治理系统了。

6. 对 C# 版最重要的提醒

后面如果继续读源码，最容易犯的错是：

  • 看到一个 feature，就想把它翻译成一个 FooService
  • 看到一个目录，就想把它翻译成一个 namespace

但 Claude Code 真正值钱的地方，很多都不是“功能目录”，而是：

  • 状态边界
  • 身份边界
  • 观测边界
  • 记忆边界
  • 扩展边界

所以我更建议后面的文档继续围着这几个问题写：

  1. 这块东西归谁管
  2. 它改了哪些运行时状态
  3. 它依赖哪些外部系统
  4. 它应该留在核心，还是留在宿主
  5. 如果迁到 C#，最小抽象应该长什么样

7. 下一步最合理的文档顺序

如果现在继续写，我建议按这个顺序往下补：

  1. AppState 与 UI/runtime 边界
  2. 认证 / Token / 登录运行时
  3. Telemetry / analytics / attribution
  4. Memory 全景
  5. 插件系统 / Marketplace / 扩展治理
  6. Hooks 运行时总览
  7. 模型 / Provider / Capability 路由

这样写的好处是：

  • 先把核心边界补齐
  • 再把 Claude Code 的产品级差异化补齐
  • 最后再把多 provider 和外延能力补齐

这条线走完，Claude Code 这份源码里最能迁移、最能复用、最能指导 C# 版设计的价值，基本就真被榨得差不多了。