Icyn Date

icyndate

面向 AI Agent 和开发者的日期语义层：农历、节气、节假日、“这一天意味着什么”——离线、可验证、MIT。 给 AI Agent 和开发者的日期语义层：农历、节气、节假日、"这一天意味着什么"——离线、可验证、MIT。

状态：第一周。农历、二十四节气、节假日层（12 个地区）均已落地；农历与节气 1900–2100 全量验证， 中国大陆节假日 2024–2026 逐天对拍。 状态：第一周。农历、二十四节气、节假日层（12 个地区）均已落地；农历与节气 1900–2100 全量验证， 中国大陆节假日 2024–2026 逐天对拍。

安装 / 安装

npm i @icyn/date                       # library: lunar + solar terms + CN holidays (~90 KB)
import "@icyn/date/regions/all";       # opt in to the other 11 regions (+ subdivisions), or "@icyn/date/regions/JP"

npx -y @icyn/date-mcp                  # MCP server for Claude Desktop / Cursor / any MCP client

目前可用 / 现在能用的

一次调用：

import { dateContext } from "@icyn/date";

dateContext("2026-02-17", { region: "CN" });
// {
//   date: "2026-02-17", region: "CN",
//   civil:    { weekday: 2, isoWeek: 8, isoWeekYear: 2026, dayOfYear: 48, leapYear: false },
//   workday:  { available: true, kind: "public_holiday", isWorkday: false, confidence: "certain", source: "official",
//               holiday: { id: "spring-festival", festival: "lunar-new-year", name: { "zh-Hans": "春节", en: "Chinese New Year" }, dayIndex: 3, span: 9 },
//               meta: { region: "CN", data_version: "2026.09.18", verified_until: 2026, … } },
//   lunar:    { year: 2026, month: 1, day: 1, yearGanZhi: "丙午", zodiac: "马", monthName: "正月", dayName: "初一", … },
//   solarTerm:{ onThisDay: null, current: { name: { zh: "立春", en: "Beginning of Spring" }, at: "2026-02-03T20:01:51.000Z" }, next: { zh: "雨水", … } }
// }

日期可以使用 "2026-02-17"、[2026, 2, 17]、{ year, month, day } 或 Date（UTC 字段）。每个节假日 答案都带有 source（official / baseline / predicted）、confidence（certain / likely / uncertain）和数据 版本元数据；对于完全没有数据的年份，返回 { available: false, reason }，绝不猜测。

功能：

import { solarToLunar, lunarToSolar } from "@icyn/date";

solarToLunar("2026-02-17");
// { year: 2026, month: 1, day: 1, leap: false, yearGanZhi: "丙午", dayGanZhi: "…",
//   zodiac: "马", monthName: "正月", dayName: "初一", isLeapYear: false, monthLength: 30 }

lunarToSolar({ year: 2033, month: 11, day: 1, leap: true }); // [2033, 12, 22]

import { solarTerms, solarTermAt, solarTermOnDay } from "@icyn/date";
solarTermOnDay("2026-02-04");          // { name: { zh: "立春", en: "Beginning of Spring" }, at: 2026-02-03T20:01:51Z, … }
solarTermAt(new Date());               // { current, next } with exact instants
solarTerms(2027);                      // all 24 of the year

import { dayInfo, nextWorkday, workdaysBetween, holidays } from "@icyn/date";
dayInfo("2026-02-14", "CN");           // { kind: "adjusted_workday", isWorkday: true, source: "official", confidence: "certain", … }
dayInfo("2027-02-13", "CN");           // { kind: "weekend", source: "predicted", confidence: "uncertain", note: "Within the usual 调休 window…" }
regionsObserving("lunar-new-year", 2026); // [{ region: "HK", days: [...] }, { region: "KR", … }, …]
dayInfo("2026-01-06", "DE-BY");        // Heilige Drei Könige — subdivision holiday, resolvedRegion "DE-BY"
nextLongWeekend("CN", "2026-09-18", 7); // { start: "2026-10-01", end: "2026-10-07", days: 7 }
nextLunarDate(8, 15, "2026-09-18");    // next 中秋: { date: "2026-09-25", lunarYear: 2026, adjusted: false }
describe("2026-02-17", { region: "CN" });
// "2026-02-17 星期二，农历丙午马年正月初一，CN 放假：春节（第 3/9 天）。"
nextWorkday("CN", "2026-09-30");       // "2026-10-08"
workdaysBetween("CN", "2026-02-13", "2026-02-24");

• 覆盖 1900-01-31 至 2100-12-31 的每一天的公历 ⇄ 农历换算（MAX_DATE；最后一个日期落在农历 2100 年 腊月内，因此该月的 monthLength 为 null——表格在月中结束，实际月长未知）
• 年 / 日干支、生肖、中文月份和日期名称、闰月处理（包括 2033 年闰冬月的情况）
• 24 节气的精确时刻（精确到秒）、当前 / 下一个节气查询，以及在任意 UTC 时区偏移下查询“这一天是否有节气”
• 查询 12 个地区的工作日 / 节假日，每个答案都标记为 official / baseline / predicted——绝不悄悄猜测
• 零依赖，无运行时天文计算；约 480 KB 的表格数据，其中默认入口点只包含农历 / 节气表和中国大陆数据——其他 11 个地区及其 70 多个下属地区仅在导入时加载

错误模型 / 失败行为

• 返回信息对象的函数（dayInfo、dateContext、holidays）在数据缺失时绝不抛出异常：它们会返回 { available: false, reason } 或空列表。
• 返回标量的函数（isWorkday、addWorkdays、nextWorkday、workdayCount）在地区年份不在覆盖范围内时会抛出 RangeError。
• 搜索函数（nextLongWeekend、nextLunarDate）在范围内找不到结果时返回 null，并在数据耗尽时抛出异常。
• 错误输入（未知地区、格式错误的日期、2 月 30 日）始终会抛出 TypeError / RangeError。 地区代码不区分大小写（"us-ca" = "US-CA"）；完全没有数据的代码仍会抛出异常。
• 预测只向未来进行。 对于尚未录入的年份，只有在该年份晚于最后录入年份时才会进行外推（coverage(region).predictedFrom）。 过去未覆盖的年份会返回 { available: false }，而不是猜测——将现行《放假办法》向过去外推会凭空编造历史（清明 / 端午 / 中秋直到 2008 年才成为法定节假日，春节也直到 2025 年才从除夕放到初三）。

验证方式 / 验证方式

tools/gen_fixtures.py 和 tools/gen_solar_terms.py 使用两种独立的参考实现 （sxtwl、lunar_python）生成 fixtures/lunar-1900-2100.json（73,384 行）。测试套件会对每一行进行双向转换。 两个参考实现有任何不一致之处，都会写入 fixtures/lunar-disagreements.json，并由人工裁定 （参见 NOTES.md）。只有 100% 的行全部通过，才能发布。

npm install
npm test                 # Node only

# the full release gate: build + tsc + tests + the CN cross-check
python3 -m pip install -r tools/requirements.txt   # one pure-Python package
npm run check

npm run check 的最后一步会逐天使用 chinesecalendar 验证 CN.json。如果缺少该软件包，检查会明确失败，而不会跳过——未经验证的表格绝不能看起来像是通过了检查。

路线图

• 农历核心功能 + 1900–2100 年测试数据
• 24 节气的精确时刻（两个参考来源的误差在 55 秒以内；发布前抽查紫金山天文台公布的数据）
• 中国 2024–2026 年官方节假日（含调休），逐日与 chinesecalendar 交叉核对；后续年份 → 根据农历/节气规则将法定节日标记为 predicted（仅预测未来；绝不猜测过去年份）
• 香港/澳门/台湾/日本/韩国/越南/新加坡/美国/英国/德国/法国 2024–2028 年的节假日作为 baseline（基于 python-holidays 规则），春节日期已与我们的农历表交叉核对
• 地区时区（通过 Intl 感知夏令时），使日本/韩国/欧盟按各自时区确定节气日期；地区层级（US-CA、DE-BY、GB-SCT，70 多个子区域以差异形式记录）；节假日 kind（公共/联邦/银行/补休日）；previousWorkday / addWorkdays / workdayCount / holidaysBetween / isHolidayEve / nextLongWeekend；月柱和时柱干支、nextLunarDate（农历生日）；describe() 为 MCP 提供一句话的中/英文输出
• dateContext() 一次调用 API、规范日期输入、置信度级别、BCP-47 名称（保证提供 en + zh-Hans）、各地区通用的规范节日 ID、数据版本元数据，以及优雅处理 available: false
• 按年份对照官方公报，将 baseline 地区升级为 official（优先处理台湾补班、香港公报和韩国替代节日）
• 来自 Wikipedia 的“历史上的今天”（CC BY-SA，每条内容注明出处）
• @icyn/date npm 包（esbuild ESM、各地区独立入口点、d.ts）· @icyn/date-mcp MCP 服务（11 个工具、stdio、已完成端到端冒烟测试）
• icyndate pip 包（使用相同的测试向量）
• 托管 API

仓库布局

docs/        product & technical plan（产品与技术方案）, worklog
fixtures/    reference test vectors (generated, committed)
tools/       fixture generators (Python, not shipped)
packages/core/  @icyn/date — the library
packages/mcp/   @icyn/date-mcp — MCP server

许可证

代码及衍生的农历/节气表采用 MIT 许可证。11 个非中国地区的 baseline 节假日表衍生自 python-holidays（MIT）；其许可证副本收录于 THIRD-PARTY-LICENSES，每个生成文件的 baseline_note 中都记录了确切版本。其他第三方数据（Wikipedia、政府节假日公告）保留其各自的许可证，并逐条注明出处。