dsh-plugin-deck-studio 0.2.2 → 0.2.4

package/seeds/docs/productization.md

@@ -0,0 +1,193 @@
+# 产品化计划（Deckline · DSH image deck 插件）
+
+简体中文 · [English](productization.en.md)
+
+> 目标：把现在这个「在 Yuna 机器上跑通的 DSH 插件」变成**任何人在自己机器上 5 分钟内装好、
+> 配好自己的 deck 和生图 key、开始用**的产品。
+>
+> 本文是完整计划 + 现状盘点 + 分阶段验收。执行登记见 `docs/feedback.md` F-54…F-57、`tasks.md` P27。
+
+## 1. 产品形态与定位
+
+- **形态**：DSH（DeepSeek Harness）的 **bundle 插件** + 一个专用 profile（`deckline`）。
+  不是独立 App；DSH 负责 chat / 模型 / 权限，Deckline 负责「整页图片 deck」的工作台。
+- **一句话**：把「讲给谁、讲什么、怎么出图」变成一条可追踪的产线——
+  Chat 里讨论 → script / intent / 治理文档 → 逐页 image prompt → 单页出图 + 版本 → 导出 / 交接。
+- **不做什么**：不做 HTML deck 渲染器（另立项目）；不默认批量出整套图；不改用户 deck 源目录。
+- **目标用户**：咨询 / 培训 / 内部汇报 / 内容创作者，已经有 DSH 或愿意装 DSH 的人。
+
+## 2. 现状盘点（已具备 / 缺口）
+
+| 能力 | 现状 | 产品化缺口 |
+|---|---|---|
+| DSH 插件形态 | ✅ bundle + preset + 客户端面板 | 包元数据已整理（MIT / 直发名 / 无个人路径，见 §10） |
+| 安装 | ✅ npm 直发包名 / git 子目录 / 本地 clone 三种方式（`docs/install.md`） | npm 尚未发布（负责人执行） |
+| 配置 | ✅ profile patch + `cordis.example.yml` + env 口径（个人路径已全部下沉到本机 patch） | 团队共享配置模板（Phase 3） |
+| 生图 key | ✅ `apiKeyEnv` / `apiKeyFile`，界面只显示是否配置 | 缺文档 + 设置面板更明确的引导 |
+| 风格 | ✅ 添加风格（贴图/上传/拖拽/粘贴）+ 8 个预设 | 预设需要随插件分发 + 一键导入（已做） |
+| 数据 | ✅ `.deck/` 全部 gitignore，源 deck 只读 | 缺「数据在哪 / 怎么备份 / 怎么迁移」说明 |
+| 验证 | ✅ smoke 46 项 + harness 门禁 + Agent 评估 16 场景 + 真机 Playwright 验证 | CI / 公开 fixture（Phase 1） |
+| 文档 | ✅ README（中/英）+ 安装 / 风格目录 / 示例 deck 文档（中/英）+ 兼容矩阵 | productization 英译、贡献指南、截图（Phase 2） |
+
+## 3. 分阶段计划（建议按此节奏）
+
+### Phase 0 · 可安装（v0.1，1–2 天）
+
+- [x] 插件包元数据：加 `repository` / `homepage` / `keywords` / `peerDependencies`（`private: true` + `UNLICENSED` 暂留防误发，license 拍板后改）；
+- [x] 默认配置模板：`plugin/deck-studio/cordis.example.yml`（decks / projectsRoot / render 节点）；
+- [x] 安装文档 `docs/install.md`（npm / git / 本地 三种方式 + key 配置 + 排障）；
+- [x] README 对外化（产品介绍 / 5 分钟安装 / 配置 / 加 design / 风格）；
+- [x] 预设风格随插件分发：`seeds/styles/*.json` + `seeds/samples/*.jpg` + 「＋ 导入预设风格」；
+- [x] 添加 design 支持贴图 / 拖拽 / 选文件；已有风格可继续加样张；
+- [x] 生图 key：工作台设置面板显示节点 + 「key 是否配置」+ 缺 key 提示；
+- [x] 把当前机器上的个人配置从**插件默认 patch** 挪到 profile patch（保证默认包可分发）——已迁移并用 `--dump-config` 验证。
+
+**验收**：一台干净机器（macOS/Linux，Node `^22.19` 或 `≥24` + pnpm + DSH）按 README 走完能：启动 → 建 deck →
+建风格（贴图）→ 设置里看到 key 状态 →（fake 模式）走完一次出图。
+
+### Phase 1 · 可分发（v0.1.0，已就绪，待负责人执行发布）
+
+- [x] **许可证：MIT**（负责人 2026-10-21 拍板）——`LICENSE` 已落仓库，包元数据同步；
+- [x] **包名直发**：`dsh-plugin-deck-studio`，无 org / scope；`private: false`；
+- [x] **公开范围**（负责人拍板）：插件 + 对外 docs + 预设 design（seeds）+ 1 个 sample deck + 1 个 sample logo；
+  → 用 `scripts/build-public-bundle.mjs` 生成**白名单干净目录**（不含内部台账 / 客户名 / 个人路径 / git 历史）；
+- [x] sample logo：`assets/logo/deckline-logo.svg|png` + mark；README 顶部已引用；
+- [x] sample deck：`samples/deckline-intro/`（Deckline 产品说明手册 10 页源 + 可粘贴跑通流程文案 `docs/sample-deck.md`）；
+- [x] 隐私扫描：插件代码已脱敏（客户名 / 个人路径 / key 名全部换掉），打包脚本内置禁用词扫描；
+- [x] `CHANGELOG.md` + v0.1.0；
+- [ ] **仓库公开**：`gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`
+  （需负责人确认后执行；不要推当前开发仓库——它的 git 历史含内部过程文档与客户信息）；
+- [ ] `npm publish dsh-plugin-deck-studio`（需 npm 账号 + 2FA）；
+- [ ] README 顶部补 3 张真机截图/GIF（公开前）；
+- [ ] GitHub Actions：
+  - `ci.yml`：`node --check` + smoke（`plugin/deck-studio/verify/smoke.mjs`）+ 提交信息规范；
+  - `release.yml`：tag 时 `npm publish`（用 `NPM_TOKEN` secret）；
+- [x] 版本兼容：`peerDependencies` / `engines.dsh` 声明 `0.1.7–0.2.x`；`docs/compat.md` 记录 0.1.7-rc.2 / 0.2.1-rc.2 两批回归。
+
+### Phase 2 · 好上手（v0.3，1 周）
+
+- [ ] 首次启动向导：无 deck 时引导「新建 deck / 导入预设风格 / 配 key」三步；
+- [ ] 「新建 Deck」表单支持从预设风格里选（现在只能手填风格）；
+- [ ] 风格库页面：预览 / 搜索 / 标签（商务、fancy、日系…），一键套用到新 deck；
+- [ ] 数据管理：`.deck` 位置可视化、备份/导出按钮（zip）；
+- [ ] i18n：中文 + English（DSH 本身支持多语言）——公开文档已中英双语，UI 文案待做；
+- [ ] 错误上报：出图失败给出可操作原因（key / 配额 / 模型名 / 尺寸）。
+
+### Phase 3 · 可协作（v0.4+）
+
+- [ ] 多用户 / 团队共享 profile 配置模板（不共享 key）；
+- [ ] 风格包 marketplace（社区贡献 `seeds/styles`，PR 校验 schema + 样张）；
+- [ ] 出图成本估算 / 用量统计（按节点）；
+- [ ] Deck 源适配更多目录约定（现在扫描 `outputs/full/final`、`outputs/final`、`pages`、`images`、`exports`）。
+
+### Phase 4 · 可选（视需求）
+
+- 桌面版（DSH desktop 已有）、Docker 镜像、SaaS 托管；
+- 与对象存储 / 图床集成（出图直接进 CDN）；
+- HTML deck 渲染器（独立项目，不在本仓库）。
+
+## 4. Git 如何公开（具体步骤）
+
+> 负责人已拍板：**公开范围 = 插件 + 对外 docs + 预设 design + 1 个 sample deck + 1 个 sample logo**。
+> 当前开发仓库的 git 历史含内部台账（feedback / tasks / 客户名 / 个人路径），**不能直接 push**。
+> 用白名单脚本生成干净目录，再创建一个新的公开仓库。
+
+```sh
+# 1) 生成干净目录（白名单 + 隐私扫描；产物在 dist/public，已 gitignore）
+node scripts/build-public-bundle.mjs
+#    ✔ 白名单 + 隐私扫描通过（以脚本输出为准），无 /Users/ 个人路径、无客户名、无 key
+
+# 2) 建公开仓库（负责人确认后执行；账号 yuna78）
+gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push
+
+# 3) 补仓库元信息：About = "DSH image deck workbench plugin"，
+#    Topics = deepseek-harness, dsh-plugin, image-deck, presentation, deck
+# 4) 打 tag / 发 Release
+cd dist/public && git tag v0.1.0 && git push origin v0.1.0
+gh release create v0.1.0 --notes "First public release: install via dsh plugin add dsh-plugin-deck-studio"
+
+# 5) npm 发布（Phase 1）
+cd plugin/deck-studio
+npm publish --access public     # 需要 npm 账号 + 2FA
+```
+
+**公开包内容（白名单）**：
+
+- `README.md` / `LICENSE` / `CHANGELOG.md`；
+- `docs/`：`productization.md`、`install.md` + `install.en.md`、`styles.md` + `styles.en.md`、`sample-deck.md` + `sample-deck.en.md`、`compat.md`；
+- `plugin/deck-studio/`：插件本体（宿主 + 客户端 + ui + lib + seeds 预设风格/样张 + verify smoke）；
+- `samples/deckline-intro/`：示例 deck 源（README / intent / script）；
+- `assets/logo/`：sample logo（svg + png）。
+
+**不公开**：`CURRENT.md` / `HANDOVER.md` / `tasks.md` / `docs/feedback.md` / `docs/architecture.md` /
+`docs/adr/` / `docs/research/` / `fixtures/`（含客户材料的本地源引用）/ `.deck/`（运行数据）/ git 历史。
+
+**已完成的清理**：
+
+1. `cordis.patch.yml` 个人路径 → profile patch；仓库里是通用 bundle patch + `cordis.example.yml`；
+2. 插件 `package.json`：`private: false`、MIT、直发包名、repository / homepage / peerDependencies；
+3. 插件代码脱敏：`client.js` / `lib/config.js` / `lib/deck-workspace.js` / `lib/render-nodes.js` /
+   `lib/source-adapter.js` / `lib/tools.js` / `verify/smoke.mjs` 里的客户名、个人路径、环境变量名全部替换为通用示例；
+4. 白名单脚本内置禁用词扫描（客户名 / `/Users/` / `sk-` / 私有 key 名），命中即中止打包。
+
+## 5. 安装与分发矩阵
+
+| 方式 | 命令 | 适合 |
+|---|---|---|
+| npm | `dsh plugin --profile deckline add dsh-plugin-deck-studio` | 普通用户（发布后） |
+| Git | `dsh plugin --profile deckline add "github:yuna78/dsh-deck-studio#path:/plugin/deck-studio"` | 想跟 main 的人 |
+| 本地 clone | `dsh plugin --profile deckline add "$PWD/plugin/deck-studio"` | 开发者 / 定制 |
+
+三种方式都落在 `~/.dsh/profiles/deckline/`；安装后用户只需要改 **profile patch**（decks / projectsRoot / render 节点），
+不需要动插件包本身——这是「任何人可安装」的关键边界。
+
+## 6. 配置口径（生图 key）
+
+- 配置只存在于两处：**profile patch**（结构）与 **环境变量 / key 文件**（凭证）；
+- 结构里只写 `apiKeyEnv`（变量名）或 `apiKeyFile`（本机路径），**永远不写 key 明文**；
+- 工作台设置面板只显示 `keyConfigured` 布尔 + 来源名；
+- 支持多节点（主 / 备用 / 不同模型），每节点独立 key；
+- 缺 key 时：fake 模式仍可走通流程；real 模式报错信息直接给出配置位置。
+
+## 7. 风格生态（本产品化差异点）
+
+- **预设包随插件分发**：`plugin/deck-studio/seeds/styles/<ABBR>.json`（定义，含 `styleBrief` + `baselineBriefs`）
+  + `seeds/samples/<ABBR>-0{1,2,3}.jpg`（3 张基线样张）；
+- **一键导入**：Designs 页「＋ 导入预设风格」，已存在的缩写自动跳过（幂等）；
+- **自己加**：界面里贴图/上传/拖拽；或把图片放到 `designs/<ABBR>/`；
+- **贡献**：PR 新增一个 JSON + 3 张基线样张即可（schema：abbr / name / description / constraints / reference / styleBrief / baselineBriefs）；
+- 已知限制：样张是风格示意，不保证能逐字复刻其中的文字（图像模型通病）；要精确文字用 HTML/Mermaid 叠字。
+
+## 8. 风险与边界
+
+| 风险 | 说明 | 对策 |
+|---|---|---|
+| DSH 插件 API 变动 | 插件依赖 DSH 版本 | 声明 peer 范围 + CI 跑 smoke + 版本豁免文档 |
+| 凭证泄漏 | 用户误把 key 写进 patch | 文档强调 apiKeyEnv / apiKeyFile；设置面板不回显 |
+| 出图成本失控 | 用户批量出图 | 允许点名批量 / 整套（逐页留痕、失败单页重出）；不做一键按钮，避免误触 |
+| 客户数据 | deck 源可能含敏感内容 | 源只读、产物本地 `.deck`、仓库不含数据；导出交接包脱敏 |
+| 模型质量 | 文字糊、版式跑 | 风格 prompt 约束 + 「文字少而英文」建议 + 后期叠字 |
+
+## 9. 里程碑（建议时间）
+
+- **M1（本周）**：Phase 0 完成 + 本机导入 8 个预设风格可用；
+- **M2（下周）**：仓库公开 + v0.1.0 Release + 2 位外部用户装通；
+- **M3（两周内）**：npm 发布 + CI + 首次启动向导；
+- **M4（一个月）**：风格库页面 + UI 双语 + 社区风格包。
+
+## 10. 已拍板（2026-10-21）
+
+| # | 决策 | 结论 | 落地 |
+|---|---|---|---|
+| 1 | License | **MIT** | `LICENSE` + package.json `license: MIT` |
+| 2 | 包名 | **直发，无 org**：`dsh-plugin-deck-studio` | package.json `name` / `private: false` |
+| 3 | 公开范围 | 插件 + docs + 预设 design + **1 个 sample deck** + **1 个 sample logo** | `scripts/build-public-bundle.mjs` 白名单；不含内部台账与历史 |
+| 4 | 品牌 | **Deckline** 最终确认（仓库名仍 `dsh-deck-studio`） | README / UI / logo |
+| 5 | 公开账号 | GitHub `yuna78`；仓库 `yuna78/dsh-deck-studio`（public） | 待负责人确认后 `gh repo create` + push |
+
+**还等负责人执行的 2 个动作**：
+
+1. 确认公开：跑 `node scripts/build-public-bundle.mjs` 后 `gh repo create yuna78/dsh-deck-studio --public --source dist/public --remote origin --push`；
+2. npm 发布：`cd plugin/deck-studio && npm publish --access public`（需登录 npm + 2FA）。
+
+之后 CI / Release / 截图由本轮之后的迭代补。

package/seeds/docs/sample-deck.en.md

@@ -0,0 +1,114 @@
+# Sample deck: run the first pipeline with the Deckline product handbook
+
+The repository ships a 10-page sample deck source: [`samples/deckline-intro/`](../samples/deckline-intro/).
+It describes what Deckline is, why it exists, how to use it and how to install it — and doubles as an
+end-to-end check of the whole loop:
+**new deck → agent drafts intent/script → confirm → render page by page → governance docs → export**.
+
+> Key point: **the content is entered in the "＋ New Deck" dialog on the home page**, not pasted into chat
+> afterwards. The dialog fields are carried into the planning prompt sent to the agent; the agent drafts
+> intent / script and you only confirm the diffs.
+
+Field cheat sheet (copy-paste ready): [`samples/deckline-intro/popup.md`](../samples/deckline-intro/popup.md).
+
+> **Language note**: the workbench UI is currently Chinese-first (English UI strings are on the roadmap).
+> For this walkthrough, keep the Chinese values below — they are what the dialog and the agent expect.
+
+## Step 1: "＋ New Deck" on the home page, fill the fields
+
+| Field | Value |
+|---|---|
+| **Topic / title** | `Deckline 产品说明手册` |
+| **Project directory name** (optional) | `deckline-intro` |
+| **Audience / users** | `第一次接触 Deckline 的人：会用 DSH、做分享材料的产品 / 咨询 / 培训 / 内容创作者；被「改稿、版本、找不到图」折磨过的人。` |
+| **What to talk about** | `一句话：Deckline 不是又一个 PPT 编辑器，而是把「讲给谁、讲什么、怎么出图」变成一条可追踪的产线——Chat 里讨论、工作台里逐页出图、风格可复用、源文件只读。` |
+| **Intent / takeaways** | `① 记住三句话：Chat 里讨论、工作台里出图、源文件只读；② 愿意按 README 花 5 分钟装一个并跑通第一个 deck；③ 知道边界：一期只做 image deck，出图按页、可点名批量连出，不碰 HTML deck。` |
+| **References** (optional) | Copy the whole "real material list" below (README / docs / code paths / screenshots / logo; see [`samples/deckline-intro/materials.md`](../samples/deckline-intro/materials.md)) |
+| **Style** | Pick the preset **`FYI · 高端深色（玻璃质感）`**; to switch, deselect then pick `BIZ` or `SWS`, or write a custom description |
+
+**References · one-page summary + real material + links (copy the whole block into the References field)**:
+
+> These are the **real materials** in the repository (a one-page fact summary + README / product docs /
+> code paths / preset styles / logo / screenshots / links), not a hand-designed 10-page outline. Which
+> material feeds which page: [`samples/deckline-intro/materials.md`](../samples/deckline-intro/materials.md).
+
+```text
+项目材料（都在本仓库，请先读再写；事实以这些为准，不要编）：
+
+【0. 先读】samples/deckline-intro/materials/project-summary.md —— 一页事实摘要：
+  定位 / 用户问题 / 三段式工作台 / 核心闭环 / deck 与 design / 一期边界 / 关键数字 / 安装 / 许可 / 链接。
+  （摘要每条都标了来源；摘要没写的，回查来源文件或问我，不要自己编。）
+
+【1. 文档（真实链接）】
+  README.md —— 产品定位 / 三段式 / 5 分钟安装 / 命令
+  CHANGELOG.md —— v0.1.0 能力清单与边界
+  docs/productization.md —— 产品化定位、路线图、发布范围、一期边界
+  docs/install.md —— 安装、profile 配置、出图节点与 key 放置、fake 模式
+  docs/styles.md —— 8 个预设风格 + 自定义风格方法
+  docs/sample-deck.md —— 用示例 deck 跑通流程（本页步骤来源）
+
+【2. 代码（真实链接）】
+  plugin/deck-studio/index.js —— 宿主路由与数据契约（workbench / deck-create / page-render / doc / export…）
+  plugin/deck-studio/lib/ —— deck 工作区 / 9 份治理文档 / 出图与 revision/QA / 风格 / Agent 工具
+  plugin/deck-studio/ui/ —— 三栏 UI 结构（workbench.html · workbench.css · client.js）
+  plugin/deck-studio/seeds/styles/*.json · seeds/samples/*.jpg —— 8 份预设风格定义与样张
+
+【3. 品牌与截图】
+  assets/logo/ —— 品牌 logo（封面 / 内页可用）
+  samples/deckline-intro/materials/screenshots/01~04.png —— 工作台 / 首页 Decks / Designs / 新建 Deck 弹窗
+
+【4. 现成稿（结构参考，可改写）】
+  samples/deckline-intro/script.md · intent.md —— 这套示例 deck 已写好的 10 页逐页稿
+
+【5. 链接】
+  公开仓库（发布后）：https://github.com/yuna78/dsh-deck-studio
+  现在真机测试：用上面这些「仓库相对路径」即可（Agent 的 cwd 就是本仓库根目录）
+
+写法要求：先复述你读到的产品定位（一句话 + 三个痛点 + 边界），再起 10 页 script；
+每页直接写结论、标题 ≤20 字、带画面说明、备注来源文件（如 P05 ← README.md）；
+不确定的事实回查上面文件或问我，不要编造数字 / 客户 / 案例 / URL。
+```
+
+
+## Step 2: click "创建并开始对话"
+
+After submitting, the plugin does three things automatically (**no need to paste an outline into chat**):
+
+1. Creates the deck source directory and the skeletons of the 7 required documents (intent / script /
+   design / changelog / feedback / research / materials);
+2. Opens a conversation for the deck and sends the **audience / topic / intent / references / style** as a
+   planning prompt to the agent;
+3. The agent restates the goal, lists what it still needs from you → completes intent → drafts the script
+   (it does not render images yet).
+
+What you do:
+
+- Review the intent diff in the **middle workspace** → confirm (a revision is only written after
+  confirmation);
+- Review the script draft diff: titles ≤20 characters, conclusions stated directly, every page has a
+  visual note → confirm;
+- Keep talking to the agent if anything is off; changes go through the same diff → confirm flow.
+
+## Step 3: render (named batches welcome)
+
+- Pick the render node on the right, then say "render P01 first" or "render P01–P10": a named batch counts as
+  confirmed and the agent renders in sequence; each page keeps its own image and revisions, so a failed page can
+  be retried on its own;
+- Unhappy with a page? Ask for a prompt change and re-render — **old revisions are kept**, roll back anytime;
+- Use the **Design / changelog / governance** tabs to inspect documents and revisions along the way;
+- When done: `导出` (export) → PDF / PPTX / handoff package (script + prompts + page images + 7 documents + events).
+
+## Expected result
+
+- A 10-page full-image deck with a consistent style (the sample uses dark glass);
+- Every page has its prompt, image, revision and events, and can roll back to any revision;
+- All 7 governance documents present, ready to hand off to the next person;
+- You have run the whole "new → confirm → render → export" loop — that is the core of Deckline.
+
+## Notes
+
+- The sample deck source lives in [`samples/deckline-intro/`](../samples/deckline-intro/); you can register
+  it in the profile's `decks[]` as a public demo (see [install.md](install.md) section 2);
+- Samples illustrate the style; for text-heavy pages prefer "little text / English placeholders", and
+  overlay exact text after rendering;
+- A failed or re-run render never affects old revisions, and the source deck directory stays read-only.

package/seeds/docs/sample-deck.md

@@ -0,0 +1,104 @@
+# Sample deck：用《Deckline 产品说明手册》跑通第一条产线
+
+简体中文 · [English](sample-deck.en.md)
+
+仓库自带一个 10 页示例 deck：[`samples/deckline-intro/`](../samples/deckline-intro/)——含逐页脚本、每页 prompt、
+10 张已渲染的示例页（`pages/`）和同一份结果的 PPTX（`deckline-intro.pptx`），可以直接看效果再复刻。
+它介绍 Deckline 自己是什么、为什么做、怎么用、怎么装——顺便用来验证整条闭环：
+**新建 Deck → Agent 起草 intent/script → 确认 → 逐页出图 → 治理文档 → 导出**。
+
+> 关键：**内容是在首页「＋ 新建 Deck」弹窗里填的**，不是你事后往 Chat 里粘一大段话。
+> 弹窗里的字段会被插件带进给 Agent 的整理 prompt，Agent 接着起草 intent / script，你只负责确认 diff。
+
+弹窗字段速查（可直接复制）：[`samples/deckline-intro/popup.md`](../samples/deckline-intro/popup.md)。
+
+## 第 1 步：首页「＋ 新建 Deck」，按下面逐字段填
+
+| 字段 | 填什么 |
+|---|---|
+| **主题 / 标题** | `Deckline 产品说明手册` |
+| **项目目录名**（可选） | `deckline-intro` |
+| **受众 / 用户** | `第一次接触 Deckline 的人：会用 DSH、做分享材料的产品 / 咨询 / 培训 / 内容创作者；被「改稿、版本、找不到图」折磨过的人。` |
+| **想讲什么话题** | `一句话：Deckline 不是又一个 PPT 编辑器，而是把「讲给谁、讲什么、怎么出图」变成一条可追踪的产线——Chat 里讨论、工作台里逐页出图、风格可复用、源文件只读。` |
+| **意图 / 希望大家带走什么** | `① 记住三句话：Chat 里讨论、工作台里出图、源文件只读；② 愿意按 README 花 5 分钟装一个并跑通第一个 deck；③ 知道边界：一期只做 image deck，出图按页、可点名批量连出，不碰 HTML deck。` |
+| **参考资料**（可选） | 见下方「真材料清单」整段复制（README / docs / 代码路径 / 截图 / logo，详见 [`samples/deckline-intro/materials.md`](../samples/deckline-intro/materials.md)） |
+| **风格** | 点选 preset **`FYI · 高端深色（玻璃质感）`**；想换就取消再点 `BIZ` 或 `SWS`，也可以自定义描述 |
+
+**参考资料 · 一页摘要 + 真材料 + 链接（整段复制进「参考资料」框）**：
+
+> 这里给的是仓库里的**真实材料**（一页事实摘要 + README / 产品文档 / 代码路径 / 预设风格 / logo / 截图 / 链接），
+> 不是「我设计好的 10 页大纲」。每份材料用在哪一页见 [`samples/deckline-intro/materials.md`](../samples/deckline-intro/materials.md)。
+
+```text
+项目材料（都在本仓库，请先读再写；事实以这些为准，不要编）：
+
+【0. 先读】samples/deckline-intro/materials/project-summary.md —— 一页事实摘要：
+  定位 / 用户问题 / 三段式工作台 / 核心闭环 / deck 与 design / 一期边界 / 关键数字 / 安装 / 许可 / 链接。
+  （摘要每条都标了来源；摘要没写的，回查来源文件或问我，不要自己编。）
+
+【1. 文档（真实链接）】
+  README.md —— 产品定位 / 三段式 / 5 分钟安装 / 命令
+  CHANGELOG.md —— v0.1.0 能力清单与边界
+  docs/productization.md —— 产品化定位、路线图、发布范围、一期边界
+  docs/install.md —— 安装、profile 配置、出图节点与 key 放置、fake 模式
+  docs/styles.md —— 8 个预设风格 + 自定义风格方法
+  docs/sample-deck.md —— 用示例 deck 跑通流程（本页步骤来源）
+
+【2. 代码（真实链接）】
+  plugin/deck-studio/index.js —— 宿主路由与数据契约（workbench / deck-create / page-render / doc / export…）
+  plugin/deck-studio/lib/ —— deck 工作区 / 9 份治理文档 / 出图与 revision/QA / 风格 / Agent 工具
+  plugin/deck-studio/ui/ —— 三栏 UI 结构（workbench.html · workbench.css · client.js）
+  plugin/deck-studio/seeds/styles/*.json · seeds/samples/*.jpg —— 8 份预设风格定义与样张
+
+【3. 品牌与截图】
+  assets/logo/ —— 品牌 logo（封面 / 内页可用）
+  samples/deckline-intro/materials/screenshots/01~04.png —— 工作台 / 首页 Decks / Designs / 新建 Deck 弹窗
+
+【4. 现成稿（结构参考，可改写）】
+  samples/deckline-intro/script.md · intent.md —— 这套示例 deck 已写好的 10 页逐页稿
+
+【5. 链接】
+  公开仓库（发布后）：https://github.com/yuna78/dsh-deck-studio
+  现在真机测试：用上面这些「仓库相对路径」即可（Agent 的 cwd 就是本仓库根目录）
+
+写法要求：先复述你读到的产品定位（一句话 + 三个痛点 + 边界），再起 10 页 script；
+每页直接写结论、标题 ≤20 字、带画面说明、备注来源文件（如 P05 ← README.md）；
+不确定的事实回查上面文件或问我，不要编造数字 / 客户 / 案例 / URL。
+```
+
+
+## 第 2 步：点「创建并开始对话」
+
+提交后插件会自动做三件事（**不需要你再粘 Chat 稿**）：
+
+1. 建好 deck 源目录 + 9 份必备文档骨架（intent / script / design / 修改日志 / 反馈 / 调研 / 支撑材料 / 审稿 / 事实核对）；
+2. 自动打开这个 deck 的会话，把**受众 / 话题 / 意图 / 参考资料 / 风格**拼成一条整理 prompt 发给 Agent；
+3. Agent 先复述目标、列出还要你补的资料 → 补完整 intent → 起 script 草案（不直接出图）。
+
+你要做的只有：
+
+- 看 **中间工作区** 的 intent diff → 确认（确认后才落 revision）；
+- 看 script 草案 diff：标题 ≤20 字、直接写结论、每页有画面说明 → 确认；
+- 不满意就继续和 Agent 说，改动同样走 diff → 确认。
+
+## 第 3 步：出图（可点名批量）
+
+- 右侧出图节点选好后，说「先出 P01」或「把 P01–P10 都出一下」：点名多页 = 已确认，Agent 按页序连续出；
+  每页一张整页图、各自留版本，失败只重出那一页；
+- 不满意就让它改 prompt 重出，**旧版本会保留**，可随时回退；
+- 中途切 **Design / 修改日志 / 治理** 标签检查文档和版本；
+- 全部出完：`导出` → PDF / PPTX / 交接包（script + prompt + 每页图 + 9 份文档 + 事件）。
+
+## 期望结果
+
+- 10 页整页图片 deck，风格统一（示例是深色玻璃质感）；
+- 每页都有 prompt、图片、版本、事件记录，能回退到任意一版；
+- 治理文档 9 份齐备（含审稿 / 事实核对），可直接交接给下一个人；
+- 你已经把「新建 → 确认 → 出图 → 导出」完整跑了一遍——这就是 Deckline 的全部核心操作。
+
+## 说明
+
+- 示例 deck 源在 [`samples/deckline-intro/`](../samples/deckline-intro/)，可以注册进 profile 的 `decks[]`
+  当公开演示（见 [install.md](install.md) 第 2 节）；
+- 样张是风格示意；文字多的页建议「少字 / 英文占位」，精确文字可在出图后叠字；
+- 一次失败/重出不影响旧版本，源 deck 目录始终只读。

package/seeds/docs/styles.en.md

@@ -0,0 +1,112 @@
+# Design styles (Designs) and custom styles
+
+A Deckline "style" (design) is a first-class entity: one description plus a set of sample images.
+Register it once and reuse it on any deck; when the agent renders, the description becomes the visual
+language for the images.
+
+## 1. Use preset styles (recommended starting point)
+
+Designs page → **＋ Import preset styles** imports the 8 styles below in one click (each ships with
+3 real baseline samples: cover / info page / data page). It is idempotent — existing abbreviations are
+skipped, never duplicated.
+
+| Abbr | Name | Visual language | Best for |
+|---|---|---|---|
+| BIZ | Business consulting (blue-grey) | White base + deep navy + warm orange accents, thin-line tables / three-column frames / data cards | Proposals, reviews, data pages |
+| FYI | Premium dark (glass) | Near-black charcoal base + glass panels + violet-cyan aurora + champagne gold | Launches, keynotes, premium brands |
+| JPN | Japanese minimal (paper) | Cream paper base + low-saturation navy/vermilion + thin frames + generous whitespace | Culture, training, quiet narratives |
+| EDT | Magazine editorial (serif headlines) | Cream white + bold serif headlines + strict grid + vermilion accents | Brand stories, long-form info pages |
+| TEC | Tech blueprint (isometric) | Deep navy grid + cyan-white technical lines + isometric system diagrams | Architecture, technical proposals |
+| SKT | Hand-drawn whiteboard (workshop) | Whiteboard + markers + sticky notes + handwritten headings | Workshops, co-creation, training |
+| SWS | Swiss minimal (black/white/red) | Pure white + oversized black type + true red + generous whitespace | Minimal manifestos, big-type posters |
+| GRD | Aurora gradient (modern SaaS) | Violet-cyan aurora gradients + glow + 3D abstraction + glass cards | Product launches, internet style |
+
+Definitions: `plugin/deck-studio/seeds/styles/<ABBR>.json`; samples:
+`plugin/deck-studio/seeds/samples/<ABBR>-0{1,2,3}.jpg` (3 baseline samples, 1280-wide previews).
+Importing is idempotent: clicking again only skips styles that already exist.
+
+## 2. Add your own style
+
+### Way 1: in the UI (supports pasting images)
+
+1. Designs page → **＋ Add style**;
+2. Fill in: name, abbreviation (2–6 letters, e.g. `INK`), visual description (paper feel / strokes /
+   colors / layout / information density), and what to avoid (negative constraints);
+3. "Sample images" area: **⌘V paste / drag and drop / pick files** (png / jpg / webp, multiple, ≤12 MB each);
+4. Create: this creates the style directory, a 0-page canvas deck and a design conversation; samples
+   appear immediately on the card and in the preview.
+
+To add samples to an existing style: click the **eye** icon on the style card → "＋ Add sample" at the
+bottom of the preview (paste / pick files work the same way).
+
+### Way 2: drop files directly
+
+Put images under `designs/<ABBR>/` (canvas directory
+`.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`, or `designs/<ABBR>/` inside any managed deck
+source). png / jpg / webp are supported; refresh the page afterwards.
+
+Fields of `style.json` (the plugin also writes one automatically):
+
+```json
+{
+  "abbr": "INK",
+  "name": "Ink-wash info page",
+  "description": "Visual language: paper texture, ink wash gradations, whitespace, brush strokes…",
+  "constraints": "no 3D, no cartoon, no photos",
+  "reference": "reference sources / brand elements (optional)",
+  "styleBrief": "full visual prompt attached automatically when rendering samples (colors / strokes / layout / type hierarchy / prohibitions)",
+  "baselineBriefs": [
+    { "title": "Cover", "brief": "What this sample should try: …" },
+    { "title": "Info page", "brief": "…" },
+    { "title": "Data page", "brief": "…" }
+  ]
+}
+```
+
+- `styleBrief`: **the style prompt itself**. It is attached automatically when the agent renders samples
+  (`composeSamplePrompt`); you only supply "what this sample should try" (brief). All 8 preset styles have
+  been completed against real samples; change styles via `deck_style_update` / the UI "duplicate" flow.
+  Note: `reference` is for humans only and never goes into image prompts — agency / client brand names
+  trigger the image adapter's content filter (manifesting as a 180 s timeout).
+- `baselineBriefs`: the layout briefs for the 3 baseline samples shipped with a preset (cover / info page /
+  data page), used by the regeneration script and "import presets".
+
+## 3. Writing a good visual description
+
+- State the **base / primary / accent colors** (hex values are welcome);
+- State the **strokes and texture** (paper grain, markers, gradients, blueprint lines);
+- State the **layout** (title position, columns, cards, tables, whitespace);
+- State the **information density** and **what to avoid** (negative constraints matter);
+- For text-heavy pages: image models garble text; prefer "little text, English" or overlay text afterwards.
+
+## 4. Contributing preset styles (PR flow)
+
+1. Add `plugin/deck-studio/seeds/styles/<ABBR>.json` (fields as above; `abbr` 2–6 uppercase letters, unique);
+2. Put 3 baseline samples in `plugin/deck-studio/seeds/samples/` as `<ABBR>-01.jpg` / `<ABBR>-02.jpg` /
+   `<ABBR>-03.jpg` (16:9, 1280 wide, ≤600 KB each, no client information / real logos) and write
+   `styleBrief` + `baselineBriefs` in the JSON;
+3. Run `node plugin/deck-studio/verify/smoke.mjs` locally (presets are verified together with fixtures);
+4. Open a PR describing where the style fits and the key points of the sample prompts.
+
+> Samples illustrate the style, not guarantee reproduction of their text content. Please never submit real
+> client material, brand logos or unlicensed assets.
+
+## 5. Preset baseline samples (3 per style) and regeneration
+
+Each of the 8 presets has 3 baseline samples (cover / info page / data page): they show at a glance what
+the style can produce, and give the agent a "same style, different layout" reference. Regeneration:
+
+```bash
+# 8 presets × 3 samples (render at 1920×1080 → downscale to 1280-wide JPEG back into seeds/samples)
+node scripts/f74-regenerate-presets.mjs
+# Regenerate one style / try one sample only
+node scripts/f74-regenerate-presets.mjs --only=BIZ --limit=1
+```
+
+What the script does: sync `styleBrief` from `seeds/styles/<ABBR>.json` into the online design's
+`style.json` → back up old samples to `.deck/tmp/f74-old-samples/<ABBR>/` → render one image per
+`baselineBriefs` entry (prompt recorded in `samples.jsonl`) → downscale and write back into `seeds/samples/`.
+Refresh the Designs page afterwards; no service restart needed.
+
+> Text inside samples is illustrative (image models garble text); it is not guaranteed verbatim. Never put
+> real client material or brand logos into sample images.

package/seeds/docs/styles.md

@@ -0,0 +1,100 @@
+# 风格目录（Designs）与自定义风格
+
+简体中文 · [English](styles.en.md)
+
+Deckline 的「风格」是独立实体（design）：一份描述 + 若干样张。登记一次，可以在任何 deck 上复用；
+Agent 出图时会以这份描述作为画面语言的基础。
+
+## 一、用预设风格（推荐先从这里开始）
+
+Designs 页 → **＋ 导入预设风格**：一次导入下面 8 个风格（每个都带 3 张真实基线样张：封面 / 信息页 / 数据页），幂等——
+已存在的缩写自动跳过，不会重复创建。
+
+| 缩写 | 名称 | 画面语言 | 适合 |
+|---|---|---|---|
+| BIZ | 商务咨询（蓝灰） | 白底 + 深海军蓝 + 暖橙强调，细线表格 / 三栏框架 / 数据卡 | 提案、汇报、数据页 |
+| FYI | 高端深色（玻璃质感） | 近黑炭底 + 玻璃面板 + 紫青极光 + 香槟金 | 发布会、keynote、高端品牌 |
+| JPN | 日系极简（纸感） | 米白纸底 + 低饱和藏青/朱色 + 细线框 + 大留白 | 文化、培训、安静叙事 |
+| EDT | 杂志编辑（衬线大标题） | 奶油白 + 粗衬线大标题 + 严格栅格 + 朱红强调 | 品牌故事、长文信息页 |
+| TEC | 科技蓝图（等距） | 深海军蓝网格 + 青白技术线 + 等距系统图 | 架构、技术方案 |
+| SKT | 手绘白板（工作坊） | 白板 + 马克笔 + 便签 + 手写标题 | 研讨、共创、培训 |
+| SWS | 瑞士极简（黑白红） | 纯白 + 超大黑体 + 正红 + 大留白 | 极简宣言、大字报 |
+| GRD | 渐变极光（深色玻璃 · 编辑感） | 近黑炭底 + 紫青极光丝带 + 玻璃面板 + 香槟金细线 | 深色封面、编辑感信息页 |
+
+定义文件：`plugin/deck-studio/seeds/styles/<ABBR>.json`；样张：`plugin/deck-studio/seeds/samples/<ABBR>-0{1,2,3}.jpg`
+（3 张基线样张，1280 宽预览）。导入逻辑幂等：再点一次只会跳过已存在的风格。
+
+## 二、自己加一个风格
+
+### 方式 1：界面里加（可以贴图）
+
+1. Designs 页 → **＋ 添加风格**；
+2. 填：名称、缩写（2–6 位字母，如 `INK`）、画面描述（纸感 / 笔触 / 颜色 / 版面 / 信息密度）、不要什么（负面约束）；
+3. 「样张图片」区：**⌘V 粘贴 / 拖入 / 点选文件**（png / jpg / webp，可多张，≤12MB/张）；
+4. 创建：会同时建风格目录、0 页空白画布 deck 和一个 design 会话；样张立即出现在卡片和预览里。
+
+已有风格补样张：点风格卡右上角 **眼睛** → 预览底部「＋ 添加样张」，同样可粘贴 / 选文件。
+
+### 方式 2：直接放文件
+
+把图片放进 `designs/<ABBR>/` 目录（画布目录 `.deck/projects/<canvasDeckId>/source/designs/<ABBR>/`，
+或任何受控 deck 源里的 `designs/<ABBR>/`）。支撑 png / jpg / webp，刷新页面即可。
+
+`style.json` 的字段（插件也会自动写一份）：
+
+```json
+{
+  "abbr": "INK",
+  "name": "水墨信息页",
+  "description": "画面语言：纸感、墨色浓淡、留白、毛笔线条……",
+  "constraints": "不要 3D、不要卡通、不要照片",
+  "reference": "参考来源 / 品牌元素（可选）",
+  "styleBrief": "出样张时自动带上的完整画面提示词（色值 / 笔触 / 版式 / 字号层级 / 禁用项）",
+  "baselineBriefs": [
+    { "title": "封面", "brief": "这张要试的画面：……" },
+    { "title": "信息页", "brief": "……" },
+    { "title": "数据页", "brief": "……" }
+  ]
+}
+```
+
+- `styleBrief`：**风格提示词本体**。Agent 出样张时自动带上（`composeSamplePrompt`），只需要再补「这张要试的画面」（brief）。
+  预设包里的 8 个风格都已按真实样张补齐；改风格用 `deck_style_update` / 界面「复制」后改。
+  注意：`reference` 只给人看，不进 image prompt——写机构 / 客户品牌名会触发 image adapter 内容过滤（表现为 180s 超时）。
+- `baselineBriefs`：预设自带的 3 张基线样张的版面 brief（封面 / 信息页 / 数据页），供重制脚本与「导入预设」使用。
+
+## 三、写一条好的画面描述
+
+- 说清 **底色 / 主色 / 强调色**（可以直接写 hex）；
+- 说清 **笔触与质感**（纸纹、马克笔、渐变、蓝图线）；
+- 说清 **版面**（标题位置、分栏、卡片、表格、留白）；
+- 说清 **信息密度** 和 **不要什么**（负面约束很重要）；
+- 需要很多文字时：图像模型会糊字，建议「文字少而英文」或者出图后叠字。
+
+## 四、贡献预设风格（PR 流程）
+
+1. 在 `plugin/deck-studio/seeds/styles/` 新增 `<ABBR>.json`（字段同上，`abbr` 2–6 位大写字母，唯一）；
+2. 在 `plugin/deck-studio/seeds/samples/` 放 3 张基线样张 `<ABBR>-01.jpg` / `<ABBR>-02.jpg` / `<ABBR>-03.jpg`
+   （16:9，1280 宽，≤600KB/张，不要含客户信息 / 真实 logo），并在 JSON 里写清 `styleBrief` + `baselineBriefs`；
+3. 本地跑 `node plugin/deck-studio/verify/smoke.mjs`（预设会随 fixtures 一起验证）；
+4. 提 PR，说明风格适用场景 + 样张 prompt 要点。
+
+> 样张是「风格示意」，不承诺复刻其中的文字内容；请不要提交真实客户资料、品牌 logo 或未授权素材。
+
+## 五、预设基线样张（3 张打底）与重制
+
+8 个预设风格每个都有 3 张基线样张（封面 / 信息页 / 数据页），作用是：**一眼看清这个风格能做成什么样**，
+同时给 Agent 一个「同风格但不同版面」的参照。重制流程：
+
+```bash
+# 8 个预设 × 3 张（1920×1080 出图 → 压 1280 宽 JPEG 回写 seeds/samples）
+node scripts/f74-regenerate-presets.mjs
+# 只重制一个风格 / 只试一张
+node scripts/f74-regenerate-presets.mjs --only=BIZ --limit=1
+```
+
+脚本做的事：把 `seeds/styles/<ABBR>.json` 的 `styleBrief` 同步进线上 design 的 `style.json` →
+旧样张备份到 `.deck/tmp/f74-old-samples/<ABBR>/` → 按 `baselineBriefs` 逐张出图（prompt 落 `samples.jsonl`）→
+预览回写 `seeds/samples/`。重制后刷新 Designs 页即可看到新样张；不用重启服务。
+
+> 样张里的文字是示意（图像模型会糊字），不承诺逐字复刻；也不要把真实客户资料、品牌 logo 放进样例图。