第26章 编程化使用无头模式

无头模式 无头模式让 Ante 脱离 TUI（终端用户界面）运行。它会处理提示词、执行任务，然后退出。这种模式非常适合脚本编写、CI/CD 流水线以及自动化工作流。 基本用法 使用 -p 或 --prompt 参数传递提示词： `ante -p "explain what this project does"` 或者使用长参数形式： `ante --prompt "add tests for the auth module"` 标准输入 通过管道从标准输入（stdin）传入内容： `cat src/main.rs | ante -p "review this code for bugs"` 将标准输入与提示词结合使用： `echo "function add(a, b) { return a + b }" | ante -p "add TypeScript types"` 如果同时提供了标准输入和提示词参数，两者会拼接在一起（标准输入在前，提示词在后）。 重定向标准输出（stdout）是专有于无头模式的。如果直接运行 `ante > out.txt` 且未提供提示词，程序会拒绝启动，因为 TUI 需要向 stdout 绘制内容，并在启动时询问终端光标位置。请提供提示词或通过管道传入，以便将输出捕获到文件中。 命令行参考 `ante [OPTIONS] [--prompt ]` FlagDescription-p, --prompt 运行提示词-m, --model 覆盖模型名称--provider 覆盖 API 提供商（如 anthropic, openai, gemini, xai, openrouter, local）--profile 在全局范围内选择现有的 ~/.ante/.settings.json；ANTE_PROFILE 等价，未知名称将回退至 settings.json，内置的裸配置文件会禁用环境特性、skills、MCP 服务器、会话保存及自动记忆--effort 覆盖模型努力级别：min, low, medium, high, xhigh, 或 max--yolo 使用 yolo 权限模式，自动批准工具调用--permission-mode 使用 strict、auto 或 yolo。无头模式默认 yolo；在 strict 或 auto 下，需要交互审批的调用会立即被拒绝，而非无限期挂起--output-format 输出格式：json、human、minimal（默认：minimal）--system-prompt 完全替换默认系统提示词。与 --system-prompt-file 冲突--system-prompt-file 从 UTF-8 文件读取替换用的系统提示词。与 --system-prompt 冲突--append-system-prompt 向系统提示词追加文本--short-prompt 使用紧凑提示词集：简化的系统提示词和更短的内置工具描述--skills / --no-skills 加载或跳过 skill 发现，覆盖 skills 设置。使用 --no-skills 时，不广播或调用任何 skills--include-skills 为本次运行添加精确的 skill 名称，替代 include_skills 设置。使用逗号分隔的值或重复该标志--exclude-skills 为本次运行移除精确的 skill 名称，替代 exclude_skills 设置。使用逗号分隔的值或重复该标志；排除项优先--enable-auto-memory / --disable-auto-memory 开启或关闭自动记忆，覆盖 auto_memory 设置（无头模式默认：关闭）--tools 用这些工具完全替换默认工具集。使用逗号分隔的值或重复该标志；已移除的 --allowed-tools 名称将被拒绝--include-tools 在默认工具集或 --tools 基础集之上添加工具。使用逗号分隔的值或重复该标志--exclude-tools 在应用 --tools 和 --include-tools 后移除工具。使用逗号分隔的值或重复该标志；已弃用的 --disallowed-tools 别名仍被接受-r, --resume 通过 ID 恢复之前保存的会话--session-save / --no-session-save 保存或跳过会话持久化，覆盖 session_save 设置。使用 --no-session-save 时，不写入转录或可恢复快照；与 --resume 冲突--check 在主任务完成后运行一次验证通过--offline-model 本地 GGUF 文件路径。启动由 llama.cpp 路由管理的 llama serve，加载模型，将会话指向本地提供商，并在退出时拆除 恢复的无头会话保留其保存的系统提示词和提示词模式；提示词标志仅影响新会话。即使选定的输出格式仅显示已完成的消息，模型调用也使用与 TUI 相同的流式传输和空闲超时。 输出格式​ 极简（默认）​ 仅显示代理消息、信息和错误： ante -p "这个项目做什么"
Human​ 以易读的格式显示消息、工具活动和回合状态。ANSI 颜色只在终端中启用，若设置了非空的 NO_COLOR 则自动关闭： ante --output-format human -p "fix the type error in main.rs"
JSON​ 把每个事件都输出为一行 JSON 对象，方便程序处理： ante --output-format json -p "list all TODO comments" | jq '.event'
验证检查​ 加上 --check 标志后，主任务完成后会再跑一轮验证，让 agent 自查工作成果： ante --check -p "refactor the auth module to use async/await"
验证阶段会： 对照原始需求检查完成了哪些工作 补齐遗漏或未完成的部分 在不影响正确性的前提下尽量优化 上下文增强​ 在无头模式下，Ante 会自动把当前目录的目录结构附加到你的 prompt 后面，让 agent 直接了解项目布局，无需你手动描述。 无头模式行为说明​ 不输出原始流式增量——输出的是完整消息而非增量片段，日志因此保持整洁 无人值守策略是明确的——默认为 yolo。显式指定 --permission-mode strict 或 auto 会被采纳，但由于无人应答，任何需要弹出确认的操作都会在入口处直接拒绝 提前检查认证——如果 provider 未认证，Ante 会立即报错退出 守护进程挂掉时快速失败——如果 agent 进程在任务完成前退出，Ante 会报错而不是返回成功码 恢复会话​ 传入 --resume 即可继续之前保存的会话。Ante 会重放已持久化的历史，然后把新的 prompt 作为下一轮对话执行： ante --resume ses_01ARZ3NDEKTSV4RRFFQ69G5FAV -p "now add tests"
会话中保存的模型、provider、effort 和对话记录会直接恢复；快照未固定的设置则按宿主机当前的默认值解析。因此无头恢复不要求当前默认 provider 与会话的 provider 一致。 TUI 会话退出时会打印会话 ID（Resume this session with: ante --resume ses_...）。 用 --no-session-save 启动的会话不会被持久化，之后也无法恢复。 无头模式必须提供会话 ID：不带 ID 的 --resume 仅在交互式 TUI 中可用，与 -p 或管道输入同时使用会报错。 示例​ CI：运行 lint 并修复​ ante --yolo -p "run cargo clippy and fix all warnings" 代码生成 ante --model claude-sonnet-5-5 --check -p "add comprehensive unit tests for src/core/session.rs" 受限工具 # 只读分析——不写入文件、不访问 shell ante --tools Read,Glob,Grep -p "analyze the codebase architecture and summarize it" 管道传入 diff 供审阅 git diff HEAD~1 | ante -p "review this diff for bugs and security issues"