5. 番外：从单一文件到清晰结构
导读 这一章是主线之外的番外篇，专门讨论插件项目结构。当插件功能还很简单时，结构本身并不重要；但随着组件增多、逻辑变复杂，一个清晰的目录布局会让开发和维护轻松很多。本章不规定唯一标准，而是通过几种典型示范，帮助你在插件成长时形成自己的判断。
这一篇不算主线章节，更像一个轻量番外。
前面我们一直在讲“先跑起来”，这没有问题。对于入门插件来说，能被系统识别、能正常加载、能把功能做出来，永远比“目录摆得漂不漂亮”更重要。
不过插件一旦开始长大，结构这件事迟早会冒出来。通常不是因为有人强迫你整理目录，而是因为你自己会慢慢感觉到：
- 文件开始变长了。
- 配置、组件、业务逻辑开始挤在一起了。
- 接 Prompt、LLM、Service 这类 API 时，有点不知道代码该往哪放。
这时候稍微整理一下项目结构，通常会让后面的开发轻松很多。
5.1 没有唯一正确答案
这一点先说在前面。
插件目录结构没有唯一标准答案，也没有必要为了“看起来专业”去套一个很重的模板。只要作者自己清楚：
- 入口在哪。
- 配置在哪。
- 组件定义在哪。
- 主要逻辑藏在哪。
那这个结构大概率就是可接受的。
所以这一篇不打算给你定规则，更不会要求所有插件都长成一样。这里更想做的，是给你几个简单示范，让你在插件做大时有个参考方向。
5.2 一个简单提醒：别让所有东西永远挤在 plugin.py
最开始把东西都放在 plugin.py 里很正常，甚至是推荐的。
但如果插件已经出现下面这些情况，通常就值得考虑拆分了：
- 配置已经明显独立出来了。
- 组件不只一个了。
- 某些逻辑会被多个组件共用。
- 你开始接入 Prompt、LLM、外部服务或其他 API。
不用把这件事想得很重。很多时候，整理结构并不意味着要大改，只是把“本来就不是一类东西的代码”分开放而已。
5.3 可以参考的几种示范
下面这几种结构都可以参考，但不要机械照抄，重点是理解它们各自适合什么情况。
示范 1：轻量插件，少量拆分就够了
像 plugins/comfyui_bridge/plugin.py 这种方向，就比较适合功能还不算特别散、但已经有配置和服务能力的插件。
它大致是这种感觉：
my_plugin/
├── manifest.json
├── plugin.py
├── config.py
└── service.py这种结构的好处是很直接：
- 入口文件很明确。
- 配置单独放。
- 主要能力也有自己的位置。
如果你的插件只是从“最小示例”再往前走一步，这种形态通常就已经够用了。
示范 2：功能开始变多，按能力拆几个文件
像 plugins/default_chatter/plugin.py 这类插件，就已经不是只靠一两个文件能讲清楚的了。它会有配置、提示词构建、运行流程、类型定义等不同部分。
这种方向大致会像：
my_plugin/
├── manifest.json
├── plugin.py
├── config.py
├── prompt_builder.py
├── runners.py
└── type_defs.py如果你的插件开始明显依赖 Prompt、LLM 或一段比较独立的能力流程，这种“按职责拆几个文件”的方式就会很自然。
示范 3：插件已经比较复杂，按子域分目录
像 plugins/booku_memory/plugin.py 这类插件，就已经进入更复杂的形态了。它下面会继续分成 agent/、service/ 之类的子目录。
这种方向更像：
my_plugin/
├── manifest.json
├── plugin.py
├── config.py
├── event_handler.py
├── agent/
└── service/当插件内部已经不只是“几个文件”，而是真正有几块相对独立的能力域时，按子目录去组织就会更舒服。
5.4 如果你问什么时候该整理
答案其实很简单：
当你自己开始觉得“找代码有点费劲”时，通常就已经值得整理了。
不用等到结构彻底失控再动手，也不用刚写完第一个插件就急着工程化。只要在插件成长过程中，让结构跟得上自己的理解，就够了。
5.5 和后续 API 章节的关系
这里简单预告一下。
后面我们会讲到一些对插件作者很重要的系统能力，比如 Prompt、LLM 以及其他插件系统 API。到那个时候你会更明显地感受到：
- 有些代码属于组件定义。
- 有些代码属于 API 调用。
- 有些代码属于把这些东西串起来的业务逻辑。
也正因为这样，插件结构这件事虽然不是主线，但也并不无关紧要。它不会决定一个插件能不能跑起来，却会影响一个插件以后是不是好继续写。
5.6 这一篇就记住一句话
如果要把这篇番外压缩成一句话，那就是：
插件小的时候不必过多在意结构，等它长大以后，适时整理一下便好；至于怎么整理，没有唯一答案，只要自己找得到代码、看得清全局，就已经足够了。
接下来我们回到主线，继续往前走：给插件加上配置。
贡献者
minecraft1024a
Windpicker-owo
