用途 Stage CLI 是一款代码审查工具，用于在提交代码或创建 Pull Request 之前，对本地代码改动进行组织与审查。它把本地代码改动整理成逻辑章节，并突出显示需要重点关注的内容。该工具完全运行在本地机器上，可与任何 AI 智能体配合使用。
主要能力
- 将代码改动组织成逻辑章节；依据文件相近程度、改动类型（新增、修改、删除）、逻辑边界（模块/组件边界）以及改动复杂度进行分组。
- 分析 Git 仓库，检测已暂存、未暂存与未跟踪的改动。
- 打开浏览器 UI 进行审查，展示章节概览与文件列表、上下文差异视图、审查要点与建议，以及章节间导航。
- 支持按范围审查：全部本地改动、仅暂存区改动、仅未暂存改动。
- 支持与指定基线分支（或其他 Git 引用）进行差异比较。
安装方式 全局安装：npm install -g stagereview 或直接运行：npx stagereview
使用方式（核心命令）
- 基础审查（自动检测审查范围）：stage-chapters
- 仅审查已暂存改动：stage-chapters --ref staged
- 仅审查未暂存改动：stage-chapters --ref unstaged
- 审查全部工作改动（暂存 + 未暂存 + 未跟踪）：stage-chapters --ref work
- 与指定分支比较：stage-chapters --base develop、stage-chapters --base feature/authentication、stage-chapters --base origin/main
常见工作流
- 提交前审查：git add . 后执行 stage-chapters --ref staged
- 功能分支审查：stage-chapters --base main --ref work
- 快速查看进行中的改动：stage-chapters --ref unstaged
- 跨分支比较：stage-chapters --base feature-a
配置选项 --base <ref>：指定用于差异比较的基线 Git 引用。默认自动检测 main、master 或 develop。可接受分支名、提交哈希、标签、远程引用，例如 --base main、--base origin/develop、--base abc123f、--base v1.2.0。 --ref <mode>：定义审查的改动范围。work 表示全部本地改动（暂存 + 未暂存 + 未跟踪）；staged 表示仅暂存区改动；unstaged 表示未暂存的 工作目录改动。默认根据仓库状态自动检测。
与 AI 智能体集成 Stage CLI 设计为可与 AI 编码智能体无缝配合。在智能体聊天界面中使用 /stage-chapters，或带选项使用 /stage-chapters --ref staged --base develop。智能体可协助解读审查章节、识别潜在问题、提出改进建议、解释复杂改动。
程序化使用 可将 Stage CLI 集成进脚本，例如提交前检查暂存改动是否存在并运行 stage-chapters --ref staged；或在推送前针对 main 分支执行 stage-chapters --base $MAIN_BRANCH。
适用场景
- 提交前的暂存区改动审查
- 功能分支相对 main 的整体审查
- 进行中改动的快速检查
- 跨分支比较
- 在 AI 智能体辅助下进行代码审查与问题识别
限制与注意事项
- Stage CLI 需要 Git 仓库；非 Git 仓库会报 "Not a git repository" 错误，需先 git init。
- 若未检测到改动，可用 git status 核实，使用 --ref staged 时需先用 git add <files> 暂存文件。
- 基线分支不存在时，需通过 git branch -a、git log --oneline 确认有效引用，或改用如 origin/main 的引用。
- Stage CLI 会启动本地 Web 服务器；若端口被占用会自动尝试其他端口，仍失败需关闭冲突应用。
- 超大差异可能超时，可分批审查（先 --ref staged 再 --ref unstaged）、拆分为更小的提交单元，或使用更具体的基线分支。
- 浏览器未自动打开时，可手动访问终端输出的 URL（通常为 http://localhost:3000 或类似地址）。
附：网站为 https://stagereview.app，示例为 https://stagereview.app/explore，博客为 https://stagereview.app/blog，Discord 为 https://discord.gg/Hs7Eexp3，Twitter 为 https://x.com/StageReviewApp，GitHub 为 https://github.com/ReviewStage/stage-cli。网站上的完整 Stage 体验还提供团队协作、持久化审查以及与 GitHub Pull Request 集成等额外功能。