koishi-plugin-aichat

一个面向 OneBot v11 QQ 群聊的 Koishi AI 聊天插件。支持配置多个 OpenAI 兼容或 Anthropic 兼容模型、多个人设、群级行为覆盖、群历史上下文、图片输入和概率主动回复。

功能

• 仅处理 OneBot v11 的 QQ 群消息，不处理私聊或其他平台。
• 支持 OpenAI Chat Completions 和 Anthropic Messages 两种协议。
• 每个模型独立配置 API Host、API Key、模型名称和输入能力。
• 为所有群设置默认人设、主模型和回退模型，并可按 QQ 群号覆盖。
• 支持被 @ 回复和概率主动回复，二者均可全局配置或按群覆盖。
• 使用 OneBot 群历史消息作为上下文，历史图片也可发送给视觉模型。
• 同群请求串行处理；主动回复具有概率、冷却和繁忙跳过机制。

安装

确保 Koishi 实例已经配置 OneBot v11 适配器和 HTTP 服务，然后安装插件：

npm install @emmm3412941994/koishi-plugin-aichat

在 Koishi 控制台中启用 ai-chat 并完成模型配置。插件至少需要两个不同的模型配置，分别作为主模型和回退模型。

模型配置

每个模型包含以下字段：

| 字段 | 说明 | | --- | --- | | id | 供其他配置引用的唯一 ID | | name | 控制台显示名称 | | protocol | openai 或 anthropic | | apiHost | API 根地址、/v1 地址或完整接口地址 | | apiKey | API Key，在控制台中以密码字段显示 | | model | 提交给服务商的模型名称 | | inputTypes | 必须包含 text，视觉模型额外选择 image | | timeout | 请求超时，单位毫秒 | | maxTokens | 最大输出 token 数 | | temperature | 可选；留空时不向 API 发送该参数 |

OpenAI 协议的 Host 示例：

https://api.openai.com
https://api.openai.com/v1
https://example.com/custom/chat/completions

Anthropic 协议的 Host 示例：

https://api.anthropic.com
https://api.anthropic.com/v1
https://example.com/custom/messages

插件会根据协议补全默认接口路径。使用代理或兼容服务时，请确认它实现了对应的请求格式，而不只是接受相同的鉴权方式。

模型路由

插件检查当前消息和所选历史上下文构成的完整请求：

1. 请求不含图片，或主模型支持图片时，使用主模型。
2. 请求含图片且主模型不支持图片时，使用回退模型。
3. 回退模型也不支持图片时，不调用 API；被 @ 时发送输入不受支持提示，主动触发时保持静默。

网络、超时、限流、HTTP 或 API 错误不会触发回退模型。被 @ 的请求失败时，群内会收到简短失败提示；主动回复失败只写入日志。

人设与群配置

人设由唯一 ID、显示名称和 system prompt 组成。默认行为指定：

• 默认人设 ID
• 主模型 ID 与回退模型 ID
• 上下文开关和历史消息条数
• 被 @ 回复开关
• 主动回复开关、概率和冷却秒数

群聊覆盖表以 QQ 群号为键。覆盖项留空时继承默认行为，因此只需填写该群真正不同的字段。

主动回复概率范围为 0 到 1，例如 0.05 表示每条符合条件的消息有 5% 概率触发。被 @ 的消息优先按 @ 回复处理，不会同时产生主动回复。

上下文与图片

上下文通过 OneBot 适配器的 getMessageList() 能力读取，并从当前消息向前分页。部分 OneBot v11 实现没有提供 get_group_msg_history 扩展接口；遇到这种情况，插件会记录警告并只使用当前消息，不会阻止回答。

历史消息会按时间正序发送给模型：机器人的历史发言作为 assistant，其他群成员作为带昵称标识的 user。所选历史范围内的图片会被下载并转为 base64 输入。

图片限制可配置：

• 单张图片最大字节数，默认 5 MiB。
• 单次请求最大图片数，默认 20 张，超过时优先保留较新的图片。
• 图片下载超时，默认 30 秒。

超限、下载失败或 MIME 类型异常的图片会转换为文本占位。图片内容会发送给配置的模型服务商，请根据群聊隐私要求设置上下文范围和图片限制。

调度行为

• 同一群内的模型请求串行执行。
• 明确的 @ 请求会进入队列，不会因繁忙丢失。
• 主动回复在同群已有请求时直接跳过。
• 主动冷却从触发时开始计算，默认 30 秒，可按群覆盖。
• 所有回答直接发送普通群消息，不引用触发消息。

开发

npm install
npm run typecheck
npm test
npm run build

构建产物输出到 lib/。

限制

• 不提供群内命令；模型、人设和群设置仅在 Koishi 控制台中修改。
• 不支持私聊、语音模型、文件模型或流式分段回复。
• 不在本地保存聊天历史，重启后不会保留任何上下文缓存。
• 不内置联网搜索或模型工具调用。

License

MIT