feat: add static help image command (/鹿帮助) v2.1.2

.gitignore

@@ -205,4 +205,7 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
-.DS_Store
+.DS_Store
+
+# Runtime data (plugin local DB/cache/host config; never commit secrets)
+data/

CHANGELOG.md

@@ -1,18 +1,32 @@
-# Changelog
-
-## [2.1.1] - 2026-07-15
-
-### Fixed
-- **移除 t2i 渲染器禁用机制**: 单次网络或服务异常不再累计失败次数，也不会阻断后续渲染；每次请求都会重新调用 AstrBot 内置 t2i
-  - 停止读取和写入 `renderer_state.json`，已有遗留文件保持不变且不再生效
-  - 删除 `/重置渲染器`、`/reset_renderer`、`/重置t2i` 命令
-  - 删除 `RendererDisabledError` 及禁用状态查询、计数和重置接口
-
-### Changed
-- 删除 `DeerPipeHTMLRenderer` 与 `get_html_renderer()` 中废弃的 `use_t2i`、`jpeg_quality` 参数和属性
-- 增加渲染恢复路径及无 Playwright 运行依赖的回归测试
-
-## [2.1.0] - 2026-06-14
+# Changelog
+
+## [2.1.2] - 2026-07-21
+
+### Added
+- **固定帮助图命令**: 新增 `/鹿帮助`（别名 `🦌帮助` / `鹿菜单` / `deer_help` / `deerhelp`）
+  - 纯文本触发：`鹿帮助`、`🦌帮助`、`鹿菜单`、`deer_help`、`deerhelp`、`deer help`
+  - 运行时直接发送 `assets/help.png`，不依赖 t2i / Playwright
+  - 资源缺失时回退为文本提示
+  - 本地重生成脚本：`python scripts/gen_help_image.py`（仅开发机，非运行时依赖）
+
+### Fixed
+- **私聊/唤醒双发**: slash 命令与纯文本 regex 在私聊或 @Bot 时会同时激活；现在对帮助/打卡/鹿历共用 `event.extra` 幂等键，并在处理后 `stop_event`，避免重复发送
+- 纯文本英文帮助触发改为大小写不敏感；允许「鹿 帮助」类中文空格；「鹿 帮助」不再误走打卡
+- 纯文本打卡支持无空格 `🦌@用户` / `帮🦌@用户`（适配 message_str 把 @ 拼进文本的情况）
+
+## [2.1.1] - 2026-07-15
+
+### Fixed
+- **移除 t2i 渲染器禁用机制**: 单次网络或服务异常不再累计失败次数，也不会阻断后续渲染；每次请求都会重新调用 AstrBot 内置 t2i
+  - 停止读取和写入 `renderer_state.json`，已有遗留文件保持不变且不再生效
+  - 删除 `/重置渲染器`、`/reset_renderer`、`/重置t2i` 命令
+  - 删除 `RendererDisabledError` 及禁用状态查询、计数和重置接口
+
+### Changed
+- 删除 `DeerPipeHTMLRenderer` 与 `get_html_renderer()` 中废弃的 `use_t2i`、`jpeg_quality` 参数和属性
+- 增加渲染恢复路径及无 Playwright 运行依赖的回归测试
+
+## [2.1.0] - 2026-06-14
 
 ### Changed
 - **移除 Playwright 本地渲染依赖**: 不再支持 Playwright 作为渲染回退方案，统一使用 AstrBot 内置 t2i 服务渲染图片

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — astrbot_plugin_deerpipe
 
-AstrBot plugin for daily check-ins, monthly calendars, group leaderboards, and yearly deer maps.
+AstrBot plugin for daily check-ins, monthly calendars, yearly deer maps, and a static help image.
 
 ## Project overview
 
@@ -30,8 +30,9 @@ src/
   infrastructure/        # DB, config, cache, rendering, utilities
   shared/                # Constants, paths, shared helpers
 templates/               # HTML/CSS templates for rendered images
-resources/images/        # Bundled image assets
-assets/                  # README screenshots and previews
+resources/images/        # Bundled runtime image assets (characters, pipes, etc.)
+assets/                  # README previews + runtime static help.png
+scripts/                 # Dev-only helpers (e.g. gen_help_image.py)
 tests/                   # pytest suites and mocks
 ```
 
@@ -40,6 +41,7 @@ tests/                   # pytest suites and mocks
 - Keep `main.py` thin; put business logic in `src/application` or `src/domain`.
 - Store shared trigger patterns and constants in `src/shared/constants.py`.
 - Plain-text command triggers must stay narrow and anchored. Add regression tests whenever matching rules change.
+- Help image is a fixed file at `assets/help.png` (no t2i). After command surface changes, regenerate with `python scripts/gen_help_image.py`.
 - Use `async def` for AstrBot handlers and public service methods that touch I/O.
 - Keep `metadata.yaml`, `CHANGELOG.md`, and release-visible behavior in sync.
 

README.md

@@ -47,14 +47,14 @@
 
 - 📅 **精美日历** - 可视化展示每月打卡记录，支持自定义样式
 - 🗓️ **历史查询** - 支持查看任意年份和月份的打卡记录
-- 📊 **群排行榜** - 支持查看今日、昨日、本月的群打卡排行榜
 - 🤝 **好友互助** - 支持帮好友打卡，批量操作一键完成
 - 🎨 **批量报告** - 多人打卡时生成精美的批量结算报告
 - 🔄 **补卡功能** - 支持补录遗漏的打卡记录
 - 📈 **数据统计** - 自动统计打卡次数、连续天数等数据
 - 💾 **数据导入导出** - 支持 JSON 格式备份和恢复数据
 - 🤖 **LLM 工具** - 提供 AI 工具函数，支持智能查询打卡数据
 - 🔒 **隐私设置** - 可设置是否允许他人帮自己打卡
+- 🧾 **帮助图** - `/鹿帮助` 或 `鹿帮助` 发送固定命令说明图
 
 ---
 
@@ -106,30 +106,31 @@
 - **附加模式** (`additive`)：打卡2次显示为 打勾图标 + "+1"
 - **计数模式** (`count`)：打卡2次显示为 打勾图标 + "x2"
 
-**打勾图标说明：**
-- 开启 `show_check_mark`：签到日期会显示打勾图标 ✓
-- 关闭 `show_check_mark`：签到日期只显示打卡次数，不显示打勾图标
-
-### 渲染配置 (`rendering`)
-
-| 配置项 | 类型 | 说明 | 默认值 |
-|--------|------|------|--------|
-| `rendering.render_timeout` | 整数 | 单次 t2i 图片渲染的最大等待时间（秒） | `30` |
-
-图片统一通过 AstrBot 内置的网络 t2i 服务渲染，插件不依赖或启动本地
-Playwright。单次渲染失败或超时只影响当前请求，后续请求仍会重新调用 t2i，
-无需人工重置渲染器。
-
----
+**打勾图标说明：**
+- 开启 `show_check_mark`：签到日期会显示打勾图标 ✓
+- 关闭 `show_check_mark`：签到日期只显示打卡次数，不显示打勾图标
+
+### 渲染配置 (`rendering`)
+
+| 配置项 | 类型 | 说明 | 默认值 |
+|--------|------|------|--------|
+| `rendering.render_timeout` | 整数 | 单次 t2i 图片渲染的最大等待时间（秒） | `30` |
+
+图片统一通过 AstrBot 内置的网络 t2i 服务渲染，插件不依赖或启动本地
+Playwright。单次渲染失败或超时只影响当前请求，后续请求仍会重新调用 t2i，
+无需人工重置渲染器。
+
+---
 
 ## 📝 使用方法
 
 ### 基础命令
 
 | 命令                     | 说明                        |
 |------------------------|---------------------------|
+| `/鹿帮助` 或 `鹿帮助` | 查看命令帮助图（固定图 `assets/help.png`，不走 t2i） |
 | `/deer` 或 `/🦌` 或 `🦌` | 自我打卡                      |
-| `/deer @用户` 或 `🦌 @用户` | 帮他人打卡                     |
+| `/deer @用户` 或 `🦌@用户` | 帮他人打卡（有无空格均可；也可 `帮🦌@用户`） |
 | `/允许被🦌`               | 允许他人帮自己打卡                 |
 | `/禁止被🦌`               | 禁止他人帮自己打卡                 |
 | `/设置被鹿 开 @用户`          | 管理员：允许指定用户被帮打卡            |
@@ -148,9 +149,21 @@ Playwright。单次渲染失败或超时只影响当前请求，后续请求仍
 🦌          # 自我打卡
 鹿           # 自我打卡
 撸🦌         # 自我打卡
-帮🦌 @用户    # 帮他人打卡
+🦌@用户      # 帮他人打卡（无空格也可）
+帮🦌@用户    # 帮他人打卡
+鹿帮助       # 查看帮助图
 ```
 
+### 维护说明（开发）
+
+若增删命令或别名，请同步：
+
+1. `main.py` 中的 `@filter.command` / 纯文本正则
+2. `scripts/gen_help_image.py` 的 `SECTIONS`
+3. 在本机执行 `python scripts/gen_help_image.py` 重生成 `assets/help.png`
+
+该脚本仅用于开发机截图，**不是**插件运行时依赖。
+
 ### 历史记录查询
 
 支持查看任意年月的打卡记录：

main.py

@@ -32,6 +32,7 @@
     DeerPipeHTMLRenderer,
     DeerPipeLLMTools,
     DeerPipeService,
+    HelpCommandHandler,
     ResourceLoader,
     TemplateRenderer,
     close_aiohttp_session,
@@ -42,6 +43,7 @@
 from .src.shared.constants import (
     PLAIN_CALENDAR_TRIGGER_PATTERN,
     PLAIN_DEER_TRIGGER_PATTERN,
+    PLAIN_HELP_TRIGGER_PATTERN,
 )
 
 logger = get_logger()
@@ -253,6 +255,7 @@ def __init__(self, context: Context, config: AstrBotConfig) -> None:
         self.data_handler = DataCommandHandler(self.data_manager)
         self.base_dir = Path(__file__).parent
         self.deermap_handler = DeermapCommandHandler(self.db, self.base_dir)
+        self.help_handler = HelpCommandHandler(self.base_dir)
 
         # 初始化 HTML 渲染器
         render_timeout = cfg.render_timeout
@@ -598,6 +601,12 @@ async def tool_get_user_deer_data(
     # Command Handlers (使用命令处理器)
     # ==================================================================
 
+    @filter.command("鹿帮助", alias={"🦌帮助", "鹿菜单", "deer_help", "deerhelp"})
+    async def help_cmd(self, event: AstrMessageEvent) -> AsyncGenerator[Any, None]:
+        """发送固定帮助图 (/鹿帮助)."""
+        async for result in self.help_handler.handle_help(event):
+            yield result
+
     @filter.command("deer", alias={"鹿", "🦌", "撸", "撸🦌"})
     async def deer_cmd(self, event: AstrMessageEvent) -> AsyncGenerator[Any, None]:
         """自我打卡或帮他人打卡 (/deer)."""
@@ -748,10 +757,17 @@ async def deermap_cmd(
     # ==================================================================
 
     def _is_explicit_slash_command(self, event: AstrMessageEvent) -> bool:
-        """检查消息是否以 / 开头."""
+        """检查消息是否显式带 / 命令前缀.
+
+        同时看 message_str（wake 可能已剥前缀）与原始 Plain 组件，
+        任一处出现 / 前缀即视为 slash 命令，避免 plain 与 command 双跑。
+        """
+        message_str = (event.get_message_str() or "").strip()
+        if message_str.startswith("/"):
+            return True
         for comp in event.get_messages():
-            if isinstance(comp, Plain):
-                return comp.text.strip().startswith("/")
+            if isinstance(comp, Plain) and comp.text.strip().startswith("/"):
+                return True
         return False
 
     def _parse_calendar_date(self, text: str) -> tuple[dt.date, str] | None:
@@ -841,3 +857,14 @@ async def plain_calendar_merged_cmd(
                     ):
                         yield result
                     return
+
+    @filter.regex(PLAIN_HELP_TRIGGER_PATTERN)
+    async def plain_help_cmd(
+        self, event: AstrMessageEvent
+    ) -> AsyncGenerator[Any, None]:
+        """纯文本帮助命令（不带/前缀）."""
+        if self._is_explicit_slash_command(event):
+            return
+
+        async for result in self.help_handler.handle_help(event):
+            yield result

metadata.yaml

@@ -1,6 +1,6 @@
 name: astrbot_plugin_deerpipe
 display_name: 鹿乃子月历
-version: v2.1.1
+version: v2.1.2
 author: FlanChanXwO
 desc: 一款可爱的每日打卡插件，记录你的健康生活每一天，生成精美的月度打卡日历，支持补签和好友互动。
 support_platforms: