灵犀Claw实战：从零搭建一个会自我进化的AI Agent（八）云文档API实战

本系列记录用WPS灵犀Claw平台从零搭建一个具备完整记忆闭环和自我改进能力的AI Agent的全过程。每个专题一篇，由浅入深。

开篇引言

前七篇搭建了完整的记忆闭环、自我改进、日记系统和生图能力。但有一个贯穿始终的"隐形基础设施"一直没有系统讲过——云文档API。

系列02的实时记忆需要读写云端user记忆；系列03的Dreaming需要同步WPS笔记；系列05的Cherry Diary需要创建笔记、上传语音和图片；系列06的Self-Improving需要加载云端记忆文件。每一篇都在用云文档，但都是"用到什么讲什么"，读者看到的只是碎片。

本篇把这些碎片拼成一张完整地图：灵犀Claw到底提供了几条路操作云文档？每条路适合什么场景？实战中踩过哪些坑？

三条路径全景

灵犀Claw操作云文档有三条完全不同的路径，很多新手甚至不知道它们的存在。

路径一：灵犀原生上传（三步上传协议）本质：HTTP API直传（V7）适用场景：发文件给用户、上传成果物系列中出现位置：系列05的语音上传

路径二：wps_docs内置技能本质：灵犀自带的Python封装适用场景：日常文件操作、ET表格、AP智能文档系列中出现位置：系列03的Dreaming笔记同步

路径三：kdocs金山文档Skill本质：独立CLI工具适用场景：完整文件管理、智能表单、知识库系列中出现位置：系列02的云盘文件管理

三条路径不是替代关系，而是互补关系。下面逐条展开。

路径一：灵犀原生上传（三步上传协议）

这是灵犀Claw最底层的文件上传能力，通过HTTP API直接操作云文档。当前底层接口为V7版本，核心流程是三步握手：

第一步：申请上传地址。向API发送文件信息（文件名、大小、SHA256哈希），服务端返回一个临时上传URL和upload_id。这一步的关键是SHA256计算——大文件需要分块读取，不能一次性加载到内存。

第二步：上传文件字节。用PUT方法将文件二进制数据发送到上一步获取的临时URL。这一步最容易出错的是HTTP方法——有的接口用PUT，有的用POST，取决于store_request返回的method字段，不能硬编码。

第三步：确认上传。上传完成后，用upload_id和store_key调用commit_upload接口，告诉服务端"文件已经传完，请处理"。这一步如果漏了，文件会上传不完整。

认证方式是通过环境变量TMP_LX_UUID注入的wps_sid Cookie，灵犀Claw启动时自动设置，开发者无需手动处理。

这个路径适合"一次性的文件上传"场景——比如把生成的图片、音频、文档发给用户。它不需要额外安装任何Skill，直接在Python代码中调用即可。

路径二：wps_docs内置技能

wps_docs是灵犀Claw自带的云文档操作技能，位于skills/wps-docs/目录下。它本质上是将底层API封装成了Python函数，提供了更友好的调用方式。

截至v1.2.4版本，wps_docs提供了以下核心能力：

云文档基础模块：文件信息查询、上传下载、文件夹管理。API函数包括get_file_info / upload_file / download_file / list_folder_files / find_folder_by_path / create_folder。

ET模块（在线表格）：创建和编辑.xlsx/.ksheet，支持公式、图表、条件格式。API函数包括create / edit + 数据读写、格式化、图表等。

AP模块（智能文档）：创建和编辑.otl文档，块级CRUD。支持导出Markdown、查询块结构、插入/删除/更新块。

DbSheet模块（多维表）：查询Schema、读写记录、管理字段和视图。支持记录CRUD、字段管理、视图配置。

使用方式很统一：导入kdocs模块，直接调用函数即可。所有函数返回统一的dict格式，包含success、data、message三个字段，方便错误处理。

一个值得注意的新功能：upload_file现在支持.md文件自动转换为.otl智能文档。上传一个Markdown文件，云端会自动创建一个同名的.otl文件，内容通过core/execute接口写入。这个功能在系列05的Cherry Diary中非常有用——日记的文本内容可以直接用Markdown格式上传，无需手动创建笔记。

路径三：kdocs金山文档Skill

kdocs金山文档Skill是从金山文档官网下载的独立Skill，与灵犀自带的wps_docs不同，它通过kdocs-CLI直接操作云文档，功能更全面。

两者的核心差异：

智能文档(.otl)：wps_docs完整（AP模块），kdocs完整（块级CRUD+页面管理）在线表格(.xlsx/.ksheet)：wps_docs完整（ET模块），kdocs完整多维表(.dbt)：wps_docs完整（DbSheet模块），kdocs完整（含父子记录、表单视图）智能表单(.form)：wps_docs不支持，kdocs支持知识库(kwiki)：wps_docs不支持，kdocs支持（空间管理、导入）文件管理（搜索/分享/回收站）：wps_docs基础（仅列表），kdocs完整版本更新：wps_docs被动（随灵犀更新），kdocs主动（自带版本检测）

一句话总结：日常操作用wps_docs就够了，需要高级功能时再装kdocs。wps_docs的优点是零安装、零配置、与灵犀版本同步；kdocs的优点是功能更全、更新更及时。

选型指南

根据实战经验，三条路径的选择逻辑如下：

给用户发文件（图片/音频/文档） → 灵犀原生上传。最轻量，无需Skill，直接Python调用。日常文件管理（浏览/上传/下载） → wps_docs基础模块。函数式调用，返回结构化数据。创建/编辑在线表格 → wps_docs ET模块。公式优先，支持格式美化。读写智能文档内容 → wps_docs AP模块。块级CRUD，精确控制。操作多维表 → wps_docs DbSheet模块。完整记录CRUD。创建智能表单 → kdocs金山文档Skill。wps_docs不支持。管理知识库 → kdocs金山文档Skill。wps_docs不支持。批量搜索/分享文件 → kdocs金山文档Skill。文件管理能力更完整。

实战配置：两套drive_id设计

在系列项目中，我们维护了两套云文档配置，这是实战中总结出的最佳实践：

第一套：用户可见的文件夹。用于存放最终交付给用户的文件——日记、图片、语音、报告等。用户打开云文档就能看到，方便分享和协作。

第二套：系统自动上传的文件夹。用于存放中间产物——记忆同步文件、临时缓存、日志等。用户不需要看到这些，避免污染文件列表。

两套配置通过不同的drive_id和folder_id区分。在wps_docs中，通过find_folder_by_path函数按路径查找文件夹，获取对应的file_id后进行操作。

踩坑清单

问题1：上传后文件不立即出现根因：API异步处理，3-5秒延迟解法：上传后等待几秒再执行后续操作

问题2：删除文件后同名文件上传失败根因：删除也是异步，旧文件元数据未完全清除解法：删除后等3-5秒再上传

问题3：MCP笔记写入中文乱码根因：服务端double-encoded UTF-8解法：先用latin-1编码还原原始字节，再按UTF-8解码

问题4：先写内容再挂标签失败根因：新版标签系统标签栏与正文分离解法：先挂标签再写内容，顺序不能反

问题5：replace后block ID变了根因：服务端重新分配block ID解法：replace后重新获取笔记大纲拿到最新block ID

问题6：硬编码drive_id导致环境迁移失败根因：不同用户的drive_id不同解法：用_resolve_drive_id动态解析

问题7：wps_docs不支持智能表单根因：功能边界限制解法：需要时安装kdocs金山文档Skill

问题8：社区帖子中code标签显示为图片根因：WPS社区编辑器限制解法：用b/strong标签替代code/pre

与前七篇的联动

云文档API不是独立技能，它是前面所有功能的基础设施。每一条路径都能对应到前七篇中的具体使用场景：

系列02（实时记忆）：读写云端user记忆、同步MEMORY.md → 灵犀原生 + wps_docs系列03（Dreaming）：同步碎片到WPS笔记 → wps_docs AP模块系列04（Memory Consolidation）：读取和更新MEMORY.md → wps_docs基础模块系列05（Cherry Diary）：创建笔记、上传语音/图片 → 灵犀原生上传 + Ainote MCP系列06（Self-Improving）：加载云端记忆文件 → 灵犀原生系列07（生图Prompt）：上传基准图、保存生图结果 → 灵犀原生上传

理解了云文档API，整个系列才算真正闭环。

下一篇：Skill开发实战——从零创建一个可发布的灵犀Claw Skill。

#WPS灵犀Claw #WPS技巧达人 #WPS灵犀