Jev agent tools

jev-agent-tools

六款面向证据的工具，适用于 pi、omp 和任何 MCP 客户端，并兼容 Jev API 格式。使用它们探索陌生代码、围绕仓库证据提出类型化问题、审查已完成的更改，以及选择现有测试。它们可与阅读、搜索和执行相辅相成，但不能取代这些操作。

观看发布视频（74 秒，MP4）。

第一次使用？请从入门指南开始；文档索引为不同受众整理了对应文档。

安装

通过宿主的包管理器安装，或向 MCP 客户端注册 MCP 服务。npm 包名为 jev-agent-tools。pi 和 omp 会直接加载其 TypeScript 源码；MCP 服务则随附预构建版本。

pi

pi install npm:[email protected]
# Project-local installation:
pi install -l npm:[email protected]

omp

omp plugin install [email protected]

任何 MCP 客户端

从 0.2.0 版本起，软件包还随附 jev-agent-tools-mcp，这是一个 stdio MCP 服务，可向任何 MCP 客户端提供相同的六款工具，包括 Claude Code、Claude Desktop、Kiro、Cursor、VS Code、Codex CLI 等。典型的 mcpServers 配置项如下：

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "/path/to/repository"],
      "env": {
        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
      }
    }
  }
}

在 Windows 上，大多数客户端启动命令时不会使用 shell，因此请将 "command": "cmd" 用作命令，并在 args 开头添加 "/c", "npx"。MCP 配置指南包含各客户端的配置文件、CLI 命令、变量插值、验证和故障排除信息。发布版本也会列在官方 MCP Registry 中，名称为 io.github.NomenAK/jev-agent-tools。将Agent 指引添加到 CLAUDE.md、AGENTS.md 或 Kiro steering 文件中，以便 Agent 正确使用和读取这些工具。

服务会读取与 pi 和 omp 相同的环境变量，以及 /jev-setup 保存的配置。每个服务进程对应一个会话。MCP 不提供自动的运行结束文档钩子；缺少此钩子并不意味着需要手动调用替代方案。在启用命令时，jev_ask 会标记为非只读；设置 JEV_TOOLS_ALLOW_COMMAND=0 可从其架构中移除 command。

要求和兼容性

需要 Node.js 24 或更高版本。支持的宿主基线版本为 pi 0.87.1 和 omp 18.4.10。这些是支持基线，并不表示已逐一验证所有更高版本。omp 使用其 Bun 运行时；基于 Node.js 的项目检查也需要 Node.js。必须提供 Git；如需可选的命令证据，还必须提供 Bash。在 Windows 上，命令证据会使用 Git for Windows bash（从 PATH 中 git 旁边的位置或 Program Files 下查找）；不会使用 WSL 的 bash.exe 启动器。设置 JEV_TOOLS_BASH 可指定另一个 bash 的完整路径。某些平台可能无法使用可选的原生解析器和文件搜索加速功能；受影响的工具会报告其限制。

已发布的 [email protected] 软件包也在 Linux 上通过 Node.js 24.15.0 搭配 pi 1.0.0 进行了检查：npm 安装、针对宿主类型的 TypeScript 检查、实际 CLI 中的全部六款工具，以及阅读指南注入均已通过。CLI 冒烟测试使用了模拟的对话提供方和 Jev 端点；它验证的是宿主集成，不代表实时模型准确性或涵盖了每种工具场景。

**pi 1.0.0 打包警告：**该软件包在 dependencies 中声明了 @sinclair/typebox，而 pi 要求由宿主提供的扩展模块放在 peerDependencies 中，并使用 "*" 范围。pi 会警告，单独安装的副本可能导致运行时模块重复。此警告未妨碍冒烟测试完成；它仍是一个打包问题，不代表兼容性不存在警告。

配置

交互式设置

在 pi 或 omp 的主交互式终端中，首次启动且尚未配置时，会显示 现在配置 / 稍后。随时运行 /jev-setup，即可更改端点、模型或密钥。密钥需在遮蔽字段中输入，绝不会作为命令行参数传递。选择 仅用于本会话（不会写入任何内容）或 保存以供后续会话使用。在任意步骤取消都不会更改任何内容。

标志	效果
--jev-skip-setup	本次运行不显示首次启动提示；仍可使用 /jev-setup。
--jev-url <url>	本次运行使用的端点。
--jev-model <name>	本次运行使用的 Jev 模型，不是对话模型。

在打印、JSON 或 RPC 模式以及子 Agent 中，不会显示对话框；请使用下方的环境变量进行配置。更改会立即生效，无需重启宿主程序。

交互式设置会等待提交或取消，不设凭据输入超时。首次启动提示不会在你查找端点或密钥期间让宿主程序的启动事件处理程序保持打开状态。

**各字段的优先级：**环境变量，然后是启动标志，再然后是本会话的设置、已保存配置，最后是默认模型 openjev。由环境变量或标志设置的字段会显示为受控状态，且绝不会保存。

已保存的配置位于仓库之外的 $XDG_CONFIG_HOME/jev-agent-tools/config.json（默认路径为 ~/.config/jev-agent-tools/config.json），存放于私有目录（0700）中的私有文件（0600）内。在没有权限位的 Windows 上，隐私由文件夹访问列表保障：保存时会限制为仅你、SYSTEM 和 Administrators 可访问；加载时若有其他账户可访问，则会拒绝加载。**密钥以明文存储，不会加密。**如果存储位置是符号链接、可被其他用户访问、不属于你所有或格式错误，系统会拒绝使用，而不会覆盖。MCP 服务也会读取此文件，读取顺序在环境变量之后。

环境变量

启动宿主程序前，使用你自己的端点和凭据设置以下变量：

export JEV_TOOLS_URL="${YOUR_JEV_ENDPOINT}"
export JEV_TOOLS_API_KEY="${YOUR_JEV_API_KEY}"
# Optional; already the default:
export JEV_TOOLS_MODEL="openjev"

YOUR_* 占位符是由你提供的输入，并非额外的产品设置。环境变量会在扩展加载时读取，且优先级高于其他所有设置。

变量	含义
JEV_TOOLS_URL	必填的完整端点 URL，须兼容 Jev API 格式。必须使用 https:；仅对 127.0.0.1、::1 或 localhost 接受纯 http:。
JEV_TOOLS_API_KEY	必填的 Bearer 凭据；配置值不会打印在工具输出中，命令子进程也永远不会收到该值。
JEV_TOOLS_MODEL	请求使用的模型字符串，默认为 openjev；这是一个会变化的别名，不保证与实际提供服务的模型一致。
JEV_TOOLS_MAX_CALLS	会话级非负安全整数调用次数上限；未设置或为空表示不限。值无效时会拒绝请求。
JEV_TOOLS_MAX_USD	会话级有限非负费用上限，可为小数；未设置或为空表示不限。值无效时会拒绝请求。
JEV_TOOLS_ALLOW_COMMAND	0 会在 jev_ask 中禁用 command；否则，命令会以普通 shell 权限运行，不会额外使用沙箱。
JEV_TOOLS_AUTO_DOCS	0 会禁用自动的运行结束文档检查。
JEV_TOOLS_BASH	可选；Windows 上用于运行 jev_ask 命令的 bash 完整路径。
JEV_TOOLS_ROOT	仅用于 MCP 服务：未提供 --root 时使用的仓库目录。

如果未提供端点或密钥，工具仍会注册并说明缺少的配置；自动文档检查会被禁用。不会回退到聊天模型。每个工具的 max_calls 与会话限制相互独立。响应中回显的模型名称无法证明实际提供服务的是哪个模型。

选择工具

工具	适用场景
jev_ask	一次判断需要综合考虑笔记、文件、早期版本或命令输出。
jev_ask_files	需要对每个候选文件分别应用相同的问题。
jev_find_files	需要找到某个行为目标的入口，但不知道文件名。在 omp 中，如果 find 可用，请使用原生 find。
jev_locate_in_file	需要在一个大小至少为 19 KB 的文件中定位相关范围。
jev_check_diff	已完成的更改需要进行风险、现有文档或规范审查。
jev_select_tests	需要为受影响的现有测试获取命令，但不运行或收集这些测试。

对于精确的源文本、已知符号、文件名、行号、计数和算术，请使用原生读取／搜索工具或代码。需要完整输出时，请自行运行命令。工具参考示例使用虚构的仓库路径，仅供说明调用方式，并非实际执行记录。

证据根目录

六种工具都接受可选的 root: string。未指定时，主机的当前目录或已配置的 MCP 服务目录将保留原有行为。覆盖值必须恰好指向初始仓库的 Git 顶层目录，或与其具有相同规范 Git common directory 的已注册活动工作树。在初始目录下解析相对覆盖路径；只有此参数接受绝对路径。收集证据、执行命令、访问缓存或作出判断之前，会拒绝子目录、其他克隆／仓库、向上遍历路径和符号链接组件。不会回退到其他检出版本。

本次调用中，获准的根目录决定文件、基准／差异、清单、规范路径、运行器计划和命令 cwd。它不会更改其他调用或自动文档钩子的行为。文件参数仍必须是仓库相对路径，并限制在仓库范围内。命令仍具有普通的 shell 权限，并非在沙箱中运行。使用结果前，请检查报告的权限、请求／生效的根目录和解析后的基准。

阅读结果

每项结果都以执行状态开头：complete、partial、not_judged 或 refused。这描述的是处理情况，而非正确性、安全性或覆盖范围。各项会区分新鲜或缓存的 Jev 判定、静态处理和从未判定的工作。静态选择和保守回退不会虚构概率。没有不确定性标记的已判定行属于结论：这是需要核查的线索，而非超出所提供证据的证明。

标记	含义和后续操作
unsure	答案存在歧义，或某项控制未通过。阅读所指段落，或补充能够消除疑问的具体证据。不要只改写问题。
abstain	缺少必要信息。获取指定证据，或暂不下结论；若证据变化后有必要，可选择再次调用 Jev。
no (not shown) / not addressed	所提供的证据未展示该陈述；这并不意味着该陈述为假。
uncalibrated	此问题没有适用的既定错误率校准；即使概率很高，也应将其视为提示。
Diagnostics and next actions	提供类型化的原因、来源、影响范围、重要性和恢复说明；区分不确定的判定与从未判定的工作。

普通布尔结论的概率区间为不高于 0.20 或不低于 0.80；类别／级别结论在应用适用控制后，要求领先选项的概率至少为 0.85。固定检查和导航工具有各自的阈值，详见其参考文档和设计。

记账会分别统计 HTTP 请求尝试次数、发送的问题数、请求的结果（新鲜／缓存／静态／未判定）、缓存探测次数、辅助控制和段落选择、当前报告的 USD 费用以及耗时。这些计数不可互换。缓存判定的 HTTP 请求尝试次数可以为零；零次尝试也可能表示执行了静态工作或未进行判定。费用未知表示未报告，并非免费。上下文值会区分已知、未知、未收集和不适用。

pi 和 omp 会通过 details.result 提供带版本的报告。2025-06-18 及之后版本的 MCP 会在 structuredContent.result 中提供同一报告，并附带声明的输出架构；较旧版本则会从同一报告生成自包含文本。文本会保留重要限制、证据来源以及实用的阅读／运行命令。

报告当前结论、决定性证据及其来源和范围，以及重要保留意见。如果原生阅读或执行在相同上下文中解决了先前的 unsure 或 abstain，应将当前结论归因于该原生证据，而非 Jev。如果 Jev 返回的不确定性仍然重要，应明确说明 Jev 未确认该结论，并指出缺失的证据及其影响。独立限制、过时证据和冲突的上下文都应保留。报告的检查结果不等于观察到的执行；无需提供详尽的历史记录块，也无需新建持久化登记簿。

pi 和 omp 的使用指南

该扩展会在两个宿主中提供共享阅读指南。omp 会在正常启动期间发现已启用的 npm 插件规则；pi 不会自动发现该软件包的 rules/ 目录。在 pi 中，相同的决策策略包含在 jev_ask 工具指南中，因此只要 jev_ask 处于启用状态，就会提供该策略。强制使用不透明提示词覆盖可能会绕过此集成；禁用的工具或 omp 规则不在此范围内。此 README 内容是推荐的使用指南，本身并非已安装的指令：

当 Jev 能改变尚未解决的决策或帮助聚焦检查范围时，用它做有限范围的语义判断。对于明确的原生阅读、搜索或授权执行，直接使用相应方式。调用 Jev 并非得出结论、完成审查或完成任务的前提。选择调用时，请提供比较双方，以及能够区分不同解释的证据。只有在证据或上下文发生变化，或出现有用的新问题时才重新检查；重复使用未变化的证据并不能解决问题。

MCP 客户端会将指南作为服务 instructions 接收，但有些客户端会忽略它。请将Agent 指令添加到项目的 CLAUDE.md、AGENTS.md 或 Kiro steering 文件中。

数据与命令安全

仓库证据、笔记和可选的命令输出会发送到你配置的端点。使用机密仓库前，请查阅该端点的数据处理政策。发送前，每个载荷字符串中的已配置 API 密钥值都会被删去；命令运行时不会设置 JEV_TOOLS_API_KEY。请参阅安全指南。

文件收集仅限于仓库范围：绝对路径、遍历父目录的路径、指向范围外的符号链接、Git 元数据和内部 URL 均不会作为文件输入。读取前会拒绝名称类似机密文件的文件（任何深度、任何大小写形式下的 .env、除 .env.example/.env.sample/.env.template 外的 .env.*、*.pem、id_rsa*、*.p12、credentials*、secrets*），并以原因 secret_pattern 标明。构建输出、二进制文件、锁文件和超大文件会被跳过或拒绝，并显示限制信息；证据不会被静默截断后用于得出判断。这种范围限制并不会对命令进行沙箱隔离。jev_ask 命令可在宿主 shell 权限范围内读取、写入或访问网络；运行时不会设置 JEV_TOOLS_API_KEY，且命令输出中的已配置密钥会被替换为 [redacted]。omp 会对命令使用执行审批；pi 不会为每个工具命令额外提供审批；MCP 客户端会使用各自的工具审批机制，且服务会将 jev_ask 标记为非只读。设置 JEV_TOOLS_ALLOW_COMMAND=0 可禁用命令。

自动文档检查

当工作树存在未提交更改时，扩展可在运行结束时检查现有 Markdown 文档，依据是相对于 HEAD 的更改，包括已纳入检查范围的未跟踪文件（未被 gitignore 忽略、名称不类似机密文件）；这些文件会在未显式调用工具的情况下发送到端点，最多进行 8 次 Jev 调用。对于被标记的现有句子，可请求额外一轮检查并更新该句子，或提供证据说明其为何仍然正确；标记本身并不能证明内容错误，也不要求进行第二次调用。仅仅不确定的部分不会触发额外一轮。若 JEV_TOOLS_AUTO_DOCS=0、缺少配置、会话预算无效或已耗尽，或工作树干净，则会跳过检查。错误和超时不会阻塞宿主。此可选择退出的宿主功能不能保证文档完整无缺。MCP 没有钩子，也不需要手动执行替代流程。

已知限制

静态证据和概率不能证明执行、安全或完整性。导入闭包无法发现所有关系；动态代码、不受支持的语法以及可选解析器故障都会留下明确的缺口。没有发现问题，并不证明未见的调用方或文档是正确的。测试选择会考虑已发现的现有场景，但不会判断是否必须添加新场景。会话缓存无法确定不断变化的模型别名的身份或稳定性。

开发与贡献

请参阅 CONTRIBUTING.md、CHANGELOG.md、设计文档 和 架构决策。请从文档索引开始；贡献者还可以添加架构文档和工具的工作原理。开发检查可在本地运行，无需联系评判端点：

npm ci --include=optional
npm run typecheck
npm run check:imports
npm run lint
npm test

内部源代码模块属于实现细节，并非稳定的库接口。

许可证

MIT。