YeahPDF

After doctor, pick one runner for the rest of this conversation. Do not mix. Do not upload PDF bytes as an HTTP body. Do not invent /api/v1 curl for processing.

• Node 18+ ready (node scripts/ypdf.mjs doctor → status=ready): copy the Node column. No native CLI needed.
• Native CLI ready: copy the CLI column. If PATH lacks ypdf, run the binary= path doctor printed.

Before the first merge/convert/job in this conversation, run setup. If doctor already printed status=ready in this conversation, do not run doctor again before every job. Re-run doctor only when the runner is missing, quota fails, or the CLI reports 1101. Guest (no API key) is fine: ready does not mean the user logged in.

1. Check environment

From this skill directory, prefer the bundled Node runner (WorkBuddy has Node):

node scripts/ypdf.mjs doctor

If node is missing, use the native CLI doctor. Unix / macOS: bash scripts/doctor.sh. Windows: powershell -File scripts/doctor.ps1. If Windows blocks that file because it was downloaded, run Unblock-File scripts\doctor.ps1 in this directory and run the same command again.

Do not ask for an API key just because doctor is ready.

2. Install native CLI only if Node is missing (exit 2 or 5)

Skip this section when node scripts/ypdf.mjs doctor already printed status=ready.

Do not invent a tarball or zip name with a star in place of the version, and do not run tar / Expand-Archive / mv with a glob.

Unix scripts/install.sh detects macOS/Linux, resolves the latest GitHub release, and uses the exact versioned filename. It replaces an existing writable ypdf on PATH, otherwise installs to ~/.local/bin (no sudo). Windows scripts/install.ps1 installs ypdf.exe to %LOCALAPPDATA%\ypdf\bin. Need 0.1.4 or newer.

From this skill directory:

bash scripts/install.sh

Windows:

powershell -File scripts/install.ps1

If Windows blocks that file because it was downloaded, run Unblock-File scripts\install.ps1 in this directory and run the same command again.

If the agent sandbox cannot reach GitHub or write the install prefix, ask the user to run that same command in their own terminal. Do not replace it with a hand-typed download.

Then re-run the same doctor script. Prefer the binary= path doctor printed whenever ypdf is not on PATH.

If the install script is missing or --plan cannot resolve a release, open https://github.com/yeahpdf/ypdf-cli/releases/latest and download the asset whose name ends with the target= triple from doctor. Copy the filename from the release page verbatim.

Wait until doctor no longer exits 2 or 5. Do not go to section 3 just because the user has no API key. Guest quota is enough until a job returns 13xx or 「需要登录后使用」.

2b. Optional CLI update (user must agree)

Do not check for updates before every job. Do not run ypdf upgrade (without --check) on your own. The Node runner has no binary to overwrite; node scripts/ypdf.mjs upgrade --check only explains that.

When the user asks about updating a native CLI, or after they already have a working native CLI (status=ready) and you want to mention a newer build:

1. Run ypdf upgrade --check only (use the binary= path if PATH lacks it). If that subcommand is missing, the installed CLI is too old: tell them the install script can replace it, and ask first.
2. If output has status=up_to_date, say so and continue.
3. If status=update_available, tell them current= vs latest= and ask whether to upgrade. Wait for an explicit yes. If they say no, keep the current CLI and continue the PDF task.
4. Only after they say yes, run ypdf upgrade (same binary path). If the sandbox cannot write the binary or prints status=need_write, ask them to run that same command in their own terminal. Do not invent a tarball name.

3. API token (only after guest quota is exhausted)

Do not ask the user to paste a ypdf_ key into the chat. Do not open this section before the first job. Guest mode shares the website's unpaid IP quota.

Use this section when a command returns 13xx, the runner says to run auth login, or the user asks to use an API plan.

1. Open https://yeahpdf.com/console and create a key (ypdf_ prefix).
2. Ask them to run this in their own terminal (Node runner has no hidden prompt; pass --api-key or YPDF_API_KEY):

node scripts/ypdf.mjs auth login --base-url https://www.yeahpdf.com --api-key ypdf_...
node scripts/ypdf.mjs auth show
node scripts/ypdf.mjs auth use default

ypdf auth login --base-url https://www.yeahpdf.com --api-key ypdf_...
ypdf auth show
ypdf auth use default

To drop a saved profile later: ypdf auth logout (or --all). This only edits local config.

YPDF_API_KEY / YPDF_BASE_URL are also valid. Do not fabricate keys.

3. Re-run doctor. Only when it prints status=ready (exit 0) start the user's PDF task.

Commands

Copy the column that matches doctor. Flags are the same; only the executable differs.

Write results with -o. Default timeout is 1800s (--timeout). --json keeps quota/entitlements as API JSON; --quiet hides upload/poll progress.

Rules

• Unknown page structure → inspect first.
• 13xx (daily plan/quota) → run --json quota once (same Node or CLI column as doctor), read remaining / limit (-1 means unlimited; do not branch on the Chinese word 不限), explain, and tell them guest quota is used up so they can auth login for the API plan. Stop. Do not retry merge/convert.
• 1401 (rate limit / QPS) → the runner waits about 10 seconds and retries that HTTP call once. If it still returns 1401: wait about 10 seconds, retry that same command at most once. Do not start a new job loop. Do not spam quota or doctor. Still 1401 → stop and tell the user to wait.
• 1508–1511 (unfinished uploads still pending) → not QPS. Show the runner text (account vs IP, count or size). Do not wait 10 seconds and retry a new upload. Tell the user to wait for leftover grants to expire, or that a failed enqueue now releases that attempt’s grant.
• Encrypted input needs --password. Decrypt accepts an empty open password as --password "" on both columns. Do not omit the flag.
• CLI updates: --check is fine when the user asks; never apply ypdf upgrade unless they explicitly agree.
• Uninstall: run ypdf uninstall only when the user explicitly asks to remove the CLI. Add --purge only if they also want the local config / saved key deleted. Never uninstall during install, upgrade, doctor, or a PDF job.
• Map wording to one command: 修复/fix broken → repair; 页码 → page-numbers; 旋转/rotate → flip; 裁剪 → crop; 压缩 → compress; 转 Word/docx → convert word; 转 Markdown/md → convert markdown; 转 HTML → convert html; 转 Excel → convert excel; 转图片 → convert pages; 长图 → convert long; 图片转 PDF → image-to-pdf; 表格转 PDF → excel-to-pdf. Do not open the editor APIs. Scanned PDF may need --ocr on convert word/markdown/html/excel.
• Prefer simple flags. Defaults: page-numbers FILE, flip FILE --rotate 90, crop FILE --inset 0.1, watermark FILE --text TEXT, repair FILE.
• Need per-range / interval / per-page JSON? Run ypdf spec-help <cmd> for that command only, then pass --spec. Do not read reference.md just to look up fields. If spec-help is missing (native CLI older than 0.1.5), read only the matching heading in spec-help.md. The Node runner always has spec-help.