Skip to content

paperskills

Verified

@dongfangw/paperskills · v0.2.1 · MIT · Web UI

paperskills 的 DeepSeek Harness 插件:文献检索/下载/OCR/翻译/图谱/写作技能集 + 文献工作台 Web UI

Install

dsh plugin add @dongfangw/paperskills

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

@dongfangw/paperskills

paperskills 的 DeepSeek Harness 插件:把仓库里 32 个文献技能 + 文献工作台 Web UI 带进 DSH, 覆盖文献全流程 检索 → 下载 → 转 MD/OCR → 翻译 → 入库/图谱 → 阅读/笔记 → 写作/评审。

与同仓库的 Claude Code 插件(.claude-plugin/ + skills/)双格式共存,skills/、ars/ 单一来源。 npm 发布包自带 assets/skills/(32 个技能)与 assets/ars/shared/,装完即用,不依赖仓库其余文件。

安装(npm,推荐)

# 1) 装进 profile(只转发 pnpm,不会改 bundles 列表)
dsh plugin --profile web add @dongfangw/paperskills

# 2) 把包加进 profile 的 dsh.profile.bundles(编辑 ~/.dsh/profiles/web/package.json)
#    "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@dongfangw/paperskills"]

# 3) 重启 dsh web

在 Web 界面的「插件」页安装则会自动加入 bundles 并可启停,不需要手改 package.json。

安装/启动时 DSH 会按 peerDependencies 校验插件与运行时版本:本包声明 >=0.2.0-rc.2 <0.3.0-0,在 0.2.1-rc.5 上实测通过;更低或更高的 DSH 需用 dsh plugin allow-version 显式豁免(dsh-app-boot 的 evaluatePluginCompatibility)。

安装(git 源码)

cd paperskills/dsh
bash scripts/install.sh            # 装进 web profile(默认)
# bash scripts/install.sh headless # 装进其它 profile

脚本会:定位本机 DSH → 装构建依赖(npm install + 合并复制本机 @deepseek-ai 对齐版本)→ 构建 → dsh plugin --profile web add。装完重启 dsh web 并新建会话。

DSH 版本兼容(基线 0.2.0-rc.2,实测到 0.2.1-rc.5)

插件最初针对 DSH 0.1.0-rc.6 编写,0.1.2 起客户端 API 有破坏性变更,已就地适配:

变更点 旧(≤0.1.1) 新(≥0.1.2-rc.1)
客户端 apply(ctx) 上下文类型 ClientContext from @deepseek-ai/dsh-client-runtime/client Context from @deepseek-ai/cordis
ctx.slots 服务声明 由 dsh-client-runtime 提供 由 @deepseek-ai/dsh-client-ui-renderer/client 增强 cordis Context 提供
JsonValue 类型 dsh-tools 转出 改由内部 dsh-util-values 定义,插件内用本地结构等价别名
客户端 inject 含 @deepseek-ai/dsh-client-runtime 换为 @deepseek-ai/dsh-client-ui-renderer(该包已不存在)

2026-11-01 在 DSH 0.2.1-rc.5 上复验:宿主与客户端 tsc 双侧通过,插件挂进组合树、 Web「插件」页正常显示、客户端 bundle 加载零报错。@deepseek-ai/dsh-client-ui-slots 只是 纯类型包(无 dsh.client 字段,也不随宿主安装),已从 dsh.client.inject 移除,仅保留在 devDependencies 供类型检查。

另:install.sh 第 2 步改为合并复制 @deepseek-ai——DSH vendor 目录不含 dsh-client-ui-slots 等纯类型包,原先的 rm -rf 会把 npm install 装进来的类型包一起删掉,客户端 tsc 随即报 TS2307。

profile 无关性:webServer 为可选服务

宿主 inject 不再包含 webServer(该服务只有带 HTTP 前端的 profile 提供)。静态路由 /paperskills/<rootKey>/<relpath> 在 registerStaticRoute 内用 ctx.get('webServer') 按需取用, 缺省即跳过。这样同一份插件既能在 web profile 提供文献工作台 UI,也能挂进 headless / ACP 这类 无前端 profile 做批处理——否则整棵插件树会以 @dongfangw/paperskills: pending (waiting for service: webServer) 启动失败。

MCP 前置(浏览器类技能)

cnki-*、nudt-library-fetcher、scihub-batch-download、scholar-carsi-download 需要真实浏览器, DSH 侧由官方插件 @deepseek-ai/dsh-mcp-client 桥接(本仓不含该插件,随 DSH 分发)。要点:

  • 每个 server 一行 YAML,serverName 必须与技能正文里的写法逐字一致:chrome-devtools(知网)、 playwright(NUDT SSO 付费墙);工具在会话里名为 mcp__<serverName>__<tool>。
  • playwright 行不要加 --headless/--isolated:SSO 登录态要留在持久 profile 里,且必须是有头浏览器。
  • 环境变量(MINERU_TOKEN / DEEPSEEK_API_KEY)由启动 dsh 的那个进程继承——请从交互终端启动; .bashrc 对非交互 shell 会提前 return。

架构

DSH 会话 ──paperskills_* 工具──▶ paperskills 脚本(ars-local-search / literature-fetcher /
   ▲                              mineru-converter / paper-translate 等)
   │                                        │
   └─ literature/* 事件 ── 投影(literatureLibrary/Activity/Search/notes) ── /paperskills/ 静态路由
                                             │
                             客户端 conversation.view「文献工作台」标签页(库/检索/笔记/活动四面板)
  • 宿主 src/index.ts:技能 provider + 工具 + 会话投影 + /paperskills/<rootKey>/<relpath> 静态路由 (白名单扩展名 + realpath 前缀校验防穿越 + HTTP Range 流式,PDF 可直接看)。
  • 客户端 src/client/:conversation.view 槽位注册「文献工作台」标签页(库/检索/笔记/活动四面板), settings.section 槽位注册「文献工作台」设置页(MCP server 注册指引 + API key 前置说明)。

技能分发(32 个)

宿主 ctx.skills.registerProvider() 扫描 <repo>/skills/,把 Claude Code 技能迁移为 DSH 技能,并做 一次性改写(get() 时注入):

  • argument-hint → whenToUse(DSH 路由提示字段)
  • user-invokable(拼写错)→ user-invocable
  • 裸 shared/ 引用 → ../../ars/shared/(ARS 四技能的共享内容,否则会静默断裂)
  • $ARGUMENTS → ⟨用户输入参数⟩
  • 注入「资源定位」说明头(resourceBase 语义显式化)

技能 rank=600(BUNDLED_SKILL_RANK),source: bundled,resourceBase 指向技能目录。撞名 (如 slidev 与本机用户技能)由 DSH 的 rank 决胜,用户技能(rank 400)优先,见 @deepseek-ai/dsh-skill-filesystem。

宿主工具(驱动 UI)

工具 作用 依赖
paperskills_library 扫描 raw/<分类>/<论文>/full.md + graphify-out/graph.json → 文献库快照 无(本地读)
paperskills_local_search 本地文献库关键词检索(图谱 + 全文) _query_local_lit.py
paperskills_arxiv_fetch arXiv 检索 + 下载到 raw/<分类>/ _arxiv_fetch.py
paperskills_convert MinerU 转 full.md MINERU_TOKEN
paperskills_translate DeepSeek 翻译 full.md → translation.md DEEPSEEK_API_KEY
paperskills_note 给论文记笔记(notes/ 持久化 + 投影) 无

其余 20+ 技能(cnki-*、scihub、nudt-library、academic-paper 等)交给技能正文,工具不重复实现, 避免双轨漂移。

前置(不含密钥,需自行配置)

依赖 用到的技能 获取
MCP server chrome-devtools(serverName 必须精确 = chrome-devtools) cnki-* 系列 在 profile 的 cordis 组合里注册 @deepseek-ai/dsh-mcp-client
MCP server playwright(serverName 精确 = playwright) nudt-library-fetcher, scihub-batch-download 同上
MINERU_TOKEN mineru-converter MinerU 平台申请
DEEPSEEK_API_KEY paper-translate platform.deepseek.com

scihub 走 fetch_scihub.sh 脚本(其 MCP 镜像已失效,别按旧 README 注册 scihub MCP)。 未配置前置的技能仍会加载,调用时因缺凭据/缺 server 而失败或提示。

目录结构

dsh/
├── src/
│   ├── index.ts             # 宿主入口(provider + 投影 + 静态路由 + 会话工具注册)
│   ├── skills-provider.ts   # 技能 provider(扫描 + frontmatter 解析 + 迁移改写)
│   ├── tools.ts             # 6 个宿主工具 + 文献库扫描
│   ├── projections.ts       # 4 个会话投影(库/活动/笔记/检索)
│   ├── static.ts            # /paperskills 静态路由(白名单 + realpath + Range)
│   ├── paths.ts / run-script.ts / types.ts
│   └── client/              # 客户端(文献工作台 UI)
├── lib/                     # 构建产物(index.js 宿主 + client.js 客户端 bundle)
├── cordis.patch.yml         # 把插件插入 cordis 组合
├── package.json             # dsh.bundle + dsh.client 声明
├── tsconfig.json / tsconfig.client.json / tsdown.config.ts
└── scripts/install.sh       # 一键安装

已知限制

  • 文献库扫描假定项目结构为 raw/<分类>/<论文目录>/full.md + graphify-out/graph.json(paperskills 采集层技能的标准产出)。
  • 全文在 UI 内以纯文本 <pre> 展示(未接 Markdown 渲染器),PDF 走浏览器原生查看器(Range 流式)。
  • agents/cnki-researcher.md(Claude subagent)尚未映射为 DSH subagent,cnki-* 由技能直接引导。