adaptive-pr-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adaptive BitBucket PR Review Skill

自适应BitBucket PR审查技能

Use the Node.js scripts in this skill to review and manage BitBucket pull requests.

使用此技能中的Node.js脚本审查和管理BitBucket拉取请求。

Prerequisites

前提条件

Set

BITBUCKET_TOKEN

before running BitBucket scripts.

A bearer token is sent as
```
Bearer <token>
```
.
```
username:app_password
```
is encoded automatically as Basic auth.

Set

BITBUCKET_BASE_URL

to the BitBucket server root URL, for example

https://bitbucket.example.com

. Do not include

/rest/api/1.0

; the scripts add that path automatically.

For Jira integration, set

JIRA_TOKEN

Set

JIRA_BASE_URL

to the Jira server root URL, for example

https://jira.example.com

. Do not include

/rest/api/2

; the scripts add that path automatically.

Node 18+ is required. Scripts live under:

```
scripts/bitbucket/
```
- BitBucket API scripts
```
scripts/jira/
```
- Jira API scripts
```
scripts/lib/
```
- internal helpers; do not call these directly

Run scripts with:

bash

node "scripts/bitbucket/<script>.mjs" --flag value

Default project:

PROJ

. Pass

--project <key>

only when working in another project.

运行BitBucket脚本前，请设置

BITBUCKET_TOKEN

。

Bearer令牌需以
```
Bearer <token>
```
的形式发送。
```
username:app_password
```
会自动编码为Basic认证格式。

将

BITBUCKET_BASE_URL

设置为BitBucket服务器根URL，例如

https://bitbucket.example.com

。请勿包含

/rest/api/1.0

；脚本会自动添加该路径。

若要集成Jira，请设置

JIRA_TOKEN

。

将

JIRA_BASE_URL

设置为Jira服务器根URL，例如

https://jira.example.com

。请勿包含

/rest/api/2

；脚本会自动添加该路径。

需要Node 18+版本。脚本存放路径：

```
scripts/bitbucket/
```
- BitBucket API脚本
```
scripts/jira/
```
- Jira API脚本
```
scripts/lib/
```
- 内部辅助脚本；请勿直接调用

运行脚本的方式：

bash

node "scripts/bitbucket/<script>.mjs" --flag value

默认项目：

PROJ

。仅当处理其他项目时，传入

--project <key>

参数。

Core Workflow

核心工作流

Always start a PR session with:

bash

node "scripts/bitbucket/get-pr-info.mjs" --prId <id> --repo <repo>

This returns PR metadata, description, and a changed-files checklist. Run it once per PR session.

Before reviewing diffs or drafting comments, load the

Current Review Patterns

section from

references/review-patterns.md

Apply any current patterns in that file during the review.
If a pattern conflicts with the current PR context, prefer the PR context and record the mismatch after the review.

If the PR description contains a Jira key such as

PROJ-1234

and

JIRA_TOKEN

is set, run:

bash

node "scripts/jira/get-jira-issue.mjs" --issueKey PROJ-1234

Then choose the smallest useful diff command:

For PRs with 20 or fewer changed files, run
```
get-pr-diff.mjs
```
.
If output is truncated or a checklist file is missing, run
```
get-file-diff.mjs --file <path>
```
.
Use
```
get-file-content.mjs --file <path> --side TO
```
only to verify code not visible in the diff before making a technical claim.

Before posting comments, run:

bash

node "scripts/bitbucket/get-activities.mjs" --prId <id> --repo <repo>

This exposes existing comment IDs, replies, approvals, and resolved thread state.

每次PR审查会话都请从以下命令开始：

bash

node "scripts/bitbucket/get-pr-info.mjs" --prId <id> --repo <repo>

该命令会返回PR元数据、描述以及变更文件清单。每个PR会话只需运行一次。

在审查差异或撰写评论前，请查看

references/review-patterns.md

中的「当前审查模式」章节。

审查过程中应用该文件中的所有当前模式。
如果模式与当前PR上下文冲突，请优先遵循PR上下文，并在审查结束后记录该不匹配情况。

如果PR描述中包含Jira密钥（如

PROJ-1234

）且已设置

JIRA_TOKEN

，请运行：

bash

node "scripts/jira/get-jira-issue.mjs" --issueKey PROJ-1234

然后选择最适用的差异命令：

对于变更文件数量≤20的PR，运行
```
get-pr-diff.mjs
```
。
如果输出被截断或缺少清单文件，运行
```
get-file-diff.mjs --file <path>
```
。
仅在需要验证差异中未显示的代码以提出技术观点时，使用
```
get-file-content.mjs --file <path> --side TO
```
。

发布评论前，请运行：

bash

node "scripts/bitbucket/get-activities.mjs" --prId <id> --repo <repo>

该命令会展示现有评论ID、回复、审批状态以及已解决的线程状态。

Review Memory Loop

审查记忆循环

This skill should evolve from actual review sessions. Treat

references/review-patterns.md

as the skill's review memory file.

Capture a note when any of these happen during a review:

The user corrects a technical claim or severity level.
The user rewrites comment tone or asks for a different framing style.
The user rejects a false positive or points out missing context.
The same kind of issue appears across multiple PRs.
A one-off manual check proves consistently useful.

Store reusable review lessons, not raw Jira details or PR-specific business context unless they generalize into a future review pattern.

Record the note when the signal appears. Do not rely on end-of-review memory for corrections that affect accuracy or tone.

During a normal PR review, the default is capture first, update the skill later. Do not rewrite this skill mid-review unless the user explicitly asks for that change or the current guidance is actively causing incorrect review output.

After the review, append or complete the entry in

references/review-patterns.md

using this format:

markdown

undefined

此技能应从实际审查会话中逐步演进。将

references/review-patterns.md

视为技能的审查记忆文件。

当审查过程中出现以下情况时，请记录笔记：

用户纠正技术观点或严重级别。
用户重写评论语气或要求采用不同的表述风格。
用户拒绝误报或指出缺失的上下文。
同类问题出现在多个PR中。
一次性手动检查被证明持续有效。

存储可复用的审查经验，而非原始Jira细节或PR特定业务上下文，除非它们可以归纳为未来的审查模式。

出现信号时立即记录笔记。不要依赖审查结束后的记忆来修正影响准确性或语气的内容。

审查结束后，使用以下格式在

references/review-patterns.md

中追加或完善条目：

markdown

undefined

Candidate Patterns

候选模式

2026-05-26 | Short label

2026-05-26 | 简短标签

Context: What PR or situation triggered this.
Lesson: What was wrong, missing, or unusually effective.
Next pass: The concrete adjustment to try in future reviews.
State: CANDIDATE
Tags: severity, false-positive


Graduation rule:

1. If the same lesson recurs twice, move it from `Candidate Patterns` to `Current Review Patterns`.
2. When a pattern proves broadly reliable, fold it into the relevant permanent guidance in this skill, usually `SKILL.md`, `references/review-workflow.md`, or `references/commenting-guide.md`.
3. Once a pattern has been folded into the permanent guidance, either keep it in `Current Review Patterns` as an active reminder or move it to `Archived Patterns` with a note such as `Codified in review-workflow.md`.
4. If a pattern becomes stale, too narrow, or misleading, move it to `Archived Patterns` with a brief reason.

上下文：触发此条目的PR或场景。
经验：存在哪些错误、缺失或异常有效的做法。
后续行动：未来审查中尝试的具体调整。
状态：候选
标签：严重级别, 误报


升级规则：

1. 如果同一经验重复出现两次，将其从「候选模式」移至「当前审查模式」。
2. 当模式被证明广泛可靠时，将其整合到本技能的相关永久指南中，通常是`SKILL.md`、`references/review-workflow.md`或`references/commenting-guide.md`。
3. 模式被整合到永久指南后，可将其保留在「当前审查模式」中作为活动提醒，或移至「归档模式」并添加备注，例如「已编入review-workflow.md」。
4. 如果模式过时、范围过窄或具有误导性，将其移至「归档模式」并附上简短原因。

Pattern Review Trigger

模式审查触发条件

Do not interrupt an active PR review to reconcile pattern notes.

After the review is complete, inspect only the

Candidate Patterns

section of

references/review-patterns.md

. Prefer a targeted text search or helper script instead of reading the whole file when possible.

Use this helper script when you want a compact summary or cleanup signal:

bash

node "scripts/memory/review-memory.mjs"
node "scripts/memory/review-memory.mjs" --section current
node "scripts/memory/review-memory.mjs" --section candidate

Run a pattern cleanup pass only when one of these is true:

```
Candidate Patterns
```
has 5 or more pattern entries.
The oldest pattern entry in
```
Candidate Patterns
```
is more than 14 days old.

If a cleanup pass is needed:

Merge duplicate or closely related candidate entries.
Promote repeated lessons into
```
Current Review Patterns
```
.

Fold broadly reliable patterns into

SKILL.md

references/review-workflow.md

, or

references/commenting-guide.md

when appropriate.

Move stale, disproven, or overly narrow entries to
```
Archived Patterns
```
.

This review is a maintenance step, not part of the active PR-review flow.

Do not frame this as model training. It is a maintained file-based memory loop: the skill carries forward review lessons in repo files and reuses them in later sessions.

不要在活跃的PR审查过程中中断以协调模式笔记。

审查完成后，仅查看

references/review-patterns.md

中的「候选模式」章节。尽可能使用针对性文本搜索或辅助脚本，而非通读整个文件。

如需简洁总结或清理信号，请使用以下辅助脚本：

bash

node "scripts/memory/review-memory.mjs"
node "scripts/memory/review-memory.mjs" --section current
node "scripts/memory/review-memory.mjs" --section candidate

仅当满足以下条件之一时，才进行模式清理：

「候选模式」包含5个或更多条目。
「候选模式」中最早的条目已超过14天。

如需清理：

合并重复或密切相关的候选条目。
将重复出现的经验升级至「当前审查模式」。

适当时将广泛可靠的模式整合到

SKILL.md

、

references/review-workflow.md

或

references/commenting-guide.md

中。

将过时、被证伪或范围过窄的条目移至「归档模式」。

此审查是维护步骤，不属于活跃的PR审查流程。

不要将此描述为模型训练。这是一个基于文件的维护记忆循环：技能在仓库文件中保留审查经验，并在后续会话中复用。

Commenting Rules

评论规则

Use

comment-line.mjs

for file-specific issues:

bash

node "scripts/bitbucket/comment-line.mjs" \
  --prId <id> --repo <repo> \
  --file <path> --line <n> \
  --lineType ADDED --comment "<text>"

Keep this short rule set in mind:

Prefer
```
ADDED
```
lines for comments.
Use the exact line number shown in annotated diff output.
Do not post positive feedback as line comments.
Use
```
--severity BLOCKER
```
only for security issues, logic errors, or breaking changes.
If the script says the line does not exist on the expected side, re-read the diff and choose a new line number.

Use

comment-pr.mjs

for top-level PR comments and replies:

bash

node "scripts/bitbucket/comment-pr.mjs" --prId <id> --repo <repo> --comment "<text>"
node "scripts/bitbucket/comment-pr.mjs" --prId <id> --repo <repo> --parentId <id> --comment "<text>"

Never use

comment-line.mjs

to reply to an existing comment.

Do not post an overall summary comment without user confirmation.

Use

update-comment.mjs

to edit, resolve, or reopen a comment thread:

bash

node "scripts/bitbucket/update-comment.mjs" \
  --prId <id> --repo <repo> --commentId <id> \
  [--text "<new text>"] [--state resolve|reopen]

针对文件特定问题使用

comment-line.mjs

：

bash

node "scripts/bitbucket/comment-line.mjs" \
  --prId <id> --repo <repo> \
  --file <path> --line <n> \
  --lineType ADDED --comment "<text>"

请牢记以下简短规则：

优先对
```
ADDED
```
行发表评论。
使用带注释的差异输出中显示的确切行号。
不要将正面反馈作为行评论发布。
仅针对安全问题、逻辑错误或破坏性变更使用
```
--severity BLOCKER
```
。
如果脚本提示预期侧的行不存在，请重新阅读差异并选择新行号。

针对PR顶部评论和回复使用

comment-pr.mjs

：

bash

node "scripts/bitbucket/comment-pr.mjs" --prId <id> --repo <repo> --comment "<text>"
node "scripts/bitbucket/comment-pr.mjs" --prId <id> --repo <repo> --parentId <id> --comment "<text>"

切勿使用

comment-line.mjs

回复现有评论。

未经用户确认，请勿发布整体总结评论。

使用

update-comment.mjs

编辑、解决或重新打开评论线程：

bash

node "scripts/bitbucket/update-comment.mjs" \
  --prId <id> --repo <repo> --commentId <id> \
  [--text "<new text>"] [--state resolve|reopen]

PR Management

PR管理

Create a PR:

bash

node "scripts/bitbucket/create-pr.mjs" \
  --title "<title>" --from <branch> --to <branch> --repo <repo>

Defaults to draft. Pass

--draft false

for ready-for-review.

List pull requests:

bash

node "scripts/bitbucket/list-prs.mjs" [--repo <repo>] [--project <key>] [--state OPEN|MERGED|DECLINED|ALL] [--role AUTHOR|REVIEWER|PARTICIPANT] [--limit <n>] [--start <n>]

Omit

--repo

to query the dashboard (all repos). Use

--start

to paginate.

Read or update PR title and description:

bash

node "scripts/bitbucket/update-pr.mjs" --prId <id> --repo <repo>

Omit

--title

and

--description

to read. Provide either or both to update.

创建PR：

bash

node "scripts/bitbucket/create-pr.mjs" \
  --title "<title>" --from <branch> --to <branch> --repo <repo>

默认创建草稿PR。传入

--draft false

以创建待审查PR。

列出拉取请求：

bash

node "scripts/bitbucket/list-prs.mjs" [--repo <repo>] [--project <key>] [--state OPEN|MERGED|DECLINED|ALL] [--role AUTHOR|REVIEWER|PARTICIPANT] [--limit <n>] [--start <n>]

省略

--repo

可查询仪表板（所有仓库）。使用

--start

进行分页。

读取或更新PR标题和描述：

bash

node "scripts/bitbucket/update-pr.mjs" --prId <id> --repo <repo>

省略

--title

和

--description

可读取信息。提供其中一个或两个参数可进行更新。

Script Routing

脚本路由

Goal	Script
Start review / get file checklist	`scripts/bitbucket/get-pr-info.mjs`
Full diff for all files	`scripts/bitbucket/get-pr-diff.mjs`
Diff for one file	`scripts/bitbucket/get-file-diff.mjs`
Verify dependency not in diff	`scripts/bitbucket/get-file-content.mjs`
See comments, IDs, approvals	`scripts/bitbucket/get-activities.mjs`
Post inline line comment	`scripts/bitbucket/comment-line.mjs`
Post summary or reply	`scripts/bitbucket/comment-pr.mjs`
Edit, resolve, or reopen comment	`scripts/bitbucket/update-comment.mjs`
Create a PR	`scripts/bitbucket/create-pr.mjs`
Read or update PR title/description	`scripts/bitbucket/update-pr.mjs`
List pull requests	`scripts/bitbucket/list-prs.mjs`
Fetch Jira issue	`scripts/jira/get-jira-issue.mjs`
Summarize review memory / cleanup signal	`scripts/memory/review-memory.mjs`

目标	脚本
开始审查 / 获取文件清单	`scripts/bitbucket/get-pr-info.mjs`
获取所有文件的完整差异	`scripts/bitbucket/get-pr-diff.mjs`
获取单个文件的差异	`scripts/bitbucket/get-file-diff.mjs`
验证差异中未包含的依赖	`scripts/bitbucket/get-file-content.mjs`
查看评论、ID、审批状态	`scripts/bitbucket/get-activities.mjs`
发布行内评论	`scripts/bitbucket/comment-line.mjs`
发布总结或回复	`scripts/bitbucket/comment-pr.mjs`
编辑、解决或重新打开评论	`scripts/bitbucket/update-comment.mjs`
创建PR	`scripts/bitbucket/create-pr.mjs`
读取或更新PR标题/描述	`scripts/bitbucket/update-pr.mjs`
列出拉取请求	`scripts/bitbucket/list-prs.mjs`
获取Jira问题	`scripts/jira/get-jira-issue.mjs`
总结审查记忆 / 清理信号	`scripts/memory/review-memory.mjs`

When to Load References

何时加载参考文档

Load the
```
Current Review Patterns
```
section from
```
references/review-patterns.md
```
at the start of every review session.
Load
```
references/commenting-guide.md
```
before posting, replying to, editing, resolving, or reopening comments.
Load
```
references/review-workflow.md
```
when performing a full code review or preparing review feedback.

每次审查会话开始时，加载
```
references/review-patterns.md
```
中的「当前审查模式」章节。
在发布、回复、编辑、解决或重新打开评论前，加载
```
references/commenting-guide.md
```
。
在执行完整代码审查或准备审查反馈时，加载
```
references/review-workflow.md
```
。

Pattern File Maintenance

模式文件维护

Keep

references/review-patterns.md

structured enough for both human review and future script-based lookup.

Add new entries as they happen; do not batch from memory if accuracy matters.
Prefer short entries tied to a concrete review mistake, correction, or repeated win.
Keep each pattern entry as one
```
###
```
block with the same field names.
When a pattern is superseded, codified elsewhere, or no longer useful, move it to
```
Archived Patterns
```
instead of leaving stale guidance in the active sections.

保持

references/review-patterns.md

的结构清晰，便于人工审查和未来基于脚本的查找。

出现新条目时立即添加；若准确性重要，请勿从记忆中批量添加。
优先添加与具体审查错误、修正或重复成功案例相关的简短条目。
每个模式条目均为一个
```
###
```
块，并使用相同的字段名。
当模式被取代、编入其他文档或不再有用时，将其移至「归档模式」，而非在活跃章节中保留过时指南。

Compatibility Rule

兼容性规则

Future edits to this skill must preserve compatibility with

references/review-patterns.md

Do not remove the instruction to load the pattern file at review start unless the memory mechanism is being replaced in the same change.
Do not rename
```
Current Review Patterns
```
,
```
Candidate Patterns
```
, or
```
Archived Patterns
```
without updating the related workflow guidance.
Do not change the entry field names or heading format without updating any helper logic that depends on them.
If the pattern file structure changes, migrate existing entries in the same update rather than resetting the file.

未来对本技能的编辑必须保持与

references/review-patterns.md

的兼容性。

除非同时替换记忆机制，否则请勿移除审查开始时加载模式文件的指令。
除非更新相关工作流指南，否则请勿重命名「当前审查模式」、「候选模式」或「归档模式」。
除非更新依赖这些字段的辅助逻辑，否则请勿更改条目字段名或标题格式。
如果模式文件结构变更，请在同一更新中迁移现有条目，而非重置文件。

Ad-hoc Queries

临时查询

For one-off lookups not covered by a script, import

bbRequest

directly:

bash

node --input-type=module <<'EOF'
import { bbRequest } from './scripts/lib/bb.mjs';
const data = await bbRequest('/projects?limit=100');
data.values.forEach(p => console.log(p.key, p.name));
EOF

Pass any

/rest/api/1.0

path. Run from the skill base directory.

Same pattern works for Jira using

jiraRequest

from

./scripts/lib/jira.mjs

— pass any

/rest/api/2

path, e.g.

/project?maxResults=200

to list projects.

对于现有脚本未覆盖的一次性查询，请直接导入

bbRequest

：

bash

node --input-type=module <<'EOF'
import { bbRequest } from './scripts/lib/bb.mjs';
const data = await bbRequest('/projects?limit=100');
data.values.forEach(p => console.log(p.key, p.name));
EOF

传入任意

/rest/api/1.0

路径。请从技能根目录运行。

使用

./scripts/lib/jira.mjs

中的

jiraRequest

可实现相同的Jira查询——传入任意

/rest/api/2

路径，例如

/project?maxResults=200

以列出项目。

Extending the Skill

扩展技能

If an ad-hoc query proves useful or a recurring task isn't covered by an existing script, offer to:

Create a new script under
```
scripts/bitbucket/
```
or
```
scripts/jira/
```
so the operation is reusable.
Add a row for it to the Script Routing table in this file.
Update the
```
description
```
trigger phrases in the frontmatter if the new script covers a new category of user request.

如果临时查询被证明有用，或现有脚本未覆盖重复任务，请提议：

在
```
scripts/bitbucket/
```
或
```
scripts/jira/
```
下创建新脚本，以便重复使用该操作。
在本文档的「脚本路由」表格中添加对应的行。
如果新脚本覆盖了新类别的用户请求，请更新前文中的
```
description
```
触发短语。