refactor: 删除过时的架构文档、变更日志和兼容矩阵文件

ARCHITECTURE.md

@@ -1,364 +0,0 @@
-# AstrBot SDK v4 当前架构文档
-
-本文描述仓库 **当前实现**，是 `src-new/astrbot_sdk` / `src-new/astrbot` / `tests_v4` 的唯一主文档。  
-`refactor.md` 仅保留历史设计意图和演进说明，不再描述现状。
-
-## 1. 目标与边界
-
-AstrBot SDK v4 当前同时承担两件事：
-
-1. 提供一套原生 v4 插件模型：`Star`、`Context`、`MessageEvent`、capability clients、v4 protocol。
-2. 维持旧插件兼容：`astrbot_sdk.api.*`、`astrbot_sdk.compat`、`astrbot.api.*` 以及选定的 `astrbot.core.*` facade 继续可用。
-
-因此，compat 现在不是可忽略的旁路，而是一个受控的过渡子系统。当前架构目标是：
-
-- v4 原生 API 仍保持清晰、窄导出、协议优先。
-- legacy 兼容逻辑尽量收口到私有边界，而不是扩散到 runtime 主干。
-- 兼容导入路径继续可用，但不把旧应用整棵树重新复制进来。
-- 文档明确区分“等价兼容”“降级兼容”“仅导入兼容”。
-
-## 2. 当前分层模型
-
-```text
-插件作者
-  ├─ 原生 v4: astrbot_sdk.{Star, Context, MessageEvent, decorators}
-  └─ legacy compat: astrbot_sdk.api.* / astrbot_sdk.compat / astrbot.api.*
-
-高层 API
-  ├─ 原生 clients: llm / memory / db / platform
-  └─ legacy facade: LegacyContext / LegacyStar / message components / filter namespace
-
-执行边界
-  ├─ runtime 主干: loader / bootstrap / handler_dispatcher / capability_router / peer
-  ├─ compat 私有实现: _legacy_api.py / _legacy_runtime.py / _legacy_loader.py
-  └─ 运行时交互辅助: _session_waiter.py / _shared_preferences.py
-
-协议与传输
-  ├─ protocol.messages / protocol.descriptors
-  ├─ Peer
-  └─ StdioTransport / WebSocket transports
-```
-
-### 当前最重要的架构判断
-
-- `astrbot_sdk.__init__` 只导出推荐的 v4 入口。
-- `astrbot_sdk.runtime.__init__` 只导出高级运行时原语，不把 loader/bootstrap 等编排细节提升为根级稳定 API。
-- `astrbot_sdk.protocol.__init__` 只导出 v4 原生协议模型；legacy JSON-RPC 适配器留在 `protocol.legacy_adapter` 子模块。
-- compat 私有实现保留在既有顶层 private 模块中，避免再维护一套并行目录。
-- `astrbot_sdk.api.*` 与 `astrbot.*` 仅作为迁移期 facade 保留，不再扩张为长期稳定主入口。
-- runtime 主干通过 `_legacy_runtime.py` / `_legacy_loader.py` 等私有边界执行 compat filters / hooks / 生命周期桥接，不直接展开更多 legacy 细节。
-
-## 3. 目录结构
-
-```text
-src-new/
-├── astrbot_sdk/
-│   ├── __init__.py                  # v4 推荐顶层入口
-│   ├── context.py                   # Context / CancelToken
-│   ├── decorators.py                # on_command / on_message / provide_capability ...
-│   ├── events.py                    # MessageEvent / PlainTextResult
-│   ├── errors.py                    # AstrBotError / ErrorCodes
-│   ├── star.py                      # Star 基类与 handler 收集
-│   ├── cli.py                       # astr / astrbot-sdk CLI 入口
-│   ├── testing.py                   # 本地开发与测试 harness
-│   ├── compat.py                    # 旧顶层兼容重导出
-│   ├── _legacy_api.py               # LegacyContext / LegacyStar / CommandComponent
-│   ├── _legacy_llm.py               # legacy LLM/tool 兼容辅助
-│   ├── _legacy_loader.py            # legacy 插件发现与 main.py 包装
-│   ├── _legacy_runtime.py           # compat 执行边界
-│   ├── _session_waiter.py           # legacy session_waiter 兼容执行
-│   ├── _shared_preferences.py       # 共享偏好兼容辅助
-│   │
-│   ├── clients/
-│   │   ├── _proxy.py                # CapabilityProxy
-│   │   ├── llm.py
-│   │   ├── memory.py
-│   │   ├── db.py                    # 包含 get_many / set_many / watch
-│   │   └── platform.py
-│   │
-│   ├── protocol/
-│   │   ├── __init__.py              # 仅导出原生 v4 协议模型
-│   │   ├── descriptors.py           # handlers / capabilities / builtin schema registry
-│   │   ├── messages.py              # initialize / invoke / result / event / cancel
-│   │   └── legacy_adapter.py        # v3 JSON-RPC ↔ v4 适配
-│   │
-│   ├── runtime/
-│   │   ├── __init__.py              # Peer / Transport / CapabilityRouter / HandlerDispatcher
-│   │   ├── peer.py
-│   │   ├── transport.py
-│   │   ├── capability_router.py
-│   │   ├── handler_dispatcher.py
-│   │   ├── loader.py
-│   │   ├── environment_groups.py    # 共享环境规划与分组环境管理
-│   │   └── bootstrap.py
-│   │
-│   └── api/                         # astrbot_sdk.api.* 兼容层
-│       ├── basic/
-│       ├── components/
-│       ├── event/
-│       ├── message/
-│       ├── platform/
-│       ├── provider/
-│       └── star/
-│
-└── astrbot/                         # 旧包名 facade，受控兼容面
-    ├── api/
-    └── core/
-```
-
-## 4. 核心执行链
-
-### 4.1 插件发现与 worker 启动
-
-1. `runtime.loader.discover_plugins()` 扫描插件目录，兼容 `plugin.yaml` 和 legacy `main.py` 插件。
-2. `PluginEnvironmentManager.plan()` 基于 `runtime.python` 和 `requirements.txt` 规划共享环境分组。
-3. `GroupEnvironmentManager` 负责准备分组环境；worker 仍然保持“一插件一进程”，只是可共享同一个 Python 环境。
-4. `load_plugin()` 加载组件，v4 `Star` 直接实例化，legacy 组件复用同一 `LegacyContext`。
-5. legacy component 注册通过 `_legacy_runtime.py` 把 compat hooks / LLM tools / context functions 绑定到共享 `LegacyContext`。
-6. `PluginWorkerRuntime` 创建 `Peer`、`HandlerDispatcher`、`CapabilityDispatcher`，初始化后向 supervisor 发送 `initialize`。
-7. worker 启动/停止时的 compat lifecycle hooks 统一由 `_legacy_runtime.py` 执行。
-
-### 4.2 handler.invoke 调用链
-
-1. 上游通过 capability `"handler.invoke"` 调 worker。
-2. `HandlerDispatcher` 构造本地 `Context` 和 `MessageEvent`，先尝试把消息路由给 `_session_waiter.py`。
-3. 若命中 legacy compat handler，则由 `_legacy_runtime.py` 应用 custom filters、结果装饰、发送后 hook、错误 hook。
-4. handler 返回值支持：
-   - `MessageEventResult`
-   - `MessageChain`
-   - `PlainTextResult`
-   - `str`
-   - `{"text": ...}`
-5. 发送链路优先使用 `ctx.platform.send_chain()` 或 `event.reply()`。
-
-### 4.3 capability 调用链
-
-1. 插件代码通过 `ctx.llm.*`、`ctx.db.*`、`ctx.memory.*`、`ctx.platform.*` 访问上游能力。
-2. clients 通过 `CapabilityProxy` 转成 `Peer.invoke()` / `Peer.invoke_stream()`。
-3. supervisor 侧 `CapabilityRouter` 处理内建能力；worker 也可以通过 `@provide_capability()` 暴露插件自定义 capability。
-4. 插件自定义 capability 由 `CapabilityDispatcher` 在 worker 内分发执行。
-
-### 4.4 session_waiter
-
-`_session_waiter.py` 提供 legacy `@session_waiter` 的最小可运行兼容实现。  
-它不是单纯导入桩，而是按 session 维度把后续消息重新路由给等待中的 compat 回调。
-
-## 5. 协议契约
-
-### 5.1 五条硬规则
-
-1. 所有协议消息统一使用 `id` 关联请求与响应。
-2. `EventMessage` 只用于 `stream=true` 的调用。
-3. 插件 handler 回调统一走 capability `"handler.invoke"`。
-4. `CancelMessage` 表示“请求停止”，调用方仍需等待终止态。
-5. `initialize` 失败后连接进入不可用状态。
-
-### 5.2 版本语义
-
-当前实现里必须区分两个概念：
-
-- `protocol_version`：**线协议版本**。当前 wire contract 使用 `"1.0"`。
-- `PeerInfo.version`：**软件/实现版本标识**。当前 runtime 常用 `"v4"` 作为软件版本字符串。
-
-二者不是同一个字段，也不应混写成同一含义。
-
-### 5.3 主要消息
-
-- `InitializeMessage`
-- `InvokeMessage`
-- `ResultMessage`
-- `EventMessage`
-- `CancelMessage`
-
-`InitializeMessage` 由 `Peer.initialize()` 发起，成功响应是  
-`ResultMessage(kind="initialize_result", success=True, output=InitializeOutput(...))`。
-
-## 6. 当前内建 capabilities
-
-当前协议注册表和 `CapabilityRouter` 内建 capability 一致，共 18 个：
-
-| 命名空间 | Capability | 流式 |
-|---|---|---|
-| `llm` | `llm.chat` | 否 |
-| `llm` | `llm.chat_raw` | 否 |
-| `llm` | `llm.stream_chat` | 是 |
-| `memory` | `memory.search` | 否 |
-| `memory` | `memory.save` | 否 |
-| `memory` | `memory.get` | 否 |
-| `memory` | `memory.delete` | 否 |
-| `db` | `db.get` | 否 |
-| `db` | `db.set` | 否 |
-| `db` | `db.delete` | 否 |
-| `db` | `db.list` | 否 |
-| `db` | `db.get_many` | 否 |
-| `db` | `db.set_many` | 否 |
-| `db` | `db.watch` | 是 |
-| `platform` | `platform.send` | 否 |
-| `platform` | `platform.send_image` | 否 |
-| `platform` | `platform.send_chain` | 否 |
-| `platform` | `platform.get_members` | 否 |
-
-说明：
-
-- `SessionRef` 是结构化发送目标 schema，不是 capability。
-- `internal.*` 与 `handler.*` 命名空间保留给框架内部使用，不属于公开内建 capability 列表。
-
-## 7. 兼容层现状（已弃用）
-
-> **⚠️ 重要：兼容层已弃用，将在下个大版本移除**
->
-> - 旧插件请使用 **AstrBot 主程序** 运行（主程序有完整的 `StarManager` 支持）
-> - 新插件请迁移到 `astrbot_sdk` 顶层入口
-> - 导入兼容层会触发 `DeprecationWarning`
-
-### 7.0 迁移指南
-
-**旧插件开发者有两个选择：**
-
-1. **继续使用旧 API**：由 AstrBot 主程序运行，无需修改代码
-2. **迁移到 v4 SDK**：
-
-```python
-# 旧版（由主程序运行）
-from astrbot.api.event import filter, AstrMessageEvent
-from astrbot.api.star import Context, Star
-
-class MyPlugin(Star):
-    def __init__(self, context: Context):
-        self.context = context
-
-    @filter.command("hello")
-    async def hello(self, event: AstrMessageEvent):
-        yield event.plain_result("Hello!")
-
-# 新版（v4 SDK）
-from astrbot_sdk import Star, on_command, MessageEvent
-
-class MyPlugin(Star):
-    @on_command("hello")
-    async def hello(self, event: MessageEvent):
-        return event.reply("Hello!")
-```
-
-### 7.1 等价或接近等价的兼容面
-
-以下兼容面当前是实际可运行的，不只是 import stub：
-
-- `astrbot_sdk.api.*` 常用导入路径
-- `astrbot_sdk.compat`
-- `astrbot.api.*` 以及选定的 `astrbot.core.*` facade
-- `LegacyContext` / `LegacyStar` / `CommandComponent`
-- `filter.command` / `regex` / `permission`
-- `event_message_type` / `platform_adapter_type`
-- 常用 compat hooks：
-  - `after_message_sent`
-  - `on_astrbot_loaded`
-  - `on_platform_loaded`
-  - `on_decorating_result`
-  - `on_llm_request`
-  - `on_llm_response`
-  - `on_waiting_llm_request`
-  - `on_using_llm_tool`
-  - `on_llm_tool_respond`
-  - `on_plugin_error`
-  - `on_plugin_loaded`
-  - `on_plugin_unloaded`
-- message components 兼容导出、别名构造和常用工厂
-- `session_waiter`
-- 旧插件共享单一 `LegacyContext`
-
-### 7.2 降级兼容
-
-这些能力可以运行，但不保证与历史实现完全等价：
-
-- `command_group`：当前会展平成普通命令名，不复刻旧的树状命令帮助与多层执行链。
-- legacy JSON-RPC handshake 转 v4 handler 描述时，只能近似恢复旧触发信息，原始 payload 会保留在 metadata 里。
-- `astrbot.core.*` 的深层 facade 只覆盖受支持的导入路径，不等于整个旧应用树。
-- `tool_loop_agent()` 当前是 compat local tool loop，并非完整复刻旧应用内部 agent 体系。
-
-### 7.3 仅导入兼容或明确不支持
-
-以下路径或能力要么只有导入兼容，要么明确不实现旧语义：
-
-- `astrbot.api.agent()`：显式 `NotImplementedError`
-- `astrbot.core.provider.provider` 中的 provider 基类与 embeddings/rerank 方法：导入可用，但方法是 stub
-- 没有可映射执行链路的旧 `filter.*` helper：显式 `NotImplementedError`
-
-兼容原则是“尽量保留可运行的旧插件路径”，不是“重新实现整个旧 AstrBot 应用”。
-
-## 8. 对插件作者的导入建议
-
-### 推荐的新代码（v4）
-
-```python
-from astrbot_sdk import Star, Context, MessageEvent
-from astrbot_sdk.decorators import on_command, on_message, provide_capability
-```
-
-### ~~仍受支持的旧代码~~（已弃用）
-
-> ⚠️ 以下导入路径已弃用，将在下个大版本移除。旧插件请使用 AstrBot 主程序运行。
-
-```python
-# 已弃用 - 请迁移到 v4 或使用主程序
-from astrbot_sdk.api.event import AstrMessageEvent
-from astrbot_sdk.api.star.context import Context
-from astrbot_sdk.api.event.filter import filter
-```
-
-### ~~旧包名 facade~~（已弃用）
-
-> ⚠️ 以下导入路径已弃用，将在下个大版本移除。
-
-```python
-# 已弃用 - 请迁移到 v4 或使用主程序
-from astrbot.api.star import Star
-from astrbot.core.utils.session_waiter import session_waiter
-```
-
-## 9. 本地开发与测试
-
-当前仓库已经提供一条受控的本地开发路径：
-
-- CLI：
-  - `astr dev --local` / `astrbot-sdk dev --local`
-  - `astrbot-sdk init`
-  - `astrbot-sdk validate`
-  - `astrbot-sdk build`
-- 稳定测试入口：`astrbot_sdk.testing`
-
-`astrbot_sdk.testing` 当前公开的稳定面包括：
-
-- `PluginHarness`
-- `LocalRuntimeConfig`
-- `MockContext`
-- `MockMessageEvent`
-- `MockLLMClient`
-- `MockPlatformClient`
-- `MockPeer`
-- `MockCapabilityRouter`
-- `InMemoryDB`
-- `InMemoryMemory`
-- `StdoutPlatformSink`
-- `RecordedSend`
-
-设计约束：
-
-- 本地 harness 复用真实的 `load_plugin()`、`HandlerDispatcher`、`CapabilityDispatcher`、`_legacy_runtime.py` 与 `_session_waiter.py`
-- `dev --local` 使用进程内 mock core，而不是重新发明一套并行 runtime
-- 同一次 `interactive` 会话会复用同一个 dispatcher / waiter manager / in-memory db / in-memory memory
-- `astrbot_sdk.testing` 是插件测试依赖的公开 API，minor 版本内保持兼容稳定
-
-## 10. 测试与维护约定
-
-- 当前主测试目录是 `tests_v4/`，覆盖 protocol、runtime、clients、compat facade、legacy plugin integration、top-level imports 与 integration flows。
-- 文档维护规则：
-  - capability 集合变化时，同时更新本文档与对应测试。
-  - compat 支持级别变化时，同时更新本文档、`CLAUDE.md` / `AGENTS.md` 备注以及相关契约测试。
-  - `refactor.md` 不再承载现状；出现冲突时，一律以本文档和代码/测试为准。
-
-## 11. 后续演进方向
-
-1. **当前版本**：兼容层已标记为 deprecated，触发 `DeprecationWarning`
-2. **下个大版本**：完全移除兼容层，SDK 只支持 v4 新插件
-3. 旧插件将由 AstrBot 主程序独立支持，不依赖 SDK 兼容层

CHANGELOG.md

@@ -1,47 +0,0 @@
-# Changelog
-
-## Unreleased
-
-### Plugin Environment Grouping
-
-v4 runtime now manages plugin Python environments as shared groups instead of
-always creating one `.venv` per plugin.
-
-Behavior changes:
-
-- Plugins are planned together before startup.
-- Plugins are grouped by `runtime.python` first, then by dependency
-  compatibility.
-- Compatible plugins share one interpreter environment under
-  `.astrbot/envs/<group_id>`.
-- Incompatible plugins are split into separate groups automatically.
-- Each plugin still runs in its own worker process. Only the Python
-  environment is shared.
-
-Environment planning details:
-
-- Group planning writes artifacts to `.astrbot/groups/`, `.astrbot/locks/`,
-  and `.astrbot/envs/`.
-- Lockfiles are generated from grouped `requirements.txt` inputs.
-- Exact pinned requirements such as `package==1.2.3` use a fast compatibility
-  check before falling back to `uv pip compile`.
-- If a plugin cannot produce a valid lockfile even when isolated, that plugin
-  is skipped without blocking other plugins.
-
-Compatibility notes:
-
-- Existing plugin manifest structure is unchanged.
-- Existing `PluginEnvironmentManager.prepare_environment(plugin)` call sites
-  remain valid.
-- Shared environments still use `--system-site-packages` in this phase to
-  reduce regressions for plugins that implicitly rely on host packages.
-- Legacy plugin-local `.venv` directories and `.astrbot-worker-state.json`
-  files are no longer part of the active v4 environment path, but they are not
-  deleted automatically.
-
-Operational notes:
-
-- Startup now performs a planning step before worker launch.
-- Shared environment state is tracked with `.group-venv-state.json` inside
-  each grouped environment.
-- Stale `.astrbot` group artifacts are cleaned up on replanning.

COMPATIBILITY_MATRIX.md

@@ -1,63 +0,0 @@
-# AstrBot 兼容矩阵
-
-`src-new/astrbot_sdk` 是 v4 真源，`src-new/astrbot` 只承担旧插件兼容门面。
-本文件记录当前兼容合同，避免把整个旧 `astrBot/core` 重新搬回新架构。
-
-## 边界
-
-| 级别 | 路径 | 策略 |
-| --- | --- | --- |
-| 一级 | `astrbot.api.*` | 优先做真实兼容 |
-| 二级 | `astrbot.core.*` 常见深路径 | 只有真实插件命中时才补薄 shim |
-| 三级 | 旧应用内部系统 | 不做树级复刻 |
-
-## 当前兼容面
-
-| 模块/路径 | 状态 | 说明 |
-| --- | --- | --- |
-| `astrbot.api` | 真实兼容 | 根入口、常见子模块可导入 |
-| `astrbot.api.all` | 真实兼容 | 聚合入口对齐旧公开面 |
-| `astrbot.api.event/filter/star/platform/provider/util` | 真实兼容 | 高频插件入口已收敛到 `src-new/astrbot` facade |
-| `astrbot.api.message_components` | 真实兼容 | 旧消息组件导入路径可用 |
-| `astrbot.core` | 导入兼容 | `AstrBotConfig`、`sp`、`logger`、`html_renderer` 门面可导入 |
-| `astrbot.core.config.*` | 导入兼容 | 当前只对齐 `AstrBotConfig` |
-| `astrbot.core.message.components` | 真实兼容 | 走 v4 消息组件 compat 实现 |
-| `astrbot.core.message.message_event_result` | 真实兼容 | 走 v4 事件结果 compat 实现 |
-| `astrbot.core.utils.session_waiter` | 真实兼容 | 已接上真实 follow-up message 路由 |
-| `astrbot.core.platform.*` | 导入兼容 / 部分真实兼容 | 高频模型与事件路径可导入，平台适配器注册仍 loud-fail |
-
-## 兼容合同测试
-
-以下合同由仓库内测试显式守护：
-
-- [tests_v4/test_compatibility_contract.py](/d:/GitObjectsOwn/astrbot-sdk/tests_v4/test_compatibility_contract.py)
-  - 一级：`astrbot.api`、`astrbot.api.all`、`astrbot.api.message_components`、`astrbot.api.event`、`astrbot.api.event.filter`、`astrbot.api.star`、`astrbot.api.platform`、`astrbot.api.provider`、`astrbot.api.util`
-  - 二级：`astrbot.core`、`astrbot.core.config.*`、`astrbot.core.message.*`、`astrbot.core.platform.*`、`astrbot.core.utils.session_waiter`
-- [tests_v4/test_external_plugin_smoke.py](/d:/GitObjectsOwn/astrbot-sdk/tests_v4/test_external_plugin_smoke.py)
-  - 外部真实插件矩阵必须走 `SupervisorRuntime -> Worker -> handler.invoke` 真链路
-  - 不以单独 `load_plugin()` 成功替代运行时兼容结论
-
-## 显式未支持
-
-以下能力仍保持 loud-fail，不伪造旧执行链：
-
-- `astrbot.api.agent`
-- `astrbot.api` / `astrbot.core` 的旧 html 渲染系统
-- `register_platform_adapter`
-- 旧 LLM hook / plugin hook / result decorate hook 的完整执行链
-
-## 真实插件矩阵
-
-矩阵清单位于 [tests_v4/external_plugin_matrix.json](/d:/GitObjectsOwn/astrbot-sdk/tests_v4/external_plugin_matrix.json)。
-当前标准是：
-
-1. 可加载
-2. 可初始化
-3. 至少一个代表命令在 `SupervisorRuntime -> Worker -> handler.invoke` 真链路下通过
-
-已纳入矩阵：
-
-- `astrbot_plugin_hapi_connector`
-- `astrbot_plugin_endfield`
-
-不 vendoring 第三方源码；测试时按需 clone。