upstream-watch：上游盯梢机制
September 8, 2026 · View on GitHub
一句话：先声明"挂在哪些上游的哪些东西上"，上游出新 tag 时自动 diff 这些挂点，把变化变成 issue，由维护者按 issue 适配。避免"事后考古"。
为什么要它
DSH 0.1.1 大更新落地时，靠一次临时考古（tag 间 compare + 读实现日记）才知道它动了会话历史/Remote 传输/插件设置/存储结构。这种更新不是机械层换版本号，是契约层变化，靠"偶尔想起去看看"一定会漏。
机制（三层）
- 挂点声明：
upstream.json—— 每个上游：pin 的 tag + 关心的路径 + 该路径变化影响插件的哪部分。这是"在哪里关联了它"的唯一事实源。 - 检测：
scripts/upstream-watch.mjs（零依赖，Node ≥18）——拉两个 tag 的全文件树做集合差（比 compare API 的 300 文件上限可靠），命中挂点路径才报告。 - 落地：
- GitHub Actions 日更 cron（
.github/workflows/upstream-watch.yml，频率可自改）自动跑--apply：开 issue（labelupstream-watch，同题去重）+ 更新 pinned 并自动提交。没变化=零输出零提交（只发变化时的报告，平时安静）。 - 维护者消费：
gh issue list --label upstream-watch→ 读官方.agents/notes对应笔记解读变更意图 → 评估影响面 → 适配修复 → 关 issue。 - 帮第三方插件挂靠：
plugin_maker_vet对任何插件目录附「挂靠建议」（用了哪些官方协议面 → 建议挂哪些路径），插件作者把清单写进自己的upstream.json即可复用本机制。
- GitHub Actions 日更 cron（
手动命令
$env:GH_TOKEN = gh auth token # 本地用 gh 的凭证
node scripts/upstream-watch.mjs # dry-run：只看报告
node scripts/upstream-watch.mjs --apply # 开 issue + 更新 pinned（然后 push 交人）
成熟模式参照
这个"下游盯上游变更 → 自动开 issue"不是我们发明的，是 GitHub 上成熟维护方式：
- Gumball12/yuki-no：GitHub Action，跨仓追踪 head 仓库 commit → 在目标仓建 issue（文档翻译项目用）。
- llm-d/llm-d 的 upstream-monitor workflow：同类上游监控。
- Vue 翻译生态 Ryu-Cho：追踪上游文档变更批量建 issue。
为什么没直接用现成工具：我们挂的是 monorepo 内具体路径而非 npm 依赖，Dependabot/Renovate 覆盖不到"tag + 路径"这个组合；官方同时发 tag 与 GitHub Release（release notes 是变更线索），但 release notes 是自然语言、且只在发版时出现——按 tag 拉全文件树做集合差才能精确落到"我挂的那条路径变了没有"，80 行脚本比引入黑盒更可控。
当前挂点（v1.5）
原则：哪里用到协议就挂哪里——只挂 maker 自己使用的协议点：现行形态（插件/skill/preset 注入/settings/UI 槽位/session 持久化与格式）与路线图形态（workflow/定时/后台任务/goal/hook），全部挂官方。
| 上游 | pin | 关心（按面） |
|---|---|---|
| deepseek-ai/deepseek-harness | dsh-v0.1.3-alpha.2 | 插件面：bundle/client/settings/web；宿主服务面：host/webserver；协作面：skill/preset/tools；会话面：session（0.1.3-alpha.1 起 SessionHandle + 格式 v2）；路线图形态：workflow/schedule/jobs/goal/guard/hooks；契约源：docs/ + .agents/notes |
| omdsh-dev/DSH-better-sidebar | v0.16.1 | src（betterSidebar 服务契约） |
备注：@deepseek-ai/dsh-tools 出自官方 monorepo，随官方 tag 一并覆盖（其契约文档在官方 docs/tool-catalog）。任务看板类上游与 maker 的协议使用面无关，不挂。packages/host/apiproxy 在 0.1.2 已移除，挂点里不再保留（迁移事实卡负责提示该服务不存在）。