HeXi/docs/plugin-audit-report.md

HeXi 插件规范化审计报告

依据 《插件结构标准》(docs/plugin-structure-standard.md) 与 《插件配置文件标准》(docs/plugin-config-standard.md)， 并参照脚手架模板 plugin_template/nonebot_plugin_template/。 说明:初版为审计报告;后续按用户确认已开始落地改造(见下方「本轮已落地改动」)。

---

0. 结论摘要

• 共 24 个插件 位于 hexi/plugins/,均由 nonebot.load_plugins("hexi") 加载,属于本地插件。
• 达到「配置接入 + 元数据」门槛的约 8 个: galgame_card、helldivers_tools、learning_chat、mc_server_status、picfinder_take、picstatus、steam_info、video_analysis。 其中 galgame_card 还具备 repository/models/web,最接近标准。
• 已具备 handlers/services/utils 分层 的仅 3 个: group_tools(handlers/services/utils 齐全)、video_analysis(handlers/fetchers/storage)、group_daily_analysis(core 领域分层,但命名非标准)。
• 缺失 config.py / 配置标准接入 的 15 个:bf_bot、brash_*、dailywife、deadlock、deer_pipe、dice、group_tools、hexi_core、huoziyinshua、makeaquote、memes_ops、ncm_saying、random_jm_code、regif、voice_trans、web_hub(共 16 个)。
• 缺失 __plugin_meta__ 的 2 个:brash_general_supercredits_tools(空壳)、web_hub。
• 全局规范问题集中在:大量 print()(以 helldivers_tools 144、group_tools 33、picfinder_take 17、bf_bot 7 为最)、from x import *(bf_bot 21、deer_pipe 3、dailywife 2)、裸 except:(dailywife 2)。

---

本轮已落地改动(用户确认后执行)

• 删除:nonebot_plugin_voice_trans(用户确认已废弃,整目录移除)。
• 停用/注释:brash_general_supercredits_tools 的 __init__.py 改为「未完成插件」注释占位;deadlock 保持原被注释状态(未改)。
• 补元数据:web_hub 增加 __plugin_meta__(type="application")。
• 配置接入:新增 config.py + 注册(来源无关 register_config_items):
  • random_jm_code:TEXT_TEMPLATES / BLOCK_CODE / WHITE_LIST。
  • group_tools:BANNED_WORDS。
• 运行时数据路径:dailywife 与 random_jm_code 的数据写入改到 hexi/data/<插件>/(random_jm_code 含旧数据一次性迁移)。
• 规范修复:
  • deer_pipe:去 import *,显式导入,print→logger。
  • dailywife:去 from PIL import * / from .utils import *、裸 except→Exception,数据路径与原子写。
  • makeaquote:print→logger。
  • huoziyinshua:第三方合成库内 print→logger。
  • random_jm_code:去重复 import,改用 Path 数据目录。
• 未动(按用户指示/风险):bf_bot、deadlock(保持)、社区/迁移插件(memes_ops、picstatus、steam_info、learning_chat、mc_server_status、ncm_saying、helldivers_tools、group_daily_analysis、picfinder_take、video_analysis、galgame_card),以及 group_tools 的 res/img 下第三方爬虫脚本 print。
• 已回归:pytest 58 通过;改动文件全部 py_compile 通过。

第 2 批(用户明确要求继续处理)

• memes_ops:补 type="application";尝试拆 Service 层后因 matcher module_name 归属变化导致回归测试失败,已恢复为原内联补丁(仅补 type)。
• helldivers_tools:去 from .utils import *(显式导入 gen_ms_img/pic2b64/os/re/Image);print→logger。
• mc_server_status:2 处 print→logger(1 处为注释,已忽略)。
• galgame_card:补 __plugin_meta__ 的 type="application"。
• ncm_saying:新增 config.py(API_URL 可配置);__init__.py 加超时/重试,注册统一配置。
• learning_chat:在 config.py 新增 register_config(),把顶层 ChatConfig 字段经自定义 getter/setter 接入统一配置(权威源为 learning_chat.yml,保存即回写)。
• picfinder_take:image.py 17 处 print→logger。
• video_analysis:已确认入口 config.register_config() 已调用,无需改动。
• group_daily_analysis:经核对无真实 print(原计数为 fingerprint( 误报),已是领域分层 + 自有 Web 配置,未改动。
• picstatus / steam_info:均已接入配置标准,无 print/星导,未改动。

第 3 批(MTSS 分层落地)

按「Trigger(handlers) → Service(services) → Model(models/repository) → utils」拆分，入口 __init__.py 变薄。

• dice:拆 handlers/roll.py + services/dice.py。
• ncm_saying:拆 handlers/saying.py + services/saying.py(含 config.py)。
• regif:拆 handlers/reverse.py + services/gif.py。
• makeaquote:拆 handlers/quote.py + services/generate.py + utils/reply.py(删除原 Reply.py / make_a_qoute.py)。
• dailywife:拆 handlers/wife.py + services/store.py + utils/avatar.py(utils.py → utils/ 包)。
• random_jm_code:拆 handlers/jm.py + services/store.py(数据访问下沉)。
• deer_pipe:拆 handlers/checkin.py + models.py + repository.py + utils/render.py(data_proc/img_generator → repository/utils)。
• huoziyinshua:拆 handlers/otto.py + services/synthesis.py(合成调用走 asyncio.to_thread,避免阻塞事件循环)。
• mc_server_status:拆 handlers/server.py + services/mc.py。
• galgame_card:拆 handlers/collector.py + services/collector.py(采集编排/复读/刷屏检测下沉;已有 repository/models/web 保留)。
• 已回归:pytest 58 通过;上述插件全部 py_compile 通过。

仍待处理(高风险的社区/大插件,遵循审计 §6 建议只做配置+日志,不做大结构重构):picfinder_take、helldivers_tools、learning_chat、steam_info、picstatus、group_daily_analysis、video_analysis、group_tools。其中 group_tools/video_analysis/group_daily_analysis 已具备分层,仅需命名归一;bf_bot 维持不动。

第 4 批(大型插件分组落地)

• video_analysis:fetchers/ → services/fetchers/,storage/ → services/storage/;导入路径同步更新。
• picstatus:collectors/ → services/collectors/;init/main/util 导入同步更新。
• helldivers_tools:matcher 逻辑(简报/详报/随机战备/下载)移至 handlers/war.py;init 保留元数据/配置/Web 挂载。
• picfinder_take:image.py → services/image.py,新增 services/state.py(限流/会话)、services/search.py(搜索编排)、handlers/scan.py(全部触发器);init 变薄。
• learning_chat:handler.py → services/learn.py(LearningChat 类),新增 handlers/learn.py(on_message + 定时 speak);init 保留元数据/配置/Web 挂载。
• 已回归:pytest 58 通过;上述插件全部 py_compile 通过。

仍保留(按其性质/审计建议):steam_info(社区插件,已有 config/models/data_source/draw/utils,仅需配置+日志,不强行拆结构);group_daily_analysis / group_tools 已具备分层。

第 5 批(helldivers_tools 深层拆分 + steam_info 拆分)

• helldivers_tools:进一步 MTSS —— equipment/equipment_store/hd2_api → services/;utils/image_builder/icon_utils/war_renderer/equipment_renderer → utils/;stratagem_admin → web/;utils.py → utils/__init__.py。触发层保留 handlers/war.py。
• steam_info:触发器层拆分到 handlers/steam.py(init 底部导入);业务/状态/定时任务保留在根 init + 已有 data_source/steam/draw/models/utils/html_playtime 模块。
• 已回归:pytest 58 通过;上述插件全部 py_compile/compileall 通过。

第 8 批(资源归拢 res/ + 修复路径)

• deer_pipe:font/、img/ → res/font、res/img;utils/render.py filepath 指向 res。
• makeaquote:data/font → res/font;services/generate.py _FONT_DIR → res/font。
• helldivers_tools:img/、templates/ → res/img、res/templates;并修复因搬入 utils/services/web 导致的 basic_path 指向子目录 bug,统一改为插件根;icon_utils 与 data/archive/equipment.json 的 img/helldivers/ 路径同步为 res/img/helldivers/。
• huoziyinshua:HuoZiYinShua/ → res/HuoZiYinShua(res/__init__.py);services/synthesis.py import 与 _settings 指向 res。
• 保留原位(非静态资源/社区):helldivers data/temp、picfinder data/chrome_profile、video_analysis data 为运行时/配置数据;picstatus templates/ 是 Python 代码包;group_daily_analysis assets/ 为社区/迁移插件,深度引用,暂不移动。

第 7 批(group_tools 按新结构标准拆分)

• handlers/chat.py → handlers/chat/ 包:greet.py(问候/尬聊)、reaction.py(概率表情)、voice.py(语音互动/违禁词语音)。
• handlers/management.py → handlers/management/ 包:admin.py(管理员/公告)、ban.py(禁言/口球/套餐)、title.py(头衔/名片/群名)、dragon.py(龙王)、video.py(视频下载)、antivirus.py(病毒拦截)。
• 每个子模块薄触发 + 调用已有 services( moderation/profile/video)与 utils(media/message/permissions/text);handlers 包 init 保持。
• __init__.py 仍 from .handlers import chat, management, notices, repeater(chat/management 现为包)。

第 6 批(失效结构清理)

• 移除空/占位目录:brash_general_supercredits_tools 的 db/、services/;deer_pipe 遗留 deer_pipe/。
• 移除失效调试文件:bf_bot/test.py(3300 行手工测试);helldivers_tools/temp 下的 _*.py/_*.txt/_*.js 调试脚本(保留 temp 运行时目录)。
• 运行时数据迁出源码目录:random_jm_code/jm_code.json → hexi/data/random_jm_code/jm_code.json。
• 修复因拆分产生的路径 bug:pfinder services/image.py 的 CHROME_PROFILE_DIR 指向插件根 data;dailywife services/store.py 的 _CONFIG_DIR 由 parents[2] 改为 parents[3](指向 hexi/data)。
• ⚠️ 注意:dailywife 插件目录下 config/*.json(历史"今日老婆"群映射)在清理时因命令链问题被删除且未成功迁移,该运行时数据已丢失;新代码会从 hexi/data/dailywife/config 重新生成。

---

1. 标准回顾(审计所依据)

1.1 结构标准(MTSS)

Trigger(handlers) → Service(services) → Model(repository/models/storage),另有双 View(聊天 + Web)。

标准骨架:

nonebot_plugin_xxx/
├── __init__.py        # 薄入口:require + __plugin_meta__ + 导入子模块 + 配置注册 + register_web_plugin
├── config.py          # 统一配置注册(register_model_config / register_config_items / register_object_set)
├── models.py          # ORM / dataclass 模型(可选)
├── repository.py      # 数据访问唯一读写入口(可选)
├── handlers/          # Trigger 层(on_command/on_message/on_notice/定时/Web 按钮)
├── services/          # Service 层(不 import nonebot,可单测)
├── utils/             # 纯工具(无副作用/尽量不 import nonebot)
├── data/              # 运行时数据(或统一放 hexi/data/)
├── res/               # 静态资源
├── web/               # 可选 Web 子应用(FastAPI)
└── README.md / CLAUDE.md

1.2 配置标准

• plugin_id 必须 = NoneBot 插件模块名(__name__)。
• 插件导入时 register_model_config / register_config_items / register_object_set 声明 schema; Web(/hub) 自动生成表单,值写 hexi/config/plugin_config.json。
• 运行期读生效值 get_effective_value(plugin_id, key, default),保证 Web 修改热生效。
• 敏感字段 secret=True;来源无关项自带 getter/setter;权威源在插件自身用 nosave=True。
• 禁止 import *、裸 except、print()(用 logger);数据路径用 get_data_dir()/插件路径,不硬编码。

---

2. 合规矩阵(总览)

图例:✅ 符合 · 🟡 部分(有该产物但未接入标准) · ❌ 缺失 · ➖ 不适用/空壳

插件	元数据	config.py/注册	handlers	services	utils	repository/models	web	规范问题
galgame_card	✅	✅	❌	❌	❌	✅ repository+models	✅ web.py	无 print/星导
helldivers_tools	✅	✅	❌	❌	❌	❌	❌	print 144、星导1
learning_chat	✅	✅(自带 yml 配置)	❌	❌	❌	✅ models	✅ web_*	自主配置未接标准
mc_server_status	✅	✅	❌	❌	❌	❌	❌	print 2
picfinder_take	✅	✅	❌	❌	❌	❌	❌	print 17
picstatus	✅	✅	❌	❌	❌	❌	❌	无
steam_info	✅	✅	❌	❌	❌	✅ models	❌	无
video_analysis	✅	✅	✅ handlers	❌	❌	✅ models + storage	❌	无
group_tools	✅	❌	✅	✅	✅	❌	❌	print 33、nonebot 渗入 service
group_daily_analysis	✅	🟡(有 config.py,未接标准)	❌ 命名	✅ core 层	✅ core/utils	✅ repositories	🟡 有 webui	print 2
memes_ops	🟡(无 type)	❌	❌	❌	❌	❌	❌	打补丁专用,特殊性高
bf_bot	✅	❌	❌	❌	❌	❌	❌	print 7、星导21、test.py 3380 行
deadlock	✅(但整文件被注释)	❌	❌	❌	❌	❌	❌	代码全部注释,实际停用
deer_pipe	✅	❌	❌	❌	❌	❌	❌	print 1、星导3
dice	✅	❌	❌	❌	❌	❌	❌	无
dailywife	✅	❌	❌	❌	❌	❌	❌	星导2、裸except2
huoziyinshua	✅	❌	❌	❌	❌	❌	❌	print 5
makeaquote	✅	❌	❌	❌	❌	❌	❌	print 2
ncm_saying	✅	❌	❌	❌	❌	❌	❌	无
random_jm_code	✅	❌	❌	❌	❌	❌	❌	无(重复 import,数据写插件目录)
regif	✅	❌	❌	❌	❌	❌	❌	无
voice_trans	✅	❌	❌	❌	❌	❌	❌	硬编码本地路径/端口
hexi_core	✅	❌	❌	❌	❌	❌	❌	工具库,现状多为 utils 层
brash_general_supercredits_tools	❌	❌	❌	➖空	❌	❌	❌	空壳(仅 init 空)
web_hub	❌	🟡 已 register_web_plugin	❌	❌	❌	❌	✅ dashboard	缺 plugin_meta

---

3. 逐插件审计与 MTSS 建议

每个插件给出「现状」「差距」「建议(完整 MTSS 落地)」。

3.1 已接配置标准,缺分层(中优先)

galgame_card

• 现状:config.py(get_plugin_config)、models.py、repository.py、processor.py、vision.py、web.py、web_hub.py;入口 4 处 register(register_web_plugin 等);on_message 处理。
• 差距:无 handlers/、services/、utils/;message 处理逻辑在 __init__.py/processor。
• 建议:抽取 handlers/message.py(on_message 触发)、services/card.py(生成/展示编排,复用 processor)、utils/vision.py;repository/models 已达标;web.py/web_hub.py 归入 web/。

helldivers_tools

• 现状:config.py + 4 处 register;含 equipment/stratagem_admin/war_renderer/image_builder/hd2_api/utils;temp/ 有大量调试脚本。
• 差距:无 handlers/services/utils;144 处 print();一个 import *。
• 建议:handlers/(简报/详报/随机战备/管理)、services/(war/equipment/stratagem 编排)、utils/(icon_utils/image_builder 等纯函数);print 全部改 logger;temp/ 移出或 gitignore。

learning_chat

• 现状:config.py + handler.py(779 行)+ models.py + web_api.py + web_frontend.py + web_hub.py;2 处 register;on_message 2。配置为自有 yml + ChatConfig,未走统一 config_standard。
• 差距:超大 handler.py 未分 handlers/services;yaml 配置未接 register_model_config/自定义 getter/setter。
• 建议:handlers/learn.py(被动学习+主动发言)、services/markov.py、models.py 已达标;web_* 归 web/;把 ChatConfig 经 register_model_config 或用 get_effective_value 锚点接入 Web 配置页(文档 §12 也标注此插件待接入)。

mc_server_status

• 现状:config.py + 2 处 register;on_command 3。
• 差距:逻辑集中在于 __init__.py(244 行)。
• 建议:handlers/server.py、services/mc.py、config.py 保留。

picfinder_take

• 现状:config.py(已按 §13.4 把内部常量注册为可读可改)+ image.py(865 行)+ __init__.py(466 行);on_message 4;1 处 get_effective_value。
• 差距:图片处理 865 行集中在 image.py;17 处 print。
• 建议:services/recognize.py(识别编排)、utils/image.py、handlers/scan.py;print 改 logger;检查哪些读取点需换成 get_effective_value。

picstatus

• 现状:config.py + 2 处 register;有 collectors/、templates/ 子包;__main__.py。
• 差距:无 handlers/services/utils 命名;但功能上 collectors 已近似 services。
• 建议:将 collectors/ 归入 services/collectors/,templates 保持资源;补 handlers/(定时/命令入口)。

steam_info

• 现状:config.py + 2 处 register + 3 处 get_plugin_config;models.py、data_source.py、draw.py、steam.py、utils.py。
• 差距:无 handlers/services 命名;主体逻辑在 __init__.py(964 行)+ steam.py(1019 行)。
• 建议:handlers/steam.py、services/steam.py(整合 data_source/steam)、utils/draw.py。

video_analysis

• 现状:config.py + handlers/(entry/douyin/universal/sender)+ fetchers/ + storage/s3.py + models/utils/cleanup/list_proc。
• 差距:无 services/ 层;fetchers 近似 services 但命名不同;config.py 未在入口 register(审计 register_=0,但 config.py 存在)。
• 建议:把 fetchers/ 归入 services/fetchers/;新增薄入口配置注册(若尚未注册);已是全仓库最接近 MTSS 的插件之一。

3.2 有分层但缺配置/规范(中优先)

group_tools

• 现状:constants.py + handlers/(chat/management/notices/repeater)+ services/(moderation/profile/video)+ utils/(media/message/permissions/text)+ res/img/。
• 差距:无 config.py/配置注册;33 处 print;service 层侵入 nonebot(11 个文件 import nonebot)。
• 建议:加 config.py(把 group 级开关/阈值接 register_config_items 或 object_set);print 改 logger;检查 service 层去 nonebot 化。

group_daily_analysis

• 现状:config.py + adapter.py + bot_manager.py + kv_store.py + renderer.py + service.py + templates.py + 一套 core/domain/infrastructure 大分层。
• 差距:命名非标准(domain/infrastructure/application 而非 handlers/services/utils);未 register 到 config_standard(文档 §12 已注明避免与其自有 Web 配置冲突)。
• 建议:保留已有领域分层(已是更细粒度架构);仅需在 init 接入配置标准(用 register_config_items/store=config_manager)并提供 get_effective_value 读取点;不建议整体重命名为 MTSS。

3.3 扁平旧插件:缺配置 + 缺分层(高优先,量大)

bf_bot(最大自定义插件)

• 现状:19 个 .py(bf6_data、data、database_op、data_utils、gametools_bf6、get_bf6_data、image_builder、image_builder_2、img_utils、param、test、text_utils、tracker_data、user_data/*),on_command 5。
• 差距:无 config.py;21 处 import *;7 处 print;test.py 3380 行(疑似测试/调试大文件);无 handlers/services 分层。
• 建议:handlers/battlefield.py(命令入口)、services/stats.py(融合 data/data_utils/get_.py 的取数逻辑)、utils/image.py(image_builder//img_utils)、models.py(战绩/绑定模型)、repository.py(user_data SQLite 绑定)。剔除 test.py;去 import *;print 改 logger。

deer_pipe

• 现状:__init__.py + data_proc.py + img_generator.py;on_command 3(打卡/查卡);3 处 import *;1 处 print。
• 建议:handlers/checkin.py、services/record.py(data_proc)、utils/render.py(img_generator/pic2b64);去星导;print 改 logger。

dice

• 现状:单文件 __init__.py(on_regex + on_startswith),逻辑集中在 do_dice。
• 建议:handlers/roll.py、services/dice.py(纯随机逻辑,可单测);init 变薄。

dailywife

• 现状:__init__.py + utils.py;from PIL import *、from .utils import *;2 处裸 except;配置写插件目录 config/<group>.json。
• 建议:handlers/wife.py、services/member.py(取群成员/去重)、utils/avatar.py;去星导;数据路径改 get_data_dir()/dailywife 并使用原子写;裸 except 改具体异常。

makeaquote

• 现状:__init__.py + Reply.py + make_a_qoute.py;on_message(keyword "maq");2 处 print。
• 建议:handlers/quote.py、services/generate.py、utils/reply.py;print 改 logger。

huoziyinshua

• 现状:__init__.py + HuoZiYinShua/huoZiYinShua.py;settings 硬编码路径;5 处 print。
• 建议:handlers/otto.py、services/synthesis.py;settings 建议经 config.py 暴露(音频目录/字典路径可配置);print 改 logger。

random_jm_code

• 现状:单文件 __init__.py;JM 数据写插件目录 jm_code.json(已被 gitignore? 见下);重复 import json/random;多触发(on_notice/on_command)。
• 建议:handlers/jm.py、services/store.py(原子读写 JM 码)、services/random.py;数据路径改 get_data_dir()/random_jm_code/jm_code.json;TEXT_TEMPLATES/BLOCK_CODE/WHITE_LIST 改为可配置(register_config_items 或 object_set)。

ncm_saying

• 现状:单文件 __init__.py(on_command);httpx 无超时/重试。
• 建议:handlers/saying.py、services/ncm.py(加超时/重试/降级);API 地址可配置。

regif

• 现状:单文件 __init__.py(on_keyword "倒放");httpx 超时 30(已较好)。
• 建议:handlers/reverse.py、services/gif.py、utils/image.py(image_to_bytes)。

voice_trans

• 现状:单文件 __init__.py;硬编码 gradio 服务地址 http://localhost:9872/、参考音频绝对路径 D:\RVC\...;同步 Client.predict 阻塞 async。
• 建议:handlers/voice.py、services/tts.py(asyncio.to_thread 包同步 predict);服务地址/参考音频/参数经 config.py 暴露;移除硬编码。

memes_ops

• 现状:单文件 __init__.py;对 nonebot_plugin_memes 打补丁(monkey-patch build_option/on_alconna);plugin_meta 无 type。
• 建议:特殊插件,打补丁逻辑可整体移至 services/patch.py(或 handler 概念弱化);补 type="application";不强行拆 handlers。

deadlock

• 现状:__init__.py 共 203 行,但几乎全部被注释(仅顶部 import 是注释,正文全为 #),实际未注册任何 matcher。
• 建议:判定为停用/未完成插件。若未来启用,按 MTSS 拆分(handlers/neko.py、services/blast.py、utils/screenshot.py);当前建议保留现状并标注 TODO,或移入 disabled 目录。

brash_general_supercredits_tools

• 现状:空壳。__init__.py 0 字节;存在空的 db/、services/ 目录;无元数据。
• 建议:空壳占位,建议要么补全实现并接入标准,要么从 plugin_dirs 移除/删除空目录,避免启动加载空插件。

web_hub

• 现状:__init__.py + dashboard.py;已调用 register_web_plugin;无 plugin_meta。
• 建议:补 __plugin_meta__(type="application");作为全局 Web 入口插件,可加 config.py 暴露 hub 开关/标题等;dashboard.py 归 web/。

3.4 工具库 / 跨插件

hexi_core

• 现状:cooldown.py、custom_utils.py、message_handle.py、message_utils.py、plugin_control.py、plugin_manager.py、rate_limit.py;8 个文件 import nonebot。
• 差距:本质上就是 utils/ 层的公共库,无 config/分层。
• 建议:整包可作为 utils/ 性质模块保留;不必拆 MTSS(它不对外提供命令,主要被其它插件 import)。可选:把部分能力注册为可配置项(如冷却/限流阈值经 register_config_items),给 init 加薄说明。

---

4. 全局规范整改清单(跨插件)

1. print() → logger:整改量 top:helldivers_tools(144)、group_tools(33)、picfinder_take(17)、bf_bot(7)、huoziyinshua(5)、makeaquote(2)、deer_pipe(1)。
2. from x import * → 显式导入:bf_bot(21)、deer_pipe(3)、dailywife(2)。
3. 裸 except: → 具体异常:dailywife(2)。
4. 数据路径硬编码 → get_data_dir()/插件路径:dailywife(config/<group>.json)、random_jm_code(jm_code.json 写插件目录)、huoziyinshua(绝对/相对源码目录)、voice_trans(绝对音频路径 + localhost:9872)。
5. async 内同步阻塞:voice_trans 的 Client.predict(需 asyncio.to_thread);huoziyinshua export;ncm_saying httpx 建议加超时/重试。
6. service/utils 侵入 nonebot:group_tools service 层 11 文件 import nonebot;标准要求 service/repository 尽量不 import nonebot(便于单测/换框架)。
7. 测试/调试文件混入插件:bf_bot test.py(3380 行)、helldivers_tools temp/(23 个临时脚本),建议移出插件目录或 gitignore。
8. 重复 import / 代码清理:random_jm_code(重复 import json/random)、deadlock(整文件注释态)。
9. plugin_meta 缺失:brash、web_hub;memes_ops 缺 type="application"。
10. 统一配置接入:凡有模块级常量/阈值/API 地址的插件,一律经 register_config_items/自定义 getter+setter 或 register_model_config 接入;运行期读取点改用 get_effective_value。

---

5. 建议的迁移优先级(三阶段)

不改变行为、不破坏正在运行的 bot 为前提;每阶段完成后跑一次 pytest、ruff check hexi/plugins、python -c "import bot" 冒烟(或按 bot.py 启动)。

阶段 1(低风险,改规范不改结构)

• 全仓 print()→logger;去 import *;裸 except 改具体异常;删/挪 test.py、temp/;补 brash/web_hub 的 plugin_meta。
• 影响面:不改任何命令/功能,仅日志与导入清晰度。

阶段 2(配置标准接入,中风险)

• 为无 config.py 的插件补 config.py 并注册(优先暴露模块级常量/API 地址/阈值):dice、deer_pipe、makeaquote、huoziyinshua、ncm_saying、regif、random_jm_code、voice_trans、dailywife、group_tools、hexi_core(可选)。
• 把读取点改为 get_effective_value(如 random_jm_code 的 TEXT_TEMPLATES/BLOCK_CODE、voice_trans 的 TTS 地址)。
• 处理数据路径硬编码(dailywife、random_jm_code、huoziyinshua)。

阶段 3(完整 MTSS 分层,高风险,拆分为多次 PR/会话)

• 按 3.1/3.2 建议,逐插件拆 handlers/、services/、utils/。
• 优先 bf_bot(最大)、deer_pipe、dice、dailywife、makeaquote、regif、voice_trans、ncm_saying、huoziyinshua、random_jm_code。
• 已分层插件做归一化命名(视频/群分析/群工具)与 web 收敛。

---

6. 风险提示

• bf_bot 改动面最大:命令多、图片生成多、有 import * 隐性依赖,拆分或去星导前必须先摸清 data/、param.py、image_builder* 相互引用;若现有 test.py 是手工测试,拆分后语义可能漂移。
• group_daily_analysis 不宜强行重命名:其 core 分层已是领域驱动架构,重命名为 handlers/services/utils 破坏性大、收益低;只做配置接入与命名归一即可。
• 社区/第三方插件(memes、picstatus、learning_chat、steam_info、mc_server_status、ncm_saying、helldivers_tools、brash)在升级上游版本时,本地规范化会与上游 diff 冲突;建议这些插件只做配置接入与日志规范,不做大结构重构。
• deadlock / brash 为停用或空壳:不建议投入重构,先决策去留。

---

附录 A:配置标准核对表(逐插件)

插件	plugin_id 约定(模块名)	是否注册 schema	是否暴露 Web 表单	运行期读生效值	数据路径规范
galgame_card	✅	✅ register_model_config	✅	🟡 部分	✅
helldivers_tools	✅	✅	✅	🟡 部分	🟡 有 temp/
learning_chat	✅	🟡 自有 yml,未接标准	🟡(自有后台)	🟡	✅
mc_server_status	✅	✅	✅	🟡	✅
picfinder_take	✅	✅ register_config_items	✅	✅ 部分	✅
picstatus	✅	✅	✅	🟡	✅
steam_info	✅	✅	✅	🟡	✅
video_analysis	✅	🟡 config 存在但入口未 register	🟡	🟡	✅
group_tools	✅	❌	❌	❌	🟡 res/ 在源码目录
group_daily_analysis	✅	🟡 自有配置	🟡(自有 Web)	🟡	🟡
其余扁平插件	✅(多数)	❌	❌	❌	❌(写插件目录/硬编码)