Topos 实战教程：给 AI 编码 Agent 装上代码质量“质检员”
你的 Claude Code 提交了一个 800 行的 diff，横跨 14 个文件。CI 全绿，语法完美，测试全过。但滚动到第 200 行时你意识到——Agent 在三个文件夹之外重新实现了一个早已存在的工具函数，还自创了一个看似简洁实则诡异的抽象层。你眼睛花了，体力耗尽，看着绿色的 CI 徽章，按下了 Squash and Merge。
这不是你的问题，这是 AI 编码 Agent 时代的通病。Krv Labs 的开源工具 Topos 就是来解决这个问题的——它不检查代码能不能跑，而是检查代码结构好不好。
Topos 是什么？
Topos 是一个面向 AI 编码 Agent 的结构化代码质量分析工具。它把代码解析成数学图结构（控制流图、模块依赖图、数据流图），从三个独立维度打分，最终给每个文件颁发一个代码质量勋章：
- SIMPLE（简洁）：AST 熵和 CFG 圈复杂度——代码是不是不必要的复杂？
- COMPOSABLE（可组合）：模块间耦合度——你改一个文件，其他文件会不会跟着崩？
- SECURE（安全）：危险 API 可达性和污染路径——有没有不安全的调用链？
| 勋章 | 条件 |
|:—|:—|
| 🥇 GOLD | 三个维度全部通过 |
| 🥈 SILVER | 通过两个维度 |
| 🥉 BRONZE | 通过一个维度 |
| ❌ SLOP | 一个都没过（或无法解析） |
这种设计的高明之处在于：它不是简单的”合格/不合格”二元判断，而是一个8 元素评估格——三个维度互相独立，GOLD 是它们的交集。Agent 在时间和 Token 预算内，可以根据优先级选择”保护哪个维度”。
快速上手
安装非常简单，一条命令：
curl -fsSL https://docs.krv.ai/topos/install.sh | sh
安装后即可使用。比如评估 src/ 目录下所有文件：
topos evaluate src/ -r
-r 参数会递归扫描，输出一个排过分数的摘要：哪些 Pillar 通过了、最差的文件、以及要翻转一个失败 Pillar 最便宜的修复路径。需要 CI 集成时加 --json 即可输出 JSON 格式。
想让 Agent 自己知道该优先保护哪个维度？用 --preferences：
topos evaluate src/ -r --preferences simple,composable,secure
如果不设偏好，Agent 在 GOLD 不可达时会优先尝试 silver 的任意一个组合。设了偏好后，它会按你的优先级降级——比如 simple,composable 意味着先保简洁和可组合性，安全可以暂时放一放。
检查单个文件和比较版本
想看单个文件的详细指标：
topos inspect src/app.py
想看两个版本之间的代码”走了多远”：
topos compare old_version.py new_version.py -v
compare 计算的是 AST 编辑距离——不是简单的行数加减，而是从语法树层面衡量代码的结构变化程度。比如 Agent 重构了一个模块后，用 compare 比对新旧版本，能清晰看到结构层面的改动量级。加上 -v 可以输出详细的差异分析。
COMPOSABLE 维度需要额外一步
SIMPLE 和 SECURE 可以在单个文件上直接评估，但 COMPOSABLE 需要跨文件的依赖图。首先安装 GitNexus：
npm install -g gitnexus
然后在项目中生成依赖图：
topos depgraph generate
最后带上依赖图数据做评估：
topos evaluate src/ -r --gitnexus-dir .gitnexus
这一步会分析模块间的 Martin Instability（马丁不稳定性）指标——如果一个工具模块被太多模块依赖，而它本身又依赖了大量其他模块，这种”中心枢纽”式的代码结构就会在 COMPOSABLE 维度暴露问题。
给 Agent 装上 MCP 实时反馈
Topos 最实用的功能是 MCP 服务器——让 Claude Code、Cursor、Gemini CLI 或 Windsurf 在写代码时实时知道自己写得好不好：
claude mcp add --transport stdio topos -- topos mcp
配置好之后，Agent 会在每次生成代码后自动调用 Topos 评估结果。比如 Claude Code 写了一个模块，Topos 回告”BRONZE（SIMPLE 通过，COMPOSABLE 和 SECURE 未通过）”，Agent 就知道下一步该拆解模块耦合了。
对于 Cursor，在 .cursor/mcp.json 中添加：
{
"mcpServers": {
"topos": {
"command": "topos",
"args": ["mcp"]
}
}
}
对于 VS Code + GitHub Copilot，在 .vscode/mcp.json 中同样配置即可。详细指引在 docs.krv.ai/topos/agents。
结构化测试覆盖率检查
除了评估代码质量，Topos 还能检查结构化的测试覆盖率：
topos coverage src/
不同于传统行覆盖率只告诉你”这行代码被执行过”，Topos 的 coverage 检查的是控制流路径覆盖和模块间接口覆盖——测试真正测试了分支逻辑的各个方向，还是只走了 Happy Path？
这在 Agent 生成的代码中尤其重要——Agent 倾向于为”通过测试”而写代码，而不是为”全面覆盖边界情况”而写。Topos coverage 恰好暴露这个差距。
在 CI 中集成
在 CI 工作流中加入质量门禁：
- name: Code quality check
run: |
topos evaluate src/ --json > topos-report.json
topos evaluate src/ --preferences simple,composable,secure
如果设置了 --preferences，Topos 会在 GOLD 或指定组合不可达时返回非零退出码，CI 管道可以直接拦截低质量的 Agent 代码合入。
最佳实践
设全局偏好文件：在项目根目录创建 .toposrc 文件，设置团队统一的评估偏好。这样所有开发者和 Agent 共享同一套质量标准。
不要追求全部 GOLD：SIMPLE、COMPOSABLE、SECURE 三者存在天然的权衡。一个高度安全的模块（大量权限检查）必然降低简洁性，一个极致简洁的工具函数可能缺少安全的异常处理。让 Agent 的 --preferences 反映你项目当前最薄弱的环节。
结合 Code Review 一起用：Topos 不是替代 Review，而是给 Review 提供数据支撑。”这个文件从 SILVER 降到了 BRONZE”比”感觉写得有点乱”有力得多。
结语
Topos 的思想很简单：Agent 生成了代码，但代码是否真的属于这个代码库，需要结构质量的确认，而不是仅靠跑一遍测试。在 Agent 一天生成数千行代码的节奏下，结构化的质量门禁不是附加功能，而是必需品。
BSD-3-Clause 开源许可，pip install topos-mcp 或 curl 一键安装，MCP 即插即用。如果你每天在 Claude Code 或 Cursor 的 PR 里纠结”这个 diff 到底行不行”，Topos 值得一试。
相关链接