Skill: sky-lv/kdocs-hold (version 1.0.0)

--- name: kdocs description: "操作金山文档（WPS 云文档 / Kdocs / 365.kdocs.cn / www.kdocs.cn）云文档的官方 Skill。核心能力覆盖云端新建、读取、编辑、搜索、分享、整理在线文档（智能文档、Word、Excel、PDF、PPT、演示文稿、智能表格、多维表格）及个人知识库。当用户的任务涉及云文档操作时使用，包括但不限于：写周报/日报/工作汇报、处理合同/发票、创建报名表/登记表、网页剪藏、接龙转表格、信息收集、文档总结与内容生成、改写仿写、翻译、AI PPT生成、PDF拆分导出、标签分类归档、收藏管理、碎片笔记整理、表格美化、回收站还原、知识库管理。" homepage: https://www.kdocs.cn/latest version: 1.4.5 metadata: {"openclaw":{"category":"kdocs","tokenUrl":"https://www.kdocs.cn/latest","emoji":"📝"},"keywords":["金山文档","金山表格","金山收藏","WPS","WPS文档","云文档","在线文档","kdocs","WPS云文档","接龙转表格","接龙","群接龙","报名表","信息收集","收集表","登记表","网页剪藏","剪藏","保存网页","网页保存到文档","保存文章","收藏文章","总结","帮我总结","帮我整理","帮我写","帮我翻译","帮我做PPT","翻译文档 - 做PPT - 生成PPT - 培训课件 - 方案展示 - 项目展示","文档总结","内容生成","改写","仿写","翻译","文档翻译","PPT","演示文稿","幻灯片","PDF","拆分PDF","导出PDF","Word","Excel","表格","Markdown","碎片整理","笔记整理","表格优化","文档处理","文件处理","办公助手","文档助手","周报","日报","工作汇报","合同","发票"],"file_types":["pdf","doc","docx","xlsx","xls","pptx","ppt","otl","ksheet","dbt","jpg","jpeg","png","bmp","gif","webp","url","md","txt","html"],"category":"productivity"} --- # 金山文档 Skill 使用指南 金山文档 Skill 提供了一套完整的在线文档操作工具，支持创建、查询、读取、编辑、分享、移动多种类型的在线文档。 ## 严格规则 ### 禁止（NEVER） - 禁止将 Token 明文出现在对话、日志、命令输出、代码注释或任何文件中；不得写入 `.env` 或环境变量；仅允许存放在 `mcporter` 的 `kdocs-qclaw` 配置中 - 上传写入等接口需传入的 `content_base64` 可能非常大（编码后 >1 MB），禁止在对话中逐 token 生成 Base64 字符串，用脚本完成文件读取、编码和传参 ### 必须（MUST） - 不可逆操作（delete/close 类）执行前必须向用户确认 - 写操作完成后必须用独立读取请求验证实际结果（不信任 `code: 0`） - 创建文档并验证通过后，必须调用 `get_file_link` 获取链接并展示给用户 --- ## 版本自检 首次使用或间隔超过 24 小时后，需要确认当前 Skill 是否为最新版本。 从本文件头部 frontmatter 的 `version` 字段读取本地版本号（语义化版本 X.Y.Z），然后调用远端接口比对： ```bash mcporter call kdocs-qclaw.check_skill_update version=<本地版本号> ``` 返回：`stdout` 为 JSON，包含三个关键字段： | 字段 | 含义 | |------|------| | `latest` | 远端最新版本号 (X.Y.Z) | | `release_note` | 该版本的变更摘要 | | `instruction` | 升级操作步骤 | 若本地版本落后于 `latest`，按 `instruction` 中的指引完成升级或者把最新版信息用户告知用户。升级时需要保留旧版 `mcporter` 配置中的 Token，并将其迁移到新版本配置中。 --- ## 认证配置 ### Token 获取与管理 | 步骤 | 操作 | |------|------| | 读取 | 仅从 `mcporter` 的 `kdocs-qclaw` 配置读取 `Authorization` header；不再依赖 `.env` 或环境变量 | | 获取 | 若 Token 为空或过期（错误码 `400006`），运行 `bash scripts/get-token.sh` 或 `node scripts/get-token.js` 获取新 Token，并直接写入 `mcporter`；mac/Linux 下 `get-token.sh` 会自动尝试打开浏览器登录页；Windows 下若本机有 Node.js，优先运行 `node scripts/get-token.js`，若本机没有 Node.js，则改为运行 `powershell -ExecutionPolicy Bypass -File scripts\get-token.ps1`；如需允许脚本自动安装 `mcporter`，可显式追加 `--auto-install-mcporter`（Node / Bash）或 `-AutoInstallMcporter`（PowerShell）；**脚本失败时改用「手动获取 Token」兜底** | | 配置 | 仅允许将 Token 保存到 `mcporter`；禁止继续写入 `.env`、`KINGSOFT_DOCS_TOKEN` 或其他环境变量 | | 验证 | 调用任意读取工具（如 `search_files`），返回 `code: 0` 即认证成功 | | 过期 | 收到错误码 `400006` 时，Token 已过期，按上述「获取」步骤重新获取 | > ⚠️ **mcporter 中未配置 Token 或 Token 过期时，所有工具调用将返回鉴权失败（400006）。** > 🔒 **Token 安全**：任何时候都不得将 Token 明文值展示给用户、写入 `.env`、导出到环境变量，或拼接到命令中。Token 仅允许保存在 `mcporter` 的 `kdocs-qclaw` 配置中。 > 🚫 **配置名绑定**：本 Skill 的所有 `mcporter` 操作必须且只能使用 `kdocs-qclaw` 这个配置名（`mcporter call kdocs-qclaw ...`、`mcporter config get kdocs-qclaw` 等）。即使本机存在其他名称的 mcporter 配置且可正常调用，也**严禁**使用。若 `kdocs-qclaw` 配置不存在，必须先按下方「环境配置」章节完成注册。 > 🔄 **旧配置迁移**：若检测到历史 `.env` 或环境变量 `KINGSOFT_DOCS_TOKEN`，只允许做一次性迁移到 `mcporter`；`.env` 仅移除 `KINGSOFT_DOCS_TOKEN` 键（其他键保留），若 `.env` 仅含该键则直接删除空 `.env` 文件。 > 🛡️ **避免改动系统环境**：默认不会执行 `npm install -g` 这类全局安装命令；只有你明确加上参数时，才会自动安装 `mcporter`（Node / bash: `--auto-install-mcporter`，PowerShell: `-AutoInstallMcporter`）。 #### 手动获取 Token（脚本失败时的兜底方案） 当 `get-token` 脚本因环境问题执行失败时，引导用户手动获取： 1. 用户在浏览器访问 https://www.kdocs.cn/latest （需已登录 WPS 账号） 2. 点击页面右上角个人头像旁的主菜单 → 选择「龙虾专属入口」→ 复制 Token 3. 用户将 Token 提供给 Agent 4. Agent 将 Token 写入 mcporter（`<VERSION>` 从 SKILL.md frontmatter 的 `version` 字段读取）： ```bash mcporter config remove kdocs-qclaw 2>/dev/null; mcporter config add kdocs-qclaw "https://mcp-center.wps.cn/skill_hub/mcp" --header "Authorization=Bearer <TOKEN>" --header "X-Skill-Version=<VERSION>" --header "X-Request-Source=qclaw" --transport http --scope home ``` > 收到用户 Token 后直接写入 mcporter，禁止回显 Token 明文。写入后调用任意读取工具验证（`code: 0` 即成功）。 ### 环境配置 本 Skill 通过 MCP 协议提供服务，不限定特定客户端，可在任何支持 MCP 的 Agent 中运行（如 OpenClaw、Cursor、Claude Code 等）。 **自动化注册（mcporter 环境）**：运行 `bash scripts/setup.sh` 即可完成 MCP 服务注册。首次使用时会自动拉起授权；若检测到 Token 过期，`setup.sh` 也会自动调用 `get-token.sh` 重新获取。mac/Linux 下 `get-token.sh` 会自动尝试打开浏览器登录页并等待回调完成。默认不会自动全局安装 `mcporter`，若需要可显式追加 `--auto-install-mcporter`。 `scripts/setup.sh` 会自动完成： 1. 从 `SKILL.md` frontmatter 提取 `version` 版本号 2. 检查 `mcporter` 中现有的 `kdocs-qclaw` 配置，并在版本更新时保留旧 Token 3. 若检测到历史 `.env` 或环境变量 `KINGSOFT_DOCS_TOKEN`，仅做一次性迁移到 `mcporter`（`.env` 只移除 token 键并保留其他配置） 4. 注册 `mcporter` 时携带 `Authorization`、`X-Skill-Version` 和 `X-Request-Source` header，用于服务端鉴权、版本追踪和渠道区分 **手动配置（其他 MCP 客户端）**：在客户端 MCP 配置中添加金山文档服务时，仅维护 `mcporter` 中的 `kdocs-qclaw` 配置；不要再额外维护 `.env` 或 `KINGSOFT_DOCS_TOKEN`。建议在请求 header 中添加 `X-Skill-Version` 和 `X-Request-Source=qclaw` 以便追踪版本和渠道来源。 --- ## 调用格式 根据运行环境选择对应方式： - **MCP function call**（Cursor / Claude Code 等客户端）：直接构造 JSON，无需处理引号或转义： ```json {"name": "otl.insert_content", "arguments": {"file_id": "xxx", "content": "hello", "format": "markdown", "mode": "append"}} {"name": "read_file_content", "arguments": {"drive_id": "xxx", "file_id": "xxx", "format": "markdown", "include_elements": ["all"]}} ``` - **mcporter CLI**：`mcporter call` 按首个 `.` 拆分 `服务名.工具名`，工具名含点号时须分开传递以防截断： ``` mcporter call kdocs-qclaw "otl.insert_content" file_id=xxx mcporter call kdocs-qclaw search_files keyword=test type=all ``` - **数组/对象参数**：`key=value` 无法表达数组或对象，须用 `--args` 传 JSON - **值含空格或特殊字符**：值需引号包裹使其成为单个参数，如 `name="项目 周报.otl"` - **bash**：`--args` 用单引号包裹 JSON 即可：`--args '{"include_elements":["all"]}'` - **PowerShell**：单引号内的双引号会被吞掉，须用反斜杠转义：`--args '{\"include_elements\":[\"all\"]}'` 以下工具不可逆，调用前必须向用户确认（详细约束见各工具参考文档的「操作约束」区）： `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` --- ## 能力范围 ### 支持的文档类型 | 类型 | 别名 | 文件后缀 | 说明 | 详细参考 | |------|------|----------|------|----------| | **智能文档** 首选 | ap | .otl | 排版美观，支持丰富组件 | `references/otl.md` — 页面、文本、标题、待办等元素操作 | | 表格 | et / Excel | .xlsx | 数据表格专用 | `references/sheet.md` — 工作表管理、范围数据获取、批量更新 | | PDF文档 | pdf | .pdf | PDF 文档专用 | `references/pdf.md` — PDF 创建与内容读取 | | 文字文档 | wps / Word | .docx | 传统格式 | `references/wps.md` — Word 文档创建与内容操作 | | 演示文稿 | wpp | .pptx | PPT 文档专用 | `references/wpp.md` — 幻灯片主题字体和配色设置、下载和导出 | | 智能表格 | as | .ksheet | 结构化表格，支持多视图、字段管理 | `references/sheet.md` — 工作表管理、范围数据获取、批量更新 | | 多维表格 | db / dbsheet | .dbt | 多数据表、丰富字段类型与视图（表格/看板/甘特等） | `references/dbsheet.md` — 支持数据表/视图/字段/记录的完整增删改查，含表单视图、父子记录、分享协作、高级权限与 Webhook | ### 通用工具总览 #### 文档创建与上传 | 工具 | 用途 | |------|------| | `create_file` | 在云盘下新建文件或文件夹 | | `scrape_url` | 网页剪藏，抓取网页内容并自动保存为智能文档 | | `scrape_progress` | 查询网页剪藏任务进度 | | `upload_file` | 全量上传写入文件（更新已有 docx/pdf 或新建并上传本地文件） | #### 文档读取与下载 | 工具 | 用途 | |------|------| | `list_files` | 获取指定文件夹下的子文件列表 | | `download_file` | 获取文件下载信息 | | `read_file_content` | 文档内容抽取为 Markdown/纯文本 | #### 文件组织 | 工具 | 用途 | |------|------| | `move_file` | 批量移动文件(夹) | | `rename_file` | 重命名文件（夹） | #### 分享与访问 | 工具 | 用途 | |------|------| | `share_file` | 开启文件分享 | | `set_share_permission` | 修改分享链接属性 | | `cancel_share` | 取消文件分享 | | `get_share_info` | 获取分享链接信息 | | `get_file_link` | 获取文件的云文档在线访问链接 | #### 搜索 | 工具 | 用途 | |------|------| | `search_files` | 文件（夹）搜索 | 完整参数、示例与返回值见 `references/drive.md`。 ### 不支持的操作 - 无批量删除文件工具（仅支持移动） - 云盘 drive 侧暂无逐文件 ACL 成员矩阵（以分享链接为主）；多维表格（.dbt）见 dbsheet.permission_* 与 dbsheet.share_*（详阅 references/dbsheet.md） - 在线 Excel / 智能表格工作表区域保护见 sheet.*_protection_ranges 相关工具（详阅 references/sheet.md） - 无文件版本回滚 - 无实时协同编辑控制 --- ## 操作指南 ### 执行指南 > 执行以下操作前，**必须**先阅读对应指南文件： | 操作类型 | 指南文件 | 何时阅读 | |----------|----------|----------| | 获取文件标识指南 | `references/file-locating-guide.md` | 需要搜索或浏览文件时 | | 文件读取指南 | `references/file-reading-guide.md` | 需要获取文档内容时 | | 文件创建与写入指南 | `references/file-writing-guide.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`。 ### 更多操作流程 | 流程 | 说明 | 详细参考 | |------|------|---------| | AI 主题生成演示文稿 | 主题生成 PPT 标准链路：澄清需求、研究资料、大纲与生成上传 | `references/workflows/topic-ppt.md` | | AI 文档生成演示文稿 | 文档生成 PPT 标准链路：创建会话、解析文档、生成大纲、美化风格与生成上传 | `references/workflows/doc-ppt.md` | | 网页剪藏 | 抓取网页内容并自动保存为智能文档 | `references/workflows/web-scrape.md` | | 搜索-读取-汇报撰写 | 搜索多份文档、提取信息、汇总撰写新报告 | `references/workflows/search-read-report.md` | | 定期读取与播报 | 定期读取指定文档，提取关键信息生成摘要 | `references/workflows/periodic-read-summary.md` | | 智能分类整理 | 列出目录，按内容或指定维度分类创建文件夹并归档 | `references/workflows/smart-classify.md` | | 精准搜索与风险排查 | 在特定目录批量搜索文档，逐一读取分析，汇总到新文档 | `references/workflows/precise-search-analysis.md` | | 接龙转表格 | 识别接龙文本内容，自动提取并转为在线表格 | `references/workflows/jielong-to-table.md` | | 信息收集表单生成 | 根据用户需求自动设计并创建信息收集表格 | `references/workflows/form-generator.md` | | 知识智能整理 | 对知识库中的零散内容进行智能化整理和结构化重组 | `references/workflows/knowledge-format.md` | | 知识一键存入 | 将各类内容（网页、文件、文本）一键保存到知识库 | `references/workflows/knowledge-save.md` | | 表格美化与数据规范 | 读取表格数据，进行格式美化、数据规范化和样式调整，并通过条件格式、数据校验、区域权限固化规则 | `references/workflows/table-beautify.md` | --- ## 错误速查 | 错误特征 | 原因 | 处理方式 | |----------|------|----------| | `400006` / 鉴权失败 | Token 过期或未配置 | 先运行 get-token 脚本重新获取；脚本失败则引导用户手动获取（见「认证配置」章节） | | `429001` / 限频 | 请求过于频繁，响应含**限频恢复时间** | 立即停止命令调用，直到达到恢复时间；禁止立即重试、换参、换子命令连续请求 | | `429002` / 熔断 | 多因短时间内连续触发 `429001` ，响应含**熔断持续时间** | 熔断时长内零请求，期满再试；重新规划任务避免请求过频 | | 工具找不到 | 未注册 MCP 服务 | 运行 `bash scripts/setup.sh` 重新注册（mcporter 环境），或检查客户端 MCP 配置 | | `mcporter` 未找到 | 运行环境缺少 mcporter | 默认不会改动系统环境（不执行全局安装）；可先手动安装后重试，或显式使用 `bash scripts/setup.sh --auto-install-mcporter` / `bash scripts/get-token.sh --auto-install-mcporter`（PowerShell: `-AutoInstallMcporter`） | | `.env` 迁移后其他配置丢失 | 脚本会整文件删除 `.env` | 新流程仅移除 `KINGSOFT_DOCS_TOKEN` 键并保留其他键；若 `.env` 仅含该键会直接删除空 `.env` | | 搜索无结果 | 关键词过精确 / 索引延迟 | 缩短关键词 / 等待 3-5 秒重试 | | 读取内容为空 | 文件无内容或格式不支持 | 确认文件非空且后缀正确 | | `read_file_content` 对 .csv 长时间 `running` | CSV 格式不支持 | 勿对 .csv 调用 `read_file_content`，建议用户转为 .xlsx 后用 `sheet.*` 读取 | | 创建文件失败 | 文件名后缀不正确 | 检查后缀：`.otl` / `.docx` / `.xlsx` / `.ksheet` / `.dbt` / `.pdf` / `.pptx` | | 移动文件失败 | 目标文件夹不存在 | 先搜索确认或创建文件夹 | | HTTP 5xx / 超时 | 服务端故障 | 等 3 秒重试 1 次 | | 验证不通过（回读值与预期不符） | 写入未生效或延迟 | 等 2 秒重新验证，仍不通过则报告用户 | | `setup.sh` 执行失败 / 安装报错 | 当前版本可能已不兼容 | 执行上方「版本自检」流程 | | MCP 接口返回未知错误码（非 5xx、非 400006、非 429001/429002、非工具不存在） | Skill 版本过旧导致接口不兼容 | 执行上方「版本自检」流程 | | 错误信息含 `version`、`incompatible`、`not_supported`、`deprecated` 等版本关键词 | Skill 或 API 版本不兼容 | 执行上方「版本自检」流程 | | 工具调用失败且原因不明 | 可能是 Skill 版本过旧 | 执行上方「版本自检」流程 | | 工具调用失败需判断是否可重试 | 不同工具幂等性不同 | 查看该工具参考文档「操作约束」区的幂等性说明，幂等工具可安全重试，非幂等工具须先确认状态 | --- ## 安全约束 - 凭据由 MCP 运行时管理，Skill 自身不存储、不记录 - 无状态代理，不缓存任何文档内容或业务数据 - 仅在用户主动发起操作时调用对应 API

path: references/aippt/doc_ppt.md
content: # 文档生成 PPT

## 1. aippt.doc_create_session

#### 功能说明

为“文档生成 PPT”链路创建服务端 AI 会话，返回后续 `aippt.doc_outline_options` / `aippt.doc_outline` 需要使用的 `session_id`。

**适用于**：已经确定要基于某份文档生成 PPT，准备进入文档解析和大纲生成流程时。



**幂等性**：否 — 创建新会话无副作用，可安全重试

#### 调用示例

创建文档生成会话：

```json
{}
```


#### 参数说明


#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "session_id": "9dbea4d8-b9f7-419c-a4ad-208d4515b8d5"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | number | 0 表示成功 |
| `message` | string | 成功时通常为“成功” |
| `data.session_id` | string | 文档生成链路会话 ID |


---

## 2. aippt.doc_outline_options

#### 功能说明

基于文档引用和会话 ID 调用文档 Agent，对文档做初步解析，并返回一组需要与用户确认的意图问题（questions）。

**适用于**：用户已经给出文档，但还需要补充“制作目标 / 受众 / 重点”等选项时。



**幂等性**：否 — 可安全重试，返回当前会话可选项

> 拿到 `questions` 后，应先与用户交互收集选择，再整理成 `resume_info`

#### 调用示例

获取文档大纲选项：

```json
{
  "session_id": "9dbea4d8-b9f7-419c-a4ad-208d4515b8d5",
  "input": [
    {
      "type": "text",
      "content": "生成PPT"
    },
    {
      "type": "file_id",
      "content": "100239253236"
    }
  ]
}
```


#### 参数说明

- `session_id` (string, 必填): AI 会话 ID，来自 `aippt.doc_create_session`
- `input` (array[object], 必填): 输入内容数组。通常包含一条 `{type:"text", content:"生成PPT"}` 和一条文档引用（如 `{type:"file_id", content:"100239253236"}`）。


#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "session_id": "9dbea4d8-b9f7-419c-a4ad-208d4515b8d5",
    "checkpoint_id": "419e8c77-5442-459e-87eb-2637ba53e132",
    "interrupt_id": "45caf5dc-2dd4-48a7-9ba3-8ba2edc67cdd",
    "user_input": "生成PPT",
    "questions": [
      {
        "type": "choice",
        "field": "制作目标",
        "label": "制作目标",
        "options": ["内部技术培训宣讲", "新功能发布介绍"]
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.session_id` | string | 当前 AI 会话 ID |
| `data.checkpoint_id` | string | 继续生成完整大纲时需要的 checkpoint |
| `data.interrupt_id` | string | follow_up 中断 ID |
| `data.user_input` | string | 从 input 中提取的文本输入摘要 |
| `data.questions` | array | 需要向用户确认的问题列表 |
| `data.assistant_messages` | array[string] | 过程中的可见提示文案，可能为空 |


---

## 3. aippt.doc_outline

#### 功能说明

基于 `session_id`、`checkpoint_id`、原始文档输入和 `resume_info`，继续文档 Agent 流程，生成完整 Markdown 大纲。

**适用于**：用户已经完成大纲选项确认，需要拿到可继续做风格美化的正式大纲时。



**幂等性**：否 — 可安全重试，会基于相同输入重新生成大纲

#### 调用示例

生成文档完整大纲：

```json
{
  "session_id": "9dbea4d8-b9f7-419c-a4ad-208d4515b8d5",
  "checkpoint_id": "419e8c77-5442-459e-87eb-2637ba53e132",
  "input": [
    {
      "type": "text",
      "content": "生成PPT"
    },
    {
      "type": "file_id",
      "content": "100239253236"
    }
  ],
  "resume_info": [
    {
      "type": "follow_up",
      "id": "45caf5dc-2dd4-48a7-9ba3-8ba2edc67cdd",
      "data": {
        "items": [
          {
            "type": "choice",
            "field": "制作目标",
            "label": "制作目标",
            "options": [
              "内部技术培训宣讲"
            ]
          },
          {
            "type": "choice",
            "field": "目标受众",
            "label": "目标受众",
            "options": [
              "技术团队成员"
            ]
          },
          {
            "type": "text",
            "field": "补充说明",
            "label": "补充说明",
            "text_input": "重点突出架构设计和性能优化部分"
          }
        ]
      }
    }
  ]
}
```


#### 参数说明

- `session_id` (string, 必填): AI 会话 ID
- `checkpoint_id` (string, 必填): 检查点 ID，来自 `aippt.doc_outline_options`
- `input` (array[object], 必填): 与获取大纲选项时一致的输入内容数组
- `resume_info` (array[object], 必填): 恢复信息数组，固定包含一个 `follow_up` 对象。结构如下：
  - `type` (string): 固定为 `"follow_up"`
  - `id` (string): 来自 `aippt.doc_outline_options` 返回的 `interrupt_id`
  - `data.items` (array[object]): 与 `doc_outline_options` 返回的 `questions` 保持相同结构，每项包含：
    - `type` (string): 题型，与 questions 中一致（`"choice"` 或 `"text"`）
    - `field` (string): 字段标识，与 questions 中一致
    - `label` (string): 字段名称，与 questions 中一致
    - `options` (array[string]): 选择题时填入用户选中的选项（可多选）
    - `text_input` (string): 文本题时填入用户输入的文本


#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "session_id": "9dbea4d8-b9f7-419c-a4ad-208d4515b8d5",
    "checkpoint_id": "419e8c77-5442-459e-87eb-2637ba53e132",
    "user_input": "生成PPT",
    "user_intention": {
      "items": [
        {
          "field": "制作目标",
          "options": ["内部技术培训宣讲"]
        }
      ]
    },
    "markdown_outline": "# 示例主题 {.topic}\n\n## 封面 {.title}\n- 副标题"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.session_id` | string | 当前 AI 会话 ID |
| `data.checkpoint_id` | string | 本次流程对应 checkpoint |
| `data.user_input` | string | 从 input 中提取的文本输入摘要 |
| `data.user_intention` | object | 规范化后的用户意图对象，可直接传给 `aippt.doc_beautify` |
| `data.markdown_outline` | string | 完整 Markdown 大纲 |
| `data.assistant_messages` | array[string] | 过程中的可见提示文案，可能为空 |


---

## 4. aippt.doc_beautify

#### 功能说明

根据完整 Markdown 大纲和用户意图，生成全局风格和逐页排版设计描述。

**适用于**：已经拿到正式大纲，准备进入最终 PPT 渲染前的风格美化阶段。



**幂等性**：否 — 可安全重试，会基于相同输入重新生成美化方案

#### 调用示例

生成文档大纲风格：

```json
{
  "topic": "航空业碳中和监管与合规应对",
  "outline": "# 航空业碳中和监管与合规应对 {.topic}\n\n## 封面 {.title}\n- 汇报主题",
  "user_intention": "{items:[...]}"
}
```


#### 参数说明

- `topic` (string, 必填): 演示文稿主题
- `outline` (string, 必填): 完整 Markdown 大纲
- `user_intention` (object, 必填): 用户意图对象，建议直接传入 `aippt.doc_outline` 返回的 `user_intention`
- `user_input` (string, 可选): 用户原始输入文本；已知时建议传入
- `model` (string, 可选): 风格模型，默认 `IMAGE_V2`

#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "topic": "航空业碳中和监管与合规应对",
    "theme": "航空业碳中和监管与合规应对",
    "global_style": "全局风格描述",
    "slides": [
      {
        "index": 0,
        "page_type": "title",
        "design_style": "封面页风格描述"
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.topic` | string | 演示主题 |
| `data.theme` | string | 上游生成的主题名 |
| `data.global_style` | string | 全局设计风格说明 |
| `data.slides` | array | 逐页风格数组 |
| `data.slides[].index` | integer | 页序号（从 0 开始） |
| `data.slides[].design_style` | string | 对应页面的风格描述 |


---

## 5. aippt.doc_generate_ppt

#### 功能说明

根据主题与 `outlines` 调用 structppt 接口，生成逐页 HTML PPTX，并返回合并后的演示文件地址。

**适用于**：已经拿到稳定的大纲结构，希望进一步生成可下载的演示文稿结果。



**幂等性**：否 — 可安全重试，会基于相同大纲重新生成 PPT

#### 调用示例

生成文档 PPT：

```json
{
  "topic": "航空业碳中和监管与合规应对",
  "outlines": [
    {
      "type": "title",
      "title": "封面",
      "page_type": "pt_title",
      "contents": "",
      "design_style": "封面页风格描述"
    }
  ]
}
```


#### 参数说明

- `topic` (string, 必填): 演示文稿主题
- `outlines` (array[object], 必填): PPT 大纲数组，建议直接传入标准 outlines 结果。每项为 object，至少需为非空对象。


#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "topic": "航空业碳中和监管与合规应对",
    "config": {
      "topic": "航空业碳中和监管与合规应对",
      "outlines": [
        {
          "type": "title",
          "title": "封面",
          "page_type": "pt_title",
          "contents": "",
          "design_style": "封面页风格描述"
        }
      ]
    },
    "merged_url": "https://example.com/final.pptx",
    "total_pages": 12,
    "pages": [
      {
        "slide_index": 0,
        "file_url": "https://example.com/0.pptx",
        "title": "封面",
        "type": "title"
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.config` | object | 透传的标准配置对象（topic + outlines） |
| `data.config.outlines[]` | array | 传给 structppt 的标准页面数组 |
| `data.merged_url` | string | 合并后的完整 PPT 地址 |
| `data.total_pages` | integer | 总页数 |
| `data.pages` | array | 逐页生成结果 |


---



path: references/aippt/theme_ppt.md
content: # 主题生成 PPT

## 1. aippt.theme_questions

#### 功能说明

根据用户输入的 PPT 主题或需求描述，生成一组可继续追问用户偏好的问卷题目。

**适用于**：用户只给了一个较宽泛的主题，还需要澄清受众、场景、风格、内容重点等信息时。

- 服务端会固定以 `stream=true` 调用上游接口，但最终工具返回为一次性 JSON 结果
- 建议将返回的问卷继续转成 `question_and_answers`，供 `aippt.theme_deep_research` 与 `aippt.theme_outline` 使用



**幂等性**：否 — 可安全重试，返回当前输入对应的问题列表

> 如果主题已经足够明确、无需继续澄清，可跳过本工具，直接组织 `question_and_answers`

#### 调用示例

生成儿童科普主题问卷：

```json
{
  "input": "帮我做一份长颈鹿主题的儿童科普 PPT，用于小学课堂讲解"
}
```


#### 参数说明

- `input` (string, 必填): 用户输入的 PPT 主题、目标或需求描述

#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "input": "帮我做一份长颈鹿主题的儿童科普 PPT",
    "questionnaire": [
      {
        "key": "properties1",
        "title": "这份长颈鹿主题的PPT主要用于什么场景？",
        "type": "radio",
        "enum": ["A", "B", "C", "D"],
        "enumNames": ["儿童科普教学", "幼儿园活动展示", "生日派对主题分享", "文创产品提案"],
        "required": false,
        "default_answer": ["儿童科普教学"]
      },
      {
        "key": "properties4",
        "title": "如果目标受众是低龄儿童，您是否希望在PPT大纲中规划互动环节模块？",
        "type": "input",
        "required": false,
        "default_answer": "是"
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | number | 0 表示成功 |
| `message` | string | 成功时通常为“成功” |
| `data.input` | string | 原始主题描述 |
| `data.questionnaire` | array | 生成的问卷列表 |
| `data.questionnaire[].key` | string | 问题唯一键 |
| `data.questionnaire[].title` | string | 问题标题 |
| `data.questionnaire[].type` | string | 题型，如 `radio` / `checkbox` / `input` |
| `data.questionnaire[].enum` | array[string] | 选项编码列表，题型为选择题时可能返回 |
| `data.questionnaire[].enumNames` | array[string] | 选项文案列表，顺序与 `enum` 对齐 |
| `data.questionnaire[].required` | boolean | 是否必答 |
| `data.questionnaire[].default_answer` | any | 默认答案，可能为字符串或字符串数组 |


---

## 2. aippt.theme_deep_research

#### 功能说明

根据用户主题和补充问答执行 AI PPT 联网研究，提炼研究目标完成情况与研究资料。

**适用于**：需要先补充事实资料、案例、背景知识，再继续生成 PPT 大纲时。

- 服务端固定以 `stream=true` 调用上游接口
- 最终工具结果只返回完成摘要，不直接返回完整研究资料文本
- 若调用端传入 MCP `_meta.progressToken`，服务会通过 `notifications/progress` 回传进度
- 若同时传入 `_meta.partialResults=true`，`notifications/progress` 中会追加逐段 partial result chunk
- 服务端还会兼容透传 `notifications/aippt/deep_research` 结构化事件



**幂等性**：否 — 可安全重试，会基于相同主题重新进行深度研究

> 若后续要调用 `aippt.theme_outline`，应从流式通知中消费研究资料文本，并将其作为 `references` 传入
> 最终 tool result 不包含完整 `references`，不要仅依赖最终返回体获取研究内容

#### 调用示例

对儿童科普主题做研究：

```json
{
  "input": "帮我做一份长颈鹿主题的儿童科普 PPT",
  "question_and_answers": [
    {
      "question": "这份 PPT 主要用于什么场景？",
      "answer": "小学科学课课堂讲解"
    },
    {
      "question": "希望突出哪些内容模块？",
      "answer": "外形特征、生活习性、趣味冷知识"
    }
  ]
}
```


#### 参数说明

- `input` (string, 必填): 用户输入的 PPT 主题或需求描述
- `question_and_answers` (array[object], 必填): 问答列表，不能为空。每项含 `question`（string，必填）与 `answer`（string，必填）。


#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "streamed": true,
    "done": true,
    "goal_count": 3,
    "goals_done": 3,
    "learning_count": 6
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | number | 0 表示成功 |
| `message` | string | 成功时通常为“成功” |
| `data.streamed` | boolean | 固定为 true，表示研究过程通过流式事件执行 |
| `data.done` | boolean | 是否已完成 |
| `data.goal_count` | integer | 研究目标总数 |
| `data.goals_done` | integer | 已完成的研究目标数 |
| `data.learning_count` | integer | 已提取的研究资料条数 |


---

## 3. aippt.theme_outline

#### 功能说明

根据主题描述、补充问答以及研究资料，生成用于 AI PPT 的结构化大纲结果。

**适用于**：已经明确主题方向，并且希望先拿到可审阅的大纲，再决定是否继续生成 HTML PPTX。

- 服务端会固定以 `stream=true` 调用上游 `image_to_slide/outline` 接口
- `references` 建议直接传入 `aippt.theme_deep_research` 流式阶段产出的研究资料文本
- `question_and_answers` 不能为空，否则服务端会直接报参数错误



**幂等性**：否 — 可安全重试，会基于相同输入重新生成大纲

> outline 的具体内部结构由上游模型决定，后续若要生成 HTML PPTX，建议优先从其中提取正式的 outlines 数组再传给 aippt.theme_generate_html_pptx

#### 调用示例

生成儿童科普主题大纲：

```json
{
  "input": "帮我做一份长颈鹿主题的儿童科普 PPT",
  "question_and_answers": [
    {
      "question": "这份 PPT 主要用于什么场景？",
      "answer": "小学科学课课堂讲解"
    },
    {
      "question": "希望整体风格更偏向哪种？",
      "answer": "插画风、适合儿童"
    }
  ],
  "references": "长颈鹿是现存最高的陆生动物，舌头很长，常以树叶为食。"
}
```


#### 参数说明

- `input` (string, 必填): 用户输入的 PPT 主题或需求描述
- `question_and_answers` (array[object], 必填): 问答列表，不能为空。每项含 `question`（string，必填）与 `answer`（string，必填）。

- `references` (string, 可选): 研究资料文本，建议直接传入 `aippt.theme_deep_research` 产出的研究内容

#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "input": "帮我做一份长颈鹿主题的儿童科普 PPT",
    "question_and_answers": [
      {
        "question": "这份 PPT 主要用于什么场景？",
        "answer": "小学科学课课堂讲解"
      }
    ],
    "references": "长颈鹿是现存最高的陆生动物，主要生活在非洲稀树草原。",
    "outline": {
      "type": "outline",
      "title": "长颈鹿主题演示",
      "slides": [
        { "title": "封面" },
        { "title": "习性介绍" }
      ]
    }
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | number | 0 表示成功 |
| `message` | string | 成功时通常为“成功” |
| `data.input` | string | 原始主题描述 |
| `data.question_and_answers` | array | 原样回传的问答列表 |
| `data.references` | string | 原样回传的研究资料文本 |
| `data.outline` | object | 上游返回的结构化大纲对象；字段会随模板与场景变化 |


---

## 4. aippt.theme_generate_html_pptx

#### 功能说明

根据主题与 `outlines` 调用 structppt 接口，生成逐页 HTML PPTX，并返回合并后的演示文件地址。

**适用于**：已经拿到稳定的大纲结构，希望进一步生成可下载的演示文稿结果。

- 服务端固定使用 `json2ppt-banana` 场景
- `outlines` 每项须包含 `title`、`content_description`、`design_style`、`page_type` 四个必填字段；推荐传入本地格式转换后的标准 outlines
- 返回值同时包含逐页结果和合并后的完整 PPTX 链接



**幂等性**：否 — 可安全重试，会基于相同 outlines 重新生成

> 返回的 `merged_url` 和 `pages[].file_url` 一般为临时链接，调用后应尽快消费
> `outlines` 各字段值不得为空字符串，否则服务端返回 badRequest
> `page_type` 只接受上述 5 个枚举值，其他值会导致 badRequest

#### 调用示例

生成儿童科普主题 HTML PPTX：

```json
{
  "topic": "长颈鹿：自然奇迹与文化象征",
  "outlines": [
    {
      "title": "长颈鹿：自然奇迹与文化象征",
      "content_description": "封面页展示主题标题，副标题说明这是一份探索长颈鹿生物学特征、进化奥秘与文化内涵的科普报告。",
      "design_style": "--- 本页版式 ---\n画面铺满全屏，标题居中偏上布局，副标题紧随其下，整体呈现简洁大气的博物馆档案风格",
      "page_type": "pt_title"
    },
    {
      "title": "目录",
      "content_description": "展示本次报告的递进式认知结构：从生物构造基础到进化理论，再到文化历史关联。",
      "design_style": "--- 本页版式 ---\n画面铺满全屏，标题位于上方居中，内容以纵向分布的四级目录列表呈现",
      "page_type": "pt_contents"
    },
    {
      "title": "探索永无止境",
      "content_description": "结束页总结长颈鹿从生物进化奇迹到文化符号的多重价值。",
      "design_style": "--- 本页版式 ---\n画面铺满全屏，居中布局，主标题位于视觉中心",
      "page_type": "pt_end"
    }
  ]
}
```


#### 参数说明

- `topic` (string, 必填): 演示文稿标题
- `outlines` (array[object], 必填): PPT 大纲数组，每项须同时包含以下四个必填字段（缺少任何一个都会返回 badRequest）。数组至少 1 项，首项 `page_type` 建议为 `pt_title`，末项建议为 `pt_end`
  - `title` (string, 必填): 该页标题，不得为空
  - `content_description` (string, 必填): 该页正文与内容要点描述，不得为空
  - `design_style` (string, 必填): 该页版式与视觉风格描述，不得为空
  - `page_type` (string, 必填): 页面类型，仅支持：`pt_title` / `pt_contents` / `pt_section_title` / `pt_text` / `pt_end`

#### 返回值说明

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "topic": "长颈鹿主题演示",
    "merged_url": "https://meihua-service.ks3-cn-beijing.ksyuncs.com/file/20260401/pptx/b74af503-ef35-445f-8106-2c1deac0dcb3.pptx?Expires=1775027041&AWSAccessKeyId=xxx&Signature=xxx",
    "total_pages": 4,
    "pages": [
      {
        "slide_index": 3,
        "file_url": "https://meihua-service.ks3-cn-beijing.ksyuncs.com/temp/20260401/pptx/3097fecf-bf39-454a-92eb-700b49e0e773.pptx?Expires=1775199540&AWSAccessKeyId=xxx&Signature=xxx",
        "title": "探索永无止境",
        "type": "ending"
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | number | 0 表示成功 |
| `message` | string | 成功时通常为“成功” |
| `data.topic` | string | 演示文稿标题 |
| `data.merged_url` | string | 合并后的完整 PPTX 下载地址 |
| `data.total_pages` | integer | 总页数 |
| `data.pages` | array | 逐页生成结果 |
| `data.pages[].slide_index` | integer | 幻灯片序号 |
| `data.pages[].file_url` | string | 单页 PPTX 文件地址 |
| `data.pages[].title` | string | 对应大纲标题 |
| `data.pages[].type` | string | 对应大纲类型，如 `cover` / `content` / `ending` |


---



path: references/aippt.md
content: # AI PPT（aippt）工具完整参考文档

本文件包含金山文档 Skill 中 **AI PPT** 相关工具的 MCP API 调用方法、脚本模板和中间文件约定。

**适用范围**：`aippt.theme_*`（主题生成 PPT）与 `aippt.doc_*`（文档生成 PPT）两类场景。

---

## 推荐调用链路

### 主题生成 PPT

```
aippt.theme_questions → aippt.theme_deep_research → aippt.theme_outline → 本地格式转换 → aippt.theme_generate_html_pptx → upload_file
```

详细工作流见 `references/workflows/topic-ppt.md`

### 文档生成 PPT

```
aippt.doc_create_session → aippt.doc_outline_options → aippt.doc_outline → aippt.doc_beautify → 本地格式转换 → aippt.doc_generate_ppt → upload_file
```

详细工作流见 `references/workflows/doc-ppt.md`

### 使用建议

| 场景 | 建议 |
|------|------|
| 用户只给一句主题 | 先 `aippt.theme_questions`，补齐受众、场景、风格、重点 |
| 用户已经给出文档 | 使用 `aippt.doc_create_session` → `aippt.doc_outline_options` → `aippt.doc_outline` |
| 需要更可靠的事实资料 | 衔接 `aippt.theme_deep_research` |
| 先看结构再决定生成 | 先停在 `aippt.theme_outline` 或 `aippt.doc_outline` |
| 需要文档直出最终演示文件 | `aippt.doc_beautify` → 本地格式转换 → `aippt.doc_generate_ppt` |
| 需要最终演示文件 | 两条链路最终都需要 `{topic, outlines[]}`，主题链路用 `aippt.theme_generate_html_pptx`，文档链路用 `aippt.doc_generate_ppt` |

---

## MCP 调用规则

### 注意事项

- 通过 `mcporter` 或 `kdocs-cli` 调用本流程中的步骤时，请为每一步单独设置超时时间为 **1800000 毫秒**
- `aippt.theme_deep_research` 的完整研究内容主要通过流式通知产生，最终 tool result 只保留摘要
- `aippt.theme_outline` 返回的 `outline` 结构可能因上游模板而变化，传给 `aippt.theme_generate_html_pptx` 时应优先使用其中正式的 `outlines` 数组
- `aippt.doc_outline` 返回的 `markdown_outline` 可能包含重复内容（大纲出现两次），建议从 `assistant_messages` 中提取最长的含 `{.topic}` 和 `{.end}` 的消息作为清洁版大纲
- `aippt.doc_outline` 的 `resume_info` 必须是**数组**，格式为 `[{type:"follow_up", id:<interrupt_id>, data:{items:[...]}}]`
- **文档链路同样需要本地格式转换**：将 `03_outline.md` + `04_beautify.json` 合并为 `{topic, outlines[]}` 后再传入 `aippt.doc_generate_ppt`
- `aippt.doc_generate_ppt` 接收 `{topic, outlines[]}` 格式，与 `aippt.theme_generate_html_pptx` 底层接口一致
- 生成速度约每页 60 秒，20 页以上的 PPT 生成可能耗时 20-30 分钟
- `aippt.theme_generate_html_pptx` 返回的下载链接通常带时效性，建议尽快消费
- `deep_research` 的 `references`、`outline` 结果、Markdown 大纲、格式转换后的 `outlines` 等内容可能很长，**必须先写入本地文件**，后续步骤再读取文件内容，避免命令行参数超过长度限制

### mcporter短参数直接调用

当参数 JSON 较短（< 2000 字符）时可直接命令行调用：

```bash
mcporter call kdocs-qclaw aippt.theme_questions --args '{"input":"长颈鹿科普PPT"}' --output json --timeout 1800000
```

### mcporter长参数脚本调用

当参数 JSON 超过 2000 字符，或包含 `references`、`outlines`、`content_base64` 等长字段时，**必须使用脚本方式调用**。

#### 脚本生成与调用流程

1. 将工具参数写入 JSON 文件（UTF-8），如 `$AIPPT_WORK_DIR/03_outline_args.json`
2. 在会话临时目录生成调用脚本 `$AIPPT_WORK_DIR/_call_mcp.js`（首次生成后复用）
3. 执行：`node $AIPPT_WORK_DIR/_call_mcp.js <toolName> <argsFile> [outputFile] [timeoutMs] [serverName]`

#### 脚本模板 `_call_mcp.js`

```javascript
const { spawnSync, execSync } = require('child_process');
const fs = require('fs');
const path = require('path');
const os = require('os');

const toolName = process.argv[2];
const argsFile = process.argv[3];
const outputFile = process.argv[4] || '';
const timeoutMs = parseInt(process.argv[5] || '1800000', 10);
const serverName = process.argv[6] || 'kdocs';
const STDOUT_LIMIT = 8000;
const TIMEOUT_BUFFER = 1800000;

if (!toolName || !argsFile) {
  console.error('用法: node _call_mcp.js <toolName> <argsFile> [outputFile] [timeoutMs] [serverName]');
  process.exit(1);
}

function findMcporterCli() {
  const candidates = [];
  if (process.env.MCPORTER_CLI) candidates.push(process.env.MCPORTER_CLI);
  const nodeDir = path.dirname(process.execPath);
  candidates.push(path.join(nodeDir, 'node_modules', 'mcporter', 'dist', 'cli.js'));
  const nvmDir = process.env.NVM_SYMLINK || path.join(os.homedir(), 'AppData', 'Roaming', 'nvm');
  if (process.platform === 'win32' && fs.existsSync(nvmDir)) {
    try {
      fs.readdirSync(nvmDir).filter(d => d.startsWith('v')).forEach(d => {
        candidates.push(path.join(nvmDir, d, 'node_modules', 'mcporter', 'dist', 'cli.js'));
      });
    } catch (_) {}
  }
  try {
    const g = execSync('npm root -g', { encoding: 'utf-8', timeout: 5000 }).trim();
    candidates.push(path.join(g, 'mcporter', 'dist', 'cli.js'));
  } catch (_) {}
  if (process.platform === 'win32') {
    candidates.push('C:\\Program Files\\nodejs\\node_modules\\mcporter\\dist\\cli.js');
  } else {
    candidates.push('/usr/local/lib/node_modules/mcporter/dist/cli.js');
    candidates.push('/usr/lib/node_modules/mcporter/dist/cli.js');
  }
  for (const p of candidates) { if (p && fs.existsSync(p)) return p; }
  return null;
}

const argsPath = path.resolve(argsFile);
if (!fs.existsSync(argsPath)) { console.error('[ERROR] 参数文件不存在:', argsPath); process.exit(1); }
const argsContent = fs.readFileSync(argsPath, 'utf-8').trim();
try { JSON.parse(argsContent); } catch (e) { console.error('[ERROR] JSON 不合法:', e.message); process.exit(1); }

const mcporterCli = findMcporterCli();
let result;
if (mcporterCli) {
  console.error('[INFO] mcporter cli:', mcporterCli);
  result = spawnSync(process.execPath, [
    mcporterCli, 'call', serverName, toolName,
    '--args', argsContent, '--output', 'json', '--timeout', String(timeoutMs)
  ], { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024, timeout: timeoutMs + TIMEOUT_BUFFER });
} else {
  console.error('[INFO] 尝试通过 PATH 调用 mcporter');
  result = spawnSync('mcporter', [
    'call', serverName, toolName,
    '--args', argsContent, '--output', 'json', '--timeout', String(timeoutMs)
  ], { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024, timeout: timeoutMs + TIMEOUT_BUFFER, shell: process.platform === 'win32' });
}

console.error('[INFO] Exit code:', result.status);
if (result.error) { console.error('[ERROR]', result.error.message); process.exit(1); }
const output = result.stdout || '';
if (outputFile && output.length > 0) {
  const outPath = path.resolve(outputFile);
  fs.mkdirSync(path.dirname(outPath), { recursive: true });
  fs.writeFileSync(outPath, output, 'utf-8');
  console.error('[INFO] 结果已写入:', outPath, '(' + output.length + ' bytes)');
}
if (output) {
  if (output.length > STDOUT_LIMIT) {
    process.stdout.write(output.substring(0, STDOUT_LIMIT));
    console.error('[INFO] stdout 已截断 (' + output.length + ' -> ' + STDOUT_LIMIT + ')');
  } else { process.stdout.write(output); }
}
if (result.stderr) {
  const cleaned = result.stderr.split('\n')
    .filter(l => !l.includes('ExperimentalWarning') && !l.includes('--experimental'))
    .join('\n').trim();
  if (cleaned) console.error(cleaned);
}
process.exit(result.status || 0);
```

#### 调用示例

```bash
# 调用 aippt.theme_outline（参数含长 references）
node $AIPPT_WORK_DIR/_call_mcp.js aippt.theme_outline $AIPPT_WORK_DIR/03_outline_args.json $AIPPT_WORK_DIR/03_outline.json 1800000

# 调用 aippt.theme_generate_html_pptx（参数含长 outlines）
node $AIPPT_WORK_DIR/_call_mcp.js aippt.theme_generate_html_pptx $AIPPT_WORK_DIR/04_config.json $AIPPT_WORK_DIR/05_ppt_result.json 1800000

# 调用 aippt.doc_outline（参数含长 resume_info）
node $AIPPT_WORK_DIR/_call_mcp.js aippt.doc_outline $AIPPT_WORK_DIR/03_doc_outline_args.json $AIPPT_WORK_DIR/03_outline.md 1800000
```

#### 关键设计要点

| 要点 | 说明 |
| --- | --- |
| 参数从文件读取 | 绕过 OS 命令行长度限制（Windows ~8191 字符） |
| `spawnSync` + `process.execPath` | 直接运行 `cli.js`，避免 PATH 查找失败 |
| 自动探测 mcporter 路径 | 按优先级搜索：环境变量 → Node 同级 → nvm → npm root -g → 默认路径 |
| `maxBuffer: 50MB` | 防止大输出被截断 |
| 超时缓冲 +30 分钟 | mcporter 内部超时与外层进程超时之间留有余量 |
| stdout 截断 8000 字符 | 避免终端刷屏，完整内容写入输出文件 |
| 过滤 ExperimentalWarning | 清除 Node.js 实验性功能噪声日志 |
| 兜底 PATH 调用 | cli.js 未找到时，退化为通过 `mcporter` 命令名调用 |

### upload_file 编程 API 调用

> **`upload_file` 无法通过 `mcporter call` 命令行调用。**
> PPTX 文件转 Base64 后 `content_base64` 字段通常有几十万字符，超出 OS 命令行长度限制。
> **唯一可行方式**：在 Node.js 脚本中直接调用 mcporter 的编程 API `callOnce()`。

#### 下载脚本 `_download_pptx.js`

```javascript
const https = require('https');
const http = require('http');
const fs = require('fs');
const path = require('path');

const workDir = process.argv[2];
const resultFile = path.join(workDir, '05_ppt_result.json');
const result = JSON.parse(fs.readFileSync(resultFile, 'utf-8'));
const mergedUrl = result.data
  ? result.data.merged_url
  : JSON.parse(result.content[0].text).data.merged_url;

const pptxFile = path.join(workDir, 'downloaded.pptx');
const driveId = process.argv[3];
const pptName = process.argv[4] || '演示文稿.pptx';

function download(url, dest) {
  return new Promise((resolve, reject) => {
    const mod = url.startsWith('https') ? https : http;
    const file = fs.createWriteStream(dest);
    mod.get(url, { timeout: 60000 }, (res) => {
      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
        file.close();
        fs.unlinkSync(dest);
        return download(res.headers.location, dest).then(resolve).catch(reject);
      }
      if (res.statusCode !== 200) { file.close(); return reject(new Error('HTTP ' + res.statusCode)); }
      res.pipe(file);
      file.on('finish', () => { file.close(); resolve(); });
    }).on('error', reject);
  });
}

async function main() {
  await download(mergedUrl, pptxFile);
  const base64 = fs.readFileSync(pptxFile).toString('base64');
  const uploadArgs = {
    drive_id: driveId,
    parent_id: '0',
    name: pptName,
    content_base64: base64
  };
  fs.writeFileSync(path.join(workDir, '06_upload_args.json'), JSON.stringify(uploadArgs), 'utf-8');
  console.log('OK');
}
main().catch(e => { console.error(e); process.exit(1); });
```

调用：`node $AIPPT_WORK_DIR/_download_pptx.js $AIPPT_WORK_DIR <drive_id> "<主题>.pptx"`

#### 上传脚本 `_upload_cloud.js`

```javascript
const fs = require('fs');
const path = require('path');
const os = require('os');

const argsFile = process.argv[2];
const outputFile = process.argv[3] || '';

async function findMcporterModule() {
  const candidates = [];
  const nodeDir = path.dirname(process.execPath);
  candidates.push(path.join(nodeDir, 'node_modules', 'mcporter', 'dist', 'index.js'));
  const nvmDir = process.env.NVM_SYMLINK || path.join(os.homedir(), 'AppData', 'Roaming', 'nvm');
  if (process.platform === 'win32' && fs.existsSync(nvmDir)) {
    try {
      fs.readdirSync(nvmDir).filter(d => d.startsWith('v')).forEach(d => {
        candidates.push(path.join(nvmDir, d, 'node_modules', 'mcporter', 'dist', 'index.js'));
      });
    } catch (_) {}
  }
  if (process.platform === 'win32') {
    candidates.push('C:\\Program Files\\nodejs\\node_modules\\mcporter\\dist\\index.js');
  } else {
    candidates.push('/usr/local/lib/node_modules/mcporter/dist/index.js');
    candidates.push('/usr/lib/node_modules/mcporter/dist/index.js');
  }
  for (const p of candidates) {
    if (fs.existsSync(p)) {
      return await import('file:///' + p.replace(/\\/g, '/'));
    }
  }
  throw new Error('mcporter module not found');
}

async function main() {
  const args = JSON.parse(fs.readFileSync(path.resolve(argsFile), 'utf-8'));
  const mcporter = await findMcporterModule();

  const result = await mcporter.callOnce({
    server: 'kdocs',
    toolName: 'upload_file',
    args: args
  });

  const output = JSON.stringify(result, null, 2);
  if (outputFile) {
    fs.writeFileSync(path.resolve(outputFile), output, 'utf-8');
  }
  const limit = 8000;
  process.stdout.write(output.length > limit ? output.substring(0, limit) : output);
}

main().catch(e => { console.error('[ERROR]', e.message); process.exit(1); });
```

调用：`node $AIPPT_WORK_DIR/_upload_cloud.js $AIPPT_WORK_DIR/06_upload_args.json $AIPPT_WORK_DIR/06_upload_result.json`

### 各调用方式适用范围

| 工具 / 步骤 | `kdocs-cli … @file` | `mcporter call` 命令行 | `_call_mcp.js` 脚本 | `callOnce()` 编程 API |
| --- | --- | --- | --- | --- |
| `aippt.theme_questions` | 可以（参数短，也可不用 `@file`） | 可以（参数短） | 可以 | 可以 |
| `aippt.theme_deep_research` | 可以（参数短，也可不用 `@file`） | 可以（参数短） | 可以 | 可以 |
| `aippt.theme_outline` | **推荐**（`@file` 绕过长度限制） | **不推荐**（`references` 可能很长） | **推荐** | 可以 |
| `aippt.theme_generate_html_pptx` | **推荐**（`@file` 绕过长度限制） | **不推荐**（`outlines` 可能很长） | **推荐** | 可以 |
| `aippt.doc_create_session` | 可以（参数短，也可不用 `@file`） | 可以（参数短） | 可以 | 可以 |
| `aippt.doc_outline_options` | 可以（参数短，也可不用 `@file`） | 可以（参数短） | 可以 | 可以 |
| `aippt.doc_outline` | **推荐**（`@file` 绕过长度限制） | **不推荐**（`resume_info` 可能较长） | **推荐** | 可以 |
| `aippt.doc_beautify` | **推荐**（`@file` 绕过长度限制） | **不推荐**（`outline` 可能很长） | **推荐** | 可以 |
| `aippt.doc_generate_ppt` | **推荐**（`@file` 绕过长度限制） | **不推荐**（`outline`+`beautify` 很长） | **推荐** | 可以 |
| `upload_file`（含 `content_base64`） | **推荐**（`@file` 从磁盘读取，绕过 OS 限制） | **不可用**（超出 OS 命令行限制） | **不可用**（`spawnSync` 同样超限） | **mcporter必须使用** |
| `get_file_link` / `search_files` 等 | 可以（参数短，也可不用 `@file`） | 可以（参数短） | 可以 | 可以 |

---

## 临时文件管理

所有中间产物必须格式规范，使用 UTF-8 格式，写入基于当前 Agent **conversation ID**（对话标识）的独立临时目录，避免污染工作区或多会话并行干扰。

> ⚠️ 此处 conversation ID 是指 Agent 当前对话的唯一标识，**不是** `aippt.doc_create_session` 返回的 API `session_id`。获取方式见工作流文档步骤 0。**禁止**使用自定义名称、缩写或硬编码字符串。

### 目录规则

| 项目 | 说明 |
|------|------|
| 根目录 | 系统临时目录，即 `os.tmpdir()`（Windows: `%TEMP%`，macOS/Linux: `/tmp`） |
| 会话子目录 | `<系统临时目录>/kdocs_aippt_<conversation_id>/` |
| 命名示例 | `/tmp/kdocs_aippt_a1b2c3d4-e5f6-7890-abcd-ef1234567890/` |

### 中间文件约定

#### 主题生成 PPT

| 步骤 | 推荐文件路径 |
|------|-------------|
| Step 01 用户选择 | `$AIPPT_WORK_DIR/01_selections.json` |
| Step 02 研究结果 | `$AIPPT_WORK_DIR/02_research.json` |
| Step 03 大纲结果 | `$AIPPT_WORK_DIR/03_outline.json` |
| Step 04 转换结果 | `$AIPPT_WORK_DIR/04_config.json` |
| Step 05 PPT 结果 | `$AIPPT_WORK_DIR/05_ppt_result.json` |
| Step 06 云文档结果 | `$AIPPT_WORK_DIR/06_cloud_result.json` |

#### 文档生成 PPT

| 步骤 | 推荐文件路径 |
|------|-------------|
| Step 01 会话信息 | `$AIPPT_WORK_DIR/01_session.json` |
| Step 02 选项确认（含 checkpoint_id, interrupt_id） | `$AIPPT_WORK_DIR/02_options.json` |
| Step 03 大纲结果 | `$AIPPT_WORK_DIR/03_outline.md` + `$AIPPT_WORK_DIR/03_extra.json` |
| Step 04 美化结果 | `$AIPPT_WORK_DIR/04_beautify.json` |
| Step 05 本地格式转换结果 | `$AIPPT_WORK_DIR/05_config.json`（`{topic, outlines[]}` 结构） |
| Step 06 PPT 结果 | `$AIPPT_WORK_DIR/06_ppt_result.json` |
| Step 07 云文档结果 | `$AIPPT_WORK_DIR/07_cloud_result.json` |

### 清理方式

流程结束时递归删除整个会话目录：

```javascript
const fs = require('fs');
fs.rmSync(sessionDir, { recursive: true, force: true });
```

```python
import shutil
shutil.rmtree(session_dir, ignore_errors=True)
```

```bash
# Linux / macOS
rm -rf "${TMPDIR}/aippt_${SESSION_ID}"

# Windows PowerShell
Remove-Item -Recurse -Force "$env:TEMP\aippt_${SESSION_ID}"
```

> 清理操作应放在 `try...finally` 中执行，无论流程成功或失败都必须尝试清理。

### JSON 格式约束

中间 JSON 文件必须通过编程语言的标准 JSON 序列化函数生成（**禁止手动拼接**）：

```javascript
// ✅ 正确
fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
// 写入后验证
JSON.parse(fs.readFileSync(filePath, 'utf-8'));
```

```python
# ✅ 正确
import json
with open(file_path, 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
```

编码要求：UTF-8 无 BOM，不要在 JSON 前后添加非 JSON 内容。

---

---

## 一、主题生成 PPT

> 从一句话主题到最终 PPT 的链路（问卷 → 深度研究 → 大纲 → 生成）

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`aippt.theme_questions`](aippt/theme_ppt.md) | 根据主题描述生成补充问卷 | `input` |
| [`aippt.theme_deep_research`](aippt/theme_ppt.md) | 围绕主题与问答执行联网深度研究 | `input`, `question_and_answers` |
| [`aippt.theme_outline`](aippt/theme_ppt.md) | 根据主题、问答和资料生成 PPT 大纲 | `input`, `question_and_answers` |
| [`aippt.theme_generate_html_pptx`](aippt/theme_ppt.md) | 根据主题与大纲生成 HTML PPTX | `topic`, `outlines` |

## 二、文档生成 PPT

> 从现有文档到 PPT 的链路（会话 → 大纲 → 美化 → 生成）

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`aippt.doc_create_session`](aippt/doc_ppt.md) | 创建文档转 PPT 的 AI 会话 |  |
| [`aippt.doc_outline_options`](aippt/doc_ppt.md) | 解析文档并返回大纲选项问题 | `session_id`, `input` |
| [`aippt.doc_outline`](aippt/doc_ppt.md) | 生成完整 Markdown 大纲 | `session_id`, `checkpoint_id`, `input`, `resume_info` |
| [`aippt.doc_beautify`](aippt/doc_ppt.md) | 为 Markdown 大纲生成整套风格描述 | `topic`, `outline`, `user_intention` |
| [`aippt.doc_generate_ppt`](aippt/doc_ppt.md) | 根据主题与大纲生成最终 PPT | `topic`, `outlines` |


path: references/dbsheet/dashboard.md
content: # 仪表盘

## 1. dbsheet.dashboard_copy

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

复制：

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


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `dashboard_id` (integer, 必填): 源仪表盘 ID
- `body` (object, 必填): 须含 name（新仪表盘名称）；其它字段以接口约定为准

**body 根级必填（与 SkillHub 校验一致）**

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 新仪表盘名称 |

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 新仪表盘 id 等 |


---

## 2. dbsheet.dashboard_list

#### 功能说明


**必填 query**：无。



#### 调用示例

列出仪表盘：

```json
{
  "file_id": "string"
}
```


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | dashboards 数组 |


---



path: references/dbsheet/data_table.md
content: # 数据表管理

## 1. dbsheet.get_schema

#### 功能说明

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



#### 调用示例

获取全部数据表结构：

```json
{
  "file_id": "string"
}
```

获取指定数据表结构：

```json
{
  "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`

#### 返回值说明

```json
{
  "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"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.sheets[].id` | integer | 数据表 ID |
| `detail.sheets[].name` | string | 数据表名称 |
| `detail.sheets[].primary_field_id` | string | 主字段 ID |
| `detail.sheets[].records_count` | integer | 总记录数 |
| `detail.sheets[].record_ids` | array | 所有记录 ID（需开启 `include_all_record_ids`） |
| `detail.sheets[].fields` | array | 字段列表 |
| `detail.sheets[].views` | array | 视图列表 |
| `detail.book_type` | string | 文档类型标识，固定为 db |
| `result` | string | ok 表示成功 |


---

## 2. dbsheet.create_sheet

#### 功能说明

在多维表格文档中创建新的数据表，支持同时指定初始视图和字段。



#### 操作约束

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

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

> 字段的 `data` 配置（如选项列表、日期格式等）与 `dbsheet.create_fields` 完全一致，详见其 `param_detail`
> `Url` 字段传字符串时地址和显示文本相同；传对象时可分别设置 `address` 和 `displayText`
> `Link` 字段的关联目标数据表需在字段 `data.link_sheet` 中指定；创建数据表时若暂不配置可留空，后续通过 `dbsheet.update_fields` 补充

#### 调用示例

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

```json
{
  "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 字段类型枚举及值传入格式）
  - `name` (string, 必填): 字段显示名称
  - `type` (string, 必填): 字段类型枚举（见 param_detail）
  - `data` (object, 视类型可选): 类型专属配置，与 `dbsheet.create_fields` 的 `data` 结构相同

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

| 类型值 | 说明 | 是否自动字段 |
|--------|------|------------|
| `MultiLineText` | 多行文本 | 否 |
| `Date` | 日期 | 否 |
| `Time` | 时间 | 否 |
| `Number` | 数值 | 否 |
| `Currency` | 货币 | 否 |
| `Percentage` | 百分比 | 否 |
| `ID` | 身份证 | 否 |
| `Phone` | 电话 | 否 |
| `Email` | 电子邮箱 | 否 |
| `Url` | 超链接 | 否 |
| `Checkbox` | 复选框 | 否 |
| `SingleSelect` | 单选项 | 否 |
| `MultipleSelect` | 多选项 | 否 |
| `Rating` | 等级 | 否 |
| `Complete` | 进度条 | 否 |
| `Contact` | 联系人 | 否 |
| `Attachment` | 附件 | 否 |
| `Link` | 关联 | 否 |
| `Note` | 富文本 | 否 |
| `Address` | 地址 | 否 |
| `Cascade` | 级联 | 否 |
| `Department` | 部门 | 否 |
| `AutoNumber` | 编号 | **是** |
| `CreatedBy` | 创建者 | **是** |
| `CreatedTime` | 创建时间 | **是** |
| `LastModifiedBy` | 最后修改者 | **是** |
| `LastModifiedTime` | 最后修改时间 | **是** |
| `Formula` | 公式 | **是** |
| `Lookup` | 引用 | **是** |
| `BarCode` | 条码字段 | **是** |
| `SearchLookup` | 查找引用 | **是** |
| `Button` | 按钮 | **是** |
| `OneWayLink` | 单向关联 | **是** |

---

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

| 类型值 | 说明 |
|--------|------|
| `Grid` | 表格视图 |
| `Kanban` | 看板视图 |
| `Gallery` | 画册视图 |
| `Form` | 表单视图 |
| `Gantt` | 甘特视图 |
| `Query` | 查询视图 |
| `Calendar` | 日历视图 |

---

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

| 字段类型 | 值格式 | 示例 |
|---------|--------|------|
| `MultiLineText` | string | `"文本内容"` |
| `Date` | string（yyyy/mm/dd） | `"2025/11/15"` |
| `Time` | string（hh:mm:ss） | `"11:12:15"` |
| `Number` / `Currency` / `Percentage` | int \| float | `123` |
| `ID` / `Phone` / `Email` | string | `"18800000000"` |
| `Url` | object 或 string | `{"address":"https://…","displayText":"百度"}` 或 `"https://…"`（同时设置地址和文本） |
| `Checkbox` | boolean | `true` |
| `SingleSelect` | string（选项 value） | `"选项1"` |
| `MultipleSelect` | string[]（选项 value 数组） | `["选项1","选项2"]` |
| `Rating` / `Complete` | int | `3` / `80` |
| `Contact` | object[] | `[{"id":"uid","nickname":"张三","avatar_url":"https://…"}]` |
| `Attachment` | object[] | `[{"uploadId":"…","fileName":"a.png","size":1024,"source":"Cloud","type":"image/png"}]`；`linkUrl`、`imgSize` 选填 |
| `Link` | string[] | `["record_id_1","record_id_2"]` |
| `Address` | object | `{"districts":["广东省","珠海市","香洲区"],"detail":"详细地址"}` |
| `Cascade` | object | `{"districts":["一级","二级"]}` |
| `Department` | object[] | `[{"districts":["总部","研发部"],"detail":"dept_id"}]` |
| `Note` | object | `{"fileId":"…","summary":"摘要","modifyDate":"2025/12/31 10:00:00"}` |
| `AutoNumber`、`CreatedBy`、`CreatedTime`、`LastModifiedBy`、`LastModifiedTime`、`Formula`、`Lookup` | — | **自动字段，无需填写** |


#### 返回值说明

```json
{
  "detail": {
    "sheet": {
      "id": 6,
      "name": "新数据表",
      "primary_field_id": "L",
      "fields": [
        { "id": "L", "name": "名称", "type": "SingleLineText" }
      ],
      "views": [
        { "id": "J", "name": "默认视图", "type": "Grid" }
      ]
    }
  },
  "result": "ok"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.sheet.id` | integer | 新建数据表 ID |
| `detail.sheet.name` | string | 数据表名称 |
| `detail.sheet.primary_field_id` | string | 主字段 ID |
| `detail.sheet.fields` | array | 字段列表 |
| `detail.sheet.views` | array | 视图列表 |
| `result` | string | ok 表示成功 |


---

## 3. dbsheet.update_sheet

#### 功能说明

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


#### 操作约束

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

**幂等性**：是

#### 调用示例

重命名数据表：

```json
{
  "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, 可选): 主字段名称

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.sheet.id` | integer | 数据表 ID |
| `detail.sheet.name` | string | 数据表名称 |
| `result` | string | ok 表示成功 |


---

## 4. dbsheet.delete_sheet

#### 功能说明

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


#### 操作约束

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

**幂等性**：是

#### 调用示例

删除数据表：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.sheet.id` | integer | 已删除的数据表 ID |
| `result` | string | ok 表示成功 |


---

## 5. dbsheet.sheet_batch_create

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

批量建表：

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


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `body` (object, 必填): 须含 sheets 数组

**body 根级必填**

| 字段 | 类型 | 说明 |
|------|------|------|
| `sheets` | array | 每个元素描述一个待建数据表（名称、字段、视图等），子字段以接口约定为准（batch-create-sheet） |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 创建结果 |


---

## 6. dbsheet.sheet_batch_delete

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

批量删除：

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


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `body` (object, 必填): 须含 sheet_ids

**body 根级必填**

| 字段 | 类型 | 说明 |
|------|------|------|
| `sheet_ids` | array[integer] | 待删除数据表 ID 列表 |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---



path: references/dbsheet/field.md
content: # 字段管理

## 1. dbsheet.create_fields

#### 功能说明

在指定数据表中批量创建字段。请求体为 JSON：`fields[]` 每项含 `name`、`type` 及类型相关的 `data`；详见 param_detail 中各字段类型定义。创建成功后由服务端分配字段 `id`，**创建请求中禁止手填 `id`**。



#### 操作约束

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

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

> 选项类字段的选项定义在 `data.items` 内；与旧文档中把 `items` 写在字段根级的写法不同，以本接口 JSON 为准。
> 身份证字段类型名为 `ID`；部分历史示例写作 `Id`，以平台校验为准。

#### 调用示例

创建多种类型字段：

```json
{
  "file_id": "string",
  "sheet_id": 3,
  "prefer_id": false,
  "fields": [
    {
      "name": "状态",
      "type": "SingleSelect",
      "data": {
        "allow_add_item_while_inputting": true,
        "items": [
          {
            "value": "待处理",
            "id": "1"
          },
          {
            "value": "进行中",
            "id": "2"
          },
          {
            "value": "已完成",
            "id": "3"
          }
        ]
      }
    },
    {
      "name": "截止日期",
      "type": "Date",
      "data": {
        "number_format": "yyyy/mm/dd",
        "default_value_type": "RecordCreateTime"
      }
    },
    {
      "name": "备注",
      "type": "MultiLineText",
      "data": {
        "unique_value": false
      }
    }
  ]
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID（路径参数）
- `sheet_id` (integer, 必填): 数据表 ID
- `fields` (array, 必填): 待创建字段列表；每项为对象，至少含 `name`、`type`，多数类型需额外 `data`（结构因类型而异，见 param_detail）
  - `name` (string, 必填): 字段显示名称
  - `type` (string, 必填): 字段类型枚举（见 param_detail 完整列表；如 `Date`、`ID`、`Percent`/`Percentage` 等以平台校验为准）
  - `data` (object, 视类型必填/可选): 类型专属配置；无专属属性时可省略或 `{}`
  - **禁止**在创建请求中传入 `id`：`id` 仅创建成功后由服务端返回
- `prefer_id` (boolean, 可选): 默认 `false`（以字段**名称**解析关联）。为 `true` 时，**Lookup** 的 `link_field`/`lookup_field`、**LastModifiedBy**/**LastModifiedTime** 的 `watched_field` 等须传**字段 id**

**请求详情**

| 项目 | 值 |
|------|-----|
| Method | `POST` |
| Content-Type | `application/json` |

**请求体根级**

| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `fields` | array[object] | 是 | 每项：`name`、`type`、可选 `data`（见下文各类型） |
| `prefer_id` | boolean | 否 | 默认 `false`。`true` 时 Lookup / 监控类字段中的引用须用**字段 id** |

**`fields[]` 通用属性（创建）**

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 字段显示名称 |
| `type` | string | 是 | 字段类型（下列各节枚举） |
| `data` | object | 视类型 | 该类型的专属配置；无配置时可省略或 `{}` |
| `id` | string | **禁止** | 仅创建后由服务端返回，**不可**在 CreateField 中手填 |

以下为各 **`type`** 在 **`data`** 中的要求及录入值类型说明（**CreateRecord** 仅帮助理解字段语义；写记录请用 `dbsheet.create_records`）。

---

**1. `Date` 日期**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 日期显示格式（Excel 风格数字格式串） |
| `default_value_type` | string | `RecordCreateTime` 记录创建时间；`Normal` 指定默认日期；不传则不自动填 |
| `default_value` | string | 当 `default_value_type` 为 `Normal` 时必填，如 `"2024/11/23"` |

录入值：符合 `number_format` 的日期字符串。

---

**2. `Time` 时间**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 时间格式，如 `hh:mm:ss;@`、`[$-409]h:mm:ss AM/PM;@` |

录入值：符合格式的时间字符串。

---

**3. `Number` 数字**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 数字显示格式，如 `"0_ "`、`"#,##0.000_ "` |

录入值：`int` / `float`。

---

**4. `Currency` 货币**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 货币格式，如 `"$#,##0.000_ "` |

录入值：`int` / `float`。

---

**5. `MultiLineText` 多行文本**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `unique_value` | boolean | 是否禁止重复录入 |

录入值：string。

---

**6. `Percent` / `Percentage` 百分比**

类型名以平台为准（文档中常见 `Percent` 与 `Percentage` 两种写法）。

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 如 `"0.00%"` |

录入值：`int` / `float`（与格式一致的百分比数值）。

---

**7. `ID` 身份证**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `unique_value` | boolean | 是否禁止重复 |

录入值：string。

---

**8. `Phone` 电话**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `unique_value` | boolean | 是否禁止重复 |

录入值：string。

---

**9. `LastModifiedBy` 最后修改者**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `watch_all` | boolean | 是否监控所有字段，默认 `true` |
| `watched_field` | string[] | `watch_all=false` 时**必填**：被监控字段的 **id** 列表（与 `prefer_id` 一致时用 id） |

系统字段：**CreateRecord 不支持手填**，由系统自动维护。

---

**10. `LastModifiedTime` 最后修改时间**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `watch_all` | boolean | 默认 `true` |
| `watched_field` | string[] | `watch_all=false` 时必填，字段 id 数组 |
| `number_format` | string | 显示格式 |

录入值：时间字符串。系统字段：**CreateRecord 一般不手填**（以产品行为为准）。

---

**11. `Formula` 公式**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `formula` | string | 公式串，如 `"=[单件盈利]*[件数]"`（列名用 `[]`） |
| `number_format` | string | 结果展示格式 |
| `value_type` | string | **仅响应**：如 `Fvt_number`、`Fvt_Text`；公式引用文本列时常用 `Fvt_Text` |

**CreateRecord**：自动计算，**不支持手填**。

---

**12. `AutoNumber` 编号**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 如 `"000000"` 控制显示位数 |

**CreateRecord**：自动字段，**不支持手填**。

---

**13. `CreatedTime` 创建时间**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 如 `yyyy-mm-dd hh:mm;@` |

**CreateRecord**：自动字段，**不支持手填**。

---

**14. `Link` 关联**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `link_sheet` | integer | 关联数据表 id |
| `link_view` | string | 关联表视图 id |
| `is_auto` | boolean | 是否自动关联 |
| `multiple_links` | boolean | 是否允许多条关联 |
| `filter` | object | 可选；自动关联条件，结构见下 **FieldLinkFilter** |

**FieldLinkFilter**

| 键 | 类型 | 说明 |
|----|------|------|
| `mode` | string | 如 `"And"` |
| `conditions` | array | 每项可含 `current_sheet_field_id`、`link_sheet_field_id` 等 |

录入值：关联记录 id 的字符串数组 `[]string`。

---

**15. `Lookup` 引用**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `link_field` | string | 对应 **Link** 字段的 id |
| `lookup_field` | string | 被引用表中的字段 id |
| `aggregation` | string | `ToString`、`Origin`、`Sum`、`Counta`、`Average`、`Max`、`Min`、`Unique`、`CountaUnique` 等 |
| `base_type` | string | 引用语义分类；如 `"1"` 引用字段 / `"MultiLineText"` 等与开放文档一致 |
| `filter` | object | 可选；**统计 / 查找**类可与 `Link` 相同结构的 FieldLinkFilter |
| `lookup_sheet_id` | integer | 与 `link_field` 常互斥：直接指定被引用表时可不传 `link_field` |

**CreateRecord**：自动字段，**不支持手填**。

---

**16. `Url` 超链接**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `display_text` | string | 按钮文案；不填则非按钮模式展示 |

录入值：对象 `{ "address": string, "displayText": string }`（`displayText` 在非按钮模式下为显示文本）。

---

**17. `SingleSelect` 单选项**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `items` | array | **FieldSelectItem**：`value`（必填）、`color`（可选 int）、`id`（**仅响应**或预置时可选） |
| `allow_add_item_while_inputting` | boolean | 是否允许输入时新增选项 |

录入值：string（选中项的 `value`）。

---

**18. `MultipleSelect` 多选项**

同 SingleSelect 的 `items` / `allow_add_item_while_inputting`。

录入值：`string[]`（多个选项 `value`）。

---

**19. `Rating` 等级**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `max` / `max_value` | integer | 等级上限；不同环境字段名可能为 `max` 或 `max_value`，与 **get_schema 返回**保持一致 |

录入值：int。

---

**20. `Contact` 联系人**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `default_value_type` | string | `RecordCreator` 记录创建者；`Normal` 搭配 `default_value` 填指定用户 uid |
| `default_value` | string | `Normal` 时：用户 uid |
| `multiple_contacts` | boolean | 是否支持多联系人 |
| `notice_new_contact` | boolean | 是否通知联系人 |
| `support_multi` | boolean | **仅响应**；创建时可不传 |

录入值：对象数组，元素含 `id`、`nickname`、`avatar_url` 等。

---

**21. `Attachment` 附件**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `only_upload_by_camera` | boolean | 是否仅允许拍照上传 |

录入值：对象数组（`uploadId`、`fileName`、`size`、`source`、`type`、`linkUrl`、`imgSize` 等）。

---

**22. `Address` 地址**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `address_level` | int | 层级：1 省 … 5 省/市/区/街道/社区 |
| `detailed_address` | boolean | 是否要求额外详细地址 |
| `preset_address` | object | `detail`（详细）、`districts`（与层级对应的地区名数组） |

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

---

**23. `Note` 富文本**

无专属 `data` 配置。

录入值：`{ "fileId", "summary", "modifyDate" }`（以开放文档为准）。

---

**24. `Checkbox` 复选框**

无专属 `data`。

录入值：boolean。

---

**25. `Complete` 进度**

无专属 `data`。

录入值：int。

---

**26. `Email` 邮箱**

无专属 `data`。

录入值：string。

---

**27. `CreatedBy` 创建人**

无专属 `data`。

**CreateRecord**：自动字段，**不需要传入**；返回含 `id`、`nickName` 等。

---

**其它**

- **`SingleLineText`** 等未在上表展开的类型：以开放文档及 `get_schema` 返回为准。
- 响应中可能含 **`data.value_type`**（公式等）、**`default_value_array`**（联系人）等仅响应字段，创建时勿强行照搬。

**请求体节选示例**

```json
{
  "fields": [
    { "name": "单选项", "type": "SingleSelect", "data": { "allow_add_item_while_inputting": true, "items": [{ "value": "选项1" }] } },
    { "name": "关联", "type": "Link", "data": { "link_sheet": 12, "link_view": "Y", "is_auto": true, "multiple_links": true } }
  ],
  "prefer_id": false
}
```


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.fields[].id` | string | 新建字段 ID |
| `detail.fields[].name` | string | 字段名称 |
| `detail.fields[].type` | string | 字段类型 |
| `detail.fields[].items` | array | 选项列表（选项类字段） |
| `result` | string | ok 表示成功 |


---

## 2. dbsheet.update_fields

#### 功能说明

批量更新数据表中已有字段的名称、选项等属性。每项更新必须包含字段 ID。


#### 操作约束

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

**幂等性**：是

> 更新字段时，`id` 为必填项（与创建字段相反，创建时禁止传入 `id`）；可通过 get_schema 获取字段 id。
> 选项类字段（SingleSelect / MultipleSelect）更新 `items` 时，含 `id` 的项为更新，不含 `id` 的项为新增，未出现的 `id` 对应选项会被删除。

#### 调用示例

更新日期字段格式：

```json
{
  "file_id": "abc123",
  "sheet_id": 1,
  "fields": [
    {
      "id": "q",
      "name": "日期",
      "type": "Date",
      "data": {
        "number_format": "yyyy\"年\"m\"月\"d\"日\";@",
        "default_value_type": "Normal",
        "default_value": "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, 可选): 字段类型，更新时一般与原类型一致
  - `data` (object, 视类型可选): 类型专属配置，结构与创建字段相同（见 param_detail）
- `prefer_id` (boolean, 可选): 默认 `false`（以字段**名称**解析关联）。为 `true` 时，**Lookup** 的 `link_field`/`lookup_field`、**LastModifiedBy**/**LastModifiedTime** 的 `watched_field` 等须传**字段 id**

**请求详情**

| 项目 | 值 |
|------|-----|
| Method | `POST` |
| Content-Type | `application/json` |

**请求体根级**

| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `fields` | array[object] | 是 | 每项：`id`（必填）、`name`、`type`、可选 `data`（见下文各类型） |
| `prefer_id` | boolean | 否 | 默认 `false`。`true` 时 Lookup / 监控类字段中的引用须用**字段 id** |

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

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | **是** | 目标字段 ID，通过 get_schema 获取 |
| `name` | string | 否 | 字段显示名称 |
| `type` | string | 否 | 字段类型，通常与原类型一致 |
| `data` | object | 视类型 | 类型专属配置，结构与 create_fields 相同（见下文） |

以下为各 **`type`** 在 **`data`** 中的配置说明，与 `dbsheet.create_fields` 的 param_detail 一致。

---

**1. `Date` 日期**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 日期显示格式（Excel 风格数字格式串） |
| `default_value_type` | string | `RecordCreateTime` 记录创建时间；`Normal` 指定默认日期；不传则不自动填 |
| `default_value` | string | 当 `default_value_type` 为 `Normal` 时必填，如 `"2024/11/23"` |

---

**2. `Time` 时间**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 时间格式，如 `hh:mm:ss;@`、`[$-409]h:mm:ss AM/PM;@` |

---

**3. `Number` 数字**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 数字显示格式，如 `"0_ "`、`"#,##0.000_ "` |

---

**4. `Currency` 货币**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 货币格式，如 `"$#,##0.000_ "` |

---

**5. `MultiLineText` 多行文本**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `unique_value` | boolean | 是否禁止重复录入 |

---

**6. `Percent` / `Percentage` 百分比**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 如 `"0.00%"` |

---

**7. `ID` 身份证**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `unique_value` | boolean | 是否禁止重复 |

---

**8. `Phone` 电话**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `unique_value` | boolean | 是否禁止重复 |

---

**9. `LastModifiedBy` 最后修改者**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `watch_all` | boolean | 是否监控所有字段，默认 `true` |
| `watched_field` | string[] | `watch_all=false` 时**必填**：被监控字段的 **id** 列表 |

---

**10. `LastModifiedTime` 最后修改时间**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `watch_all` | boolean | 默认 `true` |
| `watched_field` | string[] | `watch_all=false` 时必填，字段 id 数组 |
| `number_format` | string | 显示格式 |

---

**11. `Formula` 公式**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `formula` | string | 公式串，如 `"=[单件盈利]*[件数]"`（列名用 `[]`） |
| `number_format` | string | 结果展示格式 |

---

**12. `AutoNumber` 编号**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 如 `"000000"` 控制显示位数 |

---

**13. `CreatedTime` 创建时间**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `number_format` | string | 如 `yyyy-mm-dd hh:mm;@` |

---

**14. `Link` 关联**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `link_sheet` | integer | 关联数据表 id |
| `link_view` | string | 关联表视图 id |
| `is_auto` | boolean | 是否自动关联 |
| `multiple_links` | boolean | 是否允许多条关联 |
| `filter` | object | 可选；自动关联条件（FieldLinkFilter） |

---

**15. `Lookup` 引用**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `link_field` | string | 对应 **Link** 字段的 id |
| `lookup_field` | string | 被引用表中的字段 id |
| `aggregation` | string | `ToString`、`Origin`、`Sum`、`Counta`、`Average`、`Max`、`Min`、`Unique`、`CountaUnique` 等 |
| `base_type` | string | 引用语义分类 |
| `filter` | object | 可选；统计 / 查找条件 |
| `lookup_sheet_id` | integer | 直接指定被引用表时可不传 `link_field` |

---

**16. `Url` 超链接**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `display_text` | string | 按钮文案；不填则非按钮模式 |

---

**17. `SingleSelect` 单选项**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `items` | array | **FieldSelectItem**：`value`（必填）、`color`（可选 int）、`id`（含 id 表示更新已有选项，不含则新增） |
| `allow_add_item_while_inputting` | boolean | 是否允许输入时新增选项 |

---

**18. `MultipleSelect` 多选项**

同 SingleSelect 的 `items` / `allow_add_item_while_inputting`。

---

**19. `Rating` 等级**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `max` / `max_value` | integer | 等级上限；与 get_schema 返回字段名保持一致 |

---

**20. `Contact` 联系人**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `default_value_type` | string | `RecordCreator` 记录创建者；`Normal` 搭配 `default_value` 填指定用户 uid |
| `default_value` | string | `Normal` 时：用户 uid |
| `multiple_contacts` | boolean | 是否支持多联系人 |
| `notice_new_contact` | boolean | 是否通知联系人 |

---

**21. `Attachment` 附件**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `only_upload_by_camera` | boolean | 是否仅允许拍照上传 |

---

**22. `Address` 地址**

| `data` 键 | 类型 | 说明 |
|-------------|------|------|
| `address_level` | int | 层级：1 省 … 5 省/市/区/街道/社区 |
| `detailed_address` | boolean | 是否要求额外详细地址 |
| `preset_address` | object | `detail`（详细）、`districts`（与层级对应的地区名数组） |

---

**其它类型**（`Note` 富文本、`Checkbox` 复选框、`Complete` 进度、`Email` 邮箱、`CreatedBy` 创建人、`SingleLineText` 等）无专属 `data` 配置，以 get_schema 返回及开放文档为准。

**请求体节选示例**

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 响应代码，非 0 表示失败 |
| `msg` | string | 响应信息 |
| `data.fields` | array | 更新后的字段列表，详见多维表格参数说明 |
| `more` | object | 更多的错误信息 |


---

## 3. dbsheet.delete_fields

#### 功能说明

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


#### 操作约束

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

**幂等性**：是

#### 调用示例

删除多个字段：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.fields` | array | 删除结果列表，每项包含 `id` 和 `deleted` |
| `result` | string | ok 表示成功 |


---



path: references/dbsheet/form.md
content: # 表单视图

## 1. dbsheet.form_list_fields

#### 功能说明


**必填 query**：无。

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



#### 调用示例

列出表单字段：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 表单字段列表 |


---

## 2. dbsheet.form_update_field

#### 功能说明


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



#### 操作约束

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

**幂等性**：是

#### 调用示例

更新字段：

```json
{
  "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 根级必填**

| 字段 | 类型 | 说明 |
|------|------|------|
| `field` | object | 要更新的字段属性，子字段以 update-fields 文档 为准 |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---

## 3. dbsheet.form_get_meta

#### 功能说明


**必填 query**：无。

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



#### 调用示例

获取 meta：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 标题、描述等元数据 |


---

## 4. dbsheet.form_update_meta

#### 功能说明


**前置条件**：表单视图。



**幂等性**：是

#### 调用示例

更新 meta：

```json
{
  "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, 必填): 须含 meta 对象

**body 根级必填**

| 字段 | 类型 | 说明 |
|------|------|------|
| `meta` | object | 表单展示配置，子字段以 update-meta 文档 为准 |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---



path: references/dbsheet/parent_child.md
content: # 父子记录

## 1. dbsheet.parent_disable

#### 功能说明


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



#### 操作约束

- **提示**：行为以接口说明为准

**幂等性**：是

#### 调用示例

禁用：

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


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `body` (object, 可选): 若接口要求附加参数则传入；否则可 {}

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---

## 2. dbsheet.parent_enable

#### 功能说明


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



**幂等性**：是

#### 调用示例

启用：

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


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `body` (object, 可选): 若接口要求附加参数则传入；否则可 {}

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---

## 3. dbsheet.parent_status

#### 功能说明


**必填 query**：无。



#### 调用示例

查询状态：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 是否禁用等 |


---

## 4. dbsheet.parent_bind_children

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

绑定子记录：

```json
{
  "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 根级必填**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `child_ids` | array[string] | 是 | 子记录 ID 数组 |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---

## 5. dbsheet.parent_list_children

#### 功能说明


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

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



#### 调用示例

列出子记录：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 子记录列表 |


---

## 6. dbsheet.parent_unbind_children

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

解绑：

```json
{
  "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 根级必填**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `child_ids` | array[string] | 是 | 子记录 ID 数组 |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---



path: references/dbsheet/permission.md
content: # 高级权限

## 1. dbsheet.permission_list_roles

#### 功能说明


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

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



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

#### 调用示例

列举角色：

```json
{
  "file_id": "string"
}
```


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | permissions 列表（含系统角色等） |


---

## 2. dbsheet.permission_query_task

#### 功能说明


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

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



#### 调用示例

查询任务：

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


#### 参数说明

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

**请求参数**

| 位置 | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| Path | `file_id` | string | 是 | 文件 ID |
| Path | `task_id` | string | 是 | 异步任务 ID |
| Query | `task_type` | content_permission | 是 | 异步任务类型 |

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 任务状态与结果数据 |


---

## 3. dbsheet.permission_create_roles_async

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

创建角色：

```json
{
  "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 根级必填**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `content_permission_name` | string | 是 | 内容权限组名称 |
| `permission_data` | array[object] | 是 | 内容权限组相关信息，传递给内核设置权限用，服务端不关注内部业务语义 |

**`permission_data[]` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sheet_id` | integer | 是 | 数据表 ID |
| `sheet_permission_type` | string | 是 | 权限设置。可选值：`Permission_NoPermission`（无权限）、`Permission_View`（可查看）、`Permission_Edit`（可编辑）、`Permission_Manage`（可管理） |
| `record_config_type` | string | 否 | 可编辑模式下行范围限制。可选值：`All`（全部记录）、`Self`（协作者自己创建的记录）、`Custom`（自定义） |
| `edit_sheet_config` | object | 否 | 可编辑模式下行列条件配置（`sheet_permission_type=Permission_Edit` 时传） |
| `viewed_sheet_config` | object | 否 | 查看权限相关配置（可编辑、可查看时必须传） |

**`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` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field_filter` | array[string] | 是 | 列条件。指定可编辑字段 ID；`is_all_field` 必须为 `false` |
| `is_add_record` | boolean | 否 | 是否允许添加记录，默认 `true` |
| `is_all_field` | boolean | 是 | 是否可编辑全部字段；此场景必须传 `false` |
| `is_all_record` | boolean | 否 | 是否可编辑全部记录，默认 `true` |
| `is_remove_record` | boolean | 否 | 是否允许删除记录，默认 `true` |
| `record_filter` | object | 否 | 行条件。指定可编辑记录；前提通常为 `record_config_type=Custom` 且 `is_all_record=false` |

**`viewed_sheet_config` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field_filter` | array[string] | 是 | 列条件。指定可查看字段 ID；`is_all_field` 必须为 `false` |
| `is_all_field` | boolean | 是 | 是否可查看全部字段；此场景必须传 `false` |
| `is_all_record` | boolean | 否 | 是否可查看全部记录，默认 `true` |
| `record_filter` | object | 否 | 行条件。指定可查看/可编辑记录范围 |

**`record_filter` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `criteria` | array[object] | 是 | 筛选条件数组；同一字段不应定义多个条件 |
| `mode` | string | 否 | 条件逻辑关系，仅支持 `AND` 或 `OR`，默认 `AND` |

**`criteria[]` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field` | string | 否 | 字段名 |
| `operator` | string | 否 | 筛选规则。可选值：`Equals`、`NotEqu`、`Greater`、`GreaterEqu`、`Less`、`LessEqu`、`GreaterEquAndLessEqu`、`LessOrGreater`、`BeginWith`、`EndWith`、`Contains`、`NotContains`、`Intersected`、`Empty`、`NotEmpty` |
| `values` | array[string] | 是 | 筛选对比值；元素为字符串时表示文本匹配 |

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

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 含 task_id 等 |


---

## 4. dbsheet.permission_update_roles_async

#### 功能说明


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



#### 操作约束

- **后置验证**：轮询 permission_query_task

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

#### 调用示例

更新角色：

```json
{
  "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 根级必填**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `cloud_permission_id` | integer | 是 | 需要修改的权限组云 ID |
| `content_permission_name` | string | 是 | 内容权限组名称 |
| `permission_data` | array[object] | 是 | 内容权限组相关信息，传递给内核设置权限用，服务端不关注内部业务语义 |

**`permission_data[]` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sheet_id` | integer | 是 | 数据表 ID |
| `sheet_permission_type` | string | 是 | 权限设置。可选值：`Permission_NoPermission`（无权限）、`Permission_View`（可查看）、`Permission_Edit`（可编辑）、`Permission_Manage`（可管理） |
| `record_config_type` | string | 否 | 可编辑模式下行范围限制。可选值：`All`（所有记录）、`Self`（协作者自己创建的记录）、`Custom`（自定义） |
| `edit_sheet_config` | object | 否 | 可编辑模式下行列条件配置（`sheet_permission_type=Permission_Edit` 时传） |
| `viewed_sheet_config` | object | 否 | 内容查看权限相关配置（可编辑、可查看时可传） |

**`edit_sheet_config` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field_filter` | array[string] | 是 | 列条件。指定哪些字段可以编辑；`is_all_field` 必须为 `false` |
| `is_add_record` | boolean | 否 | 非必带，默认 `true`。是否允许添加记录 |
| `is_all_field` | boolean | 否 | 非必带，默认 `true`。是否可编辑全部字段 |
| `is_all_record` | boolean | 否 | 非必带，默认 `true`。是否可编辑全部记录 |
| `is_remove_record` | boolean | 否 | 非必带，默认 `true`。是否允许删除记录 |
| `record_filter` | object | 否 | 行条件。指定哪些记录可以编辑；前提通常为 `record_config_type=Custom` 且 `is_all_record=false` |

**`viewed_sheet_config` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field_filter` | array[string] | 是 | 列条件。指定哪些字段可以查看；`is_all_field` 必须为 `false` |
| `is_all_field` | boolean | 否 | 非必带，默认 `true`。是否可查看全部字段 |
| `is_all_record` | boolean | 否 | 非必带，默认 `true`。是否可查看全部记录 |
| `record_filter` | object | 否 | 行条件。指定哪些记录可以编辑；前提通常为 `record_config_type=Custom` 且 `is_all_record=false` |

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

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `criteria` | array[object] | 是 | 可通过 `criteria` 数组定义 filter 条件；同一字段不应定义多个条件 |
| `mode` | string | 否 | 各筛选条件之间的逻辑关系，仅支持 `AND` 或 `OR`，默认 `AND` |

**`record_filter.criteria[]` 字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `field` | string | 否 | 字段名 |
| `operator` | string | 否 | 筛选规则。可选值：`Equals`、`NotEqu`、`Greater`、`GreaterEqu`、`Less`、`LessEqu`、`GreaterEquAndLessEqu`、`LessOrGreater`、`BeginWith`、`EndWith`、`Contains`、`NotContains`、`Intersected`、`Empty`、`NotEmpty` |
| `values` | array[string] | 是 | 筛选规则对比值；元素为字符串时表示文本匹配 |

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

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 含 task_id 等 |


---

## 5. dbsheet.permission_delete_roles_async

#### 功能说明


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



#### 操作约束

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

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

#### 调用示例

删除角色：

```json
{
  "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 根级必填**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `cloud_permission_id` | integer | 是 | 需要删除的权限组云 ID |
| `replace_cloud_permission_id` | integer | 是 | 替换的云权限 ID |
| `replace_permission_type` | string | 是 | 替换的权限组类型。可选值：`system`、`team_custom`、`content_custom` |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 含 task_id 等 |


---

## 6. dbsheet.permission_list_subjects

#### 功能说明

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



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

#### 调用示例

最小必填参数：

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

携带分页与别名：

```json
{
  "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 个 item

**请求参数**

| 位置 | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| Path | `file_id` | string | 是 | 文件 ID |
| Query | `cloud_permission_id` | integer | 是 | 云权限 ID |
| Query | `permission_type` | string | 是 | 权限组类型：`system`、`team_custom`、`content_custom` |
| Query | `alias_name` | string | 否 | 权限别名：`manageable`、`viewable`、`editable`（拿不到 permission_id 时可传） |
| Query | `page_token` | string | 否 | 分页起始位置标识；首页可不传，默认分页数量 20 个 item |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 成员主体列表 |


---



path: references/dbsheet/record.md
content: # 记录操作

## 1. dbsheet.create_records

#### 功能说明

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



#### 操作约束

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

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

> `records[].fields` 是对象（key-value 映射），不是序列化 JSON 字符串
> 关联字段（Link）值格式为 `{"recordIds": ["id1", "id2"]}`，而非直接传 id 数组
> `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_value`（非 `max`）定义，可通过 get_schema 查询

#### 调用示例

按字段名批量创建记录：

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

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

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


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `records` (array[object], 必填): 要创建的记录列表，每个元素含 `fields` 对象（字段名/ID → 值的映射）
- `prefer_id` (boolean, 可选): 默认 `false`（以字段名解析）。为 `true` 时 `fields` 内部的 key 应为字段 ID
- `value_prefer_id` (boolean, 可选): 默认 `false`。为 `true` 时使用选项 ID 来标识选项值
- `omit_failure` (boolean, 可选): 默认 `false`。为 `true` 时单条记录写入失败不中断整批请求
- `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`）

**请求体根级参数**

| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sheetId` | integer | 是 | 数据表 ID |
| `records` | array[object] | 是 | 待创建记录列表，每项含 `fields` 对象 |
| `preferId` | boolean | 否 | 默认 `false`。`true` 时 `fields` 的 key 为字段 ID |
| `valuePreferId` | boolean | 否 | 默认 `false`。`true` 时用选项 ID 标识选项值 |
| `omitFailure` | boolean | 否 | 默认 `false`。`true` 时单条失败不中断整批 |
| `textValue` | string | 否 | 响应值格式：`original`（默认）/ `text` / `compound` |
| `linkValue` | string | 否 | 关联字段响应格式：`id`（默认）/ `all` |
| `bAddSelectItem` | boolean | 否 | 是否允许写入时同步新增选项 |
| `fieldValues` | array[object] | 否 | 需新增的选项配置，配合 `bAddSelectItem: true` 使用 |

**`records[]` 元素结构**

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `fields` | object | 是 | 字段名（或字段 ID）→ 值的映射对象 |

**`fieldValues[]` 元素结构**

| 属性 | 类型 | 说明 |
|------|------|------|
| `fieldId` | string | 要新增选项的字段 ID |
| `listItems` | array[object] | 待新增选项，每项含 `value`（string）和 `color`（string，如 `"0xF0EEF7"`） |

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

| 字段类型 | 值类型 | 示例值 | 备注 |
|---------|--------|--------|------|
| 文本类（SingleLineText / MultiLineText） | string | `"任务描述"` | — |
| 日期（Date） | string | `"2025/11/15"` | 须符合字段 `number_format` 格式 |
| 时间（Time） | string | `"11:12:15"` | 须符合字段时间格式 |
| 数字 / 货币 / 百分比（Number / Currency / Percent） | int \| float | `125` / `215` / `98` | — |
| 复选框（Checkbox） | boolean | `true` | — |
| 进度（Complete） | float | `1` | 进度值 0–1 |
| 等级（Rating） | int | `3` | 不超过字段 `max_value` 上限 |
| 单选项（SingleSelect） | string | `"选项1"` | 已有选项的 `value`；`bAddSelectItem=true` 时可传新选项 |
| 多选项（MultipleSelect） | string[] | `["选项1","选项2"]` | 已有选项 `value` 的字符串数组 |
| 电话 / 邮箱 / 身份证（Phone / Email / ID） | string | `"18800000000"` | — |
| 超链接（Url） | object | `{"address":"https://…","displayText":"百度"}` | 响应中以数组形式返回 |
| 关联（Link） | object | `{"recordIds":["I","G"]}` | `recordIds` 为关联记录 id 数组 |
| 联系人（Contact） | object[] | `[{"id":"uid","nickname":"张三","avatar_url":"https://…"}]` | `id` 为用户 uid |
| 地址（Address） | object | `{"districts":["广东省","珠海市","香洲区"],"detail":"详细地址"}` | `districts` 层级与字段 `address_level` 一致 |
| 富文本（Note） | object | `{"fileId":"…","summary":"摘要","modifyDate":"2024/12/09 12:00:00"}` | — |
| 附件（Attachment） | object[] | `[{"uploadId":"…","fileName":"a.png","size":1024,"source":"Cloud","type":"image/png"}]` | 需先上传获得 `uploadId`；`linkUrl`、`imgSize` 选填 |
| 公式 / 编号 / 创建时间 / 创建人 / 最后修改者 / 引用 | — | **不可填写** | 自动字段，传入会被忽略或报错 |

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

**请求体示例**

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

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

| 字段名 | 字段类型 | 值示例 |
|--------|----------|--------|
| `日期` | Date | `"2025/11/15"` |
| `时间` | Time | `"11:12:15"` |
| `数字` | Number | `125` |
| `货币` | Currency | `215` |
| `多行文本` | MultiLineText | `"yesit'sright"` |
| `百分比` | Percent | `0.98` |
| `身份证` | ID | `"110101**************9"` |
| `电话` | Phone | `"18800000000"` |
| `超链接` | Url | `{"address":"https://www.baidu.com","displayText":"百度"}` |
| `单选项` | SingleSelect | 已有选项的 `value` 字符串 |
| `多选项` | MultipleSelect | 已有选项 `value` 的字符串数组 |
| `等级` | Rating | 不超过字段 `max_value` 的整数 |
| `联系人` | Contact | `[{"id":"uid","nickname":"昵称","avatar_url":"…"}]` |
| `地址` | Address | `{"districts":["广东省","珠海市","香洲区"],"detail":"…"}` |
| `富文本` | Note | `{"fileId":"…","summary":"摘要","modifyDate":"2025/12/31"}` |
| `复选框` | Checkbox | `true` / `false` |
| `进度` | Complete | `0`–`100` 整数 |
| `邮箱` | Email | `"[REDACTED_SECRET]"` |
| `附件` | Attachment | `[{"uploadId":"…","fileName":"…","size":0,"source":"Cloud","type":"image/png"}]` |

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


#### 返回值说明

```json
{
  "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"
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 0 表示成功 |
| `data.records[].id` | string | 新建记录 ID |
| `data.records[].fields` | string | 序列化 JSON 字符串，包含创建后所有字段的实际值（含系统自动字段） |


---

## 2. dbsheet.update_records

#### 功能说明

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



#### 操作约束

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

**幂等性**：是

> `records[].fields` 是对象（key-value 映射），不是序列化 JSON 字符串；仅传入需要修改的字段，未传字段保持原值不变
> 关联字段（Link）值格式为 `{"recordIds": ["id1", "id2"]}`，而非直接传 id 数组
> `prefer_id=true` 时，`fields` 内部的 key 应为字段 ID（由 get_schema 返回），而非字段名
> `b_add_select_item=true` 时，可通过 `field_values` 预声明要新增的选项
> `text_value` 和 `link_value` 仅影响响应返回格式，不影响写入行为
> Url 字段传入为对象 `{address, displayText}`，响应中以数组形式返回
> Rating 字段的上限由 `max_value`/`max`定义，创建字段时通过 `dbsheet.create_fields` 设置

#### 调用示例

按字段名批量更新记录：

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

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

```json
{
  "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, 可选): 默认 `false`（以字段名解析）。为 `true` 时 `fields` 内部的 key 应为字段 ID
- `value_prefer_id` (boolean, 可选): 默认 `false`。为 `true` 时使用选项 ID 来标识选项值
- `omit_failure` (boolean, 可选): 默认 `false`。为 `true` 时单条记录写入失败不中断整批请求
- `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`）

**请求体根级参数**

| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sheetId` | integer | 是 | 数据表 ID |
| `records` | array[object] | 是 | 待更新记录列表，每项含 `id` 和 `fields` 对象 |
| `preferId` | boolean | 否 | 默认 `false`。`true` 时 `fields` 的 key 为字段 ID |
| `valuePreferId` | boolean | 否 | 默认 `false`。`true` 时用选项 ID 标识选项值 |
| `omitFailure` | boolean | 否 | 默认 `false`。`true` 时单条失败不中断整批 |
| `textValue` | string | 否 | 响应值格式：`original`（默认）/ `text` / `compound` |
| `linkValue` | string | 否 | 关联字段响应格式：`id`（默认）/ `all` |
| `bAddSelectItem` | boolean | 否 | 是否允许写入时同步新增选项 |
| `fieldValues` | array[object] | 否 | 需新增的选项配置，配合 `bAddSelectItem: true` 使用 |

**`records[]` 元素结构**

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | **是** | 目标记录 ID（通过 list_records / get_record 获取） |
| `fields` | object | 是 | 字段名（或字段 ID）→ 新值的映射对象；仅传需要修改的字段 |

**`fieldValues[]` 元素结构**

| 属性 | 类型 | 说明 |
|------|------|------|
| `fieldId` | string | 要新增选项的字段 ID |
| `listItems` | array[object] | 待新增选项，每项含 `value`（string）和 `color`（string，如 `"0xF0EEF7"`） |

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

| 字段类型 | 值类型 | 示例值 | 备注 |
|---------|--------|--------|------|
| 文本类（SingleLineText / MultiLineText） | string | `"新文本"` | — |
| 日期（Date） | string | `"2025/11/15"` | 须符合字段 `number_format` 格式 |
| 时间（Time） | string | `"11:12:15"` | 须符合字段时间格式 |
| 数字 / 货币 / 百分比（Number / Currency / Percent） | int \| float | `125` / `215` / `98` | — |
| 复选框（Checkbox） | boolean | `false` | — |
| 进度（Complete） | float | `0.5` | 进度值 0–1 |
| 等级（Rating） | int | `3` | 不超过字段 `max_value`/`max` 上限 |
| 单选项（SingleSelect） | string | `"选项1"` | 已有选项的 `value`；`bAddSelectItem=true` 时可传新选项 |
| 多选项（MultipleSelect） | string[] | `["选项1","选项2"]` | 已有选项 `value` 的字符串数组 |
| 电话 / 邮箱 / 身份证（Phone / Email / ID） | string | `"18800000000"` | — |
| 超链接（Url） | object | `{"address":"https://…","displayText":"百度"}` | 响应中以数组形式返回 |
| 关联（Link） | object | `{"recordIds":["I","G"]}` | `recordIds` 为关联记录 id 数组 |
| 联系人（Contact） | object[] | `[{"id":"uid","nickname":"张三","avatar_url":"https://…"}]` | `id` 为用户 uid |
| 地址（Address） | object | `{"districts":["广东省","珠海市","香洲区"],"detail":"详细地址"}` | `districts` 层级与字段 `address_level` 一致 |
| 富文本（Note） | object | `{"fileId":"…","summary":"摘要","modifyDate":"2024/12/09 12:00:00"}` | — |
| 附件（Attachment） | object[] | `[{"uploadId":"…","fileName":"a.png","size":1024,"source":"Cloud","type":"image/png"}]` | 需先上传获得 `uploadId`；`linkUrl`、`imgSize` 选填 |
| 公式 / 编号 / 创建时间 / 创建人 / 最后修改者 / 引用 | — | **不可填写** | 自动字段，传入会被忽略或报错 |

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

**请求体示例**

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 0 表示成功 |
| `msg` | string | 响应信息 |
| `data.records[].id` | string | 已更新记录 ID |
| `data.records[].fields` | object | 更新后所有字段的实际值（含系统自动字段） |


---

## 3. dbsheet.list_records

#### 功能说明

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



#### 调用示例

基础分页查询：

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

带筛选条件查询：

```json
{
  "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` (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`。


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.offset` | string | 下一页游标，无更多数据时不返回此字段 |
| `detail.records[].id` | string | 记录 ID |
| `detail.records[].fields` | object | 各字段的值 |
| `result` | string | ok 表示成功 |


---

## 4. dbsheet.get_record

#### 功能说明

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


#### 调用示例

获取单条记录：

```json
{
  "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, 可选): 是否返回字段定义信息

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.id` | string | 记录 ID |
| `detail.fields` | object | 各字段的值 |
| `result` | string | ok 表示成功 |


---

## 5. dbsheet.delete_records

#### 功能说明

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



#### 操作约束

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

**幂等性**：是

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

#### 调用示例

批量删除记录：

```json
{
  "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` | array[object] | 是 | 记录 ID 对象数组，每个元素为一条记录的 ID |

**请求体示例：**

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

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


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 响应代码，0 表示成功，非 0 表示失败 |
| `msg` | string | 响应信息 |
| `data.records` | array[object] | 删除结果列表 |
| `more` | object | 更多错误信息（失败时返回） |


---

## 6. dbsheet.records_list

#### 功能说明


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

| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| fields | array[string] | 是* | 指定返回记录中的字段；*文档写必填，若不填则默认返回全部字段。`prefer_id=true` 时填字段 id，否则填字段名 |
| filter | object | 否 | 筛选条件 |
| filter.criteria | array[object] | 条件内必填 | 条件数组，每项含 `field`（字段名/id）、`op`（操作符，如 Contains / Equal / Empty 等）、`values`（筛选值，Empty/NotEmpty 时可省略） |
| max_records | integer | 否 | 最多取前 max_records 条；不填则不限 |
| page_size | integer | 否 | 每页大小，默认 100，范围 1–1000 |
| page_token | string | 否 | 分页游标；有下一页时用上次的 page_token |
| prefer_id | boolean | 否 | 为 true 时 fields 等按字段 id 解析 |
| show_fields_info | boolean | 否 | 是否额外返回字段元信息（类似 Schema fields） |
| show_record_extra_info | boolean | 否 | 是否返回创建者、创建时间、最后修改者、最后修改时间等 |
| text_value | string | 否 | 不填默认 original；可选 original、text、compound |
| view_id | string | 否 | 指定视图则从该视图取用户可见记录；不填从工作表取 |



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

#### 调用示例

最简：

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

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

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

分页与视图：

```json
{
  "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 的值，需要输入字段名或字段 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` 与顶层字段，同键以 **顶层** 为准。


#### 返回值说明

```json
{
  "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": ""
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 响应代码，非 0 表示失败 |
| `msg` | string | 响应信息 |
| `data` | object | 响应数据 |
| `more` | object | 更多的错误信息 |


---

## 7. dbsheet.records_search

#### 功能说明


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

| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
| records | array[string] | 是 | 记录 id 列表 |
| prefer_id | boolean | 否 | 是否使用字段 / 选项 id 而不是字段 / 选项名来标识 |
| show_fields_info | boolean | 否 | 为 true 时额外返回 fields 结构体展示字段信息；返回范围取决于是否指定 fields 或 view_id |
| show_record_extra_info | boolean | 否 | 为 true 时额外显示创建者、创建时间、最后修改者、最后修改时间（与是否有对应字段无关） |
| text_value | string | 否 | 返回值类型，不填默认 original；可选 original、text、compound |



> records 为必填参数，需传入有效的记录 id 列表。
> records_search 在 MCP 层若要求 filter 为必填参数，传空条件 {"mode":"AND","criteria":[]} 即可满足

#### 调用示例

按记录 id 批量检索：

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

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

```json
{
  "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（原始值和文本值）

#### 返回值说明

```json
{
  "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"
      }
    ]
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 响应代码，非 0 表示失败 |
| `msg` | string | 响应信息 |
| `data` | object | 响应数据 |
| `more` | object | 更多的错误信息 |


---



path: references/dbsheet/share.md
content: # 分享视图

## 1. dbsheet.share_open_view

#### 功能说明


**前置条件**：对目标视图有管理分享权限；`view_id` 来自 `dbsheet.get_schema` 或 `dbsheet.views_list`。



#### 操作约束

- **前置检查**：逐项核对 file_id、sheet_id、view_id、body.permission、body.share_to、body.view_type 均已齐备；缺任一须停止并向用户列出缺少的参数名
- **禁止**：参数不齐时禁止调用，不得用默认值凑数或猜测缺失参数
- **后置验证**：可用 dbsheet.share_view_status 或 share_get_link_info 核对

**幂等性**：是

> `view_type` 须与 `get_schema` 中该视图类型一致，避免传错导致失败；不确定时先用 get_schema 确认

#### 调用示例

开启分享：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B",
  "body": {
    "permission": "read",
    "share_to": "anyone",
    "view_type": "G0"
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID（必填；缺失时提示用户缺少 `多维表格文件 ID`）
- `sheet_id` (integer, 必填): 数据表 ID（必填；缺失时提示用户缺少 `数据表 ID`）
- `view_id` (string, 必填): 视图 ID（必填；缺失时提示用户缺少 `视图 ID`）
- `body` (object, 必填): JSON 请求体；**须同时包含** `permission`、`share_to`、`view_type` 三个键，缺一则视为参数不齐
  - `permission` (string, **必填**): `edit` 或 `read`；缺失时提示缺少 `分享权限（可编辑/可查看）`
  - `share_to` (string, **必填**): `anyone`、`company` 或 `assigned`；缺失时提示缺少 `分享范围（所有人/企业内成员/指定人）`
  - `view_type` (string, **必填**): `G0`、`F0` 或 `D0`；缺失时提示缺少 `视图类型（表格/表单/仪表盘）`

**请求体（`body`）字段表**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `permission` | string | 是 | `edit`（可编辑）、`read`（可查看） |
| `share_to` | string | 是 | `anyone`（所有人）、`company`（企业内成员）、`assigned`（指定人） |
| `view_type` | string | 是 | `G0`（表格）、`F0`（表单）、`D0`（仪表盘） |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 含 share_id 等，以实际返回为准 |


---

## 2. dbsheet.share_view_status

#### 功能说明


**必填 query**：无（路径参数即全部）。

**前置条件**：有读取该视图分享状态的权限。



#### 调用示例

查询状态：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B"
}
```


#### 参数说明

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

#### 返回值说明

```json
{
  "result": "ok",
  "detail": { "is_enable": false, "share_id": "" }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 含 is_enable、share_id 等 |


---

## 3. dbsheet.share_get_link_info

#### 功能说明


**必填 query**：无。

**前置条件**：分享已开启且 `share_id` 有效（可由 view_status / open_view 返回）。



#### 调用示例

查询链接：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B",
  "share_id": "share_xxx"
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `view_id` (string, 必填): 视图 ID
- `share_id` (string, 必填): 分享链接 ID

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 链接权限、过期时间等 |


---

## 4. dbsheet.share_close_view

#### 功能说明


**前置条件**：`share_id` 有效且当前用户可关闭该分享。



#### 操作约束

- **前置检查**：share_view_status 确认当前分享状态
- **用户确认**：关闭后外部访问方将无法通过该链接访问

**幂等性**：否 — 关闭后再次调用无效，先确认当前分享状态

#### 调用示例

关闭分享：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B",
  "share_id": "share_xxx",
  "body": {}
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `view_id` (string, 必填): 视图 ID
- `share_id` (string, 必填): 分享链接 ID
- `body` (object, 可选): 若接口要求关闭原因等字段则传入；否则可 {}

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---

## 5. dbsheet.share_get_repeatable

#### 功能说明


**必填 query**：无。

**前置条件**：`view_id` 为**表单（Form）**视图且已生成分享链接；非表单视图勿调用。



#### 调用示例

查询可重复提交：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "FormViewId",
  "share_id": "share_xxx"
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `view_id` (string, 必填): 表单视图 ID
- `share_id` (string, 必填): 分享链接 ID

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 是否允许重复提交等 |


---

## 6. dbsheet.share_set_repeatable

#### 功能说明


**前置条件**：表单视图 + 有效 `share_id`；与 get_repeatable 相同。



#### 操作约束

- **提示**：与官方 set-repeatable 文档保持一致

**幂等性**：是

#### 调用示例

禁止重复提交：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "FormViewId",
  "share_id": "share_xxx",
  "body": {
    "repeatable": false
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `view_id` (string, 必填): 表单视图 ID
- `share_id` (string, 必填): 分享链接 ID
- `body` (object, 必填): 须含 repeatable（boolean），可与顶层同名字段合并

**body 根级必填**

| 字段 | 类型 | 说明 |
|------|------|------|
| `repeatable` | boolean | 是否允许访客重复提交表单 |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---

## 7. dbsheet.share_update_permission

#### 功能说明


**前置条件**：分享已开启且具备修改该链接权限的能力。



#### 操作约束

- **后置验证**：可用 dbsheet.share_get_link_info 核对

**幂等性**：是

#### 调用示例

更新权限：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B",
  "share_id": "share_xxx",
  "body": {
    "permission": "read",
    "share_to": "anyone"
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 数据表 ID
- `view_id` (string, 必填): 视图 ID
- `share_id` (string, 必填): 分享链接 ID
- `body` (object, 必填): JSON 请求体，包含 permission、share_to

**请求体（`body`）字段**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `permission` | string | 是 | 分享权限。可选值：`edit`（可编辑）、`read`（可查看） |
| `share_to` | string | 是 | 分享范围。可选值：`anyone`（所有人）、`company`（企业内成员）、`assigned`（指定人） |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---



path: references/dbsheet/view.md
content: # 视图管理

## 1. dbsheet.create_view

#### 功能说明

在指定数据表中创建新视图，支持表格、看板、画册、表单、甘特、日历等视图类型。



#### 操作约束

- **后置验证**：get_schema 确认视图已创建

**幂等性**：否 — 重复调用会创建多个视图，先确认是否已成功

#### 调用示例

创建看板视图：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "name": "看板视图",
  "type": "Kanban",
  "group_field": "状态"
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 目标数据表 ID
- `name` (string, 必填): 视图名称
- `type` (string, 必填): 视图类型（见附录：视图类型）
- `prefer_id` (boolean, 可选): 是否使用字段 ID 作为 key
- `group_field` (string, 可选): 分组字段名称

#### 返回值说明

```json
{
  "detail": {
    "view": { "id": "I", "name": "看板视图", "type": "Kanban" }
  },
  "result": "ok"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.view.id` | string | 新建视图 ID |
| `detail.view.name` | string | 视图名称 |
| `detail.view.type` | string | 视图类型 |
| `result` | string | ok 表示成功 |


---

## 2. dbsheet.update_view

#### 功能说明

更新视图的名称、字段顺序、字段显隐状态及列宽等展示配置。


#### 操作约束

- **前置检查**：get_schema 确认目标视图存在

**幂等性**：是

#### 调用示例

重命名并调整视图配置：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "I",
  "name": "重命名视图",
  "order_fields": [
    "B",
    "D",
    "F",
    "E",
    "C"
  ],
  "fields_attribute": [
    {
      "field": "D",
      "hidden": true
    }
  ],
  "widths": [
    {
      "field": "B",
      "width": 1600
    }
  ]
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 目标数据表 ID
- `view_id` (string, 必填): 视图 ID
- `name` (string, 可选): 新视图名称
- `prefer_id` (boolean, 可选): 是否使用字段 ID 作为 key
- `order_fields` (array, 可选): 字段排列顺序，字段 ID 数组
- `fields_attribute` (array, 可选): 字段显隐属性，每项包含 `field` 和 `hidden`
- `height` (integer, 可选): 行高（Twip 单位）
- `widths` (array, 可选): 字段列宽配置，每项包含 `field` 和 `width`

#### 返回值说明

```json
{
  "detail": {
    "view": { "id": "I", "name": "重命名视图", "type": "Grid" }
  },
  "result": "ok"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.view.id` | string | 视图 ID |
| `detail.view.name` | string | 视图名称 |
| `detail.view.type` | string | 视图类型 |
| `result` | string | ok 表示成功 |


---

## 3. dbsheet.delete_view

#### 功能说明

删除指定数据表中的视图。


#### 操作约束

- **前置检查**：get_schema 核对拟删视图的名称和类型
- **用户确认**：删除视图不可恢复，必须向用户确认视图名称和 ID

**幂等性**：是

#### 调用示例

删除视图：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "I"
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `sheet_id` (integer, 必填): 目标数据表 ID
- `view_id` (string, 必填): 视图 ID

#### 返回值说明

```json
{
  "detail": {
    "view": { "id": "I" }
  },
  "result": "ok"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail.view.id` | string | 已删除的视图 ID |
| `result` | string | ok 表示成功 |


---

## 4. dbsheet.views_list

#### 功能说明


**必填 query**：无。



#### 调用示例

列出视图：

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


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | views 列表 |


---

## 5. dbsheet.views_get

#### 功能说明


**必填 query**：无。



#### 调用示例

获取视图：

```json
{
  "file_id": "string",
  "sheet_id": 1,
  "view_id": "B"
}
```


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | view 对象 |


---



path: references/dbsheet/webhook.md
content: # Webhook 与开放协作

## 1. dbsheet.list_webhooks

#### 功能说明


**必填 query**：无。

**前置条件**：应用具备订阅查询权限。



#### 调用示例

列出订阅：

```json
{
  "file_id": "string"
}
```


#### 参数说明

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

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | hooks 列表或映射，以实际 data 为准 |


---

## 2. dbsheet.create_webhook

#### 功能说明

**前置条件**：应用具备多维表格 Webhook 能力；`callback_url` 可公网访问且可接收 JSON 格式 POST 请求。



#### 操作约束

- **后置验证**：list_webhooks 确认 webhook 已创建
- **提示**：勿向不可信回调地址泄露事件数据；删除订阅用 dbsheet.delete_webhook

**幂等性**：否 — 重复调用会创建多个订阅，先确认是否已成功

#### 调用示例

创建订阅（新增记录）：

```json
{
  "file_id": "string",
  "body": {
    "command": "create_record",
    "data": {
      "sheet_id": 1234567890
    },
    "callback_url": "https://example.com/dbsheet/webhook"
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `body` (object, 必填): JSON 请求体，包含 command、data、callback_url

**请求体（`body`）字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| `command` | string | Hook 订阅命令。可选值：`create_record`（订阅添加记录）、`update_sheet`（订阅修改记录）、`remove_record`（订阅删除记录）、`update_records_parent`（订阅父子记录变动）、`create_field`（订阅新增字段）、`update_field`（订阅更新字段）、`remove_field`（订阅删除字段） |
| `data` | object | Hook 订阅规则，根据 `command` 选择具体规则对象 |
| `callback_url` | string | 回调 URL，用于接收 hook 触发通知；该接口应接受 JSON 格式 POST 请求 |

**Hook 订阅规则详情（`data`）**

- 当 `command = create_record`（数据表内添加记录，HookRuleCreateRecord）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |

- 当 `command = update_sheet`（数据表内修改记录，HookRuleUpdateSheet）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |
  | `include_formula_result_change` | bool | 是否监听公式结果变化，默认 `false` |
  | `skip_after_match_create_and_fill` | bool | 是否在监听新建或修改记录时避免重复触发，默认 `false`（依然触发） |

- 当 `command = remove_record`（数据表内删除记录，HookRuleRemoveRecord）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |
  | `record_ids` | array[string] | 被监听删除的记录 id；监听所有记录删除时传空数组 |

- 当 `command = update_records_parent`（数据表内父子关系变动，HookRuleRecordParent）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |
  | `record_ids` | array[string] | 被监听父子关系变动的记录 id；监听所有记录时传空数组 |

- 当 `command = create_field`（数据表内添加字段，HookRuleCreateField）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |

- 当 `command = update_field`（数据表内修改字段，HookRuleUpdateField）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |
  | `field_id` | string | 被监听修改的字段 id |

- 当 `command = remove_field`（数据表内删除字段，HookRuleRemoveField）

  | 字段 | 类型 | 说明 |
  |------|------|------|
  | `sheet_id` | int64 | 数据表 id |
  | `field_id` | string | 被监听删除的字段 id |


#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 含 hook_id 等，以实际返回为准 |


---

## 3. dbsheet.delete_webhook

#### 功能说明


**前置条件**：`hook_id` 须为当前文档下有效订阅（可先 `dbsheet.list_webhooks`）。



#### 操作约束

- **用户确认**：取消后需重新创建才能接收事件

**幂等性**：否 — 删除失败勿盲目重试，先 list_webhooks 确认 hook_id

#### 调用示例

取消订阅：

```json
{
  "file_id": "string",
  "hook_id": "hook_xxx"
}
```


#### 参数说明

- `file_id` (string, 必填): 多维表格文件 ID
- `hook_id` (string, 必填): Hook 订阅 ID
- `body` (object, 可选): 若接口要求附加字段则置于 body；否则可省略或传 {}

#### 返回值说明

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

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `detail` | object | 接口返回详情 |


---



path: references/dbsheet.md
content: # 多维表格（dbt）工具完整参考文档

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

---

## 一、数据表管理

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

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.get_schema`](dbsheet/data_table.md) | 获取文档结构（表/字段/视图） | `file_id` |
| [`dbsheet.create_sheet`](dbsheet/data_table.md) | 创建数据表 | `file_id`, `name` |
| [`dbsheet.update_sheet`](dbsheet/data_table.md) | 修改数据表名称 | `file_id`, `sheet_id` |
| [`dbsheet.delete_sheet`](dbsheet/data_table.md) | 删除数据表 | `file_id`, `sheet_id` |
| [`dbsheet.sheet_batch_create`](dbsheet/data_table.md) | 批量创建工作表 | `file_id`, `body` |
| [`dbsheet.sheet_batch_delete`](dbsheet/data_table.md) | 批量删除工作表 | `file_id`, `body` |

## 二、视图管理

> 视图的增删改查与列表

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.create_view`](dbsheet/view.md) | 创建视图 | `file_id`, `sheet_id`, `name`, `type` |
| [`dbsheet.update_view`](dbsheet/view.md) | 更新视图配置 | `file_id`, `sheet_id`, `view_id` |
| [`dbsheet.delete_view`](dbsheet/view.md) | 删除视图 | `file_id`, `sheet_id`, `view_id` |
| [`dbsheet.views_list`](dbsheet/view.md) | 列出视图 | `file_id`, `sheet_id` |
| [`dbsheet.views_get`](dbsheet/view.md) | 获取单个视图 | `file_id`, `sheet_id`, `view_id` |

## 三、字段管理

> 字段的增删改

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.create_fields`](dbsheet/field.md) | 批量创建字段 | `file_id`, `sheet_id`, `fields` |
| [`dbsheet.update_fields`](dbsheet/field.md) | 批量更新字段 | `file_id`, `sheet_id`, `fields` |
| [`dbsheet.delete_fields`](dbsheet/field.md) | 批量删除字段 | `file_id`, `sheet_id`, `fields` |

## 四、记录操作

> 记录的增删改查

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.create_records`](dbsheet/record.md) | 批量创建记录 | `file_id`, `sheet_id`, `records` |
| [`dbsheet.update_records`](dbsheet/record.md) | 批量更新记录 | `file_id`, `sheet_id`, `records` |
| [`dbsheet.list_records`](dbsheet/record.md) | 分页遍历记录（支持筛选） | `file_id`, `sheet_id` |
| [`dbsheet.get_record`](dbsheet/record.md) | 获取单条记录 | `file_id`, `sheet_id`, `record_id` |
| [`dbsheet.delete_records`](dbsheet/record.md) | 批量删除记录 | `file_id`, `sheet_id`, `records` |
| [`dbsheet.records_list`](dbsheet/record.md) | 列举记录 | `file_id`, `sheet_id`, `fields` |
| [`dbsheet.records_search`](dbsheet/record.md) | 检索多条记录 | `file_id`, `sheet_id`, `records` |

## 五、表单视图

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

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.form_list_fields`](dbsheet/form.md) | 列出表单问题 | `file_id`, `sheet_id`, `view_id` |
| [`dbsheet.form_update_field`](dbsheet/form.md) | 更新表单问题 | `file_id`, `sheet_id`, `view_id`, `field_id`, `body` |
| [`dbsheet.form_get_meta`](dbsheet/form.md) | 获取表单元数据 | `file_id`, `sheet_id`, `view_id` |
| [`dbsheet.form_update_meta`](dbsheet/form.md) | 更新表单元数据 | `file_id`, `sheet_id`, `view_id`, `body` |

## 六、父子记录

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

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.parent_disable`](dbsheet/parent_child.md) | 禁用父子关系（仅前端） | `file_id`, `sheet_id` |
| [`dbsheet.parent_enable`](dbsheet/parent_child.md) | 启用父子关系（仅前端） | `file_id`, `sheet_id` |
| [`dbsheet.parent_status`](dbsheet/parent_child.md) | 查询父子关系是否禁用 | `file_id`, `sheet_id` |
| [`dbsheet.parent_bind_children`](dbsheet/parent_child.md) | 绑定父子记录 | `file_id`, `sheet_id`, `parent_id`, `body` |
| [`dbsheet.parent_list_children`](dbsheet/parent_child.md) | 查询子记录列表 | `file_id`, `sheet_id`, `parent_id` |
| [`dbsheet.parent_unbind_children`](dbsheet/parent_child.md) | 解绑父子记录 | `file_id`, `sheet_id`, `parent_id`, `body` |

## 七、分享视图

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

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.share_open_view`](dbsheet/share.md) | 打开分享视图 | `file_id`, `sheet_id`, `view_id`, `body` |
| [`dbsheet.share_view_status`](dbsheet/share.md) | 查询视图是否已开启分享 | `file_id`, `sheet_id`, `view_id` |
| [`dbsheet.share_get_link_info`](dbsheet/share.md) | 查询分享链接信息 | `file_id`, `sheet_id`, `view_id`, `share_id` |
| [`dbsheet.share_close_view`](dbsheet/share.md) | 关闭分享视图 | `file_id`, `sheet_id`, `view_id`, `share_id` |
| [`dbsheet.share_get_repeatable`](dbsheet/share.md) | 查询表单是否可重复提交 | `file_id`, `sheet_id`, `view_id`, `share_id` |
| [`dbsheet.share_set_repeatable`](dbsheet/share.md) | 设置表单是否可重复提交 | `file_id`, `sheet_id`, `view_id`, `share_id`, `body` |
| [`dbsheet.share_update_permission`](dbsheet/share.md) | 修改分享权限 | `file_id`, `sheet_id`, `view_id`, `share_id`, `body` |

## 八、高级权限

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

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.permission_list_roles`](dbsheet/permission.md) | 列举自定义角色 | `file_id` |
| [`dbsheet.permission_query_task`](dbsheet/permission.md) | 获取异步任务结果 | `file_id`, `task_id`, `task_type` |
| [`dbsheet.permission_create_roles_async`](dbsheet/permission.md) | 新增自定义角色（异步） | `file_id`, `body` |
| [`dbsheet.permission_update_roles_async`](dbsheet/permission.md) | 更新自定义角色（异步） | `file_id`, `body` |
| [`dbsheet.permission_delete_roles_async`](dbsheet/permission.md) | 删除自定义角色（异步） | `file_id`, `body` |
| [`dbsheet.permission_list_subjects`](dbsheet/permission.md) | 列举成员（内容权限） | `file_id`, `cloud_permission_id`, `permission_type` |

## 九、仪表盘

> 仪表盘的列表与复制

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.dashboard_copy`](dbsheet/dashboard.md) | 复制仪表盘 | `file_id`, `dashboard_id`, `body` |
| [`dbsheet.dashboard_list`](dbsheet/dashboard.md) | 列出仪表盘 | `file_id` |

## 十、Webhook 与开放协作

> Webhook 的创建、列表、删除

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`dbsheet.list_webhooks`](dbsheet/webhook.md) | 查询全部 Hook 订阅 | `file_id` |
| [`dbsheet.create_webhook`](dbsheet/webhook.md) | 创建 Hook 订阅 | `file_id`, `body` |
| [`dbsheet.delete_webhook`](dbsheet/webhook.md) | 取消 Hook 订阅 | `file_id`, `hook_id` |

## 工具组合速查

| 用户需求 | 推荐工具组合 |
|----------|-------------|
| 多维表格读结构/数据 | `dbsheet.get_schema` → `dbsheet.list_records` / `dbsheet.get_record` |
| 多维表格增删改 | `dbsheet.get_schema` → `dbsheet.create_records` / `dbsheet.update_records` / `dbsheet.delete_records`|

---

## 获取记录工具使用指南

| 场景 | 优先工具 | 备用工具 | 说明 |
|------|----------|----------|------|
| 列举数据表所有 / 分页记录 | `dbsheet.records_list` | `dbsheet.list_records` | `records_list` 基于游标分页；若返回错误，改用 `list_records`（页码分页） |
| 查询数据表中某一条记录 | `dbsheet.get_record` | `dbsheet.records_search` | `get_record` 直接按记录 id GET 查询；返回错误时可改用 `records_search` |
| 批量获取指定多条记录 | `dbsheet.records_search` | — | 传入记录 id 列表一次取回多条，无需逐条查询 |

---

## 错误速查表

| 错误特征 | 原因 | 处理方式 |
|----------|------|----------|
| 多维表格读不到结构化数据 | 误用 `read_file_content` 作主读 | 改用 `dbsheet.get_schema`、`dbsheet.list_records` 等，见 `references/dbsheet.md` |

---

## 附录

### 字段类型

| 类型 | 说明 |
|------|------|
| `SingleLineText` | 单行文本 |
| `MultiLineText` | 多行文本 |
| `Number` | 数值 |
| `Currency` | 货币 |
| `Percentage` | 百分比 |
| `Date` | 日期 |
| `Time` | 时间 |
| `Checkbox` | 复选框 |
| `SingleSelect` | 单选项 |
| `MultipleSelect` | 多选项 |
| `Rating` | 等级 |
| `Complete` | 进度条 |
| `Phone` | 电话 |
| `Email` | 电子邮箱 |
| `Url` | 超链接 |
| `Contact` | 联系人 |
| `Attachment` | 附件 |
| `Link` | 关联 |
| `Note` | 富文本 |
| `Address` | 地址 |
| `AutoNumber` | 编号（自动填充） |
| `CreatedBy` | 创建者（自动填充） |
| `CreatedTime` | 创建时间（自动填充） |
| `LastModifiedBy` | 最后修改者（自动填充） |
| `LastModifiedTime` | 最后修改时间（自动填充） |
| `Formula` | 公式（自动计算） |
| `Lookup` | 引用（自动计算） |

### 视图类型

| 类型 | 说明 |
|------|------|
| `Grid` | 表格视图 |
| `Kanban` | 看板视图 |
| `Gallery` | 画册视图 |
| `Form` | 表单视图 |
| `Gantt` | 甘特视图 |
| `Calendar` | 日历视图 |

### 筛选规则（filter op）

| 操作符 | 适用字段类型 | 说明 |
|--------|-------------|------|
| `Equals` | 通用 | 等于 |
| `NotEqu` | 通用 | 不等于 |
| `Greater` | 数值、日期 | 大于 |
| `GreaterEqu` | 数值、日期 | 大于等于 |
| `Less` | 数值、日期 | 小于 |
| `LessEqu` | 数值、日期 | 小于等于 |
| `BeginWith` | 文本 | 开头是 |
| `EndWith` | 文本 | 结尾是 |
| `Contains` | 文本 | 包含 |
| `NotContains` | 文本 | 不包含 |
| `Intersected` | 单选、多选 | 选项包含指定值 |
| `Empty` | 通用 | 为空（`values` 可省略） |
| `NotEmpty` | 通用 | 不为空（`values` 可省略） |

### 错误响应

| 情况 | 响应示例 |
|------|---------|
| 命令不支持 | `{"msg":"core not support","result":"unSupport"}` |
| 内核错误 | `{"errno":-1880935404,"msg":"Invalid request","result":"ExecuteFailed"}` |
| HTTP 状态非 200 | 请求本身失败，检查 `file_id` 是否正确及鉴权信息 |


path: references/drive/create_and_upload.md
content: # 一、文档创建与上传

## 1. create_file

#### 功能说明

在云盘下新建文件或文件夹。通过 `file_type` 区分：`file` 创建文件，`folder` 创建文件夹，`shortcut` 创建快捷方式。支持格式：doc, docx, form, xls, otl, ppt, dbt, xlsx, ksheet, pptx。**PDF 不使用本工具创建，请改用 `upload_file` 直接创建并写入。**

**`drive_id` / `parent_id`**（非必填）：
- **用户未说明保存到哪个文件夹**：两参数可省略。
- **用户已说明目标文件夹且已查到**对应的 `drive_id` 与 `parent_id`：必须传入这两项。查不到时先 `search_files` 或请用户说明，勿编造 ID。
- 如何查询 ID 见 `file-locating-guide`。



#### 操作约束

- **前置检查**：search_files 查重，避免创建同名文件
- **后置验证**：get_file_info 确认文件已创建
- **提示**：文件名必须带后缀，否则创建失败
- **提示**：PDF 不支持 create_file，需使用 upload_file

**幂等性**：否 — 重试前 search_files 检查是否已创建

#### 调用示例

创建智能文档：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "file_type": "file",
  "name": "Q1区域销售周报.otl",
  "on_name_conflict": "rename"
}
```

创建文件夹：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "file_type": "folder",
  "name": "2024年合同文件",
  "on_name_conflict": "rename"
}
```

仅必填字段（未指定目录时可不传 drive_id、parent_id）：

```json
{
  "file_type": "file",
  "name": "快速草稿.otl",
  "on_name_conflict": "rename"
}
```


#### 参数说明

- `drive_id` (string, 可选): 目标云盘 ID。与 `parent_id` 一起指定保存位置；规则见上文「`drive_id` / `parent_id`」。
- `parent_id` (string, 可选): 父文件夹 ID；保存到该盘根目录时传 `"0"`。与 `drive_id` 成对；规则见上文「`drive_id` / `parent_id`」。
- `file_type` (string, 必填): 文件类型。可选值：`file` / `folder` / `shortcut`
- `name` (string, 必填): 文件名。创建文件时须带上后缀，例: `doc.docx`(普通文件), `abc.docx.link`(快捷方式)；创建文件夹时不需要后缀。支持格式：doc, docx, form, xls, otl, ppt, dbt, xlsx, ksheet, pptx。若为 `.pdf`，请改用 `upload_file`
- `on_name_conflict` (string, 可选): 文件名冲突处理方式，该接口只识别 rename 和 fail。可选值：`fail` / `rename` / `overwrite` / `replace`；默认值：`rename`
- `parent_path` (array[string], 可选): 父文件夹路径分段（每段为文件夹名，非 ID）；缺级时系统可自动创建。与 `drive_id`/`parent_id` 的用法见上文。
- `file_id` (string, 可选): 条件必填：file_type=shortcut 时必填。快捷方式的源文件 ID

#### 返回值说明

```json
{
  "data": {
    "created_by": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "user"
    },
    "ctime": 0,
    "drive_id": "string",
    "ext_attrs": [
      { "name": "string", "value": "string" }
    ],
    "id": "string",
    "link_id": "string",
    "link_url": "string",
    "modified_by": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "user"
    },
    "mtime": 0,
    "name": "string",
    "parent_id": "string",
    "shared": true,
    "size": 0,
    "type": "folder",
    "version": 0
  },
  "code": 0,
  "msg": "string"
}

```

> `data` 字段结构见通用文件信息结构（附录 A）


---

## 2. scrape_url

#### 功能说明

网页剪藏：抓取网页内容并自动保存为智能文档。**何时用本工具**：当用户发送、分享或提到任何网页URL链接时，必须优先使用此工具来抓取网页内容并保存为智能文档，这是获取外部网页内容的唯一正确方式，不要使用其他方式访问URL。**何时不要用**：URL链接属于金山文档生态（如 `kdocs.cn`、`365.kdocs.cn`、`wps.cn` 文档域、分享页 `/l/`、`/view/l/`、`/folder/` 等）时，属于「已有云文档」场景。

#### 调用流程
1. 调用 `scrape_url` 传入网页 URL 获取 `job_id`
2. 立即调用 `scrape_progress` 传入 `job_id` 查询进度（每隔 2 秒轮询一次）
3. 当 `status=1` 时任务完成，服务端已自动创建智能文档



**幂等性**：否 — 重试前查 scrape_progress 确认上次状态

> 返回 job_id 后需立即调用 scrape_progress 轮询
> 每隔2秒轮询一次，status=1 时完成

#### 调用示例

剪藏网页：

```json
{
  "url": "https://example.com/article"
}
```


#### 参数说明

- `url` (string, 必填): 要剪藏的网页URL地址，支持http和https协议

#### 返回值说明

```json
{
  "job_id": "13883829803456643124541",
  "parent_id": 498552876371,
  "group_id": 1231238091
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `job_id` | string | 异步任务ID |
| `parent_id` | number | 父目录ID |
| `group_id` | number | 组ID |


---

## 3. scrape_progress

#### 功能说明

查询网页剪藏任务进度并自动创建智能文档，与 `scrape_url` 配合使用。



#### 操作约束

- **前置检查**：先调用 `scrape_url` 获取 `job_id`，本接口才可用

**幂等性**：是

> status=1 时停止轮询，获取 scrape_file_id
> status=-1 时停止轮询，任务失败
> 其他状态继续轮询（建议间隔 2-3 秒，最多轮询 30 次）

#### 调用示例

查询剪藏进度：

```json
{
  "job_id": "task_1234567890"
}
```


#### 参数说明

- `job_id` (string, 必填): `scrape_url` 返回的异步任务 ID

#### 返回值说明

```json
{
    "code": 0,
    "data": {
        "scrape_file_id": 501370651020,
        "status": 1,
        "file_name": "［麦理浩径二段精华段+大湾海滩］周四：3月19日 麦径二段12公里徒步，超适合新手小白！.otl",
        "parent_id": 498552876371,
        "group_id": 1231238091,
        "cache": 0,
        "core_err": null
    },
    "msg": "成功"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.scrape_file_id` | number | 剪藏专用文档标识 |
| `data.status` | number | 任务状态: 1=完成, -1=失败, 其他=进行中 |
| `data.file_name` | string | 文件名 |
| `data.parent_id` | number | 父目录ID |
| `data.group_id` | number | 组ID |
| `data.cache` | number | 缓存标识 |
| `data.core_err` | string | 内核错误信息 |


---

## 4. upload_file

#### 功能说明

**全量上传写入文件**：服务端完成三步上传，可用于：

- **更新已有文件**：传 `file_id`，覆盖已有 `docx` / `pdf`
- **新建并上传本地文件**：不传 `file_id`，改传 `name`（必须带文件后缀）

- **支持类型**：更新模式仅支持目标文件为 **docx**、**pdf**；新建模式支持文件名为 **doc**、**docx**、**xls**、**xlsx**、**ppt**、**pptx**、**pdf**
- **源为 Markdown 时**：务必传 `content_format=markdown`；仅支持转为 **docx**、**pdf** 后上传

**`drive_id` / `parent_id`**（非必填）：

- **新建、未指定位置**：两参数可省略。
- **新建、用户已说明目标文件夹且已查到** `drive_id` 与 `parent_id`：必须传入。已能查到 ID 却省略属错误。
- **更新已有文件**：须与目标文件所在云盘、父文件夹一致；建议先 `get_file_info(file_id)` 再传参。



#### 操作约束

- **前置检查**（更新已有文件时）：先 read_file_content 读取现有内容，确认覆盖范围
- **后置验证**：写入后确认结果：通过接口返回的 size 字段判断，小文件用 read_file_content 确认写入结果；大文件优先关键段抽样回读或元信息校验（大小/更新时间/版本）
- **提示**：更新模式支持 docx/pdf；新建模式支持 doc/docx/xls/xlsx/ppt/pptx/pdf
- **提示**：Markdown 源内容务必传 content_format=markdown

**幂等性**：是

#### 调用示例

同类型覆盖（docx → docx）：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "file_id": [REDACTED_SECRET],
  "content_base64": "JVBERi0xLjQK..."
}
```

新建 PDF 并写入（二进制 PDF Base64）：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "name": "2024年度报告.pdf",
  "content_base64": "JVBERi0xLjQK..."
}
```

Markdown 覆盖（先转为 docx/pdf 再上传）：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "file_id": [REDACTED_SECRET],
  "content_base64": "<Markdown 内容的 Base64>",
  "content_format": "markdown"
}
```

新建文件（显式 drive_id、parent_id）：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "name": "会议纪要.docx",
  "content_base64": "UEsDBBQAAAAI...",
  "content_format": "markdown"
}
```

新建文件（仅 name + 内容；未指定目录时可不传 drive_id、parent_id）：

```json
{
  "name": "会议纪要.docx",
  "content_base64": "UEsDBBQAAAAI...",
  "content_format": "markdown"
}
```


#### 参数说明

- `drive_id` (string, 可选): 目标云盘 ID。新建：规则见上文「`drive_id` / `parent_id`」。更新：与目标文件所在盘一致。
- `parent_id` (string, 可选): 父文件夹 ID；保存到该盘根目录时传 `"0"`。新建：规则见上文。更新：与目标文件父目录一致。
- `file_id` (string, 二选一必填: `file_id` / `name`): 条件必填：更新模式必填。要覆盖的文件 ID（仅支持 docx/pdf 文件）
- `name` (string, 二选一必填: `file_id` / `name`): 条件必填：新建模式必填。本地文件名，必须带后缀，如 `.docx` / `.xlsx` / `.pptx` / `.pdf`；仅在不传 `file_id` 时使用
- `content_base64` (string, 必填): 源文件内容，Base64 编码。若为 Markdown 文本需同时传 content_format=markdown，确保 UTF-8 格式、base64 编码
- `content_format` (string, 可选): 源内容格式。与目标文件同类型，或 `markdown`（会先转为目标格式再上传；仅支持目标为 docx / pdf）。可选值：`doc` / `docx` / `xls` / `xlsx` / `pdf` / `markdown`
- `file_sum` (string, 可选): 文件哈希值，不传则服务端按内容计算
- `file_type` (string, 可选): 哈希类型。可选值：`sha256` / `md5` / `sha1`
- `parent_path` (array[string], 可选): 父文件夹路径分段（文件夹名，非 ID）。新建时按文件夹名指定父路径；与 `drive_id`/`parent_id` 的用法见上文。

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": [REDACTED_SECRET],
    "name": "2024年度报告.docx",
    "link_url": "https://www.kdocs.cn/l/dpjw3VgQkZrm",
    "link_id": "dpjw3VgQkZrm",
    "size": 57081,
    "parent_id": "...",
    "drive_id": "...",
    "type": "file",
    "version": 1,
    "ctime": 1773563524,
    "mtime": 1773563524,
    "created_by": { ... },
    "modified_by": { ... },
    "shared": false,
    "hash": { "sum": "...", "type": "sha1" }
  }
}

```

> `data` 字段结构见通用文件信息结构（附录 A）


---

## 5. upload_attachment

#### 功能说明

向已有文档上传附件，支持传远程 URL 或本地二进制内容（Base64）。
返回 `object_id`，可用于文档内附件或图片引用。

支持两种上传方式：
- 远程 URL：传 `url`
- 本地二进制：传 `content_base64`



**幂等性**：否 — 重复调用会上传多个副本，先确认是否已成功

> url 与 content_base64 必须二选一

#### 调用示例

通过 URL 上传附件：

```json
{
  "file_id": "string",
  "filename": "头像.png",
  "url": "https://img.qwps.cn/example.png",
  "source_type": "url",
  "source": "processon"
}
```

通过 Base64 上传本地附件：

```json
{
  "file_id": "string",
  "filename": "附件.pdf",
  "content_base64": "JVBERi0xLjQK...",
  "content_type": "application/pdf"
}
```


#### 参数说明

- `file_id` (string, 必填): 已有文档文件 ID
- `filename` (string, 必填): 附件名
- `url` (string, 二选一必填: `url` / `content_base64`): 条件必填。远程附件 URL，与 content_base64 二选一
- `content_base64` (string, 二选一必填: `url` / `content_base64`): 条件必填。本地附件内容的 Base64 编码，与 url 二选一
- `content_type` (string, 可选): 可选。附件 MIME 类型；content_base64 模式下不传则默认 application/octet-stream
- `source_type` (string, 可选): 可选。上传内容类型
- `source` (string, 可选): 可选。来源标记，如 processon

#### 返回值说明

```json
{
  "result": "ok",
  "object_id": "1234567890",
  "extra_info": {
    "width": 600,
    "height": 400
  },
  "old_content_type": "image/jpeg",
  "new_content_type": "image/jpeg"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | string | ok 表示成功 |
| `object_id` | string | 附件上传后的对象 ID |
| `extra_info.width` | integer | 图片宽度（像素，仅图片类型返回） |
| `extra_info.height` | integer | 图片高度（像素，仅图片类型返回） |
| `old_content_type` | string | 原始内容类型 |
| `new_content_type` | string | 转换后内容类型 |


---



path: references/drive/label.md
content: # 六、标签

## 1. list_labels

#### 功能说明

分页获取云盘自定义标签列表。可按被分配者类型/ID、标签类型筛选。



#### 调用示例

基础分页：

```json
{
  "page_size": 50
}
```

按被分配者筛选：

```json
{
  "page_size": 50,
  "allotee_type": "user",
  "allotee_id": "238896429"
}
```


#### 参数说明

- `page_size` (integer, 必填): 每页条数；建议 50；范围 0–500（含 0）
- `page_token` (string, 可选): 分页 token，首次不传，后续传上次返回的 `next_page_token`
- `allotee_type` (string, 可选): 被分配者类型。可选值：`user` / `company`
- `allotee_id` (string, 可选): 被分配者 ID，与 `allotee_type` 配合使用
- `label_type` (string, 可选): 标签类型，如 `custom`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": "string",
        "name": "string",
        "label_type": "custom",
        "allotee_type": "user",
        "allotee_id": "string",
        "ctime": 0,
        "mtime": 0,
        "hash": 0,
        "rank": 0
      }
    ],
    "next_page_token": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array | 标签列表 |
| `data.items[].id` | string | 标签 ID |
| `data.items[].name` | string | 标签名称 |
| `data.items[].label_type` | string | 标签类型，如 `custom` |
| `data.items[].allotee_type` | string | 被分配者类型：`user` / `company` |
| `data.items[].allotee_id` | string | 被分配者 ID |
| `data.items[].ctime` | integer | 创建时间（时间戳，秒） |
| `data.items[].mtime` | integer | 修改时间（时间戳，秒） |
| `data.items[].hash` | integer | 标签内容哈希值 |
| `data.items[].rank` | integer | 排序权重 |
| `data.next_page_token` | string | 下一页 token，为空表示已是最后一页 |


---

## 2. create_label

#### 功能说明

创建自定义标签。



**幂等性**：否 — 重复调用可能创建同名标签，先确认是否已成功

#### 调用示例

创建用户标签：

```json
{
  "allotee_type": "user",
  "name": "我的项目"
}
```


#### 参数说明

- `allotee_type` (string, 必填): 归属者类型。可选值：`user` / `group` / `app`
- `name` (string, 必填): 标签名称，最多 240 字符
- `allotee_id` (string, 可选): 归属者 ID
- `label_type` (string, 可选): 标签类型。可选值：`custom` / `system`；默认值：`custom`
- `attr` (string, 可选): 自定义属性，最多 127 字符
- `rank` (number, 可选): 排序值，默认为创建时间戳（纳秒），建议使用默认值

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "label": {
      "id": "string",
      "name": "我的项目",
      "label_type": "custom",
      "allotee_type": "user",
      "allotee_id": "string",
      "ctime": 1710000000,
      "mtime": 1710000000,
      "hash": "string",
      "rank": 0
    }
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.label` | object | 新创建的标签信息 |
| `data.label.id` | string | 新标签 ID |
| `data.label.name` | string | 标签名称 |
| `data.label.label_type` | string | 标签类型 |
| `data.label.ctime` | integer | 创建时间（时间戳，秒） |
| `data.label.rank` | integer | 排序权重 |


---

## 3. get_label_meta

#### 功能说明

获取单个标签的详细信息。支持系统标签（固定 ID）和自定义标签。



#### 调用示例

查询系统星标标签：

```json
{
  "label_id": "1"
}
```


#### 参数说明

- `label_id` (string, 必填): 标签 ID。公网系统标签固定 ID：`1`（星标）/ `2`（待办）/ `3`（未确认协作）/ `4`（同步文件夹）/ `5`（常用）/ `6`（快速访问）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "string",
    "name": "string",
    "label_type": "custom",
    "allotee_type": "user",
    "allotee_id": "string",
    "ctime": 0,
    "mtime": 0,
    "hash": 0,
    "rank": 0
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.id` | string | 标签 ID |
| `data.name` | string | 标签名称 |
| `data.label_type` | string | 标签类型：`system`（系统标签）/ `custom`（自定义标签） |
| `data.allotee_type` | string | 被分配者类型：`user` / `company` |
| `data.allotee_id` | string | 被分配者 ID |
| `data.ctime` | integer | 创建时间（时间戳，秒），系统标签为 0 |
| `data.mtime` | integer | 修改时间（时间戳，秒），系统标签为 0 |
| `data.hash` | integer | 标签内容哈希值 |
| `data.rank` | integer | 排序权重，系统标签为 0 |


---

## 4. get_label_objects

#### 功能说明

获取指定标签下的所有对象。通过 `label_id` 查询该标签下打了标记的文件、云盘等对象列表。



#### 调用示例

自定义标签下的文件：

```json
{
  "label_id": "379727",
  "object_type": "file",
  "page_size": 50
}
```

查询系统标签"星标"下的文件：

```json
{
  "label_id": "1",
  "object_type": "file",
  "page_size": 50
}
```


#### 参数说明

- `label_id` (string, 必填): 标签 ID。公网系统标签固定 ID：`1`（星标）/ `2`（待办）/ `3`（未确认协作）/ `4`（同步文件夹）/ `5`（常用）/ `6`（快速访问）；自定义标签 ID 由 `list_labels` 或 `create_label` 返回
- `object_type` (string, 必填): 标签对象类型。可选值：`file` / `drive` / `history` / `app` / `url`
- `page_size` (integer, 必填): 每页条数；建议 50；范围 0–500（含 0）
- `page_token` (string, 可选): 分页 token，首次不传，后续传上次返回的 `next_page_token`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "object_id": "string",
        "object_type": "file",
        "label_id": "string",
        "ctime": 0
      }
    ],
    "next_page_token": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array | 标签对象列表 |
| `data.items[].object_id` | string | 对象 ID（如文件 ID） |
| `data.items[].object_type` | string | 对象类型：`file` / `drive` 等 |
| `data.items[].label_id` | string | 标签 ID |
| `data.items[].ctime` | integer | 打标时间（时间戳，秒） |
| `data.next_page_token` | string | 下一页 token，为空表示已是最后一页 |


---

## 5. batch_add_label_objects

#### 功能说明

批量对文档对象添加指定标签（打标签）。可一次为多个文件打上同一标签。



**幂等性**：是

#### 调用示例

批量打标签：

```json
{
  "label_id": "379727",
  "objects": [
    {
      "id": "file_id_1",
      "type": "file"
    },
    {
      "id": "file_id_2",
      "type": "file"
    }
  ]
}
```


#### 参数说明

- `label_id` (string, 必填): 标签 ID
- `objects` (array[object], 必填): 要打标签的对象列表
  - `id` (string, 必填): 对象 ID
  - `type` (string, 必填): 对象类型，可选值：`file` / `drive` / `history` / `app` / `url`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---

## 6. batch_remove_label_objects

#### 功能说明

批量移除对象与标签的关联。



**幂等性**：是

#### 调用示例

批量取消标签：

```json
{
  "label_id": "379727",
  "objects": [
    {
      "id": "file_id_1",
      "type": "file"
    }
  ]
}
```


#### 参数说明

- `label_id` (string, 必填): 标签 ID
- `objects` (array[object], 必填): 要取消标签的对象列表
  - `id` (string, 必填): 对象 ID
  - `type` (string, 必填): 对象类型，可选值：`file` / `drive` / `history` / `app` / `url`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---

## 7. batch_update_label_objects

#### 功能说明

批量更新标签下对象的排序或自定义属性。



**幂等性**：是

#### 调用示例

更新对象属性：

```json
{
  "label_id": "379727",
  "objects": [
    {
      "id": "file_id_1",
      "type": "file",
      "attr": "重要"
    }
  ]
}
```


#### 参数说明

- `label_id` (string, 必填): 标签 ID
- `objects` (array[object], 必填): 要更新的对象列表
  - `id` (string, 必填): 对象 ID
  - `type` (string, 必填): 对象类型，可选值：`file` / `drive` / `history` / `app` / `url`
  - `attr` (string, 可选): 扩展属性，最长 127 字符

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---

## 8. batch_update_labels

#### 功能说明

批量修改自定义标签的名称或属性。**注意**：全局系统标签不可修改（星标-`1` / 待办-`2` / 未确认协作-`3` / 同步文件夹-`4` / 常用-`5` / 快速访问-`6`）。



**幂等性**：是

#### 调用示例

批量重命名与清空属性：

```json
{
  "labels": [
    {
      "id": "379727",
      "name": "Q2项目",
      "attr": ""
    },
    {
      "id": "379728",
      "name": "归档"
    }
  ]
}
```


#### 参数说明

- `labels` (array[object], 必填): 要更新的标签列表
  - `id` (string, 必填): 标签 ID
  - `name` (string, 可选): 新名称，最长 240 字符
  - `attr` (string, 可选): 对象自定义属性，最长 127 字符

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---



path: references/drive/organize.md
content: # 三、文件组织

## 1. move_file

#### 功能说明

批量移动文件(夹)。大批量时可能异步，返回非空 `task_ids`。


#### 操作约束

- **前置检查**：确认目标文件夹存在（get_file_info）
- **用户确认**（批量操作（多个 file_ids））：批量移动需向用户确认文件列表和目标位置
- **后置验证**：get_file_info 确认 parent_id 为目标文件夹
- **提示**：`task_ids` 非空时，移动尚未完成，需后续确认

**幂等性**：是

#### 调用示例

移动文件到目标文件夹：

```json
{
  "drive_id": "string",
  "file_ids": [
    "string"
  ],
  "dst_drive_id": "string",
  "dst_parent_id": "string"
}
```


#### 参数说明

- `drive_id` (string, 必填): 驱动盘 ID
- `file_ids` (array[string], 必填): 文件 ID 列表
- `dst_drive_id` (string, 必填): 目标驱动盘 ID
- `dst_parent_id` (string, 必填): 目标文件夹 ID，根目录时为 "0"

#### 返回值说明

```json
{
  "data": {
    "task_ids": []
  },
  "code": 0,
  "message": "成功"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.task_ids` | array[string] | 批量任务 ID 列表；单文件移动时通常为空数组 |


---

## 2. rename_file

#### 功能说明

重命名文件（夹）。

**`drive_id`**（非必填）：

- **有明确的云盘ID** 必传。
- **没有**：不传。



**幂等性**：是

#### 调用示例

重命名文件：

```json
{
  "drive_id": "string",
  "file_id": "string",
  "dst_name": "2024年Q1销售总结.otl"
}
```

file_id：

```json
{
  "file_id": "string",
  "dst_name": "2024年Q1销售总结.otl"
}
```


#### 参数说明

- `drive_id` (string, 可选): 目标云盘 ID。
- `file_id` (string, 必填): 文件（夹）ID
- `dst_name` (string, 必填): 新文件名，须带上后缀。例: `abc.txt`。支持格式：otl, doc, xls, ppt, pptx, wdoc, wxls, wppt, h5, pom, pof, docx, xlsx, ksheet, dbt, pdf

#### 返回值说明

返回通用文件信息结构，详见附录 A。

---

## 3. copy_file

#### 功能说明

复制文件到指定目录（可跨盘）。

**`drive_id`**（非必填）：

- **有明确的 drive_id** 必传。
- **没有**：不传。



**幂等性**：否 — 重复调用会创建多个副本，先确认是否已成功

#### 调用示例

复制到目标目录：

```json
{
  "drive_id": "src_drive_id",
  "file_id": "file_id_1",
  "dst_drive_id": "dst_drive_id",
  "dst_parent_id": "dst_folder_id"
}
```

仅 file_id（不传 drive_id）：

```json
{
  "file_id": "file_id_1",
  "dst_drive_id": "dst_drive_id",
  "dst_parent_id": "dst_folder_id"
}
```


#### 参数说明

- `drive_id` (string, 可选): 源文件所在云盘 ID。规则见上文「`drive_id`」。
- `file_id` (string, 必填): 源文件 ID
- `dst_drive_id` (string, 必填): 目标驱动盘 ID
- `dst_parent_id` (string, 必填): 目标父目录 ID，根目录为 "0"

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "string",
    "name": "string",
    "type": "file",
    "drive_id": "string",
    "parent_id": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.id` | string | 新文件 ID |
| `data.name` | string | 文件名 |
| `data.type` | string | 文件类型 |
| `data.drive_id` | string | 目标驱动盘 ID |
| `data.parent_id` | string | 目标父目录 ID |


---

## 4. check_file_name

#### 功能说明

检查文件名在指定目录下是否已存在。常用于上传、复制、移动等操作前的同名预检查。


#### 调用示例

检查文件名是否占用：

```json
{
  "drive_id": "string",
  "parent_id": "string",
  "name": "Q1销售报告.docx"
}
```


#### 参数说明

- `drive_id` (string, 必填): 驱动盘 ID
- `parent_id` (string, 必填): 父目录 ID，根目录为 "0"
- `name` (string, 必填): 待检查的文件名（含后缀）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "is_exist": true,
    "file_id": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.is_exist` | boolean | 文件名是否已存在 |
| `data.file_id` | string | 若已存在，返回已有文件 ID |


---



path: references/drive/read_and_download.md
content: # 二、文档读取与下载

## 1. list_files

#### 功能说明

获取指定文件夹下的子文件列表，通过 `filter_type` 可筛选仅返回文件夹。



#### 调用示例

列出根目录内容：

```json
{
  "drive_id": "8001234567",
  "parent_id": "0",
  "page_size": 50,
  "order": "desc",
  "order_by": "mtime"
}
```


#### 参数说明

- `drive_id` (string, 必填): 驱动盘 ID
- `parent_id` (string, 必填): 文件夹 ID，根目录时为 "0"
- `page_size` (integer, 必填): 每页条数；建议 50；范围 1–500
- `page_token` (string, 可选): 分页 token，首次请求不传
- `order` (string, 可选): 排序方式。可选值：`desc` / `asc`
- `order_by` (string, 可选): 排序字段。可选值：`ctime` / `mtime` / `dtime` / `fname` / `fsize`
- `filter_exts` (string, 可选): 过滤扩展名，以英文逗号分隔，全部小写
- `filter_type` (string, 可选): 按文件类型筛选。可选值：`file` / `folder` / `shortcut`
- `with_permission` (boolean, 可选): 是否返回文件操作权限
- `with_ext_attrs` (boolean, 可选): 是否返回文件扩展属性

#### 返回值说明

```json
{
  "data": {
    "items": [
      {
        "created_by": {
          "avatar": "string",
          "company_id": "string",
          "id": "string",
          "name": "string",
          "type": "user"
        },
        "ctime": 0,
        "drive_id": "string",
        "ext_attrs": [
          { "name": "string", "value": "string" }
        ],
        "id": "string",
        "link_id": "string",
        "link_url": "string",
        "modified_by": {
          "avatar": "string",
          "company_id": "string",
          "id": "string",
          "name": "string",
          "type": "user"
        },
        "mtime": 0,
        "name": "string",
        "parent_id": "string",
        "shared": true,
        "size": 0,
        "type": "folder",
        "version": 0
      }
    ],
    "next_page_token": "string"
  },
  "code": 0,
  "msg": "string"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array[FileInfo] | 文件列表，结构见附录 A |
| `data.next_page_token` | string | 下一页 token，为空表示已是最后一页 |


---

## 2. download_file

#### 功能说明

获取文件下载信息。

**`drive_id`**（非必填）：

- **有明确的 drive_id** 必传。
- **没有**：不传。



> 不支持在线文档类型的下载，仅支持上传的二进制文件（.docx / .xlsx / .pdf / .pptx 等）。获取在线文档内容的替代方案：.otl → `read_file_content` 或 `otl.block_query`；.ksheet/.xlsx → `sheet.*`；.dbt → `dbsheet.*`

#### 调用示例

获取下载链接：

```json
{
  "drive_id": "string",
  "file_id": "string",
  "with_hash": true
}
```

file_id：

```json
{
  "file_id": "string",
  "with_hash": true
}
```


#### 参数说明

- `drive_id` (string, 可选): 目标云盘 ID。
- `file_id` (string, 必填): 文件 ID
- `with_hash` (boolean, 可选): 是否返回校验值，对应响应里的 hashes
- `internal` (boolean, 可选): 是否返回内网下载地址，默认 false
- `storage_base_domain` (string, 可选): 签发的存储网关地址会根据 base_domain 优先匹配。可选值：`wps.cn` / `kdocs.cn` / `wps365.com`

#### 返回值说明

```json
{
  "data": {
    "hashes": [
      {
        "sum": "string",
        "type": "sha256"
      }
    ],
    "url": "string"
  },
  "code": 0,
  "msg": "string"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.url` | string | 下载地址。公网环境下一级域名为 wps.cn 或 kdocs.cn 时需携带登录凭据 |
| `data.hashes` | array | 文件散列值（仅 `with_hash=true` 时返回），公网可能返回 md5/sha1/sha256 中的一个或多个 |
| `data.hashes[].sum` | string | 哈希结果 |
| `data.hashes[].type` | string | 哈希类型：`sha256` / `md5` / `sha1` / `s2s` |


---

## 3. get_file_info

#### 功能说明

获取文件（夹）信息。通过 `file_id` 获取单个文件或文件夹的详细信息，包含 `drive_id` 等关键字段，可用于获取其他接口所需的 `drive_id`。



#### 调用示例

获取文件信息：

```json
{
  "file_id": "string",
  "with_permission": true,
  "with_drive": true
}
```


#### 参数说明

- `file_id` (string, 必填): 文件（夹）ID
- `with_permission` (boolean, 可选): 是否返回文件操作权限
- `with_ext_attrs` (boolean, 可选): 是否返回文件扩展属性
- `with_drive` (boolean, 可选): 是否返回文件所在 drive 信息

#### 返回值说明

```json
{
  "data": {
    "created_by": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "user"
    },
    "ctime": 0,
    "drive": {
      "allotee_id": "string",
      "allotee_type": "user",
      "company_id": "string",
      "created_by": {
        "avatar": "string",
        "company_id": "string",
        "id": "string",
        "name": "string",
        "type": "user"
      },
      "ctime": 0,
      "description": "string",
      "ext_attrs": [
        { "name": "string", "value": "string" }
      ],
      "id": "string",
      "mtime": 0,
      "name": "string",
      "quota": {
        "deleted": 0,
        "remaining": 0,
        "total": 0,
        "used": 0
      },
      "source": "string",
      "status": "inuse"
    },
    "drive_id": "string",
    "ext_attrs": [
      { "name": "string", "value": "string" }
    ],
    "id": "string",
    "link_id": "string",
    "link_url": "string",
    "modified_by": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "user"
    },
    "mtime": 0,
    "name": "string",
    "parent_id": "string",
    "permission": {
      "comment": true,
      "copy": true,
      "copy_content": true,
      "delete": true,
      "download": true,
      "history": true,
      "list": true,
      "move": true,
      "new_empty": true,
      "perm_ctl": true,
      "preview": true,
      "print": true,
      "rename": true,
      "saveas": true,
      "secret": true,
      "share": true,
      "update": true,
      "upload": true
    },
    "shared": true,
    "size": 0,
    "type": "folder",
    "version": 0
  },
  "code": 0,
  "msg": "string"
}

```

返回通用文件信息结构，详见附录 A。当 `with_drive=true` 时额外返回 `drive` 对象（含盘的 id、name、quota 等信息）。


---

## 4. read_file_content

#### 功能说明

文档内容抽取。支持将文档内容抽取为 markdown、纯文本或 KDC 结构化格式。

**调用方式**：首次调用传入 `drive_id` 及 `file_id` / `link_id`（二选一），**不传 `task_id`**：
- 若返回 `task_status=success`：内容已就绪，直接使用，**无需再次轮询**。
- 若返回 `task_status=running`：使用返回的 `task_id` 继续轮询，直至 `task_status` 为 `success`。

> **`file_id` 与 `link_id` 二选一必填**：通过文件直接访问时传 `file_id`；通过分享链接访问时传 `link_id`。两者不可同时为空。

**类型适用范围**：不支持 .csv 格式。Excel（.xlsx）与智能表格（.ksheet）应使用 `sheet.*`，多维表格（.dbt）应使用 `dbsheet.*`，智能文档（.otl）日常读取优先使用 `otl.block_query`（本工具对 otl 存在内容遗漏风险）。



#### 操作约束

- **禁止**：禁止对 .csv 文件调用本工具
- **提示**：Excel/智能表格用 `sheet.*`，多维表格用 `dbsheet.*`，智能文档日常读取优先 `otl.block_query`

**幂等性**：是

> 首次调用（不传 `task_id`）若返回 `task_status=success`，此时内容已就绪，无需再次轮询；若返回 `task_status=running`，再携带 `task_id` 轮询
> `file_id` 与 `link_id` 二选一必填，两者均为空时请求无效
> 避免重复提交：同一 `file_id`（或 `link_id`）+ `format` + `include_elements` 在已有 `running` 任务时，优先继续使用原 `task_id` 轮询

#### 调用示例

读取文档为 Markdown：

```json
{
  "drive_id": "string",
  "file_id": "string",
  "format": "markdown",
  "include_elements": [
    "para",
    "table"
  ],
  "mode": "async",
  "task_id": "string"
}
```


#### 参数说明

- `drive_id` (string, 必填): 驱动盘 ID
- `file_id` (string, 二选一必填: `file_id` / `link_id`): 文件 ID。与 `link_id` 二选一传入
- `link_id` (string, 二选一必填: `file_id` / `link_id`): 分享链接 ID。与 `file_id` 二选一传入；通过分享链接访问文件时使用
- `format` (string, 可选): 文档内容目标格式。可选值：`kdc`（结构化表示）/ `plain`（纯文本）/ `markdown`
- `include_elements` (array, 可选): 指定抽取元素。默认元素为 `para`（段落），且一定会被导出；其余附加元素根据参数选择性导出。可选值：`para` / `table` / `component` / `textbox` / `all`
- `enable_upload_medias` (boolean, 可选): 默认 `false`，抽取结果中图片为空链接；为 `true` 时图片会携带可下载的临时 URL（有效期约 10 分钟）。仅当 `format` 为 `markdown` 或 `kdc` 时生效
- `mode` (string, 可选): **仅支持 `async`**，无需传或固定传 `async`
- `task_id` (string, 可选): 异步任务 ID，用于结果轮询；首次调用不传，后续用返回的 `task_id` 查询直至 `task_status` 为 `success`

#### 返回值说明

```json
{
  "data": {
    "task_id": "string",
    "task_status": "success",
    "dst_format": "markdown",
    "markdown": "string",
    "plain": "string",
    "src_format": "otl",
    "version": "string",
    "doc": {}
  },
  "code": 0,
  "msg": "string"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.task_id` | string | 任务 ID，异步模式下返回 |
| `data.task_status` | string | 任务状态。可选值：`success` / `running` / `failed` |
| `data.dst_format` | string | 目标格式：`kdc` / `plain` / `markdown` |
| `data.markdown` | string | markdown 内容数据，目标格式为 `markdown` 时适用 |
| `data.plain` | string | 纯文本内容数据，目标格式为 `plain` 时适用 |
| `data.doc` | object | 文字类的结构化数据，源格式为 otl/pdf/docx 且目标格式为 `kdc` 时适用 |
| `data.src_format` | string | 源格式（otl, docx, pdf, xlsx 等） |
| `data.version` | string | 版本号 |


---



path: references/drive/recent_and_recycle.md
content: # 八、最近与回收站

## 1. list_latest_items

#### 功能说明

获取当前用户最近访问的文档列表，支持分页、过滤和排序。


#### 调用示例

获取最近访问列表：

```json
{
  "page_size": 20
}
```


#### 参数说明

- `page_size` (integer, 必填): 每页条数；建议 20；范围 1–500
- `page_token` (string, 可选): 分页 token
- `include_exts` (string, 可选): 只返回指定后缀的文件，逗号分隔
- `exclude_exts` (string, 可选): 排除指定后缀的文件，逗号分隔
- `include_creators` (string, 可选): 只返回指定创建者的文件，逗号分隔（创建者 ID）
- `exclude_creators` (string, 可选): 排除指定创建者的文件，逗号分隔
- `with_permission` (boolean, 可选): 是否返回权限信息
- `with_link` (boolean, 可选): 是否返回分享信息

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": "string",
        "name": "string",
        "type": "file",
        "drive_id": "string",
        "mtime": 0
      }
    ],
    "next_page_token": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array[FileInfo] | 最近访问文件列表，结构见附录 A |
| `data.next_page_token` | string | 下一页 token，为空表示已是最后一页 |


---

## 2. list_deleted_files

#### 功能说明

获取回收站文件列表，支持分页和按驱动盘过滤。



#### 调用示例

列出回收站文件：

```json
{
  "page_size": 20
}
```


#### 参数说明

- `page_size` (integer, 必填): 每页条数；建议 20；范围 1–100
- `page_token` (string, 可选): 分页 token
- `drive_id` (string, 可选): 按驱动盘过滤
- `with_ext_attrs` (boolean, 可选): 是否返回扩展属性
- `with_drive` (boolean, 可选): 是否返回所属驱动盘信息

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": "string",
        "name": "string",
        "type": "file",
        "drive_id": "string",
        "parent_id": "string",
        "ctime": 0,
        "mtime": 0
      }
    ],
    "next_page_token": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array[FileInfo] | 回收站文件列表，结构见附录 A |
| `data.next_page_token` | string | 下一页 token，为空表示已是最后一页 |


---

## 3. restore_deleted_file

#### 功能说明

将回收站文件还原到原位置


**幂等性**：是

#### 调用示例

还原回收站文件：

```json
{
  "file_id": "string"
}
```


#### 参数说明

- `file_id` (string, 必填): 回收站中的文件 ID（由 `list_deleted_files` 返回）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---



path: references/drive/search.md
content: # 五、搜索

## 1. search_files

#### 功能说明

支持按文件名、内容全文搜索，可按时间、创建者、文件类型等条件过滤。


> 新建文件后搜索可能无法立即命中，需等待索引更新

#### 调用示例

搜索文档：

```json
{
  "keyword": "区域周报告",
  "type": "all",
  "file_type": "file",
  "parent_ids": [
    "string"
  ],
  "page_size": 20,
  "order": "desc",
  "order_by": "mtime",
  "with_total": true
}
```


#### 参数说明

- `keyword` (string, 可选): 搜索关键字
- `type` (string, 必填): 搜索类型。可选值：`file_name`表示搜索文件名，`content`表示搜索文件内容，`all`表示全局搜索。
- `page_size` (integer, 必填): 每页条数；建议 100；范围 0–500（含 0）
- `page_token` (string, 可选): 翻页 token
- `file_type` (string, 可选): 文件类型筛选。可选值：`folder` / `file`
- `file_exts` (array, 可选): 文件后缀过滤
- `drive_ids` (array, 可选): 搜索盘列表
- `parent_ids` (array, 可选): 搜索目录列表
- `creator_ids` (array, 可选): 创建者 ID。公网只支持选择是否自己创建的文件
- `modifier_ids` (array, 可选): 编辑者 ID
- `sharer_ids` (array, 可选): 分享者 ID
- `receiver_ids` (array, 可选): 接收者 ID
- `time_type` (string, 可选): 时间范围类型。可选值：`ctime` / `mtime` / `otime` / `stime`
- `start_time` (integer, 可选): 最小时间
- `end_time` (integer, 可选): 最大时间
- `with_permission` (boolean, 可选): 是否返回文件操作权限
- `with_link` (boolean, 可选): 是否返回文件分享信息
- `with_total` (boolean, 可选): 是否返回搜索到的总条数
- `with_drive` (boolean, 可选): 是否返回驱动盘
- `order` (string, 可选): 排序方式。可选值：`desc` / `asc`
- `order_by` (string, 可选): 排序字段。可选值：`ctime` / `mtime`
- `scope` (array, 可选): 搜索范围。可选值：`all` / `share_by_me` / `share_to_me` / `latest` / `personal_drive` / `group_drive` / `recycle` / `customize` / `latest_opened` / `latest_edited`
- `channels` (array, 可选): 渠道信息
- `device_ids` (array, 可选): 设备 ID
- `exclude_channels` (array, 可选): 排除渠道信息
- `exclude_file_exts` (array, 可选): 排除文件后缀
- `filter_user_id` (integer, 可选): 创建者分享者过滤
- `file_ext_groups` (array, 可选): 文件分组后缀
- `search_operator_name` (boolean, 可选): 搜索文件的创建者或文件分享者

#### 返回值说明

```json
{
  "data": {
    "items": [
      {
        "file": {
          "created_by": {
            "avatar": "string",
            "company_id": "string",
            "id": "string",
            "name": "string",
            "type": "user"
          },
          "ctime": 0,
          "drive_id": "string",
          "ext_attrs": [
            { "name": "string", "value": "string" }
          ],
          "id": "string",
          "link_id": "string",
          "link_url": "string",
          "modified_by": {
            "avatar": "string",
            "company_id": "string",
            "id": "string",
            "name": "string",
            "type": "user"
          },
          "mtime": 0,
          "name": "string",
          "parent_id": "string",
          "shared": true,
          "size": 0,
          "type": "folder",
          "version": 0
        },
        "file_src": {
          "name": "string",
          "path": "string",
          "type": "link"
        },
        "highlights": {
          "example_key": ["string"]
        },
        "otime": 0
      }
    ],
    "next_page_token": "string",
    "total": 0
  },
  "code": 0,
  "msg": "string"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array | 搜索结果列表 |
| `data.items[].file` | object | 文件信息，通用文件信息结构（附录 A） |
| `data.items[].file_src` | object | 文件位置信息 |
| `data.items[].file_src.name` | string | 来源名称 |
| `data.items[].file_src.path` | string | 文件路径 |
| `data.items[].file_src.type` | string | 来源类型：`link` / `user_private` / `user_roaming` / `group_normal` / `group_dept` / `group_whole` |
| `data.items[].highlights` | map[string][]string | 匹配关键字 |
| `data.items[].otime` | integer | 文件打开时间 |
| `data.next_page_token` | string | 下一页 token |
| `data.total` | integer | 资源集合总数（仅 `with_total=true` 时返回） |


---



path: references/drive/share.md
content: # 四、分享

## 1. share_file

#### 功能说明

开启文件分享，可设置权限范围、访问密码、过期时间等。

**`drive_id`**（非必填）：

- **有明确的 drive_id** 必传。
- **没有**：不传。



#### 操作约束

- **禁止**：未经用户明确要求，禁止调用此工具
- **后置验证**：确认返回的分享链接有效

**幂等性**：是

#### 调用示例

开启公开分享：

```json
{
  "drive_id": "string",
  "file_id": "string",
  "scope": "anyone"
}
```

file_id：

```json
{
  "file_id": "string",
  "scope": "anyone",
  "opts": {
    "allow_perm_apply": true,
    "check_code": "string",
    "close_after_expire": true,
    "expire_period": 0,
    "expire_time": 0
  }
}
```


#### 参数说明

- `drive_id` (string, 可选): 目标云盘 ID。
- `file_id` (string, 必填): 文件 ID
- `scope` (string, 必填): 链接权限范围。可选值：`anyone`（所有人，仅公网支持）/ `company`（仅企业）/ `users`（指定用户）
- `opts` (object, 可选): 链接选项
  - `allow_perm_apply` (boolean, 可选): 允许申请权限
  - `check_code` (string, 可选): 访问密码
  - `close_after_expire` (boolean, 可选): 过期后取消分享链接
  - `expire_period` (integer, 可选): 过期时长。可选值：`0` / `7` / `30`
  - `expire_time` (integer, 可选): 过期时间点

#### 返回值说明

```json
{
  "data": {
    "created_by": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "user"
    },
    "ctime": 0,
    "drive_id": "string",
    "file_id": "string",
    "id": "string",
    "mtime": 0,
    "opts": {
      "allow_perm_apply": true,
      "check_code": "string",
      "close_after_expire": true,
      "expire_period": 0,
      "expire_time": 0
    },
    "role_id": "string",
    "scope": "anyone",
    "status": "open",
    "url": "string"
  },
  "code": 0,
  "msg": "string"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.id` | string | 分享链接 ID（修改分享属性时使用） |
| `data.url` | string | 分享访问 URL |
| `data.status` | string | 链接状态：`open` / `closed` / `expired` |
| `data.drive_id` | string | 盘 ID |
| `data.file_id` | string | 文件 ID |
| `data.role_id` | string | 权限角色 ID |
| `data.scope` | string | 权限范围：`anyone` / `company` / `users` |
| `data.ctime` | integer | 创建时间 |
| `data.mtime` | integer | 修改时间 |
| `data.opts` | object | 链接设置 |
| `data.created_by` | object | 创建者信息 |


---

## 2. set_share_permission

#### 功能说明

修改已有分享链接的权限范围、密码、过期时间等属性。


#### 操作约束

- **禁止**：未经用户明确要求，禁止修改分享权限
- **后置验证**：get_share_info 确认权限已变更

**幂等性**：是

> `check_code`（访问密码）仅在 `scope=anyone` 且当前环境支持时生效；不支持时接口返回 400100，可安全忽略该参数
> 修改分享属性前需先通过 `share_file` 获取有效的 `link_id`

#### 调用示例

修改分享权限：

```json
{
  "link_id": "string",
  "scope": "anyone",
  "opts": {
    "allow_perm_apply": true,
    "check_code": "string",
    "close_after_expire": true,
    "expire_period": 0,
    "expire_time": 0
  }
}
```


#### 参数说明

- `link_id` (string, 必填): 分享链接 ID（由 `share_file` 返回的 `data.id`）
- `scope` (string, 可选): 链接权限范围。可选值：`anyone`（仅公网支持）/ `company` / `users`。`login_users` 仅私有化支持
- `opts` (object, 可选): 链接设置
  - `allow_perm_apply` (boolean, 可选): 允许申请权限
  - `check_code` (string, 可选): 访问密码
  - `close_after_expire` (boolean, 可选): 过期后取消分享链接
  - `expire_period` (integer, 可选): 过期时长。可选值：`0` / `7` / `30`
  - `expire_time` (integer, 可选): 过期时间点

#### 返回值说明

```json
{
  "code": 0,
  "msg": "string"
}

```


---

## 3. cancel_share

#### 功能说明

取消文件分享。

**`drive_id`**（非必填）：

- **有明确的 drive_id** 必传。
- **没有**：不传。



#### 操作约束

- **前置检查**：get_share_info 确认当前分享状态与模式
- **用户确认**（mode=delete）：永久删除分享链接，不可恢复，必须向用户确认
- **后置验证**：get_share_info 确认分享状态已变更
- **提示**：建议优先使用 mode=pause（可恢复）

**幂等性**：否 — pause 可重试；delete 禁止重试

#### 调用示例

暂停分享：

```json
{
  "drive_id": "string",
  "file_id": "string",
  "mode": "pause"
}
```

file_id：

```json
{
  "file_id": "string",
  "mode": "pause"
}
```


#### 参数说明

- `drive_id` (string, 可选): 目标云盘 ID。
- `file_id` (string, 必填): 文件 ID
- `mode` (string, 可选): 取消分享模式，默认 `pause`。可选值：`pause`（暂停分享）/ `delete`（删除分享）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "string"
}

```


---

## 4. get_share_info

#### 功能说明

获取分享链接信息。通过 `link_id` 查询分享链接的详细属性。


#### 调用示例

查询分享信息：

```json
{
  "link_id": "string"
}
```


#### 参数说明

- `link_id` (string, 必填): 分享链接 ID（由 `share_file` 返回的 `data.id`）

#### 返回值说明

```json
{
  "data": {
    "created_by": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "user"
    },
    "ctime": 0,
    "drive_id": "string",
    "file_id": "string",
    "id": "string",
    "mtime": 0,
    "opts": {
      "allow_perm_apply": true,
      "check_code": "string",
      "close_after_expire": true,
      "expire_period": 0,
      "expire_time": 0
    },
    "role_id": "string",
    "scope": "anyone",
    "status": "open",
    "url": "string"
  },
  "code": 0,
  "msg": "string"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.id` | string | 分享链接 ID（修改分享属性时使用） |
| `data.url` | string | 分享访问 URL |
| `data.status` | string | 链接状态：`open` / `closed` / `expired` |
| `data.drive_id` | string | 盘 ID |
| `data.file_id` | string | 文件 ID |
| `data.role_id` | string | 权限角色 ID |
| `data.scope` | string | 权限范围：`anyone` / `company` / `users` |
| `data.ctime` | integer | 创建时间 |
| `data.mtime` | integer | 修改时间 |
| `data.opts` | object | 链接设置 |
| `data.created_by` | object | 创建者信息 |


---

## 5. get_file_link

#### 功能说明

获取文件的在线访问链接。


#### 调用示例

获取文件链接：

```json
{
  "file_id": "string"
}
```


#### 参数说明

- `file_id` (string, 必填): 文件 ID

#### 返回值说明

```json
{
  "file_id": "string",
  "file_url": "https://kdocs.cn/l/xxxxx",
  "name": "Q1销售报告"
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `file_id` | string | 文件 ID |
| `file_url` | string | 在线访问链接 |
| `name` | string | 文件名 |


---



path: references/drive/star.md
content: # 七、收藏

## 1. list_star_items

#### 功能说明

获取当前用户的收藏（星标）列表，支持分页和排序。



#### 调用示例

获取收藏列表：

```json
{
  "page_size": 20
}
```


#### 参数说明

- `page_size` (integer, 必填): 每页条数；建议 20；范围 1–500
- `page_token` (string, 可选): 分页 token，首次不传，后续传上次返回的 `next_page_token`
- `order` (string, 可选): 排序方向。可选值：`desc` / `asc`
- `order_by` (string, 可选): 排序字段，如 `ctime` / `mtime` / `rank`
- `include_exts` (string, 可选): 只返回指定后缀的文件，逗号分隔，如 `docx,xlsx`
- `exclude_exts` (string, 可选): 排除指定后缀的文件，逗号分隔
- `with_permission` (boolean, 可选): 是否返回文件操作权限信息
- `with_link` (boolean, 可选): 是否返回文件分享信息

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": "string",
        "name": "string",
        "type": "file",
        "drive_id": "string",
        "parent_id": "string",
        "ctime": 0,
        "mtime": 0
      }
    ],
    "next_page_token": "string"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.items` | array[FileInfo] | 收藏文件列表，结构见附录 A |
| `data.next_page_token` | string | 下一页 token，为空表示已是最后一页 |


---

## 2. batch_create_star_items

#### 功能说明

批量添加收藏


**幂等性**：是

#### 调用示例

批量添加收藏：

```json
{
  "objects": [
    {
      "id": "file_id_1",
      "type": "file"
    },
    {
      "id": "file_id_2",
      "type": "file"
    }
  ]
}
```


#### 参数说明

- `objects` (array[object], 必填): 待收藏对象列表
  - `id` (string, 必填): 文件 ID
  - `type` (string, 必填): 类型，取值 `file` / `drive`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---

## 3. batch_delete_star_items

#### 功能说明

批量移除收藏（取消星标）。



**幂等性**：是

#### 调用示例

批量移除收藏：

```json
{
  "objects": [
    {
      "id": "file_id_1",
      "type": "file"
    }
  ]
}
```


#### 参数说明

- `objects` (array[object], 必填): 待移除收藏的对象列表
  - `id` (string, 必填): 文件 ID
  - `type` (string, 必填): 类型，取值 `file` / `drive`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok"
}

```


---



path: references/drive.md
content: # 金山文档 Skill 工具完整参考

本文件包含金山文档 Skill 所有工具的 API 说明、参数、返回值。

> **通用返回字段**：所有接口均返回 `code`（状态码，0 表示成功）和 `msg`（人可阅读的文本信息）。

---

## 一、文档创建与上传

> 新建云文档、上传本地文件、网页剪藏与附件上传

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`create_file`](drive/create_and_upload.md) | 在云盘下新建文件或文件夹 | `file_type`, `name` |
| [`scrape_url`](drive/create_and_upload.md) | 网页剪藏，抓取网页内容并自动保存为智能文档 | `url` |
| [`scrape_progress`](drive/create_and_upload.md) | 查询网页剪藏任务进度 | `job_id` |
| [`upload_file`](drive/create_and_upload.md) | 全量上传写入文件（更新已有 docx/pdf 或新建并上传本地文件） | `file_id`\|`name`, `content_base64` |
| [`upload_attachment`](drive/create_and_upload.md) | 向已有文档上传附件，支持 URL 或 Base64 | `file_id`, `filename`, `url`\|`content_base64` |

## 二、文档读取与下载

> 列出目录、读取正文、获取下载信息与文件详情

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`list_files`](drive/read_and_download.md) | 获取指定文件夹下的子文件列表 | `drive_id`, `parent_id`, `page_size` |
| [`download_file`](drive/read_and_download.md) | 获取文件下载信息 | `file_id` |
| [`get_file_info`](drive/read_and_download.md) | 获取文件（夹）详细信息 | `file_id` |
| [`read_file_content`](drive/read_and_download.md) | 文档内容抽取为 Markdown/纯文本 | `drive_id`, `file_id`\|`link_id` |

## 三、文件组织

> 移动、重命名、复制以及同名检查

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`move_file`](drive/organize.md) | 批量移动文件(夹) | `drive_id`, `file_ids`, `dst_drive_id`, `dst_parent_id` |
| [`rename_file`](drive/organize.md) | 重命名文件（夹） | `file_id`, `dst_name` |
| [`copy_file`](drive/organize.md) | 复制文件到指定目录（可跨盘） | `file_id`, `dst_drive_id`, `dst_parent_id` |
| [`check_file_name`](drive/organize.md) | 检查目录下文件名是否已存在 | `drive_id`, `parent_id`, `name` |

## 四、分享

> 分享链接的开启、权限设置、取消、查询与在线访问

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`share_file`](drive/share.md) | 开启文件分享 | `file_id`, `scope` |
| [`set_share_permission`](drive/share.md) | 修改分享链接属性 | `link_id` |
| [`cancel_share`](drive/share.md) | 取消文件分享 | `file_id` |
| [`get_share_info`](drive/share.md) | 获取分享链接信息 | `link_id` |
| [`get_file_link`](drive/share.md) | 获取文件的云文档在线访问链接 | `file_id` |

## 五、搜索

> 跨云盘的文件搜索

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`search_files`](drive/search.md) | 文件（夹）搜索 | `type`, `page_size` |

## 六、标签

> 自定义标签的维护与对象打标

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`list_labels`](drive/label.md) | 分页获取云盘自定义标签列表（可按归属者、标签类型筛选） | `page_size` |
| [`create_label`](drive/label.md) | 创建自定义标签 | `allotee_type`, `name` |
| [`get_label_meta`](drive/label.md) | 获取单个标签详情（含系统标签固定 ID） | `label_id` |
| [`get_label_objects`](drive/label.md) | 获取某标签下的对象列表（文件/云盘等） | `label_id`, `object_type`, `page_size` |
| [`batch_add_label_objects`](drive/label.md) | 批量为多个文档对象添加同一标签（打标签） | `label_id`, `objects` |
| [`batch_remove_label_objects`](drive/label.md) | 批量取消标签 | `label_id`, `objects` |
| [`batch_update_label_objects`](drive/label.md) | 批量更新标签下对象排序或属性 | `label_id`, `objects` |
| [`batch_update_labels`](drive/label.md) | 批量修改自定义标签名称或属性 | `labels` |

## 七、收藏

> 收藏列表与批量操作

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`list_star_items`](drive/star.md) | 获取收藏（星标）列表 | `page_size` |
| [`batch_create_star_items`](drive/star.md) | 批量添加收藏 | `objects` |
| [`batch_delete_star_items`](drive/star.md) | 批量移除收藏 | `objects` |

## 八、最近与回收站

> 最近访问、回收站列表与还原

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`list_latest_items`](drive/recent_and_recycle.md) | 获取最近访问文档列表 | `page_size` |
| [`list_deleted_files`](drive/recent_and_recycle.md) | 获取回收站文件列表 | `page_size` |
| [`restore_deleted_file`](drive/recent_and_recycle.md) | 将回收站文件还原到原位置 | `file_id` |

## 附录

### A. 通用文件信息结构（FileInfo）

`create_file`、`upload_file`（步骤三）、`rename_file`、`list_files` 等接口返回的文件信息共用以下结构。响应字段表中 `array[FileInfo]` 即引用此结构：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 文件 ID |
| `name` | string | 文件名 |
| `type` | string | 文件类型：`file` / `folder` / `shortcut` |
| `size` | integer | 文件大小 |
| `parent_id` | string | 父目录 ID |
| `drive_id` | string | 驱动盘 ID |
| `version` | integer | 文件版本 |
| `ctime` | integer | 文件创建时间（时间戳，秒） |
| `mtime` | integer | 文件修改时间（时间戳，秒） |
| `shared` | boolean | 是否开启分享（link.status = 'open' 时为 true） |
| `link_id` | string | 分享 ID |
| `link_url` | string | 分享链接 URL |
| `created_by` | object | 文件创建者信息 |
| `created_by.id` | string | 身份 ID |
| `created_by.name` | string | 用户或应用的名称 |
| `created_by.type` | string | 身份类型：`user` / `sp` / `unknown` |
| `created_by.avatar` | string | 头像 |
| `created_by.company_id` | string | 身份所归属的公司 |
| `modified_by` | object | 文件修改者信息（结构同 created_by） |
| `ext_attrs` | array[object] | 文件扩展属性（`with_ext_attrs=true` 时返回），每项含 name 和 value |
| `drive` | object | 文件驱动盘信息（`with_drive=true` 时返回）

**`permission` 对象**（`with_permission=true` 时返回）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `comment` | boolean | 评论 |
| `copy` | boolean | 复制 |
| `copy_content` | boolean | 内容复制 |
| `delete` | boolean | 文件删除 |
| `download` | boolean | 下载 |
| `history` | boolean | 历史版本（仅公网支持） |
| `list` | boolean | 列表 |
| `move` | boolean | 文件移动 |
| `new_empty` | boolean | 新建 |
| `perm_ctl` | boolean | 权限管理 |
| `preview` | boolean | 预览 |
| `print` | boolean | 打印 |
| `rename` | boolean | 文件重命名 |
| `saveas` | boolean | 另存为（仅公网支持） |
| `secret` | boolean | 安全文档（仅公网支持） |
| `share` | boolean | 分享 |
| `update` | boolean | 编辑/更新 |
| `upload` | boolean | 上传：手动上传新版本


path: references/file-locating-guide.md
content: # 获取文件标识指南

大多数工具需要 `file_id` 和 `drive_id` 参数。按用户提供的信息选择定位方式：

`create_file` / `upload_file`（新建）中 `drive_id`、`parent_id` 的传参规则：
- 可省略：用户未说明目标文件夹。
- 必须传入：用户已说明目标文件夹且已定位到对应 `drive_id`、`parent_id`；能传却省略视为错误。

`download_file` / `rename_file` / `share_file` / `cancel_share` / `copy_file` 的 **`drive_id` 非必填**：**已有明确的 drive_id 则传**，**没有则省略**。

| 用户提供 | 定位方式 |
|---------|---------|
| 文件名/关键词 | `search_files` → 返回结果中包含 `file_id` 和 `drive_id` |
| 文档链接 | 从 URL 提取 `link_id`（见下方链接解析）→ `get_share_info(link_id)` → 取 `file_id` 和 `drive_id` |
| 已知 `file_id` | `get_file_info(file_id)` → 补充获取 `drive_id` |
| 创建文件（指定文件夹） | `search_files` 等查到目标文件夹 → 传 `drive_id` + 该文件夹 `file_id` 作为 `parent_id` |
| 创建文件（用户未指定文件夹） | `drive_id`、`parent_id` 可不填，直接 `create_file` / `upload_file`（新建） |

> 根目录的 `parent_id` 固定为 `"0"`。

#### 文档链接解析

当链接域名为 `365.kdocs.cn` 或 `www.kdocs.cn` 时，按路径格式提取末尾的 `link_id`：

| 路径格式 | 提取规则 |
|---------|---------|
| `/l/<link_id>` | 文件分享链接 |
| `/folder/<link_id>` | 文件夹分享链接 |
| `/view/l/<link_id>` | 文件预览链接 |

提取后调用 `get_share_info(link_id)` 获取 `file_id` 和 `drive_id`。

> **AIPPT 文档转 PPT 快捷方式**：当用户提供金山文档链接并要求生成 PPT 时，从 URL 提取的 `link_id` 可直接以 `type: "v7_file_id"` 传入 `aippt.doc_outline_options` 和 `aippt.doc_outline`，无需先调用 `get_share_info` 获取 `file_id`。


path: references/file-reading-guide.md
content: # 文件读取指南

不同文件类型对应不同读取工具。先判断类型再调用工具，可避免空结果和结构丢失。

#### 读取流程

1. **定位文件**：先用 `search_files` / `get_file_info` 获取 `file_id`、`drive_id` 和文件后缀。  
2. **查看文件后缀**：按后缀确认文档类型，禁止 `search_files` 后直接批量调用 `read_file_content`。  
3. **按后缀选择读取工具**：使用下方“类型映射表”的首选路径。  
4. **命中 `read_file_content` 时再选轮询策略**：仅当类型为 `.docx/.pdf` 且使用 `read_file_content` 时，按 `size` 分档设置轮询间隔。  

#### 类型映射表（唯一主表）

| 文件类型 | 首选读取路径 | `read_file_content` 使用策略 |
|---|---|---|
| `.docx`（wps）/ `.pdf` | `read_file_content` | 默认可用 |
| `.otl`（ap） | `otl.block_query`（优先分块） | 仅在导出 Markdown 时使用 |
| `.xlsx`（et）/ `.ksheet`（as） | `sheet.get_sheets_info` + `sheet.get_range_data` | 禁止 |
| `.dbt`（db） | `dbsheet.get_schema` + `dbsheet.list_records` / `dbsheet.get_record` | 禁止 |
| `.csv` | 先转 `.xlsx` 再走 `sheet.*` | 禁止 |

#### `read_file_content` 轮询策略（仅 `.docx/.pdf` 场景）

首次调用（不传 `task_id`）**若返回 `task_status=success`**，此时内容已就绪，无需任何轮询。仅当首次返回 `task_status=running` 时，才需携带 `task_id` 继续轮询。

**客户端轮询分档**（仅 `task_status=running` 时适用）：

- `size` 字段统一使用 `FileInfo.size`（bytes）。
- `size` 来源优先级：`search_files.items[].file.size` > `get_file_info.data.size`。
- 若入口是 `get_share_info` 或当前上下文无 `size`，先调用 `get_file_info(file_id)` 补齐 `size`。

| 分档 | 条件（bytes） | 建议轮询间隔 |
|---|---|---|
| `small` | `< 1MB` | `1s,1s,2s` |
| `medium` | `1MB <= size < 10MB` | `2s,2s,3s` |
| `large` | `>= 10MB` | `3s,3s,5s` |
| `fallback` | `size` 缺失/异常 | `2s,2s,3s,5s` |

#### 特殊类型说明

**智能文档**（.otl / ap）——优先用 `otl.block_query`：

`otl.block_query`（`blockIds: ["doc"]`）可完整获取文档的块结构与内容。`read_file_content` 对 otl 存在内容遗漏风险，仅在需要导出 Markdown 时使用。

**文字文档 / PDF**（.docx / wps、.pdf）——用 `read_file_content`：

返回内容已自动转为 Markdown，可直接用于 AI 分析（摘要、审查、问答等）。

**表格类**（.xlsx / et、.ksheet / as）——**勿用 `read_file_content`**：

1. `sheet.get_sheets_info` 获取工作表列表和结构
2. `sheet.get_range_data` 按范围读取单元格数据

**多维表格**（.dbt / db）——**勿用 `read_file_content`**：

1. `dbsheet.get_schema` 获取数据表、字段、视图结构
2. `dbsheet.list_records` / `dbsheet.get_record` 读取记录

**CSV 文件**（.csv）——**不支持，勿用 `read_file_content`**：
1. 暂不支持 CSV 在线读取。建议用户将 CSV 转为 .xlsx 后用 `sheet.*` 工具读取。

#### 注意事项

- **PDF 精度**：复杂排版（表格、图片、多栏）可能存在精度损失，提取结果为近似纯文本
- **空读取排查**：若 `read_file_content` 返回空内容，检查：(1) 文件是否为空文件 (2) 文件格式是否受支持 (3) 文件后缀与实际格式是否匹配


path: references/file-writing-guide.md
content: # 文件创建与写入指南

> 已有文件（用户提供了 `file_id` 或通过搜索/链接定位到文件）→ 跳过「类型选择」和 `create_file`，直接看各类型的「更新」路径。

#### 保存位置（`drive_id` / `parent_id`）

`create_file` / `upload_file`（新建）：`drive_id`、`parent_id` 非必填。**用户未指定文件夹**时可省略两参数。**已说明目标文件夹且已查到drive_id、parent_id** 时必须传入；细则见 `file-locating-guide.md`。

#### 本地文件上传（`upload_file`）

适用场景：用户提供本地文件内容，需要直接上传到云盘（新建）或覆盖已有文件。

- 新建上传：`upload_file(drive_id, parent_id, name, content_base64)`
- 覆盖更新：`upload_file(file_id, content_base64)`
- 已明确目标目录时，建议显式传入 `drive_id`、`parent_id`，避免目录偏差

#### 类型选择决策树

仅在需要新建文件时使用：

```
用户需要创建文档
├── 需要丰富排版/图文混排？ → .otl 智能文档（别名 ap）首选
├── 需要表格/数据处理？
│   ├── 简单表格数据 → .xlsx 表格（别名 et）
│   ├── 需要多视图/字段管理/看板（智能表格产品形态）→ .ksheet 智能表格（别名 as）
│   └── 需要多数据表、关联、丰富字段类型与甘特/画册等多视图（多维表格产品形态）→ .dbt 多维表格（别名 db）
├── 需要生成 PDF？ → .pdf
├── 需要兼容 Word？ → .docx 文字文档（别名 wps）
├── 需要生成 PPT？ → .pptx 演示文稿（别名 wpp）
└── 不确定 → .otl 智能文档（别名 ap）默认推荐
```

#### 写入流程

**智能文档**（.otl / ap）——**勿用 `upload_file`**：

- 新建写入：`create_file` → `otl.insert_content` 写入内容
- 更新：`otl.insert_content` 插入内容（`format=markdown, mode=prepend` 从开头插入，`mode=append` 在末尾追加，`mode=replace` 替换全部内容）

**文字文档**（.docx / wps）：

- 新建写入：`create_file` → `upload_file(file_id, content_base64)` 写入内容
- 更新：优先调用 `wps.*` 基础能力做局部编辑；基础能力不支持或在“整篇重写/覆盖上传”场景使用 `upload_file(file_id, content_base64)` 全量覆盖
- Markdown 源内容须传 `content_format="markdown"`

**PDF**（.pdf）——新建无需 `create_file`：

- 新建写入：`upload_file(drive_id, parent_id, name="xxx.pdf", content_base64=...)`
- 更新：`upload_file(file_id, content_base64=...)` 全量覆盖

**Excel 表格**（.xlsx / et）：

- 新建写入：`create_file` → `sheet.update_range_data` 批量写入
- 更新：`sheet.update_range_data` 按范围写入

**智能表格**（.ksheet / as）：

- 新建写入：`sheet.create_airsheet_file` → `sheet.update_range_data` 批量写入
- 更新：`sheet.update_range_data` 按范围写入

**多维表格**（.dbt / db）：

- 新建写入：`create_file` → `dbsheet.create_sheet` → `dbsheet.create_fields` → `dbsheet.create_records`
- 更新：`dbsheet.update_records` / `dbsheet.create_records` 增改记录

**演示文稿**（.pptx / wpp）：

- 新建写入：`create_file` 或 `upload_file` 上传本地 pptx
- 主题生成型 AI PPT：优先走 `aippt.theme_questions` → `aippt.theme_deep_research` → `aippt.theme_outline` → 本地格式转换 → `aippt.theme_generate_html_pptx` → `upload_file`


path: references/kwiki/close_knowledge_view.md
content: # kwiki.close_knowledge_view

## 1. kwiki.close_knowledge_view

#### 功能说明

关闭并删除指定个人知识库，操作前务必确认目标正确。


#### 操作约束

- **前置检查**：调用 `kwiki.get_knowledge_view` 确认目标知识库名称和 ID
- **用户确认**：关闭知识库不可恢复，必须向用户确认目标知识库名称和 ID

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

#### 调用示例

关闭指定知识库：

```json
{
  "drive_id": "8001234567"
}
```


#### 参数说明

- `drive_id` (string, 必填): 要关闭的知识库驱动盘 ID，来自 `list_knowledge_views` 或 `get_knowledge_view` 返回值

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": ""
}

```


---



path: references/kwiki/create_item.md
content: # kwiki.create_item

## 1. kwiki.create_item

#### 功能说明

在指定父级 kuid 下新建文件夹或指定类型的云文档。


#### 操作约束

- **后置验证**：`kwiki.list_items` 确认创建成功

**幂等性**：否 — 重复调用会创建多个条目，先确认是否已成功

> 传知识库 `kuid` 则创建在根目录，传文件夹 `kuid` 则创建在该文件夹下

#### 调用示例

创建文件夹：

```json
{
  "doc_type": "folder",
  "kuid": "0s_8002345678",
  "title": "培训材料"
}
```

创建文字文档：

```json
{
  "doc_type": "w",
  "kuid": "0l_parent_xxx",
  "title": "销售常见问题"
}
```


#### 参数说明

- `doc_type` (string, 必填): 文档类型。可选值：`folder` / `w` / `s` / `o` / `p` / `d`
  - `folder`=文件夹
  - `w`=在线文字
  - `s`=表格
  - `o`=智能文档
  - `p`=演示文稿
  - `d`=轻维表
- `kuid` (string, 必填): 父级 kuid——传知识库 kuid（`0s_...`）创建在根目录，传文件夹 kuid 创建在该文件夹下
- `title` (string, 必填): 新建文件或文件夹的标题名称

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "kuid": "0lXyZw7KLmN1pQ",
    "title": "培训材料",
    "url": "/l/XyZw7KLmN1pQ?source=kmwiki"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.kuid` | string | 新建项的 kuid |
| `data.title` | string | 新建项标题 |
| `data.url` | string | 相对路径，拼接 `https://www.kdocs.cn` + url 得到完整链接 |


---



path: references/kwiki/create_knowledge_view.md
content: # kwiki.create_knowledge_view

## 1. kwiki.create_knowledge_view

#### 功能说明

创建新的个人知识库空间，可设置名称、状态、描述、封面与来源等基础信息。


#### 操作约束

- **后置验证**：新建后调用 `kwiki.get_knowledge_view` 或 `kwiki.list_knowledge_views` 核对返回的 `drive_id`、`group_id`、`kuid`

**幂等性**：否 — 重复调用会创建多个知识库，先确认是否已成功

#### 调用示例

创建销售知识库：

```json
{
  "space_name": "销售知识库",
  "desc": "沉淀销售话术、案例和培训资料",
  "status": 1
}
```


#### 参数说明

- `space_name` (string, 必填): 知识库名称
- `status` (number, 必填): 可见性状态。`1`=团队可见；`2`=企业可见；`3`=互联网公开。未提供该字段会返回 `inner invalid argument (status)` 错误。可选值：`1` / `2` / `3`；默认值：`1`
- `desc` (string, 可选): 知识库简介文本
- `img` (string, 可选): 封面图 URL 或资源标识，不传使用系统默认封面
- `source` (string, 可选): 创建来源标识，用于业务溯源
- `role_id` (string, 可选): 创建者角色 ID，不传使用默认角色

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "drive_id": "8001234567",
    "group_id": "6200987654",
    "kuid": "0s_8001234567"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.drive_id` | string | 新建知识库的驱动盘 ID |
| `data.group_id` | string | 新建知识库的群组 ID |
| `data.kuid` | string | 新建知识库的 kuid，格式 `0s_...` |


---



path: references/kwiki/delete_item.md
content: # kwiki.delete_item

## 1. kwiki.delete_item

#### 功能说明

删除后进入知识库回收站，7 天内可通过 restore_deleted_file 恢复。支持删除文件夹（包括非空文件夹，会连带删除内部所有内容）。


#### 操作约束

- **前置检查**：`kwiki.list_items` 确认对象名称和位置
- **用户确认**：删除操作不可逆（非空文件夹会连带删除），必须向用户确认

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

> 仅支持单个删除，批量清理时需循环调用
> 删除后进入知识库回收站，7 天内可通过 `restore_deleted_file(file_id=...)` 恢复
> **也支持删除文件夹**（包括空文件夹和非空文件夹），非空文件夹会连带删除内部所有内容

#### 调用示例

删除指定条目：

```json
{
  "kuid": "0lPqRs8WxYzAbC"
}
```


#### 参数说明

- `kuid` (string, 必填): 待删除条目的 kuid，来自 `list_items` 返回值

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "message": "文件已移至回收站，7天内可恢复",
    "trash_url": "https://www.kdocs.cn/enttrash/0"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.message` | string | 操作结果描述 |
| `data.trash_url` | string | 回收站页面链接 |


---



path: references/kwiki/get_knowledge_view.md
content: # kwiki.get_knowledge_view

## 1. kwiki.get_knowledge_view

#### 功能说明

根据 drive_id 或名称查询单个知识库的详细信息。drive_id 与 name 至少提供其一。


> 如果用户同时给了名称和 ID，优先用 ID
> 若名称匹配到多个知识库，需结合返回结果进一步确认目标知识库

#### 调用示例

按 drive_id 查询：

```json
{
  "drive_id": "8001234567",
  "group_id": "6200987654"
}
```

按名称查询：

```json
{
  "name": "销售知识库"
}
```


#### 参数说明

- `drive_id` (string, 二选一必填: `drive_id` / `name`): 条件必填：已知知识库驱动盘 ID 时直接传（来自 `list_knowledge_views` / `create_knowledge_view` 返回值）。与 name 至少填其一
- `name` (string, 二选一必填: `drive_id` / `name`): 条件必填：仅知道名称时传入，模糊匹配。与 drive_id 至少填其一
- `group_id` (string, 可选): 群组 ID（来自 `list_knowledge_views` / `create_knowledge_view` 返回值），已知时传入可加速定位

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "drive_id": "8001234567",
    "group_id": "6200987654",
    "kuid": "0s_8001234567",
    "space_name": "销售知识库",
    "desc": "沉淀销售话术、案例和培训资料",
    "cover_img": "https://cdn.example.com/2025/06/09/other/7.png",
    "file_total": 12,
    "member_total": 1,
    "utime": 1775221117,
    "owner": {
      "id": 900012345,
      "name": "张三",
      "avatar": "https://img.example.com/avatar/default"
    }
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.drive_id` | string | 知识库驱动盘 ID |
| `data.group_id` | string | 群组 ID |
| `data.kuid` | string | 知识库唯一标识，格式 `0s_...`，用于构造访问链接：`https://www.kdocs.cn/wiki/l/{kuid}` |
| `data.space_name` | string | 知识库名称 |
| `data.desc` | string | 知识库描述 |
| `data.cover_img` | string | 封面图片 URL |
| `data.file_total` | number | 文档总数 |
| `data.member_total` | number | 成员总数 |
| `data.utime` | number | 最近更新时间（Unix 时间戳，秒） |
| `data.owner` | object | 知识库所有者信息，含 id / name / avatar |


---



path: references/kwiki/import_cloud_doc.md
content: # kwiki.import_cloud_doc

## 1. kwiki.import_cloud_doc

#### 功能说明

把已有云文档导入到知识库中，可导入副本或快捷方式。这是「导入已有云文档」工具，不是「上传本地文件」工具。


#### 操作约束

- **后置验证**：`kwiki.list_items` 确认文档已导入

**幂等性**：否 — 重复调用会导入多份，先确认是否已成功

> 如果用户提供的是本地文件内容，应改用 `upload_file`

#### 调用示例

复制导入云文档：

```json
{
  "action": "copy",
  "kuid": "0s_8002345678",
  "file_infos": [
    {
      "file_ids": [
        100200300403
      ],
      "group_id": 6200987654
    }
  ]
}
```


#### 参数说明

- `kuid` (string, 必填): 目标知识库 kuid（格式 `0s_...`）或知识库内文件夹 kuid，来自 `list_knowledge_views` / `list_items`
- `action` (string, 可选): 导入方式，copy 为副本，shortcut 为快捷方式。可选值：`copy` / `shortcut`；默认值：`copy`
- `file_infos` (array[object], 必填): 待导入云文档列表，每项含 `file_ids`（云文档 file_id 数组）和 `group_id`（文档所属群组 ID）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "url": "/wiki/l/0s_8001234567"
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.url` | string | 知识库相对路径，拼接 `https://www.kdocs.cn` + url 得到完整链接 |


---



path: references/kwiki/list_items.md
content: # kwiki.list_items

## 1. kwiki.list_items

#### 功能说明

列出知识库根目录或某个文件夹下的内容，返回文件和文件夹混合列表。


> 浏览知识库根目录或进入某个文件夹后继续查看下一级内容
> 为后续移动、删除、下载收集 `kuid`

#### 调用示例

列出根目录内容：

```json
{
  "kuid": "0s_8002345678"
}
```


#### 参数说明

- `kuid` (string, 必填): 知识库 kuid（格式 `0s_...`，来自 `list_knowledge_views` / `get_knowledge_view`）或文件夹 kuid（来自 `list_items`）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "has_more": false,
    "list": [
      {
        "kuid": "0lAbCdE1234fGH",
        "file_id": "100200300401",
        "title": "产品需求文档",
        "doc_type": "o",
        "doc_origin_type": "otl",
        "link_id": "AbCdE1234fGH",
        "ctime": 1775221153,
        "size": 28175,
        "parent_id": "0",
        "creator": {
          "id": 900012345,
          "name": "张三",
          "avatar": "https://img.example.com/avatar/default"
        }
      },
      {
        "kuid": "0lXyZw7KLmN1pQ",
        "file_id": "100200300402",
        "title": "培训材料",
        "doc_type": "folder",
        "doc_origin_type": "",
        "link_id": "XyZw7KLmN1pQ",
        "ctime": 1775221152,
        "size": 0,
        "parent_id": "0",
        "creator": {
          "id": 900012345,
          "name": "张三",
          "avatar": "https://img.example.com/avatar/default"
        }
      }
    ],
    "next_page_token": ""
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.list` | array | 目录项列表 |
| `data.has_more` | boolean | 是否有更多项 |
| `data.next_page_token` | string | 下一页 token，为空表示无更多页 |

**items 条目字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `kuid` | string | 知识库内唯一标识，**kwiki 操作（delete_item/import_cloud_doc）均使用此 ID** |
| `file_id` | string | 云文档系统 file_id |
| `title` | string | 文件/文件夹名称（不含扩展名） |
| `doc_type` | string | 类型：`o`=智能文档, `w`=Word, `p`=PPT, `s`=Excel, `i`=图片, `v`=视频, `folder`=文件夹 |
| `link_id` | string | 分享链接标识，可通过 `get_file_link(link_id=...)` 获取在线链接 |
| `ctime` | integer | 创建时间（Unix 时间戳，秒） |
| `size` | integer | 文件大小（字节） |

> ⚠️ **注意**：`kwiki.list_items` 不返回 `mtime`（修改时间）。如需按修改时间筛选，
> 使用 `list_files(drive_id=知识库drive_id, parent_id=file_id, page_size=500, order_by="mtime")` 获取 `mtime` 信息。


---



path: references/kwiki/list_knowledge_views.md
content: # kwiki.list_knowledge_views

## 1. kwiki.list_knowledge_views

#### 功能说明

分页查询当前用户的个人知识库列表，支持按关键字过滤。


> 用户只提供了知识库名称时，先用它来定位知识库
> 需要列出某人当前有哪些知识库

#### 调用示例

按关键字分页查询：

```json
{
  "keyword": "销售",
  "page_size": 20
}
```


#### 参数说明

- `keyword` (string, 可选): 搜索关键字，匹配知识库名称；不传则返回全部
- `page_size` (number, 可选): 每页返回条数，不传使用服务端默认值
- `page_token` (string, 可选): 分页 token，首次请求不传；后续页传上一次返回的 `next_page_token`

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "has_more": false,
    "list": [
      {
        "drive_id": "8001234567",
        "group_id": "6200987654",
        "kuid": "0s_8001234567",
        "space_name": "销售知识库",
        "desc": "沉淀销售话术、案例和培训资料",
        "cover_img": "https://cdn.example.com/2025/06/09/other/1.png",
        "file_total": 12,
        "member_total": 1,
        "utime": 1775221117,
        "owner": {
          "id": 900012345,
          "name": "张三",
          "avatar": "https://img.example.com/avatar/default"
        }
      }
    ],
    "next_page_token": ""
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.list` | array[object] | 知识库摘要列表 |
| `data.has_more` | boolean | 是否有更多页 |
| `data.next_page_token` | string | 下一页 token，为空表示无更多页 |


---



path: references/kwiki/update_knowledge_view.md
content: # kwiki.update_knowledge_view

## 1. kwiki.update_knowledge_view

#### 功能说明

更新知识库名称、描述、封面、状态等配置，按需传入待修改字段。


#### 操作约束

- **前置检查**：`kwiki.get_knowledge_view` 确认目标知识库存在及当前配置
- **后置验证**：`kwiki.get_knowledge_view` 确认名称或简介已更新

**幂等性**：是

#### 调用示例

更新名称与描述：

```json
{
  "drive_id": "8001234567",
  "group_id": "6200987654",
  "name": "销售知识库（2026版）",
  "desc": "沉淀销售方法论、案例和常见问答",
  "cover_img": "https://cdn.example.com/2025/06/09/other/7.png",
  "status": 1
}
```


#### 参数说明

- `drive_id` (string, 必填): 知识库驱动盘 ID，来自 `list_knowledge_views` 或 `get_knowledge_view` 返回值
- `group_id` (string, 可选): 群组 ID，来自 `list_knowledge_views` 或 `get_knowledge_view` 返回值
- `name` (string, 可选): 新的知识库名称，不传则保持原值
- `desc` (string, 可选): 新的知识库描述，不传则保持原值
- `cover_img` (string, 必填): 封面图 URL（后端必传，可从 get_knowledge_view 获取当前值回传）
- `status` (number, 必填): 知识库状态（后端必传，可从 get_knowledge_view 获取当前值回传）

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": ""
}

```


---



path: references/kwiki.md
content: # 个人知识库（kwiki）工具完整参考文档

本文件说明金山文档 Skill 中个人知识库相关的 `kwiki.*` 工具如何使用。它们面向"知识库空间"和"知识库内资料管理"场景，适合创建知识库、浏览库内目录、导入已有云文档，以及整理知识库中的文件和文件夹。

## 通用说明

### 何时使用 `kwiki.*`

- 需要新建一个个人知识库或资料库空间
- 需要查询已有知识库列表，或按名称/ID 获取某个知识库详情
- 需要浏览知识库根目录或某个知识库文件夹下的资料
- 需要把**已有云文档**导入知识库
- 需要在知识库里新建文件夹或在线文件，并对库内资料做删除、下载
- 仔细阅读接口参数说明，不猜测，不胡编乱造

### 特别说明

> - 仔细阅读接口参数说明，不猜测，不胡编乱造

> - 本地上传不走 `kwiki.*`

### 链接输出规范

接口返回的数据中，`url` 字段为**相对路径**（如 `/l/xxx?source=kmwiki` 或 `/wiki/l/xxx`），`kuid`字段为**知识库/文件夹/文件id**。**Agent 在拼接完整链接时，必须遵循以下规则，不猜测：**

1. **拼接规则**：`https://www.kdocs.cn` + `data.url 原值`。
2. **手动构造**：若接口未返回 `url` 但返回了 `kuid`，格式为 `https://www.kdocs.cn/wiki/l/${kuid}`。

### 标识说明

在 `kwiki.*` 场景里，常见会用到以下标识：

- `drive_id`: 知识库对应的驱动盘 ID
- `group_id`: 知识库所属组 ID
- `kuid`: 知识库或知识库内文件/文件夹的标识

经验上：

- 知识库本身的 `kuid` 常见为 `0s...`
- 知识库内文件夹/文件的 `kuid` 常见为 `0l...`

如果用户只给了知识库名称，通常先用 `kwiki.list_knowledge_views` 搜，再把返回的 `drive_id` / `group_id` / `kuid` 传给后续工具。

> **注意**： `kuid` 仅用于 kwiki 专属操作（`delete_item`/`import_cloud_doc` 等）。

---

## 一、知识库空间

> 知识库空间的创建、查询、更新、关闭

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`kwiki.create_knowledge_view`](kwiki/create_knowledge_view.md) | 创建个人知识库 | `space_name`, `status` |
| [`kwiki.list_knowledge_views`](kwiki/list_knowledge_views.md) | 查询知识库列表 |  |
| [`kwiki.get_knowledge_view`](kwiki/get_knowledge_view.md) | 获取单个知识库详情 | `drive_id`\|`name` |
| [`kwiki.update_knowledge_view`](kwiki/update_knowledge_view.md) | 修改知识库基础配置 | `drive_id`, `cover_img`, `status` |
| [`kwiki.close_knowledge_view`](kwiki/close_knowledge_view.md) | 关闭（删除）知识库 | `drive_id` |

## 二、库内资料

> 空间内文件夹与文件的浏览、创建、删除、从云盘导入

| 工具 | 功能 | 必填参数 |
|------|------|----------|
| [`kwiki.list_items`](kwiki/list_items.md) | 列出知识库目录下的内容 | `kuid` |
| [`kwiki.import_cloud_doc`](kwiki/import_cloud_doc.md) | 将已有云文档导入知识库 | `kuid`, `file_infos` |
| [`kwiki.create_item`](kwiki/create_item.md) | 在知识库中创建文件或文件夹 | `doc_type`, `kuid`, `title` |
| [`kwiki.delete_item`](kwiki/delete_item.md) | 删除知识库中的文件或文件夹 | `kuid` |

## 常用工作流

#### 上传本地文件到知识库

**触发示例**：「把本地 XX 文件归档/上传/同步/放到 XX 库的 XX 文件夹」「把这些资料归档/上传/同步/放到 XX 库」「定时归档/上传/同步/放 XX 到 XX 库」

**流程**：
1. `kwiki.get_knowledge_view` 或 `kwiki.list_knowledge_views` 获取目标知识库的 `drive_id`
2. 如需放入子文件夹：
   - `kwiki.list_items` 定位目标文件夹，获取其 `kuid`（用于 kwiki 操作）和 `file_id`（用于通用接口的 `parent_id`）
   - 放入根目录则 `parent_id="0"`
3. 按文件类型选择上传方式：

**常规文件（docx/pdf/pptx/xlsx 等）**：
`upload_file(drive_id=知识库drive_id, parent_id=目标文件夹id, name="文件名.docx", content_base64=...)`

**Markdown 文件（.md）**：
> 默认转为在线智能文档，保留格式和结构化内容。仅当用户明确要求"上传并保持 md 格式"时，才使用 `upload_file` 直接上传原始 `.md` 文件。

- `kwiki.create_item(doc_type="o", kuid=目标文件夹kuid, title="文件名（不含后缀）")` 创建智能文档
- 读取本地 `.md` 文件内容
- `otl.insert_content(file_id=新文档的file_id, content=markdown原文, format="markdown", mode="prepend")` 将 markdown 写入智能文档
  - 如果内容过长（>3000 字符），分段写入：首段用 `mode="prepend"`，后续段用 `mode="append"` 追加
- 从 `kwiki.list_items` 返回中获取 `link_id`，拼接在线链接

#### 重命名知识库内的文件或文件夹

使用通用接口 `rename_file` 重命名知识库内的文件或文件夹：

1. `kwiki.get_knowledge_view(name="知识库名")` 获取知识库的 `drive_id` 和 `kuid`
2. `kwiki.list_items(kuid=知识库kuid)` 定位目标文件，获取 `file_id` 和 `drive_id`
3. `rename_file(drive_id=drive_id, file_id=file_id, dst_name="新名称")`
   - 文件须带后缀（如 `"新报告.docx"`）
   - 文件夹不带后缀（如 `"项目资料"`）

#### 下载知识库文件到本地

**流程**：

1. `kwiki.list_items(kuid=目标目录kuid)` 定位目标文件，获取 `file_id`、`link_id`、`drive_id`
2. 根据文件类型选择下载方式：

**普通文件（docx/pptx/pdf/图片等）**：
1. 使用 `wps.export` 等导出工具获取带签名的下载 URL（`link_id` 来自 `kwiki.list_items`）
2. `curl.exe -L -o "文件名" "签名URL"` 下载

**智能文档（doc_type="o"）**：`wps.export` 不支持直接导出，无特殊情况，默认转换成Markdown格式：
- **Markdown** → `read_file_content(drive_id, file_id, format="markdown")`（异步，需轮询 task_id），将返回的 markdown 内容保存为 `.md` 文件

**快捷方式文件（type="shortcut"）**：通过 `search_files` 搜索原始文件名找到源文件，再用源文件的 `link_id` 走上述通用流程。

> 注意：`download_file` 返回的 URL 需登录态，无法直接 curl。始终优先使用 `wps.export` 获取带签名的下载 URL。受保护文件（SecureDocumentError / forbidProtectedFile）所有导出接口均无法操作，需提示用户。

#### 把文件放到知识库

**触发示例**：「帮我把 XX 放到 XX 知识库」「把这些文件归档到 XX 库的 XX 文件夹」「帮我把本地 XX 文件夹的文件放到 XX 库里面」「帮我把 XX 网页的文章放到知识库」

**流程**：

1. **定位知识库**：指定库名 → `kwiki.get_knowledge_view(name=...)`；未指定 → `kwiki.list_knowledge_views` 推荐或引导创建
2. **定位目标路径**：指定文件夹 → `kwiki.list_items` 逐层查找，不存在则 `kwiki.create_item(doc_type="folder")` 按层级创建；未指定 → 根目录
3. **归档**：
   - 本地文件/文件夹 → 按「上传本地文件到知识库」流程逐个上传，保持子目录结构时递归创建文件夹
   - 网页 → `scrape_url` + `scrape_progress` 轮询完成后，`move_file` 移入目标库
   - 云盘已有文件 → `kwiki.import_cloud_doc(action="copy"/"shortcut")`
4. **确认结果**：`kwiki.list_items` 返回存放路径与直达链接；批量时展示成功/失败明细

#### 查找知识库内的文件

**触发示例**：「帮我找一下 XX 文件」「在 XX 库里找 XX 相关的资料」「我要找关于 XX 的文档」

**流程**：

1. **提取条件**：从用户指令中识别关键词、指定库名、文件类型等筛选条件
2. **定位搜索范围**：
   - 指定库 → `kwiki.get_knowledge_view(name=...)` 确认库存在，获取 `drive_id`
   - 未指定库 → `kwiki.list_knowledge_views` 获取全量知识库列表
3. **执行搜索**：`search_files(keyword="关键词", type="all", drive_ids=[目标drive_id列表])` 跨库或指定库检索
4. **返回结果**：按匹配度排序，展示文件名、所在库/路径、修改时间、直达链接；结果过多时提示用户按文件类型或时间范围二次筛选
5. **展示结果并询问用户** → 展示文件信息 + **主动询问是否下载到本地或打开查看（提供在线链接）用户选择下载时的后续操作**：

- `search_files` 返回的 `file_id` 可直接用于 `read_file_content` 等通用接口
- 根据文件类型选择下载方式，详见「下载知识库文件到本地」流程

#### 整理分类知识库

**触发示例**：「帮我整理一下 XX 知识库」「把 XX 库里的文件按类型分类」

> ⚠️ **场景识别**：当用户明确提到「知识库」「库」「资料库」等关键词时，优先使用 `kwiki.*` 系列接口完成整理/分类，确保知识库内部元数据（索引、搜索等）一致。

**流程**：

1. `kwiki.list_knowledge_views(keyword="库名")` 搜索目标知识库，获取 `drive_id`、`group_id`、`kuid` 等关键标识
2. `kwiki.list_items(kuid=知识库kuid)` 遍历根目录内容；如需递归遍历子文件夹，继续用文件夹的 `kuid` 调用 `kwiki.list_items`。收集每个文件的 `kuid`、`title`、`doc_type` 信息
3. 列出需新建的分类文件夹、文件移动目标、建议删除的内容，明确标注操作影响范围，**提交用户确认后再执行**
4. 批量创建文件夹（`kwiki.create_item`）→ 批量移动文件（`move_file`）→ 删除确认的冗余内容（`kwiki.delete_item`），提示回收站恢复路径（7 天内可恢复）

#### 清理知识库无用文件

**触发示例**：「清理 XX 库里 1 个月未修改的文件」「删掉 XX 库里的空文件夹」「把 XX 库里过期的资料清理一下」

**流程**：

1. `kwiki.list_items(kuid=空间kuid)` 递归遍历全库，获取每个文件/文件夹的 `kuid`、`file_id`、`title`、`doc_type`、`ctime`
2. **如需按修改时间筛选**：用 `list_files(drive_id=知识库drive_id, parent_id=父目录file_id, page_size=500, order_by="mtime")` 获取 `mtime`，通过 `file_id` 匹配到 `kuid`
3. **向用户展示待删除清单并确认**
4. `kwiki.delete_item(kuid=xxx)` 逐个删除（进入回收站，7 天内可 `restore_deleted_file` 恢复）
5. 空文件夹可同样通过 `kwiki.delete_item` 删除

#### 网页内容存入知识库

> **触发示例**：「把公众号文章存入XX知识库」「把这个链接存到知识库里」

**流程**
1. 主流程：scrape_url → scrape_progress(status=1) → move_file → get_file_link
2. 降级流程（scrape_url 失败/status=-1，如公众号等 JS 渲染页面）：
   browser 抓取正文 → create_file(name=xxx.docx)
   → upload_file(drive_id=xxx parent_id=0 file_id=xxx content_format=markdown content_base64=xxx)
   → move_file → get_file_link

| 注意 | 说明 |
|------|------|
| upload_file 必填参数 | `drive_id` 和 `parent_id` 必须显式传递 |
| ID 体系 | kwiki 内部 kuid 需通过 `kwiki.list_items` 获取 |

## 错误速查表

> ⛔ **强制规则**：命中下方任一错误条目时，**必须立即按「处理方式」向用户提示，禁止尝试其他接口绕过或反复重试。**

| 错误特征 | 原因 | 处理方式 |
|----------|------|----------|
| `code: 403000006`，`msg: "当前版本仅支持个人用户"` | 当前登录的是企业/团队账号，该知识库接口仅对个人账号开放 | 提示用户切换至个人账号后重试 |


path: references/otl/block_delete.md
content: # otl.block_delete

## 1. otl.block_delete

#### 功能说明

删除一个或多个块区间，适合按父块和索引范围删除内容。



#### 操作约束

- **前置检查**：先 otl.block_query 确认待删除块的内容，避免误删
- **用户确认**：删除操作不可逆，执行前必须向用户确认删除范围
- **提示**：块类型和属性具体含义可参考 `references/otl/node.md`，删除前需先理解块结构以确认删除范围
- **提示**：若查询到的块的 content 里包含 rangeMarkBegin 或 rangeMarkEnd，计算 startIndex 和 endIndex 时应忽略它们，它们是虚拟节点

**幂等性**：否 — 删除后再次调用会报块不存在，先确认当前状态

#### 调用示例

清空文档标题：

```json
{
  "file_id": "string",
  "params": {
    "blockId": "doc",
    "startIndex": 0,
    "endIndex": 1
  }
}
```

删除文档正文首个块：

```json
{
  "file_id": "string",
  "params": {
    "blockId": "doc",
    "startIndex": 1,
    "endIndex": 2
  }
}
```

删除段落的首个子节点：

```json
{
  "file_id": "string",
  "params": {
    "blockId": "PARA_ID",
    "startIndex": 0,
    "endIndex": 1
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 智能文档文件 ID
- `params` (object, 必填): 删除操作
  - `blockId` (string, 常用): 目标父块 ID；`doc` 表示删除文档根节点的子节点
  - `startIndex` (integer, 常用): 删除开始位置（包含该位置），且 `startIndex < endIndex`
  - `endIndex` (integer, 常用): 删除结束位置（不包含该位置）。例如 `startIndex=2, endIndex=5` 时，会删除索引 2、3、4。当 `blockId='doc'` 时，`index=0` 指向 title 节点，正文从 `index=1` 开始

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "...": "..."
  }
}

```


---



path: references/otl/block_insert.md
content: # otl.block_insert

## 1. otl.block_insert

#### 功能说明

向智能文档插入一个或多个块，适合在指定父块下按位置追加段落、列表、表格等结构化内容。



#### 操作约束

- **前置检查**：先 otl.block_query 了解文档块结构，确认插入位置
- **提示**：返回结果因内容和文档状态不同而异，以 code == 0 判断成功
- **提示**：待插入的节点类型和属性可参考 `references/otl/node.md`
- **提示**：当 blockId 为 `doc` 时，index 必须 >= 1，因为 doc 的首个子节点必须是 title（全局唯一）；正文开头插入应设 index 为 1
- **提示**：若查询到的块的 content 里包含 rangeMarkBegin 或 rangeMarkEnd，计算 index 时应忽略它们，它们是虚拟节点

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

#### 调用示例

在文档开头插入段落节点：

```json
{
  "file_id": "string",
  "params": {
    "blockId": "doc",
    "index": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "content": "一些文字"
          }
        ]
      }
    ]
  }
}
```

将段落的首个子节点后插入文本节点：

```json
{
  "file_id": "string",
  "params": {
    "blockId": "PARA_ID",
    "index": 1,
    "content": [
      {
        "type": "text",
        "content": "希望插入的文字"
      }
    ]
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 智能文档文件 ID
- `params` (object, 必填): 插入操作
  - `blockId` (string, 常用): 目标父块 ID，例如 `doc`
  - `index` (integer, 常用): 插入位置索引（从 0 开始）
  - `content` (array, 常用): 待插入的块内容数组

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "...": "..."
  }
}

```


---



path: references/otl/block_query.md
content: # otl.block_query

## 1. otl.block_query

#### 功能说明

查询指定块的结构与内容，适合在更新前先读取目标块信息。



> 查询得到的块类型和属性具体含义可参考 `references/otl/node.md`

#### 调用示例

查询文档根块（获取文档完整内容）：

```json
{
  "file_id": "string",
  "params": {
    "blockIds": [
      "doc"
    ]
  }
}
```

查询指定块（blockId 来自查询文档根块的返回结果）：

```json
{
  "file_id": "string",
  "params": {
    "blockIds": [
      "目标blockId"
    ]
  }
}
```


#### 参数说明

- `file_id` (string, 必填): 智能文档文件 ID
- `params` (object, 必填): 查询参数对象
  - `blockIds` (array, 常用): 要查询的块 ID 列表

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "...": "..."
  }
}

```


---



path: references/pdf/inspect.md
content: # 页面查询

## 1. pdf.get_pdf_page_count

#### 功能说明

查询指定 PDF 文件的总页数。

**适用于**：在拆页前确认范围是否合法，或当用户明确询问"这个 PDF 有多少页"时调用。

- 当用户给出"提取第 X 到 Y 页"这类要求时，若页数上限未知，先查页数再执行拆页
- 当用户已经明确给出可靠页数范围时，也可以直接调用后续工具
- 这个工具只解决"页数确认"，不负责读取正文内容



#### 调用示例

查询 PDF 页数：

```json
{
  "file_id": "file_pdf_001"
}
```


#### 参数说明

- `file_id` (string, 必填): PDF 文件 ID

#### 返回值说明

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "page_count": 15
  }
}

```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.page_count` | integer | PDF 总页数 |


---



Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)