diff --git a/docs/Q7后端接口收口与VM验收记录.md b/docs/Q7后端接口收口与VM验收记录.md new file mode 100644 index 0000000..2f3c592 --- /dev/null +++ b/docs/Q7后端接口收口与VM验收记录.md @@ -0,0 +1,95 @@ +# Q7 后端接口收口与 VM 验收记录 + +## 目标 + +在不修改前端、不切换数据库的前提下,先把运维版陪伴插件的 Bot 自有存储、用户记忆边界和真实日程对账整理成稳定的只读后端契约,为后续前端统一改造准备接口。 + +## Q7 阶段结果 + +### Q7.0 数据边界复核 + +- Bot 日程、人格、创作、梦境、自我时间线和主动行为归入 `bot_self`。 +- 用户记忆继续通过独立记忆插件保存。 +- Bot 自有数据不作为用户记忆写入。 +- 旧数据迁移继续采用预览和非破坏性隔离。 + +### Q7.1 总览接口 + +`/overview` 新增: + +- `bot_self` +- `memory_boundary` +- `agenda_contract` + +这些字段只返回摘要、状态、数量、时间和迁移预览,不返回可直接修改底层存储的写入口。 + +### Q7.2 只读详情接口 + +新增页面接口: + +- `/bot-self/summary` +- `/bot-self/timeline` +- `/bot-self/agenda` +- `/bot-self/persona` +- `/memory-boundary/status` +- `/agenda/reconciliation` +- `/migration/bot-self/preview` + +实现文件: + +- `q7_backend_contracts.py` +- `page_api.py` + +### Q7.3 日程契约 + +日程接口分别返回: + +- 计划项; +- 实际活动; +- 时间窗口快照; +- 对账历史; +- 计划状态统计; +- 当前现实时间和本地时区; +- 计划、实际和 World 来源策略。 + +计划与实际不会被压成同一条无来源记录。 + +### Q7.4 测试 + +新增: + +- `tests/test_q7_backend_contracts.py` + +覆盖: + +- Bot 自有存储摘要和命名空间隔离; +- 旧数据迁移预览不修改原始计划; +- 计划、实际、对账历史分离; +- 用户记忆边界为 `user_only`; +- Bot 自有数据外写状态为关闭。 + +## 本地验收 + +- `python -m unittest discover -s tests -v`:32 项通过。 +- Python `compileall`:通过。 +- `git diff --check`:通过。 + +## Q7.5 VM 验收计划 + +提交并部署后需要在 VM 复核: + +1. AstrBot 服务保持 `active`,重启次数不增加。 +2. 运维陪伴插件正常加载。 +3. `/overview` 能返回三个新对象。 +4. Bot 自有摘要能读取 `bot_self_store`。 +5. 记忆边界接口返回用户数据专用策略。 +6. 日程对账接口能返回计划、实际和历史分区。 +7. 迁移预览返回 `preview_only`,不删除原数据。 +8. 记忆插件目录和数据库保持不变。 + +## 暂不包含 + +- 前端页面改造; +- 主存储切换 SQLite; +- World Server 接入; +- 任意 Bot 自有数据删除操作。 diff --git a/page_api.py b/page_api.py index 5bc67f6..f8eb1dd 100644 --- a/page_api.py +++ b/page_api.py @@ -37,6 +37,13 @@ from .memo_notes import ( memo_note_sort_key, normalize_memo_note, ) +from .q7_backend_contracts import ( + build_agenda_detail, + build_agenda_summary, + build_bot_self_detail, + build_bot_self_summary, + build_memory_boundary_summary, +) PAGE_API_PREFIX = f"/{PLUGIN_NAME}/page" @@ -181,6 +188,13 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio register = self.plugin.context.register_web_api routes = [ ("/overview", self.get_overview, ["GET"], "Private Companion Page overview"), + ("/bot-self/summary", self.get_bot_self_summary, ["GET"], "Private Companion Bot self storage summary"), + ("/bot-self/timeline", self.get_bot_self_timeline, ["GET"], "Private Companion Bot self timeline"), + ("/bot-self/agenda", self.get_bot_self_agenda, ["GET"], "Private Companion Bot self agenda history"), + ("/bot-self/persona", self.get_bot_self_persona, ["GET"], "Private Companion Bot persona state"), + ("/memory-boundary/status", self.get_memory_boundary_status, ["GET"], "Private Companion memory boundary status"), + ("/agenda/reconciliation", self.get_agenda_reconciliation, ["GET"], "Private Companion agenda reconciliation"), + ("/migration/bot-self/preview", self.get_bot_self_migration_preview, ["GET"], "Private Companion Bot self migration preview"), ("/expression-library", self.get_expression_library, ["GET"], "Private Companion Page expression library"), ("/expression-library/update", self.update_expression_library, ["POST"], "Private Companion Page update expression library"), ("/users", self.list_users, ["GET"], "Private Companion Page users"), @@ -287,6 +301,62 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio for path, handler, methods, desc in routes: register(f"{PAGE_API_PREFIX}{path}", handler, methods, desc) + async def get_bot_self_summary(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_bot_self_summary(self.plugin.data)) + except Exception as exc: + logger.error("[PrivateCompanionPage] Bot 自有存储摘要失败: %s", exc, exc_info=True) + return self._error(str(exc)) + + async def get_bot_self_timeline(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_bot_self_detail(self.plugin.data, "bot_self_timeline")) + except Exception as exc: + logger.error("[PrivateCompanionPage] Bot 自我时间线读取失败: %s", exc, exc_info=True) + return self._error(str(exc)) + + async def get_bot_self_agenda(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_bot_self_detail(self.plugin.data, "bot_agenda_history")) + except Exception as exc: + logger.error("[PrivateCompanionPage] Bot 日程历史读取失败: %s", exc, exc_info=True) + return self._error(str(exc)) + + async def get_bot_self_persona(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_bot_self_detail(self.plugin.data, "bot_persona_state")) + except Exception as exc: + logger.error("[PrivateCompanionPage] Bot 人格状态读取失败: %s", exc, exc_info=True) + return self._error(str(exc)) + + async def get_memory_boundary_status(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_memory_boundary_summary(self.plugin, self.plugin.data)) + except Exception as exc: + logger.error("[PrivateCompanionPage] 记忆边界状态读取失败: %s", exc, exc_info=True) + return self._error(str(exc)) + + async def get_agenda_reconciliation(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_agenda_detail(self.plugin.data)) + except Exception as exc: + logger.error("[PrivateCompanionPage] 日程对账读取失败: %s", exc, exc_info=True) + return self._error(str(exc)) + + async def get_bot_self_migration_preview(self) -> dict[str, Any]: + try: + async with self.plugin._data_lock: + return self._ok(build_bot_self_summary(self.plugin.data).get("migration", {})) + except Exception as exc: + logger.error("[PrivateCompanionPage] Bot 自有数据迁移预览失败: %s", exc, exc_info=True) + return self._error(str(exc)) + async def get_overview(self) -> dict[str, Any]: start = time.perf_counter() try: @@ -415,6 +485,9 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio "life_observation": self._life_observation_summary(data), "daily_state": self._daily_state_summary(data.get("daily_state")), "daily_timeline": self._daily_timeline_summary(data), + "bot_self": build_bot_self_summary(data), + "memory_boundary": build_memory_boundary_summary(self.plugin, data), + "agenda_contract": build_agenda_summary(data), "daily_outfit": self._daily_outfit_summary(data), "token_stats": token_stats, } diff --git a/q7_backend_contracts.py b/q7_backend_contracts.py new file mode 100644 index 0000000..967d697 --- /dev/null +++ b/q7_backend_contracts.py @@ -0,0 +1,165 @@ +# -*- coding: utf-8 -*- +"""Stable, read-only payloads for the operations companion page API.""" +from __future__ import annotations + +from copy import deepcopy +from datetime import datetime +from typing import Any + +try: + from .bot_self_store import BOT_SELF_LIST_NAMESPACES, build_bot_self_migration_preview, ensure_bot_self_store +except ImportError: + from bot_self_store import BOT_SELF_LIST_NAMESPACES, build_bot_self_migration_preview, ensure_bot_self_store + + +AGENDA_STATUS_KEYS = ( + "planned", + "active", + "completed", + "partially_completed", + "deferred", + "cancelled", + "overridden", + "unknown", +) + + +def _list_tail(value: Any, limit: int) -> list[Any]: + if not isinstance(value, list): + return [] + return [deepcopy(item) for item in value[-max(0, int(limit)) :] if isinstance(item, dict)] + + +def _iso_now() -> str: + return datetime.now().astimezone().isoformat(timespec="seconds") + + +def _latest_timestamp(items: list[dict[str, Any]], *keys: str) -> str: + values = [] + for item in items: + for key in keys: + value = str(item.get(key) or "").strip() + if value: + values.append(value) + break + return max(values) if values else "" + + +def build_bot_self_summary(data: dict[str, Any]) -> dict[str, Any]: + ensure_bot_self_store(data) + store = data.get("bot_self_store") if isinstance(data.get("bot_self_store"), dict) else {} + namespaces: dict[str, dict[str, Any]] = {} + all_records: list[dict[str, Any]] = [] + for namespace in (*BOT_SELF_LIST_NAMESPACES, "bot_persona_state"): + raw = store.get(namespace) + records = raw if isinstance(raw, list) else ([raw] if isinstance(raw, dict) and raw else []) + safe_records = [deepcopy(item) for item in records if isinstance(item, dict)] + all_records.extend(safe_records) + namespaces[namespace] = { + "count": len(safe_records), + "latest_at": _latest_timestamp(safe_records, "updated_at", "created_at", "occurred_at", "generated_at"), + } + return { + "version": int(store.get("version") or 1), + "storage_domain": "bot_self", + "owner": "bot", + "status": "ready", + "namespaces": namespaces, + "total_records": len(all_records), + "latest_at": _latest_timestamp(all_records, "updated_at", "created_at", "occurred_at", "generated_at"), + "migration": build_bot_self_migration_preview(data), + } + + +def build_bot_self_detail(data: dict[str, Any], namespace: str, *, limit: int = 50) -> dict[str, Any]: + ensure_bot_self_store(data) + store = data.get("bot_self_store") if isinstance(data.get("bot_self_store"), dict) else {} + allowed = set(BOT_SELF_LIST_NAMESPACES) | {"bot_persona_state"} + if namespace not in allowed: + raise ValueError("unsupported Bot self namespace") + raw = store.get(namespace) + records = raw if isinstance(raw, list) else ([raw] if isinstance(raw, dict) and raw else []) + return { + "namespace": namespace, + "owner": "bot", + "storage_domain": "bot_self", + "items": [deepcopy(item) for item in records[-max(1, min(int(limit), 200)) :] if isinstance(item, dict)], + } + + +def build_agenda_summary(data: dict[str, Any]) -> dict[str, Any]: + plan = data.get("daily_plan") if isinstance(data.get("daily_plan"), dict) else {} + plan_items = [item for item in plan.get("items", []) if isinstance(item, dict)] + observed = data.get("observed_activities") if isinstance(data.get("observed_activities"), list) else [] + history = data.get("agenda_reconciliation_history") if isinstance(data.get("agenda_reconciliation_history"), list) else [] + status_counts = {key: 0 for key in AGENDA_STATUS_KEYS} + for item in plan_items: + status = str(item.get("status") or item.get("lifecycle_status") or "planned").strip() + status_counts[status if status in status_counts else "unknown"] += 1 + return { + "plan_date": str(plan.get("date") or ""), + "plan_version": int(plan.get("version") or 1), + "plan_item_count": len(plan_items), + "observed_activity_count": len([item for item in observed if isinstance(item, dict)]), + "reconciliation_count": len([item for item in history if isinstance(item, dict)]), + "status_counts": status_counts, + "current_time": _iso_now(), + "timezone": datetime.now().astimezone().tzname() or "local", + "latest_reconciliation_at": _latest_timestamp( + [item for item in history if isinstance(item, dict)], + "reconciled_at", + "updated_at", + "generated_at", + ), + } + + +def build_agenda_detail(data: dict[str, Any], *, limit: int = 100) -> dict[str, Any]: + plan = data.get("daily_plan") if isinstance(data.get("daily_plan"), dict) else {} + plan_items = [deepcopy(item) for item in plan.get("items", []) if isinstance(item, dict)] + observed = _list_tail(data.get("observed_activities"), limit) + snapshots = _list_tail(data.get("window_snapshots"), limit) + history = _list_tail(data.get("agenda_reconciliation_history"), limit) + return { + "plan_date": str(plan.get("date") or ""), + "plan": plan_items[-max(1, min(int(limit), 200)) :], + "observed": observed, + "window_snapshots": snapshots, + "reconciliation_history": history, + "source_policy": { + "plan": "planned", + "observed": "real_or_projected_activity", + "world": "world_context_only_until_enabled", + }, + } + + +def build_memory_boundary_summary(plugin: Any, data: dict[str, Any]) -> dict[str, Any]: + bridge = None + bridge_status: dict[str, Any] = {} + getter = getattr(plugin, "_memory_companion_bridge", None) + if callable(getter): + try: + bridge = getter() + except Exception: + bridge = None + status_getter = getattr(plugin, "_memory_companion_coordination_status", None) + if callable(status_getter): + try: + value = status_getter() + if isinstance(value, dict): + bridge_status = deepcopy(value) + except Exception: + bridge_status = {} + runtime = data.get("runtime_settings") if isinstance(data.get("runtime_settings"), dict) else {} + return { + "policy": "user_only", + "status": "ready" if bridge is not None else "unavailable", + "bridge_available": bridge is not None, + "bridge_name": str(getattr(bridge, "display_name", "") or "") if bridge is not None else "", + "coordination": bridge_status, + "bot_self_external_write": False, + "bot_self_store_migrated": bool(runtime.get("bot_self_store_migrated", False)), + "checked_at": _iso_now(), + "boundary_note": "Bot 日程、人格、创作、梦境和自我时间线只保存在陪伴插件自有空间。", + } diff --git a/tests/test_q7_backend_contracts.py b/tests/test_q7_backend_contracts.py new file mode 100644 index 0000000..ce16b6e --- /dev/null +++ b/tests/test_q7_backend_contracts.py @@ -0,0 +1,91 @@ +import unittest + +from bot_self_store import record_bot_self_entry +from q7_backend_contracts import ( + build_agenda_detail, + build_agenda_summary, + build_bot_self_detail, + build_bot_self_summary, + build_memory_boundary_summary, +) + + +class DummyBridge: + display_name = "Memory Companion Ops" + + +class DummyPlugin: + def _memory_companion_bridge(self): + return DummyBridge() + + def _memory_companion_coordination_status(self): + return {"available": True, "search": True} + + +class Q7BackendContractTests(unittest.TestCase): + def test_bot_self_summary_isolated_and_migration_preview_is_read_only(self): + data = { + "daily_plan": {"items": [{"title": "旧计划"}]}, + "bot_self_store": { + "version": 1, + "bot_self_memory": [], + "bot_self_timeline": [], + "bot_agenda_history": [], + "bot_persona_state": {}, + "ops_activity_history": [], + "legacy_quarantine": [], + }, + } + record_bot_self_entry( + data, + "bot_self_timeline", + {"summary": "Bot 完成了一次复盘"}, + idempotency_key="timeline-1", + ) + before = dict(data) + summary = build_bot_self_summary(data) + detail = build_bot_self_detail(data, "bot_self_timeline") + self.assertEqual(summary["owner"], "bot") + self.assertEqual(summary["storage_domain"], "bot_self") + self.assertEqual(summary["namespaces"]["bot_self_timeline"]["count"], 1) + self.assertEqual(detail["items"][0]["storage_domain"], "bot_self") + self.assertEqual(summary["migration"]["status"], "preview_only") + self.assertEqual(data["daily_plan"], before["daily_plan"]) + + def test_agenda_contract_keeps_plan_observed_and_reconciliation_separate(self): + data = { + "daily_plan": { + "date": "2026-07-25", + "version": 2, + "items": [ + {"title": "写代码", "status": "completed"}, + {"title": "休息", "status": "deferred"}, + ], + }, + "observed_activities": [{"title": "写代码", "status": "completed"}], + "agenda_reconciliation_history": [{"reconciled_at": "2026-07-25T10:00:00+08:00"}], + "window_snapshots": [{"date": "2026-07-25", "window": "morning"}], + } + summary = build_agenda_summary(data) + detail = build_agenda_detail(data) + self.assertEqual(summary["plan_item_count"], 2) + self.assertEqual(summary["observed_activity_count"], 1) + self.assertEqual(summary["status_counts"]["completed"], 1) + self.assertEqual(summary["status_counts"]["deferred"], 1) + self.assertEqual(len(detail["plan"]), 2) + self.assertEqual(len(detail["observed"]), 1) + self.assertEqual(len(detail["reconciliation_history"]), 1) + + def test_memory_boundary_is_user_only_and_bot_external_write_is_disabled(self): + status = build_memory_boundary_summary( + DummyPlugin(), + {"runtime_settings": {"bot_self_store_migrated": True}}, + ) + self.assertEqual(status["policy"], "user_only") + self.assertTrue(status["bridge_available"]) + self.assertFalse(status["bot_self_external_write"]) + self.assertTrue(status["bot_self_store_migrated"]) + + +if __name__ == "__main__": + unittest.main()