跳转至

AI 对话插件指南

内置 ai 插件(builtin/ai/)提供多提供商(OpenAI / Anthropic)的 AI 对话、工具调用与自定义技能管理。

触发方式

  • @机器人 后直接发消息(at_bot: true,默认)
  • 私聊(private_chat: true)
  • 群聊自主发言:不 @ 机器人也响应群内非命令消息(group_autonomous: true)
  • 无命令匹配兜底:群聊与私聊的全部非命令消息都由 AI 应答(fallback: true, 即 group_autonomous + private_chat 的并集;命令消息仍归其他插件)
  • 消息前缀触发:trigger_cmd(默认 /ai)

命令

命令 说明
/ai <消息> 与 AI 对话(支持工具调用与图片)
/ai reset 清空当前会话对话历史
/ai undo 撤销上一条对话
/ai retry 重新生成上一条回复
/ai stop 停止当前正在生成的回复(@机器人 说"停止"亦可)
/ai summary 后台生成对话总结
/ai status 查看会话状态(提供商/模型/消息数/时长)
/ai stats 查看使用统计(LLM 调用次数、工具调用次数)
/ai tools 列出当前可用工具
/ai memory 查看长期记忆;remove <序号\|文本> 删除单条/按内容删,clear [user\|group] 清空(clear group 需群管理员)
/ai todo 管理会话待办清单(list / add / done / remove / clear)
/ai plan 查看/取消当前任务计划(status / cancel)
/ai skill ... 自定义技能管理(见下)

关于 QQ"重新生成 / 清空会话 / 停止生成"按钮:QQ v2 公开文档只提供挂在 markdown 消息上的 keyboard 按钮(见官方《消息按钮》),action_button(含 "重新生成/停止生成"模板)无公开文档:真机冒烟确认模板 "1" 只渲染"赞/踩" 反馈行、模板 "10" 直接被服务端拒绝(HTTP 400)。操作按钮使用官方 keyboard 指令按钮(action.type=2,与 about 插件"查看命令列表"同方案):QQ 单聊 与群聊(频道除外)的 Markdown 回复底部显示"重新生成"与"清空会话",点击后 客户端把命令填入输入框(群聊自动补 @bot 前缀,见官方 action.type=2 说明) ——单聊手机端(客户端 8983+,Enter=true 仅单聊生效)自动发送,桌面端与 群聊需手动按回车发送;"清空会话"不自动发送(破坏性动作,避免误触)。 不用回调按钮(type=1)的原因:QQ webhook 下互动事件投递有秒级延迟(真机 实测约 2s),即使服务端 成功回应,客户端仍显示"请求第三方失败"(2026-09 真机验证,与 about 现象 一致);指令按钮不产生互动回调,命令走常规文本消息管线,可靠且可被新消息 抢占。连点/重复触发受会话级冷却与忙时节流提示保护。QQ 客户端自带的"清空 会话"入口(官方原生互动 type=14,CLEAR_SESSION)也会同步清空本插件会话。 纯文本回复、富媒体回复、频道消息不附加按钮,请使用 /ai retry、/ai reset 命令。

复杂任务触发计划(create_plan)时推送的"计划已创建"消息、以及 /ai plan 状态回复同样会附加指令按钮:"查看计划"(/ai plan,单聊手机端自动发送, 长任务执行期间一键刷新进度)与"停止生成"(/ai stop,不自动发送,仅在 回合进行中时附带)。停止生成会一并取消进行中的任务计划——半途中断后若不 取消,剩余步骤仍会在后续回合/后台自动推进(/ai stop 与 /ai plan cancel 语义一致)。按钮出现在 QQ 单聊与群聊(频道除外)的 Markdown 消息上(受 qq_plan_button 开关控制)。

QQ 的原生"停止生成"按钮只在流式消息渲染期间可用,本插件以整条发送为主, 因此未接入该按钮;停止统一走 /ai stop(文本命令或计划消息上的"停止生成" 指令按钮,中断进行中的 LLM 流,已生成部分会保留),全平台可用;用户直接 发送新消息同样会抢占并中断上一轮生成。

配置(plugins.ai)

plugins:
  ai:
    provider: "openai"            # openai(默认)| anthropic
    model: ""                     # 模型名(空 = 提供商默认)
    base_url: ""                  # 兼容端点(OpenAI 兼容 API 可指向代理/中转)
    api_key: ""
    max_tokens: 0                 # 单次回复最大 token(默认 4096;思考型模型的推理也计入该预算)
    max_tokens_cap: 0             # 截断重试的输出预算上限(默认 8192;<= max_tokens 时关闭重试)
    reasoning_effort: ""          # 思考程度(none/minimal/low/medium/high;空 = 不发送该字段)
    max_depth: 0                  # 工具调用最大轮数
    max_history: 0                # 保留的历史消息数
    api_timeout: ""               # LLM API 超时
    tool_timeout: ""              # 工具执行超时
    session_ttl: ""               # 会话在内存缓存中的闲置存活时长(只影响缓存,库里的历史仍保留)
    session_retention: ""         # 持久化历史保留时长(默认 720h = 30 天;0s = 不限,只有 /ai reset 删行)
    session_cache_size: 0         # 内存驻留会话上限(LRU,默认 1000;大群可下调到 200~500 省内存)
    image_cache_max_mb: 64        # 单会话附件内存缓存字节预算(MB);超出按最早过期淘汰
    system_prompt: ""             # 系统提示词
    trigger_cmd: "/ai"            # 命令触发前缀
    at_bot: true                  # 允许 @机器人 触发
    private_chat: true            # 允许私聊触发
    group_autonomous: false       # 群聊自主发言:不 @ 机器人也响应群内非命令消息
    markdown: true                # 回复使用 Markdown
    qq_regen_button: true         # QQ 单聊/群聊(频道除外)AI Markdown 回复附加"重新生成"指令按钮(type=2,单聊手机端自动发送 /ai retry,其余填入输入框)
    qq_clear_button: true         # QQ 单聊/群聊(频道除外)AI Markdown 回复附加"清空会话"指令按钮(type=2,仅填入输入框,不自动发送 /ai reset)
    qq_plan_button: true          # QQ 单聊/群聊(频道除外)Markdown 计划消息附加"查看计划/停止生成"指令按钮(/ai plan、/ai stop;stop 同时取消计划)
    fallback: false               # 无命令匹配时兜底回复(群聊+私聊全部非命令消息,group_autonomous+private_chat 并集)
    vision_enabled: false         # 是否支持图片附件(多模态)
    max_attachment_size: 0        # 附件大小上限
    allow_private_media_hosts: [] # 补充受信媒体主机("host" 或 "host:port"):允许内网/
                                  # 明文 http 的附件地址。平台适配器已会声明自己托管的媒体
                                  # 源(如 OneBot 的 media_base_url),这里用于补充内网图床等;
                                  # 未命中的附件仍只接受公网 https
    skill_timeout: ""             # 技能执行超时
    skill_max_depth: 0            # 技能调用最大嵌套深度

工具调用

  • 自动发现:已注册的命令(如 /ping、/pic、/sauce、/stats 等)自动作为工具暴露给 LLM,无需额外配置
  • 显式注册优先:插件调用 RegisterToolProvider 显式注册的工具会移除同名自动发现工具及其命令映射,保证 LLM 调用插件自实现的 Execute
  • 技能注册工具:用户自定义技能(u_ 前缀)也会作为工具可用

自定义技能(/ai skill)

技能是用户可注册的提示词模板,可被 AI 调用:

命令 说明
/ai skill add <名称> [内容] 注册技能(支持内联 Markdown 或 .md 附件;两步注册可只发名称后由系统等待内容)
/ai skill list 列出我的技能
/ai skill remove <名称> 删除技能
/ai skill enable\|disable <名称> 启用/禁用技能
/ai skill promote <名称> 提升为系统级技能(所有用户可见可调用,需管理员)
/ai skill info <名称> 查看技能详情(含 Prompt 预览)

提示词结构与缓存

每次请求的消息序列固定分四段,越稳定的越靠前:

Stable System Prompt    框架提示词 + 自定义指令(system_prompt / 群策略),逐轮字节一致
Stable Tool Definitions 工具列表(按名称升序,见下)
Conversation History    会话历史(system 消息之后、当前用户消息之前)
Dynamic Context         运行时上下文 / 群聊最近消息 / 长期记忆 / 相关历史 / 当前执行计划
Current User Message    本轮用户消息(动态上下文附着在它前面)

LLM 侧的前缀缓存(DeepSeek 磁盘缓存、OpenAI / Anthropic prompt cache)只在请求前缀 逐字节一致时才命中,因此:

  • System 消息只放稳定内容:框架提示词与自定义指令不随事件/时间变化;运行时上下文 (含当前时间)、群聊窗口、长期记忆、相关历史都不会写进 System 消息
  • 动态上下文附在当前用户消息里:只对本次请求生效,不写回会话历史(否则旧时间、 旧群状态会污染后续请求的前缀),也不新增消息(Anthropic 要求消息数组 user/assistant 交替、system 只在顶级字段)
  • 历史裁剪是批量的:超过 max_history 时一次裁到低水位,避免逐条滑窗让历史前缀 每轮都向右位移;余量随窗口放大(max_history 的 1/4,最少 4 条),避免一个带工具 调用的回合中途触发裁剪、把本回合刚生成的工具结果前缀一起作废
  • 工具顺序确定:工具注册表底层是 map,ToolRegistry.List() 按工具名升序返回, 工具集不变时序列化结果字节稳定

缓存命中量导出为 Prometheus 指标 ai_llm_tokens_total{type="prompt_cached"}, 命中率 = rate(ai_llm_tokens_total{type="prompt_cached"}) / rate(ai_llm_tokens_total{type="prompt"})。

指标另带 kind 标签区分调用用途(chat 对话回合 / judge 插话判定 / verify 回答校验 / extract 事实抽取 / summary 总结 / skill 技能子循环 / service 对外 Complete / other 漏标)。判定、校验、抽取这类一次性调用的提示词天然没有可复用的历史前缀, 命中率接近 0,混在一起会稀释主对话的真实命中率——评估前缀结构改动时请按 kind 分开看:

sum by (kind) (rate(ai_llm_tokens_total{type="prompt_cached"}[1h]))
  / sum by (kind) (rate(ai_llm_tokens_total{type="prompt"}[1h]))

每次调用还会写一条不含消息内容的 Debug 日志(llm call kind=.. scope=.. msgs=.. tools=.. prompt=.. cached=.. hit=..% ttft=..ms tok_s=..)。指标只有聚合值,要定位"哪个 会话的哪一轮前缀在哪里断开",需要把日志按 scope(会话 ID)串起来看。

延迟拆成两段:总耗时(ai_llm_latency_seconds)把排队、prefill 与逐 token 生成 混在一起——同样 8 秒,可能是首字等了 7 秒,也可能是首字 1 秒、生成 7 秒,处理方式 完全不同。

指标 含义
ai_llm_ttft_seconds{model, kind} 首字延迟:发起请求 → 第一个内容事件(正文/推理/工具调用)。推理片段也算首字
ai_llm_tokens_per_second{model, kind} 生成速度:completion token ÷(首字 → 流结束),不含排队与 prefill

两者只对真正产出内容事件的流式调用采样(非流式调用观测不到首字);解码窗口短于 10ms 时不记速度,避免定时器精度造出几千 tok/s 的伪样本。

# 首字延迟 p95 与生成速度 p50(按用途)
histogram_quantile(0.95, sum by (le, kind) (rate(ai_llm_ttft_seconds_bucket[5m])))
histogram_quantile(0.50, sum by (le, kind) (rate(ai_llm_tokens_per_second_bucket[5m])))

工具集稳定(tool_set_sticky)

tools 是请求的顶级字段,在提示词序列里排在 system 之前,相当于一个 全局前缀开关:集合一变,其后的稳定 System Prompt 与整段历史全部失去缓存。 而工具检索是按当前 query 本地打分取 Top-K,话题一抖动就会换掉集合里的补充项。

默认开启的稳定策略在检索结果之上叠加三件事:

情况 行为
候选等于当前集合 保持
候选是当前集合的子集 保持(补充项留着:一轮没选中不等于话题不再需要)
候选新增了工具 并集(只增不减,避免话题来回摆动时反复替换)
补充项长时间未被命中 按 tool_set_ttl 批量衰减;超过 tool_set_sticky_max 按最近使用淘汰

效果:话题往复(A→B→A)与回访不再产生新的缓存失效,一次工具集切换只在真正 需要新工具时发生。换来的代价是每轮工具数量可多出至多 tool_set_sticky_max 个, 以及集合滑出 tool_budget 时不再追加补充项(可调高 tool_budget 或调低 tool_set_sticky_max)。

权限边界:稳定集合始终是本轮可用工具(群策略白名单 + RBAC 过滤后)的子集, 被收回的工具立即从集合与状态中剔除——工具集状态不会成为绕过过滤的旁路。

工具集抖动程度看 ai_toolset_changes_total(变更次数 / 请求次数)与 ai_toolset_size。

主动动作闸门(need_action_gate)

工具的检索、打分与嵌入调用只在"本轮可能需要动作"时才有意义。need_action_gate 控制这个闸门(默认 auto):

  • auto:消息是纯社交寒暄(问候/致谢/告别/应答/笑声,去掉标点、表情与尾部 语气词后整条命中白名单)时判定为无需动作——不挑选可选动作、跳过检索与嵌入调用, 工具集只保留默认保留级别(通用工具)与会话已用工具;会话存在进行中的计划时不 判否(计划推进本身就要动作)
  • always:闸门恒开、不做判定,行为与收紧前一致

判定是白名单式且保守:只有"整条消息都是社交用语"才判否,任何掺杂其它文字 (如"谢谢,帮我查下天气")都判真;"纯知识问答"无法在本地与动作请求区分,不纳入 判定。判否会让该轮工具集变小,属行为变更(见 CHANGELOG.md)。

多模态(Vision)

启用 vision_enabled 后,对话中的图片附件会随消息发送给视觉模型(提供商需支持多模态)。

性能基准

AI 插件提供本地微基准,覆盖工具目录与选择、会话状态、动态提示词、记忆与检索、Provider 请求组装。运行全部基准:

go test -run '^$' -bench . -benchmem ./builtin/ai/...

基准使用本地数据和假实现,不会调用真实模型或嵌入服务。首轮测量结果与运行限制见性能报告。

架构审查与演进

当前 AI 插件的分层问题(Tool 语义过载、Tool → Plugin 依赖倒置、Decision 层缺失、 ToolSet 驱动的缓存抖动)已在 26 — AI 插件分层 中定稿, 含现状精确行为、目标分层(Context / Retrieval / Capability / Decision / Agent State / Execution / Model Provider)与分阶段迁移顺序;Phase 0 需冻结的现状行为与测试缺口见 27 — Phase 0 冻结清单。改动 builtin/ai/ 的分层结构前请先阅读这两篇。


完整的提供商模型兼容信息与 API 差异见 builtin/ai/provider_*.go。