magic-agent 1.0.3 → 1.0.49

package/client-ui/{pc/js → shared/conv}/09-stream-apply.js

@@ -20,7 +20,30 @@ function qaAskFromEvent(ask){
   return out.length ? out : null;
 }
 
+/* ---------- 工具结果在**画布上**的显示上限（2026-10-20）----------
+   用户报「读取历史太慢」。实测一条会话的 404 条 tool_result 共 28.1MB，
+   其中 30 条 >12KB 就占了 27.7MB（最大单条 1.6MB）。这些全量字串既进 `<pre>`，
+   又要过 `qaLooksLikeDiff` / `qaArtCollect` 两道全量正则，回放时把主线程卡住二十多秒。
+   工具卡明细是「看几眼」用的，不是日志查看器 —— 超限就只画前 N 字符，
+   并在末尾**如实标注**总长度（不假装这就是全部）。
+   ⚠️ 只截**显示**：ctx.onStep 仍拿全量，台账落库口径不变。 */
+const QA_TOOL_OUT_MAX = 12000;
+function qaToolOutForDisplay(text){
+  const s = String(text == null ? "" : text);
+  if(s.length <= QA_TOOL_OUT_MAX) return s;
+  const kb = (s.length / 1024).toFixed(1);
+  return s.slice(0, QA_TOOL_OUT_MAX)
+    + "\n\n… 已截断（共 " + kb + " KB，这里只显示前 " + (QA_TOOL_OUT_MAX / 1024) + " KB）";
+}
+
 function qaStreamApply(ev, ctx){
+  /* 会话锚点：**任何**带 session_id 的事件到场就绑（2026-10-16 用户：「pc端也不要等完全结束在
+     获取 sessionid」）。主进程这一轮走 `--events` 形态（见 desktop/main.js 的 buildAgentArgs
+     调用）→ core 一拿到 id 就每行都带，所以这里通常在第一行（引擎 init）就绑上了，不再等
+     result / turn_end。下面各分支里同款的绑定**保留**：老 CLI（非 --events 形态）只在收尾那几条
+     上带 id，仍靠它们落库；qaSessionBindFor 幂等，重复绑定无副作用。两套拼写都认。 */
+  const sidAny = ev && (ev.session_id || ev.sessionId);
+  if(sidAny && ctx && typeof ctx.onSession === "function") ctx.onSession(sidAny);
   for(const e of qaEventNormalize(ev)) qaStreamApplyOne(e, ctx);
 }
 
@@ -38,6 +61,16 @@ function qaStreamApplyOne(ev, ctx){
   const evParent = ev.parent != null ? String(ev.parent)
     : (ev.parent_tool_use_id != null ? String(ev.parent_tool_use_id) : null);
   const agOf = (id)=> id != null ? agents.get(id) : null;
+  /* 会话锚点：**任何**带 session_id 的事件都当场认（2026-10-15）。
+     ⚠️ 以前只在 ask / result / error / turn_failed / end / turn_end 这六条分支里认 ——
+     等于「等到终点事件才绑锚点」。而 core 在 `--events` 下一拿到 id 就**每行都带**
+     （internal/cli/events.go 的 eventAttrs），于是这段时间窗里的信息全被浪费：中途被打断、
+     或终帧本来就不带 id 的引擎（dsh 的续接轮 / SDK 通道不可用的回退轮），客户端就永远学不到
+     锚点，下一步追问被发成了**新会话**（真实报障：追问变成了新任务）。
+     抬到 switch 之前 → 谁先带 id 谁先绑；两套拼写都认（session_id / sessionId）。
+     历史回放不受影响：那条路径的 ctx.onSession 是空函数（宿主侧只读回放）。 */
+  const sidAny = ev.session_id || ev.sessionId;
+  if(sidAny && typeof ctx.onSession === "function") ctx.onSession(sidAny);
   const finishTools = (ok)=>{                 // 流结束/失败时兜底：还在转圈的工具卡一律收账
     ctx.tools.forEach(tc=>{ if(tc.state === "running") tc.done("", ok); });
     ctx.tools.clear();
@@ -66,10 +99,14 @@ function qaStreamApplyOne(ev, ctx){
       }
       /* 头像右边的「引擎 · 模型」小标同一时机跟成实际值（与胶囊同一条口径：
          界面说 A、实际跑 B 不行）。机器侧 `.qa-trace`（审查轮 / 数字分身的活动行）
-         是 qaTraceToLeft 另建的节点，句柄管不到它 —— 走 `__traceWrap` 直接改文字。 */
-      if(typeof h.setWho === "function") h.setWho(eng, mdl);
+         是 qaTraceToLeft 另建的节点，句柄管不到它 —— 走 `__traceWrap` 直接改文字。
+         ⚠️ `whoModelOnly`（2026-10-20）：宿主把「运行中」并到头像那一行之后，那一行
+            只放得下**模型名**（见 qaWhoLabel 的 modelOnly）—— 由宿主经 ctx 传下来。
+            不接这一档的话，降级换模型后这里会把长串写回去、秒数又被挤到换行。 */
+      const whoModelOnly = !!(ctx && ctx.whoModelOnly);
+      if(typeof h.setWho === "function") h.setWho(eng, mdl, whoModelOnly);
       const tw = (h.el && h.el.__traceWrap) ? h.el.__traceWrap.querySelector(".qa-who") : null;
-      if(tw) tw.textContent = qaWhoLabel(eng, mdl);
+      if(tw) tw.textContent = qaWhoLabel(eng, mdl, whoModelOnly);
       if(mdl && retry) qaModelSwitched.add(ev.rid);   // 记一笔：这轮换过模型（end 时重取链，见 Set 注释）
       if(mdl && ctx && ctx.taskId && typeof qaTaskSetModel === "function") qaTaskSetModel(ctx.taskId, mdl);
       if(mdl && retry && qaModelPick && qaModelPick !== mdl && typeof qaModelSet === "function"){
@@ -212,7 +249,7 @@ function qaStreamApplyOne(ev, ctx){
       // 期望载荷: { tid|id, text(结果串,可缺省), ok(布尔,缺省 true) }
       const tid = ev.tid != null ? ev.tid : ev.id;
       const tc = tid != null ? ctx.tools.get(tid) : null;
-      if(tc) tc.done(ev.text || "", ev.ok !== false);
+      if(tc) tc.done(qaToolOutForDisplay(ev.text || ""), ev.ok !== false);
       else if(evParent && agOf(evParent) && typeof agOf(evParent).subNote === "function")
         agOf(evParent).subNote("结果回执：" + String(ev.text || "").slice(0, 400)); // ③ 无卡可填 → 父卡注脚
       else if(typeof h.marker === "function"){
@@ -227,7 +264,7 @@ function qaStreamApplyOne(ev, ctx){
           title: "未配对结果" + (tid != null && tid !== "" ? " · " + String(tid).slice(0, 14) : ""),
           status: fail ? "failed" : "completed",
           destructive: fail,
-          detail: ev.text ? String(ev.text) : null,
+          detail: ev.text ? qaToolOutForDisplay(ev.text) : null,
           detailLabel: "output",
           hint: "这条结果配不到对应的工具卡（工具事件缺 id，或结果晚于收尾到达）",
         });
@@ -294,6 +331,12 @@ function qaStreamApplyOne(ev, ctx){
     case "result":
       // result 行是权威全文：以它覆盖正文（流式增量可能丢字符），并按 markdown 完整解析
       if(ev.text) h.setResult(ev.text);
+      /* 权威正文同时**改成台账的那一份**（2026-10-10）——画面（h.setResult）与台账
+         （run.msgText）必须同源：台账此前只由流式 text 事件逐段累加，而主进程可能在这条
+         result 里给的是**清理过**的正文（如剥掉拼在末尾的限流/额度通告，见 main.js 的
+         turn_end 分支）。不跟着改的话，画面说的是失败、历史重画时那句通告却又回来了。
+         ⚠️ 守卫与 h.setResult 一致（ev.text 非空才认），别把空正文当成「正文就是空」。 */
+      if(ev.text && ctx && typeof ctx.onResult === "function") ctx.onResult(ev.text);
       if(ev.latency_ms != null) ctx.setMs(ev.latency_ms);
       // 会话 id 写回任务（追问续接同一会话）；sessionId / session_id 双拼写兼容
       if(ev.sessionId || ev.session_id) ctx.onSession(ev.sessionId || ev.session_id);
@@ -308,6 +351,25 @@ function qaStreamApplyOne(ev, ctx){
       qaRunEnd(h);
       ctx.onError(ev);
       break;
+    /* ⚠️ 上游的**异常终态**（magic-agent 的 KindTurnFailed，2026-10-10）：
+       「引擎没走完协议（没吐 result 行）」与「引擎把限流/额度通告当正文发回来」两种情形
+       都由它收尾 —— 判决书（error / reason）与**剥掉通告的正文**（text）都在事件上，
+       是 magic-agent 那边**统一封装**过的（用户 2026-10-10 定调：「应该是给 magic-agent 的
+       返回统一这种异常的封装 然后才是 ui 线上」）。界面因此**不需要认识通告长什么样**：
+       这里只管按终态收尾，与 error 分支逐条一致。
+       与 error 的差别只有一处：它**带正文** —— 流式时那半句通告早就拼进气泡了，
+       拿 Text 覆盖一次才算真的「没混在回复里」（覆盖的是权威全文，见 setResult → rerenderAll）。 */
+    case "turn_failed":
+      if(ev.text){
+        if(typeof h.setResult === "function") h.setResult(ev.text);
+        /* 台账同源（同上：画面与台账都跟权威正文走，否则历史重画又冒出那句通告） */
+        if(ctx && typeof ctx.onResult === "function") ctx.onResult(ev.text);
+      }
+      if(ev.sessionId || ev.session_id) ctx.onSession(ev.sessionId || ev.session_id);
+      h.endThinking(); finishTools(false);
+      qaRunEnd(h);
+      ctx.onError(ev);
+      break;
     /* 过程提示（**不是**终态事件）：主进程用它说「这一轮正在自动换模型重试」这类事
        （2026-09-21 起对话侧的模型来自配置界面的降级链，前一个没额度就自动换下一个）。
        落成一行轻量注脚（h.note，与 system 事件同一处渲染），**不收尾**——
@@ -321,6 +383,43 @@ function qaStreamApplyOne(ev, ctx){
                    detail: Object.assign({}, ev, { kind: "notice" }), status: ev.status || "" });
       else if(typeof h.note === "function") h.note(String(ev.text || ev.notice || ""));
       break;
+    /* 模型产出的图片（KindImage，见 internal/agent/stream.go）：`text` 就是图片本体
+       `data:<media_type>;base64,…`。图算**正文的一部分**（对齐 h.appendImage 的约定：
+       插在当前正文块的打字预览之前，图后到的文字自然排在图下）。
+       ⚠️ 以前这里没有分支 → 这个事件掉进 default，被落成一条「未识别事件 · image」标记行。
+          信息没丢、形态不对：`qaEventNormalize` 那边对 `assistant.message.content[]` 里的
+          image 块也是「不进对话流」的同一条口径 —— 两处一起看，别再让它退回去。
+       旧手柄没有 appendImage → 静默略过（不画错、也不留噪音）。 */
+    case "image":
+      if(ev.text && typeof h.appendImage === "function") h.appendImage(String(ev.text));
+      break;
+    /* 斜杠命令节点的生命周期帧（core 的 cli/ask.go::emitCommand：开跑一条、收尾一条）。
+       状态词表与宿主同一套取值：running / completed / cancelled / failed。
+       ⚠️ 与 notice 同理，以前走 default → 标题是「未识别事件 · command」，
+          而它其实是**认得的**事件（只是本版渲染器没给形态）。 */
+    case "command": {
+      const st = String(ev.status || "");
+      const bad = (st === "cancelled" || st === "failed");
+      const label = st === "running" ? "进行中" : st === "completed" ? "已完成" : bad ? "失败" : "";
+      const title = String(ev.text || "命令");
+      if(typeof h.marker === "function")
+        h.marker({ icon: QA_V_ICONS.terminal, title, status: label, destructive: bad,
+                   detail: Object.assign({}, ev, { kind: "command" }) });
+      else if(typeof h.note === "function") h.note(title);
+      break;
+    }
+    /* 控制通道的失败**必须说出来**：用户点了打断 / 作答却没生效，静默就等于「按钮坏了」
+       （core 的 control.go 专发这条票）。以前它走 default（能看见，但标题是
+       「未识别事件 · control_error」，把「谁发的指令失败了」这条关键信息说反了）。 */
+    case "control_error": {
+      const why = String(ev.error || ev.reason || "");
+      const title = "控制失败" + (why ? " · " + why : "");
+      if(typeof h.marker === "function")
+        h.marker({ icon: QA_V_ICONS.alert, title, status: "failed", destructive: true,
+                   detail: Object.assign({}, ev, { kind: "control_error" }) });
+      else if(typeof h.note === "function") h.note(title);
+      break;
+    }
     case "end":
       h.endThinking(); finishTools(true);
       qaRunEnd(h);
@@ -345,11 +444,28 @@ function qaStreamApplyOne(ev, ctx){
            · ev.session_id  = 该轮会话 id → 绑到任务上（下一轮追问续接同一会话）
          其余收尾动作与 "end" 完全一致（收思考区/工具卡/运行胶囊 + 快照 + 状态落库）。 */
       if(ev.text) h.setResult(ev.text);
+      /* 同上：台账也跟着权威正文走（两条路同一个理由，见 result 分支那段注释）。 */
+      if(ev.text && ctx && typeof ctx.onResult === "function") ctx.onResult(ev.text);
       if(ev.session_id) ctx.onSession(ev.session_id);
       h.endThinking(); finishTools(true);
       qaRunEnd(h);
       ctx.onDone({ ok: true, code: 0, text: ev.text || "" });
       break;
+    /* 控制通道应答与握手行（`--events` 形态专属，见 magic-agent 的 internal/cli/events.go /
+       control.go）—— 对话稿不落笔：
+         · `ready` 是 `--events` 的握手首行（谁在跑 / 契约版本），纯 plumbing；
+         · `pong` / `interrupted` / `stopped` / `answered` / `answer_queued` 是「谁在跑」那套
+           控制通道的回执，而本应用的停止走 `--stop`、作答走 `--append`，收尾一律看
+           turn_end / result / error —— 它们到了也不改变画面。
+       都不认识就会被下面 default 落成「未识别事件」标记行，把画布糊成一片垃圾。
+       ⚠️ `control_error` **不在此列**：那是「你自己发的控制指令失败了」，该看得见（走 default）。 */
+    case "ready":
+    case "pong":
+    case "interrupted":
+    case "stopped":
+    case "answered":
+    case "answer_queued":
+      break;
     default:
       /* 形态不认识 ≠ 内容丢掉（2026-09-28，对齐 anywhere 的 UnknownTimelineItem）。
          原来是静默 break：引擎上了新事件类型，画面上「什么都没发生」，
@@ -364,4 +480,3 @@ function qaStreamApplyOne(ev, ctx){
       break;                                   // 心跳 / 日志等刻意噪音：忽略
   }
 }
-

package/client-ui/shared/conv/10-markdown-render.js

@@ -0,0 +1,252 @@
+/* ---------- 完整 Markdown 渲染器（专业栈：marked + DOMPurify + highlight.js）----------
+   解析：marked（GFM）——表格对齐 / 任务列表 / 删除线 / 自动链接 / 围栏语言标签，
+        远超手写正则的边界正确性（嵌套列表、松散列表、行内混排等）。
+   净化：DOMPurify——文档正文多来自网页采集（不可信源），渲染后必须消毒，
+        防脚本 / 事件属性注入；放行 title / target / align / class 等阅读必需属性。
+   高亮：highlight.js——代码块按 ```lang 自动着色（hljs.highlightElement）。
+        ⚠️ 它是**按需加载**的（2026-09-19）：129KB，只有真渲染出代码块时才注入，
+        见下方 loadHljs()，不要在 index.html 里同步引它。
+   保留契约：仍返回 { html, anchors }。anchors 为标题索引（level/text/id），
+        供右侧目录（.md-toc）点击定位；标题锚点 id 稳定（h-1 / h-2 …），
+        悬停显示「#」。与既有的 .md-body 版式 / .doc-reader 结构完全对接。 */
+
+const MD_STACK_READY = (typeof marked !== "undefined") && (typeof DOMPurify !== "undefined");
+let _mdAnchors = [], _mdHSeq = 0;
+
+/** 取纯文本（去行内标记），用于目录标题 */
+function mdPlainText(s){
+  return String(s||"")
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g,"$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g,"$1")
+    .replace(/`([^`]*)`/g,"$1")
+    .replace(/\*\*([^*]+)\*\*/g,"$1").replace(/__([^_]+)__/g,"$1")
+    .replace(/\*([^*]+)\*/g,"$1").replace(/_([^_]+)_/g,"$1")
+    .replace(/~~([^~]+)~~/g,"$1")
+    .replace(/\s+/g," ").trim();
+}
+
+/* 一次性配置 marked 渲染器：
+   - heading  → 稳定锚点 id + 收集目录 + 「#」锚点（.h-anc，::before 出 # 号）
+   - code     → 保留 code-lang 角标 + hljs 类，随后由 highlightElement 上色
+   - listitem → GFM 任务项改写成既有 .task-li 结构；普通项回退默认渲染
+   - link     → 外链加 target=_blank rel=noopener，防钓鱼落页 */
+if(MD_STACK_READY){
+  marked.use({
+    gfm:true,
+    breaks:false,
+    renderer:{
+      heading(tok){
+        const inner = this.parser.parseInline(tok.tokens||[]);
+        const id = "h-" + (++_mdHSeq);
+        _mdAnchors.push({ level:tok.depth, text:mdPlainText(tok.text), id });
+        return `<h${tok.depth} id="${id}">${inner}<a class="h-anc" href="#${id}" title="定位此标题" aria-hidden="true"></a></h${tok.depth}>\n`;
+      },
+      code(tok){
+        const lang = String(tok.lang||"").split(/\s+/)[0];
+        const cls = "hljs" + (lang ? " language-" + lang : "");
+        // 转义代码正文：既保证 <tag> 原样显示，也避免消毒阶段误删
+        const body = String(tok.text||"")
+          .replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
+        return `<pre>${lang?`<span class="code-lang">${lang}</span>`:""}<code class="${cls}">${body}</code></pre>\n`;
+      },
+      listitem(tok){
+        if(tok.task){
+          const body = this.parser.parse(tok.tokens||[], !!tok.loose);
+          return `<li class="task-li${tok.checked?" done":""}"><span class="bx">✓</span><span class="tx">${body}</span></li>\n`;
+        }
+        return false;   // 回退 marked 默认（保留嵌套 <ul>/<ol>）
+      },
+      link(tok){
+        const text = this.parser.parseInline(tok.tokens||[]);
+        const href = String(tok.href||"");
+        const ti = tok.title ? ` title="${tok.title}"` : "";
+        const ext = /^https?:/i.test(href);
+        /* 本地文件链接（2026-10-14 用户：「点击不了」）——
+           引擎回复里给交付物写的就是 `[01-draft-concept.png](file:///Users/…png)`，
+           而 DOMPurify 的协议白名单（默认只放行 http/https/mailto/tel/cid/xmpp）
+           会**连 href 一起摘掉** file: —— 落进 DOM 的就是一枚没有地址的 <a>，
+           点它什么都不会发生（这正是用户看到的那一幕）。
+           而「放行 href」更糟：工作台主窗口没有 will-navigate 拦截，默认行为是把
+           **整个窗口**导航走 —— 点一下工作台就变成一张图（别处已警告过这个坑）。
+           所以本地链接一律**不带 href**，地址放进 data-local，由渲染层接管
+           （点击分流见 05-task-list-render.js 的委托）。data-* 消毒默认放行，不必动白名单。 */
+        if(!/^(?:https?:|mailto:|tel:|#)/i.test(href)){
+          return `<a data-local="${escHtml(href)}"${ti}>${text}</a>`;
+        }
+        return `<a href="${href}"${ext?' target="_blank" rel="noopener"':""}${ti}>${text}</a>`;
+      },
+    },
+  });
+}
+
+/** 手写兜底：vendor 未加载时仍能阅读（仅线性块级，极端降级） */
+function mdFallback(src){
+  const esc = (s)=>String(s??"").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
+  let html = "", inCode = false, buf = [];
+  const flushPara = ()=>{ if(buf.length){ html += "<p>" + esc(buf.join(" ")) + "</p>"; buf = []; } };
+  String(src||"").split(/\r?\n/).forEach((ln)=>{
+    if(/^\s*```/.test(ln)){ flushPara(); if(inCode){ html += `<pre><code>${esc(buf.join("\n"))}</code></pre>`; buf=[]; } inCode=!inCode; return; }
+    if(inCode){ buf.push(ln); return; }
+    const hm = /^(#{1,6})\s+(.*)$/.exec(ln);
+    if(hm){ flushPara(); const lv=hm[1].length, id="h-"+(++_mdHSeq);
+      _mdAnchors.push({level:lv,text:mdPlainText(hm[2]),id});
+      html += `<h${lv} id="${id}">${esc(hm[2])}</h${lv}>`; return; }
+    if(/^\s*$/.test(ln)){ flushPara(); return; }
+    buf.push(ln.trim());
+  });
+  flushPara();
+  return html;
+}
+
+/** 把「独占一行的图片路径」变成 markdown 图片，让对话里**直接看到图**（2026-09-19）。
+ *
+ *  为什么需要：引擎产出/引用的截图通常写成**一行绝对路径**（或本项目入库时的 `[图片] <路径>`），
+ *  不是 markdown —— 不转的话对话里只有一行字，看不到图；而飞书那边的完成回执也会把同一批图
+ *  上传成内联图（见 feishu-bridge.cjs::extractImageRefs），两边口径对齐。
+ *
+ *  ⚠️ 只认**独占一行**的绝对路径 + 常见图片扩展名：
+ *    · 不碰行内路径（正文里提到 `src/js/xxx.png` 不该变成图）；
+ *    · 路径里不含空格 / 引号 / 括号（含了就不转，免得把 markdown 语法拼坏）；
+ *    · alt 也填路径 —— 图加载不出来时还能看见它指向哪。 */
+function mdLocalizeImagePaths(src){
+  const EX = "png|jpe?g|gif|webp|bmp";
+  return String(src||"")
+    // 本项目入库时给飞书图片的写法：`[图片] /abs/x.png`
+    .replace(new RegExp("^[ \\t]*\\[图片\\][ \\t]*(/\\S+\\.(?:" + EX + "))[ \\t]*$", "gim"),
+      (_a, p) => `![${p}](${p})`)
+    // 裸路径独占一行
+    .replace(new RegExp("^[ \\t]*(/[^\\s`'\"()<>]+\\.(?:" + EX + "))[ \\t]*$", "gim"),
+      (_a, p) => `![${p}](${p})`);
+}
+
+/** 渲染 Markdown → { html, anchors } */
+function mdToHtml(src){
+  _mdAnchors = []; _mdHSeq = 0;
+  src = mdLocalizeImagePaths(src);
+  if(!MD_STACK_READY){ return { html: mdFallback(src), anchors: _mdAnchors }; }
+  let raw;
+  try{
+    raw = marked.parse(String(src||""));
+  }catch(e){
+    console.warn("[md] marked 解析失败，回退简易渲染：", e && e.message);
+    return { html: mdFallback(src), anchors: _mdAnchors };
+  }
+  // 消毒：放行阅读必需的属性 / 标签；禁 script、事件属性、javascript: 协议
+  const html = DOMPurify.sanitize(raw, {
+    ADD_ATTR: ["target", "rel", "align", "class", "id", "title", "disabled", "checked", "type"],
+    FORBID_TAGS: ["script", "style", "iframe", "form", "input"],
+    FORBID_ATTR: ["onerror", "onload", "onclick", "style"],
+  });
+  return { html, anchors: _mdAnchors };
+}
+
+/** 只取 HTML（兼容旧调用） */
+function mdToHtmlOnly(src){ return mdToHtml(src).html; }
+
+/* ---------- highlight.js 按需加载（2026-09-19）----------
+   129KB，比 marked + purify + floating-ui 加起来还大 —— 但只有真渲染出代码块时才用得到。
+   原来它在 index.html 里同步加载，每次启动都白解析一遍。现在首次需要时才注入；
+   注入完成前代码块以纯文本呈现（下面的 typeof hljs 分支本来就兜住了，不影响功能）。
+   流式渲染每闭合一段都会调一次 highlightIn → 加载期间可能登记多个根节点，
+   用 Set 去重，加载完统一补扫一遍。 */
+let _hljsLoading = false;
+const _hljsPending = new Set();
+function loadHljs(){
+  if(typeof hljs !== "undefined" || _hljsLoading) return;
+  _hljsLoading = true;
+  const s = document.createElement("script");
+  /* 高亮库的地**由宿主定**：内核自己的目录不一定是页面的相对根
+     （PC 宿主在 /pc/ 下、移动端在 /m/ 下、magic-test 是整包拼成一个 app.js）——
+     宿主没给就落回默认相对路径 `vendor/highlight.min.js`（magic-test 那种布局正是这样）。 */
+  s.src = (typeof window !== "undefined" && window.QA_HLJS_URL) || "vendor/highlight.min.js";
+  s.onload = () => {
+    _hljsLoading = false;
+    _hljsPending.forEach((r)=>{ try{ highlightIn(r); }catch(e){ /* 节点可能已卸载，忽略 */ } });
+    _hljsPending.clear();
+  };
+  s.onerror = () => { _hljsLoading = false; };   // 加载失败就一直纯文本，不影响功能
+  document.head.appendChild(s);
+}
+
+/** 对已插入 DOM 的代码块执行语法高亮；hljs 还没就绪就先登记，加载完补扫。
+ *  ⚠️ 先查有没有代码块再决定要不要惊动 129KB —— 渲染普通文档（无 ``` 块）时
+ *  highlightIn 照样会被调一次，不能让它把 highlight.js 白拉下来。
+ *  ⚠️ mermaid 块排在 hljs 之前处理：它有自己的渲染链路，而且是异步的，
+ *     不能等 hljs 就绪（两者互不依赖）。 */
+function highlightIn(root){
+  if(!root) return;
+  mermaidIn(root);
+  const blocks = root.querySelectorAll("pre code");
+  if(!blocks.length) return;
+  if(typeof hljs === "undefined"){ _hljsPending.add(root); loadHljs(); return; }
+  blocks.forEach((el)=>{
+    if(el.dataset.hl) return;
+    try{ hljs.highlightElement(el); el.dataset.hl = "1"; }catch(e){ /* 未知语言静默跳过 */ }
+  });
+}
+
+/* ---------- mermaid 流程图按需渲染（2026-10-10 用户「markdown能有流程图吗」）----------
+   产品文档的「## 功能流程」段是 ```mermaid 围栏（源码由 requirements.cjs::renderFlowMermaid
+   拼出来，保证语法合法）。这里把它渲染成图 —— 与 highlight.js 同一套「按需 + 可失败」纪律。
+
+   ⚠️ 为什么走 CDN 而不是塞进 vendor/：mermaid 单文件 2MB+（highlight.js 才 129KB），
+      为偶尔看一眼流程图把它打进包不划算。它是**渐进增强**：加载成功出图，
+      失败 / 离线就**保留那块代码** —— mermaid 源码本身是可读的，读者照样能看懂流程，
+      不会像图片那样变成一个红叉。取舍与 loadWebFonts（1.5s 超时回落本地字体栈）一致。
+   ⚠️ 渲染出的 SVG 由 mermaid 自己生成，**不经过 DOMPurify** ——
+      所以 securityLevel 必须保持 "strict"（它会自行消毒），不要开 htmlLabels。 */
+const MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js";
+let _mmLoading = false, _mmReady = false, _mmSeq = 0;
+const _mmPending = new Set();
+
+/** 对已插入 DOM 的根节点里的 ```mermaid 块出图（幂等：同一块只处理一次） */
+function mermaidIn(root){
+  if(!root) return;
+  const blocks = root.querySelectorAll("pre > code.language-mermaid, pre > code.lang-mermaid");
+  if(!blocks.length) return;
+  if(_mmReady){ try{ renderMermaidBlocks(root); }catch(e){ /* 单块失败不影响别的块 */ } return; }
+  _mmPending.add(root);
+  if(_mmLoading) return;
+  _mmLoading = true;
+  const s = document.createElement("script");
+  s.src = MERMAID_CDN;
+  s.onload = () => {
+    _mmLoading = false; _mmReady = true;
+    /* 主题跟着壳走：中性主题的连线是深灰，落在暗色卡片上会直接看不见（见 app.css 的 .md-mermaid）。
+       ⚠️ palette 只在**首次加载**时定；不刷新就切明暗的话，已出的图保持旧配色
+          （图自带底色，仍可读）—— 为这点小事把已渲染的图全部重跑一遍不值。 */
+    const dark = (document.documentElement.getAttribute("data-theme") === "dark");
+    /* fontSize:13 —— mermaid 默认 16px，图会明显偏大（用户 2026-10-10：「显示的太大了」）。
+       13px 与正文的 caption 档接近，图里的字仍然清楚，整张图小一圈。 */
+    try{ window.mermaid.initialize({ startOnLoad:false, securityLevel:"strict",
+      theme: dark ? "dark" : "neutral", themeVariables: { fontSize: "13px" } }); }
+    catch(e){ /* 初始化失败 → 后面每个 render 各自兜住，退化成代码块 */ }
+    _mmPending.forEach((r)=>{ try{ renderMermaidBlocks(r); }catch(e){ /* 节点可能已卸载 */ } });
+    _mmPending.clear();
+  };
+  s.onerror = () => { _mmLoading = false; };   // 加载失败：一直保留代码块，不影响阅读
+  document.head.appendChild(s);
+}
+
+/** 把 root 里还没出图的 ```mermaid 块替换成渲染结果。
+ *  ⚠️ mermaid 的渲染 id 只能含 [A-Za-z0-9_-] 且**不能重复**（重复会抛），故用自增序号；
+ *     每块的状态记在 pre.dataset.mmState 上，避免流式渲染时同一块被反复处理。 */
+function renderMermaidBlocks(root){
+  const blocks = root.querySelectorAll("pre > code.language-mermaid, pre > code.lang-mermaid");
+  blocks.forEach((codeEl)=>{
+    const pre = codeEl.parentElement;
+    if(!pre || pre.dataset.mmState) return;
+    pre.dataset.mmState = "pending";
+    const src = codeEl.textContent || "";
+    const id = "mm-" + (++_mmSeq);
+    Promise.resolve()
+      .then(()=> window.mermaid.render(id, src))
+      .then((res)=>{
+        const box = document.createElement("div");
+        box.className = "md-mermaid";
+        box.innerHTML = (res && res.svg) || "";
+        pre.replaceWith(box);
+      })
+      .catch(()=>{ pre.dataset.mmState = "failed"; });   // 出图失败 → 原地留代码块，不阻断阅读
+  });
+}