deepseek-bot 0.2.0__py3-none-any.whl

deepseek_bot/__init__.py

@@ -0,0 +1,3 @@
+"""DeepSeek Bot:自进化个人智能体运行时(前代号 naga,2026-11 定名)。"""
+
+__version__ = "0.2.0"

deepseek_bot/agent.py

@@ -0,0 +1,412 @@
+"""L1 任务回路(M1 批次 2,主文档 §5.1 的最小形态)。
+
+回路:装配上下文(系统提示 + 技能检索)→ LLM 决策 → 工具调用(经
+ctx.perform 入账)→ 结果回填 → 终答 | 步数/预算上限。
+每步进 TraceRecorder(M1 出口:ReplayBundle 非空);预算逐调用
+consume(prompt+completion 全额——deepseek 推理型模型的 completion 含
+reasoning 消耗)。QuotaExhausted → outcome=aborted。
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import re
+import time
+import uuid
+from typing import Any
+
+from pydantic import BaseModel
+
+from deepseek_bot import kernel
+from deepseek_bot.branch import SessionBranch
+from deepseek_bot.ledger_store import DurableLedger
+from deepseek_bot.llm import ModelAdapter, ToolSpec, price_cents
+from deepseek_bot.memory import (
+    MEMORY_DISTILL_MIN_TOOL_CALLS,
+    MemoryStore,
+    new_memory_id,
+    parse_distilled,
+    render_memory_section,
+)
+from deepseek_bot.skills import SKILL_MAX_BYTES, SkillStore
+from deepseek_bot.trace import TraceRecorder
+
+SKILL_DISTILL_MIN_TOOL_CALLS = 5  # spec-constants skill_distill_min_tool_calls / H.4
+
+
+def keywords_of(goal: str) -> list[str]:
+    words = [w for w in re.split(r"[^\w]+", goal) if len(w) >= 2]
+    cjk = re.findall(r"[\u4e00-\u9fff]", goal)
+    return words + [a + b for a, b in itertools.pairwise(cjk)]
+
+
+
+def cluster_of(goal: str) -> str:
+    """任务簇(E.2):确定性分簇——CJK 二元组优先、拉丁词(≥3)次之,前 3 个;
+    整句 CJK 长词不入簇(太具体,簇会碎片化)。"""
+    keywords = keywords_of(goal)
+    cjk_bigrams = [k for k in keywords
+                   if len(k) == 2 and re.search(r"[\u4e00-\u9fff]", k)]
+    latin = [k.lower() for k in re.split(r"[^\w]+", goal)
+             if len(k) >= 3 and not re.search(r"[\u4e00-\u9fff]", k)]
+    parts = (cjk_bigrams + latin)[:3]
+    return "-".join(parts)[:48] or "default"
+SKILL_INJECT_MAX_CHARS = 2000    # 候选 spec-constants skill_inject_max_chars:技能正文注入预算
+
+
+class AgentResult(BaseModel):
+    reply: str | None
+    outcome: str  # success | aborted
+    trace_id: str
+    steps: int
+    tokens: int
+    cost_cents: int
+    failure_analysis: str | None = None
+
+
+def _noop_revert() -> None:
+    return None
+
+
+class AgentLoop:
+    """单任务执行体(M1:CLI 直驱;会话/lane 归属批次 3)。"""
+
+    def __init__(self, *, ledger: DurableLedger, ctx: kernel.Context,
+                 budget: kernel.Budget, adapter: ModelAdapter,
+                 tools: list[Any] | None = None, skill_store: SkillStore | None = None,
+                 session_key: str = "cli:local:owner", model_id: str = "deepseek-v4-flash",
+                 max_steps: int = 8, trace_id: str | None = None,
+                 actor_trust: str | None = None,
+                 max_tokens: int = 8192, trace_parent: str | None = None,
+                 branch: SessionBranch | None = None,
+                 forced_skills: list[tuple[str, str]] | None = None,
+                 meter_skills: bool = True,
+                 memory_store: MemoryStore | None = None):
+        self._ledger = ledger
+        self._ctx = ctx
+        self._budget = budget
+        self._adapter = adapter
+        self._tools = {t.name: t for t in (tools or [])}
+        self._skills = skill_store
+        self._memory = memory_store
+        self._session_key = session_key
+        self._model_id = model_id
+        self._max_steps = max_steps
+        self._trace_id = trace_id
+        self._actor_trust = actor_trust
+        self._max_tokens = max_tokens  # 推理模型:reasoning+content 共享上限,须给足
+        self._trace_parent = trace_parent
+        self._branch = branch
+        self._forced = forced_skills or []   # 影子验证:强制注入的候选 (uri, content)
+        self._meter_skills = meter_skills    # 影子运行不计量(非真实使用)
+        self._step_seq = 0
+
+    # ---- 技能检索(local:{session} + main 双分支;拉丁词 + CJK 二元组) ----
+    @staticmethod
+    def _keywords(goal: str) -> list[str]:
+        words = [w for w in re.split(r"[^\w]+", goal) if len(w) >= 2]
+        cjk = re.findall(r"[\u4e00-\u9fff]", goal)
+        return words + [a + b for a, b in itertools.pairwise(cjk)]
+
+    def _select_skills(self, goal: str, limit: int = 3
+                       ) -> list[tuple[str, str]]:
+        """检索命中技能为 (uri, content) 对——正文随系统提示注入(M4a-1:
+        仅列 URI 对模型行为零影响,技能必须真正进入上下文才构成资产)。"""
+        if self._skills is None:
+            return []
+        keywords = keywords_of(goal)
+        scored: list[tuple[int, str, str, str]] = []  # (score, uri, cas_id, content)
+        seen: set[str] = set()
+        for branch in (f"local:{self._session_key}", "main"):
+            for cas, name, _, _, _ in self._skills.list(branch=branch):
+                if name in seen:
+                    continue
+                got = self._skills.get(name, branch=branch)
+                if got is None:
+                    continue
+                meta, content = got
+                text = (name + " " + content).lower()
+                score = sum(1 for k in keywords if k.lower() in text)
+                if score > 0:
+                    scored.append((score, f"skill://{name}@v{meta.version}", cas, content))
+                    seen.add(name)
+        scored.sort(key=lambda p: (-p[0], p[1]))
+        picked = scored[:limit]
+        for _, _uri, cas, _body in picked:  # 命中即计量(uses/lastUsed,投影确定性更新)
+            if self._meter_skills:
+                self._ledger.append("skill.use", "root", {"cas_id": cas})
+        return [(uri, content) for _, uri, _, content in picked]
+
+    def _system_prompt(self, skills: list[tuple[str, str]],
+                       forced: list[tuple[str, str]] | None = None,
+                       memory_block: str = "") -> str:
+        lines = [
+            ("你是 DeepSeek Bot 的任务执行智能体。"
+             "能直接回答时直接回答;需要外部事实或资料时调用工具。"),
+            ("运行时能力(不要否认自己拥有它们,细节用 system_status 查):"
+             "定时任务调度器(job_create 可直接建)、两层记忆、技能库、"
+             "通知补发队列。"),
+        ]
+        if memory_block:
+            lines += ["", memory_block]  # §6.5 读取路径:召回注入(背景上下文)
+        sections = [(uri, content) for uri, content in skills]
+        if forced:
+            sections = forced + sections  # 影子验证:候选强制注入(不受检索命中约束)
+        if sections:
+            lines += ["", "## 可参考技能(按要点执行)"]
+            for uri, content in sections:
+                body = content[:SKILL_INJECT_MAX_CHARS]
+                if len(content) > SKILL_INJECT_MAX_CHARS:
+                    body += "\n…(截断)"
+                lines += [f"### {uri}", body]
+        return "\n".join(lines)
+
+    async def _call_tool(self, tc: dict[str, Any]) -> tuple[Any, bool, int, Any]:
+        name = str(tc.get("name", ""))
+        tool = self._tools.get(name)
+        raw = tc.get("arguments")
+        t0 = time.monotonic()
+        args: Any = None
+        try:
+            args = json.loads(raw or "{}")
+            if tool is None:
+                raise ValueError(f"unknown tool: {name}")
+
+            async def _apply(tool: Any = tool, args: dict[str, Any] = args) -> Any:
+                return await tool.run(args)
+
+            result: Any = await self._ctx.perform(f"tool:{name}", _apply, _noop_revert)
+            ok = True
+        except Exception as err:  # noqa: BLE001 —— 工具失败=ok=False 步(K.1),
+            # 不得杀死任务:网络错/worker 崩溃/参数错一律降级续跑(出口③前提)
+            if args is None:  # 参数不可解析(#97):截断原始串入轨迹,循环不炸
+                args = raw[:200] if isinstance(raw, str) else raw
+            result = {"error": f"{type(err).__name__}: {err}"}
+            ok = False
+        return result, ok, int((time.monotonic() - t0) * 1000), args
+
+    async def run(self, goal: str) -> AgentResult:
+        skills = self._select_skills(goal)
+        memories = (self._memory.recall(self._session_key, goal)
+                    if self._memory is not None else [])
+        loaded_uris = [uri for uri, _ in skills] + [uri for uri, _ in self._forced]
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": self._system_prompt(
+                skills, self._forced, render_memory_section(memories))},
+            {"role": "user", "content": goal},
+        ]
+        tool_specs = [ToolSpec(name=t.name, description=t.description,
+                               parameters=t.parameters) for t in self._tools.values()]
+        trace_id = self._trace_id or ("tr_" + uuid.uuid4().hex[:24])
+        rec = TraceRecorder(self._ledger,
+                            trace_id=trace_id,
+                            session_key=self._session_key, inbound={"text": goal},
+                            skills_loaded=loaded_uris,
+                            env={"model": self._model_id,
+                                 "channel": self._session_key.split(":", 1)[0],
+                                 "actor_trust": self._actor_trust,
+                                 "memories": [m.cas_id for m in memories]},
+                            parent_trace=self._trace_parent)
+        self._step_seq = 0
+        self._tool_steps = 0
+        self._tool_log: list[dict[str, Any]] = []
+        tokens = 0
+        cost = 0
+        aborted: str | None = None
+        try:
+            for _ in range(self._max_steps):
+                t0 = time.monotonic()
+                resp = await self._adapter.chat(messages, tool_specs or None,
+                                                max_tokens=self._max_tokens)
+                ms = int((time.monotonic() - t0) * 1000)
+                usage = resp.prompt_tokens + resp.completion_tokens
+                self._budget.consume(usage)
+                tokens += usage
+                cost += price_cents(self._model_id, resp.prompt_tokens, resp.completion_tokens)
+                self._step_seq += 1
+                rec.step(self._step_seq, "llm", self._model_id, True, ms, usage,
+                         args={"turn": self._step_seq},
+                         results={"content": resp.content,
+                                  "tool_calls": [tc["name"] for tc in resp.tool_calls]})
+                if resp.tool_calls:
+                    # 回填必须用 OpenAI 完整格式(id/type/function 嵌套)——简化 dict 会被 422 拒
+                    messages.append({"role": "assistant", "content": resp.content or "",
+                                     "tool_calls": [
+                                         {"id": tc["id"], "type": "function",
+                                          "function": {"name": tc["name"],
+                                                       "arguments": tc["arguments"]}}
+                                         for tc in resp.tool_calls]})
+                    for tc in resp.tool_calls:
+                        # 解析在 _call_tool 内(#97):坏 JSON 参数=ok=False 失败步,
+                        # 模型可看到错误并重试,轨迹/分支照常收尾——循环不再裸解析
+                        result, ok, tool_ms, args = await self._call_tool(tc)
+                        self._tool_steps += 1
+                        self._tool_log.append({"tool": str(tc["name"]), "args": args})
+                        self._step_seq += 1
+                        rec.step(self._step_seq, "tool", str(tc["name"]), ok, tool_ms, 0,
+                                 args=args, results=result)
+                        messages.append({"role": "tool", "tool_call_id": tc["id"],
+                                         "content": json.dumps(result, ensure_ascii=False,
+                                                                default=str)})
+                    continue
+                messages.append({"role": "assistant", "content": resp.content or ""})
+                reply = resp.content or ""
+                # 沉淀判定(H.4:≥5 工具调用才值得记;§6.4 默认局部——local:{session} 分支)
+                if self._skills is not None and self._tool_steps >= SKILL_DISTILL_MIN_TOOL_CALLS:
+                    sed = await self._sediment(goal, reply, rec, trace_id)
+                    tokens += sed["tokens"]
+                    cost += sed["cost_cents"]
+                if self._memory is not None and self._tool_steps >= MEMORY_DISTILL_MIN_TOOL_CALLS:
+                    mem = await self._memorize(goal, reply, rec, trace_id)
+                    tokens += mem["tokens"]
+                    cost += mem["cost_cents"]
+                trace = rec.finish(outcome="success", cost_tokens=tokens,
+                             cost_cents=cost,
+                             task_cluster=cluster_of(goal))
+                self._settle_branch("commit", trace_id)
+                return AgentResult(reply=reply, outcome="success",
+                                   trace_id=str(trace["trace_id"]), steps=self._step_seq,
+                                   tokens=tokens, cost_cents=cost)
+            aborted = "步数上限"
+        except kernel.QuotaExhausted:
+            aborted = "预算耗尽"
+        trace = rec.finish(outcome="aborted", cost_tokens=tokens,
+                           cost_cents=cost, failure_analysis=aborted,
+                           task_cluster=cluster_of(goal))
+        self._settle_branch("discard", trace_id)
+        return AgentResult(reply=None, outcome="aborted",
+                           trace_id=str(trace["trace_id"]), steps=self._step_seq,
+                           tokens=tokens, cost_cents=cost, failure_analysis=aborted)
+
+    def _settle_branch(self, action: str, trace_id: str | None) -> None:
+        """任务末分支裁决(M3-2):根分支 commit/discard;子分支保持 open,
+        裁决权属父会话(§5.4 人走茶不凉)——父级联时一并处理。"""
+        if self._branch is None or self._branch.parent is not None:
+            return
+        try:
+            if action == "commit":
+                self._branch.commit(trace_id)
+            else:
+                self._branch.discard()
+        except ValueError:
+            pass  # 分支已被外部处置(如 owner 介入):尊重现状
+
+    # ---- 技能沉淀(④ 类蒸馏调用,H.1;§6.4 默认局部) ----
+    @staticmethod
+    def _slug(text: str, fallback: str) -> str:
+        s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:40]
+        return s or fallback
+
+    async def _sediment(self, goal: str, reply: str, rec: TraceRecorder,
+                        trace_id: str) -> dict[str, int]:
+        """蒸馏任务经验为 SKILL.md,提交 local:{session} 分支;返回计量。"""
+        t0 = time.monotonic()
+        prompt = (
+            "根据以下任务执行记录,为\"下次同类任务直接复用\"沉淀一份技能文档。\n"
+            "第一行输出技能 ID(格式:id: <短横线小写英文>),随后是 Markdown 正文,"
+            "必须包含三个二级标题节:## 何时使用、## 步骤、## 已知陷阱。\n\n"
+            f"任务:{goal}\n"
+            f"执行记录:{json.dumps(self._tool_log, ensure_ascii=False, default=str)}\n"
+            f"最终结果:{reply}")
+        try:
+            resp = await self._adapter.chat([{"role": "user", "content": prompt}],
+                                            None, max_tokens=self._max_tokens)
+        except kernel.QuotaExhausted:
+            self._step_seq += 1
+            rec.step(self._step_seq, "llm", "skill-distill", False,
+                     int((time.monotonic() - t0) * 1000), 0,
+                     args={"goal": goal}, results={"error": "预算耗尽,跳过沉淀"})
+            return {"tokens": 0, "cost_cents": 0}
+        usage = resp.prompt_tokens + resp.completion_tokens
+        try:
+            self._budget.consume(usage)
+        except kernel.QuotaExhausted:
+            return {"tokens": 0, "cost_cents": 0}
+        body = (resp.content or "").strip()
+        m = re.match(r"^id:\s*([a-z0-9][a-z0-9-]*)\s*\n", body)
+        skill_id = m.group(1) if m else self._slug(goal, f"skill-{trace_id[-6:]}")
+        if m:
+            body = body[m.end():]
+        content = f"---\nname: {skill_id}\n---\n{body}\n"
+        data = content.encode("utf-8")
+        if len(data) > SKILL_MAX_BYTES:  # 按字节截断(CJK 多字节;15KB 硬限在 commit 兜底)
+            content = data[:SKILL_MAX_BYTES - 1].decode("utf-8", errors="ignore") + "\n"
+        ok = True
+        try:
+            if self._branch is not None:
+                # M3-2:沉淀写进会话分支(覆盖层),任务末由 commit 物化/discard 丢弃
+                self._branch.put(f"skill:{skill_id}", content.encode("utf-8"))
+            else:
+                assert self._skills is not None
+                self._skills.commit(skill_id, content,
+                                    provenance={"source": "agent", "trace_id": trace_id},
+                                    branch=f"local:{self._session_key}")
+        except (ValueError, AssertionError):
+            ok = False
+        self._step_seq += 1
+        rec.step(self._step_seq, "llm", "skill-distill", ok,
+                 int((time.monotonic() - t0) * 1000), usage,
+                 args={"goal": goal}, results={"skill": skill_id if ok else None})
+        return {"tokens": usage, "cost_cents": price_cents(self._model_id, usage, 0)}
+
+    # ---- 记忆提炼(④ 类调用 1 次,§6.5 情景层;semantic 仅 owner) ----
+    async def _memorize(self, goal: str, reply: str, rec: TraceRecorder,
+                        trace_id: str) -> dict[str, int]:
+        """任务收尾提炼:一次 LLM 调用产出 `[E]` 事件摘要(全信任级)与
+        `[S]` 长期事实(仅 owner 采纳);写经会话分支 COW(§6.5 并行语义,
+        commit 才物化——aborted 任务本就不走此路径,discard 亦不留记忆)。"""
+        t0 = time.monotonic()
+        prompt = (
+            "根据以下任务执行记录提炼记忆。\n"
+            "第一行:[E] <本次任务的一句话事件摘要(做了什么、结果如何,40字内)>\n"
+            "随后每行一条:[S] <值得长期记住的用户偏好或事实>(最多3条,没有就不输出)\n"
+            "只输出以上行,不要多余解释。\n\n"
+            f"任务:{goal}\n"
+            f"执行记录:{json.dumps(self._tool_log, ensure_ascii=False, default=str)}\n"
+            f"最终结果:{reply}")
+        try:
+            resp = await self._adapter.chat([{"role": "user", "content": prompt}],
+                                            None, max_tokens=self._max_tokens)
+        except kernel.QuotaExhausted:
+            self._step_seq += 1
+            rec.step(self._step_seq, "llm", "memory-distill", False,
+                     int((time.monotonic() - t0) * 1000), 0,
+                     args={"goal": goal}, results={"error": "预算耗尽,跳过提炼"})
+            return {"tokens": 0, "cost_cents": 0}
+        usage = resp.prompt_tokens + resp.completion_tokens
+        try:
+            self._budget.consume(usage)
+        except kernel.QuotaExhausted:
+            return {"tokens": 0, "cost_cents": 0}
+        episodic, semantic = parse_distilled((resp.content or "").strip())
+        if self._actor_trust not in (None, "owner"):
+            semantic = []  # §6.5 写入闸门:非 owner 的 [S] 不采纳(store 兜底)
+        written = 0
+        if episodic:
+            written += self._memory_put("episodic", episodic, trace_id)
+        for fact in semantic:
+            written += self._memory_put("semantic", fact, trace_id)
+        self._step_seq += 1
+        rec.step(self._step_seq, "llm", "memory-distill", True,
+                 int((time.monotonic() - t0) * 1000), usage,
+                 args={"goal": goal},
+                 results={"items": written, "episodic": bool(episodic),
+                          "semantic": len(semantic)})
+        return {"tokens": usage,
+                "cost_cents": price_cents(self._model_id, usage, 0)}
+
+    def _memory_put(self, layer: str, content: str, trace_id: str) -> int:
+        """单条落地:有分支走 COW(commit 物化),无分支直写(与 _sediment 同构)。"""
+        assert self._memory is not None  # 调用点已判空
+        provenance = {"source": "agent", "trace_id": trace_id}
+        try:
+            if self._branch is not None:
+                self._branch.put(
+                    f"memory:{layer}:{new_memory_id()}", content.encode("utf-8"))
+                return 1
+            self._memory.write(layer, self._session_key, content, provenance,
+                               actor_trust=self._actor_trust)
+            return 1
+        except (ValueError, OSError):
+            return 0  # 闸门/体检/尺寸拒绝:跳过该条,不杀任务

deepseek_bot/branch.py

@@ -0,0 +1,205 @@
+"""Session branches — the in-process COW write-capture overlay (§6.2/K.2, M3-2).
+
+One active sessionKey binds one branch: **read global, write local**. The
+overlay stores only the diff against the base (overlay_ops: put/del — a
+branch is a diff, not a copy), so untouched keys cost nothing. Session end is
+an explicit two-way choice (K.2): **commit** (diff persisted to CAS as a
+manifest linked to the trace; sink materializes the writes) or **discard**
+(dropped wholesale, zero global effect — the environment is restored).
+
+Kill semantics (§5.4): a killed sub-agent's branch stays **open** — the
+commit/discard decision belongs to the parent session ("人走茶不凉,资产留
+下"). When the parent commits, open child branches cascade-commit; when the
+parent discards, open child branches are discarded with it (ledger-recorded);
+already-committed assets are unaffected either way.
+
+Naga's honest form of K.2: agents never touch the raw filesystem — every
+write goes through the runtime — so write capture is this in-process layer,
+and the ≤10% SLO (R3-4/K.2, 100 concurrent sessions) is measured against it.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+# 写捕获 SLO(R3-4/K.2):拦截开销 ≤10%,百并发实测——M3 出口③
+WRITE_CAPTURE_OVERHEAD_SLO = 0.10
+
+BRANCH_MANIFEST_SCHEMA = "naga-branch/0"
+# manifest 为裸 dict(K.2 SLO:结算路径不建模型):{schema, branch_id,
+# owner_session, trace_id, ops:[{op, key, value_cas}], parent_branch}
+
+
+class SessionBranch:
+    """一条 COW 经验分支:overlay 覆盖 base(全局视图),只存差异。
+
+    base_get/base_has:全局只读视图(会话间不共享内存态,仅经全局库通信)。
+    sink_put/sink_delete:commit 时的物化回调(如 SkillStore.commit)。
+    """
+
+    def __init__(self, *, owner_session: str,
+                 base_get: Callable[[str], bytes | None],
+                 base_has: Callable[[str], bool],
+                 cas_put: Callable[[bytes], str],
+                 sink_put: Callable[[str, bytes], Any] | None = None,
+                 sink_delete: Callable[[str], Any] | None = None,
+                 parent: SessionBranch | None = None,
+                 ledger_append: Callable[[str, str, dict[str, Any]], Any] | None = None,
+                 branch_id: str | None = None):
+        self.branch_id = branch_id or "br_" + uuid.uuid4().hex[:12]
+        self.owner_session = owner_session
+        self._base_get = base_get
+        self._base_has = base_has
+        self._cas_put = cas_put
+        self._sink_put = sink_put
+        self._sink_delete = sink_delete
+        self._parent = parent
+        self._ledger_append = ledger_append
+        self._overlay: dict[str, bytes | None] = {}  # None = 墓碑(delete)
+        self._children: list[SessionBranch] = []
+        self._state = "open"  # open | committed | discarded
+        if parent is not None:
+            parent._children.append(self)
+
+    # ---- 生命周期 ----
+
+    @property
+    def state(self) -> str:
+        return self._state
+
+    @property
+    def parent(self) -> SessionBranch | None:
+        return self._parent
+
+    def spawn_child(self, owner_session: str | None = None) -> SessionBranch:
+        """派生子分支(同一 base/CAS/sink 上下文,挂父链供级联裁决)。"""
+        self._require_open()
+        return SessionBranch(
+            owner_session=owner_session or self.owner_session,
+            base_get=self._base_get, base_has=self._base_has,
+            cas_put=self._cas_put, sink_put=self._sink_put,
+            sink_delete=self._sink_delete, parent=self,
+            ledger_append=self._ledger_append)
+
+    # ---- COW 读写(读全局写本地) ----
+
+    def get(self, key: str) -> bytes | None:
+        """overlay ∪ base,overlay 胜;墓碑=已删除。"""
+        if key in self._overlay:
+            return self._overlay[key]
+        return self._base_get(key)
+
+    def has(self, key: str) -> bool:
+        if key in self._overlay:
+            return self._overlay[key] is not None
+        return self._base_has(key)
+
+    def put(self, key: str, value: bytes) -> None:
+        """写捕获(K.2 拦截路径,纯内存——CAS 推迟到 commit):只记差异,
+        不触全局;与全局一致则消除差异。"""
+        self._require_open()
+        if self._base_get(key) == value:
+            self._overlay.pop(key, None)   # 与全局一致:不产生差异
+            return
+        self._overlay[key] = value
+
+    def delete(self, key: str) -> None:
+        self._require_open()
+        if not self._base_has(key):
+            self._overlay.pop(key, None)   # 全局本就无此键:无差异
+            return
+        self._overlay[key] = None          # 墓碑
+
+    def diff_keys(self) -> list[str]:
+        """差异键集合(未动的键零开销——分支=差异而非副本)。"""
+        return list(self._overlay.keys())
+
+    # ---- 会话结束二选一(K.2) ----
+
+    def commit(self, trace_id: str | None = None) -> str | None:
+        """物化 sink(返回 CAS 则 manifest 引用之,杜绝同内容双写)+ manifest
+        入 CAS;级联:open 子分支一并 commit。op 集合由 overlay 终态导出
+        (同键多次写=终态一次,天然去重)。"""
+        self._require_open()
+        cascaded = self._cascade("commit", trace_id)
+        ops: list[dict[str, Any]] = []
+        for key, value in self._overlay.items():
+            if value is None:
+                if self._sink_delete is not None:
+                    self._sink_delete(key)
+                ops.append({"op": "del", "key": key})
+                continue
+            cas: Any = None
+            if self._sink_put is not None:
+                cas = self._sink_put(key, value)  # 物化即持久化:引用其 CAS
+            if not isinstance(cas, str) or not cas:
+                cas = self._cas_put(value)        # 无 sink/无返回:分支自持
+            ops.append({"op": "put", "key": key, "value_cas": cas})
+        cas_id: str | None = None
+        if ops:
+            manifest = {"schema": BRANCH_MANIFEST_SCHEMA,
+                        "branch_id": self.branch_id,
+                        "owner_session": self.owner_session,
+                        "trace_id": trace_id, "ops": ops,
+                        "parent_branch": (self._parent.branch_id
+                                          if self._parent else None)}
+            cas_id = self._cas_put(
+                json.dumps(manifest, ensure_ascii=False,
+                           separators=(",", ":")).encode())
+        self._state = "committed"
+        # commit 不另入账:manifest 已入 CAS、物化自带 skill.commit 事件
+        # (审计轨迹完备);fsync 级账本追加会令捕获开销翻倍,违反 K.2 SLO 本意
+        del cascaded
+        return cas_id
+
+    def discard(self) -> None:
+        """整体丢弃(环境还原);级联:open 子分支陪葬(入账)。"""
+        self._require_open()
+        cascaded = self._cascade("discard", None)
+        self._overlay.clear()
+        self._state = "discarded"
+        self._record("branch.discarded", {"cascaded_children": cascaded})
+
+    def _cascade(self, action: str, trace_id: str | None) -> int:
+        """§5.4:父 commit → open 子分支级联 commit;父 discard → 陪葬。"""
+        count = 0
+        for child in self._children:
+            if child._state != "open":
+                continue
+            if action == "commit":
+                child.commit(trace_id)
+            else:
+                child.discard()
+            count += 1
+        return count
+
+    def _require_open(self) -> None:
+        if self._state != "open":
+            raise ValueError(f"branch {self.branch_id} 已 {self._state},不可再操作")
+
+    def _record(self, kind: str, payload: dict[str, Any]) -> None:
+        if self._ledger_append is not None:
+            try:
+                self._ledger_append(kind, self.owner_session, payload)
+            except OSError:
+                pass  # 分支语义不因账本 IO 抖动中断(事件尽力入账)
+
+
+class BranchPool:
+    """会话→活跃分支的登记表(gateway 每任务建分支;会话级常驻绑定属会话注册表批次)。"""
+
+    def __init__(self) -> None:
+        self._branches: dict[str, SessionBranch] = {}
+
+    def bind(self, branch: SessionBranch) -> SessionBranch:
+        self._branches[branch.owner_session] = branch
+        return branch
+
+    def of(self, owner_session: str) -> SessionBranch | None:
+        return self._branches.get(owner_session)
+
+    def unbind(self, owner_session: str) -> None:
+        self._branches.pop(owner_session, None)