> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless 与 CI

> 使用 mcode exec 接入 Shell、CI、批处理和评测，并处理结构化输出与退出码。

`mcode exec` 执行一次任务，不启动 TUI，适合自动化、批处理和可复现评测。它会使用当前配置的数据目录和模型，执行前需要已经登录或配置可用的 API Key Provider。

## 最小调用

```bash theme={null}
mcode exec "运行测试并修复失败项"
```

指定工作区和机器可读输出：

```bash theme={null}
mcode exec \
  --cwd ./repo \
  --output-format json \
  "分析失败日志，修复问题并运行相关测试"
```

## 选择任务指令

从 0.4.7 起，普通 `mcode exec` 任务可通过 `--prompt-mode` 选择系统指令：

| 模式 | 用途 |
| - | - |
| `tui` | 终端任务指令，默认值 |
| `coding` | 编程任务指令 |
| `work` | 通用工作任务指令 |

```bash theme={null}
mcode exec --prompt-mode coding "运行测试并修复失败项"
mcode exec --prompt-mode work "整理当前目录中的项目文档"
```

每种模式使用随安装包提供的完整系统模板；工具和权限仍沿用当前 TUI 配置。此参数用于普通 `exec` 任务。

使用 `--session` 或 `--continue` 续跑时，所选模式必须与会话保存的模式一致。使用非默认模式的会话时，请再次显式传入对应的 `--prompt-mode`；旧会话缺少模式信息时，新建会话运行。

## 指定本次思考强度

从 0.4.9 起，`mcode exec` 和 `mcode exec review` 支持 `--effort`，只覆盖本次运行：

```bash theme={null}
mcode exec --effort high "分析迁移方案"
mcode exec review --effort high --cwd ./repo
```

`--effort` 可单独使用，也可与 `--model` 一起使用；档位必须是所选模型支持的值。不支持思考强度的模型或无效档位会在任务开始前以非零退出码报错。

覆盖值不会写回会话；之后通过 `--session` 或 `--continue` 续跑且不指定 `--effort` 时，仍使用会话原有的强度。`#variant` 属于模型标识，不能用 `--model provider/model#high` 代替 `--effort high`。

## 输入方式

### 位置参数

```bash theme={null}
mcode exec "检查当前改动是否有类型错误"
```

### stdin 文本

只有显式传入 `--input -` 时才会读取 stdin：

```bash theme={null}
cat task.txt | mcode exec --input -
```

`--input -` 不能和位置参数 prompt 同时使用。

### stdin JSON

`--input-format json` 接受 JSON 字符串，或 `{ "prompt": "..." }` 对象：

```bash theme={null}
printf '%s\n' '{"prompt":"分析这个仓库的构建失败原因"}' \
  | mcode exec --input - --input-format json --output-format json
```

### 附件

可以通过 `--file` 添加文本、代码、日志、图片、视频或其他受支持文件。路径相对于 `--cwd` 解析：

```bash theme={null}
mcode exec \
  --cwd ./repo \
  --file logs/build.log \
  --file screenshots/failure.png \
  "根据附件定位构建失败原因"
```

单次调用最多 10 个文件，所有附件合计不超过 100 MB。没有 prompt 时，至少需要一个 `--file`。

## 参数参考

| 参数 | 说明 |
| - | - |
| `--input -` | 显式从 stdin 读取输入；当前只支持 `-` |
| `--input-format <format>` | `text` 或 `json`，默认 `text` |
| `--cwd <path>` | 工作区目录，默认当前目录 |
| `--file <path>` | 添加附件，可重复传入 |
| `--model <provider/model[#variant]>` | 仅为本次运行覆盖模型 |
| `--effort <level>` | 仅覆盖本次运行的思考强度，必须是模型支持的档位 |
| `--prompt-mode <mode>` | `tui`、`coding` 或 `work`，默认 `tui`；选择普通 `exec` 的系统指令 |
| `--session <id>` | 在已有活动 Session 中运行 |
| `--continue` | 继续 `--cwd` 中最近的活动 Session |
| `--config <path>` | 为本次进程使用指定 Runtime 配置文件 |
| `--permission <policy>` | `smart`、`full` 或 `off`，默认 `smart` |
| `--timeout <duration>` | 超时，例如 `30s`、`2m`；支持 `ms`、`s`、`m`、`h` |
| `--max-steps <count>` | 限制 Assistant 步数 |
| `--output-format <format>` | `text`、`json` 或 `stream-json`，默认 `text` |
| `--output-schema <schema>` | 内联 JSON Schema 或 Schema 文件路径 |
| `-o, --output-last-message <path>` | 成功后将最终 Agent 消息写入文件 |

`--session` 和 `--continue` 不能同时使用。`--permission ask` 需要交互式宿主，Headless 会直接拒绝；需要人工确认时使用 TUI 或 ACP。

## 输出格式

任务结果写入 stdout，诊断信息写入 stderr。这样可以把 stdout 安全地交给 `jq`、CI artifact 或其他下游工具。

### text

输出最终回答文本，适合人工查看或简单 Shell 管道。

### json

输出一条稳定的 `ExecResult` JSON：

```json theme={null}
{
  "schemaVersion": 1,
  "type": "exec.result",
  "runId": "run_...",
  "sessionId": "session_...",
  "turnId": "turn_...",
  "status": "succeeded",
  "output": "最终回答",
  "model": {
    "providerId": "minimax_oauth",
    "modelId": "模型 ID"
  },
  "usage": {
    "totalTokens": 1234,
    "inputTokens": 800,
    "outputTokens": 434
  },
  "durationMs": 4567
}
```

`status` 可能是 `succeeded`、`failed`、`timeout`、`cancelled` 或 `limit_exceeded`。`error`、`model` 和 `usage` 是可选字段，消费者应先判断 `status`。

### stream-json

输出换行分隔的、带版本字段的事件流，适合实时进度展示。事件包含 `schemaVersion`、`sequence`、`timestampMs`、`runId`、`sessionId` 和 `turnId`。常见事件包括：

* `exec.started`、`exec.completed`；
* `session.started`、`session.resumed`；
* `turn.started`、`turn.completed`、`turn.failed`；
* `item.started`、`item.updated`、`item.completed`。

消费者应按 `sequence` 处理，并为未知事件保留兼容空间。

## 结构化输出

`--output-schema` 接受内联 JSON 对象或文件路径。使用该参数时，最终回答必须是符合 Schema 的 JSON：

```bash theme={null}
mcode exec \
  --output-format json \
  --output-schema '{"type":"object","required":["summary"],"properties":{"summary":{"type":"string"}}}' \
  "总结当前改动"
```

解析失败或校验失败会返回 `status: failed`，错误码为 `STRUCTURED_OUTPUT_INVALID`。`--output-last-message` 只在任务成功并完成 Runtime 关闭后原子写入；写文件失败也会报告为失败。

## Session 与恢复

在指定工作区继续已有 Session：

```bash theme={null}
mcode exec --cwd ./repo --continue "继续完成剩余测试"
mcode exec --session <session-id> "检查上一轮修改"
```

如果 Session 中存在待处理的问卷或权限请求，Headless 不会等待它们，而是返回需要 TUI 或 ACP 的运行时错误。先在交互式入口解决问题，再继续 Session。

## 超时、步数和取消

```bash theme={null}
mcode exec --timeout 2m --max-steps 20 "运行最小验证"
```

收到 `SIGINT`、`SIGTERM` 或 `SIGHUP` 时，当前运行会被取消。CI 中建议同时设置超时和步数上限，并保存 stdout 与 stderr。

## 退出码

脚本应同时检查进程退出码和 JSON 中的 `status`：

| 退出码 | 含义 |
| -: | - |
| `0` | 成功 |
| `2` | 调用参数或输入错误 |
| `3` | 配置错误 |
| `4` | Runtime 或任务失败 |
| `6` | 超时 |
| `7` | 超过步数等运行限制 |
| `70` | 内部错误 |
| `130` | 被 Ctrl+C 或其他取消信号中断 |
| `141` | 下游管道关闭导致 broken pipe |

Shell 示例：

```bash theme={null}
set -o pipefail
result=$(mcode exec --output-format json "运行最小测试集")
status=$?
if [ "$status" -ne 0 ]; then
  echo "$result" >&2
  exit "$status"
fi
```