Headless 模式
使用 auto-coder.run 在非交互环境中运行 Auto-Coder，适合脚本化调用、CI/CD 和 Claw 等自动化场景。
Headless 模式（auto-coder.run）
当你需要在非交互环境中运行 Auto-Coder —— 例如 Claw、CI/CD 流水线、批处理脚本、cron 定时任务 —— 交互式终端并不合适。auto-coder.run 是专为此类场景提供的 Headless CLI 入口：一次调用、读取 prompt、执行任务、输出结果，然后退出。
auto-coder.run和auto-coder.cli是同一入口的两个命令别名，任选其一即可。
与交互模式的区别
| 对比项 | auto-coder.chat（交互） | auto-coder.run（Headless） |
|---|---|---|
| 运行方式 | 长驻终端会话 | 一次性命令调用 |
| 输入 | 交互式命令（/auto、/async ...） | 命令行参数、文件、stdin |
| 输出 | 富文本终端渲染 | 纯文本 / JSON / 流式 JSON |
| 适用场景 | 开发中的日常协作 | 脚本、自动化、CI/CD、Agent 平台 |
| 会话 | 内置 /new、/list 管理 | 通过 --continue / --resume <id> 衔接 |
最小可用示例
直接把需求作为参数传入，一次性执行：
auto-coder.run "帮我给 src/utils.ts 里的所有函数加上 JSDoc 注释"
Auto-Coder 会自动选择第一个已配置 API Key 的模型，执行任务并把最终结果打印到 stdout。
也可以通过管道传入 prompt：
echo "修复 README 中的所有错别字" | auto-coder.run
推荐用法：prompt 文件 + 流式 JSON
在自动化场景中，推荐使用下面这个组合：
auto-coder.run \
--from-prompt-file task.md \
--verbose \
--output-format stream-json
三个关键参数的作用：
--from-prompt-file task.md：从文件读取 prompt。Prompt 可以纳入版本管理、模板化、复用，也方便长篇任务描述。--verbose：输出完整的执行过程（LLM 思考、工具调用、工具结果），便于排查问题和审计。--output-format stream-json：以流式 JSON 输出每个事件，便于上游程序实时解析与进度跟踪。
三种输出格式
| 格式 | 适用场景 |
|---|---|
text（默认） | 命令行肉眼查看，仅输出最终结果 |
json | 一次性返回完整事件列表，适合脚本批处理 |
stream-json | 每个事件独立一行 JSON，适合实时流式消费 |
auto-coder.run "<your prompt>" --output-format json
auto-coder.run "<your prompt>" --output-format stream-json
常见事件类型包括 start、llm_thinking、llm_output、tool_call、tool_result、completion、error、token_usage、commit、pull_request 等。
常用选项
输入相关
| 选项 | 说明 |
|---|---|
<prompt> | 位置参数，直接传入需求文本 |
--from-prompt-file <file> | 从文件读取 prompt 内容 |
--input-format text|json|stream-json | 指定 stdin 输入格式，默认 text |
优先级：位置参数 > --from-prompt-file > stdin。
输出相关
| 选项 | 说明 |
|---|---|
--output-format text|json|stream-json | 输出格式，默认 text |
-v, --verbose | 输出详细执行过程 |
会话复用
Headless 调用默认是独立的一次性执行。如果需要在多次调用之间保持上下文：
# 继续最近一次会话
auto-coder.run -c "再优化一下刚才那段代码"
# 恢复指定会话
auto-coder.run -r <SESSION_ID> "接着上次的任务"
| 选项 | 说明 |
|---|---|
-c, --continue | 继续最近一次会话 |
-r, --resume <SESSION_ID> | 恢复指定会话 |
--continue和--resume互斥，同时传入会报错。
模型与行为
| 选项 | 说明 |
|---|---|
--model <name> | 指定模型名（如 v3_chat）。未指定时自动选择第一个配置了 API Key 的模型 |
--max-turns <n> | 最大对话轮数，默认 10000 |
--system-prompt <text> | 直接指定系统提示内容 |
--system-prompt-path <file> | 从文件读取系统提示（与 --system-prompt 互斥） |
--permission-mode manual|acceptEdits | 权限模式。acceptEdits 会自动接受编辑操作，适合完全无人值守 |
--allowed-tools tool1 tool2 ... | 允许使用的工具白名单 |
--include-rules | 在上下文中包含项目规则文件（.autocoderrules/） |
--include-agent-definitions | 包含 agent 定义 |
--include-skills | 包含 skills |
--include-libs lib1,lib2 | 自动引入指定的 LLM friendly package（逗号分隔） |
--pr | 任务完成后自动创建 Pull Request |
--loop <n> | 循环执行 n 次，默认 1 |
--loop-keep-conversation | 循环时保持对话连续性 |
--loop-additional-prompt <text> | 循环时的附加提示 |
--workflow <name|file> | 执行指定的 workflow |
无人值守提示：
--permission-mode acceptEdits会自动接受代码编辑，请谨慎使用，并配合--pr或独立 git 分支使用，便于审查。
配置管理
除了直接执行任务，auto-coder.run 还内置了配置子命令：
# 配置单个参数
auto-coder.run config model=v3_chat
# 一次配置多个参数
auto-coder.run config model=v3_chat max_turns=10
# 查看帮助
auto-coder.run config --help
配置会持久化到项目，后续调用可省略 --model 等参数。
Memory（记忆调度器）
auto-coder.run 还提供 memory 子命令来控制项目的记忆任务调度：
# 启动记忆调度器（默认每 300 秒执行一次）
auto-coder.run memory start 600
# 查看调度器状态
auto-coder.run memory status
# 列出所有记忆任务
auto-coder.run memory list
# 手动执行指定任务
auto-coder.run memory run <task_name>
# 停止调度器
auto-coder.run memory stop
并行执行：--async
对于大型任务，可以把一份 Markdown 文档按标题或分隔符自动切分为多个独立子任务，并行在独立的 git worktree 中执行。
最简用法：
cat tasks.md | auto-coder.run --async
分割模式
| 选项 | 说明 |
|---|---|
--split h1|h2|h3|any|delimiter | 分割模式，默认 h1（按一级标题） |
--delimiter <str> | 自定义分隔符（--split delimiter 时使用），默认 === |
--min-level <n> | 最小标题级别（--split any 时使用） |
--max-level <n> | 最大标题级别（--split any 时使用） |
示例：
# 按二级标题分割
cat tasks.md | auto-coder.run --async --split h2
# 按 1-3 级任意标题分割
cat tasks.md | auto-coder.run --async --split any --min-level 1 --max-level 3
# 按自定义分隔符分割
cat tasks.md | auto-coder.run --async --split delimiter --delimiter "==="
worktree 与后台运行
| 选项 | 说明 |
|---|---|
--workdir <path> | 异步工作目录，默认 ~/.auto-coder/async_agent |
--from <branch> | worktree 基础分支（为空时自动检测） |
--worktree-name <name> | 指定 worktree 名称（为空时自动生成） |
--task-prefix <prefix> | 任务名称前缀，便于组织相关任务 |
--bg | 后台运行模式，生成日志文件后立即返回 |
--pr | 每个子任务完成后自动创建 PR |
示例：
# 后台运行 + 自动创建 PR
cat tasks.md | auto-coder.run --async --bg --pr --task-prefix "feature_auth"
Headless 异步模式的产物默认放在
~/.auto-coder/async_agent/tasks/下，元数据在~/.auto-coder/async_agent/meta/。详细概念请参考异步模式。
典型场景示例
脚本化调用
#!/usr/bin/env bash
set -euo pipefail
auto-coder.run \
--from-prompt-file tasks/refactor-auth.md \
--model v3_chat \
--permission-mode acceptEdits \
--include-rules \
--output-format stream-json \
--verbose
CI/CD 流水线
在 CI 中自动根据 issue 描述生成代码修改并开 PR：
auto-coder.run \
--from-prompt-file .github/prompts/fix-from-issue.md \
--model v3_chat \
--permission-mode acceptEdits \
--pr
Claw / Agent 平台集成
对上游 Agent 平台，推荐使用 stream-json 实时读取事件：
auto-coder.run \
--from-prompt-file /workspace/task.md \
--verbose \
--output-format stream-json
上游只需逐行解析 JSON，按 event_type 分发处理即可获得 LLM 思考、工具调用、最终结果等完整执行流。
批量处理一份计划文档
把一份包含多个小节的 plan.md 分发到多个并行 worktree 中执行：
cat plan.md | auto-coder.run \
--async \
--split h2 \
--model v3_chat \
--permission-mode acceptEdits \
--bg \
--pr \
--task-prefix "plan_q2"
退出码
| 退出码 | 含义 |
|---|---|
0 | 执行成功 |
1 | 执行失败（参数错误、运行时异常等） |
失败时会把错误信息打印到 stderr，--verbose 下还会附带完整堆栈，方便排查。