dsh-plugin-xujie-memory 0.5.0 → 0.7.0

package/python/xujie_memory/server.py

@@ -53,6 +53,7 @@ from . import __version__
 from .encoder import RuleEncoder
 from .engine import Engine, SpecRegistry
 from .memory import Memory
+from .management import Management, ManagementError
 from .orchestrator import Orchestrator, TurnBudget
 from .profile import ProfileStore
 
@@ -95,6 +96,8 @@ class MemoryService:
         self.db_path = str(db_path)
         self.engine = Engine(Path(db_path), SpecRegistry.from_dir(Path(specs_dir)))
         self.profiles = ProfileStore(self.engine)
+        from .privacy import repair_legacy
+        repair_legacy(self.engine, self.profiles)
         self.orchestrator = Orchestrator(
             self.engine,
             profiles=self.profiles,
@@ -106,6 +109,9 @@ class MemoryService:
         # `INSERT OR IGNORE` 兜住了，这里只是避免无谓的重复计算。
         self._scopes: dict[str, str] = {}
         self._lock = threading.Lock()
+        # Serialize HTTP writes with reads of dependent projections. In
+        # particular, a /turn cannot republish a half-edited graph.
+        self.request_lock = threading.RLock()
 
     # ------------------------------------------------------------ scope
     def scope_of(self, session: str, user: str = "user") -> str:
@@ -212,6 +218,19 @@ class MemoryService:
         return {"ok": True, "session": session,
                 "points": Memory(self.engine).curve(scope, trace_id, points)}
 
+    def memory_forget(self, session: str, trace_id: str, *,
+                      user: str = "user") -> dict[str, Any]:
+        """删一条记忆。主 AI 主动删时用；用户说"忘掉这条"也走这里。"""
+        scope = self.scope_of(session, user)
+        return {"ok": True, "session": session,
+                **Memory(self.engine).forget(scope, trace_id)}
+
+    def memory_stats(self, session: str, *, user: str = "user") -> dict[str, Any]:
+        """库里有多少条记忆、多少条被删过、多少条锚住——透明化用。"""
+        scope = self.scope_of(session, user)
+        return {"ok": True, "session": session,
+                **Memory(self.engine).stats(scope)}
+
     def close(self) -> None:
         self.engine.close()
 
@@ -329,7 +348,12 @@ class _Handler(BaseHTTPRequestHandler):
             self._json(400, {"ok": False, "error": f"bad_json: {exc}"})
             return
 
+        self.service.request_lock.acquire()
         try:
+            if route.startswith("/manage/"):
+                payload = self._manage(route, body)
+                self._json(200, payload)
+                return
             session = _str_field(body, "session")
             if not session:
                 self._json(400, {"ok": False, "error": "missing_session"})
@@ -366,6 +390,24 @@ class _Handler(BaseHTTPRequestHandler):
                     user=user,
                     limit=int(_num_field(body, "limit", 5, 1, 50)),
                 )
+            elif route == "/memory/stats":
+                payload = self.service.memory_stats(session, user=user)
+            elif route == "/memory/forget":
+                trace_id = _str_field(body, "trace_id")
+                if not trace_id:
+                    raise BadRequest("missing_trace_id")
+                try:
+                    payload = self.service.memory_forget(session, trace_id, user=user)
+                except ValueError as exc:
+                    # 库里没有这条 / 不属于这个 scope：调用方参数问题，不是服务端崩了。
+                    raise BadRequest(str(exc)) from exc
+            elif route == "/memory/edit":
+                payload = Management(self.service).edit(
+                    self.service.scope_of(session, user),
+                    _str_field(body, "trace_id"),
+                    _str_field(body, "content", limit=MAX_TEXT_CHARS),
+                    _str_field(body, "expected_hash"),
+                )
             elif route in ("/memory/mark", "/memory/unmark", "/memory/curve"):
                 trace_id = _str_field(body, "trace_id")
                 if not trace_id:
@@ -386,6 +428,12 @@ class _Handler(BaseHTTPRequestHandler):
             else:
                 self._json(404, {"ok": False, "error": "not_found"})
                 return
+        except ManagementError as exc:
+            status = 409 if exc.code == "version_conflict" else (
+                404 if exc.code.endswith("_not_found") else 400
+            )
+            self._json(status, {"ok": False, "error": exc.code})
+            return
         except BadRequest as exc:
             self._json(400, {"ok": False, "error": "bad_request", "detail": str(exc)})
             return
@@ -398,9 +446,37 @@ class _Handler(BaseHTTPRequestHandler):
             self._json(500, {"ok": False, "error": type(exc).__name__,
                              "detail": str(exc)[:300]})
             return
+        finally:
+            self.service.request_lock.release()
 
         self._json(200, payload)
 
+    def _manage(self, route: str, body: dict[str, Any]) -> dict[str, Any]:
+        manager = Management(self.service)
+        if route == "/manage/catalog":
+            return manager.catalog()
+        scope = _str_field(body, "scope_id")
+        if not scope:
+            raise BadRequest("missing_scope_id")
+        if route == "/manage/snapshot":
+            return manager.snapshot(scope, int(_num_field(body, "limit", 250, 1, 500)))
+        if route == "/manage/search":
+            return manager.search(
+                scope, _str_field(body, "query", limit=MAX_TEXT_CHARS),
+                int(_num_field(body, "limit", 30, 1, 50)),
+            )
+        trace = _str_field(body, "trace_id")
+        if route == "/manage/detail":
+            return manager.detail(scope, trace)
+        expected = _str_field(body, "expected_hash")
+        if route == "/manage/edit":
+            return manager.edit(
+                scope, trace, _str_field(body, "content", limit=MAX_TEXT_CHARS), expected
+            )
+        if route == "/manage/forget":
+            return manager.forget(scope, trace, expected)
+        raise ManagementError("route_not_found")
+
     # ---------------------------------------------------------- 工具
     def _read_json(self) -> dict[str, Any]:
         try:

package/python/xujie_memory/specs.py

@@ -1,170 +1,170 @@
-"""关系规格（RelationSpec）。
-
-设计文档 7.1 的理由：哪些关系可自动接受、负值是否允许、谁能写，
-不能由模型临时决定，也不应散落在代码里。每种关系用一份版本化规格声明，
-内核只执行规格，不自行推断。
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-from .errors import SpecNotFound
-
-RISK_TIERS = ("R0", "R1", "R2", "R3")
-ADMISSION_MODES = ("shadow", "assisted", "auto")
-EFFECT_KINDS = ("set", "delta", "invalidate")
-MODALITIES = (
-    "asserted",
-    # 请求 / 祈使。「给我免三碗」不是在陈述事实，也不是假设——
-    # 说话人是真的在要求这件事。缺了这一格，它会被判成 hypothetical
-    # 然后 record_only，用户明确要求的事反而不记（实测踩到）。
-    "request",
-    "hypothetical",
-    "conditional",
-    "quoted",
-    "denied",
-    "planned",
-    "joking",
-    "ironic",
-    "in_world",
-    "unclear",
-)
-
-
-@dataclass(frozen=True)
-class RelationSpec:
-    relation: str
-    version: str
-    risk_tier: str
-    required_slots: tuple[str, ...]
-    allowed_modalities: tuple[str, ...]
-    writers: tuple[str, ...]
-    effect_kind: str
-    admission_mode: str = "shadow"
-    value_type: str = "integer"          # integer / number / string / enum
-    # XM-12: unit 只用于展示，不参与 state_key，也不参与校验。
-    #        编码器给出与规格不符的单位时不会报错——这是有意的取舍，见 ISSUES。
-    #        真要校验，应判 disputed 而不是拒绝（拒绝会丢掉证据）。
-    unit: str | None = None
-    allow_negative: bool = False
-    enum_values: tuple[str, ...] = ()
-    confirmation: str = "none"           # none / implicit / explicit / authority
-    validity: str = "permanent"          # permanent / ttl / reconfirm
-    ttl_seconds: int | None = None
-    conflict_policy: str = "dispute"     # dispute / reject / last_write_wins
-    conservation: str | None = None      # None / "repayment"：追踪累计偿付量
-    feeds: tuple[str, ...] = ()
-    derived_from: tuple[str, ...] = ()
-    note: str = ""
-
-    # ------------------------------------------------------------- 自检
-    def validate(self) -> None:
-        if self.risk_tier not in RISK_TIERS:
-            raise ValueError(f"{self.relation}: bad risk_tier {self.risk_tier!r}")
-        if self.admission_mode not in ADMISSION_MODES:
-            raise ValueError(f"{self.relation}: bad admission_mode {self.admission_mode!r}")
-        if self.effect_kind not in EFFECT_KINDS:
-            raise ValueError(f"{self.relation}: bad effect_kind {self.effect_kind!r}")
-        for m in self.allowed_modalities:
-            if m not in MODALITIES:
-                raise ValueError(f"{self.relation}: unknown modality {m!r}")
-        if not self.required_slots:
-            raise ValueError(f"{self.relation}: required_slots must not be empty")
-        # R3 永远不允许自动提交（设计文档 7.3 / 15.5）
-        if self.risk_tier == "R3" and self.admission_mode == "auto":
-            raise ValueError(
-                f"{self.relation}: R3 relation must not be 'auto' "
-                "(permissions/deletion go through the control channel only)"
-            )
-        if self.value_type == "enum" and not self.enum_values:
-            raise ValueError(f"{self.relation}: enum value_type requires enum_values")
-        if self.conservation not in (None, "repayment"):
-            raise ValueError(f"{self.relation}: unknown conservation {self.conservation!r}")
-
-    @property
-    def spec_version(self) -> str:
-        return f"{self.relation}@{self.version}"
-
-
-@dataclass
-class SpecRegistry:
-    _by_relation: dict[str, RelationSpec] = field(default_factory=dict)
-
-    # ------------------------------------------------------------- 加载
-    @classmethod
-    def from_dir(cls, path: str | Path) -> "SpecRegistry":
-        reg = cls()
-        for f in sorted(Path(path).glob("*.json")):
-            reg.add(RelationSpec(**json.loads(f.read_text(encoding="utf-8"))))
-        return reg
-
-    @classmethod
-    def from_specs(cls, specs: list[RelationSpec]) -> "SpecRegistry":
-        reg = cls()
-        for s in specs:
-            reg.add(s)
-        return reg
-
-    def add(self, spec: RelationSpec) -> None:
-        spec.validate()
-        if spec.relation in self._by_relation:
-            raise ValueError(f"duplicate relation spec: {spec.relation}")
-        self._by_relation[spec.relation] = spec
-
-    # ------------------------------------------------------------- 查询
-    def get(self, relation: str) -> RelationSpec:
-        try:
-            return self._by_relation[relation]
-        except KeyError:
-            raise SpecNotFound(f"no spec registered for relation {relation!r}") from None
-
-    def all(self) -> list[RelationSpec]:
-        return list(self._by_relation.values())
-
-    # ------------------------------------------------------------- 依赖图
-    def dependency_edges(self) -> list[tuple[str, str]]:
-        """返回 (input_relation, derived_relation) 边列表，用于环检测。"""
-        edges: list[tuple[str, str]] = []
-        for spec in self._by_relation.values():
-            for src in spec.derived_from:
-                edges.append((src, spec.relation))
-        return edges
-
-    def assert_acyclic(self) -> None:
-        """依赖图必须为 DAG（设计文档 9.5）。"""
-        from .errors import DependencyCycle
-
-        graph: dict[str, set[str]] = {}
-        for src, dst in self.dependency_edges():
-            graph.setdefault(src, set()).add(dst)
-
-        WHITE, GREY, BLACK = 0, 1, 2
-        color: dict[str, int] = {}
-
-        def visit(node: str, stack: list[str]) -> None:
-            color[node] = GREY
-            stack.append(node)
-            for nxt in graph.get(node, ()):
-                c = color.get(nxt, WHITE)
-                if c == GREY:
-                    cycle = " -> ".join(stack[stack.index(nxt):] + [nxt])
-                    raise DependencyCycle(f"dependency cycle: {cycle}")
-                if c == WHITE:
-                    visit(nxt, stack)
-            stack.pop()
-            color[node] = BLACK
-
-        for node in list(graph):
-            if color.get(node, WHITE) == WHITE:
-                visit(node, [])
-
-
-def slot_value(spec: RelationSpec, slots: dict[str, Any], name: str) -> Any:
-    """取槽位；缺失时抛错，不做默认值填充（I5）。"""
-    if name not in slots:
-        raise KeyError(f"missing required slot {name!r} for relation {spec.relation!r}")
-    return slots[name]
+"""关系规格（RelationSpec）。
+
+设计文档 7.1 的理由：哪些关系可自动接受、负值是否允许、谁能写，
+不能由模型临时决定，也不应散落在代码里。每种关系用一份版本化规格声明，
+内核只执行规格，不自行推断。
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import SpecNotFound
+
+RISK_TIERS = ("R0", "R1", "R2", "R3")
+ADMISSION_MODES = ("shadow", "assisted", "auto")
+EFFECT_KINDS = ("set", "delta", "invalidate")
+MODALITIES = (
+    "asserted",
+    # 请求 / 祈使。「给我免三碗」不是在陈述事实，也不是假设——
+    # 说话人是真的在要求这件事。缺了这一格，它会被判成 hypothetical
+    # 然后 record_only，用户明确要求的事反而不记（实测踩到）。
+    "request",
+    "hypothetical",
+    "conditional",
+    "quoted",
+    "denied",
+    "planned",
+    "joking",
+    "ironic",
+    "in_world",
+    "unclear",
+)
+
+
+@dataclass(frozen=True)
+class RelationSpec:
+    relation: str
+    version: str
+    risk_tier: str
+    required_slots: tuple[str, ...]
+    allowed_modalities: tuple[str, ...]
+    writers: tuple[str, ...]
+    effect_kind: str
+    admission_mode: str = "shadow"
+    value_type: str = "integer"          # integer / number / string / enum
+    # XM-12: unit 只用于展示，不参与 state_key，也不参与校验。
+    #        编码器给出与规格不符的单位时不会报错——这是有意的取舍，见 ISSUES。
+    #        真要校验，应判 disputed 而不是拒绝（拒绝会丢掉证据）。
+    unit: str | None = None
+    allow_negative: bool = False
+    enum_values: tuple[str, ...] = ()
+    confirmation: str = "none"           # none / implicit / explicit / authority
+    validity: str = "permanent"          # permanent / ttl / reconfirm
+    ttl_seconds: int | None = None
+    conflict_policy: str = "dispute"     # dispute / reject / last_write_wins
+    conservation: str | None = None      # None / "repayment"：追踪累计偿付量
+    feeds: tuple[str, ...] = ()
+    derived_from: tuple[str, ...] = ()
+    note: str = ""
+
+    # ------------------------------------------------------------- 自检
+    def validate(self) -> None:
+        if self.risk_tier not in RISK_TIERS:
+            raise ValueError(f"{self.relation}: bad risk_tier {self.risk_tier!r}")
+        if self.admission_mode not in ADMISSION_MODES:
+            raise ValueError(f"{self.relation}: bad admission_mode {self.admission_mode!r}")
+        if self.effect_kind not in EFFECT_KINDS:
+            raise ValueError(f"{self.relation}: bad effect_kind {self.effect_kind!r}")
+        for m in self.allowed_modalities:
+            if m not in MODALITIES:
+                raise ValueError(f"{self.relation}: unknown modality {m!r}")
+        if not self.required_slots:
+            raise ValueError(f"{self.relation}: required_slots must not be empty")
+        # R3 永远不允许自动提交（设计文档 7.3 / 15.5）
+        if self.risk_tier == "R3" and self.admission_mode == "auto":
+            raise ValueError(
+                f"{self.relation}: R3 relation must not be 'auto' "
+                "(permissions/deletion go through the control channel only)"
+            )
+        if self.value_type == "enum" and not self.enum_values:
+            raise ValueError(f"{self.relation}: enum value_type requires enum_values")
+        if self.conservation not in (None, "repayment"):
+            raise ValueError(f"{self.relation}: unknown conservation {self.conservation!r}")
+
+    @property
+    def spec_version(self) -> str:
+        return f"{self.relation}@{self.version}"
+
+
+@dataclass
+class SpecRegistry:
+    _by_relation: dict[str, RelationSpec] = field(default_factory=dict)
+
+    # ------------------------------------------------------------- 加载
+    @classmethod
+    def from_dir(cls, path: str | Path) -> "SpecRegistry":
+        reg = cls()
+        for f in sorted(Path(path).glob("*.json")):
+            reg.add(RelationSpec(**json.loads(f.read_text(encoding="utf-8"))))
+        return reg
+
+    @classmethod
+    def from_specs(cls, specs: list[RelationSpec]) -> "SpecRegistry":
+        reg = cls()
+        for s in specs:
+            reg.add(s)
+        return reg
+
+    def add(self, spec: RelationSpec) -> None:
+        spec.validate()
+        if spec.relation in self._by_relation:
+            raise ValueError(f"duplicate relation spec: {spec.relation}")
+        self._by_relation[spec.relation] = spec
+
+    # ------------------------------------------------------------- 查询
+    def get(self, relation: str) -> RelationSpec:
+        try:
+            return self._by_relation[relation]
+        except KeyError:
+            raise SpecNotFound(f"no spec registered for relation {relation!r}") from None
+
+    def all(self) -> list[RelationSpec]:
+        return list(self._by_relation.values())
+
+    # ------------------------------------------------------------- 依赖图
+    def dependency_edges(self) -> list[tuple[str, str]]:
+        """返回 (input_relation, derived_relation) 边列表，用于环检测。"""
+        edges: list[tuple[str, str]] = []
+        for spec in self._by_relation.values():
+            for src in spec.derived_from:
+                edges.append((src, spec.relation))
+        return edges
+
+    def assert_acyclic(self) -> None:
+        """依赖图必须为 DAG（设计文档 9.5）。"""
+        from .errors import DependencyCycle
+
+        graph: dict[str, set[str]] = {}
+        for src, dst in self.dependency_edges():
+            graph.setdefault(src, set()).add(dst)
+
+        WHITE, GREY, BLACK = 0, 1, 2
+        color: dict[str, int] = {}
+
+        def visit(node: str, stack: list[str]) -> None:
+            color[node] = GREY
+            stack.append(node)
+            for nxt in graph.get(node, ()):
+                c = color.get(nxt, WHITE)
+                if c == GREY:
+                    cycle = " -> ".join(stack[stack.index(nxt):] + [nxt])
+                    raise DependencyCycle(f"dependency cycle: {cycle}")
+                if c == WHITE:
+                    visit(nxt, stack)
+            stack.pop()
+            color[node] = BLACK
+
+        for node in list(graph):
+            if color.get(node, WHITE) == WHITE:
+                visit(node, [])
+
+
+def slot_value(spec: RelationSpec, slots: dict[str, Any], name: str) -> Any:
+    """取槽位；缺失时抛错，不做默认值填充（I5）。"""
+    if name not in slots:
+        raise KeyError(f"missing required slot {name!r} for relation {spec.relation!r}")
+    return slots[name]