用 task-view 把编码 Agent 的改动变成一张可评审的地图：Skill 接入、评审文件校验与四种视图排雷实操

安装脚本会按你的系统与 CPU 从最新发布里挑对应的二进制，核对发布页的校验和，装到 ~/.local/bin（Windows 是 %LOCALAPPDATA%\Programs\task-view），清掉 macOS 的隔离标记，必要时把目录加进 PATH。装完请开一个新终端再跑命令，PATH 的改动才会生效；重跑同一条命令就是升级。第二步是装 Skill：这是整个设计的枢纽——Agent 之所以会写那份说明，是因为 SKILL.md 告诉它要写。任何读 skill 的 Agent 都能用同一份文件，Claude Code 装在用户目录即对所有仓库生效。

# 1) 装二进制（macOS / Linux，无需 sudo，只需要 git）
curl -fsSL https://raw.githubusercontent.com/gtindo/task-view/main/scripts/install.sh | sh

# Windows（PowerShell）
# irm https://raw.githubusercontent.com/gtindo/task-view/main/scripts/install.ps1 | iex

# 2) 装 Skill：让 Agent 干完活就写一份评审文件（以 Claude Code 为例）
mkdir -p ~/.claude/skills/task-review
curl -fsSL https://raw.githubusercontent.com/gtindo/task-view/main/skills/task-review/SKILL.md \
  -o ~/.claude/skills/task-review/SKILL.md

值得先记住它的边界：这个工具只读文件、只跑只读的 Git 命令，从不跑测试、不跑构建、不跑 linter，也不做语言解析与符号跳转。所以「测试通过了」这句话永远是 Agent 的一面之词，页面上也会明明白白标成 Agent 陈述。它校验的是说明与改动是否一致，从不评判改动本身好不好——判断代码对不对，依然是你的活。

装好之后你的工作流没有任何变化：照常用自然语言派活。区别在于，Agent 干完之后会多写一个评审文件，默认落在 .review/change-任务名.json。文件名带任务名，所以几份评审可以并排放在 .review/ 下互不干扰。文件里记录每个仓库的提交（从新到旧），这样每一处引用都指向一个确定的状态；然后是它碰过的节点、节点之间的关系、用户可见的流程，以及每一处的引用——仓库、文件、行范围、行内容、提交号。想让它先搞懂格式，直接让它读一遍自带说明即可。

# 给 Agent 的任务（照常说人话）
重构结算服务的折扣计算，把税率逻辑抽到单独模块，补上单测，
然后写评审文件。

# 它做完之后，仓库里多出来的东西
.review/change-discount-refactor.json

# 不确定它懂不懂格式？让它自己读一遍说明
Run task-view instructions

这一步真正改变的是责任分配：过去你要从 diff 里反推结构，现在结构由产出者提供，并且是可核对的。Agent 写的每一句可核对的话都带引用，不可核对的（为什么这么改、测试跑没跑）会显式标成它的陈述，不会伪装成已核验的事实。这个区分看着小，实际决定了你能不能在几分钟内判断该信哪一段。

校验这一步是给 Agent 用的，不是给你的。它会指出说明与仓库对不上的地方：行号错了、少了某个 hunk、改动状态写反了。Agent 按报错改文件，反复跑到退出码为 0、且没有 unmentioned_hunk 警告为止——剩下的每一条漏说都必须在 notes 里解释清楚。这一步的意义在于：准确的说明是可信视图的前提，否则你看到的图本身就建在错误数据上。

# 让 Agent 自己反复跑，直到干净
task-view validate .review/change-discount-refactor.json --format json

# 看退出码：0 才算通过
echo $?

# 输出里重点看这两类
# - wrong lines / wrong change state：引用与仓库对不上，必须改
# - unmentioned_hunk：有改动行没有任何节点描述，要么补上，要么在 notes 里说明

有个判断标准值得记住：校验说的一律是「说明准不准」，从不说「代码对不对」。一份通过全部校验的说明，完全可能对应一段糟糕的实现。所以别把 validate 干净当成可以合并的信号，它只是让你之后读的每一句话都有据可查。

校验干净之后就轮到你了。open 会用文件系统与 Git 解析并核对每一条引用，几秒内生成页面并在浏览器打开。产物是一个静态 HTML 文件，没有服务、没有 CI、没有账号，关掉就没了。想带走就加 --out 存成文件，贴进工单或发给同事都行——注意里面有真实代码，分享前要过一遍。

# 直接在浏览器打开
task-view open .review/change-discount-refactor.json

# 存成文件带走 / 分享
task-view open .review/change-discount-refactor.json --out review.html

页面顶栏是状态计数与错误、警告数量，点任意数字就列出对应的发现；有红色横幅说明评审文件里还有错误，此时任何被标为矛盾或未解析的内容都不是事实，先让 Agent 修。左侧面板是 Agent 的摘要、每个仓库从基线到最终状态的提交、按类别分组的发现与它的备注，右边缘可以拖动调宽。点任意节点、连线、代码块或发现分组，右侧的检查器会展开：改动在哪、按 Agent 的说法为什么改、哪些测试覆盖它、与哪些节点相关，代码框还有 Diff 与 After 两个页签——前者只看改动行与它替换掉的内容，后者看改动后整个函数或文件的样子。

四个视图是分工的：Graph 回答「整体长什么样」，节点按仓库分组，跨仓库的端点放在中间，点节点聚焦它和它的邻居，搜索框或直接按 / 可以找节点；Flows 回答「用户走的路径是什么」，从左到右逐步展开，测试挂在它覆盖的步骤下面，虚线连接表示 Agent 没给这层关系任何引用；Diff map 回答「有没有漏的」，每个改动文件一条横条，绿色表示被某个节点覆盖、琥珀色部分覆盖、红色完全没提，展开能读具体 hunk；Claims 回答「这句话我凭什么信」，比如「索引字段不会重复」「import 不用改」这类陈述，展开就能看到它指向的确切代码或提交。

# 四种状态，全站画法一致
# Verified      实线边框 + 绿色对勾：引用解析成功且与文件、diff 相符
# Contradicted  红色边框 + 红叉：解析到了但核对失败（行不对、状态不对）
# Unresolved    琥珀虚线 + 问号：文件、行范围或提交找不到
# Agent statement 灰色点线 + 斜体：没有引用可核，或只是 Agent 的解释

# 发现里最该先看的三类
# 1. 矛盾 / 未解析的引用   说明有错，打回给 Agent
# 2. 未提及的改动          改了却没交代，可能藏了你不想接受的东西
# 3. 未被引用的测试代码    测试文件里改了，却不在它列出的任何测试用例内

优先级建议是：先看 Diff map 的红色部分，再看 Claim 里你不确定的陈述，最后才顺着 Flows 走一遍。原因是前两类是「它没告诉你的」，风险最高；而 Flows 是「它告诉你的」，读起来快但已经被它的话语组织过了。节点填充色表示改动类型——绿新增、蓝修改、红删除，只有描边的是未改动；测试节点是圆角，带一个「Agent 说：通过 / 失败 / 未跑」的徽章。

它也能复盘历史：让 Agent 描述任意一个已存在的提交，并明确不许改代码——此时仓库里不相干的未提交文件会以 uncommitted_changes 警告出现，属于预期现象。跨仓库场景加 --scan-siblings，会把邻居仓库里未提交的改动也纳入视野，通常会作为「未列出的仓库」提示出来，多数情况下与你无关，但能帮你发现「这次改动其实还动了另一个包」。真正让这套流程越来越省力的，是把每次纠正写回规则文件：哪些引用容易写错、哪类改动必须单独成节点、遇到日期选择器要点开控件而不是手输——积累几次之后，同一类任务的说明一次就能校验通过。

# 复盘一个已经提交的改动（明确不许改代码）
Run task-view instructions and write .review/change-auth-hotfix.json
for commit a1b2c3d. Don't change any code.

# 多仓库：把邻居仓库的未提交改动也纳入视野
task-view open .review/change-discount-refactor.json --scan-siblings

还有一层容易被忽略的用途：评审文件本身是留痕。谁让 Agent 在什么时候改了哪一段、理由是什么，都在这份 JSON 与它生成的页面里。对需要审计的团队，这比事后翻聊天记录可靠得多。而它不做的那些事——不接 CI、不在 PR 上评论、不做门禁——反而让它保持轻量：一个命令、一个页面、不留状态，随时可以弃用。