摘要用一个 JSON 请求获取可核对的历法事实、查询时辰和结构化三语文化内容并正确处理日期边界、任务与 SSE 响应。关键词传统历法 API、农历 API、二十四节气 API、宜忌接口、日历组件、传统文化数据服务问题背景日历产品容易把多个来源的数据直接拼在页面上导致公历日期、农历日期、节气和时辰并不属于同一查询时刻。用户切换时间后如果只刷新时辰而没有刷新相关干支字段页面就会出现内部矛盾。可靠的服务应以明确的date、time和timezone作为输入先展示历法基础数据再展示文化参考内容。基础事实与文化说明必须分区并持续显示使用边界。Agent 工作流接口编排步骤接口请求方式用途查询历法与参考传统历法宜忌参考POST返回农历、干支、生肖、星座、节气、宜忌和文化参考查询异步任务异步任务状态查询GET月历预生成或后台批量任务接口地址POST https://api.gugudata.com/ai/traditional-calendar-guidance当前timezone固定支持Asia/Shanghai。date范围为 1901-01-01 至 2100-12-31time可选未传时按 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(frozenTrue) 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 不会提前切换到次日。页面应同时显示输入日期、规范化时间和查询时辰不要只显示“子时”而隐藏实际日期。节气结果同时提供兼容的日期字段和精确日期时间。节气日前后的内容应以返回时间为准不能只比较日期字符串。基础数据与文化参考分层基础数据包括农历年月日和中文日期年、月、日、时干支生肖和星座当前节气、下一节气及日期宜、忌和其他传统历法字段。文化参考用于组织日程说明。页面应明确它属于传统文化研究与娱乐参考不应触发自动审批、排期、交易、医疗或其他现实决策。月历预生成生成整月内容时不建议前端同时发起几十个同步请求。可以由后台为目标月份创建每日任务。固定时区和默认时刻。使用异步任务模式或有界并发并通过 Header 查询任务状态。保存每一天的独立状态。只重试失败日期。月历读取已完成结果并显示缺失状态。某一天失败不能让整月任务只返回一个模糊的失败结果。标准架构拆解模块责任查询入口接收日期、时间、语言和页面来源参数校验校验日期、24 小时制时间和固定时区历法服务调用接口并分离基础数据与文化参考月历任务有界并发预生成每日内容组件适配为日历、节气页和历史查询提供结构化结果内容边界展示文化娱乐参考说明数据流与接口边界推荐流程用户选择日期和可选时间。服务端补齐默认时间并固定Asia/Shanghai。校验请求格式并调用传统历法接口。基础数据和文化参考分别展示。日历组件读取结构化字段。历史查询保留原始查询条件不重新标记为当前结果。接口负责历法基础字段与文化参考应用负责展示层级、任务状态和现实使用边界。错误处理日期必须使用YYYY-MM-DD时间使用HH:mm或HH:mm:ss。传入其他时区时当前应直接提示不支持而不是悄悄改成北京时间。用户切换时间后与时柱和时辰相关的旧结果必须失效。批量月历任务发生部分失败时页面显示缺失日期并允许后台重试不能复制相邻日期内容填补。同步响应在Data返回完整结果任务模式先返回operationId成功后由任务查询的Data.result返回完整结果SSE 依次发送metadata、content和包含完整结果的done.result最后发送结束事件。任务失败、流式断开或业务码 901 都不能当作成功内容保存。可靠性与观测指标用途calendar_query_success_rate历法查询成功率invalid_datetime_count发现日期时间输入问题month_prewarm_completion_rate整月预生成完成率partial_month_failure_count发现部分日期失败query_result_mismatch_count检测页面条件与结果串位落地清单明确记录date、time和timezone。未传时间时显式使用并展示 12:00。当前仅允许Asia/Shanghai。基础数据与文化参考分层展示。切换日期或时间后完整刷新依赖字段。月历预生成使用有界并发和逐日状态。历史结果保留请求条件与生成时间。页面不根据文化参考自动执行现实事项。可扩展方向传统历法服务可以与天气、空气质量、日出日落和二十四节气内容组合成城市日历组件。组合数据时应把城市、日期、时区和更新时间作为共同上下文并明确各数据源的更新时间。相关接口传统历法宜忌参考全国天气预报信息全国城市实时空气质量指数日出与日落时间