文档状态:现状(核对日期 2026-08-13) | 产品端:原生 iOS,Web 为线上兼容端

1. 需求概述

1.1 模块定位

「今日」是登录与游客都可使用的每日首页,按固定顺序回答四个问题:

1. 今天整体状态怎样(身体恢复信号与当日运动事实);
2. 今天有哪些已确认的安排(正在吃的补剂与当日打卡);
3. 现在能做什么(今日行动);
4. 当前计划里有什么需要进一步核对(计划核对)。

它不是资料库首页,也不负责用推荐把计划填满;推荐内容只作为"可以考虑"的候选信息呈现,必须经用户确认后才进入当前计划。

1.2 用户价值

• 用户打开即知道今天的状态、要吃的补剂和可以做的事,减少"该吃什么、该不该动"的决策负担。
• 打卡闭环让执行可记录、可在周计划回看,为长期习惯提供依据。
• 计划核对帮助用户发现剂量缺失、时间未说明、用药间隔等需要自己核对的事项,但绝不自动修改计划。

1.3 范围与边界

• 范围:今日状态卡(五状态)、今日运动参考事实区、近 28 天明细、正在吃的补剂(三态)、今日打卡、今天记得做什么、可进一步了解、通知跳转与高亮。
• 边界:
  • 本页所有运动与健康内容是基于个人趋势的产品提示,不是诊断、训练负荷评分或恢复分数。
  • 运动数据(训练、圆环、步数、距离)只能回显事实与调整本卡的一条即时建议,不能自动新增、停用、改量或改周期补剂计划。
  • "今天记得做什么"与"可进一步了解"在 iOS 展示;Web 为线上兼容端,不展示这两个区块(见 3.10)。

2. 用户与使用场景

3. 功能需求

3.1 今日状态卡与五状态

入口:今日页首屏,日期与时段问候之下第一张卡。整卡可点按。

主流程:卡片展示「今日状态」标题、状态标题、解释文案、一个可执行下一步(推荐语)和已读取到的指标摘要;点按进入明细(未连接状态进入健康数据来源页)。

五状态(卡片文案为示例,括号内为产品含义):

交互:卡片按压有缩放反馈;状态变化时卡片内容平滑过渡。推荐语前有标签:「今天可以」(稳定/留意/放慢)、「接下来」(数据不足)、「下一步」(未连接)。

状态(页面状态表见第 6 章):

• 无 Apple 健康:显示连接入口,不显示任何指标。
• 有部分数据:只显示读到的指标,缺失项不写成异常。
• 状态插图:五种状态共用同一组三色元气体(珊瑚/草本/琥珀),插图只帮助快速识别,不替代标题、原因与下一步文字;状态文本由确定性规则完整表达。

3.2 两层规则(恢复状态层 / 当日活动层)

今日状态采用两层规则,分别回答"今天恢复得怎样"与"今天动了多少":

1. 恢复状态层(决定状态等级):只由睡眠时长、睡眠时段(中点偏移)、静息心率、HRV 相对个人基线判断。
   • 基线窗口:近 28 天(不含今天),至少 7 个有效睡眠日;不足则进入"信息不够"。
   • 触发放慢:睡眠 < 5 小时,或偏离信号 ≥ 2 项。
   • 触发留意:仅 1 项偏离(睡少、作息偏、静息心率偏高、HRV 低于基线 80%)。
   • 一次训练、活动圆环分钟、步数或距离都不能单独把状态改好或改差,也不能覆盖已有恢复提示。
2. 当日活动层(只影响事实区与参考建议,不影响等级):只读取本机"今天"的结构化摘要,在卡片下方"今日运动参考"事实区回显训练、活动圆环、步数和步行/跑步距离,并用训练记录或活动圆环记录调整同一张卡片的参考建议。昨天及更早的运动不进入今天的事实区和建议。

3.3 今日运动参考(事实区)

入口:今日状态卡内、指标下方,仅在今天读到正值数据时出现(有训练、活动圆环分钟、步数或步行/跑步距离之一)。

呈现:

• 一次且只有一个训练类别:「类别 + 时长」(如"力量训练 32 分钟")。
• 多次训练:「N 次训练 · 总时长 · 最多两个主要类别」。
• 独立指标:活动圆环分钟、步数、步行/跑步距离(最多三项,按读取到的展示)。
• 训练时长与活动圆环分钟同时存在时,明确说明"分别记录,不相加"。

建议优先级(按恢复风险):

• 已有训练或活动圆环记录 + 稳定状态:按原计划,训练后留出放松时间。
• 已有训练或活动圆环记录 + 留意/放慢:先保留休息、作息与不再追加高强度活动的提示。
• 数据不足:只给保守的休息与继续佩戴建议,不据此判断"恢复良好"。
• 没有读到训练或圆环记录:沿用原建议,不能反推"今天没有运动"。

步数或距离只是移动事实,不能被当作已完成训练,本身不改变参考建议。恢复状态的解释与指标只讲恢复信号,不把运动事实混入其中。

边界:这些建议由本机确定性规则生成,不需要开启账号摘要同步。

3.4 今日状态明细(近 28 天)

入口:状态卡点按(未连接除外)。

内容:

• 顶部:当前状态标题、解释、推荐语,并注明"这是基于个人趋势的产品提示,不是诊断或恢复分数"。
• 近 28 天逐日:恢复指标(睡眠、静息心率、HRV)与日常活动(步数、运动分钟、活动能量)分开呈现。
• 近期运动:只列有训练记录或步行/跑步距离的天,展示训练次数、总时长、类别及类别时长,并注明"运动分钟与训练时长是两种不同记录,不会相加;没有记录也不代表当天没有运动"。
• 底部:管理健康数据来源入口。

3.5 正在吃的补剂(三态)

入口:今日页固定区块,标题随状态变化。

状态一:未确认过当前计划。显示两个互斥选择:

• 「添加我正在吃的补剂」→ 打开计划管理。
• 「我目前没有在吃」→ 把空计划保存为已确认状态。

状态二:已确认空计划。显示"目前没有在吃补剂"与一句解释,只保留一个就近的「添加记录」入口。

状态三:已有计划:

• 标题右侧显示「管理」,打开计划管理。
• 只把今天按计划应到期的项目放入可打卡列表(显示补剂名、剂量、时段、可选提醒时间,以及待完成/已完成状态)。
• 今天无需服用的项目默认折叠,展开后只能查看(显示"无需服用"),不能误打卡。
• 有计划但今天没有任何到期项:显示"今天没有安排的补剂"。

3.6 今日打卡

入口:今日到期项的整行。

主流程:点按到期行,在「待完成」与「已完成」之间切换(已完成行有删除线与对勾)。

交互与状态:

• 登录账号:切换后按「对应计划项 + 当天日期」保存到账号,保存成功后刷新今日与周计划。
• 写入失败:撤销本次界面变化,并记录页面错误状态。
• 游客:只更新本机显示,不产生账号级日期打卡记录。
• 「跳过」:iOS 今日页不提供,统一在周计划中操作(Web 兼容端今日提供"今天跳过",见 3.10)。

3.7 今天记得做什么(服务端行动 + 本地回退)

入口:今日页固定区块,只在存在具体行动时显示。

内容来源(优先级):

1. 服务端确定性行动:根据用户已确认的今日事件(如睡得不好、今天训练、漏餐、饮酒、肠胃不适、压力大、身体不适等)生成可执行的行动卡(食物、补水、作息、安全、计划提醒等类别),最多 6 条;iOS 全量展示。
2. 本地回退:服务端没有行动时,iOS 根据首次画像的明确答案提供有限本地回退,最多 3 条,只覆盖可直接执行的生活方式行动,例如睡前 8 小时停咖啡因、下一餐主食/蛋白质/蔬菜组合、快走或户外时间。

与状态卡的分工:今日状态卡的运动参考建议只在本机根据恢复状态与当日训练/圆环生成一条即时提示,不进入「今天记得做什么」的行动列表;本区继续展示既有的今日事件与画像行动。若当天已读到训练或活动圆环记录,本地画像回退不再重复催促"快走";低户外时长对应的"白天到户外"仍可独立保留。

边界:一次睡差或一次训练不能在这里自动新增、停用或加量补剂。所有行动都标注"仅今天,不会改动长期画像或周期计划"。

3.8 可进一步了解

入口:今日页末位区块,只在存在核对内容时显示,最多 3 条。

规则:

• 只针对仍在当前计划中的对应计划项生成核对项,绝不推荐新的补剂。
• 优先级:安全 > 剂量 > 时间 > 依据/复查。
• 安全类:用药间隔核对(甲状腺药物间隔、铁与钙/镁间隔、膳食纤维错开等)。
• 剂量类:剂量缺失、"按产品标签"、鱼油未记录 EPA/DHA。
• 时间类:时间或频次未说明,无法生成准确提醒。
• 依据/复查类:维 D 检测、铁剂复查、鱼油依据等。

交互:动作指向计划项时打开该记录的编辑页;其他情况打开补剂详情。它是核对入口,不是自动修改。

3.9 提醒跳转

入口:补剂提醒的系统通知(本地通知)。

主流程:点按通知 → 写入待跳转计划项 → 切换今日 Tab、关闭其他已打开的界面、高亮对应计划项(冷启动时从本机待跳转记录恢复高亮)。

规则:通知按"提醒时点 × 星期"创建;同一时点多条记录合并为一条通知;全 App 最多 8 个不同提醒时点;锁屏默认只显示通用文案,用户可在「我的 → 提醒」选择是否在通知中显示补剂名称。

3.10 Web 兼容端差异

• 不展示:今日状态卡(含运动事实区)、今天记得做什么、可进一步了解、近 28 天明细。
• 常驻「管理计划」按钮(即使空计划),与 iOS 只在有计划时显示"管理"不同。
• 打卡按钮仅登录可见,提供「记录完成 / 今天跳过 / 已完成·撤销 / 已跳过·撤销」;游客只能查看。
• 展示「可以考虑 · 尚未加入」建议区(查看依据 / 核对后加入计划),iOS 今日不展示建议区。
• 页面文案与数据与 iOS 同源,计划与打卡数据一致。

4. 业务规则

5. 数据与状态

5.1 全局对象

5.2 跨页刷新

6. 异常与边界

7. 关联模块

8. 验收要点(现状基线)

以下为当前实现已验证到位的现状基线,任何改动不得破坏:

1. 五状态与两层规则:一次训练/圆环/步数/距离不改变状态等级;训练或圆环只调整本卡建议。
2. 事实区口径:训练时长与圆环分钟不相加;步数/距离不是训练;昨天的运动不进今天;缺失不写成"没有运动"。
3. 打卡闭环:登录按「计划项 + 日期」保存并刷新今日与周计划;游客仅本机;失败撤销本次变化且不显示假成功。
4. 补剂三态:未确认 → 两个互斥选择;已确认空计划 → 单入口;有计划 → 管理 + 到期打卡 + 今日无安排空态。
5. 今日行动:服务端事件行动优先,本地回退有限且与状态卡建议分工明确(不重复快走、保留日间户外)。
6. 计划核对:只针对当前计划、安全优先、最多 3 条、进入编辑/详情而非自动修改。
7. 提醒:同一时点合并、最多 8 个时点、通知点开回到今日并高亮。
8. 跨页刷新:打卡、计划编辑、问元气确认修改后今日与周计划一致;回到前台重新核对提醒与健康数据。
9. 未初始化账号不展示演示计划;登录账号不回退本地缓存。

9. 迭代记录

本节保留「今日功能迭代记录」的有效结论(该文件保持原样,不在此重复全文)。

9.1 当前状态

已实现待验收。今日功能从补剂任务列表升级为连续的每日入口:身体状态 → 今日行动 → 补剂执行 → 进一步核对。

9.2 已进入实现的能力

• Apple 健康只读睡眠、步数、运动记录、Apple 活动圆环运动分钟、步行与跑步距离、活动能量、静息心率和 HRV。
• 运动记录在本机按日汇总为训练次数、训练总时长、训练类别及类别时长;原始训练、轨迹和逐笔样本不上传。
• 本机合并每日摘要,使用近 28 天个人基线生成可解释状态。
• 今日状态覆盖稳定、留意、放慢、数据不足和尚未连接;状态卡采用两层规则,运动本身不改变等级。
• 卡片新增"今日运动参考"事实区:训练次数、时长和类别与活动圆环分钟、步数、步行/跑步距离分开回显;只读今天摘要,训练时长与活动圆环分钟不相加。
• 本地事实回显和参考建议不依赖账号摘要同步;步数或距离只作为事实,不当作已完成训练,也不改变建议。
• 当天已有训练或活动圆环记录时,本地画像回退不再重复展示快走行动;户外时间不足对应的日间户外建议保持独立。
• 当前补剂、今日安排、打卡、提醒和进一步了解都以同一「计划项」为纽带。
• 本地补剂提醒支持按需申请权限、同时间合并、八个时点上限和通知回到今日。
• 计划核对只针对当前已确认计划,安全核对优先。
• 登录账号的结构化健康摘要同步默认关闭;用户按账号明确开启后,才加密同步最近 35 天摘要。切换账号不沿用上一账号的选择。

9.3 仍未完成的验收

• 使用真实 Apple Watch 隔夜数据验证跨午夜睡眠合并和多来源去重。
• 使用 Apple Watch、iPhone 或其他已授权来源的真实训练,验证运动权限升级、按开始日期归日、训练类别、时长、步行/跑步距离以及多来源同时存在时的结果。
• 验证只有活动圆环运动分钟、只有训练记录、两者同时存在和两者都缺失;两种分钟不得相加,缺失不得写成"没有运动"。
• 在真实 iPhone 完成或读取一条当天训练后返回前台,验证今日状态卡、今日运动事实区与近期运动明细同时刷新且内容一致;真机实际运动尚未验收。
• 在稳定、留意、放慢和信息不足四种恢复状态下,分别走查有训练、只有活动圆环、只有步数/距离、昨天才有运动和全部缺失,确认恢复提示优先且不会误导追加运动。
• 验证账号摘要同步默认关闭、同意按账号与版本隔离、切换账号不继承开关,以及关闭同步与删除云端摘要的差异。
• 验证停止读取、删除本机摘要、删除云端摘要和再次连接的完整恢复路径。
• 在真机验证通知授权、合并通知、锁屏隐私、点按跳转和账号切换后的重建。
• 在真实 iPhone、320×568 和 VoiceOver 下完成今日首屏走查,覆盖长训练类别、多次训练与三项活动指标;本轮已完成 iPhone 17e 的浅色、深色和辅助功能超大字体渲染核对。
• 今日打卡失败目前会撤销状态,但页面尚未就近展示错误和重试入口。

未完成以上验收前,本轮不能标为 已上线。

9.4 当前有效决策

• 今日状态是可解释的产品提示,不是医学诊断或恢复百分比。
• 缺失、部分或过期数据不能被表现成健康异常。
• 两层规则:恢复状态仍由睡眠、睡眠时段、静息心率和 HRV 判断;只有当天训练记录或活动圆环记录可以调整卡片内的本地参考建议,不能改变状态等级或覆盖恢复提示。
• 今日运动事实区只使用当天摘要;训练次数、总时长、类别、活动圆环分钟、步数和步行/跑步距离分口径展示;步数或距离不等于训练,昨天的运动不进入今天建议。
• Apple 活动圆环运动分钟和训练记录时长分别呈现,不相加;没有训练记录不等于没有运动。
• 本地回显和参考建议不要求开启云同步;云同步仍默认关闭并按账号显式同意,只影响账号摘要与问元气可用范围。
• 今日状态与运动参考只能调整本卡的一条即时提示,不能自动新增、停用、改量或改周期补剂,也不把运动摘要写成计划任务。
• 今日最多展示三项具体行动(注:当前服务端事件行动上限为 6 条,与"最多三项"的旧表述存在出入,是否收紧待确认);没有足够依据时减少数量。
• 新补剂探索只在资料库;今日的"可进一步了解"只服务于当前计划。
• 当前正式产品不使用人物或情绪插画;重新启动插画方向时必须作为独立视觉课题评审。
• 2026-08-13 已确认重新启动"今日状态元气体"视觉课题:只把三块品牌形体作为状态卡内容插图,不引入人物情绪,不替代品牌 Logo;状态仍由文字和确定性规则完整表达。

9.5 已验证证据(摘要)

• 2026-08-12 服务端相关测试 6 项通过(加密摘要保存/读取/导出/删除/字段一致性/旧摘要兼容)。
• 2026-08-11 历史记录:37 项 iOS 测试(模拟器);2026-08-12 本轮 47 项;2026-08-13 运动感知今日状态领域 9 项 + 全量 56 项、57 项、49 项等,分别覆盖运动不改变恢复等级、建议优先级、步数不冒充训练、昨天运动不进今天建议、数据不足保守建议、缺失不写"没有运动"、已有训练不重复快走、五态元气体视觉与无障碍降级等。
• 已有多台设备(配对 iPhone 15 Pro)的真机构建、无线覆盖安装与启动证据(Apple 健康数据权限与签名有效);该证据确认发布链路,不替代真机运动权限、真实训练数据与 VoiceOver 的逐项验收。
• 完整证据清单以《今日功能迭代记录》为准。

最近更新：2026-08-13 <br>当前状态：已实现待验收

本文只保留“今日”功能的当前实施范围、未完成验收和有效产品决策。完整现状逻辑见今日产品逻辑，视觉要求见视觉设计规范，交互验收见交互规范。

1. 本轮目标

把今日从补剂任务列表升级为连续的每日入口：

身体状态 → 今日行动 → 补剂执行 → 进一步核对

用户打开页面后依次看见：

1. 日期与问候。
2. 今日状态。
3. 正在吃的补剂。
4. 今天记得做什么。
5. 可进一步了解。

2. 已进入实现的能力

• Apple 健康只读睡眠、步数、运动记录、Apple 活动圆环运动分钟、步行与跑步距离、活动能量、静息心率和 HRV。
• 运动记录在本机按日汇总为训练次数、训练总时长、训练类别及类别时长；原始训练、轨迹和逐笔样本不上传。
• 本机合并每日摘要，使用近 28 天个人基线生成可解释状态。
• 今日状态覆盖稳定、留意、放慢、数据不足和尚未连接。
• 今日状态卡已经采用两层规则：恢复等级仍由睡眠、睡眠时段、静息心率和 HRV 决定；本机只用当天训练记录或活动圆环记录调整参考建议，运动本身不改变等级。
• 卡片新增“今日运动参考”事实区：训练次数、时长和类别与活动圆环分钟、步数、步行/跑步距离分开回显；只读今天的摘要，训练时长与活动圆环分钟不相加。
• 本地事实回显和参考建议不依赖账号摘要同步；步数或距离只作为事实，不当作已完成训练，也不改变建议。
• 当天已有训练或活动圆环记录时，本地画像回退不再重复展示快走行动；户外时间不足对应的日间户外建议保持独立。
• 当前补剂、今日安排、打卡、提醒和进一步了解共享同一个计划项标识。
• 本地补剂提醒支持按需申请权限、同时间合并、八个时点上限和通知回到今日。
• “可进一步了解”区只针对当前已确认计划，安全核对优先。
• 登录账号的结构化健康摘要同步默认关闭；用户按账号明确开启后，才按摘要规则版本加密同步最近 35 天摘要。切换账号不沿用上一账号的选择。

3. 仍未完成的验收

• 使用真实 Apple Watch 隔夜数据验证跨午夜睡眠合并和多来源去重。
• 使用 Apple Watch、iPhone 或其他已授权来源的真实训练，验证运动权限升级、按开始日期归日、训练类别、时长、步行/跑步距离以及多来源同时存在时的结果。
• 验证只有活动圆环运动分钟、只有训练记录、两者同时存在和两者都缺失；两种分钟不得相加，缺失不得写成“没有运动”。
• 在真实 iPhone 完成或读取一条当天训练后返回前台，验证今日状态卡、今日运动事实区与近期运动明细同时刷新且内容一致；真机实际运动尚未验收。
• 在稳定、留意、放慢和信息不足四种恢复状态下，分别走查有训练、只有活动圆环、只有步数/距离、昨天才有运动和全部缺失，确认恢复提示优先且不会误导追加运动。
• 验证账号摘要同步默认关闭、同意按账号与版本隔离、切换账号不继承开关，以及关闭同步与删除云端摘要的差异。
• 验证停止读取、删除本机摘要、删除云端摘要和再次连接的完整恢复路径。
• 在真机验证通知授权、合并通知、锁屏隐私、点按跳转和账号切换后的重建。
• 在真实 iPhone、320×568 和 VoiceOver 下完成今日首屏走查，覆盖长训练类别、多次训练与三项活动指标；本轮已完成 iPhone 17e 的浅色、深色和辅助功能超大字体渲染核对。
• 今日打卡失败目前会回滚状态，但页面尚未就近展示错误和重试入口。

未完成以上验收前，本轮不能标为 已上线。

4. 当前有效决策

• 今日状态是可解释的产品提示，不是医学诊断或恢复百分比。
• 缺失、部分或过期数据不能被表现成健康异常。
• 当前采用两层规则：恢复状态仍由睡眠、睡眠时段、静息心率和 HRV 判断；只有当天训练记录或活动圆环记录可以调整卡片内的本地参考建议，不能改变状态等级或覆盖恢复提示。
• 今日运动事实区只使用当天摘要。训练次数、总时长、类别、活动圆环分钟、步数和步行/跑步距离分口径展示；步数或距离不等于训练，昨天的运动不进入今天建议。
• Apple 活动圆环运动分钟和训练记录时长分别呈现，不相加；没有训练记录不等于没有运动。
• 本地回显和参考建议不要求开启云同步。云同步仍默认关闭并按账号显式同意，只影响账号摘要与 Agent 可用范围。
• 今日状态与运动参考只能调整本卡的一条即时提示，不能自动新增、停用、改量或改周期补剂，也不把运动摘要写成计划任务。
• 今日最多展示三项具体行动；没有足够依据时减少数量。
• 新补剂探索只在资料库；今日的“可进一步了解”只服务于当前计划。
• 当前正式产品不使用人物或情绪插画；重新启动插画方向时必须作为独立视觉课题评审。
• 2026-08-13 已确认重新启动“今日状态元气体”视觉课题：只把三块品牌形体作为状态卡内容插图，不引入人物情绪，不替代品牌 Logo；状态仍由文字和确定性规则完整表达。

5. 已验证证据

• 2026-08-12 本轮服务端相关测试 6 项通过，覆盖带运动字段的加密摘要保存、读取、导出、删除、字段一致性校验和旧摘要兼容。
• iOS 工程已经包含 Apple 健康读取能力、通知服务和相关页面。
• 2026-08-11 的历史记录显示：37 项 iOS 测试在 iPhone 17 Pro 模拟器通过；随后另行完成配对 iPhone 15 Pro 的真机构建、覆盖安装和启动。两者是独立证据，不能把模拟器测试写成真机测试。
• 2026-08-12 本轮 iOS 自动测试共 47 项通过，覆盖运动摘要聚合与分类、旧摘要兼容、账号级显式同步同意以及周计划安排数据。
• 已在独立的 iPhone 17e 模拟器核对 Apple 健康数据源页面：运动记录、活动圆环运动分钟、步行与跑步距离等读取范围可见，账号摘要同步初始为关闭。模拟器不能替代真实 Apple 健康运动权限与 Apple Watch / iPhone 训练数据验收。
• 2026-08-13 已完成配对 iPhone 15 Pro 的真机构建、覆盖安装和启动，Apple 健康权限配置与开发签名均通过；尚未据此标记运动授权、真实训练记录或多来源结果为已验收。
• 2026-08-13 今日状态卡已实现五种可缩放元气体、浅深色适配、动态字体纵向重排、降低透明度降级、无需颜色区分的形体描边，以及 iOS 26 详情控件 Liquid Glass；iPhone 17e 模拟器已逐一渲染五种状态，并核对深色模式与辅助功能超大字体布局；本轮 47 项 iOS 测试通过。尚未完成真机触控、提高对比度与最大动态字体的最终验收。
• 2026-08-13 继续细化五态组件：补齐 48 pt 紧凑变体、44 pt 详情触控范围、辅助功能大字纵向重排、卡片按压反馈、降低透明度的实体色降级，并把每种状态的最大块、展开距离、层级和轮廓定义为可测试视觉签名。已在 iPhone 17e 模拟器逐一核对五态总览、深色高对比、最大辅助功能字号，以及降低透明度、无需颜色区分和降低动态效果组合；本轮 49 项 iOS 测试全部通过。
• 2026-08-13 本轮五态状态卡已完成配对 iPhone 15 Pro（iOS 27.0 Beta）的真机签名构建、无线覆盖安装和启动。初次局域网安装因开发连接服务占用失败，重建连接后设备连续保持在线，应用安装成功、启动成功，并已在设备进程列表确认应用正在运行。此证据确认签名、无线发布和启动链路，不替代五种状态的真机逐一视觉与触控验收。
• 2026-08-13 运动感知今日状态领域相关 9 项测试通过，覆盖运动不改变恢复等级、训练/活动圆环的建议优先级、步数或距离不冒充训练、昨天运动不进入今天建议、数据不足时使用保守建议，以及缺失不写成“没有运动”；同次 iOS 全量 56 项测试通过。
• 2026-08-13 在最终“今日运动参考”UI 与行动去冲突规则完成后，iPhone 17e 模拟器全量 57 项测试通过、0 失败、0 跳过；新增用例确认当天已有训练时不再重复展示快走，同时保留独立的日间户外建议。
• 2026-08-13 已在 iPhone 17e 模拟器实际渲染最终运动事实区，核对浅色、深色和辅助功能超大字体下的训练摘要、活动圆环、步数、距离及“不相加”说明。当前仍无真机实际运动和 VoiceOver 完整走查证据。
• 2026-08-13 最终代码已完成真机签名构建，Apple 健康权限配置、开发证书和描述文件均有效，构建成功。首次覆盖安装时设备连接服务异常，恢复连接后已完成安装与启动；过程中的首次离线状态已保留作验收记录。
• 2026-08-13 测试机恢复连接后，最终开发版已成功覆盖安装并启动：设备为 iPhone 15 Pro“华人牌傻妞”，未清除现有用户数据。该证据仅代表开发版真机发布与启动链路通过，真实 Apple 健康训练数据、权限变化和 VoiceOver 仍需在设备上继续走查。

这些记录证明实现链路存在，不替代本节列出的真机视觉、权限和恢复路径验收。

文档状态:现状(核对日期 2026-08-13) | 产品端:原生 iOS,Web 为线上兼容端

1. 需求概述

1.1 模块定位

「周计划」把用户已经确认的当前计划按本周七天展开,用于查看安排和补记执行情况(完成 / 跳过 / 撤销)。它以四时段 × 七天的课程表式周概览为第一视图,再进入单日打卡。

周计划只呈现用户已确认的当前计划;推荐、待确认修改、资料库内容都不是本周安排,不会出现在这张表里。

1.2 用户价值

• 一眼看清本周早、午、下午、晚四个时段的补剂安排,不再逐日回忆"今天该吃什么"。
• 支持按"事项 + 日期"补记执行情况(完成 / 跳过 / 撤销),与今日打卡共用同一份数据。
• 提供应完成 / 已完成 / 跳过的本周执行汇总,帮助用户了解执行情况;它只是执行次数,不是服从率诊断、健康评分或效果判断。

1.3 范围与边界

• 范围:本周日期范围与说明、应完成/已完成/跳过汇总、周概览/单日分段、四时段 × 七天课程表、单日打卡(完成/跳过/撤销)、未来日期边界、空态与失败重试。
• 边界:
  • 需要登录,游客不可用:游客点按周计划时先打开登录层,登录成功后自动继续进入周计划。
  • 周计划不直接编辑计划;整周为空时的「添加记录」打开统一计划管理,已有安排时从今日或提醒设置进入管理。
  • 当前只提供本周七天视图,不提供跨周历史图表。
  • 课程表是四时段概览,不按具体提醒分钟拆行,也不把一条事项复制到多个时段。
  • 「跳过」只表示该次没有执行,不自动删除长期计划,也不自动调整剂量。
  • 周复盘(健康模型域的生活方式实验周复盘)当前不在本模块内,见 3.6。

2. 用户与使用场景

3. 功能需求

3.1 进入条件与登录

入口:底部导航「周计划」Tab。

主流程:登录账号直接进入;游客点按周计划时,记录目标 Tab 并打开登录/注册界面;登录成功后自动继续进入周计划(Web 端登录成功后恢复账号数据再进入页面)。

状态与已知缺口:当前 iOS 18 以上导航层会先改变自身的 Tab 选中值,再请求登录;取消登录后没有显式恢复视觉选中项,可能造成视觉 Tab 与当前页面不一致。这是现状缺口,不是目标交互(目标交互:取消登录应回到原 Tab)。

3.2 当前信息结构

1. 本周日期范围(如 8.11 – 8.17)和说明。
2. 应完成、已完成、跳过三项汇总。
3. 「周概览 / 单日」分段选择,默认进入周概览。
4. 周概览:早、午、下午、晚四个时段 × 周一至周日七列,展示整周安排。
5. 单日视图:日期选择器、当前选中日期的计划卡片和打卡操作。

首屏与日期记忆:页面首次加载时预选今天,但仍停留在周概览;点按周概览中的日期表头或有安排的格子,会选中对应日期并切换到单日视图;也可直接用分段控件切换。刷新时优先保留原选中日期,找不到时回到今天。

无障碍:普通动态字体下,周概览是可横向滚动的课程表;进入系统超大字号后,自动改为按日期纵向排列,每一天完整列出"时段、事项、状态",不压缩成难以阅读的小格子。

3.3 周计划如何形成(数据来源)

• 数据源只取用户已确认的当前计划。
• 每条记录按计划周期决定本周哪些天出现(每日 / 工作日 / 隔日 / 周末)。
• 每条记录只属于一个时段(早晨/午间/下午/晚上),再映射到对应日期的对应时段;同一事项不会跨时段合并。
• 周概览以「时段 × 日期」的格子为准;一个格子可以有多条事项,空格只表示该日期与时段没有已确认安排。
• 时间或频次为「未说明」的仅记录项目不会伪造成日历安排(不进周表,也不生成打卡)。
• 同一「计划项」贯穿今日、周计划、提醒和打卡。

3.4 应完成统计

未来日期不计入应完成,也不显示完成/跳过按钮。汇总只统计"应该发生"的执行结果,同一"计划项 × 日期"只有一条状态,不会重复计数。

3.5 周概览与单日操作

周概览只负责理解和导航:

• 日期表头显示当天事项数量;点按后进入该日。
• 有安排的格子显示事项简称和完成状态(完成对勾 / 跳过减号);点按后进入该日。
• 空格不提供无意义的点击目标。
• 周概览不直接提供完成、跳过或撤销,避免在密集网格中误操作。

单日打卡:对今天或过去日期的每条安排,用户可以:

• 完成;已完成时再次点按为撤销完成。
• 跳过;已跳过时再次点按为撤销跳过。

状态与反馈:

• 打卡支持已完成、已跳过、撤销三种状态。
• 单次更新只禁用正在提交的"事项 + 日期",不锁住其他事项。
• 保存成功后刷新今日与周计划;失败时保留服务端真实状态,在周计划内显示可理解的错误和「重试读取」,不显示已保存结论。
• 未来日期显示"未来安排",不提供打卡操作。

3.6 周复盘(边界说明)

当前「周计划」模块只覆盖补剂安排查看与打卡。健康模型域存在独立的"生活方式实验周复盘"概念(按轨道聚合作息例程、实验状态与复盘就绪标记,支持精力/睡眠评分与保持/调整/停止决策),但它不在当前周计划页面呈现,也未与补剂周计划合并。是否在周计划页接入实验周复盘:待确认。

3.7 Web 兼容端差异

• 无「周概览 / 单日」分段:直接展示课程表,点选任意事项在底部弹出操作单完成打卡(手机端按天纵排 × 四时段列;宽屏转置为七天列 × 四时段行)。
• 汇总以文字呈现:"已完成 X / 应完成 Y · 已跳过 Z"(iOS 为三项胶囊)。
• 顶部有本周补剂图例;事项卡片可打开"查看依据卡片"。
• 未来日期选中后显示"未来安排会在当天开放记录"。
• 空态文案与 iOS 不同("这一周还没有已确认的补给" + 说明),同样提供添加记录入口。
• 数据与 iOS 同源。

4. 业务规则

5. 数据与状态

5.1 全局对象

5.2 跨页刷新

6. 异常与边界

7. 关联模块

8. 验收要点(现状基线)

以下为当前实现已验证到位的现状基线,任何改动不得破坏:

1. 登录门槛:游客不可用,登录成功后自动继续进入周计划。
2. 数据源:只取已确认当前计划;未说明时间/频次的记录不进入周表;推荐不进入安排。
3. 四时段 × 七天课程表:一个格子可多项;空格无安排;同一事项不跨时段。
4. 汇总:应完成 = 周一至今天所有已安排次数;已完成/跳过只统计应完成范围;未来不计入。
5. 打卡:三态(完成/跳过/撤销);校验登录、日期范围(今天或过去 7 天)、仍在当前计划、该日确有安排;单项更新不锁其他事项。
6. 未来日期只展示、不打卡;失败保留服务端真实状态并提供「重试读取」。
7. 保存成功后今日与周计划同步刷新;下拉刷新尽量保留选中日期。
8. 无障碍:超大字体切换为按日纵向排列,与课程表来自同一份安排数据。
9. 周概览只导航,打卡在单日(iOS);Web 兼容端为课程表 + 底部操作单。

9. 迭代记录(2026-08-12 周概览迭代)

状态:已实现待验收

9.1 已实现

• 新增「周概览 / 单日」分段,默认进入周概览。
• 周概览按四时段 × 七天显示现有安排,不改变计划数据本身。
• 点按日期表头或有安排的格子进入对应单日;概览只导航,打卡仍在单日。
• 整周空态、单日空态、读取/打卡错误重试和按"事项 + 日期"的单项更新已分别处理。
• 无障碍动态字体下改为按日纵向排列,并为日期、事项和状态提供 VoiceOver 文本。

9.2 尚未完成的验收

• 在 320×568、390×844 和真实 iPhone 上补充核对课程表横向滚动、底栏安全区与内容截断。
• 使用实际 VoiceOver 朗读、减少动态效果和降低透明度完整走查周概览到单日的焦点顺序。
• 使用真实账号补充覆盖整周为空、单日为空、一个格子多项、单项失败重试,以及完成/跳过后今日与周计划一致。

9.3 当前验证证据

• 2026-08-12 本轮 iOS 自动测试共 47 项通过,覆盖按日期组织、重复格子合并、越界日期不污染空周、跨时段计数、完整日期、未来状态和"事项 + 日期"唯一标识等回归场景。
• 已在独立的 iPhone 17e 模拟器完成一次真实渲染走查:截图导出尺寸 369×800,覆盖浅色/深色、标准字号/超大字号、课程表横向滚动、概览进入未来单日、今日完成与撤销。超大字号会按规则切换为按日纵向概览。
• 2026-08-13 已完成配对 iPhone 15 Pro 的真机构建、覆盖安装和启动;该证据确认测试包可安装运行,不替代课程表在真机尺寸下的逐项视觉与 VoiceOver 验收。
• 无障碍语义快照已核对日期、时段、事项和状态标签;实际 VoiceOver 朗读与上述未覆盖尺寸仍保留为待验收项,因此本轮不标记为 已上线。

文档状态:现状(核对日期 2026-08-13) | 产品端:原生 iOS,Web 为线上兼容端<br>本文按产品经理视角描述资料库模块当前已实现的业务逻辑与规则。匹配档位、45 项覆盖、冲突优先级等专项细节以补剂匹配规则为准;目录数据与维护规则以补剂数据库说明为准;资料时效性维护见补剂资料库自动维护方案,本文只引用不重复。

1. 需求概述

1.1 模块定位

资料库是元气中「查资料 + 个性化线索」的补剂信息模块:

• 帮助用户查找补剂资料:成分、关注方向、研究来源、适用边界与注意事项。
• 结合用户已确认的画像,展示「与你匹配」的候选条目,帮助用户判断"哪些补剂值得先进一步了解"。
• 衔接「加入当前记录」,把用户确认正在服用的补剂写进当前计划。

资料库不是处方页:匹配分和研究来源都不能直接把条目写进当前计划,只有用户主动确认的记录才会进入计划。

1.2 用户价值

1. 检索效率:搜索与「按成分 / 按关注方向」双维度分类浏览,快速定位想了解的补剂。
2. 个性化线索:基于已确认的饮食、作息、运动等画像给出匹配分,提示哪些补剂与当前情况相关。
3. 决策支持:详情展示关注方向、研究来源、适用边界与注意事项,帮助用户判断"适不适合我、使用前注意什么"。
4. 记录衔接:一键把感兴趣的补剂带入计划编辑器,填写真实剂量与时间后确认加入。

1.3 范围与边界

范围:搜索、分类浏览、匹配分展示与排序、补剂详情(成分 / 关注方向 / 研究来源 / 适用边界 / 注意事项)、加入当前记录、从资料库发起问元气、Web 兼容端资料页。

边界:

• 匹配分不是营养缺乏概率、服用后有效概率或医学推荐强度。
• 匹配分在本地按既定规则计算,不经过问元气或大模型;只有用户确认后,新信息才会更新评分所读取的画像。
• 匹配分不代表安全性;禁忌与相互作用在详情和加入记录流程中单独提示。
• 资料详情不直接调整剂量,不替代医生或药师。
• Web 为线上兼容端,结构与 iOS 不同(见 3.9),且不计算匹配值。
• 未收录名称只能作为个人记录保存,不进入自动匹配。

2. 用户与使用场景

资料库需要登录:游客不可用。游客点按资料库 Tab 时打开登录/注册层,登录成功后继续进入资料库(见 R-01)。

3. 功能需求

3.1 无搜索时的页面结构(入口:底部导航「资料库」Tab)

自上而下:

1. 「正在使用」:当前计划中已有的条目(展示剂量 · 时间)。
2. 「与你匹配」:最多 5 条满足当前阈值的候选条目,附匹配分。
3. 「浏览方式」:按成分 / 按关注方向分段切换。
4. 分类列表:当前浏览维度下的全部分类,显示目录中条目数;进入分类查看该分类下全部条目。

「正在使用」与「与你匹配」互斥去重:当前计划中同成分覆盖键(只合并同营养素/同成分形态)的条目不再出现在匹配候选中。当前仅镁的两种剂型共享覆盖键,普通共同目标不会被当作同一种补剂(R-08、R-09)。

3.2 搜索(入口:页面顶部系统搜索框)

• 主流程:输入关键词 → 本地检索 → 展示结果。
• 检索范围:中文名、英文名、目录分类(成分类型)、关注方向、别名。
• 匹配方式:忽略大小写、音调符号与分隔符差异后,按完全匹配、前缀、包含、子序列依次判断是否命中(命中判定有优先级,不对外展示)。
• 交互:搜索中命中的当前计划条目另列在「正在使用」区;其余结果按名称排序展示在「搜索结果」区。
• 状态:无结果时使用系统搜索空状态。

3.3 分类浏览(入口:3.1 的浏览方式与分类列表)

• 两种维度:按成分(维生素、矿物质、脂肪酸、氨基酸/蛋白/运动营养、益生菌/益生元/膳食纤维、草本、功能性成分等成分类型);按关注方向(日常基础、睡眠与压力、心脏与代谢、肠道与消化、骨骼与肌肉、运动与恢复、精力与认知、眼睛皮肤头发等方向)。
• 切换浏览方式会退出当前已选分类,回到新维度的分类总览。
• 每个分类显示当前目录中的条目数;进入分类后展示该分类下全部条目,并提供「查看全部分类」返回。

3.4 匹配分展示与排序(入口:「与你匹配」区)

• 匹配值由 iOS 本地按既定规则、依据已确认画像计算(R-02~R-06、R-11)。
• 「与你匹配」依次执行:合并本地与云端目录 → 排除不允许进入匹配的条目 → 排除当前计划中同成分覆盖键条目 → 保留平衡档阈值(75 分及以上,即 75 和 90)→ 按分数降序、同分按中文名称排序 → 最多展示 5 条(R-07)。
• 行内只展示最终匹配值(如「匹配 75」)或「资料不足」,不展示规则原因、命中条件或内部依据。
• 页脚说明:匹配分表示基于已记录生活状态的关注优先级;不能确认缺乏,也不等于需要服用。

3.5 补剂详情(入口:点击任意条目)

按以下顺序展示:

1. 中文名、英文名、匹配分、成分类型。
2. 关注方向。
3. 你需要知道。
4. 研究来源。
5. 是否适合你。
6. 使用前注意。
7. 添加到我的记录。

研究来源按条目读取:

• 成功:展示具体结论、来源名称与可打开链接,以及必要警示。
• 加载中:显示「正在读取依据…」。
• 失败:说明「研究来源暂时读取失败」并提供重试;不影响基础条目信息展示。
• 个人自定义记录没有研究依据卡,详情不展示研究来源(R-16)。

3.6 加入当前记录(入口:详情底部「添加到我的记录」)

• 条目已在当前计划中时,不显示加入按钮。
• 点按后先关闭详情,再打开计划编辑面板,并预选该补剂。
• 用户仍需填写或确认:实际剂量、每次数量、服用方式、时段、频次、品牌/备注,以及是否开启提醒(提醒需先有明确时间与频次)。
• 保存前显示完整预览(剂量 · 数量 · 频次 · 时段 · 服用方式),确认后(「确认加入当前计划」)才加入;编辑已有记录为「确认修改」。
• 加入成功后同步刷新今日/周计划(见第 5 章)。
• 未收录的名称只能从计划编辑器作为个人记录保存;它不是资料库自动补全出的标准成分,也没有研究依据卡(R-16)。

3.7 证据渐进披露

• 在补剂评价体系尚未完整定义前,列表和详情不展示「研究结果不一」等风险或证据等级标签。
• 研究来源与必要安全提醒仍可在用户主动打开详情时呈现(研究来源、使用前注意两节)。

3.8 从资料库发起问元气(入口:底部固定「问元气」)

• 从资料库打开问元气时,问元气知道当前在资料库,可结合当前页面理解「这个」「那个」等指代。
• 问元气最多结合 8 条当前建议来解析「这两个」等指代;名称、理由或剂量不作为问元气直接采信的事实(R-18)。

3.9 Web 兼容端差异(线上兼容端)

• 入口:Web 资料库同样要求登录。
• 结构:顶部「科学依据」区(健康生活方式依据卡片,非补剂条目)→「我确认正在吃的」→「可以考虑 · 尚未加入」→「按产品名浏览」。
• 「可以考虑」候选按云端规则初排得出,不是 iOS 的匹配分。
• 浏览:按产品分类筛选 + 搜索(名称 / 英文名 / 代码 / 别名包含匹配);无「与你匹配」、无匹配分、无按成分/关注方向双维度切换。
• 详情:使用底部抽屉展示依据卡;行内对「研究有限」条目展示「研究有限」徽标(iOS 列表不展示证据等级标签)。
• 不计算匹配值:Web 端没有五档匹配分逻辑(R-13)。

4. 业务规则

档位定义、冲突优先级、45 项覆盖与案例以补剂匹配规则为准。

• R-01 登录门槛:资料库需要登录;游客点按时打开登录/注册层,登录成功后继续进入资料库;取消登录后没有显式恢复视觉选中项是现状缺口,不是目标交互。
• R-02 五档固定值:匹配值只能是 90(明确依据)/ 75(直接相关)/ 50(间接相关)/ 25(弱相关)/ 0(暂不优先),不产生中间值;没有命中任何有效专属规则时显示「资料不足」;「0」与「资料不足」必须区分——0 是有信息后的判断,资料不足是不知道。
• R-03 匹配值语义:匹配值表示已确认的饮食、生活习惯、持续状态、用药、特殊状态或检查线索,与该项补剂专属规则的相关程度;不是营养缺乏概率、服用后有效概率、诊断/处方/自动服用建议,也不是补剂本身的通用研究评分。
• R-04 决策优先级:同一补剂命中多条规则时按 90 > 75 > 0 > 50 > 25 选中唯一结果规则,条件命中后直接映射为固定档位,不加权、不累计、不用关键词模糊打分;「0 明确暂不优先」可覆盖 50/25 类弱线索,但不能覆盖 90/75 的更强个人依据。
• R-05 条件命中方式:问卷条件按用户明确选择的选项精确命中(如鱼类摄入选择低频选项时才命中鱼油规则);组合条件支持同时满足或任一满足;用药、检查异常、特殊状态只在用户已确认的条目上匹配受控成分;不会在任意对话原文中搜索关键词加分。
• R-06 缺失不等于否定:未回答某问题不等于该信息为「0」,结果应为「资料不足」(例如没有回答鱼类摄入 ≠ 每周吃鱼 0 次 ≠ 鱼油 0 分)。
• R-07 列表阈值与排序:「与你匹配」固定使用平衡档阈值 75(仅 75 和 90 可进入);按分数降序,同分按中文名称排序;最多展示 5 条。
• R-08 同成分覆盖键只合并同形态:同成分覆盖键只有在人工确认属于同一营养素或同一成分覆盖关系时才共用;当前仅镁的两种剂型(镁、苏糖酸镁)共用同一覆盖键;仅共享关注目标的两条补剂不会被去重或替代。
• R-09 正在用某镁不再推荐另一种镁:当前计划中已有某同成分覆盖键条目时,资料库不推荐、详情不显示加入按钮、计划编辑器禁止重复加入另一种同成分覆盖键补剂。
• R-10 安全禁忌独立于分数:匹配分不表示安全性;不允许进入匹配的条目不进入匹配候选;已在当前计划中的同成分条目不重复推荐;禁忌、药物相互作用、重复成分、剂量与是否允许匹配使用独立安全门槛,不能被 90/75 抵消;详情与加入记录流程继续展示必要安全边界;低血红蛋白不等于缺铁,不触发铁剂 75/90;备孕、孕期、哺乳期、用药和明显检查异常仍需专业核对。
• R-11 匹配结果随画像更新:匹配分基于当前已确认画像计算;已确认问卷答案、画像字段(性别/检查线索/用药/特殊状态)、已确认当前目标、补剂目录或匹配规则版本任一变化后,匹配结果整体重新计算;相同输入下沿用已有结果,单纯打开页面不改变结果,也不调用大模型。
• R-12 问元气与大模型边界:问元气、DeepSeek 或其他大模型不直接决定匹配分,也不能把未确认的对话内容直接变成 90/75;问元气只能生成候选信息,用户确认后保存为画像事实,再由本地既定规则计算匹配分。
• R-13 Web 不计算匹配值:Web 兼容端没有五档匹配逻辑,「可以考虑」候选来自云端规则初排,不能把 Web 的「可以考虑」当作 iOS 匹配分。
• R-14 目录唯一源:补剂目录有唯一维护入口(当前 45 条目录、30 张完整研究依据卡);在线时 iOS 与 Web 以云端目录为准,离线时使用本机内置目录副本;目录更新后需完成校验,并同步更新本机副本。
• R-15 研究来源确定性数据:依据卡按条目确定性组装,不经过模型生成;没有完整依据卡的条目仍可出现在目录中,详情展示「研究有限」的通用资料,不得伪装成完整证据结论。
• R-16 个人记录:未收录名称只能从计划编辑器作为个人记录保存,不进入匹配候选,详情不展示研究来源;元气不会根据个人记录判断它是否适合用户或调整剂量。
• R-17 证据渐进披露:补剂评价体系尚未完整定义前,列表与详情不展示「研究结果不一」等风险或证据等级标签;研究来源与安全提醒在用户主动打开详情时呈现。
• R-18 问元气上下文:从资料库打开问元气时,问元气知道当前在资料库,最多结合 8 条当前建议理解「这个」「那个」等指代;名称、理由或剂量不作为问元气直接采信的事实。

5. 数据与状态

5.1 主要对象

5.2 跨页刷新

• 加入/修改/删除当前记录后:同步刷新今日与周计划(同一组已确认计划);计划变化同时触发提醒重排(见「我的」PRD R-13)。
• 问元气确认修改后:刷新计划、今日、周计划与健康模型;资料库「正在使用」与「与你匹配」的排除状态随之更新;画像变化后匹配结果重新计算。
• 目录或规则版本更新后:下一次读取匹配值时重新计算。

6. 异常与边界

7. 关联模块

8. 验收要点(现状基线)

以下为当前已实现且已核对的行为,作为回归验收基线:

1. 游客点按资料库 → 打开登录层;登录成功进入资料库。
2. 无搜索时页面包含:正在使用、与你匹配、浏览方式、分类列表四部分。
3. 与你匹配:排除不允许进入匹配与计划内同成分覆盖键条目;仅保留 75/90;分数降序、同分按名称;最多 5 条。
4. 搜索覆盖名称/英文名/分类/关注方向/别名,支持忽略大小写、音调与分隔符差异;结果按名称展示。
5. 详情按 名称/匹配分/成分类型 → 关注方向 → 你需要知道 → 研究来源 → 是否适合你 → 使用前注意 → 添加到我的记录 顺序展示。
6. 研究来源:成功/加载/失败重试三态;个人记录不展示研究来源。
7. 已在计划中的条目不显示加入按钮;加入走 计划编辑器预选 → 填表 → 预览 → 确认。
8. 列表与详情不展示「研究结果不一」等风险或证据等级标签。
9. 45 项规则集中,19 项无有效规则时显示「资料不足」;25 档已设计但暂不启用。
10. Web 兼容端:不计算匹配值;分区为 我确认正在吃的 / 可以考虑·尚未加入 / 按产品名浏览。

9. 迭代记录

• 2026-08-12:五档固定匹配规则落地(五档固定值、条件命中、决策优先级、45 项覆盖);补剂目录 45 条、30 张完整研究依据卡;本模块产品逻辑与补剂匹配规则、补剂数据库说明核对完成。
• 2026-08-13:二次核对(目录唯一源、研究来源三态、加入记录流程、Web 兼容端差异)。

未验收项 / 已知缺口:

• 游客取消登录后,iOS 18+ 导航层视觉 Tab 未显式恢复,可能造成视觉选中项与实际当前页面不一致(现状缺口,不是目标交互)。
• 25 档匹配分已设计,但「当前目标」仍是自由文本、没有结构化目标字段,当前不使用关键词把自由文本目标转成 25 分。
• 45 项中 19 项规则集为空(维生素 B 族、硒、维生素 E、维生素 K2、复合维生素、奶蓟草、蔓越莓、苏糖酸镁、NMN、亚精胺、阿克曼菌、PQQ、磷脂酰丝氨酸、R-α-硫辛酸、麦角硫因 + 谷胱甘肽、甜菜碱(TMG)、槲皮素、大豆异黄酮、牡蛎提取物);除非后续同时增加专属输入、受审核规则和回归验证,不得显示个性化数值。
• 补剂资料库自动维护(来源检查、复核队列、人工批准链路)处于规划中,尚未启用自动任务,详见补剂资料库自动维护方案。
• 证据等级标签(如「研究结果不一」)在补剂评价体系完整定义前不进入列表与详情,待评价体系确认后另行评估。

文件级实现地图见《项目架构与文件说明》。

状态：现状，原生 iOS 已实施；已分发版本随下一次 iOS 发布更新 <br>规则版本：2026.08.12-v1 <br>适用范围：原生 iOS「资料库 → 与你匹配」 <br>确认日期：2026-08-12

本文是补剂匹配值的唯一详细产品逻辑，和资料库产品逻辑一起维护。

1. 业务含义

匹配值表示：用户已确认的饮食、生活习惯、持续状态、用药、特殊状态或检查线索，与某项补剂专属规则的相关程度。

它不是：

• 营养缺乏概率。
• 服用后的有效概率。
• 诊断、处方或自动服用建议。
• 补剂本身的通用研究评分。

用户端列表和详情只展示最终数值，或在无法计算时展示“资料不足”。规则命中条件、内部依据和规则编号不直接显示给用户。

2. 五档固定值

分数只能是 90 / 75 / 50 / 25 / 0，不产生 68、76、85 这类伪精确中间值。0 与“资料不足”必须区分：前者是有信息后的判断，后者是不知道。

25 档已在规则模型里预留，但当前“当前目标”仍是自由文本，没有结构化目标字段，因此 v1 不用关键词把自由文本目标转成 25 分。

3. 完整计算过程

1. 读取某项补剂的版本化专属规则集
2. 使用已确认的结构化画像，逐条判断命中条件
3. 收集全部已命中规则
4. 按决策优先级选中唯一结果规则
5. 把规则档位直接映射为最终值
6. 保存规则版本与选中/命中记录，用于内部审计

没有加权、乘法或累计：

最终值 = 选中规则所在档位的固定值

同一项补剂命中多条规则时，决策优先级为：

90 明确依据
> 75 直接相关
> 0 明确暂不优先
> 50 间接相关
> 25 弱相关

0 放在 50 / 25 之前，是因为“已经记录每周吃鱼至少 3 餐”这类直接信息，应覆盖“想改善精力”这类弱目标。但它不会覆盖检查异常或更直接的个人依据。

4. 命中条件怎样判定

4.1 问卷字段精确命中

问卷条件判断的是结构化选项，不是用户原文：

「每周吃鱼几次」答 0–1 餐
→ 命中「吃鱼偏少」规则

「每周吃鱼几次」答 2 餐
→ 不命中该规则

数值区间在问题选项定义时已转成固定选项（例如“0–1 餐 / 周”）。规则引擎不用关键词猜测用户原话。

4.2 组合条件

规则支持“同时满足”和“满足其一”。例如褪黑素的间接相关规则需要同时满足：

通常 01:00 后入睡
并且
每周至少 4 晚存在睡眠困扰

4.3 已确认的画像文本

用药、检查异常和特殊状态保存在结构化列表中。因“其他：二甲双胍”包含用户确认的详情，这类字段可在结构化列表内匹配受控成分名。不会在任意对话原文中搜索“累”“鱼”等词并直接加分。

4.4 缺失不等于否定

没有回答鱼类摄入
≠ 每周吃鱼 0 次
≠ 鱼油匹配 0

正确结果 = 资料不足

5. 何时全量重算

App 为当前画像下的 45 项结果建立一份本地缓存。以下任一输入改变后，旧缓存失效，下一次读取匹配值时一次性重算完整补剂目录：

• 已确认问卷答案。
• 性别、检查线索、用药或特殊状态等画像字段。
• 已确认当前目标；当前 v1 仅作为缓存版本输入，不直接计分。
• 补剂目录范围。
• 匹配规则版本。

相同画像、相同目录和相同规则版本直接读取缓存。单纯打开页面不会调用模型，也不会为相同输入重复建立分数。

6. Agent 与规则引擎的边界

用户表达
→ Agent 可生成候选结构化信息
→ 用户确认
→ 保存为画像事实
→ 确定性规则引擎全量计算

Agent、DeepSeek 或其他大模型不直接决定分数，不能选择规则，也不能把未确认原文直接变成 90 或 75。

7. 鱼油 Omega-3 完整案例

快速画像包含「每周吃鱼几次」：

例如 35 岁男性，已确认过去 4 周每周吃鱼 0–1 餐：

性别：不是鱼油规则输入
当前目标：自由文本，v1 不计分
吃鱼频率 = 0–1 餐/周：命中「吃鱼偏少」
最终值：75

页面只显示“匹配 75”，不显示上述内部原因。

8. 叶酸案例

性别本身不是叶酸加分条件。若同时命中“备孕 / 孕期 90”和“蔬菜摄入充足 0”，选择更强的 90 分明确依据。

9. 45 项规则集覆盖

每个补剂都有一个显式规则集。“有规则集”不等于“必须有分数”。

9.1 已有可用结构化规则

50 分及以下的间接规则不进入当前“与你匹配”默认列表，但在搜索和详情中可显示结果。

9.2 已显式建档，但当前资料不足

以下 19 项在 v1 的规则集为空，不会按分类标签或条目自身热度产生分数：

• 维生素 B 族、硒、维生素 E、维生素 K2、复合维生素。
• 奶蓟草、蔓越莓、苏糖酸镁。
• NMN、亚精胺、阿克曼菌、PQQ、磷脂酰丝氨酸、R-α-硫辛酸。
• 麦角硫因 + 谷胱甘肽、甜菜碱（TMG）、槲皮素、大豆异黄酮、牡蛎提取物。

这些条目仍可作为资料浏览，但除非后续同时增加专属结构化输入、受审核规则和回归测试，不得显示个性化数值。

10. 列表、阈值与展示

“与你匹配”依次执行：

1. 合并本机内置目录和服务端返回目录。
2. 排除被标记为“不建议匹配”的条目。
3. 排除当前计划中同覆盖键条目。
4. 使用平衡档阈值 75，只保留 75 和 90。
5. 按数值降序；同分按中文名称排序。
6. 最多展示 5 项。

三档策略映射为：

当前资料库列表固定使用平衡档。

11. 安全不进入匹配值

匹配值不表示安全性。禁忌、药物相互作用、重复成分、剂量和是否允许匹配使用独立安全门槛，不能被 90 或 75 抵消。

• 被标记为“不建议匹配”的条目不进入匹配列表。
• 已在当前计划中的同成分条目不重复推荐。
• 补剂详情和加入记录流程继续显示必要安全边界。
• 低血红蛋白不等于缺铁，不会触发铁剂 75 或 90。
• 备孕、孕期、哺乳期、用药和明显检查异常仍需要专业核对。

12. 科学边界与参考

• NIH ODS：Dietary Supplements—What You Need to Know：补剂不能代替多样化饮食，也可能带来过量或相互作用风险。
• NIH ODS：Omega-3 Fatty Acids—Health Professional Fact Sheet：鱼类和海产品是 EPA / DHA 的食物来源；饮食信息不等于已确认缺乏。
• NIH ODS：Folate—Health Professional Fact Sheet和Pregnancy—Health Professional Fact Sheet：叶酸食物来源、缺乏风险和备孕 / 可能怀孕场景应分开处理。
• NIH ODS：Vitamin D—Health Professional Fact Sheet和Vitamin B12—Health Professional Fact Sheet：检查、日照、饮食和特定用药是不同强度的个人线索。

13. 实现与测试

文件级实现地图见《项目架构与文件说明》。规则回归测试覆盖：45 项覆盖、叶酸、鱼油、精确条件命中、无依据不评分、画像变化后刷新。

文档状态:现状(核对日期 2026-08-13) | 产品端:原生 iOS,Web 为线上兼容端<br>本文按产品经理视角描述「我的」模块当前已实现的业务逻辑与规则。

1. 需求概述

1.1 模块定位

「我的」集中呈现元气长期了解用户的内容、健康数据与提醒来源、账号同步状态和数据控制能力,是用户查看自己画像与数据主权的中枢页:

• 查看与确认长期画像:当前目标、偏好、限制、基础线索与科学基线。
• 管理健康数据来源:Apple 健康授权、本机每日摘要、账号摘要同步。
• 管理提醒与连接状态、设置外观。
• 账号与数据控制:导出、修改密码、重新开始体验、退出登录。

「我的」对游客开放;需要账号的能力(导出、改密、账号摘要同步等)在具体位置引导登录。

1.2 用户价值

1. 了解元气记住了什么:长期画像可见、可确认,来源标注「已确认 / 历史记录」。
2. 掌控健康数据:明确只读授权、原始样本不上传、本机与云端摘要可分别删除,同步开关默认关闭。
3. 提醒可管理:补剂名称是否出现在通知中由用户决定。
4. 账号数据自主:导出、改密、重新开始、退出均有明确边界与确认。

1.3 范围与边界

范围:身份与同步状态、元气了解的你(长期画像)、科学基线、健康数据来源(Apple 健康与账号摘要同步)、提醒设置、连接状态、外观、账号与数据控制、Web 兼容端差异。

边界:

• 游客可进入「我的」,但账号能力就地引导登录,游客不展示编造的长期画像。
• 健康数据只读:元气不向 Apple 健康写入训练或其他数据;原始样本留在 Apple 健康。
• 账号摘要同步默认关闭;摘要只解释生活趋势,不能自动新增、停用、改量或改周期补剂计划。
• 本机摘要路径与账号同步路径独立,互不影响。
• 断网、数据缺失、权限未授予不是健康异常,分别呈现当前结果与下一步。

2. 用户与使用场景

3. 功能需求

3.1 身份与同步状态(入口:我的页顶部)

• 登录后:显示「用户 {用户名}」与账号同步状态。
• 游客:显示「元气」与「仅保存在此设备」。
• 同步状态分为:仅保存在此设备(仅本机)、正在同步、已同步到账号、同步失败。
• 进入页面时触发服务连接检查与整体刷新(见 3.5)。

3.2 元气了解的你(长期画像查看;入口:我的页)

• 「当前目标」的读取顺序:登录账号健康模型中的已确认目标 → 首次画像中用户确认的当前目标 → 都没有时显示「无」。
• 登录后依次展示偏好、限制、基础线索,并标记为「已确认」或「历史记录」(历史记录为旧账号迁移数据);健康模型加载中显示加载状态。
• 游客不展示编造的长期画像,而是说明登录后可以整理长期目标、偏好与限制,并提供登录入口。
• 修改方式:长期画像主要通过问元气对话修改,问元气生成待确认修改、用户确认后保存并刷新;本页为查看与状态展示。
• 若存在科学基线,单独展示其标题和说明;个人偏好不能覆盖科学基线。

3.3 健康数据来源(入口:我的 → 健康与提醒 → 健康数据来源)

主流程与交互:

• 连接:首次连接时申请 Apple 健康只读权限;系统授权说明明确包含「运动记录」,只申请读取权限,不申请向 Apple 健康写入训练或其他数据。
• 已连接用户:可「重新读取」;已连接的旧用户可以单独「允许读取运动记录」补充新增运动类型授权;可「前往系统设置」调整权限。
• 数据展示:实际读到的数据类型、来源名称(可能来自 Apple Watch、iPhone 或其他获准写入 Apple 健康的 App)与更新时间;并说明「原始样本保留在 Apple 健康;元气只处理结构化每日摘要」。
• 停止读取(确认):停止后续读取,已读本机摘要保留,除非另外删除。
• 删除本机摘要(确认):删除元气本机保存的每日摘要,不影响 Apple 健康中的原始数据。
• 登录后:显示账号摘要同步状态,提供「同步每日摘要到账号」开关(默认关闭),以及「删除云端摘要」(确认)。
• 游客:显示「登录后可把每日摘要加密同步到账号;原始样本不会上传」。
• 状态:连接状态分为 此设备不支持 / 尚未连接 / 正在读取 / 已读取 / 数据待更新 / 未读取到数据 / 暂时无法读取。

3.4 提醒设置(入口:我的 → 健康与提醒 → 提醒)

• 当前通知权限状态(尚未开启 / 已允许 / 未允许);被拒绝时提供「前往系统设置」。
• 「在通知中显示补剂名称」开关,默认关闭;关闭时锁屏只显示通用到点提醒。
• 「已开启的提醒」列表:展示补剂名、提醒时间与频次;点按进入该计划项编辑。
• 提醒规则见 R-13。

3.5 连接状态(入口:我的 → 连接状态 → 元气服务)

• 「元气服务」由用户主动点按或进入页面时检查,显示 已连接 / 正在检查 / 轻点检查连接 / 具体可恢复错误。
• 该状态只表示服务连接,不证明计划、估值或业务数据一定正确。

3.6 外观(入口:我的 → 外观)

• 跟随系统 / 浅色 / 深色,选择立即影响整个 App。

3.7 账号与数据(入口:我的 → 账号与数据)

登录账号:

• 导出健康数据:生成带日期的数据文件,再由系统分享或保存;导出错误只出现在导出操作旁。
• 修改密码:输入当前密码、新密码(12–64 位,支持中文和空格)与确认;成功后新密码立即生效,其他设备需重新登录。
• 使用与安全。
• 重新开始体验:破坏性确认后清除当前画像、当前计划、对话显示和本机上下文,回到首次使用流程;已登录时同时清空账号画像上下文,失败时同步状态标为失败。
• 退出登录:确认后退出账号同步,载入本机游客记录;明确提示本设备记录会保留。

游客:

• 显示「登录后可导出数据、同步计划」,点按打开登录/注册层。
• 仍可查看使用与安全、重新开始体验和外观设置。

3.8 Web 兼容端差异(线上兼容端)

• Web「我的」没有:健康数据来源(Apple 健康)、提醒、连接状态、账号摘要同步。
• Web「我的」有:身份与同步提示(初始化数据已云端同步 / 账号已注册·完成初始化后数据自动同步 / 数据随账号云端同步)、元气了解的你(目标 / 偏好 / 安全边界 / 当前状态 + 已确认/历史记录标记)、科学基线、外观、导出健康数据、修改密码、重新了解我的情况、退出登录。
• 差异点:Web「重新了解我的情况」直接跳转首次流程,无破坏性确认;iOS「重新开始体验」有破坏性确认。Web 退出登录无确认弹窗,直接登出并返回首页;iOS 有确认弹窗。Web 页脚常驻「本产品提供健康信息参考,不构成医疗建议」提示,iOS「我的」页不常驻同类标签。

4. 业务规则

• R-01 游客可进入:我的页对游客开放,外观、使用与安全、重新开始为本地能力;仅登录可用的能力(导出、改密、账号摘要同步)在页面内引导登录。
• R-02 当前目标读取顺序:登录账号健康模型中的已确认目标 → 首次画像中用户确认的当前目标 → 都没有时显示「无」。
• R-03 账号数据优先:登录账号存在健康模型时以账号数据为准;游客不展示编造的长期画像,只提供登录引导。
• R-04 科学基线高于个人偏好:存在科学基线时单独展示标题与说明,个人偏好不能覆盖科学基线。
• R-05 Apple 健康只读范围:只读睡眠、步数、运动记录、运动分钟(活动圆环)、步行与跑步距离、活动能量、静息心率、HRV;只申请读取权限,不向 Apple 健康写入训练或其他数据。
• R-06 运动摘要口径:运动部分只保留训练次数、训练总时长、训练类别及各类别时长、步行与跑步距离;训练按开始日期归入当天;原始训练、轨迹、逐笔心率和其他原始样本留在 Apple 健康,不上传到元气账号。
• R-07 口径不混淆:训练时长与 Apple 活动圆环运动分钟是两种不同口径,分别展示、不相加;没有运动记录只表示本次没有读到对应数据,不能写成用户当天没有运动;iOS 不能可靠区分用户拒绝读取与确实没有数据,因此产品只说明是否读取到数据,不猜测权限原因。
• R-08 本机路径独立:只要 Apple 健康读取已开启,本机当天摘要就可以直接进入今日状态卡,不要求用户登录或开启账号摘要同步;今日卡的运动事实区分回显训练、活动圆环分钟、步数和步行/跑步距离;恢复等级仍由睡眠、睡眠时段、静息心率和 HRV 决定;只有当天训练记录或活动圆环记录会调整本机参考建议,步数和距离只作为事实,昨天的运动不进入今天建议。
• R-09 账号摘要同步默认关闭:只有登录用户主动打开「同步每日摘要到账号」后才上传结构化摘要;同意状态采用版本化、按账号记忆的设置,切换账号不沿用上一账号的选择。
• R-10 摘要同步范围与加密:开启后最多同步最近 35 天摘要;云端按摘要规则版本加密保存,并与账号、日期、规则版本关联;运动原始样本仍不上传。
• R-11 关闭与删除语义:关闭同步只停止后续上传,不等于删除已同步摘要;「删除云端摘要」成功后会同时关闭该账号的同步开关;开启、关闭或删除云端摘要都不影响本机今日状态与当日运动事实回显;删除云端摘要不删除 Apple 健康原始数据,也不自动删除本机摘要。
• R-12 摘要不自动改计划:账号摘要可以帮助解释生活趋势,但不能自动新增、停用、改量或改周期补剂计划;摘要仅作为问元气的参考输入,不提供原始样本。
• R-13 提醒先有明确时间频次:提醒必须先有明确时间和频次;最多使用 8 个不同提醒时点,多个补剂可以共用一个时点;当前只使用本地通知,不提供通知内打卡或稍后提醒。
• R-14 通知权限与名称披露:通知权限被拒绝时提供前往系统设置;「在通知中显示补剂名称」默认关闭,关闭时锁屏只显示通用到点提醒。
• R-15 服务连接状态语义:「元气服务」由用户主动点按或进入页面时检查,显示 已连接 / 正在检查 / 轻点检查连接 / 具体可恢复错误;该状态只表示服务连接,不证明计划或业务数据一定正确。
• R-16 外观立即生效:跟随系统 / 浅色 / 深色选择立即影响整个 App。
• R-17 导出:仅登录可用;导出为带日期的数据文件(文件名含导出日期),内容包含账号信息、健康模型(目标/偏好/限制/基础线索/科学基线)、历史版本上下文与画像、最近 35 天云端摘要;导出错误只出现在导出操作旁,可重试。
• R-18 修改密码:需输入当前密码、新密码与确认;新密码 12–64 位(支持中文和空格);成功后新密码立即生效、旧密码失效,并刷新账号信息;提示其他设备需要重新登录。
• R-19 重新开始体验:破坏性确认后清除当前画像、当前计划、对话显示和本机上下文,回到首次使用流程;已登录时同时清空账号画像上下文,失败时同步状态标为失败。
• R-20 退出登录:确认后删除本地会话、退出账号同步并载入本机游客记录;提示明确说明本设备记录会保留。
• R-21 破坏性操作分别确认:Apple 健康本机删除、云端删除和停止读取分别确认,不能合并成一个含糊操作;重新开始与退出登录使用不同确认文案,明确各自影响。
• R-22 错误就地呈现:导出错误只出现在导出操作旁,不常驻页面底部;运动权限未授予、数据缺失和同步失败分别显示当前结果及下一步,不把它们写成健康异常或「没有运动」。

5. 数据与状态

5.1 主要对象

5.2 跨页刷新

• 今日状态卡:本机当天摘要直接回显(不要求登录或开启账号同步)。
• 计划变化(新增 / 编辑 / 删除 / 登录 / 退出 / 回到前台):重新核对提醒。
• 问元气确认修改:刷新计划、今日、周计划与健康模型,「元气了解的你」随之更新。
• 通知点开:回到今日并高亮对应计划项。

6. 异常与边界

7. 关联模块

8. 验收要点(现状基线)

以下为当前已实现且已核对的行为,作为回归验收基线:

1. 游客可进入我的:显示「元气 / 仅保存在此设备」,长期画像区引导登录;外观、使用与安全、重新开始可用。
2. 登录后:显示用户名与同步状态;当前目标按 健康模型 → 首次画像 → 无 的优先级;偏好/限制/基础线索带「已确认 / 历史记录」标记;健康模型加载中有加载态。
3. 科学基线存在时单独展示,个人偏好不覆盖。
4. 健康数据来源:连接 / 重新读取 / 运动记录补充授权 / 数据类型与来源展示 / 前往系统设置 / 停止读取 / 删除本机摘要 均可用;登录后出现账号摘要同步开关与删除云端摘要;默认关闭、按账号记忆。
5. 本机当天摘要直接进入今日卡;训练时长与活动圆环分钟分别展示不相加;缺失不写成异常。
6. 提醒:权限状态、显示补剂名称开关(默认关)、已开启提醒列表;被拒绝提供系统设置入口;最多 8 个时点。
7. 元气服务连接状态:已连接 / 正在检查 / 轻点检查 / 具体错误。
8. 外观:跟随系统 / 浅色 / 深色立即全局生效。
9. 账号与数据:导出(带日期的数据文件)、修改密码(其他设备需重新登录)、使用与安全、重新开始(破坏性确认 + 登录时同时清空账号画像)、退出(确认 + 本机记录保留)。
10. 破坏性操作分别确认;错误只在受影响位置呈现。
11. Web 兼容端:无健康数据来源 / 提醒 / 连接状态 / 摘要同步;重新了解与退出无破坏性确认(与 iOS 不同,记录为现状差异)。

9. 迭代记录

• 2026-08-13:本模块核对完成(健康数据来源、账号摘要同步默认关闭 / 版本化 / 35 天 / 加密保存、提醒、导出、修改密码、重新开始、退出登录、Web 差异)。

未验收项 / 已知缺口:

• 账号摘要同步(开启 / 关闭 / 删除云端摘要)、修改密码后旧密码失效、重新开始体验的账号画像清空均为已实现路径;多账号切换、删除云端摘要与真机通知等场景仍需真实设备验收后标记已上线。
• 「在通知中显示补剂名称」默认关闭,锁屏只显示通用到点提醒;通知内打卡与稍后提醒暂不提供(现状约束,非缺口)。
• Web 兼容端「重新了解我的情况」无破坏性确认、退出登录无确认弹窗,与 iOS 行为不同,记录为现状差异,待产品决策是否对齐。

文件级实现地图见《项目架构与文件说明》。

本文件夹记录元气 Agent 的全部当前逻辑,按产品经理视角组织。 <br>文档状态:全部为 现状,与 2026-08-13 产品现状核对一致。 <br>默认产品端:原生 iOS;Web 为线上兼容端。

1. Agent 是什么

「问元气」是元气 App 里的健康与生活对话助手,固定在底部导航最右侧,点按后打开独立全屏对话。它在产品上有两条路径,共用同一套模型与安全理念:

核心设计一句话:模型(DeepSeek)只负责理解与表达;读取什么、能改什么、参数从哪来、什么能保存,全部由服务端确定性规则控制。 所有修改先变成"待确认动作卡",只有用户确认后才写入账号。

2. 能力地图(一览)

Agent 当前共有 14 项受控能力 + 1 个规划结束信号。完整规则见Agent 能力清单。

3. 文档导航

4. 实现地图(文件级)

文件级实现地图见《项目架构与文件说明》。

5. 维护规则

1. Agent 任何能力或规则变化,先更新本文件夹对应文档,再改代码与测试。
2. 对话体验与用户可见行为归 Agent产品逻辑.md;每项能力的触发与参数归 Agent能力清单.md;判定规则、动作生命周期与安全红线归 Agent业务规则.md。
3. 各端之间的流式传输技术合同只归 docs/技术/Agent流式协议V1.md,不在产品文档重复传输细节。
4. 已确认逻辑、代码实现和真实上线必须分别标记,不把讨论稿写成现状。

文档状态:现状,与 2026-08-13 产品现状核对一致。 <br>产品端:原生 iOS;Web 为线上兼容端。 <br>配套文档:能力清单、业务规则、流式协议。

1. 需求概述

1.1 模块定位

「问元气」是元气 App 的全局健康与生活对话助手,固定在底部导航最右侧,点按后打开独立全屏对话,关闭后回到原内容 Tab。它在一个入口里同时完成三件事:回答用户的健康/饮食/恢复/补给问题;读取账号里的已确认状态;在用户明确要求时生成"待确认修改",经确认后更新账号。

1.2 用户价值

• 用户用自然语言说"我正在吃鱼油 2 粒"就能记录计划,说"昨晚没睡好"就能拿到仅今天的调整建议,不用去各页面手动填表单。
• 所有修改先给"修改前 → 修改后"预览,确认才生效,用户始终保有控制权。
• 对话能读到账号真实状态,回答有依据,不会把推荐当成用户已经在做的事。

1.3 范围与边界

做:健康与生活方式咨询;读取已确认计划、画像、今日事件、健康模型(含按账号开启同步后的 Apple 健康摘要);生成并确认 14 类受控修改。

不做:不诊断疾病、不开处方;不把咨询、假设或未来打算写成事实;不把推荐补剂直接写进"正在服用";模型(DeepSeek)只负责理解与表达,所有写入参数、校验和保存由服务端确定性规则控制。

2. 用户与使用场景

3. 功能需求

3.1 入口与呈现

• 底部导航最右侧固定入口;点按打开全屏独立对话,不在各内容页重复放入口。
• 首次画像结果页可直接打开问元气。
• 打开时自动带上用户当前所在的页面位置(今日 / 周计划 / 资料库 / 我的),只影响理解、追问与指代解析,不扩大写入权限。

3.2 一轮对话的主流程

用户发送消息
  → 读取账号当前状态与本轮会话
  → 判断:咨询 / 读取 / 修改(可同时成立)
  → 科学准入检查(命中红线直接给安全回复,不调用语言模型)
  → 受控规划:只在本轮原话范围内判断要做什么,或由确定性规则兜底识别
  → 每个修改意图 → 校验参数必须来自本轮原话 → 生成待确认动作卡
  → 逐字输出过程摘要与回答正文(实时过滤内部处理信息)
  → 全文校验:逐字出现的内容与最终正文一致
  → 展示待确认动作、当日策略预览和 3 条后续问题

同一时间只允许一轮发送;停止后取消当前任务、保留已显示的安全正文,并把进行中的过程标为停止;上一轮停止后迟到的内容不会混入新一轮。

3.3 界面元素(从上到下)

1. 当前会话消息;
2. 正在逐字出现的回复;
3. 默认折叠的"本轮生成过程"(可核对摘要);
4. 待确认修改卡(标题/摘要/影响/修改前后,可逐项确认、"全部确认"或取消);
5. 发送中或错误恢复状态;
6. 三个后续问题建议;
7. 多行输入框(1–4 行)与发送按钮。

用户向上阅读时不自动抢滚,接近底部才跟随新内容;发送中禁止重复发送。

3.4 对话内确认

用户回复"确认/全部确认/保存/执行"等且本轮未提到新补剂时,直接确认当前待确认动作;若同一句话还提到新的补剂事实,则按新一轮理解,避免误确认。部分失败时明确汇报"已保存 N 项,还有 M 项未完成"。

3.5 新开对话

• 只有当前会话已出现用户消息、无发送中任务、无动作更新时按钮才可用。
• 登录用户新建一个活动会话;旧消息继续保留在账号记录里,但不进入新会话。
• 游客重置为基于当前首次画像的开场消息。
• 已确认的健康资料、计划、今日事件与健康摘要是账号级状态,不因新开对话被清除。

3.6 停止、错误与恢复

3.7 游客与登录两条路径

4. 业务规则(摘要)

完整规则见Agent 业务规则(R-01~R-56),核心条目:

• 修改参数只来自用户本轮原话;旧对话和账号已有状态不能替用户补齐剂量、时段、频次或画像字段(R-41)。
• 假设、未来打算、咨询和否定不生成已发生事实(R-04/R-07/R-08);一次睡差/训练/一顿饭不触发补剂新增或加量(R-38)。
• 模型主动推荐的新补剂不能直接生成"正在服用"记录(R-05)。
• 所有修改先成为待确认动作,只有确认后才写入账号(R-19);确认幂等(R-20)、取消不可再确认(R-21)、跨入口修改冲突需重新预览(R-22)、同一确认批次可逐项连续确认(R-23)。
• 未说明的剂量/时段/频次如实标"未说明",不伪造日程、不默认每日提醒(R-16)。
• 科学证据与安全红线高于用户偏好;不诊断、不开处方(R-35/R-37)。
• 回复中不得出现内部处理信息、工具名、调用编号,也不得声称未经确认的保存结果(R-28/R-44)。
• 只有按账号明确开启摘要同步后,Agent 才能读取 Apple 健康摘要,且只用于解释趋势,不能自动改药物或补剂(R-39/R-46)。

5. 数据与状态

6. 异常与边界

7. 关联模块

• 今日:今日事件确认后生成当日策略卡;补剂动作确认后刷新今日计划与打卡。
• 周计划:补剂动作确认后同步周视图。
• 资料库:补剂动作确认后刷新排除状态(正在吃的同成分不再推荐)。
• 我的:画像、健康目标与偏好确认后刷新;Apple 健康摘要同步开关决定 Agent 可读范围。
• 提醒:补剂时段/频次确认后由 iOS 重新核对本地通知。

8. 验收要点(现状基线)

• 游客与登录两条路径行为符合 3.7 表格;游客不出现动作卡。
• 修改参数只来自本轮原话:旧对话、账号状态、模型推荐均不能补参数。
• 确认幂等、取消不可再确认、跨入口冲突提示重新发送、同一确认批次逐项确认可用。
• 公开输出无内部处理信息,也不出现未经确认的"已保存"声称(含回复逐字出现过程被中断的场景)。
• 逐字出现的内容与最终正文逐字一致;内容不完整、顺序错乱或无法识别时明确失败。
• 科学红线命中时不调用语言模型、不生成动作。
• 批量口述"我正在吃的补剂"一次最多 12 项待确认;普通轮 4 项。

9. 迭代记录

• 2026-08-12 旧基线:对话产品逻辑、流式传输、动作确认与错误恢复形成现状。
• 2026-08-13:按产品经理视角重写为 PRD;Agent 文档拆分到 docs/产品/Agent/ 文件夹(README/产品逻辑/能力清单/业务规则),并新增精力睡眠方向、生活安排、健康目标与路径偏好等能力的完整记录。

文档状态:现状,与 2026-08-13 产品现状核对一致。

本文逐项记录 Agent 当前全部受控能力。每项包括:做什么、什么话会触发、参数从哪来、怎么校验、动作卡长什么样、确认后保存什么、刷新哪些页面。

通用规则(适用于所有写入能力,详见Agent业务规则):

1. 修改参数只来自用户本轮原话,不能从旧对话或账号已有状态补齐。
2. 模型给出的参数必须与确定性规则从原话抽取的结果完全一致,不一致即拒绝。
3. 修改能力只生成"待确认"状态的动作卡;确认前账号不变。
4. 疑问句、假设句、未来打算、否定表达一律不生成修改动作。

1. 读取我的状态 —— 只读

• 什么时候用:用户问"我现在吃什么 / 当前计划 / 我的画像 / 你了解我什么"等,必须读取并直接用结果回答;没有记录就明确说没有,不允许用欢迎语回避。
• 读取内容:已确认补剂计划(名称、剂量、服用方式、数量、品牌备注、时段、频次)、结构化资料、生活画像、最近 10 条今日事件。
• 参数:无。
• 保存:无。若未按需读取且用户问了当前计划/画像,由确定性规则直接给出读取结果。

2. 读取健康模型 —— 只读

• 什么时候用:回答与长期目标、路径偏好、生活安排相关的问题时。
• 读取内容:目标、偏好、约束、基线、活动策略、生活安排、实验与结果、证据引用;内部策略周期与复盘日不向用户复述,只允许说"目标、偏好、今天建议、安排"。
• 参数:无。保存:无。

3. 记录今日状态 → 记录今日事件

• 触发:用户明确说出昨晚/今天发生的一次性事实,包括睡眠、训练、饮食、漏餐、饮酒、肠胃、压力、生病或带时间词的其他状态。
• 支持的事件类型:昨晚睡得不好 / 今天完成了训练 / 记录了今天的饮食 / 今天漏了一餐 / 今天有饮酒 / 今天肠胃不舒服 / 今天压力较大 / 今天身体不舒服 / 记录了今天的状态。
• 参数校验:
  • 事件类型必须能被原话支持:假设词(如果/假如/明天/打算/准备/可能)、对应类型的否定句(如"没失眠""没运动")都会拒绝;
  • 对事件类型的判断与规则识别结果不一致时拒绝;
  • 简要描述使用固定事件标签,详细描述截取用户原话最多 300 字。
• 动作卡:标题"记录到今天";影响说明"仅影响今天,不修改长期画像和周期计划";附一张当日策略预览卡。
• 确认后保存:记录今日事件(事件类型、摘要、用户原话,日期为当天);不生成历史检查、不写入健康模型。日期已过期(非当天)或类型不支持时提示"这项修改已过期",不写入。
• 刷新:今日页的"今天记得做什么"、对话中的今日事件与当日策略。
• 连带效果:策略卡只建议食物、补水、恢复、按原计划执行;一次睡差或一次训练不新增、加倍或修改补剂。

4. 新增/修改补剂 —— 待确认写入

• 触发:用户明确表示"正在吃 / 现在吃 / 每天吃"某资料库补剂,或明确要求修改、记录、添加、调整现有记录。
• 拒绝触发:咨询句式(是不是/好吗/如何)、假设与未来意向(我打算/考虑/想开始/准备吃/计划吃/可能会吃)、模型主动推荐新补剂。
• 参数:补剂(必须命中 45 种资料库之一)、剂量、服用方式、时段、频次。
• 参数来源与校验:
  • 补剂名称必须出现在用户原话中(按别名匹配,含"维 D→维生素 D3""鱼油→欧米伽 3"等特殊别名与单字母语境保护,见业务规则);
  • 剂量/服用方式/时段/频次由确定性规则从原话抽取;给出的参数必须与抽取结果一致,否则拒绝(剂量未说明 / 时段未说明 / 频次未说明等);
  • 新增记录:原话没说的剂量、时段、频次分别保存为"剂量未说明""时间未说明""频次未说明",绝不用资料库默认值或"每日"填空;
  • 修改已有记录:只改抽取到的字段,没说的字段沿用旧值,防止旧值被误覆盖。
• 动作卡:标题"记录正在吃的补剂"或"修改当前补剂";摘要显示名称·剂量·频次·时段;有未说明字段时影响说明为"未说明的信息不会被当作推荐剂量或自动提醒"。
• 确认后保存:写入或替换账号补剂计划中的对应项,并同步健康模型里的补剂安排;计划上限 20 项。
• 刷新:今日、周计划、资料库排除状态、健康模型。
• 个人补剂除外:名称不能安全映射时按第 5 节"记录个人补剂"处理。

5. 记录个人补剂 —— 待确认写入

• 触发:用户明确说正在吃某产品,但名称不能安全等同于资料库任何成分。当前支持的个人补剂:姜黄粉、姜黄(它们不是"姜黄素"的同义词)。
• 校验:名称必须是本轮原话;若名称本身可映射到资料库(如鱼油),拒绝走个人记录路径,避免重复;剂量/方式/时段/频次规则与标准补剂相同。
• 保存:以个人记录标识存入计划,保留用户原名,不改写成相近成分。

6. 删除补剂 —— 待确认写入

• 触发:用户明确说"不吃了 / 停了 / 停止服用 / 已经不吃"或明确要求删除某资料库补剂;否定句("不想删除""不要停")拒绝。
• 校验:补剂必须在原话中且当前计划里确实存在,否则拒绝。
• 动作卡:影响说明"确认后从长期计划移除;系统建议区仍可能继续显示相关依据"。
• 确认后保存:从补剂计划中移除,并同步停止健康模型里的补剂安排;历史打卡记录保留。

7. 修改结构化资料 —— 待确认写入

• 可改字段与操作:
  • 年龄、身高、体重、性别:只能设定新值;
  • 体检标记、正在用药、特殊状态:只能添加或移除。
• 触发与校验:
  • 需要明确修改意图,或说出"体重 70kg / 身高 175cm / 我今年 30 岁"这类可验证的当前事实;
  • 数值边界:年龄 12–120 岁、身高 100–230cm、体重 25–300kg,超出拒绝;
  • 用药识别只接受"药/片"结尾或已知药名(二甲双胍、左甲状腺素、优甲乐、华法林、阿司匹林、他汀);补剂名会被排除;
  • 疑问句、否定表达拒绝。
• 动作卡:标题"更新结构化资料";摘要"字段:修改前 → 修改后";影响"确认后更新健康资料,并重新计算相关安全提醒"。
• 确认后保存:更新账号中的结构化资料;列表字段添加时去重、移除后为空时记"无"。
• 刷新:健康模型、资料库匹配分(重新计算)、安全提醒。

8. 修改生活画像 —— 待确认写入

• 可改字段:长期目标、作息、饮食习惯、咖啡因习惯;其中长期目标不允许通过此能力修改(目标更新走第 9 节),待确认方向永远由确定性规则推导,模型不可改。
• 触发:用户明确纠正长期习惯,如"我的作息改成 23 点前睡""咖啡因习惯更新为每天 1 杯";一次性今天状态不得进入长期画像。
• 校验:必须有明确修改意图(疑问/否定拒绝);值必须出现在原话中。
• 动作卡:"更新生活画像",显示字段修改前→修改后。
• 确认后保存:更新账号中的生活画像。

9. 更新健康目标 —— 待确认写入

• 触发:用户明确表达长期目标:"我最想改善睡眠""我的当前目标是……""记住/保存……为目标"。
• 区分咨询:"怎么改善睡眠"只是咨询不写入;"我最想改善睡眠"生成目标预览。
• 校验:目标文本(2–120 字)必须从原话抽取且与给出的参数一致;疑问句、否定、假设拒绝;一个账号同一时间只有一个激活目标,新目标会替换旧目标(旧目标停用)。
• 动作卡:"更新健康目标";影响"确认后用于调整后续建议;不会自动新增补剂"。
• 确认后保存:写入健康模型中的健康目标。

10. 更新健康路径偏好 —— 待确认写入

• 三档路径:
  • 优先生活方式(触发词:"不想吃补剂/优先饮食/先从饮食/先调整作息");
  • 综合考虑(触发词:"饮食和补剂都可以/综合一点/均衡考虑");
  • 愿意考虑补剂(触发词:"愿意考虑补剂/补剂也可以")。
• 校验:路径必须能从原话明确识别且与给出的参数一致。
• 动作卡:影响"确认后只调整方案排序,不改变科学证据和已有补剂记录"。
• 确认后保存:替换同类的旧偏好(旧值停用)。

11. 创建精力与睡眠改善方向 —— 待确认写入

• 触发:用户同时表达精力 + 睡眠改善意图,如"我想改善下午没精神和睡眠,先从生活方式开始";或带明确修改意图的精力睡眠目标。
• 生成内容(草稿):一个目标"改善下午精力与睡眠"、一个 7 天策略(重点只改变起床窗口和咖啡因截止时间)、4 项生活安排(固定起床窗口 / 提前结束咖啡因 / 白天见光走一走 / 不靠零食顶午餐)、1 个内置 7 天实验。是否按"优先生活方式"起草,由原话的路径偏好决定(用户明确"愿意考虑补剂"时不按优先生活方式)。
• 动作卡:标题"记住改善方向";只预览"要记住的目标和偏好",不展示内部周期等细节;影响"不会自动改动补剂记录"。
• 确认后保存:旧活动策略标记为已完成(其中已确认的补剂安排原样保留到新策略)、旧目标停用,再写入新的目标/偏好/策略/安排/实验。
• 回复:确认前的回复由规则生成,如"我会把'改善下午精力与睡眠'作为长期方向记住……确认后才会保存"。
• 去重:同一轮同时出现本能力与"更新健康目标/路径偏好"时,只保留本能力。

12. 新增/修改生活安排 —— 待确认写入

• 触发:用户明确指定具体动作 + 时间锚点的长期安排。当前确定性覆盖三种高频句式:
  • 咖啡因:"下午 3 点以后不喝咖啡"→"提前结束咖啡因,每天 15:00 后不再摄入咖啡因"(对应咖啡因截止的科学依据);
  • 睡眠:"睡觉时间固定到 23 点"→"固定上床时间,每天约 23:00 上床,允许前后 30 分钟"(对应作息规律的科学依据);
  • 活动:"晚饭后散步 20 分钟"(5–120 分钟)→"晚饭后轻松步行 20 分钟"(对应白天活动的科学依据)。
• 前提:账号已有活动策略(否则拒绝);时间表达会按"下午/晚上 1–11 点加 12、上午/凌晨 12 点归 0"归一为 24 小时制。
• 校验:类别(饮食/作息/活动/恢复)、标题、说明、时间标签必须与原话抽取一致。
• 动作卡:"添加生活安排"或"更新生活安排";摘要"类别 · 标题";回复中给出具体说明文字。
• 确认后保存:新增为活动中的生活安排,并附用户原话与对应科学依据。

13. 停止生活安排 —— 待确认写入

• 触发:用户说"删除/移除/取消/停止/不做"某项安排;先按标题精确匹配,再按类别关键词匹配(咖啡→恢复、上床→作息、散步→活动、餐→饮食),只命中唯一一条才执行,有歧义则拒绝。
• 动作卡:影响"确认后停止长期安排;历史记录保留"。
• 确认后保存:该项安排改为已停止(保留历史,不删除)。

14. 推荐后续问题 —— 只读

• 触发:由模型在回答末尾生成,或由确定性规则按页面/状态兜底生成 3 条输入建议(2–32 字,去重,不得与用户本轮消息相同)。
• 规则兜底示例:有动作卡时优先"确认后今天会怎么变?";今日页给"记录我今天吃了什么"等;无计划时插"我目前没有补剂怎么开始?";按用户轮次轮换起点,避免每轮一模一样。
• 保存:无;随助手消息一并保存,供下一次读取复用。

15. 规划结束(内部)

• 判断"本轮无需读写"时的结束信号;只在内部使用,不出现在界面或任何对外内容中。

数量与合并规则

1. 普通对话一轮最多保留 4 项待确认动作。
2. 纯"批量口述我正在吃的补剂"(同轮提到 4 项以上且不含咨询词)跳过模型规划,由确定性规则直接识别,最多 12 项。
3. 同一资源只保留一个动作(同补剂、同画像字段、同事件类型后者覆盖前者);若同轮出现"创建精力睡眠方向",丢弃同轮的目标/偏好动作。
4. 同一会话里逐轮收集的补剂修改,只要"预览生成时的账号状态指纹"相同就合并为同一个确认批次:后轮对同一补剂的修正替代旧预览,其余动作继续保留在批次中。

文档状态:现状,与 2026-08-13 产品现状核对一致。

本文记录 Agent 的判定规则、动作生命周期、回复守卫、安全红线与降级兜底。每条规则用 R-xx 编号,便于产品讨论时引用。

1. 意图判定:咨询 / 读取 / 修改

每轮先把用户这句话归为三类意图(可同时成立),再决定要不要生成动作:

2. 实体与参数识别:一切参数来自本轮原话

3. 动作生命周期:从预览到保存

3.1 动作结构与状态机

一个待确认动作包含:唯一编号、动作类型、标题/摘要/影响文案、保存内容、修改前后预览、预览生成时的账号状态指纹、确认批次、用户原话。所有动作都要求用户确认后才会保存。

状态:待确认 → 已执行 / 已取消。规则:

3.2 各动作确认后的保存与回复

4. 回复生成与四道公开输出守卫

5. 安全与科学红线

6. 会话、上下文与隐私边界

7. 降级与兜底(模型不可用时的行为)

8. 初始化对话(游客路径)的差异规则