pr-open

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Open Skill

PR 创建技能

End-to-end workflow for committing work and opening a merge-ready PR in bklit-ui.

Read this skill when the user wants to add, commit, validate, push, and open a PR — or references

@pr-open

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

当用户需要添加、提交、验证、推送代码并打开 PR，或提及

@pr-open

时，遵循本技能流程。

Before you start

开始之前

Confirm branch context
- If the user merged an earlier PR on this branch and there are new changes, branch from latest
```
main
```
  instead of stacking on a stale feature branch:
  bash
```
git fetch origin main
git checkout -b <new-branch-name> origin/main
```
- Re-apply or cherry-pick only the intended changes; do not commit unrelated
```
registry:build
```
  noise (e.g. reformatted
```
packages/ui/registry/examples/*
```
  unless those edits are intentional).
Never commit secrets — skip
```
.env
```
, credentials, API keys, etc. Warn the user if they ask to commit them.
Git safety (required)
- Do not update git config.
- Do not run destructive commands (
```
push --force
```
  ,
```
reset --hard
```
  ) unless the user explicitly asks.
- Do not skip hooks (
```
--no-verify
```
  ) unless the user explicitly asks.
- Do not
```
git commit --amend
```
  unless all amend rules in the user's git rules are satisfied (HEAD commit is yours, not pushed, or user requested amend).
- If a commit fails due to a hook, fix the issue and create a new commit — do not amend a failed commit.
- Use HEREDOC for commit messages (see below).
- Do not push unless the user asked to push or open a PR.

确认分支上下文
- 如果用户已在此分支上合并过早期 PR 且有新变更，请基于最新的
```
main
```
  分支创建新分支，而非在过时的功能分支上叠加：
  bash
```
git fetch origin main
git checkout -b <new-branch-name> origin/main
```
- 仅重新应用或挑选目标变更；请勿提交无关的
```
registry:build
```
  冗余内容（例如，除非是有意修改，否则不要提交格式化后的
```
packages/ui/registry/examples/*
```
  文件）。
切勿提交敏感信息 —— 跳过
```
.env
```
、凭证、API 密钥等文件。如果用户要求提交这些内容，需发出警告。
Git 操作安全规范（必填）
- 不要修改 git 配置。
- 除非用户明确要求，否则不要执行破坏性命令（
```
push --force
```
  、
```
reset --hard
```
  ）。
- 除非用户明确要求，否则不要跳过钩子（
```
--no-verify
```
  ）。
- 除非满足用户 git 规则中的所有修改要求（HEAD 提交属于你、尚未推送，或用户要求修改），否则不要执行
```
git commit --amend
```
  。
- 如果提交因钩子失败，请修复问题并创建新提交 —— 不要修改失败的提交。
- 使用 HEREDOC 编写提交信息（见下文）。
- 除非用户要求推送或打开 PR，否则不要执行推送操作。

Step 1 — Inspect changes

步骤1：检查代码变更

Run in parallel from the repo root:

bash

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

If opening a PR, also check divergence from base:

bash

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

Draft a commit message that explains why, not just what. Match recent repo style (e.g.

feat(charts): …

fix(web): …

从仓库根目录并行执行以下命令：

bash

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

如果要打开 PR，还需检查与基准分支的差异：

bash

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

撰写提交说明，解释原因而非仅说明内容。匹配仓库近期的风格（例如

feat(charts): …

、

fix(web): …

）。

Step 2 — Stage and commit (pre-commit loop)

步骤2：暂存并提交代码（预提交循环）

Stage

暂存

bash

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

bash

git add <paths>   # 优先使用明确路径，而非盲目执行 git add -A

Commit

提交

bash

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

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

Husky pre-commit runs

npx ultracite fix

(see

.husky/pre-commit

bash

git commit -m "$(cat <<'EOF'
<主题行>

<可选正文——1-2句话说明原因>
EOF
)"

Husky 预提交钩子会执行

npx ultracite fix

（详见

.husky/pre-commit

）。

If pre-commit fails or leaves unstaged fixes

如果预提交失败或留下未暂存的修复内容

Read the hook output and fix every reported issue (lint correctness, nested ternaries,
```
biome-ignore
```
only when justified, etc.).
Re-stage affected files:
```
git add <paths>
```
Commit again with a new commit (or amend only if amend rules allow and the previous commit succeeded but the hook auto-modified files).

Repeat until

git commit

succeeds and

git status

is clean (no leftover hook formatting).

查看钩子输出，修复所有报告的问题（lint 正确性、嵌套三元表达式、仅在合理情况下使用
```
biome-ignore
```
等）。
重新暂存受影响的文件：
```
git add <paths>
```
再次提交，创建新提交（或仅在满足修改规则且之前提交成功但钩子自动修改了文件的情况下，修改提交）。

重复上述步骤，直到

git commit

执行成功且

git status

显示工作区干净（无钩子格式化遗留内容）。

Step 3 — Ultracite from repo root

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

After commits are clean, run the root pnpm scripts (not

npx ultracite

directly unless fixing a one-off):

bash

pnpm lint          # ultracite check

If check fails:

bash

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

Then:

Review
```
git diff
```
for unexpected changes.

If files changed:

git add <paths>

→

git commit -m "$(cat <<'EOF' Fix lint issues from ultracite EOF )"

Re-run
```
pnpm lint
```
until it passes with no fixes pending.

Do not open a PR while

pnpm lint

fails or while lint fixes are unstaged.

提交完成且工作区干净后，执行根目录的 pnpm 脚本（除非是修复一次性问题，否则不要直接执行

npx ultracite

）：

bash

pnpm lint          # ultracite 检查

如果检查失败：

bash

pnpm lint:fix      # ultracite 修复（与 pnpm format 功能相同）

然后：

查看
```
git diff
```
中的意外变更。

如果文件有变更：

git add <paths>

→

git commit -m "$(cat <<'EOF' 修复 ultracite 检测到的 lint 问题 EOF )"

重新执行
```
pnpm lint
```
，直到无修复项且执行成功。

在

pnpm lint

失败或存在未暂存的 lint 修复内容时，请勿打开 PR。

Step 4 — Test build

步骤4：测试构建

Run a production build to catch type and compile errors before the PR.

Default (whole monorepo):

bash

pnpm build

Web app only (faster when changes are confined to

apps/web

bash

cd apps/web && pnpm build

If the web build OOMs in dev/CI-like environments, retry with more heap:

bash

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

Optional but recommended when touching TypeScript:

bash

pnpm check-types

在创建 PR 前执行生产环境构建，以捕获类型和编译错误。

默认（整个 monorepo）：

bash

pnpm build

仅构建 Web 应用（当变更仅涉及

apps/web

时更快）：

bash

cd apps/web && pnpm build

如果在开发/类 CI 环境中 Web 构建出现内存不足（OOM），增加堆内存后重试：

bash

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

可选但推荐（当修改 TypeScript 代码时）：

bash

pnpm check-types

If build fails

如果构建失败

Fix the root cause (types, imports, missing registry files, etc.).
Re-run the failing command until it passes.
Commit fixes with a clear message, then re-run Step 3 (
```
pnpm lint
```
) if source files changed.

修复根本原因（类型错误、导入问题、缺失的 registry 文件等）。
重新执行失败的命令，直到成功。
用清晰的说明提交修复内容，若源文件有变更，重新执行步骤3（
```
pnpm lint
```
）。

Step 5 — Push

步骤5：推送代码

Only when the user asked to push or open a PR:

bash

git push -u origin HEAD

If the branch was already pushed and you added commits,

git push

is enough.

仅当用户要求推送或打开 PR 时执行：

bash

git push -u origin HEAD

如果分支已推送过且添加了新提交，执行

git push

即可。

Step 6 — Open the PR

步骤6：打开 PR

Use GitHub CLI from the repo root:

bash

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

从仓库根目录使用 GitHub CLI：

bash

gh pr create --title "<PR 标题>" --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 build
```
(or
```
apps/web
```
build for web-only changes)
<manual verification step 1>
<manual verification step 2>

EOF )"


Return the PR URL to the user.

仓库根目录下
```
pnpm lint
```
执行通过
```
pnpm build
```
执行成功（或针对仅 Web 应用变更执行
```
apps/web
```
构建）
<手动验证步骤1>
<手动验证步骤2>

EOF )"


将 PR URL 返回给用户。

PR title guidelines

PR 标题规范

Short, imperative, scoped (e.g.

Add @bklit/chart-animation registry item

)

Match the primary commit subject when possible

简短、祈使语气、明确范围（例如
```
Add @bklit/chart-animation registry item
```
）
尽可能与主要提交的主题匹配

PR body template (copy structure every time)

PR 正文模板（每次都遵循此结构）

markdown

undefined

markdown

undefined

Summary

摘要

<1–3 bullets: what and why>

<1-3个项目符号：变更内容及原因>

Test plan

测试计划

```
pnpm lint
```
passes at repo root
Production build succeeds (
```
pnpm build
```
or scoped web build)
<feature-specific check>
<regression check if applicable>


Add extra sections only when useful:

- **Context** — link to a merged PR or issue (e.g. "Follow-up to #70")
- **Deploy notes** — e.g. registry JSON must be live on `ui.bklit.com` for Open in v0

仓库根目录下
```
pnpm lint
```
执行通过
生产环境构建成功（
```
pnpm build
```
或针对 Web 应用的范围构建）
<功能专属检查项>
<回归检查项（如适用）>


仅在必要时添加额外章节：

- **上下文** —— 关联已合并的 PR 或 issue（例如 "后续工作：#70"）
- **部署说明** —— 例如，registry JSON 文件必须在 `ui.bklit.com` 上生效才能在 v0 版本中打开

Repo-specific PR notes

仓库专属 PR 注意事项

Registry changes: run
```
pnpm registry:build
```
from root (or
```
packages/ui
```
) before commit; include
```
apps/web/public/r/
```
outputs in the commit.
Do not commit incidental reformats from
```
registry:build
```
on
```
packages/ui/registry/examples/*
```
unless intentional.
Chart/docs work: mention manual checks for docs pages, Studio, or Open in v0 when relevant.

Registry 变更：提交前从根目录（或
```
packages/ui
```
）执行
```
pnpm registry:build
```
；将
```
apps/web/public/r/
```
输出文件包含在提交中。
请勿提交
```
registry:build
```
对
```
packages/ui/registry/examples/*
```
文件的附带格式化内容，除非是有意修改。
图表/文档相关工作：相关时需提及对文档页面、Studio 或 v0 版本中 Open 功能的手动检查。

Full checklist (quick reference)

完整检查清单（快速参考）


git status
git add
pnpm lint
pnpm build
git push -u origin HEAD
gh pr create

Step	Command / action	Must pass before next step
1	`git status` / `git diff` / `git log`	Understand scope
2	`git add` → `git commit`	Pre-commit hook clean; working tree clean
3	`pnpm lint` → `pnpm lint:fix` if needed → re-commit	`pnpm lint` exits 0
4	`pnpm build` (and `pnpm check-types` if TS changed)	Build exits 0
5	`git push -u origin HEAD`	Only if user requested push/PR
6	`gh pr create` with Summary + Test plan	PR URL returned


git status
git add
pnpm lint
pnpm build
git push -u origin HEAD
gh pr create

步骤	命令/操作	必须通过才能进入下一步
1	`git status` / `git diff` / `git log`	明确变更范围
2	`git add` → `git commit`	预提交钩子执行通过；工作区干净
3	`pnpm lint` → 必要时执行 `pnpm lint:fix` → 重新提交	`pnpm lint` 执行成功（退出码0）
4	`pnpm build` （若修改了TS代码则额外执行 `pnpm check-types` ）	构建执行成功（退出码0）
5	`git push -u origin HEAD`	仅当用户要求推送/PR时执行
6	使用摘要+测试计划模板执行 `gh pr create`	返回PR URL

Common failures

常见问题及修复方案

Failure	Fix
Pre-commit biome errors	Fix code; add `biome-ignore` only with a one-line justification
Hook fixed files but commit already succeeded	`git add` + new commit (or amend if allowed)
`pnpm lint` fails after commit	`pnpm lint:fix` , review diff, commit, re-run `pnpm lint`
`Can't resolve './animation'` in registry consumers	Add missing `@bklit/*` registry deps; run `pnpm registry:build`
Web build OOM	`NODE_OPTIONS='--max-old-space-size=8192'` for `apps/web` build
PR branch already merged	New branch from `origin/main` , re-apply only new changes

问题	修复方案
预提交阶段出现 biome 错误	修复代码；仅在有单行合理理由时添加 `biome-ignore`
钩子修复了文件但提交已成功	`git add` + 新提交（或在允许的情况下修改提交）
提交后 `pnpm lint` 失败	执行 `pnpm lint:fix` ，查看差异，提交修复内容，重新执行 `pnpm lint`
注册表消费者中出现 `Can't resolve './animation'`	添加缺失的 `@bklit/*` 注册表依赖；执行 `pnpm registry:build`
Web 构建内存不足（OOM）	为 `apps/web` 构建添加参数 `NODE_OPTIONS='--max-old-space-size=8192'`
PR 分支已合并	基于 `origin/main` 创建新分支，仅重新应用新变更

Example flow

示例流程

User: "commit this and open a PR"

```
git status
```
+
```
git diff
```
+
```
git log -3
```
```
git add apps/web packages/ui
```
→
```
git commit
```
(fix pre-commit until clean)
```
pnpm lint
```
→
```
pnpm lint:fix
```
if needed → commit →
```
pnpm lint
```
```
pnpm build
```
(fix until green) → commit if needed
```
git push -u origin HEAD
```
```
gh pr create
```
with Summary + Test plan template
Reply with PR link and one-line summary of what was validated

用户："提交代码并打开PR"

执行
```
git status
```
+
```
git diff
```
+
```
git log -3
```
执行
```
git add apps/web packages/ui
```
→
```
git commit
```
（修复预提交问题直到执行成功）
执行
```
pnpm lint
```
→ 必要时执行
```
pnpm lint:fix
```
→ 提交修复内容 → 重新执行
```
pnpm lint
```
执行
```
pnpm build
```
（修复问题直到成功）→ 必要时提交修复内容
执行
```
git push -u origin HEAD
```
使用摘要+测试计划模板执行
```
gh pr create
```
回复用户PR链接及一行验证内容摘要