AI 2026年7月7日 2 分钟阅读

Topos 实战：用代码结构质量评分系统让 AI Agent 写出可维护的代码

tinyash 0 条评论

背景

AI 编码 Agent（Claude Code、Codex、Cursor）每天都在以惊人的速度写代码。一个代理在几分钟内就能生成跨越十几个文件的 PR，CI 全绿，语法完美——但当你仔细一看，发现它复制了一个本已存在的工具函数、创造了一个匪夷所思的抽象层、或塞进了不该暴露的安全风险路径。

这就是被称为 Agentic Spray 的问题——AI Agent 生成代码的速度远远超过了人类审查代码的能力。单元测试通过了，但代码的结构质量没人知道。更糟糕的是，Agent 自己也不知道。它缺少一个「结构质量仪表盘」来告诉它：”这段代码虽然能跑，但架构很脆弱。”

Topos 就是来解决这个问题的。由 Krv Labs 开源的 Topos（BSD-3-Clause 许可，Python 实现）是一个结构化的代码质量度量工具。它不看你写没写测试，而是从三个独立维度评估代码的「内在质量」：简单性（SIMPLE）、可组合性（COMPOSABLE） 和 安全性（SECURE）。评估结果用一套 Medal 勋章系统呈现：🥇 GOLD（全通过）、🥈 SILVER（通过 2 项）、🥉 BRONZE（通过 1 项）、❌ SLOP（全部失败）。

安装与环境

Topos 的安装非常简单，一条命令即可：

curl -fsSL https://docs.krv.ai/topos/install.sh | sh

安装完成后验证版本：

topos --version
topos --help

依赖说明：Topos 本身是一个独立二进制，不依赖 Python 环境。如果需要评估 COMPOSABLE 维度（可组合性），还需要安装 GitNexus 来生成依赖图：

npm install -g gitnexus

实战场景 1：评估单个文件的质量勋章

最基础的用法是评估一个具体的 Python 文件。假设你让 Claude Code 生成了一个数据处理函数 process_data.py，想快速知道它的结构质量：

topos evaluate path/to/process_data.py

输出示例：

Topos — Structural Code Quality Report
───────────────────────────────────────
File: process_data.py
  SIMPLE     ✅  PASS  (entropy 0.42, cyclomatic 8)
  COMPOSABLE ✅  PASS  (instability 0.15)
  SECURE     ✅  PASS  (0 dangerous paths)

  🥇 GOLD — All three pillars pass

如果某个维度不达标，它会明确告诉你原因：

File: hotfix_router.py
  SIMPLE     ❌  FAIL  (cyclomatic 38 > threshold 20)
  COMPOSABLE ✅  PASS
  SECURE     ❌  FAIL  (1 taint path: eval() on user input)

  🥉 BRONZE — 1 of 3 pillars pass

evaluate 命令的常用选项：

  • --json：输出 JSON 格式，方便 CI 集成
  • --language typescript：指定语言（支持 python、typescript、javascript、rust、cpp）
  • --preferences simple,composable,secure：设置 Agent 优化优先级
  • --allow yaml.load：声明已知风险调用，限制最高不超过 SILVER

对于更详细的检查，使用 inspect：

topos inspect path/to/file.py

这个命令会输出每个度量的原始数值，适合在调试时使用。

实战场景 2：对整个仓库做结构质量审查

单个文件评估只是入门。当你在整个项目上运行 Topos 时，它的真正价值才会显现：

topos evaluate src/ -r

-r（或 --report）标志会让输出变成一个排好序的摘要，告诉你三个关键信息：

  1. 目录整体评分 — 最差的那个文件把整个目录拖到哪个等级
  2. 需要关注的文件 — 评分最低的文件清单
  3. 最容易改进的文件 — 离「及格」（从 FAIL 变为 PASS）差距最小的文件，附带具体修复建议

例如：

Directory Floor Verdict:  ❌ SLOP (dragged down by src/legacy/api.py)

Needs attention:
  src/legacy/api.py    — SLOP (simple 32%, composable 19%, secure 43%)
  src/handlers/v2.go   — BRONZE (secure 51%)

Lowest-hanging fruit:
  1. src/handlers/v2.go — secure 51% → 60% (+9 pts)
     ↳ Sanitize SQL string interpolation (parameterized query missing)

这个功能非常适合在 CI 中集成。Agent 生成 PR 后，CI 自动运行 Topos，如果新代码的 Medal 低于预设阈值，直接标记为「需人工审查」：

topos evaluate src/ -r --json --preferences simple,composable,secure

输出的 JSON 包含所有度量的精确数值，可以接入 GitHub Actions、GitLab CI 或其他自动化流程。

启用 COMPOSABLE 维度

默认情况下，Topos 只能评估 SIMPLE 和 SECURE 两个维度。要启用 COMPOSABLE（可组合性），需要先生成项目的依赖图：

cd /path/to/your/project
npm install -g gitnexus  # 只需安装一次
topos depgraph generate

depgraph generate 会在项目根目录创建 .gitnexus/ 目录。之后评估时必须显式指定依赖图路径：

topos evaluate src/ -r --gitnexus-dir .gitnexus

💡 CLI 模式不会自动检测 .gitnexus/ — 必须用 --gitnexus-dir 显式指定。但 MCP 服务器模式会自动检测。

实战场景 3：集成到 Claude Code 实现自循环改进

Topos 最强大的用法是作为 MCP 服务器 运行，让 AI 编码 Agent 在写代码时实时获取结构质量反馈。

步骤 1：构建依赖图

cd /path/to/your/repo
npm install -g gitnexus
topos depgraph generate

步骤 2：注册到 Claude Code

claude mcp add topos topos mcp

如果需要指定文件根路径（默认自动检测）：

{
  "mcpServers": {
    "topos": {
      "command": "topos mcp",
      "env": { "TOPOS_MCP_FILE_ROOT": "/absolute/path/to/repo" }
    }
  }
}

Cursor、Windsurf 和 Gemini CLI 的配置方式类似，只需在各自的 MCP 配置文件中添加以上 JSON。

步骤 3：触发重构循环

注册完成后，你只需在对话中对 Agent 说：

使用 Topos 评估 src/ 中最差评分的文件，提出重构方案，然后用 topos_assess_improvement 验证改进效果。

Agent 会自动调用 Topos 的 MCP 工具，执行以下循环：

  1. topos_evaluate — 获取当前评分
  2. 根据评分提出重构建议
  3. 用 topos_assess_improvement 验证改进效果——Agent 会调用 Topos 的验证工具对新代码做二次评估

健康输出示例：

{simple: 72%, composable: 65%, secure: 95%}

如果输出中缺少 composable，说明 GitNexus 未正确配置——返回到步骤 1。

Topos 还提供 topos_refactor_until_ideal(filepath) 这个便捷提示，Agent 会持续迭代直到文件达到 GOLD 标准。这在处理关键模块时非常实用——你设定目标，Agent 自动迭代到达标为止。

最佳实践

  1. 从单个文件开始：不要一开始就对整个仓库运行 Topos。先评估 1-2 个关键模块，理解 Medal 系统的工作方式。
  1. 设置合理的优先级：通过 --preferences 告诉 Topos 哪些维度对你更重要。例如一个涉及用户数据的模块应优先满足 SECURE，而核心业务逻辑应优先满足 COMPOSABLE。
  1. CI 中设置最低门槛：将 topos evaluate --json 集成到 GitHub Actions，设定 BRONZE 为最低门槛。新代码达不到 SILVER 就不自动合并。
  1. 重新生成依赖图：每次项目结构变化后（新增模块、重命名、重构），重新运行 topos depgraph generate。依赖图缓存以 .gitnexus/ 的 mtime 为键，旧数据不会自动更新。
  1. MCP 配合 GitNexus：在 Claude Code 等 Agent 中使用 Topos MCP 时，确保先安装 GitNexus 并生成依赖图，否则 COMPOSABLE 维度不可达。

总结

Topos 为 AI 编码 Agent 提供了一个急需的「结构质量仪表盘」。它不替代单元测试，而是在测试之上加了一层架构质量的保障。通过 SIMPLE、COMPOSABLE 和 SECURE 三个独立维度，Topos 让 AI Agent 在写代码时就能知道自己的代码是否真的「可维护」，而非仅仅「可运行」。

对于使用 Claude Code、Cursor、Codex 的团队，将 Topos 集成到 CI 和 Agent 工作流中是提升代码长期质量的最快捷径之一。与其在 PR 审查时对着几百行 diff 焦虑，不如让 Agent 自己先把 SLOP 代码改到 SILVER 以上。

相关链接：

AI AI 工具 AI 编程 开发工具 开源 教程

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。