Harzva/dsh-pr-guardian

dsh-pr-guardian

一个用于接收你自己拉取请求反馈的 DSH 管理收件箱，由 Harzva 维护。版本 0.2.0-alpha.1 面向 DSH 0.1.1-rc.2、Cordis 4.0.1、React 18.2.0 和 Node 24+。已在 macOS 上测试。

侧边栏会打开一个可搜索的反馈面板。它会发现当前活跃 gh 账户所创建的开放 PR，对普通评论、正式评审和评审线程（包括嵌套评论）进行分页，并优先处理人类反馈、收藏、CI 失败和冲突。GitHub 文本是数据，绝不是可执行指令。

本地进度与版本绑定：被编辑过的反馈会再次变为待处理。收藏以及 pending / investigated / awaiting_user 状态在重启后仍会保留；已解决的线程和被取代的评审会被区分开来。原始评论正文会在适配器内进行哈希处理，不会被持久化。管理 API 没有 GitHub 写操作。

安装发布产物

要求：已认证的 GitHub CLI（gh auth status）、Git、Node 24+，以及上述精确的 DSH 兼容组合。收件箱不需要模型 API 密钥。

dsh plugin --profile web add https://github.com/Harzva/dsh-pr-guardian/releases/download/v0.2.0-alpha.1/dsh-pr-guardian-0.2.0-alpha.1.tgz
dsh --profile web

在侧边栏中打开 PR Guardian，然后点击 刷新 GitHub。发布 tarball 包含编译后的 Host、Client 和 Typert 导出。GitHub 源码快捷方式安装是一条独立且未经核实的交付路径。

共享的 Codex / DSH 工作流

From this source checkout after npm ci && npm run build:
node bin/guardian-management.mjs sync
node bin/guardian-management.mjs list
Or use guardian-management from the installed package's bin directory.

默认状态目录：$DSH_HOME/dsh-pr-guardian/management（DSH_HOME 默认为 ~/.dsh）。CLI 接受 --state-dir DIR；插件的 stateDirectory 设置可以指向同一目录。使用相同的目录即可在 Codex 和 DSH 之间共享进度。

CLI 的 action 命令接受一个 JSON 参数。收藏示例：

node bin/guardian-management.mjs action '{"kind":"favorite","caseId":"owner/repo#123","favorite":true}'

反馈进度操作需要 kind=progress、caseId、eventId、精确收集到的 version，以及 status=pending|investigated|awaiting_user。过期的版本会被拒绝。本地已调查状态不会解决 GitHub 讨论。反馈读取失败会保留先前的证据；离开已创建开放队列的 PR 在被视为已关闭之前需要经过验证。
对于 Codex 调度，配置一个每小时的本地自动化来运行 CLI，按优先级顺序检查待处理的反馈，在诊断后准备隔离的候选修复并记录与版本绑定的进度。仅在发生有意义的变化或需要做出决策时通知。调度由 Codex 负责；DSH 面板按请求刷新，不会安装隐藏的定时器。开发工作站的私有适配器和自动化不包含在此公开包中。

状态文件使用仅所有者权限、原子替换和独占写入锁。WRITER_BUSY 表示另一个进程拥有该目录。如果进程崩溃，在仅移除该锁之前，请验证 writer.lock 中的 PID 已不再运行。切勿通过清除 management.json 来解决争用。搜索被限制为 1,000 个已创建的开放 PR，反馈分页也受到限制；超出限制会报告失败，而不是将部分发现静默视为完整。

验证与范围

npm ci
npm run check
npm run pack:dsh
npm run verify:dsh-offline

离线验证器会打包全新代码，将该确切 tarball 安装到临时 DSH_HOME 中，冷启动真实的 Web 运行时，演练严格的管理 RPC 和版本冲突拒绝，检查重启持久性，移除插件并验证剩余的 Web 配置文件能够启动。它使用合成元数据，不调用 GitHub。单独的实机 UI 冒烟测试会演练经过身份验证的反馈同步和本地面板操作。

此管理预览并非完整修复/发布计划的完成。两阶段审批、通用候选执行和推送后编排仍在计划中。下面遗留的生成文件 CLI 仍单独设有关卡，默认禁用推送。有关这一区别，请参见 docs/release-0.2/PLAN.md 和原始开发计划。

遗留生成文件试运行 CLI

- 使用 gh search prs 发现开放 PR。
- 可选地使用现有的 Codex gh_pr_watch.py 快照适配器。
- 仅当 GitHub 报告冲突时，在临时克隆中试运行变基。
- 对于 awesome-dsh-plugin，仅通过恢复当前上游版本并重新生成它们来解决 README.md 和 README.zh.md。
- 记录 JSONL 观察结果并生成七日报告。
- 当确定性策略拒绝冲突时，向只读、临时的 Codex Agent 寻求建议。
- 在任何推送之前，要求全局和仓库级别的选择加入，以及确切观察到的 head 租约。

设置

要求：macOS、Node.js 24+、Git、GitHub CLI，以及经过身份验证的 gh 会话。

gh auth login -h github.com --git-protocol ssh
npm test
node bin/dsh-pr-guardian.mjs doctor
node bin/dsh-pr-guardian.mjs monitor --once
node bin/dsh-pr-guardian.mjs report --days 7
仅当需要机器本地状态目录、不透明的 localRef → 绝对克隆路径 repoMap，或外部监视器命令时，才将 guardian.local.example.json 复制为 guardian.local.json。本地文件被 Git 忽略，不得提交；公共仓库规则只能包含不透明的 localRef，绝不能包含机器路径。

命令

doctor
discover
status --pr URL
analyze --pr URL
monitor --once [--pr URL] [--no-agent]
report --days 7
install-launchd
uninstall-launchd

--push 存在于后续受控阶段，但随附的全局和仓库开关均为 false。传入该标志无法绕过任一策略门禁。

七天门禁

保持推送禁用至少七个自然日。审查每一条 auto_fixable_generated 观察结果。仅当报告不包含任何误分类、所有生成的候选均通过其配置的检查，且人工接受抽样差异后，才启用推送。

完整契约见 docs/01-需求分析.md、docs/02-架构设计.md 和 docs/03-开发计划.md。