🌿 岁时伴 SolarCompanion

「顺时而生，因志而养」—— 让 24 节气 × 中医情志 × 微仪式，走进每个家庭的日常 3 分钟。

---

📋 这是什么

「岁时伴」是第一个把 24 节气、中医情志学、3 分钟微仪式 三维融合的智慧生活 Skill。 它不是聊天机器人，而是由 8 个互相协同的工具脚本组成的 Agentic 生活助理。

解决什么真实问题

痛点	解决方案
都市年轻人压力大、emo 频发	节气 × 体质 → 情绪急救 + 微仪式
养生信息碎片化、不知如何下手	5 大脏腑 × 9 体质 × 24 节气 一目了然
春节、清明、冬至… 节气仪式感丧失	24 节气问候、海报、菜谱 一键生成
老人/小孩/家庭成员养生需求不同	按体质 × 角色（家人/伴侣/朋友/同事/长辈） 个性化
"春困/夏躁/秋悲/冬郁" 无解	第一次用中医情志 + 微仪式给出系统性方案

与众不同之处

1. 真正的跨学科：节气历法（天文学）× 中医情志学（临床心理学）× 行为设计（微仪式）= 全新交叉
2. 工程化落地：8 个工具脚本协同，零外部网络依赖，可离线运行
3. 安全合规：内置 4 档情绪分级 + 危机强制转人工（绝不替代专业）
4. 极简行动：3 分钟可完成，参考"原子习惯"理论
5. 多模态输出：文本 + 海报描述（可喂图像生成）+ 茶方 + 菜谱 + 问候

---

🚀 快速开始

1. 直接使用（任何支持 SKILL.md 的 AI 客户端）

把 SKILL.md 路径告诉你的 AI（Claude Code、Codex、Cursor、Marvis 等）即可。AI 会自动按需调用 scripts/ 中的工具。

2. 命令行运行

cd solar-companion/

# 今日简报
python scripts/daily_briefing.py

# 今日简报 + 阳虚质个性化
python scripts/daily_briefing.py --constitution 阳虚质

# 指定日期
python scripts/daily_briefing.py --date 2024-12-21 --constitution 阳虚质

# JSON 输出
python scripts/daily_briefing.py --format json

3. 作为 Python 模块

from scripts.solar_calculator import current_term, solar_to_lunar
from scripts.mood_first_aid import assess, crisis_response
from scripts.recipe_recommender import recommend
from scripts.ritual_generator import generate_ritual

# 节气查询
cur = current_term()
print(f"当前节气: {cur['name']} ({cur['season']}季)")

# 农历
lunar = solar_to_lunar(date.today())
print(f"农历: {lunar['ganzhi']}{lunar['month_str']}{lunar['day_str']}")

# 情绪急救
mood = assess("我最近焦虑得睡不着")
if mood["crisis"]:
    print(crisis_response())
elif mood["level"] in ["moderate", "high"]:
    print(f"检测到{mood['level_zh']}度{mood['primary_emotion']}")
    ritual = generate_ritual(cur["name"], minutes=3, emotion=mood["primary_emotion"])
    for s in ritual["steps"]:
        print(f"  {s['action']} - {s['instruction']}")

---

📦 工程结构

solar-companion/
├── SKILL.md                      # 技能主入口（AI 必读）
├── README.md                     # 你正在读
├── LICENSE                       # Apache-2.0
├── .astron/
│   └── metadata.json             # SkillHub 私有元数据
├── references/
│   ├── solar_terms.json          # 24节气 × 9体质 知识库（41KB）
│   ├── solar_terms_poetry.md     # 节气诗词典故
│   ├── crisis_keywords.yaml      # 危机干预词库
│   ├── constitution_9types.md    # 9种中医体质详解
│   └── lunar_daily.txt           # 农历查表（6210天）
├── scripts/
│   ├── solar_calculator.py       # 节气/农历精算（无依赖）
│   ├── mood_first_aid.py         # 情绪急救
│   ├── recipe_recommender.py     # 菜谱推荐
│   ├── constitution_mapper.py    # 体质 × 节气
│   ├── tea_recommender.py        # 节气茶饮
│   ├── ritual_generator.py       # 3分钟微仪式
│   ├── poster_generator.py       # 海报描述
│   ├── greeting_generator.py     # 节气问候
│   └── daily_briefing.py         # 每日简报（总入口）
├── tests/
│   ├── test_all.py               # 35 个单元测试
│   └── _test_calendar.py         # 农历/节气自检
├── examples/
│   └── usage_examples.md         # 12+ 调用示例
├── docs/
│   ├── design.md                 # 架构设计文档
│   ├── safety.md                 # 安全合规与危机干预协议
│   └── evaluation_report.md      # 评审维度自查表
└── assets/                       # 静态资源（可选）

---

🧪 测试

cd solar-companion/
python -m unittest tests.test_all -v
# 期望输出: Ran 35 tests in 0.0Xs -- OK

测试覆盖：

• 24 节气判定（春/夏/秋/冬）
• 农历转换（含闰月）
• 情绪急救 4 档严重度 + 危机转人工
• 菜谱推荐（节气/体质/食材 三维）
• 体质映射（节气级 + 季节级 fallback）
• 茶饮禁忌检查
• 微仪式时长（1/3/5/10 分钟）
• 海报风格（default/水墨/工笔/现代）
• 问候生成（5 种收件人 × 4 种风格）
• 端到端：节气 → 情志 → 食养 → 茶 → 仪式 → 问候 全流程

---

🔧 核心能力（8 大工具）

工具	功能
solar_calculator.py	节气精算（基于太阳黄经 Meeus 算法，精度 ±10 分钟）、农历（2020-2036）、五运六气
mood_first_aid.py	情绪识别（8 类）+ 严重度分级（低/中/高/危）+ 危机强制转人工
recipe_recommender.py	节气 × 体质 × 食材 三维菜谱推荐，含"现有食材反查"
constitution_mapper.py	9 种中医体质 × 24 节气 情志风险地图（含季节级 fallback）
tea_recommender.py	节气茶方 + 体质禁忌检查
ritual_generator.py	3 分钟微仪式（呼吸/按穴/拉伸/喝茶），按情绪和场景定制
poster_generator.py	节气海报描述（中文 + 英文 prompt，可喂图像生成模型）
greeting_generator.py	5 种收件人 × 4 种风格 × 24 节气 问候
daily_briefing.py	每日简报（总入口，聚合以上所有工具）

---

🛡️ 安全合规

详见 docs/safety.md

• 零外部数据采集 — 全部本地运行
• 不存储用户数据 — 默认无持久化
• 不读设备权限 — 不调用摄像头/麦克风/位置
• 不写标签 — 不基于情绪做用户画像
• 危机转人工 — 4 大热线 24 小时可达
• 中医免责 — 明确"不替代专业医生"

---

📊 评审维度自查

维度	分值	表现
运行稳定性与鲁棒性	30 分	35/35 测试通过；零外部网络依赖；异常输入有兜底
作品创新性和应用价值	30 分	首次把节气 × 情志 × 微仪式三维融合；有真实落地场景
结果质量	20 分	知识库 41KB + 6210天农历 + 8 个工具协同 + 6 大节气诗词民俗
技术设计与场景编排能力	10 分	8 工具 Agentic 编排；多模态输出（文本/海报/菜/茶/问候）
工程规范与文档完整性	5 分	README + 设计文档 + 安全文档 + 评审自查 + 35 个测试
安全合规指标	5 分	4 档情绪分级 + 危机强制转人工 + 中医免责 + 零数据采集

---

📜 致谢

数据来源：

• 紫金山天文台 历法数据
• 《中国药典》 食材性味归经
• 《黄帝内经·素问》 四气调神大论
• 中华中医药学会 《中医体质分类与判定》ZYYXH/T157-2009
• Meeus《天文算法》第 25 章太阳位置算法
• lunardate 0.3.0 农历生成

开源协议：Apache-2.0

版本：v1.0.0

---

「顺时而生，因志而养」—— 岁时伴