企业官网建设流程全解析

claude-paper（alaliqing/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-utils；poppler-utils 不在 npm 依赖里，装插件时不会一并带上。缺了它，图表这一段就走不通。

解决。按平台补装，装完重启宿主 Agent 再重跑学习流程：macOS 用brew install poppler，Ubuntu/Debian 用sudo apt-get install poppler-utils，Arch 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.txt；meta.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 自动整理，数据来源于插件详情页。