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
@@ -32,6 +32,42 @@
 | 开放问题榜与积分 | 移动端 `/api/aihr/community/questions`、`questions/{id}`、`questions/{id}/answers`、`questions/{id}/best-answer`、`points/me`；后台 `/api/aihr/question-admin/**`、`/api/aihr/incentive-admin/rules` | 问题、答案、最佳答案和奖励全程按租户/身份授权；重复选优不重复入账。奖励只有积分与学习学分，不代表现金或提现 |
 | 全网 AI | 员工 `GET /api/aihr/web-ai/capabilities`、`POST /api/aihr/web-ai/query`；提供方管理 `/api/aihr/web-search/providers/**` | 与企业知识问答分入口和来源。仅接受公网 HTTPS 提供方，地址或密钥变更后必须重新连接测试；未配置/未启用时返回明确不可用，不生成假答案 |

+## 数字师傅 Agent 接入
+
+移动端“问”只调用 Agent，旧 `/api/knowledge/query`、`query-media` 和 `/api/aihr/web-ai/**` 仅作底层/兼容能力。示例中的 token、会话、项目和草稿号均为占位值：
+
+```bash
+API_BASE=${API_BASE:-https://wygj-api.localhost}
+TOKEN='REPLACE_WITH_MOBILE_ACCESS_TOKEN'
+
+curl -fsS "$API_BASE/api/aihr/agent/messages" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"question":"我今天有什么训练任务","conversationId":"<conversation>","contextVersion":1,"projectCode":"<authorized_project>","externalConsent":false}'
+
+curl -fsS "$API_BASE/api/aihr/agent/messages/media" \
+  -H "Authorization: Bearer $TOKEN" \
+  -F 'file=@/path/to/image.jpg' \
+  -F 'question=图中是什么宠物' \
+  -F 'externalConsent=false'
+```
+
+文字问题去空白后必须为 1–1000 字；媒体接口的 `question` 为空时使用“请分析附件内容”。请求不接受身份、角色、`toolCode`、知识空间 ID、SQL 或任意 URL。响应继续使用若依信封，`data.status` 只会是 `COMPLETED/NEEDS_INPUT/NEEDS_CONFIRMATION/NO_EVIDENCE/FORBIDDEN/UNAVAILABLE/FAILED`，按钮分别读取 `actionDraft/clarification/resources/nextActions`，不得解析 `answer` 猜状态。
+
+全网意图在 `externalConsent=false` 时以业务成功响应返回 `NEEDS_INPUT`，用户同意后原请求携带 `externalConsent=true` 重试。确认式记忆先取得 `actionDraft.draftId`，再提交卡片中可编辑的完整 `draft`：
+
+```bash
+curl -fsS "$API_BASE/api/aihr/agent/actions/<draftId>/confirm" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"expectedVersion":1,"idempotencyKey":"<unique-key>","draft":{"category":"FOLLOW_UP","title":"业主回访","summary":"3栋1201待回访","occurredAt":"2026-07-24T09:00:00+08:00"},"enableReminder":false,"saveScope":"PRIVATE"}'
+
+curl -fsS -X POST "$API_BASE/api/aihr/agent/actions/<draftId>/dismiss" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+校验失败返回业务码 `400`；角色/工具/项目/知识空间越权返回 `403`；会话版本、候选版本或幂等冲突返回 `409`；草稿票据 30 分钟过期后必须重新生成。Agent 审计只记录最小路由元数据，不保存上述问题、回答或附件。
+
 ## 后端落点

 - 业务模块：`backend/ruoyi-modules/ruoyi-aihr`