stage-cli-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stage CLI Code Review

Stage CLI 代码审查

Skill by ara.so — Devtools Skills collection.

Stage CLI is a code review tool that organizes local code changes into logical chapters and highlights what to review. It runs entirely on your local machine and works with any AI agent to help you review code before committing or creating pull requests.

由ara.so提供的Skill — 开发工具Skill合集。

Stage CLI是一款代码审查工具，它能将本地代码变更整理为逻辑章节，并突出显示需要审查的内容。它完全在你的本地机器上运行，可与任意AI Agent配合使用，帮助你在提交代码或创建拉取请求前进行审查。

Installation

安装

Install globally via npm:

bash

npm install -g stagereview

Or use directly with npx:

bash

npx stagereview

通过npm全局安装：

bash

npm install -g stagereview

或直接使用npx：

bash

npx stagereview

Core Commands

核心命令

Basic Review

基础审查

Review your current changes (auto-detects what to review):

bash

stage-chapters

This will:

Analyze your git repository
Detect staged/unstaged/untracked changes
Organize changes into logical chapters
Open a browser UI for review

审查当前变更（自动检测需审查内容）：

bash

stage-chapters

该命令会：

分析你的git仓库
检测已暂存/未暂存/未跟踪的变更
将变更整理为逻辑章节
打开浏览器UI进行审查

Review Staged Changes Only

仅审查已暂存变更

Review only changes that are staged for commit:

bash

stage-chapters --ref staged

仅审查已暂存待提交的变更：

bash

stage-chapters --ref staged

Review Unstaged Changes Only

仅审查未暂存变更

Review only unstaged working directory changes:

bash

stage-chapters --ref unstaged

仅审查工作目录中未暂存的变更：

bash

stage-chapters --ref unstaged

Review All Working Changes

审查所有工作区变更

Review staged + unstaged + untracked files:

bash

stage-chapters --ref work

审查已暂存+未暂存+未跟踪的文件：

bash

stage-chapters --ref work

Diff Against Specific Branch

与特定分支对比

Compare your changes against a specific base branch:

bash

stage-chapters --base develop

bash

stage-chapters --base feature/authentication

bash

stage-chapters --base origin/main

将你的变更与指定基准分支对比：

bash

stage-chapters --base develop

bash

stage-chapters --base feature/authentication

bash

stage-chapters --base origin/main

Common Workflows

常用工作流

Pre-Commit Review

提交前审查

Before committing, review staged changes:

bash

git add .
stage-chapters --ref staged

提交前，审查已暂存变更：

bash

git add .
stage-chapters --ref staged

Feature Branch Review

功能分支审查

Review all changes in your feature branch against main:

bash

stage-chapters --base main --ref work

审查功能分支相对于main分支的所有变更：

bash

stage-chapters --base main --ref work

Quick WIP Check

快速WIP检查

Review what you've changed since last commit:

bash

stage-chapters --ref unstaged

审查自上次提交以来的变更：

bash

stage-chapters --ref unstaged

Cross-Branch Comparison

跨分支对比

Compare your current branch against another feature branch:

bash

stage-chapters --base feature-a

将当前分支与另一个功能分支对比：

bash

stage-chapters --base feature-a

Configuration Options

配置选项

--base <ref>

--base <ref>

Specifies the base git reference to diff against.

Default: Auto-detects
```
main
```
,
```
master
```
, or
```
develop
```
Accepts: branch names, commit hashes, tags, remote refs

Examples:

bash

--base main
--base origin/develop
--base abc123f
--base v1.2.0

指定用于对比的git基准引用。

默认值：自动检测
```
main
```
、
```
master
```
或
```
develop
```
支持：分支名称、提交哈希、标签、远程引用

示例：

bash

--base main
--base origin/develop
--base abc123f
--base v1.2.0

--ref <mode>

--ref <mode>

Defines the scope of changes to review.

Options:

```
work
```
- All local changes (staged + unstaged + untracked)
```
staged
```
- Only changes in git staging area
```
unstaged
```
- Only working directory changes not staged
Default: Auto-detects based on repository state

Examples:

bash

--ref work
--ref staged
--ref unstaged

定义待审查变更的范围。

选项：

```
work
```
- 所有本地变更（已暂存+未暂存+未跟踪）
```
staged
```
- 仅git暂存区中的变更
```
unstaged
```
- 仅工作目录中未暂存的变更
默认值：根据仓库状态自动检测

示例：

bash

--ref work
--ref staged
--ref unstaged

Integration with AI Agents

与AI Agent集成

Stage CLI is designed to work seamlessly with AI coding agents. In your agent's chat interface:

/stage-chapters

Or with options:

/stage-chapters --ref staged --base develop

The agent can help you:

Interpret the review chapters
Identify potential issues
Suggest improvements
Explain complex changes

Stage CLI专为与AI编码Agent无缝配合而设计。在Agent的聊天界面中输入：

/stage-chapters

或携带选项：

/stage-chapters --ref staged --base develop

Agent可帮助你：

解读审查章节
识别潜在问题
提出改进建议
解释复杂变更

Programmatic Usage

程序化使用

While Stage CLI is primarily a command-line tool, you can integrate it into scripts:

bash

#!/bin/bash

尽管Stage CLI主要是命令行工具，你也可以将其集成到脚本中：

bash

#!/bin/bash

Review script for CI/local checks

用于CI/本地检查的审查脚本

Check if there are staged changes

检查是否存在已暂存变更

if git diff --cached --quiet; then echo "No staged changes to review" exit 0 fi

Run Stage review

运行Stage审查

stage-chapters --ref staged


```bash
#!/bin/bash

stage-chapters --ref staged


```bash
#!/bin/bash

Pre-push review workflow

推送前审查工作流

MAIN_BRANCH="main" CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

if [ "$CURRENT_BRANCH" != "$MAIN_BRANCH" ]; then echo "Reviewing changes against $MAIN_BRANCH..." stage-chapters --base $MAIN_BRANCH fi

undefined

MAIN_BRANCH="main" CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

if [ "$CURRENT_BRANCH" != "$MAIN_BRANCH" ]; then echo "Reviewing changes against $MAIN_BRANCH..." stage-chapters --base $MAIN_BRANCH fi

undefined

Understanding the Output

理解输出内容

Stage CLI organizes changes into logical chapters based on:

File proximity - Related files grouped together
Change type - New files, modifications, deletions
Logical boundaries - Module/component boundaries
Change complexity - Similar complexity levels grouped

The browser UI shows:

Chapter overview with file lists
Contextual diff views
Review points and suggestions
Navigation between chapters

Stage CLI基于以下规则将变更整理为逻辑章节：

文件关联性 - 相关文件归为一组
变更类型 - 新文件、修改、删除
逻辑边界 - 模块/组件边界
变更复杂度 - 相近复杂度的变更归为一组

浏览器UI展示：

包含文件列表的章节概览
上下文差异视图
审查要点与建议
章节间导航

Troubleshooting

故障排除

"Not a git repository" Error

"Not a git repository" 错误

Stage CLI requires a git repository. Initialize one:

bash

git init

Stage CLI需要git仓库。初始化仓库：

bash

git init

No Changes Detected

未检测到变更

Verify you have changes:

bash

git status

If using

--ref staged

, ensure files are staged:

bash

git add <files>

确认你有变更：

bash

git status

如果使用

--ref staged

，确保文件已暂存：

bash

git add <files>

Base Branch Not Found

基准分支未找到

Ensure the base reference exists:

bash

git branch -a  # List all branches
git log --oneline  # Check commit history

Use a valid reference:

bash

stage-chapters --base origin/main

确保基准引用存在：

bash

git branch -a  # 列出所有分支
git log --oneline  # 查看提交历史

使用有效的引用：

bash

stage-chapters --base origin/main

Port Already in Use

端口已被占用

Stage CLI starts a local web server. If the port is occupied, it will try alternative ports automatically. Close any conflicting applications if issues persist.

Stage CLI会启动本地Web服务器。如果端口被占用，它会自动尝试其他端口。若问题持续，请关闭冲突的应用程序。

Large Diffs Timeout

大型差异超时

For very large changesets, consider:

Review in smaller chunks:

bash

stage-chapters --ref staged  # Review staged first
stage-chapters --ref unstaged  # Then unstaged

Split commits into smaller logical units
Use more specific base branches

对于非常大的变更集，建议：

分块审查：

bash

stage-chapters --ref staged  # 先审查已暂存内容
stage-chapters --ref unstaged  # 再审查未暂存内容

将提交拆分为更小的逻辑单元
使用更具体的基准分支

Browser Doesn't Open

浏览器未打开

Manually open the URL shown in terminal output (typically

http://localhost:3000

or similar).

手动打开终端输出中显示的URL（通常为

http://localhost:3000

或类似地址）。

Best Practices

最佳实践

1. Review Early and Often

1. 尽早并频繁审查

Run Stage reviews before commits, not just before PRs:

bash

undefined

在提交前运行Stage审查，而不仅仅是在创建PR前：

bash

undefined

After making changes

完成变更后

git add -p # Interactively stage stage-chapters --ref staged # Review staged git commit

undefined

git add -p # 交互式暂存 stage-chapters --ref staged # 审查已暂存内容 git commit

undefined

2. Use Appropriate Scope

2. 使用合适的范围

Match the

--ref

option to your workflow:

Before commit:
```
--ref staged
```
Checking progress:
```
--ref unstaged
```
Full feature review:
```
--ref work --base main
```

根据工作流匹配

--ref

选项：

提交前：
```
--ref staged
```
检查进度：
```
--ref unstaged
```
完整功能审查：
```
--ref work --base main
```

3. Leverage Chapter Organization

3. 利用章节组织

Use chapters to:

Review related changes together
Spot unintended cross-module coupling
Identify missing changes in related files

通过章节：

一起审查相关变更
发现意外的跨模块耦合
识别相关文件中缺失的变更

4. Combine with AI Agent Review

4. 结合AI Agent审查

Let the AI agent analyze Stage's output:

Review the chapters from Stage CLI and identify:
1. Potential bugs or edge cases
2. Missing error handling
3. Inconsistent patterns

让AI Agent分析Stage的输出：

Review the chapters from Stage CLI and identify:
1. Potential bugs or edge cases
2. Missing error handling
3. Inconsistent patterns

5. Pre-PR Workflow

5. PR前工作流

Before creating a pull request:

bash

undefined

创建拉取请求前：

bash

undefined

Ensure all changes are committed

确保所有变更已提交

git add -A git commit -m "Feature complete"

Review full feature against main

审查相对于main分支的完整功能

stage-chapters --base main

Address review findings

处理审查发现的问题

Create PR

创建PR

undefined

undefined

Advanced Usage

高级用法

Reviewing Specific File Patterns

审查特定文件模式

Stage reviews all changes, but you can prepare specific changes:

bash

undefined

Stage会审查所有变更，但你可以准备特定变更：

bash

undefined

Stage only TypeScript files

仅暂存TypeScript文件

git add '*.ts' stage-chapters --ref staged

Stage specific directory

暂存特定目录

git add src/components/ stage-chapters --ref staged

undefined

git add src/components/ stage-chapters --ref staged

undefined

Multi-Branch Comparison

多分支对比

Compare changes across multiple branches:

bash

undefined

跨多个分支对比变更：

bash

undefined

Review branch A vs main

审查分支A与main的差异

git checkout feature-a stage-chapters --base main

Review branch B vs main

审查分支B与main的差异

git checkout feature-b stage-chapters --base main

undefined

git checkout feature-b stage-chapters --base main

undefined

Integration with Git Hooks

与Git Hooks集成

Add to

.git/hooks/pre-commit

bash

#!/bin/bash

添加到

.git/hooks/pre-commit

：

bash

#!/bin/bash

Launch Stage review before commit

提交前启动Stage审查

stage-chapters --ref staged read -p "Proceed with commit? (y/n) " -n 1 -r echo if [[ ! $REPLY =~ ^[Yy]$ ]]; then exit 1 fi

undefined

stage-chapters --ref staged read -p "Proceed with commit? (y/n) " -n 1 -r echo if [[ ! $REPLY =~ ^[Yy]$ ]]; then exit 1 fi

undefined

Additional Resources

额外资源

Website: https://stagereview.app
Examples: https://stagereview.app/explore
Blog: https://stagereview.app/blog
Discord: https://discord.gg/Hs7Eexp3
Twitter: https://x.com/StageReviewApp
GitHub: https://github.com/ReviewStage/stage-cli

The full Stage experience on the website offers additional features like team collaboration, persistent reviews, and integration with GitHub pull requests.

官网: 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拉取请求集成等额外功能。