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 审计协议（后端内部）

docs/protocols/ui/data-flow.md

@@ -139,7 +139,19 @@ tool 结果不再走 UI 编译链路：`TOOL_CALL_RESULT` 提供 `tool_call_args
   3. 执行 GoRouter 跳转（建议 `context.go(...)`）。
 - `path` 必须是已落地页面路由，且应是已实参化路径（如 `/todo/123`，而非 `/todo/:id`）。
 
-### 7.3 约束建议
+### 7.3 路由表达粒度（Route-First 约束）
+
+- 关键业务动作（创建、编辑、分享、处理邀请等）应优先设计为可深链页面路由，而不是仅存在于临时弹层。
+- 若 UI 采用 sheet 风格展示，也应由页面路由承载状态，再以页面内 surface 呈现 sheet 视觉。
+- `todo.edit` 必须落地为独立子页面（`/todo/{id}/edit`），不应通过详情页内弹窗承载编辑主流程。
+- 推荐后端优先使用以下 route_id 生成导航（示例）：
+  - `calendar.event_create` -> `/calendar/events/new`
+  - `calendar.event_edit` -> `/calendar/events/{id}/edit`
+  - `calendar.event_share` -> `/calendar/events/{id}/share`
+  - `todo.create` -> `/todo/new`
+  - `todo.edit` -> `/todo/{id}/edit`
+
+### 7.4 约束建议
 
 - 为了让前端只保留一种解析逻辑，推荐强约束：
   - `path` 只接受内部路由；