@xiaobuyu/nodesign 0.0.1

package/server/lib/tavern-json.js

@@ -0,0 +1,154 @@
+/**
+ * tavern-json —— 酒馆（SillyTavern）导出 JSON 的解析与摘要（2026-08-15）
+ *
+ * 起因是一份真文件：`Izumi 0814.json`，464KB、210 条提示词，而**启用的只有 56 条**
+ * （合计约 9.8k 字符）。agent 拿 Read 去读它 = 十几万 token 进上下文换来一堆停用
+ * 的备选条目 —— 这不是"贵一点"，是把上下文烧光还看不清结构。所以搬酒馆的东西
+ * 进来必须先过这一层：**先给结构摘要，再按需取正文**。
+ *
+ * 认三种形态（酒馆导出的 JSON 就这几类）：
+ *   preset   Chat Completion 预设 —— `prompts[]` + `prompt_order[]`。管的是
+ *            "每次请求怎么拼上下文 + 采样参数"，跟我们的 编排.yaml 同类。
+ *            条目里那些 0 字的是 **marker**（角色描述/性格/场景/Chat History…），
+ *            运行时由酒馆填真内容，搬过来一律丢掉 —— 我们由 编排.yaml 自己管。
+ *   card     角色卡 V2（`spec: chara_card_v2`）或 V1。人设、开场白、示例对话，
+ *            可能内嵌世界书（character_book）。
+ *   lorebook 世界书单独导出 —— `entries`，每条带 keys（触发词）与 constant（常驻）。
+ *
+ * 只读不写：转成 编排.yaml 和设定文件是 agent 的活，它得按题材决定怎么分组、
+ * 哪些不要（破甲话术在我们这条通路上没意义）。
+ */
+
+/** 摘要里每条正文最多带多少字的引子 */
+const PEEK = 60;
+
+export function detectKind(doc) {
+  if (!doc || typeof doc !== 'object') return null;
+  if (Array.isArray(doc.prompts) && Array.isArray(doc.prompt_order)) return 'preset';
+  if (doc.spec === 'chara_card_v2' || doc.spec === 'chara_card_v3') return 'card';
+  if (doc.data && typeof doc.data === 'object' && typeof doc.data.first_mes === 'string') return 'card';
+  if (typeof doc.first_mes === 'string' && typeof doc.description === 'string') return 'card';
+  if (doc.entries && typeof doc.entries === 'object') return 'lorebook';
+  return null;
+}
+
+const 引 = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, PEEK);
+const 字 = (s) => String(s || '').length;
+
+/** 预设：启用的条目按 order 顺序排开，停用的只报个数 */
+export function digestPreset(doc) {
+  const byId = new Map((doc.prompts || []).map(p => [p.identifier, p]));
+  const order = (doc.prompt_order?.[0]?.order) || [];
+  const 启用 = [];
+  const 停用 = [];
+  for (const o of order) {
+    const p = byId.get(o.identifier);
+    if (!p) continue;
+    const 条 = {
+      id: p.identifier,
+      名字: p.name || p.identifier,
+      角色: p.role || 'system',
+      字数: 字(p.content),
+      占位: p.marker === true,                       // 运行时由酒馆填（角色卡/历史）
+      分隔: p.marker !== true && 字(p.content) === 0,  // 纯分节标题（"可选功能开始"这种）
+      深度: p.injection_position === 1 ? (p.injection_depth ?? 0) : null,
+      引子: 引(p.content),
+    };
+    (o.enabled ? 启用 : 停用).push(条);
+  }
+  const 实条 = 启用.filter(e => e.字数 > 0);
+  return {
+    形态: 'preset',
+    参数: {
+      temperature: doc.temperature, top_p: doc.top_p, top_k: doc.top_k,
+      frequency_penalty: doc.frequency_penalty, presence_penalty: doc.presence_penalty,
+      最大上下文: doc.openai_max_context, 最大输出: doc.openai_max_tokens,
+      reasoning_effort: doc.reasoning_effort, squash_system_messages: doc.squash_system_messages,
+    },
+    启用, 停用,
+    合计字数: 实条.reduce((n, e) => n + e.字数, 0),
+    占位条目: 启用.filter(e => e.占位).map(e => e.名字),
+    分隔条目: 启用.filter(e => e.分隔).map(e => e.名字),
+  };
+}
+
+/** 角色卡：字段清单 + 内嵌世界书条目表 */
+export function digestCard(doc) {
+  const d = doc.data && typeof doc.data === 'object' ? doc.data : doc;
+  const 字段 = ['name', 'description', 'personality', 'scenario', 'first_mes', 'mes_example',
+    'system_prompt', 'post_history_instructions', 'creator_notes']
+    .map(k => ({ 字段: k, 字数: 字(d[k]), 引子: 引(d[k]) }))
+    .filter(x => x.字数 > 0);
+  const book = d.character_book || doc.character_book || null;
+  return {
+    形态: 'card',
+    名字: d.name || '(无名)',
+    字段,
+    开场白备选: Array.isArray(d.alternate_greetings) ? d.alternate_greetings.length : 0,
+    世界书: book ? digestLorebook(book).条目 : [],
+  };
+}
+
+/** 世界书：每条的触发词、常驻与否、字数 */
+export function digestLorebook(doc) {
+  const raw = doc.entries;
+  const list = Array.isArray(raw) ? raw : Object.values(raw || {});
+  const 条目 = list.map((e, i) => ({
+    id: String(e.uid ?? e.id ?? i),
+    名字: e.comment || e.name || (Array.isArray(e.key) ? e.key.join('/') : '') || `条目${i + 1}`,
+    触发: Array.isArray(e.key) ? e.key : (Array.isArray(e.keys) ? e.keys : []),
+    常驻: !!(e.constant),
+    停用: e.enabled === false || e.disable === true,
+    字数: 字(e.content),
+    引子: 引(e.content),
+  }));
+  return { 形态: 'lorebook', 条目 };
+}
+
+export function digest(doc) {
+  const kind = detectKind(doc);
+  if (kind === 'preset') return digestPreset(doc);
+  if (kind === 'card') return digestCard(doc);
+  if (kind === 'lorebook') return digestLorebook(doc);
+  return null;
+}
+
+/**
+ * 按名字/id 取正文。名字支持部分匹配（酒馆的条目名带 emoji，让 agent 原样抄
+ * 一串 emoji 当参数是给自己找麻烦）。
+ * @returns {{名字: string, 角色?: string, 正文: string}[]}
+ */
+export function fetchEntries(doc, 选) {
+  const want = (选 || []).map(s => String(s).trim()).filter(Boolean);
+  if (!want.length) return [];
+  const kind = detectKind(doc);
+  let 池 = [];
+  if (kind === 'preset') {
+    池 = (doc.prompts || []).map(p => ({ id: p.identifier, 名字: p.name || p.identifier, 角色: p.role || 'system', 正文: String(p.content || '') }));
+  } else if (kind === 'lorebook' || (kind === 'card' && (doc.data?.character_book || doc.character_book))) {
+    const book = kind === 'lorebook' ? doc : (doc.data?.character_book || doc.character_book);
+    const list = Array.isArray(book.entries) ? book.entries : Object.values(book.entries || {});
+    池 = list.map((e, i) => ({
+      id: String(e.uid ?? e.id ?? i),
+      名字: e.comment || e.name || (Array.isArray(e.key) ? e.key.join('/') : `条目${i + 1}`),
+      正文: String(e.content || ''),
+    }));
+  }
+  if (kind === 'card') {
+    const d = doc.data && typeof doc.data === 'object' ? doc.data : doc;
+    for (const k of ['description', 'personality', 'scenario', 'first_mes', 'mes_example',
+      'system_prompt', 'post_history_instructions']) {
+      if (d[k]) 池.push({ id: k, 名字: k, 正文: String(d[k]) });
+    }
+    if (Array.isArray(d.alternate_greetings)) {
+      d.alternate_greetings.forEach((g, i) => 池.push({ id: `alt_greeting_${i}`, 名字: `alternate_greetings[${i}]`, 正文: String(g || '') }));
+    }
+  }
+  const 出 = [];
+  const 见 = new Set();
+  for (const w of want) {
+    const hit = 池.find(x => x.id === w) || 池.find(x => x.名字 === w) || 池.find(x => x.名字.includes(w));
+    if (hit && !见.has(hit.id)) { 见.add(hit.id); 出.push(hit); }
+  }
+  return 出;
+}

package/server/lib/video-variant.js

@@ -0,0 +1,237 @@
+/**
+ * lib/video-variant.js — 显示用视频派生档
+ *
+ * 跟 image-variant 同一套规矩：**磁盘上的原片是交付物，一个字节都不改；HTTP
+ * 显示路径发压过的派生档。** 导出仍然拷原片。
+ *
+ * ── 为什么视频比图片更需要这一层 ────────────────────────────────────
+ * 一张生图 3MB，一段 10 秒 1080p 的录屏可以是 40MB，而视频是**边下边播**的：
+ * 用户拖进度条会触发 Range 请求，播放器还会预取。没有压缩层的话，看一眼站点里
+ * 的一段演示视频就能吃掉几十 MB。
+ *
+ * ── 单核机器上的取舍 ──────────────────────────────────────────────
+ * 转码比图片贵一个数量级（一段 1 分钟 1080p 在这台机器上要几分钟），所以：
+ *   **请求路径永不转码。** 只查缓存，命中发派生档，没命中原样发原片。
+ *   转码一律排后台串行队列，跟图片预热共用同一条"一次只做一件"的纪律。
+ *   转码进行中再来请求，照发原片，不等不排队不阻塞。
+ *
+ * 输出规格：H.264 High + AAC，长边压到 1280，CRF 28，faststart（moov 前置，
+ * 否则浏览器要先下完整个文件才能起播）。选 H.264 不选 AV1/VP9 是因为软件编 AV1
+ * 在这台机器上是分钟级起步，而 H.264 有成熟的快速预设，画质够用体积也降得动。
+ *
+ * 缓存：<cacheDir>/videos/<sha1(路径|mtime|size|规格)>.mp4，跟图片同一套 key 口径。
+ *
+ * fail-soft：ffmpeg 不在 / 转码失败 / 探测失败，一律当作"没有派生档"，发原片。
+ */
+
+import path from 'node:path';
+import { platform } from '../runtime/platform.js';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+const CACHE_DIR = path.join(platform.cacheRoot, 'videos');
+
+/** 能转的源格式。都是浏览器能直接放的容器，转出来统一成 mp4 */
+const TRANSCODABLE = new Set(['.mp4', '.mov', '.webm', '.m4v', '.avi', '.mkv']);
+
+/** 小于这个的不转：几 MB 的短片压不出什么，还白烧几分钟 CPU */
+const MIN_SOURCE_BYTES = Number(process.env.NODESIGN_VIDEO_MIN_BYTES) || 3 * 1024 * 1024;
+
+const SPEC = Object.freeze({
+  maxDim: Number(process.env.NODESIGN_VIDEO_MAX_DIM) || 1280,
+  crf: Number(process.env.NODESIGN_VIDEO_CRF) || 28,
+  preset: process.env.NODESIGN_VIDEO_PRESET || 'veryfast',
+  audioKbps: 128,
+});
+
+const SPEC_TAG = `h264/${SPEC.maxDim}/crf${SPEC.crf}/${SPEC.preset}`;
+
+let ffmpegChecked = null;
+
+/** ffmpeg 在不在。查一次记住，不在就整个模块静默失效 */
+export async function hasFfmpeg() {
+  if (ffmpegChecked !== null) return ffmpegChecked;
+  ffmpegChecked = await new Promise((resolve) => {
+    const p = spawn('ffmpeg', ['-version'], { stdio: 'ignore' });
+    p.on('error', () => resolve(false));
+    p.on('close', (code) => resolve(code === 0));
+  });
+  if (!ffmpegChecked) console.warn('[video-variant] ffmpeg 不可用，视频一律发原片');
+  return ffmpegChecked;
+}
+
+export function isVideo(ext) {
+  return TRANSCODABLE.has(String(ext || '').toLowerCase());
+}
+
+function cacheKey(absPath, stat) {
+  return crypto.createHash('sha1')
+    .update(`${absPath}|${stat.mtimeMs}|${stat.size}|${SPEC_TAG}`)
+    .digest('hex');
+}
+
+function cachePathFor(absPath, stat) {
+  return path.join(CACHE_DIR, `${cacheKey(absPath, stat)}.mp4`);
+}
+
+/**
+ * 有没有现成的派生档。**只查缓存，绝不触发转码。**
+ * @returns {Promise<{path: string, size: number}|null>}
+ */
+export async function cachedVariant(absPath, stat) {
+  if (!isVideo(path.extname(absPath))) return null;
+  if (stat.size < MIN_SOURCE_BYTES) return null;
+  const p = cachePathFor(absPath, stat);
+  try {
+    const st = await fs.stat(p);
+    // 转出来比原片还大就当没有（短片 / 已经压过的片常见）
+    if (!st.isFile() || st.size >= stat.size) return null;
+    return { path: p, size: st.size };
+  } catch { return null; }
+}
+
+// ── 后台转码队列 ────────────────────────────────────────────────────
+// 串行。单核上两个 ffmpeg 同时跑等于两个都慢一倍，还把请求路径饿死。
+
+const queue = [];
+const queued = new Set();
+let running = false;
+const QUEUE_MAX = 200;
+
+async function transcode(absPath, stat, outPath) {
+  await fs.mkdir(CACHE_DIR, { recursive: true });
+  const tmp = `${outPath}.${process.pid}.tmp.mp4`;
+  const args = [
+    '-hide_banner', '-loglevel', 'error', '-nostdin',
+    '-i', absPath,
+    // 长边压到 maxDim，保持比例，宽高都取偶数（H.264 要求）
+    '-vf', `scale='if(gt(iw,ih),min(${SPEC.maxDim},iw),-2)':'if(gt(iw,ih),-2,min(${SPEC.maxDim},ih))'`,
+    '-c:v', 'libx264', '-preset', SPEC.preset, '-crf', String(SPEC.crf),
+    '-profile:v', 'high', '-pix_fmt', 'yuv420p',
+    '-c:a', 'aac', '-b:a', `${SPEC.audioKbps}k`,
+    // moov 前置：不加的话浏览器要下完整个文件才能起播
+    '-movflags', '+faststart',
+    '-y', tmp,
+  ];
+
+  await new Promise((resolve, reject) => {
+    const p = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let err = '';
+    p.stderr.on('data', (d) => { err += d.toString().slice(0, 2000); });
+    p.on('error', reject);
+    p.on('close', (code) => code === 0 ? resolve() : reject(new Error(err.trim() || `ffmpeg exit ${code}`)));
+  });
+
+  const out = await fs.stat(tmp);
+  if (out.size >= stat.size) {
+    // 没压小就别留着占地方，下次请求照发原片
+    await fs.rm(tmp, { force: true });
+    console.log(`[video-variant] ${path.basename(absPath)} 压不小（${out.size} ≥ ${stat.size}），丢弃`);
+    return;
+  }
+  await fs.rename(tmp, outPath);
+  console.log(`[video-variant] ${path.basename(absPath)} ${(stat.size / 1048576).toFixed(1)}MB → ${(out.size / 1048576).toFixed(1)}MB`);
+}
+
+async function drain() {
+  if (running) return;
+  running = true;
+  try {
+    while (queue.length) {
+      const job = queue.shift();
+      queued.delete(job.key);
+      try {
+        await transcode(job.absPath, job.stat, job.outPath);
+      } catch (err) {
+        console.warn(`[video-variant] 转码失败 ${path.basename(job.absPath)}: ${err.message}`);
+        await fs.rm(`${job.outPath}.${process.pid}.tmp.mp4`, { force: true }).catch(() => {});
+      }
+    }
+  } finally {
+    running = false;
+  }
+}
+
+/**
+ * 排一个后台转码。立即返回。已经在队列里 / 已经有缓存 / ffmpeg 不可用都直接跳过。
+ */
+export async function enqueueTranscode(absPath, stat) {
+  if (!isVideo(path.extname(absPath))) return;
+  if (stat.size < MIN_SOURCE_BYTES) return;
+  if (!await hasFfmpeg()) return;
+  const key = cacheKey(absPath, stat);
+  if (queued.has(key)) return;
+  const outPath = path.join(CACHE_DIR, `${key}.mp4`);
+  try { await fs.access(outPath); return; } catch { /* 没有，往下排 */ }
+  if (queue.length >= QUEUE_MAX) return;
+  queued.add(key);
+  queue.push({ absPath, stat, outPath, key });
+  drain();
+}
+
+export function transcodeQueueStats() {
+  return { pending: queue.length, running };
+}
+
+/**
+ * 发一段视频，支持 Range。
+ *
+ * Range 对视频是必需的，不是优化：没有 206 的话浏览器拖不动进度条，某些播放器
+ * 干脆拒绝播放。这条路由以前只会整个文件 res.end，视频一直是这么半残的。
+ *
+ * 派生档命中就发派生档，没命中发原片并把转码排进后台。同一个 URL 前后发的字节
+ * 会不一样（先原片后派生档），所以 ETag 必须跟着实际发的那份走。
+ */
+export async function sendVideo(req, res, absPath, stat, opts = {}) {
+  let servePath = absPath;
+  let size = stat.size;
+  let tag = `orig-${stat.mtimeMs}-${stat.size}`;
+
+  const variant = await cachedVariant(absPath, stat);
+  if (variant) {
+    servePath = variant.path;
+    size = variant.size;
+    tag = path.basename(variant.path, '.mp4');
+  } else {
+    enqueueTranscode(absPath, stat).catch(() => {});
+  }
+
+  const mime = variant ? 'video/mp4' : (opts.fallbackMime || 'application/octet-stream');
+  res.setHeader('Accept-Ranges', 'bytes');
+  res.setHeader('ETag', `"${tag}"`);
+  res.setHeader('Content-Type', mime);
+
+  const range = req.headers.range;
+  if (!range) {
+    res.setHeader('Content-Length', size);
+    const fh = await fs.open(servePath, 'r');
+    return fh.createReadStream().pipe(res).on('close', () => fh.close().catch(() => {}));
+  }
+
+  const m = /^bytes=(\d*)-(\d*)$/.exec(range.trim());
+  if (!m) {
+    res.setHeader('Content-Range', `bytes */${size}`);
+    return res.status(416).end();
+  }
+  let start = m[1] === '' ? null : Number(m[1]);
+  let end = m[2] === '' ? null : Number(m[2]);
+  if (start === null) {
+    // `bytes=-N` = 最后 N 字节
+    const n = end ?? 0;
+    start = Math.max(0, size - n);
+    end = size - 1;
+  } else {
+    end = end === null ? size - 1 : Math.min(end, size - 1);
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start >= size) {
+    res.setHeader('Content-Range', `bytes */${size}`);
+    return res.status(416).end();
+  }
+
+  res.status(206);
+  res.setHeader('Content-Range', `bytes ${start}-${end}/${size}`);
+  res.setHeader('Content-Length', end - start + 1);
+  const fh = await fs.open(servePath, 'r');
+  return fh.createReadStream({ start, end }).pipe(res).on('close', () => fh.close().catch(() => {}));
+}

package/server/lib/workspace-path.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+
+/**
+ * 工具入参里的 `file_path` → **工作区相对路径**。
+ *
+ * ## 为什么这件事必须在服务端做
+ *
+ * 画布上的物件 id 就是工作区相对路径（2026-08-08：`deck:鉴赏页/主稿.html`、
+ * `site:伊蕾娜手账研究站`、文件夹就是路径本身）。而 agent 的工具入参给的多半是
+ * **绝对路径**（Write / Edit 要求绝对），只有服务端知道工作区根在哪。
+ *
+ * 扁平化之前前端能自己抠：绝对路径里有 `tasks/<任务>/` 这个特征段，正则一锚就
+ * 拿到相对部分。`tasks/` 那层拆掉之后，绝对路径里**再没有任何可锚定的标志** ——
+ * 工作区根就是项目目录本身，名字是随机 id。前端猜不出来，也不该猜。
+ *
+ * 所以凡是要发给前端当"物件寻址依据"的路径，一律在 emit 之前过这一道。
+ * 漏掉的症状是**不报错**的：舞台卡认不出目标 → 静静地掉进屏幕底部的 dock，
+ * 看起来只是"agent 干活时画布没反应"。
+ *
+ * @param {string} filePath      绝对路径或相对 cwd 的路径
+ * @param {string} workspaceRoot 工作区根（agent 的 cwd）
+ * @returns {string} 工作区相对路径；不在工作区里的原样返回
+ */
+export function toWorkspaceRel(filePath, workspaceRoot) {
+  if (typeof filePath !== 'string' || !filePath) return '';
+  const p = filePath.replace(/\\/g, '/');
+  if (!workspaceRoot) return p;
+  const root = path.resolve(workspaceRoot);
+  const abs = path.isAbsolute(p) ? p : path.resolve(root, p);
+  // 工作区根自己 → 空串（"就是这张桌面"）；根之外的路径原样退回，让调用方决定
+  if (abs === root) return '';
+  return abs.startsWith(root + path.sep) ? abs.slice(root.length + 1) : p;
+}

package/server/ops/fix-sdk-musl.mjs

@@ -0,0 +1,40 @@
+/**
+ * server/ops/fix-sdk-musl.mjs — postinstall：修 SDK musl 误判
+ *
+ * 现象（DEPLOY.md § 故障排查已档，x64/arm64 都会中）：glibc 系统（Debian/Ubuntu）上
+ * SDK platform detection 误判成 musl，spawn `claude-agent-sdk-linux-<arch>-musl/claude`。
+ * 该 binary 链接 musl loader（/lib/ld-musl-*），glibc 系统没有 → spawn 失败，
+ * SDK 报 "native binary not found"。
+ *
+ * 修法：musl 包里的 binary 替换成指向同版本 glibc binary 的软链。
+ * npm install 会还原 node_modules，所以挂 postinstall 每次自动重打。
+ * 非 Linux / musl 系统（Alpine）/ 包不存在时静默跳过。
+ */
+
+import { existsSync, lstatSync, rmSync, symlinkSync } from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+if (os.platform() !== 'linux') process.exit(0);
+// 真 musl 系统（Alpine）不该动
+if (existsSync('/lib/ld-musl-x86_64.so.1') || existsSync('/lib/ld-musl-aarch64.so.1')) process.exit(0);
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const scope = path.join(root, 'node_modules', '@anthropic-ai');
+
+for (const arch of ['x64', 'arm64']) {
+  const glibcBin = path.join(scope, `claude-agent-sdk-linux-${arch}`, 'claude');
+  const muslBin = path.join(scope, `claude-agent-sdk-linux-${arch}-musl`, 'claude');
+  if (!existsSync(glibcBin) || !existsSync(path.dirname(muslBin))) continue;
+
+  try {
+    // 已经是软链就不重打（幂等）
+    if (existsSync(muslBin) && lstatSync(muslBin).isSymbolicLink()) continue;
+    rmSync(muslBin, { force: true });
+    symlinkSync(path.join('..', `claude-agent-sdk-linux-${arch}`, 'claude'), muslBin);
+    console.log(`[fix-sdk-musl] linked ${arch}-musl/claude -> ${arch}/claude`);
+  } catch (err) {
+    console.warn(`[fix-sdk-musl] skip ${arch}: ${err.message}`);
+  }
+}

package/server/ops/install-macos-fonts.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+#
+# install-macos-fonts.sh — 把上传到 server 的 macOS 字体装到 Linux 系统
+# + 应用 fontconfig 让 generic family 命中苹果字体。
+#
+# 前提：先从 Mac 拷字体到 server 的 ~/macos-fonts/ 目录。最少需要：
+#   PingFang.ttc       — /System/Library/Fonts/PingFang.ttc
+#   Songti.ttc         — /System/Library/Fonts/Songti.ttc
+# 推荐补：
+#   STHeiti Light.ttc  — /System/Library/Fonts/STHeiti Light.ttc
+#   STHeiti Medium.ttc — /System/Library/Fonts/STHeiti Medium.ttc
+#   Helvetica.ttc      — /System/Library/Fonts/Helvetica.ttc
+#   SF-Pro.ttf         — Apple 官网下载（developer.apple.com/fonts/）
+#   SF-Pro-Display.ttf — 同上
+#   SF-Pro-Text.ttf    — 同上
+#   SF-Mono.ttf        — 同上
+#
+# 从 Mac 拷的命令示例（在 Mac 上跑）：
+#   scp /System/Library/Fonts/PingFang.ttc \
+#       /System/Library/Fonts/Songti.ttc \
+#       "/System/Library/Fonts/STHeiti Light.ttc" \
+#       "/System/Library/Fonts/STHeiti Medium.ttc" \
+#       /System/Library/Fonts/Helvetica.ttc \
+#       user@server:~/macos-fonts/
+#
+# 在 server 上跑：
+#   sudo bash server/ops/install-macos-fonts.sh
+#
+# ⚠️ 法律：苹果字体仅限内部使用，禁止打包外传。这份 script 只装到 server 端
+# 系统字体目录，让 PDF/PPT 渲染时本地使用，不会嵌入 baked HTML 外传。
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FONT_SRC_DIR="${MACOS_FONT_SRC:-$HOME/macos-fonts}"
+FONT_DST_DIR="/usr/share/fonts/macos"
+FONTCONFIG_DST="/etc/fonts/conf.d/65-macos.conf"
+FONTCONFIG_DST_LEGACY="/etc/fonts/conf.d/99-macos.conf"  # 老位置，install 时清掉
+
+# ── 0. 必须 root 跑 ──
+if [ "$EUID" -ne 0 ]; then
+  echo "❌ 必须 sudo / root 跑（要写 /usr/share/fonts 和 /etc/fonts/conf.d）"
+  echo "   sudo bash $0"
+  exit 1
+fi
+
+# ── 1. 检查源目录 ──
+if [ ! -d "$FONT_SRC_DIR" ]; then
+  echo "❌ 找不到字体源目录：$FONT_SRC_DIR"
+  echo "   先从 Mac scp 字体过来，参考脚本头注释。"
+  echo "   或设 MACOS_FONT_SRC=/path/to/dir 环境变量再跑。"
+  exit 1
+fi
+
+shopt -s nullglob
+fonts=("$FONT_SRC_DIR"/*.ttc "$FONT_SRC_DIR"/*.ttf "$FONT_SRC_DIR"/*.otf)
+if [ ${#fonts[@]} -eq 0 ]; then
+  echo "❌ $FONT_SRC_DIR 里没找到 .ttc / .ttf / .otf 文件"
+  exit 1
+fi
+
+echo "📦 找到 ${#fonts[@]} 个字体文件："
+for f in "${fonts[@]}"; do echo "   - $(basename "$f")"; done
+echo
+
+# ── 2. 装到系统字体目录 ──
+echo "📥 拷贝到 $FONT_DST_DIR/"
+mkdir -p "$FONT_DST_DIR"
+cp -v "${fonts[@]}" "$FONT_DST_DIR/"
+
+# 权限：所有用户可读
+chmod 644 "$FONT_DST_DIR"/*
+
+# ── 3. 应用 fontconfig ──
+echo
+echo "⚙️  应用 fontconfig：$FONTCONFIG_DST"
+# 清理老位置（早期版本装到 99-，后来发现 69-language-selector-zh-cn.conf 反 override，
+# 改装到 65-）
+if [ -f "$FONTCONFIG_DST_LEGACY" ]; then
+  echo "🧹 清理老位置 $FONTCONFIG_DST_LEGACY"
+  rm -f "$FONTCONFIG_DST_LEGACY"
+fi
+cp -v "$SCRIPT_DIR/macos-fonts.conf" "$FONTCONFIG_DST"
+chmod 644 "$FONTCONFIG_DST"
+
+# ── 4. 刷字体缓存 ──
+echo
+echo "🔄 刷新 fontconfig 缓存（fc-cache -fv）"
+fc-cache -fv 2>&1 | tail -10
+
+# ── 5. 验证 ──
+echo
+echo "✅ 装完了。验证 generic family 是否命中苹果字体："
+echo
+echo "── fc-match serif（应该是 Songti SC 或 STSong 在前）──"
+fc-match -s serif | head -3
+echo
+echo "── fc-match sans-serif（应该是 PingFang SC 在前）──"
+fc-match -s sans-serif | head -3
+echo
+echo "── fc-match \"PingFang SC\"（应该返回 PingFang.ttc）──"
+fc-match "PingFang SC"
+echo
+echo "── fc-match \"Songti SC\"（应该返回 Songti.ttc）──"
+fc-match "Songti SC"
+echo
+echo "── fc-match \"system-ui\"（应该是 SF Pro Text 或 PingFang SC）──"
+fc-match -s system-ui | head -3
+
+echo
+echo "🎯 下一步：重启 NoDesign server 让 Chromium 重新读 fontconfig"
+echo "   pm2 restart nodesign"
+echo
+echo "   重启后导一份新中文 deck 的 PDF/PPT，跟 Mac preview 对比应该 1:1。"