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(execution): avoid full reloads after bounded spec repairs
hugohe329247cf069d3
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 7191d683..37ff42cd 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -383,7 +383,7 @@ The view omits universal SVG/icon prohibitions already owned by the always-loadeThe lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values that decide which execution rule files are loaded. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. When it actually combines or borrows catalog entries, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`, and execution reads every listed file before synthesis; a genuinely novel custom omits the corresponding reference field. Page-context projects these fields instead of leaving Executor with only literal `custom` ids. `template_reuse_scope: mirror|layout` projects 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 chart or no image is often a design decision rather than missing data.-`page-context v2` separates bounded continuity state from large references. It deliberately repeats the compact global anchor set on every page and binds it to `lock_source.sha256`; that set is not a color/font allowlist. The current §IX brief, rhythm, image choice, and template/chart assignment form the page delta. The project/template Design Specs plus selected prototype and `templates/charts/<key>.svg` files appear only as scoped path/SHA fingerprints. Executor reads one of those files only when that fingerprint is absent from the active context or changed, then reuses the retained understanding. Flat pages have no prototype reference; structured pages reference the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.+`page-context v2` separates bounded continuity state from large references. It deliberately repeats the compact global anchor set on every page and binds it to `lock_source.sha256`; that set is not a color/font allowlist. The current §IX brief, rhythm, image choice, and template/chart assignment form the page delta. The project/template Design Specs plus selected prototype and `templates/charts/<key>.svg` files appear only as scoped path/SHA fingerprints. Executor reads one of those files only when that fingerprint is absent from the active context or changed, then reuses the retained understanding. The project Design Spec fingerprint additionally advertises `same_context_edit_policy: targeted-readback-and-rebind`: a bounded exact repair authored by the current main agent, with roster/order/identity/communication unchanged, is verified by targeted fragment readback, validation, and a rebuilt page context, then the retained understanding is rebound to the new SHA without reloading the whole document. Fresh, external, unknown, structural, or mismatched changes still require one complete read. Flat pages have no prototype reference; structured pages reference the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.`--record-usage` writes a derived, input-hashed compact-output snapshot for that page under `analysis/page-context/`. Token counting lazily uses `o200k_base`; a missing `tiktoken` installation records `tokens: null` without blocking execution. `page-context-report` excludes stale snapshots, reports compact page-context totals, and lists unique reference fingerprints. The once-loaded reference payloads and other session context remain intentionally unmeasured.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex a201a893..9b44f093 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -379,7 +379,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。page-context 会把这些字段投影给 Executor,而不是只留下字面上的 `custom` id。`template_reuse_scope: mirror|layout` 项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。-`page-context v2` 把有界的连续性状态与大型引用分开。它有意在每页重复紧凑的全局锚点集,并用 `lock_source.sha256` 绑定版本;这个集合不是颜色/字体白名单。当前 §IX brief、节奏、图片选择和模板/图表分配构成逐页 delta。项目/模板 Design Spec、选中的原型,以及 `templates/charts/<key>.svg` 只以带 scope 的路径/SHA 指纹出现。只有该指纹不在当前执行上下文中或 SHA 已变化时,Executor 才读取文件一次;后续页面直接复用已有理解。flat 页面没有原型引用;structured 页面引用权威的完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。+`page-context v2` 把有界的连续性状态与大型引用分开。它有意在每页重复紧凑的全局锚点集,并用 `lock_source.sha256` 绑定版本;这个集合不是颜色/字体白名单。当前 §IX brief、节奏、图片选择和模板/图表分配构成逐页 delta。项目/模板 Design Spec、选中的原型,以及 `templates/charts/<key>.svg` 只以带 scope 的路径/SHA 指纹出现。只有该指纹不在当前执行上下文中或 SHA 已变化时,Executor 才读取文件一次;后续页面直接复用已有理解。项目 Design Spec 的指纹还会声明 `same_context_edit_policy: targeted-readback-and-rebind`:当前主代理基于已保留内容做有界精确回修,且页清单、叙事顺序、确认身份与沟通契约均未改变时,只回读修改片段、执行校验并重建 page-context,然后把既有整体理解和已验证 delta 绑定到新 SHA,无需重新加载整份文档。fresh、外部、来源不明、结构性或投影不符的修改仍必须完整读取一次。flat 页面没有原型引用;structured 页面引用权威的完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。`--record-usage` 在 `analysis/page-context/` 下写入当前页的派生快照,记录输入 hash 和紧凑 stdout 的实测大小。token 计数按需加载 `o200k_base`;没有安装 `tiktoken` 时写入 `tokens: null`,但不阻塞执行。`page-context-report` 排除过期快照,汇总紧凑 page-context,并列出唯一引用指纹;一次加载的大型引用 payload 与其他会话上下文有意不纳入统计。diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex b3c26fce..a97e3aaa 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -20,7 +20,7 @@ Global artifact ownership rules for PPT Master projects.| `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes || `design_spec.md` | Strategist design authority | Human-readable design intent, final page wording, rationale, resource plan, and confirmed production mechanics authored from the final confirmation plus source analysis | Strategist consumes the final confirmation once, writes and audits every confirmed field here, then later roles read this artifact instead of reopening `result.json`; after Gate 1, §IX is the Executor's page-content authority. || `spec_lock.md` | Execution anchor and routing contract | Machine-readable stable color/type roles, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist authors the route-specific anchors from the audited Design Spec plus current project/page/template context. `page-context` repeats that compact anchor set per page and adds current-page routing values. Sparse page-local color/font garnish needs no lock row; a recurring semantic role or new adaptive Layout identity requires Strategist repair before reuse. |-| `project_manager.py page-context` stdout | Derived per-page context | Read-only model-facing anchor set + current-page delta + fingerprints for large references | Generate immediately before each page without `--bundle`; never edit or persist it as a replacement source of truth. `global` is the bounded repeated anchor set, not a whitelist of every valid page-local value. `reference_set` carries path/SHA/load policy for project/template Design Specs and selected prototype/chart SVGs, but never appends their payloads. |+| `project_manager.py page-context` stdout | Derived per-page context | Read-only model-facing anchor set + current-page delta + fingerprints for large references | Generate immediately before each page without `--bundle`; never edit or persist it as a replacement source of truth. `global` is the bounded repeated anchor set, not a whitelist of every valid page-local value. `reference_set` carries path/SHA/load policy for project/template Design Specs and selected prototype/chart SVGs, but never appends their payloads. The project Design Spec alone may carry `same_context_edit_policy` for verified targeted readback/rebind after the current main agent's own repair. || `analysis/page-context/P<NN>.usage.json` | Derived context telemetry | Actual compact page-context size plus hashes of owning inputs/references | `page-context --record-usage` deterministically replaces that page's snapshot; `page-context-report` summarizes current snapshots and unique references. Use token data to evaluate context cost, never as content or an execution contract. || `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Step 5 writes here; `analysis/image_analysis.csv` derives from current contents || `icons/` | Project icon inventory | Icons copied by `icon_sync.py` for this project | Executor uses locked project icons; exporter may fall back to global library only as documented |diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex c49fdd0c..cd2d6925 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -57,11 +57,13 @@ python3 skills/ppt-master/scripts/project_manager.py page-context <project_path>`global` deliberately repeats the sub-1000-token cross-page anchor set; `lock_source.sha256` binds its version. These anchors preserve identity and recurring semantics but do not enumerate every legal color or font. `page_context` is the current §IX/resource/template/chart delta. For every `reference_set` entry—project/template Design Spec or selected prototype/chart SVG—reuse an in-context path + SHA; read it once only when absent or changed.+**Hard rule — known same-context Design Spec repair**: When the current main agent returns to Strategist and authors an exact project `design_spec.md` repair from its retained state, the `design-spec` reference's `same_context_edit_policy: targeted-readback-and-rebind` avoids a full reread. This applies only to bounded repairs that keep the page roster, narrative order, confirmed identity, and communication contract unchanged. Repair the owning Design Spec headings/page blocks first, re-author only affected lock rows, read back those changed fragments, run `project_manager.py validate`, then rerun `page-context` for every affected page. If each projected brief/global view matches the intended repair, bind the retained whole-document understanding plus verified delta to the new Design Spec SHA. A fresh context, an external/unknown edit, a roster/global-contract change, an unexpected diff, failed validation, or mismatched projection requires one full Design Spec read before continuing.+**Hard rule — exact page roster**: `design_spec.md §IX` is the ordered queue: one final slide per entry, with the same id/order. The UI range no longer applies. Never add, drop, merge, split, or reorder; repair/reconfirm the Design Spec first.**Hard rule — selection vs realization**: use Strategist-selected content, resources/paths, chart/layout keys, core fonts, palette anchors, icons, and crop boundaries. Adapt realization, never selection, except sparse local font/color garnish allowed below. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Selection changes require upstream repair.-Use named lock roles literally when that role applies, and use optional `Template Application` from the retained Design Spec. Choose contextual page-local values from the Design Spec, style, content, and current composition rather than forcing every object into a lock row. The delta overrides neither facts nor constraints. After an approved change, rerun the command and reload only changed references. Deprecated `--bundle` is a compatibility no-op.+Use named lock roles literally when that role applies, and use optional `Template Application` from the retained Design Spec. Choose contextual page-local values from the Design Spec, style, content, and current composition rather than forcing every object into a lock row. The delta overrides neither facts nor constraints. After an approved change, rerun the command; reload changed references except the verified same-context Design Spec repair above. Deprecated `--bundle` is a compatibility no-op.**Source verification**: `design_spec.md §IX` owns the final page wording; the page delta does not carry the complete source corpus. Read relevant `sources/` content only to resolve listed `Fact IDs` or verify exact claims, quotes, names, or data already required by the current §IX block. Do not enrich, expand, or substitute the authored content. An underspecified §IX block is an upstream defect; return for Design Spec repair.diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex 96fd607b..a2fd763f 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -83,10 +83,14 @@ The output deliberately repeats the bounded `global` anchor set on everypage as a cross-page anchor set, not a color/font allowlist. `lock_source` binds that projection to the current`spec_lock.md` SHA. `page_context` contains the current §IX brief, rhythm,resources, and conditional template/chart assignment. `reference_set` contains-only `kind`, scoped path, SHA, and `once-per-execution-context` policy for the-project/template Design Specs and selected prototype/chart SVGs. A model reads-a referenced file only when that exact path + SHA is absent from its active-context or has changed, then reuses the retained understanding on later pages.+`kind`, scoped path, SHA, and `once-per-execution-context` policy for the+project/template Design Specs and selected prototype/chart SVGs. The project+Design Spec additionally carries+`same_context_edit_policy: targeted-readback-and-rebind`: when the current main+agent makes a bounded repair that preserves roster/order/identity/communication,+it reads back only the exact changed fragments,+validates, reruns `page-context`, and binds the verified delta to the new SHA.+Fresh, external, unknown, or mismatched changes still require a complete read.The deprecated `--bundle` flag remains accepted as a compatibility no-op. Itnever appends a Design Spec, prototype SVG, chart SVG, manifest, or text-slotdiff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 24146da3..cd3a3414 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -17,7 +17,7 @@"file_budgets": {"AGENTS.md": 2300,"skills/ppt-master/SKILL.md": 800,- "skills/ppt-master/references/executor-base.md": 6900,+ "skills/ppt-master/references/executor-base.md": 7050,"skills/ppt-master/references/executor-structured.md": 5300,"skills/ppt-master/references/executor-chart.md": 3100,"skills/ppt-master/references/executor-image.md": 900,@@ -306,7 +306,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 80750+ "max_tokens": 80950},"route.generate.flat-ai-two-types": {"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",@@ -319,7 +319,7 @@"stage.generate.image.ai-two-types"],"files": [],- "max_tokens": 120900+ "max_tokens": 121150},"route.generate.flat-in-hand-image": {"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",@@ -331,7 +331,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 94200+ "max_tokens": 94450},"route.generate.flat-web-image": {"description": "Generate-PPTX context with web image acquisition.",@@ -344,7 +344,7 @@"stage.generate.image.web"],"files": [],- "max_tokens": 101500+ "max_tokens": 101700},"route.enhance-native-pptx.audio": {"description": "Enhance Native PPTX with the shared narration-audio stage.",@@ -364,7 +364,7 @@"profile.generate.beautify-pptx"],"files": [],- "max_tokens": 87550+ "max_tokens": 87800},"route.generate.flat-no-image-chart": {"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",@@ -377,7 +377,7 @@"stage.generate.verify-charts"],"files": [],- "max_tokens": 104550+ "max_tokens": 104750},"route.generate.brand-flat-no-image": {"description": "Brand-preset flat Generate-PPTX path without image acquisition.",@@ -389,7 +389,7 @@"stage.generate.template.brand"],"files": [],- "max_tokens": 87750+ "max_tokens": 88000},"route.generate.deck-structured-no-image": {"description": "Deck-preset structured Generate-PPTX path without image acquisition.",@@ -401,7 +401,7 @@"stage.generate.template.deck"],"files": [],- "max_tokens": 97600+ "max_tokens": 97800},"route.generate.layout-structured-no-image": {"description": "Layout-preset structured Generate-PPTX path without image acquisition.",@@ -413,7 +413,7 @@"stage.generate.template.layout"],"files": [],- "max_tokens": 98050+ "max_tokens": 98250},"route.generate.topic-only-flat-no-image": {"description": "Topic research followed by the default flat no-image Generate-PPTX path.",@@ -423,7 +423,7 @@"route.generate.flat-no-image"],"files": [],- "max_tokens": 82150+ "max_tokens": 82350},"stage.generate.executor.flat": {"description": "Incremental flat Executor core with representative multi-source custom mode/style execution.",@@ -533,7 +533,7 @@"stage.generate.executor.image"],"files": [],- "max_tokens": 58050+ "max_tokens": 58300},"stage.generate.topic-research": {"description": "Gap-targeted factual intake stage.",@@ -627,7 +627,7 @@"files": ["skills/ppt-master/workflows/governance/failure-recovery.md"],- "max_tokens": 2350+ "max_tokens": 2500},"stage.shared.conversion-reference": {"description": "Conditional source-conversion and import compatibility reference.",@@ -671,7 +671,7 @@"route.generate.planning-ai"],"files": [],- "max_tokens": 71050+ "max_tokens": 71100},"stage.generate.executor.chart": {"description": "Conditional chart/table page execution rules.",diff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.mdindex b3c83a35..52de05fb 100644--- a/skills/ppt-master/workflows/governance/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -20,6 +20,7 @@ Global stop/continue rules for all four top-level routes, plus concrete failure| Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation || Final confirmed value is missing, changed, substituted, or weakened in `design_spec.md` | Yes | Repair from the retained final-confirmation object; only a fresh recovery turn with no retained state reads persisted final evidence once | Only when the confirmed value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity || `spec_lock.md` changes confirmed identity or omits a required execution anchor/routing decision | Yes | Re-author the affected lock rows from the completed Design Spec and current context; do not enumerate page-local literals | No unless the Design Spec itself is incomplete | Step 4 Gate 2 — lock context fidelity |+| Execution exposes a missing Strategist-owned semantic role or plan detail | Yes for the affected page | In the same main-agent context, return to Strategist; repair the owning Design Spec fragments, then affected lock rows; targeted-readback, validate, rerun `page-context` for affected pages, and rebind the new SHA per [`executor-base.md`](../../references/executor-base.md) §2.1. Fresh or unknown context reads the complete Design Spec once | Only if the repair changes confirmed identity or user intent | Step 4 Gate 1/2 → Step 6 current page || Step 3 rejects a legacy or incomplete template contract | Yes | Stop template consumption; create a new current workspace through Create Template from the original PPTX/reference, then return with its exact workspace root | Only when required source evidence or template choices are unavailable | Create Template → Generate PPTX Step 3 || Formula rendering provider failure | No until the Step 7 readiness gate | Exhaust the provider chain; if unresolved, mark only the affected formula rows `Needs-Manual` and continue | Supply the exact target PNG or change formula policy | Step 4 / Step 7 image readiness gate || AI image generation failure | No | `auto`: follow A → B → Offline Manual. Explicit `api` / `host-native`: retry only that path, then mark the row `Needs-Manual` without switching automated providers | Only when missing files are required before export | Step 5 / Step 7 image readiness gate |diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.mdindex 32a3e6fa..fee66e7c 100644--- a/skills/ppt-master/workflows/stages/resume-execute.md+++ b/skills/ppt-master/workflows/stages/resume-execute.md@@ -52,7 +52,7 @@ Then jump to `### Step 6: Executor Phase` and run the documented pipeline:- Read the Step 6 flat core (`executor-base`, `shared-standards-core`, and the locked preset mode / visual-style files); for custom directions, reload every optional `*_references` file from `spec_lock.md` before applying the behavior, then only the branches selected by the condition table- Design Parameter Confirmation-- Read the project Design Spec and, when structured, the template Design Spec once; retain both in the fresh execution context+- Read the project Design Spec and, when structured, the template Design Spec once; retain both in the fresh execution context. A later repair authored by this same main agent follows [`executor-base.md`](../../references/executor-base.md) §2.1 targeted readback/rebind instead of loading the project Design Spec a second time- Per-page `python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> --record-usage` load + sequential page generation; the stable anchor projection repeats intentionally without becoming a color/font allowlist, while each prototype/chart SVG is loaded only before its first use or after its SHA changes- Quality Check Gate- Speaker notes generation