feat(picmenu): finalize menu contracts

- Enforce external menu configuration and adapter help visibility contracts
- Document current-command help navigation behavior and Python 3.10 compatibility
- Reorganize tests by runtime module and regenerate external menu schema

Co-authored-by: Codex <codex@openai.com>

Author: lgc2333

CONTEXT.md

@@ -27,7 +27,7 @@ Input supplied by a user to locate a plugin or function item in a help menu.
 The deterministic display order of plugin menu items.
 
 **菜单索引**:
-The 1-based position of a menu item in the current sorted menu snapshot. It is not a stable identifier.
+The 1-based position of a menu item in the current discoverable sorted menu snapshot. A Help view must not advertise an index when its target is absent from that snapshot. It is not a stable identifier.
 
 **同拼音菜单项**:
 Plugin menu items with the same pinyin sort key.

README.md

@@ -247,6 +247,8 @@ Telegram：[@lgc2333](https://t.me/lgc2333)
 - 修复外部菜单目录扫描异常可能导致菜单收集失败的问题
 - 优化菜单排序逻辑，名称拼音相同的插件会按插件 ID 保持稳定顺序
 - 限制 `plugin:` 资源路径只能访问目标插件模块内的文件，避免绝对路径、路径越界和符号链接越界访问
+- 外部菜单的 `pmn` 配置改为严格校验，未支持的字段将被拒绝。
+- 修复 Python 3.10 / Pydantic v1 的兼容性问题
 
 ### 0.4.2
 

defs/ExternalPluginInfo.json

@@ -1,6 +1,7 @@
 {
   "$defs": {
     "ExternalPMNData": {
+      "additionalProperties": false,
       "properties": {
         "hidden": { "default": false, "title": "Hidden", "type": "boolean" },
         "markdown": { "default": false, "title": "Markdown", "type": "boolean" },
@@ -44,7 +45,11 @@
     }
   },
   "properties": {
-    "name": { "default": null, "title": "Name", "type": "string" },
+    "name": {
+      "anyOf": [{ "type": "string" }, { "type": "null" }],
+      "default": null,
+      "title": "Name"
+    },
     "author": {
       "anyOf": [{ "type": "string" }, { "type": "null" }],
       "default": null,
@@ -66,10 +71,12 @@
       "title": "Usage"
     },
     "funcs": {
+      "anyOf": [
+        { "items": { "$ref": "#/$defs/PMDataItem" }, "type": "array" },
+        { "type": "null" }
+      ],
       "default": null,
-      "items": { "$ref": "#/$defs/PMDataItem" },
-      "title": "Funcs",
-      "type": "array"
+      "title": "Funcs"
     },
     "pmn": {
       "$ref": "#/$defs/ExternalPMNData",

docs/adr/0002-resolve-menu-queries-by-snapshot-index-name-and-pinyin.md

@@ -6,4 +6,4 @@ status: accepted
 
 PicMenu Next orders plugin menu items by pinyin sort key and then by plugin ID, removing incidental plugin-load ordering when names share the same pinyin. A numeric query selects the 1-based position in that current sorted snapshot, not a stable identity; the position may change as menu items change.
 
-A pure positive number is resolved as an index before name or pinyin matching. Zero and all-zero strings remain fuzzy queries; other queries combine the displayed name at 60% and pinyin at 40%, require a score of 60, and never replace displayed names with pinyin. This keeps direct selection predictable while retaining Chinese and romanized discovery for plugin and function items.
+A pure positive number is resolved as an index before name or pinyin matching. Zero and all-zero strings remain fuzzy queries; other queries combine the displayed name at 60% and pinyin at 40%, require a score of 60, and never replace displayed names with pinyin. Any index rendered as navigation guidance must resolve from the same discoverable snapshot under the stated help invocation. Current-command Help first uses the ordinary snapshot and uses a `-H` snapshot only for its hidden-item retry, so its guidance remains resolvable. This keeps direct selection predictable while retaining Chinese and romanized discovery for plugin and function items.

docs/adr/0007-store-adapter-support-as-menu-data.md

@@ -6,4 +6,4 @@ status: accepted
 
 Supported adapters are plugin-level menu data, not transient metadata or PicMenu extension configuration. PicMenu Next stores them internally as `set[str] | None`, accepts an array in external JSON/YAML/TOML config, collects `PluginMetadata.supported_adapters`, and lets external config replace that field as a whole so loaded and external plugin menus share one visibility model.
 
-Missing or `null` adapter data means all adapters are supported, while an explicit empty list supports none and hides the plugin from ordinary menu discovery. `-H` or `--show-hidden` includes that adapter-hidden plugin, but does not make it compatible with the current adapter. Unresolvable entries are ignored without failing the menu but do not establish support. Adapter hiding is derived from final menu data before Mixins run, so a Mixin may override it; it affects only ordinary menu visibility, not Help interception for a command the user has already invoked.
+Missing or `null` adapter data means all adapters are supported, while an explicit empty list supports none and hides the plugin from ordinary menu discovery. `-H` or `--show-hidden` includes that adapter-hidden plugin, but does not make it compatible with the current adapter. Unresolvable entries are ignored without failing the menu but do not establish support. Adapter hiding is derived from final menu data before Mixins run, so a Mixin may override it. It affects ordinary menu visibility and the first current-command Help attempt; that Help request retries in the `-H` snapshot when ordinary discovery finds no view, so any numeric navigation guidance remains valid.

docs/adr/0013-render-intercepted-alconna-help-without-silence.md

@@ -6,6 +6,6 @@ status: accepted
 
 Normal help-menu queries respect hidden plugins and hidden function items: if a plugin is hidden, users cannot find it through the ordinary menu command, and explicit display of hidden items remains subject to hidden-item permission policy. Adapter support can hide a plugin as part of the menu data transformation path, and later Mixin changes take precedence over that derived hidden state. Alconna Help interception is different because the user has already invoked a concrete command, so PicMenu Next must return Help for that command regardless of plugin or function-item hidden state. It uses the same data path as ordinary plugin and function detail rendering; when the current command has no registered function item, it may create a temporary item for that render.
 
-Alconna decides whether a `-h` or `--help` invocation requests output. Once PicMenu Next receives such a request for a recognized command, it must return a response. It first attempts a PicMenu help view with adapter filtering disabled but ordinary hidden-state filtering intact. Only a normal no-result, such as a missing plugin or function item (including an item hidden by that first attempt), triggers one retry with hidden-state filtering relaxed. If that retry still has no view, PicMenu Next returns Alconna's original help output.
+Alconna decides whether a `-h` or `--help` invocation requests output. Once PicMenu Next receives such a request for a recognized command, it must return a response. It first attempts a PicMenu help view with the same adapter and hidden-state filtering as ordinary menu discovery. Only a normal no-result, such as a missing plugin or function item (including an item hidden by that first attempt), triggers one retry with hidden-state filtering relaxed. That retry uses the `-H` snapshot, including adapter-hidden plugins, so any numeric menu-navigation guidance remains resolvable. If that retry still has no view, PicMenu Next returns Alconna's original help output.
 
 All PicMenu interception steps are protected as one operation. Any ordinary exception, including command ownership resolution, context injection, Mixin execution, or template rendering, is logged with `logger.exception` together with the command path and plugin ID, then immediately returns Alconna's original help output without a hidden-state retry. A failed interception must never turn an Alconna help request into silence.

nonebot_plugin_picmenu_next/__main__.py

@@ -222,7 +222,6 @@ async def render_menu(
     q_plugin: str | None = None,
     q_function: str | None = None,
     show_hidden: bool = False,
-    check_adapter_support: bool = True,
 ) -> tuple[UniMessage | None, PMNPluginInfo | None, PMDataItem | None]: ...
 
 
@@ -236,7 +235,6 @@ async def render_menu(
     alc_command: Alconna | None = None,
     alc_detail_des: str | None = None,
     show_hidden: bool = False,
-    check_adapter_support: bool = True,
 ) -> tuple[UniMessage | None, PMNPluginInfo | None, PMDataItem | None]: ...
 
 
@@ -250,11 +248,8 @@ async def render_menu(
     alc_command: Alconna | None = None,
     alc_detail_des: str | None = None,
     show_hidden: bool = False,
-    check_adapter_support: bool = True,
 ) -> tuple[UniMessage | None, PMNPluginInfo | None, PMDataItem | None]:
-    infos = get_infos()
-    if check_adapter_support:
-        infos = filter_unsupported_adapters(infos, bot.adapter)
+    infos = filter_unsupported_adapters(get_infos(), bot.adapter)
     infos = await resolve_main_mixin(infos)
     if not show_hidden:
         infos = [x for x in infos if not x.pmn.hidden]
@@ -447,7 +442,6 @@ async def output_converter(
                     alc_command=self.command,
                     alc_detail_des=content,
                     show_hidden=show_hidden,
-                    check_adapter_support=False,
                 )
                 if msg:
                     return msg

pyproject.toml

@@ -46,7 +46,7 @@ build-backend = "hatchling.build"
 path = "nonebot_plugin_picmenu_next/__init__.py"
 
 [tool.poe.tasks]
-gen-defs.cmd = "uv run scripts/gen_defs.py"
+gen-defs.shell = "uv run scripts/gen_defs.py && pnpx prettier -cw defs"
 test.cmd = "pytest"
 coverage.cmd = "pytest --cov=nonebot_plugin_picmenu_next --cov-branch --cov-report=term-missing"
 

scripts/gen_defs.py

@@ -5,7 +5,11 @@
 
 import nonebot
 
-nonebot.init(localstore_use_cwd=True)
+nonebot.init(
+    localstore_cache_dir="temp/cache",
+    localstore_config_dir="temp/config",
+    localstore_data_dir="temp/data",
+)
 
 nonebot.require("nonebot_plugin_picmenu_next")