|
@@ -0,0 +1,305 @@
|
|
|
|
|
+# 用户画像 prompt 拼装设计规范
|
|
|
|
|
+
|
|
|
|
|
+**日期**：2026-08-24
|
|
|
|
|
+**状态**：设计阶段
|
|
|
|
|
+**关联计划**：待 writing-plans 生成
|
|
|
|
|
+**需求来源**：浠艾福平台「AI 健康教练人格分化与管家自助选择」功能的延伸——每个用户拥有自己的画像 prompt
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 一、核心决策
|
|
|
|
|
+
|
|
|
|
|
+| 决策项 | 结论 |
|
|
|
|
|
+|--------|------|
|
|
|
|
|
+| **适用范围** | 所有 AI 对话端点（chat/send、butler/send、nutrition/send、health-coach/send），不含 health_plan（结构化方案生成，已有独立画像注入逻辑） |
|
|
|
|
|
+| **画像主体** | 按 memberId 分派：有 child_id/memberId 时用该成员画像；无时不注入 |
|
|
|
|
|
+| **渲染深度** | 完整版：五维评分 + 睡眠/压力/运动等指标清单（复用健康方案生成渲染格式） |
|
|
|
|
|
+| **可编辑性** | 允许用户手动编辑自由文本画像 prompt |
|
|
|
|
|
+| **实现方案** | A：users 表加 portrait_prompt TEXT 列；Python 侧新增 portrait_service.py |
|
|
|
|
|
+| **缓存策略** | portrait_prompt 600s，profile_snapshot 900s（进程内 dict 缓存，失败降级为不注入） |
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 二、数据层变更
|
|
|
|
|
+
|
|
|
|
|
+### 2.1 users 表新增列
|
|
|
|
|
+
|
|
|
|
|
+```sql
|
|
|
|
|
+ALTER TABLE users ADD COLUMN portrait_prompt TEXT COMMENT '用户自定义画像 prompt（为空时自动从 profile_snapshot 渲染）' AFTER mascot;
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**位置**：schema.sql 的 users 建表语句 + DatabaseInitializer.runMigrations() 迁移脚本。
|
|
|
|
|
+
|
|
|
|
|
+### 2.2 User.java 实体
|
|
|
|
|
+
|
|
|
|
|
+```java
|
|
|
|
|
+@TableField("portrait_prompt")
|
|
|
|
|
+private String portraitPrompt;
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 2.3 不新建表
|
|
|
|
|
+
|
|
|
|
|
+直接复用已有 `profile_snapshot`（五维指标 JSON）和 `profile_history`（历史快照），不新增表。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 三、API 层设计（Java 侧）
|
|
|
|
|
+
|
|
|
|
|
+### 3.1 新增两个端点（POST，统一放 /api/user/*）
|
|
|
|
|
+
|
|
|
|
|
+#### `POST /api/user/portrait/get`
|
|
|
|
|
+
|
|
|
|
|
+**说明**：读取当前登录用户的 portrait_prompt，以及指定成员的 profile_snapshot 渲染文本。
|
|
|
|
|
+
|
|
|
|
|
+**请求体**：
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "userId": 12345, // 被查询用户 ID（管理员可传任意用户；普通用户默认取 JWT userId）
|
|
|
|
|
+ "memberId": 67890 // 可选，成员 ID；不传则只返回 portrait_prompt
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**响应**：
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 200,
|
|
|
|
|
+ "data": {
|
|
|
|
|
+ "portraitPrompt": "我家孩子偏瘦，容易积食...", // 用户手动编辑的画像文本（可为空）
|
|
|
|
|
+ "renderedSnapshot": "【五维评分】身 7.2 智 6.8... # 或 null（无 member 时）"
|
|
|
|
|
+ }
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**实现要点**：
|
|
|
|
|
+- 复用 `ProfileReadService.getProfile(memberId)` 获取快照
|
|
|
|
|
+- 渲染函数复用 `adapter.py` 已有的 profile 渲染逻辑，移植到 Java（`UserService` 或新增 `PortraitRenderService`）
|
|
|
|
|
+- 管理员角色可查任意用户；普通用户只能查自己
|
|
|
|
|
+
|
|
|
|
|
+#### `POST /api/user/portrait/edit`
|
|
|
|
|
+
|
|
|
|
|
+**说明**：更新当前用户的 portrait_prompt。
|
|
|
|
|
+
|
|
|
|
|
+**请求体**：
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "portraitPrompt": "我家孩子 8 岁，偏瘦，挑食..." // 最多 2000 字符
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**权限**：任何登录用户可编辑自己的；管理员可编辑任意用户（通过请求体加 userId 字段）。
|
|
|
|
|
+
|
|
|
|
|
+**验证**：portraitPrompt 长度 ≤ 2000，null 视为清空。
|
|
|
|
|
+
|
|
|
|
|
+**实现**：`UserController` 新增方法 → `UserService.updatePortraitPrompt()` → Mapper 直接 UPDATE。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 四、Python Graph 层设计
|
|
|
|
|
+
|
|
|
|
|
+### 4.1 新增 app/portrait_service.py
|
|
|
|
|
+
|
|
|
|
|
+```python
|
|
|
|
|
+"""用户画像 prompt 组装服务
|
|
|
|
|
+
|
|
|
|
|
+职责：
|
|
|
|
|
+1. 拉取用户自定义画像文本（600s 缓存）
|
|
|
|
|
+2. 拉取 profile_snapshot 并渲染为文本（900s 缓存）
|
|
|
|
|
+3. 拼装成 SystemMessage 内容；无数据时返回 None
|
|
|
|
|
+"""
|
|
|
|
|
+import time
|
|
|
|
|
+import logging
|
|
|
|
|
+from app.tools.java_client import JavaClient
|
|
|
|
|
+from app.prompt_service import clear_cache
|
|
|
|
|
+
|
|
|
|
|
+logger = logging.getLogger(__name__)
|
|
|
|
|
+
|
|
|
|
|
+_TTL_PROMPT = 600 # 用户自定义 prompt 缓存 10 分钟
|
|
|
|
|
+_TTL_SNAPSHOT = 900 # 画像快照缓存 15 分钟
|
|
|
|
|
+
|
|
|
|
|
+_cache_prompt: dict[int, tuple[str, float]] = {} # user_id -> (text, ts)
|
|
|
|
|
+_cache_snapshot: dict[int, tuple[str, float]] = {} # member_id -> (text, ts)
|
|
|
|
|
+
|
|
|
|
|
+
|
|
|
|
|
+def _render_snapshot(profile: dict) -> str:
|
|
|
|
|
+ """将 profile Map 渲染为中文指标清单文本"""
|
|
|
|
|
+ if not profile:
|
|
|
|
|
+ return ""
|
|
|
|
|
+ lines = []
|
|
|
|
|
+ member = profile.get("member") or {}
|
|
|
|
|
+ name = member.get("name", "用户")
|
|
|
|
|
+ age = member.get("age")
|
|
|
|
|
+ gender = member.get("gender")
|
|
|
|
|
+ lines.append(f"## 画像对象：{name}（{age}岁，{gender}）")
|
|
|
|
|
+
|
|
|
|
|
+ dims = profile.get("dimension_scores") or {}
|
|
|
|
|
+ if dims:
|
|
|
|
|
+ lines.append(f"五维评分：身 {dims.get('body', '?')} 智 {dims.get('wisdom', '?')} "
|
|
|
|
|
+ f"心 {dims.get('mind', '?')} 行 {dims.get('action', '?')} 富 {dims.get('wealth', '?')}")
|
|
|
|
|
+
|
|
|
|
|
+ body = profile.get("body_metrics") or {}
|
|
|
|
|
+ if body.get("sleep_dur_avg"):
|
|
|
|
|
+ lines.append(f"平均睡眠：{body['sleep_dur_avg']}小时/天")
|
|
|
|
|
+ if body.get("exercise_count_week"):
|
|
|
|
|
+ lines.append(f"周运动频次：{body['exercise_count_week']}次")
|
|
|
|
|
+
|
|
|
|
|
+ mind = profile.get("mind_metrics") or {}
|
|
|
|
|
+ if mind.get("stress_avg"):
|
|
|
|
|
+ lines.append(f"平均压力：{mind['stress_avg']}/10")
|
|
|
|
|
+
|
|
|
|
|
+ problems = profile.get("problem_domains") or []
|
|
|
|
|
+ if problems:
|
|
|
|
|
+ lines.append(f"关注问题域：{', '.join(problems[:5])}")
|
|
|
|
|
+
|
|
|
|
|
+ return "\n".join(lines)
|
|
|
|
|
+
|
|
|
|
|
+
|
|
|
|
|
+async def get_user_portrait_text(java: JavaClient, user_id: int, member_id: int | None) -> str | None:
|
|
|
|
|
+ """返回画像 SystemMessage 内容；无画像数据时返回 None"""
|
|
|
|
|
+ parts = []
|
|
|
|
|
+
|
|
|
|
|
+ # 1. 用户自定义 prompt
|
|
|
|
|
+ now = time.time()
|
|
|
|
|
+ cached_text, cached_ts = _cache_prompt.get(user_id, (None, 0))
|
|
|
|
|
+ if now - cached_ts < _TTL_PROMPT and cached_text is not None:
|
|
|
|
|
+ user_text = cached_text
|
|
|
|
|
+ else:
|
|
|
|
|
+ try:
|
|
|
|
|
+ client = await java._get_client()
|
|
|
|
|
+ resp = await client.post("/api/user/portrait/get", json={"userId": user_id}, timeout=5.0)
|
|
|
|
|
+ data = resp.json()
|
|
|
|
|
+ user_text = (data.get("data") or {}).get("portraitPrompt") or ""
|
|
|
|
|
+ _cache_prompt[user_id] = (user_text, now)
|
|
|
|
|
+ except Exception as e:
|
|
|
|
|
+ logger.warning("拉取用户画像 prompt 失败: %s", e)
|
|
|
|
|
+ user_text = ""
|
|
|
|
|
+
|
|
|
|
|
+ if user_text.strip():
|
|
|
|
|
+ parts.append(user_text)
|
|
|
|
|
+
|
|
|
|
|
+ # 2. 快照渲染文本（仅当有 member_id 时）
|
|
|
|
|
+ if member_id:
|
|
|
|
|
+ snap_now = time.time()
|
|
|
|
|
+ cached_snap, cached_snap_ts = _cache_snapshot.get(member_id, (None, 0))
|
|
|
|
|
+ if snap_now - cached_snap_ts < _TTL_SNAPSHOT and cached_snap is not None:
|
|
|
|
|
+ snap_text = cached_snap
|
|
|
|
|
+ else:
|
|
|
|
|
+ try:
|
|
|
|
|
+ profile = await java.get_member_profile(int(member_id))
|
|
|
|
|
+ snap_text = _render_snapshot(profile) if profile else ""
|
|
|
|
|
+ _cache_snapshot[member_id] = (snap_text, snap_now)
|
|
|
|
|
+ except Exception as e:
|
|
|
|
|
+ logger.warning("拉取成员画像快照失败: %s", e)
|
|
|
|
|
+ snap_text = ""
|
|
|
|
|
+
|
|
|
|
|
+ if snap_text.strip():
|
|
|
|
|
+ if user_text.strip():
|
|
|
|
|
+ parts.append("\n---参考指标---\n" + snap_text)
|
|
|
|
|
+ else:
|
|
|
|
|
+ parts.append("以下是用户画像数据（系统自动生成），请结合这些数据给出更针对性的建议：\n" + snap_text)
|
|
|
|
|
+
|
|
|
|
|
+ return "\n\n".join(parts) if parts else None
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 4.2 各 graph 改造
|
|
|
|
|
+
|
|
|
|
|
+**待改造的 graph 文件**（需逐一确认是否存在）：
|
|
|
|
|
+- `app/graphs/health_coach_graph.py` ✅ 已知存在
|
|
|
|
|
+- `app/graphs/chat_graph.py`
|
|
|
|
|
+- `app/graphs/butler_graph.py`
|
|
|
|
|
+- `app/graphs/nutrition_graph.py`
|
|
|
|
|
+
|
|
|
|
|
+**通用插入模式**（以 health_coach_graph 为例）：
|
|
|
|
|
+
|
|
|
|
|
+```python
|
|
|
|
|
+from app.portrait_service import get_user_portrait_text
|
|
|
|
|
+
|
|
|
|
|
+async def generate_answer(state: HealthCoachState) -> dict:
|
|
|
|
|
+ _ctx = state.get("context") or {}
|
|
|
|
|
+ _coach_id = _ctx.get("coach_id")
|
|
|
|
|
+ # ... 现有 persona prompt 逻辑不变 ...
|
|
|
|
|
+ messages = [SystemMessage(content=_persona_prompt or _base_prompt or DEFAULT_COACH_PROMPT)]
|
|
|
|
|
+
|
|
|
|
|
+ # 新增：画像段
|
|
|
|
|
+ member_id = state.get("child_id") or (_ctx.get("member_id") if _ctx else None)
|
|
|
|
|
+ portrait_text = await get_user_portrait_text(java, state["user_id"], member_id)
|
|
|
|
|
+ if portrait_text:
|
|
|
|
|
+ messages.insert(1, SystemMessage(content=portrait_text))
|
|
|
|
|
+
|
|
|
|
|
+ # ... 后续 context/knowledge/memory 逻辑不变 ...
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**注意**：
|
|
|
|
|
+- `java` 变量需在 graph 创建时提前构造（与 RagRetriever/ChatOpenAI 同级）
|
|
|
|
|
+- member_id 来源：`state.get("child_id")` 优先；若 context 中有 `member_id` 则也用
|
|
|
|
|
+
|
|
|
|
|
+### 4.3 清理缓存 hook
|
|
|
|
|
+
|
|
|
|
|
+在 `/api/user/portrait/edit` 响应成功后，调用 `portrait_service.clear_cache(user_id)` 使旧缓存失效。
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 五、前端设计
|
|
|
|
|
+
|
|
|
|
|
+### 5.1 小程序（cfc-frontend）
|
|
|
|
|
+
|
|
|
|
|
+**新增页面**：`pages/profile/portrait-edit.vue`
|
|
|
|
|
+
|
|
|
|
|
+**入口**：在现有「我的」页（profile/index.vue）或聊天页顶部导航区添加「我的画像」入口按钮。
|
|
|
|
|
+
|
|
|
|
|
+**页面内容**：
|
|
|
|
|
+- 标题：我的画像
|
|
|
|
|
+- 文本域：`<textarea :value="portraitPrompt" @input="onInput" maxlength="2000" />`
|
|
|
|
|
+- 显示字数统计（如 42/2000）
|
|
|
|
|
+- 「保存」按钮 → 调用 `/api/user/portrait/edit`
|
|
|
|
|
+- 「参考指标」区块：只读，展示系统渲染的画像快照文本（调用 `/api/user/portrait/get` 获取）
|
|
|
|
|
+
|
|
|
|
|
+**API 封装**：在 `src/api/user.js` 新增：
|
|
|
|
|
+```javascript
|
|
|
|
|
+export function getPortrait(userId) {
|
|
|
|
|
+ return request('/api/user/portrait/get', 'POST', { userId })
|
|
|
|
|
+}
|
|
|
|
|
+export function editPortrait(data) {
|
|
|
|
|
+ return request('/api/user/portrait/edit', 'POST', data)
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 5.2 Web 管理端
|
|
|
|
|
+
|
|
|
|
|
+暂不新增。用户自主编辑即可；管理员如需帮用户代填，走 `/api/user/portrait/edit?userId=xxx` 接口（由技术支持操作）。
|
|
|
|
|
+
|
|
|
|
|
+### 5.3 pages.json
|
|
|
|
|
+
|
|
|
|
|
+注册新页面：
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "path": "pages/profile/portrait-edit",
|
|
|
|
|
+ "style": { "navigationBarTitleText": "我的画像" }
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 六、验收标准
|
|
|
|
|
+
|
|
|
|
|
+1. **编译**：`mvn clean compile` EXIT 0；`python3 -m py_compile` 所有涉及文件 OK
|
|
|
|
|
+2. **画像注入**：四个对话端点均能在 LLM 收到消息中包含画像 SystemMessage（可通过调试日志验证）
|
|
|
|
|
+3. **用户编辑**：edit 接口写入成功；get 接口读到最新值；缓存 5 秒内失效
|
|
|
|
|
+4. **无画像降级**：portrait_prompt 为空且无 member_id 时，LLM 不收到画像段（与改动前行为一致）
|
|
|
|
|
+5. **memberId 分派**：传 child_id=123 时渲染 123 的画像；不传时不渲染
|
|
|
|
|
+6. **字符限制**：portrait_prompt 超 2000 字符返回 400 错误
|
|
|
|
|
+7. **权限**：普通用户不能编辑他人 portrait；管理员可以
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 七、边界与注意事项
|
|
|
|
|
+
|
|
|
|
|
+- **多轮对话上下文**：画像段在每轮 `generate_answer` 中重新组装（非持久化到 State），确保每次对话都能反映最新画像
|
|
|
|
|
+- **性能**：画像数据缓存 TTL 较长（600s/900s），高频对话不会反复拉 Java
|
|
|
|
|
+- **与其他 SystemMessage 的位置关系**：画像段位于人格 prompt 之后、背景信息之前——保证 LLM 先理解人设，再理解具体用户，最后理解对话上下文
|
|
|
|
|
+- **与 mascot 注入的关系**：mascot（浠宝/福宝）是人格标识，portrait_prompt 是用户侧个性化数据，二者正交；均注入 SystemMessage
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+**文档版本**：v1
|
|
|
|
|
+**编写者**：Sisyphus（AI Agent）
|
|
|
|
|
+**审查状态**：待用户确认后进入 writing-plans 阶段
|
iwt