Add Skill workflow runtime handoffs

.github/workflows/ci.yml

@@ -38,8 +38,15 @@ jobs:
           python -m aigc_director_kit validate-plan examples/one_take_previs_case.json --json
           python -m aigc_director_kit validate-plan examples/film_contract_handoff_case.json --json
           python -m aigc_director_kit validate-plan examples/multi_actor_prop_case.json --json
-          python -m aigc_director_kit list-actions --library examples/action_library.json --query 跑
-          python -m aigc_director_kit compile-action --library examples/action_library.json --text "快速跑步然后急停，过渡0.2秒，原地"
+          python -m aigc_director_kit list-actions --library examples/action_library.json --query run
+          python -m aigc_director_kit compile-action --library examples/action_library.json --text "run quick stop, blend 0.2s, fast, in place"
+
+      - name: Validate workflow, prompt, and QC contracts
+        run: |
+          python -m aigc_director_kit validate-workflow examples/skill_workflow_case.json --library examples/action_library.json --json
+          python -m aigc_director_kit validate-prompt-pack examples/prompt_pack_case.json --plan examples/one_take_previs_case.json --json
+          python -m aigc_director_kit validate-qc-report examples/qc_report_unverified_case.json --json
+          python -m aigc_director_kit build-runtime-handoff examples/skill_workflow_case.json --library examples/action_library.json --adapter optional-runtime-adapter --json
 
       - name: Check source and JSON files
         run: |

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+- Added the `aigc-director-skill-workflow` handoff contract and schema.
+- Added `validate-workflow` for structural validation and deterministic action dry-runs.
+- Added a sanitized multi-Skill workflow example, documentation, and regression tests.
+- Added `aigc-director-prompt-pack` validation for global rules and shot-specific prompt deltas.
+- Added `aigc-director-qc-report` validation that separates observed evidence from unverified claims.
+- Added `aigc-director-runtime-handoff` and `build-runtime-handoff` for optional adapter consumption.
+- Improved the Windows example runner with an explicit Python override and common install-path fallback.
+
 ## [0.1.4] - 2026-08-12
 
 - Added two sanitized cases derived from real local previs forward tests.

README.md

@@ -1,5 +1,53 @@
 # AIGC Director Kit
 
+## Skill workflow handoff
+
+Local AIGC Skills can hand a sanitized workflow packet to this repository:
+
+```text
+Skill output -> skill-workflow JSON -> validate-workflow -> optional runtime adapter
+```
+
+The public contract is documented in [`docs/skill-workflow-integration.md`](docs/skill-workflow-integration.md),
+with a runnable example at [`examples/skill_workflow_case.json`](examples/skill_workflow_case.json):
+
+```powershell
+python -m aigc_director_kit validate-workflow `
+  examples/skill_workflow_case.json `
+  --library examples/action_library.json
+```
+
+This is a deterministic handoff and dry-run boundary. It does not bundle
+private Skills, Blender, FFmpeg, model accounts, paid generation, or final
+video QC.
+
+To create one packet for an optional runtime adapter:
+
+```powershell
+python -m aigc_director_kit build-runtime-handoff `
+  examples/skill_workflow_case.json `
+  --library examples/action_library.json `
+  --adapter blender-previs `
+  --json
+```
+
+The packet is always a dry-run handoff: it does not launch Blender or render
+media, and it keeps render/QC evidence separate from contract validation.
+
+Prompt packs and QC evidence use separate contracts:
+
+```powershell
+python -m aigc_director_kit validate-prompt-pack `
+  examples/prompt_pack_case.json `
+  --plan examples/one_take_previs_case.json
+
+python -m aigc_director_kit validate-qc-report examples/qc_report_unverified_case.json
+```
+
+Prompt validation does not generate an image or video. QC validation does not
+open or interpret media; a `pass` or `fail` result requires explicitly marked
+observed evidence from an available artifact.
+
 [![CI](https://github.com/cyou1314/aigc-director-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/cyou1314/aigc-director-kit/actions/workflows/ci.yml)
 
 面向 AI 动画、AI 漫剧和分镜预演的轻量合同工具包：把镜头任务、相机路径、入/出镜状态和动作选择写成可验证、可复现的 JSON。

docs/roadmap.md

@@ -1,5 +1,18 @@
 # Roadmap
 
+## v0.2 implementation status
+
+- [x] Workflow, prompt-pack, and QC evidence contracts are available as
+  standard-library-only validators.
+- [x] A runtime adapter dry-run handoff can combine the validated plan and
+  compiled action requests without launching Blender.
+- [x] The Windows example launcher accepts `AIGC_DIRECTOR_PYTHON` and checks
+  common Python install locations.
+- [ ] Add an optional Blender adapter that consumes the handoff and records
+  real previs evidence.
+- [ ] Add field-level error codes and keep the JSON output stable across
+  releases.
+
 ## v0.1 — 当前范围
 
 - [x] 镜头计划合同和确定性校验
@@ -8,10 +21,10 @@
 - [x] 中文/英文动作请求编译
 - [x] 无第三方运行时依赖
 
-## v0.2 — 需要真实用户反馈后再做
+## v0.2 — 部分完成，等待真实运行时反馈
 
-- [ ] 可选 Blender 适配器，不把 Blender 加入核心依赖
-- [ ] 计划到运行时的 dry-run 报告
+- [x] 可选运行时 dry-run 交接包，不把 Blender 加入核心依赖
+- [ ] 可选 Blender 适配器，消费交接包并记录真实预演证据
 - [ ] 更明确的字段级错误码和 JSON 输出稳定性
 
 ## v0.3 — 暂不承诺

docs/skill-workflow-integration.md

@@ -0,0 +1,124 @@
+# Skill workflow integration
+
+This repository is the deterministic public core for a larger AIGC workflow.
+It does not bundle Codex skills, private assets, Blender files, model accounts,
+or paid generation services. A local workflow can produce a public handoff,
+then this package validates the handoff and compiles bounded action requests.
+
+## Boundary
+
+```text
+local Skill workflow
+  -> aigc-director-skill-workflow JSON
+  -> validate-workflow
+  -> validate-plan + compile-action
+  -> prompt-pack JSON + qc-report JSON
+  -> optional Blender / FFmpeg / runtime adapter
+  -> separately recorded render or QC evidence
+```
+
+`validate-workflow` does not run an external Skill, render a scene, call a
+model, inspect a video, or prove final visual quality. It only checks the
+public contract and, when an action catalog is supplied, performs a dry-run
+against known action descriptors.
+
+## Skill-to-contract mapping
+
+| Workflow responsibility | Public handoff | Boundary |
+| --- | --- | --- |
+| Story or visual direction | `shot_plan` | The plan is a designed or observed contract, not a rendered result. |
+| Audio, pacing, or action intent | `action_requests[]` | Only catalog actions can be selected; unknown actions fail. |
+| Project coordination | `stages[]` and `handoff` | Stage names are labels, not runtime dependencies. |
+| Prompt writing and revision | `aigc-director-prompt-pack` | Global rules are written once; each shot carries only its delta and contract. |
+| Blender previs | Optional runtime adapter | Blender is not a core dependency. |
+| FFmpeg preprocessing | External evidence step | Original media remains outside this public repository. |
+| Video QC | `aigc-director-qc-report` | Pass/fail requires observed evidence from an available artifact. |
+
+The example uses `aigc-manga-video-director`, `audio-to-prompt`, and
+`aigc-project-prompt-loop` as illustrative stage labels. They are not bundled
+with this Python package and can be replaced by another workflow producer.
+
+## Run the public handoff
+
+Without an action catalog, the workflow is checked structurally and action
+requests receive an explicit not-compiled warning:
+
+```powershell
+python -m aigc_director_kit validate-workflow examples/skill_workflow_case.json
+```
+
+With the descriptor-only catalog, the action bridge is compiled deterministically:
+
+```powershell
+python -m aigc_director_kit validate-workflow `
+  examples/skill_workflow_case.json `
+  --library examples/action_library.json
+```
+
+For machine-readable output, add `--json`. The output is a validation and
+dry-run report; a runtime adapter still has to map action ids to real assets.
+
+## Build a runtime adapter handoff
+
+When the next tool needs one packet containing the validated shot plan, prompt
+pack, compiled action requests, and evidence boundary, build a runtime
+handoff:
+
+```powershell
+python -m aigc_director_kit build-runtime-handoff `
+  examples/skill_workflow_case.json `
+  --library examples/action_library.json `
+  --adapter blender-previs `
+  --json
+```
+
+This command creates a `aigc-director-runtime-handoff` packet in `dry-run`
+mode. `runtime.executed` stays `false`, `render_status` stays `not_run`, and
+the packet does not launch Blender, resolve motion files, render media, or
+claim QC. An adapter may consume the packet and must record its own runtime
+and media evidence separately.
+
+## Prompt and QC contracts
+
+The prompt-pack contract keeps reusable character, scene, style, stability,
+and avoid rules in `global_rules`. Each shot must retain a primary task,
+action causality, camera job, entry state, exit state, duration, and complete
+prompt text. When a source shot plan is supplied, ids are cross-checked and a
+duration drift is reported as a warning.
+
+The QC contract is deliberately stricter than a prompt check. A report may be
+`unverified` or `not_run` when no render is available. A `pass` or `fail`
+check must use `observed` evidence and an available artifact. This keeps a
+contract audit, a dry-run, and actual video QC as separate evidence layers.
+
+Both layers can also be embedded in the workflow packet as optional
+`prompt_pack` and `qc_report` fields. When present, `validate-workflow` checks
+them against the embedded shot plan and exposes their status in the summary.
+
+```powershell
+python -m aigc_director_kit validate-prompt-pack `
+  examples/prompt_pack_case.json `
+  --plan examples/one_take_previs_case.json
+
+python -m aigc_director_kit validate-qc-report `
+  examples/qc_report_unverified_case.json
+```
+
+## Adding a new workflow producer
+
+1. Emit a sanitized `aigc-director-skill-workflow` document.
+2. Put the producer name, role, output contract, and evidence status in a
+   `stages[]` entry.
+3. Embed a versioned `aigc-director-shot-plan` in `shot_plan`.
+4. Put natural-language action intent in `action_requests[]` with a shot and
+   stage reference.
+5. Run `validate-workflow --library ...` before handing the packet to an
+   optional runtime adapter.
+6. Run `build-runtime-handoff ... --adapter ...` when the next runtime needs a
+   single dry-run packet.
+7. Add a public example and a regression test when the contract changes.
+
+Keep private source paths, credentials, cookies, private character assets,
+unlicensed motion data, and generated media out of the packet. Mark inferred
+intent and unverified render/QC claims explicitly instead of presenting them
+as observed community or production evidence.

examples/prompt_pack_case.json

@@ -0,0 +1,37 @@
+{
+  "contract": "aigc-director-prompt-pack",
+  "version": 1,
+  "project": "sanitized-one-take-previs",
+  "global_rules": {
+    "character_anchors": [
+      "Keep the hero identity, silhouette, wardrobe, and prop state unchanged."
+    ],
+    "scene_anchors": [
+      "Preserve the platform axis and the forward-facing spatial relationship."
+    ],
+    "style": "Clean low-poly previs with readable staging and restrained detail.",
+    "stability": [
+      "Preserve the first-frame composition and the settled outgoing state."
+    ],
+    "avoid": [
+      "Do not invent dialogue, extra choreography, or an unverified final-render claim."
+    ]
+  },
+  "shots": [
+    {
+      "shot_id": "S01",
+      "source_shot_id": "S01",
+      "duration_s": 4.0,
+      "primary_task": "Establish the space and compress attention onto the hero's decision.",
+      "action_causality": "The hero moves forward from the established space and settles on the platform axis.",
+      "camera_job": "Dolly from spatial context toward the hero while keeping the endpoint readable.",
+      "entry_state": {"actors": ["hero"], "movement": "forward"},
+      "exit_state": {"actors": ["hero"], "movement": "settled-forward", "screen_position": "near-center"},
+      "prompt": "One continuous 4-second previs take. Establish the platform and the hero in space, dolly steadily toward the hero as attention compresses onto the forward decision, then settle with the hero near frame center on the platform axis. Preserve identity, silhouette, wardrobe, prop state, screen direction, and the readable outgoing endpoint. No dialogue, extra choreography, or invented camera movement.",
+      "evidence": "designed",
+      "revision_notes": [
+        "Keep one primary action and one dominant camera job."
+      ]
+    }
+  ]
+}

examples/qc_report_unverified_case.json

@@ -0,0 +1,35 @@
+{
+  "contract": "aigc-director-qc-report",
+  "version": 1,
+  "project": "sanitized-one-take-previs",
+  "artifact": {
+    "label": "No rendered video supplied; contract-only example",
+    "available": false
+  },
+  "overall_status": "unverified",
+  "source_shot_ids": ["S01"],
+  "checks": [
+    {
+      "id": "shot-contract",
+      "status": "not_run",
+      "evidence": "designed",
+      "notes": "The shot contract can be validated separately, but no render was inspected."
+    },
+    {
+      "id": "continuity",
+      "status": "unverified",
+      "evidence": "inferred",
+      "notes": "Continuity remains unverified until an actual clip and its tail frame are reviewed."
+    },
+    {
+      "id": "lip-sync",
+      "status": "not_run",
+      "evidence": "designed",
+      "notes": "No dialogue or audio evidence is present in this example."
+    }
+  ],
+  "limitations": [
+    "This report does not inspect a video, audio track, or rendered frame.",
+    "Contract validation is not final visual or audio quality approval."
+  ]
+}