Producing with xiaoyunque

Producing with XiaoYunque

Use XiaoYunque as a second production Agent, not as a file courier and not as a replacement for Codex's judgment.

Ownership

Codex owns source truth, unknowns, creative and production decisions, asset selection, the frozen brief, spend authorization checks, complete review, retake decisions, and final selection.

XiaoYunque owns macro-planning advice, current feasibility warnings, its internal production tools, provider execution, progress, questions, and artifacts.

Codex communicates only with the XiaoYunque General Agent OpenAPI. XiaoYunque chooses and invokes media capabilities inside its own Agent run. Never bypass it with a direct media-model call.

Required reading

Before the first API call, read:

• references/collaboration-contract.md for the message envelopes and thread protocol.
• references/api-reference.md for the bundled Python API and failure semantics.

Before choosing assets, production units, or reviewing output, also read:

• references/production-judgment.md.

These are one-level references; do not search for a hidden private workflow.

Hard stops

• Read XYQ_ACCESS_KEY from the process environment. Never ask the user to paste it into chat and never place it in a message, log, source file, or receipt.
• Do not start media work without a user-owned key and a scoped authorization covering the work, production units, attempt cap, budget or submission cap, and validity window.
• A planning or handover turn is plan-only: no uploads, media creation, or media-tool use.
• A submit transport failure raises UnknownSubmitOutcome. The provider may have accepted it. Do not retry; reconcile the original operation first.
• Stay in the same thread for planning, handover, production, questions, and any justified retake. A new run is not a new production authority.
• Never overwrite an asset or result. Keep every attempt addressable and hashed.
• If Codex cannot inspect an image at usable resolution or perform full playback of an audio/video result, report that review is incomplete. Do not call it usable or final.

Core loop

1. Lock the request locally

Record the intended result, exact source material, hard constraints, output form, existing references, known provider limits, and explicit unknowns. Keep source facts separate from interpretations. Do not fill missing facts by guessing.

2. Open one plan-only collaboration thread

Send the PLAN_ONLY envelope from the collaboration contract with no assets. Ask for macro narrative/composition, visual language, space and continuity, sound where relevant, asset priorities, natural production units, execution risks, and unknowns. Explicitly prohibit media actions in this turn.

Read the returned run. Codex decides every suggestion as accepted / modified / rejected / unverified, then freezes one brief. A reply from XiaoYunque is advice, not an automatic plan freeze.

3. Prepare only result-changing control assets

Identify people, locations, objects, sound identities, or reference motion whose absence would materially destabilize the result. Inspect the real local files first. Upload only selected image, video, MP3, or WAV files. Record local SHA-256, returned asset ID, what each asset controls, and what it does not control.

Derive production units from natural meaning, continuity, and current physical limits. Do not split by an arbitrary fixed duration or equal-sized chunks.

4. Handover in the same thread

Send the HANDOVER envelope: source lock, frozen decisions, ordered asset manifest, production units, continuity, and constraints. Ask for one pre-production conflict pass and explicitly keep it plan-only. Codex absorbs only advice that would change the result and updates the single frozen brief.

5. Check the spend gate once

If the user already gave a clear authorization covering the current scope, use it; do not ask twice. Otherwise state the units, maximum attempts per unit, budget or submission limit, and expiry, then wait. Authorization opens spend; it does not prove preparation is complete.

6. Run one draw

A draw (抽卡) means one deliberate production attempt for one frozen unit through the XiaoYunque Agent.

Send the DRAW envelope in the same thread with the exact unit, ordered asset IDs, continuity in/out, frozen prompt, authorization boundary, and attempt ID. Ask XiaoYunque to perform one internal production attempt and return all results. Submit exactly once and save its thread ID, run ID, operation receipt, and message hash.

Poll that exact run. Read-only query failures may be retried with backoff; production submits may not. Preserve failure and cancellation states as returned. If XiaoYunque asks a material question, answer from frozen facts or take it to the user, then continue in the same thread.

7. Preserve and review

On success, extract every artifact URL, promptly download each one to a unique attempt path, and save its SHA-256. Review every result:

• inspect each image at usable/original resolution;
• perform full playback from 0 to the end for every audio/video result;
• check source intent, causal meaning, identity, space, action, sound, continuity, and technical integrity;
• record concrete defects and timestamps, not a general aesthetic feeling.

The first question is whether the attempt is actually usable.

8. Keep, retake, or stop

• If usable, keep it and continue. “Could be prettier” is not a retake reason.
• If one concrete blocking defect remains and authorization covers another attempt, preserve the old result and send one RETAKE envelope with one changed variable.
• If the cause is unknown, the original submit is unresolved, or the cap is exhausted, stop and report the physical state. Do not improvise another run.
• Review the retake in full; never assume the newer result is better.

9. Close with final selection

Present all preserved candidates, Codex's recommendation, rejected versions, blocking defects and timestamps, and any item that truly needs human judgment. The user makes final selection. Do not publish, move into a final pool, or discard alternatives without that decision.

Completion test

Call the work production-complete only when the frozen source and plan are traceable, authorization preceded spend, every submit is tied to a known thread/run or explicitly unresolved operation, every artifact is preserved, Codex completed the required visual/listening review, and the user made the final selection. Passing offline tests or completing plan-only does not prove a media result is production-ready.