create-pr

创建拉取请求

按照规范创建 PR：本地验证、符合 Conventional Commits 规范的标题、模板化正文，以及可选的关联工单。此技能与语言和框架无关——请将示例中的构建、代码检查、测试和格式化命令替换为项目实际使用的命令。

前提条件

开始前，请确认：

1. 当前分支包含基分支上没有的提交（git log origin/<base-branch>..HEAD --oneline）
2. 分支已推送到远程（如果尚未推送，请运行 git push -u origin HEAD）
3. 没有应纳入 PR 但尚未提交的更改（git status）

工作流

1. 了解更改

并行运行：

git log origin/<base-branch>..HEAD --oneline
git diff origin/<base-branch>..HEAD --stat

确定：

• 更改内容：修改了哪些模块、软件包、服务或目录
• 更改类型：feat、fix、docs、refactor、test、chore、perf、ci、build、revert
• 范围：受影响的主要模块／软件包／服务（跨领域更改请使用目录名或 monorepo／repo）
• 是否为代码更改？：如果 PR 修改了源代码（不只是文档、markdown 或仅配置文件），请在创建 PR 前运行第 2 步中的本地验证清单。

2. 本地验证（针对代码更改）

如果 PR 仅涉及文档、markdown 文件或其他非代码文件，请跳过此步骤。对于涉及源文件的任何更改，请在创建 PR 前在本地运行项目的验证命令。

通过查看仓库根目录中的文件来查找命令（例如 Makefile、package.json、pyproject.toml、Cargo.toml、go.mod、build.gradle、mix.exs、Gemfile、composer.json、justfile、Taskfile.yml、README.md 或 CI 工作流配置）。如果支持筛选器／目标标志，请使用它们仅运行受影响的部分（例如 turbo --filter、nx --projects、pnpm --filter、bazel //path/...、cargo -p <crate>、pytest <path>、go test ./<pkg>/...）——这比运行整个仓库更快。

适用时，请运行以下常见类别的验证：

类型检查／编译

如果项目有静态类型检查或编译步骤，请运行。

各生态系统示例（请使用仓库定义的命令）：

• TypeScript：npm run typecheck、pnpm -r typecheck、tsc --noEmit
• Python（带类型标注）：mypy .、pyright、ty check
• Rust：cargo check
• Go：go build ./...、go vet ./...
• Java/Kotlin：./gradlew compileJava、./mvnw compile

代码检查／格式化

运行项目的代码检查工具和格式化工具。如果有自动修复目标，请优先使用。

示例：

• JS/TS：npm run fix、npm run lint、eslint .、prettier --check .
• Python：ruff check --fix .、ruff format .、black .、flake8
• Rust：cargo clippy --all-targets、cargo fmt --check
• Go：golangci-lint run、gofmt -l .
• Shell：shellcheck、shfmt -d .

测试

运行受影响软件包的单元／集成测试。

示例：

• JS/TS：npm run test -- --filter=<workspace>、pnpm -r test、vitest run <path>、jest <path>
• Python：pytest <path>、tox -e <env>、python -m unittest
• Rust：cargo test -p <crate>
• Go：go test ./<pkg>/...
• Java/Kotlin：./gradlew test、./mvnw test
• Ruby：bundle exec rspec <path>、rake test

其他检查（在相关时运行）

• 未使用的导出 / 死代码：如果项目提供死代码检查，请运行（例如，Python 的 knip、ts-prune、vulture，Go 的 deadcode / unused，Rust 的 cargo udeps）。
• 依赖项规范性：如果项目提供依赖项检查，请运行（例如，depcheck、pip check、cargo audit、bundle audit）。
• 锁文件保持同步：如果修改了任何依赖清单（package.json、requirements.txt、pyproject.toml、Cargo.toml、go.mod、Gemfile 等），请运行安装命令（npm install、pnpm install、uv sync、poetry lock --no-update、cargo update -w、go mod tidy、bundle install），并提交任何锁文件更改。如果锁文件过期，CI 通常会失败。
• 生成代码 / 代码生成：如果仓库中有 OpenAPI 规范、protobuf、GraphQL 架构、SQL 迁移或其他生成的制品，请重新生成并提交任何更改。
• 样式 / 资源检查工具：如果修改了样式表或资源文件，请运行样式表检查工具（stylelint 等）或资源检查工具。
• 安全扫描：运行仓库中配置的安全 / 密钥扫描工具（trivy、semgrep、gitleaks 等）。

3. 关联工单（可选）

如果组织使用问题跟踪系统，请询问用户是否要：

• 创建新工单：使用相应工具（Linear、Jira、GitHub Issues 等）
• 关联现有工单：询问工单标识符（例如，TEAM-1234、JIRA-567、#42）
• 跳过：仅当用户明确表示不需要工单时

大多数 CI 系统都可以配置为要求在 PR 正文中填写工单标识符。请遵循组织的惯例。

4. 设置 PR 标题格式

遵循 Conventional Commits：type(scope): description

• type：feat、fix、docs、refactor、test、chore、perf、ci、build、revert
• scope：受影响的模块 / 软件包 / 服务 / 目录名称；对于跨领域更改，使用 monorepo / repo。多个范围可以用逗号分隔：fix(a, b, c): ...

示例：

• feat(web): add dark mode toggle
• fix(cli, daemon): load shell env at entrypoint
• fix(api): handle nil response from upstream
• chore(repo): bump dependencies

5. 生成 PR 正文

填写 PR 模板中的所有部分。典型模板包含四个部分：

## Description

<concise summary of what changed and why>

## Related Issue

Closes TEAM-XXXX


## Potential Risk & Impact

<list risks, performance implications, technical debt>


## How Has This Been Tested?

<describe testing performed: unit tests, manual testing, typecheck, lint>

6. 创建 PR

gh pr create \
  --base <base-branch> \
  --head <branch-name> \
  --title "<type>(<scope>): <description>" \
  --body "<generated body>"

如果正文较长，请将其写入临时文件，并使用 --body-file：

gh pr create --base <base-branch> --head <branch> --title "..." --body-file /tmp/pr-body.md

7. 报告结果

向用户返回 PR URL。

CI 检查参考（模板）

以下是每个 PR 都会运行的典型检查类别。改编此技能时，请将它们映射到仓库中的实际命令。

始终运行的检查

类别	检查内容	如何查找本地命令
类型检查 / 编译	验证项目是否可编译或通过静态类型检查	检查 package.json、Makefile、pyproject.toml、Cargo.toml、go.mod 和 CI 配置
Lint	执行代码样式 / 正确性规则	检查仓库根目录中的 lint、check 或同类脚本
格式化	确保格式一致	检查 format、fmt、prettier、black、gofmt、rustfmt 等
测试	运行单元测试和集成测试	检查 test 脚本 / 目标
死代码 / 未使用的导出	标记未使用的代码	检查 knip、ts-prune、vulture、cargo udeps 等
依赖项检查	标记未使用 / 易受攻击的依赖项	检查 depcheck、audit、cargo audit 等
锁文件保持同步	如果锁文件相对于依赖清单已过期，则检查失败	运行包管理器的安装命令并提交锁文件
PR 惯例	验证分支名称、语义化标题和工单是否存在	遵循上述格式规则

条件检查（仅在受影响的文件发生更改时运行）

• API / 架构验证：在 API 或架构发生更改时触发。在本地重新生成。
• 特定平台的构建：在桌面端／移动端／嵌入式目标受到影响时触发。
• E2E 测试：在消费者应用或顶层二进制文件受到影响时触发。

CI 强制执行的常见 PR 规范

• 分支名称：长度上限、允许使用的字符（例如 [A-Za-z0-9/-]）。
• 标题：使用带有效作用域的 Conventional Commits 格式。
• 工单引用：PR 正文必须包含工单标识符（chore: 和 revert: 类型通常除外）。

应避免的常见错误

• 基准分支错误：使用组织接收 PR 的分支（例如 dev、main、develop、trunk）。
• 缺少作用域：PR 标题的 CI 检查通常要求提供有效作用域。
• 缺少工单引用：描述必须引用工单 ID，CI 才能通过（chore:／revert: 除外）。
• 忘记推送：执行 gh pr create 前，分支必须已推送到远程仓库。
• 锁文件未同步：依赖项更改后，务必运行安装命令并提交锁文件更改。
• 代码 PR 跳过本地检查：提交代码更改前，应在本地运行类型检查／编译、lint 和测试，以便及早发现问题，避免反复等待 CI。
• 未提交生成的产物：更改 API／架构后，重新生成并提交。