dsh 单机多子 Agent 集群治理:引擎级质量门禁拒收半成品、崩溃断点续跑不重来——给 AI 团队装上"跑不坏"的工程护栏。
安装
# npm 包(预构建)
dsh plugin --profile web add dsh-punky-swarm
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:Punky971210/dsh-punky-swarm#path:/packages/dsh-punky-swarm
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
DeepSeek Harness(dsh)的集群治理插件 + 引擎 —— 把「大型模块开发」拆成 plan → exec → audit 三层 DAG,配 门禁 / 状态机 / 黑板 / 结算,让多成员协作可派发、可审计、可恢复。 版本基线:
0.6.0—— 团队资产(team-asset)与chain声明面已整体退役;team为可选自由标签(不解析、不校验、不拒建批)。 适用宿主:@deepseek-ai/dsh0.2.x(宽声明;不钉具体 rc)。prerelease 宿主需在插件管理器里豁免。
一、这是什么
一句话:一个以产物为核心单元的多 Agent 治理引擎 —— 成员之间交接的不是「消息」或「子任务」,而是可 stat、可校验、可在场判定的产物。
为什么这件事重要:多 Agent 框架的常见失效不在模型能力,而在交接凭据太软。「我发给你了」「我做完了」这类自报,既无法验证也无法追责;一旦上游说做完了而产物不在,下游会带着空输入跑完整个流程。蟛蜞把交接单元从消息换成产物后,下面每一环都有了硬判据:
| 维度 | 常见多 Agent 框架 | 蟛蜞引擎 |
|---|---|---|
| 交接单元 | 消息 / 子任务 | 产物(批次内相对路径) |
| 交接凭据 | 「我发给你了」 | handoff_submit + artifacts 逐个 stat |
| 完成判据 | Agent 自报 | 产物在场 + 门禁判据(exit / targets / command) |
| 依赖表达 | 运行时调用链 | 建批期静态 DAG(lanes[].deps + handoffs),建批后不重算 |
| 失败处理 | 重试 / 换人 | 状态机 + GATE_* 拒码 + 事件流留痕 |
| 上下文 | 共享或长上下文 | 每 lane 独立任务包(拆上下文,防需求漂移) |
理念来源:把单 Agent 的「思考—执行—自检」外延成多 Agent 执行规范(plan → exec → audit),用门禁和状态机替代单 Agent 的自主判断;简单的 orchestra 式任务分发承载不了长程任务,所以引擎把任务拆到以步长行进的粒度,避免长程上下文腐败。作者观点:MCP / ACP 这类互联协议对 Agent 没有强制性,不能当作工程引擎的执行规范使用 —— 强制力只能来自门禁。
目标形态:一个内置或临时的 Agent 团队,稳定、不偏离、可并行、高吞吐、有依赖、有指导地运行(运行时 DAG + 执行留痕 + 上游指导下游 + 按需加载技能)。
能力面:wave_plan(按依赖 DAG 分层为 waves,建批后不中途重算)→ lane_dispatch / member_status(派发)→ handoff_submit(逐边交接)→ member_settle(结算);辅以 gate_status(门禁态)、log_export(事件导出)。lane_heartbeat / lane_longrun 已于 G3 B1 删除(原属停维面:维护冻结、功能保留不续维,2026-10-09 用户裁定;现无工具入口,其事件面改由 batch_status / log_export 读取)。
治理纪律:29 条 / 9 组(评估派发 / 批与交接 / 运行模式 / 审计验收 / 结算 / 恢复监管 / 输出·能力·指引 / 两方向·编号 / 执行前经验检索 / 证据·落点),细则见 references/discipline.md。
它治的是什么:一批 Agent 一起干活时的四类事故 —— 上游产物没齐就开工、跑几小时一崩全丢、几个成员同时写同一份文件、拦了却说不清为什么。工具本身没坏,缺的是流程上的闸口;闸口装进引擎后,纪律成为机器判据,而不是各成员的自觉。
装配基线:团队资产与 chain 声明面退役后,装配按「引擎基线 + 成员槽位 + 指引」;运行期 DAG 真源 = 批次 lanes[].deps + handoffs。
二、安装后得到什么(三面构成)
| 面 | 载体 | 落点 / 说明 |
|---|---|---|
| ① 插件(核心) | lib/** + cordis.patch.yml 两行 |
引擎行 dsh-punky-swarm(状态机 / 面板 / HTTP / 门禁引擎;不注册治理工具)+ preset 注册行 dsh-agent-preset-punky(0.1.7 起 preset 必须由插件行注册,不再扫描预设目录)。治理工具(27 件)由预设组合里的 punky-provider 行注册 ⇒ 只有 punky-preset 会话(含其派生 worker)在工具目录里看得到,其它模式零污染(装配隔离,2026-11-08) |
| ② 模式与指引(核心) | @deepseek-ai/dsh-agent-preset 注册的 punky-preset(蟛蜞模式) |
references/discipline.md 由启动期 syncAssets() 幂等同步到 <home>/.dsh/.agent-presets/punky-preset/ |
| ③ 团队技能指针(附加) | skills/ 5 个目录 |
design-team / research-team / software-team / video-team / writing-team ⇒ 同步落点 <home>/.agents/skills/<name>/ |
能力层(software-team):
skills/software-team/references/engineering/spec-contract.md现为蟛蜞适配层(六态证据 →gate_status/verdict映射 /SUMMARY:机读行落地 / S-10 缺口留档);规格结构与机械规则原文以仓内 vendor 原件为准(见下条),由SKILL.md的角色必读表按角色挂载。 外部能力层(已 vendor 进仓,recommend 语义不变):SKILL.md同节收录外部 SpecLang(SpecArtisans)四技能 ——speclang-waterfall/speclang-hoare-check/prd-guide/ui-component-registry。资产已 vendor 进仓:skills/software-team/references/vendor/speclang/(29 件 = 27 件上游资产 +LICENSE+NOTICE.md,合计 532,898 B;版本钉SpecLang@b3ee6ee,逐件 sha256 见NOTICE.md),读者直接读仓内原件、不依赖宿主是否装了同名技能。vendor 不改变 recommend 语义:仍按需加载、不进引擎装配面、不在册不构成失败、不影响任何门禁。源仓许可 Apache-2.0 + 运行时库例外、署 The Cangjie Project、权利人待确认;配套 node 薄壳scripts/speclang-validate.mjs(ruby不可用时exit 2= 明示未取证,绝不伪造通过)。角色级入口已接上:coder/designer/coordinator指向speclang-waterfall/(+prd-guide/),reviewer/tester/supervisor指向speclang-hoare-check/(涉 UI 追加ui-component-registry/),各 1 行、标「选读(recommend)≠ 必读」;doc-manager按 K-3 不挂。机检守护:6 个挂载角色恰各 1 条指针、路径逐条existsSync(死指针即红)、同行必须 recommend 措辞。
三、安装
通过 dsh 插件管理器以 git 地址安装 —— dsh plugin add 会把参数原样透传给 profile 内的 pnpm,故任何 pnpm 可接受的 spec 都可用:
dsh plugin add "git+https://github.com/Punky971210/dsh-punky-swarm.git#v0.6.0"
本包 dependencies 为空,两件上游 bundle 需显式另装(见 §四)。另有一条环境前提:profile 若无 .npmrc,建议先写 auto-install-peers=false —— 否则 pnpm 可能装出第二份 @deepseek-ai/cordis(两个 cordis 实例互不识别,插件挂不上)。
四、上游依赖 / 前置(两件显式 spec)
| 包 | 角色 | 声明位置 |
|---|---|---|
@deepseek-ai/dsh-experimental-agent-team-profile |
聚合 bundle:装它即带出 -agent-team / -client-ui-agent-team / -tool-agent-team(spawn_teammate / team_task_* / send_message / wait_agent / list_agents / interrupt_agent 工具面来源) |
仅命令显式列出 |
@deepseek-ai/dsh-agent-preset |
模式注册插件本体(cordis.patch.yml 的 dsh-agent-preset-punky 行以它为 name) |
仅命令显式列出 |
- 只要宿主装有 dsh 官方包即可用 —— 上游包只由安装命令的显式 spec 提供。
- 版本策略:声明面与安装面分离
peerDependencies=@deepseek-ai/cordis>=4.0.1+@deepseek-ai/dsh-tools0.2.x,两条均标peerDependenciesMeta.optional—— 否则 npm 7+ 会把它当安装闸;且 pnpm 的autoInstallPeers会在 git 安装时装入第二份 cordis(实测:非 optional 时 lockfile 出现(@deepseek-ai/cordis@4.1.0)后缀)。devDependencies=^0.2.2-rc.1(dsh-tools/dsh-scope/dsh-app-boot):registry 上零稳定版,实测npm view '@deepseek-ai/dsh-tools@0.2.x' version⇒could not be found⇒ 安装面必须给可解析的 rc 下界,否则npm ci必失败。- 标准 semver 下
0.2.x不匹配 prerelease 宿主(如0.2.x-rc.y)⇒ prerelease 宿主请在插件管理器里允许/豁免。
workflow-ptc由内核提供(@deepseek-ai/dsh-base依赖它)⇒ 无需额外安装;禁自行回加旧推进器行(见 §九)。- 本包对团队服务的依赖声明:引擎消费宿主服务
agentTeams,声明落在装配面(cordis.patch.yml的探针行inject: [agentTeams]),不进dependencies。缺该服务时该行进入 pending(启动审计响亮),同级引擎行与模式行照常存活。
五、装完自证(三面只读自检)
node scripts/selfcheck-install.mjs --home <dir> --json # exit 0 ⟺ engine / preset / skills 三面齐备
node scripts/smoke-install.mjs # 宿主级安装冒烟(含真实 home 污染守卫)
(两个脚本随包提供;冒烟会在临时 DSH_HOME + 临时 home 上装一次并断言三面。)
六、隔离测试步骤(务必照抄)
⚠ 关键事实:
syncAssets()用os.homedir(),且不读DSH_HOME。 ⇒ 只隔离DSH_HOME是不够的:它仍会把同步结果写进真实用户主目录的~/.agents/skills/*与~/.dsh/.agent-presets/punky-preset/*(= 覆写你既有资产;同类事故在本仓有 21 件真实技能文件被覆写的前科)。 ⇒ 必须同时隔离DSH_HOME与USERPROFILE/HOME,并加真实 home 前后 sha256 守卫。
6.1 Windows(PowerShell,逐行可抄)
# 0) 记住真实 home —— 第 2 步会覆盖这些变量,第 5 步必须用 $Real 复算
$Real = $env:USERPROFILE
$Tmp = Join-Path $env:TEMP ("punky-iso-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path "$Tmp\dsh-home","$Tmp\home" -Force | Out-Null
# 1) 真实 home 的 sha256 基线(只读;覆盖 skills 与 preset 两处)
Get-ChildItem -Recurse -File -ErrorAction SilentlyContinue -Path "$Real\.agents\skills","$Real\.dsh\.agent-presets\punky-preset" | Get-FileHash -Algorithm SHA256 | Sort-Object Path | ForEach-Object { "$($_.Hash) $($_.Path)" } | Set-Content "$Tmp\real-home.sha256.before"
# 2) 双变量隔离(缺一不可)
$env:DSH_HOME = "$Tmp\dsh-home"
$env:USERPROFILE = "$Tmp\home"
$env:HOME = "$Tmp\home"
# 3) 在本窗口内执行 §三 的唯一命令(不要新开窗口,否则环境变量丢失)
# 4) 三面断言(示例,可自行加严)
dsh --profile web --dump-config | Select-String 'dsh-punky-swarm'
dsh --profile web --dump-config | Select-String 'dsh-agent-preset-punky'
Test-Path "$Tmp\home\.agents\skills\software-team\SKILL.md"
Test-Path "$Tmp\home\.dsh\.agent-presets\punky-preset\references\discipline.md"
# 5) 污染守卫:复算真实 home 并与基线比对 —— 输出为空才算通过
Get-ChildItem -Recurse -File -ErrorAction SilentlyContinue -Path "$Real\.agents\skills","$Real\.dsh\.agent-presets\punky-preset" | Get-FileHash -Algorithm SHA256 | Sort-Object Path | ForEach-Object { "$($_.Hash) $($_.Path)" } | Set-Content "$Tmp\real-home.sha256.after"
Compare-Object (Get-Content "$Tmp\real-home.sha256.before") (Get-Content "$Tmp\real-home.sha256.after")
- 守卫判定:
Compare-Object无输出 = 真实 home 未被触碰;有输出 = FAIL ⇒ 保留$Tmp现场(勿删)并据差异清单排查。 - 测试结束后可删临时根:
Remove-Item -Recurse -Force $Tmp(仅在守卫通过后)。
6.2 POSIX(macOS / Linux)
Real="$HOME"; Tmp="$(mktemp -d)"; mkdir -p "$Tmp/dsh-home" "$Tmp/home"
find "$Real/.agents/skills" "$Real/.dsh/.agent-presets/punky-preset" -type f 2>/dev/null | sort | xargs shasum -a 256 > "$Tmp/real-home.sha256.before"
export DSH_HOME="$Tmp/dsh-home" USERPROFILE="$Tmp/home" HOME="$Tmp/home"
# 在此 shell 内执行 §三 的唯一命令
find "$Real/.agents/skills" "$Real/.dsh/.agent-presets/punky-preset" -type f 2>/dev/null | sort | xargs shasum -a 256 > "$Tmp/real-home.sha256.after"
diff "$Tmp/real-home.sha256.before" "$Tmp/real-home.sha256.after" && echo "GUARD OK" || echo "GUARD FAIL"
七、卸载 / 回滚
dsh plugin --profile web remove dsh-punky-swarm
或从 profile 的 dsh.profile.bundles 摘除本包后重启。团队包若不再需要,同法移除。
八、文档
| 文档 | 内容 |
|---|---|
references/discipline.md |
治理纪律细则(码表 / 语义 / 边界 / 操作序列) |
docs/engine-intro.md |
引擎内部说明 |
skills/software-team/references/engineering/spec-contract.md |
software-team 能力层:规格契约细则(机械规则 / 六态证据 / 机读行 / 需求编号;SpecLang b3ee6ee 提炼引用,recommend 语义非装配) |
九、已知边界(如实)
- 安装失败只落 stderr warning(引擎按 per-entry fail-soft:本插件两行都不在必需启动清单内)⇒ 模式可能静默未挂载。请用 §五 的自检脚本主动核。
- 预设子项在会话装配期挂载(不经启动期审计)⇒ 某一子项异常只影响该 preset 的 agent 组合,同样只留 stderr。
- workflow 面:
@deepseek-ai/dsh-workflow-ptc由内核提供,单行即可。禁项:① 禁回加旧推进器行(@deepseek-ai/dsh-workflow-…worker-thread 包,会新增必失败行);② 禁新增!!js版本条件行(内核无宿主版本变量 ⇒ 条件行不可达)。 - 宿主升级后:若插件行被兼容门跳过(stderr 出现
skipping profile bundle),检查peerDependencies宽声明是否仍覆盖宿主主版本,或在插件管理器里显式允许该版本。
链接
同类插件
loopx-project/loopx#dsh-loopx-plugin★ 6700
LoopX——面向长周期 Agent 的提供商中立、本地优先状态内核与控制平面:在 DeepSeek Harness 执行层之上持久化 Goal、Todo、门禁、证据、配额、恢复与交接状态;插件负责引导安装 CLI 与技能、准入有界的同会话续跑,并为精确绑定的工作循环提供本地 GoalBar。
Q00/ouroboros#integrations/dsh-plugin★ 6373
通过 DSH MCP 客户端挂载 Ouroboros 的纯配置包,在 DSH 中提供 36 个涵盖需求访谈、Seed、执行、评估与演化流程的工具。
chuspeeism/dashi-taskboard#deepseek-harness★ 3498
把当前已安装并运行中的 Codex Taskboard 嵌入 DeepSeek Harness 侧边栏,并通过 Launcher 运行时描述文件连接,而不是使用固定端口。
NanmiCoder/dsh-agent-teams★ 2984
AgentTeams 多智能体团队。
EthanYoQ/AI-Novel-Writer#dsh-ai-novel-writer★ 2669
安装专用 AI 小说创作预设与工作台:提供带修订号的本地项目资产、紧凑侧边工作台,以及需要原生审批的逐文件变更。
shanliuling/dsh-image-gen★ 1581
为 DeepSeek Harness 提供原生对话生图能力:直接让 Agent 画图,插件自动完成生成并把结果保留在当前会话中。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。