ThinkRail 代码审查工作流完整指南：在 Diff 上留锚点评论，一键喂回 AI Agent-开发者社区

【免费下载链接】thinkrail

Vibe code with pi in a lightweight, real IDE that customises itself around the way you work — The Vibe You Need

项目地址：https://gitcode.com/GitHub_Trending/th/thinkrail

ThinkRail 是一款围绕 pi 编码代理构建的 Agentic IDE。它的代码审查功能让你直接在 Diff 上留下锚点评论（anchored review comments），再用一个「Send review」按钮把整份评论打包成结构化上下文，一键喂回 AI Agent去逐条修复——审查意见从此不再是一句模糊的"把这块改一下"，而是带行号、带代码片段、可追踪状态的结构化工单。

为什么普通"聊天式"审查容易翻车

很多 AI 编程工具里，你发现代码问题后只能切到聊天框打字："刚才那个函数名不清晰，改一下。"问题来了：

AI 不知道你说的"那块"是哪个文件的哪几行；
一轮审查里你提了 5 个问题，AI 修了 3 个，你根本记不清剩哪 2 个；
代码在审查期间又变了，之前的意见对不上位置。

ThinkRail 的解法借鉴了 GitHub 的**草稿评论（draft comments）**模型：评论是"钉"在文件与 Diff 上的记录，先收集、后发送，发送时自动附上代码片段和上下文。整个审查层的设计与实现见 packages/server/src/reviews/SPEC.md。

三步在 Diff 上留下锚点评论

第 1 步：选中要评论的行。在 Changes 面板双击文件打开 Diff，用鼠标（或方向键）选中任意几行。

第 2 步：点侧边出现的评论图标。行选区旁会出现一个小图标，点击后弹出内联输入框（composer），显示选中的行号（如Line 2）。此时有两个选项：

Save draft—— 存为草稿，稍后统一发送；
Send now—— 立即发送并创建该文件的审查会话。

第 3 步：评论以"线程卡片"形式钉在 Diff 上。草稿评论会渲染成一张review-thread-card，标注状态为 draft，旁边有发送按钮；同时对应的编辑器标签页会出现紫色 Review 角标和待发送计数，提醒你"这个文件有话说"。

评论不仅可以挂在 Diff 上，还能挂在普通文件（inline）、整个文件（file）甚至整组改动（Whole change set）上；Diff 的左右两侧是两套独立的锚点空间，你可以针对"改动前（base 侧）被删除的代码"留言，AI 收到的会注明"这是指改动前的版本"。

在分支 Diff（All changes）视图里，每个 hunk 还配了Keep / Revert / Ask agent about this hunk三个按钮。Keep 以 hunk 内容为键，行号漂移后依然有效；底部有进度条和Next unreviewed按钮（快捷键J），V键标记当前文件已读——一次大型改动的逐块审查体验非常完整。

评论的一生：draft → sent → resolved

Review 侧栏（右侧边栏的 Review 面板）把所有评论按文件分组，每个文件下分三个区域：

区域	含义	可执行操作
Drafts	未发送的草稿	编辑、删除、单独发送、整文件发送
In progress	已发送、等待 Agent 处理	打开关联会话、查看 Agent 状态
Resolved	已解决	回看讨论

发送机制有两种粒度（SendReviewButton.tsx）：

文件级Send review (N)—— 只发这一个文件的 N 条草稿；
全局Send all (N)—— 一键清空所有草稿。

评论一旦发送就变成不可删除的记录（草稿才能删），这是刻意为之：Agent 的会话里已经引用了这条评论的 id，删除会造成悬空引用。全部处理完的文件可以点"Done"标记收尾，最后用Clear把已发送评论归档、丢弃剩余草稿，开启下一轮审查。

一键喂回 AI Agent：结构化上下文包

发送时并不是把你的文字原样丢进聊天框。Host 端会把每个文件的评论渲染成一个review 上下文包（实现见 packageRender.ts），其中每条评论都带上：

稳定 id、文件路径、行号范围、锚点状态（anchored / moved / outdated）；
你选中的代码片段原文（fragment）；
片段前后各 10 行上下文（context）；
一段给 Agent 的明确指令：逐条处理、修完调用resolve_comment工具销账、遇到过期的先核对当前文件、不同意就在对话里反驳而不要硬改。

Agent 会用真实的编辑工具去改文件，每处理完一条就调用resolve_comment工具附带一句"做了什么"，Review 面板里对应评论随即移入 Resolved。如果 Agent 还没动手、发送前就报错（比如模型密钥失效），评论会自动回滚成草稿，随时可重发——不会出现"发出去了但 AI 没收到"的尴尬。

每个文件的第一次发送会自动创建它的专属审查会话，之后该文件的所有新评论都续进同一个会话，讨论不中断。你也可以发送时直接指定当前打开的聊天。

小贴士：Settings → Layout 内置了一个Review 预设布局（1 左 + 2 右栏组），一键切换后聊天、Diff、Changes/Review 面板就位，适合长时间审查。

智能重锚：代码变了，评论不会迷路

审查往往跨越多个 Agent 回合，文件内容会不断变化。ThinkRail 在每次读取和发送前都会执行重锚（re-anchoring）（纯函数实现见 anchoring.ts），锚点有三种状态：

anchored—— 文件字节哈希未变，评论原样钉在原位；
moved—— 文件变了，但通过评论时截取的文本引用（textQuote，含前后缀消歧）在全文中恰好唯一命中，静默改钉到新行号；
outdated—— 找不到或命中多处，评论保留写下那一刻的代码快照并打上 outdated 标记，发送时明确告知 Agent"先对照当前文件核实"。

这意味着你的评论不会因为 Agent 重构了几行就"指错地方"；对不上的也会诚实标注，而不是假装还在原位。Diff 左侧 base 侧的评论则永远锚定在创建时固化的 commit 上——被删除的代码不会因为你之后的提交而"复活错位"。

高效审查技巧清单

⌨️J跳到下一个未审查文件，V标记当前文件已读，Alt+↑/↓ 上下切换文件；
边读边存草稿，攒够一批再Send all，让 Agent 一次拿到完整问题清单；
针对被删除的代码留言时选 base 侧，AI 会自动理解这是"改动前"的引用；
审查会话重启后评论不丢——状态存于~/.thinkrail，审查记录与 Agent 对话各自持久化；
想让人工+AI 协作：规划流程中的审查 Agent也会用同一套addComment通道提交发现（带机器人角标"Filed by ThinkRail's reviewer agent"），你只需逐条确认或回复；
50 个文件以上的大改动会自动提示切换到One file模式逐文件审查，避免虚拟列表卡顿。