linope 0.0.2__py3-none-any.whl

bindings/__init__.py

@@ -0,0 +1 @@
+"""Transports a caller may open. The kernel does not import this package."""

bindings/grpc_channel/__init__.py

@@ -0,0 +1,68 @@
+"""Remote call with grpcio. One generic method carries the message as JSON bytes.
+
+The directory is named ``grpc_channel`` so it does not hide the ``grpc`` package.
+The kernel does not import or open this transport.
+"""
+
+from __future__ import annotations
+
+import json
+from concurrent import futures
+from typing import Any
+
+from bindings.support import Inbox, needs
+
+_METHOD = "/linope.Channel/Send"
+
+
+class GrpcChannel:
+    """``addresses`` maps an address string to ``host:port``. ``send`` waits for the seq."""
+
+    name = "grpc"
+
+    def __init__(self, addresses: dict[str, str] | None = None, timeout: float = 10.0) -> None:
+        self._grpc = needs("grpcio", "grpc")
+        self._addresses = {str(pid): str(address) for pid, address in (addresses or {}).items()}
+        self._timeout = float(timeout)
+        self._inboxes: dict[str, Inbox] = {}
+        self._servers: list[Any] = []
+
+    def listen(self, me: str, address: str = "127.0.0.1:0") -> str:
+        """Serve this address's inbox and return the address others call."""
+        grpc = self._grpc
+        inbox = self._inboxes.setdefault(str(me), Inbox())
+
+        def take(request: bytes, context: Any) -> bytes:
+            del context
+            return str(inbox.put(json.loads(request.decode("utf-8")))).encode("utf-8")
+
+        handler = grpc.method_handlers_generic_handler(
+            "linope.Channel",
+            {"Send": grpc.unary_unary_rpc_method_handler(take)},
+        )
+        server = grpc.server(futures.ThreadPoolExecutor(max_workers=2))
+        server.add_generic_rpc_handlers((handler,))
+        host = address.rsplit(":", 1)[0]
+        port = server.add_insecure_port(address)
+        server.start()
+        self._servers.append(server)
+        bound = f"{host}:{port}"
+        self._addresses[str(me)] = bound
+        return bound
+
+    def send(self, to: str, message: dict[str, Any], sender: str = "") -> str:
+        address = self._addresses.get(str(to))
+        if not address:
+            raise LookupError(f"不知道这个地址: {to}")
+        payload = json.dumps({**message, "sender": sender}, ensure_ascii=False).encode("utf-8")
+        with self._grpc.insecure_channel(address) as remote:
+            call = remote.unary_unary(_METHOD)
+            return call(payload, timeout=self._timeout).decode("utf-8")
+
+    def receive(self, me: str, after: int = 0) -> list[dict[str, Any]]:
+        return self._inboxes.setdefault(str(me), Inbox()).after(after)
+
+    def close(self) -> None:
+        for server in self._servers:
+            server.stop(grace=None)
+        self._servers.clear()

bindings/nats_channel/__init__.py

@@ -0,0 +1,72 @@
+"""Queue and topics with nats-py. One address listens on ``linope.<address>``.
+
+A NATS server must already be running. The default address is
+``nats://127.0.0.1:4222``. The kernel does not import or open this transport.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from typing import Any
+
+from bindings.support import Inbox, needs
+
+DEFAULT_SERVER = "nats://127.0.0.1:4222"
+BROADCAST = "linope.all"
+
+
+class NatsChannel:
+    """One connection on its own event loop thread. ``send`` does not wait for a reply."""
+
+    name = "nats"
+
+    def __init__(self, server: str = DEFAULT_SERVER, timeout: float = 5.0) -> None:
+        self._nats = needs("nats-py", "nats")
+        self._server = server
+        self._timeout = float(timeout)
+        self._inboxes: dict[str, Inbox] = {}
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._loop.run_forever, name="nats-channel", daemon=True)
+        self._thread.start()
+        self._client = self._run(self._nats.connect(server, connect_timeout=self._timeout))
+
+    def listen(self, me: str) -> str:
+        """Subscribe this address to its subject and return the subject."""
+        inbox = self._inboxes.setdefault(str(me), Inbox())
+
+        async def take(message: Any) -> None:
+            inbox.put(json.loads(message.data.decode("utf-8")))
+
+        subject = f"linope.{me}"
+        self._run(self._client.subscribe(subject, cb=take))
+        self._run(self._client.subscribe(BROADCAST, cb=take))
+        return subject
+
+    def send(self, to: str, message: dict[str, Any], sender: str = "") -> str:
+        self.publish(f"linope.{to}", message, sender)
+        return ""
+
+    def publish(self, topic: str, message: dict[str, Any], sender: str = "") -> None:
+        """Deliver one message to this topic. The topic string is used as given."""
+        payload = json.dumps({**message, "sender": sender}, ensure_ascii=False).encode("utf-8")
+        self._run(self._client.publish(str(topic), payload))
+        self._run(self._client.flush(timeout=self._timeout))
+
+    def broadcast(self, message: dict[str, Any], sender: str = "") -> None:
+        """Every address that called ``listen`` sees this one message."""
+        self.publish(BROADCAST, message, sender)
+
+    def receive(self, me: str, after: int = 0) -> list[dict[str, Any]]:
+        return self._inboxes.setdefault(str(me), Inbox()).after(after)
+
+    def close(self) -> None:
+        try:
+            self._run(self._client.drain())
+        finally:
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            self._thread.join(timeout=1)
+
+    def _run(self, coroutine: Any) -> Any:
+        return asyncio.run_coroutine_threadsafe(coroutine, self._loop).result(self._timeout + 1)

bindings/support.py

@@ -0,0 +1,35 @@
+"""Small pieces the transports share. The kernel does not import them."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def needs(package: str, module: str) -> Any:
+    """Import a library a transport is built on, or say which package to install."""
+    import importlib
+
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise RuntimeError(f"这个通道要先安装 {package}: pip install {package}") from exc
+
+
+class Inbox:
+    """Received messages for one address, numbered as they arrive."""
+
+    def __init__(self) -> None:
+        import threading
+
+        self._lock = threading.Lock()
+        self._rows: list[dict[str, Any]] = []
+
+    def put(self, message: dict[str, Any]) -> int:
+        with self._lock:
+            seq = len(self._rows) + 1
+            self._rows.append({**message, "seq": seq})
+            return seq
+
+    def after(self, seq: int) -> list[dict[str, Any]]:
+        with self._lock:
+            return [dict(row) for row in self._rows if row["seq"] > int(seq)]

bindings/zeromq_channel/__init__.py

@@ -0,0 +1,68 @@
+"""Point to point with pyzmq. Each address binds a PULL socket.
+
+The kernel does not import or open this transport.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any
+
+from bindings.support import Inbox, needs
+
+
+class ZeroMqChannel:
+    """``addresses`` maps an address string to ``tcp://host:port``. ``send`` does not wait."""
+
+    name = "zeromq"
+
+    def __init__(self, addresses: dict[str, str] | None = None) -> None:
+        self._zmq = needs("pyzmq", "zmq")
+        self._context = self._zmq.Context.instance()
+        self._addresses = {str(pid): str(address) for pid, address in (addresses or {}).items()}
+        self._inboxes: dict[str, Inbox] = {}
+        self._threads: list[threading.Thread] = []
+        self._stop = threading.Event()
+
+    def listen(self, me: str, address: str = "tcp://127.0.0.1:*") -> str:
+        """Bind this address's socket and return the address others send to."""
+        socket = self._context.socket(self._zmq.PULL)
+        socket.bind(address)
+        bound = socket.getsockopt_string(self._zmq.LAST_ENDPOINT)
+        self._addresses[str(me)] = bound
+        inbox = self._inboxes.setdefault(str(me), Inbox())
+        thread = threading.Thread(target=self._drain, args=(socket, inbox), daemon=True)
+        thread.start()
+        self._threads.append(thread)
+        return bound
+
+    def send(self, to: str, message: dict[str, Any], sender: str = "") -> str:
+        address = self._addresses.get(str(to))
+        if not address:
+            raise LookupError(f"不知道这个地址: {to}")
+        socket = self._context.socket(self._zmq.PUSH)
+        try:
+            socket.connect(address)
+            socket.send_string(json.dumps({**message, "sender": sender}, ensure_ascii=False))
+        finally:
+            socket.close(linger=1000)
+        return ""
+
+    def receive(self, me: str, after: int = 0) -> list[dict[str, Any]]:
+        return self._inboxes.setdefault(str(me), Inbox()).after(after)
+
+    def close(self) -> None:
+        self._stop.set()
+        for thread in self._threads:
+            thread.join(timeout=1)
+
+    def _drain(self, socket: Any, inbox: Inbox) -> None:
+        poller = self._zmq.Poller()
+        poller.register(socket, self._zmq.POLLIN)
+        try:
+            while not self._stop.is_set():
+                if dict(poller.poll(100)).get(socket):
+                    inbox.put(json.loads(socket.recv_string()))
+        finally:
+            socket.close(linger=0)

capability/README.cn.md

@@ -0,0 +1,51 @@
+# capability/ — 进程可以加载的插件
+
+[English](README.md) | 中文
+
+这棵树是业务侧。内核启动进程并绑定它的资源记录。插件文件拥有卡片、工具参数和提示词文本。一个操作系统进程加载一个插件。模型和它调用的工具是对等进程，各自有自己的记录。
+
+增加一个能力，就是增加一个本目录扫描能看见的文件。内核没有一份要去改的登记表。
+
+[`process_adapter.py`](process_adapter.py) 随每次启动一起加载。`create_adapter()` 在已经加载的模块上找到 `load` 或 `load_async`，并转发一次请求。它只接受操作 `load`。卡片、消息形状和压缩选择留在插件里。
+
+## 内核如何找到插件
+
+[`kernel/process/process_creat`](../kernel/process/process_creat/README.cn.md) 里的 [`discover_instances`](../kernel/process/process_creat/instances.py) 遍历本目录。一个文件被登记，需要同时满足两条：
+
+- 文件名以 `_plugin.py` 结尾。
+- 文件文本里有 `def load(` 或 `async def load(`。
+
+带了 `load` 函数的 `weather.py` 不会被看见。没有 `load` 函数的 `*_plugin.py` 也不会被看见。扫描读的是文本，不会为了判断而导入该文件。
+
+能力名由路径算出来：
+
+| 位置 | 名字 |
+|---|---|
+| `capability/tools/.../glob_plugin.py` | `tools.glob` |
+| `capability/model/.../openai_chat_model/*_plugin.py` | `model.openai_chat_model` |
+| 嵌在 `capability/sandbox/` 下的插件 | `sandbox.sandbox` |
+| `capability/<family>/.../thing_plugin.py` | `<family>.thing` |
+
+`model` 用的是上一级目录名。`tools` 用的是去掉 `_plugin` 之后的文件名。直接放在 `capability/sandbox/` 里的插件会叫 `sandbox.<文件名>`；当前的入口是嵌套的，所以名字是 `sandbox.sandbox`。其他家族用第一级目录名和文件名。一个名字只保留一个文件。两个文件算出同一个名字时，留下排序后较后的那条路径。
+
+`capability/prompt` 下名为 `prompt_main.py` 且定义了 `load` 的文件也会被登记，名字是 `prompt.<group>`。这棵树里没有这样的文件。
+
+`linope process start <capability>` 启动一个已登记的名字。
+
+## 可启动的插件要提供什么
+
+[`kernel/process`](../kernel/process/README.cn.md) 的 `profile.py` 在打开记录之前调用 `capability_profile(capability_id, changes)`。该函数返回一份 `ProcessDeclaration`：能力名，以及它要租用的资源。种类是 `tool`、`sandbox`、`network` 和 `memory`。没有可用画像或画像失败时抛出 `ProfileUnavailable`，进程不会启动。卡片留在插件内部。
+
+之后的请求调用 `load(kind, body, call_params=None)`。`kind` 是资源种类，例如 `tool`。`body` 是这次调用。`call_params` 是租约带进来的参数。异步插件再写一个参数相同的 `async def load_async(...)`。希望模型能看见的工具再提供 `tool_schemas()`。
+
+工具的这份声明由 [`kernel/process/profiles.py`](../kernel/process/profiles.py) 里的 `tool_with_workspace` 和 `tool_only` 生成。哪些名字算只读、命令或写入，以及 `--change permission=` 和 `--change capabilities=` 如何选择模型能看见的工具，在 [`kernel/process`](../kernel/process/README.cn.md)。
+
+## 目录
+
+| 目录 | 职责 |
+|---|---|
+| [`model/`](model/README.cn.md) | 可启动的提供者插件，名字是 `model.<提供者目录>`。卡片、SDK 调用、消息块，以及加载一张点名卡片的运行时都在这里。回合在 [`kernel/scheduler`](../kernel/scheduler/README.cn.md)。 |
+| [`tools/`](tools/README.cn.md) | 可启动的代理工具和外部宿主，名字是 `tools.<文件名>`：文件、shell、终端、代码、网页搜索、向用户提问，以及 MCP。`load` 接受种类 `tool`。 |
+| [`sandbox/`](sandbox/README.cn.md) | 文件写入模式 `read-only`、`workspace-write`、`danger-full-access`，以及平台包装器。可启动的入口是 `sandbox.sandbox`。这里其余的 `*_plugin.py` 是 [`kernel/environment`](../kernel/environment/README.cn.md) 按路径加载的后端。Docker 工作区是另一份契约。 |
+| [`context/`](context/README.cn.md) | 语义、摘要和滑动窗口压缩。每个包的入口文件叫 `capability_profile.py`，因此 `*_plugin.py` 的遍历不会登记它。`load` 在该文件夹里选出签名与正文相符的那一个函数。 |
+| [`prompt/`](prompt/README.cn.md) | 系统提示词 Markdown。本目录没有 `load`。想使用这些文本的宿主自己读文件。 |

capability/README.md

@@ -0,0 +1,51 @@
+# capability/ — plugins a process can load
+
+English | [中文](README.cn.md)
+
+This tree is the business side. The kernel starts a process and binds its resource record. The plugin file owns the card, the tool arguments, and the prompt text. One operating-system process loads one plugin. A model and the tools it calls are peer processes, each with its own record.
+
+Adding a capability is adding a file this tree's scan can see. The kernel has no registry to edit.
+
+[`process_adapter.py`](process_adapter.py) is loaded with every start. `create_adapter()` finds `load` or `load_async` on the modules already loaded and forwards one request. The only operation it accepts is `load`. It leaves the card, the message shape, and the compression choice in the plugin.
+
+## How the kernel finds a plugin
+
+[`discover_instances`](../kernel/process/process_creat/instances.py) in [`kernel/process/process_creat`](../kernel/process/process_creat/README.md) walks this directory. A file is registered only when both are true:
+
+- The file name ends with `_plugin.py`.
+- The file text contains `def load(` or `async def load(`.
+
+`weather.py` with a `load` function stays unseen. A `*_plugin.py` file with no `load` function stays unseen. The scan reads the text. It does not import the file to decide.
+
+The capability name is computed from the path:
+
+| Place | Name |
+|---|---|
+| `capability/tools/.../glob_plugin.py` | `tools.glob` |
+| `capability/model/.../openai_chat_model/*_plugin.py` | `model.openai_chat_model` |
+| a plugin nested under `capability/sandbox/` | `sandbox.sandbox` |
+| `capability/<family>/.../thing_plugin.py` | `<family>.thing` |
+
+`model` uses the parent directory name. `tools` uses the file name with `_plugin` removed. A plugin sitting directly in `capability/sandbox/` would be `sandbox.<file stem>`; the current entry is nested, so its name is `sandbox.sandbox`. Any other family uses its first directory and the file name. One name keeps one file. Two files that compute the same name leave the later path in sorted order.
+
+A file named `prompt_main.py` under `capability/prompt` is also registered, as `prompt.<group>`, when it defines `load`. This tree has no such file.
+
+`linope process start <capability>` starts one registered name.
+
+## What a startable plugin provides
+
+[`kernel/process`](../kernel/process/README.md) `profile.py` calls `capability_profile(capability_id, changes)` before the record is opened. The function returns a `ProcessDeclaration`: the capability name and the resources it leases. The kinds are `tool`, `sandbox`, `network`, and `memory`. A missing or failing profile raises `ProfileUnavailable`, and the process does not start. The card stays inside the plugin.
+
+A later request calls `load(kind, body, call_params=None)`. `kind` is the resource kind, such as `tool`. `body` is the call. `call_params` is what the lease carried in. An async plugin adds `async def load_async(...)` with the same arguments. A tool the model should be offered also exposes `tool_schemas()`.
+
+`tool_with_workspace` and `tool_only` in [`kernel/process/profiles.py`](../kernel/process/profiles.py) build that declaration for a tool. Which names count as read, command, or write, and how `--change permission=` and `--change capabilities=` choose the tools a model sees, is [`kernel/process`](../kernel/process/README.md).
+
+## Directories
+
+| Directory | Role |
+|---|---|
+| [`model/`](model/README.md) | Startable provider plugins, named `model.<provider directory>`. The card, the SDK call, the message blocks, and the runtime that loads a named card live here. The turn is [`kernel/scheduler`](../kernel/scheduler/README.md). |
+| [`tools/`](tools/README.md) | Startable agent tools and external hosts, named `tools.<file stem>`: files, shell, terminal, code, web search, questions, and MCP. `load` accepts kind `tool`. |
+| [`sandbox/`](sandbox/README.md) | File-write modes `read-only`, `workspace-write`, and `danger-full-access`, plus the platform wrappers. The startable entry is `sandbox.sandbox`. Other `*_plugin.py` files here are backends [`kernel/environment`](../kernel/environment/README.md) loads by path. The Docker workspace is a separate contract. |
+| [`context/`](context/README.md) | Semantic, summary, and sliding-window compression. Each package's entry is `capability_profile.py`, so the `*_plugin.py` walk does not register it. `load` picks the one function in the folder whose signature fits the body. |
+| [`prompt/`](prompt/README.md) | System-prompt markdown. This directory has no `load`. A host that wants the text reads the files itself. |

capability/context/README.cn.md

@@ -0,0 +1,11 @@
+# context/ — 进程可以加载的压缩函数
+
+[English](README.md) | 中文
+
+`load_in_directory` 在一个文件夹里选出签名恰好接受正文字段、且不多接受字段的那一个公开函数。零个匹配或多于一个匹配抛出 `ValueError`。`capability_profile` 和 `load` 不是候选。字符串正文变成一条用户消息。
+
+每个压缩包声明一份 `memory` 资源，其 `scope` 是能力 id。`--change` 的值不会应用到该声明上。
+
+| 目录 | 职责 |
+|---|---|
+| [`context_compression/`](context_compression/README.cn.md) | 语义、摘要和滑动窗口函数 |

capability/context/README.md

@@ -0,0 +1,11 @@
+# context/ — compression functions a process can load
+
+English | [中文](README.cn.md)
+
+`load_in_directory` picks the one public function in a folder whose signature accepts the body's keys and no extra keys. Zero matches or more than one match raises `ValueError`. `capability_profile` and `load` are not candidates. A string body becomes one user message.
+
+Each compression package claims a `memory` resource whose `scope` is the capability id. `--change` values are not applied to that declaration.
+
+| Directory | Role |
+|---|---|
+| [`context_compression/`](context_compression/README.md) | Semantic, summary, and sliding-window functions |

capability/context/__init__.py

@@ -0,0 +1,107 @@
+"""Context capability package. Its load chooses the compression function."""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def load_in_directory(directory: Path, kind: str, body: Any) -> Any:
+    """Load context content with the one function in this folder that fits."""
+    if kind != "context":
+        raise ValueError(f"This process cannot load {kind}")
+    arguments = _arguments(body)
+    matches = _functions_for_arguments(directory, arguments)
+    if len(matches) != 1:
+        raise ValueError(
+            "No function can load this content" if not matches else "More than one function matches this content"
+        )
+    return _invoke(matches[0], arguments)
+
+
+def _arguments(body: Any) -> dict[str, Any]:
+    if isinstance(body, dict):
+        return body
+    if isinstance(body, str):
+        return {"messages": [{"role": "user", "content": body}]}
+    raise TypeError("context content must be a mapping or text")
+
+
+def _functions_for_arguments(directory: Path, arguments: dict[str, Any]) -> list[Any]:
+    keys = set(arguments)
+    found: list[Any] = []
+    seen: set[int] = set()
+    for path in sorted(directory.glob("*.py")):
+        if path.name.startswith("test_") or path.name == "__init__.py":
+            continue
+        module = _load(path)
+        for name, value in vars(module).items():
+            if not _is_local_function(name, value, directory) or id(value) in seen:
+                continue
+            if not _accepts_arguments(value, keys):
+                continue
+            seen.add(id(value))
+            found.append(value)
+    return found
+
+
+def _is_local_function(name: str, value: Any, directory: Path) -> bool:
+    if not inspect.isfunction(value) or name.startswith("_") or name in {
+        "capability_profile",
+        "load",
+    }:
+        return False
+    code = getattr(value, "__code__", None)
+    if code is None:
+        return False
+    return Path(code.co_filename).resolve().parent == directory.resolve()
+
+
+def _accepts_arguments(function: Any, keys: set[str]) -> bool:
+    try:
+        signature = inspect.signature(function)
+    except (TypeError, ValueError):
+        return False
+    required: set[str] = set()
+    accepted: set[str] = set()
+    for parameter in signature.parameters.values():
+        if parameter.kind in {
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        }:
+            continue
+        accepted.add(parameter.name)
+        if parameter.default is inspect.Parameter.empty:
+            required.add(parameter.name)
+    return required <= keys <= accepted
+
+
+def _invoke(function: Any, arguments: dict[str, Any]) -> Any:
+    try:
+        bound = inspect.signature(function).bind(**arguments)
+    except TypeError as error:
+        raise TypeError(f"Cannot load content: {error}") from error
+    bound.apply_defaults()
+    if inspect.iscoroutinefunction(function):
+        return __import__("asyncio").run(function(*bound.args, **bound.kwargs))
+    return function(*bound.args, **bound.kwargs)
+
+
+def _load(path: Path) -> Any:
+    resolved = path.resolve()
+    for module in list(sys.modules.values()):
+        raw = getattr(module, "__file__", None)
+        if raw and Path(raw).resolve() == resolved:
+            return module
+    token = "".join(character if character.isalnum() else "_" for character in resolved.as_posix())
+    name = "context_capability_" + token[-80:]
+    spec = importlib.util.spec_from_file_location(name, resolved)
+    if spec is None or spec.loader is None:
+        raise ImportError(resolved)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module

capability/context/context_compression/README.cn.md

@@ -0,0 +1,11 @@
+# context_compression/ — 三个压缩包
+
+[English](README.md) | 中文
+
+每个包由自己的 `load` 加载，它对那个包的文件夹调用 [`load_in_directory`](../README.cn.md)。一个包里的函数不导入另一个包。token 计数由调用方注入。本目录不发现一条唯一的流水线。
+
+| 目录 | 职责 |
+|---|---|
+| [`semantic_compression/`](semantic_compression/README.cn.md) | 对工具结果、参数和媒体的确定性改写 |
+| [`summary_compression/`](summary_compression/README.cn.md) | 摘要预算、提示词、模型调用和转录组装 |
+| [`sliding_window/`](sliding_window/README.cn.md) | 头部保护、锚点，以及尾部裁剪 |

capability/context/context_compression/README.md

@@ -0,0 +1,11 @@
+# context_compression/ — three compression packages
+
+English | [中文](README.cn.md)
+
+Each package is loaded by its own `load`, which calls [`load_in_directory`](../README.md) on that package's folder. Functions in one package do not import another package. Token counting is injected by the caller. This directory does not discover a single pipeline.
+
+| Directory | Role |
+|---|---|
+| [`semantic_compression/`](semantic_compression/README.md) | Deterministic rewrites of tool results, arguments, and media |
+| [`summary_compression/`](summary_compression/README.md) | Summary budget, prompt, model call, and transcript assembly |
+| [`sliding_window/`](sliding_window/README.md) | Head protection, anchors, and a tail cut |

capability/context/context_compression/semantic_compression/README.cn.md

@@ -0,0 +1,79 @@
+# 语义压缩的原子函数
+
+[English](README.md) | 中文
+
+对 `list[dict]` 消息的小型确定性函数。`load` 通过 [`load_in_directory`](../../README.cn.md) 选出其中一个。宿主也可以导入这些函数并传入回调。没有函数导入本目录里的另一个模块、`sliding_window` 或 `summary_compression`。
+
+## 契约
+
+- 消息变换接受并返回 `list[dict]`。
+- 没有函数导入另一个项目模块，或本目录里的另一个函数。
+- 没有函数导入 `sliding_window` 或 `summary_compression`。
+- 这里不实现 token 计数。宿主注入 `estimate_messages(list[dict]) -> int`。
+- 摘要、标记、选择规则和策略决定可以注入。
+- 空操作通常返回原来的列表对象，让宿主能用身份判断是否提交了改写。
+- 函数只浅复制被改写的消息或调用，不修改输入。
+
+## 原子函数
+
+- `tool_result_dedup.py`：保留相同字符串工具结果的最新完整副本，并把更早的副本换成回指。
+- `tool_result_summary.py`：常见工具的安全一行摘要，加上永不抛出的回退；也暴露由回调驱动的结果替换。
+- `json_args_truncation.py`：解析 JSON 之后递归截断字符串叶子，保留合法 JSON，畸形参数保持不变。
+- `old_tool_result_demotion.py`：用注入的摘要、图片和保护回调，降级宿主选出的旧结果。
+- `protected_tail_pressure.py`：降级受保护尾部的结果，直到注入的估计器报告尾部低于其软上限。
+- `proactive_prune_gate.py`：在提交会打破提示缓存的主动修剪之前，应用触发、资格和测得回收量这些门。
+- `tool_pair_sanitizer.py`：去掉孤儿工具结果，并剥掉没有匹配结果的工具调用。
+- `media_stripping.py`：替换图片部分，并剥掉比最新一条带图片的用户消息更早的图片。
+- `skill_view_guard.py`：识别 `skill_view` 调用，计算受保护的技能名，创建降级保护回调，并收集幽灵标记。
+- `deterministic_pipeline.py`：可选的、只跑回调的多遍运行器。它不导入插件，也不包含策略。
+
+## 宿主组合
+
+宿主拥有配置，并导入它想要的函数。它为边界和策略创建闭包，然后按这个顺序传给只跑回调的流水线：
+
+1. 去重工具结果。
+2. 计算受保护尾部的边界。
+3. 从原始或当前消息建立 `skill_view` 保护。
+4. 降级边界以外的旧工具结果。
+5. 截断旧的 JSON 工具参数。
+6. 用宿主估计器做受保护尾部的压力降级。
+7. 清理工具调用和结果对。
+8. 剥掉历史媒体。
+9. 在语义摘要之前收集幽灵技能标记，并把缺失的标记注入宿主产生的摘要。
+
+主动路径应把第 1、4、5 步作为候选放进 `commit_proactive_prune`。那个插件估计实际的前后列表，除非达到回收阈值，否则返回原来的对象。
+
+宿主接线示例（仅作说明）：
+
+```python
+passes = [
+    deduplicate_tool_results,
+    lambda rows: demote_old_tool_results(
+        rows,
+        should_demote=lambda index, _row: index < protected_start,
+        summary_callback=default_tool_result_summary,
+        protect_callback=skill_protection,
+    ),
+    lambda rows: truncate_tool_call_arguments(
+        rows,
+        should_truncate=lambda index, _row: index < protected_start,
+    ),
+    lambda rows: demote_protected_tail_under_pressure(
+        rows,
+        protected_start=protected_start,
+        soft_token_limit=tail_limit,
+        estimate_messages=host_estimator,
+        summary_callback=default_tool_result_summary,
+    ),
+    sanitize_tool_pairs,
+    strip_historical_media,
+]
+compressed = run_deterministic_pipeline(messages, passes=passes)
+```
+
+这个示例里的名字故意不通过 `__init__`、门面或宿主模块重新导出。宿主直接导入每个原子插件。
+
+## 已知限制与暂缓事项
+
+- **没有登记流水线** — `deterministic_pipeline.py` 运行给它的回调，不导入兄弟。本包上的 `load` 仍按参数名选出一个函数。
+- **token 计数是注入的** — 宿主传入时，函数调用 `estimate_messages`。本目录自己不计数。