feat: freeze ops backend page contracts
这个提交存在于:
父节点
7b68b0625c
当前提交
cd9d554e0a
共有 4 个文件被更改,包括 424 次插入 和 0 次删除
95
docs/Q7后端接口收口与VM验收记录.md
普通文件
95
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 自有数据删除操作。
|
||||
73
page_api.py
73
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,
|
||||
}
|
||||
|
|
|
|||
165
q7_backend_contracts.py
普通文件
165
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 日程、人格、创作、梦境和自我时间线只保存在陪伴插件自有空间。",
|
||||
}
|
||||
|
|
@ -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()
|
||||
正在加载…
添加表格
在新工单中引用