@pure01fx/dsh-runbook-hu

v0.3.0

Published

3 days ago

Hu's DSH Runbook — project execution governance for DeepSeek Harness: approved runbooks, milestone evidence, deviation gates, finish gates, and optional notifications.

0High
0Medium
0Low

pure01fx

Hu's DSH Runbook Plugin

Hu's DSH Runbook 是 DeepSeek Harness 上的一层项目执行治理协议，面向数小时到一两天的功能实现、工程改造和 AI 实验任务。

DSH 负责运行 agent；Runbook 负责定义 agent 被授权完成什么、当前执行到哪里、依据什么判断成功，以及何时必须暂停并把决策权交还给人类。

治理能力（V1 兼容基线）

定义阶段通过聊天和 DRAFT.md 共同收敛 spec/plan；
Start Gate：只有当前顶层人类回合明确批准后才能开始；
Host authority store 保存 canonical state；workspace 中持久化 RUNBOOK.md、STATUS.md、state projection 和不可变报告；
Milestone checkpoint 与 verification / experiment / artifact 记录；
重大偏航、更优方案和客观 blocker 的暂停流程；
新的人类 directive、decision resolution 和 plan revision；
Finish Gate：证据不完整时拒绝完成；
可选 Notification Slot：callable adapter 优先，prompt handoff 回退；
awaiting_instruction / blocked 状态下的工具执行 guard。

V1 不实现新的 agent loop、todo、subagent 调度器、detached runner、Web Dashboard、artifact 上传或多机执行。

生命周期

draft
→ defining
→ 人类批准 Start Gate
→ executing
↔ milestone checkpoint
→ 必要时 awaiting_instruction / blocked
→ 人类 directive
→ executing
→ Finish Gate static pass
→ finishing（mutation fence + quiescence）
→ completed

Revision V2（新 Run 默认）

新 Run 使用统一不可变 Revision 链：R001 → R002 → R003。R001 是初始完整合同/计划快照；后续 plan-change 或 contract-change 都保存完整 snapshot 和 parent digest，不重放 patch。RUNBOOK.md / STATUS.md 是机械投影，Host authority 保存 canonical bytes、generation、event sequence、challenge hash、evidence validity events 和待物化 outbox。

短 challenge 审批

在 DRAFT.md 中维护唯一 revision-contract R001 snapshot，并计算整个文件 digest。
Agent 调用 runbook_prepare_v2，得到短 A-... challenge。
人类只回复 RUNBOOK APPROVE A-...。
runbook_begin_v2 创建并物化 revisions/R001.md。

Plan option 会冻结完整目标 snapshot 和 option-set digest。人类使用 RUNBOOK RESUME D-...:<option-id>。若选项都不合适，则回复 RUNBOOK REVISE D-... 并在下一行写新想法；Run 保持暂停并进入 authority-owned revision drafting。

runbook_revision_draft 不接受路径，只更新固定 REVISION_DRAFT.md 投影。Contract snapshot 经 RUNBOOK APPROVE R-... 批准后仍不执行，必须再以 RUNBOOK RESUME R-... 独立激活。

Evidence 与 Finish

runbook_checkpoint_v2 接收绑定 active revision 的 evidence/verification/experiment/artifact JSON。Evidence 永不回写；跨 Revision 通过 append-only carry/invalidate/revalidate events 归约，并绑定 subject、oracle、environment 和 input digests。不能机械证明等价时必须重验。runbook_finish_v2 只接受 active revision 有效证据和通过的 required verification。

双轨兼容

Authority envelope 先按 schema 路由。已有 schema-1 Run 继续使用五个 V1 工具直至 terminal；V2 工具拒绝 V1 authority，V1 工具也拒绝 V2 authority。不会为 V1 伪造历史 Revision 或原地迁移 active Run。

安装

要求：

Node.js ^22.19.0 || >=24.0.0；
DeepSeek Harness 0.1.1-rc.2 兼容服务；0.2.x 是旧 DSH 0.1.0-rc.6 版本线；
当前 session 具有可写 workspace policy。

开发安装：

pnpm install
pnpm build

将本地包加入一个 DSH profile：

dsh plugin --profile web add link:/absolute/path/to/dsh-runbook-hu

安装时会加入一个仅负责同步 preset 的 host bundle row；它不会在 host/root scope 注册 Runbook tools 或 system prompt。DSH 下次启动时会把包内 标准模式 + Hu's DSH Runbook 和 PTC + Hu's DSH Runbook 分别同步到 $DSH_HOME/.agent-presets/runbook-standard 与 runbook-ptc，可直接在新会话选择。这两个目录由包管理，升级可能替换其文件。

Runbook 本身是可组合的工具插件，并不限定 PTC。用户可以复制任意内置 preset（Standard、PTC 或其他模式）为用户 preset，再加入下面这一行；不要修改 DSH 内置 preset，也不要把主插件挂到 profile root，否则会把治理工具暴露给所有 agent。

自定义 preset 中的插件配置：

- id: runbook
  name: '@pure01fx/dsh-runbook-hu'
  config:
    enabled: true
    announceToAgent: true
    enforcePause: true
    notificationToolNames:
      - notify_feishu
    # 可选；兼容保留的共享路径 $DSH_HOME/runbook/v1/authority（schema 1/2 均在此硬路由）
    authorityDirectory: /host-controlled/dsh-runbook-authority

enabled：是否注册插件；
announceToAgent：是否注入 Runbook 执行协议；
enforcePause：暂停后是否拒绝新的实现和实验工具；
notificationToolNames：允许 prompt handoff、且暂停期间仍可调用的通知工具名；
authorityDirectory：canonical state/outbox 的共享 host 目录；默认仍使用历史兼容路径 $DSH_HOME/runbook/v1/authority，但 envelope schema 1/2 会在解析前硬路由，该目录名不表示 V2 存在 workspace 或另一 authority root。配置到 agent workspace 内会 fail closed。

附带 preset 与自由搭配

开箱即用：选择包管理的 标准模式 + Hu's DSH Runbook（runbook-standard）或 PTC + Hu's DSH Runbook（runbook-ptc）；
自由搭配：在任意用户自有 agent.cordis.yml 中加入上面的 runbook row；
Code Mode 下模型表面仍只看到 run_code，V1/V2 Runbook tools 进入生成的 SDK，nested dispatch 仍按真实内层工具名经过暂停/终态 guard；
安装依赖不等于全局启用；只有包含 runbook row 的 agent preset 会获得工具和 prompt。

Legacy V1 用户流程

1. 定义草案

用户先在聊天中描述目标。Agent 使用普通文件工具持续维护：

.runbook/runs/<run-id>/DRAFT.md

建议包含：

## Desired effect
## Success criteria
## Constraints
## Non-goals
## Candidate approaches
## Assumptions
## Open questions
## Milestones
## Verification strategy
## Resource boundaries
## Decision register

此外，V1 要求草案中恰好一个 fenced JSON contract。它是 Start Gate 比较的结构化内容，字段必须与 runbook_begin 除 approved_draft_sha256 / human_approval 外的参数完全一致：

```runbook-contract
{
  "run_id": "example-run",
  "title": "Example run",
  "desired_effect": "...",
  "success_criteria": [{"id":"AC1","description":"...","required":true,"verification":"V1"}],
  "constraints": [],
  "non_goals": [],
  "plan_summary": "...",
  "milestones": [{"id":"M1","title":"...","expected_outcome":"..."}],
  "verification_strategy": [],
  "required_verification_ids": ["V1"],
  "resource_boundaries": [],
  "decisions": [],
  "notification_enabled": false
}
```

Block 必须是 JSON.stringify(value, null, 2) 等价的两空格 canonical JSON（从而拒绝 duplicate keys），工具再做递归、key-order 无关的精确字段比较；不能批准 prose A 后由模型提交 contract B。文件修改只是提议，不代表批准。

2. 明确批准

Agent 先计算并展示当前 DRAFT.md 的 SHA-256。用户在新的顶层回合只发送下面这条精确消息（不能附加说明文字）：

RUNBOOK APPROVE sha256=<64位 digest>

Agent 随后调用 runbook_begin，提供：

approved_draft_sha256：用户消息中的 digest；
human_approval：当前完整人类消息的逐字副本；
required_verification_ids：批准契约要求通过的 verification ID。

工具会重新读取 DRAFT.md、计算 digest、验证完整人类消息副本和 canonical 批准行，并把人类 message ID 与 digest 固化到 Runbook。digest 不一致、否定措辞、当前回合不是直接人类输入时都会拒绝开始。

3. 自主执行和检查点

实现细节继续使用 DSH todo、subagent、bash 和 background jobs。完成稳定 milestone 后，Agent 调用 runbook_checkpoint，记录：

实际 outcome；
代码和配置变化；
Verification 结果；
Experiment 执行状态与结论；
Artifact 引用；
Success criterion evidence；
计划偏差、风险和下一 milestone。

activeJobs 不由模型自报，而是从 ctx.jobs 对 root session 及 live descendants 查询。Checkpoint 只能验证当前 active milestone，至少需要一个带 evidence 的 passed verification，并且 pending milestone 尚存时必须选择下一 milestone。

普通偏差记录后继续。重大漂移不能伪装成普通 checkpoint。

4. 暂停和恢复

发现重大方案变化、更优方向或客观 blocker 时调用 runbook_request_instruction。

Run 会进入：

awaiting_instruction

或：

blocked

enforcePause: true 时，插件通过 async tools/pre-execute 从 host authority store 恢复状态，同时用进程内 projection 做同步快速拒绝；它不信任模型可见的 tool-result 文本或 workspace state.json。Guard 对 Code Mode nested dispatch 和 live descendant agent 同样生效；authority 保存独立 lineage index，并结合 fork 的 durable parentSession 阻止重启后 former child/fork 绕过暂停或 terminal closure。

进入暂停后，工具会请求停止当前 Run 拥有的 background jobs、取消 live descendants，通过 exec.deferContext() 注入一个强制收尾说明，并保留 exec.concludeTurn() 成功标记。DSH 会先让模型处理收尾说明，明确告诉用户暂停原因、待决问题、选项、建议以及可复制的精确 RUNBOOK RESUME 消息，再结束 turn。暂停 guard 继续拒绝写文件、bash、subagent、workflow 等非安全工具；仅允许只读分析、查看已有 job 结果、配置过的通知工具和 runbook_resume。用户恢复时必须只发送 RUNBOOK RESUME option=<pending option id>（无 option 的 blocker 使用 option=none），不能附加说明文字。Agent 在同一个直接人类回合调用 runbook_resume；directive 必须等于当前完整人类消息，selected_option 必须与 canonical 行及 pending decision 一致，required criteria 必须保留，active jobs 和 blockers 必须已经收敛。成功后生成 decision resolution、增加 plan revision 并回到 executing。若所有 milestone 已终结且没有 current milestone，只有在恢复契约恰好指定一个 verified milestone 时才会将它重新设为 active，从而强制通过普通 checkpoint 修正 canonical evidence 后才能再次完成；空选择、多 milestone 选择及非 verified terminal milestone 保持原状态，不会被含糊重开。

5. 完成

Agent 调用 runbook_finish。该工具只接收 run_id、结果摘要和 remaining risks，不能在 Finish 调用里临时补写 criteria、verification、job 或 blocker 状态。以下任一 canonical 条件存在都会返回 finished: false：

Required success criterion 未满足或没有 evidence；
Required verification 未记录或不是 passed；
仍有 pending 或 active milestone；
仍有 running job；
仍有 blocker；
仍有待处理的人类决策；
Run 不在 executing 状态。

静态条件通过后，Finish 先原子进入 finishing 以封住新 mutation，再取消并等待 runtime-owned 与 durable-fork descendants、重复查询 descendants/jobs，最后评估；全部通过才生成 999-final.md 并进入 completed。Terminal authority 继续拒绝该 lineage 的实现/实验工具。

五个工具

| Tool | 作用 | | --- | --- | | runbook_begin | 固化已批准草案并跨过 Start Gate | | runbook_checkpoint | 验证 milestone，保存证据和偏差 | | runbook_request_instruction | 重大漂移、更优机会或 blocker，写报告并暂停 | | runbook_resume | 保存人类 directive，创建 plan revision 并恢复 | | runbook_finish | 执行 Finish Gate，满足时生成 final report |

runbook_begin 和 runbook_resume 强制绑定当前顶层直接人类消息；前者还绑定批准的 Draft digest。Subagent 不能拥有或修改主 Runbook 生命周期。

文件结构

.runbook/
├── .gitignore
└── runs/
    └── <run-id>/
        ├── DRAFT.md
        ├── RUNBOOK.md
        ├── STATUS.md
        ├── reports/
        │   ├── 000-plan-approved.md
        │   ├── 010-M1-checkpoint.md
        │   ├── 020-decision-request.md
        │   ├── 030-decision-resolution.md
        │   └── 999-final.md
        └── .internal/
            ├── state.json
            └── session.json

插件创建 .runbook/.gitignore，默认忽略：

runs/*/DRAFT.md
runs/*/STATUS.md
runs/*/.internal/

RUNBOOK.md 和 reports/** 可以进入 Git。.internal/state.json 是可检查的 workspace projection，不是授权根；canonical state、revision lock 和待物化文件 outbox 位于 authorityDirectory。每次治理调用都会从 authority 修复 projection。output/ 是否忽略由项目自行决定。

Notification Slot

通知配置保存在 run state 中，但凭据、token 和 webhook secret 不写入 Runbook 文件。

默认关键事件：

milestone.verified
run.awaiting_instruction
run.blocked
run.completed

Callable adapter

其他 Cordis plugin 可以提供 runbookNotifier service，其能力满足：

interface NotificationAdapter {
  deliver(
    event: NotificationEvent,
    options: { signal: AbortSignal },
  ): Promise<{
    delivered: boolean
    provider?: string
    externalId?: string
    error?: string
  }>
}

Runbook 在同一次 lifecycle authority commit 中保存完整 event payload 的 pending notification outbox，再调用 adapter，最后 CAS 保存 sent / failed outcome。重启后的下一次治理调用会在 callable adapter 存在时重放 pending / failed / skipped；prompt-only 恢复不会被静默标为已交接，而是保留 pending。

Prompt handoff

没有 callable adapter、但 notificationToolNames 非空时，工具返回结构化 notification.prompt，主 Agent 可交给已配置通知工具。两者都不存在时状态为 skipped，不会伪造 handoff。为避免覆盖旧 outbox，同一 session 开始下一 Run 前，terminal pending / failed / skipped 必须先由 callable adapter 重放为已发送状态。

通知具备稳定 eventId，adapter 必须把它作为幂等键。failed / pending 可重试，sent / prompt_returned 去重；AbortError 会继续向上传播。摘要和 adapter error 会限长并清洗常见凭据模式。通知失败不会回滚 Run 生命周期状态。

Sandbox 和隔离

Workspace 只从 exec.agent.session.header.cwd 获取；
Run 与创建它的 session 和 workspace 绑定；
Workspace projection 只允许写入 canonical workspace 内的 .runbook/；.runbook 本身是 symlink 或 policy root 不匹配时 fail closed；
Workspace 写入通过 ctx.fs、fs/write-intent waterfall、standing sandbox policy 和 version guard；
Canonical authority 使用 host 目录、file+directory fsync、原子 rename、heartbeat lock、per-session revision CAS、workspace/run 排他锁和恢复 outbox；
工具不提供自动权限升级参数；
Read-only session 中的 workspace projection 写入会按 DSH policy 失败；
Subagent 不能调用生命周期工具管理主 Run；
authorityDirectory 应由 host 管理且不要暴露给模型；若把 danger-full-access 模型视为主动恶意进程，需要额外 OS 用户/容器隔离。

开发

pnpm typecheck
pnpm test
pnpm build

测试覆盖：

状态机和 Start / Deviation / Finish Gate；
Criteria、verification、experiment 语义；
Decision pause / resume；
Report sequence collision；
完整递归 state validation、authority revision CAS、并发 stale rejection 和恢复 outbox；
.runbook containment、symlink 拒绝、write-intent seam 和真实 fs-local 原子写入；
Callable notification、pending outbox、重试/去重、取消、清洗和 prompt/no-capability 分支；
伪造 surface marker 对抗测试，以及真实 DSH ToolRuntime 的 async pause enforcement；
Draft digest / human quote 绑定、premature Finish 拒绝和从 begin 到 completed 的完整持久化生命周期。

V1 设计草案见 DRAFT.md，统一 Revision V2 设计见 REVISION-DESIGN.md，面向用户的介绍页见 index.html。

当前限制

V1 的定义阶段使用普通文件工具维护 DRAFT.md，没有单独的 runbook_define 工具；
语义偏航由主 Agent 判断，插件不尝试自动理解代码设计；
Evidence 的真实性仍依赖 Agent 实际执行测试并保存可检查引用；
Workspace 文件集合不是瞬时跨文件事务；authority outbox 会在下次治理调用重放并修复 projection；
暂停 guard 对 shell 采取严格策略，因此暂停期间不能通过 bash 查看 Git 状态；
Notification adapter 发送成功后若 outcome CAS 失败会保留 pending，adapter 仍必须使用 eventId 避免重试重复发送；
V1 没有独立的 failed / cancelled lifecycle tool。