Upload folder using huggingface_hub

agentframe/README.md

@@ -2,7 +2,7 @@
 
 **脑 = DeepSeek · 手 = 工具执行 · 记忆 = 四层上下文保持**
 
-版本 4.2.0 · GPL-3.0 · Cloud LTE Studio
+版本 4.3.0 · GPL-3.0 · Cloud LTE Studio
 
 ---
 
@@ -35,6 +35,8 @@
 | **Aura 遗忘** | S(t)=I·2^(-t/τ) 指数遗忘 + 访问增强 | ✓ 有测试 |
 | **LFRU 滞回** | 历史热块信用折减驱逐分数, 防抖动 (colibrì #441/#497) | ✓ 有测试 |
 | **Couple 预取** | 跨轮共现预取: 检索到 A 后预取常与 A 共现的 B (colibrì couple) | ✓ 有测试 |
+| **KV 增量持久化** | 每轮 append 不重写全量, crash-safe 坏行跳过 (colibrì kv_persist) | ✓ 有测试 |
+| **前缀复用** | 相同前缀 query 复用上次检索, 保持热块 (colibrì kv_prefix) | ✓ 有测试 |
 | **脑+手** | function calling 工具循环, Agent 自验证代码 | ✓ 有测试 + 安全拦截 |
 | **多会话** | 每会话独立引擎, 状态可持久化 | ✓ |
 
@@ -256,6 +258,15 @@ GPL-3.0 © Cloud LTE Studio
 
 ##  Changelog
 
+### v4.3.0 (2026-08-18) — KV 增量持久化 + 前缀复用
+
+**新增**
+- **IncrementalKVStore** (移植 colibrì kv_persist.h): 每轮 ingest 新 chunk 追加一行 JSON, 不重写全量快照; 行级独立 = crash-safe (坏行跳过); `enable_incremental()` 开启, `load_incremental()` 重启恢复
+- **查询前缀复用** (移植 colibrì kv_prefix.h): 新 query 与上一条共享 ≥70% 前缀 → 直接复用上次检索结果 (跳过重新路由) + 保持热块; `_prefix_hits` 统计
+- engine.ingest() 自动 append 到增量日志
+
+**测试**: 核心测试 16 项 (+test_incremental_persist / test_prefix_reuse / test_incremental_engine)
+
 ### v4.2.0 (2026-08-18) — 真 INT4 打包 (28.4x 落地)
 
 **新增**

agentframe/__init__.py

@@ -5,9 +5,9 @@ AgentFrame — Agent 专用上下文保持框架
 手 = 工具执行 (Function Calling)
 记忆 = 四层上下文保持 (认知 × 路由 × 存储 × 物理)
 
-版本: 4.2.0 (先明·第四代: 真 INT4 打包 + Couple 预取 + LFRU 滞回 + 安全加固)
+版本: 4.3.0 (先明·第四代: KV 增量持久化 + 前缀复用 + 真 INT4 + Couple + LFRU)
 """
-__version__ = "4.2.0"
+__version__ = "4.3.0"
 
 from .core.quad import (
     CompressedKV,

agentframe/api/server.py

@@ -107,7 +107,7 @@ class AgentFrameAPI:
 
         @app.get("/health")
         def health():
-            return jsonify({"status": "ok", "version": "4.2.0",
+            return jsonify({"status": "ok", "version": "4.3.0",
                             "sessions": len(self.sessions),
                             "system": "AgentFrame Context API"})
 
@@ -257,7 +257,7 @@ def main():
     config = AgentFrameConfig.from_env()
     port = int(sys.argv[1]) if len(sys.argv) > 1 else config.api.port
     api = AgentFrameAPI(config)
-    print(f"🚀 AgentFrame API v4.2.0")
+    print(f"🚀 AgentFrame API v4.3.0")
     print(f"   四层上下文保持: 认知×路由×存储×物理")
     print(f"   会话: POST /v1/sessions | 摄入: /ingest | 查询: /ask")
     print(f"   监听: {config.api.host}:{port}")

agentframe/core/engine.py

@@ -22,6 +22,7 @@ from ..config import AgentFrameConfig, MemoryConfig
 from ..llm import create_llm, LLMProvider
 from ..embed import create_embedding, EmbeddingProvider
 from ..memory.store import StateStore
+from ..memory.incremental import IncrementalKVStore
 from .quad import QuadLayerAgent
 from .couple import CouplePrefetcher
 
@@ -140,6 +141,15 @@ class ContextEngine:
         # 跨轮共现预取 (colibrì couple_prefetch 移植)
         self.couple = CouplePrefetcher(top_k=m.couple_k)
 
+        # 增量持久化 (colibrì kv_persist 移植): 每轮 append, 不重写全量
+        self.incr_store = None
+        self.incr_path = None
+
+        # 查询前缀复用 (colibrì kv_prefix 移植)
+        self._last_query = None
+        self._last_retrieved = []
+        self._prefix_hits = 0
+
         # 会话状态
         self.chat_history = []
         self.max_history_turns = self.config.api.max_history_turns
@@ -167,6 +177,11 @@ class ContextEngine:
             "created_at": self.now,
         }
         self._chunk_counter += 1
+        # 增量追加持久化: 新 chunk 立即落盘 (crash-safe)
+        if self.incr_store is not None:
+            self.incr_store.append(
+                cid, kv.q4, kv.scales, kv.latent, kv.quant_bits,
+                kv.size_bytes, self.agent.chunk_meta[cid])
         return cid
 
     def ingest_batch(self, chunks: list) -> list:
@@ -230,9 +245,17 @@ class ContextEngine:
         subtasks = self.agent.metacog.decompose(query)
         directive = self.agent.metacog.build_directive(subtasks[0], self.agent.chunk_meta)
 
-        # 2. 路由层: landmark 检索
-        q_vec = self.embedder.embed(query)
-        selection = self.agent.router.route(q_vec, q_vec, self.agent.summaries)
+        # 1.5 查询前缀复用 (colibrì kv_prefix 移植):
+        #     新 query 与上一条共享长前缀 → 直接复用上次检索结果, 保持热块
+        reuse = self._prefix_reuse(query)
+        if reuse is not None:
+            selection = reuse
+        else:
+            # 2. 路由层: landmark 检索
+            q_vec = self.embedder.embed(query)
+            selection = self.agent.router.route(q_vec, q_vec, self.agent.summaries)
+        self._last_query = query
+        self._last_retrieved = list(selection.chunk_ids)
 
         # 2.5 跨轮共现预取: 记录本轮检索 + 预测下轮 → 提升冷块到 RAM
         self.couple.record(selection.chunk_ids)
@@ -295,6 +318,89 @@ class ContextEngine:
             directive=directive,
             meta={"now": self.now, "chunks": len(self.agent.chunk_meta)})
 
+    # ============ 前缀复用 (colibrì kv_prefix 移植) ============
+
+    def _prefix_reuse(self, query: str):
+        """
+        查询前缀复用: 新 query 与上一条共享长前缀 (前 70%+ 且 ≥8 字符)
+        → 直接复用上次检索结果 (跳过重新路由), 并保持上次热块不冷却。
+        返回 ChunkSelection 或 None (不复用)。
+        colibrì 对应: fed[] 序列前缀匹配, 跳过重复 prefill。
+        """
+        if self._last_query is None or not self._last_retrieved:
+            return None
+        prev, cur = self._last_query, query
+        if len(cur) < 8 or len(prev) < 8:
+            return None
+        # 公共前缀长度
+        common = 0
+        for a, b in zip(prev, cur):
+            if a != b:
+                break
+            common += 1
+        # 前缀须覆盖旧 query 的 70% 且新 query 的 50% (防过度复用)
+        if common >= len(prev) * 0.7 and common >= len(cur) * 0.5:
+            # 保持上次热块: 触碰一次 (刷新遗忘曲线)
+            for cid in self._last_retrieved:
+                kv = (self.agent.pager.vram.get(cid)
+                      or self.agent.pager.ram.get(cid)
+                      or self.agent.pager.disk.get(cid))
+                if kv is not None:
+                    self.agent.pager.access(cid, 0.5, self.now)
+            self._prefix_hits += 1
+            from .quad import ChunkSelection
+            return ChunkSelection(
+                chunk_ids=self._last_retrieved,
+                scores=[0.5] * len(self._last_retrieved),
+                weights=[1.0 / len(self._last_retrieved)] * len(self._last_retrieved))
+        return None
+
+    # ============ 增量持久化 (colibrì kv_persist 移植) ============
+
+    def enable_incremental(self, path: str):
+        """开启增量持久化: 新 chunk 追加到日志, 重启可增量恢复"""
+        self.incr_path = path
+        self.incr_store = IncrementalKVStore(path)
+        return self
+
+    def load_incremental(self, path: str = None) -> int:
+        """
+        从增量日志恢复所有 chunk (colibrì: 重启恢复, 不用重新 prefill)。
+        重建 chunk_meta + summaries + pager. 返回恢复的 chunk 数。
+        """
+        path = path or self.incr_path
+        if not path:
+            return 0
+        store = IncrementalKVStore(path)
+        if not store.exists():
+            return 0
+        recs = store.load()
+        restored = 0
+        for rec in recs:
+            cid = rec["chunk_id"]
+            # 跳过已存在的
+            if cid in self.agent.chunk_meta:
+                continue
+            from .quad import CompressedKV
+            kv = CompressedKV(
+                chunk_id=cid,
+                latent=rec["latent"],
+                quant_bits=rec["quant_bits"],
+                size_bytes=rec["size_bytes"],
+                q4=rec["q4"],
+                scales=rec["scales"],
+            )
+            kv.heat = 0.5
+            self.agent.chunk_meta[cid] = rec["meta"]
+            # 重建 landmark 摘要
+            k_prime, bias = self.agent.router.build_summary(
+                rec["latent"].reshape(1, -1))
+            self.agent.summaries[cid] = (k_prime, bias)
+            self.agent.pager.place(kv, self.now)
+            self._chunk_counter = max(self._chunk_counter, cid + 1)
+            restored += 1
+        return restored
+
     # ============ 工具增强版 ask ============
 
     def ask_with_hands(self, query: str, thinking: dict = None) -> AnswerResult:

agentframe/memory/incremental.py

@@ -0,0 +1,100 @@
+"""
+IncrementalKVStore — 增量追加持久化 (colibrì kv_persist.h 移植)
+=================================================================
+colibrì 做法: 每轮对话后把压缩 MLA KV 增量 append 到 .coli_kv,
+nrec 计数最后写 = crash-safe, 重启直接恢复不用重新 prefill。
+
+AgentFrame 移植:
+  - 每次 ingest 的新 chunk 追加为一行 JSON (不重写全量快照)
+  - 行级独立 = 崩溃时最多丢最后一条, 坏行跳过 (crash-safe)
+  - load() 读全部记录重建 chunk + 自动重建 landmark 摘要
+  - 与全量快照 (StateStore) 互补: 增量管内容, 快照管运行时热度状态
+"""
+import json
+import os
+import numpy as np
+
+
+class IncrementalKVStore:
+    """增量追加 KV 日志 (colibrì kv_persist 思想)"""
+
+    MAGIC = "AFKV1"
+
+    def __init__(self, path: str):
+        self.path = path
+
+    # ============ 写入 ============
+
+    def append(self, chunk_id: int, q4: np.ndarray, scales: np.ndarray,
+               latent: np.ndarray, quant_bits: int, size_bytes: int,
+               meta: dict) -> int:
+        """
+        追加一条 chunk 记录 (每行一个 JSON, 追加模式).
+        返回当前记录数 (类似 colibrì 的 nrec).
+        """
+        rec = {
+            "magic": self.MAGIC,
+            "chunk_id": int(chunk_id),
+            "quant_bits": int(quant_bits),
+            "size_bytes": int(size_bytes),
+            "q4": q4.tobytes().hex() if q4 is not None else None,
+            "scales": scales.tolist() if scales is not None else None,
+            "latent": latent.tolist(),
+            "meta": meta,
+        }
+        os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)
+        with open(self.path, "a") as f:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        return self.count()
+
+    def count(self) -> int:
+        """统计有效记录数 (跳过坏行)"""
+        return len(self._read_raw())
+
+    # ============ 读取 ============
+
+    def _read_raw(self) -> list:
+        """读全部行, 跳过损坏/不完整行 (crash-safe 核心)"""
+        if not os.path.exists(self.path):
+            return []
+        recs = []
+        with open(self.path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                    if rec.get("magic") != self.MAGIC:
+                        continue
+                    recs.append(rec)
+                except Exception:
+                    continue  # 崩溃残留的半行: 跳过
+        return recs
+
+    def load(self) -> list:
+        """
+        读全部有效记录, 反序列化为可重建的数据结构.
+        返回: [{chunk_id, q4, scales, latent, quant_bits, size_bytes, meta}, ...]
+        """
+        out = []
+        for rec in self._read_raw():
+            q4 = None
+            if rec.get("q4"):
+                q4 = np.frombuffer(bytes.fromhex(rec["q4"]), dtype=np.uint8)
+            scales = None
+            if rec.get("scales"):
+                scales = np.asarray(rec["scales"], dtype=np.float32)
+            out.append({
+                "chunk_id": int(rec["chunk_id"]),
+                "quant_bits": int(rec.get("quant_bits", 4)),
+                "size_bytes": int(rec.get("size_bytes", 0)),
+                "q4": q4,
+                "scales": scales,
+                "latent": np.asarray(rec.get("latent", [0.0]), dtype=np.float32),
+                "meta": rec.get("meta", {}),
+            })
+        return out
+
+    def exists(self) -> bool:
+        return os.path.exists(self.path)

agentframe/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentframe"
-version = "4.2.0"
-description = "AgentFrame v4.2 — 真 INT4 打包 (29.1x) + Couple 跨轮预取 + LFRU 滞回 + MemoryDirector"
+version = "4.3.0"
+description = "AgentFrame v4.3 — KV 增量持久化 + 前缀复用 + 真 INT4 (29.1x) + Couple 预取 + LFRU 滞回"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "GPL-3.0" }

agentframe/tests/test_core.py

@@ -216,6 +216,69 @@ def test_int4_packing():
     print(f"✅ test_int4_packing (cos={sim:.4f}, {ratio:.1f}x)")
 
 
+def test_incremental_persist():
+    """增量持久化 (colibrì kv_persist 移植): append + crash-safe 恢复"""
+    import tempfile, os
+    from agentframe.memory.incremental import IncrementalKVStore
+
+    path = tempfile.mktemp(suffix=".kv")
+    store = IncrementalKVStore(path)
+    # 追加 3 条
+    import numpy as np
+    n1 = store.append(0, np.zeros(288, dtype=np.uint8), np.ones(16, dtype=np.float32),
+                      np.zeros(576, dtype=np.float32), 4, 352, {"text": "A"})
+    n2 = store.append(1, np.ones(288, dtype=np.uint8), np.ones(16, dtype=np.float32) * 2,
+                      np.ones(576, dtype=np.float32), 4, 352, {"text": "B"})
+    n3 = store.append(2, np.zeros(288, dtype=np.uint8), np.ones(16, dtype=np.float32),
+                      np.zeros(576, dtype=np.float32), 4, 352, {"text": "C"})
+    assert n3 == 3
+    # 模拟崩溃: 写入半行垃圾
+    with open(path, "a") as f:
+        f.write('{"magic": "AFKV1", "chunk_id": 99, "q4": "zz')
+    recs = store.load()
+    assert len(recs) == 3, f"坏行应被跳过, 实际 {len(recs)}"
+    assert recs[1]["meta"]["text"] == "B"
+    print("✅ test_incremental_persist (append + crash-safe 坏行跳过)")
+    os.unlink(path)
+
+
+def test_prefix_reuse():
+    """查询前缀复用 (colibrì kv_prefix 移植)"""
+    eng = make_engine()
+    eng.ingest("KV 压缩 29 倍", ["kv"])
+    eng.ingest("LFRU 滞回驱逐", ["method"])
+    eng.ingest("Couple 预取", ["method"])
+    # 第一轮: 正常检索
+    r1 = eng.ask("KV 压缩是多少倍", chat=False)
+    first = r1.retrieved
+    # 第二轮: 相同前缀 → 复用
+    r2 = eng.ask("KV 压缩是多少倍呢", chat=False)
+    assert eng._prefix_hits == 1, "应触发前缀复用"
+    assert [c for c, _ in r2.retrieved] == [c for c, _ in first]
+    # 第三轮: 完全不同 → 不复用
+    r3 = eng.ask("今天天气怎么样", chat=False)
+    assert eng._prefix_hits == 1, "不同 query 不应复用"
+    print("✅ test_prefix_reuse (前缀命中复用, 不同 query 不复用)")
+
+
+def test_incremental_engine():
+    """引擎级增量恢复: ingest → enable → load_incremental 重建"""
+    import tempfile, os
+    path = tempfile.mktemp(suffix=".kv")
+    eng = make_engine()
+    eng.enable_incremental(path)
+    eng.ingest("增量持久化内容 A", ["a"])
+    eng.ingest("增量持久化内容 B", ["b"])
+    # 新引擎从日志恢复
+    eng2 = make_engine()
+    n = eng2.load_incremental(path)
+    assert n == 2, f"应恢复 2 块, 实际 {n}"
+    r = eng2.ask("增量持久化", chat=False)
+    assert len(r.retrieved) >= 1
+    os.unlink(path)
+    print("✅ test_incremental_engine (引擎级增量恢复 + 检索)")
+
+
 if __name__ == "__main__":
     test_ingest_and_retrieve()
     test_similar_text_retrieval()
@@ -228,4 +291,7 @@ if __name__ == "__main__":
     test_api_auth()
     test_couple_prefetch()
     test_int4_packing()
+    test_incremental_persist()
+    test_prefix_reuse()
+    test_incremental_engine()
     print("\n🎉 全部核心测试通过!")