deep-radar

deep-radar 是一个用于采集 X 帖子、arXiv 论文榜单并上传轮次数据的 Node.js CLI。

使用方法

npm install
npm start -- --help

安装完成后，或在本地通过 npm link 链接后，可以直接运行：

deep-radar --help

默认用户目录是 ~/.deep-radar/。

默认配置文件是 ~/.deep-radar/deep-radar.json。

采集 X 帖子：

deep-radar collect --source x
deep-radar collect --source x --url https://x.com/dotey/status/2051688341519609897

采集 arXiv 论文榜单：

deep-radar collect --source arxiv
deep-radar collect --source arxiv --day
deep-radar collect --source arxiv --day --previous
deep-radar collect --source arxiv --day 2026-04-28 --limit 20
deep-radar collect --source arxiv --week
deep-radar collect --source arxiv --week --previous
deep-radar collect --source arxiv --week 2026-W18 --limit 10
deep-radar collect --source arxiv --week --limit 10 --force
deep-radar collect --source arxiv --month
deep-radar collect --source arxiv --month --previous
deep-radar collect --source arxiv --month 2026-04 --limit 30
deep-radar collect --source arxiv --id 2604.22748

采集完成后可以选择直接调用本地安装的 codex / claude / opencode 做翻译：

deep-radar collect --source x --translate
deep-radar collect --source x --translate --agent writer
deep-radar collect --source x --upload
deep-radar collect --source x --translate --upload

采集单个网页链接并生成综合内容 JSON：

deep-radar collect --source general --url https://example.com/post
deep-radar collect --source general --url https://example.com/post --agent writer
deep-radar collect --source general --url https://example.com/post --upload

单链接采集不做前置页面解析；CLI 会把 URL、中文 Markdown 输出路径、元数据 JSON 输出路径和图片目录交给配置的 agent。agent 负责抓取页面、提取正文、识别原作者和原发布时间、下载正文图片、翻译清洗，并直接写出 -cn.md 与 -metadata.json。随后 CLI 去掉中文 Markdown 的一级标题后，使用 @rongyan/mdflow-cli 以 石墨黑 主题渲染成 HTML，并把 HTML 写入 source: "general" 的综合内容 JSON。清洗要求包括适合中文母语阅读、移除外链、移除导航/社交媒体引用/广告等冗余内容，并对政治敏感内容做脱敏处理。

综合内容 JSON 的 author 与 publishedAt 来自 agent 写出的元数据 JSON；缺失时为空字符串，不做本地猜测。正文图片必须下载到同轮次 result/ 目录下的本地图片目录，JSON 中的 HTML 会引用这些本地图片，--upload 会自动随内容一起上传。调用 agent 时默认 10 分钟超时，最多尝试 2 次；CLI 进度日志会显示当前 attempt、timeout 和 retry 信息。

使用 --output-format 控制 X 采集结果写出哪些文件。支持的值是 both（默认）、json 和 markdown：

deep-radar collect --source x --output-format both
deep-radar collect --source x --output-format json
deep-radar collect --source x --output-format markdown

arxiv 采集支持 --day、--week、--month、--previous 和 --limit：

• --day 默认采集当天日榜；也可以写成 --day YYYY-MM-DD
• --week 默认采集本周周榜；也可以写成 --week YYYY-Www
• --month 默认采集本月月榜；也可以写成 --month YYYY-MM
• --previous 会把当前目标周期往前推一档，比如 --day --previous、--week --previous、--month --previous
• --previous 不能和显式值一起用，比如 --week 2026-W18 --previous 会直接报错
• --limit 控制采集榜单数量，默认是 10；会直接透传给 Hugging Face daily_papers API，并遵循该接口当前上限（当前实现按 100 封顶）
• 周榜 / 月榜 / 日榜按 Hugging Face daily_papers 的 trending 排序直接截断，不再在本地按 upvotes 二次重排
• arxiv 榜单只会生成一个 JSON，不生成 Markdown，也不支持 --output-format
• 日榜 / 周榜 / 月榜会先按 Hugging Face 清单写出一个基础 JSON，papers 数组里包含多篇论文；随后队列会逐篇补充 arXiv 元数据、TeX source 和缩略图；单篇 --id 采集不走这个队列
• 多篇采集时，arXiv API 请求会串行执行；首次请求不额外等待，后续请求保持默认 4 秒间隔，遇到 429 等可重试失败会最多退避重试 3 次；如果开启 --pager-reader，也会先完整完成采集，再把生成好的榜单 JSON 交给 pager-reader 精读

兼容旧写法：

• 仍然支持 --period day|week|month
• 仍然支持 --date YYYY-MM-DD 作为 --day 的兼容别名

把已采集的 X 轮次上传到 deep-radar-server：

deep-radar upload 2026-04-23-01.json
deep-radar upload /absolute/path/to/2026-04-23-01.json
deep-radar upload --source arxiv 2604.20779-02-cn.json
deep-radar upload --source general 2026-05-06-general-01.json

upload 命令会读取轮次 JSON，并自动查找相关资源后一起上传。对于 x，会附带 articles-data/*.json 和引用到的媒体文件；对于 arxiv，会附带缩略图、TeX source 目录，以及 pager-reader 生成的 .wxhtml 和同级资源目录；对于 general，会上传综合内容 JSON 中的 items，并附带正文 HTML 引用到的本地资源。

默认情况下，原始采集结果会写入 ~/.deep-radar/raw/x。

arxiv 的原始采集结果默认写入 ~/.deep-radar/raw/arxiv。

general 单链接采集结果默认写入 ~/.deep-radar/raw/general。

每次采集都会生成一个带日期的 Markdown 文件，例如：

~/.deep-radar/raw/x/2026-04-21-01.md

在默认的 --output-format both 模式下，采集器还会在 Markdown 旁边额外写出同名 JSON，例如 ~/.deep-radar/raw/x/2026-04-21-01.json。这个 JSON 里的每条 tweet 都包含单独的 ID 字段、英文 interactionType 枚举值（post、repost、quote），以及合并后的 author 对象；如果账号池里有元数据，也会一起写入。collectedBy 只会出现在转发和引用的条目中。对于 X Articles，轮次 JSON 只保留轻量的 article 元数据（title、previewText 和 dataPath 引用），详细的富文本文章内容会单独写到 articles-data/ 目录下，并与 articles/ 使用同样的基础文件名。普通 Tweets/Posts 会直接写入轮次 Markdown。X Articles 仍然会单独保存到 articles/ 目录，并在轮次 Markdown 中链接过去。媒体文件会下载到类似 media/2026-04-21/ 这样的按日期分组目录中，并通过相对路径引用。

当使用 --output-format json 时，只会写出轮次 JSON 和 articles-data/*.json。当使用 --output-format markdown 时，只会写出轮次 Markdown 和 articles/*.md。无论哪种模式，去重索引 index.json 都会更新。upload 命令仍然要求输入轮次 JSON 文件，所以如果后面还要上传，请使用 both 或 json。

arxiv 榜单采集会写出一个榜单 JSON。文件名使用榜单周期和值，例如：

~/.deep-radar/raw/arxiv/2026-W18-top10-01.json

arxiv/index.json 只保留 论文ID -> 首次采集榜单 JSON 文件名 的映射。命中索引的论文不会再次进入新的采集队列；如果本轮榜单里的论文全部都已收录，就不会生成新的榜单 JSON。

arxiv 还会把缩略图和 TeX source 下载到本地目录，例如：

~/.deep-radar/raw/arxiv/thumbnails/2604-19748-thumbnail.png
~/.deep-radar/raw/arxiv/sources/2604.19748/

如果某篇论文没有可用的 TeX source，采集器会在榜单 JSON 里保留来自 Hugging Face 的基础信息，但不会更新索引；后续 pager-reader 会跳过没有 localSourcePath 的论文。

榜单 JSON 会同时保留远程 thumbnailUrl / pdfUrl，以及本地相对路径 localThumbnailPath / localSourcePath。每篇 arXiv 论文记录还会额外带一个 subTitle 字段，当前值与 title 相同，供后续流程复用。

使用 --output-dir 可以覆盖原始输出根目录：

deep-radar collect --source x --output-dir /tmp/deep-radar-raw
deep-radar collect --source arxiv --output-dir /tmp/deep-radar-raw

使用 --hours 可以覆盖采集时间范围，默认是 24 小时：

deep-radar collect --source x --hours 6

也可以对已经采集好的文件单独执行翻译，JSON 和 Markdown 都支持：

deep-radar translate 2026-04-23-01.json
deep-radar translate 2026-04-23-01.md
deep-radar translate --agent writer 2026-04-23-01.json 2026-04-24-01.json
deep-radar translate --upload 2026-04-23-01.json
deep-radar translate --source arxiv 2604.20779-02.json

对于 arXiv JSON，也可以用 translate --source arxiv 直接走精读翻译流程；它内部会复用 pager-reader。pager-reader 会读取输入 JSON 中一篇或多篇论文的 localSourcePath，拼成绝对路径交给本地 agent 的 paper-reader 技能；技能需要为每篇论文把 summary、markdownPath 和 title（Markdown 一级标题）写到本地结果 JSON 文件里，再由 CLI 回读这些结果文件。CLI 会基于每篇 Markdown 在同名位置生成 .wxhtml，并把翻译后的 summary、生成出的 localPath 和新的 title 回填到同一个 *-cn.json。

如果技能产出的 Markdown 里包含 mermaid 代码块，CLI 会先调用全局安装的 mmdpc（@rongyan/mermaid-plus-cli）把 Mermaid 原地转成本地图片，再继续生成 .wxhtml：

deep-radar pager-reader 2604.20779-02.json
deep-radar pager-reader --agent writer 2604.20779-02.json
deep-radar pager-reader --force 2026-04-top10-01.json

pager-reader 支持 source: "arxiv" 且 papers 数组里有 1 篇或多篇论文的 JSON 文件；多篇会逐篇串行调用 agent，每完成一篇就回填一次同一个 *-cn.json。默认会跳过已有 localPath 且本地文件存在的论文，使用 --force 可以强制重跑。

collect、translate 和 pager-reader 现在都支持 --upload。加上这个参数后，命令会在采集、翻译或精读结束后自动调用上传流程。

当 collect --source arxiv 同时使用 --pager-reader --upload 时，会先完整完成榜单采集，再运行一次 pager-reader 处理整个榜单 JSON，最后上传完整的榜单级 *-cn.json；如果只使用 collect --source arxiv --upload，会在队列结束后上传本次生成的榜单 JSON。

当 collect 同时使用 --translate --upload 时，如果当前轮次同时生成了 Markdown 和 JSON，会先翻译这两个文件，再上传翻译后生成的 *-cn.json。translate --upload 也会上传翻译后生成的 .json 文件，比如把 2026-04-26-03.json 翻译后上传 2026-04-26-03-cn.json；如果这次翻译里没有任何可上传的翻译后 .json 文件，会直接报错。

translate 和 pager-reader 都优先读取 ~/.deep-radar/deep-radar.json 里的 agent 配置：

• 如果没有传 --agent，会优先使用 agent.defaultAgent 指向的 Agent ID
• 如果传了 --agent，优先把它当成 Agent ID 解析
• 如果没有命中配置里的 Agent ID，仍然兼容直接传底层 provider：codex、claude、opencode
• 如果没有 agent.defaultAgent，默认使用 codex

底层调用直接使用各 agent 的原生命令：

• opencode -> opencode run
• codex -> codex exec
• claude -> claude -p

安装依赖：

npm install

HTTP 读取服务已经拆分到独立的 deep-radar-server 项目中。

可以用那个项目来读取和服务 ~/.deep-radar/raw/x 或任意自定义采集目录下的数据。

~/.deep-radar/deep-radar.json 示例：

{
  "apikey": "drsk_your_api_key",
  "serverUrl": "http://127.0.0.1:3000",
  "agent": {
    "defaultAgent": "writer",
    "writer": {
      "agent": "opencode",
      "cwd": "/absolute/path/to/your/project"
    },
    "reviewer": {
      "agent": "claude",
      "cwd": "/absolute/path/to/another/project"
    }
  },
  "storage": {
    "rawDir": "~/.deep-radar/raw"
  },
  "collect": {
    "timeRangeHours": 24
  },
  "x": {
    "authToken": "your_auth_token",
    "ct0": "your_ct0"
  }
}

开发

npm test