@liustack/pptwise 0.22.0 → 0.24.0

package/skills/pptwise/SKILL.zh-CN.md

@@ -3,100 +3,163 @@ summary: 'skills/pptwise/SKILL.md 的中文阅读镜像，仅供人工审阅该
 mirror_of: skills/pptwise/SKILL.md
 ---
 
-# pptwise — deck 生成操作手册
+# pptwise deck 生成操作手册
 
-> 本文件是 [`skills/pptwise/SKILL.md`](./SKILL.md) 的中文阅读镜像，供中文使用者审阅这个 skill 会指示 agent 执行的内容。agent 始终加载并执行英文版 `SKILL.md`——本文件不含 `name` 字段，从不注册为一个独立的 skill，也从不被 agent 读取。两个文件如有出入，以英文版 `SKILL.md` 为准。修改任一文件时，必须把改动同步镜像到另一文件。
+> 本文件是 [`skills/pptwise/SKILL.md`](./SKILL.md) 的中文阅读镜像。agent 只注册并执行英文版。两份文件如有出入，以英文版为准。
 
-pptwise 把一份 JSON IR（intermediate representation，中间表示）转换成原生 DrawingML 格式的 `.pptx`——每个图形在 PowerPoint 里都保持可编辑。内容模型由你掌控，layout、style 与动效由工具掌控。你从不绘制 SVG，也从不给任何东西定位：从受控词汇表里挑选，装不下的内容交给 validate 关卡去拦。
+pptwise 把语义 JSON 转成原生 DrawingML `.pptx`。文字与图形在 PowerPoint 中保持可编辑。作者只描述每页在怎么讲，以及页面包含哪些有类型的组件。页面的脸、几何、配色、字体和装饰归主题与引擎。
 
-## 怎么跑
+严格按这条单向链工作，不跨步，不同时决定两层。
 
-这份操作手册里的每一步都走 CLI：schema、spec/assemble、validate、render、audit、preview、serve、品牌提取。这些命令一律通过本 skill 自带的启动器执行，由它替你解析出一个可用的运行时。把 `<skill-dir>` 换成这份 SKILL.md 所在的目录：
+```text
+意图 -> 叙事 -> 主题绑定 -> 带 kind 的 spec -> 填充 -> 渲染
+```
+
+## 运行 CLI
+
+所有命令都通过本文件旁边的启动器运行。把 `<skill-dir>` 换成本 skill 的目录。
 
 ```bash
 bash <skill-dir>/scripts/run.sh <args>                                       # macOS / Linux
 powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>  # Windows
 ```
 
-它按顺序尝试：PATH 上版本兼容的 `pptwise`、`npx`、`bunx`，参数与退出码原样透传。不需要预先安装任何东西，跑到的版本被钉死在这份 skill 上。退出码 78 表示没有任何可用运行时：把它 stderr 里 JSON 的 `nextSteps` 转告用户，不要重试。
+启动器依次尝试 `PATH` 上兼容的 `pptwise`、`npx`、`bunx`，参数和退出码原样透传。退出码 78 表示没有 JavaScript 运行时。转告 stderr 中的 `nextSteps`，不要重试。
+
+无法执行脚本时，使用第一条可行路径：
+
+1. 已安装版本的主版本与本 skill 一致，且不低于钉定版本时，运行 `pptwise <args>`。
+2. `npx --yes --package @liustack/pptwise@0.24.0 pptwise <args>`。
+3. `bunx --bun @liustack/pptwise@0.24.0 <args>`。
+4. 都不可用时，请用户安装 Node 22.19+ 或 Bun。
+
+安装后运行 `pptwise doctor`。某个失败无法由错误信息本身解释时也先运行它。转告结果，不要猜。
+
+## 先读取现场真相
+
+永远不要凭记忆写 IR 或 spec。每个 deck 任务开始时运行：
+
+```bash
+pptwise schema
+pptwise schema --spec
+pptwise narratives --json
+pptwise themes --json
+```
+
+提问前先扫描工作区。已有 `deck.spec.json` 会记录叙事、绑定主题、页面顺序、标题与每张内容页的 `kind`。deck 内 `theme.json`、工作区 `themes/` 文件、用户点名的主题，或递来的 `.thmx`、`.potx`、带品牌 `.pptx` 都是主题信号。
+
+## 工作流
+
+### 1. 意图
+
+选择讲法前先记录四个事实：受众、想要的结果、现场讲述还是传阅、可用时长。请求或工作区已经给出的事实直接推导。用户在场且仍缺关键事实时，把所有未决问题合并成一轮询问。
+
+### 2. 叙事
+
+先定叙事，再定主题。叙事决定论证方式、节奏与语气。完全匹配时使用具名预设，否则显式写 `strategy`、`pacing`、`audience`。`pacing` 控制编辑预算与正文字号基线。叙事从不选择页面的脸。
 
-下文凡是写 `pptwise <args>` 的地方，都通过这个启动器执行。
+继续前先确认叙事包。简洁访谈与 spec 示例见 `references/spec.md`。
 
-刚装完，以及任何时候某条命令的表现不对、错误信息又解释不清时，先跑 `pptwise doctor`。它会报告运行时、机器上每一份已安装的 skill 副本及其是否过期、dsh 插件版本、可选能力是否具备，以及一次自检渲染。把它说的原样转达，不要靠猜。
+### 3. 绑定主题
 
-如果你的 harness 不允许执行脚本，就按同样的顺序自己判断，用第一条成立的：
+主题是一个完整、自包含的文件，包含样式、页面菜单、可选品牌规则与场合元数据。内容菜单只服务全局 11 个 `kind` 中的一个子集。缺少某个词是设计选择。
 
-1. PATH 上有 `pptwise`，且主版本号与下面的钉版本相同、版本不低于它：`pptwise <args>`。
-2. 否则，有 `npx` 就用：`npx --yes --package @liustack/pptwise@0.22.0 pptwise <args>`。
-3. 否则，有 `bunx` 就用：`bunx --bun @liustack/pptwise@0.22.0 <args>`。
-4. 都没有就告诉用户机器上找不到 JavaScript 运行时，下一步是装 Node 22.19+（https://nodejs.org）或 Bun（https://bun.sh）。不要说成是 pptwise 本身坏了。
+主题名按三级查找：
 
-## 工作流程
+1. deck 目录。
+2. 从当前目录向上查找工作区 `themes/`。
+3. 24 个出厂预设。
 
-访谈 → spec → pages → validate → audit → render。改动从能承载它的最小一步重新进入。很小的 deck（页数屈指可数）可以跳过 spec 文件，直接写一份 IR，仍用 `pptwise validate` 校验。永远不要凭上一个 session 的记忆、或凭这份文件本身的记忆去写 IR 或 spec。每个 session 都重新跑：
+按请求与工作区信号，用 `occasions` 和 `identity` 筛出候选。用固定样张比较 2 到 4 个候选：
 
 ```bash
-pptwise schema             # IR JSON Schema: the single source of truth
-pptwise schema --spec      # deck spec schema
-pptwise narratives --json  # named narrative presets (strategy/pacing/audience axes + theme recommendations)
-pptwise themes --json      # built-in themes (id + label)
+pptwise theme try consulting,swiss,memo
 ```
 
-动手问人之前，先扫工作区。已有确认过的 `deck.spec.json` 已经锁死 narrative、theme、品牌框：不要重做访谈，改那份 deck。已有 `theme.json`、项目 `pptwise.config.json` 钉死的 theme、用户点名的 theme id、或用户递来的 `.thmx` / `.potx` / 带品牌 `.pptx`，都是品牌信号：抽取或沿用。不要再问有没有模板。
-
-**边界页规则：** `chapter` 和 `ending` 永远不渲染 `components` 或 `footnote`。`cover` 永远不渲染 `footnote`。封面只有在锁定版式声明了对应槽位时才能带 `components`。今天这只发生在 `verdict-index`（consulting）：它读第一个 `bullets` 块，画成最多三条编号论据。其余封面版式仍会丢掉 components。正文放到 `content` 页，除非你在填 consulting 封面那三列论据。对错 JSON 和 spec 写法：`references/spec.md`。
-
-1. **访谈**（最多一轮）：用户在场，且受众、怎么讲、pacing 任一轴仍未知时，把未决的问放进**一条**消息，然后停。不要自己填。Q1–Q4、★ 默认、查表、`NARRATIVE_INTERVIEW` 闸：`references/spec.md`。
-2. **定 spec 并确认**，再写任何页面。写 `deck.spec.json`（以 `cover` 开篇，以 `ending` 收尾，中间是 `content` 或 `chapter`）。跑 `pptwise spec validate` 直到 `OK`，然后固化 `seed`。已确认的 spec 不要重定。写法：`references/spec.md`。品牌框姿态：`references/branding.md`。
-3. **填页面**，每批至多 4 页。写 `pages/<id>.json`（`components`，可选 `layout`/`notes`）。绝不写 `type`/`heading`。Pin-only 与稀排高潮页：`references/layouts.md`。组件形态：`references/components.md`。密度、beat、容量：`references/density.md`。配图：`references/images.md`。
-4. **Validate** 每批之后：`pptwise assemble deck-dir/`，再 `pptwise validate deck-dir/`，直到两者都打印 `OK`。重组被标出的内容，不要删。assemble / validate / audit / preview / serve 回路：`references/validate.md`。
-5. **Audit** 所有页面填完后：`pptwise audit deck-dir/` 直到 exit 0。不要用截图代替。然后把 deck 交给用户（有 `pptwise_preview` 就调它，否则 `preview --html`，再否则 `serve --no-open`）：`references/validate.md`。
-6. **渲染：** `pptwise render deck-dir/`。把打印的绝对路径报给用户。`--draft` 和 `--allow-dropped-content` 只有用户明确要求时才用。
-
-后续请求：改一页 → 只对那一页走步骤 3–6。一份新 deck → 步骤 1。和 deck 生成无关 → 不要调用 pptwise。
-
-## 组件选型
-
-| 内容形态 | 用 | 不用 |
-|---|---|---|
-| 2–5 项头条指标 | `kpi_cards` | `chart` |
-| 系列数据（趋势、对比、占比） | `chart`（`bar`/`line`/`pie`/`funnel`/`dumbbell`/`scatter`/`area`/`donut`/`gauge`） | 埋在 `bullets` 里的数字 |
-| 受众要逐行读的精确数字（价目表、规格表、按周期分列的指标网格） | `data_table` | `chart` |
-| 线性流程，无分支 | `steps` | `flowchart` |
-| 有分支、且最终走到终点的流程 | `flowchart` | `steps` |
-| 循环往复、没有终点的流程（首尾相连回到起点，如 PDCA、产品生命周期、飞轮、季节性循环） | `cycle` | `flowchart` |
-| 双方对比 | `comparison` | 两份 bullet 列表 |
-| 系统/组织分层（一叠层带，例如技术栈分层或成熟度阶梯） | `architecture` | `bullets` |
-| 有日期的里程碑 | `timeline` | 带日期的 `bullets` |
-| 分阶段计划，带多条工作线 | `roadmap` | `timeline` |
-| 分阶段计划，在共享坐标轴上画出带日期的条形 | `gantt` | `roadmap` |
-| 一句结论或要点 | `verdict_banner` 或 `callout` | `paragraph` |
-| 2×2 战略评估（优势/劣势/机会/威胁） | `swot` | `matrix` |
-| 9 宫格商业模式画布 | `bmc` | 拆开的 `bullets`/`row_cards` |
-| 累计合计的桥接/差异拆解 | `waterfall` | `chart` |
-| 2×2 宏观环境扫描（政治/经济/社会/技术） | `pest` | `swot` |
-| 竞争结构分析（竞争强度 + 周边 4 种力量） | `five_forces` | `matrix` |
-| 双轴数值网格，按颜色编码单元格（例如地区 × 季度） | `heatmap` | `matrix` |
-| 跨阶段的比例流量/数量分布（例如预算分配、能源结构） | `sankey` | `chart`（funnel）或 `flowchart` |
-| 产品/软件截图，这张 slide 要让人一眼认出「这是真实、正在运行的软件」（App 仪表盘、真实产品界面） | `device_mockup` | `image` |
-| 一份人员名单（团队、讲者阵容、评委阵容、作者名单），需要一个无照片可用的身份锚点 | `people_cards` | `row_cards`/`icon_cards` |
-| 一组短平行标签（技术栈、能力清单、关键词、资质认证）——是标签，不是带描述的条目 | `tag_row` | `bullets`/`row_cards` |
-
-形态对照、字段说明、满幅组件：`references/components.md`。
+创建就是拷贝。没有现成资产时，把最接近的预设拷进工作区。有 Office 品牌文件时，抽取配色与字体，同时拷入合适的菜单。要改色时，fork 当前主题，让整套配色重新派生，原主题保持不动。
 
-## 规则
+```bash
+pptwise theme new --from consulting --id acme-report
+pptwise brand extract corp.pptx -o themes/acme.theme.json --from consulting
+pptwise theme fork acme --primary '#0B5FFF' --id acme-blue
+```
+
+写页面内容之前，把选中的主题名写进 `deck.spec.json`。绑定后的 deck 命令只读这个名字，没有渲染时临时换主题。
+
+工作流中可以换绑到菜单相同的配色 fork。菜单不同就是另一套主题。回到本步骤，保留意图、叙事、事实、数据、图片与可复用文案，再按新菜单重写 spec 与填充。
 
-- 从不编辑或后处理生成出来的 `.pptx`
-- 从不通过删除 `validate` 报错所指的内容来绕过它——去重组它（拆分 slide、收紧标题、换一个更紧凑的 component 类型）
-- 面向用户的 deck 文本跟随用户使用的语言，IR 的结构性字段永远用 schema 里的英文枚举值
-- 从不告诉用户 `chart`、`data_table` 里的数字可以在 PowerPoint 里直接编辑。这两类组件渲染出来是成组的图形加文字，样式和文字都能自由改，但背后没有原生的图表部件，也没有 `<a:tbl>`。要改数字，去改 IR 再重新渲染
+### 4. 用 `kind` 写 spec
 
-## 何时去读
+spec 锁定主题、叙事、品牌姿态、页面顺序、页型、标题，以及每张内容页的 `kind`。它不保存任何渲染选择状态。
+
+- `cover`、`chapter`、`ending` 是页型，不写 `kind`。
+- 每张 `content` 页必须显式写且只写一个 `kind`。
+- 作者只写语义 `kind`，从不选择页面的脸或几何。
+- `focus` 与 `summary` 是可选写作提示。
+
+运行 `pptwise spec validate deck.spec.json`，直到打印 `OK`。内容页 `kind` 不在绑定主题菜单中时会硬报错，并列出菜单提供的词。不要为了消错给页面贴一个失真的词。只有页面意图确实匹配时才换词，否则回到主题层。
+
+11 个词及边界见 `references/layouts.md`。完整 spec 与主题创建流程见 `references/spec.md`。
+
+### 5. 填页面
+
+每批至多写四个 `pages/<id>.json`。页面文件可以含 `components`、`background`、`image_side`、`footnote`、`notes`。不要重复 `type`、`kind`、`heading`，它们归 spec。
+
+选择服务本页 `kind` 的组件。`quote` 是页面讲法，引用组件名是 `blockquote`。组件归属与相似项对照见 `references/components.md`。节奏与容量见 `references/density.md`。图片流程见 `references/images.md`。
+
+每批完成后运行：
+
+```bash
+pptwise assemble deck-dir/
+pptwise validate deck-dir/
+```
+
+修完每个错误后重跑两条命令。重组内容，不要删除校验抓到的信息。
+
+### 6. 审查、预览与渲染
+
+所有页面填完后运行：
+
+```bash
+pptwise audit deck-dir/
+pptwise preview deck-dir/ --html
+pptwise render deck-dir/
+```
+
+交付前 `audit` 必须以 0 退出。文字压在照片背景上时加 `--pixels`。有 `pptwise_preview` 工具时优先使用。否则交付命令打印的 `preview.html` 路径，或运行 `pptwise serve deck-dir/ --no-open` 做实时浏览器审阅。把 `render` 打印的 `.pptx` 绝对路径报给用户。
+
+只有用户明确接受妥协时才使用 `--draft` 或 `--allow-dropped-content`。
+
+## 快速组件分派
+
+| 页面意图 | `kind` | 常用组件 |
+| --- | --- | --- |
+| 有顺序的论证 | `points` | `bullets`、`numbered_cards`、`paragraph` |
+| 可换序的并列项 | `list` | `row_cards`、`icon_cards`、`tag_row`、`people_cards` |
+| 并排看差异 | `comparison` | `comparison`、`image_compare`、`matrix`、`swot` |
+| 有方向的步骤或时间 | `process` | `steps`、`flowchart`、`timeline`、`roadmap`、`gantt`、`cycle` |
+| 一组数字的结构 | `data` | `chart`、`data_table`、`kpi_cards`、`heatmap`、`sankey` |
+| 画面本身就是信息 | `photo` | `image`、`image_grid`、`device_mockup` |
+| 作者自己的立论 | `statement` | `verdict_banner`、`callout`，也可以没有组件 |
+| 借别人之口 | `quote` | `blockquote` |
+| 一个数字就是全部 | `fact` | 单项 `kpi_cards`，也可以没有组件 |
+| 断言配一件展品 | `evidence` | `image`、`chart`、`data_table`、`code`、`device_mockup` |
+| 包含或层级 | `hierarchy` | `architecture`、`bmc`、`five_forces`、`rings` |
+
+## 规则
 
-- `references/spec.md` — 写 `deck.spec.json`、选页型、或做叙事访谈时
-- `references/layouts.md` — 钉 layout，包括高潮页、金句页、证据页稀排版式时
-- `references/components.md` — 碰到形态相近的组件，或要看字段与上下限时
-- `references/density.md` — 处理 pacing 预算、`beat`、容量警告、或 slide `decor` 时
-- `references/branding.md` — 抽取公司模板，或决定要不要写 `branding: "full"` 时
-- `references/images.md` — 声明资产、搜图库、或生图时
-- `references/validate.md` — 跑 assemble / validate / audit / preview / serve，或修订某一页时
+- 从不编辑或后处理生成的 `.pptx`。
+- 从不在作者内容中加入坐标、SVG、页面脸名或几何控制。
+- 面向用户的 deck 文案跟随用户语言。schema 键与枚举值使用英文。
+- 不声称 `chart` 或 `data_table` 的数字是原生 PowerPoint 数据对象。它们导出为可编辑的成组图形与文字。改数字要改源文件并重新渲染。
+- preview 全程只读。修订回到 `deck.spec.json`、`pages/*.json`、资产或绑定主题文件。
+
+## 何时阅读
+
+- `references/spec.md`：意图、叙事、主题创建、绑定、换绑、spec 与菜单错误。
+- `references/layouts.md`：在 11 个 `kind` 中选择。
+- `references/components.md`：组件归属、字段与相似项选择。
+- `references/density.md`：节奏、容量、独占页面组件与局部装饰。
+- `references/branding.md`：deck 品牌姿态、无框页面、logo 与品牌抽取。
+- `references/images.md`：图片资产、图库、生图，以及 `photo` 和 `evidence` 的边界。
+- `references/validate.md`：assemble、validate、audit、preview、serve、render 与修订循环。

package/skills/pptwise/references/branding.md

@@ -1,18 +1,44 @@
 # Branding posture
 
-Read this when extracting a company template, or deciding whether to write `branding: "full"`.
+Read this when deciding deck-level brand visibility, extracting an Office brand, or understanding why a page has no brand frame.
 
-A brand signal answers what the deck should look like, never how it should argue. Turning "this company's palette looks like a consulting firm" into a narrative is a guess wearing a fact's clothes, and it is how a deck ends up arguing in a shape nobody chose.
+A brand signal controls appearance. It does not choose the narrative or the page kind.
 
-## Brand themes — the user's own company template
+## Deck-level posture
 
-When the user hands over (or mentions having) a company template — a `.thmx` theme, `.potx` template, or any branded `.pptx` — extract its colors and fonts into a custom theme **before** picking a built-in theme in phase 2. Extraction runs entirely locally; the file never leaves the machine.
+`branding` has three values:
+
+| value | visible result |
+| --- | --- |
+| `full` | Keeps the logo throughout, draws the content-page footer and metadata, and allows confidentiality and date on cover and ending metadata rows. |
+| `cover-only` | Keeps the logo on cover and chapter pages. Content and ending pages drop the shared footer, metadata, and logo. |
+| `minimal` | Keeps the logo but drops the content-page footer rule and metadata. |
+
+Omitting `branding` is exactly the same as `cover-only`. Choose `full` only when every content page needs the organization footer, such as a confidential or controlled document.
+
+## Page-level silence
+
+The deck posture is only the broad permission. A face may carry the structural fact `branding: "none"`. A theme menu entry may also declare `brand: "none"`. Either one removes the whole shared brand fragment from that page, even when the deck says `full`.
+
+This is intentional for faces whose composition has no safe brand frame. It is not a missing logo bug and it must not be repaired with page content. Theme motifs are separate from branding and remain governed by the face and menu decoration rules.
+
+## Extract a complete v2 theme
+
+When the user supplies a `.thmx`, `.potx`, or branded `.pptx`, extract colors and fonts locally. Choose a donor whose menu fits the intended story because extraction copies that complete menu.
 
 ```bash
-pptwise brand extract corp-template.pptx -o deck-dir/theme.json --id acme
-pptwise render deck-dir/     # theme.json auto-loads; set "theme": "acme" in deck.spec.json
+pptwise brand extract corp-template.pptx \
+  -o deck-dir/theme.json \
+  --id acme \
+  --from consulting
 ```
 
-A `theme.json` sitting in the deck project directory auto-loads on every command (validate/render/audit/preview/serve) — reference its id from `deck.spec.json` and no flag is needed. For a single IR file, pass `--theme-file deck-dir/theme.json` instead (works on the same five commands). Loading enforces a contrast floor: a template whose text/background tones are too close is refused with the failing token and ratio named — relay that message and ask the user whether to adjust the extracted file's colors or fall back to a built-in theme.
+The output is a self-contained version 2 theme with style tokens, brand tokens, occasions, identity, and a complete menu. It has no base reference and inherits nothing at load time. Bind `acme` in `deck.spec.json`, then project commands resolve `deck-dir/theme.json` automatically.
+
+To compare the result against other named themes, run the fixed fitting-room sample from a directory where all names resolve:
+
+```bash
+pptwise theme try acme,consulting,swiss
+```
 
-Leave `branding` off the spec and the IR unless every content page needs the brand footer. Write `branding: "full"` whenever `meta.confidentiality` is `confidential` or `restricted`, or the file needs an organization colophon. Confidentiality and date then appear on the cover. They stay off every other posture.
+The loader checks contrast. If extraction produces unsafe text and background pairs, adjust the extracted theme or create a palette fork. Do not add ad hoc per-page color overrides.

package/skills/pptwise/references/branding.zh-CN.md

@@ -3,19 +3,47 @@ summary: 'skills/pptwise/references/branding.md 的中文阅读镜像'
 mirror_of: skills/pptwise/references/branding.md
 ---
 
-# Branding 姿态
+# 品牌姿态
 
-何时读：抽取公司模板，或决定要不要写 `branding: "full"` 时。
+何时读：决定整份 deck 的品牌可见度，抽取 Office 品牌，或理解某页为什么没有品牌框时。
 
-品牌信号回答的是这份 deck 长什么样，从来不回答它该怎么论证。把「这家公司的配色像咨询公司」读成一种叙事，是把推断当事实抬上来，一份没人选过的论证形状就是这样上台的。
+品牌信号只控制外观，不负责选择叙事或页面讲法。
 
-## 品牌主题——用户自己的公司模板
+## Deck 级姿态
 
-当用户递来（或提到手头有）公司模板——`.thmx` 主题、`.potx` 模板，或任何带品牌的 `.pptx`——先把它的配色和字体抽成自定义 theme，**再**进入阶段二的 theme 决策。抽取完全在本地进行，文件从不离开这台机器。
+`branding` 有三个值：
+
+| value | 可见结果 |
+| --- | --- |
+| `full` | 全程保留 logo，绘制内容页页脚与元数据，并允许封面和结尾的元数据行显示保密级别与日期。 |
+| `cover-only` | 只在封面与章节页保留 logo。内容页与结尾页不画共享页脚、元数据和 logo。 |
+| `minimal` | 保留 logo，但不画内容页页脚线与元数据。 |
+
+省略 `branding` 与显式写 `cover-only` 完全相同。只有每张内容页都需要机构页脚时才选 `full`，例如保密或受控文档。
+
+## 页面级静默
+
+Deck 姿态只是广义许可。一张脸可以把 `branding: "none"` 作为不可更改的结构事实。主题菜单条目也可以声明 `brand: "none"`。两者任意一个成立时，该页都不会出现共享品牌片段，即使 deck 选择了 `full`。
+
+这适用于构图本身没有安全品牌框的脸。它不是 logo 丢失，也不应通过页面内容补救。主题装饰与品牌相互独立，仍由脸与菜单的装饰规则决定。
+
+## 抽取完整 v2 主题
+
+用户提供 `.thmx`、`.potx` 或带品牌的 `.pptx` 时，在本机抽取颜色和字体。先选择一个菜单适合目标故事的供体，因为抽取结果会完整复制该菜单。
+
+```bash
+pptwise brand extract corp-template.pptx \
+  -o deck-dir/theme.json \
+  --id acme \
+  --from consulting
+```
+
+输出是自包含的版本 2 主题，包含样式 token、品牌 token、场合、个性强度和完整菜单。它没有基础引用，加载时也不继承任何东西。在 `deck.spec.json` 中绑定 `acme` 后，项目命令会自动解析 `deck-dir/theme.json`。
+
+要与其他命名主题比较，在所有名称都能解析的目录运行固定试衣样稿：
 
 ```bash
-pptwise brand extract corp-template.pptx -o deck-dir/theme.json --id acme
-pptwise render deck-dir/     # theme.json 自动装载。在 deck.spec.json 里写 "theme": "acme"
+pptwise theme try acme,consulting,swiss
 ```
 
-spec 和 IR 不要写 `branding`，除非每一页内容页都需要品牌页脚。`meta.confidentiality` 为 `confidential` 或 `restricted`，或文件需要机构落款时，写 `branding: "full"`。密级和日期随后出现在封面。其余姿态不出现。
+装载器会检查对比度。抽取结果若产生不安全的文字与背景组合，应调整主题或创建配色分叉，不要增加临时的单页颜色覆盖。

package/skills/pptwise/references/components.md

@@ -1,35 +1,65 @@
 # Component guide
 
-Read this when choosing among lookalike components, or when a component's fields and floor/ceiling matter.
-
-`steps` vs `flowchart` is the most common miss: if the edges never branch, it is `steps`. `flowchart` vs `cycle` is the next: does the process reach an endpoint, or does it loop back to its own start? Forcing a closed loop into `flowchart` makes the closing edge draw as a stray line/arc crossing the whole diagram — it isn't a diagram bug, it's the wrong component; reach for `cycle` the moment the last stage's arrow points back at the first. `roadmap` vs `gantt` is the next: `roadmap` groups workstreams into swimlanes with no shared numeric axis, `gantt` plots dated bars against one shared axis all items compare against. `pest` vs `swot` is the next: `pest` is external macro-environment factors only (no internal strengths/weaknesses axis), always the same four named categories — an internal-vs-external strategic assessment is still `swot`. `sankey` vs `flowchart`/funnel `chart` is the next: `sankey` conserves and splits a quantity across branching/merging paths (the band width itself carries meaning), `flowchart` is decision/process branching with no quantity, and a funnel `chart` only ever narrows in one line, never branches or merges. `data_table` vs `chart` vs `comparison` is the last: exact figures the audience reads row-by-row is `data_table`, a trend/comparison shape meant to be read at a glance is `chart`, qualitative side-by-side attributes with no exact figures is `comparison`.
-
-Inside `chart`, the subtype is the shape of the data. `scatter` when both axes are quantities (give each point an optional `size` to make it a bubble chart). `area` when a line's filled region should read as accumulation or volume. `donut` for a part-to-whole share, with an optional total printed big in its center (`center_total: true`). `gauge` for one value's progress toward a target. `gauge` vs `kpi_cards` is the one to get right: a `gauge` is a single completion metric drawn as a filled half-ring (62% of goal), while `kpi_cards` is several independent headline numbers set side by side, so never build a row of gauges where `kpi_cards` belongs. `scatter` vs `line`: `scatter` needs a numeric x (a real coordinate on both axes), a category-labelled x-axis is still `line`.
-
-`architecture`'s `layers` array paints top-to-bottom by default (`layers[0]` is the topmost band) — the natural order for a system stack authored top-down (presentation layer first, infrastructure last). Author a bottom-up narrative (a maturity ladder, a foundation-first capability model) in its own natural low-to-high order and set `direction: "bottom_up"` on the component to paint `layers[0]` at the bottom instead — do not hand-reverse the array to fake it, the field exists precisely so the array stays in narrative order.
-
-`swot`/`bmc`/`waterfall`/`gantt`/`pest`/`five_forces`/`heatmap`/`sankey` are *full-body*: each fills the entire slide and must be the slide's only component — see `references/density.md`.
-
-### Cycles vs. flowcharts
-
-Both draw a sequence of stages connected by arrows — the split is whether the process has an endpoint. `flowchart` is for a process that starts somewhere and finishes somewhere, even if it branches on the way; forcing a closed loop through it means adding an edge from the last node back to the first, and `flowchart`'s layout engine has no notion that this edge is special — it draws as a long stray line or arc crossing the whole diagram, reading like a mistake, not "this repeats". `cycle` is for a process that has no endpoint: it always returns to its own start (PDCA, a product lifecycle, a flywheel, a seasonal cycle, "design → build → review → design"). The test: does the last stage's arrow point at something new, or at the first stage again? Pointing at the first stage again is `cycle`, full stop.
-
-Fields: `items` (3-8 entries, each a required `label` and an optional `description`), an optional overall `title`. `cycle` accepts no `direction` field (stages always run clockwise — write `items` in that reading order) and no center-text slot; keep the diagram to the stages themselves and put anything else in the surrounding page text. 3 is a hard floor (2 stages can't visually close into a ring — use `flowchart` or `steps` instead) and 8 is a hard ceiling (a 9th node crowds the ring past legible size on a 1280x720 slide — split into multiple `cycle` slides instead of cramming more stages onto one ring).
-
-### Device mockups vs. plain images
-
-`device_mockup` frames an asset inside a themed browser-window or device frame instead of a bare bordered rect — it exists for exactly one job: a screenshot that has to be read as "a real product, actually running", not "a picture on a slide". Reach for it when the content is a screenshot of software/an app/a dashboard and the page's own point is that this product is real and working today. Keep plain `image` for everything else — ordinary photos, diagrams, illustrations, or a screenshot used only to illustrate a point in passing, not to assert "this is live". Overusing `device_mockup` on content that isn't actually a product screenshot reads as a strange decorative border, not evidence.
-
-Fields: `device` (`"browser"` or `"phone"`, required — pptwise doesn't guess), `asset_id` (same semantics as `image`), an optional `caption`, and — `browser` only — an optional `url` that renders as the address-bar text (the single strongest "this is really running in a browser" signal available; a `phone` mockup has no address bar, so `validate` hard-rejects `url` set on one). The screen always crops to fill the frame (cover) — there's no `fit` choice, unlike `image`: a real device's screen fills edge to edge. No other decoration options exist on purpose — no tilt/perspective, no dark-frame toggle, no side-by-side multi-device layout; the theme's own tokens pick the frame colors.
-
-### People rosters vs. row/icon cards
-
-The test is simple: is every item a *person*? A team roster, a speaker lineup, a judging panel, an author list — `people_cards` lays 2-12 people out on an equal-weight card grid, each card a deterministic initials badge (derived from the person's `name`, no photo asset needed) plus name and optional `role`/`org`. Keep `row_cards`/`icon_cards` for non-person enumerations — features, milestones, product topics — even when they happen to carry the same name/description-shaped fields; those two cap out at 6 items each, `people_cards` at 12, so a list of people that would blow through that cap (a 9-speaker conference lineup, say) is the clearest sign it belongs on `people_cards` instead of forced into two unlabeled row_cards pages.
-
-Fields: `people` (2-12 entries, each a required `name` and optional `role`/`org`), an optional overall `title`. The initials badge is a pure function of `name`: a Latin name takes the first letter of its first two words ("Sarah Chen" → "SC"), a single Latin word takes its own first two letters, and a CJK name takes only its first character — the surname — never two ("王小明" → "王"). There is no photo field on purpose: a slide with real headshots already has `image_grid`, and `people_cards`'s entire reason to exist is the zero-asset initials badge. 2 is a hard floor (a single person's bio doesn't need a grid — use `callout` or plain text) and 12 is a hard ceiling (a larger roster splits across multiple `people_cards` slides instead of cramming a 13th+ card onto one grid).
-
-### Tag rows vs. bullets and cards
-
-A row of short parallel labels — a technology stack, a capability or skill set, a keyword set, the certifications a vendor holds — is `tag_row`, not `bullets` or `row_cards`. The test is whether every item is a short *label* (a name) rather than a sentence or a described item. `tag_row` lays 2-16 short labels out as a wrapping row of capsule pills, each label measured with its real per-character width so a CJK/Latin-mixed tag wraps correctly, with an optional `emphasis: "first"` that draws the first tag in the theme accent as the primary one among the rest. Keep `bullets` for a real prose list (items that read as sentences or clauses), and `row_cards`/`icon_cards` for items that each carry their own descriptive text — a tag has none.
-
-Fields: `items` (2-16 short strings, each ≤24 chars — a hard cap, because a tag is a label and not a sentence; over it, `validate` points you at `bullets`/`row_cards`), an optional overall `title`, and an optional `emphasis` (`"first"` or `"none"`, default `"none"`). 2 is a hard floor (a single label isn't a row — put it in the heading, a `callout`, or a `verdict_banner`) and 16 is a hard ceiling (past 16 the row reads as an unsorted keyword dump — split into multiple `tag_row` slides or group the tags into labeled sets).
+Read this when choosing the typed content units that fill a page after its theme and `kind` are fixed.
+
+## Naming
+
+The component type is `blockquote`. The page kind is `quote`. Use a `blockquote` for attributed prose inside a `quote` page or as supporting evidence elsewhere. Never write a component type named `quote`.
+
+## Semantic homes
+
+The table gives each component's normal kind home. A component may serve more than one kind when the page's semantic move remains honest. The kind names what the page is doing. The component names the content unit that does the work.
+
+| component | normal kind ownership |
+| --- | --- |
+| `bullets` | `points`, `list` |
+| `paragraph` | `points`, `statement` |
+| `blockquote` | `quote` |
+| `callout` | `points`, `statement`, `evidence` |
+| `code` | `points`, `evidence` |
+| `kpi_cards` | `data`, `fact` |
+| `chart` | `data`, `evidence` |
+| `flowchart` | `process` |
+| `architecture` | `hierarchy` |
+| `timeline` | `process` |
+| `comparison` | `comparison` |
+| `icon_cards` | `list`, `points` |
+| `row_cards` | `list`, `points` |
+| `steps` | `process` |
+| `rings` | `data`, `hierarchy` |
+| `numbered_cards` | `points`, `process` |
+| `roadmap` | `process` |
+| `matrix` | `comparison`, `hierarchy` |
+| `insight_panel` | `points`, `evidence` |
+| `verdict_banner` | `statement`, `points` |
+| `citation` | `quote`, `evidence` |
+| `image` | `photo`, `evidence` |
+| `image_grid` | `photo`, `list` |
+| `image_compare` | `comparison`, `evidence` |
+| `swot` | `comparison` |
+| `bmc` | `hierarchy` |
+| `waterfall` | `data`, `process` |
+| `gantt` | `process` |
+| `pest` | `comparison` |
+| `five_forces` | `hierarchy` |
+| `heatmap` | `data`, `comparison` |
+| `sankey` | `data`, `process` |
+| `data_table` | `data`, `evidence` |
+| `device_mockup` | `photo`, `evidence` |
+| `cycle` | `process` |
+| `people_cards` | `list` |
+| `tag_row` | `list` |
+
+## Lookalikes
+
+- Use `steps` for a linear sequence, `flowchart` for branching decisions, and `cycle` when the final stage returns to the first.
+- Use `roadmap` for workstreams without a shared numeric axis. Use `gantt` for dated bars on one shared axis.
+- Use `pest` for the four external macro factors. Use `swot` for internal and external strategic assessment.
+- Use `sankey` when band width carries a conserved quantity through branches and merges. Use `flowchart` when branches carry decisions rather than quantities.
+- Use `data_table` when exact values must be read row by row. Use `chart` when the audience should grasp a numeric shape at a glance. Use `comparison` for qualitative attributes.
+- Use `gauge` inside `chart` for one value against one target. Use `kpi_cards` for several independent headline values.
+- Use `tag_row` only for short labels. Use `bullets` for prose items and cards for items with their own description.
+
+`architecture.layers` paints top to bottom by default. Set `direction: "bottom_up"` when the authored order should begin at the foundation. Keep the array in narrative order.
+
+`swot`, `bmc`, `waterfall`, `gantt`, `pest`, `five_forces`, `heatmap`, and `sankey` are full-body components. Each must be the page's only component.

package/skills/pptwise/references/components.zh-CN.md

@@ -5,36 +5,66 @@ mirror_of: skills/pptwise/references/components.md
 
 # 组件指南
 
-何时读：碰到形态相近的组件，或要看字段与上下限时。
-
-`steps` 和 `flowchart` 是最常见的混用：只要分支路径从不出现，就是 `steps`。`flowchart` 和 `cycle` 是次常见的：这个流程最终走到一个终点，还是转回自己的起点？把一个闭环硬塞进 `flowchart`，那条收尾的回边会被画成一条横跨整张图的迷路线段或大弧线——这不是画图的 bug，是选错了 component；只要最后一个阶段的箭头是指回第一个阶段，就该换成 `cycle`。`roadmap` 和 `gantt` 是再下一个：`roadmap` 把多条工作线分组进泳道，没有共享的数值坐标轴，`gantt` 则把带日期的条形画在一根所有条目共同比对的共享坐标轴上。`pest` 和 `swot` 是再下一个：`pest` 只看外部宏观环境因素（没有内部优势/劣势这条轴），永远是同样命名的四个类别——一份内部对外部的战略评估仍然是 `swot`。`sankey` 和 `flowchart`/funnel `chart` 是再下一个：`sankey` 在分支/汇合的路径上守恒并拆分一个数量（带宽本身就承载意义），`flowchart` 是没有数量含义的决策/流程分支，funnel `chart` 则永远只沿一条线收窄，从不分支也不汇合。`data_table` 和 `chart` 和 `comparison` 是最后一组：受众要逐行读的精确数字用 `data_table`，一眼看出趋势/对比形态的用 `chart`，没有精确数字、只做定性并排属性对比的用 `comparison`。
-
-`chart` 内部，子型就是数据的形态。两根轴都是数值量时用 `scatter`（给每个点加可选 `size` 就成了气泡图）。线下方的填充区要读作累积或体量时用 `area`。部分对整体的占比用 `donut`，中心可选把总值放大居中（`center_total: true`）。单个指标对目标的完成度用 `gauge`。`gauge` 和 `kpi_cards` 最要分清：`gauge` 是单个完成度指标，画成一段填充的半环（例如 62% 达标），`kpi_cards` 则是多个各自独立的头条数字并排陈列，所以别在该用 `kpi_cards` 的地方摆一排 gauge。`scatter` 和 `line` 的区别：`scatter` 需要数值 x（两根轴都是真实坐标），x 轴是类目标签的仍然是 `line`。
-
-`architecture` 的 `layers` 数组默认从上到下画（`layers[0]` 是最顶层的那条带）——这是自顶向下撰写系统分层（表现层在前、基础设施在后）的自然顺序。如果是一个自底向上的叙事（成熟度阶梯、基础优先的能力模型），就按它自己从低到高的自然顺序撰写，并在 component 上设 `direction: "bottom_up"`，让 `layers[0]` 改画在最底部——不要手动把数组倒过来伪造这个效果，这个字段存在的意义正是让数组始终保持叙事顺序。
-
-`swot`/`bmc`/`waterfall`/`gantt`/`pest`/`five_forces`/`heatmap`/`sankey` 是「满幅」（full-body）组件：各自占满整张 slide，且必须是该 slide 唯一的 component——见 `references/density.md`。
-
-### cycle vs. flowchart
-
-两者都是用箭头把一串阶段连起来，区别在于这个流程有没有终点。`flowchart` 面向一个从某处开始、到某处结束的流程，哪怕中途有分支；硬要用它画一个闭环，做法只能是从最后一个节点拉一条边指回第一个节点，而 `flowchart` 的排布引擎并不知道这条边有什么特殊——画出来就是一条横跨整张图的迷路线段或大弧线，读起来像画错了，不像「这个流程会重复」。`cycle` 面向没有终点、总会转回自己起点的流程（PDCA、产品生命周期、飞轮、季节性循环、「设计 → 构建 → 复盘 → 设计」）。判断标准很直接：最后一个阶段的箭头，指向的是一个新东西，还是指回第一个阶段？指回第一个阶段，就用 `cycle`，不用再犹豫。
-
-字段：`items`（3-8 项，每项必填 `label`，可选 `description`），可选的整体 `title`。`cycle` 不接受 `direction` 字段（阶段固定按顺时针排布，`items` 就按这个阅读顺序撰写），也没有中心文字槽——把内容留给阶段本身，别的信息放进 slide 周围的文字里。3 是硬下限（2 个阶段视觉上闭不成一个环，该用 `flowchart` 或 `steps`），8 是硬上限（第 9 个节点会把环挤到 1280x720 slide 上不够清楚的程度，超过就拆成多张 `cycle` slide，不要硬塞进一个环里）。
-
-### 设备样机 vs. 普通图片
-
-`device_mockup` 把一份资产框进一个主题化的浏览器窗口或手机机身，而不是一个普通带边框的矩形——它只为一件事存在：一张截图需要被读成「一个真实的产品，正在运行」，而不是「slide 上的一张图」。内容是软件/App/仪表盘的截图，且这一页的论点就是「这个产品是真的、正在正常工作」时用它。除此之外——普通照片、示意图、插画,或者只是顺带用截图说明一个观点而不是断言「这在真实运行」——都用 `image`。把不是产品截图的内容硬套 `device_mockup`，读出来只是个奇怪的装饰边框，不是证据。
-
-字段：`device`（`"browser"` 或 `"phone"`，必填，pptwise 不猜）、`asset_id`（语义同 `image`）、可选 `caption`，以及——仅 `browser` 款——可选的 `url`，渲染为地址栏文字（这是「这是真的在浏览器里跑」这件事上最强的信号）。`phone` 款没有地址栏，`validate` 会硬拒绝在 `phone` 上设置 `url`。屏幕内容永远铺满裁切（cover）——不像 `image` 那样有 `fit` 可选：真实设备的屏幕就是边到边铺满的。故意不提供其它装饰选项——没有倾斜/透视、没有暗色窗框开关、没有多设备并排——窗框配色完全由主题 token 决定。
-
-### 人员卡片 vs. row/icon cards
-
-判据很直接：条目是不是「人」？团队名单、讲者阵容、评委阵容、作者名单，用 `people_cards`：2-12 人的等重卡片网格，每张卡是一个由 `name` 派生的确定性 initials 徽章（不需要照片资源），加姓名和可选的 `role`/`org`。非人条目仍用 `row_cards`/`icon_cards`，哪怕字段形状很像。这两个组件上限都是 6 项，`people_cards` 是 12 项：一份会撑爆 6 上限的人员名单（比如 9 位讲者的大会阵容），就是该换 `people_cards`、而不是硬拆成两页无标签 `row_cards` 的最清楚信号。
-
-字段：`people`（2-12 项，每项必填 `name`，可选 `role`/`org`），可选的整体 `title`。initials 徽章是 `name` 的纯函数：拉丁名取首两词的首字母（"Sarah Chen" → "SC"），单个拉丁词取它自己的前两个字母，CJK 名只取首字符，也就是姓（"王小明" → "王"），不取两个字。这个组件故意没有照片字段：真有头像照片的场景，`image_grid` 已经够用，`people_cards` 存在的全部理由就是这个零资产依赖的 initials 徽章。2 是硬下限（一个人的简介用不上网格，改用 `callout` 或纯文字），12 是硬上限（更大的名单拆成多张 `people_cards` slide，不要硬塞第 13 张卡进一个网格）。
-
-### 标签行 vs. bullets/卡片
-
-一行短平行标签——技术栈、能力或技能清单、关键词、供应商持有的资质——用 `tag_row`，不是 `bullets` 或 `row_cards`。判据是每一项是不是一个短*标签*（一个名词），而不是一句话或一个带描述的条目。`tag_row` 把 2-16 个短标签排成一行会自动换行的胶囊，每个标签按其真实的逐字符宽度测量，所以 CJK/拉丁混排的标签也能正确换行，可选的 `emphasis: "first"` 把首个标签画成主题 accent 色，作为其余标签中的主标签。真正的正文列表（读起来是句子或从句的条目）仍用 `bullets`，每项自带描述文字的条目用 `row_cards`/`icon_cards`——标签没有描述。
-
-字段：`items`（2-16 个短字符串，每个 ≤24 字符——这是硬上限，因为标签是标签、不是句子；超了 `validate` 会把你指向 `bullets`/`row_cards`），可选的整体 `title`，可选的 `emphasis`（`"first"` 或 `"none"`，默认 `"none"`）。2 是硬下限（单个标签不成行——放进标题、`callout` 或 `verdict_banner`），16 是硬上限（超过 16 个后这行读起来就是一堆没排序的关键词——拆成多张 `tag_row` slide，或把标签分成带小标题的组）。
+何时读：主题与 `kind` 已经确定，需要选择填充页面的类型化内容单元时。
+
+## 命名
+
+组件类型叫 `blockquote`。页面讲法叫 `quote`。有归属的引文放进 `blockquote`，它既可以出现在 `quote` 页面，也可以作为其他页面的证据。不要写名为 `quote` 的组件类型。
+
+## 语义归属
+
+下表给出每种组件通常归属的 kind。只要页面的语义动作仍然准确，一个组件可以服务多个 kind。kind 命名页面在做什么，组件命名完成这件事的内容单元。
+
+| component | 通常归属的 kind |
+| --- | --- |
+| `bullets` | `points`, `list` |
+| `paragraph` | `points`, `statement` |
+| `blockquote` | `quote` |
+| `callout` | `points`, `statement`, `evidence` |
+| `code` | `points`, `evidence` |
+| `kpi_cards` | `data`, `fact` |
+| `chart` | `data`, `evidence` |
+| `flowchart` | `process` |
+| `architecture` | `hierarchy` |
+| `timeline` | `process` |
+| `comparison` | `comparison` |
+| `icon_cards` | `list`, `points` |
+| `row_cards` | `list`, `points` |
+| `steps` | `process` |
+| `rings` | `data`, `hierarchy` |
+| `numbered_cards` | `points`, `process` |
+| `roadmap` | `process` |
+| `matrix` | `comparison`, `hierarchy` |
+| `insight_panel` | `points`, `evidence` |
+| `verdict_banner` | `statement`, `points` |
+| `citation` | `quote`, `evidence` |
+| `image` | `photo`, `evidence` |
+| `image_grid` | `photo`, `list` |
+| `image_compare` | `comparison`, `evidence` |
+| `swot` | `comparison` |
+| `bmc` | `hierarchy` |
+| `waterfall` | `data`, `process` |
+| `gantt` | `process` |
+| `pest` | `comparison` |
+| `five_forces` | `hierarchy` |
+| `heatmap` | `data`, `comparison` |
+| `sankey` | `data`, `process` |
+| `data_table` | `data`, `evidence` |
+| `device_mockup` | `photo`, `evidence` |
+| `cycle` | `process` |
+| `people_cards` | `list` |
+| `tag_row` | `list` |
+
+## 相近组件
+
+- 直线步骤用 `steps`，有决策分支用 `flowchart`，末段回到首段用 `cycle`。
+- 没有共享数值轴的工作线用 `roadmap`，在同一日期轴上比较条形用 `gantt`。
+- 四类外部宏观因素用 `pest`，同时评估内外部战略条件用 `swot`。
+- 带宽承载守恒数量并发生分支与汇合时用 `sankey`，分支表达决策而非数量时用 `flowchart`。
+- 需要逐行读取精确值时用 `data_table`，需要一眼看懂数值形态时用 `chart`，定性属性对照用 `comparison`。
+- 一个值对一个目标用 `chart` 内的 `gauge`，多个独立头条数字用 `kpi_cards`。
+- `tag_row` 只放短标签。句子式条目用 `bullets`，每项都有说明文字时用卡片组件。
+
+`architecture.layers` 默认从上向下绘制。作者按基座优先的顺序写作时，设置 `direction: "bottom_up"`，不要手工倒置数组。
+
+`swot`、`bmc`、`waterfall`、`gantt`、`pest`、`five_forces`、`heatmap` 与 `sankey` 是全页组件。它们必须独占页面。