A-Level Study Coach (Obsidian Plugin)

中文版本：README.zh.md

An assistive A-Level study coach for Obsidian: learning stays offline-first — open the plugin only when you need help: an unclear concept, a problem you're stuck on, or essay grading. Every request is logged so weaknesses surface over time. Targets: A-Level all A*, IELTS 7.5+.

Product design: docs/产品设计.md (v0.3). Prompt system from the chat-2 coach pack; tech base simplified-forked from AI Study Buddy.

Feature Overview

Coach Sessions

Feature	Description
Per-subject sessions	Each subject keeps its own session; switching saves/restores automatically; concluding closes it
Auto session start	A session opens instantly when you enter a subject — no button needed; sessions with no user input are never recorded
Opening mode menu	The opening is rendered locally from the prompt's ```opening fence (zero API call): Concept Drill A–G (blind write / decomposition / colloquial rewrite / logic chain / drill / F concept relation map — chapter-level: includes learned + not-yet-learned concepts, the latter marked as preview with a short auto-explanation, mermaid with keyword edges / G keyword recall — reproduce the whole map from keywords); Economics A–D; IELTS A–D. Reply with a letter to pick a mode, jump anytime, or let the AI guide by context
Concept map	After a chapter-level F map, a confirm card registers concepts to 记录/概念地图.md (chapter/concept/status); preview/pending concepts are auto-injected into the drill prompt so they switch to detailed mastery when actually learned, and become “learned” after confirmation; the records center shows the ledger
Conclude flow	Conclude = self-review, scrutiny, error-log rows, session tagging; then auto-archive and auto-reopen a fresh session
Problem solving & correction (unified)	Being stuck on a new problem and correcting a wrong one share one flow: any problem request enters it (with your attempt → compare; stuck → first ask how far you got); attempt images auto-transcribed; three-tier baseline for the correct answer (official / model solution verified by you / pending); locate the divergence and guide the correction; after conclude, a confirm card registers to the wrong-answer ledger and unmastered entries are auto-injected into later sessions
Session extras	SSE streaming output, image attachments (vision models; more than 4 images are auto-batched for recognition with per-batch progress and resume-on-failure, transcripts merged into the session record), session-wide doc references, resume from history
Think-first timer	In-session countdown; sending is blocked before the threshold; finishing adds a "thinking credit" note to the next message

Context & Models

Feature	Description
Global model selector	Top-bar dropdown applies to every AI call; the settings page manages models as a list per provider (add / test individually / set default / delete)
Context management	Usage shown under the input box ("x / y (n%)"); auto-compress threshold is configurable (default 80%); over-limit turns red with a "force compress" button; compression is long-running and always shows progress notices

Records & Review

Feature	Description
Error log ledger	13-column main table; recurrence auto +1; review in 7 days (3 if recurring); status flows unresolved → observing → resolved
3-way routing	Specific losses → ledger; question-type habits → practice focus; vague claims → weakness impressions
Records center	One tab shows all ledgers: A-Level error log + IELTS grades + expression library + question log (data files stay separate — zero information loss)
Review reminders	The Review tab shows today's full due list in four queues: error-log points (per item: variant question / passed / recurred), term drills, expression sentence drills, wrong-answer follow-up (per-item "mastered after redo"); you can also practice offline — report results in natural language for batch parsing, or give per-item feedback directly; plus status-bar badge and one gentle daily notice
Wrong-answer ↔ session backlink	Every wrong-answer entry records the session it occurred in; one click opens the original conversation from the records center / review queue, and "redo" prefills your mistake-at-the-time plus the session link
Mastery progress badges	Each status shows the distance to the next state (e.g. "1 spot-check away from stable"); per-row "practice" buttons jump to the coach with a prefilled request (term spot-check / wrong redo / variant)
Weakness profile (L2)	A compressed per-subject profile with ledger-ID backlinks, auto-refreshed after each conclude; injected instead of full tables when many entries are open (saves tokens); the manual-notes section survives regeneration
Review sheet	One click compiles the four due queues into a single printable note (term flashcards / wrong redo / expression sentences); fingerprint drift detection flags a stale sheet for regeneration
Trend charts	Local SVG (no deps): overall-score sparklines for writing/speaking, 30-day mark-loss code bars in Records
Answer rewrite diff	After the English review step, a Compare button opens a word-level before/after diff of the student's own two versions
Quick capture	One natural-language sentence → AI suggests a category → accept / edit / discard

Weakness Analysis

Feature	Description
Insight engine	Question hotspots × recurrence hotspots × expression-code trends × term/review backlogs; pure local stats; a suggestion needs ≥3 hits on one signal
Suggestion cards	Persisted under 建议/; view/disagree feedback loop; study advice is generated once, only after consent (no schedules)
Weekly report	周报/{ISO-week}.md with six stat blocks (help, losses & recurrence, reviews, terms, IELTS, suggestions)
Advanced corner	Stage-based advanced-exam roadmap (G10 UKMT → G11 MAT/TMUA → G12 STEP/PAT/ESAT) with one-click thinking-problem sessions and auto timer

IELTS

Feature	Description
Unified entry	Coach "IELTS Writing": A full grading / B paragraph commentary / C discussion & dispute / D targeted practice — freely mixed and switchable mid-session
Grade any note	Open any note (task + essay, images included); six-part output written to ## AI 批改; re-grading archives the previous version for comparison
Score ledger	Every grade appends overall + TR/CC/LR/GRA to 雅思/批改记录.md — your improvement trajectory
Expression library	High-score expressions auto-collected (deduplicated) with simplified SM-2 intervals 1→3→7→14→30→60 days and due sentence drills
Speaking training	Coach "IELTS Speaking": A full mock exam (Part 1→2→3) / B single-part focus / C free practice / D discussion & review; delayed & limited corrections, first-session calibration with staged targets (stepwise path to 7.5), evidence-based Band-7 scoring (ranges, no flattery); final scores go to 雅思/口语记录.md alongside the writing trend, speaking mistakes to the existing wrong-answer ledger (SP/GR/VX), upgraded expressions to the library; voice pipeline (Aliyun NLS): 🎤 hold-to-talk ASR with auto-send, examiner replies read aloud sentence-by-sentence via TTS (interruptible), recordings normalized to 16k WAV (optionally saved); falls back to text mode when keys are unset; P-dimension pronunciation eval awaits P5c

Data Locations (all inside the vault, syncable via git / iCloud)

vault/StudyCoach/
├── 档案.md          # student profile (frontmatter, editable in settings)
├── 三年路线图.md    # 3-year roadmap
├── prompts/         # coach prompts (with ```opening fences), directly editable
├── 建议/            # weakness suggestion cards
├── 雅思/            # essays / speaking reports / grade ledger / speaking ledger / expression library
├── 周报/            # weekly reports (idempotent overwrite)
├── 记录/            # error log, wrong-answer ledger, concept map, question log, terms, practice focus, impressions, stats, progress, diary
└── 会话/            # session archives (only written if there was interaction)

Installation

npm install
npm run build
./install.sh /path/to/your/vault

Then in Obsidian: Settings → Community plugins → enable A-Level Study Coach → configure the LLM in plugin settings (OpenAI-compatible endpoint or native Anthropic; the API key stays on your machine).

Development

npm run dev        # esbuild watch
npm run typecheck  # tsc --noEmit
npm test           # full UT + FVT suite (must stay green on every change)

Test suite (test/, obsidian isolated via FakeVault, runs directly in node):

Layer	Scope
UT	utils / errorlog / services / insight / ielts / report: parsing, ledger rules, state machines, analysis thresholds, grading tolerance, report stats
FVT: session	Full help loop: injection → conclude → tagging + ledger → recurrence → archive & resume
FVT: dataflow	Cold-start 3-way routing, review flow, analysis cycle
FVT: ielts	Grading closed loop: write-back → scores ledger → expression dedup → trend weak spots

Known Limitations (by design)

• Term/expression drill modals are non-streaming (replies are short)
• No IELTS listening/reading features (offline-learning scope); speaking voice requires Aliyun keys (text mode otherwise); P-dimension pronunciation eval awaits P5c
• Reports/radar are plain-text stats; no chart libraries (kept lightweight)
• Prompt template updates never overwrite existing vault files (user edits win)
• Streaming relies on fetch; if a provider blocks browser CORS, use an OpenAI-compatible gateway