Volcengine TOS 文档处理（byted-tos-doc-process）用于预览和转换存储在火山引擎 TOS 中的办公文档，涵盖 PDF/PNG/JPG 转换、页数读取、HTML 预览 URL 解析以及页面范围导出。该技能为只读的预览与转换工具，不涉及文档内容编辑。
一、用途 该技能面向存放在火山引擎 TOS 对象存储中的文档，提供在线预览与格式转换能力。它不处理与文档预览无关的通用对象存储任务，也不处理不涉及 TOS 的本地办公转换流程。
二、主要能力
- 将文档转换为 PDF 并保存到本地。
- 将单页渲染为 PNG 或 JPG。
- 通过 x-tos-total-page 头读取文档总页数。
- 解析最终的 HTML 预览 URL（跟随重定向并提取 token）。
- 通用 doc-preview，支持完整参数控制，并支持 TOS 到 TOS 的导出。
- 通过 doc-preview 批处理模式，将 PDF 页面批量导出为图片（批量截图，当前要求源对象为 PDF，并使用 {Page} 占位符将结果回存到 TOS）。
三、使用方式 首次使用时安装依赖：cd {baseDir} 后执行 pip install -r {baseDir}/requirements.txt。随后使用 Python 3.7+ 运行脚本，例如 python3 {baseDir}/scripts/<script>.py <args>。若出现 tos 的 ModuleNotFoundError，需重新安装依赖。 脚本包括：doc_preview_pdf.py（转 PDF 并本地保存）、doc_preview_png.py（单页 PNG）、doc_preview_jpg.py（单页 JPG）、doc_total_page.py（读取总页数）、doc_preview_html_url.py（解析 HTML 预览 URL）、doc_preview_process.py（通用 doc-preview，支持 TOS 到 TOS 导出）、doc_preview_params.py（构建 x-tos-doc-* 查询参数的辅助库）、doc_batch_screenshot.py（批量导出一组 PDF 页面为图片）。所有脚本支持 --key 覆盖 TOS_OBJECT_KEY；结构化脚本支持 --json 输出机器可读结果；doc_preview_process.py 与 doc_total_page.py 支持 --dry-run 预览已解析的请求；使用 -h 可查看完整用法。 环境变量方面，TOS_ACCESS_KEY、TOS_SECRET_KEY、TOS_ENDPOINT、TOS_REGION、TOS_BUCKET 为必需项，TOS_OBJECT_KEY 与 TOS_SECURITY_TOKEN 为可选项。
四、适用场景 适用于需要从 TOS 读取文档并进行在线预览、页面截图或格式转换的流程，例如生成 PDF/PNG/JPG 预览、获取文档页数、解析 HTML 预览链接，以及将指定页面范围批量导出回 TOS。
五、限制 该技能为只读预览/转换，不支持编辑文档内容；不处理与文档预览无关的通用对象存储任务；不处理不涉及 TOS 的本地办公转换工作流。文档预览使用带 x-tos-process=doc-preview 与 x-tos-doc-* 查询参数的预签名 URL，而非 get_object 的直接 process 关键字。批处理截图当前要求 PDF 源对象，并配合 {Page} 占位符回存 TOS。doc-preview 基于查询的 save-as 场景中，辅助脚本会自动对 x-tos-save-bucket 与 x-tos-save-object 进行 URL 安全的 Base64 编码。对于 2024 年 1 月 3 日之后创建的 bucket，在线 HTML 预览可能需要自定义域名而非默认 TOS 域名。完整的 doc-preview 参数以火山引擎 TOS 官方文档为准，不确定时可查阅 REFERENCE.md。
六、其它说明 认证由元数据块中声明的 TOS 身份提供，对象选择可用 --key 按脚本覆盖。设置与环境说明见 README.md，参数参考见 REFERENCE.md，端到端流程见 WORKFLOWS.md。