---
title: "如何使用 run 无头模式（编程调度）"
---

`soloncode run` 是 SolonCode CLI 的无头（Headless/Print）模式。它接收一个提示词，运行 Agent 到完成，按指定格式输出结构化结果，并以退出码标识成功或失败。整个过程不启动交互式 UI，适合在 CI 管道、定时任务、脚本编排中无人值守调用。

### 1、快速开始

```bash
# 基本调用 — 输出纯文本
soloncode run "总结最近一次提交的变更内容"

# JSON 输出 — 适合程序化消费
soloncode run "列出所有公开函数" --output-format json

# 流式输出 — 实时获取事件流
soloncode run "重构日志模块" --output-format stream-json --verbose

# 从 stdin 管道读取提示词
cat build-error.log | soloncode run --output-format json "分析这个错误的根本原因"
```

### 2、命令格式

```
soloncode run [提示词] [选项...]
```

提示词可以作为第一个位置参数传入，也可以通过 stdin 管道输入。如果两者都提供，命令行参数优先。如果都没有，进程以退出码 3 终止。

### 3、退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功完成 |
| 1 | 运行出错（Agent 异常、API 错误等） |
| 2 | 超过最大轮次限制（`--max-turns`） |
| 3 | 未提供提示词 |
| 4 | 超过费用预算（`--max-budget-usd`） |

CI 管道可以根据退出码决定是否中断流水线或触发告警。

### 4、选项说明

#### 输出控制

##### `--output-format`（默认 text）

| 值 | 说明 |
|----|------|
| `text` | 纯文本输出，直接打印最终答复 |
| `json` | 输出单个 JSON 对象，包含 result / session_id / metrics / 费用等 |
| `stream-json` | 逐行 JSONL 事件流，每个事件占一行 |

##### `--verbose`

stream-json 模式必须配合 `--verbose` 才会输出流式事件。不带此选项时 stream-json 仅输出最终 result 事件。

#### 模型与轮次

##### `--model`

指定使用的模型名称或别名。未指定时使用引擎默认模型。

```bash
soloncode run "生成文档" --model sonnet
soloncode run "快速摘要" --model haiku
```

##### `--max-turns`

限制 Agent 的最大推理-行动轮次。超过限制时以退出码 2 终止。CI 场景建议设置此值防止失控。

##### `--fallback-model`

主模型不可用时自动回退到指定模型。适合夜间批处理任务中主模型限流时的容错。

#### 会话管理

##### `--session-id`

为本次执行指定固定的会话 ID。

##### `--resume`

恢复指定的已有会话，保留之前的上下文。常用于多阶段任务：

```bash
# 第一阶段：分析
soloncode run "分析这个模块的结构和问题" --output-format json > phase1.json

# 提取 session_id
SESSION=$(jq -r '.session_id' phase1.json)

# 第二阶段：基于分析结果写测试
soloncode run "根据之前的分析为这个模块编写单元测试" --resume "$SESSION"
```

##### `--continue`

继续最近的默认会话（session ID 为 `cli`）。

#### 工具控制

##### `--allowedTools`

限制 Agent 只能使用指定的工具。多个工具用逗号分隔，未指定时允许全部工具。

##### `--disallowedTools`

禁止 Agent 使用指定的工具。

##### 工具规则语法 `ToolName(pattern)`

支持细粒度的工具命令控制，用 glob 模式限定工具的调用范围：

```bash
# 只允许特定的 Bash 命令 + Read 工具
soloncode run "总结变更" \
  --allowedTools "Bash(git log *),Bash(git diff *),Read" \
  --disallowedTools "Bash(rm *)"
```

规则解析：
- `Read` — 纯工具名，匹配该工具的所有调用
- `Bash(git log *)` — 工具名 + glob 模式，仅匹配符合模式的调用

#### 权限模式

##### `--permission-mode`（默认 default）

| 模式 | 行为 | 适用场景 |
|------|------|---------|
| `default` | 禁用人工审批，未授权操作自动拒绝 | 通用无人值守 |
| `dontAsk` | 同 default，语义化命名 | CI 推荐 |
| `plan` | 仅分析和提议，禁止所有写入类工具 | 方案评审 |
| `acceptEdits` | 自动批准文件编辑，其它操作自动拒绝 | 安全的自动修复 |
| `bypassPermissions` | 跳过所有权限检查和沙箱限制 | 沙箱环境内的全权操作 |

#### 环境与发现

##### `--bare`

跳过 skills、agents 挂载、MCP 服务和 memory 的自动发现。适合需要最小化启动开销或确保隔离环境的场景。

效果：移除所有 SKILLS/AGENTS 类型挂载、移除所有已注册的 MCP 服务、禁用 memory（长期记忆）。

##### `--add-dir`

注册额外的工作目录，授予 Agent 读写权限。可多次指定以添加多个目录：

```bash
soloncode run "跨仓库分析" \
  --add-dir /path/to/repo-a \
  --add-dir /path/to/repo-b
```

#### 结构化输出

##### `--json-schema`

约束 Agent 的输出格式为指定的 JSON Schema：

```bash
soloncode run "提取所有公开函数及其签名" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"signature":{"type":"string"},"file":{"type":"string"}},"required":["name","signature"]}}}}'
```

输出中的 `structured_output` 字段包含符合 schema 的解析结果。

#### 费用控制

##### `--max-budget-usd`

设置本次执行的费用硬上限（美元）。超过预算时以退出码 4 终止。建议与 `--max-turns` 配合使用。

```bash
soloncode run "大规模代码迁移" --max-budget-usd 5.0 --max-turns 30
```

### 5、输出格式详解

#### json 模式

```json
{
  "result": "依赖注入是一种设计模式...",
  "is_error": false,
  "session_id": "print-a1b2c3d4",
  "metrics": {
    "total_tokens": 1250,
    "prompt_tokens": 980,
    "completion_tokens": 270,
    "duration_ms": 3200
  },
  "total_cost_usd": 0.0072
}
```

#### stream-json 模式

逐行输出 JSONL 事件流，事件类型包括：

- `system/init` — 执行开始，包含模型、工具列表、版本信息
- `assistant` — Agent 输出文本或工具调用
- `user` — 工具执行结果
- `result` — 执行结束，包含最终结果和 metrics
- `error` — 执行出错

```bash
# 只提取最终结果文本
soloncode run "分析代码" --output-format stream-json --verbose \
  | jq -r 'select(.type=="result") | .result'

# 审计日志 — 保存完整事件流同时提取结果
soloncode run "重构" --output-format stream-json --verbose \
  | tee logs/run-$(date +%s).jsonl \
  | jq -r 'select(.type=="result") | .result'
```

### 6、CI/CD 实践示例

#### GitHub Actions — 自动代码审查

```yaml
- name: Code Review
  run: |
    soloncode run "Review the changes in this PR." \
      --output-format json \
      --allowedTools "Read,Grep,Glob,Bash(git log *),Bash(git diff *)" \
      --permission-mode dontAsk \
      --max-turns 15 \
      --max-budget-usd 2.0 \
      --model sonnet > review.json
    cat review.json | jq -r '.result' > review-comment.md
```

#### 两阶段任务 — 分析后生成测试

```bash
#!/bin/bash
set -euo pipefail

soloncode run "分析 src/auth 模块的结构和潜在问题" \
  --output-format json --max-turns 10 > phase1.json

SESSION=$(jq -r '.session_id' phase1.json)

soloncode run "根据之前的分析，为 src/auth 模块编写单元测试" \
  --resume "$SESSION" \
  --output-format json \
  --permission-mode acceptEdits \
  --max-turns 20 > phase2.json
```

#### 定时巡检 — 带费用控制

```bash
#!/bin/bash
soloncode run "检查项目的代码质量：未使用的导入、潜在 NPE、重复代码" \
  --output-format json \
  --allowedTools "Read,Grep,Glob,Bash(git log *)" \
  --permission-mode dontAsk \
  --max-turns 25 \
  --max-budget-usd 3.0 \
  --fallback-model haiku \
  | jq '.' > reports/health-$(date +%Y%m%d).json
```

### 7、与 Claude Code 兼容性

`soloncode run` 的设计对齐 Claude Code `claude -p` 无头模式。以下场景可以直接替换使用：

| 场景 | Claude Code | soloncode run |
|------|-------------|---------------|
| 基本调用 | `claude -p "prompt"` | `soloncode run "prompt"` |
| JSON 输出 | `claude -p "prompt" --output-format json` | `soloncode run "prompt" --output-format json` |
| 流式输出 | `claude -p "prompt" --output-format stream-json --verbose` | `soloncode run "prompt" --output-format stream-json --verbose` |
| 轮次限制 | `claude -p "prompt" --max-turns 10` | `soloncode run "prompt" --max-turns 10` |
| 模型选择 | `claude -p "prompt" --model sonnet` | `soloncode run "prompt" --model sonnet` |
| 会话续接 | `claude -p "prompt" --resume SESSION` | `soloncode run "prompt" --resume SESSION` |
| 工具限制 | `claude -p "prompt" --allowedTools "Read,Grep"` | `soloncode run "prompt" --allowedTools "Read,Grep"` |
| 细粒度控制 | `claude -p "prompt" --allowedTools "Bash(git log *)"` | `soloncode run "prompt" --allowedTools "Bash(git log *)"` |
| 权限模式 | `claude -p "prompt" --permission-mode dontAsk` | `soloncode run "prompt" --permission-mode dontAsk` |
| 结构化输出 | `claude -p "prompt" --json-schema '{...}'` | `soloncode run "prompt" --json-schema '{...}'` |
| 费用控制 | `claude -p "prompt" --max-budget-usd 5.0` | `soloncode run "prompt" --max-budget-usd 5.0` |
| 裸模式 | `claude -p "prompt" --bare` | `soloncode run "prompt" --bare` |
| 多目录 | `claude -p "prompt" --add-dir /repo/a` | `soloncode run "prompt" --add-dir=/repo/a` |
| 回退模型 | `claude -p "prompt" --fallback-model haiku` | `soloncode run "prompt" --fallback-model haiku` |

stream-json 事件格式兼容 Claude Code，jq 过滤器可以直接复用。

### 8、选项速查表

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--output-format` | text/json/stream-json | text | 输出格式 |
| `--model` | string | 引擎默认 | 模型名称或别名 |
| `--max-turns` | int | 无限制 | 最大推理-行动轮次 |
| `--session-id` | string | 自动生成 | 指定会话 ID |
| `--resume` | string | — | 恢复指定会话 |
| `--continue` | flag | false | 继续最近默认会话 |
| `--allowedTools` | CSV | 全部允许 | 允许的工具列表 |
| `--disallowedTools` | CSV | 空 | 禁止的工具列表 |
| `--permission-mode` | enum | default | 权限模式 |
| `--verbose` | flag | false | 启用流式事件输出 |
| `--bare` | flag | false | 跳过自动发现 |
| `--add-dir` | string（可重复） | — | 额外工作目录 |
| `--fallback-model` | string | — | 回退模型 |
| `--json-schema` | string | — | 结构化输出约束 |
| `--max-budget-usd` | double | 无限制 | 费用硬上限（美元） |