前言¶
在 DSH 里用 GitNexus 做代码图和影响分析时，常见问题是：索引到底覆盖了哪些文件、哪些被策略跳过、工作区相对索引是否已过期、以及是否值得跑一遍耗时的 analyze。GitNexus 本身提供 CLI 与 Web UI，但不会替你在 Harness 侧栏里汇总「漏项 + 新鲜度 + 刷新建议」，也不会把 impact / context / query 以统一前缀的工具名注册给智能体。下面介绍 Moowningstar 维护的 dsh-gitnexus-plus（社区目录名 moowningstar/gitnexus-plus）：它不 fork、不重写 GitNexus 解析器，也不打包上游；gitnexus 作为 peer 由你自行安装。
这是什么¶
dsh-gitnexus-plus 是 DeepSeek Harness 插件（npm 包名 dsh-gitnexus-plus，当前发布 0.1.10，MIT 许可证）。一句话定位：查看 GitNexus 索引覆盖了什么、漏掉了什么，判断刷新是否值得跑，在侧栏浏览图与仓库提交历史，嵌入 GitNexus 自带 3D Web UI，并把 coverage / delta 以及图查询能力暴露给 DSH 工具与 HTTP 路由。
维护者：Moowningstar。目录页：https://www.skillhub.cn/plugins/Moowningstar/gitnexus-plus；源码与文档：https://github.com/Moowningstar/gitnexus-plus。
核心功能¶
以下能力均来自插件 README，按使用路径归纳。
索引健康与刷新门禁¶
- Tier 0 差量：刷新前用工作区文件与
.gitnexus/gitnexus.json里记录的 sha256 比对，报告改 / 增 / 删及被策略排除的文件；工作区干净时毫秒级结论，不启动分析器。只有锚定在索引记录的提交上才称「已是最新」；无提交基线时退化为与HEAD比较并明确「无法确认」。 - 刷新建议：与陈旧度一并给出
none/incremental/reanalyze/rebuild/init/unknown，避免无基线时误报「可增量刷新」，或对--skip-git索引提供不可能的增量路径。 - 索引覆盖：列出
gitnexus analyze因体积跳过的文件，含大小、语言占比及生成物/压缩文件信号。 - 索引新鲜度：索引提交相对
HEAD为current/behind/diverged/unknown，并统计未提交变更；面板文案与工具前缀共用同一判断。 - 版本一致性：对比索引内
runnerIdentity.cliVersion与当前 CLI；在支持范围^1.6.12 || >=1.6.13-rc.0 <2.0.0内的跨线差异记为说明，超出范围才告警。
可视化与 Git 活动¶
- 图视图：社区级 canvas、跨社区边聚合；点社区 / 符号可定位到文件行；受宿主节点与边预算约束并写明省略量。符号视图为按文件顺序截断的全仓库投影；展开为居中弹窗而非全屏。
- 3D 视图：按需启动
gitnexus serve（插件卸载时停止），在 iframe 中加载 GitNexus 自带 SPA；可新标签打开、停止服务；端口与嵌入可通过webViewPort等配置；失败时展示子进程输出（例如索引 DB 版本不匹配）。 - AI 设置预填：通过
GITNEXUS_WEB_DIST注入生成的index.html，在 SPA 启动前写入gitnexus-llm-settings，环境变量为GITNEXUS_PLUS_AI_PROVIDER、GITNEXUS_PLUS_AI_API_KEY、GITNEXUS_PLUS_AI_MODEL，可选GITNEXUS_PLUS_AI_BASE_URL；Key 不进侧栏卡片。 - Git 活跃度 × 索引：最近提交、作者、分支、改动最多文件，并标记 已索引 / 设计上排除 / 索引缺失；含活动交叉表、基线审查、7/14/30 天时间线；顶栏分支选择执行真实
git checkout并重载报告。 - 提交图（泳道）：按
--all读历史，未合并分支独立列；可展开提交涉及的文件（每提交最多 40 个）并查看只读补丁。
智能体工具、搜索与 CI¶
DSH 内注册的工具（与 GitNexus 生成的 AGENTS.md 裸名不同，需用带前缀名称）：
| 工具 | 作用 |
|---|---|
gitnexus_coverage |
索引漏掉了什么 |
gitnexus_delta |
这次刷新会不会改变索引 |
gitnexus_impact |
改某符号会波及谁 |
gitnexus_context |
符号定义、调用关系与流程 |
gitnexus_query |
用自然语言在图里找功能位置 |
图查询经 graph-query-helper.js 子进程调用 GitNexus MCP 后端；索引落后时会在回答开头重复与面板一致的提示。graphTools: false 可关闭三图工具，仅保留 coverage / delta。
关键词搜索：默认 graph 模式（符号名/路径 + FTS 正文）；图查询不可用时 text 回退为有界源码行匹配。
独立 CLI dsh-gitnexus-coverage（lib/bin/gitnexus-coverage.js）支持 --fail-on-large（退出码 2）、--fail-on-uncovered / --fail-on-missing（退出码 3），供流水线门禁。
安装与启用¶
前置（README 原文要求）：
- DSH
>=0.2.0-rc.2 <0.3.0 - Node
>=22 - GitNexus
>=1.6.0 <2.0.0（peer，不随插件安装）
安装插件：
dsh plugin add dsh-gitnexus-plus
添加后重启 DSH。侧栏入口：点 + → 指南页 → GitNexus 索引。
desktop profile 不能靠 CLI 改插件列表，需在 Web 侧栏 Plugins 页面添加；从本地 checkout 安装：
dsh plugin --profile web add <本包绝对路径>
安装 GitNexus（推荐自行安装）：
npm install -g gitnexus
非标准 CLI 路径：
GITNEXUS_CLI=/path/to/gitnexus/dist/cli/index.js
典型用法¶
侧栏与多项目工作区¶
面板从当前工作区向下收集：工作区自身、子目录中的 .gitnexus 索引，以及尚未索引的 git 仓库。多个候选时标题栏可切换项目；刷新、差量、搜索与维护命令均针对当前选中路径。无索引时仍显示扫描概览与初始化指引。
智能体调用示例¶
查覆盖与是否该刷新：
gitnexus_coverage：{ repo, includeLanguages? }gitnexus_delta：{ repo }
改代码前问影响与上下文：
gitnexus_impact：{ repo, target, direction?, maxDepth?, summaryOnly?, limit?, minConfidence? }gitnexus_context：{ repo, name?, uid?, file_path?, kind?, include_content? }gitnexus_query：{ repo, search_query, goal?, task_context?, limit?, max_symbols? }
命令行 coverage¶
node lib/bin/gitnexus-coverage.js <repo-path>
node lib/bin/gitnexus-coverage.js -r material-ui
node lib/bin/gitnexus-coverage.js --all --json
node lib/bin/gitnexus-coverage.js <repo> --fail-on-large
node lib/bin/gitnexus-coverage.js <repo> --fail-on-uncovered
node lib/bin/gitnexus-coverage.js <repo> --fail-on-missing
（在插件包目录下构建后使用；亦可通过包内 bin dsh-gitnexus-coverage 调用。）
维护类操作经 DSH shell 执行器触发，例如 POST /api/gitnexus/analyze（force=1 全量重建，mode=repair-fts 仅修 FTS）。
适用场景与注意¶
适合谁：已在或计划在仓库上使用 GitNexus 索引，并希望在 DSH 里同时给人（侧栏报告、3D 视图）和给智能体（coverage / delta / 图工具）同一套「覆盖 + 新鲜度 + 查询」事实源的开发者与团队。
务必注意：
- 插件以当前 DSH 进程权限运行，维护命令会通过宿主 shell / subprocess 执行
git checkout、gitnexus analyze等；安装前请阅读源码与 MIT 许可证，并理解 GitNexus 为 PolyForm-Noncommercial-1.0.0，商业使用 GitNexus 需单独授权 upstream。 - 首次通过面板安装 GitNexus 会拉取较大依赖并可能需要 C++ 工具链；失败时应按 README 手动
npm install -g gitnexus。 - Windows 上 FTS、沙箱路径、3D 服务端口占用等问题，README「遇到问题怎么解决」表中有对应条目；索引版本与 CLI 不一致时 3D 视图会显示数据库版本错误而非空白页。
DSH 生态强调「一切皆插件」；SkillHub、dsh-plugin.org、dshget.com 等目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
经过上面的步骤，你可以在不动 GitNexus 核心的前提下，把「索引漏了什么、要不要刷新、图与提交长什么样」收进 DSH 侧栏，并把同一判断交给 Harness 工具。进一步细节见 GitHub README-CN.md 与 Issues；社区条目：https://www.skillhub.cn/plugins/Moowningstar/gitnexus-plus。
