Skip to content
Back to search

Research-Claw

In the AI era, why can't everyone be a Principal Investigator?

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wentorai--research-claw/badge.svg)](/listings/wentorai--research-claw)

HTML

<a href="/listings/wentorai--research-claw"><img src="/api/listings/wentorai--research-claw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**macOS / Linux — 源码一键安装(推荐):**

curl -fsSL https://wentor.ai/install.sh | bash

Docker 一键安装(macOS / Linux / Windows 通用)

先安装 [Docker Desktop](https://docs.docker.com/desktop/),确保启动后托盘显示 Running,然后:

# macOS / Linux
curl -fsSL https://wentor.ai/docker-install.sh | bash
# Windows PowerShell
irm https://wentor.ai/docker-install.ps1 | iex

> 脚本自动完成:检测 Docker → 拉取最新镜像 → 保留旧容器作为回退 → 启动并验活 → 打开浏览器。新版本未能正常启动时会自动恢复旧版本。 > 重复运行即可更新到最新版本,数据不丢失(持久化在 Docker named volumes 中)。

安装完成后浏览器自动打开 `http://127.0.0.1:28789`,在 **Setup Wizard** 中配置 API Key,无需编辑任何配置文件。安装、更新和 `pnpm serve` 启动时都会在终端显示当前 Research-Claw、OpenClaw 与代码版本。

<details> <summary><b>手动安装 / 大陆网络 / 故障排查</b></summary>

手动安装(源码)

> 需要 Git、Node.js 22+ 和 [pnpm](https://pnpm.io/installation) 9。一键脚本会自动安装这些依赖,手动安装需要自行准备。

git clone https://github.com/wentorai/Research-Claw.git
cd Research-Claw          # ⚠️ 必须进入项目目录,否则 pnpm install 会报错
pnpm install && pnpm build
cp config/openclaw.example.json config/openclaw.json
pnpm serve

本地构建 Docker(大陆用户备选)

GHCR(`ghcr.io`)在大陆无法直接访问。可以从源码本地构建,Dockerfile 已内置清华 apt 源 + npmmirror:

git clone https://github.com/wentorai/Research-Claw.git
cd Research-Claw
docker compose up -d --build

或者在 Docker Desktop → Settings → Resources → Proxies 中配置代理后使用一键脚本。

Docker 连接不上?

1. **验证端口**:`curl http://127.0.0.1:28789/healthz` — 返回 `{"ok":true}` 说明正常 2. **用 `127.0.0.1`,不用 `localhost`**:Windows 上 `localhost` 可能解析到 IPv6,导致连接失败 3. **检查 Docker**:确认 Docker Desktop 状态为 Running,容器状态为绿色 4. **重启**:`docker restart research-claw`

Docker 详细说明

> **Token 认证**:Docker 模式使用 token 认证(容器内无法完成浏览器设备配对)。默认 token `research-claw` 已内置在 Dashboard 中,直接访问 `http://127.0.0.1:28789/` 即可,无需在 URL 中手动添加 token。如需自定义 token,先删除旧容器再手动启动: > ```bash > docker stop research-claw && docker rm research-claw > docker run -d --name research-claw -p 127.0.0.1:28789:28789 \ > -e OPENCLAW_GATEWAY_TOKEN=your-token \ > -v rc-config:/app/config -v rc-data:/app/.research-claw -v rc-workspace:/app/workspace -v rc-state:/root/.openclaw \ > ghcr.io/wentorai/research-claw:latest > ``` > > **数据持久化**:配置、数据库、工作区、会话历史挂载在具名 volume(`rc-config`、`rc-data`、`rc-workspace`、`rc-state`),容器删除后数据不丢失。 > > **LLM API 代理**:如果你的 LLM API(如 OpenAI)需要代理访问,在 Docker Desktop → Settings → Resources → Proxies 中配置 HTTP/HTTPS 代理即可。本地构建用户也可在 `docker-compose.yml` 中取消 `HTTP_PROXY` / `HTTPS_PROXY` 注释。

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 754 lines · 9 findings marked
  1. <div align="center">
  2. <img src="assets/logo.png" width="200" alt="科研龙虾 · Research-Claw" />
  3. # 科研龙虾 · Research-Claw
  4. **AI 时代,谁还不能是个导师了?**
  5. 你做导师,科研龙虾做团队。24/7 本地运行,一切产出专属于你。
  6. [![Version](https://img.shields.io/badge/version-v0.8.3-EF4444?style=flat-square&logo=github)](https://github.com/wentorai/Research-Claw/releases)
  7. [![License](https://img.shields.io/badge/license-BSL_1.1-3B82F6?style=flat-square)](LICENSE)
  8. [![Node](https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org)
  9. [![Platform](https://img.shields.io/badge/platform-macOS_%7C_Windows_%7C_Linux-lightgrey?style=flat-square)](#)
  10. [![Skills](https://img.shields.io/badge/skills-433-EF4444?style=flat-square)](https://www.npmjs.com/package/@wentorai/research-plugins)
  11. [🌐 wentor.ai](https://wentor.ai) · [🇬🇧 English](README.en.md) · [📖 文档](docs/00-reference-map.md) · [🪲 问题反馈](https://github.com/wentorai/Research-Claw/issues)
  12. </div>
  13. ---
  14. > Windows 用户 → [Docker 一键部署](#docker-一键安装macos--linux--windows-通用)(推荐)或 [WSL2 手动安装](WINDOWS_INSTALL.md)
  15. ---
  16. > 下方指令适用于 macOS 和 Linux(Ubuntu)
  17. >
  18. > **同一条命令:首次安装 · 版本更新 · 重新启动**
  19. ```bash
  20. curl -fsSL https://wentor.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 32 on GitHub
  21. ```
  22. ---
  23. ## 这是什么
  24. 会定义下一个时代的研究者,不该把时间耗在排版参考文献上。凌晨两点独自面对屏幕的研究生,值得拥有和顶级实验室一样的科研基础设施。
  25. 科研龙虾完全运行在你的本机。它替你精读论文,在你入睡时盯着 arXiv,帮你起草方法论、设计实验、管理引文、生成图表,用你的口吻写作——而不是它的。
  26. **你的论文库、笔记、实验数据,全部存在你自己的机器上。唯一的外部依赖是你选择的大模型 API。**
  27. <div align="center">
  28. [📖 使用指南(飞书文档)](https://thesisagent.feishu.cn/docx/EN1Odi3dMoAPW2xkwWVcCAybnFg)
  29. 扫码加入**科研龙虾 · WentorOS** 微信群
  30. <img src="assets/community-qr.jpg" width="260" alt="微信群二维码" />
  31. 本群仅用于开发者与贡献者交流讨论。如有问题请直接提 [Issue](https://github.com/wentorai/Research-Claw/issues)
  32. </div>
  33. ---
  34. ## 六个场景
  35. ### 让 Zotero 开口说话
  36. > 你:Zotero「未分类」堆了 200 多篇,帮我按主题分类,每篇加一句话摘要
  37. > 龙虾:已读取 217 篇,聚类分析中……建议分 6 组:LLM Reasoning (43) · Agent (38) · RAG (31) · Multimodal (28) · Eval (19) · Others (58),可以吗?
  38. > 你:可以,Others 超 10 篇同主题的再拆
  39. > 龙虾:✓ 已分到 8 个 Collection · 每篇已加摘要 · 已同步 Zotero
  40. 双向联动 Zotero / EndNote:自动分类、批注摘要、BibTeX 导出,对话式管理整个文献库。
  41. <img src="assets/screenshots/zotero-import.jpg" alt="Zotero 文献导入" width="100%" />
  42. ---
  43. ### 组会材料,自动生成
  44. 每周五早 8 点,自动汇总一周研究进展,生成汇报材料,通过 **Telegram / 飞书 / QQ / 钉钉** 发到你手机。你醒来就能看到,一行命令都不用敲。
  45. ---
  46. ### 论文写作:从空白页到初稿
  47. > 你:开始写「Multi-Agent Debate for Factual Reasoning」,先构建框架,再把 Related Work 写了
  48. > 龙虾:基于 proposal + 实验笔记生成框架:1. Intro · 2. Related Work · 3. Method · 4. Experiments · 5. Conclusion,要调整吗?
  49. > 你:2.3 改成 Multi-Agent Collaboration & Consensus
  50. > 龙虾:✓ Related Work 初稿完成(2,800 词 · 47 篇引用)· 已保存至 ~/research/paper/02_related.md · BibTeX 已同步 references.bib
  51. ---
  52. ### 7×24 科研雷达 × IM 推送
  53. 设置追踪关键词、学者、期刊,科研龙虾在后台持续扫描 arXiv、OpenAlex 等学术数据库。有重要更新第一时间推送到你的 Telegram / 飞书 / QQ,你不在电脑前也不会错过。
  54. <img src="assets/screenshots/telegram.jpg" alt="Telegram 连接 × 科研雷达" width="100%" />
  55. ---
  56. ### 邮件:说想法,它发送
  57. > 你:给 Yann LeCun 发邮件,说我们正在复现他的 XXX 论文,遇到一个问题,想请教……语气正式但不生硬
  58. > 龙虾:[起草完毕,请确认后发送]
  59. 起草、确认、发送,全在对话里完成。语气随时可调。
  60. ---
  61. ### 本地 GPU,自动复现论文
  62. > 你:帮我跑一下 arxiv:2406.12345 的实验
  63. > 龙虾:正在 clone 仓库,配置 conda 环境……遇到 CUDA 版本不兼容,已自动切换,正在重试……✓ 实验完成,结果保存至 results/
  64. 卡住了自己调试,搞不定给作者发邮件。
  65. **真实案例:HiF8 量化实验** —— 以下截图来自一次实际的 Wan2.1 视频生成模型量化实验推进过程。
  66. #### 自主推进实验
  67. 龙虾每 10 分钟自动汇报:环境验证(GPU / CUDA / PyTorch 全链路检查)→ 逐个运行实验 → 记录遇到的问题与解决方案 → 制定下一步计划。你只需要看汇报,不需要手动执行任何命令。
  68. <table>
  69. <tr>
  70. <td width="50%"><img src="assets/screenshots/实验推进.png" alt="实验推进 — 环境验证与阶段汇总" /></td>
  71. <td width="50%"><img src="assets/screenshots/模型准备.PNG" alt="模型准备 — 问题解决与下一步计划" /></td>
  72. </tr>
  73. <tr>
  74. <td align="center"><sub>30 分钟完整汇总 — GPU A800 环境全绿,已完成 2 个实验</sub></td>
  75. <td align="center"><sub>自动排障(5 个问题全部自行解决)并制定后续计划</sub></td>
  76. </tr>
  77. </table>
  78. #### 遇到阻塞,主动找你决策
  79. 当模型下载被 HuggingFace 限速(~1MB/s,预计 95 分钟)时,龙虾不会傻等——它发出紧急汇报,分析根因,提出三个方案并给出推荐,等你拍板后继续执行。
  80. <table>
  81. <tr>
  82. <td width="50%"><img src="assets/screenshots/与人交互寻求帮助.png" alt="紧急汇报 — 下载阻塞" /></td>
  83. <td width="50%"><img src="assets/screenshots/与人交互给人方案.png" alt="三选一方案 — 推荐 B" /></td>
  84. </tr>
  85. <tr>
  86. <td align="center"><sub>检测到严重阻塞,主动发起紧急汇报</sub></td>
  87. <td align="center"><sub>给出 A/B/C 三个方案,推荐 B(先用小模型验证流程)</sub></td>
  88. </tr>
  89. </table>
  90. > **Human-in-the-Loop 原则**:涉及外部凭证(API Token)、不可逆操作、或需要资源决策时,龙虾不会擅自行动,而是带着分析和方案来找你——你做导师,它做执行。
  91. ---
  92. ## Dashboard
  93. 大多数本地 AI Agent 的界面是一个聊天框加几个按钮。科研龙虾不是。
  94. 我们为学术工作流专门设计了一套 Dashboard,这是目前所有本地科研 AI 中功能和设计最完整的界面,支持暖色 Paper 与暗色 Terminal 双主题切换。
  95. <table>
  96. <tr>
  97. <td width="50%"><img src="assets/screenshots/library.jpg" alt="文献库面板" /></td>
  98. <td width="50%"><img src="assets/screenshots/tasks.jpg" alt="任务管理面板" /></td>
  99. </tr>
  100. <tr>
  101. <td align="center"><sub>文献库 — 搜索、引用、一键打开 PDF</sub></td>
  102. <td align="center"><sub>任务看板 — Agent / Human 任务分层管理</sub></td>
  103. </tr>
  104. </table>
  105. | 面板 | 功能 |
  106. |:--|:--|
  107. | **Chat 对话** | 对话主界面 · 6 种结构化卡片(论文 / 任务 / 进度 / 审批 / 文件 / 监控摘要)· 文件与文件夹拖拽引用 · 首轮自动命名 · LaTeX 公式渲染 |
  108. | **文献库** | 全文检索 · 标签 · 批注 · 引用图谱 · 阅读统计 |
  109. | **工作区** | 文件操作与版本历史,Git 追踪每一次变更 |
  110. | **论文评审** *(新)* | 结构化拆解论文优缺点,生成评审结论卡片 |
  111. | **任务** | Agent / Human 任务分层 · 四级优先级 · 48h 截止日期预警 |
  112. | **监控** | 追踪关键词 / 学者 / 期刊 · 自动化任务配置 · IM 推送 |
  113. | **质量管控** *(新)* | 可独立配置的审稿模型异步复审回答(详见下文) |
  114. | **扩展** *(新)* | IM 通道 / 技能 / MCP 管理 · 微信扫码登录 |
  115. | **设置** | Setup Wizard · API 协议探针一键识别端点 · 端点级上下文窗口调参 · 全程浏览器配置 |
  116. 技术规格:React 18 + Vite 6 + Ant Design 5 + Zustand 5,中英双语,2200+ Dashboard 测试,TypeScript 零报错,响应式支持桌面 / 平板 / 浮窗三种模式。
  117. ### 质量管控:给你的 AI 配一个审稿人
  118. 科研最怕「一本正经地胡说」。**质量管控**会异步复审主模型的回答,把发现、建议修正和审计状态持久化到 Supervisor 面板;它不会阻塞或悄悄替换已经发出的回答。危险工具另有同步确定性安全规则与有界深审,确认危险时可直接阻断或请求人工审批。审稿模型可独立配置,也可继承主模型;引用存在性联网核验默认关闭,需要用户主动开启。
  119. ---
  120. ## 技能与集成
  121. 科研龙虾内置 **433 个学术技能**(安装时自动配置,无需手动操作),覆盖科研全流程:
  122. | 类别 | 技能数 | 典型能力 |
  123. |:--|:--|:--|
  124. | 学科领域 | 147 | 16+ 个学科,从 CS 到法学到生物 |
  125. | 文献检索 | 80 | 多库联搜 · 全文获取 · 文献追踪 |
  126. | 学术写作 | 62 | 论文各章节 · LaTeX · 审稿意见回复 |
  127. | 研究方法 | 52 | DID · RDD · IV · 元分析 · 系统综述 |
  128. | 效率工具 | 48 | Terminal · Jupyter · 文档处理(Office → Markdown)|
  129. | 数据分析 | 44 | Python · R · STATA · 可视化 · 面板数据 |
  130. **34 个 Agent 工具**(分布在 18 个 API 模块)直连学术数据库:arXiv · OpenAlex · CrossRef · PubMed · Unpaywall · Europe PMC · DBLP · DOAJ 等
  131. **150 个 MCP 配置**即插即用:
  132. - **文献管理**:Zotero · EndNote · Mendeley
  133. - **IM 推送**:Telegram · 飞书 · QQ · 钉钉 · Slack(在你惯用的 IM 里收到科研提醒)
  134. - **开发工具**:GitHub · Jupyter · VSCode
  135. - **AI 服务**:OpenAI · Claude · 各类国内模型 API
  136. ---
  137. ## 架构设计
  138. ```
  139. ┌─────────────────────────────────────────────────────────────────────┐
  140. │ Research-Claw │
  141. │ │
  142. │ L0 workspace/ L2 dashboard/ │
  143. │ ├─ SOUL.md React 18 + Vite 6 │
  144. │ ├─ AGENTS.md Ant Design 5 + Zustand 5 │
  145. │ ├─ TOOLS.md 6 卡片类型 · 8 面板 │
  146. │ ├─ HEARTBEAT.md WebSocket RPC v3 客户端 │
  147. │ └─ (8 bootstrap files) 1024 i18n keys (EN + ZH-CN) │
  148. │ │ │
  149. │ L1 extensions/ │ ws://127.0.0.1:28789 │
  150. │ └─ research-claw-core │ │
  151. │ ├─ 46 tools │ │
  152. │ ├─ 123 WS RPC interfaces │ │
  153. │ └─ 23 SQLite tables + FTS5 ▼ │
  154. │ ╔═══════════════════════════════════════════════════╗ │
  155. │ ║ OpenClaw (npm dependency) ║ │
  156. │ ║ Gateway · WS RPC v3 · Port 28789 ║ │
  157. │ ╚═══════════════════════════════════════════════════╝ │
  158. │ │ │
  159. │ L3 patches/ ▼ │
  160. │ ~20 lines · 7 files @wentorai/research-plugins │
  161. │ 433 skills · 34 tools │
  162. └─────────────────────────────────────────────────────────────────────┘
  163. ```
  164. ### 核心设计决策
  165. | 决策 | 原因 |
  166. |:--|:--|
  167. | **Satellite 而非 Fork** | OpenClaw 作为内置 npm 依赖引入(无需单独安装),上游可随时升级,耦合面控制在 ~20 行 pnpm patch |
  168. | **4 层耦合,从外到内** | L0 文件系统 → L1 插件 SDK → L2 WS RPC → L3 patch,每层独立,可单独替换 |
  169. | **本地优先** | SQLite + WAL 模式,无需数据库服务;数据全在本地,唯一外部依赖是 LLM API |
  170. | **技能 > 裸提示词** | 433 个 SKILL.md 结构化封装学术场景,可按研究方向安装/卸载 |
  171. | **端口与上游错开** | 28789(科研龙虾)vs 18789(OpenClaw 默认),两者可并存 |
  172. | **浏览器配置一切** | 无需编辑配置文件,所有设置通过 Setup Wizard 在浏览器完成 |
  173. ### 安全模型
  174. 四层纵深防御,前三层为代码级硬约束:
  175. ```
  176. ──────────────────────────────────────────────
  177. L1 网络隔离
  178. loopback only · 无远程端口暴露
  179. 无 telemetry · 无云端回传
  180. ──────────────────────────────────────────────
  181. L2 Workspace 沙箱
  182. 原生 write/edit 工具由 config 层禁用
  183. 插件写文件 = 强制路径校验(拒绝 ../)
  184. 原生 read 保持开放(可读论文/代码)
  185. ──────────────────────────────────────────────
  186. L3 命令执行防护(before_tool_call hook)
  187. 拦截:rm -rf / · dd of=/dev/ · fork bomb
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 267 on GitHub
  188. 放行:python · git · npm · 单文件 rm
  189. ──────────────────────────────────────────────
  190. L4 Git 版本控制备份
  191. workspace 变更自动提交(5s debounce)
  192. 纯本地 · 无 push · 支持全历史回滚
  193. ──────────────────────────────────────────────
  194. L+ 提示词级协议(软约束)
  195. SOUL.md:禁止伪造引用/数据
  196. AGENTS.md:不可逆操作需 Human-in-Loop
  197. ──────────────────────────────────────────────
  198. ```
  199. ---
  200. ## 快速上手
  201. ### 系统要求
  202. | 平台 | 方案 | 依赖 |
  203. |:--|:--|:--|
  204. | macOS / Linux / WSL2 | 一键安装脚本(推荐) | Git · Node.js 22(均自动安装) |
  205. | macOS / Linux / WSL2 | 手动安装(源码) | Git · Node.js 22+ · [pnpm](https://pnpm.io/installation) 9 |
  206. | macOS / Linux / Windows | Docker 一键安装 | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
  207. 所有平台均需 LLM API Key(推荐 Anthropic Claude / OpenAI,支持国内中转 API)。
  208. > **不需要单独安装 OpenClaw。** 科研龙虾已内置 OpenClaw 和全部学术技能插件,安装脚本 / Docker 会自动完成所有配置。如果你已有独立安装的 OpenClaw,也可以只安装技能插件:`openclaw plugins install @wentorai/research-plugins`,但推荐完整安装以获得 Dashboard 和全部功能。
  209. ### 安装
  210. **macOS / Linux — 源码一键安装(推荐):**
  211. ```bash
  212. curl -fsSL https://wentor.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 301 on GitHub
  213. ```
  214. #### Docker 一键安装(macOS / Linux / Windows 通用)
  215. 先安装 [Docker Desktop](https://docs.docker.com/desktop/),确保启动后托盘显示 Running,然后:
  216. ```bash
  217. # macOS / Linux
  218. curl -fsSL https://wentor.ai/docker-install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 310 on GitHub
  219. ```
  220. ```powershell
  221. # Windows PowerShell
  222. irm https://wentor.ai/docker-install.ps1 | iex
  223. ```
  224. > 脚本自动完成:检测 Docker → 拉取最新镜像 → 保留旧容器作为回退 → 启动并验活 → 打开浏览器。新版本未能正常启动时会自动恢复旧版本。
  225. > 重复运行即可更新到最新版本,数据不丢失(持久化在 Docker named volumes 中)。
  226. 安装完成后浏览器自动打开 `http://127.0.0.1:28789`,在 **Setup Wizard** 中配置 API Key,无需编辑任何配置文件。安装、更新和 `pnpm serve` 启动时都会在终端显示当前 Research-Claw、OpenClaw 与代码版本。
  227. <details>
  228. <summary><b>手动安装 / 大陆网络 / 故障排查</b></summary>
  229. #### 手动安装(源码)
  230. > 需要 Git、Node.js 22+ 和 [pnpm](https://pnpm.io/installation) 9。一键脚本会自动安装这些依赖,手动安装需要自行准备。
  231. ```bash
  232. git clone https://github.com/wentorai/Research-Claw.git
  233. cd Research-Claw # ⚠️ 必须进入项目目录,否则 pnpm install 会报错
  234. pnpm install && pnpm build
  235. cp config/openclaw.example.json config/openclaw.json
  236. pnpm serve
  237. ```
  238. #### 本地构建 Docker(大陆用户备选)
  239. GHCR(`ghcr.io`)在大陆无法直接访问。可以从源码本地构建,Dockerfile 已内置清华 apt 源 + npmmirror:
  240. ```bash
  241. git clone https://github.com/wentorai/Research-Claw.git
  242. cd Research-Claw
  243. docker compose up -d --build
  244. ```
  245. 或者在 Docker Desktop → Settings → Resources → Proxies 中配置代理后使用一键脚本。
  246. #### Docker 连接不上?
  247. 1. **验证端口**:`curl http://127.0.0.1:28789/healthz` — 返回 `{"ok":true}` 说明正常
  248. 2. **用 `127.0.0.1`,不用 `localhost`**:Windows 上 `localhost` 可能解析到 IPv6,导致连接失败
  249. 3. **检查 Docker**:确认 Docker Desktop 状态为 Running,容器状态为绿色
  250. 4. **重启**:`docker restart research-claw`
  251. #### Docker 详细说明
  252. > **Token 认证**:Docker 模式使用 token 认证(容器内无法完成浏览器设备配对)。默认 token `research-claw` 已内置在 Dashboard 中,直接访问 `http://127.0.0.1:28789/` 即可,无需在 URL 中手动添加 token。如需自定义 token,先删除旧容器再手动启动:
  253. > ```bash
  254. > docker stop research-claw && docker rm research-claw
  255. > docker run -d --name research-claw -p 127.0.0.1:28789:28789 \
  256. > -e OPENCLAW_GATEWAY_TOKEN=your-token \
  257. > -v rc-config:/app/config -v rc-data:/app/.research-claw -v rc-workspace:/app/workspace -v rc-state:/root/.openclaw \
  258. > ghcr.io/wentorai/research-claw:latest
  259. > ```
  260. >
  261. > **数据持久化**:配置、数据库、工作区、会话历史挂载在具名 volume(`rc-config`、`rc-data`、`rc-workspace`、`rc-state`),容器删除后数据不丢失。
  262. >
  263. > **LLM API 代理**:如果你的 LLM API(如 OpenAI)需要代理访问,在 Docker Desktop → Settings → Resources → Proxies 中配置 HTTP/HTTPS 代理即可。本地构建用户也可在 `docker-compose.yml` 中取消 `HTTP_PROXY` / `HTTPS_PROXY` 注释。
  264. </details>
  265. ### 常用命令
  266. ```bash
  267. pnpm serve # 自动选择:安装用户安静启动,源码工作区开发启动
  268. pnpm serve:user # 显式用户模式:终端 error,文件 info
  269. pnpm serve:developer # 显式开发模式:终端与文件均为 debug
  270. pnpm support # 一次性排障:debug 启动;退出时生成脱敏诊断包
  271. pnpm start # 单次启动(不自动重启)
  272. pnpm dev # 开发模式(Gateway debug + Dashboard HMR)
  273. pnpm test # 运行单元测试
  274. pnpm health # 检查运行状态
  275. pnpm backup # 备份数据库
  276. ```
  277. > `pnpm serve` 是推荐的日常启动方式。安装器会写入本机安装标记,因此安装用户与源码开发者即使运行同一命令,也会稳定得到各自的日志体验。`pnpm support` 只影响本次进程,不修改 active config;按 `Ctrl+C` 退出后自动恢复日常等级并生成脱敏诊断包。
  278. ### 斜杠命令
  279. 在对话输入框中输入 `/` 即可触发命令联想菜单,支持键盘导航(↑↓ 选择,Enter 确认,Esc 关闭)。
  280. | 命令 | 说明 |
  281. |:--|:--|
  282. | `/compact` | 压缩会话上下文;默认优先保留科研目标、证据、数值条件、方法与引用(提高保留优先级,不保证完全无损) |
  283. | `/model [name]` | 查看或切换当前模型 |
  284. | `/think [level]` | 设置思考级别(off / low / medium / high) |
  285. | `/fast [on\|off]` | 切换快速模式 |
  286. | `/verbose [on\|off\|full]` | 切换 Agent 回复详情;不改变 Gateway、启动器或 Dashboard 通知等级 |
  287. | `/usage` | 查看当前会话 Token 用量 |
  288. | `/help` | 显示所有可用命令 |
  289. | `/stop` | 停止当前运行 |
  290. | `/clear` | 清空聊天记录 |
  291. | `/new` | 开始新会话 |
  292. ### 更新
  293. ```bash
  294. curl -fsSL https://wentor.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 410 on GitHub
  295. ```
  296. ### 数据迁移(整机搬家)
  297. 科研龙虾的所有记忆、会话历史、文献库、任务和工作区文件都可以完整迁移到另一台电脑。
  298. <details>
  299. <summary><b>点击展开:完整迁移指南(macOS / Linux / WSL2 / Docker)</b></summary>
  300. #### 数据在哪里?
  301. | 数据 | 路径 | 说明 |
  302. |:--|:--|:--|
  303. | **文献库 / 任务 / 监控** | `~/research-claw/.research-claw/library.db` | SQLite 数据库(核心数据,23 张表 + FTS5 全文索引) |
  304. | **会话历史** | `~/.openclaw/agents/main/sessions/` | 所有聊天记录(.jsonl 文件) |
  305. | **Agent 记忆** | `~/.openclaw/memory/main.sqlite` | 长期记忆 FTS 数据库 |
  306. | **工作区文件** | `~/research-claw/workspace/` | MEMORY.md、.ResearchClaw/、用户上传的文件、Git 历史 |
  307. | **API Key / 模型配置** | `~/research-claw/config/openclaw.json` | 项目级配置(API Key、模型、代理等) |
  308. | **浏览器数据** | `~/.openclaw/browser/` | 已登录的学术网站 session |
  309. | **IM 渠道凭证** | `~/.openclaw/credentials/` | Telegram / 飞书 / QQ 等 token |
  310. > **不需要迁移的**:`node_modules/`、`dashboard/dist/`(重新安装会自动生成);`~/.openclaw/openclaw.json`(全局配置含机器相关绝对路径,新机器上会自动生成);`~/.openclaw/gateway/`、`~/.openclaw/cron/`(运行时数据,自动重建)。
  311. ---
  312. #### 方案一:macOS / Linux 原生安装
  313. **旧机器 — 打包:**
  314. ```bash
  315. # 1. 停止科研龙虾
  316. pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
  317. # 2. 等待 SQLite WAL 落盘(重要!否则可能丢数据)
  318. sleep 3
  319. # 3. 一键打包所有数据
  320. tar -czf ~/rc-migration.tar.gz \
  321. -C / \
  322. "$HOME/.openclaw/agents" \
  323. "$HOME/.openclaw/memory" \
  324. "$HOME/.openclaw/browser" \
  325. "$HOME/.openclaw/credentials" \
  326. -C "$HOME/research-claw" \
  327. .research-claw \
  328. config/openclaw.json \
  329. workspace
  330. ```
  331. **新机器 — 恢复:**
  332. ```bash
  333. # 1. 先在新机器上全新安装(安装脚本会创建目录结构)
  334. curl -fsSL https://wentor.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 464 on GitHub
  335. # 2. 停止刚安装好的科研龙虾
  336. pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
  337. # 3. 将 rc-migration.tar.gz 复制到新机器后解压覆盖
  338. cd /
  339. tar -xzf ~/rc-migration.tar.gz
  340. # 4. 启动
  341. cd ~/research-claw && pnpm serve
  342. ```
  343. > 如果新旧机器的用户名不同(如旧机器 `alice`,新机器 `bob`),解压后需要手动修正 tar 中的路径。可以用分步复制替代:
  344. > ```bash
  345. > # 在新机器上逐个复制
  346. > scp -r old-mac:~/.openclaw/agents/ ~/.openclaw/agents/
  347. > scp -r old-mac:~/.openclaw/memory/ ~/.openclaw/memory/
  348. > scp -r old-mac:~/.openclaw/browser/ ~/.openclaw/browser/
  349. > scp -r old-mac:~/.openclaw/credentials/ ~/.openclaw/credentials/
  350. > scp -r old-mac:~/research-claw/.research-claw/ ~/research-claw/.research-claw/
  351. > scp old-mac:~/research-claw/config/openclaw.json ~/research-claw/config/
  352. > scp -r old-mac:~/research-claw/workspace/ ~/research-claw/workspace/
  353. > ```
  354. ---
  355. #### 方案二:WSL2(Windows)
  356. WSL2 中的路径与 Linux 相同,但传输文件需要通过 Windows 文件系统中转。
  357. **旧机器 — 打包(在 WSL2 终端中):**
  358. ```bash
  359. pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
  360. sleep 3
  361. # 打包到 Windows 桌面(方便拷贝)
  362. tar -czf /mnt/c/Users/$USER/Desktop/rc-migration.tar.gz \
  363. -C / \
  364. "$HOME/.openclaw/agents" \
  365. "$HOME/.openclaw/memory" \
  366. "$HOME/.openclaw/browser" \
  367. "$HOME/.openclaw/credentials" \
  368. -C "$HOME/research-claw" \
  369. .research-claw \
  370. config/openclaw.json \
  371. workspace
  372. ```
  373. **新机器 — 恢复(在 WSL2 终端中):**
  374. ```bash
  375. # 1. 先安装科研龙虾
  376. curl -fsSL https://wentor.ai/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 518 on GitHub
  377. pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
  378. # 2. 将 rc-migration.tar.gz 复制到新机器桌面,然后在 WSL2 中解压
  379. cd /
  380. tar -xzf /mnt/c/Users/$USER/Desktop/rc-migration.tar.gz
  381. # 3. 启动
  382. cd ~/research-claw && pnpm serve
  383. ```
  384. ---
  385. #### 方案三:Docker
  386. Docker 的数据在具名 Volume 中,需要用 `docker run` 导出/导入。
  387. **旧机器 — 导出:**
  388. ```bash
  389. # 1. 停止容器
  390. docker stop research-claw
  391. # 2. 导出 4 个 Volume 到 tar 文件
  392. for vol in rc-config rc-data rc-workspace rc-state; do
  393. docker run --rm -v ${vol}:/data -v ~/:/backup alpine \
  394. tar -czf /backup/${vol}.tar.gz -C /data .
  395. done
  396. # 结果:~/rc-config.tar.gz ~/rc-data.tar.gz ~/rc-workspace.tar.gz ~/rc-state.tar.gz
  397. ```
  398. **新机器 — 导入:**
  399. ```bash
  400. # 1. 先用一键脚本安装(会创建容器和 Volume)
  401. curl -fsSL https://wentor.ai/docker-install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 554 on GitHub
  402. # 2. 停止容器
  403. docker stop research-claw
  404. # 3. 将 4 个 tar.gz 复制到新机器后,逐个导入
  405. for vol in rc-config rc-data rc-workspace rc-state; do
  406. # 清空现有 Volume 内容
  407. docker run --rm -v ${vol}:/data alpine sh -c "rm -rf /data/*"
  408. # 导入旧数据
  409. docker run --rm -v ${vol}:/data -v ~/:/backup alpine \
  410. tar -xzf /backup/${vol}.tar.gz -C /data
  411. done
  412. # 4. 启动
  413. docker start research-claw
  414. ```
  415. Windows Docker 用户:在 PowerShell 中将 `for vol in ...` 替换为逐条执行,Volume 名和命令相同。
  416. ---
  417. #### 迁移后验证
  418. 启动后在 Dashboard 中检查:
  419. - [ ] **文献库**:论文列表、标签、笔记是否完整
  420. - [ ] **任务**:待办事项和截止日期是否存在
  421. - [ ] **工作区**:文件树和版本历史是否正常
  422. - [ ] **设置**:API Key 和模型配置是否保留
  423. - [ ] **对话历史**:点击 `/new` 后能否通过历史会话列表回看之前的聊天
  424. > **如果 API Key 丢失**:进入 Settings 面板重新填写即可,其余数据不受影响。
  425. >
  426. > **如果连接了 Telegram / 飞书等 IM**:迁移后 bot token 会保留,但可能需要在新机器上重新验证网络连通性。
  427. </details>
  428. ---
  429. ## 项目结构
  430. ```
  431. research-claw/
  432. ├── config/ # OpenClaw 配置覆盖层
  433. ├── dashboard/ # React + Vite Dashboard
  434. │ └── src/
  435. │ ├── components/ # TopBar, LeftNav, ChatView, panels, cards
  436. │ ├── gateway/ # WS RPC v3 client + hooks
  437. │ ├── i18n/ # en.json + zh-CN.json
  438. │ ├── stores/ # Zustand stores × 18
  439. │ └── types/ # 6 Card type definitions
  440. ├── extensions/
  441. │ └── research-claw-core/ # 46 tools · 123 RPC · 23 tables
  442. ├── patches/ # pnpm patch (~20 lines, 7 files)
  443. ├── scripts/ # install / health / backup / sync
  444. ├── skills/ # 自定义 SKILL.md 文件
  445. └── workspace/ # Bootstrap files (SOUL.md, AGENTS.md …)
  446. ```
  447. ---
  448. ## 卸载
  449. ### 已有 OpenClaw 用户:恢复原始 OpenClaw
  450. 如果你在安装科研龙虾后遇到以下问题,说明安装脚本修改的全局设置影响了你原有的 OpenClaw:
  451. - `openclaw` 命令启动的是科研龙虾,而非原始 OpenClaw
  452. - 端口被固定为 28789,原始 OpenClaw 无法正常启动
  453. - `openclaw config` 读写的是科研龙虾的配置,而非 `~/.openclaw/openclaw.json`
  454. **修复方法**(两步即可,无需卸载科研龙虾):
  455. ```bash
  456. # 1. 删除 CLI wrapper(安装脚本在 ~/.local/bin/ 创建了指向科研龙虾的启动脚本)
  457. rm -f ~/.local/bin/openclaw
  458. # 2. 清除 shell 配置中的环境变量覆盖
  459. # 查看哪些文件被修改过:
  460. grep -n "OPENCLAW_CONFIG_PATH\|# Research-Claw\|\.local/bin.*Research-Claw" ~/.zshrc ~/.bashrc ~/.bash_profile 2>/dev/null
  461. # 找到带 "Research-Claw" 注释的行,删除即可。
  462. ```
  463. 清理后**重开终端**,`openclaw` 命令即恢复为原始版本。科研龙虾不受影响——通过 `cd ~/research-claw && pnpm serve` 启动即可,`run.sh` 会在进程内自行设置正确的配置路径,两者可以并存。
  464. > **为什么会冲突?** 安装脚本在 `~/.local/bin/openclaw` 创建了一个 wrapper 脚本,并将 `OPENCLAW_CONFIG_PATH` 写入 shell profile,使所有终端中的 `openclaw` 命令都指向科研龙虾的配置(端口 28789 等)。这是为了让纯科研龙虾用户可以在任意目录使用 `openclaw` CLI,但对已有 OpenClaw 安装的用户会造成覆盖。
  465. ### macOS / Linux(源码安装)
  466. ```bash
  467. # 1. 停止运行中的进程
  468. pkill -f "openclaw.*gateway" 2>/dev/null
  469. # 2. 删除项目目录
  470. rm -rf ~/research-claw
  471. # 3. 删除本地数据(数据库、配置、记忆)
  472. rm -rf ~/.research-claw
  473. # 4.(可选)删除 OpenClaw 全局配置
  474. rm -rf ~/.openclaw
  475. # 5. 删除 CLI wrapper 和 shell 环境变量
  476. rm -f ~/.local/bin/openclaw
  477. # 编辑 ~/.zshrc 或 ~/.bashrc,删除包含 OPENCLAW_CONFIG_PATH 和
  478. # "Research-Claw" 注释的行(通常 2-3 行),然后重开终端
  479. # 6.(可选)清除 pnpm 全局缓存
  480. pnpm store prune
  481. ```
  482. ### Docker(macOS / Linux / Windows)
  483. ```bash
  484. # 1. 停止并删除容器
  485. docker stop research-claw && docker rm research-claw
  486. # 2. 删除镜像
  487. docker rmi ghcr.io/wentorai/research-claw:latest
  488. # 3.(可选)删除持久化数据(配置、数据库、工作区)
  489. docker volume rm rc-config rc-data rc-workspace rc-state
  490. ```
  491. Windows PowerShell 命令相同,在 PowerShell 中逐行执行即可。
  492. > **注意**:执行第 3 步将永久删除所有数据(论文库、任务、工作区文件、会话历史)。如需保留数据,跳过此步。
  493. >
  494. > Docker 安装不会修改宿主机的 shell 配置或 CLI wrapper,无需额外清理。
  495. ### WSL2(Windows 手动安装)
  496. ```powershell
  497. # 1. 在 WSL2 中停止并删除(同 Linux 步骤)
  498. wsl -e bash -c "pkill -f 'openclaw.*gateway' 2>/dev/null; rm -rf ~/research-claw ~/.research-claw ~/.openclaw ~/.local/bin/openclaw"
  499. # 2. 清理 shell 环境变量(在 WSL2 Ubuntu 终端中)
  500. wsl -e bash -c "sed -i '/OPENCLAW_CONFIG_PATH/d;/Research-Claw/d' ~/.bashrc 2>/dev/null"
  501. # 3.(可选)如果 WSL2 仅用于科研龙虾,可以完全卸载 WSL 发行版
  502. wsl --unregister Ubuntu
  503. ```
  504. > 卸载 WSL 发行版会删除该发行版内的**所有数据**,请确认无其他用途后再操作。
  505. ---
  506. ## 问题反馈
  507. 遇到 Bug?在 [GitHub Issues](https://github.com/wentorai/Research-Claw/issues) 提交报告,标题格式:`[Bug] 一句话描述`。
  508. **一份有效的 Bug 报告需要四样东西:**
  509. | 要素 | 怎么提供 |
  510. |:--|:--|
  511. | **复现步骤** | 写清楚你做了什么、点了什么、说了什么,让开发者能重现问题 |
  512. | **后端日志** | 从终端 / Docker 复制日志文字(见下方命令),**不要只截图** |
  513. | **浏览器控制台** | `Cmd+Option+J`(macOS)或 `Ctrl+Shift+J`(Windows)打开,复制错误信息 |
  514. | **环境信息** | 系统、安装方式(install.sh / Docker / WSL2)、RC 版本(Dashboard 左下角)、模型 |
  515. > **为什么日志要文字复制?** 截图里的日志无法搜索、无法复制到代码中定位、容易截不全。截图展示界面异常 + 文字复制日志内容,两者配合。
  516. <details>
  517. <summary><b>各平台获取后端日志的命令</b></summary>
  518. ```bash
  519. # macOS / Linux 原生安装
  520. tail -50 ~/.research-claw/logs/openclaw.log
  521. # 一次性 debug 启动;Ctrl+C 退出后生成脱敏诊断包且不改配置
  522. cd ~/research-claw && pnpm support
  523. # Docker(macOS / Linux / Windows)
  524. docker logs --tail 50 research-claw
  525. # WSL2(systemd 服务模式)
  526. journalctl --user -u research-claw --no-pager -n 50
  527. ```
  528. 也可以在 Dashboard → **Settings** → **Logs** 标签中查看和筛选日志。
  529. </details>
  530. 功能建议和讨论请用 [GitHub Discussions](https://github.com/wentorai/Research-Claw/discussions)。
  531. ---
  532. ## 致谢
  533. - [ppt-master](https://github.com/hugohe3/ppt-master) — PPT 生成引擎,为科研龙虾的 PPT 导出功能提供了核心支持
  534. ## 许可证
  535. [BSL 1.1](LICENSE) — 个人及学术研究免费使用。商业用途需单独授权,联系 [help@wentor.ai](mailto:help@wentor.ai)。2030-03-12 自动转为 Apache 2.0 开源。
  536. ---
  537. <div align="center">
  538. <sub>Built with ❤️ by <a href="https://wentor.ai">Wentor AI</a></sub>
  539. </div>
skills/md2pdf-export/scripts/setup-env.sh · Bundled script · 393 lines · 2 findings marked
  1. #!/usr/bin/env bash
  2. # ============================================================================
  3. # md2pdf-export: Environment Setup Script
  4. # Installs Node.js, Puppeteer, and Chrome/Chromium dependencies
  5. # Idempotent — safe to run multiple times
  6. # ============================================================================
  7. set -euo pipefail
  8. # Colors for output
  9. RED='\033[0;31m'
  10. GREEN='\033[0;32m'
  11. YELLOW='\033[1;33m'
  12. BLUE='\033[0;34m'
  13. NC='\033[0m' # No Color
  14. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  15. SKILL_DIR="$(dirname "$SCRIPT_DIR")"
  16. MIN_NODE_VERSION=18
  17. NVM_VERSION="v0.40.1"
  18. # ── Utility functions ────────────────────────────────────────────────────────
  19. log_info() { echo -e "${BLUE}[INFO]${NC} $*"; }
  20. log_ok() { echo -e "${GREEN}[OK]${NC} $*"; }
  21. log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
  22. log_err() { echo -e "${RED}[ERROR]${NC} $*"; }
  23. command_exists() { command -v "$1" &>/dev/null; }
  24. version_gte() {
  25. # Returns 0 if $1 >= $2 (semver major only)
  26. local cur="$1" min="$2"
  27. [ "$cur" -ge "$min" ] 2>/dev/null
  28. }
  29. detect_os() {
  30. if [[ "$OSTYPE" == "darwin"* ]]; then
  31. echo "macos"
  32. elif [ -f /etc/os-release ]; then
  33. . /etc/os-release
  34. case "$ID" in
  35. ubuntu|debian|pop|linuxmint|elementary) echo "debian" ;;
  36. alpine) echo "alpine" ;;
  37. centos|rhel|fedora|rocky|almalinux) echo "rhel" ;;
  38. arch|manjaro) echo "arch" ;;
  39. *) echo "linux-unknown" ;;
  40. esac
  41. else
  42. echo "unknown"
  43. fi
  44. }
  45. detect_container() {
  46. # Detect if running inside Docker/container
  47. if [ -f /.dockerenv ] || grep -qsE '(docker|containerd|kubepods)' /proc/1/cgroup 2>/dev/null; then
  48. echo "true"
  49. else
  50. echo "false"
  51. fi
  52. }
  53. # ── Step 1: Detect environment ───────────────────────────────────────────────
  54. echo ""
  55. echo "============================================================"
  56. echo " md2pdf-export: Environment Setup"
  57. echo "============================================================"
  58. echo ""
  59. OS=$(detect_os)
  60. IN_CONTAINER=$(detect_container)
  61. log_info "Detected OS: $OS"
  62. log_info "In container: $IN_CONTAINER"
  63. # ── Step 2: Install Node.js ──────────────────────────────────────────────────
  64. install_node_nvm() {
  65. log_info "Installing Node.js via nvm..."
  66. # Install nvm if not present
  67. if [ ! -d "$HOME/.nvm" ]; then
  68. log_info "Installing nvm ${NVM_VERSION}..."
  69. curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" | bash
  70. fi
  71. # Source nvm
  72. export NVM_DIR="$HOME/.nvm"
  73. [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
  74. if ! command_exists nvm; then
  75. log_err "nvm installation failed. Try installing Node.js manually."
  76. return 1
  77. fi
  78. nvm install --lts
  79. nvm use --lts
  80. nvm alias default 'lts/*'
  81. log_ok "Node.js $(node -v) installed via nvm"
  82. }
  83. install_node_package_manager() {
  84. case "$OS" in
  85. macos)
  86. if command_exists brew; then
  87. log_info "Installing Node.js via Homebrew..."
  88. brew install node
  89. else
  90. install_node_nvm
  91. fi
  92. ;;
  93. debian)
  94. log_info "Installing Node.js via NodeSource..."
  95. if command_exists sudo; then
  96. sudo apt-get update -qq
  97. sudo apt-get install -y -qq curl
  98. curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 117 on GitHub
  99. sudo apt-get install -y -qq nodejs
  100. else
  101. apt-get update -qq
  102. apt-get install -y -qq curl
  103. curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 122 on GitHub
  104. apt-get install -y -qq nodejs
  105. fi
  106. ;;
  107. alpine)
  108. apk add --no-cache nodejs npm
  109. ;;
  110. rhel)
  111. if command_exists dnf; then
  112. sudo dnf install -y nodejs npm
  113. else
  114. sudo yum install -y nodejs npm
  115. fi
  116. ;;
  117. *)
  118. install_node_nvm
  119. ;;
  120. esac
  121. }
  122. check_node() {
  123. if command_exists node; then
  124. local node_major
  125. node_major=$(node -v | sed 's/v//' | cut -d. -f1)
  126. if version_gte "$node_major" "$MIN_NODE_VERSION"; then
  127. log_ok "Node.js $(node -v) found (>= v${MIN_NODE_VERSION} required)"
  128. return 0
  129. else
  130. log_warn "Node.js $(node -v) is too old (need >= v${MIN_NODE_VERSION})"
  131. return 1
  132. fi
  133. else
  134. log_warn "Node.js not found"
  135. return 1
  136. fi
  137. }
  138. if ! check_node; then
  139. install_node_package_manager
  140. # Re-source in case nvm was used
  141. [ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
  142. if ! check_node; then
  143. log_err "Failed to install Node.js >= v${MIN_NODE_VERSION}"
  144. exit 1
  145. fi
  146. fi
  147. # Ensure npm is available
  148. if ! command_exists npm; then
  149. log_err "npm not found even though Node.js is installed"
  150. exit 1
  151. fi
  152. log_ok "npm $(npm -v) found"
  153. # ── Step 3: Install Chrome/Chromium system dependencies ─────────────────────
  154. install_chrome_deps() {
  155. log_info "Installing Chromium system dependencies..."
  156. case "$OS" in
  157. debian)
  158. local DEPS=(
  159. ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0t64
  160. libatk1.0-0t64 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0t64
  161. libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1
  162. libxfixes3 libxrandr2 xdg-utils wget fonts-noto-cjk
  163. )
  164. # Try with t64 suffix first (Ubuntu 24+), fallback to plain names
  165. if command_exists sudo; then
  166. sudo apt-get update -qq
  167. sudo apt-get install -y -qq "${DEPS[@]}" 2>/dev/null || {
  168. # Fallback for older Ubuntu/Debian without t64 suffix
  169. local DEPS_FALLBACK=(
  170. ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0
  171. libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0
  172. libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1
  173. libxfixes3 libxrandr2 xdg-utils wget fonts-noto-cjk
  174. )
  175. sudo apt-get install -y -qq "${DEPS_FALLBACK[@]}"
  176. }
  177. else
  178. apt-get update -qq
  179. apt-get install -y -qq "${DEPS[@]}" 2>/dev/null || {
  180. local DEPS_FALLBACK=(
  181. ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0
  182. libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0
  183. libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1
  184. libxfixes3 libxrandr2 xdg-utils wget fonts-noto-cjk
  185. )
  186. apt-get install -y -qq "${DEPS_FALLBACK[@]}"
  187. }
  188. fi
  189. ;;
  190. alpine)
  191. apk add --no-cache \
  192. chromium nss freetype harfbuzz ca-certificates ttf-freefont \
  193. font-noto-cjk
  194. export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
  195. export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
  196. ;;
  197. rhel)
  198. if command_exists dnf; then
  199. sudo dnf install -y \
  200. alsa-lib atk cups-libs dbus-libs libdrm mesa-libgbm gtk3 \
  201. nss libXcomposite libXdamage libXfixes libXrandr xdg-utils \
  202. google-noto-sans-cjk-ttc-fonts
  203. fi
  204. ;;
  205. macos)
  206. # macOS: Puppeteer bundles Chromium, no system deps needed
  207. # But install CJK fonts if missing
  208. if command_exists brew; then
  209. brew install --cask font-noto-sans-cjk 2>/dev/null || true
  210. fi
  211. ;;
  212. *)
  213. log_warn "Unknown OS — skipping system dependency installation."
  214. log_warn "If Chrome fails to launch, install Chromium deps manually."
  215. ;;
  216. esac
  217. log_ok "Chrome system dependencies installed"
  218. }
  219. install_chrome_deps
  220. # ── Step 4: Install Puppeteer ────────────────────────────────────────────────
  221. install_puppeteer() {
  222. log_info "Installing puppeteer globally..."
  223. # Set npm global prefix to user space to avoid sudo
  224. local NPM_GLOBAL="$HOME/.npm-global"
  225. mkdir -p "$NPM_GLOBAL"
  226. npm config set prefix "$NPM_GLOBAL"
  227. # Ensure it's in PATH
  228. if [[ ":$PATH:" != *":$NPM_GLOBAL/bin:"* ]]; then
  229. export PATH="$NPM_GLOBAL/bin:$PATH"
  230. # Persist in shell rc
  231. for rc in "$HOME/.bashrc" "$HOME/.zshrc"; do
  232. if [ -f "$rc" ]; then
  233. grep -q 'npm-global/bin' "$rc" 2>/dev/null || \
  234. echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$rc"
  235. fi
  236. done
  237. fi
  238. # Install puppeteer
  239. npm install -g puppeteer 2>&1 | tail -5
  240. log_ok "puppeteer installed globally"
  241. }
  242. check_puppeteer() {
  243. if node -e "require('puppeteer')" 2>/dev/null; then
  244. local pup_ver
  245. pup_ver=$(node -e "console.log(require('puppeteer/package.json').version)" 2>/dev/null)
  246. log_ok "puppeteer v${pup_ver} found"
  247. return 0
  248. else
  249. return 1
  250. fi
  251. }
  252. if ! check_puppeteer; then
  253. install_puppeteer
  254. if ! check_puppeteer; then
  255. log_err "Failed to install puppeteer"
  256. exit 1
  257. fi
  258. fi
  259. # ── Step 5: Install md2pdf.js local dependencies ────────────────────────────
  260. install_skill_deps() {
  261. log_info "Installing md2pdf.js npm dependencies..."
  262. cd "$SKILL_DIR/scripts"
  263. if [ ! -f package.json ]; then
  264. log_warn "No package.json found in scripts/, creating one..."
  265. cat > package.json <<'PJSON'
  266. {
  267. "name": "md2pdf-export",
  268. "version": "1.0.0",
  269. "private": true,
  270. "dependencies": {
  271. "markdown-it": "^14.0.0",
  272. "markdown-it-anchor": "^9.0.0",
  273. "markdown-it-footnote": "^4.0.0",
  274. "markdown-it-highlightjs": "^4.1.0",
  275. "markdown-it-texmath": "^1.0.0",
  276. "markdown-it-toc-done-right": "^4.2.0",
  277. "katex": "^0.16.0",
  278. "gray-matter": "^4.0.3",
  279. "puppeteer": ">=21.0.0"
  280. }
  281. }
  282. PJSON
  283. fi
  284. npm install --prefer-offline 2>&1 | tail -3
  285. log_ok "md2pdf.js dependencies installed"
  286. cd - > /dev/null
  287. }
  288. install_skill_deps
  289. # ── Step 6: Verify everything works ─────────────────────────────────────────
  290. log_info "Running smoke test..."
  291. CHROME_LAUNCH_ARGS=""
  292. if [ "$IN_CONTAINER" = "true" ]; then
  293. CHROME_LAUNCH_ARGS="--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage"
  294. fi
  295. SMOKE_RESULT=$(node -e "
  296. const puppeteer = require('puppeteer');
  297. (async () => {
  298. try {
  299. const args = '${CHROME_LAUNCH_ARGS}'.split(' ').filter(Boolean);
  300. const browser = await puppeteer.launch({
  301. headless: 'new',
  302. args: args
  303. });
  304. const page = await browser.newPage();
  305. await page.setContent('<h1>Smoke Test OK</h1>');
  306. const pdf = await page.pdf({ format: 'A4' });
  307. console.log('PDF_SIZE=' + pdf.length);
  308. await browser.close();
  309. console.log('SMOKE_OK');
  310. } catch (e) {
  311. console.error('SMOKE_FAIL: ' + e.message);
  312. process.exit(1);
  313. }
  314. })();
  315. " 2>&1) || true
  316. if echo "$SMOKE_RESULT" | grep -q "SMOKE_OK"; then
  317. PDF_SIZE=$(echo "$SMOKE_RESULT" | grep "PDF_SIZE" | cut -d= -f2)
  318. log_ok "Smoke test passed (PDF generated: ${PDF_SIZE} bytes)"
  319. else
  320. log_err "Smoke test failed:"
  321. echo "$SMOKE_RESULT"
  322. echo ""
  323. log_warn "Common fixes:"
  324. log_warn " - Docker: ensure --no-sandbox is enabled"
  325. log_warn " - Missing libs: run 'npx puppeteer browsers install chrome'"
  326. log_warn " - Set PUPPETEER_EXECUTABLE_PATH to an existing Chrome binary"
  327. exit 1
  328. fi
  329. # ── Summary ──────────────────────────────────────────────────────────────────
  330. echo ""
  331. echo "============================================================"
  332. echo " ✅ md2pdf-export: Environment Ready"
  333. echo "============================================================"
  334. echo ""
  335. echo " Node.js: $(node -v)"
  336. echo " npm: $(npm -v)"
  337. echo " Puppeteer: $(node -e "console.log(require('puppeteer/package.json').version)" 2>/dev/null || echo 'unknown')"
  338. echo " OS: $OS"
  339. echo " Container: $IN_CONTAINER"
  340. echo ""
  341. echo " Usage:"
  342. echo " node ${SKILL_DIR}/scripts/md2pdf.js input.md"
  343. echo " node ${SKILL_DIR}/scripts/md2pdf.js input.md --type png"
  344. echo " node ${SKILL_DIR}/scripts/md2pdf.js input.md -o output.pdf"
  345. echo ""
  346. echo "============================================================"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.