zzd1990/dsh-parallel-dev

dsh-parallel-dev

把「智能体团队模式并行开发」从建议变成有门禁、可校验的机制。

面向 DeepSeek Harness 的编排插件。它不重造任务板，只补上平台没做的那一件事：把任务标记为「完成」时，必须有一份独立验收记录。

• 门禁：team_task_update(complete) 没有验收记录会被真的拒绝，不是提示。
• 验收：记录绑定 commit sha；验收后代码再改动，完成动作照样被拒。
• 看板：依赖分层、关键路径、同泳道排队、并发时间轴，一眼看清「现在到哪了、卡在哪」。
• 设置页：在 DSH 设置里查看插件自身状态、诊断、安装信息，并配置 8 项行为。

当前版本：v0.3.0（实验性）。

---

目录

• 为什么需要它
• 功能
• 快速开始
• 安装
• 使用
• 工具一览
• 配置
• 数据与命名空间
• 工作原理
• 设置页
• 目录结构
• 开发
• 兼容性与已知限制
• v0.3 变更
• 文档
• 许可证

---

为什么需要它

平台已经提供了团队任务板（team_task_create/list/get/update）和完整的状态机。但它允许任何成员直接把任务标成 completed —— 没有验收、没有证据、没有独立核对。

「实施和验收是同一个人」是并行开发里最隐蔽的失败方式：看板全绿，交付物却没人独立看过。本插件用 tools/pre-execute 钩子拦截「标记完成」这个动作，把「验收通过」从模型的声称变成一个能被机器校验、且能被强制的状态。

功能

• 验收门禁：team_task_update 的 complete 动作必须命中一份 passed 的验收记录，否则拒绝。
• 独立验收：记录由一次性验收代理（subagent）登记，带逐条判据、可定位证据、验收方标识；实施方自己签字的记录会被拒（自证检查，默认开启，可在设置里放宽）。
• 提交绑定：验收记录绑定 worktree 的 commit sha；完成时 HEAD 已变化 → 拒绝，因为验收过的版本已经不是交付的版本（默认开启，可在设置里放宽）。
• 用户豁免：用户本人明确说「这个任务不用验收」时，pdev_waive 逐字核对用户原话后放行，并留痕。
• 依赖看板：/pdev/board，纵向依赖图 + 关键路径 + 同泳道排队 + 并发时间轴；可嵌在 DSH 侧栏。
• 编排纪律注入：自动把团队并行开发纪律写进系统提示，不依赖用户手动贴提示词。
• 设置页：「并行开发配置」，查看插件状态 / 运行条件 / 安装信息 / 插件事件，配置 8 项行为（写入 profile 的 cordis.patch.yml）。

看板：5 层 / 最宽 6，红色为关键路径，紫色虚线为同泳道排队（?demo=1 演示数据）。

快速开始

1. 安装本插件并重启 DSH（见下一节）。
2. 让 Lead 在开工前调用 pdev_preflight，确认团队工具、git、项目占用都没问题。
3. 实施任务派 spawn_teammate，每个任务一个 worktree；完成后派一次性 subagent 验收，由它调 pdev_verify_record，再 complete。

安装

前置条件

缺 Agent Teams 时，插件仍会加载，但团队工具不可用，门禁没有可拦截的对象 —— 请先装团队包。

安装到 profile

把本仓库目录交给 DSH 会话里的 Agent，让它调用插件管理器：

plugin_manager({
  action: "install_bundle",
  target: "/绝对路径/dsh-parallel-dev"
})

安装结果以返回的 application 字段为准；为 applied 后重启 DSH。

安装后无需手工改 cordis.patch.yml：本包自带的 cordis.patch.yml 会插入 parallel-dev 这一行。

卸载：从 profile package.json 的 dsh.profile.bundles 移除 dsh-parallel-dev，删除 node_modules/dsh-parallel-dev，重启 DSH。

验证安装

重启 DSH 后，在会话里调用：

pdev_gate_status()

看到 plugin: dsh-parallel-dev v0.3.0、gateInstalled: true 即安装成功。 设置 → 并行开发配置 也应出现；看板地址是 /pdev/board。

使用

1. 开工前

pdev_preflight(project_root = "/path/to/project")

它会检查：团队工具是否真的存在、项目根是否被另一个编排会话占用、git 是否可用、已有验收记录覆盖情况。 返回的 blockers 不为空时不要降级硬做 —— 先告诉用户。

2. 团队开发 + 独立验收

1. Lead 用 team_task_create 建任务，写清 blocked_by 和 write_scopes；第一层尽量做宽。
2. 实施任务用 spawn_teammate；每个实施任务一个独立 worktree + 分支。
3. 实施方完成后，Lead 派一次性验收代理（subagent）独立核对。
4. 验收代理调用 pdev_verify_record 登记记录（判据 + 证据 + commit sha）。
5. 实施方或 Lead 调 team_task_update(action = "complete")；门禁命中记录才放行。

没有验收记录的 complete 会被拒绝，并返回正确做法与所需参数。

3. 用户豁免

用户本人明确表示某任务不需要验收时：

pdev_waive(task_id = "task-3", user_quote = "task-3 不用验收", reason = "文档改动")

插件会去本会话的用户消息里核对这句原话，并要求包含明确的豁免意思。编造的引用会被拒绝。 豁免会留痕，最终验收报告应列出所有豁免项。

4. 看板

• 浏览器打开 /pdev/board（拼在 DSH Web UI 地址后面）。
• 或在 DSH 侧栏打开「并行开发」面板：检测到未完成任务时会自动打开（可在设置页关闭）。
• 看板数据接口：/pdev/board/data，支持 ?session=<sessionId> 与 ?demo=1。

5. 设置页

设置 → 并行开发配置： 查看插件版本、加载状态、5 个服务是否可用、安装目录 / profile / 配置文件 / 数据目录、插件提供的能力、最近插件事件； 配置 8 项行为并保存（写入当前 profile 的 cordis.patch.yml）。

工具一览

project_root 省略时使用当前会话的 session.header.cwd。

配置

配置全局一份，存在当前 profile 的 cordis.patch.yml，由设置页写入；默认值全部保持最严格行为。

放宽 gateMode 或任一严格项会让「完成」的可信度下降；设置页会二次确认并显示警告。修改只在保存后生效，Host 读侧最多 1 秒缓存。

数据与命名空间

所有数据都在项目根下，可读、可 diff、可进版本库（默认建议把 .pdev/ 加进 .gitignore）：

<项目根>/.pdev/
├── verify/
│   ├── team-<leadId>__task-3.json           # 验收记录
│   └── team-<leadId>__task-7.waiver.json    # 用户豁免
└── timeline.jsonl                           # 任务状态变更（append-only）

验收记录按团队隔离：key 取团队 Lead 的会话 id；一次性验收 subagent 会归属到它所属的根会话，避免「记录落在 subagent 自己的命名空间里、Lead 找不到」。这样多个并行会话的同名 task-1 不会串。

工作原理

Lead / teammate ──team_task_update(complete)──▶ tools/pre-execute 钩子
                                                  │
                          ┌───────────────────────┴───────────────────────┐
                          │ 用户豁免？                                    │ 放行
                          │ 验收记录存在且 passed？                       │
                          │ 记录 worktree 的 HEAD == commit_sha？         │
                          └───────────────────────┬───────────────────────┘
                                                  │ 任一不满足
                                                  ▼
                                              拒绝并说明原因

• 验收记录由 pdev_verify_record 写入，工具自己跑 git rev-parse HEAD 取证，不采信调用方转述。
• 验收方不能是任务所有者（默认开启；比对任务板 ownerName 与调用方成员）。
• gateMode = enforce 时拒绝；advise 时只打一行「仅提醒」并放行。

设置页

src/client/client.js 注册 settings.section（id dsh-parallel-dev，order 50，文案「并行开发配置」）。 页面是原生 React（不是 iframe），只展示插件自身的信息，不展示任务状态：

1. 插件状态（版本、加载时间、Host/Client 半边、门禁/提示词/看板）
2. 运行条件（tools / webServer / settings / systemPrompt / agentTeams，及缺失影响）
3. 安装信息（安装目录、profile、配置文件、数据目录、Node 版本）
4. 插件提供（5 个工具、看板路由、侧栏面板、提示词段）
5. 最近插件事件（最多 20 条，只记插件自身）
6. 配置表单（保存 / 恢复默认 / 只读兜底 / 冲突处理 / 放宽二次确认）
7. 复制诊断信息

配置接口：GET /pdev/plugin/status、POST /pdev/plugin/config（同源、JSON、修订号保护）。

目录结构

dsh-parallel-dev/
├── src/
│   ├── host/
│   │   ├── index.js           # 插件入口：门禁、看板路由、工具注册、配置接线
│   │   ├── config.js          # 配置默认值 / 归一化 / 白名单校验（纯逻辑）
│   │   ├── config-schema.js   # schemastery Config（8 个 volatile 字段）
│   │   ├── gate-decision.js   # 门禁决策纯函数
│   │   ├── team-key.js        # 验收记录命名空间（含 subagent 归属修复）
│   │   ├── plugin-api.js      # /pdev/plugin/status、/pdev/plugin/config
│   │   ├── graph.js           # 依赖分层 / 关键路径 / 阻塞半径
│   │   ├── board-page.js      # 自包含看板 HTML + SVG
│   │   └── policy.js          # 注入系统提示的编排纪律
│   └── client/
│       └── client.js          # 侧栏看板面板 + 设置页（手写 React，无构建）
├── scripts/
│   ├── check-host.mjs         # Host 纯逻辑与 teamKey 行为测试
│   └── bsk-auto-browser.sh    # 开发期浏览器辅助
├── docs/                      # 设计契约、版本报告、看板快照与截图
├── cordis.patch.yml           # bundle 补丁：插入 parallel-dev 行
├── dev-sync.sh                # 开发同步到 profile
├── LICENSE
├── README.md
└── package.json

开发

# 语法检查（注意：node --check 一次传多个文件只会检查第一个）
for f in src/host/index.js src/host/config.js src/host/config-schema.js \
         src/host/gate-decision.js src/host/team-key.js src/host/plugin-api.js; do
  node --check "$f"
done
node --check src/client/client.js

# Host 纯逻辑测试（不依赖 node_modules）
node scripts/check-host.mjs

# 同步到本地 profile（macOS/Linux）
./dev-sync.sh desktop

• 没有构建步骤：Host 是普通 ESM；Client 是 window.__ModuleLoader__ 工厂 + React.createElement。
• Host 改动要重启 DSH；Client 改动刷新页面即可。
• 所有配置字段都是 .volatile()：设置保存后即时生效，不重载插件。

兼容性与已知限制

• 实验性：接口和行为可能随版本调整。
• macOS 已验证；Windows 未现场验证。Host 只用 Node API 和 git 子进程，理论上跨平台；开发脚本 dev-sync.sh 仅适用于 macOS/Linux。
• 单进程、共享 checkout：这是 Agent Teams 的当前限制，插件不提供跨进程协调。
• 验收依赖 git：项目不是 git 仓库时，pdev_preflight 会警告，提交绑定无法生效。
• 设置页依赖服务：没有 host-webserver 时页面读不到状态；没有 settings 服务时只读。
• 豁免靠人：pdev_waive 只能核对用户在本会话里说过的话，插件不判断任务是否真的该豁免。
• 界面中文：v0.3 只做了中文文案。
• 记录不提供删除按钮：避免给门禁开后门；需要清理时手工删 .pdev/verify/ 下的文件。

v0.3 变更

• 新增设置页「并行开发配置」（settings.section，order 50）。
• 新增 8 项配置，全部 volatile，写入 profile 的 cordis.patch.yml。
• 新增 GET /pdev/plugin/status、POST /pdev/plugin/config。
• 自动打开看板从 localStorage 迁移为配置（旧标记自动迁移，一次）。
• 修复：一次性验收 subagent 的验收记录归属到根会话，否则 Lead 的 complete 找不到记录。
• 版本升到 0.3.0。

文档

• v0.3 接口与实现契约
• v0.2 完成报告
• v0.1 完成报告
• v0.0 探针报告
• 看板静态快照

许可证

本项目使用 MIT 许可证，详见 LICENSE。