新增插件指引网页

Plugins/WPSBackpackSystem.py

@@ -2,14 +2,14 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import Dict, List, Optional, override
+from typing import Dict, List, Optional, Sequence, override
 
 from PWF.Convention.Runtime.Architecture import Architecture
 from PWF.Convention.Runtime.GlobalConfig import ConsoleFrontColor, ProjectConfig
 from PWF.CoreModules.database import get_db
 from PWF.CoreModules.flags import get_internal_debug
 
-from .WPSAPI import WPSAPI
+from .WPSAPI import GuideEntry, GuideSection, WPSAPI
 
 logger: ProjectConfig = Architecture.Get(ProjectConfig)
 
@@ -58,6 +58,48 @@ class WPSBackpackSystem(WPSAPI):
     ITEMS_TABLE = "backpack_items"
     USER_ITEMS_TABLE = "backpack_user_items"
 
+    def get_guide_subtitle(self) -> str:
+        return "管理物品注册、背包存储与查询的核心系统"
+
+    def get_guide_metadata(self) -> Dict[str, str]:
+        return {
+            "物品缓存数": str(len(self._item_cache)),
+            "数据表": f"{self.ITEMS_TABLE}, {self.USER_ITEMS_TABLE}",
+        }
+
+    def collect_command_entries(self) -> Sequence[GuideEntry]:
+        return (
+            {
+                "title": "背包",
+                "identifier": "背包",
+                "description": "以稀有度分组展示用户当前携带物品。",
+                "metadata": {"别名": "backpack"},
+            },
+        )
+
+    def collect_guide_entries(self) -> Sequence[GuideEntry]:
+        tier_labels = ", ".join(tier.display_name for tier in BackpackItemTier)
+        return (
+            {
+                "title": "物品注册",
+                "description": (
+                    "`register_item(item_id, name, tier, description)` "
+                    "将物品写入背包表，重复调用会更新名称、稀有度和描述。"
+                ),
+            },
+            {
+                "title": "稀有度体系",
+                "description": f"支持稀有度：{tier_labels}，调用 `to_markdown_label` 可渲染彩色标签。",
+            },
+            {
+                "title": "库存操作",
+                "description": (
+                    "`add_item` / `set_item_quantity` / `_get_user_quantity` "
+                    "确保用户物品数量保持非负，并自动创建记录。"
+                ),
+            },
+        )
+
     def __init__(self) -> None:
         super().__init__()
         self._item_cache: Dict[str, BackpackItemDefinition] = {}
@@ -124,6 +166,50 @@ class WPSBackpackSystem(WPSAPI):
                 description=description,
             )
 
+    def _iter_registered_items(self) -> Sequence[BackpackItemDefinition]:
+        try:
+            if not self._item_cache:
+                self._warm_item_cache()
+        except Exception:
+            return ()
+        return tuple(self._item_cache.values())
+
+    def collect_additional_sections(self) -> Sequence[GuideSection]:
+        sections = list(super().collect_additional_sections())
+        item_entries: List[GuideEntry] = []
+        tier_icons = {
+            BackpackItemTier.COMMON: "🪙",
+            BackpackItemTier.RARE: "💠",
+            BackpackItemTier.EPIC: "⚡",
+            BackpackItemTier.LEGENDARY: "🌟",
+        }
+        for definition in self._iter_registered_items():
+            item_entries.append(
+                GuideEntry(
+                    title=definition.name,
+                    identifier=definition.item_id,
+                    description=definition.description or "（暂无描述）",
+                    category="背包物品",
+                    metadata={
+                        "稀有度": definition.tier.display_name,
+                    },
+                    icon=tier_icons.get(definition.tier, "🎁"),
+                    tags=(definition.tier.display_name,),
+                    group=definition.tier.display_name,
+                )
+            )
+        if item_entries:
+            sections.append(
+                GuideSection(
+                    title="物品图鉴",
+                    entries=item_entries,
+                    layout="grid",
+                    section_id="backpack-items",
+                    description="当前已注册的背包物品列表，按稀有度分组展示。",
+                )
+            )
+        return tuple(sections)
+
     # region 对外接口
 
     def register_item(