摘要：用一个 JSON 请求获取可核对的历法事实、查询时辰和结构化三语文化内容，并正确处理日期边界、任务与 SSE 响应。

关键词：传统历法 API、农历 API、二十四节气 API、宜忌接口、日历组件、传统文化数据服务

问题背景

日历产品容易把多个来源的数据直接拼在页面上，导致公历日期、农历日期、节气和时辰并不属于同一查询时刻。用户切换时间后，如果只刷新时辰而没有刷新相关干支字段，页面就会出现内部矛盾。

可靠的服务应以明确的 date、time 和 timezone 作为输入，先展示历法基础数据，再展示文化参考内容。基础事实与文化说明必须分区，并持续显示使用边界。

Agent 工作流

接口编排

接口地址：

POST https://api.gugudata.com/ai/traditional-calendar-guidance

当前 timezone 固定支持 Asia/Shanghai。date 范围为 1901-01-01 至 2100-12-31；time 可选，未传时按 12:00 计算。

调用示例

curl -X POST \
  "https://api.gugudata.com/ai/traditional-calendar-guidance" \
  -H "X-GUGUDATA-APPKEY: YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-07-18",
    "time": "12:00",
    "timezone": "Asia/Shanghai",
    "language": "zh-CN"
  }'

应用侧应显式保存最终查询条件：

from dataclasses import dataclass


@dataclass(frozen=True)
class CalendarQuery:
    date: str
    time: str = "12:00"
    timezone: str = "Asia/Shanghai"
    language: str = "zh-CN"


def build_calendar_payload(query: CalendarQuery) -> dict:
    """Build an explicit traditional calendar request."""
    return {
        "date": query.date,
        "time": query.time,
        "timezone": query.timezone,
        "language": query.language,
    }

即使用户没有填写时间，也建议应用侧把默认值 12:00 写入请求，避免之后无法解释时柱为何如此。

午夜与子时边界

接口按北京时间民用日处理日期：00:00 才切换公历、农历和日柱。23:00 至 00:59 都属于子时，但 23:00 至 23:59 不会提前切换到次日。页面应同时显示输入日期、规范化时间和 查询时辰，不要只显示“子时”而隐藏实际日期。

节气结果同时提供兼容的日期字段和精确日期时间。节气日前后的内容应以返回时间为准，不能只比较日期字符串。

基础数据与文化参考分层

基础数据包括：

• 农历年月日和中文日期；
• 年、月、日、时干支；
• 生肖和星座；
• 当前节气、下一节气及日期；
• 宜、忌和其他传统历法字段。

文化参考用于组织日程说明。页面应明确它属于传统文化研究与娱乐参考，不应触发自动审批、排期、交易、医疗或其他现实决策。

月历预生成

生成整月内容时，不建议前端同时发起几十个同步请求。可以由后台：

1. 为目标月份创建每日任务。
2. 固定时区和默认时刻。
3. 使用异步任务模式或有界并发，并通过 Header 查询任务状态。
4. 保存每一天的独立状态。
5. 只重试失败日期。
6. 月历读取已完成结果并显示缺失状态。

某一天失败不能让整月任务只返回一个模糊的失败结果。

标准架构拆解

数据流与接口边界

推荐流程：

1. 用户选择日期和可选时间。
2. 服务端补齐默认时间并固定 Asia/Shanghai。
3. 校验请求格式并调用传统历法接口。
4. 基础数据和文化参考分别展示。
5. 日历组件读取结构化字段。
6. 历史查询保留原始查询条件，不重新标记为当前结果。

接口负责历法基础字段与文化参考，应用负责展示层级、任务状态和现实使用边界。

错误处理

日期必须使用 YYYY-MM-DD，时间使用 HH:mm 或 HH:mm:ss。传入其他时区时，当前应直接提示不支持，而不是悄悄改成北京时间。

用户切换时间后，与时柱和时辰相关的旧结果必须失效。批量月历任务发生部分失败时，页面显示缺失日期，并允许后台重试，不能复制相邻日期内容填补。

同步响应在 Data 返回完整结果；任务模式先返回 operationId，成功后由任务查询的 Data.result 返回完整结果；SSE 依次发送 metadata、content 和包含完整结果的 done.result，最后发送结束事件。任务失败、流式断开或业务码 901 都不能当作成功内容保存。

可靠性与观测

落地清单

• 明确记录 date、time 和 timezone。
• 未传时间时显式使用并展示 12:00。
• 当前仅允许 Asia/Shanghai。
• 基础数据与文化参考分层展示。
• 切换日期或时间后完整刷新依赖字段。
• 月历预生成使用有界并发和逐日状态。
• 历史结果保留请求条件与生成时间。
• 页面不根据文化参考自动执行现实事项。

可扩展方向

传统历法服务可以与天气、空气质量、日出日落和二十四节气内容组合成城市日历组件。组合数据时，应把城市、日期、时区和更新时间作为共同上下文，并明确各数据源的更新时间。

相关接口

• 传统历法宜忌参考
• 全国天气预报信息
• 全国城市实时空气质量指数
• 日出与日落时间