QuickForm CLI 接口说明

这一页是给老师的「AI 助手对接说明书」。 把它交给你的 AI 助手 —— WorkBuddy、豆包工作、千问办公 等能打开网页、能执行命令的智能体 —— 你就可以用一句自然语言，让 AI 在 QuickForm 上替你建表单、发问卷 / 签到 / 报名、收数据、导出表格，不必自己一个个点页面。

例如对 AI 说：「请按 quickform.cn/cli 的说明，帮我建一个『高一(3)班课堂签到表』，字段是姓名、学号、是否到场」，AI 会自己读本页说明、完成认证并调用接口。认证只需一次：在个人中心生成 QFLink 授权码交给 AI 即可，随时可以吊销。

下文是接口细节（官方命令行工具、认证方式、各接口参数与返回示例），可以整段复制给 AI，也可以把当前页面的网址链接复制给 AI；不用 AI 时，也可用脚本或扣子编程、OpenClaw 等工具直接调用。

0. 官方命令行工具

安装官方 qf 命令行工具（用下面这条命令，装到的是与本页对应的最新版 1.3.0）：

python3 -m pip install --upgrade https://quickform.cn/static/cli/quickform_cli-1.3.0-py3-none-any.whl
qf --version
qf login
qf task list
qf task add "课堂签到表" "本周签到"
qf task show <apiid>
qf task export <apiid> task.zip --include-data
qf task upload <apiid> ./index.html
qf submit <apiid> '{"name":"张三"}'
qf data <apiid>

关于 PyPI：PyPI 上的 quickform-cli 早期版本认证要求同时输入用户名与授权码，现已不再使用。上面这条直链安装包由 QuickForm 官方站点提供，请只从本页给出的地址或 PyPI 官方项目安装，不要使用来源不明的同名包或二进制文件。

首次运行 qf task … 等需要账号权限的命令会进入交互式认证；默认就是「仅 QF 授权码」——只需粘贴授权码，不必再输入用户名（服务器会按授权码反查账号并回填用户名）。也可选「用户名 + 密码」。非交互登录同样只需授权码：qf login -a <QF授权码>（想显式指定账号时可加 -u <用户名>）。凭据仅保存到当前用户的 ~/.config/quickform/config.json，文件权限为仅当前用户可读写。推荐使用可在个人中心随时吊销的 QF 授权码。运行 qf logout 可删除本机凭据。

全局选项：qf --base-url https://your.quickform.instance … 可临时指定自建站点；qf --version 显示版本。qf submit、qf brief 和 qf data 调用公开数据接口，不读取本地登录凭据，但仍受任务的读写开关限制。

1. 基础信息

Base URL：https://quickform.cn（若自建部署，请替换为您自己的站点根地址）
认证方式（三种任选其一，推荐第一种）：① 仅 QF 授权码 —— 请求体里只放 auth_code 即可，不需要 username，服务端按授权码反查账号并在响应里带回 username；② 用户名 + 密码（与网页登录一致）；③ 用户名 + 授权码（兼容旧写法，两者须属于同一账号）。授权码在个人中心「QFLink授权码」生成（类似 QQ 邮箱授权码），随时可吊销；三种方式都不依赖 Cookie/Session。
授权码一条就够：不存在「某些接口只支持密码」或「必须同时给用户名」的情况。/cli/list、/cli/add、/cli/show、/cli/export_task、/cli/upload 等任务管理接口同样接受单独的 auth_code；username 只在用密码登录时必填，用授权码时可省略（同时提供也不会报错，但必须同属一个账号）。
请求格式：支持 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/*)：给“校园版/教师版迁移、脚本、大模型工具”调用的账号凭据接口（单独的 QFLink 授权码，或 用户名 + 密码，两种等价；无需 Cookie）。
- 网页端「任务导出 / 导入」：站内按钮触发的导出 ZIP / 导入 ZIP|JSON（需要网页登录）。

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

使用「仅 QF 授权码」或「用户名 + 密码」认证（也兼容用户名 + 授权码），返回账号资料（不写 Session，适合脚本判断认证状态）；响应顶层带 username，客户端无需再让用户填写。

请求参数

参数	必填	说明
auth_code	推荐，单填即可	QFLink 授权码（`qf` + 32 位十六进制）；填了它就不需要 username
username	仅密码方式必填	用户名（也可用已绑定的邮箱/手机号登录）；用授权码时可省略
password	与 auth_code 二选一	密码

成功响应（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：用户名、密码或 QFLink 授权码不正确
429：认证尝试过于频繁

示例（curl）

推荐写法——只给授权码，不需要用户名：

curl -X POST "https://quickform.cn/cli/getuser" \
  -H "Content-Type: application/json" \
  -d '{"auth_code":"qf0123456789abcdef0123456789abcdef"}'

也可用密码：

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`

教师版/校园版连接在线服务器时使用。三种认证方式任选其一：

方式	参数	说明
仅授权码（推荐）	`auth_code`	服务端据码反查账号，响应里带 `username`，客户端无需再让用户填用户名
授权码（兼容）	`username` + `auth_code`	两者须属于同一账号
密码	`username` + `password`	与网页登录相同

可另加 client（teacher / school）。

curl -X POST "https://quickform.cn/cli/qflink/verify" \
  -H "Content-Type: application/json" \
  -d '{"auth_code":"qfxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","client":"teacher"}'

成功时返回顶层 username，以及 user、qflink.username、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。

请求参数

参数	必填	说明
auth_code	推荐，单填即可	QFLink 授权码（`qf` + 32 位十六进制）；不需要 username
username	仅密码方式必填	用户名；用 auth_code 时可省略
password	与 auth_code 二选一	密码
task_name	是	任务名称
task_intro	否	任务介绍/描述

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

成功响应（200）

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

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

错误响应

400：认证参数缺失 → { "success": false, "message": "缺少 auth_code（或 username+password）" }；只给密码却没给用户名 → { "success": false, "message": "使用密码登录时须提供 username" }
401：用户名、密码或 QFLink 授权码不正确 → { "success": false, "message": "用户名或密码错误" } / { "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 与名称。

请求参数

参数	必填	说明
auth_code	推荐，单填即可	QFLink 授权码（`qf` + 32 位十六进制）；不需要 username
username	仅密码方式必填	用户名；用 auth_code 时可省略
password	与 auth_code 二选一	密码

成功响应（200）

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

错误响应

400：认证参数缺失（既无 auth_code，也没有 username + password）
401：用户名、密码或 QFLink 授权码不正确

示例（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 附件）。

请求参数

参数	必填	说明
auth_code	推荐，单填即可	QFLink 授权码（`qf` + 32 位十六进制）；不需要 username
username	仅密码方式必填	用户名；用 auth_code 时可省略
password	与 auth_code 二选一	密码
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：用户名、密码或 QFLink 授权码不正确
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（默认开启）

请求参数

参数	必填	说明
auth_code	推荐，单填即可	QFLink 授权码（`qf` + 32 位十六进制）；不需要 username
username	仅密码方式必填	用户名；用 auth_code 时可省略
password	与 auth_code 二选一	密码
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
参数：
auth_code（推荐，无需 username）；或 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：用户名、密码或 QFLink 授权码不正确
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 等

7.1 获取「数据 id」（`include_id`）——删改数据前必读

以上读取接口默认不返回数据 id。若要用 QF 授权码删改某条数据，必须先拿到该条数据的 __id（即删改接口的 submission_id）：

读取时追加查询参数 include_id=1：
GET /api/<apiid>/all?include_id=1（全部数据，每条带 __id）
GET /api/<apiid>?include_id=1（最新 3 条，每条带 __id）
返回示例：
json { "submissions": [ { "name": "张三", "score": 85, "submitted_at": "2026-01-01 10:00:00", "__id": 1234 } ], "total_submissions": 1 }
不带 include_id=1 时响应中不会有 __id 字段，此时无法定位要删改的记录。

删改数据（需个人中心的 QF 授权码，请求头传 X-QuickForm-Username 与 X-QuickForm-Auth-Code，禁止放在 URL 参数中）：

删除单条：POST /task/<task_id>/submission/remove，Body（JSON）：{ "submission_id": 1234 }
批量删除：POST /task/<task_id>/submissions/remove_batch，Body（JSON）：{ "submission_ids": [1234, 5678] }

说明：<task_id> 为站内数字任务 ID（非 apiid）；submission_id 取自上一步读取数据得到的 __id。授权码仅用于权限校验，与是否返回 __id 无关——__id 始终由 include_id=1 控制。

高并发与网页优先（自建部署）：当 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，传入用户名与密码（或 QFLink 授权码）、任务名称（及可选介绍），得到 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`	上传并绑定到任务的可访问页面地址与保存文件名（未认证时返回审核提示页）
GET /api//all	`submissions`, `total_submissions`	加 `?include_id=1` 时，每条数据额外带 `__id`（删改所需）
GET /api/	`submissions`, `total_submissions`, `task_id`, `task_title`	最新 3 条；加 `?include_id=1` 时带 `__id`

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

QuickForm CLI 接口说明

0. 官方命令行工具

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 提交与获取数据

7.1 获取「数据 id」（include_id）——删改数据前必读

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`

7.1 获取「数据 id」（`include_id`）——删改数据前必读