Mac Mini Knowledge Base + RAG Setup

SKILL.md

---
name: macmini-knowledge-base
version: 1.2.0
description: |
  在 Mac Mini (M4) 上快速搭建本地知识库 + RAG 自然语言搜索系统。
  适用场景：
  - 新 Mac 配置知识库：从零开始安装配置 Ollama、embedding模型、定时任务、OCR文档分析
  - 遇到 PDF 提取乱码、定时任务超时、skill 加载失败等问题
  - 想要建立每日自动分析文档 + 08:00发送摘要到飞书的流程
  - 迁移或复现知识库：打包整个 knowledge 目录和配置到新电脑
  本 skill 会引导完成：目录结构创建、依赖安装、脚本部署、定时任务注册、OpenClaw 配置。
---

# Knowledge Base Setup

在 Mac Mini 上快速搭建本地知识库 + RAG 搜索系统。

## 核心功能

- **文档处理**：支持 PDF（正常/乱码字体/图片型）、PPTX、DOCX、XLSX、MD
- **智能提取**：自动识别文档类型，选择最优提取方案，中英文关键词自动匹配
- **目录生成**：自动生成带标签的文章目录，缓存加速
- **定时任务**：每天 23:00 分析新文档，08:00 发送摘要到飞书

## 快速开始

### 一键安装

```bash
cd ~/.openclaw/workspace/skills/knowledge-base-setup/scripts
bash setup.sh <飞书用户ID>
```

### 手动分步安装

**Step 1: 环境准备**
```bash
brew install tesseract
pip3 install pytesseract pymupdf pdfplumber python-pptx
# 安装 Ollama: https://ollama.com/download
```

**Step 2: 下载 embedding 模型**
```bash
ollama pull nomic-embed-text
```

**Step 3: 创建目录结构**
```bash
mkdir -p ~/.openclaw/workspace/knowledge/.analysis/summaries/archives
mkdir -p ~/.openclaw/workspace/knowledge/temp_docs
mkdir -p ~/.openclaw/workspace/knowledge/"Macro Financials"
touch ~/.openclaw/workspace/knowledge/文章目录/文章目录.md
```

**Step 4: 部署脚本**
```bash
cp ~/.openclaw/workspace/skills/knowledge-base-setup/scripts/*.py \
   ~/.openclaw/workspace/knowledge/.analysis/
cp ~/.openclaw/workspace/skills/knowledge-base-setup/scripts/generate_catalog.py \
   ~/.openclaw/workspace/knowledge/.analysis/
chmod +x ~/.openclaw/workspace/knowledge/.analysis/*.py
chmod +x ~/.openclaw/workspace/knowledge/.analysis/*.js
```

**Step 5: 配置 OpenClaw**

编辑 `~/.openclaw/openclaw.json`，加入：
```json
{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434",
        "api": "ollama",
        "models": [
          {"id": "nomic-embed-text", "name": "Nomic Embed Text"}
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "ollama",
        "model": "nomic-embed-text"
      }
    }
  }
}
```

确保 tools 区块有：
```json
"tools": {
    "alsoAllow": ["exec", "process"]
}
```

然后重启：`openclaw gateway restart`

**Step 6: 注册定时任务**
```bash
# 22:00 分析任务
openclaw cron add \
  --name "22:00分析新文档" \
  --cron "0 22 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --timeout-seconds 600 \
  --message "运行 run_analysis.py 和 generate_catalog.py" \
  --announce --channel feishu --to "user:<飞书用户ID>"

# 08:00 发送任务
openclaw cron add \
  --name "08:00发送文档摘要" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --timeout-seconds 120 \
  --message "读取 summaries/ 目录发送摘要到飞书" \
  --announce --channel feishu --to "user:<飞书用户ID>"
```

## 文档处理流程（generate_catalog.py）

### 文件类型 × 提取方式

| 格式 | 提取方式 | 说明 |
|------|----------|------|
| PDF（正常字体） | pdf-parse 直读 | 中文报告等正常文档 |
| PDF（乱码/图片型） | pymupdf 渲染 + tesseract OCR | 外资投行 PDF、自定义字体编码 |
| PPTX | python-pptx 读文字 | 幻灯片内容 |
| DOCX/XLSX | 占位（可扩展） | 待实现 |
| MD | 直接读文件 | Markdown 格式 |

### PDF 三步处理逻辑

```
Step 1: 50KB 快速预检（pdf-parse 前50KB）
         ↓
  预检文本含关键词？ → Yes → Step 2: 完整 pdf-parse
         ↓ No
  Step 3: pymupdf 渲染前3页 + OCR（跳过无意义的完整解析）
```

**为什么这样做：**
- 正常中文 PDF：pdf-parse 直接出结果（~800ms），不做 OCR 浪费
- 外资投行乱码 PDF：pdf-parse 要 30s 才返回乱码，现在 100ms 预检直接跳 OCR
- 图片型 PDF：本来就是 OCR 素材，预检阶段就会走 OCR 路线

### 关键词库（中英双语）

**中文（47个）：** 房产、房价、房地产、居民、消费、股市、经济、政策、利率、通胀、人民币、A股、美联储、PBOC、GDP、股票、资产、投资、债券、银行、PPI、CPI、PMI、M2、就业、失业、汽车、新能源、AI 等

**英文（70+个）：** property、real estate、GDP、inflation、CPI、PPI、PMI、PBOC、Fed、consumer、economy、growth、housing、stock market、EV、AI 等

**标签输出语言：** 自动判断——英文内容匹配英文关键词输出英文标签，中文内容匹配中文关键词输出中文标签

### 缓存机制

- 缓存文件：`knowledge/.analysis/.catalog_cache.json`
- 缓存命中条件：文件 mtime 未变且标签不是"待提取"
- 缓存命中时：跳过解析，直接复用，二次运行 ~1.5 秒


### 分批处理机制（2026-05-15 新增）

**解决场景：** 文件数量多（500+）时，一次性全量处理超过 cron 300s 超时限制

**核心思路：** 每次只处理一小批（20个），处理完立即保存进度并退出，下次定时任务自动继续下一批

#### run_analysis.py — 文档分析分批

```
状态文件：analysis_state.json
├── analyzed_files: [...]  已完成文件名
└── pending_files: [...]   待处理队列（文件名）

每次运行流程：
1. 从 pending_files 取前 20 个文件名
2. 全文提取 → 写入 summaries/
3. pending_files 移除已处理，追加到 analyzed_files
4. save_state() 持久化 → 退出
下次触发时自动从断点恢复
```

**效果：** 300个待分析文件 → 分15次 cron 完成，每次 ~30s

#### generate_catalog.py — 标签提取分批

```
进度文件：.catalog_progress.json
├── last_index: 39     已处理到第几个（0-based）
├── rows: [...]        每行标签数据
├── total: 598        文件总数
└── done: false       是否全部完成

每次运行流程：
1. 从 last_index+1 取 20 个文件
2. 提取标签（缓存命中则跳过）
3. 保存到 rows[last_index]
4. 每批保存一次 progress.json
5. 处理到最后一个？→ done=true → 生成完整目录
6. 否则保存 progress.json → 退出
```

**效果：** 598个文件标签 → 分30批完成，每次 ~15s

#### 手动运行命令

```bash
# 手动触发一批文档分析
python3 ~/.openclaw/workspace/knowledge/.analysis/run_analysis.py

# 手动触发一批标签提取
cd ~/.openclaw/workspace/knowledge/.analysis && python3 generate_catalog.py

# 查看标签提取进度
cat ~/.openclaw/workspace/knowledge/.analysis/.catalog_progress.json | python3 -c "
import json,sys; d=json.load(sys.stdin)
print(f'{d[\"last_index\"]+1}/{d[\"total\"]} 个文件, done={d[\"done\"]}')"
```

**注意：** pending_files 为空时说明没有新文件，脚本直接退出。进度文件损坏可删除重新开始。

## 迁移到新电脑

1. 复制整个目录：
   ```bash
   scp -r ~/.openclaw/workspace/knowledge user@new-mac:~/.openclaw/workspace/
   ```
2. 在新电脑运行 setup.sh 或手动分步安装
3. 重新注册定时任务（Job ID 会变）

## 避坑指南

| 问题 | 原因 | 解决 |
|------|------|------|
| PDF 提取乱码 | 自定义字体无 ToUnicode | pymupdf + tesseract OCR（已内置） |
| 定时任务超时 | 默认 120s 太短 | `--timeout-seconds 600` |
| 飞书无 exec 工具 | tools 策略限制 | 添加 `alsoAllow: [exec, process]` |
| skill 加载失败 | 导出名称错误 | `CodeChunker` → `FileChunker` |
| BGE-M3 卡顿 | 16GB 内存不足 | 继续用 nomic-embed-text |
| brew install ollama 慢 | 网络问题 | 直接下载 dmg 安装 |

## 关键路径

| 内容 | 路径 |
|------|------|
| Skill 目录 | `~/.openclaw/workspace/skills/knowledge-base-setup/` |
| 知识库 | `~/.openclaw/workspace/knowledge/` |
| 分析脚本 | `~/.openclaw/workspace/knowledge/.analysis/` |
| 目录缓存 | `~/.openclaw/workspace/knowledge/.analysis/.catalog_cache.json` |
| 摘要输出 | `~/.openclaw/workspace/knowledge/.analysis/summaries/` |
| 文章目录 | `~/.openclaw/workspace/knowledge/文章目录/文章目录.md` |
| OpenClaw 配置 | `~/.openclaw/openclaw.json` |