Wps

金山文档 CLI Skill 使用指南

金山文档 CLI Skill 提供了一套完整的在线文档操作工具，通过 kdocs-cli 命令行工具与金山文档 API 交互。支持创建、查询、读取、编辑、分享、移动多种类型的在线文档。

严格规则

禁止（NEVER）

• 禁止将 Token 明文出现在对话、日志、命令输出、代码注释或任何文件中；Token 仅允许通过 kdocs-cli auth set-token 或 kdocs-cli auth login 保存到系统密钥链
• 上传写入等接口需传入的 content_base64 可能非常大（编码后 >1 MB），禁止在对话中逐 token 生成 Base64 字符串，用脚本完成文件读取、编码和传参

必须（MUST）

• 不可逆操作（delete/close 类）执行前必须向用户确认
• 写操作完成后必须用独立读取请求验证实际结果（不信任 code: 0）
• 创建文档并验证通过后，必须调用 get_file_link 获取链接并展示给用户
• 通过 --file 或脚本创建的临时 JSON 文件（如 payload.json、temp.json），在整个操作流程结束后必须删除，避免残留在用户工作目录

---

保持最新版本

何时触发：首次使用 Skill / 距上次自检 >24h / 收到 `unknown action` 或 `unknown service` 错误。

1. CLI 版本：kdocs-cli version — 若命令不存在则按下方「工具安装与认证」安装；若低于本文件 frontmatter version，运行 kdocs-cli upgrade -y（自动备份旧版本，失败可 kdocs-cli upgrade --rollback） 2. Skill 版本：若本文件 version 低于 kdocs-cli version，运行 kdocs-cli call check_skill_update version=<本文件version>，若返回 update_available: true，从 instruction 中提取 zip 下载链接（格式 https://...kdocs.zip），下载解压替换当前 Skill 目录

若 upgrade 和 rollback 均失败，在本 Skill 目录下重新运行安装脚本（bash setup.sh / powershell setup.ps1 / node setup.cjs，脚本位于 scripts/）可从 CDN 重新安装。若仍无法更新，以 kdocs-cli --help 实际支持的工具集为准。

---

工具安装与认证

login 失败时的手动获取流程、auth status 诊断、auth logout 退出等详见 references/auth.md。

---

调用格式

kdocs-cli <service> <action> [参数]

参数传递

• --file / stdin 输入必须是该工具的完整 JSON 参数对象
• 中文/多行参数禁止 key=value（Windows/PowerShell 破坏 UTF-8 编码）
• 生成 JSON 文件用 Node.js/Python；禁止 ConvertTo-Json（输出带 BOM）
• PowerShell 传 JSON 字符串须反斜杠转义：'{\"key\":[\"val\"]}'

--file 示例：写入大段内容时，用脚本生成 JSON 文件再 --file 传入，操作完成后删除临时文件：

>

```javascript

const fs = require('fs');

fs.writeFileSync('payload.json', JSON.stringify({

file_id: "<file_id>",

content: fs.readFileSync('article.md', 'utf8'),

format: "markdown",

mode: "append"

}), 'utf8');

```

```

kdocs-cli otl insert-content --file payload.json --silent

```

```javascript

// 操作完成后清理临时文件

fs.unlinkSync('payload.json');

```

全局选项：

帮助：kdocs-cli --help、kdocs-cli <service> --help、kdocs-cli <service> <action> --help

以下工具不可逆，调用前必须向用户确认（详细约束见各工具参考文档的「操作约束」区）：

otl.block_delete、dbsheet.delete_sheet、kwiki.close_knowledge_view、sheet.delete_sheets、sheet.delete_range、dbsheet.delete_view、dbsheet.delete_fields、cancel_share、kwiki.delete_item、sheet.delete_protection_ranges、dbsheet.delete_records、sheet.delete_data_validations、sheet.delete_conditional_format_rules、sheet.delete_float_images、sheet.delete_filters、dbsheet.sheet_batch_delete、dbsheet.permission_delete_roles_async

---

能力范围

支持的文档类型

通用工具总览

文档创建与上传

文档读取与下载

文件组织

分享与访问

搜索

完整参数、示例与返回值见 references/drive.md。

不支持的操作

• 无批量删除文件工具（仅支持移动）
• 云盘 drive 侧暂无逐文件 ACL 成员矩阵（以分享链接为主）；多维表格（.dbt）见 dbsheet.permission_ 与 dbsheet.share_（详阅 references/dbsheet.md）
• 在线 Excel / 智能表格工作表区域保护见 sheet.*_protection_ranges 相关工具（详阅 references/sheet.md）
• 无文件版本回滚
• 无实时协同编辑控制

---

操作指南

执行指南

执行以下操作前，必须先阅读对应指南文件：

⚠️ 不阅读指南直接操作可能导致：参数错误、内容丢失、格式异常。

高频流程指引

创建并写入文档

执行顺序： 1) 先按 references/file-locating-guide.md 获取目标目录 drive_id(可选)、parent_id(可选)。 2) 再按 references/file-writing-guide.md 选择文档类型与写入路径。 字段传递：步骤 1 获取 drive_id(可选)、parent_id(可选)，作为步骤 2 的输入，执行“新建写入”流程。

上传本地文件到云盘

执行顺序： 1) 先按 references/file-locating-guide.md 获取目标目录 drive_id(可选)、parent_id(可选)、file_id(可选)。 2) 再按 references/file-writing-guide.md 的“本地文件上传（upload_file）”路径调用上传能力（新建上传或覆盖更新）。 字段传递：新建上传使用步骤 1 的 drive_id(可选)、parent_id(可选) + name；覆盖更新使用步骤 1 的 file_id 。

搜索定位文档

工具说明：search_files(keyword="关键词", type="all", page_size=20)，获取 file_id、drive_id 供后续链路使用。 详细参数与返回结构见 references/drive/search.md。

更多操作流程

---

错误速查

---

安全约束

• 凭据由 kdocs-cli 系统密钥链管理，Skill 自身不存储、不记录
• 无状态代理，不缓存任何文档内容或业务数据
• 仅在用户主动发起操作时调用对应 API

WPS 云文档 Skill（wps skill）问题反馈

当满足以下任一条件时，生成反馈链接并提供给用户：

1. 错误速查表中的处理方式（重试、保持最新版本等）均已尝试但问题仍未解决 2. 用户主动要求反馈或投诉

运行 kdocs-cli feedback 获取反馈链接，将完整链接展示给用户并告知"点击即可打开反馈页面"，由用户决定是否打开。

AI PPT（aippt）工具完整参考文档

本文件包含金山文档 Skill 中 AI PPT 相关工具的使用指南。

适用范围：aippt.execute 通用技能路由接口，支持通过主题描述或已有文档生成演示文稿。

---

通用说明

AI PPT 工具概述

AI PPT 仅包含一个通用接口 aippt.execute，通过 skill_type 参数路由到不同的生成流水线：

关键行为

• 每次调用返回 SSE 流，当步骤事件携带 need_interaction: true 时 SSE 关闭，需收集用户输入后再次调用
• input 与 interaction_response 互斥，不同时传
• 最终结果从 gen_ppt.done payload 的 doc_url 字段获取云文档链接，直接展示给用户
• 每次调用超时设为 1800000 毫秒

文档引用方式

文档转 PPT 场景下，input 数组中的文档引用使用 v7_file_id（从金山文档链接路径末尾提取的 link_id，无需先调 get_share_info）。

---

一、PPT 生成

1. aippt.execute

功能说明

aippt.execute 是 AI PPT 的通用技能路由接口，通过 skill_type 参数路由到不同的生成流水线。

已支持的能力：

调用协议：

每次调用返回一个 SSE 流，推送若干步骤事件（*.start / *.done）。 当某个事件携带 need_interaction: true 时，SSE 流关闭，调用方 收集用户输入后通过 interaction_response 发起下一次调用。 如此循环，直到 *.done 事件携带最终结果。

不同能力的调用次数不同：有的能力一次调用即可完成，有的需要多轮交互。 具体的调用次数、input 内容、interaction_response 结构、 以及中间步骤序列，均由各能力自行定义，详见 response_detail。

• 每次调用超时设为 1800000 毫秒
• 最后的 *.done 事件携带最终生成结果（含 doc_url 云文档链接等）

操作约束

• 前置检查：首次调用必须明确选择 skill_type，并按该 skill 的交互事件继续恢复调用
• 提示：收到 need_interaction=true 时先收集用户答案，再发起下一次调用，避免空恢复请求

幂等性：否 — 为流式生成任务，重复调用可能创建重复产物；重试前先确认是否已有进行中或已完成结果

input 与 interaction_response 互斥，不同时传

SSE 流中 need_interaction: true 出现时，记录 payload 后等待用户输入，再次调用

最终结果从 gen_ppt.done payload 的 doc_url 字段获取云文档链接，直接展示给用户，无需额外上传

mode 参数在首次和恢复调用中保持一致

调用示例

首次调用 — 主题生成：

{
  "skill_type": "theme_ppt",
  "mode": "html",
  "input": [
    {
      "type": "text",
      "content": "长颈鹿主题的儿童科普 PPT"
    }
  ]
}

首次调用 — 文档生成：

{
  "skill_type": "doc_ppt",
  "mode": "html",
  "input": [
    {
      "type": "text",
      "content": "根据文档生成PPT"
    },
    {
      "type": "v7_file_id",
      "content": "co4Kyv9Ofayq"
    }
  ]
}

恢复调用 — 提交 follow_up 答案（所有 skill_type 通用，下面以 doc_ppt，mode 为 html 为例）：

{
  "skill_type": "doc_ppt",
  "mode": "html",
  "interaction_response": {
    "type": "follow_up",
    "data": {
      "session_id": "9dbea4d8-b9f7-419c-a4ad-208d4515b8d5",
      "checkpoint_id": "419e8c77-5442-459e-87eb-2637ba53e132",
      "interrupt_id": "45caf5dc-2dd4-48a7-9ba3-8ba2edc67cdd",
      "items": [
        {
          "type": "choice",
          "field": "制作目标",
          "label": "制作目标",
          "options": [
            "内部技术培训宣讲"
          ]
        },
        {
          "type": "multi_choice",
          "field": "重点方面",
          "label": "重点方面",
          "options": [
            "生物特性",
            "文化关联"
          ]
        },
        {
          "type": "text",
          "field": "补充说明",
          "label": "补充说明",
          "text_input": "重点突出接入步骤"
        }
      ]
    }
  }
}

参数说明

• skill_type (string, 必填): 技能类型，决定执行哪条生成流水线。

枚举值：theme_ppt（主题生成 PPT）/ doc_ppt（文档生成 PPT）

• mode (string, 可选): 生成模式，固定传 html（推荐），无需向用户确认。

• input (array[object], 可选): 技能输入内容数组，每项为 {type, content} 对象。与 interaction_response 互斥。

type 枚举：

• text：文本指令或主题描述
• v7_file_id：从金山文档链接提取的 link_id

• interaction_response (object, 可选): 用户对交互问卷的回答，与 input 互斥。

结构固定为 {type, data}，其中 type 和 data 的内容因 skill 而异， 详见 response_detail 中各 skill 的说明。

• business_info (object, 可选): 计费、审核等通用业务信息，不传时服务端按 skill_type × mode 自动推导

返回值说明

{
  "code": 0,
  "message": "success",
  "data": {
    "type": "gen_ppt.done",
    "payload": {
      "total_slides": 12,
      "topic": "长颈鹿主题演示",
      "pptx_url": "https://ks3-cn-beijing.ksyuncs.com/.../merged.pptx",
      "doc_url": "https://365.kdocs.cn/l/yyyyy",
      "slide_images": [
        { "slide_index": 0, "image_url": "https://ks3.../slide_0.png", "task_id": "...", "provider": "IMAGE_V1" }
      ],
      "slide_files": [
        { "slide_index": 0, "file_url": "https://ks3.../slide_0.pptx" }
      ]
    },
    "need_interaction": false
  }
}

SSE 流通过 message 事件推送步骤状态，最终以 finish 事件结束。 当某步骤事件携带 need_interaction: true 时，SSE 流关闭，需要收集用户输入后再次调用。

---

工具速查表

附录

错误处理

认证详情与故障排除

何时打开：auth login 失败需手动获取 Token / 需要诊断认证状态 / 需要退出登录。日常使用无需阅读。

诊断与退出

手动获取 Token（login 失败时的兜底方案）

当 kdocs-cli auth login 因环境问题执行失败时，引导用户手动获取：

1. 打开 WPS 云文档 微信小程序 → 我 → 龙虾专属入口 → 复制 Token 2. 用户将 Token 提供给 Agent 3. Agent 保存到密钥链：kdocs-cli auth set-token "<TOKEN>"

多维表格（dbt）工具完整参考文档

本文件包含金山文档 Skill 多维表格的操作说明。

---

一、数据表管理

数据表的 Schema 查询、增删改与批量操作

二、视图管理

视图的增删改查与列表

三、字段管理

字段的增删改

四、记录操作

记录的增删改查

五、表单视图

表单视图的元数据与字段管理

六、父子记录

层级关系的绑定、解绑、状态与列表

七、分享视图

视图分享的开启、关闭、权限、状态

八、高级权限

角色与主体的权限管理与异步任务

九、仪表盘

仪表盘的列表与复制

十、Webhook 与开放协作

Webhook 的创建、列表、删除

工具组合速查

---

获取记录工具使用指南

---

错误速查表

---

附录

字段类型

视图类型

筛选规则（filter op）

错误响应

仪表盘

1. dbsheet.dashboard_copy

功能说明

前置条件：dashboard_id 来自 dbsheet.dashboard_list。

操作约束

• 后置验证：dashboard_list 确认副本已创建

幂等性：否 — 重复调用可能产生多个副本，先确认是否已成功

调用示例

复制：

{
  "file_id": "string",
  "dashboard_id": 2,
  "body": {
    "name": "副本-仪表盘"
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• dashboard_id (integer, 必填): 源仪表盘 ID
• body (object, 必填): JSON 请求体，须含 name（新仪表盘名称）

body 根级必填

其它可选字段见 copy-dashboard 文档。

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

2. dbsheet.dashboard_list

功能说明

必填 query：无。

调用示例

列出仪表盘：

{
  "file_id": "string"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

数据表管理

1. dbsheet.get_schema

功能说明

获取多维表格文档的 Schema 信息，包括所有数据表、字段和视图的结构。可指定单个数据表 ID，不填则返回全部。

调用示例

获取全部数据表结构：

{
  "file_id": "string"
}

获取指定数据表结构：

{
  "file_id": "string",
  "sheet_id": 1
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 可选): 指定数据表 ID，不填则返回所有表
• reserve_no_permission_sheet (boolean, 可选): 是否保留无权限的表；默认值：false
• show_very_hidden (boolean, 可选): 是否显示深度隐藏的表；默认值：true
• include_all_record_ids (boolean, 可选): 是否返回所有记录 ID；默认值：false

返回值说明

{
  "detail": {
    "sheets": [
      {
        "id": 3,
        "name": "数据表",
        "primary_field_id": "B",
        "records_count": 100,
        "record_ids": ["A", "B"],
        "fields": [
          { "id": "B", "name": "名称", "type": "SingleLineText", "description": "字段备注" },
          { "id": "C", "name": "数量", "type": "Number", "description": "字段备注" }
        ],
        "views": [
          { "id": "B", "name": "表格视图", "type": "grid", "records_count": 10 }
        ]
      }
    ],
    "book_type": "db"
  },
  "result": "ok"
}

---

2. dbsheet.create_sheet

功能说明

在多维表格文档中创建新的数据表，支持同时指定初始视图和字段。fields[] 中每个字段必须包含 name、type，字段专属参数直接平铺在字段对象根级（无 data 包装层）。

操作约束

• 后置验证：get_schema 确认数据表已创建

幂等性：否 — 重复调用会创建多个数据表，先确认是否已成功

此接口的 fields[] 配置不使用 data 包装层，所有字段属性（如 items、numberFormat）直接写在字段对象根级

dbsheet.create_sheet 与 dbsheet.create_fields 在字段参数结构上保持一致：字段专属参数均直接平铺在字段对象根级

视图类型（views[].type）请求传入小写（如 grid），响应返回首字母大写（如 Grid）

Url 字段传字符串时地址和显示文本相同；传对象时可分别设置 address 和 displayText

需要对字段做精细配置（如日期格式、关联目标表等）时，建议创建数据表后再通过 dbsheet.update_fields 补充

调用示例

创建带初始字段的数据表：

{
  "file_id": "string",
  "name": "新数据表",
  "views": [
    {
      "name": "默认视图",
      "type": "grid"
    }
  ],
  "fields": [
    {
      "name": "名称",
      "type": "SingleLineText"
    },
    {
      "name": "状态",
      "type": "SingleSelect",
      "items": [
        {
          "value": "待处理"
        },
        {
          "value": "已完成"
        }
      ]
    }
  ]
}

参数说明

• file_id (string, 必填): 多维表格文件 ID（路径参数）
• name (string, 必填): 数据表名称
• sync_type (string, 可选): 同步类型；默认值：None
• after_sheet_id (integer, 可选): 插入到指定数据表之后
• before_sheet_id (integer, 可选): 插入到指定数据表之前
• views (array, 可选): 初始视图列表（见 param_detail 视图类型枚举）
• name (string, 必填): 视图名称
• type (string, 必填): 视图类型枚举，小写，如 grid、kanban、gallery 等（见 param_detail）
• fields (array, 可选): 初始字段列表（见 param_detail 字段类型枚举与参数明细）；字段配置直接平铺在字段对象根级（无 data 包装层）
• name (string, 必填): 字段显示名称
• type (string, 必填): 字段类型枚举（见 param_detail）
• syncField (boolean, 可选): 是否为同步字段，默认 false
• width (integer, 可选): 字段宽度，单位缇（1/1440 英寸）
• 类型专属参数直接平铺（如 items、numberFormat、max、linkSheet 等）

请求体根级

`fields[]` 通用参数

---

字段类型枚举（`fields[].type`）

---

各字段类型的可用参数（创建字段配置）

说明：以下参数都直接写在 fields[] 元素根级，不使用 data。

---

视图类型枚举（`views[].type`）

请求传入小写，响应返回首字母大写（如请求 grid → 响应 Grid）。

---

各字段类型的记录值传入格式（写记录时参考）

返回值说明

{
  "detail": {
    "sheet": {
      "id": 6,
      "name": "sheetName",
      "primaryFieldId": "L",
      "fields": [
        { "id": "L", "name": "field1", "type": "SingleLineText" },
        {
          "id": "M",
          "name": "field2",
          "type": "SingleSelect",
          "items": [
            { "id": "K", "value": "A" },
            { "id": "L", "value": "B" },
            { "id": "M", "value": "C" }
          ]
        }
      ],
      "views": [
        { "id": "J", "name": "view1", "type": "Grid" },
        { "id": "K", "name": "view2", "type": "Kanban" },
        { "id": "L", "name": "view3", "type": "Gallery" }
      ]
    }
  },
  "result": "ok"
}

---

3. dbsheet.update_sheet

功能说明

修改数据表的名称或主字段设置。

操作约束

• 前置检查：get_schema 确认目标数据表存在

幂等性：是

调用示例

重命名数据表：

{
  "file_id": "string",
  "sheet_id": 6,
  "name": "新名称"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 目标数据表 ID
• name (string, 可选): 新名称
• prefer_id (boolean, 可选): 是否使用字段 ID 作为 key
• primary_field (string, 可选): 主字段名称

返回值说明

{
  "detail": {
    "sheet": {
      "id": 6,
      "name": "新名称",
      "primary_field_id": "L",
      "fields": [],
      "views": []
    }
  },
  "result": "ok"
}

---

4. dbsheet.delete_sheet

功能说明

删除多维表格中的指定数据表。

操作约束

• 前置检查：get_schema 核对拟删数据表的名称和内容
• 用户确认：删除数据表不可恢复，必须向用户确认数据表名称和 ID

幂等性：是

调用示例

删除数据表：

{
  "file_id": "string",
  "sheet_id": 6
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 要删除的数据表 ID

返回值说明

{
  "detail": {
    "sheet": { "id": 6 }
  },
  "result": "ok"
}

---

5. dbsheet.sheet_batch_create

功能说明

前置条件：有创建数据表权限；单次批量条数与字段结构以文档上限为准。

操作约束

• 后置验证：建议 dbsheet.get_schema 核对

幂等性：否 — 重复调用会创建多个数据表，先确认是否已成功

调用示例

批量建表：

{
  "file_id": "string",
  "body": {
    "sheets": []
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• body (object, 必填): JSON 请求体，须含 sheets 数组，数组元素描述待建数据表

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

6. dbsheet.sheet_batch_delete

功能说明

前置条件：确认目标 sheet_ids 内数据均可删除；不可逆。

操作约束

• 前置检查：get_schema 确认待删数据表名称和内容
• 用户确认：删除后表及记录不可恢复

幂等性：否 — 不可恢复操作，禁止自动重试

调用示例

批量删除：

{
  "file_id": "string",
  "body": {
    "sheet_ids": [
      2,
      3
    ]
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• body (object, 必填): JSON 请求体，须含 sheet_ids 字段，数组元素为待删除数据表 ID

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

字段管理

1. dbsheet.create_fields

功能说明

在指定数据表中批量创建字段。请求体为 JSON：fields[] 每项含 name、type 及类型特有属性（直接平铺在字段根级，无 `data` 包装层）；详见 param_detail 中各字段类型定义。创建成功后由服务端分配字段 id，创建请求中禁止手填 `id`。

操作约束

• 禁止：创建请求中禁止手填 id，id 仅由服务端分配
• 后置验证：get_schema 确认字段已创建

幂等性：否 — 重复调用会创建重复字段，先确认是否已成功

字段专属属性（如 items、numberFormat、max 等）直接平铺在字段对象根级，不存在 `data` 包装层。

选项类字段（SingleSelect/MultipleSelect）的 items 直接写在字段根级；响应中 items[].id 由服务端分配，创建时只需传 value（和可选 color）。

身份证字段类型名为 ID；部分历史示例写作 Id，以平台校验为准。

prefer_id 为 true 时，Lookup 的 linkField/lookupField、LastModifiedBy/LastModifiedTime 的 watchedField 须传字段 id 而非字段名。

调用示例

创建多种类型字段：

{
  "file_id": "string",
  "sheet_id": 3,
  "prefer_id": false,
  "fields": [
    {
      "name": "Field A",
      "type": "Checkbox",
      "width": 1080,
      "syncField": false
    },
    {
      "name": "Field B",
      "type": "SingleSelect",
      "allowAddItemWhenInputting": true,
      "items": [
        {
          "value": "待处理"
        },
        {
          "value": "进行中"
        },
        {
          "value": "已完成"
        }
      ],
      "syncField": false
    },
    {
      "name": "Field C",
      "type": "Rating",
      "max": 5,
      "syncField": false
    },
    {
      "name": "Field D",
      "type": "MultiLineText",
      "uniqueValue": false,
      "defaultValue": "Hello",
      "defaultValueType": "Normal",
      "syncField": false
    },
    {
      "name": "Field E",
      "type": "Number",
      "numberFormat": "0.00_ ",
      "syncField": false
    }
  ]
}

参数说明

• file_id (string, 必填): 多维表格文件 ID（路径参数）
• sheet_id (integer, 必填): 数据表 ID
• fields (array, 必填): 待创建字段列表；每项为对象，须含 name、type，类型专属属性直接平铺在字段对象上（无 data 包装层），见 param_detail
• name (string, 必填): 字段显示名称
• type (string, 必填): 字段类型枚举（见 param_detail 完整列表）
• width (integer, 可选): 字段宽度，单位缇（1/1440 英寸）
• syncField (boolean, 可选): 默认 false，是否为同步字段
• 类型专属属性直接平铺（如 items、numberFormat、max 等），无 `data` 包装层
• 禁止在创建请求中传入 id：id 仅创建成功后由服务端返回
• prefer_id (boolean, 可选): 默认 false（以字段名称解析关联）。为 true 时，Lookup 的 linkField/lookupField、LastModifiedBy/LastModifiedTime 的 watchedField 等须传字段 id

请求详情

请求体根级

`fields[]` 通用属性

以下为各 type 的专属属性及录入值说明（字段属性直接平铺在字段对象根级，无 data 包装层）。

---

1. `MultiLineText` 多行文本

无专属创建属性（通用属性 uniqueValue、defaultValue、defaultValueType 适用）。

录入值：string。

---

2. `Date` 日期

录入值：yyyy/mm/dd。

---

3. `Time` 时间

录入值：hh:mm:ss。

---

4. `Number` 数值

录入值：number。

---

5. `Currency` 货币

录入值：number。

---

6. `Percentage` 百分比

录入值：number。

---

7. `ID` 身份证

无专属创建属性（uniqueValue 适用）。

录入值：string。

---

8. `Phone` 电话

无专属创建属性（uniqueValue 适用）。

录入值：string。

---

9. `Email` 电子邮箱

无专属创建属性。

录入值：string。

---

10. `Url` 超链接

录入值：{ "address": "...", "displayText": "..." } 或直接传字符串。

---

11. `Checkbox` 复选框

无专属创建属性。录入值：boolean。

---

12. `SingleSelect` 单选项

录入值：string。

---

13. `MultipleSelect` 多选项

同 SingleSelect。录入值：string[]。

---

14. `Rating` 等级

录入值：int。

---

15. `Complete` 进度条

无专属创建属性。录入值：int（0 ~ 100）。

---

16. `Contact` 联系人

录入值：[{ id, nickname, avatar_url }]。

---

17. `Attachment` 附件

无专属创建属性。

录入值：[{ uploadId, fileName, size, source, type, linkUrl, imgSize }]。

---

18. `Link` 关联

录入值：["record_id_1", "record_id_2"]。

---

19. `Note` 富文本

无专属创建属性。

录入值：{ "fileId": "...", "summary": "...", "modifyDate": "yyyy/mm/dd hh:mm:ss" }。

---

20. `Address` 地址

录入值：{ "districts": [...], "detail": "..." }。

---

21. `Cascade` 级联

录入值：{ "districts": [...] }。

---

22. `AutoNumber` 编号

自动字段，无需填写记录内容。

---

23. `CreatedBy` 创建者

自动字段，无需填写记录内容。

---

24. `CreatedTime` 创建时间

自动字段，无需填写记录内容。

---

25. `LastModifiedBy` 最后修改者

自动字段，无需填写记录内容。

---

26. `LastModifiedTime` 最后修改时间

自动字段，无需填写记录内容。

---

27. `Formula` 公式

自动字段，无需填写记录内容。

---

28. `Lookup` 引用

自动字段，无需填写记录内容。

---

29. `BarCode` 条码字段

无专属创建属性。录入值：string。

---

30. `SearchLookup` 查找引用

无专属创建属性（配置沿用 Lookup 相关能力）。

---

31. `Button` 按钮

无专属创建属性（按钮行为由前端配置）。

---

32. `OneWayLink` 单向关联

同 Link（isAuto、multipleLinks、linkSheet、filter），但不创建反向关联字段。

录入值：关联记录 id 数组。

---

请求体节选示例

{
  "fields": [
    {
      "name": "单选项",
      "type": "SingleSelect",
      "allowAddItemWhenInputting": true,
      "items": [{ "value": "选项1" }, { "value": "选项2" }]
    },
    {
      "name": "关联",
      "type": "Link",
      "isAuto": true,
      "multipleLinks": true,
      "linkSheet": 12
    }
  ],
  "preferId": false
}

返回值说明

{
  "detail": {
    "fields": [
      {
        "id": "K",
        "name": "状态",
        "type": "SingleSelect",
        "items": [
          { "id": "E", "value": "待处理" },
          { "id": "F", "value": "进行中" },
          { "id": "G", "value": "已完成" }
        ]
      },
      { "id": "L", "name": "截止日期", "type": "Date" }
    ]
  },
  "result": "ok"
}

---

2. dbsheet.update_fields

功能说明

批量更新数据表中已有字段的名称、选项等属性。请求体中 fields[] 每项必须包含 id，类型专属属性直接平铺在字段对象根级（无 data 包装层）。

操作约束

• 前置检查：get_schema 确认目标字段存在及当前属性

幂等性：是

更新字段时，id 为必填项（与创建字段相反，创建时禁止传入 id）；可通过 get_schema 获取字段 id。

选项类字段（SingleSelect / MultipleSelect）更新 items 时，含 id 的项为更新，不含 id 的项为新增，未出现的 id 对应选项会被删除。

字段专属属性（如 items、numberFormat、max 等）直接平铺在字段对象根级，不存在 `data` 包装层。

调用示例

更新日期字段格式：

{
  "file_id": "abc123",
  "sheet_id": 1,
  "fields": [
    {
      "id": "q",
      "name": "日期",
      "type": "Date",
      "numberFormat": "yyyy\"年\"m\"月\"d\"日\";@",
      "defaultValueType": "Normal",
      "defaultValue": "2024/11/23"
    }
  ],
  "prefer_id": true
}

参数说明

• file_id (string, 必填): 多维表格文件 ID（路径参数）
• sheet_id (integer, 必填): 目标数据表 ID
• fields (array, 必填): 待更新字段列表；每项为对象，必须含 id，其余可更新属性与创建字段一致（见 param_detail）
• id (string, 必填): 目标字段 ID（通过 get_schema 获取）
• name (string, 可选): 更新后的字段显示名称
• type (string, 可选): 字段类型，更新时一般与原类型一致
• width (integer, 可选): 字段宽度，单位缇（1/1440 英寸）
• syncField (boolean, 可选): 默认 false，是否为同步字段
• 类型专属属性直接平铺（如 items、numberFormat、max 等），无 `data` 包装层
• prefer_id (boolean, 可选): 默认 false（以字段名称解析关联）。为 true 时，Lookup 的 linkField/lookupField、LastModifiedBy/LastModifiedTime 的 watchedField 等须传字段 id

请求详情

请求体根级

`fields[]` 通用属性（更新）

以下为各 type 的专属属性说明。字段属性直接平铺在字段对象根级，无 data 包装层。

---

1. `MultiLineText` 多行文本

无专属更新属性（通用属性 uniqueValue、defaultValue、defaultValueType 适用）。

---

2. `Date` 日期

---

3. `Time` 时间

---

4. `Number` 数值

---

5. `Currency` 货币

---

6. `Percentage` 百分比

---

7. `ID` 身份证

无专属更新属性（uniqueValue 适用）。

---

8. `Phone` 电话

无专属更新属性（uniqueValue 适用）。

---

9. `Email` 电子邮箱

无专属更新属性。

---

10. `Url` 超链接

---

11. `Checkbox` 复选框

无专属更新属性。

---

12. `SingleSelect` 单选项

---

13. `MultipleSelect` 多选项

同 SingleSelect 的 allowAddItemWhenInputting、autoAddItem、items。

---

14. `Rating` 等级

---

15. `Complete` 进度条

无专属更新属性。

---

16. `Contact` 联系人

---

17. `Attachment` 附件

---

18. `Link` 关联

---

19. `Note` 富文本

无专属更新属性。

---

20. `Address` 地址

---

21. `Cascade` 级联

---

22. `AutoNumber` 编号

---

23. `CreatedBy` 创建者

---

24. `CreatedTime` 创建时间

---

25. `LastModifiedBy` 最后修改者

---

26. `LastModifiedTime` 最后修改时间

---

27. `Formula` 公式

---

28. `Lookup` 引用

---

29. `BarCode` 条码字段

无专属更新属性。

---

30. `SearchLookup` 查找引用

无专属更新属性（配置沿用 Lookup 相关能力）。

---

31. `Button` 按钮

无专属更新属性（按钮行为由前端配置）。

---

32. `OneWayLink` 单向关联

同 Link（isAuto、multipleLinks、linkSheet、filter），但不创建反向关联字段。

---

请求体节选示例

{
  "fields": [
    { "id": "q", "name": "日期", "type": "Date", "numberFormat": "yyyy\"年\"m\"月\"d\"日\";@", "defaultValueType": "Normal", "defaultValue": "2024/11/23" },
    { "id": "E", "name": "优先级", "type": "SingleSelect", "allowAddItemWhenInputting": true, "items": [{ "id": "B", "value": "低" }, { "id": "H", "value": "中" }, { "value": "紧急" }] }
  ],
  "prefer_id": true
}

返回值说明

{
  "code": 0,
  "msg": "",
  "data": {
    "fields": [
      {
        "name": "日期",
        "type": "Date",
        "id": "q",
        "defaultValue": "2024/11/23",
        "defaultValueType": "Normal",
        "numberFormat": "yyyy\"年\"m\"月\"d\"日\";@"
      }
    ]
  }
}

---

3. dbsheet.delete_fields

功能说明

批量删除数据表中的指定字段。

操作约束

• 前置检查：get_schema 核对拟删字段的名称和类型
• 用户确认：删除字段不可恢复，字段数据将永久丢失，必须向用户确认字段列表

幂等性：是

调用示例

删除多个字段：

{
  "file_id": "string",
  "sheet_id": 3,
  "fields": [
    {
      "id": "C"
    },
    {
      "id": "D"
    }
  ]
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 目标数据表 ID
• fields (array, 必填): 要删除的字段列表，每项包含 id

返回值说明

{
  "detail": {
    "fields": [
      { "id": "C", "deleted": true },
      { "id": "D", "deleted": true }
    ]
  },
  "result": "ok"
}

---

表单视图

1. dbsheet.form_list_fields

功能说明

必填 query：无。

前置条件：view_id 必须为 Form（表单） 视图；可用 dbsheet.get_schema / dbsheet.views_list 确认 type 为表单。

调用示例

列出表单字段：

{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "FormViewId"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• view_id (string, 必填): 表单视图 ID（非 Grid 等）

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

2. dbsheet.form_update_field

功能说明

前置条件：表单视图；field_id 来自 list_fields。

操作约束

• 后置验证：可用 dbsheet.form_list_fields 核对

幂等性：是

调用示例

更新字段：

{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "FormViewId",
  "field_id": "fld_1",
  "body": {
    "field": {}
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• view_id (string, 必填): 表单视图 ID
• field_id (string, 必填): 表单字段 ID
• body (object, 必填): 须含 field 对象

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

3. dbsheet.form_get_meta

功能说明

必填 query：无。

前置条件：view_id 为表单视图。

调用示例

获取 meta：

{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "FormViewId"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• view_id (string, 必填): 表单视图 ID

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

4. dbsheet.form_update_meta

功能说明

前置条件：表单视图。

幂等性：是

调用示例

更新 meta：

{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "FormViewId",
  "body": {
    "meta": {}
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• view_id (string, 必填): 表单视图 ID
• body (object, 必填): JSON 请求体，须含 meta 对象

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

父子记录

1. dbsheet.parent_disable

功能说明

前置条件：数据表已配置父子字段；仅影响前端展示逻辑，以文档说明为准。

操作约束

• 提示：行为以接口说明为准

幂等性：是

调用示例

禁用：

{
  "file_id": "string",
  "sheet_id": 1,
  "body": {}
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• body (object, 可选): JSON 请求体，补充附加参数；无需附加则传空对象

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

2. dbsheet.parent_enable

功能说明

前置条件：同 disable-parent；仅前端展示语义。

幂等性：是

调用示例

启用：

{
  "file_id": "string",
  "sheet_id": 1,
  "body": {}
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• body (object, 可选): JSON 请求体，补充附加参数；无需附加则传空对象

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

3. dbsheet.parent_status

功能说明

必填 query：无。

调用示例

查询状态：

{
  "file_id": "string",
  "sheet_id": 1
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID

返回值说明

{
  "result": "ok",
  "detail": { "enable": true }
}

---

4. dbsheet.parent_bind_children

功能说明

前置条件：表已启用父子；parent_id 为合法父记录 ID；child_ids 为待挂接子记录 ID 列表。

操作约束

• 前置检查：确认 parent_id、record_ids 均存在且符合层级规则

幂等性：否 — 重复绑定可能报错，先确认当前绑定关系

调用示例

绑定子记录：

{
  "file_id": "string",
  "sheet_id": 1,
  "parent_id": "parent_rec",
  "body": {
    "child_ids": [
      "child_1",
      "child_2"
    ]
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• parent_id (string, 必填): 父记录 ID
• body (object, 必填): JSON 请求体，包含 child_ids

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

5. dbsheet.parent_list_children

功能说明

必填 query：以接口约定为准（若有分页、过滤参数须从文档抄写参数名）。

前置条件：父子关系已配置；parent_id 有效。

调用示例

列出子记录：

{
  "file_id": "string",
  "sheet_id": 1,
  "parent_id": "parent_rec"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• parent_id (string, 必填): 父记录 ID

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

6. dbsheet.parent_unbind_children

功能说明

前置条件：同 batch_bind；child_ids 为待解绑子记录。

操作约束

• 前置检查：parent_list_children 确认绑定关系
• 提示：解绑可能影响树形视图与筛选

幂等性：否 — 解绑后再次调用无效，先确认当前绑定关系

调用示例

解绑：

{
  "file_id": "string",
  "sheet_id": 1,
  "parent_id": "parent_rec",
  "body": {
    "child_ids": [
      "child_1"
    ]
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• parent_id (string, 必填): 父记录 ID
• body (object, 必填): JSON 请求体，包含 child_ids

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

高级权限

1. dbsheet.permission_list_roles

功能说明

必填 query：以接口约定为准（通常无或仅有筛选类参数）。

前置条件：文档已开通高级权限 / 内容权限能力；否则可能返回业务错误。

返回中的系统预置角色与自定义角色区分方式以接口约定为准。

调用示例

列举角色：

{
  "file_id": "string"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

2. dbsheet.permission_query_task

功能说明

必填 query：task_type（异步任务类型）。

前置条件：task_id 来自「新增/更新/删除自定义角色」等异步接口返回。

调用示例

查询任务：

{
  "file_id": "string",
  "task_id": "task_xxx",
  "task_type": "content_permission"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• task_id (string, 必填): 异步任务 ID
• task_type (content_permission, 必填): 异步任务类型（query 参数）

请求参数

异步类接口提交后须轮询本工具直至状态为完成或失败，勿用相同 body 盲目重试创建接口。

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

3. dbsheet.permission_create_roles_async

功能说明

前置条件：文档已开启高级权限；调用方有管理权限配置能力。

操作约束

• 后置验证：轮询 dbsheet.permission_query_task 直至结束

幂等性：否 — 先 permission_query_task 再决定是否重试

调用示例

创建角色：

{
  "file_id": "string",
  "body": {
    "content_permission_name": "销售只读",
    "permission_data": [
      {
        "sheet_id": 0,
        "sheet_permission_type": "Permission_View",
        "record_config_type": "All",
        "viewed_sheet_config": {
          "field_filter": [
            "fld_xxx"
          ],
          "is_all_field": false,
          "is_all_record": true
        }
      }
    ]
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• body (object, 必填): JSON 请求体，包含 content_permission_name、permission_data

body 根级必填

`permission_data[]` 字段

`sheet_permission_type` 条件必填约束

• 当 sheet_permission_type=Permission_Edit：
• 必须传 edit_sheet_config 与 viewed_sheet_config。
• edit_sheet_config 内必须传 field_filter 与 is_all_field，且 is_all_field 必须为 false。
• viewed_sheet_config 内必须传 field_filter 与 is_all_field，且 is_all_field 必须为 false。
• 当 sheet_permission_type=Permission_View：
• 必须传 viewed_sheet_config。
• viewed_sheet_config 内必须传 field_filter 与 is_all_field，且 is_all_field 必须为 false。

`edit_sheet_config` 字段

`viewed_sheet_config` 字段

`record_filter` 字段

`criteria[]` 字段

`criteria[].values` 取值数量限制

• Empty、NotEmpty：不允许填写元素。
• GreaterEquAndLessEqu、LessOrGreater（介于类规则）：最多 2 个元素。
• Intersected：最多 65535 个元素。
• 其他规则：最多 1 个元素。

返回值说明

{
  "result": "ok",
  "detail": { "task_id": "..." }
}

---

4. dbsheet.permission_update_roles_async

功能说明

前置条件：角色已存在；文档开启高级权限。

操作约束

• 后置验证：轮询 permission_query_task

幂等性：否 — 先 permission_query_task 确认状态再决定是否重试

调用示例

更新角色：

{
  "file_id": "string",
  "body": {
    "cloud_permission_id": 0,
    "content_permission_name": "销售只读",
    "permission_data": [
      {
        "sheet_id": 0,
        "sheet_permission_type": "Permission_View",
        "record_config_type": "All",
        "viewed_sheet_config": {
          "is_all_field": true,
          "is_all_record": true
        }
      }
    ]
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• body (object, 必填): JSON 请求体，包含 cloud_permission_id、content_permission_name、permission_data

body 根级必填

`permission_data[]` 字段

`edit_sheet_config` 字段

`viewed_sheet_config` 字段

`edit_sheet_config.record_filter` 与 `viewed_sheet_config.record_filter` 字段

`record_filter.criteria[]` 字段

`record_filter.criteria[].values` 取值数量限制

• Empty、NotEmpty：不允许填写元素。
• GreaterEquAndLessEqu、LessOrGreater（介于类规则）：最多 2 个元素。
• Intersected：最多 65535 个元素。
• 其他规则：最多 1 个元素。

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

5. dbsheet.permission_delete_roles_async

功能说明

前置条件：待删角色无不可解除的依赖；文档开启高级权限。

操作约束

• 前置检查：permission_list_roles 确认目标角色
• 用户确认：删除角色将影响已绑定成员的能力

幂等性：否 — 先 permission_query_task 确认状态再决定是否重试

调用示例

删除角色：

{
  "file_id": "string",
  "body": {
    "cloud_permission_id": 0,
    "replace_cloud_permission_id": 0,
    "replace_permission_type": "system"
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• body (object, 必填): JSON 请求体，包含 cloud_permission_id、replace_cloud_permission_id、replace_permission_type

body 根级必填

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

6. dbsheet.permission_list_subjects

功能说明

前置条件：文档已开启高级权限；cloud_permission_id 可与 dbsheet.permission_list_roles 返回体中的云权限 ID 对照填写。 请求方式：GET，请通过 query 传递 cloud_permission_id、permission_type 等参数。

若业务未开通高级权限，接口可能失败，与参数是否完整无关。

调用示例

最小必填参数：

{
  "file_id": "string",
  "cloud_permission_id": 1,
  "permission_type": "system"
}

携带分页与别名：

{
  "file_id": "string",
  "cloud_permission_id": 1,
  "permission_type": "content_custom",
  "alias_name": "viewable",
  "page_token": "next_page_token"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• cloud_permission_id (integer, 必填): 云权限 ID（query 参数）
• permission_type (string, 必填): 权限组类型（query 参数），可选值：system、team_custom、content_custom
• alias_name (string, 可选): 权限别名（query 参数）；拿不到 permission_id 时可传，可选值：manageable、viewable、editable
• page_token (string, 可选): 分页起始位置标识（query 参数），首页可不传，默认每页约 20 条

请求参数

返回值说明

{
  "result": "ok",
  "detail": {}
}

---

记录操作

1. dbsheet.create_records

功能说明

在指定数据表中批量创建记录。每条记录通过 fields 字段传入一个序列化的 JSON 字符串， 字符串内部为字段名（或字段 ID）到值的映射。

操作约束

• 后置验证：调用 list_records 或 get_record 确认记录已创建

幂等性：否 — 重复调用会插入重复记录，先确认是否已成功

records[].fields 是对象（key-value 映射），不是序列化 JSON 字符串

关联字段（Link）值格式为关联记录 id 的字符串数组，如 ["id1", "id2"]

prefer_id=true 时，fields 内部的 key 应为字段 ID（由 get_schema 返回），而非字段名

b_add_select_item=true 时，可通过 field_values 提前声明要新增的选项；若不声明，选项名称直接写入 fields 中也会触发新增

text_value 和 link_value 仅影响响应返回格式，不影响写入行为

Url 字段传入为对象 {address, displayText}，响应中以数组形式返回

Rating 字段的上限由 max/max_value 定义，可通过 get_schema 查询

调用示例

按字段名批量创建记录：

{
  "file_id": "VsdfG0001234567",
  "sheet_id": 3,
  "prefer_id": false,
  "records": [
    {
      "fields": {
        "文本": "第一行文本",
        "日期": "2024/12/20"
      }
    },
    {
      "fields": {
        "文本": "第二行文本",
        "日期": "2024/12/21"
      }
    }
  ]
}

创建记录时同步新增选项：

{
  "file_id": "VsdfG0001234567",
  "sheet_id": 3,
  "b_add_select_item": true,
  "field_values": [
    {
      "fieldId": "E",
      "listItems": [
        {
          "value": "选项30",
          "color": "0xF0EEF7"
        }
      ]
    }
  ],
  "records": [
    {
      "fields": {
        "名称": "Hello",
        "数量": 123,
        "记录关联": [
          "I",
          "G"
        ]
      }
    },
    {
      "fields": {
        "数量": 666
      }
    }
  ]
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• records (array[object], 必填): 要创建的记录列表，每个元素含 fields 对象（字段名/ID → 值的映射）
• prefer_id (boolean, 可选): 是否使用字段 ID 作为 key；默认 false（使用字段名），为 true 时 fields 内部的 key 应为字段 ID
• value_prefer_id (boolean, 可选): 是否使用选项 ID 作为 选项值，默认为 false
• omit_failure (boolean, 可选): 单条记录创建失败是否不中断整批请求，默认为 false
• text_value (string, 可选): 响应返回值格式：original 返回原始值（默认）、text 返回文本值、compound 同时返回原始值和文本值
• link_value (string, 可选): 关联字段响应格式：id 仅返回关联记录 id（默认）；all 返回 id 和文本
• b_add_select_item (boolean, 可选): 是否允许在写入记录时同步新增选项（配合 field_values 使用）
• field_values (array, 可选): 创建记录时需要新增的选项配置列表，每项含 fieldId（字段 ID）和 listItems（待新增选项数组，每项含 value 和 color）

请求体根级参数

`records[]` 元素结构

`fieldValues[]` 元素结构

`fields` 对象各字段类型填写规范

字段类型定义及 data 配置可参考 dbsheet.create_fields（param_detail 各类型节）。

请求体示例

{
  "sheetId": 3,
  "preferId": false,
  "bAddSelectItem": true,
  "fieldValues": [
    {
      "fieldId": "E",
      "listItems": [{ "value": "选项30", "color": "0xF0EEF7" }]
    }
  ],
  "records": [
    {
      "fields": {
        "名称": "Hello",
        "数量": 123,
        "记录关联": ["I", "G"]
      }
    },
    {
      "fields": { "数量": 666 }
    }
  ]
}

fields 反序列化后内容（各字段类型对应值）：

Formula、AutoNumber、CreatedTime、CreatedBy、LastModifiedBy、Lookup 为系统自动字段，无需传入。

返回值说明

{
  "code": 0,
  "msg": "",
  "data": {
    "records": [
      {
        "fields": "{\"日期\":\"2025/11/15\",\"数字\":125,\"公式\":340,\"创建人\":{\"id\":\"280026893\",\"nickName\":\"霧雨澪音\"},\"创建时间\":\"2024/12/09 17:47:18\",\"最后修改者\":{\"id\":\"280026893\",\"nickName\":\"霧雨澪音\"},\"最后修改时间\":\"2024/12/09 17:47:18\",\"编号\":2}",
        "id": "V"
      }
    ]
  }
}

---

2. dbsheet.update_records

功能说明

批量更新数据表中已有记录的字段值。每条记录必须提供 id（记录 ID）和 fields （序列化的 JSON 字符串，内容为字段名或字段 ID 到新值的映射）。

操作约束

• 前置检查：调用 list_records 或 get_record 确认目标记录 ID 存在及当前字段值
• 后置验证：调用 get_record 确认字段已更新为预期值

幂等性：是

records[].fields 是对象（key-value 映射），不是序列化 JSON 字符串；仅传入需要修改的字段，未传字段保持原值不变

关联字段（Link）值格式为关联记录 id 的字符串数组，如 ["id1", "id2"]

prefer_id=true 时，fields 内部的 key 应为字段 ID（由 get_schema 返回），而非字段名

b_add_select_item=true 时，可通过 field_values 预声明要新增的选项

text_value 和 link_value 仅影响响应返回格式，不影响写入行为

Url 字段传入为对象 {address, displayText}，响应中以数组形式返回

Rating 字段的上限由 max/max_value 定义，创建字段时通过 dbsheet.create_fields 设置

调用示例

按字段名批量更新记录：

{
  "file_id": "VsdfG0001234567",
  "sheet_id": 3,
  "prefer_id": false,
  "records": [
    {
      "id": "G",
      "fields": {
        "文本": "新的文本",
        "日期": "2024/12/21"
      }
    },
    {
      "id": "H",
      "fields": {
        "文本": "另一行文本",
        "状态": "已完成"
      }
    }
  ]
}

更新记录时同步新增选项：

{
  "file_id": "VsdfG0001234567",
  "sheet_id": 3,
  "b_add_select_item": true,
  "field_values": [
    {
      "fieldId": "E",
      "listItems": [
        {
          "value": "选项30",
          "color": "0xF0EEF7"
        }
      ]
    }
  ],
  "records": [
    {
      "id": "B",
      "fields": {
        "名称": "Hello",
        "数量": 123
      }
    },
    {
      "id": "C",
      "fields": {
        "数量": 666
      }
    }
  ]
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• records (array[object], 必填): 要更新的记录列表，每个元素包含 id（记录 ID）和 fields（序列化 JSON 字符串）
• prefer_id (boolean, 可选): 是否使用字段 ID 作为 key；默认 false（使用字段名），为 true 时 fields 内部的 key 应为字段 ID
• value_prefer_id (boolean, 可选): 是否使用选项 ID 作为 选项值，默认为 false
• omit_failure (boolean, 可选): 单条记录创建失败是否不中断整批请求，默认为 false
• text_value (string, 可选): 响应返回值格式：original 返回原始值（默认）、text 返回文本值、compound 同时返回原始值和文本值
• link_value (string, 可选): 关联字段响应格式：id 仅返回关联记录 id（默认）；all 返回 id 和文本
• b_add_select_item (boolean, 可选): 是否允许在写入记录时同步新增选项（配合 field_values 使用）
• field_values (array, 可选): 更新记录时需要新增的选项配置列表，每项含 fieldId（字段 ID）和 listItems（待新增选项数组，每项含 value 和 color）

请求体根级参数

`records[]` 元素结构

`fieldValues[]` 元素结构

`fields` 对象各字段类型填写规范

字段类型定义及值格式完整说明可参考 dbsheet.create_fields（param_detail 各类型节）。

请求体示例

{
  "sheetId": 3,
  "preferId": false,
  "bAddSelectItem": true,
  "fieldValues": [
    {
      "fieldId": "E",
      "listItems": [{ "value": "选项30", "color": "0xF0EEF7" }]
    }
  ],
  "records": [
    {
      "id": "B",
      "fields": { "名称": "Hello", "数量": 123 }
    },
    {
      "id": "C",
      "fields": { "数量": 666 }
    }
  ]
}

返回值说明

{
  "code": 0,
  "msg": "",
  "data": {
    "records": [
      {
        "id": "B",
        "fields": {
          "名称": "Hello",
          "数量": 123,
          "最后修改者": { "id": "280026893", "nickName": "霧雨澪音" },
          "最后修改时间": "2024/12/09 17:47:18"
        }
      }
    ]
  }
}

---

3. dbsheet.list_records

功能说明

分页遍历数据表中的记录，支持按视图过滤、指定返回字段，以及通过 filter 参数实现复杂查询条件（多字段 AND/OR 组合筛选）。

调用示例

基础分页查询：

{
  "file_id": "string",
  "sheet_id": 1,
  "page_size": 100,
  "offset": "",
  "fields": [
    "名称",
    "状态",
    "截止日期"
  ]
}

带筛选条件查询：

{
  "file_id": "string",
  "sheet_id": 1,
  "page_size": 100,
  "offset": "",
  "filter": {
    "mode": "AND",
    "criteria": [
      {
        "field": "状态",
        "op": "Intersected",
        "values": [
          "进行中"
        ]
      },
      {
        "field": "数量",
        "op": "Greater",
        "values": [
          "10"
        ]
      },
      {
        "field": "名称",
        "op": "Contains",
        "values": [
          "关键词"
        ]
      }
    ]
  }
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 目标数据表 ID
• page_size (integer, 可选): 每页记录数
• offset (string, 可选): 翻页游标，首次请求传空字符串，后续传响应中的 offset 值
• view_id (string, 可选): 按指定视图返回记录
• max_records (integer, 可选): 最多返回的记录总数
• fields (array, 可选): 只返回指定字段列表，不填则返回所有字段
• filter (object, 可选): 筛选条件，含 mode 和 criteria 列表
• mode (string, 必填): 条件连接方式："AND" 或 "OR"
• criteria (array, 必填): 筛选条件列表
• field (string, 必填): 字段名称或 ID
• op (string, 必填): 筛选操作符（见附录：筛选规则）
• values (array, 可选): 筛选值，Empty/NotEmpty 时可省略
• prefer_id (boolean, 可选): 是否使用字段 ID 作为 key
• text_value (string, 可选): 文本值格式："original"（原始值）或 "display"（显示值）
• link_value (string, 可选): 关联字段值格式："id" 或 "value"
• show_record_extra_info (boolean, 可选): 是否返回记录额外信息
• show_fields_info (boolean, 可选): 是否在响应中返回字段定义信息

分页说明：响应中的 offset 指向下一页第一条记录，下次请求将该值传入 offset 即可翻页。最后一页不再返回 offset。

返回值说明

{
  "detail": {
    "offset": "D",
    "records": [
      { "id": "E", "fields": { "名称": "任务A", "状态": "进行中", "数量": 15 } },
      { "id": "F", "fields": { "名称": "任务B", "状态": "进行中", "数量": 20 } }
    ]
  },
  "result": "ok"
}

---

4. dbsheet.get_record

功能说明

获取数据表中某条指定记录的完整字段内容。

调用示例

获取单条记录：

{
  "file_id": "string",
  "sheet_id": 3,
  "record_id": "B"
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 目标数据表 ID
• record_id (string, 必填): 记录 ID
• prefer_id (boolean, 可选): 是否使用字段 ID 作为 key
• text_value (string, 可选): 文本值格式："original"（原始值）或 "display"（显示值）
• link_value (string, 可选): 关联字段值格式："id" 或 "value"
• show_record_extra_info (boolean, 可选): 是否返回记录额外信息
• show_fields_info (boolean, 可选): 是否返回字段定义信息

返回值说明

{
  "detail": {
    "id": "B",
    "fields": {
      "名称": "任务A",
      "数量": 123,
      "日期": "2021/5/1",
      "状态": "未开始"
    }
  },
  "result": "ok"
}

---

5. dbsheet.delete_records

功能说明

批量删除数据表中的指定记录。records 为记录 ID 的对象数组，不是字符串数组。

操作约束

• 前置检查：调用 list_records 或 get_record 核对拟删记录的内容，确认记录 ID 正确
• 用户确认：批量删除记录不可恢复，必须向用户确认记录列表和数量

幂等性：是

records 是对象数组（记录 ID），不是字符串数组；不应该传 ["G"] 等字符串格式，而应该传 [{"id":"G"}] 等对象格式

调用示例

批量删除记录：

{
  "file_id": "VsdfG0001234567",
  "sheet_id": 3,
  "records": [
    {
      "id": "G"
    },
    {
      "id": "H"
    }
  ]
}

参数说明

• file_id (string, 必填): 多维表格文件 ID（路径参数）
• sheet_id (integer, 必填): 数据表 ID
• records (array[string], 必填): 要删除的记录 ID 列表（对象数组，每项为一个记录 ID）

请求体结构：

请求体示例：

{
  "records": [
    { "id": "G" },
    { "id": "H" },
    { "id": "I" }
  ]
}

记录 ID 可通过 dbsheet.list_records 或 dbsheet.get_record 获取。

返回值说明

{
  "code": 0,
  "msg": "",
  "data": {
    "records": [
      { "id": "G", "deleted": true },
      { "id": "H", "deleted": true }
    ]
  }
}

---

6. dbsheet.records_list

功能说明

请求体（均在 JSON 内，无 URL query）

filter.criteria 的结构需符合多维表格接口对筛选条件的约定。

调用示例

最简：

{
  "file_id": "string",
  "sheet_id": 1,
  "body": {}
}

返回文本值并携带额外信息：

{
  "file_id": "string",
  "sheet_id": 1,
  "prefer_id": false,
  "show_fields_info": false,
  "text_value": "text",
  "show_record_extra_info": true
}

分页与视图：

{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B",
  "page_size": 50,
  "page_token": ""
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• body (object, 可选): 可选整包请求体；与顶层字段混用时同键以顶层为准
• fields (array, 必填): 指定所返回记录中的字段信息，若不填写则默认返回全部字段。prefer_id=true 时须用字段 id，否则用字段名
• filter (object, 可选): 筛选条件
• mode (string, 必填): 条件连接方式："AND" 或 "OR"
• criteria (array, 必填): 筛选条件列表，每项包含：
• field (string, 必填): 字段名称或字段 id（由 prefer_id 决定）
• op (string, 必填): 筛选操作符，见多维表格参数说明（如 Contains、Intersected、Greater、Less、Equal、Empty、NotEmpty 等）
• values (array, 可选): 筛选值；Empty / NotEmpty 操作符时可省略
• max_records (integer, 可选): 最多返回前 max_records 条，若不填写则默认返回全部记录
• page_size (integer, 可选): 分页获取记录时的每页大小，默认 100，取值范围 1-1000
• page_token (string, 可选): 分页起始位置。当存在分页且未查询到最后一页或 max_records 记录时，返回值会包含 page_token
• prefer_id (boolean, 可选): 使用 id 来标识字段和选项。为 true 时，参数内全部的 field、fields 参数均按照 id 做解析
• show_fields_info (boolean, 可选): 是否返回一个 fields 结构体，展示字段信息（类似 Base Schema 中的 fields）
• show_record_extra_info (boolean, 可选): 是否返回创建者、创建时间、最后修改者、最后修改时间信息（与是否有对应字段无关）
• text_value (string, 可选): 返回值类型，不填默认为 original。可选：original（原始值）、text（文本值）、compound（原始值和文本值）
• view_id (string, 可选): 指定视图 id。填写后从该视图获取用户所见记录；不填则从工作表获取记录

所有列举参数均在 POST JSON 请求体 中，不拼 URL query。

若同时传 body 与顶层字段，同键以 顶层 为准。

返回值说明

{
  "code": 0,
  "msg": "",
  "data": {
    "fields_schema": [
      {
        "name": "文本",
        "type": "MultiLineText",
        "id": "B",
        "data": { "unique_value": false }
      },
      {
        "name": "数字",
        "type": "Number",
        "id": "C",
        "data": { "number_format": "0.00_ " }
      }
    ],
    "records": [
      {
        "fields": "{\"单选项\":\"选项1\",\"数字\":\"123.00 \",\"文本\":\"第一行文本\",\"日期\":\"2024/12/20\",\"等级\":\"1\"}",
        "id": "B",
        "created_time": "2024/12/20 11:30:32",
        "creator": "280026893",
        "last_modified_by": "280026893",
        "last_modified_time": "2024/12/20 15:47:01"
      }
    ],
    "page_token": ""
  }
}

---

7. dbsheet.records_search

功能说明

请求体（均在 JSON 内，无 URL query）

records 为必填参数，需传入有效的记录 id 列表。

records_search 在 MCP 层若要求 filter 为必填参数，传空条件 {"mode":"AND","criteria":[]} 即可满足

调用示例

按记录 id 批量检索：

{
  "file_id": "string",
  "sheet_id": 1,
  "records": [
    "B",
    "C"
  ]
}

返回文本值并携带额外信息：

{
  "file_id": "string",
  "sheet_id": 1,
  "records": [
    "B",
    "C"
  ],
  "prefer_id": false,
  "show_fields_info": false,
  "text_value": "text",
  "show_record_extra_info": true
}

参数说明

• file_id (string, 必填): 多维表格文件 ID
• sheet_id (integer, 必填): 数据表 ID
• body (object, 可选): 可选整包请求体；与顶层字段混用时同键以顶层为准
• records (array, 必填): 记录 ID 列表，指定要检索的记录
• prefer_id (boolean, 可选): 是否使用字段 / 选项 ID 而不是字段 / 选项名来标识
• show_fields_info (boolean, 可选): 是否返回 fields 结构体展示字段信息。为 true 时，若指定了 fields 则返回指定字段；未指定 fields 时，根据是否指定 view_id 决定返回视图可见字段或全部字段
• show_record_extra_info (boolean, 可选): 是否返回创建者、创建时间、最后修改者、最后修改时间信息（与是否有对应字段无关）
• text_value (string, 可选): 返回值类型，不填默认为 original。可选：original（原始值）、text（文本值）、compound（原始值和文本值）

返回值说明

{
  "code": 0,
  "msg": "",
  "data": {
    "records": [
      {
        "fields": "{\"单选项\":\"选项1\",\"图片和附件\":\"12KB.docx,aigc\",\"数字\":\"123.00 \",\"文本\":\"第一行文本\",\"日期\":\"2024/12/20\",\"等级\":\"1\"}",
        "id": "B"
      },
      {
        "fields": "{\"单选项\":\"选项2\",\"图片和附件\":\"14.4KB.png\",\"数字\":\"321.00 \",\"文本\":\"第二行文本\",\"日期\":\"2024/12/21\",\"等级\":\"2\"}",
        "id": "C"
      }
    ]
  }
}

---