opencode.nvim 架构治理揭秘：依赖拓扑扫描器如何用 CI 门禁守护分层架构

opencode.nvim 是 OpenCode 终端 AI 编码代理的 Neovim 前端，负责在编辑器里完成 AI 对话、上下文投递与修改审查。当聊天面板、会话标签、diff 审查、quick chat 等特性不断叠加，模块之间的依赖很容易失控——而它的架构治理，就藏在 scripts/dependency-topology/ 目录里：一个自研的依赖拓扑扫描器，配合make topology-check这道CI 门禁，把四层分层架构钉死在每一次 Pull Request 里。

一、为什么 AI 编码插件也要做架构治理

先认识一下主角。opencode.nvim 让你在 Neovim 侧边栏里和 AI 代理对话：发送文件、选区、诊断信息作为上下文，再逐条审查它改的每一行代码（可参考 docs/recipes/ 目录下的实践示例）。

支撑这些体验的，是lua/opencode/下近百个模块：从按键绑定到渲染管线，从命令解析到协议通信。模块一多，最容易出现的退化就是：

• 🔁循环依赖：A 要 B、B 又要 A，一碰就炸；
• 🧭跨层乱调：UI 层绕过业务层直接调底层连接，边界消失；
• 🕳️无人认领的模块：没被任何规则覆盖，等于"法外之地"。

项目没有靠人肉 review 硬扛，而是写了一套静态分析工具——依赖拓扑扫描器，把架构约束变成可执行、可对比、可门禁的规则。

二、四层分层架构：依赖只许"向下"

整个分层策略定义在 topology.jsonc 这个"策略文件"里。它把每个 Lua 模块划进 5 个组，规则只有一条：导入（require）只允许指向更低的层。

具体禁止关系由文件末尾的policy.rules给出 7 条规则，例如no_entry_to_infra（入口层不得直连基础设施层）、no_infra_to_capabilities（底层不得反向上调）。规则还支持allowed白名单——比如:checkhealth诊断入口被明确允许直连server_job，因为诊断必须驱动真实的连接生命周期。这种"规则 + 例外 + 例外理由"的写法，本身就是架构治理的一部分。

三、依赖拓扑扫描器：它到底在查什么

扫描器由 5 个文件组成，各司其职（详见 scripts/dependency-topology/README.md）：

• scan_topology.py：CLI 入口，提供scan/diff两个子命令；
• scan_analysis.py：核心分析——分组匹配、边缘规则判定、结果 payload 构建；
• graph_utils.py：纯图算法，用Tarjan SCC找强连通分量、识别反向边；
• html_renderer.py：生成交互式 HTML 依赖图，违规边用红色标出；
• topology.jsonc：分层分组 + 策略规则 + 审查备注。

它检查三类问题：

1. 分层违规（layer-rule breaks）：某条require指错了方向，比如 Entry 层直接 import 了 Infrastructure 层；
2. 循环依赖（import loops）：互相依赖成圈的模块团，按严重度（分量大小）标注；
3. 无层模块：没被任何模式匹配到的文件——它的导入根本不会被检查，必须归零。

扫描基于 git 快照：可以对比HEAD、worktree（含未提交改动）、任意分支名或 commit SHA，所以历史欠账和当前债务可以分开看。

四、CI 门禁：make topology-check 如何拦住架构腐化

治理的关键不在"能扫出来"，而在"不修就不让合"。Makefile 里定义了这道门禁：

make topology-check # 默认对比 origin/main make topology-check TOPOLOGY_BASE=upstream/main

底层实际执行的是scan_topology.py diff --from $(TOPOLOGY_BASE) --to worktree --check，它的判定策略非常克制：

• ❌新增的分层违规 → 直接失败；
• ❌新增或变大的循环依赖 → 直接失败；
• ❌任何无层模块 → 直接失败；
• ✅ 已有的历史债务 → 只报告、不拦截。

这正是增量治理的思路：承认存量问题存在，但绝不允许债务继续增长。门禁通过还会把一份 Markdown 报告以评论形式贴到 PR 上（diff --check --markdown），让每个改动者都看得见依赖变化的方向。AGENTS.md 也明确要求贡献者用扫描器（而不是 grep）来度量架构债务。

五、动手体验：三条命令上手

克隆仓库后（git clone https://gitcode.com/gh_mirrors/ope/opencode.nvim），装上 requirements.txt 里的 Python 依赖（有uv的话make目标会自动拉取），就能跑通完整流程：

--json输出里有几个值得留意的信号字段：health（一眼看清循环/违规/覆盖状况）、cycles（强连通分量明细与示例环）、violations（按规则分组的违规边）、group_coverage（各层模块计数）。

六、给新贡献者的启示

• 📌新文件不用操心：绝大多数目录已被通配符覆盖（如opencode.services.*、opencode.ui.renderer.*），只有落在通配符之外的文件才需要往 topology.jsonc 里加一行；
• 📌先归层再写码：提交前用make topology自查，比等 CI 红掉更快；
• 📌例外要留痕：文件里每处allowed白名单和REVIEW:备注都写明了理由，新增例外请照此办理；
• 📌欠账可以还：策略文件里标注的 REVIEW 项（如opencode.ui.ui对 Entry 层的反向依赖）就是现成的重构任务清单。

写在最后

opencode.nvim 的做法给所有中大型 Lua 插件打了个样：把架构约束写成策略文件，用扫描器翻译成机器可判定的规则，再交给CI 门禁执行增量拦截。分层不是刻在文档里的口号，而是每次 PR 都能过、才能合的硬约束——这才是架构治理能长期活下来的关键。

延伸阅读：docs/ 使用文档 · tests/ 测试与回放机制 · CONTRIBUTING.md