Jev Filter

简体中文 · 快速开始 · 文档 · Agent 设置 · 基准测试

Jev Filter

用于 AI Agent 工具结果的语义过滤。 在大型工具输出进入 Agent 上下文之前，将其转化为精简、类型化的决策。源记录保留在程序中，返回相关证据和未解决的 ID，并可通过 ID 取回原始记录。

• 结合上下文进行过滤。 根据任务和提供的事实，筛选搜索结果、完整代码符号及相关日志。
• 让决策可追溯。 返回类型化答案、源 ID 和待审核项目；保留缺失事实和部分失败。
• 在程序中验证操作。 对于简短的浏览器和桌面目标，Jev 会选择观察到的控件；执行、安全关卡和最终状态检查由程序负责。

由 Apixly 维护的独立 MIT 项目。官方 npm 包：@apixly/jev-filter。了解它的功能及适用场景。

快速开始

Node.js 22+ · macOS / Linux · npm 发行包中包含 Python。 Windows：使用 WSL 或原生安装 Python。安装和 doctor 无需联网；推理需要 TypeSafe Jev API 密钥。

npm install -g @apixly/jev-filter
jev-filter doctor

在任意目录中运行：

export TYPESAFE_API_KEY='your-key'

jev-filter query --input - --mode choose \
  --task 'Choose the CURRENT unresolved DNS failure' <<'JSON'
[
  {"id":"a","text":"DNS recovered; requests now succeed."},
  {"id":"b","text":"DNS lookup still fails before connection."}
]
JSON

预期的筛选结果（省略诊断信息）：

{"selected_ids":["b"],"review_ids":[],"complete":true}

处理实际批次时，请在原始输出进入对话之前，通过一次调用完成收集和过滤：

jev-filter exec --task 'Find unresolved network failures' \
  --analysis analysis.json -- your-collector --json

请从可复制的分析约定开始。即使退出码为 2，也要解析数据包：complete=false 和 review_ids 需要关注。小示例有助于了解接口；精确路径、ID、选择器、计算和简短输出通常更适合使用原生工具。安装、密钥与结果处理 →

实用教程

• 为 RAG 和 AI Agent 过滤搜索结果：根据明确的证据要求筛选段落，再将其放入主模型的上下文。
• 按行为搜索代码：结合完整代码符号、可选的有限召回和语义判断。
• 分类处理相关日志：保留请求历史，并区分当前故障与已恢复事件。

其中包含可复制的合成输入和分析约定。在文档网站上阅读教程 · 常见问题。

实测优势

采用合成输入，于 2026-10-04 获取的付费实时证据。源哈希、每次运行的用量、耗时和失败信息均公开；每项结果仅适用于其声明的范围。

• **返回的工具上下文：**在 24 次真实 Agent 运行中减少了 91.6–97.2%。筛选后完成率为 12/12，原始完成率为 11/12，且 24/24 次运行的 ID 集合均正确。
• **相同输出的筛选：**Jev 的批处理 API 路径筛选 96 条记录的中位耗时为 1.313 秒；通过已登录的 Codex CLI，Luna 耗时 13.421 秒，Astra 耗时 14.543 秒。9/9 次运行均选出了相同的 48 个 ID；计入 CLI 启动耗时，且 Jev 之后没有主 Agent 继续执行。
• **Jev 阶段批处理：**2 次请求，而非 96 次；与单条记录并行 Jev 调用相比，输入令牌减少 56.5%，筛选速度提高 2.58 倍。这衡量的是 Jev 阶段，而非整个 Agent 的速度提升。

延迟和费用各不相同。六个整体操作测试项中有五个耗时更长，增幅为 0.1–18.4%；冷启动时的 API 等效费用范围为降低 23.2% 至提高 1.1%。订阅计费情况仍未知。上下文更短不保证延迟或费用更低。

方法、负面结果和复现 · 每次运行的整体操作数据

筛选路径、测量结果和范围

**快速语义筛选，并与相同的预期答案核对。**所有路径均根据两个语义条件筛选 96 条记录，并返回完全相同的 48 个匹配 ID。

测量路径	筛选中位耗时	完全匹配的运行次数
Jev jev-1.13.0 · 自动批处理 API	1.313 秒	3/3
Luna gpt-5.6-luna · 已登录的 Codex CLI	13.421 秒	3/3
Astra gpt-6-astra · 已登录的 Codex CLI	14.543 秒	3/3

此处比较的是可用的执行路径，包含 CLI 启动和主 Agent 轮次；未单独测量模型的原生延迟。主路径使用中等推理级别，且不使用工具。三次重复仅为冒烟测试样本，不能代表整个 Agent 的速度提升，也不保证适用于其他工作负载。每次运行的证据 · 方法和复现

| 优势 | 观察结果 | 范围与权衡 | |---|---|---| | **更快获得重复判断结果** | **筛选速度提升 2.58 倍**：**3.215 → 1.246 s**，**耗时减少 61.2%**；**Jev 输入 token 减少 56.5%**。 | 单条记录并行与自动批量并行 Jev 的对比，96 条合成记录 × 两个谓词，每组重复三次；**12/12** 次运行结果均精确。仅 Jev 阶段，并行工作线程上限为 12；并非与主模型进行速度比较。[数据](benchmarks/results/2026-10-04-live-batching.json) | | **让 Agent 的上下文保持聚焦** | **返回的工具上下文减少 91.6–97.2%**；筛选后完成率 **12/12**，原始完成率 **11/12**；**24/24** 个 ID 集合均正确。 | 24 次真实 Agent 运行，三个合成场景，两个主模型，每组重复两次。五个单元格中的六个耗时更长，增幅为 **0.1–18.4%**；冷启动 API 等效成本从**降低 23.2%**到**增加 1.1%**不等。订阅计费情况仍未知。[数据](benchmarks/results/2026-10-04-live-operations-summary.json) | | **找回更多相关代码** | 正确匹配数从 **4/12 → 10/12**，**误报为零**。 | 精确匹配与选择启用的召回率对比，两者均使用原生语义筛选。返回的上下文从 **5,284 → 9,706 bytes**；缺少词汇重叠时仍会漏检。[数据](benchmarks/results/2026-10-04-live-records.json) | | **检查重要变更** | 每次重复运行均选中全部 **4/4** 个目标变更；返回的上下文比保留所有文件少 **23.9%**。 | 八个合成文件，重复两次。语义分诊会增加模型用量，并将整个操作的中位耗时从 **503 → 1,465 ms**。[数据](benchmarks/results/2026-10-04-live-records.json) | | **连接真实接口** | **13/13 项付费 E2E 检查通过**，包括精确恢复 MCP 证据，以及 **64/64** 个调查主题标签。 | Python CLI、全新的 npm **0.4.0** JS/原生包、官方 MCP、本地 Chromium 提取和调查。使用小型合成样例；这些公共适配器无法提供解析出的模型身份。[数据](benchmarks/results/2026-10-04-live-interfaces.json) | | **滚动容器内的页面** | 在相同的严格 **0.55 / 0.10** 策略下，嵌套滚动完成率经验证从 **0/3 → 3/3**。 | 固定浏览器源码的 A/B 测试；程序会添加观测到的容器证据。六次常规目标运行仍需审核。成功完成更多操作会消耗更多调用、上下文和时间。[数据](benchmarks/results/2026-10-04-live-browser-final-ab.json) |

整体操作图表与复现

方法与所有实时结果 · 逐次运行 JSON · CSV · 可复现驱动程序

早期证据：离线契约、批处理与开放网络限制

| 实验 | 日期结果 | 范围 | |---|---|---| | 离线发布契约 · 2026-10-04 | **3/13 → 13/13** 项预期行为；**3 → 0** 项错误的夹具操作。 | 脚本化响应，不调用模型；审查和诊断上下文有所增加。[数据](benchmarks/results/2026-10-04-decisions.json) | | Jev 批处理 · 2026-09-22 | **输入令牌减少 56.5%**；批处理 + 并行比单记录并行**快 32.4%**。 | 96 条合成记录 × 两个谓词，重复两次；仅限 Jev 阶段。[数据](benchmarks/results/2026-09-22-live.json) | | 历史整体操作 · 2026-09-23 | **返回的工具上下文减少 88–97%**。 | 四种合成场景共运行 48 次；成本和延迟各有不同。[数据](benchmarks/results/2026-09-23-operations.json) | | 历史托管夹具 · 2026-09-30 | 浏览器 **Camofox 15/15**、**CDP 18/18**；桌面端 **12/12**。 | 在当时的规划器策略下使用本地夹具；这不代表当前严格策略或开放网页完成能力的保证。[数据](benchmarks/results/2026-09-30-hosted.json) | | 公共网站 · 2026-09-30 | 达成 **16/48** 项只读目标；排除访问限制和提供商故障后为 **16/34**。 | 在一种环境中测试 24 项目标。自定义小组件和验证表现较弱。[数据](benchmarks/results/2026-09-30-real-world.json) |

完整方法和历史数据。最新的浏览器实验保留了失败的裁剪方案和未知的提供商尝试；它们不会将安全停止转变为目标已完成。

观看程序如何将目标转化为经过验证的结果

每一步都会观察页面或窗口，让 Jev 从程序枚举的操作和控件中进行选择，重新检查目标，然后执行并验证。模型输出绝不会成为选择器、坐标、命令或未经审核的文本。不可逆操作会暂停并等待确认。

jev-filter browse --url https://shop.example/ \
  --goal 'Find in-stock red shoes in size 42' \
  --value query='red shoes' --verify-text 'Search results'

将示例 URL 替换为你获准测试的页面，并使用有意义的验证器。对于 browse 和 desktop，要求 status: done，并独立检查最终状态；extract 和 survey 则要求 ok 和 complete。仅选择了操作或模型报告了 DONE，都不能证明任务已完成。另一个经过验证的主规划器参考在严格审查后达成了 6/6 项预期结果；它会显著增加模型耗时，也不是产品中附带的自动回退方案。

交互式回放：浏览器、桌面端、调查 · 录制方法 · 安全门控与限制

一个核心，适配你现有的 Agent

CLI · Python · JavaScript / TypeScript · MCP。 使用 shell、嵌入 jev_filter.batch.run、从 @apixly/jev-filter 导入 createClient，或公开四个只读 MCP 工具。每种接入方式都会在同一个核心中保留证据和部分结果。JavaScript 和 MCP 示例 →

为 Codex、Claude Code 或其他兼容的执行环境安装提供的技能：

# Codex; use ~/.claude/skills for Claude Code.
mkdir -p ~/.codex/skills
cp -R "$(npm root -g)/@apixly/jev-filter/skills/jev-filter" ~/.codex/skills/

为 Agent 指定一条路由规则：

Use jev-filter for many records that need a clear semantic judgment.
Pass the task, scope, exclusions, success criteria and sourced facts.
Keep collection → analysis → compact output inside one tool call.
Inspect unresolved IDs; use native tools for exact or short work.
Do not repeat settled judgments or wrap an existing Jev workflow again.

Jev 不会继承 Agent 的对话内容。将共享事实放入 context，将历史记录放在每条记录中，并声明必需字段。授权和执行验证应由你的宿主程序负责。五分钟快速设置 → · 完整集成指南 →

根据任务选择合适的入口

任务	命令 / API	指南
捕获可信命令的输出	exec	采集器方案
选择或分类 JSON 候选项	query	结合上下文进行选择
定位代码行为	code-search	完整代码符号
审查范围明确的 Git 更改	diff-review	CLI 参考
分诊相关的 JSON/JSONL 事件	triage	关联日志
在本地 Camofox 页面上选择控件	locate	浏览器选择
完成简短的网页目标或提取页面记录	browse · extract	托管浏览器指南
完成 Windows/macOS 应用目标	desktop	桌面指南
分类并总结多条记录	survey	调查指南
在 Python 中嵌入类型化推理	jev_filter.batch.run	Python 集成
离线评估带标签的决策	eval	评估示例
连接 Node.js 程序或 MCP 宿主	createClient · mcp	集成示例

从输入到发布均可检查

• 有界、无缓存的推理。 自动批处理，最多 30 个请求同时进行；不缓存结果。
• 本地证据和数值遥测数据。 私有归档支持按 ID 恢复原始内容。可选的本地仪表板会显示用量、未知项和负净值；与输入等值的估算不等于发票节省额。
• 明确的信任边界。 推理输入会发送给 TypeSafe。exec 会运行你信任的命令，并非沙箱。托管执行会保留新鲜度、来源和桌面安全防护机制。安全策略
• 可移植、可验证的发布版本。 Python 核心、打包的 npm 平台包、校验和与构建来源证明。分发与恢复

旧版 jev-context 命令和 Python 导入方式仍保持兼容。Jev Filter 由 Apixly / JIA-ss 独立维护，与 TypeSafe 无关联。

参与贡献

git clone https://github.com/apixly-ai/jev-filter.git
cd jev-filter
python -m venv .venv && . .venv/bin/activate
python -m pip install -e '.[code,dev]'
sh scripts/check.sh
npm test

贡献指南 · 开发与发布 · 更新日志 · 报告问题 · MIT 许可证