# WORKFLOW v1.0

最后更新: 2026-05-28
本文件是流程 single source of truth。任何流程改动都更新本文件并追加到 [CHANGELOG.md](CHANGELOG.md)。

---

## 角色分工

| 角色 | 干啥 | 不干啥 |
|------|------|--------|
| TG @nate_hermes_001_bot | 接口：用户拍题、回 push 通知 | 不识别题、不讲解、不归档 |
| HK Hermes (GLM-5.1) | router：收图存 inbox、ssh Mac 调 Claude、转发回复 | **不讲题**（智力降级红线）|
| Mac Claude Code | 大脑：识别 + 讲 + 归档 + 知识点串联 + 自我迭代 | 不做 SRS（v1.1）、不做 dashboard（v1.2）|

## 主循环：拍题 → 讲 → 归档

### Hermes 端（math-tutor skill 触发）

1. 用户在 TG 发图（可能附文字"哪步开始懵"）
2. Hermes 把图存到 `/opt/math-inbox/<YYYY-MM-DD-HHMMSS>.jpg`，文字（若有）存同名 `.txt`
3. Hermes ssh Mac：
   ```
   ssh natexu@100.119.8.14 \
     "cd ~/MyProjects/compass/math && \
      /Users/natexu/.local/bin/claude-remote -p '处理 inbox 新题，按 WORKFLOW.md 走主循环' \
      --dangerously-skip-permissions \
      --allowedTools 'Read,Edit,Write,Bash' --max-turns 30 < /dev/null"
   ```
4. 拿 stdout 转回 TG
5. Mac offline（ssh 超时 10s）→ TG 回："Claude 不在，已存第 N 题在 inbox。在线后会主动通知。"

### Mac Claude Code 端（被 ssh 触发）

1. `scripts/pull-inbox-from-hk.sh` 拉新文件到 `inbox/`
2. 对每张图：
   - Read 工具读图 → OCR 题面
   - 不清楚则输出 `ASK: <反问>`（Hermes 转给 TG，等下次循环）
   - 读对应 .txt 用户描述 → 定位错因（概念/思路/计算/表达）
   - 生成下一个序号 `MMDD-NNN`（当天起 001 递增；扫 `mistakes/YYYY/MM/MMDD-*.md` 取最大）
   - 写 `mistakes/YYYY/MM/MMDD-NNN.md`（schema 见下"错题文件 schema"）
   - 把 inbox 图 mv 到 `mistakes/YYYY/MM/MMDD-NNN.jpg`
   - 创建/更新 `kp/<科目>/<章>/<节>.md`（不存在按 `kp/INDEX.md` 路径建）
   - 追加反向引用到知识点页"错题反向引用"段
   - grep frontmatter 找历史相似题（同 kp 或同 errors）→ 输出"相关错题 N 道：[link]"
3. 全部处理完 → `git add . && git commit -m "math: 归档 N 道 (MMDD-NNN..NNN)"`
4. `git push hk main`
5. ssh hk 删除已处理的 inbox 原件
6. 输出讲解汇总到 stdout（Hermes 拿这个转回 TG）

## 自我迭代循环（`#改` hashtag）

### Hermes 端

1. 用户 TG 消息以 `#改` / `#改 ` / `#改：` / `#改:` 开头 → 不走主循环，走反馈流
2. ssh Mac：
   ```
   ssh natexu@100.119.8.14 \
     "cd ~/MyProjects/compass/math && \
      /Users/natexu/.local/bin/claude-remote -p '收到反馈：\"<原文>\"。按 WORKFLOW.md 自我迭代循环处理' \
      --dangerously-skip-permissions \
      --allowedTools 'Read,Edit,Write,Bash' --max-turns 20 < /dev/null"
   ```
3. 拿到 diff → 转回 TG（前缀 "已按反馈改动，diff:"）

### Mac Claude Code 端

1. 解析反馈，定位要改 `WORKFLOW.md` 还是 `hermes-skills/learning/math-tutor/SKILL.md`
2. Edit 对应文件
3. 追加一条到 `CHANGELOG.md`：
   ```
   ## YYYY-MM-DD
   - **反馈**: <原文>
   - **改动**: <一句话摘要>
   - **影响**: WORKFLOW.md / SKILL.md
   ```
4. `git commit -m "workflow: <一句话改动>"`
5. `git push hk main`
6. 若改的是 `hermes-skills/`：跑 `scripts/sync-skills-to-hk.sh`（rsync 到 HK + restart hermes-gateway-telegram_bot）
7. 输出 `git diff HEAD~1` 到 stdout

## 错因 4 分类

| 标签 | 触发条件 | 治法 |
|------|---------|------|
| 概念错 | 用户描述"不知道这是干啥"/"没学过" | 补讲概念，链接到知识点页 |
| 思路错 | 用户描述"看错了/想偏了/没想到要用 X 方法" | 拓展同类题、对比正反例 |
| 计算错 | 用户描述"知道思路但中间算错了" | 列出常错步骤，建议计算专项 |
| 表达错 | 用户描述"我做对了但答案规范不符" | 给标准答题模板 |

## 错题文件命名约定

- 当天序号：`MMDD-NNN`，NNN 从 001 起，按当天处理顺序
- 目录：按月分 `mistakes/YYYY/MM/`
- 原图与 md 同名：`0528-001.md` + `0528-001.jpg`

## 错题文件 schema

```markdown
---
id: 0528-001
date: 2026-05-28
kp: [高数/不定积分/换元积分法/三角代换]
errors: [思路错]        # 概念错 / 思路错 / 计算错 / 表达错
srs: { box: 1, next: 2026-05-30 }   # v1.1 加，v1 可省
source: 张宇1000题 P45 第3题          # 用户没说则省
related: [0521-003]                  # 双链到相似题
image: 0528-001.jpg
---

## 题面
（OCR + 修正后的文本）

## 你的做法
（用户的解题步骤；用户没具体说则写"未提供"）

## 错在哪
（具体哪一步、为什么错）

## 正确思路
（关键转折点 + 完整推导）

## 易混点 / 同类题
（这题踩的坑 / 历史相似错题链接）
```

## 知识点页 schema

```markdown
---
name: 换元积分法
parent: 高数/不定积分
related: [高数/不定积分/分部积分法, 高数/定积分/换元法]
---

## 核心要点
（一句话总结这章是干啥的、和别的方法的边界）

## 常见考点
- 三角代换（√(a²-x²), √(a²+x²), √(x²-a²)）
- 倒代换
- ...

## 易混点
- 跟某 X 方法的区别 / 边界

## 错题反向引用（自动维护）
- [[0528-001]] 三角代换符号搞错
- [[0521-003]] 倒代换没想到
```

## 知识点 taxonomy 规则

- 按需创建，不预建空壳
- 路径来自 `kp/INDEX.md`，如 `高数/不定积分/换元积分法/三角代换`
- 每个知识点页有反向引用段，错题归档时自动 append
- 知识点 4 段：`核心要点 / 常见考点 / 易混点 / 错题反向引用`

## Mac 离线兜底

- Hermes ssh 超时 10s → 视为 Mac offline
- TG 回固定话术，inbox 文件保留在 HK
- Mac 下次启动 zshrc hook 提示"inbox 有 N 张待处理"（hook 见 README.md，用户自行装到 ~/.zshrc）

## Hermes profile skill 改动规则

- skill 文件改动 = startup-cache，必须 restart `hermes-gateway-telegram_bot.service` 才能生效
- `scripts/sync-skills-to-hk.sh` 已包含 rsync + restart 两步，不要手动改 HK 上 skill 文件
- 改完一定 commit + push，Mac 上的 `hermes-skills/` 是 source of truth

## 不在 v1 范围（明确不做）

- SRS 提醒、进度看板、Hindsight 索引、定期复盘 subagent
- 整卷模式、讲解档位、学习计划
- 公开题库爬取