@lark-people/cli 0.0.17 → 0.0.18

package/skills/people-attendance/scripts/resolve_date.py

@@ -0,0 +1,894 @@
+#!/usr/bin/env python3
+"""
+resolve_date.py - 确定性日期解析脚本
+
+将中文/英文相对日期表达（如"下周六""下个月3号""last Wednesday"）解析为绝对日期。
+仅使用 Python 3 标准库，无第三方依赖。
+
+用法:
+    python3 resolve_date.py --expr "下周六" --anchor "2026-05-29"
+    python3 resolve_date.py --expr "下个月3号" --anchor "2026-05-29"
+    python3 resolve_date.py --expr "6月13日" --anchor "2026-05-29"
+    python3 resolve_date.py --expr "本周三" --anchor "2026-06-15"  # → 2026-06-17（允许落在未来）
+    python3 resolve_date.py --expr "本周" --anchor "2026-06-15" --clamp-to-anchor
+
+输出: JSON 格式
+    成功: {"success": true, "resolved_date": "2026-06-06", "is_future": false, ...}
+    失败: {"success": false, "reason": "...", ...}
+
+关于"未来日期"：
+    脚本本身不拒绝未来日期，只通过 `is_future` 字段标识。
+    调用方应根据语义自行判断：
+      - "明天/明年/下月X号/下周一" 等显式未来意图 → 应拒绝调用接口
+      - "本周X/本月N号"等 ISO 周/月内某天恰好落在未来 → 仍可调用接口（接口会返回"无记录"）
+"""
+
+import argparse
+import json
+import re
+import sys
+from datetime import date, timedelta
+from typing import Dict, List, Optional, Tuple
+
+# 中文数字映射
+CN_NUM = {
+    "零": 0, "一": 1, "二": 2, "两": 2, "三": 3, "四": 4,
+    "五": 5, "六": 6, "七": 7, "八": 8, "九": 9, "十": 10,
+    "十一": 11, "十二": 12, "十三": 13, "十四": 14, "十五": 15,
+    "十六": 16, "十七": 17, "十八": 18, "十九": 19, "二十": 20,
+    "二十一": 21, "二十二": 22, "二十三": 23, "二十四": 24, "二十五": 25,
+    "二十六": 26, "二十七": 27, "二十八": 28, "二十九": 29, "三十": 30,
+    "三十一": 31,
+}
+
+WEEKDAY_MAP = {
+    "一": 0, "二": 1, "三": 2, "四": 3, "五": 4, "六": 5, "日": 6, "天": 6, "末": 5,
+    "1": 0, "2": 1, "3": 2, "4": 3, "5": 4, "6": 5, "7": 6,
+}
+
+WEEKDAY_NAMES = ["星期一", "星期二", "星期三", "星期四", "星期五", "星期六", "星期日"]
+
+# 英文 weekday: monday=0, sunday=6
+EN_WEEKDAY = {
+    "mon": 0, "monday": 0,
+    "tue": 1, "tues": 1, "tuesday": 1,
+    "wed": 2, "weds": 2, "wednesday": 2,
+    "thu": 3, "thur": 3, "thurs": 3, "thursday": 3,
+    "fri": 4, "friday": 4,
+    "sat": 5, "saturday": 5,
+    "sun": 6, "sunday": 6,
+}
+
+
+EN_MONTH = {
+    "jan": 1,
+    "january": 1,
+    "feb": 2,
+    "february": 2,
+    "mar": 3,
+    "march": 3,
+    "apr": 4,
+    "april": 4,
+    "may": 5,
+    "jun": 6,
+    "june": 6,
+    "jul": 7,
+    "july": 7,
+    "aug": 8,
+    "august": 8,
+    "sep": 9,
+    "sept": 9,
+    "september": 9,
+    "oct": 10,
+    "october": 10,
+    "nov": 11,
+    "november": 11,
+    "dec": 12,
+    "december": 12,
+}
+
+# 英文数字词（用于 "two days ago" / "three weeks ago" 等表达）
+EN_NUM = {
+    "one": 1, "an": 1, "a": 1,
+    "two": 2, "three": 3, "four": 4, "five": 5,
+    "six": 6, "seven": 7, "eight": 8, "nine": 9, "ten": 10,
+    "eleven": 11, "twelve": 12, "thirteen": 13, "fourteen": 14,
+    "fifteen": 15, "sixteen": 16, "seventeen": 17, "eighteen": 18,
+    "nineteen": 19, "twenty": 20, "thirty": 30,
+}
+
+
+def en_to_num(s: str) -> Optional[int]:
+    """阿拉伯数字或英文数字词转 int"""
+    s = s.strip().lower()
+    if s.isdigit():
+        return int(s)
+    return EN_NUM.get(s)
+
+
+def cn_to_num(s: str) -> Optional[int]:
+    """将中文数字或阿拉伯数字字符串转为 int"""
+    s = s.strip()
+    if s.isdigit():
+        return int(s)
+    if s in CN_NUM:
+        return CN_NUM[s]
+    # 处理 "十X" 模式
+    if s.startswith("十") and len(s) == 2:
+        tail = CN_NUM.get(s[1])
+        if tail is not None:
+            return 10 + tail
+    if len(s) == 3 and s[1] == "十":
+        head = CN_NUM.get(s[0])
+        tail = CN_NUM.get(s[2])
+        if head is not None and tail is not None:
+            return head * 10 + tail
+    return None
+
+
+def _normalize(expr: str) -> str:
+    """统一同义词，便于后续正则匹配。仅做无歧义替换。"""
+    s = expr.strip()
+    # 只删除中文/全角空格；保留 ASCII 空格用于英文短语匹配
+    s = s.replace("　", "")
+    s = s.replace(",", "").replace("，", "")
+    # 同义词归一: 礼拜/拜/星期 → 周
+    s = re.sub(r"星期", "周", s)
+    s = re.sub(r"礼拜", "周", s)
+    s = re.sub(r"(?<![上下本这个那])拜(?=[一二三四五六日天\d])", "周", s)
+    # 这周/这个周 → 本周（统一前缀）
+    s = re.sub(r"^这(?=周)", "本", s)
+    s = re.sub(r"^这个(?=周)", "本个", s)
+    # 今儿/明儿/昨儿 → 今天/明天/昨天
+    s = s.replace("今儿", "今天").replace("明儿", "明天").replace("昨儿", "昨天")
+    return s
+
+
+def get_monday(d: date) -> date:
+    """获取 d 所在周的周一（ISO 8601）"""
+    return d - timedelta(days=d.weekday())
+
+
+def resolve(expr: str, anchor: date, *, clamp_to_anchor: bool = False) -> Dict:
+    """
+    尝试解析日期表达式，返回结果字典。
+    成功: {"success": True, "resolved_date": "YYYY-MM-DD", "resolved_weekday": "星期X", "type": "single"/"range"}
+    范围: {"success": True, "resolved_date_from": ..., "resolved_date_to": ..., "type": "range"}
+    失败: {"success": False, "reason": "..."}
+    """
+    expr = _normalize(expr)
+
+    # === 0. 范围表达（优先解析，如“上周一到上周五”“2026-06-01～2026-06-07”） ===
+    m = re.match(r"^(.+?)(?:到|至|~|～|—|–)(.+)$", expr)
+    if m:
+        left = m.group(1).strip()
+        right = m.group(2).strip()
+
+        # 右侧若是裸“周X”，尝试继承左侧的周前缀（上周/下周/本周/这周/上上周/下下周）
+        if re.match(r"^周[一二三四五六日天\d]$", right):
+            m2 = re.search(r"(上上|下下|上|下|本|这)(?:个)?周", left)
+            if m2:
+                right = f"{m2.group(0)}{right[-1]}"
+
+        left_r = resolve(left, anchor, clamp_to_anchor=clamp_to_anchor)
+        right_r = resolve(right, anchor, clamp_to_anchor=clamp_to_anchor)
+        if left_r.get("success") and right_r.get("success"):
+            if left_r.get("type") == "single" and right_r.get("type") == "single":
+                d1 = date.fromisoformat(left_r["resolved_date"])
+                d2 = date.fromisoformat(right_r["resolved_date"])
+                d_from = min(d1, d2)
+                d_to = max(d1, d2)
+                result = _range(d_from, d_to)
+                return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+            if left_r.get("type") == "range" and right_r.get("type") == "range":
+                d1 = date.fromisoformat(left_r["resolved_date_from"])
+                d2 = date.fromisoformat(left_r["resolved_date_to"])
+                d3 = date.fromisoformat(right_r["resolved_date_from"])
+                d4 = date.fromisoformat(right_r["resolved_date_to"])
+                result = _range(min(d1, d2, d3, d4), max(d1, d2, d3, d4))
+                return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    extracted = _extract_weekday_exprs(expr)
+    if len(extracted) > 1:
+        resolved = []
+        for item in extracted:
+            result = resolve(item, anchor, clamp_to_anchor=clamp_to_anchor)
+            if result.get("success") and result.get("type") == "single":
+                resolved.append({
+                    "expression": item,
+                    "resolved_date": result["resolved_date"],
+                    "resolved_weekday": result["resolved_weekday"],
+                })
+        if len(resolved) > 1:
+            return {
+                "success": True,
+                "type": "multiple",
+                "resolved_dates": resolved,
+            }
+
+    # === 1. 绝对日期格式 ===
+
+    # YYYY-MM-DD / YYYY.MM.DD / YYYY/MM/DD
+    m = re.match(r"^(\d{4})[-./](\d{1,2})[-./](\d{1,2})$", expr)
+    if m:
+        return _single(date(int(m.group(1)), int(m.group(2)), int(m.group(3))))
+
+    # YYYY年M月D日
+    m = re.match(r"^(\d{4})年(\d{1,2})月(\d{1,2})[日号]?$", expr)
+    if m:
+        return _single(date(int(m.group(1)), int(m.group(2)), int(m.group(3))))
+
+    # M.D / M/D (无年份，用 anchor 年)
+    m = re.match(r"^(\d{1,2})[./](\d{1,2})$", expr)
+    if m:
+        month = int(m.group(1))
+        day = int(m.group(2))
+        year = _infer_year_for_month(anchor, month)
+        return _single(date(year, month, day))
+
+    # M-D (无年份，用 anchor 年)
+    m = re.match(r"^(\d{1,2})-(\d{1,2})$", expr)
+    if m:
+        month = int(m.group(1))
+        day = int(m.group(2))
+        year = _infer_year_for_month(anchor, month)
+        return _single(date(year, month, day))
+
+    # M月D日 / M月D号
+    m = re.match(r"^(\d{1,2})月(\d{1,2})[日号]?$", expr)
+    if m:
+        month = int(m.group(1))
+        day = int(m.group(2))
+        year = _infer_year_for_month(anchor, month)
+        return _single(date(year, month, day))
+
+    # 五月 / 5月（仅月份）
+    m = re.match(r"^(\d{1,2}|[一二三四五六七八九十十一十二]+)月份?$", expr)
+    if m:
+        month = cn_to_num(m.group(1))
+        if month is not None and 1 <= month <= 12:
+            year = _infer_year_for_month(anchor, month)
+            first = date(year, month, 1)
+            last = _last_day_of_month(year, month)
+            result = _range(first, last)
+            return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # 今年X月 / 去年X月 / 明年X月
+    m = re.match(r"^(今年|本年|去年|上一年|明年|下一年)(\d{1,2}|[一二三四五六七八九十十一十二]+)月份?$", expr)
+    if m:
+        year_word = m.group(1)
+        month = cn_to_num(m.group(2))
+        if month is not None and 1 <= month <= 12:
+            if year_word in ("今年", "本年"):
+                year = anchor.year
+            elif year_word in ("去年", "上一年"):
+                year = anchor.year - 1
+            else:
+                year = anchor.year + 1
+            first = date(year, month, 1)
+            last = _last_day_of_month(year, month)
+            result = _range(first, last)
+            return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # YYYY年X月（含 month 后缀）
+    m = re.match(r"^(\d{4})年(\d{1,2})月份?$", expr)
+    if m:
+        year = int(m.group(1))
+        month = int(m.group(2))
+        first = date(year, month, 1)
+        last = _last_day_of_month(year, month)
+        result = _range(first, last)
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # May / June（仅月份）
+    key = expr.strip().lower()
+    if key in EN_MONTH:
+        month = EN_MONTH[key]
+        year = _infer_year_for_month(anchor, month)
+        first = date(year, month, 1)
+        last = _last_day_of_month(year, month)
+        result = _range(first, last)
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # YYYYMMDD
+    m = re.match(r"^(\d{8})$", expr)
+    if m:
+        return _single(date(int(expr[:4]), int(expr[4:6]), int(expr[6:8])))
+
+    # === 2. 相对天数 ===
+
+    if expr in ("今天", "今日", "本日", "当天", "当日"):
+        return _single(anchor)
+    if expr in ("明天", "明日"):
+        return _single(anchor + timedelta(days=1))
+    if expr in ("昨天", "昨日"):
+        return _single(anchor - timedelta(days=1))
+    if expr in ("后天",):
+        return _single(anchor + timedelta(days=2))
+    if expr in ("前天",):
+        return _single(anchor - timedelta(days=2))
+    if expr in ("大后天",):
+        return _single(anchor + timedelta(days=3))
+    if expr in ("大前天",):
+        return _single(anchor - timedelta(days=3))
+
+    # 英文相对天
+    low = expr.lower()
+    if low in ("today",):
+        return _single(anchor)
+    if low in ("tomorrow", "tmr", "tmrw"):
+        return _single(anchor + timedelta(days=1))
+    if low in ("yesterday",):
+        return _single(anchor - timedelta(days=1))
+    if low in ("the day before yesterday",):
+        return _single(anchor - timedelta(days=2))
+    if low in ("the day after tomorrow",):
+        return _single(anchor + timedelta(days=2))
+
+    # N天后/前（中文）
+    m = re.match(r"^(\d+|[一二三四五六七八九十]+)天[后以之]?[后]?$", expr)
+    if m and "前" not in expr:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(anchor + timedelta(days=n))
+    m = re.match(r"^(\d+|[一二三四五六七八九十]+)天[前以之]?前$", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(anchor - timedelta(days=n))
+    # 简化：N天后/N天前 直接匹配
+    m = re.match(r"^(\d+|[一二三四五六七八九十]+)天后$", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(anchor + timedelta(days=n))
+    m = re.match(r"^(\d+|[一二三四五六七八九十]+)天前$", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(anchor - timedelta(days=n))
+
+    # 一周后 / 两周后
+    m = re.match(r"^(\d+|[一二两三四五六七八九十]+)周[后以]", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(anchor + timedelta(weeks=n))
+    m = re.match(r"^(\d+|[一二两三四五六七八九十]+)周前", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(anchor - timedelta(weeks=n))
+
+    # N 个月后/前（取月份偏移，日相同；若超月末则裁剪到月末）
+    m = re.match(r"^(\d+|[一二两三四五六七八九十]+)个?月[后以]", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(_clamp_day(_month_offset(anchor, n), anchor.day))
+    m = re.match(r"^(\d+|[一二两三四五六七八九十]+)个?月前", expr)
+    if m:
+        n = cn_to_num(m.group(1))
+        if n is not None:
+            return _single(_clamp_day(_month_offset(anchor, -n), anchor.day))
+
+    # === 3. 本/上/下周X ===
+
+    monday = get_monday(anchor)
+
+    # 本周末 / 这周末
+    if expr in ("本周末", "这周末"):
+        sat = monday + timedelta(days=5)
+        sun = monday + timedelta(days=6)
+        return _range(sat, sun)
+    if expr in ("下周末",):
+        sat = monday + timedelta(days=12)
+        sun = monday + timedelta(days=13)
+        return _range(sat, sun)
+    if expr in ("上周末",):
+        sat = monday + timedelta(days=-2)
+        sun = monday + timedelta(days=-1)
+        return _range(sat, sun)
+
+    # 本周/这周 (范围)
+    if expr in ("本周", "这周", "这一周"):
+        result = _range(monday, monday + timedelta(days=6))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if expr in ("上周", "上一周"):
+        return _range(monday - timedelta(days=7), monday - timedelta(days=1))
+    if expr in ("下周", "下一周"):
+        return _range(monday + timedelta(days=7), monday + timedelta(days=13))
+    if expr in ("上上周",):
+        return _range(monday - timedelta(days=14), monday - timedelta(days=8))
+    if expr in ("下下周",):
+        return _range(monday + timedelta(days=14), monday + timedelta(days=20))
+
+    # 周X：未显式指定上/下/下下周时，默认按本周X处理
+    m = re.match(r"^周([一二三四五六日天\d])$", expr)
+    if m:
+        wd = WEEKDAY_MAP.get(m.group(1))
+        if wd is not None:
+            return _single(monday + timedelta(days=wd))
+
+    # 本周X / 这周X / 这个周X
+    m = re.match(r"^[本这](个)?周([一二三四五六日天\d])$", expr)
+    if m:
+        wd = WEEKDAY_MAP.get(m.group(2))
+        if wd is not None:
+            return _single(monday + timedelta(days=wd))
+
+    # 上周X / 上个周X
+    m = re.match(r"^上(个)?周([一二三四五六日天\d])$", expr)
+    if m:
+        wd = WEEKDAY_MAP.get(m.group(2))
+        if wd is not None:
+            return _single(monday - timedelta(days=7) + timedelta(days=wd))
+
+    # 下周X / 下个周X
+    m = re.match(r"^下(个)?周([一二三四五六日天\d])$", expr)
+    if m:
+        wd = WEEKDAY_MAP.get(m.group(2))
+        if wd is not None:
+            return _single(monday + timedelta(days=7) + timedelta(days=wd))
+
+    # 上上周X
+    m = re.match(r"^上上(个)?周([一二三四五六日天\d])$", expr)
+    if m:
+        wd = WEEKDAY_MAP.get(m.group(2))
+        if wd is not None:
+            return _single(monday - timedelta(days=14) + timedelta(days=wd))
+
+    # 下下周X
+    m = re.match(r"^下下(个)?周([一二三四五六日天\d])$", expr)
+    if m:
+        wd = WEEKDAY_MAP.get(m.group(2))
+        if wd is not None:
+            return _single(monday + timedelta(days=14) + timedelta(days=wd))
+
+    # 上N周X / 下N周X (N=2/3/...，支持中文与阿拉伯)
+    m = re.match(r"^(上|下)(\d+|[一二两三四五六七八九十]+)周([一二三四五六日天\d])$", expr)
+    if m:
+        sign = -1 if m.group(1) == "上" else 1
+        n = cn_to_num(m.group(2))
+        wd = WEEKDAY_MAP.get(m.group(3))
+        if n is not None and wd is not None:
+            return _single(monday + timedelta(days=sign * 7 * n + wd))
+
+    # 上N周 / 下N周（范围）
+    m = re.match(r"^(上|下)(\d+|[一二两三四五六七八九十]+)周$", expr)
+    if m:
+        sign = -1 if m.group(1) == "上" else 1
+        n = cn_to_num(m.group(2))
+        if n is not None:
+            base = monday + timedelta(days=sign * 7 * n)
+            return _range(base, base + timedelta(days=6))
+
+    # === 3.5 英文 weekday ===
+    # last/this/next Monday 等
+    m = re.match(r"^(last|this|next)\s+(\w+)$", low)
+    if m:
+        rel = m.group(1)
+        wd = EN_WEEKDAY.get(m.group(2))
+        if wd is not None:
+            offset = {"last": -7, "this": 0, "next": 7}[rel]
+            return _single(monday + timedelta(days=offset + wd))
+    # 裸英文 weekday（如 "Monday"），按本周X
+    if low in EN_WEEKDAY:
+        wd = EN_WEEKDAY[low]
+        return _single(monday + timedelta(days=wd))
+
+    # === 3.6 英文相对周/月/年（范围） ===
+    # this/current week, last/previous week, next week
+    if low in ("this week", "current week", "the week"):
+        result = _range(monday, monday + timedelta(days=6))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if low in ("last week", "previous week", "past week"):
+        return _range(monday - timedelta(days=7), monday - timedelta(days=1))
+    if low in ("next week", "the following week"):
+        return _range(monday + timedelta(days=7), monday + timedelta(days=13))
+
+    # this/last/next month
+    if low in ("this month", "current month", "the month"):
+        first = anchor.replace(day=1)
+        last = _last_day_of_month(anchor.year, anchor.month)
+        result = _range(first, last)
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if low in ("last month", "previous month", "past month"):
+        prev = _month_offset(anchor, -1)
+        first = prev.replace(day=1)
+        last = _last_day_of_month(first.year, first.month)
+        return _range(first, last)
+    if low in ("next month", "the following month"):
+        nxt = _month_offset(anchor, 1)
+        first = nxt.replace(day=1)
+        last = _last_day_of_month(first.year, first.month)
+        return _range(first, last)
+
+    # this/last/next year
+    if low in ("this year", "current year"):
+        result = _range(date(anchor.year, 1, 1), date(anchor.year, 12, 31))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if low in ("last year", "previous year"):
+        return _range(date(anchor.year - 1, 1, 1), date(anchor.year - 1, 12, 31))
+    if low in ("next year",):
+        return _range(date(anchor.year + 1, 1, 1), date(anchor.year + 1, 12, 31))
+
+    # first half / second half of the year
+    if low in ("first half", "first half year", "first half of the year", "h1"):
+        result = _range(date(anchor.year, 1, 1), date(anchor.year, 6, 30))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if low in ("second half", "second half year", "second half of the year", "h2"):
+        result = _range(date(anchor.year, 7, 1), date(anchor.year, 12, 31))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # === 3.7 英文相对天/周/月（数量 + 单位 + ago/later/from now/from today） ===
+    # N day(s) ago / N days later / N days from now / in N days
+    m = re.match(
+        r"^(\d+|[a-z]+)\s+(day|days|week|weeks|month|months|year|years)\s+"
+        r"(ago|before|earlier|later|after|from\s+now|from\s+today|hence)$",
+        low,
+    )
+    if m:
+        n = en_to_num(m.group(1))
+        unit = m.group(2)
+        direction = m.group(3)
+        if n is not None:
+            sign = -1 if direction in ("ago", "before", "earlier") else 1
+            if unit.startswith("day"):
+                return _single(anchor + timedelta(days=sign * n))
+            if unit.startswith("week"):
+                return _single(anchor + timedelta(weeks=sign * n))
+            if unit.startswith("month"):
+                return _single(_clamp_day(_month_offset(anchor, sign * n), anchor.day))
+            if unit.startswith("year"):
+                return _single(date(anchor.year + sign * n, anchor.month, min(
+                    anchor.day, _last_day_of_month(anchor.year + sign * n, anchor.month).day
+                )))
+
+    # in N days/weeks/months
+    m = re.match(r"^in\s+(\d+|[a-z]+)\s+(day|days|week|weeks|month|months|year|years)$", low)
+    if m:
+        n = en_to_num(m.group(1))
+        unit = m.group(2)
+        if n is not None:
+            if unit.startswith("day"):
+                return _single(anchor + timedelta(days=n))
+            if unit.startswith("week"):
+                return _single(anchor + timedelta(weeks=n))
+            if unit.startswith("month"):
+                return _single(_clamp_day(_month_offset(anchor, n), anchor.day))
+            if unit.startswith("year"):
+                return _single(date(anchor.year + n, anchor.month, min(
+                    anchor.day, _last_day_of_month(anchor.year + n, anchor.month).day
+                )))
+
+    # the day before yesterday / the day after tomorrow（已在前面 alias 部分处理过 yesterday/tomorrow）
+    if low in ("day before yesterday",):
+        return _single(anchor - timedelta(days=2))
+    if low in ("day after tomorrow",):
+        return _single(anchor + timedelta(days=2))
+
+    # === 3.8 英文 月份+日（含/不含年份） ===
+    # 支持: "May 5", "May 5th", "May 5, 2026", "May 5 2026", "5 May", "5th May 2026", "Jan 31"
+    # 序数后缀 st/nd/rd/th 直接吃掉
+    low_clean = re.sub(r"(\d+)(st|nd|rd|th)\b", r"\1", low)
+
+    # Month Day[, Year]
+    m = re.match(
+        r"^([a-z]+)\.?\s+(\d{1,2})(?:\s*,\s*|\s+)?(\d{4})?$", low_clean
+    )
+    if m and m.group(1) in EN_MONTH:
+        month = EN_MONTH[m.group(1)]
+        day = int(m.group(2))
+        year = int(m.group(3)) if m.group(3) else _infer_year_for_month(anchor, month)
+        try:
+            return _single(date(year, month, day))
+        except ValueError:
+            pass
+
+    # Day Month[, Year]
+    m = re.match(
+        r"^(\d{1,2})\s+([a-z]+)\.?(?:\s*,\s*|\s+)?(\d{4})?$", low_clean
+    )
+    if m and m.group(2) in EN_MONTH:
+        month = EN_MONTH[m.group(2)]
+        day = int(m.group(1))
+        year = int(m.group(3)) if m.group(3) else _infer_year_for_month(anchor, month)
+        try:
+            return _single(date(year, month, day))
+        except ValueError:
+            pass
+
+    # === 4. 月份相关 ===
+
+    # 本月 / 这个月
+    if expr in ("本月", "这个月", "当月"):
+        first = anchor.replace(day=1)
+        last = _last_day_of_month(anchor.year, anchor.month)
+        result = _range(first, last)
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # 上月 / 上个月
+    if expr in ("上月", "上个月"):
+        prev = _month_offset(anchor, -1)
+        first = prev.replace(day=1)
+        last = _last_day_of_month(first.year, first.month)
+        return _range(first, last)
+
+    # 下月 / 下个月
+    if expr in ("下月", "下个月"):
+        nxt = _month_offset(anchor, 1)
+        first = nxt.replace(day=1)
+        last = _last_day_of_month(first.year, first.month)
+        return _range(first, last)
+
+    # 下个月N号 / 下月N号 / 下个月N日
+    m = re.match(r"^下(个)?月(\d{1,2}|[一二三四五六七八九十二十三十]+)[号日]?$", expr)
+    if m:
+        day_num = cn_to_num(m.group(2))
+        if day_num is not None:
+            nxt = _month_offset(anchor, 1)
+            return _single(date(nxt.year, nxt.month, day_num))
+
+    # 上个月N号 / 上月N号
+    m = re.match(r"^上(个)?月(\d{1,2}|[一二三四五六七八九十二十三十]+)[号日]?$", expr)
+    if m:
+        day_num = cn_to_num(m.group(2))
+        if day_num is not None:
+            prev = _month_offset(anchor, -1)
+            return _single(date(prev.year, prev.month, day_num))
+
+    # 本月N号 / 这个月N号
+    m = re.match(r"^[本这](个)?月(\d{1,2}|[一二三四五六七八九十二十三十]+)[号日]?$", expr)
+    if m:
+        day_num = cn_to_num(m.group(2))
+        if day_num is not None:
+            return _single(date(anchor.year, anchor.month, day_num))
+
+    # 月初 / 月末 / 月底
+    if expr in ("月初",):
+        return _single(anchor.replace(day=1))
+    if expr in ("月末", "月底"):
+        return _single(_last_day_of_month(anchor.year, anchor.month))
+    if expr in ("上月初", "上个月初"):
+        prev = _month_offset(anchor, -1)
+        return _single(prev.replace(day=1))
+    if expr in ("上月末", "上月底", "上个月末", "上个月底"):
+        prev = _month_offset(anchor, -1)
+        return _single(_last_day_of_month(prev.year, prev.month))
+    if expr in ("下月初", "下个月初"):
+        nxt = _month_offset(anchor, 1)
+        return _single(nxt.replace(day=1))
+    if expr in ("下月末", "下月底", "下个月末", "下个月底"):
+        nxt = _month_offset(anchor, 1)
+        return _single(_last_day_of_month(nxt.year, nxt.month))
+
+    # 年初/年末
+    if expr in ("年初", "今年初"):
+        return _single(date(anchor.year, 1, 1))
+    if expr in ("年末", "年底", "今年末", "今年底"):
+        return _single(date(anchor.year, 12, 31))
+
+    # === 5. 年份相关 ===
+
+    if expr in ("今年", "本年", "本年度"):
+        result = _range(date(anchor.year, 1, 1), date(anchor.year, 12, 31))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if expr in ("明年", "下一年"):
+        return _range(date(anchor.year + 1, 1, 1), date(anchor.year + 1, 12, 31))
+    if expr in ("去年", "上一年"):
+        return _range(date(anchor.year - 1, 1, 1), date(anchor.year - 1, 12, 31))
+
+    # 上半年 / 下半年
+    if expr in ("上半年",):
+        result = _range(date(anchor.year, 1, 1), date(anchor.year, 6, 30))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+    if expr in ("下半年",):
+        result = _range(date(anchor.year, 7, 1), date(anchor.year, 12, 31))
+        return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # 明年N月 / 明年N月N日
+    m = re.match(r"^明年(\d{1,2})月(\d{1,2})?[日号]?$", expr)
+    if m:
+        month = int(m.group(1))
+        if m.group(2):
+            return _single(date(anchor.year + 1, month, int(m.group(2))))
+        else:
+            first = date(anchor.year + 1, month, 1)
+            last = _last_day_of_month(first.year, first.month)
+            result = _range(first, last)
+            return _maybe_clamp_range(result, anchor, clamp_to_anchor)
+
+    # === 6. 本月第N个周X ===
+    m = re.match(r"^本月第([一二三四五\d])个?周([一二三四五六日天\d])$", expr)
+    if m:
+        nth = cn_to_num(m.group(1))
+        wd = WEEKDAY_MAP.get(m.group(2))
+        if nth is not None and wd is not None:
+            result = _nth_weekday_of_month(anchor.year, anchor.month, wd, nth)
+            if result:
+                return _single(result)
+
+    # 下个月第N个周X
+    m = re.match(r"^下(个)?月第([一二三四五\d])个?周([一二三四五六日天\d])$", expr)
+    if m:
+        nth = cn_to_num(m.group(2))
+        wd = WEEKDAY_MAP.get(m.group(3))
+        if nth is not None and wd is not None:
+            nxt = _month_offset(anchor, 1)
+            result = _nth_weekday_of_month(nxt.year, nxt.month, wd, nth)
+            if result:
+                return _single(result)
+
+    # === 无法解析 ===
+    return {"success": False, "reason": f"无法解析表达式 '{expr}'，不在已知模式中"}
+
+
+def _infer_year_for_month(anchor: date, month: int) -> int:
+    """无年份月份推断：默认当年；若 month > anchor.month，回退为去年同月。"""
+    return anchor.year - 1 if month > anchor.month else anchor.year
+
+
+def _maybe_clamp_range(result: Dict, anchor: date, clamp_to_anchor: bool) -> Dict:
+    """若需要，将 range 的结束日期裁剪到 anchor（用于“本月/本周/某月”等避免包含未来）。"""
+    if not clamp_to_anchor:
+        return result
+    if not (result.get("success") and result.get("type") == "range"):
+        return result
+
+    d_from = date.fromisoformat(result["resolved_date_from"])
+    d_to = date.fromisoformat(result["resolved_date_to"])
+    if d_to <= anchor:
+        return result
+    if anchor < d_from:
+        return {
+            "success": False,
+            "reason": "解析出的日期范围全部在未来（相对 anchor）",
+        }
+
+    clamped = _range(d_from, anchor)
+    clamped["clamped_to_anchor"] = True
+    return clamped
+
+
+def _extract_weekday_exprs(expr: str) -> List[str]:
+    """从完整句子中提取周X类日期表达；裸周X默认本周X。"""
+    patterns = [
+        r"(?:上上|下下|上|下|本|这)(?:个)?周[一二三四五六日天\d]",
+        r"周[一二三四五六日天\d]",
+    ]
+    found: List[str] = []
+    occupied: List[Tuple[int, int]] = []
+
+    for pattern in patterns:
+        for match in re.finditer(pattern, expr):
+            span = match.span()
+            if any(not (span[1] <= start or span[0] >= end) for start, end in occupied):
+                continue
+            found.append(match.group(0))
+            occupied.append(span)
+
+    return found
+
+
+def _single(d: date, anchor: Optional[date] = None) -> Dict:
+    """构造单日期成功结果"""
+    out = {
+        "success": True,
+        "type": "single",
+        "resolved_date": d.isoformat(),
+        "resolved_weekday": WEEKDAY_NAMES[d.weekday()],
+    }
+    if anchor is not None:
+        out["is_future"] = d > anchor
+        out["is_past"] = d < anchor
+    return out
+
+
+def _range(d_from: date, d_to: date, anchor: Optional[date] = None) -> Dict:
+    """构造日期范围成功结果"""
+    out = {
+        "success": True,
+        "type": "range",
+        "resolved_date_from": d_from.isoformat(),
+        "resolved_date_from_weekday": WEEKDAY_NAMES[d_from.weekday()],
+        "resolved_date_to": d_to.isoformat(),
+        "resolved_date_to_weekday": WEEKDAY_NAMES[d_to.weekday()],
+    }
+    if anchor is not None:
+        out["fully_in_future"] = d_from > anchor
+        out["partially_in_future"] = d_to > anchor and d_from <= anchor
+    return out
+
+
+def _last_day_of_month(year: int, month: int) -> date:
+    """获取某月最后一天"""
+    if month == 12:
+        return date(year, 12, 31)
+    return date(year, month + 1, 1) - timedelta(days=1)
+
+
+def _clamp_day(month_first: date, day: int) -> date:
+    """把 (year, month) 月内的某天 clamp 到合法范围（处理 1/31 → 2/28 等）。"""
+    last = _last_day_of_month(month_first.year, month_first.month)
+    return date(month_first.year, month_first.month, min(day, last.day))
+
+
+def _month_offset(d: date, offset: int) -> date:
+    """月份偏移，返回目标月的第一天"""
+    month = d.month + offset
+    year = d.year
+    while month > 12:
+        month -= 12
+        year += 1
+    while month < 1:
+        month += 12
+        year -= 1
+    return date(year, month, 1)
+
+
+def _nth_weekday_of_month(year: int, month: int, weekday: int, nth: int) -> Optional[date]:
+    """获取某月第 nth 个星期 weekday（weekday: 0=周一, 6=周日）"""
+    first = date(year, month, 1)
+    # 找到该月第一个目标 weekday
+    diff = (weekday - first.weekday()) % 7
+    first_target = first + timedelta(days=diff)
+    # 第 nth 个
+    result = first_target + timedelta(weeks=nth - 1)
+    if result.month != month:
+        return None
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="解析中文日期表达式为绝对日期")
+    parser.add_argument("--expr", required=True, help="用户日期表达，如'下周六'、'下个月3号'")
+    parser.add_argument("--anchor", required=True, help="锚点日期，YYYY-MM-DD格式，通常为今天")
+    parser.add_argument(
+        "--clamp-to-anchor",
+        action="store_true",
+        help="若解析出日期范围，将结束日期裁剪到 anchor（避免包含未来日期）",
+    )
+    args = parser.parse_args()
+
+    try:
+        anchor = date.fromisoformat(args.anchor)
+    except ValueError:
+        result = {
+            "success": False,
+            "reason": f"锚点日期格式错误: '{args.anchor}'，需要 YYYY-MM-DD",
+        }
+        print(json.dumps(result, ensure_ascii=False))
+        sys.exit(1)
+
+    result = resolve(args.expr, anchor, clamp_to_anchor=args.clamp_to_anchor)
+
+    # 附加锚点信息
+    result["anchor_date"] = anchor.isoformat()
+    result["anchor_weekday"] = WEEKDAY_NAMES[anchor.weekday()]
+    result["expression"] = args.expr
+    result["clamp_to_anchor"] = bool(args.clamp_to_anchor)
+    if result["success"]:
+        result["method"] = "rule_based"
+        # 统一附加 is_future / fully_in_future / partially_in_future
+        if result.get("type") == "single":
+            d = date.fromisoformat(result["resolved_date"])
+            result["is_future"] = d > anchor
+            result["is_past"] = d < anchor
+        elif result.get("type") == "range":
+            d_from = date.fromisoformat(result["resolved_date_from"])
+            d_to = date.fromisoformat(result["resolved_date_to"])
+            result["fully_in_future"] = d_from > anchor
+            result["partially_in_future"] = d_to > anchor and d_from <= anchor
+        elif result.get("type") == "multiple":
+            for item in result.get("resolved_dates", []):
+                d = date.fromisoformat(item["resolved_date"])
+                item["is_future"] = d > anchor
+                item["is_past"] = d < anchor
+
+    print(json.dumps(result, ensure_ascii=False))
+    sys.exit(0 if result["success"] else 1)
+
+
+if __name__ == "__main__":
+    main()