ghoshell-moss 0.1.0a0__py3-none-any.whl

ghoshell_moss/README.md

@@ -0,0 +1,7 @@
+# 目录介绍
+
+- core: ghoshell moss 的核心功能模块
+- message: 兼容性的模型消息协议. 暂时放到 ghoshell-moss 库, 未来可能迁出
+- transports: 通过 provider -> proxy 范式, 跨进程的构建 channel 之间的双工通讯.
+- compatible: 兼容性模块, 用来兼容行业生态. 比如 claude mcp 和 claude skills.
+- channels: ghoshell-moss 库认为需要开箱自带的 channel 实现.

ghoshell_moss/__init__.py

@@ -0,0 +1,15 @@
+from ghoshell_container import (
+    Container,
+    IoCContainer,
+    get_container,
+    set_container,
+)
+
+from ghoshell_moss.core import *
+from ghoshell_moss.message import *
+
+"""
+Ghoshell MOSS 库的 facade, 用来存放最常用的类库引用.
+
+考虑只对外暴露最基础的常用函数. 
+"""

ghoshell_moss/channels/README.md

@@ -0,0 +1,5 @@
+# 关于 channels
+
+本目录实现 MOSS 协议认为必要的类型 Channel. 主要是业务 channel, 通常基于 PyChannel 实现.
+
+Beta 版本会包含部分.

ghoshell_moss/channels/__init__.py

@@ -0,0 +1 @@
+

ghoshell_moss/channels/mac_channel.py

@@ -0,0 +1,99 @@
+import asyncio
+from typing import Any, Optional
+
+from ghoshell_moss.core import PyChannel
+
+__all__ = ["new_mac_control_channel"]
+
+
+class JXAError(Exception):
+    """JXA 执行错误"""
+
+    pass
+
+
+async def run(*, timeout: Optional[float] = 30.0, text__: str = "") -> Any:
+    """
+    在当前 MAC 上执行一个 JXA 函数, 子进程阻塞到执行完毕.
+    如果你需要与 mac 应用做交互, 又没有别的手段时, 可以用这个办法.
+
+    :param timeout: 过期时间.
+    :param text__: jxa 脚本的源码.
+
+    CTML 使用举例:
+        <chan_name:run><![CDATA[
+        (function() {
+            'use strict';
+
+            // 1. 使用 Bundle Identifier 获取日历应用对象
+            var Calendar = Application('com.apple.iCal');
+
+            // 2. 检查是否正在运行
+            var wasRunning = Calendar.running();
+
+            // 3. 尝试激活 (如果没有运行，这会启动它)
+            Calendar.activate();
+
+            // 4. 等待一小会儿，让系统处理激活请求
+            delay(0.5); // JXA 中的 delay 函数，单位秒
+
+            // 5. 再次检查运行状态和窗口状态
+            var isRunning = Calendar.running();
+            var windowCount = Calendar.windows ? Calendar.windows.length : 0;
+
+            // 6. 返回结构化的调试信息
+            return {
+                success: true,
+                action: 'activate_calendar',
+                bundleId: 'com.apple.iCal',
+                wasRunning: wasRunning,
+                isRunning: isRunning,
+                windowCount: windowCount,
+                timestamp: Date.now()
+            };
+        })();
+        ]]></chan_name:run>
+
+    :return: 返回操作结果. 你必须等操作结果到手后, 才能知道它运行的效果如何.
+    """
+    cmd = ["osascript", "-l", "JavaScript", "-"]
+
+    process = None
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+
+        stdout, stderr = await asyncio.wait_for(process.communicate(input=text__.encode("utf-8")), timeout=timeout)
+
+        if process.returncode != 0:
+            error_msg = stderr.decode("utf-8", errors="replace").strip()
+            raise JXAError(f"JXA 执行失败 (code: {process.returncode}): {error_msg}")
+
+        output = stdout.decode("utf-8", errors="replace").strip()
+
+        # 尝试解析 JSON
+        return output
+
+    except asyncio.TimeoutError:
+        if process and process.returncode is None:
+            process.kill()
+            await process.wait()
+        raise
+
+
+def new_mac_control_channel(
+    name: str = "mac_control",
+    description: str = "使用 jxa 语法来操作当前所在 mac",
+) -> PyChannel:
+    """
+    创建一个控制 mac 的 channel.
+    """
+    mac_jxa_channel = PyChannel(
+        name=name,
+        description=description,
+        block=True,
+    )
+
+    mac_jxa_channel.build.command()(run)
+    return mac_jxa_channel

ghoshell_moss/cli/README.md

@@ -0,0 +1,5 @@
+# 关于 CLI
+
+本目录存放项目相关的常用 cli 工具.
+
+alpha 版本一个都木有.

ghoshell_moss/cli/__init__.py

@@ -0,0 +1 @@
+

ghoshell_moss/compatible/README.md

@@ -0,0 +1,7 @@
+# 关于 Compatible
+
+这里是 MOSS 架构兼容其它实现的相关类库放置.
+预计要兼容:
+
+- anthropic mcp: 将 mcp 的工具调用转化为 command.
+- anthropic skill: 将 skill 的整套机制, 转化为单一的 channel.

ghoshell_moss/compatible/__init__.py

@@ -0,0 +1 @@
+

ghoshell_moss/compatible/mcp_channel/__init__.py

@@ -0,0 +1,3 @@
+from ghoshell_moss.compatible.mcp_channel.mcp_channel import MCPChannel
+
+__all__ = ["MCPChannel"]

ghoshell_moss/compatible/mcp_channel/mcp_channel.py

@@ -0,0 +1,468 @@
+import json
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any, Generic, Optional, TypeVar
+
+from ghoshell_moss import CommandError, CommandErrorCode
+from ghoshell_moss.compatible.mcp_channel.utils import mcp_call_tool_result_to_message
+from ghoshell_moss.core.concepts.states import MemoryStateStore, StateStore
+
+try:
+    import mcp
+    from mcp import types
+except ImportError:
+    raise ImportError("Could not import mcp. Please install ghoshell-moss[mcp].")
+
+import asyncio
+
+from ghoshell_common.helpers import uuid
+from ghoshell_container import Container, IoCContainer
+
+from ghoshell_moss.core.concepts.channel import Builder, Channel, ChannelBroker, ChannelMeta
+from ghoshell_moss.core.concepts.command import (
+    Command,
+    CommandDeltaType,
+    CommandMeta,
+    CommandTask,
+    CommandWrapper,
+)
+
+R = TypeVar("R")  # 泛型结果类型
+
+
+class MCPChannelBroker(ChannelBroker, Generic[R]):
+    """MCPChannel的运行时客户端，负责对接MCP服务"""
+
+    MCP_CONTAINER_TYPES: list[str] = ["array", "object"]
+
+    MCP_PY_TYPES_TRANS_TABLE: dict[str, str] = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "list",
+        "object": "dict",
+    }
+
+    COMMAND_DELTA_PARAMTER: str = f"{CommandDeltaType.TEXT.value}:str"
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        mcp_client: mcp.ClientSession,
+        container: Optional[IoCContainer] = None,
+    ):
+        self._name = name
+        self._mcp_client: Optional[mcp.ClientSession] = mcp_client  # MCP客户端实例
+        self._commands: dict[str, Command] = {}  # 映射后的Mosshell Command
+        self._meta: Optional[ChannelMeta] = None  # Channel元信息
+        self._running = False  # 运行状态标记
+        self._logger: logging.Logger | None = None
+        self._id = uuid()
+        self._container = Container(parent=container, name="mcp_channel:" + self._name)
+        self._states: Optional[StateStore] = None
+
+    def children(self) -> dict[str, "Channel"]:
+        return {}
+
+    @property
+    def container(self) -> IoCContainer:
+        return self._container
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def logger(self) -> logging.Logger:
+        if self._logger is None:
+            self._logger = self.container.get(logging.Logger) or logging.getLogger("moss")
+        return self._logger
+
+    # --- ChannelBroker 核心方法实现 --- #
+    async def start(self) -> None:
+        """启动MCP客户端并同步工具元信息"""
+        if self._running:
+            return
+
+        # 同步远端工具元信息
+        try:
+            await asyncio.to_thread(self._container.bootstrap)
+            initialize_result = await self._mcp_client.initialize()  # 初始化MCP连接
+            tools = await self._mcp_client.list_tools()
+
+            # 转换为Mosshell Command和ChannelMeta
+            self._meta = self._build_channel_meta(initialize_result, tools)
+            self._running = True
+        except Exception as e:
+            raise RuntimeError(f"MCP tool discovery failed: {str(e)}") from e
+
+    @property
+    def states(self) -> StateStore:
+        if self._states is None:
+            _states = self._container.get(StateStore)
+            if _states is None:
+                _states = MemoryStateStore(self._name)
+                self._container.set(StateStore, _states)
+            self._states = _states
+        return self._states
+
+    async def close(self) -> None:
+        if not self._running:
+            return
+        await asyncio.to_thread(self._container.shutdown)
+
+    def is_running(self) -> bool:
+        return self._running
+
+    def meta(self) -> ChannelMeta:
+        # todo: 还没有实现动态更新, 主要是更新 command
+        if not self.is_running():
+            raise RuntimeError(f"Channel client {self._name} is not running")
+        return self._meta.model_copy()
+
+    async def refresh_meta(self) -> None:
+        # todo: shall refresh command metas
+        return None
+
+    def is_connected(self) -> bool:
+        # todo: 检查状态.
+        return self.is_running()
+
+    async def wait_connected(self) -> None:
+        # todo: 检查状态.
+        return
+
+    def commands(self, available_only: bool = True) -> dict[str, Command]:
+        # todo: 这里每次更新, 和上面好像冲突.
+        meta = self.meta()
+        result = {}
+        for command_meta in meta.commands:
+            if not available_only or command_meta.available:
+                func = self._get_command_func(command_meta)
+                command = CommandWrapper(meta=command_meta, func=func)
+                result[command_meta.name] = command
+        return result
+
+    def get_command(self, name: str) -> Optional[Command]:
+        meta = self.meta()
+        for command_meta in meta.commands:
+            if command_meta.name == name:
+                func = self._get_command_func(command_meta)
+                return CommandWrapper(meta=command_meta, func=func)
+        return None
+
+    def _get_command_func(self, meta: CommandMeta) -> Callable[[...], Coroutine[None, None, Any]] | None:
+        name = meta.name
+
+        args_schema_properties = meta.args_schema.get("properties", {})
+        required_args_list = meta.args_schema.get("required", [])
+        schema_param_count = len(args_schema_properties)
+        required_schema_param_count = len(required_args_list)
+
+        # 回调服务端.
+        async def _server_caller_as_command(*args, **kwargs):
+            # 调用MCP客户端执行工具
+            try:
+                if required_schema_param_count > schema_param_count:
+                    raise CommandError(
+                        code=CommandErrorCode.INVALID_PARAMETER.value,
+                        message=(
+                            "MCP tool: invalid parameter count, required parameter: "
+                            f"{required_schema_param_count}, schema parameter: {schema_param_count}"
+                        ),
+                    )
+
+                param_count = len(args) + len(kwargs)
+                final_kwargs = {}
+                if schema_param_count == 0:  # do nothing
+                    if not param_count == 0:
+                        raise CommandError(
+                            code=CommandErrorCode.INVALID_PARAMETER.value,
+                            message=f"MCP tool: no parameter, invalid, args={args}, kwargs={kwargs}",
+                        )
+                else:  # schema_param_count > 1
+                    if not (param_count == 1 or required_schema_param_count <= param_count <= schema_param_count):
+                        raise CommandError(
+                            code=CommandErrorCode.INVALID_PARAMETER.value,
+                            message=f"MCP tool: invalid parameters, invalid, args={args}, kwargs={kwargs}",
+                        )
+                    if param_count == 1:
+                        if len(args) == 1:
+                            if required_schema_param_count == 1:
+                                if type(args[0]) is not str:
+                                    [param_name, param_info], *_ = args_schema_properties.items()
+                                    if param_type := param_info.get("type", None):
+                                        if type(args[0]).__name__ == self._mcp_type_2_py_type(param_type):
+                                            final_kwargs[param_name] = args[0]
+
+                            if not len(final_kwargs):
+                                try:
+                                    final_kwargs = json.loads(args[0])
+                                except TypeError as e:
+                                    raise CommandError(
+                                        code=CommandErrorCode.VALUE_ERROR.value,
+                                        message=f'MCP tool: invalid "text__" type, {str(e)}',
+                                    )
+                                except json.JSONDecodeError as e:
+                                    raise CommandError(
+                                        code=CommandErrorCode.VALUE_ERROR.value,
+                                        message=(
+                                            f"MCP tool: invalid `text__` parameter format, INVALID JSON schema, {e}"
+                                        ),
+                                    )
+                        else:
+                            if "text__" in kwargs:
+                                final_kwargs = json.loads(kwargs["text__"])
+                            elif required_schema_param_count == 1:
+                                param_name = required_args_list[0]
+                                if param_name not in kwargs:
+                                    raise CommandError(
+                                        code=CommandErrorCode.INVALID_PARAMETER.value,
+                                        message=f'MCP tool: unknown parameter "{param_name}" parameter format.',
+                                    )
+                                final_kwargs.update(kwargs)
+                            else:
+                                raise CommandError(
+                                    code=CommandErrorCode.INVALID_PARAMETER.value,
+                                    message=f'MCP tool: missing "text__" parameters, kwargs={kwargs}',
+                                )
+                    else:
+                        for arg_name, arg in zip(args_schema_properties.keys(), args):
+                            final_kwargs[arg_name] = arg
+                        final_kwargs.update(kwargs)
+
+                mcp_result = await self._mcp_client.call_tool(
+                    name=meta.name,
+                    arguments=final_kwargs,
+                )
+                # convert to moss Message
+                return mcp_call_tool_result_to_message(mcp_result, name=self.name())
+            except mcp.McpError as e:
+                raise CommandError(code=CommandErrorCode.FAILED.value, message=f"MCP call failed: {str(e)}") from e
+            except Exception as e:
+                raise CommandError(
+                    code=CommandErrorCode.FAILED.value, message=f"MCP tool execution failed: {str(e)}"
+                ) from e
+
+        return _server_caller_as_command
+
+    async def execute(self, task: CommandTask[R]) -> R:
+        if not self.is_running():
+            raise RuntimeError("MCPChannel is not running")
+        func = self._get_command_func(task.meta)
+        if func is None:
+            raise LookupError(f"Channel {self._name} can find command {task.meta.name}")
+        return await func(*task.args, **task.kwargs)
+
+        # --- 工具转Command的核心逻辑 --- #
+
+    def _convert_tools_to_command_metas(self, tools: list[types.Tool]) -> list[CommandMeta]:
+        """将MCP工具转换为Mosshell的CommandMeta"""
+        metas = []
+        for tool in tools:
+            tool_name = tool.name
+
+            # 生成符合Code as Prompt的interface（模型可见的函数签名）
+            interface, description = self._generate_code_as_prompt(tool)
+
+            metas.append(
+                CommandMeta(
+                    name=tool_name,
+                    description=description or "",
+                    chan=self._name,
+                    interface=interface,
+                    available=True,
+                    args_schema=tool.inputSchema,
+                    delta_arg=CommandDeltaType.TEXT,
+                )
+            )
+        return metas
+
+    @staticmethod
+    def _mcp_type_2_py_type(param_info_type: str) -> str:
+        param_type = MCPChannelBroker.MCP_PY_TYPES_TRANS_TABLE.get(param_info_type.lower(), "Any")
+        return param_type
+
+    def _parse_schema(self, schema: dict) -> tuple[list, list]:
+        required_params = []
+        optional_params = []
+        required_param_docs = []
+        optional_param_docs = []
+
+        for param_name, param_info in schema.get("properties", {}).items():
+            # 确定参数类型
+            param_type = self._mcp_type_2_py_type(param_info.get("type", ""))
+
+            # 确定默认值
+            param_str = f"{param_name}: {param_type}"
+            if param_name not in schema.get("required", []):
+                default_value = "None" if param_type != "bool" else "False"
+                param_str += f"={default_value}"
+
+            # 根据是否必需参数，添加到不同的列表
+            if param_name in schema.get("required", []):
+                required_params.append(param_str)
+                # 添加参数文档
+                if "description" in param_info:
+                    required_param_docs.append(f"    :param {param_name}: {param_info['description']}")
+            else:
+                optional_params.append(param_str)
+                # 添加参数文档
+                if "description" in param_info:
+                    optional_param_docs.append(f"    :param {param_name}: {param_info['description']}")
+
+        return required_params + optional_params, required_param_docs + optional_param_docs
+
+    def _parse_schema_container(self, schema: dict) -> tuple[list, list]:
+        params = [self.COMMAND_DELTA_PARAMTER]
+        try:
+            required_param_docs = [
+                "param text__: 用 JSON 描述参数，它的 JSON Schema 如右:",
+                json.dumps(schema),
+            ]
+        except Exception as e:
+            raise e
+
+        return params, required_param_docs
+
+    def _parse_input_schema(self, input_schema: dict[str, Any], error_prefix="") -> tuple[list[str], list[str]]:
+        """解析inputSchema并提取参数信息和参数文档"""
+        # todo: 考虑直接将 json schema 作为 text__ 参数.
+        if not input_schema:
+            return [], []
+
+        params = []
+        param_docs = []
+        try:
+            # 解析inputSchema
+            schema = input_schema
+            if isinstance(schema, str):
+                schema = json.loads(schema)
+
+            if "properties" not in schema:
+                return params, param_docs
+
+            # 合并列表，必需参数在前，可选参数在后
+            # mcp_types = [i.get('type', '') for i in list(schema['properties'].values())]
+            # if any([x in self.MCP_CONTAINER_TYPES for x in mcp_types]):
+            #     params, param_docs = self._parse_schema_container(schema)
+            # else:
+            #     params, param_docs = self._parse_schema(schema)
+            params, param_docs = self._parse_schema_container(schema)
+
+        except Exception as e:
+            print(f"{error_prefix}解析inputSchema出错: {e}")
+        return params, param_docs
+
+    def _adjust_description(self, description: str, param_doc: str) -> str:
+        return f"{description}\n{param_doc}\n"
+
+    def _generate_code_as_prompt(self, tool: types.Tool) -> tuple[str, str]:
+        """生成模型可见的Command接口（Code as Prompt）"""
+
+        # 提取函数名（将连字符替换为下划线）
+        function_name = tool.name.replace("-", "_")
+
+        # 提取参数信息
+        params, param_docs = self._parse_input_schema(tool.inputSchema, "")
+
+        description = tool.description or ""
+        if len(params) == 1 and params[0] == self.COMMAND_DELTA_PARAMTER:
+            description = self._adjust_description(description, "".join(param_docs))
+
+        # 生成Async函数签名（符合Python语法）
+        interface = (
+            f"async def {function_name}({', '.join(params)}) -> Any:\n"
+            f"    '''\n"
+            f"    {description}\n"
+            # f"    {''.join(param_docs)}\n"
+            f"    '''\n"
+            f"    pass"
+        )
+        return interface, description
+
+    def _build_channel_meta(
+        self, initialize_result: types.InitializeResult, tool_result: types.ListToolsResult
+    ) -> ChannelMeta:
+        """构建Channel元信息（包含所有工具的CommandMeta）"""
+        return ChannelMeta(
+            name=self._name,
+            channel_id=self._name,
+            available=True,
+            description=initialize_result.instructions or "",
+            commands=self._convert_tools_to_command_metas(tools=tool_result.tools),
+            children=[],
+        )
+
+    # --- 未使用的生命周期方法（默认空实现） --- #
+    async def policy_run(self) -> None:
+        pass
+
+    async def policy_pause(self) -> None:
+        pass
+
+    async def clear(self) -> None:
+        pass
+
+    def is_available(self) -> bool:
+        return True
+
+
+class MCPChannel(Channel):
+    """对接MCP服务的Channel"""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        mcp_client: mcp.ClientSession,
+    ):
+        self._name = name
+        self._desc = description
+        self._mcp_client = mcp_client
+        self._client: Optional[MCPChannelBroker] = None
+
+    # --- Channel 核心方法实现 --- #
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def broker(self) -> ChannelBroker:
+        if not self._client or not self._client.is_running():
+            raise RuntimeError("MCPChannel not bootstrapped")
+        return self._client
+
+    @property
+    def build(self) -> Builder:
+        raise NotImplementedError("MCPChannel does not implement `build`")
+
+    def bootstrap(self, container: Optional[IoCContainer] = None) -> ChannelBroker:
+        if self._client is not None and self._client.is_running():
+            raise RuntimeError(f"Channel {self} has already been started.")
+
+        self._client = MCPChannelBroker(
+            name=self._name,
+            container=container,
+            mcp_client=self._mcp_client,
+        )
+
+        return self._client
+
+    # --- 未使用的Channel方法（默认空实现） --- #
+    def import_channels(self, *children: Channel) -> Channel:
+        raise NotImplementedError("MCPChannel does not support children")
+
+    def new_child(self, name: str) -> Channel:
+        raise NotImplementedError("MCPChannel does not support children")
+
+    def children(self) -> dict[str, Channel]:
+        return {}
+
+    def is_running(self) -> bool:
+        return self._client is not None and self._client.is_running()

ghoshell_moss/compatible/mcp_channel/types.py

@@ -0,0 +1,17 @@
+from mcp import types as mcp_types
+
+from ghoshell_moss.message import Addition
+
+
+class MCPCallToolResultAddition(Addition, mcp_types.CallToolResult):
+    @classmethod
+    def keyword(cls) -> str:
+        return "mcp_call_tool_result"
+
+    @classmethod
+    def from_mcp_types(cls, mcp_result: mcp_types.CallToolResult):
+        return cls(
+            isError=mcp_result.isError,
+            structuredContent=mcp_result.structuredContent,
+            content=mcp_result.content,
+        )

ghoshell_moss/compatible/mcp_channel/utils.py

@@ -0,0 +1,25 @@
+from mcp import types
+
+from ghoshell_moss import CommandError, CommandErrorCode
+from ghoshell_moss.compatible.mcp_channel.types import MCPCallToolResultAddition
+from ghoshell_moss.message import Base64Image, Message, Text
+
+
+def mcp_call_tool_result_to_message(mcp_result: types.CallToolResult, name: str | None = None) -> Message:
+    if mcp_result.isError:
+        raise CommandError(
+            code=CommandErrorCode.FAILED.value,
+            message=f"MCP tool: call failed, {mcp_result.content}",
+        )
+    result = Message.new(role="assistant", name=name)
+    for mcp_content in mcp_result.content:
+        if isinstance(mcp_content, types.TextContent):
+            result.with_content(Text(text=mcp_content.text))
+        if isinstance(mcp_content, types.ImageContent):
+            result.with_content(Base64Image(image_type=mcp_content.mimeType, encoded=mcp_content.data))
+        if isinstance(mcp_content, types.AudioContent):
+            pass
+        pass
+
+    result.with_additions(MCPCallToolResultAddition.from_mcp_types(mcp_result))
+    return result

ghoshell_moss/core/README.md

@@ -0,0 +1,6 @@
+# core
+
+项目的核心目录, 包含:
+
+- concepts/ # 基于代码即文档的思想, 将 moss 的抽象设计列入
+-