无头模式 （Headless Mode) ​

以编程方式运行 CodeBuddy Code,无需交互式 UI

概述 ​

无头模式允许您通过命令行脚本和自动化工具以编程方式运行 CodeBuddy Code,无需任何交互式 UI。

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

基本用法 ​

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

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

配置选项 ​

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

标志描述示例
--print, -p在非交互模式下运行codebuddy -p "查询"
--output-format指定输出格式 （text, json, stream-json)codebuddy -p --output-format json
--resume, -r通过会话 ID 恢复对话codebuddy --resume abc123
--continue, -c继续最近的对话codebuddy --continue
--verbose启用详细日志记录codebuddy --verbose
--append-system-prompt追加到系统提示词 （仅与 --print 配合使用）codebuddy --append-system-prompt "自定义指令"
--allowedTools允许的工具列表,空格分隔或

逗号分隔的字符串		codebuddy --allowedTools mcp__slack mcp__filesystem

codebuddy --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools拒绝的工具列表,空格分隔或

逗号分隔的字符串		codebuddy --disallowedTools mcp__splunk mcp__github

codebuddy --disallowedTools "Bash(git commit),mcp__github"
--mcp-config从 JSON 文件加载 MCP 服务器codebuddy --mcp-config servers.json
--permission-prompt-tool用于处理权限提示的 MCP 工具 （仅与 --print 配合使用）❌ 不支持

说明： --permission-prompt-tool 功能当前不支持。

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

多轮对话 ​

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

bash
# 继续最近的对话
codebuddy --continue "现在重构以提高性能"

# 通过会话 ID 恢复特定对话
codebuddy --resume 550e8400-e29b-41d4-a716-446655440000 "更新测试"

# 在非交互模式下恢复
codebuddy --resume 550e8400-e29b-41d4-a716-446655440000 "修复所有 linting 问题" -p

输出格式 ​

文本输出 （默认） ​

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

JSON 输出 ​

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

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

响应格式：

json
{
 ...
}

流式 JSON 输出 ​

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

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

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

输入格式 ​

文本输入 （默认） ​

bash
# 直接参数
codebuddy -p "解释这段代码"

# 从 stdin
echo "解释这段代码" | codebuddy -p

流式 JSON 输入 ​

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

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

bash
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

Agent 集成示例 ​

SRE 事件响应机器人 ​

bash
#!/bin/bash

# 自动化事件响应 agent
investigate_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"

自动化安全审查 ​

bash
# PR 的安全审计 agent
audit_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

多轮法律助手 ​

bash
# 具有会话持久性的法律文档审查
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 输出格式 进行程序化解析响应：

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

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

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

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

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

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

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

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

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

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

相关资源 ​

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