新增插件指引网页

Plugins/WPSCombatSystem/combat_plugin_adventure.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Optional
+from typing import Optional, Sequence
 
 from PWF.Convention.Runtime.GlobalConfig import ConsoleFrontColor, ProjectConfig
 
+from Plugins.WPSAPI import GuideEntry, GuideSection
 from .combat_plugin_base import WPSCombatBase
+from .combat_models import CombatConfig
 
 
 logger: ProjectConfig = ProjectConfig()
@@ -16,6 +18,133 @@ logger: ProjectConfig = ProjectConfig()
 class WPSCombatAdventure(WPSCombatBase):
     """冒险系统插件"""
     
+    def get_guide_subtitle(self) -> str:
+        return "阶段式 PVE 冒险，产出装备与素材"
+
+    def collect_command_entries(self) -> Sequence[GuideEntry]:
+        return (
+            GuideEntry(
+                title="冒险 开始",
+                identifier="冒险 开始 [食物...]",
+                description="启动第 1 阶段冒险，可额外投入食物缩短时间并提升成功率。",
+                metadata={"别名": "start"},
+                icon="🚀",
+                tags=("阶段1", "需未受伤"),
+                details=[
+                    {
+                        "type": "steps",
+                        "items": [
+                            "检查自身状态，确认未处于受伤或其他冒险中。",
+                            "可选：准备食物 `food_id` 列表；每个食物将被立即消耗。",
+                            "系统计算预计耗时、成功率并生成冒险记录。",
+                            "创建时钟任务，时间到后自动结算。",
+                        ],
+                    },
+                    "结算时会根据装备强度与运势发放奖励。",
+                ],
+            ),
+            GuideEntry(
+                title="继续冒险",
+                identifier="冒险 / 继续冒险",
+                description="在已有链路下进入下一阶段或查看剩余时间。",
+                metadata={"别名": "adventure / continue"},
+                icon="⏱️",
+                tags=("阶段推进",),
+                details=[
+                    {
+                        "type": "steps",
+                        "items": [
+                            "查询当前冒险记录，若已在倒计时阶段则返回剩余时间。",
+                            "如冒险链完成并准备进入下一阶段，可再次投喂食物并启动。",
+                            "系统保持阶段编号，累计奖励与时间。",
+                        ],
+                    }
+                ],
+            ),
+            GuideEntry(
+                title="冒险 停止",
+                identifier="冒险 停止 / 放弃",
+                description="放弃当前冒险链，结算状态并清空倒计时。",
+                metadata={"别名": "放弃 / 停止"},
+                icon="🛑",
+                tags=("风险",),
+                details=[
+                    "放弃后当前阶段奖励作废，未来可从第 1 阶段重开。",
+                    "若系统已开始结算，则命令会提示等待完成。",
+                ],
+            ),
+        )
+
+    def collect_guide_entries(self) -> Sequence[GuideEntry]:
+        return (
+            GuideEntry(
+                title="冒险阶段",
+                description="Adventure 链路包含多个阶段，难度逐渐提升，奖励也随之增加。",
+                icon="⚙️",
+                details=[
+                    {
+                        "type": "list",
+                        "items": [
+                            "阶段时间：基础 15 分钟，最高不超过 24 小时。",
+                            "投喂食物：每份食物提供额外时间与成功率加成。",
+                            "装备影响：装备强度越高，成功率越高且时间越短。",
+                            "运势影响：由运势系统提供当前整点的幸运值，用于修正成功率。",
+                        ],
+                    }
+                ],
+            ),
+            GuideEntry(
+                title="奖励构成",
+                description="冒险完成后会发放积分、装备、材料、纪念品等。",
+                icon="🎁",
+                details=[
+                    {
+                        "type": "list",
+                        "items": [
+                            "基础积分奖励随阶段提升。",
+                            "装备掉落根据稀有度加权抽取。",
+                            "部分阶段触发事件可获得药剂、种子或纪念品。",
+                        ],
+                    }
+                ],
+            ),
+        )
+
+    def collect_additional_sections(self) -> Sequence[GuideSection]:
+        sections = list(super().collect_additional_sections())
+        adventure_config_entries: List[GuideEntry] = []
+        config_labels = {
+            "combat_adventure_base_time": "阶段起始时间 (分钟)",
+            "combat_adventure_max_time": "时间上限 (分钟)",
+            "combat_food_support_time": "单个食物提供时间 (分钟)",
+            "combat_adventure_base_success_rate": "基础成功率",
+            "combat_adventure_stage_penalty": "阶段成功率衰减",
+            "combat_adventure_equipment_coeff": "装备强度加成系数",
+            "combat_adventure_fortune_coeff": "运势加成系数",
+            "combat_time_reduction_divisor": "时间缩减除数",
+        }
+        for key, label in config_labels.items():
+            value = CombatConfig.get(key)
+            adventure_config_entries.append(
+                GuideEntry(
+                    title=label,
+                    identifier=key,
+                    description=f"{value}",
+                    category="配置项",
+                    icon="📐",
+                )
+            )
+        sections.append(
+            GuideSection(
+                title="冒险参数一览",
+                entries=adventure_config_entries,
+                layout="grid",
+                section_id="adventure-config",
+                description="核心公式与系数决定冒险耗时、成功率与奖励结构。",
+            )
+        )
+        return tuple(sections)
+
     def is_enable_plugin(self) -> bool:
         return True