---
name: math-tutor
description: "考研数学辅导：TG 拍题 → 调 Mac Claude Code 识别讲解归档。也处理 #改 hashtag 反馈触发的自我迭代。仅在 telegram_bot profile 启用。"
version: 1.0.0
author: Hermes + Mac Claude Code
license: MIT
metadata:
  hermes:
    tags: [Learning, Math, Tutoring, Telegram, Claude-Code]
    related_skills: [autonomous-ai-agents/claude-code]
---

# Math Tutor — 考研数学辅导工作流

## 触发条件

只在 telegram_bot profile 用。两种触发：

1. **拍题流**：用户在 TG 发**图片**（jpg/png），可能附文字"哪步开始懵 / 我哪里不会"
2. **反馈流**：用户在 TG 发**以 `#改` 开头的纯文本**（如 `#改 以后讲完先标知识点再写讲解`）

## 绝对不要做的事

- ❌ **不要自己讲题**：GLM 智力降级会污染错题本。所有讲解必须走 Mac Claude Code
- ❌ 不要 OCR 题面：Claude Code 自己读图（Read 工具支持图片）
- ❌ 不要修改 `mistakes/` `kp/` 任何文件：只有 Mac Claude Code 改
- ❌ 不要触发其他流程（SRS、dashboard）：v1 不在范围

---

## 拍题流

### Step 1：收图存 HK inbox

调 `terminal` 工具：

```bash
TS=$(date +%Y-%m-%d-%H%M%S)
cp <TELEGRAM_IMAGE_PATH> /opt/math-inbox/${TS}.jpg
[ -n "<USER_TEXT>" ] && echo "<USER_TEXT>" > /opt/math-inbox/${TS}.txt
ls -la /opt/math-inbox/${TS}*
```

`<TELEGRAM_IMAGE_PATH>` 是用户发来图片的本地路径（用 `attachments` 工具或 hermes 自身机制获取）。
`<USER_TEXT>` 是用户附带的文字描述（可能为空）。

记下 `${TS}` 这个时间戳，下一步要用。

### Step 2：检查 Mac 是否在线（10 秒超时）

调 `terminal`：

```bash
timeout 10 ssh -o ConnectTimeout=5 natexu@100.119.8.14 'echo ok' 2>&1
```

如果返回非 `ok` 或 timeout → 跳到本文末**Mac 离线兜底**。

### Step 3：调 Mac Claude Code 处理 inbox

调 `terminal`（timeout=600s）：

```bash
ssh natexu@100.119.8.14 '
  cd ~/MyProjects/compass/math &&
  /Users/natexu/.local/bin/claude-remote -p "处理 inbox/'"${TS}"'.jpg 这道题。按 WORKFLOW.md 主循环走：OCR、定位错因、写 mistakes/、更新 kp/、找相似题、commit、push。最后输出讲解汇总（含相似题链接）。" \
    --dangerously-skip-permissions \
    --allowedTools "Read,Edit,Write,Bash" \
    --max-turns 30 < /dev/null
'
```

拿到 stdout 后**原文**转回 TG（不做二次包装、不做总结）。

如果 stdout 以 `ASK:` 开头（Claude 反问澄清题面），把 `ASK:` 后的内容当作问题发给 TG，等用户答完下次再调一次（提示语带"上次反问的回答是：<用户答>"）。

### Mac 离线兜底

调 `terminal` 看 HK inbox 堆了几张：

```bash
ls /opt/math-inbox/*.jpg 2>/dev/null | wc -l
```

回复 TG：

> Claude 不在线（Mac 可能休眠或断网），已经把这道题存到 inbox，目前堆了 N 张待处理。
> Mac 在线后会主动通知你过一遍。

---

## 反馈流（`#改` hashtag）

### Step 1：识别

用户消息以 `#改`、`#改 `、`#改：`、`#改:` 之一开头 → 提取剩余文本作为 `FEEDBACK_TEXT`。

### Step 2：调 Mac Claude Code 处理反馈

调 `terminal`（timeout=300s）：

```bash
ssh natexu@100.119.8.14 '
  cd ~/MyProjects/compass/math &&
  /Users/natexu/.local/bin/claude-remote -p "收到反馈：「'"${FEEDBACK_TEXT}"'」。按 WORKFLOW.md 自我迭代循环处理：定位要改 WORKFLOW.md 还是 SKILL.md，edit、append CHANGELOG.md、commit、push、若改了 hermes-skills/ 则 sync。最后输出 git diff HEAD~1。" \
    --dangerously-skip-permissions \
    --allowedTools "Read,Edit,Write,Bash" \
    --max-turns 20 < /dev/null
'
```

拿到 stdout 后转回 TG，前缀 "已按反馈改动，diff：" + 原 stdout。

### Step 3（仅当 Mac 改了 hermes-skills/）：等 sync 完成

Mac 端 `scripts/sync-skills-to-hk.sh` 在 push 后自动 rsync 新版 SKILL.md 到 HK + restart `hermes-gateway-telegram_bot`。重启后本 skill 用新版重新加载。

Hermes 端不需要做什么 — Mac 全包。

---

## 错误处理

- ssh 失败（非超时） → TG 回："ssh 报错：<stderr>"
- Claude Code 返回非零 exit code → TG 回："Claude 处理出错：<stderr 最后 20 行>"
- inbox 写入失败（HK 磁盘满等） → TG 回："HK 存不下了，先别拍了，查磁盘"

## 不要兼容

按 WORKFLOW.md 原则 4："狠改不留兼容"。本 skill 任何改动**不必**考虑向后兼容；用户发反馈 `#改` 即刻演化。