@yamabuki/help

山吹沙绫主题的三层图片帮助。已接入主菜单 v13、大分类 v2、单栏详细页 v2；保留原版 help 的文字输出与失败回退。

为山吹沙绫机器人定制，不以通用主题插件为目标。Koishi 控制台和配置名称为 @yamabuki/help，对应的 npm 包名为 @yamabuki/koishi-plugin-help（遵循 Koishi 的作用域插件命名规则）。本地源码目录为 external/help，不影响插件名称。

使用

当前机器已配置六个大分类及其插件层级，完整清单、调用示例和验证范围见 HIERARCHY.md。

• help：可见根级入口。分类和插件直接使用 Koishi 的父子指令关系，不维护第二棵目录树。未整理的独立根指令也保留入口，不静默丢弃。
• 分类名：直接打开分类页，按插件列出具体指令及原版 description 简介；仍兼容 help 分类名。
• help 插件名 / help 指令名：当前节点及全部可用下级指令的完整详情。
• help 大分类/插件/指令，或以空格分隔的路径：支持原指令名、别名及图片标题。路径不会绕过上下文过滤和权限。
• 指令 -h、help 指令 -H、help -H 指令：沿用原版帮助选项。-H 显示隐藏项，指令本身仍需通过权限检查。
• 无动作的虚拟分组直接执行时显示帮助，不执行子指令动作。

不要同时启用官方 @koishijs/plugin-help，否则会重复注册 help 和 -h。重命名后，当前工作区 koishi.yml 中的条目已改为 '@yamabuki/help:2x7mqa': {}，保留原实例 ID 和配置；没有启动或重启整个机器人。已有指令的 imageHelp 设置字段保持不变，无需重新整理层级或迁移覆盖文案。

自动日夜

每次渲染读取 Koishi 进程的本地时间，同一次请求的全部图片使用同一主题：

• 默认 06:00（含）至 18:00（不含）：亮黄色日间。
• 其余时间：星空夜间。
• 配置 dayStart、dayEnd 可调整分界小时；支持跨午夜区间，相同值表示全天日间。
• 不使用用户设备或聊天平台时间，也不需要定时任务。服务器或容器的本地时区应按部署需要设置。

自定义内容：直接对应原版元素

在官方“指令管理 → 指令设置 → 图片帮助设置”里编辑。未设置的字段复用原指令；显式空字符串或空数组可隐藏相应文案。覆盖同时用于图片与文字帮助，不改写其他插件注册的原数据。

| 设置 | 原版元素 | 展示位置 | | --- | --- | --- | | description | 指令的本地化 description | 分类页简介、详情页简介共用 | | usage | .usage() 或本地化 usage | 详情中的使用说明 | | options.原选项名 | 该选项的说明 | 选项语法旁的文案；variants 使用“选项名.值” | | examples | .example() 或本地化 examples | 示例列表；整体覆盖 |

语法、参数声明、别名、权限、隐藏规则始终来自真实指令，不是自由填写的替代文案。动态 help/command 和 help/option 扩展继续生效，不把覆盖内容当作 HTML/CSS/JavaScript 执行。

原先独立的 summary 不再出现在编辑界面。旧配置仅在没有 description 时兼容读取 summary；建议迁移到上表。原有 description 现在明确对应原版简介，较长的操作说明请放到 usage。

其他节点设置：

• kind：category / plugin / command。大分类必须明确标记；通常手动标记插件节点也更稳定。
• title：菜单显示名，不修改真实指令名、语法或别名。
• order：同级排序，数值越小越靠前。
• icon：sun / planet / crescent / flower / diamond / reserve 六种线绘图案。未设置时自动轮换。

示例

以下是 commands 插件条目内部的示例，不是新的插件安装项；实例 ID 使用你现有配置中的值。

category-entertainment:
  create: true
  config:
    permissions:
      - authority:0
    imageHelp:
      kind: category
      title: 娱乐功能
      description: 游戏、音乐与互动功能
      order: 10
      icon: sun

plugin-music:
  create: true
  name: category-entertainment/plugin-music
  config:
    permissions:
      - authority:0
    imageHelp:
      kind: plugin
      title: 音乐工具
      description: 歌曲查询与音乐资料
      order: 10

search-song:
  name: plugin-music/search-song
  config:
    imageHelp:
      kind: command
      description: 根据名称检索歌曲
      usage: |
        可以输入歌曲名称、常用简称或编号。
        匹配多个结果时，请使用歌曲编号再次查询。
      options:
        server: 选择服务器，如 jp 或 cn
        format.png: 使用 PNG 图片格式
      examples:
        - search-song 1000

选项键必须使用插件注册的原选项名，而不是 -s / --server 语法字符串。未知选项键不创建新选项。虚拟分类和插件节点建议设置 authority:0，避免默认父权限传给整棵子树。

菜单入口

• 主菜单：help、帮助、菜单 是同一条帮助指令的名称，也支持 菜单 邦邦助手、帮助 邦邦助手/邦邦查询 等参数与路径。
• 当前工作区的六个大分类均配置了“全称 + 菜单”别名，例如 邦邦助手菜单、图像工具菜单。直接输入大分类全称（例如 邦邦助手）也会通过无动作指令的原有机制打开帮助页。
• 分类别名保存在官方 commands 配置的 aliases 中，复用原分类节点，不创建重复目录，不改变默认分类标题。以后新增大分类时，可在指令管理页为它添加对应的菜单别名。
• 当前工作区未设置消息前缀，可直接发送以上内容。若以后配置前缀，普通指令入口遵循 Koishi 的前缀与呼叫规则；不会仅因一句聊天内容包含分类名就触发菜单。
• shortcut 只控制原版的免前缀本地化快捷触发，不删除“帮助 / 菜单”指令别名。快捷触发同样检查别名禁用与当前会话权限，禁用“帮助”后不会从旧快捷入口绕过。

指令管理页的默认名称与禁用

• 跟随官方指令管理页的“设为默认 / 禁用 / 恢复”，包括插件初始注册的原名。默认名称不可用时，按管理页顺序选择当前会话可用的下一个名称；自定义图片标题仍优先，但用法使用可用入口。
• 别名列表、指令列表、帮助路径、返回提示以及 -h 都遵循当前会话的别名 filter，不通过内部指令 ID 或自定义标题绕过禁用。-H 只显示隐藏内容，不重新启用被禁用的名称。
• 所有名称不可用的节点不再展示；仍可独立调用的子指令提升到最近的可见父节点，且保留原权限依赖。点号子指令在原父名称禁用时尝试使用有效父别名；找不到可解析入口时不展示该子指令。
• help 自身改默认名称或禁用原名后，图片提示和 -h 使用有效帮助入口；help 全部名称不可用时，-h 不会误执行业务动作。
• 状态每次请求重新读取，不需要为管理页切换重启。若刚升级本插件，则需重新加载插件代码或重启 Koishi。
• 不改写其他插件的业务动作、别名注册表或权限；既有 usage、examples 和第三方帮助钩子提供的文案仍原样保留，不自动替换其中的旧指令文本。

图片与分页

• 主菜单每页最多 9 个入口，均匀分页，保留顺序和原图方向；6 项为三列两行。
• 大分类保持双栏花笺；详细页固定单栏紧凑排布，不折叠子指令。
• 详细页用清晰的区块起始装饰线、编号和淡底标题带区分指令；标题下方用小字显示简略介绍，不再显示“所属”路径，也不在正文重复简介。别名以较小字号的衬线字体紧跟原名，不加括号，别名之间以空格分隔；长别名自然换行，直接查看单条指令时也保持这一形式。用法不使用色块或侧边高亮，避免抢过指令标题。
• 指令内部的用法、说明、选项、示例及补充信息之间使用较淡的细线分隔，首项前不加空分隔。层级装饰采用标题旁的短分支线和菱形节点，不再用贯穿整段内容的中括号；仍保留完整编号与页首导航路径。参数语法中的方括号不受影响。
• 优先保持插件、指令整体。一个指令超过单页时，再按字段和完整文字分页；超长字段按 Unicode 字素拆分，保留样式、编号、标题信息和续页标识。
• 每页独立页眉、边框、页脚和页码，不再按像素高度直接切断截图。分页前后校验长字段文本一致。
• 字段为空时不产生多余区块；虚拟分组不显示可执行用法，确实有动作的插件入口仍显示用法。
• 模板、立绘和回退字体均在 assets 中；运行时不访问外网。优先使用当前系统的中宋、微软雅黑与装饰字体，缺失时使用打包的 Noto / Allura 字体。
• 极端超长标题无法放入圆框、页眉无法给内容留下空间或截图失败时，回退文字帮助，不通过裁切隐藏内容。

渲染配置：width 默认 1120，scale 默认 1.5，maxHeight 默认 2400（CSS 像素），即压缩前单张最大约 1680 × 3600 px。旧版 accent / background 已隐藏，新模板使用统一日夜配色。

单张体积上限

• maxSizeKB 默认 500，每张图片分别限制为 500,000 字节（1 KB = 1000 字节），不是整条多图消息的合计大小。Base64 传输编码和聊天平台额外开销不包含在文件体积中。
• 原 PNG 不超限时原样保留；超限时在本地 Chromium 中转为 JPEG，优先保留原像素，搜索 78–94 的质量档位。仍超限才等比缩小，最低保留 1 倍 CSS 像素，不裁切内容、不改变分页或菜单布局。
• JPEG 最低质量和像素下限都无法满足时，使用现有文字回退；关闭 fallbackText 且使用 output: image 时按原逻辑报错，不悄悄发出超限图片。输出 MIME 与实际 PNG / JPEG 格式一致。
• 设为 0 可关闭体积限制，输出原始无损 PNG。无需为压缩安装额外依赖，不上传图片到第三方。聊天平台可能再次压缩或转换，最终平台结果仍需实机确认。

分类页排版

分类页按原有顺序先从上到下排左列，再排右列，不交替跳列；根据插件实际高度选择分栏点，尽量减少留白。超长插件先尝试同页右列续排，再分页；续排保留插件标题与“续”标记，长简介完整换行，不裁切或省略。

菜单入口提示

主菜单提示直接发送分类名，详细页返回大分类时也显示当前启用的分类名称（或别名），无需加 help；若配置了消息前缀，提示会保留该前缀。带业务动作的节点仍使用 help 名称 查看说明，避免执行动作。

文件缓存

• cache 默认开启，cacheDir 默认为相对路径 cache/yamabuki-help，基于 Koishi 根目录（ctx.baseDir，即配置文件所在目录）解析，不相对于插件目录；无加载器提供根目录时才回退当前工作目录。只缓存到本地文件，不保留成品图片或静态资源的进程内缓存；重启、重新加载插件后仍能复用文件。内存仅保留本次请求的数据及尚未结束的并发任务。
• 每次仍重新读取权限、可用名称、动态说明和帮助扩展，再对最终渲染数据、日夜主题、尺寸、500 KB 等压缩参数、模板、立绘、字体和渲染代码计算 SHA-256。只有哈希相同才复用图片，命中时跳过浏览器页面、截图和压缩；不按权限等级简单共用菜单。
• 同一个菜单的日间、夜间分别保存。对应内容哈希变化时，在生成新版前删除该菜单该主题的旧缓存；旧内容不会作为失败回退。不同权限或会话文案产生不同哈希，可能互相替换同一菜单的旧版本，但不会返回不匹配的缓存。
• 每个 menu-<菜单哈希>-<内容哈希>.bin 文件包含全部分页及每张 PNG / JPEG 的原始字节、格式、长度和 SHA-256 校验信息。完整生成后通过临时文件原子替换；缺失、损坏或校验失败时重建，不返回部分图片。
• 同一进程中的相同并发请求合并生成。较旧请求即使较晚完成，也不会覆盖已更新的版本。缓存读写失败只影响缓存，仍尝试直接生成图片，生成失败则按原有设置回退文字。
• 文件缓存不限制容量和数量，不按体积或最近使用时间淘汰；单张输出图片的 maxSizeKB 限制独立生效，默认仍为 500 KB。只在内容更新或损坏后重建时清理对应菜单缓存，且仅处理该目录中本插件命名的文件，不递归删除目录或其他用户文件。设为 cache: false 可绕过缓存。

原版行为与安全边界

参考本地 @koishijs/plugin-help 2.4.5：

• 指令匹配、别名、快捷调用、建议、-h / -H、无动作分组、权限和隐藏规则。
• 本地化描述、动态 usage、options / variants、examples、用户与频道字段收集。
• 每个指令的动态说明和帮助扩展每次请求仅收集一次；图片与回退共享同一结果。递归详情顺序观察字段，不并发改写同一个 session。
• 图片同时保留子指令的 command 扩展，以及经过 option 扩展改写的完整选项文字。command 扩展重写既有标题行时保留其结果，避免重复显示旧内容。
• 不跨请求缓存权限或动态说明；成品文件只按本次已过滤的完整渲染内容哈希复用。每次实际截图的页面在 finally 中关闭。
• Chromium 请求拦截只提供打包资源，其他 URL 全部阻止。覆盖文案用 textContent 注入。

构建与验证

在 Koishi 工作区执行：

yarn build help
node external/help/tests/identity.cjs
node external/help/tests/hierarchy.cjs --render
node external/help/tests/detail-style.cjs
node external/help/tests/preview-full.cjs
node external/help/tests/integration.cjs
node external/help/tests/aliases.cjs
node external/help/tests/entries.cjs
node external/help/tests/runtime.cjs
node external/help/tests/pagination.cjs
node external/help/tests/category-layout.cjs
node external/help/tests/compression.cjs
node external/help/tests/cache.cjs

• identity：验证作用域包名、Koishi 短名解析、插件导出名称及插件管理页的本地识别。
• hierarchy：根据本地启用插件的静态指令声明，验证正式 commands 配置、原别名/权限/上下文/子树及帮助图片。不执行业务插件或真实聊天动作。
• detail-style：使用组队工具、群友互动的实际静态文案，分别检查日夜 × 720/1120px 的指令区块、内部细分隔、短树形标记、用法弱化、对比度、标题下简介和紧跟原名的别名；另验证长别名换行、空简介及单指令标题。同时生成完整预览和以完整指令为边界的局部预览。不修改正式自动日夜配置。
• preview-full：按当前配置前缀生成主菜单、全部 6 个分类、14 个插件分组和单指令示例的完整日夜图片；验证每张默认不超过 500 KB 并记录实际编码与像素，按真实格式保存 PNG / JPG。管理页面明确标注管理员视角，不裁切或省略分页。目录为 tests/output/full-preview/index.md，各视图另有包含所有分页的日夜对照文档；仅使用静态声明和文案，不运行正式机器人。
• integration：与当前安装的原版逐项比较文字帮助，覆盖权限、隐藏项、别名、原版参数位置、动态扩展、路径、覆盖与时间边界。
• aliases：使用官方 CommandManager 的别名更新方法，在独立 App 中验证文字和图片的默认切换、原名与别名禁用、恢复、全禁用、条件过滤、多层点号路径、子指令提升与权限依赖、help 自身改名，以及原始指令尚未注册时加载禁用配置。测试不写入正式配置。
• entries：通过真实消息处理流程验证主菜单三个名称、六个分类全称及菜单别名、路径、权限对照、默认切换与禁用恢复；覆盖本地化快捷入口不能绕过禁用、用户条件过滤、启动时禁用配置，以及非空前缀和 shortcut: false。不连接真实聊天平台。
• runtime：使用独立 Koishi App 与本地 Chromium 联调真实指令到图片，检查递归扩展、variants、上下文隔离、字段观察、无系统字体以及截图失败回退。测试不连接聊天平台。
• pagination：关闭压缩单独验证无损排版；日夜 × 多种分类数量 / 宽度 / 长内容 / 九层树，28 组检查；逐项核对顺序、字段完整性和 PNG 高度。截图与报告写到 tests/output。
• compression：默认体积限制、PNG 原样保留、关闭限制、JPEG 编码与 MIME、按体积调质量和缩放、极小预算与编码故障下的文字回退、页面资源清理。使用确定性高熵测试图覆盖必要缩放分支。
• cache：使用独立测试目录验证文件命中、跨实例复用、删除和损坏后的重建、旧版本淘汰、并发合并、旧请求竞态、超过原容量和数量上限后仍能保存及安全清理；结合真实帮助插件验证动态内容仍被读取、权限隔离、别名禁用和模板字节更新。通用渲染测试绕过缓存，以便每次检查实际页面；所有测试都不读写正式机器人的成品缓存。
• UI/UX Pro Max 的 Overflow Hidden 指导用于接入后的边界检查：检查真实内容适配，不以隐藏溢出掩盖错误。

资源来源与字体许可证见 assets/README.md。未执行发布操作。