taiwan-lunar-cal

Files (1)

• SKILL.md

SKILL.md (first lines)

# taiwan-lunar-cal

> 實測日：2026-09-25（最近一次端對端實測；數值基準日各自標於內文）

純本地計算：國曆轉農曆（1900-2100，含閏月）、二十四節氣日期與交節時刻（太陽視黃經天文計算）、生肖。零網路。

## 農曆換算

用公開的 1900-2100 農曆資料表（每年一個 17-bit 整數：12 個月大小月 + 閏月位置與大小）。完整實作：

```python
import datetime

LUNAR_INFO = [
0x04bd8,0x04ae0,0x0a570,0x054d5,0x0d260,0x0d950,0x16554,0x056a0,0x09ad0,0x055d2,
0x04ae0,0x0a5b6,0x0a4d0,0x0d250,0x1d255,0x0b540,0x0d6a0,0x0ada2,0x095b0,0x14977,
0x04970,0x0a4b0,0x0b4b5,0x06a50,0x06d40,0x1ab54,0x02b60,0x09570,0x052f2,0x04970,
0x06566,0x0d4a0,0x0ea50,0x06e95,0x05ad0,0x02b60,0x186e3,0x092e0,0x1c8d7,0x0c950,
0x0d4a0,0x1d8a6,0x0b550,0x056a0,0x1a5b4,0x025d0,0x092d0,0x0d2b2,0x0a950,0x0b557,
0x06ca0,0x0b550,0x15355,0x04da0,0x0a5b0,0x14573,0x052b0,0x0a9a8,0x0e950,0x06aa0,
0x0aea6,0x0ab50,0x04b60,0x0aae4,0x0a570,0x05260,0x0f263,0x0d950,0x05b57,0x056a0,
0x096d0,0x04dd5,0x04ad0,0x0a4d0,0x0d4d4,0x0d250,0x0d558,0x0b540,0x0b6a0,0x195a6,
0x095b0,0x049b0,0x0a974,0x0a4b0,0x0b27a,0x06a50,0x06d40,0x0af46,0x0ab60,0x09570,
0x04af5,0x04970,0x064b0,0x074a3,0x0ea50,0x06b58,0x05ac0,0x0ab60,0x096d5,0x092e0,
0x0c960,0x0d954,0x0d4a0,0x0da50,0x07552,0x056a0,0x0abb7,0x025d0,0x092d0,0x0cab5,
0x0a950,0x0b4a0,0x0baa4,0x0ad50,0x055d9,0x04ba0,0x0a5b0,0x15176,0x052b0,0x0a930,
0x07954,0x06aa0,0x0ad50,0x05b52,0x04b60,0x0a6e6,0x0a4e0,0x0d260,0x0ea65,0x0d530,
0x05aa0,0x076a3,0x096d0,0x04afb,0x04ad0,0x0a4d0,0x1d0b6,0x0d250,0x0d520,0x0dd45,
0x0b5a0,0x056d0,0x055b2,0x049b0,0x0a577,0x0a4b0,0x0aa50,0x1b255,0x06d20,0x0ada0,
0x14b63,0x09370,0x049f8,0x04970,0x064b0,0x168a6,0x0ea50,0x06b20,0x1a6c4,0x0aae0,
0x0a2e0,0x0d2e3,0x0c960,0x0d557,0x0d4a0,0x0da50,0x05d55,0x056a0,0x0a6d0,0x055d4,
0x052d0,0x0a9b8,0x0a950,0x0b4a0,0x0b6a6,0x0ad50,0x055a0,0x0aba4,0x0a5b0,0x052b0,
0x0b273,0x06930,0x07337,0x06aa0,0x0ad50,0x14b55,0x04b60,0x0a570,0x054e4,0x0d160,
0x0e968,0x0d520,0x0daa0,0x16aa6,0x056d0,0x04ae0,0x0a9d4,0x0a2d0,0x0d150,0x0f252,
0x0d520]

def leap_month(y): return LUNAR_INFO[y-1900] & 0xf
def leap_days(y): return (30 if LUNAR_INFO[y-1900] & 0x10000 else 29) if leap_month(y) else 0
def month_days(y, m): return 30 if (LUNAR_INFO[y-1900] & (0x10000 >> m)) else 29
def year_days(y):
    return 348 + sum(1 for m in range(1, 13) if LUNAR_INFO[y-1900] & (0x10000 >> m)) + leap_days(y)

def to_lunar(d):
    """國曆 date -> (農曆年, 月, 日, 是否閏月);範圍 1900-01-31 ~ 2100-12-31"""
    offset = (d - datetime.date(1900, 1, 31)).days   # 1900-01-31 = 農曆1900年正月初一
    if offset < 0 or d.year > 2100: return None
    y = 1900
    while offset >= year_days(y):
        offset -= year_days(y); y += 1
    leap = leap_month(y)
    for m in range(1, 13):
        md = month_days(y, m)
        if offset < md: return (y, m, offset + 1, False)
        offset -= md
        if leap == m:
            ld = leap_days(y)
            if offset < ld: return (y, m, offset + 1, True)
            offset -= ld
    return None

ZODIAC = '鼠牛虎兔龍蛇馬羊猴雞狗豬'
def zodiac(lunar_year): return ZODIAC[(lunar_year - 1900) % 12]
```

2026-09-19 實測驗證（9 個錨點全過）：2026-02-17 = 丙午年正月初一（115 春節）、2026-09-25 = 八月十五（115 中秋）、2025-10-06 = 乙巳年八月十五（114 中秋，該年有閏六月）、2025-07-25 = 閏六月初一、2026-02-16 = 114 年十二月廿九（除夕，該月小月）。

## 節氣日期與交節時刻

節氣的定義：太陽視黃經每 15° 一個節氣（春分 = 0°、清明 = 15°……）。用低精度天文式（Meeus）算太陽視黃經，二分逼近交節時刻到分，回台灣時間（UTC+8）。**不要用**網路上流傳的「通用公式 `int(Y*0.2422+C)-int((Y-1)//4)`」——2026-09-19 實測它對中央氣象署公告的誤差：2024 年 24 節氣錯 21 個（閏年系統性偏差），2023/2025/2026/2027 各錯 1-3 個，不是「罕見例外」。

```python
import math, datetime

def _jd(dt):  # UTC datetime -> Julian Day
    return dt.timestamp() / 86400.0 + 2440587.5

def _apparent_solar_longitude(j):
    """太陽視黃經(度)。Meeus 低精度式 + 章動/光行差修正,誤差約 0.01°。"""
    T = (j - 2451545.0) / 36525.0
    L0 = (280.46646 + 36000.76983 * T + 0.0003032 * T * T) % 360
    M = math.radians((357.52911 + 35999.05029 * T - 0.0001537 * T * T) % 360)
    C = ((1.914602 - 0.004817 * T - 0.000014 * T * T) * math.sin(M)
         + (0.019993 - 0.000101 * T) * math.sin(2 * M) + 0.000289 * math.sin(3 * M))
    omega = math.radians(125.04 - 1934.136 * T)
    return (L0 + C - 0.00569 - 0.00478 * math.sin(omega)) % 360

TERMS = ['春分', '清明', '穀雨', '立夏', '小滿', '芒種', '夏至', '小暑', '大暑',
         '立秋', '處暑', '白露', '秋分', '寒露', '霜降', '立冬', '小雪', '大雪',
         '冬至', '小寒', '大寒', '立春', '雨水', '驚蟄']
TW = datetime.timezone(datetime.timedelta(hours=8))

def solar_term_moment(year, term):
    """節氣交節時刻(台灣時間 datetime,解析度到分)。year 是節氣所在的國曆年。"""
    idx = TERMS.index(term)
    target = idx * 15.0
    base = year if idx < 19 else year - 1  # 冬至後的節氣(小寒~驚蟄)落在次年 1-3 月
    approx = (datetime.datetime(base, 3, 20, tzinfo=datetime.timezone.utc)
              + datetime.timedelta(days=idx * 365.2422 / 24))
    lo, hi = (approx - datetime.timedelta(days=5),
              approx + datetime.timedelta(days=5))
    def diff(t):
        return (_apparent_solar_longitude(_jd(t)) - target + 540) % 360 - 180
    prev_t, prev_d = lo, diff(lo)
    steps = int((hi - lo).total_seconds() // 21600)  # 每 6 小時掃描
    for i in range(1, steps + 1):
        t = lo + (hi - lo) * i / steps
        d = diff(t)
        if prev_d <= 0 <= d:
            a, b = prev_t, t
            for _ in range(40):  # 二分逼近到 1 分鐘內
                m = a + (b - a) / 2
                if diff(m) < 0: a = m
                else: b = m
            return (a + (b - a) / 2).astimezone(TW)
        prev_t, prev_d = t, d
    raise RuntimeError('找不到交節時刻')

def solar_term_date(year, term):
    """節氣在台灣時間的日期:solar_term_date(2026, '清明') -> date(2026, 4, 5)"""

From tahodev/baodao-skill, MIT.

More from tahodev/baodao-skill