五月月报：读复杂系统源码的方法 —— 最小模型与补丁列表

覆盖范围：5.7 / 5.11 / 5.18 / 5.25 四周。本月工作背景一句话：从零启动后端项目（Go 技术选型、Cloudflare Serverless 网关、支付系统设计），同时深入研读 Claude Code 与 Hermes Agent 的源码级架构。

本月方法地图

mindmap
  root((五月方法))
    研究方法
      对照学习法
      Agent 评估五维框架
    技术选型
      选型三问
      前端体验 后端安全
    系统设计
      差异收敛到适配层
      文档先行做约束
      成本优化即能力
    工程卫生
      密钥只记用途不记值
      中间态不存储

原理深读：对照学习法 —— 用 "最小模型 + 补丁列表" 理解生产系统

是什么：读一个复杂系统的源码时，先读它的教学级（最小）实现建立心智模型，再读商业级（生产）实现，把两者的差异逐项对齐。每个差异都对应一个真实的生产约束。最终得到的理解 = 最小模型 + 一张 "补丁列表"。

为什么成立：生产系统的源码里，本质设计和偶然细节混在一起。单独读商业级实现，会被细节淹没 —— 分不清哪些是核心思想、哪些是历史包袱；单独读教学级实现，得到的心智模型又缺了生产必须回答的问题（上下文怎么管、错误怎么恢复、子任务怎么隔离）。两者对照后，"生产级 = 教学级 + 显式补丁" 这个分解成立了：每个补丁都有名字、有动机、有代价，理解就从记忆变成了结构。

本月验证：Claude Code（商业级实现）与 Hermes Agent（按教学级最小实现研读并复刻）对照阅读。上下文压缩分五层、Fork Subagent 为省 90% API 费用做字节级缓存对齐、记忆系统用小模型并行预取 —— 这些 "补丁" 在最小模型里都不存在，对照后才看清它们各自解决什么问题。Anthropic 官方对 compaction 的公开描述与此互证：摘要保留架构决策、未解决 bug 与实现细节，丢弃冗余工具输出，agent 携带压缩上下文与最近访问的五个文件继续工作。

为什么有效（机理）：工作记忆有限，人只能同时操作少数变量。对照学习把变量数从 "生产系统的全部细节" 降到 "最小模型 + 当前正在看的那个差异"，认知负荷始终可控。这也解释了为什么先读教学级、再读商业级的顺序不能反 —— 没有骨架时，肉挂不上去。

边界在哪：

两个实现必须是同域的：对比 "同一个问题" 的两份答案才有意义，拿不同领域的项目对照只会得到噪音。
补丁列表会过期：框架和产品迭代快，方法论（怎么对照）可迁移，具体补丁会失效。
教学级实现省略的不只是复杂度，有时是正确性 —— 不能把最小模型的简化当成设计定论。

沉淀出的配套工具：Agent 评估五维框架 —— 拿到任何 Agent 系统，问五个问题：上下文管理怎么做？权限控制怎么做？记忆怎么存？技能 / 经验怎么复用？错误怎么恢复？它是对照学习法的 "提问器"，保证对照时不会漏维度。

业界对照：Anthropic 在工程博客中公开了同类系统的设计骨架（gather context → take action → verify work 的 agent loop、subagent 隔离上下文、compaction 摘要压缩），与本月源码研读中提炼的 "五维" 高度重合 —— 这反过来验证了五维框架抓的是主流生产系统的共性约束。

原理清单

选型三问：为什么选？比竞品好在哪？效果如何？回答不了第三问的选型不算完成。用于任何技术引入。
权限分层：前端权限只改善体验，后端权限才保安全。安全边界必须落在攻击者绕不过的层。Casbin（策略引擎）+ JWT 黑名单（主动失效）的组合就是为了把安全做在后端不可绕过处。
差异收敛到适配层：统一入口背后必须承认差异 —— 文本走 Gateway 兼容端点、图像走 env.AI.run()，每个模型参数独立声明。好的系统不是假装差异不存在，而是把它关进适配层。透传不等于统一：统一透传遇到不支持的字段直接报错。
文档先行是约束不是说明书：PRD → TECH → PLAN → TEST 先写再码，后续代码和 agent 执行才不漂移。
流程约束优于模型自觉：自动化系统能否稳定工作，取决于它是否明确知道下一步做什么、用什么上下文、怎么验收 —— 而不是模型有多聪明。
成本优化是能力基础设施：Fork Subagent 省 90% 成本，意味着原本因成本不敢派的任务进入可行集。降成本不是省钱，是扩边界。
中间态不存储：SSE 流式输出只存最终完整结果，不存中间增量。存储成本与可回放性的取舍，默认取前者。
密钥卫生：日志和文档只记配置项、用途、存放位置，不记值。值交给密钥管理。

反例与边界

"统一调用路径" 不是目标：强行用 Gateway 兼容端点调用图像模型行不通（端点不支持），统一性只在协议层成立、不在能力层成立。为了统一而统一会把系统做错。
v1 未稳不做 v2 兼容：过早兼容是过度设计（本月记账，6 月在提示词拆解重构中再次验证）。

参考资料

Hermes Agent — Nous Research 开源的自进化 agent（Python，生产级：多平台 gateway、任务后自建技能）。注意：公开仓库并非 "教学级最小实现" 的出处 —— 后者是研读时按其设计自行搭建的最小复刻。
Building Agents with the Claude Agent SDK — Anthropic 工程博客：agent loop（收集上下文 → 行动 → 验证）与 subagent 机制。
Effective Context Engineering for AI Agents — Anthropic 对上下文压缩（compaction）与子 agent 隔离的公开描述，对应源码研读中的 "补丁"。
Apache Casbin — 权限策略引擎，PERM 元模型，"后端权限保安全" 的落地工具。
JWT Introduction — JWT 结构与签名机制官方入门，对应无状态认证 + 黑名单 + 续签方案。
Cloudflare AI Gateway — 官方文档：缓存、限流、日志、模型回退等网关能力总览。
Workers AI Bindings — env.AI.run() 绑定机制官方说明：资源注入而非密钥管理。
New API — 自托管 AI 网关（多渠道聚合 / 分发），本月架构阅读与二开的对象。
Server-Sent Events（MDN） — SSE 协议权威参考，对应流式输出设计。
支付宝异步通知说明 — notify_url 重试策略与验签要求，支付回调幂等设计的一手依据。