multica-squad-load-balancer

Multica 小队负载均衡

• Version: 1.0.0
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/better-agent-skills

队长和成员安装同一份 Skill。使用已有 Multica CLI 登录及运行环境身份，仅依赖 python3 标准库；实际派单需要 Linux/macOS 等支持 fcntl 的 POSIX 环境。无额外数据库或业务系统依赖，不需要共享 Token。项目负责人应为 Agent，且在同一工作区领导唯一未归档小队；Issue 应指派给该小队。直接指派个人的 Issue 按原业务执行，不强行转换。

每次处理小队 Issue 时先读取完整 Issue、触发评论和自己的 task-run。通过 is_leader_task、项目负责人和实时小队名单判断角色；不得凭 Agent 名称判断。命令中的脚本路径相对于本 Skill 目录，应使用安装位置的真实绝对路径，不复制脚本到业务项目。

队长

1. 首次派单运行：

   python3 <skill目录>/scripts/squad_balance.py plan --issue-id <当前Issue UUID> --task-run-id <自身 MULTICA_TASK_ID>
   python3 <skill目录>/scripts/squad_balance.py dispatch --issue-id <当前Issue UUID> --task-run-id <自身 MULTICA_TASK_ID>
   

   plan 只读，dispatch 在真实队长运行环境中重算并派单。CLI 的 --profile、--server-url、--workspace-id 参数须放在子命令前；通常沿用运行环境默认配置，禁止固定为创建者的 profile 或服务器。

2. 调度根据当前项目负责人解析小队，排除队长、非 Agent、归档/不可用/离线/达到并发上限的成员，按 queued/dispatched/prepared/running/claimed/starting 的任务数升序选人；并列按 Agent UUID 升序。跨项目任务也计入该 Agent 的负载。working 是正常可接单状态，是否满载由活跃任务数与并发上限判断。

3. 业务需要特定技能或角色时，从原 Issue 已授权要求确定条件。用重复参数 --required-skill-id <工作区 Skill UUID>、--member-role <小队角色>，或 Issue metadata 中的 multica_load_balance: {"requiredSkillIds": [...], "memberRole": "..."}。两条命令使用相同条件；成员异质时必须先限制能力再比较负载，不凭空替换业务 Skill。

4. dispatched：脚本已经在原 Issue 发出真实 mention，保存决策标记并记 squad activity；不要再手工发一次。保持小队 assignee，不创建子 Issue，队长不代做业务。

5. no_action：已有成员 run/派单/终态时不重派。读实际结果，按原业务流程处理。failed：说明离线、容量、身份或不确定结果的真实卡点；不自行换人重试。脚本写入失败后先读评论和 runs 对账，不能直接删除私有意图文件重跑。

6. 再次唤醒先辨别诉求。致谢、成员已交付、等待人工或系统自动推进时不派单。用户明确要求续跑或重新执行，先核对上一执行、副作用及未完成处；本版不自动重开已派 Issue，应由项目原有受控续跑机制处理。

成员

1. 只执行原 Issue 已授权任务，不递归调度。优先从运行环境取 MULTICA_TASK_ID、MULTICA_AGENT_ID，缺失时先读取当前上下文并唯一核验，不能挑选他人的 run。

2. 开始业务前运行：

   python3 <skill目录>/scripts/squad_balance.py verify-worker \
     --issue-id <当前Issue UUID> --task-run-id <自身run UUID> --agent-id <自身Agent UUID> \
     --binding-file <业务目录中的私有执行绑定.json>