AstrBot/COMPATIBILITY_MATRIX.md

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
  • 一级：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
  • 外部真实插件矩阵必须走 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。 当前标准是：

1. 可加载
2. 可初始化
3. 至少一个代表命令在 SupervisorRuntime -> Worker -> handler.invoke 真链路下通过

已纳入矩阵：

• astrbot_plugin_hapi_connector
• astrbot_plugin_endfield

不 vendoring 第三方源码；测试时按需 clone。