# 改动记录

这个文件记**用户看得见的变化**：面板上多了什么、少了什么，agent 那半多了哪个工具或参数。
内部的实现笔记（哪条坑怎么踩的、为什么这么写）在 [`DEV.md`](DEV.md) 与 [`AGENTS.md`](AGENTS.md) 里。

写法照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号照 [语义化版本](https://semver.org/lang/zh-CN/)。
`0.x` 期间 MINOR 也可能有破坏性改动，破坏性的那些会单独标出来。

## [0.1.0] - 2026-10-02

第一个版本。从「对话里记进度」长成了一个带面板的插件，面板本身又长成了八页。

### 面板（`/study`）

- 八页：主页（路口）、今日任务、知识地图、学习（资料图谱）、档案、资料、工具、对话。
  老网址 `/study/ability` 仍然能开，落到知识地图页。
- 主页只剩一张「教练的指引」——任务是活儿，在各自那一页里。
- 今日任务：抬头用复盘图那套版式（眉标 + 大字标题 + 状态块 + 量尺），一条任务只留「打开 / 改 / 删除」。
  今日复盘图只在这一页，图能单独下载成 SVG。
- 知识地图是「关卡面」：大类 / 模块 / 最小单元三层，逐层展开，**画布能按住拖着挪，Ctrl／⌘ + 滚轮才缩放**，
  普通滚轮照旧滚页面。
- 每个单元两颗按钮：**看课**自动落到那一讲的文件上（按资料图谱三档匹配，落不实就退成「这一部分里 N 个视频」的文件夹并说明），
  **做题**把一条请求递给对话里的教练，由教练按学生档案挑材料页码与题号。
- 四层掌握度：大类头、模块头一条四段色带，单元那一行四格小灯；档案页另有一张整体饼图。
- 档案页：综合学生档案（总体评价、四层掌握度、七天节奏、学生画像、基本工具、错题）+ 学习目标 + 学生画像。
  **学生画像只在这一页**。
- 资料页：材料登记表、导入、AI 出题入口；资料图谱按材料自己的目录摊三层，每层右边都是能直接打开的链接。
- 工具页：番茄钟、记忆卡（艾宾浩斯那套间隔）、清单。
- 对话页：整页一个聊天窗口，能选 DSH 里的哪个学习会话；表情包直接读盘上的图库；
  SSE 广播让面板在 DSH 那半边改完数据后立刻刷新；右下角那颗悬浮窗能拖、能缩成图标。
- 体检卡：把「现在该动哪儿」分三档（挡路的 / 该修的 / 顺手能做的），每条都说清为什么、配一颗跳转按钮。
- **换页会把那一页的数据补上**，不用按 F5（修「一开始进去读取不到数据、刷新一下才正常」）。

### agent 那半

- 21 个 `study_*` 工具：目标、材料、材料分析（含**资料图谱** `tree`）、知识地图、掌握度证据与错题本、
  今日任务、记忆卡、番茄钟、清单、学生画像、总体能力判词、面板指引、面板留言、文件目录。
- 掌握度六档，一次只推进一档；`能独立做` 以上要有证据才让升档。
- 教练的规矩收在 skill 里（`skills/study-coach/SKILL.md`）：布置作业之前先过「他在哪儿 / 他到底需要什么 /
  哪份材料的哪一段派什么用场」三关；收完作业、听完课要两份档案一起更新。
- 记录学生画像时**必须挂证据**（证据 id，或者「哪个单元的哪次」），挂不上的会被体检卡挑出来。

### 其他

- `lib/client.js`：设置 → 学习教练那一页（面板入口、快捷键、数据目录、当前档案）。
- 数据落盘：`registry.json` + `profiles/<id>/*.json`，写入是临时文件改名，坏了不留半截。
- `node --test` 340 条用例（本机全绿）；`node scripts/preview.mjs` 不用 DSH 就能把面板起在 19390 看。
- GitHub Actions 跑 `ubuntu-latest` + node 22 / 24：`node scripts/ci-test.mjs` 跑测试并把**失败用例写成 GitHub 注解**
  （Actions 的原始日志不登录看不到，注解是匿名也能读的那份）；宿主包 `@deepseek-ai/*` 没装上时跳过测试并给一条
  warning，不把「环境缺包」红成「用例失败」。

### 修掉的问题

- 体检卡误报「学习目标还缺 3 项」：它读的是平铺的 `profile.outcome` / `deadline` / `minutesPerDay`，
  而目标其实存在 `profile.goal` 里——目标填全了也会被报缺三项。
- 材料登记过、但盘上已经找不到（移动硬盘没插、网盘没挂）时，`/study/file` 回的是 404，
  而面板探活正是拿 404 判「服务端还是旧代码」的，于是它举着红条让人去重启 DSH。现在这种情况回 **410**
  并说清「登记过、盘上没了」；没登记过的路径仍然是 404。
- 同一毫秒里连着登记两份材料会撞 id，而删除是按 id 过滤的——删一份会把另一份一起删掉
  （批量登记一个文件夹、脚本灌数据时最容易撞上）。发号改成先看已有哪些 id，撞了就往后挪。

### 已知问题

- 窄屏（约 420px）下整页有横向溢出，体检卡右端那颗按钮会被切在视口外。
- 学生画像里引的证据失效时会报出来，但**不会自动修**——得让教练核一下（这是有意的：它宁可吵一句，
  也不许悄悄改掉一条判断的出处）。

[0.1.0]: https://github.com/Ame-Choo/dsh-study-coach/releases/tag/v0.1.0