API 开放文档 v37

所有 Practice 模块对外暴露的 window.* API 接口,可直接在浏览器控制台或第三方应用中调用。

目录

  1. SYLLABUS_DATA · 考纲数据层
  2. YZPractice · 练习引擎
  3. AITutor · AI 辅导
  4. Streak · 学习连续打卡
  5. SRS · 间隔重复记忆
  6. WritingGrader · 写作评分
  7. Vocab · 词汇学习
  8. Notes · 学习笔记
  9. Collab · 小组协作
  10. MCP 集成说明
加载方式 · 在 Practice 相关页面底部均已加载对应 JS 文件。也可在任意页面手动引入:
<script src="/js/syllabus-data.js"></script>
<script src="/js/practice-engine.js"></script>
<script src="/js/collab.js"></script>

1. SYLLABUS_DATA · 考纲数据层

来源:js/syllabus-data.js · 版本 v13 · 8 科结构化考纲数据

SYLLABUS_DATA.getSubject(subjectKey)
获取整科考纲数据。subjectKey: sat / act / ap / ib / alevel / toefl / ielts / igcse
// 获取 SAT 考纲
var sat = SYLLABUS_DATA.getSubject('sat');
console.log(sat.name, sat.papers.length);
// => "SAT 2"
SYLLABUS_DATA.getTopic(subjectKey, topicCode)
按 topic-code 获取单个 topic 详情,含 name / weight / prereq / questionIds
var topic = SYLLABUS_DATA.getTopic('sat', 'M-Alg-1a');
console.log(topic.name); // => "Linear equations, inequalities & systems"
console.log(topic.weight); // => "8.75%"
SYLLABUS_DATA.getAllTopicCodes(subjectKey)
获取某科目所有 topic-code 列表
var codes = SYLLABUS_DATA.getAllTopicCodes('ap');
console.log(codes.length); // => AP 全部 topic 数量
SYLLABUS_DATA.allocateQuestionsByWeight(subjectKey, totalQuestions)
按 Topic 权重分配指定数量的题目,返回 topicCode → questionCount 映射。用于 Mock Test 组卷。
// SAT 120 题按权重分配
var alloc = SYLLABUS_DATA.allocateQuestionsByWeight('sat', 120);
console.log(alloc['M-Alg-1a']); // => 约 11 题 (8.75% × 120)

2. YZPractice · 练习引擎

来源:js/practice-engine.js · 版本 v6 · 答题 + 错题本 + localStorage 持久化

YZPractice.loadData()
加载全部练习数据(含所有科目的答题记录)
var data = YZPractice.loadData();
console.log(Object.keys(data.records)); // => ["sat", "act", "ap", ...]
YZPractice.saveData(data)
保存练习数据到 localStorage
var data = YZPractice.loadData();
data.records.sat['q-1'].correct = true;
YZPractice.saveData(data);
YZPractice.getRecords()
获取当前科目(data-subject 属性)的答题记录
var satRecs = YZPractice.getRecords();
var total = Object.keys(satRecs).length;
var correct = Object.values(satRecs).filter(function(r){ return r.correct; }).length;
console.log('SAT:', correct + '/' + total);
YZPractice.clearSubject()
清空当前科目全部答题记录(慎用)
YZPractice.clearSubject(); // 清空当前科目记录

3. AITutor · AI 辅导

来源:api/ai-chat.js · 诊断 + 解析 + 自适应建议

AITutor.diagnose(subjectKey, records)
诊断学生薄弱环节,返回需要重点复习的 topic 列表
var recs = YZPractice.getRecords();
var diag = AITutor.diagnose('sat', recs);
console.log(diag.weakTopics); // => [{code:'M-Alg-1a', rate: 0.4}, ...]
console.log(diag.suggestions); // => ["建议复习线性方程组..."]
AITutor.explain(questionId, subjectKey)
获取指定题目的 AI 解析
var explanation = AITutor.explain('q-5', 'sat');
console.log(explanation.answer);  // => 正确答案
console.log(explanation.solution); // => 解题步骤

4. Streak · 学习连续打卡

学习连续天数 + 徽章系统

Streak.init(userId)
初始化/恢复用户的打卡记录
Streak.init('student001');
Streak.todayCount()
获取今日已答题数
var done = Streak.todayCount();
if (done < 20) console.log('还差', 20 - done, '题达成今日目标');
Streak.getBadges()
获取已获得的徽章列表
var badges = Streak.getBadges();
badges.forEach(function(b) {
  console.log(b.name, '·', b.description);
});

5. SRS · 间隔重复记忆

基于 SM-2 算法的错题间隔重复调度

SRS.init()
初始化 SRS 系统
SRS.init();
SRS.getDueQuestions(subjectKey)
获取当前到期需要复习的题目列表
var due = SRS.getDueQuestions('sat');
console.log('需要复习:', due.length, '题');
due.forEach(function(q) {
  console.log(q.id, q.topic);
});

6. WritingGrader · 写作评分

TOEFL/IELTS/AP 主观题自动评分

WritingGrader.grade(text, type)
评分学生写作。type: 'toefl_integrated' / 'ielts_task2' / 'ap_frq' 等
var result = WritingGrader.grade(
  'In today's society, education is important because...',
  'toefl_integrated'
);
console.log('得分:', result.score);
console.log('反馈:', result.feedback);
console.log('改进建议:', result.suggestions);

7. Vocab · 词汇学习

SAT/TOEFL/IELTS 核心词汇

Vocab.loadList(level)
加载指定级别词汇表。level: 'sat' / 'toefl' / 'ielts'
var words = Vocab.loadList('sat');
console.log('SAT 核心词汇:', words.length, '个');
console.log(words[0]); // => {word:'abandon', pos:'v.', meaning:'放弃'}
Vocab.startStudy(level, count)
开始词汇学习会话,返回指定数量的单词卡片
var cards = Vocab.startStudy('toefl', 20);
cards.forEach(function(c) {
  console.log(c.word, c.meaning);
});

8. Notes · 学习笔记

针对题目/Topic的笔记系统

Notes.addNote(target, content)
添加笔记。target 可以是题目 ID 或 topic-code
Notes.addNote('q-5', '这道题考的是线性方程组,注意消元法的步骤。');
Notes.addNote('M-Alg-1a', '核心公式:y = kx + b');
Notes.getNotes(target)
获取指定目标的所有笔记
var notes = Notes.getNotes('M-Alg-1a');
notes.forEach(function(n) {
  console.log(n.content, '·', new Date(n.ts).toLocaleDateString());
});
Notes.export(format)
导出全部笔记。format: 'json' / 'markdown' / 'txt'
var md = Notes.export('markdown');
// 下载为 .md 文件
var blob = new Blob([md], {type:'text/markdown'});
var url = URL.createObjectURL(blob);
window.open(url);

9. Collab · 小组协作

来源:js/collab.js · localStorage 模拟多人协作

Collab.createRoom(roomName, nickname)
创建房间,返回房间码
var result = Collab.createRoom('SAT 冲刺小队', '小明');
console.log('房间码:', result.code); // => "AB3X9K"
Collab.joinRoom(code, nickname)
加入已有房间
var room = Collab.joinRoom('AB3X9K', '小红');
if (room) console.log('已加入:', room.name);
else console.log('房间码无效');
Collab.sendMsg(code, nickname, text)
发送聊天消息
Collab.sendMsg('AB3X9K', '小明', '大家今天刷了多少题?');
Collab.getLeaderboard(code)
获取房间内排行榜
var lb = Collab.getLeaderboard('AB3X9K');
lb.forEach(function(u, i) {
  console.log(i+1, u.name, u.correct+'/'+u.total, u.rate+'%');
});

10. MCP 集成说明

什么是 MCP

MCP(Model Context Protocol)是一种让 AI 助手能够调用外部工具/API 的协议。通过 MCP,你可以将 Practice 的所有 API 暴露给 AI 助手(如 TRAE、Claude Desktop 等),让 AI 能够直接操作学习系统。

集成步骤

  1. 注册 API 端点:将 window.SYLLABUS_DATAwindow.YZPractice 等对象的方法映射为 MCP 工具。
  2. 配置权限:决定哪些 API 允许 AI 调用(只读 vs 读写)。建议默认只读。
  3. 设置触发规则:例如当 AI 被问到"学生 SAT 正确率"时,自动调用 YZPractice.getRecords()
  4. 添加自然语言描述:为每个工具添加清晰的描述,让 AI 理解何时该使用。

MCP 工具配置示例

{
  "mcpServers": {
    "practice": {
      "command": "node",
      "args": ["mcp-practice-server.js"],
      "env": {
        "PRACTICE_DATA_KEY": "yz_practice_data"
      }
    }
  }
}

// AI 调用示例(自然语言 → API):
// 用户:"帮我看看学生 sat_001 的 SAT 表现如何?"
// AI 自动调用:
//   1. YZPractice.loadData() → 获取全部数据
//   2. SYLLABUS_DATA.getSubject('sat') → 获取 SAT 考纲结构
//   3. 计算正确率并生成报告

安全建议