magic-agent 1.0.1 → 1.0.3

package/client-ui/shared/transport-http.js

@@ -0,0 +1,123 @@
+/* 传输层的一个**现成实现**：HTTP（打 magic-client 插件的 /desk/* 接口）。
+ *
+ *  ⚠️ 这是给「手上已经有一个 HTTP 端点」的对接方用的**可选件**，不是组件的一部分。
+ *    组件本身与传输无关（见 conversation.js 头部的 transport 契约）。
+ *    按定稿口径 magic-agent 自己不跑服务 —— 掌天瓶那种宿主应当自己实现一个走
+ *    IPC → CLI 的 transport（引擎清单/MAGIC 的 ask 与 control/会话历史都由 CLI 承担），
+ *    而不是让组件去连某个服务。
+ *
+ *  ── 这一份覆盖的接口（与 CLIENT-CONTRACT.md 第二章一致）──
+ *    GET  /desk/engines?models=1                      引擎 + 模型 + 每引擎能力
+ *    POST /desk/ask                                   SSE：open / 事件 / end
+ *    POST /desk/ask/{id}/control                      打断 / 收工 / 回答案
+ *    GET  /desk/session/{id}/messages                 全量历史
+ *    GET  /desk/session/{id}/events?after=<seq>       增量续读
+ *
+ *  ── 用法 ──
+ *    const transport = MagicTransportHttp({ base: '', token: '…' });   // 同源时 base 传空串
+ *    MagicConversation.create({ el, transport, … });
+ */
+(function () {
+  'use strict';
+
+  function MagicTransportHttp(opts) {
+    opts = opts || {};
+    var BASE = String(opts.base || '').replace(/\/+$/, '');
+    var TOKEN = opts.token || '';
+
+    function hdr(extra) {
+      var h = extra || {};
+      if (TOKEN) h['X-Magic-Token'] = TOKEN;
+      return h;
+    }
+    function api(path, o) {
+      o = o || {};
+      o.headers = hdr(o.headers);
+      if (o.json !== undefined) {
+        o.method = o.method || 'POST';
+        o.headers['Content-Type'] = 'application/json';
+        o.body = JSON.stringify(o.json);
+      }
+      return fetch(BASE + path, o).then(function (r) {
+        if (!r.ok) throw new Error(r.status + ' ' + r.statusText);
+        return r;
+      });
+    }
+
+    return {
+      /* 引擎清单：带模型（选择器要用），所以固定 ?models=1。 */
+      listEngines: function () {
+        return api('/desk/engines?models=1').then(function (r) { return r.json(); });
+      },
+
+      /* 一轮：把 SSE 拆成三个回调交给组件，组件不关心里面是 SSE 还是别的。 */
+      ask: function (payload, h) {
+        var aborted = false;
+        var ctl = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        var ended = false;
+        var finish = function (code) {
+          if (ended) return;
+          ended = true;
+          if (h && h.onEnd) h.onEnd(code);
+        };
+        api('/desk/ask', { json: payload, signal: ctl ? ctl.signal : undefined })
+          .then(function (resp) {
+            var reader = resp.body.getReader(), dec = new TextDecoder(), buf = '';
+            return (function pump() {
+              return reader.read().then(function (chunk) {
+                if (chunk.done) return finish(0);
+                buf += dec.decode(chunk.value, { stream: true });
+                var blocks = buf.split('\n\n');
+                buf = blocks.pop();
+                blocks.forEach(function (b) {
+                  var name = '', data = '';
+                  b.split('\n').forEach(function (ln) {
+                    if (ln.indexOf('event: ') === 0) name = ln.slice(7).trim();
+                    else if (ln.indexOf('data: ') === 0) data += ln.slice(6);
+                  });
+                  if (!data) return;
+                  var ev; try { ev = JSON.parse(data); } catch (e) { return; }
+                  if (name === 'open') {
+                    if (h && h.onOpen) h.onOpen(ev && (ev.id || ev.ask || ev.run));
+                    return;
+                  }
+                  if (name === 'end') { finish(ev && ev.code); return; }
+                  if (h && h.onEvent) h.onEvent(ev);
+                });
+                if (ended) return;
+                return pump();
+              });
+            })();
+          })
+          .catch(function (e) {
+            /* 被中止不算错（用户点了打断），别把它报成发送失败。 */
+            if (aborted) return finish(null);
+            if (h && h.onError) h.onError(e);
+            finish(null);
+          });
+        return { cancel: function () { aborted = true; if (ctl) ctl.abort(); } };
+      },
+
+      control: function (p) {
+        var body = { op: p.op };
+        if (p.text != null) body.text = p.text;
+        return api('/desk/ask/' + encodeURIComponent(p.id) + '/control', { json: body })
+          .then(function () { return true; });
+      },
+
+      readSession: function (id, o) {
+        o = o || {};
+        /* 有游标就走增量接口：长会话下差一个数量级。
+           形状与全量接口不同（多 lastSeq / snapshotRequired），一并原样交给组件。 */
+        if (o.after != null) {
+          return api('/desk/session/' + encodeURIComponent(id) + '/events?after=' + o.after)
+            .then(function (r) { return r.json(); });
+        }
+        return api('/desk/session/' + encodeURIComponent(id) + '/messages')
+          .then(function (r) { return r.json(); });
+      }
+    };
+  }
+
+  window.MagicTransportHttp = MagicTransportHttp;
+})();

package/client-ui-mobile/assets/OFL-Caveat.txt

@@ -0,0 +1,93 @@
+Copyright 2014 The Caveat Project Authors (https://github.com/googlefonts/caveat)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/client-ui-mobile/index.html

@@ -0,0 +1,173 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>掌天瓶 · 对话</title>
+<!--
+  移动端宿主：把**同一个**公共对话组件（shared/conversation.js）挂到页面上。
+  与 PC 那份是同一份实现 —— 差别只有两个：这个文件里的颜色令牌用的是
+  agents-anywhere 安卓端（Jetpack Compose）那套十六进制值，以及多了一条
+  移动端形态的顶栏。
+
+  ── 顶栏为什么还在宿主里 ──
+    组件只负责对话区（消息流 + 输入框 + 三项选择器）。标题栏、返回、主题这些
+    属于宿主形态，PC 与移动端的形态本来就不一样，塞进组件反而会让两边互相牵制。
+
+  ── 视觉基准（逐值抄自 AA 安卓端的 Compose 源码，不是目测）──
+    designsystem/Theme.kt        → 全部色令牌（暗色 canvas #09090B / 亮色 #FDFCFB 等）
+    SessionDetailScreen.kt       → 顶栏 BackIconButton / TitlePill 的尺寸
+    对话区本身（气泡 / markdown / 工具卡 / 思考块 / 审批卡）在共享组件里，
+    那里同样标了对应的 Compose 行号。
+
+  ── 公共组件在哪 ──
+    对话区在 ../client-ui/shared/ 下（PC 与移动端同一份实现）。这一页**按同级
+    路径 shared/ 引用**：打包时由 magic-test 的 tools/build-mobile-www.cjs 把
+    client-ui/shared 一起复制进 www/shared —— 所以产物里是这个相对关系。
+    直接拿浏览器开这个文件时，请让静态服务器同时暴露 client-ui-mobile/ 与
+    client-ui/shared（或在临时目录里拼出同样的同级关系），否则共享模块会 404。
+-->
+<link rel="stylesheet" href="shared/conversation.css">
+<style>
+/* ===== 令牌：AA 安卓端那一套，映射到共享组件的颜色契约 =====
+   ⚠️ 默认 = 暗色：跟 anywhere 的 DarkAgentsAnywhereColors 逐字段对齐。
+   用户在系统里选了亮色才切亮色（没设主题时不会莫名跑出白底）。 */
+:root{
+  color-scheme:dark;
+  --canvas:#09090B;
+  --ink:#FAFAFA; --ink-soft:#E5E5E5; --muted:#A3A3A3; --faint:#737373;
+  --border:rgba(255,255,255,.09); --subtle:#292929; --raised:#1F1F1F;
+  --primary-action:#FAFAFA; --on-primary-action:#09090B;
+  --app-shadow:rgba(0,0,0,.32);
+
+  --bubble:#2A2A2A; --bubble-text:#F4F4F5;
+  --code:#111113; --status-neutral:#2D2D2D; --status-neutral-text:#D4D4D8;
+  --activity:rgba(24,24,27,.063);
+
+  --md-body:#EDEDEF; --md-muted:#A1A1AA; --md-border:#27272A; --md-code-bg:#292929;
+  --link:#EBB353; --prompt:#E8798F; --shimmer:#FFFFFF;
+  --panel:#1F1F1F; --panel-border:#27272A;
+
+  --accent:#39A887; --warning:#F59E0B; --success:#22C55E;
+  --error-surface:#2A1214; --error-border:#5F2429; --error-text:#FCA5A5; --error-icon:#F97066;
+  --running:#10B981; --transitioning:#3B82F6; --active:#F59E0B;
+
+  /* 移动端沿用 AA 的三档圆角（18 / 12 / full），与 Compose 规格一致 */
+  --r-card:18px; --r:12px; --r-full:999px;
+  --font:-apple-system,BlinkMacSystemFont,"PingFang SC","Noto Sans CJK SC",system-ui,sans-serif;
+  --mono:ui-monospace,SFMono-Regular,Menlo,"SF Mono",monospace;
+}
+@media (prefers-color-scheme:light){
+  :root{
+    color-scheme:light;
+    --canvas:#FDFCFB;
+    --ink:#0A0A0B; --ink-soft:#2B2B2B; --muted:#777777; --faint:#AAA8A2;
+    --border:#E7E5E0; --subtle:#F1F0ED; --raised:#FFFFFF;
+    --primary-action:#0A0A0B; --on-primary-action:#FFFFFF;
+    --app-shadow:rgba(0,0,0,.13);
+    --bubble:#F1F0ED; --bubble-text:#242522;
+    --code:rgba(255,255,255,.72); --status-neutral:#E4E2DD; --status-neutral-text:#6F6E69;
+    --activity:rgba(241,240,237,.08);
+    --md-body:#242522; --md-muted:#7C7B76; --md-border:#E4E1DB; --md-code-bg:#F1F0ED;
+    --link:#EBB353; --prompt:#C45D74; --shimmer:#000000;
+    --panel:#ECECEA; --panel-border:transparent;
+    --accent:#18866A; --warning:#D97706; --success:#16A34A;
+    --error-surface:#FFF4F4; --error-border:#F4C7C7; --error-text:#B42318; --error-icon:#B42318;
+  }
+}
+
+*{box-sizing:border-box;-webkit-tap-highlight-color:transparent}
+/* ⚠️ 锁死视口高度而不是 min-height：用 min-height 时 body 会被内容撑高，
+   滚动条落到 document 上，.conv__thread 的 overflow-y:auto 就永远不触发 ——
+   后果是打开会话看不到顶部，也做不了「回到底部」。 */
+html,body{margin:0;height:100%;overflow:hidden}
+body{background:var(--canvas);color:var(--ink);font:15px/1.45 var(--font);
+     overscroll-behavior:none;display:flex;flex-direction:column}
+button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:pointer}
+svg{display:block}
+
+/* ── 顶栏 SessionDetailScreen：BackIconButton 40dp 圆 · TitlePill 34dp 胶囊 ── */
+.detailbar{display:grid;grid-template-columns:40px 1fr 40px;align-items:center;gap:8px;
+  padding:calc(env(safe-area-inset-top) + 10px) 16px 8px;flex:0 0 auto}
+.iconbtn{width:40px;height:40px;border-radius:var(--r-full);display:flex;align-items:center;
+  justify-content:center;background:var(--raised);color:var(--ink);border:1px solid var(--border)}
+.titlepill{justify-self:center;max-width:100%;height:34px;display:flex;align-items:center;
+  padding:0 14px;border:1px solid var(--border);border-radius:var(--r-full);background:var(--raised);
+  font-size:14px;font-weight:600;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+
+/* 组件挂载点：占满剩余高度 */
+#conv{flex:1;min-height:0;display:flex}
+
+/* 挂载失败时说明原因，而不是留一片空白 */
+.boot-err{margin:16px;padding:14px;border-radius:14px;background:var(--error-surface);
+  border:1.2px solid var(--error-border);color:var(--error-text);font-size:13.5px;line-height:1.55}
+
+/* 底部安全区：iPhone 的 home indicator 会压住输入框 */
+.composer{padding-bottom:calc(16px + env(safe-area-inset-bottom))}
+
+@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
+</style>
+</head>
+<body>
+
+<svg width="0" height="0" style="position:absolute" aria-hidden="true">
+  <symbol id="i-back" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 5 8 12l7 7"/></symbol>
+  <symbol id="i-plus" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5.5v13M5.5 12h13"/></symbol>
+</svg>
+
+<div class="detailbar">
+  <button class="iconbtn" id="btnNew" aria-label="新会话"><svg width="20" height="20"><use href="#i-plus"/></svg></button>
+  <span class="titlepill" id="title">新会话</span>
+  <span></span>
+</div>
+<div id="conv"></div>
+
+<script src="shared/conversation.js"></script>
+<script src="shared/transport-http.js"></script>
+<script>
+(function () {
+  'use strict';
+
+  /* 基址与令牌：两种宿主。
+     · 打包进 App（Capacitor）：页面是本地文件，地址与令牌由 boot.js 从配对信息注入 ——
+       那时 window.MAGIC_BASE 非空，所有 /desk/* 请求要前缀到桌面地址上；
+     · 浏览器同源打开（调试）：不带 MAGIC_BASE，token 在 ?token= 上。 */
+  var TOKEN = window.MAGIC_TOKEN || new URLSearchParams(location.search).get('token') || '';
+  var BASE = (window.MAGIC_BASE || '').replace(/\/+$/, '');
+
+  var titleEl = document.getElementById('title');
+
+  function showBootError(msg) {
+    var d = document.createElement('div');
+    d.className = 'boot-err';
+    d.textContent = msg;
+    document.getElementById('conv').appendChild(d);
+  }
+
+  /* 打包进 App 时页面在本地（capacitor://localhost 或 file://），
+     不能直接 fetch 本地相对路径 —— 下面这层把 <img src> 之类的相对资源
+     前缀成桌面地址。与 boot.js 的垫片同一思路，只是这里组件不产生 img，
+     所以只需要保证 fetch 走 BASE（组件已按 opts.base 处理）。 */
+
+  var conv = null;
+  (async function boot() {
+    try {
+      /* 传输层由宿主注入 —— 组件本身不连后端。
+         打包进 App 时这里会换成「走自己后端」的实现；当前先用 HTTP 参考件。 */
+      var transport = window.MagicTransportHttp({ base: BASE, token: TOKEN });
+      conv = window.MagicConversation.create({
+        el: document.getElementById('conv'),
+        transport: transport,
+        titleEl: titleEl,
+      });
+      document.getElementById('btnNew').onclick = function () { conv.newSession(); };
+      /* 供对接方/调试取用：window.magicConv.setSession(sid) 换会话 */
+      window.magicConv = conv;
+    } catch (e) {
+      showBootError('对话组件挂载失败：' + (e && e.message ? e.message : e));
+    }
+  })();
+})();
+</script>
+</body>
+</html>

package/internal/agent/custom_models.go

@@ -18,10 +18,17 @@ package agent
 // 归谁所有：models.json 是 **CLI 自己的**配置文件（CLI 的 models 控制器会读写它）。
 // 所以这里只做**合并**：只补缺失的 id，不删、不改、不动其它字段；无新增时不落盘
 //（避免无谓写盘与 mtime 抖动）。App 缓存一律只读。
+//
+// ⚠️ 硬约束（2026-09-30 补）：目标文件**必须是顶层 JSON 对象**才动它。桌面端
+// WorkBuddy 自己那份 `models.json` 顶层是**数组**（LanguageModel[]），与 CLI 的
+// `{availableModels, models}` 不是同一个格式。若把数组当"解析失败的空文件"整体写回，
+// 就是把对方的模型清单替换成只剩 custom-local 几条 —— 官方模型全丢且不可回滚。
+// 撞上这种文件一律**跳过并在 stderr 说明**；覆盖写之前另留 `.magic-agent.bak` 原文。
 
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
@@ -32,6 +39,10 @@ import (
 // customModelsFileName CLI 读自定义模型端点的文件名（见 CLI 的 getModelsPath）。
 const customModelsFileName = "models.json"
 
+// customModelsBackupSuffix 覆盖写之前留的原文备份后缀。
+// 一次误写就能把模型清单清空，留一份可回滚的东西。
+const customModelsBackupSuffix = ".magic-agent.bak"
+
 // customModelIDPrefix 自定义模型 id 前缀（App 与 CLI 共用这个约定）。
 const customModelIDPrefix = "custom-local:"
 
@@ -53,15 +64,29 @@ func syncCustomModelsFromApp(accConfigPath, configDir string) (int, error) {
 	}
 
 	path := filepath.Join(configDir, customModelsFileName)
+	var raw0 []byte // 改动前的原文（覆盖写之前留备份）
 	root := map[string]any{}
 	switch b, err := os.ReadFile(path); {
 	case err == nil:
-		// 解析失败就当空文件：CLI 自己也会这么兜（readModelsJson 失败返回 {models:[]}）。
-		// 但**不覆盖**未识别的字段 —— 解析失败时下面只会写回 models/availableModels。
-		_ = json.Unmarshal(b, &root)
-		if root == nil {
-			root = map[string]any{}
+		raw0 = b
+		/* ⚠️ 只有**顶层是 JSON 对象**才认作 CLI 的 models.json。
+		   桌面端（WorkBuddy）自己那份 models.json 顶层是**数组**（LanguageModel[]），
+		   数组解析不进 map[string]any。以前这里把"解析失败"当空文件继续写回
+		   {models, availableModels} —— 对数组格式来说那等于把对方的模型清单**整体替换**掉：
+		   官方模型全没了，且不可恢复（原注释里"解析失败时不覆盖未识别的字段"对数组不成立，
+		   数组根本装不下未知字段）。这种文件不是 CLI 的格式，一律不动。 */
+		var doc any
+		if err := json.Unmarshal(b, &doc); err != nil {
+			fmt.Fprintf(os.Stderr, "magic-agent: 跳过自定义模型端点同步：%s 不是合法 JSON（保持原文件不动）\n", path)
+			return 0, nil
+		}
+		m, ok := doc.(map[string]any)
+		if !ok {
+			fmt.Fprintf(os.Stderr, "magic-agent: 跳过自定义模型端点同步：%s 顶层不是 JSON 对象"+
+				"（该文件不是 CLI 的 models.json 格式，覆盖写会毁掉里面的模型清单；保持原文件不动）\n", path)
+			return 0, nil
 		}
+		root = m
 	case errors.Is(err, fs.ErrNotExist):
 		// 首次同步：新建
 	default:
@@ -126,6 +151,10 @@ func syncCustomModelsFromApp(accConfigPath, configDir string) (int, error) {
 		return 0, err
 	}
 	// 含第三方 apiKey：与 CLI 自身凭据同级（仅属主可读）。
+	// 覆盖写之前留一份原文备份：一次误写就能清空模型清单，必须可回滚。
+	if len(raw0) > 0 {
+		_ = os.WriteFile(path+customModelsBackupSuffix, raw0, 0o600)
+	}
 	if err := os.WriteFile(path, b, 0o600); err != nil {
 		return 0, err
 	}
@@ -195,3 +224,120 @@ func (c codebuddyCore) effectiveConfigDir() string {
 	}
 	return c.configDir
 }
+
+// ── 事故还原：把被覆盖写坏的桌面端 models.json 修回来 ──────────
+//
+// 背景（2026-09-30 Windows 事故）：Windows 上 CODEBUDDY_CONFIG_DIR 可能指向桌面端
+// 数据目录，于是上面的同步把桌面端那份**数组格式**的 models.json 覆盖成了
+// `{availableModels, models}` 对象格式。桌面端解析不了 → 模型清单整个为空，
+// 用户看到「WorkBuddy 的模型都丢失了」。
+//
+// 还原依据（实测比对同一台机器上的两份文件）：
+//
+//	桌面端数组条目   {id:"MiniMax-M3",   name, vendor, url, apiKey, ...}
+//	我们写的对象条目 {id:"custom-local:MiniMax-M3", name, vendor, url, apiKey, ...}
+//
+// 即**同一批条目、id 差一个 custom-local: 前缀**。所以还原 = 把对象里的 models[]
+// 原样搬成数组，只去掉 id 前缀。官方模型清单不在这个文件里（那是 product.json /
+// acc 缓存的事，桌面端自己拉），所以这里不需要、也不该造官方条目。
+
+// DesktopAppHomeOf 返回引擎对应的桌面端数据目录名（空 = 该引擎没有桌面端）。
+func DesktopAppHomeOf(engine string) string {
+	switch strings.ToLower(strings.TrimSpace(engine)) {
+	case "codebuddy":
+		return ".workbuddy"
+	case "codebuddy-ai":
+		return ".workbuddy-ai"
+	}
+	return ""
+}
+
+// DesktopEngines 列出有桌面端数据目录的引擎（`--repair-models` 的可用值，供提示与校验共用）。
+func DesktopEngines() []string { return []string{"codebuddy", "codebuddy-ai"} }
+
+// RepairDesktopModels 修复被反向同步写坏的桌面端 models.json。
+// 返回（是否真的做了修复, 给人看的说明, 错误）。没有可修的东西时返回 (false, 说明, nil)。
+func RepairDesktopModels(engine string) (bool, string, error) {
+	home := DesktopAppHomeOf(engine)
+	if home == "" {
+		return false, "", fmt.Errorf(
+			"引擎 %q 没有对应的桌面端数据目录，没有可修的 models.json（支持：%s）",
+			strings.TrimSpace(engine), strings.Join(DesktopEngines(), " / "))
+	}
+	dir, err := os.UserHomeDir()
+	if err != nil || dir == "" {
+		dir = os.Getenv("HOME")
+	}
+	if dir == "" {
+		return false, "", fmt.Errorf("定位用户目录失败，无法找到桌面端 models.json")
+	}
+	return repairModelsFile(filepath.Join(dir, home))
+}
+
+// repairModelsFile 就地把 appHome/models.json 从「被覆盖写的对象」还原成桌面端数组。
+//
+// 只认**明确的坏形状**（顶层对象 + models[] 全是 custom-local:* 条目）才动手：
+// 已经是数组、不是合法 JSON、或形状不认识，一律原样不动并说明原因。
+func repairModelsFile(appHome string) (bool, string, error) {
+	path := filepath.Join(appHome, customModelsFileName)
+	b, err := os.ReadFile(path)
+	switch {
+	case errors.Is(err, fs.ErrNotExist):
+		return false, fmt.Sprintf("%s 不存在，无需修复", path), nil
+	case err != nil:
+		return false, "", err
+	}
+
+	var doc any
+	if uerr := json.Unmarshal(b, &doc); uerr != nil {
+		return false, fmt.Sprintf("%s 不是合法 JSON，形状对不上，未改动", path), nil
+	}
+	if _, isArr := doc.([]any); isArr {
+		return false, fmt.Sprintf("%s 已是桌面端的数组格式，无需修复", path), nil
+	}
+	root, ok := doc.(map[string]any)
+	if !ok {
+		return false, fmt.Sprintf("%s 顶层既不是数组也不是对象，未改动", path), nil
+	}
+	raw, _ := root["models"].([]any)
+	if len(raw) == 0 {
+		return false, fmt.Sprintf("%s 里没有 models 数组，不像被我们覆盖写的形状，未改动", path), nil
+	}
+
+	out := make([]any, 0, len(raw))
+	for _, it := range raw {
+		m, ok := it.(map[string]any)
+		if !ok {
+			return false, fmt.Sprintf("%s 的 models 里混有非对象条目，未改动", path), nil
+		}
+		id, _ := m["id"].(string)
+		if !strings.HasPrefix(id, customModelIDPrefix) {
+			return false, fmt.Sprintf("%s 的 models 里混有非 %s 条目（可能不是我们写坏的），未改动",
+				path, customModelIDPrefix), nil
+		}
+		cp := make(map[string]any, len(m))
+		for k, v := range m {
+			cp[k] = v
+		}
+		cp["id"] = strings.TrimPrefix(id, customModelIDPrefix)
+		out = append(out, cp)
+	}
+
+	nb, merr := json.MarshalIndent(out, "", "  ")
+	if merr != nil {
+		return false, "", merr
+	}
+	nb = append(nb, '\n')
+
+	// 先把现场（被写坏的那份）留一份，再落盘。
+	broken := path + ".broken.bak"
+	if werr := os.WriteFile(broken, b, 0o600); werr != nil {
+		return false, "", fmt.Errorf("写备份 %s 失败: %w", broken, werr)
+	}
+	if werr := os.WriteFile(path, nb, 0o600); werr != nil {
+		return false, "", werr
+	}
+	return true, fmt.Sprintf(
+		"已还原 %s：%d 条自定义模型改回桌面端的数组格式（id 去掉 %s 前缀）；原文件备份在 %s",
+		path, len(out), customModelIDPrefix, broken), nil
+}