麦麦失忆插件

用于清理 MaiBot 的聊天上下文和记忆数据。本文档面向 MaiBot 新版插件运行环境，说明旧版 context_clear_plugin 迁移到 SDK 2.x 时需要保留的能力、配置方式和安全边界。

适用范围

• 插件应放置在 MaiBot 根目录的 plugins/context_clear_plugin 下。
• 新版插件不应再依赖旧插件系统的 src.plugin_system、BasePlugin、BaseCommand、register_plugin。
• 新版插件应通过 SDK 2.x 暴露的 Command、EventHandler、send、database、message 等能力与 Host 交互。
• 插件不应直接修改 MaiBot 主程序代码；如果确实需要主程序能力变更，应先在主仓库中单独评估。

命令

命令	参数	说明
/失忆 全部	无	清理当前聊天流的全部消息记录。
/失忆 最近 [数量]	数量可选，默认 10	清理当前聊天流最近 N 条消息。
/失忆 之前 [小时]	小时可选，默认 24	清理当前聊天流指定小时数以前的消息。
/失忆 完全	需要二次确认	清理全局记忆数据，默认关闭。
/失忆 帮助	无	查看命令说明。

可保留的命令别名：

• /忘记
• /断片
• /amnesia
• /forget
• /clear
• /清除上下文
• /清空上下文

配置

权限配置建议放在插件自己的 config.toml 中：

[plugin]
enabled = true
permission = ["1334431750", "123456789"]

permission 用于限制可执行失忆命令的用户 ID。未配置权限时，建议拒绝执行清理命令，避免插件被任意用户触发。

完全失忆应使用独立安全开关，默认关闭：

[safety]
allow_total_amnesia = false
confirm_timeout_seconds = 30

完全失忆安全边界

/失忆 完全 属于高风险操作，应满足以下约束：

• 默认关闭，必须显式配置 allow_total_amnesia = true 后才允许执行。
• 必须二次确认，确认请求应限制在同一聊天流、同一用户和超时时间内。
• 建议支持 /失忆 完全 确认 和直接回复 确认 两种确认方式。
• 清理范围应优先使用 SDK/Host 提供的数据库能力，不应直接操作主程序内部对象。
• 不应删除本地文件、配置文件、统计数据或主程序资源，除非另有明确需求和单独确认。

推荐的全局记忆清理范围包括：

• Messages
• ChatSession
• PersonInfo
• Expression
• ChatHistory
• Jargon
• ToolRecord

迁移要点

旧版插件通常存在以下不兼容点：

• 旧版直接导入主程序内部模块，在新版 Runner 插件隔离环境中可能无法加载。
• 旧版命令类基于旧插件系统注册，新版应改为 SDK 2.x 的组件声明方式。
• 旧版数据库访问可能直接调用 ORM 模型，新版应优先使用 Host 暴露的数据库能力。
• 旧版完全失忆逻辑可能会清理本地文件或修改运行时存储，新版应收窄到明确的数据模型范围。

迁移时建议先完成文档、配置模型和权限边界确认，再实现清理逻辑。这样可以避免将危险删除能力以默认开启的方式带入新版运行环境。

使用示例

/失忆 全部
/失忆 最近 20
/失忆 之前 48
/失忆 完全
/失忆 完全 确认
确认

注意事项

• 清理操作不可逆，执行前应确认目标聊天流和清理范围。
• /失忆 最近 和 /失忆 之前 只应影响当前聊天流。
• /失忆 完全 会影响全局记忆数据，不应作为普通维护命令使用。
• 插件适配新版时不要修改根目录 .gitignore，插件应作为 plugins 下的独立仓库维护。

版本历史

v2.0.0 (2026-06-22)

• ✨ 重大版本：SDK 2.x 完整迁移
  • 🔄 迁移核心依赖：BasePlugin/BaseCommand → MaiBotPlugin SDK
  • 📋 新增 Pydantic 配置模型，支持 WebUI 热重载和类型检查
  • 🔒 安全策略升级：完全失忆默认关闭（allow_total_amnesia = false）
  • ⏱️ 增加二次确认超时和清理范围限制配置
  • 📊 _manifest.json 升级到 v2，新增 SDK 版本要求和能力声明
  • 📝 文档改为 SDK 2.x 迁移指南，明确安全边界和责任分工
• 🛑 破坏性变更：需要 MaiBot 1.0.0+ 和 SDK 2.0.0+

v1.5.0 (2025-11-22)

• ✨ 状态机确认机制
  • 🔐 双确认方式：命令确认 + 直接回复确认
  • ⏰ 30秒确认超时机制
  • 🛡️ 聊天上下文验证，防止跨聊天确认
• ✨ EventHandler 监听器
  • 📢 高优先级拦截"确认"消息
  • ⚡ 防止后续处理干扰
• 🔧 修复：延迟删除机制改进
  • ✅ 修复最近/之前模式只删除回复消息的问题
  • 🕐 延迟 3 秒清理，确保消息完全移除

v1.4.0 (2025-11-20)

• ✨ 新增长期记忆和学习数据的清除
• ➕ 支持清除 ChatHistory、ThinkingBack、Jargon 表

v1.3.0 (2025-11-19)

• 🔧 修复插件无法加载的错误（移除不存在的数据库模型引用）

v1.2.2 (2025-11-19)

• 🔧 彻底解决命令消息残留问题（两阶段删除策略）

v1.2.0 - v1.1.0 (2025-11-18)

• 初期完全失忆功能实现和优化

v1.0.0 (2025-11-17)

• 🎉 首次发布（改造自 context_clear_plugin）