CodeBuddy 无头模式

一、概述

注意：重要提示：

注意：-y （或 –dangerously-skip-permissions) 是非交互模式的必需参数。在使用 -p/–print 参数进行非交互式执行时，必须添加此参数才能执行需要授权的操作（文件读写、命令执行、网络请求等）,否则这些操作会被阻止。仅在受信任的环境和明确的任务场景下使用此参数。详见 CLI 参考。

二、基本用法

CodeBuddy Code 的主要命令行接口是 codebuddy （或 cbc) 命令。使用 –print （或 -p) 标志在非交互模式下运行并打印最终结果：

codebuddy -p "暂存我的更改并为它们编写一组提交" \\ –allowedTools "Bash,Read" \\ –permission-mode acceptEdits

三、配置选项

无头模式利用 CodeBuddy Code 中所有可用的 CLI 选项。以下是用于自动化和脚本编写的关键选项：

注意：说明：

注意：–permission-prompt-tool 功能当前不支持。

有关 CLI 选项和功能的完整列表，请参阅 CLI 参考 文档。

四、多轮对话

对于多轮对话，你可以恢复对话或从最近的会话继续：

# 继续最近的对话codebuddy –continue "现在重构以提高性能"# 通过会话 ID 恢复特定对话codebuddy –resume 550e8400-e29b-41d4-a716-446655440000 "更新测试"# 在非交互模式下恢复codebuddy –resume 550e8400-e29b-41d4-a716-446655440000 "修复所有 linting 问题" -p

五、文本输出 （默认）

codebuddy -p "解释文件 src/components/Header.tsx"# 输出： 这是一个 React 组件，显示…

六、JSON 输出

返回包含元数据的结构化数据：

codebuddy -p "数据层是如何工作的?" –output-format json

响应格式：

{ …}

七、流式 JSON 输出

在收到每条消息时流式传输：

codebuddy -p "构建一个应用程序" –output-format stream-json

每个对话都以初始 init 系统消息开始,然后是用户和助手消息列表,最后是包含统计信息的最终 result 系统消息。每条消息都作为单独的 JSON 对象发出。

八、后台任务事件（异步）

当模型用 run_in_background: true 启动后台命令（Bash / PowerShell）、后台工作流或后台 Agent 子任务时，CLI 会在 stream-json 输出流上为每个任务发出独立的 system 事件，携带唯一的 task_id（多任务并发时据此区分），tool_use_id 关联回发起该任务的 tool_use：

·任务启动 → system / subtype: "task_started"

·任务进度（每完成一次 tool_use，仅 sub-agent/workflow 类）→ system / subtype: "task_progress"（带 usage）

·任务状态变迁 → system / subtype: "task_updated"（带 patch）

·任务完成/失败/被停止 → system / subtype: "task_notification"

// 任务启动（进入运行态时立即推）{"type":"system","subtype":"task_started","task_id":"agent-00f6","tool_use_id":"toolu_01","description":"bg agent","task_type":"Agent","uuid":"…","session_id":"…"}// 进度（每完成一次 tool_use，携带累计 usage + 最近工具名；shell 任务不发）{"type":"system","subtype":"task_progress","task_id":"agent-00f6","description":"bg agent","usage":{"total_tokens":320,"tool_uses":2,"duration_ms":157},"last_tool_name":"Bash","uuid":"…","session_id":"…"}// 状态变迁（patch 携带变更字段；终态补 end_time）{"type":"system","subtype":"task_updated","task_id":"agent-00f6","patch":{"status":"completed","end_time":1783945615966},"status":"completed","uuid":"…","session_id":"…"}// 任务完成（可能在触发它的那轮 result 之后才到达；sub-agent 带 usage）{"type":"system","subtype":"task_notification","task_id":"agent-00f6","tool_use_id":"toolu_01","status":"completed","summary":"Background agent \\"bg agent\\" completed","output_file":"/…/bg-tasks/agent-00f6.stdout.log","usage":{"total_tokens":480,"tool_uses":2,"duration_ms":250},"session_id":"…"}

字段说明：

·进度事件（task_progress）是事件驱动的（每完成一次 tool_use 推一条），不是定时轮询；后台 shell 任务（Bash/PowerShell）不发 progress，只有 sub-agent / workflow 类任务发。

·终态可能只来 task_updated：某些后台任务的终态只通过 task_updated（patch.status 为终态）到达而没有配套的 task_notification。跟踪"活跃任务"的消费方应对二者的终态 status（completed / failed / stopped / killed）一视同仁地清理。

·重要（stdio 长连接场景）：后台任务可能在触发它的那一轮 result 之后才完成。使用 –input-format stream-json –output-format stream-json（stdin 保持打开的长连接）时，CLI 会在任务真正结束后把 task_notification 主动推回到同一输出流——无需你再发新的输入。因此消费方应持续读取输出流，不要在收到第一个 result 后就停止读取，否则会错过后台完成事件。纯 -p 单发模式（进程随首个 result 结束）不支持后台任务，会返回明确错误。

·禁用后台任务：不支持/不需要后台任务的场景，设置环境变量 CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS=1 可禁用后台任务——Bash / PowerShell / Agent 的 run_in_background 参数会从工具 schema 中隐藏，即便模型仍下发也会被忽略/降级为前台执行，从而不产生任何后台 task 事件、也不会有跨轮回推。SDK 的 query() 单发用法已自动注入该变量（因为 query() 在首个 result 处停止、无法接收跨轮回推事件）；持续读取的 SDK 用法（JS unstable_v2_createSession / Python CodeBuddySDKClient）不受影响。

九、结构化 JSON 输出

要获得符合特定架构的输出，请使用 –output-format json 和 –json-schema 以及 JSON Schema 定义。响应包括关于请求的元数据（会话 ID、使用情况等），结构化输出在 structured_output 字段中。

此示例从 auth.py 中提取函数名称并将其作为字符串数组返回：

codebuddy -p "提取 auth.py 中的主要函数名称" \\ –output-format json \\ –json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

提示：使用 jq 之类的工具来解析响应并提取特定字段：

# 提取文本结果codebuddy -p "总结这个项目" –output-format json | jq -r '.result'# 提取结构化输出codebuddy -p "提取 auth.py 中的函数名称" \\ –output-format json \\ –json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \\ | jq '.structured_output'

十、文本输入 （默认）

# 直接参数codebuddy -p "解释这段代码"# 从 stdinecho "解释这段代码" | codebuddy -p

十一、流式 JSON 输入

通过 stdin 提供的消息流,其中每条消息代表一个用户轮次。这允许在不重新启动 codebuddy 二进制文件的情况下进行多轮对话，并允许在模型处理请求时向模型提供指导。

每条消息都是一个 JSON "用户消息" 对象,遵循与输出消息模式相同的格式。消息使用 jsonl 格式进行格式化,其中每行输入都是一个完整的 JSON 对象。流式 JSON 输入需要 -p 和 –output-format stream-json。

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"解释这段代码"}]}}' | \\ codebuddy -p –output-format=stream-json –input-format=stream-json –verbose# 单条消息（包含图片）echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"文本提示词，如参考以下图片的文案"},{"type":"image","source":{"type":"base64","media_type":"image/png","data":"原始base64（不含协议前缀）"}}]}}' \\ | codebuddy -p –input-format stream-json –output-format stream-json# 多轮对话（多行 JSON，对同一进程持续发送）printf '%s\\n' \\ '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"第一问"}]}}' \\ '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"第二问"}]}}' \\ | codebuddy -p –input-format stream-json –output-format stream-json –verbose

十二、SRE 事件响应机器人

#!/bin/bash# 自动化事件响应 agentinvestigate_incident() { local incident_description="$1" local severity="${2:-medium}" codebuddy -p "事件: $incident_description (严重性: $severity)" \\ –append-system-prompt "你是一名 SRE 专家。诊断问题，评估影响，并提供即时行动项。" \\ –output-format json \\ –allowedTools "Bash,Read,WebSearch,mcp__datadog" \\ –mcp-config monitoring-tools.json}# 使用方式investigate_incident "支付 API 返回 500 错误" "high"

十三、自动化安全审查

# PR 的安全审计 agentaudit_pr() { local pr_number="$1" gh pr diff "$pr_number" | codebuddy -p \\ –append-system-prompt "你是一名安全工程师。审查此 PR 的漏洞、不安全模式和合规问题。" \\ –output-format json \\ –allowedTools "Read,Grep,WebSearch"}# 使用并保存到文件audit_pr 123 > security-report.json

十四、多轮法律助手

# 具有会话持久性的法律文档审查session_id=$(codebuddy -p "开始法律审查会话" –output-format json | jq -r '.session_id')# 分多个步骤审查合同codebuddy -p –resume "$session_id" "审查 contract.pdf 的责任条款"codebuddy -p –resume "$session_id" "检查 GDPR 要求的合规性"codebuddy -p –resume "$session_id" "生成风险执行摘要"

十五、使用技巧

·使用 JSON 输出格式 进行程序化解析响应：

# 使用 jq 解析 JSON 响应result=$(codebuddy -p "生成代码" –output-format json)code=$(echo "$result" | jq -r '.result')cost=$(echo "$result" | jq -r '.total_cost_usd')

·优雅地处理错误 – 检查退出代码和 stderr:

if ! codebuddy -p "$prompt" 2>error.log; then echo "发生错误:" >&2 cat error.log >&2 exit 1fi

·使用会话管理 在多轮对话中维护上下文

·考虑超时 对于长时间运行的操作：

timeout 300 codebuddy -p "$complex_prompt" || echo "5 分钟后超时"

·遵守速率限制 在进行多个请求时，通过在调用之间添加延迟

·使用 -y 在非交互模式下执行需要授权的操作：

# 非交互模式下的完整示例codebuddy -p "分析代码并运行测试" \\ –output-format json \\ -y \\ –allowedTools "Bash,Read,Grep"

注意：重要提示：

注意：-y （或 –dangerously-skip-permissions) 是非交互模式的必需参数。在使用 -p/–print 参数进行非交互式执行时，必须添加此参数才能执行需要授权的操作（文件读写、命令执行、网络请求等）,否则这些操作会被阻止。仅在受信任的环境和明确的任务场景下使用此参数。详见 CLI 参考。

注意：说明：

注意：无头模式非常适合 CI/CD 管道、自动化脚本和 agent 集成。将其与 MCP 服务器结合使用以扩展功能。