Cursor rule

1---
2description: "案例规范 — 改动 examples/** 时必须遵守的目录结构、字段、章节"
3globs:
4  - "examples/**"
5  - "scripts/validate-example.mjs"
6  - "scripts/new-example.mjs"
7alwaysApply: false
8---
9 
10# 案例规范（examples/**）
11 
12> 改动任何 `examples/<id>-<slug>/` 都要遵守。CI 会用 `scripts/validate-example.mjs` 校验。
13 
14## 目录结构
15 
16```text
17examples/<id>-<slug>/
18├── README.md         # 必填：英文版（5 段，英文 H2 标题）
19├── README.zh.md      # 必填：中文版（5 段，中文 H2 标题）
20├── run.sh            # 必填：可执行 + set -euo pipefail
21├── meta.json         # 必填：通过 schema 校验
22├── data/             # 复杂 JSON 拆这里
23│   ├── captions.json
24│   ├── images.json
25│   └── ...
26└── preview.gif       # 推荐：≤ 3 MB，3-8s
27```
28 
29## 命名规则
30 
31- `<id>` 范围：
32  - `01~09` = P0 入门案例（官方维护）
33  - `10~19` = 营销 / 产品类
34  - `20~29` = 知识 / 教育类
35  - `30~39` = Vlog / 个人类
36  - `99-community/<github-handle>/<case>/` = 社区贡献区
37- `<slug>` 用 kebab-case，如 `hello-caption`、`product-promo-30s`
38 
39## meta.json schema
40 
41```json
42{
43  "id": "01-hello-caption",
44  "title": "Hello Caption",
45  "tags": ["captions", "animation"],
46  "author": "your-github-handle",
47  "duration": 5,
48  "resolution": "1080x1920",
49  "gif": "preview.gif",
50  "description": "一句话描述",
51  "level": 1
52}
53```
54 
55字段约束（详见 `scripts/_lib/example-schema.mjs`）：
56 
57| 字段 | 类型 | 约束 |
58|---|---|---|
59| `id` | string | `^[a-z0-9][a-z0-9-]*$` |
60| `tags` | string[] | 至少 1 个 |
61| `duration` | number | > 0 |
62| `resolution` | string | `^[0-9]+x[0-9]+$` |
63| `level` | int | 1-5（推荐难度） |
64 
65## README.md（英文）+ README.zh.md（中文）必有 5 个 H2 章节
66 
67主 `README.md` 必须用英文章节（CI 严格匹配）：
68 
69```markdown
70## When to use
71 
72## Run it
73 
74## Key parameters
75 
76## Customize
77 
78## cutcli features used
79```
80 
81如果存在 `README.zh.md`（强烈推荐 + `lint:i18n` 强制成对），中文章节必须是：
82 
83```markdown
84## 适用场景
85 
86## 一行运行
87 
88## 关键参数解释
89 
90## 进阶改造
91 
92## 用到的 cutcli 能力
93```
94 
95第一段必须包含 `![preview](preview.gif)`（即使 gif 还没录，也要占位）。两个 README 顶部都要有双语切换链接：
96 
97```markdown
98[English](README.md) · [简体中文](README.zh.md)
99```
100 
101## run.sh 必有要素
102 
103```bash
104#!/usr/bin/env bash
105# <id>: <一句话描述>
106# Usage: bash run.sh
107set -euo pipefail
108
109if ! command -v cutcli &gt;/dev/null 2&gt;&amp;1; then
110  echo &quot;cutcli not found. Install: curl -s https://cutcli.com/cli | bash&quot; &gt;&amp;2
111  exit 1
112fi
113if ! command -v jq &gt;/dev/null 2&gt;&amp;1; then
114  echo &quot;jq not found.&quot; &gt;&amp;2
115  exit 1
116fi
117 
118HERE=&quot;$(cd &quot;$(dirname &quot;$0&quot;)&quot; && pwd)&quot;
119 
120DRAFT_ID=$(cutcli draft create --width 1080 --height 1920 --name &quot;&lt;id&gt;&quot; | jq -r '.draftId')
121 
122# ... 加内容
123cutcli captions add &quot;$DRAFT_ID&quot; --captions &quot;@$HERE/data/captions.json&quot; ...
124
125cutcli draft info &quot;$DRAFT_ID&quot; --pretty
126```
127 
128要求：
129 
130- 顶部 shebang `#!/usr/bin/env bash`
131- `set -euo pipefail`
132- 用 `cutcli`（不是 `cut`）
133- 用 `chmod +x run.sh`
134- 用 `@$HERE/data/file.json` 引用 JSON（不要内联在命令行里转义）
135- 输出关键变量给用户参考
136 
137## 素材 URL 白名单
138 
139`run.sh` 和 `data/*.json` 中的 URL 必须匹配以下之一：
140 
141```regex
142^https://cutcli\.com/
143^https://[a-z0-9-]+\.r2\.dev/
144^https://[a-z0-9-]+\.r2\.cloudflarestorage\.com/
145^https://cdn\.jsdelivr\.net/
146^https://raw\.githubusercontent\.com/
147^https://[a-z0-9-]+\.githubusercontent\.com/
148```
149 
150不允许：
151 
152- `http://` 明文
153- 个人云盘 / OSS 私链
154- 带 query token 的临时签名 URL
155 
156## 时间单位
157 
158**所有时间字段都是微秒**：
159 
160| 期望 | 写法 |
161|---|---|
162| 0.5 秒 | `500000` |
163| 3 秒 | `3000000` |
164| 30 秒 | `30000000` |
165 
166错写毫秒（如 `3000` = 3ms）字幕只闪一帧。
167 
168## 关键帧的 segmentId 怎么拿
169 
170`segmentId` 在 add 之前不存在。脚手架模式：
171 
172```bash
173# 1. 先 add 片段
174cutcli images add &quot;$DRAFT_ID&quot; --image-infos @data/images.json
175 
176# 2. 用 list 拿回 segmentId
177SEG=$(cutcli images list &quot;$DRAFT_ID&quot; | jq -r '.[0].segmentId')
178 
179# 3. 用 jq 替换模板里的 __SEG_ID__
180KFS=$(jq --arg seg &quot;$SEG&quot; '[.[] | .segmentId = $seg]' &quot;$HERE/data/keyframes.template.json&quot;)
181 
182# 4. add 关键帧
183cutcli keyframes add &quot;$DRAFT_ID&quot; --keyframes &quot;$KFS&quot;
184```
185 
186参考 `examples/05-keyframe-zoom-in/run.sh`。
187 
188## 校验
189 
190提交前必跑：
191 
192```bash
193node scripts/validate-example.mjs examples/&lt;your-case&gt;
194bash examples/&lt;your-case&gt;/run.sh    # 实际跑一遍，剪映打开看效果
195```
196 
197校验项：
198 
199- [ ] `run.sh` / `README.md` / `meta.json` 存在
200- [ ] `README.zh.md` 存在（`npm run lint:i18n` 强制中英成对）
201- [ ] `run.sh` chmod +x、有 shebang、有 `set -euo pipefail`
202- [ ] `meta.json` 通过 ajv schema（`description` 英文，可选 `description_zh` 中文）
203- [ ] `README.md` 5 个英文章节齐全；`README.zh.md` 5 个中文章节齐全
204- [ ] `data/*.json` 都是合法 JSON
205- [ ] 所有 URL 在白名单内
206- [ ] README 不含本地路径 `/Users/...`
207 
208## 脚手架（推荐入口）
209 
210```bash
211node scripts/new-example.mjs my-case-slug
212# 按提示输入 author / title / tags / duration / resolution / description
213# 自动生成 examples/99-community/<author>/my-case-slug/{README.md,README.zh.md,run.sh,meta.json,data/}
214```
215 
216脚手架生成的 `README.md` 是英文骨架（5 段英文 H2），`README.zh.md` 是中文骨架（5 段中文 H2）。两者都已经填好双语切换链接。
217 
218## 最后
219 
220- 拿不准的 case 复杂度，先看 `examples/01~05`（最简单的样板）
221- 想做长视频，看 `examples/10~30`（30s~60s）
222- 装饰元素（贴纸/特效/滤镜）先 `cutcli query` 找 ID，再 add
223