dsh-drawai 0.4.2 → 0.4.4

package/lib/motion/shotcraft/upstream/references/publish-upload-post.md

@@ -1,111 +1,111 @@
-# 发布到社交平台：成片 → TikTok / Instagram / YouTube / LinkedIn / X …
-
-把交付的 MP4 一次发到 TikTok、Instagram（Reels 或 Stories）、YouTube（含 Shorts）、
-LinkedIn、Facebook、X、Threads、Pinterest、Bluesky，可立即发布或定时发布。
-脚本 `publish/upload_post.py`，通过 [Upload-Post](https://upload-post.com) API 完成，
-只用 Python 标准库（无需 venv / pip）。
-
-**触发时机**：只在用户**主动要求**把成片发到社交平台时执行（例如"帮我发到
-TikTok 和 YouTube"）。它不是交付收尾 1-2-3 之外的第 4 条推荐，不要主动推销。
-发布是公开且难以撤回的操作，**必须先让用户确认文案和平台清单**，再真正发布。
-
-> **说明**：Upload-Post 是第三方托管服务。免费版每月 10 次上传，覆盖上面除
-> TikTok 以外的全部平台（TikTok 需付费版）。只有用户配置了自己的 API key 时
-> 本流程才会联网。
-
-## 1. 一次性准备（用户操作）
-
-1. 在 https://upload-post.com 注册，创建一个 profile，把要发的社交账号连到这个 profile。
-2. 在后台创建 API key。
-3. 设置环境变量（或写进用户自己的 shell 配置）：
-
-```bash
-export UPLOAD_POST_API_KEY=...
-export UPLOAD_POST_USER=<profile 名>
-```
-
-缺这两个变量时，告诉用户以上三步，停下等待，不要尝试发布。
-
-## 2. 选文件与准备文案
-
-- **文件**：用交付的成片。配了 BGM 的片子有两版（带 BGM / 无 BGM），默认发
-  **带 BGM 版**；用户另有要求按用户的来。
-- **画幅**：TikTok、Reels、Shorts 要竖屏 9:16。成片是横屏 16:9 时如实告诉用户
-  （这些平台会加黑边或裁切），建议改发 YouTube / LinkedIn / X / Facebook，或另渲
-  一版竖屏。
-- **文案 `--title`**：在 TikTok / Instagram / X / Threads 上就是正文，按社交文案写
-  （钩子一句 + 2–4 个话题标签），不要写成 YouTube 标题。含 YouTube 时 ≤100 字符。
-  交付收尾第 1 条里用户若同意 @ 作者，把那句放进文案。
-- **长描述 `--description`**：YouTube / LinkedIn / Facebook / Pinterest 用。
-- **AI 声明 `--ai-generated`**：询问用户是否标注 AI 生成内容。成片由 Agent 以代码
-  渲染，一般不属于"逼真的合成影像"，默认不标；用了 AI 生成画面或 AI 配音时建议标。
-
-把「文案 + 描述 + 平台清单 + 定时（如有）+ 各平台隐私设置」整理给用户，
-**得到明确确认后**再进入下一步。
-
-## 3. 先 dry-run（不发布）
-
-```bash
-python3 publish/upload_post.py --video out/promo.mp4 --title "<文案>" \
-  --description "<长描述>" --platforms tiktok,instagram,youtube --dry-run --json-out
-```
-
-检查输出：`authOk` 为 `true`；`missingPlatforms` 非空说明这些平台没连到 profile，
-会被跳过，告诉用户去后台连接，或从清单里去掉。
-
-## 4. 发布
-
-去掉 `--dry-run` 重跑。脚本等待各平台结果（默认最多 10 分钟），逐平台输出链接或错误。
-
-- **每条发布命令只跑一次。** 无论超时、断网、报错还是 `status: "unknown"`，都**不要
-  重跑发布命令**，重跑会生成新的 request_id，同一视频会被发两次。只能查询：
-  `python3 publish/upload_post.py --status <requestId> --json-out`
-- 脚本如何区分：只有 **400 / 401 / 403 / 422**（服务端受理前明确拒绝）才判失败，此时
-  没有任何东西被发出去，修正参数后可以再发。5xx、网关错误、超时、断网、2xx 却无有效
-  JSON 都属于"不确定"，视频可能已被受理。脚本会自动用同一个 request_id 查询：查到就
-  照常继续；仍无法确认则输出 `status: "unknown"`（退出码 2）、`requestId` 和
-  `statusCommand`，并带 `doNotRerun: true`。
-- 脚本在**发送之前**就把 `request_id` 和对应的 `--status` 命令打到 stderr。进程中途
-  被中断时，用这条命令查询，不要重跑发布。
-- 定时发布（`--schedule 2026-10-01T09:00:00 --timezone Asia/Shanghai`）立即返回
-  `jobId` + `requestId` 和 `statusCommand`。定时任务按 **`jobId`** 查询：
-  `python3 publish/upload_post.py --status <jobId> --json-out`（输出里的 `statusCommand`
-  就是这条命令）。
-
-## 5. 向用户汇报
-
-每个平台一行：链接、或原因。
-
-| 平台结果 | 含义 |
-|---|---|
-| `completed` + `url` | 已发布。私密发布没有公开链接：YouTube 仍给出本人可看的链接，其他平台给 `postId` + `note` |
-| `skipped` | profile 没连这个平台，没有发 |
-| `failed` / `retryable` | `error` 是平台给的原因（如账号授权过期，去后台重新连接）；`retryable` 会由服务端自动重试 |
-| TikTok `inbox: true` | TikTok 把视频放进了草稿箱，需要用户在 TikTok App 里点发布 |
-| 整体 `status: "unknown"` | 无法确认是否已受理。原样告诉用户 `requestId`，稍后用 `statusCommand` 查询；**不要重跑发布命令** |
-
-## 6. 参数速查
-
-| 参数 | 说明 |
-|---|---|
-| `--video` / `--title` | 成片路径 / 各平台共用文案 |
-| `--description` / `--description-file` | 长描述 |
-| `--platforms` | `tiktok,instagram,youtube,linkedin,facebook,x,threads,pinterest,bluesky`（别名 `twitter` `reels` `shorts`） |
-| `--user` | profile 名，默认 `$UPLOAD_POST_USER` |
-| `--schedule` + `--timezone` | 定时发布（≤365 天），IANA 时区，默认 UTC |
-| `--first-comment` | 发布后自动发第一条评论 |
-| `--ai-generated` | AI 生成内容声明（TikTok / Instagram / YouTube / X） |
-| `--thumbnail` | 自定义封面（YouTube、LinkedIn） |
-| `--youtube-privacy` | `private`（默认）/ `unlisted` / `public` |
-| `--tags` | YouTube 标签，逗号分隔 |
-| `--tiktok-privacy` / `--tiktok-draft` | TikTok 隐私（默认沿用账号设置）/ 只存草稿 |
-| `--instagram-story` | 发 Stories 而非 Reels |
-| `--facebook-page-id` / `--linkedin-page-id` | 指定 Facebook 主页 / 以 LinkedIn 公司页发布 |
-| `--pinterest-board` | Pinterest 必填 |
-| `--status ID` | 查询之前的发布：即时发布用 request_id，定时发布用 job_id |
-| `--dry-run` / `--json-out` | 只校验不发布 / 输出一行 JSON |
-
-错误类型（`errorType`）：`auth`（key 缺失或错误）、`validation`（参数错误，或所选平台都没连接）、
-`forbidden`（套餐不支持，如免费版发 TikTok）、`quota`（频率或套餐上限）、`http`（网络 / 服务端）。
-
-离线单测：`python3 -m unittest publish/test_upload_post.py -v`
+# 发布到社交平台：成片 → TikTok / Instagram / YouTube / LinkedIn / X …
+
+把交付的 MP4 一次发到 TikTok、Instagram（Reels 或 Stories）、YouTube（含 Shorts）、
+LinkedIn、Facebook、X、Threads、Pinterest、Bluesky，可立即发布或定时发布。
+脚本 `publish/upload_post.py`，通过 [Upload-Post](https://upload-post.com) API 完成，
+只用 Python 标准库（无需 venv / pip）。
+
+**触发时机**：只在用户**主动要求**把成片发到社交平台时执行（例如"帮我发到
+TikTok 和 YouTube"）。它不是交付收尾 1-2-3 之外的第 4 条推荐，不要主动推销。
+发布是公开且难以撤回的操作，**必须先让用户确认文案和平台清单**，再真正发布。
+
+> **说明**：Upload-Post 是第三方托管服务。免费版每月 10 次上传，覆盖上面除
+> TikTok 以外的全部平台（TikTok 需付费版）。只有用户配置了自己的 API key 时
+> 本流程才会联网。
+
+## 1. 一次性准备（用户操作）
+
+1. 在 https://upload-post.com 注册，创建一个 profile，把要发的社交账号连到这个 profile。
+2. 在后台创建 API key。
+3. 设置环境变量（或写进用户自己的 shell 配置）：
+
+```bash
+export UPLOAD_POST_API_KEY=...
+export UPLOAD_POST_USER=<profile 名>
+```
+
+缺这两个变量时，告诉用户以上三步，停下等待，不要尝试发布。
+
+## 2. 选文件与准备文案
+
+- **文件**：用交付的成片。配了 BGM 的片子有两版（带 BGM / 无 BGM），默认发
+  **带 BGM 版**；用户另有要求按用户的来。
+- **画幅**：TikTok、Reels、Shorts 要竖屏 9:16。成片是横屏 16:9 时如实告诉用户
+  （这些平台会加黑边或裁切），建议改发 YouTube / LinkedIn / X / Facebook，或另渲
+  一版竖屏。
+- **文案 `--title`**：在 TikTok / Instagram / X / Threads 上就是正文，按社交文案写
+  （钩子一句 + 2–4 个话题标签），不要写成 YouTube 标题。含 YouTube 时 ≤100 字符。
+  交付收尾第 1 条里用户若同意 @ 作者，把那句放进文案。
+- **长描述 `--description`**：YouTube / LinkedIn / Facebook / Pinterest 用。
+- **AI 声明 `--ai-generated`**：询问用户是否标注 AI 生成内容。成片由 Agent 以代码
+  渲染，一般不属于"逼真的合成影像"，默认不标；用了 AI 生成画面或 AI 配音时建议标。
+
+把「文案 + 描述 + 平台清单 + 定时（如有）+ 各平台隐私设置」整理给用户，
+**得到明确确认后**再进入下一步。
+
+## 3. 先 dry-run（不发布）
+
+```bash
+python3 publish/upload_post.py --video out/promo.mp4 --title "<文案>" \
+  --description "<长描述>" --platforms tiktok,instagram,youtube --dry-run --json-out
+```
+
+检查输出：`authOk` 为 `true`；`missingPlatforms` 非空说明这些平台没连到 profile，
+会被跳过，告诉用户去后台连接，或从清单里去掉。
+
+## 4. 发布
+
+去掉 `--dry-run` 重跑。脚本等待各平台结果（默认最多 10 分钟），逐平台输出链接或错误。
+
+- **每条发布命令只跑一次。** 无论超时、断网、报错还是 `status: "unknown"`，都**不要
+  重跑发布命令**，重跑会生成新的 request_id，同一视频会被发两次。只能查询：
+  `python3 publish/upload_post.py --status <requestId> --json-out`
+- 脚本如何区分：只有 **400 / 401 / 403 / 422**（服务端受理前明确拒绝）才判失败，此时
+  没有任何东西被发出去，修正参数后可以再发。5xx、网关错误、超时、断网、2xx 却无有效
+  JSON 都属于"不确定"，视频可能已被受理。脚本会自动用同一个 request_id 查询：查到就
+  照常继续；仍无法确认则输出 `status: "unknown"`（退出码 2）、`requestId` 和
+  `statusCommand`，并带 `doNotRerun: true`。
+- 脚本在**发送之前**就把 `request_id` 和对应的 `--status` 命令打到 stderr。进程中途
+  被中断时，用这条命令查询，不要重跑发布。
+- 定时发布（`--schedule 2026-10-01T09:00:00 --timezone Asia/Shanghai`）立即返回
+  `jobId` + `requestId` 和 `statusCommand`。定时任务按 **`jobId`** 查询：
+  `python3 publish/upload_post.py --status <jobId> --json-out`（输出里的 `statusCommand`
+  就是这条命令）。
+
+## 5. 向用户汇报
+
+每个平台一行：链接、或原因。
+
+| 平台结果 | 含义 |
+|---|---|
+| `completed` + `url` | 已发布。私密发布没有公开链接：YouTube 仍给出本人可看的链接，其他平台给 `postId` + `note` |
+| `skipped` | profile 没连这个平台，没有发 |
+| `failed` / `retryable` | `error` 是平台给的原因（如账号授权过期，去后台重新连接）；`retryable` 会由服务端自动重试 |
+| TikTok `inbox: true` | TikTok 把视频放进了草稿箱，需要用户在 TikTok App 里点发布 |
+| 整体 `status: "unknown"` | 无法确认是否已受理。原样告诉用户 `requestId`，稍后用 `statusCommand` 查询；**不要重跑发布命令** |
+
+## 6. 参数速查
+
+| 参数 | 说明 |
+|---|---|
+| `--video` / `--title` | 成片路径 / 各平台共用文案 |
+| `--description` / `--description-file` | 长描述 |
+| `--platforms` | `tiktok,instagram,youtube,linkedin,facebook,x,threads,pinterest,bluesky`（别名 `twitter` `reels` `shorts`） |
+| `--user` | profile 名，默认 `$UPLOAD_POST_USER` |
+| `--schedule` + `--timezone` | 定时发布（≤365 天），IANA 时区，默认 UTC |
+| `--first-comment` | 发布后自动发第一条评论 |
+| `--ai-generated` | AI 生成内容声明（TikTok / Instagram / YouTube / X） |
+| `--thumbnail` | 自定义封面（YouTube、LinkedIn） |
+| `--youtube-privacy` | `private`（默认）/ `unlisted` / `public` |
+| `--tags` | YouTube 标签，逗号分隔 |
+| `--tiktok-privacy` / `--tiktok-draft` | TikTok 隐私（默认沿用账号设置）/ 只存草稿 |
+| `--instagram-story` | 发 Stories 而非 Reels |
+| `--facebook-page-id` / `--linkedin-page-id` | 指定 Facebook 主页 / 以 LinkedIn 公司页发布 |
+| `--pinterest-board` | Pinterest 必填 |
+| `--status ID` | 查询之前的发布：即时发布用 request_id，定时发布用 job_id |
+| `--dry-run` / `--json-out` | 只校验不发布 / 输出一行 JSON |
+
+错误类型（`errorType`）：`auth`（key 缺失或错误）、`validation`（参数错误，或所选平台都没连接）、
+`forbidden`（套餐不支持，如免费版发 TikTok）、`quota`（频率或套餐上限）、`http`（网络 / 服务端）。
+
+离线单测：`python3 -m unittest publish/test_upload_post.py -v`

package/lib/motion/shotcraft/upstream/references/sequences/promo-energy-arc.md

@@ -1,50 +1,50 @@
----
-name: promo-energy-arc
-一句话: 全片能量骨架——低开品牌 → 单主角立传 → 字卡呼吸间隔的功能爬升段 → 发布会峰值收场
-适用: 30–60s 多功能 web 产品宣传片的默认全片结构（分镜阶段先填骨架再挑卡）
-段数: 4 段位 + 2–4 张呼吸字卡
----
-
-## 意图
-
-把散落在 R1–R3/Q5/Q8/P4 的节奏规则合成一条可直接填空的全片曲线。
-模板片成片（1085f）与两次独立复现（各 900f）三次成表均收敛到同一
-骨架——它是默认项，不是令：逐项目可有意识偏离，偏离写进项目 spec。
-
-## 段位表
-
-| 段位 | 时长占比 | 能量 | 职责 | 候选配方卡 |
-|------|----------|------|------|------------|
-| ① 品牌开场 | 8–12%（30s 片）；开场+立传合计可达 20%（模板片） | 低 | 字标压印 + hold ≥1s（R1），交棒产品页面 | brand-ink-open |
-| ② 单主角立传 | 12–15% | 中（质感最高、节奏最慢） | 一个主角、一条完整动作弧 ≥3s（Q5/R3），立出产品原子单位 | spotlight-hero-card（+aesthetic-rules.md Q2 高清 rasterize 技法） |
-| ③ 功能爬升段 | 55–65% | 中高⇄低交替 | 每镜绑一个独特功能、一种手法只当一次主角（P4）；镜与镜之间按需插呼吸字卡 | deck-deal-flyin / type-and-filter / list-stack-press / row-embed / document-typewriter-reveal |
-| ④ 发布会收场 | 13–16% | 峰值（全片最高） | 已展示功能各出代表元素合影围住字标（Q8），sign-off hold ≥1s（R1） | outro-group-photo-launch |
-
-呼吸字卡（paper-title-card）规则：每 1–2 个功能镜头后插一张，单张
-50–55f（≈1.8s），全片 2–4 张；重要功能出场前用作引导字卡（C2）。
-模板片 10 镜里字卡占 4 席，两次复现各 2 席——密度按功能镜头数取。
-
-## 填空流程（替代 ad-hoc 推导）
-
-1. 列产品功能清单（P4），数出功能镜头数 N。
-2. 按段位表分配总帧数：先扣 ①②④ 与字卡的预算，剩余给 ③ 均分。
-   每镜预算内**先划走 hold/rest 帧**（R1 落定 ≥30f、批量收尾 15f，R3）
-   再排动效——不是排完动效再找空隙。
-3. ③ 段能量交替：高能量镜（发牌/堆叠）与稳节奏镜（交互/读字段）
-   间隔排列，信息密度最高的镜头（文档/报告类）放在峰值收场之前——
-   模板片与两次复现均把文档/报告类镜头排在倒数第 2–3 位。
-4. 逐槽位扫 shots/ frontmatter 挑卡，选中的卡读全文。
-5. 镜头排定后逐接缝选转场式（shot-transitions 技法卡三式选型），
-   写进分镜表"关键动效"列——转场帧从相邻镜头预算划走。
-
-## 已知坑
-
-- 骨架当风格令全局硬套：段位占比是模板片单例实证（标注：单例判例），
-  15s 短片或单功能产品应大胆合并段位，但 ①hold/④峰值两端不可省。
-- ③ 段只堆高能量镜：连续高能量读作嘈杂，交替与字卡就是节奏本身。
-- 呼吸字卡写成第二遍 tagline：字卡与 outro 文案重复即删（P4 判例：
-  outro tagline 去重）。
-
-## 参考实现
-
-template/src/aifl/Main.tsx AIFL_SHOTS 段位表（sum=1085f）。
+---
+name: promo-energy-arc
+一句话: 全片能量骨架——低开品牌 → 单主角立传 → 字卡呼吸间隔的功能爬升段 → 发布会峰值收场
+适用: 30–60s 多功能 web 产品宣传片的默认全片结构（分镜阶段先填骨架再挑卡）
+段数: 4 段位 + 2–4 张呼吸字卡
+---
+
+## 意图
+
+把散落在 R1–R3/Q5/Q8/P4 的节奏规则合成一条可直接填空的全片曲线。
+模板片成片（1085f）与两次独立复现（各 900f）三次成表均收敛到同一
+骨架——它是默认项，不是令：逐项目可有意识偏离，偏离写进项目 spec。
+
+## 段位表
+
+| 段位 | 时长占比 | 能量 | 职责 | 候选配方卡 |
+|------|----------|------|------|------------|
+| ① 品牌开场 | 8–12%（30s 片）；开场+立传合计可达 20%（模板片） | 低 | 字标压印 + hold ≥1s（R1），交棒产品页面 | brand-ink-open |
+| ② 单主角立传 | 12–15% | 中（质感最高、节奏最慢） | 一个主角、一条完整动作弧 ≥3s（Q5/R3），立出产品原子单位 | spotlight-hero-card（+aesthetic-rules.md Q2 高清 rasterize 技法） |
+| ③ 功能爬升段 | 55–65% | 中高⇄低交替 | 每镜绑一个独特功能、一种手法只当一次主角（P4）；镜与镜之间按需插呼吸字卡 | deck-deal-flyin / type-and-filter / list-stack-press / row-embed / document-typewriter-reveal |
+| ④ 发布会收场 | 13–16% | 峰值（全片最高） | 已展示功能各出代表元素合影围住字标（Q8），sign-off hold ≥1s（R1） | outro-group-photo-launch |
+
+呼吸字卡（paper-title-card）规则：每 1–2 个功能镜头后插一张，单张
+50–55f（≈1.8s），全片 2–4 张；重要功能出场前用作引导字卡（C2）。
+模板片 10 镜里字卡占 4 席，两次复现各 2 席——密度按功能镜头数取。
+
+## 填空流程（替代 ad-hoc 推导）
+
+1. 列产品功能清单（P4），数出功能镜头数 N。
+2. 按段位表分配总帧数：先扣 ①②④ 与字卡的预算，剩余给 ③ 均分。
+   每镜预算内**先划走 hold/rest 帧**（R1 落定 ≥30f、批量收尾 15f，R3）
+   再排动效——不是排完动效再找空隙。
+3. ③ 段能量交替：高能量镜（发牌/堆叠）与稳节奏镜（交互/读字段）
+   间隔排列，信息密度最高的镜头（文档/报告类）放在峰值收场之前——
+   模板片与两次复现均把文档/报告类镜头排在倒数第 2–3 位。
+4. 逐槽位扫 shots/ frontmatter 挑卡，选中的卡读全文。
+5. 镜头排定后逐接缝选转场式（shot-transitions 技法卡三式选型），
+   写进分镜表"关键动效"列——转场帧从相邻镜头预算划走。
+
+## 已知坑
+
+- 骨架当风格令全局硬套：段位占比是模板片单例实证（标注：单例判例），
+  15s 短片或单功能产品应大胆合并段位，但 ①hold/④峰值两端不可省。
+- ③ 段只堆高能量镜：连续高能量读作嘈杂，交替与字卡就是节奏本身。
+- 呼吸字卡写成第二遍 tagline：字卡与 outro 文案重复即删（P4 判例：
+  outro tagline 去重）。
+
+## 参考实现
+
+template/src/aifl/Main.tsx AIFL_SHOTS 段位表（sum=1085f）。

package/lib/motion/shotcraft/upstream/references/sfx-sourcing.md

@@ -1,95 +1,95 @@
-# Freesound 音效选材
-
-新制作与换音直接从 [Freesound](https://freesound.org) 获取 SFX，不再使用共享本地音效库。
-用户指定的音源仍优先。BGM 沿用独立选曲流程，见 [sound-design.md](sound-design.md) §2。
-本模块负责选材、下载与来源记录；钉帧、混音、输出偏移补偿继续按 sound-design 执行。
-
-## 1. 把画面写成声音需求
-
-每个 cue 记录：对应镜头/动作、声源或材质、目标时长、攻击/尾音、音色和许可要求。
-例如纸卡滑入：`paper slide`，0.2–0.8s，干燥、单次、无长尾、CC0。
-以声源匹配为先，再比较时长、录音描述与热度；不要只搜索抽象情绪或宽泛的 `click`。
-
-- 单击/滑动不要选混有多个动作的长段录音，除非能明确裁出所需动作。
-- 下载量与评分人数用于辅助排序，不能替代匹配度；大量评分的 4.4 分通常比 6 人评出的
-  4.9 分更有参考性。推荐时引用实际数据，缺失值保留未知，不能编造。
-- 上传者描述提供声源、设备、处理方式线索；优先清晰且匹配的实际声源。
-  名牌设备不保证质量，口技或内置麦克风也不自动意味着不可用，按项目质感判断。
-- UI 动作的拟音与合成提示音分开判断，遵守 aesthetic-rules S1/S4。
-
-## 2. 搜索
-
-脚本独立实现，Python 3.9+ 标准库，无需 Freesound API key；下载/分析需 ffmpeg、ffprobe。
-从 skill 根目录执行；路径含空格时加引号。安装在其他位置时用脚本绝对路径。
-
-```bash
-python3 assets/scripts/sfx-source.py search "paper slide" --max-duration 1 --limit 5 --output /path/to/video/audio-search.json
-python3 assets/scripts/sfx-source.py search "short cinematic impact" --license by --max-duration 3 --pages 2
-```
-
-输出 JSON 含 ID、标题、作者、素材页、预览地址、描述、时长、下载量、评分和人数。
-保留搜索相关性顺序，并在本地再次过滤许可与时长。`--pages` 最多 3 页，先缩窄关键词，
-不以抓取更多页面代替选材。搜索输出只用于比较，不作为下载时的许可凭据。
-
-许可默认 `cc0`；`by` 允许 CC0 和 CC BY。商用产品片不接受 BY-NC、Sampling+ 或未知许可。
-用户愿意接受署名时可用 `--license by`，无需对每条声音重复询问。
-
-## 3. 下载到当前视频工程
-
-把 ID 换成本次搜索返回的候选；`get` 也支持已知 ID，不依赖全局缓存。
-
-```bash
-python3 assets/scripts/sfx-source.py get fs:12345 fs:67890 --out-dir /path/to/video/public/audio/sfx
-```
-
-需要 CC BY 时在 `get` 上同样传 `--license by`。下载前重新读取各素材的详情页、
-核对实际许可 URL 与版本，再有界并发下载。不会修改网络代理，也不会自动切换其他音源。
-
-产物：
-
-- `fs-<id>.mp3`：Freesound 的高质量 **有损 MP3 预览**，不是上传者的原始 WAV。
-- `audio-manifest.json`：来源、作者、素材页、许可 URL/版本、预览标记、下载时间、
-  SHA-256、修改记录与实际音频分析。
-- `FREESOUND-CREDITS.md`：可随工程交付的来源与署名清单；CC BY 条目需进入发布页说明
-  或成片署名，不能仅留在工程文件中。剪辑、变速、归一化等改动需补写 `changes`。
-
-重复下载会核对文件哈希，不覆盖自行修改或来源不明的同名文件。每个输出目录同一时间
-只运行一个 `get`。部分下载失败时成功项仍保留清单，命令退出非零；根据逐条结果只重试失败 ID。
-无匹配候选时调整查询；网站超时/限流/页面结构变化时停止该来源的自动调用，说明具体问题。
-可给出素材页供人工下载，再按同样字段记录来源；不能用 HTML 错误页冒充音频。
-
-原音质或无损处理有明确要求时，从素材页走 Freesound 支持的登录/下载流程取得原文件；
-不能把预览转 WAV 后标成“原始无损素材”。记录真实文件种类、地址、哈希并重新分析。
-
-## 4. 分析、试听与接入
-
-`get` 自动用 ffprobe 与 ffmpeg 解码验收，记录实际格式/采样率/声道、时长、sample peak、
-整体 RMS、10ms RMS 能量峰和相对峰值 -40dB 的活动区间。这些不是 LUFS、true peak 或精确动作起点。
-多个动作的录音需要选择正确的峰值，不能直接将全文件最大峰用于所有 cue。
-
-单独分析处理后的文件：
-
-```bash
-python3 assets/scripts/sfx-source.py analyze /path/to/video/public/audio/sfx/fs-12345.mp3 --output /path/to/video/audio-analysis.json
-```
-
-处理后更新 manifest 的文件名、SHA-256、`analysis` 和 `changes`；原文件与处理后文件的
-峰值时间分开记录。浏览器试听或把候选垫入片段检查音色、底噪、尾音与音乐的关系。
-工具只有元数据/测量能力时，明确写“未试听”，不要将下载数、波形或 ffmpeg 分析描述成听感。
-自主创作可基于证据选定并继续；用户要求听候选时给素材页或支持的本地音频预览。
-
-随后将固定文件接入中央 SFX 表，`from` 从 `SHOTS`/`beatF` 派生，并根据
-sound-design §4.6 补偿音源峰值与输出偏移。下载文件必须随工程保存，不能只引用远程 URL。
-工作台显示工程音频；新增下载后重新运行 `node workbench/scripts/open.mjs <工程目录>` 更新索引。
-
-## 5. 模板与交付
-
-`template/public/audio/` 的历史文件保留供原样运行与验证，不作为新项目的选材池。
-用模板为新产品制作时，沿用 SFX 的动作语义和钉帧结构，从 Freesound 选音后重新测量、对齐；
-用户明确要求复现原声音时保留该要求，并按模板授权记录核实音源。
-共享 SFX 目录移除前的完整记录可从 Git 历史查询，BGM 授权仍在 `assets/audio/ATTRIBUTION.md`。
-
-交付音频文件、manifest、署名清单和 SFX 时间表。终检见 [final-review.md](final-review.md) A10。
-
-选材方法参考 [vibe-motion/sound](https://github.com/vibe-motion/sound)（查阅版本 `01f81d6`）；
-本仓库的 CLI 为独立实现，未引入其脚本或个人 Clash 配置。
+# Freesound 音效选材
+
+新制作与换音直接从 [Freesound](https://freesound.org) 获取 SFX，不再使用共享本地音效库。
+用户指定的音源仍优先。BGM 沿用独立选曲流程，见 [sound-design.md](sound-design.md) §2。
+本模块负责选材、下载与来源记录；钉帧、混音、输出偏移补偿继续按 sound-design 执行。
+
+## 1. 把画面写成声音需求
+
+每个 cue 记录：对应镜头/动作、声源或材质、目标时长、攻击/尾音、音色和许可要求。
+例如纸卡滑入：`paper slide`，0.2–0.8s，干燥、单次、无长尾、CC0。
+以声源匹配为先，再比较时长、录音描述与热度；不要只搜索抽象情绪或宽泛的 `click`。
+
+- 单击/滑动不要选混有多个动作的长段录音，除非能明确裁出所需动作。
+- 下载量与评分人数用于辅助排序，不能替代匹配度；大量评分的 4.4 分通常比 6 人评出的
+  4.9 分更有参考性。推荐时引用实际数据，缺失值保留未知，不能编造。
+- 上传者描述提供声源、设备、处理方式线索；优先清晰且匹配的实际声源。
+  名牌设备不保证质量，口技或内置麦克风也不自动意味着不可用，按项目质感判断。
+- UI 动作的拟音与合成提示音分开判断，遵守 aesthetic-rules S1/S4。
+
+## 2. 搜索
+
+脚本独立实现，Python 3.9+ 标准库，无需 Freesound API key；下载/分析需 ffmpeg、ffprobe。
+从 skill 根目录执行；路径含空格时加引号。安装在其他位置时用脚本绝对路径。
+
+```bash
+python3 assets/scripts/sfx-source.py search "paper slide" --max-duration 1 --limit 5 --output /path/to/video/audio-search.json
+python3 assets/scripts/sfx-source.py search "short cinematic impact" --license by --max-duration 3 --pages 2
+```
+
+输出 JSON 含 ID、标题、作者、素材页、预览地址、描述、时长、下载量、评分和人数。
+保留搜索相关性顺序，并在本地再次过滤许可与时长。`--pages` 最多 3 页，先缩窄关键词，
+不以抓取更多页面代替选材。搜索输出只用于比较，不作为下载时的许可凭据。
+
+许可默认 `cc0`；`by` 允许 CC0 和 CC BY。商用产品片不接受 BY-NC、Sampling+ 或未知许可。
+用户愿意接受署名时可用 `--license by`，无需对每条声音重复询问。
+
+## 3. 下载到当前视频工程
+
+把 ID 换成本次搜索返回的候选；`get` 也支持已知 ID，不依赖全局缓存。
+
+```bash
+python3 assets/scripts/sfx-source.py get fs:12345 fs:67890 --out-dir /path/to/video/public/audio/sfx
+```
+
+需要 CC BY 时在 `get` 上同样传 `--license by`。下载前重新读取各素材的详情页、
+核对实际许可 URL 与版本，再有界并发下载。不会修改网络代理，也不会自动切换其他音源。
+
+产物：
+
+- `fs-<id>.mp3`：Freesound 的高质量 **有损 MP3 预览**，不是上传者的原始 WAV。
+- `audio-manifest.json`：来源、作者、素材页、许可 URL/版本、预览标记、下载时间、
+  SHA-256、修改记录与实际音频分析。
+- `FREESOUND-CREDITS.md`：可随工程交付的来源与署名清单；CC BY 条目需进入发布页说明
+  或成片署名，不能仅留在工程文件中。剪辑、变速、归一化等改动需补写 `changes`。
+
+重复下载会核对文件哈希，不覆盖自行修改或来源不明的同名文件。每个输出目录同一时间
+只运行一个 `get`。部分下载失败时成功项仍保留清单，命令退出非零；根据逐条结果只重试失败 ID。
+无匹配候选时调整查询；网站超时/限流/页面结构变化时停止该来源的自动调用，说明具体问题。
+可给出素材页供人工下载，再按同样字段记录来源；不能用 HTML 错误页冒充音频。
+
+原音质或无损处理有明确要求时，从素材页走 Freesound 支持的登录/下载流程取得原文件；
+不能把预览转 WAV 后标成“原始无损素材”。记录真实文件种类、地址、哈希并重新分析。
+
+## 4. 分析、试听与接入
+
+`get` 自动用 ffprobe 与 ffmpeg 解码验收，记录实际格式/采样率/声道、时长、sample peak、
+整体 RMS、10ms RMS 能量峰和相对峰值 -40dB 的活动区间。这些不是 LUFS、true peak 或精确动作起点。
+多个动作的录音需要选择正确的峰值，不能直接将全文件最大峰用于所有 cue。
+
+单独分析处理后的文件：
+
+```bash
+python3 assets/scripts/sfx-source.py analyze /path/to/video/public/audio/sfx/fs-12345.mp3 --output /path/to/video/audio-analysis.json
+```
+
+处理后更新 manifest 的文件名、SHA-256、`analysis` 和 `changes`；原文件与处理后文件的
+峰值时间分开记录。浏览器试听或把候选垫入片段检查音色、底噪、尾音与音乐的关系。
+工具只有元数据/测量能力时，明确写“未试听”，不要将下载数、波形或 ffmpeg 分析描述成听感。
+自主创作可基于证据选定并继续；用户要求听候选时给素材页或支持的本地音频预览。
+
+随后将固定文件接入中央 SFX 表，`from` 从 `SHOTS`/`beatF` 派生，并根据
+sound-design §4.6 补偿音源峰值与输出偏移。下载文件必须随工程保存，不能只引用远程 URL。
+工作台显示工程音频；新增下载后重新运行 `node workbench/scripts/open.mjs <工程目录>` 更新索引。
+
+## 5. 模板与交付
+
+`template/public/audio/` 的历史文件保留供原样运行与验证，不作为新项目的选材池。
+用模板为新产品制作时，沿用 SFX 的动作语义和钉帧结构，从 Freesound 选音后重新测量、对齐；
+用户明确要求复现原声音时保留该要求，并按模板授权记录核实音源。
+共享 SFX 目录移除前的完整记录可从 Git 历史查询，BGM 授权仍在 `assets/audio/ATTRIBUTION.md`。
+
+交付音频文件、manifest、署名清单和 SFX 时间表。终检见 [final-review.md](final-review.md) A10。
+
+选材方法参考 [vibe-motion/sound](https://github.com/vibe-motion/sound)（查阅版本 `01f81d6`）；
+本仓库的 CLI 为独立实现，未引入其脚本或个人 Clash 配置。

package/lib/motion/shotcraft/upstream/references/shots/camera/basic-3d-scene.md

@@ -1,41 +1,41 @@
----
-name: basic-3d-scene
-一句话: impress.js 式空间演示：卡片以不同位置/旋转/缩放散布 3D 空间，相机取各步姿态之逆依次飞行对齐，末步拉到 OVERVIEW 总览
-适用: 概念/路线图/三步法的空间化讲述；替代平面 slides 的"每一步都换个空间视角"
-时长: 约 7.5s（225f@30fps；四站，三段飞行 28/32/32f，每站停留 ≥30f）
-能量: 中（每次转场有空间惊喜，停留段安静读卡）
----
-
-## 意图
-把"翻页"变成"在想法的空间里旅行"：每张卡不仅有位置还有姿态（第二站世界左转 38°、第三站整个画框侧躺 90°），相机对齐它时观众的世界也跟着转——空间变化本身成为"进入新章节"的仪式感。
-
-## 动效核心
-- 核心配方一行：**camera = stepTransform.inverse()**。每站只写卡片自己的 pose（x/y/z/rx/ry/rz/s），相机变换按 `scale(1/s) rotateZ(-rz) rotateY(-ry) rotateX(-rx) translate3d(-x,-y,-z)` 取逆，顺序严格相反
-- demo 用 graphite 暗场（近单色 + 香槟金点缀），video-shotcraft 的三章节卡 Frame / Craft / Ship（品牌短句拆成三章，卡头右侧挂标志 + 字标）：卡片 1240×700 **原生 1:1 排版**（对位时就是屏幕像素，不经设计坐标放大，字不糊），156px 标题 + 44px 说明 + 被卡边裁切的 560px 细体章节数字
-- 四站姿态各有戏剧点：STEP01 原点正视 → STEP02 (1690,−260,−650) + ry−38° → STEP03 (2590,830,−850) + rz90°（画框侧躺，相机跟着转正它）→ OVERVIEW s=2.7（相机 1/2.7 拉远），总览站位置按"三卡落在右上、左下留给落版"反解
-- 飞行链式插值：三段飞行 36–64 / 96–128 / 158–190（帧），不对称 in-out bezier(0.62,0,0.16,1)；站间飞行途中相机额外拉远 30%（hop，sin 包络）让观众看见空间里的其他卡；飞行段做时间采样运动模糊（快门 0.5f，子帧 1–8 按相机位移自适应）
-- 停留段不死：落位后相机极缓推近 1.5%（下一段起飞时同曲线还原），卡底金色进度线走满当前段；标题在落位前 8f 逐字从线下升起，每张卡只揭示一次
-- 空间参照：70 颗真 3D 浮尘挂在世界坐标里（各有 z），视差全部来自相机；enter/exit 聚焦按"站距"`d = |af − i|` 给 `opacity 0.22–1 + blur 0–7px`，总览段全员回到 0.85
-- OVERVIEW 落版挂在总览站姿态上（放大 2.7 倍排版，相机 1/2.7 看回来 = 屏幕 1:1）：眉题是 video-shotcraft 标志 + 字标，"Craft the shot." 150px 衬线逐词升起，尾段 hold 推近 1.5%
-
-## 参数表
-| 参数 | 典型值 | 调节手感 |
-|------|--------|----------|
-| 站点姿态 | 每站至少一个新变换维度 | 只挪 x/y 是平移幻灯片；rz 站（画框旋转）是记忆点，一支片用一次 |
-| 飞行时长 | 28–32f | 有旋转的段别短于 28f，观众需要时间理解"世界在转" |
-| 停留时长 | ≥30f | 读卡位；卡内文字多时优先加停留而不是减飞行 |
-| hop 拉远 | 30% | 0 = 贴着卡面平移，看不到空间；>50% 每段都像总览 |
-| OVERVIEW 缩放 | s=2.7 | 值越大总览越"高空"；先定总览海报构图，再反解各站世界坐标 |
-| 聚焦衰减 | opacity 0.22 底 + blur 7px 峰 | 底值别低于 0.2——离焦卡要"在场"，纯黑会丢空间感 |
-| perspective | 2600px | 与最大 |z|（850）比值约 3:1；更深的 z 需同步加大 persp 防畸变 |
-
-## 已知坑
-- 逆变换的旋转顺序（Z→Y→X 反着正变换的 X→Y→Z）不能乱——乱序在单轴旋转时看不出来，多轴复合站会歪
-- 卡片 pose 写在卡自身 transform 和相机公式两处消费，加站只改 POSES 表，两处 transform 字符串别动
-- rz90° 站的卡内文字会跟着躺倒，相机转正后才可读——这是设计（转正瞬间"啊看懂了"），但该站文案要短
-- 落版挂在世界里时，最后一段飞行中它是斜的：显影要晚（飞行过半再淡入），逐字揭示等落位前 6f 再开始
-- OVERVIEW 后无返程，作段落收尾用；要循环回 STEP01 就在末尾加一段 fly back（cam 再 lerp 回 POSES[0]）
-
-## 参考实现
-demos/camera/basic-3d-scene/
-（Basic3DScene.tsx）
+---
+name: basic-3d-scene
+一句话: impress.js 式空间演示：卡片以不同位置/旋转/缩放散布 3D 空间，相机取各步姿态之逆依次飞行对齐，末步拉到 OVERVIEW 总览
+适用: 概念/路线图/三步法的空间化讲述；替代平面 slides 的"每一步都换个空间视角"
+时长: 约 7.5s（225f@30fps；四站，三段飞行 28/32/32f，每站停留 ≥30f）
+能量: 中（每次转场有空间惊喜，停留段安静读卡）
+---
+
+## 意图
+把"翻页"变成"在想法的空间里旅行"：每张卡不仅有位置还有姿态（第二站世界左转 38°、第三站整个画框侧躺 90°），相机对齐它时观众的世界也跟着转——空间变化本身成为"进入新章节"的仪式感。
+
+## 动效核心
+- 核心配方一行：**camera = stepTransform.inverse()**。每站只写卡片自己的 pose（x/y/z/rx/ry/rz/s），相机变换按 `scale(1/s) rotateZ(-rz) rotateY(-ry) rotateX(-rx) translate3d(-x,-y,-z)` 取逆，顺序严格相反
+- demo 用 graphite 暗场（近单色 + 香槟金点缀），video-shotcraft 的三章节卡 Frame / Craft / Ship（品牌短句拆成三章，卡头右侧挂标志 + 字标）：卡片 1240×700 **原生 1:1 排版**（对位时就是屏幕像素，不经设计坐标放大，字不糊），156px 标题 + 44px 说明 + 被卡边裁切的 560px 细体章节数字
+- 四站姿态各有戏剧点：STEP01 原点正视 → STEP02 (1690,−260,−650) + ry−38° → STEP03 (2590,830,−850) + rz90°（画框侧躺，相机跟着转正它）→ OVERVIEW s=2.7（相机 1/2.7 拉远），总览站位置按"三卡落在右上、左下留给落版"反解
+- 飞行链式插值：三段飞行 36–64 / 96–128 / 158–190（帧），不对称 in-out bezier(0.62,0,0.16,1)；站间飞行途中相机额外拉远 30%（hop，sin 包络）让观众看见空间里的其他卡；飞行段做时间采样运动模糊（快门 0.5f，子帧 1–8 按相机位移自适应）
+- 停留段不死：落位后相机极缓推近 1.5%（下一段起飞时同曲线还原），卡底金色进度线走满当前段；标题在落位前 8f 逐字从线下升起，每张卡只揭示一次
+- 空间参照：70 颗真 3D 浮尘挂在世界坐标里（各有 z），视差全部来自相机；enter/exit 聚焦按"站距"`d = |af − i|` 给 `opacity 0.22–1 + blur 0–7px`，总览段全员回到 0.85
+- OVERVIEW 落版挂在总览站姿态上（放大 2.7 倍排版，相机 1/2.7 看回来 = 屏幕 1:1）：眉题是 video-shotcraft 标志 + 字标，"Craft the shot." 150px 衬线逐词升起，尾段 hold 推近 1.5%
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 站点姿态 | 每站至少一个新变换维度 | 只挪 x/y 是平移幻灯片；rz 站（画框旋转）是记忆点，一支片用一次 |
+| 飞行时长 | 28–32f | 有旋转的段别短于 28f，观众需要时间理解"世界在转" |
+| 停留时长 | ≥30f | 读卡位；卡内文字多时优先加停留而不是减飞行 |
+| hop 拉远 | 30% | 0 = 贴着卡面平移，看不到空间；>50% 每段都像总览 |
+| OVERVIEW 缩放 | s=2.7 | 值越大总览越"高空"；先定总览海报构图，再反解各站世界坐标 |
+| 聚焦衰减 | opacity 0.22 底 + blur 7px 峰 | 底值别低于 0.2——离焦卡要"在场"，纯黑会丢空间感 |
+| perspective | 2600px | 与最大 |z|（850）比值约 3:1；更深的 z 需同步加大 persp 防畸变 |
+
+## 已知坑
+- 逆变换的旋转顺序（Z→Y→X 反着正变换的 X→Y→Z）不能乱——乱序在单轴旋转时看不出来，多轴复合站会歪
+- 卡片 pose 写在卡自身 transform 和相机公式两处消费，加站只改 POSES 表，两处 transform 字符串别动
+- rz90° 站的卡内文字会跟着躺倒，相机转正后才可读——这是设计（转正瞬间"啊看懂了"），但该站文案要短
+- 落版挂在世界里时，最后一段飞行中它是斜的：显影要晚（飞行过半再淡入），逐字揭示等落位前 6f 再开始
+- OVERVIEW 后无返程，作段落收尾用；要循环回 STEP01 就在末尾加一段 fly back（cam 再 lerp 回 POSES[0]）
+
+## 参考实现
+demos/camera/basic-3d-scene/
+（Basic3DScene.tsx）