acmer-coach 2.4.0 → 2.5.0

package/dev/teaching-check.mjs

@@ -0,0 +1,191 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { createTeachingNotes } from '../lib/teaching.js'
+
+const AT = '2026-10-11T10:00:00.000Z'
+const EXEC = { agent: { session: { id: 'session-1' } } }
+const QUOTE = '状态不需要保存选择顺序，只需要保存剩余容量。'
+const userEvent = (overrides = {}) => ({
+  type: 'user/message', seq: 7,
+  data: { id: 'message-7', role: 'user', source: { kind: 'user' }, content: [{ type: 'text', text: QUOTE }] },
+  ...overrides,
+})
+
+function fixture(t) {
+  const root = mkdtempSync(join(tmpdir(), 'acmer-coach-teaching-'))
+  const path = join(root, 'PROGRESS.json')
+  const initial = {
+    version: 1, cursor: 'dp', updated: '2026-10-10',
+    nodes: { dp: { status: 'verified', taught: '2026-10-09', passes: [{ date: '2026-10-10' }] } },
+    pending: { node: 'graph', date: '2026-10-11', problems: ['fixture-problem'] },
+    pendingActions: { dp: { node: 'dp', deliverable: '写出状态含义' } },
+    verified_problems: { 'fixture-problem': { source: 'fixture' } },
+  }
+  writeFileSync(path, JSON.stringify(initial))
+  t.after(() => { unlinkSync(path); rmdirSync(root) })
+  const loadProgress = () => JSON.parse(readFileSync(path, 'utf8'))
+  const saveProgress = (p) => { writeFileSync(path, JSON.stringify(p)); return p }
+  const dependencies = {
+    loadProgress, saveProgress,
+    loadMap: () => ({ byId: new Map([['dp', { id: 'dp', name: '动态规划基础' }], ['graph', { id: 'graph', name: '最短路' }]]) }),
+    getSessionQuery: () => undefined,
+    now: () => AT,
+  }
+  return { initial, loadProgress, saveProgress, dependencies, create: () => createTeachingNotes(dependencies) }
+}
+
+test('续课笔记留在既有节点账本，重建后可读且不改变掌握与待测卷', async (t) => {
+  const f = fixture(t)
+  const result = await f.create().write({ summary: '状态含义还需检查', nextStep: '用三个物品的小例子让学生解释状态' })
+  assert.equal(result.ok, true)
+  assert.equal(result.node, 'dp')
+  assert.deepEqual(result.notes, [{ at: AT, summary: '状态含义还需检查', nextStep: '用三个物品的小例子让学生解释状态' }])
+  assert.deepEqual(f.create().read(), result)
+  const expected = structuredClone(f.initial)
+  expected.nodes.dp.lessonNotes = [{ ...result.notes[0], studentEvidence: null }]
+  assert.deepEqual(f.loadProgress(), expected)
+})
+
+test('无效知识点、空白和超长笔记不能写入账本', async (t) => {
+  const f = fixture(t)
+  const notes = f.create()
+  const valid = { summary: '仍需辨析状态', nextStep: '解释一个反例' }
+  for (const change of [
+    { node: 'unknown' }, { node: 123 }, { summary: '   ' }, { summary: 'x'.repeat(1001) },
+    { nextStep: '' }, { nextStep: 'x'.repeat(501) }, { studentQuote: ' ' },
+    { studentQuote: 'x'.repeat(1501) },
+  ]) {
+    const result = await notes.write({ ...valid, ...change })
+    assert.equal(result.ok, false, JSON.stringify(change))
+    assert.deepEqual(result.notes, [])
+    assert.equal(result.total, 0)
+    assert.deepEqual(f.loadProgress(), f.initial)
+  }
+  for (const limit of [0, -1, 21, 1.5, '5']) assert.equal(notes.read({ limit }).ok, false)
+})
+
+test('学生原话通过当前原生会话核对并保存稳定出处', async (t) => {
+  const f = fixture(t)
+  let queried
+  f.dependencies.getSessionQuery = () => ({ readSession: async (id) => {
+    queried = id
+    return { session: { id }, events: [userEvent()] }
+  } })
+  const result = await f.create().write({ summary: '能区分容量和顺序，尚未检查代码', nextStep: '独立实现转移', studentQuote: QUOTE }, EXEC)
+  assert.equal(queried, 'session-1')
+  assert.equal(result.ok, true)
+  assert.deepEqual(result.notes[0].studentEvidence, { sessionId: 'session-1', seq: 7, messageId: 'message-7', quote: QUOTE })
+  assert.equal(f.loadProgress().nodes.dp.status, 'verified')
+})
+
+test('伪造原话、插件消息、跨会话内容或缺失出处不能成为学生依据', async (t) => {
+  const invalidEvent = [
+    userEvent({ data: { ...userEvent().data, content: [{ type: 'text', text: '别的答复' }] } }),
+    userEvent({ data: { ...userEvent().data, source: { kind: 'plugin:coach' } } }),
+    userEvent({ data: { ...userEvent().data, role: 'assistant' } }),
+    userEvent({ seq: -1 }), userEvent({ seq: undefined }),
+    userEvent({ data: { ...userEvent().data, id: '' } }),
+    userEvent({ type: 'compaction/message' }),
+    userEvent({ data: { ...userEvent().data, content: [{ type: 'image', text: QUOTE }] } }),
+  ]
+  for (const event of invalidEvent) {
+    const f = fixture(t)
+    f.dependencies.getSessionQuery = () => ({ readSession: async () => ({ session: { id: 'session-1' }, events: [event] }) })
+    const result = await f.create().write({ summary: '判断', nextStep: '继续', studentQuote: QUOTE }, EXEC)
+    assert.equal(result.ok, false)
+    assert.deepEqual(f.loadProgress(), f.initial)
+  }
+  const f = fixture(t)
+  const params = { summary: '判断', nextStep: '继续', studentQuote: QUOTE }
+  assert.equal((await f.create().write(params, EXEC)).ok, false, '无会话查询服务必须拒绝')
+  f.dependencies.getSessionQuery = () => ({ readSession: async () => ({ session: { id: 'another-session' }, events: [userEvent()] }) })
+  assert.equal((await f.create().write(params, EXEC)).ok, false)
+  assert.equal((await f.create().write(params)).ok, false, '无当前调用会话必须拒绝')
+  f.dependencies.getSessionQuery = () => ({ readSession: async () => { throw new Error('unavailable') } })
+  assert.equal((await f.create().write(params, EXEC)).ok, false)
+  assert.deepEqual(f.loadProgress(), f.initial)
+})
+
+test('没有游标时找最近一次续课，默认只读最近五条并保留全部历史', async (t) => {
+  const f = fixture(t)
+  const notes = f.create()
+  for (let i = 1; i <= 6; i++) await notes.write({ summary: `第${i}次讲解`, nextStep: '继续解释转移' })
+  assert.equal(notes.read().total, 6)
+  assert.equal(notes.read().notes.length, 5)
+  assert.equal(notes.read().notes[0].summary, '第2次讲解')
+  f.dependencies.now = () => '2026-10-11T11:00:00.000Z'
+  await f.create().write({ node: 'graph', summary: '图上松弛还要澄清', nextStep: '比较两条路径' })
+  const progress = f.loadProgress()
+  progress.cursor = ''
+  progress.pendingActions = {}
+  f.saveProgress(progress)
+  assert.equal(f.create().read().node, 'graph')
+  assert.equal(f.create().read({ node: 'dp', limit: 20 }).notes.length, 6)
+})
+
+test('续课上下文短且标明教练判断，核对原话不等于证明掌握', async (t) => {
+  const f = fixture(t)
+  const notes = f.create()
+  assert.equal(notes.context(f.loadProgress()), '')
+  await notes.write({ summary: '状态含义还需辨析'.repeat(100), nextStep: '用小例子解释状态'.repeat(60) })
+  const context = notes.context(f.loadProgress())
+  assert.ok(context.length <= 700)
+  assert.match(context, /教练判断/)
+  assert.match(context, /下次接续/)
+  assert.equal(notes.context(f.loadProgress(), 'graph'), '')
+  f.dependencies.getSessionQuery = () => ({ readSession: async () => ({ session: { id: 'session-1' }, events: [userEvent()] }) })
+  await f.create().write({ summary: '对状态有一个合理解释', nextStep: '独立写出转移', studentQuote: QUOTE }, EXEC)
+  const grounded = f.create().context(f.loadProgress())
+  assert.match(grounded, /原话已核对/)
+  assert.match(grounded, /不代表掌握/)
+  assert.match(grounded, /独立写出转移/)
+})
+
+test('原话查询期间其他工具保存的进度不会被旧快照覆盖', async (t) => {
+  const f = fixture(t)
+  let release
+  f.dependencies.getSessionQuery = () => ({ readSession: () => new Promise((resolve) => { release = resolve }) })
+  const writing = f.create().write({ summary: '状态解释待验证', nextStep: '写出转移', studentQuote: QUOTE }, EXEC)
+  const updated = f.loadProgress()
+  updated.cursor = 'graph'
+  updated.nodes.graph = { status: 'studying', checks: [{ outcome: 'needs-work' }] }
+  updated.pendingActions.dp.deliverable = '更新后的动作'
+  f.saveProgress(updated)
+  release({ session: { id: 'session-1' }, events: [userEvent()] })
+  assert.equal((await writing).ok, true)
+  const saved = f.loadProgress()
+  assert.equal(saved.cursor, 'graph')
+  assert.deepEqual(saved.nodes.graph, updated.nodes.graph)
+  assert.deepEqual(saved.pendingActions, updated.pendingActions)
+  assert.deepEqual(saved.pending, updated.pending)
+  assert.deepEqual(saved.verified_problems, updated.verified_problems)
+  assert.equal(saved.nodes.dp.lessonNotes.length, 1)
+})
+
+test('续课优先最近未完动作的笔记，显式读取和默认写入不受选择影响', async (t) => {
+  const f = fixture(t)
+  await f.create().write({ summary: '游标节点的旧笔记', nextStep: '继续状态解释' })
+  const progress = f.loadProgress()
+  progress.pendingActions.graph = { node: 'graph', deliverable: '解释松弛' }
+  f.saveProgress(progress)
+  f.dependencies.now = () => '2026-10-11T11:00:00.000Z'
+  await f.create().write({ node: 'graph', summary: '刚讲到路径比较', nextStep: '继续比较两条路径' })
+  const notes = f.create()
+  assert.equal(notes.read().node, 'graph')
+  assert.match(notes.context(f.loadProgress()), /刚讲到路径比较/)
+  assert.equal(notes.read({ node: 'dp' }).node, 'dp')
+  assert.match(notes.context(f.loadProgress(), 'dp'), /游标节点的旧笔记/)
+  f.dependencies.now = () => '2026-10-11T12:00:00.000Z'
+  assert.equal((await f.create().write({ summary: '仍写入当前游标', nextStep: '继续游标节点' })).node, 'dp')
+  assert.equal(f.loadProgress().cursor, 'dp')
+  assert.deepEqual(f.loadProgress().pendingActions, progress.pendingActions)
+  assert.equal(f.create().read().node, 'dp', '多个未完动作按笔记时间选最近')
+  const finished = f.loadProgress()
+  delete finished.pendingActions.graph
+  delete finished.pendingActions.dp
+  f.saveProgress(finished)
+  assert.equal(f.create().read().node, 'dp', '没有未完动作回到当前游标')
+})

package/dev/vp-sync-check.mjs

@@ -9,7 +9,7 @@ function shape(schema, value) {
     assert.ok(value && typeof value === 'object' && !Array.isArray(value))
     if (schema.additionalProperties === false) for (const key of Object.keys(value)) assert.ok(key in schema.properties, `unexpected field ${key}`)
     for (const [key, field] of Object.entries(schema.properties ?? {})) {
-      if (field.required) assert.ok(key in value, `missing field ${key}`)
+      if (field.required === true || (Array.isArray(schema.required) && schema.required.includes(key))) assert.ok(key in value, `missing field ${key}`)
       if (key in value) shape(field, value[key])
     }
   } else if (schema.type === 'array') {

package/dev.sh

@@ -35,7 +35,7 @@ done
 # 从副本目录跑 `bash dev.sh` 走的是另一条路（`dsh plugin remove/add`，而那条
 # 路不可靠），和这份的行为不一样。换句话说，**同一个命令，从哪个目录按回车
 # 决定跑哪份脚本** —— 两份 dev.sh 就是两份真相，正是这份文件在防的那种坑。
-SYNC_FILES='index.js package.json verify.mjs verify-shape.mjs progress-cli.mjs build-node-meta.mjs cordis.patch.yml README.md lib/client.js lib/vp-client.js lib/workspace-migration.js lib/setup.js lib/curriculum.js lib/curriculum-evidence.js lib/curriculum-planning.js lib/strategy.js assets/knowledge/COMPETENCIES.yaml assets/knowledge/NODE_SCOPES.yaml assets/knowledge/CONTEST_PROFILES.yaml assets/knowledge/vp.html assets/rules/coach-rules.md dev/curriculum-check.mjs dev/curriculum-evidence-check.mjs dev/strategy-check.mjs dev/workspace-migration-check.mjs dev/vp-client-check.mjs dev/vp-sync-check.mjs dev/catalog-check.mjs dev/coaching-contract-check.mjs docs/长期课程机制.md docs/比赛与教学依据.md docs/设计方针.md dev.sh'
+SYNC_FILES='index.js package.json verify.mjs verify-shape.mjs progress-cli.mjs build-node-meta.mjs cordis.patch.yml README.md lib/client.js lib/vp-client.js lib/workspace-migration.js lib/setup.js lib/curriculum.js lib/curriculum-evidence.js lib/curriculum-planning.js lib/strategy.js lib/teaching.js assets/knowledge/COMPETENCIES.yaml assets/knowledge/NODE_SCOPES.yaml assets/knowledge/CONTEST_PROFILES.yaml assets/knowledge/vp.html assets/rules/coach-rules.md dev/curriculum-check.mjs dev/curriculum-evidence-check.mjs dev/strategy-check.mjs dev/workspace-migration-check.mjs dev/vp-client-check.mjs dev/vp-sync-check.mjs dev/catalog-check.mjs dev/coaching-contract-check.mjs dev/teaching-check.mjs dev/run-all.sh docs/长期课程机制.md docs/比赛与教学依据.md docs/设计方针.md dev.sh'
 STALE=''
 for f in $SYNC_FILES; do
   for d in "${DSTS[@]}"; do
@@ -120,7 +120,7 @@ EVIDENCE_RC=${EVIDENCE_RC:-0}
 
 echo
 echo '── 策略、教学目录、真实工具与账号数据回归 ──'
-node --test "$SRC_BASH/dev/strategy-check.mjs" "$SRC_BASH/dev/catalog-check.mjs" "$SRC_BASH/dev/coaching-contract-check.mjs" "$SRC_BASH/dev/workspace-migration-check.mjs" "$SRC_BASH/dev/vp-client-check.mjs" "$SRC_BASH/dev/vp-sync-check.mjs" || CONTRACT_RC=$?
+node --test "$SRC_BASH/dev/strategy-check.mjs" "$SRC_BASH/dev/catalog-check.mjs" "$SRC_BASH/dev/coaching-contract-check.mjs" "$SRC_BASH/dev/teaching-check.mjs" "$SRC_BASH/dev/workspace-migration-check.mjs" "$SRC_BASH/dev/vp-client-check.mjs" "$SRC_BASH/dev/vp-sync-check.mjs" || CONTRACT_RC=$?
 CONTRACT_RC=${CONTRACT_RC:-0}
 
 LEDGER_AFTER=$(ledger_fp)

package/docs//346/257/224/350/265/233/344/270/216/346/225/231/345/255/246/344/276/235/346/215/256.md

@@ -31,6 +31,37 @@ WF 扩展诊断只读了 [2024 World Finals 官方题面](https://icpc.global/wo
 
 用户临时问新知识点时可以回答。回答不自动成为主线任务，也不自动改变游标或阶段。
 
+## 2.5：给教练续课依据，不代替教练判断
+
+本版只增加 `coach_note` 的读写入口，笔记放进现有 `PROGRESS.nodes.<id>.lessonNotes`。
+记录是“当前教学判断 + 下一次接续点”；可选学生原话通过 dsh 原生 `sessionQuery`
+核对当前会话的真实用户消息，来源由程序生成。插件消息或压缩摘要不能成为学生原话。
+核对存在不证明理解，笔记也不改变游标、掌握状态、待办或检测结果。
+
+`coach_status` 和原有会话首步注入只提供短笔记，详细材料按需读取。
+默认读取优先接续最近有笔记的未完动作，再看游标；无游标时看最近笔记。
+写入默认落在当前游标，指定节点时使用该节点，不改变游标本身。
+教学进展或中断值得保存时才写，不要求每轮留笔记，不规定固定工具顺序。
+能力排名作为参考，前三之外或尚未映射到能力的节点仍允许教练安排；
+课程、前置和写入证据的检查保留。`teachMinutes` 是计划，不自动生成已教学日期，
+实际开始学习仍由教练显式记录；旧记录保留，不重新推断发生过什么。
+
+这个取舍是结合本插件所做的设计判断：
+
+* [Anthropic：Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
+  与 [OpenAI：A practical guide to building agents](https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/)
+  都建议从简单、可验证的方案开始。因此沿用小鲸这个 agent，未增加多教练编排或框架。
+* [Anthropic：Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+  支持保留必要摘要、按需获取详情；本版沿用原进度文件与宿主会话查询，不复制聊天数据库。
+* [Anthropic：Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
+  强调清楚、职责明确的工具与真实任务评测；本版把续课笔记与已有检测、日程工具分开，
+  不用固定调用次序判断教练是否正确。
+* [Anthropic：Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
+  区分任务结果与交互质量；工具回归只能验证记录和来源，不能据此声称学生学习效果已证实。
+
+验证覆盖跨模块实例读取、原话来源、拒绝伪引用和并行更新时保留已有进度。
+没有做真实学生的长期对照试验，也没有把笔记数量当教学质量分数。
+
 ## 四个明确的教学边界
 
 最短路卡提供有向边 `s→a:2`、`s→b:5`、`b→a:-4`：确定后不再更新的 Dijkstra 会过早确定 a；真实最短距离是 1。算法仍偶尔得到对的结果不能证明它适用于负权图。[技术依据](https://oi-wiki.org/graph/shortest-path/)

package/docs//350/256/276/350/256/241/346/226/271/351/222/210.md

@@ -7,7 +7,7 @@
 
 ## 一、一句话命题
 
-> **教练的价值不是知识，是位置。**
+> **教练把比赛目标、当下理解和下一步教学连起来。**
 >
 > 它站在局外、手里有地图、且不投入自尊。
 > 在局里的人看不见河的全貌 —— 这跟聪明程度无关，是位置问题。
@@ -16,7 +16,8 @@
 排优先级需要「什么重要、什么先什么后、哪里是坑」——
 而这些恰好是初学者没有的知识。**这是循环依赖，必须由外部打破。**
 
-市面上不缺讲解算法的资料，也不缺题。缺的是**替你排顺序**的那个人。
+资料和题目已经很多。教练要选择重点、讲清推理、核对理解，
+根据真实回应调整讲法，并在下次接着教；排顺序只是其中一项。
 
 ---
 
@@ -116,9 +117,9 @@ verified 是有日期和条件的检测结论，不是永久标签。阶段验
 「今天说了明天又忘」不是记忆问题，是**强制力问题**。治法见第五节。
 
 **但这条有边界，得说清楚**：结构只能强制**机械可判**的那一半。
-「新知识点必须先讲」可以做成闸门（没带 `teachMinutes` 就拒绝），
-因为「讲没讲过」是可判的；而「这块该不该复习」判不了，只能靠教练的判断。
-**别把后者也硬做成规则** —— 那会变成一个用错误数据下命令的系统。
+新知识点的工具可以要求留出讲解预算（`teachMinutes`），但预算只证明有计划，
+不能核实授课完成或学生理解。续课笔记保存教学线索，原话核对也只证明消息存在。
+讲法、重点与复习取舍交给教练；程序约束证据来源、账本写入和任务执行边界。
 
 ### 原则 6：命名是终点，不是入口（讲题规范）
 

package/index.js

@@ -1,7 +1,7 @@
 // acmer-coach
 // ══════════════════════════════════════════════════════════════════
-// 小鲸教练插件。目标：把「位置 + 判断」从小鲸的转述里拿回来 ——
-// 给它唯一动作、让它读代码判因、按检测推进，而不是报一堆百分比。
+// 小鲸教练插件。目标：保存训练位置与可核查的证据，
+// 让教练据此决定讲法、练习和复习，避免跨会话丢进度。
 //
 // 注册走 bundle 层：package.json 声明 `dsh.bundle.patch`，由
 // cordis.patch.yml 里那行 insert 挂上去。
@@ -31,13 +31,14 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { initDataDir, syncCodeforces, contactEvidence, importPool, importRecords } from './lib/setup.js'
 import { createCurriculumStore, curriculumTool } from './lib/curriculum.js'
 import { createStrategyStore } from './lib/strategy.js'
+import { createTeachingNotes } from './lib/teaching.js'
 import { createVpClient } from './lib/vp-client.js'
 import { migratePersonalWorkspace as migrateWorkspacePersonalFiles } from './lib/workspace-migration.js'
 
 const name = 'acmer-coach'
 const inject = ['tools']
 
-const VERSION = '2.4.0'
+const VERSION = '2.5.0'
 
 // 块结构（方针 §4.1.1）：40 自己做 + 10 解决遗留 + 10 重写 = 60 分钟。
 // 这是**一个题目循环**的固定形状。时间不够该换更小的题，不是把块压扁。
@@ -993,7 +994,7 @@ function nodeFlags(progress, byId) {
 // 判据 = 进度文件里**有没有关于这个节点的记录**。缺省即未学（见 nodeStatus：
 // 只有非未学的节点才会被写进文件），所以"记录存在"本身就说明有东西发生过：
 //   · `rec.at`   —— 教练标过「在学」的那天（见 markStatus：只在状态真变时更新）
-//   · `taught`   —— 布置过讲授段的那天（coach_assign 带 teachMinutes）
+//   · `taught`   —— 旧版讲解计划留下的日期，保留兼容，不证明实际讲过
 //   · `passes`   —— 他打过卡（coach_log）
 //   · `checks`   —— 判过一次卷（coach_grade）
 //
@@ -1008,9 +1009,7 @@ function taughtEvidence(progress, id) {
   if (!rec) return null
   const dates = [
     String(rec.at ?? ''),
-    // 讲授段的落点：在这之前，讲过的节点**不留任何痕迹** ——
-    // coach_status 会一直报「还没有教学记录」，而"游标节点豁免先讲闸门"这条
-    // 也就永远没法按"讲过没"来判断（这个漏洞就是从这儿反推出来的）。
+    // 兼容旧版接触线索；新计划不再写 taught，续课笔记也不算掌握证据。
     ...(Array.isArray(rec.taught) ? rec.taught.map((t) => String(t ?? '')) : []),
     ...(Array.isArray(rec.passes) ? rec.passes.map((p) => String(p?.date ?? '')) : []),
     ...(Array.isArray(rec.checks) ? rec.checks.map((c) => String(c?.date ?? '')) : []),
@@ -1670,7 +1669,7 @@ function registerPages(ctx) {
 // 它要防的是"规则被长对话压掉"，而规则在 AGENTS.md 里 —— 那是 system prompt，
 // 压根不参与压缩。真正会丢的是**位置**，而 pre-step 每轮都重注一遍，
 // 压掉的下一轮就回来了。所以那半条是多余的。
-function registerStateHook(ctx) {
+function registerStateHook(ctx, teaching) {
   ctx.on('agent/pre-step', async ({ messages, step }, next) => {
     const decision = await next()
     try {
@@ -1684,13 +1683,14 @@ function registerStateHook(ctx) {
       const studying = Object.entries(p.nodes ?? {})
         .filter(([, r]) => r?.status === 'studying')
         .map(([id]) => id)
+      const teachingContext = teaching.context(p)
 
       // 课程可以先于游标存在；即使尚未布置动作，也要在新会话继续同一路线。
       let hasCurriculum = false
       try { hasCurriculum = Boolean(curriculum.load()) } catch { hasCurriculum = true }
       let hasTarget = false
       try { hasTarget = Boolean(strategy.loadTarget().contest) } catch { hasTarget = true }
-      if (!cursor && !pending && !studying.length && !hasCurriculum && !hasTarget) return decision
+      if (!cursor && !pending && !studying.length && !hasCurriculum && !hasTarget && !teachingContext) return decision
 
       const { byId } = loadMap()
       const nameOf = (id) => byId.get(String(id))?.name ?? String(id)
@@ -1698,6 +1698,7 @@ function registerStateHook(ctx) {
       const lines = ['<coach_state>', '（教练插件注入的位置，不用再调工具问）']
       lines.push(strategy.context())
       lines.push(curriculum.context())
+      if (teachingContext) lines.push(teachingContext)
       lines.push(cursor
         ? `- 游标：${nameOf(cursor)}（${cursor}）${node?.domain ? `　[${node.domain}]` : ''}`
         : '- 游标：**还没设** —— 先问清他现在在哪个知识点，用 coach_set_cursor 设上')
@@ -1951,6 +1952,43 @@ function apply(ctx) {
   } catch { /* 没这服务 / 没这文件 → 不注，照常加载 */ }
 
   ctx.tools.register(defineTool(curriculumTool(curriculum)))
+  const teaching = createTeachingNotes({ loadProgress, saveProgress, loadMap,
+    getSessionQuery: () => ctx.get?.('sessionQuery') })
+  ctx.tools.register(defineTool({
+    name: 'coach_note',
+    description: '读取或保存简短续课笔记：讲到哪里、教练的判断、下次怎样接着讲。复用节点进度账本；不改掌握状态或自动决定下一课。' +
+      'studentQuote 可选；提供时自动核对当前会话的学生原话，核对存在不代表已经理解。无回应依据时写明尚未核对，不编造表现。',
+    parameters: {
+      action: { type: 'string', enum: ['read', 'write'], description: '默认 read；write 追加一条笔记。' },
+      node: { type: 'string', description: '地图节点 id。写入默认游标；读取默认最近有笔记的未完动作，其次游标，无游标时读最近笔记。显式指定始终优先。' },
+      limit: { type: 'integer', description: '读取最近几条，默认 5，最多 20。' },
+      summary: { type: 'string', description: 'write 必填，实际讲授位置和教练判断，最多 1000 字；区分观察与推测。' },
+      nextStep: { type: 'string', description: 'write 必填，下次续课建议，最多 500 字；后续教练可据新表现调整。' },
+      studentQuote: { type: 'string', description: '可选，当前会话学生实际发过的一段原话，最多 1500 字；不需要手输消息 id。' },
+    },
+    output: { schema: { type: 'object', additionalProperties: false, properties: {
+      ok: { type: 'boolean', required: true }, reject: { type: 'string', required: true },
+      node: { type: 'string', required: true }, total: { type: 'integer', required: true },
+      notes: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
+        at: { type: 'string', required: true }, summary: { type: 'string', required: true }, nextStep: { type: 'string', required: true },
+        studentEvidence: { type: 'object', additionalProperties: false, properties: {
+          sessionId: { type: 'string', required: true }, seq: { type: 'integer', required: true },
+          messageId: { type: 'string', required: true }, quote: { type: 'string', required: true },
+        } },
+      } } },
+    } }, render: (_args, v) => [{ type: 'text', text: !v.ok ? `❌ ${v.reject}` : v.notes.length
+      ? `续课笔记 · ${v.node}（最近 ${v.notes.length} / 共 ${v.total} 条）\n` + v.notes.map(note =>
+        `${note.at}\n教练记录：${note.summary}\n续课建议：${note.nextStep}\n` +
+        (note.studentEvidence ? `学生原话：「${note.studentEvidence.quote}」（存在已核对，理解程度仍由教练判断）`
+          : '尚无学生回应依据；这条是教练笔记。')).join('\n\n')
+      : `「${v.node || '当前节点'}」尚无续课笔记。` }] },
+    execute: async (args = {}, exec) => {
+      const action = args.action ?? 'read'
+      if (action === 'read') return teaching.read(args)
+      if (action === 'write') return teaching.write(args, exec)
+      return { ok: false, reject: 'action 只能是 read 或 write。', node: '', notes: [], total: 0 }
+    },
+  }))
 
   // ── 目标驱动策略层：比赛目标 / VP 证据 / 复盘 / 当前重点 ─────────
   // 课程图回答“有哪些知识点”，策略层回答“为什么现在学这个”。两者分开，
@@ -2747,7 +2785,7 @@ function apply(ctx) {
               (v.suggestions.length ? `\n相近的有：${v.suggestions.join(' / ')}` : '\n也没找到相近的，确认一下写法。'),
           }]
         }
-        const TIER_TAG = { core: '★核心', normal: '常见', rare: '少见', skip: '不考' }
+        const TIER_TAG = { core: '★核心', normal: '常见', rare: '少见', skip: '默认暂缓' }
         // （需求 #4）：**每个节点都要出 entry**。
         // 原来是 `c.entry ? ' ≈'+c.entry : ''` —— 于是「没数据」和「够不着」
         // 在输出里长得一模一样（都是不显示），很容易把"没数据"读成
@@ -2990,7 +3028,7 @@ function apply(ctx) {
       '它一次只收一个节点，所以**给不出候选列表** —— 这正是设计意图。' +
       '有长期课程时先读 coach_curriculum，带 curriculumRevision；主线必须属于当前阶段，' +
       '补漏或复习用 purpose 与 routeReason 说明关系和回归条件。课程节点可以跨图分支，但前置检查仍生效。' +
-      '有比赛目标时，progress 动作还必须落在当前目标能力；跨重点训练只能走课程绑定，' +
+      '比赛目标与重点排序是决策参考，不会限制在排名前三；结合学生表现说明 why。' +
       '补漏/复习必须说明 routeReason。',
     parameters: {
       cursor: {
@@ -3013,7 +3051,8 @@ function apply(ctx) {
           '**先讲一遍**的时间（分钟）。开一个他从没碰过的知识点时**必须给**，' +
           '不给会被拒绝 —— 直接扔题让他自己卡，那是给学过的人的练法。' +
           '讲多久**你自己定**（不参考任何固定值），看你判断他需要多少。' +
-          `最低 ${TEACH_FLOOR_MIN} 分钟，没有上限。已经在学或学过的节点不用给。`,
+          `最低 ${TEACH_FLOOR_MIN} 分钟，没有上限。已经在学或学过的节点不用给。` +
+          '这是计划时长，不能证明已经讲过或学生理解了。',
       },
       why: { type: 'string', description: '为什么挑它（一句话，进台账，供训练员质疑时举证）' },
       curriculumRevision: { type: 'integer', description: '有效课程 read 返回的 revision；无课程时可不填。' },
@@ -3163,7 +3202,7 @@ function apply(ctx) {
       const targetRoute = strategy.route(node, { purpose: args?.purpose, courseBound: Boolean(route.binding) })
       if (!targetRoute.ok) return deny(targetRoute.reject)
       if (targetRoute.competencyIds.length) {
-        why = `目标能力「${targetRoute.competencyIds.join('、')}」：${why || '当前重点对应的训练动作'}`
+        why = `目标能力「${targetRoute.competencyIds.join('、')}」：${why || '目标能力对应的训练动作'}`
       }
 
       // ③ 未建课程时沿用直接后继；有课程时允许当前阶段跨分支，仍检查前置。
@@ -3271,18 +3310,7 @@ function apply(ctx) {
         totalMinutes: net + teach + TAIL_MIN, why,
       }
       if (route.binding) pend[node].curriculum = route.binding
-      // 讲授段落盘：带 teachMinutes = 这次布置含讲授段，
-      // 在节点上记一条 `taught` 日期 —— 它是「讲过没」唯一的结构化痕迹。
-      // 在这之前讲完**不留任何记录**：coach_status 永远报「还没有教学记录」，
-      // 游标节点那条豁免也就没法按"讲过没"来判断（漏洞就是从这儿反推出来的）。
-      // 记的是"讲授段排上了"这一天，不是"讲得多好" —— 回答"讲过没"够用了。
-      if (teach > 0) {
-        const rec = { ...(progA.nodes[node] ?? {}) }
-        const taught = Array.isArray(rec.taught) ? rec.taught.slice() : []
-        if (!taught.includes(assignedAt)) taught.push(assignedAt)
-        rec.taught = taught
-        progA.nodes[node] = rec
-      }
+      // 布置讲解只保存计划；接触状态与理解证据由各自入口记录。
       progA.pendingActions = pend
       let pendingRecorded = true
       try { saveProgress(progA) } catch { pendingRecorded = false }
@@ -3332,6 +3360,7 @@ function apply(ctx) {
           // 让"讲过没"对教练**可查** —— 判据跟 coach_test 开卷时用的同一个
           // 函数（taughtEvidence），不另写一份。需求 #5 的验收 ③。
           cursorTaught: { type: 'string', required: true },
+          teachingContext: { type: 'string', required: true },
           domain: { type: 'string', required: true },
           updated: { type: 'string', required: true },
           verifiedCount: { type: 'integer', required: true },
@@ -3489,9 +3518,10 @@ function apply(ctx) {
             // 十有八九就是游标这个节点。埋在别处等于没报。（需求 #5 验收 ③）
             (v.cursorName
               ? (v.cursorTaught
-                ? `　讲于 ${v.cursorTaught}`
+                ? `　接触记录 ${v.cursorTaught}（不证明理解）`
                 : `　⚠️ **还没有教学记录** —— 现在开卷会被拒，先讲`)
               : ''),
+          v.teachingContext,
           // 押着的卷放最前面之一：它是个**卡住下一步的约束**（有新卷就开不了），
           // 埋在底下等于没报。
           v.pendingNode
@@ -3640,6 +3670,7 @@ function apply(ctx) {
         cursor: p.cursor,
         cursorName: byId.get(p.cursor)?.name ?? '',
         cursorTaught: taughtEvidence(p, p.cursor)?.first ?? '',
+        teachingContext: teaching.context(p),
         domain: byId.get(p.cursor)?.domain ?? '',
         updated: p.updated,
         verifiedCount: verified.length,
@@ -5052,7 +5083,7 @@ function apply(ctx) {
       const deny = (reject) => ({
         ok: false, reject, node: '', nodeName: '', domain: '',
         outcome: '', score: 0, maxScore: 0, passScore: PASS_SCORE,
-        minutes: 0, limit: 0, status: '', verifiedAt: 0, problems: [], checks: 0,
+        minutes: 0, limit: 0, status: '', verifiedAt: 0, selfReported: 0, problems: [], checks: 0,
       })
 
       const prog = loadProgress()
@@ -5593,10 +5624,8 @@ function apply(ctx) {
             L.push(`  ${r.nodeName}　${tag} ${ago}${rec}`)
           }
           L.push('',
-            '⚠️ **复习别把新知识挤没了。** 这套系统的价值在"往前推"，不在"原地保温" —— ' +
-            '一个月的表里全是复习，等于这个月没往前走。他自己会想先复习（复习舒服、' +
-            '做新题难受），**所以那个平衡得你来把**：复习块按上面的火候排，' +
-            '剩下的时间留给推进。')
+            '根据目标、剩余时间和实际表现，选择新课、复习、迁移或 VP。' +
+            '上面的间隔只供判断；不要为了填满课表持续开新知识点。')
         }
         L.push('', '要排就用 coach_plan，**一次只排他说的那一天**。')
         return [{ type: 'text', text: L.join('\n') }]
@@ -6097,8 +6126,8 @@ function apply(ctx) {
     },
   }))
 
-  // 强制力那一层（方针 §五 第四层）：每个 turn 注入当前位置
-  registerStateHook(ctx)
+  // 每个 turn 注入当前位置与续课线索，教学判断仍交给小鲸。
+  registerStateHook(ctx, teaching)
 
   // 技能树页面（可选注入 —— 没有 webServer 的环境跳过，工具照常工作）
   ctx.inject(['webServer'], (sctx) => { registerPages(sctx) })

package/lib/strategy.js

@@ -356,19 +356,13 @@ export function createStrategyStore({ dataDir, vpDir = dataDir, competenciesPath
     const node = clean(nodeOrId)
     let targetDoc
     try { targetDoc = loadTarget() } catch (err) { return { ok: false, reject: err.message, node, purpose, courseBound: Boolean(courseBound), targetAligned: false, competencyIds: [] } }
-    const base = { node, purpose, courseBound: Boolean(courseBound), targetAligned: true, competencyIds: [] }
-    if (!targetDoc.contest || purpose !== 'progress' || courseBound) return { ok: true, reject: '', ...base }
+    const base = { node, purpose, courseBound: Boolean(courseBound), targetAligned: false, competencyIds: [] }
+    if (!targetDoc.contest) return { ok: true, reject: '', ...base }
     const catalog = loadCompetencies()
     const priorityIds = new Set(targetDoc.priorities.map((item) => item.id))
-    const current = focus()
-    const currentIds = new Set((current.focus ?? []).map((item) => item.id))
     const targetCards = catalog.filter((item) => priorityIds.has(item.id) && item.nodes?.includes(node))
-    const currentCards = targetCards.filter((item) => currentIds.has(item.id))
-    const mappedTarget = catalog.filter((item) => priorityIds.has(item.id) && item.nodes?.length)
-    if (mappedTarget.length && !currentCards.length) {
-      return { ok: false, reject: `「${node}」不服务当前比赛重点；当前重点是 ${current.focus.map((item) => item.id).join('、')}。如果这是课程主线，请带 curriculumRevision；如果是补漏/复习，请声明 purpose 和 routeReason。`, ...base, targetAligned: false, competencyIds: targetCards.map((item) => item.id) }
-    }
-    return { ok: true, reject: '', ...base, targetAligned: currentCards.length > 0, competencyIds: currentCards.map((item) => item.id) }
+    // 能力映射只报事实；优先级排名不能替教练决定这一课。
+    return { ok: true, reject: '', ...base, targetAligned: targetCards.length > 0, competencyIds: targetCards.map((item) => item.id) }
   }
 
   function evidence() {

package/lib/teaching.js

@@ -0,0 +1,78 @@
+/** Short lesson continuity notes; teaching judgments never change mastery records. */
+export function createTeachingNotes({ loadProgress, saveProgress, loadMap, getSessionQuery, now = () => new Date().toISOString() }) {
+  const failure = (reject, node = '') => ({ ok: false, reject, node, notes: [], total: 0 })
+  const publicNote = ({ studentEvidence, ...note }) => studentEvidence ? { ...note, studentEvidence } : note
+  const mostRecentNoteNode = (progress, ids) => {
+    let latest = '', latestAt = ''
+    for (const id of ids) {
+      const at = progress.nodes[id]?.lessonNotes?.at(-1)?.at
+      if (at && at >= latestAt) { latest = id; latestAt = at }
+    }
+    return latest
+  }
+  const resolveNode = (progress, node) => {
+    if (node !== undefined) return typeof node === 'string' ? node.trim() : ''
+    return mostRecentNoteNode(progress, Object.keys(progress.pendingActions || {}))
+      || progress.cursor || mostRecentNoteNode(progress, Object.keys(progress.nodes))
+  }
+  const meaningful = (value, max) => typeof value === 'string' && value.trim().length > 0 && value.length <= max
+
+  function read({ node, limit = 5 } = {}) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20) return failure('读取条数须为 1 到 20 的整数。')
+    const progress = loadProgress()
+    node = resolveNode(progress, node)
+    if (!node || !loadMap().byId.has(node)) return failure('请指定有效的知识点或先设置游标。', node)
+    const notes = progress.nodes[node]?.lessonNotes || []
+    return { ok: true, reject: '', node, notes: notes.slice(-limit).map(publicNote), total: notes.length }
+  }
+
+  async function write({ node, summary, nextStep, studentQuote }, exec) {
+    if (!meaningful(summary, 1000) || !meaningful(nextStep, 500)) return failure('教学摘要和下次接续必须有内容，分别最多 1000 和 500 字。')
+    if (studentQuote !== undefined && !meaningful(studentQuote, 1500)) return failure('学生原话必须有内容，最多 1500 字。')
+    let progress = loadProgress()
+    node = node === undefined ? (progress.cursor || '') : typeof node === 'string' ? node.trim() : ''
+    if (!node || !loadMap().byId.has(node)) return failure('请指定有效的知识点或先设置游标。', node)
+    let studentEvidence = null
+    if (studentQuote !== undefined) {
+      const sessionId = exec?.agent?.session?.id
+      if (!meaningful(sessionId, 500)) return failure('无法核对学生原话：当前调用缺少会话标识。', node)
+      try {
+        const query = getSessionQuery?.()
+        if (typeof query?.readSession !== 'function') return failure('无法核对学生原话：宿主未提供会话查询服务。', node)
+        const snapshot = await query.readSession(sessionId)
+        if (snapshot?.session?.id && snapshot.session.id !== sessionId) return failure('会话查询返回了其他会话，未写入笔记。', node)
+        const event = Array.isArray(snapshot?.events) && snapshot.events.findLast((event) => {
+          const message = event.data
+          return event.type === 'user/message' && message?.role === 'user' && message.source?.kind === 'user'
+            && Number.isInteger(event.seq) && event.seq >= 0 && meaningful(message.id, 500)
+            && Array.isArray(message.content) && message.content.filter((block) => block.type === 'text' && typeof block.text === 'string').map((block) => block.text).join('\n').includes(studentQuote)
+        })
+        if (!event) return failure('当前会话中没有可核对的这段学生原话，未写入笔记。', node)
+        studentEvidence = { sessionId, seq: event.seq, messageId: event.data.id, quote: studentQuote }
+      } catch {
+        return failure('会话查询失败，学生原话尚未核对，未写入笔记。', node)
+      }
+      // Session lookup yields; keep any progress another tool saved in the meantime.
+      progress = loadProgress()
+    }
+    const record = progress.nodes[node] || {}
+    progress.nodes[node] = { ...record, lessonNotes: [...(record.lessonNotes || []), { at: now(), summary: summary.trim(), nextStep: nextStep.trim(), studentEvidence }] }
+    saveProgress(progress)
+    return read({ node })
+  }
+
+  function context(progress, preferredNode) {
+    const node = resolveNode(progress, preferredNode)
+    const note = progress.nodes[node]?.lessonNotes?.at(-1)
+    if (!note) return ''
+    const clip = (text, length) => text.replace(/\s+/g, ' ').slice(0, length)
+    const lines = [
+      `续课笔记 · ${clip(node, 60)} · ${note.at}`,
+      `教练判断：${clip(note.summary, 200)}`,
+      note.studentEvidence ? `学生原话已核对（不代表掌握）：${clip(note.studentEvidence.quote, 120)}` : '尚无学生原话依据；这是教练的教学观察。',
+      `下次接续建议（可调整）：${clip(note.nextStep, 220)}`,
+    ]
+    return lines.join('\n')
+  }
+  return { read, write, context }
+}