通过 Headless 集成 IaC Code

Headless 集成通过一次性子进程向 IaC Code 提交任务，并从标准输出和退出码取得结果。它适合 CI/CD、定时任务、Shell 和不需要持续会话的后端作业。本文重点说明调用方与 IaC Code 之间的进程契约；完整命令用法由 Headless 使用文档维护。

前提条件

• 已完成安装和配置 IaC Code。

• 已在相同运行用户和环境中验证模型及阿里云身份可用。

• 调用方可以指定工作目录、分离标准输出和标准错误，并读取进程退出码。

最小接入

在项目工作目录中启动一次查询：

iac-code \
  --prompt "查询 cn-hangzhou 的 ROS 资源栈，汇总异常状态，不要执行任何写操作" \
  --output-format json \
  --max-turns 20 \
  --permission-mode dont_ask

预期结果：标准输出返回一个最终 JSON 结果，任务结束后进程退出。诊断信息写入标准错误。

调用方职责

输入格式、权限参数和可直接使用的 Shell 脚本请参见 使用 Headless 非交互模式，本页不重复维护。

集成建议

• 每个并发任务使用独立进程和明确的工作目录，避免多个任务同时修改同一项目文件。

• 为 --max-turns、进程超时、重试次数和模型成本设置上限。

• 只读检查使用 dont_ask 并在提示词中明确不执行写操作。

• 云资源变更由上游审批系统决定是否放行，并通过 --allowed-tools 精确授权目标 API。

• 如果需要一个长驻子进程交换多轮流式 JSON，使用 GitHub 文档中的 SDK Process Mode； 如果还需要结构化权限请求和会话生命周期，改用 ACP。

常见问题

标准输出不是有效 JSON

确认使用 --output-format json，并让调用方分别捕获 stdout 和 stderr。需要增量事件时改用 stream-json，不要按单个 JSON 文档解析。

自动化任务因为权限被拒绝

dont_ask 会拒绝原本需要询问的操作。检查任务需要的文件或云 API，并在上游完成审批后配置精确授权；不要直接开放全部工具。

需要延续上一次任务

一次性任务可以使用会话恢复参数，但如果调用方需要稳定的多轮会话、事件和中断控制， 优先评估 ACP。智能体之间的远程任务协作使用 A2A。

相关文档

• 集成 IaC Code

• 使用 Headless 非交互模式

• Headless 完整参考

• 命令行参数