WPS-AirPage-Skill的介绍

Lv.2潜力创作者

项目地址： github.com/WPS-SmartDocs/WPS-AirPage-Skill

介绍文章：https://mp.weixin.qq.com/s/XHMgiJyLPXnajf6-NOV1ZA

WPS AirPage Skill 是金山办公 SmartDocs 团队开源的 AI Agent 技能插件，让 Claude Code、Cursor、Codex、Gemini CLI 等 AI 编程助手能够用自然语言直接操控 WPS 365 智能文档。

它本质上是一个运行在本地的 Node.js CLI 工具，充当 AI Agent 与 WPS 365 在线文档平台之间的桥梁。用户无需学习任何 API 或命令，只需用日常语言描述需求——"帮我在那个 kdocs 文档里加一段周报"、"创建一个新的 AirPage 文档并把这份 Markdown 插进去"——Agent 就会自动调用 CLI 命令完成文档的搜索、创建、编辑、图片上传、评论管理等全部操作，大幅降低了智能文档的操作门槛。

一、核心能力

WPS AirPage Skill 覆盖了智能文档操作的完整生命周期：

能力类别	具体功能
文档管理	按关键词搜索文档、创建新文档、获取文档 URL
内容操作	插入 Markdown / HTML 内容、更新块内容、插入和删除块
结构查询	查询块结构树（Block Tree）、查看文档标题目录
表格操作	插入行/列、删除行/列、合并单元格、拆分单元格
多媒体	上传图片并嵌入文档、设置图片尺寸
评论协作	查看评论列表、添加评论、回复评论、更新评论内容
格式转换	将 Markdown 或 HTML 转换为 AirPage 块数据

二、安装与鉴权

安装

前置条件：Node.js 18+ 和 WPS 365 账号。

在GITHUB仓库下载文件后，按需将相应的文件导入不同的AI客户端

比如针对Claude Code：

npx skills add WPS-SMARTDOCS/WPS-AIRPAGE-SKILL

对话中提及 kdocs、AirPage、智能文档或 365.kdocs.cn 时，Skill 自动激活。用户无需记忆任何命令，用自然语言描述需求即可。

鉴权

鉴权是连接 Agent 与 WPS 365 的关键环节。

方式一 — MCP 全自动（首选）：通过 Chrome DevTools MCP 自动检测登录状态、打开浏览器、等待用户完成登录后提取 Cookie 和 CSRF Token，整个过程用户只需做一次登录操作。凭据自动保存，后续操作零感知。

方式二 — Playwright 自动提取：执行 node scripts/cli.js auth --browser。若登录态有效，无头模式静默提取；若过期则弹出浏览器窗口，用户登录后自动保存 Profile，下次复用。

方式三 — 手动兜底：从浏览器 DevTools 复制 Cookie 和 CSRF Token，通过命令行直接写入：node scripts/cli.js auth --set-cookie "..." --set-csrf "..."。

凭据存储在 ~/.claude/secrets/wps365.json，权限模式 0600，超过 8 小时自动提示刷新。所有凭据仅保存在用户本地，不向任何第三方发送。

三、任务执行流程

Agent 收到 AirPage 相关请求后，严格按五步流程执行，每一步都有明确的完成条件：

检查凭据 → 确认 file_id → 执行操作 → 验证结果 → 回报用户

Step 1 — 检查凭据：调用 auth 命令确认凭据有效。缺失、过期或 API 返回鉴权错误时，自动触发刷新流程。凭据有效前禁止进入下一步。

Step 2 — 确认 file_id： file_id 是所有文档操作的核心标识。支持三种输入形式：数字 ID 直接使用；短链 365.kdocs.cn/l/xxx 和完整链接均由 CLI 自动解析。若用户提供了关键词，则调用 search 搜索；未明确目标时主动询问是搜索已有文档还是新建。

Step 3 — 执行操作：优先使用高层 CLI 命令（如 insert-markdown），仅在 CLI 无法满足时才读取 API 参考文件构造底层 payload。

Step 4 — 验证结果：写操作必须回读确认——内容变更用 query 复查，评论变更用 comments 验证。写操作未经验证等于未完成。需特别注意：outline 对新文档有索引延迟（可能返回空列表），验证写入应使用 query 而非 outline。

Step 5 — 回报用户：说明操作结果，包括文档名称、file_id、变更内容和验证状态。失败则明确告知卡在哪一步及原因。

四、CLI 核心命令

命令	功能
auth / auth --browser	检查凭据状态 / 全自动刷新凭据
search <keyword>	按关键词搜索文档，返回数字 file_id
new-doc --name <名称>	新建文档，返回 file_id 和文档 URL
query <file_id> [block_id]	查询块结构（默认查根节点）
insert-markdown <file_id> --content <text\|@file> [--pos begin\|end]	插入 Markdown（首选方式）
outline <file_id>	查看文档标题目录结构
update <file_id> --body <json>	更新块内容
insert <file_id> --block-id <id> --index <n> --content <json>	在指定位置插入块
delete <file_id> --body <json>	删除块
convert <file_id> --from markdown --content <text>	Markdown/HTML 转为块数据
upload-image <file_id> <path>	上传并插入图片
comments <file_id>	查看评论列表
comment-add / comment-update <file_id> ...	添加 / 回复 / 更新评论

五、典型使用示例

示例 1 — 插入 Markdown 内容（最高频操作）：

node scripts/cli.js auth
node scripts/cli.js search "周报"                    # 搜索获取 file_id
node scripts/cli.js insert-markdown <file_id> --content "# 本周进展\n正文内容..." --pos end
node scripts/cli.js query <file_id>                  # 回读验证写入结果

示例 2 — 新建文档并写入：

node scripts/cli.js new-doc --name "Q2 季度总结"     # 返回 file_id + URL
node scripts/cli.js insert-markdown <file_id> --content @content.md   # 支持读文件
node scripts/cli.js query <file_id>                  # 验证

示例 3 — 评论协作：

node scripts/cli.js comments <file_id>                           # 查看评论
node scripts/cli.js comment-add <file_id> --sid <sid> --text "评审意见"
node scripts/cli.js comments <file_id>                           # 验证

六、底层架构

所有块操作通过 WPS 365 内部封装的统一 API 端点完成：

POST https://365.kdocs.cn/api/v3/office/file/{file_id}/core/execute

与原始 WPS 开放平台 API 相比，无需复杂的 KSO-1 签名，参数直接用 JSON 格式传递，大幅简化了 Agent 的调用难度。API 使用两种 Command 类型区分操作：

http.otl.exec — 写操作（创建 / 更新 / 删除），参数为 subtype + params

http.otl.query — 读操作（查询 / 转换），参数为 name + params

智能文档的核心数据模型是块节点树（Block Tree）。文档由多个块节点组成，每个块包含类型（type）、属性（attrs）和内容（content），内容可嵌套子块形成树形结构。支持的块类型包括：标题、段落（支持列表）、标题 H1-H6、代码块（43 种语言）、表格、图片、视频、引用块、分栏布局（1-10 栏）、多维表格、流程图等十余种。

七、关键坑点

在 SKILL.md 的"Critical Gotchas"部分：

outline 索引延迟：新建文档后 outline 可能返回空列表，即使内容已写入。服务端索引存在数秒到数十秒的延迟。验证写入用 query 命令过滤 heading 块。

--body 必须是数组：即使只更新一个块，--body 也要传 '[{...}]' 数组格式，传单对象会报参数错误（错误码 -152）。

行内文本字段名是 content：正确写法为 {"type": "text", "content": "文本内容"}，写成 "text": "..." 会导致静默失败——API 不报错但内容不会更新。

跳过评论锚点： rangeMarkBegin / rangeMarkEnd 是评论锚点标记，非真实块。计算 insert --index 时必须跳过；执行 update_content 时若需保留评论锚点，需将其一并带回 content 数组。

附件上传需带 Origin：图片上传端点必须附带 Origin: https://365.kdocs.cn 请求头，否则会被服务器拒绝。CLI 已内置处理，但手动构造 API 时需注意。

八、安全设计与适用边界

安全方面：凭据仅存本地 ~/.claude/secrets/，权限 0600；HttpOnly Cookie 通过拦截浏览器网络请求获取，不走 JavaScript；凭据超 8 小时自动提示刷新，避免长期暴露陈旧会话。

适用场景： WPS 365 AirPage / 智能文档 / kdocs 在线文档的块级 CRUD、Markdown 转换、评论协作、文档搜索与管理。

不适用场景：本地 .docx / .xlsx 文件操作、WPS 桌面应用问题排查、Notion / Google Docs 等其他平台、与 AirPage 无关的通用浏览器自动化。

WPS AI

2026-04-15 03:02:39 广东省

5 +1