@aswless_854771076/ai_short_studio_cli 0.1.97 → 0.1.99

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/video-downloads.md

@@ -0,0 +1,47 @@
+# Downloading a video from a link
+
+Read this when a reference or source clip lives on a video page. `hypit media fetch` saves the
+video as a project file through yt-dlp. For a website's interface, scroll or interaction, use
+[browser capture](browser-capture.md).
+
+## Save the source video
+
+```bash
+hypit media fetch "https://example.com/watch?v=VIDEO_ID" \
+  --to references/ad/source.mp4
+```
+
+Replace the example URL with the actual video link. Quote it so URL punctuation stays part of the
+argument. The destination is relative to the current directory; the CLI creates parent directories
+and requires a new output path. `--json` reports the saved path, source URL, duration, dimensions,
+frame rate and audio presence.
+
+The command fetches one video, including its audio when available, even when the link also belongs
+to a playlist. It prefers H.264 and a resolution near 1080p; the source's available formats determine
+the result. Destinations can use `.mp4`, `.mkv`, `.webm` or `.mov`. Downloading retains source timing;
+it is separate from preparing material for a production's frame clock.
+
+## Prepare the downloader
+
+Run `hypit media prepare-fetch` explicitly before the first fetch. It uses uv to prepare the
+Distribution's locked downloader and JavaScript solver, then reports the executable path. Reuse that
+environment for subsequent downloads. `media fetch` never installs dependencies, updates tools or
+acquires remote components; a missing environment reports the preparation command. `ffmpeg` merges separate picture and sound streams, and `ffprobe` reads the
+saved file. [Local tools](../environment/local-tools.md#supply-host-executables-at-machine-scope)
+covers these executables on macOS, Windows and Linux. The command runs directly, without a Runtime
+Profile, model credential or Build.
+
+Supported sites and access requirements depend on yt-dlp and the source site. A failed download
+includes the downloader's error. When a site needs additional download options, the installed
+`services/yt-dlp/README.md` explains direct use of the packaged tool; the site's own download or
+export can also supply the same local file.
+
+## Continue from the saved file
+
+Keep the source URL and local path in the reference notes. Use the file for
+[reference understanding](../creation/reference-video.md): transcription, timed frames and grids all
+refer to that same source clock. Reuse the saved file when returning to the reference.
+
+When the downloaded clip becomes material in the new video, declare it as `media:Video` and follow
+[media preparation](media.md). The composition then places the prepared material against the
+target's events.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/vocabulary.md

@@ -0,0 +1,119 @@
+# Choosing and extending author vocabulary
+
+Read this when deciding which installed Surface should express a Treatment role, or whether the
+production needs a new project Author Package.
+
+## Search from the role
+
+Name what the element must do in the work before choosing its implementation. Useful questions are:
+
+- What does the viewer perceive, and why is it present?
+- Is it Caption, independent Typography, A-roll, B-roll, MG, UI, Effect, Audio, or a new role?
+- What does it consume and publish?
+- Does it follow a Script Selection, a Moment, an explicit time span, or another component state?
+- What changes over time, and what stays visually persistent?
+- Which choices need author inputs, and which design can stay specific to this piece?
+
+Query the likely package owners:
+
+```bash
+hypit vocabulary
+hypit vocabulary @hypit/caption-fine
+hypit vocabulary @hypit/media-pipeline --tag StillVideo
+hypit vocabulary --visual text
+```
+
+Use a focused package and tag query before the first use of an unfamiliar Surface in the current
+production. Query it again when the selected package or Distribution changes, or when `hypit check`
+shows that an assumed declaration is not the installed one. Once the declaration is established in
+the current context, ordinary edits do not require repeating the same query.
+
+With no package argument, the command lists every package visible to the current Distribution and
+project together with its tags and models. Use that inventory when the role is clear but the owner is
+not. A focused package query then reports Surface attributes, children, ports, examples, and designed
+previews, including the logical Module import when one physical package contributes several Modules.
+The package README supplies exact behavior that is local to that installed implementation.
+When the question requires more detail, inspect the relevant implementation and exported API. An
+existing component can also provide a useful implementation example for a new project package.
+
+Run Fragment libraries have a separate interface. A package can provide
+Candidates while declaring no Markup Surfaces. Read [Runs](runs.md) and the library's
+package-local Fragment documentation for those inputs and exports.
+
+## Connect model references as typed inputs
+
+Read the model Surface's reference roles and per-input metadata as well as its prompt parameters.
+The prompt gives direction; the actual edges supply media and the declared facts needed to use it.
+Seedance requires `person-reference="true|false"` on every image/video reference: true if the supplied
+material contains a person, false otherwise. Audio must omit it. Its installed README owns the required
+first/last-frame forms. The
+[Provider](../environment/model-and-provider.md) translates these facts into the selected service's
+media preparation without adding service instructions to the creative prompt.
+
+## Choose a component for its behavior
+
+An installed Surface fits when its semantic role, inputs and outputs, temporal behavior, composition
+ownership, and visual range match the intended work. Parameter differences such as words, colors,
+spacing, or ordinary media inputs belong to authored configuration when the Surface already exposes
+them.
+
+A catalogue preview helps identify the component's visual role. Its declared inputs and behavior
+show what can be adapted; its configured appearance in Studio shows how it serves this production.
+
+Record the creative role in Treatment and express the implementation choice through Source imports
+and elements. Those two places contain the useful reason and the exact choice.
+
+## Create a project component as normal production work
+
+When the work introduces a new visual role, structure, state change, interaction, or crafted behavior,
+create a project Author Package under the project's `packages/`. This is a normal part of making a
+video. Do not patch Hypit Core, the CLI, or an installed Distribution package to implement one video's
+component. Author the behavior in the video's project package and select it through normal imports.
+
+Keep the boundary useful:
+
+- the package owns rendering behavior, fixed design, input shapes, defaults and the vocabulary that
+  explains them, whether used once or reused;
+- Source and Recipe connect supplied content, assets and semantic timing, and own the choices exposed
+  by the component;
+- Runtime Profiles own external execution and credentials;
+- Provider packages implement media tools and external services.
+
+Read the installed `@hypit/hypit/author-kit` README for the public package boundary and a relevant component
+for an implementation example. Give the new package its own Module identity and use the project
+owner's scope; the selected Distribution owns the reserved `@hypit/*` namespace.
+
+TypeScript imports use public SDK paths such as `@hypit/hypit/author-kit`, `@hypit/hypit/composition`,
+`@hypit/hypit/text`, `@hypit/hypit/caption` or `@hypit/hypit/studio-adapter`. Source imports instead name logical Modules,
+such as `@hypit/caption@1`. When learning from installed official source, translate its internal
+workspace imports to the corresponding public SDK paths in the project package.
+
+Describe the Surface's role, attributes and outputs with a small valid example so a future author
+can select it. A visual preview makes its appearance recognizable; Studio shows the actual
+configuration used in a production.
+
+For existing Track composition, read [Tracks](tracks.md). For a new Track,
+[Component design](component-design.md) shapes its visual idea, semantic behavior and useful controls.
+[Track authoring](track-authoring.md) explains temporal inputs, spatial ownership, persistent
+state, preset content and peer visual/audio outputs. [Caption authoring](caption-authoring.md) covers
+a new speech-text family without rebuilding its transcript or timing.
+
+[Studio and Companions](studio.md) covers timeline presentation and Inspector editing for the new
+component.
+
+[Component visuals](component-visuals.md) explains the actual Track and element representation,
+with a drawing example. [System relationships](system.md) places it in the complete production.
+
+## Let ordinary package management own distribution
+
+The project's package manager installs and versions components. Hypit loads only packages selected
+by Source or Run imports and their declared dependencies. Project packages resolve from the project;
+reserved `@hypit/*` packages come from the selected Distribution. It does not scan the dependency
+tree for possible components.
+
+Keep a new component project-local while it serves this work. If its owner later wants to use it
+across projects, send a versioned tarball or publish an npm/private-registry release and pin it in the
+consumer project's `package.json` and lockfile. Sharing changes where the same package is installed;
+it does not change the component model or require a Hypit-specific registry.
+
+[Sharing a project package](component-sharing.md) owns the packaging, identity and upgrade details.

package/skills/using-vvicat-ai-short-studio-cli/references/project-and-canvas.md

@@ -5,7 +5,7 @@
 ## 初始化和配置
 
 1. `preflight --json` 检查地址、CLI 版本、认证和标准能力；`restartRequired` 为真时重跑。仅缺可确定的账户 `capabilityDefaults` 时，从实时 options、目标项目有效值或模型默认值补齐并回读；模型不可用或候选缺失时停下询问。
-2. `config get` 展示个人默认模型、能力默认值和管理员下发的工作流并发；`config set` 只能修改前两项。供应商、密钥、全局模型目录和工作流并发由管理员维护。
+2. `config get` 只管理个人默认模型、能力默认值和工作流并发。供应商、密钥和全局模型目录由管理员维护。
 3. 新项目按“确认名称/用途 → `project create` → `project get` + 一次 `canvas inspect`”执行；既有项目先聚合读取。项目配置回读通过前不得创建创作节点。
 4. `canvas settings get` 必须确认项目覆盖值、继承后的有效值、来源和实时候选。默认推荐 `storyboardImageType: grid`；`visualBible` 按实时 schema 构造。`outputLanguage` 必须与用户确认的交付语言一致；“自动”只适合用户明确要求跟随输入且源剧本语言单一的普通拆镜。CLI `--locale` 只影响命令界面和输出消息，不代表内容语言。
 5. `imageResolution`、`imageQuality`、`videoResolution` 优先由项目统一设置；节点只有确需不同且实时能力允许时才覆盖。H3 模型必须与 `videoPromptType: "h3"` 同次写入。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/README.md

@@ -0,0 +1,11 @@
+# 可扩展画风
+
+`art-styles.json` 是 Dashboard 的内置画风目录。每个数组元素都是一个画风对象，至少需要包含：
+
+- `id`、`name`、`description`、`prompt`
+- `visualBible.version`（必须为 `1`）
+- `visualBible.palette`、`baseline`、`lighting`、`narrative_arc`、`motion_language`、`negative_constraints`
+
+复制一个现有对象修改即可新增画风。保存后重启 Dashboard，新的画风会出现在「生成配置」中；画风内容会原样写入项目的 `creative.art_style`。
+
+通过插件生成并确认的自定义画风，会自动追加到统一工作区根目录下的 `art-styles.custom.json`，下次启动自动与系统画风合并。也可用环境变量 `SHORT_DRAMA_CUSTOM_ART_STYLES_FILE` 指定自定义库路径。

package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: short-drama
+version: 1.0.0
+description: 短剧全流程唯一入口。用于原创短剧的创建、恢复、分析、编剧、导演、资产、分镜、打斗与 Blender 白模、图片/视频/声音生成、审核、剪辑、交付和市场研究；根据项目状态渐进读取 references 模块，不暴露或猜选子 Skill。参考片复刻统一使用原生 Hypit 链路。
+---
+
+# 短剧制作主 Skill
+
+本 Skill 是插件唯一入口。专业能力保存在 `references/` 模块中；不要凭模块名自行模仿，也不要一次性读取全部 reference。始终由项目状态和 `references/module-map.json` 决定当前需要加载的最小模块集合。
+
+## 固定控制循环
+
+进入控制循环前先确认项目类型：有参考片需要复刻、克隆或仿拍，或现有项目的 `workflow.type=viral-recreation` 时，立即转到原生 `hypit recreate`，不执行本插件的校验、模块路由或制作命令。以下步骤只适用于原创短剧的新建、恢复、继续和修改：
+
+1. 确认项目目录。除非用户指定其他绝对路径，新项目位于 `~/darma_project/<project-key>`。
+2. 新项目读取 [项目管理模块](operations/manage-drama-projects.md) 后初始化；已有项目先读取 `.short-drama/RESUME.md`、`.short-drama/project.json`、`.short-drama/state.json`、`.short-drama/module-runs.json`（若不存在则读取旧 `skill-runs.json` 供迁移）、`.short-drama/environment.json` 和 `source/manifest.json`。
+3. 运行：
+
+   ```bash
+   node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/validate-project.mjs" <项目目录>
+   node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/workflow.mjs" status <项目目录>
+   node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/module-runs.mjs" required <项目目录> <当前阶段>
+   ```
+
+4. 对返回的每个 `module_id`，从 `references/module-map.json` 读取唯一 `path`，完整读取该 reference 后执行其输入、输出、失败关闭和验收合同。
+5. 文本由 Codex 生成；只有图片、视频、声音和媒体变换调用 Provider。所有提示词使用 `assets/modules/<module_id>/prompts/` 中登记的模板并通过 `render-prompt.mjs` 留痕。
+6. 每个模块完成后登记实际输入与证据：
+
+   ```bash
+   node "${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}/scripts/module-runs.mjs" record <项目目录> <阶段> <module_id> <项目内证据...> --input <项目内输入...>
+   ```
+
+7. 运行 `workflow.mjs check`；只有当前及已完成阶段的文档、资产、审核和 module-run 全部有效时才 `advance`。修改上游事实时按状态机回退，不手改完成状态。
+
+## 九阶段基础路由
+
+基础顺序以 `module-map.json` 为唯一机器事实：
+
+| 阶段 | 基础模块 |
+|---|---|
+| analysis | `manage-drama-projects` → `analyze-drama-source` → `define-drama-brief` → `design-drama-bible` → `outline-drama-series` |
+| script | `short-drama` → `write-drama-episode` → `humanizer` → `review-drama-script` |
+| director-book | `write-drama-director-book` |
+| asset-analysis | `plan-drama-assets` → `generate-drama-art-style`，存在人物时增加 `generate-character-profiles` |
+| asset-generation | `manage-drama-assets`，缺少可复用资产时按需增加人物、场景、道具生成与生成服务模块 |
+| production-plan | 按条件加入 `design-fight-video`，再执行结构化分镜、制作计划与连续性模块 |
+| media-production | 原创项目制作双分镜板、视频提示词、镜头审核、视频生成和任务监控；复杂调度按需增加 Blender 白模，按声音策略增加音频模块 |
+| editing | `remotion-best-practices` → `edit-drama-timeline` |
+| delivery | `edit-deliver-drama` |
+
+不得把本表当作静态清单绕过 `requiredModules()`；动态模块只由结构化项目事实触发。
+
+## 条件模块
+
+### 打斗与动作设计
+
+只有导演本或制作决策明确存在 `action_complexity=choreographed`、`fight_design` 或 `fight_design_ref` 时加载 [打斗设计](storyboard/design-fight-video.md)。它适用于跨镜动作连续性、接触与受力结果、兵器、追逐、擒抱、跌倒、多人攻防或能力战。普通争吵、静态对峙、走路、握手、推门和简单拿放道具不触发；扇耳光、推搡和短暂拉扯只有被导演本明确判为需专业编排时触发。
+
+### 图片分镜与 Blender 白模
+
+制作计划按项目来源决定主运动参考，并逐镜记录 `storyboard_strategy.mode=image|blender`：
+
+- 所有镜头都生成并分别审核时间故事版与镜头分镜板；两者是视频生成必需参考。
+- `standard` 无参考视频项目默认依赖双分镜板，不把白模设为硬门禁；只有复杂路线、多人交互、精确接触、轴线风险或连续运镜无法由静态板无歧义证明时才用 `blender` 白模作为运动参考。不得先生成伪参考视频再转深度。
+- 需要白模时加载 [白模编导](storyboard/direct-blender-previz.md)、[白模生成](storyboard/generate-blender-previz.md) 和七项导演验收。
+- UE Mannequin 是默认人物模型；镜头时长、导演合同、媒体实际时长和制作计划必须一致。生成成功不等于通过，必须完整观看并完成多维审计。
+
+### 参考片复刻
+
+参考片复刻不属于短剧插件；请退出本流程，使用原生 Hypit 复刻链路。旧项目会被插件阻止并提示迁移。
+
+### 声音
+
+声音以成片原生声轨为先，先做七维复听并记录真实失败区间，再从最终 selected 音轨生成、复核字幕。合格原声不得重复 TTS 或整轨覆盖。StarRouter 尚无已验证的 CosyVoice 音色设计/克隆与 MuseTalk 口型能力；需要这些能力才能满足人物音色或可见对白同步合同时，明确阻塞并请用户调整制作方案，不得调用旧厂商或伪造通过。普通旁白、画外音只有在用户确认 StarRouter 可用音色与参数，且现有声音合同可满足时才能生成并完成八维复听。只有明确需要时才生成或授权 BGM、OP、ED；生成曲必须绑定剧情、人物主题、情绪弧、剪辑节奏和时长创作简报，未声明音乐不得交付。
+
+### 市场与支持操作
+
+市场模块只在用户明确要求或项目已绑定市场输入时加载。Dashboard、Provider 配置、资产管理、任务监控、媒体变换和故障恢复都是按需 reference，不是独立 Skill；MCP、CLI 与 Dashboard 工具入口保持可用。
+
+## 全局硬门禁
+
+- 不伪造原文、用户确认、权利、资产、Provider 调用、任务状态、媒体观看或审核结果。
+- Agent 检视本地图片时必须把生产原件与分析输入分开：先读取尺寸和文件体积，默认生成最长边不超过 2048 px、文件不超过 2 MB 的临时预览，并以普通/高细节模式读取，禁止首次直接读取或上传原图。预览仍不足时只裁切或分块读取关注区域，每块沿用相同上限；只有确需像素级核验且确认请求体安全时才读取原图。临时预览不得替换资产账本、哈希、Provider 参考或交付中的原件。
+- 远端生成前展示完整制作计划，包括 Provider、模型、参数、素材用途、候选数和请求次数；不计算具体价格，计划未确认不得提交。
+- 所有剧情事实、人物关系、结局、逐字对白与旁白变更先获得用户确认。
+- 画风确认必须先形成包含 `renderingContract` 的完整 style 对象；人物、场景、道具、双分镜板和视频提示词一律从该对象编译媒介与渲染规则。不得把真人写实当成通用默认，也不得让“设定板/故事板/电影感”等版式或质量词覆盖用户选择的二维、三维、定格、像素或自定义媒介。
+- 成年人物突出帅气、漂亮、飒、性张力、独立妆造和记忆点；儿童突出可爱并禁止成人化或性化。
+- 任何人物、场景、道具、分镜、视频、音频和剪辑产物都必须登记真实本地路径、版本、来源和 SHA-256；不得用占位文件通过门禁。
+- 图片分镜、白模、视频、原生声音、兜底配音和成片必须执行各自 reference 的完整多维审核。未观看/未听完不得批准。
+- 复刻必须遵守权利范围；结构迁移不等于获得原人物、声音、音乐、字幕、品牌或镜头素材的使用权。
+- Provider 失败不得静默切换、重复付费或隐式降低质量。用户允许兜底时也必须记录原因、范围和新确认。
+- `automation_mode` 只减少常规确认，不得绕过阶段、权利、付费、安全、选版或质量门禁。
+
+## 凭证与恢复
+
+`module-runs.json` 的每条记录绑定 module ID、reference 路径与哈希、输入与哈希、输出证据与哈希、prompt-run 及完成时间。reference、输入、选版或证据变化后记录自动失效。旧 `skill-runs.json` 永不原地修改；`module-runs.mjs migrate` 只迁移来源快照和证据均可验证的记录，其余模块重新执行。
+
+遇到失败先读取 [恢复模块](operations/recover-drama-pipeline.md)，保持失败关闭。需要更新分镜时生成新不可变版本，不覆盖旧版本；需要重新生成媒体时先检查已有请求、任务和收据，避免重复提交。
+
+## 完成标准
+
+只有 delivery 阶段的 module-run、时间线审片、技术 QC、字幕、声音、权利和交付清单全部有效，才可运行 `workflow.mjs complete` 并向用户报告完成。报告必须区分已完成、已审核、待确认、失败和允许兜底的部分。