多智能体编排器fiultyy/maestro-preset

maestro — 高级编排模式(DSH agent preset)

将 DeepSeek Harness 会话转变为多智能体编排监督器 — 通过持久回调桥协调 Orca 终端/工作树、dais 窗格(原 zap)和 DSH 子智能体会话之间的工作,并配备 SQLite 项目账本和编译式监督平面。

License: MIT
zero npm deps
preset
GitHub stars
GitHub forks
GitHub issues

English TL;DR — maestro 是一个自包含的 DeepSeek Harness agent preset:将其克隆到 ~/.dsh/.agent-presets/maestro,在新会话中选择该预设,该会话即成为编排监督器。它附带 6 个插件(file-pump + HTTP 回调桥、host-lane 桥、工作区解归档、会话清除)、14 个 CLI 工具(跨会话消息传递、fleet 准入/租约、工单派发、SQLite 账本、流程编译器),以及面向 Claude/Orca/dais 智能体的对等发现技能。零 npm 依赖 — 仅使用 node: 内建模块和相对导入。完整手册:USAGE.md。

跨 Orca、dais(原 zap,2026-08-17 改名)、DSH 三平面的多 agent 编排套件,以 DSH agent preset 形态分发。本目录自包含: 插件、技能、脚本全部随包走,零 npm 依赖(仅 node: 内建 + 相对 import)。

装好后怎么用 → 使用说明 USAGE.md;开发调试(dev-sync 同步,禁用软链接)→ USAGE §10;打包规范(怎么装成插件/怎么发布)→ PACKAGING.md;回调桥抽象设计 → callback-bridge-design.md。

为什么值得一个 Star

| 能力 | 一句话 |
|---|---|
| 双通道回调桥 | 文件桥(at-least-once: 去重/死信/轮转/游标)+ HTTP 直发,对端 cb-send 自动降级,投递语义有持久证据 |
| host lane | host-callback-bridge 把回调链路上移到宿主 boot,sessionId 成为跨重启的持久路由键 |
| fleet 准入 | Orca 终端 probing→verified 探测准入 + 心跳 + 属主租约(fleet-touch claim/heartbeat/release/sweep) |
| SQLite 项目账本 | 分发/回收/审查全落账,节点过程跨会话持久(bin/ledger) |
| flowc 编排编译器 | flow.yml → 状态机(节点/单元/触发器 SQL),十动词监督面 |
| 回合外事件守护 | event-watchd 常驻巡检,agent 不在场也能推进 |
| 对端冷发现 | shared/maestro-bridge 技能镜像到 ~/.agents/skills,Claude/Orca/dais 侧 agent 凭它接入回调协议 |
| 分发即复制 | 无构建、无 npm install、无第三方依赖;git clone 即用 |

flowchart LR
subgraph planes["三个工作平面"]
ORC["Orcaterminal / worktree"]
DAI["dais pane(原 zap)"]
DSH["DSH 子会话"]
end
ORC & DAI & DSH -->|"bin/cb-sendack / done / ask"| BR["回调桥file inbox + HTTP去重·死信·at-least-once"]
BR -->|"注入回合"| ORCH["编排者会话(maestro preset)"]
ORCH -->|"bin/session-sendDSHMSG 信封"| planes
ORCH -.->|"bin/ledger 落账"| DB[("ledger.db")]
ORCH -.->|"fleet.json准入·心跳·租约"| FL["fleet 码表"]

前置要求

| 依赖 | 用途 | 缺失时的降级 |
|---|---|---|
| DeepSeek Harness (DSH) | 宿主 | 不可用 |
| Orca (orca-ide/orca-dev) | 桥 pane、terminal send、worktree 管理 | 仅剩普通编码能力,编排面不可用 |
| sqlite3 CLI | 项目状态账本 | 账本技能不可用 |
| python3 + curl | bin 脚本(session-send/cb-send/fleet-probe 等) | 对应脚本不可用 |
| dais (原 zap,可选) | dais 平面投递 | 该平面跳过 |

安装

方式一: git(推荐,可升级)
git clone https://github.com/fiultyy/maestro-preset.git ~/.dsh/.agent-presets/maestro

方式二: 复制目录
cp -r maestro/ ~/.dsh/.agent-presets/maestro

可选但推荐——安装对端共享 skill(其他 harness 的 agent 冷发现回调协议;开发流 bin/dev-sync.sh 自动完成,无需手工):

mkdir -p ~/.agents/skills
cp -r ~/.dsh/.agent-presets/maestro/shared/maestro-bridge ~/.agents/skills/
ln -sfn ~/.agents/skills/maestro-bridge ~/.claude/skills/maestro-bridge   # claude 发现面

安装后新建会话,preset 列表出现「高级编排模式」,选用即挂载。preset 一经选用不可热切换;升级 = git pull + 重启 DSH 进程(运行中会话保持加入时的代际,属预期)。

包结构

maestro/
├── preset.yml            # 名字/描述(官方 schema: name/description[/order],本包不设 order → 排在官方集之后)
├── agent.cordis.yml      # 组合文件: persona(编排纪律)+ 每插件一行的注册表(路径相对本目录、写到精确 .js)
├── plugins/              # 插件(每个 = 一个 ESM 入口,export inject + apply(ctx, config))
│   ├── callback-bridge/  #   回调统一内核 v4(Sources→Codec→内核→Sink;文件桥 at-least-once + HTTP 直发双通道共享语义;含测试;已吸收早期 orca-callback/message-bridge)
│   ├── host-callback-bridge/  # host lane: 宿主 boot 承载回调链路(受理即持久,sessionId 跨重启路由)
│   ├── a2a-profile-server/    # 孵化池插件(独立守护 :8790;cordis polyfill lane,非 polyfill.patch.yml 注册)
│   ├── persona-axis/     #   会话级人格轴(host half):人格与 preset 正交,A2A 池注入遮蔽,RPC=/persona-axis/rpc
│   ├── _narrow-waist/    #   窄腰共享库桶导出(信封/dedup/词汇表单一物理源,零逻辑零副作用)
│   ├── workspace-unarchive/  # 会话归档恢复(活体 registry 走 setState 同路径)
│   └── session-purge/    #   按需删除会话(RPC 面无 session.delete,补全生命周期)
├── bin/                  # CLI 脚本(26 项;dev-sync 镜像到 ~/.dsh/maestro/bin 作兜底)
│   ├── ledger            #   账本助手(node/event/review/status/ticket,替代手写 SQL)
│   ├── dispatch-ticket   #   票派发一体化: 读票→组契约→terminal send→落账
│   ├── flowc             #   编排编译器 v2(flow.yml → 状态机,十动词监督面)
│   ├── event-watchd      #   回合外常驻事件守护(声明式四类看守面;systemd: maestro-watchd.service)
│   ├── wave-checkpoint   #   波次检查点机读 JSONL(原子追加)
│   ├── verify-report     #   审查助手: 重跑验证门 + 解析回报 → A/B/C 判定草稿
│   ├── session-send      #   跨会话消息直发(DSHMSG 信封 → /api/session.prompt;另有 v3 窄腰信封变体)
│   ├── session-spawn     #   起新会话并入 fleet(回显 4 位码)
│   ├── session-purge     #   调 session-purge 插件的 purge 端口
│   ├── cb-send           #   对端回调投递(ACK/DONE 握手;HTTP 优先,文件桥兜底;HTTP 200≠送达,见 USAGE §3.3;另有 v2 变体)
│   ├── msg-dedup         #   收方回合首动作去重(信封 v2,60s 窗口)
│   ├── orca-send         #   DSH→Orca 窄腰 adapter(orchestration send Run mailbox 优先)
│   ├── bridge-rearm      #   桥 registry 卫生一条命令(清死条目/重注册/验活)
│   ├── fleet-probe       #   Orca 终端准入探测(termid 回报验证后才入编排列表)
│   ├── fleet-touch       #   fleet 心跳 + 属主租约(claim/heartbeat/release/sweep)
│   ├── fleet-list        #   列出 fleet.json 在册席位(读侧,零写入)
│   ├── fleet-release     #   席位释放原语(摘条目+可选归档会话+清 liaison 绑定)
│   ├── liaison-state     #   读网关 liaison 绑定状态(读侧,零写入)
│   ├── session-archived  #   判定 sessionId/code 是否已在归档集(读侧,零写入)
│   ├── worker-up         #   dais 编排面 worker 供给一体化(开 pane→绑定→起 harness→派任务)
│   ├── dev-sync.sh       #   开发同步: 正向 / --reverse 回流 / --verify 漂移报告
│   └── rebuild-host-packages.sh / release-check.sh / githooks  # 宿主包重建与发布检查
├── shared/               # 对端共享 skill(镜像到 ~/.agents/skills,供其他 harness 的 agent 发现)
│   ├── maestro-orch/     #   编排者总入口(三平面契约模板/回调语义/红线;Orca 桥 pane 手册在此)
│   ├── cb-send/          #   worker 侧回调手册(一条命令回报;触发词冷发现)
│   └── dais-orchestration/  # dais 平面 v2 命令面 + 别名透明代理契约
├── tests/                # 自测(cb-send 降级链 + OF-001..010 加固波自测)
├── docs/                 # 设计文档(DESIGN / callback-bridge 抽象 / orch-loop / fleet 约定 / PACKAGING)
├── host/                 # 独立分发面①: 装点自研插件(host/install.sh 统一安装,dev-sync 不碰)
│   ├── packages/         #   4 个 @deepseek-ai/dsh-long-task* 构建包 → profile node_modules
│   ├── plugins/          #   random-uuid-polyfill / workspace-unarchive / ui-agent-pool → ~/.dsh/plugins
│   └── polyfill.patch.yml#   host 补丁组合模板(run-web.sh --patch 挂载,路径 DSH_HOME 感知)
└── agent-presets/        # 独立分发面②: long-task / liangshen 两个自研 preset(→ ~/.dsh/.agent-presets/)

运行时状态(不在包内,自动生成)

包是无状态的;一切运行数据落 ~/.dsh/maestro/,首次使用自动创建:

| 路径 | 内容 |
|---|---|
| ~/.dsh/maestro/bridge/ | inbox.log(桥)、registry.json(消费者)、.cursor.、state/dead/echo |
| ~/.dsh/maestro/fleet.json | 会话 fleet 码表(session-send/spawn 读写) |
| ~/.dsh/maestro/ledger.db | SQLite 账本 |
| ~/.dsh/maestro/bin/ | bin/ 镜像(cb-send 兜底安装点,dev-sync 维护)+ 换代交接简报 handoff-.md |
| ~/.dsh/maestro/flows/ | flowc v2 编译产物(state.db 状态机 + triggers.sql + nodes/),每流程一目录 |

环境变量

| 变量 | 缺省 | 作用 |
|---|---|---|
| MAESTRO_BRIDGE | ~/.dsh/maestro/bridge | 桥目录(泵 + skill 脚本同认) |
| MAESTRO_BRIDGE_ALIAS | (无) | bridge_arm 的消费别名 |
| MAESTRO_LEDGER | ~/.dsh/maestro/ledger.db | 账本路径 |
| MAESTRO_HOME | ~/.dsh | DSH home(插件内运行数据定位) |
| MAESTRO_FLEET | ~/.dsh/maestro/fleet.json | fleet 码表路径 |
| MAESTRO_ORCH_SIGNATURE | (无) | fleet-probe 必需: 编排者 @ 签名,嵌进探测消息回信地址 |
| MAESTRO_PRESET_BIN | ~/.dsh/.agent-presets/maestro/bin | fleet-probe 探测消息里 cb-send 的路径 |
| MAESTRO_SHARED_SKILLS | ~/.agents/skills | dev-sync 镜像 shared/ 的目标目录 |
| DSH_PORT | 3080 | session-send 目标端口 |

快速开始(装完后第一个会话)

1. 会话开场注册回调身份——host-lane 部署(USAGE §3.4)不在会话内 arm,POST /register {"sessionId","alias"} 到 bridge/http.port 所记端口(host lane 持有 HTTP 通道);裸 preset 部署单次 bridge_arm {alias}(file 桥;bridge_http_status 为 deprecated 别名)。回执给出规范签名 @
2. 按 shared/maestro-orch/SKILL.md 建 Orca 桥 pane(一次性)
3. Orca 终端入编: MAESTRO_ORCH_SIGNATURE= bin/fleet-probe ,回报匹配入 verified 后才可派发(见 USAGE §5)
4. 之后外部 agent 的回调经桥自动驱动本会话回合;对外发消息用 bin/session-send

信任边界(必读)

本 preset 的插件会执行文件系统写入、开本地回环监听端口、驱动会话回合;技能指使 agent 操作 Orca 终端。按 DSH 的信任模型,user preset 等同 shell 权限——只装你愿意托付 shell 的来源的包。装了什么、每行是什么,见 agent.cordis.yml(逐行注释)。

升级 / 卸载

- 升级: git pull → 重启 DSH → 新会话用新代际(旧会话自然消亡)
- 卸载: 删掉 ~/.dsh/.agent-presets/maestro/ 即可;运行数据在 ~/.dsh/maestro/,另行处置

在多 harness 环境里跑过编排、踩过投递/换代/准入这些坑的话,这套东西应该能帮你省不少时间——觉得有用欢迎 Star,想改造成自己平面的编排面直接 Fork;issue 里报现场(复现步骤 + 桥日志)最快得到响应。