简档云开放接口

当你需要把「简档云」作为静态站点后端、团队共享资源池，或者在自动化流水线中管理 HTML / Markdown / 图片时，手动上传和改名显然不可持续。这个技能把简档云开放 API 包装成一套 CLI 命令，让文件夹结构、文件内容和访问密码都能通过脚本直接控制，而不必在管理端反复点选。

核心能力与关键步骤

这套命令围绕协作空间、文件夹和文件三个层级展开。执行任何操作前，脚本只认 API Token，不使用管理端 Session Cookie。Token 可以通过 --token、环境变量 FILELIB_TOKEN 或交互式输入提供；缺失时脚本会直接报错并提示，不会静默执行。

日常使用可以按下面的路径推进：

• 列出空间与目录：spaces list 返回当前 Token 可访问的团队空间，spaces categories 则以扁平结构列出空间内的文件夹，方便快速拿到 id。
• 建目录并上传：先用 categories create --name 名称 [--parent-id ID] 建好落点，再用 files upload --category-id ID --file 路径 上传文件。files list 可以按 --file-type 过滤 html、markdown、image。
• 修改与替换：files update 只调整标题、slug、密码或归属文件夹，不会产生新版本；files replace 则替换文件内容，生成新版本并保留旧版，适合已发布页面需要回滚的场景。
• 安全预览：所有命令都支持 --dry-run，在真正发送请求前预览参数，确认无误后再去掉该参数执行。

适用边界与注意点

这套 API 并不是通用的团队权限管理工具。协作空间只提供文件读写接口，不包含成员管理类操作；Token 用户的权限由其在空间中的角色（管理员或成员）决定。

几个容易踩坑的地方需要特别留意：

1. 文件必须挂在文件夹下。上传时必须提供已存在的 category_id，不能把文件直接放在个人根目录或空间的 root_category_id 下。没有目标文件夹时，要先执行 categories create。
2. replace 与 update 语义不同。前者产生新版本并保留历史，后者只改元数据；想保留发布历史就别误用 update 覆盖内容。
3. 删除文件夹前必须先清空。categories delete 遇到非空目录会返回 400；正确顺序是先 files delete，再删空文件夹。
4. 上传格式有限。支持 .html/.htm/.md/.markdown 和 .png/.jpg/.jpeg/.gif/.webp，图片单文件最大 10MB。
5. 公开访问不需要 Token。上传成功后，访客可以通过响应里的 url 或 /{slug} 访问当前版本；如果设置了访问密码，需要按页面提示输入。

更细的请求 / 响应字段、数据模型与错误码可以查阅技能附带的 references/api_docs.md，需要拼原始 HTTP 请求时先看那份规范。