AI 写代码越来越快，架构文档却死得更快了

最近两三年，我几乎每天都在用 AI 写代码。

它确实快。一个下午能做完以前一两天的活，改一个模块、补一组测试、顺手把调用方 一起迁掉，都不在话下。但用久了我发现一个更麻烦的问题：

代码在飞速变化，架构文档却死得更快了。

这里说的“架构文档”，不是那种写完就没人看的 Word，而是团队真正拿来做决策的 东西：系统分几层、模块之间允许怎么依赖、每个模块对外暴露什么、某个实体应该 放在哪里。

AI 可以在十分钟内加一个新模块，但架构图不会自己更新。下次有人问 “订单和支付为什么直接耦合了”，你只能去翻 diff；而 diff 只会告诉你哪几行变了， 不会告诉你系统结构发生了什么。

更危险的是，AI 做架构决策时，往往没有人真正“批准”过。它可能在一次看似普通的 重构里，悄悄引入了一条跨层依赖；也可能把本该独立的模块合并在一起。你事后在 代码审查里看到了，但那时它已经写完了。

我想解决的，就是这一段。

我做了个什么

Jin 是 OpenCode 的一个社区分支，不是新模型，也不是新 IDE。

它在 OpenCode Desktop 里加了一层面向架构的开发流程：

1. Agent 要改结构，先创建一个 Jin 提案。
2. 提案里保存目标架构快照，架构部分只能编辑提案指定的目标文件。
3. jin_validate 用真实代码校验目标：位置、符号、依赖、漂移。
4. 校验通过后，桌面端自动打开审阅面板。
5. 用户点一次 批准并应用 或 拒绝。
6. 服务器签名并应用目标，然后 Agent 自动继续。

一句话：把结构性改动从“直接改代码”变成“可审阅的提案”，再把审批和继续做成 一个动作。

为什么不是“再画一张架构图”

市面上的架构工具很多，画图也不难。难的是让架构图和代码一直保持一致，并且让 Agent 真的经过它。

Jin 的做法是把架构做成两层小型 YAML：

• L0：项目、系统、包、模块、分层、外部依赖、约束。
• L1：每个模块里的实体、位置、字段、方法、关系。

它不追求把整个代码库建模成一张巨大的图，而是保留对决策最有用的部分。实体 ID 是稳定引用，位置必须指向真实声明，否则校验不通过。

这样做有几个好处：

• 架构可以进 Git。 每个提案都有版本、理由、验收标准和结构化差异。
• Agent 可以读，也可以改。 它不需要猜项目结构，而是对着真实的 L0/L1 工作。
• 校验不靠“感觉”。 jin_validate 会扫真实代码，检查声明的文件和符号是否 存在。
• 审批不是聊天里的“好的”。 决策由服务器签名，并绑定到用户审阅时的目标 哈希；审阅后目标被改了，批准就失效。

一次真实的流程

假设我在一个电商项目里说：

为取消订单增加审计路径。创建一个 Jin 提案，只编辑目标文件，并校验。

Agent 会做几件事：

1. 读取当前架构，找到订单模块和取消订单相关的实体。
2. 创建提案，生成 target-L0.yaml 和 target-L1/*.yaml。
3. 修改代码，并让目标架构与代码对齐。
4. 调用 jin_validate。

如果校验有错，比如声明的函数不存在、位置写错了、跨层依赖不合法，Agent 会拿到 错误并继续修。校验通过后，提案进入 in_review，桌面端会自动打开审批面板并选中 这个提案。

我看到的是：

• 目标架构和当前架构的结构化差异；
• 新增、删除、变更、移动的节点；
• 跨层依赖和实体依赖；
• 校验摘要和漂移提示；
• 可选备注。

然后我只需要点一次。

批准：服务器验证签名、目标哈希和基线架构，把目标写入 arch/，再给会话发一条 合成继续消息，Agent 接着做实现。

拒绝：服务器保存决策和备注，不修改 arch/，同样自动继续。Agent 会带着我的 意见去修订，而不是停下来等我再发一句“继续”。

这个“拒绝也自动继续”的细节看起来很小，但它决定了这套流程能不能真的用起来。 很多审批工具的问题不是没有审批，而是审批完之后流程断了，用户还得手动催一次。

为什么审批门放在服务器

这是我在设计时最坚持的一点。

如果审批只是一个前端按钮，那么它本质上还是“UI 层约定”。Agent 可以绕过 UI 直接改文件，脚本也可以伪造一个“已批准”的状态。

Jin 把决策权放在服务器：

• 服务器持有 HMAC 密钥；
• 桌面端只发送“我的决策”和“我审阅过的目标哈希”；
• 服务器验证签名、目标哈希和基线架构，才允许应用；
• 手动修改 meta.yaml 或 decisions/*.yaml 不会生效。

这不是为了防住所有攻击，而是为了明确一件事：Agent 有提案权，但没有批准权。

这个边界一旦清楚，很多流程就顺了。Agent 不需要猜“用户是不是同意了”，它只要 知道“提案还在等待决策”；用户也不需要在一堆聊天记录里找自己有没有说过“可以”。

它现在还不是什么

我不想把这篇文章写成“又一个改变世界的 AI 工具”。Jin 现在还很早期，有几个明确 的限制：

• 以桌面端为主。 GUI 扩展已经注册，但还不是一个独立可下载的 Jin 应用。
• 扫描器是声明级的。 它优先稳定、可审阅的结构，不是完整编译器或类型检查器。
• 审批不替代测试。 它保证架构目标经过用户决策，但不能证明实现符合意图； CI、代码审查、测试仍然必要。
• 当前安装包未签名。 macOS 可能需要“仍要打开”，Windows 可能触发 SmartScreen。
• 自动更新已关闭。 这是为了避免 Jin 构建被上游 OpenCode 的更新源覆盖。
• 模型要自己配。 Jin 不内置模型凭据，也不带 Python sidecar；模型由用户通过 OpenCode 提供。

这些限制我都写进了文档，因为一个工具值不值得试，不只看它吹了什么，也看它敢 不敢把边界说清楚。

适合谁试

如果你符合下面任意一条，Jin 可能值得花半小时看看：

• 你已经在用 OpenCode、Cursor、Claude Code 这类 AI 编码工具；
• 你做过“AI 一口气改了十几个文件，review 时不知道结构变没变”的噩梦；
• 你在维护一个多人协作、模块边界很重要的项目；
• 你想让架构文档真正进入开发闭环，而不是季度汇报时才更新；
• 你对“Agent 提案、人类审批、自动继续”这种协作模式感兴趣。

如果你只是想让 AI 帮忙改个错别字、补个注释，Jin 可能有点重。它关注的是结构性 改动，不是所有编辑。

怎么试

项目地址：

github.com/ZYF93/openc…

v2.0.32-jin.1 已经发布了 macOS（Apple Silicon / Intel）、Windows x64、Linux x64 的桌面安装包：

github.com/ZYF93/openc…

也可以从源码运行：

git clone git@github.com:ZYF93/opencode-jin.git
cd opencode-jin
bun install
bun run dev:desktop

中文完整指南：

github.com/ZYF93/openc…

如果你试了，欢迎告诉我三件事：

1. 你的项目里，哪种结构性改动最需要审批？
2. 现在的架构图和审阅界面，哪里最碍事？
3. 你希望 Jin 先支持哪种语言或框架？

项目还早，拍砖比 star 更有价值。但如果这个方向对你有一点启发，也欢迎点个 star， 让更多人看到。

AI 写代码的速度已经够快了。接下来要补的，可能是让它别把架构甩下车。