📖 CLI API 文档

学习科目管理系统 — 命令行接口调用说明

基本信息
服务地址：http://<服务器IP>:3003/study
所有接口返回 JSON 格式数据，成功返回 {"success": true, ...}，失败返回 {"success": false, "error": "..."}
科目 ID 可通过「查询科目列表」接口获取，首页全局科目 ID 为 global

1. 查询科目列表

GET/api/cli/subjects

获取所有科目列表，用于查找 subjectId

curl 示例

curl http://localhost:3003/study/api/cli/subjects

返回示例

{ "success": true, "count": 3, "subjects": [ { "id": "sub_1718600000000", "name": "语文", "icon": "📚" }, { "id": "sub_1718600000001", "name": "数学", "icon": "📐" }, { "id": "sub_1718600000002", "name": "物理", "icon": "🔬" } ] }

2. 新建笔记

POST/api/cli/notes

在指定科目下创建笔记，支持 Markdown 格式内容

参数	类型	必填	说明
subjectId	string	是	科目 ID，首页为 "global"
title	string	是	笔记标题
type	string	否	笔记类型："manual"（手动笔记，默认）或 "qa"（问答笔记）
content	string	否	笔记内容（manual 类型使用），支持 Markdown
question	string	否	问题内容（qa 类型使用）
answer	string	否	答案内容（qa 类型使用），支持 Markdown

curl 示例（手动笔记）

curl -X POST http://localhost:3003/study/api/cli/notes \ -H "Content-Type: application/json" \ -d '{ "subjectId": "sub_1718600000000", "title": "古诗文背诵清单", "type": "manual", "content": "## 必背古诗\n1. 《静夜思》李白\n2. 《春晓》孟浩然\n3. 《登鹳雀楼》王之涣" }'

curl 示例（问答笔记）

curl -X POST http://localhost:3003/study/api/cli/notes \ -H "Content-Type: application/json" \ -d '{ "subjectId": "sub_1718600000001", "title": "勾股定理是什么？", "type": "qa", "question": "勾股定理是什么？", "answer": "直角三角形两直角边的平方和等于斜边的平方：**a² + b² = c²**" }'

返回示例

{ "success": true, "note": { "id": "a1b2c3d4-...", "subject_id": "sub_1718600000000", "type": "manual", "title": "古诗文背诵清单", "createdAt": "2026-06-24T10:00:00.000Z", "updatedAt": "2026-06-24T10:00:00.000Z" } }

3. 上传资料

POST/api/cli/materials

上传文件到指定科目，使用 multipart/form-data 格式

参数	类型	必填	说明
file	file	是	要上传的文件（使用 -F "file=@路径"）
subjectId	string	是	科目 ID，首页为 "global"
description	string	否	文件描述信息

curl 示例

curl -X POST http://localhost:3003/study/api/cli/materials \ -F "file=@/path/to/期末试卷.pdf" \ -F "subjectId=sub_1718600000000" \ -F "description=2025年期末数学试卷"

返回示例

{ "success": true, "material": { "id": "e5f6g7h8-...", "name": "期末试卷.pdf", "filename": "a1b2c3d4-uuid.pdf", "size": 1048576, "mimetype": "application/pdf", "description": "2025年期末数学试卷", "subjectId": "sub_1718600000000" } }

提示：同名同大小的文件会被自动跳过，返回 {"success": false, "error": "文件已存在"}

4. 发布公告

POST/api/cli/bulletins

在指定科目下发布公告，支持 Markdown 格式。如果该科目已有公告，将覆盖更新

参数	类型	必填	说明
subjectId	string	是	科目 ID，首页为 "global"
content	string	是	公告内容，支持 Markdown

curl 示例

curl -X POST http://localhost:3003/study/api/cli/bulletins \ -H "Content-Type: application/json" \ -d '{ "subjectId": "sub_1718600000000", "content": "## 期末复习安排\n下周一开始期末复习，请同学们做好准备：\n1. 课本第1-6单元\n2. 古诗文背诵\n3. 作文素材整理" }'

返回示例

{ "success": true, "subjectId": "sub_1718600000000", "contentLength": 87 }

速查表

功能	方法	路径	Content-Type
查询科目	GET	/api/cli/subjects	-
新建笔记	POST	/api/cli/notes	application/json
上传资料	POST	/api/cli/materials	multipart/form-data
发布公告	POST	/api/cli/bulletins	application/json

批量操作提示：可结合 shell 脚本批量上传文件或创建笔记。例如批量上传目录下所有 PDF：

SUBJECT_ID="sub_1718600000000"
for f in /path/to/files/*.pdf; do
  curl -X POST http://localhost:3003/study/api/cli/materials \
    -F "file=@$f" \
    -F "subjectId=$SUBJECT_ID"
  echo ""
done

学习科目管理系统 CLI API · v2.11.0