Stage CLI 实战教程：用章节式审查告别 AI 代码大海捞针

AI 编码 Agent 能瞬间生成几百行代码，但真正卡住开发者的不是生成速度，而是审阅速度。面对一个 600 行的 AI 生成 diff，要逐行看完已经够痛苦了，更别说理解每一段改动的意图。

Stage CLI（npm 包名 stagereview）从一个反直觉的角度解决了这个问题：不是让你更高效地看 diff，而是让 diff 自己变成章节。它会自动分析你的本地代码改动，按逻辑分组为「章节」，每个章节附带一句前置说明——你一眼就能知道这章改了什么，再决定要不要深入看。

本文带你从安装到三个实战场景，快速上手这个开源工具。

安装

Stage CLI 是一个 npm 包，一条命令搞定：

npm install -g stagereview

安装后，在你的 AI Agent（Claude Code、Codex、OpenCode、Cursor 等）中运行：

/stage-chapters

它会自动分析当前仓库的本地改动，生成章节结构并在浏览器中打开一个审阅 UI。整个过程在你的机器本地完成，代码不会上传到任何服务器。

场景一：审查 Agent 生成的大型 PR

假设你让 Claude Code 重构一个 API 模块，它改了 12 个文件、增删 800 行。如果用传统的 git diff 看，你看到的是一锅粥——重构逻辑、类型定义更新、测试追加、注释修改全部混在一起。

用 Stage CLI：

/stage-chapters --ref unstaged

Stage 会自动识别出四个章节：

1. 核心路由重构（routes/user.ts + routes/post.ts）— 统一的错误处理中间件
2. 类型定义更新（types/*.ts）— 新增 ApiResponse 泛型
3. 测试覆盖（tests/**/*.test.ts）— 三个新测试用例
4. 配置与注释（.env.example + 注释修复）

每个章节都可以独立折叠展开，你只需要按章节顺序审阅，而不是在 800 行混合 diff 中找头绪。

场景二：对比两个分支的改动

在团队协作中，经常需要对比两个开发分支的差异。Stage CLI 支持分支间比较：

/stage-chapters --base main --compare feature/new-pipeline

或者更简洁的语法：

/stage-chapters main..feature/new-pipeline

这个场景特别适合 Code Review 场景——Reviewer 可以快速理解 feature 分支改了什么，按章节逐一评估，而不是逐个文件比较。

场景三：只检查已暂存的改动

有时候你只想审查已经 git add 的改动（staged changes），忽略未暂存的工作区文件：

/stage-chapters --ref staged

Stage 会自动只分析已暂存的 diff，并按逻辑分组。对于使用 git add -p 分块暂存的开发者来说，这正好配合你的工作流——你已经按小块暂存了，Stage 再帮你把相关的小块合并成逻辑章节。

进阶配置：.stageignore

如果某些文件你不想出现在章节分析中（比如构建产物、生成的代码），在项目根目录创建 .stageignore 文件：

build/**
dist/**
*.generated.ts

忽略的文件不会从章节中消失，而是归入「其他改动」章节——不会被遗漏，但不会干扰主要逻辑章节的清晰度。

与 AI Agent Skill 集成

Stage CLI 提供了一套完整的 AI Agent Skill，可以直接集成到 Claude Code 的工作流中：

npx skills add ReviewStage/stage-cli

集成后，你可以在 Agent 对话中随时执行 /stage-chapters，Agent 会自动调用 Stage CLI 并为你呈现代码改动的章节化视图。这本质上是一个元审阅层：Agent 负责生成代码，Stage CLI 负责帮你审阅代码，两者各司其职，互不干扰。

如果你用 Cursor 或 Windsurf，也可以在终端中直接运行 stage-chapters CLI 命令。Stage CLI 检测到非 Agent 环境时会自动回退到纯浏览器模式。

为什么 Stage CLI 比纯 diff 更好

普通 git diff 按文件顺序排列，AI 生成的改动又是跨文件交织的（改一个功能可能涉及 3 个文件）。Stage CLI 的核心价值在于跨文件的逻辑分组——它理解你的代码库结构，把分散在多个文件中的同一次改动聚合成一章。

这意味着：你花 5 分钟看章节标题和说明，就能在心里画出整份 PR 的地图，然后再用 10 分钟深入审阅。比在 800 行 diff 里漫无目的地滚动高效得多。

总结

Stage CLI 解决了 AI 编码时代一个被严重低估的问题：代码生成快于代码审阅。它不试图让 AI 帮你审阅（那会引入新的信任问题），而是给人类 Reviewer 提供了一条清晰的结构化路径。

如果你也在为 AI 生成的巨大 diff 头疼，试试 npm install -g stagereview && /stage-chapters。

开源地址：github.com/ReviewStage/stage-cli（213⭐，MIT 协议） npm 包名：stagereview 在线体验：stagereview.app