271 行
13 KiB
Python
271 行
13 KiB
Python
|
|
# -*- coding: utf-8 -*-
|
|||
|
|
"""跨插件共享合同:Bot 个人归档 + 日程分级(陪伴分支)
|
|||
|
|
|
|||
|
|
⚠️ 这个文件在两个插件里**各有一份,必须逐字相同**:
|
|||
|
|
陪伴插件:astrbot_plugin_private_companion/bot_personal_contract.py
|
|||
|
|
记忆插件:astrbot_plugin_memory_companion/core/bot_personal_contract.py
|
|||
|
|
权威副本在 peiban/doc/shared/bot_personal_contract.py。
|
|||
|
|
|
|||
|
|
两个插件是独立的 AstrBot 插件包,互相不能 import,所以「共享常量」只能靠
|
|||
|
|
「同一份文件复制两份 + 启动时指纹互校」来保证。任何改动必须同时满足三条:
|
|||
|
|
|
|||
|
|
① 两侧同一次提交(不允许一侧先合)
|
|||
|
|
② 升 CONTRACT_REVISION
|
|||
|
|
③ 重算并更新 CONTRACT_FINGERPRINT(python bot_personal_contract.py 会打印)
|
|||
|
|
|
|||
|
|
只依赖标准库。不要在这里 import 任何插件内部模块,否则复制到对侧会炸。
|
|||
|
|
|
|||
|
|
修改规则与背景见:peiban/doc/跨插件共享合同.md
|
|||
|
|
"""
|
|||
|
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
import hashlib
|
|||
|
|
import json
|
|||
|
|
|
|||
|
|
CONTRACT_NAME = "bot_personal_archive"
|
|||
|
|
CONTRACT_REVISION = 1
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 一、日程分级(原「四段」→ 陪伴分支五段)
|
|||
|
|
#
|
|||
|
|
# 这是**唯一定义源**。两侧任何地方需要窗口划分,都必须从这张表派生,不允许再写
|
|||
|
|
# 第二份硬编码——OPS 分支就是因为存在四份互不派生的副本,改一处改不动全部。
|
|||
|
|
#
|
|||
|
|
# 边界与原版已持久化的主动配额桶(user["proactive_daypart_counts"],
|
|||
|
|
# constants.py:489)完全对齐,所以「日程窗口」与「主动配额桶」共享切点,
|
|||
|
|
# 但**仍是两套独立存储**:配额桶是计数器,窗口是快照/归档的维度,不要合并。
|
|||
|
|
#
|
|||
|
|
# 字段:(slug, 中文名, 起始分钟, 结束分钟)。结束分钟 <= 起始分钟表示跨午夜。
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
SCHEDULE_WINDOWS: tuple[tuple[str, str, int, int], ...] = (
|
|||
|
|
("late_night", "深夜", 21 * 60, 6 * 60), # 21:00 - 次日 06:00
|
|||
|
|
("morning", "早晨", 6 * 60, 11 * 60), # 06:00 - 11:00
|
|||
|
|
("noon", "中午", 11 * 60, 14 * 60 + 30), # 11:00 - 14:30
|
|||
|
|
("afternoon", "下午", 14 * 60 + 30, 18 * 60), # 14:30 - 18:00
|
|||
|
|
("evening", "晚上", 18 * 60, 21 * 60), # 18:00 - 21:00
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
WINDOW_SLUGS: tuple[str, ...] = tuple(item[0] for item in SCHEDULE_WINDOWS)
|
|||
|
|
WINDOW_NAMES: tuple[str, ...] = tuple(item[1] for item in SCHEDULE_WINDOWS)
|
|||
|
|
WINDOW_SLUG_BY_NAME: dict[str, str] = {item[1]: item[0] for item in SCHEDULE_WINDOWS}
|
|||
|
|
WINDOW_NAME_BY_SLUG: dict[str, str] = {item[0]: item[1] for item in SCHEDULE_WINDOWS}
|
|||
|
|
|
|||
|
|
# 记忆侧 validate_bot_personal_envelope 用它做**硬校验**:不在集合里 → invalid_window,
|
|||
|
|
# 归档静默失败。所以它必须由上表派生,不能手写。
|
|||
|
|
BOT_PERSONAL_WINDOWS = frozenset(WINDOW_SLUGS)
|
|||
|
|
|
|||
|
|
# LLM 与用户口语里的窗口别名 → slug。只做输入归一,不参与判定。
|
|||
|
|
WINDOW_ALIASES: dict[str, str] = {
|
|||
|
|
"深夜": "late_night", "凌晨": "late_night", "半夜": "late_night", "夜里": "late_night",
|
|||
|
|
"早晨": "morning", "早上": "morning", "清晨": "morning", "上午": "morning",
|
|||
|
|
"中午": "noon", "正午": "noon", "午间": "noon", "晌午": "noon",
|
|||
|
|
"下午": "afternoon",
|
|||
|
|
"晚上": "evening", "傍晚": "evening", "晚间": "evening",
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
# 旧四段(OPS 22/06/12/18)→ 新五段的迁移映射。
|
|||
|
|
# 值为 None 表示「靠窗口名判不出来,必须看时间戳」,见 migrate_legacy_window()。
|
|||
|
|
LEGACY_WINDOW_MIGRATION: dict[str, str | None] = {
|
|||
|
|
"late_night": "late_night", # 旧 22:00-06:00 ⊂ 新 21:00-06:00,可直接沿用
|
|||
|
|
"morning": None, # 旧 06:00-12:00 → 新 morning(06-11) + noon(11-12)
|
|||
|
|
"afternoon": None, # 旧 12:00-18:00 → 新 noon(12-14:30) + afternoon(14:30-18)
|
|||
|
|
"evening": None, # 旧 18:00-22:00 → 新 evening(18-21) + late_night(21-22)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
def window_for_minutes(minutes: int) -> str:
|
|||
|
|
"""把「当日分钟数」归入窗口 slug。跨午夜的窗口拆成两截判定。
|
|||
|
|
|
|||
|
|
这是**唯一判定实现**。带日期的判定(跨午夜时 window_date 归属哪一天)留在
|
|||
|
|
陪伴侧 agenda_contracts.window_for_datetime,但它必须调用本函数取窗口名,
|
|||
|
|
不允许自己再判一次阈值。
|
|||
|
|
"""
|
|||
|
|
try:
|
|||
|
|
value = int(minutes) % (24 * 60)
|
|||
|
|
except (TypeError, ValueError):
|
|||
|
|
return ""
|
|||
|
|
for slug, _name, start, end in SCHEDULE_WINDOWS:
|
|||
|
|
if start < end:
|
|||
|
|
if start <= value < end:
|
|||
|
|
return slug
|
|||
|
|
elif value >= start or value < end:
|
|||
|
|
return slug
|
|||
|
|
return ""
|
|||
|
|
|
|||
|
|
|
|||
|
|
def normalize_window(value: object) -> str:
|
|||
|
|
"""把窗口名/别名/slug 归一成 slug;无法识别返回空串(**不要猜**)。"""
|
|||
|
|
text = str(value or "").strip()
|
|||
|
|
if not text:
|
|||
|
|
return ""
|
|||
|
|
lowered = text.lower()
|
|||
|
|
if lowered in BOT_PERSONAL_WINDOWS:
|
|||
|
|
return lowered
|
|||
|
|
return WINDOW_ALIASES.get(text, "")
|
|||
|
|
|
|||
|
|
|
|||
|
|
def migrate_legacy_window(old_window: object, minutes: object = None) -> str:
|
|||
|
|
"""旧四段窗口值 → 新五段 slug。
|
|||
|
|
|
|||
|
|
拿得到当日分钟数就按时间重算;拿不到且旧值本身不唯一对应新值时返回空串,
|
|||
|
|
调用方应当**按旧名保留、只读不重算**,不要猜——猜错会让历史快照的窗口归属
|
|||
|
|
和它内部的时间戳自相矛盾。
|
|||
|
|
"""
|
|||
|
|
old = normalize_window(old_window) or str(old_window or "").strip().lower()
|
|||
|
|
if minutes is not None:
|
|||
|
|
recomputed = window_for_minutes(minutes)
|
|||
|
|
if recomputed:
|
|||
|
|
return recomputed
|
|||
|
|
return LEGACY_WINDOW_MIGRATION.get(old) or ""
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 二、Bot 个人归档域
|
|||
|
|
#
|
|||
|
|
# memory_domain 保持 OPS 时期的取值 "bot_self_schedule":它描述的是「Bot 自有
|
|||
|
|
# 日程域」,不含运维语义,改名要同步两侧 7 处 + 存量数据迁移,收益为零。
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
BOT_PERSONAL_MEMORY_DOMAIN = "bot_self_schedule"
|
|||
|
|
BOT_PERSONAL_SUBJECT = "bot_self"
|
|||
|
|
BOT_PERSONAL_SESSION_ID = "bot_personal"
|
|||
|
|
BOT_PERSONAL_SCOPE = "private"
|
|||
|
|
BOT_PERSONAL_VISIBILITY = "bot_self"
|
|||
|
|
BOT_PERSONAL_MAX_PAYLOAD_BYTES = 16 * 1024
|
|||
|
|
|
|||
|
|
# payload 结构本身未变 → 保持 1.0。
|
|||
|
|
BOT_PERSONAL_PAYLOAD_SCHEMA_VERSION = "1.0"
|
|||
|
|
# 信封字段 window 的**值域**变了(四段→五段)→ 能力版本必升,且必须在能力探测里
|
|||
|
|
# 回传 windows,让调用方启动时就能发现两侧值域不一致,而不是等到归档 invalid_window。
|
|||
|
|
BOT_PERSONAL_CAPABILITY_SCHEMA_VERSION = "1.1"
|
|||
|
|
|
|||
|
|
BOT_PERSONAL_MEMORY_TYPES: tuple[str, ...] = (
|
|||
|
|
"bot_schedule_plan",
|
|||
|
|
"bot_observed_activity",
|
|||
|
|
"bot_schedule_reconciliation",
|
|||
|
|
"bot_window_snapshot",
|
|||
|
|
"bot_daily_diary",
|
|||
|
|
"bot_creative_work",
|
|||
|
|
"bot_media_memory",
|
|||
|
|
"bot_subjective_memory",
|
|||
|
|
"bot_shared_activity",
|
|||
|
|
"bot_detail_fragment",
|
|||
|
|
"bot_calendar_event",
|
|||
|
|
"bot_proactive_message",
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# memory_type → (source_kind, 默认 evidence_level, 默认 status)。
|
|||
|
|
# 记忆侧一律用合同 source_kind 覆盖调用方上报值,所以两侧必须同表,
|
|||
|
|
# 否则创作/梦境/日历会被标成「真实观察」。
|
|||
|
|
TYPE_CONTRACTS: dict[str, tuple[str, str, str]] = {
|
|||
|
|
"bot_schedule_plan": ("planned", "L0", "planned"),
|
|||
|
|
"bot_observed_activity": ("observed", "L2", "active"),
|
|||
|
|
"bot_schedule_reconciliation": ("reconciled", "L3", "completed"),
|
|||
|
|
"bot_window_snapshot": ("projection", "L2", "completed"),
|
|||
|
|
"bot_daily_diary": ("subjective", "L1", "completed"),
|
|||
|
|
"bot_creative_work": ("creative", "L1", "active"),
|
|||
|
|
"bot_media_memory": ("media", "L1", "active"),
|
|||
|
|
"bot_subjective_memory": ("subjective", "L1", "active"),
|
|||
|
|
"bot_shared_activity": ("shared", "L1", "active"),
|
|||
|
|
"bot_detail_fragment": ("detail", "L1", "active"),
|
|||
|
|
"bot_calendar_event": ("calendar", "L1", "active"),
|
|||
|
|
"bot_proactive_message": ("proactive", "L1", "active"),
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
EVIDENCE_LEVELS: tuple[str, ...] = ("L0", "L1", "L2", "L3")
|
|||
|
|
|
|||
|
|
# 幂等键前缀表。归档链路每条写入都要落在这些前缀之一下,方便对账与去重排查。
|
|||
|
|
# ⚠️ agenda_snapshot / reconciliation 两类的 id 内部含窗口 slug,改分级后新旧 key
|
|||
|
|
# 不同源:**旧 key 不重写,新记录用新 slug**(见迁移策略)。
|
|||
|
|
IDEMPOTENCY_KEY_PREFIXES: tuple[str, ...] = (
|
|||
|
|
"agenda_snapshot", # agenda_snapshot:{snapshot_id} 含窗口 slug
|
|||
|
|
"reconciliation", # reconciliation:{reconciliation_id} 含窗口 slug
|
|||
|
|
"observed", # observed:{activity_id}
|
|||
|
|
"daily_plan", # daily_plan:{date}
|
|||
|
|
"detail", # detail:{date}:{start}:{end}
|
|||
|
|
"diary", # diary:{date}
|
|||
|
|
"calendar", # calendar:{event_id}:{action}
|
|||
|
|
"proactive", # proactive:{user_id}:{action}:{content[:80]}
|
|||
|
|
"creative", # creative:{project_id|title}:{chunks}
|
|||
|
|
"photo", # photo:{media_id}
|
|||
|
|
"daily_outfit", # daily_outfit:{date}
|
|||
|
|
"dream", # dream:{text[:120]}:{mood}
|
|||
|
|
"qzone", # qzone:{tid|content[:100]} ← 娱乐能力,陪伴分支保留
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
|
|||
|
|
def capability_descriptor(*, available: bool = True, read_only: bool = False) -> dict[str, object]:
|
|||
|
|
"""记忆侧 probe_bot_personal_memory_capabilities 的标准返回骨架。
|
|||
|
|
|
|||
|
|
windows / memory_types / contract_fingerprint 三个字段是给陪伴侧做启动自检用的:
|
|||
|
|
对不上就说明两侧合同文件漂移了,应当直接告警并停用归档,而不是带着不一致跑。
|
|||
|
|
"""
|
|||
|
|
return {
|
|||
|
|
"available": bool(available),
|
|||
|
|
"read_only": bool(read_only),
|
|||
|
|
"memory_domain": BOT_PERSONAL_MEMORY_DOMAIN,
|
|||
|
|
"contract_name": CONTRACT_NAME,
|
|||
|
|
"contract_revision": CONTRACT_REVISION,
|
|||
|
|
"contract_fingerprint": CONTRACT_FINGERPRINT,
|
|||
|
|
"capability_schema_version": BOT_PERSONAL_CAPABILITY_SCHEMA_VERSION,
|
|||
|
|
"payload_schema_version": BOT_PERSONAL_PAYLOAD_SCHEMA_VERSION,
|
|||
|
|
"windows": list(WINDOW_SLUGS),
|
|||
|
|
"memory_types": list(BOT_PERSONAL_MEMORY_TYPES),
|
|||
|
|
"max_payload_bytes": BOT_PERSONAL_MAX_PAYLOAD_BYTES,
|
|||
|
|
"warnings": [],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
def _fingerprint_source() -> str:
|
|||
|
|
"""参与指纹的只有**跨插件必须一致**的值。注释、别名表、辅助函数不参与——
|
|||
|
|
别名只影响本地输入归一,两侧不一致不会造成数据不一致。"""
|
|||
|
|
canonical = {
|
|||
|
|
"contract_name": CONTRACT_NAME,
|
|||
|
|
"contract_revision": CONTRACT_REVISION,
|
|||
|
|
"windows": [[slug, name, start, end] for slug, name, start, end in SCHEDULE_WINDOWS],
|
|||
|
|
"memory_domain": BOT_PERSONAL_MEMORY_DOMAIN,
|
|||
|
|
"subject": BOT_PERSONAL_SUBJECT,
|
|||
|
|
"session_id": BOT_PERSONAL_SESSION_ID,
|
|||
|
|
"scope": BOT_PERSONAL_SCOPE,
|
|||
|
|
"visibility": BOT_PERSONAL_VISIBILITY,
|
|||
|
|
"max_payload_bytes": BOT_PERSONAL_MAX_PAYLOAD_BYTES,
|
|||
|
|
"payload_schema_version": BOT_PERSONAL_PAYLOAD_SCHEMA_VERSION,
|
|||
|
|
"capability_schema_version": BOT_PERSONAL_CAPABILITY_SCHEMA_VERSION,
|
|||
|
|
"memory_types": list(BOT_PERSONAL_MEMORY_TYPES),
|
|||
|
|
"type_contracts": {k: list(v) for k, v in TYPE_CONTRACTS.items()},
|
|||
|
|
"evidence_levels": list(EVIDENCE_LEVELS),
|
|||
|
|
"idempotency_key_prefixes": list(IDEMPOTENCY_KEY_PREFIXES),
|
|||
|
|
}
|
|||
|
|
return json.dumps(canonical, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
|
|||
|
|
|
|||
|
|
|
|||
|
|
def compute_contract_fingerprint() -> str:
|
|||
|
|
return hashlib.sha256(_fingerprint_source().encode("utf-8")).hexdigest()[:16]
|
|||
|
|
|
|||
|
|
|
|||
|
|
# 由 compute_contract_fingerprint() 生成。改了上面任何常量都要重跑本文件更新它。
|
|||
|
|
CONTRACT_FINGERPRINT = "5b8a97c1527dcc62"
|
|||
|
|
|
|||
|
|
|
|||
|
|
def contract_self_check() -> list[str]:
|
|||
|
|
"""两侧启动时各自跑一遍,再互相比对 CONTRACT_FINGERPRINT。"""
|
|||
|
|
problems: list[str] = []
|
|||
|
|
if CONTRACT_FINGERPRINT != compute_contract_fingerprint():
|
|||
|
|
problems.append("contract_fingerprint_stale: 常量改过但没重算指纹")
|
|||
|
|
if len(set(WINDOW_SLUGS)) != len(WINDOW_SLUGS):
|
|||
|
|
problems.append("duplicate_window_slug")
|
|||
|
|
if set(TYPE_CONTRACTS) != set(BOT_PERSONAL_MEMORY_TYPES):
|
|||
|
|
problems.append("type_contracts_out_of_sync")
|
|||
|
|
covered = {window_for_minutes(m) for m in range(0, 24 * 60)}
|
|||
|
|
if covered != set(WINDOW_SLUGS):
|
|||
|
|
problems.append(f"window_coverage_gap: 未覆盖或多余 {covered ^ set(WINDOW_SLUGS)}")
|
|||
|
|
for alias, slug in WINDOW_ALIASES.items():
|
|||
|
|
if slug not in BOT_PERSONAL_WINDOWS:
|
|||
|
|
problems.append(f"alias_points_to_unknown_window: {alias}->{slug}")
|
|||
|
|
return problems
|
|||
|
|
|
|||
|
|
|
|||
|
|
if __name__ == "__main__": # pragma: no cover
|
|||
|
|
print("CONTRACT_FINGERPRINT =", compute_contract_fingerprint())
|
|||
|
|
issues = contract_self_check()
|
|||
|
|
print("self_check:", "OK" if not issues else issues)
|