dsh-diagnostic-tutor 0.1.1 → 0.2.0

package/README.md

@@ -11,24 +11,35 @@ learn interactively, and move to the next best step.
 
 ## Status
 
-`v0.1.1` — the current stable release. Conversation-scoped projects, focus,
-next steps and handoffs keep each learning session separate, while maps and
-lessons remain shared. The Learning UI now offers one next action and reports
-its actual state, with working scroll containers in docked and expanded views.
-
-Install the prebuilt package with
-`dsh plugin --profile web add dsh-diagnostic-tutor@0.1.1` — no clone, no
-`pnpm install`, no build step.
+`v0.2.0` is the published release. It includes the learning-path flow — saved
+goal and time budget, evidence-referenced initial assessment, versioned course
+routes with per-lesson Overviews, session-scoped attempts, and the
+English/Simplified-Chinese interface — plus the content/input/review loop:
+
+- typeset math, formula/code/quiz/flashcard/resource/comparison blocks;
+- learner sources with `sourceRefs` citations;
+- Today plan with ICS export and learner-controlled completion;
+- spaced review with automatic flashcard cards, four ratings and undo;
+- read-only Insights.
+
+Install it with
+`dsh plugin --profile web add dsh-diagnostic-tutor@0.2.0` — no clone, no
+`pnpm install`, no build step. A checkout can be installed instead (see
+[Installing a checkout](#installing-a-checkout-instead-of-the-package)).
 
 The learning loop works end to end: a real goal in your own words, a diagnosis
 map grown one node at a time, a tutor-written lesson, a check answered in the
 chat, recorded evidence, and a next step the tutor chose — which the learner
-presses Continue to take.
+presses Continue to take. The route flow adds a full plan the learner reviews
+and accepts, lesson by lesson; the content loop adds math, sources, Today and
+review on top of it.
 
 It is also early. The [limitations](#known-limitations) are listed rather than
 left to be discovered, and nothing below claims a capability that is not there:
-no PDF or document ingestion, no RAG, no flashcards, no resource libraries, no
-analytics, no course generation.
+no PDF extraction, no RAG, no automatic external resource fetching, no analytics.
+Review scheduling is a local interval heuristic, not FSRS. Course routes are
+proposed by the teaching model, never generated by the runtime, and a route never
+marks knowledge as mastered.
 
 ## Two halves, one system
 
@@ -124,12 +135,13 @@ see is a *diagnosis map*, not a syllabus.
 
 Stated plainly, because each one is a real edge a user can reach.
 
-**Math is styled, not typeset.** The tutor writes LaTeX by convention — `\(...\)`
-inline, `\[...\]` display — and the runtime sets it apart in a monospace face
-with its own background. It does **not** render it. Real typesetting needs a
-library plus fonts and CSS, and the client bundle is a single JavaScript file
-with nowhere to serve those from. This is the most visible rough edge in any
-STEM lesson.
+**Math is rendered as MathML on the host.** The tutor writes LaTeX by convention
+— `\(...\)` inline, `\[...\]` display — and the host pre-renders it with
+KaTeX's MathML output before storing the block. The browser renders native
+MathML through a tag/attribute whitelist; no font or CSS is fetched. Invalid
+TeX inside a text block falls back to the old styled source; an invalid
+`formula` block is refused at write time. Browser MathML quality varies, and
+this build ships no KaTeX CSS/fonts.
 
 **Skill presence requires a live Agent.** The runtime checks the open
 conversation's Agent scope on each overview, including its workspace. Before an
@@ -157,9 +169,12 @@ matrix as load-bearing, not decoration.
 
 | This plugin | Verified against DSH | Node |
 | --- | --- | --- |
-| `0.1.1` | `0.2.1-rc.2`, `0.2.0-rc.2` (test suite also on `0.1.7-alpha.2`) | `^22.19.0 \|\| >=24.0.0` |
+| `0.2.0` | `0.2.1-rc.3`, `0.2.1-rc.2`, `0.2.0-rc.2` (test suite also on `0.1.7-alpha.2`) | `^22.19.0 \|\| >=24.0.0` |
+| `0.1.1` | `0.2.1-rc.3`, `0.2.1-rc.2`, `0.2.0-rc.2` (test suite also on `0.1.7-alpha.2`) | `^22.19.0 \|\| >=24.0.0` |
 | `0.1.0` | `0.1.7-alpha.2` (also composed under `0.1.5-rc.1`) | `^22.19.0 \|\| >=24.0.0` |
 
+Phase 1–6 的本机 boot 矩阵（2026-10-29）覆盖 `0.2.1-rc.3`、`0.2.1-rc.2`、`0.2.0-rc.2`、`0.1.7-alpha.2` 的插件加载、本地路由、domain v1 与客户端启动；其中 rc3/alpha.2 还通过了 tarball 安装，并用真实模型完成 lesson → Review 评分/撤销 → Insights；rc2/rc20 的完整真实会话仍是补充项。详见 [`docs/planning/COMPATIBILITY.md`](docs/planning/COMPATIBILITY.md)。
+
 Rules this repository enforces mechanically:
 
 - **Named exports only.** A `export default` plugin makes Cordis' loader prefer
@@ -174,6 +189,38 @@ Rules this repository enforces mechanically:
   in the range — so the compatibility matrix above, not the range floor, is the
   contract. Dev dependencies pin one exact cohort for the type baseline.
 
+## UI baseline for redesign
+
+The current surfaces, state model and screenshots (generated from fixtures) live in
+[`docs/design/ui-baseline/index.html`](docs/design/ui-baseline/index.html) with a
+detailed handoff in
+[`docs/design/ui-baseline/README.md`](docs/design/ui-baseline/README.md). It covers
+the system structure, Learning map / Current lesson surfaces, every route-page state
+and the design constraints a new UI must keep.
+
+## Diagnostics
+
+Monitoring is local and content-free: no chat, goal, lesson or evidence text is
+recorded, and nothing is sent anywhere.
+
+```sh
+pnpm doctor                 # human-readable health report
+node scripts/doctor.mjs --json   # machine-readable
+node scripts/doctor.mjs --strict # exit 1 if an error-severity issue exists
+```
+
+It reads `<dsh-home>/storages/udt.json` plus the event journal and reports each
+project's stage, pending/failed tutor requests (with age), stalled attempts and
+route-length conflicts. The same report is available at
+`GET /diagnostic-tutor/api/diagnostics` (loopback-only, like every plugin
+route).
+
+The host journal lives at `<dsh-home>/logs/diagnostic-tutor-events.jsonl`
+(`DSH_DIAGNOSTIC_TUTOR_EVENTS` overrides the path, `off` disables it). It logs
+lifecycle events only: tool names and operations, durations, request outcomes,
+provider error messages (truncated). A single file is capped at 1 MB and
+rotated once.
+
 ---
 
 ## Install
@@ -182,7 +229,7 @@ Rules this repository enforces mechanically:
 
 | | |
 | --- | --- |
-| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | verified against `0.2.1-rc.2` |
+| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | verified against `0.2.1-rc.3` |
 | the [Universal Diagnostic Tutor](https://github.com/SenmuuuuW/universal-diagnostic-tutor-skill) skill | the teaching brain. Without it the runtime loads, records and displays state, but **no lesson is ever written** |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 
@@ -234,7 +281,7 @@ learn?*.
 
 ```sh
 npm pack
-dsh plugin --profile web add "$PWD/dsh-diagnostic-tutor-0.1.1.tgz"
+dsh plugin --profile web add "$PWD/dsh-diagnostic-tutor-0.2.0.tgz"
 ```
 
 **What gets installed is prebuilt.** The package ships `lib/` — the host half
@@ -321,7 +368,7 @@ route around them:
 
 ### Tools
 
-Six, and none of them decides anything about teaching.
+Eighteen. None of them decides anything about teaching; they record or report.
 
 | Tool | Does |
 | --- | --- |
@@ -329,8 +376,20 @@ Six, and none of them decides anything about teaching.
 | `udt_goal_create` | records a goal and plants only the map root; may also select it for this conversation |
 | `udt_map_get` | reads the selected project's map, or an explicitly named shared course, with each node's relation, state and evidence |
 | `udt_map_update` | `add-nodes` · `set-state` · `add-evidence` |
-| `udt_lesson_update` | writes teaching into the learning surface as blocks |
+| `udt_lesson_update` | writes teaching into the learning surface as blocks; pre-renders math; attaches source citations |
+| `udt_quiz_update` | records a quiz/flashcard submission; never grades and never changes node state |
 | `udt_decide_next` | records where the learner should go next, and why |
+| `udt_path_get` | reads the goal brief, assessment, routes and this conversation's active attempt |
+| `udt_path_update` | saves a brief, assessment or route proposal |
+| `udt_course_run_update` | binds a diagnosed node to an attempt, or completes with evidence |
+| `udt_source_add` | stores pasted text or one explicitly named local `.md`/`.txt` file; deduplicates by SHA-256 |
+| `udt_source_list` | lists source metadata without content |
+| `udt_source_get` | returns one stored source for citation |
+| `udt_plan_get` | reads the learner-owned Today plan |
+| `udt_plan_update` | adds, completes or removes plan items; planning is policy, not teaching |
+| `udt_review_add` | queues review cards; scheduling is policy, not mastery |
+| `udt_review_next` | reads cards due now |
+| `udt_review_grade` | records a review rating and reschedules; never confirms a node |
 
 The division is the architecture: the tutor decides **what** to teach, when to
 check, and what an answer showed; the runtime decides **what may be stored** and
@@ -404,20 +463,19 @@ the button means.
 
 | Surface | Where | For |
 | --- | --- | --- |
-| **Learning tab** | right sidebar, beside the chat | everyday work — map, node and lesson while you talk |
-| **Learning panel** | the main column (`main`) | focus mode — the whole runtime at once |
-
-The tab is the reason the loop is usable: the full panel fills the main column,
-which is also where the conversation lives, so with only that panel answering a
-check meant leaving the lesson. The right sidebar is a separate column.
+| **Learning map** | the main column (`main`, key `diagnostic-tutor-map`) | browsing — course route, every lesson Overview, knowledge & evidence |
+| **Current lesson** | the right sidebar tab, beside the chat | the lesson itself — teaching units, and checks answered in the chat |
 
-Both run on one shared `useLearning` state, so they cannot disagree about what
-is focused or what the tutor wrote. The panel's **Answer in the chat** button
-returns to the conversation and docks the tab in the same step.
+One page for browsing, one surface for learning. The page never starts a lesson;
+the tab never decides what to teach. Both read the same `useLearning` state and
+the same path client, so they cannot disagree about what is focused, accepted or
+written. **Open current lesson** on the map returns to the conversation with the
+lesson tab open in the same step.
 
-The right sidebar hosts session-scoped tabs, so it can only accept one while a
-session surface is mounted — which is why docking happens on the way back to the
-conversation rather than at load.
+The container for the main column is the map page. A full-page lesson panel used
+to exist as a second main destination; it was removed so the same lesson is not
+offered in two places. The standalone full-page component is still used by the
+preview and the tests, but the plugin does not register it.
 
 ### Teaching-brain detection
 
@@ -450,20 +508,76 @@ which judged an answer is *not finished* until the next step is recorded — so
 the bridge was **deleted rather than kept as a second voice**. The plugin got
 better at it, which is the evidence it belonged upstream.
 
-## The panel
-
-The browser half registers two things and nothing else: a sidebar icon
-(`sidebar.panellist`, a `list`) and the page it opens (`main`, a `keyed` slot).
-The sidebar `id` and the panel `key` come from one constant — a drift between
-them would leave the icon opening nothing.
-
-It reads as one sentence, left to right:
+## The page and the lesson surface
+
+The browser half registers three things: the **Learning map** icon in the
+sidebar (`sidebar.panellist`, a `list`), the page it opens (`main`, a `keyed`
+slot, key `diagnostic-tutor-map`), and the **Current lesson** tab in the right
+sidebar (a tab type plus its body and title). The map's sidebar `id` and its
+`main` key come from one constant — a drift between them would leave the icon
+opening nothing.
+
+The page has two tabs: **Course route** (the versioned plan, route canvas,
+ordered lesson list and every Overview) and **Knowledge & evidence** (the
+diagnosis map and its recorded observations). Neither one teaches: they show
+stored state.
+
+The route tab shows one stage at a time and one next step. A progress bar names
+the four stages — goal & time, initial diagnosis, route, learning — and a
+**Next step** card always answers "what now?" with a single primary action
+(set the goal, request or answer the diagnosis, request the route, accept the
+version, start the first lesson, continue the current one) plus at most one
+real alternative. Competing action rows live in the folded history, not beside
+it. Before a goal is saved the wizard owns the page; while the tutor is asking
+diagnostic questions the card points back to the conversation, shows how long it
+has waited, says whether the tutor is still thinking, and on a failed turn
+retries with the current model and opens the chat (the failure is recorded on
+the path request, so it survives a restart; provider errors are translated into
+billing / auth / rate-limit / network / context advice); route versions
+appear only after the diagnosis is complete or skipped; once accepted, the page
+leads with the route canvas. A proposed or accepted route shows its total study
+time, the weeks it takes at the saved weekly budget, and any lessons longer than
+the preferred session. Next step moves to the first unfinished lesson after a
+completion, and says when the whole route is done. Completed diagnosis details
+and route settings stay reachable in folded sections.
+
+The plugin's own accent is **DeepSeek's brand blue** — `#4d6bfe` on the light
+canvas, `#6a84ff` on the dark one — used sparingly for progress, the active tab,
+the current/selected item, focus rings and action links. Primary buttons keep the
+host's near-black/white fill: the blue marks, it does not act. All other colours
+continue to come from the host theme.
+
+The initial diagnosis is asked through DSH's **interactive question card**
+(`ask_user_question`) when the profile provides it: options are tapped rather
+than typed, multi-select works, and a free-text question covers explanations.
+The tutor still owns the questions, evidence and assessment; profiles without
+that tool fall back to chat text.
+
+The lesson lives in the docked tab, where the conversation is still on screen.
+That is what makes the check loop work without leaving the lesson. The sidebar
+action **Learn** opens that tab and never takes over the main column; the map's
+**Open current lesson** button returns to the conversation and opens the same
+tab.
 
 ```
-[ Course + Diagnosis Map ]  →  [ Selected node ]  →  [ Learning surface ]
+sidebar Learn ─────────────▶ Current lesson (right sidebar)
+sidebar Learning map ──────▶ Learning map (main column: route | knowledge)
+
+Open current lesson ◀────── returns to chat + lesson tab
 ```
 
-There is no dashboard: three panes, and the map is the navigation.
+Entering learning follows the conversation, not the window. A project is
+shared, but its focus and planned runs belong to a conversation, so the project
+library and **Open current lesson** ask the host which conversation was last
+learning the project (`GET /project/session`, read-only) and switch there with
+the shell's session navigation when it differs. The order is: newest active
+focus, then newest course run with an attempt, then newest project selection;
+only a project no conversation has ever touched falls back to the conversation
+on screen.
+
+A full-page lesson panel used to exist as a second main destination. It was
+removed: one page for browsing, one surface for learning, and the conversation
+keeps the main column.
 
 ### Learning Blocks
 
@@ -473,25 +587,42 @@ keyed by `type`:
 
 | Type | Content |
 | --- | --- |
-| `text` | `md` — markdown, with the skill's `\(...\)` math convention |
+| `text` | `md` — markdown, plus host `math[]` fragments for typeset formulas |
 | `example` | `title`, `steps[]`, `takeaway?` |
 | `diagram` | `format` (`ascii` \| `mermaid`), `spec`, `caption?` |
 | `check` | `prompt`, `expect?`, `hint?` — the stop-and-wait surface |
-
-Adding Formula, Code, Comparison, Practice or Resource later means adding one
-registry entry, never rewriting the lesson renderer. An **unknown type renders a
-readable placeholder** rather than throwing, so a lesson authored by a newer
-host still renders here.
+| `formula` | `tex`, `display?`, host-rendered `mathml`, `caption?` |
+| `code` | `language?`, `source`, `caption?` — displayed, never executed |
+| `quiz` | `title?`, `questions[]` (`mcq`/`short`); answers are recorded, never graded by the runtime |
+| `flashcard` | `front`, `back`, `tags?`; self-report is recorded, not scheduled as mastery |
+| `resource` | `title`, optional `sourceId`/`locator`/`url`/`note` |
+| `comparison` | `columns[]`, `rows[][]`, `caption?` |
+
+Blocks may also carry `sourceRefs: [{sourceId, locator}]`; every reference is
+checked against the `sources` table at write time. The stored schema accepts an
+**unknown type** from a newer host and the client renders a readable placeholder;
+the current model tool still writes only known types.
+The Learning map also shows a compact **Today** card when `udt_plan_update` has created open plan items, with a done action and an **Export calendar** action for dated items. DSH's own `schedule` is session-local, so this is an explicit calendar export rather than a push notification. Review cards and their local interval scheduler are stored but have no separate review surface yet.
 
 ### Browser API
 
-Three calls, at `/diagnostic-tutor/api`:
+The browser's core calls, at `/diagnostic-tutor/api` (the full route list is in
+[the architecture notes](docs/planning/CURRENT-ARCHITECTURE.md)):
 
 | Route | Returns |
 | --- | --- |
 | `GET /overview` | the current course and its whole map (`course: null` on a first run) |
 | `GET /node?id=` | one node with its evidence, parent and children |
+| `GET /project/session?courseId=` | the conversation that should resume a project (read-only) |
 | `POST /lesson {nodeId}` | the prototype lesson, built once and reused after that |
+| `GET /source?id=` | one stored source and its text, for a citation preview |
+| `POST /path/answer` | record a quiz/flashcard submission on the active attempt |
+| `GET /plan/ics` | download open, dated Today plan items as an ICS calendar |
+| `GET /review` | due review cards (read-only) |
+| `POST /review/grade` | record a review rating and reschedule |
+| `POST /review/undo` | restore the previous schedule after the latest grade |
+| `GET /insights?courseId=` | read-only course insight counts |
+| `POST /plan/task` | mark a Today plan item done (learner action; plan only) |
 
 Every request passes a **trust fence**: a bare `ctx.webServer.register()` route
 inherits no authentication, so the route checks that the request arrived at a
@@ -499,6 +630,27 @@ loopback `Host`, from a loopback `Origin`, and is not marked cross-site. Anythin
 else gets `403` and no body. The browser receives **views only** — no storage
 path, no domain handle, no raw record.
 
+### Interface language
+
+Every plugin surface ships copy in **English and Simplified Chinese**: the
+Learning map page, the course route, the docked Current-lesson tab, the
+standalone full-page panel used by the preview and tests, and the shared
+next-step card, handoff line and welcome row. The sidebar Learn action and its
+missing-conversation explanation switch too. A toggle in the map header (and in
+the lesson surfaces) changes the copy in place; the language is saved on the
+learner profile (`preferredLanguage`, via `GET /preferences` and
+`POST /preferences/language`), so it survives a restart and applies to every
+conversation. The choice applies immediately and is saved in the background: a
+failed request keeps the local choice rather than flipping the UI back.
+
+It is copy, not content: the tutor's teaching, the learner's goal text, lesson
+overviews, node titles and recorded evidence are never machine-translated, and
+the model is not instructed to change language by the toggle. Three things stay
+outside the switch: the **Learning map** sidebar label (registered once when the
+plugin loads, so it cannot follow an in-place change), server/model error text
+and dynamic handoff details as generated, and the development preview's own
+toolbar.
+
 ## Preview
 
 The panel takes its API as a prop, so the UI runs with no DSH and no agent:
@@ -522,8 +674,10 @@ Machine Learning            [goal, unconfirmed]
 
 Two query parameters reach the states that are otherwise awkward to produce on
 demand — `?scenario=` (`first-use`, `map`, `handoff`, `next`, `stay`, `noskill`,
-`long`, `scroll`, `library`, `new`) and `?surface=tab` for the docked right-sidebar
-tab. The scenario switch is in the page's toolbar, and the theme toggle sets the same
+`long`, `scroll`, `library`, `new`, `showcase`, `curriculum`, `path-draft`,
+`path-setup`, `path-assessment`) and `?surface=tab` / `?surface=map` for the
+docked right-sidebar tab and the standalone map page. The scenario switch is in
+the page's toolbar, and the theme toggle sets the same
 `body[data-ds-dark-theme]` attribute DSH does. The page carries the real DSH
 design tokens for the same reason: with hardcoded fallbacks in their place, a
 token that resolves to near-white in dark mode looks perfectly fine locally.
@@ -566,15 +720,19 @@ What the surfaces look like now, captured from a live profile:
 
 | | light | dark |
 | --- | --- | --- |
-| full panel | ![panel, light](preview/ui-polish/panel-light-1440.png) | ![panel, dark](preview/ui-polish/panel-dark-1440.png) |
+| standalone panel (preview/tests only) | ![panel, light](preview/ui-polish/panel-light-1440.png) | ![panel, dark](preview/ui-polish/panel-dark-1440.png) |
 | docked tab | ![tab, light](preview/ui-polish/tab-light-400.png) | ![tab, dark](preview/ui-polish/tab-dark-400.png) |
 
+These captures predate the current layout: the standalone full-page panel is no
+longer a product surface. Today the Learning map page owns the main column and
+the Current lesson tab holds the teaching.
+
 ## Development
 
 ```sh
 pnpm install
 pnpm typecheck   # tsc --noEmit  (host and client)
-pnpm test        # 455 tests: unit, guard, DOM, render, real composition
+pnpm test        # unit, guard, DOM, render, real composition
 pnpm build       # tsc -> lib/ (host) + tsdown -> lib/client.js
 ```
 
@@ -617,8 +775,10 @@ shows a loader row exists.
 | `v0.0.10` | export and delete your data |
 | `v0.0.11` | storage layout tested; `single` kept, with the reason |
 | `v0.1.0-rc.1` | packaged install, no clone or build required |
-| `v0.1.0` | **current** — first stable release, installable from npm |
-| `v0.2.0` | settings, i18n, math typesetting |
+| `v0.1.0` | first stable release, installable from npm |
+| `v0.1.1` | packaged release with the docked learning surface |
+| `v0.2.0` | **published** — Phase 1–6 content/input/review loop, learning-path flow, Today/Review/Insights |
+| next | settings, automatic replan suggestions (the tutor already proposes revisions on request; no runtime auto-replan) |
 
 ## Trust
 
@@ -626,7 +786,10 @@ DSH does not sandbox plugin code: an installed plugin runs in-process with your
 privileges, and a bare `ctx.webServer.register()` route inherits no
 authentication. This plugin's commitments:
 
-- reads and writes only its own storage domain;
+- reads and writes only its own storage domain, with one explicit exception:
+  `udt_source_add(path)` reads exactly one regular `.md`/`.markdown`/`.txt` file
+  the caller names, once, then stores its text in that domain. It never scans a
+  directory, follows a symlink, accepts a URL, or fetches anything;
 - serves its browser half only from loopback-fenced routes it checks itself;
 - makes no outbound network requests;
 - writes no files outside the harness's own storage;
@@ -727,4 +890,6 @@ MIT. The Universal Diagnostic Tutor skill is a separate MIT project by the same
 author and is not vendored here.
 
 Planning and architecture research for this project live in
-[`docs/planning/`](docs/planning/).
+[`docs/planning/`](docs/planning/). Phase 1–6 merge order, acceptance checks and the DSH compatibility checklist are in
+[`docs/planning/PHASE-1-6-MERGE.md`](docs/planning/PHASE-1-6-MERGE.md). 0.2.0 发布清单与验证记录见
+[`docs/planning/RELEASE-0.2.0.md`](docs/planning/RELEASE-0.2.0.md).