前言¶
在 DeepSeek Harness (DSH) 的生态中，Stacked PR（堆叠 PR）常用于管理具有依赖关系的多层级代码变更。然而，当底层 PR 需要修改时，变基操作会重写提交 SHAs，导致原先的 CI 验证记录失效。如果没有额外的校验，开发者可能误以为“测试通过”并直接合并，从而引入未经验证的代码。
dsh-stack 是 DeepSeek Harness 的一个 Cordis 插件，它为堆叠 PR 工作流提供了一套强制性的安全策略。它覆盖了从同步、验证到合并和清理的全流程，通过 SHA 绑定的验证记录，确保每次合并前的测试状态是可追溯且有效的。这是对 GitHub 分支保护规则的防御深度补充，而非替代品。
核心功能¶
dsh-stack 在命令执行过程中会依次校验以下八个安全点：
-
G-ENV（环境与认证校验）
确保当前环境满足要求：GitHub CLI 版本 >= 2.90.0，gh-stack扩展版本 >= 0.1.0，且具备 GraphQL 认证权限。 -
G-TREE（工作区清洁校验）
在执行同步或变基前，通过git status --porcelain检查工作区。若存在未提交的修改，操作将被阻止。 -
G-TOPO（拓扑结构校验）
验证 PR 依赖链的完整性，拒绝跨 Fork 仓库、循环依赖或孤立节点的存在。 -
G-TEST（重写层测试校验）
当变基触达某一层时，强制运行该层的本地测试套件（默认pnpm test或npm test），并将测试结果写入验证记录。 -
G-VERIFY（验证记录校验）
拒绝合并当前 Head SHA 没有对应验证记录的分支。若记录缺失、过期或失败，合并请求将被阻塞。 -
G-LAND（合并资格校验）
检查 CI 构建状态是否为绿色，以及代码审查是否已获批准。 -
G-POLL（合并状态轮询）
在执行合并后，持续轮询 GitHub API 确认分支状态确认为MERGED。 -
G-DEL（零依赖清理校验）
在删除分支前，严格检查该分支是否存在开放依赖。只有依赖计数为 0 时才允许删除。
安装与配置¶
安装¶
通过 npm 安装插件：
dsh plugin --profile default add dsh-stack
前置条件¶
在安装前，请确保环境满足以下要求：
* Node.js >= 22
* GitHub CLI >= 2.90.0
* gh-stack 扩展 >= 0.1.0
配置测试命令¶
默认情况下，插件使用 pnpm test 或 npm test。若项目使用其他测试框架，需在配置文件中指定验证命令。配置文件路径为 $DSH_HOME/profiles/default/cordis.patch.yml：
- replace:
- id: stack
config:
validationCommand: ['pytest', '-q'] # 自定义测试命令，以数组形式传入
validationTimeoutMs: 600000 # 设置超时时间（毫秒）
注意：更改
validationCommand会使之前的验证记录失效，因此必须重新运行验证流程。
验证安装¶
安装完成后，可以通过以下命令确认配置已生效：
dsh --profile default --dump-config | grep stack
适用场景与注意事项¶
适用场景：
* 使用 gh stack 进行多层级 PR 管理的开发者。
* 依赖 CI 结果来决定代码合并权的团队。
* 希望在本地命令行层面增加一层安全防护的 DSH 用户。
注意事项：
* 防御深度：该插件是防御策略的一部分，不应替代 GitHub 仓库的分支保护规则。
* 构建脚本限制：如果使用 pnpm >= 10，Git 依赖的构建脚本可能会被阻止。若安装失败，需将包名添加到 $DSH_HOME/profiles/default/pnpm-workspace.yaml 的 allowBuilds 字段中。
* 记录失效：修改验证命令会导致历史记录失效，必须重新测试。
