给它状态和选项，拿回概率分布

适合做什么

Agent 的大部分步骤不是写作问题：测试过了没有，下一步调哪个工具，这条命令能不能跑。常见做法是让一个 27B–70B 的模型写一段话，再从话里解析出布尔值。AgentJev 直接给出你提供的每个选项的概率，没有 JSON 需要修，也没有一句自信的错话需要识别。

五分钟跑起来

需要 Python 3.10+ 和一块 CUDA 显卡（本次优化后权重常驻约 1.4 GB 显存）；CPU 也能跑，但慢很多。左边是步骤，右边的终端按顺序回放这几步在本机的真实输出。

三种问题

一个请求是一段 state 加若干道题。state 可以是文字，也可以是对象或数组，对象会按键排序后紧凑地序列化成 JSON。题目的 id 只用来对应返回结果，模型看不到它；意思必须写进题目文字和选项描述里。

{
  "id": "done",
  "type": "boolean",
  "question": "Are all tests passing?",
  "criteria": {
    "true": "The suite is green.",
    "false": "At least one test failed."
  }
}

{
  "id": "next",
  "type": "choice",
  "question": "What is the useful next action?",
  "options": {
    "debug_failure": "Read the failing assertion.",
    "submit_patch": "Open a pull request now."
  }
}

{
  "id": "risk",
  "type": "score",
  "question": "How risky is this change?",
  "levels": [
    "Isolated change, no external behavior.",
    "A public signature changed.",
    "Authentication may be bypassed."
  ]
}

构造请求

在左边改状态和题目，右边实时生成请求体和各语言的调用代码，并按服务端的规则检查。“模型实际读到的文字”展示一条候选路径被拼成什么样。

读懂返回

每道题的答案都带完整分布。下面是一个 Boolean 门控在六段测试输出上的真实 P(true)。拖动门槛或点“扫一遍”，看哪些会被放行。门槛放多高取决于放错一次的代价：自动合并代码要严，提醒人工复核可以松。

问题：“Have all tests passed?”，带 criteria。状态是为本页编写的示例，概率是 v1 权重的真实输出（已校准）。

Python 客户端

agentjev_client.py 只用标准库。三个高阶方法各问一道题，evaluate(state, questions) 一次问多道。

批量与性能 本次优化 · PR #15

每个候选都会被拼成一条独立的路径：[状态][问题][候选]。以前，一个状态下有多少条候选路径，状态就要被骨干重算多少遍；只有当同一问题有 ≥8 个候选且前缀够长时才复用。现在，同一状态下的所有问题和候选合并成一棵 token 前缀树，一次前向算完。每个 token 只关注自己的祖先，位置编码取它在原路径中的深度，所以每个候选读到的仍然恰好是自己那条路径。

README 结果表里的 79.25% 来自训练时的 FP32 权重；发布的 BF16 权重经服务端是 79.35%（1,587 / 2,000），优化前后相同。逐题对比里变了的两道题，在优化前就是平局或近似平局（第一名与第二名相差 0.0031 和 0.0000），一道因此改对、一道改错。

• 把同一状态的所有问题放进一个请求，才能共享状态编码。分开请求，每次都会把状态重算一遍。
• 一次请求最多 32 个状态、128 道题、1,024 条候选路径，请求体 1 B–1 MB。多个状态放在 {"requests": [{"id", "state", "questions"}, …]} 里。
• 某个状态的前缀树太大（单次前向超过 8,192 个 token 或 64 MB 掩码）时，这个状态自动退回按问题共享的旧路径，结果不变。

写好问题

AgentJev 只看得到文字。题目和选项写得越像一个清楚的判断，分布就越可信。

接入 Claude Code

agentjev_hook.py 是一个 PreToolUse 命令钩子。Claude Code 执行 Bash、Write、Edit 前，它把工具调用发给本地服务，问一道 Boolean（安全吗）和一道四级 Score（风险多高），再给出三种判决之一：风险第 3 级并且判为不安全时，拦下这一次调用，理由交给 Claude，Claude 可以换一步继续；风险第 2 级及以上，或 P(安全) 低于 0.5 时，请你确认；其余情况不干预，按你自己的权限设置走。它从不回答 allow，所以不会绕过你的权限设置。服务没有响应时钩子直接退出，这次调用照常走权限流程。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          { "type": "command", "command": "python /path/to/agent-jev/agentjev_hook.py" }
        ]
      }
    ]
  }
}

真实输出，问题与 agentjev_hook.py 完全相同。默认连 127.0.0.1:8149；AGENTJEV_URL 改地址，AGENTJEV_ASK_LEVEL、AGENTJEV_ASK_BELOW 调整询问门槛，AGENTJEV_VERBOSE=1 让不干预的调用也显示判定。

排错