ultraindex — 构建并导航整个代码仓库的 AI 分析百科全书
在大型代码仓库中,上下文窗口在被填满之前往往来不及找到真正重要的内容。
ultraindex 通过 分工 解决了这个问题:确定性的、零依赖的引擎(node scripts/ultraindex.mjs <command> —— 无需 npm install,无需 API 密钥,运行 --help 查看完整功能)负责机械工作 —— 扫描项目、构建链接图、布局百科全书;你 负责理解工作 —— 基于证据的、带有引用的分析 —— 然后导航结果,而不是阅读整个仓库。
核心规则:
- 引擎拥有代码视图和图(
ui:gen区域)——每次构建都会重新生成;切勿手动编辑。- 你拥有业务视图(
ui:human区域)。build会在重建和重命名时保留你的文字。- 基于证据进行分析,而非凭记忆。 仅根据
dossier展示的真实源代码编写分析,并引用它[file:line],check命令会因任何无法解析的引用而失败 —— 因此不要猜测。- 加载最小内容。 一次只读取一个条目(或一个
dossier)——这是预期的模式,也是每个模块的富化子代理所做的。切勿将graph.json或整个encyclopedia/目录批量加载到上下文中 —— 那将违背目的。
大多数命令都接受 --json —— 当你需要根据结果进行分支判断而不是阅读文字时,请优先使用它。
根据情况选择路径
按以下顺序判断你属于哪种情况,并阅读对应的参考文档以获取详细工作流程:
-
尚无索引 —— 仓库根目录下没有
.ultraindex/或docs/ultraindex/(查找graph.json)。构建它,然后富化顶层模块: 阅读 references/generate.md。 -
存在索引 —— 先检查新鲜度。
node scripts/ultraindex.mjs check --out <index-dir> --json。如果报告过期或损坏,重新运行build(你的文字会保留),然后继续。如果仅更改了与任务无关的文件,你可以继续并注明这一点。 -
用户有一个任务或问题(“X 在哪里”、“Z 如何工作”、“我应该修改哪些文件”)——导航索引,只打开它指向的文件,用经过验证的引用支撑答案: 阅读 references/navigate.md。
-
答案必须是高保证的(审计、安全、正确性至关重要的声明),或者用户要求你验证/判断一个答案 —— 在
check --answer通过后(引用可解析),升级到语义验证门,以便证明每个被引用的摘录确实支持其声明,而不仅仅是不存在: 阅读 references/verify.md。 -
用户要求索引/分析/文档化,或者
status --json显示未富化的枢纽节点且有预算 —— 运行状态驱动的富化循环(dossier → 编写带引用的分析 → check)。在大型仓库上可以并行化:队列中的每个模块分配一个子代理,前提是你的主机支持子代理 —— 阅读 references/generate.md。 -
find总是找不到,或者用户想要语义/更好的搜索 —— 设置可选的嵌入层(docker compose,embed, 混合find): 阅读 references/semantic.md。
典型的首次访问流程为 1 → 5 → 3;再次访问通常是 2 → 3;高保证答案则添加 → 4。
命令速查表
build --repo <dir> [--out .ultraindex] [--include/--exclude <glob>] [--max-bytes <n>] [--max-files <n>] [--no-cache] [--no-mermaid]—— 扫描并(重新)写入索引。幂等;保留已富化的文字。增量式(重用未变更文件的提取结果);如果--max-files截断则会发出警告。--out docs/ultraindex用于可提交、可审查 PR 的索引。map [--module <slug>] [--json]—— 打印 INDEX.md(或一个条目,或模块表格)。find "<query>" [--k <n>]—— 对模块进行排序,打印需要打开的确切文件。默认为词汇搜索(带 IDF 词项加权);当vectors.json存在时则为混合搜索(+ 语义)。neighbors <file|module> [--depth <n>]—— 显示链接到它/从它链接出去的内容。symbols "<name>" [--json]—— 某个符号的定义位置(文件:行、类型、所属模块)以及哪些文件引用了它。对标识符子词元进行模糊匹配。impact <file|module> [--depth <n>] [--json]—— 反向依赖闭包:所有导入或使用该目标的内容。“如果我修改这个,会破坏什么。”status—— 富化工作队列,按照需要富化的确切顺序排列。dossier <slug>—— 一个模块的接地信息包(真实源代码 + 相邻模块;纯文档/配置模块,例如root,不显示代码 —— 改为引用其 README/配置来富化)。ask "<question>"—— 收集接地证据来回答问题。check [--answer <file>] [--semantic]—— 检查陈旧性 + 完整性 + 接地性(引用必须可解析)。非零退出码表示过期、损坏或未接地。--semantic还会折叠验证门(如果某个声明所引用的摘录反驳了它,或者该声明被完全裁定且没有支持证据,则会失败);它会从原始verdicts[]中重新缩减判决,并从实时仓库重新读取每个裁定的摘录 —— 被篡改的摘要或漂移的源代码会失败,绝不会通过。verify --answer <file> [--apply <verdicts.json>] [--max-verify <n>]—— 高于check --answer的高保证门:生成声明↔引用工作清单以进行对抗性支持检查,然后--apply将你的判决缩减为通过/失败门。参见 references/verify.md。embed [--force]—— 构建/刷新vectors.json以用于语义find(需要提供者 —— 参见 references/semantic.md)。
范围说明
- 无需密钥,无需网络,确定性(可选的语义层是唯一的例外,当提供者缺失时它会降级为词汇搜索)。对未变更仓库的两次构建是字节相同的,除了
manifest.json中的builtAt来源时间戳;vectors.json也被排除在外(其浮点数取决于提供者)。 - AST 精确符号,通过内置的 tree-sitter 语法实现,支持 JS/TS/TSX、Python、Go、Rust、Java、C、C++、C#、Ruby、PHP —— 真实的嵌套结构、精确的类型、结构化的导出。其他语言会回退到正则表达式提取器(仍然可搜索)。语法 wasm 文件包含在包中,因此在技能使用时仍然无需
npm install(安装较重——约 17 MiB 的 wasm)。 - 导入边 支持 JS/TS(tsconfig
paths、packageexports映射)、Python、Go(多模块 +replace)、Rust(mod/use)、Java(包)、C/C++(#include "...")、Ruby(require_relative/require)、PHP(composer PSR-4 + 相对require)、C#(using→namespace)。此外还有保守的代码→代码use边,当某个文件引用了另一个文件的唯一导出符号但未导入时。其余语言没有导入边。Yarn PnP 的虚拟文件系统超出范围(工作区名称仍然可以解析)。 - 悬挂的边通常意味着仓库本身存在损坏的导入或过时的文档链接——这应该作为发现报告,而不是被掩盖。