| name | wrong-answer-book |
| description | 魔法错题本 — 试卷图片自动识别与错题管理工具。
上传试卷照片后，自动完成去重校验、调用腾讯云 SubmitQuestionMarkAgentJob API 识别批改、
提取错题信息、按可读格式生成错题库 Markdown 文件，并维护统计索引支持按科目/年级等维度查询。
支持按试卷级或单题级删除错题记录。
当用户发送 /wrong-answer-book 命令或上传试卷图片并表达"录入错题"、"分析试卷"、
"错题本"等意图时触发。
|
魔法错题本 Skill
触发方式
通过以下任一方式触发本 Skill：
- 发送命令：
/wrong-answer-book
- 上传试卷图片并表达意图：
录入错题、分析试卷、错题本、帮我看看这张卷子
- 查询统计：
数学有多少错题、三年级错了几道、列出错题、错题统计
- 删除记录：
删除 [1]、删除 1.2、删除错题
- 掌握标记：
掌握了 1.1、1.2 已掌握、标记 1.3 已掌握、1.1 还没掌握、取消掌握 1.2
使用方式
录入错题
/wrong-answer-book
然后上传试卷图片，或直接发送图片并附上说明（如"帮我分析这张语文卷子的错题"）。
查询统计
直接提问即可，无需命令前缀：
语文有多少错题？
三年级的错题有几道？
列出错题 / 错题统计
标记掌握
当某道错题已掌握时，可标记为"已掌握"，方便追踪复习进度：
掌握了 1.1 → 标记 [1] 中第 1 个错题为「✅ 已掌握」
1.2 已掌握 → 同上
取消掌握 1.1 → 取消已掌握标记
1.2 还没掌握 → 同上
也可以在查看单题详情后直接说「这题我掌握了」。
删除记录
先通过「列出错题」获取编号，然后：
删除 [1] → 删除整份试卷记录（含图片）
删除 1.2 → 只删除记录1里的第2个错题
执行流程
阶段1：接收图片并去重检查
用户上传试卷图片后，先验证去重，确认不重复后再保存。
操作步骤：
- 校验图片格式（支持 jpg / jpeg / png / webp），文件大小不超过 10MB
- 计算图片的 MD5 哈希值（使用
md5sum 或 Python hashlib.md5）
- 读取
wrong-answer-book/.index.json，在索引记录的 md5 字段中查找当前图片的 MD5
- 如果 命中已有记录：
- 告知用户：该图片已录入过（显示录入时间、对应科目、错题数）
- 询问用户是否需要查看已有错题库或重新录入（覆盖）
- 如果用户选择重新录入，继续步骤5（更新
created_at 但不追加新记录）
- 如果用户放弃，流程终止，不保存图片
- 如果 未命中（或用户选择覆盖）：
- 将图片以
{MD5}.{ext} 为文件名，保存到 wrong-answer-book/images/ 目录
- 输出确认信息：图片已保存，MD5 为
xxx
通过条件：
- 图片格式合法，MD5 哈希已计算
- 去重检查已完成（新图片 或 用户同意覆盖）
- 图片已保存到
images/ 目录
阶段2：调用腾讯云 API 识别批改
调用腾讯云 OCR SubmitQuestionMarkAgentJob 接口对试卷图片进行识别和批改。
操作步骤：
- 检查认证信息：读取项目根目录
credentials.md，检查 SecretId 和 SecretKey 是否已配置（不是占位符 <YOUR_SECRET_ID> / <YOUR_SECRET_KEY>）
- 如果文件不存在或未配置：提示用户复制 Skill 内置的
assets/.credentials.md 为 credentials.md 并填入真实密钥，流程中止
- 执行
scripts/submit_question_mark.py，传入已保存的图片路径：
pip install tencentcloud-sdk-python
python scripts/submit_question_mark.py wrong-answer-book/images/{MD5}.{ext}
- 捕获脚本的 stdout 输出（JSON），stderr 中会打印 JobId 等进度信息
- 如果脚本执行失败（API 报错、超时等），提示用户错误信息，流程中止
详细的 API 接口规范、请求参数、响应字段说明参见 references/api-spec.md。
通过条件：
- API 调用成功，获取到试卷识别和批改的结构化数据
- 数据中包含题目列表（含正确答案和学生作答信息）
阶段3：分析错题数据
解析 API 返回的数据，提取错题并整理分析。
操作步骤：
- 解析 API 响应的题目列表，逐一比对每道题的「学生答案」与「正确答案」
- 标记答案不匹配的题目为错题
- 对每道错题，结合题目类型和答案差异，分析可能的错误原因（如：概念混淆、计算错误、审题不清、知识盲区等）
- 汇总薄弱知识点，诊断学生的知识薄弱环节
- 提取元数据信息（尽量推断，不强求）：
- 科目（subject）：从题目内容或上下文推断（如含"语文""数学""英语"字样）；无法推断则设为
未知
- 年级（grade）：同理推断；无法推断则设为
未知
- 试卷名称（exam_name）：从题目内容推断（如"期中""月考"等）；无法推断则留空
- 以上信息缺失不阻塞流程，后续可通过编辑错题库文件补充
- 统计：
wrong_count：错题总数total_questions：总题数- 各知识点错题分布
通过条件：
- 错题列表完整提取
- 每道错题有错误原因分析
- 统计数据已计算
阶段4：写入错题库
生成可读性强、支持统计查询的错题库文件。
操作步骤：
- 参照
assets/wrong-answer-book-template.md 的格式规范，生成 Markdown 错题库文件
- 文件保存路径：
wrong-answer-book/错题库_{年级}{科目}_{试卷名称}.md
- 可读性要求（硬性）：
- 使用清晰的
# ## ### 标题层级
- 试卷信息用 blockquote
> 展示
- 错题统计用 Markdown 表格
- 每道错题使用分隔线
--- 隔开
- 错题包含：题目原文、我的答案、正确答案、错误原因、知识点标签
- 末尾附薄弱知识点诊断和巩固建议
- 文档末引用原始试卷图片：
- 整体排版舒适，方便屏幕阅读和打印
- 更新
wrong-answer-book/.index.json，追加新记录：
{
"md5": "...",
"image": "images/{MD5}.{ext}",
"file": "错题库_{年级}{科目}_{试卷名称}.md",
"subject": "语文",
"grade": "三年级",
"exam_name": "期中测试题",
"wrong_count": 3,
"total_questions": 20,
"mastered": [],
"created_at": "2026-05-29T15:00:00"
}
- 输出完成信息：
- 错题库文件路径
- 本次发现 N 道错题
- 薄弱知识点摘要
- 累计统计（读取索引汇总：总共 N 份卷子、M 道错题）
通过条件：
- 错题库 Markdown 文件已生成，排版清晰可读
.index.json 已更新- 用户已获知本次和累计统计结果
查询与删除
列出错题
本 Skill 支持层级化展示错题记录，格式如下：
📚 错题库 | 共 2 份卷子，5 道错题（2 道已掌握）
[1] 三年级语文 期中测试题 | 2026-05-29 | 2错/14题
├─ 1.1 汉字拼音拼写 — 蜡烛
└─ 1.2 ✅ 音序查字法 — 先查大写字母 [已掌握]
[2] 三年级数学 单元测验 | 2026-05-30 | 3错/10题（1题已掌握）
├─ 2.1 两位数乘法 — 第3题
├─ 2.2 ✅ 单位换算 — 第7题 [已掌握]
└─ 2.3 分数加减 — 第5题
展示规则：
[N] 为试卷级编号，每份试卷一个编号N.M 为单题编号，N=试卷编号，M=题序号✅ 前缀 + [已掌握] 后缀标记已掌握的错题- 试卷行末尾标注
（N题已掌握）
- 头部汇总标注
（N 道已掌握）
- 错题摘要优先用「答错空」字段，其次用知识点名
操作步骤：
- 读取
.index.json，过滤出 wrong_count > 0 的有效记录
- 对每条记录，读取对应
.md 文件，提取 ## 错题统计 表格中每行的「大题」「小题」列
- 组装层级化格式输出
- 如果只有一份试卷且用户问的是个人类问题（如「我的错题有哪些」），则不带试卷编号前缀
查看单题详情
当用户指定查看某个记录或单题时（如 看 [1]、看 1.2），必须输出完整题目信息，包括：
| 字段 | 必出 | 来源 |
|---|
| 大题 | ✅ | .md 文件中错题的 **大题** |
| 原题 | ✅ | .md 文件中错题的 **原题** |
| 答错空 | ✅ | 定位具体空（填空题）/ 具体问（问答题） |
| 我的答案 | ✅ | 学生错误答案 |
| 正确答案 | ✅ | 标准答案 |
| 错误原因 | ✅ | 错误分析 |
| 订正 | ✅ | 订正建议 |
输出格式示例：
--- [1] 三年级语文 期中测试题 | 2错/18题 ---
### 1.1 — 汉字拼音拼写
大题：(一) 根据语境拼写词语 (10分)
原题：(2) zǎo chén ( )一群穿着xiān yàn ( )...
答错空：zǎo chén（第一个空）
| 我的答案 | 早辰 |
| 正确答案 | 早晨 |
| 错误原因 | 「辰」指日月星辰，「晨」才是清晨 |
💡 订正：早晨 = 早 + 晨（日字底）
### 1.2 — ✅ 音序查字法 [已掌握]
大题：(五) 按查字典的知识填空 (7分)
...
禁止摘要式输出。用户看错题就是要看完整信息，不能只有答案对比而没有题目上下文。
标记掌握
支持标记/取消某道错题的掌握状态：
标记已掌握步骤：
- 根据编号
N.M 定位到第 N 份记录的 .index.json 条目
- 将 M 追加到该条目的
mastered 数组中（如果已存在则跳过）
- 读取对应
.md 文件，找到 ## 错题统计 表格中序号为 M 的行，将「状态」列改为 ✅ 已掌握
- 找到第 M 个
### 错题 标题，追加 ✅ 已掌握 后缀
- 输出确认信息
取消掌握步骤：
- 将 M 从
mastered 数组中移除
- 将
.md 表格中「状态」列改回 —
- 从
### 错题 标题移除 ✅ 已掌握 后缀
- 输出确认信息
边界规则：
- 标记时如果
mastered 数量 = wrong_count（全部掌握），额外提示「全部错题已掌握！🎉」
- 用户查看单题详情后说「这题我掌握了」，直接定位当前查看的错题执行标记
统计查询
| 查询示例 | 实现方式 |
|---|
语文有多少错题 | 读取 .index.json，按 subject 过滤，汇总 wrong_count（含已掌握统计） |
三年级错了几道 | 按 grade 过滤，汇总 wrong_count |
还有多少没掌握 | 汇总 wrong_count - len(mastered) |
数学的错题有哪些 | 按 subject 过滤，列出所有相关文件的 file 和 wrong_count |
总体统计 | 汇总全部 wrong_count 和 total_questions，按科目/年级分组展示，标注已掌握进度 |
删除记录
支持两种粒度的删除：
| 操作 | 示例 | 效果 |
|---|
| 删除整份试卷 | 删除 [1] | 删除 .md 文件 + .index.json 对应记录 + 关联图片 |
| 删除单个错题 | 删除 1.2 | 修改 .md 文件移除该错题章节 + 更新 .index.json 的 wrong_count |
删除整份试卷步骤：
- 根据编号找到
.index.json 中的记录
- 删除
wrong-answer-book/{file}
- 删除
wrong-answer-book/{image}
- 从
.index.json 中移除该记录（含 mastered 数组）
删除单个错题步骤：
- 根据编号
N.M 定位到第 N 份记录的 .md 文件
- 读取
.md 文件，定位第 M 个 ### 错题 区块及其前一行 --- 分隔线
- 移除该区块，重新编号后续错题，更新统计表格、诊断、建议
- 将
.index.json 中该记录的 wrong_count 减 1
- 从
mastered 数组中移除对应序号，且 ≥M 的已掌握序号减 1（因为后续序号前移）
- 如果
wrong_count 变为 0，询问用户是否删除整份试卷记录
重要提醒
数据安全
- 腾讯云 API 认证信息（SecretId / SecretKey）独立存储在项目根目录
credentials.md 中，不得在对话中直接展示。模板文件随 Skill 分发（assets/.credentials.md）
.index.json 仅记录文件和元数据索引，不存储原始图片数据- 用户上传的图片保存在
wrong-answer-book/images/ 中
元数据处理
- 科目/年级/试卷名称尽量从题目内容推断，无法推断则用"未知"或留空，不阻塞流程
- 用户可随时通过编辑错题库文件或索引来补充/修正元数据
API 异步调用
SubmitQuestionMarkAgentJob 是异步接口，提交后需轮询 DescribeQuestionMarkAgentJob 查询结果JobStatus 状态值：WAIT（等待中）→ RUN（执行中）→ DONE（完成）/ FAIL（失败）- 轮询间隔建议 3 秒，最长等待 120 秒
- 超时或失败时提示用户，不要静默跳过
去重行为
- 同一张图片不会重复生成错题库文件
- 但用户可以选择"覆盖"重新录入（适用于 API 识别结果需要修正的场景）
- 覆盖时更新
.index.json 中的 wrong_count 和 created_at，不追加新记录
示例交互
示例1：首次录入试卷
用户：/wrong-answer-book + 上传语文期中试卷图片
Skill 处理：
- 阶段1：校验图片 → 计算 MD5 → 查
.index.json → 未命中，保存到 images/abc123.jpg
- 阶段2：调用
SubmitQuestionMarkAgentJob → 等待异步结果 → 获取批改数据
- 阶段3：解析数据 → 发现 3 道错题 → 推断科目"语文"、年级"三年级"、试卷名"期中测试题"
- 阶段4：生成
错题库_三年级语文_期中测试题.md → 更新索引 → 输出总结
最终输出：
✅ 错题库已生成：wrong-answer-book/错题库_三年级语文_期中测试题.md
📊 本次统计：
- 试卷：三年级语文 期中测试题
- 错题：3 道 / 共 20 题
- 薄弱点：近义词辨析、音序查字法、拼音音节书写
📈 累计统计：已录入 1 份卷子，共 3 道错题
示例2：重复图片
用户：上传之前已录入过的同一张图片
Skill 处理：
- 阶段1：计算 MD5 → 查
.index.json → 命中！发现该图片已于 2026-05-29 录入（三年级语文期中，3道错题），不保存图片
输出：
⚠️ 这张试卷已经录入过了：
- 科目：语文 | 年级：三年级
- 试卷：期中测试题
- 录入时间：2026-05-29
- 错题数：3 道
是否需要重新录入（覆盖）？
示例3：列出错题
用户：列出错题
输出：
📚 错题库 | 共 2 份卷子，8 道错题
[1] 三年级语文 期中测试题 | 2026-05-29 | 3错/14题
├─ 1.1 汉字拼音拼写 — 蜡烛
├─ 1.2 音序查字法 — 先查大写字母
└─ 1.3 音序查字法 — 再查音节
[2] 三年级语文 期末模拟卷 | 2026-05-30 | 5错/20题
├─ 2.1 近义词辨析 — 安静/宁静
├─ 2.2 修改病句 — 第4题
├─ 2.3 阅读理解 — 第2问
├─ 2.4 阅读理解 — 第3问
└─ 2.5 作文 — 段落结构
示例4：删除
用户：删除 1.1
Skill 处理：定位 [1] → 读取 .md → 移除错题 1 → 重新编号 → 更新统计
输出：
✅ 已删除 [1] 中的错题 1.1「汉字拼音拼写 — 蜡烛」
📊 [1] 剩余 2 道错题
示例5：标记已掌握
用户：1.1 已掌握
Skill 处理：定位 [1] 的 .index.json → 追加 mastered: [1] → 更新 .md 表格和标题
输出：
✅ 已标记 [1] 中错题 1.1「汉字拼音拼写 — 蜡烛」为已掌握
📊 [1] 进度：1/2 已掌握
示例6：取消掌握
用户：1.1 还没掌握（或查看 1.1 详情后说「这题还是不会」）
输出：
✅ 已取消 [1] 中 1.1 的已掌握标记
📊 [1] 进度：0/2 已掌握
示例7：全部掌握
用户：在已标记 1.1 的基础上，1.2 已掌握
输出：
✅ 已标记 [1] 中错题 1.2「音序查字法 — 先查大写字母」为已掌握
📊 [1] 全部错题已掌握！🎉
参考资料使用
| 场景 | 参考文件 |
|---|
| API 接口规范、请求参数、响应格式 | references/api-spec.md |
| 腾讯云认证信息（SecretId / SecretKey） | credentials.md（项目根，由 Skill 内置模板 assets/.credentials.md 复制） |
| 错题库输出格式模板 | assets/wrong-answer-book-template.md |
| 去重与统计索引 | wrong-answer-book/.index.json |
| 已保存的试卷图片 | wrong-answer-book/images/ |
注意事项
- 本 Skill 仅处理图片格式的试卷，通过腾讯云
SubmitQuestionMarkAgentJob API 完成识别和批改
- API 调用依赖有效的腾讯云账号认证信息，存储在项目根目录
credentials.md 中（从 Skill 内置模板 assets/.credentials.md 复制后填写）
- 所有错题库文件保存在
wrong-answer-book/ 下，图片保存在 images/ 子目录
- 索引文件
.index.json 是统计查询的唯一数据源，务必保持其完整和准确
- 如需删除某份错题库，应同时从
.index.json 中移除对应记录
