bailong-Hakuryu/dsh-engineering-control-plane

DSH 工程控制平面

DeepSeek Harness 的工程任务编排与发布门禁插件 · 中文默认，English below

Release
Harness Compatibility
License: MIT

中文

这是什么

dsh-engineering-control-plane 为 DeepSeek Harness 提供受治理的工程任务执行。它把一次实现、修复、重构或发布验证请求固定为一个可追踪的 Mission，并由宿主负责计划、执行、验证、证据和质量门禁。

它适合希望把“让 Agent 改代码”变成可审计流程的团队：每个 Mission 都有明确的身份、Attempt、策略快照、验证结果和最终状态。

如果 Agent 能改代码，却不能回答“谁改的、改前是什么、证据是否完整、为什么最终放行”，那只是不可审计的写操作。Control Plane 把这条边界固定为 Mission → Evidence → Quality Gate → Receipt。

Mission 如何流转

Mission 只按单向阶段推进；角色输出、验证结果、外部 Assurance 和工作区指纹先形成摘要绑定的 Evidence，再由确定性 Quality Gate 计算终态。revision CAS、执行租约与仓库写租约负责拒绝并发漂移，取消和恢复也必须经过持久化协议。

主要能力

- 一个工作区同时只允许一个非终态 Mission。
- 在启动时冻结仓库身份、分支、HEAD 和有效策略。
- Planner、Tester、Reviewer 只读；Developer 不能提交、切换分支或改写历史。
- 验证命令来自宿主配置，不由模型临时编造。
- 只有确定性 Quality Gate 可以产生 APPROVED。
- 缺失、损坏、截断或不确定的证据会 fail closed。
- 外部 Assurance Subject 同时绑定 Git 状态与 baseline→produced change 的逐字节指纹。
- 支持可恢复的 BLOCKED、REWORK_REQUIRED、取消和重启恢复。
- 持久化 SQLite、Evidence 清单和不可变版本化 Receipt/Snapshot。

3 分钟最短安装（Harness Web）

要求 Node.js ^22.19.0 || >=24.0.0，以及可用的 DeepSeek Harness CLI。先安装 Control Plane，再安装可选的 Security Assurance Provider：

1. 下载对应 Release 的 tarball。
2. 用下面的命令安装并检查最终组合。
3. 在目标 Git 仓库目录启动 Harness Web。

~~~powershell
dsh plugin --profile web add D:\Downloads\dsh-engineering-control-plane-0.1.13.tgz
dsh --profile web --dump-config
dsh web
~~~

从 GitHub 下载：v0.1.13 Release。如果两个插件一起使用，Control Plane 必须先安装，因为它提供共享的不变量注册表。

默认配置会把 Harness 启动时的当前工作目录绑定为 current-workspace，并冻结以下默认验证命令：

~~~text
pnpm test
pnpm run typecheck
pnpm run build
~~~

Python/uv 仓库可以从随包发布的
profiles/erii-python.cordis.patch.example.yml
开始配置。该示例要求显式设置 DSH_ERII_PYTHON、位于工作树之外的
DSH_ERII_TEMP_ROOT 和预热的离线 UV_CACHE_DIR，并固定 ERII Dogfood 已验证的生命周期测试、主测试、
continuity-review、凭据扫描、Ruff、Compileall、重构清单和离线构建范围。请复制到目标
Harness Profile 后运行 --dump-config，不要用它自动替换其他仓库的宿主策略。
启动 Harness 时，请把终端当前目录设为要治理的 Git 仓库。安装后先执行 dsh --profile web --dump-config 检查最终组合，再执行 dsh web。

用户如何调用

插件同时支持被动路由和主动指令：

被动调用（推荐）：直接描述工程目标，模型会把实现、修复、迁移和发布验证请求路由到 Mission 工具。

~~~text
请为当前仓库实现这个功能，并在完成后运行完整验证。
请修复这个问题，所有修改必须经过 Mission 发布门禁。
~~~

主动调用：在 Harness Web 或 CLI 输入：

~~~text
/mission 为当前仓库执行一次发布前验证，要求测试、类型检查和构建全部通过
~~~

如果确实不需要治理流程，可以明确写出“直接模式，不创建 Mission”。插件不会在委派的 Mission 子角色中创建嵌套 Mission。

工具与生命周期

| 工具 | 用途 | 是否改变状态 |
| --- | --- | --- |
| mission_start | 冻结目标、策略和 Attempt，创建 Mission | 是 |
| mission_status | 读取权威快照、Gate 和合法下一步 | 否 |
| mission_resume | 从 BLOCKED 恢复同一 Attempt | 是 |
| mission_cancel | 先停止子任务与外部 Provider，再终态取消 | 是 |
| mission_rework | 从 REWORK_REQUIRED 创建新 Attempt | 是 |

所有变更操作都必须带上 mission_status 返回的精确 revision。过期 revision 会被拒绝，不会自动合并或重试。

典型生命周期：

~~~text
mission_start
→ planner → developer → tester → reviewer
→ evidence capture → quality gate
→ APPROVED / REWORK_REQUIRED / BLOCKED / CANCELLED
~~~

只读完整性检查

安装包提供不修改状态的 doctor 命令，用于检查 SQLite 身份、Schema、Lease、Evidence 引用和摘要绑定：

~~~powershell
dsh-control-plane doctor --pretty
dsh-control-plane doctor --dsh-home D:\path\to\dsh-home --pretty
~~~

退出码：0 表示通过，1 表示发现完整性或可用性问题，2 表示命令本身无法执行。doctor 不会创建、迁移、修复、清空或删除数据。

持久化与入口

持久化目录默认为：

~~~text
$DSH_HOME/control-plane/
├── control-plane.sqlite
└── missions//attempt-####/records/.json
~~~

公开入口：

| 入口 | 作用 |
| --- | --- |
| dsh-engineering-control-plane | Cordis Service 与 Kernel 契约 |
| dsh-engineering-control-plane/tools | 五个严格模型工具 |
| dsh-engineering-control-plane/client | 浏览器安全的版本化投影缓存，不拥有权威状态 |
| dsh-engineering-control-plane/invariant | 启动就绪与不变量诊断 |
| dsh-engineering-control-plane/assurance-provider | 可选的 Security Assurance Provider 契约 |

与 Security Assurance 联用

安装 dsh-security-assurance 后，Control Plane 会按精确的 Provider ID、版本和 current-workspace 绑定调用安全评估，并把 baseline HEAD、Git 状态指纹和逐字节产出变更指纹冻结进执行 Subject。安全评估结果只满足外部安全义务；最终 APPROVED 仍由 Control Plane 根据全部工程证据和 Reviewer 结果计算。

两个插件不共享 SQLite、可写 Evidence 目录、事务句柄或 Kernel 对象。

v0.1 边界

- 当前发布包面向 Harness 0.1.2-alpha.1（主目标），并声明兼容 0.1.2-alpha.2 至 0.1.2-rc.1、0.1.3-alpha.1、0.1.3-alpha.2、0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1 与 0.1.5-rc.2；该显式已验证集合由 Security Assurance 仓的 Harness Compatibility 双插件矩阵每日验证，Harness 仍处于开发预览阶段。
- 默认验证配置是 pnpm 项目；其他构建系统需要在宿主 Profile 中替换完整的 repository/config 行。
- client 是投影缓存，不是浏览器端 Mission Store；传输和 UI 由宿主集成。
- 该插件负责工程治理，不等同于漏洞扫描器；安全评估由可选的 Security Assurance 插件负责。

开发与验证

~~~powershell
pnpm install
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build
pnpm pack:dry-run
pnpm pack:profile-smoke
pnpm release:check
~~~

当前 main 分支发布门禁已通过：33 个测试文件、154 个测试，并覆盖静态检查、类型检查、构建、打包以及 fresh Harness Profile 安装与 Web 探针。公开 CI 在 Ubuntu、macOS 和 Windows 上重复该门禁。

设计依据和完整决策记录见：CONTEXT.md、docs/adr/、docs/implementation-specification.md。安全问题请参阅 SECURITY.md。

English

它是什么

dsh-engineering-control-plane 是 DeepSeek Harness 的一个受治理的工程工作流插件。它将实现、修复、重构、迁移或发布验证请求转化为可审计的 Mission，具有明确的策略、尝试、证据、验证和确定性的 Quality Gate。

Mission 概览

每个 Mission 按一个有序的阶段序列推进。摘要绑定的角色输出、验证、可选的外部保证和工作区证据共同输入确定性的 Quality Gate；修订 CAS 以及独立的执行/写入租约拒绝过期或冲突的变更。

如果 agent 可以更改代码，却无法回答是谁更改的、事先冻结了什么、证据是否完整，或者为什么结果被发布，那就是一次不可审计的写入操作。Control Plane 将边界固定为 Mission → Evidence → Quality Gate → Receipt。

亮点

- 每个规范工作树一个非终态 Mission。
- 仓库身份、分支、HEAD 和 Effective Policy 在启动时冻结。
- Planner、Tester 和 Reviewer 为只读；Developer 不能提交、切换分支或重写历史。
- 验证命令来自宿主拥有的配置。
- 只有确定性的 Quality Gate 才能产生 APPROVED。
- 缺失、损坏、截断或不确定的证据会失败关闭。
- External Assurance Subjects 同时绑定 Git 状态和字节精确的基线到产出变更指纹。
- 持久化 SQLite 状态、Evidence 清单、不可变 Receipts 和版本化 Snapshots。

在 Harness Web 中三分钟安装

需要 Node.js ^22.19.0 || >=24.0.0 和 DeepSeek Harness CLI：

1. 从匹配的 Release 下载 tarball。
2. 使用以下命令安装并检查组合后的 profile。
3. 从你想要治理的 Git 仓库启动 Harness Web。

~~~powershell
dsh plugin --profile web add D:\Downloads\dsh-engineering-control-plane-0.1.13.tgz
dsh --profile web --dump-config
dsh web
~~~
从 v0.1.13 Release 下载该软件包。同时使用两者时，请在 Security Assurance 之前安装此插件，因为它提供共享的不变量注册表。启动器工作目录变为 current-workspace；默认检查为 pnpm test、pnpm run typecheck 和 pnpm run build。

Python/uv 仓库可以从打包的
profiles/erii-python.cordis.patch.example.yml 开始。
它要求显式的 DSH_ERII_PYTHON、位于工作树之外的
DSH_ERII_TEMP_ROOT，以及预先预热的离线 UV_CACHE_DIR；它在测试、
密钥扫描、Ruff、Compileall、清单验证和离线构建中保留了完整的 ERII dogfood 范围。将其复制到目标
Harness Profile 中并检查 --dump-config；这是一个显式的主机策略示例，并非
其他仓库的自动替代品。

调用

用户可以用自然语言描述工程目标，或显式运行：

~~~text
/mission Run release validation for the current repository; tests, typecheck, and build must pass.
~~~

当有意不需要治理时，使用“直接模式，不创建 Mission”。在委派的 Mission 角色内，嵌套创建 Mission 会被拒绝。

该软件包公开了 mission_start、mission_status、mission_resume、mission_cancel 和 mission_rework。每次变更都需要 mission_status 返回的确切修订版本；过期的控制意图会被拒绝。

只读 doctor

~~~powershell
dsh-control-plane doctor --pretty
~~~

doctor 会检查 SQLite 身份、schema、租约、Evidence 引用和摘要绑定，而不会创建、修复、迁移、清除或删除状态。退出码为 0（通过）、1（发现问题）和 2（调用失败）。

公共入口

- dsh-engineering-control-plane：Cordis Service 和 Kernel 契约
- dsh-engineering-control-plane/tools：严格模型工具
- dsh-engineering-control-plane/client：浏览器安全的投影缓存
- dsh-engineering-control-plane/invariant：启动诊断
- dsh-engineering-control-plane/assurance-provider：可选的 Security Assurance 契约

当选择 Security Assurance 时，Control Plane 会将基线 HEAD、Git 状态指纹和字节精确的产出变更指纹冻结到实现后执行 Subject 中。Provider 可以独立验证确切的 Mission 输出，而无需接收仓库路径。
当前包面向 Harness 0.1.2-alpha.1，并声明了以下额外已验证的确切版本：0.1.2-alpha.2 至 0.1.2-rc.1、0.1.3-alpha.1、0.1.3-alpha.2、0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1 以及 0.1.5-rc.2。由 Security Assurance 负责的 Harness Compatibility 矩阵会验证这一封闭集合。

开发

~~~powershell
pnpm install
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build
pnpm pack:dry-run
pnpm pack:profile-smoke
pnpm release:check
~~~

当前 main 分支门禁通过了 33 个测试文件和 154 个测试，此外还包括 lint 检查、类型检查、构建、打包、全新 Harness Profile 安装以及实时 Web 探测。公共 CI 会在 Ubuntu、macOS 和 Windows 上重复该门禁。Harness Compatibility 工作流还会针对所声明的 Harness 版本验证双插件矩阵。有关领域模型、决策和安全策略，请参阅 CONTEXT.md、docs/adr/ 和 SECURITY.md。

许可证

MIT