@lingfan-engine/editor 0.0.0-stage → 0.1.0

package/src/editing/storyOps.ts

@@ -0,0 +1,268 @@
+/**
+ * 列级/命令级映射器便捷操作（全部纯函数、不可变，基于指针原语）：
+ * addColumn / removeColumn / renameColumn（引用同步更新）/ 命令容器定位与增删改移。
+ * renameColumn 更新 jump.target、menu.options[].target、navigate（scene ?? path）
+ * ——「列名即标签」，重命名必须保持全部列的引用图一致。
+ */
+
+import type { Story } from "@lingfan-engine/core";
+import { isSafeFileNameSegment } from "@lingfan-engine/core";
+import {
+  getAtPointer,
+  insertAtPointer,
+  moveAtPointer,
+  removeAtPointer,
+  setAtPointer,
+} from "./pointers.ts";
+
+/** 列的命令容器：flow → commands；scene → elements + entry */
+export function columnContainers(column: unknown): {
+  field: "commands" | "elements" | "entry";
+  list: unknown[];
+}[] {
+  if (column === null || typeof column !== "object") return [];
+  const record = column as Record<string, unknown>;
+  if (record.kind === "flow") {
+    return Array.isArray(record.commands)
+      ? [{ field: "commands", list: record.commands }]
+      : [];
+  }
+  const out: { field: "elements" | "entry"; list: unknown[] }[] = [];
+  if (Array.isArray(record.elements)) {
+    out.push({ field: "elements", list: record.elements });
+  }
+  if (Array.isArray(record.entry))
+    out.push({ field: "entry", list: record.entry });
+  return out;
+}
+
+/** 指向某列命令容器的数组指针（列不存在返回 null） */
+export function containerPointer(
+  story: Story,
+  columnId: string,
+  field: "commands" | "elements" | "entry",
+): string | null {
+  const index = story.columns.findIndex((column) => column.id === columnId);
+  if (index < 0) return null;
+  return `/columns/${index}/${field}`;
+}
+
+/**
+ * 语义化列 id 生成：建议 → 唯一化 → 兜底。 `hint` 是**建议**非命令：非法（空 / 不安全文件名字符）→ 回退 `column-N` 计数
+ * （不抛、不静默把作者输入改写成另一个语义 id）；重名 → `-2`/`-3` 递增取空位。
+ * 列 id 语义：文件名 = 列 id 是存储不变量，运行时永不派生；
+ * 列序 = 文件路径码元序 ⇒ 语义化 id 优于计数 id（`column-N` 重排后落字母位，仅兜底）。
+ */
+export function suggestColumnId(
+  hint: string | null | undefined,
+  existingIds: readonly string[],
+): string {
+  const taken = new Set(existingIds);
+  const cleaned = typeof hint === "string" ? hint.trim() : "";
+  if (cleaned !== "" && isSafeFileNameSegment(cleaned)) {
+    if (!taken.has(cleaned)) return cleaned;
+    let n = 2;
+    while (taken.has(`${cleaned}-${n}`)) n += 1;
+    return `${cleaned}-${n}`;
+  }
+  let n = existingIds.length + 1;
+  while (taken.has(`column-${n}`)) n += 1;
+  return `column-${n}`;
+}
+
+/** 追加列；id 缺省时按 `hint` 生成语义化 id（无建议 → column-N 兜底）并保证唯一；显式 id 撞名 = fail-closed 原样返回；scene 预置双容器 */
+export function addColumn(
+  story: Story,
+  options: {
+    id?: string;
+    kind?: "scene" | "flow";
+    /**
+     * 运行语义轴（与 `kind` 正交）：game 缺省 / menu 菜单 / ui 覆盖层。
+     * **缺省与 game 都不写字段**——默认值不显式存储（与写回保真同一口径：
+     * 新建列的内存形态必须与重开后的解析形态深等）。
+     */
+    type?: "game" | "menu" | "ui";
+    /** 语义化建议（仅 id 缺省时参与；见 suggestColumnId） */
+    hint?: string | null;
+  } = {},
+): { story: Story; id: string } {
+  const id =
+    options.id ??
+    suggestColumnId(
+      options.hint,
+      story.columns.map((column) => column.id),
+    );
+  if (
+    options.id !== undefined &&
+    story.columns.some((column) => column.id === id)
+  ) {
+    return { story, id };
+  }
+  const kind = options.kind ?? "flow";
+  const base =
+    kind === "flow"
+      ? { id, kind, commands: [] }
+      : { id, kind, elements: [], entry: [] };
+  // 仅非 game 的显式 type 才落字段（默认形态保持与旧工程逐字节一致）
+  const column =
+    options.type !== undefined && options.type !== "game"
+      ? { ...base, type: options.type }
+      : base;
+  const next = insertAtPointer(story, "/columns", story.columns.length, column);
+  if (next === null) return { story, id };
+  return { story: next, id };
+}
+
+/** 删除列（引用完整性交诊断层报 missing-target，不做静默改指） */
+export function removeColumn(story: Story, columnId: string): Story | null {
+  const index = story.columns.findIndex((column) => column.id === columnId);
+  if (index < 0) return null;
+  return removeAtPointer(story, `/columns/${index}`);
+}
+
+/**
+ * 反查：**哪个文件承载的第一个列**（列序；资源树点击故事文件时用）。
+ *
+ * 语义：一个 `.story` 文件可承载**多个列**（如 `chapter1.story` = 4 列），
+ * 「点击资源树里的故事文件」⇒ 打开该文件**列序第一**的列（确定性，不猜作者意图）。
+ * 匹配键 = 组装器回填的 `sourcePath`（工程级事实；默认路径 `Stories/<id>.json`
+ * 不显式存 `sourcePath`——那种文件由 `columnIdOfDocument` 先行命中，不走这里）。
+ */
+export function firstColumnIdOfSourcePath(
+  story: Story,
+  filePath: string,
+): string | undefined {
+  return story.columns.find(
+    (column) =>
+      typeof column.sourcePath === "string" &&
+      column.sourcePath !== "" &&
+      column.sourcePath === filePath,
+  )?.id;
+}
+
+/** 引用同步面：jump.target / menu.options[].target / navigate（scene ?? path） */
+function updateRefsDeep(value: unknown, from: string, to: string): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => updateRefsDeep(item, from, to));
+  }
+  if (value === null || typeof value !== "object") return value;
+  const record = value as Record<string, unknown>;
+  let next = record;
+  const replace = () => {
+    next = { ...next };
+  };
+  if (next.op === "jump" && next.target === from) {
+    replace();
+    next.target = to;
+  }
+  if (next.op === "menu" && Array.isArray(next.options)) {
+    replace();
+    next.options = next.options.map((option) => {
+      if (
+        option !== null &&
+        typeof option === "object" &&
+        (option as Record<string, unknown>).target === from
+      ) {
+        return { ...(option as Record<string, unknown>), target: to };
+      }
+      return option;
+    });
+  }
+  if (next.op === "navigate") {
+    // 目标列 = scene ?? path：显式 scene 优先，无 scene 时 path 承载目标
+    if (
+      next.scene === from ||
+      (next.scene === undefined && next.path === from)
+    ) {
+      replace();
+      if (next.scene === from) next.scene = to;
+      else next.path = to;
+    }
+  }
+  return next;
+}
+
+/** 重命名列并同步全部列内的引用（jump/menu/navigate）；列不存在或新 id 撞名返回 null */
+export function renameColumn(
+  story: Story,
+  from: string,
+  to: string,
+): Story | null {
+  if (from === to) return story;
+  const index = story.columns.findIndex((column) => column.id === from);
+  if (index < 0) return null;
+  if (story.columns.some((column) => column.id === to)) return null;
+  const columns = story.columns.map((column, i) => {
+    const renamed = i === index;
+    const containers = columnContainers(column);
+    if (!renamed && containers.length === 0) return column;
+    const next: Record<string, unknown> = {
+      ...(column as unknown as Record<string, unknown>),
+    };
+    if (renamed) {
+      next.id = to;
+      // **重命名 ⇒ 来源文件同步改名**。
+      // `sourcePath` 是「这个列来自哪个文件」；列 id 变了而文件名不变，
+      // 会写回旧文件名（`Stories/inn.json` 里躺着 id=tavern 的列）——
+      // 那是**分裂**：文件名与内容 id 不一致，下次打开会被组装器拒绝
+      // （「单列文件名必须等于列 id」）。
+      // 只改**文件名段**（basename），目录层级（作者的章节编排）保持不变。
+      const source = column.sourcePath;
+      if (typeof source === "string" && source !== "") {
+        const slash = source.lastIndexOf("/");
+        const dir = slash < 0 ? "" : source.slice(0, slash + 1);
+        const base = slash < 0 ? source : source.slice(slash + 1);
+        const dot = base.indexOf(".");
+        const ext = dot < 0 ? "" : base.slice(dot);
+        next.sourcePath = `${dir}${to}${ext}`;
+      }
+    }
+    for (const container of containers) {
+      next[container.field] = updateRefsDeep(next[container.field], from, to);
+    }
+    return next as unknown as typeof column;
+  });
+  return { ...story, columns };
+}
+
+/** 向列容器插入命令（index 缺省 = 末尾） */
+export function insertCommand(
+  story: Story,
+  columnId: string,
+  field: "commands" | "elements" | "entry",
+  command: Record<string, unknown>,
+  index?: number,
+): Story | null {
+  const pointer = containerPointer(story, columnId, field);
+  if (pointer === null) return null;
+  const list = getAtPointer(story, pointer);
+  if (!Array.isArray(list)) return null;
+  return insertAtPointer(story, pointer, index ?? list.length, command);
+}
+
+/** 移除命令（elementPointer 指向命令对象） */
+export function removeCommand(
+  story: Story,
+  elementPointer: string,
+): Story | null {
+  return removeAtPointer(story, elementPointer);
+}
+
+/** 更新命令负载字段（elementPointer 指向命令对象） */
+export function updateCommandField(
+  story: Story,
+  elementPointer: string,
+  field: string,
+  value: unknown,
+): Story | null {
+  return setAtPointer(story, `${elementPointer}/${field}`, value);
+}
+
+/** 移动命令在容器内的位置（toIndex 为移除后目标位） */
+export function moveCommand(
+  story: Story,
+  elementPointer: string,
+  toIndex: number,
+): Story | null {
+  return moveAtPointer(story, elementPointer, toIndex);
+}

package/src/editing/tsSourceGuard.ts

@@ -0,0 +1,40 @@
+import { MANIFEST_FILE, STORIES_DIR } from "@lingfan-engine/core";
+
+/**
+ * TS 源工程只读守卫：启用 `Stories.src/` 的工程，其 JSON 产物（`Stories/**` 与
+ * `project.json`）由构建管线全量管理（`pnpm stories:build`），编辑器不得写回。
+ *
+ * 判据 = 清单标记键（非托管键，`serializeProject` 原位保留）：构建编排写入
+ * `tsSource: true`，编辑器只读不动——浏览侧 FSA 取径拿不到 `Stories.src/` 的
+ * 探测能力（资源根外无父句柄），清单标记是两侧唯一的通信通道。
+ */
+
+/** 清单标记键（构建写入 / 编辑器读取；非托管键跨 `serializeProject` 保真） */
+export const TS_SOURCE_MANIFEST_KEY = "tsSource";
+
+/** TS 源工程的统一拒绝文案（编辑器三个写回入口共用） */
+export const TS_SOURCE_READONLY_HINT =
+  "TS 源工程（Stories.src/）的产物归构建管线管理——请改 .ts 源后运行 pnpm stories:build，编辑器不写回 Stories/** 与 project.json";
+
+/** 工程清单是否标记为 TS 源工程 */
+export function isTsSourceProject(manifest: unknown): boolean {
+  return (
+    typeof manifest === "object" &&
+    manifest !== null &&
+    (manifest as Record<string, unknown>)[TS_SOURCE_MANIFEST_KEY] === true
+  );
+}
+
+/** 在候选写回路径里挑出 TS 源工程禁写项（`Stories/**` 与清单；空数组 = 全部可写） */
+export function tsSourceWriteBlockers(paths: readonly string[]): string[] {
+  return paths.filter(
+    (path) => path === MANIFEST_FILE || path.startsWith(`${STORIES_DIR}/`),
+  );
+}
+
+/** fail-closed：TS 源工程下命中禁写路径即抛（含操作指引） */
+export function assertTsSourceWritable(paths: readonly string[]): void {
+  const blocked = tsSourceWriteBlockers(paths);
+  if (blocked.length === 0) return;
+  throw new Error(`${TS_SOURCE_READONLY_HINT}（命中：${blocked.join("、")}）`);
+}

package/src/element/drag.ts

@@ -0,0 +1,22 @@
+/**
+ * 舞台编辑：拖拽位移 → 新坐标（纯函数，可测）。
+ *
+ * 元素 `x`/`y` 可为数字（px）或 CSS 长度串（如 `"50%"`）。**只有数字参与像素拖拽**：
+ * 百分比 / `calc()` / `em` 等无法与像素位移相加，拖拽时保持原值不动
+ * （改这类值请用属性面板显式输入）——静默改成 px 会丢失作者意图。
+ */
+
+/** 数值坐标（非有限数字 → null） */
+export function parseNumericPosition(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * 拖拽落点：基准值可拖（数字或缺失）→ 新数值（四舍五入到整数像素）；
+ * 字符串坐标 → `null`（调用方**保持原值**，不写回）。
+ */
+export function draggedPosition(base: unknown, delta: number): number | null {
+  if (typeof base === "string" && base !== "") return null;
+  const start = parseNumericPosition(base) ?? 0;
+  return Math.round(start + delta);
+}

package/src/element/dragCreate.ts

@@ -0,0 +1,60 @@
+/**
+ * 舞台编辑：组件面板 → 舞台**落点创建**元素的纯逻辑。
+ *
+ * 与 `drag.ts`（移动已有元素）同域：DOM/事件留在组件，**判定与数值只在这里**——
+ * - `createElementDraft`：新元素的**最小草稿**（`{type,x,y}`）——只含契约内、有渲染语义的
+ *   属性，绝不含 `UNIMPLEMENTED_ELEMENT_ATTRS`（未实现属性清单：写了也不生效的属性不给默认值）；
+ *   未知类型 / 非有限坐标 fail-closed 返回 `null`（调用方忽略，不静默造坏节点）。
+ * - `planElementDrop`：落点规划——命中容器（组件侧已按 DOM rect 判定）→ **进 `children`**
+ *   且坐标换算为**相对容器原点**（与运行期渲染一致：子元素绝对定位于父容器内）；
+ *   未命中 → 追加为顶级元素，落点即 `x`/`y`。
+ */
+
+import { ELEMENT_TYPES } from "@lingfan-engine/core";
+
+/** 一次落点的规划结果：`parentIndex = null` → 顶级；否则 → 该下标容器的 `children`（坐标已换算为相对值） */
+export interface ElementDropPlan {
+  parentIndex: number | null;
+  x: number;
+  y: number;
+}
+
+/** 组件侧的容器命中信息（`index` = 顶级元素下标；`originX/Y` = 容器块在画布内容坐标系的原点） */
+export interface DropContainerHit {
+  index: number;
+  originX: number;
+  originY: number;
+}
+
+/**
+ * 落点规划：未命中容器 → 顶级（坐标 = 画布内容坐标，四舍五入到整数像素，与拖拽位移同口径）；
+ * 命中 → 相对容器原点取整。纯数值运算，DOM rect 的提取留在组件。
+ */
+export function planElementDrop(
+  x: number,
+  y: number,
+  container: DropContainerHit | undefined,
+): ElementDropPlan {
+  if (container === undefined) {
+    return { parentIndex: null, x: Math.round(x), y: Math.round(y) };
+  }
+  return {
+    parentIndex: container.index,
+    x: Math.round(x - container.originX),
+    y: Math.round(y - container.originY),
+  };
+}
+
+/**
+ * 新元素草稿：**最小面** `{type, x, y}`（数字坐标；id 缺省 = 运行期 `{列id}#{序号}` 寻址，
+ * 不在创建期生成，避免撞号逻辑）。
+ */
+export function createElementDraft(
+  type: string,
+  x: number,
+  y: number,
+): Record<string, unknown> | null {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+  if (!(ELEMENT_TYPES as readonly string[]).includes(type)) return null;
+  return { type, x: Math.round(x), y: Math.round(y) };
+}

package/src/element/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 元素编辑域出口：舞台拖拽的位移换算与拖放落点规划（纯函数，可测）。
+ * 只有数字坐标参与像素拖拽；百分比等 CSS 长度保持原值不动。
+ */
+export { parseNumericPosition, draggedPosition } from "./drag.ts";
+export {
+  planElementDrop,
+  createElementDraft,
+  type ElementDropPlan,
+  type DropContainerHit,
+} from "./dragCreate.ts";

package/src/i18n/coverage.ts

@@ -0,0 +1,191 @@
+/**
+ * 本地化工作台 · **覆盖率与状态判据**（纯函数，可测）。
+ *
+ * 为何不直接用 `reconcileTranslations` 就够了：它给的是**缺译/多译的键集合**，
+ * 而工作台要回答的是「这个语言**到什么程度**了」——需要**比率**与**三态**，
+ * 且比率的**分母口径**必须显式（见下）。这是 UI 判据，不该散在模板里算。
+ *
+ * **分母口径（本模块最重要的决定）**：覆盖率分母 = **原文键总数**（`sources.length`），
+ * 而非「已出现的译键数」。理由：若用后者，`sources=[]` 时会出现 `0/0`，
+ * 而 `0/0` 在 UI 上会被渲染成 `NaN%` 或 `Infinity%` ⇒ 用户看到"进度 100%"
+ * 或"进度未定义"。本模块把该情形**显式判为 `empty` 态**（见 `coverageStateOf`）。
+ */
+
+/** 单语言覆盖率 */
+export interface LangCoverage {
+  readonly lang: string;
+  /** 原文键总数（分母） */
+  readonly total: number;
+  /** 该语言已译键数（分子；只数**原文里存在**的键，多译键不进分子） */
+  readonly translated: number;
+  /** 缺译键（稳定排序） */
+  readonly missing: readonly string[];
+  /** 多译键（该语言有、原文无；稳定排序） */
+  readonly unused: readonly string[];
+  /** 覆盖率 0~1（**分母为 0 时取 0**，绝不给 NaN） */
+  readonly ratio: number;
+  /** 原文**字符总数**（码点计：中文 1/字，emoji 不因代理对算 2） */
+  readonly totalChars: number;
+  /** 已译原文的**字符总数** */
+  readonly translatedChars: number;
+  /**
+   * **字数加权覆盖率** 0~1（分母为 0 时取 0）。
+   *
+   * 为什么要加权：条数比把「一句长台词」与「一个两字词」同等看待，
+   * 而译者体感是**长句没翻更显眼**。未译键里大量是短词
+   * ⇒ 条数比会**低估**译者的实际工作量。
+   *
+   * 权重取**原文长度**（不取译文长度）：i18n 体系里**键 = 原文**，
+   * 所以无需值即可算；且「这句原话有多重要」只与原话长短有关，与译本无关。
+   * 用译文长度会**奖励「译得长」**（同一句翻成啰嗦的版本反而提升覆盖率）——语义错。
+   */
+  readonly weightedRatio: number;
+}
+
+/** 键的权重 = **码点长度**（`[...s].length`：中文每字算 1；`s.length` 会把 emoji 算 2） */
+function weightOf(key: string): number {
+  return [...key].length;
+}
+
+/**
+ * 单语言覆盖率。
+ *
+ * 分子的口径：`translated` 只数**原文与该语言译文的交集**——
+ * 多译键（译文有、原文无）**不计入**（它们不是"翻译了原文"，是残留）。
+ */
+export function langCoverage(
+  sources: readonly string[],
+  lang: string,
+  overlayKeys: readonly string[],
+): LangCoverage {
+  const sourceSet = new Set(sources);
+  const overlaySet = new Set(overlayKeys);
+  const missing: string[] = [];
+  let translated = 0;
+  let totalChars = 0;
+  let translatedChars = 0;
+  for (const source of sources) {
+    const w = weightOf(source);
+    totalChars += w;
+    if (overlaySet.has(source)) {
+      translated += 1;
+      translatedChars += w;
+    } else missing.push(source);
+  }
+  missing.sort();
+  const unused = [...overlaySet].filter((k) => !sourceSet.has(k)).sort();
+  return {
+    lang,
+    total: sources.length,
+    translated,
+    missing,
+    unused,
+    ratio: sources.length === 0 ? 0 : translated / sources.length,
+    totalChars,
+    translatedChars,
+    weightedRatio: totalChars === 0 ? 0 : translatedChars / totalChars,
+  };
+}
+
+/** 多语言工作台全貌（稳定排序：按语言码码元序） */
+export interface WorkbenchOverview {
+  readonly coverages: readonly LangCoverage[];
+  /** 全部语言的多译键并集（= `unused-translation` 诊断同口径） */
+  readonly unusedAll: readonly string[];
+  /** 原文键总数（各语言共用同一分母） */
+  readonly totalSources: number;
+  /** 原文**字符总数**（= 字数加权覆盖率的分母；各语言共用） */
+  readonly totalSourceChars: number;
+}
+
+/** 汇总多语言覆盖率（`overlayKeysByLang` 的键 = 语言码） */
+export function workbenchOverview(
+  sources: readonly string[],
+  overlayKeysByLang: Readonly<Record<string, readonly string[]>>,
+): WorkbenchOverview {
+  const langs = Object.keys(overlayKeysByLang).sort();
+  const coverages = langs.map((lang) =>
+    langCoverage(sources, lang, overlayKeysByLang[lang] ?? []),
+  );
+  const unusedAll = [...new Set(coverages.flatMap((c) => c.unused))].sort();
+  return {
+    coverages,
+    unusedAll,
+    totalSources: sources.length,
+    // 各语言共用同一分母（原文长度与译本无关）⇒ 不取 coverages 的平均，避免与「同一分母」矛盾
+    totalSourceChars: sources.reduce((sum, s) => sum + weightOf(s), 0),
+  };
+}
+
+/** 覆盖率的**三态**（UI 据此选文案与配色，绝不裸显示 `NaN%`） */
+export type CoverageState = "empty" | "untranslated" | "partial" | "complete";
+
+/**
+ * 三态判定。
+ *
+ * - `empty` = **原文为空**（无可译内容；`0/0` 归此类，**不是 100%**）
+ * - `complete` = 全部已译
+ * - `untranslated` = 一条都没译
+ * - `partial` = 其余
+ */
+export function coverageStateOf(c: LangCoverage): CoverageState {
+  if (c.total === 0) return "empty";
+  if (c.translated === c.total) return "complete";
+  if (c.translated === 0) return "untranslated";
+  return "partial";
+}
+
+/** 三态的显示文案（**状态口径**：描述当前状态，不叙述历史） */
+export function coverageLabelOf(state: CoverageState): string {
+  switch (state) {
+    case "empty":
+      return "无可译内容";
+    case "complete":
+      return "已全部译出";
+    case "untranslated":
+      return "尚未开始";
+    default:
+      return "部分已译";
+  }
+}
+
+/** 百分比文本（**永不出现 NaN/Infinity**；空态给「—」而不是 0%）——**按条数** */
+export function coveragePercentOf(c: LangCoverage): string {
+  if (c.total === 0) return "—";
+  return `${Math.round(c.ratio * 100)}%`;
+}
+
+/**
+ * **字数加权**百分比文本（主显示口径）。
+ *
+ * 为何它是主显示：条数比把「一句长台词」与「一个两字词」同等看待，
+ * 而译者体感是**长句没翻更显眼**。诊断里「未使用的译文键」多为短词
+ * ⇒ 条数比会**高估**完成度（短词翻完就跳一大截）。
+ *
+ * 空态判据与按条数版**一致**（`total === 0` ⇒ 「—」）：两者都是「无可译内容」的同一态，
+ * 不该一个「—」一个「0%」。而 `totalChars === 0` 只可能发生在所有键都是空串
+ * （已被上游 fail-closed 拦掉），但此处仍兜底。
+ */
+export function coverageWeightedPercentOf(c: LangCoverage): string {
+  if (c.total === 0 || c.totalChars === 0) return "—";
+  return `${Math.round(c.weightedRatio * 100)}%`;
+}
+
+/** 骨架生成的分组依据（骨架布局决定 `Lang/{lang}/**` 怎么切） */
+export type SkeletonLayoutChoice = "single" | "main" | "per-story";
+
+/**
+ * 按布局把「故事 → 该故事原文键」分好组，供 `planOverlaySkeleton` 消费。
+ *
+ * **键 = 故事文件相对 `Stories/` 的路径（不含扩展名）**（与 `SkeletonOptions` 契约一致）——
+ * 这里只做**分组**不做过滤（非法 id 由 `planOverlaySkeleton` fail-closed 抛）。
+ */
+export function groupKeysByStory(
+  storyKeys: ReadonlyMap<string, readonly string[]>,
+): ReadonlyMap<string, readonly string[]> {
+  const out = new Map<string, readonly string[]>();
+  for (const [story, keys] of storyKeys) {
+    out.set(story, [...keys].sort());
+  }
+  return out;
+}

package/src/i18n/extract.ts

@@ -0,0 +1,38 @@
+/**
+ * i18n 工具链 · 原文键抽取器。
+ *
+ * 「原文即 key」的正向半边：遍历故事，产出**会被运行期 Translate 的全部原文**
+ * （去重、稳定排序）。口径 = `TRANSLATE_SURFACES`（命令流，含嵌套块体）+ 元素 `text`
+ * （含 children 递归）——与诊断 `indexStory.originals` 同表同源；互锁测试锁定
+ * 「抽取器 ≡ 诊断原文集合 ≡ 运行期真查的键」三方可证。
+ */
+
+import type { Story } from "@lingfan-engine/core";
+import { walkStoryCommands, walkStoryElements } from "../schema/index.ts";
+import { isPlainObject } from "../shared/index.ts";
+import { TRANSLATE_SURFACES, valuesAtPath } from "./surfaces.ts";
+
+/**
+ * 从故事抽取可翻译原文键集合（= 运行期会查 overlay 表的全部字符串，插值前原文）。
+ * 畸形输入 fail-closed 返回空数组；输出**稳定排序**——骨架生成、
+ * 对账报告与快照对比的确定性都依赖它。
+ */
+export function extractStoryKeys(story: Story): string[] {
+  if (story === null || typeof story !== "object") return [];
+  const keys = new Set<string>();
+  walkStoryCommands(story, (cmd) => {
+    if (!isPlainObject(cmd) || typeof cmd.op !== "string") return;
+    for (const path of TRANSLATE_SURFACES[cmd.op] ?? []) {
+      for (const { value } of valuesAtPath(cmd, path)) {
+        if (typeof value === "string" && value !== "") keys.add(value);
+      }
+    }
+  });
+  // 元素展示文字（运行期 translateElements 同口径：装载时 Translate，递归 children）
+  walkStoryElements(story, (node) => {
+    if (!isPlainObject(node)) return;
+    const text = node.text;
+    if (typeof text === "string" && text !== "") keys.add(text);
+  });
+  return [...keys].sort();
+}

package/src/i18n/index.ts

@@ -0,0 +1,47 @@
+/**
+ * i18n 工具链（正向「从故事生成 i18n」）：翻译面单一事实源（surfaces）+
+ * 原文键抽取 + overlay 骨架生成 + 缺译/多译对账。
+ * 全部纯函数：落盘 / CLI / UI 归调用方；与诊断 originals 消费同一张面表
+ * （互锁：抽取与诊断同表、骨架往返、覆盖率报告）。
+ */
+
+export { TRANSLATE_SURFACES, valuesAtPath } from "./surfaces.ts";
+export { extractStoryKeys } from "./extract.ts";
+export { columnStoryKey } from "./storyKeys.ts";
+export {
+  planOverlaySkeleton,
+  type OverlaySkeletonFile,
+  type SkeletonLayout,
+  type SkeletonOptions,
+  type SkeletonPlaceholder,
+} from "./skeleton.ts";
+export {
+  formatTranslationReport,
+  reconcileTranslations,
+  type TranslationReconcileReport,
+} from "./reconcile.ts";
+export {
+  coverageLabelOf,
+  coveragePercentOf,
+  coverageWeightedPercentOf,
+  coverageStateOf,
+  groupKeysByStory,
+  langCoverage,
+  workbenchOverview,
+  type CoverageState,
+  type LangCoverage,
+  type SkeletonLayoutChoice,
+  type WorkbenchOverview,
+} from "./coverage.ts";
+export {
+  addTranslationRow,
+  isTableDirty,
+  parseTranslationTable,
+  removeTranslationRow,
+  renameTranslationRow,
+  serializeTranslationTable,
+  setTranslationValue,
+  type TableEdit,
+  type TableParse,
+  type TranslationRow,
+} from "./table.ts";