卡路里手账工厂 - Skill 配置说明

快速开始（30秒入门）

最快触发方式（直接复制粘贴给AI）：

我今天早餐吃了包子和鸡蛋，帮我生成手账

记录一下今天的饮食：午餐宫保鸡丁米饭，加餐苹果和奶茶

帮我生成今天的饮食手账，主题用治愈森林

一句话版：描述你吃了什么/做了什么运动，自动生成7张精美卡片 + 情绪盘点 + 今日小动物 + 数据自检报告。支持字符版/图片版双输出，用户可100%自定义手账风格。

增值效果：平均节省90%的饮食记录时间，从枯燥的数字记录变成治愈的每日仪式，自动发现3-5种你可能没意识到的食物情绪，人人都是手账创作者。

---

概述

卡路里手账工厂 是一个一人公司级的治愈系饮食记录平台。从"手账生成器"升级为"手账工厂"，用户不仅可以生成手账，更可以100%自定义属于自己的手账风格。

核心能力（v3.0 完整升级）

• 🎨 完整主题包系统：6大JSON配置模块（命名/角色/情绪/话术/视觉/贴纸），零代码即可制作专属主题，人人都是手账创作者
• 📝 双输出系统：支持字符版（纯文本/Markdown）+ 图片版（PNG高清卡片）双模式输出，适用于不同场景
• 🔍 智能食物识别：7级搜索降级架构，智能估算兜底
• 🧠 食物情绪占星：基于营养学权威依据，6种情绪分类
• 🐾 小动物盲盒：基于真实营养数据动态匹配，7只纯手绘小动物
• 🧪 7维度数据自检：生成前自动验证，从源头避免错误
• 🌍 100%跨平台兼容：零Emoji字体依赖，Linux完美运行
• 🔌 插件式扩展架构：食物数据/API/主题/贴纸/语录均可零侵入扩展

设计理念：0批评原则 — 所有话术温暖包容，绝对不使用"超标""警告""错误"等制造焦虑的词汇。

---

触发条件（Adaptability）

当用户执行以下操作时自动加载：

明确触发（高置信度）：

• 说"帮我记录今天的饮食"
• 说"生成饮食手账/卡路里手账"
• 描述吃了什么并说"帮我记录一下"
• 说"今天吃了XX和XX，帮我生成卡片"
• 说"解锁今天的小动物"
• 说"帮我生成字符版手账"
• 说"我想自定义一个主题"
• 说"帮我制作专属手账风格"

关键词触发：

• "记录饮食"、"饮食手账"、"吃了什么"、"卡路里"
• "情绪盘点"、"食物情绪"、"小动物"、"贴纸"
• "基础代谢"、"运动记录"、"每日总结"、"营养"
• "自定义主题"、"制作主题"、"主题包"、"换个风格"
• "字符版"、"文字手账"、"纯文本手账"

不触发（避免误激活）：

• 单纯讨论减肥方法（无记录意图）
• 用户已有完整饮食日志仅需排版美化（用文档工具更合适）
• 讨论医学/营养学专业问题（非记录场景）

---

核心脚本

| 脚本 | 功能 | 核心命令 | |---|---|---| | scripts/gen_card.py | 图片版卡片生成主引擎 + 数据自检系统 | python gen_card.py 输出目录名 | | scripts/text_handbook_generator.py | 字符版手账生成器（纯文本/Markdown） | python text_handbook_generator.py --meal ... | | scripts/theme_pack_loader.py | 主题包加载器（6大JSON模块系统） | loader.load_theme("default") | | scripts/food_mood_analyzer.py | 食物情绪占星师 | get_food_mood("香蕉") | | scripts/animal_blind_box.py | 小动物盲盒匹配引擎 | match_diet_animal(protein_pct, carb_pct, ...) | | scripts/emoji_stickers.py | 纯代码手绘贴纸系统 | draw_sticker_star(draw, x, y, size) | | scripts/search_engine_v2.py | 7级智能食物搜索引擎 | engine.search("宫保鸡丁") | | scripts/food_extension_loader.py | 疾控中心数据扩展系统 | loader.load_extensions() |

---

能力边界说明（Trust）

在开始处理之前，明确Skill的处理能力范围，避免用户期望落差：

✅ 擅长处理

• 日常饮食记录：三餐+加餐的标准饮食场景，步骤清晰
• 中文家常菜：覆盖100+种常见中餐，支持模糊描述
• 情绪导向记录：更关注食物带来的感受，而非精确数字
• 治愈系视觉输出：精美卡片、温暖文案、可爱小动物
• 跨平台稳定运行：Linux/Windows/Mac全兼容，无字体问题

⚠️ 勉强处理（需降级期望）

• 极简描述（<10字）：AI会尽量估算，但精度有限，建议补充描述
• 专业级精确计算：可给出参考值，但精确医疗级计算需专业工具
• 超大规模批量生成：单日>10餐时，建议分批生成
• 高度专业的饮食方案：糖尿病/肾病等特殊饮食需遵医嘱，本工具仅作记录

❌ 不适合使用

• 纯聊天/无实质饮食内容：如"我们讨论了减肥方法"，没有具体食物
• 已是结构化营养数据仅需排版：直接用文档工具更高效
• 需要精确医疗诊断的场景：此类需专业医师/营养师介入
• 超过30种食物的巨型单日记录：建议拆分多天记录

---

使用误区（5条反模式，Convention）

遇到这些情况时，换个思路效果更好：

| ❌ 常见误用 | ✅ 正确做法 | |---|---| | 把一周7天的饮食一次性扔进来，期望生成7×7=49张卡片 | 按天分批次生成，每天7张，最后人工整合 | | 用于专业医疗级营养计算，期望精确到克 | 用本工具做日常记录，精确计算用专业营养软件 | | 期望AI自动从聊天记录里"猜"你吃了什么 | 明确说"我早餐吃了XX"，不要让AI猜 | | 只发一句"帮我生成手账"，不补充任何细节 | 参考快速开始的模板，描述具体吃了什么 | | 把生成的卡片直接用于商业医疗用途 | 本工具仅供个人记录参考，不构成医疗建议 |

---

输入质量容错机制（Reliability）

输入质量直接影响输出效果，Skill按以下策略自动降级处理：

| 输入质量 | 判断标准 | 处理策略 | |---|---|---| | 优质 | 有明确食物名称、数量、烹饪方式，≥50字 | 直接运行全流程，生成完整7张卡片 | | 一般 | 有基本食物名称但细节不足，20-50字 | 先输出卡片框架，标注「⚠️ 数据为估算值」，提示可补充描述后更新 | | 简短模糊 | <20字 或 只有"我吃了饭"这类泛泛描述 | 不直接报错，改为追问3个关键问题，再处理 |

理解确认机制：收到复杂饮食描述后，先输出一行确认：

📌 我理解你今天吃了「早餐XX、午餐XX、加餐XX」，运动了「XX分钟」。按[确认]继续生成，或告诉我理解有误的地方。

三轮追问话术（输入不足时）：

• 第1轮：「你说的我收到了，但能告诉我大概吃了多少吗？比如一个/一碗/一份？」
• 第2轮：「好的，我已按常见分量估算。能告诉我烹饪方式吗？比如清蒸/红烧/油炸？」
• 第3轮（仍不清晰时）：「能简单描述一下这道菜大概是什么样的吗？或者有类似的菜名也行」

---

错误诊断速查（Reliability）

当脚本输出错误时，对照下表快速定位并修复：

| 错误信息 | 原因 | 修复建议 | |---|---|---| | ModuleNotFoundError: PIL | 缺少Pillow依赖 | 安装依赖：pip install Pillow | | Font not found | 系统缺少中文字体 | 安装Noto Sans CJK字体，或修改脚本中的字体路径 | | 卡片生成失败 | 输入数据格式错误 | 运行自检：python gen_card.py --check，查看报告 | | 情绪标签不显示 | 食物不在内置库 | 自动降级为通用标签，或扩展自定义食物库 | | Linux下显示方框 | v2.4及以前版本的Emoji问题 | 升级到v3.0，已全部改为纯代码手绘 | | 贴纸遮挡文字 | v2.4及以前版本布局问题 | 升级到v3.0，贴纸已统一移到右上角 |

💡 更多排错详情见 SELF_CHECK_REPORT.txt（每次生成自动生成）

---

完整工作流（Effectiveness）

一键生成（推荐，新手首选）

cd scripts
python gen_card.py 我的手账

自动串联全部步骤：食物识别 → 情绪分析 → 营养计算 → 卡片生成 → 小动物匹配 → 数据自检 → 输出交付。

出错时自动输出「原因+修复建议」，无需手动排查。

分步运行（适合：进阶/调试用）

用户描述餐食和运动
 ↓
search_engine_v2.py → 食物识别 + 营养计算
 ↓
food_mood_analyzer.py → 情绪标签匹配
 ↓
gen_card.py → 7张卡片生成 + 贴纸布局
 ↓
animal_blind_box.py → 今日小动物匹配
 ↓
DataSelfChecker → 7维度数据自检 + 生成报告

---

主题包自定义工作流（v3.0 核心能力）

人人都是手账创作者，零代码即可完成：

步骤1：复制模板主题
 └─ cp -r theme_packs/default theme_packs/my_amazing_theme

步骤2：修改6大JSON模块
 ├─ naming.json    → 卡片标题、营养素名称、图标名称
 ├─ character.json → 陪伴角色设定、性格描述、专属台词
 ├─ emotion.json   → 食物情绪分类名称、颜色、匹配规则
 ├─ quotes.json    → 治愈语录库、场景化暖心文案
 ├─ style.json     → 配色方案、字体、布局参数
 └─ stickers.json  → 贴纸种类、样式、触发条件

步骤3：一键加载使用
 └─ loader.load_theme("my_amazing_theme")

修改难度分级： | 难度 | 可修改内容 | 所需技能 | 示例 | |---|---|---|---| | ⭐ 入门 | 配色方案、语录库 | 会用记事本 | 把绿色改成粉色，加几句自己喜欢的话 | | ⭐⭐ 进阶 | 卡片标题、情绪分类名称 | 会编辑JSON | 把「清晨能量」改成「元气早餐」 | | ⭐⭐⭐ 高手 | 角色设定、贴纸规则 | 理解JSON结构 | 创建一个「猫咪陪伴」主题 |

完整制作指南：见 scripts/theme_packs/HOW_TO_MAKE_THEME.md

---

字符版手账工作流（v3.0 新增）

用户描述餐食和运动
 ↓
text_handbook_generator.py → 纯文本手账生成
 ↓
输出：ASCII艺术 + Markdown格式
 ↓
可直接复制到：微信/钉钉/Notion/飞书文档/任何纯文本环境

适用场景：快速记录、团队分享、笔记软件、无图环境、需要搜索引擎收录的内容

---

AI 工作流程（Effectiveness）

步骤 1：主动开场 + 收集饮食描述

AI应主动说明工作流程（触发后的开场话术）：

我来帮你生成今天的饮食手账。我会帮你：
① 识别所有食物并估算营养 ② 匹配食物情绪标签 ③ 生成7张精美卡片 ④ 匹配今日专属小动物 ⑤ 自动数据自检

请告诉我你今天吃了什么，越详细越好：
- 早餐/午餐/晚餐/加餐分别吃了什么？
- 大概吃了多少（一个/一碗/一份）？
- 做了什么运动，大概多久？

对于简短或模糊的输入，启动三轮追问机制（见「输入质量容错机制」章节），不直接报错。

---

步骤 2：运行食物识别与营养计算

# 自动选择最优数据源
from search_engine_v2 import FoodSearchEngineV2
engine = FoodSearchEngineV2()

# 按优先级搜索：
# 1. 内置常用食物库 → 毫秒级响应
# 2. 用户扩展食物数据 → 疾控中心1300+种
# 3. TianAPI（家常菜/外卖）
# 4. Open Food Facts（450万+全球食品）
# 5. 烹饪方式系数修正
# 6. 外卖加成系数
# 7. 智能估算（永不失败）

---

步骤 3：运行情绪分析与卡片生成

# 为每种食物匹配情绪标签
from food_mood_analyzer import get_food_mood

# 生成7张卡片，自动选择主题
# 贴纸统一右上角，永不遮挡文字

---

步骤 4：小动物匹配 + 数据自检

# 基于真实营养数据匹配今日小动物
from animal_blind_box import match_diet_animal

# 自动运行7维度数据自检，生成SELF_CHECK_REPORT.txt

---

步骤 5：展示结果

向用户汇报：

• 📊 今日总摄入热量，4项营养素达标状态
• 😊 今日情绪盘点（吃了几种开心/治愈/力量食物）
• 🐾 今日解锁的小动物 + 专属slogan
• 🧪 数据自检结果（通过/警告/错误）
• 📦 生成的7张卡片文件列表

---

输出格式一览（Convention）

| 格式 | 用途 | 说明 | |---|---|---| | 7张PNG卡片 | 核心交付物 | 640×580 高清，每张一个主题，治愈系视觉效果 | | 字符版手账 | 纯文本输出 | Markdown/ASCII格式，可直接复制分享 | | SELF_CHECK_REPORT.txt | 质量报告 | 7维度自检结果，问题发现与修复建议 | | JSON数据文件（可选） | 数据归档 | 结构化餐食数据，便于后续分析 |

---

📝 字符版手账可视化示例

╔════════════════════════════════════════╗
║           🌲 治愈森林手账               ║
║        今日森林伙伴：小狐狸 🦊          ║
╚════════════════════════════════════════╝

╭────────────────────────────────────────╮
│  ☀️ 清晨能量                            │
│  包子 + 鸡蛋                           │
│  元气值：约 420 kcal                   │
│  肌肉力：18g  ✨ 快乐源：52g           │
│  能量储备：15g  🌱 清道夫：3g           │
│                                        │
│  😊 开心食物 · 🧸 治愈食物             │
│                                        │
│  💬 新的一天，从好好吃饭开始           │
╰────────────────────────────────────────╯

╭────────────────────────────────────────╮
│  🌞 午后活力                            │
│  宫保鸡丁 + 米饭                       │
│  元气值：约 680 kcal                   │
│  💪 力量食物 · 🧸 治愈食物             │
╰────────────────────────────────────────╯

╭────────────────────────────────────────╮
│  🏃 轻盈律动                            │
│  跑步 30分钟                            │
│  消耗：约 180 kcal                     │
│                                        │
│  ✨ 刚刚好                              │
│  身体正在被温柔唤醒，今天也很棒         │
╰────────────────────────────────────────╯

✅ 数据自检：所有检查通过 ✓

字符版优势：

• 零依赖：任何设备都能显示，无需图片加载
• 可搜索：文本内容可以被搜索引擎和笔记软件检索
• 可编辑：可以直接在聊天中修改、补充内容
• 体积小：整份手账仅约2KB，秒发秒收

---

质量评分体系（Effectiveness）

每次生成后，自检系统自动按以下标准评分：

| 评分 | 等级 | 含义 | |---|---|---| | 85-100 | A | 优秀 — 所有数据完整，可直接使用 | | 70-84 | B | 良好 — 个别数据为估算值，基本可用 | | 55-69 | C | 合格 — 部分数据缺失，建议补充描述后重新生成 | | <55 | D | 需改进 — 输入过于模糊，建议增加细节后重试 |

---

参考资料按需导航（Convention）

| 你的情况 | 推荐阅读 | |---|---| | 第一次用，不知道怎么描述饮食 | 看下面的「常见问题」中的示例 | | 想制作自己的专属手账主题 | scripts/theme_packs/HOW_TO_MAKE_THEME.md → 零代码主题制作指南 | | 想了解情绪分类的依据是什么 | 见README.md「权威数据来源」部分 | | 想扩展自定义食物数据库 | ADVANCED_SETUP.md → 疾控中心数据扩展指南 | | 想接入TianAPI覆盖更多中餐 | TianAPI集成说明.md | | 想切换不同的手账主题风格 | THEME_PACKS_README.md → 2套内置主题 + 可扩展 | | 想生成字符版纯文本手账 | scripts/text_handbook_generator.py → 头部注释说明 | | 遇到卡片生成问题或显示异常 | 查看同目录下 SELF_CHECK_REPORT.txt | | 想了解小动物匹配的触发条件 | 见README.md「功能模块导航」部分 |

已内置参考文档：

• scripts/theme_packs/HOW_TO_MAKE_THEME.md — 零代码主题制作完整指南
• ADVANCED_SETUP.md — 疾控中心数据扩展高级配置指南
• TianAPI集成说明.md — TianAPI可插拔集成步骤
• THEME_PACKS_README.md — 2套主题系统使用说明 + 自定义扩展指南
• VERSION.md — v3.0完整版本更新说明
• 权威数据来源及依据 → 见README.md「权威数据来源」部分

---

常见问题（FAQ ≥ 6题，Convention）

Q1：为什么不用Emoji？Linux下显示方框怎么办？

A：v3.0已彻底移除所有Emoji字符，全部改为纯代码手绘图标。这是SkillHub发布的必备条件——很多Agent运行在Linux环境下，Emoji字体支持不一致会导致显示异常。v3.0实现了100%跨平台兼容。

---

Q2：为什么进度条不用"加油""还差"这类词？

A：这是我们的「0批评原则」核心设计。传统饮食App用"加油""还差""超标"这类词，本质是在评判和制造焦虑，让吃饭变成一种负担。v3.0统一改为治愈系3档文案：「探索中」「刚刚好」「很充足」「很满足」——记录的目的是了解自己，不是审判自己。

---

Q3：数据自检系统是做什么的？为什么每次都要运行？

A：v3.0新增的7维度数据自检系统，是质量保障的核心。它会在生成前自动检查：平台兼容性、卡片尺寸、数据结构完整性、营养字段类型、kcal数值范围、总热量合理性、错误分级。从源头避免90%以上的生成失败问题，让Skill更可靠（Reliability评分项）。

---

Q4：小动物是随机的吗？还是有什么规则？

A：不是随机的，7只小动物完全基于你当天的真实营养数据动态匹配：

• 🐆 小猎豹：蛋白质 > 35% 或 > 100g
• 🐹 小仓鼠：碳水 > 55% 或 主食≥3种
• 🦊 小狐狸：三大营养素比例均衡（±10%）
• 🐿️ 小松鼠：加餐 ≥ 2次 或 吃了零食/坚果
• 🐰 小兔子：总热量 < 目标80% 或 蔬菜多
• 🐻 小熊：脂肪 > 40% 或 热量超目标20%
• 🐱 小猫咪：以上都不满足，兜底匹配

每天吃的不一样，小动物也会不一样~

---

Q5：营养目标是怎么定的？为什么用1.5g/kg蛋白质？

A：完全基于权威指南校准：蛋白质1.5g/kg体重，正好落在《中国居民膳食指南2022》和中国营养学会推荐的「普通成人1.0-1.2g/kg，健身人群1.2-1.6g/kg」合理区间内。既科学，又不会给用户造成不必要的压力。

---

Q6：可以自定义食物数据吗？想加入我常吃的本地美食。

A：完全可以！v2.4就已支持疾控中心数据可插拔扩展系统。你只需：

1. 把你的食物数据按JSON格式整理好
2. 放入 scripts/plugins/foods/ 目录
3. 系统自动加载，无需重启，无需改代码

优先级：扩展数据 > API查询 > 内置库，所以你的食物会优先匹配。官方数据源：中国疾控中心营养与健康所 https://fq.chinafcd.org（免费开放1300+种食物）

---

Q7：运动提醒机制是怎么工作的？会不会说我运动过量？

A：绝对不会说"过量"。v3.0基于WHO《身体活动指南2020》建立了温和的3档提醒机制：

• < 30分钟 → 「探索中」：运动是循序渐进的过程，慢慢来也很好
• 30-90分钟 → 「刚刚好」：身体正在被温柔唤醒，今天也很棒

• 90分钟 → 「很充实」：今天很充实，给身体一些时间休息恢复吧

全程零批评，只有温柔的陪伴和提醒。

---

Q8：为什么总结页的情绪盘点要显示所有分类？只显示前3种不行吗？

A：v3.0做了优化，完整显示所有情绪分类。因为每一种食物带来的感受都值得被看见——哪怕你今天只吃了一口「甜蜜食物」，那也是你生活的一部分，不应该被截断和忽略。动态布局会根据实际分类数量自动调整卡片宽度和字体大小，确保所有标签都完整可见。

---

Q9：什么是主题包系统？真的可以零代码自定义吗？

A：完全可以！v3.0最大的升级就是从"手账生成器"变成"手账工厂"。主题包系统包含6大JSON配置模块：命名系统（卡片标题）、角色设定（陪伴角色和台词）、情绪分类（食物情绪标签）、话术系统（治愈语录）、视觉风格（配色和字体）、贴纸库（贴纸样式）。你只需要用任何文本编辑器修改JSON文件，不需要写一行代码，就能制作出100%属于你的专属手账风格。完整制作指南见 scripts/theme_packs/HOW_TO_MAKE_THEME.md。

---

Q10：字符版手账和图片版有什么区别？分别适合什么场景？

A：双输出系统是v3.0的另一大升级：

• 字符版：纯文本/Markdown输出，体积小、可直接复制粘贴到聊天、笔记、文档中，适合快速分享和纯文本环境
• 图片版：640×580高清PNG卡片，视觉效果精美，适合社交媒体发布、打印、壁纸等场景 你可以根据使用场景自由选择，也可以同时生成两种格式。

---

Q11：能给一个主题包自定义的完整示例吗？比如我想做一个「哈利波特魔法学院」主题

A：完全可以！这是一个简化的真实示例：

步骤1：复制默认主题

cp -r scripts/theme_packs/default scripts/theme_packs/hogwarts

步骤2：修改 naming.json（命名系统）

{
  "breakfast_card": "🌅 霍格沃茨早餐",
  "lunch_card": "☀️ 礼堂午餐",
  "dinner_card": "🌙 晚间盛宴",
  "protein": "⚡ 魔力值",
  "carbs": "✨ 能量晶",
  "fat": "🔮 魔法储备"
}

步骤3：修改 character.json（角色设定）

{
  "name": "海德薇",
  "personality": "忠诚的信使，温暖陪伴",
  "catchphrases": [
    "霍格沃茨的早餐从不迟到",
    "猫头鹰会把你的饮食记录带给邓布利多",
    "魔法让每一餐都充满奇迹"
  ]
}

步骤4：修改 style.json（配色）

{
  "primary_color": "#7F0909",
  "secondary_color": "#FFD700",
  "background_color": "#2A2A2A"
}

步骤5：加载使用

loader.load_theme("hogwarts")

就是这么简单！零代码，只需编辑JSON文件。

---

Q12：我改坏了JSON怎么办？主题包会崩溃吗？

A：不会！主题包加载器有完整的容错机制：

1. 自动降级：如果某个JSON文件格式错误，系统会自动使用默认主题的对应模块
2. 错误提示：控制台会清晰告诉你哪个文件哪一行出错了
3. 部分加载：一个模块出错不影响其他模块正常工作
4. 一键恢复：随时可以删除你的主题目录，重新复制default模板即可

推荐做法：修改前先备份原文件，用JSON校验工具检查格式（很多在线工具，免费）。

---

Q13：怎么快速切换不同主题？有命令吗？

A：有多种方式切换主题：

方式1：生成时指定参数

python gen_card.py 我的手账 --theme space_explorer

方式2：修改配置文件 编辑 scripts/config.json 中的 default_theme 字段，永久切换默认主题。

方式3：AI对话时直接说

帮我生成今天的手账，用星际探索主题

内置主题速查：

• default → 治愈森林（绿色系，温暖陪伴）
• space_explorer → 星际探索（深蓝系，科技感）

---

Q14：我做了一个很棒的主题，可以分享给其他人吗？

A：当然可以！这正是手账工厂的设计理念——人人都是创作者。

分享方式：

1. 把你的主题目录（如 theme_packs/my_theme/）打包成zip
2. 分享给其他用户
3. 对方解压到自己的 theme_packs/ 目录即可使用

主题市场构想：未来我们计划建立一个主题分享社区，让大家可以互相分享、下载、评价各种创意主题。你的主题可能会被成千上万的人使用！🌟

---

v3.0 温暖治愈你的每一餐 🌸

卡路里手账工厂 — 让记录成为一种享受，让好好吃饭成为一种生活方式。