qzl/social-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update agent and UI protocol documentation

Browse Source 
- Update api-endpoints.md with new agent endpoints
- Update run-agent-input.md with new input schemas
- Update sse-events.md with new event types
- Update ui-schema.md with schema changes
This commit is contained in:
qzl
2026-03-19 18:42:45 +08:00
parent 0abf51e837
commit 641d847008
5 changed files with 158 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/protocols/agent/api-endpoints.md
+10 -2
View File
@@ -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`。
### 说明
- 若用户没有任何会话：返回
docs/protocols/agent/run-agent-input.md
+18 -7
View File
@@ -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` 对外返回
docs/protocols/agent/sse-events.md
+13 -7
View File
@@ -84,7 +84,7 @@ data: <json>
"type": "STEP_STARTED",
"threadId": "...",
"runId": "...",
"stepName": "worker" | "memory"
"stepName": "router" | "worker" | "memory"
}
```
@@ -95,7 +95,7 @@ data: <json>
"type": "STEP_FINISHED",
"threadId": "...",
"runId": "...",
"stepName": "worker" | "memory"
"stepName": "router" | "worker" | "memory"
}
```
@@ -111,7 +111,7 @@ data: <json>
"messageId": "...",
"toolCallId": "...",
"toolCallName": "...",
"stage": "worker"
"stage": "worker" | "memory"
}
```
@@ -126,7 +126,7 @@ data: <json>
"toolCallId": "...",
"toolCallName": "...",
"args": {},
"stage": "worker"
"stage": "worker" | "memory"
}
```
@@ -140,7 +140,7 @@ data: <json>
"messageId": "...",
"toolCallId": "...",
"toolCallName": "...",
"stage": "worker"
"stage": "worker" | "memory"
}
```
@@ -153,7 +153,7 @@ data: <json>
"runId": "...",
"messageId": "...",
"role": "tool",
"stage": "worker",
"stage": "worker" | "memory",
"tool_name": "...",
"tool_call_id": "...",
"tool_call_args": {},
@@ -184,7 +184,7 @@ data: <json>
"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 位过滤装载，不依赖前端展示可见性。
docs/protocols/models/auth.md
+116
View File
@@ -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`（旧密码/短信混合登录入口）
docs/protocols/ui/ui-schema.md
+1 -1
View File
@@ -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 }
]}
]
},