kt-template-online-api/docs/qqbot-bangdream-tsugu-reference.md

QQBot BangDream 模块参考文档

生成日期：2026-06-07

文档定位

本文记录 QQBot BangDream 插件在文件结构重构完成后的稳定结构、入口链路、扩展点和验证方式。原 tsugu 子目录已经移除，内嵌 Tsugu 能力现在直接归入 src/qqbot/plugins/bangDream。

函数级用途以源码 JSDoc 为准；本文只维护模块边界、文件职责、命令入口、数据流、测试和发布验证入口。

覆盖范围

项	当前值
模块源码目录	src/qqbot/plugins/bangDream
Nest 客户端入口	src/qqbot/plugins/bangDream/application/bangdream-client.service.ts
应用入口	src/qqbot/plugins/bangDream/application/bangdream-application.service.ts
渲染 Facade	src/qqbot/plugins/bangDream/application/bangdream-renderer.facade.ts
Operation 注册表	src/qqbot/plugins/bangDream/registry/operation-registry.ts
测试目录	test/qqbot/plugins/bangDream
资源目录	src/qqbot/plugins/bangDream/assets
静态配置目录	src/qqbot/plugins/bangDream/static-config

总体链路

QQBot 在线命令
  -> QqbotBangDreamPluginService / command engine
  -> QqbotBangDreamClientService.execute(operationKey, input)
  -> TsuguApplicationService
  -> TsuguOperationPipeline
  -> QqbotBangDreamRendererService.executeOperationHandler(handlerName, input)
  -> song/card/event/gacha/player/cutoff 等模块 renderer
  -> provider + repository + search + theme/shared
  -> CQ image base64 reply

核心约束：

• registry/operation-registry.ts 是 15 个 BangDream operation、handlerName、在线命令别名和冷却配置的单一来源。
• application/bangdream-application.service.ts 是 Nest 边界，负责主数据 ready、字典刷新、pipeline 和错误字符串化。
• application/bangdream-renderer.facade.ts 只做 handler 分发、输入归一化、字典解析和 CQ 图片输出。
• 业务模块按领域聚合，例如歌曲文件集中在 song，卡牌文件集中在 card。
• 横切能力只放 hook、provider、policy、registry、theme、search、shared。
• 不再新增 tsugu、models、render-blocks、command-renderers、data-clients、runtime、canvas 顶层目录。

目录职责

目录	职责
application	Nest 客户端、应用服务、渲染 facade、operation pipeline
registry	operation key、handlerName、在线命令别名、冷却和说明
hook	生命周期 hook 和命令执行日志 hook
provider	Bestdori、HHWX、静态修正、缓存、重试、URL 解析和文件缓存
policy	服务器策略、国服活动时间预估、档线规则、抽卡规则
theme	Canvas 基础能力、布局 token、本地资源 manifest 和渲染主题
config	运行时配置、环境变量 key、服务器默认值和档线 tier
dictionary	默认字典和 API 字典加载
search	模糊搜索、关系表达式、搜索字典和实体列表匹配
song	查曲、歌曲详情、随机曲、分数表、谱面图片、歌曲资源 repository
card	查卡、卡面、卡牌图标、卡牌属性/稀有度/技能/综合力渲染
character	查角色、角色详情、角色列表和角色资源 repository
event	查活动、活动详情、试炼、活动时间和活动数据 repository
gacha	查卡池、抽卡模拟、卡池概率、Pick Up 和卡池资源 repository
player	查玩家、玩家卡组、乐队等级、角色等级、难度完成情况和排名
cutoff	档线、全档线、近期档线、档线图表、时间线图表和预测算法
catalog	服务器、乐队、属性、区域道具、服装、称号、道具、技能、颜色
shared	协议常量、主数据 store/repository、通用详情块、数据块、列表框架
assets	本地图片、字体和静态视觉资源
static-config	搜索配置、昵称表、CN 修正表和玩家编号表

Operation 注册表

operation key	handler	命令名	主要别名
bangdream.song.search	searchSong	查曲	查曲、bd、bangdream、bandori、邦邦
bangdream.song.chart	getSongChart	查谱面	查谱面、谱面、bd谱面
bangdream.song.random	randomSong	随机曲	随机曲、随机、bd随机
bangdream.song.meta	getSongMeta	查询分数表	查询分数表、查分数表、查询分数榜
bangdream.card.search	searchCard	查卡	查卡、查卡牌、bd查卡
bangdream.card.illustration	getCardIllustration	查卡面	查卡面、查卡插画、查插画
bangdream.character.search	searchCharacter	查角色	查角色、bd角色
bangdream.event.search	searchEvent	查活动	查活动、bd活动
bangdream.event.stage	getEventStage	查试炼	查试炼、查stage、查舞台、查5v5
bangdream.player.search	searchPlayer	查玩家	查玩家、查询玩家、bd玩家
bangdream.gacha.search	searchGacha	查卡池	查卡池、bd卡池
bangdream.gacha.simulate	simulateGacha	抽卡模拟	抽卡模拟、bd抽卡
bangdream.cutoff.detail	getCutoffDetail	ycx	ycx、预测线、查档线、bd档线
bangdream.cutoff.all	getCutoffAll	ycxall	ycxall、myycx、全部档线
bangdream.cutoff.recent	getCutoffRecent	lsycx	lsycx、历史档线、近期档线

新增或调整在线命令时先改 registry/operation-registry.ts，再跑 test/qqbot/plugins/bangDream/registry/command-sql.spec.ts 检查数据库初始化 SQL 与注册表是否一致。

扩展规则

• 新增歌曲能力：优先在 song 增加 model/repository/renderer/layout，不要回到横切目录堆文件。
• 新增卡牌能力：优先在 card 内聚合；只有静态目录实体才放 catalog。
• 新增活动、卡池、玩家、档线能力：分别放 event、gacha、player、cutoff。
• 新增外部数据源或缓存策略：放 provider。
• 新增跨模块业务规则：放 policy。
• 新增 Canvas 基础能力或视觉 token：放 theme。
• 新增通用渲染块：先确认是否真跨多个业务模块，才放 shared。
• 不建巨型 index.ts barrel，保持显式 import，降低循环依赖风险。

本地验证

常规结构或源码改动优先跑：

pnpm run typecheck
pnpm exec jest --runInBand --runTestsByPath test/qqbot/plugins/bangDream/registry/operation-registry.spec.ts test/qqbot/plugins/bangDream/registry/command-sql.spec.ts
pnpm exec eslint src/qqbot/plugins/bangDream test/qqbot/plugins/bangDream
pnpm run build

图片 smoke 使用：

.\scripts\bangdream-render-smoke.ps1 -OperationKey bangdream.song.search -Text "夏祭り" -OutFile ".kt-workspace/bangdream-smoke/song.jpg"
.\scripts\bangdream-render-smoke.ps1 -OperationKey bangdream.event.search -Text "50" -OutFile ".kt-workspace/bangdream-smoke/event.jpg"
.\scripts\bangdream-render-smoke.ps1 -OperationKey bangdream.event.stage -Text "310" -OutFile ".kt-workspace/bangdream-smoke/stage.jpg"
.\scripts\bangdream-render-smoke.ps1 -OperationKey bangdream.gacha.simulate -Text "10 259" -OutFile ".kt-workspace/bangdream-smoke/gacha.jpg"
.\scripts\bangdream-render-smoke.ps1 -OperationKey bangdream.cutoff.detail -Text "100 50 cn" -OutFile ".kt-workspace/bangdream-smoke/cutoff.jpg"
.\scripts\bangdream-render-smoke.ps1 -OperationKey bangdream.song.chart -Text "136 expert" -OutFile ".kt-workspace/bangdream-smoke/chart.jpg"

发布验证

推送 Jenkins/K8s backed 分支后必须观察发布闭环：

1. Jenkins 构建完成。
2. K8s deployment rollout 成功。
3. Pod 启动日志没有 BangDream module load error。
4. 线上 /qqbot/command/test 按 operationKey 查询 commandId 后真实调用。
5. 拉取线上 smoke 图片并目视检查。
6. 检查操作日志中对应 command/test 调用和 BangDream hook 日志。
7. 清理远程 smoke 临时目录。

常见风险

风险	处理方式
资源路径丢失	检查 nest-cli.json 的 assets include 是否指向 qqbot/plugins/bangDream/assets 和 static-config
Jest pattern 匹配不到	Windows 下指定文件统一用 pnpm exec jest --runInBand --runTestsByPath path/with/slash.spec.ts
smoke 卡住	使用 scripts/bangdream-render-smoke.ps1 的 TimeoutSeconds，远程临时脚本也要有外层 timeout
commandId 查错	线上 smoke 必须先用 operationKey 查在线命令，不使用历史脏数据
大图 OOM 回归	优先验证 bangdream.event.stage，关注 imageCount=5 和图片大小