orchestration-native-invokeSkill orchestration-native-invoke

---

name: orchestration-native-invoke description: “通过原生任务代理（Claude, Codex, Gemini, Cursor）调用外部AI CLIs。多供应商编排的主要模式，具有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工具将被"自动拒绝（提示不可用）"。

需要在.claud/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. [ ] 选择代理(S)：确定要使用的代理
3. [ ] 阅读：从../spawn/agent/cookbook/为每个选定的代理阅读食谱
4. [ ] 运行帮助：执行<cli> --help以验证可用的标志
5. [ ] 构建命令：根据食谱构建非交互式命令
6. [ ] 检查点：确认遵循了食谱说明
7. [ ] 通过任务工具执行，run_in_background: true
8. [ ] 通过TaskOutput收集结果
9. [ ] 在认证失败时：触发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为true时，始终在提示中包含：

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

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

当代理需要写入访问权限时，使用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’为true
• 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>"

• 认证失败模式：“Please log in”, “authentication required”
• 登录命令：codex login

Gemini (Google)

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

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

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

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

• 认证失败模式：“Please authenticate”, “run gemini auth”
• 登录命令：gemini auth login

Cursor

• IF：用户请求Cursor且’ENABLED_CURSOR’为true
• 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>"

• 认证失败模式：“Please log in”, 需要浏览器弹窗
• 登录命令：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/交互式	NO	YES
认证处理	报告失败	交互式登录
恢复能力	YES（代理ID）	NO

使用原生时：

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

使用Fork-Terminal时：

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