{ "openapi": "3.0.3", "info": { "title": "AIP TALK 第三方集成 API", "description": "面向第三方系统的 AIP TALK SSO、iframe 嵌入、消息元数据与决策复盘接口。\n第三方系统通过 HMAC-SHA256 JWT assertion 换取 CowAgent v2 token，随后可在 iframe 中嵌入 AIP TALK 或直接调用下文 API。", "version": "1.0.0", "contact": { "name": "CowAgent Enterprise AI Team" } }, "servers": [ { "url": "http://localhost:9899", "description": "CowAgent AIP-TALK 集成服务器" } ], "tags": [ { "name": "SSO", "description": "第三方 SSO 单点登录与令牌交换" }, { "name": "Embed", "description": "iframe 嵌入页" }, { "name": "AIP-TALK Metadata", "description": "AIP-TALK 消息历史、收藏、标签、分类、决策标记" }, { "name": "Decision Review", "description": "决策复盘中心接口" } ], "paths": { "/api/v1/sso/token": { "post": { "tags": [ "SSO" ], "summary": "服务端 assertion 换 token", "description": "第三方后端构造 HMAC-SHA256 JWT assertion，调用此接口换取 CowAgent v2 token。该 token 可用于 iframe 嵌入或后续 API 调用。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assertion" ], "properties": { "assertion": { "type": "string", "description": "HS256 签名的 JWT assertion" } } }, "example": { "assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } }, "responses": { "200": { "description": "成功返回 token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "token": { "type": "string" }, "user_id": { "type": "string" }, "tenant_id": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "expires_in": { "type": "integer" } } } } } }, "400": { "description": "请求格式错误" }, "403": { "description": "assertion 校验失败或 issuer 未启用" } }, "security": [] } }, "/auth/sso": { "post": { "tags": [ "SSO" ], "summary": "浏览器跳转 SSO", "description": "第三方页面可通过自动提交的 form 将 assertion 发送到该端点，CowAgent 设置 cookie 后 302 跳转到 return_to。", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "assertion" ], "properties": { "assertion": { "type": "string" }, "return_to": { "type": "string", "description": "登录成功后跳转路径，默认 /chat#view=aip-talk" } } } } } }, "responses": { "302": { "description": "设置 cookie 后跳转" }, "403": { "description": "assertion 校验失败" } }, "security": [] } }, "/embed/aip-talk": { "get": { "tags": [ "Embed" ], "summary": "iframe 嵌入页", "description": "返回 AIP TALK 嵌入页 HTML。需要在 query 或 Authorization header 中提供有效的 CowAgent v2 token，且 embedding origin 必须在 issuer.allowed_origins 列表中（该列表留空时不限制来源）。", "parameters": [ { "name": "token", "in": "query", "description": "CowAgent v2 token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "嵌入页 HTML" }, "401": { "description": "token 缺失或无效" }, "403": { "description": "embedding origin 不在 allowed_origins 中" } }, "security": [] } }, "/api/v1/aip-talk/history": { "get": { "tags": [ "AIP-TALK Metadata" ], "summary": "获取会话消息历史", "parameters": [ { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "is_decision", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "消息列表" } } } }, "/api/v1/aip-talk/favorites": { "get": { "tags": [ "AIP-TALK Metadata" ], "summary": "获取当前用户收藏的查询记录", "parameters": [ { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "tags", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "收藏列表" } } } }, "/api/v1/aip-talk/messages/{session_id}/{seq}/favorite": { "post": { "tags": [ "AIP-TALK Metadata" ], "summary": "收藏/取消收藏消息", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_favorite": { "type": "boolean" }, "favorite_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/aip-talk/messages/{session_id}/{seq}/tags": { "post": { "tags": [ "AIP-TALK Metadata" ], "summary": "更新消息标签", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/aip-talk/messages/{session_id}/{seq}/category": { "post": { "tags": [ "AIP-TALK Metadata" ], "summary": "更新消息分类", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/aip-talk/messages/{session_id}/{seq}/decision": { "post": { "tags": [ "AIP-TALK Metadata" ], "summary": "标记/取消标记关键决策", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_decision": { "type": "boolean" }, "title": { "type": "string" }, "note": { "type": "string" }, "expected_outcome": { "type": "string" }, "decision_status": { "type": "string", "example": "marked" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/aip-talk/messages/{session_id}/{seq}/decision/review": { "post": { "tags": [ "AIP-TALK Metadata", "Decision Review" ], "summary": "更新决策复盘信息", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_status": { "type": "string", "example": "reviewed" }, "actual_outcome": { "type": "string" }, "review_notes": { "type": "string" }, "reviewed_at": { "type": "string" }, "reviewed_by": { "type": "string" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/insights/decisions": { "get": { "tags": [ "Decision Review" ], "summary": "决策复盘列表", "parameters": [ { "name": "session_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "tags", "in": "query", "schema": { "type": "string" } }, { "name": "is_favorite", "in": "query", "schema": { "type": "boolean" } }, { "name": "datasource", "in": "query", "schema": { "type": "string" } }, { "name": "keyword", "in": "query", "schema": { "type": "string" } }, { "name": "period_start", "in": "query", "schema": { "type": "string" } }, { "name": "period_end", "in": "query", "schema": { "type": "string" } }, { "name": "visibility", "in": "query", "schema": { "type": "string" } }, { "name": "include_shared", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "决策列表" } } } }, "/api/v1/insights/decisions/{session_id}/{seq}": { "get": { "tags": [ "Decision Review" ], "summary": "决策详情（含上下文）", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "决策详情" } } } }, "/api/v1/insights/decisions/{session_id}/{seq}/review": { "post": { "tags": [ "Decision Review" ], "summary": "更新决策复盘（session/seq 路径）", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_status": { "type": "string" }, "actual_outcome": { "type": "string" }, "review_notes": { "type": "string" }, "reviewed_at": { "type": "string" }, "reviewed_by": { "type": "string" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/insights/decisions/{decision_id}/share": { "post": { "tags": [ "Decision Review" ], "summary": "共享决策", "parameters": [ { "name": "decision_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "string" } }, "visibility": { "type": "string", "example": "shared" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/insights/decisions/{decision_id}/approve": { "post": { "tags": [ "Decision Review" ], "summary": "审批决策", "parameters": [ { "name": "decision_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_status": { "type": "string", "example": "approved" }, "approved_by": { "type": "string" } } } } } }, "responses": { "200": { "description": "操作结果" } } } }, "/api/v1/insights/decisions/diff-summary": { "post": { "tags": [ "Decision Review" ], "summary": "生成预期结果与实际结果的 LLM 差异摘要", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_id": { "type": "integer" }, "title": { "type": "string" }, "note": { "type": "string" }, "expected_outcome": { "type": "string" }, "actual_outcome": { "type": "string" }, "query_record_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "差异摘要" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "CowAgent v2 token，通过 /api/v1/sso/token 换取。" } } }, "security": [ { "bearerAuth": [] } ] }