前言¶

在 DSH 里接仓库、问 agent「这块需求现在怎么实现的」，常见结果是等研发翻代码，或 agent 根据片段猜一个「大概是这样」。产品经理要的是能点、能转发、且每句话都能对回索引的材料，而不是另一份口头说明。

dsh-repotruth（npm 包名 dsh-plugin-repotruth，当前版本 v0.3.0）由 SilasSolivagus 维护，归类为 工作流 插件。它只读本机构建好的内容寻址索引，产出两类 HTML：系统现状（这个仓里有什么）与 需求走查（这件事落到哪些节点、哪里要问研发）。结论遵守「读不到 / 没找到 / 待确认」不混写一条的纪律。

这是什么¶

插件定位：把代码仓库变成能被代码核实的话。主产物之一是三栏需求走查页——左为流程节点，中为页面结构或时序骨架，右为索引能证明的标注与「待研发确认」槽位。材料是单文件 HTML，可内嵌面板、新窗口打开或直接发到群里，离线也能看；地址可加 #node=<节点id> 直达某个节点。

它不跑语义理解、不改远端代码、不执行仓库脚本；检索当前以词面匹配和固定中英词表为主，查不到会明确说查不到，不生成空的三栏页。

两份产物：别混着读¶

共同点：都只读本机索引；都写「没找到 ≠ 不存在」。

核心能力¶

接入、索引与覆盖率¶

一条链路大致分五步（面板与后台协作）：

1. 接入仓库：克隆为 bare 镜像到 mirrors/<仓名>.git，之后只 fetch。
2. 建索引：按内容寻址写入 index/<仓名>.json；同一内容块只解析一次（README 实测：98 文件仓首轮约 4.5 秒，同 HEAD 第二轮约 100 ms、0 解析）。
3. 说需求：在 DSH 聊天框用中文描述需求，由 agent 调用 repotruth_material。
4. 看材料：生成 materials/<id>.html，默认用系统浏览器打开。
5. 配置与盘点：面板管理代码源、仓库与覆盖率；产出 coverage.json。

克隆与建索引在独立子进程中执行，带硬超时；宿主不等子进程，界面仍可用。

索引跳过 vendor/、third_party/、testdata/、测试文件及生成代码等，并在覆盖率表里分列「已索引」与「跳过生成」。页面统计口径统一走 lib/scan.js，demo 与索引不会给出两个页面数。

走查页的栏位规则¶

• 左栏：命中文件按页面与目录区域归并为节点。
• 中栏（有页面）：模块结构卡；读不到则写原因，不画假截图。
• 中栏（无页面）：时序骨架（参与者限于固定词表），并标明「不是从代码里读出来的流程」。
• 右栏：规模、波及面、以及明确的「待研发确认（未证实）」。
• 没命中：面板与命令行均只返回「没能在已索引的代码里找到与「X」相关的地方」，不生成空页。

作为 DSH 插件的界面能力¶

• 登记 GitHub / GitLab / 通用代码源，测试只读连接并列可见仓库数。
• 接入、同步（clone --mirror 后 git fetch --prune）、移除（删本机镜像与索引）。
• 需求只从 DSH 聊天框进入，插件侧不再单独提供需求输入框。
• 界面文案为中文；健康检查示例：GET http://127.0.0.1:60425/api/repo-truth/health（桌面挂上后期望 200）。

命令行（与面板同实现）¶

适合脚本、CI 或群消息：

npx dsh-plugin-repotruth material vue-admin-template --question "用户登录页面是怎么做的？" --out ./examples

生成系统现状且本次不带页脚署名（meta 仍保留）：

npx dsh-plugin-repotruth demo <仓地址> --no-attribution

配置与署名¶

config.json 顶层示例：

{ "version": 1, "attribution": false, "hosts": [] }

attribution: false 可关页脚「由 repotruth 生成 · … · v0.3.0」；<meta name="generator"> 不可关，便于从 HTML 辨认生成版本。

安装与启用¶

运行环境：node >= 22，peer 依赖 @deepseek-ai/cordis ~4.0.5，许可证 MIT。

桌面版 desktop profile 由 Electron 独占，不能用 CLI dsh plugin 直接装，需在仓库根目录执行 README 中的 link 步骤：备份 ~/.dsh/profiles/desktop 的 package.json 与 cordis.patch.yml，写入 dsh-plugin-repotruth 的 link: 依赖并加入 bundles，再 ln -sfn 到 node_modules。dsh-hmr 热重组，一般无需重启应用。卸载按 README 恢复备份并删除符号链接即可。

若不想动桌面 app，可自建 profile（README「方式二」）；截断处之后的具体命令以 GitHub README 为准。

典型用法¶

界面走查：在聊天框写一句需求，例如「分享页要支持未登录下载但只有会员能下」，点「生成走查材料」→ 读索引按名归节点 → 浏览器打开三栏页，点左侧节点切换中间结构与右侧标注。

盘点现状：接入仓库并完成索引后，在覆盖率页查看「接进来 / 看得见 / 看不见」及跳过原因分项；用 demo 或面板查看单仓长文现状。

问一句（现状检索）：例如「用户登录页面是怎么做的？」——返回相关页面名、引用波及、最近改动与显式限界；检索为词面 + 中文二元组 + 约 50 条中英词表，偏产品常用词（登录、订单等），生僻说法可能找不到。

适用场景与注意¶

适合：产品/项目在评审前要把「现在怎么走」落成可转发材料；接手新仓先做覆盖率与页面规模账；研发与产品要对齐「哪里是索引证明、哪里必须问研发」。

边界（README 明确）：只有只读 git 操作；不 push、不在用户工作区跑 git clean；不做 AST、不读路由声明、不做跨仓索引复用；谁能打开 DSH 界面谁就能看到配置（令牌掩码）；配置与索引仅本机，无多用户同步。

安全与合规：插件以当前 DSH 进程权限访问令牌、克隆与读仓；安装前请自行审阅 源码与许可证。企业内部分发可走 attribution: false 去掉页脚外链。

结尾¶

dsh-repotruth 把「接仓 → 内容寻址索引 → 现状 / 走查 HTML」收成一条工作流，并把「没读到、没找到、待确认」拆开写死，减少评审会上用空页或猜测冒充现状的情况。

• 社区目录页：skillhub.cn/plugins/SilasSolivagus/dsh-repotruth
• 源码与完整安装说明：github.com/SilasSolivagus/dsh-repotruth