StudyFlow · 学习专注流
> 形态：full（全栈工程型）。孩子是主要操作者，家长是督导者；对话、拍照转录、网页工作台三入口读写同一份 ~/.workbuddy/studyflow/data.json。拍照录入主通路 = Agent 直接读图转录（多模态内生能力，零配置）；腾讯云 OCR（ocr_ingest.py）为可选增强——需 TC_SECRET_ID/TC_SECRET_KEY 环境变量，缺省显式降级直读/口述，不阻塞。
> 核心主张：订正 ≠ 掌握——错题按遗忘间隔（1/3/7/14 天）进复习队列，答对降级、答错重置；抄完订正不改等级，只有复习答对才出队。
定位
- 做什么：任务计划（作业→专注单元→今日焦点→复盘）、错题管理（录入→按知识点挂网→间隔复习→错题本）、资料记录（科目+类型内容级归档条目）、日报周报、双端网页工作台。
- 给谁用：初中生（孩子，主操作）+ 家长（督导：看周报、批注错题、调整计划）。
- 数据底座：本地 JSON 单文件
~/.workbuddy/studyflow/data.json（五域：tasks/quizzes/knowledge/review_plan/materials + config 段），零第三方依赖、可人工查看备份。试点科目=数学+英语，扩科=改 config.subjects 即生效。
不做的事（fail-with-direction，拒绝时说清该用什么）：
- 拍照搜题 / 给解法 / 判分批改 → 「本 skill 只录入转写，不给答案」（讲解辅导除外，见消歧表）
- 成人工作待办 / 番茄钟 → focusflow（正交共存，不混用命令）
- 文件改名 / 移动 / 归档操作 → 文档分类管理（本 skill 只记内容级数据条目，对文件系统零直接操作）
- 成绩单分析 / 学校系统抓取 / 在线题库 / 云账号体系 → 拒绝
全局红线（每次执行前自查）
- 串行写库：所有写操作逐条调用，前一条返回再发下一条，禁并行——一次报 10 道错题也逐条
quiz-add。并行写 data.json 会互相覆盖损坏（focusflow 实测铁律）。 - GATE 门禁（机制类型门，非关键词匹配）：删除任何记录 → GATE-1；一次改 ≥3 条 → GATE-2（机器计数 dry-run 清单行数）。执行侧内置：无
gate-checked.json冻结文件，脚本 fail-closed 拒绝（退出码 2）。 - 批量纪律（并排写清，勿混）：批量新增（录多道错题 / 多个任务）= 串行逐条直接执行，不设门；删除 / 批量修改 ≥3 条 = 必过 GATE 勾选确认门。
- 间隔由脚本算：队列推导 / 答对降级 / 答错重置一律调
spaced_repetition.py纯函数，禁 LLM 现算日期。 - 转录必须回显全文等确认才写库（Agent 直读或可选 OCR 通路同规）；失败/低置信显式声明降级转口述录入，不静默。
- 「订正≠掌握」：唯一等级迁移入口是
review-result（复习答对才降级）。
Workflow（7 步）
- 意图路由：命中 5 正触发词或学习场景口语 → 按 triage-rules.md 判六域（任务/错题/资料/复习/报告/工作台）；模糊意图（「今天学啥」）→ 逐步澄清先判场景。
- 读库检态（只读零副作用，不写任何文件）：
python scripts/studyflow.py view|today|queue；data.json 不存在 →init初始化空库并告知。 - 分域执行：
- 任务 = AI 出拆解稿（15–30 分钟专注单元，学生口语措辞）→ 孩子拍板 → 逐条add-task（可带--units）
- 错题 = 拍照 → Agent 直读图转录（可选ocr_ingest.py增强）/ 口述 → 回显全文等确认 →quiz-add
- 资料 = 按 archive-rules.md 出归档建议（文件操作委托文档分类管理）→material-add
- 复习 =queue出今日队列 → 陪练判对错 →review-result写库（孩子说「今天不想复习」→ 选项式：顺延或跳过，不出强制话术） - GATE 判定：删除任何记录 → GATE-1 出待删清单等确认；一次改 ≥3 条 → GATE-2 dry-run 清单勾选（rejected 列表保留）；日常单条写与批量新增直接执行（标准档铁律）。GATE 正例：「把『已知三边求角』那条错题删了，重复录入了」→ 单条明确指认，正常走 GATE-1 出单条清单，不因含「删」字拒答也不跳门。
- 串行写库：逐条调用，前一条返回再发下一条（红线 1）。
- 反馈收尾：操作回执（完成 N/失败 N/未处理 N，含编号）+ 摘要 + 工作台刷新提示（数据变了 → 提示重新生成并打开工作台 HTML）。
- 报告分支：日报/周报 = 文字稿 + HTML 双层推送（present_files）；HTML 生成失败仍发文字并说明原因；改推送时间 = 更新已有自动化 RRULE，禁重复创建。
Clarification Protocol（四型 + 上限）
- 一次性追问：录错题缺「科目+知识点+错因」多个独立字段 → 一次问齐，不逐个追问。
- 逐步澄清：「今天学啥」类模糊意图 → 先判场景（任务/错题/资料/复习）再定后续。
- 选项式（2–4 选项+影响）：复习调整（今天复习/顺延/免复习）；归档去向（讲义/试卷/笔记）；任务拆解粒度确认。
- 关键假设确认（GATE 专用）：GATE-1/GATE-2 触发时复述将删/改条目清单 → 等勾选确认 →
gate prepare→gate confirm→ 执行 → 回报结果。 - 上限：单轮追问 ≤4 问；全程提问批数 ≤4 批；同一问题重问 0 次；⛔ 用户已确认即闭环，禁止软化条款（「你确定吗/还要继续吗」）。
Resource Routing（三层强路由 + 命令速查）
① 正向决策表——命中即 load，before 指先于该动作读：
| If 用户/流程 需要… | load（before） | 产出 |
|---|---|---|
| 判定意图域或遇到易混淆说法 | references/triage-rules.md（before 执行任何写操作） |
六域路由结论 + 消歧处置 |
| 写入/读取任务或错题记录 | references/data-schema.md（before 首次写库/改字段） |
合规 data.json 记录 |
| 拆解作业任务 | references/task-workflow.md（before 出拆解稿） |
学生五步专注单元 |
| 执行间隔复习 | references/review-protocol.md（before 判对错写结果） |
复习结果 + 间隔等级更新 |
| 归档学习资料 | references/archive-rules.md（before 出归档建议） |
内容级归档条目 |
| 接入多端同步 | references/sync-backend.md（before 部署/配置后端） |
双端同步可用 |
| 拼装 CLI 调用 | references/commands.md（before 任何脚本调用） |
正确命令与参数 |
② 易混淆消歧表：
| 像【A】但其实不是 | 别用 | 该用 |
|---|---|---|
| 像「搜题解题」其实是「错题录入」 | 给解法/搜题 API | 转录（直读/可选 OCR）+ 回显确认 + 归队列 |
| 像「讲解请求」其实是正常学习辅导 | 拒答或当搜题 | 正常讲解 + 顺带问是否记错题本（讲解≠给答案代写） |
| 像「成人待办」其实是「学习任务」 | focusflow 命令 | StudyFlow 学生五步 |
| 像「文件归档」其实是「资料记录」 | 直接 mv/改名文件 | 文件操作委托文档分类管理，本 skill 只记数据条目 |
| 像「订正完成」其实是「复习通过」 | 抄完订正就降级 | 仅 review-result 答对才降级 |
③ 跨模块顺序表：录错题【triage-rules → data-schema → review-protocol】；周报【task-workflow → review-protocol → data-schema】；资料整理【archive-rules →（委托文档分类管理）→ data-schema】。
④ 命令速查（完整参数见 references/commands.md，before 任何脚本调用先读它）：
| 域 | 代表命令 | 一句话 |
|---|---|---|
| 读态 | studyflow.py view/today/queue |
只读零副作用 |
| 任务 | studyflow.py add-task / task-status / task defer |
defer ≥3 条过 GATE-2 |
| 错题 | studyflow.py quiz-add / quiz list / quiz delete |
delete 过 GATE-1 |
| 复习 | studyflow.py review-result |
唯一等级迁移入口 |
| 门禁 | studyflow.py gate prepare/confirm |
冻结文件是执行前提 |
| 报告 | studyflow.py report daily/weekly |
文字+HTML 双层 |
| 诊断 | studyflow.py doctor + validate.py --self |
依赖预检 + 自验 |
Failure Handling（四状态 + 双层错误分类）
| 状态 | 触发 | 动作 |
|---|---|---|
| Not started | data.json 损坏且无备份 / OCR 不可用且用户无口述 | fail-with-direction：说清缺什么 + 替代方案（口述录入/恢复备份），不阻断，明说「没做什么」 |
| In progress | 批量操作中 | checkpoint：已处理/未处理计数；中断 → 落 state.json 断点，resume 幂等续跑只跑未完成项（≤3 轮，到顶转人工） |
| Partial success | 批量部分成功 | 分区报告：成功清单 + 挂起清单（errors.log），明确「完成了什么、没完成什么」 |
| Failed safely | 致命错误 | 原子写保证现场不半写；保留 tmp 现场 + errors.log + 非零退出码 |
业务错误码（每条写动作不写解释；退出码 0 成功 / 1 部分成功 / 2 致命）：
| 错误码 | 触发 | 动作 |
|---|---|---|
E-JSON-CORRUPT |
库损坏 | raw_decode 抢救 + 备份后修复；不静默重建空库丢数据 |
E-SCHEMA |
字段不符 | 按 data-schema.md 修正后重试（可重试，≤2 次，到顶转人工） |
E-OCR-FAIL |
可选 OCR 通路不可用/低置信（主通路=Agent 直读不受此影响） | 显式降级：直读重试（≤2 次，到顶转口述）/ 回显确认 / 转口述录入 |
E-GATE-NOT-CONFIRMED |
无冻结文件 | 先走 gate prepare + gate confirm 流程 |
E-KP-CONFLICT |
知识点归属不明 | 追问用户归类，不自动择一 |
E-SERIAL-WRITE |
检测到并行写 | 逐条串行重发 |
拒绝类：不支持 → 说清替代（搜题→「只录入不给答案」；成人待办→focusflow；文件归档→文档分类管理）。
升级条件：复习队列输出与 golden 比对不符 / 集合对账不平（applied ⊄ checked）→ 停止自动写库转人工。
回退：backups/ 最近一份恢复（写库前已滚动备份，保留 10 份）；GATE 批量越界 detected-and-stop 保留现场，按 log 逆序人工恢复 ≤1 次/文件。
Validation（完成前必查）
- data.json 存在且
json.load通过；python scripts/studyflow.py doctor+python scripts/validate.py --self退出码 0（M1 组合防线 = validate.py workbench 冒烟档 + workbench --self-test，双分支各断言一次） python scripts/validate.py <data路径>schema 校验 + 集合对账 applied ⊆ checked 通过- spaced_repetition 单测通过：
python scripts/spaced_repetition.py --self-test；队列推导与assets/data.golden.json基准比对一致 - 写操作回执已报「完成 N/失败 N/未处理 N」；报告附验证命令与结果
- 工作台/报告 HTML 已用 present_files 推送且用户可打开（人工核验项）
- 每条错误消息可答三问（原因是什么 / 下一步做什么 / 有没有替代渠道）
