aitoearn-dsh-plugin-test 0.0.2 → 0.0.4

package/skills/cloudedit/references/edit-text.md

@@ -0,0 +1,227 @@
+# Text
+
+Text editing includes content, position, size, style, orientation, and animation. Treat the MCP contract
+below as hard input and readback requirements. Treat the later editorial guidance as quality guidance that
+the MCP does not necessarily enforce.
+
+## MCP Text Contract
+
+### Field Placement
+
+Place `content`, `offset_x`, and `offset_y` at the root of each text Add or Update item. Apply the same
+rule to `shared.add` and `shared.update`. Do not place these fields inside `text_style`; `text_style`
+only carries typography, appearance, orientation, text-box alignment, and text animation.
+
+`content` accepts at most 10,000 characters. `offset_x` and `offset_y` must be integers. These fields
+apply only to text elements.
+
+### Adding Text
+
+Every text Add must provide both `horizon` and `vertical`. Use `left`, `center`, or `right` for
+`horizon`, and `top`, `center`, or `bottom` for `vertical`. Text does not support `pos_x` or `pos_y`.
+
+Do not provide `width` or `height` when adding text. New horizontal text uses 80% of the canvas width
+and derives its height from the rendered content. New vertical text uses 80% of the canvas height and
+derives its width from the rendered content. Always provide meaningful `content`; otherwise the editor's
+placeholder text may remain.
+
+Use concrete values in tool calls rather than enum-like expressions such as `"center" | "left"`.
+For example:
+
+```json
+{
+  "adds": [
+    {
+      "type": "text",
+      "from_time_ms": 0,
+      "duration_ms": 3000,
+      "horizon": "center",
+      "vertical": "bottom",
+      "content": "Hello World",
+      "offset_y": -100,
+      "text_style": {
+        "font_size": 40,
+        "text_align": "center"
+      }
+    }
+  ]
+}
+```
+
+Omit `track_id` to use automatic track selection. Provide an existing compatible text-track ID only when
+the text must be placed on that specific track.
+
+### Updating Text Size
+
+For existing horizontal text, only `width` may be updated; do not provide `height`. For existing vertical
+text, only `height` may be updated; do not provide `width`. Use `font_size` to change glyph size.
+
+`font_size` must be an integer from 1 to 1000 and uses the same pixel coordinate scale as the canvas.
+
+### Text Orientation and Alignment
+
+Use `text_style.text_align` for horizontal text, with `left`, `center`, or `right`. Use
+`text_style.alignment` for vertical text, with `top`, `center`, or `bottom`. Do not provide both fields
+in the same item. Setting either field also selects the corresponding horizontal or vertical orientation.
+
+For horizontal text, `\n` starts a new row. For vertical text, `\n` starts a new column.
+
+### Text Positioning
+
+Use `horizon` and `vertical` for semantic nine-grid placement. Reserve root-level `offset_x` and `offset_y`
+for fine adjustment and collision avoidance. A positive `offset_x` moves text right, and a negative value
+moves it left. A positive `offset_y` moves text down, and a negative value moves it up.
+
+The MCP keeps text within a 10-pixel safe inset on every canvas edge. Offsets are clamped to that safe
+area. If the rendered text itself is larger than the available safe area, the entire edit batch is rejected.
+Reduce the font size, shorten the content, or, when updating existing text, adjust the supported fixed axis.
+
+### Text Style
+
+`text_style` supports `text_res`, `font_type`, `font_size`, `font_color`, `bold`, `italic`, `underline`,
+`background_color`, `background_border_size`, `border`, `text_align`, `alignment`, and `text_animation`.
+
+Use the editor's `#RRGGBBAA` format for colors. `background_border_size` must be a non-negative integer
+in canvas pixels and expands the background equally on all four sides. A value of `0` keeps the background
+at the rendered text bounds.
+
+Use `list_resources` to obtain `font_type` and `text_res` IDs. The default font is `思源黑体 Bold`.
+The public MCP contract does not expose text shadows, rich-text spans, or multiple colors inside one text
+element. When individual words require different styles, use separate text elements and position them
+explicitly.
+
+### Text Animation Contract
+
+`text_style.text_animation` may contain `in`, `out`, and `loop`, and must contain at least one stage.
+Each stage must provide both `resource_id` and an integer `duration_ms` of at least 100 milliseconds.
+
+Use `list_resources` to obtain the matching resource category:
+
+- `in`: `enter_animation`
+- `out`: `out_animation`
+- `loop`: `loop_animation`
+
+The MCP validates the animation structure and minimum stage duration. It does not verify that the combined
+animation duration leaves enough time to read the text.
+
+### Shared Text Defaults
+
+In `shared.add` and `shared.update`, keep `content`, `offset_x`, and `offset_y` at the template root and
+place styling fields inside `text_style`. Each shared template must declare `type: "text"`. An individual
+Add or Update item overrides the corresponding shared value; nested style objects are merged.
+
+### Verification
+
+After adding or updating text, call `inspect_elements` for the affected element IDs. Read `content`,
+`offset_x`, and `offset_y` from the element root. Read typography, appearance, orientation, alignment, and
+animation from `text_style`.
+
+Text inspection does not expose `pos_x` or `pos_y`. Use `horizon`, `vertical`, `offset_x`, and `offset_y`
+as the public positioning contract. Read back the final values instead of treating a successful write as
+proof that the requested layout was preserved.
+
+## Editorial Guidance
+
+### Text Size
+
+Derive a visually appropriate integer `font_size` from the canvas. For ordinary subtitles, start around
+3.75% of the long edge. As editorial guidance, text intended for normal viewing should generally remain
+between 1.5% and 12% of the long edge, depending on its role and viewing context.
+
+Recommended proportions for common text types, using a canvas long edge of 1920:
+
+| Text type | Recommended long-edge ratio | Default | At 1920 long edge |
+|---|---:|---:|---:|
+| Standard film/documentary subtitles | 3.5%–4.2% | 3.75% | 72 |
+| Landscape talking-head subtitles | 3.8%–4.5% | 4.1% | 79 |
+| Portrait mobile subtitles | 4.2%–5.0% | 4.5% | 86 |
+| Emphasis subtitles for short video | 4.8%–6.0% | 5.4% | 104 |
+| Large opening hook | 6%–9% | 7.5% | 144 |
+| Main video title | 5.5%–8% | 6.5% | 125 |
+| Chapter/transition title | 4%–5.5% | 4.5% | 86 |
+| Quote/key point | 3.8%–5.5% | 4.5% | 86 |
+| Informational text | 2.6%–3.6% | 3% | 58 |
+| Lower-third primary name | 2.5%–3.2% | 2.8% | 54 |
+| Lower-third role/description | 1.8%–2.4% | 2.1% | 40 |
+| Label/corner badge | 2%–2.8% | 2.4% | 46 |
+| CTA text | 3.2%–4.5% | 3.8% | 73 |
+| Price/data/countdown | 7%–12% | 9% | 173 |
+| Watermark/account | 1.2%–1.8% | 1.5% | 29 |
+| Source/note | 1.5%–2.2% | 1.8% | 35 |
+| Disclaimer | 1.8%–2.5% | 2.1% | 40 |
+| End-card title | 6%–9% | 7% | 134 |
+| End-card description | 2.8%–3.8% | 3.2% | 61 |
+| Credits | 2.2%–3.2% | 2.6% | 50 |
+
+### Text Style
+
+Basic text styling includes font, decorative text, color, bold, italic, underline, background, and border.
+Decorative text is generally suitable for short titles, but not recommended for subtitles, body text, or
+explanatory text. Bold and underline are for emphasis. Unless the request or visual context calls for them,
+prefer the default font and avoid unnecessary decorative text, bold, italic, or underline styling.
+
+### Text Animation
+
+The following timing rules are editorial quality guidance, not MCP validation rules. Keep the combined
+entrance and exit duration within the text display duration, and keep a loop cycle within that duration.
+Leave enough stable display time after the entrance animation for the viewer to read the text. As a starting
+point, keep stable reading time at least 1.5 times the entrance-animation duration.
+
+### Scene-Aware Text
+
+Determine the role of the text before choosing its position and style. Subtitles make dialogue readable,
+informational text identifies people, places, or steps, and display titles create mood and memorable
+moments. Do not use all three to repeat the same information. Leave the frame free of text when the
+visuals already communicate the intended message.
+
+#### Position
+
+- Place dialogue subtitles at the bottom center by default and limit them to two lines. In landscape video,
+  keep the bottom of the text about 6%–10% above the bottom edge of the canvas.
+- For portrait video on short-form platforms, move subtitles into the lower-middle region to avoid controls
+  on the right and titles or progress indicators at the bottom. Inspect representative frames to ensure the
+  text does not cover important gestures, people, or objects.
+- Use a lower-left or lower-right information block for names and roles. Place locations, chapter titles,
+  and opening keywords in the center or in negative space beside the subject.
+- Keep labels near the person, product, or action they describe, but never cover faces, important actions,
+  product details, or existing on-screen text.
+- Use the nine-grid values to express semantic placement. Reserve `offset_x` and `offset_y` for collision
+  avoidance and fine adjustment. The MCP's 10 px inset prevents overflow; it is not a recommended visual
+  margin.
+
+#### Color
+
+- Use white or near-white for ordinary subtitles. Add a dark stroke or translucent background when
+  needed to preserve readability across both bright and dark shots.
+- `text_style.background_color` uses a `#RRGGBBAA` color string. `text_style.background_border_size`
+  uses a non-negative integer in Canvas pixels to expand the background equally on all four sides of
+  the text; `0` makes the background fit the text's rendered bounds.
+- Use color only when it carries meaning, such as identifying a keyword, number, product name, brand,
+  correct or incorrect state, or speaker. Because one text element has one `font_color`, split words that
+  require distinct colors into separate text elements and position them explicitly.
+- Keep one primary accent color throughout a video and add at most one status color when necessary. The same
+  color should always communicate the same meaning, so decorative color does not compete with information.
+- Color does not replace contrast. If colored text blends into the footage, add a stroke or background, or
+  move the text to a clearer region.
+
+#### Decorative Text
+
+- Use decorative text for opening titles, location reveals, chapter cards, brand slogans, festive moments,
+  and a small number of key quotes. Keep it brief; Chinese display text should usually contain 2–8 characters.
+- Use a clear standard typeface for dialogue subtitles, explanatory body text, instructions, specifications,
+  prices, and disclaimers.
+- Match the typeface, texture, and animation to the video's tone, and keep the treatment consistent throughout
+  the video. Do not add decorative text merely because a resource is available.
+- Reduce decoration, or switch to standard text on a background panel, when the footage is visually busy,
+  moves quickly, or requires the viewer to follow an important action.
+
+#### Common Choices
+
+| Scenario | Position | Color and style |
+| --- | --- | --- |
+| Film or documentary dialogue | Bottom center | White standard typeface with a dark stroke or translucent background; no decorative text |
+| Talking-head or educational short | Lower-middle region | White body text with a small number of keywords in one accent color |
+| Vlog or cinematic location reveal | Center or negative space | Larger type in white, a theme color, or context-appropriate decorative text |
+| Person's name and role | Lower left or lower right | Larger name and smaller role; reserve brand color for a small label or bar |
+| Promotional benefit, price, or slogan | Center or beside the subject | One key message per shot; use a brand or high-contrast color; short phrases may use decorative text |
+| Tutorial annotation or product callout | Near the referenced object | Give colors consistent category meanings; add an arrow or background when needed |

package/skills/cloudedit/references/edit-timeline.md

@@ -0,0 +1,29 @@
+## Timeline
+
+The timeline displays media playback order and ranges along linear time, while its Z-axis track stacking represents masking relationships.
+
+- **Never predict the post-operation timeline from descriptions of how transitions, speed changes, `absorb`, or similar operations affect it. Operate only on the logical timeline returned by `preview_timeline`. Elements on the same logical track must not overlap.**
+
+## Track Types
+
+A track must contain elements. When `edit_element` does not receive a `track_id`, it automatically finds the nearest suitable track by default. Use `create_new_track=true` to force creation of a new track.
+
+The track with `order=0` is the “main track.” Only a video track can be the main track. The main track supports transitions; other tracks do not.
+
+## Track Order
+
+A well-formed track order ensures correct video stacking and masking relationships.
+
+Track order is read from the highest numeric `order` down to `order=0`. By default, track types in that direction must be arranged as audio → effect → text → video. Therefore, whenever the timeline contains video tracks, `order=0` must remain a video track and serves as the main track.
+Tracks of the same type must remain contiguous and must not be interleaved with other track types.
+Change this default grouping only when the task explicitly specifies a special layer stack, mask, or parent-child relationship. When changing it, prioritize the requested rendering and masking relationship without moving a non-video track to `order=0`.
+
+## Timeline Alignment
+
+When aligning different tracks, an element’s `target_time` semantically represents the time at which it is displayed. **`preview_timeline` is the sole time reference for alignment. Never calculate the structural effects of transitions, speed changes, `absorb`, or similar operations to align elements.**
+
+## Edit Receipts
+
+The `adds`, `deletes`, and `updates` fields returned by `edit_element` report only explicit operations. Added items include their final track and millisecond timing.
+For updated items, `updated` contains the fields actually processed. Confirm indirect movements and automatic transition maintenance by reading the timeline back.
+Obtain a new track ID from `adds[].track_id` or `updates[].updated.track_id`. For validation-only operations, `warnings` marks the changes as uncommitted, and IDs generated during validation cannot be reused.

package/skills/cloudedit-planner/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: cloudedit-planner
+description: Turn editing intent and video, audio, or image sources into an evidence-backed, executable CloudEdit plan. Use whenever an edit needs decisions about selection, story, ordering, pacing, sound, composition, or necessary media processing, even when the user simply says to make a video. Understand intent, obtain sufficient content and timing evidence, prepare needed assets, and hand the concrete plan to cloudedit for requested project production. Plan-only requests stop at the plan. Exact mechanical edits, import-only, export-only, and isolated parameter changes can use cloudedit directly.
+requiredTools:
+  - get_media_metadata
+---
+
+# From Editing Intent to an Executable Project Plan
+
+Own the editorial decisions from the request through a plan that another editor can implement without guessing content, sources, timing, or treatments. Use tools to resolve real evidence gaps and prepare necessary materials. The only skill dependency is [cloudedit](../cloudedit/SKILL.md), which owns project operations and remains independently usable. All understanding and planning guidance below belongs to this skill.
+
+## 1. Establish the Intended Result
+
+Reuse the conversation and project context. Identify what the audience should understand or experience, the intended use, and the deliverable: one sequence, independent cuts, or alternative versions. Separate binding requirements from preferences and choices left to editorial judgment. Preserve exact supplied ranges, order, duration bounds, aspect ratio, required/excluded content, sound, and text requirements.
+
+Determine whether the user wants analysis, a plan, or production. Analysis and plan-only requests do not authorize project writes. For production, continue through cloudedit and its verification; do not stop at a proposal when execution is already authorized. Export only on request.
+
+Ask only about gaps that materially change the result and cannot be resolved from sources or project state: conflicting mandatory duration and content, an ambiguous target project, or an unspecified deliverable that changes selection. State reasonable minor assumptions and continue independent work. Do not require a questionnaire or another approval after direction or end-to-end execution is established.
+
+For existing projects, use cloudedit's reading rules to identify materials, affected clips/tracks, and neighboring boundaries. Check the material pool before asking for a missing upload. Preserve unrelated content and account for synchronized downstream elements in structural revisions.
+
+## 2. Inventory Sources and Define Evidence Needs
+
+Keep a lightweight record of source identity/access, media type, usable technical properties, existing content evidence and coverage, and remaining gaps. Distinguish originals from derivatives. IDs come from actual results; filenames are hints, not facts about content, chronology, or emotion.
+
+Include standalone audio and images as well as video and its audio. Import success or metadata establishes no subjects, readable text, dialogue, musical mood, beats, or sound events. Reuse adequate source-linked results and specific user-provided facts rather than analyzing everything again.
+
+Before choosing tools, separate what the material shows or says from the technical numbers a tool parameter needs. For every source used in a content decision, use what you already see or hear in this conversation, or say which file you have not seen. A metadata result does not answer a content question. Do not treat an image as a logo, overlay, cover, or decoration from its filename; that role also needs the picture. No further content pass is needed when the task is purely technical or the user's exact instructions and existing evidence leave no content decision unresolved.
+
+If the user requests analysis of all supplied materials, inventory every file and obtain adequate understanding for each before claiming complete analysis or deciding it is irrelevant. Mark pending/unavailable files individually. Otherwise scope analysis to decisions: broad candidate coverage for selection, affected ranges and continuity boundaries for local edits, and no new semantic analysis for fully specified mechanical operations.
+
+Turn the intent into questions about the material: what deserves attention, what the audience needs to understand it, which relationships are supported, and what visual or audible details determine a usable cut. Consult [Media Evidence Models](references/media-evidence-models.md) only for questions that need more precision. Choose evidence by the decision it supports, without classifying the task into a scenario or assigning a preset sequence.
+
+Treat labels such as “Vlog,” “cinematic,” or “highlights” as clues to clarify through the rest of the request and actual content. The same sources may support very different edits. Neither a label nor an available tool determines what the finished piece should say or how it should unfold.
+
+## 3. Obtain Sufficient Understanding
+
+Attached video, images, and audio in this conversation are the content evidence. What you see and hear decides selection, order, pacing, and which moments count as highlights. Do not call another tool to restate that content.
+
+This environment has no shell. Never look for, install, or run mediakit-cli, and never use a terminal command. Do not treat frame extraction, OCR, or `extract_video_frame` as content understanding. `extract_video_frame` only makes a cover image.
+
+Use tools in this order, and skip a step that the decision does not need. Read [Timestamp fallback](references/media-understanding.md) before step 4 or step 5.
+
+1. Watch and listen to the attached media. Labels such as highlights, Vlog, or cinematic are selection clues, not a reason to call an analysis tool.
+2. Before `sync_materials` or a canvas size, call `get_media_metadata` on each HTTP(S) source. Set integer `duration_ms` to `round(duration × 1000)`. Pass `width` and `height` for video and images. Do not guess these numbers, and do not call a CloudEdit probe for an ordinary public URL. Use `probe_video_metadata`, `probe_audio_metadata`, or `probe_image_metadata` only for a `vod://` or `tos://` address, or when an image needs average hue or BlurHash. Video and audio probes return completed technical metadata. Use that result. Image probe returns immediately.
+3. Call `asr_subtitles` only when this edit places timed subtitles or the user asks for sentence-level source times. Speech you can already hear, or a transcript already in the conversation, is enough to understand dialogue. It is not subtitle timing. Do not submit ASR just because people are talking.
+4. When a planned cut still has no usable source time, call `media_understanding` for that one material. For a video storyboard pass `scene` as `editing`. Ask only for the missing range. Do not ask it to describe what you have already watched.
+5. Call `analyze_video_highlights` only when step 4 is still not enough, the source is a short drama (`Miniseries` / `StorylineCuts`) or a mini-game (`Game` / `HighlightExtract`), and the user needs scored highlight ranges. Those scores are candidates, not a finished cut. A request to keep the highlights of a Vlog or interview stays at step 1; if those chosen moments still lack times, use step 4.
+
+If a file is only a bare URL with no attachment, or you could not watch it because it exceeds the current model's input limits, say that you did not see it. Do not invent a shell workflow. In that case `media_understanding` may supply both content and times. That is the exception.
+
+Keep observed visual facts, recognized speech, and inference distinct. Retain original source times and coverage. Do not fill partial or failed results with imagined scenes, words, chronology, beats, or precise cut points. Use the finished tool result. If `status` is `failed`, read `error` (`code`, `message`, `param`, `type`) and do not submit that same task again.
+
+Evidence is sufficient when:
+
+- Each selected source has accessible identity and the content or timing its use needs. Watching or hearing the attachment counts. A broad selection has adequate candidate coverage.
+- Each content-dependent image or audio use has its own content evidence. Metadata-only results remain technical checks.
+- Retained speech, actions, steps, and story references remain intelligible at proposed boundaries.
+- Requested audio alignment, text, crop, and connections have their own supporting evidence.
+- `sync_materials` numbers come from `get_media_metadata` or the allowed probe, not from a guess.
+- Required coverage is reconciled against the inventory, including excluded files when all-file analysis was requested.
+
+For a gap, take the next applicable step above, choose a supported alternative within the user's constraints, or leave the decision explicitly unresolved. Continue independent portions, but do not label dependent planning executable while required evidence is pending. Sufficient evidence is decision-specific, not exhaustive transcription or frame-by-frame cataloging.
+
+## 4. Prepare Only Necessary Materials
+
+Read [Processing and Source Lineage](references/processing-and-lineage.md) when a technical obstacle blocks the edit or the user asks for processing. Prefer timeline trims, placement, speed, gain, and crop. This agent cannot separate audio, transcode, repair, or sample frames for analysis, and it has no shell. If the timeline cannot do the operation, say so.
+
+Retrieve completed processing results, verify properties and affected content, and preserve original-to-derived time/geometry mappings. Invalidate only affected evidence. A returned URL is not a project material ID; give cloudedit ready external assets for explicit synchronization before timeline references.
+
+For plan-only work, perform analysis prerequisites within authorized scope, but describe production processing as pending unless also requested. Required pending output keeps the dependent plan conditional; do not claim a derivative exists.
+
+## 5. Design and Check the Edit
+
+Form an editorial idea before filling a timeline: state what the piece should communicate or make the audience experience, and how the available material can achieve that. This is a working hypothesis, not a slogan or a genre template. Revise it when source evidence contradicts it.
+
+Develop the idea through the decisions that matter for this request:
+
+- Identify the material carrying the central meaning or experience, and what context makes it understandable. Distinguish indispensable content from supporting, redundant, or distracting material.
+- Find supported connections among those pieces: what changes, what answers another piece, what contrasts, or what creates a meaningful visual or audible association. Choose an order for those reasons; upload order and assumed chronology are not evidence.
+- Set emphasis and pacing around the time needed to understand, observe, hear, or feel each piece. Decide what should be brief, sustained, omitted, or intentionally repeated rather than allocating equal slots or a fixed stage budget.
+- Decide how picture, sound, silence, and any requested text contribute together. Use processing or stylistic treatments only when they solve a problem or serve a specific expressive purpose supported by the user's intent.
+
+When materially different approaches fit the evidence, compare their effect on the user's priorities and select the strongest supported one. Do not require multiple proposals for every task or ask the user to make routine editorial decisions. Explain the chosen idea concisely before the detailed source-to-timeline mapping.
+
+Check whether the idea survives its concrete selections and boundaries: whether meaning remains complete, claimed relationships are supported, and each treatment earns its place. Revisit weak decisions or gather focused evidence. A hook, staged progression, music, subtitles, transitions, and a closing message are choices, not required components. Autonomy includes leaving an effective passage simple.
+
+Read [Editing Plan Mechanics](references/editing-plan.md) to map the idea to timeline uses and check duration and continuity. Keep source in/out separate from placement; account for speeds, holds, transitions, and repeated occurrences. Independent cuts and alternatives have separate placements/budgets, not one concatenated timeline. Total duration is the final timeline end, not the sum of concurrent tracks. Resolve strict duration conflicts without silently changing mandatory content or asserting unproven minima.
+
+For text, read [Subtitle Timing and Display Units](references/subtitle-timing.md). Distinguish verified dialogue from editorial titles. Map source speech to every audible edited occurrence; muted/replaced sound does not automatically contribute subtitles. Recheck synchronization after structural changes.
+
+Before handoff, read cloudedit's [Project Fundamentals](../cloudedit/references/edit-project.md) and applicable operation references. Confirm treatments can be represented by available capabilities. Keep editorial timing explicit; cloudedit translates it to its current schema and integer-millisecond conventions. Resolve unsupported required operations rather than silently dropping them.
+
+## 6. Hand Off and Deliver
+
+Use [Executable Handoff](references/executable-handoff.md) as a completeness guide. Simple sequences need concise source/range/order instructions; complex edits need explicit layer/occurrence timing. This is an editorial contract, not a new tool schema.
+
+For plan-only work, deliver the plan, reasons, and unresolved dependencies, then stop. For production, pass the same plan/evidence to cloudedit and continue to synchronize materials, apply changes, and run its quality gate. cloudedit resolves real resource IDs and operation parameters without reopening settled creative decisions. If execution is unavailable, retain the usable plan and state what remains unapplied.
+
+After implementation, compare actual source trims, placements, canvas, treatments, and duration with the plan in addition to cloudedit's structural gate. Read back after the final write. On partial failure, inspect current state and repair only missing/wrong changes; recheck affected dependencies rather than rebuilding everything.
+
+Report what was planned, processing completed, project changes read back, and whether a composed audiovisual preview was inspected. A structural snapshot does not prove visual appearance or perceived audio quality. Return a real project/editor reference when available; never invent preview/export URLs. Identify remaining manual review and blocked work without claiming audiovisual validation.

package/skills/cloudedit-planner/evals/evals.json

@@ -0,0 +1,80 @@
+{
+  "skill_name": "cloudedit-planner",
+  "evals": [
+    {
+      "id": 1,
+      "name": "mixed-media-pending",
+      "prompt": "离线推演，不调用真实媒体服务或写工程。用户要求：先充分理解全部素材，再做约45秒周末骑行Vlog，保留高光瞬间和我的原声。素材 ride.mp4、03_reconciliation_sad.wav、cover.jpg 都已附在对话里，模型可以直接观看和收听。视频画面已看清：出发、骑行、到达。对白能听懂，但没有句级时间戳，用户没要字幕。wav 和 jpg 的内容本轮也能直接听到和看到；另外已知 wav 时长与声道、jpg 尺寸。请给出下一步工具安排、能确定的方案和 cloudedit 交接状态，不编造任何工具结果。",
+      "expected_output": "用已观看的画面和已听到的声音做 Vlog 选片，高光自己选，不调用 media_understanding、高光工具或 ASR；切点时间未知时方案保持条件性。",
+      "files": [],
+      "assertions": [
+        "Keeps the deliverable a Vlog rather than standalone highlight extraction.",
+        "Uses the attached video, wav, and image as content evidence instead of scheduling media_understanding or a metadata-only reading.",
+        "Does not call analyze_video_highlights, mediakit-cli, or ASR. Heard dialogue is enough because subtitles were not requested.",
+        "Keeps source cut times and the cloudedit handoff conditional; invents no timestamps or executed project. A later timestamp tool is a gap, not the next step."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "processed-source-clock",
+      "prompt": "离线方案，不调用工具或写工程。已确认原视频A的12–20秒完整一句话，原始ASR词句时间为14–16秒。已完成必要的音频清理，输出D是A的12–20秒，验证过保持1x且无额外偏移，所以D长8秒；输出仅有可访问URL，未入库。成片使用A画面12–20秒放在时间线0–8秒且原声静音，D作为唯一声音从时间线0秒开始，末尾加已审核图片B停留3秒。加这一句的字幕。请给出来源、三种时钟、轨道安排、cloudedit交接和验收边界，不宣称工程已经完成。",
+      "expected_output": "原14–16对应D2–4和时间线2–4；画面0–8图片8–11，D0–8，整体11秒；D需同步真实ID，不重复字幕；区分结构和视听验证。",
+      "files": [],
+      "assertions": [
+        "Maps original speech 14–16 s to derived D 2–4 s and timeline 2–4 s.",
+        "Places video and sole audio at 0–8 s, image at 8–11 s, and computes total 11 s.",
+        "Requires explicit synchronization of D and real material IDs before use, preserving original and derived identity.",
+        "Avoids duplicated audio/subtitles and distinguishes project readback from composed audiovisual validation."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "independent-cuts-conflict",
+      "prompt": "离线计划，不调用工具或写工程。用户要两条独立发布的演讲精选，每条最多10秒，不能变速，必须保留各自完整指定论点。用户已确认保留区间：第一条唯一完整必保留span为S1源0–12秒，第二条为S2源20–28秒；不存在转场重叠或可删停顿，相关内容和字幕时间都已核对完成。当前只知道一个已有工程P。请说明冲突、可继续部分、交给cloudedit所需内容和项目安排，不自行替用户放宽限制。",
+      "expected_output": "第一条12秒超10秒约束冲突需要选择，不截断变速；第二条8秒可规划；独立项目目的地需落实，不把两条放一条时间线，不重新取证。",
+      "files": [],
+      "assertions": [
+        "Identifies the first mandatory 12-second span as incompatible with the 10-second cap without changing speed or truncating it.",
+        "Plans the second independent 8-second cut while retaining the first conflict for user resolution.",
+        "Keeps separate deliverable/project destinations and resolves use of P rather than concatenating both cuts.",
+        "Reuses the user-confirmed ranges and checked subtitle timing; does not rerun selection or claim application."
+      ]
+    },
+    {
+      "id": 4,
+      "name": "same-sources-different-intent",
+      "prompt": "离线设计，不调用媒体或工程工具。全部素材内容已核对：A是完整8秒操作，前2秒拿工具、中4秒操作、后2秒展示结果；B是同一次操作的细节近景4秒；C是一张结果照片；D是用户6秒原声，解释刚才容易犯的错误，文字与时间已有核对。针对同一组素材，分别设计两个不同思路：甲希望观众学会避免这个错误；乙希望给家人留一段安静的个人记录，不强调教学。均无固定时长，不加音乐/字幕/包装。请自主选材、解释顺序和节奏，不必列多套候选，不编造具体动作细节。",
+      "expected_output": "Two distinct evidence-backed ideas; instructional context vs personal observation, without default packaging or invented events.",
+      "files": [],
+      "assertions": [
+        "Develops different organizing ideas for the two user goals using the supplied content, rather than repeating a fixed sequence.",
+        "Explains retention/order/pacing with source evidence and preserves complete meaning without inventing specific actions.",
+        "Respects no music, subtitles, or packaging and does not unnecessarily delegate routine creative decisions back to the user."
+      ]
+    },
+    {
+      "id": 5,
+      "name": "label-versus-priority",
+      "prompt": "离线设计，素材均已理解。用户说“做一个产品Vlog，要高级一点”，进一步明确：仅让观众看清手工杯表面纹理，不卖货、不讲制作过程、不加文字或音乐；保留自然触摸声。现有A为12秒稳定缓慢转动杯子，纹理持续可辨，完整自然声音；B为3秒快速晃动，纹理看不清；C为4秒包装上的logo。无强制片长。请直接给出剪辑思路、选舍理由与cloudedit可实现的计划，不再向用户提问。",
+      "expected_output": "Prioritizes observable texture and natural sound, can retain A simply, omits unsuitable footage without imposing ad/Vlog stages.",
+      "files": [],
+      "assertions": [
+        "Centers the plan on visible texture and natural touch sound rather than a Vlog or advertisement formula.",
+        "Gives concrete cloudedit-implementable placement with source ranges or an explicit full-source use, without arbitrary fast cutting or padding.",
+        "Omits unclear B and irrelevant logo C with reasons; adds no text/music/selling message and asks no unnecessary question."
+      ]
+    },
+    {
+      "id": 6,
+      "name": "unknown-material-autonomy",
+      "prompt": "离线下一步计划。用户给了一段视频、一张照片和一段录音，都已附在对话里，模型可以直接观看和收听。用户说“帮我剪成一个让人能理解这件事的短片，你自己决定怎么剪”。目前回复里还没写出内容结论，只另外知道时长和尺寸。请说明如何开始、会围绕哪些剪辑问题做决定，以及什么条件下能形成思路。不要编造事件，也不要把所有创作选择都退回给用户。",
+      "expected_output": "先根据已附上的画面和声音做选片和结构，不把 media_understanding、高光工具或 ASR 当作第一步。",
+      "files": [],
+      "assertions": [
+        "Starts from watching and hearing the attached video, image, and audio. Does not schedule media_understanding, highlight analysis, or ASR before that.",
+        "Frames the edit around comprehension, relationships, usable boundaries, and editorial decisions rather than exhaustive genre checklists. Metadata does not replace content.",
+        "Keeps the organizing idea provisional until the attached media has been used, invents no event or predetermined arc, and assumes responsibility for routine editorial decisions. Missing cut times stay a later gap."
+      ]
+    }
+  ]
+}

package/skills/cloudedit-planner/references/editing-plan.md

@@ -0,0 +1,63 @@
+# Editing Plan Mechanics
+
+## Scope
+
+Choose structure and treatments from the user's goal and source content, without imposing a fixed template.
+
+When working with an existing project, read its current timeline and identify whether the request calls for appending content, replacing a sequence, or modifying specific clips. Derive the affected range and tracks from the request and project context. Preserve unrelated content; clarify only if the target or scope remains ambiguous. Account for ripple changes to later clips and synchronized audio or subtitles before applying a duration change.
+
+Identify whether the output is one sequence, several independent cuts, or alternative versions. Maintain separate placements, duration budgets, and checks for independent deliverables; concatenate only when a montage is requested. For a local revision, reuse the established plan and inspect the affected sources and neighboring boundaries instead of restarting full-source selection.
+
+## Preserve the Editorial Idea
+
+Carry the source-backed editorial idea from the main skill into concrete selections and placements. Use these mechanics to check feasibility, not to decide a finished structure in advance. Presentation order does not establish event chronology or causal relationships.
+
+## Select Material and Fill Evidence Gaps
+
+Check whether each candidate serves the goal, communicates clearly, and preserves necessary meaning or action results at its cut points. Request further understanding only for unresolved questions: semantic and audio boundaries for dialogue, steps and state changes for processes, or direction, framing, and subject position for visual connections.
+
+Reuse adequate descriptions, transcripts, or precise user-supplied ranges. Request only evidence needed for a decision, without requiring a fixed set of fields or numerical confidence scores.
+
+Distinguish redundant content, multiple views of the same event, and purposeful repetition. Remove repetition only when it adds no information and serves no purpose. Reuse is valid for recap, comparison, callbacks, or replay. Matching filenames or people alone do not establish duplication.
+
+## Arrange and Treat the Material
+
+- Allocate duration according to content and the user's target. Preserve complete meaning in dialogue and key steps in operations; allow enough time to read and view images. Do not truncate content to fit arbitrary shot lengths.
+- Make adjacent clips connect through information, visuals, or sound. A hard cut is usually sufficient; use transitions for a clear purpose, allow the required source handles, and account for overlap in total duration.
+- Use speed changes, freezes, and cropping for a specific expressive purpose. Check their effect on action comprehension, sound, and key information. Keep source time separate from timeline time.
+- Preserve informative dialogue and source sound. When music is supplied or requested, balance it against important audio. Music is optional, and the edit need not match a whole track's length.
+- Add subtitles or text only when requested or needed for communication. Follow [Subtitle Timing and Display Units](subtitle-timing.md): reuse verified text, map it to edited occurrences, and fill only missing or unreliable evidence. A summary is not a verbatim transcript. Do not present summary titles as quotations. Create no subtitle track when text is unnecessary.
+- Orient the audience at the opening and end in a way that serves the goal.
+
+## Resolve Duration Conflicts
+
+Distinguish a strict duration limit from an approximate target. If the edit is too long, first remove expendable waits and redundancy while preserving intentional pauses and purposeful repetition. Then omit lower-priority complete units, checking that remaining statements, steps, and outcomes still make sense. Preserve user-required content, order, and ranges.
+
+Use faster playback only when it serves the content and remains intelligible. If required material still exceeds a strict limit, explain the conflict and identify the constraint that would need to change. Give an exact feasible duration only when source ranges, playback speeds, and overlaps are established. Otherwise provide an estimate or range with its assumptions, and identify missing timing evidence; do not claim a proven minimum. Ask which requirement can yield before executing an incompatible edit. For a plan-only request, present the conflict and feasible alternatives. If the material is shorter than the target, avoid padding with unsupported content or arbitrary repetition; report the achievable duration when meaningful holds or pacing adjustments are insufficient.
+
+## Map Sources to the Timeline
+
+Use a concise list or table with each selected source, its source in/out range or image hold duration, its sequence or timeline placement, and any necessary treatment. For an existing project, identify the affected clips or sequence and the intended operation. Add fields only when needed to execute the edit; no fixed schema is required.
+
+For a simple sequence, order and resulting clip durations may be enough. When speed changes, overlaps, replay, or synchronization affect placement, state timeline start/end positions and distinguish them from source times. At constant speed, playback duration is source duration divided by the speed multiplier; add holds and account for actual transition overlaps. Derive total duration from the timeline's end, rather than summing concurrent audio, video, and text tracks.
+
+For example, source `action.mp4` at 10–14 seconds plays for 4 seconds at 1x. Replaying the same range at 0.5x adds 8 seconds: with no gap or overlap, the two timeline placements are 0–4 and 4–12 seconds. Align any retained audio or captions with their respective edited occurrences, not with the original source timestamps.
+
+## Plan and Acceptance Checks
+
+Let the material guide unspecified minor choices, and explain choices that materially affect the result. Ask the user only when a critical gap prevents a decision.
+
+Before delivering a plan, check that:
+
+- Selection and structure serve the goal and preserve specified order, ranges, and audio requirements.
+- Selected content is supported by evidence; content, chronology, and outcomes have not been invented.
+- Timeline placement accounts for speed changes, image holds, and transition overlaps; duration conflicts, required resources, and gaps are explicit.
+
+After execution, also check that:
+
+- Actual project clips, order, and duration match the plan.
+- Changes stay within the intended scope; unrelated content is preserved and affected downstream clips, audio, and subtitles remain correctly placed.
+- There are no accidental gaps, black frames, out-of-bounds trims, truncated dialogue, competing audio, or misaligned subtitles; intentional pauses, silence, black frames, and reuse remain intact.
+- Subtitles, music, and effects that were used have been verified. Unused treatments introduce no extra production or validation requirements.
+
+After a correction, verify the changed values and dependent boundaries, not every unrelated source. Selection, order, or duration changes may require broader content and synchronization checks; a style-only change does not. If a write failed or a readback value differs, inspect current elements and IDs before retrying to avoid duplicate additions. Treat unconfirmed writes and unpreviewed audiovisual behavior as incomplete verification.

package/skills/cloudedit-planner/references/executable-handoff.md

@@ -0,0 +1,25 @@
+# Executable Handoff to Basic
+
+Use a list/table suitable for task complexity. These are completeness criteria, not mandatory JSON fields or tool parameters:
+
+1. Intent and scope: purpose, plan-only/production, known project, new/append/replace/local edit, binding constraints, assumptions, separate deliverables.
+2. Canvas and duration: requested dimensions/aspect ratio and relevant known FPS; strict/approximate budget per deliverable. Reuse current settings or state suitable defaults where unspecified.
+3. Sources and preparation: accessible reference, original/derived identity, readiness, evidence provenance/ranges, synchronization, completed/pending processing. Only use actual retrieved IDs.
+4. Sequence and layers: source, source in/out or image hold, order, track role, necessary treatment. Include timeline start/end, speed, overlap, and occurrence identity when synchronization/layering requires them. Preserve audio/video associations.
+5. Audio/text/connections: supplied assets, audible ranges, requested mixing/fades, verified subtitle text and source timing, editorial titles distinguished from quotations, transitions and required handles. Omit unused categories.
+6. Rationale and gaps: evidence for major choices, unresolved dependencies, blocked operations, and next checks. Label the plan conditional until required evidence/assets/capabilities are ready.
+7. Acceptance: values to compare with project readback, dependent timing, content/audio checks needing composed preview. Apply cloudedit's gate without treating structural success as audiovisual review.
+
+Independent deliverables need separate project destinations under cloudedit's one-timeline-per-project model and actual environment support. Do not assume multiple timelines inside one project or concatenate independent versions. Resolve ambiguous destinations before writing.
+
+## Example: Exact Accepted Material
+
+User facts: silent video A source 10–14 s at 1x, replay that range at 0.5x, then supplied image B held 3 s. No transitions/music/text. Sources are accessible; content and fitting already approved.
+
+| Occurrence | Source selection | Timeline | Treatment |
+| --- | --- | --- | --- |
+| A-main | A 10–14 s | 0–4 s | 1x, silent |
+| A-replay | A 10–14 s | 4–12 s | 0.5x, silent |
+| B-end | B hold 3 s | 12–15 s | Approved fitting |
+
+Duration is 15 s. These are planning values, not proof of application. Basic resolves IDs, translates to supported operations, and reads back ranges, speed, duration, order, and fitting. No new semantic analysis is needed for this exact approved sequence. Selecting an image or choosing an unknown crop would require image-content evidence first.

package/skills/cloudedit-planner/references/media-evidence-models.md

@@ -0,0 +1,32 @@
+# Evidence for Editorial Decisions
+
+Start from an unresolved decision, not a media genre or a list of everything a tool can describe. Use only the dimensions that can change the edit. Existing source-linked understanding, verified transcripts, and exact user instructions may already answer the question.
+
+| Decision | Evidence to establish |
+| --- | --- |
+| What is worth retaining? | Relevant visible/audible content, complete meaning or action, usable source boundaries, contribution to the user's purpose |
+| What context is necessary? | Referents, prerequisites, questions and responses, state changes and outcomes, with observed facts distinguished from interpretation |
+| How do pieces relate? | Supported identity, time/place or causal relationships, complementary views, contrasts, repetitions; mark uncertain connections |
+| Where can a cut work? | Speech/action completeness, entering and leaving visual states, direction and position, continuing sound, missing context at the boundary |
+| What should lead the pacing? | Time needed to comprehend speech, inspect details, read visible text, perceive an action or sustain a requested feeling; relevant sound phrases/events |
+| How should sound be used? | Actual speech, music, ambience or sound events, source-time boundaries, overlap, intelligibility and correspondence to picture |
+| Can a composition work? | Visible subjects, important details/text, spatial bounds and regions that must remain visible; actual content of standalone images |
+| Is processing necessary? | An observed defect or compatibility limit, where it occurs, what required content it obscures, and whether selection or editable adjustment already solves it |
+
+These are questions to select from, not mandatory sections of every analysis result. Do not request detail merely to fill a record. Do not invent numeric confidence scores or exact timing from coarse evidence.
+
+## Match Evidence to the Source
+
+Videos may supply motion and sound, but understanding their frames does not establish the speech or music. Images can supply subjects, composition, text, and visible states; they do not establish motion, before/after events, or sound. Separate audio can carry meaning and timing independently of video, but does not prove what was visible. Inspect each source needed for a content-dependent use.
+
+Metadata establishes technical properties, not meaning. Filenames may suggest questions, but do not establish identity, chronology, mood, claims, or quality. Similar people or objects do not by themselves prove sources show the same event or are interchangeable takes.
+
+Understand dialogue from what you hear in this conversation, or from a transcript that is already present. Call `asr_subtitles` only when the edit needs sentence-level source times for subtitles or the user asks for those times. Preserve complete utterances and uncertain words. A summary is not verified dialogue. An empty transcript does not prove silence or describe non-speech sound.
+
+When a cut needs a source time you cannot place by watching, follow [Timestamp fallback](media-understanding.md). Preserve original time offsets and any processing mappings. Do not turn a coarse impression into an exact beat or cut point.
+
+## Close a Gap
+
+Specify the affected source/range, the blocked decision, and the visual or audible fact needed. Retrieve the result, check whether it answers that question, and update the decision. Continue independent decisions while results are pending. If a fact cannot be established, retain the uncertainty or choose an adequately supported alternative within the user's constraints.
+
+Stop gathering evidence when it is sufficient for the intended decisions and requested analysis coverage. More description is not inherently a better basis for editing.

package/skills/cloudedit-planner/references/media-understanding.md

@@ -0,0 +1,25 @@
+# Timestamp fallback
+
+Use this page only when a planned cut still has no usable source time after you have watched or heard the attached media. It is not the way to learn what the material contains.
+
+This environment has no shell. Do not look for, install, or run mediakit-cli. Do not run a terminal command. Do not sample frames, run OCR, or call `extract_video_frame` to understand a video. `extract_video_frame` only produces a cover image.
+
+## When a cut still has no source time
+
+Call `media_understanding` for the one material whose in and out times are missing.
+
+- Put the timing question in `prompt`. Name the moment you already identified and ask for its source-clock range. Do not ask for a fresh description of a video you have already watched.
+- For a video storyboard with precise shot boundaries, pass `scene` as `editing`. Omit `scene` for a standalone image or audio file.
+- Submit one `media_url` per call. The finished text is in `result.contents`. Use those source-clock times. Do not submit the same material again.
+- If the material is only a bare URL with no file attached, or you could not watch it because it exceeds the current model's input limits, say that you did not see the picture. In that case this tool may supply both content and times. That is the exception, not the default.
+
+Returned ranges are evidence for the cut. They do not replace the editorial choice you already made from watching.
+
+## Scored highlight ranges
+
+Call `analyze_video_highlights` only when `media_understanding` still does not provide the times you need, the source is a short drama or a mini-game, and the user needs scored highlight ranges.
+
+- Short drama: `model` `Miniseries`, `mode` `StorylineCuts`.
+- Mini-game: `model` `Game`, `mode` `HighlightExtract`.
+
+A Vlog, interview, or talking-head request to keep the highlights is a selection you make from what you watched. Do not call this tool for that. Scores and suggested segments in `result.highlight_info` are candidates, not a finished edit. Use that finished result and do not resubmit it.