dsh-plugin-deck-studio 0.2.24 → 0.2.27

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 / 提案时按新目标字数写。
@@ -2268,7 +2458,12 @@ export function createService(config, logger, env = process.env) {
       appendixCount: adapterOf(deck.deckId)?.available() ? adapterOf(deck.deckId).overview().appendixCount ?? 0 : workspace.manifest(deck.deckId)?.appendix?.count ?? 0,
       appendixRows: workspace.manifest(deck.deckId)?.appendix?.rows ?? [],
     }));
-    const activeId = (requestedDeckId && decks.some((deck) => deck.deckId === requestedDeckId) ? requestedDeckId : null) ?? decks[0]?.deckId ?? workspace.listDeckIds()[0] ?? null;
+    // F-205：显式点名要打开某本 deck、但这次快照里还没有它（刚导入 / 刚创建，列表还没跟上）时，
+    // 不要静默退回第一本——前端拿到 requestedMissing 会立刻重试，避免「导入成功却打开别的 deck」。
+    const requestedMissing = Boolean(requestedDeckId) && !decks.some((deck) => deck.deckId === requestedDeckId);
+    const activeId = requestedMissing
+      ? decks[0]?.deckId ?? workspace.listDeckIds()[0] ?? null
+      : requestedDeckId ?? decks[0]?.deckId ?? workspace.listDeckIds()[0] ?? null;
     // P0：进 deck 时先体检（规格 §2「进入某本 deck 时，每次，读 manifest 之前」）。
     // mismatch / partial 时不 ensureDeck：那会凭空建出空的 decks/<id>/，旧图也找不回（禁止项）。
     const dataDirInfo = dataDirStateOf({ config, store, workspace, adapters, env }, activeId);
@@ -2385,6 +2580,9 @@ export function createService(config, logger, env = process.env) {
       renderSettings: renderSettings(),
       decks,
       active,
+      // F-205：这次请求点名的 deck 是否存在（true = 列表还没跟上，前端重试即可）。
+      requestedDeckId: requestedDeckId ?? null,
+      requestedMissing,
       designProjects: designProjects(),
       bindings: listBindings(),
       proposals: base.pendingProposals,
@@ -2399,7 +2597,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 }
 }
 
 /* ─────────────────────────────────────────────────────────────────────────
@@ -2487,6 +2685,25 @@ function noteDataDirTransitions(serviceLike, report, trigger = "poll") {
 /**
  * 数据目录载荷：黄条 / 设置页 / 自检共用（不重算解析，只合并最新体检）。
  */
+/**
+ * 「指针覆盖了 profile 配置」的事实（没有冲突返回 null）。
+ * 这是本次事故的根因：web profile 没配 dataRoot、desktop 配了仓库 .deck，而指针全机共享——
+ * 谁写的指针谁说了算，界面上却只显示「当前 = 指针」，看不出 profile 里还写着另一个目录。
+ */
+function pointerConflictOf(resolved = {}) {
+  const profileDataRoot = String(resolved.profileDataRoot ?? "").trim();
+  const fact = resolved.dataRoot ?? {};
+  if (!profileDataRoot || fact.source !== "pointer") return null;
+  if (String(fact.value ?? "") === profileDataRoot) return null;
+  return {
+    profileDataRoot,
+    pointerDataRoot: String(fact.value ?? ""),
+    pointerFile: String(resolved.pointerFile?.path ?? ""),
+    setBy: String(resolved.pointerFile?.setBy ?? ""),
+    updatedAt: String(resolved.pointerFile?.updatedAt ?? ""),
+  };
+}
+
 function dataDirStateOf(serviceLike, deckId = null, { refresh = false, countImages = false } = {}) {
   const { config } = serviceLike;
   const resolved = config.dataDir ?? {};
@@ -2503,6 +2720,8 @@ function dataDirStateOf(serviceLike, deckId = null, { refresh = false, countImag
     firstRun: resolved.firstRun === true,
     processCwd: resolved.processCwd ?? process.cwd(),
     sourceLabel: resolved.sourceLabel ?? "",
+    // 指针赢过 profile 时的「为什么」：profile 配的是哪个目录、指针文件在哪。前端只在有冲突时多画一行。
+    pointerConflict: pointerConflictOf(resolved),
     banner: dataDirBannerFacts({ report, deckId, envOverride: resolved.envOverride?.active === true, dataRoot: config.dataRoot }),
     decks: report.decks,
     candidates: report.candidates,
@@ -2846,7 +3065,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 +3096,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 +3113,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 +3139,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,16 +3147,81 @@ 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。
   // 只列子目录名 + deckCount，不读内容、不返回大小 / 权限 / 环境变量；切换窗口内复用切换闸 409。
   registerRoute(ROUTES.dirBrowse, (request) => {
     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 +3295,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/data-dir.js

@@ -232,6 +232,8 @@ function decksDirEmpty(dataRoot) {
 /** 冲突 warn 只打一次：5s 轮询与多次重建服务都不重复刷屏。 */
 let warnedDataRootConflict = false;
 let warnedProjectsRootConflict = false;
+/** 指针 vs profile 的冲突按「指针→profile」这一对去重：同一处冲突不刷屏，换了目录再提醒一次。 */
+const warnedPointerProfilePairs = new Set();
 
 export function resolveDataDir({ env = process.env, profileDataRoot = "", profileProjectsRoot = "", logger = null } = {}) {
   const envDataRoot = normalizeDirPath(env[DATA_DIR_ENV] ?? "", env);
@@ -253,6 +255,13 @@ export function resolveDataDir({ env = process.env, profileDataRoot = "", profil
   const pointerDataRoot = pointer.error || !isAbsolute(pointer.dataRoot) ? "" : pointer.dataRoot;
   const pointerProjectsRoot = pointer.error || !isAbsolute(pointer.projectsRoot) ? "" : pointer.projectsRoot;
 
+  // 指针（用户点「切到这个目录」写下的）优先级高于 profile；两者不一致时以前是**完全静默**的，
+  // 表现成「我这本 deck 怎么没了」。留一条 warn，日志里能找到是谁把目录换掉的。
+  const pointerProfileKey = pointerDataRoot && profileRoot && pointerDataRoot !== profileRoot ? `${pointerDataRoot}→${profileRoot}` : "";
+  if (warn && pointerProfileKey && !warnedPointerProfilePairs.has(pointerProfileKey)) {
+    warnedPointerProfilePairs.add(pointerProfileKey);
+    warn(`dataRoot: 指针文件（${pointerDataRoot}）与 profile 配置（${profileRoot}）不一致，已按指针生效；要让 profile 配置生效就删掉指针文件 ${pointer.path}`);
+  }
   const dataRoot = envDataRoot || pointerDataRoot || profileRoot || normalizeDirPath(defaultDataRoot(env), env);
   const source = envDataRoot ? "env" : pointerDataRoot ? "pointer" : profileRoot ? "profile" : "default";
   const projectsSource = envProjectsRoot ? "env" : pointerProjectsRoot ? "pointer" : profileProjects ? "profile" : "default";

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.27",
   "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/seeds/docs/install.md

@@ -188,6 +188,13 @@ Deckline 的数据分两处：**你的 deck 源**（`projectsRoot`，纯 md +
   `dataRoot` / `DSH_DECK_DATA_ROOT`，两边就各看各的。所以「换到另一个端口，内容变空 / 标题在但页面空白」先别怀疑端口：
   去那个实例的 ⚙ 看「当前数据目录」，再和这边显示的路径比一比。
   **换端口不改数据，换 dataRoot 才改数据。**
+- **指针的优先级高于 profile**（「打开一片空白 + 黄条」最常见的真凶）：`$DSH_HOME/deckline/location.json`
+  是全机共享的「用户选择」，解析顺序是 `env > 指针 > profile patch > 默认`。在一个实例里点过
+  「切到这个目录」，同一个 `$DSH_HOME` 下的其它 profile 也会跟着换目录——**哪怕它在 patch 里写了 `dataRoot`**。
+  想让各端稳定一致，二选一：① 每个 profile 的 patch 写**同一个** `dataRoot`，并删掉
+  `~/.dsh/deckline/location.json`；② 只用默认目录，不要在界面里切。真有冲突时黄条会多写一行
+  「你的 profile 里配的是 A，但指针文件把它改成了 B——指针优先；切换只改指针，不动文件」，
+  日志里也有一条 `dataRoot: 指针文件（B）与 profile 配置（A）不一致` 的 warn（每次冲突只打一次）。
 - 报问题不用自己拼路径：⚙ →「当前数据目录与自检」底部 **「复制诊断信息」** 一键复制（内容由插件生成、已脱敏，
   不含 key），贴出来就包含 cwd / dataRoot（含来源）/ projectsRoot / 每本 deck 有没有 `script/current.md`。
 - 开发环境用独立 `dataRoot`，不要把运行数据写进仓库（见 §7「开发数据目录」）。

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}
@@ -782,9 +830,15 @@ function mdToHtml(markdown, options = {}) {
 }
 
 /* ---------------- 数据加载 ---------------- */
+/* F-205：并发保护。导入 / 切 deck 会连着打好几次 workbench 接口，先发的旧请求如果后回来，
+ * 会把刚切到的新 deck 覆盖成旧数据（表现：导入成功却停在上一个 / 第一个 deck）。
+ * 只让**最后发起**的那次结果落地。 */
+let LOAD_SEQ = 0;
 async function loadWorkbench(deckId = null) {
+  const seq = ++LOAD_SEQ;
   try {
     const next = await route("workbench", deckId ? { deckId } : undefined);
+    if (seq !== LOAD_SEQ) return;
     const active = next.active || {};
     const signature = JSON.stringify([
       active.deckId,
@@ -817,6 +871,7 @@ async function loadWorkbench(deckId = null) {
       }
     }
   } catch (error) {
+    if (seq !== LOAD_SEQ) return;
     STATE.demo = true;
     STATE.data = demoData();
     renderChrome();
@@ -1196,15 +1251,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 +1355,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;
@@ -1460,11 +1528,16 @@ function renderDataDirBanner(data) {
       : "⚠ 这本 deck 的正文和图片不在当前数据目录";
   const currentRoot = dd?.dataRoot?.value || banner.dataRoot || "—";
   const sourceNote = dd?.sourceLabel ? `（${esc(dd.sourceLabel)}）` : "";
+  // 指针赢过 profile 时把「为什么」写出来：否则只看到「当前 = 指针」，不知道 profile 里还写着另一个目录。
+  const conflict = dd?.pointerConflict && dd.pointerConflict.profileDataRoot !== dd?.dataRoot?.value ? dd.pointerConflict : null;
+  const conflictLine = conflict
+    ? `<span class="data-dir-line data-dir-conflict">你的 profile 里配的是 <code>${esc(conflict.profileDataRoot)}</code>，但指针文件把它改成了上面这个目录${conflict.setBy ? `（${esc(conflict.setBy)}）` : ""}——<b>指针优先</b>。点「切到这个目录」只改指针，不会删改任何 deck 文件。</span>`
+    : "";
   const candidates = banner.candidates || [];
   const rows = candidates.length
     ? candidates.map((candidate) => `<div class="data-dir-candidate"><span class="data-dir-path">已发现：${esc(candidate.dataRoot)}</span><span class="data-dir-count">（${Number(candidate.deckCount) || 0} 本 deck · ${Number(candidate.imageCount) || 0} 张图）</span><button class="btn ghost" data-data-root="${esc(candidate.dataRoot)}"${envOverride ? " disabled" : ""}>切到这个目录</button></div>`).join("")
     : `<div class="data-dir-candidate data-dir-empty"><span>没找到这本 deck 的历史数据。如果你在另一个 DSH 实例里出过图，请在那个实例的『设置』里看它显示的数据目录，然后把它填到下面。</span><input id="dataDirManualInput" placeholder="/绝对路径"${envOverride ? " disabled" : ""}><button class="btn ghost" id="dataDirManualSwitch"${envOverride ? " disabled" : ""}>用这个目录</button></div>`;
-  box.innerHTML = `<div class="data-dir-banner-body"><div class="data-dir-banner-main"><b>${title}</b><span class="data-dir-line" title="换端口不改数据，换 dataRoot 才改数据。">当前：<code>${esc(currentRoot)}</code>${sourceNote}</span>${rows}</div><div class="data-dir-banner-actions"><button class="btn ghost" id="dataDirOpenSettings">打开设置</button><button class="btn ghost" id="dataDirCopyDiag">复制诊断信息</button>${envOverride ? `<span class="data-dir-readonly">由环境变量 ${esc(dd?.envOverride?.name || "DSH_DECK_DATA_ROOT")} 指定（只读）</span>` : ""}</div></div>`;
+  box.innerHTML = `<div class="data-dir-banner-body"><div class="data-dir-banner-main"><b>${title}</b><span class="data-dir-line" title="换端口不改数据，换 dataRoot 才改数据。">当前：<code>${esc(currentRoot)}</code>${sourceNote}</span>${conflictLine}${rows}</div><div class="data-dir-banner-actions"><button class="btn ghost" id="dataDirOpenSettings">打开设置</button><button class="btn ghost" id="dataDirCopyDiag">复制诊断信息</button>${envOverride ? `<span class="data-dir-readonly">由环境变量 ${esc(dd?.envOverride?.name || "DSH_DECK_DATA_ROOT")} 指定（只读）</span>` : ""}</div></div>`;
   box.hidden = false;
   box.querySelectorAll("[data-data-root]").forEach((node) => node.addEventListener("click", () => switchDataDirTo(node.dataset.dataRoot)));
   box.querySelector("#dataDirOpenSettings")?.addEventListener("click", () => openSettingsPanel());
@@ -4858,6 +4931,266 @@ 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();
+  }
+});
+/**
+ * F-205：导入成功后必须停在**刚导入的这本** deck。
+ *
+ * 导入要跑 pdftoppm（几秒到几十秒），期间 5s 轮询、宿主指令、刚创建 deck 的列表延迟都可能
+ * 把视图切到别的 deck（典型：工作台列表还没收录新 deck 时接口退回第一本）。
+ * 这里在成功后的 ~3 秒里以新 deck 为准核对几次；用户自己点了/按了键就立刻停手，不抢手动导航。
+ */
+async function openImportedDeck(deckId) {
+  let userTookOver = false;
+  const flag = () => { userTookOver = true; };
+  window.addEventListener("pointerdown", flag, true);
+  window.addEventListener("keydown", flag, true);
+  try {
+    await showDeck(deckId);
+    for (const gap of [500, 900, 1500]) {
+      await new Promise((resolve) => setTimeout(resolve, gap));
+      if (userTookOver) return;
+      if (STATE.view === "deck" && STATE.deckId === deckId) continue;
+      await showDeck(deckId);
+    }
+  } finally {
+    window.removeEventListener("pointerdown", flag, true);
+    window.removeEventListener("keydown", flag, true);
+  }
+}
+
+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");
+    // F-205：导入成功后以新 deck 为准（详见 openImportedDeck）。
+    if (result.deck?.deckId) await openImportedDeck(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");
@@ -6028,7 +6361,11 @@ function backToManual(box) {
     STATE.homeSection = match ? match[1] : "decks";
     showHome();
   }
-  setInterval(() => loadWorkbench(STATE.deckId), 5000);
+  // F-205：导入（pdftoppm 可能要几十秒）期间别用旧 deckId 轮询，否则回来晚的那次会把新 deck 顶掉。
+  setInterval(() => {
+    if (IMP.busy) return;
+    loadWorkbench(STATE.deckId);
+  }, 5000);
 
   /**
    * 0.2.21：boot 完成 → 把启动期间暂存的「打开某本 deck」执行掉，再向宿主报 ready。