acmer-coach 2.3.1 → 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-client-check.mjs

@@ -7,6 +7,7 @@ import { createVpClient } from '../lib/vp-client.js'
 const root = mkdtempSync(join(tmpdir(), 'acmer-coach-vp-'))
 let account = { id: 1, handle: 'A', display_name: 'Coach A' }
 let mismatch = false
+let nextPage = false
 const fetchImpl = async (url, options = {}) => {
   const path = new URL(url).pathname
   const body = options.body ? JSON.parse(options.body) : {}
@@ -19,8 +20,8 @@ const fetchImpl = async (url, options = {}) => {
   if (path.endsWith('/api/coach/contests')) return json({ account, contests: [{ id: 7, title: 'VP 7', status: 'ended' }] })
   if (path.endsWith('/api/coach/sync')) return json({
     account: mismatch ? { id: 1, handle: 'A' } : account,
-    submissions: [{ id: 9, contest_id: 7, verdict: 'AC' }], events: [], contests: [],
-    next_cursor: { submission_id: 9, event_id: 0 }, has_more: false,
+    submissions: [{ id: nextPage ? 10 : 9, contest_id: 7, verdict: nextPage ? 'WA' : 'AC' }], events: [], contests: [],
+    next_cursor: { submission_id: nextPage ? 10 : 9, event_id: 0 }, has_more: !nextPage,
   })
   if (path.endsWith('/api/coach/replay/7')) return json({ account, visualization: { team_events: [] } })
   throw new Error(`unexpected ${url}`)
@@ -34,7 +35,16 @@ try {
   await client.finish({ code: 'A' })
   const synced = await client.sync()
   assert.equal(synced.account.id, 1)
+  assert.equal(synced.hasMore, true, 'first page must expose continuation')
+  assert.deepEqual(synced.pageCounts, { submissions: 1, events: 0, contests: 0 })
   assert.equal(JSON.parse(readFileSync(join(root, 'vp-accounts', '1', 'SYNC.json'))).account.id, 1)
+  nextPage = true
+  const secondPage = await client.sync()
+  assert.equal(secondPage.hasMore, false, 'last page must expose completion')
+  assert.deepEqual(secondPage.pageCounts, { submissions: 1, events: 0, contests: 0 }, 'page counts must not include old cached rows')
+  assert.deepEqual(secondPage.submissions.map(item => item.id), [9, 10], 'incremental pages must retain earlier accepted runs')
+  assert.deepEqual(JSON.parse(readFileSync(join(root, 'vp-accounts', '1', 'SYNC.json'))).submissions.map(item => item.id), [9, 10])
+  nextPage = false
   await client.finish({ code: 'B' })
   assert.equal((await client.status()).account.id, 2)
   assert.equal((await client.contests()).contests[0].id, 7)

package/dev/vp-sync-check.mjs

@@ -0,0 +1,122 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+function shape(schema, value) {
+  if (schema.type === 'object') {
+    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 === 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') {
+    assert.ok(Array.isArray(value))
+    if (schema.items) value.forEach(item => shape(schema.items, item))
+  } else if (schema.type === 'integer') assert.ok(Number.isInteger(value))
+  else assert.equal(typeof value, schema.type)
+}
+
+async function fixture(run) {
+  const dir = mkdtempSync(join(tmpdir(), 'coach-vp-sync-'))
+  const previous = { data: process.env.COACH_DATA_DIR, db: process.env.COACH_DB, fetch: globalThis.fetch }
+  const account = { id: 1, handle: 'mock-account', display_name: 'Mock account' }
+  let page = 0
+  let mode = 'normal'
+  const calls = []
+  try {
+    writeFileSync(join(dir, 'MAP.yaml'), 'meta: {version: 1}\nnodes: []\n')
+    process.env.COACH_DATA_DIR = dir
+    process.env.COACH_DB = join(dir, 'unused.db')
+    globalThis.fetch = async url => {
+      const parsed = new URL(url)
+      if (parsed.pathname === '/api/coach/auth/exchange') return json({ access_token: 'test-token', user: account })
+      if (parsed.pathname !== '/api/coach/sync') throw new Error(`unexpected mock route ${parsed.pathname}`)
+      if (mode === 'error') return { ok: false, status: 503, json: async () => ({ detail: 'temporary mock failure' }) }
+      calls.push(Number(parsed.searchParams.get('submission_cursor')))
+      const submissionId = mode === 'duplicate' ? page : ++page
+      const contest = { id: mode === 'invalid' ? 8 : 7, title: 'Mock VP', start_time: mode === 'invalid' ? '2026-02-30T00:00:00Z' : mode === 'naive-utc' ? '2026-10-10 00:00:00' : '2026-10-10T00:00:00Z', duration_min: 300 }
+      return json({ account, contests: [contest], events: [],
+        submissions: [{ id: submissionId, contest_id: contest.id, problem_id: 'A', verdict: 'AC', submitted_at: mode === 'naive-utc' ? '2026-10-10 00:10:00' : '2026-10-10T00:10:00Z' }],
+        next_cursor: { submission_id: submissionId, event_id: 0 }, has_more: page === 1 })
+    }
+    const { apply } = await import(`../index.js?vp-sync-${dir.replace(/\\/g, '/')}`)
+    const registered = new Map()
+    apply({ tools: { register: tool => registered.set(tool.name, tool) }, inject() {}, on() {} })
+    const call = async (name, args = {}) => {
+      const tool = registered.get(name)
+      const result = await tool.execute(args)
+      shape(tool.output.schema, result)
+      return result
+    }
+    assert.equal((await call('coach_vp_connect', { action: 'finish', code: 'test-code' })).ok, true)
+    await run({ call, calls, mode: value => { mode = value } })
+  } finally {
+    globalThis.fetch = previous.fetch
+    for (const [key, value] of [['COACH_DATA_DIR', previous.data], ['COACH_DB', previous.db]]) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+function json(value) { return { ok: true, json: async () => value } }
+
+test('public VP sync exposes two-page continuation and distinguishes page rows from cumulative cache', async () => {
+  await fixture(async ({ call, calls, mode }) => {
+    const first = await call('coach_vp_sync')
+    assert.equal(first.ok, true, first.reject)
+    assert.equal(first.hasMore, true)
+    assert.deepEqual(first.pageCounts, { submissions: 1, events: 0, contests: 1 })
+    const second = await call('coach_vp_sync')
+    assert.equal(second.ok, true, second.reject)
+    assert.equal(second.hasMore, false)
+    assert.deepEqual(second.pageCounts, { submissions: 1, events: 0, contests: 1 })
+    assert.equal(second.submissions.length, 2)
+    assert.deepEqual(calls, [0, 1])
+    assert.equal(second.nextCursor.submission_id, 2)
+    assert.match(second.text, /缓存累计/)
+    assert.doesNotMatch(second.text, /新增训练证据/)
+    mode('duplicate')
+    const repeated = await call('coach_vp_sync')
+    assert.equal(repeated.ok, true, repeated.reject)
+    assert.equal(repeated.submissions.length, 2)
+    assert.deepEqual(repeated.pageCounts, { submissions: 1, events: 0, contests: 1 })
+    assert.match(repeated.text, /缓存累计/)
+    assert.doesNotMatch(repeated.text, /新增训练证据/)
+  })
+})
+
+test('public VP sync propagates training import refusal and network failure with complete output shapes', async () => {
+  await fixture(async ({ call, mode }) => {
+    mode('invalid')
+    const rejected = await call('coach_vp_sync')
+    assert.equal(rejected.ok, false, 'invalid imported date must not be reported as successful sync')
+    assert.match(rejected.reject, /VP 导入被拒绝/)
+    assert.equal(rejected.imported, 0)
+    mode('error')
+    const failed = await call('coach_vp_sync')
+    assert.equal(failed.ok, false)
+    assert.match(failed.reject, /503/)
+    assert.equal(failed.hasMore, false)
+    assert.deepEqual(failed.pageCounts, { submissions: 0, events: 0, contests: 0 })
+    assert.deepEqual(failed.nextCursor, { submission_id: 0, event_id: 0 })
+  })
+})
+
+test('platform UTC timestamps without a timezone become valid ISO evidence', async () => {
+  await fixture(async ({ call, mode }) => {
+    mode('naive-utc')
+    const synced = await call('coach_vp_sync')
+    assert.equal(synced.ok, true, synced.reject)
+    const facts = await call('coach_curriculum', { action: 'assess', evidenceEventIds: ['vp:1:7'] })
+    assert.equal(facts.evidence[0].occurredAt, '2026-10-10T00:10:00.000Z')
+    assert.equal(facts.evidence[0].minutes, 10)
+    const platformStart = new Date('2026-10-10T00:00:00Z')
+    const localDate = `${platformStart.getFullYear()}-${String(platformStart.getMonth() + 1).padStart(2, '0')}-${String(platformStart.getDate()).padStart(2, '0')}`
+    assert.equal(facts.evidence[0].date, localDate)
+  })
+})

package/dev/workspace-migration-check.mjs

@@ -1,11 +1,27 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 
-test('startup migrates legacy personal files out of an active VP account', async () => {
+const target = (contest) => `version: 1\nrevision: 1\nupdated: 2026-10-11T00:51:42.901Z\ncontest: ${contest}\ndate: 2026-10-17\nresult: 保铜争银\nteamMode: team\nweeklyHours: 25\nconstraints: {}\npriorities: []\n`
+let startupCount = 0
+async function startup(root) {
+  const previous = process.env.COACH_DATA_DIR
+  const previousDb = process.env.COACH_DB
+  process.env.COACH_DATA_DIR = root
+  process.env.COACH_DB = join(root, 'unused.db')
+  try { await import(`../index.js?workspace-migration=${Date.now()}-${startupCount++}`) }
+  finally {
+    if (previous === undefined) delete process.env.COACH_DATA_DIR
+    else process.env.COACH_DATA_DIR = previous
+    if (previousDb === undefined) delete process.env.COACH_DB
+    else process.env.COACH_DB = previousDb
+  }
+}
+function fixture(t) {
   const root = mkdtempSync(join(tmpdir(), 'acmer-coach-workspace-'))
+  t.after(() => rmSync(root, { recursive: true, force: true }))
   const accountDir = join(root, 'vp-accounts', '6')
   mkdirSync(accountDir, { recursive: true })
   writeFileSync(join(root, 'VP_ACCOUNTS.json'), JSON.stringify({
@@ -13,22 +29,78 @@ test('startup migrates legacy personal files out of an active VP account', async
     activeAccountId: 6,
     accounts: { 6: { account: { id: 6, handle: 'Mianiii', display_name: 'Mianiii' }, baseUrl: 'https://example.test' } },
   }))
-  writeFileSync(join(root, 'TARGET.yaml'), 'version: 1\nrevision: 1\nupdated: 2026-10-10T20:55:57.385Z\ncontest: 旧目标\ndate: 2026-10-17\nresult: 保铜争银\nteamMode: team\nweeklyHours: 25\nconstraints: {}\npriorities: []\n')
-  writeFileSync(join(accountDir, 'TARGET.yaml'), 'version: 1\nrevision: 1\nupdated: 2026-10-11T00:51:42.901Z\ncontest: 西安区域赛\ndate: 2026-10-17\nresult: 保铜争银\nteamMode: team\nweeklyHours: 25\nconstraints: {}\npriorities: []\n')
-  const oldTargetTime = new Date('2026-10-10T20:55:57.385Z')
-  const newTargetTime = new Date('2026-10-11T00:51:42.901Z')
-  const { utimesSync } = await import('node:fs')
-  utimesSync(join(root, 'TARGET.yaml'), oldTargetTime, oldTargetTime)
-  utimesSync(join(accountDir, 'TARGET.yaml'), newTargetTime, newTargetTime)
-  process.env.COACH_DATA_DIR = root
-  try {
-    await import(`../index.js?workspace-migration=${Date.now()}`)
-    assert.equal(existsSync(join(root, 'TARGET.yaml')), true)
-    assert.equal(existsSync(join(accountDir, 'TARGET.yaml')), true)
-    assert.equal(existsSync(join(root, 'TARGET.yaml.pre-vp-account-6')), true)
-    assert.match((await import('node:fs')).readFileSync(join(root, 'TARGET.yaml'), 'utf8'), /contest: 西安区域赛/)
-  } finally {
-    delete process.env.COACH_DATA_DIR
-    rmSync(root, { recursive: true, force: true })
-  }
+  writeFileSync(join(accountDir, 'TARGET.yaml'), target('账号旧目标'))
+  return { root, accountDir, main: join(root, 'TARGET.yaml'), source: join(accountDir, 'TARGET.yaml'), marker: join(accountDir, 'PERSONAL_MIGRATION.json') }
+}
+
+test('startup fills missing personal files while retaining their account originals', async (t) => {
+  const f = fixture(t)
+  await startup(f.root)
+  assert.equal(readFileSync(f.main, 'utf8'), target('账号旧目标'))
+  assert.equal(readFileSync(f.source, 'utf8'), target('账号旧目标'))
+  assert.equal(existsSync(f.marker), true)
+})
+
+test('first migration preserves an existing global ledger even when the account mtime is newer', async (t) => {
+  const f = fixture(t)
+  writeFileSync(f.main, target('合法个人目标'))
+  const older = new Date('2026-10-10T12:00:00Z'), newer = new Date('2026-10-12T12:00:00Z')
+  utimesSync(f.main, older, older); utimesSync(f.source, newer, newer)
+  await startup(f.root)
+  assert.equal(readFileSync(f.main, 'utf8'), target('合法个人目标'))
+  assert.equal(readFileSync(`${f.main}.from-vp-account-6`, 'utf8'), target('账号旧目标'))
+  assert.equal(readFileSync(f.source, 'utf8'), target('账号旧目标'))
+})
+
+test('repeated startup never replaces edited global data after old account files change', async (t) => {
+  const f = fixture(t)
+  await startup(f.root)
+  const marker = existsSync(f.marker) ? readFileSync(f.marker, 'utf8') : ''
+  writeFileSync(f.main, target('迁移后合法修订'))
+  writeFileSync(f.source, target('旧账号后来变化'))
+  const newer = new Date('2026-10-12T12:00:00Z')
+  utimesSync(f.source, newer, newer)
+  await startup(f.root)
+  assert.equal(readFileSync(f.main, 'utf8'), target('迁移后合法修订'))
+  assert.equal(readFileSync(f.marker, 'utf8'), marker)
+})
+
+test('a newer global ledger is also finalized once rather than reconsidered on later account updates', async (t) => {
+  const f = fixture(t)
+  writeFileSync(f.main, target('已经较新的个人目标'))
+  const old = new Date('2026-10-10T12:00:00Z')
+  utimesSync(f.source, old, old)
+  await startup(f.root)
+  writeFileSync(f.source, target('再次变新的旧账号目标'))
+  const newer = new Date('2026-10-13T12:00:00Z')
+  utimesSync(f.source, newer, newer)
+  await startup(f.root)
+  assert.equal(readFileSync(f.main, 'utf8'), target('已经较新的个人目标'))
+  assert.equal(readFileSync(`${f.main}.from-vp-account-6`, 'utf8'), target('账号旧目标'))
+})
+
+test('migration helper preserves existing conflict backups and safely finalizes unmarked accounts', async (t) => {
+  const { migratePersonalWorkspace } = await import('../lib/workspace-migration.js')
+  const f = fixture(t)
+  writeFileSync(f.main, target('合法个人目标'))
+  const backup = `${f.main}.from-vp-account-6`
+  writeFileSync(backup, target('更早的冲突副本'))
+  assert.deepEqual(migratePersonalWorkspace(f.root, 6), [])
+  assert.equal(readFileSync(f.main, 'utf8'), target('合法个人目标'))
+  assert.equal(readFileSync(backup, 'utf8'), target('更早的冲突副本'))
+  assert.equal(readFileSync(f.source, 'utf8'), target('账号旧目标'))
+  const marker = JSON.parse(readFileSync(f.marker, 'utf8'))
+  assert.equal(marker.files['TARGET.yaml'], 'conflict-preserved')
+  writeFileSync(join(f.accountDir, 'PROGRESS.yaml'), 'version: 1\nnodes: {}\n')
+  assert.deepEqual(migratePersonalWorkspace(f.root, 6), [])
+  assert.equal(existsSync(join(f.root, 'PROGRESS.yaml')), false)
+})
+
+test('migration helper validates account paths and skips absent accounts', async (t) => {
+  const { migratePersonalWorkspace } = await import('../lib/workspace-migration.js')
+  const f = fixture(t)
+  for (const accountId of ['../other', '-1', '6/subdir', true]) assert.throws(() => migratePersonalWorkspace(f.root, accountId), /账号 id/)
+  assert.deepEqual(migratePersonalWorkspace(f.root, 0), [])
+  assert.deepEqual(migratePersonalWorkspace(f.root, 7), [])
+  assert.equal(existsSync(f.marker), false)
 })

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/setup.js lib/curriculum.js lib/curriculum-evidence.js lib/curriculum-planning.js lib/strategy.js assets/knowledge/COMPETENCIES.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 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
@@ -93,7 +93,7 @@ echo '· 全部副本哈希一致'
 # 病因已修（那几节改跑临时副本），这条是**兜底闸门**：自检跑完比一次指纹，
 # 一变就报错退出。这种事不靠自觉，靠闸门。
 LEDGER_DIR="$DSH_HOME_BASH/knowledge"
-LEDGERS='PROGRESS.yaml SCHEDULE.yaml CURRICULUM.yaml'
+LEDGERS='PROGRESS.yaml SCHEDULE.yaml CURRICULUM.yaml TARGET.yaml VP_EVENTS.yaml'
 ledger_fp() { (cd "$LEDGER_DIR" 2>/dev/null && sha256sum $LEDGERS 2>/dev/null || true); }
 LEDGER_BEFORE=$(ledger_fp)
 
@@ -118,6 +118,11 @@ echo '── 编排证据验收（目录、引用、事件身份与重复记录
 node --test "$SRC_BASH/dev/curriculum-evidence-check.mjs" || EVIDENCE_RC=$?
 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/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)
 if [ "$LEDGER_BEFORE" != "$LEDGER_AFTER" ]; then
   echo
@@ -149,4 +154,4 @@ if [ -n "$DSH_LIVE" ]; then
   echo '  要验「工具挂进教练的清单里」，得先重启 dsh。'
 fi
 
-exit $(( VERIFY_RC + SHAPE_RC + CURRICULUM_RC + EVIDENCE_RC ))
+exit $(( VERIFY_RC + SHAPE_RC + CURRICULUM_RC + EVIDENCE_RC + CONTRACT_RC ))

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

@@ -0,0 +1,79 @@
+# 比赛依据与节点教学卡
+
+训练路线先回答“目标比赛里要完成什么任务、本人被什么障碍挡住”，再选知识点。Rating 可以帮助找题池，不能证明某项能力已掌握，也不能单独决定下一阶段。
+
+## 三种信息分别负责什么
+
+| 资料 | 用途 | 不能据此声称什么 |
+| --- | --- | --- |
+| `COMPETENCIES.yaml` | 九项通用比赛能力；关联精确 MAP 节点 | 它们不是官方考纲，教学验收阈值不是比赛规则 |
+| `NODE_SCOPES.yaml` | 十四个常用节点的识别条件、证明问题、适用范围、反例、延伸与迁移动作 | 卡片不是完整教材，完成一张卡不等于永久掌握 |
+| `CONTEST_PROFILES.yaml` | 有限真题样本支持的诊断任务与取舍提示 | 不代表专题频率、奖牌线或未来题目预测 |
+
+`NODE_SCOPES` 的 `id` 必须与 MAP 节点完全一致。`recognition` 用于读题识别；`proofQuestions` 用于确认学生能解释；`notFor` 用于主动暴露边界；`transferProblems` 是练习任务描述，不是假造的题目编号；`exitEvidence` 是教学验收建议。来源证明技术条件，练习设计由插件负责。
+
+三个 profile 当前均是 `provisional`：`regional-diagnostic`、`wf-extension`、`xian-pending`。这个状态表示可用于带限制的诊断，不能输出“已掌握本比赛考纲”。`reviewed` 也只能表示记录的样本已人工核验，不能去掉样本限制。
+
+## 本轮采样范围
+
+区域赛诊断取自 [NWERC 2024 官方题面](https://2024.nwerc.eu/main/problem-set.pdf) 的 A、D、E、F、K、L，与[官方解题](https://2024.nwerc.eu/main/solutions.pdf)对应章节核对。它们用来检查规则实现、状态设计、重复变换与多模型组合；没有采样全部题目，也没有跨年份计数。NWERC 与中国区域赛的差异保留为限制，不推导西安趋势。
+
+WF 扩展诊断只读了 [2024 World Finals 官方题面](https://icpc.global/worldfinals/problems/2024-ICPC-World-Finals/icpc2024.pdf) 的 B、I、L，能力映射是教学推断。没有核验这些题的完整官方题解。交互程序的刷新与协议要求另依据[官方交互评测说明](https://docs.icpc.global/wp-content/uploads/2024/08/2024-JudgingNotes.pdf)。
+
+[QOJ 西安目录](https://qoj.ac/category/87)只用于确认历年原题入口。当前没有完成原题、主办方题解、榜单的逐题核验，所以西安配置保持待采样，不生成专题权重。采用 [NCNA 公布的区域赛规则](https://nc.na.icpc.global/rules/)作通用赛制背景，也不能把它视作西安本届现场规则。
+
+## 小鲸怎样使用
+
+1. 先确认目标、剩余时间和个人/团队训练场景。选择 profile 时解释样本范围，不能从比赛名字推断考纲。
+2. 用 VP 可观察事实形成诊断假设。失败原因经代码或复盘确认后，才称为短板；成功记录保留为能力基线。
+3. 挑一个能完成验收的动作，说明它对应什么比赛任务、为何现在练、预计投入和改变安排的条件。
+4. 讲知识点时先要求识别和证明，接着给边界反例，再找未标注专题的新题与隔天复测。来源跟随卡片一起展示。
+
+用户临时问新知识点时可以回答。回答不自动成为主线任务，也不自动改变游标或阶段。
+
+## 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/)
+
+SCC 卡提供中心与三个叶子组成的双向星形图：四个点互达，但简单路径最多访问三个点。收集每个点必须保持简单路径时，不能把整个分量点权直接相加。[技术依据](https://oi-wiki.org/graph/scc/)
+
+线段树卡对比 `[0,4]` 与 `[2,2]`：两段长度和区间和相同，各项与 2 取最小值后的区间和分别是 2 和 4。只维护和及长度不足以支持此更新，需要补信息或更换算法。[技术依据](https://oi-wiki.org/ds/seg/)
+
+DP 卡要求证明状态足够。同一个位置如果对应不同剩余资源，而后续可选动作依赖资源，就不能直接合并这两段历史；这是状态设计问题，增加模板数量不能解决。[技术依据](https://oi-wiki.org/dp/basic/)
+
+## 验证与范围
+
+`node --test dev/catalog-check.mjs` 检查唯一 ID、真实 MAP 节点、能力映射、每张卡所需字段、公开来源链接、profile 状态与采样限制。该测试不向外网请求，也不读写用户训练账本。
+
+集成回归已验证 `coach_scope` 返回节点卡、profile 可被目标选中且保留限制，以及两场测量从公开导入到阶段推进的闭环。目录校验不等于小鲸对话效果评测，也没有验证具体迁移练习的完整 AC 程序。