AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
fix(authoring): replace mandatory recall with vocabulary-led selection
hugohe3774a605c3a6d
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 0ef3fade..82fd0b50 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -127,7 +127,7 @@ never inventories them or promotes a concrete preset, primitive, Connector,Boolean/freeform operation, or authoring parameter into a binding planningselection. A macro Reference may mention a technique as optional inspirationwithout prescribing or gating construction. The Design Spec / lock create no-native-shape field; Executor discovers the complete current preset registry and+native-shape field; Executor reads the complete current preset vocabulary andchooses the page-fit construction during realization.**Preparation timing**: In the default pipeline, topic research and import ofdiff --git a/docs/technical-design.md b/docs/technical-design.mdindex 751aec98..8bbd8b7f 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -574,7 +574,7 @@ Why both? `design_spec.md` preserves the complete confirmed solution and rationaThe view omits universal SVG/icon prohibitions already owned by the always-loaded Executor core and retains only project-specific forbidden rows. It selects images from the current page brief, explicit image-resource page assignments, and mirror prototype references. Images assigned elsewhere are excluded; any unresolved legacy image remains in a compatibility subset, and `confirmed-none` appears only when every locked image has a deterministic assignment elsewhere.-The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_visualizations` (the selected page-local `chart|table/<key>` reference, which triggers reading the corresponding family SVG and §VII Usage but does not lock the final information model, type, or geometry), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values. Each role reads the compact catalog index while deciding, freezes the selected ids, and only then reads one preset file or the exact custom references; unselected detail files never enter that role context. Qualitative Structure is described directly in §IX and generated from those relationships; it has no §VII row, `page_visualizations` key, or catalog SVG. Legacy `page_charts` remains readable but is not written by new planning; a historical Structure bare key is retained only as semantic intent without an SVG reference. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. It may use zero, one, or many catalog bases; when any are used, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`. Reference count has no fixed cap, but every listed id must contribute a distinct executable job and no second id is required for a one-basis specialization. Those ids preserve provenance, constrain synthesis to the declared bases, and route the only permitted detail-file reads. A genuinely novel custom omits the corresponding reference field. `template_reuse_scope: mirror|layout` locks additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no catalog reference or no image is often a design decision rather than missing data.+The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_visualizations` (the selected page-local `chart|table/<key>` reference, which triggers reading the corresponding family SVG and §VII Usage but does not lock the final information model, type, or geometry), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values. Each decision owner first reads its complete compact capability map: Chart planning reads the objective 33-entry expression vocabulary rather than authoring instructions, Table planning reads its small registry, and Executor reads the full 187-name preset-shape vocabulary before local contour selection. After a reference is selected, only its exact detail or implementation source enters the owning role context. Qualitative Structure is described directly in §IX and generated from those relationships; it has no §VII row, `page_visualizations` key, or catalog SVG. Legacy `page_charts` remains readable but is not written by new planning; a historical Structure bare key is retained only as semantic intent without an SVG reference. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. It may use zero, one, or many catalog bases; when any are used, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`. Reference count has no fixed cap, but every listed id must contribute a distinct executable job and no second id is required for a one-basis specialization. Those ids preserve provenance, constrain synthesis to the declared bases, and route the only permitted detail-file reads. A genuinely novel custom omits the corresponding reference field. `template_reuse_scope: mirror|layout` locks additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no catalog reference or no image is often a design decision rather than missing data.`page-context v2` remains an on-demand projector. Each invocation emits a compact global anchor set bound to `lock_source.sha256`, the current §IX/resource/routing delta, and scoped path/SHA fingerprints for large references; the projection is not a color/font allowlist or a replacement authority. It is used only for explicit diagnostics/telemetry or an unresolved page/template/visualization path-SHA question. A bounded exact repair in a valid uncompacted context may use targeted fragment readback plus validation; fresh, compacted, external, unknown, structural, or mismatched changes require one complete Design Spec and lock read. Flat pages have no prototype reference; structured pages use the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.diff --git a/docs/templates-architecture.md b/docs/templates-architecture.mdindex 3d12153b..3d09c949 100644--- a/docs/templates-architecture.md+++ b/docs/templates-architecture.md@@ -312,7 +312,7 @@ kind owns this segment”.## 3. The four index files-Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick, following the compact "meta + summary" pattern used by the Visualization catalog indexes ([Chart](../skills/ppt-master/templates/charts/charts_index.json) and [Table](../skills/ppt-master/templates/tables/tables_index.json)) while preserving structured metadata that helps selection. Qualitative Structure has no index because Executor generates it from page relationships.+Each of these four indexes maps one-to-one with its physical directory, and its fields are trimmed to what Strategist needs to select a reusable workspace. Visualization uses a separate boundary: Chart planning reads the objective [`chart-vocabulary.md`](../skills/ppt-master/templates/charts/chart-vocabulary.md), while [`charts_index.json`](../skills/ppt-master/templates/charts/charts_index.json) remains the machine registry; the small [Table registry](../skills/ppt-master/templates/tables/tables_index.json) serves both roles directly. Qualitative Structure has no index because Executor generates it from page relationships.These indexes cover library scope only. A project-root workspace is intentionally absent from all four indexes and remains usable through its explicit `projects/<name>/` path. Because both scopes use the same workspace shape, moving or copying the complete core workspace between them does not require asset-path rewriting; only library registration changes.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 81e00321..88d7c9a0 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -484,7 +484,7 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge该视图省略 Executor core 已经恒定加载的通用 SVG/图标禁令,只保留项目专属 forbidden 行。图片从当前页 brief、图片资源表中的显式页分配和 mirror 原型引用中选择;已分配给其他页面的图片会被排除,仍无法归属的 legacy 图片保留在兼容子集中,只有所有锁定图片都能确定归属到其他页面时才记录 `confirmed-none`。-这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_visualizations`(某页选中的 `chart|table/<key>` 页面级参考;它只触发读取对应 family SVG 与 §VII Usage,不锁定最终信息模型、类型或几何)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。定性 Structure 直接在 §IX 描述并根据这些关系现场生成,没有 §VII 行、`page_visualizations` key 或 catalog SVG。旧 `page_charts` 仍可读取,但新规划不再写入;历史 Structure bare key 只保留为不带 SVG reference 的语义意图。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有 catalog 参考、没有图片,很多时候是设计选择,而不是漏填。+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_visualizations`(某页选中的 `chart|table/<key>` 页面级参考;它只触发读取对应 family SVG 与 §VII Usage,不锁定最终信息模型、类型或几何)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。每个决策所有者会先读取自己完整而紧凑的能力地图:Chart 规划读取客观的 33 项表达词汇表,而不是制作说明;Table 规划读取其小型 registry;Executor 在局部轮廓选择前读取完整 187 项 preset shape 词汇表。选中参考后,只有对应的精确细节或实现来源进入职责上下文。定性 Structure 直接在 §IX 描述并根据这些关系现场生成,没有 §VII 行、`page_visualizations` key 或 catalog SVG。旧 `page_charts` 仍可读取,但新规划不再写入;历史 Structure bare key 只保留为不带 SVG reference 的语义意图。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有 catalog 参考、没有图片,很多时候是设计选择,而不是漏填。`page-context v2` 保留为按需投影器。每次调用都会输出绑定 `lock_source.sha256` 的紧凑全局锚点、当前 §IX/资源/路由 delta,以及大型引用的带 scope 路径/SHA 指纹;该投影既不是颜色/字体白名单,也不是替代权威。只有明确的诊断/统计需求,或页面/模板/可视化参考的路径-SHA 问题仍未解决时才调用。有效且未压缩的上下文中做有界精确回修,可以只回读修改片段并校验;fresh、已压缩、外部、来源不明、结构性或投影不符的修改必须完整读取 Design Spec 与 lock。flat 页面没有原型引用;structured 页面使用权威完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.mdindex db74f5e5..a35ae328 100644--- a/docs/zh/templates-architecture.md+++ b/docs/zh/templates-architecture.md@@ -269,7 +269,7 @@ Template Overview 写明可重复演示类型、目标受众与结果、交付/## 三、四套 index 文件-每个 index 跟物理目录一一对应,字段按需精简,沿用 Visualization catalog 索引([Chart](../../skills/ppt-master/templates/charts/charts_index.json) 和 [Table](../../skills/ppt-master/templates/tables/tables_index.json))的紧凑“meta + summary”模式,同时保留对 Strategist 选型有用的结构化元数据。定性 Structure 没有 index,因为 Executor 会根据当前页关系现场生成。+这四份 index 都与各自物理目录一一对应,字段只保留 Strategist 选择可复用 workspace 所需的信息。Visualization 采用另一条边界:Chart 规划读取客观的 [`chart-vocabulary.md`](../../skills/ppt-master/templates/charts/chart-vocabulary.md),[`charts_index.json`](../../skills/ppt-master/templates/charts/charts_index.json) 只保留为机器 registry;小型 [Table registry](../../skills/ppt-master/templates/tables/tables_index.json) 则直接同时承担两种职责。定性 Structure 没有 index,因为 Executor 会根据当前页关系现场生成。四套索引只覆盖全局库范围。项目根工作区有意不进入任何索引,仍可通过显式 `projects/<name>/` 路径使用。因为两种范围采用相同工作区形态,完整核心工作区可在两者之间移动或复制,不需要重写素材路径;只有全局库注册不同。diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 74850b4b..0a40ffcf 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -197,10 +197,11 @@ materialize that contour with Boolean semantics, and use freeform last. Blockarrows, chevrons, banners / ribbons, callouts, flowchart nodes, stars, and otherOffice symbols use `preset_shape_svg.py`, not plain paths or fake rectangles.-Before the first page, complete [`native-shape-authoring.md`](./native-shape-authoring.md)'s-unfiltered full-registry discovery. Decide every page-fit contour and its-simplest exact authoring form directly from the page content and visual system;-no Design Spec construction selection or material inventory gates this choice.+Before the first page, read+[`preset-shape-vocabulary.md`](./preset-shape-vocabulary.md) completely. Decide+every page-fit contour and its simplest exact authoring form directly from the+page content and visual system; no Design Spec construction selection, scorer,+or material inventory gates this choice.**Mandatory — independent per-page geometry move**: after the Structure resultand any applicable topology resolve, applydiff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.mdindex 3341a1e0..01cd88f7 100644--- a/skills/ppt-master/references/native-shape-authoring.md+++ b/skills/ppt-master/references/native-shape-authoring.md@@ -12,35 +12,29 @@ only when those constructions fail. Neither helper writes a page. The presethelper does not create the shape's own `p:txBody`; keep visible text outside theatomic fragment.-**Mandatory — semantic registry discovery at authoring entry**: before the-first newly authored page or template contour in each valid context, run the-following command unfiltered and retain its complete output. It organizes all-187 presets by the official Office gallery categories, then adds semantic-groups, scopes, and one-line intent summaries. This compact index is-authoring-time capability discovery, never a Strategist task or Design Spec-field. Rerun only after context invalidation or a registry change.+**Mandatory — complete vocabulary at authoring entry**: before the first newly+authored page or template contour in each valid context, read+[`preset-shape-vocabulary.md`](./preset-shape-vocabulary.md) completely and+retain it. It exposes all 187 exact preset names under the Office gallery and+objective contour families. This is Executor-side capability knowledge, never+a Strategist task or Design Spec field. Reread only after context invalidation+or a known file change; a filtered query cannot replace the complete read.**Hard rule — direct structured calls**: `${SKILL_DIR}` below is the retained-absolute Skill root. Invoke each JSON command once per concrete argument set-and read stdout directly. Do not change CWD, encode executables or flag lists in-scalar shell strings, batch these calls through shell loops, merge stderr, or-add a downstream parser when `--compact` exists.--```bash-python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" list --grouped-```--The plain `list` command remains a compatibility view of exact registry names;-it does not replace grouped discovery. For each page entering ordinary contour-selection, run `recommend --compact --limit 6` from the actual page role and-applicable relationship, direction, aspect, text capacity, scope, or intent-terms before choosing a contour, then run `describe <name> --compact` on the-serious candidates. Grouped discovery followed by direct `describe` does not satisfy-page-local recall. Those commands supply the full match reasons, intended uses,-misuse boundaries, adjustments, and key geometry facts omitted from the compact-entry index. Recommendation is diverse candidate recall, not a whitelist,-automatic choice, or shape quota; a neutral primitive remains valid when it-fits best. Each page still resolves the final contour through §§1–2.1.+absolute Skill root. After choosing a concrete lookup or authoring operation,+invoke that command once per argument set and read stdout directly. Do not+change CWD, encode executables or flag lists in scalar shell strings, batch+these calls through shell loops, merge stderr, or add a downstream parser when+`--compact` exists.++`list --search` and `list --grouped --search` are optional spelling/location+helpers. `recommend` is an optional heuristic fallback when the complete+vocabulary still leaves several plausible families; it is neither required+evidence nor a selection authority, and zero results never establish that a+shape is unavailable or unsuitable. Run `describe <name> --compact` only when+a serious candidate needs objective identity, adjustment, connector, path,+connection-site, or text-rectangle facts. Executor makes the final comparison+through §§1–2.1; no query narrows the already-loaded vocabulary.## 1. Contour Selection and Materialization Gate@@ -97,36 +91,37 @@ objects or their composition.----## 2. Semantic Preset Selection+## 2. Vocabulary-Guided Preset Selection-The catalog's top level follows the Office gallery taxonomy: Lines,-Rectangles, Basic Shapes, Block Arrows, Equation Shapes, Flowchart, Stars and-Banners, Callouts, and Action Buttons. The bundled semantic layer at-`scripts/pptx_shapes/data/presetShapeSemantics.json` adds authoring roles and-use boundaries; it does not redefine the DrawingML registry.+[`preset-shape-vocabulary.md`](./preset-shape-vocabulary.md) follows the Office+gallery taxonomy: Lines, Rectangles, Basic Shapes, Block Arrows, Equation+Shapes, Flowchart, Stars and Banners, Callouts, and Action Buttons. Its family+labels and objective identities expose the available contours without deciding+their page use. The optional semantic helper data does not redefine the+DrawingML registry or override Executor judgment.Apply this page-local sequence before drawing:| Pass | Action | Result ||---|---|---|| Job | State what the object must do for the reader before naming a shape. | Page role plus any real relationship, direction, aspect, text load, or literal scope. |-| Recall | Run `recommend --compact` with the known criteria. Keep the default `general` scope unless the page truly needs `literal`, `flowchart`, or `navigation`. | A group-diverse candidate set with match reasons and misuse boundaries. |-| Inspect | Run `describe --compact` for candidates whose contour could fit; compare `intent`, `recommended_for`, `avoid_for`, adjustments, text rectangle, and connection sites. | Evidence for choosing or rejecting each serious candidate. |+| Browse | Compare that job against the complete loaded vocabulary; move from Office category to contour family to exact name. | A small candidate set chosen by meaning, not scorer rank or syntax convenience. |+| Inspect | When exact facts could change the decision, run `describe --compact` directly for those candidates and compare identity, scope, adjustments, connector status, paths, text rectangle, and connection sites. | Objective geometry evidence without prescribed use. || Select | Choose the contour whose inference and visual character fit the page, including a neutral primitive when neutrality is useful. | One page-fit contour; no syntax decision yet. || Encode | Apply §1's materialization gate. | Ordinary SVG primitive, helper-authored preset, Boolean result, or necessary freeform. |-Example recall and inspection commands:+Example location and inspection commands:```bash-python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" recommend --compact \- --role spine --relationship order --directionality horizontal --aspect wide \- --limit 6python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" describe chevron --compact--python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" recommend --compact \- --scope flowchart --role node --relationship flow --query decision --limit 6+python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" list --search connector```+**Reference — not a constraint**: `recommend --compact` remains available as a+legacy-compatible heuristic for an unresolved family search. Read it as another+browse aid only; its filters, scores, and returned limit cannot prove fit,+misfit, or absence.+**Hard rule — semantic fit, not name association**: a preset name, topic word,or metaphor is not evidence of use. Respect `literal_only` and `scope` beforevisual preference. For example, a scroll is not a generic playbook carrier, a@@ -135,10 +130,9 @@ lightning bolt is not generic price tension, `chartX` / `chartStar` /belongs only in an actual flowchart. An action-button preset supplies visualgeometry only; it never creates an action or hyperlink.-The semantic catalog chooses contours, not syntax. It never requires `rect`,-`ellipse`, `line`, or any other primitive to pass through the preset helper;-after selection, the simplest exact authoring form in §1 remains authoritative.-Export never scans or upgrades existing geometry.+The vocabulary exposes contours; Executor chooses them, and §1 chooses syntax.+It never requires `rect`, `ellipse`, `line`, or any other primitive to pass+through the preset helper. Export never scans or upgrades existing geometry.**Shape-first diagram rule**: use `<line>` for straight thin relationships;use an exact connector-family preset for a stock bent or curved contour; use adiff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 78fd0ce7..7f759c74 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -341,9 +341,10 @@ no-AI or editable-only requirements win. Execution follows1. Before authoring Stage-2 directions, load the workflow's complete fixedplanning-capability batch. It includes this module, the image-layout- authorities, all compact choice indexes, the icon-library contract, and the- complete Chart/Table registries. After the three whole-direction intents- exist and their mode/style/rendering reference ids are frozen, read only+ authorities, all compact decision maps, the icon-library contract, the+ complete Chart expression vocabulary, and the Table registry. After the+ three whole-direction intents exist and their mode/style/rendering reference+ ids are frozen, read onlythose exact detail siblings once and author one complete custom renderinginside each direction before deciding whether `recommend.image_usage`includes AI.@@ -411,17 +412,18 @@ Classify by information model, never source PowerPoint object type:| Model | Planning action ||---|---|| Qualitative `order`, `link`, `parent`, `membership`, `contrast`, or `overlap` | Preserve units, relationship, and reading path as free §IX prose; no catalog key |-| Values/dates/durations determine geometry | Chart; compare the complete loaded chart registry |+| Values/dates/durations determine geometry | Chart; compare the complete loaded chart expression vocabulary || Row header × column header addresses each fact | Table; compare the complete loaded table registry |**Mandatory — relationship handoff**: keep every qualitative relationship in §IX free prose; never serialize grammar atoms, coordinates, or named models. Executor makes the per-page Structure decision at runtime.**Mandatory — complete Chart/Table capability review**: During the same §IX-roster composition, compare every page's information model against every-`Pick` / `Skip` rule in the two already-loaded live registries. The registries-expose the possibility space; they are neither usage quotas nor whitelists.-Skip custom objects and qualitative composition. Retain `no-template-match`-when no registered reference fits.+roster composition, compare every page's information model against every entry+in the already-loaded Chart expression vocabulary and Table registry. These+complete capability maps expose what can be selected; their descriptions do+not rank candidates or replace judgment from the actual information. They are+neither usage quotas nor whitelists. Skip custom objects and qualitative+composition. Retain `no-template-match` when no registered reference fits.**Selection**:@@ -434,7 +436,7 @@ python3 skills/ppt-master/scripts/visualization_recall.py validate \<family>/<key> [<family>/<key> ...]```-Correct failed selections by re-reading the complete registries;+Correct failed selections by re-reading the complete vocabulary/registry;`no-template-match` never enters `page_visualizations`.**Section VII selection list**: write `Page | Family | Template | Usage` for each `chart|table` reference; Usage is semantic purpose. Omit empty/no-match detail. Qualitative composition stays in §IX; only Layout/Deck owns reusable PowerPoint structure.diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 864ff20a..b6b02408 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -197,9 +197,7 @@ python3 scripts/pptx_delivery_check.py <finished.pptx>Native preset shape authoring (one or more registry-backed fragments on stdout):```bash-python3 scripts/preset_shape_svg.py list --grouped-python3 scripts/preset_shape_svg.py recommend --compact --role spine --relationship order \- --directionality horizontal --aspect wide --limit 6+python3 scripts/preset_shape_svg.py list --search arrowpython3 scripts/preset_shape_svg.py describe rightArrow --compactpython3 scripts/preset_shape_svg.py render rightArrow --id process-arrow --frame 120 180 240 96 --fill '#2563EB'python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'@@ -211,23 +209,23 @@ python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'JSON```-`list --grouped` is the compact entry index: it organizes the exact 187-name-registry under the official Office gallery categories, then exposes semantic-groups, scopes, one-line intent summaries, and grouped preset names. Full match-reasons, intended uses, and misuse boundaries remain page-local in `recommend`-and `describe` instead of being repeated in the mandatory discovery output.-`recommend` recalls candidates from page-job criteria; its default `general`-scope excludes literal-only symbols, flowchart notation, and action controls.-Its result is neither a whitelist nor an automatic selection.-`recommend --compact` keeps criteria, counts, selection note, and each-candidate's preset, scope, literal boundary, intent, match reasons, and misuse-boundaries; plain `recommend` preserves the full payload. The-`describe --compact` view returns one flat object with semantic boundaries,-adjustments, connection/text facts, and path count. Plain `describe` preserves-the full nested geometry/semantics payload. A zero-match recommendation is-valid JSON with exit code 0 so the caller can relax its criteria; a zero-match-`list --search` remains a failed lookup with exit code 1. Plain-`list [--search QUERY]` remains the compatibility name view.+Runtime capability discovery reads+[`preset-shape-vocabulary.md`](../references/preset-shape-vocabulary.md), which+lists all 187 exact names by Office category and objective contour family.+`list [--search QUERY]` and `list --grouped [--search QUERY]` remain optional+location and compatibility views; they do not replace the complete vocabulary.+`describe --compact` returns the selected preset's objective identity, Office+category, family, scope, literal boundary, adjustments, connector/path facts,+connection sites, and text-rectangle availability. Plain `describe` preserves+the full nested legacy semantics payload.++`recommend` remains an optional heuristic browse aid for unresolved family+searches. Its result is neither a whitelist nor an automatic selection, and a+zero-match result is not evidence that a preset is absent or unsuitable.+`recommend --compact` keeps criteria, counts, selection note, and reduced+candidate records; plain `recommend` preserves the full payload. A zero-match+recommendation is valid JSON with exit code 0; a zero-match `list --search`+remains a failed lookup with exit code 1.The helper never writes a page or project file. Select one exact semanticstock-shape match, inspect the emitted fragment, and insert it into thediff --git a/skills/ppt-master/scripts/docs/visualization-recall.md b/skills/ppt-master/scripts/docs/visualization-recall.mdindex 1f4d794a..c8ff1c25 100644--- a/skills/ppt-master/scripts/docs/visualization-recall.md+++ b/skills/ppt-master/scripts/docs/visualization-recall.md@@ -1,13 +1,15 @@# Visualization Candidate Recall-Default Strategist and the Quick Generate main agent read both complete compact-registries before planning. `visualization_recall.py validate` resolves their-selected canonical references. Its `recall` command remains an optional-deterministic diagnostic across the same live Chart and Table registries; it is-not the runtime capability-discovery gate and cannot replace the complete-registry review. The tool reads these indexes on every invocation and maintains-no second category or keyword index:-+Default Strategist and the Quick Generate main agent read the complete Chart+expression vocabulary and Table registry before planning.+`visualization_recall.py validate` resolves their selected canonical+references. Its `recall` command remains an optional deterministic diagnostic+across the machine Chart and Table registries; it is not the runtime+capability-discovery gate and cannot replace the complete planning review. The+tool reads these indexes on every invocation and maintains no second category+or keyword index:++- `templates/charts/chart-vocabulary.md` — planning capability map, not read by this tool- `templates/charts/charts_index.json`- `templates/tables/tables_index.json`@@ -35,11 +37,10 @@ boundary certain; the default `all` preserves unified Chart/Table recall.`tail`, `head`, `grep`, or another truncator can discard higher-rankedcandidates. `confidence` reports lexical strength only and never decides fit.-At `high` / `medium`, retain `no-template-match` when none fits. At `low` /-`none`, select a fitting bounded candidate directly; otherwise rerun the same-command once with `--semantic-fallback` to inspect its diagnostic payload. The-runtime owner still bases selection on the complete registries already loaded-before planning.+At any confidence, compare the diagnostic candidates against the complete+planning maps already loaded. `--semantic-fallback` only exposes another+diagnostic payload; it never requires a selection. Retain `no-template-match`+when none fits.| Field | Contract ||---|---|@@ -84,8 +85,9 @@ it without catalog lookup.## Selection boundary-- Runtime selection comes from the complete loaded registries; recall output is- optional diagnostic evidence, while `validate` resolves positive selections.+- Runtime selection comes from the complete loaded Chart vocabulary and Table+ registry; recall output is optional diagnostic evidence, while `validate`+ resolves positive selections.- Default records `Page | Family | Template | Usage` for each positiveselection and projects `family/key` into `page_visualizations`.- Usage is one concise page-local purpose; detailed adaptation remains in §IX.diff --git a/skills/ppt-master/scripts/pptx_shapes/semantics.py b/skills/ppt-master/scripts/pptx_shapes/semantics.pyindex 75e7f2c4..a75125a5 100644--- a/skills/ppt-master/scripts/pptx_shapes/semantics.py+++ b/skills/ppt-master/scripts/pptx_shapes/semantics.py@@ -374,11 +374,12 @@ class PresetShapeSemantics:"candidate_count": len(candidates),"returned_count": min(len(ordered), limit),"selection_note": (- "Candidate recall only. Compare contour, content fit, and avoid_for "- "before choosing; this is neither a whitelist nor an automatic choice."+ "Heuristic browse candidates only. Compare them against the complete "+ "vocabulary and page context; scores, filters, and the returned limit "+ "do not decide fit or absence."if ordered- else "No candidates matched. This is a valid recall result; relax or "- "change the criteria before selecting a contour."+ else "No heuristic candidates matched. This does not prove absence; "+ "select from the complete vocabulary directly or change the criteria."),"candidates": ordered[:limit],}diff --git a/skills/ppt-master/scripts/preset_shape_svg.py b/skills/ppt-master/scripts/preset_shape_svg.pyindex fc16e7a7..9318eca4 100644--- a/skills/ppt-master/scripts/preset_shape_svg.py+++ b/skills/ppt-master/scripts/preset_shape_svg.py@@ -2,9 +2,9 @@"""PPT Master - Preset Shape SVG Fragment Tool-Browse and recommend DrawingML presets, or print compact canonical-native-preset SVG groups to stdout for manual insertion into a hand-authored-page or template.+Browse and inspect DrawingML presets, optionally run heuristic recall, or print+compact canonical native-preset SVG groups to stdout for manual insertion into+a hand-authored page or template.Usage:python3 scripts/preset_shape_svg.py list [--grouped] [--search QUERY]@@ -14,9 +14,7 @@ Usage:python3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASHExamples:- python3 scripts/preset_shape_svg.py list --grouped- python3 scripts/preset_shape_svg.py recommend --role spine \- --relationship order --directionality horizontal --compact+ python3 scripts/preset_shape_svg.py list --search arrowpython3 scripts/preset_shape_svg.py describe rightArrow --compactpython3 scripts/preset_shape_svg.py render rightArrow --id next-step \--frame 160 210 320 112 --fill "#2563EB" --stroke none@@ -103,21 +101,20 @@ def build_parser() -> argparse.ArgumentParser:describe_parser = subparsers.add_parser("describe",- help="Print preset geometry and semantic metadata as JSON.",+ help="Print preset geometry and identity metadata as JSON.",)describe_parser.add_argument("preset", help="DrawingML preset name.")describe_parser.add_argument("--compact",action="store_true",help=(- "Print one flat selection view with semantic boundaries and key "- "geometry facts."+ "Print one flat objective identity view with key geometry facts."),)recommend_parser = subparsers.add_parser("recommend",- help="Recall semantically matched preset candidates as JSON.",+ help="Optionally recall heuristic preset candidates as JSON.",)recommend_parser.add_argument("--role",@@ -330,9 +327,11 @@ def main(argv: Sequence[str] | None = None) -> int:payload = ({"preset": definition.name,- "intent": semantics["intent"],- "recommended_for": semantics["recommended_for"],- "avoid_for": semantics["avoid_for"],+ "identity": semantics["intent"],+ "office_category": semantics["office_category_label"],+ "family": semantics["label"],+ "scope": semantics["scope"],+ "literal_only": semantics["literal_only"],"adjustments": adjustments,"connector_preset": connector_preset,"path_count": path_count,diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.mdindex 6fe5d9b6..eb84a225 100644--- a/skills/ppt-master/templates/README.md+++ b/skills/ppt-master/templates/README.md@@ -119,14 +119,14 @@ effects and PowerPoint interfaces loaded only when triggered.Page-local Shape-first references are catalog families, not reusable templatekinds:-| Family | Owns | Directory | Index |+| Family | Owns | Planning map | Machine index ||---|---|---|---|-| Chart | Value-driven geometry (33) | [`charts/`](./charts/) | [`charts_index.json`](./charts/charts_index.json) |-| Table | Row × column fact grid (6) | [`tables/`](./tables/) | [`tables_index.json`](./tables/tables_index.json) |+| Chart | Value-driven geometry (33) | [`chart-vocabulary.md`](./charts/chart-vocabulary.md) | [`charts_index.json`](./charts/charts_index.json) |+| Table | Row × column fact grid (6) | [`tables_index.json`](./tables/tables_index.json) | [`tables_index.json`](./tables/tables_index.json) |[`VISUALIZATION_TEMPLATE_AUTHORING.md`](./VISUALIZATION_TEMPLATE_AUTHORING.md)-is the shared authoring contract. Each index owns family membership and-selection rules.+is the shared authoring contract. Each machine index owns family membership;+the Chart vocabulary is its complete objective planning projection.Qualitative Structure is a Slide-local Executor method rather than a catalog:Default and Quick both derive its relationship model and compose shapes for thediff --git a/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md b/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.mdindex 47cb94bc..706d4bf4 100644--- a/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md+++ b/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md@@ -317,14 +317,14 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与**Forbidden — placeholder storytelling**: 不写长篇营销文案、部门归属、真实品牌或无法复用的项目背景。-### 7.2 Family indexes+### 7.2 分类索引与规划投影新增模板只登记到其 owning family index:-| Family | Directory | Index object |-|---|---|---|-| `chart` | `charts/` | `charts_index.json` → `charts` |-| `table` | `tables/` | `tables_index.json` → `tables` |+| 分类 | 目录 | 机器索引 | 规划词汇表 |+|---|---|---|---|+| `chart` | `charts/` | `charts_index.json` → `charts` | `chart-vocabulary.md` |+| `table` | `tables/` | `tables_index.json` → `tables` | 同一份紧凑注册表 |每个 `<key>.summary` 使用相同的选择句合同:@@ -334,7 +334,13 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与}```-**Hard rule**: `summary` 是选型句,使用 `Pick for ... Skip if ...`,不是视觉描述;`key` 与同 family 文件名一致,`meta.total` 与该 family catalog 数量一致。不要建立跨 family 的第二份成员清单。+`summary` 保留 `Pick for ... Skip if ...` 句式,供可选的机器召回诊断使用;+规划主路径不读取这些记录。Chart 的 `chart-vocabulary.md` 必须完整列出同一组+canonical `chart/<key>`,只说明信息关系,不写 SVG 实现、布局参数或选择结论。++**Hard rule**: `key` 与同 family 文件名一致,`meta.total` 与该 family catalog+数量一致;Chart vocabulary 与 index 的成员集合必须精确一致。除此以外不要建立+跨 family 的第二份成员清单。---diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.mdindex 700fb5d5..bbf00d4b 100644--- a/skills/ppt-master/templates/charts/README.md+++ b/skills/ppt-master/templates/charts/README.md@@ -9,21 +9,27 @@ Cell-grid semantics belong in [`tables/`](../tables/). Reusable PowerPointMaster/Layout, page-type, slot, and placeholder contracts belong in[`layouts/`](../layouts/).-## Source of truth+## Planning vocabulary and source of truth[`charts_index.json`](./charts_index.json) is the sole chart registry. Its`charts` object maps each canonical key to one selection-rule `summary` in theform `Pick for ... Skip if ...`. The key matches `<key>.svg`; `meta.total`matches the canonical SVG roster.-Default Strategist and Quick read this complete compact registry together with-the Table registry before planning. They compare every `Pick` / `Skip` rule,-then use [`visualization_recall.py`](../../scripts/visualization_recall.py)-`validate` to resolve selected canonical references. Its `recall` mode remains-an optional diagnostic helper, not the runtime capability gate. Default writes-`chart/<key>` to `page_visualizations`; Quick keeps the selected reference in-active context. [`chart_recall.py`](../../scripts/chart_recall.py) and bare keys-remain legacy compatibility only.+[`chart-vocabulary.md`](./chart-vocabulary.md) is the complete planning+projection. It lists all 33 exact `chart/<key>` references by information+relationship and states only what each encoding represents. It contains no+chart-authoring instructions and does not prescribe selection.++Default Strategist and Quick read the vocabulary together with the Table+registry before planning, choose through their own judgment, then use+[`visualization_recall.py`](../../scripts/visualization_recall.py) `validate`+to resolve selected canonical references. Its `recall` mode remains an+optional diagnostic helper over the machine registry, not the runtime+capability gate. Default writes `chart/<key>` to `page_visualizations`; Quick+keeps the selected reference in active context. Executor then reads only the+selected SVG and execution references. [`chart_recall.py`](../../scripts/chart_recall.py)+and bare keys remain legacy compatibility only.## Authoring contractdiff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex cca2d70e..7dbe9f51 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -280,7 +280,7 @@ Read references/modes/_index.mdRead references/visual-styles/_index.mdRead references/image-renderings/_index.mdRead templates/icons/README.md-Read templates/charts/charts_index.json+Read templates/charts/chart-vocabulary.mdRead templates/tables/tables_index.json```@@ -611,6 +611,7 @@ construction block plus the resolved mode/style detail files as one batch:Read references/shared-standards-core.md # REQUIRED: SVG compatibility + shared aesthetic/leading baselineRead references/svg-effects.md # REQUIRED: Visual Job Router + effects/construction vocabularyRead references/native-shape-authoring.md # REQUIRED: native-shape selection and Boolean construction+Read references/preset-shape-vocabulary.md # REQUIRED: complete 187-name authoring vocabularyRead references/executor-structure.md # REQUIRED: qualitative relationship and topology grammarRead references/semantic-svg.md # REQUIRED: semantic metadata boundaryRead references/modes/<resolved-id>.md # one preset id, or each `mode_references` id@@ -672,7 +673,7 @@ sidecars, or guessed family paths.**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`-Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Native shapes are Executor-local authoring capabilities, not planned resources: follow [`native-shape-authoring.md`](../references/native-shape-authoring.md), load its complete current preset inventory before the first page, choose page-fit contours before their authoring forms, keep exact native atoms independent when possible, materialize a Merge Shapes Boolean result only where contour semantics require it, and use necessary freeform last. Diagram relationships follow the same Shape-first gate; do not infer a preset from contour similarity.+Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Native shapes are Executor-local authoring capabilities, not planned resources: follow [`native-shape-authoring.md`](../references/native-shape-authoring.md), read the complete current preset vocabulary before the first page, choose page-fit contours before their authoring forms, keep exact native atoms independent when possible, materialize a Merge Shapes Boolean result only where contour semantics require it, and use necessary freeform last. Diagram relationships follow the same Shape-first gate; do not infer a preset from contour similarity.**Motion-ready image composition**: Only when an explicit user motioninstruction, the effective Custom Animations outcome in `design_spec.md §I` isdiff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex a98b809d..100c41a0 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -255,7 +255,7 @@ Read references/modes/_index.mdRead references/visual-styles/_index.mdRead references/image-renderings/_index.mdRead templates/icons/README.md-Read templates/charts/charts_index.json+Read templates/charts/chart-vocabulary.mdRead templates/tables/tables_index.json```@@ -420,14 +420,16 @@ This carrier menu does not satisfy or replace the per-page Structure decision inResolving one visual style, `Illus.` propensity, or generated-image rendering resolves how imagery **looks**; it resolves the source for no page. A named place, building, product, artwork, person, or other externally verifiable subject stays a web/supplied candidate no matter how illustrative the deck looks. When such a subject is deliberately not shown as itself, state that choice and its reason in the final report rather than leaving it implicit.**Mandatory — complete Chart/Table capability review**: During that same-carrier resolution, compare every page's information model against every-`Pick` / `Skip` rule in the two already-loaded live registries. The registries-expose the possibility space; they are neither usage quotas nor whitelists. Do-not select a catalog reference for qualitative shape composition. Choose at-most one primary Chart/Table `family/key` for a page, validate it with-`visualization_recall.py validate`, and keep its short purpose only in active-context. Retain `no-template-match` when none fits. The reference remains-flexible: it does not lock final type, geometry, style, or native output.+carrier resolution, compare every page's information model against every entry+in the already-loaded Chart expression vocabulary and Table registry. These+complete capability maps expose what exists; their descriptions do not rank+candidates or replace judgment from the actual information, and they are+neither usage quotas nor whitelists. Do not select a catalog reference for+qualitative shape composition. Choose at most one primary Chart/Table+`family/key` for a page, validate it with `visualization_recall.py validate`,+and keep its short purpose only in active context. Retain `no-template-match`+when none fits. The reference remains flexible: it does not lock final type,+geometry, style, or native output.Describe an embedded child Chart/Table and every qualitative relationship inthe page's active decision rather than selecting another primary reference.Actual information models determine the loaded execution branches. Give every independent@@ -495,6 +497,7 @@ not route among them one file at a time:[`shared-standards-core.md`](../../references/shared-standards-core.md),[`svg-effects.md`](../../references/svg-effects.md),[`native-shape-authoring.md`](../../references/native-shape-authoring.md),+[`preset-shape-vocabulary.md`](../../references/preset-shape-vocabulary.md),[`semantic-svg.md`](../../references/semantic-svg.md),and [`executor-structure.md`](../../references/executor-structure.md). Retainonly the mode/style detail files selected during one-pass design resolution and@@ -517,8 +520,8 @@ Reread only after a known file change or context invalidation.`Structure=yes` result can apply its qualitative topology grammar.`native-shape-authoring.md` independently owns contour selection and compoundpage geometry for both Structure results. Reuse both throughout the valid-execution context; before P01, complete its unfiltered full-registry discovery,-then reread only after a known file change or context invalidation.+execution context; before P01, read the complete preset vocabulary once, then+reread only after a known file change or context invalidation.**Mandatory — per-image-page composition decision**: For every page with oneor more images, after its content and communication move are@@ -562,14 +565,14 @@ This decision is mandatory on every page and cannot be satisfied by thecapability menu, visualization recall, template geometry, or a later check.**Mandatory — independent per-page geometry move**: after the Structure result-and any applicable topology resolve, but before choosing any contour, run the-page-local direct `recommend --compact --limit 6` invocation defined by-[`native-shape-authoring.md`](../../references/native-shape-authoring.md) from-the actual job, then invoke `describe --compact` directly only for serious-candidates. Registry discovery followed by direct `describe` without-`recommend` does not satisfy this recall. Apply §2.1 to the transient geometry-job, actual content, resolved style, and complete native vocabulary before-writing coordinates. It owns the exact-fit geometry gate, independent+and any applicable topology resolve, apply+[`native-shape-authoring.md`](../../references/native-shape-authoring.md) §2.1+to the transient geometry job, actual content, resolved style, and complete+loaded native vocabulary before writing coordinates. Select through direct+semantic comparison; use `describe --compact` only when objective geometry+facts could change a serious candidate decision. Optional search or+recommendation output cannot narrow or replace the vocabulary. This move owns+the exact-fit geometry gate, independentrelationship / carrier fit,contour-family / exact-result choice, reader effect for a generic or undrawnresult, running actual-geometry signature, and materialization boundary. A@@ -743,7 +746,7 @@ or lock.- [x] All required source/resource preparation is complete- [x] The fixed planning-capability batch was read before the roster, and every selected detail source was read-- [x] The complete native preset registry was read unfiltered before P01; every page entering ordinary contour selection ran job-derived `recommend` before choosing a contour and described only serious candidates+- [x] The complete 187-name native preset vocabulary was read before P01; each page chose from that full capability surface, with objective candidate details inspected only when needed- [x] Every page considered suitable carrier combinations without a coverage quota or single-carrier assumption- [x] The proactive decorative-lettering scan ran before capability resolution; every exact string passing both eligibility questions entered an AI item or lettering sheet/slice job unless the user forbade AI- [x] Every page not bound to literal supplied geometry carried its geometry job into authoring, resolved each drawn contour from its exact family and job, retained the reader effect for any generic or undrawn result, and compared its actual geometry signature before the next page; repetition served the same page job / relationship or continuity motif