iCode Agent · 指南 · 自动化

在脚本和 CI 中自动化。

iCode Agent 是终端智能体,但不需要终端。你在交互模式下运行的任务,同样可以用 -p 以无头模式运行,运行时的完整事件流以 JSON 形式提供。

打印模式

运行一个任务,打印最终回复,然后退出:

icode-agent -p "run the tests and report failures" /path/to/project

工作区可以作为参数传入,或用 --cwd <dir> 设置。打印模式在运行得到最终答案时以 0 退出,否则以 1 退出——因此你可以在脚本中据此分支。

JSON 事件模式

添加 --mode json,将每个运行事件作为 JSON 行流式输出,最后再输出一行最终结果。这是供工具使用的模式:你以数据而非终端输出的形式获得智能体的进度。

icode-agent --mode json -p "find all TODO comments" /path/to/project

事件流包含如下事件:

  • run_start——任务和模型身份。
  • iteration_start、assistant_delta——每一步内的进度。
  • tool_call 和 tool_result——智能体使用的每个工具及其返回内容。
  • model_response——本次调用的 token 用量(当提供商报告时)。
  • compaction、projection_reduced——上下文管理事件,因此成本行为在事件流中可见。
  • run_end——本次运行的摘要。

每一行都是一个完整的 JSON 对象,因此标准工具——jq、日志管道、CI 步骤——可以直接使用它。

继续会话

工作区会话会自动持久化。继续最近的一个,或按 id 恢复指定会话:

# continue the most recent session in this workspace
icode-agent -c -p "now fix the issue you found" /path/to/project

# resume a specific session
icode-agent --resume <id> -p "add tests for that fix" /path/to/project

CI 示例

一个要求智能体让测试套件通过的步骤;当它返回非零值时,该步骤会使作业失败:

icode-agent -p "run the full test suite and fix any failures" "$PWD"
status=$?
if [ "$status" -ne 0 ]; then
  echo "iCode Agent did not reach a passing state." >&2
  exit 1
fi

项目指令与设置

无头运行读取的配置与交互式运行相同:

  • 仓库根目录中的 AGENTS.md(或 CLAUDE.md)会加载到系统提示词中,因此 CI 运行会遵循你项目的规则。
  • 全局设置位于 ~/.icode-agent/settings.json,可在每个项目中通过 .icode-agent/settings.json 覆盖。
  • 提示词模板(.icode-agent/prompts/*.md)和技能(.icode-agent/skills/<name>/SKILL.md)会自动加载。

在没有 ~/.icode-agent 的 CI 运行器上,将 ICODE_AGENT_CONFIG_DIR 指向准备好的目录,以便模型配置可用。