@dongfangw/study-kit 0.1.1 → 0.1.3

package/README.md

@@ -14,16 +14,60 @@ dsh plugin install @dongfangw/study-kit
 ## 能力
 
 - 书籍版式读 adoc / md，公式走 KaTeX；超长文档自动分段
+- **PDF 阅读器**：浏览器的 pdf.js 渲染（矢量清晰、可缩放、可翻页），选中文字即可取色标记 /
+  画重点线 / 写批注 / 问 AI——与 md/adoc 共用同一套标注面板与「带着这段问 AI」
 - 荧光笔 / 重点线 / 便签提问（标注只落本机）
-- 阅读位置记住（按文档、按段）
+- 阅读位置记住（文档按段，PDF 按页 + 页内比例）
 - 「我的库」：加库向导、库隔离（`visibility: private` 三出口全隐）、每库 Git 状态
 - 4 个工具：`kb_libraries` / `kb_catalog` / `kb_read` / `kb_search`
 - 5 个技能：学习导航、学习路径、概念答疑、物理直觉、建库向导
 
+## PDF 怎么用
+
+1. 在库的 `library.yaml` 里把 `pdf` 加进某个分组的 `exts`（例：`exts: [md, pdf]`），
+   目录树里就会出现 PDF 节点（徽章 `PDF`）。
+2. 点开即读：默认**适宽**；顶栏有页码跳转、上一页/下一页、缩小/适宽/放大（`Ctrl` + 滚轮也行）。
+3. 选中一段文字 → 工具条浮出：四种荧光色 / 重点线 / 写想法 / 问 AI。
+   标记按「第几页 + 页内文字偏移」存，换缩放、换窗口宽度后仍贴在同一段话上。
+4. 右下角「✍ N」打开标记面板：按页列出、可定位、删除、复制全部（Markdown）、清空。
+
+实现要点（改这块之前先读，否则很容易踩回去）：
+
+| 组件 | 职责 |
+|---|---|
+| 宿主 `src/pdf.ts` | `/kb/pdf` 送 PDF 字节（Range 感知，pdf.js 靠它分块拉大文件）；`/kb/pdfjs/*` 按白名单伺服 pdf.js 运行时（含 `cmaps/` 与 `standard_fonts/`，中文 PDF 缺 cmaps 会抽不出文字）；`loader.js` 带版本号 |
+| 客户端 `pdfjs.ts` | 注入宿主 loader、等 `window.__aeroPdfjs`；**pdf.js 不进客户端 bundle**（主库 350KB + worker 1.4MB，且 worker 必须是独立文件） |
+| 客户端 `PdfViewer.tsx` | 逐页 canvas + 文字层（只渲视口附近两屏的页）、缩放/翻页/位置记忆、选区 → 页内锚点 |
+| 客户端 `pdfAnno.ts` | 页内文字索引、选区 → 偏移锚点、标注 → 色块矩形（空白归一后按原文兜底找回） |
+| 客户端 `annotations.ts` | 标注库（`aero.anno.v1`）：PDF 用 `paintPageTextAnnotation`，键是 `pdf:<relPath>` |
+
+- 色块画在 canvas 与文字层**之间**，且 `pointer-events: none`：文字层在最上面，
+  所以拖选永远不被色块拦住；点色块靠矩形反查（`hitTestAnnotations`）。
+- 文字层正在重建时（缩放/重新进视口）代码块会先摘掉，避免旧色块挂在新排版上。
+- 只有 `md/adoc` 走 `/kb/doc`；`.pdf` 走 `/kb/pdf`——把二进制喂给 markdown 渲染器只会得到乱码。
+
+**安装体积**：`pdfjs-dist` 带来约 36MB（含 `.map` 与 legacy 构建），另有它的可选依赖
+`@napi-rs/canvas` 约 36MB（**只有 Node 端渲染才用**，浏览器里用不到）。想省掉后者：
+`npm install --omit=optional`，或装完后删掉 `<profile>/node_modules/@napi-rs`。
+
+**已知限制**：扫描件（没有文字层）里选不中文字，因此只能翻看、不能取色标注——页面上会显示
+「第 N 页」占位；PDF 也不进 `kb_search`（全文检索只认 md/adoc）。
+
+## 门禁与自测
+
+```bash
+npm test          # 含 PDF 路由的行为约定（字节/Range/白名单/教师端分组）
+npm run audit     # 套件铁律（零课程专名、路由、技能完整性）
+npm run probe:pdf # 真实浏览器实测：真 bundle + 真路由 + 真 PDF，断言渲染/选中/标注/缩放
+```
+
+`probe:pdf`（`scripts/pdf-harness.mjs`）需要工作区根装有 `puppeteer-core` 与本机 Chrome/Edge；
+它把「学习资料」组件按 DSH 槽位约定挂到一个空白页里跑，截图落在 `tmp/pdf-harness/`。
+
 ## 状态
 
 施工中（阶段 2）。本仓从 `student-pack` 的阅读器部分拆出并去课程化。
 
 ## 许可
 
-MIT。
+MIT。

package/ext/adoc-convert/index.mjs

@@ -1,62 +1,62 @@
-#!/usr/bin/env node
-/**
- * AsciiDoc → HTML 转换的**隔离执行器**（供 src/render.ts 以子进程方式调用）。
- *
- * 为什么必须隔离（血泪教训，勿改回进程内 require）：
- *   `@asciidoctor/core` 内含 Opal（Ruby 的 JS 实现）运行时，加载后会把内建原型链改写掉
- *   （实测：`Object.getPrototypeOf(Array.prototype) !== Object.prototype`）。而 DSH 宿主用
- *   `@deepseek-ai/dsh-util-values` 的「无损 JSON」校验（snapshotJsonValue/isJsonValue）来把关
- *   会话事件落盘，该校验会逐层核对内建原型（hasPlainArrayPrototype/hasIntrinsicObjectPrototype）。
- *   原型链一旦被 Opal 改写，**宿主进程里所有数组都不再算合法 JSON**：
- *     · 任何 prompt 都无法写入会话日志 → 上层把错误包装成 session/agent-busy "prompt rejected"
- *       → 学生端看到的就是「提问报错 agent busy」；
- *     · 新会话的 api-session/added 事件也无法转发 → 新建会话失败。
- *   触发时机：学生首次打开任意 `.adoc` 教案（本插件的渲染库是惰性加载的）之后，进程即"中毒"。
- *
- *   注意：事后恢复原型链（Object.setPrototypeOf 回退）虽然能让 DSH 校验恢复正常，但会让
- *   Opal 自身的后续调用崩溃（Ruby 方法沿被改写后的原型链查找）。所以唯一稳妥的做法是
- *   把整个 asciidoctor 运行时挡在宿主进程之外——本文件的子进程就是这层隔离。
- *
- * 协议：stdin 收 JSON `{ text, options }`，stdout 回 JSON `{ ok: true, html }` 或
- *      `{ ok: false, error }`；退出码 0/1 仅作辅助，调用方以 JSON 为准。
- */
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-
-function readStdin() {
-    try {
-        return readFileSync(0, 'utf8');
-    }
-    catch {
-        return '';
-    }
-}
-
-function main() {
-    // 容忍 UTF-8 BOM（手工用 `< file` / Get-Content 喂请求时会带上）。
-    const raw = readStdin().replace(/^\uFEFF/u, '');
-    if (raw.trim() === '')
-        return { ok: false, error: 'asciidoctor 隔离执行器：stdin 为空' };
-    let request;
-    try {
-        request = JSON.parse(raw);
-    }
-    catch (error) {
-        return { ok: false, error: `请求不是合法 JSON：${error instanceof Error ? error.message : String(error)}` };
-    }
-    try {
-        const factory = require('@asciidoctor/core');
-        const api = factory();
-        const doc = api.load(String(request.text ?? ''), request.options ?? {});
-        return { ok: true, html: String(doc.convert()) };
-    }
-    catch (error) {
-        return { ok: false, error: error instanceof Error ? error.message : String(error) };
-    }
-}
-
-const result = main();
-process.stdout.write(JSON.stringify(result));
-process.exitCode = result.ok ? 0 : 1;
+#!/usr/bin/env node
+/**
+ * AsciiDoc → HTML 转换的**隔离执行器**（供 src/render.ts 以子进程方式调用）。
+ *
+ * 为什么必须隔离（血泪教训，勿改回进程内 require）：
+ *   `@asciidoctor/core` 内含 Opal（Ruby 的 JS 实现）运行时，加载后会把内建原型链改写掉
+ *   （实测：`Object.getPrototypeOf(Array.prototype) !== Object.prototype`）。而 DSH 宿主用
+ *   `@deepseek-ai/dsh-util-values` 的「无损 JSON」校验（snapshotJsonValue/isJsonValue）来把关
+ *   会话事件落盘，该校验会逐层核对内建原型（hasPlainArrayPrototype/hasIntrinsicObjectPrototype）。
+ *   原型链一旦被 Opal 改写，**宿主进程里所有数组都不再算合法 JSON**：
+ *     · 任何 prompt 都无法写入会话日志 → 上层把错误包装成 session/agent-busy "prompt rejected"
+ *       → 学生端看到的就是「提问报错 agent busy」；
+ *     · 新会话的 api-session/added 事件也无法转发 → 新建会话失败。
+ *   触发时机：学生首次打开任意 `.adoc` 教案（本插件的渲染库是惰性加载的）之后，进程即"中毒"。
+ *
+ *   注意：事后恢复原型链（Object.setPrototypeOf 回退）虽然能让 DSH 校验恢复正常，但会让
+ *   Opal 自身的后续调用崩溃（Ruby 方法沿被改写后的原型链查找）。所以唯一稳妥的做法是
+ *   把整个 asciidoctor 运行时挡在宿主进程之外——本文件的子进程就是这层隔离。
+ *
+ * 协议：stdin 收 JSON `{ text, options }`，stdout 回 JSON `{ ok: true, html }` 或
+ *      `{ ok: false, error }`；退出码 0/1 仅作辅助，调用方以 JSON 为准。
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+function readStdin() {
+    try {
+        return readFileSync(0, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+
+function main() {
+    // 容忍 UTF-8 BOM（手工用 `< file` / Get-Content 喂请求时会带上）。
+    const raw = readStdin().replace(/^\uFEFF/u, '');
+    if (raw.trim() === '')
+        return { ok: false, error: 'asciidoctor 隔离执行器：stdin 为空' };
+    let request;
+    try {
+        request = JSON.parse(raw);
+    }
+    catch (error) {
+        return { ok: false, error: `请求不是合法 JSON：${error instanceof Error ? error.message : String(error)}` };
+    }
+    try {
+        const factory = require('@asciidoctor/core');
+        const api = factory();
+        const doc = api.load(String(request.text ?? ''), request.options ?? {});
+        return { ok: true, html: String(doc.convert()) };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+
+const result = main();
+process.stdout.write(JSON.stringify(result));
+process.exitCode = result.ok ? 0 : 1;