jianying-draft-harness

JianYing Harness

Runtime contract for plugin and agent hosts. All execution goes through a unified Rust CLI handler; the CLI, MCP, and host adapters must return the same task and error semantics.

When to use

• The user explicitly requests the Jianying capability corresponding to this skill's title and accepts handling through the unified Rust jianying CLI.
• The user needs auditable planning, execution, or verification evidence, rather than just a conceptual answer.
• When requirements are not yet clear, first hand off to jianying-draft-use routing; this skill should not be used to handle other editors, general video knowledge Q&A, or speculative execution lacking necessary materials.

Capability boundaries

• ✅ Can do: Generate deterministic plans based on real paths and probe results; when capability is supported , execute operations in this domain; output the evidence level actually achieved.
• ⚠️ Requires conditions: Writes must use an isolated copy; costs, external services, and native application actions must have precise approval; playback or export conclusions must have corresponding runtime evidence.
• ❌ Out of scope: Does not automatically install or upgrade the CLI, does not generate Python draft scripts, does not call external headless checkout, does not overwrite source drafts, and does not fabricate resource IDs, media facts, or success states.

Step 1 — Establish a factual baseline

Record the user's goal, absolute paths, host platform, target deliverables, and allowed side effects; when information is insufficient, first provide a read-only diagnostic plan and list the missing facts item by item.

Step 2 — Handshake capabilities

Run version, doctor, and capabilities checks. A satisfied version does not mean the capability is available;partial、external_dependency or a missing state must enter the degraded path.

Step 3 — Validate inputs

Probe media, drafts, configuration, or task state; reject nonexistent paths, out-of-range times, unknown schemas, mismatched hashes, and approvals that cannot be bound to a target.

Step 4 — Form a deterministic plan

Write the operations, parameters, output paths, risk levels, confirmation points, and expected evidence into the plan. Order multiple tasks as "read-only facts → reversible writes → external/native actions".

Step 5 — Execute or stop before the gate

Execute only steps that are supported and authorized. When output is ambiguous, times out, or partially succeeds, retain the task ID, audit log, and artifacts; do not automatically retry.

Step 6 — Verify and deliver

Run structural validation, then append cold-reopen, playback, or native export evidence according to the target; report the actual level, failed fields, recoverable actions, and unverified items.

Rules

• Material durations, dimensions, streams, hashes, and draft versions in the plan must come from tool output.
• Approval must be bound to the command, parameters, target, validity period, and budget; if any field changes, reconfirm.
• User data is processed only within local target paths and the declared external Provider boundary; unrelated credentials must not be collected, uploaded, or logged.
• When current evidence is insufficient, use UNVERIFIED、BLOCKED or AMBIGUOUS; it is forbidden to fill in results by inference.

Gotchas

1. Treating version as capability: Always check the specific capability; do not execute directly just because the CLI version is new enough.
2. Treating structural validation as final acceptance: project verify It only proves the structural layer; playback and native export require independent evidence.
3. Directly modifying the source draft: First create an isolated copy and record the input hash. Any in-place overwrite request must be stopped and changed to a new output.
4. Automatic retry for ambiguous: First query the task, audit, and external artifacts. Only after confirming that no side effects occurred can the user approve a retry.
5. Filling in resources or time from memory: Resource IDs come from the catalog, and times come from probe/ASR/project data; if they cannot be obtained, explicitly block.
6. Vaguely asking for more information: First provide an executable read-only plan, then explicitly list the gaps such as paths, delivery level, or authorization.

Verification checklist

• CLI identity, version, and capability have been recorded.
• All input paths, media facts, and hashes are reviewable.
• The write target is isolated from the source draft, and the confirmation point is precisely bound.
• Failure and ambiguous paths retain the task ID, logs, and recovery suggestions.
• The final wording is consistent with the actual evidence level.

Runtime contract

• Trigger conditions: the user needs persistent tasks, approvals, configuration, MCP, host integration, cancellation/retry, or audit capabilities.
• Required capability:job.lifecycle、approvals、config、mcp.serve、mcp.job_lifecycle。
• Minimum CLI version:1.6.0; verify the actual manifest before running.
• Default risk:high_risk_write; read-only list/show/audit can be downgraded to read_only.
• Input facts: Job file, CLI/runtime identity, cwd/target, profile, task ID, required transport, and host constraints.
• Confirmation point: the approval record must be precisely bound to the command, arguments, cwd/target, task, validity period, and budget; re-approve after any field changes.
• Success evidence:structural; even if the task succeeded, cold reopen, playback, or native export evidence must still be added according to the delivery goal.
• Prohibited actions: do not generate Python draft scripts, do not call external headless checkout, and do not bypass the Runtime Adapter, reuse mismatched approvals, or silently resubmit ambiguous operations.

Runtime flow

1. Complete the version/schema/capability handshake.
2. Compile the deterministic jianying-job/v2 and save the input summary and asset hashes.
3. Create precise approvals for risky operations; read-only commands do not create approvals.
4. Use jianying job run --json、job batch or job serve; record the CLI task ID.
5. Via job show、job audit、job cancel、job retry manage the lifecycle.
6. MCP uses the official protocol implementation of stdio, Streamable HTTP, or SSE; remote listening must verify the token, Host, and Origin, and via jianying_job_list/show/cancel/retry/audit manage persistent business tasks.

When screen recording, interaction events, smart zoom, Web VFX, media normalization, exposure analysis, or native asset discovery enter the task, first load Auxiliary Provider boundary. Providers can only create assets, ledgers, or evaluations; draft writing is still performed by the locked-release Rust CLI.

For lifecycle, approval, and transport gates, see references/workflow.md. When writing or reviewing a Job, load jianying-job/v2 field manual, and do not reuse old headless plans, private wire fields, or operations not proven by capability. For a minimal Job, see examples/minimal-job.json。

Progressive materials

• On first execution, first load normal path to obtain the end-to-end sequence.
• When encountering failure or an unknown state, load Failure Recovery and Error Recovery Table。
• Load when the user requests privilege escalation, override, or automatic retry Boundary Rejection。
• Complete each item before delivery Verification Checklist, and do not claim completion based only on a plan or the existence of files.