金山文档SKILL功能更新，引入知识库功能

在金山文档 SKILL v1.3.3 版本中，个人知识库（kwiki）作为独立的功能模块被正式纳入。它提供了一套完整的 API 工具集，覆盖知识库的创建、浏览、内容管理、文件归档和整理分类等全流程操作。知识库模块专注于结构化的知识管理场景——将分散的文档、资料和网页内容组织到独立的知识空间中，实现高效的归档、检索与协作。

本文将基于 kwiki_references.md 参考文档，对这套知识库能力进行完整解析。

一、知识库模块定位与能力边界

与通用文档管理的区别

金山文档 SKILL 本身已经提供了 list_files、search_files、create_file、move_file 等通用接口，可以管理云空间中的各类文档。知识库模块（kwiki.*）与之的区别在于：

核心能力清单

知识库模块提供 9 个专用工具，分为三个层级：

• 空间管理层：创建、查询、修改、关闭知识库

• 内容浏览层：列出目录、搜索库内文件

• 内容操作层：导入云文档、新建文件/文件夹、删除条目

二、空间管理：知识库的完整生命周期

创建知识库 — kwiki.create_knowledge_view

创建一个新的知识库空间，支持设置名称、描述、封面和可见状态。

必填参数：

可选参数：desc（描述）、img（封面图 URL）、source（创建来源标识）、role_id（创建者角色）。

创建成功后返回三个核心标识：

这三个标识在后续的所有操作中都会用到。文档要求创建后执行后置验证——调用 get_knowledge_view 核对返回值是否正确。

查询知识库 — list 与 get

两个查询工具各有侧重：

kwiki.list_knowledge_views — 分页列表查询，支持关键字搜索。当用户只提供知识库名称时，这是定位目标知识库的首选方式。返回列表中包含每个知识库的名称、描述、封面、文件数、成员数和更新时间。

kwiki.get_knowledge_view — 查询单个知识库的详细信息。支持两种查询方式：按 drive_id（精确）或按 name（模糊匹配）。如果用户同时给了名称和 ID，优先使用 ID。若名称匹配到多个知识库，需要进一步确认。

更新知识库 — kwiki.update_knowledge_view

支持修改名称、描述、封面和状态。cover_img 和 status 在后端是必传字段。如果只想修改名称，需要先通过 get_knowledge_view 获取当前的 cover_img 和 status，再连同新名称一起回传。

关闭知识库 — kwiki.close_knowledge_view

不可逆操作。操作前必须向用户确认目标知识库的名称和 ID，并通过 get_knowledge_view 执行前置检查。关闭后知识库数据将被永久删除。

三、内容浏览：从目录到文件

列出目录内容 — kwiki.list_items

这是知识库内容浏览的核心工具，可以列出根目录或任意子文件夹下的内容。只需传入目标目录的 kuid 即可。

返回结果是一个文件和文件夹的混合列表，每个条目包含以下关键字段：

注意：**list_items 不返回 mtime（修改时间）**。如果需要按修改时间筛选文件，需要改用通用接口 list_files(drive_id=知识库drive_id, parent_id=file_id, order_by="mtime")，通过 file_id 与 kuid 建立关联。

标识体系的使用规则

知识库模块使用了一套统一的标识体系，文档中有明确的经验规则：

• 知识库本身的 kuid 以 0s_ 开头

• 知识库内文件和文件夹的 kuid 以 0l_ 开头

• kuid 仅用于知识库专属操作（delete_item、move_items、import_cloud_doc 等）

• 通用操作（如读取文件内容、重命名）需要使用 file_id

链接拼接规范

文档对链接拼接有严格的规范要求，不允许猜测：

1. 有 url 字段时：https://www.kdocs.cn + data.url 原值拼接

2. 只有 kuid 时：https://www.kdocs.cn/wiki/l/${kuid}

四、内容操作：导入、创建与删除

导入云文档 — kwiki.import_cloud_doc

将已有的金山文档导入到知识库中。支持两种导入方式：

参数中需要提供目标知识库/文件夹的 kuid，以及待导入文档的 file_ids 和 group_id。

需要注意：这个工具只能导入已有的云文档，不支持上传本地文件。本地文件需要通过通用接口 upload_file 上传。

新建内容 — kwiki.create_item

在知识库中创建新的文件夹或在线文档。支持的文档类型：

通过 kuid 参数控制创建位置：传入知识库的 kuid（0s_）则在根目录创建，传入文件夹的 kuid（0l_）则在指定文件夹下创建。

删除内容 — kwiki.delete_item

删除后进入知识库回收站，7 天内可通过通用接口 restore_deleted_file 恢复。支持删除文件夹（包括非空文件夹，会连带删除所有内容）。

文档要求执行删除前必须通过 list_items 确认对象名称和位置，并向用户确认。仅支持单个删除，批量操作需要循环调用。

五、典型工作流

5.1 本地文件归档到知识库

这是最常见的使用场景之一。完整流程：

1. 定位知识库：get_knowledge_view 或 list_knowledge_views 获取 drive_id

2. 定位目标文件夹（可选）：list_items 逐层查找，不存在则 create_item(doc_type="folder") 创建

3. 上传文件：

• 常规文件（docx/pdf/pptx/xlsx）：upload_file(drive_id=, parent_id=, name=, content_base64=)

• Markdown 文件：先 create_item(doc_type="o") 创建智能文档，再用 otl.insert_content 写入内容（超过 3000 字符需分段写入）

4. 确认结果：list_items 验证文件已成功归档

5.2 网页内容存入知识库

将网页文章保存到知识库有两条路径：

主流程：scrape_url（抓取网页） → scrape_progress（轮询完成状态） → move_file（移入知识库） → get_file_link（获取链接）

降级流程（适用于 JS 渲染页面如公众号文章）：通过浏览器抓取正文 → create_file 创建文档 → upload_file 上传到知识库 → move_file 移动 → get_file_link

5.3 知识库整理分类

当用户需要对知识库中的内容进行重新组织时：

1. list_items 递归遍历全库，收集每个文件的 kuid、title、doc_type

2. 按需通过 list_files(order_by="mtime") 获取修改时间信息

3. 制定整理方案（新建分类文件夹、文件移动计划、待删除内容），提交用户确认

4. 批量执行：create_item（创建文件夹）→ move_file（移动文件）→ delete_item（删除冗余内容）

5.4 跨库搜索

知识库的搜索能力需要借助通用接口 search_files：

search_files(keyword="关键词", type="all", drive_ids=[目标知识库的drive_id列表])

通过 drive_ids 参数可以指定搜索范围——单个知识库或跨多个知识库检索。

六、工程实践要点

6.1 标识系统的正确使用

知识库模块中存在两套 ID 体系，正确区分至关重要：

• kuid：知识库专有标识，用于 kwiki.* 系列操作（list_items、delete_item、import_cloud_doc、create_item）

• file_id + drive_id：金山文档通用标识，用于通用接口（read_file_content、upload_file、move_file、rename_file）

两套标识之间通过 list_items 的返回结果建立映射关系——每次调用 list_items 都会同时返回条目的 kuid 和 file_id。

6.2 操作约束链

文档为每个写操作定义了严格的前置/后置验证链路：

7.3 错误处理

文档定义了强制性的错误处理规则——遇到特定错误时必须立即提示用户，禁止尝试绕过：

金山文档 SKILL 的知识库模块（kwiki.*）提供了一套设计严谨的知识管理 API。从空间的生命周期管理（创建/查询/修改/关闭）到内容的精细操作（浏览/导入/创建/删除），9 个工具覆盖了知识库使用的主要场景。

几个值得注意的设计特点：

1. 双标识体系：kuid 用于知识库内部操作，file_id 用于通用文档操作，通过 list_items 建立映射

2. 云文档优先导入：import_cloud_doc 支持副本和快捷方式两种模式，让已有文档可以快速进入知识库体系

3. 与通用接口的深度协同：知识库模块专注于空间和内容管理，文件读写、搜索、下载等能力复用通用接口，形成了清晰的职责分层

4. 严格的操作约束：每个写操作都有明确的前置/后置验证要求，删除类操作强制用户确认，7 天回收站机制提供了容错保障

这套能力让 AI Agent 可以程序化地完成知识库的搭建、内容归档、分类整理等复杂任务，将原本需要手动操作的繁琐流程自动化。