1k-create-pr

创建 OneKey App PR

自动完成 OneKey app-monorepo 更改的完整 PR 创建工作流。

快速参考

步骤	操作	命令
1	检查状态	git status、git branch --show-current
2	确定基础分支	自动检测或询问用户
3	创建分支（如果当前位于 x 或 release/*）	git checkout -b <branch-name>
4	Agent 检查	yarn agent:check --profile commit
5	暂存并提交	git add .、git commit -m "type: description"
6	推送到远程	git push -u origin <branch-name>
7	提取上下文	分析对话以了解意图、决策和风险
8	创建 PR	gh pr create --base <base> --title "..." --body "..."
9	更新分支	gh pr update-branch <number>
10	启用自动合并	gh pr merge <number> --auto --squash
11	返回 PR URL	与用户分享 PR URL

工作流

1. 检查当前分支状态

git status
git branch --show-current

2. 确定基础分支

PR 的基础分支取决于当前分支从哪个分支创建。

自动检测逻辑：

VERSION=$(grep -E '^VERSION=' .env.version | cut -d '=' -f 2)
RELEASE_BRANCH="release/v${VERSION}"

# Compare distance to both candidate base branches
# (--is-ancestor would give false positives when release branch just forked from x)
release_distance=$(git rev-list --count "origin/$RELEASE_BRANCH"..HEAD 2>/dev/null || echo 999999)
x_distance=$(git rev-list --count origin/x..HEAD 2>/dev/null || echo 999999)

if [ "$release_distance" -lt "$x_distance" ]; then
  BASE="$RELEASE_BRANCH"
else
  BASE="x"
fi

如果当前直接位于 x 或 release/* 上（而非功能分支），自动检测会有歧义。此时，创建功能分支前先询问用户：

"你当前直接位于 $current_branch 上。PR 应以哪个分支为目标？"

• x — 常规开发（非 bundle）
• $RELEASE_BRANCH — bundle 发布

这将决定功能分支以哪个分支为基础。

3. 分支处理

如果当前位于 x 或 release/* 分支上（而非功能分支）：

• 如果尚未确定 PR 目标分支，询问用户（见上面的步骤 2）
• 分析当前更改（已暂存和未暂存）
• 根据更改生成描述性分支名称：
  • feat/ — 新功能
  • fix/ — 错误修复
  • refactor/ — 重构
  • chore/ — 维护任务
• 创建并切换分支：git checkout -b <branch-name>
  • 如果基础分支是 x，则从当前 x 创建分支
  • 如果基础分支是 release/*，则获取最新内容，并从 origin/$RELEASE_BRANCH 创建分支

**如果当前已位于功能分支：**跳过创建分支，使用自动检测的基础分支

4. 运行 Agent 检查

yarn agent:check --profile commit

提交前修复所有报告的 lint 或类型错误。只有在调试 agent:check 报告的日志路径时，才使用底层的 lint/typecheck 命令。

5. 暂存并提交更改

git add .
git commit -m "<type>: <description>"

提交格式：

• 遵循常规提交规范
• 不要添加 Claude 签名或 Co-Authored-By

6. 推送到远程

git push -u origin <branch-name>

PR 创建后，使用统一的 PR 就绪检查：

yarn agent:check --profile pr

7. 提取上下文和意图（关键）

创建 PR 前，分析完整的对话历史，提取以下信息：

• 意图：为什么要进行这些更改？要解决什么问题？
• 根本原因：如果这是错误修复，根本原因是什么？
• 设计决策：考虑过哪些方案？为什么选择当前方案？
• 权衡：是否有妥协或已知限制？
• 风险区域：更改中哪些部分风险最高或最复杂？
• 平台影响：影响哪些平台（桌面端/移动端/Web/扩展程序）？
• 相关问题：对话中是否提及任何 OK-{number} 问题 ID？

上下文提取指南：

1. 用户的原始请求 — 用户提出了什么要求？如有帮助，可引用关键短语。
2. 问题诊断 — 如何发现并理解该问题？
3. 实现理由 — 为什么选择这种特定方案，而不是其他方案？
4. 讨论过的约束 — 用户提到了哪些约束或要求？
5. 考虑过的边缘情况 — 开发过程中讨论了哪些边缘情况？
6. 安全注意事项 — 讨论过哪些安全影响？
7. 性能注意事项 — 讨论过哪些性能权衡？

8. 创建包含上下文的 Pull Request

gh pr create --base $BASE --title "<title>" --body "<description>"

使用第 2 步确定的 $BASE（x 或 release/v{X.Y.Z}）。

Issue ID 处理：

• 从提交摘要/描述和对话历史中提取 OK-{number}
• 将其附加到 PR 标题中：fix: description(OK-49185)
• 左括号前不要加空格

PR 正文模板：

PR 正文必须使用此模板。省略不适用的部分（不要写“ N/A”）。

## Summary
<1-3 bullet points describing WHAT changed>

## Intent & Context
<WHY these changes were made. What problem was being solved? What was the user's original request or the bug report that triggered this work?>

## Root Cause
<For bug fixes: What was the root cause? How was it diagnosed?>

## Design Decisions
<Key decisions made during implementation and WHY. Alternatives considered and reasons for the chosen approach.>

## Changes Detail
<Brief description of each significant file change and its purpose>

## Risk Assessment
- **Risk Level**: Low / Medium / High
- **Affected Platforms**: Extension / Mobile / Desktop / Web
- **Risk Areas**: <Which parts of the change are riskiest?>

## Test plan
- [ ] <Testing steps to verify the changes>

9. 更新分支

将 PR 分支与最新的基础分支同步，以确保 CI 在合并后的状态上运行：

gh pr update-branch <PR_NUMBER>

这等同于点击 GitHub PR 页面上的“Update branch”按钮。

10. 启用自动合并

gh pr merge <PR_NUMBER> --auto --squash

11. 返回 PR URL

向用户显示 PR URL 并在浏览器中打开：

open <PR_URL>

重要说明

• 基础分支会自动检测：对于 bundle 发布分支，使用 release/*；其他情况使用 x。如果当前直接位于 x 或 release/* 上，请在创建功能分支前询问用户要使用哪个目标分支。
• 使用约定式提交格式：type: description
• 提取并将 issue ID（OK-{number}）附加到 PR 标题
• 必须提取上下文：PR 描述必须体现对话上下文。不要创建通用描述。代码审查 AI 依赖这些上下文来理解更改背后的意图。
• 所有 PR 内容都必须使用英语：标题、正文（摘要、更改、测试计划）、分支名称和提交消息。绝不要使用中文或其他语言。