无头 CLI 没有人即时确认操作，因此默认应只读。agent -p 适合脚本；–force 会允许直接改文件，必须在隔离分支和明确验证下使用。
开始前先准备什么
先在本地测试仓库完成 CLI 认证，并把提示词、允许目录、超时、输出格式和失败处理写清楚。
建议使用临时分支或独立工作树，记录运行前提交哈希与 git status --short。提示词应包含允许读取的路径、预期输出、禁止动作和完成判据；脚本还要设置合理超时，并把标准输出、标准错误与退出码分别保存。
实际操作步骤
- 用 agent -p 执行只读分析，捕获标准输出、标准错误和退出码。
- 需要机器解析时选择 json 或 stream-json，先用固定样本验证字段，不用正则猜文本。
- 只有任务明确需要写文件时才加 –force，并在临时分支或工作树运行。
- 脚本结束后检查退出码、git diff、生成物和测试；任何一项异常都让流水线失败。
Cursor Headless CLI 官方文档说明，非交互脚本使用 -p 或 --print；不加 --force 时，修改只会被建议而不会写入。可先执行：
agent -p "只读分析 src/auth，列出三个最高风险并给出文件路径；不要修改文件" \
> agent-output.txt 2> agent-error.txt
status=$?
test "$status" -eq 0 || exit "$status"PowerShell 中可以读取 $LASTEXITCODE。上例的重定向写法适用于常见 Unix shell，CI 应按实际 shell 调整。即使退出码为零，也要验证输出包含约定字段或可接受结论。
选择稳定的机器输出
Cursor Output Format 官方文档区分三种格式：text只给最终消息，适合人读；json等待完成后返回结构化结果；stream-json按行输出完整事件，适合实时进度。流式格式不是单个 JSON 对象，消费者应逐行解析，并忽略将来新增的未知字段。
agent -p --output-format json "审查当前 diff，按严重级别返回问题"
agent -p --output-format stream-json "解释测试失败" > events.jsonl先用固定的小仓库保存样例输出，验证解析器能处理成功、Agent 报错、超时、空输出和未知字段。不要依赖自然语言固定句式，也不要用正则从 text 模式猜工具结果。
写入模式增加四道门禁
确实需要改文件时才使用 agent -p --force "..."。四道门禁分别是：隔离分支或工作树；限制允许改动的目录与文件；运行后审查 git diff --check和文件清单；最后执行项目测试。任何超出范围的文件、非零退出码、解析失败或测试失败都应让流水线失败并保留日志。
怎样验证结果
验收是同一输入可重复获得可解析结果，非零退出码被捕获，写入模式的 diff 与测试均被检查。
可在同一固定提交上连续运行两次只读任务，比较输出结构而非要求措辞完全相同。写入任务则应验证目标文件存在、差异仅限白名单、构建产物可重建，并在干净环境重新测试。
常见错误
- 不要默认使用 –force 或 –yolo。
- 不要把 JSON 流当单个 JSON 对象。
- 退出码为零仍要核对业务结果。
适用边界
自动化调用会消耗账户用量并可能接触源码；CI 密钥要用受控 Secret，日志中不得输出。
相关问答
text、json、stream-json 怎么选？
人读摘要用 text，单次机器处理用 json，实时事件与工具进度用 stream-json。
CI 中如何防止意外修改？
默认不加 –force，并用只读权限或临时工作树再加 diff 门禁。
资料与适用范围
本文根据 2026 年 10 月 1 日核验的 Cursor Headless CLI 官方文档、Cursor Output Format 官方文档整理。示例流程未在你的设备、账号或仓库中实测，界面、方案、权限和项目命令应以当前环境为准。
Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/32670.html
