211 lines
6.7 KiB
Markdown
211 lines
6.7 KiB
Markdown
---
|
||
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`（服务器磁盘现状）
|