如何使用 Jev Review 执行结构化 Git 和代码库审查

Jev Review 的作用

Jev Review 是一个使用 TypeSafe Jev 构建的小型代码审查工作流。它可以审查 Git diff，或扫描所选范围内所有未被忽略的源文件，然后在简洁的本地仪表板中展示审查结果。

该工作流将编排和策略保留在应用程序代码中，同时使用 Jev 执行有界、结构化的判断。审查结果旨在作为审查提示，而不是证明缺陷确实存在的决定性证据。

审查工作流的运行方式

Jev Review 采用分阶段流程，在评估影响之前逐步缩小关注范围：

1. 构建风险矩阵。
2. 选择并评估文件特征。
3. 选择相关证据。
4. 对底层机制进行分类。
5. 评估严重性。
6. 当工作流要求时，将选定的审查结果提交给审查人员。

审查人员会检查正确性、安全性、可靠性、兼容性和测试覆盖率。评估测试缺口时，可以将已修改的测试或相关测试作为上下文。审查人员还会在评估影响前选择具体的 diff 代码块或源代码区域，同时应用结构化提示、反例、决策边界、阈值和工作流策略。

前置条件与安装

开始前，请安装 Node.js 24 或更高版本以及 Git。你还需要一个 TypeSafe API 密钥。

克隆项目或以其他方式获取项目，然后安装其依赖：

npm install

根据提供的示例创建环境文件：

cp .env.example .env

打开 .env 并添加你的 API 密钥：

TYPESAFE_API_KEY=your_api_key

请勿通过仪表板公开此文件。Jev Review 将仪表板绑定到 127.0.0.1，不会提供环境文件。

审查当前 Git Diff

要以 JSON 格式输出当前 Git diff 的审查结果，请运行变更审查命令并提供 Git 仓库路径：

npm run review:changes -- /path/to/git/repository

当你希望将反馈集中在仓库当前存在的变更上时，此模式非常有用。

要保存结果以便稍后在仪表板中查看，请使用保存变体：

npm run review:changes:save -- /path/to/git/repository

扫描完整代码库

如需进行更广泛的审查，请扫描仓库或软件包范围下所有未被忽略的源文件：

npm run review:codebase -- /path/to/git/repository-or-package

此命令会以 JSON 格式输出完整的代码库扫描结果。若要改为将报告保存到仪表板，请运行：

npm run review:codebase:save -- /path/to/git/repository-or-package

需要集中审查当前活动变更时，请使用变更审查入口；希望检查所选范围内所有可用源文件时，请使用完整代码库入口。

打开本地仪表板

保存变更审查或代码库扫描结果后，启动本地仪表板：

npm run dashboard

在浏览器中打开 http://127.0.0.1:4317。大型报告会以可折叠区块显示，便于你在不离开本地环境的情况下浏览审查结果。

命令参考

• npm run review:changes -- <path> 以 JSON 格式输出当前 diff 审查结果。
• npm run review:changes:save -- <path> 保存当前 diff 审查结果以供仪表板查看。
• npm run review:codebase -- <path> 以 JSON 格式输出完整代码库扫描结果。
• npm run review:codebase:save -- <path> 保存完整代码库扫描结果以供仪表板查看。
• npm run dashboard 启动本地仪表板。
• npm run check 对项目执行类型检查、验证依赖流，并对仪表板客户端执行语法检查。

了解项目结构

实现代码位于 src/ 下，并按仅依赖更低层级的分层结构组织：

src/
  domain/      config.ts, types.ts, patch.ts
  adapters/    git.ts, repository-files.ts
               report-store.ts
  review/      changes.ts, codebase.ts
               *-judgments.ts, workflow.ts
  cli/         review-*.ts, save-*.ts
  dashboard/   server.ts, public/

各层职责如下：

• 领域层：共享配置、报告类型、策略和 diff 解析。
• 适配器层：Git 与完整源代码发现，以及报告的原子化保存和加载。
• 审查层：特定模式的工作流、Jev 调用和分阶段编排。
• CLI 层：明确的审查和保存入口。
• 仪表板层：仅限本地访问的 HTTP 服务器和简洁客户端。

导入依赖从 cli 和 dashboard 向下流向 review，再流向 adapters 和 domain。仪表板层和 CLI 层不会相互导入。

高级用法与项目检查

在依赖工作流变更或贡献架构修改之前，请运行项目检查：

npm run check

此命令会检查类型、验证依赖流，并对仪表板客户端执行语法检查。当检测到向上的导入、cli 与 dashboard 之间的导入，或依赖循环时，依赖脚本会失败。

如需进行更有针对性的审查，请在完成相关 Git 更改后保存变更报告，并通过仪表板查看。对于范围更广的调查，请提供要扫描的仓库或软件包范围路径。这两个入口点将面向变更的工作流与完整源码工作流分开。

请记住，Jev Review 是一项用于组合快速类型化判断的实验。目前，它尚未集成编译器诊断、静态分析器、仓库索引或生成式解释。请将其发现视为人工审查的提示，尤其是在仅根据报告的严重性就要进行更改之前。

结论

Jev Review 提供两种实用的审查模式：针对当前 Git 差异的聚焦分析，以及对完整未被忽略的代码库范围进行扫描。安装依赖项，配置 TYPESAFE_API_KEY，保存报告，然后打开本地仪表板查看结构化发现。其分阶段判断、证据选择和明确的工作流策略，使它成为组织 AI 辅助代码审查的一项有用本地实验。