HarperZ9/index

# 索引 [Project Telos](https://harperz9.github.io) | [gather](https://github.com/HarperZ9/gather) | [crucible](https://github.com/HarperZ9/crucible) | [index](https://github.com/HarperZ9/index) | [forum](https://github.com/HarperZ9/forum) | [telos](https://github.com/HarperZ9/telos) | [learn](https://github.com/HarperZ9/learn) | [emet](https://github.com/HarperZ9/emet) | [buildlang](https://github.com/HarperZ9/buildlang) [](https://github.com/HarperZ9/index/actions/workflows/ci.yml)    [](LICENSE) `index` 会读取你的代码和文档，并绘制出可供他人查阅的地图。将它指向一个陌生的 repo，你就能获得一个独立、经过验证的 wiki；将它指向整个工作区，你就能获得一份依赖拓扑图。它专为那些接手非本人编写的代码库的人、新的维护者、审查者以及智能体（agent）而设计，因为当模块或 repo 数量超过一定规模后，系统的结构往往只存在于某个人的脑海中，而那个人通常很忙，或者已经离开了。它基于 `file:line` 证据构建，而非猜测。完全离线、确定性、零运行时依赖。 只需一个名字即可安装、运行和导入：`pip install index-graph` 负责安装，`index` 负责运行，`import index_graph` 负责导入。 ## 5 分钟体验 ``` pip install index-graph # 一个陌生的 repo -> 一个自包含、经过验证的 wiki index wiki --root /path/to/one/repo --out wiki.html index wiki --verify wiki.html --root /path/to/one/repo # MATCH / DRIFT / UNVERIFIABLE # 然后是工作区海拔图：repos + 文档在同一张双层地图上 index atlas --root /path/to/your/workspace --format html --out atlas.html # 或者仅仅是 repo 依赖图： index viz --root /path/to/your/workspace --format html --out graph.html ``` 每条命令都会生成一个独立的 HTML 文件。可在任何浏览器中离线打开。无需托管，也不会向外发送任何数据。 想在安装前查看输出效果？仓库中附带了渲染好的示例：验证过的单 repo wiki 见 [`examples/wiki-demo.html`](examples/wiki-demo.html)，工作区拓扑图见 [`examples/atlas-demo.html`](examples/atlas-demo.html)，静态验证展示见 [`examples/index-demo.html`](examples/index-demo.html)。这些演示可以通过 `python examples/wiki_demo.py` 和 `python examples/atlas_demo.py` 确定性地重新生成。 直接运行 `index`（不带子命令）会写入 JSON 清单地图并提示位置：它会在写入前打印写入路径，而 `index --dry-run` 会报告将要写入的内容而不实际写入。 ## 为什么这很重要 当没有人能掌控工作区的整体结构时，它就会变得充满风险。index 为团队和智能体（agent）提供了一份基于导入、清单、文档和证据（而非记忆）构建的地图，因此上下文包可以引用它们所依赖的结构。 ## 它能做什么 每个代码库都有其结构。当 repo 数量超过一定规模后，这种结构只存在于某个人的脑海中，而那个人通常很忙，或者已经离开了。`index` 替你把它画出来：你的各个 repo 之间是如何依赖的，以及解释其原因的文档，全都汇集为你可打开的一张地图。基于证据，而非猜测。零依赖。 将 `index` 指向一个包含 Git 仓库的文件夹，它就能回答那个随着 repo 增加而变得越来越难的问题：这一切究竟是如何组合在一起的？它会按照代码中已经声明的方式读取依赖——一个文件中的 import，另一个文件中的清单条目——并记录每一条连边，附带证明它的文件和行号。接着，`index atlas` 会完成大多数工具忽略的部分。它将你的 markdown 拉入同一张图中：README、ADR、设计笔记，让解释最终紧挨着被解释的对象。最终产出的是一个单一的 HTML 文件。无需服务器，无需构建步骤，无需账号。除了 Python，什么都不需要安装。 ## 为什么需要它 程序的结构就是一种知识，而只存在于一个人记忆中的知识是脆弱的。人们会休假，会调换团队，会离职。下一个人只能通过四处 `grep` 来重建地图，而且还容易弄错一点。与此同时，记录着原因的文档（为什么存在这个服务、为什么允许那个依赖）被放在无人问津的文件夹中，与它们描述的代码隔绝开来。 `index` 把那张地图变成你手中切实可握的东西。它是确定性的，可按需重新生成，并且对每一行的来源都绝对诚实。人们通常会在以下几种情况中用到它。 - 你接手了一个不是自己写的工作区。二十个 repo，没有架构图，原作者早已离职。一条命令就能为你提供入职第一天就能看懂的资料。 - 你在维护一个 monorepo，或者一个分散在多个 repo 中的产品。你希望一眼看清依赖路径，在被坑之前发现循环依赖，并且无需翻找十个文件夹就能找到某个服务的文档。 - 你维护着大量开源项目。这些 repo 及其解释文档被整合在同一张地图中，且每次都以相同方式重新生成，因此绝不会悄无声息地偏离真实情况。 - 你在编写入职指南。交给别人一个可以永远离线使用且能自我解释的文件。 ## `index wiki`，经过验证的 wiki 拓扑图用于映射整个工作区。`index wiki` 则是另一个视角，也是新人真正需要的“单一陌生 repo”视图。基于模型构建的 wiki 生成器会猜测你的架构，并针对不存在的结构写出自信满满的文字；repo 打包工具则只是在不加理解的情况下倾倒源代码。`index wiki` 采取第三种道路：它从 index 已经提取的模块依赖图中推导出某个 repo 的 wiki，然后对其进行封装，使得结果可以被重新验证，而不是被迫盲目信任。 ``` index wiki https://github.com/org/repo --out wiki.html # clone, derive, clean up index wiki --root /path/to/one/repo --out wiki.html # one self-contained file index wiki --verify wiki.html --root /path/to/one/repo # MATCH / DRIFT / UNVERIFIABLE ``` 将其指向一个 git URL，index 会将 repo 浅克隆到临时目录中，推导出 wiki，然后删除该克隆，因此你可以阅读尚未检出的 repo。本地路径的工作方式也是如此。 一条命令，生成一个带有客户端页面导航的离线 HTML 文件（或使用 `--format json` 生成 JSON 包），包含四种页面： - **概述**：repo 标识、检测到的生态系统、图推导出的入口点、模块数量、文档清单，以及 wiki 所绑定的 commit SHA。 - **模块页面**：每个模块一个页面（在大型 repo 中为包集群），包含导入、依赖者、文件路径和循环依赖成员关系，并且显示的每一条边都带有图为其记录的 `file:line` 证据。这也是 `index internals` 之前所缺少的可视化渲染。 - **符号页面**：每个函数、类和方法（Python）各一个页面，包含定义的 `file:line`、谁调用了它（FIND-REFERENCES）、它调用了什么（GO-TO-DEFINITION），以及任何静态扫描无法解析的引用，这些都是如实展示而非猜测出来的。模块内调用是 AST 精确的；绑定到真实定义的跨模块调用是尽力而为的，并标记为中等；其余的则被标记为未解析，绝不凭空捏造。当超过符号数量阈值时，为避免内容臃肿，这些页面将被省略，且 CLI 上的图依然可用。 - **架构**：基于真实依赖图渲染的图表，绝非推断。 - **文档**：原封不动地整合了你现有的 markdown，并明确标记为由人类编写。 没有模型，没有网络，没有生成的文字。每个页面底部都标明了推导边界，即结构来源于依赖图以及该页面自身的证据数量。产出物嵌入了一个 `index.wiki/1` 清单、固定的 commit（对于非 git 根目录则为“unversioned”）、每个页面的规范 SHA-256，以及生成输入，并使用与每个 index 证书相同的哈希规则进行封装。`index wiki --verify` 会针对当前代码树重新计算页面哈希和图推导，并给出 MATCH、DRIFT（页面被篡改、声称存在的边在实际图中不存在，或者 repo 偏离了其绑定的 commit）或 UNVERIFIABLE 的结果，对应的退出码为 0/1/2。测试套件中保留了已知的恶劣样本：被篡改的页面、哈希一致但伪造的连边、恶意的 markdown 和模块名，因为无法在已知恶劣输入上报错的验证器根本算不上验证器。 仓库中附带了一个渲染好的示例，见 [`examples/wiki-demo.html`](examples/wiki-demo.html)。直接打开它，或者使用 `python examples/wiki_demo.py` 重新生成。 ## `index serve`，按需提供的 wiki 服务器 `index wiki ` 会一次性推导出某个 repo 的 wiki。`index serve` 则将其置于一个 URL 之后：这是一个本地服务器，在你发出请求的那一刻为你推导出 repo 已验证的 wiki，绝不提前。 ``` index serve # http://127.0.0.1:8000/ (loopback by default) # 然后通过其 forge 路径打开一个 repo： # http://127.0.0.1:8000/github.com/org/repo index serve --host 127.0.0.1 --port 9000 ``` 对 `GET ///` 的请求会重构出 git URL `https:////`，运行与 `index wiki ` 完全一致的路径（浅克隆、从模块图推导、清理克隆），并提供自包含的 wiki HTML。根路径 `/` 是一个简洁的落地页。 它在构建上符合知情同意原则，因为经过验证的 wiki 类工具正因为生成内容（往往在排名上盖过官方文档）而饱受非自愿生成的争议，而这个展示界面坚决不趟这趟浑水： - **仅按需生成。** 绝不进行爬取，也不预建索引。wiki 的生命周期仅与一次请求的时间等长，之后克隆即被删除。 - **每一页都保持诚实。** 落地页和每个被访问的页面都声明，该 wiki 的结构派生自依赖图，不生成任何文字，已绑定 commit，可通过 `index wiki --verify` 重新验证，并遵从 repo 所有者编写的文档。 - **不针对搜索引擎。** `/robots.txt` 禁止索引，且每个响应都携带 `X-Robots-Tag: noindex, nofollow`。 - **仅限本地。** 这是本地服务器组件。此处不进行任何外部发布，将其部署或托管在任何地方都是独立运营者的决定。 仅接受格式为 `host/org/repo` 的 http(s) forge URL。格式错误的路由会返回带有明确原因的 400 类型错误，而克隆失败会返回一个简单的 502 页面，绝不暴露堆栈跟踪。服务器默认绑定 `127.0.0.1`；提供 `--host`/`--port` 选项，但默认回环地址。不存在对应的 MCP `serve` 工具：长时间运行的服务器不适合 MCP 的 stdio 模型，因此该接口仅支持 CLI。 ## `index atlas`，双层地图 大多数依赖工具止步于代码。但代码只是理解系统所需的一半。另一半是解释它的文字，而这些文字通常滞留在图谱无法看见的地方。`index atlas` 将它们重新拉回来。每个 markdown 文件都成为一个节点，与其所记录的代码相连接，你甚至不需要离开地图就能阅读它。 ``` flowchart TD subgraph code["code: repos and dependencies"] api["api"] storage["storage"] end subgraph knowledge["knowledge: your markdown docs"] apiR["api/README.md"] storageR["storage/README.md"] arch["docs/architecture.md"] adr["docs/adr-001-storage.md"] end api -- depends on --> storage apiR -. describes .-> api storageR -. describes .-> storage apiR -. links-to .-> arch apiR -. links-to .-> storage arch -. links-to .-> api arch -. mentions .-> storage ``` 地图上有四种边，工具会从真实存在的事物中推导出它们中的每一个。绝无猜测。 | 边 | 含义 | 来源 | |------|-------|------------| | **depends-on** | repo 到 repo | 真实的 import 和 manifest 依赖，附带作为凭证的 `file:line` | | **describes** | 文档到 repo | 文档就位于该 repo 的目录树中 | | **links-to** | 文档到文档或 repo | 文档正文中的 `[[wiki-link]]` | | **mentions** | 文档到文档或 repo | 名称出现在正文中（关联最弱，显示为暗色，可切换隐藏） | 打开结果，它用起来像是一个工作台，而不是一张海报。 ``` +----------------------------------------------+-----------------------+ | search repos + docs [reset][focus][filter] | Architecture doc | | | links: api, storage | | +-----+ +---------+ | linked from: api/RE | | | api |-------->| storage | repos | ------------------- | | +--+--+ +----+----+ | # Architecture | | . api/README . storage/README | api is the entry; | | . . . . knowledge band . . . . | storage is the core. | | [architecture] [adr-001-storage] | > Rule: api never | | pan / zoom / click a doc to read it | > imports a peer. | +----------------------------------------------+-----------------------+ ``` - 平移和缩放图谱。滚轮在光标处缩放，拖拽进行平移，一个按钮即可重置视图。 - 同时搜索 repo 和文档标题。不匹配的内容会自动淡出。 - 点击文档即可直接阅读其渲染后的 markdown，包含标题、列表、表格和代码，以及可点击跳转到所命名节点的 `[[links]]`。 - 双击任何节点可将视图缩小到它的邻域。单击即可清除。 - 面包屑轨迹会记住你的路径，因此跟随链接的操作总是可逆的。 仓库中附带了一个渲染好的示例，见 [`examples/atlas-demo.html`](examples/atlas-demo.html)。直接打开它，或者使用 `python examples/atlas_demo.py` 重新生成。 ## 在实际场景中试用 当问题出在没人能再在工作区内理清架构时，`index` 就是你的首选测试工具。 - **工程 / 智能体路由：** 在分配模型工作之前映射出 repo 图谱和文档，确保 token 能被发送到真正重要的文件和决策上。 - **临床或合规软件团队：** 在涉及政策、记录或审查流程的系统周围保留架构证据。 - **媒体 / 研究团队：** 将源代码库、笔记和项目文档保留在一个可重复运行的拓扑图中，而不是靠记忆重建地图。 Project Telos：。GitHub：。对等旗舰项目：[gather](https://github.com/HarperZ9/gather)、[crucible]()、[forum](https://github.com/HarperZ9/forum) 和 [telos 引擎](https://github.com/HarperZ9/telos)。 我正在寻找验证的机会、针对真实工作区的测试、愿意检查证书的早期用户的支持，以及可能适度的草根研究资金或线索。 ## 亲自上手 在一个真实的多 repo 工作区上运行它，将拓扑图用于人员入职、尽职调查或智能体交接，并测试上下文包是否保留了足够的结构，以便另一个人能够接手工作。 ## 首先测试什么 - 在一个目前架构只存在于某人脑海中的工作区上运行 `index atlas`。 - 打开生成的地图，并思考一位新的贡献者或智能体是否能在没有交接会议的情况下找到正确的 repo、文档和依赖边。 - 报告任何缺失的边、嘈杂的上下文包或过时的证据指针。目标不是更漂亮的图表，而是一张在另一次运行中可以被重新核对的地图。 ## 当前状态 - **发布版本：** `index-graph 2.8.0`；命令 `index`；Python 3.11+；零运行时依赖。 - **操作接口：** `index status --json`、`index doctor --json`、`index demo --json` 和 `index mcp` 暴露了 Project Telos 操作信封和原生 MCP 工具：`index.map`、`index.context`、`index.context.envelope`、`index.select`、`index.invalidate`、`index.wiki`、`index.status`、`index.doctor`，以及现有的图谱、焦点、验证、路由和内部工具。生成的路由现在会在内部连边旁携带紧凑的依赖证据（如 `pyproject.toml:12`），对于大型工作区使用快速的仅描述文档通过，状态负载会为企业、研究、创意、科学和教育工作流声明共享的 CLI/MCP/插件/IDE/TUI/应用契约。 - **当前基线：** 2.8.0 涵盖拓扑图映射、九大生态系统解析器、架构证书、新鲜度检查、token 经济学基准测试、选择感知上下文信封，以及 MCP 原生工作区智能。 - **公共角色：** Project Telos 的工作区地图和上下文信封层：index 为 gather、forum、crucible 和 telos 提供了关于当前存在哪些代码、文档和依赖证据的共享视图。 - **企业就绪性：** [docs/ENTERPRISE-READINESS.md](docs/ENTERPRISE-READINESS.md) 记录了用于无人值守智能体工作流的大上下文、操作回执、可读性和主机集成契约。 ``` # 从源码 checkout python -m index status --json ``` ## 产出说明 | 产出 | 命令 | 描述 | |--------|---------|-------------| | **代码 + 知识仪表盘** | `index atlas --format html` | 双层地图：repo 与文档，支持平移、缩放、搜索、渲染 markdown 和 `[[links]]` | | **拓扑图包 (JSON)** | `index atlas --json` | 作为数据的双层图谱结构，是上下文包的严格超集 | | **交互式依赖仪表盘** | `index viz --format html` | 自包含。点击节点，跟随证据提示，查看高亮显示的循环依赖 | | **分层 SVG** | `index viz --format svg` | 用于文档或 CI 产物的静态矢量图 | | **Mermaid 图表** | `index viz --format mermaid` | 粘贴到 GitHub markdown 或任何 Mermaid 渲染器中 | | **JSON 上下文清单** | `index map` | 机器可读的清单：远程仓库、分支、未提交数量、分类 | | **依赖图 (文本/JSON)** | `index graph [--cycles]` | 带有证据的 repo 到 repo 连边，以及依赖循环报告 | | **上下文包 (文字描述 + 关系)** | `index context` | 综合包：角色、关系、叙述性摘要 | | **上下文信封** | `index context-envelope --budget N` | 预算受限、带回执的上下文，专为大型代码库智能体工作流设计；源引用是经过哈希处理的扩展句柄，选择摘要说明覆盖率，新鲜度根节点使数据包可复查，省略部分会携带失败代码 | | **路径选择 (回执)** | `index select` | 将候选文件分为选定和拒绝；每个拒绝操作都带有类型的 `index.path-selection/v1` 回执，并且对账检查证明 候选数 = 选定数 + 拒绝数 | | **经过验证的 wiki (单个 repo)** | `index wiki` | 源自模块图的多页、自包含 wiki：概述、携带证据的模块页面、基于真实图谱的架构图、人类编写的文档；逐页封装，绑定 commit，可通过 `--verify` 重新验证 | | **按需 wiki 服务器** | `index serve` | 本地 `http.server`：通过其 forge 路径 (`/github.com/org/repo`) 请求 repo 并获取其已验证的 wiki，与 `index wiki` 代码路径一样按需推导；符合知情同意（不爬取、不预索引，`robots.txt` 禁止索引，遵从 repo 所有者的文档），默认回环地址 | | **模块图 (内部结构)** | `index internals` | 单个 repo 内的依赖图，包含内部循环和扇入/扇出 | | **符号图 (GO-TO-DEFINITION / FIND-REFERENCES)** | `index internals-symbols` | 单个 repo 内直到函数、类和方法的调用/引用图；模块内 AST 精确，跨模块尽力而为且如实标记，确定且可在 `index wiki` 中封装 | | **符号导航 (def / refs / impls)** | `index symbols QUERY` | 在 CLI（和 JSON）中对单个符号进行 Go-to-definition、find-references 和 find-implementations，每一跳都带有 `file:line` 证据；find-implementations 解析 repo 中类的子类和方法的覆盖，绝不凭空猜测外部或无法绑定的基类并将其变成连边 | | **LSP 服务器 (IDE go-to-definition / find-references)** | `index lsp` | 基于相同符号图的 stdio 语言服务器 (VSCode/Neovim/JetBrains)；每一次跳转都有 `file:line` 证据支持或如实返回 `null`，绝不将未解析的引用变成猜测的跳转，并且能检测到磁盘上被修改的工作区，而不是用过期的图谱来答复 | | **架构检查 (证书)** | `index check` | 根据你的 `[architecture]` 规则衡量结构；输出可重新验证的结论 | | **偏移 (证书)** | `index snapshot` 然后 `index drift` | 为结构快照，然后准确查看发生了什么变化 | | **声明依据** | `index verify` | 根据图谱并附带证据来确认或反驳某个依赖或存在性声明 | | **新鲜度** | `index check --freshness`，然后 `index freshness` | 为证书盖上内容指纹；稍后查询真实情况是否已发生变动 | | **失效 (类型化)** | `index invalidate --out PIN`，然后 `index invalidate --pin PIN` | 固定目录树，然后获取一份报告，准确指出哪些产物会因更改而失效，包含类型化的原因和已对账的计数 | | **Token 经济学** | `index bench` | 在你自己的工作区中衡量，结构包比其所提炼的源代码小多少 | | **智能体协议** | `index mcp` | 一个 MCP 形式的 stdio 服务器，将 index 的工具暴露给智能体宿主 | ## 经过验证的架构智能 地图告诉你结构是什么样的。接下来的问题是：这是你原本打算的结构吗？它在今天仍然是这个结构吗？`index` 会回答这两个问题，并返回一个你可以重新运行去验证而非盲目信任的答案。 一切从审视内部开始。`index internals` 在 repo *内部*逐个模块地构建依赖图，而这正是架构逐渐瓦解的地方。Python 的结果是精确的，直接从语法树中读取。JavaScript、TypeScript、Rust 和 Go 则是通过其导入以尽力而为的方式读取。你可以看到内部循环以及所有模块都在依赖哪些模块。 然后你写下你的意图。`.index.toml` 中的一个简短的 `[architecture]` 块陈述了健康代码库应遵守的规则：哪些层可以依赖哪些层、绝不能存在的连边、循环依赖的上限。 ``` [architecture] layers = ["core", "domain", "service", "web"] # a lower layer may not import a higher one forbid = [{ from = "core/**", to = "web/**" }] require = [{ from = "web", to = "core" }] # an intended edge that must exist max_cycles = 0 ``` `index check` 将真实的图谱与该规则进行比对，并报告每一处违规，同时附带证明它的文件和行号。当出现问题时，它会以非零状态退出，因此可以作为 CI 中的门禁。`index snapshot` 和 `index drift` 在时间维度上做同样的事情：记录今天的结构，在明天进行对比，准确查看发生了什么移动。 每次检查和偏移分析都会返回一份证书。结论是 MATCH、DRIFT 或 UNVERIFIABLE 这三个词之一，绝无第四种可能。不存在 TRUSTED。当工具无法评估某条规则时，它会输出 UNVERIFIABLE 并停止，而不是返回一个披着答案外衣的猜测。你之所以相信一份证书，是通过运行其 `recheck` 命令并从相同的证据中确认结论，而不是因为它让你这么做。它还会陈述自身的覆盖率，包括无法解析的文件和无法遵循的动态导入，因此 MATCH 绝不会声称证明了超出其能力范围的内容。它的结构记录在 [`docs/PROTOCOL.md`](docs/PROTOCOL.md) 中，因此 CI 任务、审查者或其他工具可以在对 `index` 本身一无所知的情况下使用它。 证书还能知道它何时变得过时。`index check --freshness` 会在生成时记录工作区的内容指纹，稍后 `index freshness --cert CERT --root ROOT` 会重新计算该指纹，并返回 FRESH 或 STALE 结果，准确指出哪些 repo 发生了移动。这是循环中期的“自上次验证以来有什么变化吗？”检查，防止结论在智能体继续信任它的同时悄然失效。该指纹是保守的：它可能会标记未改变图结构的更改，但绝不会漏掉任何可能改变图结构的更改。 当你需要知道比“有东西移动了”更多的信息时，`index invalidate` 会指出这种移动导致了什么失效。固定一次目录树（`index invalidate --out pin.json`），之后进行对比（`index invalidate --pin pin.json`）：报告会将带有指纹的产出物、证书、上下文包、图谱快照以及每个固定的 repo 划分为已失效和仍然有效两类，每次失效都带有封闭集合中的一个原因（file-changed、file-removed、dependency-edge-changed、doc-changed、unversioned）。计数必须能对账，捆绑的检查会从报告本身重新推导它们，而且对 README 的编辑只会使上下文包失效，同时保持结构快照依然有效，因此你只需刷新差异实际涉及的内容。 所有这些都离线运行。没有 API，没有账号，没有模型，没有网络。该工具读取代码并写入 JSON，它不关心代码是谁写的，也不关心是谁在读取结论。 ## CLI 参考 ``` index atlas [--root ROOT] [--format html] [--json] [--out FILE] [--no-external] index map [--root ROOT] [--output FILE] [--json] [--dry-run] [--config CFG] index graph [--root ROOT] [--json] [--cycles] index context [--root ROOT] [--focus REPO] [--hops N] [--json] [--audit] index context-envelope [--root ROOT] [--budget N] [--focus REPO] [--hops N] [--json] index select [--root ROOT] [--suffix S ...] [--max-files N] [--json] index wiki [--root REPO] [--out PATH] [--format {html,json}] index wiki --verify PATH [--root REPO] [--json] index serve [--host HOST] [--port PORT] (on-demand local wiki server, loopback by default) index viz [--root ROOT] [--format {html,svg,mermaid,all}] [--focus REPO] [--no-external] [--out FILE] [--out-dir DIR] index internals [--root REPO] [--json] [--cycles] index internals-symbols [--root REPO] [--json] [--coverage] index symbols QUERY [--root REPO] [--json] [--def] [--refs] [--impls] index lsp [--root ROOT] [--trace {off,messages,verbose}] (stdio LSP server for the IDE) index check [--root ROOT] [--internals] [--json] [--config CFG] index snapshot [--root ROOT] --out FILE index drift --from OLD --to NEW [--json] index router [--root ROOT] [--out FILE] index verify [--root ROOT] [--depends "A -> B" | --exists NAME] [--json] index freshness --cert CERT [--root ROOT] [--json] index invalidate [--root ROOT] (--out PIN | --pin PIN) [--json] index bench [--root ROOT] [--json] index mcp (stdio JSON-RPC; an agent host connects and calls index's tools) ``` `--focus REPO` 会将 `viz` 或 `context` 的渲染范围缩小到某个 repo 的依赖邻域。 如果解析不到任何 repo 的焦点会发生类型化失败：一张 `index.focus-rejection/v1` 回执会指出 未解析的选择器、封闭集合中的原因代码以及有限的候选列表， 而不是仅仅抛出一句裸露的错误字符串。 `--no-external` 隐藏标准库和第三方节点，将图谱保持在你自己的 repo 范围内。 在 `atlas` 仪表盘中，焦点是交互式的。只需双击一个节点即可。 `map`（也是直接调用 `index`）会在写入前打印写入路径，因此 INDEX.json 的写入绝不是静默的。`--dry-run` 会报告预计路径和 repo 计数而不写入任何内容；与 `--json` 结合使用会被拒绝，因为 `--json` 本身就不写入任何内容。 `context-envelope` 是支持守护进程的安全交接平台。它将原始源代码排除在 数据包之外，但每个保留的 repo 都带有 `project-telos.source-ref/v1` 句柄，其中包含 工作区相对路径、SHA-256 哈希、信号类型、可选的行号以及 `gather.docs` 展开命令。它还包括一份简洁的 `selection` 摘要和 `index.context-envelope-freshness/v1` 根哈希，以便后续运行能看出数据包涵盖了 哪些内容，以及工作区视图是否需要刷新。如果预算耗尽了重要内容，省略记录将携带 一个标准化的 `failure_code`（例如 `budget_exceeded`）；下一次运行可以请求更多上下文， 而不是从缺失的文件中继承信心。 `select` 是路径级别的对应物。它将根目录下的每个候选文件拆分为 选定或拒绝，并且每次拒绝都带有一份类型化的 `index.path-selection/v1` 回执， 指明封闭集合中的原因代码（`excluded-by-rule`、`suffix-mismatch`、`over-budget`、 `not-found`、`unreadable`）以及将其剔除的规则。计数必须能够对账 候选数 = 选定数 + 拒绝数)，并且捆绑的对账报告在发生 静默丢弃、伪造计数或未知原因代码时会转为 DRIFT 状态，因此“文件被跳过”始终是一个 你可以重新核对而非盲目信任的声明。 ## 一条连边如何获得其存在的资格 无法追踪的连边就是谣言。`index` 从两个独立的信号中解析出每一条边，并评估它们吻合的置信度。 ``` flowchart TD n_api["api"] n_core["core"] n_cli["cli"] n_pathlib(("pathlib")) n_requests(("requests")) n_core --> n_pathlib n_api --> n_core n_cli --> n_api n_cli --> n_requests ``` 当 manifest 依赖和观察到的 import 指向同一个方向时，你就会得到一条高置信度的连边。当只有其中一个指向一致时，它依然会被记录下来，并附带作为见证的确切文件和行号。没有任何东西是凭空轻信进入图谱的。 `index` 以这种方式读取九大生态系统，每一个都从其各自的 manifest 和源码 import 中读取：Python、JavaScript 和 TypeScript、Rust、Go、Java、C#、Ruby、PHP，以及 C 和 C++。这种扩展能力是累加的。每一个新的生态系统只是共享协议背后的一个小型解析器类，它们中没有任何一个会增加运行时依赖。 ## 配置 在你的工作区根目录下放置一个可选的 `.index.toml`： ``` # .index.toml，位于你的工作区根目录 [[rule]] # classify repos by workspace-relative path; first match wins pattern = "oss/**" class = "public" [[rule]] pattern = "work/**" class = "internal" [scan] jobs = 16 # parallel workers prune = ["vendor", "target"] # extra dirs to skip (added to the built-in safety set) [privacy] omit_origin_classes = ["internal"] # drop remote URLs for repos in these classes [output] portable = true # root-relative paths + hashed root (default on) ``` 完整 schema 请参见 [`example.index.toml`](example.index.toml)，完整的 flag 参考、可导入的 Python API 以及演示示例请参见 [`USAGE.md`](USAGE.md)。 ## 你可以信赖的特性 - 每一条边都有证据。没有依赖边可以在没有作为见证的文件和行号以及置信度评级的情况下存在。拓扑图中的边（`describes`、`links-to`、`mentions`）来源于位置和 `[[links]]`，而非主观臆断。 - 相同的输入得出相同的输出。在同一个工作区上运行两次，返回的 JSON 和渲染结果在字节层面都是完全一致的。没有时间戳，没有随机性。 - 除了 Python 无需安装任何东西。纯 3.11+ 标准库，包括 markdown 渲染器和仪表盘的平移与缩放功能。有专门的测试来保证这一点。 - 自包含，且对不受信任的文档也能安全处理。单个 HTML 文件，没有外部 URL。Markdown 在渲染时会被转义，通过恶劣内容测试证明它无法导致破坏。 - 默认保护隐私。Repo 路径保持相对于根目录，本地根目录被缩减为一个短哈希，远程 URL 中任何看起来像凭证的内容都会被脱敏。 ## 安装 ``` pip install index-graph ``` 或者从检出的代码库安装： ``` pip install -e . ``` Python 3.11+。这就是全部的依赖列表。 `index` 之所以存在，是因为代码库应该是你能够看透的东西，而不是每次有新人加入时都要从记忆中重新构建的东西。将它指向你的 repo，打开它写好的文件，结构就在那里。每一次运行都是相同的结构，每一条边的证据都只需一次点击即可呈现。 Zain Dana Harper。[作品集](https://harperz9.github.io)，[GitHub](https://github.com/HarperZ9)。 使用 Claude Code 构建。由我本人审查、测试并拥有。 ## 面向开发者 保持公开的 README、包元数据和示例与当前行为保持一致。在开启 Pull Request 或发布版本之前，请运行本地包验证流程。 ``` python -m pip install -e ".[test]" python -m pytest ```

标签：MCP, SOC Prime, 代码分析, 代码可视化, 凭证管理, 多模态安全, 开发工具, 文档生成, 自动化payload嵌入, 逆向工具