自动化与协议
一次性任务使用 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 查看。
执行一次任务
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、正文与用量均为示意值:
{"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、缺失结束事件、 中断和非零退出码。运行完成不代表每个工具都成功或任务已通过验证,仍需检查结果与实际测试。
mica exec --json "检查项目依赖和测试入口" > events.jsonl 2> diagnostics.log包含可运行消费示例和校验步骤的完整工作流见 实战演示。
持续会话:app-server
mica app-server --dir ./your-project --thinking为一个会话持有一个常驻进程,持续写入 stdin、逐行读取 stdout。请求带 id,响应以相同 ID 返回 result 或 error;通知不带 ID。消息不需要 jsonrpc 字段。
下面的请求须由客户端按顺序发送:等待初始化响应,再创建线程,等待线程响应后启动任务。将项目路径替换为主机上的绝对路径。
{"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。下面展示两种独立操作,客户端按需发送:
{"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 和请求错误响应。
压缩已保存会话
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 提交
mica commit --dir ./your-projectmica 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 系驱动集成。