docs(agent): define digital master orchestration

docs/superpowers/specs/2026-07-24-digital-master-agent-design.md

@@ -0,0 +1,318 @@
+# 数字师傅工作 Agent 总体设计
+
+> 状态：待评审
+>
+> 日期：2026-07-24
+>
+> 适用入口：员工端、主管端、候选人端的“问”能力；管理端只允许受限运营预览，不可代替移动用户身份。
+>
+> 本设计定义产品最终形态，不代表已经实现、发布或通过阶段一正式试点验收。
+
+## 1. 结论
+
+“问”不再定义为 SOP 检索页，而是银城员工端的 **数字师傅工作 Agent**。
+
+它接收文字、语音、图片和视频，先理解用户意图、当前身份、项目和对话状态，再选择受控工具完成一件事：回答有依据的制度问题、读取实时业务事实、形成待确认的工作记录、交付文件/视频、分析现场图片、或在用户同意后转向全网。RAG 是其中一个工具，不能再作为所有消息的默认出口。
+
+Agent 不拥有任意数据库、任意 HTTP 或任意写入权限；它只可调用服务端注册、参数校验、身份授权、幂等和审计均已具备的业务工具。写操作必须先形成可编辑的确认卡，再由用户显式确认执行。
+
+## 2. 要解决的问题
+
+当前能力已有会话改写、`QA/FILE/VIDEO/DATA_TOOL`、受控训练数据工具、确认式记忆、媒体识别和独立全网 AI，但普通 `QA` 会统一进入知识检索。因此以下消息的体验都不正确：
+
+| 用户表达 | 正确处理 | 当前错误倾向 |
+|---|---|---|
+| “我今天有什么待办？” | 读取当前登录员工的真实待办 | 当作 SOP 检索 |
+| “记一下，3 栋 1201 要回访” | 生成可编辑确认卡 | 先检索知识库，再后置猜测 |
+| “图中是什么宠物？” | 图片理解；必要时征得同意转全网 | 以图片关键词检索 SOP |
+| “这台电梯门打不开怎么处理？” | 图片线索 + 已授权 SOP 联合处理 | 仅作文本搜索或无依据兜底 |
+| “把刚才的原文件发我” | 利用会话指代，交付仍被授权的附件 | 普通问答或不相关资料 |
+| “给主管发一份待复盘名单” | 形成范围、内容、接收人都明确的动作草稿 | 模型口头承诺“已发送” |
+
+## 3. 设计原则
+
+1. **先授权，再理解，再调用。** 租户、应用、移动端身份、角色、项目范围和媒体大小在模型调用前由服务端固定；模型不能选择或扩张这些边界。
+2. **计划可验证，工具不可越权。** 模型只产生受严格 JSON Schema 校验的计划；执行器只接受注册工具和结构化参数。
+3. **事实与建议分开。** 实时任务、训练、成绩、项目数据必须来自领域工具；制度结论必须带知识引用；模型建议不得伪装为已分配任务或已执行动作。
+4. **读可自动，写必确认。** 读取权限范围内的资料或数据可直接执行；创建记录、提交成果、指派训练、通知主管等操作先生成草稿，确认后才调用领域写接口。
+5. **会话是短期工作上下文，不是事实库。** 会话仅保留 30 分钟、最近 6 轮；可复用的个人或项目事实通过现有确认式记忆保存；任务和组织状态每次从业务系统重新读取。
+6. **多模态先变成受控上下文。** 图片/视频只在本次会话按授权处理；视觉结论必须说明为“图片识别”，不能自动入共享知识库，也不能替代 SOP 依据。
+7. **失败要保守且可理解。** 无权限、无资料、数据不可用、模型不可用、需要补充信息、等待确认分别返回不同状态，绝不降级成编造答案。
+
+## 4. 产品边界和角色
+
+### 4.1 统一 Agent，分角色工具集
+
+底层只建设一个 `Agent Orchestrator`，但根据当前可信主体装配不同工具集：
+
+| 主体 | 可读能力 | 可确认的动作 | 明确禁止 |
+|---|---|---|---|
+| 员工 | 本人待办、训练、成长、工作成果、本人/项目确认记录、授权知识 | 保存私人或项目记录、提交已有流程支持的成果草稿 | 查询团队或他人数据、代替主管指派、伪造工作单 |
+| 主管/项目经理 | 本人及可信项目范围内团队训练、待复盘、已授权运营资料 | 创建已有契约支持的训练指派/复盘草稿 | 跨项目读取或写入、以手机号猜测团队身份 |
+| 候选人 | 本人面试进度、资料状态、岗前学习资料 | 提交本人资料草稿 | 访问员工、主管、项目或内部运营数据 |
+| 管理端运营人员 | 固定 `operator:{userId}` 的内容与工具预览 | 管理端既有运营契约内的动作 | 冒充移动员工/主管、写入其历史或试点统计 |
+
+项目、人员和主管范围仍只由服务端的认证手机号、组织快照外部 ID 和既有唯一映射规则确定。Agent 不新增任何客户端可传的身份字段。
+
+### 4.2 不在 Agent 内承担的职责
+
+- 不执行任意 SQL、任意 URL、任意数据库更新或模型自选工具。
+- 不把“建议联系主管”“建议创建工单”描述成已经通知、建单或派单。
+- 不替代训练、考试、候选人资料、成果投稿等领域模块的审核和状态机。
+- 不把外网答案混入企业知识、个人记忆或正式业务记录。
+- 不扩张当前阶段一的正式试点验收范围。
+
+## 5. 总体架构
+
+```mermaid
+flowchart TD
+    A["文字 / 语音 / 图片 / 视频"] --> B["可信请求上下文\n身份、项目、应用、会话、附件"]
+    B --> C["Agent Planner\n意图、实体、缺失字段、工具计划、风险"]
+    C --> P["Policy Gate\n权限、工具白名单、确认要求、外发同意"]
+    P -->|"需要补充"| Q["澄清卡"]
+    P -->|"只读"| T["Tool Executor"]
+    P -->|"写操作"| D["Action Draft / 确认卡"]
+    D -->|"确认 + 幂等键"| T
+    T --> K["知识 RAG"]
+    T --> R["实时领域工具"]
+    T --> M["确认式记忆"]
+    T --> W["全网 AI / 视觉"]
+    K --> O["Evidence Composer\n答案、来源、动作结果、下一步"]
+    R --> O
+    M --> O
+    W --> O
+    O --> L["会话、审计、可观测性"]
+```
+
+### 5.1 服务组件
+
+| 组件 | 职责 | 复用或新增 |
+|---|---|---|
+| `AihrAgentOrchestrator` | 唯一编排入口：组装上下文、调用 Planner、过 Policy、执行工具、生成响应 | 新增 |
+| `AihrAgentPlanner` | 输出结构化意图和工具计划；模型不可用时使用保守规则 | 新增，替代会话服务中仅查询改写的职责 |
+| `AihrAgentPolicy` | 校验角色、项目、工具参数、外发同意、确认要求和最大调用数 | 新增 |
+| `AihrAgentToolRegistry` | 注册工具元数据、输入/输出 schema、读写风险和权限谓词 | 新增 |
+| 领域工具适配器 | 将 Agent 计划映射到已有训练、工作成果、记忆、知识、全网等服务 | 新增薄适配层；不复制领域逻辑 |
+| `AihrKnowledgeQueryService` | 被 `KNOWLEDGE_SEARCH/FILE/VIDEO` 工具调用，继续负责空间授权、RAG、引用和受保护资源 | 复用 |
+| `AihrKnowledgeDataToolService` | 被训练/待办读取工具调用，继续做 APP 身份和主管范围校验 | 复用并按领域扩充 |
+| `AihrMemoryService` | 被记录草稿工具调用，继续生成、确认和落库确认式记忆 | 复用 |
+| `AihrWebAiService` | 仅在用户已同意外发时调用；保持独立来源与限流 | 复用 |
+
+## 6. 意图模型和工具计划
+
+### 6.1 标准意图
+
+`intent` 不是 UI 标签，而是执行策略。每个请求必须属于以下之一：
+
+| 意图 | 典型表达 | 默认工具 | 是否自动执行 |
+|---|---|---|---|
+| `KNOWLEDGE_QA` | “装修人员怎么进场？” | 企业知识检索 | 是 |
+| `RESOURCE_DELIVERY` | “把刚才 SOP 原文给我” | 知识检索 + 受保护文件/视频交付 | 是 |
+| `LIVE_MY_WORK` | “我今天有什么待办？” | 当前待办、工作成果、训练读取工具 | 是 |
+| `LIVE_TEAM_WORK` | “谁还没复盘？” | 主管范围团队工具 | 是，权限不足即拒绝 |
+| `PRACTICE_COACHING` | “我这次练得怎么样？” | 本人训练/画像/错题工具，可补充 SOP | 是 |
+| `CAPTURE_FACT` | “记一下 1201 要回访” | 记忆候选草稿 | 仅生成确认卡 |
+| `DRAFT_ACTION` | “给主管发待复盘名单” | 动作草稿工具 | 仅生成确认卡 |
+| `MEDIA_UNDERSTANDING` | “图上漏水点在哪？” | 当前附件视觉/视频上下文；必要时接 SOP | 是 |
+| `WEB_RESEARCH` | “这是什么宠物？”“查一下国家规定” | 全网 AI | 需要一次有效的外发同意 |
+| `CLARIFY` | “帮我处理一下” | 无 | 返回最小必要澄清 |
+| `SOCIAL` | 寒暄、能力询问 | 无 | 简短回应，不检索 |
+
+`KNOWLEDGE_QA` 不能作为识别失败后的通用垃圾桶：当没有明确工作问题、知识诉求或文档指代时，应当选择 `CLARIFY`、`SOCIAL` 或明确的领域意图。
+
+### 6.2 Planner 输出契约
+
+Planner 只能返回以下受校验 JSON。服务端忽略任何未知字段和工具名：
+
+```json
+{
+  "intent": "LIVE_MY_WORK",
+  "rewrittenRequest": "查询当前认证员工的待办与训练任务",
+  "entities": {"timeRange": "today"},
+  "toolCalls": [
+    {"tool": "MY_CURRENT_TASKS", "arguments": {}}
+  ],
+  "missingFields": [],
+  "requiresConfirmation": false,
+  "requiresExternalConsent": false,
+  "responseStyle": "FACT"
+}
+```
+
+规则：
+
+1. 每次最多一个只读工具或一个“草稿生成工具”；需要组合时仅允许预定义组合，例如“图片理解 + SOP 检索”。
+2. `toolCalls` 只能是本次主体、项目、应用和附件形态允许的工具。
+3. Planner 可提取“今天”“本项目”“刚才那份”等语义，但不能输出员工 ID、项目编码、知识空间 ID、收件人 ID 等权限主体；这些值必须由工具侧再解析。
+4. Planner 失败时用确定性规则路由 `RESOURCE_DELIVERY`、`LIVE_MY_WORK`、`CAPTURE_FACT`、`WEB_RESEARCH`；其余返回 `CLARIFY`，而不是自动 RAG。
+
+## 7. 工具注册表
+
+最终工具集合按“工具名—服务端能力—授权—写入”登记。以下表中的“现有”表示已有领域接口或服务可复用，不表示客户端可绕过 Agent 直接扩大权限。
+
+| 工具 | 类型 | 当前能力来源 | 授权与输出约束 |
+|---|---|---|---|
+| `KNOWLEDGE_SEARCH` | 读 | `AihrKnowledgeQueryService` | 当前有效知识空间交集；必须返回引用或 `noEvidence` |
+| `KNOWLEDGE_RESOURCE` | 读 | 现有 FILE/VIDEO 与资源下载接口 | 当前命中且下载时再次授权；不暴露 OSS URL |
+| `MY_CURRENT_TASKS` | 读 | `AihrKnowledgeDataToolService` | 认证 APP 员工本人；无任务要明确返回无任务 |
+| `MY_PRACTICE_SUMMARY` | 读 | 既有训练历史服务 | 仅认证员工本人 |
+| `TEAM_PRACTICE_SUMMARY` | 读 | 既有主管团队服务 | 仅主管且仅可信项目范围 |
+| `MY_WORK_RESULTS` | 读 | 既有工作成果服务 | 员工 + 项目 + 自然日；禁止未来日期 |
+| `TEAM_WORK_RESULTS` | 读 | 既有主管工作成果服务 | 主管项目范围 |
+| `CAPTURE_MEMORY_DRAFT` | 草稿 | `AihrMemoryService` | 只能形成 `DRAFT/NEEDS_INPUT`，由用户选择 PRIVATE/COMPANY 后确认 |
+| `PRACTICE_ASSIGNMENT_DRAFT` | 草稿 | 既有训练指派领域契约 | 仅主管范围；确认前不创建任务 |
+| `REVIEW_DRAFT` | 草稿 | 既有复盘领域契约 | 仅主管范围；确认前不改变复盘状态 |
+| `WORK_REPORT_DRAFT` | 草稿 | 成果投稿领域契约 | 只覆盖 CASE/VIDEO/SOP/KNOWLEDGE，不与日常记忆互写 |
+| `MEDIA_ANALYZE` | 读 | 现有 vision/ASR/media 提取 | 当次附件、大小限制、临时上下文；不自动入库 |
+| `WEB_RESEARCH` | 读/外发 | `AihrWebAiService` | 独立来源、用户同意、HTTPS 提供方、现有限流；不写企业知识 |
+
+每个工具必须声明：`risk=READ|DRAFT|WRITE`、允许角色、项目范围谓词、输入 schema、最大返回大小、是否可带附件、幂等要求、审计事件类型。任何未登记工具一律拒绝。
+
+## 8. 确认式动作和真实状态
+
+### 8.1 动作状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> DRAFT
+    DRAFT --> NEEDS_INPUT: 缺少项目、对象或内容
+    NEEDS_INPUT --> DRAFT: 用户补齐
+    DRAFT --> CONFIRMED: 用户确认且携带幂等键
+    CONFIRMED --> EXECUTED: 领域接口成功
+    CONFIRMED --> FAILED: 领域接口失败
+    DRAFT --> DISMISSED: 用户取消或过期
+    FAILED --> DRAFT: 用户修订后重试
+```
+
+确认卡必须显示“将要做什么、作用范围、目标对象、字段、来源、是否可撤销”。例如“给主管发待复盘名单”在确认前只能展示草稿，不得显示“已发送”。确认请求要包含 `expectedVersion + idempotencyKey`；领域服务负责最终状态机与幂等，Agent 只编排。
+
+### 8.2 事实来源优先级
+
+1. 领域工具的实时返回值：任务、训练、复盘、工作成果、候选进度。
+2. 已授权且引用明确的企业知识。
+3. 已确认的个人/项目记录。
+4. 当前附件的视觉/语音识别结果。
+5. 经用户同意取得的全网资料。
+6. 模型建议只能作为建议，不能写成事实、状态或执行回执。
+
+不同来源不得相互覆盖：企业 SOP 不会产生个人待办；确认式记忆不自动变成成果投稿或工单；图片识别不成为企业知识；全网资料不进入内部制度答案。
+
+## 9. 会话、记忆和多模态上下文
+
+### 9.1 三层状态
+
+| 层 | 数据 | 保留与用途 | 规则 |
+|---|---|---|---|
+| 短期会话 | 最近 6 轮、30 分钟 | 指代消解、当前图片/任务讨论连续性 | 保持现有租户 + app + user + project 隔离和版本冲突控制 |
+| 确认式记忆 | 已确认个人或项目事实 | 后续检索和个人助理 | 必须显式确认；COMPANY 仅为 PENDING，不冒充已送达 |
+| 实时业务事实 | 任务、训练、成果、组织、候选进度 | 当前状态和动作前置校验 | 不写入会话作为真相；每次工具调用重新读取 |
+
+### 9.2 图片和视频
+
+附件先经过 `MEDIA_ANALYZE` 生成带来源标签的临时事实，例如“图片识别：电梯门无法打开”。Agent 再决定：
+
+- 现场工作问题：将临时事实与当前身份可访问的 SOP 联合检索；无 SOP 时回显图片理解，并明确缺少制度依据。
+- 泛视觉问题：直接回答识别结果；需要外部信息时提示并取得全网外发同意。
+- 后续追问：临时事实随短期会话保存，直到会话过期或新对话；原图、原视频不写入共享知识库。
+
+## 10. API 和响应模型
+
+### 10.1 规范入口
+
+内部移动端规范入口为：
+
+```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
+```
+
+请求继续由登录态、`clientid`、当前项目选择、`conversationId/contextVersion` 约束；不接受客户端身份、角色、项目编码替代物或工具名。旧 `/api/knowledge/query`、`query-media`、`/api/aihr/web-ai/**` 保留为兼容或底层能力，但移动端“问”统一改调 Agent 入口。
+
+### 10.2 统一响应
+
+```json
+{
+  "runId": "agent_run_xxx",
+  "conversationId": "conversation_xxx",
+  "contextVersion": 4,
+  "intent": "LIVE_MY_WORK",
+  "status": "COMPLETED",
+  "answer": "当前没有查到分配给你的待办或训练任务。",
+  "sourceSummary": [
+    {"type": "LIVE_DATA", "label": "我的当前待办", "verifiedAt": "2026-07-24T14:00:00+08:00"}
+  ],
+  "citations": [],
+  "resources": [],
+  "data": {"state": "NO_TASKS", "taskCount": 0},
+  "actionDraft": null,
+  "clarification": null,
+  "nextActions": ["查看学习中心", "联系主管确认安排"]
+}
+```
+
+`status` 只能是 `COMPLETED/NEEDS_INPUT/NEEDS_CONFIRMATION/NO_EVIDENCE/FORBIDDEN/UNAVAILABLE/FAILED`。前端据此渲染答案、澄清卡、确认卡或受保护资源卡，不解析模型自由文本来决定按钮和业务状态。
+
+## 11. 移动端交互
+
+1. 将“问”首页改为一个统一入口“问数字师傅”；不要求用户先判断该选“工作助手”还是“查全网”。
+2. 输入框接受文字、录音、图片、视频；附件选择后显示“仅本次分析”，并在发出前显示是否可能外发。
+3. 回复顶部展示精简来源条：`已查内部 SOP`、`已读取我的待办`、`图片识别`、`需全网授权`、`待你确认`。
+4. `NEEDS_INPUT` 使用不超过三个字段的澄清卡，优先从当前可选项目、日期和已授权对象中选择，不让用户输入内部编码。
+5. `NEEDS_CONFIRMATION` 显示结构化草稿及“确认/修改/取消”；完成后显示领域系统返回的真实编号、时间和状态。
+6. RAG 结果保留引用、原文件/视频卡和总结卡；全网结果保持独立免责声明与来源，不能与企业引用混排。
+7. 主管和候选人复用同一交互组件，但只展示其工具注册表允许的快捷入口和结果卡。
+
+## 12. 审计、模型评价和运营
+
+### 12.1 审计对象
+
+新增 `aihr_agent_run` 与 `aihr_agent_action_draft`，记录最小必要信息：
+
+- `runId`、tenant/app/user、项目范围快照、会话版本；
+- 识别意图、执行工具、策略结果、来源类别、耗时、脱敏错误码；
+- 动作草稿版本、确认人、幂等键哈希、领域回执 ID 和最终状态。
+
+不得在审计表保存原始密钥、完整敏感提示词、未脱敏聊天正文、原始 OSS URL 或模型隐藏推理。
+
+### 12.2 质量指标
+
+每个 Agent run 应可统计：意图准确率、工具选择准确率、澄清率、无依据率、确认转化率、确认后执行成功率、越权拒绝率、模型/工具失败率和用户反馈。用于评估的样本必须按租户、角色、项目和媒体类型分层，且敏感内容脱敏后才可出运营报表。
+
+## 13. 安全与降级
+
+- Policy Gate 在任何模型调用和工具调用前执行；工具内部仍需重复做授权，不能信任 Planner 结果。
+- 模型输出不能直接触发写操作、通知、下载、外发、身份切换或项目选择。
+- 全网、图片外发必须使用现有 HTTPS 提供方白名单、连接测试、大小限制、限流和用户同意。
+- 解析失败、模型关闭或 JSON 不合法时：优先规则路由已知只读/确认式意图；无法可靠判定则返回澄清，不回退到全量 RAG。
+- RAG 无依据返回 `NO_EVIDENCE`；数据工具不可用返回 `UNAVAILABLE`；权限不足返回 `FORBIDDEN`；三者不能混为同一提示。
+- 公司消息上下文继续只允许服务端按 `broadcastMessageId` 重新加载；不接受附件、数据工具或客户端正文注入。
+
+## 14. 验收标准
+
+### 14.1 行为
+
+1. “我今天有什么待办”只调用 `MY_CURRENT_TASKS`，不调用知识检索；无任务明确显示真实 `NO_TASKS`。
+2. “记一下 3 栋 1201 要回访”只生成确认卡；确认前不创建捕获记录，确认后只按用户选择的 PRIVATE/COMPANY 落库。
+3. “图中是什么宠物”不检索 SOP；显示图片识别来源。如需外网则在同意后才调用全网能力。
+4. “图中电梯门打不开怎么办”先显示图片线索，再基于授权 SOP 回答；没有命中时不捏造流程。
+5. “把刚才的原文件给我”在同一会话内交付当前授权附件；权限撤销后旧资源仍拒绝。
+6. “给主管发待复盘名单”仅产生草稿；确认后才调用可用领域接口，并回显真实结果。
+7. 普通寒暄和不完整表达不触发 RAG，不产生无依据知识缺口。
+
+### 14.2 安全与回归
+
+1. 员工、主管、候选人和管理端预览的工具集合、项目范围和身份映射均有正反例测试。
+2. Planner 伪造工具、项目、员工、收件人、SQL、URL 或确认结果时全部由 Policy Gate 拒绝。
+3. 动作确认重复提交不重复写入；过期草稿和旧版本确认被拒绝。
+4. 外网、媒体、知识、实时数据和确认式记忆的来源标签、保存边界和审计均可验证。
+5. 文字、语音、图片、视频、会话过期、并发冲突、模型失效、工具失效、无权限和撤销授权都有自动化合同测试及真实移动端交互验收。
+
+## 15. 迁移约束
+
+- 不删除现有知识空间授权、会话、资源下载、媒体分析、全网 AI、确认式记忆或领域服务；Agent 只作为统一编排层接入。
+- `AihrKnowledgeQueryService` 不再承担通用意图总线，只保留知识、文件和视频检索职责。
+- 现有移动端 `conversationId/contextVersion` 和确认卡可以复用；新响应通过 `status/sourceSummary/actionDraft/clarification` 扩展，旧客户端可继续使用旧查询入口。
+- 数据库结构必须走正式 SQL 迁移；生产请求路径不执行 DDL。
+- 发布及验收必须区分：代码实现、自动化、H5/真机交互、部署、真实账号业务流和正式试点证据。