dsh-plugin-deck-studio 0.0.0-stage → 0.2.3

package/lib/config.js

@@ -0,0 +1,216 @@
+/**
+ * 插件配置解析与路径解析。纯函数、无 IO——冒烟测试可直接喂假 env。
+ *
+ * 两个挂载点共用本文件（ADR-0006 D2）：
+ * - profile 根挂载：`tools: false`，只开观测路由 + 客户端面板；
+ * - preset 子树挂载：`tools: true` + `decks[]`（受控源路径等）。
+ *
+ * 源路径纪律（ADR-0006 D5）：客户源目录只从 config / env 来，绝不写死在工具逻辑里。
+ * @module dsh-plugin-deck-studio/config
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_MAX_REVIEWERS, HARD_MAX_REVIEWERS } from "./review-personas.js";
+import { fileURLToPath } from "node:url";
+
+/** 插件包根目录（lib/ 的上一级——本文件住在 lib/ 里）。 */
+export const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * 资产根：开发仓库根 `<repo>/plugin/deck-studio/` 的上一级。
+ *
+ * npm 安装时插件在 `<profile>/node_modules/dsh-plugin-deck-studio`，上两级是 node_modules，
+ * 那里没有 samples / docs；公开包把手册与示例 deck 一起打进包内 `seeds/`（prepack 生成），
+ * 这种情况回退到 `seeds/`，否则「使用手册」和首次启动的示例 deck 在 npm 安装下是空的。
+ */
+export function repoRootFrom(pluginDir = PLUGIN_DIR) {
+  const repo = resolve(pluginDir, "..", "..");
+  const looksLikeRepo = existsSync(join(repo, "samples", "deckline-intro", "script.md")) || existsSync(join(repo, "docs", "manual.md"));
+  if (looksLikeRepo) return repo;
+  const bundled = join(pluginDir, "seeds");
+  if (existsSync(join(bundled, "docs", "manual.md"))) return bundled;
+  return repo;
+}
+
+/**
+ * 默认渲染配置。
+ * 出图节点地址**不设默认值**：provider 中立，节点只来自 profile patch / env / 本机 key 文件，
+ * 仓库里不携带任何厂商或个人中转地址（real 模式缺 endpoint 时 `lib/render.js` 会明确报错）。
+ * API key 永不出现在配置或仓库里，只从 env / key 文件读。
+ */
+export const DEFAULT_RENDER = {
+  mode: "fake",
+  model: "gpt-image-2.5-sunburst",
+  endpoint: "",
+  size: "2560x1440",
+  apiKeyEnv: "DSH_DECK_IMAGE_API_KEY",
+  apiKeyFile: "",
+  // F-110：2560x1440 的整页图在慢网络下会超过 3 分钟（真机 p01 出图在 180s 被 abort）。
+  // 2560x1440 实测 219s 成功、慢的时候 300s 还没回来；给到 7 分钟，超时文案会提示重试。
+  timeoutMs: 420_000,
+  /** 多节点配置（ADR-0010）：nodes 存在时优先；没有时回退到上面的单节点字段。 */
+  nodes: [],
+  /** 缺省选择：nodeId/modelId；留空用 nodes[0].models[0]。 */
+  default: "",
+};
+
+/** 默认视觉 preset（写进每页 prompt 头部；可在 profile 里用 styleBrief 覆盖）。 */
+export const DEFAULT_STYLE_BRIEF =
+  "品牌信息图风格：深青 #06363B 主色、米白纸张底、暖金点缀，纸张纹理背景；" +
+  "信息密度高、克制、知识型；版式干净、层级清楚；不要卡通、不要 3D 渲染、不要照片素材。";
+
+/** 展示名（status / 面板横幅用）。 */
+export const DEFAULT_DISPLAY_NAME = "Deckline";
+
+/**
+ * 展开一个 deck 源条目：config 里的 path 支持 `~`；缺 id 拒绝。
+ * @param {unknown} raw - config.decks[] 的一项。
+ * @param {NodeJS.ProcessEnv} env - 展开 `~` 与 env 覆盖用。
+ */
+function normalizeDeck(raw, env) {
+  if (!raw || typeof raw !== "object") return null;
+  const sourceRoot = typeof raw.sourceRoot === "string" ? expandHome(raw.sourceRoot, env) : "";
+  if (!sourceRoot) return null;
+  const id = typeof raw.id === "string" && raw.id.trim() ? raw.id.trim() : "";
+  if (!id || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(id)) return null;
+  return {
+    id,
+    label: typeof raw.label === "string" && raw.label.trim() ? raw.label.trim() : id,
+    sourceRoot,
+  };
+}
+
+/** 展开 `~/` 前缀；其余原样。 */
+/** 默认数据根：安装用户的可写位置（不落进插件包 / node_modules）。开发仓库可在 profile 里显式配 dataRoot。 */
+export function defaultDataRoot(env = process.env) {
+  return join(expandHome(env.DSH_HOME || "~/.dsh", env), "deckline");
+}
+
+export function expandHome(value, env = process.env) {
+  if (typeof value !== "string") return "";
+  if (value === "~") return env.HOME ?? value;
+  if (value.startsWith("~/")) return join(env.HOME ?? "", value.slice(2));
+  return value;
+}
+
+/**
+ * 合并 loader config ← 默认值 ← env 覆盖。
+ * @param {Record<string, unknown>|undefined} raw - apply(ctx, config) 的 config。
+ * @param {{pluginDir?: string, env?: NodeJS.ProcessEnv}} [options]
+ */
+export function mergeConfig(raw, options = {}) {
+  const env = options.env ?? process.env;
+  const pluginDir = options.pluginDir ?? PLUGIN_DIR;
+  const input = raw && typeof raw === "object" ? raw : {};
+  const positive = (value, fallback) =>
+    Number.isFinite(Number(value)) && Number(value) > 0 ? Number(value) : fallback;
+
+  const renderInput = input.render && typeof input.render === "object" ? input.render : {};
+  const mode = renderInput.mode === "real" || env.DSH_DECK_RENDER_MODE === "real" ? "real" : "fake";
+  const render = {
+    ...DEFAULT_RENDER,
+    ...renderInput,
+    mode,
+    // 配置优先；env 别名与 docs/install.md 一致（DSH_DECK_IMAGE_*），保留 GPT_IMAGE_* 兼容旧用法。
+    model:
+      renderInput.model || env.DSH_DECK_IMAGE_MODEL || env.GPT_IMAGE_MODEL || DEFAULT_RENDER.model,
+    size: renderInput.size || env.DSH_DECK_IMAGE_SIZE || env.GPT_IMAGE_SIZE || DEFAULT_RENDER.size,
+    endpoint: renderInput.endpoint || env.DSH_DECK_IMAGE_ENDPOINT || DEFAULT_RENDER.endpoint,
+    apiKeyFile: expandHome(
+      renderInput.apiKeyFile || env.DSH_DECK_IMAGE_API_KEY_FILE || DEFAULT_RENDER.apiKeyFile,
+      env,
+    ),
+    timeoutMs: positive(renderInput.timeoutMs, DEFAULT_RENDER.timeoutMs),
+  };
+
+  const decksRaw = Array.isArray(input.decks) ? input.decks : [];
+  const decks = decksRaw.map((deck) => normalizeDeck(deck, env)).filter(Boolean);
+
+  const singleSource = expandHome(
+    typeof input.sourceRoot === "string" ? input.sourceRoot : (env.DSH_DECK_SOURCE_ROOT ?? ""),
+    env,
+  );
+  if (singleSource && !decks.some((deck) => deck.sourceRoot === singleSource)) {
+    decks.unshift({
+      id: typeof input.sourceDeckId === "string" && input.sourceDeckId.trim() ? input.sourceDeckId.trim() : "sample-deck",
+      label: typeof input.sourceDeckLabel === "string" && input.sourceDeckLabel.trim() ? input.sourceDeckLabel.trim() : "示例受控源",
+      sourceRoot: singleSource,
+    });
+  }
+
+  return {
+    /** 只在 preset 子树挂载点为 true；根挂载只开路由与面板。 */
+    tools: input.tools === true,
+    /** preset 子树挂载点设 false（根挂载已注册同路径路由，避免双重注册）。 */
+    routes: input.routes !== false,
+    dataRoot:
+      expandHome(
+        typeof input.dataRoot === "string" && input.dataRoot
+          ? input.dataRoot
+          : (env.DSH_DECK_DATA_ROOT ?? ""),
+        env,
+      ) || defaultDataRoot(env),
+    /**
+     * 新建 deck 项目的落盘根（2026-10-21 负责人：以后写的 deck 都放
+     * `00_company/sharing/`）。留空 = 旧的内部 `.deck/projects/<id>/source`。
+     * 配置了这个根时，新项目直接建在 `<projectsRoot>/<目录名>/`
+     * （script.md / intent.md / style-reference.md / prompts/ 同层，和已有 deck 源结构一致）。
+     */
+    projectsRoot: expandHome(
+      typeof input.projectsRoot === "string" && input.projectsRoot.trim()
+        ? input.projectsRoot.trim()
+        : (env.DSH_DECK_PROJECTS_ROOT ?? ""),
+      env,
+    ),
+    decks,
+    render,
+    styleBrief:
+      typeof input.styleBrief === "string" && input.styleBrief.trim()
+        ? input.styleBrief.trim()
+        : DEFAULT_STYLE_BRIEF,
+    displayName:
+      typeof input.displayName === "string" && input.displayName.trim()
+        ? input.displayName.trim()
+        : DEFAULT_DISPLAY_NAME,
+    /**
+     * 是否把 DSH 外壳左侧栏默认收起隐藏（F-69）。
+     * 默认 false：只有专门的产品 profile（如 deck-studio）显式打开才生效，
+     * 开发/其他 profile 的 DSH 界面不受影响。
+     */
+    hideShellSidebar: input.hideShellSidebar === true,
+    /**
+     * 新建 Deck 弹窗默认预选的登记风格（F-112）：填 design 缩写（如 GRD）。
+     * 留空 = 不预选。只在 UI 预选，不改变任何已有 deck 的关联风格。
+     */
+    defaultStyleAbbr:
+      typeof input.defaultStyleAbbr === "string" && input.defaultStyleAbbr.trim()
+        ? input.defaultStyleAbbr.trim().toUpperCase()
+        : "",
+    /**
+     * 首次启动自举（F-157）：新装 profile 自动登记示例 deck、拷一份资源库、导入预设风格。
+     * 默认 false（通用插件不强加内容）；产品 bundle patch 里打开，关掉填 false。
+     */
+    bootstrap: input.bootstrap === true,
+    /**
+     * 听众评审（F-159）：审稿人由 intent 的「听众」动态生成，不是写死的固定 role。
+     * presetId 指向只读评审 preset（cordis.patch.yml 的 preset-deck-critic）；
+     * maxReviewers 是成本上限（每个审稿人 = 一次子 agent 调用），默认 3。
+     */
+    review: {
+      presetId:
+        typeof input.review?.presetId === "string" && input.review.presetId.trim()
+          ? input.review.presetId.trim()
+          : "deck-critic",
+      maxReviewers: Math.min(
+        HARD_MAX_REVIEWERS,
+        positive(input.review?.maxReviewers, DEFAULT_MAX_REVIEWERS),
+      ),
+    },
+    /** 首页问候语里的用户名（默认空 = 只显示「欢迎你」；可在 profile 配置里改）。 */
+    userName:
+      typeof input.userName === "string" && input.userName.trim()
+        ? input.userName.trim()
+        : "",
+  };
+}

package/lib/content-density.js

@@ -0,0 +1,98 @@
+/**
+ * deck 内容密度（F-124）：一页写多少字、画面要求写多细。
+ *
+ * 背景：同一份 deck，有人要「一页 300 字、图里信息密集」的自阅稿，有人要「一页 80 字、
+ * 一页一件事」的演讲稿。密度是 deck 级设置（manifest.contentDensity），落在：
+ * - 新建 Deck 弹窗 / deck 工具栏「密度」下拉（用户改）；
+ * - deck_source_overview、deck_script_read（Agent 每次写 script 前读到目标字数）；
+ * - persona 第 23 条（按设置写，auto 时自己判断并说明理由）。
+ *
+ * 数字口径（负责人 2026-10-23 定）：
+ * - 信息密集 dense：正文 200–500 字/页，画面要求 800–900 字
+ * - 适中 medium：正文 100–200 字/页，画面要求 400–600 字
+ * - 简洁 concise：正文 50–100 字/页，画面要求 200–300 字
+ * - 自动 auto：**不设固定字数**——由 Agent 按这一页／这份 deck 的内容自己判断每一页该多长
+ *   （该密则密、该简则简），但要说明判断理由；不是「套一个 100–200 的区间」
+ *
+ * 注意：正文长 ≠ 画面字多。画面里的字仍由风格与视觉规则约束（信息密集也不许堆小字）。
+ */
+
+export const CONTENT_DENSITY_KEYS = ["auto", "concise", "medium", "dense"];
+
+export const CONTENT_DENSITIES = {
+  auto: {
+    key: "auto",
+    label: "自动",
+    hint: "不设固定字数：由 Agent 按每页内容自己判断该多长，并说明理由",
+    bodyMin: null,
+    bodyMax: null,
+    briefMin: null,
+    briefMax: null,
+  },
+  concise: {
+    key: "concise",
+    label: "简洁",
+    hint: "一页一件事，标题即结论，正文只留支撑句",
+    bodyMin: 50,
+    bodyMax: 100,
+    briefMin: 200,
+    briefMax: 300,
+  },
+  medium: {
+    key: "medium",
+    label: "适中",
+    hint: "结论 + 2–3 句支撑 + 一句收口",
+    bodyMin: 100,
+    bodyMax: 200,
+    briefMin: 400,
+    briefMax: 600,
+  },
+  dense: {
+    key: "dense",
+    label: "信息密集",
+    hint: "自阅型：一页给足论据 / 数据 / 步骤，读者不用问讲者",
+    bodyMin: 200,
+    bodyMax: 500,
+    briefMin: 800,
+    briefMax: 900,
+  },
+};
+
+/** 归一化：未知值一律当 auto（老 deck 没有这个字段）。 */
+export function normalizeContentDensity(value) {
+  const key = String(value ?? "").trim().toLowerCase();
+  return CONTENT_DENSITY_KEYS.includes(key) ? key : "auto";
+}
+
+export function densitySpec(value) {
+  return CONTENT_DENSITIES[normalizeContentDensity(value)];
+}
+
+/** UI 下拉用的选项（含目标字数，便于用户看懂差别；auto 不写死区间）。 */
+export function contentDensityOptions() {
+  return CONTENT_DENSITY_KEYS.map((key) => {
+    const spec = CONTENT_DENSITIES[key];
+    const fixed = spec.bodyMin != null;
+    return {
+      key,
+      label: spec.label,
+      body: fixed ? `${spec.bodyMin}–${spec.bodyMax} 字/页` : "每页由 Agent 判断（不固定）",
+      brief: fixed ? `${spec.briefMin}–${spec.briefMax} 字` : "每页由 Agent 判断（不固定）",
+      // 数值口径也带上：工作台要按它逐页标「字数是否达标」，不能只靠字符串解析
+      bodyMin: spec.bodyMin,
+      bodyMax: spec.bodyMax,
+      briefMin: spec.briefMin,
+      briefMax: spec.briefMax,
+      hint: spec.hint,
+    };
+  });
+}
+
+/** 给 Agent 看的一行（工具结果 / 脚本页都用它，保证口径一致）。 */
+export function densityLine(value) {
+  const spec = densitySpec(value);
+  if (spec.key === "auto") {
+    return "内容密度：自动（不设固定字数——按这一页的内容自己判断该多长、画面要求该多细，该密则密、该简则简；判断完告诉用户理由，不要套固定区间）";
+  }
+  return `内容密度：${spec.label}（正文 ${spec.bodyMin}–${spec.bodyMax} 字/页、画面要求 ${spec.briefMin}–${spec.briefMax} 字；${spec.hint}）`;
+}

package/lib/deck-brief.js

@@ -0,0 +1,87 @@
+/**
+ * 读 deck 的「写作上下文」：script.md 头部（title / owner / created）+ intent.md 的结构化字段
+ * （听众 / 带走 / 成功标准 / 不讲的）。给两处用（F-158）：
+ * - deck_script_read / 提案结果：让 Agent 写正文前看到「讲给谁、为什么讲」；
+ * - buildPrompt：出图 prompt 带上受众与目的，封面页带作者 / 日期。
+ *
+ * 只读源文件，纯解析；找不到文件时返回空字段，不抛错。
+ * @module dsh-plugin-deck-studio/deck-brief
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const clean = (value) => String(value ?? "").replace(/^（待补[^）]*）$/, "").trim();
+
+/** 读 `---` front matter（只取顶层 `key: value`）。 */
+export function readFrontMatter(text) {
+  const out = {};
+  const lines = String(text ?? "").split("\n");
+  if (lines[0]?.trim() !== "---") return out;
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() === "---") break;
+    const match = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+    if (match) out[match[1]] = match[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+/** 从 intent.md 的 `- **字段**：值` 行取值。 */
+export function readIntentFields(text) {
+  const out = {};
+  for (const line of String(text ?? "").split("\n")) {
+    const match = line.match(/^\s*[-*]\s*\*\*([^*]+)\*\*\s*[：:]\s*(.*)$/);
+    if (match) out[match[1].trim()] = clean(match[2]);
+  }
+  return out;
+}
+
+/**
+ * @param {string} sourceRoot deck 源根
+ * @returns {{title:string, owner:string, created:string, audience:string, topic:string, takeaway:string, success:string, scopeOut:string, rules:string}}
+ */
+export function readDeckBrief(sourceRoot) {
+  const empty = { title: "", owner: "", created: "", audience: "", topic: "", takeaway: "", success: "", scopeOut: "", rules: "" };
+  const root = String(sourceRoot ?? "").trim();
+  if (!root) return empty;
+  let scriptHead = {};
+  try {
+    if (existsSync(join(root, "script.md"))) scriptHead = readFrontMatter(readFileSync(join(root, "script.md"), "utf8"));
+  } catch {
+    scriptHead = {};
+  }
+  let intent = {};
+  try {
+    if (existsSync(join(root, "intent.md"))) intent = readIntentFields(readFileSync(join(root, "intent.md"), "utf8"));
+  } catch {
+    intent = {};
+  }
+  return {
+    title: clean(scriptHead.title || intent["主题"]),
+    owner: clean(scriptHead.owner),
+    created: clean(scriptHead.created),
+    audience: clean(intent["听众"]),
+    topic: clean(intent["主题"]),
+    takeaway: clean(intent["带走"]),
+    success: clean(intent["成功标准"]),
+    scopeOut: clean(intent["不讲的"]),
+    rules: "",
+  };
+}
+
+/** 出图 prompt 用的上下文行：受众 / 目的（一句话）。没有就返回空数组。 */
+export function briefPromptLines(brief = {}) {
+  const lines = [];
+  if (brief.audience) lines.push(`受众：${brief.audience}（术语密度、例子、取舍按这个受众来）`);
+  if (brief.takeaway || brief.success) lines.push(`这页服务的目的：${brief.takeaway || brief.success}`);
+  return lines;
+}
+
+/** 封面页用的作者 / 日期行。日期只取 YYYY-MM-DD。 */
+export function coverPromptLines(brief = {}) {
+  const lines = [];
+  if (brief.owner) lines.push(`作者：${brief.owner}`);
+  const date = String(brief.created ?? "").match(/^\d{4}-\d{2}-\d{2}/)?.[0];
+  if (date) lines.push(`日期：${date}`);
+  return lines;
+}