用途
oil-delegate 用于把一项边界清楚的单次任务交给外部 AI 编程 CLI 执行,例如代码分析、评审、诊断或实现。调用方(当前 Agent)负责定义范围、控制权限并做最终验收,外部 Agent 的自报结果不能替代工作区检查与真实测试。
主要能力
- 多 runner 支持:可委托给 Claude Code(cc)、WorkBuddy(wb)、Antigravity(agy)、Codex、OpenCode、DeepSeek Harness(dsh)、Grok Build(grok)或 Kimi 等已接入的 CLI。
- 统一委托契约:提示词需覆盖目标与边界、完成标准、入口文件线索、真实验证命令和最终报告要求。
- 模式选择:支持新任务、续接原会话(
--session)、按角色委托(review、critique、diagnose、implement)以及配置与诊断模式。 - 权限控制:默认使用 write 最高权限;用户明确要求只读时可使用
--mode read,读类角色自动只读;Kimi 非交互模式自带 auto 权限,不能保证只读,因此拒绝 read。 - 会话管理:支持按标题查找已有会话、导出会话为 Markdown 交接文件,并可将会话续接到新 CLI 会话。
- 结构化输出:脚本输出 status、session_id、runner、output_path、result_path、events_path 和 elapsed;使用
--json时 stdout 只输出一个带 contract_version 的 JSON 对象。 - 失败恢复:非零退出、协议错误或超时后不盲目重试,需先修正配置、登录状态、任务范围或权限。
使用方式
核心命令为 DELEGATE run,其中 DELEGATE 是 python3 "$SKILL_DIR"/scripts/delegate.py 的简写。典型调用:
DELEGATE run --runner <名称> \
--workspace "<项目绝对路径>" \
--file "<相对入口文件>" \
--prompt "<目标、边界、完成标准与真实验证命令>"
首次使用若省略 --runner 且未完成 onboarding,run 会返回 NEEDS_ONBOARDING,并自动静默扫描已安装的 runner。用户确认启用池与默认项后,通过以下命令保存:
DELEGATE onboard --enable <claude,workbuddy,antigravity,codex,opencode,dsh,grok,kimi> --default-runner <runner|ask>
查看配置或设置二进路径:
DELEGATE config
DELEGATE config --set-bin <runner>=<可执行文件绝对路径>
按角色委托示例:
DELEGATE run --role review --workspace "<项目绝对路径>" --prompt "<审查范围与要求>"
续接原会话:
DELEGATE run --runner <原 runner> \
--workspace "<原工作区>" \
--mode <read|write> \
--session <session_id> \
--prompt "<本轮新发现、追问或修正要求>"
查找与导出会话:
DELEGATE sessions --query "标题关键词" --limit 20 --json
DELEGATE sessions export --runner <名称> --session-id <ID> --out "<交接文件.md>" --json
启动前预览参数可追加 --dry-run,预览不会启动外部 Agent。
适用场景
- 将独立代码审查或方案挑刺交给只读的外部 Agent。
- 在动手实现前进行双模型会诊(diagnose 角色可保存两个不同选择,用
--role-slot 1和--role-slot 2分别调用)。 - 按已确认方案委托实现任务。
- 对同一 CLI 的上一轮结果进行追问或返工。
- 在其他 Skill(如 oil-plan、oil-code-review、oil-govern)中按角色委托审查、会诊或实现。
限制
- 每次只委托一个边界清楚的任务,不自动切换 runner。
- 不传递或保存密钥,不把密钥写入提示词;沿用各 CLI 自身的模型、provider 与登录。
- 跨 runner 不能复用 session ID。
- Kimi 不能保证只读,不能配给读类角色;Antigravity IDE 桌面来源会话不能由 agy 续接。
- 安装与登录必须另行获得用户授权;缺少 CLI 或登录时应停止并给出对应官方入口。
- 会话导出目前仅支持 Antigravity IDE/CLI 与 Claude(含桌面来源),其他 runner 返回 ERROR。
- 输出父目录必须存在;已有文件默认报错,需显式加
--force才覆盖,禁止写入 CLI 数据目录。
资源
references/runners.md:首次配置、显式只读、排查特定 CLI 或维护适配器时阅读。scripts/delegate.py:扫描、配置、调用、解析与运行产物的确定性工具。tests/test_delegate.py:八种 Runner 的回归测试,仅在开发或整改时阅读。