dsh-nerd-mode 0.4.5 → 0.5.0

package/lib/index.js

@@ -11,6 +11,7 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { COMMAND, KEY, fold, init } from './fold.js'
+import { scan } from './study-sessions.js'
 import z from '@deepseek-ai/schemastery'
 
 export const name = 'dsh-nerd-mode'
@@ -38,6 +39,7 @@ export const Config = z.object({
 const SECTION = 'study:policy'
 // Between PLAN_POLICY (500) and TEAM_POLICY (600).
 const SECTION_ORDER = 550
+const STUDY_SESSIONS_PATH = '/dsh-nerd-mode/api/study-sessions'
 const studyPlusDefaultsBySession = new WeakMap()
 const directStudyPlusBySession = new WeakMap()
 // A PTC skill load leaves no message in the history, so keep its id for later
@@ -162,6 +164,53 @@ const projection = {
   },
 }
 
+function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+function cursorOf(req) {
+  const match = /[?&]cursor=(\d+)/.exec(req?.url ?? '')
+  return match === null ? 0 : Number.parseInt(match[1], 10)
+}
+
+/**
+ * Build the read-only history route handler.
+ *
+ * `webServer.register` adds no auth fence, so the connection service decides
+ * first: a missing cookie is 401 and a bad Host or Origin is 403.
+ *
+ * @param options
+ * @param options.connection - the host connection service
+ * @param options.indexFile - forwarded to `scan`; tests point it at a temp file
+ * @param options.sessionsRoot - forwarded to `scan`; tests point it at a temp tree
+ * @returns {(req, res) => Promise<void>} replies `{ phase, cursor, done,
+ * total, sessions }` with `no-store`, `{ error }` with status 500, or the
+ * rejection status
+ */
+export function createStudySessionsHandler({ connection, ...scanOptions }) {
+  return async function studySessionsRoute(req, res) {
+    const rejection = connection.requestRejection(req)
+    if (rejection !== undefined) {
+      res.writeHead(rejection)
+      res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+      return
+    }
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { error: 'Method not allowed.' })
+      return
+    }
+    try {
+      sendJson(res, 200, scan({ ...scanOptions, cursor: cursorOf(req) }))
+    } catch (error) {
+      sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+}
+
 /**
  * @param config - `section` is an optional overlay text; a missing value uses
  * the bundled `assets/section.md`.
@@ -220,4 +269,18 @@ export function apply(ctx, config) {
       },
     })
   })
+
+  // The web server is optional: a host without it still loads the switch and
+  // the prompt section, and the panel shows its failure line.
+  ctx.inject(['webServer', 'connection'], (webCtx) => {
+    webCtx.effect(
+      () =>
+        webCtx.webServer.register({
+          kind: 'exact',
+          path: STUDY_SESSIONS_PATH,
+          handler: createStudySessionsHandler({ connection: webCtx.connection }),
+        }),
+      'dsh-nerd-mode: study sessions route',
+    )
+  })
 }

package/lib/study-sessions.js

@@ -0,0 +1,283 @@
+/**
+ * The Study Sessions history index. It reads the session logs the host writes
+ * and caches the two facts the panel needs: whether Nerd Mode was ever on, and
+ * whether a completed `/study-plus` invocation appears. Kept free of host
+ * imports like `lib/fold.js`, so it runs under plain node. See ADR 0021.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { zstdDecompressSync } from 'node:zlib'
+
+const COMMAND = 'nerd-mode'
+const STUDY_PLUS = 'study-plus'
+const SESSION_FILE = 'session.v4.jsonl.zstd'
+const DEFAULT_INDEX_FILE = join(homedir(), '.dsh', 'study-sessions-index.json')
+const DEFAULT_SESSIONS_ROOT = join(homedir(), '.dsh', 'sessions')
+const DEFAULT_CHUNK_SIZE = 20
+const MAGIC = [0x28, 0xb5, 0x2f, 0xfd]
+// The token must stand alone: `not/study-plus` and `/study-plussed` are not
+// invocations. This is the same boundary the live command parser uses.
+const DIRECT_COMMAND = /(^|\s)\/study-plus(?=\s|$)/
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function messageText(message) {
+  const content = message?.content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
+}
+
+function skillNameOf(argumentText) {
+  if (typeof argumentText !== 'string') return undefined
+  try {
+    return JSON.parse(argumentText)?.name
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read the two history facts from one session's decoded events.
+ * @param events - decoded session log events, in log order
+ * @returns {{ nerd: boolean, studyPlus: boolean }} `nerd` means Nerd Mode was
+ * switched on at least once, `studyPlus` means a completed `/study-plus`
+ * invocation appears. Malformed events are ignored.
+ */
+export function classify(events) {
+  const successfulCommands = new Set()
+  const wantedCommands = new Set()
+  const skillCalls = new Set()
+  const completedCalls = new Set()
+  let studyPlus = false
+
+  for (const event of events) {
+    const data = event?.data
+    if (event?.type === 'command/run') {
+      if (data?.name !== COMMAND) continue
+      // A bare /nerd-mode means on, matching lib/fold.js.
+      const args = typeof data.args === 'string' ? data.args : ''
+      if (args.trim().toLowerCase() !== 'off' && typeof data.commandId === 'string') {
+        wantedCommands.add(data.commandId)
+      }
+    } else if (event?.type === 'command/done') {
+      if (data?.kind === 'success' && typeof data.commandId === 'string') {
+        successfulCommands.add(data.commandId)
+      }
+    } else if (event?.type === 'user/message') {
+      const source = data?.source
+      if (source?.kind === 'skill-invocation') {
+        if (source.name === STUDY_PLUS) studyPlus = true
+      } else if (source?.kind === 'user' && DIRECT_COMMAND.test(messageText(data))) {
+        studyPlus = true
+      }
+    } else if (event?.type === 'tool/call') {
+      if (data?.name === 'skill' && typeof data.callId === 'string' && skillNameOf(data.arguments) === STUDY_PLUS) {
+        skillCalls.add(data.callId)
+      }
+    } else if (event?.type === 'tool/result') {
+      const message = data?.message
+      if (message?.isError !== true && typeof message?.source?.callId === 'string') {
+        completedCalls.add(message.source.callId)
+      }
+    } else if (event?.type === 'tool/ptc-dispatch') {
+      // A skill load inside run_code arrives as a dispatch and carries its own outcome.
+      if (data?.name === 'skill' && data?.arguments?.name === STUDY_PLUS && data?.isError !== true) {
+        studyPlus = true
+      }
+    }
+  }
+
+  if (!studyPlus) {
+    studyPlus = [...skillCalls].some((callId) => completedCalls.has(callId))
+  }
+  return {
+    nerd: [...wantedCommands].some((commandId) => successfulCommands.has(commandId)),
+    studyPlus,
+  }
+}
+
+/**
+ * Decode a session log into events.
+ *
+ * The file is a chain of zstd frames, one per append batch. Whole-file
+ * decompression stops at the first frame, which holds only the header, so each
+ * frame is decoded on its own.
+ *
+ * @param file - path to a `session.v4.jsonl.zstd` file
+ * @returns the decoded events; malformed frames and lines are dropped
+ * @throws when the file itself cannot be read
+ */
+export function decodeSessionFile(file) {
+  const bytes = readFileSync(file)
+  const starts = []
+  for (let offset = 0; offset <= bytes.length - MAGIC.length; offset += 1) {
+    if (MAGIC.every((byte, index) => bytes[offset + index] === byte)) starts.push(offset)
+  }
+
+  const events = []
+  for (let index = 0; index < starts.length; index += 1) {
+    let text
+    try {
+      text = zstdDecompressSync(bytes.subarray(starts[index], starts[index + 1] ?? bytes.length)).toString('utf8')
+    } catch {
+      // A magic byte sequence can occur inside compressed data, so a failed
+      // slice is expected. See docs/agents/dsh-session-api.md.
+      continue
+    }
+    for (const line of text.split('\n')) {
+      if (line === '') continue
+      try {
+        events.push(JSON.parse(line))
+      } catch {
+        // A crash can leave a partial trailing line. One bad record must not
+        // hide the rest of the log.
+      }
+    }
+  }
+  return events
+}
+
+function readIndex(file) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    // A missing index is a first run. Any other failure reaches the panel.
+    throw error
+  }
+  try {
+    const index = JSON.parse(text)
+    return isRecord(index) ? index : {}
+  } catch {
+    // A corrupt cache is rebuilt from the logs, not reported as a failure.
+    return {}
+  }
+}
+
+function writeIndex(file, index) {
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.tmp`
+  writeFileSync(temp, JSON.stringify(index))
+  // Rename keeps the previous index readable if the process dies mid-write.
+  renameSync(temp, file)
+}
+
+function listSessionFiles(root) {
+  let workspaces
+  try {
+    workspaces = readdirSync(root, { withFileTypes: true })
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { files: [], complete: true }
+    throw error
+  }
+
+  const files = []
+  let complete = true
+  for (const workspace of workspaces) {
+    if (!workspace.isDirectory()) continue
+    let sessions
+    try {
+      sessions = readdirSync(join(root, workspace.name), { withFileTypes: true })
+    } catch {
+      // One locked workspace must not blank the others, and must not prune them.
+      complete = false
+      continue
+    }
+    for (const session of sessions) {
+      if (!session.isDirectory()) continue
+      const file = join(root, workspace.name, session.name, SESSION_FILE)
+      try {
+        const stat = statSync(file)
+        if (stat.isFile()) {
+          files.push({ id: session.name, file, mtimeMs: stat.mtimeMs, size: stat.size })
+        }
+      } catch {
+        // A session folder without a readable log is not a session yet.
+      }
+    }
+  }
+  files.sort((left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0))
+  return { files, complete }
+}
+
+/**
+ * Classify one chunk of the session tree and persist the index.
+ *
+ * @param options
+ * @param options.cursor - index of the first file in the sorted session list to
+ * process; negative and non-integer values read as 0
+ * @param options.indexFile - index path; defaults to
+ * `~/.dsh/study-sessions-index.json`
+ * @param options.sessionsRoot - session tree; defaults to `~/.dsh/sessions`
+ * @param options.chunkSize - files to process per call; defaults to 20
+ * @param options.decode - decoder override for tests; defaults to
+ * `decodeSessionFile`
+ * @returns {{ phase: 'pending' | 'ready', cursor: number, done: number,
+ * total: number, sessions: Record<string, { studyPlus: boolean }> }} `cursor`
+ * is the next call's starting index and equals `total` once `phase` is
+ * `ready`. `done` counts files visited so far. A key in `sessions` means Nerd
+ * Mode was on at least once for that id.
+ * @throws when the index or the session tree cannot be read or written
+ */
+export function scan({
+  cursor = 0,
+  indexFile = DEFAULT_INDEX_FILE,
+  sessionsRoot = DEFAULT_SESSIONS_ROOT,
+  chunkSize = DEFAULT_CHUNK_SIZE,
+  decode = decodeSessionFile,
+} = {}) {
+  const { files, complete } = listSessionFiles(sessionsRoot)
+  const index = readIndex(indexFile)
+  if (complete) {
+    const live = new Set(files.map(({ id }) => id))
+    for (const id of Object.keys(index)) {
+      if (!live.has(id)) delete index[id]
+    }
+  }
+
+  const start = Number.isInteger(cursor) && cursor > 0 ? cursor : 0
+  const size = Number.isInteger(chunkSize) && chunkSize > 0 ? chunkSize : DEFAULT_CHUNK_SIZE
+  const end = Math.min(start + size, files.length)
+  for (let position = start; position < end; position += 1) {
+    const { id, file, mtimeMs, size: bytes } = files[position]
+    const previous = index[id]
+    if (previous?.mtimeMs === mtimeMs && previous?.size === bytes) continue
+
+    let flags
+    try {
+      flags = classify(decode(file))
+    } catch {
+      // An unreadable session keeps its previous record and retries next scan.
+      continue
+    }
+    index[id] = {
+      mtimeMs,
+      size: bytes,
+      // Compaction can drop the original event. A fact that disappeared from a
+      // rewritten log must not resurface as a missing session.
+      nerd: flags.nerd || previous?.nerd === true,
+      studyPlus: flags.studyPlus,
+    }
+  }
+  writeIndex(indexFile, index)
+
+  const sessions = {}
+  for (const [id, entry] of Object.entries(index)) {
+    if (entry?.nerd === true) sessions[id] = { studyPlus: entry.studyPlus === true }
+  }
+  return {
+    phase: end >= files.length ? 'ready' : 'pending',
+    cursor: end,
+    done: end,
+    total: files.length,
+    sessions,
+  }
+}

package/package.json

@@ -1,70 +1,70 @@
-{
-  "name": "dsh-nerd-mode",
-  "version": "0.4.5",
-  "description": "A study switch and study skills for DeepSeek Harness.",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bocchii-the-code/dsh-nerd-mode.git"
-  },
-  "homepage": "https://github.com/bocchii-the-code/dsh-nerd-mode#readme",
-  "bugs": {
-    "url": "https://github.com/bocchii-the-code/dsh-nerd-mode/issues"
-  },
-  "main": "./lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./client.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "client.js",
-    "assets",
-    "cordis.patch.yml",
-    "skills",
-    "README.md",
-    "README.zh.md",
-    "NOTICE.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "immediately": true,
-      "inject": [
-        "@deepseek-ai/dsh-client-ui-conversation"
-      ]
-    }
-  },
-  "scripts": {
-    "test": "node --test",
-    "lint": "eslint .",
-    "check": "npm run lint && npm test"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/schemastery": "^3.18.5"
-  },
-  "engines": {
-    "node": "^22.19.0 || >=24.0.0"
-  },
-  "keywords": [
-    "dsh-plugin",
-    "deepseek-harness",
-    "study",
-    "tutor",
-    "agent-skill"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@deepseek-ai/schemastery": "^3.18.5",
-    "eslint": "^10.13.0",
-    "globals": "^17.13.0"
-  }
-}
+{
+  "name": "dsh-nerd-mode",
+  "version": "0.5.0",
+  "description": "A study switch and study skills for DeepSeek Harness.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bocchii-the-code/dsh-nerd-mode.git"
+  },
+  "homepage": "https://github.com/bocchii-the-code/dsh-nerd-mode#readme",
+  "bugs": {
+    "url": "https://github.com/bocchii-the-code/dsh-nerd-mode/issues"
+  },
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client.js",
+    "assets",
+    "cordis.patch.yml",
+    "skills",
+    "README.md",
+    "README.zh.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "check": "npm run lint && npm test"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "study",
+    "tutor",
+    "agent-skill"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0"
+  }
+}

package/skills/study/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: study
-description: Teach one concept or help complete one task, using the supplied material as scope and defaulting to chat output.
+description: "[v0.5.0] Teach one concept or help complete one task, using the supplied material as scope and defaulting to chat output."
 argument-hint: "<concept or task>"
 ---
 # Study

package/skills/study-plus/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: study-plus
-description: Run one tracked session against a dated learning record. Load for an explicit command or after the user chooses tracked study in the upper router.
+description: "[v0.5.0] Run one tracked session against a dated learning record. Load for an explicit command or after the user chooses tracked study in the upper router."
 argument-hint: "<course-slug>, or empty to continue the current Course"
 ---
 # Study Plus
@@ -52,15 +52,15 @@ For a new graph:
 2. Make a concept table in prerequisite order. Each row has a one-line definition and prerequisite numbers. Keep prerequisite order separate from textbook reading order.
 3. Use the source's book and chapter hierarchy when present. Otherwise, propose logical chapter groupings.
 4. Show the full graph and chapter layout in the reply before the approval question, as a Markdown table. Keep the question text short, because it renders as one paragraph: ask whether to approve, edit, or rebuild the graph shown above, and state that approval starts draft generation for every concept, including any concept the learner then skips, and that drafts are not teaching. Do not put the table in the question text. Do not add another approval step.
-5. After approval, run calibration as one `question` call with up to three items: what the learner wants to be able to do after this Course, what they have already read, studied, or used in this area in their own words, and which concepts in the approved graph they know well enough to skip, as a multi-select list. Items 1 and 2 are free text. Ask the goal and background items only when nothing already answers them: not the current request, not the opening question, not the supplied material. Reuse an opening-question answer verbatim. Derive the level. Then write `graph.md`, create `state.md` with every concept `new` and undated except the concepts selected to skip, which are `skipped`, create an empty `log.md`, and generate one draft per concept (section 3). Do not create `plan.md`.
+5. After approval, run calibration as one question-tool call with up to three items: what the learner wants to be able to do after this Course, what they have already read, studied, or used in this area in their own words, and which concepts in the approved graph they know well enough to skip, as a multi-select list. Items 1 and 2 are free text. Ask the goal and background items only when nothing already answers them: not the current request, not the opening question, not the supplied material. Reuse an opening-question answer verbatim. Derive the level. Then write `graph.md`, create `state.md` with every concept `new` and undated except the concepts selected to skip, which are `skipped`, create an empty `log.md`, and generate one draft per concept (section 3). Do not create `plan.md`.
 
 Calibration writes `Goal`, `Background`, and `Teaching level` to `graph.md`. Derive the level from the two answers:
 
-| Answers | Level |
-|---|---|
-| Most prerequisites are unknown, or the goal is to learn the topic from zero | `beginner` |
+| Answers                                                                                    | Level        |
+| ------------------------------------------------------------------------------------------ | ------------ |
+| Most prerequisites are unknown, or the goal is to learn the topic from zero                | `beginner` |
 | Some prerequisites are known, and the goal is to understand the principles or pass an exam | `standard` |
-| Most prerequisites are known, and the goal is review, reference, or use in a project | `advanced` |
+| Most prerequisites are known, and the goal is review, reference, or use in a project       | `advanced` |
 
 When the two answers clearly conflict, you may choose an adjacent level and state the reason in one line. When the learner declines or gives no usable answer, write `Teaching level: standard` and omit the `Goal` and `Background` lines. Each selected concept becomes `skipped`, with no date and no passes.
 
@@ -136,7 +136,7 @@ If the row was already `in_process`, say that the last session stopped before th
 
 **Ask unseen questions.** Use the explicit count or type preference in the current `/study-plus` request when present. Otherwise, use the profile defaults in the top-level Nerd Mode instructions. Plan the configured number of unseen question slots, from 0 to 10. A hint, re-ask, or similar question stays in its current slot and does not add a slot. For each slot, write down the expected answer and criteria for a good answer. Keep both private. A draft never contains them. The criteria test the conclusion and whether each step taken is valid, not the route you had in mind. Ask one question at a time, then wait. One call asks one question. Outside `study-plus`, ignore these preferences.
 
-For `short-answer`, ask the question in the conversation. For `multiple-choice`, ask it as one `question` call with four options and exactly one correct answer; choosing it is sufficient. Give the labels alone, with no description, and shuffle the four positions for each slot. A host without a `question` tool gets the same four options as a numbered text list. A typed answer that names or repeats one option counts as choosing it. Any other typed answer is graded like a short answer. For `mixed`, choose short-answer or multiple-choice independently at random for each planned slot. Do not add question-type details to the session log. When the configured count is zero, skip unseen questions. A passed Teach-back alone is sufficient to pass. With one or more slots, require a passed Teach-back and `ceil(2 × slot count / 3)` correct slots.
+For `short-answer`, ask the question in the conversation. For `multiple-choice`, ask it as one question-tool call with four options and exactly one correct answer; choosing it is sufficient. Give the labels alone, with no description, and shuffle the four positions for each slot. A host without a question tool gets the same four options as a numbered text list. A typed answer that names or repeats one option counts as choosing it. Any other typed answer is graded like a short answer. For `mixed`, choose short-answer or multiple-choice independently at random for each planned slot. Do not add question-type details to the session log. When the configured count is zero, skip unseen questions. A passed Teach-back alone is sufficient to pass. With one or more slots, require a passed Teach-back and `ceil(2 × slot count / 3)` correct slots.
 
 A question exists to find the gap, not to stop the session. Nothing in this step blocks the learner.
 

package/skills/study-plus/scripts/book-client.js

@@ -13,8 +13,8 @@
     if (!panels.length) return;
 
     var L = book.lang === 'en'
-      ? { search: 'Search the book', toc: 'Contents', none: 'No match', hits: ' hits', chapter: 'Chapter', section: 'Section', sections: 'sections', menu: 'Chapters', draft: 'Draft' }
-      : { search: '搜索全书', toc: '目录', none: '没有匹配', hits: ' 处', chapter: '第', section: '第', sections: '节', menu: '章节', draft: '草稿' };
+      ? { search: 'Search the book', toc: 'Contents', none: 'No match', hits: ' hits', chapter: 'Chapter', sections: 'sections', menu: 'Chapters', draft: 'Draft' }
+      : { search: '搜索全书', toc: '目录', none: '没有匹配', hits: ' 处', chapter: '第', sections: '节', menu: '章节', draft: '草稿' };
 
     var layout = document.querySelector('.am-doc-layout');
     var body = document.querySelector('.am-doc-body');
@@ -33,10 +33,8 @@
         : L.chapter + chapter.n + '章 ' + chapter.name;
     }
 
-    function sectionLabel(unit) {
-      return book.lang === 'en'
-        ? L.section + ' ' + unit.section
-        : L.section + unit.section + '节';
+    function sectionNumber(unit) {
+      return unit.chapter + '.' + unit.section;
     }
 
     function chapterCount(chapter) {
@@ -46,9 +44,7 @@
     }
 
     function sectionTitle(unit) {
-      return book.lang === 'en'
-        ? L.section + ' ' + unit.section + '. ' + unit.title
-        : L.section + unit.section + '节 ' + unit.title;
+      return sectionNumber(unit) + ' ' + unit.title;
     }
 
     var style = document.createElement('style');
@@ -70,6 +66,8 @@
       '.am-doc-body .am-md h3 { font-size: 18px; font-weight: 650; margin-top: 28px; }',
       '.am-doc-body .am-md h3:first-child { margin-top: 0; }',
       '.am-doc-body .am-md h4 { font-size: 16px; font-weight: 600; margin-top: 20px; }',
+      // am's overflow-x:auto makes overflow-y auto too; a 1px overshoot draws scrollbar arrows on Windows.
+      '.am-math-block { overflow-y: hidden; }',
       '.bk-context { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; margin: 0 0 8px; font-size: 13px; }',
       '.bk-context-chapter { color: var(--ink-2); font-weight: 600; }',
       '.bk-context-section { color: var(--ink-3); white-space: nowrap; }',
@@ -151,7 +149,7 @@
         chapter.textContent = chapterTitle(g.chapter);
         var section = document.createElement('span');
         section.className = 'bk-context-section';
-        section.innerHTML = esc(sectionLabel(u)) + draftTag(u);
+        section.innerHTML = esc(sectionNumber(u)) + draftTag(u);
         context.appendChild(chapter);
         context.appendChild(section);
         var heading = panel.querySelector('.am-panel-head');

package/skills/study-plus/scripts/build-book.mjs

@@ -82,9 +82,13 @@ function build() {
     ...(book.goal ? [`subtitle: ${JSON.stringify(book.goal)}`] : []),
     '---',
     '',
-    book.units.map((unit) => `## ${unit.section}. ${unit.title}\n\n${unit.body}`).join('\n\n'),
+    book.units.map((unit) => `## ${unit.chapter}.${unit.section} ${unit.title}\n\n${unit.body}`).join('\n\n'),
     '',
-  ].join('\n');
+  ].join('\n')
+    // am reads $ and $$ math only: a LaTeX display delimiter on its own line
+    // would reach the page as a literal bracket, so turn it into a $$ block.
+    .replace(/^ {0,3}\\\[\s*$/gm, () => '$$')
+    .replace(/^ {0,3}\\\]\s*$/gm, () => '$$');
   const outPath = join(dir, 'book.html');
   const backupPath = join(dir, 'book.html.bak');
   const guardPath = (path, what) => {
@@ -123,7 +127,9 @@ function build() {
       units: book.units.map(({ concept, title, chapter, section, index, status }) => ({ concept, title, chapter, section, index, status })),
     };
     const json = JSON.stringify(payload).replace(/</g, '\\u003c');
-    const client = readFileSync(CLIENT, 'utf8');
+    // HTML parsing turns CRLF into LF before the browser checks the CSP hash,
+    // so a Windows checkout would otherwise be blocked as the wrong hash.
+    const client = readFileSync(CLIENT, 'utf8').replace(/\r\n?/g, '\n');
     const html = readFileSync(tmpPath, 'utf8');
     const scriptText = `\n${client}\n`;
     const hash = createHash('sha256').update(scriptText, 'utf8').digest('base64');