# dsh-notebook-studio

[English](README.md) | **中文**

将一个 dsh 会话作为一个文献项目：导入最多 30 篇文字版 PDF，选择本次使用的文献，检索带页码的证据，通过提示词生成**报告（DOCX/PDF）**或**演示文稿（PPTX/PDF）**。成稿自动保存到当前会话工作区，并可在 Studio 内预览 PDF。可选联网背景，默认不搜索；按章节和页内容规划文献原图、可编辑流程图与证据表，AI 概念示意图也是可选项，不再固定全篇各一张图。

这是独立 Git 仓库，不包含 dsh 本体、文献或成稿。仓库地址：<https://github.com/HaoKuo/dsh-notebook-studio>。版本记录见 `RELEASE_NOTES.md`。

## 要求与安装

- DeepSeek Harness `0.1.7-rc.2`（开发与验收基准，依赖锁定为此版本）、Node.js 24、Python 3.12/PyMuPDF。文本模型可以使用 dsh 已注册的模型，或兼容 OpenAI Chat Completions 的独立服务。
- PDF 使用 PDFKit 直接排版，需要包含中文字形的 TTF 字体。本机可自动选用 Arial Unicode；其他环境请设置 `STUDIO_CJK_FONT=/path/to/font.ttf`，不能找到中文字形时会明确报错。
- 可选：`@qithird/dsh-paste-input-plus@0.2.1` 供**聊天输入框**上传 PDF。Studio 内文件/文件夹上传不依赖该插件。可选的生图服务需返回 `images/generations` 的 base64 PNG。
- 可选联网参考使用 dsh 的 `ctx.web.search`；需由 dsh 部署方配置可用的网络搜索提供方。服务不可用或没有带摘录的 HTTPS 结果时任务明确失败，不会偷偷降级为离线成稿。

在仓库根目录执行：

```sh
npm ci
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
npm run check
dsh plugin --profile web add "$PWD"
mkdir -p "$HOME/.dsh/skills"
ln -sfn "$PWD/.agents/skills/research-studio" "$HOME/.dsh/skills/research-studio"
```

`dsh` 不在 `PATH` 时改用实际可执行文件的绝对路径。本机 `web` profile 中插件和技能已软链接到本仓库；**不要让安装命令代替确认**。安装或更新后由用户自行安排重启现有 `dsh web`，以重新打包 Web Client。本任务不自动停止或重启正在运行的 dsh。

### 从 GitHub 安装

宿主通过 pnpm 安装 git 源，无需本地克隆：

```sh
dsh plugin --profile web add github:HaoKuo/dsh-notebook-studio
# 固定到某个发布版本：github:HaoKuo/dsh-notebook-studio#v0.6.1
```

git 安装不带 Python 虚拟环境。PDF 解析按顺序寻找解释器：`STUDIO_PYTHON`（设置后必须可用）→ 包内 `.venv` → `PATH` 上的 `python3`／`python`，且该解释器必须能 `import pymupdf`；都不满足时，报错会列出尝试过的每个候选项以及修复方法：

```sh
python3 -m venv ~/.venv-studio && ~/.venv-studio/bin/pip install "PyMuPDF>=1.26,<2"
export STUDIO_PYTHON=~/.venv-studio/bin/python    # 启动 dsh web 前设置
```

## 语言

插件跟随 dsh 的语言设置（设置 → 通用 → 语言，`zh`/`en`）。Web Client 加载时从宿主 locale 服务读取当前语言，并向宿主取一份词典（`getMessages`）；词典键就是中文原文，因此缺失的翻译会回退到中文原文而不是空标签。切换语言会重新渲染已打开的工作台。宿主侧 `studio_search` 的面向模型文案（工具描述与返回给模型的指引）跟随用户显式选择的非中文语言；没有显式选择时保持原文。

## 使用流程

**v0.5.1 使用唯一侧栏入口**：点击 dsh 左侧「插件」上方的 **NotebookStudio**，工作台在主区域打开，保留宿主左侧导航。已取消会话标签和会话顶部 Studio 按钮。工作台内左侧资料库，中间正文编辑／PDF 预览，右侧创作设置；两侧可收起。顶部集中显示项目、任务进度、生成和导出，模型配置放在齿轮设置中。按钮、背景、文字、边框及状态直接使用 dsh 主题变量，跟随明暗主题，不再使用独立的青绿色配色。窄屏改为纵向排列，内容区域优先。

1. 先选择一个 dsh 会话，再点击左侧 **NotebookStudio**；「返回对话」回到原会话界面，不更换会话。没有当前会话时展示选择／新建会话的指引，不自动创建项目，也不会读取其他会话文献。换项目时在宿主侧栏选择另一个会话，再点击 NotebookStudio。从聊天框回形针发送 PDF，或在资料库选择多个 PDF／选择文件夹。文件夹中的非 PDF 文件会跳过。每项目最多 30 篇，单篇必须非空且**严格小于 30,000,000 字节（30 MB）**；按内容哈希去重。扫描件目前不做 OCR。离开工作台会取消尚未传完的上传；已入库文献保留，后台生成任务继续执行。
2. 在「模型设置」选择已加载的 dsh 文本模型；或填写独立 API 的 Base URL、模型名和 API Key。默认使用 dsh 的 DeepSeek Flash。图片模型默认关闭；需要时勾选启用，填入兼容 `/v1/images/generations` 的地址及模型，API Key 可留空用于本机 Qwen。单张图片默认最长等待 600 秒，可设置 30–1800 秒；模型冷启动较慢时可适当延长。
3. 等资料显示「已索引」，勾选本次使用的 PDF（默认全选已索引文献），在右侧填写写作目标。需要外部背景时再勾选「加入网络搜索参考」：仅发送提示词关键词到 dsh 搜索，不发送 PDF 正文。网络参考以 `[Wn]`、URL 和检索时间单列，不能冒充 `[n] PDF p.x` 的论文证据。
4. 选择报告 **DOCX 或 PDF**，点顶部「生成完整报告」；选择演示 **PPTX 或 PDF**，点「生成完整演示」。后者先综合所选 PDF 分 4 批生成 14 页有引用的大纲，再逐页带入 PDF 原文摘录生成详细结论、论述和讲者备注，最后排版。中间「大纲」是可选步骤，也可先生成、编辑保存，再按大纲生成详细成稿；旧大纲仍绑定创建时的选篇及联网结果。
5. 等任务成功后点「预览成稿」查看 PDF，顶部「导出」下载所选格式，「文件与来源」提供实际路径和来源清单。DOCX/PPTX、PDF、来源 JSON 会同时保存到 **dsh 当前会话工作区**的 `notebook-studio/<会话专属目录>/<report或deck-随机后缀>/`；这不是插件仓库目录。重新排版保存到新目录，不覆盖用户修改过的副本。幻灯片已完成的逐页成稿会缓存供失败重试。
   插图按正文规划，报告每节可有 0–2 个视觉素材、演示每页一个主要视觉区域，全篇数量不固定。相关结果用原图，步骤和机制用流程图，多篇比较用表格，抽象概念可用 AI 示意图；每张图保留本节/页用途和来源。生图串行执行，失败会提示并以相应章节/页的流程图补位，不冒充论文结果。服务恢复后可重新排版重试生图。
6. 点击「打开正文编辑」，修改标题、报告摘要／段落／表格结论，或逐页论述／核心结论／讲者备注；再「保存并重新排版」。此操作不调用文本模型改写正文，不接受修改引用 ID 或素材来源；修改结论后仍须人工核对证据。启用图片服务时，重新排版可能请求概念图。排版失败保留编辑草稿，拒绝用过期稿覆盖新版；原导出文件不变。旧版演示从来源清单还原正文，不拿当前大纲冒充正文。
7. 同一浏览器页面内，离开后重新进入 NotebookStudio 会保留该会话的提示词、选篇和编辑草稿；不同会话隔离。工作台中有未保存草稿时刷新／关闭页面会提示；离开工作台后刷新也会丢失内存草稿，请先保存。这不是跨设备或重启后的草稿恢复。生成成功的内容已保存在 Host 数据库和文件中。
8. 在 Chat 中使用 `studio_search` 问答；回答应附上证据 ID、文献名和 PDF 页码。左侧可检索证据、查看任务记录及重试失败文献。

### 宿主兼容范围

本轮基于本机 **dsh 0.1.7-rc.2** 的公开槽位契约和实际 React 运行时实现。入口注册到 `sidebar.panellist`（顺序 -10，宿主「插件」为 0），工作台注册到 `main`，以 `session-maybe` 子槽读取当前会话，使用 `layout.selectPanel(null)` 返回。不改宿主核心布局、私有路由或模拟点击，导航行样式和折叠提示由宿主管理。已做隔离界面与 Host 合成测试；界面测试加载实际宿主导航行组件及亮暗主题 CSS。

在 `0.1.7-rc.2` 上的验收状态：`npm run check` 针对锁定的 `0.1.7-rc.2` 依赖通过 **40 个 JavaScript + 2 个 Python 测试**；`dsh --profile web --dump-config` 能把该插件层合成进 profile；运行中的 `dsh web`（0.1.7-rc.2）已挂载宿主侧插件，`studio_search` 可正常应答。**尚未验证**：在 0.1.7-rc.2 上用真实文献跑完整云端生成；以及已加载新依赖树的重启实例中的部署验收——这需要重启，重启后请各跑一次真实报告与真实演示。`0.1.7-rc.2` 以外的宿主版本不在本次验收范围内。

升级后，打开 Studio 会自动把该会话最近已完成的旧稿补存到工作区，**不改写旧稿内容**。要采用新版按内容规划的插图，请重新点击生成报告／完整演示；「重新排版」只复用已保存的正文和视觉计划。工作区缺失或不可写时保留内部成稿、下载和预览，界面明确提示保存失败。

## 目录和安全

- `src/`：Host、认证 RPC、上传、SQLite FTS5、模型调用、DOCX/PPTX 与独立 PDF 排版；`lib/client.js`：侧栏入口及会话隔离的 Studio 主面板；`worker/`：PyMuPDF 解析；`tests/`：合成资料与客户端注册契约回归；`.agents/skills/`：检索技能。
- 内部数据库、原始 PDF、提取图和成稿缓存保留在 `~/.dsh/studio/v1/<会话专属目录>/`；可交付的 Office、PDF 和来源清单另存到会话工作区。输出路径只取自 Host 的会话 `cwd`，不能由模型或客户端指定任意文件路径，并拒绝输出子目录符号链接。Studio 分块上传每块 512 KiB，经 dsh Connection 认证；服务端只处理自行建立的暂存文件。聊天框入口仍校验会话清单和目录所有权。下载和预览均按当前会话中的记录 ID 校验。
- API Key 保存在该项目权限受限的 SQLite 文件，读取设置只返回“已配置”，不回传明文。文本 API 会收到用于总结和逐页成稿的**所选 PDF 摘录**；联网搜索只收到用户提示词关键词；启用云端图片 API 后示意图提示词也会发送给对应服务。请先确认文献上传、原图使用和 API 提供方的授权。图片不标记为论文实验结果。
- DOCX/PPTX 可编辑；PDF 由同一内容单独排版，**不是 Office 的逐像素转换**。没有原图或没有生图模型时仍可输出有证据的原生流程图和对照表。质量和“优于 NotebookLM”的说法须经人工对照测评，不能仅凭自动测试宣称达成。

运行 `npm run check` 检查 JS/Python；真实文献的完整云端生成与真实联网检索**尚未经许可执行**。本机旧版曾以 12–30 篇真实 PDF 测试导入和图像提取，本版生成与联网使用合成资料和模拟接口测试，不会自动向云端发送这些文献。

### 第六页「未引用当前 PDF 摘录」

`v0.4.0` 拆开结论长度、引用缺失和引用过多的校验：旧代码把结论超过 120 字也误报成引用错误。重试会把具体字段、约束及上次 JSON 交给模型修复，缺失 `refs` 时说明本页可用编号；绝不自动补造引用或接受无依据成稿。旧的无效逐页缓存会重新生成。已覆盖第六页结论过长、漏写引用后修正及持续虚构引用被拒绝的回归。

### 下载为 0 字节、Studio 预览空白

`v0.4.1` 修复下载路由遗漏 `requestBody: 'buffered'`：在 dsh `0.1.6-alpha.2` 中，这会让 GET 被错误地构造成带请求体的请求，返回空的 HTTP 400。现在全部六种文件路由声明正确模式，并支持 HEAD 预览检查；下载先检查 HTTP 状态、文件大小与传输长度，错误不再另存为“成功下载”的空文件。

这个问题不代表服务器没有生成正文，也不是图片模型降级造成的。更新并重新加载插件后，到「成稿」重新下载即可，无需重新调用文本模型。也可直接打开工作区内的原始成稿。

### 文本模型输出被截断

`max-tokens` 表示模型到达本次调用的输出上限，不是 PDF 导入失败。`v0.3.1` 对 DeepSeek 结构化写作关闭不必要的推理输出，调高摘要、大纲、逐页成稿及报告额度，并在明确截断时有限次提高额度重试；仍失败时任务会保留具体阶段并提示改用支持更长输出的模型或缩小生成范围。更新插件后需由用户自行重启运行中的 `dsh web`，再重新点击生成；已完成的逐篇摘要和逐页成稿会继续复用。

## 许可证

MIT，见 [LICENSE](LICENSE)。