VQ Agent Core 三层 Agent 循环解析：让智能体可审计

Agent 框架的常见做法是把方向盘、油门和后视镜同时塞给一个大模型。VQ Agent Core 选择了另一条路：用 THINK → ACT → DECIDE → THINK 的锁定循环，把职责拆成三层。据 rss 源对该开源项目的分析，这个项目值得讨论的地方不在外观，而在架构决策本身。

核心循环：三层各司其职

agent.py 定义了 Agent 类。输入首先交给 THINK 层（think.py: understand()），返回一个 actionable_request，再由 ACT 层据此路由。ACT 由 needle_router.py 承担，底层是 Needle 2（cactus-needle==2.0.15）的语法约束函数调用——这意味着工具名和参数在构造层面就是合法的，而不是靠运气通过格式校验。

当路由置信度低于 router.confidence_threshold（config.yaml 中默认 0.7），或请求本身有歧义时，智能体会调用 _decide_gate()，也就是 DECIDE 层。随后 THINK 的 compose() 撰写最终回答。所有事件写入 runs/run-<timestamp>.jsonl，每次运行一个文件，形成完整审计轨迹。

语法约束函数调用（Grammar-Constrained Function Calling）：传统做法是让大模型自由生成文本，再用 JSON 解析器或正则去校验输出是否符合工具调用格式，一旦不合法就重试或报错。Needle 2 走的是另一条路——在解码阶段就通过对词表施加语法约束，把输出空间限制为合法的函数名与参数结构，使生成的 token 序列在构造层面即满足语法。这带来的直接好处是消除了"格式幻觉"：模型不可能输出不存在的工具名或类型错误的参数。代价是灵活性下降、对嵌套或自由文本参数的支持受限，因此这类引擎通常只用于路由和结构化决策，而非开放式生成。

THINK 的诚实降级机制

这是 think.py 中最值得称道的部分。当没有可用的本地模型时：

• understand() 直接返回带 via="skipped" 标记的原始请求——记录在案，而非隐藏。
• compose() 返回对实际发生事件的事实性结构化摘要，绝不编造 LLM 式散文。

媒体描述器会内联 100KB 以下的文本文件，并将二进制媒体标记为"仅通过元数据描述"，而不是凭空编造内容。代码注释写得很直白："Never fakes content." 更多 Agent 代码应该具备这一特性。

ACT 层：克制的工具注册表

工具存放在 tools/ 目录下，带有注册表（tools/__init__.py、tools.get(name)）。项目树中包含 local_tools.py（draft_text）、system_tools.py（get_time、sysinfo）、web_tools.py（web_search、fetch_url），以及 notes_tools 和 decide_tools。刻意保持精简——这是一个用于扩展的注册表，而不是什么功能都往里塞的大杂烩。

Needle 2 在桌面端通过 ctypes 进程内运行，或经 HTTP 连接到 needle CLI 二进制文件（serve 模式）——这正是 Termux/Android 方案，同一引擎能跑在手机上。

DECIDE 层：四个裁判，一个接口

deciders.py 是一个工厂，通过 config.yaml 中的 decider: 键选择（jev | local | auto）：

1. Jev（TypeSafe 云）——专用决策模型，一次调用返回 choice / score / noul。
2. Strands Decider 2B（本地）——Qwen3.5-2B + 指针头 + LoRA，Apache-2.0 许可，约 4.5GB 权重，单次前向传播得出校准的类型化答案。
3. Laya（本地）——约 1GB 的专用决策模型。
4. 基于提示词的本地 LLM——最后手段，严格 JSON 提示，未经校准但免费且离线可用。

LocalDecider._backends = ("strands", "laya", "prompt") 按顺序尝试，每个后端抛出类型化的 *DeciderUnavailable 异常由运行器捕获。四个后端暴露相同接口：decide()、classify_reply()、score_lead()、should_escalate()。把 Jev 换成端侧方案不需要改动任何调用代码，只改配置值即可。auto 模式意味着优先 Jev，失败后转本地。如果全部失败，错误向上传播，智能体升级到人工处理——安全的默认行为，且写进了代码。

具体任务方面：classify_reply() 把潜在客户邮件转化为如 demo_requested 的标签及置信度；score_lead() 返回线索温度与匹配度（1–5）；should_escalate() 返回概率和推荐操作。工具读取 agent.py 设置的同一个 VQ_DECIDER 环境变量，因此独立工具调用与运行中的智能体保持一致。

校准（Calibration）与指针头（Pointer Head）：未校准的模型输出概率往往与真实正确率脱节，例如模型说"置信度 0.9"但实际只有 60% 正确，这会让下游阈值判断失效。Strands Decider 2B 之所以强调"校准的类型化答案"，是因为它在 Qwen3.5-2B 之上加了一个指针头——一个轻量分类头，把隐藏状态直接映射到预定义答案选项的分布上，而非让模型自由生成答案文本。这种方法让输出天然落在封闭标签集内，并通过训练使概率分布贴近真实准确率。对需要"根据分数决定是否升级人工"的智能体而言，校准比单纯的准确率更重要，因为它决定了阈值何时真正有效。

should_escalate() 与人工升级（Human-in-the-Loop Escalation）：这是智能体可靠性设计中的一个关键安全阀。当所有自动决策后端都不可用，或 should_escalate() 返回高概率时，系统会把控制权交给人类而非勉强作答。这种设计承认模型能力边界，避免在不确定时输出低质量结果。与"诚实降级"一脉相承，升级机制把失败显式化——宁可停下等人，也不假装成功。在客服、线索评分等场景中，这一行为直接关系到误判成本，因此是否具备可靠的升级路径，往往比模型本身的准确率更能决定生产可用性。

上手运行

git clone https://github.com/Shivay00001/vq-agent-core.git
pip install -r requirements.txt
# 将 config.yaml 中 local_model.base_url 指向 OpenAI 兼容端点
# decider: jev | local | auto
python agent.py "score this lead: ..."

fetch_model.sh 辅助模型下载；phone-setup.md 覆盖 Termux 路径（Needle serve 后端 + 基于提示词的本地决策器，因为 torch 在 Termux 上装不上）。仓库还包含 test_agent.py、test_strands_backend.py，以及来自真实端到端运行的带日期工程笔记。

客观评价

这是个可用的基础，而不是成品：没有 UI，没有托管服务，THINK 的多模态能力取决于你所连端点背后的模型，本地 DECIDE 后端需要 PC 级机器。但真正重要的特性——诚实的降级、可替换的校准判断层、完整运行轨迹——都写在代码里，而不是 README 里。如果你正在构建需要审计或离线运行的智能体，值得一读。

仓库地址：https://github.com/Shivay00001/vq-agent-core

审计轨迹（Audit Trail）与 JSONL 事件流：每次运行生成一个 runs/run-<timestamp>.jsonl 文件，是"可审计"这一卖点的技术底座。JSONL（每行一个 JSON 对象）格式便于追加写入、流式读取和逐行解析，适合记录智能体运行过程中分散的时序事件——THINK 的输入理解、ACT 的路由结果、DECIDE 的裁判分数、最终 compose 输出。相比把状态塞进单条大 JSON，逐行事件流天然支持增量持久化和崩溃后恢复，也便于事后按时间线重放整个决策过程。对于需要合规、调试或复现的智能体场景，这种"运行即日志"的设计比可选的日志开关更可靠，因为它不可被绕过。