# 5. 番外：从单一文件到清晰结构

> **导读** 这一章是主线之外的番外篇，专门讨论插件项目结构。当插件功能还很简单时，结构本身并不重要；但随着组件增多、逻辑变复杂，一个清晰的目录布局会让开发和维护轻松很多。本章不规定唯一标准，而是通过几种典型示范，帮助你在插件成长时形成自己的判断。

这一篇不算主线章节，更像一个轻量番外。

前面我们一直在讲“先跑起来”，这没有问题。对于入门插件来说，能被系统识别、能正常加载、能把功能做出来，永远比“目录摆得漂不漂亮”更重要。

不过插件一旦开始长大，结构这件事迟早会冒出来。通常不是因为有人强迫你整理目录，而是因为你自己会慢慢感觉到：

- 文件开始变长了。
- 配置、组件、业务逻辑开始挤在一起了。
- 接 Prompt、LLM、Service 这类 API 时，有点不知道代码该往哪放。

这时候稍微整理一下项目结构，通常会让后面的开发轻松很多。

## 5.1 没有唯一正确答案

这一点先说在前面。

插件目录结构没有唯一标准答案，也没有必要为了“看起来专业”去套一个很重的模板。只要作者自己清楚：

- 入口在哪。
- 配置在哪。
- 组件定义在哪。
- 主要逻辑藏在哪。

那这个结构大概率就是可接受的。

所以这一篇不打算给你定规则，更不会要求所有插件都长成一样。这里更想做的，是给你几个简单示范，让你在插件做大时有个参考方向。

## 5.2 一个简单提醒：别让所有东西永远挤在 plugin.py

最开始把东西都放在 `plugin.py` 里很正常，甚至是推荐的。

但如果插件已经出现下面这些情况，通常就值得考虑拆分了：

- 配置已经明显独立出来了。
- 组件不只一个了。
- 某些逻辑会被多个组件共用。
- 你开始接入 Prompt、LLM、外部服务或其他 API。

不用把这件事想得很重。很多时候，整理结构并不意味着要大改，只是把“本来就不是一类东西的代码”分开放而已。

## 5.3 可以参考的几种示范

下面这几种结构都可以参考，但不要机械照抄，重点是理解它们各自适合什么情况。

### **示范 1：轻量插件，少量拆分就够了**

像 [plugins/comfyui_bridge/plugin.py](plugins/comfyui_bridge/plugin.py) 这种方向，就比较适合功能还不算特别散、但已经有配置和服务能力的插件。

它大致是这种感觉：

```text
my_plugin/
├── manifest.json
├── plugin.py
├── config.py
└── service.py
```

这种结构的好处是很直接：

- 入口文件很明确。
- 配置单独放。
- 主要能力也有自己的位置。

如果你的插件只是从“最小示例”再往前走一步，这种形态通常就已经够用了。

### **示范 2：功能开始变多，按能力拆几个文件**

像 [plugins/default_chatter/plugin.py](plugins/default_chatter/plugin.py) 这类插件，就已经不是只靠一两个文件能讲清楚的了。它会有配置、提示词构建、运行流程、类型定义等不同部分。

这种方向大致会像：

```text
my_plugin/
├── manifest.json
├── plugin.py
├── config.py
├── prompt_builder.py
├── runners.py
└── type_defs.py
```

如果你的插件开始明显依赖 Prompt、LLM 或一段比较独立的能力流程，这种“按职责拆几个文件”的方式就会很自然。

### **示范 3：插件已经比较复杂，按子域分目录**

像 [plugins/booku_memory/plugin.py](plugins/booku_memory/plugin.py) 这类插件，就已经进入更复杂的形态了。它下面会继续分成 `agent/`、`service/` 之类的子目录。

这种方向更像：

```text
my_plugin/
├── manifest.json
├── plugin.py
├── config.py
├── event_handler.py
├── agent/
└── service/
```

当插件内部已经不只是“几个文件”，而是真正有几块相对独立的能力域时，按子目录去组织就会更舒服。

## 5.4 如果你问什么时候该整理

答案其实很简单：

> 当你自己开始觉得“找代码有点费劲”时，通常就已经值得整理了。

不用等到结构彻底失控再动手，也不用刚写完第一个插件就急着工程化。只要在插件成长过程中，让结构跟得上自己的理解，就够了。

## 5.5 和后续 API 章节的关系

这里简单预告一下。

后面我们会讲到一些对插件作者很重要的系统能力，比如 Prompt、LLM 以及其他插件系统 API。到那个时候你会更明显地感受到：

- 有些代码属于组件定义。
- 有些代码属于 API 调用。
- 有些代码属于把这些东西串起来的业务逻辑。

也正因为这样，插件结构这件事虽然不是主线，但也并不无关紧要。它不会决定一个插件能不能跑起来，却会影响一个插件以后是不是好继续写。

## 5.6 这一篇就记住一句话

如果要把这篇番外压缩成一句话，那就是：

> **插件小的时候不必过多在意结构，等它长大以后，适时整理一下便好；至于怎么整理，没有唯一答案，只要自己找得到代码、看得清全局，就已经足够了。**

接下来我们回到主线，继续往前走：给插件加上配置。