前言¶
在 DeepSeek Harness（DSH）里通过 MCP 接入 Codebase Memory（CBM）后，语义查询往往可以正常工作，但知识图谱会在你不知情的情况下变旧：MCP 的 cwd 是 profile 级常量，CBM 的监看与 auto-index 容易落在错误的目录树；内置 watcher 又缺少可观测的重建过程；MCP 工具 index_repository 还有 60 秒超时。README 引用的需求文档 P5 曾记录一次实测：图谱落后 33 小时、37 个提交、988 个文件，而使用者仍以为索引是最新的。
下面介绍维护者 WwW7olFWwW 发布的 DSH 插件 dsh-codebase-watcher（分类：记忆）。它自行判断图谱相对各 git 工作树落后多少，只在需要时通过 CBM CLI 条件式重建，并把状态集中展示在 DSH 设定页与 REST 接口上；除安装本插件外，不必改 CBM 或 DSH 核心配置，也无需在宿主上另挂 systemd timer。
这是什么¶
dsh-codebase-watcher 是一行 MCP 之外的「图谱保鲜」层：把 CBM 知识图谱与各已纳管项目的 git rev-parse HEAD 对齐，避免静默过期。
- 仓库：github.com/WwW7olFWwW/dsh-codebase-watcher
- 社区目录：skillhub.cn 插件页（独立站点，与 DeepSeek / 幻方无官方从属关系）
- 当前 package 版本：0.7.1，许可证 MIT
- 运行环境：Node.js ≥ 20.13、DSH ≥ 0.2.0-rc.2；需已安装 codebase-memory-mcp CLI（README 实测 0.11.0，清单外版本会在设定卡片上转为警告）
- 前提：被纳管路径必须是 git 工作树，落后判定依赖 HEAD 与图谱中
Branch.head_sha的对比
核心功能¶
落后判定与条件式重建¶
插件对比图谱里的 Branch.head_sha 与仓库当前 HEAD，给出精确的 behindBy；若无 Branch 节点，则退用 indexed_at 与数据库 mtime，证据不足时明确回报「无法判定」。重建只排入仍落后的项目；若图谱已与 HEAD 一致，POST /rebuild 返回 queued: 0，不产生索引工作。
重建通过子进程调用 codebase-memory-mcp cli index_repository，绕开 MCP 工具 60 秒上限。全局重建并发为 1；README 记载单次全量重建约 60,980 ms、数据库约 658 MB、峰值内存约 2.8 GB（与 CBM auto_index 同类成本）。
每项目监看与防抖¶
每个已纳管项目具备文件监看：优先 chokidar，缺失时退回 node:fs.watch。Linux 上递归 fs.watch 自 Node 20.13.0 起可用（20.0–20.12 会导致每项目监看直接失败，扫描与条件式重建不受影响）。
设定页「CBM 图谱」卡片与侧边栏指示¶
安装并在设定页刷新后，会出现 「CBM 图谱」 卡片：上方为本次 DSH 启动以来的重建成效（排入 / 成功 / 失败、冷却与闸门省下的次数、累计耗时）；下方逐项目比对图谱 HEAD 与工作树 HEAD，落后项排在前面。卡片动作与 REST 控制面同源，共 7 条 REST 路由、18 个可调字段（详见仓库 docs/CONFIGURATION.md）。
侧边栏常驻指示：有落后项目时显示 warn 圆点；有重建 / 监看 / 扫描失败或项目已不在图谱时显示 error 圆点；全部同步时不渲染。纯指示，不可点击。
只读状态示例：
curl -s http://127.0.0.1:3080/api/codebase-watcher/state
curl -s http://127.0.0.1:3080/api/codebase-watcher/config
state有内容且status.revision为数字，表示 host 已至少完成一轮扫描。config.runtime含rebuildCooldownMs表示新世代模块已加载；若无该字段，重启dsh web清掉旧模块缓存。
状态文件：~/.dsh/codebase-watcher/state.json；keeper 日志：~/.dsh/codebase-watcher/keeper.log。
安装与启用¶
npm 上尚无该包名，勿使用裸名 add dsh-codebase-watcher（会 404）。任选 README 给出的完整规格，--profile web 须换成你本机的 profile 名：
# GitHub 规格
dsh plugin --profile web add github:WwW7olFWwW/dsh-codebase-watcher
# Release tarball（预打包，免本地建置）
dsh plugin --profile web add https://github.com/WwW7olFWwW/dsh-codebase-watcher/releases/latest/download/dsh-codebase-watcher.tgz
# 或在 DSH 插件市场搜索 dsh-codebase-watcher
codebase-memory-mcp 不在 PATH 时，卡片会显示「（未解析）」；可在设定页填写 cliPath。
建议关闭 CBM 无条件全量 auto_index，否则每个 session 仍可能白跑约 61 秒，并与本插件重建重复；插件检测到仍开启时会在卡片上留具名警告：
codebase-memory-mcp config set auto_index false
典型用法¶
首次启动：先观察再放大¶
第一次扫描会纳管 CBM 已索引的全部项目，落后项进入重建队列。三项目量级可能对应数分钟 CPU 与数 GB 峰值内存。README 建议在设定页先缩小范围：
includeProjects：只纳管一两个项目试跑。autoRebuild: false：仅观察落后判定是否正确，再开启自动重建。
两项在设定页修改后立即生效。
通过 REST 触发重建（与卡片等价）¶
条件式重建逻辑与设定页按钮一致；图谱已同步时不会排队。具体路径与请求体见 docs/CONFIGURATION.md。
卸载¶
dsh plugin --profile web remove dsh-codebase-watcher
rm -rf ~/.dsh/codebase-watcher
rm -f ~/.dsh/profiles/web/node_modules/dsh-codebase-watcher
profile 名与最后一行路径需按本机调整；卸载不会自动删除状态目录。
适用场景与注意¶
适合谁：已在 DSH 中接入 CBM、多项目共用同一 profile、需要可观测的「图谱是否跟上 HEAD」且希望只在落后时重建的开发者。
与相近做法的差异（README 摘要）：
- 同类插件
dsh-codebase-memory在 2026-10-20 查核时长期无新提交，Linux 路径解析问题且无覆盖配置。 - CBM
auto_index为每 session 全量重建；关掉则完全没有自动更新。 - 宿主 systemd timer 或一项目一 profile 会动宿主或复制多份配置，且与 DSH 由 systemd 常驻、
WorkingDirectory固定的部署方式不易契合。
安全与权限：插件在 当前 dsh web 进程的用户与权限 下运行，会执行 git 探针、调用 CBM CLI、监听项目目录。安装前应阅读仓库源码与 MIT 许可证，确认路径与 CLI 来源可信。
已知限制：以家目录为根的 project 不支持 CBM 监看（上游策略）；图谱结构声明不可单独作为落后证据；其余见 docs/LIMITATIONS.md。
结尾¶
dsh-codebase-watcher 把 CBM 图谱保鲜从「以为是最新的」变成可核对、可节流、可 REST 控制的流程：落后才重建，成效写在设定卡片上。DeepSeek Harness 生态主张「一切皆插件」；若你已在用 CBM，可按上文命令安装并在首次启动时先用 includeProjects 与 autoRebuild: false 验证判定。
