🧠 智能知识库导入助手 (KB Importer)

AstrBot 插件 — 一键将网页/网站导入知识库

📋 简介

KB Importer 是一个 AstrBot 插件，支持从单个网页或整站自动提取内容、清洗去噪、智能命名，并导入到 AstrBot 知识库。无需手动复制粘贴、无需逐页操作。

✨ 功能特性

特性	说明
🌐 单页导入	importkb [URL] — 输入一个 URL，自动提取正文、清洗、分类、入库
🏗️ 整站爬取	importkb-site [URL] — 自动通过搜索引擎发现网站下所有子页面，批量导入到同一个知识库
🧹 内容清洗	自动去除导航栏、广告、页脚等噪音，保留核心正文（可关闭）
🏷️ 智能命名	跳过域名中 www/docs/global/zh 等无意义前缀，精准提取品牌名 （global.bttwiki.com/zh → 「Bttwiki 中文 文档」）
🎛️ 双命名模式	smart 模式智能提取品牌名；fixed 模式走固定五分类（技术/AI/产品/设计/通用）
📂 统一入库	整站爬取自动创建/匹配合适的知识库，所有子页面汇聚到同一个库
⏱️ 防限频保护	单页间隔 + 每 5 页额外暂停，双重延迟防 API 限频（均可调）
🔧 WebUI 可调参数	7 个参数实时可调：超时、搜索数量、间隔、清洗开关、命名模式等
🚀 智能发现	site: 语法 + 中英文搜索词自动切换，对 VitePress 等动态站点友好
🛡️ 健壮中断	知识库创建失败立即终止，不浪费后续 API 调用

🔧 安装

前提条件

• AstrBot v4.x 运行中，Dashboard 插件已启用
• Tavily API Key 已配置（AstrBot WebUI → 通用配置 → websearch_tavily_key）

安装步骤

1. 将 astrbot_plugin_kb_importer/ 复制到 AstrBot/data/plugins/ 下
2. 重启 AstrBot 加载插件
3. （可选）在 WebUI 插件栏调整参数

📖 使用方法

导入单个网页

importkb https://example.com/docs/page

支持一次传入多个 URL（每两个 URL 之间有间隔延迟）：

importkb https://a.com/doc1 https://a.com/doc2 https://b.com/doc3

批量导入整个网站

importkb-site https://docs.openclaw.ai/zh-CN

插件会自动：发现子页面 → 按站点创建统一知识库 → 逐个导入 → 汇总汇报。

提示：importkb-site https://example.com/zh-CN 会限定该路径下的页面，并自动切换中文搜索词。

WebUI 可调参数

参数	说明	默认值
Tavily API Key	可独立配置，留空使用全局配置	(空)
网页提取超时	Tavily 提取网页的最大等待秒数	90
搜索最大结果	整站爬取时发现子页面的最大数量	50
单条URL提交间隔	每个 URL 导入后等待秒数	5
批量导入间隔	每导入 5 页后额外暂停的秒数	15
自动内容清洗	是否去除网页噪音	开启
命名方式	smart（智能品牌提取）/ fixed（固定五分类）	smart

🧠 智能命名逻辑

Smart 模式（默认）

1. 跳过 www/docs/global/zh/cn/en/api/cdn/static 等常见无意义前缀
2. 取第一个有意义词作为品牌名
3. 从 URL 路径判断语言（zh-CN → 中文）
4. 根据内容判断性质后缀（教程/手册/规范/安装指南）
5. 组合 → 「Bttwiki 中文 文档」

示例：

• global.bttwiki.com/zh/ → Bttwiki 中文 文档
• docs.openclaw.ai/zh-CN → Openclaw 中文 文档
• en.wikipedia.org → Wikipedia 文档

Fixed 模式

基于内容关键词自动匹配五大分类：技术文档库 / AI/ML 知识库 / 产品文档库 / 设计资源库 / 通用知识库。

🐛 常见问题

问题	解决方案
导入提示 timeout	增大 WebUI「网页提取超时」参数
提示 "未发现子页面"	VitePress/SPA 站点已默认使用搜索引擎优先方式。如仍失败，尝试用英文版首页 URL
批量导入过慢	减小「搜索最大结果」或「批量导入间隔」
显示 ✅ 但没入库（丢页）	增大「单条URL提交间隔」至 5–8 秒
知识库命名不符合预期	切换 naming_mode 为 fixed 使用固定分类
创建知识库失败	确认 Dashboard 插件已启用，AstrBot 正在监听 localhost:6185

📦 文件结构

astrbot_plugin_kb_importer/
├── main.py           # 核心逻辑（~500 行）
├── _conf_schema.json # WebUI 可调参数配置
├── metadata.yaml     # 插件元数据
├── README.md         # 本文档
├── logo.png          # 插件图标
└── LICENSE

📝 版本历史

版本	日期	变更
v1.1.0	2026-05-08	🔧 重构：删除 45% 死代码，修复命名三重文档、域名不一致、搜索词硬编码等致命 Bug；naming_mode 双模式生效；品牌提取改用前缀跳过算法；单页导入支持多 URL 间隔；实机 API 测试通过
v1.0.0	2026-05-07	🎉 初始版本：单页导入、整站爬取、VitePress 兼容、智能命名、WebUI 参数配置

👤 作者

3BM42的AI Agent

由 ash 主人审查、测试并持续改进 🐱