docs(agent): sync final implementation state

2026-07-25 00:03:19 +08:00
parent 9b39ffbb76
commit a67444645e
10 changed files with 157 additions and 105 deletions
@@ -1,6 +1,6 @@
 # 物业行业 AI 人力资源系统 · 开发规格(Tech Spec)

-> 版本:v1.9 ｜ 日期:2026-07-22
+> 版本:v2.0 ｜ 日期:2026-07-24
 > 定位:**开发层唯一依据**。回答"怎么建"——工程结构、数据表、API 契约、Prompt 规格、集成适配。
 > v1.1 变更:数据模型对齐《手册》卷1 第9章 HR 主干,补 3 张 backbone 表(职位职责/雇员绩效/雇用终止),新增附录 D 对照表。
 > v1.2 变更:第 6 章按 Codex 设计评审重写——状态机补异常/终止态、COACH_CHECK 工程化、评分引擎分层(P0 单 LLM / P1 融合)、澄清"单场对练评分 vs 跨期能力画像"两套评分、Prompt 加固 + RAG 硬约束、新增 6.5 P0/P1 切分。
@@ -11,6 +11,7 @@
 > v1.7 文档收口:明确当前“工作上报”是四类成果投稿审核链，工作助手负责日常事实采集；项目名称选择、项目化会话、来源追溯和今日工作成果仍属后续迭代，不能从规划文档推断已实现。详见[迭代计划](工作助手与今日工作成果迭代计划-20260721.md)。
 > 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 浏览器验证，尚未部署或完成正式账号/真机验收。
 > 配套:需求见[《物业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 用快照) / 数据范围以项目为主体。
@@ -25,7 +26,7 @@
 |---|---|
 | 后端 | Java + Spring Boot 4(若依 RuoYi 后端) |
 | 管理端前端 | Vue + plus-ui(若依前端,前后端分离) |
-| 移动端前端 | 独立 `mobile/` Vue/Vite Web/H5;小程序技术栈后续再定 |
+| 移动端前端 | `mobile-uni/` uni-app Vue3 H5 + App-Plus；旧 `mobile/` 只作 MVP 演示兜底 |
 | 数据库 | MySQL(主数据/事务)+ MinIO(原始文件)+ Qdrant(向量索引) |
 | 检索 | MySQL Fulltext + Qdrant 混合 RAG(一期);知识图谱 Neo4j(P2) |
 | 大模型 | 公有大模型 API(对话/出题/评分/案例整理) |
@@ -43,8 +44,10 @@ backend/
  script/sql/aihr_model_mysql8.sql
 frontend/
  src/views/{index,recruit,train,knowledge,system/model} # 管理端 MVP 页面
+mobile-uni/
+  src/pages/              # 员工端/候选人端/主管端当前页面
 mobile/
-  src/App.vue             # 员工端/候选人端/主管端 H5 首页
+  src/App.vue             # 旧 MVP 演示兜底
 ```

 - 复用若依 `ruoyi-system` 的用户/角色/菜单/数据权限;自有后端 API 集中在 `ruoyi-aihr`,不要塞回上游 `ruoyi-demo`。
@@ -68,6 +71,7 @@ mobile/
 | M8 治理/版本/审核 | 支撑 | P1 |
 | M9 AI 适配层 | 支撑 | P0 |
 | M10 管理驾驶舱/报表 | 分析 | P1 |
+| M11 数字师傅 Agent | 业务编排 | 本地已实现，待发布验收 |

 ---

@@ -164,6 +168,7 @@ mobile/
 | `content_version`(版本留痕) | id, target_type, target_id, version, diff, change_by | P1 |
 | `llm_call_log`(大模型调用/成本) | id, module, model, tokens_in, tokens_out, cost, latency_ms, created_at | P1(成本闸门G6) |
 | `asr_config`(语音配置) | id, vendor, dialect, endpoint, enabled | P0 |
+| `aihr_agent_run`(Agent 最小运行审计) | run_id, tenant_id, client_key, user_id, conversation_id, context_version, intent, tool, status, source_type, duration_ms, error_code, result_ref | 本地已落；不保存原始问题、答案、附件或模型推理 |

 ---

@@ -181,7 +186,7 @@ mobile/
 | `/h5/#/pages/user/today/index` | 员工端首页，手机号登录后可“开始训练”并同步主管待复盘计数；旧 `/h5/user` 兼容重定向 | P0跑通 |
 | `/h5/#/pages/candidate/index/index` | 候选人端首页，手机号登录后可面试练习、查岗位 SOP/案例、上传补充资料；旧 `/h5/candidate` 兼容重定向 | P0跑通 |
 | `/h5/#/pages/supervisor/index/index` | 主管端首页，查看团队、待复盘、案例/SOP 工具；旧 `/h5/supervisor` 兼容重定向 | P0跑通 |
-| `/h5/#/pages/user/sop/index` | 工作助手；按项目名称选择当前项目，语音/文字/照片/视频统一采集，确认后形成日常工作记录 | 2026-07-21 已部署；媒体生产真机回归未完成 |
+| `/h5/#/pages/user/sop/index` | 问·数字师傅 Agent；文字、语音、图片/视频自动路由知识、训练、待办、记忆、媒体或全网工具，项目按名称选择 | Agent 本地已实现，未部署；正式账号/真机验收未完成 |
 | `/h5/#/pages/user/work-results/index` | 员工工作成果；按员工、项目、自然日汇总确认记录和待跟进 | 2026-07-22 已发布历史日期选择与未来日期拒绝 |
 | `/h5/#/pages/supervisor/work-results/index` | 主管项目成果；按目标项目权限查看员工成果和高优问题 | 2026-07-22 已发布历史日期选择与手机号授权兜底 |
 | `/h5/#/pages/user/report/index` | 员工成果投稿；复用「问」的微信式语音会话，AI 整理确认后提交既有审核链 | 会话式页面和接口已部署；本地界面已正式改名；项目归属和媒体内容理解未实现 |
@@ -347,6 +352,21 @@ POST /api/ai/score       req:{ rubricId, dialogue }        resp:{ dimensions, co
 - 混合检索:`POST /api/knowledge/search` 先查 MySQL Fulltext，同时在 vector 模型和 Qdrant 可用时生成 query embedding 走 Qdrant，最后按 RRF 融合并回 MySQL hydrate 片段；Qdrant 不存正文事实源。
 - Rubric 配置:`/api/competency/rubric/**` CRUD

+### 5.6 数字师傅 Agent
+
+```text
+POST /api/aihr/agent/messages
+POST /api/aihr/agent/messages/media
+POST /api/aihr/agent/actions/{draftId}/confirm
+POST /api/aihr/agent/actions/{draftId}/dismiss
+```
+
+- 文字请求只接受 `question`、短会话版本、当前项目、大喇叭消息引用和明确的外发同意；`question` 去空白后必填且不超过 1000 字。multipart 请求只增加当次附件，不接受客户端身份、角色、工具名、知识空间 ID 或任意 URL。
+- Planner 只输出已知 `intent/tool`；服务端固定策略按认证主体与角色授权，领域工具再次校验项目、会话和资源。寒暄/澄清不调用 RAG；普通图片只做当次媒体分析，明确制度/流程问题才补充授权知识。
+- 响应状态限定为 `COMPLETED/NEEDS_INPUT/NEEDS_CONFIRMATION/NO_EVIDENCE/FORBIDDEN/UNAVAILABLE/FAILED`，并分别返回来源、引用、资源、数据、动作草稿或澄清字段；客户端不得从回答文本猜按钮或业务状态。
+- 全网工具必须先取得用户本次明确同意；写入只通过 30 分钟有效的 `draftId` 确认/忽略，并复用领域服务的 `expectedVersion + idempotencyKey + saveScope`。`aihr_agent_run` 只记录最小路由元数据。
+- 旧 `/api/knowledge/query`、`query-media` 和 `/api/aihr/web-ai/**` 保留为底层/兼容接口。完整请求示例、错误码和当前发布边界见 [API_INTEGRATION.md](API_INTEGRATION.md)。
+
 ---

 ## 6. 核心自建组件规格(无框架可复用,最关键)