QuickForm CLI 接口说明

供命令行、扣子编程、OpenClaw 等工具自动化创建与查看数据任务，无需打开网页。

1. 基础信息

Base URL：https://quickform.cn（若自建部署，请替换为您自己的站点根地址）
认证方式：所有 CLI 接口均在请求体中传递 用户名 + 密码，或 用户名 + 授权码（auth_code）（在个人中心「QFLink授权码」生成，类似 QQ 邮箱授权码），不依赖 Cookie/Session
请求格式：支持 JSON（Content-Type: application/json）或表单（application/x-www-form-urlencoded）
响应格式：一般为 JSON。
安全限制：为保护账号安全，短时间内连续认证失败可能会被暂时限制请求频率（返回 429，并包含 retry_after 秒数）。
教师认证：CLI 与 QFLink 仅对已认证教师开放（管理员除外）。未认证账号无论使用 用户名+密码 还是 QFLink 授权码 调用 /cli/*、/mcp/*（含 POST /cli/qflink/verify）均返回 403，code: certification_required，并附带 certification_url 与说明；个人中心生成 QFLink 授权码亦需先完成认证。

用户名含中文、特殊 Unicode

请使用 UTF-8 编码发送请求；JSON 方式（Content-Type: application/json）对中文最稳妥。
表单方式请使用 application/x-www-form-urlencoded; charset=utf-8（或依赖客户端默认 UTF-8）。
服务端会对 username 做 Unicode NFC 规范化、去除首尾空白与常见零宽字符，并尝试纠正常见的「UTF-8 被误按 Latin-1 解码」乱码，以便与站内已注册用户名一致。
密码不做空白裁剪，请原样传输。

说明：本文档涵盖两类能力
- CLI 接口（/cli/*)：给“校园版/教师版迁移、脚本、大模型工具”调用的账号密码接口（无需 Cookie）。
- 网页端「任务导出 / 导入」：站内按钮触发的导出 ZIP / 导入 ZIP|JSON（需要网页登录）。

2. 获取当前用户信息 `POST /cli/getuser`

使用用户名与密码认证，返回账号资料（不写 Session，适合脚本判断认证状态）。

请求参数

参数	必填	说明
username	是	用户名（也可用已绑定的邮箱/手机号登录）
password	与 auth_code 二选一	密码
auth_code	与 password 二选一	QFLink 授权码（`qf` + 32 位十六进制）

成功响应（200）

{
  "success": true,
  "user": {
    "id": 12,
    "username": "teacher1",
    "email": "teacher@example.com",
    "email_verified": true,
    "phone": "13800138000",
    "school": "某某中学",
    "school_province": "浙江省",
    "role": "user",
    "is_certified": true,
    "certified_at": "2025-03-01 10:00:00",
    "task_limit": 3,
    "created_at": "2024-09-01 08:00:00"
  }
}

说明：

school 为个人资料中的单位/学校。
is_certified 为是否已通过教师认证。
未绑定真实邮箱时，email 可能为空字符串（占位邮箱不返回）。

错误响应

400：缺少参数
401：用户名或密码错误
429：认证尝试过于频繁

示例（curl）

curl -X POST "https://quickform.cn/cli/getuser" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password"}'

（兼容旧路径：POST /mcp/getuser。）

2.1 QFLink 校验 `POST /cli/qflink/verify`

教师版/校园版连接在线服务器时使用；认证参数同 getuser，另可加 client（teacher / school）。

成功时返回 user 与 qflink.online_base、qflink.cli_endpoints。详见 QFLINK.md。

未认证教师（用户名+密码或授权码）示例响应（403）：

{
  "success": false,
  "code": "certification_required",
  "message": "该账号尚未完成教师认证，无法使用 QFLink / CLI 连接在线版。用户名+密码与 QFLink 授权码均不可用，请先完成教师认证。",
  "is_certified": false,
  "certification_url": "https://quickform.cn/certification/request",
  "hint": "请登录在线版个人中心提交「教师认证」申请，审核通过后再从校园版/教师版重试。"
}

3. 增加数据任务 `POST /cli/add`

创建一条新的数据任务，并返回用于提交数据的 apiid。

请求参数

参数	必填	说明
username	是	用户名
password	是	密码
task_name	是	任务名称
task_intro	否	任务介绍/描述

（兼容字段：title 等同 task_name，description 等同 task_intro。）

成功响应（200）

{
  "success": true,
  "apiid": "a1b2c3d4ef"
}

apiid 即该任务的 API 标识，后续提交数据、拉取数据都使用此 id。

错误响应

400：缺少必填参数 → { "success": false, "message": "缺少 username 或 password" } 等
401：用户名或密码错误 → { "success": false, "message": "用户名或密码错误" }
403：已达任务数量上限 → { "success": false, "message": "已达任务数量上限（当前 N 个）..." }
403：从第二个任务起需先绑定/验证邮箱 → { "success": false, "code": "email_not_bound" | "email_not_verified", "message": "..." }
500：服务器异常 → { "success": false, "message": "..." }

示例（curl）

# JSON
curl -X POST "https://quickform.cn/cli/add" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password","task_name":"课堂签到表","task_intro":"本周签到"}'

# 表单
curl -X POST "https://quickform.cn/cli/add" \
  -d "username=teacher1&password=your_password&task_name=课堂签到表&task_intro=本周签到"

4. 查看数据任务列表 `POST /cli/list`

获取当前账号下所有数据任务及其 apiid 与名称。

请求参数

参数	必填	说明
username	是	用户名
password	是	密码

成功响应（200）

{
  "success": true,
  "tasks": [
    { "apiid": "a1b2c3d4ef", "name": "课堂签到表" },
    { "apiid": "x9y8z7w6vu", "name": "问卷回收" }
  ]
}

错误响应

400：缺少 username 或 password
401：用户名或密码错误

示例（curl）

curl -X POST "https://quickform.cn/cli/list" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password"}'

5. 查看单个任务详情（用于迁移导出端）`POST /cli/show`

通过 apiid 获取任务的基本信息与附件（用于“校园版/教师版”从在线版拉取任务并下载 HTML 附件）。

请求参数

参数	必填	说明
username	是	用户名
password	是	密码
apiid	是	任务 API 标识
include_data	否	`true` 时额外返回 `submissions` 数组（仅任务所有者；公开任务不可用）。不计入 `/all` 配额，禁读模式下仍可用。

成功响应（200）

{
  "success": true,
  "apiid": "a1b2c3d4ef",
  "name": "课堂签到表",
  "intro": "任务描述（可空）",
  "tutorial": "教程链接（可空）",
  "share_url": "分享链接（可空）",
  "attachments": [
    { "name": "index.html", "url": "https://quickform.cn/static/uploads/xxxxxxxx.html" }
  ],
  "submissions": [],
  "total_submissions": 0
}

（无 include_data 时不含 submissions / total_submissions。）

attachments 重要要求（迁移导出端必读）

attachments 应包含该任务的 HTML/HTM 页面附件（至少 1 个也可以）。
attachments[].url 必须是 无需 Cookie/Session、无需登录即可下载的直链（否则导入端无法下载并改写 HTML 内的 API 地址）。
导入端通常只处理 .html/.htm；你也可以返回其它类型，但不会被迁移处理。

错误响应

400：缺少参数
401：用户名或密码错误
404：任务不存在或无权限

示例（curl）

curl -X POST "https://quickform.cn/cli/show" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password","apiid":"a1b2c3d4ef"}'

含提交数据（所有者，JSON 内联，适合条数较少时）：

curl -X POST "https://quickform.cn/cli/show" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password","apiid":"a1b2c3d4ef","include_data":true}'

5.1 导出任务迁移 ZIP `POST /cli/export_task`

与网页「导出任务」相同，返回 application/zip 附件（v2 仅结构，v3 含 submissions.json 与附件目录）。

权限：任务所有者或管理员
不计入 GET /api/<apiid>/all 的读取次数与流量配额（适用于配额已用尽时备份/迁移）
禁读模式下仍允许导出（对外 API 仍禁读）
需启用 TASK_MIGRATION_ACTIVE（默认开启）

请求参数

参数	必填	说明
username	是	用户名
password	是	密码
apiid	是	任务 API 标识（也可用 `task_id` / `id`）
include_data	否	`true` 时导出含全部提交数据（默认 `false` 仅 HTML+manifest）

成功响应（200）

Content-Type：application/zip
Content-Disposition：附件文件名
响应头：X-QuickForm-Export-Include-Data、X-QuickForm-Task-Apiid

错误响应

400 / 401 / 404：同 /cli/show
403：禁读且策略不允许（当前站内导出通道对所有者开放）
413：ZIP 超过 TASK_MIGRATION_ZIP_MAX_BYTES
503：任务迁移功能未启用

示例（curl，含数据保存为文件）

curl -X POST "https://quickform.cn/cli/export_task" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password","apiid":"a1b2c3d4ef","include_data":true}' \
  -o task_migration.zip

6. 上传 HTML 文件 `POST /cli/upload`

上传单个 HTML/HTM 文件，并绑定到某个已创建的任务（用于迁移导入端：后续需要带 taskid 的可访问页面）。

说明：CLI 上传时必须指定目标任务（apiid 推荐 / task_id 或 taskid / id）。否则会出现“未走教师认证/任务权限校验就拿到可访问公网 HTML”的问题。

请求方式

Content-Type：multipart/form-data
参数：
username、password（表单字段）
apiid（推荐）/ task_id（或 taskid）/ id（数据库ID，二选一：三者其一即可）
file（文件字段，仅支持 .html / .htm，单文件最大 4MB）

成功响应（200）

{
  "success": true,
  "url": "https://quickform.cn/uploads/xxxxxxxx.html?taskid=a1b2c3d4ef",
  "filename": "xxxxxxxx.html"
}

url：该文件的公网访问地址，可直接在浏览器或前端 iframe 中打开。
url：在未通过教师认证（或未满足任务 HTML 审核条件）时，访问页面会显示“审核中/未通过”提示页，不会直接返回原始 HTML。
filename：服务器保存后的文件名（随机命名，避免冲突）。

若你需要该上传结果马上用于迁移导入/展示，请确保当前账号已满足“教师认证通过/任务 HTML 可访问”条件。

错误响应

400：缺少参数、未选择文件、未提供目标任务参数（apiid/task_id/id 任意一个）、或文件格式/大小不符合（仅允许 .html/.htm，单文件 ≤ 4MB）→ { "success": false, "message": "..." }
401：用户名或密码错误
403：目标任务不存在或无权限（非任务所有者/无管理员权限）
500：服务器保存失败

示例（curl）

curl -X POST "https://quickform.cn/cli/upload" \
  -F "username=teacher1" \
  -F "password=your_password" \
  -F "apiid=a1b2c3d4ef" \
  -F "file=@/path/to/your/page.html"

7. 使用 apiid 提交与获取数据

拿到 apiid 后，与网页端一致：

提交一条数据：POST /api/<apiid>
Body：JSON 对象，例如 {"name":"张三","score":85}
成功：{ "message": "提交成功", "status": "success" }
获取全部提交数据：GET /api/<apiid>/all
返回：{ "submissions": [ ... ], "total_submissions": N }
简要查询（最新 3 条）：GET /api/<apiid>
返回：含 submissions、total_submissions、task_id、task_title 等

高并发与网页优先（自建部署）：当 POST /api/<apiid>、GET /api/<apiid>/all 等数据通道瞬时占满 Waitress 工作线程时，进程内可对上述路由施加有界并发。POST /api/<apiid>（JSON 或 application/x-www-form-urlencoded，非 multipart）在槽位已满时默认将已解析数据写入本地临时队列并返回 202（queued: true、spool_id），后台线程在有空槽时写入数据库；若关闭落盘（QF_API_POST_SPOOL_ON_BUSY=0）或队列目录积压超过上限，则仍返回 503（含 retry_after）。GET /api/<apiid>/all 等仍以 503 退避为主。环境变量：QF_BULK_API_MAX_INFLIGHT（0 关闭）、QF_WEB_IN_FLIGHT_RESERVE、QF_BULK_API_RETRY_AFTER、QF_API_POST_SPOOL_*（见 core/api_submit_spool.py）。详见 core/bulk_api_gate.py 注释。

完整提交地址示例：https://quickform.cn/api/a1b2c3d4ef

8. 与扣子 / OpenClaw 的自动化流程

创建任务：调用 POST /cli/add，传入用户名、密码、任务名称（及可选介绍），得到 apiid。
配置提交地址：在扣子/OpenClaw 应用中将「数据提交接口」配置为：
https://quickform.cn/api/<apiid>
例如：https://quickform.cn/api/a1b2c3d4ef
应用内提交：用户在前端填写的数据以 JSON 形式 POST 到上述地址即可写入 QuickForm。
查询任务列表：需要展示或选择「往哪个任务提交」时，可调用 POST /cli/list 获取当前用户下所有 apiid 与名称。

这样即可在不打开 QuickForm 网页的情况下，完成任务的创建、列表查看与数据提交地址的配置。

9. 网页端「任务导出 / 导入」（站内功能）

如果你是在网页里操作（不是脚本/CLI），请看这里。

8.1 开关

管理员可用环境变量控制是否启用：

启用：默认即启用，或设置 TASK_MIGRATION_ACTIVE=1
关闭：设置 TASK_MIGRATION_ACTIVE=0

8.2 导出任务（ZIP）

入口：任务详情页 / 仪表盘
「导出任务」：仅任务结构与 HTML（v2）
「导出含数据」：供校园版迁移，含全部提交记录（v3）
路由：
GET /task/<task_id>/export_template — 不含提交数据
GET /task/<task_id>/export_template_with_data — 含提交数据
产物（v2）：quickform-task-migration.json、html/ 下页面文件
产物（v3，在 v2 基础上增加）：
submissions.json：提交数组，每项含 legacy_id、submitted_at、data
attachments/：多模态等字段中的附件文件（data.attachment 内 URL 已改写为包内相对路径）

环境变量（可选）：

TASK_MIGRATION_ZIP_MAX_BYTES：ZIP 总体积上限（默认 50MB）
TASK_MIGRATION_EXPORT_MAX_SUBMISSIONS：单次最多导出条数，0 表示不限制

注意：导出通常仅任务创建者/管理员可用；含数据导出走站内/CLI 所有者通道，不因「禁读」或 /all 配额用尽而拒绝（公开 API 的 /all 仍受配额限制）。在线版不负责将 v3 包导入为提交记录，由校园版自行消费 ZIP。

8.3 导入任务（ZIP 或 JSON）

入口：仪表盘/任务详情页弹窗 「导入任务」
路由：POST /task/import_template（multipart/form-data）
支持：
ZIP（v2）：由本站“任务导出”生成；导入后会分配新的 APIID，并按选项改写 HTML 内 /api/<old> → /api/<new>（可选同时替换站点根地址）。
JSON（v1）：旧版模板，仅任务基本信息，不含 HTML 与提交数据。

10. 返回数据格式小结

接口	成功时返回字段	说明
POST /cli/getuser	`success: true`, `user`	用户信息（认证、单位、邮箱等）
POST /cli/add	`success: true`, `apiid`	新任务的 API 标识
POST /cli/list	`success: true`, `tasks`	`tasks` 为 `[{ apiid, name }, ...]`
POST /cli/show	`success: true`, `attachments`	迁移导出端：返回 HTML 附件直链；`include_data` 可拉 JSON
POST /cli/export_task	ZIP 文件流	与网页「导出任务」一致；`include_data=true` 含全部数据，不计 /all 配额
POST /cli/upload	`success: true`, `url`, `filename`	上传并绑定到任务的可访问页面地址与保存文件名（未认证时返回审核提示页）

所有错误均为 success: false 且带 message 字段，便于 CLI 或技能内统一处理。

QuickForm CLI 接口说明

1. 基础信息

用户名含中文、特殊 Unicode

2. 获取当前用户信息 POST /cli/getuser

请求参数

成功响应（200）

错误响应

示例（curl）

2.1 QFLink 校验 POST /cli/qflink/verify

3. 增加数据任务 POST /cli/add

请求参数

成功响应（200）

错误响应

示例（curl）

4. 查看数据任务列表 POST /cli/list

请求参数

成功响应（200）

错误响应

示例（curl）

5. 查看单个任务详情（用于迁移导出端）POST /cli/show

请求参数

成功响应（200）

attachments 重要要求（迁移导出端必读）

错误响应

示例（curl）

5.1 导出任务迁移 ZIP POST /cli/export_task

请求参数

成功响应（200）

错误响应

示例（curl，含数据保存为文件）

6. 上传 HTML 文件 POST /cli/upload

请求方式

成功响应（200）

错误响应

示例（curl）

7. 使用 apiid 提交与获取数据

8. 与扣子 / OpenClaw 的自动化流程

9. 网页端「任务导出 / 导入」（站内功能）

8.1 开关

8.2 导出任务（ZIP）

8.3 导入任务（ZIP 或 JSON）

10. 返回数据格式小结

2. 获取当前用户信息 `POST /cli/getuser`

2.1 QFLink 校验 `POST /cli/qflink/verify`

3. 增加数据任务 `POST /cli/add`

4. 查看数据任务列表 `POST /cli/list`

5. 查看单个任务详情（用于迁移导出端）`POST /cli/show`

5.1 导出任务迁移 ZIP `POST /cli/export_task`

6. 上传 HTML 文件 `POST /cli/upload`