Merge branch 'main' of https://huggingface.co/spaces/build-small-hackathon/PregoPal

docs/项目架构说明书.md

@@ -0,0 +1,995 @@
+# PregoPal 项目架构说明书
+
+> **📌 关于批注区的重要说明**
+>
+> 本文档每个模块/小节均设有「批注区」（用 `> **批注：**` 标记），用于记录开发过程中的讨论、决策、待办事项。
+>
+> **批注区中由你（项目负责人）亲手写入的文字，是重要的原始参考依据，任何人不得修改或删除。**
+>
+> - 如有新的观察或建议，请在 `> **批注：**` 下方以 `>>` 追加新行
+> - 如需修正已有批注内容，请在后方追加 `[修正: ...]` 标记，不得覆盖原始文字
+> - 批注区中的意见将指导后续迭代方向，所有 Cline 协作修改前应先阅读对应批注
+
+---
+
+## 目录
+
+- [一、项目概览](#一项目概览)
+- [二、整体文件结构](#二整体文件结构)
+- [三、app.py — 主入口](#三apppy--主入口)
+- [四、config.py — 全局配置](#四configpy--全局配置)
+- [五、utils.py — 工具函数](#五utilspy--工具函数)
+- [六、loop.py — 核心循环引擎](#六looppy--核心循环引擎)
+- [七、plugins/ — 插件系统](#七plugins--插件系统)
+- [八、modules/ — 业务逻辑层](#八modules--业务逻辑层)
+- [九、core/ — AI 核心层](#九core--ai-核心层)
+- [十、ui/ — 表现层](#十ui--表现层)
+- [十一、data/ — 数据存储](#十一data--数据存储)
+- [十二、tests/ — 测试套件](#十二tests--测试套件)
+- [十三、配置文件](#十三配置文件)
+- [十四、协作规范与 Git 工作流](#十四协作规范与-git-工作流)
+- [十五、当前运行状态](#十五当前运行状态)
+- [十六、待办与已知问题](#十六待办与已知问题)
+
+---
+
+## 一、项目概览
+
+### 一句话定位
+
+**一个基于每日生命周期 Loop 驱动的孕期陪护 AI 助手**：每天首次启动时自动总结昨日饮食、对比国家营养标准（DRIs/膳食指南/体重标准），生成今日简报注入对话上下文；白天与家庭成员（通过声纹区分）自然交互，实时记录饮食、推荐食谱；次日循环往复。
+
+### 技术栈
+
+| 层级 | 技术 | 用途 |
+|------|------|------|
+| 核心模型 | **MiniCPM-o 4.5**（统一多模态模型） | 全双工推理：视觉+语音+文本+语音输出 |
+| 前端框架 | **Gradio 6.x** | Web 界面，4 个子页面 |
+| 声纹识别 | 频谱统计特征（baseline） | 说话人身份识别 |
+| 频谱方案 | NumPy + SoundFile（备选 fallback） | 声纹识别兜底 |
+| 数据存储 | JSON + Markdown | 饮食记录 + 报告存档 + 每日简报 + 家庭信息 |
+| 营养标准 | 三个 MD 文件（已下载）+ 自写解析器 | 体重标准/膳食指南/DRIs |
+| 循环引擎 | 自研状态机 + 插件注册 | 每日生命周期管理 |
+| 数据提取 | 正则表达式（system prompt 标记格式） | 从对话中提取结构化数据 |
+| 部署平台 | HuggingFace Spaces（目前）+ Modal（后续） | 云端部署 |
+
+> **批注：** ________
+
+---
+
+## 二、整体文件结构
+
+```
+PregoPal/
+│
+├── app.py                          # 主入口：启动 Gradio + Loop
+├── config.py                       # 全局配置（路径/常量/数据模板）
+├── utils.py                        # 工具函数（中文字体设置/国际化/首页卡片数据）
+├── loop.py                         # 核心循环引擎（状态机驱动）
+├── requirements.txt                # 依赖清单
+├── .gitignore                      # Git 忽略规则
+├── README.md                       # 并行 Cline 协作接口文档
+│
+├── plugins/                        # Loop 插件
+│   ├── __init__.py
+│   ├── base.py                     # LoopPlugin 基类 + PluginRegistry + LoopContext
+│   ├── family_quiz.py              # 家庭菜谱/体重询问检查
+│   ├── diet_summary.py             # 昨日饮食总结
+│   ├── weight_check.py             # 体重检查（WS/T 801）
+│   ├── family_memory.py            # 家庭记忆加载
+│   ├── dri_analysis.py             # DRIs 营养素对比分析
+│   ├── briefing_generator.py       # 今日简报生成器
+│   ├── three_day_summary.py        # 每三天总结
+│   └── preset_writer.py            # 预设文件写入
+│
+├── modules/                        # 业务逻辑层（纯函数/无状态）
+│   ├── __init__.py
+│   ├── voiceprint.py               # 声纹识别
+│   ├── meal_recommender.py         # 菜品推荐
+│   ├── diet_extractor.py           # AI 回复数据提取
+│   ├── diet_logger.py              # 饮食记录存储
+│   ├── family_manager.py           # 家庭信息管理
+│   ├── nutrition_standards.py      # 中国官方营养标准
+│   └── nutrition_analyzer.py       # 营养分析与可视化
+│
+├── core/                           # AI 核心层（等待 MiniCPM-o）
+│   ├── __init__.py
+│   ├── model_loader.py             # 模型加载器（空接口）
+│   ├── voice_processor.py          # 语音处理器（空接口）
+│   ├── vision_processor.py         # 视觉处理器（空接口）
+│   └── conversation_manager.py     # 对话管理器（部分实现）
+│
+├── ui/                             # 表现层
+│   ├── __init__.py
+│   └── app_builder.py              # Gradio 界面（4 个 Tab）
+│
+├── data/                           # 持久化存储
+│   ├── nutrition/
+│   │   └── raw/                    # 三个官方 MD 文件
+│   ├── family/                     # 家庭信息
+│   │   ├── recipes.md
+│   │   ├── preferences.md
+│   │   └── memory.md
+│   ├── presets/                    # 每日简报 + 状态位
+│   ├── voices/                     # 声纹音频文件
+│   ├── logs/                       # 每日饮食日志 Markdown
+│   ├── reports/                    # 营养报告 Markdown
+│   ├── diet_logs.json              # 结构化饮食记录 JSON
+│   ├── nutrition_db.json           # 营养数据库 JSON
+│   └── family.json                 # 家庭成员声纹 JSON
+│
+├── tests/                          # 测试套件
+│   ├── __init__.py
+│   ├── run_tests.py                # 测试运行器
+│   ├── test_diet_extractor.py
+│   ├── test_family_manager.py
+│   ├── test_nutrition_standards.py
+│   ├── test_loop.py
+│   └── test_plugins.py
+│
+└── docs/                           # 文档
+    ├── 项目理解_技术架构.md
+    ├── 开发日志.md
+    └── 项目架构说明书.md            # ← 本文件
+```
+
+> **批注：** 文档中的目录结构以实际代码为准，后续新增模块/文件需同步更新此处。三代营养文档（体重标准/膳食指南/DRIs）的原始 md 文件在 `data/nutrition/raw/` 中，解析器在 `modules/nutrition_standards.py` 中硬编码了结构化数据。
+
+---
+
+## 三、app.py — 主入口
+
+### 文件路径
+
+`app.py`
+
+### 职责
+
+Gradio 应用的薄入口，不包含任何业务逻辑。启动时：
+1. 设置中文字体（调用 `utils.setup_chinese_font()`）
+2. 检查并运行每日 Loop（调用 `loop.check_and_run_loop()`）
+3. 创建 Gradio 应用（调用 `ui.app_builder.create_app()`）
+4. 启动 Gradio 服务（绑定 `0.0.0.0:7860`）
+
+### 关键代码
+
+```python
+# 启动时设置中文字体
+_CHINESE_FONT = setup_chinese_font()
+
+if __name__ == "__main__":
+    loop = check_and_run_loop()
+    demo = create_app(loop)
+    demo.launch(server_name="0.0.0.0", server_port=7860, ...)
+```
+
+### 外部依赖
+
+- `ui.app_builder.create_app` — 构建 Gradio 界面
+- `loop.check_and_run_loop` — 检查并运行每日循环
+- `utils.setup_chinese_font` — 中文字体设置
+
+> **批注：** ________
+
+---
+
+## 四、config.py — 全局配置
+
+### 文件路径
+
+`config.py`
+
+### 职责
+
+所有全局常量的集中管理。包含六大配置区：
+
+#### 4.1 目录路径
+
+| 常量 | 值 | 用途 |
+|------|-----|------|
+| `DATA_DIR` | `data/` | 数据根目录 |
+| `VOICE_DIR` | `data/voices/` | 声纹音频存储 |
+| `LOGS_DIR` | `data/logs/` | 饮食日志 Markdown |
+| `REPORTS_DIR` | `data/reports/` | 营养报告导出 |
+| `FAMILY_FILE` | `data/family.json` | 家庭成员声纹数据 |
+| `DIET_LOG_FILE` | `data/diet_logs.json` | 饮食记录 JSON |
+| `NUTRITION_DB_FILE` | `data/nutrition_db.json` | 营养数据库 |
+
+启动时自动创建所有目录。
+
+#### 4.2 常量枚举
+
+- `FAMILY_ROLES = ["孕妇", "丈夫", "婆婆", "妈妈", "爸爸", "其他家人"]`
+- `TRIMESTERS = ["孕早期", "孕中期", "孕晚期"]`
+
+#### 4.3 数据模板
+
+- `DEFAULT_NUTRITION_DB` — 10 种营养素的内置推荐数据
+- `MEAL_TEMPLATES` — 4 餐次 × 4 选项的食谱模板
+- `TRIMESTER_ADJUSTMENTS` — 各孕期阶段 focus/avoid 建议
+- `TRIMESTER_TIPS` — 各孕期阶段饮食提示字符串
+
+#### 4.4 Schema 版本
+
+- `DIET_LOG_SCHEMA_VERSION = "1.0"`
+
+#### 4.5 声纹阈值
+
+- `VOICEPRINT_SIMILARITY_THRESHOLD = 0.7`
+
+### 修改规范
+
+- 新增常量追加到同类型区域末尾，不删改已有常量名
+- 改版本号前需评估向后兼容
+- commit message 需注明新增常量的用途
+
+> **批注：** ________
+
+---
+
+## 五、utils.py — 工具函数
+
+### 文件路径
+
+`utils.py`
+
+### 职责
+
+提供通用工具函数，包含三个主要功能：
+
+#### 5.1 中文字体设置
+
+`setup_chinese_font()` — 遍历候选字体列表（SimHei → Microsoft YaHei → SimSun → ...），找到可用字体后设置 `matplotlib.rcParams`。支持 Windows 系统字体文件 fallback。
+
+#### 5.2 国际化（i18n）
+
+提供中英文字典（`ZH` / `EN`）+ `t(key, lang)` 翻译函数。
+
+字典覆盖：应用标题、4 个 Tab 名称、语音交互页标签、家庭饮食习惯页标签、三天总结页标��、营养报告页标签。
+
+#### 5.3 首页卡片数据
+
+`get_home_cards(loop)` — 从 Loop 上下文提取首页展示数据：
+- `trimester` — 孕期阶段
+- `focus_nutrients` — 营养关注点
+- `recommended_foods` — 推荐食材
+- `recipe_count` / `recipe_names` — 家庭菜谱统计
+- `yesterday_summary` / `meal_count` — 昨日饮食摘要
+- `weight_status` / `weight_trend` — 体重评估
+- `thinking_keywords` — AI 思考关键词
+
+#### 5.4 自定义 CSS
+
+`CUSTOM_CSS` — Gradio 界面样式表，包含：
+- 圆角卡片（`border-radius: 16px`）
+- 大圆形语音按钮（`160px × 160px`）
+- 状态指示灯（`green/gray dot`）
+- 聊天气泡样式
+- Tab 按钮美化
+- 响应式适配
+
+> **批注：** ________
+
+---
+
+## 六、loop.py — 核心循环引擎
+
+### 文件路径
+
+`loop.py`
+
+### 职责
+
+状态机驱动的每日生命周期管理。是 PregoPal 与「被动响应式应用」的核心区别。
+
+### 6.1 状态枚举
+
+```python
+class LoopState(Enum):
+    LAUNCH        # 启动检查：检查今日状态位
+    FAMILY_QUIZ   # 家庭问卷：检查是否需要询问菜谱/体重
+    SUMMARIZE     # 昨日总结：分析昨日饮食/体重/家庭记忆
+    ANALYZE       # 营养分析：对比 DRIs
+    BRIEF         # 生成今日简报
+    INTERACT      # 白天交互模式（等待用户操作）
+    THREE_DAY     # 每三天自动总结
+    CONSOLIDATE   # 晚间整理
+    DONE          # 标记今日完成
+```
+
+### 6.2 状态转移表
+
+```
+LAUNCH       -- need_summary  → FAMILY_QUIZ
+LAUNCH       -- already_done  → INTERACT
+FAMILY_QUIZ  -- ok            → SUMMARIZE
+SUMMARIZE    -- ok            → ANALYZE
+ANALYZE      -- ok            → BRIEF
+BRIEF        -- ok            → INTERACT
+INTERACT     -- day_ended     → CONSOLIDATE
+CONSOLIDATE  -- need_3day     → THREE_DAY
+CONSOLIDATE  -- ok            → DONE
+THREE_DAY    -- ok            → DONE
+```
+
+### 6.3 主类：`PregoPalLoop`
+
+#### 核心属性
+- `plugins` — `PluginRegistry` 实例，管理所有插件
+- `state` — 当前状态（`LoopState`）
+- `context` — `LoopContext` 实例，插件间共享数据
+
+#### 主循环
+```python
+async def run(self):
+    while self.state is not LoopState.DONE:
+        handler = getattr(self, f"_state_{self.state.value}")
+        event = await handler()
+        next_state = _TRANSITIONS[(self.state, event)]
+        self.state = next_state
+```
+
+#### 状态处理器（9 个）
+每个状态对应一个 `_state_xxx` 异步方法，负责执行该阶段逻辑或调用对应插件。
+
+#### 外部接口
+- `get_briefing()` → `dict`（获取今日简报）
+- `get_thinking_keywords()` → `str`（获取 AI 思考关键词）
+- `get_errors()` → `list[str]`（获取错误列表）
+- `run_sync()` → 同步运行入口
+
+### 6.4 状态位管理：`DailyStatus`
+
+管理 `data/presets/.daily_status.json`，记录每日完成状态。
+
+关键方法：
+- `is_today_done()` — 检查今日是否已完成
+- `mark_summary_done()` — 标记今日总结完成
+- `mark_day_ended()` — 标记今日结束
+- `days_since_last_summary()` — 距离上次总结天数
+- `should_three_day_summary()` — 是否需要进行三天总结
+
+### 6.5 便捷函数
+
+- `run_daily_loop()` — 创建并运行每日循环
+- `check_and_run_loop()` — 检查状态位后决定是否运行循环（供 Gradio 启动时调用）
+
+> **批注：** 状态机设计根据目的迭代。INTERACT 状态目前是简单的 `return "day_ended"`，实际使用时需通过 Gradio 事件队列触发状态转换。三天的触发条件在 `DailyStatus.should_three_day_summary()` 中定义为 `days_since_last_summary() >= 3`。
+
+---
+
+## 七、plugins/ — 插件系统
+
+### 7.1 基类与注册中心
+
+**文件：** `plugins/base.py`
+
+核心类型：
+
+| 类型 | 说明 |
+|------|------|
+| `LoopStage` | 阶段枚举：`FAMILY_QUIZ`, `SUMMARIZE`, `ANALYZE`, `BRIEF`, `THREE_DAY`, `CONSOLIDATE` |
+| `LoopContext` | 插件间共享数据容器（`briefing`, `weight_data`, `diet_records`, `family_recipes`, `family_memory`, `analysis_results`, `errors`） |
+| `PluginResult` | 插件执行结果（`success`, `data`, `message`） |
+| `LoopPlugin` | 插件抽象基类（`stage()`, `name()`, `run(ctx)`） |
+| `PluginRegistry` | 注册中心（`register`, `get_plugins`, `get_all`, `unregister`） |
+
+### 7.2 插件清单
+
+| 插件名 | 类名 | 注册阶段 | 文件 | 功能 | 数据源 |
+|--------|------|---------|------|------|--------|
+| 家庭菜谱检查 | `FamilyRecipeQuizPlugin` | `FAMILY_QUIZ` | `family_quiz.py` | 检查是否需要询问新菜谱 | `data/family/recipes.md` |
+| 体重询问检查 | `WeightQuizPlugin` | `FAMILY_QUIZ` | `family_quiz.py` | 检查是否需要询问体重 | `data/logs/` |
+| 昨日饮食总结 | `DietSummaryPlugin` | `SUMMARIZE` | `diet_summary.py` | 读取昨日饮食日志，汇总三餐 | `data/logs/饮食日志_*.md` |
+| 体重检查 | `WeightCheckPlugin` | `SUMMARIZE` | `weight_check.py` | 检查体重记录，对比 WS/T 801 | `WeightStandardParser` |
+| 家庭记忆加载 | `FamilyMemoryPlugin` | `SUMMARIZE` | `family_memory.py` | 加载家庭关系/事件记忆 | `data/family/memory.md` |
+| DRIs 分析 | `DRIAnalysisPlugin` | `ANALYZE` | `dri_analysis.py` | 对比营养素参考摄入量 | `DRIsParser` + 昨日饮食 |
+| 简报生成 | `BriefingGeneratorPlugin` | `BRIEF` | `briefing_generator.py` | 汇总分析为结构化 JSON | `LoopContext` |
+| 三天总结 | `ThreeDaySummaryPlugin` | `THREE_DAY` | `three_day_summary.py` | 分析营养缺失趋势，改进家庭菜单 | 近三天饮食记录 |
+| 预设写入 | `PresetWriterPlugin` | `CONSOLIDATE` | `preset_writer.py` | 生成明日预设文件 | `data/presets/` |
+
+### 7.3 插件向 `ctx.briefing` 写入的 Key
+
+```
+trimester              # str
+need_ask_weight        # bool
+weight_quiz_message    # str
+weight_evaluation      # dict
+need_ask_recipe        # bool
+recipe_quiz_message    # str
+yesterday_diet         # dict {"status","summary","meal_count"}
+dri_analysis           # dict {"focus_nutrients","summary","comparison_table"}
+recommended_foods      # list[str]
+family_memory          # dict
+thinking_keywords      # str
+three_day_summary      # dict（仅 THREE_DAY 阶段）
+```
+
+### 7.4 扩展方式
+
+```python
+# 新增功能只需两步：
+class NewPlugin(LoopPlugin):
+    def stage(self) -> LoopStage: return LoopStage.SUMMARIZE
+    def name(self) -> str: return "new_feature"
+    async def run(self, ctx: LoopContext) -> PluginResult: ...
+
+loop.plugins.register(NewPlugin())
+# 不需要修改 loop.py 的状态机代码
+```
+
+> **批注：** ________
+
+---
+
+## 八、modules/ — 业务逻辑层
+
+### 8.1 声纹识别 — `modules/voiceprint.py`
+
+**类：** `VoiceprintManager`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `register_member(name, relation, audio_path)` | str, str, str | (dict\|None, str) | 注册新成员声纹 |
+| `identify_speaker(audio_path)` | str | (dict\|None, str) | 识别说话人 |
+| `get_members_list()` | — | str | 格式化成员列表 |
+| `delete_member(member_id)` | str | str | 删除指定成员 |
+
+**技术方案：**
+- 当前：频谱统计特征（mean/std/max/min/zero_crossing_rate/energy/duration）
+- 后续：Whisper-medium encoder embedding
+
+**数据存储：** `data/family.json`（JSON 格式）
+```json
+{
+  "members": [{"id", "name", "relation", "registered_at", "audio_path", "features"}],
+  "voiceprints": {"member_id": {"mean": ..., "std": ..., ...}}
+}
+```
+
+依赖：`config.VOICE_DIR`、`config.FAMILY_FILE`、`config.VOICEPRINT_SIMILARITY_THRESHOLD`（默认 0.7）
+
+> **批注：** 当前为频谱统计特征 baseline，后续升级 Whisper encoder 时需保持 `register_member`/`identify_speaker` 签名不变。
+
+---
+
+### 8.2 菜品推荐 — `modules/meal_recommender.py`
+
+**类：** `MealRecommender`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `get_recommendation(preference, trimester, restrictions)` | str, str, str | dict | 返回今日推荐食谱 |
+| `format_meal_plan(recommendation)` | dict | str | 格式化为可读文本 |
+
+**输出 schema：**
+```json
+{
+  "date": "2026-06-09",
+  "trimester": "孕中期",
+  "preference": "想吃清淡的",
+  "focus": "补充蛋白质、钙、铁",
+  "meals": {"早餐": "...", "午餐": "...", "晚餐": "...", "加餐": "..."},
+  "tips": ["🌿 ...", "💡 ..."]
+}
+```
+
+**当前方案：** 随机模板推荐（从 `config.MEAL_TEMPLATES` 中随机选取）
+**后续方案：** MiniCPM-o 4.5 AI 对话推荐
+
+> **批注：** 当前为随机模板推荐。后续对接 AI 对话推荐时需保持 `get_recommendation` 签名，内部逻辑可任意替换。
+
+---
+
+### 8.3 AI 对话数据提取 — `modules/diet_extractor.py`
+
+**类：** `DietExtractor`（全静态方法）
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `extract_all(text)` | str | dict | 正则提取所有结构化数据 |
+| `fallback_extract_diet(text)` | str | dict\|None | 关键词 fallback 提取饮食 |
+| `fallback_extract_thinking(text)` | str | dict\|None | 关键词 fallback 提取思考 |
+| `robust_extract(text)` | str | dict | 正则优先 → fallback 兜底 |
+
+**extract_all 返回 schema：**
+```json
+{
+  "diets": [{"meals": {"早餐": "...", "午餐": "..."}, "日期": "...", "记录人": "...", "备注": "..."}],
+  "recipes": [{"菜名": "...", "制作人": "...", "难度": "...", "食材": "...", "备注": "..."}],
+  "preferences": [{"人员": "...", "类型": "偏好/忌口/过敏", "内容": "..."}],
+  "weights": [{"日期": "...", "体重": "...", "记录人": "..."}],
+  "memories": [{"类型": "关系/事件/日常", "内容": "..."}],
+  "thinking": {"当前步骤": "...", "下一步": "..."}
+}
+```
+
+**Markdown 提取标记格式**（需在 system prompt 中告知模型使用）：
+```
+[EXTRACT_DIET]...[/EXTRACT_DIET]
+[EXTRACT_RECIPE]...[/EXTRACT_RECIPE]
+[EXTRACT_PREFERENCE]...[/EXTRACT_PREFERENCE]
+[EXTRACT_WEIGHT]...[/EXTRACT_WEIGHT]
+[EXTRACT_MEMORY]...[/EXTRACT_MEMORY]
+[THINKING]...[/THINKING]
+```
+
+**辅助函数：** `get_extract_prompt(date_str=None) → str` — 返回含日期占位符的 System Prompt 模板
+
+> **批注：** ________
+
+---
+
+### 8.4 饮食记录存储 — `modules/diet_logger.py`
+
+**类：** `DietLogger`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `add_record(member_name, member_relation, date, meals, mood, notes)` | str, str, str, dict, str, str | (record, md_path) | JSON + MD 双写 |
+| `get_recent_records(days=7)` | int | list[dict] | 获取近 N 天记录 |
+| `get_all_markdown_files()` | — | list[Path] | 所有 MD 日志文件 |
+| `parse_diet_record(text) — static` | str | dict\|None | [DIET_RECORD] 标记解析 |
+
+**add_record 返回的 record schema：**
+```json
+{
+  "id": "a1b2c3d4",
+  "member_name": "小红",
+  "member_relation": "孕妇",
+  "date": "2026-06-09",
+  "meals": {"早餐": "燕麦粥+坚果", "午餐": "清蒸鱼+米饭"},
+  "mood": "挺好",
+  "notes": "今天胃口不错",
+  "extensions": {},
+  "created_at": "2026-06-09T12:00:00"
+}
+```
+
+**双写机制：**
+1. `data/diet_logs.json` — 结构化 JSON（所有记录累积）
+2. `data/logs/饮食日志_YYYY-MM-DD.md` — 每日可读 Markdown
+
+> **批注：** schema 已加版本号，`extensions: {}` 字段可向后兼容扩展。
+
+---
+
+### 8.5 家庭信息管理 — `modules/family_manager.py`
+
+三个管理器类，全部使用 `@classmethod`：
+
+#### RecipeManager — 家庭菜谱
+| 方法 | 说明 |
+|------|------|
+| `load_all()` → `list[dict]` | 读取所有菜谱 |
+| `add_recipe(name, cook, difficulty, ingredients, notes)` → `str` | 添加菜谱 |
+| `get_names()` → `list[str]` | 所有菜名 |
+| `format_for_prompt()` → `str` | System Prompt 格式 |
+
+菜谱 dict：`{"name", "cook", "difficulty", "ingredients", "notes"}`
+
+#### PreferenceManager — 饮食偏好
+| 方法 | 说明 |
+|------|------|
+| `load_all()` → `list[dict]` | 所有成员偏好 |
+| `add_member(name, role, preferences, avoid, allergies, notes)` → `str` | 添加/更新（覆盖同名） |
+| `format_for_prompt()` → `str` | System Prompt 格式 |
+
+偏好 dict：`{"name", "role", "preferences", "avoid", "allergies", "notes"}`
+
+#### MemoryManager — 家庭记忆
+| 方法 | 说明 |
+|------|------|
+| `load_all()` → `dict` | 所有记忆（relationships/events/daily） |
+| `add_event(description)` → `str` | 添加重要事件 |
+| `add_daily(content)` → `str` | 添加日常记录 |
+| `format_for_prompt()` → `str` | System Prompt 格式 |
+
+#### 统一接口
+- `load_all_family_info() → dict` — 一次性加载所有家庭信息
+- `format_all_for_prompt() → str` — 全量 System Prompt 文本
+
+#### 数据文件（`data/family/`）
+| 文件 | 示例内容 |
+|------|---------|
+| `recipes.md` | 5 道菜谱（番茄牛腩/清蒸鲈鱼/鲫鱼豆腐汤/番茄炒蛋/红枣枸杞鸡汤） |
+| `preferences.md` | 3 位成员（小红-孕妇/小明-丈夫/张阿姨-婆婆） |
+| `memory.md` | 家庭关系 + 重要事件 + 日常记录 |
+
+> **批注：** 更新 `add_member` 覆盖逻辑时注意保留已有数据。
+
+---
+
+### 8.6 营养标准 — `modules/nutrition_standards.py`
+
+三个只读数据类，全部使用 `@classmethod`：
+
+#### BMIStandards — 体重增长标准
+| 方法 | 说明 |
+|------|------|
+| `get_standard(bmi_before_pregnancy)` → `dict` | 根据孕前 BMI 获取标准 |
+| `evaluate(bmi_before_pregnancy, current_week, total_gain)` → `dict` | 评估体重增长是否在推荐范围内 |
+| `load()` → `dict` | 兼容接口 |
+
+4 个 BMI 分类（低体重/正常/超重/肥胖）的硬编码标准（WS/T 801-2022 表1）。
+
+#### DietaryGuideStandards — 膳食指南
+| 方法 | 说明 |
+|------|------|
+| `get_recommendations(trimester)` → `dict` | 返回指定孕期食物推荐量 |
+| `get_core_principles()` → `list[str]` | 六条核心建议 |
+| `format_for_prompt(trimester)` → `str` | System Prompt 格式 |
+
+4 个阶段（备孕/孕中期/孕晚期/哺乳期）的平衡膳食宝塔数据。
+
+#### DRIsParser — 膳食营养素参考摄入量
+| 方法 | 说明 |
+|------|------|
+| `get_rni(stage)` → `dict` | 返回指定阶段 RNI 数据 |
+| `compare_with_intake(stage, intake)` → `dict` | 对比实际摄入与 RNI |
+| `format_comparison_table(comparisons)` → `str` | 格式化为文本对比表 |
+
+12 种营养素的 RNI 数据（4 阶段），含分类和推荐食物源。
+
+#### 统一接口
+- `load_all_standards() → dict` — 加载所有标准
+- `compile_standards_to_presets()` — 编译为 JSON 缓存
+
+> **批注：** ________
+
+---
+
+### 8.7 营养分析与可视化 — `modules/nutrition_analyzer.py`
+
+**类：** `NutritionAnalyzer`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `analyze_diet(records)` | list[dict] | dict | 营养覆盖分析 |
+| `generate_report_chart(analysis)` | dict | matplotlib Figure | 4 面板可视化图表 |
+| `generate_report_text(analysis)` | dict | str | 文本格式报告 |
+| `export_report_markdown(analysis, filename)` | dict, str | Path | 导出 Markdown 报告 |
+
+**analyze_diet 返回 schema：**
+```json
+{
+  "total_days": 7,
+  "total_records": 21,
+  "meal_counts": {"早餐": 5, "午餐": 6, "晚餐": 6, "加餐": 4},
+  "food_items": ["全麦面包", "鸡蛋", ...],
+  "nutrition_coverage": {
+    "叶酸": {"matched_foods": ["菠菜"], "covered": true, ...},
+    ...
+  },
+  "diversity_score": {"score": 75, "details": [...]},
+  "suggestions": ["⚠️ 以下营养素摄入不足: 铁, 钙", ...]
+}
+```
+
+**图表布局（4 面板）：**
+1. 左上：营养覆盖雷达图
+2. 右上：各餐次频率柱状图
+3. 左下：饮食多样性评分环形图
+4. 右下：营养建议文本框
+
+> **批注：** **高优先级待改造** — 当前使用通用 `DEFAULT_NUTRITION_DB` 做营养覆盖分析，尚未对接 `modules/nutrition_standards.py` 的 DRIs 数据。改造时需保持 `analyze_diet(records) -> dict` 签名不变。
+
+---
+
+## 九、core/ — AI 核心层
+
+### 文件路径
+
+`core/` 目录下所有文件当前均为「空接口」状态，等待 MiniCPM-o 4.5 部署后填充。
+
+### 9.1 `__init__.py`
+
+空模块，标注等待 MiniCPM-o 部署。
+
+### 9.2 `model_loader.py`
+
+**类：** `ModelLoader`
+
+| 方法 | 说明 |
+|------|------|
+| `load()` | 加载模型（`raise NotImplementedError`） |
+| `unload()` | 卸载模型释放显存 |
+
+### 9.3 `voice_processor.py`
+
+**类：** `VoiceProcessor`
+
+| 方法 | 说明 |
+|------|------|
+| `transcribe(audio_path)` | 语音转文字（`raise NotImplementedError`） |
+| `extract_speaker_embedding(audio_path)` | 提取说话人声纹 embedding（`raise NotImplementedError`） |
+
+### 9.4 `vision_processor.py`
+
+**类：** `VisionProcessor`
+
+| 方法 | 说明 |
+|------|------|
+| `analyze_frame(image_path)` | 分析单帧图像（`raise NotImplementedError`） |
+
+### 9.5 `conversation_manager.py`
+
+**类：** `ConversationManager`
+
+当前已有部分骨架实现：
+- `current_mode` / `current_speaker` / `conversation_history`
+- `switch_mode(mode)` / `set_speaker(speaker_info)`
+- `parse_response(response)` — 解析 `[DIET_RECORD]` 标记
+
+待实现：
+- `build_system_prompt()` — 构建完整系统提示词
+
+> **批注：** ________
+
+---
+
+## 十、ui/ — 表现层
+
+### 文件路径
+
+`ui/app_builder.py`
+
+### 职责
+
+基于 Gradio 6.x 构建 4 个子页面的 Web 界面。
+
+### 10.1 主入口
+
+`create_app(loop=None)` — 创建 Gradio Blocks 应用。
+
+设计要点：
+- 只使用 **一个** `@gr.render` 包裹所有 Tab，避免多个 `@gr.render` 并发触发导致 `RuntimeError`
+- 语言切换通过 `gr.State(value="zh")` + `lang_selector` Radio 实现
+- 每个 Tab 的标题通过 `t()` 函数实现中英文切换
+
+### 10.2 页面结构
+
+| Tab | ID | 功能说明 |
+|-----|-----|---------|
+| 🏠 首页 | `tab_home` | 语音启动按钮 + AI 思考状态 + 5 个信息卡片 + 最近饮食记录表格 |
+| 👨‍👩‍👧‍👦 家庭饮食习惯 | `tab_family` | 3 个子 Tab：偏好设置 / 菜谱管理 / 家庭记忆 |
+| 📊 三天总结 | `tab_summary` | 孕期阶段选择 + 分析结果 + 菜单改进建议 |
+| 📈 营养报告 | `tab_report` | 天数滑块 + 文本报告 + 可视化图表 + 导出 Markdown |
+
+### 10.3 全局实例
+
+```python
+voiceprint_mgr = VoiceprintManager()
+meal_recommender = MealRecommender()
+diet_logger = DietLogger()
+nutrition_analyzer = NutritionAnalyzer()
+```
+
+> **批注：** ________
+
+---
+
+## 十一、data/ — 数据存储
+
+### 11.1 数据文件一览
+
+| 文件/目录 | 格式 | 内容 | 读模块 | 写模块 |
+|-----------|------|------|--------|--------|
+| `data/diet_logs.json` | JSON | 所有饮食记录（累积） | `diet_logger`, `nutrition_analyzer` | `diet_logger` |
+| `data/nutrition_db.json` | JSON | 10 种营养素数据 | `nutrition_analyzer` | `nutrition_analyzer` |
+| `data/family.json` | JSON | 成员声纹数据 | `voiceprint` | `voiceprint` |
+| `data/family/recipes.md` | Markdown | 5 道家庭菜谱 | `family_manager.RecipeManager` | `family_manager.RecipeManager` |
+| `data/family/preferences.md` | Markdown | 3 位成员偏好 | `family_manager.PreferenceManager` | `family_manager.PreferenceManager` |
+| `data/family/memory.md` | Markdown | 家庭关系/事件/日常 | `family_manager.MemoryManager` | `family_manager.MemoryManager` |
+| `data/logs/饮食日志_*.md` | Markdown | 每日饮食记录 | `plugins/diet_summary` | `diet_logger` |
+| `data/reports/营养报告_*.md` | Markdown | 营养分析报告 | 用户 | `nutrition_analyzer` |
+| `data/presets/.daily_status.json` | JSON | 每日完成状态 | `loop.DailyStatus` | `loop.DailyStatus` |
+| `data/presets/今日简报_*.json` | JSON | 每日简报缓存 | `loop` | `plugins/preset_writer` |
+| `data/voices/*.wav` | WAV | 声纹注册音频 | `voiceprint` | `voiceprint` |
+| `data/nutrition/raw/*.md` | Markdown | 三个官方营养文档 | 解析器 | 手动下载 |
+
+### 11.2 家庭信息示例数据
+
+**`recipes.md`**：5 道菜谱（番茄牛腩/清蒸鲈鱼/鲫鱼豆腐汤/番茄炒蛋/红枣枸杞鸡汤）
+
+**`preferences.md`**：
+- 小红（孕妇）：爱吃水果/鱼/清淡，不吃辣/油腻，芒果过敏
+- 小明（丈夫）：爱吃肉/面食，不吃香菜
+- 张阿姨（婆婆）：会做各种汤
+
+**`memory.md`**：
+- 3 条家庭关系
+- 3 条重要事件（2026-06-07 ~ 06-09）
+- 3 条日常记录
+
+### 11.3 状态位文件
+
+```json
+{
+  "2026-06-09": {
+    "summary_done": true,
+    "completed_at": "2026-06-09T00:40:53.606526"
+  }
+}
+```
+
+### 11.4 营养标准原始文档
+
+`data/nutrition/raw/` 中的三个 MD 文件：
+1. `妊娠期妇女体重增长推荐值标准.md`（WS/T 801-2022）
+2. `中国孕期妇女膳食指南2022图片转md版.md`
+3. `备孕&孕早中晚三期和哺乳期的所有膳食营养素参考摄入量.md`
+
+> **批注：** 所有 md 文件都需要我们自己写函数读取，而不是让大模型自己读。数据类的需要写全面的读取比较函数接口，文本类的需要设计好自动提取输出的函数。
+
+---
+
+## 十二、tests/ — 测试套件
+
+### 12.1 测试运行器
+
+**文件：** `tests/run_tests.py`
+
+无需 pytest，内置 `TestRunner` 类：
+- 自动发现 `test_*.py` 中的 `Test*` 类和方法
+- 每个测试方法独立实例（setup/teardown 隔离）
+- 生成 HTML 和 JSON 两种报告格式
+
+运行方式：
+```bash
+python tests/run_tests.py
+```
+
+### 12.2 测试覆盖
+
+| 测试文件 | 覆盖内容 | 状态 |
+|---------|---------|------|
+| `test_diet_extractor.py` | 正则解析 + fallback 提取（18 个测试用例） | ✅ |
+| `test_family_manager.py` | 菜谱/偏好/记忆 CRUD | ✅ |
+| `test_nutrition_standards.py` | BMI/膳食指南/DRIs 数据 | ✅ |
+| `test_loop.py` | 循环执行测试 | 待确认 |
+| `test_plugins.py` | 插件集成测试 | 待确认 |
+
+> **批注：** ________
+
+---
+
+## 十三、配置文件
+
+### 13.1 `.gitignore`
+
+```gitignore
+.vscode/           # IDE 配置
+__pycache__/       # Python 缓存
+*.pyc / *.pyo
+*.egg-info/ / dist/ / build/
+*.gguf / models/   # 模型文件
+llamacpp/
+*.wav / *.mp3      # 音频文件
+.env / .venv/ / venv/
+*.tmp / *.log / debug*.txt
+_check_hf.py / _download_models.py
+```
+
+### 13.2 `requirements.txt`
+
+```
+gradio>=6.0.0
+modal>=0.60.0
+numpy>=1.24.0
+matplotlib>=3.7.0
+pandas>=2.0.0
+soundfile>=0.12.0
+pillow>=10.0.0
+```
+
+> **批注：** 依赖相对精简，核心依赖为 Gradio 6.x + NumPy + Matplotlib。后续集成 MiniCPM-o 后可能需要追加 PyTorch / Transformers 等。
+
+---
+
+## 十四、协作规范与 Git 工作流
+
+### 14.1 并行 Cline 分工建议
+
+```
+Cline A: Modules 强化（营养分析对接 DRIs、菜谱推荐 AI 化）
+Cline B: UI 界面优化（Gradio 前端增强、报告模板美化）
+Cline C: 声纹升级（Whisper encoder 替换频谱特征）
+Cline D: 数据处理与插件增强（diet_extractor fallback、新插件）
+```
+
+### 14.2 关键约定
+
+1. **改接口前先 grep**：用 `search_files` 搜索方法名找到所有调用方
+2. **config.py 修改需沟通**：新增常量追加到同类型区域，不删改已有常量名
+3. **数据文件向后兼容**：新增字段优先用 `extensions: {}` 或新增可选 key，不删除已有 key
+4. **测试保持通过**：`python tests/run_tests.py` 零失败
+5. **README 同步更新**：接口签名变更 → 更新 README 对应章节
+
+### 14.3 Git 工作流
+
+```bash
+# 工作前
+git pull --rebase origin main
+
+# 开发中：每完成一个独立功能点就提交
+git add -A
+git commit -m "feat/fix/test/refactor/docs/chore: 描述"
+
+# 推送前再次 pull
+git pull --rebase origin main
+
+# 测试通过后推送
+python tests/run_tests.py
+git push origin main
+```
+
+### 14.4 Commit Message 规范
+
+```
+feat:     新功能/新模块/新接口
+fix:      修复 bug
+test:     添加或修改测试
+refactor: 重构（不改功能）
+docs:     文档更新
+chore:    配置/依赖/路径调整
+```
+
+### 14.5 冲突处理策略
+
+| 冲突类型 | 处理方式 |
+|---------|---------|
+| `config.py` 常量冲突 | 取并集，双方新增常量都保留 |
+| 同函数不同实现 | 保留逻辑更完整的一方，另一方的无冲突改动合并到合适位置 |
+| 数据文件（JSON/MD）冲突 | 保留两个版本共有的条目 + 各自独有条目（去重） |
+| 测试文件冲突 | **取并集**：保留所有测试用例 |
+| 本架构说明书冲突 | **取行数更长的一方**，手动整合 |
+| `.gitignore` 冲突 | 取并集 |
+
+> **批注：** ________
+
+---
+
+## 十五、当前运行状态
+
+| 项目 | 状态 |
+|------|------|
+| Gradio 6.16.0 运行端口 | `localhost:7860` |
+| 4 个 Tab | 全部正常加载 |
+| 声纹识别 | 可用（频谱统计 baseline） |
+| 菜品推荐 | 可用（随机模板） |
+| 饮食记录 | 可用（JSON + MD 双写） |
+| 营养分析 | 可用（内置数据库） |
+| 每日 Loop | 可用（状��机驱动） |
+| core/ 层 | 空接口（等待 MiniCPM-o） |
+| Modal 部署 | 代码就绪，CUDA 编译中 |
+| Git 远程 | HuggingFace Spaces `build-small-hackathon/PregoPal` |
+
+---
+
+## 十六、待办与已知问题
+
+### 16.1 高优先级
+
+- [ ] **营养分析对接 DRIs**：`NutritionAnalyzer` 当前使用内置 `DEFAULT_NUTRITION_DB`，需替换为 `DRIsParser` 的中国官方标准
+- [ ] **菜谱推荐 AI 化**：当前为随机模板，后续需对接 MiniCPM-o 对话推荐
+
+### 16.2 中优先级
+
+- [ ] **core/ 层实现**：MiniCPM-o 4.5 模型加载、语音/视觉处理
+- [ ] **声纹升级**：从频谱统计特征升级到 Whisper encoder embedding
+- [ ] **INTERACT 状态激活**：当前 `_state_interact()` 直接返回 `day_ended`，需对接 Gradio 事件队列
+
+### 16.3 低优先级
+
+- [ ] **测试补全**：`test_loop.py` 和 `test_plugins.py` 需确认状态
+- [ ] **Modal 部署修复**：`@modal.concurrent` 兼容性、`build_server_args` 参数命名、多模态端点验证
+- [ ] **data/nutrition/raw/ 中 MD 文件的解析**：当前营养标准数据为硬编码，后续可从原始 MD 文件中自动解析
+
+> **批注：** ________
+
+---
+
+*文档生成时间：2026-06-09 | 由 PregoPal 项目架构说明书 v1 生成*
+
+*本文档各小节批注区中的原始文字为项目负责人的重要参考依据，所有 Cline 在修改对应模块前应先阅读对应批注。*