miora-video-studio

miora Video Generation Workbench

Prerequisites: The current environment already has the WorkBuddy / Miora video tool configured. If the tool is unavailable, this Skill can only be used for diagnosis and explanation, and cannot replace the actual video generation channel.

If the environment also provides the following Skills, they can be loaded in coordination:

miora-creative-core — Foundation: confirmation and cost boundaries, how to set parameters before generation, canvas delivery.
miora-video-generation — Decision-making: shot language, duration and aspect ratio, subject consistency, failure handling.

They are not installation prerequisites for this Skill; this Skill itself is responsible for:How to determine the completion signal, how far the parameters have been measured, and how to modify the prompt。

1. The one and only core issue: the completion signal

The miora generation process and the conversation process are separate. From this follow five points, none of which may be violated:

The completion signal comes from the fact of the file being written to disk, not from the interface return. The return value may be lost entirely—this has been observed in practice: a 15-second video was generated successfully and the finished video had already been written to disk, yet the caller received nothing. Treating "no return" as "failure" is wrong. The reverse situation also exists: the call will block until the task is complete and then return status: completed + resultFiles[].localPath(measured wait of about 6.4 minutes), in which caseyou still need to go through one --wait verification—read the specifications from the file header, and do not trust self-reported values.
- In the return valuecarries a localPath when present, that binding takes precedence over file scanning: immediately --wait --claim <localPath> --job <作业名> record it (see Section 4;--claim is not an independent action and must be given together with one of --submit/--wait/--poll/--poll-all , otherwise argparse will directly error out and exit). Do not let heuristic scanning have any chance to count a concurrent job's finished video as yours.
Register the job before submitting, then initiate generation. If the order is reversed, cross-turn traceability is lost.
Poll immediately after generation, without relying on the user to send another message. Videos take 6 to 21 minutes, which can be waited out in a single turn.
Specifications are based on the file header, read out the duration / resolution / audio track yourself, and do not trust self-reported values.
Do not resubmit. An unclear status does not equal failure; resubmitting will result in duplicate billing, and an already submitted task cannot be canceled.

The accompanying script scripts/miora_watch.py implements the above determination.

Before calling, you need to connect_cloud_service obtain session credentials, and pass clientTempToken as tempKey to the video tool.Credential validity is unstable—it has been observed that the same token was rejected on its second use within the same minute (AUTH_INVALID_TEMP_KEY). Therefore: if it reports AUTH_*_TEMP_KEY , obtain a new one and retry;when retrying consecutively, simply obtain a new one each time, which is less trouble than guessing the validity period. Credential contents must not be shown to the user.

1.1 Step 0: First check whether the tool is present

Check every time you start work; do not skip it based on last time's experience— availability may differ across sessions on the same machine (verified in practice: on the same machine, in one session mcp__miora__* was working normally and successfully produced output, while in another new session it was not registered at all).

The first step when starting work is to confirm whether the current session's tool list includes mcp__miora__*。

The determination has three steps, and the order cannot be reversed— the two forms of "missing" are easy to misjudge.

Step one: first look at the main tool list. If mcp__miora__miora_reference_to_video / mcp__miora__miora_text_to_video / mcp__miora__miora_write_canvas theseappear directly in the current session's callable tool list, then it is available, and you can start work directly. No further probing is needed — they are not in the deferred index,ToolSearch so they can never be found by searching for them.

Step two (only when mcp__miora__* cannot be seen in the main list): ToolSearch Use queries: ["miora"] to search. The results here are only used to identify the empty-shell state of "the server entry is present, but not a single sub-tool is registered":available_deferred_tools lists mcp__miora, but by comparing with mcp__agent-mail / mcp__sheetagent you can see that the other one's sub-tool names are all expanded, while miora's are not.

Step three (second confirmation): Use DeferExecuteTool to probe mcp__miora__miora_reference_to_video— reporting Tool "..." not found in the deferred tools index is the decisive evidence.

Step four (only do this after a missing state is confirmed, to distinguish "not configured" from "not enabled"): Look at the three pieces of on-disk evidence together, so the conclusion given to the user is specific.

File	What is seen	Explanation
`~/.workbuddy/mcp.json`	Has `mcpServers.miora` entry (`command: node` + `args` points to `miora-mcp/dist/cli.cjs`，`defer_loading: false`）	The configuration is present, not "not configured"
`~/.workbuddy/mcp-approvals.json`	The content is `{}`	No MCP is trusted/approved → the service is not enabled
`~/.workbuddy/plugins/data/mcp-miora/miora-media` The latest `.mp4`	mtime is a few minutes ago	The channel was previously normal, and the outputs are all there

At the same time, compare available_deferred_tools: miora appears only asa bare mcp__miora with sub-tool names not expanded, while mcp__agent-mail / mcp__sheetagent 's sub-tool names are all listed in full —this asymmetry itself is the empty-shell signature. Add to that defer_loading: false(which should be in the main list) not being in the main list, and the two points corroborate each other.

Based on this, three things can be stated: ① This issession-level not enabled/not registered, not plugin damage (miora-mcp/dist/cli.cjs is still there, and the historical outputs are still there); ② The requirement specification itself is fine; ③ The minimal unblocking action is to go to the upper-right corner of connector management, in "Custom connectors", trust the miora service, and restart the session.Do notrun dist/cli.cjs yourself or modify mcp-approvals.json to fake trust.

⚠️ Pitfalls encountered (verified in practice on 2026-09-16)：ToolSearch only indexes deferred tools,not being able to find mcp__miora__* does not mean it is not registered. That time queries: ["miora"] only returned connect_cloud_service, which looked like "not registered", but mcp__miora__miora_reference_to_video was originally in the main list, and calling it directly once successfully produced output (15s / 768P / 4 reference images, about 6.8 minutes).The basis for judgment is "whether it is in the main list", not "whether ToolSearch can find it"— acting on the latter will misjudge a usable channel as unavailable and block a delivery for nothing.

After confirming the absence, roll back the placeholder marker that was registered. If during probing you happened to run --submit, that is a job that never completes and will pollute the --poll-all list; use os.remove to delete ~/.workbuddy/miora-jobs/<作业名>.json(delete only the one you just created this time).

Giving the user a piece of on-disk evidence is more convincing: read the mtime of the latest ~/.workbuddy/plugins/data/mcp-miora/miora-media under .mp4 , and you can say "the most recent successful render was just a few minutes ago." In actual testing, the media directory contained a miora_reference_to_video-*.mp4produced about 7 minutes earlier, while in the new session the tool was completely unregistered—based on this you can explain clearly that this is asession-level registration issue, and that the plugin itself, historical renders, and reference materials are all still there; neither the materials nor the outputs were lost.

If there is none, stop and explain; do not look for a substitute. On this machine, miora-mcp is in a product-level hidden state:workbuddy-builtin/mcps/miora-mcp/HIDDEN.md records that it has been removed from marketplace registration and will not be loaded at runtime. At this point, truthfully inform the user:

The plugin itself, historical renders, and reference materials are all still there, but currentlythere is no usable miora channel；
The requirement specification itself is fine (for example, 9 seconds falls within the legal range of 4–15 seconds); the blocker is only the missing tool;
no environment changes were made.

Do not switch to a substitute tool: the built-in VideoGen(Hunyuan) only takes 1 first frame + 1 last frame, does not support multiple reference images, and has no duration parameter—it cannot produce an equivalent result to reference-to-video. Switching to it would be a silent downgrade.

Stop at this step; do not register a job and do not submit a generation.

2. Three modes

What you have on hand	Mode	Tool
Text only	Text-to-video	`mcp__miora__miora_text_to_video`
Have an image and want it as the starting frame (optionally also provide an ending frame)	First-and-last-frame-to-video	`mcp__miora__miora_frame_to_video`
Have an image and want it to anchor the subject or style	Reference-to-video	`mcp__miora__miora_reference_to_video`

Two hard rules:

If you have materials, never use a text-only tool. Reference images, confirmed anchors, and the previous round's final cut are all hard constraints; degrading to a text description gets you something that "looks similar but is not the same," and this invalid generation will be paid for by the user.
With multiple images, the roles must be stated explicitly. Add a line at the beginning of the prompt: "Image 1 = main subject, Image 2 = scene, Image 3 = prop." When the user references them with @image#N , add a number mapping table so the numbers can be resolved—this is a structural addition and does not count as changing the user's original text.

3. Specification facts

Source of the standard: MiniMax official documentation platform.minimax.cn/docs/guides/video-generation(H3 / H3 Max), verified on 2026-09-16; entries marked "local actual test" are the actual behavior produced by this channel.

3.1 Gate one: four required parameters — if even one is missing, submission is not allowed

Mode, resolution, duration, aspect ratioThese four itemsmust be declared by the user. If any one of the four is missing,do not call miora, and do not guess on their behalf.

Required parameter	Legal values
Mode	Text-to-video / First-and-last-frame-to-video / Reference-to-video
Resolution	`768P` / `2K`
Duration	Integer from 4 to 15 seconds
Aspect ratio	`16:9` / `9:16` / `1:1` etc.

Standard action when items are missing:

Stop, do not submit, and clearly tell the user which items are still missing;
The missing itemslist them all at once(do not ask one per round), and state "submission and generation can only happen after all four items are filled in";
You may givesuggested valuesto help the user decide, buta suggestion is not a default—unless the user agrees, you may not write it into the parameters.

Four forbidden things：

Filling in a "reasonable default" and submitting—this skill no longer sets any automatic default for these four items；
Bluffing your way through with a verbal description (for example, not providing duration, and hoping the model decides on its own);
Asking about only part of it and submitting the task first;
Claiming "I filled in the default value according to your intent"—you have no such authority.

One situation that does not count as a legally missing item: the user declared a certain item, but the value is invalid (for example, the resolution is stated as 720p). This counts asdeclared—it belongs to value clarification, not parameter omission—map it to a legal equivalent tier and disclose it (720p → 768P, see 3.2).

The mode item must also be aligned with the materials: if you have a reference image on hand, you must use reference-to-video or first-and-last-frame-to-video,and must not degrade to text-to-video(see Section 2).

When all four items are present, treat them directly as confirmed; do not ask again; for the remaining parameters (prompt content, choice of reference materials), follow Sections 2 and 6.

With miora-creative-corethe conflict ruling of "AskUserQuestion confirmation is required before generation": when the four parameters are complete and the specificationsare all declared by the user(none of them is a default value filled in by the model), and the reference materials are also clear,do not ask again, and submit directly—the specifications were given by the user in the first place, and repeated confirmation only adds another round trip; when the user has written the script down to the storyboard second-level timeline, that is even more clearly a finalization signal. The only situations that require asking again are: a change in output scale, a substantive change in parameters, or the user requesting a redo. If core's confirmation step really must be done, it should also be packed with substantive information about "what is being produced / specifications / materials", and must not be made into a vague "confirm to continue?"

3.2 Output specifications

Item	MiniMax H3 (currently in use on this channel)	MiniMax H3 Max
Model name	`MiniMax-H3`	`MiniMax-H3-Max`
Output resolution	`768P` / `2K`	`480P` / `768P`
Output duration	4 to 15 seconds, integers only	5 to 15 seconds, integers only

Measured on this machine:resolution only accepts 768P / 2K, passing 720p / 1080p is rejected by the upstream—unsupported video resolution: 720p, supported values: [768P 2K]. When the user says 720p , submit according to 768P (the native 16:9 tier is 1344×768, an equivalent tier, not a downgrade), and state this clearly in the delivery notes; when the user wants a higher tier, use 2K。
16:9 output 1344×768；24 FPS; the final videocarries a native stereo audio track（32 kHz）。
Measured on this machine (2026-09-16):15 seconds + 768P + 4 reference imagespassed in one go, and the file header reads 15.08 seconds / 1344×768 / has_audio: true。4 images is exactly the legal boundary value at the channel limit, no need to leave margin "just in case".
The finished video duration will be slightly longer than the requested value: requesting 9 seconds → file header mvhd reads 9.42 seconds(due to frame alignment); in the same batch of actual measurements there were also 11 seconds → 11.54 seconds, 12 seconds → 12.25 seconds, 13 seconds → 13.67 seconds(consistent across two runs), 15 seconds → 15.08 seconds. When verifying, tolerate ±1 second(the maximum observed deviation was +0.67 seconds); do not judge it as a spec mismatch just because of those few tenths of a second, and even less should you resubmit because of it.
From submission to writing to disk: 1.7 ~ 55 minutes, highly variable(five actual measurements: for the 13-second tier, 1.7 minutes and 6 minutes; for the 15-second tier, 6.8 minutes, 20.8 minutes, and55.3 minutes). Set the polling budget to 60 minutes or more—a single segment of --timeout 1800 may not be enough either; for long tasks, continue in segments (see Section 5); the officially recommended polling interval is 10 seconds.
- Most recent run (2026-09-17, 15 seconds + 768P + 4 reference images): submitted 12:14:59 → written to disk 13:10:16,55.3 minutes, file header 15.08 seconds / 1344×768 / has_audio: true, completely consistent with historical measurements for the same spec. At about 40 minutes in, there were no local files at all, and the upstream query_task still reported pending(with Request failed with status code 400），but the video was ultimately produced normally。
- Conclusion: a long duration cannot be used as a basis for determining failure or resubmitting. The only completion signal is still the file written to disk (see Section 1).
- Supplementary measurement (2026-09-17, same spec 15 seconds + 768P + 3 reference images): submitted 13:31:24 → written to disk 13:39:41,8.2 minutes, file header 15.08 seconds / 1344×768 / has_audio: true. On that day, two jobs with the same spec took 55.3 minutes and 8.2 minutes respectively, further showing that duration dispersion is extremely large (about 1.7 ~ 55 minutes);you cannot estimate this run from historical durations。
- Supplementary measurement (2026-09-17, 15 seconds + 768P + 4 reference images): submitted 14:12:29 → written to disk 14:24:11,11.7 minutes, file header 15.08 seconds / 1344×768 / has_audio: true; the generation call blocked in the foreground until completion and returned status: completed + resultFiles[].localPath，--wait --claim after binding, probe and self-reported values matched. Another job that same day with 15 seconds + 4 images took 55.3 minutes—same spec and same number of assets, 11.7 minutes and 55.3 minutes coexisting; duration dispersion does not narrow just because the spec is the same。
- Supplementary measurement (2026-09-17,11 seconds + 768P + 3 reference images): submitted 13:45:12 → written to disk 13:50:37,5.4 minutes, file header 11.54 seconds / 1344×768 / has_audio: true; this generation call blocked in the foreground until completion and returned status: completed + resultFiles[].localPath(the situation in Section 1 of "still needing --wait --claim verification"),--claim after being recorded, probe and self-reported values matched.
duration only accepts integers; decimals will be rejected.

There are two sets of standards for the minimum duration; don't conflate them: the official documentation says H3 starts at 4 seconds; on this machine, historical empirical testing has only verified that 5 secondsis usable; the 4-second tier has not been verified. When 4 seconds is needed, state it truthfully as "allowed by the documentation, unverified on this machine"; do not assert that it can definitely be done, and do not spend money probing just to verify it.

There is no automatic default value. Duration and aspect ratio are both required fields for gate one; if the user has not provided them, stop and ask. You may offer suggestions (a single shot starts at 5 seconds; multiple storyboard panels are estimated at panel count × 3–6 seconds), butsuggestions must be adopted by the user before they can be written into the parameters。

3.3 Input material limits

Model standards (H3 all-purpose reference entry):

Material	Limit	Additional conditions
Images	≤ 9 images	Single image ≤ 30 MB; JPG / JPEG / PNG / WEBP / HEIC / HEIF
Videos	≤ 3 clips	Each clip 2–15 seconds, total ≤ 15 seconds; each clip ≤ 50 MB; H.264/H.265, containing audio AAC/MP3
Audio	≤ 3 clips	Each clip 2–15 seconds, total ≤ 15 seconds; each clip ≤ 15 MB; WAV/MP3; must be paired with images or videos
Mixed total	≤ 12 files	API request body ≤ 64 MB
Image dimensions	Both width and height within [256, 5760]	Aspect ratio 5:2 ~ 2:5

Channel standards (empirically tested on this machine, stricter than the model): the miora channel applies a ≤ 4 images check to reference images; if exceeded, it returns directly

UPSTREAM_ERROR: input.reference_images must contain no more than 4 elements (10005)

This isa submission-layer validation failure; no generation task is created and no billing occurs, so you can safely resubmit.
The difference is on the channel side, not the model side: never say "the model only supports 4 images"—the official limit is ≤ 9 images, and the user will see through it as soon as they check.
When there are more than 4 images, select 4 by subject priority (protagonist / scene / key prop / main opponent), and the settings of the materials that are not selectedare downgraded into textual descriptions in the prompt, disclosed item by item at delivery.
The real criterion for making the trade-off is "difficulty of textual restoration", not copying the enumeration order above: mechanical props (vehicles, weapons, and other precision structures) and character identity depend most on reference images,keep them first; environments are easiest to carry with text (surface materials, lighting, and distant elements can all be written clearly), so they canbe discarded first. Empirical case: when 8 materials include both a motorcycle and a folding steel knife as two mechanical props, discarding the scene image to keep the two prop images is more worthwhile than giving the scene a vote.
Add one more criterion: look at how much this element appears in the storyboard and how close it is to the camera. When everything is close-up medium shots / close-ups, the environment is just background texture, so the scene image is the first to cut. Conversely, for shots with a wide long shot where the environment is the subject, the scene image deserves a slot. Likewise, if the final shot is only a distant silhouette of a monster, "character identity" still takes priority over the environment, but use a full-body three-view rather than a head close-up—head details are useless for a long shot. Tested: for a film whose four shots are all close-quarters combat, cutting the scene image and keeping the four images "protagonist / weapon / close-range opponent / distant giant beast silhouette" is the most cost-effective.
Add one more criterion: when the same character has multiple forms (costume change / transformation / early and late forms), keep only the one form that actually appears in this unit. A form switch occurswithin the same unitonly then do you need to keep both—because the process of "transforming from form A to form B" requires the model to see both the starting point and the endpoint. Conversely, if the unit is form B throughout and form A appears 0 times, then occupying a slot with A is a waste. Tested (2026-09-17): in the same character's assets there were "basic suit three-view" and "combat armor three-view"; the previous unit was the process of the armor extending from the spine to the whole body → keep both; the next unit is armor form throughout and the basic suit appears 0 times → cut the basic suit and give the slot to the opponent's head close-up (that unit has two key head-focused moments: raising the head and roaring, and a head-on penetration from behind), and the trade-off is correct.
First verify whether the "declared form" actually corresponds to the file; do not just copy the attachment path. Tested (2026-09-17): the user used @image#1 / @image#2 to declare "Lan · Basic Combat Suit" and "Lan · Combat Armor Form" respectively, but both times attachedthe same file（岚基础三视图.jpg (appears twice), while in the asset directory there exists a semantically corresponding 战斗装甲三视图.jpg(Read the image and visually confirm it is the same character's full armor form). This isattachment slippage, not the user wanting to use the same image as two forms. Handling: ① First go to the asset directory and look for files with the same or similar names according to form semantics, and use Read to visually confirm whether it is that form of the same character; ② After confirmation, replace it into the slot according to form semantics—when the slots have redundancy (number of unique assets < 4), the replacement does not crowd out any asset, so there is no need to stop and ask, but you must prominently disclose in the delivery notes "which image was used instead, why, and what the declared original path was"; ③ If the slots have no redundancy (the replacement would crowd out another asset) or no semantically matching independent file can be found, ask back; do not decide for the user. The criterion is "whether the asset the user originally wanted was crowded out," not "whether the path was touched."
To fit more assets into the 4 slots, the only feasible method isoffline reference board stitching(local PIL stitching, no regeneration, no pixel loss), for example stitching "monster full-body three-view + head close-up" into one cell. This modifies the user's assets,so you must ask the user first。

3.4 Prompts and Parameters

Prompt limit 7000 characters。
After key descriptions, you can use [运镜] instructions to guide camera scheduling—the officially recommended precision control method; paragraphs writing camera language can use it.
H3 has native audio output, and there is no parameter to turn audio off. Therefore requirements like "no music / no subtitles" can only be written into the prompt to suppress them, and at delivery you must truthfully state that this is a prompt-level constraint, not a parameter guarantee.
Dialogue (human voice): there is no line input channel. It can generate "someone is speaking," butit does not guarantee the lip-sync will match the sentence you wrote, and there is no controllable way to dub it word by word. How to handle it: when writing the lines into the prompt, explicitly mark them asperformance cues(who is speaking, what tone, where the pauses are, the mouth must open and close), and state "no subtitles, no text overlay"; do not promise that the lines will be spoken correctly.
Mix-type descriptions ("lower the ambient sound during dialogue, keep the room tone") are post-production steps, and the generation side cannot do them. Writing them into the prompt as-is is fine (it will lean in that direction), but at delivery you must make clear that this is a post-production matter, and not let the user think the generation side has already done it. When the user's script contains notes like this, it usually means they already have a post-production dubbing/mixing workflow—just submit it, and do not stop work over it.
Parameter name mapping(for interpreting upstream errors): miora's aspect_ratio = the API's ratio; miora's references maps upstream to input.reference_images; in image-to-video mode, ratio is always adaptive, and the aspect ratio is determined by the first-frame image and cannot be specified separately.

3.5 Gate Two: Duration Range — Say It First, Do Not Try First

When the duration parameter (a required item for Gate One) falls outside the legal range,do not call miora, and directly explain to the user in text that it cannot be done and give the reason.

H3's legal range is 4–15 seconds(integer). But the 4-second tier has not been verified on this machine (see 3.2), so:

If you want < 5 seconds → explain that the measured usable lower limit for this channel is 5 seconds; the documented lower limit is 4 seconds but it has not been verified on this machine,whether to try 4 seconds once is up to the user, do not decide for them, and do not spend your own money to probe.
If you want a single run > 15 seconds → explain that a single run is at most 15 seconds, and clearly state it cannot be done.

You must not proactively help the user split the prompt, and you must not submit storyboard segments in batches for generation. Whether to split is the user's decision, not your remedy: only follow it when the user explicitly asks for batching.

The same three kinds of "pretending to satisfy" that are also forbidden:

Writing the parameter as the value the user wants, hoping the model will truncate or stretch it on its own;
Quietly turning an over-limit request into multiple runs, and claiming at delivery that it was "completed";
After the fact, describing a spec mismatch as having been achieved.

Both gates come before the workflow: first pass Gate One (are all four parameters present) → then pass Gate Two (is the duration within range) → only then go to Section 4. If either fails, stop where you are and explain to the user; do not submit.

3.5.1 Upstream `context ir` error (measured 2026-09-17)

Immediately after submission, it returns status: failed，errorMessage as:

1033: system error, MiniMax-H3 context ir (status_code=2000)

Meaning and handling:

context ir refers to the official prompt enhancement step; the failure occurs in the upstream processing chain,not an illegal parameter—this time all four parameters (reference-to-video / 768P / 15s / 16:9) and all 4 reference images were legal.
First use miora_query_task to recheck, do not guess: this recheck returned the same failed, confirming it is not a pending illusion, so you can safely resubmit.
Measured: a ~2400-character Chinese prompt failed on first submission → compressed to ~1800 characters, with all other parameters and assets unchanged,resubmitted once and succeeded(15.08s / 1344×768 / with audio track, ~9.7 minutes to finalize on disk).
Causality unproven: an upstream transient glitch cannot be ruled out, so do not write it as "an overlong prompt necessarily triggers it." But compressing the prompt is a low-cost differentiated retry measure, preferable to resubmitting as-is (do not retry as-is without new evidence).
Counter data point (2026-09-17): ~ 1900 charactersof Chinese prompt + 3 reference images,passed on first submission(8.2 minutes to finalize on disk). So the 1900-character tier is a verified passable magnitude—when the user's storyboard script falls in this tier,submit it verbatim directly, no need to compress in advance; keep compression only as a differentiated measure after a first-submission failure.
A failed task produces no finished video, no resultFiles, and resubmission counts as a new generation, which must be explained to the user.

3.5.2 Submission returns `MIORA_UNAVAILABLE` / `ENOTFOUND`(measured 2026-09-17)

A submission call may return:

{"code":"MIORA_UNAVAILABLE","message":"Miora /api/ai/workbuddy-proxy/video/query-task unreachable: ENOTFOUND.","upstreamTaskId":"v89618551-..."}

Meaning and handling:

This isthe submission has been accepted but the result callback channel is broken（query-task domain DNS resolution failed),not a submission failure. The return value carries upstreamTaskId = upstream did receive the task.
Per resumeHint：do not resubmit(double billing, and the two finished videos' ownership interferes with each other). First miora_query_task review, then rely on the local on-disk wait in Section 4 to collect the result.
During review you will most likely first hit AUTH_INVALID_TEMP_KEY—just re- connect_cloud_service and fetch once more, then check again (consistent with the credential instability description in Section 1).
Measured link: submission reported ENOTFOUND → review pending → local wait produced the video normally (15.08s / 1344×768 / with audio track).On this path, "interface unreachable" never equals "generation failed."
query_task returns pending when attached Request failed with status code 400 does not change the pending conclusion, nor is it evidence that the task went wrong; no local file means no finished product, keep waiting.

3.6 Capabilities that exist officially but are not exposed on this channel

When users ask about these, truthfully say the channel has not enabled it; do not promise:

Official capability	Status on this channel
MiniMax H3 Max(480P/768P, faster generation, duration 5–15s)	There is no model selection parameter, cannot be called. When users want "faster" or "480P," explain it cannot be done
Video regeneration(take an existing 768P finished video + original `content` and rerun to produce 2K)	No corresponding tool. For 2K, the only option isdirectly with `2K` regenerate a new one, which is a new billed generation and must first be agreed to by the user
H3-Context-IR(only returns enhanced prompts, does not generate video)	No corresponding tool. Prompt enhancement is done by this skill itself in Section 6
Reference video / reference audio input	miora's reference-to-video only accepts images; there are no video or audio channels. When the user wants to drive motion with a reference video or provide reference audio, explain that the channel is not supported.
Cancel / delete the task	Once submitted, it cannot be canceled

4. Workflow

First pass two gates:Gate one (3.1): are all four required parameters present → Gate two (3.5): is the duration within range. If either one does not pass, stop and explain to the user; do not submit.

① 登记   python scripts/miora_watch.py --submit --job <作业名>
② 生成   mcp__miora__miora_*_video（tempKey + 参数）
          ↑ 返回值丢失属正常，不因此重发
②.5 认领 返回值带了 localPath → --wait --claim <localPath> --job <作业名>
          ↑ --claim 是修饰项，必须挂在一个动作上。实测 2026-09-16：单独跑 --claim 报
            "one of the arguments --submit --wait --poll --poll-all is required"
          ↑ 有绑定就用绑定；没返回就跳过，走 ③ 的扫描
③ 等待   python scripts/miora_watch.py --wait --job <作业名> --timeout 1800
④ 核验   从 ③ 的 probe 读时长/分辨率/音轨，与确认过的规格对照

Job name collisions really do happen: multiple sessions on the same machine can generate at the same time, and once the time windows overlap, "the earliest file written to disk after since" may not necessarily belong to you. This was observed once: a concurrent job was submitted at 22:42:22, this job was submitted at 22:44:49, the former's final video was written to disk at 22:49:09, and was recognized by this job's --wait as its own result; this job's actual final video was not written to disk until 22:50:46. Two lines of defense:

During script scanning,skip files already registered in other job markers（claimed_by_others), to avoid claiming artifacts someone else has already taken;
If still in doubt,use the signedUrl from the return value for fingerprint reconciliation: download it and compare md5 with the local candidate file. In practice, this method can uniquely determine ownership (the signedUrl and the local file bytes match). The signedUrl has a short validity period, so use it early; it is only for verification,do not give it to present_files。

Do not hand over a concurrent job's final video: if two videos have the same parameters and the same duration, probe alone cannot distinguish them; you can only rely on submission time + fingerprint ownership. Before ownership is determined, do not write to the canvas and do not present.

Use meaningful names for jobs (lan-15s、shot-03), not random strings. All three actions require --job, and the script will reject empty names — an empty name generates a pseudo-job named .json that pollutes the list.

It is okay if you forget to register before generation:--wait / --poll will automatically count from the time of that call and register retroactively, so the chain will not break.

③ Return code 2 means timeout,not failure, go to section 5;--wait if it is interrupted by an upper-layer timeout, switch to background running and collect the result using the task id.

How to call the script (measured on a local Windows machine): use the absolute Python path, and write the script path in Windows style.

"/c/Users/<username>/.workbuddy/binaries/python/versions/3.13.12/python.exe" "C:/Users/<username>/.workbuddy/skills/miora-video-studio/scripts/miora_watch.py" --submit --job <作业名>

Two pitfalls: ① if the script path is passed as /c/Users/... in Git Bash form, it will be incorrectly converted to c:\c\Users\...and report No such file or directory——the script path must use C:/...; ② in some sessions, Bash's ls / head / cat / which will command not found(PATH missing), sodo not pipe script output, read stdout directly, and use Glob / Read or the absolute Python path for file probing.

Two supplements (also encountered in practice):

Do not store paths in shell variables and then expand them。SK="/c/Users/.../miora_watch.py"; "$PY" "$SK" it will likewise be converted to c:\c\Users\.... Always write paths as C:/... literals, with no intermediate step.
This machine may not have curl, and may not have ffmpeg. When you need to download the signedUrl from the return value for fingerprint reconciliation, use Python urllib.request; when you need to read video header specifications, directly importlib load this script and reuse its probe(), no need to install additional tools.

5. State synchronization

Path	Command	Applicable
Same-round closed loop	`--wait`	Primary. One poll is enough to get it, the user does not need to say anything more
Explicit binding	`--wait --claim <localPath> --job <名>`	The generation call return value includes `localPath` whenrun this first, then use `--wait` to verify
Cross-round fallback	`--poll --job <名>`; for a new session use `--poll-all` to restore the scene	come back after the turn ends and the app is reopened

Return codes are semantics for the upper layer to judge:0 completed / 2 timed out (≠ failure) / 3 still generating. The job status is separate: unknown—marker missing or corrupted,cannot be determined, not equal to completed.

Background --wait interrupted (measured 2026-09-17): the --wait run in the background may be killed by session switch / app reopen, returning status: killed andno output at all, long tasks are especially likely to hit this. Handling:

run --poll once to confirm the current state;
thenhang another --wait and keep waiting——since is already registered; continuing to hang does not lose context or double-bill;
killed is not a failure, and even less a reason to resubmit.

For long tasks, recommended:hang in segments(single segment --timeout 900 ~ 1500), more resistant to interruption than hanging 1800 seconds at once.

Three hard rules for judgment(all established after hitting pitfalls, do not break them when modifying the script):

Take since the earliest appearing file after that, not the newest. When the two job time windows overlap, taking the newest will mistake the finished video of the later-submitted job for the result of the previous job—this is a false positive that really happens.
Files already claimed by another job must be excluded. Relying only on the previous rule will still collide: when the finished video of a concurrent job lands first, it will be preemptively claimed as its own result by a later job (measured once, and the two videos probe exactly the same, impossible to distinguish by specs). The script uses claimed_by_others() to implement this, do not delete it.
since once registered is never lost. Cannot determine the marker of since in all cases mark unknown and skip scanning,never fallback to 0; falling back to 0 equals scanning all historical files, and will inevitably report the previous round's old finished video as this completion.

Other reliability sources:

Size stability determination: only when two consecutive readings match is it considered finished writing, excluding half-written files from falsely reporting completion.
File header verification: parse mvhd to read duration,tkhd to read resolution, check mp4a to determine audio tracks.
Markers are fixed in the user-level directory, not drifting with the working directory, findable when changing directories or sessions.

Path: media directory ~/.workbuddy/plugins/data/mcp-miora/miora-media(can use --media-dir to override); marker file ~/.workbuddy/miora-jobs/<作业名>.json. Make the job name 项目-用途-序号(e.g. lan-15s-2) for easy distinction.

No callbacks, no reverse invocation. The only automatic path when the user is not speaking is scheduled automation—that is an exceptional measure; do not keep it resident for routine tasks.

6. Prompt construction and correction boundaries

Cases for verbatim passing: the user has already given a complete description, or indicated "just use my exact words." Do not expand or change wording; only the numbering mapping described in Section 2 may be added.

If ambiguous, complete it, and motion must be added—writing only a static image will produce a video that barely moves. State four things clearly:

What the subject is doing (a specific action, not "a person standing");
How the camera moves (push / pull / pan / follow / orbit,one shot uses only one type of movement; stacking them will cause chaos);
Light and atmosphere (key light direction, hard/soft, color temperature + atmosphere words);
End state (where the camera stops; if you do not write the ending, it easily drifts).

When writing the 2nd item for the shot, you may use the officially supported [运镜] instruction: directly follow the key description with [运镜], to guide camera scheduling; this is more stable than restating it in natural language.

Keep the total length within 7000 characters(upper limit, see 3.4). When the script the user provides is already long, prioritize preserving the subject identity description, camera movement, physical actions, and global constraints, and compress artistic wording.

6.1 Allowed automatic changes (after changing, each must be disclosed item by item in the delivery notes)

Obvious problem	Handling
Storyboard timeline overlap, out of bounds, discontinuity	Change to sequential connection and disclose
Storyboard timeline total ≠ declared duration	Use the declared duration as the standard(it is the required field for gate one), but the timelineis kept as-is, not stretched, not slowed down. If the total is shorter than declared → write the difference as "continue the ending state of the last shot, add no new actions" (tested: put a 10.5s storyboard into 13s, and for the final segment write "the giant beast continues to turn slowly, dust has not settled, the protagonist remains kneeling"); if the total is longer than declared → compress the second marks proportionally (tested: 14s compressed to 13s). In both cases, point out the conflict and the handling method in the delivery notes, and provide the option to "resubmit according to the other value."Prohibitedto fill the duration with slow motion, supplementary content, or repeated cuts.
Only static description, no motion information at all	Complete according to the four things above
Reference image role / material order not declared and `@image#N` inconsistent	Add role mapping, align to the user-visible order, and disclose
The setting segment mixes in entries that do not appear in this unit (common when using fixed templates, e.g. "this segment has three monsters fighting" actually belongs to the previous unit, or a discarded prop)	Do not delete the original text; instead, add at the promptbeginning a paragraph called "Basis for entering the frame", clarify who is and is not in this unit's frame; for those excluded, write "worldbuilding background only / not in frame." Tested: in a unit containing only the protagonist and a giant beast, the character sheet still carried over the previous unit's minor-monster entries and a discarded motorcycle; excluding them via the "basis for being in frame" section is safer and easier to disclose than deleting and revising the source text item by item.
Spelling, punctuation, obvious typos, formatting chaos	Fix directly, preserving the original meaning and wording style
Conflicts with an explicit global constraint (e.g., music is written, but "no music" is also required)	The explicit constraint takes precedence, and disclose it
Any one of mode / resolution / duration / aspect ratio is missing	Do not fill it in. This is a Gate 1 missing item; stop and ask the user for all of them at once (see 3.1)
Reference images exceed the channel limit of 4	Trim to 4 by subject priority, rewrite the settings of the excluded materials into the prompt's text description, and disclose each one at delivery (see 3.3)
`resolution` declared as `720p` / `1080p`(declared but invalid)	at the equivalent tier `768P` submit (when the user wants a higher tier, `2K`) and disclose (see 3.2)
Prompt exceeds 7000 characters	Compress to within the limit, prioritizing subject / motion / action / global constraints, and explain at delivery what was compressed out
The user requests no music / no subtitles	Write it into the prompt (H3 no-audio switch), and explain at delivery that this is a prompt-layer constraint and requires visual and auditory confirmation

6.2 Must ask back; do not decide on your own

ChangesSubject identity traits, key settings, dialogue content or tonesuch core attributes fixed by the user;
Add or remove reference materials;
Substantially change the output scale (number of items, duration tier jumps);
Passages the user explicitly said to keep "exactly as is" — only adding numbering mappings is allowed; not a single word may be changed.

If you can't tell, ask.Exception: Gate 1's four required parameters (mode / resolution / duration / aspect ratio) are not subject to "if the question is skipped, execute with defaults"— those four are submission prerequisites; if the user does not declare them, everything stays stopped, see 3.1. For the other items, when the user skips the question, execute with defaults and state so explicitly.

7. Acceptance

The artifact was actually obtained: the local path is valid, not a failure placeholder.
The measured duration / resolution matches the confirmed specs — read the probe values to check, do not restate what is written in the prompt.
The subject traits fixed by the user have not been changed; the same batch of finished videos is on the same canvas; the aspect ratio is uniform.
Do not assert "the visuals are smooth," "the camera work is on point," or "the sound effects and dialogue are correct" — these cannot be read from the file header; honestly mark them as requiring the user's visual confirmation.
Do not automatically redo failed items; whether to redo is decided by the user.

Delivery actions (canvas,present_files parameters and order) are governed by miora-creative-core .

8. Two boundaries

Cramming multiple storyboards into a single generation makes the model choose freely, and it will not cut shots strictly according to the seconds you wrote — for precise segmentation, you can only generate separately and then splice.
Strict cross-item identity consistency is not achievable. Reference images can only be approximated, and visible differences are inevitable among multiple versions. When the user has hard requirements, explain the limitations and let the user decide; do not force it and then deliver a bunch of images that do not match.