orchestration-native-invokeSkill orchestration-native-invoke

---

name: orchestration-native-invoke description: “通过原生任务代理调用外部AI CLIs（Claude, Codex, Gemini, Cursor）。多供应商编排的主要模式，具有fork-terminal回退认证。” type: documentation

目的

注意：这是一个文档/指南技能。它提供了使用Claude Code的原生任务代理调用 外部AI CLIs的指令。阅读这个技能以学习模式，然后手动使用任务工具与 subagent_type="general-purpose"。

通过Claude Code的原生任务代理调用外部AI编码CLIs。这是多供应商编排的主要模式，具有fork-terminal作为认证失败的回退。

变量

变量	默认	描述
DEFAULT_AGENT	gemini	当未明确指定时使用的代理
ENABLED_CODEX	true	通过原生代理启用OpenAI Codex
ENABLED_GEMINI	true	通过原生代理启用Google Gemini
ENABLED_CURSOR	true	通过原生代理启用Cursor代理
RUN_IN_BACKGROUND	true	异步运行代理
PARALLEL_EXECUTION	true	并行启动多个代理
AUTO_RETRY_ON_AUTH	true	在认证失败时自动使用fork-terminal重试
READ_ONLY_MODE	true	防止代理修改代码库
CLEANUP_AGENT_FILES	true	清理代理写入仓库的任何文件

前提条件

子代理的CLI权限

原生任务代理（子代理）需要预先批准的权限来执行CLI命令。 没有这些权限，Bash工具将被"自动拒绝（提示不可用）"。

需要在 .claude/settings.json 中：

{
  "permissions": {
    "allow": [
      "Bash(codex:*)",
      "Bash(gemini:*)",
      "Bash(cursor-agent:*)"
    ]
  }
}

设置：运行 /ai-dev-kit:setup 自动配置权限。

手动：通过Claude Code设置添加权限或在提示时批准。

回退：如果权限被拒绝，使用fork-terminal进行交互式执行。

指令

MANDATORY - 你必须按照下面的工作流程顺序执行。不要跳过步骤。

代理选择

1. 明确请求：如果用户指定代理，使用该代理
2. 未指定代理：使用DEFAULT_AGENT
3. 检查启用：在继续之前验证ENABLED_*标志为true

阅读食谱

• 根据选定的代理，从 ../spawn/agent/cookbook/ 读取相应的食谱
• 你必须在构建命令之前运行CLI的 --help
• 遵循食谱指示非交互式标志

红旗 - 停止并遵循食谱

如果你即将：

• 在未阅读食谱的情况下启动原生代理
• 未运行 --help 执行CLI命令
• 因为"这很简单"而跳过步骤
• 在非交互式上下文中使用交互式标志

停止 -> 阅读相应的食谱文件 -> 检查 --help -> 然后继续

关键：原生代理不能处理TTY输入。始终使用非交互式标志：

• Codex: codex exec --full-auto
• Cursor: cursor-agent --force -p
• Gemini: 使用位置提示（不使用 -i）

工作流程

MANDATORY CHECKPOINTS - 在继续之前验证每个检查点：

1. [ ] 理解用户的请求
2. [ ] SELECT AGENT(S): 确定要使用的代理
3. [ ] READ: 从 ../spawn/agent/cookbook/ 读取每个选定代理的食谱
4. [ ] RUN HELP: 执行 <cli> --help 以验证可用的标志
5. [ ] CONSTRUCT COMMAND: 根据食谱构建非交互式命令
6. [ ] CHECKPOINT: 确认遵循了食谱指示
7. [ ] 通过任务工具执行，run_in_background: true
8. [ ] 通过TaskOutput收集结果
9. [ ] ON AUTH FAILURE: 触发fork-terminal回退（见认证恢复）

只读与写入模式

默认：READ_ONLY_MODE = true

当READ_ONLY_MODE启用时，代理应仅分析和报告 - 不修改文件。

按供应商的只读标志

供应商	只读命令	写入模式命令
Codex	codex exec --sandbox read-only --full-auto	codex exec --sandbox workspace-write --full-auto
Gemini	gemini --sandbox --yolo	gemini --yolo
Cursor	cursor-agent -p（无 --force）	cursor-agent --force -p

提示只读

当READ_ONLY_MODE为真时，始终在提示中包含：

"不要修改任何文件。只分析和报告结果。
如果通常会写入文件，请改为在响应中返回内容。"

工作树隔离（写入模式推荐）

当代理需要写入访问时，使用git工作树进行真正的隔离：

# 为代理工作创建隔离的工作树
git worktree add /tmp/agent-workspace-<id> -b agent/<provider>-<task>

# 在工作树中运行代理
cd /tmp/agent-workspace-<id>
<agent-command>

# 审查更改
git diff

# 如果批准，合并回
git checkout main
git merge agent/<provider>-<task>

# 清理
git worktree remove /tmp/agent-workspace-<id>
git branch -d agent/<provider>-<task>

工作树隔离的好处

• 完全写入访问：代理可以自由地进行任何更改
• 选择性合并：仅合并批准的更改
• 无需清理：丢弃工作树以拒绝更改
• 并行代理：多个工作树用于并行供应商
• 分支历史记录：更改在git中跟踪

何时使用工作树

场景	方法
分析/审查仅	READ_ONLY_MODE + CLI标志
单文件编辑	写入模式与清理
多文件重构	工作树隔离
实验性更改	工作树（易于丢弃）
并行代理工作	每个代理单独的工作树

清理协议

当CLEANUP_AGENT_FILES为true（默认）且不使用工作树时：

1. 检查工作目录中的新文件
2. 通过在删除前读取文件来保留有价值的内容
3. 删除代理创建的文件（例如，*_REVIEW_OUTPUT.md，*_analysis.json）
4. 记录清理操作以进行审计跟踪

# 清理模式
cleanup_patterns = [
    "*_REVIEW_OUTPUT.md",
    "*_analysis.json",
    "*_findings.md",
    "agent_output_*.txt"
]

食谱

Codex (OpenAI)

• IF: 用户请求Codex/OpenAI且’ENABLED_CODEX’为真
• THEN: 读取 ../spawn/agent/cookbook/codex-cli.md
• 原生命令模式（只读）：

codex exec --sandbox read-only --full-auto --model gpt-5.2-codex "<prompt>"

• 原生命令模式（写入模式）：

codex exec --sandbox workspace-write --full-auto --model gpt-5.2-codex "<prompt>"

• 认证失败模式：“请登录”，“需要认证”
• 登录命令：codex login

Gemini (Google)

• IF: 用户请求Gemini/Google且’ENABLED_GEMINI’为真
• THEN: 读取 ../spawn/agent/cookbook/gemini-cli.md
• 原生命令模式（只读）：

gemini --model gemini-3-pro --sandbox --yolo "<prompt>"

• 原生命令模式（写入模式）：

gemini --model gemini-3-pro --yolo "<prompt>"

• 认证失败模式：“请认证”，“运行 gemini auth”
• 登录命令：gemini auth login

Cursor

• IF: 用户请求Cursor且’ENABLED_CURSOR’为真
• THEN: 读取 ../spawn/agent/cookbook/cursor-cli.md
• 原生命令模式（只读 - 提示批准）：

cursor-agent --model claude-sonnet-4.5 -p "<prompt>"

• 原生命令模式（写入模式 - 自动批准）：

cursor-agent --model claude-sonnet-4.5 --force -p "<prompt>"

• 认证失败模式：“请登录”，需要浏览器弹出窗口
• 登录命令：cursor-agent login

认证恢复

当原生代理报告认证失败时：

1. 检测：检查输出中的认证失败模式
2. 登录分支：使用fork-terminal和登录命令
3. 等待：监控终端关闭
4. 重试：重新启动原生代理

# 认证恢复流程
def handle_auth_failure(provider: str, original_prompt: str):
    login_commands = {
        "codex": "codex login",
        "gemini": "gemini auth login",
        "cursor": "cursor-agent login"
    }

    # Fork terminal for interactive login
    fork_terminal(login_commands[provider], wait_for_close=True)

    # After terminal closes, retry native invocation
    return invoke_native(provider, original_prompt)

并行调用

要并行调用多个代理，使用单个消息中的多个任务工具调用：

# 并行启动Gemini, Codex和Cursor
Task(subagent_type="general-purpose", run_in_background=true, prompt="gemini ...")
Task(subagent_type="general-purpose", run_in_background=true, prompt="codex ...")
Task(subagent_type="general-purpose", run_in_background=true, prompt="cursor ...")

收集结果：

TaskOutput(task_id="...", block=false)  # 检查进度
TaskOutput(task_id="...", block=true)   # 等待完成

结果收集

原生代理通过TaskOutput工具返回结果：

参数	值	行为
block=false	检查状态	非阻塞进度检查
block=true	等待完成	阻塞直到代理完成
timeout	毫秒	最大等待时间超时之前

示例收集模式

# 检查进度（非阻塞）
TaskOutput(task_id="abc123", block=false)

# 等待完成（阻塞）
TaskOutput(task_id="abc123", block=true, timeout=120000)

比较：原生与Fork-Terminal

方面	原生任务代理	Fork-Terminal
并行执行	优秀	良好
结果收集	TaskOutput（干净）	文件解析
TTY/交互式	否	是
认证处理	报告失败	交互式登录
恢复能力	是（代理ID）	否

使用原生 当：

• 需要自动化多供应商任务
• 需要并行执行
• 需要干净地收集结果

使用Fork-Terminal 当：

• 需要交互模式
• 需要基于浏览器的认证
• 需要实时流式输出