NoneBot-Plugin-Advisor

基于 OpenAI 兼容格式的跨平台 LLM 客服。让机器人像一个真人客服一样为你的项目提供支持：读文档、查日志、看截图、在图上圈注并回发、必要时联网搜索。

• 跨平台：基于 nonebot-plugin-alconna + nonebot-plugin-uninfo
• 定时从文档仓库（git）拉取 md / 图片，并用视觉模型给每张图片建立描述索引
• @ 机器人提问 → agent 检索文档回答，口吻自然、短句、不甩长文、不输出 Markdown，引导用户一步步排查
• 用户发来的图片 / txt / log 会自动进入会话的“内存文件系统”，agent 可用工具按行读取、搜索关键词
• 引用消息里的图片/文件也会进入会话
• 提供图片标注工具：画矩形/椭圆/箭头/高亮、写不超过 10 个字的文字，标注后随回复回发给用户
• 可联网搜索（SearXNG / Bing 兜底）

📦 安装

nb plugin install nonebot-plugin-advisor

或在项目里安装后，在 pyproject.toml 的 [tool.nonebot] 中加入：

plugins = ["nonebot_plugin_advisor"]

依赖：nonebot2 >= 2.5、nonebot-plugin-alconna、nonebot-plugin-uninfo、nonebot-plugin-localstore、nonebot-plugin-apscheduler、openai >= 3.8、pillow、httpx、curl-cffi

⚙️ 配置

在 .env / .env.prod 中配置（环境变量前缀 ADVISOR_）：

# ── LLM（OpenAI 兼容） ──
ADVISOR_LLM_BASE_URL=https://api.openai.com/v1
ADVISOR_LLM_API_KEY=sk-xxxx
ADVISOR_LLM_MODEL=gpt-4o-mini
# 视觉模型（图片描述/索引用）。留空则尝试使用主模型
ADVISOR_VISION_MODEL=

# ── 人设 / 行为 ──
ADVISOR_NICKNAME=小顾
ADVISOR_PRODUCT_NAME=NoneBot
ADVISOR_KB_DESCRIPTION=关于 NoneBot 的官方文档
ADVISOR_ACK_TEXT=收到~我帮您看下，稍等一下哦
ADVISOR_IMAGE_INLINE=false   # 是否把用户图片直接以多模态塞给主模型（主模型需支持看图）

# ── 联网搜索 ──
ADVISOR_ENABLE_WEB=true
# 自建 SearXNG（推荐，无 key）；留空自动退回 Bing
ADVISOR_SEARXNG_URL=

# ── 文档知识库：定时拉取仓库并给图片做视觉索引 ──
ADVISOR_KB_SOURCE=            # git 仓库地址或本地目录；留空禁用
ADVISOR_KB_BRANCH=
ADVISOR_KB_SYNC_CRON=0 3 * * *   # cron；留空且 INTERVAL>0 时用间隔
ADVISOR_KB_SYNC_INTERVAL=0       # 分钟；都为 0 则仅启动时同步一次
ADVISOR_KB_MAX_IMAGES_PER_SYNC=50

完整配置项

🎉 使用

对话

• 群聊：@机器人 <问题>；支持直接发截图 / txt / log / 引用带图消息。
• 私聊：直接发消息即可。
• 发送后机器人会先回一句“收到”，随后以客服口吻给出短回复并引导你一步步排查；必要时会在你发的图上画框标注并回发给你，配一句“照着红框这里点一下”。

指令

知识库

配置 ADVISOR_KB_SOURCE 后：

• 插件启动时会先同步一次（后台进行，不阻塞启动）；
• 按 ADVISOR_KB_SYNC_CRON 或 ADVISOR_KB_SYNC_INTERVAL 定时更新；
• 每次同步会拉取 git 仓库，收集全部 md/mdx 文档与图片；新增/变更的图片会调用视觉模型生成描述，写入本地索引（localstore 数据目录下的 knowledge/kb_index.json）。

agent 回答时会通过 search_kb / read_kb_doc 检索文档，并可用 send_kb_image 把文档里的截图发给用户，或先标注再发送。

提示：知识库内容缓存于本地数据目录，可随时用 客服同步 手动刷新；机器人重启后索引仍在（文档/图片索引持久化），只有聊天记忆与上传附件是内存态、重启即清空。

🧠 工具一览

📁 目录结构

src/nonebot_plugin_advisor/
├── __init__.py        # 插件入口：matcher、控制命令、定时调度
├── config.py          # 全部配置项
├── agent.py           # agent 工具调用主循环
├── llm.py             # OpenAI 兼容客户端（对话/视觉）
├── toolkit.py         # 工具集（文档/文件/图片/搜索）
├── docs_store.py      # 知识库：git 拉取 + md/图片索引 + 检索
├── session_store.py   # 会话内存虚拟文件系统 + 对话历史
├── media.py           # 从 UniMessage 抽取文本/图片/文件/引用
├── imageops.py        # 图片标注（Pillow，归一化坐标）
├── searcher.py        # 联网搜索
├── prompts.py         # 客服人设提示词
└── utils.py           # 通用工具

🧪 开发 / 测试

uv sync
uv run pytest        # 跑测试
uv run ruff check .  # lint
uv run ruff format . # 格式化

📄 协议

MIT