feat: add read-only user fact bridge

这个提交存在于:
YokiiroBW 2026-07-26 02:14:15 +08:00
父节点 17d171a5c8
当前提交 753077469b
共有 5 个文件被更改,包括 185 次插入 和 4 次删除

查看文件

@ -1,4 +1,4 @@
from __future__ import annotations from __future__ import annotations
import re import re
from typing import Any from typing import Any
@ -7,6 +7,7 @@ from .models import MemoryRecord, clean_text
from .temporal_context import build_temporal_memory_meta from .temporal_context import build_temporal_memory_meta
ARCHIVE_API_VERSION = "1.0" ARCHIVE_API_VERSION = "1.0"
USER_FACT_QUERY_API_VERSION = "1.0"
SOURCE_NAME = "memory_companion" SOURCE_NAME = "memory_companion"
SOURCE_VERSION = "1.6.2-ops.2" SOURCE_VERSION = "1.6.2-ops.2"
@ -50,6 +51,23 @@ def archive_capabilities(*, available: bool = True, warnings: list[str] | None =
} }
def user_fact_query_capabilities(*, available: bool = True, warnings: list[str] | None = None) -> dict[str, Any]:
return {
"source_name": SOURCE_NAME,
"source_version": SOURCE_VERSION,
"api_version": USER_FACT_QUERY_API_VERSION,
"available": bool(available),
"read_only": True,
"memory_domain": "user_memory",
"accepted_scopes": ["private", "group"],
"supports_time_range": True,
"supports_temporal_metadata": True,
"memory_write_available": False,
"warnings": list(warnings or []),
}
def archive_payload(record: MemoryRecord, score: float | None = None, reason: str = "") -> dict[str, Any]: def archive_payload(record: MemoryRecord, score: float | None = None, reason: str = "") -> dict[str, Any]:
content, content_redacted = redact_text(record.content, 4000) content, content_redacted = redact_text(record.content, 4000)
evidence, evidence_redacted = redact_text(record.evidence, 520) evidence, evidence_redacted = redact_text(record.evidence, 520)
@ -73,6 +91,7 @@ def archive_payload(record: MemoryRecord, score: float | None = None, reason: st
"score": score, "score": score,
"topics": [clean_text(item, 80) for item in topics if clean_text(item, 80)][:8], "topics": [clean_text(item, 80) for item in topics if clean_text(item, 80)][:8],
"source_plugin": record.source_plugin or SOURCE_NAME, "source_plugin": record.source_plugin or SOURCE_NAME,
"memory_domain": record.memory_domain,
"redacted": content_redacted or evidence_redacted, "redacted": content_redacted or evidence_redacted,
} }
if score is None: if score is None:

查看文件

@ -1,10 +1,11 @@
from __future__ import annotations from __future__ import annotations
from datetime import datetime, timezone from datetime import datetime, timezone
from typing import Any from typing import Any
from zoneinfo import ZoneInfo from zoneinfo import ZoneInfo
from .models import EntityRef, MemoryRecord, SessionContext, clean_text from .models import EntityRef, MemoryRecord, SessionContext, clean_text
from .archive_contract import user_fact_query_capabilities
from .ops_domain import OpsDomainContract, normalize_ops_audit, normalize_ops_event, normalize_ops_task from .ops_domain import OpsDomainContract, normalize_ops_audit, normalize_ops_event, normalize_ops_task
from .temporal_context import build_reply_delay, build_temporal_memory_meta from .temporal_context import build_reply_delay, build_temporal_memory_meta
@ -302,6 +303,30 @@ class MemoryCompanionBridge:
def probe_archive_capabilities(self) -> dict[str, Any]: def probe_archive_capabilities(self) -> dict[str, Any]:
return self._plugin.bridge_probe_archive_capabilities() return self._plugin.bridge_probe_archive_capabilities()
def probe_user_fact_query_capabilities(self) -> dict[str, Any]:
getter = getattr(self._plugin, "bridge_probe_user_fact_query_capabilities", None)
if not callable(getter):
return user_fact_query_capabilities(available=False, warnings=["bridge_method_unavailable"])
return getter()
async def query_user_facts(
self,
query: str,
*,
scope: dict[str, Any],
limit: int = 10,
time_range: dict[str, str] | None = None,
) -> dict[str, Any]:
getter = getattr(self._plugin, "bridge_query_user_facts", None)
if not callable(getter):
return {
**user_fact_query_capabilities(available=False, warnings=["bridge_method_unavailable"]),
"query": clean_text(query, 1400),
"scope": dict(scope or {}),
"memories": [],
}
return await getter(query, scope=scope, limit=limit, time_range=time_range)
async def get_archive_scope(self, *, scope: dict[str, Any] | None = None) -> dict[str, Any]: async def get_archive_scope(self, *, scope: dict[str, Any] | None = None) -> dict[str, Any]:
return await self._plugin.bridge_get_archive_scope(scope=scope) return await self._plugin.bridge_get_archive_scope(scope=scope)

查看文件

@ -1,4 +1,4 @@
from __future__ import annotations from __future__ import annotations
import asyncio import asyncio
import time import time
@ -14,7 +14,12 @@ from pathlib import Path
from typing import Any from typing import Any
from zoneinfo import ZoneInfo from zoneinfo import ZoneInfo
from .archive_contract import ARCHIVE_API_VERSION, archive_capabilities, archive_payload from .archive_contract import (
ARCHIVE_API_VERSION,
archive_capabilities,
archive_payload,
user_fact_query_capabilities,
)
from .astrbot_compat import ( from .astrbot_compat import (
append_temp_text, append_temp_text,
clean_private_companion_history_text, clean_private_companion_history_text,
@ -864,6 +869,61 @@ class MemoryCompanionService:
def bridge_probe_archive_capabilities(self) -> dict[str, Any]: def bridge_probe_archive_capabilities(self) -> dict[str, Any]:
return archive_capabilities() return archive_capabilities()
def bridge_probe_user_fact_query_capabilities(self) -> dict[str, Any]:
return user_fact_query_capabilities()
async def bridge_query_user_facts(
self,
query: str,
*,
scope: dict[str, Any],
limit: int = 10,
time_range: dict[str, str] | None = None,
) -> dict[str, Any]:
payload = dict(scope or {})
requested_scope = clean_text(payload.get("scope"), 40).lower()
user_id = clean_text(payload.get("user_id"), 120)
group_id = clean_text(payload.get("group_id"), 120)
if requested_scope not in {"private", "group"}:
return {
**user_fact_query_capabilities(available=True, warnings=["invalid_scope"]),
"query": clean_text(query, 1400),
"scope": payload,
"memories": [],
}
if not user_id or (requested_scope == "group" and not group_id):
return {
**user_fact_query_capabilities(available=True, warnings=["missing_subject_scope"]),
"query": clean_text(query, 1400),
"scope": payload,
"memories": [],
}
payload["scope"] = requested_scope
payload["strict_session_only"] = bool(payload.get("strict_session_only", False))
result = await self.bridge_search_archive_memories(
query,
scope=payload,
limit=max(1, min(50, int(limit or 10))),
time_range=time_range,
include_timeline=False,
)
memories = [
item for item in result.get("memories", [])
if item.get("memory_domain") == "user_memory"
and item.get("visibility") not in {"bot_self", "internal"}
]
warnings = list(result.get("warnings", []))
if len(memories) != len(result.get("memories", [])):
warnings.append("non_user_memory_filtered")
return {
**user_fact_query_capabilities(available=True, warnings=warnings),
"query": clean_text(query, 1400),
"scope": result.get("scope", payload),
"memories": memories,
"excluded": result.get("excluded", []),
"warnings": warnings,
}
def _archive_context(self, scope: dict[str, Any] | None) -> SessionContext: def _archive_context(self, scope: dict[str, Any] | None) -> SessionContext:
payload = dict(scope or {}) payload = dict(scope or {})
payload["strict_session_only"] = bool(payload.get("strict_session_only", True)) payload["strict_session_only"] = bool(payload.get("strict_session_only", True))

查看文件

@ -125,3 +125,13 @@
- 修复或规避:部署后检查插件启动日志、数据目录、Archivist capability、服务重启次数,并用 AstrBot 实际 Python 做只读编译和合同 smoke test。 - 修复或规避:部署后检查插件启动日志、数据目录、Archivist capability、服务重启次数,并用 AstrBot 实际 Python 做只读编译和合同 smoke test。
- 预防规则:VM 验收必须同时满足服务 active、目标插件加载、Bridge/Archivist 可用、数据目录保留和无新增 traceback;pytest 不可用时必须明确标注而不是伪造通过。 - 预防规则:VM 验收必须同时满足服务 active、目标插件加载、Bridge/Archivist 可用、数据目录保留和无新增 traceback;pytest 不可用时必须明确标注而不是伪造通过。
- 验证证据:提交 `a8598e7`;插件 `1.6.2-ops.2` loaded;`available=True search=True`;`NRestarts=0`;`Q5_SMOKE_OK user_memory`;部署包 SHA-256 与 VM 一致。 - 验证证据:提交 `a8598e7`;插件 `1.6.2-ops.2` loaded;`available=True search=True`;`NRestarts=0`;`Q5_SMOKE_OK user_memory`;部署包 SHA-256 与 VM 一致。
## 2026-07-25 — Q6 只读用户事实查询 Bridge
- 阶段:Q6.0 记忆侧只读事实合同与边界过滤
- 类型:API契约 / 数据安全 / 测试
- 现象:现有通用归档 Bridge 能检索历史记忆,但调用方无法通过明确接口表达“只读用户事实”;跨域调用容易误用通用 search。
- 根因:归档 API 已有 scope 和可见性过滤,但缺少独立的用户事实能力声明、输入校验和结果域收口。
- 修复或规避:新增 `query_user_facts` 和能力探测;要求私聊用户 ID、群聊用户 ID 与群 ID;结果只接受明确的 `user_memory`,保留时间元数据;Bridge 缺失返回空结果和 warning。
- 预防规则:用户事实查询必须显式绑定 user/scope,禁止把缺失域、Bot 自有域、混合域或日历历史视为用户记忆;只读查询不得写库。
- 验证证据:`tests/test_q6_user_fact_bridge.py` 已补齐能力、降级、scope 和非用户域过滤测试;`compileall` 与模块导入检查通过;pytest 当前环境未安装,未虚报测试通过。

查看文件

@ -0,0 +1,67 @@
import asyncio
from core.archive_contract import user_fact_query_capabilities
from core.bridge import MemoryCompanionBridge
from core.service import MemoryCompanionService
class _MissingPlugin:
pass
def test_user_fact_query_capabilities_are_read_only_and_user_scoped():
payload = user_fact_query_capabilities()
assert payload["available"] is True
assert payload["read_only"] is True
assert payload["memory_domain"] == "user_memory"
assert payload["accepted_scopes"] == ["private", "group"]
def test_bridge_missing_user_fact_query_degrades_without_raising():
bridge = MemoryCompanionBridge(_MissingPlugin())
result = asyncio.run(
bridge.query_user_facts(
"用户偏好",
scope={"scope": "private", "user_id": "u1"},
)
)
assert result["available"] is False
assert result["memories"] == []
assert "bridge_method_unavailable" in result["warnings"]
def test_service_rejects_unscoped_user_fact_query_without_database_access():
service = object.__new__(MemoryCompanionService)
result = asyncio.run(
service.bridge_query_user_facts(
"用户偏好",
scope={"scope": "private"},
)
)
assert result["memories"] == []
assert "missing_subject_scope" in result["warnings"]
def test_service_filters_non_user_domains_from_user_fact_query():
service = object.__new__(MemoryCompanionService)
async def fake_archive_search(*args, **kwargs):
return {
"scope": kwargs["scope"],
"memories": [
{"id": "user-1", "memory_domain": "user_memory", "visibility": "private_pair"},
{"id": "bot-1", "memory_domain": "bot_self_legacy", "visibility": "bot_self"},
{"id": "mixed-1", "memory_domain": "shared_or_mixed", "visibility": "shareable"},
],
"excluded": [],
"warnings": [],
}
service.bridge_search_archive_memories = fake_archive_search
result = asyncio.run(
service.bridge_query_user_facts(
"用户偏好",
scope={"scope": "group", "user_id": "u1", "group_id": "g1"},
)
)
assert [item["id"] for item in result["memories"]] == ["user-1"]
assert "non_user_memory_filtered" in result["warnings"]