sophhub 0.2.3 → 0.2.4

package/skills/sophnet-schedule/src/_meta.json

@@ -0,0 +1,6 @@
+{
+  "slug": "sophnet-schedule",
+  "version": "1.0.0",
+  "description": "Sophnet 日程提醒：Google Calendar 自动同步、定时提醒、日程变化监控、ROC 周期事件管理",
+  "publishedAt": 1743292800000
+}

package/skills/sophnet-schedule/src/api/models.py

@@ -0,0 +1,245 @@
+"""
+API 请求 / 响应 Pydantic 模型。
+
+所有外部接口的 schema 集中在此定义，与业务逻辑解耦。
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+# ── 通用 ──────────────────────────────────────────────────────────────
+
+class OkResponse(BaseModel):
+    ok: bool = True
+    id: Optional[str] = None
+    message: str = ""
+
+
+# ── 日历事件 ──────────────────────────────────────────────────────────
+
+class EventOut(BaseModel):
+    id: str
+    summary: str
+    start: str                    # ISO 8601
+    end: str
+    is_all_day: bool = False
+    location: str = ""
+    description: str = ""
+    status: str = "confirmed"
+    duration_minutes: int = 0
+    provider: str = ""
+    sync_state: str = ""
+
+
+class ConflictOut(BaseModel):
+    type: str                     # "conflict" | "tight"
+    event_a: str                  # summary
+    event_b: str
+    time_a: str                   # "HH:MM–HH:MM"
+    time_b: str
+    overlap_minutes: int = 0
+    gap_minutes: int = 0
+    text: str                     # 格式化文字描述
+
+
+class EventsResponse(BaseModel):
+    date: str
+    events: List[EventOut]
+    conflicts: List[ConflictOut]
+    provider: str = ""
+    active_mode: str = ""
+
+
+class EventCreateRequest(BaseModel):
+    summary: str = Field(..., description="事件标题")
+    date: str    = Field(..., description="日期 YYYY-MM-DD")
+    start: str   = Field(..., description="开始时间 HH:MM")
+    end: Optional[str]   = Field(None, description="结束时间 HH:MM（与 duration 二选一）")
+    duration: int        = Field(60,   gt=0, description="持续分钟数（默认 60）")
+    location: str        = Field("",   description="地点")
+    description: str     = Field("",   description="备注")
+    remind: int          = Field(0,    ge=0, description="提前提醒分钟数（0 = 不注册）")
+
+
+class EventCreateResponse(BaseModel):
+    ok: bool
+    event_id: str = ""
+    summary: str = ""
+    start: str = ""
+    end: str = ""
+    reminder_registered: bool = False
+    error: str = ""
+    provider: str = ""
+    sync_state: str = ""
+
+
+class EventDeleteResponse(BaseModel):
+    ok: bool
+    event_id: str
+    error: str = ""
+
+
+# ── ROC 事件 ──────────────────────────────────────────────────────────
+
+class RocEventOut(BaseModel):
+    id: str
+    name: str
+    rule: str
+    reminder_time: str
+    lead_days: int
+    description: str = ""
+    # 计算字段（含年份时附带）
+    event_date: Optional[str] = None
+    reminder_date: Optional[str] = None
+
+
+class RocListResponse(BaseModel):
+    year: int
+    events: List[RocEventOut]
+
+
+class RocUpcomingItem(BaseModel):
+    id: str
+    name: str
+    event_date: str
+    reminder_date: str
+    days_until_reminder: int
+    days_until_event: int
+    description: str = ""
+
+
+class RocUpcomingResponse(BaseModel):
+    today: str
+    days: int
+    upcoming: List[RocUpcomingItem]
+
+
+class RocEventCreateRequest(BaseModel):
+    id: str          = Field(..., description="唯一 ID（英文小写+下划线）")
+    name: str        = Field(..., description="事件名称")
+    rule: str        = Field(..., description="时间规则，如 每年6月15日")
+    reminder_time: str = Field("09:00", description="推送时间 HH:MM")
+    lead_days: int   = Field(7,  ge=0, description="提前提醒天数")
+    description: str = Field("", description="说明")
+
+
+class RocEventUpdateRequest(BaseModel):
+    name: Optional[str] = None
+    rule: Optional[str] = None
+    reminder_time: Optional[str] = None
+    lead_days: Optional[int] = None
+    description: Optional[str] = None
+
+
+# ── 提醒 ──────────────────────────────────────────────────────────────
+
+class ReminderItem(BaseModel):
+    summary: str
+    start: str
+    end: str
+    lead_minutes: int
+    trigger_at: str
+    message: str
+
+
+class RemindersResponse(BaseModel):
+    window_minutes: int
+    reminders: List[ReminderItem]
+    provider: str = ""
+    active_mode: str = ""
+
+
+# ── Cron 任务 ─────────────────────────────────────────────────────────
+
+class TaskItem(BaseModel):
+    name: str
+    description: str
+    schedule_kind: str    # "at" | "cron"
+    schedule_expr: str    # HH:MM 或 cron expr
+    type: str             # "silent" | "report"
+
+
+class TasksResponse(BaseModel):
+    tasks: List[TaskItem]
+
+
+class TaskSyncResponse(BaseModel):
+    ok: bool = True
+    dry_run: bool = False
+    added: List[str] = []
+    skipped: List[str] = []
+    errors: List[str] = []
+    message: str = ""
+
+
+# ── 日报 ──────────────────────────────────────────────────────────────
+
+class DailyPlanResponse(BaseModel):
+    date: str
+    events: List[EventOut]
+    conflicts: List[ConflictOut]
+    reminders_registered: int
+    markdown: str         # 完整日报 Markdown 文本
+    provider: str = ""
+
+
+# ── Google 接入 ───────────────────────────────────────────────────────
+
+class GoogleGuideStep(BaseModel):
+    key: str
+    title: str
+    description: str
+
+
+class GoogleSyncSummary(BaseModel):
+    status: str = "idle"
+    total: int = 0
+    succeeded: int = 0
+    failed: int = 0
+    skipped: int = 0
+    started_at: str = ""
+    finished_at: str = ""
+    last_error: str = ""
+
+
+class GoogleStatusResponse(BaseModel):
+    active_mode: str
+    google_state: str
+    has_token: bool
+    masked_client_id: str = ""
+    needs_initial_sync: bool = False
+    current_step: str
+    last_error: str = ""
+    last_sync_time: str = ""
+    last_sync_summary: GoogleSyncSummary
+
+
+class GoogleGuideResponse(BaseModel):
+    current_step: str
+    active_mode: str
+    google_state: str
+    callback_url: str
+    required_fields: List[str]
+    steps: List[GoogleGuideStep]
+
+
+class GoogleStartRequest(BaseModel):
+    client_id: str = Field(..., description="Google OAuth Client ID")
+    client_secret: str = Field(..., description="Google OAuth Client Secret")
+
+
+class GoogleStartResponse(BaseModel):
+    ok: bool = True
+    authorize_url: str
+    expires_at: str
+    google_state: str
+
+
+class GoogleSyncResponse(BaseModel):
+    ok: bool = True
+    active_mode: str
+    google_state: str
+    summary: GoogleSyncSummary

package/skills/sophnet-schedule/src/apps/add_event.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+自然语言日程录入工具。
+
+Agent 将用户的自然语言解析为结构化字段后，调用此脚本写入 Google Calendar，
+并可选择性地立即在 OpenClaw Cron 中注册提醒任务。
+
+用法：
+  # 基本：只指定开始时间，持续时间默认 60 分钟
+  python3 apps/add_event.py \\
+    --summary "客户会议" \\
+    --date "2026-03-31" \\
+    --start "14:00"
+
+  # 完整：指定结束时间 + 地点 + 备注
+  python3 apps/add_event.py \\
+    --summary "产品评审" \\
+    --date "2026-04-02" \\
+    --start "10:00" \\
+    --end "11:30" \\
+    --location "线上" \\
+    --description "Q2 规划讨论" \\
+    --remind 15
+
+  # 只指定时长（分钟）而非结束时间
+  python3 apps/add_event.py \\
+    --summary "跑步" \\
+    --date "2026-04-01" \\
+    --start "07:00" \\
+    --duration 45
+
+  # 干运行（不写 GCal，只打印 payload）
+  python3 apps/add_event.py \\
+    --summary "测试事件" \\
+    --date "2026-04-01" \\
+    --start "10:00" \\
+    --dry-run
+
+输出（JSON，供 Agent 读取）：
+  成功：{"ok": true,  "event_id": "xxx", "summary": "...", "start": "...", "end": "..."}
+  失败：{"ok": false, "error": "..."}
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# ── sys.path ─────────────────────────────────────────────────────
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from config.settings import TIMEZONE
+from gcal.client import CalendarAPIError, CalendarAuthError
+from services.calendar_backend import active_provider, create_event as backend_create_event
+from services.datetime_utils import (
+    DateTimeValidationError,
+    build_event_range,
+    parse_local_date,
+    parse_local_time,
+)
+from services.job_store import append_job_if_absent
+from services.task_builder import build_reminder_task, build_reminder_task_name
+
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(message)s")
+logger = logging.getLogger(__name__)
+
+
+# ─────────────────────────── 时间解析 ────────────────────────────
+
+def parse_date(date_str: str, tz: str) -> datetime:
+    return parse_local_date(date_str, tz)
+
+
+def parse_time(time_str: str, base_date: datetime) -> datetime:
+    return parse_local_time(time_str, base_date)
+
+
+# ─────────────────────────── 提醒注册 ────────────────────────────
+
+def _register_reminder(
+    summary: str,
+    start: datetime,
+    lead_minutes: int,
+    dry_run: bool,
+    event_id: str = "",
+) -> dict:
+    """
+    将提醒任务注册到 OpenClaw Cron（jobs.json）。
+
+    返回状态字典：
+    {
+        "registered": bool,      # 是否成功注册
+        "existed": bool,         # 是否已存在
+        "error": str or None     # 错误信息（如果有）
+    }
+    """
+    from datetime import timezone
+
+    remind_at_utc = (start - timedelta(minutes=lead_minutes)).astimezone(timezone.utc)
+    name = build_reminder_task_name(summary, start, event_id)
+    payload = build_reminder_task(
+        name=name,
+        remind_at_utc=remind_at_utc,
+        message=(
+            f"⏰ **{summary}** 将在 {lead_minutes} 分钟后开始\n"
+            f"🕐 {start.strftime('%H:%M')}"
+        ),
+    )
+
+    if dry_run:
+        print(f"[dry-run] 将注册提醒任务: {name}（{remind_at_utc.strftime('%H:%M')} UTC）",
+              file=sys.stderr)
+        return {"registered": True, "existed": False, "error": None}
+
+    try:
+        if append_job_if_absent(payload):
+            logger.warning(f"✅ 提醒任务已注册: {name}")
+            return {"registered": True, "existed": False, "error": None}
+        else:
+            logger.warning(f"⏭️  提醒任务已存在，跳过: {name}")
+            return {"registered": True, "existed": True, "error": None}
+    except Exception as e:
+        error_msg = str(e)
+        logger.warning(f"注册提醒失败（不影响日历写入）: {error_msg}")
+        return {"registered": False, "existed": False, "error": error_msg}
+
+
+# ─────────────────────────── main ─────────────────────────────────
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="将结构化日程信息写入 Google Calendar",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--summary",     required=True,  help="事件标题")
+    parser.add_argument("--date",        required=True,  help="日期 YYYY-MM-DD")
+    parser.add_argument("--start",       required=True,  help="开始时间 HH:MM")
+    parser.add_argument("--end",                         help="结束时间 HH:MM（与 --duration 二选一）")
+    parser.add_argument("--duration",    type=int, default=60,
+                        help="持续时间（分钟，默认 60）；--end 优先")
+    parser.add_argument("--location",    default="",     help="地点（可选）")
+    parser.add_argument("--description", default="",     help="备注（可选）")
+    parser.add_argument("--remind",      type=int, default=0,
+                        help="提前提醒分钟数（0 = 不注册提醒，默认 0）")
+    parser.add_argument("--dry-run",     action="store_true",
+                        help="只打印 payload，不写入 Google Calendar")
+    args = parser.parse_args()
+
+    def _fail(msg: str) -> None:
+        print(json.dumps({"ok": False, "error": msg}, ensure_ascii=False))
+        sys.exit(1)
+
+    # ── 1. 解析时间 ───────────────────────────────────────────────
+    try:
+        start, end = build_event_range(
+            args.date,
+            args.start,
+            args.end,
+            args.duration,
+            TIMEZONE,
+        )
+    except DateTimeValidationError as e:
+        _fail(str(e))
+        return
+
+    # ── 2. dry-run ────────────────────────────────────────────────
+    payload_preview = {
+        "summary":     args.summary,
+        "date":        args.date,
+        "start":       start.strftime("%H:%M"),
+        "end":         end.strftime("%H:%M"),
+        "duration_min": int((end - start).total_seconds() / 60),
+        "location":    args.location,
+        "description": args.description,
+        "remind_min":  args.remind,
+    }
+    if args.dry_run:
+        print(json.dumps(
+            {
+                "ok": True,
+                "dry_run": True,
+                "provider": active_provider(),
+                "payload": payload_preview,
+            },
+            ensure_ascii=False, indent=2,
+        ))
+        if args.remind > 0:
+            _register_reminder(args.summary, start, args.remind, dry_run=True)
+        return
+
+    # ── 3. 写入当前事件后端 ───────────────────────────────────────
+    try:
+        created = backend_create_event(
+            summary=args.summary,
+            start=start,
+            end=end,
+            location=args.location,
+            description=args.description,
+            remind_minutes=args.remind,
+        )
+    except (CalendarAuthError, CalendarAPIError) as e:
+        _fail(str(e))
+        return
+
+    # ── 4. 可选：注册提醒 ─────────────────────────────────────────
+    reminder_status = {"registered": False, "existed": False, "error": None}
+    if args.remind > 0:
+        reminder_status = _register_reminder(
+            args.summary, start, args.remind, dry_run=False, event_id=created.event_id
+        )
+
+    # ── 5. 输出结果 ───────────────────────────────────────────────
+    result = {
+        "ok":                     True,
+        "provider":               created.provider,
+        "sync_state":             created.sync_state,
+        "event_id":               created.event_id,
+        "summary":                args.summary,
+        "date":                   args.date,
+        "start":                  start.strftime("%H:%M"),
+        "end":                    end.strftime("%H:%M"),
+        "duration_min":           int((end - start).total_seconds() / 60),
+        "location":               args.location,
+        "remind_min":             args.remind,
+        "reminder_registered":    reminder_status["registered"],
+        "reminder_existed":       reminder_status["existed"],
+        "reminder_error":         reminder_status["error"],
+    }
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/sophnet-schedule/src/apps/check_reminders.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+即时提醒检查器。
+
+执行时机：由 OpenClaw Cron 高频触发（如每 5 分钟），或手动执行。
+
+流程：
+  1. 拉取今天剩余的日程
+  2. 计算每个事件的提醒时间
+  3. 筛选出提醒时间在未来 N 分钟内的事件
+  4. 有提醒时输出提醒内容（供 OpenClaw 投递）
+  5. 无提醒时只输出 NO_REPLY
+
+即时提醒检查器，此处补齐实现。
+
+用法：
+  python3 apps/check_reminders.py              # 默认检查窗口 30 分钟
+  python3 apps/check_reminders.py --window 15  # 只检查 15 分钟内
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from datetime import timedelta
+from pathlib import Path
+
+# ── sys.path ─────────────────────────────────────────────────────
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from config.settings import TIMEZONE
+from services.calendar_backend import active_provider, list_events
+from services.time_window import get_remaining_today_window, now_tz
+from services.reminder_planner import plan_reminders
+
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(message)s")
+logger = logging.getLogger(__name__)
+
+NO_REPLY = "NO_REPLY"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="即时提醒检查")
+    parser.add_argument(
+        "--window", type=int, default=30,
+        help="检查提醒时间在未来多少分钟内的事件（默认 30）",
+    )
+    parser.add_argument(
+        "--json", action="store_true",
+        help="输出结构化 JSON，供 HTTP API 使用",
+    )
+    args = parser.parse_args()
+
+    now = now_tz(TIMEZONE)
+    check_until = now + timedelta(minutes=args.window)
+
+    # ── 1. 拉取今天剩余日程 ───────────────────────────────────────
+    t_min, t_max = get_remaining_today_window(TIMEZONE)
+
+    try:
+        events = list_events(t_min, t_max)
+    except Exception as e:
+        logger.error(f"拉取日程失败: {e}")
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+
+    # ── 2. 计算提醒计划 ───────────────────────────────────────────
+    plans = plan_reminders(events, now=now, tz=TIMEZONE)
+
+    # ── 3. 筛选窗口内需要提醒的事件 ─────────────────────────────
+    due = [
+        p for p in plans
+        if p.should_schedule and now <= p.remind_at <= check_until
+    ]
+
+    if args.json:
+        items = [
+            {
+                "summary": p.event.summary,
+                "start": p.event.start.isoformat(),
+                "end": p.event.end.isoformat(),
+                "lead_minutes": p.lead_minutes,
+                "trigger_at": p.remind_at.isoformat(),
+                "message": p.reminder_message(),
+            }
+            for p in due
+        ]
+        print(json.dumps(
+            {
+                "ok": True,
+                "window_minutes": args.window,
+                "provider": active_provider(),
+                "active_mode": active_provider(),
+                "reminders": items,
+            },
+            ensure_ascii=False,
+        ))
+        return
+
+    if not due:
+        print(NO_REPLY)
+        sys.exit(0)
+
+    # ── 4. 输出提醒 ───────────────────────────────────────────────
+    for p in due:
+        print(p.reminder_message())
+
+
+if __name__ == "__main__":
+    main()