byted-tos-doc-process

火山引擎 TOS 文档处理

预览并转换存储在火山引擎 TOS 中的办公文档 — 转换为 PDF/PNG/JPG、获取页数、HTML 预览 URL，以及导出指定页码范围。

设置（每个环境仅需一次）

首次使用时安装依赖：

cd {baseDir}
pip install -r {baseDir}/requirements.txt

然后使用 Python 3.7+ 运行脚本：

python3 {baseDir}/scripts/<script>.py <args>

如果看到针对 tos 的 ModuleNotFoundError，请重新安装依赖。

环境变量

此技能依赖 metadata 块中声明的 TOS 身份信息。常见的运行时变量如下：

环境变量	必需	描述
TOS_ACCESS_KEY	是	TOS 访问密钥 ID
TOS_SECRET_KEY	是	TOS 访问密钥
TOS_ENDPOINT	是	TOS 终端节点 URL
TOS_REGION	是	TOS 区域
TOS_BUCKET	是	存储文档的源存储桶
TOS_OBJECT_KEY	否	文档的源对象键。可使用 --key 覆盖
TOS_SECURITY_TOKEN	否	使用临时凭证时的 STS 会话令牌

快速开始（常见任务）

# Convert document to PDF
python3 {baseDir}/scripts/doc_preview_pdf.py --key report.docx --output preview.pdf

# Preview page 2 as PNG
python3 {baseDir}/scripts/doc_preview_png.py --key report.docx --page 2 --output page_2.png

# Preview page 2 as JPG
python3 {baseDir}/scripts/doc_preview_jpg.py --key report.docx --page 2 --output page_2.jpg

# Get total page count
python3 {baseDir}/scripts/doc_total_page.py --key report.docx --dest-type pdf

# Resolve HTML preview URL
python3 {baseDir}/scripts/doc_preview_html_url.py --key report.docx

# Batch export page range to TOS
python3 {baseDir}/scripts/doc_preview_process.py --key report.docx \
  --dest-type jpg --img-mode 1 --start-page 1 --end-page 3 \
  --saveas-bucket "output-bucket" --saveas-object "export/page_{Page}.jpg"

# Batch screenshot a PDF page range
python3 {baseDir}/scripts/doc_batch_screenshot.py --key test.pdf \
  --format png --start-page 1 --end-page 3 \
  --saveas-object "skill-test/doc/{Page}.png"

可用脚本

脚本	用途
scripts/doc_preview_pdf.py	将文档转换为 PDF 并保存到本地。
scripts/doc_preview_png.py	将单页渲染为 PNG。
scripts/doc_preview_jpg.py	将单页渲染为 JPG。
scripts/doc_total_page.py	通过 x-tos-total-page 标头读取总页数。
scripts/doc_preview_html_url.py	获取最终的 HTML 预览 URL（跟随重定向并提取令牌）。
scripts/doc_preview_process.py	通用文档预览脚本，可全面控制参数；支持 TOS 到 TOS 的导出。
scripts/doc_preview_params.py	用于一致构建 x-tos-doc-* 查询参数的辅助库。
scripts/doc_batch_screenshot.py	通过文档预览批处理模式将 PDF 页面批量导出为图像。

所有脚本都支持使用 --key 覆盖 TOS_OBJECT_KEY。结构化脚本还支持使用 --json 输出机器可读的结果，doc_preview_process.py 和 doc_total_page.py 支持使用 --dry-run 预览解析后的请求。运行任意脚本时加上 -h 可查看完整用法。

不适用范围

• 编辑文档内容（此技能仅支持只读预览和转换）。
• 与文档预览无关的通用对象存储任务。
• 不涉及 TOS 的本地办公文档转换工作流。

规则

• 身份验证：身份验证使用上方 metadata 块中声明的 TOS 身份信息。可在每个脚本中使用 --key 覆盖对象选择。
• 预签名 URL 模式：文档预览使用带有 x-tos-process=doc-preview 和 x-tos-doc-* 查询参数的预签名 URL，而非 get_object 的直接 process 关键字。请使用 doc_preview_params.py 一致地构建参数。
• 批量截图限制：doc_batch_screenshot.py 目前要求源对象为 PDF，并使用 {Page} 占位符将结果写回 TOS。
• 另存为编码：对于基于 doc-preview 查询参数的另存为操作，辅助脚本会自动对 x-tos-save-bucket 和 x-tos-save-object 进行 URL 安全 Base64 编码，以符合后端要求。
• 自定义域名说明：对于 2024 年 1 月 3 日之后创建的存储桶，在线 HTML 预览可能需要使用自定义域名，而非默认的 TOS 域名。
• 参数权威来源：火山引擎 TOS 官方文档是完整 doc-preview 参数矩阵的权威来源。如有疑问，请查阅 REFERENCE.md。
• 语言：使用用户偏好的语言回复。

延伸阅读

• 设置和环境：README.md
• 参数参考：REFERENCE.md
• 端到端工作流：WORKFLOWS.md