wps-airpage

WPS AirPage CLI スキル

ローカル CLI を使用して WPS 365 AirPage ドキュメントを操作します。手書きの HTTP リクエストより CLI を優先してください。CLI で要求された操作を実行できない場合に限り、API の生のリファレンスを参照してください。

使用する場合

このスキルを使用する場合：

• ユーザーが WPS 365 AirPage／智能文档／kdocs ドキュメントの変更、確認、検索、作成を希望している場合。
• ユーザーが段落の追加、見出しの変更、コメントの追加、画像のアップロード、ブロック構造の照会、ブロック ID の検索、Markdown／HTML の変換、AirPage 内の表の編集について言及した場合。
• ユーザーが WPS のスマートドキュメントの自動化を依頼しており、対象がローカルの Office ファイルではなく、明らかに AirPage である場合。

使用しない場合： ローカルの .docx／.xlsx、WPS デスクトップのトラブルシューティング、Notion／Google Docs、AirPage と無関係な一般的なブラウザー自動化。

タスクの流れ

AirPage のリクエストを受け取ったら、必ず以下の順序で実行します。各ステップには明確な完了条件があります。満たすまでは次のステップに進んではいけません。

1. 認証情報を確認：node scripts/cli.js auth

   • 有効 → Step 2 に進みます。
   • 認証情報がない／期限切れ（>8h）／API が認証エラーを返す → 全自動で更新します（全過程を通じて、ユーザーに手動での画面移動を求めたり、状態を伝えたりしてはいけません）。
     1. MCP による全自動ログイン（最優先）→ references/auth.md の方式零を参照
     2. Chrome DevTools MCP のページが開いている → 方式一
     3. auth --browser（Playwright による全自動）→ 方式二
     4. 手動での代替手段：auth --set-cookie ... --set-csrf ...
   • auth が有効な状態を返すまで、Step 2 に進んではいけません。

2. file_id を確認

   • ユーザーが数字の ID、短縮リンク（365.kdocs.cn/l/xxx）、またはドキュメントリンク（/office/o/xxx）を提示した → そのまま CLI に渡し、自動解析します。
   • ドキュメント名／キーワードが提示された → search <keyword>。
   • 対象が明確でない → 既存ドキュメントを検索するか、新規ドキュメントを作成するか、ユーザーに確認します。
   • 検索／新規作成は必ず CLI で実行し、ユーザーにブラウザーでの手動操作を求めてはいけません。
   • 有効な数字の file_id を取得するまで、Step 3 に進んではいけません。

3. 操作を実行 → 下記のコアコマンドを優先し、複雑なペイロードの場合は該当するリファレンスを参照します。

4. 結果を検証：内容を変更した後は query で読み戻し、コメントを変更した後は comments で再確認します。

   • このステップを省略してはいけません。書き込み操作は検証されるまで未完了です。
   • outline は新規ドキュメントでインデックス反映が遅延します。内容の検証には query を使用し、outline は使用しません。

5. ユーザーに報告：ドキュメント名、file_id、変更内容、検証結果を説明します。失敗した場合は、どのステップで行き詰まったかを説明します。

コアコマンド

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>

コマンドの全パラメーターは references/block-ops.md を参照してください。

よくあるタスクパターン

Markdown コンテンツの挿入（推奨方法）

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>    # 验证

挿入位置を細かく制御する場合に限り、convert + insert を使用します。

ドキュメントを新規作成してコンテンツを書き込む

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

ブロックの照会／変更

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>               # 验证

コメント操作

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 "新内容"

ドキュメントの目次を表示

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

重要な注意点（リファレンスを読まずに覚えておく）

この 4 点は Claude が最も誤りやすい動作です。直感よりも優先してください。

1. outline は新規ドキュメントでインデックス反映が遅延します：内容が書き込まれていても、outline が空を返すことがあります。書き込み結果の検証には必ず query で heading ブロックを絞り込み、outline は使用しません。
2. update --body は配列でなければなりません：ブロックを 1 つだけ更新する場合でも '[{...}]' を使用する必要があります。単一オブジェクトを指定するとパラメーターエラー（エラーコード -152）が発生します。
3. インラインテキストフィールドは text ではなく content です：{ "content": [...] } を使用します。{ "text": "..." } と記述すると、エラーなく失敗します。
4. rangeMarkBegin／rangeMarkEnd は実際のブロックではありません：insert の --index を計算する際は、これらのマーカーを飛ばす必要があります。update_content の際にコメントアンカーを維持する場合は、これらのマーカーも一緒に戻す必要があります。

注意点の全一覧は references/verified-behavior.md を参照してください。

主な制約

• file_id は数字の ID、短縮リンク（365.kdocs.cn/l/xxx）、ドキュメントリンク（365.kdocs.cn/office/o/xxx）の 3 形式に対応し、CLI が自動で解析します。
• insert --index は >= 1 でなければなりません（title は index 0 に固定されています）。
• update --body は、ブロックを 1 つだけ更新する場合でも配列でなければなりません。
• コメントを含むブロックを更新する場合は、rangeMarkBegin／rangeMarkEnd を保持する必要があります。
• comment-update には comment_id と selection_id の両方を指定する必要があります。
• insert-markdown --pos は begin／end のみ対応しています。
• outline は新規ドキュメントでインデックス反映が遅延するため、内容の検証には query で heading ブロックを絞り込んでください。
• ドキュメント URL の形式：https://365.kdocs.cn/office/o/{fileid}（new-doc が自動で返します）。

セキュリティ

• 認証情報は ~/.claude/secrets/wps365.json（権限 0600）に保存され、cookie と csrf が含まれます。
• wps_sid は HttpOnly cookie であり、ネットワークリクエストヘッダーからのみ読み取れます。document.cookie に依存してはいけません。
• CSRF token は AirPage の編集ページ（共有／プレビューページ以外）の window.__WPSENV__.csrf_token からのみ取得できます。
• MCP 認証ではブラウザーのネットワークリクエストを傍受して認証情報を抽出します。認証情報がローカル環境の外部に送信されることはありません。
• 古いセッションの長期的な露出を防ぐため、認証情報が 8 時間を超えると更新を促すメッセージが自動で表示されます。

段階的な情報開示

必要に応じて参照してください。すべてのリファレンスを事前に読み込まないでください。

状況	参照先
認証情報の更新に失敗した場合、MCP の手順、認証エラー	references/auth.md
ドキュメントの検索、file_id の理解	references/file-search.md
insert/update/delete／表のペイロードの構築	references/block-ops.md
ブロックの種類、inline 構造、フィールドの制約	references/data-structure.md
エラーコード	references/error-codes.md
実測された注意点、互換性のある書き方、検証済みの対応範囲	references/verified-behavior.md
CLI で対応できない場合（低頻度）	references/api-reference.md
すぐに使えるブロック JSON の例	assets/

api-reference.md と verified-behavior.md の内容が矛盾する場合は、verified-behavior.md を優先してください。