Jev Harness 常见问题
这些回答介绍 Apixly 的 Jev Harness v0.2.0，并区分运行时契约、历史真实推理证据与 说明性媒体，便于读者核对每一项声明。
Jev Harness 是什么？
Jev Harness 是运行 AI 编写任务脚本的 Python 运行时，工具权限和预算受控。 目标可以开放、路线可以未知；主 AI 定义能力与检查，新现场提供当前候选， Jev 根据反馈探索。主 AI 定义任务并注册工具； Jev 选择下一项已注册工具及程序提供的参数候选。程序执行已绑定动作，并独立检查目标 是否完成。它适合在明确边界内进行语义分支选择。详见项目概览 与架构。
开放目标需要预写完整路线吗？
不需要。每轮观察后可刷新工具可用性和参数域，子参数也能依赖已选父值。权限和资源 有边界不等于知道全部未来页面或参数。脚本定义能力，不写任务专用路由器。 通用证据引用读取和缺失参数后的探索恢复仍是开发优先项；新文本需要显式可信生成 工具。见开放目标与设计案例，其完整真实 验收仍待完成。
这是 TypeSafe AI 官方产品，或 PyPI 上的 jev-harness 包吗？
不是。这是 Apixly 在 apixly-ai/jev-harness
维护的独立社区软件。发行包名是 apixly-jev-harness，Python 命名空间是
apixly_jev_harness，CLI 别名是 apixly-jev-harness 与 jev-harness。
PyPI 上名为 jev-harness 的包属于另一个无关项目，请使用下方准确的 Git 安装地址。
架构参考资料列出了其他项目，但不代表
背书或继承其基准测试结果。
Jev Harness 与 Jev Filter 有什么关系？
Jev Filter 提供类型化的语义选择与过滤接口。 Jev Harness 围绕已注册工具、参数候选域和调用方负责的完成检查，构建有界的 观测、选择、执行、验证循环。它固定依赖 Jev Filter v0.4.1，使用其类型化批处理推理 传输接口及浏览器、桌面 surface，不重复实现推理。选择记录时可直接使用过滤接口； 需要多步、有界工具决策，并能独立观测进展的任务可使用 harness。 详见架构与采用步骤。
如何安装准确的 v0.2.0 版本？
需要 Python 3.10+ 与 Git。创建虚拟环境并安装带版本标签的仓库地址：
python -m venv .venv
. .venv/bin/activate
pip install 'git+https://github.com/apixly-ai/jev-harness.git@v0.2.0'
jev-harness spec
jev-harness init-task task.py
jev-harness check-task task.py
安装、spec、init-task 与 check-task 不调用模型，下载依赖仍需要网络。
通过 Jev 推理运行任务会计费，需要调用方通过 TYPESAFE_API_KEY 或
TYPESAFE_API_KEY_FILE 提供凭证。仅在主动开发时使用 @main。
运行前请遵循首个任务说明。
Jev 可以自行生成命令、选择器或工具参数吗？
不可以。Jev 只能选择已注册工具及已有参数候选。候选可以是静态值，也可以由可信的
只读 provider 根据当前观测生成。Option(id, description, value) 将模型可见的描述
与实际绑定值分开；depends_on 在父参数选定后构建子候选域。只有一个候选的域无需
推理即可绑定。模型输出不会成为可执行代码、任意文本参数、命令、路径、选择器或坐标。
业务工具仍须自行验证业务条件。详见参数协议。
Provider 参数数量判断以 follow_wrapped=False 获取入口签名，尊重显式 signature。 少于三个显式槽位的通用 *args 转发器保留 advertised 委托契约，所选两/三参数须同时 可绑定两个签名。这保留透明两参数转发器，同时支持显式 bridge；不改变 Task.tool 签名，也不证明所有 decorator 的元数据/函数体行为。模糊包装器应使用明确的两/三参数 入口或准确 Signature。见provider 证据， 不声称异步支持、提速或降费。
完整参数候选域在重复 ID/数量检查后、选择之前深拷贝，避免该次等待中共享来源修改 替换普通 Option/dict/list 实际值。Provider 保留身份并继续每次新调用，不缓存结果； 采集并未原子化，也不证明全局/业务 freshness。自定义 deepcopy 即使来自未选值也 可能失败，完整域复制按全部候选值的对象结构增加时间/内存开销，失败和未知用量 保留。见 快照证据，不承诺提速或省费。
Task.bind/execute 还要求标准 Action 以 builtin 类型比较匹配最近提供的快照：布尔 不同于数字，list/tuple 不同，有限数字 1/1.0 仍等价。这不是字节/对象身份。未修改的 Enum/str/dict/list 子类也可能被拒绝，应在提供候选前正规化，不要绑定后转换。直接 调用保留已有 ValueError 原因码；Engine execute 拒绝即使没进入工具函数体仍可能 是不确定状态。此前效果/未知用量保留，应核对后处理而非重试。标准 Engine 不主动 修改 Action。见已提供动作契约与 离线证据，不代表模型攻击、普遍错参、语义质量、 提速或省费。
什么任务适合使用 harness？
适合具有明确边界、有意义的语义选择、可信工具及可观测完成条件的任务，例如选择 前置工具、先收集证据再执行下一步，或准备允许操作的合成浏览器草稿。精确计算和固定 步骤交给程序；开放写作交给主 AI，或明确注册的可信生成工具。harness 没有内置通用 表单顺序，候选位置也不代表优先级；范围、前置条件与顺序由调用方提供。 详见下一步工具选择与 已有案例。
Jev Harness 如何判断任务已完成？
只有调用方的独立验证器根据观测状态检查通过，结果才是 done。仅由模型声称完成会
返回 needs_review。选中工具、提交动作或收到工具结果，本身都不是完成证据。
通过 result_context 准入的安全结果摘要可以推动下一步决策，但不能替代验证。
终态包会保留阻塞、缺少上下文、需复核及执行不确定等结果。
详见上下文与结果及
终态。
verify_state 使用递归的 builtin 匹配：布尔与数字不同，数字 1/1.0 仍等价，嵌套 list/tuple 类型不互换，字典 key 保留布尔/数字区别。不支持的类型/子类不匹配； 文本检查要求观察为 builtin str；预期文本仅接受 None/builtin str，其他类型/子类 在构造时拒绝，而不支持的比较值是不匹配。这收窄隐式自定义相等语义，其他有意的语义应使用 自定义 verify。拒绝错误完成可能带来后续工具和额外决策，不改变授权，也不证明提速、 省费、AI 准确率或真实 UI 验收。见类型验证证据。
主页浏览器演示是 Jev 真实推理录屏吗？
MP4 与 GIF 已标明为说明性截图回放，由当前 headless Camofox 对未修改的本地 合成表单截图生成。它们没有新模型调用，也不是连续录屏。另有历史真实推理验收： v0.1.0 使用 Jev 1.13.0 与 Camofox，在四次工具执行后到达最终状态，并独立检查最终 DOM 文本与字段。早期需复核及因授权门槛停止的结果也保留在证据中。没有发送真实 预订或消息。详见媒体范围与验收记录。
浏览器与原生桌面任务是否支持，是否已经验收？
浏览器适配器使用本机回环地址上的 Camofox 服务、最新观测目标、允许来源，以及 调用方针对具体点击的授权策略。原生桌面适配器使用固定版本的 macOS Accessibility 或 Windows UI Automation 后端，并指定具名应用或窗口；该适配器不支持 Linux 原生 桌面。原生桌面完成仍未验证：Mac 验收主机处于锁屏状态，项目没有宣称通过 Windows 真实环境验收。离线适配器测试不能证明原生任务完成。 详见适配器与证据边界。
Jev Harness 保证更省钱或更快完成吗？
不保证。真实 Jev 推理会计费。报告保留整段耗时、返回上下文、在有依据时按返回模型 分组的已知用量，以及缺少证据时的未知用量。缺少模型身份或中断的尝试不会被视为 零费用。已发布的小规模开发样例不能证明普遍的质量、延迟或成本优势。金额估算不是 发票，也不假设当前价目。各项实验的测量范围与负面结果可供核对。
请求计数不是发票。原生 Choice 的已有 telemetry.requests 计逻辑打包请求；可选 owned_transport 在终态 finish 时记录本次拥有的 SDK client 尝试与 HTTP client 对象 创建/复用。重试可让一个逻辑请求对应三次尝试；错误凭据也可能对应零尝试。不可靠计数 为 null，元数据缺省是未知。即使计数完整，也不证明 HTTP 发出、服务端收到、推理、 计费、TCP 连接或其他工具流量；未知用量仍未知。见 计数契约 与 A/B 范围。
运行时是沙箱吗？是否保证动作只执行一次？
不是沙箱，也没有跨运行的 exactly-once 保证。任务脚本是可信 Python；配置合法后仍会
导入脚本，并可能产生顶层副作用。静态 check-task 只解析和编译，不执行脚本；检查
通过不能证明运行有效。单次运行中，相同观测、动作 ID 和实际绑定参数的重复执行会
在执行前被阻止；这是一项执行保护，不是跨运行只执行一次或恢复运行的保证。
调用方业务工具负责身份、授权、幂等、事务及外部状态核对。不确定的动作不会自动重试。
详见静态检查、
执行上下文与终态。
当前执行窗口内，不确定的 DecisionStop 结果会携带可用的当前已绑定 action_id， 供定位私有日志并核对目标状态。它不证明成功或执行次数，不是幂等 key 或重跑许可； 终态不新增绑定参数，未知用量仍为未知。见标识证据。
任务编写者需要落实哪些执行与上下文边界？
推理不缓存结果，独立推理并发最多 30。同步运行时使用协作式墙钟预算检查点，每项 工具须自行限制 I/O 与轮询。在每轮顶部，验证返回 false 后先检查原有步骤上限，再在候选采集前 因该检查发现超时而停止；晚到的 true 仍完成 done，验证为 false 时 max_steps 仍优先于 此超时检查。不会中断回调，也 不是每个边界都检查，因此不是硬截止。此前效果/未知用量保留；跳过的空候选/抛错 候选回调不再提供原来的 blocked/failed 诊断。见 候选预算证据，不承诺普遍提速或省费。 固定观测下不支持重复调用同一个动作。默认上下文策略 保留最近八次已准入的动作结果及较早动作的记录；如果准入上下文仍超过保守的 15,000 字符预算，会返回复核，而不会悄悄丢弃约束。原始证据留在私有日志中，仅准入 安全摘要。详见上下文管理与 同步回调契约。
选择没有派发时，AI 应如何处理？
阅读当前选择遥测中的 planning，及 loop 诊断的工具或参数阶段。
request_needs_narrowing 表示类型化的输入需要收窄，request_needs_context 表示
缺少必需上下文/字段；未知规划状态使用通用 request_planning_review。应修正程序的
候选/描述或必需字段，并保留目标与安全约束，不盲目重试。这次选择未进入原生 runner，
但此前可能已有 loop 调用/效果或未知用量。上限、prompt 与模型选择不变，提供方/
HTTP413 失败及通用完整 spec 验证异常另行处理。见
规划契约 与
离线证据，不声称语义质量、提速或费用收益。