refactor: 重构 Tool Result 契约，移除 ui_hints 统一使用 result 字段

- ToolAgentOutput 移除 result_summary 和 ui_hints，统一使用 result 字段 - 日历/用户查找工具移除 ui_hints 输出，改为机器可读的结构化结果 - Agent History 移除 tool 消息的 ui_hints 处理逻辑 - App 版本检查改为 manifest.json 方式，支持多渠道发布 - 更新 settings 配置和测试用例适配新结构
2026-03-17 12:18:09 +08:00
parent c26cdbbc27
commit aa30fe0ce6
44 changed files with 984 additions and 655 deletions
@@ -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`）由打包脚本自动递增