内置插件
AniaBot 自带六个插件，在 cmd/main.go 中注册。它们既是开箱即用的功能，也是插件开发的最佳参考实现。
bot.AddPlugin(pluginsys.NewPluginSys()) // 系统插件
bot.AddPlugin(pluginlog.NewPlugin()) // 日志插件
bot.AddPlugin(pluginrepeat.NewPlugin()) // 复读机
bot.AddPlugin(plugininterceptor.NewPlugin()) // 请求拦截
bot.AddPlugin(pluginaichat.NewAIChatPlugin()) // AI 对话
bot.AddPlugin(pluginnews.NewNewsPlugin()) // 每日新闻命令中的 @ 约定
群聊中标注「需 @」的命令，都需要 @机器人 后再发命令才会触发（如 @机器人 /news）；私聊中直接发送即可。
系统插件
pluginsys · Order = -1000（最先执行）· 群聊 + 私聊
框架的「管家」，负责帮助信息、远程控制与故障告警。
| 命令 | 场景 | 说明 |
|---|---|---|
/help | 私聊 | 列出已加载插件及帮助说明（按 ShowFor 过滤） |
@机器人 /help | 群聊 | 群聊版帮助 |
/exit | 私聊 | 仅管理员，远程停止机器人进程 |
其他行为：
- 启动通知：Bot 启动完成后自动私聊管理员「AniaBot启动成功」
- panic 告警：任何插件运行时 panic，系统插件会私聊通知管理员（1 分钟内防抖，避免刷屏）
AI 对话插件
pluginaichat · Order = 1000（最后执行，兜底响应）· 群聊 + 私聊
AniaBot 的核心插件，支持三种 LLM API 格式：OpenAI 兼容（Chat Completions，如 DeepSeek）、OpenAI Responses API 与 Anthropic Messages API（Claude），经 plugin.ai_chat_bot.api_format 切换。
对话方式
| 操作 | 效果 |
|---|---|
| 群聊中 @机器人 + 内容 | 发起/继续对话 |
| 私聊直接发送内容 | 发起/继续对话 |
消息中带 #新对话 | 清空当前会话历史，开始新对话 |
/stop | 立即停止正在进行的 AI 响应 |
其他细节：
- 每个群 / 每个好友拥有独立会话，互不影响
- 对话历史持久化保存，重启后继续聊；超过 token 预算 80% 时自动压缩。历史按消息行级存储（
ania_chat_session+ania_chat_message两表），新消息增量落盘 - 闲置会话会被自动回收（默认闲置 120 分钟或驻留超过 128 个会话时淘汰最久未活动的，均可在配置中调整或关闭）；淘汰只释放内存，历史已持久化，下次发言自动重建继续聊
- 群内连续 30 条消息无人 @ 机器人时，自动清理该群对话缓存
- 同一时刻同一会话只允许一个进行中的请求；响应期间到达的消息会进入排队队列（每会话上限 20 条），当前响应结束后自动合并为一轮请求逐条回应，
/stop会同时清空队列
内置工具
AI 可在对话中自主调用：
| 工具 | 说明 |
|---|---|
time | 获取当前时间 |
webSearch / webExplore | 联网搜索 / 抓取网页（需配置 Jina token） |
get_msg_history | 读取群/私聊最近消息 |
load_images | 加载用户消息中的图片（多模态或 OCR 识别） |
get_private_file_url / file | 私聊文件链接获取与发送生成的文件（file 需配置开启） |
bash | 执行宿主机命令（默认关闭，黑白名单 + 审批三段式权限） |
local_image | 读取宿主机本地图片（默认关闭） |
screenshot / mouse_click / mousemove / mouse_scroll / keyboard_type / keyboard_press / active_window / list_windows | 电脑操作：截图查看宿主机屏幕并控制鼠标键盘（默认关闭，仅 Windows 宿主机；可配合工具审批逐次确认） |
todo_write | 维护当前会话的任务清单，复杂多步任务逐项推进 |
此外还有 MCP 发现/加载工具与 skill_read，见 配置详解。
AI 定时任务（clock）
让 AI 拥有「闹钟」。用户和 AI 都能创建 cron 任务，到点后以一个全新的一次性会话执行任务内容（可调用全部工具），执行结果发送到目标群/好友。
用户命令（群聊里需先 @ 机器人）：
/clock 查看当前会话的定时任务
/clock list [all] 列出任务（all 仅管理员）
/clock add [--once] <cron> | <标题> | <内容> 新增任务（--once 为单次任务）
/clock del <id> 删除任务
/clock on <id> / /clock off <id> 启用 / 停用
/clock info <id> 任务详情与最近执行记录
/clock timeout <id> <秒数> 设置单次执行超时（0 恢复默认）
/clock run <id> 立即执行一次（仅管理员）
/clock log [n] 最近 n 条执行记录（默认 10）示例：
/clock add 0 8 * * * | 早安播报 | 告诉大家早上好，并播报今日日期也可以直接对 AI 说：「每天早上 8 点提醒大家喝水」，它会通过 clock_create 工具自己建好任务。
任务触发时 AI 还可以调用 skip_output 工具跳过本轮输出：巡检、监控这类任务在确认没有需要汇报的内容时保持安静——本次执行的最终回复不发送给目标，只留在执行日志里（面板「定时任务 → 执行日志」与 /clock log 会标注「已跳过输出」并附 AI 说明的原因）。
主动互动（proactive）
让 AI 拥有「说话的时机感」。与定时任务「到点必发」不同，主动互动只是一条意图：到点后还要看现场气氛，再决定说不说、说什么。
默认关闭，且需要按会话启用（面板「AI 对话 · 主动互动」的白名单，或管理员在会话内发送 /proactive on——两者是同一份名单，指令会直接改写配置，面板刷新即可看到）。
用户/管理员命令（群聊里需先 @ 机器人，与 /stop、/plan 一致）：
/proactive 查看本会话状态（今日已发言次数、待执行意图）
/proactive on / off 开启 / 关闭本会话（直接改写面板里的白名单，管理员）
/proactive reload 从配置中心重新读取白名单，面板改完不必重启（管理员）
/proactive now [想说的话] 立即触发一次，用于调试（管理员）
/proactive list 列出所有启用主动互动的会话（管理员）
/proactive log [n] 查看本会话最近的主动发言记录（管理员）意图从哪来：
- 冷场：会话安静超过设定时长（默认 90 分钟）后，生成一条「要不要说点什么」的意图
- AI 自建：对话中 AI 觉得「过一会儿值得再说一句」（问题还没人答、约好稍后跟进）时，用
proactive_create预约一条意图；也可以在对话里直接对它说「十分钟后再问问我进展」 - 意图有独立的到点时间与有效期（默认 30 分钟），过期作废，不会翻出已经冷掉的话题
到点后仍要过闸门：
- 免打扰时段（默认
23:00-08:00，支持跨午夜）内顺延到时段结束，撑不过有效期就作废 - 单会话 / 全局每日发言上限、两次发言最小间隔、刚发过言后的静默期
- 现场复核：正在聊天就推迟；冷场意图排队期间有人说话了，这条意图直接作废
- 最后由 AI 自己判断——确实没什么可说就调用
skip_output保持安静
反馈环：每次主动发言后观察一段时间（默认 10 分钟），有人接话记为「有回应」，没人理记为「无人理」；连续多次无人理会自动进入冷却（默认 6 小时），让它在冷场里更谨慎。
主动发言会像普通回复一样写回该会话的对话历史（跨重启保留）：之后有人接话时，AI 知道自己上一句说了什么；下次主动开口前还会以只读方式回放最近的对话（这次生成的触发提示词与思考不会写进历史），既能接着之前的话题说，也会参考最近几次自己说过的话避免重复。
每次执行的生成过程都会写入面板「Query 日志」（来源标记为「主动互动」）：触发来源与现场、工具调用、token 消耗，以及最终发出的内容；AI 判断不该说话时状态显示为「保持安静」并附原因。Token 统计里也会单列「主动互动」一项。闸门直接拒绝的意图（免打扰、上限、间隔、冷却、现场已活跃）没有 AI 调用，仍只能在 /proactive log 与意图记录里看到。
配置见 配置详解。
AI 长期记忆（memory）
让 AI 拥有「记性」。AI 通过 memory_save / memory_search / memory_update / memory_forget 四个工具自行管理长期记忆：得知用户的称呼、偏好、重要信息，或群里形成约定时主动保存；对话涉及过去的事情时先检索回忆；发现记忆有误、过时或重复时主动更正合并（换成另一种说法的近似重复，保存时也会收到合并提示）；用户明确要求忘记时才删除。
- 记忆跨会话、跨重启保留，持久化保存（存于
ania_memory表，每行一条） - 记忆按群聊 / 好友隔离（
g:群号/f:QQ号），群与群、群与私聊之间互不可见 - 每个会话记忆条数上限默认 200 条，写满后 AI 需先清理或合并旧记忆
- 相同内容自动去重，不会重复写入
无需用户命令，直接对 AI 说「记住我喜欢喝美式」「我之前说过什么？」即可触发。配置见 配置详解。
AI 子代理（subagent）
让 AI 拥有「分身」。AI 通过 subagent_run 工具把复杂/耗时的子任务（如深度调研、多轮搜索后总结）委派给一次性子代理执行，子代理跑完后只把最终结果带回给主对话：
- 子代理以全新一次性上下文运行（看不到当前对话历史），不持久化、执行完即丢弃，中间过程不占用主对话上下文
- 子代理拥有与主 AI 一致的工具能力（搜索、网页浏览、消息历史、MCP 等；定时任务/长期记忆需对应功能开启），但不能再委派子代理（防止递归）
- 子代理执行过程中的中间消息不会发给用户，发送图片/文件等能力仍作用于当前会话；用户消息中的图片需由主 AI 加载（子代理的图片状态与主会话隔离）
- 执行参数全部跟随主模型：模型与 API 格式、生成参数、工具轮数取「AI 对话 · 模型」配置，超时取框架级「消息处理超时」（默认 5 分钟，单次调用可指定、上限 1800 秒；实际还会按主请求剩余预算自动收缩，预留收尾时间），超时后子代理中止、主 AI 继续回复；返回结果完整回填、不截断
功能默认启用，无需用户命令，直接对 AI 说「帮我深入调研一下 XXX 再总结」这类复杂任务即可触发。说明见 配置详解。
AI 知识库（knowledge）
让 AI 拥有「资料库」。AI 通过 kb_add / kb_search 工具把完整资料（教程、文章、URL 正文）存入知识库，并在对话中按需检索引用：
- 知识库按会话隔离（群聊
g:群号/ 私聊f:用户ID），另有一份全局库（global），所有会话都可检索、仅 Web 面板可管理 - 文档按行级存储（存于
ania_kb_doc表，每篇一行），增删改即写即生效，旧版数据升级后自动迁移 - 长文档自动按 600 字符一块、60 字符重叠切片，检索命中块而非整篇，避免无关内容占用上下文
- 默认每次对话前自动按关键词检索相关文档注入上下文（
kb.auto_inject）；启用向量检索（kb.embedding.enable）后入库计算语义向量，检索与关键词混合打分，检索更准 - 每个作用域文档上限默认 500 篇，标题+内容相同自动去重
无需用户命令，对 AI 说「把这篇教程存进知识库」或问知识库里的内容即可触发。配置见 配置详解。
Agent 团队（team）
让 AI 拥有「团队」。AI 通过 team_run 组建临时团队，把子任务拆给多个带角色描述的成员代理并行执行，再汇总各成员结果给出最终回答；团队定义可保存复用（team_create / team_list / team_delete），Web 面板提供「Agent 团队」管理页：
- 每个成员复用子代理执行路径：全新一次性上下文、执行完即丢弃；模型与执行参数跟随主模型
- 单次最多并行 5 个成员，成员结果完整汇总、不截断
- 成员不能再组建团队（防止递归）
功能默认启用，对 AI 说「组建一个调研团队，分别负责技术、市场、竞品分析，最后汇总报告」即可触发。说明见 配置详解。
每日 Token 配额（quota）
在 Web 面板「配额管理」页可查看每个会话与全局的 AI token 用量；启用配额后可按「每会话每日」与「全局每日」两个维度限制消耗，超限后 AI 请求被拒绝（含子代理、定时任务消耗），未设置上限时仍记录用量。配置见 配置详解。
Query 日志（query_log）
Web 面板「Query 日志」页记录每次 AI 回复的完整执行过程：触发会话、发送者、用户输入、LLM 轮数、工具调用明细（名称/参数/结果/耗时）、token 用量与最终回复，状态区分执行中 / 成功 / 保持安静（主动互动判断无需发言）/ 已停止 / 超时 / 出错，可条件筛选，也可按来源只看「对话」或「主动互动」。执行中的记录实时显示已用时，工具调用逐条落盘、随面板轮询即时可见，无需等待执行完成。配置见 配置详解。
计划模式（/plan）
让 AI「先出方案，再动手」。群聊中 @机器人 发送 /plan on（私聊直接发送）开启计划模式：AI 只做分析与规划并输出实施计划，修改文件、运行命令、改配置、建任务等副作用操作会被系统自动阻止；确认计划无误后发送 /plan off 退出，AI 即可正常执行。/plan 无参数可查看当前状态。计划模式按会话隔离，是会话内的临时状态。
工具审批（approval）与 bash 三段式权限
默认关闭。开启后，approval.tools 列出的工具（默认 file）每次执行前都会向会话发送一条确认消息，消息发送者或机器人管理员在超时时间（默认 120 秒）内回复「允许」或「拒绝」决定放行与否，超时自动拒绝；子代理 / 定时任务发起的审批仅管理员可批。审批期间正常聊天不受影响。
配置修改类工具（config_set / config_file_set）恒需管理员审批：无论审批开关是否开启，执行前审批提示都会直接私聊发给机器人管理员，管理员在私聊中回复「允许/拒绝」才写入（发起会话会收到一条「已通知管理员」提示；管理员在发起会话中回复同样有效；私聊发送失败时提示回退到发起会话）。请求发送者本人不能批准，无权者的审批回复会被拦截并提示，超时自动拒绝。
bash 工具使用独立的命令级三段式权限（无需列入 approval.tools）：
- 命中黑名单正则 → 直接拒绝；
- 命中白名单正则 → 直接放行；
- 两者都不命中（包括两份名单都为空）→ 发起上述人工审批，批准后执行；审批未启用时默认放行（只认黑名单）。
AI 钩子（hooks）
默认关闭。管理员在面板「扩展配置」页的 files.hooks_json 中配置 shell 命令，挂在会话事件上执行：SessionStart（会话创建）、UserPromptSubmit（用户消息进入，可阻断/注入上下文）、PreToolUse（工具执行前，可按工具名正则匹配、可阻断）、PostToolUse、Stop（回复完成）、SubagentStop、PreCompact（上下文压缩前）。钩子从 stdin 接收 JSON 载荷；退出码 0 表示通过（stdout 内容注入 AI 上下文）、2 表示阻断（stderr 为原因）、其他退出码仅记日志。保存后数秒内热生效。插件开发者还可实现 Go 钩子接口（agenthook.Handler）以代码方式介入同一事件流，见 AI 引擎（三）。
自定义斜杠命令（/cmd）
把常用提示词固化为斜杠命令。管理员发送 /cmd add translate 把以下内容翻译成英文：$args 后，任何人发送 /translate 你好 即等同于向 AI 发送「把以下内容翻译成英文：你好」（$args 为参数占位符；无占位符时参数追加到模板末尾）。/cmd 列出全部自定义命令，/cmd del <名> 删除（增删仅管理员）。命令名不得与内置命令（clock/stop/plan/cmd/help 等）撞名。自定义命令存于面板「扩展配置」页的 files.commands_json，多行模板可直接在面板编辑 JSON，保存后数秒内热生效。
请求拦截插件
plugininterceptor · Order = 900（普通插件之后、AI 对话插件之前）· 群聊 + 私聊
按白名单 / 黑名单模式放行或屏蔽指定群聊、好友的消息：被拦截的消息不再向后续插件传播（AI 对话插件收不到，也就不会产生 AI 请求），而排在其前面的复读机等插件不受影响。
无内置命令，名单在 Web 控制面板配置；如需用 /wl 命令即时增删查名单，可在面板「插件市场」安装「白名单管理」插件（whitelist，与内置请求拦截共用同一份名单）：
| 配置 | 说明 |
|---|---|
| 启用请求拦截 | 默认关闭，关闭时放行全部消息 |
| 名单模式 | blacklist：名单内的群/好友被屏蔽；whitelist：仅名单内的群/好友放行 |
| 可用平台 | 多选，默认全选。仅勾选平台的消息进入名单判定，未勾选的平台直接拦截（不触发 AI）；想单独屏蔽某平台时取消勾选它 |
| 群 ID 名单 | 每行一个群 ID（QQ 为 qq:群号，其他平台为带前缀的群 ID，如 fs:oc_xxx） |
| 用户 ID 名单 | 每行一个用户 ID（QQ 为 qq:QQ号，其他平台带前缀），对私聊及群聊消息发送者均生效 |
白名单模式注意
whitelist 模式下，放行的群对全体成员开放（群内屏蔽成员规则除外），无需把成员逐个加进用户 ID 名单；此时用户 ID 名单只作用于私聊。名单留空表示拦截所有会话——任何群和私聊都无法触发 AI 回复。
复读机插件
pluginrepeat · 群聊
群内同一条消息连续出现（默认 3 次，可配置）时，机器人自动跟读一次（之后需消息变化才会再次跟读）。
| 命令 | 说明 |
|---|---|
@机器人 /close repeat | 仅管理员，关闭复读（同步写回配置，重启后保持） |
@机器人 /enable repeat | 仅管理员，开启复读（同步写回配置，重启后保持） |
控制面板可配置是否启用（默认开启）与触发条数（默认 3，至少 2），详见 配置详解 · repeat。
每日新闻插件
pluginnews · 群聊
按 cron 表达式定时向配置的群推送 60s 读懂世界 新闻图。
| 命令 | 说明 |
|---|---|
@机器人 /news | 立即获取一张新闻图 |
/news force | 仅管理员（私聊），立即向所有配置群执行一次推送 |
配置见 配置详解 · dailyNews。
日志插件
pluginlog · Order = -1000 · 群聊 + 私聊
在控制台打印每一条收发的消息内容，无命令、无配置，调试期建议保留，生产环境可从 cmd/main.go 移除。