magic-agent 2.6.0 → 2.6.3

package/client-ui-mobile/reqs.css

@@ -17,8 +17,11 @@
 .wsrow__sync:active{opacity:.7}
 .wsrow__sync:disabled{color:var(--muted);opacity:.6}
 /* 「未初始化」与「待整理」同形不同色：前者是「还没按目录生成过基线」，
-   后者是「有对话等着归纳」，两种提示不能混成一个数字。 */
+   后者是「有对话等着归纳」，两种提示不能混成一个数字。
+   深色下「待整理」那枚走 --badge-accent（警告琥珀，压在页面底上 5.8），别用 --warning 直接当字色：
+   它和排队金只差 1.08，11px 上分不出来（2026-10-25 第二轮）。 */
 .wsrow__badge--init{color:var(--warning);background:var(--tint-wait)}
+.wsrow__badge--pending{color:var(--badge-accent,var(--queued));background:var(--tint-queued)}
 
 /* ══════════ 需求页：整理失败的提示卡 ══════════
    服务端给的是引擎原始报错（`HTTP 402: {…JSON…}`，还常被截断），原样铺开会是一屏乱码。
@@ -26,7 +29,9 @@
    配色走 warning（淡底 + 左侧竖条），与「待整理 / 未初始化」同一套语义色，不做大红报错块 ——
    整理失败不损坏数据，它是「这次没跑成」，不是页面出错。 */
 .reqerr{margin:2px 10px 10px;padding:9px 12px;border-radius:var(--r);text-align:left;
-  background:color-mix(in srgb,var(--warning) 9%,var(--raised));
+  /* 底色走令牌 --warn-surface / --warn-badge（**必须按主题分给**，理由见 index.html 的 :root）：
+     深色压 --canvas 20% 才保住琥珀族（H64），浅色仍压 --raised 9%（原样暖白）。 */
+  background:var(--warn-surface);
   border:1px solid color-mix(in srgb,var(--warning) 26%,transparent);
   border-left:3px solid var(--warning)}
 .reqerr__head{display:flex;align-items:center;gap:6px}
@@ -34,9 +39,11 @@
 .reqerr__t{flex:1;min-width:0;font-size:13px;font-weight:600;color:var(--ink);
   overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 /* 类别徽标（额度不足 / 未授权 / 超时…）：认不出类别时不出，不硬套标签。
-   底色比卡片再浓一档、文字用 --ink —— 黄字压黄底在暗色主题下几乎读不出来（实测）。 */
+   文字色走 --warn-badge-text —— 黄字压黄底在暗色主题下几乎读不出来（实测）。
+   深色（2026-10-25 第二轮）底色提到实心琥珀、文字换成 --canvas 墨字（8.5+）；
+   浅色钉住「--ink 压 24% 琥珀」（与改动前逐像素一致）。 */
 .reqerr__badge{flex:0 0 auto;padding:1px 7px;border-radius:var(--r-full);font-size:11px;line-height:16px;
-  color:var(--ink);background:color-mix(in srgb,var(--warning) 24%,transparent)}
+  color:var(--warn-badge-text);background:var(--warn-badge)}
 .reqerr__msg{margin-top:5px;font-size:13px;line-height:1.55;color:var(--ink-soft);word-break:break-word}
 .reqerr__hint{margin-top:3px;font-size:12px;line-height:1.5;color:var(--muted)}
 .reqerr__more{display:flex;align-items:center;gap:3px;margin-top:5px;padding:0;background:none;border:0;

package/client-ui-mobile/reqs.js

@@ -96,6 +96,33 @@
     return alias || w.name || baseName(w.dir || '') || w.id;
   }
 
+  /* 空间列表按**显示名**去重（2026-10-26，用户截图：「magic-stock 出现了两行」）。
+   *
+   * 为什么路径去重不够：core 的 Workspaces() 按 ws id（sha1(归一路径)）去重 ——
+   * 那只认**同一个目录**。但「别名」是客户端这一层的概念：两个**不同目录**可以起
+   * 同一个显示名（自定义空间 D:/workspace/chan-chart-py 起了别名「magic-stock」，
+   * 而根目录下真有一个 magic-stock 目录）—— 路径各不相干，用户看到的却是两行一模一样的条目。
+   *
+   * 留谁：留**显示名 == 目录真名**的那条（真名是客观事实，别名是用户随手起的）。
+   * 两条都是别名时留先出现的那条（不靠猜）。
+   *
+   * ⚠️ 与任务页 collectSpaceKeys 是同一套口径 —— 两页列的是同一批空间，
+   *    去重规则不一样就会出现「任务页 3 个空间、需求页 4 个空间」。 */
+  function dedupeByLabel(list) {
+    var byLabel = {}, out = [];
+    (list || []).forEach(function (w) {
+      var label = reqSpaceLabel(w);
+      var isRealName = (label === baseName(w && w.dir));
+      var at = byLabel[label];
+      if (at === undefined) { byLabel[label] = out.length; out.push(w); return; }
+      if (!isRealName) return;
+      var prev = out[at];
+      if (reqSpaceLabel(prev) === baseName(prev && prev.dir)) return;
+      out[at] = w;
+    });
+    return out;
+  }
+
   /* 相机徽标的判定（**纯函数**：DOM 之外的逻辑单独拎出来，好测）。
    *
    * 触发条件 = 归纳时从对话里提取到了页面地址（page_url）：
@@ -294,8 +321,10 @@
        空间规模不是状态，套上会让人误以为这个空间在排队。 */
     var mods = (w.modules || []).filter(function (m) { return (m.features || []).length; });
     tog.appendChild(elSpan('wsrow__meta', mods.length + ' 模块 · ' + count + ' 条'));
-    /* 待整理条数做成徽标（与「等待中」同款）：折叠起来也看得见这个空间在长新需求。 */
-    if (w.pending > 0) tog.appendChild(elSpan('wsrow__badge', w.pending + ' 待整理'));
+    /* 待整理条数做成徽标（与「等待中」同款形状）：折叠起来也看得见这个空间在长新需求。
+       主色挂 --badge-accent（= 警告琥珀）：11px 的「待整理」若直接用排队金，深色下和上方
+       模块计数、和空间名几乎同亮度，「有活等着」读不出来（2026-10-25 第二轮）。 */
+    if (w.pending > 0) tog.appendChild(elSpan('wsrow__badge wsrow__badge--pending', w.pending + ' 待整理'));
     /* 未初始化 = 还没按空间目录生成过基线。老 core 不带 initialized 字段（undefined），
        此时不提示 —— 不能把「不知道」画成「未初始化」。 */
     if (w.initialized === false) tog.appendChild(elSpan('wsrow__badge wsrow__badge--init', '未初始化'));
@@ -419,6 +448,9 @@
          需求页于是出现一个叫「/」的假空间（用户 2026-10-22：「没有空间的不需要」）。
          这里先卡一道：不是真空间目录的直接不画。 */
       if (!H.isRealSpaceDir(dir)) return false;
+      /* 被用户移除过的空间（2026-10-26）：需求页整块不画 —— 与任务页「空间」分段
+         同一口径，否则用户删了空间、需求页还留着它（用户：「空间都可以修改和删除」）。 */
+      if (H.isHiddenSpace && H.isHiddenSpace(w && w.dir)) return false;
       return !REQ_ALIVE || !dir || !!REQ_ALIVE[dir];
     });
     /* 排序：**需求条数多的排前面**（用户 2026-10-22）。
@@ -431,6 +463,13 @@
       if (ca !== cb) return cb - ca;
       return String((a && a.name) || '').localeCompare(String((b && b.name) || ''));
     });
+    /* ⚠️ 按**显示名**去重（2026-10-26，用户截图：「magic-stock 出现了两行」）：
+       core 的 Workspaces() 按 ws id（sha1(归一路径)）去重，但**别名**不在 core 那层 ——
+       两个不同目录可以起同一个显示名（自定义空间 D:/workspace/chan-chart-py 起了别名
+       「magic-stock」，而根目录下真有一个 magic-stock 目录），需求页就会画两个同名空间组。
+       与任务页 collectSpaceKeys 同一口径：留**显示名 == 目录真名**的那条，
+       都是别名时留先出现的那条。 */
+    list = dedupeByLabel(list);
     /* 二级视图：只画这个模块的需求列表。空间可能已被会话删除联动掉
        （list 里没有它）—— 那就退回一级目录，不要留一页空白。 */
     if (REQ_DETAIL) {
@@ -505,8 +544,7 @@
           H.topLevelSessions(sess).forEach(function (s) {
             if (s && s.workspace && H.isRealSpaceDir(s.workspace)) alive[spaceKey(s.workspace)] = 1;
           });
-          REQ_ALIVE = alive;
-        } else {
+          REQ_ALIVE = alive;        } else {
           REQ_ALIVE = null;   // 清单没拿到：不筛，宁可多显示
         }
         REQ_DATA = a[0] || { workspaces: [] };
@@ -746,6 +784,9 @@
     return all.filter(function (w) {
       var dir = spaceKey(w && w.dir);
       if (!H.isRealSpaceDir(dir)) return false;
+      /* 被用户移除过的空间（2026-10-26）：图谱顶部 chips 与需求列表同一口径 ——
+         删了的空间不该又从图谱入口冒出来。 */
+      if (H.isHiddenSpace && H.isHiddenSpace(w && w.dir)) return false;
       return !REQ_ALIVE || !dir || !!REQ_ALIVE[dir];
     });
   }
@@ -753,7 +794,10 @@
   function renderGraphPick() {
     var pick = els.detail.querySelector('#reqGraphPick');
     if (!pick) return;
-    var list = graphWsList();
+    /* ⚠️ 按**显示名**去重（2026-10-26，用户截图：「magic-stock 出现了两行」）：
+       与需求列表同一套口径（dedupeByLabel）—— 列表里只留一条，图谱里也不能冒出两枚
+       一模一样的 chip（否则用户点哪枚都一样，又是一处「重复」）。 */
+    var list = dedupeByLabel(graphWsList());
     pick.replaceChildren.apply(pick, list.map(function (w) {
       var b = hEl('button', 'reqgraph__chip' + (REQ_GRAPH_WS && REQ_GRAPH_WS.id === w.id ? ' is-on' : ''));
       b.type = 'button';

package/client-ui-mobile/scripts.css

@@ -19,3 +19,49 @@
 /* 详情页的日志区：比插件页那条略高一点 —— 脚本日志是要盯着看的，
    170px 只够三四行，看不出「在动」。 */
 .pd__log--script{max-height:260px}
+
+/* ══════════ 空态：一个脚本都没有 ══════════
+   2026-10 用户：「发现中各项没有的时候界面设计一下」。从前是一行居中灰字，
+   整页看着像「坏了 / 没加载出来」。现在收成一条路：
+     一枚图标（说清这一页管什么）→ 一句标题（说清现状）→ 一句说明（说清下一步）
+     → 主按钮（直达「添加」）→ 三行示例（告诉用户要填什么、怎么填）。
+   ⚠️ 三行示例是**静态文案**，不是可点的假入口 —— 点了就该有事，不能摆给你看。
+   ⚠️ 颜色全走 var()，不定义令牌（同本文件开头）；明/暗两套主题自动跟随。
+   入页时若清单还没回来，先把这块**淡**一点画出来（.is-loading）：
+   手指一碰就有东西，不会先白屏、再闪一句「读取中…」、再换成空态，跳两次。 */
+.scriptempty{display:flex;flex-direction:column;align-items:center;padding:36px 20px 16px;text-align:center}
+.scriptempty__ico{position:relative;width:64px;height:64px;border-radius:50%;background:var(--subtle);color:var(--muted);
+  display:flex;align-items:center;justify-content:center;margin-bottom:14px;
+  box-shadow:inset 0 0 0 1px var(--border)}
+.scriptempty__t{font-size:16px;font-weight:600;line-height:24px;color:var(--ink)}
+.scriptempty__why{margin-top:6px;max-width:280px;font-size:13px;line-height:1.65;color:var(--muted)}
+.scriptempty__act{width:200px;margin-top:18px}
+.scriptempty__act .btn{margin-top:0}
+/* 图标中央一枚 ＋：与右上角「添加」同一个 i-plus，形成「点这儿 = 点右上角」的暗示。 */
+.scriptempty__plus{position:absolute;width:22px;height:22px;border-radius:50%;
+  background:var(--primary-action);color:var(--on-primary-action);
+  display:flex;align-items:center;justify-content:center;
+  box-shadow:0 0 0 2px var(--canvas)}
+/* 示例：一行一条「什么 → 填什么」，等宽值用 --mono，像在交代格式而不是堆正文。 */
+.scriptempty__eg{margin-top:22px;width:100%;max-width:320px;padding:12px 14px;border-radius:var(--r);
+  background:var(--subtle);text-align:left}
+.scriptempty__eg-h{font-size:11px;font-weight:700;letter-spacing:.04em;color:var(--faint);margin-bottom:8px}
+.scriptempty__eg-row{display:flex;align-items:baseline;gap:10px;font-size:13px;line-height:22px}
+.scriptempty__eg-row+.scriptempty__eg-row{margin-top:2px}
+.scriptempty__eg-k{flex:0 0 auto;min-width:44px;color:var(--muted)}
+.scriptempty__eg-v{min-width:0;color:var(--ink-soft);font:12px/22px var(--mono);
+  white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.scriptempty__foot{margin-top:14px;font-size:12px;line-height:1.6;color:var(--faint)}
+/* 清单回来之前：「读取中 → 空态」不该跳成两帧。先以 55% 透明度摆出空态骨架，
+   回来还是空 → 原地变实；回来了脚本 → 直接换成清单。 */
+.scriptempty.is-loading{opacity:.55}
+@media (prefers-reduced-motion: no-preference){
+  .scriptempty:not(.is-loading){animation:scriptempty-in .18s ease-out}
+  @keyframes scriptempty-in{from{opacity:.55}to{opacity:1}}
+}
+
+/* ══════════ 读取失败 ══════════
+   与上面同一条竖向节奏，只是图标换成警示色、按钮换成「重试」。
+   失败态和空态必须一眼分得开 —— 用户看到空壳时要知道「是真没有」还是「没读到」。 */
+.scriptempty--fail .scriptempty__ico{background:var(--tint-fail);color:var(--fail);box-shadow:none}
+.scriptempty--fail .scriptempty__why{color:var(--error-text);max-width:300px;word-break:break-word}

package/client-ui-mobile/scripts.js

@@ -96,12 +96,61 @@
   }
 
   /* ── 一级：脚本清单 ── */
+  /* ── 空态 / 失败态（竖排：图标 → 标题 → 说明 → 按钮 → 示例）──
+     `intro`：只有标题与说明，颜色更淡，用来在清单回来之前先占位（见 renderList 注释）。
+     样式在 scripts.css 的「空态」一节，颜色全走 var()。 */
+  function emptyBox(icon, title, why, actionText, onAction, intro) {
+    var box = hEl('div', 'scriptempty' + (intro ? ' is-loading' : ''));
+    var ico = hEl('span', 'scriptempty__ico');
+    ico.appendChild(svgUse(icon, 26));
+    if (!intro) {
+      var plus = hEl('span', 'scriptempty__plus');
+      plus.appendChild(svgUse('#i-plus', 14));
+      ico.appendChild(plus);
+    }
+    box.appendChild(ico);
+    box.appendChild(hEl('div', 'scriptempty__t', title));
+    box.appendChild(hEl('div', 'scriptempty__why', why));
+    if (actionText) {
+      var act = hEl('div', 'scriptempty__act');
+      var btn = hEl('button', 'btn btn--filled', actionText);
+      btn.type = 'button';
+      btn.onclick = onAction;
+      act.appendChild(btn);
+      box.appendChild(act);
+    }
+    if (intro) return box;
+    /* 示例：告诉用户「要填什么、长什么样」。纯文案，不可点。 */
+    var eg = hEl('div', 'scriptempty__eg');
+    eg.appendChild(hEl('div', 'scriptempty__eg-h', '示例'));
+    [['路径', 'D:\\tools\\build.cmd'],
+     ['参数', '--port 8080'],
+     ['解释器', '可选，如 python.exe']].forEach(function (r) {
+      var row = hEl('div', 'scriptempty__eg-row');
+      row.appendChild(hEl('span', 'scriptempty__eg-k', r[0]));
+      row.appendChild(hEl('span', 'scriptempty__eg-v', r[1]));
+      eg.appendChild(row);
+    });
+    box.appendChild(eg);
+    box.appendChild(hEl('div', 'scriptempty__foot', '脚本跑在桌面端，手机上可以随时启停、看日志。'));
+    return box;
+  }
+
+  /* 空态的标题与说明只写一份：清单回来前的淡色占位、与正式空态，
+     文案必须逐字相同 —— 两处各写一遍，改一处就会在「淡 → 实」时看到文字跳一下。 */
+  var EMPTY_TITLE = '还没有脚本';
+  var EMPTY_WHY = '登记一个桌面端上的脚本文件，就能在手机上启动、停止它，并实时看它的日志。';
+
   function renderList() {
     if (!els.list) return;
     var frag = document.createDocumentFragment();
     if (!ITEMS.length) {
-      frag.appendChild(hEl('div', 'history__hint',
-        '还没有脚本。点右上角「添加」登记一个脚本文件（路径 + 参数），就能在这里启停它、看它的日志。'));
+      /* 2026-10 用户：「发现中各项没有的时候界面设计一下」。
+         从前是一行居中灰字，整页看着像没加载出来；现在给图标 + 标题 + 下一步 + 示例。
+         清单**真的读到了**才显示为正式空态 —— 读失败是另一块（见 loadList 的 catch），
+         两者长得像的话，用户分不清「没有脚本」还是「没连上」。 */
+      frag.appendChild(emptyBox('#i-cpu', EMPTY_TITLE, EMPTY_WHY,
+        '添加脚本', function () { openForm(null); }));
       els.list.replaceChildren(frag);
       return;
     }
@@ -128,7 +177,13 @@
 
   function loadList(quiet) {
     if (!els.list) return;
-    if (!quiet) els.list.innerHTML = '<div class="history__hint">读取中…</div>';
+    if (!quiet) {
+      /* 不先闪一句「读取中…」：直接按空态骨架淡着画出来（.is-loading），
+         读到空 → 原地变实；读到脚本 → 换成清单；读失败 → 换成失败块。
+         本地服务一般几十毫秒就回来，三帧闪烁反而更像卡住了。 */
+      ITEMS = [];
+      els.list.replaceChildren(emptyBox('#i-cpu', EMPTY_TITLE, EMPTY_WHY, null, null, true));
+    }
     return fetch(api('/desk/scripts'), { headers: headers() })
       .then(function (r) {
         if (r.status === 404) throw new Error('当前桌面端没有脚本能力（需要较新版本）');
@@ -136,14 +191,19 @@
         return r.json();
       })
       .then(function (j) {
+        /* 空 → 有 / 有 → 空 都走同一条 renderList：
+           从前 quiet 刷新在「空了」的时候会停在上一张旧卡片上，删掉最后一个脚本后
+           返回清单还是空的（2026-10 顺带修）。 */
         ITEMS = (j && j.scripts) || [];
         renderList();
       })
       .catch(function (e) {
+        /* quiet 且有内容：一次网络抖动不该把用户正看的清单换掉（同宿主会话列表的口径）。 */
         if (quiet && ITEMS.length) return;
-        els.list.innerHTML = '';
-        els.list.appendChild(hEl('div', 'history__hint',
-          '读取脚本清单失败：' + ((e && e.message) || e)));
+        var msg = (e && e.message) || String(e);
+        ITEMS = [];
+        els.list.replaceChildren(emptyBox('#i-bang', '脚本清单没读到',
+          msg, '重试', function () { loadList(false); }));
       });
   }
 

package/cmd/magic-client/browsectl.go

@@ -58,7 +58,7 @@ func runBrowseDriver(args []string) int {
 		if len(argv) < 1 {
 			return browseUsage("open 需要 <url>")
 		}
-		return browseCall("open " + argv[0], func() (any, error) {
+		return browseCall("open "+argv[0], func() (any, error) {
 			return nil, client.ABOpen(context.Background(), argv[0])
 		})
 	case "state":

package/cmd/magic-client/clientctl.go

@@ -136,9 +136,18 @@ func runClientStart(args []string) int {
 func runClientStop(args []string) int {
 	fs := newFlagSet("stop")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
+	profilePath := fs.String("profile", "", "profile JSON 路径（决定单实例锁在哪个数据目录；空 = 内置默认）")
 	_ = fs.Parse(args)
 
-	stopped, st, err := client.StopDaemon(client.StopOptions{StatePath: *statePath})
+	/* AlsoLockHolder：前台 serve 起的实例、以及旧版（*.stale）起的实例都不写状态文件，
+	   只读状态文件的 stop 会答「本来就没在跑」，而端口与隧道实际还占着 —— 用户此时
+	   唯一的自救途径就是这条。DataDir / AppID 决定去查哪两处登记。 */
+	stopped, st, err := client.StopDaemon(client.StopOptions{
+		StatePath:      *statePath,
+		AlsoLockHolder: true,
+		DataDir:        dataDirOf(*profilePath),
+		AppID:          appIDOf(*profilePath),
+	})
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "magic-client:", err)
 		return 1
@@ -161,10 +170,15 @@ func runClientStop(args []string) int {
 func runClientRestart(args []string) int {
 	fs := newFlagSet("restart")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
+	profilePath := fs.String("profile", "", "profile JSON 路径（决定单实例锁在哪个数据目录；空 = 内置默认）")
 	delay := fs.Duration("delay", 0, "停旧实例前等多久（服务端自重启用，给响应留时间）")
 	_ = fs.Parse(args)
 
-	st, err := client.RestartDaemon(client.RestartOptions{StatePath: *statePath, Delay: *delay})
+	st, err := client.RestartDaemon(client.RestartOptions{
+		StatePath: *statePath,
+		Delay:     *delay,
+		DataDir:   dataDirOf(*profilePath),
+	})
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "magic-client:", err)
 		return 1
@@ -173,6 +187,27 @@ func runClientRestart(args []string) int {
 	return 0
 }
 
+// dataDirOf 按 profile 算数据目录（单实例锁的位置由它决定）。
+//
+// 读不到 profile 就返回空串 —— 调用方会回落到「从状态文件目录推」的老行为，
+// 不能因为 profile 路径写错就让 `stop` 变成「什么都不做」。
+func dataDirOf(profilePath string) string {
+	prof, err := client.LoadProfile(profilePath)
+	if err != nil {
+		return ""
+	}
+	return prof.DataDir()
+}
+
+// appIDOf 按 profile 算 AppID（AppID 级占用登记的位置由它决定）。
+func appIDOf(profilePath string) string {
+	prof, err := client.LoadProfile(profilePath)
+	if err != nil {
+		return ""
+	}
+	return prof.AppID()
+}
+
 func runClientStatus(args []string) int {
 	fs := newFlagSet("status")
 	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")

package/cmd/magic-client/main.go

@@ -31,6 +31,7 @@ import (
 	"time"
 
 	"github.com/darren/magic-agent/internal/client"
+	"github.com/darren/magic-agent/internal/config"
 )
 
 func main() {
@@ -68,9 +69,59 @@ func main() {
 		browseUA    = fs.String("browse-ua", "", "内置浏览器中转的 User-Agent：mobile（默认）/ desktop / 任意自定义串")
 		readyFile   = fs.String("ready-file", "", "监听成功后把 {pid,port,url,lanAddrs} 原子写到这个路径（`magic-client start` 用它拿端口，别手工传）")
 		anyOrigin   = fs.Bool("allow-any-origin", false, "对任意 Origin 回 CORS 头（默认只放行本机页面）。局域网模式自动开启；令牌仍是唯一门锁")
+		/* 前台 serve 自登记（2026-10-26）：
+		   `POST /desk/restart` 需要知道「这台实例是怎么起的」，否则手机点重启只能 409。
+		   `magic-client start` 起的实例一直有 client.json 可读；前台 serve（magic-test 的
+		   桥接就是这种）过去什么都不写，于是按钮永远点不动。 */
+		statePath = fs.String("state", "", "把本实例的启动参数登记到这个状态文件（空 = <数据目录>/serve.json）。重启接口靠它认领自己")
+		hostPID   = fs.Int("host-pid", 0, "托管本服务的父进程 pid（桌面壳）。它退出后本服务跟着退出，避免重启后留下孤儿占端口")
 	)
 	_ = fs.Parse(os.Args[2:])
 
+	prof, err := client.LoadProfile(*profilePath)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client:", err)
+		os.Exit(1)
+	}
+
+	/* 单实例互斥（2026-10-26 用户：「同时只启动1个」）。
+	 *
+	 * 位置：紧跟 LoadProfile（要 profile 才能算出 AppID 与数据目录），**早于
+	 * client.New / net.Listen**，原因是：
+	 *   · client.New 会跑 `magic-agent --contract`（20s 超时）并建起作业队列，
+	 *     那一步已经会去碰共用的 <DataDir>/jobs 与状态文件。晚于它就等于
+	 *     「先动了手再问有没有别人」；
+	 *   · 晚于 net.Listen 的话，第二份实例的报错会变成「端口被占用」—— 那是在描述
+	 *     症状不是原因（端口撞了只是这份目录上已有一份在跑的结果）；
+	 *   · --addr 各不相同的话，端口探测根本发现不了对方，但两份照样各跑一套作业
+	 *     队列去抢同一批工作区 —— 手机连着 A、任务在 B 里跑完，界面空回复。
+	 *
+	 * 两道闸门（缺一不可，见 singleinstance.go 的长注释）：
+	 *   ① AppID 登记：同一应用**换了数据目录**也不算两份不同应用；
+	 *   ② DataDir 锁：同一个目录上只能有一份。
+	 * 只做 ② 会漏掉「同一次部署被算出两个数据目录」这种漂移（本机真有：
+	 * magic-test 既有 ~/.magic-test 又有 ~/.magic-client/magic-test）。
+	 *
+	 * 只跳过 --print-url（脚本探活用的，它连服务都不起，不该占锁）。 */
+	var instLock *client.SingleInstanceLock
+	if !*printURL {
+		lk, holder, which, lerr := client.AcquireInstanceLocks(prof.AppID(), prof.DataDir(), 0)
+		if lerr != nil {
+			fmt.Fprintln(os.Stderr, "magic-client:", lerr)
+			os.Exit(1)
+		}
+		if lk == nil {
+			if which == "appid" {
+				fmt.Fprintln(os.Stderr, "magic-client:", client.AppIDConflictMessage(prof.AppID(), holder))
+			} else {
+				fmt.Fprintln(os.Stderr, "magic-client:", client.SingleInstanceConflictMessage(holder))
+			}
+			os.Exit(3)
+		}
+		instLock = lk
+		defer instLock.Release()
+	}
+
 	// 局域网是默认行为（手机开箱能连）；--local 或显式回环地址回到「只给本机」。
 	lanEnabled := *lan && !*localOnly
 	listenAddr := strings.TrimSpace(*addr)
@@ -85,11 +136,6 @@ func main() {
 		lanEnabled = false
 	}
 
-	prof, err := client.LoadProfile(*profilePath)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "magic-client:", err)
-		os.Exit(1)
-	}
 	tok := strings.TrimSpace(*token)
 	if tok == "" {
 		tok = randToken() // 16 字节 = 32 位十六进制，远强于局域网那条线
@@ -102,18 +148,35 @@ func main() {
 			os.Exit(2)
 		}
 	}
+	/* 飞书推送凭据（2026-10-26）：config.json 的 feishu 节 / MAGIC_AGENT_FEISHU_APP_ID|SECRET。
+	   读不到配置文件不算错 —— 没配就是没开推送，界面里会提示去填（见 internal/client/feishu.go）。 */
+	feishuCfg, _ := config.Load()
+	/* 本实例的自登记路径，**在 New 之前**就算出来：Service 要靠它「认领自己」
+	   （手机点重启时 selfDaemonState 按这条路找回状态，见 coreupgrade.go）。
+	   空串不可能 —— prof 一定有数据目录；真没有就退回 <数据目录>/serve.json 的约定。 */
+	selfStatePath := strings.TrimSpace(*statePath)
+	if selfStatePath == "" {
+		selfStatePath = client.SelfStatePath(prof.DataDir())
+	}
 	svc, err := client.New(client.Options{
-		MagicAgent: *magicAgent,
-		Profile:    prof,
-		UIRoot:     *uiDir,
-		MobileRoot: *mobileDir,
-		Token:      tok,
-		Lan:        lanEnabled,
-		BrowseUA:   *browseUA,
+		MagicAgent:      *magicAgent,
+		FeishuAppID:     feishuCfg.Feishu.AppID,
+		FeishuAppSecret: feishuCfg.Feishu.AppSecret,
+		Profile:         prof,
+		UIRoot:          *uiDir,
+		MobileRoot:      *mobileDir,
+		Token:           tok,
+		Lan:             lanEnabled,
+		BrowseUA:        *browseUA,
 		/* 局域网 = 「允许来自任意 IP 的页面访问」：再按 loopback 卡 CORS Origin
 		   等于把手机 / 别的设备的页面全判成跨域（用户侧就是「只能本地访问」）。
 		   显式 --allow-any-origin 也可以单独打开（绑回环但要给容器页面用）。 */
 		AllowAnyOrigin: *anyOrigin || lanEnabled,
+		/* 前台 serve 自登记的落点：重启接口靠它认领本进程（见 daemon.go 的 SelfStateName）。 */
+		SelfStatePath: selfStatePath,
+		/* 托管父进程：重启之后的实例是 detach 的，壳退出杀不到它。
+		   记下来交给服务自己盯（见 service.go 的 WatchHost）。 */
+		HostPID: *hostPID,
 	})
 	if err != nil {
 		// 契约不匹配是**要立刻停**的错误：带着不匹配的能力跑起来只会让人以为是界面 bug。
@@ -207,10 +270,94 @@ func main() {
 		}
 	}
 
+	/* 自登记（2026-10-26 用户：「通过 magic-test 启动的无法在移动端点击重启服务重启」）。
+	 *
+	 * 手机「重启服务」＝ POST /desk/restart。它要做的第一件事是「确认我说的是本进程、
+	 * 并且知道当初是怎么把我起来的」—— 重启助手要照这份参数停旧起新。`magic-client start`
+	 * 起的实例一直有 client.json；前台 serve（magic-test 桥接、手工调试都是这种）过去
+	 * 什么都不写，于是 409「当前实例不是后台启动的」，按钮永远点不动。
+	 *
+	 * 记到 <数据目录>/serve.json（**不是** client.json：那份是 start 的唯一实例记录，
+	 * 详见 daemon.go 的 SelfStateName）。带 HostPID 是为了重启出来的 detach 实例还能
+	 * 跟着壳一起退（见 svc.WatchHost）。
+	 *
+	 * 顺序：**监听成功之后**。写早了会把一个还没 Serve 的端口登记出去，手机拿着它去
+	 * 探活／重启都会撞空。
+	 *
+	 * ⚠️ `magic-client start` 拉起的 serve **不登记**（ready 文件就是它那条路的标志）：
+	 *    那条路已经有 client.json（信息更全：LogPath / 幂等判据都在里面），再写一份
+	 *    serve.json 会让 selfDaemonState 先认领到这份**信息更少**的登记 —— 重启后
+	 *    日志位置丢了、`stop` 的幂等判据也没了。两条启动路径各登记各的，不交叉。 */
+	/* 无论走哪条启动路径，只要知道「我那份登记在哪」，退出就清理（下面 defer）。
+	 *
+	 * 为什么 start 路径也要清：重启出来的实例不是被 `stop` 停掉的，而是 WatchHost
+	 * 发现宿主没了、自己 srv.Close() 收摊 —— 那条路上没有任何人删登记，留着就是一个
+	 * 指向死 pid 的陈旧文件（实测：serve.json 残留在 35444 这个已退出的 pid 上）。
+	 * RemoveSelfState 带 pid 校验，新实例已经接管时不会误删它的。
+	 *
+	 * 但**写**登记只有前台 serve 才做：start 路径的 client.json 由 StartDaemon 写
+	 *（它信息更全，含日志位置），serve 再写一遍等于用一份更少的覆盖它。 */
+	if !*printURL && selfStatePath != "" {
+		defer client.RemoveSelfState(selfStatePath)
+	}
+	if !*printURL && strings.TrimSpace(*readyFile) == "" {
+		lanURLs := make([]string, 0, len(lanAddrs))
+		for _, a := range lanAddrs {
+			lanURLs = append(lanURLs, fmt.Sprintf("http://%s/?token=%s", a, tok))
+		}
+		/* Exe 必须是**本进程自己的可执行文件**：重启助手照它拉新实例
+		   （RestartDaemon → StartDaemon 的 Exe）。记空的话新实例会退回
+		   「当前进程自己」，而助手是另一个进程 —— 那就成了拉起助手自己。 */
+		exePath, _ := os.Executable()
+		p, werr := client.WriteSelfStateAt(selfStatePath, prof.DataDir(), &client.DaemonState{
+			PID:        os.Getpid(),
+			Port:       port,
+			URL:        url,
+			LanAddrs:   lanURLs,
+			Lan:        lanEnabled,
+			Profile:    *profilePath,
+			UIRoot:     *uiDir,
+			MobileDir:  *mobileDir,
+			ProxyAddr:  proxyActual,
+			Token:      tok,
+			StartedAt:  time.Now(),
+			LogPath:    "",
+			Exe:        exePath,
+			Addr:       strings.TrimSpace(*addr),
+			BrowseUA:   *browseUA,
+			MagicAgent: *magicAgent,
+			AnyOrigin:  *anyOrigin,
+			HostPID:    *hostPID,
+		})
+		if werr != nil {
+			/* 登记失败不致命：服务照常能用，只是手机点重启会 409。
+			   绝不因此退出 —— 那等于「为了一个按钮把服务弄挂」。 */
+			fmt.Fprintf(os.Stderr, "magic-client: 警告 - 没能登记本实例状态（%v）：手机端「重启服务」会不可用\n", werr)
+		} else {
+			fmt.Fprintf(os.Stderr, "magic-client: 实例状态 %s（手机可一键重启本实例）\n", p)
+		}
+	}
+
+	/* 飞书启动通知（2026-10-26 用户：「重新启动后如果绑定了飞书 触发一下发送访问地址」）：
+	   重启是手机最容易失联的时刻（换网 / 换端口 / 隧道换域名），飞书是唯一不依赖那条
+	   连接的通道。没绑定 / 关了推送时 NotifyStartup 直接返回，不发任何请求；它在后台
+	   等隧道、可能试几十秒，不能挡住 Serve。局域网入口传进去，没有公网时拿它兜底。 */
+	startupEntry := ""
+	if len(lanAddrs) > 0 {
+		startupEntry = fmt.Sprintf("http://%s/?token=%s", lanAddrs[0], tok)
+	}
+	go svc.NotifyStartup(startupEntry)
+
 	srv := &http.Server{
 		Handler:           svc.Handler(),
 		ReadHeaderTimeout: 10 * time.Second,
 	}
+	/* 托管父进程没了就收摊（见 service.go 的 WatchHost）。
+	   只在重启链路里才有意义：重启出来的实例是 detach 的，壳的 r.stop() 杀不到它，
+	   没有这一条就会留下孤儿占着端口与单实例锁，下次开壳「插件启动即退出」。 */
+	svc.WatchHost(func() {
+		_ = srv.Close()
+	})
 	go func() {
 		stop := make(chan os.Signal, 1)
 		signal.Notify(stop, os.Interrupt, syscall.SIGTERM)