持续观察进展与交付状态

JevSupervisionMiddleware 在 Agent 运行期间观察进展、偏航、验证需求和交付证据，向应用返回建议。适合研发任务、资料整理和需要多步工具执行的工作流。监督器不会自行停止任务、重放工具或宣布完成。

示例场景：Agent 在整理核查报告，如何判断该补证据还是交付

一个订单核查任务需要查询状态、汇总异常并生成有依据的报告。Agent 可能连续输出“正在处理”，也可能在没有完成验证时声称任务已结束。单凭输出活跃或完成措辞，不能判断是否有实质进展。监督中间件在运行过程中结合当前输出和宿主证据观察任务，建议继续工作、补验证、复核方向或进入完成复核。它只提供建议，不自行停止 Agent，也不会把“模型认为完成”直接写成任务完成状态。

基本 API

依赖 io.agentscope:agentscope-extensions-jev，版本随当前项目 BOM。类型位于 io.agentscope.extensions.judge.jev.supervision：JevTaskSupervisor、JevSupervisionMiddleware、SupervisionEvidence。

import io.agentscope.extensions.judge.jev.JevClient;
import io.agentscope.extensions.judge.jev.JevExecution;
import io.agentscope.extensions.judge.jev.supervision.JevTaskSupervisor;
import io.agentscope.extensions.judge.jev.supervision.JevSupervisionMiddleware;
import io.agentscope.harness.agent.HarnessAgent;
import java.time.Duration;

var client = JevClient.builder().build();
var supervisor = new JevTaskSupervisor(
    client::systemOne,
    new JevTaskSupervisor.Thresholds(0.2, 0.8), // 演示值，未校准
    JevTaskSupervisor.Limits.defaults(),
    new JevExecution.Options(
        JevExecution.Mode.SHADOW, Duration.ofSeconds(3), "supervision-v1",
        (ctx, record) -> System.out.println(record)));
var middleware = new JevSupervisionMiddleware(
    supervisor,
    JevSupervisionMiddleware.Schedule.defaults(),
    (ctx, observation) -> System.out.println(observation));

var agent = HarnessAgent.builder()
    .name("engineering-assistant")
    .model(model)
    .middleware(middleware)
    .build();

model 是已有生成模型；实际核查工具仍按原方式注册。第一层观察器记录检查是否成功、耗时和版本，第二层接收可供应用消费的监督建议。示例打印到终端，服务里应换成快速返回的元数据记录器。 Schedule.defaults() 限制检查频率和总次数；3 秒只约束一次证据读取与模型判断，不是限制任务必须在 3 秒内完成。先使用 SHADOW，可以确认哪些时刻建议补验证，而不改变现有任务流程。中间件也可以注册到 ReActAgent。OFF 不捕获或调用模型；SHADOW 保持输入、工具执行与输出事件原样；ENFORCE 构造时拒绝。API 构造要求显式指定模式。也可独立调用 supervisor.observe(ctx, () -> Mono.just(snapshot))，使用完全相同的检查定义与仲裁逻辑进行离线轨迹观察。Snapshot 包含 Scope、观察序号、任务、输出尾部、近期事件、运行/失败状态、截断标志、耗时和宿主证据。证据获取与模型请求共享一次 JevExecution 预算。

结合核查任务处理建议

检查按职责命名：

职责	检查
core.completion	implementation_complete、requirements_satisfied、ready_to_finish
core.verification	tests_sufficient、needs_verification
core.worker-health	meaningful_progress、worker_stuck、work_off_track
repository.instructions	agents_md_drift
core.human-escalation	needs_human
quality.documentation	documentation_sufficient，仅在明确要求文档时启用

每项返回原始概率及 YES / NO / UNKNOWN；UNKNOWN 不是否定。0.2 / 0.8 是演示阈值，需要按业务样本校准。仅影响当前决策分支的不确定项触发人工复核，信息性的 meaningful_progress 独立保留。 Decision<Report> 沿用 DECIDED / INCONCLUSIVE / ERROR / SKIPPED。Report 保留所有 Findings、全部 Proposal、选中建议、截断标志、验证状态、后端版本与用量。DECIDED 表示建议能够确定，不能解释为全部检查通过。错误或超限可以没有 Report。建议仲裁顺序为：人工需求 → 运行异常 → 活动 worker 的方向问题 → 证据不完整 → 当前验证缺失/不足 → 必需文档不完整 → 完成复核 → 与当前分支相关的不确定 → 继续工作。相同优先级比较概率，再按稳定顺序选择；仓库约束在相同置信度的健康问题之前。例如任务仍在查订单时，应用可以记录 CONTINUE；报告看似完整但缺少宿主验证时，应请求补验证；有版本匹配的成功验证后，才可能建议 REVIEW_COMPLETION。返回 CONTINUE、REQUEST_VERIFICATION、REVIEW_COMPLETION、REVIEW_DOCUMENTATION、REVIEW_DIRECTION 或 MANUAL_REVIEW。它们都不附带执行权。即使 REVIEW_COMPLETION，也不更改 Agent 或业务任务的完成状态。监督按当前 Agent 的 AgentResultEvent.result.generateReason 判断逻辑结果，与 Core 的 Session 生命周期一致。AllToolsDeniedEvent 和 RequestStopEvent 保留为观察事实，本身不表示 worker 失败；全拒绝后继续推理并正常完成的任务仍可进入完成复核。等待权限确认、工具挂起或 Hook/middleware 暂停时，任务保持未完成，不能因本次调用结束就进入完成复核。最终结果为 ALL_TOOLS_DENIED、MAX_ITERATIONS 或 INTERRUPTED 时，监督标记 worker 失败并阻止完成复核；离线 Snapshot 显式设置的 workerFailed 也保留此约束。迭代上限事件仍提供即时失败信号，异常退出原样传播。

可信验证证据

在本次 RuntimeContext 注入 EvidenceSource，提供带 revision 和作用域的产物与验证记录。缺少有效证据时不能得到完成复核建议。接入方法与有效性规则

预算、并发与取消

默认最小间隔 5 秒，周期 30 秒，每次调用最多 60 次评估，连续错误最多 3 次。新事件只使观察变脏；密集输出不会逐条发模型请求。没有新事件时仍按周期检查。每次调用仅一个判断在途，待处理 tick 保留最新一个。 Agent 事件继续流向下游，不等待语义结果。正常结束会等待在途判断，并在额度允许时再作一次终局判断，因而完成信号最多增加两次预算的等待；回调必须非阻塞。观察期间若有更新，Observation 标为 superseded，旧建议在消费接口降为 CONTINUE，分数保留供审计。该检查只覆盖观察到的运行事件；外部产物变化仍由宿主快照版本负责。取消会取消 tick、证据读取与在途判断，不追加终局观察；不能据此保证远端停止计费。Agent 异常原样传播，不重试整个 Agent。瞬时观察错误只记录，连续失败达到上限后停止该调用后续观察并建议人工复核，worker 继续原流程。总评估次数达到上限记录 ASSESSMENT_LIMIT；额度不会因长任务持续输出而无限增加。默认文本上限 12,000 字符、diff 30,000、文件数 100、整体 state 100,000 字符。任务和仓库约束超限时直接弃权，不裁掉关键约束。输出与 diff 可以保留尾部，但会标记截断并禁止完成复核；非文本输入或最终结果同样标为证据不完整。近期事件最多 32 个类型标签，不是完整轨迹归档。缺题、错误类型、非法概率、空响应、获取证据失败或超时均不构造完成结论。观察器 RuntimeException 被隔离。

运行与验证

按案例构建步骤设置 JEV_CP 后运行：

java -cp "$JEV_CP" io.agentscope.examples.jev.JevSupervisionExample

案例使用真实 ReActAgent、脚本模型、模拟订单工具与合成 JEV 响应。宿主检查工具恰好执行一次，再提供与当前观察 UUID 匹配的验证记录。预期输出包含 Tool executions: 1, advice: REVIEW_COMPLETION, verified revision: true。该例验证执行边界，不代表模型语义准确率。完整源码。用例将核查任务缩小为一笔订单，以便直接检查实际工具次数与验证收据；长任务方向判断和完成建议的准确率需要另用真实任务轨迹评测。