软件工程 / 架构设计方法论知识图谱 / 分组目录 / 案例层 / Claude Code 架构逆向
X · P2 · active

Claude Code 架构逆向

Reverse-Engineering the Claude Code Agent Architecture
P2高级verified案例X · 跨域/其他质量属性团队与康威GC-CASE · 案例层

§1摘要与结论

TL;DR · 一句话结论

以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。

别名：Claude Code 逆向、多源交叉验证、Agent 架构逆向　|　英文：Reverse-Engineering the Claude Code Agent Architecture　|　类型：案例 / reverse-engineering

§2局部关系图

Claude Code 架构逆向 的 1-2 跳邻域关系图前置依赖（prerequisite）：关注点分离是信息隐藏的前提前置依赖（prerequisite）：本质复杂度不可消除，故架构只能在约束下权衡前置依赖（prerequisite）：本质复杂度是演化中复杂度递增的成因前置依赖（prerequisite）：关注点分离促成知识的单一归属组合（combination）：信息隐藏与关注点分离常组合使用依赖关联（dependency）：需求易变性源于软件本质困难中的 changeability依据推导（derives_from）：覆盖与精度只能在本质复杂度不可消除的空间中选点依据推导（derives_from）：代价不对称的取舍依据权衡不可消除依据推导（derives_from）：粒度决定偶然复杂度与理解成本依据推导（derives_from）：复杂度阶梯以降低认知复杂度为目标依据推导（derives_from）：理解成本即认知复杂度的核心度量依赖关联（dependency）：复杂度阶梯的选择依赖理解成本原则前置依赖（prerequisite）：本质复杂度不可消除支撑权衡不可消除依据推导（derives_from）：文档化方法以架构描述为对象组织视图与对应关系依据推导（derives_from）：文档化依视图与视角约定组织架构信息组合（combination）：决策记录与文档化方法共同承载架构决策与理由促成（enables）：架构文档是架构评估流程的输入前置依赖（prerequisite）：视图与视角概念是理解架构描述构成与对应关系的前提组合（combination）：架构描述按干系人关注点组织局部表达案例印证（case_instance）：印证：按关注点将系统分解为可独立处理的 18 个模块案例印证（case_instance）：印证：以视图与依赖图文档化架构，支撑无源码理解案例印证（case_instance）：印证：去中心化与本地优先等主张皆为显式架构取舍案例印证（case_instance）：印证：以分层文档组织视图，再补跨视图信息案例印证（case_instance）：印证：按不同关注点组织层级与模块视图案例印证（case_instance）：印证：把不可见的架构转写为可复核的架构描述案例印证（case_instance）：印证：以蓝本为参照的多视图文档与深链互引案例印证（case_instance）：张力：受蓝本粒度约束，增量定位精度受限案例印证（case_instance）：印证：查询引擎、工具、权限、记忆的关注点分离案例印证（case_instance）：印证：多源交叉验证与分章文档化案例印证（case_instance）：印证：编译期特性裁剪消除偶然复杂度案例印证（case_instance）：印证：五段式节点页与图谱化文档前置依赖（prerequisite）：模块化目标是信息隐藏判据的前提前置依赖（prerequisite）：关注点分离是理解与选择架构风格的认知基础组合（combination）：风格选择是架构权衡的典型对象前置依赖（prerequisite）：关注点分离是视图与视角划分的基础组合（combination）：模块化是关注点分离在结构上的体现依据推导（derives_from）：决策记录依架构即权衡，留存取舍与理由依据推导（derives_from）：ATAM 以架构权衡为根本前提前置依赖（prerequisite）：识别敏感点与权衡点是记录架构决策的前提Claude Code …Claude Code 架构逆向（CAS-X-13）关注点分离关注点分离（ESS-G-01）本质复杂度与偶然复杂度本质复杂度与偶然复杂度（ESS-O-01）架构文档化方法架构文档化方法（MTH-G-05）架构即权衡架构即权衡（ESS-O-02）权衡的不可消除性权衡的不可消除性（ESS-O-03）信息隐藏信息隐藏（ESS-H-01）质量属性场景与ATAM质量属性场景与ATAM（MTH-G-02）Open Code Re…Open Code Review 图谱（CAS-X-15）模块化与分解模块化与分解（ESS-G-04）视图与视角视图与视角（ESS-G-06）架构描述与对应关系架构描述与对应关系（ESS-G-07）粒度与边界设定粒度与边界设定（MTH-O-06）去中心化聊天架构逆向去中心化聊天架构逆向（CAS-X-01）harness 源码架构…harness 源码架构解析（CAS-X-09）架构风格架构风格（ESS-G-05）DRY 单一知识来源DRY 单一知识来源（ESS-H-03）软件演化定律软件演化定律（ESS-L-01）架构决策记录架构决策记录（MTH-G-01）dsh 插件依赖增量定位dsh 插件依赖增量定位（CAS-X-10）覆盖与精度的不对称权衡覆盖与精度的不对称权衡（MTH-O-01）复杂度阶梯与演进时机复杂度阶梯与演进时机（MTH-O-08）需求的不确定性与变更需求的不确定性与变更（ESS-F-04）理解成本优先的简单原则理解成本优先的简单原则（MTH-O-09）
前置依赖实现依据推导案例印证对比冲突
以本节点为中心，静态内联 1–2 跳邻域：内环 3 个直接邻接、外环 20 个二跳节点，共 24 个节点；连线按边类型着色（六类配色见下）。构建期计算，无运行期脚本。

§3原理 · 为什么

对闭源商业 Agent，理解其架构不能依赖单一信源：打包产物、系统提示词、社区逆向与官方文档各带偏差，只有把多源对同一机制的证据交叉印证，才能把「看起来如此」收敛为「三方一致」。这本质是给逆向结论建立证据分级——哪些是编译产物可证的事实（工具数、提示词片段数、文件结构），哪些是逆向者的推断，哪些来自官方声明，必须显式区分。混淆证据等级是逆向分析最常见的错误：把推断当事实、把文档当实现，会让整份架构结论建立在不稳定的沙地上。多源交叉的价值，正是用相互独立的证据压低单一来源的系统性偏差，也让后续引用者清楚每条结论的可信度。这也解释了为什么同一份逆向报告在不同人手里可信度不同：差别不在文笔，而在于是否把每条陈述的证据等级、来源与不确定性交代清楚，让读者能自行决定信多少。对于没有官方源码的对象，这套分级方法几乎是唯一能让结论站得住脚的方式。把可信度分级，本质上也是对自己结论的保护，避免一次误判否定全篇。

§4机制 · 如何运作

材料分三类：社区还原的 TypeScript 源码树、从编译产物提取的数百个系统提示词片段、以及对十余兆字节打包产物的自探索逆向（内部代号、遥测事件、沙箱策略）。据此归纳核心机制：查询引擎是一个异步生成器，主循环、子Agent 与后台分叉共用同一条查询管道，仅在上下文组装上分流，这一设计让多形态执行共享一套流式与重试逻辑，减少重复实现；工具调用经统一编排层分发；提示词缓存只在最后一条消息上放单个标记以最大化命中；编译期特性标志把整段子系统在打包时树摇掉，使「源码里存在」与「运行时启用」分离，这正是逆向最容易踩空之处。把机制归纳到「共享管道、单一编排、缓存标记、编译裁剪」这类结构性判断上，比罗列函数名更耐久，因为前者在版本迭代后仍然成立，后者会随重构迅速过期。这些结构性判断彼此并不孤立，共同指向「以统一管道承载多形态执行」这一设计主线。结构性主线一旦确认，具体函数与文件名的变动就不再动摇整体理解。

§5工程 · 怎么落地

报告按「概览、核心架构、子Agent 调度、工具系统、上下文与记忆、安全权限、协议集成、Agent 间通信、跨子系统模式、可借鉴改造」十章组织，并对代码规模做三方口径核对，凡三方一致才记为事实、有分歧则并列展示，避免把单一口径当定论。可借鉴的设计模式被单独提炼成改造建议，使逆向成果从「理解」落到「复用」。这种「事实核对表加模式提炼加证据分级」的写法，是处理任何缺乏官方源码的系统的通用范式，也可直接用于竞品分析与自研架构对标。这种结构使报告既是理解文档，也是证据台账：任何一条结论都能沿清单回溯到出处，便于在后续版本中核对哪些仍然成立、哪些已经失效。报告同时记录了未能证实的部分，把它们明确列为开放问题，供后续有新材料时补充。证据台账让报告能在项目演进的每个版本后快速复核，而不必重做整轮逆向。

§6权衡卡

代价 · 风险

因此在使用这类报告做决策前，最好先确认关键结论的证据等级是否足以支撑所要付出的代价。

原文要点
  • 逆向源码的保真度不可证：社区还原可能有缺漏或臆测，与真实编译产物存在差距；打包时的死代码消除使「源码里存在」不等于「运行时启用」，把静态存在当运行时行为是典型误判。
  • 以商业产品为样本提炼的模式带有产品特定约束（沙箱、遥测、特定 runtime），迁移到自建体系需重新评估，不能直接照搬。
  • 多源交叉验证能提高可信度，却不能消除逆向的固有不确定性——它降低的是错误概率，而非给出真值。
  • 因此结论必须标注置信度与证据等级，把「已验证事实」「基于证据的推断」「尚不确定」清楚分开，避免读者把一份漂亮的架构报告当作官方实现文档。
  • 更稳妥的做法是把逆向结论与实测行为分开记录，凡能复现的才上升到事实，其余明确标注为待验证，并在取得官方材料后及时修订，而不是一次性定稿。
  • 因此引用任何逆向结论时，都应连带引用其证据等级与时间戳，供读者判断是否仍适用。

权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。

§7案例带

CAS-X-01 · 经 ESS-G-01

去中心化聊天架构逆向

对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。

CAS-X-02 · 2 跳派生：当前节点 → ESS-G-01 → ESS-G-05

网申填写扩展逆向架构

对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。

CAS-X-03 · 2 跳派生：当前节点 → ESS-G-01 → ESS-H-03

网申 v3 多模块解耦

一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。

CAS-X-04 · 2 跳派生：当前节点 → ESS-G-01 → ESS-H-03

网申 v2 深度重构

一次由「改一处漏多处」症状触发的深度重构：定位到接口定义散落 12 个文件、存在 7 种接口形态的根因后，以单一契约源、dispatch 消息表与能力注册中心重建三层契约系统，恢复可审计与可校验性。

CAS-X-08 · 2 跳派生：当前节点 → ESS-O-01 → MTH-O-06

dsh-manager 插件深度分析

以「编译依赖、运行时注入、组合装配」三硬依据加源码行号，对第三方插件做依赖、功能、需求溯源与设计问题裁决，并复用上游 DAG 知识库节点标识，使分析结果可与主图互查。

CAS-X-09 · 经 MTH-G-05

harness 源码架构解析

对 deepseek-harness 官方源码做分层解析：镜像官方架构文档，按九个层与九十余模块建立文档集群，产出跨层联动矩阵与七条关键路径，并钉住「模型可见即已记录」、能力缝三角等设计不变量。

CAS-X-10 · 经 MTH-G-05

dsh 插件依赖增量定位

以官方插件 DAG 为蓝本，对一个官方清单之外的全新社区插件做功能定位与依赖位置增量分析，产出可下钻交互依赖图与多形态文档的源码级架构逆向案例。

CAS-X-11 · 2 跳派生：当前节点 → ESS-G-01 → ESS-G-04

Hermes 七层架构总览

对八千余文件的工业级 AI Agent 项目做七层架构总览逆向，揭示其「越用越聪明」的自进化闭环如何在层间传导的控制型架构案例。

CAS-X-12 · 2 跳派生：当前节点 → ESS-O-01 → ESS-O-02

MCP 四件套选型对比

对四个同类 MCP 服务器做源码级能力与成本对比，并以常驻 token 预算为轴给出分级接入策略的技术选型实战案例。

CAS-X-15 · 经 MTH-G-05

Open Code Review 图谱

对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。

CAS-X-18 · 2 跳派生：当前节点 → ESS-O-01 → MTH-O-06

AI Agent 架构 DAG 复盘

对四个工作日内独立完成三个异构对象 DAG 分析的方法论复盘，总结「采集→建模→生成→门控→交付」可复用管线与关键教训。

§8信源与核验

核验状态True（verified）
置信度medium
复核日期2026-09-10
生命周期active
规范信源LOC-032
勘误
常见误解：从逆向源码里看到的模块就是产品实际启用的模块
核验结论：打包时按特性标志做死代码消除，「源码存在」不等于运行时启用；逆向结论须多源交叉并标注证据分级，避免把静态存在当运行时行为　[LOC-032]

§9原始关系清单

展开：本节点的全部原始关系边（3 条，含边 ID 与方向）
关系方向对端节点说明
案例印证→ ESS-G-01关注点分离
E-978		印证：查询引擎、工具、权限、记忆的关注点分离
案例印证→ ESS-O-01本质复杂度与偶然复杂度
E-980		印证：编译期特性裁剪消除偶然复杂度
案例印证→ MTH-G-05架构文档化方法
E-979		印证：多源交叉验证与分章文档化