magic-agent 1.0.2 → 1.0.46

package/internal/agent/codex_test.go

@@ -63,6 +63,30 @@ func TestCodexBuildArgsModel(t *testing.T) {
 	}
 }
 
+// 续接轮的模型不能走 `-m`：`codex exec resume` 的参数表里没有它（同 `-C` 一样会被 clap
+// 以 `unexpected argument` 拒掉、exit 2、stdout 全空 → core 报「empty result · 0.0s」）。
+// 改为配置覆写 `-c model="<m>"` —— codex 帮助里正是拿 model 当 `-c` 的例子。
+func TestCodexResumeModelViaConfigOverride(t *testing.T) {
+	dir := t.TempDir()
+	w, log := argsCaptureCLI(t, dir, "codex", codexStubWithText("ok"))
+	e := &CodexEngine{BinPath: w.bin}
+	if _, err := e.Complete(context.Background(), Request{
+		SessionID: "th-1",
+		Model:     "codex/MiniMax-M3",
+		Messages:  []Message{{Role: "user", Content: "继续"}},
+	}); err != nil {
+		t.Fatalf("Complete: %v", err)
+	}
+	data, _ := readFile(log)
+	args := string(data)
+	if strings.Contains(args, "-m MiniMax-M3") {
+		t.Errorf("续接轮不该用 -m（resume 子命令没有这个 flag）：%q", args)
+	}
+	if !strings.Contains(args, `-c model="MiniMax-M3"`) {
+		t.Errorf("续接轮的模型应走 -c model=…：%q", args)
+	}
+}
+
 func TestCodexSystemPrompt(t *testing.T) {
 	dir := t.TempDir()
 	w, log := argsCaptureCLI(t, dir, "codex", codexStubWithText("ok"))

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,9 +39,38 @@ import (
 // customModelsFileName CLI 读自定义模型端点的文件名（见 CLI 的 getModelsPath）。
 const customModelsFileName = "models.json"
 
+// customModelsBackupSuffix 覆盖写之前留的原文备份后缀。
+// 一次误写就能把模型清单清空，留一份可回滚的东西。
+const customModelsBackupSuffix = ".magic-agent.bak"
+
 // customModelIDPrefix 自定义模型 id 前缀（App 与 CLI 共用这个约定）。
 const customModelIDPrefix = "custom-local:"
 
+// StripCustomLocalPrefix 去掉模型 id 的 "custom-local:" 前缀（仅用于 --engines / --contract
+// 展示：codebuddy 系模型的噪点前缀，给客户端渲染用）。-m 实际传值时由
+// codebuddyCore.modelArg 按裸名补回前缀，自定义模型依旧可用（见该函数的说明）。
+// 不修改入参，返回新切片。
+func StripCustomLocalPrefix(models []string) []string {
+	out := make([]string, 0, len(models))
+	for _, m := range models {
+		out = append(out, strings.TrimPrefix(m, customModelIDPrefix))
+	}
+	return out
+}
+
+// StripCustomLocalPrefixCredits 同 StripCustomLocalPrefix，但作用于「模型 → 倍率」表。
+// custom-local 模型本来就没有倍率（不进表），这里只为键名形态与 models 一致。
+func StripCustomLocalPrefixCredits(credits map[string]string) map[string]string {
+	if len(credits) == 0 {
+		return credits
+	}
+	out := make(map[string]string, len(credits))
+	for k, v := range credits {
+		out[strings.TrimPrefix(k, customModelIDPrefix)] = v
+	}
+	return out
+}
+
 // syncCustomModelsFromApp 把 App 合并配置缓存（acc-product-config）里的
 // `custom-local:*` 模型合并进 `<configDir>/models.json`，返回新增条数。
 //
@@ -53,15 +89,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 +176,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
 	}
@@ -178,15 +232,96 @@ func collectCustomModels(node any, out map[string]map[string]any) {
 // ensureCustomModelEndpoint 仅当本次请求用的是一个自定义模型时，才补一次端点。
 //
 // 为什么不止在 listModels 里同步：用户可能在 App 里刚加了一个自定义模型，就直接
-// `-m custom-local:<新>` 调用（没打开过模型选择器）。这条兜底让那种路径也能用上。
-// best-effort：不同步失败也不影响正常模型（官方模型根本不读 models.json）。
+// `-m custom-local:<新>` 或 `-m <裸名>` 调用（没打开过模型选择器）。这条兜底让那种
+// 路径也能用上。best-effort：不同步失败也不影响正常模型（官方模型根本不读 models.json）。
 func (c codebuddyCore) ensureCustomModelEndpoint(model string) {
-	if !strings.HasPrefix(model, customModelIDPrefix) {
+	m := stripModelPrefix(model)
+	// 已是 custom-local: 前缀（用户直传全 id），或裸名命中自定义模型 → 需要补端点。
+	if !strings.HasPrefix(m, customModelIDPrefix) && c.resolveCustomModelID(model) == "" {
 		return
 	}
 	_, _ = syncCustomModelsFromApp(c.accConfigPath, c.effectiveConfigDir())
 }
 
+// resolveCustomModelID 把可能带 "engine/" 或 "custom-local:" 前缀的模型名归一成
+// 自定义模型 id（"custom-local:<裸名>"）。裸名命中 acc 缓存里的自定义模型、且**不是**
+// 同缓存里的官方模型时才补回前缀 —— 避免把官方模型（如 glm-5.3）误改写成
+// custom-local:glm-5.3（用户自定义了一个同名模型时的退化处理：优先官方）。
+// 命中返回该 id，否则返回 ""（不是自定义模型，不补前缀）。
+//
+// 用途：--engines 展示时剥掉了 custom-local: 前缀（见 StripCustomLocalPrefix），用户
+// 选了之后回传的是裸名；-m 需要带前缀才能真正命中自定义模型端点，故在此补回。
+func (c codebuddyCore) resolveCustomModelID(model string) string {
+	name := stripModelPrefix(model)
+	name = strings.TrimPrefix(name, customModelIDPrefix)
+	if name == "" {
+		return ""
+	}
+	customID := customModelIDPrefix + name
+	// 同份 acc 缓存里递归收集全部 id（含嵌套、官方与 custom-local:*）：裸名若也是官方模型，
+	// 优先官方、不补前缀；仅当它是「纯自定义」（无同名官方）时才补回 custom-local:。
+	all := readAllAccModelIDs(c.accConfigPath)
+	if all[customID] && !all[name] {
+		return customID
+	}
+	return ""
+}
+
+// collectAllModelIDs 递归遍历 acc 配置缓存，收集所有模型的 id（官方与 custom-local:*
+// 都收，先到先得）。acc 缓存里官方模型常常嵌在嵌套结构里，故必须递归而非只读顶层。
+func collectAllModelIDs(node any, out map[string]bool) {
+	switch v := node.(type) {
+	case map[string]any:
+		if id, ok := v["id"].(string); ok && id != "" {
+			out[id] = true
+		}
+		for _, child := range v {
+			collectAllModelIDs(child, out)
+		}
+	case []any:
+		for _, child := range v {
+			collectAllModelIDs(child, out)
+		}
+	}
+}
+
+// readAllAccModelIDs 返回 acc 配置缓存里出现过的全部模型 id 集合（递归，不区分官方 / 自定义）。
+// 文件不存在 / 解析失败 → 空集。
+func readAllAccModelIDs(accConfigPath string) map[string]bool {
+	out := map[string]bool{}
+	if accConfigPath == "" {
+		return out
+	}
+	b, err := os.ReadFile(accConfigPath)
+	if err != nil {
+		return out
+	}
+	var doc any
+	if err := json.Unmarshal(b, &doc); err != nil {
+		return out
+	}
+	collectAllModelIDs(doc, out)
+	return out
+}
+
+// modelArg 返回传给 CLI --model 的值。
+//
+// --engines 展示时剥掉了 custom-local: 前缀（见 StripCustomLocalPrefix），用户选了
+// 自定义模型后回传裸名；这里命中自定义模型就补回 custom-local: 前缀，保证 -m 可用。
+func (c codebuddyCore) modelArg(model string) string {
+	m := stripModelPrefix(model)
+	if m == "" {
+		return ""
+	}
+	if strings.HasPrefix(m, customModelIDPrefix) {
+		return m
+	}
+	if id := c.resolveCustomModelID(m); id != "" {
+		return id
+	}
+	return m
+}
+
 // effectiveConfigDir 本次子进程实际使用的配置目录：用户显式设了 CODEBUDDY_CONFIG_DIR
 // 就跟着走（CLI 也这么读，见 codebuddyAccountEnv），否则用引擎自带的那个。
 func (c codebuddyCore) effectiveConfigDir() string {
@@ -195,3 +330,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
+}

package/internal/agent/custom_models_test.go

@@ -9,8 +9,11 @@ package agent
 //  2. 幂等：无新增时**不落盘**（内容逐字节不变）
 //  3. 只增不改：既有条目与未识别字段原样保留；availableModels 追加不丢
 //  4. 安全兜底：App 缓存缺失 / 条目 disabled → 不建文件、不报错
+//  5. 陌生文件一律不碰：顶层不是 JSON 对象（桌面端是数组）/ 坏 JSON → 逐字节保持原样，
+//     且覆盖写之前一定留 .magic-agent.bak（见 2026-09-30 Windows 事故用例）
 
 import (
+	"bytes"
 	"encoding/json"
 	"os"
 	"path/filepath"
@@ -53,6 +56,80 @@ func appCacheFixture() map[string]any {
 	}
 }
 
+// StripCustomLocalPrefix 剥掉自定义模型 id 的 "custom-local:" 前缀（仅展示用）。
+func TestStripCustomLocalPrefix(t *testing.T) {
+	got := StripCustomLocalPrefix([]string{"hy3", "custom-local:MiniMax-M3", "custom-local:glm-5.3"})
+	want := []string{"hy3", "MiniMax-M3", "glm-5.3"}
+	if len(got) != len(want) {
+		t.Fatalf("StripCustomLocalPrefix = %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("StripCustomLocalPrefix[%d] = %q want %q (full %v)", i, got[i], want[i], got)
+		}
+	}
+	c := StripCustomLocalPrefixCredits(map[string]string{"hy3": "0.00", "custom-local:X": "0.34"})
+	if c["custom-local:X"] != "" || c["X"] != "0.34" || c["hy3"] != "0.00" {
+		t.Errorf("StripCustomLocalPrefixCredits = %v", c)
+	}
+}
+
+// resolveCustomModelID：裸名命中纯自定义模型时补回 custom-local: 前缀；
+// 裸名同时是官方模型时**不补**（优先官方，避免把 glm-5.3 误写成 custom-local:glm-5.3）。
+func TestResolveCustomModelID(t *testing.T) {
+	dir := t.TempDir()
+	acc := filepath.Join(dir, "acc.json")
+	writeJSON(t, acc, map[string]any{"models": []any{
+		map[string]any{"id": "glm-5.3"},
+		map[string]any{"id": "custom-local:MiniMax-M3"},
+		// 嵌套结构里的官方模型也要能识别（readAllAccModelIDs 递归收集）。
+		map[string]any{"wrapped": map[string]any{"id": "deepseek-v4.1-flash"}},
+	}})
+	c := codebuddyCore{accConfigPath: acc}
+
+	if got := c.resolveCustomModelID("MiniMax-M3"); got != "custom-local:MiniMax-M3" {
+		t.Errorf("resolve MiniMax-M3 = %q want custom-local:MiniMax-M3", got)
+	}
+	if got := c.resolveCustomModelID("glm-5.3"); got != "" {
+		t.Errorf("resolve glm-5.3 = %q want \"\"（优先官方模型，不补前缀）", got)
+	}
+	// 已带前缀：原样返回。
+	if got := c.resolveCustomModelID("custom-local:MiniMax-M3"); got != "custom-local:MiniMax-M3" {
+		t.Errorf("resolve custom-local:MiniMax-M3 = %q", got)
+	}
+	// 既不是官方也不是自定义 → 不补。
+	if got := c.resolveCustomModelID("nonexistent-model"); got != "" {
+		t.Errorf("resolve nonexistent = %q want \"\"", got)
+	}
+}
+
+// modelArg：传给 CLI --model 的值。展示时剥了前缀的自定义模型裸名要补回前缀。
+func TestCodeBuddyModelArg(t *testing.T) {
+	dir := t.TempDir()
+	acc := filepath.Join(dir, "acc.json")
+	writeJSON(t, acc, map[string]any{"models": []any{
+		map[string]any{"id": "glm-5.3"},
+		map[string]any{"id": "custom-local:MiniMax-M3"},
+	}})
+	c := codebuddyCore{accConfigPath: acc}
+
+	cases := []struct {
+		in, want string
+	}{
+		{"hy3", "hy3"},                                         // 官方：原样
+		{"codebuddy/hy3", "hy3"},                               // 带 engine/ 前缀：剥掉
+		{"glm-5.3", "glm-5.3"},                                 // 同名官方：不补前缀
+		{"MiniMax-M3", "custom-local:MiniMax-M3"},              // 自定义裸名：补前缀
+		{"custom-local:MiniMax-M3", "custom-local:MiniMax-M3"}, // 已带前缀：原样
+		{"", ""}, // 空：空
+	}
+	for _, tc := range cases {
+		if got := c.modelArg(tc.in); got != tc.want {
+			t.Errorf("modelArg(%q) = %q want %q", tc.in, got, tc.want)
+		}
+	}
+}
+
 func TestSyncCustomModelsFromApp_FirstSync(t *testing.T) {
 	dir := t.TempDir()
 	acc := filepath.Join(dir, "acc-product-config-v3.json")
@@ -182,11 +259,112 @@ func TestSyncCustomModelsFromApp_IdempotentAndMergeOnly(t *testing.T) {
 	}
 }
 
-func TestSyncCustomModelsFromApp_NoSourceNoFile(t *testing.T) {
+// 目标文件顶层不是 JSON 对象（桌面端 WorkBuddy 的 models.json 就是**数组**）时，
+// 必须**一个字都不动**、也不留备份（因为压根没写）。
+//
+// 为什么是关键回归：以前把"解析不进 map"当空文件继续写回 {models, availableModels}，
+// 等于把对方的模型清单整体替换成只剩 custom-local 几条 —— 官方模型全丢且不可回滚。
+func TestSyncCustomModelsFromApp_RefusesNonObjectFile(t *testing.T) {
+	// 桌面端 models.json 的真实形状：顶层数组，条目是 LanguageModel。
+	desktop := []byte(`[
+  {
+    "id": "MiniMax-M3",
+    "name": "MiniMax-M3",
+    "vendor": "MiniMax",
+    "url": "https://api.minimaxi.com/v1/chat/completions",
+    "apiKey": "sk-user-own"
+  },
+  {
+    "id": "glm-5.3",
+    "name": "glm-5.3",
+    "url": "https://open.bigmodel.cn/api/paas/v4",
+    "apiKey": "sk-user-own-2"
+  }
+]`)
+
+	cases := []struct {
+		name    string
+		content []byte
+	}{
+		{"顶层是数组（桌面端格式）", desktop},
+		{"坏 JSON", []byte("{oops")},
+		{"顶层是字符串", []byte(`"just a string"`)},
+		{"顶层是数字", []byte(`42`)},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			acc := filepath.Join(dir, "acc.json")
+			writeJSON(t, acc, appCacheFixture())
+			cfg := filepath.Join(dir, "config")
+			if err := os.MkdirAll(cfg, 0o700); err != nil {
+				t.Fatal(err)
+			}
+			path := filepath.Join(cfg, customModelsFileName)
+			if err := os.WriteFile(path, tc.content, 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			added, err := syncCustomModelsFromApp(acc, cfg)
+			if err != nil {
+				t.Errorf("应静默跳过，不该报错: %v", err)
+			}
+			if added != 0 {
+				t.Errorf("added = %d, want 0", added)
+			}
+
+			after, err := os.ReadFile(path)
+			if err != nil {
+				t.Fatalf("原文件必须还在: %v", err)
+			}
+			if !bytes.Equal(after, tc.content) {
+				t.Errorf("原文件被改写了！\nbefore=%s\nafter =%s", tc.content, after)
+			}
+			if _, err := os.Stat(path + customModelsBackupSuffix); !os.IsNotExist(err) {
+				t.Errorf("没写就不该留备份")
+			}
+		})
+	}
+}
+
+// 真的要覆盖写时，必须先把原文留成 <models.json>.magic-agent.bak（可回滚）。
+func TestSyncCustomModelsFromApp_BacksUpBeforeOverwrite(t *testing.T) {
 	dir := t.TempDir()
+	acc := filepath.Join(dir, "acc.json")
+	writeJSON(t, acc, appCacheFixture())
 	cfg := filepath.Join(dir, "config")
+	if err := os.MkdirAll(cfg, 0o700); err != nil {
+		t.Fatal(err)
+	}
 	path := filepath.Join(cfg, customModelsFileName)
 
+	before := []byte("{\n  \"models\": [],\n  \"availableModels\": [\"hy3\"]\n}\n")
+	if err := os.WriteFile(path, before, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	added, err := syncCustomModelsFromApp(acc, cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if added == 0 {
+		t.Fatal("本次应有新增（触发落盘）")
+	}
+
+	bak, err := os.ReadFile(path + customModelsBackupSuffix)
+	if err != nil {
+		t.Fatalf("覆盖写之前应留备份: %v", err)
+	}
+	if !bytes.Equal(bak, before) {
+		t.Errorf("备份内容应为改动前的原文\nwant=%s\ngot =%s", before, bak)
+	}
+}
+
+func TestSyncCustomModelsFromApp_NoSourceNoFile(t *testing.T) {
+	dir := t.TempDir()
+	cfg := filepath.Join(dir, "config")
+	path := filepath.Join(cfg, customModelsFileName)
 	cases := []struct{ name, acc string }{
 		{"acc 路径为空", ""},
 		{"acc 文件不存在", filepath.Join(dir, "nope.json")},
@@ -221,7 +399,17 @@ func TestSyncCustomModelsFromApp_NoSourceNoFile(t *testing.T) {
 	}
 }
 
-func TestSyncCustomModelsFromApp_CorruptExistingFileRebuilt(t *testing.T) {
+/* 既有 models.json 无法确认为「CLI 自己的格式」时，一律**不碰**，而不是重建。
+ *
+ * 这条契约是 2026-09-30 改的（Windows 事故）。原行为是「解析失败当空文件，重建」，
+ * 理由看起来无害（CLI 自己也这么兜底）。实际后果是把**别人的**文件整体替换掉：
+ * 桌面端 WorkBuddy 的 models.json 顶层是数组，数组解析不进 map[string]any，
+ * 于是被当成「坏文件」重建 → 里面 61 条官方模型全没了，只剩 8 条 custom-local，
+ * 而且没有备份，不可回滚。
+ *
+ * 宁可少同步一次端点（CLI 会自己报 "has no endpoint url configured"），
+ * 也不要毁掉一份不是我们管的配置。 */
+func TestSyncCustomModelsFromApp_CorruptExistingFileLeftUntouched(t *testing.T) {
 	dir := t.TempDir()
 	acc := filepath.Join(dir, "acc.json")
 	writeJSON(t, acc, appCacheFixture())
@@ -229,16 +417,25 @@ func TestSyncCustomModelsFromApp_CorruptExistingFileRebuilt(t *testing.T) {
 	if err := os.MkdirAll(cfg, 0o700); err != nil {
 		t.Fatal(err)
 	}
-	// 既有 models.json 坏了：应重建（CLI 自己也这么兜：读失败当空），且不崩
-	if err := os.WriteFile(filepath.Join(cfg, customModelsFileName), []byte("{oops"), 0o600); err != nil {
+	path := filepath.Join(cfg, customModelsFileName)
+	broken := []byte("{oops")
+	if err := os.WriteFile(path, broken, 0o600); err != nil {
 		t.Fatal(err)
 	}
+
 	added, err := syncCustomModelsFromApp(acc, cfg)
 	if err != nil {
-		t.Fatalf("坏文件应可恢复: %v", err)
+		t.Fatalf("不认识的文件应静默跳过，不该报错: %v", err)
 	}
-	if added != 2 {
-		t.Errorf("added = %d, want 2", added)
+	if added != 0 {
+		t.Errorf("added = %d, want 0（不碰未知格式）", added)
+	}
+	after, rerr := os.ReadFile(path)
+	if rerr != nil {
+		t.Fatalf("原文件必须还在: %v", rerr)
+	}
+	if !bytes.Equal(after, broken) {
+		t.Errorf("原文件被改写了：%s", after)
 	}
 }