Topos

面向结构化代码质量的 Agent 执行框架

Topos 衡量复杂度、耦合度、高风险数据流和 Agent 的认知负荷，然后为你的 Agent 提供明确目标——从 SLOP 到 PLATINUM。

安装 · 检查内容 · 实现原理 · 文档 · 问题

---

为什么选择 Topos

编码 Agent 能快速生成可运行的代码。更难的问题是，生成结果是否依然易于理解、安全修改，并且与代码库的其他部分契合。质量就是新的货币。

Topos 根据程序结构计算这一信号，而非依赖大模型评审或风格观点，并返回具体的故障位置和后续操作。它足够快速，可以嵌入 Agent 工作循环：衡量、编辑、验证、重复。

测试检查行为。Topos 检查实现是否经得起持续修改。

以范畴论为基础，用 Rust 编写。

安装和快速开始

一个二进制文件。支持所有 Agent 执行框架。也能轻松卸载。

1. 安装 CLI

使用经过验证的发行版安装程序：

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

或者使用 Homebrew 安装：

brew install krv-labs/tap/topos

在 Homebrew 6 及更高版本中，这条完整限定的一行命令会自动添加 tap，并且只信任此 formula。如果你先运行 brew tap krv-labs/tap，请在 brew install topos 之前运行 brew trust --formula krv-labs/tap/topos。

提示

更喜欢由编辑器管理安装？ 在 VS Code 或 Cursor 中，前往扩展视图搜索 @mcp topos，或选择安装 MCP 服务。这是 topos install 的替代方案：编辑器会为你安装并管理 Topos MCP 服务。

2. 连接编码 Agent

topos install 会检测所有受支持的 MCP 框架，并通过一个交互式清单，让你配置其中任意一个或全部：

topos install

┌  Which agent integrations do you want to configure?
│
│  ↑↓ move · space toggle · a all · enter confirm · esc cancel
│
│ ❯ ○ Claude Code          (detected)
│   ○ Claude Desktop       (detected)
│   ● Codex CLI            (✓ active)
│   ● Gemini CLI           (✓ active)
│   ○ GitHub Copilot CLI   (detected)
│   ○ Cursor               (detected)
│   ○ VS Code              (detected)
│   ○ Google Antigravity   (detected)
│   ○ pi                   (detected)
│   ○ OpenCode             (detected)
└

重启已配置的 Agent，然后提出：

“使用 Topos 找出此代码库最严重的结构性问题，进行一项有针对性的改进，并验证结果。”

重要

太多工具会把 MCP 服务散落到 Agent 的 JSON 文件中，在你的机器上到处创建符号链接，然后让你耗掉半个 Claude 会话来理清这些乱七八糟的东西——或者让你自己抓狂。Topos 不会这么做。我们遵循安装状态不留痕的策略：topos status 会显示所有注册项，而 topos uninstall 会打开同一个选择器，预览具体会发生哪些更改，并移除它添加到框架配置中的所有内容。 共享缓存记录和仓库范围的缓存租约不属于安装状态，因此卸载时不会删除它们，并会报告保留的共享记录；生成的 PR 缓存只能通过明确执行 topos cache clean 或 topos cache prune 来删除。如果 Topos 让操作变得简单，那么撤销操作也应该同样简单。

topos status
topos uninstall

有关权限、手动配置和故障排除，请参阅 Agent 设置指南。

3. 在终端中评估

topos evaluate . -r

Topos 会自动检测 Python、Rust、JavaScript、TypeScript、C++ 和 Go。只有在想缩小运行范围时，才传入 --language。

要审查拉取请求？topos pr-recap 5 会为 PR 中已更改的文件生成结构性前后对比卡片和债务清单——不使用大模型，结果完全可复现，预设基于 1,609 个开源拉取请求进行校准（PR Recap 校准 · 实验室笔记）。

平台支持和其他安装方式，请参阅安装。

Topos 检查什么

每个文件都会获得四项独立判定：

• SIMPLE — 使用 AST 熵和控制流复杂度，避免不必要的复杂性。
• COMPOSABLE — 限制文件对外部依赖的负担；更广泛的耦合度和稳定性指标仍可用于诊断。
• SECURE — 避免代码属性图中的危险 API 可达路径和污点路径。
• NAVIGABLE — 使用基于深度加权的 AST 作用域树嵌套偏差，确保文件足够浅，让 Agent 能一遍读懂并完成修改。

这些判定会汇总为一个容易记住的质量奖牌，同时保留未通过的具体支柱：

奖牌	标准
🏆 PLATINUM	4 项全部通过
🥇 GOLD	4 项中通过 3 项
🥈 SILVER	4 项中通过 2 项
🥉 BRONZE	4 项中通过 1 项
❌ SLOP	0 项通过，或解析失败

参阅完整指标参考。重构指南还会指出控制流循环、关键依赖边和流程瓶颈。

奖牌系统的推导方式

这四个支柱两两不可比较，构成一个含十六个元素的评估格（4 维超立方体）；PLATINUM 是它们的交集。下方标签分别以 Simple（简单）、Composable（可组合）、Sc = Secure（安全）、Navigable（易导航）表示各支柱。

度量 · 范畴论基础

实现原理

Topos 是独立运行的 Rust CLI 和 MCP 服务。分析在本地运行；你的源代码不会发送到外部模型或托管分析服务。

组件	作用
tree-sitter	解析六种语言，并为原生 AST、CFG、CPG、PDG 和 UAST 表示提供支持。
GitNexus	提供由 COMPOSABLE 评分的仓库依赖图（topos depgraph generate）。需要 npm install -g [email protected]。
Sighthound	嵌入 MCP 服务，用于补充安全问题发现；原生 CPG 探测仍是 SECURE 评分的依据。

最终为 Agent 提供一套统一接口，整合多个结构视角：一个可优化的分数、每项失败的明确证据，以及一个能区分真正改进与表面变更的验证循环。

使用 Topos 的其他方式

• OpenClaw / ClawHub： openclaw skills install @Krv-Labs/topos
• Hermes： 先运行 hermes skills tap add Krv-Labs/topos，再运行 hermes skills install Krv-Labs/topos/topos
• Agent 插件： 将兼容客户端指向 agent-plugin/（规范）
• MCP 注册表名称： io.github.Krv-Labs/topos
• CLI 参考： docs.krv.ai/topos/cli

分发

Topos 通过四种方式发布：

• GitHub Releases — topos CLI 二进制文件（macOS/Linux），可通过 install.sh 安装或直接下载发布版本。
• PyPI — topos-mcp，一个捆绑 MCP 服务二进制文件的轻量型 bin wheel（pip install topos-mcp / uvx topos-mcp），无需 Python 运行时。
• VS Code Marketplace — Topos 扩展，捆绑各平台的二进制文件。
• Docker — 用于 Glama 和其他 MCP 注册表托管的容器镜像。

crate 布局和适配器详情：docs.krv.ai/topos/architecture。

贡献

Krv Labs 内部使用 Topos 管理 AI Agent 生成的代码输出。欢迎提交 Bug、想法和贡献。

• 发现 Bug？ 提交 issue
• 有想法？ 发起 discussion 或提交 PR
• 想要合作？ [email protected]

---

完整文档 · 度量与指标 · 工程笔记