批量将本地目录下的文件导入 AstrBot 知识库，绕过网页控制端"单次最多 10 个文件"的限制。
适用于需要一次性导入成百上千个文档（如 Markdown 笔记、Wiki 导出）的场景。
插件不调用 HTTP，而是直接复用 AstrBot 内部的 KBHelper.upload_document，与网页端走完全相同的解析、分块、向量化代码路径，仅去掉了数量限制。上传在后台 asyncio 任务中逐文件进行，不阻塞会话。
- 📁 递归扫描：导入指定目录下所有匹配文件（默认
*.md），含子目录 - 🔄 后台运行：启动后立即返回，任务在后台持续进行
- 📊 进度查询：
/kbimport status实时查看完成数、失败数、速率、预计剩余 - 🔁 断点续传：按"相对路径文件名"去重，已上传的文件重启后自动跳过
- 🛑 可停止：
/kbimport stop优雅停止，已上传的保留 - 🖥️ 跨平台路径：自动识别 Linux / WSL
/mnt/ 原生 Windows 路径
先在 AstrBot 网页控制端创建一个知识库（需配置好 embedding 模型）。本插件只负责往已有知识库导入内容，不创建知识库。
/kbimport list
输出示例：
可用知识库(用 start 命令时填写序号):
1. 我的Wiki | 文档数 0 | 块数 0
2. 开发笔记 | 文档数 120 | 块数 856
用法: /kbimport start <序号> <文件目录路径>
/kbimport start <序号> <文件目录路径>
序号来自 list 命令。路径支持以下写法（含空格无需加引号，路径作为命令末尾参数）：
| 环境 | 写法示例 |
|---|---|
| WSL2 访问 Windows 盘 | /mnt/d/Program Files/KiwixDownloads/Markdown |
| Windows 盘符（自动转换） | D:\Program Files\KiwixDownloads\Markdown |
| Linux 原生 | /home/user/docs/wiki |
示例：
/kbimport start 1 /mnt/d/Program Files/KiwixDownloads/Markdown
/kbimport status
输出示例：
知识库: 我的Wiki
根目录: /mnt/d/Program Files/KiwixDownloads/Markdown
状态: running
进度: 240 完成 / 0 跳过 / 2 失败 / 7646 总计
当前文件: 15周年庆/活动介绍.md
耗时: 18分32秒
速率: 0.22 文件/秒
预计剩余: 558分5秒
失败列表(最多显示10条):
- xxx.md: 文档解析失败：未能从文件中提取可索引文本。
/kbimport stop
将在当前文件处理完后退出。已上传的文件保留在知识库中，下次 start 同一知识库会自动跳过。
- 已上传的文件路径会持久化到插件 KV 存储中（key 为
kb:{kb_id}:done）。 - AstrBot 进程重启后，后台任务进程会丢失，但已完成记录保留。再次
start同一知识库 + 同一根目录，会自动跳过已传文件，实现续传。 - 去重依据是相对根目录的文件路径（如
15周年庆/活动介绍.md），因此不同子目录下的同名文件不会冲突。
在 AstrBot 网页控制端 → 插件管理 → 本插件配置中设置：
| 配置项 | 默认 | 说明 |
|---|---|---|
chunk_size |
512 | 文本分块大小（字符数） |
chunk_overlap |
50 | 分块重叠大小 |
batch_size |
32 | 向量化批处理大小 |
tasks_limit |
3 | 并发任务数 |
max_retries |
3 | 单文件最大重试次数 |
progress_interval |
20 | 每传 N 个文件推送一次进度 |
glob_pattern |
*.md |
文件匹配模式 |
chunk_size/chunk_overlap建议与知识库创建时的分块参数保持一致。
| 命令 | 权限 | 说明 |
|---|---|---|
/kbimport list |
管理员 | 列出所有知识库及序号 |
/kbimport start <序号> <路径> |
管理员 | 启动后台批量导入 |
/kbimport status |
管理员 | 查看当前任务进度 |
/kbimport stop |
管理员 | 停止当前任务 |
- 上传速度主要受 embedding 模型 API 限制，千级文件可能耗时数小时，请耐心等待。
- 进度推送通过会话主动发送，QQ 官方 API 平台（qq_official）不支持主动消息，该情况下请用
/kbimport status手动查询。 - 单个文件失败不会中断整体任务，失败信息会记录在
status输出中。 - 本插件不修改 AstrBot 核心代码，无额外外部依赖。