|
| 1 | +# Planning Layer |
| 2 | + |
| 3 | +新建演示文稿或大幅改写页面时，必须先写 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。这个文件是 deck 的设计中间层，用来把叙事、页面角色、布局、视觉重点和文字密度固定下来，避免从用户提示直接跳到 XML。 |
| 4 | + |
| 5 | +小型已有页编辑可豁免，例如只替换一个标题、改一个数字、插入一个块、上传并插入一张图。只要任务会重排多页、生成新 deck、替换整页结构，仍然需要规划层。 |
| 6 | + |
| 7 | +## Required Flow |
| 8 | + |
| 9 | +1. 理解用户需求，必要时澄清主题、受众、页数、风格。 |
| 10 | +2. 如果适合模板，先用 `template_tool.py search` 检索，锁定模板后用 `summarize` 获取主题和页型信息。 |
| 11 | +3. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。 |
| 12 | +4. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。 |
| 13 | +5. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。 |
| 14 | +6. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。 |
| 15 | +7. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。 |
| 16 | +8. 创建 PPT 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。 |
| 17 | + |
| 18 | +模板不能代替 plan。模板搜索和摘要只能影响 `theme_style`、页面流、布局选择和局部布局骨架；最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。 |
| 19 | + |
| 20 | +## Plan Path |
| 21 | + |
| 22 | +Use a separate plan directory per deck or task so multiple presentations in the same workspace cannot overwrite each other. |
| 23 | + |
| 24 | +Recommended IDs: |
| 25 | + |
| 26 | +- New deck before creation: title slug plus date/time, such as `q3-review-20260507-1805`. |
| 27 | +- Existing PPT rewrite: the `xml_presentation_id`. |
| 28 | +- Ambiguous or untitled task: short task slug plus date/time. |
| 29 | + |
| 30 | +Rules: |
| 31 | + |
| 32 | +- Do not reuse `.lark-slides/plan/slide_plan.json` as a shared path. |
| 33 | +- Create the directory before writing the file. |
| 34 | +- Reuse the same plan path for XML generation and post-create verification for that deck. |
| 35 | + |
| 36 | +## JSON Shape |
| 37 | + |
| 38 | +```json |
| 39 | +{ |
| 40 | + "presentation_goal": "Explain the proposal and secure approval for the next phase.", |
| 41 | + "audience": "Product and engineering leaders who know the domain but need a concise decision narrative.", |
| 42 | + "theme_style": "Clean business style, light background, restrained blue accent, strong visual hierarchy.", |
| 43 | + "visual_system": { |
| 44 | + "background_strategy": "Content pages use one light base; cover and closing may use a related dark treatment with the same accent system.", |
| 45 | + "motif": "A reusable left accent bar and consistent card/header treatments.", |
| 46 | + "color_roles": { |
| 47 | + "primary": "Used for the dominant structural motif and about 60-70% of visual weight.", |
| 48 | + "secondary": "Used for grouped regions, comparison panels, or supporting categories.", |
| 49 | + "accent": "Used only for key numbers, conclusions, or focus markers." |
| 50 | + } |
| 51 | + }, |
| 52 | + "typography_constraints": { |
| 53 | + "title_max_lines": 2, |
| 54 | + "body_max_lines_per_box": 2, |
| 55 | + "footer_max_lines": 1, |
| 56 | + "long_text_handling": "Shorten, split into multiple boxes, or move detail to speaker notes instead of shrinking into a tight box." |
| 57 | + }, |
| 58 | + "verification_plan": { |
| 59 | + "check_background_consistency": true, |
| 60 | + "check_text_fit": true, |
| 61 | + "check_visual_focus": true, |
| 62 | + "check_asset_rendering": true |
| 63 | + }, |
| 64 | + "slides": [ |
| 65 | + { |
| 66 | + "page": 1, |
| 67 | + "title": "Proposal Title", |
| 68 | + "key_message": "The initiative is ready for a focused pilot.", |
| 69 | + "layout_type": "title-cover", |
| 70 | + "visual_focus": "Large title area with one concise supporting statement.", |
| 71 | + "asset_need": { |
| 72 | + "asset_type": "logo", |
| 73 | + "purpose": "Signal product or team identity on the opening page.", |
| 74 | + "suggested_query": "product logo", |
| 75 | + "fallback_if_missing": "Use a small text badge and abstract shape motif instead of a real logo." |
| 76 | + }, |
| 77 | + "text_density": "low", |
| 78 | + "speaker_intent": "Frame the decision and establish the deck's point of view." |
| 79 | + } |
| 80 | + ] |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +## Required Fields |
| 85 | + |
| 86 | +Top-level fields: |
| 87 | + |
| 88 | +- `presentation_goal`: what the whole deck is trying to achieve. |
| 89 | +- `audience`: target readers or listeners and their assumed background. |
| 90 | +- `theme_style`: visual tone, palette direction, and professional style. |
| 91 | +- `visual_system`: deck-level visual rules that must stay stable across pages, including background strategy, recurring motif, and color roles. |
| 92 | +- `typography_constraints`: deck-level limits for line count, text box density, and how to handle long text before XML generation. |
| 93 | +- `verification_plan`: explicit checks to perform after creation or major edits; include background consistency, text fit, visual focus, and asset rendering when relevant. |
| 94 | +- `slides`: ordered page plans. |
| 95 | + |
| 96 | +Each slide must include: |
| 97 | + |
| 98 | +- `page`: 1-based page number. |
| 99 | +- `title`: slide title. |
| 100 | +- `key_message`: the one idea this page must land. |
| 101 | +- `layout_type`: planned page structure. |
| 102 | +- `visual_focus`: dominant visual object or region. |
| 103 | +- `asset_need`: planning-only structured asset metadata; no search, download, or upload required. Follow `asset-planning.md`. |
| 104 | +- `text_density`: `low`, `medium`, or `high`. |
| 105 | +- `speaker_intent`: why the speaker needs this page and how it advances the story. |
| 106 | + |
| 107 | +## Layout Vocabulary |
| 108 | + |
| 109 | +Use one of these `layout_type` values unless the user explicitly needs a custom structure: |
| 110 | + |
| 111 | +- `title-cover` |
| 112 | +- `section-divider` |
| 113 | +- `two-column` |
| 114 | +- `image-left-text-right` |
| 115 | +- `image-right-text-left` |
| 116 | +- `big-number` |
| 117 | +- `timeline` |
| 118 | +- `comparison` |
| 119 | +- `architecture-diagram` |
| 120 | +- `process-flow` |
| 121 | +- `quote-highlight` |
| 122 | +- `conclusion` |
| 123 | + |
| 124 | +The value must affect XML geometry, not just appear as a label. For example, `timeline` should create a horizontal or vertical sequence, `comparison` should create distinct side-by-side regions, and `big-number` should reserve dominant space for a large metric. |
| 125 | + |
| 126 | +## Text Density Rules |
| 127 | + |
| 128 | +- `low`: title plus 1 short statement, or 1-3 very short labels. |
| 129 | +- `medium`: title plus 2-4 concise bullets or labeled regions. |
| 130 | +- `high`: allowed only when the user needs detail; use tables, columns, or grouped regions instead of a long bullet list. |
| 131 | + |
| 132 | +Do not let all pages become title + bullet slides. For decks of 4 or more pages, aim for at least 4 different `layout_type` values when the content allows it. |
| 133 | + |
| 134 | +Text density must be realistic for the planned geometry. If a page needs long titles, bilingual labels, paper figure captions, legal disclaimers, or dense technical wording, record how the text will be shortened, split, or moved to speaker notes. Do not rely on small font sizes or tight boxes to make text fit. |
| 135 | + |
| 136 | +## Visual System Planning |
| 137 | + |
| 138 | +Before generating XML, define a visual system that can survive the whole deck: |
| 139 | + |
| 140 | +- `background_strategy`: specify the default background for normal content pages, and which page roles may intentionally differ. Do not let pages drift through near-identical but inconsistent background colors. |
| 141 | +- `motif`: choose one or two reusable structural devices, such as a side bar, header rail, numbered node, card treatment, diagram lane, or section band. The motif should appear consistently enough that pages feel related. |
| 142 | +- `color_roles`: assign primary, secondary, and accent roles. The same color must not mean unrelated things across pages. |
| 143 | +- `cover_content_relationship`: if the cover uses a different dark or image-led treatment, state how it connects to content pages through shared colors, motifs, or geometry. |
| 144 | +- `closing_relationship`: if the closing page mirrors the cover, state that explicitly so it looks intentional rather than like a new theme. |
| 145 | + |
| 146 | +These are planning constraints, not decoration notes. They must affect coordinates, background fills, shape styles, and text placement in generated XML. |
| 147 | + |
| 148 | +## Iterative Deck State |
| 149 | + |
| 150 | +When continuing an existing deck, update the same plan path rather than creating a new disconnected plan. Keep the plan aligned with what has actually been created. |
| 151 | + |
| 152 | +Recommended optional fields for long-running work: |
| 153 | + |
| 154 | +- `deck_status`: current slide count, target slide count if known, and last verified revision or timestamp. |
| 155 | +- `created_slides`: page number, slide id when known, and the page role. |
| 156 | +- `assets_used`: source, local path when applicable, uploaded token when known, and which page uses it. |
| 157 | +- `open_issues`: known layout, text fit, asset, or consistency risks that still need correction. |
| 158 | + |
| 159 | +Do not hard-code a page number just because a previous deck used that pattern. Plan by page role and evidence need, such as "method overview pages should use a figure when the source has a readable figure" instead of binding screenshots, charts, or diagrams to a fixed page index. The plan should describe decision rules, not a rigid template sequence. |
| 160 | + |
| 161 | +## Asset Planning |
| 162 | + |
| 163 | +`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback shape-based visual, but it must not require web search, local download, or media upload. |
| 164 | + |
| 165 | +Use an object for one planned asset, an array for multiple real needs, or `asset_type: "none"` when no asset is useful. Each planned asset must include: |
| 166 | + |
| 167 | +- `asset_type`: one of `paper_figure`, `architecture_diagram`, `icon`, `logo`, `chart`, `infographic`, `screenshot`, `flow_diagram`, or `none`. |
| 168 | +- `purpose`: why this asset helps the page's key message. |
| 169 | +- `suggested_query`: short future lookup hint only; do not execute it unless separately requested. |
| 170 | +- `fallback_if_missing`: concrete XML-native visual plan using shapes, arrows, labels, tables, simple charts, or placeholder panels. |
| 171 | + |
| 172 | +For detailed rules and examples, read `asset-planning.md`. |
| 173 | + |
| 174 | +Good examples: |
| 175 | + |
| 176 | +- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw grouped boxes and arrows with short labels."}` |
| 177 | +- `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}` |
| 178 | +- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple line chart with shapes and value labels."}` |
| 179 | + |
| 180 | +## XML Generation Contract |
| 181 | + |
| 182 | +Before writing each slide XML, map the plan fields to concrete decisions: |
| 183 | + |
| 184 | +- `key_message` determines the headline, dominant claim, or main takeaway. |
| 185 | +- `layout_type` determines the coordinate structure and element types. Use `visual-planning.md` for concrete layout rules. |
| 186 | +- `visual_focus` determines the largest visual region or emphasized object. |
| 187 | +- `text_density` caps visible text volume. |
| 188 | +- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions. |
| 189 | + |
| 190 | +After creating the PPT, fetch the presentation and verify: |
| 191 | + |
| 192 | +- Page count matches the plan. |
| 193 | +- Every page has the planned title and key message represented. |
| 194 | +- At least several pages have visibly different XML layout structures. |
| 195 | +- Planned `visual_focus` appears as a dominant visual region or object. |
| 196 | +- Asset planning is proportional to the deck topic and length: technical, research, product, and analytical decks should include meaningful planned visuals where they clarify the story, and each planned asset has a visible fallback if no real asset was used. |
| 197 | +- `text_density` is reflected in the amount of visible text. |
| 198 | +- Pages are not crowded, and any planned `timeline`, `comparison`, or `architecture-diagram` page uses its matching visual structure. |
| 199 | +- The actual backgrounds match `visual_system.background_strategy`; any dark, image-led, or emphasis page has an intentional relationship to the rest of the deck. |
| 200 | +- Text boxes respect `typography_constraints`; long labels, captions, footer text, and conclusion bars are not squeezed into boxes that are too short for the intended line count. |
| 201 | +- If real assets are used, the final XML contains renderable asset tokens or supported local placeholders for creation, not http URLs, stale local paths, or blank image boxes. |
0 commit comments