# TOOLS.md - 工具备忘


## 文档转换工具

### skill

可以优先采用 `skills/sophnet-docx` 

### pandoc

用于将 `.docx` 转换为 `.md`，保留格式并提取图片：

```bash
# 基本转换（纯文字）
pandoc knowledge/原文件.docx -t markdown -o knowledge/目标文件.md

# 含图片提取（推荐）
pandoc knowledge/原文件.docx -t markdown --extract-media=knowledge/images -o knowledge/目标文件.md
```

图片会提取到 `knowledge/images/media/` 下，`.md` 中自动生成引用路径。

**注意：** pandoc 不支持提取 `.emf` 格式图片（Word 常用的 Windows 矢量格式）。遇到 EMF 时需要：
1. 用 python zipfile 从 docx 中解压 `word/media/*.emf` 到 `knowledge/images/emf_raw/`
2. 用 LibreOffice 转换为 PNG：
```bash
libreoffice --headless --convert-to png --outdir knowledge/images/media/ knowledge/images/emf_raw/*.emf
```

### LibreOffice

用于 EMF → PNG 转换。Docker 重启后可能丢失，安装命令：
```bash
apt-get update -qq && apt-get install -y -qq libreoffice-draw
```

### python-docx

用于提取 `.docx` 纯文本（不保留格式）。Docker 重启后可能丢失，安装命令：
```bash
pip3 install python-docx
```

使用示例：
```bash
python3 -c "from docx import Document; d=Document('knowledge/原文件.docx'); print('\n'.join(p.text for p in d.paragraphs))" > knowledge/目标文件.md
```

### 嵌入附件提取（python zipfile）

Word 文档中嵌入的 Excel/Visio/PDF 等附件位于 docx zip 包的 `word/embeddings/` 路径下：

```python
import zipfile, os
with zipfile.ZipFile('knowledge/原文件.docx', 'r') as z:
    for f in z.namelist():
        if f.startswith('word/embeddings/'):
            z.extract(f, 'knowledge/attachments/')
```

提取后文件名可能不可读（如 `Microsoft_Excel____.xlsx`），需根据上下文重命名。

> `zipfile` 是 Python 标准库，无需额外安装。

---

## 图片识别工具

### image 工具（内置）

调用配置的视觉语言模型（VLM）分析图片内容，无需额外安装。

用途：
- 识别用户发来的图片中的文字、表格、流程图
- 为知识库中的流程图生成文字描述
- 识别拍照的纸质文档内容，辅助录入知识库

---

## 工作目录

- **workspace 根目录:** `~/.openclaw/workspace/` 或绝对路径 `/home/node/.openclaw/workspace/`
- **知识库目录:** `knowledge/`
- **图片目录:** `knowledge/images/media/`
- **嵌入附件目录:** `knowledge/attachments/`
- **旧版本归档:** `knowledge/archive/`
- **FAQ 文件:** `knowledge/FAQ.md`
- **长期记忆:** `MEMORY.md`
- **日常记忆目录:** `memory/`（含日常交互记录、用户反馈、安全日志）

## 注意事项

- `read` 工具可直接读取 `.md`、`.txt`、`.xlsx`，但不能读取 `.docx`、`.pdf` 的文字内容
- `.docx` 必须先用 pandoc 或 python-docx 转换后再读取
- `.pdf` 必须先用 `sophnet-image-ocr` skill 转换后再读取
- `grep` 工具可搜索 `knowledge/` 目录下所有 `.md` 文件的内容
- **Docker 环境：** 容器重启后 pandoc、libreoffice、python-docx 可能丢失，使用前务必先执行依赖检查
