会话与消息 HTTP API

HTTP 会话流程通常是创建或选择 session，再提交消息，并按同步响应或事件追踪结果。下列 :id、:messageID 都需要替换为实际 ID；请求体中的 ? 表示可选字段，不是 JSON 键名的一部分。

创建与选择会话

方法和路径	用途或请求体
GET /session	会话列表
POST /session	创建会话，{ parentID?, title? }
GET /session/status	按 ID 返回全部会话状态
GET /session/:id	会话详情
PATCH /session/:id	更新属性，{ title? }
GET /session/:id/children	子会话
GET /session/:id/todo	待办列表
DELETE /session/:id	删除会话及其全部数据

初始化项目规则使用 POST /session/:id/init，请求体为 { messageID, providerID, modelID }，会分析应用并创建 AGENTS.md。

消息与任务入口

方法和路径	行为
GET /session/:id/message	列出消息，可带 limit 查询参数
GET /session/:id/message/:messageID	消息详情
POST /session/:id/message	发消息并等待响应
POST /session/:id/prompt_async	发消息后立即返回 204 No Content
POST /session/:id/command	执行 slash command
POST /session/:id/shell	执行 shell command

普通消息和异步消息的请求字段为 { messageID?, model?, agent?, noReply?, system?, tools?, parts }。parts 的具体类型依实例的 OpenAPI schema，不应把模型文本直接当作任意 part 对象。

普通消息接口返回 { info, parts }；异步接口的 204 仅表示此请求不等待结果，不是任务完成的信号。结合事件流与会话状态检查执行进度。

slash command 请求体为 { messageID?, agent?, model?, command, arguments }；shell 请求体为 { agent, model?, command }。二者均返回消息信息及 parts，而不是随意替换成普通消息的字段。

中止、分叉与摘要

方法和路径	请求体及行为
POST /session/:id/abort	中止正在执行的会话
POST /session/:id/fork	可传 { messageID? }，从已有会话的消息创建分叉
GET /session/:id/diff	可带 messageID 查询参数，返回文件 diff
POST /session/:id/summarize	{ providerID, modelID }，生成会话摘要
POST /session/:id/revert	{ messageID, partID? }，撤销消息
POST /session/:id/unrevert	恢复被撤销的消息

分叉接口返回新的 Session；不要继续把旧 ID 当成新分支。撤销涉及会话与工作区变更，不能将其视为仅删除界面显示。

权限响应与分享

权限请求响应端点为 POST /session/:id/permissions/:permissionID，请求体 { response, remember? }。此处官方表没有列出 response 的全部枚举；实现客户端时应依据实例 schema，不自行猜测字符串。

POST /session/:id/share 创建分享，DELETE /session/:id/share 撤回分享，均返回 Session。访问范围和保留行为见会话分享。

接入程序应保留中止、权限处理和最终状态判断，而不是将一次 HTTP 响应成功等同于所有文件操作已成功完成。