开发者文档

1快速开始

自学平台提供 REST API，通过 HTTP 请求直接创建在线题库并生成答题链接。用户无需注册登录即可答题，题库默认保存 24 小时。

curl 示例

curl -X POST https://zixue.gshyj.com/api/mcp/create-quiz \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Python 基础测验",
    "questions": [
      {
        "content": "Python 中哪个关键字用于定义函数？",
        "type": "single",
        "options": ["func", "def", "function", "define"],
        "answer": [1],
        "explanation": "Python 使用 def 关键字定义函数"
      }
    ]
  }'

返回结果

{
  "code": 0,
  "msg": "题库创建成功",
  "data": {
    "token": "a1b2c3d4...",
    "url": "/quiz-anon.html?token=a1b2c3d4...",
    "full_url": "https://zixue.gshyj.com/quiz-anon.html?token=a1b2c3d4...",
    "title": "Python 基础测验",
    "question_count": 1,
    "expires_at": "2026-07-29 18:00:00"
  }
}

拿到 full_url 后直接发给用户，打开即可答题。

3Python 示例

import requests

resp = requests.post("https://zixue.gshyj.com/api/mcp/create-quiz", json={
    "title": "高一数学 - 函数与导数",
    "questions": [
        {
            "content": "函数 f(x) = x² 在 x=2 处的导数值是？",
            "type": "single",
            "options": ["2", "4", "6", "8"],
            "answer": [1],
            "explanation": "f'(x) = 2x，f'(2) = 4",
            "difficulty": 2
        },
        {
            "content": "下列哪些是偶函数？",
            "type": "multiple",
            "options": ["f(x)=x²", "f(x)=x³", "f(x)=|x|", "f(x)=sin(x)"],
            "answer": [0, 2],
            "explanation": "x² 和 |x| 满足 f(-x)=f(x)",
            "difficulty": 3
        }
    ]
})

data = resp.json()
if data["code"] == 0:
    print(f"答题链接: {data['data']['full_url']}")
    print(f"有效期至: {data['data']['expires_at']}")
else:
    print(f"创建失败: {data['msg']}")

4在 TRAE 中使用（推荐）

本项目内置了 zixue-quiz 技能，在 TRAE 中打开本项目后，直接对 Agent 说"帮我出题"即可自动生成题库并返回答题链接。

使用方式

1. 在 TRAE 中打开自学平台项目
2. 对 Agent 说："帮我出 10 道高中物理力学单选题"
3. Agent 自动生成题目，通过 curl 调用 API 创建题库
4. 返回真实答题链接，直接点击即可答题

从文档/PDF出题

1. 将 PDF 或文档内容提供给 Agent
2. 说："阅读这份文档，帮我生成 10 道选择题"
3. Agent 阅读内容后生成题目并调用 API
4. 返回答题链接，打开即可答题

5API 参数说明

创建题库

POST /api/mcp/create-quiz — 无需认证

参数	类型	必填	说明
title	string	是	题库标题
questions	array	是	题目数组（1-200道）

questions 数组每项的结构：

字段	类型	必填	说明
content	string	是	题干内容
type	string	是	"single" 单选题 / "multiple" 多选题
options	string[]	是	选项数组（至少2个）
answer	number[]	是	正确答案索引数组（从0开始）
explanation	string	否	答案解析
source	string	否	题目来源（默认 "MCP生成"）
difficulty	number	否	难度 1-5（默认 3）

查询题库状态

GET /api/mcp/quiz/{token} — 无需认证

curl https://zixue.gshyj.com/api/mcp/quiz/a1b2c3d4...

6完整 API 列表

以下接口均以 https://zixue.gshyj.com 为基础路径。

匿名题库接口

方法	路径	功能	认证
POST	/api/mcp/create-quiz	创建匿名题库，返回答题链接	无需
GET	/api/mcp/quiz/{token}	获取题库数据	无需
POST	/api/mcp/save-quiz	保存匿名题库到个人词库	需登录

认证接口

方法	路径	功能
POST	/api/login	登录
POST	/api/register	注册
POST	/api/logout	退出

题库与分类

方法	路径	功能	认证
GET	/api/index	获取分类树 + 用户信息	可选
GET	/api/categories	获取分类树	可选
GET	/api/quiz/{categoryId}	获取分类下的题目	可选
GET	/api/quiz/mistakes	获取错题集	需登录
POST	/api/quiz/mark	标记题目掌握/未掌握	需登录

用户词库管理

方法	路径	功能
GET	/api/bank/list	获取私有词库列表
POST	/api/bank/rename	重命名词库
POST	/api/bank/import	从 JSON 导入题目
POST	/api/bank/question	添加新题目
GET	/api/bank/question/{id}	获取题目详情
POST	/api/bank/question/{id}	更新题目
POST	/api/bank/question/{id}/delete	删除题目
GET	/api/bank/{categoryId}/questions	获取词库题目列表
GET	/api/bank/{categoryId}/export	导出词库为 JSON

题库分享

方法	路径	功能
POST	/api/share/create	创建分享链接
GET	/api/share/{token}	获取分享详情
POST	/api/share/{token}/claim	领取分享题库

7注意事项

故障排查

问题	原因	解决方案
连接服务器失败	网络不通或后端未运行	检查网络连接
题库已过期	创建超过 24 小时	重新创建题库
题目格式错误	选项不足或答案索引越界	检查 options 和 answer 字段
保存失败	未登录或 token 无效	先在自学平台登录，再尝试保存