基于OpenClaw与AI的智能错题管理系统：自由标签与间隔重复算法实践

1. 项目概述一个会“思考”的错题管家备考过GRE、考研或者任何需要大量刷题考试的朋友应该都经历过这个阶段错题本越记越厚但真正要复习的时候却无从下手。要么是题目抄得手酸要么是拍了一堆照片在相册里吃灰最后复习还是得从头刷题效率极低。我自己在备考时就深受其扰直到我开始用OpenClaw搭建自己的自动化工作流才萌生了做一个“智能错题管家”的想法。这就是“拾遗·通用考试备考追踪”项目的由来。它不是一个独立的App而是一个运行在OpenClaw平台上的Skill技能。你可以把它理解为一个24小时在线的、懂你备考内容的私人助教。它的核心功能极其简单粗暴你只管把错题截图或文字扔给它它负责自动识别、分类、归档并在最合适的时间提醒你复习。无论是GRE的Verbal难题、考研数学的积分计算还是驾照科目一的理论题它都能通过AI理解并打上精准的标签。我把它设计成“通用版”是因为我发现不同考试的错题管理逻辑是相通的但具体知识点千差万别。与其做一个固定结构的死板工具不如让AI根据你备考的考试类型动态地构建知识体系。你只需要在开始时告诉它“我在备考雅思”它就会调用针对雅思阅读、听力题型的识别逻辑后续积累的标签也会越来越精准。这个项目完全开源基于Node.js如果你也在用OpenClaw几分钟就能部署上手彻底告别混乱的错题管理。2. 核心设计思路为什么是“自由标签”与“间隔重复”在深入代码之前我想先聊聊这个项目的两个核心设计哲学这决定了它和市面上其他错题软件的根本不同。理解了这些你就能明白后续的每一个技术选择。2.1 从“固定科目”到“自由标签”应对备考的复杂性很多错题工具包括我之前为考公做的“朱批录”都采用预设科目结构。比如行测就固定分为“言语理解”、“判断推理”等五大模块。这对于目标明确、结构固定的考试很高效。但当我想用它来管理GRE错题时问题就来了GRE的Verbal部分细分为“Text Completion”文本填空、“Sentence Equivalence”句子等价和“Reading Comprehension”阅读理解而每类下面又有更细的考点比如“双空逻辑”、“词汇辨析”、“长难句结构”。预设的固定结构无法容纳这种动态、深度的知识体系。因此“拾遗”采用了自由标签系统。它不预设任何科目树。当你首次告知系统备考“GRE”时系统会从一个预置的“考试背景知识库”中加载GRE相关的题型和常见考点描述作为AI初始理解的参考。当你提交第一道错题时AI会基于这个背景知识结合题目内容生成一套标签例如[考试: GRE, 模块: Verbal, 题型: Text Completion, 知识点: 双空逻辑, 错误原因: 词汇量不足]。这套标签会被存入一个专属于“GRE”考试的标签词库。关键在于后续当你提交第二道GRE错题时AI会优先从“GRE标签词库”里寻找相似的历史标签来复用而不是每次都从头生成。这使得标签系统具备自我进化的能力。你刷的题越多标签体系就越完善、越贴合你的个人薄弱环节。而当你切换去备考“雅思”时系统会加载另一套背景知识并建立独立的“雅思标签词库”两者完全隔离互不干扰。这种设计让一个工具能弹性适配从高考到注会的几乎所有考试。2.2 自动化“间隔重复”解决“何时复习”的终极难题管理错题只是第一步更重要的是在遗忘临界点进行复习这正是“艾宾浩斯遗忘曲线”给我们的启示。但手动安排复习计划太反人性了。“拾遗”将间隔重复算法做成了自动化服务核心逻辑如下首次录入一道错题被成功识别并归档后系统会为其标记状态为“待复习”并计划在第二天晚上进行第一次复习提醒。复习与反馈系统通过定时任务在预设时间如每晚20点向你推送待复习的题目。你只需要回复“记得”或“不记得”甚至可以用表情符号。这个交互必须极其简单才能保证长期执行。状态机演进系统内部维护一个简单的复习状态机连续两次“记得”题目状态变为“已掌握”退出后续的主动复习循环。任何一次“不记得”题目状态重置为“待复习”复习间隔会适当缩短例如从隔天复习调整为明天再次复习重新开始循环。定时任务驱动这一切都由OpenClaw的cron_jobs功能在后台静默完成。你完全感受不到它的存在它就像一个有经验的教练准时把需要温习的“记忆卡片”递到你面前。这个设计把复杂的复习计划从用户脑中卸载到了系统中你只需要在收到推送时花几秒钟反馈剩下的交给算法。长期坚持下来复习效率会有质的提升。3. 技术架构与核心模块解析项目采用模块化设计结构清晰所有核心逻辑都封装在scripts/目录下的独立JS文件中。我们来逐一拆解关键模块是如何工作的。3.1 入口与路由parse_input.js这是整个Skill的“大脑”负责处理你发送给机器人的每一条消息。它的工作流程是一个典型的分发器模式// 简化逻辑示意 module.exports async (context) { const userMessage context.message.text; const userId context.user.id; // 1. 检查用户是否已完成初始配置即是否选择了备考考试 const userConfig await loadConfig(userId); if (!userConfig.examKey) { // 未配置触发 onboarding 流程 return await onboarding(context); } // 2. 消息类型路由 if (userMessage.includes(导出)) { // 触发导出流程 return await exportXlsx(context, userConfig.examKey); } else if (isQuickInput(userMessage)) { // 例如“Verbal-词汇不足” // 快速录入路径 return await handleQuickInput(context, userMessage, userConfig); } else if (hasImageAttachment(context)) { // 图片识别路径 - 核心功能 return await handleImageOCR(context, userConfig); } else { // 文本消息尝试直接解析 return await handleTextAnalysis(context, userMessage, userConfig); } };它的智能之处在于优先级判断。例如当用户发送一张图片时它会优先尝试用OCR提取文字然后调用AI进行分析。如果图片质量太差OCR失败它会友好地提示用户“识别失败能否直接输入题目文本”而不是直接报错。3.2 错题解析的核心handleImageOCR与 AI 提示工程处理截图是项目的亮点。这里结合了OCR技术和大型语言模型的推理能力。流程如下图片下载与OCROpenClaw SDK提供附件下载接口。下载图片后使用tesseract.js这类OCR库提取图片中的文字。这里有一个关键细节对于数学公式密集的考研数学题纯OCR效果很差。因此在实际部署中我更推荐接入专门的数学OCR API如Mathpix虽然成本略高但识别准确率对后续分析至关重要。构建AI分析提示词这是项目的“灵魂”。我们不能简单地把OCR文本扔给AI说“分析一下”。必须构建一个高度结构化的提示词引导AI输出我们想要的JSON格式。// 取自 assets/exam_prompts.js 中 GRE 的提示词片段 const grePrompt 你是一位资深的GRE备考导师。请分析用户提供的错题信息。 当前考试类别GRE。 请严格按照以下JSON格式输出不要有任何额外解释 { question_content: 清理后的题目文本, exam: GRE, module: Verbal | Quantitative | Writing, question_type: 例如: Text Completion, Reading Comprehension, Quantitative Comparison, knowledge_point: 具体知识点如双空逻辑转折词识别、排列组合计数原理, mistake_reason: 错误原因分析如词汇生疏、时间管理不当、概念理解偏差, tags: [标签1, 标签2] // 从标签库中优先选择 } 题目原文[${ocrText}] ;标签库优先匹配在生成提示词时会动态插入当前考试对应的tag_library.json内容。指令中会要求AI优先从已有标签库中选择tags如果确实没有合适的再生成新标签。新标签在归档后会被自动添加到标签库中。这就实现了标签系统的自我生长。结果结构化存储收到AI返回的标准JSON后调用update_daily.js模块将这道题按日期存入daily/目录下的JSON文件同时追加到总的wrong_questions.json数组中并标记复习状态。实操心得AI分析的稳定性初期测试时AI偶尔会“放飞自我”输出不完整的JSON或额外的话。为了保证稳定性我在代码中增加了强制JSON解析与回退机制首先尝试解析AI返回的内容如果失败则用正则表达式尝试提取{}之间的部分如果还失败则向用户返回一个标准格式的模板让用户手动填写。这比直接告诉用户“AI出错了”体验要好得多。3.3 数据持久化与备份策略所有数据都保存在~/.openclaw/skills/shiyi/data/目录下采用纯JSON文件存储简单直观。config.json: 存储每个用户的当前考试设置。以用户ID为键避免多用户干扰。tag_library.json: 嵌套结构。以exam_key如gre,ielts为第一层键其值是一个标签数组。每次新增标签时会检查去重。wrong_questions.json: 一个巨大的数组包含所有错题记录。每个记录包含完整的AI解析结果、时间戳、复习状态、复习历史。这里存在性能隐患当记录数超过5000条时直接读写这个文件会变慢。解决方案是引入分页或数据库但对于个人备考场景这个量级已经足够。daily/目录: 按YYYY-MM-DD.json格式存储每日的错题快照。这有两个好处一是备份二是便于生成“每日总结”看看今天在哪些知识点上栽了跟头。自动备份机制在每次写入wrong_questions.json或tag_library.json之前会先将其复制到backups/目录并保留最近10个版本。这是一个低成本高收益的防错措施一旦文件意外损坏可以快速回滚。3.4 定时任务daily_summary.js与review_reminder.js这两个脚本是自动化复习的“发动机”由OpenClaw的定时任务调度。daily_summary.js(每日21点执行)读取当天的daily/YYYY-MM-DD.json文件。统计今日错题总数、各知识点分布。用AI生成一段鼓励性的、带统计数据的总结例如“今晚总结你共记录了8道错题其中5道集中在‘定积分计算’上这是明天的攻坚重点继续坚持量变引起质变。”通过飞书/钉钉等配置的频道发送给用户。正向反馈对坚持备考非常重要。review_reminder.js(每隔一天20点执行)扫描wrong_questions.json找出所有状态为“待复习”且计划复习日期为今天或之前的题目。为了避免信息过载每次最多随机选取3-5道题可配置。格式化题目信息发送给用户。消息末尾会附带简单的指令提示“回复‘记得’或‘不记得’或使用/表情。”用户回复后parse_input.js会识别并调用更新逻辑修改题目的复习状态和下次复习时间。4. 完整部署与配置实操指南假设你已经在服务器或本地电脑上安装并配置好了OpenClaw环境。以下是手把手的部署步骤。4.1 技能安装与初始化# 1. 进入OpenClaw的技能目录 cd ~/.openclaw/skills # 2. 克隆本项目 git clone https://github.com/KaguraNanaga/shiyi-study-tracker # 3. 进入技能目录并安装Node.js依赖 cd shiyi-study-tracker npm install注意确保你的Node.js版本在18以上。如果安装依赖缓慢可以尝试设置淘宝镜像npm config set registry https://registry.npmmirror.com4.2 配置OpenClaw工作空间文件这是最关键的一步需要在OpenClaw的workspace.yaml文件中启用技能和定时任务。# ~/.openclaw/workspace.yaml skills: - shiyi-study-tracker # 启用拾遗技能 cron_jobs: - name: 拾遗_每日总结 schedule: 0 21 * * * # 每天21:00执行 action: type: run_script script: skills/shiyi-study-tracker/scripts/daily_summary.js channel: feishu # 按需替换为你的通知渠道如 dingtalk, wechat - name: 拾遗_二刷提醒 schedule: 0 20 1-31/2 * * # 每隔一天20:00执行每月1,3,5...号 action: type: run_script script: skills/shiyi-study-tracker/scripts/review_reminder.js channel: feishu参数详解schedule: 使用Cron表达式。0 21 * * *代表“每天的第21小时第0分钟”即晚上9点。0 20 1-31/2 * *代表“每月奇数日晚上8点”。你可以根据自己作息调整例如改成0 22 * * *晚上10点。channel: 指定消息推送的渠道。你需要先在OpenClaw中配置好对应渠道的机器人。飞书、钉钉、企业微信都是常见选择。4.3 首次使用与考试配置完成部署后在你的OpenClaw聊天界面比如飞书群里机器人或者直接给机器人发送任意消息如“嗨”。触发引导流程机器人会回复“欢迎使用拾遗你正在备考什么考试请直接告诉我例如GRE、考研数学、驾照科目一。”选择考试你回复“考研英语”。机器人会从预置列表中找到匹配项并确认“已设置为‘考研英语’。现在你可以发送错题截图或文字给我了。”开始记录发送你的第一道考研英语阅读错题截图。稍等片刻你会收到AI的解析结果“已归档。题型阅读理解-细节题知识点长难句指代关系错误原因定位偏差。标签已添加。”体验自动化从第二天开始你将在晚上8点收到复习提醒在晚上9点收到每日学习报告。4.4 如何新增一个考试类型项目预置了主流考试但如果你备考的是“注册电气工程师”这类小众考试可以轻松添加。打开文件shiyi-study-tracker/assets/exam_prompts.js。在EXAM_PROMPTS对象中添加一个新的键值对。键是考试的英文标识exam_key值是给AI看的背景知识提示词。// 在 EXAM_PROMPTS 对象内添加 const EXAM_PROMPTS { // ... 其他考试 electrical_engineer: 注册电气工程师考试分为基础考试和专业考试。 基础考试包含高等数学、物理学等公共基础课。 专业考试涉及电路理论、电机学、电力系统分析等。 请根据题目内容将knowledge_point标注到具体的课程和章节例如“电路理论-三相电路功率计算”。 , }; // 同时在 EXAM_ALIASES 对象中添加别名方便用户输入 const EXAM_ALIASES { // ... 其他别名 注册电气工程师: electrical_engineer, 注电: electrical_engineer, };保存文件。下次用户输入“注册电气工程师”时系统就能识别并应用这套新的解析逻辑了。强烈建议将你的修改通过Pull Request提交给原项目帮助到更多有同样需求的人。5. 常见问题与故障排查实录在实际使用和朋友们反馈的过程中我积累了一些典型问题的解决方法。5.1 图片识别不准或AI解析混乱这是最常见的问题通常不是代码bug而是输入或配置问题。症状1OCR提取的文字乱码或缺失。原因截图模糊、背景复杂、字体特殊如手写体。解决确保截图清晰最好是题目部分的特写。如果题目包含大量数学公式考虑在handleImageOCR函数中根据考试类型切换OCR服务。可以增加一个判断如果exam_key包含math则调用Mathpix API否则用默认Tesseract。终极方案直接发送题目文本。你可以长按题目复制文字然后发送“题目[粘贴文字]”。AI对纯文本的分析准确率远高于图片。症状2AI返回的标签总是不对比如把数学题分析成英语题。原因config.json中用户的考试设置错误或者exam_prompts.js中对应考试的提示词写得太笼统。解决检查用户配置可以发送命令“查看当前考试”机器人会返回你的当前设置。重置考试发送“切换考试”重新选择。优化提示词编辑exam_prompts.js让对应考试的描述更具体明确题型范围和知识点分类方式。5.2 定时任务没有执行症状到了时间没有收到每日总结或复习提醒。排查步骤检查OpenClaw服务状态在服务器上运行pm2 list如果你用PM2管理或systemctl status openclaw确保OpenClaw进程正在运行。检查Cron表达式确认workspace.yaml中的schedule设置是否正确。可以使用在线Cron表达式验证工具检查。检查脚本路径确保script:后面的路径是绝对路径或相对于OpenClaw根目录的正确路径。有时复制粘贴会导致路径错误。查看OpenClaw日志日志中通常会记录定时任务的触发和执行情况。运行pm2 logs openclaw或查看日志文件寻找错误信息。5.3 数据导出失败或格式错乱症状发送“导出GRE错题”后机器人没有反应或文件无法打开。排查步骤检查文件权限确保OpenClaw进程有对data/exports/目录的写入权限。检查依赖导出功能使用xlsx库生成Excel。确保在项目目录下正确执行了npm install。检查数据过滤导出脚本会根据命令中的关键词如“GRE”过滤错题。确认wrong_questions.json中存在对应exam字段为“GRE”的记录。手动调试可以临时在export_xlsx.js中增加日志输出过滤后的数据条数看是否为空。5.4 性能问题随着错题增多变慢症状当错题积累到数千条后查询、导出或加载数据感觉变慢。优化方案分库分表思想不要永远读写一个巨大的wrong_questions.json。可以修改存储逻辑按考试或按月拆分文件例如wrong_questions_gre.json,wrong_questions_202501.json。引入索引如果拆分后查询仍慢可以考虑引入轻量级数据库如SQLite。为exam,review_status,date等常用查询字段建立索引。缓存热点数据将用户当前考试的标签库tag_library在服务启动时加载到内存中避免每次分析都读文件。5.5 复习提醒的题目太多或太少症状一次提醒10道题复习压力大或者一次只提醒1道感觉没效率。定制化调整这是设计上的可配置项。你可以修改review_reminder.js中的相关常量。// 在文件顶部附近定义 const MAX_QUESTIONS_PER_REMINDER 5; // 每次最多提醒5道 const MIN_QUESTIONS_PER_REMINDER 2; // 如果待复习题多于2道才发送提醒根据你自己的复习节奏调整这些数字。如果你某天时间充裕可以调大MAX_QUESTIONS_PER_REMINDER如果希望复习更聚焦可以调小。这个项目本质上是一个高度定制化的个人效率工具。开源出来是希望提供一个灵活的思路和可用的基础框架。你在使用中遇到的任何问题很可能就是下一个需要优化的特性。最让我有成就感的不是代码本身而是看到它真正融入了一个备考者的学习流变成了一个无声却有力的伙伴。如果你在部署或使用中有了新的想法比如集成Anki、或者增加错题相似度推荐欢迎动手改造它。