【内容源自李伟坚老师的WPS-dbsheet技能】如何让AI管理多维表AirScript脚本？

Lv.2潜力创作者

场景

　　用户在日常工作中使用 WPS 多维表格管理业务数据，对数据进行增删查改、字段计算、报表生成等操作。起初数据量不大，用户手动完成这些操作尚可应付。

　　随着业务推进，需要处理的数据越来越多，涉及的人员和环节也日益复杂。面对大量的数据操作任务，用户产生了利用多维表格构建持续管理和协作系统的需求——将零散的表格操作组织为稳定的业务流程，让团队成员在同一套体系中协同工作。

　　当应用的复杂度达到一定程度时，仅靠手动操作和内置功能已无法满足需求。用户开始寻求更高层次的自动化能力：让表格能够遍历数据记录，按条件做出判断和处理，调用外部接口获取信息，在特定时间自动执行任务。这些能力已经超越了公式和条件格式的范畴，需要一段能够运行在表格内部的脚本来承载。

　　 WPS 多维表格提供了内置的 JavaScript 脚本运行环境 —— AirScript。AirScript可以对表格数据进行增删查改、修改单元格格式、调用外部接口获取数据、执行定时任务和批量处理。开发者可以在AirScript编辑器中进行脚本的编写、调试和运行。

　　尽管有了 AirScript 这一强大的工具，但并非所有用户都具备编写代码的能力。此时 AI 智能体（如 WPS 灵犀）可以作为辅助——用户用自然语言描述业务需求后，AI 分析表格结构，理解业务流程，生成一段可直接运行的 AirScript 代码。

　　AI 将代码生成完毕后，一个新的问题摆在用户面前：这段代码现在位于 AI 的对话界面中，用户要通过什么途径才能将其部署到自己的多维表格里？

问题

　　要回答这个问题，需要先了解 WPS 多维表格为外部系统调用脚本提供的认证机制——脚本令牌（AirScript-Token）。用户在脚本编辑器中创建令牌后，会得到一个字符串凭证。将该凭证放入 HTTP 请求头 AirScript-Token 中，发送至脚本的 webhook 链接，即可触发一个已存在于表格中的脚本执行。

POST /api/v3/ide/file/{file_id}/script/{script_id}/sync_task
AirScript-Token: <令牌值>
Content-Type: application/json

　　官方接口文档中，脚本令牌支持的操作有三类：同步执行脚本（sync_task）、异步执行脚本（task）、查询任务状态（GET /api/v3/script/task）。这三类操作均以**"脚本已存在于表格中"**为前提——脚本需要先被创建和保存，Token 才能触发其运行。也就是说，脚本令牌解决的是"脚本已就位，由谁触发执行"的问题，而非"脚本如何进入表格"的问题。

　　创建新脚本、查看脚本源码、修改脚本内容、删除已有脚本、列出当前表格中的所有脚本——这些脚本生命周期管理操作，官方接口文档中并未定义，Token 机制也不覆盖它们。如果 AI 在对话中生成了脚本代码，目前无法通过AirScript-Token将其部署到多维表格中。

　　创建新脚本、粘贴代码、保存这三个步骤，仍需用户在脚本编辑器中手动完成。这意味着一个断层：AI 可以生成脚本代码，但用户无法通过现有公开接口将其送入表格。代码在对话界面中产生，也在对话界面中停留。

解决方案

　　WPS 网页版（www.kdocs.cn）脚本编辑器在与服务器交互时调用了一组 HTTP 接口。编辑器在新建脚本时发送 POST 请求至 /api/v3/ide/file/{file_id}/script；查看脚本源码时发送 GET 请求至 /api/v3/ide/file/{file_id}/script/{script_id}；保存修改时发送 PUT 请求；删除脚本时发送 DELETE 请求。

　　这些接口不在官方公开的 API 文档中，但我们通过分析浏览器与服务器之间的通信可以获取其调用方式和参数结构。这组接口涵盖的正是 Token 机制所缺失的脚本管理能力。

架构流程图

　　这些接口的认证依赖浏览器自动携带的 Cookie——用户在浏览器中登录 WPS 账号后，Cookie 即为身份凭证。脚本令牌不具备这些管理接口的访问权限，但浏览器 Cookie 可以。用户在脚本编辑器中执行新建、保存、删除等操作时，背后正是通过这些接口完成的，接口的通行证就是 Cookie。

　　由此可以形成一个技术方案：让自动化程序借用本机浏览器中已有的 WPS 登录态，以与用户本人相同的身份调用这些管理接口。

　　该方案的权限范围与用户在浏览器中手动操作完全一致。

接口获取

　　要实现上述方案，我们需要先获取两个关键标识符：文件 ID（file_id）和脚本 ID（script_id）。用户可以从脚本的 webhook 链接中提取这两个参数。

　　用户打开脚本编辑器，选中左侧脚本列表中的任意一个脚本，点击鼠标右键，选择"复制脚本webhook"。复制得到的链接格式如下：

https://www.kdocs.cn/api/v3/ide/file/{file_id}/script/{script_id}/sync_task

　　链接中包含两个路径参数：file_id 代表当前多维表格文档的标识符，script_id 代表该脚本的标识符。需要特别说明的是，文档分享链接（如 https://www.kdocs.cn/l/cb9B1dbZJLMk）中的字符串是 link_id，该字符串不是 file_id，不能直接用于 API 调用。

接口规范

　　拿到正确的 file_id 和 script_id 之后，所有接口的 Base URL 均为 https://www.kdocs.cn，Content-Type 统一为 application/json。　　

　　这些接口分为管理接口和执行接口两类。

　　管理接口（5个）包括：获取脚本列表、获取脚本详情、创建脚本、修改脚本、删除脚本。管理接口经浏览器通信分析获得，非官方公开 API，依赖浏览器 Cookie 认证。

　　执行接口（3个）包括：同步执行脚本、异步执行脚本、查询任务状态。执行接口为官方公开 API，既支持 AirScript-Token 认证，也支持浏览器 Cookie 认证。

API 汇总表

管理接口

获取脚本列表

GET /api/v3/ide/file/{file_id}/script

该接口无需请求体。系统返回当前表格下所有脚本的基本信息，包含每个脚本的 id、script_name、runtime_version、ctime 和 mtime。

获取脚本详情

GET /api/v3/ide/file/{file_id}/script/{script_id}

该接口在路径中增加 script_id 参数锁定目标脚本。返回数据中的 script 字段包含该脚本的完整 JavaScript 源码。

创建脚本

POST /api/v3/ide/file/{file_id}/script

调用方在请求体中传入三个字段：script_name（脚本名称）、script（JavaScript 源码全文）、runtime_version（固定值 "1.0"）。该接口是将代码注入表格的核心接口——通过浏览器会话调用一次，即可将 AI 生成的代码注册为表格系统中的一个正式脚本。

修改脚本

PUT /api/v3/ide/file/{file_id}/script/{script_id}

请求体包含四个字段：id（目标脚本 ID）、script_name（新名称）、script（新源码）、change_script（设为 true，表示确认修改脚本内容）。系统接收到请求后更新目标脚本，覆盖原有内容。

删除脚本

DELETE /api/v3/ide/file/{file_id}/script/{script_id}

该操作不可逆。系统执行后将脚本及其关联的任务记录永久移除。

执行接口

同步执行脚本

POST /api/v3/ide/file/{file_id}/script/{script_id}/sync_task

请求体为一个 Context 对象，脚本内部通过 Context.argv 读取传入参数。典型请求体：

{"Context": {"argv": {"sheetName": "利润表"}, "sheet_name": "利润表"}}

系统返回数据包含 data.result（脚本的 return 值）、data.logs（日志数组）、status（"finished" 表示执行完毕）。该接口采用同步阻塞模式，调用方等待系统返回后直接获取结果。

异步执行脚本

POST /api/v3/ide/file/{file_id}/script/{script_id}/task

请求体结构与同步执行一致。系统不等待脚本执行完成，立即返回一个 task_id。调用方通过该 task_id 轮询结果：

GET /api/v3/script/task?task_id={task_id}

由于 task_id 包含特殊字符，调用方在将其作为 query 参数传递前需进行 URL 编码。返回结构与同步执行相同，status 为 "finished" 时表示脚本执行完成。

代码实现

　　开发者可以基于 PowerShell将上述接口调用组合为可执行脚本：启动本机已登录 WPS 的 Edge 浏览器进程，通过 Chrome DevTools Protocol（CDP）连接调试端口，通过 --user-data-dir 参数指定用户的个人数据目录，新打开的浏览器窗口自动复用已有登录会话。打开多维表格网页后，在该窗口的页面上下文中执行 JavaScript 的 fetch() 函数调用上述脚本管理接口，fetch() 自动携带当前页面的 Cookie，无需额外设置认证头。

PowerShell 脚本

　　脚本整体分为四层。参数层通过 param 块定义输入合约，ValidateSet 将 $Action 限定为 7 个合法操作，[switch]$Visible 控制浏览器是否窗口化启动。桥接层通过 CDP 向浏览器注入 JavaScript，credentials: 'include' 使 fetch() 携带登录 Cookie 完成认证，text/plain 的 Content-Type 避免跨域预检请求。转换层的 Convert-BrowserFetchResult 根据 $FetchResult.json 的真值自动选择 JSON 对象或原始文本。调度层的 switch ($Action) 将操作路由至 7 个分支，每个分支遵循"参数校验→构造请求体→发起请求→格式化结果→返回"的顺序。请求体通过 @{} 哈希表构造，ConvertTo-Json 序列化为 JSON 后发送。-not $ScriptId 的校验模式确保不完整请求被提前拦截。

　　用户在使用前应将脚本保存为 .ps1 文件，并将 YOUR_FILE_ID 替换为从 webhook 链接中提取的真实 file_id。使用前提是 Edge 浏览器已登录 WPS 账号。

　　脚本通过 -Action 参数指定操作类型，以下是一段示例代码：

# 列出所有脚本
.\invoke-wps-script.ps1 -Action list

# 创建名为"毛利计算"的新脚本
.\invoke-wps-script.ps1 -Action create -ScriptName "毛利计算" -ScriptText "function main(){var s=Application.Sheets('利润表');return {c:s.RecordRange.Count};} main();"

# 同步执行指定脚本
.\invoke-wps-script.ps1 -Action run -ScriptId "V2-xxxx" -ContextJson '{"argv":{"sheet":"利润表"}}'

WPS灵犀

3天前

7 +1

1 +1