Maguyva 博客

会随行的上下文

Mon, 07 Sep 2026 00:00:00 GMT

Cursor 的索引器在 Cursor 里非常出色。Tab 补全、行内编辑、聊天，以及那个窗口里的智能体，都已经建立在 Cursor 为打开的工作区维护的项目索引之上。如果 Cursor 是你唯一写代码的界面，而那个索引已经能找到正确的文件，那就留在那里。这是诚实的“原地不动”情形，也理应是本文的第一句话。

这篇文章讲的是普通一周中的另一半。同一个仓库也会在 Claude Code 中打开，被 Codex CLI 询问，在第二台机器上被审查，或者被运行在 CI 中的智能体查询。问题不是“哪个索引器更好”。问题是，智能体在一个窗口里信任的地图，和它在下一个窗口里信任的地图，是不是同一张。

Maguyva 就是那张会随行的地图。它是一个远程 MCP 代码库上下文层。智能体查询它的方式，和查询其他任何 MCP 工具一样。结果以带行号的排序路径返回。Cursor 仍然是编辑器。移动的是上下文。

Cursor 的索引器是干什么用的

Cursor 内置的索引存在的目的，是让编辑器内的聊天、智能体和搜索能够检索相关代码，而不只是依赖模型原始上下文窗口所能容纳的内容。这对 IDE 来说是正确的设计。这个索引是 Cursor 原生的。它不是 MCP 服务器，也无法被任何其他客户端访问。

它的工作方式，按照撰写本文时 Cursor 公开文档和 Cursor 自身说法的描述是这样的：主要的搜索路径不再是云端 embedding 索引。Cursor 团队在其社区论坛上表示，专门的语义/基于 embedding 的搜索正在逐步淘汰，转而支持基于 grep 的检索，因为当前的模型自己就能足够好地探索一棵活跃的代码树。取而代之的是 Instant Grep，一个由 n-gram、倒排列表和布隆过滤器构建的本地搜索索引，保存在一张内存映射的查找表中，因此查询是在开发者自己的机器上解析的，而不是在服务器上。

索引本身存放在仓库自己的 .git/cursor/ 目录中，锚定在某个具体的 git 提交上；自那次提交以来的编辑会叠加在其之上，而不是触发重新扫描，只有当本地状态与索引构建时的状态严重偏离时，索引才会重建。因为它位于 .git 内部，它从不被跟踪，也从不被推送——删除该文件夹，索引就消失了。.gitignore 因构造而自动得到遵守，因为只有被 git 跟踪的内容才符合条件，.cursorignore 则在读取路径上被强制执行。这条路径上已经没有服务器端的 embedding 步骤，也没有远程向量数据库。早先的文档描述了一种云辅助设计——分块加密、Merkle 树同步、团队成员间的索引复用——而 Cursor 自己的团队后来表示这种设计正在被淘汰，所以本文不再把它描述为当前状态。

编辑器内一个突出的亮点是 Cursor 的 Explore 子智能体。它可以在自己的上下文窗口中，用一个更快的模型发起多路并行搜索，只返回相关的发现，这样主对话就不会被搜索结果撑大。这是编辑器内部一项真正的优势。保留它。

多根工作区也受支持：每个打开的文件夹的上下文都对 Agent 可用。一些依赖 git 的功能，比如 worktree，在多根设置中会被禁用，而 Cloud Agents 完全不支持多根工作区。

这些都不是离开 Cursor 的理由。这只是对一张地图的准确描述——它在自己所处的地方非常出色。

“随行”到底意味着什么

当同样的问题在不止一个客户端上返回同样类型的答案，并带有你可以打开查看的引用时，一张地图就算是会随行的。

在 Cursor 中：“parseConfig 定义在哪里，谁调用了它？”
在 Claude Code 中，同一个仓库：同样的问题。
在 Codex CLI 中，一台从未打开过 Cursor 窗口的审查机器上：同样的问题。
在一个会说 MCP 的 CI 智能体中：同样的问题，针对同一个托管的快照。

如果每个界面都构建自己的私有索引，你拥有的就不是一张地图，而是几份彼此漂移的缓存。编辑器索引可能对磁盘上的代码树是最新的。CLI 会话可能落后一天。CI 任务可能看的是另一份检出的代码。而智能体听起来照样自信满满。

Cursor 的索引器本来就不该解决这个问题。因为它活在编辑器内部，它构建的上下文就是为那个编辑器服务的。同时还需要 CLI、CI 流水线或另一个编辑器的读者，需要一个针对这些界面的独立工具。这是一个范围事实，不是缺陷。Maguyva 就是那个独立的工具。

Cursor 索引器公开的语言数量，在本文可以使用的资料中没有说明。Maguyva 公开支持 279 种以上的语言和基于文本的技术。Cursor 的定价这里也没有照搬；请参考他们的定价页面。Maguyva 按工作区计费，而不是按席位，公开的方案为 $0、$19、$49 和 $149，取决于已索引的规模和工作区大小。

一张托管地图，每个 MCP 客户端

Maguyva 是一个远程 MCP 服务器。你连接 GitHub，选择仓库，云端流水线会构建符号、图边和一张排序后的地图。你把一个 API 密钥添加到你已经在用的客户端的 MCP 配置中。Maguyva 为 24 个有文档记录的 MCP 客户端（包括 Cursor）提供设置指南，也可以连接到其他支持标准配置的 MCP 兼容客户端。

如果你在 Cursor 中工作，Cursor 设置页面是特定于该编辑器的路径。同一个服务器也服务于 Claude Code、VS Code、Windsurf、Codex CLI 等。你不需要更换编辑器。你为每个智能体提供同样的工具界面：11 个面向客户的 MCP 工具，涵盖搜索、符号、依赖分析、文件检索、仓库上下文和确定性实用工作流。语义、结构、图和文本检索被融合成排序结果。

这就是可移植性带来的好处。你今天早上在 Cursor 中核实过的引用，和 Codex CLI 今晚返回的引用形式相同。文件路径和行号。打开它们。如果错了，你会看到。如果对了，下一次编辑就有地方落脚。被认可的说法是更少的幻觉编辑，而不是承诺每一次编辑都正确。

新鲜度是公开的。快照带有时间戳，因此智能体知道自己读到的是哪个版本的代码树。重建节奏是：免费方案每天一次，付费方案每小时一次。诚实的限制是未同步的本地工作：只存在于工作树中的编辑，还没有进入托管地图。无论你从哪个客户端查询，这个限制都是一样的，而这正是重点所在。客户端之间的漂移不再是第二个隐藏的限制。

文档给出了适用于每个客户端的激活循环：索引一个你已经了解的仓库，连接客户端，问一个你能核实的问题。先在 Cursor 中做一次。再从你在审查那天真正会用的 CLI 中做一次。如果两次回答引用的是同一个处理函数，说明地图确实随行了。

两张地图如何并存

两个都用。它们不是比较页那种意义上的替代关系。

让 Cursor 的索引器继续为磁盘上的项目工作。让 Explore、Instant Grep 和编辑器内的智能体使用它。这个循环是原生且快速的。
在 Cursor 中把 Maguyva 添加为 MCP 服务器，让同一个会话也能查询托管的工作区地图。Cursor 是一个有文档记录的 Maguyva 客户端。你不是在两个索引之间二选一、删掉另一个。
把同一个 Maguyva 服务器添加到 Claude Code、Codex CLI，或任何接触该仓库的其他 MCP 客户端。一种 API 密钥形式。一个工作区。
如果某个 CI 智能体兼容 MCP，把它指向同一个服务器。它会读到和笔记本电脑一样的、带时间戳的快照。

编辑器索引仍然是回答“此刻这个窗口里磁盘上有什么”的最佳工具。托管地图则是回答“今天要接触这个工作区的每一个智能体眼中它是什么样子”的最佳工具。这两句话并不冲突。

工作区配额发布在定价页面上：仓库数、已索引行数和用户数，按工作区计费。智能体和人类共享同一个用户数。先用一个你能自己评判的仓库免费开始。等引用经受住了与代码树接触的考验之后，再提升工作区规模。

本文不主张的事

本文不主张 Cursor 的索引器薄弱、不完整，或是更换编辑器的理由。本文的第一句话恰恰相反。

本文不主张 Maguyva 取代了 Instant Grep 或 Explore 子智能体。那些是 Cursor 的功能。它们留在 Cursor 里。

本文不为任何一个产品编造语言数量、延迟数字或 token 节省数字。未知的数字保持未公开。

本文不假装未推送的本地工作已经在托管地图里。带时间戳的快照让这个限制变得可见，而不是消除它。

测试很普通。索引一个你已经了解的仓库。问一个你能核实的问题，先在 Cursor 中，再在第二个 MCP 客户端中。会随行的上下文，就是两处得到同一条引用。

// same map, wherever you opened it.

先地图，后审查

Mon, 07 Sep 2026 00:00:00 GMT

在一个拉取请求的两端，坐着两项不同的工作。在智能体动笔之前，它需要一张即将修改的代码树的地图。在智能体打开 PR 之后，应该有什么东西对照系统的其余部分来读这个变更，并留下人类可以据以行动的评论。

这两项工作从远处看很相似，因为二者都涉及“理解代码库”。但它们不是同一个产品。一个回答的是“这个改动应该落在哪里？”。另一个回答的是“这个 diff 破坏了什么，而逐行检查的代码检查工具会漏掉？”。把它们混为一谈，只会产出更差的初稿和更嘈杂的审查。

这篇文章是一份联合工作流指南。Maguyva 是智能体首先查询的地图。Greptile 是随后为 PR 添加评论的审查智能体。这个搭档从构造上就是互补的：Maguyva 不审查拉取请求，Greptile 也不会取代智能体用来撰写这些改动的上下文层。

为什么这种分工有用

一个从训练先验加上几个粘贴文件出发的编码智能体，会编造一条看似合理的路径并编辑它。这就是错误文件的失败模式，是一个检索问题。Maguyva 是一个远程 MCP 代码库上下文层：语义、结构（AST）、图/依赖和文本检索融合成排序结果，再加上符号查找和文件获取。有依据的答案以 path/file.ext:line 的形式返回，让你能在补丁存在之前就拒绝一个错误的结果。这个主张保持谦逊：更少的幻觉编辑。模型仍然可能猜测。只是第一步不再是猜测。

Greptile 是一个 AI 代码审查智能体。用他们自己的话说，它以对代码库的完整理解自动审查每一个拉取请求，并将这与孤立检查文件、而非整个系统的传统代码检查工具相对照。它的设置就是安装 GitHub 或 GitLab 应用并选择仓库。没有需要你运维的本地索引。托管方式是 Greptile Cloud（他们声明符合 SOC 2 Type II，并可应要求提供报告），也为企业提供自托管选项。

他们自己的编号流程是：连接并为每个函数、类和依赖构建依赖关系图；在每个拉取请求上，使用那张完整仓库图分析变更，并在大约三分钟内以带修复建议的 PR 评论形式发布结果；每条评论都可以把问题移交给团队已经在用的编码智能体。他们还声明会长期阅读之前人类留下的 PR 评论，以学习团队的编码标准并减少嘈杂的建议。据他们所说，这套学习系统需要 2 到 3 周来适应。

这是审查，不是起草。Greptile 的突出之处在于，针对已经落地到 PR 中的变更提供完整仓库图上下文，随后是一个闭环，把发现结果发给 Claude Code、Codex、Conductor、Cursor 或 Devin。Maguyva 的突出之处在于智能体在那次变更被写下之前查询的排序地图。两者都用。不要要求任何一方去做另一方的工作。

Maguyva 与 Greptile 之间没有声明存在官方一方产品集成。你也不需要。Maguyva 通过 MCP 与智能体对话。Greptile 通过自己的应用与 GitHub 或 GitLab 对话。它们在拉取请求处相遇。没有胶水脚本，没有把一个工具接到另一个工具的定时任务。这个搭档不需要 bash，因为每个产品都已经站在自己应有的位置上。

这不是什么

这不是对 Greptile 的拆解。这不是一篇“换个审查工具”的文章。Greptile 于 2024 年 3 月 5 日作为 Y Combinator W24 公司在 Hacker News 上发布，那个帖子是很多人第一次了解这款产品的方式。如果你也是这样发现他们的，那就继续用。这个页面补上的是那个循环中缺失的前半段：先让智能体扎根，使 Greptile 看到的那个 PR 一开始就瞄准了正确的文件。

Greptile 的营销材料主打审查速度和捕获 bug 的说法。请把这些当作 Greptile 自己的说法，而不是独立核实过的数字。本文不会把它们当作事实重复。

语言覆盖也是同样的诚实问题。Greptile 把支持范围表述为覆盖所有编程语言，而不是一份枚举清单；没有给出精确的数字。Maguyva 公开支持 279 种以上的语言和基于文本的技术，并在涉及技术问题时，在网站上给出技术上的细分（有解析器支持的 AST 与纯文本）。这是两个不同的产品，做出不同的声明。不要把它们混为一谈。

Greptile 的定价没有出现在本文可以使用的资料中。付费方案是存在的；请参考他们的定价页面。Maguyva 按工作区计费，而不是按席位。方案从免费开始。如果你需要工作区数字，定价页面上列出了公开的档位。

工作流

三个有名字的阶段。按这个顺序执行。第一次尝试这个搭档时，一个都不要跳过。

1. Maguyva 上下文

索引一个你已经了解的仓库。连接你已经在用来写代码的 MCP 客户端——Claude Code、Cursor、Codex CLI、VS Code、Windsurf，或者其他 MCP 兼容客户端。Maguyva 为 24 个有文档记录的 MCP 客户端提供设置指南，也能连接到支持标准 MCP 配置的其他客户端。

在任何人写下一行代码之前，先问一个你能评判的问题。“会话过期在哪里处理，什么在调用它？”比“修一下认证”是更好的第一步。要求引用。打开 file.ext:line 结果。跟着符号走。确认你即将触碰的依赖关系。

Maguyva 提供 11 个面向客户的 MCP 工具，涵盖搜索、符号、依赖分析、文件检索、仓库上下文和确定性实用工作流。四种检索模式融合成排序结果；当你已经知道名字时，find_symbol 是一个独立的工具。文档描述了最短路径：先免费开始，索引一个你已经了解的仓库，连接客户端，然后问一个你能核实的问题。

快照带有时间戳，因此智能体能判断自己读到的是哪个版本的代码树。诚实的限制是未同步的本地工作。如果编辑只存在于工作树中，还没有被推送，托管地图就还不包含它。指令文件（CLAUDE.md、AGENTS.md）在这里依然有它们的位置，用来记录约定和不该触碰的东西。它们不是一张活的地图。用它们来规范行为。用 Maguyva 来核实事实。

在引用经受住与仓库接触的考验之前，不要让智能体打开 PR。这道关卡就是这个阶段的全部意义所在。

2. 智能体 PR

同一个智能体现在会在你已经付费使用的客户端里写下这个改动。Maguyva 既不是编辑器，也不是审查者。智能体仍然负责生成 diff。你仍然像以前一样，在 GitHub 或 GitLab 上打开拉取请求。

应该不同的是第一个文件。这个 PR 应该点明实际实现该行为的处理函数、将会被破坏的调用方，以及在改动出错时会失败的测试。如果第一阶段被跳过了，第三阶段就会把评论花在一个落在错误包里的改动上。Greptile 依然能发现系统性的问题。但它不应该还要从一条幻觉出来的路径中恢复过来。

把 PR 的范围控制好。一个有依据的第一个文件，不是重写整个模块的许可证。这个互补的搭档之所以有效，是因为智能体先带着地图完成了一项工作，然后请审查者在一个有边界的 diff 上完成另一项工作。

3. Greptile 审查

Greptile 已经通过 GitHub 或 GitLab 应用连接到仓库。在新的拉取请求上，它使用自己构建的完整仓库图分析改动，并以带修复建议的评论形式发布结果。他们自己的材料把这个过程的时长定在大约三分钟。

像读一位仔细的队友那样读这些评论：打开被引用的位置，判断这个发现是否真实，然后再行动。当 Greptile 提供“Fix with your Agent”时，它会把问题——文件路径、行号、建议代码——发送给 Claude Code、Codex、Conductor、Cursor 或 Devin。“Fix All”会一次性发送审查中的所有问题。他们还为这次移交提供了 Greptile MCP 和一个 Claude Code 插件。Maguyva 不在那份具名的目标列表上；这种缺席不是问题。Maguyva 已经在第一阶段完成了自己的工作。写下这个 PR 的编码智能体，才是应该接收修复负载的那一方。

在最初的 2 到 3 周里，预期会有一些噪音，因为 Greptile 的学习系统正在适应你团队实际留下的评论。这是他们声明的时间表，不是这个搭档的缺陷。人类审查依然在这个循环里。Greptile 是自动化的第一道关卡，不是合并按钮。

如果一条 Greptile 评论指向了智能体在第一阶段从未查询过的文件，这是一个有用的信号。要么是地图漏掉了一个调用方，要么是智能体跳过了一次引用。针对这条评论修正草稿。不要关掉审查者。

如何保持这种互补关系的诚实

Maguyva 永远在先。对一个错误文件的 PR 进行审查，依然是在审查错误的文件。
Greptile 永远在后。一份引用充分的草稿，依然需要一次系统层面的 diff 通读。
不要要求 Maguyva 发布 PR 评论。它不会这么做。
不要要求 Greptile 在智能体还在选择路径时，充当它的第一层检索工具。这不是他们的 GitHub 或 GitLab 应用被设计来做的事。
不要编造一个“同步”两者的 bash 流水线。PR 就是接口。
独立地验证两端。索引一个你已经了解的仓库。问一个你能核实的问题。然后打开一个小的 PR，看看 Greptile 实际上评论了什么。

一旦被命名，这个循环就很普通了。先地图。再智能体 PR。再审查。每个产品都留在自己擅长的那一侧拉取请求上。

// map first. review second. in that order.

在没有本地索引器的情况下，给 AI 智能体大型仓库的上下文

Fri, 14 Aug 2026 00:00:00 GMT

一个大型仓库放不进上下文窗口，而如果你曾经把笔记本电脑上的索引器指向一个真正的 monorepo，你就知道它在那里也放不舒服——内存飙升，第一次索引要花一个小时，而你的智能体在下一个会话开始时，依然在猜哪些文件重要。

通常的答案是在编辑器旁边运行一个索引器，对于能舒服放进一台机器的仓库来说，这是个不错的答案。如果你的 monorepo 在 Cursor 中已经索引得很快，而那也是你唯一需要这张地图的地方，那么这篇文章没有什么可以补充的——跳过它就好。

这篇文章讲的是另一种情况——当一个智能体需要一张大型仓库的可查询地图，而你又不想为此运行本地索引器时。

什么时候本地索引器是错误的工具

本地索引假定代码存在于查询它的那台机器上，而在真正的 monorepo 规模下，即便在单个编辑器内部，这个假设也会变得吃紧。这个仓库单纯就是大到你不想一直在笔记本电脑上保持热索引：你在一个包里工作，而影响范围却在三个目录之外，一次针对两百万行代码树的冷启动首次索引，不是你想经历两次的事——无论是在你自己的机器上，还是在一个从未克隆过这棵代码树的 CI 运行器上。或者，某个同事应该能查询你在用的同一张地图，而不必等自己的机器吃力地跑完同一个索引。

这些都不是丢弃一个好的编辑器索引器的理由。这是一个理由，说明你还应该拥有一张任何智能体都能通过 MCP 查询的托管地图。

而规模问题比“文件太多没法粘贴”要深得多。在一棵大代码树上，有意思的问题几乎从来不是“给我看这个文件”——而是哪个文件、哪个符号、哪些调用方、哪些测试。一个从列出 src/ 并读取前三个结果开始的智能体，会心安理得地漏掉 apps/api 里的处理函数和 packages/sdk 里生成的客户端。你需要的是从整棵代码树构建、然后排序、然后带引用的检索。

“大型仓库的上下文”到底意味着什么

把文件一股脑塞进提示词不是上下文——那只是代码树更小、更差的一份拷贝。你的智能体真正需要的是提出问题，并得到带引用的答案：这个符号定义在哪里、谁在调用它，我即将修改的模块有什么依赖它，哪个测试文件覆盖了这个行为，以及代码树现在是什么样子，而不是上个季度的样子。

这些答案必须来自一个基于你的仓库构建的索引，而不是模型对别人仓库的记忆，而且这个索引必须存在于智能体上下文窗口之外的某个地方。对这个问题来说，它也应该存在于你笔记本电脑之外的某个地方。

还有一件事，指令文件替你做不到：CLAUDE.md 和 AGENTS.md 是放置约定和行为规范的正确地方，但它们不是一张两百万行代码树的、活的、经过排序的、可查询的地图。行为用规则，事实用仓库智能。

在云端构建地图，从任何客户端查询它

Maguyva 是一个远程 MCP 代码库上下文层。你连接 GitHub，选择你的仓库，然后就可以放手，让云端流水线解析代码树、构建符号和图边、维护一张排序后的地图——永远不需要本地索引器。

当你推送代码时，变更的文件会被增量解析，图和排序层会按计划重建：免费方案每天一次，付费方案每小时一次。每份快照都带有时间戳，让你的智能体能分辨自己读到的是哪个版本的代码树。这里诚实的限制是未同步的本地工作——只存在于你工作树中、从未推送过的编辑，还不在托管地图里。

然后，你把 API 密钥添加到你已经在用的客户端的 MCP 配置中，完成接入。这里有 24 个有文档记录的 MCP 客户端的设置指南，任何支持标准配置的其他 MCP 兼容客户端也都能连接。如果 Cursor 是你的主场，Cursor 页面会带你走完那条路；同一个服务器也服务于 Claude Code、VS Code、Windsurf、Codex CLI 等等。

你不需要更换编辑器。你给智能体的是一整套工具界面——11 个 MCP 工具，涵盖搜索、符号、依赖分析、文件检索和仓库上下文——覆盖 279 种以上的语言和基于文本的技术，这在一个早已不再是单一语言的 monorepo 上，比你想象的更重要。

答案带着依据返回，以带行号的文件路径形式呈现。语义、结构、图和文本检索被融合成排序结果，所以像“什么依赖 parseConfig”这样的问题，得到的既不是一堆 grep 转储，也不是单一的语义片段，而是真正重要的那一小撮位置。

一份具体的操作指南

不要一上来就索引整个公司。以下是行之有效的路径：

选一个你已经很熟悉的仓库——一个你能手动评判的包，胜过你手头最大的代码树。
免费开始：3 个仓库，5 万行索引额度，全部 11 个工具，没有月度查询配额。如果你的代表性仓库比这更大，定价页面按已索引规模——而不是按席位数——列出了工作区档位（$0、$19、$49、$149）。
连接 GitHub，等待首次索引完成。你没有在本地编译任何东西。
接入 MCP 客户端——几行配置。Maguyva 是一个远程 MCP 服务器，所以没有插件、没有扩展，也不需要采用第二个编辑器。
问一个你能核实的问题。“什么依赖 parseConfig?”或者“登录会话过期在哪里处理？”然后打开被引用的 file.ext:line 结果，对照眼前的代码树核对。
只有在引用经受住那次核对之后，才让智能体去编辑。

如果第一个仓库合适，而你的代码树很大，就按你的已索引行数和重建节奏提升工作区规模。人类和智能体共享同一个用户数——Maguyva 按工作区计费，而不是按席位——所以往这个循环里再加一个智能体不会多花你一分钱。

激活测试和文档为任何首次运行推荐的一样：索引一个你已经了解的仓库，问一个你能核实的问题。大型仓库不会改变这个测试，只会让第一个选错的文件代价更高。

接入之后要留意什么

留意三件事。新鲜度：付费方案每小时重建，免费方案每天重建，未推送的本地工作不会出现在地图里——这是你接受的权衡。范围：索引一组有代表性的仓库，而不是每一个被归档的分叉仓库；免费档位是刻意设计成这个规模，让你先弄清楚这些答案值不值得留下。以及验证：一张无法引用路径和行号的大型仓库地图，只是一台更慢的猜测机器，所以在智能体交付补丁之前，让它先展示位置。

然后运行你在小仓库上会运行的同一个测试。索引一个你已经了解的仓库。问一个你能核实的问题。如果这张地图是真实的，你的智能体就不会再从一棵冷代码树开始。

// no laptop got hot building this map.

为什么你的 AI 编码智能体会产生文件路径幻觉

Fri, 14 Aug 2026 00:00:00 GMT

破绽不是一个写错的函数体。而是一次自信满满的编辑，针对一个不存在的文件，或者一个存在但并非实现该行为的文件。

你要求修复会话过期问题。智能体打开了 src/auth/session.ts。这条路径看起来合理。但它也是错的。真正的处理函数在 apps/api/src/middleware/expiry.ts 里，两次重构之前被重命名过。智能体没有对你撒谎。它是用训练先验加上上下文窗口里已经有的内容，补全了一个路径形状的字符串。

这是真实仓库中常见的失败模式。模型会写代码。失误在于选错了写代码的地方。

为什么智能体会编造路径

编码智能体是一个带工具的下一个 token 预测模型。当你说“修一下会话过期”时，它必须先指定一个文件，才能读取或修补任何东西。如果它还没有一张有依据的地图，它就会从以下来源构造一条路径：

它在其他仓库里见过的命名约定。src/auth/session.ts 是一种常见形态。
已经出现在对话里的文件，那可能是你上周粘贴过的文件，而不是现在真正重要的文件。
它碰巧运行过的目录列表，在大型代码树上是不完整的。
指令文件。CLAUDE.md 和 AGENTS.md 告诉智能体该如何表现。它们不是符号、调用方或当前路径的活索引。

这些来源没有一个是今天这个仓库的地图。模型填补空白的方式，和它填补任何空白的方式一样：用一个高概率的延续。这个延续常常看起来像一条真实的路径。有时那个文件确实存在，而且就在正确文件旁边。有时它曾经存在于上个月已合并的一个分支上。有时它从来就不存在。

如果智能体从未搜索过正确的字符串，grep 在这里救不了你。智能体猜了一条路径，然后读了那条路径返回的内容，然后编辑了它。第一个错误的步骤是路径，不是补丁。

读文件也不等于找到正确的文件。Claude Code、Cursor、Codex 以及类似的工具，可以打开你指向的任何东西。问题在于，它们能否在编辑之前，可靠地找到正确的文件、重要的符号、依赖关系、测试，以及影响范围。没有地图的文件访问，依然是从猜测开始的。

错误文件的编辑是一个检索问题

把编造出来的路径当作一次检索失败来处理，而不是当作性格缺陷。

如果智能体在被允许编辑之前必须返回 path/file.ext:line，会发生两件事。第一，你可以打开这条引用，在十秒内拒绝这次工作。第二，智能体必须去查询某个真正了解这棵代码树的东西。

这就是代码库上下文层的工作。仅靠语义搜索是不够的。一个“听起来像会话过期”的片段，依然可能落在一个已废弃的包里。当你知道字符串时，你还需要精确文本；当你知道名字时，你需要符号查找；当你知道形状时，你需要结构化搜索；当你需要调用方和影响范围时，你需要依赖关系图。

Maguyva 就是为兼容 MCP 的编码智能体提供的这一层。它不是编辑器。Claude Code、Cursor、Codex CLI、VS Code、Windsurf 以及其他 MCP 客户端，都留在它们原本的位置。智能体在触碰任何一行代码之前，先查询一张排序过的地图。

这个主张刻意保持谦逊：更少的幻觉编辑。Maguyva 并不会剥夺模型猜测的能力。它改变的是默认的第一步，从“编造一条看似合理的路径”变成“请求排序过、带引用的位置”。

一份有依据的答案是什么样子

对“会话过期在哪里处理”这个问题，一个有用的答案不是一段话。而是一份简短的位置清单：

apps/api/src/middleware/expiry.ts:48 - 处理函数
apps/web/src/lib/auth-client.ts:112 - 调用方
apps/api/tests/expiry.test.ts:20 - 如果这次改动出错就会失败的测试

你可以打开这些行。如果错了，你就停下。如果对了，智能体就可以编辑。重点在于验证，而不是一句口号。

Maguyva 提供 11 个面向客户的 MCP 工具，涵盖搜索、符号、依赖分析、文件检索、仓库上下文和确定性实用工作流。四种检索模式（语义、结构、图/依赖和文本）融合成排序结果；符号查找是一个独立的 MCP 工具（find_symbol）。有依据的答案会带着文件路径和行号返回，方便你对照眼前的代码树来评判。

文档描述了最短路径：先免费开始，索引一个你已经了解的仓库，连接客户端，然后问一个你能核实的问题。

一个改变第一次编辑的循环

你不需要一套新的工作流信条。你需要的是在第一次落笔之前多加一步。

问一个你已经能评判的问题。“哪段代码处理登录和会话过期”比“修一下认证”更好。
要求引用。文件路径和行号，而不是“认证模块”的一段摘要。
打开被引用的文件。跟着符号走。确认你即将触碰的依赖关系。
只有到那时，才让智能体去打补丁。

如果第二步没有返回任何有用的东西，智能体就没有资格临时编造一条路径。它要么再搜索一次，要么由你来指路。正是这一道关卡，产生了更少的幻觉编辑。模型还是同一个模型。变了的是地图。

指令文件依然重要。保留它们。用它们来记录约定、审查规则，以及不该触碰的东西。不要要求它们充当索引。一个列出三个重要目录的 CLAUDE.md，在一次包拆分之后的那一周就会过时。而一张可查询的地图，会随着仓库的更新而更新。

一个相关的失败是“几乎对”的文件：当行为其实在 auth-client.ts 里时，智能体却打开了 auth.ts；或者补丁打在了一个生成的文件上，而不是源文件；或者因为名字匹配，编辑了 packages/legacy 里的那份拷贝。引用不会让这些错误变得不可能发生。它们只是让这些错误在 diff 落地之前变得可见。

一张地图不会为你修复的东西

对自己得到的东西保持清醒。一张有依据的地图不会让每一次编辑都变得正确——你的智能体依然可能在完全正确的文件里写出一个糟糕的补丁。如果你的代码库依赖动态派发、反射或猴子补丁，一些符号查找返回的结果会比你希望的更单薄，因为运行时的间接性对任何静态索引都会造成这种效果。而如果你在期待一个百分比——“幻觉路径减少了 X%”——你在这里找不到，因为除了你自己，没有人能为你的仓库诚实地测出这个数字。

你可以期待的东西范围更窄，也更有用：智能体不再用一条猜测出来的路径来开始它的编辑。这第一步会扎根于一张真实的地图，而更少的幻觉编辑正是由此而来。引用之后的一切——阅读 diff、判断补丁——依然是你的工作，和以往一样。

这个测试几乎不花你什么成本：索引一个你已经了解的仓库，问一个你能核实的问题。从一条曾经让你吃过亏的路径开始。如果引用错了，你会立刻看出来。如果对了，你智能体的下一次编辑就有了一个更好的落脚点。

// it doesn't know the file. it knows how to find it.

我们为什么把代码搜索升级到了 voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

本文中的基准数字反映的是发布时（2026 年 6 月）的 RTEB 排行榜状态。排行榜会变动，请把这些排名当作某个时间点的快照，而不是永恒不变的事实。

语义搜索的好坏，完全取决于它底层所用的 Embedding。

当一个智能体问 Maguyva “我们在哪里处理重试”时，它并不是在用 grep 搜索“retry”这个单词，而是在寻求含义——退避循环、熔断器，那些包裹着一次不稳定调用的东西。这个问题的答案，来自一个把代码转化为空间中一个点、再去寻找邻近点的向量模型。选一个更好的模型，产品里的每一次语义查询，都会悄悄变得更精准。

所以我们换了模型。截至 2026 年 6 月，Maguyva 的代码 Embedding 运行在 voyage-4-large 之上，取代了 voyage-code-3。

基准测试

我们做这个决定，靠的不是感觉。公开的 Retrieval Embedding Benchmark（RTEB，检索 Embedding 基准测试）会依据真实的检索任务，对各家 Embedding 模型进行排名，而在它的 Code 排行榜上，voyage-4-large 以 总分 90.86 排名第一——领先于 gemini-embedding-2-preview（90.26），而且值得注意的是，也领先于我们当时正在使用的模型 voyage-code-3（89.73，排名第三）。

这是一个很小的绝对差距。但它是在一个公开基准测试上、在我们真正在意的那项任务（按含义检索代码）上，朝着正确方向迈出的差距。

我们接受的取舍：二值量化（Binary Quantization）

这里是大多数“我们升级了模型”的文章都会略去的部分。

Maguyva 并不存储全精度向量，我们存储的是二值量化后的 Embedding：每个 2048 维的向量，都会被压缩成一个 2048 比特的签名——每个向量只占 256 字节。这些签名会用汉明距离（Hamming Distance）来搜索，并按租户进行索引和分区。

这是一次刻意为之的取舍。二值量化牺牲了一部分检索精度，换来的是大幅缩小的存储体积，以及快速、廉价的距离运算，而且不需要运维一个独立的向量数据库。对于一个要为每个工作区索引整个代码仓库的产品来说，这种经济性，比在基准测试分数上多抠出最后那一点点更重要。

voyage-4-large 恰好契合这套设计，不需要强行迁移存储层：它产生的是 2048 维输出，和 voyage-code-3 一样，所以我们的 bit(2048) 列和汉明搜索路径都不需要改动。模型变好了，Schema 原封不动。

代码只是个开始

Maguyva 是一个代码智能工具。但我们自己也是零号客户，而我们把它指向了另一样东西：那些和代码一起存在于我们代码仓库里的 Markdown 文档。架构决策记录、Runbook、合同、财务和政策文档——全部都在 Git 中受版本控制，全部都藏在同一个 MCP 服务器背后，是一个针对文档本身、而不只是源代码的语义索引。

这正是 voyage-4-large 的广度之所以重要的原因。在同一个 RTEB 排行榜家族中，它在金融领域排名第一，在医疗领域排名第一，在整体文本检索上也排名第一——领先于 Google 的 Gemini Embedding、Cohere 的 Embed v4，以及 OpenAI 的 text-embedding-3-large。（Voyage 是 RTEB 的共同创建者之一，所以我们把这个结果解读为一个有力的公开信号，而不是一个完全中立的裁判——但它确实是在私有的保留测试集上，与每一个主流商业模型正面对比得出的。）那套能为智能体找到正确函数的索引，同样能在一份合同里找到正确的条款，或者在一份政策文件里找到正确的那一行——在这些领域里，voyage-4-large 不是一种妥协，而是当之无愧的领跑者。

我们为什么愿意为高端 Embedding 付费

搜索本来有更便宜的做法，而且很大一部分是免费的。词法搜索——BM25 及其同类方法——匹配关键词，本地运行，不花一分钱。像 BGE、Nomic 和 embeddinggemma 这样的开源 Embedding 模型，能提供真正说得过去的语义检索能力，你只需要一块 GPU 的成本，就能自行托管它们。Maguyva 也用了这些免费的部分：每一次查询都融合了文本、AST、图谱和语义搜索。我们唯独不在语义这一层省钱。

我们按 Token 付费使用高端 Embedding——voyage-4-large——而不是自行托管一个免费模型，原因有两个。第一，当代码里写的是 backoff 和 circuit breaker、却从没出现过“retry”这个词时，单靠关键词搜索没法回答“我们在哪里处理重试”这个问题——含义，才是 Embedding 存在的全部意义，而在我们服务的这些领域里，开源模型都落后于高端模型：在通用文本上落后几分，在代码、合同、金融这类细分领域里则落后得更多。第二，根据我们的经验，检索质量对最终答案的影响，比另一端用的是什么模型更大——一个强大的智能体，如果拿到的是错误的上下文，依然会给出错误的答案，它永远看不到那份从未被交到它手上的文档。

所以，高端 Embedding 是一笔按 Token 计费、并随着我们索引的每一个代码仓库和每一份文档不断增长的账单——而我们是有意为之地在支付它。为了让用户得到那个正确的函数、或者那条正确的条款，我们认为这笔交易是值得的。

诚实的部分

Voyage 自己的文档，依然把 voyage-code-3 标注为代码优化模型。那我们为什么还要换？

因为我们参考的是公开基准测试，而不只是供应商自家的模型对照表，而这份基准测试，把 voyage-4-large 排在了代码检索的榜首。这是一个具有前瞻性的决定：选用更新、总体上更强的模型，并在关乎实际任务的公开排行榜上验证它。我们愿意下这个注，是因为证据是全面的——voyage-4-large 不只是在代码上获胜，它在金融、医疗和整体检索上同样领先。

默默支撑一切的基础

我们暴露出去的每一个工具——语义搜索、任务上下文收集、有据问答——最终都要落到检索上。当检索器变好了，另一端的智能体就能获得更好的证据，少走一些弯路，把答案扎根在正确的代码上——或者正确的条款、正确的政策上。一个更锐利的 Embedding 模型，不是一个花哨的功能，它是支撑其他一切的基础，而我们刚刚提升了这层基础的质量。你不会注意到这一点，而这正是重点所在。

语言递归自我提升：在约 280 种语言上打磨代码智能

Tue, 26 May 2026 00:00:00 GMT

本文中的数字反映了发布时（2026 年 5 月）的系统状态。最新数据请参见我们的团队页面。

Maguyva 从大约 280 种语言的源代码中提取符号、引用和依赖关系图。每种语言都对应一个自定义的 tree-sitter 处理器——查询、启发式规则、边界情况——每个处理器都可能以自己独特的方式出现细微的错误：一次方法调用被记录成了读取；一个函数被归属到错误的外层作用域；一段根本不存在的关系。

这种问题无法靠人工逐一核查。没有任何团队能够通读跨越 280 种语法的提取结果并找出其中的坏边。所以真正有意思的问题不是“我们的提取是否正确”，而是“在这样的规模下，如何在不让人工介入每一个循环的情况下发现它是错的”。我们的答案是语言的递归式自我改进：由语言智能体驱动的质量闭环，以 LLM 充当裁判，以及一条我们不断重新学习的规则——绿灯不等于正确。

绿灯不等于正确

每种语言都有一套 fixture 测试集，发布关卡会在五个维度上为其打分——准确性、结构完整性、完整度、质量和性能。只有当某种语言在其 fixture 上精确率 ≥ 0.95、召回率 ≥ 0.99、F1 ≥ 0.97，且至少有 20 条预期边以保证统计置信度时，该语言才会被判定为绿灯（GREEN）。低于这个标准就是黄灯或红灯，不能发布。

这道关卡是必要条件，但不是充分条件。Fixture 是针对我们自己编写的 fixture 做验证的，它们只编码了我们已经想到的那些情形。一个处理器可以在其 fixture 上表现完美，却仍会在真实代码中出现的模式上出错——一个宏惯用法、一个泛型约束方法、一个没人为它写过 fixture 的语言特性。绿灯只意味着 fixture 通过了，并不意味着真实代码仓库能被干净地提取。所以这个闭环必须离开 fixture，走向真实世界。

内层循环：抽查、裁判、修复、验证

核心闭环每次运行一种语言：

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

有几个设计让这套流程真正起作用，而不是原地打转。

裁判是智能体本身，而不是一次 API 调用。 我们所说的“LLM 作裁判”，指的是语言智能体亲自将每一条抽样得到的边与真实源码对照，并按照一套固定的五分类标准进行判定：这条边是正确的、是误报、是关系正确但类型错误、是挂错了作用域，还是携带了错误的元数据？这套评判标准才是关键所在——在你知道“23% 的错误率”究竟是真实缺陷还是裁判数错之前，这个数字本身毫无意义。

一次只修一件事，然后证明它有效。 每一次迭代只改动一项可编辑资产，随后针对固定的测试基准重新运行，只有当 F1 提升且重新分类的结果更好时才保留这次改动，否则就回滚。不做成批的猜测性改动，也没有“应该会更好”这种说法。一个改动要么证明了自己的价值，要么就被丢弃。而当一次修复站稳脚跟后，它会被提升进入 fixture 测试集——这样它修复的那个 bug 就再也不会悄悄回归。正是这一步“提升”操作，让这个闭环成为递归的，而不仅仅是重复的：每一轮都在加固下一轮据以验证的那个基准。

我们不断重新学到的教训：指标会过度报告

这里有一个陷阱，而我们一头扎了进去。次级语料库指标——比如提取出的目标有多少比例找不到可解析的符号、有多少符号看起来“孤立”等等——会大幅度地过度报告问题。它们大多数情况下是范式产物，而不是 bug。

最典型的例子是：llvm 曾一度显示出 73% 的“有源无符号”比例，被贴上了“灾难性”的标签。我们深入排查后发现，真实准确率其实是 98.5%。那些“缺失的符号”几乎全部是合法的外部引用——调用标准库、调用框架、调用仓库之外的代码。这项指标衡量的是这门语言本身的特性，而不是处理器的缺陷。像 Zig、COBOL 和 Odin 这样的语言“孤立”比例高达 65%–70%，但完全正确；COBOL 甚至零真实错误。

如果我们当初任由这些数字牵着走，就会花上数周时间去“修复”那些本来就没问题的处理器，反而忽略了那些真正存在隐蔽 bug 的语言。结论很直白：聚合指标充其量只是一个粗略的分诊信号。真正的质量信号来自带有边分类的抽查——逐条查看真实代码仓库中的实际边并逐一判定。数据胜于直觉，但前提是你得先知道哪些数据在说真话。

外层循环：一支舰队，而不是一场马拉松

如果一次只处理一种语言，280 种语言要跑到天荒地老，所以内层循环被包裹进一个能并行运行多种语言的外层循环中。

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

每个智能体都在一个一次性的工作树中运行，彼此互不干扰。编排器逐个整合它们的修复，每一次都要通过完整清单的回归检查：一个改动即便让自己那门语言受益，只要悄悄破坏了另外三门语言，就不会被合入。集成过程受到把关并在推送前得到确认——回归关卡决定什么是安全的，而人来决定什么可以发布。之后，整个语言池会轮换到下一批语言，整个流程再来一遍。

仍不完美之处

裁判也会出错，而且出错是有方向性的：上下文太少的智能体往往会过度报告。在某一批次中，有八种语言被标记为 5%–20% 的错误率；仔细排查后，只有一种是真正的语言特定 bug——其余都是裁判因为没理解该语言自身语义而犯下的错误（同一行源码合理地产生多条边、参数绑定被建模为赋值、按标识符逐一生成引用的语言）。这也是为什么我们用两个种子分别抽样并交叉核对，以及为什么裁判与 fixture 之间的分歧被视为最值得关注的信号，而不是定论——有时候错的其实是 fixture。

我们对目标也保持诚实。目标是零真实错误，毫无保留——但“零”是我们一门语言接一门语言不断磨出来的方向，而不是一个可以打钩的选项。永远还有下一个仓库、下一种惯用法在等着。

靠赢得，而非靠断言

Maguyva 为智能体所做的一切——查找一个符号、追踪一条依赖、用引用的代码回答一个问题——都建立在底层提取正确的基础上。跨越 280 种语言，“正确”无法靠断言获得，它必须在真实代码面前被持续地赢得。这个闭环就是我们赢得它的方式：一个自主的抽查—修复循环，它对自己的指标始终保持怀疑，为每一次改动提供证明，并把每一次修复都变成对下一次回归的防线。这并不光鲜。但正是这份工作，让我们能够说出“我们支持你的语言”这句话并且言出必行。绿灯很容易，正确要靠赢得。

多模态融合搜索：为每一次查询挑选正确的检索器

Wed, 15 Apr 2026 00:00:00 GMT

历史设计说明：这篇 2026 年 4 月的文章描述的是当时的路由设计，并非当前的默认行为。下方 9 月的更正仅针对一项测量声明。关于当前的路由、预设和显式检索模态控制，请参阅工作原理。

搜索查询从来都不是单一的一种东西。

“parseConfig 在哪里定义”想要的是一个精确的符号——一个准确的位置，越快越好。“身份验证是如何工作的”想要的是含义——一整片能解释某个概念的相关代码。“如果我改动这个函数会破坏什么”想要的是依赖关系图。“查找字符串 ECONNREFUSED”想要的是字面匹配，不需要任何巧思。

Grep 非常擅长字面匹配，对某些引用查找也很有用，但它不是依赖关系图，也不理解含义。嵌入向量覆盖了语义这一侧，但对精确字符串匹配和影响分析来说，它是错误的工具。大多数代码搜索工具只挑一种引擎，然后让每一个查询都受制于这个选择。Maguyva 不做这种取舍。它会先判断你问的是哪一类问题，再按这个问题应得的比例混合四种检索器。

四种模态

底层有四种独立的代码查找方式：

语义（semantic）——基于 Voyage 二进制嵌入的向量搜索；按含义查找代码。
文本（text）——trigram 匹配；查找字面量、错误字符串、精确标识符。
结构（structural）——AST 查询；查找定义、签名和语言构造。
图（graph）——依赖关系图；查找调用方、被调用方和影响范围（blast radius）。

每一种模态都擅长应对不同类型的问题。诀窍在于针对眼前这个查询，决定该在多大程度上信任每一种模态。

意图分类

在任何检索开始之前，一个轻量级分类器会先把查询归入六种意图之一，并给出一个置信度分数。它被刻意做得很“便宜”——按顺序排列的启发式规则，第一个命中就采用——因为它运行在热路径上，只会额外增加一两毫秒：

以 def 、class 、func 、import 开头…… → find_definition（置信度 0.95）
“who calls”、“usages of”、“references to” → find_references（0.90）
“impact”、“blast radius”、“what depends on” → impact_analysis（0.90）
带引号的 "string" 或像 traceback 这样的错误标记 → exact_match（0.85–0.90）
CamelCase 或 snake_case 这样的标识符 → find_definition（0.60–0.80）
“how”、“why”、“explain”、“architecture” → understand_code（0.75）
什么都不匹配 → understand_code，低置信度（0.40）

每种意图在四种模态上都带有一套权重配置。以下是实际数值：

意图	semantic	text	structural (AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

所以“parseConfig 在哪里定义”会强烈偏向 AST（0.6）。“身份验证是如何工作的”会偏向语义向量（0.5）。“这个改动会影响到什么”几乎完全落在图模态上（0.7）。“查找 ECONNREFUSED”几乎全靠 trigram（0.9），嵌入模型完全被关闭——因为对精确字符串来说，语义相似度恰恰是错误的工具。

快速路径与融合路径

当分类器足够自信时——分数 ≥ 0.85——并且查询是一个常规查询，Maguyva 会完全跳过融合，直接路由到那个唯一占主导地位的模态。“X 在哪里定义”不需要四个检索器，它现在就需要 AST 索引。这条直接路径会被回报为 fusion_strategy: "direct"。

一切模糊不清的查询都要经过融合。四种（或在默认预设下是三种）模态并行运行，各自返回自己的排序列表，然后我们把它们合并起来。

加权倒数排名融合（Weighted Reciprocal Rank Fusion）

融合异构检索器比听起来更难：0.82 的余弦相似度、137 的 trigram 分数和 0.004 的图中心度并不在同一个量纲上，所以不能直接相加。倒数排名融合（Reciprocal Rank Fusion）绕开了这个问题：它丢弃原始分数，只保留每个引擎给出的排名。一个结果来自某一模态的贡献值是：

contribution = weight × 1 / (k + rank + 1)

其中 rank 是它在该模态列表中的位置，k 是一个平滑常数。对于被不止一个引擎找到的结果，各模态的贡献会被累加——检索器之间的一致意见自然会浮到最上面。默认预设下我们使用 k = 40，在 thorough 上使用 60（quick 只运行语义检索，所以那里从不会触发融合）。RRF 原始论文对通用检索场景给出的是 k = 60；我们的默认值略微更“锐利”一些，这让排名靠前、被多个模态一致认可的结果获得更多一点的权重——我们不建议手动去调它。

除此之外，结果还会带有一个图重要性加成。一个枢纽节点——整个代码库都依赖的一个函数——即便文本相关性相同，也应该排在一个不起眼的叶子节点前面，所以我们会把每个贡献值乘以：

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

中心度来自流水线预先计算好的 PageRank / 度数指标，加成被限制在 1.5 倍以内，这样一个热门函数就不会把一个更相关但不起眼的函数完全埋没。最后，我们会降权来自 vendor、build 和 archive 路径的结果，并按文件对最佳片段去重。

仍不完美之处

意图分类器是一组正则表达式，而不是经过训练的模型。它使用启发式方法处理常见的查询形式，遇到含糊的查询时，会回退到 understand_code 和偏重语义的混合检索。本文的早期版本曾将无结果查询比例从约 15% 降至低于 5% 描述为已实现的改进。实际上，2025 年 12 月的提案列出的是估计基线和目标，并未提供支持这一结果的查询集或测量记录。我们撤回这项已实现改进的声明；参见源证据与更正（英文）。我们尚未用训练过的模型替换该分类器，因为低成本版本对于预期的路由用途而言足够快、也足够好，而且一个自信却错误的分类器，比一个坦诚的回退方案更糟。这些权重是手工选定的先验值，并非从我们没有收集的点击数据中学习而来。

问问题，而不是问该用哪个工具

智能体不应该需要知道该用 grep 还是嵌入向量还是调用图——它应该用大白话问出自己的问题，然后得到正确的答案。多模态融合正是让 find_symbol、语义搜索和依赖分析能够共处于同一个查询入口背后的原因：系统会读出问题的形状，并悄悄组装出适合它的检索器。给嵌入打分的模型固然重要，但知道什么时候不该用它同样重要。为每个查询挑选正确的工具，本身就是一种质量，而这是我们宁愿自己承担、也不愿推给调用方的事情。

// you bring the question. it brings the tools.

智能体可观测性：Hooks、Alloy 与 Grafana

Tue, 24 Mar 2026 00:00:00 GMT

智能体系统会以各种古怪的方式出问题。

有时候是模型的问题，有时候是工具的问题。有时候你的 MCP 服务器明明一切正常，但智能体选错了专家子智能体，或者花了半个会话去做你根本没料到的 Shell 操作，又或者在一个表面看起来很“高产”的循环里悄悄烧掉了成本。

如果你看不出这些差异，你其实并不是在运维一个智能体系统，你只是在瞎猜。

所以我们为自己的工作流搭建了一套可观测性技术栈：Claude Code、Codex、Claude 的 Hook 事件、Codex 的 notify 事件、原生 OpenTelemetry，另一端则是 Grafana Alloy 和 Grafana Cloud。

有意思的地方不在于“我们做了一个仪表盘”，而在于我们不得不把遥测数据拆分成两条不同的数据流——因为没有任何一条单一的数据源能给我们完整的图景。

问题所在：智能体遥测数据是碎片化的

现代编码智能体本身已经会发出一些遥测数据，这有帮助，但还不够。

原生 OTEL 很擅长回答这类问题：

我们发出了多少次请求？
一个会话花费了多少成本？
Span 和 Trace 在哪里？
延迟有没有出现峰值？

但它在回答这类问题时就差得多了：

智能体主要依赖了哪个 MCP 服务器？
这次失败发生在 Bash、某个内置文件工具，还是某次 MCP 调用中？
究竟哪个技能被激活了？
调度出去的是哪种子智能体类型？
这个会话到底是在做有用的工作，还是在空转？

第二类问题，离 Hook 更近，离 Trace 更远。

但反过来也一样成立：一些最重要的性能问题，反而离 Trace 更近，离 Hook 更远。

如果你想知道延迟究竟积累在哪里、哪些 Span 慢了，或者这个会话把时间花在了模型调用上还是工具执行上，你既需要 Trace 数据，也需要语义事件。

我们最终采用的架构

我们并行运行两条遥测路径。

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

这种拆分是刻意为之的。

它同时也是不对称的。Claude Code 给了我们丰富得多的生命周期 Hook 接口；Codex 给了我们原生 OTEL 加上一个 notify 接口，所以我们把 Codex 那些较为单薄的“轮次完成”事件规范化进同一套日志 Schema，而不是假装两个运行时暴露出的是同一套控制能力。

原生 OTEL 为我们提供了基线数据流：来自运行时本身的日志和 Trace，以及运行时实际发出的指标。

Hook 与 notify 事件 为我们提供了语义层：诸如 PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、SubagentStop、SkillActivated，以及我们在调试智能体行为时真正关心的那些分类元数据。Claude Code 在这里贡献了更丰富的事件流，Codex 贡献的是一条更单薄、但依然有用的规范化数据流。

Hook 究竟为什么存在

我们的 Hook 流水线会在事件进入 Loki 之前，先对它们进行增强处理。

我们不会只说“某个工具运行了”，而是把事件分类到诸如以下字段中：

tool_type:builtin、mcp、skill、agent、bash
mcp_server：哪个 MCP 后端处理了这次调用
bash_cli:Shell 命令的类别
subagent_type：调度出去的是哪种子智能体
agent_tool：事件来源是 Claude Code 还是 Codex

这意味着我们可以提出真正关乎运维的问题：

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

这些都不是花架子字段。它们是“感觉智能体有点慢”和“智能体在过去十分钟里都耗在了工具失败率很高的、大量使用 Shell 的 Git 操作上”这两种说法之间的真正差异。

有一个看起来比实际更奇怪的实现细节：即便事件来自 Codex，共享的 Loki 数据流仍然使用 service_name="claude-code-hooks" 作为标签。运行时之间真正的区分发生在 agent_tool 上。

为什么 Alloy 处在中间位置

在这套设置里，Grafana Alloy 不只是一个转发器，它是策略边界。

我们把来自 Claude Code 和 Codex 的原生 OTEL 数据流，指向 localhost:4318 上的本地 Alloy 代理，让 Alloy 在把负载转发给 Grafana Cloud 之前先清理一遍。

这一点很重要，因为原始的智能体遥测数据里，充斥着大量对分析很有用、但作为索引标签却很糟糕的高基数字段：

session_id
prompt_id
Token 计数
耗时
工具参数数据块

如果你把一切都拿去建索引，就会遇到标签爆炸，然后迎来糟糕的一天。

所以 Alloy 为我们做了三件事：

只保留一小撮低基数标签进行索引。
把嘈杂但有用的字段挪进结构化元数据里。
把纯粹的噪声彻底丢弃。

核心理念很简单：多观测，少索引。

为什么 Hook 数据流会绕开 Alloy

Hook 数据流本身已经是为 Loki 量身打造的了。

在 send_event.py 推送一个事件之前，我们早就已经决定好了哪些字段值得作为标签处理、哪些字段应该留在结构化的 JSON 主体里。这条数据流会直接发往 Grafana Cloud 的 OTLP 网关，而不会再经过 Alloy 处理一遍。

所以整个系统的分工非常清晰：

Alloy 驯服原始的原生 OTEL 数据流。
Hook 增强 让语义事件变得可查询。

这比试图把一切都硬塞进同一条路径，要简单得多。

仪表盘实际展示了什么

下面的截图来自我们智能体工作流背后的一个可观测性仪表盘。这不是基准测试，这些数字也只是某个时间点的切片。重点在于数据的形态：活动流、工具调用、失败情况、提示词，以及按智能体、内置工具、MCP 使用情况、Shell 命令和技能划分的明细。

有用的地方在于，这个仪表盘和其余的智能体遥测数据位于同一套 Grafana 技术栈上。我们可以按来源智能体和工具族群筛选，跨运行时查看，而不必为每个系统都另外发明一套可观测性方案。

这是我们智能体工作流背后实时仪表盘中的一个。这张截图只是共享 Grafana 技术栈中的一个切片，该技术栈还接收着来自我们其他智能体运行时和系统的遥测数据。点击图片可查看完整分辨率版本。

为什么 Trace 比乍看之下更重要

日志告诉我们发生了哪一类工作，Trace 告诉我们这项工作是如何随时间展开的。

这个区别在智能体系统中很重要，因为“慢”这个词太笼统，没什么实际用处。

一条 Trace 可以告诉我们，痛点究竟来自：

模型延迟
工具执行耗时
反复重试
某一次格外昂贵的 MCP 交互
一长串单独看起来都无伤大雅的小操作

实际操作中，我们会把 Hook 数据流和 Tempo 的 Trace 结合起来使用。

Hook 日志 回答的是：发生了什么类型的事情？
Trace 回答的是：时间都花到哪里去了？

正是这种组合，才把可观测性从一个仪表盘变成了一份解释。

Codex 处在什么位置

Codex 是同一套技术栈的一部分，但它和 Claude Code 并不完全相同。

对于 Codex，我们接入了两个部分：

来自 Codex 的原生 OTEL 数据接入 Alloy
一个 notify Webhook 接入 codex_notify.py，把轮次完成事件映射进我们用于 Hook 事件的那套 Loki Schema

这让我们能在同一条日志流内，使用像 agent_tool="codex-cli" 这样的统一筛选条件。

诚实地说有个但书：Codex 的 notify 负载目前比 Claude Code 的 Hook 负载要单薄，因为二者本就不是同一种集成接口。在我们今天的设置里，Codex 的轮次完成事件可以被规范化进共享 Schema，但要做到逐工具的丰富提取，原生 OTEL 数据流依然比 notify 桥接更胜一筹。

这不是回避这篇文章要说的问题的理由，恰恰相反，这正是这篇文章想说的重点：真正的可观测性系统，本就是由不完美的信号拼凑而成的。

通过 MCP 使用 Grafana，彻底改变了游戏规则

更大的转变在于，Grafana 不再只是人类在浏览器里访问的地方。

在这个代码仓库中，我们还通过 MCP 把 Grafana 暴露了出来。这意味着智能体可以直接查询 Loki、Prometheus 和 Tempo，而不必等人类先手动查看一遍仪表盘。

这让可观测性变成了工作流中一项主动的输入，而不只是被动的报告。

智能体可以提问：

过去一小时里，哪个工具族群失败次数最多？
哪个 MCP 服务器在某个会话中占据了主导？
最近的改动是减少了工具失败，还是只是把工作挪到了更依赖 Shell 的路径上、却犯着同样的错误？
哪些 Trace 显示出最高的延迟或反复的重试？

一旦你能做到这些，你就已经非常接近一个自我提升循环了。

从仪表盘到反馈循环

这是我们觉得最有意思的部分。

一旦可观测性技术栈可以从智能体层被查询，遥测数据就不再是一个被动的报告界面，而是变成了一个控制信号。

这个循环大致是这样的：

智能体活动产生 Trace、指标，以及经过增强处理的 Hook 日志。
Grafana 把证据存储在 Loki、Tempo，以及存在指标的地方——Prometheus。
智能体通过 Grafana MCP 查询这些证据。
系统识别出糟糕的工具组合、脆弱的技能、薄弱的路由，或是那些不断产生可避免错误的、大量依赖 Shell 的工作流。
智能体或运维人员调整提示词、智能体配置、技能描述、路由规则或工具访问权限。
下一个会话产生新的遥测形态，循环再次开始。

这就是从“有意思的仪表盘”走向“可衡量的改进系统”的方式。

目标不是把某一类工具的使用量最大化，而是针对实际正在进行的工作，找到 CLI、内置工具、MCP 调用和技能之间恰到好处的组合。

这让我们能够回答什么问题

一旦两种运行时都汇入同一套 Grafana 技术栈，我们就能更快地回答运维层面的问题：

失败是否集中在某一个工具族群里？
大量依赖 Shell 的工作流，是否正在制造本可以用更高层级工具避免的错误？
哪些 MCP 服务器承担了主要工作量？
我们是否在为那些没有产生实质进展的智能体活动买单？
一个会话状态不健康，是因为模型、工具，还是编排层出了问题？

这在多智能体工作流中格外有用，因为“智能体一直很忙”这句话几乎什么都说明不了。

如果某个专家子智能体不断被调度、却产生很高的失败率，那就是路由或提示词设计的问题。

如果某个 MCP 服务器主导了所有调用，这可能是良好的架构，也可能说明其他一切都是摆设。

如果工具失败率飙升、成本却居高不下，那是运维问题，不是质量问题。

如果 Shell 相关工作总是以可预测、本可避免的方式失败、而本该有更高层级的工具存在，那就是一个产品信号。

如果某个技能持续被激活、却没有改善结果，那就是一个提示词或路由信号。

真正的教训

这里更深一层的教训是：智能体可观测性同时需要运行时遥测和工作流遥测。

运行时遥测告诉你系统做了什么。

工作流遥测告诉你智能体当时以为自己在做什么。

两者我们都需要。

如果你只保留 Trace 和计数器，就会错过语义层；如果你只保留 Hook 事件，就会错过延迟、Span 以及更宏观的运行时全貌。

而如果你两者都保留了、却从不把它们反馈回智能体层，那你拥有的只是监控，而不是自适应能力。

正是这种组合，才让系统既足够可解释、能够运维，又足够可调优、能够改进。

目前仍不完美之处

仍然存在一些粗糙的边缘。

并非每个 Hook 事件都包含我们想要的耗时和 Token 数据。
一些最好的时序视图，依然来自 Tempo 的 Trace，而非 Hook 日志。
目前在增强事件流的语义丰富度上，Codex 仍不及 Claude Code。
仪表盘截图是一个真实的运维界面，而不是一件打磨过的营销作品。

最后一点是有意为之的：比起假装智能体系统能神奇地自我解释清楚，我们更愿意展示真实的仪表盘本身。

为什么这对 Maguyva 很重要

Maguyva 的核心，是为智能体提供更好的代码智能。但一旦智能体真正开始做有用的工作，一个新的需求就会立刻浮现：你需要能看清它们的行为方式。

搜索质量、路由质量、工具选择和上下文效率，统统会变成可观测的问题。

这正是我们认为这个话题值得写一写的原因。未来的智能体技术栈不会只是提示词加工具，而是提示词、工具，再加上一层能告诉你整套系统是否真正在正常运转的仪表层。

如果你正在构建认真严肃的智能体工作流，可观测性就不是可有可无的基础设施，而是产品本身的一部分。

挖掘闭环：变更如何沉淀为组织记忆

Tue, 03 Feb 2026 00:00:00 GMT

本文中的数字反映的是发布时（2026 年 2 月）的系统状态。如需查看最新数据，请参阅我们的团队页面。

每个工程团队都面临同一个难题：变更每天都在发生，但这些变更背后的原因却会渐渐消失。六个月之后，有人会问“我们当初为什么在流水线阶段里采用了 DuckDB?”，而答案往往只存在于当初做出这个决定的人脑子里——前提是那个人还在。

我们搭建了一套挖掘工作流，把这个闭环补上了。变更通过 Git 提交流动，经由我们的挖掘流水线处理，变成结构化的变更日志条目和架构决策记录，再通过 CLI 查询反哺回我们的 AI 智能体。结果就是：一份人类和 AI 都能访问的组织记忆。

问题所在：决策会蒸发

设想一个典型场景。某个开发者提交了这样一条记录：

feat(canonical): add DuckDB runtime for pipeline stages

这次提交代表着一个重大的架构选择。团队评估过多个方案、权衡过各种取舍，最终出于特定原因选定了 DuckDB。但所有这些上下文，都散落在：

某个 Slack 讨论串里（大概率已经被删了）
某个人的记忆里（必然正在淡去）
代码里的某条注释里（如果你运气好的话）

三个月后，一位新加入团队的成员问道：“这个新阶段我应该用 DuckDB 还是 SQLite?”没有组织记忆的情况下，他们要么重新发明一遍轮子，要么做出前后不一致的选择。

这个闭环：从提交到上下文

我们的挖掘工作流，把 Git 历史转化为可查询的知识：

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

这里的关键洞见是：变更日志和架构决策，都来自同一份 Git 历史，经由同一套统一的流水线处理。这确保了不会有任何东西从缝隙中漏掉。

挖掘是如何进行的

第一步：同步索引

uv run orkestra mine sync

这个命令会扫描 Git 历史，为所有提交建立索引。它会从每次提交中提取结构化信号：

符合约定式提交（Conventional Commit）规范的类型（feat、fix、chore、docs）
作用域（涉及哪个包或哪个领域）
破坏性变更标记
涉及的文件以及复杂度指标

第二步：检查覆盖状态

uv run orkestra mine status

我们目前的状态大致是这样的：

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637 次提交已被处理。476 次变成了架构决策。6,799 次变成了变更日志条目。每一次提交都被分类过了。

第三步：获取待审查的候选提交

uv run orkestra mine candidates --limit 50 --full

这会找出尚未处理过的提交，并附带用于分类的完整上下文：

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

这些信号能帮助指导分类：is_releasable_type: true 暗示这应该出现在变更日志中；较大的插入行数以及涉及的基础设施文件，则暗示它可能同时也是一条架构决策。

第四步：对提交进行分类

到这一步，会分出两条路径：变更日志条目和架构决策。

对于变更日志条目：

uv run orkestra mine classify abc123 --changelog added

这会记录下提交 abc123 应该出现在变更日志的“Added”类别下。

对于架构决策：

首先，获取一个真实的决策 ID:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

然后用这个决策 ID 进行分类：

uv run orkestra mine classify abc123 --decision DEC-PL-143

这会把这次提交，关联到一条将被创建或更新的决策记录上。

对于批量处理（我们实际采用的方式）：

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

JSONL 格式可以在一次处理中同时支持两个领域：

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

第五步：渲染输出

uv run orkestra registry changelog render --package <pkg>

这会根据台账（Ledger），为每个包生成 CHANGELOG.md 文件。变更日志是派生产物——删掉它们，也能从源头台账完美地重新生成。

决策记录的结构

提取出的决策，会变成带有丰富元数据的 YAML 文件：

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

每条决策都会关联回其源头提交，每条决策都会指明它影响哪些文件，决策与决策之间的关系也是明确的。

CLI 集成：查询组织记忆

这正是闭环真正合拢的地方。智能体可以通过 CLI 查询决策：

# Search by topic
uv run orkestra registry decisions search --query "retry"

返回与重试逻辑、错误处理、恢复模式相关的决策。

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

返回完整的决策记录，包括上下文、理由和影响。

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

展示最近做出了哪些架构选择。

智能体如何使用它

我们编排器的基础指令中包含了这样一条：

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

当一个智能体被要求实现与 DuckDB 相关的东西时，它可以先检查：

uv run orkestra registry decisions search --query "DuckDB"

然后发现 DEC-PL-142，并从中了解到：

我们为什么选择 DuckDB(context)
该如何正确使用它（agent_guidance）
应该查看哪些文件（files）
存在哪些相关决策（related）

智能体不需要重新发明轮子，而是在既有模式的基础上继续构建。

三问测试

并非每次提交都值得拥有一条决策记录。我们用“三问测试”来做筛选：

这个决定难做吗？ 是否需要经过大量分析、权衡评估，或者一番争论？
改变它的代价高吗？ 如果要推翻这个决定，是否需要大量返工？
它是否具有系统级的影响？ 是否影响多个包，或者树立了其他人会遵循的模式？

如果一次提交对这三个问题中至少一个的答案是“是”，那它就是决策提取的候选对象。我们通常的比例是：每 100 次提交中有 1 到 4 条决策（大约 1% 到 4%）。

对于变更日志条目，门槛要低一些：任何面向用户的变更（功能、修复、改进）都会被记录下来。内部杂务、文档更新和重构通常会被跳过。我们通常的比例是：每 100 次提交中有 30 到 50 条变更日志条目。

数据存储：仅追加式台账

这套挖掘系统使用仅追加式的 JSONL 台账，以实现无冲突的多智能体协作：

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

这种在 .gitattributes 中使用 merge=union 的 JSONL 格式，意味着多个智能体可以同时对提交进行分类，而不会产生合并冲突。每一行都是独立的。

验证门禁

在任何一次挖掘会话开始之前，我们都会先运行验证：

uv run orkestra mine validate --quick

这会检查：

SHA 格式是否有效
决策 ID 格式是否合规
同一个 SHA 是否存在重复条目
引用的决策是否真实存在

分类完成之后，我们会在提交改动之前再验证一遍。

为什么这很重要

我们搭建的这个反馈闭环，解决了好几个问题：

对新团队成员而言： 他们不必再问“我们当初为什么这么做”，而是可以直接搜索决策注册表。上下文被完整保留了下来。

对 AI 智能体而言： 它们不再是在真空中运作，而是可以在给出建议之前先查询组织知识。当被要求新增一个流水线阶段时，它们可以发现 DuckDB 这个模式并加以遵循。

对架构一致性而言： 决策是明确的、可搜索的。当有人提出一个与既有决策相矛盾的方案时，系统可以把这个冲突暴露出来。

对变更日志生成而言： 发布说明不再是临阵磨枪赶出来的东西，而是开发过程中持续分类的一个副产品。

对新人上手而言： 新加入的智能体能继承代码库的完整上下文。它们看到的不只是代码本身，还有塑造了这些代码的那些决策。

现状

截至目前：

已有 15,637 次提交 经流水线处理
已提取并记录了 476 条架构决策
已记录了 6,799 条变更日志条目
两个领域都达到了 100% 覆盖率

自我们开始以来的每一次提交，都已经被分类过了。这份组织记忆是完整的，并且可以查询。

快速上手

如果你想实现类似的东西：

从约定式提交开始。 当提交带有结构化前缀（feat:、fix:、chore:）时，这套挖掘流水线的效果最好。
定义你自己的领域。 我们使用诸如 pipeline、agent-design、observability、data-modeling 这样的领域，用它们按区域来组织决策。
养成分类的习惯。 只有当团队持续、定期地对提交进行分类时，挖掘才会真正有效。借助 LLM 辅助的批量处理，有助于扩大规模。
让决策可以被查询。 当智能体能够通过 CLI 搜索决策时，这份价值会不断复利累积。请为机器可读性来组织你的输出结构。
让闭环真正闭合。 决策应该影响未来的工作。请在智能体指令和代码评审清单中，加入对决策的引用。

目标不是追求完美的文档，而是让变更背后的原因——无论是今天，还是六个月之后——对人类和 AI 都保持可访问。当变更沉淀为组织记忆，团队就能在既有模式的基础上继续构建，而不必重新发明它们。

这套挖掘工作流，是我们编排引擎的一部分，具体来说，是我们编排包中的上下文引擎（Context Engine）模块。

技能挖掘：从 3,500 个候选项到 466 项能力

Tue, 27 Jan 2026 00:00:00 GMT

本文中的数字反映的是发布时（2026 年 1 月）的系统状态。如需查看最新数据，请参阅我们的团队页面。

3,500 个技能的难题

当我们开始搭建一套智能体编排系统时，面对的是一个有意思的挑战：整个 AI 生态里，散落着成千上万个潜在的技能。GitHub 代码仓库、供应商文档、社区项目、内部模式——技能无处不在。但哪些才真正重要？哪些真正管用？你又该如何维护一套智能体真正能用得上的、连贯一致的技能库？

我们的答案是：一套系统化的挖掘与吸纳循环。

今天的数字

距 Anthropic 于 2025 年 10 月 16 日推出 Agent Skills 刚过三个多月，以下是本文发布时（2026 年 1 月 27 日）我们所处的状态：

指标	数量
已识别的候选项	3,500+
已采纳的技能	466
供应商技能	373
内部技能	93
活跃供应商	25+
每项技能平均 Token 数	2,834
引用的工具数	89
唯一标签数	635

我们审查了超过 3,500 个技能候选项，最终采纳了 466 个。采纳率是 13%——而这种挑剔，是有意为之的设计。

知识分层体系

并非所有技能都生而平等。我们把它们组织成五个知识层级（K0 到 K4），每一层代表一种不同的适用范围：

K0：基础（通用）

每个智能体都应该具备的技能。这些代表着放之四海皆准的“优秀思考者”能力。

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 技能可以移植到任何项目、任何领域、任何技术栈，它们编码的是通用的认知模式。

K1：身份（学科）

在某个学科内、跨项目通用的“优秀工程师”或“优秀研究者”技能。

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2：领域（专业知识）

在某个领域内可移植的“优秀数据库专家”或“优秀安全工程师”技能。

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3：技术栈（技术）

针对特定技术栈的“优秀 Supabase 用户”或“优秀 Cloudflare 开发者”技能。

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4：项目（组织）

特定于我们自己组织和工作流的技能。

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

挖掘循环

第一阶段：发现

技能来自四面八方：

供应商代码仓库:AWS、Anthropic、Cloudflare、Supabase，以及社区贡献者，都会发布技能合集。我们追踪着 25 个以上的供应商源。

社区项目:GitHub 上到处都是 Claude Code 模板、智能体模式和工作流定义。

内部模式：随着我们团队不断解决问题，各种模式会自然浮现，这些模式随后会被正式提炼成技能。

文档挖掘：技术文档中常常隐含着技能——流程、检查清单、决策树。

发现是持续不断的。我们用一个技能待办列表，在正式评估之前追踪这些候选项。

第二阶段：评估

每个候选项都要经过同一套评估标准：

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

五项产品标准必须全部通过，这就是为什么 87% 的候选项会被淘汰。

然后，每个候选项还要经过一次独立的信任评审。我们不会把一个官方供应商代码仓库、一个知名的社区维护者，和一个随机的 GitHub 代码仓库，当作同等可信的来源来对待。

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

可信的供应商会得到一次较轻量的溯源审查，但绝不是可以直接放行的通行证。不可信或未知的来源，会经过更深入的人工审计，而且在脚本被阅读、圈定范围、并被判定为安全之前，我们不会执行任何随附脚本。

差距分析：在采纳之前，我们会先搜索自己的注册表：

uv run orkestra skills search "<capability>"

如果我们已经有了，那就不需要它。如果我们已经有相近的东西，我们可能会选择合并，而不是采纳。

深度与规范评分：我们还会给候选项打分，评估它对“智能体-技能”模型的运用有多充分。一个孤零零的 SKILL.md 依然可能有用，但当一项技能按照 agentskills.io 所鼓励的方式，把指令和参考资料、脚本、素材区分开来时，它会更有价值，也更深入。

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub 星标数可以稍微提升一点可信度评分，但它永远无法拯救一个浅薄或不安全的技能。一个星标很多、却只有一份内容含糊的 SKILL.md 和不透明脚本的代码仓库，评分会低于一个规模更小、但描述精确、references/ 经过精心整理、且配有真正用足完整技能能力的原子化辅助工具的代码仓库。

结构分析：我们会检查技能的质量：

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

如果候选项包含脚本，这项审查就会变得更加严格。一个好的技能，不仅要有用，还必须清晰可读、边界明确，并且可以放心交给智能体去用。仅这一道安全过滤，就足以淘汰掉一大批原本看起来很有意思的候选项。

第三阶段：吸纳

当一项技能通过评估后，就会进入注册表。但技能从来不会被原封不动地采纳，而是会被修改以适配我们的系统。

采纳时的修改:

元数据规范化：每项技能都会套用我们的 Frontmatter Schema
K 层级分配：把技能归入合适的知识层
标签充实：添加标签以便被发现
工具声明：明确声明允许使用的工具
章节对齐：重新组织内容，使其符合我们的模板

吸纳之后一份典型的技能 YAML:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

第四阶段：作用域分配

技能会被分配到不同的作用域——这些类别决定了哪些智能体会加载哪些技能：

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

智能体声明自己的作用域，技能就会被自动分配：

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

第五阶段：物化落地

在生产环境中，技能并不是以 YAML 的形式存在的，而是被渲染成 Claude Code 可以加载的 SKILL.md 文件：

uv run orkestra sync

这条命令会：

读取所有技能的 YAML 定义
通过 Jinja 模板渲染它们
把 SKILL.md 文件写入 .claude/skills/
按 K 层级（foundations/、identities/、domains/、stacks/、project/）组织

最终的输出结构：

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

休眠作用域模式

我们最有效的模式之一，是“已采纳但不加载”的技能，我们称之为休眠作用域。

以来自 k-dense-scientific 代码仓库的科学计算技能为例。我们已经采纳了 120 多项技能，涵盖生物信息学、化学、量子计算和临床信息学。但我们的大多数智能体，并不需要分子对接或基因表达分析。

与其把全部 120 项技能都加载进每一个智能体（把上下文窗口撑爆），我们的做法是：

用一个特定的作用域（例如 bioinformatics）来采纳这些技能
让它们保持休眠状态——已注册，但不加载
只有当某个智能体声明了那个作用域时，才启用它们

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

这种模式让我们的注册表里可以容纳 466 项技能，而典型的智能体只会加载其中 40 到 60 项真正相关的技能。

技能类型

技能分为三种认知模式：

工作流（Workflow）

有序的流程步骤：“第一步做 X，第二步做 Y，第三步做 Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

准则（Discipline）

行为护栏：“始终 X”“绝不 Y”“优先 Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

检查清单（Checklist）

验证标准：“确认 X”“核实 Y”“检查 Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

质量门禁

每项技能在发布前，都必须通过校验：

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

描述必须在 50 到 400 个字符之间，并带有触发短语（“Use when…”“When you need…”），这样 Claude Code 才知道什么时候该建议使用它们。

我们会持续进行校验：

uv run orkestra validate --show-warnings

供应商生态

我们的 373 项供应商技能来自：

供应商	技能数	领域
AWS Agent	19	云服务
Anthropic	12	文档生成
Cloudflare	8	边缘计算
Supabase	5	数据库
k-dense	100+	科学计算
silvainfm	4	数据科学
Java Developer Kit	45+	Spring/Java
Vercel	1	浏览器自动化

每个供应商源都在 metadata.yaml 中声明：

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

当 orkestra sync 运行时，供应商技能会以各自的供应商命名空间，被符号链接进 .claude/skills/vendor/。

我们学到了什么

挑剔是值得的。 采纳一切看起来有用的东西，诱惑力很大。但每一项技能都要消耗 Token。每项技能平均消耗 2,834 个 Token，一旦臃肿起来，伤害来得很快。我们 13% 的采纳率，让智能体保持精简。

结构成就可发现性。 K 层级体系不只是一种组织方式，更关乎可移植性。K0 技能可以在任何地方复用；K4 技能则是有意设计成特定于项目的。这种清晰度，能帮助人类和智能体都找到自己需要的东西。

休眠作用域能带来规模。 你可以采纳数百项技能，而不必把它们全部加载进来。作用域让你能构建一份全面的注册表，同时让每个智能体的上下文窗口保持在可控范围内。

采纳时的修改必不可少。 原始的供应商技能，很少能直接契合你的系统。吸纳流程——添加元数据、分配层级、充实标签——让外部技能能够在内部真正发挥作用。

挖掘是持续不断的。 3,500 这个数字还在不断增长。新的供应商代码仓库不断出现，社区模式不断涌现，内部工作流不断沉淀固化。这个循环永不停止。

接下来的计划

我们正在推进几项改进：

自动化差距检测：当某个常见的智能体失败，原本可以被一项尚未采纳的技能解决时，发出提醒
技能弃用工作流：为退役那些已被取代或不再使用的技能，建立正式流程
跨技能依赖：明确声明技能之间的前置依赖关系
使用情况分析：追踪智能体究竟真正调用了哪些技能，而不只是加载了哪些

技能挖掘循环是一种基础设施，它并不光鲜亮丽，但正是它，让 41 个智能体能够在遵守上下文限制的同时，连贯一致地驾驭 466 项能力。

这就是 3,500 如何变成 466 的故事。不是靠忽略掉 3,000 个，而是靠系统性地评估它们，只采纳真正管用的那些。

想看看这套技能系统的实际运作？查看 uv run orkestra skills list，探索我们当前的注册表。

渐进式披露：透视智能体系统的 CLI 窗口

Tue, 20 Jan 2026 00:00:00 GMT

本文中的数字反映的是发布时（2026 年 1 月）的系统状态。如需查看最新数据，请参阅我们的团队页面。

智能体系统在设计上就是不透明的。它们做决策、调用工具，在数十个专家之间协调工作。但当出了问题——或者你只是单纯想弄清楚正在发生什么——你该往哪里看？

答案是渐进式披露：一个分层的界面，恰好在你需要的时候，精确地展现出你所需要的那部分复杂度。

不透明问题

一套现代智能体编排系统，可能拥有：

40 多个各有专长的专家智能体
700 多项技能，涵盖内部自动化和供应商集成
470 多条塑造行为的架构决策
数十个提供外部能力的 MCP 工具服务器

这种复杂性是有意为之的。智能体需要访问丰富的上下文——领域知识、代码智能、数据库 Schema——才能做出好的决策。但正是这种丰富性，带来了一个可见性问题。

你怎么知道该由哪个智能体来处理数据库迁移？是哪些决策塑造了搜索系统的排序行为？架构顾问又能访问哪些工具？

没有结构化的访问方式，你就只能去读源代码，或者祈祷文档是最新的。

作为一种架构的渐进式披露

渐进式披露不只是一种 UI 模式，它是一条架构原则：把信息分层组织，一层比一层深入，让用户可以在回答了自己问题的那一层停下来。

对智能体系统而言，这转化成了深度逐级递增的 CLI 命令：

层级	命令	回答的问题
1	`orkestra system status`	一切都健康吗？
2	`orkestra agents list`	有哪些智能体存在？
3	`orkestra agents info <name>`	这个智能体做什么？
4	`orkestra decisions search`	它为什么是这样运作的？
5	Maguyva MCP 工具	把代码给我看看。

每一层都回答了一个自然而然会引出的追问。你很少需要直接跳到第 5 层。

第一层：系统健康度

第一个问题永远是：一切都在正常运作吗？

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

一条命令，四个数字。足以知道系统已经配置妥当，各个注册表也已经填充了数据。

如果智能体数量意外下降，或者技能加载失败，你会最先在这里看到。不需要一头扎进日志里去挖。

第二层：智能体清单

一旦你知道系统是健康的，下一个问题就是：有哪些资源可用？

$ orkestra agents list

这会返回结构化数据——智能体名称、描述、模型偏好、领域覆盖范围。输出默认是 JSON，便于你将其通过管道传给 jq 来进行筛选：

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

想找能处理数据库相关工作的智能体？搜索命令可以帮你缩小范围：

$ orkestra agents search "database"

这会扫描名称、描述和能力，让你不必读完 40 份智能体定义，就能找到合适的专家。

第三层：深入了解智能体

找到了一个看起来相关的智能体？info 命令会把一切都展现出来：

$ orkestra agents info architecture-advisor

输出内容包括：

元数据：名称、类别、模型偏好、描述
领域：这个智能体覆盖哪些知识领域
身份：性格特质（architect、strategist、knowledge-architect）
工具指南：哪些工具文档被注入到了上下文中
工具：这个智能体可用的完整 MCP 工具列表

下面是你会看到的内容示例：

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

这会准确地告诉你这个智能体能做什么，不需要去看源代码。

第四层：决策考古

智能体的行为，遵循着已经记录在案的决策。当你需要理解某件事为什么是这样运作的，决策注册表就是那个唯一可信的来源。

$ orkestra decisions search "agent"

这会返回匹配的架构决策：

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

每一条决策都有完整的溯源信息——它是何时做出的、为什么、权衡过哪些取舍、哪些提交实现了它：

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

这是一份始终保持最新的架构文档，因为它是从提交记录中挖掘出来的，而不是靠人工手动维护的。

第五层：直接的代码智能

当你需要看到真正的实现——而不只是关于它的元数据——Maguyva 的 MCP 工具能提供直接访问。

在一个智能体会话内部：

mcp__maguyva__intelligent_search
  query: "agent context loading"

这会在语义、文本和 AST 搜索之间自动路由，找到相关代码。对于特定的符号：

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

对于依赖分析：

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

这些不只是 grep 的替代品，它们具备图谱感知能力、经过语义索引，并且和驱动智能体本身的那套代码智能是同一套系统。

跨注册表的统一搜索

有时候你并不知道答案藏在哪个注册表里。统一搜索会覆盖所有的注册表：

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

在五个注册表中找到了 254 条匹配。摘要会告诉你该深入哪里去看。去掉 --summary 可以获得详细结果，或者加上 --limit 5 来让输出保持在可控范围内。

为什么这很重要

渐进式披露不只是为了方便，它改变了你与复杂系统互动的方式。

调试变得可控。 当一个智能体做出意料之外的决策时，你不需要在日志里翻来翻去。你可以检查它能访问哪些工具（agents info）、哪些决策塑造了它的行为（decisions search），需要的话再去追溯具体实现（intelligent_search）。

上手速度加快。 新加入团队的成员不需要读完整个代码库，他们可以从 system status 开始，用 agents list 去探索，只有碰到自己不理解的东西时，才需要深入下去。

文档始终保持最新。 因为 CLI 读取的，和配置智能体所用的，是同一批注册表，所以输出总是准确的。文档所说的和系统实际的行为之间，不存在漂移。

作为界面的 CLI

我们本可以搭建一个 Web 仪表盘，本可以写一份详尽的文档。但我们选择打造了一个直接读取唯一可信来源的 CLI。

CLI 有它的优势：

可组合：可以把输出通过管道传给 jq，与脚本集成
可编写脚本：能自动化检查、生成报告
快：没有页面加载，没有身份验证流程
准确：读取的是真实的配置，而不是某个缓存版本

对于正确性比美观更重要的系统来说，CLI 才是赢家。

构建你自己的渐进式披露

如果你正在构建智能体系统，不妨想一想用户会如何检视它们：

从健康检查开始。 用一条命令，告诉你事情是否在正常运作。
提供清单视图。 在解释某样东西做什么之前，先列出有哪些东西存在。
支持有针对性的查询。 在规模面前，搜索胜过浏览。
暴露溯源信息。 让用户能把决策追溯回它们的源头。
接入代码智能。 最终，用户总是需要看到实际的实现。

每一层都回答了一个后续的追问。请按使用频率来构建它们——大多数用户会在第 2 层或第 3 层就止步了，只有资深用户才会一路走到第 5 层。

目标不是把一切都暴露出来，而是恰好在需要的时候，暴露出恰好需要的那部分。这就是把渐进式披露应用到智能体架构上的样子。

基准事实：把 AI 智能体锚定在现实之中

Tue, 13 Jan 2026 00:00:00 GMT

本文中的数字反映的是发布时（2026 年 1 月）的系统状态。如需查看最新数据，请参阅我们的团队页面。

AI 智能体的能力相当出色，它们能推理、能综合、能生成。但它们有一个根本性的弱点：会编造东西。不是出于恶意，而是自信满满地编造。一个智能体可能会凭空发明并不存在的 API 参数，引用从未被定义过的配置，或者套用训练数据里的某种模式——而这种模式恰恰与你真实的架构相矛盾。

标准的应对办法是“给智能体更多上下文”。但上下文本身也可能是自相矛盾的：文档会与实现产生偏差，注释会撒谎，甚至代码本身，如果脱离了对意图的理解去阅读，也会产生误导。

我们需要一种更明确的东西——一种无法被忽略、也无法被曲解的东西，一种能把智能体锚定在可验证现实之上的东西。

我们把它称为基准事实。

什么是基准事实？

一条基准事实，是一条智能体必须遵守的、明确的、带版本的事实陈述。它不是文档，也不是注释，而是系统中的一等实体，具备：

唯一标识符（例如 GT-MAG-015 或 GT-MAG-036）
生命周期状态（current、tentative 或 deprecated）
作用域（全平台、特定包，或限定在某个领域内）
证据（能证明该陈述的文件路径、URL 或引用）
智能体指引（明确的“该做”与“该避免”指示）

下面是一个来自我们 Maguyva 代码智能平台的示例：

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

这不是散文，而是一份契约。当智能体遇到这条基准事实时，它就知道：

默认行为是确定性的（返回空结果，而不是模糊猜测）
存在具体的参数（find_similar、exact_match），各自有明确定义的行为
证据存在于可以核实的具体文件中
该陈述是在某个具体日期被核实过的

一份基准事实注册表的结构

基准事实存放在 ai_assets/reference/ground_truths.yaml 下的 YAML 注册表中。每个包或领域都可以拥有自己的注册表。其结构如下：

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

这份注册表包含关于集合本身的元数据、用于生成文档的渲染配置，以及陈述内容本身。每条陈述都遵循一套由 Pydantic 模型校验的严格 Schema:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

智能体如何访问基准事实

基准事实通过多个渠道对外暴露：

1. 渲染后的文档

orkestra sync 命令会把 YAML 注册表转换成可读的 Markdown:

uv run orkestra sync

这会生成 GROUND_TRUTHS.md 文件，并被纳入智能体的上下文中。渲染后的输出会按状态和类别对陈述进行分组：

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI 搜索

拥有 Shell 访问权限的智能体，可以通过编程方式搜索基准事实：

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

搜索函数会在多个字段上按加权相关度为匹配结果打分：

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. 上下文组合

当智能体从 YAML 定义渲染出来时，它们的上下文可以引用基准事实注册表：

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

这确保了相关的基准事实，会在智能体开始工作之前就已经加载完毕。

基准事实的分类

纵观我们的各个注册表，基准事实大致可以归纳为几种模式：

产品原则

界定产品是什么、不是什么的约束：

“Maguyva 相对于用户代码仓库是只读的；唯一不可重建的资产是付费的 Embedding 缓存。”（GT-MAG-001）

架构边界

职责归属何处、为什么如此划分：

“Pipeline 与 Maguyva 之间的边界是刻意设计的：Pipeline 是可复用的，Maguyva 承载特定于代码的逻辑，而 CQRS 把流水线阶段的写入和服务端读取分离开来。”（GT-MAG-006）

反幻觉规则

让工具契约保持确定性、而非靠推断的明确规定：

“模糊符号匹配需要通过 find_similar=true 主动开启。默认行为对不存在的符号返回空结果；exact_match=true 强制执行严格匹配，并禁用所有模糊回退。”（GT-MAG-015）

质量门禁

必须持续维持的标准：

“对共享基础设施（post_filters.py、关系提取器、共享处理器）的改动，提交前必须通过全量清单生成，针对所有支持的语言进行验证。仅针对单一语言的验证，对共享代码来说是不够的。”（GT-MAG-036）

代码模式

实现层面的要求：

“在异步上下文中处理 CPU 密集型工作时使用 asyncio.to_thread()；已废弃的 loop.run_in_executor() 模式不应再用于新代码。”（GT-MAG-018）

基准事实的生命周期

基准事实并非一成不变，它们会经历一个明确定义的生命周期：

Tentative（暂定）

一条正在评估中的拟议事实。该陈述会被记录下来，但仍可能发生变化：

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current（现行）

一条已被核实、智能体必须遵守的事实。其证据已经过验证：

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated（已废弃）

一条不再适用的事实。出于历史参考的目的被保留下来，并附有指向其替代内容的指引：

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

为什么不干脆只用文档？

文档服务于另一个目的：它负责解释，负责教学，可以是含糊的，可以使用“通常”“一般来说”这类限定词。

基准事实不能含糊。它们是断言，要么适用，要么不适用。

来看看这种区别：

文档：“当找不到某个符号时，API 通常会返回空结果，不过在某些配置下可能会启用模糊匹配。”

基准事实：“默认行为对不存在的符号返回空结果；exact_match=true 强制执行严格匹配，并禁用所有模糊回退。”

第一种说法，对正在学习这套系统的人类很有帮助；第二种说法，对正在做决策的智能体是可以直接采取行动的。

智能体指引：该做与该避免

一些基准事实会包含明确的智能体指引：

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

这消除了歧义。读到这条内容的智能体，不仅知道什么是事实，还知道这个事实意味着该采取什么行动。

验证与维护

基准事实需要持续维护。我们会追踪：

last_verified：上一次有人确认该陈述仍然成立的时间
evidence：能证明该陈述的文件（可以核实其是否存在）
source：这条事实的来源（CLI 检查、架构评审，或事后复盘所得的教训）

如果一条基准事实的验证日期已经过时，或者证据链接已经失效，这就是一个需要排查的信号——要么这条事实依然成立、只是需要重新核实，要么现实已经发生了变化、这条事实需要更新。

来自生产环境的真实示例

安全边界

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

这条基准事实，防止了一整类会破坏产品的、方向搞错了的“安全改进”。

提取阶段的准确性

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

这是一条来自痛苦经验的教训。智能体曾经会通过添加仅作用于校验器的过滤器，来“修补”失败的语言包，让测试框架看起来更绿了，但线上真正运行的 Maguyva 提取器，依然在产出错误的边。这条规则强制把修复推回真正的路径上：YAML 配置、查询，或处理器本身。

多层过滤

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

这防止了智能体在错误的位置添加过滤器——这是一个常见的错误，曾经导致过准确率的回归。

与编排系统的集成

基准事实是一套更广泛上下文体系中的一层：

架构决策（ADR） —— 记录我们为什么选择方案 A 而非方案 B
基准事实 —— 陈述此刻确凿为真的事实
领域模式（Domain Patterns） —— 描述如何把事情做对
反模式（Anti-Patterns） —— 描述应该避免什么、为什么要避免

在系统中工作的智能体，能够访问全部这四层。基准事实提供事实层面的锚点，决策解释历史脉络，模式指导具体实现，反模式则警示可能踩到的陷阱。

衡量成效

自从引入基准事实以来，我们观察到：

“修复那个基于幻觉的修复”这类循环变少了
当事实清晰时，智能体的决策会更有把握
PR 评审质量提升了，因为预期变得明确
新智能体（以及新人类）的上手时间缩短了

维护基准事实所投入的成本，换来了更少的调试和更清晰的系统边界。

快速上手

要为你的系统添加一条基准事实：

在你的包的 ai_assets/reference/ 目录下创建一个 ground_truths.yaml
定义元数据和渲染配置
按照 Schema 添加陈述内容
运行 uv run orkestra sync 生成文档
把这份注册表纳入智能体的上下文组合中

先从那些最容易引起混淆的事实、或者最常被违反的约束入手，那些才是你价值最高的基准事实。

结语

AI 智能体会产生幻觉，这是它们的天性。但我们可以创造出这样的环境：幻觉被约束住，某些事实是不容商量的，智能体可以拿自己的假设去对照已验证的现实。

基准事实并非一个完整的解决方案。它们需要维护，可能会过时，也会给开发流程增加一些开销。

但它们提供了一样宝贵的东西：一套人类和智能体都能信任的、共享的事实词汇表。在一个智能体日益深度参与软件开发的世界里，这个共享的基础变得至关重要。

另一种选择，是让智能体不断自信满满地犯错、再让人类不断去纠正，循环往复。基准事实打破了这个循环，让纠正变得明确、持久。

你的智能体值得知道什么是真的。那就告诉它们。

Orkestra：大规模编排 AI 智能体

Tue, 06 Jan 2026 00:00:00 GMT

本文中的数字反映的是发布时（2026 年 1 月）的系统状态。如需查看最新数据，请参阅我们的团队页面。

当我们开始用 Claude Code 构建东西时，我们撞上了一个每个使用 AI 编码助手的团队迟早都会遇到的问题：一个智能体，没办法把所有事情都做好。

你可以用提示词把一个智能体变成数据库专家，或者安全审计员，或者前端工程师。但一旦你要求它同时身兼这三者，质量就会打折扣。上下文被稀释，指令彼此冲突，智能体就变成了一个万事通，却样样平庸。

所以我们打造了 Orkestra。

什么是 Orkestra?

Orkestra 是一套面向 Claude Code 及同类 AI 编码工具的智能体编排系统。它在一个编排器之下，协调多个各有专长的专家智能体，由编排器把工作分派给合适的专家。

可以把它想象成一家面向 AI 智能体的人才中介机构：编排器接到一个任务，判断该由哪个专家来处理，再带着合适的上下文进行委派。工作完成后，结果会流回编排器，进行汇总整合。

这些数字很能说明问题：

组成部分	数量
专家智能体	46
可复用技能	466
身份原型	27
思维模式	11
沟通风格	10
知识领域	21

角色系统：智能体的“龙与地下城”

Orkestra 背后的核心洞见是：智能体的行为，是由三种可组合的基本要素涌现出来的：

身份（Identity） 定义了智能体是什么。架构师设计系统结构，调试者把故障追溯到根本原因，守护者确保合规并维护安全边界。我们有 27 种可以混搭的身份原型。

思维模式（Mindset） 定义了智能体如何思考。分析型思维把断言建立在证据之上，并量化不确定性；怀疑型思维质疑假设、主动寻找反证；探索型思维拥抱模糊性，尝试多种路径。

风格（Style） 定义了智能体如何沟通。技术型风格会给出精确数值、引用具体文件；简洁型风格砍掉冗言、直接给出答案；圆融型风格在坦诚与得体之间取得平衡。

一个智能体会把这些要素组合起来：

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

这样的组合，创造出了一个能设计系统（architect）、能跨领域串联知识（knowledge-architect）、能设定战略方向（strategist）、以证据和数据为思考依据（analytical）、并且沟通不带废话（concise）的智能体。

真正的威力在于组合爆炸：27 种身份 × 11 种思维模式 × 10 种风格，能产生近 3,000 种可能的智能体人格。但你只需要定义那些对你的工作真正重要的组合。

技能：可复用的能力模块

技能（Skill）是智能体可以调用的知识和工作流。它们遵循一套按作用域分层的体系：

层级	名称	作用域	示例
K0	基础（Foundations）	通用方法论	测试先行原则、基于证据的任务完成
K1	身份（Identities）	基于角色的工作流	CLI 界面标准、性能优化手册
K2	领域（Domains）	特定领域的知识	数据库迁移模式、身份验证校验
K3	技术栈（Stacks）	特定技术相关	Cloudflare 部署、Supabase 运维
K4	项目（Project）	仅限本代码库	特定于项目的工作流与约定

技能是懒加载的。智能体在启动时只会看到技能的名称和描述，完整的技能内容只有在被触发时才会加载。这让上下文保持精简，同时让数百项技能依然可被发现。

每项技能都包含：

明确的触发条件（“在迁移数据库 Schema 时使用”）
一步步的操作指引
该工作流允许使用的工具
成功标准与失败恢复路径

我们注册表中的 466 项技能，覆盖的范围从 Git worktree 隔离，到 Web 研究工作流，再到部署健康度验证，应有尽有。

为什么编排很重要

单智能体架构很快就会碰壁：

上下文稀释。 20 万 Token 的上下文窗口听起来很大，但一旦你把数据库 Schema、API 文档、测试 fixture 和领域知识都塞进去，它就没那么大了。专家智能体可以只处理有针对性的上下文。

指令冲突。 让一个智能体既“要全面又要快”，又“要什么都验证、但又别过度设计”，会产生相互牵制的要求。专家智能体通过明确的作用域来协调这些要求。

专业深度。 一个万事通智能体，对什么都只懂一点皮毛；而一个搭配了正确身份和技能的专家智能体，能够深入了解自己的领域。

Orkestra 实行的是扁平化编排：一个编排器协调多个专家，专家不能再衍生出子专家。这既避免了复杂度爆炸，又保留了并行工作的能力。

编排器可以调用的有效容量高达 220 万 Token：它自己的 20 万 Token 窗口，再加上 10 个并发子智能体、每个各 20 万 Token。那些足以耗尽单个智能体的工作，在这支舰队上却能从容运行。

渲染流水线

智能体的定义存放在 YAML 中，而 Claude Code 读取的是 Markdown。Orkestra 用一条确定性的渲染流水线，弥合了这道鸿沟：

YAML Registries → Jinja Templates → .claude/agents/*.md

运维人员编辑 YAML 源文件，运行 orkestra sync，渲染后的 Markdown 就会出现在 .claude/agents/ 中，Claude Code 随即拾取这些变化。

这种分离服务于不同的受众：

YAML 源文件 包含生命周期元数据、标签、校验规则，以及供工具使用的弃用提示
渲染后的 Markdown 只包含模型真正需要的内容：描述、工具、技能和行为指引

这条流水线会把身份、思维模式、风格和技能，组合成一份连贯统一的提示词。一个 architect-analytical-concise 组合的智能体，得到的系统提示词，会和一个 debugger-skeptical-technical 组合的智能体截然不同，即便它们共享了一些底层技能。

领域知识：四文件模式

每个知识领域都遵循一套一致的结构：

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

这套结构是为智能体的上下文加载而设计的。一个处理身份验证工作的智能体，会加载 authentication/patterns.md 来获取指引，加载 authentication/anti-patterns.md 来避开已知的坑。这些文件的大小经过权衡，既足够聚焦、能派上用场，又足够全面、具备权威性。

我们维护着 21 个顶级领域，包括数据分析、身份验证、数据科学、基础设施、机器学习、性能和安全等等。每个领域都可以拥有子领域，以获得更细的粒度。

价值观：运行的底层系统

所有智能体共享同一套基础价值观，定义了它们该如何运作：

简单优先。 使用能奏效的最简单方案，只有在有充分理由时才增加复杂度。

修复根本原因。 绝不绕过故障去打补丁。如果一条流水线失败了，就去调试这条流水线；如果一个测试失败了，就去修复代码或者修复测试本身。

基于证据。 把每一个论断标记为“已验证”（附带基准数据）或“估计”（附带假设条件）。检测到某种模式，不等于确认了问题的存在。

上下文经济学。 MCP 工具的开销只占上下文的 0.1%；每次文件读取的开销是 2%。先运用领域专业知识，再去探索代码。

这些价值观会通过渲染流水线，传播到每一个专家智能体身上。任何智能体都无法靠组合方式绕开它们。

CLI：控制平面

Orkestra 内置了一个用于管理智能体生态的 CLI:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

这个 CLI 是“有哪些智能体存在、它们各自拥有哪些技能、系统是否健康”这些信息的唯一可信来源。它会在同步之前先运行校验，尽早捕获问题。

关于开源的考量

我们打造 Orkestra，是为了解决自己的问题：在一个复杂的代码库中，大规模地协调 AI 智能体。但我们发现的这些模式，并不是我们这个领域独有的。

角色组合系统（身份 + 思维模式 + 风格），适用于任何需要定义智能体人格的团队。

技能分层体系（K0 到 K4），提供了一套按作用域组织可复用能力的思维模型。

渲染流水线模式（YAML 源文件 + 模板 + 生成产物），把工具层面和模型消费层面的关注点分离开来。

扁平化编排模型（一个协调者，多个专家），既避免了复杂度，又保留了并行能力。

Orkestra 是否会走向开源，取决于这些模式对其他用 Claude Code 构建产品的人是否有价值。如果你也正撞上我们描述的这些墙，这套架构或许能帮上忙。

我们学到了什么

打造 Orkestra 让我们明白：编排的重点，不在于让智能体变得更聪明，而在于让它们变得更专注。

一个拥有完美指令的单一智能体，依然会耗尽上下文。一个拥有全部技能的单一智能体，依然会搞不清该用哪一项。一个试图无所不能的单一智能体，只会在每个地方都产出平庸的结果。

四十个专家，每个都精通自己的领域，由一个懂得何时该委派的编排器来协调——这就是我们交付产品的方式。

数字本身不如架构重要。你可能需要五个智能体，也可能需要五十个。原则始终不变：组合胜过单打独斗的能力，专精胜过泛泛而谈，协作胜过个人英雄主义。

Orkestra 驱动着 Maguyva——我们的代码智能平台——背后的整个智能体生态。想了解更多？欢迎联系我们的团队。