dsh-learn-everything — DSH 费曼学习法插件

状态：M4 发布门禁（README Model Experience、组合 smoke、验收矩阵、GIF）。 设计决策与验收标准见 SPEC.md；验收矩阵见 docs/ACCEPTANCE.md。

一句话定位：让 DeepSeek Harness 变成"边学边做"的环境——开启学习模式后，模型按费曼学习法讲解概念、出卡片题请你复述、针对缺口重新讲解，教学内容以富 HTML 卡片可视化呈现。

核心形态

• 会话级 /learn on|off 切换；开启后注入费曼教学引导（learning:policy prompt 段），关闭后完全恢复默认行为。
• 模型经 teach 工具产出结构化 Lesson（标题、一句话总结、小节：正文/代码/mermaid 图/类比、可选 raw HTML），Web 客户端经 tool.call.toolview keyed 视图渲染为富 HTML 卡片：代码经 shell shiki 高亮（语言横幅 + 复制），mermaid 源渲染成 SVG 图（pending/error 回落源码块）。
• 答题复用现有 ask_user_question（卡片选项由 ui-user-questions 呈现）；模型在下一步自行判定对错并讲解。
• 模式状态是 log-only learning/mode session event：resume/fork/compaction 从日志折叠恢复，无 live mirror。
• 每次会话独立，无跨会话长期记忆。
• 零 mainline core 改动：不加 card kind、不改 agent-loop、不加新事件族（Lesson 卡片直接消费既有 tool/call 日志）。

动机

• 用户在工作会话里学新概念时，往往只拿到一段答案，没有结构化的讲解、练习和反馈。
• 费曼学习法（讲清楚 → 讲回来 → 找缺口 → 简化）是经过验证的学习闭环，适合模型驱动。
• DSH 已有全部所需 seam（prompt 段、工具、命令、logged state、keyed 工具视图），插件可零 core 改动落地。

里程碑

• M1 脚手架：仓库结构、独立构建链、/learn 状态机、learning:policy 段、teach 工具、tool.call.toolview 卡片、单元测试。
• M2 教学闭环：费曼引导文案调优（讲解→复述→判定→回讲四步，含至多两次提问的收尾约束）；key-gated 真实模型 e2e（pnpm run test:e2e）走通一轮并断言闭环。
• M3 富 HTML 打磨：keyless assembled Web 快照测试（Playwright + aria golden，pnpm run test:web）；卡片视觉打磨；mermaid 渲染成图（mermaid.js 客户端渲染，惰性单例 + 串行化）；代码高亮（复用 shell shiki CodeBlock，含语言横幅与复制按钮）。
• M4 发布门禁：README Model Experience（canonical 格式 + verbatim 引导 + token/KV Cache 逐条）、Known Limitations 对齐 SPEC §10、keyless 组合 smoke（Loader 子进程装配，pnpm run test:smoke）、验收矩阵（docs/ACCEPTANCE.md）、GIF（真实服务 + 真实模型）。

本地开发

仓库不从 npm 解析或发布私有 DSH 包。先准备已构建的 DSH 源码目录（本机即 mainline checkout），再安装公开依赖并建立本地链接：

DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm install
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run dsh:link:check   # 链接就绪自检
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run build            # tsc + tsdown + esbuild client
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm test                 # vitest 单元测试
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:smoke       # keyless 组合 smoke（Loader 子进程装配）
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:web         # keyless assembled Web 快照（Playwright + aria golden）
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:e2e         # 真实模型 e2e（需 DEEPSEEK_API_KEY，缺省跳过）

DSH_SOURCE_DIR 也可省略：脚本回退到 ~/.dsh/source/current（若存在）。e2e 使用真实 DeepSeek 适配器并模拟用户答题；key 从进程环境读取，缺省时回退到 $DSH_HOME/.env（与 CLI 的 credential 平面一致）。e2e 依赖的 @deepseek-ai/dsh-agent-loop、dsh-llm-deepseek、dsh-user-questions、dsh-tool-ask-user、dsh-agent-loop-testkit 与运行期 peer 一样从 DSH 源码树链接，不经 npm 解析。安装到运行中的 DSH：把本仓库 cordis.patch.yml 的插件行并入 profile 补丁，并在 web bundle 声明 client 行（见 SPEC.md）。

仓库结构

cordis.patch.yml        # 插件行（host 全局行 + 配对 client bundle）
src/
  index.ts              # host 插件入口（name/inject/Config/apply）
  controller.ts         # LearningModeController：状态机 + /learn + prompt 段 + teach
  config.ts             # LearningConfig 校验（默认费曼引导）
  guidance.ts           # 内置费曼四步引导文案（单一事实来源）
  fold.ts               # foldLearningMode（日志折叠）
  teach.ts              # teach 工具注册
  types.ts              # Lesson 类型（host/client 共享）
  constants.ts          # TEACH_TOOL wire 名（host/client 共享）
  client/
    index.ts            # browser 插件入口：注册 toolview + 注入样式
    LessonToolView.tsx  # 富 HTML 卡片（复用 shell shiki CodeBlock）
    Diagram.tsx         # mermaid 图组件（SVG 渲染，pending/error 回落源码块）
    mermaid.ts          # 惰性 mermaid 单例 + 串行化渲染队列
    project.ts          # args → Lesson 纯函数投影（replay 安全）
    sanitize.ts         # DOMPurify 净化（contentHtml 逃生舱）
    styles.ts           # 卡片样式（--dsw-* 变量）
scripts/                # clean / setup-dsh-links / build-client
tests/                  # vitest 单元测试 + 组合 smoke 夹具 + Web 快照
docs/ACCEPTANCE.md      # 验收矩阵（M1–M4 逐项证据）
SPEC.md                 # 设计决策与验收标准（单一事实来源）

Model Experience

learning:policy prompt section — conditional

What the model sees

While learning mode is active, the learning:policy system-prompt section (order 50) renders the shipped Feynman guidance below; while inactive it renders empty and is dropped from the assembled prompt, so the model sees nothing from this package. The section text is the deployment-configurable Config.section, defaulting to the guidance quoted verbatim from src/guidance.ts.

src/guidance.ts — shipped Feynman guidance

你在学习模式（Learning Mode）中。当用户提问、或开始学习一个新概念时，按费曼学习法四步教学：

1. 讲解（Explain）：调用 teach 工具产出一张结构化教学卡片（title / summary / sections），讲清概念：定义与核心机制、一个最小代码示例（code）、一个生活化类比（analogy）、必要时配一张 mermaid 图（diagram）。
2. 复述（Teach-back）：讲解结束后，调用 ask_user_question 请用户用自己的话复述这个概念。给 2-4 个选项（覆盖常见的模糊或部分理解，而不是"懂了/不懂"）+ 自定义输入（Other），并在问题里明确请用户讲出关键机制。
3. 判定（Judge）：用户回答后，对照概念逐点判定并明确说出：哪些说对了、哪些说错了、哪些漏掉了。不要含糊地说"基本正确"。
4. 回讲（Re-explain）：存在缺口时，调用 teach 再产出一张只针对缺口的小卡片（1-2 个小节），不重发整张卡片；之后最多再用 ask_user_question 确认一次。没有缺口时，用一句话总结（summary）收尾，补一个更简单的类比，结束教学。

约束：
- 一个概念只做一轮：初始讲解只调用一次 teach；回讲只补缺口，可再调用一次 teach，不要重复已讲对的部分。
- 不要为凑足四步而循环提问：复述正确就收尾；一次教学最多调用两次 ask_user_question。
- 用户明确表示不需要学习、或当前任务与学习无关时，直接完成任务，不要强行教学。
- 始终使用用户正在使用的语言教学。

Token effect

Conditional. When learning mode is inactive the section contributes zero tokens; when active it adds the full guidance block to every request's system prompt.

KV Cache effect

While active, the guidance is a stable repeated prefix — identical text on every request, so the provider can reuse the cached prefix. A learning/mode flip inserts or removes the large Chinese block at the section boundary, invalidating reuse of that prefix (and any later sections) from the flip onward. The package does not otherwise change earlier request tokens.

teach tool schema — always registered, execution gated on learning mode

What the model sees

The teach tool is registered unconditionally, so its schema and description are in the request tool catalog on every request regardless of mode; entering or leaving learning mode changes only the prompt section, never the catalog. Calling teach while inactive fails with teach is only available in learning mode (run /learn). The description and parameter schema below are defined in src/teach.ts.

teach tool description

Use only in learning mode. Deliver one structured, visually rendered teaching card for the concept you are explaining: a short title, a one-sentence summary, and sections with prose plus optional code, mermaid diagram, and analogy.

field	type	required	meaning
title	string	✓	Short title of the concept being taught.
summary	string	✓	One-sentence plain-language summary of the concept.
sections	array	✓	Teaching sections of the lesson, in order; non-empty is enforced at execution.
sections[].heading	string	✓	Heading of this section.
sections[].prose	string	✓	Explanation prose for this section.
sections[].code	object		Optional { language, text } minimal code example.
sections[].diagram	object		Optional { type: 'mermaid', source } diagram source.
sections[].analogy	string		Optional plain-language analogy for this section.
contentHtml	string		Optional raw HTML payload, sanitized client-side; prefer the structured fields.

Result: { ok: true }; execution outside learning mode fails.

Token effect

Constant. The tool schema and description occupy the catalog on every request whether or not learning mode is active; there is no mode-conditional change to this entry.

KV Cache effect

Stable. The catalog's tool-schema portion is unchanged by a mode flip and does not invalidate an otherwise-reusable prefix.

teach output narration and /learn mode notices — auxiliary user-role text

What the model sees

After each teach call the tool result renders one fixed continuation line, and a /learn switch injects a user-role plugin notice when the last logged header described the other mode.

• teach result: Lesson delivered. Continue the Feynman loop: ask the user to teach the concept back, or answer their follow-up questions.
• /learn on notice: The user switched this session to learning mode.
• /learn off notice: The user switched this session back to the default mode.

Token effect

Conditional. These texts appear only on the events that produce them — a teach execution or a mode switch — and add nothing otherwise.

KV Cache effect

Append-only. The teach result is appended as tool/result content and the notice as a user message; neither replaces earlier request tokens.

Known Limitations and Deferred Work

• 判定为软约束 — the model can skip the teach-back or judgment step; v1 enforces the loop only through the learning:policy guidance, not a hard mechanism. A dedicated quiz tool is the deferred path to a hard constraint (SPEC D3).
• mermaid 体积 — mermaid.js is bundled whole into the client bundle (about 3.3MB raw / 900KB gzip) for offline, deterministic rendering under the plugin's single-file bundle route; import() only defers module execution, so download and parse cost recur on every page load (SPEC D6).
• 长内容折叠未做 — an overlong lesson renders fully expanded (v1 accepts this).
• 卡片无结果态 — the toolview consumes only the tool/call arguments, so a failed tool/result is not reflected on the card (a failed teach is unlikely, and the generic card is the fallback).
• 无跨会话记忆 — each session is independent; mastery and current learning topic are not persisted (D5).
• 无 mode 投影单元 — the client does not read learning-mode state; a future mode indicator would go through sessionProjections.
• 无 i18n 命名空间 — card labels are fixed Chinese prose; localization is deferred.
• /learn 依赖 ctx.commands — in a headless composition without a command registry /learn is unavailable; the prompt section and teach tool still work, and ctx.learningMode.set remains a non-command switch path.

许可

BSD-3-Clause。