dsh-punky-swarm

dsh plugin --profile web add dsh-punky-swarm

dsh-punky-swarm

DeepSeek Harness（dsh）的集群治理插件 + 引擎 —— 把「大型模块开发」拆成 plan → exec → audit 三层 DAG，配 门禁 / 状态机 / 黑板 / 结算，让多成员协作可派发、可审计、可恢复。

版本基线：0.5.0 = 新基线 —— 团队资产（team-asset）与 chain 声明面已整体退役；team 为可选自由标签（不解析、不校验、不拒建批）。

适用宿主（目标线）：@deepseek-ai/dsh 0.2.0-rc.1 —— 0.1.7 仅历史兼容、不再验证（其行为不再作为支持断言；peerDependencies 范围不动 —— 保持宽松、不主动拒装，0.1.7 宿主仍可被装；退役只表示不再验证，不是拒装）⇒ 目标线支持矩阵（单线）与上游版本钉法见 §3.2。

---

一、这是什么

• 引擎面：wave_plan（按依赖 DAG 分层为 waves，建批后不中途重算）→ lane_dispatch / member_status（派发）→ handoff_submit（逐边交接）→ member_settle（结算）；辅以 gate_status（门禁态）、log_export（事件导出）。lane_heartbeat / lane_longrun 属停维面（维护冻结：功能保留、不继续维护，2026-10-09 用户裁定），不作为在役能力推荐。
• 治理纪律：27 条 / 9 组（评估派发 / 批与交接 / 运行模式 / 审计验收 / 结算 / 恢复监管 / 输出·能力·指引 / 两方向·编号 / 执行前经验检索），细则见 references/discipline.md；Manager 侧通用定义见 references/manager.md。
• 它治的是什么：一批 Agent 一起干活时的四类事故 —— 上游产物没齐就开工、跑几小时一崩全丢、几个成员同时写同一份文件、拦了却说不清为什么。工具本身没坏，缺的是流程上的闸口；闸口装进引擎后，纪律成为机器判据，而不是各成员的自觉。
• 0.5.0 新基线：团队资产与 chain 声明面退役后，装配按「引擎基线 + 成员槽位 + 指引」；运行期 DAG 真源 = 批次 lanes[].deps + handoffs。

---

二、安装后得到什么（三面构成）

面 · 载体 · 落点 / 说明

① 插件（核心） · lib/ + cordis.patch.yml 两行 · 引擎行 dsh-punky-swarm（治理工具 + 面板）+ preset 注册行 dsh-agent-preset-punky（0.1.7 起 preset 必须**由插件行注册，不再扫描预设目录）

② 模式与指引（核心） · @deepseek-ai/dsh-agent-preset 注册的 punky-preset（蟛蜞模式） · references/discipline.md / references/manager.md 由启动期 syncAssets() 幂等同步到 <home>/.dsh/.agent-presets/punky-preset/

③ 团队技能指针（附加） · skills/ 8 个目录 · acceptance-gate / design-team / engine-team / research-team / retro-and-memory / review-execution / software-team / writing-team ⇒ 同步落点 <home>/.agents/skills/<name>/

---

三、安装（唯一命令）

Step 1 —— 产出可分发包（在包目录内执行）：

pnpm pack                 # ⇒ dsh-punky-swarm-0.5.0.tgz

Step 2 —— 唯一安装命令（dev / 离线环境；干净 DSH_HOME 上一条命令装齐）：

先取宿主 rc（下文记作 <HOST_RC>；本机示例值 0.2.0-rc.1，请以你的宿主实际输出为准）：

dsh --version

dsh plugin --profile web add <ABSOLUTE_PATH>/dsh-punky-swarm-0.5.0.tgz @deepseek-ai/dsh-experimental-agent-team-profile@<HOST_RC> @deepseek-ai/dsh-agent-preset@<HOST_RC>

三条硬要求（不要省）：

1. 两件上游包都要显式列出，且都钉「宿主同 rc」：<HOST_RC> 取自上面的 dsh --version（例：宿主 0.2.0-rc.1 ⇒ 两处都写 @0.2.0-rc.1）。为什么不写 caret、也不能固定写某一个 rc —— 见 §3.1（写错的后果是模式面无声消失）。

2. 禁裸 spec、禁标签式 spec：无版本会被兼容门直接拒装（原因见 §四 的 latest 陷阱）；而用 dist-tag（标签）代替版本号会随上游发布静默换线（next 现已指向目标线）⇒ 一律把 <HOST_RC> 写成精确版本（目标线形如 0.2.0-rc.x；历史线 0.1.7-rc.x 仅存史、不再验证）。

3. 显式列出 spec 不可省：本包 dependencies 键已整体移除 ⇒ 上游包只由安装命令提供（本包不再携带任何上游版本范围）；而 profile 的 dsh.profile.bundles 只登记新增的 top-level 依赖 ⇒ transitive 依赖不会成为 profile layer ⇒ 命令里必须把包名 + 版本写全。

3.1 为什么必须钉「宿主同 rc」（别写 caret，也别固定写某一个 rc）

• ① prerelease caret 会静默浮版：^0.2.0-rc.1 的语义包含 0.2.0-rc.2，且包管理器取最高满足版 ⇒ 你以为装的是 rc.1，实际落 rc.2。依赖声明层无法表达「宿主同 rc」 —— 这是把该约束放在命令里的根本原因。
• ② 模式注册包与宿主 registry 精确强耦合：@deepseek-ai/dsh-agent-preset@0.2.0-rc.2 的 peerDependencies 精确钉 @deepseek-ai/dsh-agent-preset-registry@0.2.0-rc.2，而 rc.1 宿主上实装的是 …-preset-registry@0.2.0-rc.1 ⇒ 版本不符 ⇒ 引擎在启动期 行级禁用三行：preset-minimal / preset-cordis / dsh-agent-preset-punky ⇒ 模式面无声消失（引擎按 per-entry fail-soft：进程照起，只往 stderr 落一行 disabling profile plugin row …，界面无提示）。
• ③ 固定写某一个 rc 同样错：宿主是 rc.1 时钉 rc.2 = 必现上面那条链；宿主是 rc.2 时钉 rc.1 亦同 ⇒ 唯一自洽写法 = 按 dsh --version 取宿主 rc，两件上游包都钉它（「四件同 rc」由此才成立；请勿把任一 rc 写死进模板）。
• ④ 本包 dependencies 中已不再有任何 -profile 声明（该键整体移除 ⇒ 由命令独占，根治「双族共存」），更不是「免列 spec」的理由（见第 3 条）；@deepseek-ai/dsh-agent-preset 同样不在 dependencies 中 —— 正因上述浮版链（它的 peer 与宿主 registry 强耦合）。

补充说明：

• <ABSOLUTE_PATH> 请用绝对路径（dsh plugin 以 process.cwd() 作为 pnpm 的 cwd，相对路径易踩）。
• 干净 DSH_HOME 上该命令会自动初始化 web profile，无需先手工建。

3.2 目标线支持矩阵（单线）（宿主 × 上游版本钉法）

宿主线 · 支持 · 命令里两件 spec 的精确后缀 · 安装命令形态 · 已证 / 未证边界

历史线 0.1.7-rc.2 · ⚪ 历史兼容（不再验证） · @deepseek-ai/dsh-experimental-agent-team-profile@0.1.7-rc.2 ＋ @deepseek-ai/dsh-agent-preset@0.1.7-rc.2 · 仍是同一条唯一命令（§三 Step 2）：把两处 <HOST_RC> 替换为 0.1.7-rc.2 · 历史记录（已跑；解析层 + 运行面）：上游包只由命令提供（本包 dependencies 键已整体移除）；解析层三探针 distinct=1 —— 目标线（0.2.0-rc.1）与历史线（0.1.7-rc.2）各一次，且不传 spec 时四包 0 命中（「双族共存」的必要条件已消除）；peerDependencies 的 @deepseek-ai/dsh-* 范围三版全通过（内核兼容门只读它）；workflow 行单行同名同构（双副本一致性机检在役）。史实（已实跑）：历史线 0.1.7-rc.2 用真实隔离实例 D:\dsh\iso-0.1.7-rc.2（真 rc.2 内核）跑通，3/3 GREEN、三面 / workflow / 端口 / 哨兵全达标；未覆盖项 = 真实既有 profile 的就地 boot（读数见批次产物 exec/verify-fix.md，该结论尚未落地 ⇒ 登记为待复核，见 §九）

目标线 0.2.0-rc.1 · ✓（唯一目标行） · @deepseek-ai/dsh-experimental-agent-team-profile@0.2.0-rc.1 ＋ @deepseek-ai/dsh-agent-preset@0.2.0-rc.1 · 同上：替换为 0.2.0-rc.1 · 已证（解析层）：上游包只由命令提供（同上）；解析层探针目标线 distinct=1（改动前并集范围下同一 lock 含两族，负例留档）；本机有隔离载体 D:\dsh\iso-0.2.0-rc.1。运行面：批 6 曾观测安装层非确定性（同一输入 9 跑 6 红：形态 A 三件子包恰一件落历史线 ⇒ 行被静默停用；形态 B 安装整体 status=1）；本批已从解析层消除形态 A 的必要条件，形态 B 属环境 / 包管理器侧、本批不承诺修复（只要求响亮失败）⇒ 目标线运行面复验读数见 exec/verify-fix.md（待复核）

参考 · 0.1.7-rc.1 · ⚪ 非目标线 · 同上（钉 0.1.7-rc.1） · 同上 · 仅作历史线等价代表（本机 CLI 实装）；不是本支持矩阵的目标行 —— 以 0.2.0-rc.1 一行为准

共同前置：@deepseek-ai/dsh-workflow-ptc 由内核提供（0.1.7-rc.1 / 0.1.7-rc.2 / 0.2.0-rc.1 三版内核全部依赖它）⇒ 无需用户额外安装（见 §四）。—— ⚠ 三版为史实（客观依赖事实，非支持断言）；目标线 = 0.2.0-rc.1。

声明面口径：本表 = 人读声明面；机读声明面 = 本包 peerDependencies 中 @deepseek-ai/dsh-* 条目的范围（内核兼容门只读它，本批未改动）。上游包不由本包提供：本包 dependencies 键已整体移除 ⇒ 上游包只由安装命令的显式 spec 提供（<HOST_RC>）。本包内不存在、也不应有 compatibility.json —— 该文件名在 DSH 中专指 profile 级豁免表（落点是 profile 目录），包内放它无消费者。

---

四、上游依赖 / 前置（两件显式 spec）

安装命令里的两件上游包（见 §三）各自身份与声明位置：

…(truncated)