Knowledge Base Skill

⚠️ 首次使用必读 ⚠️

安装后请立即运行初始化脚本，自动安装依赖并创建知识库目录：
python3 scripts/init.py
不运行这一步，后续所有功能都无法正常工作。

一套完整的文档转换与知识库管理工具。自动将各类文档转换为 Markdown，按内容智能分类，建立本地可检索的私人知识库。

功能

文档转换：集成 Microsoft MarkItDown，支持 PDF、Word、PPT、Excel、HTML、EPUB、图片等格式转为 Markdown
自动分类：基于内容关键词智能分类，支持自定义分类
关键词提取：使用 jieba 中文分词 + TF-IDF 提取关键词，建立检索索引
本地检索：基于关键词、标题、摘要、内容的全文检索
向量检索：基于 chromadb 的语义搜索
自动导入：监控目录自动导入新文件
批量导入：递归扫描目录批量导入
飞书打通：接收飞书文件消息自动导入
知识库管理：文档增删改查、分类管理、统计信息
降低 Token 消耗：文档内容存储于本地，仅在检索时按需加载，不占用 Memory

支持的文件格式

PDF、DOCX、PPTX、XLSX/XLS
HTML、EPUB、TXT、CSV、JSON、XML
图片（EXIF + OCR）
ZIP（遍历内容）
更多格式详见 MarkItDown 文档

依赖（自动安装）

首次使用自动检测并安装依赖，无需手动配置：

markitdown[all] — 文档转换核心
jieba — 中文分词
chromadb — 向量检索（首次使用向量功能时自动安装）

如需手动安装：

pip install markitdown[all] jieba chromadb

目录结构

~/.openclaw/workspace/knowledge-base/
├── .index.json          # 索引文件（元数据、关键词、摘要）
├── .chroma/             # 向量数据库
├── 学术论文/
├── 技术文档/
├── 工作资料/
├── 读书笔记/
├── 项目文档/
├── 参考资料/
└── 未分类/

使用方式

初始化知识库

python3 scripts/init.py

1. 单文件导入

python3 scripts/kb_cli.py ingest <文件路径>
python3 scripts/kb_cli.py ingest ~/Downloads/report.pdf --category 技术文档

2. 批量导入

递归扫描整个目录，批量导入所有支持的文件：

python3 scripts/batch_ingest.py ~/Documents/我的资料
python3 scripts/batch_ingest.py ~/Downloads --no-recursive  # 不递归子目录
python3 scripts/batch_ingest.py ~/Documents --dry-run       # 预览模式

3. 自动导入（监控模式）

持续监控 /tmp/openclaw/ 目录（飞书文件下载目录），新文件自动导入：

# 单次扫描
python3 scripts/auto_ingest.py --once

# 持续监控（每30秒扫描一次）
python3 scripts/auto_ingest.py --watch

# 自定义间隔
python3 scripts/auto_ingest.py --watch --interval 60

飞书自动导入建议：将监控脚本加入 OpenClaw cron job，每分钟自动扫描：

{
  "schedule": { "kind": "cron", "expr": "*/1 * * * *" },
  "payload": {
    "kind": "agentTurn",
    "message": "运行 python3 ~/.openclaw/workspace/skills/knowledge-base/scripts/auto_ingest.py --once"
  },
  "sessionTarget": "isolated"
}

4. 关键词检索

python3 scripts/kb_cli.py search "机器学习"
python3 scripts/kb_cli.py search "神经网络" --category 技术文档 --limit 5

5. 向量语义检索

首次使用前需构建索引：

# 构建/更新向量索引
python3 scripts/vector_index.py build

# 强制重建
python3 scripts/vector_index.py build --force

# 语义搜索
python3 scripts/vector_index.py search "深度学习在图像处理中的应用"
python3 scripts/vector_index.py search "神经网络" --limit 5 --category 技术文档

6. 列出文档

python3 scripts/kb_cli.py list
python3 scripts/kb_cli.py list --category 学术论文

7. 查看文档详情

python3 scripts/kb_cli.py get <doc_id>

8. 删除文档

python3 scripts/kb_cli.py delete <doc_id>

9. 管理分类

python3 scripts/kb_cli.py add-category "旅行攻略"

10. 查看统计

python3 scripts/kb_cli.py stats

飞书文件自动处理

当用户通过飞书发送文件时：

文件会被下载到 /tmp/openclaw/ 目录
运行 python3 scripts/auto_ingest.py --once 自动导入
或直接调用 feishu_im_bot_image 下载后手动导入

示例 workflow：

用户发送 PDF → 检测到文件消息
  → 调用 feishu_im_bot_image 下载到 /tmp/openclaw/
  → 调用 auto_ingest.py 导入知识库
  → 返回导入结果给用户

核心脚本

脚本	功能
`scripts/kb_manager.py`	核心引擎（Python API）
`scripts/kb_cli.py`	单文件操作 CLI
`scripts/batch_ingest.py`	批量导入
`scripts/auto_ingest.py`	自动监控导入
`scripts/vector_index.py`	向量索引与语义搜索
`scripts/init.py`	初始化与依赖安装

设计原则

零配置开箱即用：自动安装依赖，默认分类，自动处理
内容优先：按内容而非文件名分类
本地优先：所有数据本地存储，无需外部服务
检索高效：关键词索引 + 向量语义检索双层架构
降低负担：文档内容不进 Memory，需要时再读
中文友好：jieba 分词 + 中文停用词过滤
自动化：支持监控模式和批量导入，减少手动操作

技术栈

文档转换：Microsoft MarkItDown
中文分词：jieba + TF-IDF
向量检索：ChromaDB（默认 embedding）
索引存储：JSON 文件索引
存储格式：Markdown + YAML 头部

许可证

MIT

Knowledge Base

Safety Notice

Copy this and send it to your AI assistant to learn