# 数字师傅工作 Agent 总体设计

> 状态：已确认（2026-07-24）
>
> 日期：2026-07-24
>
> 适用入口：员工端、主管端、候选人端的“问”能力；管理端只允许受限运营预览，不可代替移动用户身份。
>
> 本设计定义产品最终形态。当前已实现员工“问”的文字/媒体编排、知识与资源、本人待办/训练、主管训练概况、确认式记忆、全网同意、结构化响应和最小运行审计；主管/候选人统一入口及工作成果、指派、复盘、成果投稿等草稿工具仍是后续范围。Agent 增量已随 2026-07-25 完整包部署，移动身份失败关闭语义又包含在 2026-07-29 定向发布的生产后端中；正式账号完整业务、真机和阶段一试点仍未验收。

## 1. 结论

“问”不再定义为 SOP 检索页，而是银城员工端的 **数字师傅工作 Agent**。

它接收文字、语音、图片和视频，先理解用户意图、当前身份、项目和对话状态，再选择受控工具完成一件事：回答有依据的制度问题、读取实时业务事实、形成待确认的工作记录、交付文件/视频、分析现场图片、或在用户同意后转向全网。RAG 是其中一个工具，不能再作为所有消息的默认出口。

Agent 不拥有任意数据库、任意 HTTP 或任意写入权限；它只可调用服务端注册、参数校验、身份授权、幂等和审计均已具备的业务工具。写操作必须先形成可编辑的确认卡，再由用户显式确认执行。

## 2. 要解决的问题

升级前已有会话改写、`QA/FILE/VIDEO/DATA_TOOL`、受控训练数据工具、确认式记忆、媒体识别和独立全网 AI，但普通 `QA` 会统一进入知识检索；本地 Agent 增量正是为纠正以下路由：

| 用户表达 | 正确处理 | 升级前错误倾向 |
|---|---|---|
| “我今天有什么待办？” | 读取当前登录员工的真实待办 | 当作 SOP 检索 |
| “记一下，3 栋 1201 要回访” | 生成可编辑确认卡 | 先检索知识库，再后置猜测 |
| “图中是什么宠物？” | 图片理解；必要时征得同意转全网 | 以图片关键词检索 SOP |
| “这台电梯门打不开怎么处理？” | 图片线索 + 已授权 SOP 联合处理 | 仅作文本搜索或无依据兜底 |
| “把刚才的原文件发我” | 利用会话指代，交付仍被授权的附件 | 普通问答或不相关资料 |
| “给主管发一份待复盘名单” | 形成范围、内容、接收人都明确的动作草稿 | 模型口头承诺“已发送” |

## 3. 设计原则

1. **可信上下文不可由模型决定。** 登录态、租户和应用由服务端固定；请求长度和附件先做基础校验，领域/外发工具调用前再校验角色、项目、媒体和同意范围。Planner 只能理解语义，不能选择或扩张权限边界。
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` | 用显式 `switch` 校验角色、已知工具、外发同意和确认要求 | 新增；当前工具数量无需注册表或工厂 |
| `AihrAgentActionService` | 将不透明 `draftId` 映射到既有记忆候选，确认/忽略继续走领域版本与幂等规则 | 新增；Redis 票据 30 分钟有效 |
| `AihrAgentAuditService` | 尽力写入最小运行元数据，失败不泄漏业务内容 | 新增 |
| 领域服务调用 | Orchestrator 将已校验计划直接映射到训练、待办、记忆、知识、媒体和全网服务 | 复用；不复制领域逻辑 |
| `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. 受控工具目录

最终工具集合按“工具名—服务端能力—授权—写入”维护。当前实现用枚举和 `AihrAgentPolicy` 显式 `switch` 固定工具集；以下“现有”表示已有领域接口或服务可复用，不表示客户端可绕过 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` | 读 | 既有工作成果服务 | 最终范围；当前 Agent 尚未接入 |
| `TEAM_WORK_RESULTS` | 读 | 既有主管工作成果服务 | 最终范围；当前 Agent 尚未接入 |
| `CAPTURE_MEMORY_DRAFT` | 草稿 | `AihrMemoryService` | 只能形成 `DRAFT/NEEDS_INPUT`，由用户选择 PRIVATE/COMPANY 后确认 |
| `PRACTICE_ASSIGNMENT_DRAFT` | 草稿 | 既有训练指派领域契约 | 最终范围；当前 Agent 尚未接入 |
| `REVIEW_DRAFT` | 草稿 | 既有复盘领域契约 | 最终范围；当前 Agent 尚未接入 |
| `WORK_REPORT_DRAFT` | 草稿 | 成果投稿领域契约 | 最终范围；当前 Agent 尚未接入，且不得与日常记忆互写 |
| `MEDIA_ANALYZE` | 读 | 现有 vision/ASR/media 提取 | 当次附件、大小限制、临时上下文；不自动入库 |
| `WEB_RESEARCH` | 读/外发 | `AihrWebAiService` | 独立来源、用户同意、HTTPS 提供方、现有限流；不写企业知识 |

每个工具必须在枚举、Policy 和测试中同时固定风险、允许角色、输入边界、附件/同意/确认要求与审计类型。工具数量和动态配置需求显著增加前不引入注册表框架；任何未知工具一律拒绝。

## 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. “工作助手”即数字师傅 Agent 主入口，普通消息由 Agent 自动路由；现有“查全网”显式页签保留独立来源与免责声明，同时 Agent 内识别到全网意图时也必须先展示外发同意卡。
2. 输入框接受文字、录音、图片、视频；附件选择后显示“仅本次分析”，并在发出前显示是否可能外发。
3. 回复顶部展示精简来源条：`已查内部 SOP`、`已读取我的待办`、`图片识别`、`需全网授权`、`待你确认`。
4. `NEEDS_INPUT` 使用不超过三个字段的澄清卡，优先从当前可选项目、日期和已授权对象中选择，不让用户输入内部编码。
5. `NEEDS_CONFIRMATION` 显示结构化草稿及“确认/修改/取消”；完成后显示领域系统返回的真实编号、时间和状态。
6. RAG 结果保留引用、原文件/视频卡和总结卡；全网结果保持独立免责声明与来源，不能与企业引用混排。
7. 主管和候选人后续复用同一响应契约和结果卡；当前移动端接入仅覆盖员工“问”，不得据此宣称三端已完成。

## 12. 审计、模型评价和运营

### 12.1 审计对象

新增 `aihr_agent_run`，只记录最小必要信息：

- `runId`、tenant/client/user、会话与上下文版本；
- 识别意图、执行工具、最终状态、主要来源类别、耗时、脱敏错误码和领域结果类型引用。

动作草稿不新增数据库表：当前仅用 30 分钟有效的 Redis 不透明票据引用既有 `aihr_memory_candidate`，最终版本、幂等键和回执继续由领域表负责。不得在 Agent 审计保存问题、答案、附件、原始密钥、敏感提示词、OSS URL 或模型隐藏推理。

### 12.2 质量指标

每个 Agent run 应可统计：意图准确率、工具选择准确率、澄清率、无依据率、确认转化率、确认后执行成功率、越权拒绝率、模型/工具失败率和用户反馈。用于评估的样本必须按租户、角色、项目和媒体类型分层，且敏感内容脱敏后才可出运营报表。

## 13. 安全与降级

- 登录态和请求基础校验先于 Planner；Policy 在任何领域或外发工具调用前执行，工具内部仍需重复授权，不能信任 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/真机交互、部署、真实账号业务流和正式试点证据。