09. 自动化与编辑器集成

无界面与 CI

在脚本或 CI 任务里跑 Matcha CLI：一条提示词进去，结果打到 stdout，然后退出。没有全屏 TUI，也没有 Matcha 托管的运行器。

无界面怎么工作

打开 TUI 的同一个 matcha 二进制也可以只跑一轮就离开。无界面模式就是这条一次性路径。你提供提示词，助手使用你已配置的服务商和本地工具，进程打印答案，然后以流水线可检测的状态码退出。

这不是编辑器嵌入。若要让编辑器对接一个长驻的 JSON-RPC 服务，用 matcha agent stdio。若要多个客户端挂到同一个本地后端，见主导进程。

传入 -p / --single（或 --prompt-json / --prompt-file）会把进程切成无界面模式。助手仍能用工具。变的是和你之间的约定：

部分	无界面行为
输入	标志或文件上的提示词。管道 stdin 不是提示词。
输出	stdout。默认纯文本；`--output-format json` 是一个对象。
权限	没有可点的 TUI。CI 里用 `--always-approve`（别名 `--yolo`）；需要护栏时再加 `--allow` / `--deny`。
会话	每次运行都开一个新会话，除非传入 `-r` / `-c`。
退出	提示词完成是 `0`；鉴权、网络或运行时失败是 `1`；SIGINT 是 `130`；SIGTERM 是 `143`。

--output-format 的取值：plain（默认）、json、streaming-json、streaming-messages-json。CI 先用 json，读 text 和 sessionId。

什么时候用

人不该坐在 TUI 里时用这个：

pre-commit 检查或 PR 评审机器人
Makefile 或 hook 里一次性「总结这次 diff」
用 ID 续上昨天的会话，再发一条后续提示词

无界面是本地的，也是 BYOK。在环境里设置服务商密钥（例如 XAI_API_KEY、OPENAI_API_KEY 或 ANTHROPIC_API_KEY），或先在这台机器上跑 matcha login --provider <id> --from-env。没有 Matcha 托管的运行器，没有 grok.com 中继，CI 也没有账号 OAuth。

跑一条提示词

先配置服务商，再在项目目录里跑提示词：

export XAI_API_KEY="…"   # or OPENAI_API_KEY / ANTHROPIC_API_KEY
matcha -p "List the top-level files and say what this repo is."

机器可读结果（这一轮结束后一个 JSON 对象）：

matcha -p "Summarize this repository in one paragraph." \
  --output-format json --always-approve

成功时有用的字段：text、stopReason、sessionId、requestId。提示词到达模型后，用量字段（usage、num_turns、modelUsage）也可能出现。失败时，stdout 是错误对象，例如 {"type":"error","message":"…"}，进程以非零退出。

记下会话并继续

ID=$(matcha -p "Review the staged diff." --output-format json --always-approve \
  | jq -r '.sessionId')
matcha -p "Now list only security issues." --resume "$ID" --always-approve

-r / --resume 接受会话 ID（脚本里优先用这个）或当前目录下的标题。-c / --continue 续上该目录最近一次会话。-s / --session-id 只**创建**一个新 UUID，不会续上。

管道与文件

# stdout is the answer — redirect it
matcha -p "Draft a README for this crate." --always-approve > README.md

# stdin is not the prompt; inject context yourself
matcha -p "Write a commit message for:

$(git diff --staged)" --always-approve

matcha --prompt-file ./prompt.txt --always-approve

CI 形态的评审（--always-approve 仍遵守拒绝规则和 hook）：

matcha -p "Review changes for bugs. Reply OK, or list issues." \
  --output-format json --always-approve | jq -r '.text'

常用标志

标志	作用
`-p, --single`	提示词文本（`--print` 是别名）。与 `--prompt-json` / `--prompt-file` 冲突。
`--output-format json`	一个结果对象。还有 `plain`、`streaming-json`、`streaming-messages-json`。
`--always-approve` / `--yolo`	跳过交互式工具确认。与 `--permission-mode bypassPermissions` 同一思路。
`-m, --model`	你所选服务商的模型 ID。
`--cwd`	工作目录（也用来向上找 `.git` 作为项目根）。
`--tools` / `--disallowed-tools`	仅无界面：工具允许名单 / 拒绝名单（内部 ID，例如 `read_file`）。
`--max-turns`	仅无界面：助手轮次上限。
`--allow` / `--deny`	权限规则（`Bash(npm)`、`Edit(src/*)`，…）。拒绝优先。
`--rules`	追加到系统提示词的额外文本。

容器里可以把 ~/.matcha 只读挂载：会话就会是临时的。不要把 API Key 放进 auth.json；那是元数据。用服务商的官方环境变量。

什么不可用

**Matcha 托管的运行器** — 没有替你跑提示词的官方云作业。
**产品中继** — 不要用不带 stdio 的 matcha agent，也不要传 --grok-ws-url。光写 matcha agent 是另一条面向中继的模式。
**自动更新** — --no-auto-update 会被接受，但什么也不做。
**账号 OAuth** — --oauth / --device-auth 会直接失败关闭。