使用 Dot Reflex 14B 构建更安全的智能体恢复循环

Dot Reflex 14B 的作用

Dot Reflex 14B 是面向编程和工具调用智能体的执行恢复控制器。它不会取代工作智能体，而是审查智能体轨迹的精简 JSON 摘要，并建议外围执行框架应如何控制下一阶段的执行。

该控制器基于标准化执行事件运行，而不依赖工作模型的内部架构，因此可以监督由 GPT、Claude、Gemini、Qwen、Llama 或其他模型驱动的智能体。此版本是适用于 Qwen3-14B-Base 的 rank-64 QLoRA 适配器。

Dot Reflex 会返回以下十种动作之一：

• continue：允许合理的计划继续执行。
• verify：要求为某项声明或高风险假设提供证据。
• retry_differently：使用不同的命令、参数或方法重新进行当前尝试。
• replan：替换核心假设已经失效的方案。
• rollback：在发生有害变更后恢复到已知正常状态。
• branch：在独立环境中分别尝试多个可行方案。
• switch_model：在持续出现能力不足或服务提供商故障后，将下一次尝试路由到其他模型。
• ask_human：当需要权限、机密信息、澄清或外部决策时暂停。
• stop_successfully：在有充分证据支持任务已完成时结束。
• stop_failure：在没有安全且获授权的恢复方式时停止。

输出是一项建议，而非授权。权限管理、策略执行、工具调用、回滚机制以及是否停止的最终决定，仍由你的执行框架负责。

主要功能

• 框架无关的输入：控制器接受由智能体框架已记录的执行事件组成的普通 JSON。
• 机器可读的输出：每个有效响应都包含动作、理由、置信度、恢复指令和解析状态。
• 确定性生成：参考运行时采用贪心生成。
• 故障时默认关闭：当输入模式或生成的动作无效时，CLI 会以非零状态码退出。
• 多种接口：可以从命令行执行单次决策、通过标准输入传入 JSON，或托管本地 HTTP 端点。
• 跨模型监督：工作智能体无需使用 Qwen，也无需与控制器采用相同架构。

要求与安装

参考 4 位运行时需要 Linux 和 NVIDIA GPU。对于一次处理一个请求的场景，24 GB GPU 是实际最低要求；40–48 GB 则可提供更多余量。此版本不包含 GGUF、Ollama、MLX、CPU 或合并权重构建。

克隆代码仓库，创建 Python 虚拟环境并安装运行时依赖项：

git clone https://github.com/usedotai/dot-reflex.git
cd dot-reflex
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

GitHub 代码仓库包含运行时、测试、示例、文档和评估记录。大小约为 1.03 GB 的适配器托管在 Hugging Face 上，并会在首次使用时自动下载。固定版本的 Qwen3 基础权重也会由 Hugging Face 下载并缓存。

验证发布版本

在 Linux 上，从代码仓库根目录验证源代码包：

sha256sum --check SHA256SUMS

在 macOS 上，请使用下面的等效命令。请注意，macOS 未被列为参考 GPU 运行时的受支持平台。

shasum -a 256 -c SHA256SUMS

无需加载模型，即可验证源代码清单、固定的基础模型标识、JSON 示例、模式和图表记录：

python3 scripts/validate_release.py

准备智能体轨迹

Dot Reflex 需要精简的状态快照，而不是原始对话记录。确切的输入约定定义在 trajectory.schema.json 中。大多数智能体系统都需要一个小型适配器，将框架特有的事件映射到该结构。

例如，假设某个智能体修改了密码重置代码，并在未运行测试的情况下声称任务已经完成。其轨迹可能如下所示：

{
  "task_summary": "Add password-reset token validation",
  "execution_history": [
    {
      "step": 1,
      "actor": "agent",
      "action": "Modified auth/reset.py and declared completion.",
      "result": "Patch applied; no verification was run."
    }
  ],
  "tool_results": [
    {
      "tool": "pytest",
      "status": "not_run",
      "summary": "Tests were never executed."
    }
  ],
  "current_state": "Code changed, but there is no evidence it works.",
  "detected_failure_signals": ["false_completion_risk"]
}

随后，控制器可以识别缺失的证据，并返回如下结构化决策：

{
  "action": "verify",
  "rationale": "The agent claimed completion without test evidence.",
  "confidence": 0.98,
  "recovery_instructions": "Run the targeted reset-token tests, then the relevant auth suite.",
  "parse_valid": true
}

仅应包含执行框架能够准确支持的证据。缺失、过时或具有误导性的事件可能导致错误建议。

执行基本决策

代码仓库提供了一个针对虚假完成场景的轨迹示例。将其提交给单次执行 CLI：

python3 inference.py examples/trajectory_false_completion.json \
  --adapter usedot/Dot-Reflex-14B

也可以使用 - 作为输入路径，通过标准输入传入轨迹：

python3 inference.py - --adapter usedot/Dot-Reflex-14B \
  < examples/trajectory_false_completion.json

在编排器中，应同时检查进程退出状态和返回的 parse_valid 字段。非零退出状态表示输入模式或生成的动作无效，此时应阻止自动继续执行。

将 Dot Reflex 作为本地 HTTP 服务运行

安装额外的服务器依赖项，并使用 Uvicorn 启动 FastAPI 应用：

python3 -m pip install -r requirements-server.txt
uvicorn serve:app --host 127.0.0.1 --port 8080

将同一条轨迹提交到决策端点：

curl --fail-with-body \
  -H 'content-type: application/json' \
  --data @examples/trajectory_false_completion.json \
  http://127.0.0.1:8080/v1/decision

该示例绑定到 localhost。将服务暴露到网络之前，请添加身份验证、TLS、速率限制、请求大小限制和审计日志。

将控制器集成到智能体循环中

应在有意义的证据检查点调用 Dot Reflex，而不是在每生成一个 token 后调用。适合的检查点包括工具调用失败、重复动作、代码编辑、测试或构建结果、环境变更以及任务完成声明。

trajectory = harness.snapshot_for_supervisor()
decision = reflex.predict(trajectory)

if decision["action"] == "continue":
    harness.resume()
elif decision["action"] == "verify":
    harness.require_verification(
        decision["recovery_instructions"]
    )
elif decision["action"] == "ask_human":
    harness.pause_for_user(decision["rationale"])
elif decision["action"].startswith("stop_"):
    harness.stop(decision)
else:
    harness.apply_recovery_control(decision)

这种模式可以明确划分职责。Dot Reflex 对恢复需求进行分类，执行框架则负责实施实际操作。例如，只有当执行框架已经定义并授权相应的回滚原语时，rollback 建议才应触发该操作。

通过标准化事件，可以将控制器连接到 LangGraph、OpenAI Agents SDK、OpenHands、AutoGen、CrewAI、Google ADK 或自定义工具循环。除非使用封装器或钩子捕获 Cursor、Claude Code、Codex CLI 或 Aider 的事件流，否则它并不是这些工具的即插即用中间件。有关映射示例和兼容性说明，请参阅 INTEGRATION.md。

高级集成技巧

使用最小但具有决定性的验证

当动作为 verify 时，应优先采用能够确认或否定该声明的最小范围检查。在编程工作流中，这可能意味着先运行针对性测试，再运行规模更大的测试套件。记录结果，并在下一个证据检查点提交新的轨迹。

显式映射每一种动作

不要将未知或不受支持的动作视为 continue。应为全部十种动作定义执行框架行为，验证生成的动作，并在解析或策略检查失败时安全停止。

提供真实的恢复原语

只有执行框架能够强制实施建议时，建议才有实际价值。支持 branch 的系统应创建隔离的 worktree 或沙箱。支持 rollback 的系统应维护已知正常且可恢复的状态。多模型路由器需要真实的路由机制来实施 switch_model。

由人类掌控敏感决策

当智能体缺少权限、机密信息、澄清或外部决策时，应使用 ask_human。绝不能仅凭模型输出，授权破坏性、金融、医疗、法律、安全敏感或其他高影响操作。

在本地校准置信度

返回的置信度值是生成的文本，并非安全保证。在应用阈值或自动化策略之前，应使用能够代表自身环境的轨迹对其进行测量和重新校准。

保留证据和审计记录

保存输入轨迹、控制器响应、已执行的恢复动作及后续结果。这些记录有助于调查故障，并评估控制器能否迁移到你的工作负载。

了解评估边界

Dot Reflex 使用 6,000 条合成轨迹进行训练，并使用 600 条合成轨迹进行验证。已发布的 Agent Recovery Bench v0 评估包含 1,000 条类别均衡、留出的合成轨迹，以及另外 200 个有状态合成恢复回合。

在该合成基准上，此适配器取得了 1.000 的恢复准确率、1.000 的宏平均 F1 和 1.000 的模拟恢复得分。报告的平均延迟在 NVIDIA H200 上为 6.13 秒，但这是针对特定运行的测量结果，并非普遍适用的服务性能声明。

合成数据上 100% 的结果并不能证明其具有普遍可靠性。该基准既不是 SWE-bench，也不是端到端代码仓库问题解决测试或生产环境试验。

已发布的数据证明了模型对该基准分布的拟合程度，并不代表它能可靠迁移到独立编写的故障或生产环境故障。在引用结果或设计部署策略之前，请查阅 EVALUATION.md。

模型与运行时详情

• 基础模型：Qwen/Qwen3-14B-Base。
• 方法：采用 BF16 计算的 4 位 NF4 QLoRA。
• LoRA 配置：rank 64、alpha 128、dropout 0.05。
• 目标模块：注意力层和 MLP 投影层。
• 训练上下文：2,048 个 token。
• 可训练参数：256,901,120 个，占基础模型的 1.710%。
• 许可证：代码仓库和适配器文件采用 Apache-2.0。

Qwen 基础模型是独立的上游依赖项。在分发或部署组合系统之前，请查看其模型卡和许可证。

总结

Dot Reflex 14B 为智能体执行循环添加了结构化恢复层。首先安装 GPU 运行时，将现有事件转换为轨迹模式，并通过 CLI 测试一次决策。随后，可以添加 HTTP 服务，或在自定义执行框架的证据检查点调用控制器。应将执行权限保留在执行框架中，验证每个响应，保存审计证据，并在启用自动化之前使用自己的工作负载评估其性能。