---
name: docker_toolbox_enhancement_plan
description: 当需要继续推进 my-agent-shell 容器镜像增强改造、查看本地实验结果、或在云端构建新版镜像时，应该索引本记忆
---

# my-agent-shell 容器镜像增强改造计划与本地实验进度

> 记录时间：2026-06-25
> 相关记忆：`cloud_server_disk_usage`（服务器磁盘现状）

## 背景

当前运行在云端的 `my-agent-shell` 容器（镜像 `my-agent-shell:latest`，基于 `python:3.11-slim`）依赖不足：

- docx/pptx skill 缺少 `defusedxml`
- pptx skill 推荐的 `markitdown` 未安装
- 完全缺少 LibreOffice / soffice
- 完全缺少 pandoc、pdftoppm（poppler-utils）
- 完全缺少 Node.js / npm
- 完全缺少中文字体（`fc-list` 为 0）

导致用户常见的 Office 转换、图片处理、OCR、网页截图等需求无法跑通。

## 改造方案

### 方案 B（已选定）

在最小方案基础上扩展常见业务能力：

**系统 apt 包：**
- Office：libreoffice、pandoc、poppler-utils
- 图片/视频：imagemagick、ffmpeg
- OCR：tesseract-ocr、tesseract-ocr-chi-sim、tesseract-ocr-chi-tra
- 网页：chromium
- 字体：fonts-noto-cjk、fonts-noto-color-emoji、fonts-liberation
- 开发工具：jq、ripgrep、fd-find、tree

**Python pip 包（加入 `docker/toolbox-requirements.txt`）：**
- defusedxml
- markitdown[docx]
- pytesseract
- pdf2image

**Node 全局包：**
- docx
- pptxgenjs

**特殊处理：**
- 用 NodeSource 安装 Node 20 LTS，避免 Debian 源版本过老
- 修改 ImageMagick policy.xml 允许读写 PDF
- 设置 `NODE_PATH=/usr/lib/node_modules`

## 已修改文件

### 1. `docker/terminal.Dockerfile`

主要变更：
- apt 安装段加入 libreoffice、pandoc、poppler-utils、imagemagick、ffmpeg、tesseract、chromium、中文字体、开发工具
- 增加 ImageMagick PDF 策略调整 RUN 层
- 增加 NodeSource Node 20 安装
- 增加 `npm install -g docx pptxgenjs`
- 末尾添加 `ENV NODE_PATH="/usr/lib/node_modules"`

### 2. `docker/toolbox-requirements.txt`

新增：
- `defusedxml`
- `markitdown[docx]`
- `pytesseract`
- `pdf2image`

## 本地实验进度

### 实验环境

- 本地 macOS 15.6.1, arm64
- Docker Desktop
- 构建命令：
  ```bash
  cd /Users/jojo/Desktop/agents/正在修复中/agents
  docker build -f docker/terminal.Dockerfile -t my-agent-shell:local .
  ```

### 实验结果

| 指标 | 结果 |
|------|------|
| 构建成功 | ✅ 是 |
| 新镜像大小 | **2.9 GB**（原镜像 913 MB） |
| 镜像增加 | 约 **2 GB** |
| 空闲内存 | ~10 MB |
| 单任务峰值内存 | ~40 MB |
| 并发 5×soffice + 1×chromium 峰值内存 | **~237 MB** |

### 功能验证（全部通过）

| 测试项 | 结果 |
|--------|------|
| `soffice --headless --convert-to pdf` docx→pdf | ✅ |
| `pandoc docx -o md` | ✅ |
| `pdftoppm` pdf→png | ✅ |
| `markitdown` 读取 docx/pptx | ✅ |
| `python-docx` / `python-pptx` | ✅ |
| Node `docx-js` 生成 docx | ✅ |
| Node `pptxgenjs` 生成 pptx | ✅ |
| ImageMagick 图片裁剪 | ✅ |
| matplotlib 生成中文字体表格图片 | ✅ |
| tesseract OCR 中英文 | ✅（可运行，中文识别准确度一般） |
| chromium 网页截图 | ✅ |
| `pdf2image` PDF 转图片 | ✅ |
| docx/pptx skill 脚本 import | ✅ |

### 遇到的问题与解决

1. **markitdown 读 docx 报 MissingDependencyException**
   - 原因：默认 `markitdown` 不包含 docx converter 的 `mammoth` 依赖
   - 解决：改成 `markitdown[docx]`

2. **Node 全局安装的 `docx`/`pptxgenjs` require 不到**
   - 原因：node 默认不搜索 `/usr/lib/node_modules`
   - 解决：Dockerfile 添加 `ENV NODE_PATH="/usr/lib/node_modules"`

3. **chromium 运行时有 dbus 报错**
   - 不影响截图结果，属于 headless 环境下的常见警告

4. **ImageMagick 默认禁止 PDF 处理**
   - 解决：修改 `/etc/ImageMagick-6/policy.xml` 中 PDF 的 rights 为 `read|write`

5. **onnxruntime 启动警告**
   - 警告：`Unknown CPU vendor. cpuinfo_vendor value: 0`
   - 不影响功能，arm64 容器中的常见提示

## 尚未完成的工作

1. **云端构建验证**
   - 当前只在本地 arm64 构建验证
   - 需要在云端 x86_64 上实际构建
   - 云端磁盘紧张（只剩 4GB），需先清理或分阶段构建

2. **精简镜像体积（可选）**
   - 2.9GB 较大，可考虑去掉 chromium/ffmpeg 做成"最小方案 B"（约 1.5GB）
   - 或保留完整方案 B，但需确保云端有足够空间

3. **react-icons / react / react-dom / sharp**
   - pptxgenjs skill 文档中提到图标生成需要这几个包
   - 当前未预装，需要时可在运行时安装或后续加入镜像
   - `sharp` 涉及原生编译，构建时间和失败风险较高

4. **更详细的内存压力测试**
   - 当前只做了简单并发测试
   - 未测试大文件转换、长时间运行场景

5. **ImageMagick 安全策略复核**
   - 当前为支持 PDF 放宽了限制，需确认是否符合安全要求

## 下一步建议

### 推荐路径：分阶段上云端

1. **阶段一：精简必要包**
   - 去掉 chromium、ffmpeg、imagemagick、tesseract
   - 保留：libreoffice、pandoc、poppler-utils、node、npm、docx、pptxgenjs、字体、defusedxml、markitdown[docx]
   - 目标镜像约 1.3-1.5GB
   - 先验证 Office skill 能跑通

2. **阶段二：按需加回媒体能力**
   - 根据实际使用频率，决定是否加回 imagemagick、ffmpeg、chromium、tesseract

3. **阶段三：优化构建缓存**
   - 考虑把 apt 层拆成多个 RUN，便于失败后重试
   - 云端构建时加 `--progress=plain` 便于排查

## 关键命令

```bash
# 本地构建
 cd /Users/jojo/Desktop/agents/正在修复中/agents
 docker build -f docker/terminal.Dockerfile -t my-agent-shell:local .

# 本地测试容器
 docker run -d --name agent-test-local my-agent-shell:local tail -f /dev/null

# 验证基础依赖
 docker exec agent-test-local bash -c "which soffice pandoc pdftoppm node npm convert ffmpeg chromium tesseract jq rg fdfind tree"

# 验证 Python 包
 docker exec agent-test-local bash -c "/opt/agent-venv/bin/python -c 'import defusedxml, markitdown, pytesseract, pdf2image'"

# 验证 Node 包
 docker exec agent-test-local bash -c "node -e 'require(\"docx\"); require(\"pptxgenjs\"); console.log(\"OK\")'"

# 查看镜像大小
 docker images my-agent-shell:local

# 监控运行时内存
 docker stats agent-test-local --no-stream
```

## 重要约束

- **本地 arm64，云端 x86_64，禁止把本地构建的镜像上传到云端**
- 云端磁盘只剩 4GB，必须清理或分阶段构建
- 云端内存 2GB，构建/运行需警惕 OOM
- 云端网络差，大文件下载可能超时

## 相关文件

- `docker/terminal.Dockerfile`
- `docker/toolbox-requirements.txt`
- 项目记忆：`cloud_server_disk_usage`（服务器磁盘现状）