3-stage agent workflow (outline -> one scene per turn -> validated merge), per-turn fragment gate, validation commands, smoke test with the shipped examples, plan_json_input wiring notes, and requirements.
96 lines
4.8 KiB
Markdown
96 lines
4.8 KiB
Markdown
# mmprompt
|
||
|
||
## h3-plan-gate — MiniMax H3 plan-JSON agent workflow + validator
|
||
|
||
Prompt set and tooling that turn a story idea into the `plan_json_input` JSON for the
|
||
**Production Plan** node (`MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)`) in
|
||
[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop),
|
||
verified against commit `43afeff`. The workflow is agent-shaped: one outline turn, one turn
|
||
per scene, then a validated merge — so long stories are written scene by scene and single
|
||
scenes can be regenerated without touching the rest.
|
||
|
||
### Files
|
||
|
||
| File | Role |
|
||
|---|---|
|
||
| `h3_scene_agent_system_prompt.md` | Stage 1 + 2 system prompts: **PROMPT A** (outline planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) |
|
||
| `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts |
|
||
| `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories |
|
||
| `build_plan.py` | Deterministic Stage 3 merger: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing |
|
||
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments) with an embedded test suite |
|
||
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) |
|
||
| `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` |
|
||
|
||
### Agent workflow (3 stages)
|
||
|
||
**Stage 1 — Outline.** Put PROMPT A (from `h3_scene_agent_system_prompt.md`) in the system
|
||
field, the story idea in the user field. Save the reply as `outline.json`. It freezes scene
|
||
count, ids, durations, beats, verbatim dialogue distribution, and the `style_and_cast` block
|
||
so later turns cannot drift. You may hand-edit it before Stage 2 — the scene agents follow
|
||
the edited skeleton.
|
||
|
||
**Stage 2 — One scene per turn.** Put PROMPT B in the system field and paste this turn
|
||
template as the user message:
|
||
|
||
```text
|
||
STORY: <the full story idea>
|
||
STYLE AND CAST: <paste the "style_and_cast" object from the outline>
|
||
OUTLINE: <paste the "scenes" array from the outline>
|
||
WRITE SCENE: 2
|
||
PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is scene 1.>
|
||
```
|
||
|
||
Save each reply as `scene_NN.json` (zero-padded). Each fragment carries the native H3
|
||
three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_soundscape: …`
|
||
/ `non_diegetic_music: …`), the duration-tiered word budget, and a truthful `_handoff`
|
||
object for the next turn. Optional gate after each turn:
|
||
|
||
```sh
|
||
python3 h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json
|
||
```
|
||
|
||
**Stage 3 — Assembly (deterministic, preferred):**
|
||
|
||
```sh
|
||
python3 h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
|
||
```
|
||
|
||
The merger validates every fragment in the `_handoff` chain (against the outline when
|
||
present), then validates the merged plan — only clean JSON is written. Do **not** edit
|
||
fragment prose by hand during assembly; if you want a scene changed, re-run its Stage 2
|
||
turn and re-merge. Use the LLM assembler prompt only in a pure-chat setup with no script
|
||
execution, and diff its output against the fragments if you do (small models transcribe
|
||
long strings unreliably; `build_plan.py` is byte-exact by construction).
|
||
|
||
### Validating
|
||
|
||
```sh
|
||
python3 h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite
|
||
python3 h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan
|
||
python3 h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report
|
||
```
|
||
|
||
Smoke test with the shipped examples:
|
||
|
||
```sh
|
||
python3 h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
|
||
# expect: PLAN OK — 1042 delivered frames = 43.42s
|
||
```
|
||
|
||
### Wiring the result
|
||
|
||
Paste the full contents of `plan.json` into the Plan node's forced STRING input
|
||
**`plan_json_input`** — a non-empty connected value overrides the visual editor's plan and
|
||
receives identical normalization/validation. Resolution, context length, audio mode, and
|
||
`base_seed` stay on the node's own widgets (the JSON cannot set them; default canvas is
|
||
960×544 — set width/height widgets and wire the width/height outputs into the conditioning
|
||
node and sampler latent to avoid square output).
|
||
|
||
### Requirements
|
||
|
||
- `build_plan.py` and `verify_plan_rules.py`: Python 3 stdlib only.
|
||
- `count_prompt_tokens.py`: needs `tiktoken`.
|
||
- LLM settings: temperature 0.3–0.7; enable `response_format: {"type": "json_object"}` or
|
||
grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so
|
||
ctx 16384 is comfortable; 128k runs the whole workflow many times over.
|