cms-docdb — 索引
本文件提供能力边界、路由规则与使用约束。详细说明见 references/，实际执行见 scripts/。
当前版本: 1.0.1
接口版本: 所有业务接口统一使用 /open-api/* 前缀，鉴权类型全部为 appKey。
能力概览（5 块能力）：
browse：发现可用空间、获取个人空间 ID、浏览目录结构、查看最近上传query：搜索文件，找到文件后获取内容、下载链接或预览链接upload：新建文件——上传纯文本或物理文件到知识库（仅用于新建）delete：删除指定文件（高风险，需用户确认）manage：重命名/移动文件；更新已有文件内容（版本管理）；查看历史版本；版本定稿
统一规范：
- 鉴权依赖：
cms-auth-skills/SKILL.md - 运行日志：
.cms-log/
授权依赖：
- 需要鉴权时先读取
cms-auth-skills/SKILL.md - 如果未安装，先安装依赖，再继续执行
输入完整性规则（强制）：
- 浏览目录必须提供 parentId（根目录传 0）或 projectId
- 搜索文件必须提供关键词
- 上传文件必须提供文件名和内容（纯文本）或 resourceId（物理文件）
- 删除/重命名/移动文件必须提供 fileId
- 版本更新必须提供目标文件的 fileId（纯文本）或文件 id + projectId + resourceId（物理文件）
版本管理强制规则（最高优先级）：
- 禁止直接覆盖已有文件内容：对已存在文件的任何内容更新，必须通过版本管理接口保存为新版本，不得使用覆盖方式。直接覆盖无法溯源，违反本规则。
- 保存前必须判断文件是否已存在：执行任何"保存/上传/更新"动作前，必须先通过
searchFile或getChildFiles确认目标文件是否已存在。- 若不存在：路由到
upload模块走新建流程 - 若已存在：路由到
manage模块走版本更新流程，禁止新建同名文件或覆盖
- 若不存在：路由到
- 不得询问用户是否覆盖：版本管理是默认且唯一的更新方式，无需向用户确认，直接执行版本更新。
建议工作流（简版）：
- 先读取
SKILL.md，确认能力边界和限制 - 根据用户意图定位模块，读取对应
references/<module>/README.md - 确认具体动作后，读取
scripts/<module>/README.md了解脚本入参 - 保存/上传前必须执行存在性检查：通过
search.py或browse.py确认目标文件是否已存在。已存在则切换为版本更新流程（manage 模块），不存在才新建（upload 模块） - 补齐用户必需输入
- 执行对应脚本
脚本使用规则（强制）：
- 每个动作必须有对应脚本：不允许"暂无脚本"
- 脚本可独立执行：所有
scripts/下的脚本均可脱离 AI Agent 直接在命令行运行 - 先读模块说明再执行：执行脚本前，必须先阅读对应模块的
references/<module>/README.md - 鉴权一致：涉及 appKey 时，统一依赖
cms-auth-skills
意图路由与加载规则（强制）：
- 先路由再加载：必须先判定模块，再打开该模块的
references/<module>/README.md - 先读说明再调用：在执行前，必须加载对应模块说明
- 脚本必须执行：所有接口调用必须通过脚本执行，不允许跳过
- 不猜测：若意图不明确，必须追问澄清
宪章（必须遵守）：
- 只读索引：
SKILL.md只描述"能做什么"和"去哪里读"，不写具体接口参数 - 按需加载：默认只读
SKILL.md+cms-auth-skills/SKILL.md，只有触发某模块时才加载该模块的references与scripts - 对外克制：对用户只输出"可用能力、必要输入、结果链接或摘要"，不暴露鉴权细节与内部字段
- 素材优先级：用户给了文件或 URL，必须先提取内容再确认，确认后才触发生成或写入
- 生产约束：仅允许生产域名与生产协议，不引入任何测试地址
- 危险操作：删除文件等高风险操作应礼貌确认，不直接执行
- 脚本语言限制：所有脚本必须使用 Python 编写
- 重试策略：出错时间隔 1 秒、最多重试 3 次，超过后终止并上报
- 禁止无限重试：严禁无限循环重试
- 输出规范：脚本输出优先按
resultCode、resultMsg、data读取，对用户输出最小必要信息：摘要/必要输入/链接，不回显完整 JSON 响应
模块路由与能力索引：
| 用户意图 | 模块 | 能力摘要 | 模块说明 | 脚本 |
|---|---|---|---|---|
| "帮我看看这个目录下有什么"、"浏览一下xxx文件夹"、"帮我看看知识库里有什么"、"查看某个目录的内容" | browse | 发现空间、浏览目录结构、查看最近上传 | ./references/browse/README.md | ./scripts/browse/browse.py |
| "找一下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 | 见 ./scripts/manage/README.md（按意图选择对应脚本） |
能力树：
cms-docdb/
├── SKILL.md
├── references/
│ ├── browse/README.md
│ ├── query/README.md
│ ├── upload/README.md
│ ├── delete/README.md
│ └── manage/README.md
└── scripts/
├── browse/
│ ├── README.md
│ ├── browse.py
│ ├── get-level1-folders.py
│ ├── get-personal-project-id.py
│ ├── get-project-list.py
│ ├── get-recent-files.py
│ └── get-uploadable-list.py
├── query/
│ ├── README.md
│ ├── search.py
│ ├── get-full-content.py
│ ├── get-download-info.py
│ ├── get-file-content.py
│ └── batch-get-content.py
├── upload/
│ ├── README.md
│ ├── 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/
│ ├── README.md
│ └── delete-file.py
└── manage/
├── README.md
├── update-file-property.py
├── update-file-version.py
├── get-version-list.py
├── get-last-version.py
└── finalize-version.py