496 行
19 KiB
Python
496 行
19 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""Local C3 agenda contracts for the chat-side companion plugin.
|
|
|
|
The schedule definition is deliberately imported from ``bot_personal_contract``
|
|
so this module cannot drift into a second set of window thresholds. Everything
|
|
stored by this module is a plain JSON-compatible dictionary or scalar.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from copy import deepcopy
|
|
from datetime import date, datetime, time, timedelta
|
|
import hashlib
|
|
import json
|
|
from typing import Any, Iterable
|
|
from zoneinfo import ZoneInfo
|
|
|
|
try: # package import
|
|
from .bot_personal_contract import (
|
|
SCHEDULE_WINDOWS as _CONTRACT_WINDOWS,
|
|
WINDOW_SLUGS as _CONTRACT_WINDOW_SLUGS,
|
|
window_for_minutes as _contract_window_for_minutes,
|
|
)
|
|
except ImportError: # direct test/import from the plugin directory
|
|
from bot_personal_contract import (
|
|
SCHEDULE_WINDOWS as _CONTRACT_WINDOWS,
|
|
WINDOW_SLUGS as _CONTRACT_WINDOW_SLUGS,
|
|
window_for_minutes as _contract_window_for_minutes,
|
|
)
|
|
|
|
|
|
AGENDA_VERSION = 1
|
|
SCHEDULE_WINDOWS = tuple(_CONTRACT_WINDOWS)
|
|
WINDOW_SLUGS = tuple(_CONTRACT_WINDOW_SLUGS)
|
|
SOURCE_KINDS = {"planned", "observed", "projection", "reconciled"}
|
|
EVIDENCE_LEVELS = {"L0", "L1", "L2", "L3", "L4", "L5"}
|
|
AGENDA_STATUSES = {
|
|
"planned",
|
|
"active",
|
|
"completed",
|
|
"partially_completed",
|
|
"overridden",
|
|
"reconciled",
|
|
"deferred",
|
|
"cancelled",
|
|
"unknown",
|
|
}
|
|
|
|
|
|
class AgendaContractError(ValueError):
|
|
"""Raised when a value cannot satisfy the local agenda contract."""
|
|
|
|
|
|
def _text(value: Any, limit: int = 240) -> str:
|
|
if value is None:
|
|
return ""
|
|
return str(value).strip()[:limit]
|
|
|
|
|
|
def _list(value: Any, limit: int = 30) -> list[str]:
|
|
if isinstance(value, str):
|
|
value = [value]
|
|
if not isinstance(value, (list, tuple, set)):
|
|
return []
|
|
result: list[str] = []
|
|
for item in value:
|
|
text = _text(item, 200)
|
|
if text and text not in result:
|
|
result.append(text)
|
|
if len(result) >= limit:
|
|
break
|
|
return result
|
|
|
|
def _items(value: Any, limit: int = 40) -> list[Any]:
|
|
if not isinstance(value, list):
|
|
return []
|
|
return deepcopy(value[:limit])
|
|
|
|
|
|
def _version(value: Any, default: int = 1) -> int:
|
|
try:
|
|
return max(1, int(value or default))
|
|
except (TypeError, ValueError):
|
|
return default
|
|
|
|
|
|
def _now_iso(now: datetime | None = None) -> str:
|
|
current = now or datetime.now().astimezone()
|
|
if current.tzinfo is None:
|
|
current = current.replace(tzinfo=ZoneInfo("Asia/Shanghai"))
|
|
return current.isoformat(timespec="seconds")
|
|
|
|
|
|
def stable_id(prefix: str, *parts: Any) -> str:
|
|
"""Return a deterministic, order-stable identifier for JSON-like parts."""
|
|
|
|
def canonical(value: Any) -> Any:
|
|
if isinstance(value, dict):
|
|
return {str(key): canonical(value[key]) for key in sorted(value, key=str)}
|
|
if isinstance(value, (list, tuple)):
|
|
return [canonical(item) for item in value]
|
|
if isinstance(value, set):
|
|
return sorted(canonical(item) for item in value)
|
|
if isinstance(value, (datetime, date, time)):
|
|
return value.isoformat()
|
|
return value
|
|
|
|
raw = json.dumps(canonical(parts), ensure_ascii=False, sort_keys=True, default=str, separators=(",", ":"))
|
|
digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:20]
|
|
return f"{_text(prefix, 48) or 'agenda'}-{digest}"
|
|
|
|
|
|
def timezone_or_default(timezone_name: Any = "Asia/Shanghai") -> ZoneInfo:
|
|
try:
|
|
return ZoneInfo(_text(timezone_name, 64) or "Asia/Shanghai")
|
|
except Exception:
|
|
return ZoneInfo("Asia/Shanghai")
|
|
|
|
|
|
def normalize_window(value: Any) -> str:
|
|
candidate = _text(value, 48).lower()
|
|
return candidate if candidate in WINDOW_SLUGS else ""
|
|
|
|
|
|
def window_for_minutes(minutes: Any) -> str:
|
|
"""Delegate minute classification to the shared chat-side contract."""
|
|
|
|
try:
|
|
return _contract_window_for_minutes(int(minutes))
|
|
except (TypeError, ValueError):
|
|
return ""
|
|
|
|
|
|
def _window_spec(window: Any) -> tuple[str, str, int, int]:
|
|
slug = normalize_window(window)
|
|
for item in SCHEDULE_WINDOWS:
|
|
if item[0] == slug:
|
|
return item
|
|
raise AgendaContractError(f"unknown window: {window!r}")
|
|
|
|
|
|
def _as_date(value: Any) -> date:
|
|
if isinstance(value, datetime):
|
|
return value.date()
|
|
if isinstance(value, date):
|
|
return value
|
|
try:
|
|
return date.fromisoformat(_text(value, 32))
|
|
except ValueError as exc:
|
|
raise AgendaContractError(f"invalid date: {value!r}") from exc
|
|
|
|
|
|
def parse_datetime(value: Any, *, timezone_name: str = "Asia/Shanghai", default: datetime | None = None) -> datetime:
|
|
"""Parse ISO/date/time values and attach the requested local timezone."""
|
|
|
|
tz = timezone_or_default(timezone_name)
|
|
if isinstance(value, datetime):
|
|
current = value
|
|
elif isinstance(value, date):
|
|
current = datetime.combine(value, time.min)
|
|
else:
|
|
text = _text(value, 96)
|
|
if not text:
|
|
if default is None:
|
|
raise AgendaContractError("datetime is required")
|
|
current = default
|
|
else:
|
|
if text.endswith("Z"):
|
|
text = text[:-1] + "+00:00"
|
|
try:
|
|
current = datetime.fromisoformat(text)
|
|
except ValueError:
|
|
try:
|
|
current = datetime.strptime(text, "%H:%M")
|
|
except ValueError as exc:
|
|
raise AgendaContractError(f"invalid datetime: {value!r}") from exc
|
|
if current.tzinfo is None:
|
|
return current.replace(tzinfo=tz)
|
|
return current.astimezone(tz)
|
|
|
|
|
|
def window_bounds(
|
|
window_date: str | date,
|
|
window: str,
|
|
*,
|
|
timezone_name: str = "Asia/Shanghai",
|
|
) -> tuple[datetime, datetime]:
|
|
"""Return inclusive-start/exclusive-end aware bounds for a window date."""
|
|
|
|
_slug, _name, start_minute, end_minute = _window_spec(window)
|
|
target = _as_date(window_date)
|
|
tz = timezone_or_default(timezone_name)
|
|
start = datetime.combine(target, time.min, tzinfo=tz) + timedelta(minutes=start_minute)
|
|
end_date = target + timedelta(days=1) if end_minute <= start_minute else target
|
|
end = datetime.combine(end_date, time.min, tzinfo=tz) + timedelta(minutes=end_minute)
|
|
return start, end
|
|
|
|
|
|
def window_for_datetime(
|
|
value: datetime | date | str,
|
|
timezone_name: str = "Asia/Shanghai",
|
|
) -> tuple[str, str, datetime, datetime]:
|
|
"""Resolve a moment to ``(slug, window_date, start, end)``.
|
|
|
|
The early-morning part of ``late_night`` belongs to the preceding
|
|
``window_date``. Minute classification always goes through the shared
|
|
``bot_personal_contract.window_for_minutes`` implementation.
|
|
"""
|
|
|
|
current = parse_datetime(value, timezone_name=timezone_name)
|
|
minute = current.hour * 60 + current.minute
|
|
slug = window_for_minutes(minute)
|
|
if not slug:
|
|
raise AgendaContractError(f"no window for minute: {minute}")
|
|
_slug, _name, start_minute, end_minute = _window_spec(slug)
|
|
belongs_to_previous_date = end_minute <= start_minute and minute < end_minute
|
|
target_date = current.date() - timedelta(days=1) if belongs_to_previous_date else current.date()
|
|
start, end = window_bounds(target_date, slug, timezone_name=timezone_name)
|
|
return slug, target_date.isoformat(), start, end
|
|
|
|
|
|
def window_for_plan_minutes(
|
|
plan_date: str | date,
|
|
minutes: Any,
|
|
*,
|
|
timezone_name: str = "Asia/Shanghai",
|
|
) -> tuple[str, str]:
|
|
"""Resolve a plan date plus possibly out-of-range minute offset."""
|
|
|
|
try:
|
|
base = _as_date(plan_date)
|
|
value = int(minutes)
|
|
except (TypeError, ValueError, AgendaContractError):
|
|
return "", ""
|
|
day_offset, raw_minute = divmod(value, 24 * 60)
|
|
moment = datetime.combine(base + timedelta(days=day_offset), time.min)
|
|
moment += timedelta(minutes=raw_minute)
|
|
slug, target_date, _start, _end = window_for_datetime(moment, timezone_name=timezone_name)
|
|
return slug, target_date
|
|
|
|
|
|
def interval_overlaps_window(
|
|
item: dict[str, Any],
|
|
start: datetime,
|
|
end: datetime,
|
|
*,
|
|
timezone_name: str = "Asia/Shanghai",
|
|
) -> bool:
|
|
"""Return whether an item interval intersects ``[start, end)``."""
|
|
|
|
if not isinstance(item, dict):
|
|
return False
|
|
try:
|
|
item_start = parse_datetime(item.get("start_at") or item.get("start"), timezone_name=timezone_name)
|
|
except AgendaContractError:
|
|
return False
|
|
try:
|
|
item_end = parse_datetime(
|
|
item.get("end_at") or item.get("end"),
|
|
timezone_name=timezone_name,
|
|
default=item_start,
|
|
)
|
|
except AgendaContractError:
|
|
item_end = item_start
|
|
if item_end <= item_start:
|
|
item_end = item_start + timedelta(seconds=1)
|
|
start_local = parse_datetime(start, timezone_name=timezone_name)
|
|
end_local = parse_datetime(end, timezone_name=timezone_name)
|
|
return item_start < end_local and item_end > start_local
|
|
|
|
|
|
def normalize_source_kind(value: Any, default: str) -> str:
|
|
candidate = _text(value, 32).lower()
|
|
return candidate if candidate in SOURCE_KINDS else default
|
|
|
|
|
|
def normalize_evidence_level(value: Any, default: str) -> str:
|
|
candidate = _text(value, 8).upper()
|
|
return candidate if candidate in EVIDENCE_LEVELS else default
|
|
|
|
|
|
def _normalize_status(value: Any, default: str) -> str:
|
|
candidate = _text(value, 32).lower()
|
|
return candidate if candidate in AGENDA_STATUSES else default
|
|
|
|
|
|
def normalize_plan_item(
|
|
raw: dict[str, Any],
|
|
*,
|
|
plan_id: str = "",
|
|
now: datetime | None = None,
|
|
) -> dict[str, Any]:
|
|
if not isinstance(raw, dict):
|
|
raise AgendaContractError("plan item must be an object")
|
|
title = _text(raw.get("title") or raw.get("activity") or raw.get("description"), 240)
|
|
if not title:
|
|
raise AgendaContractError("plan item requires a title")
|
|
result = deepcopy(raw)
|
|
result.update(
|
|
{
|
|
"plan_id": _text(plan_id or raw.get("plan_id") or raw.get("event_id"), 120)
|
|
or stable_id("plan", title, raw.get("date"), raw.get("time"), raw.get("start_at")),
|
|
"title": title,
|
|
"source_kind": "planned",
|
|
"evidence_level": normalize_evidence_level(raw.get("evidence_level"), "L0"),
|
|
"status": _normalize_status(raw.get("status"), "planned"),
|
|
"version": _version(raw.get("version")),
|
|
"source_refs": _list(raw.get("source_refs") or raw.get("basis")),
|
|
"visibility": _text(raw.get("visibility"), 32) or "private",
|
|
"certainty": _text(raw.get("certainty"), 24) or "medium",
|
|
"updated_at": _text(raw.get("updated_at"), 64) or _now_iso(now),
|
|
}
|
|
)
|
|
return result
|
|
|
|
|
|
def normalize_observed_activity(
|
|
raw: dict[str, Any],
|
|
*,
|
|
now: datetime | None = None,
|
|
) -> dict[str, Any]:
|
|
if not isinstance(raw, dict):
|
|
raise AgendaContractError("observed activity must be an object")
|
|
title = _text(raw.get("title") or raw.get("summary") or raw.get("activity"), 240)
|
|
if not title:
|
|
raise AgendaContractError("observed activity requires a title")
|
|
source_refs = _list(raw.get("source_refs") or raw.get("evidence_refs"))
|
|
result = deepcopy(raw)
|
|
result.update(
|
|
{
|
|
"activity_id": _text(raw.get("activity_id") or raw.get("id"), 120)
|
|
or stable_id("activity", title, raw.get("start_at") or raw.get("start"), raw.get("end_at") or raw.get("end"), source_refs),
|
|
"title": title,
|
|
"kind": _text(raw.get("kind"), 48) or "conversation",
|
|
"source_kind": "observed",
|
|
"source": _text(raw.get("source"), 64) or "conversation",
|
|
"source_refs": source_refs,
|
|
"participants": _list(raw.get("participants")),
|
|
"evidence_level": normalize_evidence_level(raw.get("evidence_level"), "L2"),
|
|
"visibility": _text(raw.get("visibility"), 32) or "private",
|
|
"certainty": _text(raw.get("certainty"), 24) or "medium",
|
|
"status": _normalize_status(raw.get("status"), "active"),
|
|
"version": _version(raw.get("version")),
|
|
"updated_at": _text(raw.get("updated_at"), 64) or _now_iso(now),
|
|
}
|
|
)
|
|
return result
|
|
|
|
|
|
def normalize_window_snapshot(
|
|
raw: dict[str, Any],
|
|
*,
|
|
now: datetime | None = None,
|
|
) -> dict[str, Any]:
|
|
if not isinstance(raw, dict):
|
|
raise AgendaContractError("window snapshot must be an object")
|
|
window_date = _text(raw.get("window_date") or raw.get("date"), 20)
|
|
window = normalize_window(raw.get("window") or raw.get("slug"))
|
|
if not window_date or not window:
|
|
raise AgendaContractError("window snapshot requires window_date and window")
|
|
result = deepcopy(raw)
|
|
result.update(
|
|
{
|
|
"snapshot_id": _text(raw.get("snapshot_id"), 160) or stable_id("agenda_snapshot", window_date, window),
|
|
"date": _text(raw.get("date"), 20) or window_date,
|
|
"window_date": window_date,
|
|
"window": window,
|
|
"planned": _items(raw.get("planned")),
|
|
"observed": _items(raw.get("observed")),
|
|
"reconciled": _items(raw.get("reconciled")),
|
|
"open_items": _list(raw.get("open_items")),
|
|
"source_refs": _list(raw.get("source_refs")),
|
|
"source_kind": "projection",
|
|
"evidence_level": normalize_evidence_level(raw.get("evidence_level"), "L2"),
|
|
"visibility": _text(raw.get("visibility"), 32) or "private",
|
|
"certainty": _text(raw.get("certainty"), 24) or "medium",
|
|
"status": _normalize_status(raw.get("status"), "completed"),
|
|
"version": _version(raw.get("version")),
|
|
"generated_at": _text(raw.get("generated_at"), 64) or _now_iso(now),
|
|
"timezone": _text(raw.get("timezone"), 64) or "Asia/Shanghai",
|
|
}
|
|
)
|
|
return result
|
|
|
|
|
|
def normalize_reconciliation(raw: dict[str, Any], *, now: datetime | None = None) -> dict[str, Any]:
|
|
if not isinstance(raw, dict):
|
|
raise AgendaContractError("reconciliation must be an object")
|
|
window_date = _text(raw.get("window_date") or raw.get("date"), 20)
|
|
window = normalize_window(raw.get("window") or raw.get("slug"))
|
|
result = deepcopy(raw)
|
|
result.update(
|
|
{
|
|
"reconciliation_id": _text(raw.get("reconciliation_id"), 160)
|
|
or stable_id("reconciliation", window_date, window),
|
|
"window_date": window_date,
|
|
"date": _text(raw.get("date"), 20) or window_date,
|
|
"window": window,
|
|
"source_kind": "reconciled",
|
|
"evidence_level": normalize_evidence_level(raw.get("evidence_level"), "L3"),
|
|
"visibility": _text(raw.get("visibility"), 32) or "private",
|
|
"certainty": _text(raw.get("certainty"), 24) or "high",
|
|
"status": _normalize_status(raw.get("status"), "completed"),
|
|
"source_refs": _list(raw.get("source_refs")),
|
|
"version": _version(raw.get("version")),
|
|
"generated_at": _text(raw.get("generated_at"), 64) or _now_iso(now),
|
|
}
|
|
)
|
|
return result
|
|
|
|
|
|
def migrate_store(data: dict[str, Any]) -> tuple[dict[str, Any], bool]:
|
|
"""Additive migration for old plugin JSON without deleting old fields."""
|
|
|
|
if not isinstance(data, dict):
|
|
raise AgendaContractError("store must be an object")
|
|
changed = False
|
|
defaults: dict[str, Any] = {
|
|
"agenda_version": AGENDA_VERSION,
|
|
"observed_activities": [],
|
|
"window_snapshots": [],
|
|
"agenda_reconciliation_history": [],
|
|
}
|
|
for key, default in defaults.items():
|
|
if key not in data:
|
|
data[key] = deepcopy(default)
|
|
changed = True
|
|
elif not isinstance(data.get(key), type(default)):
|
|
data[f"legacy_{key}"] = deepcopy(data[key])
|
|
data[key] = deepcopy(default)
|
|
changed = True
|
|
|
|
if "activities" in data and not data["observed_activities"] and isinstance(data["activities"], list):
|
|
data["observed_activities"] = deepcopy(data["activities"])
|
|
changed = True
|
|
|
|
try:
|
|
current_version = max(0, int(data.get("agenda_version") or 0))
|
|
except (TypeError, ValueError):
|
|
current_version = 0
|
|
if current_version < AGENDA_VERSION:
|
|
data["agenda_version"] = AGENDA_VERSION
|
|
changed = True
|
|
|
|
if isinstance(data.get("daily_plan"), dict) and isinstance(data["daily_plan"].get("items"), list):
|
|
migrated_items: list[Any] = []
|
|
for item in data["daily_plan"]["items"]:
|
|
if not isinstance(item, dict):
|
|
migrated_items.append(item)
|
|
continue
|
|
try:
|
|
migrated_items.append(normalize_plan_item(item))
|
|
except AgendaContractError:
|
|
migrated_items.append(deepcopy(item))
|
|
if migrated_items != data["daily_plan"]["items"]:
|
|
data["daily_plan"]["items"] = migrated_items
|
|
changed = True
|
|
return data, changed
|
|
|
|
|
|
def agenda_entry_from_plan(plan: dict[str, Any], *, reason: str = "") -> dict[str, Any]:
|
|
result = {
|
|
"entry_id": stable_id("agenda_entry", "plan", plan.get("plan_id")),
|
|
"title": _text(plan.get("title") or plan.get("activity"), 240),
|
|
"kind": "planned",
|
|
"status": _normalize_status(plan.get("status"), "planned"),
|
|
"source_kind": "planned",
|
|
"evidence_level": normalize_evidence_level(plan.get("evidence_level"), "L0"),
|
|
"visibility": _text(plan.get("visibility"), 32) or "private",
|
|
"certainty": _text(plan.get("certainty"), 24) or "medium",
|
|
"source_refs": _list(plan.get("source_refs")) or [_text(plan.get("plan_id"), 120)],
|
|
}
|
|
if reason:
|
|
result["reconciliation_reason"] = reason
|
|
for key in ("plan_id", "start_at", "end_at", "date", "time", "end", "participants", "version"):
|
|
if key in plan:
|
|
result[key] = deepcopy(plan[key])
|
|
return result
|
|
|
|
|
|
def agenda_entry_from_activity(activity: dict[str, Any], *, source_refs: Iterable[str] = ()) -> dict[str, Any]:
|
|
refs = _list(list(source_refs)) or _list(activity.get("source_refs")) or [_text(activity.get("activity_id"), 120)]
|
|
result = {
|
|
"entry_id": stable_id("agenda_entry", "activity", activity.get("activity_id")),
|
|
"title": _text(activity.get("title"), 240),
|
|
"kind": "observed",
|
|
"status": _normalize_status(activity.get("status"), "active"),
|
|
"source_kind": "observed",
|
|
"evidence_level": normalize_evidence_level(activity.get("evidence_level"), "L2"),
|
|
"visibility": _text(activity.get("visibility"), 32) or "private",
|
|
"certainty": _text(activity.get("certainty"), 24) or "medium",
|
|
"source_refs": refs,
|
|
}
|
|
for key in ("activity_id", "start_at", "end_at", "participants", "version", "kind"):
|
|
if key in activity:
|
|
result[key] = deepcopy(activity[key])
|
|
return result
|