feat(frontend): Enchante Agent 改为置灰开关 + 参考使用手册链接，停用 agent deeplink

Enchante 的 Agent deeplink（enchante://agent/install）在真机上验证不可靠
（即便 PR #3 补上了缺失的顶层 name 字段，deeplink 本身对 Enchanté 版本/环境的
依赖仍不稳定），改为引导用户直接看使用手册，避免继续给一个不可靠的安装入口。

改动范围仅 Enchante + agent 这一格：
- 设置弹窗 Agent 分组、首次引导 2.2 结论页，Enchante 那一行都改成不可点的置灰
  开关（视觉与 Hooks 分组里 Enchante 那行「平台原生不支持」的置灰渲染一致），
  描述文字改为「参考使用手册」，旁边加一个「查看手册」链接。
- store.js: usesDeeplink() 收窄为仅 Enchante+MCP；新增 isEnchanteAgentManual()
  判定 + openEnchanteAgentManual() 打开手册。
- desktop/main.js + preload.js: 新增独立的 open-manual IPC 通道，用
  shell.openPath 打开手册文件。没有复用 open-external，因为那个通道专门 block
  了 file: 前缀（避免渲染层任意打开本地文件/命令）；手册路径由主进程硬编码，
  渲染层不传参，同样是为了不给渲染层传任意本地路径的口子。

TODO（分发前必须替换，已在代码里标注）：MANUAL_PATH 目前是本机开发路径占位，
正式版应指向打包进 app 资源目录的手册文件，并加入 electron-builder 的
extraResources / build-backend datas。

Enchante 的 MCP deeplink、其它平台的 Agent 配置均未改动。

测试：只跑了改动直接影响的静态结构测试（不含全局前端/浏览器测试套件）：
  pytest tests/frontend/test_stage3.py::TestStage3StaticStructure  # 16 passed
  pytest tests/frontend/test_stage3.py::TestStage3Build            # 1 passed（对新 build 的 standalone 断言）
同时更新了这两类测试里跟 Agent deeplink 按钮相关的断言（按钮已移除、改为手册引导），
以及一个受影响的浏览器测试（TestStage3Browser，未在本地跑，留给 review/CI）。

Author: chenyida7-prog

desktop/main.js

@@ -477,6 +477,28 @@ app.whenReady().then(async () => {
     }
   });
 
+  // ── 使用手册系统级打开（IPC）──────────────────────────────
+  // Enchante 的 Agent deeplink 在真机验证不可靠（2026-08-26），改为引导用户看使用
+  // 手册。手册是本地文件，open-external 专门 block 了 file: 前缀（避免渲染层任意打
+  // 开本地文件/命令），所以走独立的、路径由主进程硬编码（渲染层不传路径）的 IPC 通
+  // 道，用 shell.openPath 交给系统默认程序（.html → 默认浏览器）打开。
+  //
+  // TODO(分发前替换)：MANUAL_PATH 目前是本机开发路径占位，正式版应改为打包进 app
+  // 资源目录的手册文件（如 path.join(process.resourcesPath, "docs", "MyKnowledge使用手册.html")），
+  // 并把手册一并加入 electron-builder 的 extraResources / build-backend datas。
+  const MANUAL_PATH =
+    "/Users/chenyida/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_6qcy1jhgv90312_a764/msg/file/2026-08/MyKnowledge使用手册3_2.html";
+  ipcMain.handle("open-manual", async () => {
+    try {
+      const err = await shell.openPath(MANUAL_PATH);
+      // shell.openPath 失败时返回非空错误字符串（不像 openExternal 那样 reject）
+      if (err) return { ok: false, error: err };
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: String(err) };
+    }
+  });
+
   try {
     if (DEV_BACKEND_URL) {
       // 开发模式：直接连开发者后端

desktop/preload.js

@@ -58,3 +58,8 @@ contextBridge.exposeInMainWorld("__mykOnCloseChoice__", (payload) => {
 contextBridge.exposeInMainWorld("__mykOpenExternal__", (url) => {
   return ipcRenderer.invoke("open-external", url);
 });
+
+// 使用手册系统级打开（本地文件，路径由主进程硬编码，渲染层不传参，避免任意路径注入）
+contextBridge.exposeInMainWorld("__mykOpenManual__", () => {
+  return ipcRenderer.invoke("open-manual");
+});

frontend/css/components.css

@@ -2561,6 +2561,18 @@
   color: var(--text-secondary);
   font-style: italic;
 }
+/* Enchante Agent「参考使用手册」行内链接：与置灰状态文字同级，不额外抢视觉焦点 */
+.ai-platform-row__manual-link {
+  margin-left: 6px;
+  font-size: 12px;
+  color: var(--accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+.ai-platform-row__manual-link:hover {
+  color: var(--accent-hover, var(--accent));
+}
 
 /* ── 连接态（MCP 卡平台行右，平台级四态：not_connected/connected/inactive/lost；置灰仅 !installed） ── */
 .ai-platform-row__connection {

frontend/index.html

@@ -47,7 +47,7 @@
   <link rel="stylesheet" href="css/sidebar.css?v=a098a49cbe" />
   <link rel="stylesheet" href="css/viewer.css?v=326a61002d" />
   <link rel="stylesheet" href="css/editor.css?v=e811a96156" />
-  <link rel="stylesheet" href="css/components.css?v=77f20937a1" />
+  <link rel="stylesheet" href="css/components.css?v=a560dd30c4" />
   <link rel="stylesheet" href="css/markdown-content.css?v=6c10b2632f" />
 
   <!-- highlight.js 主题 -->
@@ -69,7 +69,7 @@
   <script src="js/converter.js?v=d8110f4a62"></script>
   <script src="js/renderer.js?v=95b7ca304e"></script>
   <script src="js/splash.js?v=9bc7eee6bd"></script>
-  <script src="js/store.js?v=e8407d2f87"></script>
+  <script src="js/store.js?v=72bb9afc4a"></script>
   <script src="js/router.js?v=a1968069d7"></script>
   <script src="js/app.js?v=5c96193949"></script>
   <script src="js/components/doc.js?v=16de8d15b7"></script>
@@ -1743,7 +1743,8 @@ <h2 class="modal__title" style="text-align:center;">AI 协作初始化</h2>
                     <span class="guide-conclusion-row__dot" :style="'background:' + plat.dot"
                           :class="{ 'guide-conclusion-row__dot--skip': !$store.app.clientInstalled(plat.key) }"></span>
                     <span class="guide-conclusion-row__name" x-text="plat.label"></span>
-                    <!-- Enchante：专属 deeplink 安装入口（MCP / Agent 两个按钮，各自四态） -->
+                    <!-- Enchante：MCP 走专属 deeplink 安装；Agent deeplink 在真机验证不可靠
+                         （2026-08-26），改为置灰不可点开关 + 引导看使用手册，不再生成安装链接。 -->
                     <template x-if="plat.key === 'Enchante'">
                       <span class="guide-conclusion-row__body">
                         <span class="guide-conclusion-row__action">需手动安装</span>
@@ -1753,12 +1754,12 @@ <h2 class="modal__title" style="text-align:center;">AI 协作初始化</h2>
                           <span x-text="$store.app.deeplinkBusy ? '生成中…'
                                         : ($store.app.deeplinkClickedFor('mcp') ? 'MCP 已生成 · 可再次点击' : '⚡ 生成 MCP 链接')"></span>
                         </button>
-                        <button class="btn btn--sm btn--deeplink guide-conclusion-row__deeplink"
-                                :disabled="$store.app.deeplinkBusy || !$store.app.clientInstalled('Enchante')"
-                                @click="$store.app.generateEnchanteDeeplink('Enchante', 'agent')">
-                          <span x-text="$store.app.deeplinkBusy ? '生成中…'
-                                        : ($store.app.deeplinkClickedFor('agent') ? 'Agent 已生成 · 可再次点击' : '⚡ 生成 Agent 链接')"></span>
+                        <button class="toggle toggle--off" disabled aria-label="Enchante Agent：参考使用手册">
+                          <span class="toggle__knob"></span>
                         </button>
+                        <span class="guide-conclusion-row__action guide-conclusion-row__action--native">参考使用手册</span>
+                        <a class="ai-platform-row__manual-link"
+                           href="#" @click.prevent="$store.app.openEnchanteAgentManual()">查看手册</a>
                         <span class="guide-conclusion-row__hint"
                               x-show="!$store.app.clientInstalled('Enchante')">请先安装 Enchanté</span>
                       </span>
@@ -2013,7 +2014,7 @@ <h3 class="settings-body__title" x-text="kind.label"></h3>
                 <div class="settings-card__desc" x-text="'为各 AI 客户端配置 ' + kind.label + '；开关关闭 = 移除配置'"></div>
                 <template x-for="plat in $store.app.platformsForKind(kind.key)" :key="kind.key + '-' + plat.key">
                   <div>
-                    <div class="ai-platform-row" :class="{ 'ai-platform-row--unsupported': !plat.supported }"
+                    <div class="ai-platform-row" :class="{ 'ai-platform-row--unsupported': !plat.supported || $store.app.isEnchanteAgentManual(plat.key, kind.key) }"
                          :data-platform="plat.key" :data-kind="kind.key">
                       <span class="status-indicator__dot"
                             :class="$store.app.clientStatus(plat.key, kind.key) === true ? 'status-indicator__dot--success'
@@ -2022,18 +2023,25 @@ <h3 class="settings-body__title" x-text="kind.label"></h3>
                             :style="$store.app.clientStatus(plat.key, kind.key) !== null && !$store.app.clientInstalled(plat.key) ? 'opacity:0.5' : ''"></span>
                       <span class="ai-platform-row__name" x-text="plat.label"></span>
                       <span class="ai-platform-row__state"
-                            :class="!plat.supported ? 'ai-platform-row__state--unsupported'
+                            :class="$store.app.isEnchanteAgentManual(plat.key, kind.key) ? 'ai-platform-row__state--unsupported'
+                                   : !plat.supported ? 'ai-platform-row__state--unsupported'
                                    : $store.app.clientStatus(plat.key, kind.key) === null ? 'ai-platform-row__state--fail'
                                    : !$store.app.clientInstalled(plat.key) ? 'ai-platform-row__state--soft'
                                    : ($store.app.clientStatus(plat.key, kind.key) ? 'ai-platform-row__state--ok' : 'ai-platform-row__state--off')"
-                            x-text="!plat.supported ? '平台原生不支持'
+                            x-text="$store.app.isEnchanteAgentManual(plat.key, kind.key) ? '参考使用手册'
+                                    : !plat.supported ? '平台原生不支持'
                                     : $store.app.clientStatus(plat.key, kind.key) === null
                                     ? '检测失败 · 重新检测'
                                     : !$store.app.clientInstalled(plat.key)
                                       ? ($store.app.clientStatus(plat.key, kind.key) ? '请在安装 ' + plat.label + ' 后使用' : '请先安装 ' + plat.label)
                                       : ($store.app.clientStatus(plat.key, kind.key) ? '已配置'
                                          : ($store.app.usesDeeplink(plat.key, kind.key) ? '生成专属链接' : '未配置 · 点击开关开启'))"></span>
-                      <!-- deeplink 平台（当前 Enchante MCP/Agent）：单按钮「生成专属链接」，不走 toggle。
+                      <!-- Enchante Agent：deeplink 在真机验证不可靠，改为引导看使用手册（置灰
+                           不可点开关 + 手册链接），不再生成安装链接。 -->
+                      <a class="ai-platform-row__manual-link"
+                         x-show="$store.app.isEnchanteAgentManual(plat.key, kind.key)"
+                         href="#" @click.prevent="$store.app.openEnchanteAgentManual()">查看手册</a>
+                      <!-- deeplink 平台（当前仅 Enchante MCP）：单按钮「生成专属链接」，不走 toggle。
                            未安装时禁用（状态文字已显示「请先安装 X」，与引导页结论行一致） -->
                       <button class="btn btn--sm btn--deeplink"
                               x-show="$store.app.usesDeeplink(plat.key, kind.key)"
@@ -2043,12 +2051,13 @@ <h3 class="settings-body__title" x-text="kind.label"></h3>
                       </button>
                       <button class="toggle"
                               x-show="!$store.app.usesDeeplink(plat.key, kind.key)"
-                              :class="!plat.supported ? 'toggle--off'
+                              :class="$store.app.isEnchanteAgentManual(plat.key, kind.key) ? 'toggle--off'
+                                     : !plat.supported ? 'toggle--off'
                                      : $store.app.clientStatus(plat.key, kind.key) === null ? 'toggle--failed'
                                      : !$store.app.clientInstalled(plat.key)
                                        ? ($store.app.clientStatus(plat.key, kind.key) ? 'toggle--on-soft' : 'toggle--off-soft')
                                        : ($store.app.clientStatus(plat.key, kind.key) ? 'toggle--on' : 'toggle--off')"
-                              :disabled="!plat.supported || $store.app.clientStatus(plat.key, kind.key) === null || $store.app.isClientConfiguring(plat.key, kind.key)"
+                              :disabled="$store.app.isEnchanteAgentManual(plat.key, kind.key) || !plat.supported || $store.app.clientStatus(plat.key, kind.key) === null || $store.app.isClientConfiguring(plat.key, kind.key)"
                               @click="$store.app.clientStatus(plat.key, kind.key) === null
                                       ? $store.app.loadClientConfig()
                                       : $store.app.configureClient(plat.key, kind.key)">

frontend/js/store.js

@@ -1714,9 +1714,10 @@ let _tocCollapsedSet = {};
       }));
     },
 
-    /** 该平台该 kind 是否走 deeplink 安装（当前仅 Enchante MCP/Agent：无配置文件，客户端捕获链接） */
+    /** 该平台该 kind 是否走 deeplink 安装（当前仅 Enchante MCP：无配置文件，客户端捕获链接。
+     *  Enchante Agent 已改为「参考使用手册」，见 isEnchanteAgentManual）。 */
     usesDeeplink(platform, kind) {
-      return platform === "Enchante" && (kind === "mcp" || kind === "agent");
+      return platform === "Enchante" && kind === "mcp";
     },
 
     /** 正在生成 deeplink（Enchante deeplink 按钮 spinner / 防重复点击） */
@@ -1727,6 +1728,30 @@ let _tocCollapsedSet = {};
       return !!(this.deeplinkClicked && this.deeplinkClicked[kind]);
     },
 
+    /** Enchante 的 Agent 安装入口已停用（deeplink 在真机上验证不可靠，2026-08-26
+     *  决定改为引导用户看使用手册）——设置页 Agent 分组行 + 引导结论页命中该判断时，
+     *  一律渲染为置灰不可点开关 +「参考使用手册」+ 手册链接，不再走 usesDeeplink。 */
+    isEnchanteAgentManual(platform, kind) {
+      return platform === "Enchante" && kind === "agent";
+    },
+
+    /** 打开 MyKnowledge 使用手册（桌面端走现有 IPC 系统级打开外链，同 enchante:// deeplink
+     *  的机制）。手册路径当前是占位符，分发前需替换为打包进 app 资源目录的真实路径。 */
+    openEnchanteAgentManual() {
+      // TODO(分发前替换)：这是本机路径，占位用；正式版应指向打包进 app 的手册文件
+      // （如 resources/docs/MyKnowledge使用手册.html），由主进程解析，不应硬编码本机用户路径。
+      const url = "file:///Users/chenyida/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_6qcy1jhgv90312_a764/msg/file/2026-08/MyKnowledge%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C3_2.html";
+      if (window.__MYK_APP_MODE__ && typeof window.__mykOpenManual__ === "function") {
+        window.__mykOpenManual__().then((res) => {
+          if (res && res.ok === false) {
+            showToast("打开使用手册失败，请联系管理员确认手册路径", "error");
+          }
+        });
+      } else {
+        window.open(url, "_blank", "noopener");
+      }
+    },
+
     /**
      * Enchante deeplink 专属链接流程（MCP / Agent 共用）：GET deeplink → 复制剪贴板 →
      * 隐藏 <a target=_blank> 触发唤起（避免 SPA location.href 跳转中断）→ toast。失败给出可读提示。