JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
main
agent-Specialization/.astrion/memory/docker_toolbox_enhancement_plan.md

6.7 KiB
Raw Permalink Blame History

name description
docker_toolbox_enhancement_plan 当需要继续推进 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
  • 构建命令： 
    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 便于排查

关键命令

# 本地构建
 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（服务器磁盘现状）