byted-tos-doc-process

# Volcengine TOS Document Process Preview and convert office documents stored in Volcengine TOS — PDF/PNG/JPG conversion, page count, HTML preview URL, and page-range export. ## Setup (once per environment) Install dependencies on first use: ```bash cd {baseDir} pip install -r {baseDir}/requirements.txt ``` Then run scripts with Python 3.7+: ```bash python3 {baseDir}/scripts/<script>.py <args> ``` If you see a `ModuleNotFoundError` for `tos`, reinstall dependencies. ## Environment Variables This skill relies on the TOS identity declared in the `metadata` block. Common runtime variables are: | Environment Variable | Required | Description | | --- | --- | --- | | `TOS_ACCESS_KEY` | Yes | TOS access key ID | | `TOS_SECRET_KEY` | Yes | TOS secret access key | | `TOS_ENDPOINT` | Yes | TOS endpoint URL | | `TOS_REGION` | Yes | TOS region | | `TOS_BUCKET` | Yes | Source bucket that stores the document | | `TOS_OBJECT_KEY` | No | Source object key of the document. Can be overridden with `--key` | | `TOS_SECURITY_TOKEN` | No | STS session token when using temporary credentials | ## Quick start (common tasks) ```bash # 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" ``` ## Available scripts | Script | Purpose | |--------|---------| | `scripts/doc_preview_pdf.py` | Convert document to PDF and save locally. | | `scripts/doc_preview_png.py` | Render a single page as PNG. | | `scripts/doc_preview_jpg.py` | Render a single page as JPG. | | `scripts/doc_total_page.py` | Read total page count via `x-tos-total-page` header. | | `scripts/doc_preview_html_url.py` | Resolve the final HTML preview URL (follows redirects and extracts tokens). | | `scripts/doc_preview_process.py` | Generic doc-preview with full parameter control; supports TOS-to-TOS export. | | `scripts/doc_preview_params.py` | Helper library to build `x-tos-doc-*` query parameters consistently. | | `scripts/doc_batch_screenshot.py` | Batch-export PDF pages as images through doc-preview batch mode. | All scripts support `--key` to override `TOS_OBJECT_KEY`. Structured scripts also support `--json` for machine-readable output, and `doc_preview_process.py` / `doc_total_page.py` support `--dry-run` to preview the resolved request. Run any script with `-h` for full usage. ## Out of scope - Editing document contents (this skill is read-only preview/conversion). - Generic object storage tasks unrelated to document preview. - Local office conversion workflows that do not involve TOS. ## Rules - **Authentication**: Authentication is provided by the TOS identity declared in the `metadata` block above. Object selection can be overridden per script with `--key`. - **Pre-signed URL pattern**: Document preview uses pre-signed URLs with `x-tos-process=doc-preview` and `x-tos-doc-*` query parameters, not the direct `process` keyword of `get_object`. Use `doc_preview_params.py` to build parameters consistently. - **Batch screenshot constraint**: `doc_batch_screenshot.py` currently requires a PDF source object and persists results back to TOS with a `{Page}` placeholder. - **Save-as encoding**: For `doc-preview` query-based save-as, the helper script automatically URL-safe-Base64 encodes `x-tos-save-bucket` and `x-tos-save-object` to match backend expectations. - **Custom domain note**: For buckets created after Jan 03, 2024, online HTML preview may require a custom domain rather than the default TOS domain. - **Parameter source of truth**: Official Volcengine TOS documentation is authoritative for the full `doc-preview` parameter matrix. When uncertain, check [REFERENCE.md](REFERENCE.md). - **Language**: Reply in the user's preferred language. ## Further reading - Setup and environment: [README.md](README.md) - Parameter reference: [REFERENCE.md](REFERENCE.md) - End-to-end workflows: [WORKFLOWS.md](WORKFLOWS.md)