源笔记本 cultureshocked/dsh-source-notebook

DeepSeek Harness 源笔记本

把你自己的课程文件——讲义 PDF、幻灯片、Word 笔记——附到对话里，智能体只依据这些段落作答，每条结论都标注文件名和页码、幻灯片页或行号范围。它还能把材料整理成学习指南和练习题。

这里有两个包，刻意分开：

| 文件夹 | 包名 | 是什么 |
| dsh-source-notebook/ | @local/dsh-source-notebook | 插件。每个对话里多一个 Sources 标签页，五个智能体工具，三个斜杠命令，一个 HTTP 读取端点，以及系统提示词里的一条依据规则。 |
| notebook-preset/ | @local/dsh-notebook-preset | 可选的 Notebook 智能体模式：同样的工具，配上学习伙伴的语气和一条 notebook/ 输出规则。 |

插件是部署级的配置行，所以它的工具在每个智能体模式里都存在。预设只提供策略和语气，不挂载任何笔记本代码。

你会得到什么

- Sources 标签页。 对话顶部 Chat 和 Trajectory 旁边的第三个标签页。选中它，列表就在原地展开：每个已索引的文件及其格式和大小，对没提取出可读文本的文件给出警告，一个用来添加路径的输入框，每行一个 × 用来移除。
- 标签页上的状态灯。 笔记本为空时标签显示 🔴 Sources，有内容时显示 🟢 Sources · 3。标签页只接受显示文本，所以这个灯是文字，不是带样式的圆点。
- 空白会话表单。 全新对话没有头部，也就没有标签页，所以输入框停靠区里会放一行 Sources [path] Add 表单，直到第一轮对话开始。第一个文件就是这样附上去的。
- 有依据的回答。 智能体回答前先搜索笔记本，每条结论都引用 file — locator，源文件没覆盖到的内容就直说，而不是凭记忆补上。

要求

- DeepSeek Harness Desktop，或任意 web UI 配置档。插件的客户端部分是一个浏览器模块；无头命令行配置档会加载工具，但不显示标签页。
- 别的都不需要。 没有 npm 依赖，没有构建步骤，没有编译器。提取器只基于 node:zlib 和 Buffer 编写。
- 可选：poppler 的 pdftotext，放在 PATH 里（或常见安装位置）。它是唯一能从幻灯片 PDF 里可靠还原阅读顺序的读取器。没有它就跑内置 PDF 读取器，结果看起来乱序时加一条警告。

安装

选一条路线。两条都以重启 harness 和刷新页面结束。

方案 A — 插件管理器（推荐）

1. 把本仓库克隆或解压到某个固定位置，例如 ~/code/dsh-source-notebook。
2. 在 DeepSeek Harness 里打开 Plugin Manager，对 dsh-source-notebook/dsh-source-notebook 的绝对路径执行 install bundle 操作。
3. 可选：对 notebook-preset 文件夹重复一遍，得到 Notebook 模式。
4. 重启 harness，然后刷新页面。
安装器会写入配置档的依赖列表和 bundle 列表，并把包链接进配置档，这正是下面手动方式所做的事。

方式 B — 手动编辑配置档

编辑配置档的 package.json —— ~/.dsh/profiles/<profile>/package.json（Windows：C:\Users\<you>\.dsh\profiles\desktop\package.json）。把这些条目合并进已有内容，不要替换整个文件。

{
"dependencies": {
"@local/dsh-source-notebook": "link:<path-to-repo>/dsh-source-notebook",
"@local/dsh-notebook-preset": "link:<path-to-repo>/notebook-preset"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"@local/dsh-source-notebook",
"@local/dsh-notebook-preset"
]
}
}
}

link: 路径里用正斜杠，Windows 上也一样（link:C:/Users/you/code/dsh-source-notebook/dsh-source-notebook）。

两条规则：

- 顺序有讲究。 @deepseek-ai/dsh-base 必须排第一。preset 必须排在 @deepseek-ai/dsh-web-app 之后，因为 preset 挂载的注册表由 web app 注册。
- link: 不是复制。 配置档指向这个目录，所以这里的改动下次加载就生效，不用重新安装。

然后重启 harness 并刷新页面。如果提示某个 bundle 无法解析，在配置档目录里跑一次安装步骤（pnpm install），生成 node_modules/@local/ 链接。

验证是否加载成功

Sources 标签页应该出现在至少有一轮对话的聊天里，模型也应该能用 notebook_search 等工具。输入 /source-notebook-list，会返回工作区源文件的 JSON 摘要。

使用

1. 打开聊天，选择 Sources 标签页（或在全新聊天里用 dock 表单）。
2. 输入路径 —— 相对工作区、纯文件名或绝对路径都行 —— 按 Add。notebook 会提取文本并建立索引。
3. 就材料提问。智能体会搜索、引用并标注出处。
4. 要学习指南或模拟考试；装了 preset 的话，在模式选择器里选 Notebook 模式。生成的文件放在工作区的 ./notebook/，转录文本放在 ./notebook/transcripts/。

智能体工具

| 工具 | 用途 |
| notebook_add_source | 按路径索引单个文件。 |
| notebook_remove_source | 按 id 移除文件。 |
| notebook_search | 按查询返回排序后的段落，每段带来源和定位信息。 |
| notebook_study_guide | 按文档顺序返回某主题的全部段落，受字符预算限制。 |
| notebook_practice_exam | 按主题区域返回段落，以及每个区域能支撑多少道题。 |

斜杠命令

/source-notebook-list、/source-notebook-add <path>、/source-notebook-remove <id>。

支持的文件

| 格式 | 引用中的标签 |
| PDF | page N |
| DOCX | outline、notes，然后是 lines A–B |
| PPTX | slide N，外加演讲者备注 |
| .txt .md .markdown .text .rst .csv .tsv .log .json .yaml .yml .html .htm | lines A–B |

扫描版 PDF 没有文本层：这类文件会报告为不可读，而不是悄悄按空内容建索引。加密 PDF 会被拒绝，并给出明确提示。

源文件存放位置

每个工作区一个 JSON 文件，放在已安装包旁边：

<repo>/dsh-source-notebook/source-notebook/<workspace-name>-<hash>.json

工作区就是一个目录，在其中打开的每个会话共用同一份列表，所以两个工作区互相看不到对方的源文件。文件只记录路径，不记录内容；文本索引本身会在重启后首次使用时于内存中重建。这个目录在这里被 git 忽略，因为它是运行时状态。

删除该文件（或从标签页里移除某个源）是受支持的遗忘方式。你的原始文件永远不会被移动、重命名或改写。

卸载时，在插件管理器里移除该 bundle（或从配置档中删掉依赖项和 bundle 条目）。把 dsh-source-notebook/ 连同它的 source-notebook/ 状态文件夹一起删除，别处不会留下任何痕迹。

配置

每个键都是可选的；下面是默认值。在配置档的 cordis.patch.yml 里改，或在本 bundle 自己的补丁文件里改。

| 键 | 默认值 | 含义 |
| maxSources | 400 | 单个工作区可容纳的文件数。 |
| maxSourceBytes | 25165824 | 单文件上限（24 MB），超过即拒绝。 |
| maxChunksPerSource | 4000 | 每个文件保留的分块数。 |
| searchResults | 8 | notebook_search 默认返回的段落数。 |
| chunkChars | 1200 | 每个可搜索分块的窗口大小。 |

工作原理

browser ── GET /source-notebook/sources?session=… (reads: no session event) └─ ctx.remote.commands.execute(…) (add / remove: logged) │ host: index.js ── registry (JSON per workspace) ── tools ──► model └─ extract.js PDF/DOCX/PPTX/text → citations

一切归宿主所有：客户端不持有索引，也不做任何提取。读取走 HTTP 而不是斜杠命令，因为命令执行是一次会话事件，而一个会自我重绘的视图不该往对话里写东西。添加和移除仍走命令，这里要的正是每个真实用户操作对应一行记录。

宿主侧把路由注册在可选的 webServer 服务上，路由缺失时客户端回退到命令，所以没有 web 服务器的配置档照样能用。

故障排查

没有 Sources 标签页。 刷新页面——客户端那一半是浏览器模块。全新的聊天按设计会隐藏页头和标签页；请用 dock 形式。

另一个聊天里看不到某个源。 源是按工作区划分的。同一目录下的两个聊天共用一份列表；不同目录下的两个聊天则不共用。

PDF 文本出来是乱码。 安装 poppler 并重启。警告信息在那一行显示 pdftotext 不可用。

改动插件不会生效。 宿主代码（index.js、extract.js、cordis.patch.yml）需要重启 harness；客户端代码（client.js）需要刷新页面。会话会一直沿用启动时的插件版本，所以改动之后要开新会话。

开发

没有构建步骤：这里的每个文件都按原样加载。

dsh-source-notebook/
├── package.json bundle manifest: dsh.bundle.patch, dsh.client, exports
├── cordis.patch.yml the deployment-level row and its config
├── index.js host half: registry, tools, commands, HTTP read
├── extract.js PDF/DOCX/PPTX/text extraction, no dependencies
├── client.js Sources tab, status light, blank-session add form
├── locale/en.json title and description for the Plugin Manager
└── icon.svg catalog icon

notebook-preset/
├── package.json
└── cordis.patch.yml the Notebook agent mode

代码遵循的约定：提取器只导入 node: 内置模块，因为 bundle 无法解析第三方包；客户端只导入 react；样式只用宿主主题 token（--dsw-alias-*），别的都不用。

权利

本仓库不授予任何许可。它仅供直接使用；要在别处复用代码，请先询问作者。