hunk-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hunk Review

Hunk 差异审查

Hunk is an interactive terminal diff viewer. The TUI is for the user -- do NOT run

hunk diff

hunk show

, or other interactive commands directly. Use

hunk session *

CLI commands to inspect and control live sessions.

If no session exists, ask the user to launch Hunk in their terminal first.

Hunk 是一款交互式终端差异查看器。TUI（终端用户界面）供用户直接操作——请勿直接运行

hunk diff

、

hunk show

或其他交互式命令。请使用

hunk session *

系列CLI命令来查看和控制运行中的会话。

如果没有会话正在运行，请先让用户在终端中启动Hunk。

Workflow

工作流程

1. hunk session list                    # find live sessions
2. hunk session context --repo .        # check current focus
3. hunk session navigate ...            # move to the right place
4. hunk session reload -- <command>     # swap contents if needed
5. hunk session comment add ...         # leave review notes

1. hunk session list                    # 查找运行中的会话
2. hunk session context --repo .        # 检查当前焦点
3. hunk session navigate ...            # 导航到目标位置
4. hunk session reload -- <command>     # 按需替换会话内容
5. hunk session comment add ...         # 添加审查备注

Session selection

会话选择

Every command (except

list

) needs a session target:

```
--repo <path>
```
-- match by repo root (most common)
```
<session-id>
```
-- match by exact ID (use when multiple sessions share a repo)
If only one session exists, it auto-resolves

除

list

外的所有命令都需要指定会话目标：

```
--repo <path>
```
—— 通过仓库根路径匹配（最常用）
```
<session-id>
```
—— 通过精确ID匹配（当多个会话共享同一仓库时使用）
如果仅存在一个会话，将自动匹配

Commands

命令说明

Inspect

查看会话信息

bash

hunk session list [--json]
hunk session get (--repo . | <id>) [--json]
hunk session context (--repo . | <id>) [--json]

bash

hunk session list [--json]
hunk session get (--repo . | <id>) [--json]
hunk session context (--repo . | <id>) [--json]

Navigate

导航定位

Requires

--file

and exactly one of

--hunk

--new-line

, or

--old-line

bash

hunk session navigate --repo . --file src/App.tsx --hunk 2
hunk session navigate --repo . --file src/App.tsx --new-line 372
hunk session navigate --repo . --file src/App.tsx --old-line 355

```
--hunk <n>
```
is 1-based
```
--new-line
```
/
```
--old-line
```
are 1-based line numbers on that diff side

需要指定

--file

，且必须从

--hunk

、

--new-line

或

--old-line

中选择其一：

bash

hunk session navigate --repo . --file src/App.tsx --hunk 2
hunk session navigate --repo . --file src/App.tsx --new-line 372
hunk session navigate --repo . --file src/App.tsx --old-line 355

```
--hunk <n>
```
采用1-based编号（从1开始计数）
```
--new-line
```
/
```
--old-line
```
对应差异两侧的1-based行号

Reload

重新加载内容

Swaps the live session's contents. Pass a Hunk review command after

--

bash

hunk session reload --repo . -- diff
hunk session reload --repo . -- show HEAD~1
hunk session reload --repo . -- show HEAD~1 -- README.md

替换运行中会话的内容。在

--

后传入Hunk审查命令：

bash

hunk session reload --repo . -- diff
hunk session reload --repo . -- show HEAD~1
hunk session reload --repo . -- show HEAD~1 -- README.md

Comments

评论管理

bash

hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" [--rationale "..."] [--author "agent"]
hunk session comment list --repo . [--file README.md]
hunk session comment rm --repo . <comment-id>
hunk session comment clear --repo . --yes [--file README.md]

comment add

requires

--file

--summary

, and exactly one of

--old-line

--new-line

Quote
```
--summary
```
and
```
--rationale
```
defensively in the shell

bash

hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" [--rationale "..."] [--author "agent"]
hunk session comment list --repo . [--file README.md]
hunk session comment rm --repo . <comment-id>
hunk session comment clear --repo . --yes [--file README.md]

```
comment add
```
需要指定
```
--file
```
、
```
--summary
```
，且必须从
```
--old-line
```
或
```
--new-line
```
中选择其一
在shell中请谨慎使用引号包裹
```
--summary
```
和
```
--rationale
```
的内容

New files in working-tree reviews

工作区审查中的新文件

Newly created files won't appear in

hunk diff

until Git knows about them:

bash

git add -N src/new-file.ts
hunk session reload --repo . -- diff

新创建的文件在Git追踪前不会出现在

hunk diff

中：

bash

git add -N src/new-file.ts
hunk session reload --repo . -- diff

Guiding a review

引导审查流程

The user may ask you to walk them through a changeset or review code using Hunk. Your role is to narrate: steer the user's view to what matters and leave comments that explain what they're looking at.

Typical flow:

Load the right content (
```
reload
```
if needed)
Navigate to the first interesting file/hunk
Add a comment explaining what's happening and why
Move to the next point of interest -- repeat
Summarize when done

Guidelines:

Work in the order that tells the clearest story, not necessarily file order
Navigate before commenting so the user sees the code you're discussing
Keep comments focused: intent, structure, risks, or follow-ups
Don't comment on every hunk -- highlight what the user wouldn't spot themselves

用户可能会要求你引导他们通过Hunk查看变更集或审查代码。你的职责是进行讲解：将用户的视图引导至关键内容，并添加评论解释所查看的内容。

典型流程：

加载正确的内容（必要时使用
```
reload
```
）
导航至第一个需要关注的文件/代码块
添加评论说明当前代码的作用及原因
移动至下一个关注点——重复上述步骤
完成后进行总结

指导原则：

按照最清晰的逻辑顺序操作，而非严格按照文件顺序
先导航定位再添加评论，确保用户能看到你讨论的代码
评论需聚焦：意图、结构、风险或后续工作
无需对每个代码块添加评论——重点突出用户可能忽略的内容

Common errors

常见错误

"No visible diff file matches ..." -- file isn't in the loaded review. Check
```
context
```
, then
```
reload
```
if needed.
"No active Hunk sessions" -- ask the user to open Hunk in their terminal.
"Multiple active sessions match" -- pass
```
<session-id>
```
explicitly.
"Specify exactly one navigation target" -- pick one of
```
--hunk
```
,
```
--old-line
```
,
```
--new-line
```
.

"No visible diff file matches ..." —— 该文件未在已加载的审查会话中。请先查看
```
context
```
，必要时使用
```
reload
```
重新加载。
"No active Hunk sessions" —— 请让用户在终端中打开Hunk。
"Multiple active sessions match" —— 请显式传入
```
<session-id>
```
。
"Specify exactly one navigation target" —— 请选择
```
--hunk
```
、
```
--old-line
```
或
```
--new-line
```
中的一个参数。