4.2 KiB
ADR-002：采用受约束工具执行与证据分型
- 状态：Accepted
- 日期：2026-08-04
决策
问师傅继续基于现有 Spring 服务实现受约束 Agent，不引入第三方自由 Agent 框架。LLM 负责语义规划和答案组织，服务端负责确定性事实校验、授权、工具执行、证据评估和引用复核。
工具结果分为 DOCUMENT_EVIDENCE 与 VERIFIED_FACT；用户陈述单独保存为 USER_ASSERTION。文档提到某系统只能证明文档内容，不能证明系统已接入或已查询实时数据。历史 LLM 回答不能成为事实来源。
DocumentEvidence.supportedNeedCodes/claimTypes 只表达语义分类器提出的候选支持关系。最终资格由服务端结合来源权威、来源类型、有效期、适用范围、正文逐槽位支持和逐 claim 蕴含共同判定；模型标签不能绕过门禁。正式场景模糊时 fail-closed。
执行循环最多三轮：首次工具执行、一次有明确证据缺口的补查、澄清或结束。最终模型只接收通过门禁的证据、事实、缺口、冲突和决策结果。
工具参数由注册 schema 约束：MY_CURRENT_TASKS 接收日期范围，KNOWLEDGE_SEARCH 不接收日期字段；授权作用域只从服务端 ExecutionContext 注入。运行时对调用 hash 去重，并限制调用数、候选数与耗时；超时作为受控状态结束当前链路。
原因
现有单工具计划、关键词早退、历史文本改写和数据工具 Citation 无法稳定支持多工具问题，也无法阻止文档事实与实时业务状态混淆。继续增加关键词和正则会扩大不可解释分支，不能解决授权、时效和证据完整性问题。
影响
- 保留现有统一 Agent API、认证解析、知识授权、RAG 治理和审计。
- 金额候选/送模/复核成为确定性校验器的第一条纵向切片。
- 旧路径在影子验证期间继续承担兼容回退。
- 新运行时先以默认
OFF的异步 SHADOW 旁路挂在现役文本入口之后；旧响应先完成，旁路不得改变客户端契约，媒体/附件不进入影子执行。 - SHADOW 使用有界队列、独立 watchdog 和单次原子终态；审计只保存 query hash、授权范围哈希、结构化代码、计数与耗时，不保存问题、答案、附件或工具正文。
- 工具必须声明 schema、授权、时效、幂等、审计和允许意图。
PARTIAL只能输出已覆盖 claim slots；零合格证据不调用答案模型。- 客户端最终按
DecisionStatus展示完整、部分、需补充、无依据和冲突状态。
本地验证更新（2026-08-04，ACTIVE 发布前的旁路阶段）
- 治理 Qdrant
aihr_knowledge_governed_v1已在本地以 MySQL 有效 production fragments 幂等重建：224/224 points 一致，1024 维 Cosine，BAAI/bge-m3，payload 治理字段完整。 - 当时真实 HTTP 只启用进程级
SHADOW诊断，旧响应保持用户可见；金额变体、能力查询、CRM 能力边界、待办+流程和第二项材料已通过双工具/能力工具观测。正式来源缺失时为NO_EVIDENCE或PARTIAL，不调用答案生成模型。 - 最近样本 Planner 约 1.4-4.1 秒、shadow 总耗时约 3.1-7.3 秒，默认 4 秒仅是旁路保护预算，不是生产 SLA。尚未具备客户端灰度接管条件，也没有在缺少 100-300 条人工黄金集时宣称召回率达标。
当前运行态（2026-08-04）
在保留上述隔离、回退和证据门禁原则的前提下，生产已通过受控发布将 AIHR_AGENT_GROUNDED_MODE 设置为 ACTIVE。当前只接管符合严格计划的文本 KNOWLEDGE_QA 与 LIVE_MY_WORK；媒体、资源、外网、写入、训练及不满足门禁的请求继续使用旧 Orchestrator。生产 JAR SHA-256 为 74d0cd2acc60ebf52f20eb8bee643f59395ba7cff3583076d671e57406f824ac，服务为 active，schema 预检 83/83，公开接口预检通过。
这不是对原决策中“先影子验证、再受控接管”原则的否定，而是该迁移顺序的当前阶段。认证态用户逐例问答、客户端状态 UI 全量验收和 100–300 条人工黄金集仍未完成；在这些证据补齐前，不宣称生产召回率达标，也不视为完整客户端灰度。