tuicr

tuicr 审查工作流

默认使用 tuicr review 作为 Agent 接口。TUI 是供用户审查代码的界面；CLI 则用于让 Agent 查找活动会话、读取用户评论，并且仅在适当时添加由 Agent 撰写的评论。

核心规则

首先判断用户想要哪种工作流：

1. 用户主导审查 Agent 生成的更改

   • 用户想在 tuicr 中检查补丁并撰写评论。
   • 你的任务是打开或找到会话，然后在用户表示评论已准备好时，通过 tuicr review comments 获取用户评论。如果你明确处于等待用户审查的状态，请定期轮询同一命令，并留意新的评论 ID。
   • 不要添加自己的审查评论，不要抢先审查自己的补丁，也不要冒充用户撰写评论。

2. Agent 审查 AI 生成的补丁

   • 用户希望你理解、批评或总结补丁。
   • 你可以检查补丁并提出问题。
   • 如果你能有把握地判断这是此工作流，且目标会话明确，则使用 tuicr review add 直接添加审查结果，并通过显式的 --username 标明 Agent 身份。如果工作流或会话不明确，请先询问。

如果用户的意图不明确，请询问他们想采用哪种工作流。

附加到会话

1. 根据用户请求、当前工作目录或近期文件操作，确定仓库目录。如果不明确，请询问。

2. 列出已持久化的会话：

   tuicr review list --repo /path/to/repo   # checkout + its repo's PR sessions
   tuicr review list --repo owner/repo      # all sessions for a forge repo
   tuicr review list --all                  # every session across all repos
   

   --repo 是一个选择器：checkout 路径也会显示该 checkout 的 origin 仓库对应的 PR 会话；像 owner/repo 这样的 Forge 坐标则会按 owner/repo 匹配本地会话和 PR 会话。每一行都包含一个 kind（local 或 pr）和一个可用的 slug。如果不知道仓库，请使用 --all。

   退出码为 0 且输出 [] 也表示“不是仓库根目录”——子目录同样会返回此结果。请传入根目录，然后使用 --all，之后再判断是否没有打开的会话。

3. 选择会话：

   • 如果 CLI 明确报告恰好有一个相关的活动会话，且 "active": true，则附加到该会话。
   • 如果有多个活动会话，或无法确定正确的会话，请询问用户要使用哪个 slug。一个仓库可能同时有一个 worktree 会话和一个 commit-range 会话；如果添加到错误的会话，命令仍会以 0 退出。
   • 如果用户提供了 slug 或会话 JSON 路径，请直接使用。
   • 对于 PR 审查，请将列表中的 PR slug（例如 gh:owner/repo/pr/N）传给 --session；它是自包含的，无需 --repo。
   • 如果没有活动会话，请按下文所述启动会话或等待会话。
   • 在活动会话发现机制被正式确立为稳定协议之前，将 "active": true 视为便捷信号。如果 slug 解析失败，请向用户询问该会话使用的 slug 或仓库路径。

即使 Agent 未在 tmux、Zellij 或 Herdr 中运行，CLI 也可以正常工作，因此连接到现有活动会话时不需要多路复用器。

启动会话

当用户需要交互式 tuicr 窗格且当前没有活动会话时：

环境	操作
已设置 $CMUX_WORKSPACE_ID	运行 tuicr-wrapper-cmux.sh /path/to/repo -- <scope>
已设置 $TMUX	运行 tuicr-wrapper.sh /path/to/repo -- <scope>
已设置 $ZELLIJ	运行 tuicr-wrapper-zellij.sh /path/to/repo -- <scope>
$HERDR_ENV 为 1	运行 tuicr-wrapper-herdr.sh /path/to/repo -- <scope>
均未设置	告诉用户你正在等待他们在仓库中启动 tuicr，然后在他们表示准备就绪后，通过 tuicr review list 连接

<scope> 在未提交的工作树更改时为 -w，在提交范围时为 -r <revset>——务必显式传入其中一个，以免用户需要在 TUI 中手动选择暂存 / 未暂存 / 提交范围。

如果设置了多个复用器标记，且能确定哪个复用器位于最内层，则优先使用它；否则请询问。cmux 使用 Ghostty 终端，因此在 cmux 中 $TERM_PROGRAM 的值为 ghostty——请检查 $CMUX_WORKSPACE_ID，而不是终端名称。

tuicr 同时支持 git 和 Jujutsu（jj）仓库，jj 工作区可能完全没有 .git 目录。不要预先使用 git rev-parse 检查目录，也不要因为 git 无法识别它而拒绝启动；始终运行包装器，让它验证仓库。

包装器路径相对于此技能目录：

<skill-directory>/tuicr-wrapper-cmux.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper-zellij.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper-herdr.sh /path/to/repo -- -w

Herdr 包装器需要 jq，以便从 Herdr 的 JSON 响应中读取窗格 ID 和完成结果。

每个包装器都支持在 -- 后传入 tuicr 参数，这样就能限定审查范围，而不是让用户填写范围选择器——例如，未提交的工作树更改使用 -- -w，提交范围使用 -- -r <revset>。启动审查窗格时，务必显式传入其中一个。

如果你的工具支持命令超时，请设置较长的超时时间，例如 10 分钟，因为 tmux、Zellij 和 Herdr 包装器会等待 TUI 退出。cmux 包装器则例外：窗格运行后它会立即返回，并在 === TUICR SURFACE === 标记之间打印新的 surface 引用。请捕获该引用——之后可通过 cmux close-surface --surface <ref> 关闭窗格。TUI 创建活动会话后，使用 tuicr review list --repo /path/to/repo 获取 slug。如果你的环境无法在阻塞中的包装器等待时运行其他命令，请等用户退出 tuicr 后再读取评论。

重建差异

若要自行审查补丁，请重建用户看到的差异。slug 的来源片段会说明所需操作：

Slug 片段	差异
worktree/<head>、staged-and-unstaged/<head>	git diff HEAD
staged/<head>	git diff --cached
unstaged/<head>	git diff
commits/<base>..<head>	git diff <base>~1..<head>
pr/<n>	gh pr diff <n>
pristine	无；完整显示每个已跟踪文件

范围端点包含在内，并按从旧到新的顺序输出，因此不带 ~1 的 <base> 会漏掉第一个提交。请将文件数与列表行中的 file_count 核对；如果不一致，你推导出的所有行号都会有误。

阅读用户评论

这是由用户主导的评审流程中的主要评审环节。

tuicr 不会向 Agent 推送评论。按需运行 CLI 来读取评论。用户表示评论已准备就绪后，或 TUI 退出后，运行：

tuicr review comments --repo /path/to/repo --session <slug>

该命令会输出 JSON。每条评论包含如下字段：

• id
• location
• path
• start_line
• end_line
• side
• comment_type
• author
• lifecycle_state
• content

将这些评论视为用户的评审反馈：

• issue：需要优先修复的阻断问题
• suggestion：考虑是否实现，或说明不实现的原因
• note：回答或确认收到
• praise：无需采取行动

如果评审仍在进行，而你正在等待，请大约每隔 30 秒轮询一次此命令，并将评论 ID 与上一次的结果进行比较。用户表示评论已准备就绪时，立即读取。用户表示评审已完成，或你的工具会阻碍其他工作时，停止轮询。

结果为空并不一定意味着评审没有发生。退出时，tuicr 总会向 stderr 输出类似 tuicr-summary: reviewed 3/3 files, 0 comments added 的行（可在窗格的滚动记录中看到），而 tuicr review list 会为该会话报告相同的 reviewed_count/file_count。如果 reviewed_count 等于 file_count，那么没有评论是合理的“无需标记”结果——将评审视为已完成，不要要求用户确认。只有在 reviewed_count 小于 file_count（用户尚未审阅所有内容便退出），或完全找不到 tuicr-summary: 行时，才询问用户是否已在预期会话中保存评论，或是否应选择另一个活跃会话。如果评审可能在你工作期间继续进行，请在声称评审已完成前重新运行 tuicr review comments。

添加 Agent 评论

只有在工作流允许时才添加评论；对于由 Agent 撰写的评审评论，还须先获得用户同意将其写入 tuicr。

默认规则：

• 已知具体文件和行号时，优先使用行评论。
• 对文件范围的反馈使用文件评论。
• 仅在总结整个评审时使用评审级评论。
• 对问题默认使用 --type issue。
• 根据意图选择更合适的 suggestion、note 或 praise。
• 传入 --username，以便明显区分 Agent 评论。

示例：

tuicr review add --repo /path/to/repo --session <slug> \
  --target-file src/main.rs \
  --line 42 \
  --side new \
  --type issue \
  --username "Codex" \
  "Handle the empty case here."

tuicr review add --repo /path/to/repo --session <slug> \
  --target-file src/main.rs \
  --type suggestion \
  --username "Codex" \
  "Consider splitting this file-level concern into a helper."

评审级评论不要传入 --target-file。范围评论需添加 --end-line。对于已删除的行，使用 --side old；对于新增或未更改的行，使用 --side new。

对于结构化输入，使用 --input，并提供字面量 JSON、@path/to/file.json 或表示从标准输入读取的 -。每次调用只能传入一个对象——数组会导致解析错误。文件键是 file，不是 path。target.type 会根据提供的字段推断：

tuicr review add --session <slug> --username "Codex" --input \
  '{"file":"src/main.rs","line":42,"side":"new","comment_type":"issue","content":"Handle the empty case."}'

然后进行验证。位于差异范围之外的行会被存储、回显并以状态码 0 退出，但永远不会显示出来——对用户不可见，对你来说却看似成功。重新读取 tuicr review comments，并检查你指定一侧上的每个 start_line 是否存在（新增或未更改的行使用 new，已删除的行使用 old）。检查 author 以区分你的评论和用户的评论，并保留返回的 id，以便在之后的读取中识别确切的评论。

旧版导出输出

较旧的包装器驱动流程可能会输出：

=== TUICR INSTRUCTIONS ===
...
=== END TUICR INSTRUCTIONS ===

如果存在，请按其中的说明处理。否则优先使用 tuicr review comments；它是评审反馈的主要来源。如果包装器提到剪贴板导出，仅当 CLI 评论不可用时，才请用户粘贴内容。

Multiplexer 使用提示

cmux：

• 切换窗格：点击窗格，或运行 cmux focus-pane --pane <ref>
• 关闭 tuicr：按 q；窗格会自行关闭。强制关闭请运行 cmux close-surface --surface <ref>
• 列出窗格：运行 cmux list-panes
• 不切换焦点即可读取窗格内容：运行 cmux read-screen --surface <ref>

tmux：

• 切换窗格：按 Ctrl-b，然后按方向键
• 关闭 tuicr：按 q
• 调整窗格大小：按 Ctrl-b，然后按 Ctrl-arrow
• 放大窗格：按 Ctrl-b，然后按 z

zellij：

• 切换窗格：按 Alt + 方向键
• 关闭 tuicr：按 q
• 调整窗格大小：按 Ctrl-n，然后按方向键
• 切换全屏：按 Alt-f
• 循环切换堆叠窗格：按 Alt + [ / ]

Herdr：

• 选择窗格：在 Herdr 界面中点击窗格
• 关闭 tuicr：按 q；随后包装器会关闭审查窗格

错误处理

情况	操作
有多个可能处于活动状态的会话	询问要使用哪个会话 slug
没有活动会话，但 cmux/tmux/Zellij/Herdr 可用	使用相应的包装器启动新的 tuicr 窗格
没有活动会话，也没有复用器	告知用户你正在等待他们启动 tuicr
cmux 包装器未输出 surface ref	运行 cmux list-panes 查找窗格，或请用户自行启动 tuicr
未安装 tuicr	告知用户安装 tuicr
当前目录不是代码仓库	请用户提供正确的仓库目录
评论为空，但 reviewed_count == file_count	将其视为已完成且无需标记的审查——不要询问
评论为空，且 reviewed_count < file_count	确认所选会话，或请用户保存/添加评论

不适用场景

• 用户只想要原始的 git diff 输出。
• 用户明确要求使用非 tuicr 的审查工作流。
• 任务是远程 PR 审查，且没有涉及 tuicr PR 会话。