create-pr

创建拉取请求

全面创建 PR 并进行验证。所有输出都会直接发送到 GitHub PR。

快速开始

create-pr
create-pr "Add user authentication"

CC ≥ 2.1.119 多主机说明（M122）： PR 创建支持 GitHub、GitLab、Bitbucket 和 GitHub Enterprise。根据已配置的远程端（git remote -v）检测目标主机，并根据主机系列选择合适的 CLI：

主机系列	CLI
github / github-enterprise	gh pr create（GHE 使用 GH_HOST=<host>）
gitlab / gitlab-self	glab mr create
bitbucket	bb pr create

自定义企业 URL：prUrlTemplate 设置（参见 src/skills/configure/ 和 src/skills/chain-patterns/references/pr-from-platform.md）。

参数解析

TITLE = "$ARGUMENTS"  # Optional PR title, e.g., "Add user authentication"
# If provided, use as PR title. If empty, generate from branch/commits.
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

基础分支解析

根据远程端确定基础分支。不要硬编码 dev 或 main；不同仓库可能有所不同。

BASE=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
BASE=${BASE:-main}   # ref missing (fresh/shallow clone)? run: git remote set-head origin -a

以下所有 $BASE 都指此值。

基于另一个未关闭的 PR 创建

如果此工作依赖于一个未关闭的 PR（“一个依赖 PR #50 的 PR”），则该 PR 的 head 分支是基础分支，而不是 $BASE：

PARENT=50
PARENT_BRANCH=$(gh pr view "$PARENT" --json headRefName -q .headRefName)
git fetch origin && git rebase "origin/$PARENT_BRANCH"   # pre-flight: sync with the parent
gh pr create --base "$PARENT_BRANCH" --title "$TYPE(#$ISSUE): ... [2/3]" \
  --body "Stacked on #$PARENT. Do not merge into the parent branch."

第 1 阶段的防护规则仍然适用：绝不能从 main 或 dev 创建 PR，工作区也不能有未提交的更改。在正文中记录 git rev-parse "origin/$PARENT_BRANCH"；父 PR 经过 squash 合并后，该 sha 就是 git rebase --onto "origin/$BASE" <that-sha> <branch> 所需的上游参数，而分支本身也会消失。有关 squash 恢复、深度上限和草稿陷阱：Read("references/stacked-pr.md")。

---

步骤 0：确认用户意图

创建任务之前，先确认 PR 类型：

AskUserQuestion(
  questions=[{
    "question": "What type of PR is this?",
    "header": "PR Type",
    "options": [
      {"label": "Feature (Recommended)", "description": "Full validation: security + quality + tests"},
      {"label": "Bug fix", "description": "Focus on test verification"},
      {"label": "Refactor", "description": "Code quality review, skip security"},
      {"label": "Quick", "description": "Skip validation, just create PR"}
    ],
    "multiSelect": false
  }]
)

根据回答调整工作流：

• 功能：完整执行第 2 阶段，包括 3 个并行 Agent 和本地测试
• 错误修复：执行第 2 阶段，仅使用 test-generator，并运行本地测试
• 重构：执行第 2 阶段，仅使用 code-quality-reviewer，并运行本地测试
• 快速处理：跳过第 2 阶段，直接进入第 3 阶段

可选的预检：claude ultrareview（CC 2.1.120+，#1542）

如果 claude ultrareview --help 执行成功，可选择在创建 PR 前运行该命令，并将发现的问题显示在 PR 正文的 ## Pre-flight 部分。此 CLI 子命令会返回结构化的 --json 输出，可筛选出高/中严重性问题写入正文，并在后续评论中发布完整结果。

if claude ultrareview --help >/dev/null 2>&1; then
  claude ultrareview "origin/$BASE..HEAD" --json > /tmp/ultra.json
  # Bucket by severity, put HIGH in PR body, MEDIUM/LOW as comment
fi

CC < 2.1.120 时跳过（该版本中不存在此子命令）。.github/workflows/ultrareview.yml 工作流会在 PR 创建时运行同一命令作为后备，因此此预检纯粹是为了加快反馈循环。

渐进式输出（CC 2.1.76）

创建 PR 时逐步输出结果：

步骤之后	向用户展示
预检	分支状态、远程同步结果
每个 Agent	Agent 返回时显示其验证结果
测试	测试结果、lint/类型检查状态
PR 已创建	PR URL、CI 状态链接

对于有 3 个并行 Agent 的功能 PR，应在每个 Agent 返回时展示其结果——不要等所有 Agent 都完成后才运行本地测试。

---

步骤 1：创建任务（必须）

在进行任何其他操作之前，先创建任务以跟踪进度：

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Create PR for {branch}", description="PR creation with validation", activeForm="Creating pull request")

# 2. Create subtasks for each phase
TaskCreate(subject="Pre-flight checks", activeForm="Running pre-flight checks")        # id=2
TaskCreate(subject="Run validation agents", activeForm="Validating with agents")       # id=3
TaskCreate(subject="Run local tests", activeForm="Running local tests")                # id=4
TaskCreate(subject="Create PR on GitHub", activeForm="Creating GitHub PR")             # id=5
TaskCreate(subject="Generate PR playground", activeForm="Generating playground")       # id=6

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Agents need pre-flight to pass
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Tests run after agent validation
TaskUpdate(taskId="5", addBlockedBy=["4"])  # PR creation needs tests to pass
TaskUpdate(taskId="6", addBlockedBy=["5"])  # Playground after PR (needs title/summary)

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

---

工作流

第 1 阶段：预检

加载 Read("rules/preflight-validation.md")，查看完整检查清单。

BRANCH=$(git branch --show-current)
[[ "$BRANCH" == "dev" || "$BRANCH" == "main" ]] && echo "Cannot PR from dev/main" && exit 1
[[ -n $(git status --porcelain) ]] && echo "Uncommitted changes" && exit 1

git fetch origin
git rev-parse --verify "origin/$BRANCH" &>/dev/null || git push -u origin "$BRANCH"

第 2 阶段：并行验证（功能/错误修复 PR）

在一条消息中启动 Agent。加载 Read("references/parallel-validation.md")，查看完整的 Agent 配置。

PR 类型	要启动的 Agent
功能	security-auditor + test-generator + code-quality-reviewer
错误修复	仅 test-generator
重构	仅 code-quality-reviewer
快速处理	无

Agent 完成后，运行本地验证：

# Adapt to project stack
npm run lint && npm run typecheck && npm test -- --bail
# or: ruff check . && pytest tests/unit/ -v --tb=short -x

第 3 阶段：收集上下文

BRANCH=$(git branch --show-current)
ISSUE=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
git log --oneline "origin/$BASE..HEAD"
git diff "origin/$BASE...HEAD" --stat

Phase 3b：Agent 归属信息（自动）

创建 PR 之前，检查分支活动日志 .claude/agents/activity/{branch}.jsonl 是否存在。 如果存在，则为 PR 正文生成 Agent 归属信息部分：

1. 读取 .claude/agents/activity/{branch}.jsonl（每行一个 JSON 对象，包含完整的分支历史）
2. 按 Agent 类型去重（每种 Agent 保留耗时最长的条目）
3. 生成以下部分并追加到 PR 正文：
   • 徽章行：显示 Agent 数量、生成的测试数、漏洞数的 shields.io 徽章
   • Agent 团队名单：包含 Agent、角色、阶段（Lead/⚡ Parallel/Follow-up）、耗时的 Markdown 表格
   • 致谢名单：按执行阶段（Lead/Parallel/Follow-up）分组的可折叠 <details> 部分
4. 每个 Agent 条目包含：agent（类型）、stage（0=lead、1=parallel、2=follow-up）、duration_ms、summary

如果日志不存在或为空，则跳过此步骤，正常创建 PR。

CC 2.1.183 — attribution.sessionUrl： Web 和 Remote Control 会话会在 PR 正文中附加 claude.ai 会话链接。对于不应公开此链接的公开仓库，请在创建 PR 之前设置 attribution.sessionUrl: false（/config attribution.sessionUrl=false）。ork 上述 Agent 归属信息部分不受此设置影响。

Phase 3c：CodeRabbit CLI 预审（运行 gh pr create 之前）

CodeRabbit PR 审查按 GitHub 身份实施速率限制（Essentials：7 天内审查数少于 30 次时，每小时补充 5 次；达到 60 次及以上时，每小时补充 1 次），且向已打开的 PR 推送任何内容都会消耗一次额度。CLI 有单独的额度，因此请先在本地审查分支差异。仅供参考，不会阻断流程。

CR_BIN=$(command -v coderabbit || true)   # `cr` is also helm chart-releaser: accept it only by --help
[ -z "$CR_BIN" ] && command -v cr >/dev/null 2>&1 && grep -q CodeRabbit <<<"$(cr --help 2>&1)" && CR_BIN=cr
CR_OUT=$(mktemp "${TMPDIR:-/tmp}/cr-prereview.XXXXXX")
[ -n "$CR_BIN" ] && perl -e 'alarm shift; exec @ARGV' 600 \
  "$CR_BIN" review --agent --base "origin/$BASE" </dev/null > "$CR_OUT" 2>&1 \
  || echo "CodeRabbit CLI pre-review skipped (not installed, not signed in, timed out, or errored): $CR_OUT"

修复此分支改动的代码行中明显的缺陷，提交更改，重新运行 Phase 2 本地验证，然后直接进入 Phase 4，不要再次运行 CLI。仅当组织的按用量计费附加项设置为 On demand 或 Off 时，省略 --use-credits 才能避免产生费用；设置为 Automatic 时，超额用量会计费。 检测方式、降级表、计费模式和问题分流：Read("references/coderabbit-cli-prereview.md")。

Phase 4：创建 PR

遵循 Read("rules/pr-title-format.md") 和 Read("rules/pr-body-structure.md")。使用 Read("references/pr-body-templates.md") 中的 HEREDOC 模式。

在 PR 正文的 Test Plan 部分之后，加入 Agent 归属信息部分（来自 Phase 3b）。

TYPE="feat"  # Determine: feat/fix/refactor/docs/test/chore
gh pr create --base "$BASE" \
  --title "$TYPE(#$ISSUE): Brief description" \
  --body "$(cat <<'EOF'
## Summary
[1-2 sentence description]

## Changes
- [Change 1]
- [Change 2]

## Test Plan
- [x] Unit tests pass
- [x] Lint/type checks pass

## Agent Team Sheet
| Agent | Role | Stage | Time |
|-------|------|-------|------|
| 🏗️ **backend-system-architect** | API design | Lead | 2m14s |
| 🛡️ **security-auditor** | Dependency audit | ⚡ Parallel | 0m42s |
| 🧪 **test-generator** | 47 tests, 94% coverage | ⚡ Parallel | 2m01s |

<details>
<summary><strong>🎬 Agent Credits</strong> — 3 agents collaborated on this PR</summary>

**Lead**
- 🏗️ **backend-system-architect** — API design (2m14s)

**⚡ Parallel** (ran simultaneously)
- 🛡️ **security-auditor** — Dependency audit (0m42s)
- 🧪 **test-generator** — 47 tests, 94% coverage (2m01s)

---
<sub>Orchestrated by <a href="https://github.com/yonatangross/orchestkit">OrchestKit</a> — 3 agents, 4m57s total</sub>

</details>

Closes #$ISSUE

---
Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Phase 4b：PR Playground（必需，缺少此步骤时 CI 会阻断）

对于每个非机器人 PR，在 Phase 4 之后：Read("references/pr-playground.md") 并遵循其中的说明（选择原型，将提交推送到 docs/{branch-dir}/，并在正文中添加 SHA 固定的 Live Preview 链接）。

Phase 5：验证

PR_URL=$(gh pr view --json url -q .url)
echo "PR created: $PR_URL"

CI 监控（CC 2.1.71）

创建 PR 后，安排 CI 状态监控。

时间预算：轮询 CI 60 分钟（每 5 分钟运行一次 cron，最多触发 12 次）。cron 任务会重复执行同一条固定提示词，无法统计自身的触发次数，因此提示词中包含创建时计算的一次性墙上时钟截止时间；当所有检查都已完成或到达截止时间时（以先发生者为准），停止并在任一停止时删除 cron 任务。

# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)
# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
# deadline_iso = creation time + 60 minutes, in UTC, filled in ONCE here
CronCreate(
  schedule="*/5 * * * *",
  prompt="Check CI for PR #{pr_number}: gh pr checks {pr_number} --repo {repo}. Deadline {deadline_iso}.
    All pass → CronDelete this job, report success.
    Any fail → CronDelete this job, alert with failure details.
    Still pending and `date -u` is at or past the deadline → CronDelete this job, report the pending checks."
)

CodeRabbit 反馈收集

CI 全部通过后、运行 gh pr merge 或 --auto 之前，如果仓库包含 .coderabbit.yaml 且 PR 不是草稿：Read("references/coderabbit-harvest.md")。

交接文件

为后续技能写入 PR 详细信息：

Write(".claude/chain/pr-created.json", JSON.stringify({
  "phase": "create-pr", "pr_number": N, "pr_url": "...",
  "branch": "...", "files_changed": [...], "related_issues": [...]
}))

---

规则

1. 不要创建无用文件——不要在仓库根目录创建文件
2. 在本地运行验证——不要启动 Agent 执行 lint/test
3. 所有内容都放到 GitHub 上——通过 gh pr create --body 设置 PR 正文
4. 保持简单——用一条命令创建 PR
5. 遵守 gh 速率限制提示（CC ≥ 2.1.116）——当 Bash 工具在 gh 调用后显示 GitHub 速率限制提示时（例如在 /loop 5m gh pr checks … 监控任务中），停止循环并等待限制重置——不要盲目重试。完整说明请参阅 ork:github-operations。

后续步骤（创建 PR 后向用户建议）

review-pr {PR_NUMBER}                # Self-review before requesting reviews
gh pr checks {PR_NUMBER}                  # one-shot status; the CI Monitoring cron polls up to its 60-minute deadline
/loop 1h gh pr view {PR_NUMBER} --json reviewDecision  # Monitor review status

验证门槛

在声称 PR 已准备就绪之前，应用：Read("${CLAUDE_PLUGIN_ROOT}/shared/rules/verification-gate.md")。所有测试都必须通过，并有最新证据。所有 CI 检查都必须为绿色。不要说“应该没问题”。

质量标准

满足以下所有条件才算完成：

• 从功能分支创建 PR，且相对于正确的基准分支（$BASE，根据 origin/HEAD 推导，或使用检测到的托管平台对应值），工作区干净
• 标题采用与变更相符的 type(#issue): ... 格式
• 正文包含“摘要”“变更”和“测试计划”部分；每个已关闭的问题都单独使用 Closes #N 关键词
• 创建前已在本地通过所选 PR 类型的预检验证（仅 Quick 类型可跳过）
• 在执行 gh pr create 之前（阶段 3c）运行过一次 CodeRabbit CLI 预审，或者在“测试计划”中写明一行跳过原因
• docs/{branch-dir}/*.html 中存在 Playground HTML，且正文链接到该文件，具体参见 references/pr-playground.md（非机器人 PR 必须满足）
• gh pr view --json url 返回已创建 PR 的 URL
• 对于包含 .coderabbit.yaml 且非草稿的 PR：根据 references/coderabbit-harvest.md 解决每条 CodeRabbit 线程，并回复说明修复的 sha 或驳回原因（scripts/coderabbit-harvest.sh --unresolved 输出 []）

相关技能

• ork:commit — 创建 PR 前先创建提交
• ork:review-pr — 创建 PR 后审查 PR

选择器回退（#1795）

如果 AskUserQuestion 选择器卡住（这是架构问题，而非 CC 输入错误 — orchestkit#1795，现由 tests/skills/structure/test-askuserquestion-schema.sh 中的测试加以防护），请在启动 CC 前设置 ORK_ASK_FALLBACK=text。lifecycle/ask-fallback-injector 钩子会注入提醒，指示助手以内联编号列表的形式给出选项，并要求用户回复选项编号。

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
references/pr-body-templates.md	PR 正文模板
references/parallel-validation.md	并行验证 Agent 配置
references/ci-integration.md	CI 集成模式
references/multi-commit-pr.md	多提交 PR 指南
assets/pr-template.md	PR 模板（旧版）
scripts/coderabbit-harvest.sh	CodeRabbit 线程：读取（一次 GraphQL 调用）、--reply、--resolve
references/coderabbit-zero-reviews.md	收集结果为零：审查后无问题，还是从未审查？
references/coderabbit-cli-prereview.md	阶段 3c：PR 审查额度为何稀缺、CLI 命令、降级表、分流
references/pr-playground.md	阶段 4b：PR Playground 原型、提交路径、固定 SHA 的 Live Preview 链接（CI 门禁）
references/coderabbit-harvest.md	CI 变绿后：读取、反驳、修复或驳回，并解决每条 CodeRabbit 线程