内容
# GitNexus for Agent Zero
通过安装 [GitNexus](https://www.npmjs.com/package/gitnexus) 命令行工具并注册其 MCP 服务器，为 Agent Zero 提供代码图超级能力，使代理能够在更改任何内容之前分析代码库 — 依赖项、影响/爆炸半径、符号调用者、路由/工具映射和临时图（Cypher）查询。
## 支持
如果这个插件对您有帮助，您可以支持开发者。
[](https://buymeacoffee.com/king0james0) [](https://solscan.io/account/HXrzPqgcxBR9LctTVdTF6xCLpah4hQwyYEevsQ98QvTo) [](https://etherscan.io/address/0xfF61681F907fA8DB39C1d23cbdbE89D24A94De17) [](https://mempool.space/address/bc1qyr6x7kmxpy6ke0xutkxg90f30658fnr39h0d7r)
## 功能
- **代码图查询**（`gitnexus-code-graph` 技能）— 启用后，GitNexus 的 MCP 工具出现在代理的工具集中：列出索引仓库、查找符号的调用者、衡量编辑的爆炸半径、映射路由/工具，并对图运行 Cypher 查询。
- **Canvas 中的可视化代码图**（`gitnexus-canvas-view` 技能）— 在 Agent Zero 的右侧 Canvas 栏中添加 GitNexus 图标。单击它以在 Agent Zero 中直接浏览索引仓库的图（符号、依赖项、执行流程）和文件树。因为 GitNexus 的 Web 界面是本地的（它通过 `localhost` 与其服务器通信），所以插件在 **无头 Chromium 中渲染它**，并将该视图流式传输到 Canvas — 所有内容都保留在 `127.0.0.1`，没有任何内容外部暴露。（需要环境中的 Chromium；如果不存在，插件会通过 `apt` 安装一个。MCP 工具无论如何都起作用。）仓库列表 **自动刷新**：当您索引或重新索引仓库时，表面会在几秒钟内重新加载（并且在打开时）以使新的/更新的仓库出现 — 无需手动刷新，并且代码换行保留。重新加载仅在索引实际更改时发生，因此否则不会干扰您的视图。您还可以 **选择表面中的文本并按 `Ctrl/Cmd+C` 复制** 到您自己的机器的剪贴板（代码视图和详细信息面板被制作成可选的），并按 **`Ctrl/Cmd+V` 粘贴** 本地剪贴板到表面的字段中。它是跨平台的；复制在 `https`/`localhost` 上使用异步剪贴板 API，并为纯 `http` LAN 访问提供传统回退。
- **定时重新索引** — 保持索引图新鲜。选择加入（默认关闭）— 打开它，插件会注册一个循环 Agent Zero 调度任务（**"GitNexus 重新索引"**，默认在周日 06:00），对您已经 **索引** 的任何仓库运行 `gitnexus analyze`，其最新提交自上次索引后已更改。它 **不会** 发现或索引新仓库 — 这是您的选择。参见 [保持索引新鲜](#保持索引新鲜)。
## 安装
1. **安装** 通过插件中心、GitHub 仓库 URL 或上传插件 ZIP，然后在 **插件** 列表中启用它。
2. 首次运行时，插件会安装 `gitnexus` 命令行工具（`npm install -g gitnexus`）并在 Agent Zero 的 MCP 设置中注册 `gitnexus mcp` 作为 stdio MCP 服务器。**重启/重新启用** 以使 MCP 服务器连接。
3. 就是这样 — 无需 API 密钥。询问类似 *"什么依赖于此函数？"* 或 *"映射此仓库"* 的问题，代理将使用 GitNexus 工具。
> 需要 Node.js/npm 在 Agent Zero 环境中（标准 Docker 镜像中存在），并且在首次运行时需要出站网络访问来安装命令行工具。
> **注意 `onnxruntime-node`:** gitnexus 引入了 `onnxruntime-node` 用于其可选的本地嵌入（ `--embeddings` ）功能，并且该依赖项的原生安装程序下载了一个 NuGet 运行时，该运行时在某些环境中无法解压 — 否则会中止整个命令行工具安装。插件不使用嵌入，因此它安装 gitnexus 时带有 `ONNXRUNTIME_NODE_INSTALL=skip`：仅跳过一个可选下载，而 gitnexus 的必需原生部分（其图数据库引擎和语言语法）会正常构建。您将获得一个完全可用的命令行工具（MCP、分析、Canvas、所有核心语言），只是没有本地嵌入。
## 工作原理
插件在 Agent Zero 的 `mcp_servers` 设置下注册一个标准的 MCP 服务器条目：
```json
"gitnexus": { "type": "stdio", "command": "gitnexus", "args": ["mcp"] }
```
Agent Zero 生成 `gitnexus mcp` 并向代理公开其工具。因为 A0 在更改此设置时自动重新加载 MCP，所以服务器无需手动配置即可连接。
## 保持索引新鲜
GitNexus 索引是一个快照 — 它反映了仓库在分析时的提交状态，因此随着您不断提交，它会过时。要保持其最新，插件可以注册一个调度任务 — **选择加入，默认关闭。** 在插件的 **配置** 面板中打开 **定时重新索引** ，注册任务；关闭它，任务将被删除 — 切换立即生效，无需重启：
- **任务名称：** `GitNexus 重新索引` （在 Agent Zero 的 **调度器** 中可见； 在插件的 **配置** 面板中设置其节奏）。
- **默认节奏：** 每周（周日 06:00），在 Agent Zero 的配置时区 — 在配置面板中更改（**间隔** 预设或 **自定义 cron** ）。
- **每次运行执行的操作：** 读取 GitNexus 注册表，并对于您已经索引的每个 git 工作树仓库，将其当前 `HEAD` 与上次索引时的提交进行比较。如果它们不同，则对该仓库运行增量 `gitnexus analyze` ；如果不是，则跳过它（因此空闲周几乎不执行任何操作）。
- **不执行的操作：** 永远不会索引新仓库。您决定索引什么（`gitnexus analyze <path>` ）；任务仅保持当前您已经选择的内容。
### 工作原理
工作和调度被故意分开：
- **确定性助手执行所有工作。** `helpers/reindex.py` 是纯 Python — 它读取注册表，进行提交比较，并对更改的仓库运行 `gitnexus analyze` 。索引逻辑本身不涉及模型/LLM。
- **调度任务纯粹是可见的触发器。** `GitNexus 重新索引` 任务不包含任何逻辑；其指令只是 **"调用 `gitnexus_reindex` 工具一次并报告摘要。"** 它存在以便调度是可见的，可以按需运行，禁用或从调度器 UI 删除（节奏本身在配置面板中设置）。
- **触发通过代理循环。** Agent Zero 通过将提示传递给代理来运行每个调度任务（这是 A0 具有的唯一执行路径），因此当任务触发时，代理的单个操作是调用内置的 `gitnexus_reindex` 工具，该工具在进程中运行助手（无终端/代码执行会话 — 因此手动 **运行** 从调度器与调度运行相同）。 **没有后台线程** — 除了此任务外，没有任何东西运行助手，因此它永远不会重复触发。
- **成本：** 由于触发器通过代理传递，因此每次运行都会在该 **"运行此命令"** 跳跃上花费模型预算的一小部分 — 而不是索引，这是确定性助手的任务。
### 设置调度
节奏存在于插件的 **配置** 面板中 — 配置是 **真实来源** （在保存和每次启动时应用，因此直接在调度器中编辑任务的调度将被覆盖；请在此处更改）：
- **间隔** — 预设下拉菜单：每 **6 小时** / **12 小时** ， **每天** ， **每周** （默认）或 **每月** 。每天/每周/每月在 06:00 运行。
- **自定义调度（cron）** — 一个 5 字段的 crontab（`分钟 小时 天 月份 星期几` ）用于预设无法表达的任何内容（例如 `0 3 * * *` = 每天 03:00）。**覆盖间隔。**
- **每次运行重置上下文** — 在每次运行后清除任务的对话，以免其上下文无限制增长（默认启用）。
- **时区** — 在配置中设置 `reindex.timezone` 以与 Agent Zero 的默认时区不同。
任务仍在 Agent Zero 的 **调度器** 中显示，您可以在那里查看其历史记录，**按需运行** 或 **禁用** /删除它。要关闭整个功能，请在配置面板中关闭 **定时重新索引** （它会删除任务）。
**限制：** 使用 `--skip-git` （或非 git 文件夹）索引的仓库没有提交可比较，因此不会自动刷新；请手动重新索引那些仓库。
## 配置
`default_config.yaml` （在插件配置 UI 中按范围覆盖）：
| 键 | 默认值 | 含义 |
|---|---|---|
| `gitnexus_version` | `latest` | 要安装的 gitnexus 命令行工具的 npm 版本，或固定版本。 |
| `mcp_server_name` | `gitnexus` | 此插件在 `mcp_servers.mcpServers` 下注册的键。 |
| `serve_port` | `4747` | 用于 `gitnexus serve` 图形 Web 界面（容器内的 Chromium 加载；绑定到 `127.0.0.1` ）的本地端口。 |
| `cdp_port` | `9223` | 无头 Chromium 的远程调试端口，屏幕截图桥接器连接到的端口。 |
| `bridge_port` | `14601` | 在 A0 的 Canvas 网关中注册的屏幕截图桥接器端口。 |
| `reindex.enabled` | `false` | 注册定时重新索引任务。 **选择加入 — 默认关闭。** 在插件的 **配置** 面板中打开它（立即生效，无需重启）。 |
| `reindex.interval` | `7d` | 节奏预设： `6h` / `12h` / `1d` （每天）/ `7d` （每周）/ `30d` （每月）。每天/每周/每月在 06:00 运行。 |
| `reindex.cron` | `""` | 高级：完整的 5 字段 cron（`分钟 小时 天 月份 星期几` ）。设置后，**覆盖** 间隔。 |
| `reindex.reset_context` | `true` | 在每次运行后清除任务的对话，以免其上下文无限制增长。 |
| `reindex.timezone` | `""` | 调度的时区；空值使用 Agent Zero 的配置时区。 |
## 卸载
通过 **插件 UI** 卸载。卸载钩子会删除 `GitNexus 重新索引` 调度任务，从 `mcp_servers` 设置中删除 gitnexus 条目（Agent Zero 重新加载 MCP），并且 **如果此插件安装了 gitnexus 命令行工具，则卸载它** — 因此不会留下任何内容。您的索引仓库及其 `.gitnexus` 数据保持不变。您之前独立安装的 `gitnexus` 保持不变。（手动 `rm -rf` 插件文件夹会绕过此钩子 — 始终通过 UI 卸载以进行干净的删除。）
## 引用
如果您在工作中使用它，请引用它（使用 **"引用此仓库"** 按钮在 GitHub 上，或）：
```bibtex
@misc{a0gitnexusplugin2026,
title = {a0-gitnexus-plugin: GitNexus 代码图适用于 Agent Zero},
author = {King0James0},
year = {2026},
howpublished = {\url{https://github.com/King0James0/a0-gitnexus-plugin}},
note = {GitHub 仓库}
}
```
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
