简档云api技能

概述

简档云（filelib）开放接口

通过开放 API 管理「简档云」中的文件夹与文件，并支持协作空间（团队共享目录）。生产地址：https://filelib.tgnsz.com（唯一接口地址，不可使用本地地址）。

权限模型：

• 个人文件：仅能操作自己创建的文件夹与文件。
• 协作空间：Token 用户若为空间管理员或成员，可对该空间内的文件夹/文件做完整读写（新建、上传、查询、修改、删除）；不提供成员管理类接口。

前置条件：先提供 API Token

简档云只认 API Token，不认管理端 Session Cookie。任何操作之前都必须先拿到 Token：

• 在管理端「API Token」设置页创建、查看、吊销；

提供 Token 的三种方式（按优先级）：

1. 命令行参数 --token ff_xxx
2. 环境变量 FILELIB_TOKEN=ff_xxx
3. 在交互终端直接运行 CLI 时按提示输入（脚本会用隐藏输入方式询问）

没有 Token 时脚本会直接报错并提示，不会静默执行。

快速开始

export FILELIB_TOKEN=ff_xxx
# 可选，默认即生产地址
export FILELIB_BASE_URL=https://filelib.tgnsz.com

python3 scripts/filelib.py categories list --all
python3 scripts/filelib.py files upload --title 示例页 --category-id 1 --file ./page.html

# 不想真的发请求时，加 --dry-run 只打印请求预览（无需 Token）
python3 scripts/filelib.py files replace 12 --file ./page-v2.html --dry-run

--token / --base-url 也可作为命令行参数覆盖环境变量。

操作速查

协作空间 spaces

• spaces list — 列出当前 Token 可访问的协作空间（返回 id / root_category_id / role）
• spaces categories <space_id> — 扁平列出空间内全部文件夹
• spaces files <space_id> [--file-type html|markdown|image] — 列出空间内全部文件

文件夹 categories

• categories list [--parent-id ID] [--all] — 列目录；--all 返回个人扁平全量（不含协作空间）
• categories path <id> — 根→该文件夹的面包屑路径
• categories create --name 名称 [--parent-id ID|null] — 新建（null/root = 个人根下；传空间文件夹 ID 即在空间内建）
• categories rename <id> [--name 新名] [--parent-id ID|null] — 改名/移动
• categories delete <id> — 删除空文件夹（非空返回 400）

文件 files

• files list [--category-id ID] [--file-type html|markdown|image] — 列文件
• files upload --title 标题 --category-id ID --file 路径 [--slug] [--file-type] [--access-password 4位] — 上传（multipart，支持 .html/.md/.png/.jpg/.jpeg/.gif/.webp，≤10MB）
• files update <id> [--title] [--slug] [--category-id ID] [--access-password 密码|--clear-password] — 改元数据（不产生版本）
• files replace <id> --file 路径 — 替换内容（产生新版本，旧版保留）
• files delete <id> — 删除文件及版本

使用说明（典型场景）

下面按真实场景给出端到端命令。所有命令都可先加 --dry-run 预览请求、确认无误后再去掉执行。

场景 0：进入协作空间并操作空间内文件

# 1) 列出可访问的协作空间，记下空间的 id 与 root_category_id（假设 id=7，root=50）
python3 scripts/filelib.py spaces list
# 2) 直接列出空间内全部文件夹 / 文件
python3 scripts/filelib.py spaces categories 7
python3 scripts/filelib.py spaces files 7 --file-type image
# 3) 在空间的 root_category_id 下建子目录、上传文件（与个人文件用法完全相同）
python3 scripts/filelib.py categories create --name 2026活动 --parent-id 50
python3 scripts/filelib.py files upload --title 封面 --category-id 50 --file ./cover.png

场景 1：查看目录结构，找到目标文件夹 ID

# 列出全部文件夹（扁平），拿到每个文件夹的 id / parent_id
python3 scripts/filelib.py categories list --all
# 只看某个文件夹下的子目录
python3 scripts/filelib.py categories list --parent-id 1
# 查看某文件夹从根到自身的路径（面包屑）
python3 scripts/filelib.py categories path 12

场景 2：新建文件夹并上传一个 HTML 页面

# 1) 在根下建「活动页」文件夹（记下返回的 id，假设为 20）
python3 scripts/filelib.py categories create --name 活动页
# 2) 上传 HTML 到该文件夹，并设 4 位访问密码
python3 scripts/filelib.py files upload 
  --title 双十一活动 --category-id 20 
  --file ./sale.html --access-password ab12
# 返回的 url / slug 即公开访问地址（访客输入密码即可看）
# 同样支持上传图片（.png/.jpg/.jpeg/.gif/.webp，最大 10MB）
python3 scripts/filelib.py files upload 
  --title 活动封面 --category-id 20 
  --file ./cover.png

场景 3：更新一个已发布页面的内容（保留历史版本）

# 先按文件夹或类型找到文件 id
python3 scripts/filelib.py files list --category-id 20 --file-type html
# 用 replace 替换内容 —— 产生新版本，旧版仍可回溯
python3 scripts/filelib.py files replace 35 --file ./sale-v2.html

场景 4：只改元数据（改标题、换文件夹、增减密码，不动内容）

# 改标题 + 移动到另一个文件夹（不产生版本）
python3 scripts/filelib.py files update 35 --title 双十一返场 --category-id 21
# 清除访问密码，让页面公开可访问
python3 scripts/filelib.py files update 35 --clear-password

场景 5：清理（删除文件、再删空文件夹）

# 先删文件（连同其版本对象一起删除）
python3 scripts/filelib.py files delete 35
# 文件夹清空后才能删除，否则返回 400
python3 scripts/filelib.py categories delete 20

提示：--token / --base-url 可在任意命令上覆盖环境变量；日常批量操作建议先用 --dry-run 跑一遍确认请求体正确。

关键约束（易错点）

1. 文件必须挂在文件夹下：上传 POST /api/open/files 必须带已存在的 category_id，不能在根目录直接挂文件（个人根或协作空间的 root_category_id）。没有目标文件夹时，先用 categories create 建一个。
2. 支持 HTML / Markdown / 图片：file_type 可取 html、markdown、image；上传支持 .html/.htm/.md/.markdown/.png/.jpg/.jpeg/.gif/.webp，图片单文件最大 10MB。
3. replace 产版本，PATCH 不产版本：replace 生成新版本并保留旧版；update（PATCH 元数据）只改标题/slug/密码/归属，不动内容版本。
4. 删除文件夹须先清空：categories delete 仅删空目录，含子目录或文件时返回 400，需先删文件/子目录。
5. parent_id: null 语义：create/rename 传 null（CLI 用 null 或 root）表示移到/建在根下；update 的 access_password: null 表示清除密码（CLI 用 --clear-password）。
6. 公开访问不走 Token：上传后访客通过响应的 url 或 /{slug} 访问当前版本；设了访问密码需按页面提示输入。

完整接口规范

详细的请求/响应字段、数据模型（CategoryOut / SpaceOut / FileOut）与错误码，见 [references/api_docs.md](references/api_docs.md)。需要拼原始 HTTP 请求或确认字段语义时先读它。