本页内容

自动化与协议

一次性任务使用 mica exec,持续会话使用 mica app-server。两种入口都能调用模型与工具,适合接入脚本、CI 或自己的客户端。

选择入口

入口用途输出
mica models发现可用的 provider 与模型 ID。默认逐行文本,--json 为 JSON 数组。
mica exec执行一次任务,或续跑已有会话。默认文本,--json 为 ThreadEvent JSONL。
mica app-server让客户端持续驱动一个会话。stdin/stdout 上的 Codex v2 风格 JSONL 请求与通知。
mica compact压缩已保存会话的上下文。单行 JSON 结果。
mica commit执行 commit 插件命令:生成提交说明并执行 Git 提交、尝试推送。单行 JSON 结果。

先按 模型与配置 配置 API,再执行 mica models 获取准确的模型 ID。全部参数也可通过 mica --help 查看。

执行一次任务

TERMINAL
mica exec "概述当前项目的主要模块和测试命令"
mica exec --dir ./your-project --no-save "检查安装文档是否与脚本一致"
mica exec --json --thinking --max-turns 20 "查找测试失败原因并给出修复"
参数用途
--dir <path>指定任务工作目录;exec 也接受 --cd。
--model <provider/model>覆盖本次任务的 provider 与模型。
--variant <effort>选择模型声明的档位(取值见 mica models --json 的 efforts)。exec 严格校验显式值,不支持该值或没有声明档位都会报错;不需要指定时省略此参数。
--role <name>使用已安装角色。
--max-turns <count>限制模型往返与工具循环次数。
--session <id>续跑已保存的会话。
--no-save不保存本次会话;工具仍可读写工作区。
--json输出适合程序消费的事件流。
--thinking在 JSON 事件中包含模型提供的思考内容。

MCP 参数为 --mcp-config <file>、--strict-mcp-config 与 --mcp-init-timeout-ms <ms>。配置结构和合并规则见 扩展指南。提示词中也可使用 [Image](本地路径) 引用图片,实际处理能力取决于模型。

消费 exec JSONL

将 stdout 作为事件流读取,将 stderr 单独保存为诊断日志。下面是省略工具事件后的格式示例,ID、正文与用量均为示意值:

JSON
{"type":"thread.started","thread_id":"example-session"}
{"type":"turn.started"}
{"type":"item.updated","item":{"id":"agent-message","type":"agent_message","text":"项目使用 Vitest 运行测试。"}}
{"type":"item.completed","item":{"id":"agent-message","type":"agent_message","text":"项目使用 Vitest 运行测试。"}}
{"type":"turn.completed","usage":{"input_tokens":1200,"cached_input_tokens":900,"cache_write_input_tokens":0,"output_tokens":100,"reasoning_output_tokens":0}}

当前投影发送 thread.started、turn.started、item.started、item.updated、item.completed、turn.completed 和 error。agent_message 更新中的 text 是本次已累计的文本,应替换显示而不是逐条拼接; 它可包含工具调用前后的文本,也可能保留重试时已输出的文本,不一定只是最终答复。启用 --thinking 后的 reasoning 更新是思考片段。

所有工具调用都投影为 command_execution,其中 command 是工具名与截断后的参数摘要, 并非一定是 shell 命令;结果输出会截断,完成事件的 exit_code: 0 是投影占位值,不能用来判断实际命令成功。 没有原始工具 ID 时会生成 ID,开始与结束不保证可配对。该接口也不输出完整子代理事件或子代理用量。

turn.completed.usage 的 input_tokens 不含缓存读取量,后者单独计入 cached_input_tokens;当前投影中的 cache_write_input_tokens 和 reasoning_output_tokens 是零值占位,不能据此推断服务的实际用量。

使用 thread.started.thread_id 关联会话;带 --no-save 时不能据此恢复本次会话。 只有收到 turn.completed 且进程成功退出,才能认为运行正常完成;同时处理 error、缺失结束事件、 中断和非零退出码。运行完成不代表每个工具都成功或任务已通过验证,仍需检查结果与实际测试。

TERMINAL
mica exec --json "检查项目依赖和测试入口" > events.jsonl 2> diagnostics.log

包含可运行消费示例和校验步骤的完整工作流见 实战演示。

持续会话:app-server

TERMINAL
mica app-server --dir ./your-project --thinking

为一个会话持有一个常驻进程,持续写入 stdin、逐行读取 stdout。请求带 id,响应以相同 ID 返回 result 或 error;通知不带 ID。消息不需要 jsonrpc 字段。

下面的请求须由客户端按顺序发送:等待初始化响应,再创建线程,等待线程响应后启动任务。将项目路径替换为主机上的绝对路径。

JSON
{"id":1,"method":"initialize"}
{"method":"initialized"}
{"id":2,"method":"thread/start","params":{"cwd":"/absolute/path/to/project"}}
{"id":3,"method":"turn/start","params":{"input":[{"type":"text","text":"解释项目的测试入口"}]}}

turn/start 的响应表示任务已开始,不表示任务已完成。持续读取通知,直到收到该轮的 turn/completed,其状态为 completed、interrupted 或 failed。

核心请求

方法用途
initialize获取协议能力与平台信息。
thread/start创建或加载线程,可传 cwd 和 model。
thread/resume通过 threadId 恢复已保存的线程。
turn/start在空闲时提交 input,可覆盖 model、effort、cwd,并支持 Mica 的 role 扩展。
turn/steer运行中提交补充要求,须携带当前 expectedTurnId。
turn/interrupt携带当前 turnId 中止任务,随后等待结束通知。

用 turn/started 通知中的 turn ID 替换 ACTIVE_TURN_ID。下面展示两种独立操作,客户端按需发送:

JSON
{"id":4,"method":"turn/steer","params":{"expectedTurnId":"ACTIVE_TURN_ID","input":[{"type":"text","text":"也检查一下集成测试"}],"clientMessageId":"follow-up-1"}}
{"id":5,"method":"turn/interrupt","params":{"turnId":"ACTIVE_TURN_ID"}}

补充要求在完整工具迭代边界注入。任务已经结束或 ID 不匹配时,客户端应处理错误并重新判断状态。

通知与扩展

生命周期使用 thread/started、turn/started、turn/completed;内容使用 item/started、item/completed、item/agentMessage/delta、item/reasoning/textDelta 和 item/commandExecution/outputDelta。thread/tokenUsage/updated 提供用量。

app-server 的 item 类型采用 commandExecution 等驼峰名称,exec 则采用 command_execution 等下划线名称。两者是不同输出接口,消费端应分别处理。

Mica 的 mica/* 扩展同步排队、后台任务、子代理与会话状态。客户端应忽略不认识的通知,避免因扩展事件中断主流程。详细协议实现见 协议类型。

进程生命周期

保持 stdin 打开才能持续会话。发送 {"method":"shutdown"} 或关闭 stdin 将触发收尾并中止当前任务。MCP 初始化和部分启动失败可降级为警告;客户端仍需检查 warning、error 和请求错误响应。

压缩已保存会话

TERMINAL
mica compact --session SESSION_ID --tool-results-only
mica compact --session SESSION_ID
mica compact --session SESSION_ID --force

将 SESSION_ID 替换为实际会话 ID,操作前等待会话空闲。输出单行 JSON,以 ok 判断结果;内容较少或没有可清理内容时可能返回 code: "not_needed"。

  • --tool-results-only:本地清理,把工具调用与结果聚合成一条占位调用(只留工具名与次数)、 丢弃思考、替换媒体,保留对话正文与轮次,不调用模型。
  • 不带模式参数:使用摘要压缩策略,必要时调用模型;--force 可在历史较短时强制摘要。
  • --prune-only:本地清理,必要时丢弃最早轮次,适合接受历史损失的任务。

生成并执行 Git 提交

TERMINAL
mica commit --dir ./your-project

mica commit 以一次性插件命令执行官方插件 commit 的 /commit:收集 Git 变化,调用模型生成提交说明,然后执行 git add -A、提交并尝试推送。它会包含工作区中的全部 可暂存变化,运行前应完成审阅。写提交说明的模型默认跟随主配置,也可以在$MICA_HOME/plugin-settings/commit.json(或配置页 Plugins → Git Commit)单独指定接口、模型与是否推送。

成功结果包含 ok、commitHash、subject、commitMessage 与 pushed;失败结果包含 code 与 error。推送失败时本地提交可能已经创建,重试前检查 Git 状态。

Codex 参数兼容与执行边界

exec 接受部分 Codex 系驱动参数,包括 --cd、-c model_reasoning_effort=... 和权限参数别名。--enable、--skip-git-repo-check 等参数只用于调用兼容,不代表启用相同功能。

面向集成开发者的设计说明见 Headless 执行层设计 与 Codex 系驱动集成。

文档随项目持续更新编辑此页