feat(aihr): add grounded agent shadow runtime
This commit is contained in:
key
@@ -0,0 +1,84 @@
|
||||
# 帮道受约束业务 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 条人工黄金集前不宣称正式召回率达标。
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
本文维护当前前后端业务接口和安全边界；旧演示流继续保留降级链，但不能作为生产或试点通过证据。
|
||||
|
||||
> 2026-08-04 本地新增的 Grounded Agent 仍是影子运行时，尚未接入本页 `/api/aihr/agent/**` 现役入口，也没有改变客户端响应契约。其内部 DTO、双工具、证据门禁和结构化会话状态见 [AIHR_GROUNDED_AGENT_TECHSPEC.md](AIHR_GROUNDED_AGENT_TECHSPEC.md)；生产行为仍以本页现役接口说明为准。
|
||||
|
||||
## 第一阶段范围
|
||||
|
||||
| 页面 | 后端接口 | 处理 |
|
||||
|
||||
+3
-1
@@ -11,7 +11,7 @@
|
||||
3. 专项 TechSpec 细化单个领域；实施计划可记录本地实现与验证，但部署和生产状态仍以审查文档、接口事实和真实环境证据为准。
|
||||
4. `prototypes/` 只作视觉回归基准；会议纪要、历史 Prompt、`legacy/` 与 `archive/` 只作需求来源和追溯材料。
|
||||
|
||||
“问”模块的最终 Agent 边界见[《数字师傅工作 Agent 总体设计》](superpowers/specs/2026-07-24-digital-master-agent-design.md)，实施与验证进度见[《实施计划》](superpowers/plans/2026-07-24-digital-master-agent.md)；工作助手相关术语、实施状态与文档关系集中在[《工作助手与今日工作成果迭代计划》](工作助手与今日工作成果迭代计划-20260721.md)。阶段一“练”的唯一后续施工范围见[《AI陪练完整交付计划》](AI陪练完整交付计划-20260724.md)，公司消息现状见[九项能力设计](superpowers/specs/2026-07-24-company-message-nine-capabilities-design.md)与[大喇叭纠偏增量方案](银城大喇叭与问模块纠偏增量方案-20260722.md)。不得把已部署但尚未完成 Agent 专项生产回归的包存在性，或已验证的全员文件消息和直通车闭环，外推为 Agent 正式验收、消息修订、强触达、工单流转、完整个人知识空间或完整试点已经完成。
|
||||
“问”模块的产品边界见[《数字师傅工作 Agent 总体设计》](superpowers/specs/2026-07-24-digital-master-agent-design.md)，现役旧链路的实施与验证进度见[《实施计划》](superpowers/plans/2026-07-24-digital-master-agent.md)；2026-08-04 本地新增、尚未切流的 Grounded Agent 架构以[专项 TechSpec](AIHR_GROUNDED_AGENT_TECHSPEC.md)和[ADR-002](adr/ADR-002-GROUNDED-AGENT-EXECUTION.md)为准。工作助手相关术语、实施状态与文档关系集中在[《工作助手与今日工作成果迭代计划》](工作助手与今日工作成果迭代计划-20260721.md)。阶段一“练”的唯一后续施工范围见[《AI陪练完整交付计划》](AI陪练完整交付计划-20260724.md)，公司消息现状见[九项能力设计](superpowers/specs/2026-07-24-company-message-nine-capabilities-design.md)与[大喇叭纠偏增量方案](银城大喇叭与问模块纠偏增量方案-20260722.md)。不得把本地影子实现、已部署但尚未完成 Agent 专项生产回归的包存在性，或已验证的全员文件消息和直通车闭环，外推为 Agent 正式验收、消息修订、强触达、工单流转、完整个人知识空间或完整试点已经完成。
|
||||
|
||||
## 当前项目文档
|
||||
|
||||
@@ -32,6 +32,8 @@
|
||||
| [FIGMA需求覆盖与版本偏差审计-20260717.md](FIGMA需求覆盖与版本偏差审计-20260717.md) | 旧版功能、已确认需求、Figma 实际画板与当前实现的四方对照，以及防止遗漏旧功能和误拉后续阶段的事实源规则 |
|
||||
| [DEMO_ACCEPTANCE.md](DEMO_ACCEPTANCE.md) | 一期 MVP 演示脚本、录屏兜底、MVP 演示流验收清单 |
|
||||
| [API_INTEGRATION.md](API_INTEGRATION.md) | 后端 API 对接顺序、数字师傅 Agent、正式试点 CSV、移动端训练/复盘、候选资料和 SOP 接口 |
|
||||
| [AIHR_GROUNDED_AGENT_TECHSPEC.md](AIHR_GROUNDED_AGENT_TECHSPEC.md) | 受约束语义规划、双工具、证据/事实分型、有界执行、逐结论引用和结构化会话状态的本地影子契约；尚未切换现役 API |
|
||||
| [adr/ADR-002-GROUNDED-AGENT-EXECUTION.md](adr/ADR-002-GROUNDED-AGENT-EXECUTION.md) | 采用 Spring 内受约束工具执行、证据分型和 fail-closed 门禁，不引入自由 Agent 框架的架构决策 |
|
||||
| [DIGITAL_ASSET_PROCESSING_GOVERNANCE.md](DIGITAL_ASSET_PROCESSING_GOVERNANCE.md) | 企业数字资产从原始保存、规范化、结构化、质量门禁、人工审核到发布、撤回和规则自动化演进的总体方案 |
|
||||
| [data-quality-audit.md](data-quality-audit.md) | 数据质量、脏数据治理、信任边界、数据血缘与当前本地实施证据的只读审计基线 |
|
||||
| [superpowers/specs/2026-07-24-digital-master-agent-design.md](superpowers/specs/2026-07-24-digital-master-agent-design.md) | “问”模块最终 Agent 产品/架构边界，以及当前已实现与后续工具范围 |
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# 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 治理和审计。
|
||||
- 金额候选/送模/复核成为确定性校验器的第一条纵向切片。
|
||||
- 旧路径在影子验证期间继续承担兼容回退。
|
||||
- 工具必须声明 schema、授权、时效、幂等、审计和允许意图。
|
||||
- `PARTIAL` 只能输出已覆盖 claim slots；零合格证据不调用答案模型。
|
||||
- 客户端最终按 `DecisionStatus` 展示完整、部分、需补充、无依据和冲突状态。
|
||||
@@ -12,6 +12,7 @@
|
||||
> v1.8 发布前本地实施快照:项目名称选择、项目化会话、确认记录来源/状态、员工今日成果、主管项目成果和“成果投稿”界面名称已完成本地实现与 390×844 验证；该快照记录的是发布前状态，外部线索、工单和考勤投递仍保持 PENDING。
|
||||
> v1.9 发布与本轮回填: v1.8 所列多项目、项目化确认采集、来源/状态、员工今日成果、主管项目成果和“成果投稿”界面名称已于 2026-07-21 部署。成果历史日期选择、服务端拒绝未来日期及主管手机号授权兜底已于 2026-07-22 发布，并完成远端服务、schema 与产物匹配复核；外部线索、工单和考勤投递仍保持 PENDING。
|
||||
> v2.0 实施快照：“问”改由 `/api/aihr/agent/**` 统一规划意图并执行受控工具，知识 RAG 退回底层能力；新增 `aihr_agent_run` 最小路由审计。该增量已完成自动化、H5 构建和部分 390×844 浏览器验证，并随 2026-07-25 完整包部署；移动身份失败关闭语义又包含在 2026-07-29 定向发布的生产后端中。正式账号完整业务和真机验收仍未完成。
|
||||
> v2.1 本地影子增量：2026-08-04 新增 Grounded Agent 核心契约、`MY_CURRENT_TASKS + KNOWLEDGE_SEARCH` 双工具、证据/事实分型、有界执行、逐结论引用和结构化会话状态；现役 `/api/aihr/agent/**` 仍由 v2.0 路径处理，本增量未切流、未部署。详细契约见 [AIHR_GROUNDED_AGENT_TECHSPEC.md](AIHR_GROUNDED_AGENT_TECHSPEC.md)。
|
||||
> 配套:需求见[《物业AI人力资源系统业务需求文档BRD》](物业AI人力资源系统业务需求文档BRD.md);2026-07 MVP 执行计划已归档到[《AI人力资源系统一期MVP版作战清单》](archive/2026-07-mvp-delivery/AI人力资源系统一期MVP版作战清单.md)。
|
||||
> **优先级图例**:`P0`=2026-07-05 MVP 演示必需 · `P1`=一期必需 · `P2`=二期/推迟。
|
||||
> 决策基线:若依基座 / 集中式前后端分离 / 本地登录 / 公有大模型API / 一期RAG / 组织人员外部同步(MVP 用快照) / 数据范围以项目为主体。
|
||||
@@ -71,7 +72,7 @@ mobile/
|
||||
| M8 治理/版本/审核 | 支撑 | P1 |
|
||||
| M9 AI 适配层 | 支撑 | P0 |
|
||||
| M10 管理驾驶舱/报表 | 分析 | P1 |
|
||||
| M11 数字师傅 Agent | 业务编排 | 本地已实现，待发布验收 |
|
||||
| M11 数字师傅 Agent | 业务编排 | v2.0 现役；v2.1 Grounded 运行时仅本地影子验证，未切流 |
|
||||
|
||||
---
|
||||
|
||||
@@ -367,6 +368,8 @@ POST /api/aihr/agent/actions/{draftId}/dismiss
|
||||
- 全网工具必须先取得用户本次明确同意；写入只通过 30 分钟有效的 `draftId` 确认/忽略，并复用领域服务的 `expectedVersion + idempotencyKey + saveScope`。`aihr_agent_run` 只记录最小路由元数据。
|
||||
- 旧 `/api/knowledge/query`、`query-media` 和 `/api/aihr/web-ai/**` 保留为底层/兼容接口。完整请求示例、错误码和当前发布边界见 [API_INTEGRATION.md](API_INTEGRATION.md)。
|
||||
|
||||
2026-08-04 的 Grounded Agent 增量不改变以上 HTTP 契约：新 `SemanticQueryPlan`、Tool Registry、Evidence Evaluator、DecisionResult 和 Grounded Composer 目前只在内部测试链路串联。只有完成真实模型/授权知识库回归、客户端状态契约和独立发布验收后，才能逐步接管 v2.0 Orchestrator；不得从源码存在推断已切流。
|
||||
|
||||
---
|
||||
|
||||
## 6. 核心自建组件规格(无框架可复用,最关键)
|
||||
|
||||
Reference in New Issue
Block a user