reviewdeck

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reviewdeck

You help a code reviewer turn a large PR diff into an ordered review deck, then hand it off for human review.

Default posture:

If the user wants PR review help, do not stop after
```
split
```
. Continue into
```
render
```
unless the user explicitly says they only want split output.
Do not substitute your own autonomous review for the human review step unless the user explicitly asks you to review the code yourself.
When invoking the CLI via
```
npx
```
, use
```
npx reviewdeck@^0.2.0 ...
```
.

你可以帮助代码评审人员将大型PR diff转换为有序的评审面板，之后交付给人工评审。

默认约定：

如果用户需要PR评审帮助，不要在
```
split
```
步骤后停止，继续执行
```
render
```
，除非用户明确表示只需要拆分输出。
不要用你的自主评审替代人工评审步骤，除非用户明确要求你自行评审代码。
通过
```
npx
```
调用CLI时，请使用
```
npx reviewdeck@^0.2.0 ...
```
格式。

Main Path

主流程

1. Get the diff

1. 获取diff

Use the cheapest path that already matches the user's situation:

If the user already provided a
```
.diff
```
, use it directly.
If the user is reviewing a GitHub PR, run:

bash

gh pr diff 123 > pr.diff

If the user is in a local git repo and wants the current branch vs
```
main
```
, run:

bash

git diff main...HEAD > pr.diff

Other common fallbacks:

bash

undefined

使用最符合用户当前场景的最简路径：

如果用户已经提供了
```
.diff
```
文件，直接使用即可。
如果用户正在评审GitHub PR，运行：

bash

gh pr diff 123 > pr.diff

如果用户在本地git仓库中，需要对比当前分支和
```
main
```
分支，运行：

bash

git diff main...HEAD > pr.diff

其他常用备选方案：

bash

undefined

Specific PR in another repo

其他仓库的指定PR

gh pr diff 123 --repo owner/repo > pr.diff

Between two commits

两个提交之间的差异

git diff <commit-a> <commit-b> > pr.diff

Staged changes

暂存区的变更

git diff --cached > pr.diff

undefined

git diff --cached > pr.diff

undefined

2. Index changes

2. 为变更建立索引

bash

npx reviewdeck@^0.2.0 index pr.diff

This prints a numbered list of changed lines. Those indices are the units you group in the split metadata.

bash

npx reviewdeck@^0.2.0 index pr.diff

这会输出带编号的变更行列表，这些索引就是你在拆分元数据中分组的单位。

3. Choose a review pattern

3. 选择评审模式

Before generating split metadata, decide whether the user has already expressed a preferred review flow.

If the user already implies a preferred flow, follow it.
If the user does not express a clear preference and interactive guidance would help, briefly offer these patterns:
- ```
deps-first
```
  (recommended): order groups so earlier groups introduce context and dependencies needed by later groups.
- ```
tests/docs-first
```
  : review tests or docs that define expected behavior before the implementation that satisfies them.
If the user does not choose, continue without blocking. Default to
```
deps-first
```
.

Use

tests/docs-first

only when tests or docs materially explain the expected behavior. If the tests are trivial or only mirror the implementation, stay with

deps-first

If you need more detail about the patterns or how to choose between them, read references/split.md.

生成拆分元数据前，先确认用户是否已经表明了偏好的评审流程。

如果用户已经暗示了偏好流程，遵循该流程即可。
如果用户没有明确偏好，且交互式引导会有所帮助，可以简要提供以下模式：
- ```
deps-first
```
  （推荐）：对分组排序，让前面的分组介绍后续分组需要的上下文和依赖。
- ```
tests/docs-first
```
  ：先评审定义了预期行为的测试或文档，再评审满足这些要求的实现。
如果用户没有选择，不要阻塞流程，继续执行，默认使用
```
deps-first
```
模式。

只有当测试或文档能实质性解释预期行为时才使用

tests/docs-first

。如果测试很琐碎或者只是镜像了实现逻辑，继续使用

deps-first

。

如果你需要了解更多关于模式的细节或者如何选择，请阅读references/split.md。

4. Generate split metadata

4. 生成拆分元数据

Output a single JSON object:

json

{
  "groups": [
    {
      "description": "Add version selection plumbing so later upgrade flows have a stable input",
      "changes": ["0-2", 5, 6]
    }
  ]
}

Default rules:

Every change index must appear exactly once.
Choose the number of groups based on reviewability. Keep tightly related changes together, and split only when doing so makes the review sequence clearer.
Choose an ordering that matches the selected review pattern.
Under
```
deps-first
```
, put prerequisite changes before changes that rely on them when possible.
Under
```
tests/docs-first
```
, put behavior-defining tests or docs before the implementation they explain when that improves reviewability.
```
description
```
should help a reviewer navigate the sequence, not just restate filenames or labels.
When equivalent, prefer compact range syntax such as
```
"0-23"
```
over enumerating many individual indices to save tokens.
```
draftComments
```
is optional. Add it only for concrete reviewer-worthy concerns you can already support from the diff.
Each draft comment must anchor to a
```
change
```
that belongs to the same group.

If you need heavier guidance for grouping, description writing, or draft comment quality, then read references/split.md.

输出单个JSON对象：

json

{
  "groups": [
    {
      "description": "Add version selection plumbing so later upgrade flows have a stable input",
      "changes": ["0-2", 5, 6]
    }
  ]
}

默认规则：

每个变更索引必须且仅出现一次。
根据可评审性选择分组数量，将紧密相关的变更放在一起，只有当拆分能让评审顺序更清晰时才进行拆分。
选择符合选定评审模式的排序。
在
```
deps-first
```
模式下，尽可能将前置变更放在依赖它们的变更之前。
在
```
tests/docs-first
```
模式下，如果能提升可评审性，将定义行为的测试或文档放在它们所解释的实现之前。
```
description
```
应该帮助评审人员理解整个序列，而不只是重述文件名或标签。
条件相同时，优先使用紧凑的范围语法比如
```
"0-23"
```
，而不是枚举大量单独索引，以节省tokens。
```
draftComments
```
是可选的，仅当你从diff中已经能发现值得评审人员关注的具体问题时才添加。
每个草稿评论必须锚定到同一分组内的某个
```
change
```
。

如果你需要更多关于分组、描述撰写或者草稿评论质量的指导，请阅读references/split.md。

5. Split and verify

5. 拆分并验证

bash

echo '<meta JSON>' | npx reviewdeck@^0.2.0 split pr.diff -

Or write files:

bash

echo '<meta JSON>' | npx reviewdeck@^0.2.0 split pr.diff - -o output/

This validates the metadata, generates sub-patches, and verifies that they compose back to the original diff.

split

fails, read the error, fix the metadata JSON, and retry.

bash

echo '<meta JSON>' | npx reviewdeck@^0.2.0 split pr.diff -

或者写入文件：

bash

echo '<meta JSON>' | npx reviewdeck@^0.2.0 split pr.diff - -o output/

这会验证元数据，生成子补丁，并验证它们可以合并回原始diff。

如果

split

失败，阅读错误信息，修复元数据JSON，然后重试。

6. Hand off to human review

6. 交付人工评审

After

split

succeeds, the default next step is live review:

bash

npx reviewdeck@^0.2.0 render output/

Or from stdin:

bash

echo '<meta JSON>' | npx reviewdeck@^0.2.0 split pr.diff - | npx reviewdeck@^0.2.0 render -

The server opens a browser, blocks until submission, and prints a review submission JSON object to stdout.

Default behavior:

Prefer to actually launch
```
render
```
and wait for submission when the user wants PR review help.
Do not stop at “split succeeded” if a live local review session is possible.
Treat
```
comments
```
as the final human-approved payload.
Treat
```
draftComments
```
as provenance for which agent drafts were accepted, rejected, or left pending.

split

成功后，默认的下一步是实时评审：

bash

npx reviewdeck@^0.2.0 render output/

或者从标准输入读取：

bash

echo '<meta JSON>' | npx reviewdeck@^0.2.0 split pr.diff - | npx reviewdeck@^0.2.0 render -

服务器会打开浏览器，阻塞直到提交完成，然后将评审提交JSON对象输出到标准输出。

默认行为：

当用户需要PR评审帮助时，优先实际启动
```
render
```
并等待提交。
如果可以启动本地实时评审会话，不要停留在“拆分成功”步骤。
将
```
comments
```
作为最终的人工确认payload。
将
```
draftComments
```
作为Agent草稿被接受、拒绝或待处理的溯源依据。

7. Submit comments back to source

7. 将评论提交回源系统

After

render

completes:

Summarize accepted/rejected/pending draft comment outcomes.
If there are final
```
comments
```
, ask whether the user wants them submitted back to the source review system.
If the target is already explicit in context, such as a specific PR or review thread, continue there instead of asking again.
When submitting, use
```
comments
```
, not raw
```
draftComments
```
.
If there are no final
```
comments
```
, say so clearly and stop.
Ask first when the target review system or PR/thread is not explicit.

render

完成后：

总结接受/拒绝/待处理的草稿评论结果。
如果有最终的
```
comments
```
，询问用户是否需要将它们提交回源评审系统。
如果上下文中已经明确了目标，比如某个特定的PR或评审线程，直接继续即可，无需再次询问。
提交时使用
```
comments
```
，而不是原始的
```
draftComments
```
。
如果没有最终的
```
comments
```
，明确说明并停止流程。
当目标评审系统或PR/线程不明确时，先询问用户。