二十四节气·时令生活助手V1

概述

二十四节气 · 时令生活助手

不是告诉你「今天是什么节气」，而是告诉你「在今天、在这里、作为你，怎样生活更合时」。

核心公式：时间 × 地点 × 节气 × 当地气候 × 人物画像 × 当季食材 → 当下生活建议

三字诀：知时 · 知地 · 知人

触发条件

• 用户问「今天适合吃什么 / 怎么运动 / 生活上注意什么」
• 用户问「现在是什么节气，我该怎么养生 / 生活」
• 用户提供位置 + 画像，要「时令生活建议」

调用方式（调用方视角）

本 Skill 通过自有公网 Pay Skill 后端提供服务，调用方不需要关心内部脚本、知识库或 LLM 实现：

• 输入：query（用户问题）+ city / province（城市与省份）+ 可选 lat / lon / adcode / weather / date / profile
• 输出：SeasonalAdvice（含饮食/运动/作息/生活建议、健康科普、时令文化，以及 JSON/MD/HTML 等结果）
• 公网调用入口：POST https://seasonal-pay-backend-303827-11-1429942071.sh.run.tcloudbase.com/invoke

示例请求：

{
  "query": "最近容易疲劳，想要一份时令生活建议",
  "city": "贵港",
  "province": "广西",
  "date": "2026-08-19",
  "weather": {"temp": 30, "humidity": 70, "condition": "晴", "wind": "微风"}
}

调用方只负责向该公网入口发起请求并处理支付握手；节气查表、数据组装、LLM 推理和多格式渲染均由后端完成。

核心原则（铁律）

1. LLM 只做推理与表达，不做事实数据库：节气查表、天气拉服务、食材查库、画像用户给，LLM 只在最后综合判断、排序、解释、语言生成。
2. 传统文化 ≠ 现代医学结论：传统节气养生理念与「当前天气下的生活常识」分层表述，绝不把传统理论包装成医学结论。
3. 节气精确到天即可，不需要分钟级交节时刻。

输出内容（本 Skill 生成什么）

调用成功后，本 Skill 输出一份完整的 SeasonalAdvice，包含五部分：

1. 今日饮食：早餐 / 午餐 / 晚餐推荐 + 当季水果 / 蔬菜 + 当地风味
2. 今日运动：运动指数（星级）+ 推荐项目 + 需要避开的时段
3. 今日作息与生活：今日宜（推荐做）+ 今日注意（提醒避坑）
4. 健康养生：当地当季健康风险（成因通俗）+ 药食同源建议（性味/功效/用法）+ 养生茶饮推荐
5. 节气之意与为何如此：传统节气文化说明 + 结论的可解释性（节气 × 天气 × 画像三因子）

输出格式支持 JSON / Markdown / HTML（中国工笔画风格展示页）/ PDF 四种，默认输出 Markdown 文本建议即可，HTML/PDF 为可选增强。

内部实现（开发者参考 · 调用方无需执行）

以下内容由自有公网后端自动完成，调用方不需要手动执行。

1. 获取位置：腾讯地图 MCP geocoder（城市名→经纬度+adcode），降级 ipLocation 自动定位
2. 获取天气：腾讯地图 MCP weather（adcode→实时天气）
3. 数据组装：scripts/main.py 节气查表 + 当季食材查库 + 健康风险 + 风俗 + 画像 → SeasonalContext（纯本地，无网络依赖）
4. LLM 推理：由调用方 Agent 自己完成（Agent 即 LLM），把 SeasonalContext 综合成 SeasonalAdvice。本步骤无任何外部 LLM API 依赖
5. 多格式渲染：scripts/export.py 输出 JSON/MD/HTML/PDF（PDF 依赖 playwright，缺失时自动降级为 HTML，不阻塞主流程）

数据来源均为 references/ 下的本地知识库（节气表 201 年、食材库 338 城、药食同源 48 种、茶饮 17 款、风俗 39 城等），全部本地查表，无运行时外部数据依赖。

输入 Schema（SeasonalContext）

见 scripts/main.py 输出，核心字段：time / location / solar_term / weather / food / health / customs / persona。

输出 Schema（SeasonalAdvice）

overview / seasonal_state / food / exercise / sleep / daily_life / health / customs（时令风俗）/ precautions / traditional_culture / explanation。详见 DESIGN-SPEC.md。

目录结构

seasonal-life-guide/
├── SKILL.md
├── DESIGN-SPEC.md              # 设计规格（权威）
├── scripts/
│   ├── main.py                 # 数据组装主脚本
│   ├── gen_solar_terms.py      # 节气表生成器（开发期工具）
│   ├── render_html.py          # HTML 渲染（配色三维灵动化）
│   ├── render_md.py            # Markdown 渲染
│   ├── render_json.py          # JSON 输出
│   ├── render_pdf.py           # PDF 输出（HTML→PDF）
│   ├── export.py               # 统一导出入口（json/md/html/pdf）
│   └── test_suite.py           # 自动化测试套件
├── references/
│   ├── solar_terms.json        # 1900-2100 节气表
│   ├── festival_dates.json     # 1900-2100 农历节日公历日期表
│   ├── ingredients_db.json     # 三层时令食材库（338 城）
│   ├── health_risks.json       # 节气健康风险库（含天气触发）
│   ├── herbs_db.json           # 药食同源知识库
│   ├── tea_db.json             # 养生茶饮知识库
│   ├── customs_db.json         # 时令文化风俗库（节气/节日/区域/地方）
│   ├── color_themes.json       # 配色（季节色+节气成分+气候带+意象类型）
│   ├── climate_zones.json      # 城市→气候带+意象映射
│   └── profile_schema.md       # 画像字段说明
└── assets/
    ├── default_profile.json    # 默认画像
    └── template.html           # HTML 展示模板（中国工笔画风格）

免责声明（必读）

⚠️ 本 Skill 的所有健康养生内容（含药食同源、养生茶饮、体质与饮食建议）仅供参考，不构成医疗诊断、治疗或用药建议，不能替代执业医师的诊疗。 如有健康问题、慢性病或正在服药，请先咨询专业医生，切勿据此自行停药、用药或改变治疗方案。

• 本 Skill 输出的是「时令生活常识」与「传统食疗文化」，属保健养生科普范畴，非医学结论。
• 药食同源食材虽普遍安全，但个体体质、过敏史、孕期哺乳期、慢病用药者需谨慎，食用前咨询专业人士。
• 输出页面（HTML/PDF）的健康板块与页脚均固定标注「仅供参考 · 不替代医疗建议」。

付费前置检查（Pay Skill · 必读）

本 Skill 为付费 Pay Skill，单次调用 0.3 元/次（amount_fen=30），由自有公网后端执行微信支付 Agent Pay X402 协议。

调用方先向公网入口发起首次 POST /invoke 请求，不带支付凭据。后端完成 Native 下单与 X402 预下单后返回 HTTP 402，并在响应 Header 与 Body 中提供：

• WeixinPay-Required：本次支付的 payment_code
• X-Out-Trade-No：本次订单号

支付由 Agent 的微信支付能力完成。支付成功后，调用方必须携带原始请求体、WeixinPay-Required 和 X-Out-Trade-No 重试同一公网入口。后端主动查单确认 trade_state=SUCCESS 后才返回付费内容。

付费调用工作流程（X402 协议 · 自有公网后端）

第一步：请求资源（首次调用）

向以下入口发起首次调用（不带任何支付凭证）：

POST https://seasonal-pay-backend-303827-11-1429942071.sh.run.tcloudbase.com/invoke

请求体使用上一节的输入格式。

后端完成 Native 下单 + AI 预下单并返回 HTTP 402。调用方必须同时保存响应中的 WeixinPay-Required 和 X-Out-Trade-No。

{
  "WeixinPay-Required": "payment_code_xxx",
  "out_trade_no": "WX402_xxxxxxxx",
  "WeixinPay": {
    "WeixinPay-Required": "payment_code_xxx",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

调用方必须同时保存以下两个字段，缺一不可：

• WeixinPay-Required：支付码（paymentCode）
• out_trade_no：商户订单号（即 X-Out-Trade-No）

第二步：处理支付触发响应

从平台返回 JSON 中提取：

• WeixinPay-Required → 作为 paymentCode 备用
• out_trade_no → 作为订单号（X-Out-Trade-No）备用

任一字段缺失立即终止流程，不向用户返回任何「付费内容预览」。

第三步：发起支付

将第一步保存的 WeixinPay-Required 值作为 paymentCode 参数，调用 weixinpay_pay 工具向用户发起微信支付 AI 专属卡授权：

weixinpay_pay(paymentCode=<WeixinPay-Required>)

用户确认支付后返回 trade_state=SUCCESS。

第四步：支付成功后重新调用（⚠️ 必须执行 · 重试机制）

用户支付完成后，调用方必须重新发起调用才能拿到付费 SeasonalAdvice（重试机制）。重试时订单号传递：

• 参数 out_trade_no：第二步保存的订单号（X-Out-Trade-No）
• 业务参数（query / location / persona）：与第一次请求完全一致

⚠️ 警告：不传 out_trade_no（订单号）重试，平台视为未支付调用，拒绝返回付费内容。 这是最容易踩坑的点，调用方必须严格按"支付成功后重新请求"流程执行。

平台收到重试后查单验证（trade_state=SUCCESS），通过后返回完整付费 SeasonalAdvice。

异常处理

调用方必须实现以下异常处理：

• 支付字段缺失：首次响应未拿到 WeixinPay-Required 或 out_trade_no，立即终止流程，不展示付费内容预览
• 重试请求不一致：支付后重试必须保持原始请求体不变，并同时携带 WeixinPay-Required 与 X-Out-Trade-No
• 支付未完成：后端返回 NOT_PAID 时，不得交付内容；按支付能力提示等待或重试
• payment_code 过期：重新发起首次调用获取新的支付码
• 网络异常 / 5xx：指数退避重试，最多 3 次
• 订单幂等：同一 X-Out-Trade-No 只履约一次，重复请求返回缓存结果