代码 diff 是给实现者看的，架构 diff 是给决策者看的。
这句话听起来有点绝对，但你可以回想一下 review AI 代码时的体验：
- 500 行 diff，十几个文件；
- 有些是格式化，有些是移动，有些是真的逻辑变化；
- 测试过了，但你说不清系统结构有没有变；
- 过两周再看，连自己当时为什么批准都忘了。
代码 diff 回答“哪几行变了”，但不回答“系统变成了什么样”。
所以 Jin 把架构也做成了可以 diff 的东西。
一、架构 diff 到底看什么？
Jin 的结构化差异不只有“新增/删除文件”，它覆盖：
- 系统、包、模块；
- 实体、字段、方法；
- 模块依赖、实体关系；
- 分层和约束；
- 变更文件；
- 新增、删除、变更、移动的数量摘要。
举个概念上的例子。一个“给取消订单加审计”的提案，架构 diff 可能会告诉你：
+ module audit
+ entity audit.event
+ orders -> audit (emits)
~ entity orders.cancelOrder
relations: + emits audit.event
~ module orders
public_entities: + fn-cancel-order
这比“orders.ts 改了 80 行”更接近人真正想知道的答案：
- 多了一个模块；
- 多了一个实体；
- 订单和审计之间多了一条关系；
- 订单的公开接口变了；
- 哪些文件被改了。
你仍然要看代码，但你先知道了这次改动在结构上意味着什么。
二、为什么架构 diff 更容易读？
因为它的抽象层级刚好。
代码 diff 太细：一个重命名能产生几十行噪音，一个移动能看起来像重写。 架构 diff 太粗：如果只有一张“系统架构图”，又看不出这次到底改了什么。
Jin 的 diff 在中间：
- 它不是每一行代码，而是模块、实体、依赖这一级；
- 它能标出新增、删除、变更、移动；
- 它把“变更文件”作为线索，而不是让人从文件列表里猜；
- 它能按提案版本对比，而不是只看最终结果。
在架构图模式里，这些变化还有颜色：
- 新增节点：绿色
+； - 删除节点：红色虚线
−； - 变更节点：琥珀色
~； - 移动节点：紫色
›。
颜色不是为了好看，是为了让 review 的眼睛有优先级：先看新增和删除，再看变更， 最后看移动。
三、每个版本都要能讲清楚自己
AI 改代码很容易出现一种情况：v1 写完，你说“不对”，它改出 v2；v2 又不对，改出 v3。最后你只记得“改了好几轮”，但说不清每一轮到底改了什么。
Jin 的提案是版本化的：
arch/proposals/<REQ>/
versions/
v1/
target-L0.yaml
target-L1/<module>.yaml
summary.yaml
v2/
...
decisions/
v1.yaml
v2.yaml
每个版本有：
- 完整的目标快照；
- 结构差异；
summary：这一版做了什么；rationale：为什么这么做；- 决策记录：谁批准/拒绝、备注、时间、目标哈希。
这意味着你可以回答：
- v1 为什么被拒绝？
- v2 相对 v1 改了什么？
- 当时批准的是哪一版？
- 应用之后正式架构变成了什么样？
这比“聊天记录里翻半天”可靠得多。
四、一个典型的 review 场景
假设 Agent 说它完成了“审计功能”。你打开代码 diff，看到：
orders.ts多了一个audit调用；types.ts多了一个事件类型；audit.ts是新文件；- 另外还有几个不相关的格式化。
代码看起来没问题。但你真正想确认的是：
- 这是新模块，还是塞在 orders 里的一个文件？
- orders 是直接依赖 audit，还是通过事件解耦？
- audit 的实体有没有登记，位置对不对？
- 有没有多出跨层依赖？
- 这次改动有没有碰到 payment？
架构 diff 会把这些答案先摆出来。你不需要从 500 行里推理，只需要看结构变化， 再决定要不要深入某个文件。
这就是“先看架构 diff，再看代码 diff”的价值：不是替代代码 review，而是给代码 review 一个地图。
五、它不能替代什么
架构 diff 不是万能的：
- 它看不出实现细节的 bug；
- 它不能证明业务逻辑正确；
- 它不能替代测试、性能检查和安全审查；
- 如果架构声明本身是错的，diff 也会跟着错。
所以 Jin 的定位不是“用架构图代替代码”，而是把结构变化从代码 diff 里抽出来， 让人先做结构判断，再做实现判断。
一个很实际的顺序是：
- 先看架构 diff：方向对不对？
- 再看变更文件：有没有越界？
- 最后看关键代码：实现有没有问题？
- 跑测试和 CI：行为有没有坏？
这比一上来扎进 500 行 diff 更省脑子。
六、为什么这对 AI 编程特别重要
人类改代码，通常会留下 commit message、PR 描述、设计文档。AI 改代码，很多时候 只留下一个“已完成”的聊天消息。
版本一多，人就失去了叙事：
- 这次为什么加这个模块？
- 上一版为什么被拒？
- 这个依赖是什么时候出现的？
- 我当时到底批准了什么？
架构 diff 加上版本化提案，补的就是这段叙事。
它不是让 AI 写得更快，而是让 AI 写完以后，人还能理解、复盘和追责。
项目地址：
v2.0.32-jin.1 下载：
中文完整指南：
Jin 是 OpenCode 的社区分支，不是 OpenCode 官方产品。架构 diff 是审阅工具，不是 正确性证明；代码 review、测试和 CI 仍然必要。
