Ontology Atlas：把代码库的意义也纳入 git diff
AI coding agent 越能改代码，review 的压力就越不像以前那样只看 diff。Diff 告诉你哪些行变了，agent summary 告诉你它声称做了什么，但经常缺一层东西：这段代码对应什么产品能力，为什么边界这样划分，改这里会牵到哪些模块，哪些判断只是猜测还没有证据。
今天看的是 wlsdks/ontology-atlas。它的想法不是再做一个代码索引，而是在仓库里放一个 atlas/ Markdown 文件夹，用固定的节点类型和关系把代码库的“意义层”写下来。人可以在桌面 app 里看图、编辑和 review；agent 可以通过 MCP 读取、查询、提出更新；最后是否接受，仍然回到 git diff。
按 GitHub repository API、README、LICENSE、package.json、release API、tags 和 commits feed 在 2026-09-01 18:06 Asia/Shanghai 能核验的信息，wlsdks/ontology-atlas 当前有 86 stars、14 forks。主要语言是 TypeScript，许可证是 MIT，默认分支是 main，仓库创建于 2026-04-29 12:21:36 UTC，latest push 是 2026-09-01 09:57:48 UTC。最新 main 提交是 f734c4d，提交时间 2026-09-01 09:51:48 UTC，主题是 fast-sensor lane 和 one-shot verification reminder hooks。最新 GitHub Release 是 v1.0.2，发布时间 2026-09-01 07:57:14 UTC；package.json 里项目版本也是 1.0.2，源码运行要求是 Node.js >=24 <25。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | wlsdks/ontology-atlas |
| 定位 | 面向代码库的本地 Markdown ontology、可视化 app、CLI 和 MCP server |
| Stars | 86 |
| Forks | 14 |
| 主要语言 | TypeScript |
| 许可证 | MIT |
| 创建时间 | 2026-04-29 12:21:36 UTC |
| Latest push | 2026-09-01 09:57:48 UTC |
| 最近提交 | f734c4d，2026-09-01 09:51:48 UTC |
| 最新 Release | v1.0.2，2026-09-01 07:57:14 UTC |
| 运行要求 | 桌面下载内置 MCP server；源码路径需要 Node.js >=24 <25 |
| 关键词 | codebase ontology、MCP、local-first、impact analysis、AI agents |
它补的是代码和意图之间的空档
很多团队已经有足够多的源码结构信息：语言服务器知道 symbol，grep 能找字符串，AST 工具能画调用关系，CI 会告诉你测试过不过。但这些工具通常不回答“这个文件为什么属于 checkout 能力”“这个边界为什么不能跨”“一个 agent 改完这里后，业务层面还应该验证什么”。
Ontology Atlas 的做法是把这些判断写成仓库内的 Markdown ontology。README 里把可作者写入的节点限定为 project、domain、capability、element、document 这几类，关系和证据也写在文件 frontmatter 里。这个限制很重要：它不是开放式 wiki，也不是让 agent 随便堆记忆，而是把可审阅的语义声明变成普通文件。
这和 AI agent 的 workflow 很贴。Agent 可以很快读完一个目录、提出一个修改计划、生成一段 summary，但它对“哪些意义已经被人接受”没有天然记忆。Atlas 把这层信息固定在 repo 里：下次 agent 开工前，可以先问 MCP server 哪些 capability、boundary、dependency 和 unknown 与当前任务相关；agent 完成后，也可以提出 ontology 更新，让人从 diff 里决定是否接受。
MCP 不是装饰，而是主要接口之一
这个项目最值得注意的地方，是它没有只把 ontology 做成一个给人看的图。仓库里的 mcp/README.md 写得很具体：MCP server 通过 stdio 暴露工具，让 Claude Code、Cursor、Codex 和其他 MCP client 读取、查询、维护旁边的 Markdown vault。compile_ontology 和 query_ontology 会把 Markdown 编译成确定性的运行时图，而不是要求你启动一个额外数据库。
这让它更像一个代码库意义层的 shared state。人看的是桌面 app 里的 map、architecture、docs、insights、projects 和 git history；agent 读的是同一个 vault 编译出来的查询结果。两边操作的不是两个系统，也不是把人类文档再喂给模型，而是同一批可版本化的 Markdown 文件。
安全边界也写得比较克制。MCP server 当前是本地 stdio，不是本地 HTTP 服务；写操作有 expected mtime、dry-run、confirm、overwrite、force 这类防护；破坏性操作要暴露机器可读的 decision fields。对会让 agent 写项目语义的工具来说，这些细节比“支持 MCP”四个字更关键。
为什么不是另一个知识库
README 反复强调它不是通用 ontology editor、不是 wiki、不是 agent memory，也不是代码索引。这个定位比较窄，但窄得有价值。一个通用知识库很容易变成“什么都能写，最后没人维护”；agent memory 又容易变成“模型说了算，没人 review”。Atlas 把仲裁点放回 git：任何新增或修改的意义声明，都应该像代码一样能被 diff、comment、revert。
它也不试图替代现有代码理解工具。更合理的用法，是把 Atlas 当成“先问该问什么”的层。比如你要改 checkout flow，Atlas 可以告诉 agent 这属于哪些 capability、依赖哪些 domain、有哪些 architecture rule、哪些证据已经过期。接下来仍然要用 grep、LSP、测试和人工 review 去验证具体代码。
这种边界让它适合长期项目，而不是一次性提问。对新 repo，它的成本可能偏高；对经历过多轮 agent 修改、文档和现实开始脱节的 repo，它的价值更明显。核心问题不是“能不能自动理解所有代码”，而是“团队能不能维护一份足够小、足够明确、能被 agent 使用的项目语义地图”。
安装和使用路径
README 当前把桌面 app 放在主要入口。macOS 版是签名和 notarized 的 app，下载包里带有编译好的 MCP server；Windows x64 是公开 beta，并且 README 明确提醒它是 unsigned，可能被 SmartScreen 或企业设备策略拦截。源码路径可以 clone 仓库，但 package.json 要求 Node.js 24.x。
项目还明确说它不在 npm 上，npx ontology-atlas 不是安装入口。这个 caveat 值得写出来，因为很多开发者看到 TypeScript + CLI + MCP 会本能地找 npm 包。当前更稳的理解是：桌面 app 内置 server，源码 checkout 是 fallback，agent 配置由 app 或 CLI 写入本地配置文件。
适合谁
第一类是已经让 coding agent 深度参与开发的团队。一次 agent patch 不难 review，难的是连续十几次之后，项目边界、能力说明、验证清单和架构意图都被口头 summary 冲散。Atlas 试图把这些东西变成可维护资产。
第二类是本地优先、重视审计的人。它没有把项目语义放进云服务，核心数据就是仓库里的 Markdown。你可以 branch、commit、review、revert，也可以让 agent 通过 MCP 读取同一份资料。
第三类是需要做影响分析的人。不是那种“谁 import 了谁”的纯结构分析，而是更靠近产品和架构语义的 blast radius：改一个 capability，哪些 boundary、document、element 和 unknown 应该一起看。
Caveats
第一，维护 ontology 本身需要纪律。工具能把图画出来，能让 agent 提议更新，但什么应该成为 capability、什么只是实现细节、哪些 evidence 足够可信，仍然要靠人判断。没有这个 review 习惯，它就会退化成另一份会过期的文档。
第二，项目还很年轻。仓库创建于 2026-04-29，虽然提交和 release 很密集，但真实团队长期使用的经验还需要时间积累。把它接到核心仓库前，最好先从一个边界清晰的子系统试跑。
第三，安装路径不像普通 npm CLI 那么轻。桌面 app 是主要路径，Windows 还是 unsigned beta；源码运行又要求 Node.js 24.x。它更像给认真使用 agent 的团队准备的工作台，而不是随手试一下的单命令小工具。
总结
wlsdks/ontology-atlas 有意思的地方，是它把 AI agent 时代的一个真实 review 痛点拿得很具体：代码变得更快，但“代码现在代表什么”也需要被版本化。它没有承诺自动理解一切，而是把项目意义层压进一个小而可审阅的 Markdown vault，再用桌面 app、CLI 和 MCP 把人和 agent 接到同一份状态上。
如果你的团队已经开始让 agent 做跨文件、跨模块的长期工作，Ontology Atlas 值得观察。它的成本不低，但问题抓得准：真正需要长期维护的，不只是代码 diff，还有每次 diff 背后的能力、边界和验证责任。