CLAUDE.md — study-loop 项目说明（给 Claude 的工作指南）

本文件是 study-loop 仓库的「工作指南」。每次在本仓库工作时先读它。用户手册见 docs/USAGE.md，主 Agent 路由见 SKILL.md，交付说明见 docs/DELIVERY-REPORT.md。

这是什么

study-loop 是一个本地优先、事件溯源的持续学习 Agent（Claude Code Skill），面向大学课程。核心定位：不生产知识，生产关于你的证据——把每道题变成可查证、可反驳的知识档案。不只追踪「会不会」，还追踪「为什么错、什么条件下错、能否迁移、依赖多少提示、多久会忘、下一步最该学什么」。当前主要实战课程：毛中特（文科、选择题密集）。产品全景（三个承诺 / 五条护城河 / 各功能实现状态）见 study-loop-产品定位与功能设计.md。

变更纪律（重要）

每次修改代码或新增功能后，必须在 CHANGELOG.md 顶部 [Unreleased] 下追加一条记录：日期 + 类型（feat/fix/refactor/docs/chore）+ 一句话摘要 + 涉及文件/命令 + 对应 commit 短哈希。功能交付后，把对应条目从 [Unreleased] 归入带日期版本号的小节。不要跳过这一步。

功能版本更新必须同步 README.md、README_EN.md：凡涉及用户可感知的新功能或新版本（与 CHANGELOG.md 中带版本号的小节对应），必须同步更新 README.md 和 README_EN.md 的功能说明与使用方式，避免 README 与实际能力脱节。不要跳过这一步。

所有更新备注一律用中文：git commit message、CHANGELOG.md 记录等面向人阅读的更新说明都用中文书写；代码、标识符、命令、文件名仍用英文。

架构铁律（不可违反）

事件溯源：events.jsonl 是唯一真相源。.study/ 下的 state.json 只是快照。 → 任何状态写入都只走 scripts/ 下的 CLI（写事件），绝不直接编辑 .study/ 下的 JSON/JSONL。
听懂 ≠ 掌握：知识点升级到 checked/confirmed 由脚本规则执行，不得口头宣布掌握。
AI 出题四道闸门：Generator → 盲解 Solver → 对抗 Reviewer → 机械验证，过 validate_question.py 才入库。
原题优先：真题/课后题优先于 AI 生成题，且必须进 FSRS。
规则可升级：改规则后用 derive_state.py 重算或 rebuild.py --dry-run 核对差异。

目录速查

路径	作用
`SKILL.md`	主 Agent 路由表（意图 → 动作）
`references/`	完整规则文档（架构/证据图/FSRS/迁移阶梯/错因记忆/出题校验…）
`agents/`	出题三卡：`question-generator.md` / `independent-solver.md` / `adversarial-reviewer.md`
`scripts/`	CLI 入口（`event.py` `next_step.py` `fsrs.py` `validate_question.py` …）
`scripts/studylib/`	核心库（`schemas.py` 数据模型 / `derive.py` 派生 / `registry.py` KC/题注册表 / `validation.py` 闸门 / `nextstep.py` 推荐 / `fsrs_store.py` 间隔重复 …）
`templates/`	dashboard 等 Jinja 模板
`tests/`	全量 pytest 测试
`tmp/`	工作草稿（OCR/字体/候选题 JSON），已 gitignore，不入库

关键数据模型（见 `scripts/studylib/schemas.py`）

KC（知识点）：kc_id（英文 slug，如 mao_living_soul）+ name（中文，如「毛泽东思想活的灵魂」）+ chapter_id + prerequisites + exam_weight + source_ids + explained + aliases（同义表，防漂移）+ related（双向关联）+ weight（core/familiar/aware 备考分级）+ syllabus_node（挂大纲骨架节点）。
Question：question_id / kc_ids / source_type / transfer_level(T0–T4) / stem / answer / solution / difficulty / estimated_minutes / changed_dimensions / preserved_dimensions / derived_from / target_level / grounding（必填，文件/页/段）/ exam_ref（仅 URL）/ style_note / rubric / validation（四闸门块）。
选择题答案存在 stem（含 A.xxx\nB.xxx）+ answer（如 ABC）+ solution（解析）。

常用命令

# 测试
python3 -m pytest                      # 或 python3 -m pytest tests/test_xxx.py

# 课程工作区操作（在工作区目录下，自动识别）
python3 scripts/next_step.py           # 今天最该做什么 + 为什么
python3 scripts/drill.py --mode syllabus --count 10 --format html  # 一站式刷题（考纲/诊断 × html/paper/md）
python3 scripts/render_dashboard.py    # 状态页
python3 scripts/derive_state.py        # 重算状态
python3 scripts/rebuild.py --dry-run   # 全量重建预演

当前进度（V4 已交付，下一轮规划中）

V4（2026-07-26）已交付 8 方向，见 CHANGELOG.md 的 [V4.0-rc1]：基础数据模型收紧（D7 无提示升级 / D8 仅概念类错因降级）、质量信任层（题目溯源 + 脏数据回滚）、三层排程（今日清单 + 备考日历预测）、错因交互（学生确认 + 询问式修复）、个性化（出题策略 / 讲解风格 / 学习节律）、大纲骨架 syllabus.json。产品全景与各功能实现状态见 study-loop-产品定位与功能设计.md。

下一轮目标（产品定位 md §9 未决事项，按价值排序）：

场景补全：/preview 预习、/exam 备考（分级知识清单 + 仿真卷成套批改）、/review 由 FSRS 扩到完整闭环。
断点续传：把「没做完」当一等状态（open_tasks.json），§6.7。
三前端回传统一：HTML/PDF 作答回传 attempt，补 evidence 契约 frontend/student_answer。
出题双路径：真题变式（路径 A）。
内容解析：段落级定位、PPT/教材解析；别名自动合并、Obsidian 导出。

FilesExpand file tree

CLAUDE.md

Latest commit

History