Shyboy0499/dsh-pr-watch

dsh-pr-watch

Status
License
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、bundle | ✅ 已就位                                       |
| src/types.ts — PrRecord、Snapshot、Delta、常量      | ✅ 已就位                                       |
| src/delta.ts — 纯 diff 核心                               | ✅ 已就位                                       |
| 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 — typecheck、lint、format、test、build                   | ✅ 每个拉取请求均为绿色                         |
| 已发布到 npm                                                | ⛔ 尚未——安装命令无法使用                       |

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

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

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

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

功能

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

| 行为                           | 详情                                                                  |
| ------------------------------ | --------------------------------------------------------------------- |
| 已合并                     | 你提交的一个 pull request 被合并了                                     |
| 未合并即关闭               | 与合并区分开来，不会混为一谈                                          |
| 变为陈旧                   | 14 天无活动（可配置）                                                 |
| 新注意到                   | 出现了一个快照不知道的 pull request                                   |
| 未克隆的仓库               | 通过 owner/repo#number 跟踪，因此永远不需要本地检出                 |
| 报告一次，之后静默         | 合并和陈旧状态在后续检查中不会重复报告                                |

工作原理

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

因此 pr_watch 分两个阶段获取：

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

只有真正发生变化的 pull request 才会触发第二次调用——通常每次检查为零或一次。

安装

dsh plugin --profile web add dsh-pr-watch

尚未发布，所以这条命令目前无法使用。 这是该包发布后的预期
安装方式。

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

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

请从仓库根目录运行。

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

gh auth login

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

用法

让 agent 检查你的 pull request，或直接调用该工具。

{
"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 | number  | 拉取请求在多少天无活动后算作过期。默认为 14。                                                            |
| all       | boolean | 列出所有打开的拉取请求，而不是只列出发生变化的部分。在首次运行时很有用，此时所有内容都是“新注意到的”。默认为 false。 |

配置

v1 通过上面这两个工具参数暴露所有配置。它不读取任何
设置文件，因此目前没有其他可配置的内容。

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

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

行为说明

- 过期在状态转换时触发，且仅触发一次。 一个已经过期数周的拉取请求会在首次越过阈值时被报告，之后便保持安静。如果它出现新的活动，过期计时器会重置，之后可以再次被报告。
- 抓取失败不会写入任何内容。 如果 gh 中途失败，快照会保持原样，因此待处理的更改不会被静默标记为已见。
- 快照以原子方式写入（先写临时文件，再重命名），因此中断的写入绝不会留下一个被读取为“一切消失”的截断文件。
- 损坏的快照会被隔离，绝不会被丢弃。 它会被移动到 snapshot.json.corrupt-，并且工具会在其输出中说明这一点。另一种做法——静默重置——会丢失待处理的更改，且无法将其与“什么都没发生”区分开来。

已知限制

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

新评论和审查不会被报告。 “已合并”这样的结果与“维护者回复要求更改”并不相同，而后者往往才是应该改变你下一步行动的依据。这是被推迟而非被忽视：它需要单独的数据源和每个条目的评论游标。

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 — no network access
pnpm run lint         # oxlint
pnpm run typecheck    # tsc --noEmit
pnpm run format       # prettier --write .

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

要检查构建产物而不是源代码，请运行 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