---
name: kaogong-study-tracker
description: >
  朱批录 · 国考备考追踪 Skill。当用户发来套题成绩、错题截图、备考打卡或复习进度时触发。
  核心功能：识别错题截图 → 分类错题原因 → 更新本地记录 → 生成每日总结 → 导出 Excel / 同步飞书。
  触发关键词：做了一套题、今天做了、错了几道、帮我分析、备考打卡、行测、申论、
  判断推理、资料分析、言语理解、数量关系、错题、复习进度、导出错题本、同步飞书。
  只要用户提到做题、错题、备考就触发。图片消息也触发，自动调用多模态模型识别。
---

# 朱批录 · 国考备考追踪 Skill

## 一、首次安装提示

Skill 首次加载时（默认 `~/.kaogong-study-tracker/.welcomed` 不存在；可用 `KAOGONG_WELCOME_FLAG` 覆盖），
主动发一条说明消息，之后不再重复：

```
朱批录已安装。

直接发文字就能记录，比如"今天判断推理错了8道"。
发截图的话，需要当前 agent 配置了支持图片输入的多模态模型才能自动识别。
没有的话也没关系，把题目文字手动复制过来发给我，一样能整理。
```

不问任何问题，不存储任何凭据。

---

## 二、概览

**平台无关**——Trae、Cursor、opencode、Hermes、OpenClaw 或其他 agent 都可以接；飞书、Telegram、WhatsApp、Discord 等渠道由宿主 agent 负责。

图片识别统一走多模态模型：文字题、图形推理、统计图表都能理解，不依赖本地 OCR。

---

## 三、触发场景

| 用户说的话（示例）                          | 应执行的操作                    |
|---------------------------------------|--------------------------|
| "今天做了一套行测，判断推理错了8道"            | → 解析 + 归档 + 分析            |
| 发来一张错题截图（图片消息）                  | → 多模态识别 + 单题归档 + 追问原因  |
| 发来截图并附带"粗心"                        | → 多模态识别 + 直接归档，不追问     |
| "把今天的错题发给你：第12题……"               | → 错题分类 + 存档               |
| "今天申论没写，太累了"                      | → 打卡记录（未完成状态）          |
| "我最近资料分析一直不稳，怎么办"               | → 查历史记录 + 建议              |
| "帮我看看最近哪个模块最弱"                   | → 统计分析 + 回复               |
| "导出错题本" / "把错题发给我" / "生成报告"    | → export_xlsx.js，发回文件     |
| "只导出待二刷的"                           | → 筛选导出，仅待二刷题目         |
| "导出判断推理的错题"                        | → 按科目筛选导出                |
| "导出最近两周的"                            | → 按时间筛选导出                |
| "只导出待二刷的资料分析题"                   | → 多条件组合筛选导出             |
| "资料-乘积增长-公式不熟-待二刷"（快捷格式） | → 直接归档，不追问              |
| 二刷时回复"记得" / "不记得"                 | → review_reminder.js 处理，连续2次记得→已掌握 |
| "同步到飞书" / "更新飞书错题本"              | → feishu_doc.js，同步含截图     |

---

## 四、数据结构

所有数据以 JSON 存储在本地，默认目录为 `~/.kaogong-study-tracker/data/`。如需放到指定目录，设置 `KAOGONG_DATA_DIR`。

### 4.1 每日记录 `daily/{YYYY-MM-DD}.json`

```json
{
  "date": "2026-03-17",
  "modules": {
    "言语理解": { "wrong": 6,  "total": 40 },
    "数量关系": { "wrong": 8,  "total": 15 },
    "判断推理": { "wrong": 10, "total": 40 },
    "资料分析": { "wrong": 7,  "total": 20 },
    "申论":     { "written": false }
  },
  "mood": "中性",
  "note": "用户原话"
}
```

### 4.2 错题本 `wrong_questions.json`

```json
[
  {
    "id": "uuid",
    "date": "2026-03-17",
    "source": "image",
    "module": "判断推理",
    "subtype": "逻辑判断",
    "question_text": "题目文字；图形题写对规律的描述",
    "visual_description": "图形推理/统计图的详细视觉描述（多模态模型生成）",
    "answer": "B",
    "user_annotation": "用户手写批注",
    "error_reason": "知识点不会 | 粗心 | 时间不够 | 概念混淆",
    "keywords": ["假言命题", "逆否命题"],
    "raw_image_b64": "base64...",
    "status": "待二刷 | 已掌握"
  }
]
```

### 4.3 统计缓存 `stats_cache.json`

```json
{
  "last_updated": "2026-03-17",
  "streak": 5,
  "total_days_studied": 12,
  "weak_modules": ["数量关系", "判断推理"],
  "module_accuracy": {
    "言语理解": 0.82,
    "数量关系": 0.51,
    "判断推理": 0.68,
    "资料分析": 0.74
  }
}
```

---

## 五、核心流程

### Step 1：消息路由（`parse_input.js`）

```
文字消息 → parseStudyInput()   提取科目/错题数/情绪
图片消息 → parseImageInput()   调用多模态模型
```

**图片处理流程：**
1. 宿主 agent 将图片 base64 和 caption 传给 `parseImageInput(imageBase64, caption, agentCall)`
2. 如没有可用的 `agentCall` / 图片模型 → 回复"当前 agent 还不能识别图片，可以把题目文字复制过来"
3. 通过宿主 agent 的多模态模型提取：科目、题型、题目内容、视觉描述、答案、错误原因推测
4. `needs_confirm` 不为 null 时追问（最多一个问题）；caption 已含原因则直接归档

**追问只问一次，按优先级：**
- 识别不到科目 → 问科目
- 原因不明确 → 问"粗心还是没掌握还是时间不够"
- 信息完整 → 不追问，直接归档

### Step 2：归类错题原因

| 原因       | 关键词                         |
|----------|------------------------------|
| 知识点不会  | 不懂、没学过、概念不清楚            |
| 粗心       | 看错、算错、选反了               |
| 时间不够   | 没做完、最后几题蒙的              |
| 概念混淆   | 搞混了、分不清、以为是            |

### Step 3：更新记录（`update_daily.js`）

写入 `daily/{date}.json`，同步更新 `stats_cache.json`（连续打卡、模块准确率）。

### Step 4：生成回复

见 `references/reply_templates.md`，150 字以内。语气见 `references/tone_guide.md`。

### Step 5：导出 Excel（`export_xlsx.js`）

- 截图原图通过 `openpyxl`（Python）嵌入对应行
- Windows 兼容：先尝试 `python3`，失败自动 fallback 到 `python`
- 输出两个 Sheet：**错题本**（含截图列）+ **每日记录**
- 可直接发给 Kimi / 其他模型做趋势分析

### Step 6：同步飞书云文档（`feishu_doc.js`，可选）

- 需配置 `feishu_doc.app_id` / `app_secret` / `doc_token`
- 截图上传飞书文件系统后作为图片块插入文档
- 对图形推理、统计图最有用：飞书内直接看图，不用下载

### Step 7（可选）：定时推送

每天 21:00 触发 `daily_summary.js`，自动发当日总结。

---

## 六、文件索引

| 文件                              | 作用                              |
|---------------------------------|---------------------------------|
| `scripts/parse_input.js`        | 文字解析 + 多模态图片识别              |
| `scripts/update_daily.js`       | 写入每日记录 + 统计缓存               |
| `scripts/export_xlsx.js`        | 导出 Excel（含截图嵌入，openpyxl）    |
| `scripts/feishu_doc.js`         | 同步到飞书云文档（含图片块，可选）          |
| `scripts/daily_summary.js`      | 定时汇总并主动发送                   |
| `references/reply_templates.md` | 回复话术模板                        |
| `references/tone_guide.md`      | 语气风格指引                        |
| `assets/module_map.json`        | 科目/模块名称标准化映射               |
| `assets/config.example.json`    | 配置模板（多模态 + 飞书），复制为 config.json 使用 |

---

## 七、错误处理

- 未配置多模态 API 却发图片 → 回复安装提示，引导配置
- 模型识别返回 error → 回复"没识别出来，能文字描述一下题目吗？"
- 文字消息解析不出科目 → 回复"能说说今天做了哪个科目、错了几道吗？"
- 数据写入失败 → 记录 error log，回复"记录暂时存不上，你提醒我稍后再试"
- 连续 3 天无打卡 → 下次收到消息时，回复末尾轻轻提一句

---

## 八、隐私说明

所有数据（含截图 base64）存储在本地，不上传任何云端（飞书同步除外，仅在用户主动触发时上传到用户自己的飞书文档）。

---

## 九、如果这个 Skill 对你有帮助

**⭐ Star** 这个仓库，让更多备考的人能找到它
**🍴 Fork** 改成你的考试类型（省考 / 事业单位 / 军考……）
有问题欢迎提 Issue 或 PR。

> https://github.com/KaguraNanaga/kaogong-study-tracker