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
docs(topic-research): document bounded research isolation
hugohe3f8891fff1a76
diff --git a/docs/faq.md b/docs/faq.mdindex c52b4ca8..bd6c2b5c 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -246,7 +246,9 @@ default-quality-equivalence promise.Default recommendation: **continuous one-shot generation**. 10–15 page decks fit comfortably in a 200K window, and cross-page visual consistency is best when the Executor can see prior pages in the same session (it actively aligns style, font sizes, and rhythm).-Only when signals are heavy (≥ 18 pages, thick source material, or `topic-research` ran with substantial web-fetch accumulation) does the AI surface an optional **split mode** hint at the Strategist phase: the planning session (Strategist confirmation stage + image acquisition) ends in the current chat; you open a fresh chat window and type `resume execution projects/<project_name>` to enter the execution session (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there.+When the current AI editor supports an isolated research worker, `topic-research` keeps raw fetches there and the main chat reads only the saved research supplement and fact-provenance file.++Only when signals are heavy (≥ 18 pages, thick source material, or substantial research material remains in the main chat after a local fallback or unusually large imported supplement) does the AI surface an optional **split mode** hint at the Strategist phase: the planning session (Strategist confirmation stage + image acquisition) ends in the current chat; you open a fresh chat window and type `resume execution projects/<project_name>` to enter the execution session (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there.Split mode is a **compromise** — the fresh session pays the fixed cost of reloading the Generate authority and required execution references, but drops the planning-session noise and reuses the freed budget to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode.diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 0e36e3de..f3b5ffe7 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -441,7 +441,7 @@ When several workspaces are selected, fusion is segment-level, not field-level.## Role System: Specialized Modes in a Single Pipeline-PPT Master uses **role switching within one main agent** rather than parallel sub-agents. Strategist, Image_Generator, Executor, and workflow-specific modes are instruction scopes loaded on demand; they are not independent agents with their own stale copies of the deck state. The choice has three connected reasons:+PPT Master keeps deck-state roles—Strategist, Image_Generator, and Executor—inside one main agent rather than distributing them across parallel sub-agents. They are instruction scopes loaded on demand, not independent agents with stale copies of the deck state. A supporting stage may use a bounded sub-agent only when its authority defines a durable artifact hand-off that does not depend on shared deck state. The core choice has three connected reasons:**Why one agent, not parallel sub-agents.** Page design depends on the full upstream context — Strategist's color choices, the image resources that actually got acquired (vs failed and substituted), prior pages' visual rhythm. Sub-agents would start with a stale partial snapshot of that context and produce visually drifting decks. The same logic forbids batched page generation (e.g., five pages per turn): batching accelerates context compression and the deck's visual consistency degrades faster than the speed gain is worth.@@ -514,7 +514,7 @@ icons, and formulas with their required manifests or provenance records, andthen hand-authors SVG. It does not invoke Strategist, Confirm UI,`design_spec.md`, or `spec_lock.md`.-**Default preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.+**Default preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.**Prepared project-local assets are the boundary.** In the default pipeline, images and other declared resources remain available only when Strategist has selected them, recorded them in the planning artifacts, and made their project paths resolvable or explicitly `Needs-Manual`. Icons are prepared when their SVG files exist under `<project>/icons/`; `spec_lock.icons.inventory` records the Strategist's planned bundled selection but is not an exhaustive execution whitelist. In quick generation, the active-context resource roster and its project-local files/manifests replace that planning projection; the current agent may acquire and prepare those resources before SVG authoring. Files elsewhere on disk are not authorized. Missing material returns to the owning preparation step; SVG authoring never silently substitutes it.diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 1cb21787..1704a75d 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -220,7 +220,9 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t默认推荐**一次性连续生成**——10–15 页的 deck 在 200K 上下文窗口下完全够用,跨页视觉一致性也最好(Executor 看到前几页 SVG 后会主动对齐风格、字号、节奏)。-只有信号偏重的场景(页数 ≥ 18 / 源材料很厚 / 走过 topic-research 累积大量 web 抓取),AI 才会在策略师阶段给出**拆分模式**的可选提示:规划会话(策略师确认阶段 + 图片获取)结束后停止当前对话;你新开聊天窗口,输入 `继续生成 projects/<项目名>` 进入执行会话(SVG 生成 + 导出)。新会话从磁盘重新加载 `design_spec` / `spec_lock` / `sources` / `images` 继续执行。+当前 AI 编辑器若支持隔离研究子代理,`topic-research` 会把原始网页抓取留在该上下文,主会话只读取落盘的研究摘要和事实来源文件。++只有信号偏重的场景(页数 ≥ 18 / 源材料很厚 / 本地回退研究后主会话仍保留大量研究材料,或导入的研究摘要本身异常庞大),AI 才会在策略师阶段给出**拆分模式**的可选提示:规划会话(策略师确认阶段 + 图片获取)结束后停止当前对话;你新开聊天窗口,输入 `继续生成 projects/<项目名>` 进入执行会话(SVG 生成 + 导出)。新会话从磁盘重新加载 `design_spec` / `spec_lock` / `sources` / `images` 继续执行。两段式是**折中方案**——新会话需付出重载 Generate 权威文档与必需执行引用的固定成本,但可丢弃规划会话噪声,并把节省下来的窗口空间用于主动重读 `sources/` 做内容增稠。**信号正常时不需要**,提示也不会出现;用户随时可以忽略提示,走默认连续模式。diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 91d26dc7..205fedbc 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -392,7 +392,7 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是编译生成的 PowerPoin## 角色系统:单一流水线中的专业模式-PPT Master 用的是**单主代理内的角色切换**,不是并行子代理。Strategist、Image_Generator、Executor,以及各路线中的 child workflow / profile / stage,本质上都是按需加载的指令作用域;它们不是带着各自过期 deck 状态的独立 agent。这个选择有三条互相支撑的理由:+PPT Master 把拥有 deck 状态的 Strategist、Image_Generator 和 Executor 保持在同一主代理内,而不是分发给并行子代理。它们是按需加载的指令作用域,不是各自持有过期 deck 状态的独立 agent。只有当支撑阶段的权威文件定义了不依赖共享 deck 状态的持久产物交接时,才可使用有界子代理。核心选择有三条互相支撑的理由:**为什么是单代理而非并行子代理。** 页面设计依赖完整的上游上下文——Strategist 的色彩选择、图片资源是否成功获取(还是失败被替代)、之前几页的视觉节奏。子代理拿到的只能是这个上下文的过期局部快照,产出的 deck 视觉会逐页漂。同一逻辑也禁止分批生成(比如一次 5 页):分批加速上下文压缩,deck 的视觉一致性下降速度比节省的速度更快——不划算。@@ -457,7 +457,7 @@ Generate 执行以 [`workflows/generate-pptx.md`](../../skills/ppt-master/workfl**快速生成把规划职责合并到当前 Agent。** 来源转换、事实缺口研究和资源准备仍按需运行。当前 Agent 在上下文中自动选择内容、页面清单、视觉系统和资源需求,准备用户提供 / 来源抽取 / AI / 网络 / 切片图片、图标和公式及其必要 manifest 或来源记录,随后手写 SVG;不进入 Strategist、Confirm UI、`design_spec.md` 或 `spec_lock.md`。-**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。+**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。**项目中已备好的材料就是边界。** 默认流程中,图片和其他声明型资源须由 Strategist 选定、写入规划产物,并保证项目路径可解析或明确标为 `Needs-Manual`。图标 SVG 只要已位于 `<project>/icons/` 就属于已备材料;`spec_lock.icons.inventory` 记录 Strategist 计划选用的内置图标,但不是穷尽式执行白名单。快速生成以当前上下文中的资源清单及其项目级文件 / manifest 代替该规划投影;当前 Agent 可以在手写 SVG 前获取并准备这些资源。其他目录中的文件不构成使用许可。缺料必须回到所属备料步骤;SVG 创作阶段不得静默换料。