sokel-plugin-sdk 0.2.0__py3-none-any.whl

sokel/nats_transport.py

@@ -0,0 +1,417 @@
+"""NATS 承载：插件**出站**连 broker（无入站端口、无公网 IP、无防火墙洞）。
+
+流程与 Go SDK 逐条对齐（协议 §1-§7）：发现 → 连接 → 注册（上报契约）→ 订阅（队列组）→
+心跳续约 → 分发调用 → 优雅下线。事件源插件另有 per-credential supervisor。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import signal
+import socket
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+import nats
+from nats.aio.msg import Msg
+
+from . import contract as C
+from . import env
+from .events import CredEntry, SourceCtx, desired_source_creds, SourceSupervisor
+from .plugin import Plugin
+from .runtime import BufferSink, File
+
+log = logging.getLogger("sokel")
+
+QUEUE_GROUP = "sokel-workers"  # 同组多副本共享队列组 → 每次调用只投一个副本（真·负载均衡）
+INSTANCE_HEADER = "Sokel-Instance"  # 回包/流帧自报副本身份
+FILE_CHUNK = 1 << 20  # 1 MiB：字节不走操作 reply（受 max_payload 约束），走专用分块通道
+HEARTBEAT_SEC = 20
+RETRY_SEC = 8
+REQUEST_TIMEOUT = 8
+FILE_TIMEOUT = 30
+
+
+class NatsFiles:
+    """经同一条 NATS 连接与平台交换文件字节。不要求插件可达平台 HTTP —— 内网插件同样可用。"""
+
+    def __init__(self, nc: Any, token: str) -> None:
+        self._nc = nc
+        self._token = token
+
+    async def fetch(self, f: File) -> bytes:
+        fid = f.id or (f.url.rsplit("/", 1)[-1] if f.url else "")
+        if not fid:
+            raise ValueError("文件引用缺少 id/url")
+        out = bytearray()
+        seq = 0
+        while True:
+            req = json.dumps({"token": self._token, "id": fid, "seq": seq}).encode()
+            resp = await self._nc.request("sokel.file.get", req, timeout=FILE_TIMEOUT)
+            r = json.loads(resp.data)
+            if r.get("error"):
+                raise RuntimeError(r["error"])
+            out += base64.b64decode(r.get("data") or "")
+            if r.get("last"):
+                return bytes(out)
+            seq += 1
+
+    async def store(self, name: str, mime: str, data: bytes) -> File:
+        upload_id = ""
+        seq = 0
+        total = len(data)
+        while True:
+            chunk = data[seq * FILE_CHUNK : (seq + 1) * FILE_CHUNK]
+            last = (seq + 1) * FILE_CHUNK >= total
+            req = json.dumps(
+                {
+                    "token": self._token,
+                    "upload_id": upload_id,
+                    "name": name,
+                    "mime": mime,
+                    "seq": seq,
+                    "last": last,
+                    "data": base64.b64encode(chunk).decode(),
+                }
+            ).encode()
+            resp = await self._nc.request("sokel.file.put", req, timeout=FILE_TIMEOUT)
+            r = json.loads(resp.data)
+            if r.get("error"):
+                raise RuntimeError(r["error"])
+            if r.get("upload_id"):
+                upload_id = r["upload_id"]
+            if last:
+                f = r.get("file")
+                if not f:
+                    raise RuntimeError("平台未返回文件引用")
+                return File(**f)
+            seq += 1
+
+
+class NatsTransport:
+    async def run(self, p: Plugin) -> None:
+        target = await discover(p.endpoint, p.token)
+        # broker 的传输层鉴权优先用 SOKEL_NATS_TOKEN；缺省回退接入 token（无鉴权 broker 会忽略它）
+        nats_token = env.get("NATS_TOKEN") or p.token
+        opts: Dict[str, Any] = {
+            "servers": [target],
+            "name": p.name,
+            "max_reconnect_attempts": -1,  # 无限重连；订阅在重连后自动恢复
+            "reconnect_time_wait": 2,
+            "disconnected_cb": _cb(lambda: log.warning("[sokel] 与平台断开（自动重连中）")),
+            "reconnected_cb": _cb(lambda: log.info("[sokel] 已重连平台")),
+        }
+        if nats_token:
+            opts["token"] = nats_token
+        if ca := env.get("NATS_CA"):  # 连 TLS broker 且证书非系统信任时的自定义 CA
+            import ssl
+
+            ctx = ssl.create_default_context(cafile=ca)
+            opts["tls"] = ctx
+        nc = await _connect_forever(opts)
+
+        host = socket.gethostname()
+        instance_id = stable_instance_id(p.token)
+        started_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        files = NatsFiles(nc, p.token)
+        state: Dict[str, Any] = {"notify": ""}
+
+        async def register() -> Tuple[str, str, List[CredEntry]]:
+            body = p.register_payload(instance_id, host, started_at)
+            resp = await nc.request("sokel.register", json.dumps(body).encode(), timeout=REQUEST_TIMEOUT)
+            reg = json.loads(resp.data)
+            if not reg.get("ok") or not reg.get("subject"):
+                raise RuntimeError(f"注册被拒：{reg.get('error') or '平台未给 subject'}")
+            if reg.get("notify_subject"):
+                state["notify"] = reg["notify_subject"]
+            creds = [CredEntry(c.get("id", ""), c.get("fields")) for c in (reg.get("credentials") or [])]
+            # 旧平台只有单数形态 → 折算成单元素集合（行为与旧版一致）
+            if not creds and (reg.get("credential_id") or reg.get("credential")):
+                creds = [CredEntry(reg.get("credential_id", ""), reg.get("credential"))]
+            return reg["subject"], reg.get("name") or p.name, creds
+
+        # 启动注册失败不退出（broker / 平台可能尚未就绪），固定间隔重试直到成功
+        while True:
+            try:
+                subject, name, creds = await register()
+                break
+            except Exception as e:  # noqa: BLE001
+                log.warning("[sokel] 注册失败（%s），%ds 后重试…", e, RETRY_SEC)
+                await asyncio.sleep(RETRY_SEC)
+
+        async def on_call(msg: Msg) -> None:
+            await self._dispatch(p, nc, msg, files, instance_id)
+
+        await nc.subscribe(subject, queue=QUEUE_GROUP, cb=on_call)
+        log.info("[sokel] 已接入平台：插件「%s」就绪，副本 %s 监听 %s", name, instance_id, subject)
+
+        supervisor: Optional[SourceSupervisor] = None
+        if p.sources:
+            supervisor = _make_supervisor(p, nc, files)
+            supervisor.reconcile(desired_source_creds(creds))
+            if state["notify"]:
+                # 凭证变更即时通知：普通订阅（非队列组），组内每个副本都要收——各自的分配集合都可能变
+                debounce = _Debouncer(0.3, lambda: _resync(register, supervisor))
+
+                async def on_notify(_msg: Msg) -> None:
+                    debounce.trigger()
+
+                # 回调必须是协程：nats-py 对普通函数直接抛「must use coroutine for subscriptions」
+                await nc.subscribe(state["notify"], cb=on_notify)
+
+        stop = asyncio.Event()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, stop.set)
+            except NotImplementedError:  # Windows / 非主线程
+                pass
+
+        try:
+            while not stop.is_set():
+                try:
+                    await asyncio.wait_for(stop.wait(), timeout=HEARTBEAT_SEC)
+                    break
+                except asyncio.TimeoutError:
+                    pass
+                try:
+                    _, _, hb_creds = await register()
+                    if supervisor is not None:
+                        # 每拍按最新分配集合 reconcile：分片迁移 / 凭证增删 / 字段刷新 → 起停或重启源实例
+                        supervisor.reconcile(desired_source_creds(hb_creds))
+                except Exception as e:  # noqa: BLE001
+                    log.warning("[sokel] 心跳续约失败: %s", e)
+        finally:
+            # 优雅下线：通知平台立即标记 offline（秒级感知），而不是等心跳超时清扫（45s+）
+            if supervisor is not None:
+                supervisor.stop_all()
+            try:
+                await nc.publish(
+                    "sokel.unregister",
+                    json.dumps({"token": p.token, "instance_id": instance_id}).encode(),
+                )
+                await nc.flush()  # 确保下线通知先于断连送达
+            except Exception:  # noqa: BLE001
+                pass
+            log.info("[sokel] 已通知平台下线，退出")
+            await nc.drain()
+
+    async def _dispatch(self, p: Plugin, nc: Any, msg: Msg, files: NatsFiles, instance_id: str) -> None:
+        if not msg.reply:
+            return
+        try:
+            call = json.loads(msg.data)
+        except Exception:  # noqa: BLE001
+            await nc.publish(msg.reply, json.dumps({"error": "调用帧解不开"}).encode())
+            return
+        op = call.get("operation") or ""
+        tag = _trace_tag(call.get("trace") or {})
+
+        # 平台代收 webhook 的特殊帧：分发前拦截（老 SDK 没这段会走 unknown operation，
+        # 平台把它翻译成「插件未注册 webhook 处理器」）
+        if op == C.OP_WEBHOOK:
+            log.info("[sokel] ← webhook 入站%s", tag)
+            sctx = SourceCtx(
+                token=p.token,
+                publish=nc.publish,
+                valid_events=p.contract.event_ids(),
+                credential=call.get("credential"),
+                credential_id=call.get("credential_id", ""),
+                source_id="webhook",
+                files=files,
+            )
+            out = await p.handle_webhook(sctx, call.get("input") or {})
+            await nc.publish(msg.reply, json.dumps(out).encode())
+            return
+
+        headers = {INSTANCE_HEADER: instance_id}
+        started = time.monotonic()
+        log.info("[sokel] ← %s 开始%s", op, tag)
+        if p.contract.is_stream(op):
+            # 流式：逐帧发布到回复通道，末尾必发终止帧
+            async def publish_frame(frame: Dict[str, Any]) -> None:
+                await nc.publish(msg.reply, json.dumps(frame).encode(), headers=headers)
+
+            pending: List[asyncio.Task] = []
+
+            def sink(frame: Dict[str, Any]) -> None:
+                pending.append(asyncio.create_task(publish_frame(frame)))
+
+            try:
+                await p.dispatch(call, sink, files)
+                if pending:
+                    await asyncio.gather(*pending)
+                log.info("[sokel] ✓ %s 完成(%dms)%s", op, _ms(started), tag)
+            except Exception as e:  # noqa: BLE001
+                log.warning("[sokel] ✗ %s 失败(%dms)%s: %s", op, _ms(started), tag, e)
+                await publish_frame({"kind": "error", "text": str(e)})
+            await publish_frame({"kind": "end"})
+            return
+
+        try:
+            vars_ = await p.dispatch_buffered(call, files)
+        except Exception as e:  # noqa: BLE001
+            log.warning("[sokel] ✗ %s 失败(%dms)%s: %s", op, _ms(started), tag, e)
+            await nc.publish(msg.reply, json.dumps({"error": str(e)}).encode(), headers=headers)
+            return
+        log.info("[sokel] ✓ %s 完成(%dms)%s", op, _ms(started), tag)
+        await nc.publish(msg.reply, json.dumps(vars_).encode(), headers=headers)
+
+
+def _make_supervisor(p: Plugin, nc: Any, files: NatsFiles) -> SourceSupervisor:
+    """每个凭证一套源实例：ctx 绑定该凭证，trigger 自动回带其 credential_id。"""
+
+    def start(cred: CredEntry):
+        stopping = asyncio.Event()
+        tasks: List[asyncio.Task] = []
+        for src in p.sources:
+            sctx = SourceCtx(
+                token=p.token,
+                publish=nc.publish,
+                valid_events=p.contract.event_ids(),
+                credential=cred.fields,
+                credential_id=cred.id,
+                source_id=src.id,
+                board=p.board,
+                files=files,
+                stopping=stopping,
+            )
+            tasks.append(asyncio.create_task(_run_source(p, src, sctx, cred)))
+
+        def stop() -> None:
+            stopping.set()
+            for t in tasks:
+                t.cancel()
+            p.board.remove_cred(cred.id)
+
+        return stop
+
+    return SourceSupervisor(start)
+
+
+async def _run_source(p: Plugin, src: Any, sctx: SourceCtx, cred: CredEntry) -> None:
+    log.info("[sokel] 事件源「%s」启动（credential=%s）", src.id, cred.id or "(无凭证)")
+    p.board.set(src.id, cred.id, "running")
+    try:
+        await src.fn(sctx)
+        p.board.set_if_running(src.id, cred.id, "exited")
+    except asyncio.CancelledError:
+        raise  # reconcile 停止：状态已由 stop() 整体移除
+    except Exception as e:  # noqa: BLE001
+        log.exception("[sokel] 事件源「%s」退出（credential=%s）", src.id, cred.id or "(无凭证)")
+        p.board.set(src.id, cred.id, "error", str(e))
+
+
+def _resync(register: Any, supervisor: SourceSupervisor) -> None:
+    async def go() -> None:
+        try:
+            _, _, creds = await register()
+            supervisor.reconcile(desired_source_creds(creds))
+        except Exception as e:  # noqa: BLE001
+            log.warning("[sokel] 凭证变更 re-register 失败: %s", e)
+
+    asyncio.create_task(go())
+
+
+class _Debouncer:
+    """合并短窗内的多次触发（批量增删凭证只 re-register 一趟）。"""
+
+    def __init__(self, delay: float, fn: Any) -> None:
+        self._delay = delay
+        self._fn = fn
+        self._handle: Optional[asyncio.TimerHandle] = None
+
+    def trigger(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._handle is not None:
+            self._handle.cancel()
+        self._handle = loop.call_later(self._delay, self._fn)
+
+
+async def _connect_forever(opts: Dict[str, Any]) -> Any:
+    """broker 未就绪时挂起等它，而不是启动失败退出（与 Go 的 RetryOnFailedConnect 同义）。"""
+    while True:
+        try:
+            return await nats.connect(**opts)
+        except Exception as e:  # noqa: BLE001
+            log.warning("[sokel] 连接平台失败（%s），%ds 后重试…", e, RETRY_SEC)
+            await asyncio.sleep(RETRY_SEC)
+
+
+async def discover(endpoint: str, token: str) -> str:
+    """统一 https 端点 → 经平台 /connect-info 发现真实承载地址。
+
+    直填 nats:// / tls:// 时跳过发现（本地开发 / 离线场景）。
+    """
+    ep = (endpoint or "").strip()
+    if ep.startswith("nats://") or ep.startswith("tls://"):
+        return ep
+    if not (ep.startswith("http://") or ep.startswith("https://")):
+        raise ValueError(f"端点 {endpoint!r} 不合法：应为平台地址（https://…）或 nats://")
+    url = ep.rstrip("/") + "/api/v1/connect-info"
+    info = await asyncio.to_thread(_http_get_json, url, token)
+    target = (info.get("transports") or {}).get("nats")
+    if not target:
+        raise RuntimeError("平台未提供可用承载（connect-info.transports 为空）")
+    return target
+
+
+def _http_get_json(url: str, token: str) -> Dict[str, Any]:
+    import urllib.request
+
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(req, timeout=8) as resp:  # noqa: S310
+        return json.loads(resp.read().decode())
+
+
+def stable_instance_id(token: str) -> str:
+    """副本的稳定身份：重启复用，否则平台侧每次重启都多出一行永远 offline 的幽灵实例。
+
+    1) SOKEL_INSTANCE_ID；2) 工作目录里按 token 指纹命名的落盘文件；3) 落盘失败 → host-pid。
+    """
+    if v := env.get("INSTANCE_ID"):
+        return v
+    import hashlib
+    import secrets
+
+    name = ".sokel-instance-id"
+    if token:
+        name += "." + hashlib.sha256(token.encode()).hexdigest()[:8]
+    try:
+        with open(name, "r", encoding="utf-8") as fh:
+            if existing := fh.read().strip():
+                return existing
+    except OSError:
+        pass
+    host = socket.gethostname()
+    ident = f"{host}-{secrets.token_hex(4)}"
+    try:
+        with open(name, "w", encoding="utf-8") as fh:
+            fh.write(ident + "\n")
+    except OSError:
+        return f"{host}-{os.getpid()}"
+    return ident
+
+
+def _trace_tag(trace: Dict[str, str]) -> str:
+    parts = [
+        f"{label}={trace[key]}"
+        for key, label in (("run_id", "run"), ("workflow_id", "wf"), ("node_id", "node"))
+        if trace.get(key)
+    ]
+    return f" [{' '.join(parts)}]" if parts else ""
+
+
+def _ms(started: float) -> int:
+    return int((time.monotonic() - started) * 1000)
+
+
+def _cb(fn: Any) -> Any:
+    async def cb(*_args: Any, **_kw: Any) -> None:
+        fn()
+
+    return cb

sokel/plugin.py

@@ -0,0 +1,276 @@
+"""Plugin：注册表 + 分发。传输无关——NATS 那一层只负责收发字节。
+
+分发这段是**最值得单测的一段**（未知操作、流式与非流式的回复形态、webhook 帧的拦截），
+所以它一行都不碰 NATS：测试塞一个假 sink 就能跑完整条路径。
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import traceback
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from . import contract as C
+from .auth import AuthChallenge, AuthState
+from .contract import Contract
+from .events import Source, SourceCtx, StateBoard
+from .runtime import BufferSink, Ctx, Emitter, FileRuntime
+from .webhook import WebhookRequest, WebhookResponse
+
+log = logging.getLogger("sokel")
+
+Invoke = Callable[[Ctx, Dict[str, Any], Emitter], Awaitable[None]]
+
+
+class Plugin:
+    """一个插件实例。
+
+    契约来自 sokel-gen 从 sokel.yaml 生成的 CONTRACT —— 声明与实现分离，
+    这里只认「操作 id → 实现」。
+    """
+
+    def __init__(
+        self,
+        contract: Optional[Dict[str, Any]] = None,
+        name: str = "",
+        endpoint: str = "",
+        token: str = "",
+        version: str = "",
+    ) -> None:
+        from . import env
+
+        self.contract = Contract(contract)
+        self.name = name or self.contract.get("name") or "sokel-plugin"
+        self.endpoint = endpoint or env.get_or("ENDPOINT", "http://localhost:8088")
+        self.token = token or env.get("TOKEN")
+        # 版本三档：显式参数 > 契约里声明的（sokel.yaml 的 plugin.version）> 环境变量 > 兜底。
+        # 实例列表的「版本」列靠它回答「线上跑的是不是我刚发的那版」。
+        self.version = version or self.contract.get("version") or env.get("VERSION") or "sdk-python"
+        self._ops: Dict[str, Invoke] = {}
+        self._sources: List[Source] = []
+        self._webhook: Optional[Callable[[SourceCtx, WebhookRequest], Any]] = None
+        self.board = StateBoard()
+        self._managed = False
+
+    # —— 注册 ——
+
+    def register(self, op_id: str, fn: Invoke) -> None:
+        """低阶注册：fn(ctx, input_dict, emitter)。生成的 on_xxx 就是它的类型化外壳。"""
+        if op_id not in ("",) and self.contract.operation(op_id) is None and "." not in op_id:
+            raise ValueError(
+                f"操作 {op_id!r} 不在契约里 —— 先在 sokel.yaml 的 operations 声明它，再重新生成"
+            )
+        if op_id in self._ops:
+            raise ValueError(f"操作 {op_id!r} 重复注册")
+        self._ops[op_id] = fn
+
+    def register_source(self, id: str, label: str, fn: Callable[[SourceCtx], Awaitable[None]]) -> None:
+        """注册常驻事件源；run() 时每个「源 × 凭证」起一个 task。"""
+        self._sources.append(Source(id, label, fn))
+
+    def register_webhook(self, fn: Callable[[SourceCtx, WebhookRequest], Any]) -> None:
+        """注册 webhook 处理器（一个插件一个：按 header / path 自行分流上游事件类型）。"""
+        self._webhook = fn
+        # 能力位不靠自报靠事实：注册了处理器就是支持，作者忘声明不该让入口按钮消失
+        caps = dict(self.contract.get(C.KEY_CAPABILITIES) or {})
+        caps[C.CAP_WEBHOOK] = True
+        self.contract.set(C.KEY_CAPABILITIES, caps)
+
+    def register_auth(
+        self,
+        start: Optional[Callable[[Ctx], Any]] = None,
+        poll: Optional[Callable[[Ctx, str], Any]] = None,
+        submit: Optional[Callable[[Ctx, str, str], Any]] = None,
+    ) -> None:
+        """挂上认证流的实现。形态（qr / input / oauth）在 sokel.yaml 里声明，这里只给实现。
+
+        kind=oauth 的 start/poll 由**平台代答**（client_secret 在平台手里，插件构造不出
+        同意页地址），所以那种插件一个 handler 都不用写。
+        """
+        declared = self.contract.get(C.KEY_AUTH_FLOW) or {}
+        steps = list(declared.get("steps") or [])
+        if start is not None:
+            self._require_step(steps, "start")
+
+            async def _start(ctx: Ctx, raw: Dict[str, Any], out: Emitter) -> None:
+                ch = await _maybe_await(start(ctx))
+                if ch is None:
+                    raise RuntimeError("认证流 start 未返回挑战")
+                if not isinstance(ch, AuthChallenge):
+                    raise TypeError("认证流 start 必须返回 AuthChallenge")
+                auth_id = ch.auth_id or _new_auth_id()
+                out.vars(
+                    {
+                        "auth_id": auth_id,
+                        "challenge": {
+                            "kind": ch.kind or declared.get("kind", ""),
+                            "qr_image": ch.qr_image,
+                            "prompt": ch.prompt,
+                        },
+                        "expires_in": ch.expires_in,
+                    }
+                )
+
+            self._ops[C.OP_AUTH_START] = _start
+        if poll is not None:
+            self._require_step(steps, "poll")
+
+            async def _poll(ctx: Ctx, raw: Dict[str, Any], out: Emitter) -> None:
+                st = await _maybe_await(poll(ctx, raw.get("auth_id") or ""))
+                if st is None:
+                    st = AuthState()
+                if not isinstance(st, AuthState):
+                    raise TypeError("认证流 poll 必须返回 AuthState")
+                vars_: Dict[str, Any] = {"status": st.status}
+                # session 只在 confirmed 时带出去；pending 时带一个 null 会让平台反复覆写凭证行
+                if st.status == "confirmed" and st.session:
+                    vars_["session"] = st.session
+                out.vars(vars_)
+
+            self._ops[C.OP_AUTH_POLL] = _poll
+        if submit is not None:
+            self._require_step(steps, "submit")
+
+            async def _submit(ctx: Ctx, raw: Dict[str, Any], out: Emitter) -> None:
+                await _maybe_await(submit(ctx, raw.get("auth_id") or "", raw.get("input") or ""))
+                out.vars({"ok": True})
+
+            self._ops[C.OP_AUTH_SUBMIT] = _submit
+
+    def _require_step(self, steps: List[str], step: str) -> None:
+        if step not in steps:
+            raise ValueError(
+                f"契约里的认证流没有 {step!r} 这一步（当前 {steps or '未声明'}）——"
+                "步骤由 credential.auth.kind 定死，实现多于声明就是一份永远不会被调用的代码"
+            )
+
+    def set_capabilities(self, caps: Dict[str, bool]) -> None:
+        """声明本插件支持/不支持哪些**可选**能力（同一个操作做到什么程度）。"""
+        merged = dict(self.contract.get(C.KEY_CAPABILITIES) or {})
+        merged.update(caps)
+        self.contract.set(C.KEY_CAPABILITIES, merged)
+
+    # —— 注册握手载荷 ——
+
+    def register_payload(self, instance_id: str, host: str, started_at: str) -> Dict[str, Any]:
+        """注册 / 心跳的载荷（协议 §3）。
+
+        单独一个方法是为了能测：**声明了却没上报**是这套自报机制最典型的静默失效——
+        插件侧一切正常、平台侧什么也没发生，作者只能对着一个没反应的界面排查。
+        """
+        from . import env
+
+        body: Dict[str, Any] = {
+            "token": self.token,
+            "instance_id": instance_id,
+            "host": host,
+            # 进程启动时刻：注册与每拍心跳重发同一值，平台据此区分「重新上线的新副本」与「一直活着的老副本」
+            "started_at": started_at,
+            "version": self.version,
+            "transport": "nats",
+            "managed": self._managed,
+        }
+        if region := env.get("REGION"):
+            body["region"] = region
+        body.update(self.contract.payload())
+        if self._sources:
+            body["source_states"] = self.board.snapshot()
+        return body
+
+    # —— 分发 ——
+
+    def find(self, op_id: str) -> Optional[Invoke]:
+        fn = self._ops.get(op_id)
+        if fn is not None:
+            return fn
+        # 单操作插件：operation 省略（或对不上）时默认唯一操作，与 Go SDK 同一条兜底
+        business = [k for k in self._ops if "." not in k]
+        if len(business) == 1:
+            return self._ops[business[0]]
+        return None
+
+    async def dispatch(
+        self,
+        call: Dict[str, Any],
+        sink: Callable[[Dict[str, Any]], None],
+        files: Optional[FileRuntime] = None,
+    ) -> None:
+        """跑一次调用，把各帧交给 sink。异常原样抛出，由传输层翻成 error 帧 / error 回复。"""
+        op_id = call.get("operation") or ""
+        fn = self.find(op_id)
+        if fn is None:
+            raise LookupError(f"unknown operation {op_id!r}")
+        ctx = Ctx(credential=call.get("credential"), trace=call.get("trace"), files=files)
+        await fn(ctx, call.get("input") or {}, Emitter(sink))
+
+    async def dispatch_buffered(
+        self, call: Dict[str, Any], files: Optional[FileRuntime] = None
+    ) -> Dict[str, Any]:
+        """非流式：缓冲各帧，合并 variables 作为单次回复。"""
+        sink = BufferSink()
+        await self.dispatch(call, sink, files)
+        return sink.vars
+
+    async def handle_webhook(self, sctx: SourceCtx, frame: Dict[str, Any]) -> Dict[str, Any]:
+        """处理一帧 __webhook__。应答带 events 计数——平台的 webhook 面板靠它回答
+        「请求到了但为什么没起工作流」这一问。"""
+        if self._webhook is None:
+            return {"status": 0, "error": "插件未注册 webhook 处理器"}
+        req = WebhookRequest.from_frame(frame or {})
+        counted = _CountingCtx(sctx)
+        try:
+            resp = await _maybe_await(self._webhook(counted, req))
+        except Exception as e:  # noqa: BLE001 —— 上游要的是一个明确的失败应答，不是插件进程退出
+            log.exception("[sokel] webhook 处理失败")
+            return {"status": 0, "error": f"{e}"}
+        if resp is None:
+            resp = WebhookResponse()
+        if not isinstance(resp, WebhookResponse):
+            return {"status": 0, "error": "webhook 处理器必须返回 WebhookResponse"}
+        log.info("[sokel] ✓ webhook 处理完成（status=%s events=%d）", resp.status, counted.n)
+        return resp.to_frame(counted.n)
+
+    # —— 运行 ——
+
+    async def run(self) -> None:
+        """连接平台、注册、心跳、分发调用。阻塞到收到 SIGINT/SIGTERM。"""
+        from .nats_transport import NatsTransport
+
+        await NatsTransport().run(self)
+
+    @property
+    def sources(self) -> List[Source]:
+        return self._sources
+
+    @property
+    def has_webhook(self) -> bool:
+        return self._webhook is not None
+
+
+class _CountingCtx:
+    """数 trigger 成功次数（webhook 应答的 events 字段）。"""
+
+    def __init__(self, inner: SourceCtx) -> None:
+        self._inner = inner
+        self.n = 0
+
+    def __getattr__(self, item: str) -> Any:
+        return getattr(self._inner, item)
+
+    async def trigger(self, event: str, event_id: str, payload: Any) -> None:
+        await self._inner.trigger(event, event_id, payload)
+        self.n += 1
+
+
+async def _maybe_await(v: Any) -> Any:
+    """handler 可以是 async def，也可以是普通函数——两种都收。"""
+    if inspect.isawaitable(v):
+        return await v
+    return v
+
+
+def _new_auth_id() -> str:
+    import time
+
+    return f"auth_{int(time.time() * 1e9)}"