mindfulness/spec_kit/User Profile Scoring/spec.md

User Profile Scoring（高层规范）

1. 背景与目标

本模块用于将 Onboarding 问卷答案转换为标准化、可计算、可版本化的用户画像（User Profile），供其他模块（个性化推荐 / Push 推送排序 / 内容过滤）统一调用。

该模块的设计原则：

• 不做心理诊断：只描述「此刻允许被如何对待」
• 区分 身份（离散） 与 状态（连续）
• 允许「通用」与「高个性化」内容并存，并通过置信度控制“个性化力度”

来源规则文档：设计说明文档/客戶端問卷打分規則.md（V1 / V1.1 工程补充）

2. 模块定位与边界

2.1 负责（In Scope）

• 定义统一画像结构（字段、类型、取值范围）
• 定义从问卷答案到画像的映射规则（V1）
• 生成画像的元信息（V1.1：版本、来源、生成时间、置信度）
• 提供最小可复用的“硬规则”输出（用于下游模块做禁推/降风险）

2.2 不负责（Out of Scope）

• 不负责具体推荐算法实现（相似度计算、排序、探索/利用策略等）
• 不负责内容标签的生成与管理（内容画像 Cᵢ 的维护属于内容/推荐模块）
• 不负责长期行为信号融合（行为修正可在后续版本扩展）

3. 关键概念

• 用户画像 U：由问卷生成，描述用户阶段、状态与当下需求
• 内容画像 Cᵢ：内容侧标签/强度（由内容模块维护）
• 置信度 conf_U：画像可靠程度（用于推送等高风险场景的降个性化/降风险）

4. 输入与输出（对外接口）

4.1 输入（问卷答案）

V1 假设每题为单选：

• mom_stage：expecting | parenting | unknown
• emotion：low | overwhelmed | tired | neutral | calm | joyful
• context：family | work | relationship | friends | health
• need：emotional_support | parenting_pressure | self_worth | anxiety_relief | rest_balance

说明：多选 context/need 可在后续版本扩展，但 V1 输出结构需保持可兼容升级。

4.2 输出（用户画像）

输出为一个 JSON 对象（或等价的 TypeScript 类型），包含：

• 元信息（V1.1）
  • profile_version: string（如 "v1.1"）
  • profile_source: "questionnaire"（后续可扩展 "behavior" / "mixed"）
  • profile_generated_at: string（ISO8601 时间戳）
  • profile_confidence: number（0–1）
• 四个维度（V1）
  • stage: one-hot
  • emotion_score: number（0–1）
  • context: one-hot
  • need: one-hot

推荐的最小输出示例（结构示意）：

{
  "profile_version": "v1.1",
  "profile_source": "questionnaire",
  "profile_generated_at": "2026-01-30T00:00:00Z",
  "profile_confidence": 1.0,
  "stage": { "expecting": 0, "parenting": 1, "unknown": 0 },
  "emotion_score": 0.4,
  "context": { "work": 1 },
  "need": { "rest_balance": 1 }
}

5. 画像字段定义（V1）

5.1 mom_stage（母职阶段，离散）

映射（one-hot）：

• Pregnant / Preparing → stage.expecting = 1
• Parenting → stage.parenting = 1
• Prefer not to say → stage.unknown = 1

语义约束：

• unknown 的语义是：不希望被母职身份定义（不是“没有孩子”）

5.2 emotion（当下情绪，连续 0–1）

该分数不是“快乐程度”，而是可承受刺激与吸收内容的能力。分数越低越需要减压、陪伴、允许停下；分数越高才适合庆祝、提醒珍惜等高能量调性内容。

映射（固定离散值）：

选项	tag	emotion_score
Low	emotion: low	0.0
Overwhelmed	emotion: overwhelmed	0.2
Tired	emotion: tired	0.4
Okay	emotion: neutral	0.6
Calm	emotion: calm	0.8
Joyful	emotion: joyful	1.0

输出：emotion_score ∈ [0,1]

5.3 context（影响来源，离散）

映射（one-hot）：

• Family → context.family = 1
• Work or study → context.work = 1
• Relationship → context.relationship = 1
• Friends → context.friends = 1
• Health → context.health = 1

语义说明：

• context 不是情绪，而是情绪的“触发场景”
• 用于提升内容共感（语境命中），而非硬性过滤

5.4 need（最需要的支持，离散，推荐权重最高）

映射（one-hot）：

• Emotional support → need.emotional_support = 1
• Parenting pressure → need.parenting_pressure = 1
• Self-worth → need.self_worth = 1
• Anxiety relief → need.anxiety_relief = 1
• Rest & balance → need.rest_balance = 1

语义说明：

• need 是推荐权重最高的维度
• 表示“她现在最缺的是哪一种心理资源”

6. 元信息与置信度（V1.1）

6.1 profile_version / source / generated_at

• profile_version：用于规则升级与兼容（建议从 "v1.1" 起步）
• profile_source：固定为 "questionnaire"（后续可扩展）
• profile_generated_at：画像生成时间（用于推送降风险）

6.2 profile_confidence（conf_U）

默认规则（可配置参数）：

• 问卷刚完成：conf_U = 1.0
• 随时间衰减（避免用过期状态强个性化推送）：
  • 0–7 天：conf_U = 1.0
  • 7–30 天：线性衰减到 0.7
  • 30 天以上：conf_U = 0.5（除非用户重新做问卷或有行为信号更新）

下游使用建议：

• Push 推送等高风险场景：当 conf_U 低时，应启用不确定性惩罚（例如 P_uncertainty）并限制个性化力度上限。

7. 跨维度硬规则（Hard Rules）输出

本模块应向下游暴露“可直接执行”的硬规则结果（例如 forbidden_tags 或 content_tone_blacklist），以保证在任何排序之前先做安全过滤。

V1 核心禁推规则：

1. stage.unknown = 1
   • 禁推：强指向育儿压力的内容（need: parenting_pressure）
2. stage.parenting = 1
   • 禁推：明确怀孕 / 孕期 / 胎动等内容
3. emotion_score ≤ 0.2（low / overwhelmed）
   • 禁推：高能量庆祝型（joyful 调性）内容

原则说明：

• 这些不是“答案不准”，而是“会造成反感或退出”的高风险匹配，应始终优先执行。

8. 兼容性与演进策略

• 向后兼容：新版本字段可新增，但不得破坏 V1 的四维度结构与含义
• 多选扩展：后续允许 context/need 多选时，输出仍可保持 one-hot，但可允许多个 key=1（并提供归一化规则）
• 行为融合：后续可引入 profile_source=mixed，将行为信号用于修正 emotion_score 或补全缺失维度，但必须保留 questionnaire 原始画像以便可观测与回溯

9. 验收标准（模块级）

• Onboarding 填写完成后，能够生成符合本规范的用户画像对象
• 输出包含元信息（版本、来源、时间、置信度）与四维度字段
• 硬规则输出可被推荐/推送模块直接用于过滤（先过滤、后打分）