Topos 实战教程：用代码质量度量让 AI Agent 写出可维护的代码
AI 编码 Agent（Claude Code、Cursor、Codex 等）写代码的速度越来越快，但一个尴尬的问题也随之浮现：代码能跑，但能维护吗？
单元测试通过只证明代码”工作”，不证明它”健康”。当 AI 生成的代码进入生产环境，技术债务的累积速度往往超出预期。Krv Labs 开源的 Topos（BSD-3-Clause，Python）正是为解决这个问题而生——它是一个面向 AI Agent 的结构化代码质量度量工具，给 Agent 一个可以优化和迭代的具体目标。
快速安装
Topos 的安装非常简单，一条命令即可：
curl -fsSL https://docs.krv.ai/topos/install.sh | sh topos --version # 验证安装成功 topos --help # 查看完整命令列表
安装完成后，topos 就在你的 PATH 中了。
60 秒快速上手
Topos 的使用非常直观，核心就是 evaluate 命令：
topos evaluate path/to/file.py topos evaluate src/ -r topos evaluate src/ -r --json topos inspect path/to/file.py topos compare before.py after.py
运行 evaluate 后，Topos 会为每个文件颁发一个”代码质量奖牌”——稍后会详细介绍。
三大质量支柱
Topos 从三个独立维度衡量代码质量，每个维度称为一个”支柱”（Pillar）：
| 支柱 | 含义 | 测量方法 |
|---|---|---|
| SIMPLE | 避免不必要的复杂度 | AST 熵 + CFG 圈复杂度 |
| COMPOSABLE | 模块间低耦合 | 模块依赖图（Martin Instability） |
| SECURE | 无危险 API 可达和污点路径 | 代码属性图（CPG）分析 |
这三个支柱相互独立、不可比较。一个文件可以独立达成任意子集。
奖牌系统
Topos 根据三个支柱的通过情况颁发四种奖牌：
🥇 GOLD — 三项全部通过（SIMPLE + COMPOSABLE + SECURE） 🥈 SILVER — 通过两项 🥉 BRONZE — 通过一项 ❌ SLOP — 全部未通过（或解析失败）
你可以通过 --preferences 参数设置优先级，告诉 AI Agent 在有限的 Token 和时间内优先优化哪些维度：
topos evaluate src/ -r --preferences simple,composable,secure
MCP Server 集成：让 AI Agent 自动优化代码
Topos 最有价值的功能是内置的 MCP Server。任何支持 MCP 协议的 AI 编码 Agent（Claude Code、Cursor、Gemini CLI、Windsurf）都可以接入 Topos，在编码过程中实时获取质量反馈并自动迭代。
第一步：构建依赖图（可选但推荐）
npm install -g gitnexus cd /path/to/your/repo topos depgraph generate # 生成 .gitnexus/ 目录
没有依赖图时，COMPOSABLE 支柱不可达，但这不影响 SIMPLE 和 SECURE。
第二步：注册 MCP Server
Claude Code：
claude mcp add topos topos mcp
Cursor： 在 .cursor/mcp.json 中添加：
{ "mcpServers": { "topos": { "command": "topos mcp" } } }
其他工具（Gemini CLI、Windsurf 等）： 同样的 JSON 配置。
第三步：让 Agent 使用 Topos
启动后，你可以直接告诉 Agent：
“Use topos to find the worst-scoring file in
src/, propose a refactor, and verify withtopos_assess_improvement.”
Agent 会自动调用 Topos 的 MCP 工具，评估代码质量，提出重构方案，然后验证改进效果。整个过程不离开编辑器会话。
代码覆盖率测量
Topos 提供一种独特的双重覆盖率测量，区分声明覆盖（结构层面）和 ECT 覆盖（语义层面）：
topos coverage --tests tests/test_foo.py topos/foo.py topos coverage --tests tests/test_foo.py topos/foo.py --coverage-threshold 0.8 --json
这比传统的行覆盖率更精确——它能判断测试是否覆盖了代码的”形状”和”模式”，而不仅仅是逐行执行。
实战场景：用 Topos 重构 AI 生成的代码
假设你刚用 Claude Code 生成了一个 Python 模块 src/data_processor.py，代码能跑但感觉有点”乱”。以下是完整的 Topos 工作流：
topos evaluate src/data_processor.py topos inspect src/data_processor.py topos evaluate src/data_processor.py
总结
Topos 解决了一个很现实的问题：AI 生成的代码”能用但不健康”。通过三大质量支柱 + 奖牌系统 + MCP 集成，它让 AI Agent 有了明确的优化目标，不再盲目生成代码。9 个 GitHub Stars 虽然不多，但 BSD-3-Clause 的开源许可和清晰的架构设计，使其值得在生产流程中一试。
如果你也在用 AI 编码 Agent 写生产代码，Topos 可以作为 CI 流水线的一个质检关卡——在合并之前，确保新代码不只是”通过测试”，更是”值得维护”。