Soia Dev Agent CLI Dispatch

soia-dev-agent-cli-dispatch

把编码、审查、分析、研究、文档或内容任务交给外部 AI Agent CLI 进程，并对工作目录、权限、实际模型、用量、成本和结果质量做统一约束。它不调度宿主内置子代理，也不替代普通的一次性 shell 命令。

客户可读说明

这个技能可以做什么

本技能不会把“进程退出码为 0”直接当成模型或任务质量已验证，也不会在没有证据时开放新的自动路由。

客户如何使用

客户至少说明：

1. 要完成的任务和验收标准；
2. 目标项目或工作目录；
3. 指定执行器/模型/推理档，或允许自动选择；
4. 是否允许修改文件、联网、创建 worktree、提交或执行其他高影响动作。

示例请求：

把这个小范围修复派给 Pi，允许改当前项目，不允许提交；运行相关测试并回报实际模型和 Token。

依赖与安装

• 运行依赖：Python 3，以及本次选择的外部 AI CLI。缺少目标 CLI 时停止，不静默换成另一个执行器。
• 可选依赖：soia-meta-sync-skills，仅用于把已安装技能同步到客户明确选择的其他宿主。
• 各 CLI 的认证、模型和套餐由其官方登录态或 provider 配置管理；本技能不代管凭据。

默认按项目、单技能、单个明确指定的 Agent 安装。在已选项目目录运行，将 <explicit-agent> 替换为客户选择的 Agent ID：

npx skills add soia-team/soia-open-dev-skills -a "<explicit-agent>" -s soia-dev-agent-cli-dispatch -y

只有客户显式选择全局范围时才加 -g；只有显式选择全部 Agent 时才用 -a '*'。项目、宿主、技能和影响范围已明确获批时不重复确认；缺少关键选择时先问，不因发现技能缺失自动安装。

只有客户明确选择整个 dev 插件及其安装范围时，才使用对应插件安装流程；以下为 Claude Code 命令示例，执行前按已批准的范围设置安装选项：

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-dev@soia

同一宿主、同一使用范围内不要同时维护插件副本和 skills 目录副本，以免同名技能漂移。完整安装说明以元仓 README 安装入口为准。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

配置文件

本技能目录中有两类 YAML，职责不同：

可选私有配置位置与覆盖变量：

~/.config/soia-skills/soia-dev-agent-cli-dispatch/config.yml
SOIA_DEV_AGENT_CLI_DISPATCH_CONFIG_FILE=<custom-config-path>

配置优先级：本次 CLI 参数 → 进程环境 → 私有 config.yml → 跨平台默认值。API key、cookie、token、session 不得写进该配置；它们留在 provider 登录态或系统凭据库。

私密信息与中间数据

• prompt：写入 OS 临时目录下按 task-id 隔离的目录；任务结束后清理。除非客户明确要求，不把 prompt 长期保存。
• run manifest：默认写入 <state>/soia-skills/soia-dev-agent-cli-dispatch/runs/<run-id>/manifest.json。
• manifest 只保存脱敏状态、CLI 版本、请求/实际模型、Token、费用、时间和恢复信息；不保存 prompt、响应正文、凭据、账号或私有绝对路径。
• 平台允许时，state 目录使用 0700、manifest 使用 0600。默认最多保留 50 个 run；达到上限时阻断新 run，不自动删除。清理前先让客户查看范围并确认。
• 仓库 checkout 不得作为运行时 config、state、cache 或临时目录。

路径解析：

python3 scripts/resolve_storage.py --json

日志与完成回执

最终回执固定包含：

完成：<本次派发结果>。

调用：
- executor: <外部 AI CLI>
- requested/actual model: <值或 unknown>
- requested/actual reasoning: <值或 unknown>
- status: <passed / failed / blocked / fallback_or_downgrade / actual_model_unverified>

用量与费用：
- input/cache/output/total tokens: <分项值或 unavailable>
- provider-reported / API-equivalent cost: <值、口径或 unavailable>

验证：<实际运行的检查及结果>
状态记录：<泛化 state 位置或“纯 stdout”>
问题与下一步：<阻塞、未验证边界或“无”>

不在客户回执中打印凭据、账号、完整响应正文或本机私有绝对路径。

若 Skill 导致需要确认、暂停或留下已请求但未完成的工作，在暂停说明及最终回执中点名并链接实际读取的具体 SKILL.md（关联规则也给出来源），引用相关原句，解释它为何适用于当前动作，并说明已完成部分与受阻部分。区分规则明确要求与派发者自身推断；仅在已有授权不能覆盖且规则确实适用时请求补充确认，不把历史裁决、建议或其它工作模式的门禁当作新增审批。规则链接使用可公开或客户可访问且不泄露私有目录的形式。

触发与边界

命中以下任一场景时使用：

• 明确要求“派给 Codex / Claude / Pi / DeepCode / agy / 其他外部 AI CLI”；
• 需要多 CLI 分工、外部模型路由、额度预检或统一用量回执；
• 需要把长任务放入独立外部进程并可恢复地跟踪。

不要使用：

• 当前宿主直接完成任务，没有外部 AI 进程；
• 只需普通 shell 命令；
• 任务边界、目标工作目录或验收标准仍不明确。

输入契约

执行前把请求归一化为：

task:
  title: <short-title>
  objective: <observable-result>
  acceptance: [<evidence>]
executor: <agent-id-or-auto>
model: <model-id-or-auto>
reasoning: <level-or-auto>
workdir: <project-path>
permissions:
  file_write: false
  network: false
  worktree: false
  commit: false
  remote_write: false

未明确授权的权限保持 false。显式指定的执行器、模型和推理档优先；但未验证组合必须标记 explicit_unverified，不能包装为自动推荐。 Coordinator、Executor、Verifier、Reviewer、Advisor 的具体模型分工属于调用方项目/用户策略，不由本通用技能写死；派发者必须把该策略作为本次输入，未提供时才按任务复杂度和现有验证证据给出候选。

核心流程

1. 定义任务与证据

写清目标、输入、允许修改范围、禁区和验收命令。任务拆分按可独立验证的边界进行；每个子任务分配唯一 task ID。

先读取目标仓适用的 AGENTS.md、贡献说明和测试约定。目标仓规则优先；不要把本技能自己的历史治理术语或无关文件塞进派发 prompt。

2. 选择执行器

1. 读取 references/supported-agents.yml，确认 dispatch_supported、验证状态和对应 reference。
2. 用户显式指定时按指定值执行，不做静默替换。
3. 用户允许自动路由时，先判定 easy/medium/hard，再运行：

python3 scripts/route_model.py --executor <agent-id> --complexity <easy|medium|hard>

4. 没有 verified candidate 时停止；不得从 pending_benchmark 或 command_help_verified 条目自动选模。
5. 确定执行器后只加载其 reference；需要路由判据时再加载 references/executor-routing.md。

3. 执行前预检

• 运行 command -v <cli> 和 <cli> --version，记录实际版本。
• 使用官方只读状态检查认证/套餐；如果检查本身会调用付费模型，先取得客户确认。
• 检查 workdir 是否存在、是否是凭据/配置目录、是否有未提交改动以及是否与其他任务重叠。
• 不可服务、认证阻断、额度不足或目录不安全时停止并给出明确状态。
• Antigravity 消费者通道与 Gemini 企业/API Key/Vertex 通道必须分开，禁止复制认证状态或静默 alias。

4. 建立隔离与权限门

• 每个写任务使用独立 workdir；多任务不得同时写同一文件。
• 创建 git worktree 前展示目标路径、分支和用途，并等待客户明确批准；已在当前任务书中明确批准的目标不重复确认。新增、移动、删除或改变 Worktree/分支/目标路径仍须单独批准。
• “覆盖”指替换未知内容、他人改动或授权范围外目标，不包括已授权文件集内的常规补丁编辑。
• 删除、覆盖、提交、push、发布、发送、授权变更及其他远端写入必须单独获得当前任务授权。
• 工作区已有未知改动时不提交、不清理、不覆盖；把冲突范围回报给客户。

5. 安全传递 prompt

prompt 必须先写入按 task-id 隔离的 UTF-8 临时文件。不要把不可信正文直接拼进 shell；优先 stdin 或执行器原生文件参数。具体命令、参数终止符和结构化输出方式以选中执行器的 reference 为准。

prompt 只包含：任务目标、必要上下文、目标文件/范围、权限边界、验收命令和回执要求。排除无关仓库、私有路径、凭据和其他任务上下文。

6. 派发与监控

• 简短任务前台执行；长任务使用可观察的后台方式并定期检查退出状态、日志摘要和资源信号。
• 多 case 使用 scripts/run_matrix.py；每个 case 完成后原子更新 manifest。
• 失败后先分类原因再决定是否重试；同一命令、同一假设不得无变化重复运行。
• 外部 Agent 自报“完成”只是待验证输入，不能直接作为主控结论。

7. 验证与收口

1. 比对 requested_model 与结构化或可信回显中的 actual_model。
2. 缺少实际模型证据时写 actual_model_unverified；不以请求值填充实际值。
3. 分开记录 input、cache read/write、output 和 total Token；缺少分项时保持 unavailable。
4. provider 报告费用与 API 等价估算分开，订阅套餐不得伪装成真实按 Token 扣费。
5. 在目标 workdir 运行验收命令，并检查真实 diff/产物；退出码与模型回显不能替代任务质量验证。
6. 检查同类问题、未授权改动和残余风险，再输出完成回执。

统一字段、状态机、恢复与 Model Integrity Gate 见 references/dispatch-contract.md。

证据与状态规则

• manifest 中的 passed：执行器成功且模型证据满足该执行器门禁；它不代表任务产物质量已验收。
• 客户回执中的“完成”：除上述调用状态外，还必须由主控独立验证任务产物。
• fallback_or_downgrade：实际模型与请求不符。
• actual_model_unverified：任务可能有输出，但缺少可信实际模型证据。
• blocked_*：认证、额度、权限或付费确认未满足，未执行对应调用。
• partial_coverage：只有部分模型/档位或聚合报告，不能声称全矩阵完成。

要声称“全模型 × 全推理档已验证”，必须保留发现快照、完整 case 清单、逐 case manifest、模型回显和聚合报告。

按需资源

加载原则：主文件 → 所选执行器 reference，最多一跳；不要一次性加载全部 references。

验证

修改本技能后至少运行：

python3 scripts/resolve_storage.py --selftest
python3 scripts/validate_supported_agents.py --selftest
python3 scripts/catalog_lib.py --selftest
python3 scripts/estimate_cost.py --selftest
python3 scripts/route_model.py --selftest
python3 scripts/run_claude_prompt.py --selftest
python3 scripts/run_matrix.py --selftest
python3 scripts/probe_claude_models.py --selftest

复杂行为还要运行一个脱敏的真实前向实例，并核对产物或 manifest 内容，不能只核对退出码。