Grove-ovo/dsh-stack

dsh-stack

DeepSeek Harness 中 GitHub 堆叠式 PR（Stacked PRs）工作流的业务级安全监理员与自动化状态机。

License: MIT
Cordis: Plugin
Host: DeepSeek%20Harness

dsh-stack 是运行在 DeepSeek Harness 上的 Cordis 插件，为多层 PR 依赖链（Stacked PRs，堆叠式 PR）在本插件命令范围内执行安全策略：每次同步、合入与清理都经过默认强制、仅允许显式受限豁免（见 --self-approve）的守门断言，绑定提交 SHA 的验证记录让“测过一次”可按提交查证。这是叠加在 GitHub 分支保护规则（required checks、过期审批撤销）之上的纵深防御，而非其替代——其他工具与网页操作仍由仓库规则约束。

📖 30 秒电梯演说：用 3 层小楼理解 Stacked PR

想象一下用堆叠式 PR 开发一个大型功能，就像盖一座 3 层小楼：
- 1 楼 (PR #101)：底层数据库迁移与表结构
- 2 楼 (PR #102)：后端业务 API 端点（基于 1 楼构建）
- 3 楼 (PR #103)：前端 UI 控制台（基于 2 楼构建）

主干分支 (master)
└── PR #101 (feat/auth-db)
└── PR #102 (feat/auth-api)
└── PR #103 (feat/auth-ui)

生产中的真实灾难
当 1 楼在代码审查（Code Review）中收到修改意见时：
1. 修改 1 楼的代码会改变基底 Commit SHA。
2. 随后执行 gh stack rebase / gh stack push 等同步操作，会重写受影响的上层提交并更新远端分支。
3. 虚假安全感与致命盲区（The Fatal Blindspot）：开发者看到绿色的 "Sync Success" 提示，往往条件反射地点击 Merge 合入。
4. 灾难发生：Commit SHA 改写后，既有 CI 结果不再证明新的 HEAD（GitHub 要求 required checks 针对最新提交）；若仓库启用了过期审批撤销或“最近推送需重新审批”等规则，既有 Approve 也可能失效或需要重新审批。如果仓库保护规则没有覆盖这一风险，新的 HEAD 就可能在未经充分重新验证的情况下被合入 master。

dsh-stack 如何拯救你
GitHub 官方 gh stack 提供底层管道 —— gh stack rebase（底层修改后的级联变基）、gh stack push、gh stack sync（拉取、调和、trunk 移动时变基并同步 PR 状态）。dsh-stack 是架在管道之上的工地安全监理员：本地工作树不干净时中止操作，变基触及的每一层都重跑本地测试并把结果绑定到被测提交，SHA 改写后提示审批可能需按仓库规则重新验证，合入前轮询 GitHub 确认 MERGED，且仅在下游依赖数确证为 0 时删除分支——删除本身也带条件，分支移动即保留。

⚡ 快速上手与前置准备

1. 环境前置依赖
dsh-stack 基于 GitHub 官方 CLI 及其官方扩展运行，首次使用前请确保完成以下配置：

1. 确认已安装 GitHub CLI（要求版本 >= 2.90.0）
gh --version

2. 安装 GitHub 官方 gh-stack 扩展（要求版本 >= 0.1.0）
gh extension install github/gh-stack

3. 登录并授权 GitHub 凭证
gh auth login

[!NOTE]
如果通过源码构建运行 DeepSeek Harness，在启动 pnpm dsh web 之前请务必先在宿主 monorepo 执行 pnpm run build，以生成 Web 端所需的 client bundle，避免遇到 MissingClientBundleError。

2. 安装到 DeepSeek Harness

从 npm 安装（推荐 —— 预构建产物，无需任何构建权限）：

dsh plugin --profile default add dsh-stack

从 GitHub 安装（拉取源码并通过 prepare 脚本构建）：

dsh plugin --profile default add github:Grove-ovo/dsh-stack

[!NOTE]
pnpm ≥ 10 会在用户显式允许前阻止 git 依赖的构建脚本。若首次 add 失败，请将 pnpm 提示的包名键复制到 profile 目录下 pnpm-workspace.yaml（$DSH_HOME/profiles/default/pnpm-workspace.yaml）的 allowBuilds 中后重试。建议锁定 commit（github:Grove-ovo/dsh-stack#）以保证可复现安装。

从本地检出安装（开发模式）：

git clone https://github.com/Grove-ovo/dsh-stack.git
cd dsh-stack && pnpm install   # prepare 会自动构建 lib/
dsh plugin --profile default add ./dsh-stack

配置验证命令（可选）：

默认每层使用 pnpm test 验证（缺失时回退 npm test）。使用其他测试命令的项目可在 profile 的 cordis.patch.yml（$DSH_HOME/profiles/default/cordis.patch.yml）中配置：

- replace:
- id: stack
config:
validationCommand: ['pytest', '-q']     # 可执行文件 + 参数数组
validationTimeoutMs: 600000             # 默认 120000

验证记录按命令打指纹：修改 validationCommand 会使既有验证记录失效，层必须在新命令下重新验证后方可合入。

以上任一安装方式都会自动激活 bundle（dsh.bundle 清单会自动并入 profile 层栈），dsh plugin --profile default remove dsh-stack 可移除。验证 Profile 组合配置：

dsh --profile default --dump-config | grep stack

🛡️ 八维安全守门体系 (The 8-Point Guard System)

dsh-stack 在 PR 全生命周期中执行八道守门断言 —— 默认对经由本插件命令的全部操作强制生效，仅允许显式且作用域受限的豁免：

┌─────────────────────────────────────────────────────────────────────────┐
│                        dsh-stack 八维守门架构                           │
├───────────────┬─────────────────────────────────────────────────────────┤
│ 1. G-ENV      │ 环境与凭证门禁：gh >= 2.90.0, extension >= 0.1.0, 鉴权  │
│ 2. G-TREE     │ 干净工作树门禁：git status --porcelain 同步前强拦截     │
│ 3. G-TOPO     │ 拓扑 DAG 门禁：严禁跨 Fork、严禁依赖环路与断层孤儿栈     │
│ 4. G-TEST     │ 改写层强制重测：逐层检出并执行本地单元测试套件          │
│ 5. G-VERIFY   │ 验证记录门禁：每层必须持有绑定提交 SHA 的通过记录      │
│ 6. G-LAND     │ 合入资格门禁：CI 全绿且获得充足 Review Approval        │
│ 7. G-POLL     │ 状态确认门禁：主动轮询探测 GitHub 确已进入 MERGED 状态   │
│ 8. G-DEL      │ 零依赖分支回收：下游待处理 PR 严格为 0 才允许删除分支   │
└───────────────┴─────────────────────────────────────────────────────────┘

1. G-ENV（环境与凭证门禁）：强校验 GitHub CLI 版本（$\ge 2.90.0$）、官方扩展版本（$\ge 0.1.0$）与 GraphQL API 鉴权。拦截 CLI 的推荐安装文案，避免误判为就绪状态。
2. G-TREE（干净工作树门禁）：在 /stack-sync 执行变基前，通过 git status --porcelain 执行 Pre-flight 检查。若工作区存在未提交的脏代码，强行阻断并引导提交，防止代码丢失。
3. G-TOPO（拓扑 DAG 门禁）：全面检验依赖图谱结构。拒绝跨 Fork 仓库混合堆叠，检测死锁环路依赖，拒绝中间断层的孤儿 PR 栈。
4. G-TEST（改写层强制重测）：变基触及分支后，自动化逐层检出并强制触发项目的测试套件（pnpm test，缺失时平滑回退 npm test；命令与超时可配置），结果写入绑定提交 SHA 的验证记录。现场恢复为尽力而为且绝不静默：恢复失败会显式上报。
5. G-VERIFY（验证记录门禁）：/stack-land 拒绝合入任何缺少“当前 head SHA 通过记录”的开放层。缺失、过期（head 移动）与失败各有独立阻塞码；修复测试后运行 /stack-verify 原地重测——无需再触发变基与推送。
6. G-LAND（合入资格门禁）：在所有开放层上收集全部违规（状态、CI、审批）后再判定——被豁免的类别（如 --self-approve 豁免审批）绝不会掩盖其他类别的违规。天然兼容多层链中已被上一轮提前合入的基底 PR。
7. G-POLL（状态确认门禁）：执行官方合入后，轮询 GitHub GraphQL 确认所有目标 PR 变为 MERGED 后才进入分支清理。堆叠合入可能进入 GitHub 合并队列，因此如实报告观察到的状态而非把“尚未合并”一律报为失败。
8. G-DEL（零依赖分支回收）：向远端发起查询，严格在依赖当前分支的下游活跃 PR 数量精确为 0 时才执行删除 —— 且每次删除本身也是带条件的：远端使用 --force-with-lease=:、本地使用 update-ref -d  ，分支若在合并后追加了提交（或在检查与删除之间被他人推送）则保留而非销毁。若查询异常或存在下游依赖，则保留分支并发出告警（Fail-Safe）。/stack-cleanup 可幂等重跑此清理以完成部分合入后的收尾。

💻 Slash 命令完整参考指南

| 命令 | 语法 | 角色 | 触发的核心守门 | 机器可读输出 |
|---|---|---|---|---|
| /stack-doctor | /stack-doctor [--json] | 运行环境体检 | G-ENV | DoctorOutputJson |
| /stack | /stack [pr...] [--json] | 拓扑探查与挂载 | G-ENV, G-TOPO | StackOutputJson |
| /stack-sync | /stack-sync [--dry-run] [--json] | 同步·重测·记录 | G-ENV, G-TREE, G-TEST | SyncOutputJson |
| /stack-land | /stack-land [--dry-run] [--limit ] [--self-approve] [--json] | 带门禁的按序合入 | G-ENV, G-VERIFY, G-LAND, G-POLL, G-DEL | LandOutputJson / LandPreviewJson |
| /stack-verify | /stack-verify [--json] | 原地重测（不 rebase/不推送） | G-ENV, G-TOPO, G-TEST | VerifyOutputJson |
| /stack-cleanup | /stack-cleanup [--json] | 幂等分支清理 | G-ENV, G-TOPO, G-DEL | CleanupOutputJson |

详细操作与输出示例

1. /stack-doctor（环境与凭证体检）
对本地工具链与网络连通性进行全链路端到端诊断：
/stack-doctor
正常输出示例：
Stack Doctor Diagnostic Report

| Component | Status | Details |
|---|---|---|
| GitHub CLI (gh) | ✅ Ready | gh version 2.92.0 (2026-04-28) |
| gh-stack Extension | ✅ Ready | gh stack version 0.1.1 |
| Auth & API Status | ✅ Authenticated | User: alice |

2. /stack [pr...]（栈探查与关联挂载）
渲染当前栈的 ASCII 树状图。支持空格或逗号分隔，智能兼容 # 前缀：
自动基于当前 Git 分支探查关联栈
/stack

显式挂载关联一组 PR
/stack 101 102 103
/stack #101, #102, #103
终端树形图示例：
📦 GitHub Stack Topology (Trunk: master)

master (Trunk)
│
├─ #101 [feat/auth-db] (APPROVED | CI: SUCCESS)
│    │
│    └─ #102 [feat/auth-api] (APPROVED | CI: SUCCESS)
│         │
│         └─ #103 [feat/auth-ui] (CHANGES_REQUESTED | CI: PENDING)

3. /stack-sync（同步 · 重测 · 记录）
经 gh stack sync 同步堆叠（拉取、调和、trunk 移动时变基并推送），随后对触及的每一层重跑本地测试并记录绑定 SHA 的结果：
仅仿真预览，不变更 git 状态
/stack-sync --dry-run

同步堆叠,重测触及层并记录结果
/stack-sync
测试失败熔断示例：
🛑 Sync Halted: Validation Failure on Layer #102

Branch feat/auth-api failed tests after rebase.
AssertionError： Token validation expected 200， received 401

Safety Guard Triggered: Fix test errors on branch feat/auth-api before landing.

4. /stack-land（按序合入与安全分支回收）
拓扑顺序自底向上合入 PR，轮询确认合入成功后，安全删除零依赖分支：
预览合入顺序与受影响分支（未获批也能预览，守卫结论会包含在预览中）
/stack-land --dry-run

仅合入底部前 2 个 PR
/stack-land --limit 2

单人维护者：显式豁免评审审批要求（CI 等其余守卫仍然强制执行）
/stack-land --self-approve

全量合入整栈
/stack-land
合入报告示例：
🚀 Official Stack Landed Successfully

Merged 2 PRs in order (limited from 3).

Branch Cleanup Summary:
- ✅ Deleted clean branch: feat/auth-db
- ⚠️ Retained branch: feat/auth-api (Branch "feat/auth-api" still has 1 open PR(s) depending on it.)

[!NOTE]
--self-approve 的存在是因为 GitHub 拒绝本人审批自己的 PR。它仅豁免评审审批守卫（CI、拓扑、验证记录与合并状态校验仍然强制），输出会附带单人维护者警告横幅，--json 输出中标记 selfApproved: true。团队协作仓库应依赖真实同伴评审，不应使用此选项。

🤖 机器可读 JSON 模式 (--json)

全部 6 条命令均原生支持追加 --json 参数，专为 Harness 自主智能体或自动化 CI 流水线设计：

预览输出显式区分意图

/stack-land --dry-run --json 绝不把动作描述为已执行，而是返回带结论与机器可读原因的预览信封：

{
"mode": "preview",
"canLand": false,
"plannedPrNumbers": [101, 102],
"blockers": [{ "code": "GUARD_ERR_UNVERIFIED", "prNumber": 101, "message": "..." }],
"cleanupCandidates": ["feat/auth-api"],
"wouldRetain": ["feat/auth-db"]
}

智能体依据稳定的守卫码（GUARD_ERR_UNVERIFIED、GUARD_ERR_VALIDATION_STALE、GUARD_ERR_CI_FAILED、GUARD_ERR_NOT_APPROVED 等）行动，而无需解析英文错误文案。

✅ 验收标准

本插件对自己的行为承诺（每条均有测试覆盖）：

1. 参数拒绝：非法参数（--dryrun、--limit 0）导致 零次 link/sync/merge/delete 调用。
2. 豁免隔离：--self-approve 仅豁免评审审批；存在任何 CI 失败或缺失/过期的验证记录时，合并调用保持 零次。
3. 跨命令验证：sync 因测试失败中止后，/stack-land 被记录的失败阻断；/stack-verify 通过后方可合入。没有当前 head SHA 的通过记录，合并绝不执行。
4. 变基后记录绑定：记录绑定变基后的 SHA——刚同步完的栈立即可合入，绝不自我过期。
5. 幂等恢复：部分合入后，/stack-cleanup 无需重新合并即可完成清理，并如实报告合并状态而非笼统超时。

/stack-doctor --json
/stack --json
/stack-sync --dry-run --json
/stack-land --limit 2 --json

JSON 返回结构体示例 (SyncOutputJson)
{
"ok": true,
"dryRun": false,
"trunk": "master",
"syncedLayers": [
{ "prNumber": 101, "headRef": "feat/auth-db", "newSha": "8a3f91c" },
{ "prNumber": 102, "headRef": "feat/auth-api", "newSha": "b4e120d" }
],
"validationResults": [
{ "prNumber": 101, "headRef": "feat/auth-db", "passed": true, "output": "Tests passed" },
{ "prNumber": 102, "headRef": "feat/auth-api", "passed": true, "output": "Tests passed" }
]
}

🏛️ 技术架构与测试保障

┌─────────────────────────────────────────────────────────┐
│                      dsh UI / Agent                     │
│         Slash Commands: /stack, /stack-sync, ...        │
└────────────────────────────┬────────────────────────────┘
│ CommandInvocation
┌────────────────────────────▼────────────────────────────┐
│              dsh-stack Runtime Engine                   │
│   ├── GuardEngine (8 维守门断言 / 修复指引)             │
│   └── StackOrchestrator (DAG 拓扑解析 & 状态机调度)     │
└────────────────────────────┬────────────────────────────┘
│ depends on interface
┌────────────────────────────▼────────────────────────────┐
│                    GhClient Interface                   │
│         完全解耦的底层抽象层，支持 100% Mock 隔离单测   │
└──────────────┬───────────────────────────┬──────────────┘
│ (Production)              │ (Test Fixture)
┌──────────────▼─────────────┐ ┌───────────▼──────────────┐
│  ExecGhClient (execFile)   │ │  MockGhClient (In-Memory)│
│  - 子进程超时熔断控制      │ │  - 完整测试套件           │
│  - AbortSignal 强杀传播    │ │  - 100% 确定性内存运行   │
│  - 非快进强拉远端跟踪分支  │ │  - 3~5 层复杂 PR 拓扑注入│
│  - Detached HEAD 现场恢复  │ │  - 瞬时模拟轮询状态流转  │
│  - 零依赖失败安全清理      │ └──────────────────────────┘
└────────────────────────────┘

运行测试套件

测试套件采用 Node.js 原生测试运行器编写，零 npm 运行时依赖；npm test 会先构建 lib/（tsdown 是唯一开发依赖），确保包入口断言针对的是实际发布产物：

先构建 lib/ 与类型检查,再运行完整测试套件
npm test
npm run test:node

使用 Vitest 运行（在 monorepo 根目录下开发时）
npm run test:vitest

🔒 边界与安全模型

本插件强制什么——同样重要的是，不强制什么。

信任模型
- 栈状态经 gh 来自 GitHub API（PR、审批决策、检查汇总）。插件在查询时刻信任这些响应；检查与后续变更之间的竞态在可行处已收窄（分支删除带 SHA 条件），但未完全消除。
- 本地验证在你的工作树中对分支头执行：它证明被测提交通过了你的本地套件；不替代 GitHub required checks——后者由 GitHub 在自己的基础设施与策略下评估。

权限与作用域
- 变更类操作（link、同步/推送、合入、分支删除）需要对仓库的写权限，并以你的 gh 凭证执行。
- --self-approve 是面向单人维护者的受限、可审计豁免：仅豁免评审审批守卫，输出与 JSON 中显著标记（selfApproved: true），绝不豁免 CI、拓扑或验证记录检查。团队仓库应依赖同伴评审。

已知边界
- 合并队列：堆叠合入可能进入 GitHub 合并队列；插件如实报告观察到的状态并在落定后引导 /stack-cleanup 收尾，但不驱动队列本身。
- 并发修改：两人同时变更同一堆叠不做协调。守卫会安全失败（保留分支、拒绝有歧义的合并），但底层 gh 操作以最后写入者为准。
- 跨 Fork 堆叠不支持（GitHub 原生栈为单仓库）；拓扑守卫显式拒绝。
- 审批失效取决于仓库配置：SHA 改写必然使 CI 对新 HEAD 失去证明力；审批是否失效取决于仓库的过期审批/最近推送规则。插件提示风险，GitHub 执行规则。
- 企业代理、组织策略与自建 GitHub 未测试。

报告问题：请附命令、--json 输出及 gh / gh-stack 版本提交 issue。

📄 开源许可

- 开源协议：MIT License
- AI Agent 技能定义：SKILL.md