@xiaobuyu/nodesign 0.0.1

package/server/lib/canvas-id.js

@@ -0,0 +1,36 @@
+/**
+ * canvas-id —— agent 侧画布 id 归一化（2026-08-14，摆位批）
+ *
+ * id = kind 前缀 + 工作区相对路径（board 的铁律）。agent 传进来的写法五花八门
+ * （反斜杠 / ./ 前缀 / 裸 .html），read_board / arrange_on_board / create_on_board
+ * 共用这一份归一。跟 pin_to_board 内联的那段同源同规则 —— 收敛计划里它也该
+ * 迁过来（现在没动它：改稳定工具要单独一刀）。
+ */
+
+export function normalizeCanvasId(raw) {
+  let id = String(raw || '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+  if (!id || id.includes('..')) return null;
+  if (id.endsWith('agent-memory/brand/memory.md')) return 'doc:brand';
+  if (id.endsWith('agent-memory/memory.md')) return 'doc:_root';
+  if (!/^(deck|site|doc|text|scribble):/.test(id) && /\.html?$/i.test(id)) return `deck:${id}`;
+  return id;
+}
+
+/**
+ * 它住在哪一层（服务端近似版）：显式 zone 字段优先，其次沿路径往上找第一个
+ * 已知文件夹。已知集 = board.zones 的 key —— 比前端少了"服务端扫出来的任务
+ * 目录"这一路，没摆过的深层目录会归到根。read_board 的输出里写明这是近似。
+ */
+export function layerOf(id, entry, knownFolders) {
+  if (entry && typeof entry.zone === 'string') return entry.zone;
+  const s = String(id);
+  if (s.startsWith('doc:')) return '';
+  const c = s.indexOf(':');
+  const p = (c > 0 && /^[a-z]+$/.test(s.slice(0, c))) ? s.slice(c + 1) : s;
+  let d = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '';
+  while (d && !knownFolders.has(d)) {
+    const i = d.lastIndexOf('/');
+    d = i > 0 ? d.slice(0, i) : '';
+  }
+  return d;
+}

package/server/lib/cover.js

@@ -0,0 +1,227 @@
+/**
+ * lib/cover.js — 项目封面（首页卡片缩略图）
+ *
+ * 为什么是截图而不是 iframe：
+ *   首页早期版本用 iframe 直接挂 canvas.html 当封面，且 sandbox 不给 allow-scripts
+ *   （一屏十几张卡，放开脚本等于每张卡都跑一遍生成页的动画 / 3D）。代价是**凡是靠
+ *   JS 出画面的产物封面全是空白**——站点的滚动揭示、three.js 场景、图表库全中招。
+ *   服务端截一次图就没这个矛盾：脚本在 chromium 里真跑，浏览器只收一张 webp。
+ *
+ * 选谁当封面：/artifacts 的口径——任务目录 mtime 新→旧，第一个真有产物的任务的
+ * artifacts[0]（形态注册表已经把 canvas.html / 根 index.html 排在别的稿前面）。
+ *
+ * 取景按形态：
+ *   deck — viewport = 真实画幅（16:9 / 16:10 / 9:16 / 4:3），整页入镜
+ *   site — 页面高度无上界，按桌面宽 1440 渲染取顶部一屏（首屏即封面）
+ *
+ * 缓存：<cacheDir>/<pid>/<sha1(任务|入口|mtime|宽)>.webp。key 带源 mtime，
+ * agent 改完产物下次请求自然重截；旧文件留着不清（一个项目也就攒几张几十 KB）。
+ * 并发：截图串行（chromium 一次一个），十张卡同时冷启也只排队不炸内存。
+ */
+
+import path from 'node:path';
+import { platform } from '../runtime/platform.js';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { taskManifest, can } from './kinds/index.js';
+import { resolveArtifactFile } from './artifact-file-path.js';
+import { resolveDeckSize, extractDeckAspect } from '../shared/deck.js';
+import { openArtifactPage, launchPerceptionBrowser } from '../engine/mcp/tools/helpers/perception-page.js';
+
+const SITE_VIEWPORT = { width: 1440, height: 900 };
+const OUT_WIDTH = 800;          // 出图宽度（卡片最宽也就 ~400 CSS px，2x 足够）
+const CACHE_DIR = path.join(platform.cacheRoot, 'covers');
+
+/** 截图串行闸门 —— 冷启动时十张卡同时请求也只有一个 chromium 在跑 */
+let renderChain = Promise.resolve();
+function serialize(fn) {
+  const next = renderChain.then(fn, fn);
+  renderChain = next.catch(() => {});
+  return next;
+}
+
+/**
+ * 选出项目封面产物。
+ * @returns {Promise<null | { taskId, kind, view, absPath, relPath, mtimeMs }>}
+ */
+export async function pickCoverArtifact(sharedDir) {
+  // 扁平化之前这里先按 mtime 把任务目录排个序，再从最新那个任务里取头一份产物。
+  // 现在产物都在工作区根上并排放着，直接按**产物**的 mtime 挑最新的那份。
+  const manifest = await taskManifest(sharedDir).catch(() => null);
+  const list = manifest?.artifacts || [];
+  const dated = [];
+  for (const art of list) {
+    try {
+      dated.push({ art, mtimeMs: (await fs.stat(path.join(sharedDir, art.entryRel))).mtimeMs });
+    } catch { /* 入口是声明出来的但还没写盘 → 换下一份 */ }
+  }
+  dated.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const { art } of dated) {
+    // ⚠️ 2026-08-18：docx 进来之后这里会挑到一个 .docx 当封面，chromium 打开它
+    // 只会触发 "Download is starting"，封面整个渲不出来（生产日志实锤）。
+    // 加形态时最容易漏的就是这种「默认所有产物都能用浏览器打开」的假设 ——
+    // 按能力位问，别按形态名问。renderable（docx）也能当封面：renderCoverShot
+    // 里按能力分流走 LO 页图，不进 chromium —— 纯 word 项目的首页卡不再开天窗。
+    if (!can(art.kind, 'browsable') && !can(art.kind, 'renderable')) continue;
+    const taskDir = sharedDir;
+    const absPath = path.join(taskDir, art.entryRel);
+    let fileMtime = 0;
+    try {
+      fileMtime = (await fs.stat(absPath)).mtimeMs;
+    } catch { continue; }   // 入口是声明出来的但还没写盘 → 换下一个任务
+    return {
+      taskId: null,
+      kind: art.kind,
+      view: art.view,
+      absPath,
+      relPath: art.entryRel,
+      mtimeMs: fileMtime,
+    };
+  }
+  return null;
+}
+
+/**
+ * 真正跑一次 chromium，返回 JPEG buffer。
+ * 导出是为了能单独对某个产物验证取景（缓存/选片逻辑之外的那一半）。
+ * @param {{ absPath: string, kind: 'deck'|'site' }} cover
+ * @param {{ projectId?: string, workspaceRoot?: string }} [pctx]
+ *   给了就走 http（与用户预览同源）—— 用 fetch 装内容的站点在 file:// 下
+ *   封面会是一张空白页。⚠️ 这里**允许静默退回 file://**：封面是给用户看的
+ *   缩略图，没有 agent 会被误导，宁可退化也别让首页卡片开天窗。
+ */
+export async function renderCoverShot(cover, pctx = {}) {
+  // renderable 产物（docx）没有 DOM：封面 = 第一页页图，跟画布缩略图同一份
+  // LibreOffice 缓存，别把二进制包喂给 chromium（那只会触发下载弹窗）
+  if (!can(cover.kind, 'browsable')) {
+    const { pageImage } = await import('./docx-pages.js');
+    return (await pageImage(cover.absPath, 1, { width: OUT_WIDTH })).buf;
+  }
+  const html = await fs.readFile(cover.absPath, 'utf8').catch(() => '');
+  const viewport = cover.kind === 'deck'
+    ? (() => { const d = resolveDeckSize(extractDeckAspect(html)); return { width: d.width, height: d.height }; })()
+    : SITE_VIEWPORT;
+
+  let browser;
+  try {
+    browser = await launchPerceptionBrowser();
+    const opened = await openArtifactPage(browser, {
+      projectId: pctx.projectId, workspaceRoot: pctx.workspaceRoot,
+      absPath: cover.absPath, viewport, deviceScaleFactor: 1, timeout: 20_000,
+    });
+    const ctx = opened.context;
+    const page = opened.page;
+    try {
+      await opened.goto();
+    } catch (err) {
+      if (!opened.viaHttp) throw err;
+      console.warn('[cover] http 加载失败，退回 file://:', err.message);
+      await page.goto('file://' + cover.absPath, { waitUntil: 'networkidle', timeout: 20_000 });
+    }
+    // 字体加载完再截（同导出管线的口径：CJK 子集是 lazy 的，不显式 load 会截到 fallback）
+    await page.evaluate(async () => {
+      document.body.offsetHeight;
+      await Promise.all(Array.from(document.fonts).map(f => f.load().catch(() => {})));
+      await document.fonts.ready;
+      await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+    }).catch(() => { /* 页面自己抛错也照样截，截到什么算什么 */ });
+    // deck 的 standalone-fit 脚本在真实 viewport 下会再缩一次，抹掉它
+    await page.addStyleTag({ content: `
+      body { margin: 0 !important; padding: 0 !important; }
+      body.__nd-fit-active > .__nd-deck-wrap > .__nd-page-frame {
+        width: ${viewport.width}px !important; height: ${viewport.height}px !important;
+        display: block !important; overflow: visible !important;
+      }
+      body.__nd-fit-active section[data-page] { transform: none !important; }
+    ` }).catch(() => {});
+    await page.waitForTimeout(600);   // 给入场动画 / 首帧渲染一点时间
+    const png = await page.screenshot({ type: 'png', clip: { x: 0, y: 0, ...viewport } });
+    await ctx.close();
+
+    const { default: sharp } = await import('sharp');
+    return await sharp(png)
+      .resize({ width: OUT_WIDTH, withoutEnlargement: true })
+      .webp({ quality: 80 })
+      .toBuffer();
+  } finally {
+    await browser?.close().catch(() => {});
+  }
+}
+
+/**
+ * 指定产物的封面目标（橱窗用：某件具体作品，不是"项目最新那件"）。
+ *
+ * @param {string} relPath  产物入口，相对工作区根。橱窗表里的存量数据是
+ *   扁平化之前的 `tasks/<任务>/<入口>`，前两段剥掉就是现在的位置。
+ */
+export async function resolveCoverTarget(sharedDir, relPath) {
+  // ⛔ 这里原来无条件剥掉 `tasks/<名>/` 前缀（跟 artifact-file 路由犯过同一个错，
+  // 那是**第三份**同样的判据）。而橱窗存的 artifact_rel 恰恰就是那个形状 ——
+  // 线上两条橱窗条目实测：文件真的在 `shared/tasks/伊蕾娜手账研究站/index.html`，
+  // 剥完变成 `shared/index.html`（不存在）→ 返 null → 封面接口 204 → **橱窗无图**。
+  // 收敛到 lib/artifact-file-path.js 那一份：先看原路径在不在，在就别动它。
+  const resolved = await resolveArtifactFile(sharedDir, String(relPath || '').replace(/\\/g, '/'));
+  if (!resolved.ok) return null;
+  const { absPath, subPath: rel } = resolved;
+  const taskDir = sharedDir;
+  let fileMtime = 0;
+  try {
+    fileMtime = (await fs.stat(absPath)).mtimeMs;
+  } catch { return null; }
+  const manifest = await taskManifest(taskDir).catch(() => null);
+  const art = manifest?.artifacts?.find(a => a.entryRel === rel) || manifest?.artifacts?.[0];
+  return {
+    taskId: null,
+    kind: art?.kind || 'site',   // 认不出来按 site 取景（首屏一屏，比硬套 16:9 安全）
+    view: art?.view || 'site',
+    absPath,
+    relPath: rel,
+    mtimeMs: fileMtime,
+  };
+}
+
+/**
+ * 拿项目封面 JPEG（命中缓存直接读盘，否则截一张）。
+ * @returns {Promise<null | { buffer, etag, cover }>}  没有任何产物时返回 null
+ */
+export async function getProjectCover(pid, sharedDir) {
+  const cover = await pickCoverArtifact(sharedDir);
+  if (!cover) return null;
+  return renderOrRead(pid, cover, sharedDir);
+}
+
+/** 指定产物的封面（橱窗卡片） */
+export async function getArtifactCover(pid, sharedDir, relPath) {
+  const cover = await resolveCoverTarget(sharedDir, relPath);
+  if (!cover) return null;
+  return renderOrRead(pid, cover, sharedDir);
+}
+
+async function renderOrRead(pid, cover, sharedDir) {
+  // ⚠️ key 里要带**渲染方式的版本**。08-18 感知层从 file:// 改走 http（同源，
+  // fetch/localStorage 才活），但缓存 key 只认 relPath|mtime|宽度 —— 于是改动
+  // 之前渲的封面（file:// 版，页面里 fetch 回来的内容一片空白）会一直供着，
+  // 直到 HTML 自己被改动。渲染管线换了就该换一代 key。
+  // v2（2026-08-19）：docx 字体替身换代（雅黑→MiSans、仿宋→朱雀仿宋），
+  // 封面里渲着 docx 页图的那批要跟着重截
+  const RENDER_GEN = 'http-v2';
+  const etag = crypto.createHash('sha1')
+    .update(`${cover.relPath}|${cover.mtimeMs}|${OUT_WIDTH}|${RENDER_GEN}`)
+    .digest('hex');
+  const file = path.join(CACHE_DIR, pid, `${etag}.webp`);
+
+  try {
+    return { buffer: await fs.readFile(file), etag, cover };
+  } catch { /* 未命中 → 截 */ }
+
+  const buffer = await serialize(async () => {
+    // 排队期间可能已经被前一个同 key 的请求截好了，再看一眼再动手
+    try { return await fs.readFile(file); } catch { /* */ }
+    const buf = await renderCoverShot(cover, { projectId: pid, workspaceRoot: sharedDir });
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, buf);
+    return buf;
+  });
+  return { buffer, etag, cover };
+}

package/server/lib/danbooru-tags.js

@@ -0,0 +1,291 @@
+/**
+ * server/lib/danbooru-tags.js — danbooru 标签收录量校验 + 查询（2026-08-18 起）
+ *
+ * ## 为什么需要
+ *
+ * danbooru 系模型（noobai / noobai-eps / pony）吃的是 danbooru 标签。标签写错
+ * **不会报错，只会静默失效** —— 模型收到的等于空气。一个 agent 在一轮长时间
+ * 配图里因此烧掉至少五轮出图，每次都是"图不对 → 用户反馈 → 去查标签 → 发现
+ * 根本没有这个词"。
+ *
+ * 最典型的一次：连续三张图里"妆花了"完全不生效，用户反复说"她太干净了"，
+ * 而 `running_makeup` / `smeared_eyeliner` / `dried_tears` / `ruined_makeup`
+ * 四个词**全是 0 收录**。真正有货的是 tears(29万) / crying_with_eyes_open(5.4万)
+ * / smeared_lipstick / dirty_face。
+ *
+ * ⭐ **判据是 post_count 不是"标签存不存在"**：`running_makeup` 在 danbooru 上
+ * 确实有这个条目，`post_count` 是 0 —— 存在但没有一张图用过它，训练里等于不存在。
+ * 只查"有没有这个条目"会漏掉整类问题（实测过）。
+ *
+ * ## 两个入口，一份逻辑（2026-08-20）
+ *
+ * - `lintTags`：paint_still **画完之后**的体检 —— 收录量 + 「这段像句子不像标签」
+ *   + 「带下划线」两项本地判定（不联网也能说）。
+ * - `lookupTags`：`lookup_tags` 工具，**画之前**查 —— 同一套收录量判定，外加
+ *   弱词自动给候选替换（danbooru 通配搜索按收录量排序）、自由词搜索、wiki 释义。
+ *   目的是把"先理解用户意思 → 查真实标签 → 再画"的纪律变得比 curl 便宜。
+ *
+ * ## 纪律
+ *
+ * - **fail-open**：查不到、超时、断网一律不挡出图。这是一个提示，不是闸门。
+ * - **只提示不改写**：绝不替 agent 改 prompt —— 「逐字传递」是既有纪律，
+ *   而且替换词的选择是创作判断，不是查表能定的。
+ */
+
+const API = 'https://danbooru.donmai.us';
+const BATCH = 100;
+const LOW = 1000;
+const UA = { 'User-Agent': 'nodesign-tag-lint' };
+
+/** 进程内缓存。标签收录量是慢变量，一个进程生命周期内不用重查。 */
+const cache = new Map();   // name → post_count（-1 = 查过但 danbooru 上没有这个条目）
+
+// 句子判定用的功能词。⚠️ 刻意不收 of/with/on/in/own：danbooru 真标签里满是
+// `hand_on_own_chest` / `playing_with_own_hair` / `cup_of_tea`，收了就是误伤。
+const STOPWORDS = new Set(['a', 'an', 'the', 'and', 'is', 'are', 'was', 'were',
+  'who', 'which', 'she', 'he', 'they', 'her', 'his', 'their', 'being', 'very']);
+
+/** 把 prompt 切成逗号片段（剥 <lora>、BREAK），保留原文便于回显。 */
+function splitFragments(text) {
+  if (!text || typeof text !== 'string') return [];
+  return String(text)
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\bBREAK\b/gi, ',')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+/** 片段是否像自然语言句子而不是标签（模型基本不认这种输入）。 */
+export function isSentenceLike(fragment) {
+  const bare = fragment.replace(/[()[\]{}]/g, '').replace(/:\s*[\d.]+\s*$/, '').trim();
+  if (!bare) return false;
+  if (/[぀-ヿ㐀-鿿]/.test(bare)) return true;        // 中日文
+  const words = bare.toLowerCase().split(/[\s_]+/).filter(Boolean);
+  if (words.length >= 6) return true;
+  return words.length >= 3 && words.some(w => STOPWORDS.has(w));
+}
+
+/**
+ * 本地判定（不联网）：哪些片段像句子、哪些带下划线。
+ * @returns {{sentences:string[], underscored:string[]}}
+ */
+export function classifyFragments(text) {
+  const sentences = [], underscored = [];
+  for (const f of splitFragments(text)) {
+    if (isSentenceLike(f)) sentences.push(f);
+    else if (f.includes('_')) underscored.push(f);
+  }
+  return { sentences, underscored };
+}
+
+function balanced(s) {
+  let d = 0;
+  for (const ch of s) { if (ch === '(') d++; else if (ch === ')') { d--; if (d < 0) return false; } }
+  return d === 0;
+}
+
+/**
+ * 标签名归一成 danbooru 的 name：剥反斜杠转义、`(tag:1.2)` 权重、纯强调用的外层括号、
+ * `artist:` 一类前缀；空格转下划线。⚠️ 名字自带的括号要留：`lucy \(cyberpunk\)` → `lucy_(cyberpunk)`。
+ */
+export function normalizeTag(raw) {
+  let s = String(raw).replace(/\\/g, '').trim();
+  s = s.replace(/:\s*[\d.]+\s*(\)*)\s*$/, '$1');           // (tag:1.2) → (tag)
+  while (/^[([{][\s\S]*[)\]}]$/.test(s)) {                  // 外层强调括号
+    const inner = s.slice(1, -1).trim();
+    if (!balanced(inner)) break;
+    s = inner;
+  }
+  return s.replace(/[[\]{}]/g, '')
+    .toLowerCase()
+    .replace(/^(artist|character|copyright|meta|general):/, '')
+    .trim().replace(/\s+/g, '_');
+}
+
+/**
+ * 从一段 danbooru 风格 prompt 里抠出标签名（像句子的片段跳过 —— 它们另有去处）。
+ */
+export function extractTags(text) {
+  return splitFragments(text)
+    .filter(f => !isSentenceLike(f))
+    .map(normalizeTag)
+    .filter(t => t
+      && t.length >= 3 && t.length <= 60
+      && /^[a-z0-9_\-'.()!?&+]+$/.test(t)     // 中文/自然语言句子不是 danbooru 标签，跳过
+      && !/^\d+$/.test(t));
+}
+
+async function getJson(url, timeoutMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ac.signal, headers: UA });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchCounts(names, timeoutMs) {
+  const out = new Map();
+  for (let i = 0; i < names.length; i += BATCH) {
+    const chunk = names.slice(i, i + BATCH);
+    const rows = await getJson(`${API}/tags.json?search%5Bname_comma%5D=${encodeURIComponent(chunk.join(','))}&limit=${BATCH * 2}`, timeoutMs);
+    if (!rows) return null;                               // fail-open
+    for (const row of rows) if (row?.name) out.set(row.name, Number(row.post_count) || 0);
+    for (const n of chunk) if (!out.has(n)) out.set(n, -1);   // danbooru 上没这条目
+  }
+  return out;
+}
+
+async function countsFor(names, timeoutMs) {
+  const need = names.filter(n => !cache.has(n));
+  if (need.length) {
+    const fetched = await fetchCounts(need, timeoutMs);
+    if (!fetched) return false;
+    for (const [k, v] of fetched) cache.set(k, v);
+  }
+  return true;
+}
+
+function bucket(names) {
+  const zero = [], low = [], missing = [], ok = [];
+  for (const n of names) {
+    const c = cache.get(n);
+    if (c == null) continue;
+    if (c === -1) missing.push(n);
+    else if (c === 0) zero.push(n);
+    else if (c < LOW) low.push([n, c]);
+    else ok.push([n, c]);
+  }
+  return { zero, low, missing, ok };
+}
+
+/**
+ * @param {string[]} texts  prompt / negative 原文
+ * @returns {Promise<{zero:string[], low:Array<[string,number]>, missing:string[], checked:number,
+ *   sentences:string[], underscored:string[], offline:boolean}|null>}
+ *   null = 既查不了也没什么本地可说的（调用方什么都不要说）
+ */
+export async function lintTags(texts, { timeoutMs = 3000 } = {}) {
+  const local = { sentences: [], underscored: [] };
+  for (const t of texts) {
+    const c = classifyFragments(t);
+    local.sentences.push(...c.sentences);
+    local.underscored.push(...c.underscored);
+  }
+  local.sentences = [...new Set(local.sentences)];
+  local.underscored = [...new Set(local.underscored)];
+
+  const names = [...new Set(texts.flatMap(extractTags))];
+  const online = names.length ? await countsFor(names, timeoutMs) : true;
+  const b = online ? bucket(names) : { zero: [], low: [], missing: [] };
+  const r = { ...b, ok: undefined, checked: online ? names.length : 0, ...local, offline: !online };
+  delete r.ok;
+  if (!r.zero.length && !r.low.length && !r.missing.length && !r.sentences.length && !r.underscored.length) return null;
+  return r;
+}
+
+/** 把 lint 结果写成给 agent 看的一段话。没什么可说时返回 null。 */
+export function formatTagLint(r) {
+  if (!r) return null;
+  const parts = [];
+  if (r.sentences?.length) {
+    parts.push('像句子不像标签（模型基本不认这种输入，还摊薄其它标签的权重 —— 拆成标签）：'
+      + r.sentences.map(s => `"${s}"`).join(' · '));
+  }
+  if (r.underscored?.length) parts.push(`带下划线（手册要求写成空格）：${r.underscored.join(', ')}`);
+  if (r.missing?.length) parts.push(`不存在的标签：${r.missing.join(', ')}`);
+  if (r.zero?.length) parts.push(`0 收录（存在但训练里等于没有）：${r.zero.join(', ')}`);
+  if (r.low?.length) {
+    parts.push(`低收录（<${LOW}，弱但不是禁区：主流需求换掉，用户要的本来就偏门就照用、配近义词加固）：`
+      + r.low.map(([n, c]) => `${n}(${c})`).join(', '));
+  }
+  if (!parts.length) return null;
+  const head = r.offline ? '⚠️ 标签体检（danbooru 查不到，只做了本地判定）：' : `⚠️ 标签体检（查了 ${r.checked} 个）：`;
+  return `${head}\n  ${parts.join('\n  ')}\n`
+    + '  这些词模型收不到，等于没写 —— 用 lookup_tags 换成有收录量的词再滚一次，别按这批图判断方向。';
+}
+
+// ── 画之前查：lookup_tags ──
+
+/** 从一个弱标签里挑最多两个值得拿去通配搜索的词（最长的非功能词优先）。 */
+function searchWordsOf(tag) {
+  const words = tag.split(/[_\s\-()]+/).filter(w => w.length >= 3 && !STOPWORDS.has(w)
+    && !['own', 'with', 'and', 'from', 'the', 'out', 'off'].includes(w));
+  return [...new Set(words)].sort((a, b) => b.length - a.length).slice(0, 2);
+}
+
+/** 弱标签 → 候选：每个关键词各搜一次，合并按收录量排，太弱的（<100）不当候选。 */
+async function candidatesFor(tag, timeoutMs) {
+  const seen = new Map();
+  for (const w of searchWordsOf(tag)) {
+    const hits = await wildcard(w, timeoutMs, 6);
+    for (const [n, c] of hits || []) if (n !== tag && c >= 100) seen.set(n, c);
+  }
+  return [...seen].sort((a, b) => b[1] - a[1]).slice(0, 8);
+}
+
+async function wildcard(term, timeoutMs, limit = 8) {
+  const q = `*${normalizeTag(term).replace(/^\*+|\*+$/g, '')}*`;
+  const rows = await getJson(`${API}/tags.json?search%5Bname_matches%5D=${encodeURIComponent(q)}`
+    + `&search%5Border%5D=count&search%5Bhide_empty%5D=true&limit=${limit}`, timeoutMs);
+  if (!rows) return null;
+  return rows.map(r => [r.name, Number(r.post_count) || 0]);
+}
+
+async function wikiOf(tag, timeoutMs) {
+  const rows = await getJson(`${API}/wiki_pages.json?search%5Btitle%5D=${encodeURIComponent(normalizeTag(tag))}&only=title,body`, timeoutMs);
+  const body = rows?.[0]?.body;
+  if (!body) return null;
+  return body.replace(/\[\[([^\]|]+)(\|[^\]]*)?\]\]/g, '$1').replace(/\s+/g, ' ').trim().slice(0, 220);
+}
+
+/**
+ * @param {{tags?:string[], search?:string[], explain?:string[]}} q
+ * @returns {Promise<{offline:boolean, tags:{ok:Array, low:Array, zero:string[], missing:string[]},
+ *   suggestions:Array<[string, Array<[string,number]>]>, searches:Array<[string, Array<[string,number]>|null]>,
+ *   wiki:Array<[string,string|null]>}>}
+ */
+export async function lookupTags({ tags = [], search = [], explain = [] } = {}, { timeoutMs = 5000 } = {}) {
+  const names = [...new Set(tags.map(normalizeTag).filter(Boolean))].slice(0, 60);
+  const online = names.length ? await countsFor(names, timeoutMs) : true;
+  const b = online ? bucket(names) : { ok: [], low: [], zero: [], missing: [] };
+
+  const suggestions = [];
+  if (online) {
+    const weak = [...b.missing, ...b.zero, ...b.low.map(([n]) => n)].slice(0, 8);
+    for (const w of weak) {
+      const hits = await candidatesFor(w, timeoutMs);
+      if (hits.length) suggestions.push([w, hits]);
+    }
+  }
+  const searches = [];
+  for (const s of [...new Set(search)].slice(0, 10)) searches.push([s, await wildcard(s, timeoutMs, 10)]);
+  const wiki = [];
+  for (const t of [...new Set(explain)].slice(0, 8)) wiki.push([t, await wikiOf(t, timeoutMs)]);
+  return { offline: !online, tags: b, suggestions, searches, wiki };
+}
+
+/** lookup_tags 的文本输出。 */
+export function formatLookup(r) {
+  const fmt = (arr) => arr.map(([n, c]) => `${n}(${c})`).join(', ');
+  const out = [];
+  if (r.offline) out.push('⚠️ danbooru 暂时查不到（超时/断网），收录量这部分空着；别因此停工，照手册词表写。');
+  const t = r.tags;
+  if (t.ok?.length) out.push(`✅ 可用（≥${LOW}）：${fmt(t.ok)}`);
+  if (t.low?.length) out.push(`⚠️ 低收录（<${LOW}）：${fmt(t.low)} —— 弱但不是禁区：主流需求换成候选，用户要的本来就偏门就照用、配近义词加固`);
+  if (t.zero?.length) out.push(`✗ 0 收录（等于不存在）：${t.zero.join(', ')}`);
+  if (t.missing?.length) out.push(`✗ 不存在：${t.missing.join(', ')}`);
+  for (const [w, hits] of r.suggestions) out.push(`  ↳ ${w} 的候选（按收录量）：${fmt(hits) || '（没搜到相近的）'}`);
+  for (const [s, hits] of r.searches) {
+    out.push(`🔍 *${s}*：${hits == null ? '（查不到）' : hits.length ? fmt(hits) : '（没有匹配的标签）'}`);
+  }
+  for (const [tag, body] of r.wiki) out.push(`📖 ${tag}：${body || '（没有 wiki）'}`);
+  if (!out.length) out.push('（什么都没查 —— tags / search / explain 至少给一个）');
+  return out.join('\n');
+}