msp-py 0.1.0a1__py3-none-any.whl

msp/__init__.py

@@ -0,0 +1,97 @@
+"""
+MSP — Model Sensing Protocol.
+
+一个以「节点」为中心的分布式 AI 通讯协议。
+Everything is a node. Everything is a signal. Every layer is extensible.
+
+常用入口：
+
+    from msp import MSPNode, Preset
+
+    node = MSPNode("my_node", preset=Preset.FULL_PEER)
+
+    @node.tool("get_weather")
+    def get_weather(location: str) -> dict: ...
+
+    node.start()
+"""
+
+# 版本号与 pyproject.toml 的 [project] version 保持同步。
+__version__ = "0.1.0a1"
+
+# --- 节点与预设 ---------------------------------------------------------
+from .core.node import MSPNode
+from .core.preset import Preset
+from .core.peer import Peer
+from .core.remote_tools import RemoteTool, ToolView
+
+# --- 核心数据结构 --------------------------------------------------------
+from .core.signal import Signal, SignalType
+from .core.manifest import Manifest
+from .core.content import (
+    TextContent,
+    ImageContent,
+    AudioContent,
+    EmbeddedResource,
+    ResourceLink,
+    BlobRef,
+    ToolResult,
+    ToolError,
+    block_from_dict,
+    blocks_from_list,
+)
+
+# --- 通讯模式 ------------------------------------------------------------
+from .patterns.base import PatternHandler
+from .patterns.multi_round import MultiRoundHandler
+from .patterns.task import TaskHandler, TaskSnapshot, Artifact, TaskError, TaskCanceled
+
+# --- 发现 / 宣告 / 传输 --------------------------------------------------
+from .discovery.base import Discovery, Endpoint
+from .presence.base import Presence
+from .transport.base import Transport, Connection, ConnectionClosed
+from .transport.registry import TransportRegistry
+from .transport.tcp import TCPTransport
+from .transport.websocket import WebSocketTransport
+from .transport.uds import UDSTransport
+
+__all__ = [
+    "__version__",
+    # 节点与预设
+    "MSPNode",
+    "Preset",
+    "Peer",
+    # 核心数据结构
+    "Signal",
+    "SignalType",
+    "Manifest",
+    "TextContent",
+    "ImageContent",
+    "AudioContent",
+    "EmbeddedResource",
+    "ResourceLink",
+    "BlobRef",
+    "ToolResult",
+    "ToolError",
+    "block_from_dict",
+    "blocks_from_list",
+    # 通讯模式
+    "PatternHandler",
+    "MultiRoundHandler",
+    "TaskHandler",
+    "TaskSnapshot",
+    "Artifact",
+    "TaskError",
+    "TaskCanceled",
+    # 发现 / 宣告 / 传输
+    "Discovery",
+    "Endpoint",
+    "Presence",
+    "Transport",
+    "Connection",
+    "ConnectionClosed",
+    "TransportRegistry",
+    "TCPTransport",
+    "WebSocketTransport",
+    "UDSTransport",
+]

msp/core/__init__.py

@@ -0,0 +1 @@
+"""core — 核心数据与入口：Signal、Manifest、ContentBlock、Preset、MSPNode。"""

msp/core/content.py

@@ -0,0 +1,270 @@
+"""
+ContentBlock — 工具返回结果的内容块。
+
+兼容 MCP 的 content 数组结构：
+    - text:          纯文本
+    - image:         图片（Base64 内嵌）
+    - audio:         音频（Base64 内嵌）
+    - resource:      嵌入资源（文本或二进制）
+    - resource_link: 资源引用（URI）
+    - blob_ref:      MSP 扩展，指向独立 blob 通道
+
+所有内容块共享 to_dict() / from_dict() 接口。
+未知类型的块原样返回，遵循宽容读取原则。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ----------------------------------------------------------------------
+# 内容块定义
+# ----------------------------------------------------------------------
+
+@dataclass
+class TextContent:
+    text: str
+    annotations: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {"type": "text", "text": self.text}
+        if self.annotations:
+            d["annotations"] = self.annotations
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TextContent":
+        return cls(
+            text=d.get("text", ""),
+            annotations=d.get("annotations", {}),
+        )
+
+
+@dataclass
+class ImageContent:
+    data: str              # Base64 编码的图片字节
+    mime_type: str         # "image/png" / "image/jpeg" / ...
+    annotations: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {"type": "image", "data": self.data, "mimeType": self.mime_type}
+        if self.annotations:
+            d["annotations"] = self.annotations
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ImageContent":
+        return cls(
+            data=d.get("data", ""),
+            mime_type=d.get("mimeType", ""),
+            annotations=d.get("annotations", {}),
+        )
+
+
+@dataclass
+class AudioContent:
+    data: str              # Base64 编码的音频字节
+    mime_type: str         # "audio/wav" / "audio/mp3" / ...
+    annotations: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {"type": "audio", "data": self.data, "mimeType": self.mime_type}
+        if self.annotations:
+            d["annotations"] = self.annotations
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AudioContent":
+        return cls(
+            data=d.get("data", ""),
+            mime_type=d.get("mimeType", ""),
+            annotations=d.get("annotations", {}),
+        )
+
+
+@dataclass
+class EmbeddedResource:
+    """嵌入资源：文本或二进制直接内嵌。"""
+
+    uri: str
+    mime_type: str = ""
+    text: str = ""         # 文本资源用 text
+    blob: str = ""         # 二进制资源用 blob（Base64）
+    annotations: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {
+            "type": "resource",
+            "resource": {
+                "uri": self.uri,
+                "mimeType": self.mime_type,
+            },
+        }
+        if self.text:
+            d["resource"]["text"] = self.text
+        if self.blob:
+            d["resource"]["blob"] = self.blob
+        if self.annotations:
+            d["annotations"] = self.annotations
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "EmbeddedResource":
+        r = d.get("resource", {})
+        return cls(
+            uri=r.get("uri", ""),
+            mime_type=r.get("mimeType", ""),
+            text=r.get("text", ""),
+            blob=r.get("blob", ""),
+            annotations=d.get("annotations", {}),
+        )
+
+
+@dataclass
+class ResourceLink:
+    """资源引用：只给 URI，内容由对端自行获取。"""
+
+    uri: str
+    name: str = ""
+    mime_type: str = ""
+    description: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "resource_link",
+            "uri": self.uri,
+            "name": self.name,
+            "mimeType": self.mime_type,
+            "description": self.description,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ResourceLink":
+        return cls(
+            uri=d.get("uri", ""),
+            name=d.get("name", ""),
+            mime_type=d.get("mimeType", ""),
+            description=d.get("description", ""),
+        )
+
+
+@dataclass
+class BlobRef:
+    """MSP 扩展：指向独立 blob 通道的引用。
+
+    大文件走独立的 blob_chunk 信号流，不塞进 tool_result。
+    """
+
+    blob_id: str
+    mime_type: str
+    size: int = 0
+    checksum: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "blob_ref",
+            "blobId": self.blob_id,
+            "mimeType": self.mime_type,
+            "size": self.size,
+            "checksum": self.checksum,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BlobRef":
+        return cls(
+            blob_id=d.get("blobId", ""),
+            mime_type=d.get("mimeType", ""),
+            size=d.get("size", 0),
+            checksum=d.get("checksum", ""),
+        )
+
+
+# ----------------------------------------------------------------------
+# 工厂：从字典构造内容块
+# ----------------------------------------------------------------------
+
+_BLOCK_TYPES = {
+    "text": TextContent,
+    "image": ImageContent,
+    "audio": AudioContent,
+    "resource": EmbeddedResource,
+    "resource_link": ResourceLink,
+    "blob_ref": BlobRef,
+}
+
+
+def block_from_dict(d: dict):
+    """从字典解析内容块。
+
+    未知类型原样返回（宽容读取）。
+    """
+    t = d.get("type")
+    cls = _BLOCK_TYPES.get(t)
+    if cls is None:
+        return d
+    return cls.from_dict(d)
+
+
+def blocks_from_list(items: list) -> list:
+    """批量解析内容块。
+
+    非 dict 元素原样保留：与「未知类型原样保留」同一口径，不能让一个
+    异常元素（字符串 / 数字）调 .get 抛错带崩整份结果。
+    """
+    return [
+        item if not isinstance(item, dict) else block_from_dict(item)
+        for item in items
+    ]
+
+# ----------------------------------------------------------------------
+# ToolResult：工具调用的完整结果
+# ----------------------------------------------------------------------
+
+class ToolError(Exception):
+    """工具执行失败。"""
+    pass
+
+
+@dataclass
+class ToolResult:
+    """工具调用的完整结果。
+
+    简单场景：
+        result = node.call(...)
+        data = result.unwrap()          # 直接拿 dict
+
+    丰富场景：
+        for block in result.content:
+            if block["type"] == "image":
+                show_image(block["data"])
+
+    错误处理：
+        if result.is_error:
+            print(result.error)
+    """
+
+    content: list = field(default_factory=list)
+    structured: Any = None
+    error: str = ""
+
+    @property
+    def is_error(self) -> bool:
+        return bool(self.error)
+
+    def unwrap(self):
+        """返回结构化数据。错误时抛异常。"""
+        if self.error:
+            raise ToolError(self.error)
+        return self.structured
+
+    def text(self) -> str:
+        """把所有 text 块拼起来。"""
+        parts = []
+        for block in self.content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                parts.append(block.get("text", ""))
+            elif hasattr(block, "text"):
+                parts.append(block.text)
+        return "\n".join(parts)

msp/core/exposure.py

@@ -0,0 +1,90 @@
+"""部署姿态：「监听是否暴露到网络」的判定与启动期告警。
+
+与 C++ 侧的 ``core/exposure.hpp`` 同构：判定与文案都是**纯函数**，因此测试可以直接
+断言文本，而节点只负责把结果打到日志里。
+
+为什么需要它：监听地址与授权是**分开配置**的两件事。把门开到网络上却以为自己还
+关着，或者反过来以为已经开了其实只绑了 localhost——这两类误解都**不会报错**，只是
+行为与预期不符，属于最难查的一类问题。C++ 侧已因此加了这个告警，Python 侧原先没有。
+
+三档姿态与 C++ 对齐（授权层落地后，原先那句「本实现没有授权层」不再成立，故改为按
+授权表的实际姿态分档）。
+"""
+
+from __future__ import annotations
+
+# is_local_host 的家在 grants.py——「本机整张表绕过」与「这个 host 是不是本机」是同一件
+# 事（security.md §3.5）。这里复用它，避免同一条判定在两处各写一遍；对外仍从这里可见。
+from .grants import (
+    grants_is_default,
+    grants_is_permissive,
+    grants_summary,
+    is_local_host,
+)
+
+__all__ = ["is_local_host", "exposed_bindings", "exposure_warning"]
+
+
+def exposed_bindings(listen_result: dict) -> list:
+    """从 ``listen_all()`` 的返回值里挑出**已暴露到网络**的后端。
+
+    返回形如 ``["tcp=0.0.0.0"]``；未暴露时为空列表。
+
+    判定只看**实际绑定到的地址**（本端事实），不看配置写了什么、更不看对端自报了
+    什么。不计入暴露的三种情形：没有 ``host`` 键（uds 是本机专用后端）、``host``
+    为空（后端走自己的默认值）、``host`` 属于本机。
+    """
+    exposed = []
+    if not isinstance(listen_result, dict):
+        return exposed
+    for ttype, info in listen_result.items():
+        if not isinstance(info, dict):
+            continue
+        address = info.get("address")
+        if not isinstance(address, dict):
+            continue
+        if "host" not in address:
+            continue  # uds 之类没有 host
+        host = address.get("host") or ""
+        if not isinstance(host, str) or not host:
+            continue  # 空 host = 后端默认值（localhost）
+        if is_local_host(host):
+            continue
+        exposed.append(f"{ttype}={host}")
+    return exposed
+
+
+def exposure_warning(exposed: list, grants=None) -> str:
+    """启动期告警文本；**不需要告警时返回空串**（调用方据此决定是否打日志）。
+
+    与 C++ 侧同一组三档：
+
+        - 未暴露 → 空串；
+        - 暴露 + 授权表是**默认姿态** → 告警：连得上但什么都做不了（最容易被误解的一档，
+          表现为「对端调不动任何工具」，很容易被当成程序坏了）；
+        - 暴露 + 授权表**放行了权限** → 告警：网络可达者都能行使这些权限，请确认；
+        - 暴露 + 一张**显式且很窄**的表 → 空串（想清楚了的部署不该被反复告诫，
+          否则告警会变成噪声，真出问题时反而被忽略）。
+    """
+    if not exposed:
+        return ""
+    where = "监听已暴露到网络（" + "、".join(exposed) + "）"
+
+    if grants_is_default(grants):
+        return (
+            where
+            + "，但授权表是**默认姿态**（对非本机对端全拒，只保留应答通道）："
+            "网络对端能连上，却调不动任何工具、也收不到任何广播。"
+            "要跨机使用请显式配置 config[\"grants\"]；只在本机使用请把监听地址留在"
+            " 127.0.0.1（config[\"listen\"] 不写即为默认）。"
+        )
+
+    if grants_is_permissive(grants):
+        return (
+            where
+            + "，且授权表**放行了权限**："
+            + grants_summary(grants)
+            + "。网络可达者都能行使这些权限，请确认这是你要的。"
+        )
+
+    return ""

msp/core/grammar.py

@@ -0,0 +1,62 @@
+"""命名文法校验。
+
+**权威源**：``schema/2026-10-10/msp.yaml`` 的 ``grammars`` 段（对应
+``docs/spec/README.md`` §5.3）。这里逐字照抄那几条正则并注明出处——正则只该有**一份**
+真相，两处各写一遍迟早会漂移。
+
+与 C++ 侧的 ``core/grammar.hpp`` 同构。
+
+为什么需要它：MCP 允许的工具名是 ``A-Za-z0-9_-.`` 且最长 128 字符（均为 SHOULD），
+而 MSP 要求 ``^[a-z0-9_-]+$``（MUST，无大写、无点号）。逐字注册远端名会产出**违反 MSP
+自身文法**的工具名——本地字典查表仍能命中，但清单与其他实现无法按规范解析
+（规范 ``interop.md`` §9 G11）。
+"""
+
+from __future__ import annotations
+
+import re
+
+# 逐字来自 schema/2026-10-10/msp.yaml 的 grammars 段
+_NODE_ID = re.compile(r"^[a-z0-9_-]+$")
+_PATH = re.compile(r"^[a-z0-9_-]+(\.[a-z0-9_-]+)*$")
+_TOOL_NAME = re.compile(r"^[a-z0-9_-]+$")
+# pattern_id **恰好**一个斜杠：只有 `msp/task` 这种形态合法，
+# `msp` 与 `msp/task/x` 都不合法（正则本身就把这条钉住了）
+_PATTERN_ID = re.compile(r"^[a-z0-9_-]+/[a-z0-9_-]+$")
+# 状态是闭集；注意 `input-required` 用**连字符**（对齐 A2A TaskState），
+# 而信号类型 `input_required` 用**下划线**——两者不得互换、不得归一化。
+_TASK_STATE = re.compile(
+    r"^(submitted|working|input-required|completed|failed|canceled)$"
+)
+
+
+def _matches(pattern: re.Pattern, value) -> bool:
+    # 非字符串一律判否，而不是抛异常：校验器的调用方通常在处理外部数据。
+    # 用 fullmatch 而不是 match + `$`：`$` 还能匹配串尾换行之前，
+    # "node_a\n" 会被 `^[a-z0-9_-]+$` 错误放行。
+    return isinstance(value, str) and pattern.fullmatch(value) is not None
+
+
+def is_valid_node_id(value) -> bool:
+    """节点 id：``^[a-z0-9_-]+$``。"""
+    return _matches(_NODE_ID, value)
+
+
+def is_valid_path(value) -> bool:
+    """信号路径：``^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$``（点分段，无空段）。"""
+    return _matches(_PATH, value)
+
+
+def is_valid_tool_name(value) -> bool:
+    """工具名：``^[a-z0-9_-]+$``（比 MCP 更严：无大写、无点号）。"""
+    return _matches(_TOOL_NAME, value)
+
+
+def is_valid_pattern_id(value) -> bool:
+    """模式 id：``^[a-z0-9_-]+/[a-z0-9_-]+$``（恰好一个斜杠）。"""
+    return _matches(_PATTERN_ID, value)
+
+
+def is_valid_task_state(value) -> bool:
+    """任务状态：闭集，且 ``input-required`` 用连字符。"""
+    return _matches(_TASK_STATE, value)