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

fix(native-shapes): make preset recall shell-safe

hugohe34d11a75bdc76
diff --git a/AGENTS.md b/AGENTS.md
index 511d8144..ae7230c8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,10 @@ first command. Paths in this file are repository-relative notation only; invoke
them through those absolute roots, retain the absolute project path returned by
initialization, and never issue `cd skills/ppt-master` or `cd projects/...`.
When parsing machine-readable stdout, keep stderr separate and never place
-`2>&1` upstream of a JSON or XML parser.
+`2>&1` upstream of a JSON or XML parser. Invoke each such command once per
+concrete argument set; never encode its executable or flag list in scalar shell
+strings, batch it through a shell loop, or add a downstream parser when the
+command provides a compact view.
## Project Overview
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index 6d6ea0af..3341a1e0 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -20,16 +20,22 @@ 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.
+**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
+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 --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
+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,
@@ -104,7 +110,7 @@ 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` 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. |
+| 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. |
| 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. |
@@ -112,12 +118,12 @@ Apply this page-local sequence before drawing:
Example recall and inspection commands:
```bash
-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py recommend \
+python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" recommend --compact \
--role spine --relationship order --directionality horizontal --aspect wide \
--limit 6
-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py describe chevron --compact
+python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" describe chevron --compact
-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py recommend \
+python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" recommend --compact \
--scope flowchart --role node --relationship flow --query decision --limit 6
```
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index c6365de8..864ff20a 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -198,7 +198,7 @@ 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 --role spine --relationship order \
+python3 scripts/preset_shape_svg.py recommend --compact --role spine --relationship order \
--directionality horizontal --aspect wide --limit 6
python3 scripts/preset_shape_svg.py describe rightArrow --compact
python3 scripts/preset_shape_svg.py render rightArrow --id process-arrow --frame 120 180 240 96 --fill '#2563EB'
@@ -218,7 +218,10 @@ 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. The
+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
diff --git a/skills/ppt-master/scripts/preset_shape_svg.py b/skills/ppt-master/scripts/preset_shape_svg.py
index f54f37d9..fc16e7a7 100644
--- a/skills/ppt-master/scripts/preset_shape_svg.py
+++ b/skills/ppt-master/scripts/preset_shape_svg.py
@@ -9,14 +9,14 @@ page or template.
Usage:
python3 scripts/preset_shape_svg.py list [--grouped] [--search QUERY]
python3 scripts/preset_shape_svg.py describe PRESET [--compact]
- python3 scripts/preset_shape_svg.py recommend --role ROLE [options]
+ python3 scripts/preset_shape_svg.py recommend --role ROLE [options] [--compact]
python3 scripts/preset_shape_svg.py render PRESET --id ID --frame X Y W H
python3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASH
Examples:
python3 scripts/preset_shape_svg.py list --grouped
python3 scripts/preset_shape_svg.py recommend --role spine \
- --relationship order --directionality horizontal
+ --relationship order --directionality horizontal --compact
python3 scripts/preset_shape_svg.py describe rightArrow --compact
python3 scripts/preset_shape_svg.py render rightArrow --id next-step \
--frame 160 210 320 112 --fill "#2563EB" --stroke none
@@ -173,6 +173,14 @@ def build_parser() -> argparse.ArgumentParser:
default=12,
help="Maximum returned candidates; default: 12.",
)
+ recommend_parser.add_argument(
+ "--compact",
+ action="store_true",
+ help=(
+ "Print a reduced recall view for direct inspection without "
+ "downstream parsing."
+ ),
+ )
render_parser = subparsers.add_parser(
"render",
@@ -338,7 +346,7 @@ def main(argv: Sequence[str] | None = None) -> int:
return 0
if args.command == "recommend":
- payload = get_preset_shape_semantics().recommend(
+ full_payload = get_preset_shape_semantics().recommend(
roles=args.role,
scope=args.scope,
relationships=args.relationship,
@@ -349,6 +357,27 @@ def main(argv: Sequence[str] | None = None) -> int:
query=args.query,
limit=args.limit,
)
+ payload = (
+ {
+ "criteria": full_payload["criteria"],
+ "candidate_count": full_payload["candidate_count"],
+ "returned_count": full_payload["returned_count"],
+ "selection_note": full_payload["selection_note"],
+ "candidates": [
+ {
+ "preset": candidate["preset"],
+ "scope": candidate["scope"],
+ "literal_only": candidate["literal_only"],
+ "intent": candidate["intent"],
+ "why": candidate["why"],
+ "avoid_for": candidate["avoid_for"],
+ }
+ for candidate in full_payload["candidates"]
+ ],
+ }
+ if args.compact
+ else full_payload
+ )
print(json.dumps(payload, ensure_ascii=False, indent=2))
return 0
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index 50b4dcfd..35c28bd0 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -563,13 +563,14 @@ capability 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 `recommend --limit 6` defined by
+page-local direct `recommend --compact --limit 6` invocation defined by
[`native-shape-authoring.md`](../../references/native-shape-authoring.md) from
-the actual job, then `describe --compact` only 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 relationship / carrier fit,
+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
+relationship / carrier fit,
contour-family / exact-result choice, reader effect for a generic or undrawn
result, running actual-geometry signature, and materialization boundary. A
primitive remains valid when it wins this comparison; there is no preset quota.