dsh-drawai 0.4.2 → 0.4.4

package/lib/motion/shotcraft/upstream/references/guided-free-creation.md

@@ -1,199 +1,199 @@
-# guided-free-creation — 共同创作引导流程
-
-共同创作模式用于用户希望参与产品短片的关键业务与创意决策。它把产品简报、
-需求决策、视觉方向、镜头映射和最终分镜交给用户确认，把视频工程细节交给
-Agent 执行。自主自由创作不读本文件，也不使用这里的逐阶段确认节点。
-
-## 目录
-
-- 产品简报与安全素材预检
-- 需求到执行决策表
-- 视觉方向与 styleframe
-- 功能到镜头映射
-- Gallery 镜头名称解析
-- 分镜确认与制作放行
-
-## 1. 产品简报
-
-先只读检查项目，不写视频代码、不修改业务项目、不采集或导出敏感内容。检查技术栈、
-入口、启动命令、页面路由、主要组件、交互状态、API、页面文案、CSS 视觉 token、
-外部依赖和数据风险，并判断哪些功能能通过真实页面状态清楚表达。
-
-输出一张由 Agent 先填写的产品简报表。每一行都必须先给出判断或推荐，
-再写明依据；不要把所有字段原样丢给用户填写。
-
-```text
-当前阶段：产品理解
-
-| 项目 | Agent 的判断或推荐 | 依据 |
-|---|---|---|
-| 项目定位 |  |  |
-| 目标用户 |  |  |
-| 视频用途 |  |  |
-| 核心卖点 |  |  |
-| 必须展示的功能 |  |  |
-| 可用页面/状态 |  |  |
-| 首屏主张 |  |  |
-| 期望时长/画幅/语言 |  |  |
-| 音乐/配音 |  |  |
-| 数据合规口径 |  |  |
-| 视觉线索 |  |  |
-
-需要确认：
-1. 只列出无法从项目或用户已有描述中确定的事项。
-2. 对可以推荐但仍需用户拍板的事项，先写“推荐方案＋依据”，再在此处提问。
-```
-
-填写规则：
-
-- 能从 README、源码、路由、页面状态、文案或 computed styles 确定的，直接填写
-  判断和证据，不再询问；
-- 无法完全确定但可以根据项目合理推荐的，填写动态推荐、推荐依据和需要用户
-  拍板的选项；
-- 完全无法判断的，明确写“无法从当前材料判断”，只把它放到下方问题中；
-- 每轮只追问 1–3 个最影响视频结果的问题；不显示“置信度”字段；
-- 推荐必须来自当前上传项目或页面，不得使用固定答案。
-
-用户确认简报后，先按数据口径进行一次**临时安全素材预检**：只采集制作
-styleframe 所需的少量页面截图或 token，不做完整切片、全量导出或最终素材入库。
-公开演示数据只有在简报明确确认后可保留；客户、个人、内部、密钥、实时或其他
-敏感数据必须先替换、脱敏或冻结。已经明确提供的信息不要重复询问。
-
-## 2. 需求到执行决策表
-
-把已确认的用户需求、项目证据和 Agent 的执行选择写成同一张可追溯表。它不是
-固定的“受众→风格”规则表：每行都必须写明当前项目与用户材料带来的依据，
-并允许 Agent 提出与常见套路不同的推荐。
-
-```text
-当前阶段：从需求到制作决策
-
-| 已确认需求 | 项目/用户依据 | 受影响的执行范围 | Agent 推荐 | 需要确认项 |
-|---|---|---|---|---|
-| 视频用途 |  | 叙事结构、信息量、CTA |  |  |
-| 目标受众及其情境 |  | 场景、语言、节奏、功能优先级 |  |  |
-| 核心卖点与必须展示功能 |  | 页面状态、镜头、文案 |  |  |
-| 时长/画幅/语言 |  | 镜头数、字幕密度、构图 |  |  |
-| 音乐/配音 |  | 节奏、停顿、SFX 留白 |  |  |
-| 数据合规口径 |  | 采集、mock、打码、终检 |  |  |
-| 视觉方向 |  | tokens、材质、转场语气 |  |  |
-```
-
-表只记录对当前视频会产生实际影响的项。无法确定的项保留在“需要确认项”，
-每轮合计只问 1–3 个；已经确认的项不得再次提问。后续的视觉方向、镜头映射、
-分镜、素材采集、声音设计与终检都必须能追溯回此表，并在设计 spec 中保存。
-
-## 3. 视觉方向
-
-从页面、源码或 computed styles 提取字体、色板、圆角、信息密度、光感和动效
-性格。视觉方向分两轮确认：
-
-1. 先给出最多 3 个根据当前项目生成的文字方向。每个方向说明：名称、一句话
-   视觉主张、3–5 个关键词、字体/色彩/材质、镜头运动性格、适合原因和取舍。
-   只有产品确实适合纸张、编辑部或叙事质感时，才把 Ink Press 列为候选；不能
-   因为仓库里有它就固定加入。
-2. 用户选出 1–2 个入围方向，或明确授权 Agent 自选。对入围方向制作一个纯
-   HTML/CSS 的实际 styleframe 对比页：每个方向展示 2–3 张 1920×1080 的
-   静态关键画面（例如品牌开场、核心功能、品牌收尾），使用当前产品的真实
-   页面素材或已提取的视觉 token，不写 Remotion 代码、不渲染完整视频。
-3. 用 Playwright/Puppeteer 截出 styleframe 对比图，展示并列方向的字体、色板、
-   材质、构图、光感和信息密度。用户确认最终方向后，才能进入功能到镜头映射。
-
-Styleframe 用来确认静态视觉语言，不能单独证明缓动、运镜速度或节奏；这些仍需
-结合动效 tokens、Gallery 参考样片判断。若动效差异无法靠文字和样片判断，再做
-短的运动测试。用户已经提供严格品牌规范、明确参考片、直接选定 Ink Press，或
-明确授权 Agent 自选并跳过视觉确认时，可以记录理由后跳过 styleframe 对比。
-
-## 4. 功能到镜头映射
-
-先列产品功能，再扫描 `references/shots/` 各卡 frontmatter 的用途、能量、建议
-时长和限制。给每个必须展示的功能推荐首选和备选镜头：
-
-| 功能 | 首选镜头 | 备选镜头 | 画面要表达什么 | 需要的页面状态 |
-|---|---|---|---|---|
-
-用户可以接受、替换、删除或授权 Agent 自选。确定映射后，必须完整读取选中卡片，
-并按其“参考实现”定位准确 demo 源码；没有合适镜头时可以新写，但要说明新写范围
-和验证风险。Gallery 标为“仅供参考，需要自定义实现”的样式不默认推荐；用户明确
-点名后才允许自定义实现，并把风险写进设计 spec。
-
-这张映射表不是完整分镜，不得在用户确认映射后直接开始制作。它只确定“哪个
-产品功能使用哪一种镜头语法”，之后还必须进入第 5 节，展开镜头顺序、时长、
-页面状态、具体动作、素材、字幕、转场和声音。
-
-## 5. Gallery 镜头名称解析
-
-Gallery（https://vincentwei1021.github.io/video-shotcraft/）只是用户浏览和挑选
-动态样片的界面，镜头定义和实现源码已经包含在本仓库。用户不需要描述动画，
-只需复制并提供镜头名。
-
-收到镜头名后按以下顺序处理：
-
-1. 读取 `gallery/api/library.json`，用其中的 `cards[].name` 校验 `card-name`，
-   用该卡的 `styles[].key` 校验 `style-key`；不要用模糊猜测代替索引校验；
-2. 用索引中的 `source` 定位并完整读取 `references/shots/*.md`；
-3. 按卡片“参考实现”的明确路径，把具体样式解析到准确的 demo TSX；若文档只写
-   demo 目录，读取目录文件并根据导出名、注释和样式语义确定对应文件；
-4. 将索引中的 `styles[].media.url` 解析为参考样片（本地 `gallery/media/`
-   若无 mp4，先跑 `gallery/fetch-media.sh` 从 release 拉取，或直接用在线
-   Gallery 对应链接），并在设计 spec 记录：卡名、style-key、卡片文档、
-   准确 demo TSX、参考样片；
-5. 如卡片需要通用组件，再读取并复制 `assets/lib/` 的对应文件；
-6. 保留 demo 中已经调校的缓动、时值配比、遮罩时机和“已知坑/命门”参数；
-7. 只替换目标产品的截图、布局坐标、文案、品牌 token 和必要的构图参数。
-
-Gallery 可能复制出两种形式：
-
-```text
-spotlight-hero-card
-shot-transitions · whip-pan
-```
-
-- 只有卡名：使用卡片默认变体；如果同一卡的多个变体表达差异明显，Agent 先按
-  前后镜头和产品气质推荐一个具体变体，并说明原因，必要时让用户确认。
-- `卡名 · 样式名`：优先使用用户点名的具体变体，读取对应实现，不擅自换式。
-- 名称不存在：报告无法匹配，并给出仓库中最接近的真实卡名；不要凭名字臆造。
-- 索引标为“仅供参考，需要自定义实现”：不主动推荐；用户明确点名后，明确说明
-  该样式没有可复用的完整实现，按配方参数和参考样片制作，并把实现风险写进设计 spec。
-- 索引标为“缺少预览”：可读取准确源码并用于制作，但不得声称已对照动态样片。
-
-严禁只根据卡名含义重新写一套近似动画。卡片文件提供语义，demo 源码才是参数
-真相。用户选中多个镜头后，把它们与产品功能映射，再继续生成完整分镜。
-
-## 6. 分镜确认
-
-把确认的功能和镜头组合成分镜，并至少包含：
-
-```text
-| # | 时间/帧 | 功能信息 | 镜头卡 | 主动作 | 素材来源 | 字幕/SFX |
-```
-
-检查每镜只讲一个主要动效，品牌字标 hold 至少 1 秒，批量动效收尾至少静止
-0.5 秒，避免重复 tagline 或让同一种动效反复当主角。用户确认分镜与最终设计 spec
-后，二者共同构成**制作放行**：不重新打开此前已确认的业务或创意问题，只补实现
-必要的未决项。此时再做最终全量素材采集（整页 2x 截图、元素切片、layout.json），
-把批准分镜转成帧级时间轴，再进入 `pipeline.md` 阶段 4 的最终素材采集、阶段 5
-逐镜头实现、阶段 6 声音设计和阶段 7 终检。
-
-将用户确认后的产品简报、需求到执行决策表、视觉方向/tokens、styleframe 或跳过理由、
-功能到镜头映射、Gallery 卡名与具体变体、最终分镜和数据合规口径保存为稳定的设计 spec
-（或在终检交接时完整提供），作为 `final-review.md` 的审查基准。不要让独立
-审查 Agent 依赖零散聊天记录猜测用户确认过什么。
-
-## 默认与跳过规则
-
-用户授权 Agent 全权决定时，仍须根据产品内容动态推导：从视觉 token 生成方向，
-从核心功能与页面状态选择镜头，从发布渠道、功能数量和阅读密度推荐时长/画幅/
-语言，从品牌能量与节奏推荐音乐。只有项目和用户描述都没有相关线索时，才使用
-30–38 秒、1920×1080 作为兜底。数据口径按项目风险决定：公开演示数据可沿用，
-客户、个人或内部数据改用虚构/脱敏内容。首次整片渲染前仍需提交分镜备案，除非
-用户明确要求不看中间产物。
-
-## 每轮回复格式
-
-```text
-当前阶段：
-已确认：
-本轮需要确认：
-确认后交付：
-```
+# guided-free-creation — 共同创作引导流程
+
+共同创作模式用于用户希望参与产品短片的关键业务与创意决策。它把产品简报、
+需求决策、视觉方向、镜头映射和最终分镜交给用户确认，把视频工程细节交给
+Agent 执行。自主自由创作不读本文件，也不使用这里的逐阶段确认节点。
+
+## 目录
+
+- 产品简报与安全素材预检
+- 需求到执行决策表
+- 视觉方向与 styleframe
+- 功能到镜头映射
+- Gallery 镜头名称解析
+- 分镜确认与制作放行
+
+## 1. 产品简报
+
+先只读检查项目，不写视频代码、不修改业务项目、不采集或导出敏感内容。检查技术栈、
+入口、启动命令、页面路由、主要组件、交互状态、API、页面文案、CSS 视觉 token、
+外部依赖和数据风险，并判断哪些功能能通过真实页面状态清楚表达。
+
+输出一张由 Agent 先填写的产品简报表。每一行都必须先给出判断或推荐，
+再写明依据；不要把所有字段原样丢给用户填写。
+
+```text
+当前阶段：产品理解
+
+| 项目 | Agent 的判断或推荐 | 依据 |
+|---|---|---|
+| 项目定位 |  |  |
+| 目标用户 |  |  |
+| 视频用途 |  |  |
+| 核心卖点 |  |  |
+| 必须展示的功能 |  |  |
+| 可用页面/状态 |  |  |
+| 首屏主张 |  |  |
+| 期望时长/画幅/语言 |  |  |
+| 音乐/配音 |  |  |
+| 数据合规口径 |  |  |
+| 视觉线索 |  |  |
+
+需要确认：
+1. 只列出无法从项目或用户已有描述中确定的事项。
+2. 对可以推荐但仍需用户拍板的事项，先写“推荐方案＋依据”，再在此处提问。
+```
+
+填写规则：
+
+- 能从 README、源码、路由、页面状态、文案或 computed styles 确定的，直接填写
+  判断和证据，不再询问；
+- 无法完全确定但可以根据项目合理推荐的，填写动态推荐、推荐依据和需要用户
+  拍板的选项；
+- 完全无法判断的，明确写“无法从当前材料判断”，只把它放到下方问题中；
+- 每轮只追问 1–3 个最影响视频结果的问题；不显示“置信度”字段；
+- 推荐必须来自当前上传项目或页面，不得使用固定答案。
+
+用户确认简报后，先按数据口径进行一次**临时安全素材预检**：只采集制作
+styleframe 所需的少量页面截图或 token，不做完整切片、全量导出或最终素材入库。
+公开演示数据只有在简报明确确认后可保留；客户、个人、内部、密钥、实时或其他
+敏感数据必须先替换、脱敏或冻结。已经明确提供的信息不要重复询问。
+
+## 2. 需求到执行决策表
+
+把已确认的用户需求、项目证据和 Agent 的执行选择写成同一张可追溯表。它不是
+固定的“受众→风格”规则表：每行都必须写明当前项目与用户材料带来的依据，
+并允许 Agent 提出与常见套路不同的推荐。
+
+```text
+当前阶段：从需求到制作决策
+
+| 已确认需求 | 项目/用户依据 | 受影响的执行范围 | Agent 推荐 | 需要确认项 |
+|---|---|---|---|---|
+| 视频用途 |  | 叙事结构、信息量、CTA |  |  |
+| 目标受众及其情境 |  | 场景、语言、节奏、功能优先级 |  |  |
+| 核心卖点与必须展示功能 |  | 页面状态、镜头、文案 |  |  |
+| 时长/画幅/语言 |  | 镜头数、字幕密度、构图 |  |  |
+| 音乐/配音 |  | 节奏、停顿、SFX 留白 |  |  |
+| 数据合规口径 |  | 采集、mock、打码、终检 |  |  |
+| 视觉方向 |  | tokens、材质、转场语气 |  |  |
+```
+
+表只记录对当前视频会产生实际影响的项。无法确定的项保留在“需要确认项”，
+每轮合计只问 1–3 个；已经确认的项不得再次提问。后续的视觉方向、镜头映射、
+分镜、素材采集、声音设计与终检都必须能追溯回此表，并在设计 spec 中保存。
+
+## 3. 视觉方向
+
+从页面、源码或 computed styles 提取字体、色板、圆角、信息密度、光感和动效
+性格。视觉方向分两轮确认：
+
+1. 先给出最多 3 个根据当前项目生成的文字方向。每个方向说明：名称、一句话
+   视觉主张、3–5 个关键词、字体/色彩/材质、镜头运动性格、适合原因和取舍。
+   只有产品确实适合纸张、编辑部或叙事质感时，才把 Ink Press 列为候选；不能
+   因为仓库里有它就固定加入。
+2. 用户选出 1–2 个入围方向，或明确授权 Agent 自选。对入围方向制作一个纯
+   HTML/CSS 的实际 styleframe 对比页：每个方向展示 2–3 张 1920×1080 的
+   静态关键画面（例如品牌开场、核心功能、品牌收尾），使用当前产品的真实
+   页面素材或已提取的视觉 token，不写 Remotion 代码、不渲染完整视频。
+3. 用 Playwright/Puppeteer 截出 styleframe 对比图，展示并列方向的字体、色板、
+   材质、构图、光感和信息密度。用户确认最终方向后，才能进入功能到镜头映射。
+
+Styleframe 用来确认静态视觉语言，不能单独证明缓动、运镜速度或节奏；这些仍需
+结合动效 tokens、Gallery 参考样片判断。若动效差异无法靠文字和样片判断，再做
+短的运动测试。用户已经提供严格品牌规范、明确参考片、直接选定 Ink Press，或
+明确授权 Agent 自选并跳过视觉确认时，可以记录理由后跳过 styleframe 对比。
+
+## 4. 功能到镜头映射
+
+先列产品功能，再扫描 `references/shots/` 各卡 frontmatter 的用途、能量、建议
+时长和限制。给每个必须展示的功能推荐首选和备选镜头：
+
+| 功能 | 首选镜头 | 备选镜头 | 画面要表达什么 | 需要的页面状态 |
+|---|---|---|---|---|
+
+用户可以接受、替换、删除或授权 Agent 自选。确定映射后，必须完整读取选中卡片，
+并按其“参考实现”定位准确 demo 源码；没有合适镜头时可以新写，但要说明新写范围
+和验证风险。Gallery 标为“仅供参考，需要自定义实现”的样式不默认推荐；用户明确
+点名后才允许自定义实现，并把风险写进设计 spec。
+
+这张映射表不是完整分镜，不得在用户确认映射后直接开始制作。它只确定“哪个
+产品功能使用哪一种镜头语法”，之后还必须进入第 5 节，展开镜头顺序、时长、
+页面状态、具体动作、素材、字幕、转场和声音。
+
+## 5. Gallery 镜头名称解析
+
+Gallery（https://vincentwei1021.github.io/video-shotcraft/）只是用户浏览和挑选
+动态样片的界面，镜头定义和实现源码已经包含在本仓库。用户不需要描述动画，
+只需复制并提供镜头名。
+
+收到镜头名后按以下顺序处理：
+
+1. 读取 `gallery/api/library.json`，用其中的 `cards[].name` 校验 `card-name`，
+   用该卡的 `styles[].key` 校验 `style-key`；不要用模糊猜测代替索引校验；
+2. 用索引中的 `source` 定位并完整读取 `references/shots/*.md`；
+3. 按卡片“参考实现”的明确路径，把具体样式解析到准确的 demo TSX；若文档只写
+   demo 目录，读取目录文件并根据导出名、注释和样式语义确定对应文件；
+4. 将索引中的 `styles[].media.url` 解析为参考样片（本地 `gallery/media/`
+   若无 mp4，先跑 `gallery/fetch-media.sh` 从 release 拉取，或直接用在线
+   Gallery 对应链接），并在设计 spec 记录：卡名、style-key、卡片文档、
+   准确 demo TSX、参考样片；
+5. 如卡片需要通用组件，再读取并复制 `assets/lib/` 的对应文件；
+6. 保留 demo 中已经调校的缓动、时值配比、遮罩时机和“已知坑/命门”参数；
+7. 只替换目标产品的截图、布局坐标、文案、品牌 token 和必要的构图参数。
+
+Gallery 可能复制出两种形式：
+
+```text
+spotlight-hero-card
+shot-transitions · whip-pan
+```
+
+- 只有卡名：使用卡片默认变体；如果同一卡的多个变体表达差异明显，Agent 先按
+  前后镜头和产品气质推荐一个具体变体，并说明原因，必要时让用户确认。
+- `卡名 · 样式名`：优先使用用户点名的具体变体，读取对应实现，不擅自换式。
+- 名称不存在：报告无法匹配，并给出仓库中最接近的真实卡名；不要凭名字臆造。
+- 索引标为“仅供参考，需要自定义实现”：不主动推荐；用户明确点名后，明确说明
+  该样式没有可复用的完整实现，按配方参数和参考样片制作，并把实现风险写进设计 spec。
+- 索引标为“缺少预览”：可读取准确源码并用于制作，但不得声称已对照动态样片。
+
+严禁只根据卡名含义重新写一套近似动画。卡片文件提供语义，demo 源码才是参数
+真相。用户选中多个镜头后，把它们与产品功能映射，再继续生成完整分镜。
+
+## 6. 分镜确认
+
+把确认的功能和镜头组合成分镜，并至少包含：
+
+```text
+| # | 时间/帧 | 功能信息 | 镜头卡 | 主动作 | 素材来源 | 字幕/SFX |
+```
+
+检查每镜只讲一个主要动效，品牌字标 hold 至少 1 秒，批量动效收尾至少静止
+0.5 秒，避免重复 tagline 或让同一种动效反复当主角。用户确认分镜与最终设计 spec
+后，二者共同构成**制作放行**：不重新打开此前已确认的业务或创意问题，只补实现
+必要的未决项。此时再做最终全量素材采集（整页 2x 截图、元素切片、layout.json），
+把批准分镜转成帧级时间轴，再进入 `pipeline.md` 阶段 4 的最终素材采集、阶段 5
+逐镜头实现、阶段 6 声音设计和阶段 7 终检。
+
+将用户确认后的产品简报、需求到执行决策表、视觉方向/tokens、styleframe 或跳过理由、
+功能到镜头映射、Gallery 卡名与具体变体、最终分镜和数据合规口径保存为稳定的设计 spec
+（或在终检交接时完整提供），作为 `final-review.md` 的审查基准。不要让独立
+审查 Agent 依赖零散聊天记录猜测用户确认过什么。
+
+## 默认与跳过规则
+
+用户授权 Agent 全权决定时，仍须根据产品内容动态推导：从视觉 token 生成方向，
+从核心功能与页面状态选择镜头，从发布渠道、功能数量和阅读密度推荐时长/画幅/
+语言，从品牌能量与节奏推荐音乐。只有项目和用户描述都没有相关线索时，才使用
+30–38 秒、1920×1080 作为兜底。数据口径按项目风险决定：公开演示数据可沿用，
+客户、个人或内部数据改用虚构/脱敏内容。首次整片渲染前仍需提交分镜备案，除非
+用户明确要求不看中间产物。
+
+## 每轮回复格式
+
+```text
+当前阶段：
+已确认：
+本轮需要确认：
+确认后交付：
+```