{ "openapi": "3.1.0", "info": { "title": "xiaoyu HTTP API", "description": "把小羽（coding agent）接给工作流编排器（n8n / Dify / 自研调度）的 HTTP 面。长任务用 prompt_async + status 轮询；需要人工放行的工具调用会让 status 停在 running/waiting_for_approval，回 POST /session/{id}/permissions 放行。\n\n本服务同时在 `POST /mcp` 挂着 **MCP server 面**（agent 级三工具 xiaoyu / xiaoyu_reply / xiaoyu_close，streamable HTTP；LangChain / LangGraph 经 langchain-mcp-adapters 即插即用，`--no-mcp` 可关）。它是 JSON-RPC 端点，刻意不列进下方路由表——这份 schema 是给 Dify / n8n 导入的 REST 工具清单。详见 docs/mcp-server.md。", "version": "0.66.0" }, "paths": { "/diagnostics": { "get": { "tags": [ "system" ], "summary": "进程自诊断：RSS / 线程 / fd + 各子系统在册计量（会话、请求、MCP 连接、后台任务）", "operationId": "diagnostics", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Diagnostics" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "tags": [ "system" ], "summary": "存活探针", "operationId": "health", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Health" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent": { "post": { "tags": [ "agent" ], "summary": "新建 agent（持久化、版本化的配置对象）", "description": "把 model / mode / effort / append_system_prompt / approval / sandbox / budget / pricing 打包成一个可引用的对象；POST /session 用 agent 字段引用它。approval / sandbox 只能比服务端启动参数更严。", "operationId": "create_agent", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_create_agent" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Agent" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "agent" ], "summary": "列出 agent", "operationId": "list_agents", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Agents" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/{agent_id}": { "get": { "tags": [ "agent" ], "summary": "agent 详情", "operationId": "get_agent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "versions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "true=带全部历史版本", "default": false, "title": "Versions" }, "description": "true=带全部历史版本" }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Agent" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "agent" ], "summary": "更新 agent → 新版本", "description": "config 里给的键覆盖、没给的沿用；每次更新版本号 +1。已在跑的会话仍钉着创建时的版本。", "operationId": "update_agent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_update_agent" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Agent" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "agent" ], "summary": "归档 agent（只读、不再接受新会话）", "operationId": "archive_agent", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Archive Agent" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session": { "post": { "tags": [ "session" ], "summary": "新建会话", "operationId": "create_session", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_create_session" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Session" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "session" ], "summary": "列出会话", "operationId": "list_sessions", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Sessions" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}": { "get": { "tags": [ "session" ], "summary": "会话详情", "operationId": "get_session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Session" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "session" ], "summary": "关闭会话", "operationId": "close_session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Close Session" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/prompt": { "post": { "tags": [ "run" ], "summary": "跑一轮（同步等结果）", "description": "适合几十秒内能跑完的任务；长任务用 prompt_async，否则会撞上调用方的 HTTP 超时。", "operationId": "prompt", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "idempotency-key", "in": "header", "required": false, "schema": { "type": "string", "description": "重发同一次提交时带同一个键：不会再跑一轮，拿回的是那一轮的结果", "default": "", "title": "Idempotency-Key" }, "description": "重发同一次提交时带同一个键：不会再跑一轮，拿回的是那一轮的结果" }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_prompt" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Prompt" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/prompt_async": { "post": { "tags": [ "run" ], "summary": "跑一轮（立刻返回）", "description": "接受后立刻返回 202；用 GET /status 轮询，或 GET /events 拉进度。", "operationId": "prompt_async", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "idempotency-key", "in": "header", "required": false, "schema": { "type": "string", "description": "重发同一次提交时带同一个键：不会再跑一轮", "default": "", "title": "Idempotency-Key" }, "description": "重发同一次提交时带同一个键：不会再跑一轮" }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_prompt_async" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Prompt Async" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/status": { "get": { "tags": [ "run" ], "summary": "轮询状态", "description": "status: idle / running / error；detail: working / waiting_for_approval / finished / interrupted / failed。waiting_for_approval 表示卡在等人放行，不是在算——编排侧据此决定去回 /permissions 还是继续等。", "operationId": "get_status", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Status" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/events": { "get": { "tags": [ "events" ], "summary": "拉事件（游标 + long-poll）", "description": "从 from 开始拉；返回的 `next` 就是下次的 from。wait>0 时没有新事件会挂起等待，最长 60s——给不方便消费 SSE 的编排器（n8n HTTP 节点、Dify）用。", "operationId": "get_events", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "起始游标", "default": 1, "title": "From" }, "description": "起始游标" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2000, "minimum": 1, "default": 200, "title": "Limit" } }, { "name": "wait", "in": "query", "required": false, "schema": { "type": "number", "maximum": 60.0, "minimum": 0.0, "description": "long-poll 秒数", "default": 0.0, "title": "Wait" }, "description": "long-poll 秒数" }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Events" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/events/stream": { "get": { "tags": [ "events" ], "summary": "事件流（SSE）", "description": "follow=true（默认）常驻推送，会话关掉或客户端断开才结束——编辑器/看板用。follow=false 只把当前这一轮推完就关流：调用方不必自己想办法中断连接，适合'提交一轮 → 跟完 → 收工'的一次性消费方。⚠️ follow=false 要在**提交 prompt 之后**开——会话空闲且没有新事件时它立刻关流，先开会拿到一个空流（200 但零事件）。", "operationId": "stream_events", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "From" } }, { "name": "follow", "in": "query", "required": false, "schema": { "type": "boolean", "description": "false=本轮跑完即关流", "default": true, "title": "Follow" }, "description": "false=本轮跑完即关流" }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/questions": { "get": { "tags": [ "questions" ], "summary": "查询待答问题或重连时的全部状态", "operationId": "list_questions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "include_terminal", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Terminal" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/questions/{question_id}": { "get": { "tags": [ "questions" ], "summary": "查询问题状态与提交回执", "operationId": "get_question", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "question_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Question Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "questions" ], "summary": "取消未接纳的问题", "operationId": "cancel_question", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "question_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Question Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/questions/{question_id}/answers": { "post": { "tags": [ "questions" ], "summary": "幂等提交回答，不启动空闲模型", "operationId": "answer_question", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "question_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Question Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answers", "idempotency_key" ], "additionalProperties": false, "properties": { "idempotency_key": { "type": "string", "maxLength": 200 }, "answers": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "object", "required": [ "item_id" ], "properties": { "item_id": { "type": "string" }, "selected": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "string", "maxLength": 4000 }, "skipped": { "type": "boolean" } } } } } } } } } } }, "/session/{session_id}/permissions": { "get": { "tags": [ "approval" ], "summary": "挂起的审批", "operationId": "list_permissions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Permissions" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "approval" ], "summary": "回一个审批决定", "description": "decision=allow 放行；deny 拒绝（reason 会原文回灌给模型，等于改指令）；updated_args 非空时整体替换本次调用参数再执行（宿主'包一层再放行'的通道）。", "operationId": "respond_permission", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_respond_permission" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Respond Permission" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/budget": { "post": { "tags": [ "run" ], "summary": "改/撤本会话的预算", "description": "budget=null 撤掉预算；否则整体替换为 {tokens, usd}。到线后的会话（detail=budget_reached）只有经这里调高或撤掉才能再跑——这是硬闸，不是提醒。", "operationId": "set_budget", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_set_budget" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Set Budget" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/abort": { "post": { "tags": [ "run" ], "summary": "打断当前这一轮", "operationId": "abort", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_abort" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Abort" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/session/{session_id}/steer": { "post": { "tags": [ "run" ], "summary": "向进行中的一轮插话", "description": "不打断，模型在下一个 step 边界看到这句话再继续。会话空闲时回 409——空闲期入队的插话会在下一轮开头被 drain 掉，回 200 等于骗调用方说话已送到。", "operationId": "steer", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "Authorization" } }, { "name": "x-xiaoyu-token", "in": "header", "required": false, "schema": { "type": "string", "default": "", "title": "X-Xiaoyu-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_steer" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Steer" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_abort": { "properties": { "turn": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Turn", "description": "要打断的是第几轮（/status 的 in_flight）。给了就只打断那一轮：它已经结束、在跑的是别的轮时什么都不做" } }, "type": "object", "title": "Body_abort" }, "Body_create_agent": { "properties": { "name": { "type": "string", "title": "Name", "description": "给人看的名字，不要求唯一" }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "model / base_url / mode / effort / approval / append_system_prompt / sandbox / sandbox_network / budget{tokens,usd} / pricing{模型:{input,output}}（美元/百万 token） / mcp_servers{名:{command,args,env}|{url,headers}}（宿主自有 MCP server，同 .mcp.json 的 mcpServers；需服务端 --agent-mcp 开放）" } }, "type": "object", "required": [ "name" ], "title": "Body_create_agent" }, "Body_create_session": { "properties": { "workspace": { "type": "string", "title": "Workspace", "description": "工作区路径，须在 root 之内；缺省用 root", "default": "" }, "model": { "type": "string", "title": "Model", "description": "模型名，缺省跟随服务端配置", "default": "" }, "mode": { "type": "string", "title": "Mode", "description": "default / auto / plan", "default": "" }, "agent": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Agent", "description": "引用一个 agent：agent_id（最新版本）或 {\"id\": ..., \"version\": n}（钉版本）。给了它就不能再给 model/mode" }, "budget": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Budget", "description": "本会话的硬预算 {tokens, usd}；缺省用 agent 的默认预算；usd 需要 agent 带 pricing" }, "questions": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Questions", "description": "显式启用持久化问答：{} 或 {foreground_timeout_seconds: 60}；须启用 persist" }, "fork_from": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Fork From", "description": "从另一个会话的历史起步：会话 id，或 {\"session_id\": ..., \"turns\": K}（只带前 K 轮）。来源会话不受影响；没另给 workspace / agent / model / mode 就沿用来源的" } }, "type": "object", "title": "Body_create_session" }, "Body_prompt": { "properties": { "text": { "type": "string", "title": "Text", "description": "给模型的指令" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "JSON Schema：要求本轮以符合它的对象收尾，结果在 result.output（模型没给则 null）" } }, "type": "object", "required": [ "text" ], "title": "Body_prompt" }, "Body_prompt_async": { "properties": { "text": { "type": "string", "title": "Text", "description": "给模型的指令" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "JSON Schema：要求本轮以符合它的对象收尾，结果在 result.output（模型没给则 null）" } }, "type": "object", "required": [ "text" ], "title": "Body_prompt_async" }, "Body_respond_permission": { "properties": { "request_id": { "type": "string", "title": "Request Id" }, "decision": { "type": "string", "title": "Decision", "description": "allow | deny" }, "reason": { "type": "string", "title": "Reason", "default": "" }, "updated_args": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Updated Args" } }, "type": "object", "required": [ "request_id", "decision" ], "title": "Body_respond_permission" }, "Body_set_budget": { "properties": { "budget": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Budget" } }, "type": "object", "title": "Body_set_budget" }, "Body_steer": { "properties": { "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "text" ], "title": "Body_steer" }, "Body_update_agent": { "properties": { "config": { "additionalProperties": true, "type": "object", "title": "Config" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "title": "Body_update_agent" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "servers": [ { "url": "http://127.0.0.1:8420", "description": "xiaoyu serve" } ] }