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

数字师傅工作 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. 总体架构

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。服务端忽略任何未知字段和工具名：

{
  "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 动作状态机

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 规范入口

内部移动端规范入口为：

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 统一响应

{
  "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/真机交互、部署、真实账号业务流和正式试点证据。