| name | wps-dbsheet |
| description | CRUD operations on WPS smart sheets (数据表/多维表格/dbsheet) via wpsx. Use for querying/inserting/updating records, fields, sheet structures, imports, table management, or prompts about 多维表格/数据表/记录/字段. |
WPS Smart Sheet (DBSheet) Operations
通过 wpsx CLI 操作 WPS 数据表（多维表格/dbsheet），实现表结构查询和数据 CRUD。
Setup
Endpoint: https://openapi.wps.cn/mcp/v2/kso-dbsheet/message
认证: token 由 wpsx 自动注入。首次使用请先运行 wpsx auth --app-id <ID> --app-secret <SECRET> 完成 WPS 365 OAuth2 授权。
调用格式:
wpsx call <tool> -p '<json>' https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
Guardrails
确认规则:
- 创建记录前，展示要录入的字段和值让用户确认
- 更新记录前，展示修改前后的对比让用户确认
- 批量操作前，明确告知影响范围
空结果处理:
- keyword 搜索不到文件 → 建议用户检查文件名或直接提供 fileID/fileURL
- 查询记录返回空 → 告知用户该表暂无数据
分页策略:
- 用户要求"全部/所有" → 自动翻页直到结束
- 其他情况 → 展示首页结果，告知"还有更多数据，需要继续查看吗？"
错误处理:
- API 返回错误 → 将错误信息展示给用户，不要吞掉
- 字段名不匹配 → 检查是否与表结构中的字段名完全一致（先执行 Playbook 1）
- Endpoint 不可达 / 401 未授权 → 提示用户先运行
wpsx auth 完成 WPS 365 授权
Playbook 1: 查看表结构 / 找数据表
触发: 用户说"看看XX表有哪些字段"、"有没有XX相关的表"、"这个表的结构是什么"、"帮我找个表"
wpsx call kso_dbsheet_get_file_schema \
-p '{"keyword": "{关键词}"}' \
https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
也可用 fileID 或 fileURL 精确定位。返回文件基本信息 + 所有工作表名称/ID/字段结构。
重要: 几乎所有后续操作都需要先获取 fileID、sheetID 和字段名，所以这一步通常是必须的前置操作。
Playbook 2: 查询表数据
触发: 用户说"看看表里有什么数据"、"查一下XX记录"、"列一下XX表的内容"、"有多少条数据"
步骤:
-
获取表结构 — 如果还没有 fileID 和 sheetID，先执行 Playbook 1。
-
查询记录:
wpsx call kso_dbsheet_list_sheet_records \
-p '{"fileID": "{FILE_ID}", "sheetID": "{SHEET_ID}", "pageSize": 100}' \
https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
可选参数：
fieldNames: 只返回指定字段，如 ["姓名", "状态"]pageSize: 每页记录数，默认 100pageToken: 翻页 token，首次不传，后续从上次返回值获取
-
整理输出 — 用表格形式展示给用户。如果数据量大，汇总关键信息或按用户要求筛选。
Playbook 3: 新增记录
触发: 用户说"帮我加一条记录"、"录入一条数据"、"往表里添加XX"、"记一下XX"
步骤:
-
获取表结构 — 先执行 Playbook 1 获取 fileID、sheetID 和字段名列表（必须用准确的字段名）。
-
确认要录入的数据 — 根据字段结构，向用户确认每个字段的值。
-
创建记录:
wpsx call kso_dbsheet_create_sheet_records \
-p '{"fileID": "{FILE_ID}", "sheetID": "{SHEET_ID}", "records": [{"fields_value": "{\"字段1\": \"值1\", \"字段2\": \"值2\"}"}]}' \
https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
注意:
fields_value 是一个 raw JSON 字符串（字符串里嵌套 JSON），不是对象- 自动类型字段（auto_number、created_by、created_time 等）不能手动填入
- 支持批量添加多条记录
Playbook 4: 更新记录
触发: 用户说"帮我改一下XX的数据"、"把XX的状态改成YY"、"更新一下记录"
步骤:
-
先查询 — 执行 Playbook 2 找到要修改的记录，取得记录的 id。
-
确认修改内容 — 向用户确认要改哪些字段和新值。
-
更新记录:
wpsx call kso_dbsheet_update_sheet_records \
-p '{"fileID": "{FILE_ID}", "sheetID": "{SHEET_ID}", "records": [{"id": "{RECORD_ID}", "fields_value": "{\"字段1\": \"新值\"}"}]}' \
https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
- 只需传要更新的字段，其他字段保持不变
- 支持批量更新多条记录
Playbook 5: 创建新工作表
触发: 用户说"帮我建一个新表"、"创建一个XX工作表"、"加个 sheet"
步骤:
-
确认所属文件 — 需要 fileID，如果用户没给，先用 Playbook 1 找到目标文件。
-
创建工作表:
wpsx call kso_dbsheet_create_sheet \
-p '{"fileID": "{FILE_ID}", "sheetName": "{表名}", "fieldNames": ["字段1", "字段2", "字段3"]}' \
https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
Playbook 6: 重命名工作表
触发: 用户说"把XX表改个名"、"重命名工作表"
wpsx call kso_dbsheet_update_sheet \
-p '{"fileID": "{FILE_ID}", "sheetID": "{SHEET_ID}", "newSheetName": "{新名称}"}' \
https://openapi.wps.cn/mcp/v2/kso-dbsheet/message -f json
Playbook 7: 从其他来源导入数据到表
触发: 用户说"把文档里的表格导入到数据表"、"从XX整理成表格"、"帮我把这些数据录到表里"
步骤:
-
获取源数据 — 可能来自：
- 云文档内容（联动 wps-yundoc skill 读取）
- 本地文件（Read 工具读取）
- 用户直接提供的文本
-
解析为结构化数据 — 将内容解析为字段名 + 记录列表。
-
创建表（如需要） — Playbook 5 创建工作表并定义字段。
-
批量写入 — Playbook 3 批量创建记录。
fields_value 格式说明
fields_value 是创建/更新记录时最关键的参数，它是一个 JSON 字符串（不是对象）：
{"fields_value": "{\"任务名称\": \"完成设计稿\", \"负责人\": \"张三\", \"状态\": \"进行中\"}"}
- key 必须与表中字段名完全一致（建议先用 Playbook 1 获取准确字段名）
- 自动类型字段（auto_number、created_by、created_time 等）不要传入
常见错误:
✅ 正确: {"fields_value": "{\"任务名称\": \"完成设计稿\", \"负责人\": \"张三\"}"}
❌ 错误: {"fields_value": {"任务名称": "完成设计稿", "负责人": "张三"}}
fields_value 的值必须是 JSON 字符串（用引号包裹的 JSON），不是 JSON 对象。
Additional Resources
