PR 变更追踪 Shyboy0499/dsh-pr-watch

dsh-pr-watch

状态许可证 DeepSeek Harness

报告你创建的拉取请求自上次检查以来发生的变化——已合并、已关闭或已过期。

dsh-pr-watch 是一个无依赖的 DeepSeek Harness（dsh）插件，它暴露一个 agent 工具，pr_watch。它跟踪你创建的每一个拉取请求，跨所有仓库——包括你从未克隆过的仓库——并且只告诉你自上次查看以来发生变化的内容。

状态：预发布。 实现已完成：该插件恰好注册一个工具，pr_watch，整个流水线都由测试套件覆盖。目前尚未发布到 npm，因此下面的安装命令今天无法使用。 包含它是为了明确预期路径，而不是因为它已经就绪。

- 设计：docs/superpowers/specs/2026-09-10-dsh-pr-watch-design.md
- 计划：docs/superpowers/plans/2026-09-10-dsh-pr-watch.md
- 剩余工作：路线图

目前可用的部分

| 部分 | 状态 |
| package.json、tsconfig.json、tsdown.config.ts、打包产物 | ✅ 已就位 |
| src/types.ts — PrRecord、Snapshot、Delta、常量 | ✅ 已就位 |
| src/delta.ts — 纯差异核心 | ✅ 已就位 |
| src/snapshot.ts — 加载、隔离、原子保存 | ✅ 已就位 |
| src/gh-exec.ts — gh 调用与记录映射 | ✅ 已就位 |
| src/tools/watch.ts — 报告渲染器 | ✅ 已就位 |
| src/tools/pr-watch.ts — pr_watch 工具 | ✅ 已就位 |
| src/index.ts — 插件入口（name、inject、apply） | ✅ 已就位，注册一个工具：pr_watch |
| CI — 类型检查、lint、格式、测试、构建 | ✅ 每个拉取请求均通过 |
| 已发布到 npm | ⛔ 尚未——安装命令无法使用 |

今天安装此插件会注册 pr_watch。仍然缺少的是发布本身，而不是工具。

此处有意不列出测试数量。它们在一个拉取请求内就过时了，而 CI 已经按提交报告它们——散文中的数字是没人会重新核对的声明。

为什么一个 agent 对你上次检查毫无记忆，所以每个状态问题都要从头重新推导。对一个 pull request 来说这没问题，对三十个就毫无用处了。摩擦不在于看到你的 pull request——而在于一遍又一遍地重新检查同样的那些，还得记住上次的状态是什么。

pr_watch 通过存储快照并报告增量来弥合这一差距。

功能

已实现，待发布。 以下所有内容均已构建并通过测试套件覆盖。它尚未发布到 npm，因此除了从检出安装之外没有其他安装方式——参见安装和当前可用功能。

| 行为 | 详情 |
| 已合并 | 你创作的 pull request 被合并了 |
| 未合并即关闭 | 与合并区分开来，不混为一谈 |
| 变为陈旧 | 14 天无活动（可配置） |
| 新发现 | 快照不知道的、处于打开状态的 pull request——包括一个被关闭后又重新打开的 |
| 未克隆的仓库 | 通过 owner/repo#number 跟踪，因此永远不需要本地检出 |
| 报告一次，之后静默 | 只要被修剪的结果仍被记住，合并和陈旧在后续检查中永不重复 |

工作原理

朴素的做法——获取打开的 pull request，与快照做差异比较——行不通。pull request 一合并就离开了打开列表，所以单纯的差异无法区分“已合并”和“未合并即关闭”，而且空结果看起来与失败的 gh 调用一模一样。

因此 pr_watch 分两个阶段获取：

1. 枚举你创作的所有打开的 pull request，一次调用完成。
2. 解析每一个离开该集合的快照条目，逐个进行，以了解其最终状态。

只有真正发生变化的 pull request 才会产生第二次调用——通常每次检查为零或一次。一个已离开打开集合但无法解析的条目会在每次检查时重试，直到其结果为已知，因此在此期间每次检查会增加一次调用。

安装

dsh plugin --profile PROFILE add dsh-pr-watch

将 PROFILE 替换为你实际运行的 dsh profile——该工具只会出现在那一个里。Desktop 应用管理着自己的 profile，所以在它的终端中完全省略该标志，让它以活动 profile 为目标：

dsh plugin add dsh-pr-watch

尚未发布，所以这两条命令目前都无法使用。 它们是预期的包发布后，路径会变为这样。

在此之前，请从代码检出安装。dsh plugin 会将参数转发给配置文件目录中的 pnpm，并将相对路径规范锚定到你运行它的目录，因此本地链接在所有平台上都能正常工作：

pnpm install && pnpm run build
dsh plugin --profile PROFILE add link:.

从仓库根目录运行该命令，并使用与上面相同的配置文件。

需要在 PATH 中安装并已认证的 GitHub CLI（gh）：

gh auth login

dsh-pr-watch 不存储自己的凭据。它完全依赖 gh 自身由密钥环支持的认证。

用法

让 agent 检查你的拉取请求，或直接调用该工具。

{
"staleDays": 14,
"all": false
}

典型输出：

✅ Merged (2):
octo/repo#41 — Add Russian locale (last activity 1 day ago) octo/repo#38 — Fix broken link (last activity 3 days ago)

⏳ Became stale (1):
octo/repo#29 — docs: clarify install steps (last activity 21 days ago)

🆕 Newly noticed (1):
octo/repo#44 — Add MCP server entry (last activity today)

再次运行它时，只会出现真正的变化。今天报告过的合并永远不会再次报告。

参数

| 参数 | 类型 | 描述 |
| staleDays | integer | 拉取请求在无活动多少整天后算作陈旧。默认值为 14。必须介于 1 和 3650 之间；0 会被拒绝，因为这很可能是错误。 |
| all | boolean | 列出所有打开的拉取请求，而不仅仅是发生变化的内容。在首次运行时很有用，因为此时所有内容都是“新注意到的”。默认值为 false。 |

配置

v1 通过上述工具的两个参数公开所有内容。它不读取设置文件，因此目前没有其他可配置项。

| 设置 | 默认值 | 在 v1 中可设置 | 用途 |
| staleDays | 14 | 是 — 工具参数 | 拉取请求在无活动多少天后被报告为陈旧 |
| pruneDays | 90 | 否 — 编译时常量 | 丢弃在这么久之前达到终态的条目 |
| forgottenDays | 180 | 否 — 编译时常量 | 被修剪的结果在被再次报告之前会被记住多久 |
| 快照路径 | $DSH_HOME/pr-watch/snapshot.json | 否——由环境派生 | 当 DSH_HOME 未设置时回退到 ~/.dsh/pr-watch/snapshot.json |

设计文档中还出现了另外两个键—— ignoreRepos 和一个用户可设置的 snapshotPath——但它们推迟到 v2 且未实现。要支持它们需要一个尚不存在的设置加载器，而且 ignoreRepos 还需要一条规则来从快照中清除被忽略的条目：一个从枚举中移除但仍保留在快照中的条目将永远无法解决，因此每次检查都会永远将其报告为 unresolved。完整推理见计划的改进部分。

行为说明

- 过期在状态转换时触发，且仅触发一次。 一个已经过期数周的拉取请求会在首次越过阈值时被报告，之后便保持安静。如果它出现新的活动，过期计时器会重置，之后可以再次被报告。
- 枚举失败时不写入任何内容。 如果那一次 gh search 调用失败，或其输出无法读取，快照将保持不变，这样待处理的变更就不会被静默标记为已见。解析阶段的失败范围更窄：每一个_已_确定的结果仍会被记录，而无法解析的条目保持 OPEN 并在下次检查时重试——在此期间不会再次被通告。
- 重新打开的拉取请求会再次被通告。 关闭并非最终状态：如果一个已关闭的拉取请求在下次检查时又处于打开状态，它会被报告为新注意到并恢复正常跟踪。合并被视为最终状态，因为它无法撤销。
- 快照以原子方式写入（先写临时文件，然后重命名），因此中断的写入绝不会留下一个被读取为“一切消失”的截断文件。
- 损坏的快照会被隔离，绝不会被丢弃。 它会被移动到 snapshot.json.corrupt-，工具会在其输出中说明这一点，包括之后检查失败时——该移动不可逆，因此那条消息是报告它的唯一机会。

已知限制

在两个检查之间打开_并_合并的拉取请求是不可见的。 它不在打开集合中（它已经合并），也不在快照中（拍摄快照时它还不存在），因此两个阶段都看不到它。这是按当前状态而非按活动窗口进行枚举的直接后果，而且只有在你检查不频繁时才可能发生。修复方案——活动窗口查询——已作为 v2 候选记录在设计文档中。

新评论和审查不会被报告。 像“已合并”这样的结果并不等同于“维护者回复要求修改”，而后者往往才是应该改变你下一步行动的东西。它被推迟而非被忽视：它需要一个单独的数据源和一个按条目的评论游标。
重新开启以枚举结果为准。 一个已关闭的拉取请求是否再次打开，是由与其他一切相同的 gh search 列表决定的。如果该列表已过时，并指向一个仍然关闭的拉取请求，它会被宣布为新注意到，而当它消失时，会被第二次报告为已关闭。用 gh pr view 确认每一次重新出现，会为每个候选项付出一次查询的代价，以防备罕见的不一致，因此这里选择信任该列表。

被修剪的结果会保留 180 天，然后被永久遗忘。 条目在达到终态 90 天后被删除，因此快照保持有界——但被删除的记录也是该结果曾被报告过的唯一证据。因此，一个被修剪的条目会留下一个两字段的记忆（状态以及它被修剪的时间），而一个后来解析为同一状态的离开，在该记忆持续期间不会被再次宣布。这正是“合并永远不会被报告两次”在修剪过程中依然成立的原因。一旦该记忆过期，键就真正消失了：如果枚举随后将其列为打开（过时的索引可能会这样），它会被宣布为新注意到，而之后的离开可能会第二次报告该结果。

CI 状态不会被报告。

每个 GitHub 身份一个快照。 在第二个账户下运行会共享一个快照，并产生虚假的“新注意到”条目。

路线图

设计已完成，工作被拆分为十五项任务，见实施计划。

| 状态 | 任务 |
| ✅ | 1–3 — 脚手架、类型、测试夹具 |
| ✅ | 4–7 — 纯 delta.ts 核心 |
| ✅ | 8–10 — snapshot.ts：路径解析、加载、隔离、原子保存 |
| ✅ | 11–12 — gh-exec.ts：调用、记录映射、错误处理 |
| ✅ | 13–14 — renderWatch() 和 pr_watch 工具，然后注册 |
| ✅ | 15 — 构建接线、README、产物检查 |

剩余工作是发布，而不是功能：该包尚未发布，因此 dsh plugin --profile web add dsh-pr-watch 尚无法解析。

开发

pnpm install
pnpm run build # tsdown → lib/
pnpm test # vitest — 无网络访问
pnpm run verify:live # 可选：驱动真实的 gh 访问 GitHub
pnpm run lint # oxlint
pnpm run typecheck # tsc --noEmit
pnpm run format # prettier --write .

测试套件不发起网络请求，也从不运行 gh。delta.ts 和 tools/watch.ts 是纯的——没有文件系统、没有网络、没有时钟——并且每个 IO 模块都将其依赖项作为参数，因此整个流水线由夹具和注入的执行器驱动，而不是模拟对象。

这种隔离有一个盲点，而且它不是理论上的：一个夹具编写与代码相同的错误假设无法被它捕获。gh pr view 被请求了一个它并不存在的字段，因此每次针对真实 CLI 的解析都失败了，而每个模拟测试却都通过了。pnpm run verify:live 填补了这一空白。它需要 gh 已认证，会发起真实的 API 调用，并检查固定装置无法检查的内容：参数列表是否被接受、实时负载是否映射正确，以及完整检查是否在第一次运行时写入快照并在第二次运行时保持安静。它适合在发布前运行，而不是在每次提交时运行。

要检查构建产物而不是源代码，请运行 pnpm run build，然后加载 lib/index.js：它必须导出 name、inject、apply，以及一个恰好包含一个条目的 tools 数组。pnpm pack 应生成一个 tarball，其中仅包含 lib/index.js、cordis.patch.yml、package.json、README.md、LICENSE 和 SECURITY.md。

在 Windows 上，pnpm 使用符号链接组织 node_modules，这需要开发者模式或提升权限的 shell；否则，安装会因 EPERM 而失败。npm 缓存和存储通过 .npmrc 重定向到仓库内部，因此不会在检出目录之外写入任何内容。

许可证

MIT