这篇是实操文。目标很简单：让你在自己的项目里跑通一次完整流程——
Agent 提架构提案 → 校验 → 你审阅 → 批准或拒绝 → Agent 自动继续。
全程大约 20–30 分钟，前提是你已经有一个能正常使用的模型 Provider。
0. 先确认你适合用 Jin
Jin 不是给所有编辑动作准备的。它关注的是结构性改动，比如：
- 新增或拆分模块；
- 调整模块依赖和分层；
- 新增对外暴露的实体、接口、字段；
- 把某个实现从一个模块移到另一个模块；
- 修改系统边界或外部依赖。
如果你只是想改错别字、补注释、调 CSS，不需要走 Jin 的审批流程。把它当成“架构 级改动的红绿灯”，而不是“每次保存都要弹窗的编辑器”。
另外，Jin 是 OpenCode 的社区分支，不是 OpenCode 官方产品。它不内置模型，也不带 模型凭据；你需要先在 OpenCode 里配置好自己的 Provider。
1. 安装：安装包或源码
方式 A：下载桌面安装包
v2.0.32-jin.1 已经提供 macOS（Apple Silicon / Intel）、Windows x64、Linux x64 的构建：
按平台选择对应的 .dmg、.zip、.exe、.AppImage、.deb 或 .rpm。发布页
还附带 SHA256SUMS.txt，下载后可以校验。
当前构建是未签名的，所以系统可能会拦一下：
- macOS：右键应用选择“打开”，或到“系统设置 → 隐私与安全性”里点“仍要打开”。
- Windows：SmartScreen 提示时点“更多信息 → 仍要运行”。
- Linux AppImage：下载后
chmod +x，再运行。
当前版本还关闭了自动更新，避免 Jin 构建被上游 OpenCode 的更新源覆盖。后续版本 需要手动下载安装。
方式 B：从源码运行
如果你已经有 Bun：
git clone git@github.com:ZYF93/opencode-jin.git
cd opencode-jin
bun install
bun run dev:desktop
桌面端会直接使用当前 checkout 的源码 CLI，因此 Jin 的服务器插件和 GUI 扩展都会 生效。
注意：不要用 OpenCode 官网的一键安装脚本，然后期待得到 Jin。那条命令安装的是 上游 OpenCode，不包含这个分支的 Jin 功能。
2. 打开项目，生成第一份架构
启动桌面端，打开一个你想试的项目。
在侧边栏找到 架构 面板。它是一个固定标签页，也可以通过命令
Open Jin architecture 打开。
如果项目里还没有 arch/L0.yaml，面板会提示你扫描。点击 扫描当前代码：
- Jin 会用和服务器相同的扫描器生成草稿；
- 不会覆盖已有的
arch/； - 生成的是声明级结构，不是完整语义模型。
第一次扫描后，建议先花几分钟看看：
- 模块划分是否符合你的理解；
- 公开实体有没有明显遗漏；
- 有没有把不该跨层依赖的东西标出来；
- 语言支持是否符合你的项目。
Jin 目前支持 TypeScript / JavaScript、Python、Java、Kotlin 的声明级扫描。它优先 稳定和可审阅，不追求完整编译器语义。
3. 给 Agent 一个“结构改动”任务
不要一上来就说“帮我重构一下”，太模糊。用下面这个模板：
为取消订单增加审计路径。
请创建一个 Jin 提案：
1. 先读取当前架构；
2. 只编辑当前提案版本的目标 L0/L1 文件；
3. 修改代码让目标架构与真实实现对齐；
4. 用 jin_validate 校验；
5. 校验通过后停下来等待我审批，不要自己批准。
几个关键点：
- 明确说“创建提案”，否则 Agent 可能直接改代码；
- 明确说“只编辑目标文件”，避免它绕过提案改正式架构；
- 明确说“校验后等待”，让
jin_validate成为交接点； - 不要让它自己批准，它也没有这个权限。
Agent 做完后，你会看到目标架构、结构化差异、校验摘要和漂移提示。校验通过时，
提案进入 in_review，审批面板会自动打开。
4. 审阅：重点看这四件事
审批面板不是让你逐行读 YAML。重点看：
① 结构差异
新增节点是绿色 +，删除是红色虚线 −，变更是琥珀色 ~，移动是紫色 ›。
先看有没有你没预期的模块或依赖变化。
② 跨层依赖
跨层模块依赖是蓝色虚线，跨层实体依赖是青色实线。问自己：这条依赖是这次需求 需要的，还是 Agent 为了省事抄近路？
③ 实体检查器
选中实体后，右侧会显示完整字段、方法和关系。重点看公开实体有没有多出来、位置 有没有放错、字段和方法是否和代码一致。
④ 校验与漂移
location-not-found/symbol-not-found：声明的文件或符号不存在，是错误；symbol-unregistered：代码里有公开符号没登记到 L1，是警告；base_hash不一致：提案创建后架构变了，需要基于当前架构修订；planned实体已经存在：提示，不是错误。
如果你觉得方向不对，直接点 拒绝，写一句备注，比如：
不要把审计逻辑放进订单模块，抽成独立模块，并通过事件解耦。
拒绝不会修改 arch/，但会把备注带回给 Agent，并自动继续。Agent 会基于你的意见
修订提案，不需要你再发一句“继续”。
5. 批准之后发生了什么
你点 批准并应用 后：
- 桌面端把决策和你审阅过的目标哈希发给服务器；
- 服务器验证 HMAC 签名、目标哈希和基线架构；
- 验证通过后，把目标写入正式
arch/； - 服务器给会话发一条合成继续消息；
- Agent 接着做实现、测试或你要求的下一步。
如果目标在你审阅之后被改了，哈希不匹配，批准会失效。这是刻意设计的：你批准的 必须是你实际看过的那个版本。
如果提案创建后正式架构已经变化，base_hash 会不一致，默认不能直接应用。正常做
法是基于当前架构修订提案；只有确实需要覆盖时，才走显式的 force 路径。
6. 四个可复用的提示词
新增模块
新增一个通知模块，负责邮件和站内信。
请创建 Jin 提案，定义模块边界、公开实体和依赖；
只编辑目标文件，修改代码后用 jin_validate 校验，然后等待我审批。
拆分服务
把订单模块里的支付调用拆成独立模块，保持现有行为不变。
请先给出目标架构和依赖变化，再修改代码；
校验通过后停下来等我审批。
增加实体字段
给 User 实体增加 locale 字段，并更新相关 API。
请创建提案，更新 L1 目标，确保 location 指向真实声明；
校验通过后等待审批。
让 Agent 修订被拒绝的提案
根据我的拒绝备注修订当前提案。
不要新建提案，基于当前版本生成下一版；
修改后重新校验，并等待我再次审批。
7. 常见问题
| 现象 | 处理 |
|---|---|
| 面板提示决策已保存，但 Agent 没有继续 | 正常发一条消息。决策已经持久化，只是合成恢复失败。 |
| 审批面板没有自动打开 | 手动打开 架构 面板，提案仍在待审批状态。 |
symbol-unregistered 警告 | 代码里有公开符号没登记到 L1。补实体，或标记为 internal。 |
location-not-found / symbol-not-found | 声明的文件或符号不存在。修正目标或代码后重新校验。 |
base_hash 不一致 | 提案创建后架构变了。基于当前架构修订；不要一上来就 force。 |
approval signature invalid | 签名密钥变了。用当前密钥重新批准，或保持 JIN_APPROVAL_SECRET 稳定。 |
| 扫描结果不符合预期 | 先确认语言支持和目录范围；声明级扫描不保证完整语义。 |
| 模型没有响应 | Jin 不内置模型。先在 OpenCode 里配置可用的 Provider。 |
| macOS 提示“无法验证开发者” | 当前构建未签名，右键打开或到隐私与安全性里允许。 |
| Windows 出现 SmartScreen | 点“更多信息 → 仍要运行”。 |
8. 使用建议
- 先在小项目试。 扫描、提案、审批都跑顺，再放到核心仓库。
- 一次只做一个结构决策。 提案太大，审阅会退化成“看个大概”。
- 拒绝时写具体原因。 备注会回到 Agent，模糊的“再想想”没有信息量。
- 把测试留给 CI。 审批门保证架构决策经过你，不证明实现正确。
- 不要手动改
meta.yaml或decisions/*.yaml。 它们不会批准提案，反而会让 状态更难排查。 - 保持签名密钥稳定。 换密钥会让旧决策签名失效。
- 关注漂移，但别追求零警告。 警告是让你看见不一致，不是让你把扫描器关掉。
9. 它现在还不做的事
- 不替代代码审查、测试或 CI；
- 不内置模型，不绑定 Provider；
- 不是完整编译器或类型检查器；
- 目前以桌面端为主，不是独立可下载的 Jin 应用；
- 超大仓库的漂移扫描以后可能需要缓存。
这些限制不是“以后再说”的免责声明，而是当前设计的一部分。知道边界，才能判断它 适不适合你的项目。
项目与下载
项目地址：
v2.0.32-jin.1 下载：
中文完整指南（架构模型、审批契约、安全、排错）：
跑通之后，欢迎回到评论区告诉我：你最想让 Jin 支持哪种结构性改动？或者直接去 GitHub 开 issue，把真实项目里的痛点丢过来。
