pr-open

PR 创建技能

在 bklit-ui 中提交工作并创建可合并 PR 的端到端工作流。

当用户想要添加、提交、验证、推送并创建 PR，或提到 @pr-open 时，请阅读此技能。

---

开始之前

1. 确认分支上下文

   • 如果用户已在此分支上合并了之前的 PR，且现在有新改动，请从最新的 main 分支创建分支，而不是在过时的功能分支上继续叠加：

     git fetch origin main
     git checkout -b <new-branch-name> origin/main
     

   • 仅重新应用或 cherry-pick 预期的改动；不要提交无关的 registry:build 噪声（例如重新格式化 packages/ui/registry/examples/*，除非这些编辑是有意的）。

2. 绝不提交机密信息——跳过 .env、凭据、API 密钥等。如果用户要求提交这些内容，请提醒用户。

3. Git 安全（必需）

   • 不要更新 git 配置。
   • 不要运行破坏性命令（push --force、reset --hard），除非用户明确要求。
   • 不要跳过钩子（--no-verify），除非用户明确要求。
   • 除非满足用户 git 规则中的所有 amend 条件（HEAD 提交由你创建且尚未推送，或用户要求 amend），否则不要运行 git commit --amend。
   • 如果提交因钩子而失败，请修复问题并创建一个新提交——不要 amend 失败的提交。
   • 使用 HEREDOC 编写提交消息（见下文）。
   • 除非用户要求推送或创建 PR，否则不要推送。

---

步骤 1 — 检查改动

在仓库根目录并行运行：

git status
git diff
git diff --staged
git log -5 --oneline

如果要创建 PR，还要检查与基准分支的差异：

git fetch origin main
git log origin/main..HEAD --oneline
git diff origin/main...HEAD --stat

拟定一条说明原因而不只是说明改了什么的提交消息。遵循仓库近期的风格（例如 feat(charts): …、fix(web): …）。

---

步骤 2 — 暂存并提交（提交前循环）

暂存

git add <paths>   # prefer explicit paths over blind git add -A

提交

git commit -m "$(cat <<'EOF'
<subject line>

<optional body — 1–2 sentences on why>
EOF
)"

Husky 的提交前钩子会运行 npx ultracite fix（见 .husky/pre-commit）。

如果提交前钩子失败或留下未暂存的修复

1. 阅读钩子输出并修复报告的所有问题（lint 正确性、嵌套三元表达式、仅在合理时使用 biome-ignore 等）。
2. 重新暂存受影响的文件：git add <paths>
3. 使用一个新提交再次提交（仅当 amend 规则允许，且之前的提交成功但钩子自动修改了文件时，才可 amend）。

重复上述步骤，直到 git commit 成功，且 git status 干净（没有遗留的钩子格式化改动）。

---

步骤 3 — 从仓库根目录运行 Ultracite

提交干净后，运行根目录中的 pnpm 脚本（除非是修复一次性问题，否则不要直接运行 npx ultracite）：

pnpm lint          # ultracite check

如果检查失败：

pnpm lint:fix      # ultracite fix (same as pnpm format)

然后：

1. 检查 git diff 中是否有意外改动。
2. 如果文件有改动：git add <paths> → git commit -m "$(cat <<'EOF' Fix lint issues from ultracite EOF )"
3. 重新运行 pnpm lint，直到检查通过且没有待处理的修复。

pnpm lint 失败或 lint 修复尚未暂存时，不要创建 PR。

---

步骤 4 — 重建 shadcn registry（必需）

在每个 PR 的生产构建之前，务必运行此步骤——不仅是在 packages/ui 有改动时才运行。apps/web/public/r/ 下的 registry 产物必须与已提交的 UI 包保持同步。

在仓库根目录运行：

pnpm registry:build

此操作会根据 packages/ui 更新 apps/web/public/r/（见 packages/ui/package.json → registry:build）。

1. 构建后检查 git diff。纳入 apps/web/public/r/ 下有意进行的改动。
2. 不要提交 packages/ui/registry/examples/* 下偶然产生的重新格式化改动，除非这些编辑是有意的。
3. 如果 apps/web/public/r/（或在你编辑过的情况下，packages/ui/registry.json）有改动：

git add apps/web/public/r packages/ui/registry.json
git commit -m "$(cat <<'EOF'
chore(registry): rebuild shadcn registry for PR
EOF
)"

4. 如果 public/r/ 之外的源文件有改动，请重新运行步骤 3（pnpm lint）。

registry 输出过期时，不要创建 PR（运行 registry:build 后，apps/web/public/r/ 仍有未提交的差异）。

第 5 步 — 测试构建

执行生产构建，在提交 PR 前发现类型和编译错误。

默认（整个 monorepo）：

pnpm build

仅 Web 应用（更改仅涉及 apps/web 时速度更快）：

cd apps/web && pnpm build

如果 Web 构建在开发或类似 CI 的环境中因内存不足而失败，可增加堆内存后重试：

cd apps/web && NODE_OPTIONS='--max-old-space-size=8192' pnpm build

可选但推荐：更改 TypeScript 代码时执行：

pnpm check-types

如果构建失败

1. 修复根本原因（类型、导入、缺少注册表文件等）。
2. 重新运行失败的命令，直到通过。
3. 使用清晰的消息提交修复，然后重新运行第 3 步（pnpm lint）；如果更改了 packages/ui 下的源文件，还要重新运行第 4 步（pnpm registry:build）。

---

第 6 步 — 推送

仅当用户要求推送或创建 PR 时执行：

git push -u origin HEAD

如果分支已推送，且你又添加了提交，只需运行 git push。

---

第 7 步 — 创建 PR

在仓库根目录使用 GitHub CLI：

gh pr create --title "<PR title>" --body "$(cat <<'EOF'
## Summary

- <bullet: what changed and why>
- <bullet: user-facing impact>
- <bullet: follow-ups or deploy notes if any>

## Test plan

- [ ] `pnpm lint` passes at repo root
- [ ] `pnpm registry:build` run; `apps/web/public/r/` committed if updated
- [ ] `pnpm build` (or `apps/web` build for web-only changes)
- [ ] <manual verification step 1>
- [ ] <manual verification step 2>

EOF
)"

将 PR URL 返回给用户。

PR 标题规范

• 简短、祈使、范围明确（例如 Add @bklit/chart-animation registry item）
• 尽可能与主要提交的主题保持一致

PR 正文模板（每次都复制此结构）

## Summary

- <1–3 bullets: what and why>

## Test plan

- [ ] `pnpm lint` passes at repo root
- [ ] `pnpm registry:build` run; registry outputs committed if changed
- [ ] Production build succeeds (`pnpm build` or scoped web build)
- [ ] <feature-specific check>
- [ ] <regression check if applicable>

仅在有用时添加额外章节：

• 背景 — 链接到已合并的 PR 或议题（例如“后续工作：#70”）
• 部署说明 — 例如，Open in v0 需要 ui.bklit.com 上的注册表 JSON 已上线

仓库专属 PR 备注

• 注册表：第 4 步始终运行 pnpm registry:build；如果构建更新了 apps/web/public/r/，请提交该目录。
• 不要提交 registry:build 在 packages/ui/registry/examples/* 中产生的非必要格式调整，除非这些调整是有意为之。
• 图表或文档相关工作：在适用时说明对文档页面、Studio 或 Open in v0 进行的手动检查。

---

完整检查清单（速查）

步骤	命令 / 操作	进入下一步前必须通过
1	git status / git diff / git log	了解更改范围
2	git add → git commit	提交前钩子通过；工作树干净
3	pnpm lint → 如有需要则运行 pnpm lint:fix → 重新提交	pnpm lint 以状态码 0 退出
4	pnpm registry:build → 如果有更改则提交 apps/web/public/r/	注册表差异无过期内容
5	pnpm build（如果更改了 TS，还要运行 pnpm check-types）	构建以状态码 0 退出
6	git push -u origin HEAD	仅当用户要求推送或创建 PR 时
7	使用 Summary + Test plan 运行 gh pr create	返回 PR URL

---

常见故障

故障	修复方法
提交前 biome 检查报错	修复代码；仅在有一行说明理由时添加 biome-ignore
钩子修复了文件，但提交已成功	运行 git add 并创建新提交（如果允许，也可 amend）
提交后 pnpm lint 失败	运行 pnpm lint:fix，检查差异，提交，然后重新运行 pnpm lint
注册表使用方出现 Can't resolve './animation'	添加缺失的 @bklit/* 注册表依赖；运行 pnpm registry:build
Web 构建因内存不足而失败	为 apps/web 构建设置 NODE_OPTIONS='--max-old-space-size=8192'
PR 分支已合并	从 origin/main 创建新分支，只重新应用新的更改

---

示例流程

用户：“提交这些更改并创建 PR”

1. git status + git diff + git log -3
2. git add apps/web packages/ui → git commit（修复提交前检查的问题，直到通过）
3. pnpm lint → 如有需要则运行 pnpm lint:fix → 提交 → pnpm lint
4. pnpm registry:build → 如果有更改则提交 apps/web/public/r/
5. pnpm build（修复问题直到构建通过）→ 如有需要则提交
6. git push -u origin HEAD
7. 使用 Summary + Test plan 模板运行 gh pr create
8. 回复 PR 链接，并用一句话概述已验证的内容