1. 写在前面
导读 本章不涉及任何代码，它的任务是帮你建立对这份指南的整体预期：它为谁而写、以怎样的节奏展开、完成阅读后你将具备什么能力。如果你习惯直接动手，可以扫一遍各节标题后跳至第二章；如果你希望对整条学习路径有完整把握，通读本章只需几分钟，却能避免后续许多不必要的困惑。
如果你会一点 Python，也愿意花一点时间理解 Neo-MoFox 的运行方式，那么这份指南就是写给你的。
它不是那种开篇便将所有组件类型、生命周期、依赖关系一次性铺开的"系统说明书"，而更像一条循序渐进的实践路径：先做出一个真正能加载、能运行、能被亲手验证的插件，再慢慢看清它背后的结构，理解插件系统为什么会被设计成现在这样。
Neo-MoFox 的插件体系并不只是"把几段代码塞进一个目录"那么简单。插件会参与系统启动、组件注册与能力组合，并最终与整个 Bot 的运行时协同工作。因此，我们从一开始就不会把插件当作一批临时脚本来看待，而是将它视为一个有明确边界、有清晰职责、有扩展空间的开发单元来理解。
也正因如此，这份指南不会只告诉你"怎么写"，还会不断引导你去思考另一件同样重要的事：为什么要这样写。
1.1 这份指南适合谁
本指南主要面向以下读者：
- 能使用 Python，可以读懂类、函数、导入、异步函数等基础语法。
- 初次接触 Neo-MoFox，或虽然看过仓库，但尚未真正写过插件。
- 希望为社区或自己的 Bot 扩展新能力，而不仅仅是修改配置。
如果你已经熟悉 Bot 框架、组件化设计或事件驱动系统，前几章的节奏对你来说可能偏慢。即便如此，仍建议先顺着读下去——Neo-MoFox 的插件系统有其自己的一套组织方式，例如插件清单、组件签名、组件装载顺序，以及不同组件类型之间的职责分工。这些约定并不复杂，但值得从一开始就理解清楚，而不是在遇到问题后再反过来查。
1.2 阅读前你需要具备什么
开始阅读前，不需要掌握项目的全部细节，但最好已具备以下基础：
- 能在本地运行 Python 3.11 及以上版本。
- 知道如何安装项目依赖并启动项目。
- 对 Python 的面向对象写法有基本了解。
- 在阅读教程时，习惯结合项目源码一起看，而不是只盯着示例代码复制粘贴。
如果你对插件系统、Bot 框架、消息适配器、事件总线等术语还不熟悉，不必在意。本指南会尽量先用直观的场景铺垫，再逐步引入概念。很多术语第一次出现时不需要完全记住，只要了解它大致用来做什么即可，等到实际案例出现时，理解自然会逐渐清晰。
1.3 读完后你将能够做到什么
完成本指南后，你应当能够：
- 写出结构完整、可被 Neo-MoFox 正常发现和加载的插件。
- 理解插件、组件、配置与清单之间的组织关系。
- 了解 Command、Service、Tool、EventHandler、Chatter、Agent、Router、Adapter 各类组件分别适合解决什么问题。
- 将一个最小插件逐步演化为包含多个组件、具备清晰职责分工的完整实现。
- 在插件出现加载失败、依赖错误、配置异常时，具备基本的排查思路。
如果读到最后，你还能回答下面这个问题，那说明你已不只是"会照着教程写插件"，而是真正开始理解这个系统的设计意图了：
为什么某段逻辑应该放进 Service，而不是继续放在 Command 里？
这个问题看似具体，却几乎贯穿了后文所有的设计讨论。
1.4 这份指南会怎么展开
为了降低学习成本，整份指南会围绕同一个示例插件逐步推进，而不是每章换一个新案例。
这样做的好处是直接的：你不必在每一章重新理解一套新的业务背景，只需关注"这一章新增了什么设计"。上一章写的内容，下一章继续沿用；上一章留下的问题，在下一章中自然得到解答。示例插件会从一个只有单一入口的小例子，慢慢演化为包含多个组件、具备清晰职责分工的完整案例。
可以把这个过程想象成建造一座小屋：
- 第一阶段：先把门立起来，让它能打开——先让插件跑起来。
- 第二阶段：划分屋内的空间，让每个区域各司其职——按职责组织组件。
- 第三阶段：接通水电、打通通道，让不同部分真正协同——组件间的协作与扩展。
写插件的路径也大致如此：先有结果，再谈结构；先能工作，再谈优雅；先划清边界，再谈复用和扩展。
1.5 关于项目阶段的说明
Neo-MoFox 目前仍处于相对早期的演进阶段，这意味着两件事同时成立：插件系统已具备清晰的骨架，足以开始编写、使用并积累实践经验；与此同时，部分细节约定仍可能持续收敛和调整，尤其是在高级组件协作与工程化体验方面。
因此，本指南会尽量区分"当前稳定可依赖的部分"与"仍在演进中的部分"。已经确定的约定会作为实践直接给出；可能变化的部分，则会在适当位置作出提示，避免将阶段性的实现方式误当作固定规则。
这并不是一种缺陷。越早参与一个正在演进的系统，就越有机会真正理解它为什么会演变成现在这个样子。
1.6 开始之前的环境建议
继续阅读前，请先确认以下几点：
- 当前 Python 版本为 3.11 或更高。
- 项目依赖已通过
uv正常安装。 - 了解项目入口为根目录下的
main.py。 - 了解插件默认从
plugins目录中被发现和加载。
后文示例均基于这一套运行方式：
- 使用
uv管理依赖与运行环境。 - 将插件放置在
plugins目录下。 - 通过项目主入口启动 Neo-MoFox，由系统自动完成插件发现与加载。
如果你还没有把项目跑起来，建议先停下来确认好运行环境。调试插件时一个常见的陷阱是：误以为是插件代码有问题，实际上只是项目本身未能正常启动。这类错误排查起来并不复杂，但容易消耗不必要的精力。
1.7 带着这几个问题，进入下一章
读完本章，你暂时不需要记住任何名词。只需带着下面三个问题进入第二章：
- 一个 Neo-MoFox 插件最少需要哪些文件？
- 系统是通过什么机制识别一个插件的？
- 为什么我们从最简单的组件开始，而不是一开始就介绍完整体系？
如果这些问题已经让你有了一点好奇，那后续内容就有了最好的起点。
贡献者
minecraft1024a
Windpicker-owo
