插件自生成器(测试版) (Self-Writing Plugin) v0.2.1

让麦麦根据自然语言描述自动生成 MaiBot 插件代码。

这是一个实验性质的原型工具（0.2.1 测试版）。使用前请务必阅读本文档的全部内容，尤其是安全警告、免责声明和分级使用建议。

📦 安装方式

手动安装至目录

步骤 1：复制插件文件

将插件目录放入 MaiBot 的 plugins/ 目录下：

# Linux / macOS
cp -r self_writing_plugin/ /path/to/MaiBot/plugins/

# Windows (PowerShell)
Copy-Item -Recurse self_writing_plugin/ C:\path\to\MaiBot\plugins\

最终目录结构应为：

plugins/
└── self_writing_plugin/
    ├── _manifest.json
    ├── config.toml
    ├── plugin.py
    ├── README.md
    └── generators/
        ├── __init__.py
        ├── code_parser.py
        ├── llm_client.py
        ├── plugins_scanner.py
        ├── prompt_builder.py
        └── validator.py

步骤 2：检查目录权限

确保 MaiBot 进程对以下目录具有读写权限：

目录/文件	需要权限	用途
`plugins/self_writing_plugin/config.toml`	读写	MaiBot 热重载时会重写配置文件
`plugins/self_writing_plugin/staging/`	读写	暂存生成的插件代码（自动创建）
`plugins/generated/`	读写	确认安装后插件的输出目录（自动创建）

# Linux / macOS 权限示例
chmod -R 755 plugins/self_writing_plugin/
chmod 644 plugins/self_writing_plugin/config.toml

步骤 3：验证安装

重启 MaiBot 或在 WebUI 中重载插件
在聊天中发送 /write_help
如果收到帮助文档回复，说明安装成功

🔄 升级/更新

升级前备份（必须）

升级前务必备份以下数据，以防不兼容变更导致数据丢失：

备份项	路径	说明
配置文件	`plugins/self_writing_plugin/config.toml`	包含 access_token、白名单、API 密钥等
配置备份	`plugins/self_writing_plugin/config_back/`	历史配置备份
暂存数据	`plugins/self_writing_plugin/staging/`	生成的但未确认的插件代码
已安装生成插件	`plugins/generated/`	已确认安装的生成插件

备份命令示例：

# 创建备份
tar -czf maibot_self_writing_backup_$(date +%Y%m%d_%H%M%S).tar.gz \
  plugins/self_writing_plugin/config.toml \
  plugins/self_writing_plugin/config_back/ \
  plugins/self_writing_plugin/staging/ \
  plugins/generated/

升级步骤

备份上述所有数据
在 MaiBot WebUI 中禁用（unload）本插件
用新版本文件覆盖 plugins/self_writing_plugin/ 目录
对比新旧 config.toml，合并新增的配置项（切勿直接复制旧配置覆盖新配置，可能丢失新增字段）
在 MaiBot WebUI 中启用（load）本插件
发送 /write_help 验证升级成功
发送 /list_staged 检查暂存数据是否正常恢复

回滚步骤

如果升级后出现问题：

禁用本插件
用备份的旧版本文件覆盖 plugins/self_writing_plugin/
恢复备份的 config.toml
启用本插件
恢复备份的 plugins/generated/（如有必要）

🗑 卸载方式

完全卸载步骤

在 MaiBot WebUI 中禁用（unload）本插件
（可选）备份 plugins/generated/ 中的生成插件（如果仍需要使用）
删除插件目录：

rm -rf plugins/self_writing_plugin/

# 仅当不再需要任何生成插件时执行
rm -rf plugins/generated/

重启 MaiBot 或重载配置

注意：

删除本插件不会自动删除已安装的生成插件（plugins/generated/）。生成插件是独立的，需要手动管理

删除本插件后，已安装的生成插件仍然可以正常使用（它们不依赖本插件运行）

config_back/ 目录下的配置备份不会自动清理，卸载后需手动删除

💻 环境要求

项目	最低要求	推荐
Python	3.10+	3.11+
MaiBot	1.0.0	1.0.0
MaiBot SDK	2.0.0 ~ 2.99.99	2.x 最新版
操作系统	Linux / macOS / Windows	Linux (生产环境)
磁盘空间	≥ 10 MB（插件自身） ≥ 100 MB（含生成插件）	≥ 500 MB
内存	≥ 256 MB（插件自身无额外占用）	≥ 1 GB（含 LLM）

LLM 模型要求：

使用内置 MaiBot LLM 时无额外要求

使用自定义 API 时需网络连通性（能访问 API 端点）

生成质量与模型能力正相关，建议使用推理能力较强的模型

⚠️ 重要：安全警告与免责声明

🛡️ 安全警告

本插件生成的代码由 AI 模型（大语言模型/LLM）自动生成，并非人类编写。您必须了解以下全部风险：

🔴 代码信任与审查

AI 代码零信任原则：AI 生成的所有代码均应默认视为不可信来源。尽管本插件内置了 6 层自动安全验证机制，但这些机制是辅助性的检测工具，不是正式的安全审计替代品。验证可能无法覆盖：
- 隐蔽的后门或恶意逻辑（如特定条件下触发的不良行为）
- 通过间接方式（函数组合、反射、动态属性）实现的危险操作
- 语义层面的逻辑漏洞（验证层只检查语法和结构）
- Unicode 同形字或编码混淆绕过
必须人工审计：在任何环境中启用生成插件之前，您必须亲自（或请具备编程能力的人）审阅完整的 plugin.py 代码。绝对不要跳过代码审阅直接在生产环境中启用生成插件。建议的审阅步骤见下方"分级使用建议"。

🟠 运行时与系统风险

同进程运行：生成的插件在 MaiBot 的 同一进程 中运行，与其他所有插件共享相同的运行时环境。这意味着：
- 代码级别享有与任何手动编写的插件完全相同的能力
- 可以访问 MaiBot 配置、数据库、文件系统和网络
- 单个生成插件的崩溃可能影响整个 MaiBot 实例的稳定性
具体运行时风险（非穷举）：
- 数据泄露：通过 send.text 等能力向外部聊天流发送敏感信息
- 数据破坏：通过文件 I/O 或数据库操作修改/删除 MaiBot 数据
- 资源耗尽：死循环、递归过深、内存泄漏导致 CPU/内存/磁盘耗尽
- 服务中断：阻塞事件循环导致整个 Bot 无响应
- 能力声明不匹配：manifest 声明了一个能力，但代码使用了另一个，导致运行时错误或权限检查绕过
- 沙盒逃逸：虽然验证层尽力防范，但无法 100% 保证代码不包含系统级操作
LLM 模型提示注入风险：
- 恶意构造的需求描述可能诱导 LLM 忽略安全边界，生成包含危险代码的插件
- 本插件在 LLM prompt 中施加了明确的安全边界指令，但大语言模型的指令遵循并非绝对可靠
- 高级模型更容易产生"越狱"行为，低级模型更容易产生语法错误或逻辑缺陷
- 防御层级（由外到内）：
  1. Prompt 层安全边界包裹用户输入
  2. 6 层自动输出验证（AST → 能力白名单 → 复杂度 → 模式 → 依赖 → 水印）
  3. 生成预览 + 人工审查（最重要防线）
  4. 默认禁用状态 + 沙盒目录隔离
LLM 模型能力差异：
- 不同 LLM 模型对 MaiBot SDK 的理解深度和使用模式差异巨大
- 使用低能力模型可能导致：语法错误、逻辑缺陷、使用了废弃 API（如 @Action）、能力声明缺失或错误
- 建议使用推理能力较强的模型（如 GPT-4o、Claude 3.5 Sonnet、DeepSeek V3 等）

🟡 配置与密钥安全

API 密钥明文存储：
- 使用 [custom_api] 功能时，API 密钥以明文存储在 config.toml 中
- 禁止将此配置文件上传到 Git、网盘、或通过聊天工具分享
- 建议为自定义 API 创建专用的受限 API 密钥（具有最小权限和用量限制），而非使用主密钥
- 密钥不会在日志输出中出现，但内存中仍存在完整密钥
暂存数据安全性：
- 生成的插件代码在确认/拒绝前暂存在 plugins/self_writing_plugin/staging/ 目录中
- 暂存文件包含完整的插件源代码，如果服务器被入侵可被读取
- 过期暂存文件在 1 小时 后自动清理（通过 /list_staged 或插件重载触发）
- 安装后的插件位于 plugins/generated/ 目录，与手动编写的插件物理隔离
操作员白名单局限性：
- 白名单验证依赖于适配器正确传递用户身份信息（sender_id / user_id / operator）
- 如果适配器未正确实现身份传递，白名单可能被绕过
- 建议同时在 MaiBot 层面配置访问控制，形成双层防护
- enabled = true 且两个名单均为空时，所有用户都会被拒绝（安全默认设计）
访问令牌的安全局限性：
- access_token 以明文存储在 config.toml 中，与 api_key 等敏感信息同文件存放
- 访问令牌是确认机制而非安全机制，它只在应用层拦截命令，不提供密码学级别的访问控制
- 任何人只要获得 config.toml 文件的读写权限，就可以修改或删除 token
- 访问令牌不能防护以下攻击场景：
  - 操作系统级别的权限提升
  - 其他有文件读写权限的插件或进程修改配置
  - 通过 MaiBot WebUI 修改配置绕过令牌检查
- 如果 config.toml 文件因不当分享而泄露，攻击者可以知晓您已确认条款并可能推断其他配置信息
- 建议：配合操作系统的文件权限控制（如 chmod 600）和 MaiBot 自身的访问控制，形成多层防护
- 访问令牌不记录设置时间、操作人、审批流程，不满足合规审计要求
生成代码中的硬编码凭据与敏感信息风险：
- LLM 的训练数据可能包含示例代码中的 URL、API 端点、默认凭据或测试密钥，这些可能在生成代码时被无意中嵌入
- 生成的插件如果涉及调用外部 API，可能在代码中硬编码 API 密钥、访问令牌或其他凭据
- 生成代码中的字符串常量可能包含被 LLM "记忆"的训练数据片段，包括但不限于内部 IP 地址、数据库连接串、邮箱地址等
- 应在人工审计时重点检查代码是否存在硬编码的敏感信息
多生成插件并发交互风险：
- 当多个由 AI 生成的插件同时在 MaiBot 中运行时，可能产生不可预见的交互冲突：
  - 状态竞争：多个插件同时读写共享状态（如全局变量、文件、数据库记录）可能导致数据不一致
  - 事件传播链：一个生成插件的输出可能意外触发另一个生成插件的事件处理器，形成不可控的级联行为
  - 资源争用：多个生成插件争抢内存、文件句柄、网络连接等有限资源
  - 命令命名冲突：不同生成插件可能注册相同名称的命令或事件处理器名
- 生成插件的代码不会考虑与其他生成插件的共存性，因为它们是在不同时间独立生成的
- 建议每次新增生成插件后，在测试环境中整体回归测试已有插件功能
日志与输出泄露风险：
- 生成的插件可能包含 print()、日志输出或调试语句，这些输出可能意外泄露：
  - MaiBot 的配置信息（如数据库路径、WebUI 地址、其他插件配置）
  - 用户会话数据（聊天内容、用户 ID、消息时间戳）
  - 内部文件系统路径和目录结构
  - 其他插件的运行时状态和内部数据
- 日志系统通常由 MaiBot 全局管理，生成插件的调试输出可能被自动记录到持久化日志中，增加泄露面
- 如果日志被分享或用于排查问题，其中的敏感信息可能扩散到更多人员
卸载/删除不彻底导致的残留风险：
- 如果生成插件在执行期间注册了以下资源，仅删除插件目录不会自动释放：
  - 通过 asyncio.create_task() 创建的后台异步任务（除非插件在 on_unload 中正确取消）
  - 使用 asyncio.get_event_loop().call_later() 或类似方式注册的定时回调
  - 通过 SDK 注册的事件处理器（部分实现可能缓存处理器引用）
  - 打开的文件句柄、网络连接、数据库连接等系统资源
- AI 生成的 on_unload 方法可能不完整或不正确，导致资源泄露
- 残留的异步任务可能在下次 MaiBot 启动时引发异常
- 建议清理生成插件后重启 MaiBot，并检查日志中是否有相关异常
配置文件权限与篡改风险：
- 生成插件的 config.toml 文件如果文件系统权限设置不当（如 chmod 777），可能被以下来源修改：
  - 同一服务器上的其他用户或进程
  - 其他具有文件写入能力的生成插件
  - 通过 WebUI 管理界面意外修改
- 如果生成插件的配置中包含自定义 API 密钥、白名单用户 ID 等敏感字段，文件权限过宽将直接导致这些信息暴露
- 建议将生成插件的配置目录权限设为 700（仅目录所有者可读写）或 MaiBot 进程用户的最小必要权限
联网行为不可控风险（放宽网络限制后）：
- 如果用户从 [safety] 的 forbidden_imports 中移除了 socket 等网络相关模块：
  - 生成的插件可能向任意网络地址发起连接，包括内网服务、恶意 C2 服务器或数据收集端点
  - 网络请求可能泄露服务器的公网 IP 地址、内部网络拓扑、DNS 查询记录
  - 生成的代码可能下载并执行外部资源（尽管 AST 验证拦截部分动态执行，但无法覆盖所有绕过方式）
  - 网络超时设置缺失或不当可能导致请求长时间挂起，阻塞 MaiBot 事件循环
- 放宽网络限制前，请在人工审计时严格检查所有网络相关代码
- 建议使用网络隔离或防火墙规则限制生成插件的出站连接范围
环境依赖与兼容性风险：
- 不同操作系统（Linux/macOS/Windows）之间的差异可能导致生成插件行为不一致：
  - 路径分隔符（/ vs \）处理不当
  - 文件权限模型差异（如 Windows 无 chmod 语义）
  - 系统调用和子进程创建方式的平台差异
- Python 版本差异：生成的代码可能使用了仅在新版本中可用的语法或库特性
- 文件编码问题：生成的代码可能在处理非 UTF-8 文件或路径时出错
- MaiBot 部署环境差异：不同部署方式（Docker/直接安装/虚拟环境）的文件路径和权限模型不同
- 建议生成后在目标部署环境中实际测试，而非仅在开发环境中验证
WebUI 管理安全隐患：
- 通过 WebUI 启用/禁用生成插件时，管理界面可能不会完整展示生成代码的全部内容
- 存在以下风险场景：
  - 在 WebUI 中误点击"启用"而未经代码审阅
  - 多人共享 WebUI 管理权限时，其他人可能未经授权启用未审计的生成插件
  - WebUI 的配置编辑功能可能无法正确显示或保留生成配置文件中的特殊字段
- 建议仅在确认代码安全后通过 WebUI 管理生成插件，而非在 WebUI 中初次启用未经审计的插件

📜 免责声明

无担保（AS IS）：本插件按"现状"（AS IS）提供，不提供任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性、非侵权、可用性、准确性、可靠性的担保。插件开发团队不保证本插件无缺陷、无错误或无安全漏洞。
使用风险自负：您使用本插件生成、存储、安装、修改和运行任何生成插件的行为完全出于您的自愿，并自行承担由此产生的全部风险和责任。生成插件可能包含错误、漏洞、恶意行为、性能问题，或与其他插件/系统产生不可预见的交互冲突。
不构成专业建议：本插件生成的任何代码、分析、建议或输出均不构成专业软件开发建议、安全审计结果或法律合规意见。您不应将 AI 生成的代码视为经过安全审计、代码审查或质量保证的产物。在依赖生成代码做出关键决策前，您应咨询合格的专业人士。
责任豁免：插件开发团队及所有贡献者对于因使用或无法使用本插件或其生成内容而产生的任何直接、间接、偶然、特殊、惩罚性、示范性或后果性损害（包括但不限于数据丢失、系统故障、安全漏洞、服务中断、名誉损害、业务中断、利润损失、经济损失、第三方索赔）不承担任何责任，即使已被告知此类损害的可能性。此责任豁免在适用法律允许的最大范围内有效。
无审计义务：插件开发团队对任何生成插件的代码内容没有主动审计义务。6 层安全验证是辅助性的自动检测工具，不是也不可能替代正式的安全审计。安全验证机制可能对恶意代码产生漏报（未检测到的危险代码）或误报（拒绝安全的合法代码），开发团队不对漏报或误报导致的任何后果负责。
第三方服务风险：如果您启用了自定义 API 功能：
- 您使用的第三方 LLM 服务（如 OpenAI、DeepSeek、Anthropic、Ollama、本地模型等）的隐私政策、服务条款、数据处理方式、数据驻留和安全性由各提供商自行决定
- 本插件不对第三方服务的行为、响应质量、可用性、安全性、隐私保护或合规性负责
- 您的 prompt 和生成内容可能会通过第三方服务的网络传输并在其服务器上处理
- 请在使用前审阅您所选 LLM 提供商的隐私政策和数据处理条款
法律合规责任：您应自行确保使用本插件及其生成内容的行为符合您所在司法管辖区的所有适用法律法规，包括但不限于数据保护法（如 GDPR）、网络安全法、出口管制法、知识产权法。某些司法管辖区可能对自动化代码生成、AI 生成内容的使用有特殊的合规和披露要求。
知识产权声明：
- 本插件自身采用 GPL v3.0 或更高版本许可证
- 生成插件的许可证由用户在 manifest license 字段中自行指定
- 生成插件的版权归属按生成时所选许可证的条款确定
- 使用参考插件（--from）功能生成代码时，需自行注意原始插件的许可证限制
版本声明与兼容性：本插件为 0.2 测试版原型。API、配置结构、安全验证机制、命令接口和行为可能在后续版本中发生重大且不向后兼容的变化。升级前必须备份您的以下数据：
- config.toml 配置文件
- staging/ 目录中的暂存数据
- plugins/generated/ 目录中的已安装生成插件
同意与接受：通过设置非空的 access_token 值并启用和使用本插件（包括但不限于安装、配置、执行任何命令、安装任何生成插件），即表示您已完整阅读、充分理解并自愿同意上述所有安全警告（共 18 条）和免责声明（共 16 条）。如果您不完全同意这些条款，请不要设置 access_token、立即停止使用并禁用（unload）本插件。
数据训练与隐私风险：
- 使用自定义 API 时，您的需求描述、参考插件代码和生成结果可能被第三方 LLM 服务商用于模型训练、服务改进、数据标注或其他商业目的
- 不同 LLM 服务商的数据使用政策差异很大：部分服务商明确禁止将 API 调用数据用于训练，部分默认允许，部分提供 opt-out 选项
- 您完全自行承担因使用第三方 LLM 服务而产生的数据隐私风险
- 本插件开发团队不对第三方 LLM 服务商的数据处理行为、隐私保护措施或数据泄露事件负责
- 如果您的需求描述中包含商业机密、用户隐私数据或受监管信息，强烈建议使用本地部署的 LLM（如 Ollama）而非第三方 API
可分割性：
- 如果本免责声明的任何条款被有管辖权的法院认定为无效、非法或不可执行，该条款应在必要的最小范围内被修改或删除
- 其余条款应在法律允许的最大范围内继续保持完全效力
- 被认定无效的条款应在不违背其原始意图和法律的前提下，被解释为最接近原意的有效条款
- 本免责声明的任何权利或条款的放弃，不得被视为对任何其他权利或条款的放弃
管辖法律与争议解决：
- 本免责声明及因本插件产生的任何争议，适用本插件开发团队所在地法律，但不得排除您所在司法管辖区的强制性消费者保护法律
- 因使用本插件产生的任何争议，双方应首先通过友好协商解决
- 协商不成的，任何一方可将争议提交有管辖权的法院解决
- 本插件开发团队不保证本插件在所有司法管辖区的合法性和可用性，用户应自行了解并遵守当地法律
- 如果您所在司法管辖区不允许或限制本免责声明中的部分条款（如责任豁免范围），这些条款可能在您的辖区内受到限制
生成代码供应链风险：
- 使用 --from 参数参考已有插件生成代码时，生成的插件可能继承参考插件的以下问题：
  - 设计缺陷或架构问题
  - 未公开的安全漏洞
  - 不良的编码实践或反模式
  - 过时的 SDK API 调用方式
  - 不恰当的错误处理或日志记录习惯
- 参考插件本身可能包含未被发现的安全问题，本插件不会对其进行安全审计
- 生成插件的安全性受限于参考插件的质量、LLM 的理解能力和验证机制的覆盖范围
- 使用自定义参考插件（非官方示例）生成代码时，风险显著增加
服务连续性与维护：
- 本插件为社区维护的实验性项目，开发团队不承诺：
  - 持续提供维护、更新、安全补丁或功能改进
  - 保持与 MaiBot 未来版本的兼容性
  - 修复所有已报告或未报告的缺陷
  - 在特定时间内响应安全问题或漏洞报告
- 插件可能在任何时候：
  - 停止维护（archived/abandoned）
  - 产生破坏性变更（breaking change），且不提供迁移工具
  - 因上游依赖（MaiBot SDK、LLM API）变更而无法使用
- 用户应自行做好数据备份、迁移预案和应急预案
- 生产环境中使用本插件时，应评估维护风险并建立备用方案
不可抗力：
- 因超出合理控制范围的事件（"不可抗力事件"）导致的任何延迟、失败或损失，开发团队不承担任何责任
- 不可抗力事件包括但不限于：
  - 自然灾害（地震、洪水、火灾、台风等）
  - 战争、恐怖主义、暴动、内乱
  - 政府行为、法律法规变更、进出口管制
  - 网络攻击（DDoS、DNS 劫持、大规模入侵等）
  - 第三方服务中断或故障（云服务商宕机、LLM API 服务不可用、网络基础设施故障）
  - 流行病、疫情、隔离措施
  - 电力中断、电信中断
- 不可抗力事件持续期间，本免责声明的相关义务暂停履行

🔑 访问令牌 (Access Token) — 强制确认机制

为什么需要访问令牌

本插件具有自动生成并安装可执行代码的能力，生成的插件在 MaiBot 同一进程中运行，享有与手动编写插件完全相同的能力和权限。这是一个高风险操作，因此设计上强制要求您在配置文件中显式设置访问令牌，以确认您：

已完整阅读本文档中的全部安全警告（共 18 条，见上方"安全警告"章节）
已充分理解上述安全警告中描述的所有风险，包括但不限于：
- AI 生成代码的不可信性
- 同进程运行的权限风险
- 数据泄露、数据破坏、资源耗尽、服务中断等具体风险
- LLM 提示注入的潜在风险
- API 密钥明文存储的安全隐患
- 白名单验证的局限性
- 生成代码中嵌入的凭据和敏感信息风险
- 多生成插件并发交互的不可预见风险
- 日志与输出泄露风险
- 卸载不彻底的资源残留风险
- 配置文件权限与篡改风险
- 联网行为不可控风险
- 环境依赖与兼容性风险
- WebUI 管理安全隐患
已完整阅读本文档中的全部免责声明（共 16 条，见上方"免责声明"章节）
自愿同意在无担保、风险自负、自行承担全部责任的前提下使用本插件
了解本插件为 0.2 测试版原型，API 和行为可能在后续版本中发生不向后兼容的变化

如何设置访问令牌

编辑 plugins/self_writing_plugin/config.toml，在 [plugin] 节中添加或修改：

[plugin]
enabled = true
config_version = "0.2.1"
access_token = "I_ACCEPT"

设置项	说明
`access_token = ""`（默认）	插件拒绝所有命令（`/write_help` 除外），提示先阅读文档
`access_token = "I_ACCEPT"`	推荐值。显式表达您已阅读并接受全部条款
`access_token = "任意非空字符串"`	等同于已确认。自定义字符串也不会影响功能

技术细节

检查时机：每次执行用户命令时实时检查（非缓存）。如果热重载后 token 被清空，下一次命令立即被拒绝
检查顺序：访问令牌检查在权限检查链中的位置为：
1. enabled 检查 → 插件是否启用
2. access_token 检查 → 访问令牌是否已设置（本层）
3. operator_whitelist 检查 → 用户是否在白名单
4. busy 检查 → 是否有正在进行的任务
检查范围：覆盖 /write_plugin、/modify_plugin、/fix_plugin、/analyze_plugin、/confirm_plugin、/reject_plugin、/list_plugins、/list_staged、/view_plugin、/abort 共 10 个命令
例外命令：/write_help 不受令牌限制，始终可用（帮助文档本身即为告知用户如何设置访问令牌的入口）
拒绝提示：被拒绝时插件会通过聊天消息直接向使用者发送提示，告知文档路径和配置路径。提示消息简短，仅说明需要阅读 README 并设置 token，不包含条款细节（条款细节仅在本文档中）
设计理念：拒绝消息是简短的导航提示（"去哪里看、怎么设置"），文档是详细的条款说明（"看了什么、同意什么"）。这样确保用户必须实际打开文档阅读才能了解全部内容，而非通过拒绝消息获取摘要后直接填入
热重载行为：
- MaiBot 热重载配置时会重写 config.toml，不会丢失 access_token 字段的值（只要您在热重载前正确地将其写入了文件中）
- 如果通过 WebUI 修改配置后 token 被意外清空，所有命令立即被拒绝
- 配置备份文件（config_back/）不会自动恢复 token
存储安全：令牌以明文存储在 config.toml 中。以下措施降低泄露风险：
- 请勿将 config.toml 上传到 Git、网盘或通过聊天工具分享
- 建议在 Git 仓库中将 config.toml 加入 .gitignore
- 令牌不是密码/密钥，仅为确认标志，泄露不直接导致安全问题
- 但泄露可能让他人知晓您已跳过安全审阅流程
- 如果您使用自定义 API 并将 api_key 存放在同一文件中，泄露将直接导致密钥暴露
多用户场景：访问令牌是全局设置（而非按用户），一旦设置，所有通过白名单的用户均可使用插件。如果您需要更细粒度的用户确认追踪，建议配合操作员白名单使用
合规记录：访问令牌设置时间不会被记录。如果您需要合规审计追踪，建议自行记录设置 token 的时间、操作人和审批流程

法律声明

通过设置非空的 access_token 值，您承认并同意：

您已阅读、理解本插件的全部安全警告和免责声明
您接受"现状"（AS IS）条款，不要求插件开发团队提供任何形式的担保
您自行承担使用本插件及其生成代码的全部风险和责任
您同意在适用法律允许的最大范围内豁免插件开发团队的责任
您确认本确认机制不构成任何形式的法律建议，也不影响免责声明的法律效力
如果您代表组织或实体使用本插件，您声明您有权代表该组织/实体接受这些条款

如果您不完全同意上述任何一条，请不要设置访问令牌并停止使用本插件。 您仍然可以使用 /write_help 查看本文档，或卸载插件。

📚 分级使用建议

根据您的编程经验和 MaiBot 熟悉程度，请选择适合您的使用方式。无论哪个等级，首次使用前请通读安全警告部分。

🟢 等级一：完全不懂编程的小白用户

您可能不知道 Python 是什么，也没有写过代码。您只是想用自然语言让麦麦帮您做一个简单的功能。

✅ 适合您的操作

操作	风险等级	说明
`/list_plugins`	🟢 安全	仅查看已有插件列表，不执行任何代码
`/write_help`	🟢 安全	查看帮助文档
`/analyze_plugin <已有插件> --check`	🟢 安全	让 AI 分析一个现有插件做什么用、有没有安全问题
`/analyze_plugin <生成插件> --check`	🟢 安全	在安装前，让 AI 帮您审查生成的代码

⚠️ 需要别人帮助的操作

操作	说明
`/write_plugin`	可以尝试生成，但不要自己执行 `/confirm_plugin`
`/view_plugin`	可以查看代码
`/confirm_plugin`	禁止：请让懂编程的朋友帮您审阅代码后再安装
`/modify_plugin`	同上

📋 小白用户安全清单

生成插件前：
- 描述需求时尽量具体、清晰，避免模糊指令
- 不要说"帮我写一个能操作系统的插件"之类的话
- 描述要做什么，而不要说怎么做（让 AI 自己决定实现方式）
生成插件后，安装前（必须执行）：
- 运行 /view_plugin <ID> 截图发给懂编程的朋友
- 运行 /analyze_plugin <ID> --check 并截图
- 让朋友确认代码安全后，由朋友帮您 /confirm_plugin
- 绝对不要自己凭感觉判断"看起来没问题"就安装
安装后：
- 首次启用后在测试群/私聊中观察行为
- 如果出现异常（Bot 卡住、不断发消息、功能异常），立即禁用插件
善用 AI 辅助审查：
- 将 /view_plugin <ID> 的完整代码和 /analyze_plugin <ID> --check 的结果一起发给 ChatGPT / Claude / DeepSeek 等 AI 助手
- 提问模板："这是一段由 AI 自动生成的 MaiBot 插件代码，请帮我审查它是否安全，有没有恶意行为或逻辑错误。以下是完整代码：[粘贴代码]。以下是自动安全检查结果：[粘贴分析结果]。"
- AI 辅助审查虽然不是 100% 可靠，但能大幅提高发现问题的概率

🟡 等级二：懂一些编程但不太熟悉 MaiBot 的用户

您会写 Python，但不太了解 MaiBot 的 SDK、插件系统或事件模型。

✅ 适合您的操作

您可以使用全部命令。但请遵循以下审阅流程：

📋 中等用户安全清单

生成前：
- 如果需求涉及 EventHandler（监听消息），先用 /analyze_plugin <参考插件> --check 了解参考插件的结构
- 使用 --from 参数指定参考插件，可以大幅提高生成质量
- 参考插件建议选择功能相似的：事件监听 → deepseek-v4-pro.self-writing-plugin，简单命令 → deepseek-v4-pro.avatar-fetcher-plugin
生成后审阅要点：
- manifest 检查：capabilities 是否与代码中实际使用的 ctx 能力匹配？用 /analyze_plugin <ID> 查看
- EventHandler 检查：是否检查了 is_command？返回值是否正确？
- 导入检查：是否有不应该出现的模块导入？
- 逻辑检查：代码的业务逻辑是否符合需求描述？
- 配置检查：config.toml 的 section 是否与 PluginConfigBase 子类名对应？
安装后测试：
- 先在私聊或测试群中启用，验证行为
- 检查 MaiBot 日志是否有报错
- 如果出错，使用 /fix_plugin <ID> <错误日志> 让 AI 自动修复
- 错误日志中包含 Python traceback 信息时修复效果最好
修改迭代：
- 使用 /modify_plugin <ID> <具体需求> 进行功能修改
- 修改需求越具体越好："把回复文字改成图片" 比 "改一下回复方式" 效果好
- 每次修改后重新审阅代码，关注变化的部分
善用 AI 辅助审查：
- 即使是懂编程的用户，AI 辅助审查也是有价值的
- 重点问 AI 三个问题：
  1. "这段代码是否包含安全漏洞？"
  2. "Event Handler 的实现是否正确？"
  3. "有哪些潜在的运行时错误？"

🔵 等级三：编程能力强的用户

您熟悉 Python、了解 MaiBot SDK 和插件系统，能够阅读和修改生成的代码。

✅ 适合您的操作

您可以使用全部功能，并能在此基础上进行深度定制。

📋 高级用户建议

高效生成策略：
- 使用 /analyze_plugin <参考> --check 快速了解参考插件的架构
- 用 --from 指定架构最接近的参考插件，生成质量最高
- 复杂插件可以分步生成：先生成核心功能 → 确认安装 → 用 /modify_plugin 逐步添加功能
直接修改生成代码：
- 确认安装后，直接编辑 plugins/generated/<ID>/plugin.py
- 编辑后确保 manifest 的 capabilities 与实际使用的 ctx 能力保持一致
- 如果改坏了，可以用 /modify_plugin 让 AI 帮你重新生成
调试与修复：
- 遇到运行时错误，直接复制 Python traceback 用 /fix_plugin <ID> <完整错误日志>
- 错误日志越完整，修复准确度越高
- 如果是逻辑问题（不报错但行为不对），用 /modify_plugin 描述具体的问题和期望行为
自定义安全策略：
- 可以编辑 [safety] 的 forbidden_imports 调整安全策略
- 需要网络请求的插件（如调用外部 API）：移除 socket 和 sys 的限制
- 警告：放宽安全策略前务必充分思考风险
审查深度建议：
- 检查生成的代码是否存在竞态条件（多个协程共享状态）
- 检查异步操作是否有合理的超时和错误处理
- 检查 on_load / on_unload 是否正确管理资源（定时器、连接、缓存）
- 检查配置默认值是否安全（特别是 enabled 是否默认 false）
贡献与反馈：
- 如果发现生成质量反复不佳的类型，可以考虑总结规律反馈给开发团队
- 如果您自己编写了优秀的模板插件，可以用作参考提高生成质量

快速开始

0. 设置访问令牌（必须）

本插件强制要求在配置文件中设置 access_token 才能使用任何功能。此设计确保您在启用插件之前已经完整阅读并理解本文档中全部安全警告与免责声明。

编辑 plugins/self_writing_plugin/config.toml：

[plugin]
enabled = true
config_version = "0.2.1"
access_token = "I_ACCEPT"

access_token 详细说明：

默认值：空字符串 ""，此时插件拒绝所有命令（/write_help 除外）

填入任意非空值：视为您已完整阅读、充分理解并自愿同意本文档全部安全警告（18 条）和免责声明（16 条），自行承担使用本插件及其生成代码的全部风险和责任

推荐值："I_ACCEPT" 或 "I_HAVE_READ_AND_AGREE" 或任意自定义字符串

存储位置：明文存储在 config.toml 中，请勿分享此文件

不设 token 时的行为：任何命令（/write_plugin、/list_plugins、/confirm_plugin 等）均返回拒绝消息，提示用户先阅读 README 并设置访问令牌

例外：/write_help 命令始终可用，不受访问令牌限制

1. 启用插件

编辑 plugins/self_writing_plugin/config.toml：

[plugin]
enabled = true
config_version = "0.2.1"

或在 MaiBot WebUI 中将插件状态设为"启用"。

2. 查看可用参考插件

/list_plugins

3. 查看帮助

/write_help

4. 生成插件

/write_plugin 帮我写一个/hello命令，回复你好世界

或指定参考插件：

/write_plugin 类似头像获取但获取B站头像 --from deepseek-v4-pro.avatar-fetcher-plugin

5. 审查代码

/view_plugin <插件ID>           ← 查看完整代码
/analyze_plugin <插件ID> --check ← 安全排查

6. 确认安装

/confirm_plugin <插件ID>

7. 手动启用生成的插件

进入 plugins/generated/<插件ID>/，编辑 config.toml：

[plugin]
enabled = true

命令参考

生成与安装

命令	格式	功能
`/write_plugin`	`/write_plugin <功能描述>`	根据自然语言描述生成插件代码
	`/write_plugin <描述> --from <插件ID>`	以指定已有插件为参考生成
	`/write_plugin <描述> 参考:<插件ID>`	同上（中文语法）
`/view_plugin`	`/view_plugin <插件ID>`	查看暂存插件的完整代码（转发消息）
`/confirm_plugin`	`/confirm_plugin <插件ID>`	确认安装暂存中的插件到输出目录
`/reject_plugin`	`/reject_plugin <插件ID>`	放弃暂存中的插件（会同时取消进行中的生成）
`/list_staged`	`/list_staged`	查看所有待确认的暂存插件及剩余有效时间

修改与修复

命令	格式	功能
`/modify_plugin`	`/modify_plugin <ID> <修改需求>`	按需求修改已生成/已安装的插件
`/fix_plugin`	`/fix_plugin <ID> <错误描述>`	提交报错日志，AI 分析并修复
`/analyze_plugin`	`/analyze_plugin <ID>`	分析插件功能和原理
	`/analyze_plugin <ID> --check`	附带安全排查

管理

命令	格式	功能
`/list_plugins`	`/list_plugins`	列出所有可参考的已有插件
`/abort`	`/abort`	取消当前正在进行的后台生成任务
`/write_help`	`/write_help`	显示帮助文档

命令说明

权限：当 [operator_whitelist] 启用时，仅白名单中的用户可执行命令；未启用时所有用户可执行。此外，所有命令（/write_help 除外）均要求已设置 access_token
忙碌保护：生成过程中非操作员消息被自动拦截；操作员仅能执行 /abort、/reject_plugin、/list_staged 三条中断指令
异步执行：/write_plugin、/modify_plugin、/fix_plugin、/analyze_plugin 为异步任务，命令立即返回，完成后通知结果

完整配置项

配置文件位置

plugins/self_writing_plugin/config.toml

注意：MaiBot 热重载机制会在配置变更时重写此文件，请勿在文件内添加自定义注释（注释会被清除）。

`[plugin]` — 插件基础设置

字段	类型	默认值	说明
`enabled`	bool	`false`	是否启用插件。首次使用需手动改为 `true`
`config_version`	str	`"0.2.1"`	配置版本号，用于兼容性校验。请勿手动修改
`access_token`	str	`""` (空)	【重要】访问令牌。填入任意非空值即视为您已完整阅读并同意本文档全部安全警告与免责声明。留空则插件拒绝所有操作（`/write_help` 除外）。详见上方"访问令牌"章节

`[generation]` — 生成参数

字段	类型	默认值	约束	说明
`model`	str	`"replyer"`	—	LLM 模型任务名。`replyer`=回复模型 / `utils`=工具模型 / `planner`=规划模型
`model_temperature`	float	`0.3`	—	预留字段。当前版本由 prompt 内部控制
`max_retries`	int	`2`	0 ≤ N ≤ 5	验证失败后的最大重试次数。每轮重试会将验证错误反馈给 LLM 要求修复
`output_base_dir`	str	`"plugins/generated"`	—	生成插件的输出目录。相对路径基于 `plugins/` 根目录
`llm_timeout_seconds`	int	`25`	10 ≤ N ≤ 30	LLM 调用超时时间。MaiBot 平台 `cap.call` 硬限制为 30 秒

`[safety]` — 安全设置

字段	类型	默认值	约束	说明
`require_confirmation`	bool	`true`	—	是否需要在安装前预览确认。强烈建议保持启用
`forbidden_imports`	str	见下	—	禁止生成的插件导入的 Python 模块，逗号分隔
`max_file_size_bytes`	int	`204800`	≥ 1024	单个生成文件的最大字节数（200KB）

默认禁止导入的模块：

os, subprocess, socket, sys, ctypes, multiprocessing, pickle, marshal, importlib

共 9 个模块，在 AST 分析和正则模式扫描两层同时拦截。如需放宽限制，删除对应模块名即可（不推荐）。

`[custom_api]` — 自定义 API（可选）

字段	类型	默认值	说明
`enabled`	bool	`false`	设为 `true` 时使用自定义 API 替代内置 LLM
`api_url`	str	`""`	API 端点地址。必须兼容 OpenAI 的 `/chat/completions` 格式
`api_key`	str	`""`	API 密钥。明文存储，请勿分享此文件。密钥不会出现在日志输出中
`model`	str	`""`	模型名。留空则不指定模型（部分 API 要求必填）

常用配置示例：

# OpenAI GPT-4o
[custom_api]
enabled = true
api_url = "https://api.openai.com/v1"
api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
model = "gpt-4o"

# DeepSeek
api_url = "https://api.deepseek.com/v1"
model = "deepseek-chat"

# 本地 Ollama
api_url = "http://localhost:11434/v1"
model = "llama3"

`[operator_whitelist]` — 操作员白名单

字段	类型	默认值	说明
`enabled`	bool	`false`	是否启用白名单。启用后仅白名单中的用户/聊天流可执行命令
`allowed_users`	str	`""`	允许的用户 ID，逗号分隔。例如 `"123456,789012"`
`allowed_streams`	str	`""`	允许的聊天流 ID，逗号分隔。留空不限制聊天流
`reject_message`	str	见默认值	非白名单用户被拒绝时的提示消息

注意：enabled = true 且 allowed_users 和 allowed_streams 均为空时，所有用户都会被拒绝（安全默认）。请至少填写一个名单。

用户身份识别优先级：

kwargs.sender_id  →  kwargs.user_id  →  kwargs.operator  →  无（仅匹配 stream_id）

安全验证机制详解

生成的插件代码需通过 6 层安全验证 才能进入暂存：

第 1 层：AST 安全分析

通过 Python ast 模块解析代码结构，精确检测：

禁止导入：9 个默认模块（os/subprocess/socket/sys/ctypes/multiprocessing/pickle/marshal/importlib），可配置扩展
禁止调用危险函数：eval()/exec()/compile()/__import__()/getattr()/setattr()/delattr()/globals()/locals()/vars()/breakpoint()
禁止访问危险属性：.__subclasses__/.__bases__/.__mro__/.__builtins__/.__globals__/.__code__/.__closure__/.__func__/.__self__
文件写入检测：静态检测 open() 的 mode 参数，拦截写入/追加/创建模式；变量 mode 直接拦截
入口函数检查：确保 create_plugin() 存在

第 2 层：Capability 白名单

仅允许 18 种安全能力
明确禁止 5 个高危前缀：component.* / gateway.* / tool.* / knowledge.* / llm.*

第 3 层：代码复杂度限制

指标	上限
行数	1000
函数数	30
导入数	20
AST 节点数	5000

第 4 层：正则模式扫描

24 组危险模式全面扫描，涵盖动态执行、网络请求、系统命令、文件操作、反序列化、代码混淆、作用域访问、类层级内省、底层操作。

第 5 层：依赖限制

禁止外部 pip 依赖
禁止依赖其他插件/适配器
仅允许 maibot_sdk/maibot- 系列

第 6 层：审计水印与溯源

生成的 plugin.py 头部注入：生成工具名/版本、生成时间（UTC）、插件 ID、需求描述、安装位置、安全审查提醒
每个生成插件计算 SHA256 哈希（16 位截断），在预览中展示

修复重试机制

验证失败时，错误列表反馈给 LLM 要求针对性修复。每轮重试包含：原始需求、错误列表（最多 10 条）、6 类修复策略指引、完整 SDK 参考文档、插件目录上下文。

工作流程

/write_plugin <需求>
│
├── 权限检查 + busy 检查 + 冷却检查
│
├── 创建后台异步任务 ← 命令立即返回
│
└── 后台任务:
    ├── 解析需求 + 读取参考插件
    ├── 构建 LLM Prompt
    ├── 调用 LLM 生成
    ├── 解析响应 → 提取 3 文件
    ├── 6 层安全验证
    │   ├── 通过 → 暂存 + 水印 + 预览通知
    │   └── 失败 → 错误反馈 → 重试(max 2次)
    └── 释放 busy 锁

用户:
    /view_plugin <ID>     → 完整代码
    /analyze_plugin <ID>  → 功能分析
    /confirm_plugin <ID>  → 安装
    /modify_plugin <ID>   → 修改
    /fix_plugin <ID>      → 修复
    /reject_plugin <ID>   → 放弃

暂存超时: 1 小时自动清理

文件结构

plugins/self_writing_plugin/
├── _manifest.json              # 插件清单
├── config.toml                 # 配置文件
├── plugin.py                   # 主类：11 个 Command + 1 个 EventHandler
├── README.md                   # 本文档
└── generators/                 # 核心逻辑
    ├── __init__.py
    ├── prompt_builder.py       # Prompt 构建（SDK 文档 + 输出规则）
    ├── code_parser.py          # LLM 响应解析
    ├── validator.py            # 6 层安全验证器
    ├── llm_client.py           # 统一 LLM 客户端
    └── plugins_scanner.py      # 插件目录扫描

🔧 生成插件管理

本插件生成的插件安装在 plugins/generated/<插件ID>/ 目录中。生成插件是独立的、不依赖本插件运行。

生成插件的目录结构

plugins/generated/
└── <插件ID>/
    ├── _manifest.json      # 插件清单（含许可证、能力声明）
    ├── plugin.py           # 插件主代码（含水印标记）
    ├── config.toml         # 插件配置（需手动编辑启用）
    └── _meta.json          # 生成元信息（仅暂存时有）

启用生成插件

生成插件安装后默认处于禁用状态（config.toml 中 enabled = false），需要手动启用：

进入 plugins/generated/<插件ID>/
编辑 config.toml：
```
[plugin]
enabled = true
```
在 MaiBot WebUI 中重载插件，或重启 MaiBot

安全提示：首次启用生成插件时，建议先在私聊或测试群中观察行为，确认正常后再开放到公共群。

禁用生成插件

编辑 plugins/generated/<插件ID>/config.toml，将 enabled 设为 false
在 MaiBot WebUI 中重载插件
或直接在 WebUI 中将插件状态设为"禁用"

删除/卸载生成插件

# 删除单个生成插件
rm -rf plugins/generated/<插件ID>/

# 删除所有生成插件（谨慎操作）
rm -rf plugins/generated/

删除后 MaiBot 会检测到插件目录不存在并自动卸载。无需手动触发重载。

修改生成插件

有两种方式修改生成插件：

方式	适用场景	操作
AI 修改	功能级修改、不熟悉代码	使用 `/modify_plugin <ID> <需求>` 让 AI 重新生成修改后的版本
手动修改	微调、修 bug、懂 Python	直接编辑 `plugins/generated/<ID>/plugin.py`，编辑后重载插件

AI 修改流程：

/modify_plugin <ID> <修改需求>
    → 读取原插件代码
    → LLM 生成修改后的代码
    → 安全验证
    → 暂存（覆盖原暂存）
    → /confirm_plugin <ID> 安装（覆盖原安装目录）

手动修改注意事项：

修改后确保 _manifest.json 的 capabilities 与代码中实际使用的 ctx 能力一致
修改后重载插件才能生效
如果改坏了，使用 /modify_plugin 让 AI 重新生成

修复生成插件

如果生成插件出现运行时错误：

/fix_plugin <ID> <完整错误日志>

错误日志包含 Python traceback 时修复效果最佳
复制完整报错信息（包括 File、line、Error 类型），不要截断
修复完成后会暂存新版本，需要 /confirm_plugin 确认覆盖

分析生成插件

/analyze_plugin <ID>           ← 分析功能和原理
/analyze_plugin <ID> --check   ← 附带安全排查

分析报告会说明插件使用了哪些 SDK 组件、如何响应事件、配置结构
安全排查会检查：危险导入、动态执行、网络请求、文件操作、能力声明匹配度

生成插件与已有插件的冲突

如果生成插件的 ID 与已有插件相同，/confirm_plugin 会拒绝覆盖并提示手动删除
建议在生成时使用独特的描述，让 LLM 创建不重复的插件 ID
插件 ID 格式：author.plugin-name（小写字母、数字、点号、连字符构成）

生成插件的数据备份

# 备份所有生成插件
tar -czf generated_plugins_backup_$(date +%Y%m%d_%H%M%S).tar.gz plugins/generated/

# 备份单个生成插件
cp -r plugins/generated/<插件ID>/ /backup/location/

故障排查

问题	可能原因	解决方法
所有命令被拒绝，提示"访问令牌未设置"	`access_token` 为空	阅读 README 安全警告和免责声明后，在 `config.toml` 中设置 `access_token`
`access_token` 设置后仍被拒绝	热重载清空了 token / 包含不可见字符	重新编辑 `config.toml`，确保 `access_token = "I_ACCEPT"` 不含多余空格
升级后 `access_token` 丢失	新版 `PluginSectionConfig` 新增字段	升级后手动添加 `access_token = "I_ACCEPT"` 到 `config.toml`
生成总是失败	模型能力不足	启用 `[custom_api]` 切换更强模型
LLM 调用超时	响应慢 / 平台 30s 限制	简化需求描述，或切换到更快的模型
`/confirm_plugin` 显示未找到	插件热重载后未恢复 / 暂存已过期	等待几秒后重试；暂存超时需重新 `/write_plugin`
`/confirm_plugin` 显示"目标目录已存在"	同名插件 ID 已安装	删除 `plugins/generated/<ID>/` 后重试，或修改需求重新生成不同 ID 的插件
生成插件无法加载	manifest 缺字段 / 代码语法错误	`/view_plugin` 查看完整代码后检查，或 `/fix_plugin <ID> <错误日志>`
生成插件加载后 MaiBot 崩溃	生成代码有严重 bug	立即删除 `plugins/generated/<ID>/` 目录，重启 MaiBot
操作员被忙碌拦截	EventHandler 锁定	使用 `/abort` 或 `/list_staged`
暂存区有文件但 `/list_staged` 空	元数据丢失	检查 `staging/<ID>/_meta.json` 是否存在
自定义 API 报错	URL/Key 配置错误	检查 `api_url` 格式和 `api_key`；测试 curl
白名单用户仍被拒绝	`allowed_users` 格式错误	用户 ID 用半角逗号分隔，不含空格，如 `"123456,789012"`
生成插件的 EventHandler 不触发	`is_command` 检查逻辑问题	查看其他 EventHandler 插件的实现，或用 `--from` 指定参考
MaiBot 重启后暂存数据丢失	暂存数据未持久化成功	检查 `staging/` 目录权限；确认 `_meta.json` 存在

版本历史

版本	日期	变更
0.2.1	2026-06	新增 `access_token` 强制确认机制（拒绝消息直接发送至使用者）；所有长文本输出改为转发消息；SDK 参考文档全面重写（补充 10+ ctx 接口、4 种编码模式、后台任务模板、完整生命周期示例）；输出格式规范扩展（12→22 条规则，补充 EventHandler/Config/Manifest 规范）；复杂度验证上限提升以支持中等复杂度插件；安全警告从 9 条扩展至 18 条（新增第 10 条访问令牌安全局限性、第 11-18 条覆盖硬编码凭据风险、多插件交互、日志泄露、卸载残留、配置篡改、联网不可控、环境兼容性、WebUI 管理安全）；免责声明从 9 条扩展至 16 条（新增第 11-16 条覆盖数据训练隐私、可分割性、管辖法律、供应链风险、服务连续性、不可抗力）；新增安装/卸载/升级/回滚完整说明；新增生成插件管理章节；补充环境要求、热重载行为、多用户场景、合规记录说明；扩展故障排查条目（7→15 条）
0.2.0	2026-05	新增 `/modify_plugin`、`/fix_plugin`、`/analyze_plugin`、`/view_plugin`、`/write_help`；安全加固（busy 泄漏修复、白名单补全、禁止导入 9 模块、双层超时）；转发消息预览+磁盘持久化；分级使用建议
0.1.0	2026-05	初始原型：异步生成、6 层安全验证、操作员白名单、自定义 API、冷却防滥用、自动修复重试、路径穿越防护

许可证

本插件采用 GPL v3.0 或更高版本许可证。生成插件的许可由您在生成时指定（在 manifest license 字段中）。

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
generators		generators
README.md		README.md
_manifest.json		_manifest.json
config.toml		config.toml
plugin.py		plugin.py

Folders and files

Latest commit

History

Repository files navigation

插件自生成器(测试版) (Self-Writing Plugin) v0.2.1

📦 安装方式

手动安装至目录

步骤 1：复制插件文件

步骤 2：检查目录权限

步骤 3：验证安装

🔄 升级/更新

升级前备份（必须）

升级步骤

回滚步骤

🗑 卸载方式

完全卸载步骤

💻 环境要求

⚠️ 重要：安全警告与免责声明

🛡️ 安全警告

🔴 代码信任与审查

🟠 运行时与系统风险

🟡 配置与密钥安全

📜 免责声明

🔑 访问令牌 (Access Token) — 强制确认机制

为什么需要访问令牌

如何设置访问令牌

技术细节

法律声明

📚 分级使用建议

🟢 等级一：完全不懂编程的小白用户

✅ 适合您的操作

⚠️ 需要别人帮助的操作

📋 小白用户安全清单

🟡 等级二：懂一些编程但不太熟悉 MaiBot 的用户

✅ 适合您的操作

📋 中等用户安全清单

🔵 等级三：编程能力强的用户

✅ 适合您的操作

📋 高级用户建议

快速开始

0. 设置访问令牌（必须）

1. 启用插件

2. 查看可用参考插件

3. 查看帮助

4. 生成插件

5. 审查代码

6. 确认安装

7. 手动启用生成的插件

命令参考

生成与安装

修改与修复

管理

命令说明

完整配置项

配置文件位置

[plugin] — 插件基础设置

[generation] — 生成参数

[safety] — 安全设置

[custom_api] — 自定义 API（可选）

[operator_whitelist] — 操作员白名单

安全验证机制详解

第 1 层：AST 安全分析

第 2 层：Capability 白名单

第 3 层：代码复杂度限制

第 4 层：正则模式扫描

第 5 层：依赖限制

第 6 层：审计水印与溯源

修复重试机制

工作流程

文件结构

🔧 生成插件管理

生成插件的目录结构

启用生成插件

禁用生成插件

删除/卸载生成插件

修改生成插件

修复生成插件

分析生成插件

生成插件与已有插件的冲突

生成插件的数据备份

`[plugin]` — 插件基础设置

`[generation]` — 生成参数

`[safety]` — 安全设置

`[custom_api]` — 自定义 API（可选）

`[operator_whitelist]` — 操作员白名单

Packages