docs: 更新协议文档和设计文档

docs/protocols/agent/api-endpoints.md

@@ -79,6 +79,11 @@ Base URL: `/api/v1/agent`
 - usage 审计与成本回退策略见 `docs/protocols/agent/sse-events.md`（5) Usage 审计协议）
 - 空闲时会发送 keep-alive 注释行 `: keep-alive`
 
+当前阶段执行说明：
+
+- 公开事件阶段为 `worker` / `memory`。
+- `router` 已从运行链路移除，不再作为阶段事件对外发送。
+
 ### 错误码
 
 - `401` 未认证

docs/protocols/agent/run-agent-input.md

@@ -185,7 +185,7 @@ interface Context {
 
 ---
 
-## forwardedProps.client_time Schema
+## forwardedProps Schema（当前仅支持 client_time）
 
 `RunAgentInput.forwardedProps` 支持透传客户端时间上下文。日历相关能力必须使用以下结构：
 
@@ -213,6 +213,7 @@ interface ForwardedProps {
 - `device_timezone` 必须是有效 IANA 时区。
 - `client_now_iso` 必须是 RFC3339 且包含时区偏移。
 - `client_epoch_ms` 必须是整数毫秒时间戳。
+- `forwardedProps` 当前仅允许 `client_time`，额外字段会触发 `422 invalid RunAgentInput.forwardedProps`。
 - 业务代码不得使用服务器本地时区作为事件语义时区。
 
 ### 说明
@@ -434,7 +435,7 @@ interface HistoryMessageAssistant {
   seq: number;
   role: "assistant";
   content: string;
-  ui_schema: UiSchemaRenderer | null; // 由 worker_agent_output.ui_hints 编译
+  ui_schema: UiSchemaRenderer | null; // 由 agent_output.ui_hints 编译
   timestamp: string;
 }
 
@@ -519,4 +520,5 @@ interface UiSchemaRenderer {
 - `tools` 是前端工具通道字段；当前后端运行时不基于该字段构造后端工具 prompt
 - `RunAgentInput` 同时接受 camelCase 与 snake_case 别名输入（推荐统一使用 camelCase）
 - 日历能力依赖 `forwardedProps.client_time` 透传设备时间上下文；缺失时回退用户 profile 时区
+- `forwardedProps` 不支持业务私有控制字段（例如 `system_agent_mode`）
 - tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回

docs/protocols/agent/sse-events.md

@@ -84,7 +84,7 @@ data: <json>
   "type": "STEP_STARTED",
   "threadId": "...",
   "runId": "...",
-  "stepName": "router" | "worker"
+  "stepName": "worker" | "memory"
 }
 ```
 
@@ -95,7 +95,7 @@ data: <json>
   "type": "STEP_FINISHED",
   "threadId": "...",
   "runId": "...",
-  "stepName": "router" | "worker"
+  "stepName": "worker" | "memory"
 }
 ```
 
@@ -197,6 +197,11 @@ data: <json>
 
 `inputTokens`、`outputTokens`、`cost`、`latencyMs`、`model` 属于后端内部统计字段，不在 SSE 对外协议中暴露。
 
+当前实现补充说明：
+
+- `TEXT_MESSAGE_END` 在 wire payload 中会包含 `totalTokens`、`cachedPromptTokens`、`promptCacheHitTokens`、`promptCacheMissTokens`、`reasoningTokens`、`costSource`、`usageComplete` 等 usage 摘要字段，供前端观测面板使用。
+- 这些字段来自后端 usage 归一化层，属于 AG-UI 事件数据的一部分，不改变 `TEXT_MESSAGE_END` 主结构。
+
 ---
 
 ## 5) Usage 审计协议（后端内部）