cliff-byte/alipay-doc-fetcher

Fetch Alipay Open Platform Documentation

The Alipay documentation site is a JS-rendered SPA; WebFetch / curl cannot retrieve the body content, and code and parameter sections rely on lazy loading and collapsible interactions. This skill uses a pre-packaged Playwright tool to fetch them in one step as structured Markdown.

When to Use

• The user wants to "pull", "fetch", or "convert to Markdown" an Alipay API / integration guide / error code / product doc.
• The user pastes an opendocs.alipay.com or opendoc.alipay.com link and wants its content.
• Normal web fetching (WebFetch / curl etc.) returns only the title with an empty body for Alipay docs.

How to Use

Let the skill installation directory be $SKILL (e.g., ~/.claude/skills/fetch-alipay-doc, for Codex ~/.codex/skills/..., for Cursor ~/.cursor/skills/...).

1. First-time setup: Install dependencies once in $SKILL (one-time only, independent of your working directory):

   (cd "$SKILL" && npm install && npx playwright install chromium)   # can be skipped if playwright is already global
   

2. Collect the URLs to fetch. For multiple pages, write a config JSON file (e.g., urls.json) as an array [{ "name": "...", "url": "..." }, ...]. The name determines the output filename (optional, defaults to the page's H1).

3. Run from the user's current project directory (use absolute paths to call the script, so output lands in the project and is visible to the user). Do not cd into $SKILL — that would write docs into the skill installation directory (the tool will refuse). Specify output with --out inside the project, organized by product/topic:

   # Single page
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --url "<Alipay doc URL>" --name "<filename>" --out ./alipay-docs/<product>
   # Batch
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --config urls.json --out ./alipay-docs/<product>
   

   Node resolves Playwright dependencies from the script file's location looking for node_modules, independent of the working directory, so calling with an absolute path from the project directory works.

4. Output is placed in the --out directory: <name>.md + images/. Default --out is ./alipay-docs in the current directory.

Key Principles

• Faithfulness: The body text must be 100% from the page; no fabrication / summarization / rewriting / interpretation allowed. The tool only performs mechanical formatting.

Post-Fetch Checklist

For each fetched page, verify every item. If something is wrong, follow "Troubleshooting" or re-fetch:

• No leftover @@...@@ placeholders (unreplaced placeholders = lost code/table/images).
• No UI noise lines (bookmarks / subscribe updates / my docs / cURL·Java·C# tabs / "This example is for reference only" / "Collapse all properties" etc.).
• All image references point to existing local images/ files (no broken links).
• API business parameters include nested sub-properties and enum values complete (compare to the page state after "Expand all properties").
• Common request/response parameter tables, Java request examples, and error code tables are all present.
• Table rowspan aligns correctly (each code matches its sub_code one-to-one, no misalignment).

Troubleshooting

• Missing code / parameters → Likely lazy-loaded areas weren't scrolled to or collapsed sections ("More" enums, "Sub-properties" nesting) weren't expanded; ensure the fetching process does full-page scroll + real click expansions one by one.
• Images not downloading → cdn.nlark.com (Yuque image CDN) fails with Node https; this tool switches to curl (with UA / Referer); make sure curl is installed on the system.
• API page structure anomalies (e.g., notification/callback pages with sections like "Message properties / Notification response" instead of standard request/response) → The tool handles generic H2 sections; no need to hardcode section names.

Maintainer's note: Full troubleshooting experience, root causes, and design rationale are in PLAYBOOK.md at the repository root (not distributed with the skill installation; read before modifying code).