@acedatacloud/skills 2026.615.0 → 2026.620.1

package/AGENTS.md

@@ -31,6 +31,7 @@ Skills are located in the `skills/` directory (also mirrored to `.agents/skills/
 - **google-search** — Search the web, images, news, maps, places, and videos via Google
 - **face-transform** — Face analysis, beautification, age/gender transform, swap, cartoon
 - **short-url** — Create and manage short URLs
+- **onepage-pdf** — Convert an HTML page into one tall single-page PDF (local; no API token; needs Python + pymupdf + Chrome/Edge)
 - **acedatacloud-api** — API usage guide — authentication, SDKs, error handling
 
 ## Authentication

package/README.md

@@ -50,6 +50,7 @@ Compatible with **30+ AI coding agents** via the [agentskills.io](https://agents
 | [google-search](skills/google-search/) | Search the web, images, news, maps, places, and videos via Google |
 | [face-transform](skills/face-transform/) | Face analysis, beautification, age/gender transform, swap, cartoon |
 | [short-url](skills/short-url/) | Create and manage short URLs |
+| [onepage-pdf](skills/onepage-pdf/) | Convert an HTML page into one tall single-page PDF — no pagination breaks (local, no token) |
 | [acedatacloud-api](skills/acedatacloud-api/) | API usage guide — authentication, SDKs, error handling |
 
 ### Connectors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.615.0",
+  "version": "2026.620.1",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/cos-upload/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: cos-upload
+description: Upload a local file to AceData Cloud CDN and get back a public URL. Use whenever you produce a local artifact (image, audio, video, doc) that another API needs as a URL, or that you need to return/persist (e.g. feed a generated image into an image-to-video API, or publish a finished video).
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_PLATFORM_TOKEN (see _shared/authentication.md). Some runtimes instead provide a bundled uploader — prefer that when present.
+---
+
+# Upload a file → AceData CDN URL
+
+Turn a local file into a public `https://cdn.acedata.cloud/...` URL.
+
+## Upload (multipart, synchronous)
+
+```bash
+curl -s -X POST https://platform.acedata.cloud/api/v1/files/ \
+  -H "Authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
+  -F "file=@/path/to/video.mp4"
+```
+
+Response:
+
+```json
+{"file_url": "https://cdn.acedata.cloud/7f849b80b9.mp4"}
+```
+
+→ use `file_url`. One file per request (loop for several).
+
+## When to use
+
+- **Feed a generated asset into another API by URL** — e.g. upload a gpt-image-2 still, then pass its URL to `seedance` / `kling` image-to-video.
+- **Publish/return a finished artifact** (final video, cover image).
+- **Persist intermediate artifacts** so a later run can re-download and continue.
+
+## Notes
+
+- Auth uses the **platform token** (`ACEDATACLOUD_PLATFORM_TOKEN`), not the per-service API token — the files endpoint is on `platform.acedata.cloud`, not `api.acedata.cloud`.
+- If your runtime ships a bundled uploader (e.g. a worker that owns the storage creds), prefer it — it avoids handling the platform token directly.
+- The returned URL is CDN-served and stable; safe to store and re-download later.

package/skills/fish-audio/SKILL.md

@@ -1,99 +1,83 @@
 ---
 name: fish-audio
-description: Generate AI audio and synthesize voices with Fish Audio via AceDataCloud API. Use when creating text-to-speech audio, synthesizing voices, or generating audio content. Supports multiple voice models and TTS capabilities.
+description: Generate AI text-to-speech audio and clone voices with Fish Audio via AceDataCloud API. Use when creating voiceover/narration audio (TTS), synthesizing speech, or cloning a reference voice. Chinese + multilingual.
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 compatibility: Requires ACEDATACLOUD_API_TOKEN in .env file (see _shared/authentication.md).
 ---
 
-# Fish Audio — Voice & Audio Synthesis
+# Fish Audio — Text-to-Speech & Voice Cloning
 
-Generate AI audio and synthesize voices through AceDataCloud's Fish Audio API.
+Generate narration / voiceover and clone voices through AceDataCloud's Fish Audio API.
 
 > **Setup:** See [authentication](../_shared/authentication.md) for token setup.
 
-## Quick Start
+## Quick Start (TTS — synchronous, ~3s)
 
 ```bash
 curl -X POST https://api.acedata.cloud/fish/audios \
   -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"prompt": "Hello, this is a demonstration of AI voice synthesis."}'
+  -d '{"action":"speech","model":"fish-tts","voice_id":"543e4181d81b4ef6874b0e8fbdf27c78","prompt":"你好,欢迎使用 AceData Cloud。"}'
 ```
 
-> **Async:** See [async task polling](../_shared/async-tasks.md). Poll via `POST /fish/tasks` with `{"id": "..."}`.
+Response (synchronous — no polling needed for `speech`):
+
+```json
+{"success": true, "data": [{"audio_url": "https://platform.r2.fish.audio/task/....mp3"}]}
+```
+
+→ download `data[0].audio_url`. `voice_id` is **required**. A good default Mandarin
+news-anchor voice is **`543e4181d81b4ef6874b0e8fbdf27c78`**.
 
 ## Endpoints
 
 | Endpoint | Purpose |
 |----------|---------|
-| `POST /fish/audios` | Generate audio from text or parameters |
-| `POST /fish/voices` | Voice synthesis and cloning |
-| `POST /fish/tasks` | Poll task status |
+| `POST /fish/audios` | TTS (`action: "speech"`) — synchronous |
+| `POST /fish/voices` | List / register (clone) voices |
 
 ## Workflows
 
-### 1. Text-to-Speech
+### 1. Text-to-Speech (the common case)
 
 ```json
 POST /fish/audios
 {
-  "prompt": "The quick brown fox jumps over the lazy dog.",
-  "voice_id": "default"
+  "action": "speech",
+  "model": "fish-tts",
+  "voice_id": "543e4181d81b4ef6874b0e8fbdf27c78",
+  "prompt": "你的旁白文本。"
 }
 ```
 
-### 2. Voice Cloning — Register a Voice
-
-Upload a reference audio to create a cloneable voice.
+### 2. Clone a voice from a reference sample
 
 ```json
 POST /fish/voices
 {
   "voice_url": "https://example.com/reference-voice.mp3",
   "title": "My Custom Voice",
-  "description": "Clear, neutral-toned speaker for TTS",
-  "image_url": "https://example.com/avatar.jpg"
-}
-```
-
-### 3. Text-to-Speech with Cloned Voice
-
-```json
-POST /fish/audios
-{
-  "prompt": "Welcome to our platform.",
-  "voice_id": "<voice_id from POST /fish/voices>"
+  "description": "Clear, neutral-toned speaker"
 }
 ```
 
-## Parameters
-
-### `/fish/audios`
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `prompt` | string | Text to synthesize into speech |
-| `voice_id` | string | Voice model or cloned voice ID to use |
-| `model` | string | TTS model (e.g., `"speech-1.5"`, `"speech-1.5-hd"`) |
-| `action` | string | Operation type (e.g., `"generate"`) |
-| `callback_url` | string | Webhook URL for async delivery |
+Then pass the returned id as `voice_id` in workflow 1.
 
-### `/fish/voices`
+## Parameters — `/fish/audios`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `voice_url` | string | Reference audio URL for voice cloning |
-| `title` | string | Display title for the cloned voice |
-| `description` | string | Description of the voice |
-| `image_url` | string | Cover image URL for the voice |
-| `callback_url` | string | Webhook URL for async delivery |
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | string | yes | Use `"speech"` for TTS |
+| `model` | string | yes | `"fish-tts"` |
+| `voice_id` | string | yes | A Fish reference/cloned voice id (default Mandarin: `543e4181d81b4ef6874b0e8fbdf27c78`) |
+| `prompt` | string | yes | Text to synthesize |
 
 ## Gotchas
 
-- Pricing is based on **byte count** of the generated audio
-- Voice cloning requires a clear reference audio sample
-- Text-to-speech supports multiple languages automatically
-- Use the `/fish/voices` endpoint to register a reference audio and receive a `voice_id` for TTS
+- **TTS (`action:"speech"`) is synchronous** — the response carries `data[0].audio_url`; do NOT poll `/fish/tasks` for it.
+- `voice_id` is **required** — a bare `{"prompt": "..."}` returns `400 voice_id is required when action is speech`.
+- `model` must be `"fish-tts"` for speech (NOT `speech-1.5`); sending a different model returns `400 model is invalid if action is speech`.
+- Pricing is based on the **byte count** of the generated audio. Multilingual is automatic.

package/skills/gpt-image-2/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gpt-image-2
+description: Generate and EDIT images with OpenAI gpt-image-2 via AceDataCloud API. Use when you need high-fidelity images from a prompt, or to edit/composite existing images (e.g. fuse a real logo/QR/screenshot into a scene, keep characters consistent, restyle). Strong at legible text and faithful editing.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_API_TOKEN in .env file (see _shared/authentication.md).
+---
+
+# gpt-image-2 — Image Generation & Editing
+
+OpenAI `gpt-image-2` through AceDataCloud. Two endpoints, both **synchronous** (return image url(s) directly). Its standout is **editing**: feed real images (logos, QR codes, product shots, screenshots) and it composites/restyles them faithfully — great for on-brand video assets and character consistency.
+
+> **Setup:** See [authentication](../_shared/authentication.md) for token setup.
+
+## 1. Generate (text → image)
+
+```bash
+curl -X POST https://api.acedata.cloud/openai/images/generations \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-image-2","prompt":"a clean dark tech hero background with a glowing API hub, lots of negative space","size":"1792x1024","n":1}'
+```
+
+## 2. Edit / composite (images + prompt → image)  ← the powerful one
+
+Multipart. Pass one or more source images via repeated `image[]` (local files with
+`@`, or URLs). Use it to **fuse a real logo/QR into a generated scene**, keep a subject
+consistent across scenes, or restyle a screenshot.
+
+```bash
+curl -X POST https://api.acedata.cloud/openai/images/edits \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+  -F "model=gpt-image-2" \
+  -F "prompt=Place this logo crisply in the top-left on the tech background; keep the logo's exact colors and shape." \
+  -F "image[]=@background.png" \
+  -F "image[]=@logo.png" \
+  -F "size=1792x1024" \
+  -F "n=1"
+```
+
+Response (both endpoints): `{"data":[{"url":"https://...png"}]}` → download `data[0].url`.
+
+## Sizes
+
+`size` is `WxH` (a preset) or `"auto"`. Common presets:
+
+| Aspect | Sizes |
+|---|---|
+| 16:9 | `1792x1024` (HD), `2048x1152`, `3840x2160` (4K) |
+| 9:16 | `1024x1792`, `1152x2048`, `2160x3840` |
+| 1:1 | `1024x1024`, `2048x2048`, `4096x4096` |
+
+(Omit `size` or use `"auto"` to let the model pick. Invalid sizes 400.)
+
+## Tips
+
+- **Editing keeps things faithful** — to place a logo/QR exactly, pass it as one of the
+  `image[]` and say "keep its exact colors/shape, do not redraw it".
+- For **character/scene consistency** across video beats, generate one hero image, then
+  `edits` it per beat instead of regenerating from scratch.
+- Text in images renders legibly — good for titles/labels you don't want to overlay in HTML.
+- Both endpoints are synchronous; no `/tasks` polling.

package/skills/onepage-pdf/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XNTJ LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/onepage-pdf/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: onepage-pdf
+description: Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.
+license: MIT
+metadata:
+  author: xntj-ai
+  version: "1.0"
+  source: https://github.com/xntj-ai/onepage-pdf
+compatibility: No API token required. Requires Python 3.10+ with `pymupdf` (`pip install pymupdf`) and a local Chrome or Edge browser. Runs fully offline against local HTML — does not call api.acedata.cloud.
+---
+
+# onepage-pdf
+
+> Vendored from [github.com/xntj-ai/onepage-pdf](https://github.com/xntj-ai/onepage-pdf)
+> by 张拼拼 · XNTJ, under the MIT License. See [LICENSE](LICENSE).
+
+Render HTML to one tall PDF page via headless Chrome, then crop the page to the
+real content height with PyMuPDF. Height is never predicted (print layout is
+not screen layout); it is measured after rendering, which is exact.
+
+**Requires:** Python with `pymupdf`, plus a local Chrome or Edge. No API token.
+
+## Workflow
+
+### 1. Inspect the source HTML first
+
+Read the HTML and check four things; they decide whether `--extra-css` is needed:
+
+1. **Responsive breakpoints.** Print media queries evaluate against the default
+   paper width (~741px), NOT the `@page` size. Any `@media (max-width: N)` with
+   N ≥ 741 will fire during print and collapse the desktop layout. For each such
+   rule, write an override locking the desktop value with `!important`
+   (e.g. `.grid{grid-template-columns:repeat(3,1fr)!important}`).
+2. **Glassmorphism.** `backdrop-filter` blur is silently dropped in PDF output.
+   If glass elements sit on busy backgrounds, add a print fallback:
+   `.glass{backdrop-filter:none!important;background:rgba(255,255,255,.88)!important}`.
+3. **Scroll-reveal animations.** Common class patterns (`fade*`, `reveal*`,
+   `animate*`, `aos`) are forced visible automatically. Anything else that
+   starts at `opacity:0` needs an explicit `opacity:1!important` override.
+4. **vh/vw sizing.** Viewport units resolve against the page area in print and
+   drift ~1%; a `min-height:100vh` hero becomes ~187in tall on the bedrock
+   page. Override such rules with fixed px values.
+
+Put all overrides in one CSS file and pass it via `--extra-css`.
+
+### 2. Convert
+
+Paths below are relative to this skill directory.
+
+```bash
+python scripts/onepage_pdf.py input.html -o output.pdf --width 1280 \
+    [--extra-css fixes.css] [--replace subs.json --forbid words.txt]
+```
+
+- `--width`: match the design width of the page (snapped to 8px; non-8px
+  page sizes hit MediaBox rounding bugs that spawn phantom pages).
+- `--replace`: JSON `[["old","new"], ...]`, applied in order — put longer /
+  more specific strings first. Use for redaction before publishing.
+- `--forbid`: one word per line; the script aborts if any survives in the
+  HTML or in the final PDF text layer. Always pair with `--replace`.
+- `--crop pixel`: switch to raster row-scanning if the vector crop misjudges
+  (e.g. a decorative element painted taller than the real content).
+
+The script self-handles: oversized-bedrock rendering with auto-retry on
+overflow, content cropping (MediaBox + CropBox rewritten identically for
+viewer compatibility), CJK-safe output paths, single-page assertion.
+
+A bundled example lives in `examples/` — try it end to end:
+
+```bash
+python scripts/onepage_pdf.py examples/demo.html -o /tmp/demo.pdf \
+    --width 1280 --extra-css examples/demo-fixes.css
+```
+
+### 3. Verify
+
+The script prints `OK 1 page, WxHpt`. Then:
+
+1. Render a thumbnail and eyeball it (layout intact, no collapsed grids,
+   backgrounds present, nothing cut at the bottom):
+   ```python
+   import pymupdf
+   doc = pymupdf.open("output.pdf")
+   doc[0].get_pixmap(dpi=40).save("check.png")
+   ```
+2. If redaction was used, the forbid check already ran against the PDF text;
+   still spot-check the rendered image for sensitive content in raster form.
+3. Heed the script warnings: heights above 14400pt break Acrobat (Chrome,
+   Firefox and WeChat preview are fine); "content nearly fills the bedrock"
+   means inspect the tail for truncation.
+
+## Troubleshooting and mechanics
+
+Read [references/mechanics.md](references/mechanics.md) when output looks wrong
+(collapsed layout, missing backgrounds, blank page, phantom second page, blurry
+or missing CJK glyphs) — it documents the Chrome print-rendering rules this
+tool is built around, plus the CDP-based alternative route.

package/skills/onepage-pdf/examples/demo-fixes.css

@@ -0,0 +1,5 @@
+/* lock the 900px breakpoint back to desktop (print MQ evaluates at ~741px) */
+.card-grid { grid-template-columns: repeat(3, 1fr) !important; }
+.hero h1 { font-size: 56px !important; }
+/* glassmorphism: backdrop-filter blur is dropped in PDF — solidify the card */
+.glass { backdrop-filter: none !important; background: rgba(255, 255, 255, .88) !important; }

package/skills/onepage-pdf/examples/demo.html

@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<title>示例提案 — 星尘咖啡烘焙工坊数字化方案</title>
+<style>
+  :root { --accent: #b45309; --ink: #1f2937; }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: "Noto Sans SC", "Microsoft YaHei", sans-serif;
+    color: var(--ink);
+    background: linear-gradient(175deg, #fdf6ec 0%, #f3e7d3 45%, #e8d5b5 100%);
+    width: 1280px; margin: 0 auto;
+  }
+  .hero { padding: 120px 80px 80px; }
+  .hero h1 { font-size: 56px; font-weight: 700; letter-spacing: 2px; }
+  .hero p { font-size: 20px; color: #6b7280; margin-top: 24px; max-width: 720px; }
+  section { padding: 64px 80px; }
+  h2 { font-size: 32px; margin-bottom: 32px; border-left: 6px solid var(--accent); padding-left: 18px; }
+  .card-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px; }
+  .card {
+    background: #fff; border-radius: 16px; padding: 28px;
+    box-shadow: 0 8px 24px rgba(31, 41, 55, .08);
+  }
+  .card h3 { font-size: 20px; margin-bottom: 12px; color: var(--accent); }
+  .card p { font-size: 15px; line-height: 1.8; color: #4b5563; }
+  .glass {
+    margin-top: 48px; padding: 36px; border-radius: 20px;
+    background: rgba(255, 255, 255, .35);
+    backdrop-filter: blur(14px);
+    border: 1px solid rgba(255, 255, 255, .6);
+  }
+  .fade-in { opacity: 0; transform: translateY(24px); transition: all .8s ease; }
+  table { width: 100%; border-collapse: collapse; background: #fff; border-radius: 12px; overflow: hidden; }
+  th, td { padding: 14px 20px; text-align: left; border-bottom: 1px solid #f3f4f6; font-size: 15px; }
+  th { background: var(--ink); color: #fff; font-weight: 500; }
+  footer { padding: 48px 80px 96px; color: #9ca3af; font-size: 13px; }
+  /* breakpoint >= 741px: fires during print unless locked via --extra-css */
+  @media (max-width: 900px) {
+    .card-grid { grid-template-columns: 1fr; }
+    .hero h1 { font-size: 36px; }
+  }
+</style>
+</head>
+<body>
+  <div class="hero fade-in">
+    <h1>星尘咖啡烘焙工坊<br>数字化升级方案</h1>
+    <p>虚构示例：本页面用于演示 onepage-pdf 的转换效果 — 渐变背景、三列卡片栅格、玻璃拟态、滚动渐入动画与中文排版，全部应在单页 PDF 中保持桌面布局。</p>
+  </div>
+
+  <section class="fade-in">
+    <h2>一、现状与目标</h2>
+    <div class="card-grid">
+      <div class="card"><h3>门店运营</h3><p>三家门店的点单、库存与会员数据彼此孤立，月度对账依赖人工汇总表格，平均耗时两个工作日，且错漏率随单量增长而上升。</p></div>
+      <div class="card"><h3>烘焙生产</h3><p>烘焙排期靠经验估算，生豆损耗未量化。引入批次追踪后，可将每炉烘焙曲线与杯测评分关联，沉淀为可复用的烘焙档案。</p></div>
+      <div class="card"><h3>会员增长</h3><p>现有会员体系仅有储值功能，缺少消费行为分析。目标是基于购买频次与口味偏好做精准触达，提升复购率至行业均值以上。</p></div>
+    </div>
+    <div class="glass">
+      <h3>方案总览（玻璃拟态卡片）</h3>
+      <p>分三期推进：第一期打通点单与库存数据流，第二期上线烘焙批次追踪，第三期构建会员画像与自动化营销。每期交付均含验收标准与回滚预案。</p>
+    </div>
+  </section>
+
+  <section class="fade-in">
+    <h2>二、实施排期</h2>
+    <table>
+      <tr><th>阶段</th><th>内容</th><th>周期</th><th>验收标准</th></tr>
+      <tr><td>一期</td><td>点单系统与库存打通</td><td>4 周</td><td>日结报表自动生成，误差为零</td></tr>
+      <tr><td>二期</td><td>烘焙批次追踪上线</td><td>6 周</td><td>每炉烘焙档案可检索、可对比</td></tr>
+      <tr><td>三期</td><td>会员画像与营销自动化</td><td>8 周</td><td>触达转化率较基线提升 20%</td></tr>
+    </table>
+  </section>
+
+  <section class="fade-in">
+    <h2>三、投入与回报</h2>
+    <div class="card-grid">
+      <div class="card"><h3>一次性投入</h3><p>系统搭建与数据迁移共计十二万元，含三个月驻场支持。所有数据资产归属工坊，供应商不留存任何经营数据副本。</p></div>
+      <div class="card"><h3>年度运维</h3><p>云资源与维护费用每年两万四千元，按季度支付。合同期内功能迭代不另行收费，重大版本升级提前一个月公示变更说明。</p></div>
+      <div class="card"><h3>预期回报</h3><p>按当前单量测算，对账人力成本年省约五万元；会员复购提升带来的增量收入预计在第二年覆盖全部投入。</p></div>
+    </div>
+  </section>
+
+  <footer>本文档为 onepage-pdf 演示用虚构内容 · 星尘咖啡烘焙工坊并不存在 · 生成于示例管线</footer>
+
+  <script>
+    // scroll-reveal: in a headless print pass these never fire — the injected
+    // CSS must force .fade-in visible or the PDF renders blank blocks
+    const io = new IntersectionObserver(es => es.forEach(e => {
+      if (e.isIntersecting) { e.target.style.opacity = 1; e.target.style.transform = 'none'; }
+    }));
+    document.querySelectorAll('.fade-in').forEach(el => io.observe(el));
+  </script>
+</body>
+</html>

package/skills/onepage-pdf/references/mechanics.md

@@ -0,0 +1,149 @@
+# Chrome print-rendering mechanics
+
+Why this tool crops instead of calculating, and what to do when output looks
+wrong. Findings verified against Chromium source / specs / production code
+(Gotenberg), June 2026.
+
+## Contents
+
+- [Why height cannot be predicted](#why-height-cannot-be-predicted)
+- [Media queries vs @page — two viewports](#media-queries-vs-page--two-viewports)
+- [The 1.5x hidden shrink](#the-15x-hidden-shrink)
+- [Unit rounding and the phantom page](#unit-rounding-and-the-phantom-page)
+- [PDF size limits](#pdf-size-limits)
+- [Fidelity losses in PDF output](#fidelity-losses-in-pdf-output)
+- [Resource readiness](#resource-readiness)
+- [CJK pitfalls](#cjk-pitfalls)
+- [Crop internals](#crop-internals)
+- [Alternative route: CDP measured height](#alternative-route-cdp-measured-height)
+
+## Why height cannot be predicted
+
+Screen-measured `scrollHeight` does not match the printed layout height:
+
+- `page.pdf()` / `--print-to-pdf` render with **print** media CSS; measuring on
+  screen measures a different layout.
+- Print media queries evaluate against a different width than the layout width
+  (next section), shifting breakpoints.
+- Web fonts arriving after measurement change line heights.
+- The px→inch→pt conversion chain rounds non-monotonically (puppeteer#2278).
+
+Hence: render onto an oversized bedrock page, measure the result, crop.
+
+## Media queries vs @page — two viewports
+
+Per css-page-3 §7.1, media queries **must ignore `@page size`** (anti-cycle
+rule) and evaluate against the default paper. Measured in Chrome: MQ width is
+the default paper's page area, **~741px** (US Letter minus default margins),
+regardless of any `@page` declaration.
+
+Meanwhile vw/vh resolve against the **first page area** — which DOES honor
+`@page size` — with ~1% drift from device-unit rounding. So one document
+evaluates MQ at 741px and vw at the @page width simultaneously. Container
+queries follow the laid-out container and are the only reliable responsive
+mechanism in print.
+
+Practical rule: lock every breakpoint ≥741px to its desktop value via
+`--extra-css`, and replace vh/vw sizing with px.
+
+## The 1.5x hidden shrink
+
+`printingMaximumShrinkFactor = 1.5` in Blink: if the widest unbreakable content
+exceeds the page width, Chrome relayouts and **scales the whole document down
+by up to 1.5x** to fit (beyond that it clips). One overflowing element changes
+the scale of everything. Keep actual content width ≤ `--width`.
+
+## Unit rounding and the phantom page
+
+Chrome converts px → inches → pt with rounding errors up to ~0.2% (MediaBox
+73pt becomes 72.959999). A height short by a fraction of a pt spills one line
+onto a second page. Mitigations used here:
+
+- widths/heights snapped to 8px (8px = 6pt exactly);
+- the bedrock is intentionally huge, so rounding never matters at render time;
+- Gotenberg's equivalent trick for the CDP route is `pageRanges: "1"`.
+
+## PDF size limits
+
+- 14400pt (200in, ≈19200px) is the **Acrobat implementation limit** from ISO
+  32000-1 Annex C — not a format limit. PDF 2.0 drops it.
+- Chrome happily writes larger pages (verified: 22500pt, no clamp, no
+  UserUnit). Chrome/Firefox/PDFium/WeChat render them; old Acrobat may refuse.
+- The script warns when output exceeds 14400pt; that's a compatibility note,
+  not an error.
+
+## Fidelity losses in PDF output
+
+| Feature | Behavior in PDF | Fix |
+|---|---|---|
+| `backdrop-filter` blur | **Silently dropped** (crbug 40895818); translucent bg layer survives | Print fallback: `backdrop-filter:none` + near-opaque `background` |
+| `background-attachment: fixed` | Painted on page 1 only, off-spec | Injected CSS forces `scroll` |
+| `box-shadow` | Fine, stays vector | — |
+| Perspective transforms | Rendered as identity (SkPDF) | Avoid in print |
+| Element behind CSS `filter`/image filter | Rasterized; text loses selectability | Avoid filters on text containers |
+| Backgrounds in general | Need `print-color-adjust: exact` (injected) | — |
+
+## Resource readiness
+
+CLI `--print-to-pdf` waits for the `load` event only — not fonts, not
+JS-injected content. The script passes:
+
+- `--virtual-time-budget=10000`: fast-forwards timer-driven JS (experimental;
+  does not wait for slow networks or CPU);
+- `--run-all-compositor-stages-before-draw`: ensures rasterization completes
+  before capture.
+
+If fonts or late-loading images still miss: raise `--virtual-time`, inline
+resources as data URLs, or preload fonts in `<head>`. Note headless
+`--print-to-pdf` silently refuses external resources referenced from inside
+`@page` margin-box CSS — inline those as data URLs.
+
+`loading="lazy"` images render fine in current headless print (verified Chrome
+149); for older Chrome force `loading="eager"` via `--replace`.
+
+## CJK pitfalls
+
+- Set `<html lang="zh-CN">` — without it, fontconfig on Linux may pick the
+  Thin weight of Noto CJK for body text.
+- Docker/CI images need `fonts-noto-cjk` installed or all CJK renders as tofu.
+- CJK fonts often ship Regular only; `font-weight:600+` triggers synthetic
+  bold that looks smeared in PDF. Load real weight files (e.g. Noto Sans SC
+  500/700).
+- Webfonts without CJK glyphs fall back to system fonts on screen but may
+  embed nothing in the PDF — Acrobat shows missing glyphs. Declare a CJK
+  fallback explicitly in `font-family`.
+
+## Crop internals
+
+- Content bottom comes from `page.get_bboxlog()` — a render-level command log
+  covering text, images, vector paths, and contents of Form XObjects (the
+  APIs `get_text('blocks')` + `get_drawings()` miss XObject internals and
+  inline images). `ignore-text` (invisible text) entries are skipped, as are
+  fills taller than 97% of the page (the body background painted across the
+  whole bedrock).
+- Pixel mode (`--crop pixel`) rasterizes at 24dpi and scans rows bottom-up for
+  horizontal variance > threshold; vertical gradients are horizontally uniform
+  so they don't count as content. Use it when vector mode keeps decorative
+  geometry that extends below the real content.
+- Both MediaBox and CropBox are rewritten to the same rect via `xref_set_key`
+  in raw PDF (y-up) coordinates. This avoids PyMuPDF's `set_mediabox` side
+  effect (it deletes CropBox) and the viewer ambiguity between viewers that
+  honor MediaBox (some mobile/embedded viewers) vs CropBox (Acrobat, pdf.js).
+
+## Alternative route: CDP measured height
+
+Gotenberg 8's production `singlePage=true` implementation (tasks.go):
+
+```
+Emulation.setEmulatedMedia(media="print")
+m = Page.getLayoutMetrics()              # cssContentSize is the authoritative height
+Page.printToPDF(paperWidth = W/96,
+                paperHeight = m.cssContentSize.height/96,
+                marginTop=0, ..., pageRanges="1")   # "1" discards rounding spill
+```
+
+Pros: no bedrock, no crop, exact MediaBox at render time. Cons: requires a CDP
+client (websocket) instead of a bare CLI call; lazy-load / viewport-relative
+layouts can still mismeasure (gotenberg#1046). This tool deliberately stays on
+the CLI+crop route for zero runtime dependencies beyond PyMuPDF; switch to CDP
+only if a page class consistently defeats the crop heuristics.

package/skills/onepage-pdf/scripts/onepage_pdf.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""onepage-pdf: render an HTML file into a single continuous-page PDF (no pagination).
+
+Strategy: never *predict* the page height (screen layout != print layout, and the
+px->inch->pt conversion chain rounds non-monotonically). Instead render onto an
+oversized "bedrock" page, then measure the real content bottom with PyMuPDF's
+render-level bbox log and shrink MediaBox + CropBox to fit. Height is cropped,
+not calculated.
+
+Dependencies: PyMuPDF (pip install pymupdf) + a local Chrome or Edge.
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+from pathlib import Path
+
+try:
+    import pymupdf
+except ImportError:  # PyMuPDF < 1.24 exposes the legacy name only
+    import fitz as pymupdf
+
+BROWSERS = [
+    r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+]
+
+# Injected before </head>. The @page rule is the only official channel for paper
+# size in CLI headless mode (--print-to-pdf hardcodes preferCSSPageSize:true).
+# Width/height must be multiples of 8px: 8px = 6pt exactly, anything else risks
+# MediaBox rounding errors that spill content onto a phantom second page.
+PRINT_CSS = """
+<style data-onepage-pdf>
+  @page {{ size: {width}px {bedrock}px; margin: 0; }}
+  * {{
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+    animation: none !important;
+    transition: none !important;
+    background-attachment: scroll !important; /* fixed bg paints only page 1 */
+  }}
+  /* scroll-reveal patterns start at opacity:0 and never "enter the viewport"
+     during a headless print pass — force them visible */
+  [class*="fade"], [class*="reveal"], [class*="animate"], [class*="aos"],
+  [data-aos] {{
+    opacity: 1 !important;
+    transform: none !important;
+    visibility: visible !important;
+  }}
+{extra}
+</style>
+</head>"""
+
+ACROBAT_LIMIT_PT = 14400  # ISO 32000-1 Annex C; Chrome will exceed it happily
+
+
+def find_browser(explicit):
+    if explicit:
+        if Path(explicit).exists():
+            return explicit
+        sys.exit(f"browser not found: {explicit}")
+    for p in BROWSERS:
+        if Path(p).exists():
+            return p
+    found = shutil.which("chrome") or shutil.which("chromium") or shutil.which("msedge")
+    if found:
+        return found
+    sys.exit("no Chrome/Edge found; pass --chrome PATH")
+
+
+def align8(px):
+    return max(8, int(round(px / 8.0)) * 8)
+
+
+def apply_replacements(html, replace_file):
+    pairs = json.loads(Path(replace_file).read_text(encoding="utf-8"))
+    for old, new in pairs:  # order matters: longest/most specific first
+        html = html.replace(old, new)
+    return html
+
+
+def check_forbidden(text, forbid_file, where):
+    words = [w.strip() for w in Path(forbid_file).read_text(encoding="utf-8").splitlines() if w.strip()]
+    leaks = [w for w in words if w in text]
+    if leaks:
+        sys.exit(f"LEAK in {where}: {leaks}")
+    return len(words)
+
+
+def render(browser, html_path, pdf_path, width, virtual_time):
+    cmd = [
+        browser,
+        "--headless=new",
+        "--disable-gpu",
+        "--no-pdf-header-footer",
+        "--hide-scrollbars",
+        f"--window-size={width},2000",
+        f"--virtual-time-budget={virtual_time}",
+        "--run-all-compositor-stages-before-draw",
+        f"--print-to-pdf={pdf_path}",
+        html_path.as_uri(),
+    ]
+    subprocess.run(cmd, check=True, timeout=180,
+                   stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+def content_bottom_vector(page):
+    """Bottom edge (pt, from page top) via the render-level bbox log.
+
+    get_bboxlog() covers text, images, vector paths and unrolls Form XObjects —
+    the only single API that misses nothing. Full-page-height fills are the
+    body background painted across the whole bedrock page; skip them or the
+    union degenerates to the entire page.
+    """
+    page_h = page.rect.height
+    bottom = None
+    for kind, bbox in page.get_bboxlog():
+        if kind == "ignore-text":  # invisible text, must not drive the crop
+            continue
+        r = pymupdf.Rect(bbox)
+        if r.is_empty or r.is_infinite or r.height >= 0.97 * page_h:
+            continue
+        bottom = r.y1 if bottom is None else max(bottom, r.y1)
+    try:
+        for annot in page.annots():
+            bottom = annot.rect.y1 if bottom is None else max(bottom, annot.rect.y1)
+    except TypeError:
+        pass
+    return bottom
+
+
+def content_bottom_pixel(page, dpi=24, stdev_threshold=3.0):
+    """Fallback: rasterize and scan rows bottom-up for horizontal variance.
+
+    A vertical gradient background is horizontally uniform (variance ~0);
+    real content (text, cards, rules) breaks horizontal uniformity.
+    """
+    pix = page.get_pixmap(dpi=dpi, colorspace=pymupdf.csGRAY)
+    w, h, buf = pix.width, pix.height, pix.samples
+    threshold = stdev_threshold ** 2
+    for row in range(h - 1, -1, -1):
+        line = buf[row * w:(row + 1) * w]
+        mean = sum(line) / w
+        if sum((b - mean) ** 2 for b in line) / w > threshold:
+            return (row + 1) / dpi * 72.0
+    return None
+
+
+def crop_to_content(doc, padding_px, crop_mode):
+    page = doc[0]
+    bottom = None
+    if crop_mode != "pixel":
+        bottom = content_bottom_vector(page)
+    if bottom is None:
+        bottom = content_bottom_pixel(page)
+    if bottom is None:
+        sys.exit("could not locate any content on the page")
+    new_h = min(page.rect.height, bottom + padding_px * 0.75)  # px -> pt
+    # Rewrite both boxes via xref in raw PDF coordinates (y-up) — sidesteps
+    # PyMuPDF's top-left flip ambiguity and the set_mediabox side effect of
+    # deleting CropBox. Some viewers read MediaBox, some CropBox ∩ MediaBox;
+    # writing both identically removes the difference.
+    mb = page.mediabox
+    box = f"[{mb.x0:.2f} {mb.y1 - new_h:.2f} {mb.x1:.2f} {mb.y1:.2f}]"
+    doc.xref_set_key(page.xref, "MediaBox", box)
+    doc.xref_set_key(page.xref, "CropBox", box)
+    return new_h
+
+
+def main():
+    ap = argparse.ArgumentParser(description="HTML -> single continuous-page PDF")
+    ap.add_argument("input", help="source HTML file")
+    ap.add_argument("-o", "--output", required=True, help="destination PDF")
+    ap.add_argument("--width", type=int, default=1280,
+                    help="page width in CSS px (default 1280, snapped to 8px)")
+    ap.add_argument("--bedrock", type=int, default=18000,
+                    help="initial oversized page height in px (default 18000)")
+    ap.add_argument("--padding", type=int, default=32,
+                    help="whitespace kept below content, px (default 32)")
+    ap.add_argument("--extra-css", help="CSS file appended to the injected print styles "
+                    "(breakpoint locks, glassmorphism fallbacks, ...)")
+    ap.add_argument("--replace", help="JSON file [[old,new],...] applied to the HTML "
+                    "before rendering (redaction / token substitution)")
+    ap.add_argument("--forbid", help="text file, one word per line; abort if any "
+                    "survives in the HTML or the final PDF text")
+    ap.add_argument("--crop", choices=["vector", "pixel"], default="vector",
+                    help="content-bottom detection (default vector, auto-falls back)")
+    ap.add_argument("--chrome", help="explicit browser executable")
+    ap.add_argument("--virtual-time", type=int, default=10000,
+                    help="--virtual-time-budget ms (default 10000)")
+    ap.add_argument("--max-retries", type=int, default=2,
+                    help="bedrock doublings when content overflows (default 2)")
+    ap.add_argument("--keep-temp", action="store_true")
+    args = ap.parse_args()
+
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except AttributeError:
+        pass
+
+    src = Path(args.input)
+    html = src.read_text(encoding="utf-8")
+    if args.replace:
+        html = apply_replacements(html, args.replace)
+    if args.forbid:
+        n = check_forbidden(html, args.forbid, "HTML after replacements")
+        print(f"forbid check (html): {n} words, clean")
+
+    width = align8(args.width)
+    extra = ""
+    if args.extra_css:
+        extra = Path(args.extra_css).read_text(encoding="utf-8")
+    if "</head>" not in html:
+        sys.exit("input HTML has no </head>; cannot inject print CSS")
+
+    browser = find_browser(args.chrome)
+    # Chrome writes PDFs unreliably to non-ASCII paths; stage everything in TEMP
+    workdir = Path(tempfile.gettempdir()) / f"onepage-pdf-{uuid.uuid4().hex[:8]}"
+    workdir.mkdir()
+    tmp_pdf = workdir / "out.pdf"
+
+    try:
+        bedrock = align8(args.bedrock)
+        for attempt in range(args.max_retries + 1):
+            injected = html.replace(
+                "</head>",
+                PRINT_CSS.format(width=width, bedrock=bedrock, extra=extra), 1)
+            tmp_html = workdir / "in.html"
+            tmp_html.write_text(injected, encoding="utf-8")
+            render(browser, tmp_html, tmp_pdf, width, args.virtual_time)
+            doc = pymupdf.open(tmp_pdf)
+            if doc.page_count == 1:
+                break
+            print(f"content overflowed {bedrock}px bedrock "
+                  f"({doc.page_count} pages); doubling")
+            doc.close()
+            bedrock = align8(bedrock * 2)
+        else:
+            sys.exit(f"still paginated after {args.max_retries} retries; "
+                     f"raise --bedrock explicitly")
+
+        new_h = crop_to_content(doc, args.padding, args.crop)
+        final = workdir / "final.pdf"
+        doc.save(final)
+        doc.close()
+
+        check = pymupdf.open(final)
+        page = check[0]
+        assert check.page_count == 1
+        w_pt, h_pt = page.rect.width, page.rect.height
+        if args.forbid:
+            text = "".join(p.get_text() for p in check)
+            check_forbidden(text, args.forbid, "final PDF text")
+            print("forbid check (pdf): clean")
+        check.close()
+
+        dest = Path(args.output)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(final, dest)
+
+        size_kb = dest.stat().st_size / 1024
+        print(f"OK 1 page, {w_pt:.0f}x{h_pt:.0f}pt "
+              f"({w_pt/72*96:.0f}x{h_pt/72*96:.0f}px), {size_kb:.0f} KB -> {dest}")
+        if h_pt > ACROBAT_LIMIT_PT:
+            print(f"warning: height {h_pt:.0f}pt exceeds the 14400pt Acrobat "
+                  f"limit; fine in Chrome/Firefox/WeChat, may fail in Acrobat")
+        if new_h >= bedrock * 0.75 * 0.985:
+            print("note: content nearly fills the bedrock; check the PDF tail "
+                  "for accidental truncation")
+    finally:
+        if args.keep_temp:
+            print(f"temp kept: {workdir}")
+        else:
+            shutil.rmtree(workdir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()