Merge pull request #216 from PallasBot/feat/core-devx

feat(core-devx): plugin_sdk、pb_core 与开发体验路线 M0–M4

Author: TogetsuDo

.github/workflows/ci.yml

@@ -28,7 +28,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --dev
+          # core plugin matrix 测试会加载 kernel/LLM 与分片 coord（需 sqlalchemy、redis）
+          uv sync --dev --extra pg --extra coord-redis
 
       - name: Run Ruff linting
         run: |

docs/architecture/core-devx-roadmap.md

@@ -0,0 +1,54 @@
+# 热重载分级（L1 / L2 / L3）
+
+> 与 [core-devx-roadmap · P3](core-devx-roadmap.md#p3--热重载分级) 对齐。  
+> **现状**：L1 已成熟；L2/L3 以文档与 `reload_policy` 解析桩为主，CLI `pallas plugin reload` 尚未落地。
+
+## 三级对照
+
+| 级别 | 名称 | 变更内容 | 生效方式 | 现状 |
+| --- | --- | --- | --- | --- |
+| **L1** | 配置 | `config.py` 字段 → `webui.json` | `install_hot_reload_config` 保存后立即 reload | ✅ 默认路径 |
+| **L2** | 元数据 | `PluginMetadata.extra`、help 索引、ingress route | 保存后重读声明 / 重建索引（**不**卸载 matcher） | 部分（save hook）；`reload_policy: metadata` 预留 |
+| **L3** | 插件代码 | Python 模块变更 | 受控 reload 或提示进程重启 | ❌ 默认需重启 |
+
+## 明确不做
+
+- NoneBot matcher 级热卸载/重载**不作为默认运维路径**（见 [pallas-cli.md](pallas-cli.md)）。
+- 扩展 pip 包安装：`extension_install` 仍返回 `needs_restart`；与 **牛牛重启**（`pb_core`）共用调度 API。
+
+## `reload_policy`（extra 可选键）
+
+在 `PluginMetadata.extra` 声明插件作者期望的重载粒度（供能力总览与未来 CLI 读取）：
+
+| 值 | 含义 |
+| --- | --- |
+| `config_only` | 仅 L1（**默认**；与现网一致） |
+| `metadata` | L2：允许重读 extra / help / ingress，不卸载 matcher |
+| `full` | L3：尝试重载模块；失败则提示重启 |
+
+解析 API：`src.features.plugin_reload.reload_policy_from_metadata()`。
+
+示例：
+
+```python
+extra={
+    ...
+    "reload_policy": "config_only",
+}
+```
+
+## 运维入口
+
+| 场景 | 推荐 |
+| --- | --- |
+| 改插件开关/阈值 | WebUI **插件** 页保存（L1） |
+| 改命令权限 / CD | WebUI **命令权限** / **命令冷却**（L1） |
+| 改 help / ingress 声明 | 暂需重启；L2 落地后按 `reload_policy` 提示 |
+| 改 Python 代码 | 重启 Bot；群内 **牛牛重启** 或 `pallas restart` |
+| 安装官方扩展 | WebUI 插件商店；勾选「安装并重启」或手动重启 |
+
+## 相关文档
+
+- [WebUI 配置与热重载](../common/webui/README.md)
+- [settings-storage.md](settings-storage.md)
+- [core-devx-roadmap.md](core-devx-roadmap.md)

docs/architecture/hot-reload-tiers.md

@@ -56,6 +56,8 @@
 
 ## WebUI 配置与命令权限
 
+- **`PluginMetadata.extra` 键名表**（`command_permissions`、`plugin_storage`、`ingress_route` 等）：见 [core-devx-roadmap.md · 内核键名约定](core-devx-roadmap.md#内核键名约定)。
+- **新内核插件包名**：`pb_<role>`（如 `pb_core`、`pb_webui`、`pb_protocol`；`pb` = Pallas-Bot，与 NoneBot 的 `nb` 对齐）。历史 `pallas_webui` / `pallas_protocol` 改名见 [core-devx-roadmap · P7](core-devx-roadmap.md#p7--历史插件-pb_-改名m5)。
 - 需在 WebUI 保存 **`webui.json`** 后立即生效的插件配置：在 `config.py` 使用 `src.console.webui.install_hot_reload_config`（见 [WebUI 插件配置](../common/webui/README.md)）；已有自定义缓存的插件可登记到 `plugin_webui_registry`（如决斗插件）。
 - 可配置命令权限：在 `PluginMetadata.extra` 声明 `command_permissions`，matcher 使用 `src.features.cmd_perm.permission_for_command`（见 [cmd_perm](../common/cmd_perm/README.md)）。
 - 命令冷却：在 handler 内使用 `src.features.command_limits`（见 [command_limits](../common/command_limits/README.md)）；可在 `extra["command_limits"]` 声明默认 CD 供文档与后续扩展。

docs/architecture/plugin-convention.md

@@ -12,6 +12,8 @@
 
 命令权限说明见 [cmd_perm](../cmd_perm/README.md)。
 
+**热重载分级**（L1 配置 / L2 元数据 / L3 代码）：见 [hot-reload-tiers.md](../../architecture/hot-reload-tiers.md)。插件可在 `extra["reload_policy"]` 声明期望粒度（默认 `config_only`）。
+
 ## 插件接入热重载
 
 在 `config.py` 末尾：

docs/common/webui/README.md

@@ -9,6 +9,7 @@
 | PUT | `/plugins/help-menu-visibility` | 是 | 更新帮助可见性 |
 | GET | `/plugins/global-disable` | | 全局禁用插件名集合 |
 | PUT | `/plugins/global-disable` | 是 | 批量禁用/启用（保护核心插件） |
+| GET | `/plugins/capabilities` | | 插件能力聚合（命令权限/CD、LLM tools、storage keys、`reload_policy`） |
 | GET | `/plugins/group-fleet-whitelist` | | 群舰队白名单插件 |
 | PUT | `/plugins/group-fleet-whitelist` | 是 | 更新舰队白名单 |
 
@@ -49,6 +50,7 @@ PUT 成功后：
 ## 前端对应
 
 - `fetchPlugins`、`fetchPluginConfig`、`putPluginConfig`
+- `fetchPluginCapabilities`（插件页「能力总览」与卡片预览）
 - `fetchHelpMenuVisibility`、`putHelpMenuVisibility`
 - `fetchGlobalPluginDisable`、`putGlobalPluginDisable`
 - `fetchGroupFleetWhitelist`、`putGroupFleetWhitelist`

docs/common/webui/api/02-plugins.md

@@ -23,6 +23,8 @@
 | [插件规范](../architecture/plugin-convention.md) | `src/plugins` 约定 |
 | [站点定制](../architecture/site-customization-and-updates.md) | `local/plugins`、官方扩展 |
 | [4.0 路线图](../architecture/pallas-4.0-roadmap.md) · [瘦身迁移](../architecture/pallas-4.0-slim.md) | core / extra |
+| [Core 开发体验路线](../architecture/core-devx-roadmap.md) | plugin_sdk、`pb_core`、M5 `pb_webui`/`pb_protocol` 改名 |
+| [热重载分级](../architecture/hot-reload-tiers.md) | L1 配置 / L2 元数据 / L3 代码 |
 | [Bot ↔ AI 仓](../architecture/pallas-ai-service.md) | LLM 协同 |
 | [cmd_perm](../common/cmd_perm/README.md) · [command_limits](../common/command_limits/README.md) | 权限与冷却 |
 | [WebUI 配置](../common/webui/README.md) · [message_scrub](../common/message_scrub/README.md) | 热重载与审查 |

docs/develop/README.md

@@ -46,8 +46,8 @@ extra_plugin_dirs = ["local/plugins"]
 local/plugins/praise_me/
 ├── __init__.py      # PluginMetadata + 注册 Matcher（保持短）
 ├── config.py        # Pydantic + WebUI 热重载
-├── store.py         # 读写 data/praise_me/ 下的 JSON（纯函数，便于测）
-└── handlers.py      # 三个命令的处理逻辑
+├── store.py         # 群级点赞计数（GroupPluginStorage + 纯函数，便于测）
+└── handlers.py      # 命令处理逻辑
 ```
 
 在仓库根执行：
@@ -95,34 +95,32 @@ get_config = plugin_webui.get
 
 ## 3、数据落盘（按群计数）
 
-点赞数按 **群** 存 JSON，路径用 `plugin_data_dir`，不要手写 `data/` 字符串。
+群级结构化状态优先走 **声明式 `plugin_storage` + `GroupPluginStorage`**（写入 `GroupConfig` 文档的 `plugin_storage` 字段，与 help / duel 等同源）。  
+**不要**再为这种小 JSON 手写 `data/<plugin>/groups/*.json`；`plugin_data_dir` 留给图片、导出、缓存等大文件（见 [插件结构 · 路径与持久化](structure.md)）。
+
+在 `store.py` 封装读写；纯函数 `add_praise` / `top_praisers` 便于单测：
 
 ```python
 # local/plugins/praise_me/store.py
 from __future__ import annotations
 
-import json
-from pathlib import Path
-
-from src.foundation.paths import plugin_data_dir
+from src.features.plugin_storage import GroupPluginStorage
 
+PLUGIN_NAME = "praise_me"
+COUNTS_KEY = "praise_counts"
 
-def counts_path(group_id: int) -> Path:
-    return plugin_data_dir("praise_me") / "groups" / f"{group_id}.json"
 
-
-def load_counts(group_id: int) -> dict[str, int]:
-    path = counts_path(group_id)
-    if not path.is_file():
+async def load_counts(group_id: int) -> dict[str, int]:
+    store = GroupPluginStorage(PLUGIN_NAME, group_id)
+    raw = await store.get(COUNTS_KEY)
+    if not isinstance(raw, dict):
         return {}
-    raw = json.loads(path.read_text(encoding="utf-8"))
     return {str(k): int(v) for k, v in raw.items()}
 
 
-def save_counts(group_id: int, counts: dict[str, int]) -> None:
-    path = counts_path(group_id)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(counts, ensure_ascii=False, indent=2), encoding="utf-8")
+async def save_counts(group_id: int, counts: dict[str, int]) -> None:
+    store = GroupPluginStorage(PLUGIN_NAME, group_id)
+    await store.set(COUNTS_KEY, counts)
 
 
 def add_praise(counts: dict[str, int], user_id: str) -> int:
@@ -135,26 +133,38 @@ def top_praisers(counts: dict[str, int], limit: int = 5) -> list[tuple[str, int]
     return pairs[:limit]
 ```
 
-文件会落在 `data/praise_me/groups/<群号>.json`，备份时整目录拷走即可。
+要点：
+
+- 存储键名 **`praise_counts`** 须在 `__init__.py` 的 `extra["plugin_storage"]` 声明（下一节一并写入）；未声明键在运行时会报 `PluginStorageKeyError`。
+- 备份/迁移时随群配置走库；WebUI **插件能力** API 可看到已声明的 storage keys。
 
 ---
 
 ## 4、元数据、权限与帮助图
 
 在 `__init__.py` 声明 `PluginMetadata`。帮助图文案格式见 [cmd_perm](../../common/cmd_perm/README.md)。
 
+**推荐**用 [plugin_sdk](../../architecture/core-devx-roadmap.md#p1--plugin_sdk) 注册口令（权限 + 可选 CD 一次封装）：
+
 ```python
 # local/plugins/praise_me/__init__.py
-from nonebot import on_command
 from nonebot.plugin import PluginMetadata
 
-from src.features.cmd_perm import group_message_permission_for_command
 from src.features.cmd_perm.metadata_defaults import (
     PLUGIN_EXTRA_VERSION,
     PLUGIN_HOMEPAGE,
     PLUGIN_MENU_TEMPLATE,
 )
 from src.features.cmd_perm.metadata_text import SCENE_GROUP, join_usage, usage_line
+from src.features.plugin_sdk import (
+    bind_alias_handlers,
+    command_limit_list,
+    command_limit_row,
+    command_perm_list,
+    command_perm_row,
+    group_command,
+)
+from src.features.plugin_storage import plugin_storage_list, plugin_storage_row
 
 from .handlers import handle_praise, handle_rank
 
@@ -171,13 +181,16 @@ __plugin_meta__ = PluginMetadata(
     extra={
         "version": PLUGIN_EXTRA_VERSION,
         "menu_template": PLUGIN_MENU_TEMPLATE,
-        "command_permissions": [
-            {"id": "praise_me.praise", "label": "牛牛赞我", "default": "everyone"},
-            {"id": "praise_me.rank", "label": "牛牛赞榜", "default": "everyone"},
-        ],
-        "command_limits": [
-            {"id": "praise_me.praise", "cd_sec": 0},
-        ],
+        "command_permissions": command_perm_list(
+            command_perm_row("praise_me.praise", "牛牛赞我", "everyone"),
+            command_perm_row("praise_me.rank", "牛牛赞榜", "everyone"),
+        ),
+        "command_limits": command_limit_list(
+            command_limit_row("praise_me.praise", 0),
+        ),
+        "plugin_storage": plugin_storage_list(
+            plugin_storage_row("praise_counts", scope="group", label="群内点赞计数"),
+        ),
         "menu_data": [
             {
                 "func": "牛牛赞我",
@@ -201,28 +214,20 @@ __plugin_meta__ = PluginMetadata(
     },
 )
 
-praise_cmd = on_command(
-    "牛牛赞我",
-    priority=5,
-    block=True,
-    permission=group_message_permission_for_command("praise_me.praise"),
-)
-rank_cmd = on_command(
-    "牛牛赞榜",
-    priority=5,
-    block=True,
-    permission=group_message_permission_for_command("praise_me.rank"),
-)
+praise_cmd = group_command("praise_me.praise", "牛牛赞我", cd_sec=0)
+rank_cmd = group_command("praise_me.rank", "牛牛赞榜", cd_sec=0)
 
-praise_cmd.handle()(handle_praise)
-rank_cmd.handle()(handle_rank)
+bind_alias_handlers(praise_cmd, handle_praise)
+bind_alias_handlers(rank_cmd, handle_rank)
 ```
 
+仍可直接 `on_command` + `group_message_permission_for_command`（见 [getting-started](getting-started.md)）；新插件优先 SDK。
+
 注意：
 
 - 命令 ID `praise_me.praise` 在 metadata、matcher、`command_limits` 里 **必须一致**。
 - `usage` / `trigger_condition` **不要**写「群管可用」——权限由 WebUI / cmd_perm 自动展示。
-- `command_limits` 里 `praise` 先填 `0`：冷却秒数改由配置驱动，在 handler 里用同一套 helper（下一节）。
+- `command_limits` 里 `praise` 填 `0`：默认 CD 由配置 `praise_cd_sec` 驱动，在 handler 里显式检查（下一节）。
 
 ---
 
@@ -232,60 +237,60 @@ rank_cmd.handle()(handle_rank)
 
 ```python
 # local/plugins/praise_me/handlers.py
-from nonebot.adapters.onebot.v11 import GroupMessageEvent
-
 from src.features.command_limits import is_command_cooldown_ready, refresh_command_cooldown
+from src.features.plugin_sdk import PluginHandlerContext
 
 from .config import get_config
 from .store import add_praise, load_counts, save_counts, top_praisers
 
 
-async def handle_praise(event: GroupMessageEvent):
-    from . import praise_cmd
-
+async def handle_praise(ctx: PluginHandlerContext) -> None:
     cfg = get_config()
     if not cfg.enable:
-        await praise_cmd.finish("点赞功能已关闭。")
+        await ctx.finish("点赞功能已关闭。")
 
     cd = cfg.praise_cd_sec
-    if cd > 0 and not await is_command_cooldown_ready(event, "praise_me.praise", cd):
-        await praise_cmd.finish(f"点太快啦，{cd} 秒后再赞吧。")
+    if cd > 0 and not await is_command_cooldown_ready(ctx.event, "praise_me.praise", cd):
+        await ctx.finish(f"点太快啦，{cd} 秒后再赞吧。")
     if cd > 0:
-        await refresh_command_cooldown(event, "praise_me.praise", cd)
+        await refresh_command_cooldown(ctx.event, "praise_me.praise", cd)
 
-    gid = event.group_id
-    uid = str(event.user_id)
-    counts = load_counts(gid)
+    gid = ctx.group_id
+    if gid is None:
+        return
+    uid = ctx.user_id
+    counts = await load_counts(gid)
     total = add_praise(counts, uid)
-    save_counts(gid, counts)
-
-    await praise_cmd.finish(cfg.praise_reply.format(total=total))
+    await save_counts(gid, counts)
 
+    await ctx.finish(cfg.praise_reply.format(total=total))
 
-async def handle_rank(event: GroupMessageEvent):
-    from . import rank_cmd
 
+async def handle_rank(ctx: PluginHandlerContext) -> None:
     cfg = get_config()
     if not cfg.enable:
-        await rank_cmd.finish("点赞功能已关闭。")
+        await ctx.finish("点赞功能已关闭。")
 
-    gid = event.group_id
-    uid = str(event.user_id)
-    counts = load_counts(gid)
+    gid = ctx.group_id
+    if gid is None:
+        return
+    uid = ctx.user_id
+    counts = await load_counts(gid)
     mine = counts.get(uid, 0)
     top = top_praisers(counts, limit=5)
 
     if not top:
-        await rank_cmd.finish("还没有人赞过牛牛，发送「牛牛赞我」抢第一个吧。")
+        await ctx.finish("还没有人赞过牛牛，发送「牛牛赞我」抢第一个吧。")
 
     lines = [f"{i}. QQ {qq} — {n} 赞" for i, (qq, n) in enumerate(top, start=1)]
     body = "\n".join(lines)
-    await rank_cmd.finish(f"本群赞榜 Top {len(top)}：\n{body}\n\n你的赞数：{mine}")
+    await ctx.finish(f"本群赞榜 Top {len(top)}：\n{body}\n\n你的赞数：{mine}")
 ```
 
 说明：
 
-- **冷却**：`is_command_cooldown_ready` / `refresh_command_cooldown` 的 key 为 `cmd_limit:{command_id}`，与 [command_limits](../../common/command_limits/README.md) 一致。
+- **存储**：`GroupPluginStorage` 读写须在 metadata 声明键；与 [command_limits](../../common/command_limits/README.md) 一样纳入能力总览。
+- **冷却**：`is_command_cooldown_ready` / `refresh_command_cooldown` 的 key 为 `cmd_limit:{command_id}`。
 - 配置里的 `praise_cd_sec` 为 0 时不做 CD 检查。
 - 本插件只读用户口令，不接 [message_scrub](../../common/message_scrub/README.md)；复读/做梦类才需要。
 
@@ -301,16 +306,16 @@ async def handle_rank(event: GroupMessageEvent):
 
 ## 6、拆文件与注册方式（小结）
 
-上面把 handler 写在 `handlers.py`，`__init__.py` 里用 `praise_cmd.handle()(handle_praise)` 注册。  
+上面把 handler 写在 `handlers.py`，`__init__.py` 里用 `bind_alias_handlers` 注册。  
 也可以直接在 `__init__.py` 里 `@praise_cmd.handle()`，但教程刻意练习 **入口轻量、业务外置**，与 [插件结构](structure.md) 一致。
 
-Matcher 选型见 [Matcher 决策树](../../skills/pallas-plugin-development/references/02-matchers-decision.md)：口令型用 `on_command` + `group_message_permission_for_command`。
+口令型优先 [plugin_sdk](../../architecture/core-devx-roadmap.md#p1--plugin_sdk) 的 `group_command`；选型见 [Matcher 决策树](../../skills/pallas-plugin-development/references/02-matchers-decision.md)。
 
 ---
 
 ## 7、测试
 
-纯函数 `store.py` 最适合单测，不必每次起真 Bot。
+`store.py` 里的纯函数最适合单测，不必每次起真 Bot；`GroupPluginStorage` 集成测法见 `tests/features/test_plugin_storage.py`。
 
 在 `tests/plugins/praise_me/test_store.py`（贡献主仓时）：
 
@@ -388,9 +393,10 @@ uv run pytest tests/plugins/praise_me/
 - [ ] `__init__.py` 短；`config` / `store` / `handlers` 已拆分
 - [ ] WebUI 热重载；handler 内 `get_config()`
 - [ ] 命令 ID 与 cmd_perm、matcher、`command_limits` 一致
+- [ ] 群/用户结构化状态：`extra["plugin_storage"]` + `GroupPluginStorage`（Cookbook §3–§4）
 - [ ] `usage` / `trigger_condition` 无写死权限句
-- [ ] 路径用 `plugin_data_dir`
-- [ ] 有最小单测（至少 `store`）
+- [ ] 大文件/缓存才用 `plugin_data_dir` / `resource_dir`
+- [ ] 有最小单测（至少 `store` 纯函数）
 - [ ] `docs/plugins/praise_me/README.md` 已写
 
 提交流程：[贡献与提交流程](../workflow.md)。
@@ -404,7 +410,7 @@ uv run pytest tests/plugins/praise_me/
 | 方向 | 提示 |
 | --- | --- |
 | 私聊查赞 | 再加 `on_command` + `private_message_permission_for_command` |
-| 全服榜 | 用 `src.foundation.db` 做持久化，或汇总多群 JSON |
+| 全服榜 | 用 `src.foundation.db` 做持久化，或 deploy 级 `plugin_storage` |
 | 帮助图样式 | 保持 `menu_data` 与 metadata 同步即可 |
 | 贡献主仓 | 挪到 `src/plugins/praise_me/`，PR 附测试与插件文档 |
 | 官方扩展包 | 4.0 玩法类可走扩展仓 + `uv sync --extra plugins-*` |