09. 自动化与编辑器集成

ACP / stdio

把 Matcha CLI 嵌进编辑器或 SDK，作为长驻的本地助手。产品为这件事支持的传输是 Agent Client Protocol（ACP）上的 **stdio**。

ACP 怎么和 Matcha 说话

ACP 是 JSON-RPC：客户端掌管 stdin/stdout，Matcha CLI 作为 ACP 助手进程运行。典型会话是四次调用，可以手写，也可以用 SDK：

initialize — 协议版本与客户端能力
session/new — 工作目录（以及可选的 _meta）
session/prompt — 用户这一轮
session/update 通知 — 流式文本、思考和工具调用

标准 ACP 方法名（initialize、session/new、session/prompt、session/update）不会改写。私有扩展用 Matcha 命名空间 io.github.iampaco.matcha/*。接收端仍接受旧的 x.ai/* 名称。

这不是无界面 -p（一条提示词，然后退出）。

启动进程

显式以 stdio 模式启动助手：

matcha agent --always-approve stdio

适用于所有 matcha agent 传输的标志写在 agent **之后**、模式名 **之前**。模式专用标志写在模式名之后。

标志	作用
`-m, --model`	模型 ID
`--always-approve`	别名 `--yolo`。跳过交互式工具权限确认。
`--reauth`	助手启动前鉴权（可见别名 `--reauthenticate`）。
`--agent-profile <PATH>`	加载配置文件。
`--plugin-dir <DIR>`	本进程额外的插件目录（可重复；受信任）。
`--leader` / `--no-leader`	挂到共享主导进程，或强制用本地助手。

session/new 可以只为该会话打开 always-approve：

{
  "cwd": "/path/to/project",
  "mcpServers": [],
  "_meta": { "yoloMode": true }
}

其他 _meta 字段：rules、systemPromptOverride、agentProfile、autoMode。yoloMode 优先于 autoMode。

提示词运行期间，助手会发 session/update 通知。按 sessionUpdate 分支：

取值	含义
`agent_message_chunk`	回复文本
`agent_thought_chunk`	推理
`tool_call`	工具已开始
`tool_call_update`	进度或结果
`plan`	当前计划

从 initialize 的结果里发现额外方法。不要把旧教程里的 x.ai/* 表当成完整清单。反馈和产品遥测扩展保持关闭。

什么时候用 stdio

客户端必须保持会话打开时用 stdio：已经会讲 ACP 的编辑器、评测程序，或把工具调用流进自己界面的小程序。只要最终文本时，无界面 -p 更简单。

已经会讲 ACP 的编辑器（Zed、部分 Neovim 与 Emacs 包、marimo）可以自己拉起 matcha agent stdio。官方 ACP 客户端库有 TypeScript、Rust、Python、Go 和 Kotlin；见 https://agentclientprotocol.com。

发送提示词

给 SDK 或编辑器用的最小本地服务：

matcha agent --always-approve --model <your-model-id> stdio

JSON-RPC 是 stdin/stdout 上每行一个对象。在 initialize 和 session/new 之后，提示词长这样：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "<id from session/new>",
    "prompt": [{ "type": "text", "text": "List the files in this project" }]
  }
}

客户端接着读 session/update 通知，直到提示词结果到达。

命令行上的 always-approve 是 CI/SDK 的常见默认。拒绝规则和 hook 仍然生效。交互式 TUI 用户通常保持询问模式。

什么不可用

**产品中继**和**中继会话同步**。不要跑 matcha agent headless，不要传 --grok-ws-url，也不要打开 grok.com / 官方云 WebSocket。光写 matcha agent（没有 stdio / serve / leader 模式）会走那条中继路径 — BYOK 编辑器嵌入务必传 stdio。
**ACP 内的账号登录**（x.ai/auth/* 设备/OAuth 辅助）。先在这台机器上配置服务商密钥。
**反馈和遥测**扩展方法。