# TOOLS.md

转换与目录备忘；收录流程见 `AGENTS.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）分析图片内容，无需额外安装。

用途：用户图片；知识库配图的文字化；纸质材料 OCR 辅助。

---

## 工作目录

- **workspace 根目录:** `~/.openclaw/workspace/` 或 **`/home/node/.openclaw/workspace/`**（以部署为准）
- **`knowledge/`**、`knowledge/images/media/`、`knowledge/attachments/`、`knowledge/archive/`、`knowledge/FAQ.md`
- **`workspace-intern-qa/records/`**：与 intern-admin 工作区并列；**本地目录**，日报按日 `.md`、`leave.md` 专记请假（**无软链**）
- **`MEMORY.md`**、**`memory/`**（本侧日志与反馈）
- **答疑会话:** **`sessions-analysis`**；默认 **`/home/node/.openclaw/agents/intern-qa/sessions/`**

## 注意事项

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