cendaifeng/dsh-learn-everything

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

dsh-learn-everything banner

状态：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 改动落地。

里程碑

- [x] M1 脚手架：仓库结构、独立构建链、/learn 状态机、learning:policy 段、teach 工具、tool.call.toolview 卡片、单元测试。
- [x] M2 教学闭环：费曼引导文案调优（讲解→复述→判定→回讲四步，含至多两次提问的收尾约束）；key-gated 真实模型 e2e（pnpm run test:e2e）走通一轮并断言闭环。
- [x] M3 富 HTML 打磨：keyless assembled Web 快照测试（Playwright + aria golden，pnpm run test:web）；卡片视觉打磨；mermaid 渲染成图（mermaid.js 客户端渲染，惰性单例 + 串行化）；代码高亮（复用 shell shiki CodeBlock，含语言横幅与复制按钮）。
- [x] 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                 # 设计决策与验收标准（单一事实来源）

模型体验

learning:policy prompt 段 — 条件性

模型看到的内容

当学习模式处于激活状态时，learning:policy 系统提示段（顺序 50）会渲染下方随包附带的费曼引导；当处于非激活状态时，它渲染为空并从组装后的提示中移除，因此模型不会从本包看到任何内容。该段文本是可由部署配置的 Config.section，默认值为从 src/guidance.ts 逐字引用的引导文案。

src/guidance.ts — 随包附带的费曼引导

你在学习模式（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 影响

条件性。当学习模式处于非激活状态时，该段贡献零 token；当处于激活状态时，它会把整个引导块添加到每个请求的系统提示中。

KV Cache 影响

激活期间，引导是一个稳定的重复前缀——每个请求的文本完全相同，因此提供方可以复用缓存的前缀。一次 learning/mode 翻转会在段边界处插入或移除这个大型中文块，从而使该前缀（以及任何后续段）从翻转点起无法复用。除此之外，本包不会改变更早的请求 token。

teach 工具 schema — 始终注册，执行受学习模式门控

模型看到的内容
teach 工具是无条件注册的，因此无论处于何种模式，其 schema 和描述都会出现在每次请求的工具目录中；进入或离开学习模式只会改变提示词部分，而不会改变目录。在非学习模式下调用 teach 会失败，并提示 teach is only available in learning mode (run /learn)。下面的描述和参数 schema 定义在 src/teach.ts 中。

teach 工具描述

仅在处于学习模式时使用。为你正在讲解的概念提供一张结构化、可视化渲染的教学卡片：一个简短标题、一句摘要，以及包含正文和可选代码、mermaid 图表与类比的部分。

| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
| title | string | ✓ | 正在教授的概念的简短标题。 |
| summary | string | ✓ | 对该概念的一句话通俗摘要。 |
| sections | array | ✓ | 课程的教学部分，按顺序排列；执行时强制要求非空。 |
| sections[].heading | string | ✓ | 本部分的标题。 |
| sections[].prose | string | ✓ | 本部分的解释性正文。 |
| sections[].code | object | | 可选的 { language, text } 最小代码示例。 |
| sections[].diagram | object | | 可选的 { type: 'mermaid', source } 图表源。 |
| sections[].analogy | string | | 本部分可选的通俗类比。 |
| contentHtml | string | | 可选的原始 HTML 载荷，在客户端进行清理；优先使用结构化字段。 |

结果：{ ok: true }；在学习模式之外执行会失败。

Token 影响

恒定。无论学习模式是否处于激活状态，工具 schema 和描述都会在每次请求中占用目录；此条目没有随模式变化的条件性更改。

KV 缓存影响

稳定。目录中的工具 schema 部分不会因模式切换而改变，也不会使原本可复用的前缀失效。

teach 输出叙述与 /learn 模式通知 — 辅助用户角色文本

模型看到的内容

每次 teach 调用后，工具结果会渲染一行固定的后续提示；当最后记录的头部描述的是另一种模式时，/learn 切换会注入一条用户角色的插件通知。

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

Token 影响

条件性。这些文本只会出现在产生它们的事件中——一次 teach 执行或一次模式切换——在其他情况下不会增加任何内容。

KV 缓存影响

仅追加。teach 结果会作为 tool/result 内容追加，通知会作为用户消息追加；二者都不会替换先前的请求 token。

已知限制与后续工作
- 判定为软约束 — 模型可以跳过复述或判断步骤；v1 仅通过 learning:policy 指导来强制执行循环，而非硬性机制。专用测验工具是通向硬约束的延迟路径（SPEC D3）。
- mermaid 体积 — mermaid.js 被整体打包进客户端 bundle（约 3.3MB 原始大小 / 900KB gzip），以便在插件的单文件 bundle 路由下实现离线、确定性渲染；import() 仅推迟模块执行，因此下载和解析成本在每次页面加载时都会重复产生（SPEC D6）。
- 长内容折叠未做 — 过长的课程会完全展开渲染（v1 接受此行为）。
- 卡片无结果态 — toolview 仅消费 tool/call 参数，因此失败的 tool/result 不会反映在卡片上（teach 失败不太可能发生，且通用卡片是回退方案）。
- 无跨会话记忆 — 每个会话相互独立；掌握程度和当前学习主题不会被持久化（D5）。
- 无 mode 投影单元 — 客户端不读取学习模式状态；未来的模式指示器将通过 sessionProjections 实现。
- 无 i18n 命名空间 — 卡片标签为固定中文文案；本地化被推迟。
- /learn 依赖 ctx.commands — 在没有命令注册表的无头组合中，/learn 不可用；提示词部分和 teach 工具仍然可用，且 ctx.learningMode.set 仍是非命令切换路径。

许可

BSD-3-Clause。