submit-pull-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Submit Pull Request

提交Pull Request

Goal

目标

Pull request is published.

成功发布Pull Request。

Prerequisites

前置条件

```
vcs-tools
```
skill available
```
scratch
```
skill available
```
ticket-tools
```
skill available

```
vcs-tools
```
技能可用
```
scratch
```
技能可用
```
ticket-tools
```
技能可用

Input

输入参数

```
branch
```
(optional): branch to merge. If omitted, resolve to the current branch (
```
git branch --show-current
```
).
```
target_branch
```
(optional): branch to merge into. If omitted, resolve it from the project's documented convention (e.g. the "Base branch" fact in its
```
AGENTS.md
```
), falling back to
```
main
```
if undocumented.
```
draft
```
(optional): whether to create the PR in draft status. Defaults to
```
false
```
.

```
branch
```
（可选）：待合并的分支。如果未提供，则自动解析为当前分支（
```
git branch --show-current
```
）。
```
target_branch
```
（可选）：合并目标分支。如果未提供，则根据项目文档约定解析（例如
```
AGENTS.md
```
中的「Base branch」配置），若无文档则默认使用
```
main
```
分支。
```
draft
```
（可选）：是否以草稿状态创建PR。默认值为
```
false
```
。

Steps

操作步骤

Step 1: Resolve branches

步骤1：解析分支

Resolve

branch

and

target_branch

per the defaults above if not supplied as input.

如果未提供

branch

和

target_branch

参数，则按照上述默认规则进行解析。

Step 2: Check for existing PR

步骤2：检查现有PR

Skill(skill: "vcs-tools", args: "identify-pr")

If one is found for

branch

, stop and ask the user how to proceed (e.g. update the existing PR instead, or abort) - do not create a duplicate.

Skill(skill: "vcs-tools", args: "identify-pr")

如果检测到该

branch

已有对应的PR，则停止操作并询问用户后续处理方式（例如更新现有PR或终止流程）——请勿创建重复PR。

Step 3: Assert size

步骤3：校验PR规模

bash

git diff --stat <target_branch>..<branch>

Verify diff does not exceed 300 added lines (ideally < 200).
If it exceeds 300, warn user and suggest splitting the PR.

bash

git diff --stat <target_branch>..<branch>

验证代码差异新增行数不超过300行（理想情况应少于200行）。
如果超过300行，需向用户发出警告并建议拆分PR。

Step 4: Push branch

步骤4：推送分支

bash

git push origin <branch>

bash

git push origin <branch>

Step 5: Get commits

步骤5：获取提交记录

bash

git log --no-decorate --oneline <target_branch>..<branch>

Capture as

commits

bash

git log --no-decorate --oneline <target_branch>..<branch>

将结果保存为

commits

变量。

Step 6: Resolve Ticket ID

步骤6：解析工单ID

Infer in priority order from: input, branch name, commit messages, context.

Capture as

ticket_id

按照以下优先级推断：输入参数、分支名称、提交信息、上下文。

将结果保存为

ticket_id

变量。

Step 7: Form Description

步骤7：生成PR描述

Summarize the changes into a PR description.

Rules:

Check the project's documented convention.
Keep it short: no boilerplate, no fluff, no repetitions.

Core details:

1-3 sentence intro (explain implementation, approach, or root cause).
2-4 bullets starting with Action Verbs for changes (Add X, Fix Y, Refactor Z).
If multiple commits exist, suggest reviewing commits separately with a bulleted list of commits (
```
- [12abfe42](https://...) Add user auth
```
).

Additional details (all situational):

Mention what is worth extra attention (e.g., complex logic).
Mention what can be skipped (e.g., indentation, generated files, code moved without actual changes).
Verification attachments (e.g., screenshots, recordings, logs).
Mention related PRs/tickets via IDs/URLs (e.g., PRs dependent on, PRs introducing issue fixed here).

Write the description to a scratch file via

scratch

Skill(skill: "scratch", args: "write pr-description md")

Capture the returned path as

<pr_description_file_path>

将变更内容总结为PR描述。

规则：

遵循项目文档约定。
简洁明了：无冗余模板、无废话、无重复内容。

核心内容：

1-3句话的引言（说明实现方案、处理方式或问题根源）。
2-4条以动作动词开头的变更列表（添加X、修复Y、重构Z）。
如果存在多个提交记录，建议按提交分别评审，并列出提交列表（
```
- [12abfe42](https://...) Add user auth
```
）。

可选补充内容：

标注值得重点关注的内容（例如复杂逻辑）。
标注可跳过评审的内容（例如缩进调整、自动生成文件、仅移动未修改的代码）。
验证附件（例如截图、录屏、日志）。
通过ID/URL关联相关PR/工单（例如依赖的PR、修复当前PR引入问题的PR）。

通过

scratch

技能将描述写入临时文件：

Skill(skill: "scratch", args: "write pr-description md")

将返回的文件路径保存为

<pr_description_file_path>

。

Step 8: Resolve Title

步骤8：生成PR标题

Summarize the description into a PR title.

Rules:

Check the project's documented convention. Fallback to
```
<ticket_id>: <summary>
```
.
Keep it short: no boilerplate, no fluff, no repetitions.
Imperative mood.
Single sentence.
Contains ticket ID.

Capture as

title

将PR描述总结为PR标题。

规则：

遵循项目文档约定。默认格式为
```
<ticket_id>: <摘要>
```
。
简洁明了：无冗余模板、无废话、无重复内容。
使用祈使语气。
单句表述。
包含工单ID。

将结果保存为

title

变量。

Step 9: Create PR

步骤9：创建PR

Invoke:

Skill(skill: "vcs-tools", args: "create-pr <title> <pr_description_file_path> <target_branch> <branch> [DRAFT_FLAG]")

DRAFT_FLAG

--draft

if input

draft

true

, omitted otherwise.

调用技能：

Skill(skill: "vcs-tools", args: "create-pr <title> <pr_description_file_path> <target_branch> <branch> [DRAFT_FLAG]")

如果输入参数

draft

为

true

，则

DRAFT_FLAG

为

--draft

，否则省略。

Step 10: Update Ticket Status

步骤10：更新工单状态

ticket_id

from Step 6 exists:

Skill(skill: "ticket-tools", args: "change-status <ticket_id> code-review")

如果步骤6中获取到

ticket_id

：

Skill(skill: "ticket-tools", args: "change-status <ticket_id> code-review")

Output

输出

JSON format:

jsonc

{
  "prUrl": "string", // The URL of the created Pull Request.
}

JSON格式：

jsonc

{
  "prUrl": "string", // 创建的Pull Request的URL
}