create-dwy 0.16.0 → 0.17.0

package/templates/ai-tools/skills//350/207/252/345/252/222/344/275/223/uc-media-0040-script/templates//351/252/250/346/236/266-v1.1.md

@@ -0,0 +1,174 @@
+# 单集科普骨架 · v1.1（标准主体结构）
+
+> **用途：** 3–5 分钟、单概念、讲故事式自媒体短片的**默认骨架**。  
+> **原则：** 主体结构统一；**各段可裁剪/降级**，非每段都必须满配。  
+> **复用：** 新集复制同目录 [`单集文档.template.md`](./单集文档.template.md)，按本文件填段。  
+> **所属 skill：** `uc-media-0040-script` · 标准目录 `templates/`
+
+---
+
+## 1. 一句话
+
+```text
+钩子（场景+缺口）→ 历史（何以至此）→ 事实（1 个机制）
+  → 生活（1 主例）→ 边界（需要时）→ 验证（动手|演示|真图）→ 落点+下集
+```
+
+画面原则（贯穿，不是单独一大段）：**真截图 / 真 UI 优先**；插画只解释结构。
+
+---
+
+## 2. 七段定义
+
+| 代号 | 段名 | 目标（观众得到什么） | 默认时长 | 必选？ |
+|------|------|----------------------|----------|--------|
+| **H** | 钩子 | 场景 + 认知缺口：为什么要看完 | 25–35s | **必选** |
+| **T** | 历史 | ≤4 锚点，只服务「何以至此」 | 40–50s | 默认有；可 **缩/并** |
+| **F** | 事实 | **1 个**机制模型，人话 | 60–75s | **必选** |
+| **L** | 生活 | 1 主例 + 可选 1 辅 | 40–50s | **必选**（至少 1 主例） |
+| **B** | 边界 | 幻觉 / 误用 / 能力边界 | 20–30s | **按需** |
+| **V** | 验证 | 动手 \| 演示 \| 真图对照 | 30–40s | **按需**（三选一或组合） |
+| **C** | 落点 | 记住一句 + 下集钩子 | 15–25s | **必选** |
+
+合计默认约 **3:30–5:00**。压到 3′ 时优先砍 **T 与 V 时长**，不砍 H/F/L/C 的存在。
+
+---
+
+## 3. 必选 / 可裁剪规则
+
+### 3.1 硬必选（缺了不像完整单集）
+
+| 段 | 最低交付 |
+|----|----------|
+| **H** | 1 个观众已有场景 + 1 句缺口问题 |
+| **F** | 1 个机制模型（可配「名字拆开」） |
+| **L** | 1 个生活主例（辅例可删） |
+| **C** | 1 句落点；系列片加下集钩子 |
+
+### 3.2 默认可裁剪
+
+| 段 | 何时保留 | 何时缩/删 | 降级写法 |
+|----|----------|-----------|----------|
+| **T 历史** | 名词有明确「进日常」节点 | 无公开史、或纯工具操作集 | 缩成 **1 句**「从…变成你桌上的…」并进 H 或 F |
+| **B 边界** | 易神化/易误用（LLM、Agent、幻觉相关） | 纯中性术语且误用成本低 | 并入 F 末尾 1 句警告 |
+| **V 验证** | 观众 30s 内能复现或看懂 | 训练全流程等无法跟做 | 改为 **演示录屏** 或 **1 张真图对照** |
+
+### 3.3 验证段三选一（V）
+
+| 模式 | 适用 | 例子 |
+|------|------|------|
+| **动手** | 对话框/设置里能点 | 半句续写、改一句 Prompt |
+| **演示** | 环境重、需账号/装环境 | MCP 接工具、本地跑命令 |
+| **真图对照** | 重在「认界面」 | Token 用量页、上下文截断提示 |
+
+可组合：动手 20s + 真图 10s。
+
+---
+
+## 4. 时长配比（默认 4′ 片）
+
+| 段 | 占比 | 约秒 | 硬顶 |
+|----|------|------|------|
+| H | 10–15% | 25–35 | — |
+| T | 15–20% | 40–50 | **≤50s**；锚点 **≤4** |
+| F | 25–30% | 60–75 | 机制只保留 **1 个主模型** |
+| L | 15–20% | 40–50 | 主例 1；辅例 ≤1 |
+| B | 8–12% | 20–30 | 可 0 |
+| V | 10–15% | 30–40 | 可 0 或改演示 |
+| C | 5–8% | 15–25 | 落点句必须有 |
+
+**超时优先砍：** T 参数堆砌 → L 第二例子 → V 步骤数 → F 的次要比喻。
+
+---
+
+## 5. 各段写法清单（复用检查）
+
+### H · 钩子
+
+- [ ] 场景是观众**已经在做的事**（打开对话框、贴长文、看用量…）  
+- [ ] 有**认知缺口**（不是「今天讲 XXX」）  
+- [ ] 3 秒内出现本集名词或问题句  
+
+### T · 历史
+
+- [ ] 每个锚点都服务「何以进到你生活」  
+- [ ] ≤4 点；不报排行榜/参数竞赛（除非本集主题就是规模）  
+- [ ] 日期/机构可溯源（写进事实底稿）  
+
+### F · 事实
+
+- [ ] 只有 **1 条主机制**（如「猜下一个 token」）  
+- [ ] 人话优先；公式/实现细节默认不进  
+- [ ] 与 L 的例子不重复讲同一套比喻两遍  
+
+### L · 生活
+
+- [ ] 主例高共鸣、可一秒懂映射  
+- [ ] 辅例可删；不新开第三条机制  
+
+### B · 边界
+
+- [ ] 具体误用场景，不空洞「要理性」  
+- [ ] 与落点句一致（防神话）  
+
+### V · 验证
+
+- [ ] 步骤 ≤3；可静帧给观众照做  
+- [ ] 真 UI，不 AI 假界面冒充  
+
+### C · 落点
+
+- [ ] **一句**可被记住（片尾花字）  
+- [ ] 单集闭环：没看过上集也听得懂  
+- [ ] 系列：下集钩子 1 句，不剧透成长文  
+
+---
+
+## 6. 内容适配速查（本系列九站）
+
+| 主题 | T | B | V 建议 |
+|------|---|---|--------|
+| LLM | 满配 3–4 锚点 | **要**（幻觉） | 动手：续写+冷门题 |
+| 训练 | 可短 | 要（不是一次聊天就「学会」） | 演示/类比图，难动手 |
+| Token | 可短 | 可选 | 真图：用量/计数界面 |
+| Prompt | 可短 | 可选 | 动手：同一题两种写法 |
+| 上下文 | 可短 | 要（会忘/装不下） | 真图：超长贴入被截 |
+| 多模态 | 中 | 要（乱认图） | 演示：图+文同问 |
+| Agent | 中 | **要**（乱调工具） | 演示：想做看循环 |
+| MCP | 要（谁发布） | 可选 | 演示：接一个 server |
+| Skills | 要（和 prompt 区别） | 可选 | 真图：技能包/说明页 |
+
+---
+
+## 7. 目录与流水线（和 media 契约对齐）
+
+```text
+0N-主题/
+  research/事实-*.md           # 0040 向：只锁可讲事实
+  scripts/单集文档-*.md        # 按 单集文档.template 填满 v1.1
+  assets/_real-shots/          # 真截图
+  package/                     # 可选：短片 shots.json + 人审包
+```
+
+开发顺序建议（由 **uc-media-0040-script** 短集模式执行）：
+
+```text
+1. 填产品卡 + 选定段（哪些满配/缩/删）
+2. 事实底稿（口播只讲有源内容；字段见 事实.template.md）
+3. 按 H→…→C 写口播（对时长表）
+4. 分镜 + 真图清单
+5. 人审 → 配音/package/成片
+```
+
+模板路径：本 skill 包内 `templates/`（sync 后：`.claude/skills/uc-media-0040-script/templates/` 或 `.agents/skills/…`）
+
+---
+
+## 8. 版本
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| v1.1 | 2026-07-27 | 七段主体；T 硬顶；B/V 按需；验证三选一；真图贯穿 |
+| v1.0 | — | 早期：钩子-历史-事实-生活-实操-落点（实操偏强制） |
+
+升级规则：改默认配比或必选规则 → 升 v1.x；推倒七段 → v2。

package/templates/ai-tools/skills//350/207/252/345/252/222/344/275/223/uc-media-0050-design/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: uc-media-0050-design
+description: |
+  制作设计（0050）：本集 design-lock.md；优先复用跨集 design-defaults，只写本集增量。
+  触发词：设计风格、style-lock、制作技术、0050。
+---
+
+# uc-media-0050-design · 制作设计
+
+## 行为（本 skill 内聚）
+
+1. **先读跨集默认（若有）**  
+   `{project_root}/.dwy/uc-media/design-defaults.md`  
+   无则从频道档案气质 + 近集惯例推断，并可**首次**写入 defaults（用户未反对时）。  
+2. **写本集** `design-lock.md`：= defaults 引用 + **本集增量/例外**（勿整份重抄气质长文）。  
+3. **不确定不胡编**：工厂只写 **偏好** / `undecided`；最终以 **0080 人选** 为准。
+
+**硬停：** 人审前不进 0060。  
+**flow `fast`：** 本步确认后可连跑 0060，在 0070 再停（见 flow 硬停表）。
+
+---
+
+## 大步骤契约
+
+| 项 | 内容 |
+|----|------|
+| **序** | 0050 |
+| **stage** | `design` |
+| **目录** | `{work_dir}/0050-design/` |
+| **主文档** | **`design-lock.md`** |
+| **上游** | `0040-script` 已人审；频道档案；可选 `design-defaults.md` |
+| **风格扩展** | `uc-media-comic-kit` / `uc-media-knowledge-town`（若项目采用，按各自 skill 挂载） |
+| **不做** | 批量生图；替用户最终锁定工厂 |
+
+### design-lock 要点
+
+- `style_id` / 气质 / 禁止项（可写「同 design-defaults」）  
+- `production_stack` **偏好**：`remotion` | `hyperframe` | `undecided`  
+  - 若 defaults 已有默认工厂偏好，本集只写覆盖  
+- `asset_model` / 字幕安全区 / comic-kit 与否  
+- 本集例外表（仅本集）  
+- 签字：可进 0060  
+
+### 跨集 design-defaults（可选，建议）
+
+路径：`.dwy/uc-media/design-defaults.md`  
+
+| 块 | 内容 |
+|----|------|
+| 默认 style_id / 气质关键词 | 与频道档案对齐 |
+| 默认 production_stack 偏好 | |
+| 禁止项 / 字幕安全区 | |
+| 风格 skill | comic-kit / knowledge-town / 无 |
+
+刷新：用户说「更新设计默认 / 重设画风默认」。  

package/templates/ai-tools/skills//350/207/252/345/252/222/344/275/223/uc-media-0060-assets/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: uc-media-0060-assets
+description: |
+  素材（0060）：0060-assets/素材清单.md + files/。触发词：素材、配图、生图、logo、0060。
+---
+
+# uc-media-0060-assets · 素材
+
+## 行为（本 skill 内聚）
+
+1. **能自动的全部自动**：按脚本镜号 + design-lock 生成完整 `素材清单.md`；能从 `shared/icons` 定位的 logo 先填好。  
+2. **产出可改终稿**：用户改 method、补 `user_provided` 即可。  
+3. **不确定不胡编**：找不到的官方 Logo 不 AI 乱画当真标；路径不存在标 `missing`。
+
+---
+
+## 大步骤契约
+
+| 项 | 内容 |
+|----|------|
+| **序** | 0060 |
+| **stage** | `assets` |
+| **目录** | `{work_dir}/0060-assets/` |
+| **主文档** | **`素材清单.md`** |
+| **媒体** | `files/**` |
+| **上游** | `0050-design/design-lock.md` + `0040-script/脚本-*.md` |
+| **禁止** | 每镜一篇说明 md 当真源 |
+
+清单表含：shot_id / 层 / method / 路径 / 就绪；支持 `user_provided`。  

package/templates/ai-tools/skills//350/207/252/345/252/222/344/275/223/uc-media-0070-package/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: uc-media-0070-package
+description: |
+  成片包（0070）：0070-package/成片包.md + shots.json。工厂入口。
+  触发词：package、成片包、对轨冻结、0070。
+---
+
+# uc-media-0070-package · 成片包
+
+**Schema：** [`shots.schema.json`](./shots.schema.json)  
+**模板：** [`成片包.template.md`](./成片包.template.md)  
+**说明：** [`人审说明.md`](./人审说明.md)
+
+## 行为（本 skill 内聚）
+
+1. **能自动的全部自动**：从脚本 + design-lock + 素材清单组装 `成片包.md` + `shots.json`，并跑 validate。
+2. **产出可改终稿**：人审改时长/vo 后重校验。
+3. **不确定不胡编**：上游缺失不猜秒数、不编 vo。  
+
+使用 `knowledge-town-paper-film-v1` 时，另产出 `cue-timeline.json` 作为字幕、旁白、视觉动作与 SFX 的唯一对轨真源；`shots.json` 写入 `cue_timeline_file` 和每镜 `cue_ids`，但不复制或改写 cue 时码。
+
+**本步硬停：** 人审通过前不进 0080。
+
+---
+
+## 大步骤契约
+
+| 项 | 内容 |
+|----|------|
+| **序** | 0070 |
+| **stage** | `package` |
+| **目录** | `{work_dir}/0070-package/` |
+| **人读** | **`成片包.md`** |
+| **机读** | **`shots.json`** |
+| **上游** | 脚本 + design-lock + `0060-assets/素材清单.md` |
+| **下游** | 0080-factory |
+
+```bash
+# 脚本相对本 skill 包（sync 后：.claude/skills/uc-media-0070-package/ 或 .agents/skills/…）
+python3 scripts/validate_shots.py \
+  "{work_dir}/0070-package/shots.json"
+```

package/templates/ai-tools/skills//350/207/252/345/252/222/344/275/223/uc-media-0070-package/scripts/validate_shots.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Validate media package shots.json (schema version 1).
+
+Usage:
+  python validate_shots.py path/to/shots.json
+  python validate_shots.py path/to/package/   # reads shots.json inside
+
+Exit 0 = ok; 1 = validation errors; 2 = usage/io error.
+Does not require jsonschema package: checks the critical contract rules inline.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+import sys
+from pathlib import Path
+
+SHOT_ID_RE = re.compile(r"^[A-Z][0-9]{2}$")
+PRESETS = {
+    "hold",
+    "fade_up",
+    "scale_in",
+    "draw_on",
+    "highlight_pulse",
+    "slide_in",
+    "crossfade",
+}
+
+
+def load_package(path: Path) -> tuple[dict, Path]:
+    if path.is_dir():
+        path = path / "shots.json"
+    if not path.is_file():
+        raise FileNotFoundError(f"shots.json not found: {path}")
+    with path.open(encoding="utf-8") as f:
+        data = json.load(f)
+    return data, path
+
+
+def validate(data: dict, fps_tol: float = 0.51) -> list[str]:
+    errs: list[str] = []
+
+    if data.get("version") != 1:
+        errs.append(f"version must be 1, got {data.get('version')!r}")
+
+    for key in ("fps", "width", "height", "chapters", "shots"):
+        if key not in data:
+            errs.append(f"missing top-level field: {key}")
+
+    if errs:
+        return errs
+
+    fps = data["fps"]
+    if not isinstance(fps, (int, float)) or fps <= 0:
+        errs.append(f"fps must be > 0, got {fps!r}")
+
+    chapters = data.get("chapters") or []
+    shots = data.get("shots") or []
+    if not isinstance(chapters, list) or len(chapters) < 1:
+        errs.append("chapters must be a non-empty array")
+    if not isinstance(shots, list) or len(shots) < 1:
+        errs.append("shots must be a non-empty array")
+        return errs
+
+    shot_by_id: dict[str, dict] = {}
+    for i, s in enumerate(shots):
+        if not isinstance(s, dict):
+            errs.append(f"shots[{i}] not an object")
+            continue
+        sid = s.get("shot_id")
+        if not sid or not isinstance(sid, str) or not SHOT_ID_RE.match(sid):
+            errs.append(f"shots[{i}].shot_id invalid: {sid!r} (expect A00-style)")
+        else:
+            if sid in shot_by_id:
+                errs.append(f"duplicate shot_id: {sid}")
+            shot_by_id[sid] = s
+
+        for req in (
+            "chapter_id",
+            "order",
+            "vo_text",
+            "duration_sec",
+            "duration_frames",
+        ):
+            if req not in s:
+                errs.append(f"shot {sid or i}: missing {req}")
+
+        vo = s.get("vo_text")
+        if not isinstance(vo, str) or not vo.strip():
+            errs.append(f"shot {sid or i}: vo_text empty")
+
+        sec = s.get("duration_sec")
+        frames = s.get("duration_frames")
+        if isinstance(sec, (int, float)) and sec <= 0:
+            errs.append(f"shot {sid}: duration_sec must be > 0")
+        if isinstance(frames, int) and frames <= 0:
+            errs.append(f"shot {sid}: duration_frames must be > 0")
+        if (
+            isinstance(sec, (int, float))
+            and isinstance(frames, int)
+            and isinstance(fps, (int, float))
+            and fps > 0
+            and sec > 0
+        ):
+            expected = round(sec * fps)
+            if abs(expected - frames) > fps_tol:
+                errs.append(
+                    f"shot {sid}: duration_frames={frames} != round(sec*fps)={expected}"
+                )
+
+        motion = s.get("motion") or {}
+        if isinstance(motion, dict):
+            preset = motion.get("preset")
+            if preset is not None and preset not in PRESETS:
+                errs.append(f"shot {sid}: unknown motion.preset {preset!r}")
+
+        builds = s.get("builds_on")
+        if builds and isinstance(builds, str) and builds not in shot_by_id and builds:
+            # may appear later in list; check after pass
+            pass
+
+        assets = s.get("assets")
+        if assets is not None:
+            if not isinstance(assets, list):
+                errs.append(f"shot {sid}: assets must be array")
+            else:
+                for j, a in enumerate(assets):
+                    if not isinstance(a, dict):
+                        errs.append(f"shot {sid} assets[{j}] not object")
+                        continue
+                    if a.get("type_only"):
+                        continue
+                    if not a.get("role") or not a.get("path"):
+                        errs.append(
+                            f"shot {sid} assets[{j}]: need role+path (or type_only)"
+                        )
+
+    # builds_on integrity (after all ids known)
+    for sid, s in shot_by_id.items():
+        builds = s.get("builds_on")
+        if builds in (None, "", "null"):
+            continue
+        if isinstance(builds, str) and builds not in shot_by_id:
+            errs.append(f"shot {sid}: builds_on {builds!r} not in shots")
+
+    # chapters vs shots
+    chapter_ids = set()
+    for ci, ch in enumerate(chapters):
+        if not isinstance(ch, dict):
+            errs.append(f"chapters[{ci}] not an object")
+            continue
+        cid = ch.get("chapter_id")
+        if not cid:
+            errs.append(f"chapters[{ci}]: missing chapter_id")
+        else:
+            chapter_ids.add(cid)
+        ids = ch.get("shot_ids") or []
+        if not ids:
+            errs.append(f"chapter {cid}: shot_ids empty")
+        for sid in ids:
+            if sid not in shot_by_id:
+                errs.append(f"chapter {cid}: shot_id {sid} missing from shots[]")
+
+    for sid, s in shot_by_id.items():
+        cid = s.get("chapter_id")
+        if cid and chapter_ids and cid not in chapter_ids:
+            errs.append(f"shot {sid}: chapter_id {cid!r} not in chapters")
+
+    # optional totals
+    if "total_duration_frames" in data and shot_by_id:
+        sum_f = sum(
+            s.get("duration_frames", 0)
+            for s in shot_by_id.values()
+            if isinstance(s.get("duration_frames"), int)
+        )
+        if data["total_duration_frames"] != sum_f:
+            errs.append(
+                f"total_duration_frames={data['total_duration_frames']} != sum shots {sum_f}"
+            )
+
+    return errs
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print(__doc__.strip(), file=sys.stderr)
+        return 2
+    try:
+        data, path = load_package(Path(argv[1]))
+    except Exception as e:
+        print(f"IO error: {e}", file=sys.stderr)
+        return 2
+
+    errs = validate(data)
+    if errs:
+        print(f"FAIL {path} ({len(errs)} error(s))")
+        for e in errs:
+            print(f"  - {e}")
+        return 1
+    n = len(data.get("shots") or [])
+    print(f"OK {path}  version=1  shots={n}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))