SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillswps-airpage

wps-airpage

Office & productivity

View repository

Updated 10-16 06:20

About this skill

WPS AirPage CLI Skill

Use the local CLI to operate WPS 365 AirPage documents. Prefer the CLI over hand-written HTTP requests. Only read raw API references when the CLI cannot express the requested operation.

When to Use

Use this skill when:

  • The user wants to modify, inspect, search, or create a WPS 365 AirPage / Smart Documents (智能文档) / kdocs document.
  • User mentions adding a paragraph, changing a heading, adding comments, uploading an image, querying block structure, finding a block ID, converting Markdown/HTML, or editing a table inside AirPage.
  • User asks to automate a WPS smart doc and the target is clearly AirPage rather than a local Office file.

Do NOT use for: local .docx / .xlsx, WPS desktop troubleshooting, Notion/Google Docs, or generic browser automation unrelated to AirPage.

Task Flow

When an AirPage request is received, execute strictly in this order.Each step has clear completion conditions; do not proceed to the next step until they are met.

  1. Check credentials：node scripts/cli.js auth

    • Valid → continue to Step 2.
    • Missing/expired (>8h)/API returns authentication error → fully automatic refresh (Never require the user to manually navigate or report status throughout the process）：
      1. MCP fully automatic login (preferred) → see references/auth.md Method Zero
      2. Chrome DevTools MCP page already open → Method One
      3. auth --browser(Playwright fully automatic) → Method Two
      4. Manual fallback:auth --set-cookie ... --set-csrf ...
    • DO NOT enter Step 2 until auth returns a valid status.

  2. Confirm file_id

    • User provided a numeric ID, short link (365.kdocs.cn/l/xxx) or document link (/office/o/xxx) → pass directly to the CLI, which parses it automatically.
    • Provided a document name/keyword → search <keyword>。
    • No clear target → proactively ask: search existing documents or create a new document.
    • Search/createAlways complete via the CLI, and never require the user to perform manual operations in the browser.
    • DO NOT enter Step 3 until you hold a valid numeric file_id.

  3. Execute the operation → prefer the core commands below; for complex payloads, read the corresponding reference.

  4. Verify the result: after content changes, use query to read back; after comment changes, use comments to recheck.

    • DO NOT omit this step. An unverified write operation equals incomplete.
    • outline There is indexing delay for newly created documents—to verify content use query, not outline。

  5. Report back to the user: state the document name,file_id, changes made, and verification result; on failure, state which step it got stuck at.

Core Commands

node scripts/cli.js                          # 交互式向导（推荐用户直接使用）
node scripts/cli.js auth                     # 检查凭据状态
node scripts/cli.js auth --browser           # 全自动刷新凭据（Playwright）
node scripts/cli.js search <keyword>         # 搜索文档，返回数字 file_id
node scripts/cli.js new-doc --name <名称>   # 新建文档，返回 file_id + doc_url
node scripts/cli.js query <file_id> [block_id]   # 查询块（默认查根节点）
node scripts/cli.js insert-markdown <file_id> --content <text|@file> [--pos begin|end]
node scripts/cli.js outline <file_id> [--format markdown|json]   # 目录结构
node scripts/cli.js update <file_id> --body <json>
node scripts/cli.js insert <file_id> --block-id <id> --index <n> --content <json>
node scripts/cli.js upload-image <file_id> <path> [--index <n>]
node scripts/cli.js comments <file_id>
node scripts/cli.js comment-add <file_id> --sid <id> --text <text>

For full command parameters see references/block-ops.md。

Common Task Patterns

Insert Markdown content (preferred method)

node scripts/cli.js auth
node scripts/cli.js search <keyword>   # 拿 file_id
node scripts/cli.js insert-markdown <file_id> --content "# 标题\n正文" --pos end
node scripts/cli.js query <file_id>    # 验证

Only switch to this when fine-grained control over the insertion position is needed convert + insert。

Create a new document and write content

node scripts/cli.js new-doc --name "文档名"
# 输出包含 file_id 和 doc_url（格式：https://365.kdocs.cn/office/o/{fileid}）
node scripts/cli.js insert-markdown <file_id> --content @content.md

Query / modify blocks

node scripts/cli.js query <file_id>                          # 查根节点
node scripts/cli.js query <file_id> <block_id>               # 查指定块
node scripts/cli.js update <file_id> --body '[{...}]'        # 更新（必须数组）
node scripts/cli.js query <file_id> <block_id>               # 验证

Comment operations

node scripts/cli.js comments <file_id>
node scripts/cli.js comment-add <file_id> --sid <sid> --text "评论内容"
node scripts/cli.js comment-update <file_id> --id <cid> --sid <sid> --text "新内容"

View document outline

node scripts/cli.js outline <file_id>              # markdown 格式，含 tileId
node scripts/cli.js outline <file_id> --format json  # 带 level/attrs 结构

Critical Gotchas (no need to read the reference, just remember these)

These 4 items are the behaviors Claude is most likely to get wrong by default; their priority is higher than intuition:

  1. outline There is indexing delay for newly created documents：outline may return empty even though the content has been written. To verify write results, always use query to filter heading blocks, not outline。
  2. update --body must be an array: even if only one block is being updated, you must use '[{...}]', a single object will report a parameter error (error code -152).
  3. The inline text field is content not text：{ "content": [...] }, writing it as { "text": "..." } will fail silently.
  4. rangeMarkBegin / rangeMarkEnd is not a real block: when calculating insert --index you must skip these markers;update_content If you want to preserve comment anchors, you need to carry these markers back as well.

For the full list of pitfalls, see references/verified-behavior.md。

Key Constraints

  • file_id Accepts three forms: numeric ID, short link (365.kdocs.cn/l/xxx), document link (365.kdocs.cn/office/o/xxx), CLI parses automatically.
  • insert --index Must be >= 1(title is fixed at index 0).
  • update --body Must be an array, even if only one block is updated.
  • When updating a block containing comments, you need to preserve rangeMarkBegin / rangeMarkEnd。
  • comment-update Must pass both comment_id + selection_id。
  • insert-markdown --pos Only supports begin / end。
  • outline There is indexing delay for newly created documents; to verify content, use query to filter heading blocks.
  • Document URL format:https://365.kdocs.cn/office/o/{fileid}（new-doc will be returned automatically).

Security

  • Credentials are stored in ~/.claude/secrets/wps365.json(permissions 0600), containing cookie + csrf。
  • wps_sid is an HttpOnly cookie, can only be read from network request headers, must not rely on document.cookie。
  • CSRF token is only available in the window.__WPSENV__.csrf_token of the AirPage edit page (not the share/preview page).
  • MCP authentication is extracted by intercepting browser network requests; credentials do not leave the local machine.
  • Credentials automatically prompt for refresh after 8 hours, avoiding long-term exposure of stale sessions.

Progressive Disclosure

Read on demand, do not preload all references:

Scenario Read
Credential refresh failure, MCP steps, authentication errors references/auth.md
Search documents, understand file_id references/file-search.md
Construct insert/update/delete/table payloads references/block-ops.md
Block types, inline structure, field constraints references/data-structure.md
Error codes references/error-codes.md
Tested pitfalls, compatible syntax, verified coverage references/verified-behavior.md
When the CLI cannot cover it (low frequency) references/api-reference.md
Ready-made block JSON examples assets/

If api-reference.md conflicts with verified-behavior.md , verified-behavior.md takes precedence.