DeepSeek Harness 插件

Punky971210/dsh-punky-swarm#dsh-punky-swarm

Star 数 ★ 4 下载量(近 30 天) 1,871 分类 工作流与自动化 收录于 2026-08-19 npm dsh-punky-swarm

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/dsh 0.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-tools 0.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 宽声明是否仍覆盖宿主主版本,或在插件管理器里显式允许该版本。

内容来自项目 README(GitHub)↗

链接

同类插件

查看整个分类 →

社区评论

评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。