学习中心 ZBC-QRLA/dsh-learning-hub

dsh-learning-hub

面向 DeepSeek Harness（DSH）的本地优先学习中心。

它把 _learner 目录里的普通 Markdown/JSON 文件变成：

- 课程 → 概念的分支树；
- 前置关系/关联关系的概念图；
- 掌握度、有证据支撑的进度，以及 1/3/7/14 天复习；
- 供 DSH 智能体使用的 learning_hub 工具；
- 带记录表单的三栏仪表盘，体积很小。

没有数据库，没有 CDN，没有遥测，也不依赖云服务。数据留在你的 _learner 文件夹里，可以读取、做 diff、备份，也可以手动编辑。

状态：0.1.1，早期版本。数据 schema 和工具动作可能还会变。见 ROADMAP。

更新日志

0.1.1 — 2026-10-27

- 仪表盘下钻：点击 KPI 卡片、掌握度分桶、堆叠条或头部统计，在原生对话框里查看数字背后的概念。
- 拍照发给 DSH：记录表单可以附加照片，在浏览器里压缩，再通过同源 RPC 发给选定的 DSH 会话。
- 一键登录 DSH：GET /learning-hub/auth 走 DSH 的浏览器认证并重定向，设置 HttpOnly cookie；之后面板直接加载 session/list 和 session/prompt，不用手动处理 token。
- seed/真实数据混合模式：seed:true 的示例行保持严格校验；真实的 record 行使用 seed:false + 会话 id + 非占位证据。
- 会话与复习同步：record 会创建或复用 sessions.jsonl 中的一行，并在每次概念更新时同步对应的 reviews.json 条目（due、mastery、interval_days、status、last_reviewed）。
- 更严格的证据校验：证据为空，或为 seed: / 待补充 / 示例: 占位符，一律在写入前拒绝。
- 测试：34 个插件测试 + 523 项面板自检。

0.1.0 — 2026-10-26

- 首次开源发布：learning_hub 工具、分支/概念图、仪表盘、记录、间隔复习、本地 HTTP API、演示用 _learner。
- 测试：23 个插件测试 + 412 项面板自检。

功能

| 分支树 | 进行中和计划中的课程，每门课带概念和下一步 |
| 概念图 | 前置边、关联边、掌握度配色、点击查看 |
| 证据优先 | mastery 只在有记录时变化；不会悄悄「我觉得你懂了」就升级 |
| 记录 | study / practice / exam / review / misconception |
| 复习 | 1 / 3 / 7 / 14 天排期；review 返回到期的概念 |
| 路由 | cwd、关键词、分支名和概念名 → 主/次分支 + 置信度 |
| 仪表盘 | 可折叠侧栏、桌面/平板/手机布局、明暗主题、无需构建步骤 |
| 下钻 | 点击 KPI / 分布 / 堆叠条 / 头部统计，查看数字背后的概念 |
| 拍照发给 DSH | 在浏览器里压缩照片，通过同源 RPC 发给选定的 DSH 会话 |
| 安全写入 | 仅回环地址 HTTP、同源写入、realpath 包含校验、64 KiB 请求体上限、写入前备份 |
| 混合数据 | seed 固定数据和真实 record 行可以共存；真实行带 seed:false、会话和证据 |

环境要求

- DSH >=0.2.1-rc.3 <0.3.0-0
- Node.js >=20（DSH 自带运行时；单独装个 Node 方便跑测试）

从本地检出安装

1. Link the package into a DSH profile
dsh plugin --profile desktop add D:\path\to\dsh-learning-hub

2. Point the plugin at your learner data and the bundled panel
Edit <DSH_HOME>\profiles\desktop\cordis.patch.yml:

- id: learning-hub
name: dsh-learning-hub
config:
dataRoot: 'D:\path\to\learner'
panelDir: 'D:\path\to\dsh-learning-hub\public'
port: 19480 # optional loopback-only extra port

重启 DSH，然后：

- 工具 learning_hub 可用；
- 面板：http://127.0.0.1:<DSH_PORT>/learning-hub/；
- API：/api/learning-hub/state、/record、/route。

不写任何配置时，插件使用自带的演示数据：

- 数据：examples/demo-learner/
- 面板：public/

快速开始（演示）

node --test # 35 tests (34 plugin + panel selfcheck)
node test/panel-selfcheck.mjs # 523 panel checks

用任意静态服务器打开 public/index.html，或者安装插件后打开 /learning-hub/。

工具

只有一个工具，支持多个 action：

{"action":"status"}
{"action":"route","cwd":"D:/courses/c","text":"pointers and arrays"}
{"action":"record","branch":"cs.c","unit":"pointer","event":"practice","mastery":2,"evidence":"homework-4 Q3"}
{"action":"search","query":"pointer"}
{"action":"review","withinDays":7}
{"action":"link","from":"cs.c.array","to":"cs.c.pointer","relation":"prereq"}

event 取值为 study | practice | exam | review | misconception。
evidence 必填，且必须可追溯（作业 id、文件、会话 id）。

HTTP API

| 路由 | 方法 | |
| /learning-hub | GET | 302 → /learning-hub/ |
| /learning-hub/ | GET | 仪表盘 |
| /learning-hub/auth | GET | 302 → DSH /?token=…；设置 30 天 HttpOnly cookie |
| /learning-hub/<asset> | GET | 静态资源 |
| /api/learning-hub/state | GET | 规范状态 |
| /api/learning-hub/record | POST | 追加一条记录 |
| /api/learning-hub/route | POST | 路由文本/cwd |

所有非回环请求一律拒绝。写请求必须是同源 JSON，且限制在 64 KiB 以内。

数据模型

_learner/ 是唯一数据源：

profile.md
branches.json
concepts.json
progress.jsonl
errors.json
reviews.json
sessions.jsonl
materials/index.md
.backups/ # created by the plugin before writes

概念包含 id、name、aliases、branches、prereq、related、mastery（0–5）、evidence、misconceptions、sources、next_review，混合模式下还有 seed 和 mastery_basis。
先修关系有方向且无环；关联关系对称。
种子行保留 seed:true 和占位证据；真正执行 record 会写入 seed:false，追加一条真实证据字符串，新增一个 session，并同步 reviews.json 中对应的行。详见 docs/DATA-SCHEMA.md。

安全与隐私

- 只使用本地数据；不发起对外网络请求，不上报遥测，_learner 中不保存凭据。
- HTTP 仅限回环地址；写入要求同源的 Origin/Referer 和 JSON。
- 面板通过 GET /learning-hub/auth 使用 DSH 的浏览器认证（30 天 HttpOnly cookie）；JSON 中不返回 token，_learner 中也不保存 token。
- 静态路径会做 realpath 校验；..、绝对路径、符号链接逃逸和 NUL 字节一律拒绝。
- 每次写入都是原子操作，并备份到 _learner/.backups/ 下。

通过隧道或反向代理暴露面板之前，请先读 SECURITY.md。认证只面向本地 DSH 浏览器；这不是多用户或远程访问产品。

开发

node --test # store/router/api/escape tests
node --check public/app.js
node test/panel-selfcheck.mjs

面板是纯 HTML/CSS/JS。没有构建步骤，也没有前端依赖。
插件是普通的 Cordis 包（lib/index.js）；改动 lib/ 需要重启 DSH，改动面板只需刷新浏览器。

参见 CONTRIBUTING.md 和 docs/ARCHITECTURE.md。

许可证

MIT。参见 LICENSE。