sophhub 0.2.3 → 0.2.4

package/skills/sophnet-schedule/src/services/calendar_backend.py

@@ -0,0 +1,139 @@
+"""
+轻量日历后端选择器。
+
+不引入完整 provider 抽象层，只集中管理：
+- 当前模式判断
+- 事件读取
+- 事件创建
+- 事件删除
+- Google 同步触发
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from config.settings import (
+    GCAL_CALENDAR_ID,
+    GCAL_MAX_RETRIES,
+    GCAL_SSL_VERIFY,
+    GCAL_TIMEOUT,
+    GCAL_TOKEN_PATH,
+    PROXIES,
+    TIMEZONE,
+)
+from gcal.client import CalendarClient
+from gcal.models import CalendarEvent
+from services import local_event_store
+from services.google_integration import get_active_mode, sync_local_events_to_google
+
+
+@dataclass
+class EventView:
+    event: CalendarEvent
+    provider: str
+    sync_state: str = ""
+
+
+@dataclass
+class EventCreateResult:
+    provider: str
+    event_id: str
+    sync_state: str = ""
+
+
+def _new_google_client() -> CalendarClient:
+    return CalendarClient(
+        token_path=GCAL_TOKEN_PATH,
+        proxies=PROXIES,
+        calendar_id=GCAL_CALENDAR_ID,
+        timeout=GCAL_TIMEOUT,
+        max_retries=GCAL_MAX_RETRIES,
+        verify=GCAL_SSL_VERIFY,
+    )
+
+
+def active_provider() -> str:
+    return get_active_mode()
+
+
+def list_event_views(time_min: datetime, time_max: datetime) -> list[EventView]:
+    provider = active_provider()
+    if provider == "google":
+        client = _new_google_client()
+        return [
+            EventView(event=event, provider="google", sync_state="")
+            for event in client.list_events(time_min, time_max)
+        ]
+
+    records = local_event_store.list_records(time_min=time_min, time_max=time_max)
+    return [
+        EventView(
+            event=local_event_store.record_to_event(record),
+            provider="local",
+            sync_state=record.get("sync_state", "local_only"),
+        )
+        for record in records
+    ]
+
+
+def list_events(time_min: datetime, time_max: datetime) -> list[CalendarEvent]:
+    return [item.event for item in list_event_views(time_min, time_max)]
+
+
+def create_event(
+    summary: str,
+    start: datetime,
+    end: datetime,
+    location: str = "",
+    description: str = "",
+    remind_minutes: int = 0,
+) -> EventCreateResult:
+    provider = active_provider()
+    if provider == "google":
+        client = _new_google_client()
+        event_id = client.create_event(
+            summary=summary,
+            start=start,
+            end=end,
+            location=location,
+            description=description,
+            tz=TIMEZONE,
+        )
+        return EventCreateResult(provider="google", event_id=event_id, sync_state="")
+
+    record = local_event_store.create_event(
+        summary=summary,
+        start=start,
+        end=end,
+        location=location,
+        description=description,
+        remind_minutes=remind_minutes,
+    )
+    return EventCreateResult(
+        provider="local",
+        event_id=record["id"],
+        sync_state=record.get("sync_state", "local_only"),
+    )
+
+
+def delete_event(event_id: str) -> bool:
+    provider = active_provider()
+    if event_id.startswith("local_") or provider == "local":
+        return local_event_store.delete_event(event_id)
+    client = _new_google_client()
+    client.delete_event(event_id)
+    return True
+
+
+def get_event_status(event_id: str) -> str | None:
+    provider = active_provider()
+    if event_id.startswith("local_") or provider == "local":
+        return local_event_store.get_event_status(event_id)
+    client = _new_google_client()
+    return client.get_event_status(event_id)
+
+
+def sync_local_events() -> dict:
+    return sync_local_events_to_google()

package/skills/sophnet-schedule/src/services/conflict_detector.py

@@ -0,0 +1,96 @@
+"""
+日程冲突检测器。
+
+检测同一批事件中时间重叠的事件对。全天事件不参与检测。
+
+规则：
+  - A.start < B.end AND A.end > B.start → 有重叠
+  - 紧接场景（间隔 < 5 分钟）→ 额外警告（is_tight=True）
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from gcal.models import CalendarEvent
+
+_TIGHT_MINUTES = 5   # 间隔小于此值视为"紧接"
+
+
+@dataclass
+class ConflictPair:
+    a: CalendarEvent
+    b: CalendarEvent
+    overlap_minutes: int   # 0 表示紧接但不重叠
+    is_tight: bool = False # True = 无重叠但间隔 < 5 分钟
+
+    def format_text(self) -> str:
+        ta = f"{self.a.start.strftime('%H:%M')}–{self.a.end.strftime('%H:%M')}"
+        tb = f"{self.b.start.strftime('%H:%M')}–{self.b.end.strftime('%H:%M')}"
+        if self.is_tight:
+            gap = int((self.b.start - self.a.end).total_seconds() / 60)
+            return (
+                f"⚡ 紧接：【{self.a.summary}】({ta}) 结束后仅 {gap} 分钟"
+                f"【{self.b.summary}】({tb}) 就开始"
+            )
+        return (
+            f"⚠️ 冲突：【{self.a.summary}】({ta})"
+            f" 与 【{self.b.summary}】({tb})"
+            f" 重叠 {self.overlap_minutes} 分钟"
+        )
+
+
+def detect_conflicts(
+    events: list[CalendarEvent],
+    tight_minutes: int = _TIGHT_MINUTES,
+) -> list[ConflictPair]:
+    """
+    检测时间重叠或紧接的事件对。
+
+    返回结果按事件开始时间升序排列。
+    仅检测有确定时间的事件（跳过全天事件）。
+    """
+    timed = [
+        e for e in events
+        if not e.is_all_day and e.start is not None and e.end is not None
+    ]
+    timed.sort(key=lambda e: e.start)
+
+    pairs: list[ConflictPair] = []
+    for i in range(len(timed)):
+        for j in range(i + 1, len(timed)):
+            a, b = timed[i], timed[j]
+
+            # b 开始已超过 a 结束 + tight window → 不可能再有冲突/紧接
+            if b.start >= a.end + timedelta(minutes=tight_minutes):
+                break
+
+            if b.start < a.end:
+                # 有重叠
+                overlap_start = max(a.start, b.start)
+                overlap_end   = min(a.end,   b.end)
+                overlap_min   = int((overlap_end - overlap_start).total_seconds() / 60)
+                if overlap_min > 0:
+                    pairs.append(ConflictPair(a=a, b=b, overlap_minutes=overlap_min))
+            else:
+                # 无重叠但间隔 < tight_minutes
+                pairs.append(ConflictPair(a=a, b=b, overlap_minutes=0, is_tight=True))
+
+    return pairs
+
+
+def format_conflicts_section(pairs: list[ConflictPair]) -> str:
+    """将冲突列表格式化为 Markdown 通知文本。"""
+    if not pairs:
+        return ""
+    lines = ["⚠️ **发现日程冲突：**", ""]
+    for p in pairs:
+        lines.append(f"- {p.format_text()}")
+    lines.append("")
+    lines.append("建议：检查 Google Calendar 并调整时间安排。")
+    return "\n".join(lines)

package/skills/sophnet-schedule/src/services/datetime_utils.py

@@ -0,0 +1,117 @@
+"""
+共享的时间解析与时区工具。
+
+统一处理：
+- 本地业务时区下的“今天/今年”
+- 本地日期 + 时间组合
+- offset-less ISO 时间按业务时区解释
+- 跨午夜结束时间
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from compat import ZoneInfo, make_aware
+
+_DEFAULT_TZ = "Asia/Shanghai"
+
+
+class DateTimeValidationError(ValueError):
+    """时间输入不合法。"""
+
+
+def now_local(tz: str = _DEFAULT_TZ) -> datetime:
+    return datetime.now(ZoneInfo(tz))
+
+
+def current_date_str(tz: str = _DEFAULT_TZ) -> str:
+    return now_local(tz).strftime("%Y-%m-%d")
+
+
+def current_year(tz: str = _DEFAULT_TZ) -> int:
+    return now_local(tz).year
+
+
+def parse_local_date(date_str: str, tz: str = _DEFAULT_TZ) -> datetime:
+    try:
+        dt = datetime.strptime(date_str.strip(), "%Y-%m-%d")
+    except ValueError as exc:
+        raise DateTimeValidationError(
+            f"日期格式错误：'{date_str}'，应为 YYYY-MM-DD"
+        ) from exc
+    return make_aware(dt, tz)
+
+
+def parse_local_time(time_str: str, base_date: datetime) -> datetime:
+    raw = time_str.strip()
+    for fmt in ("%H:%M", "%H:%M:%S"):
+        try:
+            parsed = datetime.strptime(raw, fmt)
+            return base_date.replace(
+                hour=parsed.hour,
+                minute=parsed.minute,
+                second=0,
+                microsecond=0,
+            )
+        except ValueError:
+            continue
+    raise DateTimeValidationError(f"时间格式错误：'{time_str}'，应为 HH:MM")
+
+
+def build_event_range(
+    date_str: str,
+    start_str: str,
+    end_str: str | None = None,
+    duration_minutes: int = 60,
+    tz: str = _DEFAULT_TZ,
+) -> tuple[datetime, datetime]:
+    if duration_minutes <= 0:
+        raise DateTimeValidationError("持续时间必须大于 0 分钟")
+
+    base = parse_local_date(date_str, tz)
+    start_dt = parse_local_time(start_str, base)
+
+    if end_str:
+        end_dt = parse_local_time(end_str, base)
+        if end_dt <= start_dt:
+            end_dt = end_dt + timedelta(days=1)
+    else:
+        end_dt = start_dt + timedelta(minutes=duration_minutes)
+
+    return start_dt, end_dt
+
+
+def parse_iso_datetime(
+    value: str,
+    tz: str = _DEFAULT_TZ,
+    assume_local_if_naive: bool = True,
+) -> datetime:
+    raw = value.strip()
+    if not raw:
+        raise DateTimeValidationError("时间不能为空")
+
+    try:
+        dt = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise DateTimeValidationError(
+            f"时间格式错误：'{value}'，应为 ISO 8601"
+        ) from exc
+
+    if dt.tzinfo is None:
+        if not assume_local_if_naive:
+            raise DateTimeValidationError(
+                f"时间缺少时区偏移：'{value}'，请使用 ISO 8601 带时区格式"
+            )
+        return make_aware(dt, tz)
+
+    return dt
+
+
+def local_date_window(date_str: str, tz: str = _DEFAULT_TZ) -> tuple[datetime, datetime]:
+    start = parse_local_date(date_str, tz)
+    return start, start + timedelta(days=1)
+
+
+def local_date_label(dt: datetime, tz: str = _DEFAULT_TZ) -> str:
+    return dt.astimezone(ZoneInfo(tz)).strftime("%Y-%m-%d")

package/skills/sophnet-schedule/src/services/event_classifier.py

@@ -0,0 +1,100 @@
+"""
+事件分类器。
+
+根据事件标题关键词判断类型（sport / meal / family / medical / appointment）。
+分类规则从 config/reminder_rules.yaml 加载，支持运行时覆盖。
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_RULES_PATH = Path(__file__).parent.parent / "config" / "reminder_rules.yaml"
+
+# yaml 不可用时的内置 fallback
+_BUILTIN_KEYWORDS: dict[str, list[str]] = {
+    "sport":       ["跑步", "晨跑", "健身", "游泳", "打球", "羽毛球", "乒乓球", "网球", "篮球", "足球", "瑜伽"],
+    "meal":        ["聚餐", "饭局", "晚餐", "午餐", "火锅", "烧烤", "下午茶"],
+    "family":      ["亲子", "接送", "接孩子", "送孩子", "家长会", "探望", "探亲", "回家"],
+    "medical":     ["体检", "看病", "就医", "门诊", "复诊", "牙医", "口腔", "打疫苗"],
+    "appointment": ["预约", "约定", "美发", "理发", "活动", "讲座", "展览", "旅行", "课程"],
+}
+_BUILTIN_DEFAULT = "appointment"
+
+
+def _load_rules(path: Path) -> dict:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except Exception as e:
+        logger.warning(f"加载 reminder_rules.yaml 失败，使用内置规则: {e}")
+        return {}
+
+
+class EventClassifier:
+    """
+    事件分类器。
+
+    用法：
+        clf = EventClassifier()
+        clf.classify("跑步晨练")   # → "sport"
+        clf.classify("家庭聚餐")   # → "meal"
+        clf.classify("牙医预约")   # → "medical"
+        clf.classify("接孩子放学") # → "family"
+        clf.classify("理发")       # → "appointment"
+    """
+
+    def __init__(
+        self,
+        rules_path: Path | None = None,
+        keywords: dict[str, list[str]] | None = None,
+        default_type: str | None = None,
+    ):
+        data = _load_rules(rules_path or _DEFAULT_RULES_PATH)
+
+        # 优先级：外部传入 > yaml > 内置
+        if keywords:
+            self.keywords = keywords
+        elif data.get("keywords"):
+            self.keywords = {
+                k: [str(w) for w in v]
+                for k, v in data["keywords"].items()
+            }
+        else:
+            self.keywords = _BUILTIN_KEYWORDS
+
+        self.default_type: str = (
+            default_type or data.get("default_type", _BUILTIN_DEFAULT)
+        )
+
+    def classify(self, summary: str, description: str = "") -> str:
+        """
+        返回事件类型：'sport' | 'meal' | 'family' | 'medical' | 'appointment'。
+        按 sport → meal → family → medical → appointment 顺序匹配，匹配即返回。
+        """
+        text = (summary + " " + description).lower()
+        for event_type in ("sport", "meal", "family", "medical", "appointment"):
+            for kw in self.keywords.get(event_type, []):
+                if kw.lower() in text:
+                    return event_type
+        return self.default_type
+
+
+# 模块级默认实例，可直接 import 快速使用
+_default: EventClassifier | None = None
+
+
+def classify_event(summary: str, description: str = "") -> str:
+    """模块级快捷函数，使用默认分类器（延迟初始化）。"""
+    global _default
+    if _default is None:
+        _default = EventClassifier()
+    return _default.classify(summary, description)

package/skills/sophnet-schedule/src/services/event_diff.py

@@ -0,0 +1,160 @@
+"""
+日程变化检测。
+
+对比两份事件快照，输出新增、修改、取消列表。
+
+核心规则：
+  - 日程自然结束后消失  → 不通知
+  - 日程被取消          → 通知（status=cancelled）
+  - 标题或时间有变化    → 通知（修改）
+  - 无任何变化          → 不通知
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from gcal.models import CalendarEvent
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EventDiffResult:
+    added:    list[CalendarEvent]                              = field(default_factory=list)
+    removed:  list[CalendarEvent]                              = field(default_factory=list)
+    modified: list[tuple[CalendarEvent, CalendarEvent]]        = field(default_factory=list)
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(self.added or self.removed or self.modified)
+
+    @property
+    def summary_text(self) -> str:
+        parts = []
+        if self.added:    parts.append(f"新增 {len(self.added)} 个")
+        if self.removed:  parts.append(f"取消 {len(self.removed)} 个")
+        if self.modified: parts.append(f"修改 {len(self.modified)} 个")
+        return "、".join(parts) if parts else "无变化"
+
+    def format_notification(self) -> str:
+        """生成发送给 用户 的通知文本。"""
+        lines = ["📅 **Google Calendar 日程变化通知**", ""]
+
+        if self.added:
+            lines.append("**新增日程：**")
+            for e in self.added[:5]:
+                lines.append(f"• {e.summary} — {_fmt_time(e.start)}")
+            if len(self.added) > 5:
+                lines.append(f"  还有 {len(self.added) - 5} 个…")
+            lines.append("")
+
+        if self.removed:
+            lines.append("**已取消：**")
+            for e in self.removed[:5]:
+                lines.append(f"• {e.summary} — {_fmt_time(e.start)}")
+            if len(self.removed) > 5:
+                lines.append(f"  还有 {len(self.removed) - 5} 个…")
+            lines.append("")
+
+        if self.modified:
+            lines.append("**已修改：**")
+            for prev, cur in self.modified[:3]:
+                if prev.summary != cur.summary:
+                    lines.append(f"• 标题：{prev.summary} → {cur.summary}")
+                else:
+                    lines.append(
+                        f"• {cur.summary}：{_fmt_time(prev.start)} → {_fmt_time(cur.start)}"
+                    )
+            if len(self.modified) > 3:
+                lines.append(f"  还有 {len(self.modified) - 3} 个…")
+
+        return "\n".join(lines)
+
+
+def diff_events(
+    current: list[CalendarEvent],
+    last: list[CalendarEvent],
+    get_remote_status: Callable[[str], str | None] | None = None,
+    now: datetime | None = None,
+) -> EventDiffResult:
+    """
+    对比当前事件列表与上次快照。
+
+    get_remote_status：
+      可选回调，传入 event_id，返回 'confirmed' | 'cancelled' | None。
+      传入时使用 API 查询精确判断取消/自然结束（推荐）。
+      不传时退化为时间判断（event.is_past → 不报告）。
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    cur_map  = {e.id: e for e in current if e.id}
+    last_map = {e.id: e for e in last    if e.id}
+
+    added:    list[CalendarEvent]                       = []
+    removed:  list[CalendarEvent]                       = []
+    modified: list[tuple[CalendarEvent, CalendarEvent]] = []
+
+    # 新增
+    for eid, event in cur_map.items():
+        if eid not in last_map:
+            added.append(event)
+
+    # 消失：区分取消 vs 自然结束
+    for eid, event in last_map.items():
+        if eid not in cur_map:
+            if get_remote_status is not None:
+                status = get_remote_status(eid)
+                logger.debug(f"事件 {eid}（{event.summary}）远端状态: {status}")
+                if status == "cancelled":
+                    removed.append(event)
+                else:
+                    logger.info(f"'{event.summary}' 已自然结束，不通知")
+            else:
+                # 降级：用时间判断
+                if not event.is_past(now):
+                    removed.append(event)
+                else:
+                    logger.info(f"'{event.summary}' 已结束，不通知")
+
+    # 修改（标题、开始时间、结束时间）
+    for eid in cur_map.keys() & last_map.keys():
+        if _is_modified(cur_map[eid], last_map[eid]):
+            modified.append((last_map[eid], cur_map[eid]))
+
+    return EventDiffResult(added=added, removed=removed, modified=modified)
+
+
+# ────────────────────────── 内部工具 ─────────────────────────────
+
+def _is_modified(cur: CalendarEvent, prev: CalendarEvent) -> bool:
+    if cur.summary != prev.summary:
+        return True
+
+    def to_utc(dt: datetime) -> datetime:
+        if dt.tzinfo is None:
+            return dt.replace(tzinfo=timezone.utc)
+        return dt.astimezone(timezone.utc)
+
+    if to_utc(cur.start) != to_utc(prev.start):
+        return True
+    if to_utc(cur.end) != to_utc(prev.end):
+        return True
+    return False
+
+
+def _fmt_time(dt: datetime) -> str:
+    import sys
+    from pathlib import Path
+    sys.path.insert(0, str(Path(__file__).parent.parent))
+    from compat import ZoneInfo, make_aware
+    bj = dt.astimezone(ZoneInfo("Asia/Shanghai"))
+    return bj.strftime("%m月%d日 %H:%M")