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
@@ -8,6 +8,8 @@

 **Tech Stack:** Java 17、Spring Boot、Sa-Token、JdbcTemplate、Jackson、JUnit 5/Mockito、uni-app Vue 3/TypeScript、Node test、MySQL 8。

+**实施状态（2026-07-24）：** Tasks 1–8 及 Task 9 的自动化、H5 构建和当前事实文档已完成；后端相关回归 91/91、移动端 Agent 契约 3/3。390×844 浏览器已验证寒暄、训练实时来源、全网同意和普通媒体分析；确认式写入、现场风险图 + SOP、旧资源撤权，以及主管/候选人入口仍未完成正式账号/真机浏览器验收。本分支尚未部署或生产验证。
+
 ---

 ## Scope split
@@ -21,7 +23,7 @@
 - Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentPlanner.java`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentPlannerTest.java`

- [ ] **Step 1: Write failing planner tests**
+- [x] **Step 1: Write failing planner tests**

 Cover exact routes:

@@ -35,7 +37,7 @@ assertEquals(Intent.MEDIA_UNDERSTANDING, planner.plan("图中是什么宠物", t
 assertEquals(Intent.KNOWLEDGE_QA, planner.plan("装修人员怎么进场", false).intent());
 ```

- [ ] **Step 2: Run the focused test and verify RED**
+- [x] **Step 2: Run the focused test and verify RED**

 Run:

@@ -47,7 +49,7 @@ timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \

 Expected: compilation failure because Agent contract and planner do not exist.

- [ ] **Step 3: Add the minimal typed contract**
+- [x] **Step 3: Add the minimal typed contract**

 `AihrAgentDto` defines:

@@ -76,11 +78,11 @@ record AgentPlan(

 Add request/response records matching the approved design. Requests accept question, conversation/version, project, broadcast ID and explicit external consent; they do not accept identity, role or tool name.

- [ ] **Step 4: Implement deterministic safe routing, then optional model refinement**
+- [x] **Step 4: Implement deterministic safe routing, then optional model refinement**

 Known high-confidence intents route deterministically. Model output is parsed only when it matches known enums, contains at most one tool and does not supply identity/project IDs. Invalid or unavailable model output returns deterministic `CLARIFY`, never default RAG.

- [ ] **Step 5: Run planner tests and commit**
+- [x] **Step 5: Run planner tests and commit**

 Expected: all `AihrAgentPlannerTest` tests pass.

@@ -96,7 +98,7 @@ git commit -m "feat(agent): add conservative intent planner"
 - Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentPolicy.java`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentPolicyTest.java`

- [ ] **Step 1: Write failing policy tests**
+- [x] **Step 1: Write failing policy tests**

 Required assertions:

@@ -108,15 +110,15 @@ assertThrows(ServiceException.class, () -> policy.authorize(candidate, plan(MY_C
 assertThrows(ServiceException.class, () -> policy.authorize(employee, forgedUnknownToolPlan));
 ```

- [ ] **Step 2: Verify RED**
+- [x] **Step 2: Verify RED**

 Run `AihrAgentPolicyTest` with the same Maven command pattern.

- [ ] **Step 3: Implement one explicit switch**
+- [x] **Step 3: Implement one explicit switch**

 `AihrAgentPolicy` declares risk and allowed roles for each `Tool`; it rejects unsupported role/tool pairs, write-like plans without confirmation, external plans without consent and multiple calls. Do not introduce an interface/factory/registry framework.

- [ ] **Step 4: Verify GREEN and commit**
+- [x] **Step 4: Verify GREEN and commit**

 ```bash
 git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentPolicy.java \
@@ -132,7 +134,7 @@ git commit -m "feat(agent): enforce tool policy"
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentOrchestratorTest.java`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentControllerContractTest.java`

- [ ] **Step 1: Write failing orchestrator tests**
+- [x] **Step 1: Write failing orchestrator tests**

 Verify:

@@ -142,7 +144,7 @@ Verify:
 - unavailable data maps to `UNAVAILABLE`; no task maps to `COMPLETED` plus `data.state=NO_TASKS`.
 - the controller has login protection and does not expose identity/tool parameters.

- [ ] **Step 2: Verify RED**
+- [x] **Step 2: Verify RED**

 Run:

@@ -152,7 +154,7 @@ timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \
  -Dtest=AihrAgentOrchestratorTest,AihrAgentControllerContractTest test
 ```

- [ ] **Step 3: Implement the unified text endpoint**
+- [x] **Step 3: Implement the unified text endpoint**

 Add:

@@ -162,7 +164,7 @@ POST /api/aihr/agent/messages

 The orchestrator resolves the current principal server-side, calls Planner, then Policy, and delegates to existing services. It maps citations, resources, conversation/version and data into `AgentResponse`.

- [ ] **Step 4: Verify GREEN and commit**
+- [x] **Step 4: Verify GREEN and commit**

 ```bash
 git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
@@ -179,7 +181,7 @@ git commit -m "feat(agent): orchestrate read-only work tools"
 - Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentController.java`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentMediaTest.java`

- [ ] **Step 1: Write failing tests for both media modes**
+- [x] **Step 1: Write failing tests for both media modes**

 Verify:

@@ -187,15 +189,15 @@ Verify:
 - “图中电梯门打不开怎么办” may combine vision context with authorized SOP search.
 - no-evidence work media still returns the vision observation and explicitly marks missing SOP evidence.

- [ ] **Step 2: Verify RED**
+- [x] **Step 2: Verify RED**

 Run focused knowledge and Agent media tests.

- [ ] **Step 3: Expose one internal media mode**
+- [x] **Step 3: Expose one internal media mode**

 Change the knowledge media method to accept an internal enum `MEDIA_ONLY|MEDIA_WITH_KNOWLEDGE`; the client cannot submit it. Reuse current extraction, authorization, size checks and conversation append. `MEDIA_ONLY` skips `queryDocuments`.

- [ ] **Step 4: Add the multipart Agent endpoint**
+- [x] **Step 4: Add the multipart Agent endpoint**

 Add:

@@ -205,7 +207,7 @@ POST /api/aihr/agent/messages/media

 Request parameters mirror text conversation/project fields and explicit consent only.

- [ ] **Step 5: Verify GREEN and commit**
+- [x] **Step 5: Verify GREEN and commit**

 ```bash
 git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
@@ -221,7 +223,7 @@ git commit -m "fix(agent): route media by intent"
 - Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentController.java`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentActionServiceTest.java`

- [ ] **Step 1: Write failing capture-action tests**
+- [x] **Step 1: Write failing capture-action tests**

 Verify:

@@ -231,22 +233,22 @@ Verify:
 - changed payload with the same key, expired candidate and cross-user candidate are rejected;
 - dismiss delegates to the existing candidate state machine.

- [ ] **Step 2: Verify RED**
+- [x] **Step 2: Verify RED**

 Run `AihrAgentActionServiceTest`.

- [ ] **Step 3: Implement reference-backed actions**
+- [x] **Step 3: Implement reference-backed actions**

 Agent `draftId` is opaque and resolves server-side to an existing domain draft. Confirmation delegates to `AihrMemoryService.confirm`; dismissal delegates to `AihrMemoryService.dismiss`. Do not duplicate memory normalization, authorization, persistence or idempotency logic.

- [ ] **Step 4: Add endpoints and verify GREEN**
+- [x] **Step 4: Add endpoints and verify GREEN**

 ```text
 POST /api/aihr/agent/actions/{draftId}/confirm
 POST /api/aihr/agent/actions/{draftId}/dismiss
 ```

- [ ] **Step 5: Commit**
+- [x] **Step 5: Commit**

 ```bash
 git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
@@ -260,15 +262,15 @@ git commit -m "feat(agent): confirm existing domain drafts"
 - Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentOrchestrator.java`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentWebResearchTest.java`

- [ ] **Step 1: Write failing consent tests**
+- [x] **Step 1: Write failing consent tests**

 Without consent, `WEB_RESEARCH` returns a clarification/consent card and never calls `AihrWebAiService`. With consent, it delegates to the existing web service and maps only web sources; enterprise citations stay empty.

- [ ] **Step 2: Verify RED, implement minimal delegation, verify GREEN**
+- [x] **Step 2: Verify RED, implement minimal delegation, verify GREEN**

 Keep existing provider enablement, HTTPS validation, privacy redaction and rate limits inside `AihrWebAiService`.

- [ ] **Step 3: Commit**
+- [x] **Step 3: Commit**

 ```bash
 git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentOrchestrator.java \
@@ -287,11 +289,11 @@ git commit -m "feat(agent): require web research consent"
 - Modify: `scripts/tests/aihr-schema-migrations.test.sh`
 - Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentAuditServiceTest.java`

- [ ] **Step 1: Write failing schema and audit tests**
+- [x] **Step 1: Write failing schema and audit tests**

 Assert the migration provides `aihr_agent_run` with run, tenant/app/user, conversation/version, intent, tool, status, source type, duration and sanitized error code. Action details remain in existing domain draft tables and are linked by `result_ref`; do not duplicate sensitive request bodies.

- [ ] **Step 2: Verify RED**
+- [x] **Step 2: Verify RED**

 Run Java audit test plus:

@@ -299,15 +301,15 @@ Run Java audit test plus:
 bash scripts/tests/aihr-schema-migrations.test.sh
 ```

- [ ] **Step 3: Add idempotent MySQL migration and audit writer**
+- [x] **Step 3: Add idempotent MySQL migration and audit writer**

 The service records final state in a `finally`-safe path. Audit failure logs a sanitized warning and does not turn a valid user response into failure.

- [ ] **Step 4: Extend reset and read-only preflight checks**
+- [x] **Step 4: Extend reset and read-only preflight checks**

 Production request code must not run DDL. Preflight checks the table and required indexes.

- [ ] **Step 5: Verify GREEN and commit**
+- [x] **Step 5: Verify GREEN and commit**

 ```bash
 git add backend/script/sql backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
@@ -325,11 +327,11 @@ git commit -m "feat(agent): audit orchestrated runs"
 - Test: `mobile-uni/tests/agent.test.mjs`
 - Test: `mobile-uni/tests/mobile-user-pages.test.mjs`

- [ ] **Step 1: Write failing contract tests**
+- [x] **Step 1: Write failing contract tests**

 Verify source chips, `NO_EVIDENCE/UNAVAILABLE/FORBIDDEN`, clarification cards, memory confirmation cards, external-consent prompts, citations/resources and media uploads all use the new Agent endpoints. Verify the UI never derives an action button from answer text.

- [ ] **Step 2: Verify RED**
+- [x] **Step 2: Verify RED**

 Run:

@@ -337,18 +339,18 @@ Run:
 node --test mobile-uni/tests/agent.test.mjs mobile-uni/tests/mobile-user-pages.test.mjs
 ```

- [ ] **Step 3: Add typed Agent service and map the existing chat page**
+- [x] **Step 3: Add typed Agent service and map the existing chat page**

 Reuse existing audio recording, upload, citation, resource, memory-card and conversation-version UI. Add only source chips, clarification/consent card and status-specific copy. Keep legacy knowledge service for compatibility outside this page.

- [ ] **Step 4: Verify tests and H5 build**
+- [x] **Step 4: Verify tests and H5 build**

 ```bash
 node --test mobile-uni/tests/agent.test.mjs mobile-uni/tests/mobile-user-pages.test.mjs
 npm --prefix mobile-uni run build:h5
 ```

- [ ] **Step 5: Commit**
+- [x] **Step 5: Commit**

 ```bash
 git add mobile-uni/src/services/agent.ts mobile-uni/src/types/api.ts \
@@ -364,7 +366,7 @@ git commit -m "feat(mobile): use digital master agent"
 - Modify: `docs/20260708/数字师傅学练问报整合方案.md`
 - Modify: `docs/superpowers/specs/2026-07-24-digital-master-agent-design.md`

- [ ] **Step 1: Run backend regression**
+- [x] **Step 1: Run backend regression**

 ```bash
 timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \
@@ -372,7 +374,7 @@ timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \
  -Dtest='AihrAgent*Test,AihrKnowledgeQueryServiceTest,AihrKnowledgeDataToolServiceTest,AihrMemoryServiceTest' test
 ```

- [ ] **Step 2: Run mobile regression and build**
+- [x] **Step 2: Run mobile regression and build**

 ```bash
 node --test mobile-uni/tests/*.test.mjs
@@ -380,29 +382,25 @@ npm --prefix mobile-uni run build:h5
 git diff --check
 ```

- [ ] **Step 3: Update current-truth documentation**
+- [x] **Step 3: Update current-truth documentation**

 Document exact API contract, migration order, implemented/verified/deployed distinction and remaining courseware/personal-resource subprojects. Remove “待评审” from the approved design.

- [ ] **Step 4: Run authenticated browser acceptance**
+- [ ] **Step 4: Complete authenticated browser and real-device acceptance**

-At 390×844 and desktop widths, exercise:
+已在 390×844 完成寒暄、训练实时来源、全网同意和普通媒体分析。发布前仍须以正式账号/真机补齐：

-1. “你好” — no RAG/source card.
-2. “我今天有什么待办” — live-data source and truthful `NO_TASKS|HAS_TASKS`.
-3. “记一下，3栋1201要回访” — confirmation before persistence.
-4. pet image — media source, no SOP lookup.
-5. work-risk image — media + authorized SOP or explicit no evidence.
-6. web question — consent before external call.
-7. old file follow-up — protected resource delivery and revoked-access rejection.
+1. “记一下，3栋1201要回访” — confirmation before persistence.
+2. work-risk image — media + authorized SOP or explicit no evidence.
+3. old file follow-up — protected resource delivery and revoked-access rejection.

-Capture screenshots and inspect layout, overflow, keyboard, focus and action-state feedback.
+同时补齐桌面宽度、键盘、焦点、确认/撤销反馈和主管/候选人角色正反例；截图不能替代实际交互。

- [ ] **Step 5: Final commit and release gate**
+- [x] **Step 5: Prepare the final documentation commit and preserve the release gate**

 ```bash
 git add docs
 git commit -m "docs(agent): record implementation and acceptance"
 ```

-Do not deploy until the complete remote static/backend/schema preflight can be run from a clean committed tree. Deployment and formal production account/real-device acceptance remain separate explicit actions.
+本次只提交本地实现和事实文档。未执行发布；只有在干净已提交树上完成远端静态、后端、schema 三项预检并补齐上面的正式验收，才可更新为 deployed / production-verified。
@@ -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。