zhike-tq

智学题库导入/导出命令行工具，封装 packages/service 的题库导入/导出 HTTP API （/api/v1/import、/api/v1/export），不用写代码，一行命令就能把题目批量导入题库，或者按 条件把题目导出成文件。

工具本身是独立的（不依赖 packages/service 的源码，只通过 HTTP 调用它暴露的接口），也不在 仓库的 pnpm workspace 里，依赖单独用 npm 管理。

安装 / 本地运行

当前暂未发布到任何 npm registry，本地用 npm link 验证：

cd tools/zhike-tq
npm install
npm link          # 会在全局 bin 目录建一个 zhike-tq 的软链接
zhike-tq --help

不想污染全局环境也可以不 link，直接用相对路径运行：

node tools/zhike-tq/bin/zhike-tq.js --help
# 或者指定本地包路径给 npx（同样不需要发布）
npx --package=./tools/zhike-tq zhike-tq --help

不再需要时清理：npm unlink -g zhike-tq。

配置：服务地址 + API Key

导入/导出接口用 X-API-Key 鉴权，zhike-tq 需要知道服务地址前缀和 Key，两种方式都支持， 命令行参数优先级更高：

| 环境变量 | CLI 参数 | 说明 | |----------|----------|------| | ZHIKE_TQ_BASE_URL | --base-url | 服务地址前缀，不带 /api/v1/...，工具内部会自动拼 /api/v1/import、/api/v1/export | | ZHIKE_TQ_API_KEY | --api-key | API Key |

export ZHIKE_TQ_BASE_URL=http://localhost:8787       # 本地开发
# 或
export ZHIKE_TQ_BASE_URL=https://api.gaotuliuxue.com # 生产/其他环境
export ZHIKE_TQ_API_KEY=your_api_key_here

--base-url/--api-key 既可以跟在 zhike-tq 后面（全局），也可以跟在 import/export 子命令后面，两种写法等价：

zhike-tq --base-url http://localhost:8787 --api-key xxx export --file out.json
zhike-tq export --file out.json --base-url http://localhost:8787 --api-key xxx

如果既没设环境变量也没传参数，命令会直接报错并给出提示，不会静默失败。

命令一览

zhike-tq --help                                       查看帮助（每个命令都支持 --help）
zhike-tq --types                                      展示所有支持的题型（题型ID+名称），离线可用
zhike-tq --samples [--output <path>]                  展示所有题型的样题格式（需要联网）
zhike-tq import --file <path> [options]               批量导入题目
zhike-tq export --file <path> [options]                按条件查询并导出题目

--types：支持的题型

题库导入/导出接口本身用的是字符串 type（Writing/Speaking/...），数据库里没有数字题型ID。 zhike-tq 自己定义了一份固定的数字ID映射，方便 --type 1 这种简写：

| ID | type | 名称 | |----|------|------| | 1 | Writing | 写作题 | | 2 | Speaking | 口语题 | | 3 | ChooseOne | 单选题 | | 4 | ChooseMultiple | 多选题 | | 5 | Drag | 拖拽题 | | 6 | Insert | 插入句子题 | | 7 | Table | 表格题 | | 8 | FillBlank | 填空题 |

zhike-tq --types

--type 参数同时接受数字 ID 和字符串 type 名（大小写不敏感），逗号分隔可传多个： --type 1、--type Speaking、--type 3,4 都合法。

--samples：查看样题格式

对 8 种题型分别向服务请求 schema + 示例（GET /api/v1/import/schemas/:type），汇总展示， 帮助了解每种题型应该按什么 JSON 结构准备数据（需要能连上服务）：

zhike-tq --samples                       # 打印到 stdout
zhike-tq --samples --output samples.json # 保存成一个文件（8 种题型的 example 汇总在一起）

import：批量导入题目

zhike-tq import --file questions.json
zhike-tq import --file questions.json --mode upsert
zhike-tq import --file questions.json --validate-only

| 参数 | 说明 | |------|------| | --file <path>（必填） | 题目 JSON 文件路径 | | --mode <mode> | 导入模式：create（默认）/ update / upsert | | --defaults <json> | 默认值（JSON 字符串），应用到所有题目，如 --defaults '{"examId":1,"subjectId":4}' | | --validate-only | 只校验数据是否合法，不实际写入，正式导入前建议先跑一遍 |

--file 指向的 JSON 文件支持三种形态：

• 题目对象数组：[{...}, {...}]
• 完整请求体：{"questions": [{...}, {...}]}
• 单个题目对象：{...}（会自动包成长度为 1 的数组）

导入结束会打印 总数/创建/更新/跳过/失败 的汇总和每条题目的明细；只要有失败的题目，进程会以 非 0 退出码结束，方便写在 CI/脚本里判断成败。

export：按条件导出题目

zhike-tq export --file questions.json --limit 100 --type 1
zhike-tq export --file questions.json --type Speaking,ChooseOne --difficulty Medium
zhike-tq export --file questions.json --practice-id 807 --status Visible

| 参数 | 说明 | |------|------| | --file <path>（必填） | 导出结果保存路径 | | --type <ids> | 题型（ID 或名称，逗号分隔），见 zhike-tq --types | | --limit <n> | 最多导出题数（服务端有硬上限，超过会被截断） | | --exam-id / --subject-id / --textbook-id / --practice-id / --question-tag-id | 精确匹配的外键过滤条件 | | --difficulty <level> | Easy / Medium / Hard | | --status <status> | Visible / Invisible | | --name <keyword> | 按题目名称模糊匹配 | | --ids <ids> | 题目ID列表，逗号分隔 | | --created-after / --created-before | 创建时间范围（ISO 日期） |

导出的文件内容是纯题目数组（不带外层 {data:...} 包装），可以直接作为 import --file 的输入——这是有意设计成这样的，方便"导出 → 编辑 → 回灌导入"的备份/迁移流程。

如果匹配结果超过导出上限，stdout 会明确提示"结果被截断"，此时应该加更多过滤条件（比如 --practice-id/--textbook-id）分批导出，而不是想着一次性导出全部数据。

典型工作流：导出备份 → 回灌导入

# 1. 导出某个练习下的题目
zhike-tq export --file backup.json --practice-id 807

# 2. 校验一下这份数据（比如搬到另一个环境前，先确认目标环境能接受）
ZHIKE_TQ_BASE_URL=https://target-host ZHIKE_TQ_API_KEY=target_key \
  zhike-tq import --file backup.json --mode upsert --validate-only

# 3. 校验通过后正式回灌（upsert：题目对象里带着原 id，会更新同 id 的题目、否则创建新的）
ZHIKE_TQ_BASE_URL=https://target-host ZHIKE_TQ_API_KEY=target_key \
  zhike-tq import --file backup.json --mode upsert

跨环境搬迁提醒：examId/subjectId/textbookId/practiceId/questionTagId 这些外键 ID 在目标环境里未必指向同样的考试/科目/教材/练习/标签，回灌前要先确认目标环境的外键映射关系， 不要想当然地直接导入。

历史数据提醒：不是所有导出的题目都能无条件回灌导入成功。题库里一部分导入/导出接口上线之前 创建的历史题目，在 choices/stem/analysis 等字段上用的是和当前导入 Schema 不一致的历史 数据形状（详见 packages/service/docs/EXPORT_API_DOCUMENTATION.md 的 FAQ），这类题目导出后直接回灌会校验失败，属于历史数据本身的限制，不是 zhike-tq 的 bug。用 --validate-only 提前校验就是为了发现这类情况。

相关文档

• 导入 API 设计与完整字段说明：packages/service/docs/API_DOCUMENTATION.md
• 导出 API 设计与完整字段说明：packages/service/docs/EXPORT_API_DOCUMENTATION.md
• Python SDK（另一种客户端）：packages/service/sdk/python/tiku_import_sdk.py
• 配套的 Claude Code 技能：.claude/skills/zhixue_questions_import/、 .claude/skills/zhixue_questions_export/