docs(agent): approve design and add implementation plan

This commit is contained in:
2026-07-24 19:47:15 +08:00
parent 5d864a1444
commit 36b5bc8564
2 changed files with 409 additions and 1 deletions
@@ -0,0 +1,408 @@
# 数字师傅工作 Agent Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 将移动端“问”从默认 RAG 查询改为受身份、权限、确认和审计约束的数字师傅工作 Agent,并保持现有知识、数据工具、记忆、全网和媒体链路兼容。
**Architecture:** 新增 `org.dromara.aihr.agent` 编排边界,Planner 只产生受校验的意图和工具计划,Policy 固定角色与工具许可,Orchestrator 复用现有领域服务。旧 `/api/knowledge/**` 与 `/api/aihr/web-ai/**` 保留;移动端改用 `/api/aihr/agent/**` 的统一响应,不从模型自由文本决定按钮或业务状态。
**Tech Stack:** Java 17、Spring Boot、Sa-Token、JdbcTemplate、Jackson、JUnit 5/Mockito、uni-app Vue 3/TypeScript、Node test、MySQL 8。
---
## Scope split
本计划完整实现已确认的 Agent 设计。课程播放器/防快进和个人文件/网页知识空间有独立数据生命周期,不塞入 Agent 编排改动;Agent 只读取当前已经正式存在的学习、训练、工作成果、记忆和知识能力。它们分别形成后续独立计划,不影响本计划验收。
### Task 1: Agent contract and conservative planner
**Files:**
- Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentDto.java`
- 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**
Cover exact routes:
```java
assertEquals(Intent.LIVE_MY_WORK, planner.plan("我今天有什么待办", false).intent());
assertEquals(Tool.MY_CURRENT_TASKS, planner.plan("我今天有什么待办", false).tool());
assertEquals(Intent.CAPTURE_FACT, planner.plan("记一下,3栋1201要回访", false).intent());
assertEquals(Intent.SOCIAL, planner.plan("你好", false).intent());
assertEquals(Intent.CLARIFY, planner.plan("帮我处理一下", false).intent());
assertEquals(Intent.MEDIA_UNDERSTANDING, planner.plan("图中是什么宠物", true).intent());
assertEquals(Intent.KNOWLEDGE_QA, planner.plan("装修人员怎么进场", false).intent());
```
- [ ] **Step 2: Run the focused test and verify RED**
Run:
```bash
timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \
-DskipTests=false -Dsurefire.failIfNoSpecifiedTests=false \
-Dtest=AihrAgentPlannerTest test
```
Expected: compilation failure because Agent contract and planner do not exist.
- [ ] **Step 3: Add the minimal typed contract**
`AihrAgentDto` defines:
```java
enum Intent {
KNOWLEDGE_QA, RESOURCE_DELIVERY, LIVE_MY_WORK, LIVE_TEAM_WORK,
PRACTICE_COACHING, CAPTURE_FACT, DRAFT_ACTION,
MEDIA_UNDERSTANDING, WEB_RESEARCH, CLARIFY, SOCIAL
}
enum Tool {
NONE, KNOWLEDGE_SEARCH, KNOWLEDGE_RESOURCE, MY_CURRENT_TASKS,
MY_PRACTICE_SUMMARY, TEAM_PRACTICE_SUMMARY,
CAPTURE_MEMORY_DRAFT, MEDIA_ANALYZE, WEB_RESEARCH
}
record AgentPlan(
Intent intent,
String rewrittenRequest,
Tool tool,
boolean requiresConfirmation,
boolean requiresExternalConsent,
ResponseStyle responseStyle
) {}
```
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**
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**
Expected: all `AihrAgentPlannerTest` tests pass.
```bash
git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentPlannerTest.java
git commit -m "feat(agent): add conservative intent planner"
```
### Task 2: Policy gate and registered tool metadata
**Files:**
- 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**
Required assertions:
```java
assertDoesNotThrow(() -> policy.authorize(employee, plan(MY_CURRENT_TASKS)));
assertThrows(ServiceException.class, () -> policy.authorize(employee, plan(TEAM_PRACTICE_SUMMARY)));
assertDoesNotThrow(() -> policy.authorize(supervisor, plan(TEAM_PRACTICE_SUMMARY)));
assertThrows(ServiceException.class, () -> policy.authorize(candidate, plan(MY_CURRENT_TASKS)));
assertThrows(ServiceException.class, () -> policy.authorize(employee, forgedUnknownToolPlan));
```
- [ ] **Step 2: Verify RED**
Run `AihrAgentPolicyTest` with the same Maven command pattern.
- [ ] **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**
```bash
git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentPolicy.java \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentPolicyTest.java
git commit -m "feat(agent): enforce tool policy"
```
### Task 3: Read-only orchestrator and unified API
**Files:**
- Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentOrchestrator.java`
- Create: `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/AihrAgentOrchestratorTest.java`
- Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentControllerContractTest.java`
- [ ] **Step 1: Write failing orchestrator tests**
Verify:
- `LIVE_MY_WORK` sends only `MY_CURRENT_TASKS` to the existing query/data-tool chain and never invokes RAG.
- `KNOWLEDGE_QA` delegates to `AihrKnowledgeQueryService`.
- `SOCIAL` and `CLARIFY` do not invoke knowledge or data services.
- 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**
Run:
```bash
timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \
-DskipTests=false -Dsurefire.failIfNoSpecifiedTests=false \
-Dtest=AihrAgentOrchestratorTest,AihrAgentControllerContractTest test
```
- [ ] **Step 3: Implement the unified text endpoint**
Add:
```text
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**
```bash
git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent
git commit -m "feat(agent): orchestrate read-only work tools"
```
### Task 4: Correct media routing and conversation context
**Files:**
- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/knowledge/service/AihrKnowledgeQueryService.java`
- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/knowledge/AihrKnowledgeQueryServiceTest.java`
- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentOrchestrator.java`
- 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**
Verify:
- “图中是什么宠物” returns the vision observation, labels it `MEDIA`, does not call SOP search and appends that answer to the short conversation.
- “图中电梯门打不开怎么办” 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**
Run focused knowledge and Agent media tests.
- [ ] **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**
Add:
```text
POST /api/aihr/agent/messages/media
```
Request parameters mirror text conversation/project fields and explicit consent only.
- [ ] **Step 5: Verify GREEN and commit**
```bash
git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/knowledge/service/AihrKnowledgeQueryService.java \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr
git commit -m "fix(agent): route media by intent"
```
### Task 5: Confirmation actions by reference, not duplicate business logic
**Files:**
- Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentActionService.java`
- 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**
Verify:
- capture intent creates/reuses the existing memory candidate and returns `NEEDS_CONFIRMATION`;
- confirmation requires candidate version, idempotency key, edited draft and `PRIVATE|COMPANY`;
- duplicate identical confirmation returns the same target;
- 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**
Run `AihrAgentActionServiceTest`.
- [ ] **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**
```text
POST /api/aihr/agent/actions/{draftId}/confirm
POST /api/aihr/agent/actions/{draftId}/dismiss
```
- [ ] **Step 5: Commit**
```bash
git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent
git commit -m "feat(agent): confirm existing domain drafts"
```
### Task 6: Explicit web consent and source separation
**Files:**
- 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**
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**
Keep existing provider enablement, HTTPS validation, privacy redaction and rate limits inside `AihrWebAiService`.
- [ ] **Step 3: Commit**
```bash
git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentOrchestrator.java \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent/AihrAgentWebResearchTest.java
git commit -m "feat(agent): require web research consent"
```
### Task 7: Minimal Agent audit and migration
**Files:**
- Create: `backend/script/sql/update/aihr_20260724_agent_orchestration_mysql8.sql`
- Modify: `backend/script/sql/aihr_knowledge_mysql8.sql`
- Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent/AihrAgentAuditService.java`
- Modify: `scripts/reset-dev-db.sh`
- Modify: `scripts/release-preflight.sh`
- 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**
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**
Run Java audit test plus:
```bash
bash scripts/tests/aihr-schema-migrations.test.sh
```
- [ ] **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**
Production request code must not run DDL. Preflight checks the table and required indexes.
- [ ] **Step 5: Verify GREEN and commit**
```bash
git add backend/script/sql backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/agent \
backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/agent \
scripts/reset-dev-db.sh scripts/release-preflight.sh scripts/tests/aihr-schema-migrations.test.sh
git commit -m "feat(agent): audit orchestrated runs"
```
### Task 8: Move mobile “问” to the Agent response contract
**Files:**
- Create: `mobile-uni/src/services/agent.ts`
- Modify: `mobile-uni/src/types/api.ts`
- Modify: `mobile-uni/src/pages/user/sop/index.vue`
- Test: `mobile-uni/tests/agent.test.mjs`
- Test: `mobile-uni/tests/mobile-user-pages.test.mjs`
- [ ] **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**
Run:
```bash
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**
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**
```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**
```bash
git add mobile-uni/src/services/agent.ts mobile-uni/src/types/api.ts \
mobile-uni/src/pages/user/sop/index.vue mobile-uni/tests
git commit -m "feat(mobile): use digital master agent"
```
### Task 9: Regression, docs, browser and release handoff
**Files:**
- Modify: `docs/API_INTEGRATION.md`
- Modify: `docs/BRD_IMPLEMENTATION_AUDIT.md`
- Modify: `docs/20260708/数字师傅学练问报整合方案.md`
- Modify: `docs/superpowers/specs/2026-07-24-digital-master-agent-design.md`
- [ ] **Step 1: Run backend regression**
```bash
timeout 120s mvn -pl ruoyi-modules/ruoyi-aihr -am \
-DskipTests=false -Dsurefire.failIfNoSpecifiedTests=false \
-Dtest='AihrAgent*Test,AihrKnowledgeQueryServiceTest,AihrKnowledgeDataToolServiceTest,AihrMemoryServiceTest' test
```
- [ ] **Step 2: Run mobile regression and build**
```bash
node --test mobile-uni/tests/*.test.mjs
npm --prefix mobile-uni run build:h5
git diff --check
```
- [ ] **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**
At 390×844 and desktop widths, exercise:
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.
Capture screenshots and inspect layout, overflow, keyboard, focus and action-state feedback.
- [ ] **Step 5: Final commit and 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.
@@ -1,6 +1,6 @@
# 数字师傅工作 Agent 总体设计
> 状态:待评审
> 状态:已确认(2026-07-24)
>
> 日期:2026-07-24
>