docs(agent): sync final implementation state

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

@@ -6,7 +6,7 @@
 >
 > 适用入口：员工端、主管端、候选人端的“问”能力；管理端只允许受限运营预览，不可代替移动用户身份。
 >
-> 本设计定义产品最终形态，不代表已经实现、发布或通过阶段一正式试点验收。
+> 本设计定义产品最终形态。当前本地已实现员工“问”的文字/媒体编排、知识与资源、本人待办/训练、主管训练概况、确认式记忆、全网同意、结构化响应和最小运行审计；主管/候选人统一入口及工作成果、指派、复盘、成果投稿等草稿工具仍是后续范围。该增量尚未部署，也未通过正式账号、真机或阶段一试点验收。
 
 ## 1. 结论
 
@@ -18,9 +18,9 @@ Agent 不拥有任意数据库、任意 HTTP 或任意写入权限；它只可
 
 ## 2. 要解决的问题
 
-当前能力已有会话改写、`QA/FILE/VIDEO/DATA_TOOL`、受控训练数据工具、确认式记忆、媒体识别和独立全网 AI，但普通 `QA` 会统一进入知识检索。因此以下消息的体验都不正确：
+升级前已有会话改写、`QA/FILE/VIDEO/DATA_TOOL`、受控训练数据工具、确认式记忆、媒体识别和独立全网 AI，但普通 `QA` 会统一进入知识检索；本地 Agent 增量正是为纠正以下路由：
 
-| 用户表达 | 正确处理 | 当前错误倾向 |
+| 用户表达 | 正确处理 | 升级前错误倾向 |
 |---|---|---|
 | “我今天有什么待办？” | 读取当前登录员工的真实待办 | 当作 SOP 检索 |
 | “记一下，3 栋 1201 要回访” | 生成可编辑确认卡 | 先检索知识库，再后置猜测 |
@@ -31,7 +31,7 @@ Agent 不拥有任意数据库、任意 HTTP 或任意写入权限；它只可
 
 ## 3. 设计原则
 
-1. **先授权，再理解，再调用。** 租户、应用、移动端身份、角色、项目范围和媒体大小在模型调用前由服务端固定；模型不能选择或扩张这些边界。
+1. **可信上下文不可由模型决定。** 登录态、租户和应用由服务端固定；请求长度和附件先做基础校验，领域/外发工具调用前再校验角色、项目、媒体和同意范围。Planner 只能理解语义，不能选择或扩张权限边界。
 2. **计划可验证，工具不可越权。** 模型只产生受严格 JSON Schema 校验的计划；执行器只接受注册工具和结构化参数。
 3. **事实与建议分开。** 实时任务、训练、成绩、项目数据必须来自领域工具；制度结论必须带知识引用；模型建议不得伪装为已分配任务或已执行动作。
 4. **读可自动，写必确认。** 读取权限范围内的资料或数据可直接执行；创建记录、提交成果、指派训练、通知主管等操作先生成草稿，确认后才调用领域写接口。
@@ -90,9 +90,10 @@ flowchart TD
 |---|---|---|
 | `AihrAgentOrchestrator` | 唯一编排入口：组装上下文、调用 Planner、过 Policy、执行工具、生成响应 | 新增 |
 | `AihrAgentPlanner` | 输出结构化意图和工具计划；模型不可用时使用保守规则 | 新增，替代会话服务中仅查询改写的职责 |
-| `AihrAgentPolicy` | 校验角色、项目、工具参数、外发同意、确认要求和最大调用数 | 新增 |
-| `AihrAgentToolRegistry` | 注册工具元数据、输入/输出 schema、读写风险和权限谓词 | 新增 |
-| 领域工具适配器 | 将 Agent 计划映射到已有训练、工作成果、记忆、知识、全网等服务 | 新增薄适配层；不复制领域逻辑 |
+| `AihrAgentPolicy` | 用显式 `switch` 校验角色、已知工具、外发同意和确认要求 | 新增；当前工具数量无需注册表或工厂 |
+| `AihrAgentActionService` | 将不透明 `draftId` 映射到既有记忆候选，确认/忽略继续走领域版本与幂等规则 | 新增；Redis 票据 30 分钟有效 |
+| `AihrAgentAuditService` | 尽力写入最小运行元数据，失败不泄漏业务内容 | 新增 |
+| 领域服务调用 | Orchestrator 将已校验计划直接映射到训练、待办、记忆、知识、媒体和全网服务 | 复用；不复制领域逻辑 |
 | `AihrKnowledgeQueryService` | 被 `KNOWLEDGE_SEARCH/FILE/VIDEO` 工具调用，继续负责空间授权、RAG、引用和受保护资源 | 复用 |
 | `AihrKnowledgeDataToolService` | 被训练/待办读取工具调用，继续做 APP 身份和主管范围校验 | 复用并按领域扩充 |
 | `AihrMemoryService` | 被记录草稿工具调用，继续生成、确认和落库确认式记忆 | 复用 |
@@ -146,9 +147,9 @@ Planner 只能返回以下受校验 JSON。服务端忽略任何未知字段和
 3. Planner 可提取“今天”“本项目”“刚才那份”等语义，但不能输出员工 ID、项目编码、知识空间 ID、收件人 ID 等权限主体；这些值必须由工具侧再解析。
 4. Planner 失败时用确定性规则路由 `RESOURCE_DELIVERY`、`LIVE_MY_WORK`、`CAPTURE_FACT`、`WEB_RESEARCH`；其余返回 `CLARIFY`，而不是自动 RAG。
 
-## 7. 工具注册表
+## 7. 受控工具目录
 
-最终工具集合按“工具名—服务端能力—授权—写入”登记。以下表中的“现有”表示已有领域接口或服务可复用，不表示客户端可绕过 Agent 直接扩大权限。
+最终工具集合按“工具名—服务端能力—授权—写入”维护。当前实现用枚举和 `AihrAgentPolicy` 显式 `switch` 固定工具集；以下“现有”表示已有领域接口或服务可复用，不表示客户端可绕过 Agent 扩大权限。
 
 | 工具 | 类型 | 当前能力来源 | 授权与输出约束 |
 |---|---|---|---|
@@ -157,16 +158,16 @@ Planner 只能返回以下受校验 JSON。服务端忽略任何未知字段和
 | `MY_CURRENT_TASKS` | 读 | `AihrKnowledgeDataToolService` | 认证 APP 员工本人；无任务要明确返回无任务 |
 | `MY_PRACTICE_SUMMARY` | 读 | 既有训练历史服务 | 仅认证员工本人 |
 | `TEAM_PRACTICE_SUMMARY` | 读 | 既有主管团队服务 | 仅主管且仅可信项目范围 |
-| `MY_WORK_RESULTS` | 读 | 既有工作成果服务 | 员工 + 项目 + 自然日；禁止未来日期 |
-| `TEAM_WORK_RESULTS` | 读 | 既有主管工作成果服务 | 主管项目范围 |
+| `MY_WORK_RESULTS` | 读 | 既有工作成果服务 | 最终范围；当前 Agent 尚未接入 |
+| `TEAM_WORK_RESULTS` | 读 | 既有主管工作成果服务 | 最终范围；当前 Agent 尚未接入 |
 | `CAPTURE_MEMORY_DRAFT` | 草稿 | `AihrMemoryService` | 只能形成 `DRAFT/NEEDS_INPUT`，由用户选择 PRIVATE/COMPANY 后确认 |
-| `PRACTICE_ASSIGNMENT_DRAFT` | 草稿 | 既有训练指派领域契约 | 仅主管范围；确认前不创建任务 |
-| `REVIEW_DRAFT` | 草稿 | 既有复盘领域契约 | 仅主管范围；确认前不改变复盘状态 |
-| `WORK_REPORT_DRAFT` | 草稿 | 成果投稿领域契约 | 只覆盖 CASE/VIDEO/SOP/KNOWLEDGE，不与日常记忆互写 |
+| `PRACTICE_ASSIGNMENT_DRAFT` | 草稿 | 既有训练指派领域契约 | 最终范围；当前 Agent 尚未接入 |
+| `REVIEW_DRAFT` | 草稿 | 既有复盘领域契约 | 最终范围；当前 Agent 尚未接入 |
+| `WORK_REPORT_DRAFT` | 草稿 | 成果投稿领域契约 | 最终范围；当前 Agent 尚未接入，且不得与日常记忆互写 |
 | `MEDIA_ANALYZE` | 读 | 现有 vision/ASR/media 提取 | 当次附件、大小限制、临时上下文；不自动入库 |
 | `WEB_RESEARCH` | 读/外发 | `AihrWebAiService` | 独立来源、用户同意、HTTPS 提供方、现有限流；不写企业知识 |
 
-每个工具必须声明：`risk=READ|DRAFT|WRITE`、允许角色、项目范围谓词、输入 schema、最大返回大小、是否可带附件、幂等要求、审计事件类型。任何未登记工具一律拒绝。
+每个工具必须在枚举、Policy 和测试中同时固定风险、允许角色、输入边界、附件/同意/确认要求与审计类型。工具数量和动态配置需求显著增加前不引入注册表框架；任何未知工具一律拒绝。
 
 ## 8. 确认式动作和真实状态
 
@@ -256,25 +257,24 @@ POST /api/aihr/agent/actions/{draftId}/dismiss
 
 ## 11. 移动端交互
 
-1. 将“问”首页改为一个统一入口“问数字师傅”；不要求用户先判断该选“工作助手”还是“查全网”。
+1. “工作助手”即数字师傅 Agent 主入口，普通消息由 Agent 自动路由；现有“查全网”显式页签保留独立来源与免责声明，同时 Agent 内识别到全网意图时也必须先展示外发同意卡。
 2. 输入框接受文字、录音、图片、视频；附件选择后显示“仅本次分析”，并在发出前显示是否可能外发。
 3. 回复顶部展示精简来源条：`已查内部 SOP`、`已读取我的待办`、`图片识别`、`需全网授权`、`待你确认`。
 4. `NEEDS_INPUT` 使用不超过三个字段的澄清卡，优先从当前可选项目、日期和已授权对象中选择，不让用户输入内部编码。
 5. `NEEDS_CONFIRMATION` 显示结构化草稿及“确认/修改/取消”；完成后显示领域系统返回的真实编号、时间和状态。
 6. RAG 结果保留引用、原文件/视频卡和总结卡；全网结果保持独立免责声明与来源，不能与企业引用混排。
-7. 主管和候选人复用同一交互组件，但只展示其工具注册表允许的快捷入口和结果卡。
+7. 主管和候选人后续复用同一响应契约和结果卡；当前移动端接入仅覆盖员工“问”，不得据此宣称三端已完成。
 
 ## 12. 审计、模型评价和运营
 
 ### 12.1 审计对象
 
-新增 `aihr_agent_run` 与 `aihr_agent_action_draft`，记录最小必要信息：
+新增 `aihr_agent_run`，只记录最小必要信息：
 
-- `runId`、tenant/app/user、项目范围快照、会话版本；
-- 识别意图、执行工具、策略结果、来源类别、耗时、脱敏错误码；
-- 动作草稿版本、确认人、幂等键哈希、领域回执 ID 和最终状态。
+- `runId`、tenant/client/user、会话与上下文版本；
+- 识别意图、执行工具、最终状态、主要来源类别、耗时、脱敏错误码和领域结果类型引用。
 
-不得在审计表保存原始密钥、完整敏感提示词、未脱敏聊天正文、原始 OSS URL 或模型隐藏推理。
+动作草稿不新增数据库表：当前仅用 30 分钟有效的 Redis 不透明票据引用既有 `aihr_memory_candidate`，最终版本、幂等键和回执继续由领域表负责。不得在 Agent 审计保存问题、答案、附件、原始密钥、敏感提示词、OSS URL 或模型隐藏推理。
 
 ### 12.2 质量指标
 
@@ -282,7 +282,7 @@ POST /api/aihr/agent/actions/{draftId}/dismiss
 
 ## 13. 安全与降级
 
-- Policy Gate 在任何模型调用和工具调用前执行；工具内部仍需重复做授权，不能信任 Planner 结果。
+- 登录态和请求基础校验先于 Planner；Policy 在任何领域或外发工具调用前执行，工具内部仍需重复授权，不能信任 Planner 结果。
 - 模型输出不能直接触发写操作、通知、下载、外发、身份切换或项目选择。
 - 全网、图片外发必须使用现有 HTTPS 提供方白名单、连接测试、大小限制、限流和用户同意。
 - 解析失败、模型关闭或 JSON 不合法时：优先规则路由已知只读/确认式意图；无法可靠判定则返回澄清，不回退到全量 RAG。