基于多模态AI与本地优先架构的考公错题管理助手设计与实现

1. 项目概述：一个本地优先的考公错题管理助手

如果你正在准备公务员考试，或者身边有朋友在备考，那你一定对“刷题”和“错题本”这两个词不陌生。每天一套行测，做完对答案，看着满篇的红叉，心里想着“明天一定要整理”，结果往往是草草看一眼就翻篇，错题本永远停留在第一页。不是不想整理，而是这个过程太繁琐了：截图、粘贴、分类、写分析……一套流程下来，比做题还累，极大地消耗了本就宝贵的备考精力。

“朱批录”（kaogong-study-tracker）这个项目，就是为了解决这个“最后一公里”的痛点而生的。它不是一个独立的App，而是一个运行在OpenClaw平台上的Skill（技能）。你可以把它理解为一个24小时在线的、专属于你的“考公备考小秘书”。它的核心逻辑非常简单：你只管做题和反馈，它来负责所有繁琐的记录、归档和分析工作。你通过日常聊天的飞书、Telegram等工具，把错题截图或者成绩文字发过去，它就能自动帮你把错题整理得明明白白，所有数据都安全地留在你自己的电脑里。

我之所以花时间折腾这个工具，是因为我自己在备考和辅导他人的过程中，深刻体会到“有效复盘”才是提分的关键。大部分人的分数瓶颈，不在于做题量，而在于对错题的消化吸收程度。朱批录的目标，就是利用多模态AI的能力，把“消化吸收”这个环节的门槛降到最低，让你能更轻松、更持续地进行高质量的复习。

1.1 核心需求与设计思路

在深入代码之前，我们先拆解一下考公备考者在错题管理上的真实需求，这决定了朱批录的每一个功能设计。

第一，极致的便捷性。备考已经够累了，任何增加操作步骤的工具都会被抛弃。因此，朱批录确立了“对话即操作”的第一原则。你不需要打开任何额外的软件界面，就在你平时聊天的飞书窗口里，像跟朋友吐槽一样说一句“今天资料分析错了5道”，或者随手丢一张错题截图，它就能理解并处理。这种无缝的体验，是坚持使用的关键。

第二，数据的绝对主权与隐私。错题，尤其是那些反复做错的题，某种程度上反映了你的思维弱点和知识盲区，是非常个人且敏感的数据。很多在线工具需要上传到云端，存在隐私泄露风险，也让人心里不踏实。朱批录采用“本地优先”架构，所有截图、识别后的文本、分析结果，都存储在你本地电脑的~/.openclaw/目录下。它调用AI模型进行识别的过程，也是通过你已经配置好的、可信的API渠道（如DeepSeek、Kimi等），数据流完全可控。

第三，智能与鲁棒性的平衡。我们希望能用AI自动识别截图中的题目、答案和错误原因，但这技术并非100%可靠，尤其是对于复杂的图形推理题。因此，朱批录设计了“失败软降级”机制。如果图片识别不清或失败，它会明确地提示你：“这张图有点模糊，能直接把题目文字发我吗？” 引导你进行手动文本输入，确保流程不会因为一次识别失败而彻底中断，你整理错题的动作依然可以继续。

第四，提供持续的正反馈与指导。备考是场马拉松，容易迷失方向。朱批录不只是被动的记录者，它还是一个主动的提醒者。通过配置定时任务，它会在每天晚间（比如21:00）主动给你发送一条总结，告诉你今天各模块的准确率、近期最薄弱的环节，并给出一条像教练一样的、具体的明日复习建议（例如：“图形推理的‘位置规律’最近3天错了7次，建议明天花15分钟专项复习一下这个知识点”）。这种及时的反馈，能帮助你保持节奏，聚焦重点。

基于以上四点，朱批录的整体架构就清晰了：一个以后台服务形式运行、通过自然语言交互、在本地处理数据、并具备一定主动提醒能力的错题管理自动化助手。

2. 核心功能模块深度解析

朱批录的功能看似简单，但背后是几个模块的精密协作。理解这些模块，不仅能帮你更好地使用它，也方便你未来根据自己的需求进行定制化修改。

2.1 多模态错题识别引擎

这是项目的技术核心，位于scripts/parse_input.js。当你发送一张错题截图时，背后发生了一系列动作。

第一步，消息路由与类型判断。OpenClaw框架会拦截到你的消息，朱批录的Skill被触发。它首先判断消息类型：是纯文本（如“言语4错”），还是包含图片附件？如果是图片，它会将图片下载到本地临时目录，并准备进行识别。

第二步，构造识别提示词（Prompt）。这是决定识别准确率的关键。你不能简单地把图片丢给AI说“看看这是什么”，必须给出明确的指令。朱批录的Prompt经过精心设计，旨在引导AI结构化地输出信息。其核心要点包括：

1. 身份与任务界定：明确告诉AI“你是一个公务员考试备考助手”，需要从截图中提取错题信息。
2. 结构化输出要求：强制要求AI以指定的JSON格式回复，字段包括module（模块，如“言语理解”）、subtype（题型，如“逻辑填空”）、question_text（题目文字）、visual_description（对图表、图形的文字描述）、answer（正确答案）、error_reason（错误原因分类）。
3. 错误原因分类引导：预先定义了几种常见的错误类型（“知识点不会”、“粗心失误”、“时间不足”、“概念混淆”），让AI从中选择，这比让AI自由发挥更稳定、更实用。
4. 容错与降级指令：在Prompt中明确说明，如果图片质量太差无法识别，就返回一个特定的失败状态码，从而触发前文提到的“软降级”流程，转而向你请求文字输入。

第三步，调用模型与解析结果。朱批录本身不绑定任何特定模型，它使用你在OpenClaw中已经配置好的多模态模型（例如Qwen-VL、Kimi-Vision、Claude等）。这带来了极大的灵活性，你可以根据自己对准确性、速度和成本的需求选择最合适的模型。收到AI返回的JSON后，脚本会进行校验，确保必要字段存在，然后将其与原始的图片Base64编码一起，组装成一个完整的错题记录对象。

实操心得：Prompt工程是灵魂在实际测试中，我发现直接让AI“分析错题”效果很差，它可能会开始讲解题目解法。必须用“提取信息”和“按以下JSON格式输出”来严格约束其行为。此外，为error_reason提供选项池至关重要，这能保证后续统计分析的维度统一。如果你发现识别结果总是不准，第一个要调整的就是Prompt。

2.2 本地数据存储与管理体系

所有数据都存放在~/.openclaw/skills/kaogong-study-tracker/data/目录下，采用文件数据库的形式，简单而高效。

• daily/目录：按日期存储每天的整体练习情况。每个文件如2026-03-15.json，记录的是你当天汇报的“行测做完了，言语4错，判断8错…”这样的汇总数据。它的结构侧重于宏观统计，用于计算每日正确率和生成趋势图。
• wrong_questions.json文件：这是核心数据库，一个JSON数组，保存了所有识别/录入的错题详情。每一条记录都包含我们在2.1节提到的完整字段。这个文件是所有深度分析的基础。
• stats_cache.json文件：这是一个为了提高响应速度而设计的缓存文件。系统会定期（如每次新增记录后）计算“近7日各模块准确率”、“连续打卡天数”等指标，并缓存于此。当你在聊天中询问“我最近怎么样？”时，它能快速读取缓存返回结果，而无需实时遍历大量历史数据重新计算，体验更流畅。
• config.json文件：存储一些简单的配置，比如是否已完成初始设置、默认选择的AI模型等。
• exports/目录：存放生成的Excel错题本文件。

这种基于文件的设计，优点是非常直观、易于备份和迁移（直接复制整个文件夹即可）。缺点是不适合超大规模并发写入，但对于个人备考场景，这完全不是问题。

2.3 自然语言交互与上下文理解

朱批录的“对话即操作”体验，依赖于对自然语言的灵活解析。这主要在scripts/parse_input.js的文本处理部分实现。

它并不依赖复杂的NLP模型，而是采用“关键词匹配+规则解析”的轻量级方案，这对于垂直领域、句式相对固定的场景非常有效且可靠。例如：

• 当消息中包含“今天”、“错了”、“言语”、“判断”等关键词组合时，判定为“每日成绩汇报”。
• 当消息是“导出错题本”或“导出Excel”时，触发导出流程。
• 当消息是“同步飞书”时，触发云文档同步流程。
• 当消息是“我最近怎么样”或“总结一下”时，触发生成统计分析报告。

对于成绩汇报，它会使用正则表达式来捕捉“[模块名][数字]错”的模式，例如从“言语4错，判断8错”中提取出“言语”->4，“判断”->8。同时，它还内置了一个module_map.json别名映射表，能理解“逻辑”指的是“判断推理”，“数资”可能同时指代“数量关系”和“资料分析”，并进行智能拆分或追问确认。

这种设计使得交互非常自然，你可以用多种方式表达同一意图，系统都能正确理解。

2.4 定时任务与主动关怀系统

被动响应之外，主动提醒是提升工具粘性的法宝。这是通过OpenClaw的cron_jobs功能配合scripts/daily_summary.js脚本实现的。

在workspace.yaml配置文件中，你可以添加一个定时任务，例如每天21:00执行。时间一到，OpenClaw的调度器就会自动运行daily_summary.js脚本。这个脚本会：

1. 读取stats_cache.json和当天的daily/记录。
2. 分析出近期（如7天内）准确率最低的1-2个模块。
3. 从预定义的“建议语料库”中，选取一条针对该薄弱模块的具体、可操作的建议。比如，针对“图形推理-位置规律”薄弱，建议可能是：“建议明天花20分钟，专项练习10道涉及‘旋转’、‘平移’、‘翻转’的位置规律题，重点观察元素的方向和移动步长。”
4. 将今日成绩、薄弱分析和建议，拼接成一条鼓励性的消息，通过你指定的渠道（如飞书）发送给你。

这个功能模拟了一个负责任的备考伙伴，在你可能松懈的时候给你一个轻轻的推动，帮助你保持复盘的习惯和复习的方向性。

3. 从零开始的完整部署与配置实操

理论讲完了，我们动手把它跑起来。假设你已经在电脑上安装并配置好了OpenClaw（一个用于连接各种聊天平台和AI模型的自动化框架），下面是一步步的部署指南。

3.1 环境准备与技能安装

首先，确保你的环境符合要求：Node.js版本需要大于等于18。打开终端，进入OpenClaw的技能目录。

# 1. 进入OpenClaw的技能目录，通常在这里 cd ~/.openclaw/skills # 2. 克隆朱批录项目 git clone https://github.com/KaguraNanaga/kaogong-study-tracker # 3. 进入项目目录并安装依赖 cd kaogong-study-tracker npm install

npm install会安装项目所需的第三方库，主要是用于生成Excel文件的openpyxl（通过某个Node.js封装包或Python桥接）以及一些工具库。

3.2 核心配置文件详解与修改

接下来是关键的配置环节。你需要修改OpenClaw的主配置文件workspace.yaml，通常位于~/.openclaw/目录下。

# 在 workspace.yaml 中找到或添加 skills 部分 skills: - kaogong-study-tracker # 添加这一行，启用朱批录技能 # 在 workspace.yaml 中找到或添加 cron_jobs 部分 cron_jobs: - name: "备考晚间总结" schedule: "0 21 * * *" # 每天21:00执行，cron表达式 action: type: run_script script: skills/kaogong-study-tracker/scripts/daily_summary.js # 脚本路径 channel: feishu # 推送渠道，根据你实际使用的改，比如 telegram

• schedule: 这是Cron表达式，“0 21 * * *”表示每天21:00。你可以根据需要调整，比如“0 22 * * *”是22点。
• channel: 必须与你OpenClaw中配置的某个聊天渠道名称一致。如果你主要用Telegram，就改成telegram。

注意事项：路径与权限确保script路径是正确的相对路径或绝对路径。如果OpenClaw提示找不到脚本，请检查路径。另外，确保Node.js有权限读取和写入~/.openclaw/下的目录。

3.3 飞书机器人接入（可选但推荐）

飞书在国内访问稳定，且支持图片消息，是使用朱批录的绝佳渠道。配置稍复杂，但一劳永逸。

1. 创建飞书机器人：登录飞书开放平台，创建一个企业自建应用，获取app_id和app_secret。
2. 启用接收消息能力：在应用的功能权限中，启用“接收消息”和“发送消息”。
3. 配置事件订阅：在事件订阅页面，设置请求网址URL（你需要有一个公网IP或使用内网穿透工具，如ngrok，将本地OpenClaw的端口暴露出去）。验证令牌和加密密钥需要记录下来。
4. 修改OpenClaw配置：在OpenClaw的workspace.yaml中，应该有专门配置飞书连接的部分，填入上面获取的app_id,app_secret,verification_token,encryption_key等信息。
5. 配置朱批录的飞书文档同步（可选）：如果你想使用“同步到飞书”功能，还需要在飞书云文档中创建一个表格，并获取其app_token和table_id。然后，将项目assets/目录下的config.example.json复制为config.json，并填入你的飞书文档信息。

详细的飞书配置步骤，项目中的assets/workspace-example.yaml文件提供了非常清晰的模板，你可以直接参考复制。

3.4 首次运行与测试

配置完成后，重启你的OpenClaw服务。

# 在OpenClaw主目录下，通常这样重启 npm run restart # 或者根据你的启动方式，可能是 pm2 restart openclaw

重启后，在你配置的飞书或Telegram群里，@一下你的机器人或者直接给它发一条消息，比如“你好”。朱批录应该会回复一条欢迎信息，介绍它的基本功能。这说明技能已经成功加载。

现在，你可以开始真正的测试了：

1. 文本汇报：发送“今天行测，言语理解错了3道，判断推理错了5道”。
2. 图片识别：找一道行测错题，截图后发送给机器人。
3. 功能指令：发送“导出错题本”，检查是否能收到Excel文件。发送“我最近怎么样”，查看统计分析。

4. 高级使用技巧与个性化定制

基础功能用熟后，你可以通过一些调整，让朱批录更贴合你的个人备考习惯。

4.1 适配不同类型的公职考试

朱批录默认的科目映射是针对国考行测的五大模块（言语、判断、数量、资料、常识）。但省考、事业单位、军队文职的科目名称和划分可能不同。

你可以修改assets/module_map.json文件来实现适配。这个文件定义了关键词别名映射。例如，事业单位《职业能力倾向测验》可能把“判断推理”叫做“逻辑判断”，把“言语理解”叫做“言语表达”。你可以在module_map.json里添加：

{ "逻辑判断": "判断推理", "言语表达": "言语理解", "策略制定": "判断推理", // 将事业单位特有题型映射到相近大类 ... }

这样，当你汇报“逻辑判断错了4道”时，系统会自动将其归类到“判断推理”模块下进行统计。

对于差异更大的考试（如军队文职的专业科目），你可以Fork这个项目，直接修改parse_input.js中关于模块列表的定义，并相应调整daily_summary.js中的分析逻辑，打造一个完全为你目标考试定制的版本。

4.2 优化AI识别提示词（Prompt）

如果你发现某个AI模型（比如你用的Kimi）对图形推理题的描述总是不准确，可以针对性优化Prompt。提示词模板主要在scripts/parse_input.js的buildImagePrompt函数中。

优化的方向可以包括：

• 更具体的格式要求：对于图形推理，明确要求按“图形构成（点、线、面、角、素）”、“位置变化（平移、旋转、翻转）”、“样式规律（叠加、遍历）”等维度进行描述。
• 提供例子（Few-shot）：在Prompt中加入一两个正确描述的例子，让AI模仿。
• 限制输出长度：要求“visual_description”字段控制在100字以内，避免生成冗长废话。

修改后记得重启OpenClaw服务使改动生效。

4.3 错题本Excel的深度利用

导出的Excel错题本（备考记录_日期.xlsx）是一个宝藏。除了本地查看，你可以：

1. 二次分析：将这个Excel文件直接上传到Kimi、ChatGPT等AI助手，让它基于所有错题数据，为你生成一份更详细的《薄弱知识点诊断报告》和《后续两周复习计划建议》。
2. 手动筛选与标记：在Excel中，你可以方便地根据“模块”、“错误原因”、“状态”进行筛选。例如，筛选出所有“知识点不会”且“状态”为“待二刷”的图形推理题，集中攻克。
3. 定期清零与复盘：建议每两周或一个月，将已经掌握、二刷正确的题目“状态”改为“已掌握”，并在文件中新建一个Sheet存档。保持当前错题本的清爽，只聚焦于最新的、未解决的难题。

4.4 数据备份与迁移

所有数据都在本地，备份非常简单。只需定期压缩复制~/.openclaw/skills/kaogong-study-tracker/data/这个目录即可。

如果你想换电脑，或者重装系统，迁移步骤是：

1. 在新电脑上安装OpenClaw和朱批录Skill（重复3.1和3.2步）。
2. 将旧电脑上备份的data/目录整体覆盖到新电脑的对应路径。
3. 重启OpenClaw，你的所有历史记录就都回来了。

5. 常见问题排查与实战心得

在实际使用和与一些早期用户交流的过程中，我总结了一些典型问题和解决方案。

5.1 图片识别失败或不准

这是最常见的问题。

• 现象：机器人回复“识别失败，请直接发送题目文字”，或者识别出的题目内容乱七八糟。
• 排查步骤：
  1. 检查截图质量：确保截图清晰、完整，包含了题目、选项和你的错误答案标记。避免截图上有大量无关内容或文字重叠。
  2. 检查AI模型配置：确认你的OpenClaw中配置的多模态模型API是有效的，且有足够的余额或调用次数。
  3. 查看OpenClaw日志：运行pm2 logs openclaw（如果你用PM2管理）或直接查看OpenClaw的输出日志，里面通常会有模型调用的详细错误信息，例如API密钥错误、网络超时等。
  4. 尝试手动输入：如果图片识别始终不行，这是“失败软降级”设计发挥作用的时候。直接复制粘贴题目文字和你的错误选项发给机器人，效果是一样的。不要因为识别问题放弃记录。

5.2 定时总结消息没有发送

• 现象：到了设定时间（如21:00），没有收到总结消息。
• 排查步骤：
  1. 检查Cron表达式：确认workspace.yaml中的schedule设置正确。可以用在线的Cron表达式验证工具检查。
  2. 检查OpenClaw服务状态：确保OpenClaw服务在后台正常运行，没有崩溃。pm2 list查看状态。
  3. 检查渠道配置：确认channel设置的值（如feishu）与你在OpenClaw中配置的某个聊天渠道的name完全一致，且该渠道连接正常（能收發普通消息）。
  4. 查看定时任务日志：OpenClaw的日志中会记录定时任务的触发和执行情况，查看是否有错误信息。

5.3 导出Excel失败或文件损坏

• 现象：发送“导出错题本”后，机器人没有反应，或收到的文件无法打开。
• 排查步骤：
  1. 检查依赖：确保npm install成功安装了所有依赖，特别是处理Excel的库（如exceljs）。有时网络问题会导致安装不完整，可以删除node_modules文件夹和package-lock.json，重新运行npm install。
  2. 检查文件权限：确保OpenClaw进程有权限在data/exports/目录下创建和写入文件。
  3. 检查数据内容：如果wrong_questions.json文件格式损坏（例如JSON格式错误），导出脚本可能会失败。可以尝试用JSON格式化工具验证一下该文件的有效性。

5.4 性能与存储空间

• 担心：截图以Base64形式存储，会不会占用很大空间？
• 解答：一张普通的手机截图，转换成Base64文本后，大小大约在几百KB。即使你每天记录20道带截图的错题，一个月也就几十MB。对于现代电脑的硬盘来说微不足道。项目设计时也考虑过存储优化，例如可以定期清理exports/目录下的旧Excel文件。核心的wrong_questions.json是纯文本，体积更小。

我个人最深刻的实战心得是：工具的价值在于坚持使用。朱批录把记录错题的成本从“10分钟”降到了“10秒钟”，但这10秒钟的动作，需要你养成习惯。我的建议是，每次做完题对完答案，趁着记忆还新鲜，立刻打开聊天窗口，把错题截图或成绩发出去。让这个动作成为你刷题闭环的一部分。坚持两周，当你回顾自动生成的错题本和趋势图时，你会清晰地看到自己的进步轨迹和顽固弱点，这种数据驱动的反馈，会比任何模糊的感觉都更能指导你高效备考。