SDK 协议(stream-json)

最底层的集成面:经 stdin/stdout 上的 NDJSON 驱动 hipmmcode。服务器与各类桥接内部用的就是它;要把 hipmmcode 作为智能体引擎嵌进你自己的程序,选它。

hipmmcode --input-format stream-json --output-format stream-json

进来的每一行是控制消息或用户回合;出去的每一行是事件。

你发送的消息

消息	用途
{"type":"user", "message":{…}}	一个用户回合(文本和/或附件)
initialize	握手:能力、会话信息
set_model	会话中切换渠道/模型
interrupt	取消运行中的回合
set_permission_mode	切换 default / acceptEdits / plan / bypass
控制应答	回应权限/提问往返(见下)

你收到的事件

事件	含义
system(subtype init)	会话已启动:会话 id、模型、工具
assistant / 文本增量	流式回答内容
工具事件	每个工具调用 + 其结果
control_request → can_use_tool	权限往返:在 stdin 回 allow/deny
control_request → ask_user_question	结构化提问往返
result	回合结束:最终文本、用量、费用、subtype(success / error / budget_exceeded / …)

--include-partial-messages 增加逐 token 原始帧,--include-hook-events 增加 hook 生命周期帧,--replay-user-messages 把你的回合回显为帧(做转写器有用)。

一次性结构化管线

简单自动化不需要完整协议 —— 无头 exec 输出同样的信封:

hipmmcode --print --output-format stream-json "跑测试并总结失败项"
hipmmcode --print --json --json-schema '{"type":"object",…}' "…"   # schema 校验的回答

权限接线

协议模式下,权限决策以 can_use_tool 控制请求发给你 —— 宿主进程就是审批人。替代方案:预设模式(--permission-mode acceptEdits)、settings 里给规则、或 --permission-webhook 把决策搬到 HTTP 服务。未应答的请求失败关闭。

嵌入清单

1. 拉起 hipmmcode --input-format stream-json --output-format stream-json(可选 -p/-m、--resume <id>)。
2. 发 initialize,再发一条 user 消息。
3. 流式消费事件;应答 control_request。
4. 收到 result 后,要么发下一条 user(会话保温),要么退出。
5. 想以后 --resume,持久化 session_id。

完整、始终最新的手册 —— 消息 schema、示例、退出码 —— 内嵌在二进制里:

hipmmcode integration | less