# Branding posture

Read this when deciding deck-level brand visibility, extracting an Office brand, or understanding why a page has no brand frame.

A brand signal controls appearance. It does not choose the narrative or the page kind.

## Deck-level posture

`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 \
  --from brief
```

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,brief,swiss
```

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.

---
summary: 'skills/pptwise/references/branding.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/branding.md
---

# 品牌姿态

何时读：决定整份 deck 的品牌可见度，抽取 Office 品牌，或理解某页为什么没有品牌框时。

品牌信号只控制外观，不负责选择叙事或页面讲法。

## Deck 级姿态

`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 brief
```

输出是自包含的版本 2 主题，包含样式 token、品牌 token、场合、个性强度和完整菜单。它没有基础引用，加载时也不继承任何东西。在 `deck.spec.json` 中绑定 `acme` 后，项目命令会自动解析 `deck-dir/theme.json`。

要与其他命名主题比较，在所有名称都能解析的目录运行固定试衣样稿：

```bash
pptwise theme try acme,brief,swiss
```

装载器会检查对比度。抽取结果若产生不安全的文字与背景组合，应调整主题或创建配色分叉，不要增加临时的单页颜色覆盖。

# Component guide

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` |
| `image` | `photo`, `evidence` |
| `image_grid` | `photo`, `list` |
| `image_compare` | `comparison`, `evidence` |
| `logo_wall` | `list` |
| `product_cards` | `list`, `comparison` |
| `quote_wall` | `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` |
| `hub_spoke` | `hierarchy` |
| `progress_donuts` | `data` |
| `staircase` | `process` |
| `chevron_process` | `process` |
| `swimlane` | `process` |
| `journey_map` | `process` |
| `decision_tree` | `hierarchy`, `process` |
| `from_to` | `comparison` |
| `org_tree` | `hierarchy` |
| `issue_tree` | `hierarchy` |
| `pyramid` | `hierarchy` |
| `iceberg` | `hierarchy`, `statement` |
| `pillar_model` | `hierarchy` |
| `value_chain` | `process` |
| `harvey_balls` | `data`, `comparison` |
| `scorecard` | `data`, `comparison` |
| `pictogram` | `data`, `fact` |
| `word_cloud` | `data`, `list` |
| `venn` | `comparison` |
| `fishbone` | `hierarchy` |
| `positioning_map` | `comparison` |
| `concept_equation` | `points`, `statement` |
| `segmented_wheel` | `hierarchy`, `list` |
| `pros_cons` | `comparison` |

## Lookalikes

- Use `org_tree` when a line means reports to, `issue_tree` when it means breaks down into, and `flowchart` when a branch is a decision taken on a condition.
- Use `pyramid` when each level supports the one above — a claim over its evidence, a rank over the ranks that hold it. Use `rings` when the levels nest one inside another, `architecture` when each level holds the parts of a system, and `steps` when they run in order.
- Use `iceberg` when the argument is that the stated reason is the small part. Use `comparison` when the two sets are peers being weighed.
- Use `pillar_model` when a goal only stands if every pillar stands. Use `icon_cards` when the items are merely parallel.
- Use `value_chain` when the question is which link makes the value. Use `steps` when only the order matters and `sankey` when a quantity splits between stages.
- Use `steps` for a linear sequence, `flowchart` for branching decisions, and `cycle` when the final stage returns to the first.
- Use `chevron_process` when work passes through every stage in order and the handover between them is the point. Use `staircase` when the stages climb in degree rather than follow one another, and `swimlane` when who does each step is part of the argument.
- Use `journey_map` when each stage carries a 1-5 feeling and the low point is the argument. Use `chevron_process` when no feeling is attached to the stages.
- Use `decision_tree` when a condition sends the reader down one of two or three paths and each ending has its own cost. Use `flowchart` for one thread with decisions along it.
- Use `from_to` when the same measures carry a value in both states and the size of the move is the point. Use `comparison` when the two sides are different subjects rather than one subject twice.
- Use `hub_spoke` for one central concept with unordered peer elements attached to it. Use `cycle` when they close a loop and `rings` when they nest inside one another.
- Use `venn` when two or three sets overlap and the shared region is the point. Use `comparison` when the sides are weighed against each other and `rings` when each set contains the next.
- Use `fishbone` when the result is known and the page sorts the causes behind it into categories. Use `flowchart` when the boxes lead somewhere.
- Use `positioning_map` when where each subject sits on two continuous dimensions is the argument. Use `matrix` when the two dimensions are categories rather than scales.
- Use `concept_equation` when two or three things together produce a fourth and the addition is the argument. Use `icon_cards` when the items produce nothing between them.
- Use `segmented_wheel` when four to eight equal parts together make up one whole. Use `cycle` when the last part returns to the first and `pie` inside `chart` when the parts are unequal shares.
- Use `pros_cons` when both columns argue about the same proposal and the page has to land on a verdict. Use `comparison` when the columns are two different subjects.
- 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 an amount through branches and merges, and a gap should show where a flow is not accounted for. 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 `progress_donuts` for several completion rates and `kpi_cards` for one or more independent headline values.

- Use `logo_wall` when a set of organization names is itself the claim and every name carries the same weight. Use `image_grid` for photographs and `row_cards` when each name needs a line of its own.

- Use `product_cards` when each item is a thing someone could buy and has its own picture. Use `comparison` when options are weighed on shared attributes and `data_table` when specifications must be read row by row.

- Use `quote_wall` when several people saying the same thing is the argument. Use `blockquote` for one remark set at full size and `people_cards` when the page is about who the speakers are.

- Use `harvey_balls` when options are judged on shared criteria in five steps and the reader should spot the weak column. Use `heatmap` when the values are continuous numbers whose spread across two dimensions is the message, `data_table` when any figure must be read exactly, and `comparison` for qualitative attributes with no shared scale.

- Use `scorecard` when each figure is judged against a target and carries a verdict. Use `data_table` when the numbers are reported without one.

- Use `pictogram` to land a rate as a countable number of people. Use `progress_donuts` when the rate itself is the subject.

- Use `word_cloud` when the point is which words keep coming back. Use `chart` when the counts must be read and `tag_row` for a line of labels that carry no weight against each other.

`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`, `sankey`, `harvey_balls`, `scorecard`, `pictogram`, and `word_cloud` are full-body components. Each must be the page's only component.

---
summary: 'skills/pptwise/references/components.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/components.md
---

# 组件指南

何时读：主题与 `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` |
| `image` | `photo`, `evidence` |
| `image_grid` | `photo`, `list` |
| `image_compare` | `comparison`, `evidence` |
| `logo_wall` | `list` |
| `product_cards` | `list`, `comparison` |
| `quote_wall` | `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` |
| `hub_spoke` | `hierarchy` |
| `progress_donuts` | `data` |
| `staircase` | `process` |
| `chevron_process` | `process` |
| `swimlane` | `process` |
| `journey_map` | `process` |
| `decision_tree` | `hierarchy`, `process` |
| `from_to` | `comparison` |
| `org_tree` | `hierarchy` |
| `issue_tree` | `hierarchy` |
| `pyramid` | `hierarchy` |
| `iceberg` | `hierarchy`, `statement` |
| `pillar_model` | `hierarchy` |
| `value_chain` | `process` |
| `harvey_balls` | `data`, `comparison` |
| `scorecard` | `data`, `comparison` |
| `pictogram` | `data`, `fact` |
| `word_cloud` | `data`, `list` |
| `venn` | `comparison` |
| `fishbone` | `hierarchy` |
| `positioning_map` | `comparison` |
| `concept_equation` | `points`、`statement` |
| `segmented_wheel` | `hierarchy`、`list` |
| `pros_cons` | `comparison` |

## 相近组件

- 线的含义是「向谁汇报」用 `org_tree`，是「拆解成」用 `issue_tree`，是按条件做判断用 `flowchart`。
- 上层由下层支撑（结论压在论据上、高一级压在低一级上）用 `pyramid`，同心包含用 `rings`，每层装的是系统构件用 `architecture`，有先后顺序用 `steps`。
- 要说「说得出口的只是一小部分」用 `iceberg`，两组东西平级掂量用 `comparison`。
- 目标要靠几件事同时立住才成立用 `pillar_model`，只是并列几项用 `icon_cards`。
- 问「价值出在哪一环」用 `value_chain`，只讲先后用 `steps`，讲数量的分合用 `sankey`。
- 直线步骤用 `steps`，有决策分支用 `flowchart`，末段回到首段用 `cycle`。
- 工作必须依次穿过每个环节、交接本身是重点时用 `chevron_process`；环节之间差的是程度而不是先后用 `staircase`；每一步归谁做也是论点用 `swimlane`。
- 每个阶段都带 1-5 的情绪分、最低点就是论点时用 `journey_map`；阶段不带情绪用 `chevron_process`。
- 一个条件把读者送上两三条路之一、每个结局各有代价时用 `decision_tree`；一条主线上带若干决策用 `flowchart`。
- 同一批指标在两个状态下都有值、移动幅度就是论点时用 `from_to`；两边是不同主体而不是同一主体的两次用 `comparison`。
- 一个中心概念带一组无序并列要素用 `hub_spoke`，要素闭环用 `cycle`，层层包含用 `rings`。
- 两三个集合互相重叠、重叠处才是结论时用 `venn`，两边互相权衡用 `comparison`，层层包含用 `rings`。
- 结果已经发生、页面在给原因分类时用 `fishbone`，方框通向某个终点时用 `flowchart`。
- 每个主体在两个连续维度上的位置就是论据时用 `positioning_map`，两个维度是分类而不是刻度时用 `matrix`。
- 两三个要素加起来得到一个结果、相加本身就是论证时用 `concept_equation`，条目之间不产生结果时用 `icon_cards`。
- 四到八块对等的部分合起来正好是一个整体时用 `segmented_wheel`，末段回到首段用 `cycle`，各块占比不等用 `chart` 内的 `pie`。
- 两栏说的是同一个方案的正反两面、最后要落一句结论时用 `pros_cons`，两栏是两个不同对象时用 `comparison`。
- 没有共享数值轴的工作线用 `roadmap`，在同一日期轴上比较条形用 `gantt`。
- 四类外部宏观因素用 `pest`，同时评估内外部战略条件用 `swot`。
- 带宽承载数量并发生分支与汇合时用 `sankey`：宽度即论据，缺口显示未核算的流量。分支表达决策而非数量时用 `flowchart`。
- 需要逐行读取精确值时用 `data_table`，需要一眼看懂数值形态时用 `chart`，定性属性对照用 `comparison`。
- 一个值对一个目标用 `chart` 内的 `gauge`，多个完成度百分比用 `progress_donuts`，一个或多个独立头条数字用 `kpi_cards`。

- `logo_wall` 用在一串组织名字本身就是论据、每个名字权重相同时。照片用 `image_grid`，每个名字都要配一句说明用 `row_cards`。

- `product_cards` 用在每一项都是可购买的东西、各自带一张图时。同一组属性横向权衡用 `comparison`，参数要逐行读用 `data_table`。

- `quote_wall` 用在几个人说同一件事本身就是论据时。一个人说一句、要放大到整页用 `blockquote`，页面讲的是这些人是谁用 `people_cards`。

- 几个方案在同一组标准上按五档打分、要一眼看出短板时用 `harvey_balls`。数值是连续量、要看它在两个维度上的分布时用 `heatmap`，任何数字要读准时用 `data_table`，没有共同刻度的定性属性对照用 `comparison`。

- 每个数字都对着一个目标、还要给结论时用 `scorecard`。只报数字不下结论用 `data_table`。

- 要把比例还原成数得过来的人时用 `pictogram`。比例本身是主角时用 `progress_donuts`。

- 重点是「哪些词反复出现」时用 `word_cloud`。次数要被读出来时用 `chart`，一排等重短标签用 `tag_row`。

`architecture.layers` 默认从上向下绘制。作者按基座优先的顺序写作时，设置 `direction: "bottom_up"`，不要手工倒置数组。

`swot`、`bmc`、`waterfall`、`gantt`、`pest`、`five_forces`、`heatmap`、`sankey`、`harvey_balls`、`scorecard`、`pictogram` 与 `word_cloud` 是全页组件。它们必须独占页面。

# Density and decoration

Read this when writing to pacing budgets, fitting the bound face, or deciding whether a page needs local decoration.

## Two capacity limits

Every content page has two independent limits. Narrative pacing sets an editorial budget. The face selected by the bound theme menu sets a physical body capacity. The effective component limit is the smaller value.

| pacing | body baseline | components | bullet items | width units per bullet |
| --- | ---: | ---: | ---: | ---: |
| `dense` | 24px | 5 | 6 | 27 |
| `balanced` | 24px | 4 | 5 | 25 |
| `spacious` | 32px | 3 | 4 | 22 |

`validate` reports the effective limit for the actual theme and kind. Editorial excess is normally a warning. Render-safety limits and content loss remain hard errors. Shorten or split a page instead of hiding overflow.

`spacious` means fewer elements at a larger body size. It does not mean the same content compressed into a cleaner-looking page. Keep headings assertive and keep bullet items near two lines.

Three consecutive content pages with the same kind produce a spec advisory. Repetition can be correct, but confirm that the story truly calls for the same semantic move three times.

Twelve components own the whole body: `swot`, `bmc`, `waterfall`, `gantt`, `pest`, `five_forces`, `heatmap`, `sankey`, `harvey_balls`, `scorecard`, `pictogram`, and `word_cloud`. Each must be the page's only component.

## Decoration ownership

Decoration resolves in this order:

1. A face with structural `suppressMotif: true` never receives a theme motif.
2. Otherwise a menu entry may choose `decor.kind: "silent"` or select another motif.
3. With no menu opinion, the theme's ordinary motif paints.

The face's structural silence cannot be undone by a menu. A page-level `decor` is a controlled local primitive such as a rule, tag, quote mark, dots, or large number. Use it only when the page meaning needs that accent. It does not replace the theme menu and should not be stamped across the deck.

---
summary: 'skills/pptwise/references/density.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/density.md
---

# 密度与装饰

何时读：按 pacing 预算写作，适配已绑定的脸，或判断页面是否需要局部装饰时。

## 两种容量限制

每张内容页同时受两种独立限制。叙事 pacing 给出编辑预算，主题菜单选中的脸给出正文物理容量。实际组件上限取两者中的较小值。

| pacing | 正文基线 | components | bullet 条目 | 每条宽度单位 |
| --- | ---: | ---: | ---: | ---: |
| `dense` | 24px | 5 | 6 | 27 |
| `balanced` | 24px | 4 | 5 | 25 |
| `spacious` | 32px | 3 | 4 | 22 |

`validate` 会按实际主题与 kind 报出有效上限。超出编辑预算通常是警告，越过渲染安全线或造成内容丢失仍然是硬错误。应该缩短或拆页，不要隐藏溢出。

`spacious` 表示元素更少且正文字号更大，不是把同样多的内容压缩进一张看似更干净的页面。标题要短而有判断，bullet 条目尽量控制在两行附近。

连续三张内容页使用相同 kind 时，spec 会给出提示。重复可能正确，但应确认故事确实需要连续三次相同的语义动作。

十二种组件独占整个正文区：`swot`、`bmc`、`waterfall`、`gantt`、`pest`、`five_forces`、`heatmap`、`sankey`、`harvey_balls`、`scorecard`、`pictogram` 与 `word_cloud`。每种都必须是该页唯一的组件。

## 装饰归属

装饰按以下顺序解析：

1. 一张脸若把 `suppressMotif: true` 声明为结构事实，就永远不接收主题 motif。
2. 其他脸可以由菜单条目选择 `decor.kind: "silent"`，或换用另一个 motif。
3. 菜单没有表达意见时，绘制主题的普通 motif。

菜单不能推翻脸的结构静默。页面级 `decor` 是受控的局部原语，例如线、标签、引号、圆点或大数字。只有页面含义确实需要这一个强调时才使用。它不能替代主题菜单，也不应整份 deck 到处盖章。

# Images

Read this when declaring image assets, choosing `photo` or `evidence`, searching stock, or generating art.

## Choose the semantic move first

Use `kind: "photo"` when the image itself is the subject. Use `kind: "evidence"` when one exhibit supports one assertion. The bound theme menu chooses the face for that kind. Authors do not name image geometry.

Cover and chapter pages can use an asset background. The renderer applies the dedicated image-cover treatment with a dark readability scrim. Content and ending asset backgrounds retain the theme-toned scrim. Use a background image only when the page truly needs a full-canvas scene.

Declare each image once in `assets.images`, then reference it by `asset_id` from `image`, `image_grid`, `image_compare`, or `device_mockup`. Check every key. `validate` reports a dangling reference, and an unresolved source cannot become a real image.

`image_side: "left"` or `"right"` is an optional preference for a face that supports a side image. Other faces ignore no authoring geometry because none is supplied.

## Brief before sourcing

Run the real renderer before sourcing any missing asset:

```bash
pptwise asset-brief <target>
```

The brief reports the actual frame, crop mode, safe zone, suggested pixel size, theme palette, and a paste-ready prompt. Match the reported aspect ratio and palette.

## Stock photos

Use a short concrete English query of two to four words, such as `office desk` or `wind farm`. Keep mood, quality claims, and negative keywords out of the query. Search Pexels first, Pixabay when configured, then the commercially filtered Openverse sources.

```bash
pptwise config set pexels.apiKey
pptwise images search "office desk" --orientation landscape
```

Do not take the first result automatically. Have a person or vision model choose from the thumbnails, then fetch the selected asset.

```bash
pptwise images fetch pexels:123 --deck <dir> --as hero
pptwise images list --deck <dir>
```

## Generated images

```bash
pptwise images generate --deck <dir> --as <asset_id>
```

Local generators remain disabled until the user enables one:

```bash
pptwise config set images.generators.grok.enabled true
pptwise config set images.generators.codex.enabled true
pptwise config set images.generators.antigravity.enabled true
```

Fetched and generated files live under `.pptwise/<deck>/assets/` with sidecars. Do not delete that directory to rerun a step because it contains selected assets. Without an available source, leave the asset missing and report it. Do not invent a photo or scrape an unsupported provider. Print required attribution in the terminal unless the license or user asks for on-slide credit.

---
summary: 'skills/pptwise/references/images.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/images.md
---

# 配图

何时读：声明图片资产，选择 `photo` 或 `evidence`，搜索图库，或生成图片时。

## 先选择语义动作

图像本身就是主角时用 `kind: "photo"`。一件展品支持一个断言时用 `kind: "evidence"`。已绑定主题的菜单为这个 kind 选择脸。作者不点名图片几何。

封面与章节页可以使用资产背景。渲染器会采用专门的压图处理，并加深色可读性遮罩。内容页与结尾页的资产背景保留主题色调遮罩。只有页面确实需要全画布场景时才使用背景图。

每张图片只在 `assets.images` 中声明一次，再由 `image`、`image_grid`、`image_compare` 或 `device_mockup` 通过 `asset_id` 引用。逐个检查 key。`validate` 会报告悬空引用，没有解析到来源的资产不能变成真实图片。

`image_side: "left"` 或 `"right"` 是给支持侧图的脸使用的可选偏好。其他脸不需要处理作者几何，因为作者没有提供这类信息。

## 先取简报再找图

为任何缺失资产找图之前，先运行真实渲染器：

```bash
pptwise asset-brief <target>
```

简报会给出实际画框、裁切方式、安全区、建议像素尺寸、主题配色和可直接使用的提示词。素材应匹配它报告的宽高比与色调。

## 图库照片

使用两到四个词的具体英文查询，例如 `office desk` 或 `wind farm`。查询中不要写情绪词、质量描述或否定关键词。搜索顺序是 Pexels，已配置时再查 Pixabay，最后查经过商业用途过滤的 Openverse 来源。

```bash
pptwise config set pexels.apiKey
pptwise images search "office desk" --orientation landscape
```

不要自动选择第一张结果。由人或视觉模型从缩略图中选择，再拉取目标资产。

```bash
pptwise images fetch pexels:123 --deck <dir> --as hero
pptwise images list --deck <dir>
```

## 生成图片

```bash
pptwise images generate --deck <dir> --as <asset_id>
```

本地生成器默认关闭，只有用户启用后才使用：

```bash
pptwise config set images.generators.grok.enabled true
pptwise config set images.generators.codex.enabled true
pptwise config set images.generators.antigravity.enabled true
```

拉取与生成的文件存放在 `.pptwise/<deck>/assets/`，旁边带 sidecar。不要为了重跑某一步而删除整个目录，因为其中保存了已经选定的资产。没有可用来源时，保留缺失状态并如实汇报。不要虚构照片，也不要抓取未支持的提供方。除非许可或用户要求在页面署名，归属信息默认打印在终端。

# Kinds and theme menus

Read this when deciding what a content page is saying and which `kind` names that move.

## The authoring rule

Boundary pages use only `cover`, `chapter`, or `ending`. Every content page carries exactly one of the eleven `kind` values below. Authors choose the semantic move. The bound theme menu chooses the visual face.

Do not encode geometry in the spec or page file. If the requested kind is absent from the theme menu, validation stops with a hard error and lists the kinds that theme offers. Resolve the mismatch by choosing an offered kind that still tells the truth, binding a theme that offers the intended kind, or creating a complete theme whose menu does.

## Close calls

- `points` is an argument whose order matters. `list` is a set of peers that can be reordered.
- `data` is a numeric set with a shape to read. `fact` is one number carrying the page.
- `photo` makes the image the subject. `evidence` makes an exhibit support one assertion.
- `statement` is the deck author's proposition. `quote` attributes the words to someone else.
- `process` expresses direction or time. `hierarchy` expresses containment or levels. `comparison` puts alternatives side by side.

## Menu consequences

A theme menu binds each boundary page and each offered content kind to one face. The same choice also fixes that face's capacity, motif posture, and branding permissions. Write to that physical capacity after binding the theme. A different color fork with the same menu can be rebound without rewriting the story. A theme with a different menu requires a return to the theme step, followed by spec and page-fill revision.

<!-- generated:begin kinds -->
### Complete kind vocabulary

This section is generated from the IR v5 kind vocabulary and the 24 preset menus. The final column shows how many preset menus offer each kind.

| kind | name | use it when | boundary | preset menus |
| --- | --- | --- | --- | ---: |
| `points` | Points | Advance an ordered argument whose sequence matters. | Use list when the items are peers that can be reordered. | 24/24 |
| `list` | List | Present peer items whose order may change. | Use points when the sequence carries the reasoning. | 24/24 |
| `comparison` | Comparison | Place alternatives, sides, or dimensions in direct contrast. | Containment belongs to hierarchy and direction belongs to process. | 24/24 |
| `process` | Process | Show directed steps, a timeline, or a closed cycle. | An ordered argument without motion is points. | 24/24 |
| `data` | Data | Make a set of numbers, a chart, or a table the subject. | Use fact when one number is the whole message. | 23/24 |
| `photo` | Photo | Make the image itself the content. | Use evidence when an exhibit exists to support a claim. | 21/24 |
| `statement` | Statement | Give the deck author's own proposition a full page. | Words attributed to someone else are quote. | 20/24 |
| `quote` | Quote | Center words attributed to another speaker or source. | The deck author's own proposition is statement. | 8/24 |
| `fact` | Fact | Build the page around one number. | A numeric set whose structure matters is data. | 18/24 |
| `evidence` | Evidence | Pair one assertion with one exhibit that supports it. | Use photo when the image stands on its own. | 10/24 |
| `hierarchy` | Hierarchy | Express containment, levels, or composition. | Sequence belongs to process and side-by-side contrast to comparison. | 22/24 |
<!-- generated:end kinds -->

---
summary: 'skills/pptwise/references/layouts.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/layouts.md
---

# 讲法与主题菜单

何时读：判断内容页在说什么，以及该用哪个 `kind` 命名这种表达动作时。

## 作者规则

边界页只使用 `cover`、`chapter` 或 `ending`。每张内容页必须且只能带一个下列十一词中的 `kind`。作者选择语义动作，已绑定主题的菜单负责选择视觉脸。

不要在 spec 或页面文件中编码几何。请求的 kind 不在主题菜单里时，验证会硬报错，并列出该主题提供的讲法。解决方式只有三种：改用仍然忠于内容的已提供讲法，绑定一个提供目标讲法的主题，或创建一个菜单包含目标讲法的完整主题。

## 容易混淆的边界

- `points` 是顺序不可调换的论证。`list` 是可以换序的并列条目。
- `data` 是要读出结构的一组数字。`fact` 是由一个数字承担整页信息。
- `photo` 让图像本身成为主角。`evidence` 让一件展品支持一个断言。
- `statement` 是作者自己的立论。`quote` 把话归给别人。
- `process` 表达方向或时间。`hierarchy` 表达包含或层级。`comparison` 把多个对象并排对照。

## 菜单带来的约束

主题菜单为每种边界页和每个已提供的内容讲法各绑定一张脸。这次绑定也同时确定了脸的容量、装饰姿态和品牌权限。先绑定主题，再按真实物理容量写作。菜单相同的换色分叉可以直接换绑。菜单不同的主题需要回到主题步骤，再修订 spec 与页面填充。

<!-- generated:begin kinds -->
### 讲法全量表

本段由 IR v5 的讲法词表与 24 个预设菜单生成。最后一列表示有多少预设菜单提供该讲法。

| kind | 中文 | 何时使用 | 边界 | 预设菜单 |
| --- | --- | --- | --- | ---: |
| `points` | 要点 | 按不可调换的顺序推进一组论点。 | 并列条目可换序时用 list。 | 24/24 |
| `list` | 清单 | 并列陈列一组可以换序的条目。 | 顺序承载论证时用 points。 | 24/24 |
| `comparison` | 对比 | 把两边、多个方案或多个维度直接对照。 | 包含关系用 hierarchy，有方向的变化用 process。 | 24/24 |
| `process` | 流程 | 表达有方向的步骤、时间线或闭环。 | 只有论证递进而没有运动关系时用 points。 | 24/24 |
| `data` | 数据 | 让一组数字、图表或表格成为页面主角。 | 只有一个数字承担全部信息时用 fact。 | 23/24 |
| `photo` | 图像 | 让画面本身成为内容。 | 展品是为断言服务时用 evidence。 | 21/24 |
| `statement` | 宣言 | 让作者自己的一句话立论占据整页。 | 借别人之口时用 quote。 | 20/24 |
| `quote` | 引用 | 以他人或外部来源的话为中心。 | 作者自己的立论用 statement。 | 8/24 |
| `fact` | 大数字 | 让一个数字承担整页冲击。 | 要看一组数字的结构时用 data。 | 18/24 |
| `evidence` | 单证据 | 把一个断言与一件支持它的展品配对。 | 画面自己就是内容时用 photo。 | 10/24 |
| `hierarchy` | 层级 | 表达包含、层级或组成关系。 | 先后关系用 process，并排对照用 comparison。 | 22/24 |
<!-- generated:end kinds -->

# Intent, narrative, theme binding, and spec

Read this before creating `deck.spec.json`, choosing a theme, or handling a menu mismatch.

The authoring chain is causal and one-way:

```text
intent -> narrative -> theme binding -> spec with kind -> fill -> render
```

## Read live vocabularies

Run these at the start of every deck task:

```bash
pptwise schema
pptwise schema --spec
pptwise narratives --json
pptwise themes --json
```

The command output and workspace files outrank this guide. Scan for an existing `deck.spec.json`, deck-local `theme.json`, workspace `themes/`, and supplied Office brand files before asking questions.

## Intent and narrative

Intent records who the deck is for, the result it should cause, whether it will be presented or circulated, and the available time. Narrative is the first decision made from that intent. It chooses argument strategy, pacing, and tone.

When essential facts are missing and a user is present, ask one compact round:

1. Who is the audience, and what should they decide, understand, or do afterward?
2. Will someone present it, or must it stand alone? How much time is available?
3. Should the argument lead with a conclusion, unfold as a story, teach a sequence, showcase an image or number, or read as a compact briefing?
4. Should pages be dense, balanced, or spacious?

Use `pptwise narratives --json` to map the answer to a named preset or to explicit `strategy`, `pacing`, and `audience`. Do not infer the narrative from brand colors. Confirm this package before choosing a theme.

## Choose, create, and bind a theme

Theme is the second decision and must be settled before the spec. A theme is one complete file with style, a page menu, optional brand rules, `occasions`, and `identity`. The menu serves a deliberate subset of the 11 content kinds.

Shortlist by occasion first and identity strength second. Compare two to four candidates with the fixed fitting-room sample:

```bash
pptwise theme try brief,swiss,memo
```

`theme try` renders the same fixed sample deck under every candidate. It is the only place to compare themes without binding a deck. Choose from the images, not from names alone.

Create means copy. Prefer a workspace-owned theme even when the starting point is a factory preset:

```bash
pptwise theme new --from brief --id acme-report
```

With an Office theme or template, choose the donor menu by occasion, then extract colors and fonts into one complete v2 file:

```bash
pptwise brand extract corp.pptx -o themes/acme.theme.json --from brief
```

With an existing theme and a requested color change, fork it. The fork keeps the menu byte-identical and rederives the full palette:

```bash
pptwise theme fork acme --primary '#0B5FFF' --id acme-blue
```

Theme names resolve in three levels:

1. The deck directory, including `theme.json` and named theme JSON files.
2. A workspace `themes/` directory while walking upward from the deck.
3. Factory presets.

Bind exactly one name by writing it to `deck.spec.json` as `theme`. To freeze a workspace theme for one deck, copy the complete file into the deck directory as `theme.json` without changing its id. Deck commands then load it automatically.

<!-- generated:begin themes -->
### Complete factory preset catalog

This section is generated from the preset library and each preset menu. `identity` is the strength of the visual voice. `menu words` and the final column count content kinds only.

| id | label | occasions | identity | menu words | offered kinds |
| --- | --- | --- | --- | ---: | --- |
| `brief` | Brief | business | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `bulletin` | Bulletin | business, institutional | low | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `thesis` | Thesis | education | medium | 11 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `evidence`, `hierarchy` |
| `ledger` | Ledger | finance | medium | 9 | `points`, `list`, `comparison`, `process`, `data`, `statement`, `quote`, `fact`, `hierarchy` |
| `rally` | Rally | marketing, event | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `homeroom` | Homeroom | education | medium | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `ink` | Ink | culture | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `terminal` | Terminal | tech | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `runway` | Runway | fashion | high | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement` |
| `journal` | Journal | editorial | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `luxe` | Luxe | luxury, event | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `heritage` | Heritage | culture, luxury | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `clinic` | Clinic | health | medium | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `almanac` | Almanac | sustainability | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `ember` | Ember | startup | high | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `vermilion` | Vermilion | government, institutional | low | 9 | `points`, `list`, `comparison`, `process`, `data`, `statement`, `fact`, `evidence`, `hierarchy` |
| `crayon` | Crayon | kids, education | high | 6 | `points`, `list`, `comparison`, `process`, `photo`, `statement` |
| `arena` | Arena | entertainment | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `museum` | Museum | museum, culture | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `stage` | Stage | keynote | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `lecture` | Lecture | education | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `swiss` | Swiss | institutional | low | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `memo` | Memo | business, institutional | low | 9 | `points`, `list`, `comparison`, `process`, `data`, `statement`, `quote`, `fact`, `hierarchy` |
| `playbill` | Playbill | event, entertainment | high | 9 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `hierarchy` |
<!-- generated:end themes -->

## The 11 content kinds

`kind` states how a content page makes its point. It is required on every content page and absent from cover, chapter, and ending pages.

| `kind` | Use it when | Do not confuse it with |
| --- | --- | --- |
| `points` | Ordered reasoning advances step by step | `list`, whose items may be reordered |
| `list` | Peer items are displayed together | `points`, whose order carries the argument |
| `comparison` | Alternatives or sides need direct contrast | `hierarchy` for containment, `process` for direction |
| `process` | Steps, time, movement, or a closed cycle matter | `points` for an argument with no process relation |
| `data` | A set of numbers, chart, or table is the subject | `fact` for one number only |
| `photo` | The image itself is the content | `evidence`, where an exhibit supports a claim |
| `statement` | The deck author's own proposition gets a full page | `quote` for another speaker's words |
| `quote` | Words are attributed to another speaker or source | `statement` for the deck author's own voice |
| `fact` | One number carries the whole message | `data` for numeric structure across a set |
| `evidence` | One assertion is paired with one supporting exhibit | `photo` when the image stands alone |
| `hierarchy` | The page explains containment, levels, or composition | `process` for sequence, `comparison` for two sides |

Four boundaries settle most ambiguous cases:

- `statement`, `quote`, `fact`, and `evidence` differ by the speaking subject: our proposition, another person's words, one number, or a claim with an exhibit.
- `data` exposes structure across several values. `fact` creates impact with one value.
- `points` has progression. `list` can be reordered.
- `photo` makes the image the message. `evidence` makes the image serve the assertion.

## Write the spec

A valid deck spec opens with `cover`, closes with `ending`, and uses `content` or `chapter` inside. Every page has `id`, `type`, and `heading`. Content pages additionally require `kind`. `focus` may name a preferred component type. `summary` is a short content anchor for the fill step.

```json
{
  "version": "1",
  "filename": "q3-review.pptx",
  "narrative": "boardroom-report",
  "theme": "acme-report",
  "meta": { "organization": "Acme", "date": "2026 Q3" },
  "pages": [
    { "id": "cover", "type": "cover", "heading": "Q3 operating review" },
    { "id": "decision", "type": "content", "kind": "points", "heading": "Two actions protect the annual target" },
    { "id": "options", "type": "content", "kind": "comparison", "heading": "The focused plan wins on payback" },
    { "id": "economics", "type": "content", "kind": "data", "heading": "Margin recovers before year end" },
    { "id": "delivery", "type": "content", "kind": "process", "heading": "Three releases close the gap" },
    { "id": "close", "type": "ending", "heading": "Approve the focused plan" }
  ]
}
```

The spec contains no page geometry or render selection state. Do not add retired author fields. Page files later contain only fillable content and never repeat `type`, `kind`, or `heading`.

Run:

```bash
pptwise spec validate deck.spec.json
```

Fix hard errors until the command prints `OK`. Page count is checked against pacing. Three or more consecutive content pages with the same `kind` produce an editorial warning.

## Menu mismatch handling

If the spec requests a `kind` that the bound theme does not offer, validation fails and lists the available kinds. Handle it in this order:

1. Recheck the page's semantic posture. Change `kind` only when another offered word is genuinely correct.
2. If the page intent is fixed, choose or create a theme whose menu serves it.
3. If content was already filled, return to the theme layer. Keep useful facts, data, images, and copy fragments, then rewrite the spec and page files for the new menu.

Do not force a nearby word merely to pass validation. A menu gap is a theme decision, not missing geometry.

## Rebinding after work starts

A color fork with the same menu may replace the bound theme. Update the bound name and rerun spec validation, assemble, validate, audit, and render.

A theme with a different menu is not a repaint. It requires restarting at the theme layer and rewriting the spec. The CLI compares normalized menus directly and refuses an in-place different-menu rebind.

A very small deck may use one IR file instead of a deck project. It still follows the same chain. Its top-level `theme.id` is the binding, and every content slide still requires explicit `kind`.

---
summary: 'skills/pptwise/references/spec.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/spec.md
---

# 意图、叙事、主题绑定与 spec

何时读：创建 `deck.spec.json`、选择主题、或处理菜单不匹配时。

作者链条是因果单向的：

```text
意图 -> 叙事 -> 主题绑定 -> 带 kind 的 spec -> 填充 -> 渲染
```

## 读取现场词汇

每个 deck 任务开始时运行：

```bash
pptwise schema
pptwise schema --spec
pptwise narratives --json
pptwise themes --json
```

命令输出与工作区文件优先于本指南。提问前先找已有 `deck.spec.json`、deck 内 `theme.json`、工作区 `themes/`，以及用户递来的 Office 品牌文件。

## 意图与叙事

意图记录讲给谁、要促成什么结果、现场讲述还是传阅、可用时长。叙事是根据意图作出的第一个决定，确定论证方式、节奏与语气。

用户在场且仍缺关键事实时，只问一轮简洁问题：

1. 受众是谁，结束后应该决定、理解或做什么？
2. 会有人现场讲，还是文件必须独立读懂？有多少时间？
3. 论证应该结论先行、按故事展开、分步教学、突出一个画面或数字，还是写成紧凑简报？
4. 页面应该密、均衡，还是留白？

用 `pptwise narratives --json` 把答案映射成具名预设，或显式的 `strategy`、`pacing`、`audience`。不要从品牌配色推导叙事。先确认这份叙事包，再选择主题。

## 选择、创建并绑定主题

主题是第二个决定，必须早于 spec。主题是一个完整文件，包含样式、页面菜单、可选品牌规则、`occasions` 与 `identity`。菜单只服务 11 种内容页讲法中的一个明确子集。

先按场合筛选，再按视觉个性强度筛选。用固定样张比较 2 到 4 个候选：

```bash
pptwise theme try brief,swiss,memo
```

`theme try` 用每个候选渲染同一份固定样张 deck。只有这里会在不绑定 deck 的情况下比较主题。按图选，不要只看名字。

创建就是拷贝。即使从出厂预设开始，也优先创建工作区自有主题：

```bash
pptwise theme new --from brief --id acme-report
```

有 Office 主题或模板时，先按场合选择菜单来源，再把配色与字体抽进一个完整的 v2 文件：

```bash
pptwise brand extract corp.pptx -o themes/acme.theme.json --from brief
```

已有主题要改色时，fork 它。fork 保持菜单逐字节相同，并重新派生整套配色：

```bash
pptwise theme fork acme --primary '#0B5FFF' --id acme-blue
```

主题名按三级解析：

1. deck 目录，包括 `theme.json` 与具名主题 JSON。
2. 从 deck 向上查找的工作区 `themes/`。
3. 出厂预设。

在 `deck.spec.json` 的 `theme` 中写入唯一名称完成绑定。要把工作区主题冻结给单个 deck，保持 id 不变，把完整文件复制到 deck 目录并命名为 `theme.json`。之后 deck 命令会自动装载。

<!-- generated:begin themes -->
### 出厂预设全量表

本段由预设库及每个预设的菜单生成。`identity` 表示视觉个性强度。`菜单词数` 与最后一列都只计算内容页讲法。

| id | label | occasions | identity | 菜单词数 | 提供的 kind |
| --- | --- | --- | --- | ---: | --- |
| `brief` | Brief | business | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `bulletin` | Bulletin | business, institutional | low | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `thesis` | Thesis | education | medium | 11 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `evidence`, `hierarchy` |
| `ledger` | Ledger | finance | medium | 9 | `points`, `list`, `comparison`, `process`, `data`, `statement`, `quote`, `fact`, `hierarchy` |
| `rally` | Rally | marketing, event | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `homeroom` | Homeroom | education | medium | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `ink` | Ink | culture | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `terminal` | Terminal | tech | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `runway` | Runway | fashion | high | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement` |
| `journal` | Journal | editorial | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `luxe` | Luxe | luxury, event | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `heritage` | Heritage | culture, luxury | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `clinic` | Clinic | health | medium | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `almanac` | Almanac | sustainability | medium | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `ember` | Ember | startup | high | 7 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `hierarchy` |
| `vermilion` | Vermilion | government, institutional | low | 9 | `points`, `list`, `comparison`, `process`, `data`, `statement`, `fact`, `evidence`, `hierarchy` |
| `crayon` | Crayon | kids, education | high | 6 | `points`, `list`, `comparison`, `process`, `photo`, `statement` |
| `arena` | Arena | entertainment | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `museum` | Museum | museum, culture | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `stage` | Stage | keynote | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `quote`, `fact`, `hierarchy` |
| `lecture` | Lecture | education | high | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `swiss` | Swiss | institutional | low | 10 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `evidence`, `hierarchy` |
| `memo` | Memo | business, institutional | low | 9 | `points`, `list`, `comparison`, `process`, `data`, `statement`, `quote`, `fact`, `hierarchy` |
| `playbill` | Playbill | event, entertainment | high | 9 | `points`, `list`, `comparison`, `process`, `data`, `photo`, `statement`, `fact`, `hierarchy` |
<!-- generated:end themes -->

## 11 种内容页讲法

`kind` 说明内容页怎样表达观点。每张内容页必填。封面、章节与结尾不写。

| `kind` | 何时使用 | 不要混淆 |
| --- | --- | --- |
| `points` | 论证按顺序逐步推进 | `list` 的条目可以换序 |
| `list` | 一组并列项一起陈列 | `points` 的顺序承载论证 |
| `comparison` | 方案或两边需要直接对照 | 包含关系用 `hierarchy`，方向关系用 `process` |
| `process` | 步骤、时间、运动或闭环很重要 | 没有流程关系的递进论证用 `points` |
| `data` | 一组数字、图表或表格是主角 | 只有一个数字时用 `fact` |
| `photo` | 画面本身就是内容 | 展品服务断言时用 `evidence` |
| `statement` | 作者自己的一句话立论占满一页 | 借别人之口用 `quote` |
| `quote` | 文字归属于另一位说话者或来源 | 作者自己的话用 `statement` |
| `fact` | 一个数字承担整页信息 | 多个数字之间的结构用 `data` |
| `evidence` | 一个断言配一件支持它的展品 | 图片独立成义时用 `photo` |
| `hierarchy` | 页面解释包含、层级或组成 | 先后关系用 `process`，两边对照用 `comparison` |

四条边界能解决大多数歧义：

- `statement`、`quote`、`fact`、`evidence` 的区别在说话主体，分别是自己的立论、别人的话、一个数字、断言加展品。
- `data` 展示多个值之间的结构。`fact` 用一个值制造冲击。
- `points` 有递进。`list` 可换序。
- `photo` 让画面成为信息。`evidence` 让画面服务断言。

## 编写 spec

合法 spec 以 `cover` 开头，以 `ending` 结束，中间使用 `content` 或 `chapter`。每页都有 `id`、`type`、`heading`。内容页还必须有 `kind`。`focus` 可以点名偏好的组件类型。`summary` 是填充步骤使用的简短内容锚点。

```json
{
  "version": "1",
  "filename": "q3-review.pptx",
  "narrative": "boardroom-report",
  "theme": "acme-report",
  "meta": { "organization": "Acme", "date": "2026 Q3" },
  "pages": [
    { "id": "cover", "type": "cover", "heading": "Q3 经营复盘" },
    { "id": "decision", "type": "content", "kind": "points", "heading": "两项动作守住全年目标" },
    { "id": "options", "type": "content", "kind": "comparison", "heading": "聚焦方案回报更快" },
    { "id": "economics", "type": "content", "kind": "data", "heading": "利润率在年末前恢复" },
    { "id": "delivery", "type": "content", "kind": "process", "heading": "三次发布补齐缺口" },
    { "id": "close", "type": "ending", "heading": "批准聚焦方案" }
  ]
}
```

spec 不含页面几何或渲染选择状态。不要加入已退役的作者字段。后续页面文件只装可填内容，不重复 `type`、`kind` 或 `heading`。

运行：

```bash
pptwise spec validate deck.spec.json
```

修完硬错误，直到命令打印 `OK`。页数会按 `pacing` 检查。连续三张或更多内容页使用同一个 `kind` 时，会产生编辑提示。

## 菜单不匹配怎么处理

spec 请求了绑定主题没有提供的 `kind` 时，校验会失败并列出可用词。按这个顺序处理：

1. 重查页面的语义姿势。只有另一个可用词确实正确时才改 `kind`。
2. 页面意图不能变时，选择或创建菜单能服务它的主题。
3. 已经填过内容时，回到主题层。保留有用的事实、数据、图片与文案片段，再按新菜单重写 spec 与页面文件。

不要为了通过校验硬套一个相近词。菜单缺口是主题决策，不是几何缺口。

## 开工后的换绑

菜单相同的配色 fork 可以替换绑定主题。更新绑定名称，再重跑 spec validate、assemble、validate、audit 与 render。

菜单不同的主题不是换色，必须回到主题层重写 spec。CLI 会直接比较规范化后的菜单，并拒绝流程内换绑到不同菜单。

很小的 deck 可以使用单个 IR 文件而不是 deck 项目。它仍遵循同一条链。顶层 `theme.id` 是绑定，每张内容页仍必须显式写 `kind`。

# Validation and review loop

Read this when filling pages, assembling a deck project, rendering, auditing, previewing, serving, or revising.

## Fill small batches

For each confirmed spec page, write `pages/<page-id>.json`. A page file may contain only `components`, `background`, `image_side`, `footnote`, and `notes`. The spec owns `type`, content `kind`, `heading`, and page order. Repeating any locked field in a page file is a hard error.

Fill at most four pages, then run:

```bash
pptwise assemble deck-dir/
pptwise validate deck-dir/
```

`assemble` merges the locked semantics and page content into IR v5. It does not write face choices or any other rendering decision into the project. A missing page file remains an accepted placeholder. An orphan page file, a locked-field conflict, an unknown theme, or a kind absent from the bound theme menu is a hard error.

`validate` applies schema, component, asset, narrative, physical capacity, and editorial checks. Fix errors until it prints `OK`. Warnings do not block output, but long headings, excessive density, dangling assets, and repetitive choices should normally be tightened before delivery.

Speaker `notes` export as native PowerPoint notes and never paint on the slide.

## Render only from the binding

```bash
pptwise render deck-dir/
```

The `.pptx` is written under `.pptwise/<deck>/`, and the command prints its absolute path. There is no render-time theme switch. The project spec is the binding.

An unfinished project requires explicit `--draft`. Content that would be dropped remains blocked unless the user explicitly accepts `--allow-dropped-content`. Prefer fixing or splitting the page.

When changing themes, compare candidates with `pptwise theme try`. A same-menu fork can replace the binding and proceed through assemble, validate, audit, and render. A different menu requires returning to theme selection, then revising the spec and affected page fills before those checks.

## Audit geometry

After every page is filled, run:

```bash
pptwise audit deck-dir/
```

The deterministic audit checks overflow, out-of-bounds content, low contrast, overlap, truncation, dropped content, and repeated lead components. A finding exits with code 1 and names the page. Restructure the content, rerun assemble and validate when source files changed, then rerun audit until it exits 0.

Add `--pixels` when cover or chapter pages use photo backgrounds. Pixel sampling catches text placed on an unsafe part of a real image.

## Review the whole deck

When an in-conversation deck preview tool exists, use it. Otherwise generate the self-contained review file:

```bash
pptwise preview deck-dir/ --html
```

It writes one SVG per page plus `preview.html` under `.pptwise/<deck>/`. The preview is read-only. Placeholder pages are marked, and a complete deck includes audit findings in the review interface.

When the user needs a live browser round, run the project server as a background task:

```bash
pptwise serve deck-dir/ --no-open
```

Share the exact localhost URL, keep the process for the review round, and stop only that process when the round ends.

## Revise at the source

- For a content change, edit only the affected `pages/<id>.json`, then assemble, validate, audit, and render again.
- For page order, page type, kind, heading, or theme binding, edit `deck.spec.json`, run `pptwise spec validate`, then repeat the project checks.
- For a different topic or audience, create a new project and restart from intent and narrative.

Never regenerate unrelated pages during a focused revision. Interpret screenshot feedback as a content requirement, change the smallest source file that owns it, and keep preview output read-only.

---
summary: 'skills/pptwise/references/validate.md 的中文阅读镜像'
mirror_of: skills/pptwise/references/validate.md
---

# 验证与评审循环

何时读：填充页面，组装 deck 项目，渲染，审计，预览，启动评审服务，或修订内容时。

## 小批量填充

为 spec 中每张已确认页面编写 `pages/<page-id>.json`。页面文件只能包含 `components`、`background`、`image_side`、`footnote` 与 `notes`。Spec 拥有 `type`、内容页 `kind`、`heading` 和页面顺序。在页面文件中重复任何锁定字段都会硬报错。

每次最多填四页，然后运行：

```bash
pptwise assemble deck-dir/
pptwise validate deck-dir/
```

`assemble` 把锁定语义与页面内容合并成 IR v5。它不会把脸的选择或其他渲染决定写回项目。没有页面文件时保留为合法占位页。孤儿页面文件、锁定字段冲突、未知主题，或 kind 不在已绑定主题菜单中，都会硬报错。

`validate` 检查 schema、组件、资产、叙事、物理容量与编辑预算。修复错误，直到它打印 `OK`。警告不拦输出，但长标题、密度过高、资产悬空和重复选择通常都应在交付前收紧。

演讲者 `notes` 会导出为原生 PowerPoint 备注，从不画在页面上。

## 只按绑定渲染

```bash
pptwise render deck-dir/
```

`.pptx` 写到 `.pptwise/<deck>/`，命令会打印绝对路径。渲染阶段没有临时换主题的开关。项目 spec 就是绑定。

未填完的项目需要显式使用 `--draft`。可能丢失的内容仍会被拦截，除非用户明确接受 `--allow-dropped-content`。应优先修复或拆页。

更换主题前，用 `pptwise theme try` 比较候选。菜单相同的分叉可以换绑，再依次运行 assemble、validate、audit 和 render。菜单不同则要回到主题选择，修订 spec 与受影响的页面填充，再重复这些检查。

## 审计几何

全部页面填完后运行：

```bash
pptwise audit deck-dir/
```

确定性审计会检查溢出、越界、低对比度、重叠、截断、内容丢失和连续使用相同首组件。发现问题时退出码为 1，并指出页面。重组内容，源文件改变后重跑 assemble 与 validate，再重复 audit，直到退出码为 0。

封面或章节页使用照片背景时，加上 `--pixels`。像素采样能发现文字落在真实图片不安全区域的问题。

## 评审整份 deck

运行环境若有对话内 deck 预览工具，优先使用。否则生成自包含评审文件：

```bash
pptwise preview deck-dir/ --html
```

它会在 `.pptwise/<deck>/` 下写出每页一个 SVG 与 `preview.html`。预览只读。占位页会被标记，完整 deck 会在评审界面中带上 audit 发现。

用户需要浏览器实时评审时，把项目服务作为后台任务启动：

```bash
pptwise serve deck-dir/ --no-open
```

分享命令打印的准确 localhost 地址，在评审轮次中保留进程，结束时只停止这个进程。

## 在源头修订

- 内容变化只编辑受影响的 `pages/<id>.json`，再依次运行 assemble、validate、audit 和 render。
- 页面顺序、页型、kind、标题或主题绑定变化时，编辑 `deck.spec.json`，运行 `pptwise spec validate`，再重复项目检查。
- 主题或受众完全不同的新任务应创建新项目，从意图与叙事重新开始。

聚焦修订时不要重新生成无关页面。把截图反馈解释为内容要求，修改拥有这项要求的最小源文件，并始终保持预览产物只读。

#!/bin/sh
# pptwise skill launcher (macOS / Linux).
#
# One stable action for the agent ("run pptwise"); this script picks a working
# way to run it in the current environment. Written to POSIX sh so it runs under
# dash, busybox ash, and bash alike. Invoke it with `bash run.sh ...` (or plain
# `sh run.sh ...`) so a lost execute bit after a file copy never matters.
#
# Resolution order (kept identical in run.ps1):
#   1. A compatible pptwise already on PATH -> run it directly.
#   2. npx present, on a node meeting the floor -> run the pinned npm version.
#   3. bunx present -> run the pinned version via Bun.
#   4. Nothing usable -> structured diagnosis, exit 78.
#
# It never writes PATH, never needs admin rights, never fetches a second script,
# and has no postinstall step.
set -eu

# --- Version constants: stamped by scripts/stamp.mts at release time. ---------
# Do not edit PINNED by hand; scripts/stamp.test.mts asserts it equals the
# package.json version, and `pnpm release:version` rewrites it on every bump.
PKG="@liustack/pptwise"
BIN="pptwise"
PINNED="0.35.0"
# ------------------------------------------------------------------------------

# Split "X.Y.Z" (extra suffix ignored) into the globals _MAJ, _MIN, _PAT.
# Any non-numeric component becomes 0 so integer tests below never abort.
parse_semver() {
  _raw="$1"
  _MAJ="${_raw%%.*}"
  _rest="${_raw#*.}"
  if [ "$_rest" = "$_raw" ]; then
    _MIN=0
    _PAT=0
  else
    _MIN="${_rest%%.*}"
    _rest2="${_rest#*.}"
    if [ "$_rest2" = "$_rest" ]; then _PAT=0; else _PAT="${_rest2%%.*}"; fi
  fi
  case "$_MAJ" in '' | *[!0-9]*) _MAJ=0 ;; esac
  case "$_MIN" in '' | *[!0-9]*) _MIN=0 ;; esac
  case "$_PAT" in '' | *[!0-9]*) _PAT=0 ;; esac
}

# Compatible = same major version as PINNED AND not older than PINNED.
# Same major keeps a globally installed CLI usable without a forced re-download;
# not-older refuses a stale build that predates the version this skill needs.
compatible() {
  parse_semver "$1"
  _f_maj=$_MAJ
  _f_min=$_MIN
  _f_pat=$_PAT
  parse_semver "$PINNED"
  [ "$_f_maj" = "$_MAJ" ] || return 1
  if [ "$_f_min" -gt "$_MIN" ]; then return 0; fi
  if [ "$_f_min" -lt "$_MIN" ]; then return 1; fi
  [ "$_f_pat" -ge "$_PAT" ]
}

# First "X.Y.Z" token printed by `$BIN --version`.
cli_version() {
  "$BIN" --version 2>/dev/null | head -n 1 |
    sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*/\1/p'
}

# The npx path runs the CLI on this machine's node, so npx is only usable when
# node itself meets the package's floor (package.json engines). An old node
# with a working npx would otherwise be selected into a path known to fail.
NODE_FLOOR="22.19.0"
node_meets_floor() {
  command -v node >/dev/null 2>&1 || return 1
  _nv="$(node --version 2>/dev/null | sed 's/^v//')"
  [ -n "$_nv" ] || return 1
  parse_semver "$NODE_FLOOR"
  _floor_maj="$_MAJ"
  _floor_min="$_MIN"
  parse_semver "$_nv"
  if [ "$_MAJ" -gt "$_floor_maj" ]; then return 0; fi
  if [ "$_MAJ" -lt "$_floor_maj" ]; then return 1; fi
  [ "$_MIN" -ge "$_floor_min" ]
}

# Echo exactly one word: the chosen launch path.
resolve() {
  if command -v "$BIN" >/dev/null 2>&1; then
    _v="$(cli_version)"
    if [ -n "$_v" ] && compatible "$_v"; then
      echo "path"
      return
    fi
  fi
  if command -v npx >/dev/null 2>&1 && node_meets_floor; then
    echo "npx"
    return
  fi
  if command -v bunx >/dev/null 2>&1; then
    echo "bunx"
    return
  fi
  echo "none"
}

detect_os() { uname -s 2>/dev/null | tr '[:upper:]' '[:lower:]'; }

detect_arch() {
  _a="$(uname -m 2>/dev/null)"
  case "$_a" in
    x86_64 | amd64) echo "x64" ;;
    aarch64 | arm64) echo "arm64" ;;
    *) echo "$_a" ;;
  esac
}

# Escape a value for a JSON string literal (backslash and double quote).
json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }

# Render "null" for an empty value, else an escaped JSON string.
jstr() {
  if [ -z "$1" ]; then printf 'null'; else printf '"%s"' "$(json_escape "$1")"; fi
}

# 1 -> true, anything else -> false.
jbool() { if [ "$1" = "1" ]; then printf 'true'; else printf 'false'; fi; }

# Probe the environment once into G_* globals shared by the emitters.
collect() {
  G_OS="$(detect_os)"
  G_ARCH="$(detect_arch)"

  G_CLI_PRESENT=0
  G_CLI_PATH=""
  G_CLI_VER=""
  G_CLI_COMPAT=0
  if command -v "$BIN" >/dev/null 2>&1; then
    G_CLI_PRESENT=1
    G_CLI_PATH="$(command -v "$BIN")"
    G_CLI_VER="$(cli_version)"
    if [ -n "$G_CLI_VER" ] && compatible "$G_CLI_VER"; then G_CLI_COMPAT=1; fi
  fi

  G_NPX_PRESENT=0
  G_NPX_PATH=""
  if command -v npx >/dev/null 2>&1; then
    G_NPX_PRESENT=1
    G_NPX_PATH="$(command -v npx)"
  fi

  G_BUNX_PRESENT=0
  G_BUNX_PATH=""
  if command -v bunx >/dev/null 2>&1; then
    G_BUNX_PRESENT=1
    G_BUNX_PATH="$(command -v bunx)"
  fi

  G_NODE_PRESENT=0
  G_NODE_VER=""
  if command -v node >/dev/null 2>&1; then
    G_NODE_PRESENT=1
    G_NODE_VER="$(node --version 2>/dev/null | sed 's/^v//')"
  fi

  G_NODE_FLOOR_OK=0
  if node_meets_floor; then G_NODE_FLOOR_OK=1; fi

  G_SEL="$(resolve)"
}

# Build the nextSteps JSON array body (without the brackets) into G_NEXTSTEPS.
compute_next_steps() {
  if [ "$G_SEL" = "none" ]; then
    if [ "$G_NPX_PRESENT" = 1 ] && [ "$G_NODE_FLOOR_OK" = 0 ]; then
      _s1="npx is present but node ${G_NODE_VER:-missing} is below the $NODE_FLOOR floor this CLI needs. Upgrade Node at https://nodejs.org, then re-run this launcher."
    else
      _s1="Install Node 22.19+ from https://nodejs.org so npx can run $PKG@$PINNED, then re-run this launcher."
    fi
    _s2="No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $BIN (major ${PINNED%%.*}, at or above $PINNED) on PATH."
    G_NEXTSTEPS="$(printf '"%s", "%s"' "$(json_escape "$_s1")" "$(json_escape "$_s2")")"
  else
    G_NEXTSTEPS=""
  fi
}

# Emit the structured diagnosis.
emit_json() {
  compute_next_steps
  printf '{\n'
  printf '  "tool": %s,\n' "$(jstr "$BIN")"
  printf '  "package": %s,\n' "$(jstr "$PKG")"
  printf '  "pinnedVersion": %s,\n' "$(jstr "$PINNED")"
  printf '  "os": %s,\n' "$(jstr "$G_OS")"
  printf '  "arch": %s,\n' "$(jstr "$G_ARCH")"
  printf '  "checked": {\n'
  printf '    "pathCli": { "present": %s, "path": %s, "version": %s, "compatible": %s },\n' \
    "$(jbool "$G_CLI_PRESENT")" "$(jstr "$G_CLI_PATH")" "$(jstr "$G_CLI_VER")" "$(jbool "$G_CLI_COMPAT")"
  printf '    "npx": { "present": %s, "path": %s, "nodeMeetsFloor": %s },\n' "$(jbool "$G_NPX_PRESENT")" "$(jstr "$G_NPX_PATH")" "$(jbool "$G_NODE_FLOOR_OK")"
  printf '    "bunx": { "present": %s, "path": %s },\n' "$(jbool "$G_BUNX_PRESENT")" "$(jstr "$G_BUNX_PATH")"
  printf '    "node": { "present": %s, "version": %s }\n' "$(jbool "$G_NODE_PRESENT")" "$(jstr "$G_NODE_VER")"
  printf '  },\n'
  printf '  "selected": %s,\n' "$(jstr "$G_SEL")"
  printf '  "nextSteps": [%s]\n' "$G_NEXTSTEPS"
  printf '}\n'
}

# Default action: forward every argument to the resolved CLI, inheriting stdio
# and exit code. No usable runtime -> structured diagnosis on stderr, exit 78
# (EX_CONFIG) so the agent never mistakes the diagnosis for a result.
run() {
  _sel="$(resolve)"
  case "$_sel" in
    path) exec "$BIN" "$@" ;;
    npx) exec npx --yes --package "$PKG@$PINNED" "$BIN" "$@" ;;
    bunx) exec bunx --bun "$PKG@$PINNED" "$@" ;;
    none)
      collect
      emit_json >&2
      exit 78
      ;;
  esac
}

case "${1:-}" in
  where)
    resolve
    ;;
  *)
    run "$@"
    ;;
esac