Index of every page on this site: llms.txt
All skills
cat-xierluo avatar

/multi-agent-orca

@5fb69a0
Run it yourself

编排两个以上边界独立的本地 worker,使用 Orca Run/Task/Dispatch、独立 worktree/session 或 tmux 回退,由 PM 负责拆解、派发、巡检、429 停滞恢复、独立验收、PR 收口与临时资源清理;也用于用户明确要求“并行推进”“多个 worker”“PM 总控”“Wave Autopilot”或防止 PM 直接实现逃逸。不要用于单个短任务、纯状态同步,或仅需 Git 分支、提交、PR、merge 规则的工作。

Use this Skill: https://skilld.dev/gh/cat-xierluo/legal-skills/multi-agent-orca

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

references10-parallel-lessons.md

≈2.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

并发任务排障索引

遇到具体异常时读取本页。日常流程以 SKILL.md 为准;下列入口复用当前合同,历史项目事故、旧版本参数和性能记录留在维护任务/本地归档。

1. 先确定卡在哪一层

现象 先读事实 操作权威
backend/宿主被拒 实际PM祖先链、policy与本轮选择 06 CLI路由、26按需backend
consumer_fenced / 协调身份拒绝 原run-use/create回执、coordinator handle及本轮consumer 14 PM控制,保留原Run/Task,不重建Run逃避fencing
spawn失败但已有工作树/终端 正式回执、精确资源归属、输入是否已消费 13 Orca worker、31借用边界
原生CLI就绪未知 实际进程、composer及匹配入口的就绪证据 32 profile;ZCode原生另读30
命令accepted但未工作 原输入/原生会话是否消费、实际活动与产物 14 PM控制、33接续
权限/登录/信任等待 精确请求、命令、身份与新鲜screen 02授权边界、对应backend操作页
模型或provider不符 实际请求证据与选定配置 06、ZCode的28
429、空闲或预算拒绝 新鲜额度/压力、原native活动及pending输入 20限流、22内存
worker完成后PM不接续 原PM、正式监测配置/触发、是否人工唤醒 33、15波次
STATUS done但不能结算 真实产物、Task/Dispatch、Delivery、lease/资源 18验收、23结算
主CLI退出仍有负载 本轮归属清单、后代/额外shell/端口与保留理由 37资源收尾

失败与未知都保留原件。先确认发生了什么,再消费原合同允许的恢复动作;不因一条失败退出码重新派发已经工作的任务。

2. Agent Teams与消息

官方Teams配置/inbox与本Skill的Session Context不是同一状态源。成员创建、收件、上下文不足等问题读取 11 Teams排障;不要以项目内自建同名目录冒充官方团队状态。

T1. tmux输入未提交

在已经选定tmux回退的原会话核当前输入状态,区分文本输入与提交键,观察实际消费。按键不能保证原生业务开始;不固定重复Enter、attach占住PM或把文本发送给退回的shell。

T2. 输入法或终端键处理

确认目标窗口/终端、输入法和CLI当前状态后再处理原输入。优先正式CLI控制接口;不要把本机一次键盘修复写成其他backend通用配方。

T6. spawn worker撞项目MCP选择dialog

先核任务是否需要MCP。Claude路线的--no-mcp是显式选择;CodeBuddy默认strict空MCP、需工具时--with-mcp。通过现有renderer生成,见 06 / 08。不以--bare、盲Escape或删全局hooks规避正式门。

本小节继续承接claude-provider-env.sh和spawn注释中的T6旧指路;当前行为以这两份backend指南及实际代码为准。

3. 工作树、依赖与基线

G28. verify用主仓node_modules

先核项目允许的依赖复用方式、实际工作树路径与验证命令。主仓存在依赖不证明任意Orca工作树可以解析到它;也不意味着worker可自动安装。使用 02依赖合同 的实际入口,保留复用/缺失证据。

G31. Orca工作树脱离主仓父链

工作树位于另一根目录时,Node向父目录解析依赖的结果可能不同。核真实cwd与解析路径,按项目合同选择依赖复用或获授权安装;不要为解决验证失败把任务移回主仓或扩大写范围。G28/G31保留供spawn-worker-deps.sh旧注释定位。

分支、HEAD与重复创建

比较任务变更时先核冻结起点/实际基线,再检查与最新主干的关系;按项目Git规则集成,不照搬历史直接merge处方。occupied分支/工作树按正式借用或恢复合同处理,不加后缀重建来解除拒绝。

工作树实际目录/分支/HEAD应在任务注入前通过正式隔离门。已有partial-create残留先核所有权及原输入消费,再按原任务恢复;仅创建资源成功不等于worker-start成功。

G40. 复用 branch 名 → Orca 自动 -2 后缀 → worker-start 先于门禁的 partial dispatch(isolation pre-gate)

实战来源:2026-09-02,PM 请求复用已有 worktree/branch 派 supervised worker(claude-code)的 spawn 事故复现。

  • 现象:Orca worktree create 发现同名 branch 已存在时自动改用 -2 后缀分支新建 worktree。spawn-worker.sh 旧顺序里 terminal create + supervised register/worker-start(任务注入)先执行,末尾 final SPAWN_WORKER_GATE 才发现 actual branch != expected 而 exit 2——但 Dispatch/worker 已带任务活跑。spawn 报失败、编排面却留下半活 Task/Dispatch/terminal,PM 无法从退出码判断"到底起没起"。
  • 根因:final gate 里 cwd/branch/HEAD 这类在 worktree 落盘后立即可判定的事实,被排在了 terminal/worker-start/dispatch 副作用之后。校验时机与副作用边界错位,失败语义就从"拒绝创建"退化成"召回半成品"。
  • 修复:spawn-worker.sh 在 worktree 落盘并 realpath 后、ensure_worktree_deps/Session Context/authority receipt/METADATA/guard/terminal 之前插入 isolation pre-gate:非 lightweight 且非 dry-run 时机械判定 git -C <worktree> branch --show-current == $BRANCH 且 HEAD 可解析;mismatch 打印 SPAWN_WORKER_ISOLATION_PREGATE_FAILED 并 exit 2。此时 fake Orca 调用日志只有 worktree current/status/create,没有任何 terminal create/run-create/task-create/worker-start,Session Context 与 receipt 未落盘(失败重试不会撞 receipt 已存在的 fail-closed),worktree 保留供 PM 精确清理。final SPAWN_WORKER_GATE 只保留 pane cwd 这个 launch 后才能观察的校验。
  • 教训:
    • 凡"创建资源 → 观察资源实际形态 → 校验期望"的流程,校验必须紧贴观察点、先于下游第一个不可撤销副作用;把校验堆在流程末尾等于把失败变成召回。
    • 门禁前移不是加一道重复检查,是同一检查换到副作用边界之前;final gate 保留的部分(pane cwd)是 launch 前原理上不可判定的,不算冗余。
    • 失败路径还要考虑可重试性:pre-gate 放在 authority receipt 写盘之前,同名 session 直接重派不会撞"receipt already exists"。

回归:scripts/test-spawn-worker-orca.sh 末尾 E2E(真实入口 + fake Orca CLI 真建 -2 分支):mismatch 断言 exit 2 + 调用日志无 terminal create/run-create/task-create/worker-start + 无 Session Context 落盘 + worktree 保留;同名成功路径断言 exit 0 + worker-start 正常注入 + METADATA supervised 合同完整。

关联:SKILL §3 不变量与启动门禁(isolation pre-gate 硬约束条)、§4.4(worker-start 唯一任务注入器)、G38(branch 名规范化的另一形态:spec 写斜杠)。

4. 纠偏、权限与验收

  • worker偏题时先把具名问题、证据与范围交回原任务,在允许预算内纠偏;PM接管需符合现有例外,不因难审直接代写业务。
  • 多维任务逐项定义验收,独立审查覆盖实际约束;按文件域/依赖拆解,参考 12任务分组 与 18验收。不靠增加worker数量代替任务定义。
  • provider并发按当前配额、lease和内存合同,不将历史“三四个”的经验变成所有backend的上限或豁免。
  • 授权回执、launch和能力身份由正式入口绑定;修改旁路配置不能追认原worker权限。恢复读取 14,不能手改receipt或重置Task身份。
  • STATUS/检查点帮助巡检,完成与释放按实际模式的权威来源验收;读取 03 checkpoint 与 23。

G41. Reviewer证据预算

先看固定产物/head、diff与受影响合同;同一证据不反复全文重读。验证失败按事实分类,有理由才复跑,保留首次失败。预算耗尽写明确剩余和下一动作,不变成放宽验收,也不自动重派同题;具体规则以 18 和原任务预算为准。

5. 历史记录与维护

旧G编号中的项目复盘、未支持CLI、价格/速度比较、通用Git/测试教材不再作为运行正文。维护任务保存原文归档与章节去向;当前规则已在权威指南存在时只保留路由,不复制第二套。

新增排障项至少包含可观察症状、最小事实、合法下一步和权威入口。一次事故的时间、提交、测试计数、失败过程与待实现修复写回原TASK;真实取舍写DECISIONS。只把经过核实且可重复使用的操作知识放入本页。

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert18d3 checks · Risk HIGH
  • Gen Agent Trust Hub18d

    This skill is a highly sophisticated multi-agent orchestration framework designed to manage and parallelize local AI worker tasks using tools like Orca, tmux, and SSH. While it incorporates an extensive array of security features—including automated installation guards, file write scope guards, and a structured authority receipt system—it fundamentally relies on broad system permissions. It performs extensive command execution, dynamic script loading, and remote execution on network nodes via SSH. Users should review the configuration and security policies (e.g., config/harness-backend-policy.json) to ensure they align with their environment's security requirements.

  • Socket18d

    2 alerts: gptAnomaly

  • Snyk18d

    Risk: LOW · No issues

Signed by skilld at 5fb69a0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
Other metadata
metadata
{
  "version": "3.1.1",
  "homepage": "https://github.com/cat-xierluo/legal-skills",
  "author": "杨卫薪律师(微信ywxlaw)"
}

README badge

README badge for cat-xierluo/legal-skills/multi-agent-orca