使用 Jev Review 持续评估 AI 辅助的代码质量

什么是 Jev Review？

Jev Review 是一个本地模型上下文协议服务器，可在 AI 编程代理工作期间为其提供结构化的软件质量信号。它支持 Claude Code、Codex、Cursor 和 OpenCode，并提供一个名为 jev_review 的专用 MCP 工具。

该工具会从正确性、复杂度、可读性、模块化、测试质量、可靠性、安全性和可维护性等独立维度评估代码。它返回数值评分、置信度、适用性指标和预定义的评分标准提示，而不是一篇叙述式代码审查文章。

Jev 提供质量信号，但你的主要编程代理仍负责诊断问题、修改代码并验证结果。

Jev Review 作为本地 Node.js 进程通过 MCP 标准输入输出运行。它没有托管后端、数据库、遥测服务或由作者运营的代理。包含明确提供的审查上下文的请求会直接发送到配置的 Jev API。

主要功能

• 持续评估：在每个连贯的实现阶段完成后审查变更，而不是等到任务结束。
• 独立质量维度：每个适用指标都会获得 1 到 10 的独立评分，以及 0 到 1 的置信度值。
• 迭代比较：提供先前的评估结果，以识别改进、回归和未解决的问题。
• 聚焦上下文：提交任务、差异、选定文件、仓库上下文，或适当组合这些内容。
• 本地执行：每个受支持的客户端都会通过标准输入输出启动同一个内置的 dist/server.js 进程。
• 不会自动访问仓库：服务器只处理明确传递给工具的上下文。
• 不生成人为的总分：Jev Review 保留各维度结果，而不是将其混合成可能造成误导的百分比。

前置条件

安装 Jev Review 前，请确保你具备：

• Node.js 20 或更高版本。
• 从 TypeSafe 控制台获取的 Jev API 密钥。
• Claude Code、Codex、Cursor 或 OpenCode。

快速安装

1. 导出 API 密钥

启动编程客户端前，将密钥设置到环境变量中：

export JEV_API_KEY="your-key"

不要将真实密钥放入提示词、源文件、差异或已提交的配置中。

2. 从 GitHub 安装插件

Jev Review 直接从其 GitHub 仓库分发，而不是通过 npm 发布：

npx plugins add NiazMorshed2007/jev-review

在出现提示时选择你的编程客户端，重启客户端，并确认 MCP 服务器已连接。

3. 请求审查

完成非平凡变更的实现和测试后，让编程代理使用 Jev Review。例如：

实现请求的身份验证变更，运行相关测试，并使用 jev-review 检查聚焦后的差异。检查重要维度中最薄弱的部分，只进行有充分依据的改进，并在最终交付前重新评分。

客户端专属设置

Claude Code

明确安装 Claude Code 目标：

npx plugins add NiazMorshed2007/jev-review --target claude-code

重启 Claude Code 并运行 /mcp，确认 jev-review 已连接。

如需仅通过手动 MCP 配置，请让 Claude Code 指向内置服务器：

claude mcp add --scope user jev-review -- node /absolute/path/to/jev-review/dist/server.js

从本地克隆进行开发时，也可以直接加载插件目录：

claude --plugin-dir /absolute/path/to/jev-review

Codex

安装 Codex 目标并重启客户端：

npx plugins add NiazMorshed2007/jev-review --target codex

运行 /mcp 验证连接。若要手动配置，请将以下服务器定义添加到 ~/.codex/config.toml：

[mcp_servers.jev-review]
command = "node"
args = ["/absolute/path/to/jev-review/dist/server.js"]
env_vars = ["JEV_API_KEY"]

Cursor

安装 Cursor 目标：

npx plugins add NiazMorshed2007/jev-review --target cursor

重启 Cursor 并检查设置 → MCP。内置技能名为 jev-review。你可以使用 /jev-review 调用它，也可以将其保留为由代理决定。

如需手动设置，请创建或更新 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "jev-review": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/jev-review/dist/server.js"],
      "env": {
        "JEV_API_KEY": "${env:JEV_API_KEY}"
      }
    }
  }
}

在 macOS 上，从 Dock 启动的 Cursor 可能不会继承 shell 配置文件中的变量。启动 Cursor 前，请让图形界面应用能够使用已导出的密钥：

launchctl setenv JEV_API_KEY "$JEV_API_KEY"

验证变量是否存在，但不要打印其值：

test -n "$(launchctl getenv JEV_API_KEY)" && echo "JEV_API_KEY is configured"

OpenCode

目前，OpenCode 尚未列为可移植的安装目标。请克隆仓库并手动注册内置服务器：

git clone https://github.com/NiazMorshed2007/jev-review.git
cd jev-review
opencode mcp add jev-review --global -- node "$PWD/dist/server.js"

对于技能和 MCP 服务器，都需要将类似下面的配置添加到 ~/.config/opencode/opencode.json，并替换其中的绝对路径：

{
  "$schema": "https://opencode.ai/config.json",
  "skills": ["/absolute/path/to/jev-review/skills"],
  "mcp": {
    "servers": {
      "jev-review": {
        "type": "local",
        "command": ["node", "/absolute/path/to/jev-review/dist/server.js"],
        "environment": {
          "JEV_API_KEY": "{env:JEV_API_KEY}"
        }
      }
    }
  }
}

运行 opencode mcp list 以验证连接。OpenCode 可能会将该工具显示为 jev-review_jev_review，但其底层 MCP 名称仍为 jev_review。

了解工具输入

jev_review 工具接受以下结构：

{
  task?: string;
  diff?: string;
  files?: Array<{
    path: string;
    content: string;
  }>;
  repositoryContext?: string;
  previousEvaluation?: Evaluation;
}

至少需要提供一个当前上下文字段。在大多数情况下，请发送任务和聚焦的差异。只有在理解变更需要周边实现细节时，才添加完整文件。

一个概念性的请求可能包含：

{
  "task": "Add input validation to the account creation endpoint",
  "diff": "<focused version-control diff>",
  "repositoryContext": "Node.js service using the repository's existing validation conventions"
}

此示例用于说明输入形式；编码客户端通常会代表你调用 MCP 工具。

推荐的评估工作流

1. 理解任务。 检查代码仓库、需求、约定和相关测试。
2. 实现一个完整切片。 完成一部分有意义的变更，而不是审查每个细微编辑。
3. 运行相关检查。 在请求评分来指导后续工作前，先验证行为。
4. 建立基线。 使用任务和聚焦的差异调用 jev_review。
5. 调查薄弱维度。 让编码代理检查实现，并针对每个重要弱点形成具体假设。
6. 进行最小且有依据的改进。 避免推测性重写或不必要的架构调整。
7. 再次验证。 重新运行测试、类型检查、代码检查工具或其他适合项目的检查。
8. 结合历史重新评分。 将之前的结果作为 previousEvaluation 传入，以获得各项指标的比较。
9. 在合适的时机停止。 当需求和检查均已通过，继续追求更高分数却几乎没有实际价值时，就应结束。

例如，比较结果可能显示可读性从 6.3 → 8.1 提升，而安全性保持为 8.2 → 8.2。这比单一的综合分数更有信息量，因为它准确显示了哪些质量维度发生了变化。

质量维度

核心维度

当所提供的上下文足够时，Jev Review 会评估：

• 正确性和需求契合度。
• 认知复杂度。
• 可读性和意图表达。
• 模块化和内聚性。
• 耦合和依赖质量。
• 可变更性和变更放大效应。
• 抽象和 API 设计。
• 项目和文件结构。
• 重复和复用。
• 可维护性。
• 可测试性和测试质量。
• 可靠性和错误处理。
• 安全性。
• 一致性和约定。
• 文档和可解释性。

上下文相关维度

只有在存在相关证据时，才会评估以下维度：

• 性能和资源效率。
• 可扩展性和灵活性。
• 兼容性和 API 稳定性。
• 可观测性和可运维性。

如果所提供的上下文无法支持某个维度，结果会使用 { "applicable": false }。评估器不会假设更短的函数、更小的文件、更多的层、更多注释、零重复或更多测试就一定更好。

高级技巧

保持审查上下文聚焦

发送任务和能够完整体现实现的最小连贯差异。只有在缺少上下文会妨碍可靠评估时，才包含完整文件。聚焦的提交内容更便于编码代理理解反馈。

Jev Review 不会自行添加字符数、令牌数或文件数量限制。不过，jev-latest API 的实际行为表明，提交状态上限大约为 32,768 个令牌。该限制未在 API 文档中公布，并且可能发生变化。如果 API 返回 max_tokens_exceeded，请移除无关上下文，或将工作拆分为连贯的审查切片。

使用之前的评估结果进行受控迭代

重新评分时，将完整的之前结果传入 previousEvaluation。Jev Review 会在本地进行比较，并报告各项指标的差异、改进、回归和未解决的弱点。之前的评估结果不会包含在发送给 Jev 的当前代码上下文中。

先诊断，再编辑

低分是一个信号，而不是根因解释。让编码代理检查实现，找出支持该弱点的证据，并提出最小修正方案。不要仅仅为了改变一个数字而重写代码。

优先满足需求，而不是追求分数

正确的行为和用户需求始终优先于提高分数。更高的分数并不能为破坏行为、扩大范围、添加无意义的测试、引入推测性抽象或创建不必要的层提供正当性。

同时使用专用安全工具

安全性是评估维度之一，但 Jev Review 是对依赖扫描器、密钥检测、静态分析、渗透测试及其他专用安全控制措施的补充，而非替代。

安全与隐私

本地 MCP 进程会读取 JEV_API_KEY，并且仅将其用于直接发送到 https://api.typesafe.ai/v1/systemone 的 TLS Authorization 标头中。Jev Review 不会存储或记录该密钥。

只有明确提供给工具的 task、diff、files 和 repositoryContext 会发送到 Jev。服务器不会自动发现或上传仓库文件。

评审上下文会离开您的计算机并发送到 TypeSafe 的 Jev API。请勿提交密钥或无关的专有材料。

有关远程服务如何处理所提交数据的信息，请参阅 TypeSafe 的隐私政策。

在本地开发 Jev Review

如需参与项目本身的开发，请克隆仓库、安装依赖并运行验证：

git clone https://github.com/NiazMorshed2007/jev-review.git
cd jev-review
npm install
npm run validate

常用的开发命令包括：

npm run check
npm test
npm run build
npx plugins discover .
claude plugin validate . --strict

npm run build 会创建已提交的 dist/server.js 构建包。单元测试和 MCP 协议测试使用本地模拟对象，不会消耗 Jev API 配额。实时 Jev 请求需要 JEV_API_KEY。

结论

Jev Review 为受支持的 AI 编程客户端增加了规范的质量反馈闭环，同时不会接管实现过程。安装本地 MCP 服务器，在完成有意义的更改后提交聚焦的上下文，使用各维度的结果指导谨慎改进，并比较不同迭代的评估结果。应将分数视为证据而非目标；当需求、检查和实际质量要求都已满足时即可停止。