Update docs: architecture + plugin guide for v0.2.1 enhancements

2026-06-10 13:09:52 +08:00
parent 1cbe52174d
commit 5e23778d90
2 changed files with 90 additions and 2 deletions
@@ -5075,4 +5075,63 @@ logger.error("错误信息", exc_info=True)
   - Stack Overflow：解决具体技术问题
   - 开发者群组：实时交流和协作

-通过遵循本指南，您可以开发出高质量的SenSu插件，为用户提供有价值的功能，同时为插件生态系统做出贡献。祝您开发顺利！
+通过遵循本指南，您可以开发出高质量的SenSu插件，为用户提供有价值的功能，同时为插件生态系统做出贡献。祝您开发顺利！
+---
+
+## 九、v0.2.1 新增 API（已实现）
+
+### 9.1 PluginStatus 状态枚举
+
+```python
+from fmfuncs.plugin_status import PluginStatus
+
+# 插件生命周期状态
+PluginStatus.UNLOADED    # "unloaded"
+PluginStatus.LOADING     # "loading"
+PluginStatus.LOADED      # "loaded"
+PluginStatus.RUNNING     # "running"
+PluginStatus.ERROR       # "error"
+PluginStatus.STOPPING    # "stopping"
+PluginStatus.STOPPED     # "stopped"
+```
+
+用法：`plugin_service.plugin_status["my_plugin"] = PluginStatus.RUNNING`
+
+### 9.2 PluginError 异常层级
+
+```python
+from fmfuncs.plugin_error import (
+    PluginError,            # 基础异常
+    PluginLoadError,        # 加载失败
+    PluginConfigError,      # 配置错误
+    PluginPermissionError,  # 权限不足
+    PluginCommandError,     # 命令执行错误
+)
+
+# 抛出
+raise PluginConfigError("缺少必需配置项: name", plugin_name="my_plugin")
+```
+
+### 9.3 PluginBridge.subscribe_plugin()
+
+```python
+# 便捷订阅方法（同时注册到 CoreBridge 和插件订阅表）
+self.bridge.subscribe_plugin("test.event", self._handler, "my_plugin")
+```
+
+### 9.4 PluginNetworkBridge 跨插件数据
+
+```python
+# 设置数据接收通道
+await self.network_bridge.setup_data_transfer("status_update", self._on_data)
+
+# 向其他插件发送数据
+await self.network_bridge.send_data("target_plugin", "status_update", {"key": "val"})
+```
+
+### 9.5 配置验证
+
+框架在插件加载时自动检查：
+- `config.yaml` 必须存在且可解析
+- 必需字段：`name`, `version`
+- 版本号格式建议遵循 semver