@dongfangw/study-kit 0.0.0-stage → 0.1.1

package/lib/docsplit.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 超大文档**分段**（宿主侧切源文档，客户端按段渲染）。
+ *
+ * 背景（实测）：参考书里存在单文件 1.2 MB 的 Markdown，KaTeX 渲染后 HTML 达 22 MB、
+ * 浏览器一个文档就要建 **54 万个 DOM 节点**——右侧窗格空白十几秒、标签页整体卡死。
+ * 41% 的文档源文件超过 40 KB（渲染后 1–2 MB HTML、2–4 万节点），日常阅读同样发涩。
+ *
+ * 做法：在**标题边界**把源文档切成若干段（每段字符数不超过 budget），客户端一次只渲染
+ * 一段，并提供「上一段 / 下一段」导航。切在标题上而不是任意字符处，保证：
+ *   · 公式、表格、列表、admonition 等块级构造不会被切断；
+ *   · 每段都有自然标题，导航可读。
+ * 单个小节本身就超预算时（参考书常见：整章一个 `# 标题`），退化为按段落边界续切，
+ * 续段标题自动加「（续 N）」。
+ *
+ * 文档头（AsciiDoc 的 `= 标题` 与 `:属性:` 区、Markdown 的首部引言）在每段前原样补回：
+ * `:stem:`、`:imagesdir:` 等属性只声明一次，不补回会让第 2 段起公式与图片全部失效。
+ */
+/** 一段（供客户端做导航）。 */
+export interface DocSegmentInfo {
+    readonly index: number;
+    /** 导航标题（该段首个标题，或「第 N 段」）。 */
+    readonly title: string;
+    /** 该段源文本字符数。 */
+    readonly chars: number;
+}
+export interface DocSplit {
+    /** 文档头（含标题与属性行），每段渲染时都要前置。 */
+    readonly header: string;
+    readonly segments: readonly DocSegment[];
+}
+/** 一段正文：标题 + 源文本 + 在源文档中的字符区间（[from, to)）。 */
+export interface DocSegment {
+    readonly title: string;
+    readonly text: string;
+    /** 该段在**源文档**中的起始字符偏移（用于超限重切时把旧段号映射到新段号）。 */
+    readonly from: number;
+    readonly to: number;
+}
+/** 单段渲染结果硬上限（字节）：超过就重切更细。留足余量给「估算偏低」的参考书。 */
+export declare const SEGMENT_HARD_MAX_BYTES = 2200000;
+/** 默认每段源文本预算（字符，单轮粗切的起点）。 */
+export declare const DEFAULT_SEGMENT_BUDGET = 120000;
+/**
+ * 每段**渲染后 HTML** 的估算预算（字节）。
+ *
+ * 取 1.2 MB 而不是 2 MB：估算公式对「公式极密 + 长表格」的参考书会低估 2–3 倍
+ * （NACA-TR-1135 实测比值 2.84），留出这个安全系数后，实测单段最大 HTML 约 2 MB
+ * （≈ 5–8 万节点），而日常文档（知识库正文、教案，估算 0.3–0.7 MB）仍保持整篇不分段。
+ */
+export declare const DEFAULT_SEGMENT_TARGET_BYTES = 1200000;
+/**
+ * 渲染后 HTML 体积的**估算**（不渲染，只数）：正文本身约 1.3 倍，
+ * 每个公式按 KaTeX HTML 输出**实测区间中上值** 1.3 KB 计（实测：C01.1 约 1.0 KB、
+ * C04.3 约 2.0 KB、NACA-TR-1135 约 3.0 KB——取中上值，宁可对长公式文档略保守）。
+ *
+ * 为什么不用源字符数当唯一预算：同为 120 KB，纯表格文档只有 0.13 MB HTML，
+ * 公式密集的参考书能到 2.9 MB——差 20 倍。按估算定预算，才不会把轻文档切碎、
+ * 又漏掉重文档。
+ */
+export declare function estimateHtmlBytes(text: string): number;
+/**
+ * 把「超限重切」前的段起点映射到新计划的段号：两套计划都是同一源文档的有序切片，
+ * 只要找到包含该偏移的新段即可（重切只会把段切得更细，不会跨过它的起点）。
+ */
+export declare function mapSegmentIndex(next: DocSplit, sourceOffset: number): number;
+/**
+ * 把源文档切成段。返回段数 ≤ 1 时表示「无需分段」，调用方走原来的整篇渲染路径。
+ *
+ * targetBytes 为**估算 HTML 字节**预算（默认 1.2 MB）：先按字符粗切，
+ * 再按估算结果自适应收紧，直到每段估算都在预算内或已到最小粒度。
+ */
+export declare function splitDocument(source: string, kind: 'md' | 'adoc', targetBytes?: number): DocSplit;
+//# sourceMappingURL=docsplit.d.ts.map

package/lib/docsplit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docsplit.d.ts","sourceRoot":"","sources":["../src/docsplit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,mBAAmB;AACnB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;CACzC;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAED,6CAA6C;AAC7C,eAAO,MAAM,sBAAsB,UAAY,CAAA;AAE/C,6BAA6B;AAC7B,eAAO,MAAM,sBAAsB,SAAU,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,UAAY,CAAA;AAkFrD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtD;AA4BD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,WAAW,SAA+B,GAAG,QAAQ,CAUvH"}

package/lib/docsplit.js

@@ -0,0 +1,241 @@
+/**
+ * 超大文档**分段**（宿主侧切源文档，客户端按段渲染）。
+ *
+ * 背景（实测）：参考书里存在单文件 1.2 MB 的 Markdown，KaTeX 渲染后 HTML 达 22 MB、
+ * 浏览器一个文档就要建 **54 万个 DOM 节点**——右侧窗格空白十几秒、标签页整体卡死。
+ * 41% 的文档源文件超过 40 KB（渲染后 1–2 MB HTML、2–4 万节点），日常阅读同样发涩。
+ *
+ * 做法：在**标题边界**把源文档切成若干段（每段字符数不超过 budget），客户端一次只渲染
+ * 一段，并提供「上一段 / 下一段」导航。切在标题上而不是任意字符处，保证：
+ *   · 公式、表格、列表、admonition 等块级构造不会被切断；
+ *   · 每段都有自然标题，导航可读。
+ * 单个小节本身就超预算时（参考书常见：整章一个 `# 标题`），退化为按段落边界续切，
+ * 续段标题自动加「（续 N）」。
+ *
+ * 文档头（AsciiDoc 的 `= 标题` 与 `:属性:` 区、Markdown 的首部引言）在每段前原样补回：
+ * `:stem:`、`:imagesdir:` 等属性只声明一次，不补回会让第 2 段起公式与图片全部失效。
+ */
+/** 单段渲染结果硬上限（字节）：超过就重切更细。留足余量给「估算偏低」的参考书。 */
+export const SEGMENT_HARD_MAX_BYTES = 2_200_000;
+/** 默认每段源文本预算（字符，单轮粗切的起点）。 */
+export const DEFAULT_SEGMENT_BUDGET = 120_000;
+/**
+ * 每段**渲染后 HTML** 的估算预算（字节）。
+ *
+ * 取 1.2 MB 而不是 2 MB：估算公式对「公式极密 + 长表格」的参考书会低估 2–3 倍
+ * （NACA-TR-1135 实测比值 2.84），留出这个安全系数后，实测单段最大 HTML 约 2 MB
+ * （≈ 5–8 万节点），而日常文档（知识库正文、教案，估算 0.3–0.7 MB）仍保持整篇不分段。
+ */
+export const DEFAULT_SEGMENT_TARGET_BYTES = 1_200_000;
+/** 最小字符预算：再小就只剩几段公式，导航比正文还长。 */
+const MIN_SEGMENT_BUDGET = 12_000;
+/** Markdown 一级/二级标题：`# ` / `## `（行首，至多 3 个空格缩进）。 */
+const MD_HEADING_RE = /^ {0,3}(#{1,2})\s+\S/;
+/** AsciiDoc 一级/二级节标题：`== ` / `=== `。 */
+const ADOC_HEADING_RE = /^(={2,3})\s+\S/;
+/** 段落边界（空行）——小节自身超预算时的续切点。 */
+function isBlank(line) {
+    return line.trim() === '';
+}
+/** 去掉标题标记后的可读标题。 */
+function cleanTitle(line) {
+    return line.replace(/^ {0,3}(?:#{1,6}|={1,6})\s+/, '').trim();
+}
+/** 把源文本切成「标题块 + 正文块」，正文块以空行为界。 */
+function toBlocks(lines, isHeading) {
+    const blocks = [];
+    let buf = [];
+    const flush = () => {
+        if (buf.length === 0)
+            return;
+        blocks.push({ text: buf.join('\n'), title: '', heading: false });
+        buf = [];
+    };
+    for (const line of lines) {
+        const title = isHeading(line);
+        if (title !== null) {
+            flush();
+            blocks.push({ text: line, title, heading: true });
+            continue;
+        }
+        if (isBlank(line)) {
+            flush();
+            // 空行并入下一个块的分隔（保持段间空行）
+            blocks.push({ text: '', title: '', heading: false });
+            continue;
+        }
+        buf.push(line);
+    }
+    flush();
+    return blocks;
+}
+/**
+ * 段落级续切：把超预算的块文本按**空行**再切小。
+ *
+ * 只认空行边界，不做按字符硬切：Markdown 的长表格、AsciiDoc 的 listing/表格块内部没有空行，
+ * 硬切会把一行（表格一整行、公式一整块）劈成两半，渲染出来就是残表 + 乱码。
+ * 因此单个段落本身超预算时**整块保留**（这一段会大于预算，但内容正确）。
+ */
+function splitOversized(text, budget) {
+    if (text.length <= budget)
+        return [text];
+    const paras = text.split(/\n{2,}/);
+    const out = [];
+    let cur = '';
+    for (const p of paras) {
+        const piece = cur === '' ? p : `${cur}\n\n${p}`;
+        if (piece.length > budget && cur !== '') {
+            out.push(cur);
+            cur = p;
+        }
+        else {
+            cur = piece;
+        }
+    }
+    if (cur !== '')
+        out.push(cur);
+    return out;
+}
+/**
+ * 渲染后 HTML 体积的**估算**（不渲染，只数）：正文本身约 1.3 倍，
+ * 每个公式按 KaTeX HTML 输出**实测区间中上值** 1.3 KB 计（实测：C01.1 约 1.0 KB、
+ * C04.3 约 2.0 KB、NACA-TR-1135 约 3.0 KB——取中上值，宁可对长公式文档略保守）。
+ *
+ * 为什么不用源字符数当唯一预算：同为 120 KB，纯表格文档只有 0.13 MB HTML，
+ * 公式密集的参考书能到 2.9 MB——差 20 倍。按估算定预算，才不会把轻文档切碎、
+ * 又漏掉重文档。
+ */
+export function estimateHtmlBytes(text) {
+    const macro = (text.match(/(?:latexmath|asciimath|stem):\[/g) ?? []).length;
+    const stemBlock = (text.match(/^\[stem[^\]]*\]/gm) ?? []).length;
+    const dollars = (text.match(/\$/g) ?? []).length;
+    const math = macro + stemBlock + Math.floor(dollars / 2);
+    return Math.round(text.length * 1.3 + math * 1300);
+}
+/** 取段落里第一行非空文本（用于在源文档中定位该段起点）。 */
+function locateProbe(text) {
+    for (const line of text.split('\n')) {
+        const t = line.trim();
+        if (t !== '')
+            return t.slice(0, 60);
+    }
+    return '';
+}
+/** 给切好的段落补上源文档字符区间（旧段号→新段号映射要用）。 */
+function withOffsets(source, raw) {
+    const out = [];
+    let cursor = 0;
+    for (const s of raw) {
+        const probe = locateProbe(s.text);
+        const found = probe === '' ? -1 : source.indexOf(probe, cursor);
+        const from = found >= 0 ? found : cursor;
+        cursor = from;
+        out.push({ title: s.title, text: s.text, from, to: source.length });
+    }
+    for (let i = 0; i < out.length - 1; i++) {
+        out[i] = { ...out[i], to: out[i + 1].from };
+    }
+    return out;
+}
+/**
+ * 把「超限重切」前的段起点映射到新计划的段号：两套计划都是同一源文档的有序切片，
+ * 只要找到包含该偏移的新段即可（重切只会把段切得更细，不会跨过它的起点）。
+ */
+export function mapSegmentIndex(next, sourceOffset) {
+    for (let i = 0; i < next.segments.length; i++) {
+        const s = next.segments[i];
+        if (s.from <= sourceOffset && sourceOffset < s.to)
+            return i;
+    }
+    return 0;
+}
+/**
+ * 把源文档切成段。返回段数 ≤ 1 时表示「无需分段」，调用方走原来的整篇渲染路径。
+ *
+ * targetBytes 为**估算 HTML 字节**预算（默认 1.2 MB）：先按字符粗切，
+ * 再按估算结果自适应收紧，直到每段估算都在预算内或已到最小粒度。
+ */
+export function splitDocument(source, kind, targetBytes = DEFAULT_SEGMENT_TARGET_BYTES) {
+    let budget = DEFAULT_SEGMENT_BUDGET;
+    let split = splitOnce(source, kind, budget);
+    for (let i = 0; i < 6 && split.segments.length > 1; i++) {
+        const worst = Math.max(...split.segments.map((s) => estimateHtmlBytes(split.header + '\n' + s.text)));
+        if (worst <= targetBytes || budget <= MIN_SEGMENT_BUDGET)
+            break;
+        budget = Math.max(MIN_SEGMENT_BUDGET, Math.floor((budget * targetBytes) / worst * 0.9));
+        split = splitOnce(source, kind, budget);
+    }
+    return split;
+}
+/** 单轮切分：按源字符预算贪心装箱（供 splitDocument 自适应调用）。 */
+function splitOnce(source, kind, budget) {
+    const lines = source.split(/\r?\n/);
+    const re = kind === 'adoc' ? ADOC_HEADING_RE : MD_HEADING_RE;
+    const isHeading = (line) => (re.test(line) ? cleanTitle(line) : null);
+    const blocks = toBlocks(lines, isHeading);
+    // 文档头：首个标题块之前的全部内容（adoc 的 `= 标题` 与 `:属性:` 行、md 的引言）。
+    let headerEnd = blocks.findIndex((b) => b.heading);
+    if (headerEnd === -1)
+        headerEnd = 0;
+    const headerLines = blocks.slice(0, headerEnd).map((b) => b.text);
+    const header = headerLines.length === 0 ? '' : headerLines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+    const body = blocks.slice(headerEnd);
+    if (source.length <= budget) {
+        return { header: '', segments: withOffsets(source, [{ title: '', text: source }]) };
+    }
+    // 贪心装箱：段以标题块开头；正文块跟进，超预算就开新段。
+    const segments = [];
+    let cur = '';
+    let curTitle = '';
+    const push = () => {
+        if (cur.trim() === '')
+            return;
+        segments.push({ title: curTitle === '' ? `第 ${segments.length + 1} 段` : curTitle, text: cur.replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '') });
+        cur = '';
+        curTitle = '';
+    };
+    for (const b of body) {
+        if (b.text === '') {
+            cur += '\n';
+            continue;
+        }
+        if (b.heading) {
+            if (cur !== '' && cur.length + b.text.length > budget)
+                push();
+            if (curTitle === '')
+                curTitle = b.title;
+            cur += `${cur === '' ? '' : '\n'}${b.text}\n`;
+            continue;
+        }
+        if (cur.length + b.text.length > budget) {
+            // 正文块自身超预算：先收当前段，再把该块切成多段
+            const parts = splitOversized(b.text, budget);
+            if (cur !== '') {
+                const [first, ...rest] = parts;
+                cur += `${first ?? ''}\n`;
+                push();
+                for (const r of rest) {
+                    cur = r + '\n';
+                    curTitle = `第 ${segments.length + 1} 段（续）`;
+                    push();
+                }
+            }
+            else {
+                for (const r of parts) {
+                    cur = r + '\n';
+                    curTitle = `第 ${segments.length + 1} 段（续）`;
+                    push();
+                }
+            }
+            continue;
+        }
+        cur += `${cur === '' ? '' : '\n'}${b.text}\n`;
+    }
+    push();
+    // 只有一段时不做分段：header 已含在整篇源文里，调用方不能再前置一次。
+    if (segments.length <= 1) {
+        return { header: '', segments: withOffsets(source, [{ title: '', text: source }]) };
+    }
+    return { header, segments: withOffsets(source, segments) };
+}
+//# sourceMappingURL=docsplit.js.map

package/lib/docsplit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docsplit.js","sourceRoot":"","sources":["../src/docsplit.ts"],"names":[],"mappings":"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"}

package/lib/git.d.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface GitRepoDef {
+    readonly id: string;
+    readonly name: string;
+    /** 仓库根目录（绝对路径）。 */
+    readonly dir: string;
+}
+export declare let REPO_DEFS: readonly GitRepoDef[];
+/** 把 REPO_DEFS 绑定到实际目录（KB 根 + 插件包目录），过滤不存在的仓库。 */
+/**
+ * 仓库清单**由调用方注入**（来自 libraries.yaml 里各库的根目录 + 名字），
+ * 本插件源码里不出现任何课程仓库名。没注入过就是空 → Git 面板自动隐藏。
+ */
+export declare function setGitRepos(defs: readonly GitRepoDef[]): void;
+/** 当前生效的仓库清单（只读）。 */
+export declare function getGitRepos(): readonly GitRepoDef[];
+/** 兼容旧调用：返回已注入的仓库清单。 */
+export declare function resolveRepos(_kbRoot: string | null, _pkgDir: string): GitRepoDef[];
+interface GitHandlerOptions {
+    /** 解析知识库根目录（含 cwd 提示）。 */
+    readonly resolveKbRoot: (hintCwd: string | null | undefined) => string | null;
+    /** 插件包目录（student-pack 仓库）。 */
+    readonly pkgDir: string;
+    /** pull 成功后回调（清目录缓存、刷新案例清单）。 */
+    readonly onPullSuccess: (repoId: string) => void;
+}
+export declare function createGitHandler(opts: GitHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export {};
+//# sourceMappingURL=git.d.ts.map

package/lib/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAQhE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mBAAmB;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,IAAI,SAAS,EAAE,SAAS,UAAU,EACxC,CAAA;AAED,kDAAkD;AAClD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAE7D;AAED,qBAAqB;AACrB,wBAAgB,WAAW,IAAI,SAAS,UAAU,EAAE,CAEnD;AAED,wBAAwB;AACxB,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAElF;AAyID,UAAU,iBAAiB;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,MAAM,GAAG,IAAI,CAAA;IAC7E,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CACjD;AA2BD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CA4ItH"}