docs: 添加完整接口说明文档，包含架构图、模块接口表、数据schema、并行协作规范

README.md

@@ -12,7 +12,568 @@ license: mit
 short_description: Voice-based Pregnant Meal & Nutrition Tracker
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PregoPal — 孕期陪护 AI 助手
 
+> **并行 Cline 协作接口文档**  
+> 每个 Cline 在修改模块前，先 `git pull --rebase`；修改完成后立即 `git commit && git push`。
 
-Model to be Used: MiniCPM-o 4.5
+---
+
+## 1. 项目概述
+
+PregoPal 是一款面向孕期家庭的 AI 陪护工具，支持：
+
+| 功能 | 状态 | 负责模块 |
+|------|------|----------|
+| 🎤 声纹识别与家庭成员区分 | 基线可用 | `modules/voiceprint.py` |
+| 🍽️ 今日菜品推荐（营养+家庭能力） | 基线可用 | `modules/meal_recommender.py` |
+| 📝 饮食记录储存（JSON + Markdown） | 已实现 | `modules/diet_logger.py` + `modules/diet_extractor.py` |
+| 📊 营养分析与可视化报告 | 基线可用 | `modules/nutrition_analyzer.py` + `modules/nutrition_standards.py` |
+
+**技术栈**: Python 3.13 · Gradio 6.16 · MiniCPM-o 4.5 · Matplotlib · Pandas
+
+---
+
+## 2. 架构总览
+
+```
+app.py                          ← Gradio 薄入口
+├── ui/app_builder.py           ← 前端 Tab 布局（饮食记录/营养分析/家庭管理/声纹/菜品推荐/环境配置）
+├── loop.py                     ← 每日自动分析循环（状态机）
+│   ├── plugins/base.py         ← 插件基类（LoopPlugin, PluginRegistry, LoopContext）
+│   ├── plugins/family_quiz.py  ← 家庭问卷插件（菜谱/体重检查）
+│   ├── plugins/diet_summary.py ← 昨日饮食总结
+│   ├── plugins/weight_check.py ← 体重检查插件
+│   ├── plugins/family_memory.py← 家庭记忆处理
+│   ├── plugins/dri_analysis.py ← DRIs 营养对比分析
+│   ├── plugins/briefing_generator.py ← 今日简报生成
+│   ├── plugins/three_day_summary.py  ← 每三天综合总结
+│   └── plugins/preset_writer.py      ← 预设/缓存写入
+├── modules/                    ← 核心业务逻辑（纯函数/无状态）
+│   ├── voiceprint.py           ← 声纹识别
+│   ├── meal_recommender.py     ← 菜品推荐
+│   ├── diet_extractor.py       ← AI 回复数据提取
+│   ├── diet_logger.py          ← 饮食记录存储
+│   ├── family_manager.py       ← 家庭信息管理
+│   ├── nutrition_standards.py  ← 中国官方营养标准
+│   ├── nutrition_analyzer.py   ← 营养分析与可视化
+│   └── core/                   ← 核心能力层
+│       ├── model_loader.py     ← MiniCPM-o 模型加载
+│       ├── voice_processor.py  ← 语音处理
+│       ├── vision_processor.py ← 视觉处理
+│       └── conversation_manager.py ← 对话管理
+├── config.py                   ← 全局配置（路径/常量/数据模板）
+├── utils.py                    ← 工具函数（中文字体设置等）
+└── data/                       ← 持久化存储
+    ├── diet_logs.json          ← 结构化饮食记录 JSON
+    ├── nutrition_db.json       ← 营养数据库 JSON
+    ├── family.json             ← 家庭成员声纹 JSON
+    ├── family/                 ← 家庭信息 Markdown（recipes/preferences/memory）
+    ├── logs/                   ← 每日饮食日志 Markdown
+    ├── presets/                ← 预设/缓存 + .daily_status.json
+    ├── reports/                ← 营养报告 Markdown
+    ├── voices/                 ← 声纹音频文件
+    └── nutrition/              ← 营养标准原始文档
+```
+
+---
+
+## 3. 核心模块接口说明
+
+> **约定**：模块间通过函数调用传递数据。所有返回 dict 的接口，其 key 约定在下方列出。  
+> **修改清单**：改任何模块的输入/输出签名时，必须同步更新本 README 对应条目。
+
+### 3.1 声纹识别 — `modules/voiceprint.py`
+
+类：`VoiceprintManager`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `register_member(name, relation, audio_path)` | `name: str`, `relation: str`, `audio_path: str` (Path) | `(member_info: dict\|None, msg: str)` | 注册新成员声纹，返回 `{"id","name","relation","registered_at","audio_path","features"}` |
+| `identify_speaker(audio_path)` | `audio_path: str` (Path) | `(member_info: dict\|None, msg: str)` | 识别说话人，需声纹库非空 |
+| `get_members_list()` | — | `str` (格式化文本) | 获取已注册成员列表 |
+| `delete_member(member_id)` | `member_id: str` | `str` (结果消息) | 删除指定成员 |
+
+**依赖**:
+- `VOICE_DIR`（`data/voices/`）从 `config.py` 导入
+- `FAMILY_FILE`（`data/family.json`）— JSON 格式 `{"members": [...], "voiceprints": {...}}`
+- `config.VOICEPRINT_SIMILARITY_THRESHOLD`（默认 0.7）
+
+**内部数据结构**（`data/family.json`）:
+```json
+{
+  "members": [
+    {
+      "id": "abc12345",
+      "name": "小红",
+      "relation": "孕妇",
+      "registered_at": "2026-06-09T07:00:00",
+      "audio_path": "data/voices/abc12345.wav",
+      "features": {"mean": 0.01, "std": 0.05, "max": 0.5, "min": -0.5, "zero_crossing_rate": 0.3, "energy": 0.001, "duration": 3.5}
+    }
+  ],
+  "voiceprints": {
+    "abc12345": {"mean": 0.01, ...}
+  }
+}
+```
+
+> ⚠️ **风险等级：中** — 当前使用频谱统计特征（baseline），后续升级 Whisper encoder 需保持 `register_member`/`identify_speaker` 签名不变。
+
+---
+
+### 3.2 菜品推荐 — `modules/meal_recommender.py`
+
+类：`MealRecommender`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `get_recommendation(preference, trimester, restrictions)` | `preference: str=""`, `trimester: str="孕中期"`, `restrictions: str=""` | `dict` | 返回今日推荐食谱 |
+| `format_meal_plan(recommendation)` | `recommendation: dict`（上一个方法的返回值） | `str` | 格式化为可读文本 |
+
+**输出 dict schema**（`get_recommendation` 返回）:
+```json
+{
+  "date": "2026-06-09",
+  "trimester": "孕中期",
+  "preference": "想吃清淡的",
+  "focus": "补充蛋白质、钙、铁",
+  "meals": {
+    "早餐": "小米粥+包子+煮鸡蛋",
+    "午餐": "番茄牛腩+杂粮饭+凉拌黄瓜",
+    "晚餐": "蒸蛋羹+小米粥+炒青菜",
+    "加餐": "酸奶+坚果"
+  },
+  "tips": ["🌿 孕中期建议：...", "💡 建议每天饮水..."]
+}
+```
+
+**依赖**:
+- `config.MEAL_TEMPLATES`（4 餐次 × 4 选项的食谱模板 dict）
+- `config.TRIMESTER_ADJUSTMENTS`（各孕期阶段的 focus/avoid 建议）
+- `config.TRIMESTER_TIPS`（各孕期阶段的饮食提示字符串）
+
+> ⚠️ **风险等级：中** — 当前为随机模板推荐。后续对接 AI 对话推荐时需保持 `get_recommendation` 签名，内部逻辑可任意替换。
+
+---
+
+### 3.3 AI 对话数据提取 — `modules/diet_extractor.py`
+
+类：`DietExtractor`（全静态方法）
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `extract_all(text)` | `text: str` (AI 回复全文) | `dict` | 正则提取所有结构化数据 |
+| `fallback_extract_diet(text)` | `text: str` | `dict\|None` | 关键词 fallback 提取饮食 |
+| `fallback_extract_thinking(text)` | `text: str` | `dict\|None` | 关键词 fallback 提取思考 |
+| `robust_extract(text)` | `text: str` | `dict` | 正则优先 → fallback 兜底 |
+
+**`extract_all` 返回 dict schema**:
+```json
+{
+  "diets": [
+    {
+      "meals": {"早餐": "全麦面包+鸡蛋+牛奶", "午餐": "清蒸鱼", "晚餐": "", "加餐": ""},
+      "日期": "2026-06-09",
+      "记录人": "孕妇",
+      "备注": "孕妇吃了"
+    }
+  ],
+  "recipes": [{"菜名": "清蒸鱼", "制作人": "丈夫", "难度": "简单", "食材": "鱼、姜", "备注": ""}],
+  "preferences": [{"人员": "孕妇", "类型": "偏好", "内容": "爱吃酸"}],
+  "weights": [{"日期": "2026-06-09", "体重": "65", "记录人": "孕妇自己"}],
+  "memories": [{"类型": "事件", "内容": "婆婆今天来家里"}],
+  "thinking": {"当前步骤": "记录饮食", "下一步": "分析营养"}  // or None
+}
+```
+
+**Markdown 提取标记格式**（AI 回复中需含）:
+```
+[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 模板
+
+> ✅ **风险等级：低** — 接口稳定，已存在完整测试（`tests/test_diet_extractor.py`）。
+
+---
+
+### 3.4 饮食记录存储 — `modules/diet_logger.py`
+
+类：`DietLogger`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `add_record(member_name, member_relation, date, meals, mood, notes)` | `member_name: str`, `member_relation: str`, `date: str (ISO)`, `meals: dict`, `mood: str=""`, `notes: str=""` | `(record: dict, md_path: Path)` | 添加记录 → JSON + MD 双写 |
+| `get_recent_records(days=7)` | `days: int` | `list[dict]` | 获取近 N 天记录 |
+| `get_all_markdown_files()` | — | `list[Path]` | 所有 MD 日志文件 |
+| `parse_diet_record(text) — static` | `text: str` | `dict\|None` | [DIET_RECORD] 标记解析（后续 AI 版本用） |
+
+**`add_record` 返回的 record dict**:
+```json
+{
+  "id": "a1b2c3d4",
+  "member_name": "小红",
+  "member_relation": "孕妇",
+  "date": "2026-06-09",
+  "meals": {"早餐": "燕麦粥+坚果", "午餐": "清蒸鱼+米饭"},
+  "mood": "挺好",
+  "notes": "今天胃口不错",
+  "extensions": {},
+  "created_at": "2026-06-09T12:00:00"
+}
+```
+
+**依赖**:
+- `config.DIET_LOG_FILE`（`data/diet_logs.json`）— JSON 格式
+- `config.LOGS_DIR`（`data/logs/`）— Markdown 日志目录
+- `config.DIET_LOG_SCHEMA_VERSION`（当前 "1.0"）
+
+**Markdown 日志文��格式**（`data/logs/饮食日志_YYYY-MM-DD.md`）:
+```markdown
+# 🥗 孕期饮食日志
+
+## 📋 基本信息
+- **日期**: 2026-06-09
+- **记录人**: 孕妇 - 小红
+- **记录时间**: 2026-06-09T12:00:00
+
+## 🍽️ 今日饮食记录
+
+### 早餐
+- 燕麦粥+坚果
+
+### 午餐
+- 清蒸鱼+米饭
+
+---
+*由 PregoPal 自动生成*
+```
+
+> ✅ **风险等级：低** — schema 已加版本号，`extensions: {}` 字段可向后兼容扩展。
+
+---
+
+### 3.5 家庭信息管理 — `modules/family_manager.py`
+
+三个管理器类，全部使用 `@classmethod`（无需实例化）:
+
+#### 3.5.1 RecipeManager — 家庭菜谱
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `load_all()` | — | `list[dict]` | 读取所有菜谱 |
+| `add_recipe(name, cook, difficulty, ingredients, notes)` | 五个 `str` 参数 | `str` (结果消息) | 添加菜谱 |
+| `get_names()` | — | `list[str]` | 所有菜名 |
+| `format_for_prompt()` | — | `str` | System Prompt 格式 |
+
+菜谱 dict: `{"name", "cook", "difficulty", "ingredients", "notes"}`
+
+#### 3.5.2 PreferenceManager — 饮食偏好
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `load_all()` | — | `list[dict]` | 所有成员偏好 |
+| `add_member(name, role, preferences, avoid, allergies, notes)` | 六个 `str` 参数 | `str` (结果消息) | 添加/更新（覆盖同名） |
+| `format_for_prompt()` | — | `str` | System Prompt 格式 |
+
+偏好 dict: `{"name", "role", "preferences", "avoid", "allergies", "notes"}`
+
+#### 3.5.3 MemoryManager — 家庭记忆
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `load_all()` | — | `dict` (relationships/events/daily) | 所有记忆 |
+| `add_event(description)` | `str` | `str` (结果消息) | 添加重要事件 |
+| `add_daily(content)` | `str` | `str` (结果消息) | 添加日常记录 |
+| `format_for_prompt()` | — | `str` | System Prompt 格式 |
+
+**顶层统一接口**:
+- `load_all_family_info() -> dict` — 一次性加载所有家庭信息
+- `format_all_for_prompt() -> str` — 全量 System Prompt 文本
+
+**数据文件**（`data/family/`）:
+- `recipes.md` — Markdown 格式表
+- `preferences.md` — Markdown 格式表
+- `memory.md` — Markdown 格式表
+
+> ✅ **风险等级：低** — 接口稳定，有完整测试（`tests/test_family_manager.py`）。更新 `add_member` 覆盖逻辑时注意保留已有数据。
+
+---
+
+### 3.6 营养标准 — `modules/nutrition_standards.py`
+
+类：`BMIStandards`, `DietaryGuideStandards`, `DRIsParser`（全部只读数据+静态方法）
+
+| 类 | 关键方法 | 说明 |
+|----|---------|------|
+| `BMIStandards` | `get_bmi_range(pre_preg_bmi) → dict`, `get_recommended_gain(pre_preg_bmi) → dict`, `calculate_bmi(weight_kg, height_m) → float` | 孕前 BMI 标准（中国标准） |
+| `DietaryGuideStandards` | `get_daily_guideline(trimester) → dict`, `get_food_groups_info() → dict` | 膳食指南推荐 |
+| `DRIsParser` | `get_dri_for_trimester(trimester) → dict`, `get_all_dris() → dict` | DRIs 2023 数据 |
+
+**DRIsParser.get_dri_for_trimester 返回示例**:
+```json
+{
+  "蛋白质": {"value": 70, "unit": "g", "note": "孕中期+15g"},
+  "钙": {"value": 1000, "unit": "mg"},
+  "铁": {"value": 27, "unit": "mg"},
+  "叶酸": {"value": 600, "unit": "mcg"},
+  ...
+}
+```
+
+> ✅ **风险等级：低** — 只读数据类，有完整测试（`tests/test_nutrition_standards.py`）。
+
+---
+
+### 3.7 营养分析与可视化 — `modules/nutrition_analyzer.py`
+
+类：`NutritionAnalyzer`
+
+| 方法 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| `analyze_diet(records)` | `records: list[dict]` (diet_logger 格式) | `dict` | 营养覆盖分析 |
+| `generate_report_chart(analysis)` | `analysis: dict`（上一个方法返回） | `matplotlib.figure.Figure` | 4 面板可视化图表 |
+| `generate_report_text(analysis)` | `analysis: dict` | `str` | 文本格式报告 |
+| `export_report_markdown(analysis, filename)` | `analysis: dict`, `filename: str\|None` | `Path` | 导出 Markdown 报告 |
+
+**`analyze_diet` 返回 dict schema**:
+```json
+{
+  "total_days": 7,
+  "total_records": 21,
+  "meal_counts": {"早餐": 5, "午餐": 6, "晚餐": 6, "加餐": 4},
+  "food_items": ["全麦面包", "鸡蛋", "牛奶", "清蒸鱼", ...],
+  "nutrition_coverage": {
+    "叶酸": {
+      "matched_foods": ["菠菜"],
+      "covered": true,
+      "recommended_foods": ["菠菜", "西兰花", "芦笋"],
+      "benefit": "预防胎儿神经管畸形",
+      "daily_recommend": "0.4",
+      "unit": "mg"
+    },
+    ...
+  },
+  "diversity_score": {"score": 75, "details": ["✅ 早餐: 6/7天 (86%)", ...]},
+  "suggestions": ["⚠️ 以下营养素摄入不足: 铁, 钙", ...]
+}
+```
+
+**图表输出**（`generate_report_chart`）:
+1. 左上：营养覆盖雷达图（最多 8 种营养素）
+2. 右上：各餐次频率柱状图
+3. 左下：饮食多样性评分环形图
+4. 右下：营养建议文本框
+
+**依赖**:
+- `config.NUTRITION_DB_FILE`（`data/nutrition_db.json`）— 可自定义
+- `config.DEFAULT_NUTRITION_DB`（10 种营养素的内置推荐）
+- `config.REPORTS_DIR`（`data/reports/`）
+- `utils.setup_chinese_font()` — matplotlib 中文字体
+
+> 🔴 **风险等级：高（待改造）** — 当前使用通用 `DEFAULT_NUTRITION_DB` 做营养覆盖分析，**尚未对接 `modules/nutrition_standards.py` 的 DRIs 数据**。改造时需：
+> 1. 将 `_calculate_nutrition_coverage` 中的 `self.nutrition_db` 替换为 `DRIsParser.get_dri_for_trimester()`
+> 2. 保持 `analyze_diet(records) -> dict` 签名不变
+> 3. 保持 `nutrition_coverage` 的 dict key 不变（nutrient name 为 key）
+
+---
+
+### 3.8 插件基类 — `plugins/base.py`
+
+核心类型（供所有插件和 loop 使用）:
+
+```python
+# 阶段枚举
+class LoopStage(Enum):
+    FAMILY_QUIZ = "family_quiz"
+    SUMMARIZE = "summarize"
+    ANALYZE = "analyze"
+    BRIEF = "brief"
+    THREE_DAY = "three_day"
+    CONSOLIDATE = "consolidate"
+
+# 上下文容器（插件间共享）
+@dataclass
+class LoopContext:
+    briefing: dict = {}           # 累积的简报数据
+    weight_data: dict = {}
+    diet_records: list = []
+    family_recipes: list = []     # family_manager.RecipeManager.load_all() 格式
+    family_memory: dict = {}      # family_manager.MemoryManager.load_all() 格式
+    analysis_results: dict = {}
+    errors: list = []
+
+# 插件结果
+@dataclass
+class PluginResult:
+    success: bool = True
+    data: dict = {}
+    message: str = ""
+
+# 插件基类
+class LoopPlugin(ABC):
+    @abstractmethod
+    def stage(self) -> LoopStage: ...
+    @abstractmethod
+    def name(self) -> str: ...
+    @abstractmethod
+    async def run(self, ctx: LoopContext) -> PluginResult: ...
+```
+
+> ✅ **风险等级：低** — 核心架构稳定。新增插件：实现 `LoopPlugin`，在 `loop.py` 的 `_register_default_plugins` 中注册即可。
+
+---
+
+## 4. 插件管线一览
+
+| 插件名 | 阶段 | 文件 | 职责 |
+|--------|------|------|------|
+| `FamilyRecipeQuizPlugin` | `FAMILY_QUIZ` | `plugins/family_quiz.py` | 检查是否需要询问家庭菜谱 |
+| `WeightQuizPlugin` | `FAMILY_QUIZ` | `plugins/family_quiz.py` | 检查是否需要询问体重 |
+| `DietSummaryPlugin` | `SUMMARIZE` | `plugins/diet_summary.py` | 读取昨日饮食日志 |
+| `WeightCheckPlugin` | `SUMMARIZE` | `plugins/weight_check.py` | 体重变化分析 |
+| `FamilyMemoryPlugin` | `SUMMARIZE` | `plugins/family_memory.py` | 提取家庭记忆 |
+| `DRIAnalysisPlugin` | `ANALYZE` | `plugins/dri_analysis.py` | DRIs 营养对比 |
+| `BriefingGeneratorPlugin` | `BRIEF` | `plugins/briefing_generator.py` | 汇总生成今日简报 |
+| `ThreeDaySummaryPlugin` | `THREE_DAY` | `plugins/three_day_summary.py` | 三天综合总结 |
+| `PresetWriterPlugin` | `CONSOLIDATE` | `plugins/preset_writer.py` | 写入预设/缓存 |
+
+**插件向 `ctx.briefing` 写入的 key**（`BriefingGeneratorPlugin` 最终消费）:
+```
+ctx.briefing["trimester"]              # str
+ctx.briefing["need_ask_weight"]        # bool
+ctx.briefing["weight_quiz_message"]    # str
+ctx.briefing["weight_evaluation"]      # dict
+ctx.briefing["need_ask_recipe"]        # bool
+ctx.briefing["recipe_quiz_message"]    # str
+ctx.briefing["yesterday_diet"]         # dict {"status","summary","meal_count"}
+ctx.briefing["dri_analysis"]           # dict {"focus_nutrients","summary"}
+ctx.briefing["recommended_foods"]      # list[str]
+ctx.briefing["family_memory"]          # dict
+ctx.briefing["thinking_keywords"]      # str
+```
+
+---
+
+## 5. 配置模块 — `config.py`
+
+每个 Cline 如需新增全局常量，**追加到同类型区域末尾**，并在 commit message 中注明。
+
+| 配置区 | 主要内容 | 修改风险 |
+|--------|---------|----------|
+| 目录路径 | `DATA_DIR`, `VOICE_DIR`, `LOGS_DIR`, `REPORTS_DIR`, `FAMILY_FILE`, `DIET_LOG_FILE`, `NUTRITION_DB_FILE` | ⚠️ 中 |
+| 常量枚举 | `FAMILY_ROLES`, `TRIMESTERS` | ✅ 低 |
+| 数据模板 | `DEFAULT_NUTRITION_DB` (10种营养素), `MEAL_TEMPLATES` (4×4), `TRIMESTER_ADJUSTMENTS`, `TRIMESTER_TIPS` | ⚠️ 中 |
+| Schema 版本 | `DIET_LOG_SCHEMA_VERSION = "1.0"` | ⚠️（改版本号前需评估向后兼容） |
+| 声纹阈值 | `VOICEPRINT_SIMILARITY_THRESHOLD = 0.7` | ✅ 低 |
+
+---
+
+## 6. 数据文件格式规范
+
+| 文件 | 格式 | Schema | 读模块 | 写模块 |
+|------|------|--------|--------|--------|
+| `data/diet_logs.json` | JSON | `{"schema_version": "1.0", "records": [...]}` | `diet_logger`, `nutrition_analyzer` | `diet_logger` |
+| `data/nutrition_db.json` | JSON | `{"营养素名": {"category", "daily_recommend_mg/g/mcg", "foods": [...], "benefit"}}` | `nutrition_analyzer` | `nutrition_analyzer` (首次初始化) |
+| `data/family.json` | JSON | `{"members": [...], "voiceprints": {...}}` | `voiceprint` | `voiceprint` |
+| `data/family/recipes.md` | Markdown | `### 菜名\n- **制作人**: ...` | `family_manager.RecipeManager` | `family_manager.RecipeManager` |
+| `data/family/preferences.md` | Markdown | `### 成员：姓名\n- **偏好**: ...` | `family_manager.PreferenceManager` | `family_manager.PreferenceManager` |
+| `data/family/memory.md` | Markdown | `## 重要事件\n- **日期**: ...` | `family_manager.MemoryManager` | `family_manager.MemoryManager` |
+| `data/logs/饮食日志_*.md` | Markdown | 见 3.4 节 | `plugins/diet_summary` | `diet_logger` |
+| `data/reports/营养报告_*.md` | Markdown | 见 3.7 节 | 用户 | `nutrition_analyzer` |
+| `data/presets/.daily_status.json` | JSON | `{"YYYY-MM-DD": {"summary_done": bool, "day_ended": bool}}` | `loop.DailyStatus` | `loop.DailyStatus` |
+
+---
+
+## 7. 并行 Cline 协作规范
+
+### 7.1 分工建议
+
+```
+Cline A: Modules 强化（营养分析对接 DRIs、菜谱推荐 AI 化）
+Cline B: UI 界面优化（Gradio 前端增强、报告模板美化）
+Cline C: 声纹升级（Whisper encoder 替换频谱特征）
+Cline D: 数据处理与插件增强（diet_extractor fallback、新插件）
+```
+
+### 7.2 关键约定
+
+1. **改接口前先 grep**：用 `search_files` 搜索方法名找到所有调用方
+2. **config.py 修改需沟通**：新增常量追加到同类型区域，不删改已有常量名
+3. **数据文件向后兼容**：新增字段优先用 `extensions: {}` 或新增可选 key，不删除已有 key
+4. **测试保持通过**：`python tests/run_tests.py` 零失败
+5. **README 同步更新**：接口签名变更 → 更新本 README 对应章节
+
+### 7.3 Git 工作流（强制执行）
+
+```bash
+# 工作前
+git pull --rebase origin main
+
+# 开发中：每完成一个独立功能点就提交
+git add -A
+git commit -m "feat: 描述做了什么"
+
+# 推送前再次 pull
+git pull --rebase origin main
+
+# 测试通过后推送
+python tests/run_tests.py
+git push origin main
+```
+
+### 7.4 Commit Message 规范
+
+```
+feat: 新功能/新模块/新接口
+fix: 修复 bug
+test: 添加或修改测试
+refactor: 重构（不改功能）
+docs: 文档更新（含本 README）
+chore: 配置/依赖/路径调整
+```
+
+### 7.5 冲突处理策略
+
+| 冲突类型 | 处理方式 |
+|---------|---------|
+| `config.py` 常量冲突 | 取并集，双方新增常量都保留 |
+| 同函数不同实现 | 保留逻辑更完整的一方，另一方改动如果无冲突则合并到合适位置 |
+| 数据文件（JSON/MD）冲突 | 保留两个版本共有的条目 + 各自独有条目（去重） |
+| 测试文件冲突 | **取并集**：保留所有测试用例 |
+| 本 README 冲突 | **取行数更长的一方**，手动整合 |
+| `.gitignore` 冲突 | 取并集 |
+
+---
+
+## 8. 测试
+
+```bash
+# 运行全部测试
+python tests/run_tests.py
+```
+
+当前测试覆盖：
+- `test_diet_extractor.py` — ✅ 通过（正则解析 + fallback 提取）
+- `test_family_manager.py` — ✅ 通过（菜谱/偏好/记忆 CRUD）
+- `test_nutrition_standards.py` — ✅ 通过（BMI/膳食指南/DRIs 数据）
+- `test_loop.py` — 循环执行测试
+- `test_plugins.py` — 插件集成测试
+
+---
+
+## 9. Model: MiniCPM-o 4.5
+
+```
+Model  to be Used: MiniCPM-o 4.5
+```
+
+核心能力层（`core/` 目录）提供模型加载、语音处理、视觉处理、对话管理的底层能力封装。详见各文件 docstring。
+
+---
+
+*最后更新: 2026-06-09 | 由 PregoPal Cline 团队维护*