双语源码学习页yangl326-Dylan/learning-dsh

learning-dsh

为 DeepSeek Harness (dsh) 提供版本化、中英双语（EN/ZH）的源码学习页面；以 dsh 插件形式运行，挂载在可配置的前缀路由（默认 /learning）上。

为 DeepSeek Harness (dsh) 提供版本化中英双语源码学习页面；以 dsh 插件形式运行，挂载在可配置的前缀路由（默认 /learning）上。

|  |  |
|---|---|
| 插件 Plugin | @dylan/learning-dsh（Cordis plugin） |
| 前端 Frontend | @learning-dsh/web（Vite static build） |
| License | MIT |

Screenshots / 界面展示

| 首页（章节卡片 + 版本切换）/ Home | 章节页（左侧导航树 + 正文）/ Chapter |
|---|---|
| Home | Chapter with sidebar |

| 架构图全屏灯箱 / Diagram lightbox | 英文界面 / English UI | 移动端抽屉导航 / Mobile drawer |
|---|---|---|
| Lightbox | English chapter | Mobile drawer |

- 章节导航树 — 左侧常驻目录，展开到子章节，点击平滑滚动定位（scroll-margin 避开 sticky header） / Persistent sidebar tree with sub-chapter anchors and smooth scroll-to-heading.
- 架构图灯箱 — 点击图表全屏查看，按 SVG 固有比例自动适配视口，Esc/背景/按钮关闭 / Click a diagram to open a fullscreen lightbox; auto-scales to the viewport, closes via Esc/backdrop/button.
- 中英双语 — 一键切换 EN/ZH，内容与 UI 同步，locale 记忆 / One-click EN/ZH toggle, content and UI switch together, locale is remembered.
- 版本化内容 — 版本下拉选择已发布内容版本，正文锁定对应 sourceRef / Version dropdown; content locked to its published sourceRef.
- 响应式 — 窄屏下导航树变为抽屉 + backdrop / Sidebar becomes a drawer with backdrop on narrow screens.

Usage / 使用方式

Prerequisites / 前置条件

- dsh CLI available (pnpm dsh ... from the dsh source tree, or an installed dsh binary) / dsh CLI 可用（dsh 源码树下 pnpm dsh ...，或已安装的 dsh 命令）
- Node ≥ 22
- Built artifacts / 构建产物：
cd packages/web && npx vite build
cd packages/plugin && npx tsc -p tsconfig.build.json

Option 0 — Let an AI agent install it for you / 方式 0：交给 AI agent 自行安装

Prefer to delegate the install? Paste the whole block below as the starting instruction to your AI coding agent (Claude Code, Cursor, …); the agent should clone, build, install and verify on its own. The block is self-contained, so it works even without reading the rest of this README. / 想省事？把下面整段作为起始指令交给你的 AI 编程助手（Claude Code、Cursor 等），让它自行完成克隆、构建、安装与验证。该指令块自包含，不依赖本 README 其余内容。

You are installing the learning-dsh plugin into a DeepSeek Harness (dsh) profile.

1. Locate the dsh checkout — the directory where pnpm dsh ... works (an installed dsh binary also works). Pick the target profile (default web); ask the user if ambiguous. Require Node ≥ 22.
2. Prepare the plugin repo in a scratch directory:
sh
git clone https://github.com/yangl326-Dylan/learning-dsh.git /tmp/learning-dsh
cd /tmp/learning-dsh && pnpm install
3. Build content, frontend and plugin, in this order:
sh
npx tsx scripts/build-content.ts                  # content JSON -> packages/web/public/data
cd packages/web && npx vite build                 # frontend dist
cd ../plugin && npx tsc -p tsconfig.build.json    # plugin lib

4. 安装到 profile 中：
pnpm dsh plugin --profile  add /tmp/learning-dsh/packages/plugin

5. 无需启动即可验证组合后的配置——应能看到一个 # == @dylan/learning-dsh 层：
pnpm dsh --profile  --dump-config

6. 启动一个全新实例，并确认学习页面以 HTTP 200 响应：
pnpm dsh --profile  --port 3080
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/learning/

7. 如果用户不希望改动 profile，跳过步骤 4–5，改为加载现成的覆盖文件：
pnpm dsh --profile  --patch /tmp/learning-dsh/scripts/learning-dsh.patch.yml --port 3099

保持检出目录的 monorepo node_modules 完整——插件通过 require.resolve('@learning-dsh/web') 定位前端 dist。之后未经告知用户，不要移动或删除 /tmp/learning-dsh。报告所使用的 profile、已验证的 URL，以及任何失败的步骤；按用户偏好保留环境（运行中的实例、临时目录）。

方式 A：作为 bundle 安装（推荐）

插件包自带 dsh.bundle 配置层（cordis.patch.yml），可与任意 dsh bundle 一样安装进 profile。在 dsh 源码树下执行：
sh
pnpm dsh plugin --profile web add /path/to/learning-dsh/packages/plugin

效果：

1. pnpm 将包链接进 profile（~/.dsh/profiles/web/node_modules）
2. 因 manifest 声明了 dsh.bundle.patch，dsh 自动将 @dylan/learning-dsh 追加到 dsh.profile.bundles
3. 重启 dsh 实例（或启动新实例）：
sh
pnpm dsh --profile web --port 3080

4. 打开学习页面：

不启动即可验证组合配置：
sh
pnpm dsh --profile web --dump-config   # 查找 "# == @dylan/learning-dsh" 层

卸载：
sh
pnpm dsh plugin --profile web remove @dylan/learning-dsh

方式 B：--patch 覆盖加载（不改 profile）

适合不想改动 profile 的快速试用。仓库已提供现成覆盖文件 scripts/learning-dsh.patch.yml：
sh
pnpm dsh --profile web --patch /path/to/learning-dsh/scripts/learning-dsh.patch.yml --port 3099

打开 。不写入 profile；去掉 --patch 参数即恢复原状。
Configuration / 配置

插件行可在 cordis.patch.yml 中按 id: learning-dsh 覆盖：
yaml
- id: learning-dsh
config:
mountPath: /learning   # 挂载前缀，默认 /learning
title: Learning dsh    # 页面标题，写入所服务的 index.html

Notes / 注意事项

- 挂载路径必须唯一——插件在 dsh webserver 上注册 prefix 路由；重复的 mountPath 会直接报错。
- webserver 的 fallback seat 归 dsh web app 所有——mountPath 之外的路径仍由 dsh 主界面服务。
- 服务名兼容——插件自动识别宿主 webserver 服务：ctx.httpServer（npm 发布版）或 ctx.webServer（master 源码），无需配置。
- @learning-dsh/web 需可从插件包解析——插件通过 require.resolve('@learning-dsh/web') 定位前端 dist；本仓库中它是 workspace devDependency，从源码运行时请保留 monorepo node_modules。

Repository layout / 仓库布局

content/            版本化双语内容源（YAML + body.md + SVG）
docs/               spec 驱动文档（contract / feature / spec）— 中文
packages/web        Vite 静态前端（@learning-dsh/web）
packages/plugin     dsh Cordis 插件（@dylan/learning-dsh）
scripts/            内容构建管线（build-content.ts）

Development / 开发
sh
pnpm install                       # workspace 安装
npx tsx scripts/build-content.ts   # 构建内容数据 -> packages/web/public/data
cd packages/web && npx vite build  # 构建前端 dist
cd packages/plugin && npx tsc -p tsconfig.build.json   # 构建插件 lib
cd packages/plugin && node e2e/verify.mjs              # 独立 E2E（真实 Cordis + webserver + 插件）

Docs / 文档：docs/README.md