diff --git a/docs/protocols/agent/api-endpoints.md b/docs/protocols/agent/api-endpoints.md index 3b3a820..d8fb7bb 100644 --- a/docs/protocols/agent/api-endpoints.md +++ b/docs/protocols/agent/api-endpoints.md @@ -27,6 +27,8 @@ Base URL: `/api/v1/agent` - Body: `RunAgentInput` - 详细结构见 `docs/protocols/agent/run-agent-input.md` +- `forwardedProps.agent_type` 必填，由调用方透传，task 不做默认赋值 +- `agent_type=memory` 仅用于自动化调度内部触发，API 入口返回 422 ### Response @@ -81,8 +83,9 @@ Base URL: `/api/v1/agent` 当前阶段执行说明： -- 公开事件阶段为 `worker` / `memory`。 -- `router` 已从运行链路移除，不再作为阶段事件对外发送。 +- `worker` 模式采用两阶段：`router` -> `worker`。 +- `memory` 模式保持单阶段：`memory`。 +- 因此阶段事件可能出现 `router` / `worker` / `memory`。 ### 错误码 @@ -129,6 +132,11 @@ Base URL: `/api/v1/agent` tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回。续接时以 `metadata.tool_agent_output` 作为主信源（`content` 为轻量摘要）。 +可见性说明： + +- `/history` 仅返回命中 `ui.history` 可见位的消息。 +- 内部消息（例如 memory 私有输入）可落库但不会出现在 `/history`。 + ### 说明 - 若用户没有任何会话：返回 diff --git a/docs/protocols/agent/run-agent-input.md b/docs/protocols/agent/run-agent-input.md index f2b8010..45af3b0 100644 --- a/docs/protocols/agent/run-agent-input.md +++ b/docs/protocols/agent/run-agent-input.md @@ -185,12 +185,13 @@ interface Context { --- -## forwardedProps Schema（当前仅支持 client_time） +## forwardedProps Schema（支持 agent_type + client_time） -`RunAgentInput.forwardedProps` 支持透传客户端时间上下文。日历相关能力必须使用以下结构： +`RunAgentInput.forwardedProps` 支持透传运行模式与客户端时间上下文。日历相关能力必须使用以下结构： ```typescript interface ForwardedProps { + agent_type: string; // 必填，运行模式（如 "worker" / "memory"） client_time?: { device_timezone: string; // IANA 时区，例如 "America/Los_Angeles" client_now_iso: string; // RFC3339 带偏移时间，例如 "2026-03-16T09:12:33-07:00" @@ -213,7 +214,9 @@ interface ForwardedProps { - `device_timezone` 必须是有效 IANA 时区。 - `client_now_iso` 必须是 RFC3339 且包含时区偏移。 - `client_epoch_ms` 必须是整数毫秒时间戳。 -- `forwardedProps` 当前仅允许 `client_time`，额外字段会触发 `422 invalid RunAgentInput.forwardedProps`。 +- `forwardedProps.agent_type` 必填，且必须匹配后端已注册的 agent type。 +- `agent_type=memory` 为自动化任务内部模式，HTTP `/agent/runs` 入口不接受该值。 +- `forwardedProps` 仅允许 `agent_type` 与 `client_time`，额外字段会触发 `422 invalid RunAgentInput.forwardedProps`。 - 业务代码不得使用服务器本地时区作为事件语义时区。 ### 说明 @@ -235,6 +238,7 @@ Backend 实现了以下验证规则： | runId 最大 128 字符 | `runId exceeds length limit` | | messages ≤ 200 条 | `RunAgentInput.messages exceeds limit` | | user text ≤ 10,000 字符 | `RunAgentInput user message text exceeds limit` | +| forwardedProps.agent_type 必填 | `invalid RunAgentInput.forwardedProps` | | **恰好 1 条 user message** | `RunAgentInput.messages must contain exactly one user message` | | user message 必须在第一条 | `RunAgentInput.messages[0].role must be user` | | binary 必须是 image/* | `binary content requires image mimeType` | @@ -272,7 +276,9 @@ Backend 实现了以下验证规则： ], "tools": [], "context": [], - "forwardedProps": {} + "forwardedProps": { + "agent_type": "worker" + } } ``` @@ -302,7 +308,9 @@ Backend 实现了以下验证规则： ], "tools": [], "context": [], - "forwardedProps": {} + "forwardedProps": { + "agent_type": "worker" + } } ``` @@ -337,7 +345,9 @@ Backend 实现了以下验证规则： } ], "context": [], - "forwardedProps": {} + "forwardedProps": { + "agent_type": "worker" + } } ``` @@ -358,6 +368,7 @@ Backend 实现了以下验证规则： "tools": [], "context": [], "forwardedProps": { + "agent_type": "worker", "client_time": { "device_timezone": "America/Los_Angeles", "client_now_iso": "2026-03-16T09:12:33-07:00", @@ -520,5 +531,5 @@ interface UiSchemaRenderer { - `tools` 是前端工具通道字段；当前后端运行时不基于该字段构造后端工具 prompt - `RunAgentInput` 同时接受 camelCase 与 snake_case 别名输入（推荐统一使用 camelCase） - 日历能力依赖 `forwardedProps.client_time` 透传设备时间上下文；缺失时回退用户 profile 时区 -- `forwardedProps` 不支持业务私有控制字段（例如 `system_agent_mode`） +- `forwardedProps.agent_type` 是受控路由字段，必须由调用方显式传入；后端 task 不做默认赋值 - tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回 diff --git a/docs/protocols/agent/sse-events.md b/docs/protocols/agent/sse-events.md index 031ae06..4845677 100644 --- a/docs/protocols/agent/sse-events.md +++ b/docs/protocols/agent/sse-events.md @@ -84,7 +84,7 @@ data: "type": "STEP_STARTED", "threadId": "...", "runId": "...", - "stepName": "worker" | "memory" + "stepName": "router" | "worker" | "memory" } ``` @@ -95,7 +95,7 @@ data: "type": "STEP_FINISHED", "threadId": "...", "runId": "...", - "stepName": "worker" | "memory" + "stepName": "router" | "worker" | "memory" } ``` @@ -111,7 +111,7 @@ data: "messageId": "...", "toolCallId": "...", "toolCallName": "...", - "stage": "worker" + "stage": "worker" | "memory" } ``` @@ -126,7 +126,7 @@ data: "toolCallId": "...", "toolCallName": "...", "args": {}, - "stage": "worker" + "stage": "worker" | "memory" } ``` @@ -140,7 +140,7 @@ data: "messageId": "...", "toolCallId": "...", "toolCallName": "...", - "stage": "worker" + "stage": "worker" | "memory" } ``` @@ -153,7 +153,7 @@ data: "runId": "...", "messageId": "...", "role": "tool", - "stage": "worker", + "stage": "worker" | "memory", "tool_name": "...", "tool_call_id": "...", "tool_call_args": {}, @@ -184,7 +184,7 @@ data: "runId": "...", "messageId": "...", "role": "assistant", - "stage": "worker", + "stage": "worker" | "memory", "status": "success" | "partial_success" | "failed", "answer": "...", "key_points": [], @@ -323,3 +323,9 @@ cost = uncached_prompt_tokens * input_cost_per_token - `ui_schema` 这部分命名属于当前后端实现约束，文档与实现保持一致。 + +## 8) 可见性与上下文装载说明 + +- 持久化消息使用单字段 `visibility_mask`（位掩码）控制 consumer 可见性。 +- `/history` 仅投影 `ui.history` 可见消息。 +- 运行时上下文按当前 stage 对应 consumer 位过滤装载，不依赖前端展示可见性。 diff --git a/docs/protocols/models/auth.md b/docs/protocols/models/auth.md new file mode 100644 index 0000000..726db20 --- /dev/null +++ b/docs/protocols/models/auth.md @@ -0,0 +1,116 @@ +# Auth 协议（手机号 OTP） + +本文档定义 `/api/v1/auth` 的手机号验证码认证协议。 + +Base URL: `/api/v1/auth` + +--- + +## 手机号格式 + +- 统一使用 E.164：`^\+[1-9]\d{7,14}$` +- 前端必须提供国家/地区码选择，提交时拼接为完整 E.164（例如：`+14155552671`、`+8613812345678`） +- 后端只做安全归一化（去空白和常见分隔符），不推断或补全国家码 + +--- + +## 端点 + +| 方法 | 路径 | 说明 | +|---|---|---| +| POST | `/otp/send` | 发送短信验证码 | +| POST | `/phone-session` | 验证码登录/注册（同一路由） | +| POST | `/sessions/refresh` | 刷新会话 | +| DELETE | `/sessions` | 退出登录 | + +--- + +## 1) POST `/otp/send` + +发送验证码，不区分登录和注册场景。 + +### Request + +```json +{ + "phone": "+14155552671" +} +``` + +### Response + +`204 No Content` + +--- + +## 2) POST `/phone-session` + +验证码校验成功后返回会话。 + +- 若手机号已存在：直接登录 +- 若手机号不存在：自动创建账号后登录 + +### Request + +```json +{ + "phone": "+14155552671", + "token": "123456" +} +``` + +### Response + +```json +{ + "access_token": "...", + "refresh_token": "...", + "expires_in": 3600, + "token_type": "bearer", + "user": { + "id": "uuid", + "phone": "+14155552671" + } +} +``` + +--- + +## 3) POST `/sessions/refresh` + +### Request + +```json +{ + "refresh_token": "..." +} +``` + +### Response + +同 `/phone-session` 会话响应。 + +--- + +## 4) DELETE `/sessions` + +### Request + +```json +{ + "refresh_token": "..." +} +``` + +### Response + +`204 No Content` + +--- + +## 已移除端点 + +- `POST /verifications` +- `POST /verify` +- `POST /resend` +- `POST /sessions`（旧密码/短信混合登录入口） diff --git a/docs/protocols/ui/ui-schema.md b/docs/protocols/ui/ui-schema.md index a9e541c..52c939e 100644 --- a/docs/protocols/ui/ui-schema.md +++ b/docs/protocols/ui/ui-schema.md @@ -553,7 +553,7 @@ interface UiIconSpec { { "type": "text", "content": "基本信息", "role": "title" }, { "type": "kv", "items": [ { "key": "name", "label": "姓名", "value": "张三" }, - { "key": "email", "label": "邮箱", "value": "zhangsan@example.com", "copyable": true } + { "key": "phone", "label": "手机号", "value": "+8613812345678", "copyable": true } ]} ] },