feat: release v1.0.0

2026-07-10 20:34:30 +00:00 · 2026-06-09 15:28:05 +08:00
parent bc1575a0da
commit 9b7dbdd7b2
83 changed files with 7737 additions and 335 deletions
@@ -63,6 +63,23 @@ print(core["content"])
 # L3: write core memory
 client.write_core("# User Profile\n...")

+# Offload v2: send tool pairs for server-side L1 async processing (fire-and-forget)
+client.offload_ingest(
+    session_id="agent_sess_123",
+    tool_pairs=[
+        {"tool_name": "search", "tool_call_id": "call_1", "params": {"q": "..."}, "result": "...", "timestamp": "..."},
+    ],
+)
+
+# Offload v2: server-side context compaction (sync wait for result)
+compacted = client.offload_compact(
+    session_id="agent_sess_123",
+    messages=[...],
+    ratio=0.7,
+    context_window=128000,
+)
+print(compacted["messages"], compacted["report"])
+
 # Read memory pipeline artifacts (e.g. persona.md, scene_blocks/*.md)
 raw = client.read_file("scene_blocks/工作.md")
 ```
@@ -103,6 +120,9 @@ asyncio.run(main())
 | L2 | `rm_scenario()` | `POST /v2/scenario/rm` |
 | L3 | `read_core()` | `POST /v2/core/read` |
 | L3 | `write_core()` | `POST /v2/core/write` |
+| Offload | `offload_ingest()` | `POST /v2/offload/ingest` |
+| Offload | `offload_compact()` | `POST /v2/offload/compact` |
+| Offload | `offload_query_mmd()` | `POST /v2/offload/query-mmd` |

 ## Error Handling

@@ -63,6 +63,23 @@ print(core["content"])
 # L3: 写入核心记忆
 client.write_core("# User Profile\n...")

+# Offload v2: 上报工具调用对，触发服务端 L1 异步处理（可 fire-and-forget）
+client.offload_ingest(
+    session_id="agent_sess_123",
+    tool_pairs=[
+        {"tool_name": "search", "tool_call_id": "call_1", "params": {"q": "..."}, "result": "...", "timestamp": "..."},
+    ],
+)
+
+# Offload v2: 服务端上下文压缩（同步等待结果）
+compacted = client.offload_compact(
+    session_id="agent_sess_123",
+    messages=[...],
+    ratio=0.7,
+    context_window=128000,
+)
+print(compacted["messages"], compacted["report"])
+
 # 读取记忆 pipeline 产物（如 persona.md、scene_blocks/*.md）
 raw = client.read_file("scene_blocks/工作.md")
 ```
@@ -103,6 +120,9 @@ asyncio.run(main())
 | L2 | `rm_scenario()` | `POST /v2/scenario/rm` |
 | L3 | `read_core()` | `POST /v2/core/read` |
 | L3 | `write_core()` | `POST /v2/core/write` |
+| Offload | `offload_ingest()` | `POST /v2/offload/ingest` |
+| Offload | `offload_compact()` | `POST /v2/offload/compact` |
+| Offload | `offload_query_mmd()` | `POST /v2/offload/query-mmd` |

 ## 错误处理

@@ -255,6 +255,116 @@ class MemoryClient:
        """``POST /core/write``"""
        return self._stub.post(f"{_V2}/core/write", {"content": content})

+    # -- Offload (Ingest + Compact + Query-MMD) ----------------------------
+
+    def offload_ingest(
+        self,
+        session_id: str,
+        tool_pairs: List[Dict[str, Any]],
+        *,
+        prompt: Optional[str] = None,
+        recent_messages: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        """``POST /v2/offload/ingest`` — 上报工具调用对，触发 L1 异步处理。
+
+        可 fire-and-forget 使用（忽略返回值）。
+
+        Parameters
+        ----------
+        session_id : str
+            会话 ID。
+        tool_pairs : list[dict]
+            工具调用对列表，每个元素包含 ``tool_name``、``tool_call_id``、
+            ``params``、``result``、``timestamp``，可选 ``duration_ms``。
+        prompt : str, optional
+            最新 user message，用于 L1.5 任务判断。
+        recent_messages : list[dict], optional
+            近期历史消息列表（``role`` + ``content``），辅助 L1 提取上下文。
+        """
+        return self._stub.post(
+            f"{_V2}/offload/ingest",
+            _strip_none({
+                "session_id": session_id,
+                "tool_pairs": tool_pairs,
+                "prompt": prompt,
+                "recent_messages": recent_messages,
+            }),
+        )
+
+    def offload_compact(
+        self,
+        session_id: str,
+        messages: List[Dict[str, Any]],
+        ratio: float,
+        total_tokens: int,
+        *,
+        context_window: Optional[int] = None,
+        message_tokens: Optional[List[int]] = None,
+    ) -> Dict[str, Any]:
+        """``POST /v2/offload/compact`` — 对 messages 执行服务端上下文压缩。
+
+        Parameters
+        ----------
+        session_id : str
+            会话 ID。
+        messages : list[dict]
+            当前完整对话消息列表。
+        ratio : float
+            当前 token 使用比例（已用 / context_window），触发压缩策略判断。
+        total_tokens : int
+            当前完整上下文的总 token 数（包含 system prompt、tool schemas 等不在
+            messages 中的隐性开销）。服务端用于计算 fixed overhead 和校准 token 估算。
+        context_window : int, optional
+            模型 context window 大小（token 数）。
+        message_tokens : list[int], optional
+            每条消息对应的 token 数，提供时可跳过服务端估算，提升性能。
+
+        Returns
+        -------
+        dict
+            ``messages``（压缩后消息列表）+ ``report``（压缩报告）。
+        """
+        return self._stub.post(
+            f"{_V2}/offload/compact",
+            _strip_none({
+                "session_id": session_id,
+                "messages": messages,
+                "ratio": ratio,
+                "total_tokens": total_tokens,
+                "context_window": context_window,
+                "message_tokens": message_tokens,
+            }),
+        )
+
+    def offload_query_mmd(
+        self,
+        session_id: str,
+        *,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """``POST /v2/offload/query-mmd`` — 查询 session 的任务流程图（MMD 文件）。
+
+        Parameters
+        ----------
+        session_id : str
+            会话 ID。
+        limit : int, optional
+            最多返回几个 MMD 文件。``limit=1`` 时走快速路径只返回当前活跃 MMD。
+
+        Returns
+        -------
+        dict
+            ``mmds``（列表，每项含 ``filename``、``content``、``version``）+
+            ``current_mmd``（当前活跃 MMD 文件名，无则为 ``None``）。
+        """
+        return self._stub.post(
+            f"{_V2}/offload/query-mmd",
+            _strip_none({
+                "session_id": session_id,
+                "limit": limit,
+            }),
+        )
+
    # -- File read (memory pipeline artifacts) -----------------------------

    def read_file(self, path: str) -> str:
@@ -432,6 +542,65 @@ class AsyncMemoryClient:
    async def write_core(self, content: str) -> Dict[str, Any]:
        return await self._stub.post(f"{_V2}/core/write", {"content": content})

+    # -- Offload (Ingest + Compact + Query-MMD) ----------------------------
+
+    async def offload_ingest(
+        self,
+        session_id: str,
+        tool_pairs: List[Dict[str, Any]],
+        *,
+        prompt: Optional[str] = None,
+        recent_messages: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        """``POST /v2/offload/ingest``（异步）"""
+        return await self._stub.post(
+            f"{_V2}/offload/ingest",
+            _strip_none({
+                "session_id": session_id,
+                "tool_pairs": tool_pairs,
+                "prompt": prompt,
+                "recent_messages": recent_messages,
+            }),
+        )
+
+    async def offload_compact(
+        self,
+        session_id: str,
+        messages: List[Dict[str, Any]],
+        ratio: float,
+        total_tokens: int,
+        *,
+        context_window: Optional[int] = None,
+        message_tokens: Optional[List[int]] = None,
+    ) -> Dict[str, Any]:
+        """``POST /v2/offload/compact``（异步）"""
+        return await self._stub.post(
+            f"{_V2}/offload/compact",
+            _strip_none({
+                "session_id": session_id,
+                "messages": messages,
+                "ratio": ratio,
+                "total_tokens": total_tokens,
+                "context_window": context_window,
+                "message_tokens": message_tokens,
+            }),
+        )
+
+    async def offload_query_mmd(
+        self,
+        session_id: str,
+        *,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """``POST /v2/offload/query-mmd``（异步）"""
+        return await self._stub.post(
+            f"{_V2}/offload/query-mmd",
+            _strip_none({
+                "session_id": session_id,
+                "limit": limit,
+            }),
+        )
+
    # -- lifecycle ---------------------------------------------------------

    # -- File read (memory pipeline artifacts) -----------------------------