--- name: cms-docdb description: 公司内部知识库—目录浏览与搜索，读全文或下载/预览；上传与归档；已存在文件用新版本与定稿更新（禁止覆盖），删除须确认；Open API 仅允许通过本仓库脚本执行。 metadata: skillcode: cms-docdb github: https://github.com/liuyanhua1222/cms-docdb dependencies: - cms-auth-skills openclaw: requires: bins: - python3 - python --- # cms-docdb — 索引 OpenClaw 技能 **`name`** 为 `cms-docdb`，与仓库目录名和 **`skillcode`** 保持一致。本技能用于访问公司内部知识库（康哲/玄关/德镁知识库）。 本文件提供能力边界与路由规则。详细说明见 `references/`，实际执行见 `scripts/`。 **当前版本**: 1.0.7 **接口版本**: 所有业务接口统一使用 `/open-api/*` 前缀，鉴权类型全部为 `appKey`。 **能力概览（5 块能力）**： - `browse`：发现可用空间、获取个人空间 ID、浏览目录结构、查看最近上传 - `query`：搜索文件，找到文件后获取内容、下载链接或预览链接 - `upload`：新建文件——上传纯文本或物理文件到 **康哲/玄关/德镁知识库**（内部应用侧；仅用于新建） - `delete`：删除指定文件（高风险，需用户确认） - `manage`：重命名/移动文件；更新已有文件内容（版本管理）；查看历史版本；版本定稿 ## 适用范围与歧义排除（技能门控，强制） - **本 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//README.md` 3. 确认具体动作后，在 `references//README.md` 中查看脚本清单、入参与运行方式 4. **保存/上传前必须执行存在性检查**：通过 `search.py` 或 `browse.py` 确认目标文件是否已存在。已存在则切换为版本更新流程（manage 模块），不存在才新建（upload 模块） 5. 补齐用户必需输入 6. 执行对应脚本 脚本使用规则（强制）： 1. **每个动作必须有对应脚本**：不允许"暂无脚本" 2. **脚本可独立执行**：所有 `scripts/` 下的脚本均可脱离 AI Agent 直接在命令行运行 3. **先读模块说明再执行**：执行脚本前，必须先阅读对应模块的 `references//README.md` 4. **鉴权一致**：涉及 appKey 时，统一依赖 `cms-auth-skills` 意图路由与加载规则（强制）： 1. **先路由再加载**：必须先判定模块，再打开该模块的 `references//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**。 | 模块 | 触发词模式 | |-----|-----------| | `browse` | "知识库"、"打开知识库"、"打开公司在线知识库"、"打开康哲/玄关/德镁知识库"、"浏览文件夹"、"查看目录"、"知识库里有什么"、"目录结构"、"空间列表"、"项目列表" | | `query` | "查询知识库中的…"、"搜索知识库里的…"、"搜索xxx"、"查询xxx"、"查找xxx"、"检索xxx"、"帮我找xxx"、"搜索一下xxx"、"读取xxx"、"阅读xxx"、"查看xxx内容"、"打开文件"、"总结文件"、"提取信息" | | `upload` | "上传到康哲/玄关/德镁知识库"、"保存到康哲/玄关/德镁知识库"、"上传到知识库"、"保存到知识库"、"归档文件"、"新建文件" | | `delete` | "删除文件"、"移除文件"、"删掉xxx" | | `manage` | "重命名xxx"、"移动文件"、"更新内容"、"版本管理"、"历史版本"、"定稿" | **意图标签与模块目录（强制）**：`intent-matcher.py` 输出的 `data.intent` 中，`browse`、`query`、`upload`、`delete`、`manage` 与同名 `references//`、`scripts//` 一致。`read` 仅为意图分类标签（匹配「读取/总结文件」等话术），**不存在** `references/read/`；一旦 `intent` 为 `read`，路由与加载必须与 **`query`** 相同，使用 `references/query/` 与 `scripts/query/`。 ### 参数提取规则 1. **关键词提取**：自动识别引号、括号内内容及"xxx文件"格式 2. **路径解析**：支持"产品资料-慷彼申"格式的层级路径 3. **指代处理**：理解"这个文件"、"它"等指代，自动关联上下文 4. **数字提取**：识别版本号、页码等数字参数 ### 上下文管理 - **会话历史**：保留最近10条对话记录 - **当前目录**：记录用户正在浏览的目录（id + name） - **最后文件**：记录用户最后操作的文件（id + name） - **当前项目**：记录用户当前操作的项目（id + name） ### 多轮对话支持 | 场景 | 示例 | 处理方式 | |-----|------|---------| | 指代解析 | "读取这个文件" | 自动补全最后操作的文件ID | | 路径继承 | "查看上一级" | 使用当前目录上下文 | | 连续操作 | "搜索xxx" → "读取它" → "保存新版本" | 上下文链式传递 | ### 触发脚本 | 脚本 | 功能 | |-----|------| | `intent-matcher.py` | 意图识别和关键词提取 | | `context-manager.py` | 上下文管理和状态维护 | | `parameter-extractor.py` | 参数提取和缺失提示生成 | ### 触发流程图 ```text 用户输入 ↓ 意图识别 (intent-matcher.py) ↓ 参数提取 (parameter-extractor.py) ↓ 上下文补全 (context-manager.py) ↓ ┌──────────────────────┐ │ 参数是否完整？ │ └──────────────────────┘ ↓ ├─ 是 → 路由到对应模块 │ ↓ │ 执行脚本 │ ↓ │ 更新上下文 │ ↓ │ 返回结果 │ └─ 否 → 生成追问提示 ↓ 返回追问 ``` 模块路由与能力索引： | 用户意图 | 模块 | 能力摘要 | 模块说明 | 脚本 | |---|---|---|---|---| | "打开公司在线知识库"、"打开康哲/玄关/德镁知识库"、"浏览一下xxx文件夹"、"知识库里有什么"、"查看某个目录的内容"、"目录结构" | `browse` | 发现空间、浏览目录结构、查看最近上传 | `./references/browse/README.md` | `./scripts/browse/browse.py` | | "查询知识库中的…"、"搜索知识库里的…"、"搜索xxx"、"查询xxx"、"查找xxx"、"看看这个文件的内容"、"帮我读取xxx文件"、"帮我总结一下xxx文件" | `query` | 搜索文件并读取内容、下载链接或预览链接 | `./references/query/README.md` | `./scripts/query/search.py` | | "存到康哲/玄关/德镁知识库"、"上传到知识库"、"上传xxx到知识库"、"把这份文档归档"、"帮我保存这个文件" | `upload` | 新建文件到内部知识库（仅用于新建，已存在则路由到 manage 走版本更新） | `./references/upload/README.md` | `./scripts/upload/upload-content.py` | | "帮我把xxx删了"、"删除xxx文件"、"把xxx文件移除" | `delete` | 删除指定文件（高风险，需确认） | `./references/delete/README.md` | `./scripts/delete/delete-file.py` | | "帮我把xxx重命名"、"把xxx改名为yyy"、"把这个文件移到xxx文件夹"、"更新一下知识库里的xxx"、"把最新内容存进去"、"这个文档有更新，存一下"、"查看xxx文件的历史版本"、"把这个版本定稿" | `manage` | 重命名/移动文件；更新已有文件内容（版本管理）；查看历史版本；版本定稿 | `./references/manage/README.md` | 见 `./references/manage/README.md`（按意图选择对应脚本） | 能力树： ```text cms-docdb/ ├── SKILL.md ├── references/ │ ├── browse/README.md │ ├── query/README.md │ ├── upload/README.md │ ├── delete/README.md │ └── manage/README.md └── scripts/ ├── browse/ │ ├── browse.py │ ├── get-level1-folders.py │ ├── get-personal-project-id.py │ ├── get-project-list.py │ ├── get-recent-files.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 │ └── 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 ```