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.
Badge for your README
Markdown
[](/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
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
- <div align="center">
- <img src="assets/logo.png" width="200" alt="科研龙虾 · Research-Claw" />
- # 科研龙虾 · Research-Claw
- **AI 时代,谁还不能是个导师了?**
- 你做导师,科研龙虾做团队。24/7 本地运行,一切产出专属于你。
- [](https://github.com/wentorai/Research-Claw/releases)
- [](LICENSE)
- [](https://nodejs.org)
- [](#)
- [](https://www.npmjs.com/package/@wentorai/research-plugins)
- [🌐 wentor.ai](https://wentor.ai) · [🇬🇧 English](README.en.md) · [📖 文档](docs/00-reference-map.md) · [🪲 问题反馈](https://github.com/wentorai/Research-Claw/issues)
- </div>
- ---
- > Windows 用户 → [Docker 一键部署](#docker-一键安装macos--linux--windows-通用)(推荐)或 [WSL2 手动安装](WINDOWS_INSTALL.md)
- ---
- > 下方指令适用于 macOS 和 Linux(Ubuntu)
- >
- > **同一条命令:首次安装 · 版本更新 · 重新启动**
- ```bash
- 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
- ```
- ---
- ## 这是什么
- 会定义下一个时代的研究者,不该把时间耗在排版参考文献上。凌晨两点独自面对屏幕的研究生,值得拥有和顶级实验室一样的科研基础设施。
- 科研龙虾完全运行在你的本机。它替你精读论文,在你入睡时盯着 arXiv,帮你起草方法论、设计实验、管理引文、生成图表,用你的口吻写作——而不是它的。
- **你的论文库、笔记、实验数据,全部存在你自己的机器上。唯一的外部依赖是你选择的大模型 API。**
- <div align="center">
- [📖 使用指南(飞书文档)](https://thesisagent.feishu.cn/docx/EN1Odi3dMoAPW2xkwWVcCAybnFg)
- 扫码加入**科研龙虾 · WentorOS** 微信群
- <img src="assets/community-qr.jpg" width="260" alt="微信群二维码" />
- 本群仅用于开发者与贡献者交流讨论。如有问题请直接提 [Issue](https://github.com/wentorai/Research-Claw/issues)
- </div>
- ---
- ## 六个场景
- ### 让 Zotero 开口说话
- > 你:Zotero「未分类」堆了 200 多篇,帮我按主题分类,每篇加一句话摘要
- > 龙虾:已读取 217 篇,聚类分析中……建议分 6 组:LLM Reasoning (43) · Agent (38) · RAG (31) · Multimodal (28) · Eval (19) · Others (58),可以吗?
- > 你:可以,Others 超 10 篇同主题的再拆
- > 龙虾:✓ 已分到 8 个 Collection · 每篇已加摘要 · 已同步 Zotero
- 双向联动 Zotero / EndNote:自动分类、批注摘要、BibTeX 导出,对话式管理整个文献库。
- <img src="assets/screenshots/zotero-import.jpg" alt="Zotero 文献导入" width="100%" />
- ---
- ### 组会材料,自动生成
- 每周五早 8 点,自动汇总一周研究进展,生成汇报材料,通过 **Telegram / 飞书 / QQ / 钉钉** 发到你手机。你醒来就能看到,一行命令都不用敲。
- ---
- ### 论文写作:从空白页到初稿
- > 你:开始写「Multi-Agent Debate for Factual Reasoning」,先构建框架,再把 Related Work 写了
- > 龙虾:基于 proposal + 实验笔记生成框架:1. Intro · 2. Related Work · 3. Method · 4. Experiments · 5. Conclusion,要调整吗?
- > 你:2.3 改成 Multi-Agent Collaboration & Consensus
- > 龙虾:✓ Related Work 初稿完成(2,800 词 · 47 篇引用)· 已保存至 ~/research/paper/02_related.md · BibTeX 已同步 references.bib
- ---
- ### 7×24 科研雷达 × IM 推送
- 设置追踪关键词、学者、期刊,科研龙虾在后台持续扫描 arXiv、OpenAlex 等学术数据库。有重要更新第一时间推送到你的 Telegram / 飞书 / QQ,你不在电脑前也不会错过。
- <img src="assets/screenshots/telegram.jpg" alt="Telegram 连接 × 科研雷达" width="100%" />
- ---
- ### 邮件:说想法,它发送
- > 你:给 Yann LeCun 发邮件,说我们正在复现他的 XXX 论文,遇到一个问题,想请教……语气正式但不生硬
- > 龙虾:[起草完毕,请确认后发送]
- 起草、确认、发送,全在对话里完成。语气随时可调。
- ---
- ### 本地 GPU,自动复现论文
- > 你:帮我跑一下 arxiv:2406.12345 的实验
- > 龙虾:正在 clone 仓库,配置 conda 环境……遇到 CUDA 版本不兼容,已自动切换,正在重试……✓ 实验完成,结果保存至 results/
- 卡住了自己调试,搞不定给作者发邮件。
- **真实案例:HiF8 量化实验** —— 以下截图来自一次实际的 Wan2.1 视频生成模型量化实验推进过程。
- #### 自主推进实验
- 龙虾每 10 分钟自动汇报:环境验证(GPU / CUDA / PyTorch 全链路检查)→ 逐个运行实验 → 记录遇到的问题与解决方案 → 制定下一步计划。你只需要看汇报,不需要手动执行任何命令。
- <table>
- <tr>
- <td width="50%"><img src="assets/screenshots/实验推进.png" alt="实验推进 — 环境验证与阶段汇总" /></td>
- <td width="50%"><img src="assets/screenshots/模型准备.PNG" alt="模型准备 — 问题解决与下一步计划" /></td>
- </tr>
- <tr>
- <td align="center"><sub>30 分钟完整汇总 — GPU A800 环境全绿,已完成 2 个实验</sub></td>
- <td align="center"><sub>自动排障(5 个问题全部自行解决)并制定后续计划</sub></td>
- </tr>
- </table>
- #### 遇到阻塞,主动找你决策
- 当模型下载被 HuggingFace 限速(~1MB/s,预计 95 分钟)时,龙虾不会傻等——它发出紧急汇报,分析根因,提出三个方案并给出推荐,等你拍板后继续执行。
- <table>
- <tr>
- <td width="50%"><img src="assets/screenshots/与人交互寻求帮助.png" alt="紧急汇报 — 下载阻塞" /></td>
- <td width="50%"><img src="assets/screenshots/与人交互给人方案.png" alt="三选一方案 — 推荐 B" /></td>
- </tr>
- <tr>
- <td align="center"><sub>检测到严重阻塞,主动发起紧急汇报</sub></td>
- <td align="center"><sub>给出 A/B/C 三个方案,推荐 B(先用小模型验证流程)</sub></td>
- </tr>
- </table>
- > **Human-in-the-Loop 原则**:涉及外部凭证(API Token)、不可逆操作、或需要资源决策时,龙虾不会擅自行动,而是带着分析和方案来找你——你做导师,它做执行。
- ---
- ## Dashboard
- 大多数本地 AI Agent 的界面是一个聊天框加几个按钮。科研龙虾不是。
- 我们为学术工作流专门设计了一套 Dashboard,这是目前所有本地科研 AI 中功能和设计最完整的界面,支持暖色 Paper 与暗色 Terminal 双主题切换。
- <table>
- <tr>
- <td width="50%"><img src="assets/screenshots/library.jpg" alt="文献库面板" /></td>
- <td width="50%"><img src="assets/screenshots/tasks.jpg" alt="任务管理面板" /></td>
- </tr>
- <tr>
- <td align="center"><sub>文献库 — 搜索、引用、一键打开 PDF</sub></td>
- <td align="center"><sub>任务看板 — Agent / Human 任务分层管理</sub></td>
- </tr>
- </table>
- | 面板 | 功能 |
- |:--|:--|
- | **Chat 对话** | 对话主界面 · 6 种结构化卡片(论文 / 任务 / 进度 / 审批 / 文件 / 监控摘要)· 文件与文件夹拖拽引用 · 首轮自动命名 · LaTeX 公式渲染 |
- | **文献库** | 全文检索 · 标签 · 批注 · 引用图谱 · 阅读统计 |
- | **工作区** | 文件操作与版本历史,Git 追踪每一次变更 |
- | **论文评审** *(新)* | 结构化拆解论文优缺点,生成评审结论卡片 |
- | **任务** | Agent / Human 任务分层 · 四级优先级 · 48h 截止日期预警 |
- | **监控** | 追踪关键词 / 学者 / 期刊 · 自动化任务配置 · IM 推送 |
- | **质量管控** *(新)* | 可独立配置的审稿模型异步复审回答(详见下文) |
- | **扩展** *(新)* | IM 通道 / 技能 / MCP 管理 · 微信扫码登录 |
- | **设置** | Setup Wizard · API 协议探针一键识别端点 · 端点级上下文窗口调参 · 全程浏览器配置 |
- 技术规格:React 18 + Vite 6 + Ant Design 5 + Zustand 5,中英双语,2200+ Dashboard 测试,TypeScript 零报错,响应式支持桌面 / 平板 / 浮窗三种模式。
- ### 质量管控:给你的 AI 配一个审稿人
- 科研最怕「一本正经地胡说」。**质量管控**会异步复审主模型的回答,把发现、建议修正和审计状态持久化到 Supervisor 面板;它不会阻塞或悄悄替换已经发出的回答。危险工具另有同步确定性安全规则与有界深审,确认危险时可直接阻断或请求人工审批。审稿模型可独立配置,也可继承主模型;引用存在性联网核验默认关闭,需要用户主动开启。
- ---
- ## 技能与集成
- 科研龙虾内置 **433 个学术技能**(安装时自动配置,无需手动操作),覆盖科研全流程:
- | 类别 | 技能数 | 典型能力 |
- |:--|:--|:--|
- | 学科领域 | 147 | 16+ 个学科,从 CS 到法学到生物 |
- | 文献检索 | 80 | 多库联搜 · 全文获取 · 文献追踪 |
- | 学术写作 | 62 | 论文各章节 · LaTeX · 审稿意见回复 |
- | 研究方法 | 52 | DID · RDD · IV · 元分析 · 系统综述 |
- | 效率工具 | 48 | Terminal · Jupyter · 文档处理(Office → Markdown)|
- | 数据分析 | 44 | Python · R · STATA · 可视化 · 面板数据 |
- **34 个 Agent 工具**(分布在 18 个 API 模块)直连学术数据库:arXiv · OpenAlex · CrossRef · PubMed · Unpaywall · Europe PMC · DBLP · DOAJ 等
- **150 个 MCP 配置**即插即用:
- - **文献管理**:Zotero · EndNote · Mendeley
- - **IM 推送**:Telegram · 飞书 · QQ · 钉钉 · Slack(在你惯用的 IM 里收到科研提醒)
- - **开发工具**:GitHub · Jupyter · VSCode
- - **AI 服务**:OpenAI · Claude · 各类国内模型 API
- ---
- ## 架构设计
- ```
- ┌─────────────────────────────────────────────────────────────────────┐
- │ Research-Claw │
- │ │
- │ L0 workspace/ L2 dashboard/ │
- │ ├─ SOUL.md React 18 + Vite 6 │
- │ ├─ AGENTS.md Ant Design 5 + Zustand 5 │
- │ ├─ TOOLS.md 6 卡片类型 · 8 面板 │
- │ ├─ HEARTBEAT.md WebSocket RPC v3 客户端 │
- │ └─ (8 bootstrap files) 1024 i18n keys (EN + ZH-CN) │
- │ │ │
- │ L1 extensions/ │ ws://127.0.0.1:28789 │
- │ └─ research-claw-core │ │
- │ ├─ 46 tools │ │
- │ ├─ 123 WS RPC interfaces │ │
- │ └─ 23 SQLite tables + FTS5 ▼ │
- │ ╔═══════════════════════════════════════════════════╗ │
- │ ║ OpenClaw (npm dependency) ║ │
- │ ║ Gateway · WS RPC v3 · Port 28789 ║ │
- │ ╚═══════════════════════════════════════════════════╝ │
- │ │ │
- │ L3 patches/ ▼ │
- │ ~20 lines · 7 files @wentorai/research-plugins │
- │ 433 skills · 34 tools │
- └─────────────────────────────────────────────────────────────────────┘
- ```
- ### 核心设计决策
- | 决策 | 原因 |
- |:--|:--|
- | **Satellite 而非 Fork** | OpenClaw 作为内置 npm 依赖引入(无需单独安装),上游可随时升级,耦合面控制在 ~20 行 pnpm patch |
- | **4 层耦合,从外到内** | L0 文件系统 → L1 插件 SDK → L2 WS RPC → L3 patch,每层独立,可单独替换 |
- | **本地优先** | SQLite + WAL 模式,无需数据库服务;数据全在本地,唯一外部依赖是 LLM API |
- | **技能 > 裸提示词** | 433 个 SKILL.md 结构化封装学术场景,可按研究方向安装/卸载 |
- | **端口与上游错开** | 28789(科研龙虾)vs 18789(OpenClaw 默认),两者可并存 |
- | **浏览器配置一切** | 无需编辑配置文件,所有设置通过 Setup Wizard 在浏览器完成 |
- ### 安全模型
- 四层纵深防御,前三层为代码级硬约束:
- ```
- ──────────────────────────────────────────────
- L1 网络隔离
- loopback only · 无远程端口暴露
- 无 telemetry · 无云端回传
- ──────────────────────────────────────────────
- L2 Workspace 沙箱
- 原生 write/edit 工具由 config 层禁用
- 插件写文件 = 强制路径校验(拒绝 ../)
- 原生 read 保持开放(可读论文/代码)
- ──────────────────────────────────────────────
- L3 命令执行防护(before_tool_call hook)
- 拦截:rm -rf / · dd of=/dev/ · fork bomb
- Dismissed after review: Runs `rm -rf` against a root or home-directory path
- Line 267 on GitHub
- 放行:python · git · npm · 单文件 rm
- ──────────────────────────────────────────────
- L4 Git 版本控制备份
- workspace 变更自动提交(5s debounce)
- 纯本地 · 无 push · 支持全历史回滚
- ──────────────────────────────────────────────
- L+ 提示词级协议(软约束)
- SOUL.md:禁止伪造引用/数据
- AGENTS.md:不可逆操作需 Human-in-Loop
- ──────────────────────────────────────────────
- ```
- ---
- ## 快速上手
- ### 系统要求
- | 平台 | 方案 | 依赖 |
- |:--|:--|:--|
- | macOS / Linux / WSL2 | 一键安装脚本(推荐) | Git · Node.js 22(均自动安装) |
- | macOS / Linux / WSL2 | 手动安装(源码) | Git · Node.js 22+ · [pnpm](https://pnpm.io/installation) 9 |
- | macOS / Linux / Windows | Docker 一键安装 | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
- 所有平台均需 LLM API Key(推荐 Anthropic Claude / OpenAI,支持国内中转 API)。
- > **不需要单独安装 OpenClaw。** 科研龙虾已内置 OpenClaw 和全部学术技能插件,安装脚本 / Docker 会自动完成所有配置。如果你已有独立安装的 OpenClaw,也可以只安装技能插件:`openclaw plugins install @wentorai/research-plugins`,但推荐完整安装以获得 Dashboard 和全部功能。
- ### 安装
- **macOS / Linux — 源码一键安装(推荐):**
- ```bash
- 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
- ```
- #### Docker 一键安装(macOS / Linux / Windows 通用)
- 先安装 [Docker Desktop](https://docs.docker.com/desktop/),确保启动后托盘显示 Running,然后:
- ```bash
- # macOS / Linux
- 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
- ```
- ```powershell
- # Windows PowerShell
- irm https://wentor.ai/docker-install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 315 on GitHub
- ```
- > 脚本自动完成:检测 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。一键脚本会自动安装这些依赖,手动安装需要自行准备。
- ```bash
- 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:
- ```bash
- 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>
- ### 常用命令
- ```bash
- pnpm serve # 自动选择:安装用户安静启动,源码工作区开发启动
- pnpm serve:user # 显式用户模式:终端 error,文件 info
- pnpm serve:developer # 显式开发模式:终端与文件均为 debug
- pnpm support # 一次性排障:debug 启动;退出时生成脱敏诊断包
- pnpm start # 单次启动(不自动重启)
- pnpm dev # 开发模式(Gateway debug + Dashboard HMR)
- pnpm test # 运行单元测试
- pnpm health # 检查运行状态
- pnpm backup # 备份数据库
- ```
- > `pnpm serve` 是推荐的日常启动方式。安装器会写入本机安装标记,因此安装用户与源码开发者即使运行同一命令,也会稳定得到各自的日志体验。`pnpm support` 只影响本次进程,不修改 active config;按 `Ctrl+C` 退出后自动恢复日常等级并生成脱敏诊断包。
- ### 斜杠命令
- 在对话输入框中输入 `/` 即可触发命令联想菜单,支持键盘导航(↑↓ 选择,Enter 确认,Esc 关闭)。
- | 命令 | 说明 |
- |:--|:--|
- | `/compact` | 压缩会话上下文;默认优先保留科研目标、证据、数值条件、方法与引用(提高保留优先级,不保证完全无损) |
- | `/model [name]` | 查看或切换当前模型 |
- | `/think [level]` | 设置思考级别(off / low / medium / high) |
- | `/fast [on\|off]` | 切换快速模式 |
- | `/verbose [on\|off\|full]` | 切换 Agent 回复详情;不改变 Gateway、启动器或 Dashboard 通知等级 |
- | `/usage` | 查看当前会话 Token 用量 |
- | `/help` | 显示所有可用命令 |
- | `/stop` | 停止当前运行 |
- | `/clear` | 清空聊天记录 |
- | `/new` | 开始新会话 |
- ### 更新
- ```bash
- 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
- ```
- ### 数据迁移(整机搬家)
- 科研龙虾的所有记忆、会话历史、文献库、任务和工作区文件都可以完整迁移到另一台电脑。
- <details>
- <summary><b>点击展开:完整迁移指南(macOS / Linux / WSL2 / Docker)</b></summary>
- #### 数据在哪里?
- | 数据 | 路径 | 说明 |
- |:--|:--|:--|
- | **文献库 / 任务 / 监控** | `~/research-claw/.research-claw/library.db` | SQLite 数据库(核心数据,23 张表 + FTS5 全文索引) |
- | **会话历史** | `~/.openclaw/agents/main/sessions/` | 所有聊天记录(.jsonl 文件) |
- | **Agent 记忆** | `~/.openclaw/memory/main.sqlite` | 长期记忆 FTS 数据库 |
- | **工作区文件** | `~/research-claw/workspace/` | MEMORY.md、.ResearchClaw/、用户上传的文件、Git 历史 |
- | **API Key / 模型配置** | `~/research-claw/config/openclaw.json` | 项目级配置(API Key、模型、代理等) |
- | **浏览器数据** | `~/.openclaw/browser/` | 已登录的学术网站 session |
- | **IM 渠道凭证** | `~/.openclaw/credentials/` | Telegram / 飞书 / QQ 等 token |
- > **不需要迁移的**:`node_modules/`、`dashboard/dist/`(重新安装会自动生成);`~/.openclaw/openclaw.json`(全局配置含机器相关绝对路径,新机器上会自动生成);`~/.openclaw/gateway/`、`~/.openclaw/cron/`(运行时数据,自动重建)。
- ---
- #### 方案一:macOS / Linux 原生安装
- **旧机器 — 打包:**
- ```bash
- # 1. 停止科研龙虾
- pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
- # 2. 等待 SQLite WAL 落盘(重要!否则可能丢数据)
- sleep 3
- # 3. 一键打包所有数据
- tar -czf ~/rc-migration.tar.gz \
- -C / \
- "$HOME/.openclaw/agents" \
- "$HOME/.openclaw/memory" \
- "$HOME/.openclaw/browser" \
- "$HOME/.openclaw/credentials" \
- -C "$HOME/research-claw" \
- .research-claw \
- config/openclaw.json \
- workspace
- ```
- **新机器 — 恢复:**
- ```bash
- # 1. 先在新机器上全新安装(安装脚本会创建目录结构)
- 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
- # 2. 停止刚安装好的科研龙虾
- pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
- # 3. 将 rc-migration.tar.gz 复制到新机器后解压覆盖
- cd /
- tar -xzf ~/rc-migration.tar.gz
- # 4. 启动
- cd ~/research-claw && pnpm serve
- ```
- > 如果新旧机器的用户名不同(如旧机器 `alice`,新机器 `bob`),解压后需要手动修正 tar 中的路径。可以用分步复制替代:
- > ```bash
- > # 在新机器上逐个复制
- > scp -r old-mac:~/.openclaw/agents/ ~/.openclaw/agents/
- > scp -r old-mac:~/.openclaw/memory/ ~/.openclaw/memory/
- > scp -r old-mac:~/.openclaw/browser/ ~/.openclaw/browser/
- > scp -r old-mac:~/.openclaw/credentials/ ~/.openclaw/credentials/
- > scp -r old-mac:~/research-claw/.research-claw/ ~/research-claw/.research-claw/
- > scp old-mac:~/research-claw/config/openclaw.json ~/research-claw/config/
- > scp -r old-mac:~/research-claw/workspace/ ~/research-claw/workspace/
- > ```
- ---
- #### 方案二:WSL2(Windows)
- WSL2 中的路径与 Linux 相同,但传输文件需要通过 Windows 文件系统中转。
- **旧机器 — 打包(在 WSL2 终端中):**
- ```bash
- pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
- sleep 3
- # 打包到 Windows 桌面(方便拷贝)
- tar -czf /mnt/c/Users/$USER/Desktop/rc-migration.tar.gz \
- -C / \
- "$HOME/.openclaw/agents" \
- "$HOME/.openclaw/memory" \
- "$HOME/.openclaw/browser" \
- "$HOME/.openclaw/credentials" \
- -C "$HOME/research-claw" \
- .research-claw \
- config/openclaw.json \
- workspace
- ```
- **新机器 — 恢复(在 WSL2 终端中):**
- ```bash
- # 1. 先安装科研龙虾
- 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
- pkill -f "run.sh" 2>/dev/null; pkill -f openclaw 2>/dev/null
- # 2. 将 rc-migration.tar.gz 复制到新机器桌面,然后在 WSL2 中解压
- cd /
- tar -xzf /mnt/c/Users/$USER/Desktop/rc-migration.tar.gz
- # 3. 启动
- cd ~/research-claw && pnpm serve
- ```
- ---
- #### 方案三:Docker
- Docker 的数据在具名 Volume 中,需要用 `docker run` 导出/导入。
- **旧机器 — 导出:**
- ```bash
- # 1. 停止容器
- docker stop research-claw
- # 2. 导出 4 个 Volume 到 tar 文件
- for vol in rc-config rc-data rc-workspace rc-state; do
- docker run --rm -v ${vol}:/data -v ~/:/backup alpine \
- tar -czf /backup/${vol}.tar.gz -C /data .
- done
- # 结果:~/rc-config.tar.gz ~/rc-data.tar.gz ~/rc-workspace.tar.gz ~/rc-state.tar.gz
- ```
- **新机器 — 导入:**
- ```bash
- # 1. 先用一键脚本安装(会创建容器和 Volume)
- 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
- # 2. 停止容器
- docker stop research-claw
- # 3. 将 4 个 tar.gz 复制到新机器后,逐个导入
- for vol in rc-config rc-data rc-workspace rc-state; do
- # 清空现有 Volume 内容
- docker run --rm -v ${vol}:/data alpine sh -c "rm -rf /data/*"
- # 导入旧数据
- docker run --rm -v ${vol}:/data -v ~/:/backup alpine \
- tar -xzf /backup/${vol}.tar.gz -C /data
- done
- # 4. 启动
- docker start research-claw
- ```
- Windows Docker 用户:在 PowerShell 中将 `for vol in ...` 替换为逐条执行,Volume 名和命令相同。
- ---
- #### 迁移后验证
- 启动后在 Dashboard 中检查:
- - [ ] **文献库**:论文列表、标签、笔记是否完整
- - [ ] **任务**:待办事项和截止日期是否存在
- - [ ] **工作区**:文件树和版本历史是否正常
- - [ ] **设置**:API Key 和模型配置是否保留
- - [ ] **对话历史**:点击 `/new` 后能否通过历史会话列表回看之前的聊天
- > **如果 API Key 丢失**:进入 Settings 面板重新填写即可,其余数据不受影响。
- >
- > **如果连接了 Telegram / 飞书等 IM**:迁移后 bot token 会保留,但可能需要在新机器上重新验证网络连通性。
- </details>
- ---
- ## 项目结构
- ```
- research-claw/
- ├── config/ # OpenClaw 配置覆盖层
- ├── dashboard/ # React + Vite Dashboard
- │ └── src/
- │ ├── components/ # TopBar, LeftNav, ChatView, panels, cards
- │ ├── gateway/ # WS RPC v3 client + hooks
- │ ├── i18n/ # en.json + zh-CN.json
- │ ├── stores/ # Zustand stores × 18
- │ └── types/ # 6 Card type definitions
- ├── extensions/
- │ └── research-claw-core/ # 46 tools · 123 RPC · 23 tables
- ├── patches/ # pnpm patch (~20 lines, 7 files)
- ├── scripts/ # install / health / backup / sync
- ├── skills/ # 自定义 SKILL.md 文件
- └── workspace/ # Bootstrap files (SOUL.md, AGENTS.md …)
- ```
- ---
- ## 卸载
- ### 已有 OpenClaw 用户:恢复原始 OpenClaw
- 如果你在安装科研龙虾后遇到以下问题,说明安装脚本修改的全局设置影响了你原有的 OpenClaw:
- - `openclaw` 命令启动的是科研龙虾,而非原始 OpenClaw
- - 端口被固定为 28789,原始 OpenClaw 无法正常启动
- - `openclaw config` 读写的是科研龙虾的配置,而非 `~/.openclaw/openclaw.json`
- **修复方法**(两步即可,无需卸载科研龙虾):
- ```bash
- # 1. 删除 CLI wrapper(安装脚本在 ~/.local/bin/ 创建了指向科研龙虾的启动脚本)
- rm -f ~/.local/bin/openclaw
- # 2. 清除 shell 配置中的环境变量覆盖
- # 查看哪些文件被修改过:
- grep -n "OPENCLAW_CONFIG_PATH\|# Research-Claw\|\.local/bin.*Research-Claw" ~/.zshrc ~/.bashrc ~/.bash_profile 2>/dev/null
- # 找到带 "Research-Claw" 注释的行,删除即可。
- ```
- 清理后**重开终端**,`openclaw` 命令即恢复为原始版本。科研龙虾不受影响——通过 `cd ~/research-claw && pnpm serve` 启动即可,`run.sh` 会在进程内自行设置正确的配置路径,两者可以并存。
- > **为什么会冲突?** 安装脚本在 `~/.local/bin/openclaw` 创建了一个 wrapper 脚本,并将 `OPENCLAW_CONFIG_PATH` 写入 shell profile,使所有终端中的 `openclaw` 命令都指向科研龙虾的配置(端口 28789 等)。这是为了让纯科研龙虾用户可以在任意目录使用 `openclaw` CLI,但对已有 OpenClaw 安装的用户会造成覆盖。
- ### macOS / Linux(源码安装)
- ```bash
- # 1. 停止运行中的进程
- pkill -f "openclaw.*gateway" 2>/dev/null
- # 2. 删除项目目录
- rm -rf ~/research-claw
- # 3. 删除本地数据(数据库、配置、记忆)
- rm -rf ~/.research-claw
- # 4.(可选)删除 OpenClaw 全局配置
- rm -rf ~/.openclaw
- # 5. 删除 CLI wrapper 和 shell 环境变量
- rm -f ~/.local/bin/openclaw
- # 编辑 ~/.zshrc 或 ~/.bashrc,删除包含 OPENCLAW_CONFIG_PATH 和
- # "Research-Claw" 注释的行(通常 2-3 行),然后重开终端
- # 6.(可选)清除 pnpm 全局缓存
- pnpm store prune
- ```
- ### Docker(macOS / Linux / Windows)
- ```bash
- # 1. 停止并删除容器
- docker stop research-claw && docker rm research-claw
- # 2. 删除镜像
- docker rmi ghcr.io/wentorai/research-claw:latest
- # 3.(可选)删除持久化数据(配置、数据库、工作区)
- docker volume rm rc-config rc-data rc-workspace rc-state
- ```
- Windows PowerShell 命令相同,在 PowerShell 中逐行执行即可。
- > **注意**:执行第 3 步将永久删除所有数据(论文库、任务、工作区文件、会话历史)。如需保留数据,跳过此步。
- >
- > Docker 安装不会修改宿主机的 shell 配置或 CLI wrapper,无需额外清理。
- ### WSL2(Windows 手动安装)
- ```powershell
- # 1. 在 WSL2 中停止并删除(同 Linux 步骤)
- wsl -e bash -c "pkill -f 'openclaw.*gateway' 2>/dev/null; rm -rf ~/research-claw ~/.research-claw ~/.openclaw ~/.local/bin/openclaw"
- # 2. 清理 shell 环境变量(在 WSL2 Ubuntu 终端中)
- wsl -e bash -c "sed -i '/OPENCLAW_CONFIG_PATH/d;/Research-Claw/d' ~/.bashrc 2>/dev/null"
- # 3.(可选)如果 WSL2 仅用于科研龙虾,可以完全卸载 WSL 发行版
- wsl --unregister Ubuntu
- ```
- > 卸载 WSL 发行版会删除该发行版内的**所有数据**,请确认无其他用途后再操作。
- ---
- ## 问题反馈
- 遇到 Bug?在 [GitHub Issues](https://github.com/wentorai/Research-Claw/issues) 提交报告,标题格式:`[Bug] 一句话描述`。
- **一份有效的 Bug 报告需要四样东西:**
- | 要素 | 怎么提供 |
- |:--|:--|
- | **复现步骤** | 写清楚你做了什么、点了什么、说了什么,让开发者能重现问题 |
- | **后端日志** | 从终端 / Docker 复制日志文字(见下方命令),**不要只截图** |
- | **浏览器控制台** | `Cmd+Option+J`(macOS)或 `Ctrl+Shift+J`(Windows)打开,复制错误信息 |
- | **环境信息** | 系统、安装方式(install.sh / Docker / WSL2)、RC 版本(Dashboard 左下角)、模型 |
- > **为什么日志要文字复制?** 截图里的日志无法搜索、无法复制到代码中定位、容易截不全。截图展示界面异常 + 文字复制日志内容,两者配合。
- <details>
- <summary><b>各平台获取后端日志的命令</b></summary>
- ```bash
- # macOS / Linux 原生安装
- tail -50 ~/.research-claw/logs/openclaw.log
- # 一次性 debug 启动;Ctrl+C 退出后生成脱敏诊断包且不改配置
- cd ~/research-claw && pnpm support
- # Docker(macOS / Linux / Windows)
- docker logs --tail 50 research-claw
- # WSL2(systemd 服务模式)
- journalctl --user -u research-claw --no-pager -n 50
- ```
- 也可以在 Dashboard → **Settings** → **Logs** 标签中查看和筛选日志。
- </details>
- 功能建议和讨论请用 [GitHub Discussions](https://github.com/wentorai/Research-Claw/discussions)。
- ---
- ## 致谢
- - [ppt-master](https://github.com/hugohe3/ppt-master) — PPT 生成引擎,为科研龙虾的 PPT 导出功能提供了核心支持
- ## 许可证
- [BSL 1.1](LICENSE) — 个人及学术研究免费使用。商业用途需单独授权,联系 [help@wentor.ai](mailto:help@wentor.ai)。2030-03-12 自动转为 Apache 2.0 开源。
- ---
- <div align="center">
- <sub>Built with ❤️ by <a href="https://wentor.ai">Wentor AI</a></sub>
- </div>
skills/md2pdf-export/scripts/setup-env.sh · Bundled script · 393 lines · 2 findings marked
- #!/usr/bin/env bash
- # ============================================================================
- # md2pdf-export: Environment Setup Script
- # Installs Node.js, Puppeteer, and Chrome/Chromium dependencies
- # Idempotent — safe to run multiple times
- # ============================================================================
- set -euo pipefail
- # Colors for output
- RED='\033[0;31m'
- GREEN='\033[0;32m'
- YELLOW='\033[1;33m'
- BLUE='\033[0;34m'
- NC='\033[0m' # No Color
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
- SKILL_DIR="$(dirname "$SCRIPT_DIR")"
- MIN_NODE_VERSION=18
- NVM_VERSION="v0.40.1"
- # ── Utility functions ────────────────────────────────────────────────────────
- log_info() { echo -e "${BLUE}[INFO]${NC} $*"; }
- log_ok() { echo -e "${GREEN}[OK]${NC} $*"; }
- log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
- log_err() { echo -e "${RED}[ERROR]${NC} $*"; }
- command_exists() { command -v "$1" &>/dev/null; }
- version_gte() {
- # Returns 0 if $1 >= $2 (semver major only)
- local cur="$1" min="$2"
- [ "$cur" -ge "$min" ] 2>/dev/null
- }
- detect_os() {
- if [[ "$OSTYPE" == "darwin"* ]]; then
- echo "macos"
- elif [ -f /etc/os-release ]; then
- . /etc/os-release
- case "$ID" in
- ubuntu|debian|pop|linuxmint|elementary) echo "debian" ;;
- alpine) echo "alpine" ;;
- centos|rhel|fedora|rocky|almalinux) echo "rhel" ;;
- arch|manjaro) echo "arch" ;;
- *) echo "linux-unknown" ;;
- esac
- else
- echo "unknown"
- fi
- }
- detect_container() {
- # Detect if running inside Docker/container
- if [ -f /.dockerenv ] || grep -qsE '(docker|containerd|kubepods)' /proc/1/cgroup 2>/dev/null; then
- echo "true"
- else
- echo "false"
- fi
- }
- # ── Step 1: Detect environment ───────────────────────────────────────────────
- echo ""
- echo "============================================================"
- echo " md2pdf-export: Environment Setup"
- echo "============================================================"
- echo ""
- OS=$(detect_os)
- IN_CONTAINER=$(detect_container)
- log_info "Detected OS: $OS"
- log_info "In container: $IN_CONTAINER"
- # ── Step 2: Install Node.js ──────────────────────────────────────────────────
- install_node_nvm() {
- log_info "Installing Node.js via nvm..."
- # Install nvm if not present
- if [ ! -d "$HOME/.nvm" ]; then
- log_info "Installing nvm ${NVM_VERSION}..."
- curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" | bash
- fi
- # Source nvm
- export NVM_DIR="$HOME/.nvm"
- [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
- if ! command_exists nvm; then
- log_err "nvm installation failed. Try installing Node.js manually."
- return 1
- fi
- nvm install --lts
- nvm use --lts
- nvm alias default 'lts/*'
- log_ok "Node.js $(node -v) installed via nvm"
- }
- install_node_package_manager() {
- case "$OS" in
- macos)
- if command_exists brew; then
- log_info "Installing Node.js via Homebrew..."
- brew install node
- else
- install_node_nvm
- fi
- ;;
- debian)
- log_info "Installing Node.js via NodeSource..."
- if command_exists sudo; then
- sudo apt-get update -qq
- sudo apt-get install -y -qq curl
- 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
- sudo apt-get install -y -qq nodejs
- else
- apt-get update -qq
- apt-get install -y -qq curl
- 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
- apt-get install -y -qq nodejs
- fi
- ;;
- alpine)
- apk add --no-cache nodejs npm
- ;;
- rhel)
- if command_exists dnf; then
- sudo dnf install -y nodejs npm
- else
- sudo yum install -y nodejs npm
- fi
- ;;
- *)
- install_node_nvm
- ;;
- esac
- }
- check_node() {
- if command_exists node; then
- local node_major
- node_major=$(node -v | sed 's/v//' | cut -d. -f1)
- if version_gte "$node_major" "$MIN_NODE_VERSION"; then
- log_ok "Node.js $(node -v) found (>= v${MIN_NODE_VERSION} required)"
- return 0
- else
- log_warn "Node.js $(node -v) is too old (need >= v${MIN_NODE_VERSION})"
- return 1
- fi
- else
- log_warn "Node.js not found"
- return 1
- fi
- }
- if ! check_node; then
- install_node_package_manager
- # Re-source in case nvm was used
- [ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
- if ! check_node; then
- log_err "Failed to install Node.js >= v${MIN_NODE_VERSION}"
- exit 1
- fi
- fi
- # Ensure npm is available
- if ! command_exists npm; then
- log_err "npm not found even though Node.js is installed"
- exit 1
- fi
- log_ok "npm $(npm -v) found"
- # ── Step 3: Install Chrome/Chromium system dependencies ─────────────────────
- install_chrome_deps() {
- log_info "Installing Chromium system dependencies..."
- case "$OS" in
- debian)
- local DEPS=(
- ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0t64
- libatk1.0-0t64 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0t64
- libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1
- libxfixes3 libxrandr2 xdg-utils wget fonts-noto-cjk
- )
- # Try with t64 suffix first (Ubuntu 24+), fallback to plain names
- if command_exists sudo; then
- sudo apt-get update -qq
- sudo apt-get install -y -qq "${DEPS[@]}" 2>/dev/null || {
- # Fallback for older Ubuntu/Debian without t64 suffix
- local DEPS_FALLBACK=(
- ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0
- libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0
- libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1
- libxfixes3 libxrandr2 xdg-utils wget fonts-noto-cjk
- )
- sudo apt-get install -y -qq "${DEPS_FALLBACK[@]}"
- }
- else
- apt-get update -qq
- apt-get install -y -qq "${DEPS[@]}" 2>/dev/null || {
- local DEPS_FALLBACK=(
- ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0
- libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0
- libnspr4 libnss3 libx11-xcb1 libxcomposite1 libxdamage1
- libxfixes3 libxrandr2 xdg-utils wget fonts-noto-cjk
- )
- apt-get install -y -qq "${DEPS_FALLBACK[@]}"
- }
- fi
- ;;
- alpine)
- apk add --no-cache \
- chromium nss freetype harfbuzz ca-certificates ttf-freefont \
- font-noto-cjk
- export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
- export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
- ;;
- rhel)
- if command_exists dnf; then
- sudo dnf install -y \
- alsa-lib atk cups-libs dbus-libs libdrm mesa-libgbm gtk3 \
- nss libXcomposite libXdamage libXfixes libXrandr xdg-utils \
- google-noto-sans-cjk-ttc-fonts
- fi
- ;;
- macos)
- # macOS: Puppeteer bundles Chromium, no system deps needed
- # But install CJK fonts if missing
- if command_exists brew; then
- brew install --cask font-noto-sans-cjk 2>/dev/null || true
- fi
- ;;
- *)
- log_warn "Unknown OS — skipping system dependency installation."
- log_warn "If Chrome fails to launch, install Chromium deps manually."
- ;;
- esac
- log_ok "Chrome system dependencies installed"
- }
- install_chrome_deps
- # ── Step 4: Install Puppeteer ────────────────────────────────────────────────
- install_puppeteer() {
- log_info "Installing puppeteer globally..."
- # Set npm global prefix to user space to avoid sudo
- local NPM_GLOBAL="$HOME/.npm-global"
- mkdir -p "$NPM_GLOBAL"
- npm config set prefix "$NPM_GLOBAL"
- # Ensure it's in PATH
- if [[ ":$PATH:" != *":$NPM_GLOBAL/bin:"* ]]; then
- export PATH="$NPM_GLOBAL/bin:$PATH"
- # Persist in shell rc
- for rc in "$HOME/.bashrc" "$HOME/.zshrc"; do
- if [ -f "$rc" ]; then
- grep -q 'npm-global/bin' "$rc" 2>/dev/null || \
- echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$rc"
- fi
- done
- fi
- # Install puppeteer
- npm install -g puppeteer 2>&1 | tail -5
- log_ok "puppeteer installed globally"
- }
- check_puppeteer() {
- if node -e "require('puppeteer')" 2>/dev/null; then
- local pup_ver
- pup_ver=$(node -e "console.log(require('puppeteer/package.json').version)" 2>/dev/null)
- log_ok "puppeteer v${pup_ver} found"
- return 0
- else
- return 1
- fi
- }
- if ! check_puppeteer; then
- install_puppeteer
- if ! check_puppeteer; then
- log_err "Failed to install puppeteer"
- exit 1
- fi
- fi
- # ── Step 5: Install md2pdf.js local dependencies ────────────────────────────
- install_skill_deps() {
- log_info "Installing md2pdf.js npm dependencies..."
- cd "$SKILL_DIR/scripts"
- if [ ! -f package.json ]; then
- log_warn "No package.json found in scripts/, creating one..."
- cat > package.json <<'PJSON'
- {
- "name": "md2pdf-export",
- "version": "1.0.0",
- "private": true,
- "dependencies": {
- "markdown-it": "^14.0.0",
- "markdown-it-anchor": "^9.0.0",
- "markdown-it-footnote": "^4.0.0",
- "markdown-it-highlightjs": "^4.1.0",
- "markdown-it-texmath": "^1.0.0",
- "markdown-it-toc-done-right": "^4.2.0",
- "katex": "^0.16.0",
- "gray-matter": "^4.0.3",
- "puppeteer": ">=21.0.0"
- }
- }
- PJSON
- fi
- npm install --prefer-offline 2>&1 | tail -3
- log_ok "md2pdf.js dependencies installed"
- cd - > /dev/null
- }
- install_skill_deps
- # ── Step 6: Verify everything works ─────────────────────────────────────────
- log_info "Running smoke test..."
- CHROME_LAUNCH_ARGS=""
- if [ "$IN_CONTAINER" = "true" ]; then
- CHROME_LAUNCH_ARGS="--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage"
- fi
- SMOKE_RESULT=$(node -e "
- const puppeteer = require('puppeteer');
- (async () => {
- try {
- const args = '${CHROME_LAUNCH_ARGS}'.split(' ').filter(Boolean);
- const browser = await puppeteer.launch({
- headless: 'new',
- args: args
- });
- const page = await browser.newPage();
- await page.setContent('<h1>Smoke Test OK</h1>');
- const pdf = await page.pdf({ format: 'A4' });
- console.log('PDF_SIZE=' + pdf.length);
- await browser.close();
- console.log('SMOKE_OK');
- } catch (e) {
- console.error('SMOKE_FAIL: ' + e.message);
- process.exit(1);
- }
- })();
- " 2>&1) || true
- if echo "$SMOKE_RESULT" | grep -q "SMOKE_OK"; then
- PDF_SIZE=$(echo "$SMOKE_RESULT" | grep "PDF_SIZE" | cut -d= -f2)
- log_ok "Smoke test passed (PDF generated: ${PDF_SIZE} bytes)"
- else
- log_err "Smoke test failed:"
- echo "$SMOKE_RESULT"
- echo ""
- log_warn "Common fixes:"
- log_warn " - Docker: ensure --no-sandbox is enabled"
- log_warn " - Missing libs: run 'npx puppeteer browsers install chrome'"
- log_warn " - Set PUPPETEER_EXECUTABLE_PATH to an existing Chrome binary"
- exit 1
- fi
- # ── Summary ──────────────────────────────────────────────────────────────────
- echo ""
- echo "============================================================"
- echo " ✅ md2pdf-export: Environment Ready"
- echo "============================================================"
- echo ""
- echo " Node.js: $(node -v)"
- echo " npm: $(npm -v)"
- echo " Puppeteer: $(node -e "console.log(require('puppeteer/package.json').version)" 2>/dev/null || echo 'unknown')"
- echo " OS: $OS"
- echo " Container: $IN_CONTAINER"
- echo ""
- echo " Usage:"
- echo " node ${SKILL_DIR}/scripts/md2pdf.js input.md"
- echo " node ${SKILL_DIR}/scripts/md2pdf.js input.md --type png"
- echo " node ${SKILL_DIR}/scripts/md2pdf.js input.md -o output.pdf"
- echo ""
- echo "============================================================"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.