# 无头模式 （Headless Mode)

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

## 概述

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

无头模式也支持定时任务相关能力。在脚本、SDK 或服务端集成场景中，可以使用 `CronCreate`、`CronList`、`CronDelete` 等工具来创建、查看和取消定时任务。

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

## 基本用法

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`           | 允许的工具列表,空格分隔或<br /><br />逗号分隔的字符串                                           | `codebuddy --allowedTools mcp__slack mcp__filesystem`<br /><br />`codebuddy --allowedTools "Bash(npm install),mcp__filesystem"` |
| `--disallowedTools`        | 拒绝的工具列表,空格分隔或<br /><br />逗号分隔的字符串                                           | `codebuddy --disallowedTools mcp__splunk mcp__github`<br /><br />`codebuddy --disallowedTools "Bash(git commit),mcp__github"`   |
| `--settings`               | 从 JSON 文件或 JSON 字符串加载额外的设置配置                                                     | `codebuddy -p --settings '{"model":"gpt-5"}' "查询"`                                                                   |
| `--setting-sources`        | 指定要加载的设置源（可选值: `user`, `project`, `local`）                                         | `codebuddy -p --setting-sources project,local "查询"`                                                                  |
| `--mcp-config`             | 从 JSON 文件加载 MCP 服务器                                                                     | `codebuddy --mcp-config servers.json`                                                                                  |
| `--permission-prompt-tool` | 用于处理权限提示的 MCP 工具 （仅与 `--print` 配合使用）                                           | ❌ 不支持                                                                                                              |

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

有关 CLI 选项和功能的完整列表，请参阅 [CLI 参考](cli-reference.md) 文档。

## 多轮对话

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

```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 对象发出。

### 结构化 JSON 输出

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

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

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

> **提示**：使用 [jq](https://jqlang.github.io/jq/) 之类的工具来解析响应并提取特定字段：
>
> ```bash
> # 提取文本结果
> 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'
> ```

## 输入格式

### 文本输入 （默认）

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

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

### 流式 JSON 输入

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

每条消息都是一个 JSON "用户消息" 对象,遵循与输出消息模式相同的格式。消息使用 [jsonl](https://jsonlines.org/) 格式进行格式化,其中每行输入都是一个完整的 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 参考](cli-reference.md)。

## 相关资源

* [CLI 参考](cli-reference.md) - 完整的 CLI 文档
* [常见工作流](common-workflows.md) - 常见用例的分步指南
* [交互模式](interactive-mode.md) - 交互式会话功能
* [IAM 权限](iam.md) - 工具权限和访问控制

---

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