LightRead CLI (lr)

终端原生学术研究工具，连接 LightRead 云端能力，支持论文搜索、资源库管理、笔记与图谱构建。配合 Cursor Skill 使用，可让 AI Agent 通过 CLI 命令完成学术研究任务。

特性

• 多源学术搜索：Semantic Scholar、arXiv 等，支持 BibTeX / JSON / Markdown 输出
• Agent 学术搜索：LLM 自主决定搜索策略，多轮检索并生成学术综述（lr agent）
• 资源库管理：上传 PDF、URL 导入、语义搜索、标签、文件夹、下载
• 笔记与 AI 笔记：创建、编辑、删除笔记，为 PDF 生成 AI 导读
• 论文关系图谱：基于 OpenAlex 构建引用/共引关系，发现相关文献
• 每日推荐：获取当日精选论文
• Skill + CLI：配合 Cursor Skill 使用，AI Agent 通过执行 lr 命令完成学术任务

环境要求

• Node.js >= 18.0.0
• LightRead 账户：在 lightingread.cn 注册，并记住登录邮箱和密码

安装

# 全局安装（推荐，任选其一）
yarn global add lightread-cli
# 或
npm install -g lightread-cli

# 验证
lr --version

本仓库内开发请使用 Yarn（与 LightRead 主仓库一致，锁文件为 yarn.lock），不要用 npm install 以免生成 package-lock.json。

快速开始

# 1. 登录（输入邮箱 + 密码，自动复用已有 Key 或创建新 Key 并保存）
lr auth login

# 2. 验证认证状态（含账户积分、订阅信息）
lr auth status --verify

# 3. 搜索学术论文
lr search "attention mechanism" --source scholar

# 4. 查看资源库
lr library ls

认证配置

lr auth login 是推荐的认证方式。登录成功后，CLI 会优先复用你账号下已有的可用 Key；若不存在可用 Key，再自动创建一个新的 lr_xxx 格式 API Key 并保存到本地。

如果你已经在 LightRead 网页端手动创建了 API Key，也可以跳过登录直接配置：

| 方式 | 说明 | |------|------| | 交互式登录（推荐） | lr auth login | | 直接设置 Key | lr auth key set <key> | | 环境变量 | export LR_API_KEY=lr_xxx | | 后端地址 | lr config set server <url>（默认 https://lightingread.cn） |

命令参考

lr auth — 认证管理

lr auth login                  # 邮箱 + 密码登录，自动复用已有 Key 或创建并保存新 Key（推荐）
lr auth status --verify        # 查看 Key 状态 + 账户积分/订阅信息
lr auth key set lr_xxx         # 手动设置已有的 API Key
lr auth key list               # 列出所有 Key（需登录）
lr auth logout                 # 清除本地凭据

lr search — 学术搜索

lr search "RLHF"                            # 默认 Semantic Scholar
lr search "transformer" --source arxiv      # arXiv 搜索
lr search "LLM alignment" --limit 20 --year 2022-
lr search "deep learning" --format bibtex   # BibTeX 格式输出

选项：-s/--source、-l/--limit、--year、--format（json / table / csv / md / bibtex / plain）

lr agent — Agent 学术搜索

LLM 自主决定搜索策略，多轮调用 Semantic Scholar 和 arXiv，并生成学术综述。适合需要智能检索和综合分析的场景。

# 单次搜索（Agent 自动选择工具和参数）
lr agent "RLHF 最新进展"
lr agent "transformer survey 2024" --format json

# 多轮交互对话（需 TTY）
lr agent --interactive
> 找 2024 年以来的 diffusion model 论文
> 其中影响力最高的几篇重点介绍一下
> exit

选项：-i/--interactive（多轮对话）、-f/--format（plain / json）、--no-color

说明：进度信息输出到 stderr，最终回答输出到 stdout，便于管道和脚本化使用。

lr folder — 文件夹管理

lr folder create "研究/NLP"                 # 创建文件夹
lr folder create "子文件夹" --parent <id>   # 在指定文件夹下创建
lr folder rename <id> "新名称"              # 重命名
lr folder delete <id> -y                   # 删除（-y 跳过确认）

lr library — 资源库管理

lr library ls                              # 列出所有资源
lr library ls --type pdf --tag 重要        # 按类型/标签筛选
lr library tree                            # 文件夹树形视图
lr library search "attention"            # 关键词全文搜索（标题等）
lr library semantic-search "注意力如何计算"  # 内容级语义搜索（向量）
lr library grep "BERT|GPT"                 # 正则全文搜索
lr library import "paper.pdf"               # 上传本地 PDF
lr library import https://...               # 通过 URL 导入（自动解析并确认）
lr library import https://... --wait        # URL 导入后等待 PDF 处理完成
lr library info <resource-id>              # 查看资源详情
lr library mv <resource-id> --to <folder-id>  # 移动到文件夹（省略 --to 则根目录）
lr library rm <resource-id> -y             # 删除资源（-y 跳过确认）
lr library download <resource-id>          # 下载原始文件
lr library storage                         # 查看存储用量
lr library tag ls                          # 列出所有标签
lr library tag add <resource-id> <tag>     # 为资源添加标签
lr library tag rm <resource-id> <tag-id>   # 移除标签
lr library graph                           # 资源库图谱（folder/tag/conversation 模式）
lr library graph --mode tag --format json  # 指定模式 + JSON 输出

URL 导入流程：提交 URL → 自动轮询解析（约 10–60 秒）→ 自动确认导入 → 输出 resource_id。失败时提示到网页端手动确认。

lr note — 笔记管理

lr note list                           # 列出所有笔记
lr note read <note-id>                 # 读取笔记内容
lr note create "研究日志"               # 创建空笔记
lr note create "笔记" --content "内容"  # 带内容创建
cat notes.md | lr note create "导入" --from-stdin
lr note update <note-id> --title "新标题"
lr note update <note-id> --content "新内容"
lr note delete <note-id> -y
lr note ai-generate <resource-id>      # 为 PDF 生成 AI 笔记
lr note ai-generate <resource-id> --wait  # 等待并显示结果

lr memo — 记忆库

lr memo list                             # 列出记忆（按创建时间倒序）
lr memo list --limit 50 --format json
lr memo search "查询语句"                 # 语义搜索（向量相似度）
lr memo search "RLHF" --limit 5 --format json
lr memo add "一段需要长期记住的知识点"    # 添加记忆（异步向量化）

lr checkin — 每日签到

lr checkin status                      # 查看签到状态
lr checkin do                          # 执行签到

lr open — 打开 Web 资源

lr open <resource-id>                  # 在浏览器中打开资源
lr open <task-id> --type paper        # 打开学术写作任务
lr open <id> --no-browser             # 仅输出 URL

lr papers — 每日推荐论文

lr papers today                        # 今日推荐
lr papers today --date 2025-01-15      # 指定日期
lr papers today --format md            # Markdown 格式
lr papers dates                        # 查看有推荐的历史日期

lr graph — 论文关系图谱

基于 OpenAlex 数据，以指定论文为种子，构建引用关系、共引关系的学术图谱，发现与种子论文相关的核心文献。

# 1. 搜索种子论文，获取 OpenAlex ID
lr graph search "attention mechanism" --limit 10

# 2. 以指定论文为种子启动图谱构建（异步任务）
lr graph build W2741809807 --title "Attention Is All You Need"
lr graph build W2741809807 --top-n 40 --wait            # 等待完成后查看摘要

# 3. 实时观察构建进度
lr graph watch <task-id>

# 4. 查看图谱数据
lr graph show <task-id>                                  # 展示 Top 10 高被引节点
lr graph show <task-id> --top 20                         # 展示 Top 20
lr graph show <task-id> --format json > graph.json        # 导出完整 JSON 数据

# 5. 管理任务
lr graph list                                            # 列出所有图谱任务
lr graph list --status finished                          # 仅显示已完成
lr graph delete <task-id> -y                             # 删除任务记录

构建选项：

| 参数 | 说明 | 默认值 | |------|------|--------| | --title | 种子论文标题（仅用于展示） | — | | --top-n | 目标图谱节点数 | 30 | | --max-references | 最多抓取参考文献数 | 100 | | --max-citing | 最多抓取引用该论文的近期论文数 | 50 | | --max-secondary | 二级节点最大数量 | 20 | | --edge-threshold | 边权重阈值 (0.0-1.0) | 0.1 | | --wait | 等待完成后展示摘要 | false |

注意：图谱构建通常需要 30–120 秒，--wait 模式会根据进度自动调整轮询间隔（5–30 秒），避免频繁请求。

AI Agent 集成（Skill + CLI）

本分支专注于 Skill + CLI 模式：通过 Cursor Skill 指导 AI Agent 执行 lr 命令完成学术任务，无需 MCP Server。

推荐做法：在项目或全局创建 .cursor/skills/lightread-cli/ 或 ~/.cursor/skills/lightread-cli/，编写 SKILL.md 描述何时、如何调用 lr 命令。例如：

• 学术搜索：lr search "关键词" --source scholar --format json
• Agent 搜索：lr agent "RLHF 最新进展"（LLM 自主检索并综述）
• 资源库：lr library ls、lr library search / semantic-search / grep、lr library graph
• 文件夹：lr folder create "名称"、lr folder rename/delete
• 记忆：lr memo list、lr memo search、lr memo add
• 笔记：lr note list、lr note read <note-id>
• 每日签到：lr checkin do
• 每日推荐：lr papers today
• 论文图谱：lr graph search "论文名"、lr graph build <openalex-id> --wait
• 打开 Web：lr open <resource-id>、lr open <task-id> --type paper

通用选项

所有命令支持：

| 选项 | 说明 | |------|------| | -f/--format | 输出格式：json / table / csv / md / bibtex / plain | | --no-color | 禁用彩色输出 |

管道使用示例：

lr library ls --format json | jq '.[] | select(.resource_type == "pdf") | .title'
lr search "BERT" --format bibtex >> bibliography.bib

Shell 自动补全

# Bash
lr completion bash >> ~/.bashrc && source ~/.bashrc

# Zsh
lr completion zsh >> ~/.zshrc && source ~/.zshrc

# Fish
lr completion fish >> ~/.config/fish/completions/lr.fish

本地开发

修改源码后，需先重新编译再重装，变更才会生效：

cd lightread-cli

# 1. 安装依赖（首次会生成 yarn.lock）
yarn install

# 2. 编译 TypeScript → dist/
yarn build

# 3. 重新安装到全局（任选其一）
yarn global add "$(pwd)"
# 或
npm install -g .

# 验证
lr search "transformer"

全局链入打包的是 dist/ 目录内容；若跳过编译直接安装，运行的仍是上一次的旧产物。

发布流程

正式发包前，建议按下面顺序执行一次：

cd lightread-cli

# 1. 安装依赖（首次或 package.json 变更后）
yarn install

# 2. 编译
yarn build

# 3. 生成 oclif manifest 并打包校验
yarn pack --filename lightread-cli.tgz

# 4. 本地 smoke test
node ./bin/lr --help
node ./bin/lr agent --help
node ./bin/lr search --help

# 5. 确认无误后再发布（与 npm publish 等价，走 npm registry）
yarn publish

说明：

• prepack 会自动执行 TypeScript 编译，并通过 scripts/polyfill-node18.js 兼容 Node 18 下的 oclif manifest
• yarn pack 成功后会产出 .tgz，可先本地验证包内容，再决定是否 yarn publish（或 npm publish）
• 若 package.json 新增了依赖，必须先执行一次 yarn install，否则 prepack / yarn pack 会因缺少依赖失败

相关链接

• LightRead 官网
• CLI 文档
• API 文档
• 更新日志

License

MIT