Cursor rule

1---
2description: "cutcli-cookbook 提交流程：commit message 风格、PR 流程、CI 通过线、分支保护"
3globs: "**/*"
4alwaysApply: true
5---
6 
7# 提交流程
8 
9## 提交前自检（必跑）
10 
11```bash
12npm run lint            # cases + commands + links 全过
13npm run docs:build      # VitePress 构建无错
14```
15 
16如果改动了案例：
17 
18```bash
19node scripts/validate-example.mjs examples/<your-case>
20bash examples/<your-case>/run.sh    # 真跑一遍，剪映打开验证
21```
22 
23如果改动了 Worker：
24 
25```bash
26cd worker && npx tsc --noEmit       # type-check
27cd worker && npx wrangler dev       # 本地起测一下
28```
29 
30## Conventional Commits
31 
32格式：
33 
34```text
35<type>(<scope>): <subject>
36 
37[可选正文]
38 
39[可选 footer，如 BREAKING CHANGE / Closes #123]
40```
41 
42| type | 用途 |
43|---|---|
44| `feat` | 新功能、新案例、新模板 |
45| `fix` | bug 修复 |
46| `docs` | 文档变更（含 README、guide、cookbook） |
47| `chore` | 构建脚本、依赖升级、CI、配置 |
48| `refactor` | 重构、不影响行为 |
49| `test` | 测试代码 |
50| `style` | 仅格式调整 |
51 
52scope 推荐：`examples` / `templates` / `prompts` / `docs` / `worker` / `scripts` / `ci` / `release`
53 
54例子：
55 
56```text
57feat(examples): add 06-cinematic-title with bouncy text
58fix(worker): handle trailing slash in path resolution
59docs(guide): translate first-draft.md to English
60chore(ci): bump cloudflare/wrangler-action to v3.5
61refactor(scripts): extract walk() into _lib
62```
63 
64## PR 流程
65 
661. **Fork 或创建分支**
67```bash
68   git checkout -b feat/my-case
69```
702. **改动 + 自检**（见上文）
713. **Push 到 origin**
72```bash
73   git push -u origin feat/my-case
74```
754. **开 PR**
76```bash
77   gh pr create --title &quot;feat(examples): add my-case&quot; --body-file &lt;(cat &lt;&lt;'EOF'
78   ## 这个 PR 做了什么？
79   ...
80   ## 自检
81   - [x] npm run lint 通过
82   - [x] bash examples/my-case/run.sh 本地跑成功
83   - [x] preview.gif 已加（≤3 MB）
84   EOF
85   )
86```
875. **等 CI 绿**（约 1-2 分钟）
886. **等 review**：默认要 1 个 approve
89 
90## CI 必过线
91 
92PR 必须满足：
93 
94| 检查 | workflow | 任务 |
95|---|---|---|
96| Lint | `ci.yml` | `npm run lint:cases / lint:cmds / lint:links` |
97| 文档构建 | `ci.yml` | `npm run docs:build` |
98| Worker 类型检查 | `ci.yml` | `cd worker && npx tsc --noEmit` |
99 
100合并到 `main` 后还会自动跑：
101 
102| Workflow | 触发 | 内容 |
103|---|---|---|
104| `deploy-docs.yml` | push 到 main 且改了 `docs/` 或 `worker/` | build + R2 上传 + worker deploy + smoke test |
105| `scheduled-cases-test.yml` | 每天 02:00 UTC+8 | 跑全部案例校验，失败自动开 issue |
106 
107## 分支保护
108 
109`main` 启用以下保护（首次部署后由维护者一次性设置）：
110 
111```bash
112gh api repos/xuliang2024/cutcli-cookbook/branches/main/protection \
113  --method PUT \
114  --field required_status_checks[strict]=true \
115  --field required_status_checks[contexts][]='Lint (cases + commands + links)' \
116  --field required_status_checks[contexts][]='VitePress build' \
117  --field enforce_admins=false \
118  --field required_pull_request_reviews[required_approving_review_count]=1 \
119  --field restrictions=null
120```
121 
122## 不要做的事
123 
124- ❌ 直接编辑 `docs/reference/cli.md` / `api.md` / `concepts.md`（由同步脚本生成）
125- ❌ 引用 `cut <subcommand>` 命令名（用 `cutcli`）
126- ❌ 提交 `.env` 文件或任何含 token / cookie 的内容
127- ❌ 把私有 CDN 链接（带 query token）写进 case
128- ❌ 提交 > 3 MB 的 preview.gif（会被 CI 警告）
129- ❌ 跨用例修改超过 5 个文件 — 请拆成多个 PR
130 
131## 应急回滚
132 
133```bash
134# 上一个 commit 出 bug，但已 push 到 main
135git revert HEAD
136git push
137 
138# CI deploy-docs 自动重跑，约 1 分钟内 docs.cutcli.com 回到旧版本
139```
140 
141## 闭源同步配套
142 
143如果改动了闭源 `jy_cli/docs/cli.md` 等需要传到公开仓：
144 
145```bash
146cd /Users/m007/codes/jy_cli
147node scripts/sync-to-cookbook.mjs
148
149cd /Users/m007/codes/cutcli-cookbook
150git status -s docs/reference/    # 看是哪些文件变了
151git add docs/reference && git commit -m &quot;docs(sync): sync from jy_cli@&lt;short-sha&gt;&quot;
152git push
153```
154