ultraindex：AI Agent 工具实践指南

实际看ultraindex，先要确认它的用途：将整个存储库（代码 + 文档）索引到可导航的 AI-analyzed 百科全书中 - 映射 + 每个模块条目 + 类型化链接图 - 因此 AI 在巨大的代码库中工作而无需填等相关能力。软件开发里，依赖、接口和异常处理往往比主路径更影响采用。我会在隔离分支完成一个可回滚的小任务，检查安装步骤、接口契约、测试结果和错误信息。它适合需要可检查开发流程而非单次演示的工程师；采用前仍要看维护状态和试跑结果。

超指数

验证每项声明，包括长答案

verify --answer ANSWER.md --repo . --complete --batch-size 40 写完整 VERIFY.todo.json 并列出其中的有界 VERIFY.batch-NNN.todo.json 文件 JSON/Markdown 输出。裁决列出的当前批次，然后折叠它们 带有 verify --answer ANSWER.md --apply verdicts-1.json,verdicts-2.json 的路径。 重新生成验证会删除该答案的过时生成批次， 包括切换回采样模式时；不相关的文件被保留。 在重新生成工作列表之前，将裁决保存到单独的裁决文件中。 拒绝重复的对。带有 check --out .ultraindex --answer ANSWER.md 的门 --repo 。 --semantic --complete：任何缺失的对，unreadable/stale 证据或 实质性未引用散文失败，甚至超过 40 对。 JSON 报告预期和 覆盖计数。单独的工作列表生成永远无法证明这一主张得到支持。

默认验证采样仍为 40 对。 --complete 与 --max-verify； --batch-size (1–1000) 需要 --complete。最后的登机口检查 实时答案和来源，无论提交批次中的元数据如何。 完整模式还拒绝空引用的源代码行并保留每个标准化的代码行 完整的索赔，因此旧的 400 个字符的抽样判决无法证明更长的时间 声明或更改的后缀。默认采样声明截断未更改。

祈求

默认为手动。 ultraindex 在您要求时运行：Codex 中的 $ultraindex， 克劳德代码中的 /ultraindex 或 OpenCode。代理永远不会自行启动它，并且 CLI 命令不变。每个主机的一项设置使其自动化 - 请参阅 手动或自动。

代码索引 告诉您东西在哪里。 ultraindex 告诉您它们的含义并证明了这一点。

AI 代理在代码索引之上写入经过验证的知识层 引擎：一个持久的、每个模块的百科全书，解释了存储库意味着什么，其中每个 句子必须引用真实来源，并且每次引用都经过机械检查。

搜索答案的问题的答案已在代码中。 为什么会这样 模块存在吗？如果错误的话，产品会出现什么问题？——没有人写过这个 下来。模型必须解决这个问题，然后它必须生活在某个地方 在会话、上下文窗口和下一次重构中继续存在。

这就是 ultraindex 构建的：一个你逐个加载的“分层”工件， 模型拥有其散文区域，而工具拒绝让它伪造。

.ultraindex/
  INDEX.md              # the map — always-loadable: summary, hubs, bridges, tests, module table
  encyclopedia/
    <module>.md         # per-module entry: business view + code view + links + sources
    _orphaned/<m>.md    # prose of a module that disappeared — kept, never deleted
  graph.json            # the full typed link-graph (file + module level)
  symbols.json          # symbol → definition sites + referencing files (`symbols` cmd)
  graph.mmd             # a Mermaid module diagram
  manifest.json         # per-file hashes (staleness) + merge bookkeeping
  cache.json            # incremental-build extraction cache (regenerable; gitignore for committed indexes)
  vectors.json          # optional per-module embeddings (`embed`, keyless)
  orchestration/        # optional multi-agent fan-out (`orchestrate`): workflows, contracts, RUNBOOK

两个仓库，一个边界

ultraindex 建立在 代码索引 和 供应商逐字记录 — src/vendor/codeindex-engine.mjs，由 sha256 字节固定 在 engine.meta.json 中，在每个代码索引版本上自动重新固定。的 两个项目之间的划分是一种规则，而不是一种习惯：

• codeindex 是引擎，并且没有模型处于循环中。 回购协议，提取符号（tree-sitter 代表 13 种语言，正则表达式代表 15 种语言）， 解决跨 9 个生态系统的导入、类型化链接图、PageRank 和 中间性、Louvain 社区、测试→代码图、BM25 和无钥匙 确定性语义搜索、SCIP 输出、存储库映射以及其自己的 MCP 服务器。 确定性、零依赖、无密钥。 如果某个功能返回相同的值 回答 AI 是否存在，它属于 codeindex。

• ultraindex 的存在只是因为模型处于循环中。 它的整个表面 是关于模型对存储库的理解以及这种理解是否 可以信赖：百科全书（比任何上下文都持久的持久记忆 窗口），接地证据组件（dossier，ask），引文和 支持检查门（check、verify）、丰富工作队列（status）、 多智能体扇出（orchestrate）和技能提示层。 什么也没有 如果没有 LLM 存在，这里仍然有意义。

我们坚持这条规则的结果是：当 ultraindex 需要一个 确定性能力，它被贡献给 codeindex 的上游而不是 在这里重新实现。 这就是为什么 ultraindex 没有搜索引擎，没有解析器， 没有自己的图形代码，为什么它很小，需要一个下午才能阅读，以及 为什么“重新固定引擎”是一个无聊的自动化事件而不是合并。

你想要哪一款？

为什么不只是 codeindex 或其 MCP 服务器？

使用它。 codeindex 的 MCP 服务器非常出色，ultraindex 配备相同的引擎 下面：26 个确定性工具回答“某物在哪里”和“是什么” 存在*。代码已经回答了每个问题，它会回答 - 更快更 比任何型号都便宜。

ultraindex 适用于代码中没有答案的问题：

“为什么这个模块存在，如果它错了，什么会破坏？” 那就是 encyclopedia/<slug>.md。生成的区域是引擎的并被重建 每次； ui:human 区域是您的 — 在每次重建中都保留， 跨模块重命名迁移，并且从未删除（删除的模块的散文是 保存在 encyclopedia/_orphaned/ 下）。

“这个解释真的是真的吗？” 返回源的工具无法判断 您是否支持模型关于它所写的段落。 check 任何无法解析的 [file:line] 都会失败 - 以及装饰性引用 代码围栏内不算在内。 verify 更进一步：它发出一个声明↔引用 工作列表，模型根据真实摘录判定每一对，以及门 在重新阅读每个摘录的同时重新减少原始 verdicts[] 的判决 来自实时存储库 - 因此经过修改的 VERIFY.json 或漂移的源会失败 比通过。

“模型下一步应该做什么，按什么顺序？” status 是 工作队列按解释购买最大导航价值的位置排序； orchestrate 将其分散到具有真实合同和顺序的子代理 后备。检索没有未完成工作的概念。

搜索检索。 ultraindex 累积 — 并拒绝累积 任何它无法证明的事情。

安装

它作为 一个 skills.sh 代理技能 提供，并具有承诺的 零依赖包：

npx skills add maxgfr/ultraindex             # this project
npx skills add maxgfr/ultraindex --global    # user-level, every project

该技能安装独立（其 SKILL.md + 工作流程参考 + 提交的捆绑包），因此它单独与 node 一起运行 - 没有 npm install，没有 API 密钥。 与 Claude Code、Codex 和 skills CLI 支持的其他代理配合使用。

根据情况自动路由的技能：没有索引→它建立一个；陈旧索引 → 它重建（你的散文得以幸存）；任务或问题 → 它导航、打开 仅索引指向并以 grounded 回答的文件， 引文检查分析（dossier/ask 向代理提供真实来源； check 拒绝任何无法解析的引用）。

将其用作 MCP 服务器

两台服务器，与 README 的其余部分位于同一边界。 代码索引 为引擎的 26 个回购分析工具提供服务——其中包括：

claude mcp add codeindex -- codeindex mcp      # brew install maxgfr/tap/codeindex

ultraindex 服务于顶层的知识层——事物的含义以及 保持诚实的协议。不同的工具，不同的名称，不冲突 当客户同时注册时：

# stdio — the default, and what Claude Code / Claude Desktop / Cursor expect
claude mcp add ultraindex -- node /abs/path/to/scripts/ultraindex.mjs mcp

# or over HTTP, on loopback
node scripts/ultraindex.mjs mcp --transport http --port 7338
claude mcp add --transport http ultraindex http://127.0.0.1:7338/mcp

克劳德桌面（claude_desktop_config.json）和光标（.cursor/mcp.json）：

// Claude Desktop takes stdio servers only — a remote URL here will not work.
{ "mcpServers": { "ultraindex": { "command": "node", "args": ["/abs/path/to/scripts/ultraindex.mjs", "mcp"] } } }
// Cursor, HTTP:
{ "mcpServers": { "ultraindex": { "url": "http://127.0.0.1:7338/mcp" } } }

它服务于所有三个 MCP 原语，因为技能由三部分组成：引擎 （工具）、方法（提示）以及该方法引用的文档 到（资源）。只给客户提供工具的客户必须发明其余的工具。

工具

十二个阅读工具。 ultraindex_map 是第一个到达的：

--allow-write 另外公开了 ultraindex_build 和 ultraindex_embed， 写入您的存储库的两个工具。它们默认处于关闭状态，因此 自动批准代理无法联系到他们 - 这也是只读行的位置 是在你的树上绘制的，而不是在工具是否接触磁盘上绘制的。

在启动时传递 --repo <dir> 将服务器专用于一个项目 — repo 然后在每个工具上都成为可选的。

提示——工作流程，而不仅仅是工具

每个人都承担着整个技能所依赖的分工：发动机拥有 代码视图，您拥有业务视图，并且每个声明都引用 [file:line]。

资源——技能自己的文档

SKILL.md 和所有五个 references/*.md 均在 skill:// 下服务，读出 在请求时磁盘 - 因此文档修复到达每个客户端而无需 重建。没有有效负载安装的构建仍然可以为每个工具提供服务， 资源列表为空。

值得了解的三件事：

• 每个读取工具都需要一个索引。 每个存储库运行一次 ultraindex_build (--allow-write);之后是增量的。没有一个，工具就会失败 命名缺少的步骤，而不是使用“未定义”。
• build 和 embed 按索引目录进行序列化。 两者都读取、合并 并编写相同的文件 - 并且 build 明确保留您的散文 写道，两个交错的调用将会丢失。
• HTTP 传输绑定 127.0.0.1 并拒绝任何其他除非您 通过--allow-remote。该服务器读取本地文件；暴露端口是 为任何发现它的人阅读任何原始的东西。浏览器 Origins 已检查 出于同样的原因。

CLI

ultraindex build   --repo <dir> [--out <dir>] [--include <glob>] [--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--full-hash] [--no-mermaid] [--no-gitignore]
ultraindex find    "<query>" [--out <dir>] [--k <n>]
ultraindex embed   [--out <dir>] [--force]
ultraindex neighbors <file|module-slug> [--out <dir>] [--depth <n>] [--kind <k>]
ultraindex symbols "<name>" [--out <dir>] [--json]
ultraindex impact  <file|module-slug> [--out <dir>] [--depth <n>] [--json]
ultraindex delta   [--base <ref>] [--staged] [--out <dir>] [--repo <dir>] [--depth <n>] [--json]
ultraindex map     [--out <dir>] [--module <slug>] [--json]
ultraindex status  [--out <dir>]
ultraindex dossier <module-slug> [--out <dir>] [--repo <dir>] [--budget <n>]
ultraindex ask     "<question>" [--out <dir>] [--repo <dir>] [--k <n>] [--budget <n>]
ultraindex check   [--out <dir>] [--repo <dir>] [--answer <file>] [--semantic] [--quiet]
ultraindex verify  --answer <file> [--repo <dir>] [--apply <verdicts.json>] [--max-verify <n>]
ultraindex orchestrate [--out <dir>] [--repo <dir>] [--answer <file>] [--phase <name>] [--eco] [--list]
ultraindex grammars [status|pull]

• 构建 — 扫描+（重新）写入索引。幂等：重新生成代码视图 和图表，保留您丰富的散文（甚至通过区域键匹配 模块重命名；真正删除的模块的散文保存在 encyclopedia/_orphaned/ 下）。 增量：重建重用提取内容为 不变（--no-cache 强制完全重新提取）。 --max-files 边界 当达到上限时，扫描和构建警告（从不静默截断）。
• 查找 — 对任务的模块进行排序并打印要打开的精确文件。 默认词法（标识符分割、轻量词干、码域 同义词，IDF 术语权重）；当 vectors.json 时混合词汇 + 语义 存在（如下）。
• 符号 — 定义符号的位置（文件：行、种类、所属模块）和 哪些文件引用它，来自 symbols.json — 精确然后是标识符子令牌 匹配，无需重新扫描存储库。
• 影响 — import/use 边缘上的反向依赖闭包：一切 它传递地依赖于文件或模块（“如果我更改它会破坏什么”）。
• delta — 映射 git diff（--base 与工作树的合并基础，或者 --staged) 到索引：更改的文件 → 封闭符号 → 爆炸半径 → 风险评分审查小组并解释原因（导出的 API 已更改， PageRank-percentile 集线器，爆炸尺寸，测试间隙，令人惊讶的跨社区 耦合，悬挂进口）。需要一个新的索引——当一个索引失败时关闭 自构建以来更改的文件发生了漂移。空 diff 退出 0。
• 嵌入 — build/refresh vectors.json 用于语义 find （可选，无键 并且没有可运行的提供程序 - 见下文）。增量：未更改的模块保持其原有状态 向量。
• 邻居 — 从文件或模块中遍历图形。
• map — 便宜地打印 INDEX.md （或一个模块的条目）。
• 状态 — 丰富工作队列：接下来要丰富哪些模块 （首先是未丰富的，最后是尾部，最先连接的）。
• 档案 — 打印模块的接地数据包（其真正的关键源+图表 邻居），这样您就可以在其条目中写入引用的分析。
• 询问 - 收集有根据的证据（相关模块的真实来源） 问题，因此您可以通过引用来回答它。
• 检查 — 报告陈旧性 + 完整性 + 接地（每个 [file:line] 散文中的引用必须解决）。使用 --answer <file>，验证 而是引用答案；添加 --semantic 来折叠验证门。 非零退出⇒陈旧、损坏或不接地气。
• 验证 — 高保证门上方 check --answer：发出 主张↔引用工作清单，对每项进行裁决（支持/部分/反驳/ 不支持），然后 --apply 将判决减少为 pass/fail — 因此引用 摘录必须实际上“支持”其主张，而不仅仅是解决。
• 编排 — 发出 CURRENT 索引状态的多代理扇出 进入 <out>/orchestration/：每个就绪阶段一个工作流程脚本 (enrich = status 工作队列； verify-answer = 声明↔引用工作列表）， 调度合约，以及连续的 RUNBOOK.md 后备。确定性和 幂等——只要队列发生变化就重新运行它。
• 语法 [状态|pull] — 检查或预热树守护者 wasm 缓存。 build 在首次使用时拉动，因此这仅用于离线或诊断。

默认输出为 <repo>/.ultraindex（gitignored）。使用--out docs/ultraindex 提交 PR- 可审查索引 — 确定性、字节稳定的重建使差异保持较小。

它是如何运作的

供应的代码索引引擎（无模型，无密钥）完成所有机械操作 下面工作。这些都不是在这里创作的——请参阅两个存储库，一个 boundary:

• 扫描 — gitignore 感知行走；每个文件提取 Markdown（标题/ 标题/链接）和代码。符号来自 tree-sitter (AST-exact: real 嵌套、精确类型、结构导出）用于 JS/TS/TSX、Python、Go、Rust、 Java、C、C++、C#、Ruby、PHP。语法 wasms 未在 捆绑：机器上的第一个 build 将它们（~17 MiB）拉入共享 缓存（<XDG_CACHE_HOME|〜/.cache>/codeindex/grammars/<engine>/), sha256 验证，并永久重复使用它们 - 因此默认情况下 AST 精度处于启用状态 下载一次后，技能使用时没有 npm install 并且小得多 安装技能。 离线，还没有缓存 ⇒ build 这么说并索引 使用正则表达式提取器（绝不是静默降级）；预热 ultraindex grammars pull。无论如何，其他语言都使用正则表达式提取器。 桶装再出口、顶级文档评论和本地进口也随之而来。
• Resolve — markdown 相对链接，以及 JS/TS 的本地导入（包括 tsconfig 路径别名 — 甚至 Nx 样式的根 tsconfig.base.json — 以及 工作区包及其 exports 映射 → 存储库内源），Python， Go（多模块 go.mod 包括 replace 指令），Rust （mod/use，跨箱），Java（包→源根映射）， C/C++（#include "..."），红宝石（require_relative/require），PHP （作曲家 PSR-4 + 相对 require）和 C# (using → namespace)。加号 保守代码→代码 use 当一个文件引用另一个文件的边缘时 独特的导出符号，无需导入。未解决的本地目标变成 悬空边缘（浮出水面，从未悄然掉落）； third-party/stdlib 和 资产进口是外部的（无优势）。
• 图 — 类型边（import、call、use、doc-link、保守 mention — 设置 neighbors --kind 过滤器打开）， 文件级别并提升到模块级别；确定性 PageRank 排名 集线器和品牌之间性找到了子系统之间的桥梁， 派生测试→代码映射记录哪些测试覆盖每个模块，以及Louvain 社区标记令人惊讶近乎独特的跨社区耦合。
• 渲染 — 预算 INDEX.md，每个模块条目分为工具拥有的 ui:gen 区域和作者拥有的 ui:human 区域，加上 graph.json / graph.mmd / manifest.json.

然后，接地的 AI 层（此技能，通过代理）添加理解： dossier/ask 手上代理真实源码，里面写的是业务分析/ 机械地引用 [file:line] 和 check 的答案 拒绝任何引用 这并不能解决——反幻觉防护（ultradoc的模型，应用 到本地索引）。代码围栏/内联代码/降价链接内的引用 不算，所以装饰性的引用不能满足大门。为了高保证 回答可选的验证门更进一步 - check --answer --semantic 放弃裁决并驳回其引用的摘录反驳的主张（或者， 一旦得到充分裁决，就不再支持它），而不仅仅是它解决了。的 门不相信任何记录：判决是从原始结果中重新还原的 verdicts[] 每一次检查（篡改的摘要无法通过），每一次裁决 从实时存储库中重新读取摘录，并与之前的摘要进行比较 判断（内容漂移失败），覆盖范围按身份匹配，而不是计数。

当存在时使用 ripgrep（更快）；如果没有它，则使用内置扫描仪。 如果没有 git，清单将忽略提交。未更改的存储库的两个构建 字节相同（除了 manifest.json 的 builtAt 出处时间戳）。

find 是纯词法的，但比子字符串匹配更智能：查询拆分 camelCase/snake_case 标识符（getUserProfile 查找 src/user/profile.ts）， 保守的词干分析器桥接 plural/-ing 变体和小代码域 同义词表桥 auth↔authentication↔login — 所有确定性， 离线，无依赖。

一个经过解释、有根据的答案的衡量成本

evals/token-savings/run.mjs 测量 ultraindex 单独提供的功能。它曾经 将 symbols/impact 与 ripgrep 进行比较 - 但这是检索，即 codeindex 引擎的工作并进行了基准测试 还有。测量 这里将引擎的工作归功于 ultraindex。

现在衡量的是什么：代理人花费的代币达到解释和 成立答案，计算它将读取的每个字节（令牌= ceil（chars/4））， 反对天真的阅读源代码基线。在此存储库上运行：

有两件事故意不讨好：

• 它低估了第一行。 在 185 854 个标记之后，基线已读取 每个文件，但仍然无法说出“为什么”该模块存在——这在任何地方都找不到 来源。该条目在 3 863 中回答了这个问题。
• 在一个小型回购 ultraindex LOSES 上，评估是这么说的。 在固定的 夹具（tests/fixtures/mini-repo，14个小文件）总计为0.43× — 索引的成本比它索引的东西要高。运行打印该判决 而不是隐藏它。如果存储库适合您的上下文窗口，则不需要 这个工具。

接地门被报告为一种能力，而不是一个比率：一个可解析的 引文退出 0，不可解析的退出 1，基线没有 等价的——搜索工具没有任何东西可以检查索赔。发明一个 加速这个项目的存在正是不劳而获的 防止。

一次性成本永远不会合并到一项任务中：索引构建 ~600 ms / 86 输出 此存储库上的代币，加上丰富通行证本身。

用 node evals/token-savings/run.mjs 重现（默认固定夹具； --repo <dir> --module <slug> --module-path <dir> --question "<q>" 重新定位它）。

语义搜索（可选，无键）

词汇搜索无法弥合真正的词汇差距（“发票”与模块 只说“计费”）。可选的语义层嵌入每个模块和 使 find 混合：词汇和语义排名与倒数融合 等级融合。它是严格附加的——没有它，什么都不会改变。

没有 API 密钥，也没有提供者可以站出来。嵌入层属于 到供应商的代码索引引擎； ultraindex 只决定嵌入的内容 — 每个模块一个向量，折叠在你写的散文中，这是一个信号 文件级索引不能有。

ultraindex embed                # pulls the keyless model on first use, writes vectors.json
ultraindex find "invoicing"     # now hybrid — results carry semanticRank

优先级是引擎的：端点>静态>无。更喜欢当地比较富裕的 型号？ codeindex embed serve 打印容器一行；然后设置 CODEINDEX_EMBED_ENDPOINT — 设置它是明确的意图，因此它赢得了 本地模型。

降级是优雅的：端点无法到达 ⇒ 纯词汇结果 + stderr 警告；无 vectors.json ⇒ 纯词法、无声、零网络（删除文件 关闭图层）。当向量漂移过时时，check 发出警告。 再现性： manifest.json 是除 字节相同的重建保证（其 builtAt 时间戳）。 vectors.json 是 内部它位于静态层 - 编码器是一个纯粹的查找表 银彳家的四舍五入和整数排名。仅端点层，其浮点数来自 从服务器，落在外面。

开发

pnpm install
pnpm build        # tsup → scripts/ultraindex.mjs, mirrored into the skill dir
pnpm test         # vitest
pnpm typecheck
pnpm check:build  # asserts the committed bundles are reproducible

发布是通过语义发布（GitHub 发布）进行常规提交驱动的。

手动或自动

ultraindex 提供 仅显式，并且 skills add 以这种方式安装它：它运行 当您调用它时，永远不要在代理愿意时调用它。在 Codex 中使用 $ultraindex， Claude 代码中的 /ultraindex 或 OpenCode，在插件名称空间为前缀时 作为克劳德插件安装。

让代理选择它是每个主机的一个设置，应用于 安装技能副本：

克劳德代码可以在不接触文件的情况下做到这一点：put "skillOverrides": { "ultraindex": "on" } 中的 settings.json，其中 "user-invocable-only" 强制返回手动模式。插件安装忽略 skillOverrides，因此编辑那里的 frontmatter。更新或重新安装 技能会恢复出厂默认设置，因此请稍后重新应用更改。

OpenCode V1 不读取 autoinvoke 元数据。保持手动状态 permission.skill 在 ~/.config/opencode/opencode.json 或项目中 配置，保留无关权限；删除条目或设置 "allow"，是让代理到达它的原因：

{
  "permission": {
    "skill": {
      "ultraindex": "deny"
    }
  }
}

在 OpenCode 1.18.30 上，该规则向代理隐藏技能并拒绝 技能工具加载，而显式 /ultraindex 命令仍然有效。 使用 skills add 安装不会写入此 OpenCode V1 配置。