claude-paperalaliqing/claude-paper装上了、也跑起来了但总有一两处不对劲图表没出现、论文像是被截断、查看器打不开……这些大多不是插件坏了而是几个可预期的坑。这篇只做排错不复述安装步骤按「现象 → 原因 → 解决」把五个高频问题过一遍。先说清它装好之后应该是什么样它的学习流程会自动做八件事解析 PDF 并提取元数据、分析论文复杂性和类型、生成自适应学习材料、创建代码演示、提取并包含原始代码、提取关键图表和图像、更新全局搜索索引、自动启动网页查看器。产物落在~/claude-papers/papers/{paper-slug}/比如paper.txt完整文本、meta.json元数据、quick-summary.md快速摘要、insights.md核心洞察、images/图表、code/代码演示全局索引是~/claude-papers/index.json。记住这个「应该长什么样」后面每个坑就能对号入座。站点给它的定位是dsh 原生插件 · chat本站星标 337、综合分 62.9安装命令为dsh plugin --profile web add zlzliqing/claude-paper。想先横向对照同类插件的中文清单与安装形态可以看 完整插件清单与汉化避坑指南。坑一 · poppler-utils 没装图表提取整段失败现象。学习流程跑到「提取关键图表和图像」这一步images/目录没有产出或者干脆只有文字材料一张图都没有。原因。图像提取器是一个 Python 脚本它依赖系统级的 poppler-utilspoppler-utils 不在 npm 依赖里装插件时不会一并带上。缺了它图表这一段就走不通。解决。按平台补装装完重启宿主 Agent 再重跑学习流程macOS 用brew install popplerUbuntu/Debian 用sudo apt-get install poppler-utilsArch Linux 用sudo pacman -S poppler。坑二 · 忘记 --target四个 Agent 的配置一起被改现象。你只想在 DSH 里用结果发现 Claude Code、Codex、OpenCode 的目录也被写了东西。原因。安装与升级的默认 target 都是all一次覆盖四个 Agent升级时如果只传了部分--target它还会把其他 Agent 的集成额外补齐。解决。安装时显式指定宿主DSH 就是--target deepseek-harness升级时必须传入与当初相同的--target列表例如upgrade --target codex,opencode。装之前想清楚要给哪几个宿主是这里唯一的稳妥做法。坑三 · 元数据里看不到全文误判论文被截断现象。打开meta.json发现里面的内容明显比论文正文短怀疑解析失败或被截断。原因。这是「上下文安全预览」的设计元数据只保留 50,000 字符的预览完整文本另外保存到同目录的paper.txt。它不是故障是为了不给上下文塞满整篇论文。解决。核对长度看paper.txtmeta.json只用于快速读取标题、作者、摘要不要拿它判断解析是否完整。坑四 · 按仓库名猜包名npx 直接报 404现象。照着 GitHub 路径写alaliqing/claude-paper或者干脆写claude-paper安装直接失败。原因。npm 包的作用域是zlzliqing与 GitHub 账号alaliqing不一致——包名和仓库名不同源靠仓库名猜必然对不上。解决。统一用zlzliqing/claude-paper。DSH 侧的安装命令就是dsh plugin --profile web add zlzliqing/claude-paper。坑五 · 5815 端口被占用查看器起不来现象。学习流程最后一步「自动启动网页查看器」失败http://localhost:5815打不开。原因。端口是写死的默认值README 明确「无需配置」——没有暴露端口配置项所以撞端口时改不了。解决。先查占用进程并释放 5815用lsof -i :5815找到它或者干脆改用材料文件直接阅读summary.md、insights.md、index.html。查看器只是浏览层不影响已经生成的学习材料。排错之外的几条边界这五个坑排完还有几件与「坏没坏」无关、但值得先知道的事该插件当前通过 Agent Skills 运行、没有独立 MCP 服务它只面向论文场景不做通用文档也不做网页抓取维护已放缓最近一次提交在 55 天前、npm 1.2.1 发布于 2026-08-14、周下载量只有 59社区面窄遇到新问题可搜的现成答案不多站点尚未对该插件做风险分级静态扫描判定「含敏感能力」其中一条证据是bin/claude-paper.mjs用spawnSync执行外部命令介意安装期执行脚本的人建议先在隔离环境验证。把同类插件的安装形态与汉化情况放在一起对照能少踩一些重复坑完整插件清单与汉化避坑指南 里那份清单可以当参考。总结claude-paper 的多数「故障」其实是五个可预期原因缺 poppler-utils、漏加--target、误读meta.json的 50k 预览、按仓库名猜错包名、5815 端口被占想对照同类插件的中文清单与安装形态见 完整插件清单与汉化避坑指南。适合与不适合适合刚装完插件、正卡在图表提取或查看器打不开的 DSH 用户遇到meta.json偏短就想回滚的人不小心把四个 Agent 配置都改了、想搞清楚怎么收场的多宿主用户包名写错报 404 后想确认正确安装命令的人。不适合希望插件自带 OCR、能直接处理扫描版或图片型 PDF 的用户README 只声明自动 PDF 解析与pdf-parse没有 OCR期待可配置查看器端口的人5815 写死在意安装期执行外部命令、又不愿意先隔离验证的用户。标签claude-paper、DeepSeek Harness、避坑排错、poppler、插件安装本文由 DeepSeek Harness Hub 自动整理数据来源于插件详情页。