Skip to content

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

feat(confirm-ui): support multi-source image usage

hugohe342f1122fd357
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 98770159..2755df3b 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -377,7 +377,7 @@ Steps:
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait
```
Page opens at `http://localhost:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4). If 5050 is held, the launcher **auto-advances** (5051, …) — read the actual URL from the launch log and report it. The page does **not** close after Tier 1: it shows a "deriving…" state and polls for Tier 2. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host), do **NOT** troubleshoot — **on any non-zero exit, re-check `result.json` once** (a fresh `status: tier1-confirmed`) before dropping to the chat fallback. **On success (exit 0 with a tier-1 result), do not pause or report — go straight to step 3 in the same turn.**
-3. **Re-derive Tier 2 from the confirmed anchors, then write it — immediately, same turn (the page is polling for it).** Read the tier-1 `result.json` (`status: tier1-confirmed`). Using the user's **actual** confirmed anchors (not your originals), author the realization candidates and **overwrite** `recommendations.json` with `"tier": 2`: page count (content volume × `delivery_purpose`); color, typography, and generated-image style as **generative ≥3-candidate** fields (creative recommendations always offer real choice — same rule as h.5; fewer than 3 only on the honest-shortfall exception, with a stated reason; color: core `palette` with background/secondary_bg/primary/accent/secondary_accent/body_text; typography: CJK + Latin for `heading` and `body` with `css` preview stacks + `body_size` as the body baseline in **px** (every canvas) — **one fixed value per confirmed `delivery_purpose`** (`text` 20 / `balanced` 24 / `presentation` 32), not a range; each typography candidate must include topic-matched `sample_heading` / `sample_heading_latin` / `sample_body` / `sample_body_latin` preview text, never a fixed unrelated industry sample; images: `image_strategy.candidates` rendering × palette from h.5); enumerable `icons` / `formula_policy` / `generation_mode` (recommended `id`); `image_usage` (`ai` / `web` / `provided` / `placeholder` / `none`, or a custom prose plan when several sources mix — never bare `"custom"`; write `image_ai_path` only when the plan includes AI). The still-open page polls, renders Tier 2, and preserves the user's Tier 1 picks. Closed fields (`image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec`) stay finite; open fields (`icons`, `image_usage`, typography custom text) show a Custom box.
+3. **Re-derive Tier 2 from the confirmed anchors, then write it — immediately, same turn (the page is polling for it).** Read the tier-1 `result.json` (`status: tier1-confirmed`). Using the user's **actual** confirmed anchors (not your originals), author the realization candidates and **overwrite** `recommendations.json` with `"tier": 2`: page count (content volume × `delivery_purpose`); color, typography, and generated-image style as **generative ≥3-candidate** fields (creative recommendations always offer real choice — same rule as h.5; fewer than 3 only on the honest-shortfall exception, with a stated reason; color: core `palette` with background/secondary_bg/primary/accent/secondary_accent/body_text; typography: CJK + Latin for `heading` and `body` with `css` preview stacks + `body_size` as the body baseline in **px** (every canvas) — **one fixed value per confirmed `delivery_purpose`** (`text` 20 / `balanced` 24 / `presentation` 32), not a range; each typography candidate must include topic-matched `sample_heading` / `sample_heading_latin` / `sample_body` / `sample_body_latin` preview text, never a fixed unrelated industry sample; images: `image_strategy.candidates` rendering × palette from h.5); enumerable `icons` / `formula_policy` / `generation_mode` (recommended `id`); `image_usage` as one or more source ids (`["ai"]`, `["ai","provided"]`, `["web","placeholder"]`, or `["none"]`; `none` is exclusive). If the recommendation involves several sources, keep the source list structured in `recommend.image_usage` and write the usage rationale / page-role guidance into `image_notes` (for example, "封面和章节页用 AI 主视觉,产品页优先用户素材,行业背景页可用网络参考"). Write `image_ai_path` only when `image_usage` includes `ai`. The still-open page polls, renders Tier 2, and preserves the user's Tier 1 picks. Closed fields (`image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec`) stay finite; open fields (`icons`, typography custom text, image notes) expose free-text controls.
4. **Wait for the final confirmation** — attach to the already-running page, do **not** relaunch (same 600000 ms budget):
```bash
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only
@@ -391,17 +391,18 @@ Steps:
**Always also print each tier's recommendations + URL in chat** as the always-valid fallback. **The chat fallback is two-step too**: if the page never opens or a wait times out with no fresh result, present Tier 1 in chat → get confirmation → re-derive → present Tier 2 → get confirmation → take those values. Either path converges.
-**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate):
+**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate). `image_usage` may be either a legacy single string or a Confirm UI multi-select array; for arrays, apply every selected source. `image_notes`, when present, is a user-authored image intent note that Strategist must honor while assigning per-page §VIII rows:
| `result.json.image_usage` | §VIII `Acquire Via` | h.5 + Step 5 generation |
|---|---|---|
-| `ai` (or a custom plan that includes AI) | `ai` rows | Run h.5 (lock rendering + palette); Step 5 generates |
+| `ai` | `ai` rows | Run h.5 (lock rendering + palette); Step 5 generates |
| `web` | `web` rows | None |
| `provided` | **`user`** rows | None — never generate |
| `placeholder` | `placeholder` rows | None |
| `none` | no image rows (§h option A) | None |
+| Legacy custom prose | Infer the intended rows from the prose | Run h.5 only if the prose includes AI |
-When the confirmed `image_usage` is not `ai` (and the plan has no AI part), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).
+When the confirmed `image_usage` does not include `ai` (and no legacy custom prose includes AI), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. `none` is exclusive: if confirmed, write no §VIII image rows. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).
**Small spot illustrations are a Strategist judgment, not a confirmation field.** The user chooses image source through `image_usage`; within that boundary, Strategist may proactively add a coherent family of small decorative illustrations when the confirmed style and content benefit from them. They are ordinary §VIII image rows (`Type: Illustration` / `Illustration Sheet`) using normal `Acquire Via` values. `image_usage: none` still wins: write no decorative illustration rows. If the plan needs ≥3 same-family AI spot illustrations, use the `ai` Illustration Sheet + `slice` workflow by default; do not generate one AI image per spot. Use them on suitable pages and omit them where they would weaken clarity.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 30c075a1..11bad964 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -350,7 +350,9 @@ The script renders PNGs into `images/`, trying `codecogs`, `quicklatex`, `mathpa
>
> Read `<project_path>/analysis/image_analysis.csv` (size / ratio / category of every in-hand picture). The A–E choice is still your judgment, but it MUST be made with the current inventory in full view — never in ignorance of what is already on hand. `image_analysis.csv` is a regenerated view of the live folder, not a durable fact: re-run this whenever `images/` changes.
-> **Confirmed value wins.** The `image_usage` in `result.json` (or the chat reply) **overrides the recommendation here** — map it to §VIII `Acquire Via` (`ai`→`ai`, `web`→`web`, `provided`→**`user`**, `placeholder`→`placeholder`, `none`→option A, no image rows). When it is not `ai` (and the plan has no AI part), skip h.5 entirely and write no `ai` rows. See SKILL.md Step 4 for the full mapping.
+> **Recommendation shape.** In `recommendations.json`, write `recommend.image_usage` as source ids, not prose. Use a single id for a single source (`"ai"`) and an array for mixed sources (`["ai", "provided"]`, `["web", "placeholder"]`). Put the strategy explanation in top-level `image_notes.value`: page roles, which supplied assets are authoritative, where AI may fill gaps, what kind of imagery to prefer/avoid, and whether placeholders are acceptable. `none` is exclusive and must not be combined with other ids.
+
+> **Confirmed value wins.** The `image_usage` in `result.json` (or the chat reply) **overrides the recommendation here**. It may be a legacy single string or a Confirm UI multi-select array. Map every selected value to §VIII `Acquire Via` (`ai`→`ai`, `web`→`web`, `provided`→**`user`**, `placeholder`→`placeholder`, `none`→option A, no image rows). When it does not include `ai` (and no legacy prose plan includes AI), skip h.5 entirely and write no `ai` rows. If `image_notes` is present, honor it as the user's image intent while assigning per-page rows. See SKILL.md Step 4 for the full mapping.
> **Small spot illustrations are optional visual enhancement, not a confirmation field.** The user confirms image source via `image_usage`; within that boundary, Strategist may proactively add a coherent family of small decorative spot illustrations when the deck's `visual_style`, content texture, and page density would benefit. Do not create a separate system, page-role map, or user-facing picker. Use them on suitable pages; do not force a quota, and do not phrase the rule as "few pages." Suitable means the spot improves rhythm, warmth, continuity, or section identity without carrying facts or competing with charts, photos, tables, screenshots, or key text. `image_usage: none` wins and produces no decorative illustration rows.
diff --git a/skills/ppt-master/scripts/confirm_ui/static/app.js b/skills/ppt-master/scripts/confirm_ui/static/app.js
index bdd65932..7183ff7f 100644
--- a/skills/ppt-master/scripts/confirm_ui/static/app.js
+++ b/skills/ppt-master/scripts/confirm_ui/static/app.js
@@ -51,7 +51,10 @@
image_strategy_visual: "Visual",
image_strategy_color: "Color",
image_strategy_mood: "Mood",
- image_usage_custom_required: "Describe the custom image plan before confirming.",
+ image_usage_notes: "Additional image requirements",
+ image_usage_notes_placeholder: "e.g. realistic handwashing scenes; avoid cartoon germs; keep product photos untouched.",
+ image_usage_required: "Select at least one image usage option.",
+ image_usage_none_exclusive: "No images cannot be combined with other image options.",
font_heading: "Heading",
font_body: "Body",
font_body_size: "Body baseline size",
@@ -133,7 +136,10 @@
image_strategy_visual: "视觉",
image_strategy_color: "色彩",
image_strategy_mood: "情绪",
- image_usage_custom_required: "请先写清楚自定义图片方案。",
+ image_usage_notes: "图片补充要求",
+ image_usage_notes_placeholder: "例如:优先真实洗手场景;不要卡通病菌;产品照片保持原样。",
+ image_usage_required: "请至少选择一种图片使用方式。",
+ image_usage_none_exclusive: "「不使用图片」不能和其它图片选项同时选择。",
font_heading: "标题",
font_body: "正文",
font_body_size: "正文基准字号",
@@ -287,6 +293,15 @@
return aliases[value] || value;
}
+ function normalizeRecIds(field, value) {
+ if (Array.isArray(value)) {
+ return value.map(function (item) { return normalizeRecId(field, item); })
+ .filter(function (item, idx, arr) { return item && arr.indexOf(item) === idx; });
+ }
+ var normalized = normalizeRecId(field, value);
+ return normalized ? [normalized] : [];
+ }
+
function legacyRecId(field) {
if (!REC) return null;
if (field === "canvas") return REC.canvas && REC.canvas.value;
@@ -303,6 +318,10 @@
var value = (REC && REC.recommend && REC.recommend[field]) || legacyRecId(field);
return normalizeRecId(field, value || null);
}
+
+ function recValue(field) {
+ return (REC && REC.recommend && REC.recommend[field]) || legacyRecId(field);
+ }
// Guaranteed recommendation: the AI's pick, or the first catalog option as a
// fallback so an enumerable field ALWAYS shows a badged recommendation.
function recOrFirst(field, list) {
@@ -518,6 +537,7 @@
function usesCustomImagePlanValue(value) {
var ids = (CAT.image_usage || []).map(function (item) { return item.id; });
+ if (Array.isArray(value)) return false;
return value && ids.indexOf(value) === -1;
}
@@ -526,9 +546,30 @@
}
function needsGeneratedImagesForUsage(value) {
+ if (Array.isArray(value)) return value.indexOf("ai") >= 0;
return value === "ai" || (usesCustomImagePlanValue(value) && customImagePlanHasAiSignal());
}
+ function selectedImageUsageIds(value) {
+ var validIds = (CAT.image_usage || []).map(function (item) { return item.id; });
+ return normalizeRecIds("image_usage", value).filter(function (id) {
+ return validIds.indexOf(id) >= 0;
+ });
+ }
+
+ function imageUsageNotesRecommendation(rawUsage) {
+ var notes = (REC && REC.image_notes && REC.image_notes.value) ||
+ (REC && REC.image_notes) ||
+ (REC && REC.images && REC.images.notes) ||
+ "";
+ if (!notes && usesCustomImagePlanValue(rawUsage)) notes = rawUsage;
+ return typeof notes === "string" ? notes : "";
+ }
+
+ function defaultImageUsageId() {
+ return firstId(CAT.image_usage);
+ }
+
function imageStrategySelectedIndex() {
var spec = imageStrategySpec();
var idx = spec.selected || 0;
@@ -1175,15 +1216,20 @@
function renderImages(host) {
var sec = section(8, "sec_images");
+ var usageChips = el("div", "chips");
+ var usageNote = el("div", "subfield");
+ usageNote.appendChild(el("div", "subfield-label", t("image_usage_notes")));
+ var usageNoteInput = el("textarea", "text-input image-usage-notes-input");
+ usageNoteInput.placeholder = t("image_usage_notes_placeholder");
+ usageNoteInput.value = STATE.image_notes || "";
+ usageNoteInput.addEventListener("input", function () { STATE.image_notes = usageNoteInput.value; });
+ usageNote.appendChild(usageNoteInput);
var sub = el("div", "subfield");
sub.appendChild(el("div", "subfield-label", t("image_ai_path")));
var strategySub = el("div", "subfield image-strategy-subfield");
strategySub.appendChild(el("div", "subfield-label", t("image_strategy")));
var strategyGrid = el("div", "font-grid");
var strategyCands = imageStrategyCandidates();
- function usesCustomImagePlan() {
- return usesCustomImagePlanValue(STATE.image_usage);
- }
function needsGeneratedImages() {
return needsGeneratedImagesForUsage(STATE.image_usage);
}
@@ -1225,27 +1271,51 @@
});
if (!strategyCands.length) strategyGrid.appendChild(el("div", "toggle-desc", t("image_strategy_empty")));
strategySub.appendChild(strategyGrid);
- enumField(sec, CAT.image_usage, recOrFirst("image_usage", CAT.image_usage),
- function () { return STATE.image_usage; },
- function (v) {
- STATE.image_usage = v;
- refreshAiControls();
- },
- {
- allowCustom: true,
- customSentinel: "custom",
- customInvalidValues: ["custom"],
- inputClass: "image-usage-custom-input",
- placeholder: LANG === "zh"
- ? "例如:封面用 AI 生成,产品页用用户素材,行业页用网络来源"
- : "e.g. AI cover + user product assets + web industry images"
+ var recommendedIds = selectedImageUsageIds(recValue("image_usage"));
+ if (!recommendedIds.length) recommendedIds = [defaultImageUsageId()];
+ var usageChipById = {};
+ function refreshUsageChips() {
+ Object.keys(usageChipById).forEach(function (id) {
+ usageChipById[id].classList.toggle("selected", STATE.image_usage.indexOf(id) >= 0);
});
+ var noImages = STATE.image_usage.indexOf("none") >= 0;
+ usageNote.style.display = noImages ? "none" : "block";
+ refreshAiControls();
+ }
+ function toggleImageUsage(id) {
+ var cur = STATE.image_usage.slice();
+ if (id === "none") {
+ cur = cur.indexOf("none") >= 0 ? [] : ["none"];
+ } else {
+ cur = cur.filter(function (item) { return item !== "none"; });
+ if (cur.indexOf(id) >= 0) cur = cur.filter(function (item) { return item !== id; });
+ else cur.push(id);
+ }
+ STATE.image_usage = cur;
+ refreshUsageChips();
+ }
+ (CAT.image_usage || []).forEach(function (o) {
+ var label = optionLabel(o);
+ var desc = optionDesc(o);
+ if (desc) label += (LANG === "zh" ? ":" : " — ") + desc;
+ var chip = el("div", "chip");
+ chip.appendChild(el("span", "chip-text", label));
+ if (recommendedIds.indexOf(o.id) >= 0) {
+ chip.classList.add("recommended");
+ chip.appendChild(el("span", "rec-badge", "★ " + t("recommended")));
+ }
+ chip.addEventListener("click", function () { toggleImageUsage(o.id); });
+ usageChipById[o.id] = chip;
+ usageChips.appendChild(chip);
+ });
+ sec.appendChild(usageChips);
+ sec.appendChild(usageNote);
enumField(sub, CAT.image_ai_path, recOrFirst("image_ai_path", CAT.image_ai_path),
function () { return STATE.image_ai_path; }, function (v) { STATE.image_ai_path = v; });
sec.appendChild(sub);
sec.appendChild(strategySub);
if (strategyCands.length) selectImageStrategy(imageStrategySelectedIndex());
- refreshAiControls();
+ refreshUsageChips();
host.appendChild(sec);
}
@@ -1374,7 +1444,12 @@
};
STATE.formula_policy = pick("formula_policy", CAT.formula_policy);
- STATE.image_usage = pick("image_usage", CAT.image_usage);
+ var rawImageUsage = recValue("image_usage");
+ STATE.image_usage = selectedImageUsageIds(rawImageUsage);
+ if (!STATE.image_usage.length) {
+ STATE.image_usage = [defaultImageUsageId()];
+ }
+ STATE.image_notes = imageUsageNotesRecommendation(rawImageUsage);
STATE.image_ai_path = pick("image_ai_path", CAT.image_ai_path);
STATE.generation_mode = pick("generation_mode", CAT.generation_mode);
@@ -1472,14 +1547,16 @@
var payload = JSON.parse(JSON.stringify(STATE));
normalizeTypographyForSubmit(payload);
payload.stage = "final";
- var customImagePlan = usesCustomImagePlanValue(payload.image_usage);
- if (payload.image_usage === "custom" || (customImagePlan && !String(payload.image_usage).trim())) {
- document.getElementById("confirm-status").textContent = t("image_usage_custom_required");
- var customImageInput = document.querySelector(".image-usage-custom-input");
- if (customImageInput) customImageInput.focus();
+ payload.image_usage = selectedImageUsageIds(payload.image_usage);
+ if (!payload.image_usage.length) {
+ document.getElementById("confirm-status").textContent = t("image_usage_required");
+ return;
+ }
+ if (payload.image_usage.indexOf("none") >= 0 && payload.image_usage.length > 1) {
+ document.getElementById("confirm-status").textContent = t("image_usage_none_exclusive");
return;
}
- if (customImagePlan) payload.image_usage = String(payload.image_usage).trim();
+ if (!String(payload.image_notes || "").trim()) delete payload.image_notes;
if (!needsGeneratedImagesForUsage(payload.image_usage)) {
delete payload.image_ai_path;
delete payload.image_strategy;
diff --git a/skills/ppt-master/scripts/confirm_ui/static/style.css b/skills/ppt-master/scripts/confirm_ui/static/style.css
index 20dde656..c0411c68 100644
--- a/skills/ppt-master/scripts/confirm_ui/static/style.css
+++ b/skills/ppt-master/scripts/confirm_ui/static/style.css
@@ -175,6 +175,7 @@ body {
.font-sample-body { font-size: 14px; color: #333; margin-top: 4px; }
.custom-typography-input { margin-top: 8px; min-height: 58px; resize: vertical; }
.custom-color-input { margin-top: 8px; min-height: 58px; resize: vertical; }
+.image-usage-notes-input { min-height: 64px; resize: vertical; }
.font-size-row { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
.font-size-input { width: 96px; }
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index dec4a772..d0eee534 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -1,6 +1,6 @@
# Confirm UI — Eight Confirmations Page
-> The interactive, visual surface for SKILL.md Step 4 (the Eight Confirmations). Enumerable fields list **all** options from a catalog with the AI's recommendation badged; generative fields (color, typography, generated-image style) show **≥3** AI candidates (creative recommendations always offer real choice — same rule as the h.5 image strategy; fewer only on the honest-shortfall exception, with a stated reason). Fields whose universe is open (canvas, mode, visual style, icons, image usage) also get a **Custom** box; fully closed fields (AI source when applicable, formula policy, generation mode, refine spec) do not. The AI writes its recommendation to `recommendations.json`; the user's final choices are written back to `result.json` for the AI to read. On confirm the page saves the result and shuts the server down (auto-close). The chat path is always a valid fallback — if the browser cannot open (remote / headless / web host), the AI presents the same confirmations in chat.
+> The interactive, visual surface for SKILL.md Step 4 (the Eight Confirmations). Enumerable fields list **all** options from a catalog with the AI's recommendation badged; generative fields (color, typography, generated-image style) show **≥3** AI candidates (creative recommendations always offer real choice — same rule as the h.5 image strategy; fewer only on the honest-shortfall exception, with a stated reason). Fields whose universe is open (canvas, mode, visual style, icons) also get a **Custom** box; image usage is a multi-select source list plus a free-text `image_notes` box. Fully closed fields (AI source when applicable, formula policy, generation mode, refine spec) do not. The AI writes its recommendation to `recommendations.json`; the user's final choices are written back to `result.json` for the AI to read. On confirm the page saves the result and shuts the server down (auto-close). The chat path is always a valid fallback — if the browser cannot open (remote / headless / web host), the AI presents the same confirmations in chat.
## `confirm_ui/server.py`
@@ -31,13 +31,14 @@ pip install flask
## Two kinds of field
-- **Enumerable + custom** — canvas / mode / visual_style / icons / image usage. The page lists common options from `static/catalogs.json`, badges the AI's recommendation, and still offers a Custom box for edge cases (custom canvas size, bespoke narrative mode, mixed image plan, self-provided icon system, etc.). `visual_style` additionally honors an optional `visual_style_spectrum` that badges a 3-pick personality spectrum (safe / shifted / bold, each with a temperament tag + analogy) in place of the single recommendation — see the schema below.
-- **Closed enumerable** — formula policy / generation mode / refine spec, plus AI source only when image usage may include `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option. Use pipeline vocabulary: icon ids are actual library ids such as `tabler-outline`, or `emoji` for system emoji; image usage labels mirror Strategist terminology: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. Use image-usage custom prose only when several sources are mixed.
+- **Enumerable + custom** — canvas / mode / visual_style / icons. The page lists common options from `static/catalogs.json`, badges the AI's recommendation, and still offers a Custom box for edge cases (custom canvas size, bespoke narrative mode, self-provided icon system, etc.). `visual_style` additionally honors an optional `visual_style_spectrum` that badges a 3-pick personality spectrum (safe / shifted / bold, each with a temperament tag + analogy) in place of the single recommendation — see the schema below.
+- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
+- **Closed enumerable** — formula policy / generation mode / refine spec, plus AI source only when image usage includes `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option. Use pipeline vocabulary: icon ids are actual library ids such as `tabler-outline`, or `emoji` for system emoji.
- **Generative (open)** — color, typography, generated-image style. No finite catalog; the AI authors **≥3 candidates** the page renders as cards (never a single option — creative fields must offer real choice; fewer than 3 only on the honest-shortfall exception). `page_count`, `audience`, and `content_divergence` are free inputs (`content_divergence` is a free-text intent shown under audience in §c, not a fixed-option field).
-**Custom box** appears only on fields whose universe is genuinely open — `canvas`, `mode`, `visual_style`, `icons`, and `image_usage`. Fully closed sets — `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec` — have **no** Custom box; an out-of-catalog value there is snapped back to the recommended option.
+**Custom box** appears only on fields whose universe is genuinely open — `canvas`, `mode`, `visual_style`, and `icons`. Image usage uses a multi-select source list plus `image_notes` instead of a Custom box. Fully closed sets — `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec` — have **no** Custom box; an out-of-catalog value there is snapped back to the recommended option.
-`image_ai_path` is conditional: the page shows it and writes it to `result.json` only when `image_usage` is `ai` or a custom image plan that may include AI. Web-sourced / User-provided / Placeholder / No images paths do not carry an AI backend choice.
+`image_ai_path` is conditional: the page shows it and writes it to `result.json` only when `image_usage` includes `ai`. Web-sourced / User-provided / Placeholder / No images paths do not carry an AI backend choice.
## Catalogs — `static/catalogs.json` (the finite option universe)
@@ -69,7 +70,7 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
"mode": "pyramid",
"visual_style": "swiss-minimal",
"icons": "tabler-outline",
- "image_usage": "ai",
+ "image_usage": ["ai", "provided"],
"image_ai_path": "auto",
"formula_policy": "mixed",
"generation_mode": "continuous",
@@ -78,6 +79,7 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
"page_count": { "value": "12-15" },
"audience": { "value": "..." },
"content_divergence": { "value": "" },
+ "image_notes": { "value": "封面和章节页用 AI 主视觉;产品页优先用户素材,缺口页可用占位符。" },
"color": {
"selected": 0,
"candidates": [
@@ -127,16 +129,17 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
> Each `candidates` array above shows **one** entry for brevity — the creative fields (`color`, `typography`, `image_strategy`) must each carry **≥3** in a real file (see the rule above); `selected` indexes the recommended default.
-- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids. For `recommend.image_usage`, do not write bare `"custom"`; if several image sources are mixed, write the concrete prose plan directly, such as `"封面用 AI 生成,产品页用用户素材,行业页用网络来源"` / `"AI cover + user product assets + web industry images"`.
-- When `recommend.image_usage` is `ai` or a custom plan that includes AI, also set `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`; the page presents these as explicit choices.
-- For a custom image plan, the page treats "may include AI" as true only when the recommendation includes `recommend.image_ai_path` or `image_strategy.candidates`; a custom plan without those signals is handled as non-AI and omits AI controls / fields.
+- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids.
+- `recommend.image_usage` should be an array of source ids when more than one source applies, e.g. `["ai", "provided"]`. A single string is still accepted for backward compatibility. Do not write bare `"custom"` and do not encode a mixed-source plan as prose here; write the prose to top-level `image_notes.value`.
+- `image_notes` is the initial strategy note shown under the image source chips. Use it for page-role guidance and constraints: which source applies where, what to avoid, which user assets are authoritative, how realistic / abstract the imagery should be, and what can remain as placeholders. It is intent guidance, not a separate finite option.
+- When `recommend.image_usage` includes `ai`, also set `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`; the page presents these as explicit choices.
- **Color candidates carry the user-facing core `palette`**: `background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, and `body_text`. The page renders labelled swatches and offers per-role override inputs for precise single-role edits, plus a **Custom color card with a free-text box** (parallel to the custom typography box) — the user can describe the palette in words or paste HEX values instead of filling each role; this writes `color: { "name": "custom", "custom": "<text>" }` to `result.json` for the AI to interpret. Legacy `text` is accepted as an alias for `body_text`, but new files should write `body_text`. Strategist derives secondary text, borders, state colors, and visual-style neutral tiers later when writing `design_spec.md` / `spec_lock.md`; those are not user-facing confirmation choices.
- **Candidate display text may be bilingual**: color / typography candidates can provide `name_zh` / `name_en` and `note_zh` / `note_en`; the page falls back to legacy `name` / `note`.
- **Typography candidates split CJK and Latin** for both `heading` and `body`; `css` is the fallback preview `font-family` stack. The page previews CJK sample text with `cjk + css` and Latin sample text with `latin + css`, so the two script choices are visible independently. Each candidate should include topic-matched `sample_heading`, `sample_heading_latin`, `sample_body`, and `sample_body_latin`; do not reuse unrelated fixed examples such as a digital-transformation headline for a travel, education, product, or brand deck. Each candidate should also include `body_size` — the body baseline in **px** (the system's only unit, every canvas). The initial value comes from the candidate's `body_size`, sized for the recommended delivery purpose: `text` ~20 · `balanced` ~24 · `presentation` ~32. On submit the page writes `typography.body_size` as px directly — no pt conversion, no `body_size_pt` provenance. The page exposes `body_size` as an editable numeric field whose hint shows the recommended size — **one fixed px per delivery purpose on PPT (`text` 20 · `balanced` 24 · `presentation` 32), not a range** (non-PPT ≈2.5–3.3% of height in px). The user may still edit it; an out-of-range flag only warns if the value strays far (e.g. a unit mistake). **Inputs are independent — the hint updates with canvas / delivery purpose but never rewrites a value the user can see.** It also offers a custom typography text box so the user is not limited to the proposed candidates.
- **Per-role size override** (parallel to color's per-role HEX override): besides `body_size`, the page exposes **independent** editable inputs for `title` / `subtitle` / `annotation`. Each role is pre-filled **once** with a starting value — the candidate's `typography.sizes[role]` if provided, otherwise a one-time ramp suggestion (`body × ` mid-band ratio) — and then holds its own value. **There is no cross-field cascade**: changing `body_size`, `delivery_purpose`, or canvas updates only the recommended-value hint, never the role values; a re-render preserves exactly what the user sees. The final values are written to `result.json` as `typography.sizes: { "title", "subtitle", "annotation" }` in **px** — every canvas, no pt and no `sizes_pt` provenance. Seeding `sizes` in a candidate is optional — omit it and each role gets its one-time ramp suggestion.
- **`delivery_purpose`** (enumerable, PPT only) is the primary driver of the body baseline: `text` (read-close), `balanced` (business, the default), `presentation`. It is surfaced in the **§c key-information area** (beside audience, Tier 1) as a consumption-mode choice; the Tier-2 typography section then reads the confirmed value for the recommended body px — the pick itself does not rewrite the body field (inputs are independent). `recommend.delivery_purpose` pre-selects one (default `balanced`); the user's pick writes back to `result.json.delivery_purpose` as a plain id. Strategist uses it to set the px body baseline — **one fixed px per purpose (`text` 20 · `balanced` 24 · `presentation` 32), not a range** (see [strategist.md §g](../../references/strategist.md)). Non-PPT canvases omit it.
- **Combined style preview** — a compact live "overall impression" strip sits just above the color section and is **sticky**: it pins under the topbar so it stays visible while the user scrolls through the color / icon / typography sections, keeping the picking controls and their combined effect on screen together. It applies the currently selected color palette **and** typography (heading sample in `primary` over `background`, body sample in `body_text`, an `accent` bar, a `secondary_bg` chip) and repaints on every color / HEX-override / font / `body_size` change. It does not replace the per-candidate swatches or font samples (those stay for picking); it is deliberately an abstract style chip, **not** a slide-layout preview — page layout preview remains the live-preview server's job (Step 6). No schema field; it derives entirely from the existing color + typography selections.
-- **Generated image style candidates** live in `image_strategy.candidates` and are shown only when `image_usage` is `ai` or a custom image plan may include generated images. Each candidate records `rendering`, `palette`, and short `visual` / `color` / `mood` lines from Strategist h.5. The chosen value is written to `result.json.image_strategy`; it is omitted when generated images are not part of the plan.
+- **Generated image style candidates** live in `image_strategy.candidates` and are shown only when `image_usage` includes `ai`. Each candidate records `rendering`, `palette`, and short `visual` / `color` / `mood` lines from Strategist h.5. The chosen value is written to `result.json.image_strategy`; it is omitted when generated images are not part of the plan.
- **`visual_style_spectrum`** (optional) lets the AI surface the deck's aesthetic as a **personality spectrum** instead of one badged style. Each entry is `{ "id", "tag_zh"/"tag_en", "note_zh"/"note_en" }` where `id` is a real `visual_styles` catalog id; the page badges those chips with their temperament `tag` (replacing the single ★) and appends the `note` (a real-world analogy) inline. The full grouped style list and Custom box stay visible below, and `recommend.visual_style` is still the pre-selected default (it should equal the spectrum's safe pick). Author **≥3** spanning safe / shifted / bold (mirrors h.5; honest-shortfall exception applies — fewer only when the constraints genuinely cannot yield 3). The user's pick still writes back to `result.json.visual_style` as a plain id; the spectrum is presentation-only. Omit the field to fall back to the single-recommendation badge.
- `recommend.generation_mode` and `refine_spec` mirror the two mandatory notes in SKILL.md Step 4. Confirmed `generation_mode: "split"` / `refine_spec: true` are explicit user choices, equivalent to opting in through chat.
- `content_divergence` is a **free-text** field shown right under the audience box in §c — the user states in their own words how closely to follow the source vs how freely to reshape it (e.g. "stick closely to the document" / "freely restructure and expand within the source"). It is **not** a fixed-option field; blank means a balanced default. Whatever the level, facts stay sourced — reshaping develops what is in the source, never imports facts from outside it. The Strategist consumes the prose when authoring the §IX outline and records it in `design_spec.md §I`; it is **not** written to `spec_lock.md` (the Executor never reads it). It carries no page-count coupling and no source-signal recommendation — it is purely the user's stated intent. Beautify / template-fill keep content verbatim and do not surface this field.
@@ -157,7 +160,8 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
"typography": { "name": "...", "heading": { "cjk": "...", "latin": "...", "css": "..." }, "body": { "cjk": "...", "latin": "...", "css": "..." }, "body_size": 24, "body_size_unit": "px", "sizes": { "title": 42, "subtitle": 32, "annotation": 18 } },
"delivery_purpose": "balanced",
"formula_policy": "mixed",
- "image_usage": "ai",
+ "image_usage": ["ai", "provided"],
+ "image_notes": "封面和章节页用 AI 主视觉;产品页优先用户素材,缺口页可用占位符。",
"image_ai_path": "auto",
"image_strategy": { "name": "方案 A", "rendering": "vector-illustration", "palette": "cool-corporate", "visual": "...", "color": "...", "mood": "..." },
"generation_mode": "continuous",
@@ -170,8 +174,8 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
The shape above is the **final** (Tier 2) result, carrying all Tier 1 + Tier 2 fields. The intermediate **Tier 1** write carries only the anchor fields plus `"stage": "tier1"`, `"status": "tier1-confirmed"`; the AI reads it to re-derive Tier 2 and never treats it as the final confirmation. A legacy single-pass write has no `stage` (or `stage: "final"`) and `status: "confirmed"`.
-- Any option field may instead hold a **free-text custom string** (the user picked **Custom**); `color` / `typography` custom entries set `name: "custom"`. Image usage custom values must be concrete prose plans, not the literal string `"custom"`. The AI interprets custom text against the canonical references.
-- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` is `ai` or a custom image plan that may include generated images. Both are honored downstream as confirmed choices — and the page is only a convenience surface over the **canonical chat channel**: the same choices made in chat are honored identically when no `result.json` exists. `image_ai_path` drives the Step 5 generation path (`image-generator.md` §7 — `host-native` forces the host tool even when `IMAGE_BACKEND` is set); the chosen `image_strategy` candidate is locked verbatim by Strategist h.5 (no re-pick).
+- Any option field may instead hold a **free-text custom string** (the user picked **Custom**); `color` / `typography` custom entries set `name: "custom"`. Image usage is not a custom string in new results: it is a source-id array, with free-text strategy captured in `image_notes`.
+- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` includes `ai`. Both are honored downstream as confirmed choices — and the page is only a convenience surface over the **canonical chat channel**: the same choices made in chat are honored identically when no `result.json` exists. `image_ai_path` drives the Step 5 generation path (`image-generator.md` §7 — `host-native` forces the host tool even when `IMAGE_BACKEND` is set); the chosen `image_strategy` candidate is locked verbatim by Strategist h.5 (no re-pick).
- After the user clicks the **final Confirm** (Tier 2, or single-pass), the page saves `result.json` and shuts the server down (auto-close). A Tier-1 **Next** instead keeps the page open (it polls for the re-derived Tier 2). In the default flow, the first `--daemon --wait` returns on the tier-1 result and the second `--wait-only` returns on the final result; the AI reads each immediately — no extra chat confirmation is required. Chat confirmation remains the fallback when the page cannot be used. Either way, Step 4 ends with a `--shutdown` cleanup so a never-confirmed page cannot keep holding port 5050 ahead of the Step 6 live preview.
## Scope