@xiaobuyu/nodesign 0.0.1

package/server/lib/kinds/docx.js

@@ -0,0 +1,283 @@
+/**
+ * kinds/docx.js — word 形态（.docx 正式文档）
+ *
+ * 形态契约见 kinds/index.js。docx 跟前两种形态有一处**结构性差异**：
+ * 它是第一个 `browsable: false` 的形态 —— 入口是二进制包，塞不进 iframe，
+ * playwright 也打不开。感知层为此新增 `renderable` 能力位：能力位说的是
+ * 「这东西怎么才能被看见」，screenshot 按能力分流（renderable → LibreOffice
+ * 渲成页图），agent 那边动词不变，还是「做完看一眼」。
+ *
+ * 源与产物：
+ *   文档.json  —— token + 内容的**真相源**（我们自己造的文档走这条）
+ *   *.docx     —— 构建产物；也可能是用户上传的外来文档（那时没有 json 源）
+ *
+ * 实例发现两者都认，是因为「外来 docx 也是 word 任务」这件事从第一天就成立，
+ * 等接编辑那一段再改判据 = 到时候要动寻址、导出、前端三处。
+ *
+ * ⚠️ 判定次序：docx 排在 deck / site **之后**（taskManifest 里 docx 实例最后 append）。
+ * 任务里同时有 canvas.html / index.html 和一个 .docx 时，那个 docx 是素材不是
+ * 产物，不能把整个任务判成 word。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { isReservedFile, RESERVED_DIRS } from '../task-scan.js';
+
+/** token + 内容的源文件名。产物 .docx 与它同级同名 */
+const SOURCE = '文档.json';
+
+/** 无更好信号时的默认产物名（跟源同名，`文档.json` → `文档.docx`） */
+const ENTRY = '文档.docx';
+
+async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+/**
+ * 一堆文件名 → 排好序的产物 .docx 名单（排掉保留文件和临时文件）。
+ * 导出收集器（export-collect）反解 `docx:<文件夹>` 卡时用同一份判据挑主成员，
+ * 别在那边再抄一遍排序。
+ */
+function sortDocxNames(names) {
+  return names
+    .filter(n => /\.docx$/i.test(n))
+    // Word 自己开着文件时会留 `~$xxx.docx` 锁文件，那不是产物
+    .filter(n => !n.startsWith('.') && !n.startsWith('~$'))
+    .filter(n => !isReservedFile(n))
+    .sort((a, b) => (b === ENTRY) - (a === ENTRY) || a.localeCompare(b, 'zh'));
+}
+
+/** 目录顶层的 .docx */
+async function topLevelDocx(dir) {
+  let entries = [];
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { /* */ }
+  return sortDocxNames(entries.filter(e => e.isFile()).map(e => e.name));
+}
+
+/* ── 源文件配对（2026-08-19 自动纠偏） ─────────────────────────
+ *
+ * 约定是源和产物同 stem（文档.json → 文档.docx），但 agent 真会写出
+ * `刘万钢-简历-v3.docx` + `文档-v3.json` 这种组合（生产实锤）——按老判据
+ * sourceFile 关联不上，窗里「看源码」消失、banner 误标「外来文档」，下一个
+ * 会话就真把它当外来文档改。所以 stem 对不上时做两级兜底，宁缺勿错：
+ * 配错源比配不上更坏（agent 会去改一份别的文档的 JSON 然后 build 覆盖）。
+ */
+
+/** 这份 json 长得像不像 docx 的 token 源（content 数组 + preset/tokens 至少一样） */
+async function isDocxSourceShape(absPath) {
+  try {
+    const stat = await fs.stat(absPath);
+    if (stat.size > 2 * 1024 * 1024) return false;   // 源文件不会大到哪去，超了就不是
+    const j = JSON.parse(await fs.readFile(absPath, 'utf8'));
+    return !!j && Array.isArray(j.content)
+      && (typeof j.preset === 'string' || (j.tokens && typeof j.tokens === 'object' && !Array.isArray(j.tokens)));
+  } catch { return false; }
+}
+
+const stemOf = (n) => n.replace(/\.(docx|json)$/i, '');
+/** 末尾的版本记号（要带分隔符：`-v3` / `_2` 算，`报告2024` 不算 —— 裸尾数太容易撞） */
+const verOf = (n) => (stemOf(n).match(/[-_][vV]?(\d+)$/) || [])[1] ?? null;
+
+/**
+ * docx 名单 × 源候选名单 → Map(docx 名 → 源名)。纯函数，好测。
+ * 三级：同 stem 精确 → 版本记号唯一对唯一 → 双方各剩一个。
+ * 剩下的一律不配（多对一/一对多是歧义，配错的代价见上）。
+ */
+export function pairDocxSources(docxNames, jsonNames) {
+  const res = new Map();
+  const freeJson = new Set(jsonNames);
+  for (const d of docxNames) {
+    const want = `${stemOf(d)}.json`;
+    if (freeJson.has(want)) { res.set(d, want); freeJson.delete(want); }
+  }
+  const freeDocx = docxNames.filter(d => !res.has(d));
+  // 版本记号：两边都唯一才配（v2/v3 各一份的多版本文件夹就是这形状）
+  const byVer = (names) => {
+    const m = new Map();
+    for (const n of names) {
+      const v = verOf(n);
+      if (v == null) continue;
+      m.set(v, m.has(v) ? null : n);   // 同版本出现两次 = 歧义，记 null
+    }
+    return m;
+  };
+  const dv = byVer(freeDocx);
+  const jv = byVer([...freeJson]);
+  for (const [v, d] of dv) {
+    const j = jv.get(v);
+    if (d && j) { res.set(d, j); freeJson.delete(j); }
+  }
+  const left = docxNames.filter(d => !res.has(d));
+  if (left.length === 1 && freeJson.size === 1) res.set(left[0], [...freeJson][0]);
+  return res;
+}
+
+/**
+ * 目录顶层的源配对结果 Map(docx 名 → 源名)。
+ * 同 stem 直接认（命名约定本身就是信号，不读文件 —— pending 半写状态的源也认，
+ * 跟老判据一致）；只有剩下配不上的才读 json 做形状校验再进模糊配对 —— 目录里
+ * 躺着的 data.json / 配置文件不能被当成源认走。命名规矩的目录一个文件都不读。
+ */
+async function resolveSources(dirAbs, docxNames) {
+  let entries = [];
+  try { entries = await fs.readdir(dirAbs, { withFileTypes: true }); } catch { /* */ }
+  const jsons = entries
+    .filter(e => e.isFile() && /\.json$/i.test(e.name) && !e.name.startsWith('.') && !isReservedFile(e.name))
+    .map(e => e.name);
+  const res = new Map();
+  const claimed = new Set();
+  for (const d of docxNames) {
+    const want = `${stemOf(d)}.json`;
+    if (jsons.includes(want) && !claimed.has(want)) { res.set(d, want); claimed.add(want); }
+  }
+  const freeDocx = docxNames.filter(d => !res.has(d));
+  if (!freeDocx.length) return res;
+  const fuzzy = [];
+  for (const n of jsons) {
+    if (!claimed.has(n) && await isDocxSourceShape(path.join(dirAbs, n))) fuzzy.push(n);
+  }
+  for (const [d, j] of pairDocxSources(freeDocx, fuzzy)) res.set(d, j);
+  return res;
+}
+
+/**
+ * word 文件夹（2026-08-18）：一级子目录顶层有 .docx（或 token 源）、且没有任何
+ * 网页入口 → 整个文件夹是**一件**目录型 word 产物，里面的 .docx 是它的成员
+ * （多版本并排放，窗里切换）。这跟 site 的「无根站时一级子目录各自为站」同构。
+ *
+ * 「没有网页入口」这条挡两种误伤：站点内部目录（posts/ 里全是 html）和
+ * deck 文件夹 —— 它们各有自己的解析器，word 不去认领。
+ */
+async function wordDirs(taskDir) {
+  const out = [];
+  let entries = [];
+  try { entries = await fs.readdir(taskDir, { withFileTypes: true }); } catch { /* */ }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name.startsWith('_')) continue;
+    if (RESERVED_DIRS.has(e.name)) continue;
+    let sub = [];
+    try { sub = await fs.readdir(path.join(taskDir, e.name), { withFileTypes: true }); } catch { continue; }
+    if (sub.some(x => x.isFile() && /\.html?$/i.test(x.name))) continue;
+    const files = sortDocxNames(sub.filter(x => x.isFile()).map(x => x.name));
+    if (files.length) out.push({ dir: e.name, files });
+    else if (sub.some(x => x.isFile() && x.name === SOURCE)) {
+      // 源已就位、还没 build 的窗口期：跟根层 pending 同款「声明即意图」
+      out.push({ dir: e.name, files: [ENTRY], pending: true });
+    }
+  }
+  return out;
+}
+
+export default {
+  id: 'docx',
+  entryFile: ENTRY,
+  view: 'docx',
+  injectFit: false,
+  // ⭐第一个不可浏览的形态。'renderable' = 要先渲染成页图才能被看见
+  capabilities: ['renderable'],
+  // raw 排头：.docx 本身就是交付物，这跟 deck/site「导出是二次加工」不一样
+  exportFormats: ['raw', 'pdf'],
+
+  // 目录型实例判据（卡即文件夹）：word 文件夹带成员表；根层散放的单份 .docx
+  // 是单文件产物。全仓只问 isDirArtifact（kinds/index.js），别在调用点自判
+  directory: (a) => !!a.members,
+
+  // 源和产物同住任务根，没有构建目录这回事
+  artifactRoot: async () => '',
+
+  /**
+   * 实例发现，两种粒度：
+   *   - **根层**每个 .docx 各是一份单文件产物（跟 deck 顶层每个 .html 同构）——
+   *     桌面上并排躺着的文档未必互相有关，不硬捆成一组
+   *   - **word 文件夹**（一级子目录）整个是一件目录型产物，里面的 .docx 全是
+   *     它的成员（多版本并排，窗里的导航切换）—— 跟 site 的子目录站同构
+   *
+   * 特例：有 `文档.json` 但还没构建出 .docx 时，也要报一份 —— 这是 site.js
+   * 「声明即意图」那条的同款处理（agent 刚写完源还没 build 的窗口期，寻址该
+   * 指向将要出现的地方，而不是让整个任务在那几秒里没有形态）。
+   */
+  async discoverInstances(taskDir) {
+    const out = [];
+    const files = await topLevelDocx(taskDir);
+    if (files.length) out.push(...files.map(f => ({ file: f })));
+    else if (await exists(path.join(taskDir, SOURCE))) out.push({ file: ENTRY, pending: true });
+    out.push(...await wordDirs(taskDir));
+    return out;
+  },
+
+  async instanceManifest(taskDir, _marker, inst) {
+    // ── word 文件夹：目录型实例，members 是它的版本清单 ──
+    if (inst.dir) {
+      const pairs = await resolveSources(path.join(taskDir, inst.dir), inst.files);
+      const members = [];
+      for (const f of inst.files) {
+        const stem = f.replace(/\.docx$/i, '');
+        const src = pairs.get(f);
+        members.push({
+          file: `${inst.dir}/${f}`,
+          title: stem === '文档' ? inst.dir : stem,
+          sourceFile: src ? `${inst.dir}/${src}` : null,
+        });
+      }
+      const primary = members[0];
+      return {
+        kind: 'docx',
+        // root = 文件夹本身：前端卡 id（docx:<root>）和舞台寻址的认领范围都从它来
+        root: inst.dir,
+        srcRoot: inst.dir,
+        entry: primary.file,
+        entryRel: primary.file,
+        // file 仍指主成员（不是 null）：单文件消费方（卡脸的第一页缩略图、
+        // setActiveArtifact、导出兜底）拿它就能干活，不用都学会 members
+        file: primary.file,
+        members,
+        pages: null,
+        single: false,
+        title: inst.dir,
+        sourceFile: primary.sourceFile,
+      };
+    }
+    const stem = inst.file.replace(/\.docx$/i, '');
+    // 配对要看根层**全部** docx（唯一候选那级的语义是"整个目录里就这一对"）；
+    // pending 实例的 docx 还没落盘，不在 topLevelDocx 里，补进去让同 stem 那级认
+    const roots = await topLevelDocx(taskDir);
+    if (!roots.includes(inst.file)) roots.push(inst.file);
+    const pairs = await resolveSources(taskDir, roots);
+    return {
+      kind: 'docx',
+      root: '',
+      srcRoot: '',
+      entry: inst.file,
+      entryRel: inst.file,
+      file: inst.file,
+      // 页数只有渲染过才知道，而 manifest 每轮都要算 —— 不能为了一个数去跑
+      // LibreOffice。页数由 screenshot 返回时才给。
+      pages: null,
+      single: false,
+      title: stem === '文档' ? null : stem,
+      // 有没有 token 源，决定了「改它」走重建还是走手术（见 dump-styles.js）
+      sourceFile: pairs.get(inst.file) ?? null,
+    };
+  },
+
+  /** 每轮注入的产物清单里，这份文档的一行说明 */
+  async describe(taskDir, artifact) {
+    const label = `word ${artifact.entryRel}`;
+    const src = artifact.sourceFile;
+    try {
+      const stat = await fs.stat(path.join(taskDir, artifact.entryRel));
+      const kb = (stat.size / 1024).toFixed(0);
+      return src
+        ? `${label} · ${kb}KB · 源 ${src}（改源重建，别直接改 .docx）`
+        : `${label} · ${kb}KB · 外来文档，没有 token 源`;
+    } catch {
+      return src
+        ? `${label} · 还没构建（源 ${src} 已就位）`
+        : `${label} · 入口读不到`;
+    }
+  },
+
+  // 给别处复用，别再各写各的字符串 / 排序
+  SOURCE,
+  sortDocxNames,
+};

package/server/lib/kinds/file-kinds.js

@@ -0,0 +1,113 @@
+/**
+ * kinds/file-kinds.js — 文件形态注册表（2026-08-17）
+ *
+ * 跟 kinds/index.js 那张表是**两族东西，别混**：
+ *
+ *   任务形态（deck / site）  = 一个**目录**是什么。契约里有 detect(taskDir) /
+ *                             artifactRoot / manifest —— 它回答「这个文件夹装的
+ *                             是一份幻灯还是一个站」。
+ *   文件形态（本文件）        = 一个**文件**是什么。没有任务目录、没有入口文件、
+ *                             没有 manifest，硬塞进上面那张表会把 detect(taskDir)
+ *                             的契约撑坏。所以另起一张，契约小得多。
+ *
+ * 两族共用的只有一件事：`exportFormats` —— 导出层问的是「这张卡能导出成什么」，
+ * 不关心它背后是目录还是文件。
+ *
+ * ⭐**这条映射规则原来住在前端** `BoardCanvas.jsx`（`a.kind === 'note'` →
+ * note、`isImage` → image、`isVideo` → video、其余 file），服务端只算
+ * `isImage` / `isVideo` 两个布尔。导出要按卡类型收产物，就必须在服务端问同一个
+ * 问题 —— 与其在导出层再写一遍判据，不如把规则挪到这里当唯一真相，前端将来直接
+ * 消费。多写一份影子判据的债见 [[nodesign-truth-sources]]。
+ */
+
+/**
+ * 文件形态契约：
+ *   id             'image' | 'video' | 'note' | 'file'
+ *   label          中文名（导出菜单、报错文案用）
+ *   exportFormats  这种卡能导出成什么
+ *                    raw — 原件直接下（单张 / 单个文件）
+ *                    zip — 多个打成一个压缩包
+ *                    md  — 合并成一份 markdown（只有便签有意义）
+ */
+export const FILE_KINDS = Object.freeze({
+  image: { id: 'image', label: '图片', exportFormats: ['raw', 'zip'] },
+  video: { id: 'video', label: '视频', exportFormats: ['raw', 'zip'] },
+  note:  { id: 'note',  label: '便签', exportFormats: ['raw', 'zip', 'md'] },
+  file:  { id: 'file',  label: '文件', exportFormats: ['raw', 'zip'] },
+});
+
+export function fileKindDef(kind) {
+  return FILE_KINDS[kind] || null;
+}
+
+/**
+ * 「什么算图片 / 视频」—— 原来住在 `api/assets.js`，08-17 挪到这里。
+ * 挪的理由：导出要按卡类型收产物，如果在导出层再抄一份扩展名表，就会出现
+ * 「画布认它是图片、导出不认」这种没人查得出来的分叉。assets.js 现在从这里 import。
+ */
+export const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg']);
+// 视频上墙（2026-08-08 roll_film）：isVideo 让前端渲成带播放器的视频卡而不是
+// 通用文件卡。播放走既有 Range+派生档管线（video-variant.js），这里只标记。
+export const VIDEO_EXTS = new Set(['.mp4', '.webm']);
+
+/** 便签的两个扫描根（跟 assets.js 的 scanDir 调用一致） */
+const NOTE_PREFIXES = ['assets/notes/', 'notes/'];
+
+/**
+ * 只拿一个工作区相对路径判文件形态（导出按卡 id 寻址时用 —— 那时手上只有路径，
+ * 没有 `/artifacts` 那条带 isImage/isVideo 的记录）。
+ *
+ * ⚠️ 结果必须跟 `fileKindOf()` 一致。两者的次序都是：便签 → 图 → 视频 → 其余。
+ *
+ * @param {string} relPath 工作区相对路径
+ */
+export function fileKindOfPath(relPath) {
+  if (!relPath || typeof relPath !== 'string') return 'file';
+  const p = relPath.replace(/\\/g, '/');
+  // ⚠️ 便签**按位置判，不看扩展名**。`/artifacts` 的真规则是「note 扫描根下的
+  // 任何文件都是 note」（assets.js 的 scanDir 是按 kind 参数打标，扩展名根本不
+  // 参与），前端也是先问 `a.kind === 'note'` 再问 isImage。
+  // 这里曾经多加了个 `.md` 条件，于是 `notes/参考图.png` 路径判成 image、记录判
+  // 成 note —— 同一个文件两种答案，正是"一个事实多份算法"那条债。
+  if (NOTE_PREFIXES.some(pre => p.startsWith(pre))) return 'note';
+  const dot = p.lastIndexOf('.');
+  const ext = dot > 0 ? p.slice(dot).toLowerCase() : '';
+  if (IMAGE_EXTS.has(ext)) return 'image';
+  if (VIDEO_EXTS.has(ext)) return 'video';
+  return 'file';
+}
+
+/**
+ * 一个 `/artifacts` 条目是哪种文件形态。
+ *
+ * ⚠️ 判据次序跟前端 BoardCanvas 那四行**必须一致**，改这里要连它一起改
+ * （note 在最前：便签也是 .md 文件，先问来源再问扩展名，否则会掉进 file）。
+ *
+ * @param {{kind?:string, isImage?:boolean, isVideo?:boolean}} item `/artifacts` 的一条
+ * @returns {'note'|'image'|'video'|'file'}
+ */
+export function fileKindOf(item) {
+  if (!item || typeof item !== 'object') return 'file';
+  if (item.kind === 'note') return 'note';
+  if (item.isImage) return 'image';
+  if (item.isVideo) return 'video';
+  return 'file';
+}
+
+/** 这种文件形态支不支持某个导出格式（导出守卫用，跟任务形态的 formatAllowed 同语义） */
+export function fileFormatAllowed(kind, format) {
+  const def = FILE_KINDS[kind];
+  return def ? def.exportFormats.includes(format) : false;
+}
+
+/**
+ * 给 `/artifacts` 的一条记录补上「它是哪种卡、能导出成什么」。
+ *
+ * 收在这里而不是写在 assets.js 的扫描循环里：卡类型的判据本来就住这个文件，
+ * 调用方只该说「补一下」，不该自己再拼一遍 `fileKindOf` + `exportFormats`。
+ */
+export function decorateCardKind(item) {
+  item.cardKind = fileKindOf(item);
+  item.exports = FILE_KINDS[item.cardKind]?.exportFormats || [];
+  return item;
+}

package/server/lib/kinds/index.js

@@ -0,0 +1,202 @@
+/**
+ * kinds/index.js — 产物形态注册表（2026-07-29）
+ *
+ * 一种形态 = 一份注册条目。加第三种形态（比如视频：shots/ 镜头集 + output/
+ * 成片）应该只需要在这里挂一个新模块 + 前端加一个对应的窗组件 ——
+ * 寻址层、刷新链路、桌面派生、导出守卫都从注册表读，不再各写各的 if。
+ *
+ * 形态契约（每个 kind 模块导出的字段）：
+ *   id             'deck' | 'site' | …
+ *   entryFile      入口文件名（文件即真相的判定证据之一）
+ *   view           前端窗组件提示（'deck' → DeckWindow，'site' → SiteWindow）
+ *   injectFit      导出 / 独立打开时是否注入整屏翻页 fit script
+ *   exportFormats  这个形态可用的导出格式 id 列表（前端导出菜单按它渲染）
+ *   referenceDoc   首次写这种产物时注入的技术参考 { file, title }
+ *   artifactRoot(taskDir, marker)  → string   产物根（相对任务根，'' = 任务根）
+ *   manifest(taskDir, marker)      → { root, entry, entryRel, pages, drafts }
+ *   describe(taskDir, manifest)    → string   每轮注入清单里的一行说明
+ *
+ * 形态判定 = taskManifest 的实例发现顺序（deck → site → docx 垫底），文件优先、
+ * marker 兜底：文件会被用户和 agent 直接改，marker 不会，让不会变的那个当兜底
+ * 而不是当权威。（原来还有条平行的 detect/detectTaskKind 判定链，对「散装
+ * html + docx」跟 taskManifest 给不同答案且全仓无生产调用方，2026-08-19 拆除。）
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import deck from './deck.js';
+import site from './site.js';
+import docx from './docx.js';
+
+export const KINDS = Object.freeze({ [deck.id]: deck, [site.id]: site, [docx.id]: docx });
+
+export { RESERVED_DIRS, isReservedFile } from '../task-scan.js';
+
+export function kindDef(kind) {
+  return KINDS[kind] || null;
+}
+
+/**
+ * 这个形态有没有某项能力。
+ *
+ * 加这层是因为代码里反复在问的其实不是「这是不是站点」，而是「这东西能不能
+ * 用浏览器打开」。现在两种形态都能，但形态一多，`kind === KIND_SITE` 这种写法
+ * 就会误伤 —— 感知工具（screenshot / read_page / query_elements）该问能力，
+ * 不该问形态名。
+ *
+ * 只声明**当前真的有人查**的能力，不预先铺一张能力表。
+ *
+ * @param {string} kind
+ * @param {string} cap
+ *   'browsable'  —— 入口是 html，能塞进 iframe / 交给 playwright（deck / site）
+ *   'renderable' —— 入口是二进制包，要先渲染成页图才能被看见（docx）
+ *   两者互斥不是巧合：它们回答的是同一个问题「这东西怎么才能被看见」，
+ *   感知工具按能力分流而不是按形态名分流，加第四种形态时不用再改工具。
+ */
+export function can(kind, cap) {
+  return !!KINDS[kind]?.capabilities?.includes(cap);
+}
+
+/**
+ * 读产物标记（`.nd-project.json`）。没有 / 读不动 → null。
+ *
+ * 2026-08-07 从 `.nd-task.json` 改名。旧文件里有两个字段：`sessionId`（这个
+ * 任务属于哪次对话 —— 正是要废的那条绑定，迁移时直接删）和 `root`（构建型
+ * 站点显式声明产物根，agent 刚写完源还没 build 的窗口期靠它认出"站已经在了"）。
+ * 后者还有用，所以标记本身留着，只是不再承载归属。
+ */
+export async function readTaskMarker(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, '.nd-project.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : null;
+  } catch { return null; }
+}
+
+/**
+ * 任务的完整 manifest —— 服务端唯一的解析器，前端、感知工具、导出都吃这份。
+ *
+ * 多产物平权（2026-07-29）：一个任务目录可以装多个平等产物，`artifacts` 是
+ * 权威清单，没有主/试作等级。每条 = { kind, view, exportFormats, root, srcRoot,
+ * entry, entryRel, file, pages, single, title }。
+ * 顶层的 kind/root/entry/entryRel/pages 是**兼容字段**（= artifacts[0]），给
+ * 只需要"一个默认目标"的老消费方；新代码一律读 artifacts。
+ *
+ * @returns {Promise<null | { kind, artifacts, root, entry, entryRel, pages,
+ *                            exportFormats, view, sessionId }>}
+ */
+export async function taskManifest(taskDir) {
+  const marker = await readTaskMarker(taskDir);
+
+  const siteInsts = await site.discoverInstances(taskDir, marker);
+  const rootSite = siteInsts.find(i => !i.single && !i.srcRoot);
+  const deckInsts = await deck.discoverInstances(taskDir, marker, { rootSiteExists: !!rootSite });
+
+  const decorate = (def) => (m) => ({
+    ...m,
+    view: def.view,
+    // 单页产物没有"整站 zip"可言（zip 会把整个任务根都卷进去）
+    exportFormats: m.single ? def.exportFormats.filter(f => f !== 'site') : def.exportFormats,
+  });
+  const artifacts = [];
+  // 顺序 = 无更好信号时的默认偏好：deck（canvas.html 排头，兼容旧判定链 deck
+  // 先于 site）→ 目录站点 → 单页
+  for (const i of deckInsts) {
+    artifacts.push(decorate(deck)(await deck.instanceManifest(taskDir, marker, i)));
+  }
+  for (const i of siteInsts.filter(x => !x.single)) {
+    artifacts.push(decorate(site)(await site.instanceManifest(taskDir, marker, i)));
+  }
+  for (const i of siteInsts.filter(x => x.single)) {
+    artifacts.push(decorate(site)(await site.instanceManifest(taskDir, marker, i)));
+  }
+  // docx **垫底但不隐身**（2026-08-18 拍板）：任务里已有 deck / site 时，旁边的
+  // .docx 不参与形态判定（append 在 deck / site 之后已保证），但照样出卡 —— 「不当判定依据」
+  // 和「不显示」是两回事，用户产出的 word 附件消失在画布上比多一张卡更坏。
+  for (const i of await docx.discoverInstances(taskDir, marker)) {
+    artifacts.push(decorate(docx)(await docx.instanceManifest(taskDir, marker, i)));
+  }
+
+  const kind = artifacts[0]?.kind || (KINDS[marker?.kind] ? marker.kind : null);
+  if (!kind) return null;
+  const def = KINDS[kind];
+  const primary = artifacts[0] || null;
+  return {
+    kind,
+    artifacts,
+    // ── 兼容字段（= artifacts[0]；产物还没写出来时给形态的入口约定）──
+    root: primary?.root || '',
+    entry: primary?.entry || def.entryFile,
+    entryRel: primary?.entryRel || def.entryFile,
+    pages: primary?.pages || [],
+    exportFormats: def.exportFormats,
+    view: def.view,
+  };
+}
+
+/**
+ * 这份产物实例是不是**目录型**（卡即文件夹：站点的目录站、word 文件夹）。
+ *
+ * 判据由各形态自己声明（条目上的 `directory(a)`；没声明 = 这种形态没有目录型）。
+ * 收成一份之前，「这张卡是不是文件夹」全仓有四份互不相同的算法（这里的
+ * `!a.file`、前端的 type+members 组合、export-collect 的手写 Set、assets.js
+ * claimed 段的排除法）—— 一个事实多份算法，加形态时必然漏。
+ */
+export function isDirArtifact(a) {
+  return !!KINDS[a?.kind]?.directory?.(a);
+}
+
+/**
+ * 路径 → 所属产物。specificity 从高到低：单文件产物（deck / 单页）精确命中 →
+ * 目录型产物按 root 前缀（长的优先；word 文件夹的成员、token 源、散文件都在
+ * 这条上归位）→ 根站（root='' 的站是整任务的兜底，源文件和构建产物都归它）。
+ * 找不到返回 null（调用方自己兜底）。
+ *
+ * @param {object} manifest  taskManifest 的返回
+ * @param {string} relInTask 相对任务根的路径
+ */
+export function artifactOfPath(manifest, relInTask) {
+  const rel = String(relInTask || '').replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!manifest?.artifacts?.length) return null;
+  const files = manifest.artifacts.filter(a => a.file);
+  const hit = files.find(a => a.file === rel);
+  if (hit) return hit;
+  const dirs = manifest.artifacts
+    // ⚠️ 别用 `!a.file` 当目录判据：word 文件夹的 file 合法地指着主成员
+    //（单文件消费方不用学 members），那样判会把它整个漏掉
+    .filter(isDirArtifact)
+    // 子目录（srcRoot 非空）优先精确匹配，根站（srcRoot=''）最后兜底
+    .sort((a, b) => (b.srcRoot?.length || 0) - (a.srcRoot?.length || 0));
+  for (const a of dirs) {
+    if (!a.srcRoot) return a;   // 根站兜底整任务（源和构建产物都归它，root='dist' 也一样）
+    if (rel === a.srcRoot || rel.startsWith(`${a.srcRoot}/`)
+      || rel === a.root || rel.startsWith(`${a.root}/`)) return a;
+  }
+  return null;
+}
+
+/**
+ * word 产物认领的文件全集（.docx 本体 + token 源，含 members），键是工作区相对
+ * 路径。散文件过滤靠它把这些文件从文件卡里收编 —— 不然一份文档在桌面上是三张卡
+ * （docx 产物卡 + .docx 文件条 + .json 文件条），双击到哪张全看运气。
+ * @param {Array<{artifacts?:Array}>} tasks  /artifacts 路由的 tasks（路径已加前缀）
+ */
+export function docxClaimedFiles(tasks) {
+  const out = new Set();
+  for (const t of tasks || []) {
+    for (const a of (t.artifacts || [])) {
+      if (a.kind !== 'docx') continue;
+      for (const m of [a, ...(a.members || [])]) {
+        if (m.file) out.add(m.file);
+        if (m.sourceFile) out.add(m.sourceFile);
+      }
+    }
+  }
+  return out;
+}
+
+/** 这个形态允不允许某种导出格式（导出路由的守卫从这里查，不再各自 if kind） */
+export function formatAllowed(kind, format) {
+  const def = KINDS[kind];
+  return def ? def.exportFormats.includes(format) : format !== 'site';
+}