dsh-plugin-deck-studio 0.2.24 → 0.2.25

package/index.js

@@ -9,7 +9,7 @@
  * @module dsh-plugin-deck-studio
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -37,6 +37,7 @@ import { resolveMediaFile, scanDesignStyles, scanResources } from "./lib/home-ca
 import { defaultSelection, renderModelPayload, resolveSelection } from "./lib/render-nodes.js";
 import { applyRenderSettings, readRenderSettings, renderSettingsPayload, saveRenderSettings } from "./lib/render-settings.js";
 import { buildPrompt, editEndpointFor, selectRenderer } from "./lib/render.js";
+import { PDF_IMPORT_MAX_PAGES, applyImportedTitles, buildImportNote, extractIntentFields, headingsAsTitles, listImportDir, normalizeDpi, rasterizePdfToPng, scriptPagesFromMarkdown, titleFromPdfName } from "./lib/pdf-import.js";
 import { readDeckBrief } from "./lib/deck-brief.js";
 import { detectProfileDir, installModeOf, isNewer, latestFromRegistry, repoLinksOf } from "./lib/update-check.js";
 
@@ -78,6 +79,8 @@ export const ROUTES = {
   media: "/api/deck-studio.media",
   renderModel: "/api/deck-studio.render-model",
   deckCreate: "/api/deck-studio.deck-create",
+  // PDF 导入：目录里的一份 PDF → 每页整页图的 deck（附带 md 抽取）
+  deckImport: "/api/deck-studio.deck-import",
   deckDensity: "/api/deck-studio.deck-density",
   renderSettings: "/api/deck-studio.render-settings",
   userSettings: "/api/deck-studio.user-settings",
@@ -753,6 +756,193 @@ export function createService(config, logger, env = process.env) {
     };
   }
 
+  /**
+   * PDF 导入（需求 req_28a1eec6eab8）：导入目录里的 PDF → 每页一张整页图的 deck。
+   *
+   * 顺序：列目录（PDF / md）→ 栅格化（pdftoppm）→ createDeck（页数 = PDF 页数）→ 落 pages/p01.png…
+   * → md 抽取（script / intent / 其它 md 进 materials）→ 写导入说明 → 事件。
+   * - **只读**导入目录，产物全部落 createDeck 新建的目录；PDF 本身不复制。
+   * - 意图只抽 md 里已写好的字段，不推断；看图推意图是下一阶段。
+   * - `rasterize` 参数是测试缝（smoke 注入假栅格器，CI 不需要 poppler），产品路径用默认实现。
+   */
+  function importPdfDeck(payload = {}, { rasterize = rasterizePdfToPng } = {}) {
+    // 两种入口：直接给 PDF 绝对路径（工作台「点一份 PDF」走这条），或给目录 + 可选文件名（脚本 / API 用）。
+    const pdfPath = String(payload.pdf ?? "").trim();
+    let dir = String(payload.dir ?? "").trim();
+    let wanted = String(payload.file ?? "").trim();
+    if (pdfPath) {
+      if (!isAbsolute(pdfPath)) throw new Error(`PDF 要填绝对路径：${pdfPath}`);
+      if (!existsSync(pdfPath) || !statSync(pdfPath).isFile()) throw new Error(`PDF 不存在：${pdfPath}`);
+      if (!/\.pdf$/i.test(pdfPath)) throw new Error(`不是 PDF：${pdfPath}`);
+      dir = dirname(pdfPath);
+      wanted = basename(pdfPath);
+    }
+    if (!dir) throw new Error("请先选一份 PDF");
+    if (!isAbsolute(dir)) throw new Error(`导入目录要填绝对路径：${dir}`);
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`导入目录不存在：${dir}`);
+
+    const listing = listImportDir(dir);
+    if (!listing.pdfs.length) throw new Error("这个目录里没有 PDF（本轮只支持 PDF；PPTX 下一阶段再做）");
+    let pdf = listing.pdfs[0];
+    if (wanted) {
+      pdf = listing.pdfs.find((item) => item.name === wanted || item.path === wanted);
+      if (!pdf) throw new Error(`目录里没有这份 PDF：${wanted}`);
+    } else if (listing.pdfs.length > 1) {
+      throw new Error(`目录里有 ${listing.pdfs.length} 份 PDF，先指定要导入哪一份：${listing.pdfs.map((item) => item.name).join(" / ")}`);
+    }
+
+    const dpi = normalizeDpi(payload.dpi);
+    // 暂存区放在数据目录里（不是导入目录）：导入不该往别人的目录里写东西。
+    const staging = join(config.dataRoot, "imports", `staging-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`);
+    const raster = rasterize({ pdfPath: pdf.path, outDir: staging, dpi });
+    if (raster.pageCount > PDF_IMPORT_MAX_PAGES) {
+      rmSync(staging, { recursive: true, force: true });
+      throw new Error(`这份 PDF 有 ${raster.pageCount} 页，超过单次导入上限 ${PDF_IMPORT_MAX_PAGES} 页；先拆分再导入`);
+    }
+
+    try {
+      const mdTexts = listing.markdown.map((entry) => ({ ...entry, text: readFileSync(entry.path, "utf8") }));
+      const scriptEntry = mdTexts.find((entry) => /^script\.md$/i.test(entry.name));
+      const intentEntry = mdTexts.find((entry) => /^intent\.md$/i.test(entry.name));
+      const otherEntries = mdTexts.filter((entry) => entry !== scriptEntry && entry !== intentEntry);
+
+      // 意图字段：intent.md > script.md > 其它 md；只取第一个非空值，并记下来源。
+      const fields = {};
+      const fieldSources = {};
+      for (const entry of [intentEntry, scriptEntry, ...otherEntries]) {
+        if (!entry) continue;
+        const extracted = extractIntentFields(entry.text);
+        for (const [key, value] of Object.entries(extracted.fields)) {
+          if (fields[key]) continue;
+          fields[key] = value;
+          fieldSources[key] = `${entry.name} 的 ${extracted.sources[key] ?? "字段"}`;
+        }
+      }
+
+      const warnings = [];
+      const scriptRows = scriptEntry ? scriptPagesFromMarkdown(scriptEntry.text) : [];
+      const scriptMatches = scriptRows.length === raster.pageCount;
+      if (scriptEntry && !scriptMatches) {
+        warnings.push(`script.md 解析出 ${scriptRows.length} 页，和 PDF 的 ${raster.pageCount} 页对不上：已按 PDF 页数重建逐页骨架，请人工核对。`);
+      }
+      let titles = scriptMatches ? scriptRows.map((row) => String(row.title ?? "").trim()) : [];
+      if (!titles.length || titles.some((title) => !title)) {
+        const headingFallback = [intentEntry, scriptEntry, ...otherEntries]
+          .filter(Boolean)
+          .map((entry) => headingsAsTitles(entry.text, raster.pageCount))
+          .find((list) => list.length) ?? [];
+        if (headingFallback.length) titles = headingFallback;
+      }
+      titles = Array.from({ length: raster.pageCount }, (_, index) => titles[index] || `导入页 ${index + 1}`);
+
+      const title = String(payload.title ?? "").trim() || titleFromPdfName(pdf.name);
+      const deck = createDeck({
+        title,
+        dirName: payload.dirName,
+        pageTitles: titles,
+        audience: fields.audience,
+        topic: fields.topic,
+        intent: fields.intent,
+        occasion: fields.occasion,
+        success: fields.success,
+        scopeOut: fields.scopeOut,
+        contentDensity: payload.contentDensity,
+        kind: "deck",
+      });
+
+      // 1) 每页整页图：直接落 pages/p01.png…，sourceImages() 认的就是这套命名。
+      const pagesDir = join(deck.sourceRoot, "pages");
+      mkdirSync(pagesDir, { recursive: true });
+      for (const file of raster.files) copyFileSync(file.file, join(pagesDir, `${file.pageId}.png`));
+
+      // 2) md 抽取：script 页数对得上才当脚本源；intent.md 有就直接沿用原文。
+      const copiedScript = Boolean(scriptEntry && scriptMatches);
+      if (copiedScript) writeFileSync(join(deck.sourceRoot, "script.md"), scriptEntry.text, "utf8");
+      if (!copiedScript) {
+        // 没沿用 md 脚本时，把占位「**标题**：待定」换成导入推出来的标题，否则每页都显示「待定」。
+        const scriptFile = join(deck.sourceRoot, "script.md");
+        writeFileSync(scriptFile, applyImportedTitles(readFileSync(scriptFile, "utf8"), titles), "utf8");
+      }
+      if (intentEntry) writeFileSync(join(deck.sourceRoot, "intent.md"), intentEntry.text, "utf8");
+
+      // 3) 其余 md → materials/，并在支撑材料清单里登记（表头必须是 文件名/链接/总结，见 deck-templates）。
+      const materialsDir = join(deck.sourceRoot, "materials");
+      const materialRows = [];
+      for (const entry of otherEntries) {
+        mkdirSync(materialsDir, { recursive: true });
+        copyFileSync(entry.path, join(materialsDir, entry.name));
+        const sizeKb = Math.max(1, Math.round(entry.sizeBytes / 1024));
+        materialRows.push({ ref: `materials/${entry.name}`, type: "文件", status: "已找到", note: `${sizeKb} KB · 随 PDF 一起导入，待 Agent 抽事实` });
+      }
+      const materialsFile = join(workspace.deckDir(deck.deckId), "docs", "materials.md");
+      mkdirSync(dirname(materialsFile), { recursive: true });
+      writeFileSync(
+        materialsFile,
+        buildMaterialsMarkdown({
+          title,
+          raw: `从导入目录 ${dir} 导入：PDF \`${pdf.name}\`（${raster.pageCount} 页 · ${raster.dpi} dpi，整页图见 pages/，原 PDF 不复制）${materialRows.length ? `；另带 ${materialRows.length} 份 md` : ""}。`,
+          rows: materialRows,
+        }),
+        "utf8",
+      );
+
+      // 4) 导入说明写进 intent.md 末尾：哪来的、抽到哪几个字段、哪些没做。
+      const intentFile = join(deck.sourceRoot, "intent.md");
+      if (existsSync(intentFile)) {
+        const note = buildImportNote({
+          pdfName: pdf.name,
+          pageCount: raster.pageCount,
+          dpi: raster.dpi,
+          mdFiles: mdTexts.map((entry) => entry.name),
+          fieldSources,
+          warnings,
+        });
+        writeFileSync(intentFile, `${readFileSync(intentFile, "utf8").trimEnd()}\n\n${note}`, "utf8");
+      }
+
+      // 5) 页数 / 标题变了 → 重建 manifest（createDeck 里建的是占位页）。
+      const adapter = adapters.find((item) => item.id === deck.deckId);
+      if (adapter) {
+        try {
+          workspace.ensureDeck(adapter, { forceRebuild: true });
+        } catch (error) {
+          logger?.warn?.(`deck-studio: 导入 deck ${deck.deckId} 重建 manifest 失败：${error?.message ?? error}`);
+        }
+      }
+
+      store.recordEvent({
+        type: "deck.imported",
+        deckId: deck.deckId,
+        actor: "user",
+        status: "succeeded",
+        payload: {
+          label: deck.label,
+          sourceRoot: deck.sourceRoot,
+          importedFrom: dir,
+          pdf: pdf.name,
+          pages: raster.pageCount,
+          dpi: raster.dpi,
+          markdown: mdTexts.map((entry) => entry.name),
+          copiedScript,
+          note: `PDF 导入：${raster.pageCount} 页整页图${copiedScript ? " + script.md" : ""}${materialRows.length ? ` + ${materialRows.length} 份材料` : ""}`,
+        },
+      });
+
+      return {
+        deck: { ...deck, pages: raster.pageCount },
+        importedFrom: dir,
+        pdf: { name: pdf.name, sizeBytes: pdf.sizeBytes },
+        pages: raster.pageCount,
+        dpi: raster.dpi,
+        markdown: mdTexts.map((entry) => entry.name),
+        copiedScript,
+        warnings,
+      };
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+    }
+  }
+
   /**
    * F-124：设置 deck 的内容密度（auto / concise / medium / dense）。
    * 只改 manifest 设置，不改已有内容；Agent 下次读 script / 提案时按新目标字数写。
@@ -2399,7 +2589,7 @@ export function createService(config, logger, env = process.env) {
     bootstrapDesignStyles();
   }
 
-  return { config, store, workspace, adapters, status, state, workbench, readManual, readUserName: () => config.userName, saveUserName, readDoc, docsAsset, setDeckDensity, renderSettings, saveRenderConfig, isLocalDeck: (deckId) => localDeckIds().has(String(deckId ?? "")), assetFile, slideRenderInfo, deckCoverUrl, deckRevisions, deckDocs, deckDoc, deckDocsScaffold, deckDocFile, pageForEdit, pagePrompt, savePage, exportDeckFile, designSamples, sourceFile, homeCatalog, mediaFile, renderState, setRenderSelection, renderRuntime, createDeck, createDesign, createStyleFromDeck, designProjects, designStyle, updateDesignStyle, backfillStyleBriefs, listBindings, bindSession, unbindSession, deleteDesign, deleteDeck, setDeckDesign, addDesignSamples, seedStyleDesigns, renderStatus, exportHandoff, updateBrief, updateStatus, runSelfUpdate }
+  return { config, store, workspace, adapters, status, state, workbench, readManual, readUserName: () => config.userName, saveUserName, readDoc, docsAsset, setDeckDensity, renderSettings, saveRenderConfig, isLocalDeck: (deckId) => localDeckIds().has(String(deckId ?? "")), assetFile, slideRenderInfo, deckCoverUrl, deckRevisions, deckDocs, deckDoc, deckDocsScaffold, deckDocFile, pageForEdit, pagePrompt, savePage, exportDeckFile, designSamples, sourceFile, homeCatalog, mediaFile, renderState, setRenderSelection, renderRuntime, createDeck, importPdfDeck, createDesign, createStyleFromDeck, designProjects, designStyle, updateDesignStyle, backfillStyleBriefs, listBindings, bindSession, unbindSession, deleteDesign, deleteDeck, setDeckDesign, addDesignSamples, seedStyleDesigns, renderStatus, exportHandoff, updateBrief, updateStatus, runSelfUpdate }
 }
 
 /* ─────────────────────────────────────────────────────────────────────────
@@ -2846,7 +3036,7 @@ export function apply(ctx, rawConfig) {
    * @param {string} pathValue 绝对路径；空 = 当前生效的 dataRoot
    * @returns {{path: string, parent: string, isRoot: boolean, truncated: boolean, dirs: {name: string, path: string, hidden: boolean, hasScript: boolean, deckCount: number, isDataRoot: boolean}[]}}
    */
-  function browseDir(pathValue) {
+  function browseDir(pathValue, { includeFiles = false } = {}) {
     const raw = String(pathValue ?? "").trim();
     if (raw && !isAbsolute(raw)) {
       const error = new Error(`必须是绝对路径：${raw}`);
@@ -2877,6 +3067,7 @@ export function apply(ctx, rawConfig) {
       throw failed;
     }
     const dirs = [];
+    const files = [];
     let truncated = false;
     for (const entry of entries) {
       if (dirs.length >= BROWSE_MAX_ENTRIES) {
@@ -2893,7 +3084,22 @@ export function apply(ctx, rawConfig) {
           childIsDir = false;
         }
       }
-      if (!childIsDir) continue;
+      if (!childIsDir) {
+        // 导入 PDF 要从这里直接点文件：只认 pdf / md，其它一律不列（不暴露目录里有什么）。
+        if (includeFiles && entry.isFile()) {
+          const kind = /\.pdf$/i.test(entry.name) ? "pdf" : /\.md$/i.test(entry.name) ? "md" : "";
+          if (kind) {
+            let sizeBytes = 0;
+            try {
+              sizeBytes = statSync(childPath).size;
+            } catch {
+              sizeBytes = 0;
+            }
+            files.push({ name: entry.name, path: childPath, kind, sizeBytes });
+          }
+        }
+        continue;
+      }
       dirs.push({
         name: entry.name,
         path: childPath,
@@ -2904,6 +3110,7 @@ export function apply(ctx, rawConfig) {
       });
     }
     dirs.sort((a, b) => a.name.localeCompare(b.name));
+    files.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === "pdf" ? -1 : 1));
     const parentPath = dirname(target);
     return {
       path: target,
@@ -2911,7 +3118,48 @@ export function apply(ctx, rawConfig) {
       isRoot: parentPath === target,
       truncated,
       dirs,
+      ...(includeFiles ? { files } : {}),
+    };
+  }
+
+  /** 有界地找子目录里的 PDF（导入 PDF 用：先看当前层，找不到再一键往下找）。 */
+  function findPdfFiles(rootDir, { maxDepth = 3, maxFiles = 60 } = {}) {
+    const found = [];
+    let truncated = false;
+    const walk = (dir, depth) => {
+      if (found.length >= maxFiles) {
+        truncated = true;
+        return;
+      }
+      let entries = [];
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (found.length >= maxFiles) {
+          truncated = true;
+          return;
+        }
+        if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+        const childPath = join(dir, entry.name);
+        if (entry.isFile() && /\.pdf$/i.test(entry.name)) {
+          let sizeBytes = 0;
+          try {
+            sizeBytes = statSync(childPath).size;
+          } catch {
+            sizeBytes = 0;
+          }
+          found.push({ name: entry.name, path: childPath, kind: "pdf", sizeBytes });
+          continue;
+        }
+        if (depth < maxDepth && entry.isDirectory()) walk(childPath, depth + 1);
+      }
     };
+    walk(rootDir, 0);
+    found.sort((a, b) => a.path.localeCompare(b.path));
+    return { files: found, truncated };
   }
 
   // 目录浏览（目录选择器）：GET ?path=<绝对路径>；缺省 = 当前 dataRoot。
@@ -2920,7 +3168,31 @@ export function apply(ctx, rawConfig) {
     if (switching) return switchingResponse();
     const url = new URL(request?.url ?? "/", "http://localhost");
     try {
-      return json({ ok: true, dir: browseDir(url.searchParams.get("path") ?? "") });
+      const includeFiles = url.searchParams.get("files") === "1";
+      if (url.searchParams.get("find") === "pdf") {
+        const raw = String(url.searchParams.get("path") ?? "").trim();
+        if (raw && !isAbsolute(raw)) {
+          const error = new Error(`必须是绝对路径：${raw}`);
+          error.code = "bad-path";
+          throw error;
+        }
+        const target = resolve(raw || config.dataRoot || process.cwd());
+        let stats;
+        try {
+          stats = statSync(target);
+        } catch {
+          const error = new Error(`目录不存在：${target}`);
+          error.code = "not-found";
+          throw error;
+        }
+        if (!stats.isDirectory()) {
+          const error = new Error(`不是目录：${target}`);
+          error.code = "not-a-dir";
+          throw error;
+        }
+        return json({ ok: true, found: { path: target, ...findPdfFiles(target) } });
+      }
+      return json({ ok: true, dir: browseDir(url.searchParams.get("path") ?? "", { includeFiles }) });
     } catch (error) {
       const code = error?.code ?? "browse-failed";
       const status = code === "switching" ? 409 : code === "browse-failed" ? 500 : 400;
@@ -2994,6 +3266,28 @@ export function apply(ctx, rawConfig) {
     return json({ ok: true, deck: service.createDeck(body) });
   }, ["POST"]);
 
+  // PDF 导入：body { dir, file?, title?, dirName?, dpi? }。错误按 code 分支，message 只做兜底（与 dir-browse 一致）。
+  registerRoute(ROUTES.deckImport, async (request) => {
+    if ((request?.method ?? "POST").toUpperCase() !== "POST") return json({ ok: false, error: { code: "method", message: "POST only" } }, 405);
+    const body = await request.json().catch(() => ({}));
+    try {
+      return json({ ok: true, ...service.importPdfDeck(body) });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const code = error?.code === "pdftoppm-missing"
+        ? "pdftoppm-missing"
+        : /不在|没有 PDF|没有这份 PDF|份 PDF|不是 PDF|PDF 不存在/.test(message)
+          ? "no-pdf"
+          : /不存在/.test(message)
+            ? "not-found"
+            : /超过单次导入上限|绝对路径|请先选/.test(message)
+              ? "bad-dir"
+              : "import-failed";
+      const status = code === "import-failed" ? 500 : code === "pdftoppm-missing" ? 501 : 400;
+      return json({ ok: false, error: { code, message } }, status);
+    }
+  }, ["POST"]);
+
   // 生图设置（F-126）：body { mode, endpoint, model, apiKeyEnv, apiKeyFile, size }，存本机数据目录并即刻生效。
   registerRoute(ROUTES.renderSettings, async (request) => {
     if ((request?.method ?? "GET").toUpperCase() === "GET") return json({ ok: true, ...service.renderSettings() });

package/lib/capabilities.js

@@ -6,6 +6,7 @@
 import { lstatSync, realpathSync, readdirSync } from "node:fs";
 import { isAbsolute, resolve, relative, sep, parse, join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { presentNative } from "./present-native.js";
 
 export const name = "deck-studio-capabilities";
 export const inject = ["tools", "workingDirectory", "agents", "systemPrompt"];
@@ -183,7 +184,7 @@ export function createResearchProvider(ctx, config = {}, dependencies = {}) {
           signal: controller.signal,
           setup(agentCtx, child) {
             agentCtx.systemPrompt.suppressRuntimeContext();
-            agentCtx.tools.presentAs("native");
+            presentNative(agentCtx.tools);
             agentCtx.tools.restrict({ allow: [] });
             for (const definition of researchDefinitions) agentCtx.tools.register(definition);
             agentCtx.tools.guard(createCapabilityGuard(ctx, config, { readonly: true, cwd }));
@@ -217,7 +218,7 @@ export function createResearchProvider(ctx, config = {}, dependencies = {}) {
 
 /** Mount ONLY under the main-assistant preset, never the root router mount. */
 export function apply(ctx, config = {}) {
-  ctx.tools.presentAs("native");
+  presentNative(ctx.tools);
   ctx.tools.guard(createCapabilityGuard(ctx, config));
   const provider = createResearchProvider(ctx, config);
   ctx.tools.register({

package/lib/pdf-import.js

@@ -0,0 +1,270 @@
+/**
+ * PDF 导入（需求 req_28a1eec6eab8，2026-11-06）：把目录里的一份 PDF 变成 Deckline 的
+ * 「每页一张整页图」deck，顺带抽取同目录里的 md。
+ *
+ * 设计边界（先看清再改）：
+ * - **不做 OCR、不做视觉推理**：意图字段只从 md 里「已经写好的」字段抽；抽不到就留占位，
+ *   并在 intent.md 末尾写「导入说明（推断 · 待确认）」。看图推意图是下一阶段的事。
+ * - **导入的整页图是参考 baseline**，不是最终交付图：PDF 渲染出来的字/版式与源 pptx 不一致时
+ *   不能当过审的稿子用（真正的原因见 docs/architecture.md「导入」一节）。
+ * - 纯函数（分类 / 抽字段 / 标题启发 / 说明生成）都不碰磁盘，smoke 直接测；
+ *   IO 只有两处：`listImportDir()` 与 `rasterizePdfToPng()`。
+ * - `rasterizePdfToPng()` 依赖 poppler 的 `pdftoppm`（本机 brew install poppler）。
+ *   插件本身不引入 npm 依赖，缺二进制时**明确报错**，不静默降级成空 deck。
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { parseSectionedPages, parseStoryPages } from "./source-adapter.js";
+
+export const PDF_IMPORT_DEFAULT_DPI = 120;
+export const PDF_IMPORT_MIN_DPI = 72;
+export const PDF_IMPORT_MAX_DPI = 300;
+/** 一次导入的页数上限：够覆盖常见分享会 deck，又不至于让一次请求跑十几分钟。 */
+export const PDF_IMPORT_MAX_PAGES = 40;
+
+/** dpi 规范化：非数字回默认，超范围夹到边界（越界不报错，导入不该因为参数小错失败）。 */
+export function normalizeDpi(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) return PDF_IMPORT_DEFAULT_DPI;
+  return Math.min(PDF_IMPORT_MAX_DPI, Math.max(PDF_IMPORT_MIN_DPI, parsed));
+}
+
+/** 目录里哪些文件是导入源：只要 PDF 与 md（其它文件不猜、不读）。 */
+export function classifyImportNames(names = []) {
+  const pdfs = [];
+  const markdown = [];
+  for (const raw of Array.isArray(names) ? names : []) {
+    const name = String(raw ?? "").trim();
+    if (!name || name.startsWith(".")) continue;
+    if (/\.pdf$/i.test(name)) pdfs.push(name);
+    else if (/\.md$/i.test(name)) markdown.push(name);
+  }
+  return { pdfs: pdfs.sort(), markdown: markdown.sort() };
+}
+
+/** 从 PDF 文件名推 deck 标题（末级兜底，用户填了就用用户的）。 */
+export function titleFromPdfName(fileName = "") {
+  const base = basename(String(fileName ?? ""), extname(String(fileName ?? "")));
+  return base.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim() || "导入的 deck";
+}
+
+/** 意图六字段的别名表（中文 / 英文都认，大小写不敏感）。 */
+const INTENT_FIELDS = [
+  { key: "audience", labels: ["听众", "受众", "用户", "audience"] },
+  { key: "topic", labels: ["主题", "话题", "topic"] },
+  { key: "intent", labels: ["意图", "带走", "intent"] },
+  { key: "occasion", labels: ["场合", "时长", "occasion"] },
+  { key: "success", labels: ["成功标准", "success"] },
+  { key: "scopeOut", labels: ["不讲的", "不讲", "边界", "scopeout", "scope-out"] },
+];
+
+/** 占位值不算抽取成功（「（待补：…）」正是模板里的空位）。 */
+function isEmptyPlaceholder(value) {
+  const text = String(value ?? "").trim();
+  if (!text) return true;
+  return /^[（(]\s*待补/.test(text) || /^[（(]\s*未填/.test(text);
+}
+
+/**
+ * frontmatter 的键值对。这里**不复用** source-adapter 的 `parseFrontmatter`：
+ * 它只认 ASCII 键名（`^[A-Za-z0-9_-]+`），
+ * 而导入目录里的 md 常写 `听众:` / `主题:` 这种中文键——那些正是我们要抽的字段。
+ */
+function readFrontmatterPairs(text = "") {
+  const body = String(text ?? "");
+  if (!body.startsWith("---")) return [];
+  const end = body.indexOf("\n---", 3);
+  if (end < 0) return [];
+  const pairs = [];
+  for (const line of body.slice(4, end).split("\n")) {
+    if (!line.trim() || /^\s*[-#]/.test(line)) continue;
+    const match = /^\s*([^:\s][^:]{0,31}?)\s*[：:]\s*(.*)$/.exec(line);
+    if (!match) continue;
+    pairs.push([match[1].trim(), match[2].trim()]);
+  }
+  return pairs;
+}
+
+function cleanFieldValue(value) {
+  return String(value ?? "").replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
+}
+
+/**
+ * 从一段 md 里抽意图字段：
+ * 1. frontmatter（`audience:` / `听众:` 等）；
+ * 2. `**听众**：…` 这种结构化字段行（Deckline 自己的 intent.md 就是这个写法）。
+ * 只抽「已经写好的」，不推断；返回 `sources` 方便在说明里交代每个字段从哪来。
+ */
+export function extractIntentFields(text = "") {
+  const fields = {};
+  const sources = {};
+  const body = String(text ?? "");
+  if (!body.trim()) return { fields, sources };
+
+  const metaEntries = readFrontmatterPairs(body);
+  for (const { key, labels } of INTENT_FIELDS) {
+    for (const label of labels) {
+      const hit = metaEntries.find(([name]) => String(name).trim().toLowerCase() === label.toLowerCase());
+      if (!hit) continue;
+      const value = cleanFieldValue(hit[1]);
+      if (isEmptyPlaceholder(value)) continue;
+      fields[key] = value;
+      sources[key] = `frontmatter · ${hit[0]}`;
+      break;
+    }
+  }
+
+  for (const line of body.split("\n")) {
+    const match = /^\s*[-*]?\s*\*\*([^*]{1,16})\*\*\s*[：:]\s*(.+)$/.exec(line);
+    if (!match) continue;
+    const label = match[1].trim();
+    const value = cleanFieldValue(match[2]);
+    if (isEmptyPlaceholder(value)) continue;
+    for (const { key, labels } of INTENT_FIELDS) {
+      if (fields[key]) continue;
+      if (labels.some((item) => label.toLowerCase() === item.toLowerCase())) {
+        fields[key] = value;
+        sources[key] = `「${label}」字段`;
+      }
+    }
+  }
+  return { fields, sources };
+}
+
+/**
+ * 标题启发：md 里 `#` / `##` 标题的条数**正好等于页数**（或多一条文档大标题）时，
+ * 才把它们当逐页标题——数量对不上就宁可不用，也不硬塞。
+ */
+export function headingsAsTitles(text = "", pageCount = 0) {
+  const count = Number(pageCount) || 0;
+  if (!count) return [];
+  const heads = String(text ?? "")
+    .split("\n")
+    .map((line) => /^(#{1,2})\s+(.+?)\s*$/.exec(line.trim()))
+    .filter(Boolean)
+    .map((match) => match[2].replace(/\*\*/g, "").replace(/^\d+[.、)]\s*/, "").trim())
+    .filter(Boolean);
+  if (heads.length === count) return heads;
+  if (heads.length === count + 1) return heads.slice(1);
+  return [];
+}
+
+/** 一份 md 能不能当这台 deck 的 script：逐页解析出来的页数必须和 PDF 页数一致。 */
+export function scriptPagesFromMarkdown(text = "") {
+  const body = String(text ?? "");
+  if (!body.trim()) return [];
+  const table = parseStoryPages(body);
+  const rows = table.length ? table : parseSectionedPages(body);
+  return rows.filter((row) => row && Number(row.page) > 0);
+}
+
+/**
+ * 把 `createDeck()` 写出来的占位 `**标题**：待定` 换成导入时推出来的页标题。
+ * 不改分节头（`### P01 · …` 在建档时已经是目标标题），只补「标题」字段——
+ * 否则 deck 列表 / 工作台每一页都显示「待定」，等于没导入。
+ */
+export function applyImportedTitles(scriptText = "", titles = []) {
+  let index = 0;
+  return String(scriptText ?? "").replace(/^\*\*标题\*\*\s*[：:].*$/gm, (line) => {
+    const title = String(titles[index] ?? "").trim();
+    index += 1;
+    return title ? `**标题**：${title}` : line;
+  });
+}
+
+/**
+ * 导入说明（写在 intent.md 末尾）：把「哪些是抽到的、哪些是占位、哪些没做」一次交代清楚，
+ * 避免用户或 Agent 把导入的占位当成已确认的意图。
+ */
+export function buildImportNote({
+  pdfName = "",
+  pageCount = 0,
+  dpi = PDF_IMPORT_DEFAULT_DPI,
+  mdFiles = [],
+  fieldSources = {},
+  warnings = [],
+} = {}) {
+  const lines = [
+    "## 导入说明（推断 · 待确认）",
+    "",
+    `- 来源：\`${pdfName || "（未知 PDF）"}\` —— ${Number(pageCount) || 0} 页 · ${Number(dpi) || PDF_IMPORT_DEFAULT_DPI} dpi，每页已落成整页图 \`pages/p01.png…\`。`,
+    `- 抽到的 md：${mdFiles.length ? mdFiles.map((name) => `\`${name}\``).join("、") : "（目录里没有 md）"}。`,
+  ];
+  const sourced = Object.entries(fieldSources ?? {}).filter(([, from]) => from);
+  lines.push(
+    `- 上面字段的来源：${sourced.length ? sourced.map(([key, from]) => `${key} ← ${from}`).join("；") : "没有抽到现成字段，全部是占位"}。`,
+  );
+  lines.push("- 没做的：**逐页看图推断意图**（本轮不做视觉推理）。需要时让 Agent 读整页图后补这里。");
+  lines.push("- 提醒：导入的整页图是**参考 baseline**（`rev=source`），不是最终交付图；要重出图请走正常出图流程。");
+  for (const warning of Array.isArray(warnings) ? warnings : []) lines.push(`- ⚠️ ${warning}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** 列导入目录（只读一层，不递归）：返回 PDF / md 的文件对象。 */
+export function listImportDir(dir) {
+  const names = readdirSync(dir).filter((name) => !name.startsWith("."));
+  const { pdfs, markdown } = classifyImportNames(names);
+  const stat = (name) => {
+    const path = join(dir, name);
+    const info = statSync(path);
+    return { name, path, sizeBytes: info.size };
+  };
+  return {
+    dir,
+    pdfs: pdfs.map(stat),
+    markdown: markdown.map(stat),
+  };
+}
+
+/** poppler 的 pdftoppm 在不在（只用于提前给人话提示）。 */
+export function hasPdftoppm() {
+  try {
+    execFileSync("pdftoppm", ["-v"], { stdio: "ignore", timeout: 10_000 });
+    return true;
+  } catch (error) {
+    return error?.code !== "ENOENT";
+  }
+}
+
+/**
+ * PDF → 每页 PNG。
+ * 输出名统一成 `p01.png … pNN.png`（两位补零，超过 99 页按实际位数），
+ * 与 `source-adapter.sourceImages()` 认的 `P01.png` 约定一致（大小写都认）。
+ */
+export function rasterizePdfToPng({ pdfPath, outDir, dpi = PDF_IMPORT_DEFAULT_DPI } = {}) {
+  if (!pdfPath || !existsSync(pdfPath)) throw new Error(`PDF 不存在：${pdfPath ?? "（空）"}`);
+  const value = normalizeDpi(dpi);
+  mkdirSync(outDir, { recursive: true });
+  const rawPrefix = join(outDir, "raw");
+  try {
+    execFileSync("pdftoppm", ["-png", "-r", String(value), pdfPath, rawPrefix], {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 20 * 60 * 1000,
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      const missing = new Error("PDF 导入需要 poppler 的 `pdftoppm`：macOS `brew install poppler`，Debian/Ubuntu `apt install poppler-utils`");
+      missing.code = "pdftoppm-missing";
+      throw missing;
+    }
+    const stderr = String(error?.stderr ?? "").trim();
+    throw new Error(`PDF 转图片失败：${stderr || error?.message || "pdftoppm 退出异常"}`);
+  }
+
+  const produced = readdirSync(outDir)
+    .filter((name) => /^raw-\d+\.png$/i.test(name))
+    .map((name) => ({ name, page: Number(/^raw-(\d+)\.png$/i.exec(name)[1]) }))
+    .sort((a, b) => a.page - b.page);
+  if (!produced.length) throw new Error("pdftoppm 没有产出任何页图（PDF 可能损坏、加密或没有页面）");
+
+  const files = produced.map((item, index) => {
+    const pageId = `p${String(index + 1).padStart(2, "0")}`;
+    const file = join(outDir, `${pageId}.png`);
+    renameSync(join(outDir, item.name), file);
+    return { pageId, file, bytes: statSync(file).size };
+  });
+  return { files, pageCount: files.length, dpi: value };
+}

package/lib/present-native.js

@@ -0,0 +1,17 @@
+/**
+ * Declare native tool presentation, when the host still has that API.
+ *
+ * DSH `0.2.1-rc.2` exposes `ctx.tools.presentAs()` and a preset must declare its
+ * presentation there; DSH `0.2.2-rc.1` removed the method and mounts
+ * `@deepseek-ai/dsh-tool-executor-native` at the base layer instead. Calling it
+ * unconditionally on `0.2.2` throws `ctx.tools.presentAs is not a function`
+ * while the preset mounts, which surfaces as `agent-preset/invalid` and blocks
+ * every new deck session. Feature-detect instead of version-sniffing: native
+ * execution is the only shape this plugin supports, so declaring it is a no-op
+ * on hosts that already default to it.
+ */
+
+/** @param {{ presentAs?: (mode: "native") => void } | undefined} tools */
+export function presentNative(tools) {
+  if (typeof tools?.presentAs === "function") tools.presentAs("native");
+}

package/lib/review-agent.js

@@ -1,6 +1,7 @@
 /** Dedicated, preset-free, one-shot audience reviewer. No Cordis import is required. */
 import { randomUUID } from "node:crypto";
 import { isAbsolute } from "node:path";
+import { presentNative } from "./present-native.js";
 
 export const REVIEW_AGENT_PROVIDER = "deck-studio-review";
 
@@ -122,7 +123,7 @@ export function registerReviewAgentProvider(ctx, dependencies = {}) {
           signal: controller.signal,
           setup(agentCtx, child) {
             agentCtx.systemPrompt.suppressRuntimeContext();
-            agentCtx.tools.presentAs("native");
+            presentNative(agentCtx.tools);
             agentCtx.tools.restrict({ allow: [] });
             agentCtx.tools.guard(() => "Internal reviewers cannot execute tools");
             agentCtx.systemPrompt.section({ name: "deck-studio:internal-review", order: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-deck-studio",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Deckline：DSH 的 image deck / PPT 工作台插件——原生 Chat + 整页图片 deck 工作区 + 设计风格库；用对话做 PPT、按页出图、版本可追踪、导出 PDF/PPTX。",
   "icon": "assets/icon.svg",
   "homepage": "https://github.com/yuna78/dsh-deck-studio#readme",

package/ui/workbench.html

@@ -128,6 +128,7 @@
 <section id="homeView" class="home">
   <aside class="home-nav">
     <button class="btn rail-new home-new-deck" id="newDeckBtn">＋ 新建 Deck</button>
+    <button class="btn alt rail-new home-new-deck" id="importPdfBtn" title="把一份 PDF 的每一页转成整页图，建一本 deck">⇪ 导入 PDF</button>
     <nav class="home-nav-list" id="homeNav">
       <button class="home-nav-item" data-section="decks"><span class="hn-icon">▦</span><span class="hn-label">Decks</span><em id="navCountDecks">0</em></button>
       <button class="home-nav-item" data-section="designs"><span class="hn-icon">◈</span><span class="hn-label">Designs</span><em id="navCountDesigns">0</em></button>
@@ -215,6 +216,42 @@
   </div>
 </div>
 
+<div id="importPdfModal" class="modal" hidden>
+  <div class="modal-card newdeck-card">
+    <div class="modal-head">
+      <div><div class="eyebrow">Import</div><h2>导入 PDF</h2></div>
+      <button class="modal-close" id="impClose" title="关闭">✕</button>
+    </div>
+    <div class="modal-body newdeck-body">
+      <p class="nd-tip">点一份 PDF：每一页会转成一张整页图，建一本新 deck。
+        <br>同一个文件夹里有 md 就顺手抽（页数对得上当脚本，其余进支撑材料），没有就只导入图。
+        <br>只支持 PDF（本机 poppler 的 <code>pdftoppm</code>）；单次上限 40 页。</p>
+      <div class="imp-picker">
+        <div class="imp-picker-bar">
+          <button type="button" class="btn ghost" id="impUp">↑ 上一级</button>
+          <code id="impPath">—</code>
+        </div>
+        <div class="imp-picker-list" id="impList"><div class="dir-picker-empty">正在读目录…</div></div>
+      </div>
+      <p class="engine-note" id="impSelected">还没有选 PDF：点上面的 📄 文件即可。</p>
+      <div class="nd-foot">
+        <label class="imp-dpi">清晰度
+          <select id="impDpi">
+            <option value="96">96 · 快</option>
+            <option value="120" selected>120 · 默认</option>
+            <option value="200">200 · 更清</option>
+            <option value="300">300 · 最清最慢</option>
+          </select>
+        </label>
+        <span class="spacer"></span>
+        <button type="button" class="btn alt" id="impCancel">取消</button>
+        <button type="button" class="btn" id="impSubmit" disabled>开始导入</button>
+      </div>
+      <p class="engine-note" id="impState"></p>
+    </div>
+  </div>
+</div>
+
 <div id="confirmModal" class="modal" hidden>
   <div class="modal-card confirm-card">
     <div class="modal-head">
@@ -518,6 +555,17 @@
 .dir-picker-tag{font-size:10.5px;color:#0f6975}
 .dir-picker-count{font-size:10.5px;color:#8a7a58}
 .dir-picker-list{border:1px solid #e3e1d8;border-radius:10px;max-height:42vh;overflow:auto;background:#fff}
+/* F-203：导入 PDF —— 直接在弹层里点文件，不让人手打目录 / 文件名 */
+.imp-picker{border:1px solid #e4ded0;border-radius:10px;overflow:hidden;margin:8px 0 10px;background:#fff}
+.imp-picker-bar{display:flex;align-items:center;gap:10px;padding:8px 10px;border-bottom:1px solid #f2efe6;background:#faf8f3}
+.imp-picker-bar code{flex:1;min-width:0;font-size:11.5px;color:#6d7f83;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.imp-picker-list{max-height:280px;overflow:auto;padding:2px}
+.imp-picker-list .dir-picker-row.selected{background:#eaf4f1;box-shadow:inset 0 0 0 1px #0d6b62}
+.imp-picker-list .dir-picker-name{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.imp-picker-list .imp-find{background:#fbf7ec;border-top:1px solid #f2efe6;color:#8a5b12}
+.imp-picker-list .imp-find:hover{background:#f7f1df}
+.imp-dpi{display:flex;align-items:center;gap:6px;font-size:12px;color:#6d7f83}
+.imp-dpi select{font-size:12px;padding:4px 6px;border-radius:8px;border:1px solid #dcd5c6;background:#fff}
 .dir-picker-row{display:flex;gap:10px;align-items:center;width:100%;padding:8px 12px;border:0;border-bottom:1px solid #f2efe6;background:transparent;text-align:left;font-size:12.5px;color:#18343b;cursor:pointer}
 .dir-picker-row:last-child{border-bottom:0}
 .dir-picker-row:hover{background:#f6f9f8}
@@ -1196,15 +1244,18 @@ function openDirPicker(options = {}) {
   const modal = getEl("dirPickerModal");
   if (!modal) return;
   const dd = readDataDir(DIAG_DATA || STATE.data);
-  if (dd.envOverride.active) {
+  const targetId = options.targetId || "frDataRoot";
+  // 只读闸只针对「选数据目录」；导入 PDF 选的是别人的目录，不该被 env 覆盖挡住。
+  const dataDirTarget = targetId === "frDataRoot" || targetId === "frProjectsRoot";
+  if (dataDirTarget && dd.envOverride.active) {
     // env 覆盖时目录是只读的，选也没用——直接说清楚，不弹一个点不动的界面。
     flash(ENV_READONLY_TEXT + "，改环境变量后重启 DSH", "error");
     return;
   }
   DIR_PICKER = {
     mode: options.mode === "switch" ? "switch" : "fill",
-    targetId: options.targetId || "frDataRoot",
-    path: options.path || dd.dataRoot.value || dd.dataRoot.effective || "",
+    targetId,
+    path: options.path || (dataDirTarget ? dd.dataRoot.value || dd.dataRoot.effective || "" : ""),
     data: null,
     loading: true,
     error: "",
@@ -1297,6 +1348,16 @@ async function confirmDirPicker() {
   const path = st.data.path;
   if (st.mode === "fill") {
     const targetId = st.targetId;
+    // 非数据目录的填写目标（导入 PDF 的目录）只往输入框里填，不借首次引导那张表单。
+    if (targetId !== "frDataRoot" && targetId !== "frProjectsRoot") {
+      closeDirPicker();
+      const input = getEl(targetId);
+      if (input) {
+        input.value = path;
+        input.dispatchEvent(new Event("input", { bubbles: true }));
+      }
+      return;
+    }
     closeDirPicker();
     const wizard = getEl("firstRunModal");
     const wizardOpen = wizard && wizard.hidden === false;
@@ -4858,6 +4919,239 @@ getEl("newDeckForm").addEventListener("submit", async (event) => {
   }
 });
 
+/* ---------------- 导入 PDF：点一份 PDF → 每页整页图建 deck；同目录 md 顺手抽（F-203） ----------------
+ * 交互目标（负责人反馈）：不要填目录 / 文件名 / 标题——直接浏览、点那份 PDF，同文件夹的 md 有就抽、没有拉倒。
+ * 目录列表：GET /api/deck-studio.dir-browse?files=1（只回 pdf / md）
+ * 子目录搜索：GET /api/deck-studio.dir-browse?find=pdf&path=…（深度 ≤3、最多 60 份，解决「这层只有文件夹」）
+ * 导入：POST /api/deck-studio.deck-import { pdf: <绝对路径>, dpi } */
+const IMPORT_ERR_TEXT = {
+  "pdftoppm-missing": "本机缺 poppler 的 pdftoppm：macOS 执行 `brew install poppler`，Linux 装 poppler-utils，装完重启 DSH。",
+  "no-pdf": "这个文件夹里没有 PDF（或者这份 PDF 读不到）。",
+  "not-found": "这个路径不存在，检查一下。",
+  "bad-dir": "这个路径不对：要绝对路径，单次最多 40 页。",
+};
+
+function importErrText(code, message) {
+  return IMPORT_ERR_TEXT[code] || message || "导入失败";
+}
+
+const IMP = {
+  path: "",
+  mode: "browse", // browse=看当前目录；found=子目录搜索结果的平铺列表
+  dirs: [],
+  pdfs: [],
+  mdCount: 0,
+  foundFiles: [],
+  foundTruncated: false,
+  stale: false, // 后端还是旧版（dir-browse 没返回 files）——必须重启 DSH
+  loading: false,
+  error: "",
+  selected: null,
+  busy: false,
+};
+
+function impSize(bytes) {
+  const n = Number(bytes) || 0;
+  if (n >= 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${Math.max(1, Math.round(n / 1024))} KB`;
+}
+
+function impSelectedText() {
+  if (!IMP.selected) return "还没有选 PDF：点上面的 📄 文件即可。";
+  const md = IMP.mdCount ? `同目录 ${IMP.mdCount} 份 md 会一起抽` : "同目录没有 md —— 只导入整页图";
+  return `已选：${IMP.selected.name} · ${md}`;
+}
+
+function impFileRow(file, label) {
+  const selected = IMP.selected?.path === file.path;
+  return `<button type="button" class="dir-picker-row imp-file${selected ? " selected" : ""}" data-imp-pdf="${esc(file.path)}" title="${esc(file.path)}"><span class="dir-picker-name">📄 ${esc(label)}</span><span class="dir-picker-meta">${impSize(file.sizeBytes)}</span></button>`;
+}
+
+function renderImportPicker() {
+  const list = getEl("impList");
+  if (!list) return;
+  getEl("impPath").textContent = IMP.mode === "found" ? `${IMP.path}（含子目录）` : IMP.path || "—";
+  getEl("impPath").title = IMP.path || "";
+  getEl("impUp").disabled = IMP.loading || !IMP.path || IMP.mode === "found";
+  getEl("impSubmit").disabled = !IMP.selected || IMP.busy;
+  getEl("impSelected").textContent = impSelectedText();
+
+  if (IMP.loading) {
+    list.innerHTML = `<div class="dir-picker-empty">正在读目录…</div>`;
+    return;
+  }
+  if (IMP.error) {
+    list.innerHTML = `<div class="dir-picker-empty">${esc(IMP.error)}</div>`;
+    return;
+  }
+  if (IMP.stale) {
+    list.innerHTML = `<div class="dir-picker-empty">这个弹层是新版，但**正在运行的 Deckline 后端还是旧版**：<br>接口没返回文件列表，所以只看得到文件夹。<br><br>重启 DSH（<code>dsh --profile deck-studio</code> 或 DSH 桌面端）后再打开这里。</div>`;
+    return;
+  }
+
+  if (IMP.mode === "found") {
+    const rows = IMP.foundFiles.length
+      ? IMP.foundFiles.map((file) => impFileRow(file, file.path.replace(`${IMP.path.replace(/[\\/]+$/, "")}/`, ""))).join("")
+      : `<div class="dir-picker-empty">子目录里也没找到 PDF（只看 3 层）。</div>`;
+    list.innerHTML = `<button type="button" class="dir-picker-row" data-imp-back="1"><span class="dir-picker-name">↩ 回到目录列表</span></button>${rows}${IMP.foundTruncated ? `<div class="dir-picker-empty">只列了前 60 份，缩小范围再找。</div>` : ""}`;
+    return;
+  }
+
+  const dirs = (IMP.dirs || []).filter((item) => !item.hidden);
+  const pdfs = IMP.pdfs || [];
+  const findRow = dirs.length
+    ? `<button type="button" class="dir-picker-row imp-find" data-imp-find="1"><span class="dir-picker-name">🔍 ${pdfs.length ? "这层也有 PDF；在子目录里再找一遍" : "这层没有 PDF —— 在子目录里找（≤3 层）"}</span></button>`
+    : "";
+  const body = [
+    ...pdfs.map((file) => impFileRow(file, file.name)),
+    ...dirs.map((dir) => `<button type="button" class="dir-picker-row" data-imp-dir="${esc(dir.path)}" title="${esc(dir.path)}"><span class="dir-picker-name">📁 ${esc(dir.name)}</span></button>`),
+  ].join("");
+  if (!body) {
+    list.innerHTML = `<div class="dir-picker-empty">这个文件夹里没有子目录，也没有 PDF。点「↑ 上一级」换个位置。</div>`;
+    return;
+  }
+  list.innerHTML = body + findRow;
+}
+
+async function impFetchJson(url) {
+  const res = await fetch(url, { headers: { accept: "application/json" } });
+  let payload = {};
+  try { payload = await res.json(); } catch { /* 非 JSON 兜底 */ }
+  if (!res.ok || !payload?.ok) {
+    const failure = new Error(payload?.error?.message || `HTTP ${res.status}`);
+    failure.code = payload?.error?.code || "";
+    throw failure;
+  }
+  return payload;
+}
+
+async function impLoad(pathValue) {
+  IMP.loading = true;
+  IMP.error = "";
+  IMP.selected = null;
+  IMP.mode = "browse";
+  IMP.stale = false;
+  renderImportPicker();
+  try {
+    const query = pathValue ? `?files=1&path=${encodeURIComponent(pathValue)}` : "?files=1";
+    const payload = await impFetchJson("/api/deck-studio.dir-browse" + query);
+    const dir = payload.dir || {};
+    IMP.path = dir.path || pathValue || "";
+    IMP.dirs = dir.dirs || [];
+    // 旧版后端不会返回 files：明确说「要重启」，别让人以为目录里真没 PDF。
+    IMP.stale = !Array.isArray(dir.files);
+    const files = Array.isArray(dir.files) ? dir.files : [];
+    IMP.pdfs = files.filter((file) => file.kind === "pdf");
+    IMP.mdCount = files.filter((file) => file.kind === "md").length;
+  } catch (error) {
+    IMP.error = importErrText(error?.code, error?.message);
+    IMP.dirs = [];
+    IMP.pdfs = [];
+    IMP.mdCount = 0;
+  } finally {
+    IMP.loading = false;
+    renderImportPicker();
+  }
+}
+
+async function impFindPdfs() {
+  IMP.loading = true;
+  IMP.error = "";
+  renderImportPicker();
+  try {
+    const payload = await impFetchJson(`/api/deck-studio.dir-browse?find=pdf&path=${encodeURIComponent(IMP.path)}`);
+    IMP.foundFiles = payload.found?.files || [];
+    IMP.foundTruncated = Boolean(payload.found?.truncated);
+    IMP.mode = "found";
+  } catch (error) {
+    IMP.error = importErrText(error?.code, error?.message);
+  } finally {
+    IMP.loading = false;
+    renderImportPicker();
+  }
+}
+
+const IMP_LAST_DIR_KEY = "deckImportLastDir";
+
+function openImportPdfModal() {
+  IMP.busy = false;
+  IMP.selected = null;
+  IMP.stale = false;
+  getEl("impState").textContent = "";
+  getEl("impDpi").value = "120";
+  getEl("importPdfModal").hidden = false;
+  let start = "";
+  try { start = localStorage.getItem(IMP_LAST_DIR_KEY) || ""; } catch { start = ""; }
+  if (!start) start = String(STATE.data?.config?.dataRoot || "").trim();
+  impLoad(start);
+}
+
+function closeImportPdfModal() {
+  getEl("importPdfModal").hidden = true;
+}
+
+getEl("importPdfBtn").addEventListener("click", openImportPdfModal);
+getEl("impClose").addEventListener("click", closeImportPdfModal);
+getEl("impCancel").addEventListener("click", closeImportPdfModal);
+getEl("importPdfModal").addEventListener("click", (event) => { if (event.target === getEl("importPdfModal")) closeImportPdfModal(); });
+getEl("impUp").addEventListener("click", () => {
+  if (!IMP.path || IMP.mode === "found") return;
+  const parent = IMP.path.replace(/[\\/]+$/, "").replace(/[\\/][^\\/]+$/, "");
+  impLoad(parent || "/");
+});
+getEl("impList").addEventListener("click", (event) => {
+  if (event.target.closest("[data-imp-back]")) {
+    impLoad(IMP.path);
+    return;
+  }
+  if (event.target.closest("[data-imp-find]")) {
+    impFindPdfs();
+    return;
+  }
+  const dirHit = event.target.closest("[data-imp-dir]");
+  if (dirHit) {
+    impLoad(dirHit.dataset.impDir);
+    return;
+  }
+  const pdfHit = event.target.closest("[data-imp-pdf]");
+  if (pdfHit) {
+    IMP.selected = [...IMP.pdfs, ...IMP.foundFiles].find((file) => file.path === pdfHit.dataset.impPdf) || null;
+    renderImportPicker();
+  }
+});
+getEl("impSubmit").addEventListener("click", async () => {
+  if (!IMP.selected || IMP.busy) return;
+  IMP.busy = true;
+  getEl("impSubmit").disabled = true;
+  getEl("impState").textContent = `正在把 ${IMP.selected.name} 每页转成整页图（页数多会慢一点，别关页面）…`;
+  try {
+    const res = await fetch("/api/deck-studio.deck-import", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ pdf: IMP.selected.path, dpi: Number(getEl("impDpi").value) || 120 }),
+    });
+    const result = await res.json().catch(() => ({}));
+    if (!res.ok || !result.ok) {
+      const failure = new Error(result?.error?.message || `HTTP ${res.status}`);
+      failure.code = result?.error?.code || "";
+      throw failure;
+    }
+    try { localStorage.setItem(IMP_LAST_DIR_KEY, IMP.path); } catch { /* 隐私模式忽略 */ }
+    const parts = [`已导入 ${result.pages} 页（${result.dpi} dpi）`];
+    if (result.markdown?.length) parts.push(`抽到 md：${result.markdown.join("、")}`);
+    if (result.warnings?.length) parts.push(`注意：${result.warnings.join("；")}`);
+    getEl("impState").textContent = parts.join(" · ");
+    closeImportPdfModal();
+    flash(`已导入「${result.deck?.label || ""}」：${result.pages} 页整页图`, "ok");
+    if (result.deck?.deckId) await showDeck(result.deck.deckId);
+  } catch (error) {
+    getEl("impState").textContent = "导入失败：" + importErrText(error?.code, error?.message);
+  } finally {
+    IMP.busy = false;
+    getEl("impSubmit").disabled = !IMP.selected;
+  }
+});
+
 // F-63：标签是动态渲染的，用事件委托
 getEl("observeTabs").addEventListener("click", (event) => {
   const btn = event.target.closest(".observe-tab");