AstrBot/docs/SDK_INTEGRATION_PLAN.md

# AstrBot SDK 接入实施计划

> 本文档基于用户 `whatevertogo` 的分析文档，补充具体实施细节。

## 一、架构验证结果

经代码审查确认：

| 组件 | 路径 | 状态 |
|------|------|------|
| Core Context | `astrbot/core/star/context.py` | ✅ 包含所有核心能力方法 |
| CapabilityRouter | `src-new/astrbot_sdk/runtime/capability_router.py` | ✅ 已实现内置能力注册 |
| StarHandlerMetadata | `astrbot/core/star/star_handler.py` | ✅ 定义清晰，可扩展 |
| HandlerDescriptor | `src-new/astrbot_sdk/protocol/descriptors.py` | ✅ Pydantic 模型，类型安全 |
| SupervisorRuntime | `src-new/astrbot_sdk/runtime/bootstrap.py` | ✅ 已实现完整生命周期 |
| CoreLifecycle | `astrbot/core/core_lifecycle.py` | ✅ 接入点明确 |

---

## 二、实施阶段

### Phase 1: 基础桥接层 (预计 2-3 天)

#### 1.1 创建目录结构

```
astrbot/core/sdk_bridge/
├── __init__.py
├── capability_bridge.py    # CoreCapabilityBridge
├── supervisor_bridge.py    # SdkPluginBridge
├── event_bridge.py         # 事件转换
├── handler_bridge.py       # Handler 注册桥接
└── transport_adapter.py    # Transport 适配
```

#### 1.2 实现 `capability_bridge.py`

```python
"""CoreCapabilityBridge: 把 astrbot.core.Context 能力映射到 CapabilityRouter。"""
from __future__ import annotations

import logging
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from astrbot.core.star.context import Context as CoreContext
    from astrbot_sdk.runtime.capability_router import CapabilityRouter

logger = logging.getLogger("astrbot.sdk_bridge")


class CoreCapabilityBridge:
    """把 astrbot.core.Context 的真实实现注入进 SDK CapabilityRouter。

    SupervisorRuntime 初始化后，Core 侧的 Peer 调用此 Bridge 来响应插件发来的能力请求。
    """

    def __init__(self, core_context: CoreContext, router: CapabilityRouter) -> None:
        self.ctx = core_context
        self.router = router
        self._wire()

    def _wire(self) -> None:
        """注册所有能力处理器到 router。"""
        # 替换 router 的内置 echo 实现为真实实现
        self._wire_llm()
        self._wire_db()
        self._wire_platform()
        self._wire_memory()
        self._wire_metadata()
        logger.info("SDK CapabilityBridge 已连接")

    def _wire_llm(self) -> None:
        """连接 LLM 能力。"""
        async def llm_chat(request_id: str, payload: dict[str, Any], _token) -> dict[str, Any]:
            # 从 payload 提取参数
            prompt = payload.get("prompt", "")
            provider_id = payload.get("provider_id")
            # 调用 core 的 llm_generate
            if provider_id:
                resp = await self.ctx.llm_generate(
                    chat_provider_id=provider_id,
                    prompt=prompt,
                    # ... 其他参数
                )
            else:
                # 使用默认 provider
                prov = self.ctx.get_using_provider()
                if prov:
                    resp = await self.ctx.llm_generate(
                        chat_provider_id=prov.meta().id,
                        prompt=prompt,
                    )
                else:
                    return {"text": f"Echo (no provider): {prompt}"}
            return {"text": resp.completion_text or ""}

        # 注册到 router (覆盖默认 echo 实现)
        self.router.unregister("llm.chat")
        self.router.register(
            self.router._registrations["llm.chat"].descriptor,  # 复用 descriptor
            call_handler=llm_chat,
        )

    def _wire_db(self) -> None:
        """连接数据库能力。"""
        async def db_get(request_id: str, payload: dict[str, Any], _token) -> dict[str, Any]:
            key = str(payload.get("key", ""))
            # 使用 core 的数据库
            db = self.ctx.get_db()
            value = await db.get(key)
            return {"value": value}

        async def db_set(request_id: str, payload: dict[str, Any], _token) -> dict[str, Any]:
            key = str(payload.get("key", ""))
            value = payload.get("value")
            db = self.ctx.get_db()
            await db.set(key, value)
            return {}

        # 覆盖注册
        self.router.unregister("db.get")
        self.router.unregister("db.set")
        # ... 类似注册其他 db 方法

    def _wire_platform(self) -> None:
        """连接平台消息发送能力。"""
        async def platform_send(request_id: str, payload: dict[str, Any], _token) -> dict[str, Any]:
            from astrbot.core.platform.astr_message_event import MessageSesion
            from astrbot.core.message.message_event_result import MessageChain

            session_str = payload.get("session", "")
            text = payload.get("text", "")

            # 构建 MessageChain
            chain = MessageChain().message(text)

            # 调用 core 的 send_message
            success = await self.ctx.send_message(session_str, chain)
            return {"message_id": f"msg_{request_id}", "success": success}

        self.router.unregister("platform.send")
        self.router.register(
            self.router._registrations["platform.send"].descriptor,
            call_handler=platform_send,
        )

    def _wire_memory(self) -> None:
        """连接记忆/会话管理能力。"""
        async def memory_save(request_id: str, payload: dict[str, Any], _token) -> dict[str, Any]:
            # 使用 conversation_manager
            key = str(payload.get("key", ""))
            value = payload.get("value")
            # 实现具体逻辑
            return {}

        # 注册...

    def _wire_metadata(self) -> None:
        """连接插件元数据能力。"""
        # metadata.get_config -> context.get_config()
        # metadata.get_star -> star_registry 查询
        pass
```

#### 1.3 实现 `event_bridge.py`

```python
"""事件双向转换模块。"""
from __future__ import annotations

from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from astrbot.core.platform.astr_message_event import AstrMessageEvent


def astr_event_to_sdk_payload(event: AstrMessageEvent) -> dict[str, Any]:
    """把旧版 AstrMessageEvent 转成 SDK MessageEvent 的 to_payload() 格式。"""
    return {
        "text": event.message_str,
        "user_id": event.get_sender_id(),
        "group_id": event.get_group_id() if event.is_group_message() else None,
        "platform": event.get_platform_name(),
        "session_id": event.unified_msg_origin,
        "target": {
            "conversation_id": event.unified_msg_origin,
            "platform": event.get_platform_name(),
        },
        # 保留原始消息对象引用
        "_raw_message_obj": event.message_obj,
        "_raw_platform_meta": event.platform_meta,
        # 保留原始 event 引用，供后续处理
        "_core_event": event,
    }


def sdk_payload_to_event_context(payload: dict[str, Any]) -> dict[str, Any]:
    """从 SDK payload 提取事件上下文信息。"""
    return {
        "session": payload.get("session_id", ""),
        "user_id": payload.get("user_id"),
        "group_id": payload.get("group_id"),
        "platform": payload.get("platform"),
        "text": payload.get("text"),
    }
```

#### 1.4 实现 `handler_bridge.py`

```python
"""Handler 注册桥接：把 SDK HandlerDescriptor 转换为 StarHandlerMetadata。"""
from __future__ import annotations

import logging
from collections.abc import Awaitable
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Callable

from astrbot.core.star.filter import HandlerFilter
from astrbot.core.star.star_handler import EventType, StarHandlerMetadata

if TYPE_CHECKING:
    from astrbot_sdk.protocol.descriptors import HandlerDescriptor
    from astrbot_sdk.runtime.bootstrap import WorkerSession

logger = logging.getLogger("astrbot.sdk_bridge")


# SDK 事件类型到 Core 事件类型的映射
TRIGGER_TO_EVENT_TYPE = {
    "message": EventType.AdapterMessageEvent,
    "command": EventType.AdapterMessageEvent,
    "event": EventType.AdapterMessageEvent,  # 需要根据具体 event_type 细分
    "schedule": EventType.OnAstrBotLoadedEvent,  # 定时任务特殊处理
}


@dataclass
class SdkHandlerWrapper:
    """包装 SDK handler 的调用闭包。"""
    session: WorkerSession
    handler_id: str

    async def __call__(self, *args, **kwargs) -> Any:
        """调用 SDK handler。"""
        # 从 args/kwargs 提取事件信息
        event = kwargs.get("event") or (args[0] if args else None)
        if event is None:
            raise ValueError("SDK handler 需要 event 参数")

        # 转换事件格式
        from .event_bridge import astr_event_to_sdk_payload
        payload = astr_event_to_sdk_payload(event)

        # 通过 session 调用远程 handler
        return await self.session.invoke_handler(self.handler_id, payload)


def handler_descriptor_to_metadata(
    descriptor: HandlerDescriptor,
    session: WorkerSession,
) -> StarHandlerMetadata:
    """把 SDK HandlerDescriptor 转换为 Core 的 StarHandlerMetadata。

    Args:
        descriptor: SDK handler 描述符
        session: Worker 会话，用于调用远程 handler

    Returns:
        StarHandlerMetadata: Core 兼容的 handler 元数据
    """
    # 创建包装器
    wrapper = SdkHandlerWrapper(session=session, handler_id=descriptor.id)

    # 确定 Core 事件类型
    trigger = descriptor.trigger
    event_type = TRIGGER_TO_EVENT_TYPE.get(trigger.type, EventType.AdapterMessageEvent)

    # 构建 event_filters
    event_filters = _build_event_filters(trigger)

    # 构建 extras_configs
    extras_configs = {
        "priority": descriptor.priority,
        "require_admin": descriptor.permissions.require_admin,
        "level": descriptor.permissions.level,
        "sdk_handler": True,  # 标记为 SDK handler
    }

    # 解析 handler_full_name
    parts = descriptor.id.rsplit(".", 1)
    if len(parts) == 2:
        module_path, handler_name = parts
    else:
        module_path = descriptor.id
        handler_name = descriptor.id

    return StarHandlerMetadata(
        event_type=event_type,
        handler_full_name=descriptor.id,
        handler_name=handler_name,
        handler_module_path=module_path,
        handler=wrapper,  # 使用包装器
        event_filters=event_filters,
        desc=getattr(trigger, "description", "") or "",
        extras_configs=extras_configs,
    )


def _build_event_filters(trigger: Any) -> list[HandlerFilter]:
    """根据 trigger 类型构建事件过滤器。"""
    from astrbot.core.star.filter.command import CommandFilter
    from astrbot.core.star.filter.regex import RegexFilter

    filters: list[HandlerFilter] = []

    if trigger.type == "command":
        # 命令触发器 -> CommandFilter
        filters.append(CommandFilter(
            command_name=trigger.command,
            # handler_md 需要稍后设置
        ))
    elif trigger.type == "message":
        # 消息触发器 -> RegexFilter
        if trigger.regex:
            filters.append(RegexFilter(regex=trigger.regex))
        # keywords 过滤需要在运行时检查

    return filters
```

#### 1.5 实现 `supervisor_bridge.py`

```python
"""SdkPluginBridge: 在 Core 侧管理 SupervisorRuntime。"""
from __future__ import annotations

import asyncio
import logging
from pathlib import Path
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from astrbot.core.star.context import Context as CoreContext

logger = logging.getLogger("astrbot.sdk_bridge")


class SdkPluginBridge:
    """在 Core 侧管理 SupervisorRuntime，并把 SDK handler 注册进 pipeline。"""

    def __init__(
        self,
        core_context: CoreContext,
        sdk_plugins_dir: Path,
    ) -> None:
        from astrbot_sdk.runtime.capability_router import CapabilityRouter
        from astrbot_sdk.runtime.bootstrap import SupervisorRuntime
        from astrbot_sdk.transport.stdio import StdioTransport

        self.ctx = core_context
        self.plugins_dir = sdk_plugins_dir

        # 创建 CapabilityRouter 和 Bridge
        self.capability_router = CapabilityRouter()
        self.capability_bridge = None  # 延迟初始化

        # 创建 Transport (使用 stdio 进行进程间通信)
        self.transport = StdioTransport()

        # 创建 Supervisor
        self.supervisor = SupervisorRuntime(
            transport=self.transport,
            plugins_dir=sdk_plugins_dir,
        )

        # 已注册的 handler 映射
        self._registered_handlers: dict[str, str] = {}  # handler_id -> plugin_name

    async def start(self) -> None:
        """启动 SDK 插件桥接。"""
        # 初始化 CapabilityBridge (替换默认 echo 实现)
        from .capability_bridge import CoreCapabilityBridge
        self.capability_bridge = CoreCapabilityBridge(self.ctx, self.capability_router)

        # 启动 Supervisor
        await self.supervisor.start()

        # 注册所有 handler 到 pipeline
        self._register_handlers_into_pipeline()

        logger.info(f"SDK 插件桥接已启动，共加载 {len(self._registered_handlers)} 个 handler")

    async def stop(self) -> None:
        """停止 SDK 插件桥接。"""
        await self.supervisor.stop()
        self._registered_handlers.clear()
        logger.info("SDK 插件桥接已停止")

    def _register_handlers_into_pipeline(self) -> None:
        """把 supervisor 聚合的所有 HandlerDescriptor 注册进 star_handlers_registry。"""
        from astrbot.core.star.star_handler import star_handlers_registry

        from .handler_bridge import handler_descriptor_to_metadata

        for handler_id, session in self.supervisor.handler_to_worker.items():
            # 获取 handler 的 descriptor
            descriptor = self._get_handler_descriptor(handler_id)
            if descriptor is None:
                logger.warning(f"无法获取 handler descriptor: {handler_id}")
                continue

            # 转换为 StarHandlerMetadata
            metadata = handler_descriptor_to_metadata(descriptor, session)

            # 注册到全局 registry
            star_handlers_registry.append(metadata)

            self._registered_handlers[handler_id] = descriptor.id.split(".")[0]
            logger.debug(f"注册 SDK handler: {handler_id}")

    def _get_handler_descriptor(self, handler_id: str):
        """从 supervisor 获取 handler descriptor。"""
        # 遍历所有 session 的 loaded_plugin 找到对应的 handler
        for plugin_id, session in self.supervisor._plugin_sessions.items():
            if session.loaded_plugin:
                for handler in session.loaded_plugin.handlers:
                    if handler.id == handler_id:
                        return handler
        return None
```

---

### Phase 2: 生命周期集成 (预计 1 天)

#### 2.1 修改 `core_lifecycle.py`

```python
# 在 CoreLifecycle 类中添加

def __init__(self, ...):
    # ... 现有代码 ...
    self.sdk_bridge: SdkPluginBridge | None = None

async def initialize(self) -> None:
    # ... 现有初始化代码 ...

    # 在 PluginManager 初始化后，初始化 SDK Bridge
    if self.astrbot_config.get("enable_sdk_plugins", False):
        from pathlib import Path
        from astrbot.core.sdk_bridge.supervisor_bridge import SdkPluginBridge

        sdk_plugins_dir = Path("data/sdk_plugins")
        sdk_plugins_dir.mkdir(parents=True, exist_ok=True)

        self.sdk_bridge = SdkPluginBridge(
            core_context=self.star_context,
            sdk_plugins_dir=sdk_plugins_dir,
        )

async def start(self) -> None:
    self._load()

    # 启动 SDK Bridge
    if self.sdk_bridge:
        await self.sdk_bridge.start()
        logger.info("SDK 插件桥接启动完成")

    # ... 现有代码 ...

async def stop(self) -> None:
    # 停止 SDK Bridge
    if self.sdk_bridge:
        await self.sdk_bridge.stop()

    # ... 现有代码 ...
```

---

### Phase 3: 测试与验证 (预计 2 天)

#### 3.1 单元测试

```python
# tests/test_sdk_bridge.py

import pytest
from astrbot.core.sdk_bridge.capability_bridge import CoreCapabilityBridge
from astrbot.core.sdk_bridge.event_bridge import astr_event_to_sdk_payload
from astrbot.core.sdk_bridge.handler_bridge import handler_descriptor_to_metadata


class TestEventBridge:
    def test_astr_event_to_sdk_payload(self, mock_event):
        payload = astr_event_to_sdk_payload(mock_event)
        assert payload["text"] == mock_event.message_str
        assert payload["user_id"] == mock_event.get_sender_id()
        assert "_core_event" in payload


class TestCapabilityBridge:
    async def test_llm_chat_capability(self, mock_core_context, mock_router):
        bridge = CoreCapabilityBridge(mock_core_context, mock_router)
        # 验证 llm.chat 已被覆盖
        assert "llm.chat" in mock_router._registrations


class TestHandlerBridge:
    def test_command_handler_conversion(self, mock_descriptor, mock_session):
        metadata = handler_descriptor_to_metadata(mock_descriptor, mock_session)
        assert metadata.handler_full_name == mock_descriptor.id
        assert len(metadata.event_filters) > 0
```

#### 3.2 集成测试

```python
# tests/integration/test_sdk_integration.py

import pytest
from pathlib import Path


@pytest.fixture
async def sdk_bridge(test_context, tmp_path):
    from astrbot.core.sdk_bridge.supervisor_bridge import SdkPluginBridge

    bridge = SdkPluginBridge(
        core_context=test_context,
        sdk_plugins_dir=tmp_path / "sdk_plugins",
    )
    await bridge.start()
    yield bridge
    await bridge.stop()


async def test_sdk_plugin_loading(sdk_bridge):
    """测试 SDK 插件能被正确加载。"""
    assert len(sdk_bridge._registered_handlers) > 0


async def test_sdk_handler_invocation(sdk_bridge, mock_event):
    """测试 SDK handler 能被正确调用。"""
    from astrbot.core.star.star_handler import star_handlers_registry

    # 查找 SDK 注册的 handler
    handlers = [h for h in star_handlers_registry if h.extras_configs.get("sdk_handler")]
    assert len(handlers) > 0

    # 调用 handler
    handler = handlers[0]
    result = await handler.handler(event=mock_event)
    # 验证结果
```

---

### Phase 4: 配置与文档 (预计 1 天)

#### 4.1 配置项

```yaml
# config/astrbot_config.yaml
sdk_plugins:
  enabled: true
  plugins_dir: "data/sdk_plugins"
  worker_timeout: 30  # Worker 启动超时（秒）
  max_restarts: 3     # Worker 崩溃后最大重启次数
```

#### 4.2 用户文档

创建 `docs/sdk_plugin_development.md`，说明：
- SDK 插件目录结构
- `plugin.yaml` 配置格式
- Handler 注册方式
- Capability 调用示例

---

## 三、能力映射详细表

| SDK Capability | Core Context 方法 | 实现状态 |
|----------------|------------------|----------|
| `llm.chat` | `context.llm_generate()` | 待实现 |
| `llm.chat_raw` | `context.llm_generate()` | 待实现 |
| `llm.stream_chat` | `context.llm_generate()` + stream | 待实现 |
| `db.get` | `context.get_db().get()` | 待实现 |
| `db.set` | `context.get_db().set()` | 待实现 |
| `db.delete` | `context.get_db().delete()` | 待实现 |
| `db.list` | `context.get_db().list()` | 待实现 |
| `platform.send` | `context.send_message()` | 待实现 |
| `platform.send_image` | `context.send_message()` + image | 待实现 |
| `platform.send_chain` | `context.send_message()` | 待实现 |
| `memory.search` | `context.conversation_manager.*` | 待实现 |
| `memory.save` | `context.conversation_manager.*` | 待实现 |
| `metadata.get_config` | `context.get_config()` | 待实现 |
| `metadata.get_star` | `star_registry` 查询 | 待实现 |

---

## 四、风险与缓解措施

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| Worker 进程崩溃 | 插件不可用 | 实现自动重启机制 |
| 事件格式不兼容 | 功能异常 | 完善事件转换层 |
| 性能下降 | 用户体验变差 | 优化序列化，考虑共享内存 |
| 旧插件迁移成本 | 用户流失 | 保持 legacy 兼容层 |

---

## 五、后续优化

1. **Worker 崩溃重启**：在 `SupervisorRuntime` 中添加指数退避重启机制
2. **性能优化**：考虑使用共享内存传输大消息
3. **调试支持**：添加 SDK 插件调试模式
4. **热重载**：支持 SDK 插件热更新

---

## 六、实施检查清单

- [ ] 创建 `astrbot/core/sdk_bridge/` 目录
- [ ] 实现 `capability_bridge.py`
- [ ] 实现 `event_bridge.py`
- [ ] 实现 `handler_bridge.py`
- [ ] 实现 `supervisor_bridge.py`
- [ ] 修改 `core_lifecycle.py` 集成
- [ ] 添加配置项
- [ ] 编写单元测试
- [ ] 编写集成测试
- [ ] 编写用户文档
- [ ] 处理 `legacy_adapter.py` 死代码
- [ ] 给 `CommandComponent` 添加 DeprecationWarning