# TOOLS.md - 工具备忘

## 文档转换工具

### sophnet-docx skill

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

### 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 标准库，无需额外安装。

---

## 图片识别工具

### sophnet-image-ocr skill

用于将 `.pdf`、扫描件、图片中的文字提取为可读文本。

### image 工具（内置）

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

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

**图片录入知识库约定：** 图片识别后须将文字内容写入 `.md` 正文（而非仅保留图片引用），保证后续可 `grep` 检索。

---

## 本 Agent 工作区目录

| 路径 | 用途 |
|------|------|
| `knowledge/` | 部门知识库（制度、流程、常用管理文档） |
| `knowledge/INDEX.md` | 知识库总索引 |
| `knowledge/images/media/` | pandoc 提取的图片（PNG 等） |
| `knowledge/images/emf_raw/` | docx 中解压的 EMF 矢量图原始文件 |
| `knowledge/attachments/` | docx 中提取的嵌入附件 |
| `people/` | 人员：名册、简历、绩效等 |
| `meetings/` | 会议：周期定义、单次与场次实例、总索引 |
| `todos/` | 待办：`open.md` 与按月归档 |
| `retrospectives/` | 复盘：`templates/`（预留）、`records/` |
| `MEMORY.md` | 长期记忆 |
| `memory/` | 日志与安全记录 |

## 注意事项

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