Community写作与编辑github.com

maxgfr/ultraindex

将整个代码仓库(代码+文档)索引为可导航的、AI 分析的百科全书——包含地图、每个模块的条目以及类型化的链接图——使 AI 能够在大型代码库中工作而不填满上下文。一个自动路由的 skills.sh 技能,带有基于证据、可验证引用的分析,以及可选的本地(Ollama)语义搜索。

ultraindex 是什么?

ultraindex 是一个强大的 AI 技能,专为解决在大型代码库中上下文窗口过小的问题而设计。它通过将任务分解为“机械工作”(由零依赖的 Node.js 引擎 `node scripts/ultraindex.mjs <command>` 完成,无需 `npm install` 或 API 密钥)和“理解工作”(由用户完成的基于真实代码的、带有引用的分析)来实现。引擎负责扫描项目、构建链接图、生成百科全书;而用户负责分析和导航,而不是直接阅读整个代码库。该技能支持通过 `build` 命令构建索引,通过 `map`、`find`、`neighbors`、`symbols`、`impact` 等命令导航索引,并通过 `check` 和 `verify` 命令提供高保证的验证。它内置了 AST 精确的符号分析(支持 JS/TS、Python、Go、Rust 等主流语言)和导入边分析,其可选语义搜索层通过 Docker Compose 和 Ollama 提供本地嵌入支持。核心规则包括:引擎管理代码视图和图,用户管理业务视图(分析文本在重建时会被保留),分析必须基于 `dossier` 提供的实际源代码并准确引用,以及每次只加载一个条目以优化上下文使用。典型的用例是:构建索引 → 丰富模块 → 根据问题导航。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraindex

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

ultraindex — 构建并导航整个代码仓库的 AI 分析百科全书

在大型代码仓库中,上下文窗口在被填满之前往往来不及找到真正重要的内容。 ultraindex 通过 分工 解决了这个问题:确定性的、零依赖的引擎(node scripts/ultraindex.mjs <command> —— 无需 npm install,无需 API 密钥,运行 --help 查看完整功能)负责机械工作 —— 扫描项目、构建链接图、布局百科全书;你 负责理解工作 —— 基于证据的、带有引用的分析 —— 然后导航结果,而不是阅读整个仓库。

核心规则:

  1. 引擎拥有代码视图和图(ui:gen 区域)——每次构建都会重新生成;切勿手动编辑。
  2. 你拥有业务视图(ui:human 区域)。build 会在重建和重命名时保留你的文字。
  3. 基于证据进行分析,而非凭记忆。 仅根据 dossier 展示的真实源代码编写分析,并引用它 [file:line],check 命令会因任何无法解析的引用而失败 —— 因此不要猜测。
  4. 加载最小内容。 一次只读取一个条目(或一个 dossier)——这是预期的模式,也是每个模块的富化子代理所做的。切勿将 graph.json 或整个 encyclopedia/ 目录批量加载到上下文中 —— 那将违背目的。

大多数命令都接受 --json —— 当你需要根据结果进行分支判断而不是阅读文字时,请优先使用它。

根据情况选择路径

按以下顺序判断你属于哪种情况,并阅读对应的参考文档以获取详细工作流程:

  1. 尚无索引 —— 仓库根目录下没有 .ultraindex/ 或 docs/ultraindex/(查找 graph.json)。构建它,然后富化顶层模块: 阅读 references/generate.md。

  2. 存在索引 —— 先检查新鲜度。 node scripts/ultraindex.mjs check --out <index-dir> --json。如果报告过期或损坏,重新运行 build(你的文字会保留),然后继续。如果仅更改了与任务无关的文件,你可以继续并注明这一点。

  3. 用户有一个任务或问题(“X 在哪里”、“Z 如何工作”、“我应该修改哪些文件”)——导航索引,只打开它指向的文件,用经过验证的引用支撑答案: 阅读 references/navigate.md。

  4. 答案必须是高保证的(审计、安全、正确性至关重要的声明),或者用户要求你验证/判断一个答案 —— 在 check --answer 通过后(引用可解析),升级到语义验证门,以便证明每个被引用的摘录确实支持其声明,而不仅仅是不存在: 阅读 references/verify.md。

  5. 用户要求索引/分析/文档化,或者 status --json 显示未富化的枢纽节点且有预算 —— 运行状态驱动的富化循环(dossier → 编写带引用的分析 → check)。在大型仓库上可以并行化:队列中的每个模块分配一个子代理,前提是你的主机支持子代理 —— 阅读 references/generate.md。

  6. 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、package exports 映射)、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 的虚拟文件系统超出范围(工作区名称仍然可以解析)。
  • 悬挂的边通常意味着仓库本身存在损坏的导入或过时的文档链接——这应该作为发现报告,而不是被掩盖。

相关技能