refactor: 重构 Tool Result 契约，移除 ui_hints 统一使用 result 字段
- ToolAgentOutput 移除 result_summary 和 ui_hints，统一使用 result 字段 - 日历/用户查找工具移除 ui_hints 输出，改为机器可读的结构化结果 - Agent History 移除 tool 消息的 ui_hints 处理逻辑 - App 版本检查改为 manifest.json 方式，支持多渠道发布 - 更新 settings 配置和测试用例适配新结构
This commit is contained in:
qzl
@@ -110,18 +110,20 @@ Base URL: `/api/v1/agent`
|
||||
messages: Array<{
|
||||
id: string;
|
||||
seq: number;
|
||||
role: "user" | "assistant" | "tool";
|
||||
role: "user" | "assistant";
|
||||
content: string;
|
||||
attachments?: Array<{ // user 附件签名链接列表
|
||||
mimeType: string;
|
||||
url: string;
|
||||
}>;
|
||||
ui_schema?: object | null; // assistant/tool 的编译后 UI
|
||||
ui_schema?: object | null; // assistant 的编译后 UI
|
||||
timestamp: string; // ISO-8601
|
||||
}>;
|
||||
}
|
||||
```
|
||||
|
||||
tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回。
|
||||
|
||||
### 说明
|
||||
|
||||
- 若用户没有任何会话：返回
|
||||
|
||||
@@ -428,16 +428,6 @@ interface HistoryAttachment {
|
||||
url: string;
|
||||
}
|
||||
|
||||
// role = "tool"
|
||||
interface HistoryMessageTool {
|
||||
id: string;
|
||||
seq: number;
|
||||
role: "tool";
|
||||
content: string;
|
||||
ui_schema: UiSchemaRenderer | null; // 由 tool_agent_output.ui_hints 编译
|
||||
timestamp: string;
|
||||
}
|
||||
|
||||
// role = "assistant"
|
||||
interface HistoryMessageAssistant {
|
||||
id: string;
|
||||
@@ -448,7 +438,7 @@ interface HistoryMessageAssistant {
|
||||
timestamp: string;
|
||||
}
|
||||
|
||||
type HistoryMessage = HistoryMessageUser | HistoryMessageTool | HistoryMessageAssistant;
|
||||
type HistoryMessage = HistoryMessageUser | HistoryMessageAssistant;
|
||||
```
|
||||
|
||||
### UiSchemaRenderer
|
||||
@@ -529,3 +519,4 @@ interface UiSchemaRenderer {
|
||||
- `tools` 是前端工具通道字段；当前后端运行时不基于该字段构造后端工具 prompt
|
||||
- `RunAgentInput` 同时接受 camelCase 与 snake_case 别名输入（推荐统一使用 camelCase）
|
||||
- 日历能力依赖 `forwardedProps.client_time` 透传设备时间上下文；缺失时回退用户 profile 时区
|
||||
- tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回
|
||||
|
||||
@@ -157,13 +157,14 @@ data: <json>
|
||||
"tool_name": "...",
|
||||
"tool_call_id": "...",
|
||||
"tool_call_args": {},
|
||||
"status": "success" | "failed",
|
||||
"result_summary": "...",
|
||||
"ui_schema": {},
|
||||
"status": "success" | "failure" | "partial",
|
||||
"result": "...",
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
说明：`TOOL_CALL_RESULT` 不再携带 `ui_schema`。tool 结果通过 `result` 字段提供紧凑、结构化、可执行的信息（优先包含 id/status/count 等关键事实），用于 agent 后续推理与工具编排。
|
||||
|
||||
### 3.4 文本完成事件
|
||||
|
||||
#### `TEXT_MESSAGE_END`
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
# App Update Check Protocol
|
||||
|
||||
本文档定义移动端应用更新检查协议，适用于 Android/iOS。
|
||||
|
||||
## 1. Endpoint
|
||||
|
||||
- Method: `GET`
|
||||
- Path: `/api/v1/app/check-updates`
|
||||
|
||||
## 2. Request Query
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `platform` | `android` \| `ios` | 否 | 默认 `ios` |
|
||||
| `channel` | `string` | 否 | 发布渠道，默认 `release` |
|
||||
| `current_version_code` | `int` | 是 | 当前构建号（Android versionCode / iOS buildNumber） |
|
||||
| `current_version_name` | `string` | 否 | 当前展示版本号（如 `0.1.1`） |
|
||||
|
||||
## 3. Response
|
||||
|
||||
```json
|
||||
{
|
||||
"has_update": true,
|
||||
"update_type": "optional",
|
||||
"latest_version_name": "0.1.1",
|
||||
"latest_version_code": 2,
|
||||
"min_supported_version_code": 1,
|
||||
"download_url": "https://example.com/releases/social-app-android-v0.1.1+2-release.apk",
|
||||
"release_notes": "问题修复和体验优化",
|
||||
"file_name": "social-app-android-v0.1.1+2-release.apk",
|
||||
"file_size": 59768832,
|
||||
"sha256": "<sha256>"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Update Decision Algorithm
|
||||
|
||||
后端必须按以下顺序判定：
|
||||
|
||||
1. `current_version_code >= latest_version_code` -> `update_type = none`
|
||||
2. `current_version_code < min_supported_version_code` -> `update_type = required`
|
||||
3. 其他且 `< latest_version_code` -> `update_type = optional`
|
||||
|
||||
`has_update = (update_type != "none")`
|
||||
|
||||
## 5. Release Manifest
|
||||
|
||||
发布清单文件位置：`deploy/static/releases/manifest.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"releases": [
|
||||
{
|
||||
"platform": "android",
|
||||
"channel": "release",
|
||||
"version_name": "0.1.1",
|
||||
"version_code": 2,
|
||||
"min_supported_version_code": 1,
|
||||
"file_name": "social-app-android-v0.1.1+2-release.apk",
|
||||
"release_notes": "问题修复和体验优化",
|
||||
"file_size": 59768832,
|
||||
"sha256": "<sha256>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
同一 `platform + channel` 可存在多条记录，服务端按 `version_code` 最大值选最新版。
|
||||
|
||||
## 6. Package Naming Convention
|
||||
|
||||
Android 安装包命名规范：
|
||||
|
||||
`social-app-android-v{versionName}+{versionCode}-{channel}.apk`
|
||||
|
||||
示例：
|
||||
|
||||
- `social-app-android-v0.1.1+2-release.apk`
|
||||
- `social-app-android-v0.1.2+3-beta.apk`
|
||||
|
||||
规则：
|
||||
|
||||
- `versionName` 给用户展示（如 `0.1.1`）
|
||||
- `versionCode` 必须严格递增
|
||||
- `channel` 建议使用 `release` / `beta`
|
||||
|
||||
推荐打包命令：
|
||||
|
||||
```bash
|
||||
./deploy/build-android-release.sh \
|
||||
--backend-host 115.190.63.157 \
|
||||
--channel release \
|
||||
--release-notes "问题修复和体验优化"
|
||||
```
|
||||
|
||||
该脚本会：
|
||||
|
||||
- 按命名规范生成 APK 文件到 `deploy/static/releases/`
|
||||
- 每次打包自动将 `apps/pubspec.yaml` 的 `buildNumber` 递增 1 并写回
|
||||
- 自动更新 `deploy/static/releases/manifest.json`
|
||||
- 输出版本号、文件路径和 SHA256
|
||||
|
||||
注意：
|
||||
|
||||
- `versionName`（如 `0.1.0`）由开发者手动维护
|
||||
- `buildNumber`（如 `+2`）由打包脚本自动递增
|
||||
@@ -93,11 +93,13 @@ data: <json>
|
||||
|
||||
### 5.2 UI 编译器一致
|
||||
|
||||
两条链路都使用后端 `ui_compiler.compile(...)` 将 `ui_hints` 编译为可渲染结构：
|
||||
两条链路都使用后端 `ui_compiler.compile(...)` 将 **worker** 的 `ui_hints` 编译为可渲染结构：
|
||||
|
||||
- events：在 runtime 发送事件前编译，字段名为 `ui_schema`
|
||||
- history：在历史转换时编译，字段名为 `ui_schema`
|
||||
|
||||
tool 结果不再走 UI 编译链路：`TOOL_CALL_RESULT` 仅提供 `result`，并在持久化时写入 message `content`。
|
||||
|
||||
### 5.3 当前命名差异（实现现状）
|
||||
|
||||
两条链路字段命名已统一：
|
||||
|
||||
Reference in New Issue
Block a user