蜂群治理 Punky971210/dsh-punky-swarm

dsh-punky-swarm · 蟛蜞模式治理引擎

一个智能体是随叫随到的外包；一批被治理的智能体，才是一个部门。

把公司的制度做成软件、装进引擎：排期、质检、审批、容灾逐条由引擎跑。人退到只剩裁决——说清要什么，验收做出什么。

English: README.en.md

亮点

- 四道闸口，缺件不放行 —— 派发前查上游产物、合并前查计划结构、结算前查产物落盘、收尾前查验收完成。半成品到不了你手里。
- 判据在开工前写死 —— 验收标准落在计划层，审计按条对照；智能体只能提交，不能自己写结算。
- 按任务特点分配运行模式 —— 顺手小活直接干，不背治理开销；多环节的活走流水线，不建批不许动手。
- 一步一存档 —— 每完成一个子步骤存一档，崩了从存档续，做完的步骤不重做。
- 同一份活只许一个写者 —— 各用隔离工作区；冲突不自动合并、不静默覆盖，保留现场交人裁决。
- 复杂长任务必须建批 —— 不建批直接动手，引擎拒绝；评估会过期，防止一路闷头干下去。
- 拦得明白 —— 越界被拒时给的是「哪条规则拦的」＋可验篡改的收据，不是一句泛化的拒绝。
- 全程留痕 —— 状态、交接、结算、门禁判定全落事件流，可回放、可导出审计；只读面板一眼看全。

为什么需要它

单个智能体好管：派活、盯活、验收，一个人管一个，管得过来。但它的价值到个体为止。堆数量更糟——十个智能体一起干活，谁先跑、谁等谁、谁写哪个文件、崩了从哪续，没有规则兜底，跑起来就是事故现场。堆出来的不是帮手，是更多要盯的外包。

外包靠人盯，部门靠制度。 一个人盯不过来，一套制度可以。制度装进引擎之后账也算得过来：部门要养编制，没活也得养；引擎里的规则按 token 租，有活才租。一个人、一套自动化的制度、一批随叫随到的智能体——这就是一人公司的全部构成。

多数多智能体产品卡在一条看不见的线上：它们给了你能力，没给你制度落座的位置。 这句话拆开看是三处毛病——状态留不住、目标守不住、任务说不清。

| 毛病 | 你得到的后果 | 引擎的对策 |
| 状态留不住 | 上下文一压、会话一关，做过的事蒸发；中断一次等于从头再来 | 状态搬进文件当唯一事实源，按步存档 |
| 目标守不住 | 聊着聊着需求就变了，没人察觉 | 目标开工前钉死，批次建好不重算 |
| 任务说不清 | 只能说「帮我写个方案」 | 先分级，再按依赖分层，每轨声明交什么 |

工具调用级定轨

智能体跑偏，靠更强的能力治不了，得靠纪律治。就像走路刻在脊髓里而不占大脑——任务能不能走完，不取决于它当下多聪明，取决于有没有一套流程在兜着它。

判断权因此从智能体手里收走：开工前把契约立好（这一步交什么、什么算齐），一步做完先验收，检查不落在智能体的自觉上，而拦在它调用外部工具的链路上。

这件事只能在宿主把执行循环开放出来的那一层做。宿主只开放到能接外部协议，纪律只能在引擎外面手工拼装；开放到执行循环内部，纪律才装得进引擎、变成本能。

这套东西由三件组成：引擎给能力（分级、编排、门禁、锁、存档、护栏、只读面板）；模式规范行为（角色、纪律、引导）；指引教怎么用（分层角色手册、产物格式、模板）。三件随包安装，装完即是一支可运行的队伍。

纪律在引擎里，不在协议外

互联协议（MCP / ACP）解决「互相找得到、递得出任务」，最多组成聊天室。真正的流水线不长在互通上，长在验收上——前脚没站稳后脚不能迈，产物不齐绝不放行。

这类检查只有一个位置能长：宿主执行循环内部。只有循环自己知道这次调用前缺什么、产出了什么、谁在等这份产出。所以「让智能体记得做」和「引擎必须验」是两种治理，本引擎选后者。

市面上的东西大致分三类：单智能体编程产品（让一个智能体把活干成，设计目标里没有多线并行与产物契约）、多智能体编排框架（让几个智能体按拓扑说话，判据仍留在调用方手里）、判定工程类（有门禁有审查，但只有一条线）。单智能体产品缺编排，编排框架缺门禁，判定工程类只有一条线——本引擎把三样塞进同一个引擎。

装进来你会得到什么

三层门禁与批次/成员状态机 · 单写者锁 · 隔离工作区与存档点 · 任务难度门禁 · 显式消息通道（三个信箱、只写元数据、消费需确认）· 心跳与长跑探针 · 调用级护栏（六种裁决原语 ＋ 可验篡改的拒绝收据，出厂规则为空、装上不改变行为）· 本地审计日志（默认开、不外发）· 只读监控面板。

另随包 5 套团队技能：软件工程、设计、调研、视频、写作。软件工程那套另含规格语言原文与适配层——写规格、查结构、验一致性都有据可依。

它管不到的地方

不判模型意图（护栏在工具调用层，生成与推理不在防线内）；不是沙箱、不做联网网关、不检测绕过显式通道的侧信道；不提供一次性写入存储（哈希链防静默篡改，不防删除，也无第三方签名）；判定不了调用者身份（留痕是记录与可见性，不是访问控制）；单机进程内治理，不做跨机编排；护栏出厂规则为空，裁决恒放行。

所以它不宣称「防住了模型跑偏」。它提供的是一个位置选择：把可判定的越界与交付缺失拦在执行期，而不是等它变成一份事后报告。

谁该用

一个人或一个小型技术团队，做的是有验收标准的交付——代码、调研、设计、写作都算。三个条件同时成立才值得：

1. 你同时在推进好几件事，不是改一个函数；
2. 你需要产物链可追溯、失败可查、越界能拦；
3. 你不愿意在 Agent 说做完了之后，自己再当一遍审查者。

三条同时成立的人不多。但如果你恰好是这种人，市面上没有第二个选择——这不是调研结论，是当初自己动手写插件的原因。

安装

前置：已安装 DeepSeek Harness（dsh），Node.js ≥ 22。

dsh plugin add dsh-punky-swarm
dsh web restart

备选：npm install -g dsh-punky-swarm 后 dsh plugin --profile <profile> add dsh-punky-swarm；开发路线可用 link: 指向本地包目录。

重启后会话区多出蟛蜞集群面板，团队技能自动同步到用户目录——安装即得，无需额外配置。

兼容性与许可

版本单一真源 packages/dsh-punky-swarm/package.json（变更见 CHANGELOG.md）。测试基线：204 个测试文件 / 2,147 个测试 / 10,560 条断言 / 0 条恒真（单一真源 baselines/test-baseline.json）。

peer 依赖：@deepseek-ai/dsh-tools（^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.1.5-rc.1 || ^0.1.6-alpha.1 || ^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.2）与 @deepseek-ai/cordis（^4.0.1）；零第三方运行时依赖。边界：单机进程内治理，无分布式同步、无成本控制、无模型路由，零云依赖、默认零网络暴露；失败即终态，不自动续跑。

许可：GNU AGPL v3（AGPL-3.0-only）为唯一许可；遵守 AGPL-3.0 可自由使用、修改、分发（含商用），修改后经网络提供服务须公开修改内容。