main_plugin_farm/docs/help-menu.md

# 动态农场帮助菜单

发送 `农场帮助` 返回单张帮助长图，发送 `农场帮助 文字` 返回完整文字版。
未开通农场也可使用；帮助查询不触发旧玩家数据迁移。
缺少可用字体或绘图失败时自动返回文字版，并在运行日志记录原因。

菜单使用包内农场背景、绿色分类栏和浅米色卡片。命令与说明采用固定字号，
按实测字宽换行，不省略长指令；分类自动分配到两列并随内容增加图片高度。
说明区包含参数、编号示例、虫害、经验及迁移提示。

图片遵循现有农场图片格式与质量配置；帮助菜单不支持高清参数。
同内容、平台、格式及质量的请求复用成图缓存，并发绘制复用同一任务。

## 增加或调整指令

唯一的中文命令定义位于 `src/farm_core/commands.py` 的 `COMMAND_SPECS`。
每条定义包含注册名称、运行时动作、分类、语法、说明、别名、适用框架，
同一主命令的附加语法使用 `extra`，例如 `开垦 条件`。

新增实际功能时，先实现对应运行时动作，再添加定义。三个框架的中文命令注册、
帮助图片及文字版共同读取该定义，无需再修改独立的帮助文案列表。
插件加载时读取定义，修改后随正常的插件重新加载生效，不支持在线编辑文件热更新。

`platforms` 为空时三平台共用；限制为 `('zhenxun',)` 的已接入指令仅在真寻注册
并显示。NoneBot 和 AstrBot 不显示该分类的空卡片。框架类型由接入层明确指定，
不使用用户可配置的 deployment 名称判断。

当前新版尚未接入金币兑换，因此不会显示旧版的购买农场币或点券兑换指令。
以后接入真寻兑换时，将真实动作及其平台限制一同加入定义即可。

## 验证边界

离线测试覆盖平台筛选、注册与帮助一致性、别名、超长命令换行、内容增长、
图片格式、质量配置、缓存及并发合并，以及文字兜底和帮助查询无玩家迁移。
离线图片和模拟宿主验证不代表已安装到真实机器人。