85 lines
6.8 KiB
Markdown
85 lines
6.8 KiB
Markdown
# 帮道受约束业务 Agent TechSpec
|
||
|
||
状态：`IMPLEMENTED_AND_LOCALLY_VERIFIED_SHADOW`。未接入现役 `/api/aihr/agent/**` 请求入口，未部署生产。
|
||
|
||
## 目标
|
||
|
||
将当前由关键词路由、RAG 回答和单数据工具组成的问师傅链路，迁移为受约束、可授权、可审计的业务 Agent。RAG 是工具之一；最终回答只能使用通过门禁的文档证据和实时事实。
|
||
|
||
## 不变量
|
||
|
||
1. LLM 不得生成或覆盖 `tenantId/userId/projectId/spaceId/appId/extPartyId/role` 等授权字段。
|
||
2. 原问题中的数字、币种、日期、期限、比较符、否定和版本必须由确定性校验器保真。
|
||
3. `DOCUMENT_EVIDENCE`、`VERIFIED_FACT` 和 `USER_ASSERTION` 永久分型，不能互相升级。
|
||
4. 历史回答只用于语言理解，不具有事实资格；跨轮事实只能通过重新鉴权的 `factRef/citationId` 延续。
|
||
5. 初次执行加一次有明确证据目标的补查；第三轮只允许澄清或结束。无新增证据目标立即停止。
|
||
6. 零合格证据直接返回 `NO_EVIDENCE`，不调用答案生成模型。
|
||
7. 模型私有思维过程不保存、不展示；只记录结构化 action、observation 和 reason code。
|
||
8. 模型输出的 `supportedNeedCodes/claimTypes` 仅是候选支持关系，不能授予“已证明”资格；正式场景无法确认正文支持时必须 fail-closed。
|
||
9. 工具调用参数必须匹配服务端注册的 schema。日期范围只进入 `MY_CURRENT_TASKS`，不得进入 `KNOWLEDGE_SEARCH`；授权与作用域参数始终由 `ExecutionContext` 注入。
|
||
|
||
## 核心契约
|
||
|
||
- `ResolvedContext`：问题与上轮状态的关系、当前目标、候选实体、用户陈述、可信引用和缺口。
|
||
- `SemanticQueryPlan`：原问题、规范化问题、意图、领域、候选实体、证据需求和白名单动作。
|
||
- `ExecutionContext`：服务端从认证上下文解析的租户、主体、应用、项目、空间与角色；不进入模型输入。
|
||
- `ToolCall`：只包含工具代码和业务参数。
|
||
- `ToolResult`：工具状态、文档证据、实时事实、缺口、冲突和结构化观察。
|
||
- `DocumentEvidence`：引用 ID、来源权威/类型、版本、生效时间、适用范围、正文、候选 `supportedNeedCodes` 和候选 `claimTypes`。
|
||
- `VerifiedFact`：事实引用、类型、值、来源系统、查询时点、TTL、范围和授权快照。
|
||
- `DecisionResult`：`ANSWERED/PARTIAL/NEEDS_INPUT/NO_EVIDENCE/CONFLICT` 与领域结果。
|
||
- `GroundedAnswer`：摘要、确定性陈述、步骤、缺失信息和澄清问题；陈述和步骤逐项绑定引用。
|
||
|
||
Java 契约以 `AihrAgentGroundingDto` 为准。HTTP DTO 在兼容期保持 additive，旧客户端可继续读取 `answer/citations/data`。
|
||
|
||
## 模块边界
|
||
|
||
- `agent.context`：上下文关系识别、结构化会话状态和引用失效。
|
||
- `agent.planning`：受约束语义规划及确定性实体校验。
|
||
- `agent.tool`：Spring Bean Tool Registry、参数 schema、授权策略和执行。
|
||
- `agent.evidence`：来源、授权、有效期、适用范围、证据槽位与冲突评估。
|
||
- `agent.runtime`：最多三轮的有限状态执行器。
|
||
- `agent.answer`：基于已验证输入的组装与 Claim/Reference 校验。
|
||
- `knowledge`：继续负责 MySQL/Qdrant 检索、治理过滤、候选追踪和原文件重新鉴权。
|
||
|
||
## 证据资格与结论校验
|
||
|
||
证据需求按槽位逐项判断，不能因为标题、领域相同或模型标签命中就让一份文档满足全部需求。文档槽位只有同时满足以下条件才算已覆盖：
|
||
|
||
1. 来源权威、来源类型、版本、有效期和适用范围通过治理门禁。
|
||
2. `supportedNeedCodes` 明确包含当前需求，且 `claimTypes` 包含该需求映射的结论类型。
|
||
3. 正文独立支持对应结论类型；模型分类结果与正文保守判定取交集。
|
||
4. 最终逐 claim 校验正文蕴含、数字一致性和引用 ID 属于本轮通过门禁的证据。
|
||
|
||
额度片段只可支持 `AMOUNT_RULE`，不能自动支持 `PROCESS_STEPS/MATERIALS/APPROVAL`；操作手册步骤也不能自动证明额度或适用资格。制度/流程结论只能由合适 authority/kind 的 `DocumentEvidence` 支持，实时状态只能由未过期、重新鉴权的 `VerifiedFact` 支持。`PARTIAL` 只输出已覆盖槽位，缺失步骤不得由最终模型补齐。
|
||
|
||
## 有界执行与工具参数
|
||
|
||
`MY_CURRENT_TASKS` 只接受 `dateRange/startDate/endDate/status`，`KNOWLEDGE_SEARCH` 只接受 `query/domain`。Planner 对模型参数按工具 schema 收敛，Tool Registry 在执行前再次校验；`tenant/user/project/space/app` 等授权字段出现时整份模型计划失效。
|
||
|
||
运行时只允许初次执行和一次具有新增证据目标的定向补查；第三轮只允许澄清或结束。同工具同规范化参数通过 hash 去重，无新增证据目标立即停止。运行时设总工具调用数、候选数和耗时预算；超时映射为受控 `TIMEOUT`，迟到结果丢弃，不无限重试，也不把失败详情交给答案模型。
|
||
|
||
`aihr_knowledge_conversation.context_json` 继续保持旧版 `List<Turn>` 格式。结构化状态使用 additive
|
||
的 `state_json/state_version` 列；其中的 `factRef` 仅映射到服务端保存的工具代码、业务参数、
|
||
`itemKey`、时点、TTL、作用域、授权快照和审计引用，不保存工具事实正文。引用再次使用时必须按
|
||
当前 tenant/app/user/conversation/project/version 重新读取并调用已注册工具，不能接受客户端回传的事实内容。
|
||
|
||
## 迁移顺序
|
||
|
||
1. 新契约和 Semantic Planner 以影子方式运行，不改变旧响应。
|
||
2. 将 `MY_CURRENT_TASKS` 与 `KNOWLEDGE_SEARCH` 接入 Tool Registry，分别返回事实和文档证据。
|
||
3. 新 Evidence Evaluator 和 Grounded Composer 只接管新 Planner 能完整规划的请求，其他请求回退旧链路。
|
||
4. 增加结构化 ConversationState、引用 TTL/重新鉴权和纠正失效。
|
||
5. 黄金集达到门槛后，逐步退出旧 Planner 的关键词早退和 Orchestrator 文本边界分支。
|
||
|
||
## 兼容与回滚
|
||
|
||
- 不直接删除 `AihrAgentPlanner`、`AihrKnowledgeConversationService` 或现有 RAG 回答。
|
||
- 新运行时仅在计划通过严格 schema 校验且所有动作已注册时接管，否则回退旧链路。
|
||
- 数据库变更使用 additive、幂等 MySQL 8 SQL；旧服务忽略新增列。
|
||
- 不接入自由 ReAct 或第三方 Agent 框架。
|
||
|
||
## 验收
|
||
|
||
首批 30 条纯内存契约黄金集覆盖金额口径、`哪些` 路由、CRM 能力幻觉、零证据、待办与流程、多轮第二项、月份纠正、跨项目、过期 factRef、来源冲突、工具失败/超时、模型失败回退、重复调用停止和对抗性槽位误标。该集合验证内部契约，不代表本地 MySQL/Qdrant/真实模型效果；没有 100-300 条人工黄金集前不宣称正式召回率达标。
|