共读讲义 James-Yao-xj/dsh-plugin-handout

description: "共读讲义：Markdown / 文本 / PDF 讲义接进会话，按节按页取文、随时提问，并按讲师提示词讲解" kind: "package-bundle"

dsh-plugin-handout

把一份讲义接进 DSH 会话，让模型和你一起读：按节 / 按页取原文、全文检索、同步阅读位置、记批注，并按你写的讲师提示词讲解。

核心不是「渲染文档」——右侧栏的内置预览已经能显示 Markdown 和 PDF。这个插件补的是另外三件事：

1. 模型看不见你在读哪里。 你滚到 3.2 节时，模型的上下文里没有任何一行提到这件事。
2. 一份讲义塞不进上下文。 讲义动辄几万字，整份读进来既贵又会被压缩掉细节。
3. 「讲什么」有了，「怎么讲」还没有。 讲义决定内容，但讲解方式（先直觉还是先定义、一次讲多少、不确定时怎么说）默认由模型的通用风格决定。所以这里留了一份可维护的讲师提示词。

所以它的设计重心是 「共享阅读位置」+「按需取文」+「可调的教学法」：状态里只存大纲（每节一行），正文永远按需读取，讲解风格由一份 Markdown 决定。设计取舍与实现细节见 docs/DESIGN.zh.md。

Summary

注册五个模型工具、一条会话投影、一段动态系统提示、一段静态系统提示（讲师提示词）和一条斜杠命令：

| 工具 | 作用 |
| handout_open | 打开讲义，返回目录大纲，并把它设为本次共读的讲义 |
| handout_read | 读一节（Markdown，含子节）或一页（PDF），也支持任意行区间 |
| handout_search | 全文检索，返回命中位置与上下文 |
| handout_goto | 记录用户当前读到哪一节 / 哪一页 |
| handout_note | 把疑问或批注挂在某一节 / 哪一页上 |

支持三种来源：

- Markdown —— 按标题分节；编号优先采用讲义自己的数字（3.2、「第三讲」→3），取不到才回退层级编号；
- 纯文本 —— 没有标题时按 60 行一块兜底；
- PDF —— 按页寻址（P12，也接受 12 / p12），逐页抽取文字层，并读出自带的书签目录作辅助；页眉、页码、纯符号行会被自动跳过，小标题取每页第一行真内容。

讲义正文不进会话日志；PDF 抽取结果按文件指纹（dev:ino:size:mtimeNs:ctimeNs）缓存，文件一改立刻失效。没有文字层的扫描件会明确报错并提示 OCR，而不是悄悄打开一份空讲义。

Use this package

安装

需要 DeepSeek Harness（本插件在 0.2.0-rc.2 上开发验证）。三种装法：

① 从本地源码目录（开发期推荐：pnpm 会建软链，改代码立刻生效）
cd ~/.dsh/profiles/desktop
pnpm add /绝对路径/dsh-plugin-handout

② 从 git 仓库
cd ~/.dsh/profiles/desktop
pnpm add github:James-Yao-xj/dsh-plugin-handout

③ 界面：Web 侧栏 → Plugins → 用绝对路径或 git 地址安装 → 启用

装完后把包名加进 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles（走界面安装时插件管理器会自动做这一步），然后重启或刷新。

源码改动默认不会热重载：base 层给 hmr 的默认配置是 root: []，只监听配置。要打开源码热重载，在 profile 的 cordis.patch.yml 里覆盖这一行（详见 docs/DESIGN.zh.md §5）：

- id: hmr
config:
base: /绝对路径 # 插件源码的父目录
root: ["dsh-plugin-handout"]

使用方法

整条流程只有两步是「必须做对」的：让模型打开讲义，然后告诉它你在哪。其余都是自然语言。

1. 准备讲义

把讲义放进工作区最省事（路径就是 handouts/xxx.pdf），也可以是任意可读位置。路径按会话的工作目录解析相对路径，不确定就写绝对路径。

| 格式 | 怎么寻址 | 编号举例 |
| Markdown（含子节） | 按标题分节，编号优先用讲义自己的数字 | 3.2、「第三讲」→ 3 |
| 纯文本 | 没有标题时按 60 行一块兜底 | 层级编号 |
| PDF | 按页，一页就是一个坐标 | P12，也可以直接写 12 |

PDF 需要有文字层。扫描件（图片型 PDF）会明确报错并要求先 OCR——不会悄悄打开一份空讲义。

2. 让模型打开它

打开 handouts/gradient-descent.pdf

模型调用 handout_open，拿到一份大纲（PDF 还会带上自带的书签目录），并把这份讲义设为本次共读的对象。没有这一步，handout_read 和 handout_search 都会直接报「还没有打开的讲义」。 一次会话里只有一份当前讲义；换讲义就是再打开一份，位置和批注会跟着一起清空。

3. 开始读

之后想说就说：

| 你说 | 插件做什么 |
| 「读一下 3.2 节」/「翻到第 2 页」 | handout_read 取那一节 / 那一页的原文 |
| 「我在看第 2 页」 | handout_goto 记住位置，之后每轮请求都自动带上它 |
| 「讲义里哪提到 oscillate」 | handout_search 定位，返回命中页与上下文 |
| 「记一下：这里没懂」 | handout_note 记批注，后续每轮提示都带着 |

一次完整的共读大概长这样（用的是仓库里的样例讲义，真机跑过）：

你： 打开 handouts/gradient-descent.pdf 模型：（handout_open）4 页，按页寻址，section_id 形如 "P12"…… ← 大纲 + 每页首行小标题你： 第 2 页讲了什么？
模型：（handout_read P2）……（引用第 2 页原文）你： 我在看第 3 页模型：（handout_goto 3）好，之后我就当你在第 3 页你： 记一下：这里没懂收敛率怎么来的模型：（handout_note）已记在 §P3 你： 讲义里哪提到 oscillate？
模型：（handout_search）命中 1 处，在第 2 页，上下文是……

4. 位置靠你说，批注靠你记

右侧栏的「共读」面板还没做，插件看不见你滚到哪里——「我在看第 3 页」这句话就是全部的同步机制。说过一次之后，模型的每轮上下文都带着它，不用反复提醒。

位置和批注随会话走，跨会话不共享：重开一个会话要重新打开讲义、重新指位置。

也可以直接说「把这段记在 3.2 节上」，让批注挂到你指定的节/页，而不是当前位置。

5. 斜杠命令

不经过模型，直接改状态：

/handout where 查看当前讲义、当前位置、书签与批注数量 /handout goto 3.2 跳到某一节（PDF 用页码，如 /handout goto 2） /handout teacher 查看讲师提示词的加载状态、生效范围与预览 /handout teacher reload 改了提示词文件后强制重读一次

6. 出问题的时候

| 现象 | 怎么办 |
| 「找不到讲义」 | 路径按会话工作目录解析，改用绝对路径 |
| 「有 N 页但没有可抽取的文字层」 | 扫描件，先 OCR 再打开 |
| 「讲义里没有编号为 X 的节」 | 编号要和 handout_open 给的大纲对得上：PDF 用页码 12 / P12，Markdown 用 3.2 |
| 一次没读全 | 单次返回有字符上限（默认 12000），结果里会附「本节还有 N 个字符」，让它按 from_line/to_line 接着读 |
| 批注挂错了地方 | 没有先指位置时，handout_note 会兜底挂到大纲第一节；先「我在看第 3 页」，或直接说「记在 3.2 节上」 |
| 模型讲得太啰嗦、爱打比方 | 改讲师提示词，见下一节，不用动代码 |
| 讲义改了 | 正文每次按需重读，改完直接生效；PDF 的抽取结果按文件指纹缓存，文件一改也立刻失效 |

讲师提示词：让模型讲得更像老师

讲义决定「讲什么」，讲师提示词决定「怎么讲」——先给直觉还是先给定义、一次讲多少、拿不准时怎么说、要不要留自测题。它不是代码里的硬编码，而是一份 Markdown，你可以一直改：

prompts/teacher.md # 随包发布，直接改这一份

随包发布的那份是可用默认值：面向本科在读学生，语言简朴、简洁，禁止比喻句与类比，讲义原文要标坐标，不确定就说不确定。它不绑定任何学科，按你自己的课改就是了。

内容会原样作为一段系统提示注入（位置在部署级 persona 之后、计划 / 工具策略之前），默认只在打开讲义后生效（teacherAlways: true 可以对所有对话生效）。三条约定值得先知道：

- HTML 注释不会进提示词（），可以在文件里放心留写作笔记；
- 不做模板变量替换，所以正文里写 {{...}} 也是安全的；
- 改完存盘，下一轮对话就是新内容：每次调用共读工具都会顺手核对文件的版本，不用重启 DSH，也不用重开讲义。想立刻确认就 /handout teacher。

路径怎么解析：相对路径按插件包根目录（不是会话 cwd——这是部署级配置），也接受绝对路径与 ~/；写成空串就关掉这个功能。超过 teacherPromptMaxChars 会拒绝加载并在 /handout teacher 里报错——提示词每轮都进上下文，失控的文件必须有闸门。

配置

在 profile 的 cordis.patch.yml 里按 id 覆盖（整块 config 替换）：

| 字段 | 默认 | 含义 |
| maxSectionChars | 12000 | 单次 handout_read 返回的字符上限 |
| maxOutlineEntries | 300 | 大纲最多返回多少节 / 页 |
| maxSearchHits | 20 | 单次检索的命中上限 |
| searchContextLines | 3 | 每条命中附带的前后文行数 |
| maxPdfBytes | 67108864 | 允许读取的 PDF 字节上限 |
| maxPdfPages | 600 | 最多抽取多少页 |
| pdfCacheEntries | 4 | 缓存几份已抽取的 PDF |
| teacherPromptPath | prompts/teacher.md | 讲师提示词文件；相对包根目录，支持绝对路径与 ~/，空串关闭 |
| teacherPromptMaxChars | 24000 | 讲师提示词字符上限，超过则拒绝本次加载 |
| teacherOrder | 100 | 讲师提示词在系统提示里的排序位置 |
| teacherAlways | false | 没有打开讲义时也注入讲师提示词 |

界面上的标题与图标

插件卡片、bundle 详情和「内置插件」清单里的标题与描述，读的是 locale/<语言>.json 里 meta 下面的字段，图标是 package.json 顶层的 icon：

{ "meta": { "title": "共读讲义", "description": "把一份讲义（Markdown / 文本 / PDF）接进会话一起读……" } }

三处缺一不可，缺了都不报错，只是卡片退回显示包名 dsh-plugin-handout 和默认图标：显示文本必须在 meta 下（顶层 title 会被静默忽略）、exports 里必须导出 ./package.json 与 ./locale/.json（读取方是通过 ESM 解析器拿这两个资源的）、icon 必须是包内的 SVG / PNG / JPEG / WebP 且不超过 256 KiB。同一个文件里那些扁平键（empty / outline / notes …）是右侧栏面板要用的文案，与上面这套互不干扰；test/locale.test.js 把两条契约都挡住了。

Model Experience

模型侧新增五个工具、一段动态上下文与一段静态提示（讲师提示词）。动态上下文只在有讲义打开时出现，内容是讲义路径、节数 / 页数、用户当前所在位置与已记批注，以及 PDF 的书签目录（最多 40 条）；正文永远需要显式调用 handout_read 才会进入上下文。提示里还写了四条行为约束：先取原文再断言、引用要标坐标（§3.2 / p12）、可以补充自己的知识但要明确区分讲义内容与补充。

讲师提示词是静态文本（走 systemPrompt.section，interpolate: false），默认只在共读进行中出现，内容完全由部署方的 Markdown 决定；去掉 HTML 注释后为空就等于不注入。

KV Cache effect

讲义路径、当前位置、批注数量在会话中变化时，动态上下文前缀会改变，可能使该轮之后的 KV 缓存失效；没有打开讲义时该插件不产生任何提示文本（零开销）。讲师提示词只在文件真的改动（文件版本变化）时才换文本，平时是稳定的前缀，不额外破坏缓存。

Known Limitations and Deferred Work

- 没有图形界面。 右侧栏「共读」面板（阶段 4）尚未实现，因此阅读位置目前靠用户口述，而不是滚动自动同步。
- PDF 只支持有文字层的文档，扫描件需要先 OCR；DOCX / PPTX / 图片讲义不支持。
- 阅读状态存在会话日志里，跨会话不共享。
- 检索是大小写不敏感的字面匹配，没有分词、模糊匹配或语义检索。
- 一次抽取整份 PDF，超大文档靠 maxPdfPages 截断。
- 讲师提示词是每份提示词一份文件、全 profile 共用一个：没有按讲义 / 按会话切换提示词的能力，也没有「A/B 两份提示词比效果」的机制。

Dev Note

lib/handout.js（文本解析）、lib/pdf.js（PDF 抽取）与 lib/teacher.js（讲师提示词加载）是零宿主依赖的纯函数，可以直接测；lib/index.js 才是 Cordis 插件。test/plugin.test.js 用假 ctx 把 apply() 真跑起来，覆盖工具注册、执行、投影、动态提示、讲师提示词与命令，不需要启动 DSH。test/locale.test.js 不测代码，测清单与 harness 读取方之间的契约：meta 包装、icon 规则、读取方要解析的两个 exports。

pnpm install
node --test test/.test.js # 72 个测试（文本 11 + PDF 16 + 插件集成 29 + 讲师提示词 9 + 清单与显示元数据 7）
node test/fixtures/make-pdf.mjs /tmp/sample.pdf # 生成一份样例 PDF

测试夹具 PDF 是用 30 行代码手写生成的（test/fixtures/make-pdf.mjs），不是二进制入库——夹具因此可读、可改、可复查。

License

MIT