magic-agent 1.0.111 → 2.1.5

package/CLIENT-CONTRACT.md

@@ -349,6 +349,8 @@ notice     {text:"团队模式：追加 N 个补充任务（a1、a2），继续
 | 产物文本回读 | `POST /desk/path-read`：`{path, base}` → `{ok:true, text, size, path}` / `{ok:true, tooBig:true, size}` / `{ok:true, binary:true, size}` / `{ok:false, error}`，统一 200。上限 512 KB；前 8000 字节含 NUL 判二进制；`~/`、`file://`、相对 `base` 同 `path-probe` 口径。移动端产物卡「查看」经 `window.desk.pathRead` 用它打开 Markdown / 文本 | 已实现 |
 | 插件目录 | `GET /desk/plugins` → `{plugins:[{id, name, cli, tagline, description, requirements?, homepage?, installed, version?, bin?, sourcePath?, sourceExists, install, upgrade, examples[], usePrompt, note?}]}`。**这不是引擎**（core 的 `--engines` 里没有它们）：它是「发现 → 插件」里那两个工程 CLI（`magic-shorts` / `magic-video`）的介绍与安装状态。`installed` / `version` 由服务端探测（`exec.LookPath` + 可执行文件所属 npm 包的 `package.json`，不跑 `--version`），客户端只显示不推断 | 已实现 |
 | 插件安装/升级 | `POST /desk/plugins/{id}/{install\|upgrade}` → SSE：`event: open`（`{id, action, commands[]}`）→ 每条命令 `event: step` → 输出逐行 `event: line` → `event: end`（`{ok, code, error?, plugin}`）。**命令只来自服务端那张固定表**（argv，不过 shell），客户端只传 id 与动作，未知 id/动作一律 404 —— 这条接口不接受客户端传命令 | 已实现 |
+| 移动端 APK 分发 | `GET /desk/app` → `{version, size, url}`（`version` 取自随包的 `npm/apk/version.json`，与 npm 包同一个版本号；没带 APK 时 `version` 为空串、`url` 为空）；`GET /desk/app.apk[?token=]` → 安装包本体（`application/vnd.android.package-archive`）。移动端「我的」→「版本」点一下先读前者，发现更高版本后由系统浏览器/安装器下载后者 | 已实现 |
+| 移动端环境配置 | `GET /desk/prefs` → 这台桌面的移动端配置 JSON（没存过是 `{}`）；`PUT /desk/prefs` 整份覆盖（≤256KB，原子写）。字段由移动端定义、桌面端原样存（`~/.magic-agent/mobile-prefs.json`），当前是「默认引擎/模型 + 团队配置 + 空间选择 + 置顶」。**多客户端连同一台桌面共用这一份** —— 不再是各存各的浏览器 localStorage | 已实现 |
 | 静态资源 | `GET /`（`--ui-dir` + profile 的 `ui.entry`） | 已实现 |
 | 鉴权 | `X-Magic-Token` 头或 `?token=`；默认只绑 `127.0.0.1`；`--lan` 时绑 `0.0.0.0` 且令牌强制 ≥24 字符（见 2.4） | 已实现 |
 
@@ -479,6 +481,18 @@ notice     {text:"团队模式：追加 N 个补充任务（a1、a2），继续
 用户要看的是「此刻连着的这份桌面端是哪一版」。老 core 没有该字段 → 空串，界面显示「—」，
 客户端不写死版本号。
 
+⚠️ **`/desk/health.version` 是插件启动时缓存的 core 版本**：只升级 CLI、没重启插件时它会
+一直报旧值（2026-10-22 实测：CLI 已 2.1.3，手机仍显示 1.0.111）。要显示「此刻真正的
+core 版本」必须读 `/desk/contract.version`（每次都重新问 core）；`health.version` 只适合
+当插件与 core 同一次安装、且不追求实时性的场景。移动端已改为 contract 优先、health 兜底。
+
+移动端自己的版本（2026-10-22，用户：「移动端版本跟着 npm 走」）：APK 的
+`versionName` 与 `magic-agent/package.json` 同一个版本号（构建脚本同步，见 magic-test 的
+`tools/build-mobile-apk.cjs`）。闸门页把版本用 `?appv=<x.y.z>` 带给远程界面，界面优先显示
+它；没有 `appv`（浏览器预览 / 旧闸门页）才回落到 `/desk/health.version`，两者不一致时把
+桌面端版本放进 `title`。点「版本」读 `/desk/app`，发现更高版本后触发 `/desk/app.apk`
+下载（系统浏览器/安装器接手，不静默安装）。
+
 关于 `permission` 的两条语义，客户端必须照做：
 
 1. **没选就原样不传，不要替 core 补默认值。** core 只在**显式传过** `--permission` 时