如何使用 run 无头模式（编程调度）

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

1、快速开始

# 基本调用 — 输出纯文本
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、退出码

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

4、选项说明

输出控制

--output-format（默认 text）

--verbose

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

模型与轮次

--model

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

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

--max-turns

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

--fallback-model

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

会话管理

--session-id

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

--resume

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

# 第一阶段：分析
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 命令 + Read 工具
soloncode run "总结变更" \
  --allowedTools "Bash(git log *),Bash(git diff *),Read" \
  --disallowedTools "Bash(rm *)"

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

权限模式

--permission-mode（默认 default）

环境与发现

--bare

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

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

--add-dir

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

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

结构化输出

--json-schema

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

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 配合使用。

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

5、输出格式详解

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 — 执行出错

# 只提取最终结果文本
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 — 自动代码审查

- 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

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

#!/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

定时巡检 — 带费用控制

#!/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 无头模式。以下场景可以直接替换使用：

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

8、选项速查表