cms-docdb — 索引

OpenClaw 技能 name 为 cms-docdb，与仓库目录名和 skillcode 保持一致。本技能用于访问公司内部知识库（康哲/玄关/德镁知识库）。

本文件提供能力边界与路由规则。详细说明见 references/，实际执行见 scripts/。

当前版本: 1.1.0

接口版本: 所有业务接口统一使用 /open-api/* 前缀，鉴权类型全部为 appKey。

能力概览（6 块能力）：

• browse：发现可用空间、获取个人空间 ID、浏览目录结构、查看最近上传与全空间上传记录
• query：搜索文件，找到文件后获取内容、下载链接或预览链接
• upload：新建文件或文件夹——上传纯文本/物理文件、显式创建目录到 康哲/玄关/德镁知识库（内部应用侧；仅用于新建）
• delete：删除指定文件（高风险，需用户确认）
• manage：重命名/移动文件；更新已有文件内容（版本管理）；查看历史版本；版本定稿
• share：将文件/文件夹授权分享给指定员工；可撤销分享（默认发钉钉通知；默认权限：分享+在线预览+查看）

适用范围与歧义排除（技能门控，强制）

• 本 skill 唯一指向：通过 appKey 访问内部知识库应用所对接的 document-database 开放接口（路径形态 /open-api/document-database/*，OpenClaw name：cms-docdb；skillcode / 技术代号：cms-docdb / document-database）。对用户与内部沟通常用说法：知识库、康哲知识库、玄关知识库、德镁知识库、在线知识库及 公司知识库（同一类内部知识库应用的不同称呼/环境）。
• 明确不使用本 skill 的典型场景（应改走对应产品能力或追问用户）：钉钉知识库/钉盘、企业微信微盘、飞书知识库/云文档、语雀、Notion、Confluence、SharePoint、石墨 等。
• OpenClaw 路由建议：只要提及「知识库」就触发本 skill。
• 典型有效问法（内部真实话术）：如「打开知识库」「打开公司在线知识库」「请查询知识库中某政策标题并总结」「请阅读知识库中某文件夹内的文件」「能读产品资料-慷彼申里的内容吗」等，均在本 skill 能力范围内（具体模块依动作是浏览、搜索还是读全文而定）。

统一规范：

• 鉴权依赖：cms-auth-skills/SKILL.md
• 运行日志：.cms-log/log/cms-docdb/
• 运行时状态：.cms-log/state/cms-docdb/

授权依赖：

• 需要鉴权时先读取 cms-auth-skills/SKILL.md
• 如果未安装，先安装依赖，再继续执行

输入完整性规则（强制）：

1. 浏览目录必须提供 parentId（根目录传 0）或 projectId
2. 搜索文件必须提供关键词 + projectId（限定搜索范围，避免返回无关结果）
3. 上传文件必须提供文件名和内容（纯文本）或 resourceId（物理文件）
4. 删除/重命名/移动文件必须提供 fileId
5. 版本更新必须提供目标文件的 fileId（纯文本）或文件 id + projectId + resourceId（物理文件）

版本管理强制规则（最高优先级）：

• 禁止直接覆盖已有文件内容：对已存在文件的任何内容更新，必须通过版本管理接口保存为新版本，不得使用覆盖方式。直接覆盖无法溯源，违反本规则。
• 保存前必须判断文件是否已存在：执行任何"保存/上传/更新"动作前，必须先通过 searchFile 或 getChildFiles 确认目标文件是否已存在。
  • 若不存在：路由到 upload 模块走新建流程
  • 若已存在：路由到 manage 模块走版本更新流程，禁止新建同名文件或覆盖
• 不得询问用户是否覆盖：版本管理是默认且唯一的更新方式，无需向用户确认，直接执行版本更新。

建议工作流（简版）：

1. 先读取 SKILL.md，确认能力边界和限制
2. 根据用户意图定位模块，读取对应 references/<module>/README.md
3. 确认具体动作后，在 references/<module>/README.md 中查看脚本清单、入参与运行方式
4. 保存/上传前必须执行存在性检查：通过 search.py 或 browse.py 确认目标文件是否已存在。已存在则切换为版本更新流程（manage 模块），不存在才新建（upload 模块）
5. 补齐用户必需输入
6. 执行对应脚本

脚本使用规则（强制）：

1. 每个动作必须有对应脚本：不允许"暂无脚本"
2. 脚本可独立执行：所有 scripts/ 下的脚本均可脱离 AI Agent 直接在命令行运行
3. 先读模块说明再执行：执行脚本前，必须先阅读对应模块的 references/<module>/README.md
4. 鉴权一致：涉及 appKey 时，统一依赖 cms-auth-skills

意图路由与加载规则（强制）：

1. 先路由再加载：必须先判定模块，再打开该模块的 references/<module>/README.md
2. 先读说明再调用：在执行前，必须加载对应模块说明
3. 脚本必须执行：所有接口调用必须通过脚本执行，不允许跳过
4. 不猜测：若意图不明确，必须追问澄清
5. 歧义门控：只要提及「知识库」就触发本 skill

宪章（必须遵守）：

1. 只读索引：SKILL.md 只描述"能做什么"和"去哪里读"，不写具体接口参数
2. 按需加载：默认只读 SKILL.md + cms-auth-skills/SKILL.md，只有触发某模块时才加载该模块的 references 与 scripts
3. 对外克制：对用户只输出"可用能力、必要输入、结果链接或摘要"，不暴露鉴权细节与内部字段
4. 素材优先级：用户给了文件或 URL，必须先提取内容再确认，确认后才触发生成或写入
5. 生产约束：仅允许生产域名与生产协议，不引入任何测试地址
6. 危险操作：删除文件等高风险操作应礼貌确认，不直接执行
7. 脚本语言限制：调用 Open API 的业务脚本必须使用 Python
8. 重试策略：出错时间隔 1 秒、最多重试 3 次，超过后终止并上报
9. 禁止无限重试：严禁无限循环重试
10. 输出规范：脚本输出优先按 resultCode、resultMsg、data 读取，对用户输出最小必要信息：摘要/必要输入/链接，不回显完整 JSON 响应
11. 直接执行：所有脚本必须可直接通过 Python 执行，不依赖包装脚本

触发配置

意图触发词

下表为常见说法，非穷举。只要提及「知识库」就触发本 skill。

意图标签与模块目录（强制）：intent-matcher.py 输出的 data.intent 中，browse、query、upload、delete、manage 与同名 references/<module>/、scripts/<module>/ 一致。read 仅为意图分类标签（匹配「读取/总结文件」等话术），不存在 references/read/；一旦 intent 为 read，路由与加载必须与 query 相同，使用 references/query/ 与 scripts/query/。

参数提取规则

1. 关键词提取：自动识别引号、括号内内容及"xxx文件"格式
2. 路径解析：支持"产品资料-慷彼申"格式的层级路径
3. 指代处理：理解"这个文件"、"它"等指代，自动关联上下文
4. 数字提取：识别版本号、页码等数字参数

上下文管理

• 会话历史：保留最近10条对话记录
• 当前目录：记录用户正在浏览的目录（id + name）
• 最后文件：记录用户最后操作的文件（id + name）
• 当前项目：记录用户当前操作的项目（id + name）

多轮对话支持

触发脚本

触发流程图

用户输入
    ↓
意图识别 (intent-matcher.py)
    ↓
参数提取 (parameter-extractor.py)
    ↓
上下文补全 (context-manager.py)
    ↓
┌──────────────────────┐
│ 参数是否完整？       │
└──────────────────────┘
    ↓
    ├─ 是 → 路由到对应模块
    │         ↓
    │     执行脚本
    │         ↓
    │     更新上下文
    │         ↓
    │     返回结果
    │
    └─ 否 → 生成追问提示
              ↓
          返回追问

模块路由与能力索引：

能力树：

cms-docdb/
├── SKILL.md
├── references/
│   ├── browse/README.md
│   ├── query/README.md
│   ├── upload/README.md
│   ├── delete/README.md
│   ├── manage/README.md
│   └── share/README.md
└── scripts/
    ├── browse/
    │   ├── browse.py
    │   ├── get-level1-folders.py
    │   ├── get-personal-project-id.py
    │   ├── get-project-list.py
    │   ├── get-recent-files.py
    │   ├── get-my-upload-records.py
    │   └── get-uploadable-list.py
    ├── query/
    │   ├── search.py
    │   ├── get-full-content.py
    │   ├── get-download-info.py
    │   ├── download-file.py
    │   ├── get-file-content.py
    │   └── batch-get-content.py
    ├── upload/
    │   ├── upload-content.py
    │   ├── save-file-by-path.py
    │   ├── save-file-by-parent-id.py
    │   ├── upload-whole-file.py
    │   ├── check-slice.py
    │   ├── register-slice.py
    │   ├── merge-resource.py
    │   ├── create-folder.py
    │   └── get-file-download-info.py
    ├── delete/
    │   └── delete-file.py
    ├── manage/
    │   ├── update-file-name.py
    │   ├── move-file.py
    │   ├── update-file-property.py
    │   ├── update-file-version.py
    │   ├── get-version-list.py
    │   ├── get-last-version.py
    │   └── finalize-version.py
    └── share/
        ├── search-emp-by-name.py
        ├── get-my-share-permissions.py
        ├── upsert-file-share-grants.py
        ├── get-file-shares.py
        ├── get-share-url.py
        └── revoke-file-share-grants.py

文档对齐：Open API 契约以 dev-guide/02.产品业务AI文档/知识库/（v2.3+）为准；新增 1.15 getMyUploadRecords、1.9 createFolder、6.2.1 revokeFileShareGrants 均已提供对应脚本。