Jev-Review：面向 AI 编程代理的本地优先 MCP 代码评审插件

Jev Review

Jev Review 跑在本地，做成一个 MCP（Model Context Protocol，模型上下文协议）服务器。Claude Code、Codex、Cursor、OpenCode 写代码的时候，它能一边给它们打一个结构化的质量分。

编码代理（coding agent）依然负责诊断代码的弱点，并动手改代码。Jev 不干这事，只负责给一个快速的标量信号（scalar signal），覆盖正确性、复杂度、可变更性、模块化、测试、安全性这些独立的质量维度。

重要 你的 API key 只留在本机。

Jev Review 没有托管后端，没有数据库，没有遥测服务，也没有作者维护的代理。唯一的远程请求，直接发到配好的 Jev API。

概览

| 用途 | 持续、结构化的软件质量评估 |
| --- | --- |
| 支持的客户端 | Claude Code、Codex、Cursor、OpenCode |
| 分发方式 | 这个 GitHub 仓库，不发 npm |
| 运行时 | 本地 Node.js 进程，走 MCP stdio |
| 远程访问 | 用你的 API key 直接请求 Jev |
| MCP 工具 | 一个专注的工具，jev_review |
| 代码改动 | 一律由主编码代理完成 |

快速上手

需要 Node.js 20 或更新版本，一个从 TypeSafe 控制台拿到的 Jev API key，再挑一个编码客户端，Claude Code、Codex、Cursor、OpenCode 都行。

启动编码代理之前，先把 API key 设好

export JEV_API_KEY="your-key"

直接从 GitHub 装 Jev Review，不用发 npm

npx plugins add NiazMorshed2007/jev-review

按提示挑你的编码客户端，重启它，然后让代理在做一个非平凡的改动时调用 jev-review。

工作原理

flowchart LR
    A[Agent implements] --> B[Focused diff and context]
    B --> C[Jev Review MCP]
    C --> D[Jev evaluation]
    D --> E[Structured quality signals]
    E --> F[Agent improves the code]
    F -. review again .-> B

Loading Jev Review 就是给频繁、聚焦的检查点用的。一段连贯的实现切片写完之后，盯分数做完一轮改进之后，最终交付之前，都该过一次。

第一次调用是立基线。然后代理自己检查实现，对薄弱维度形成假设，改代码、验证、再打分。

Jev 返回的是带类型的 Score、Choice、Noul 决策，不是一篇自由格式的评论文章。它不会给你写一段散文解释为啥分低。

Jev Review 把这些决策校验、转换一下，输出指标分数、置信度（confidence level）、粗粒度的评分标准提示（rubric hints），还有跟上一次评估的对比。原因到底是啥、改动该怎么写，都得编码代理自己想，Jev 不管。

故意不给一个合成的 82/100 总分。Readability 6.3 → 8.1、Security 8.2 → 8.2 这种维度变化，比一个糊在一起的百分比有用多了。

客户端配置

| 客户端 | 插件安装 | 支持手动配 MCP |
| --- | --- | --- |
| Claude Code | npx plugins add NiazMorshed2007/jev-review --target claude-code | 是 |
| Codex | npx plugins add NiazMorshed2007/jev-review --target codex | 是 |
| Cursor | npx plugins add NiazMorshed2007/jev-review --target cursor | 是 |
| OpenCode | 见下方手动配置 | 是 |所有客户端都一样，本地起那个打包好的 dist/server.js 进程，走 stdio。

Claude Code

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

重启 Claude Code，跑 /mcp，看 jev-review 接上没有。

开发时想加载本地克隆

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

只想要纯手动 MCP 配置

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

Codex

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

重启 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

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

重启 Cursor，看 Settings → MCP。打包好的技能（skill）叫 jev-review，用 /jev-review 调用，或者保留 Agent Decides（由代理自行决定）。

手动写到 ~/.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}"
      }
    }
  }
}

如果 Cursor 是从 macOS Dock 启动的，shell profile 里的环境变量它不会继承。开 Cursor 之前，先把已经导出的 key 喂给 GUI 进程

launchctl setenv JEV_API_KEY "$JEV_API_KEY"

验一下，但别把 key 打出来

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

OpenCode

OpenCode 现在好像还没出现在 plugins 安装工具的目标列表里。直接让它指向上面那个打包好的服务器就行

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

想拿到完整的 skill 和 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。

MCP 工具

Jev Review 故意从一个工具起步，jev_review。

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

current-context 这一组字段至少要传一个。一般传 task 和 focused diff 就够了，只有改动需要周边实现一起看的时候，才补完整文件。Jev Review 从来不会自己去读仓库。

Jev Review 自己不设额外的字符、token、文件数量上限。token 上限是 Jev API 那边卡的，根据 jev-latest 实际跑的情况，提交状态（submitted state）大概封顶 32,768 tokens。这个数字 API 文档和 OpenAPI schema 里都没写，以后也可能变。

Jev 返回 max_tokens_exceeded 的时候，服务器会让代理砍掉无关上下文，或者把这次改动拆成几个连贯的审查切片。

返回内容里有这些东西

- 每个适用指标独立的 1–10 分数和 0–1 置信度。覆盖不到的维度，会返回 { "applicable": false }
- 按优先级排好的薄弱维度，加上粗粒度的预定义 rubric 提示，但不会自动生成根因分析
- 传了 previousEvaluation 的话，会返回每个指标的 delta（差值），以及改进、退步、还没解决的薄弱点

质量维度

只要上下文够，下面这些维度都会评估

- 正确性与需求匹配度（Correctness and requirement fit）
- 认知复杂度（Cognitive complexity）
- 可读性与意图清晰度（Readability and intent）
- 模块化与内聚性（Modularity and cohesion）
- 耦合与依赖质量（Coupling and dependency quality）
- 可变更性与变更放大（Changeability and change amplification）
- 抽象与 API 设计（Abstraction and API design）
- 项目与文件结构（Project and file structure）
- 重复与复用（Duplication and reuse）
- 可维护性（Maintainability）
- 可测试性与测试质量（Testability and test quality）
- 可靠性与错误处理（Reliability and error handling）
- 安全性（Security）
- 一致性与约定（Consistency and conventions）
- 文档与可解释性（Documentation and explainability）

只有证据摆在那儿的时候，才评估这些

- 性能与资源效率（Performance and resource efficiency）
- 可扩展性与灵活性（Scalability and flexibility）
- 兼容性与 API 稳定性（Compatibility and API stability）
- 可观测性与可运维性（Observability and operability）

评估器会看上下文再下判断。它不会无脑地认为函数越短越好、文件越小越好、零重复越好、分层越多越好、注释越多越好、测试越多越好。

评估流程

随附的 jev-review skill 教代理把 Jev 当成一个反复跑的标量反馈循环（scalar feedback loop）

1. 理解任务，把仓库翻一翻。
2. 实现一段连贯的改动，把相关检查跑一遍。
3. 调 jev_review，传聚焦的上下文，立基线。
4. 自己再看一遍代码，对薄弱的关键分数形成假设。
5. 做最小、最有依据的改动，再验一下。
6. 带上 previousEvaluation 再评一次，看改进和退步。
7. 只要还有别的有证据支持的改进点，就继续重复。
8. 需求和检查都过了，再刷分也带不来啥真实价值了，就收手。

正确性和用户的需求，永远排在分数前面。分数再高，也不能拿来给投机性的架构、不必要的抽象、范围扩张、破坏既有行为、没意义的测试、无脑的重写当遮羞布。