# @a9i5k4/dsh-literature 中文文档

规范地址：https://npmcn.com/package/%40a9i5k4/dsh-literature/

版本：0\.3\.6
npm 元数据更新时间：2026-09-08T05:53:27.264Z
中文译文更新时间：2026-11-07T07:45:57.470Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40a9i5k4/dsh-literature
原文对照：https://npmcn.com/package/%40a9i5k4/dsh-literature/?lang=original
项目主页：https://github.com/Aik358/dsh-literature#readme
源码仓库：https://github.com/Aik358/dsh-literature

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.2 MB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1
- 首次发布：2026-08-30T12:23:37.628Z
- 最新版本发布：2026-09-08T05:53:27.070Z
- 近 30 天下载量：2006（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

DSH Literature 文献侧窗：在 DeepSeek Harness 侧边栏识别 DOI/arXiv/标题、抓取元数据与全文、写入本地文献库或导出目录，并提供内置 PDF 阅读器（缩放/翻页/目录/搜索/高亮/笔记）。

## 安装

```sh
npm install @a9i5k4/dsh-literature
```

也可以使用：`pnpm add @a9i5k4/dsh-literature`、`yarn add @a9i5k4/dsh-literature`、`bun add @a9i5k4/dsh-literature`

## README

# DSH Literature · 文献侧窗

[![中文](https://img.shields.io/badge/%E8%AF%AD%E8%A8%80-%E4%B8%AD%E6%96%87-blue)](https://npmcn.com/package/%40a9i5k4/dsh-literature/#) · [English](https://npmcn.com/package/%40a9i5k4/dsh-literature/README_EN.md) · [💬 QQ 交流群](https://qm.qq.com/q/v7Asxn6vPa)

> 在 DeepSeek Harness 侧边栏里识别、下载、阅读并归档学术文献。 对话中出现的 DOI / arXiv ID / 标题，一键落入本地文献库，全文随取随读。

**反馈与交流：** 欢迎加入 QQ 交流群 —— [点此加入「文献侧窗」交流群](https://qm.qq.com/q/v7Asxn6vPa) —— 问题反馈、使用技巧、快速答疑，比 GitHub issue 更及时。

* * *

## 📥 安装与下载（npm）

[![npm version](https://img.shields.io/npm/v/@a9i5k4/dsh-literature)](https://www.npmjs.com/package/@a9i5k4/dsh-literature) [![npm downloads](https://img.shields.io/npm/dt/@a9i5k4/dsh-literature)](https://www.npmjs.com/package/@a9i5k4/dsh-literature) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://npmcn.com/package/%40a9i5k4/dsh-literature/LICENSE) ![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)

**npm 包：** [`@a9i5k4/dsh-literature`](https://www.npmjs.com/package/@a9i5k4/dsh-literature)

```bash
dsh plugin --profile web add @a9i5k4/dsh-literature
```

-   源码与发布版：[GitHub Releases](https://github.com/Aik358/dsh-literature/releases)
-   本地开发：`dsh plugin --profile web add D:/path/to/dsh-literature`（`link:` 协议）
-   安装后重启 `dsh web`，侧边栏出现「文献」入口（若装有右侧栏工作台则并入其 tab）

* * *

## ✨ 特性

-   **内置文献库** —— 识别、下载、保存、阅读、笔记全程自给自足，**不依赖任何外部软件**；可选导出到本地文献库（Zotero 生态）或目录
-   **自动识别** —— 从模型回复或粘贴文本解析 `DOI` / `arXiv` / `PMID` / `ISBN` / 标题，自动去重
-   **元数据抓取** —— Crossref / arXiv / OpenAlex，自动补全标题、作者、期刊、年份、摘要
-   **全文下载** —— OA 多源（arXiv → OpenAlex OA → Unpaywall → DOI → 出版商链接），失败明确分类并支持重试；可配置自定义下载源
-   **引用生成器** —— Scribbr 风格：参考文献 / 文内引用 / 直接引用（带页码）× APA 7 / GB/T 7714 / MLA 9 / Chicago 17 / **BibTeX**，一键复制；卡片**右键**直达引用菜单
-   **库管理** —— 扫描导入文件夹（文件名自动识别 DOI/arXiv/标题）、从本地文献库批量导入、自动监控新 PDF、条目增删；**标签**与**状态过滤**、**排序**（添加时间/标题/年份）；**多选批量导出** RIS / BibTeX / CSL-JSON
-   **侧窗阅读** —— 内置 PDF 阅读器：缩放、翻页、目录跳转、全文搜索、多色高亮与笔记（**支持简单 Markdown**：加粗/斜体/行内代码）；**阅读位置记忆**、**键盘快捷键**（←/→ 翻页、+/- 缩放、/ 搜索、Esc 关闭）、**夜读模式**（跟随暗色主题或手动开关）、**页面缩略图侧栏**（≤50 页）、**一键导出全部高亮与笔记为 Markdown**；**逐页加载**（按需取流式数据块，大文件秒开不卡顿）
-   **AI 助手联动** —— ChatPDF / SciSpace 式划词操作：选中文字即可**翻译 / 解释 / 总结**；工具栏可**对全文提问**（基于 PDF 文本回答）或一键**总结全文**；结果直接发送到当前 DeepSeek Harness 对话，可继续追问
-   **全网入口** —— 每条文献直达 Google Scholar / 百度学术 / 知网 / 来源页
-   **冲突预览** —— 库中已有相似条目时，先展示字段级差异再决定保留 / 覆盖 / 合并
-   **中英文双语界面** —— 界面语言可切换：**跟随宿主** / **简体中文** / **English**，选择后立即生效无需重启；服务端返回的提示与错误信息同样按当前语言呈现，英文界面下不会出现中文提示
-   **完全本地** —— 所有请求经本机回环接口转发，无遥测、无云端中转、无账号依赖

## 🚀 快速开始

1.  点击「文献」打开侧窗（或粘贴文本识别）
2.  让模型调用 `zotero_lookup`，或直接粘贴含 DOI / arXiv ID 的文本
3.  条目入窗后：**下载全文 → 阅读 → 保存**（默认存内置文献库）

```
"参考 DOI: 10.1038/xxxx"   →   条目出现，自动解析元数据
"arXiv:1706.03762"         →   一键下载全文 PDF
点击「保存」                →   存入内置文献库（可随时导出）
```

## ⚙️ 配置

侧窗右上角齿轮进入设置（分类：保存与导出 / 识别与下载 / 行为与界面 / 导入管理 / 自定义下载源 / 高级）：

| 项 | 说明 | 默认 |
| --- | --- | --- |
| 保存方式 | `内置文献库`（无需外部软件）/ `本地文献库`（需运行）/ `目录` | 内置文献库 |
| 导出目录 / 命名规则 / 导出侧车 | 目录模式的目标路径、命名模板、CSL-JSON/RIS 选择 | `{author}_{year}_{title}` |
| 默认标签 | 保存时附加，逗号分隔 | 空 |
| 自动解析 / 标题识别 / 自动扫描回复 | 识别策略与误报控制 | 开 / 开 / 关 |
| 重试次数 / 下载超时 | 网络重试与超时控制 | 3 次 / 30s |
| 重复条目策略 | 询问 / 保留库中 / 覆盖为新版本 | 询问 |
| 入口位置 | 自动（优先右侧栏 tab）/ 固定左侧栏 / 隐藏 | 自动 |
| 面板宽度 / 阅读器默认缩放 / 夜读模式 | 浮窗尺寸与阅读初始视图 / 跟随暗色主题或强制开关 | 380px / 适应宽度 / 自动 |
| 导入文件夹 / 自动扫描 | 本机 PDF 入库（手动或每 30s 自动） | 空 / 关 |
| 自定义下载源 | 自建镜像 / 机构代理 / 专属端点（含请求头） | 空 |

## 🧩 与 dsh-better-sidebar 集成

安装了 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 时，插件自动把「文献」注册为**右侧栏 tab**（`ctx.get('betterSidebar').registerTab`），不再占用左侧栏按钮位；未安装则回退为左侧栏入口 + 浮窗，并持续探测，检测到后自动迁移。

## 📚 引用生成

每条文献卡片的「引用」菜单：

| 模式 | 说明 |
| --- | --- |
| 参考文献 | APA 7 / GB/T 7714-2015 / MLA 9 / Chicago 17 完整条目 |
| 文内引用 | `(Vaswani et al., 2017)` / `（Vaswani等，2017）` |
| 直接引用 | 输入页码后生成 `(Vaswani et al., 2017, p. 7)` 等 |
| BibTeX | `@article{...}` 完整条目，可直接粘贴 JabRef / Overleaf |

## 🔌 自定义下载源

合规前提下，你可以在设置里添加**自己信任**的镜像 / 机构代理 / 专属端点：

-   URL 模板变量：`{doi}` `{arxiv}` `{isbn}` `{title}` `{url}`
-   自定义请求头（每行 `名称: 值`），适配带 token / cookie 的端点
-   作为官方 OA 链之后的兜底；缺变量或非法模板自动跳过

> 合规提醒：这些源由你自行配置并对其合法性负责，插件不内置任何破解或侵权来源。

## 🔒 付费墙与需要登录的文献

全文抓取仅使用公开的开放获取来源。当文献需要**登录或机构订阅**时：

1.  条目标记「需要登录」并给出原因
2.  「打开登录页」在浏览器完成登录 / 机构访问
3.  下载 PDF 后点「导入本地 PDF」，插件校验并自动执行保存流程

## 🧠 工作原理

```
浏览器侧窗 ── fetch / SSE ──▶ DSH 宿主进程 ──▶ 本地文献库（可选）/ 自定义源
  · 识别/状态/进度       · 解析与下载        · 内置库 / OA 链
  · PDF 阅读器          · 影子索引与笔记
```

-   默认（内置文献库）把条目与全文存放在插件自己的本地存储，**不依赖任何外部软件**
-   导出到本地文献库（Zotero 生态）时：浏览器无法直连（CORS 仅放行特定来源），读写经 DSH 宿主转发，写入走官方 Connector 协议两步提交

## 🔐 数据与隐私

-   元数据与全文请求直连公开学术 API（Crossref / arXiv / OpenAlex / Unpaywall），**不经任何第三方中转**
-   插件仅监听 `127.0.0.1` 回环路由，非本机请求一律 403
-   无遥测、无统计、不上传任何本地数据

## 🖥️ 兼容性

| 组件 | 版本 |
| --- | --- |
| DeepSeek Harness | ≥ 0.1.1-rc.2（Cordis v4） |
| 本地文献库（可选） | 8.x（Zotero 生态，Local API v3 / Connector API） |
| Node | ≥ 20 |

> 本插件与文献库官方无任何附属关系，为独立的开源兼容实现。

## ❓ 常见问题

**保存后没看到条目？** 确认保存方式；内置库模式完全离线，无需任何应用运行。

**付费文献下载失败？** 条目标记「需要登录/付费墙」：先「打开登录页」完成登录，下载后「导入本地 PDF」即可入库；或配置自定义下载源。

**修改设置后没生效？** 设置即时落盘；修改端口后需重启文献库应用使其生效。

## 🛠️ 开发

```bash
npm install
npm run build      # 产物输出到 lib/
npm run smoke      # 逻辑冒烟
npm run check:client  # 前端 bundle 结构 + apply 矩阵
npm run test       # 宿主侧端到端
```

```
src/
├── node/          # 宿主侧：路由 / 识别 / 元数据 / 下载 / 引用 / 导入 / 影子库
│   ├── zotero/    # 与本地文献库交互（只读查询 + Connector 写入）
│   ├── metadata/  # Crossref · arXiv · OpenAlex
│   └── fetch/     # OA 全文获取 / 自定义源 / 重试
└── client/        # 浏览器侧：侧窗 UI / 引用菜单 / PDF 阅读器（pdf.js 自捆）
```

## 📄 License

[MIT](https://npmcn.com/package/%40a9i5k4/dsh-literature/LICENSE)

商标声明：本插件与 Zotero 官方无任何关联。"Zotero" 为其版权所有者的商标，此处仅用于描述兼容性。

## 常见问题

### @a9i5k4/dsh-literature 是什么？

DSH Literature 文献侧窗：在 DeepSeek Harness 侧边栏识别 DOI/arXiv/标题、抓取元数据与全文、写入本地文献库或导出目录，并提供内置 PDF 阅读器（缩放/翻页/目录/搜索/高亮/笔记）。

### 如何安装 @a9i5k4/dsh-literature？

在项目目录运行 npm install @a9i5k4/dsh-literature，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @a9i5k4/dsh-literature 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/a9i5k4\_\_dsh-literature 是否存在。

### @a9i5k4/dsh-literature 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @a9i5k4/dsh-literature 可以商用吗？

@a9i5k4/dsh-literature 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @a9i5k4/dsh-literature 的下载量有多少？

根据 npm 官方下载统计，@a9i5k4/dsh-literature 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,006 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @a9i5k4/dsh-literature 还在维护吗？

最新版本 0\.3\.6 发布于 2026/09/08（1 个月前）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/08/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。