reddapidev/dsh-reddit-radar

@reddapi/dsh-reddit-radar

一个 dsh 插件，它会定期扫描
reddapi.dev，寻找与一句话 ICP 描述相匹配的新 Reddit 线索，
剔除你已经看过的那些，并将新的线索写入你工作区中一份带日期的 markdown 报告。
它还会转发 reddapi.dev 的六个只读搜索/查询 MCP 工具，以便 agent 在两次运行之间
按需查询 Reddit。

它读取的内容

| | |
|---|---|
| 50K+ | 跟踪的 subreddit 数量 |
| 30M+ | 已索引的帖子数量 |
| 170M+ | 已索引的评论数量 |
| 1024D | 向量维度 |
| 5 | 分类的线索类型数量 |

为什么这比关键词提醒更好

关键词提醒会返回成千上万条无关的提及，却仍然会漏掉那些真正重要的，因为
那些想买你所卖东西的人很少会用你的词来描述它。没有人会写“我需要一个面向
B2B SaaS 的 Reddit 线索生成工具”。他们会写“你们都是怎么在不花钱投广告的
情况下找到客户的”。

reddapi.dev 匹配的是含义，而不是拼写。你的 ICP 句子会被嵌入到与每一条
已索引帖子相同的 1024 维空间中，所以当一条帖子的含义相同时，它就会出现在
你的报告里，无论是否有任何一个关键词重叠。在此之上还有意图评分：每条线索
都会按信号强度获得 0-100 的评分，并自动打上线索类型、情感和行业标签，
因此到达你报告中的是那一小撮准备购买的人，而不是每一个碰巧说了某个词的
人。reddapi.dev 主页上的演示数据集平均达到 96% 的意图评分。

这正是此插件中定时扫描的全部意义所在：你写一句关于你卖给谁的话，然后一份
带日期的 markdown 文件就会出现，里面是本周用自己的话描述了那个问题的人，
并附有回复链接。

它的功能

- 定时线索扫描。 按你选择的频率（weekly / daily / hourly
/ manual），它用你的 ICP 作为查询调用 reddapi.dev 的 /api/v1/leads，
过滤掉它已经报告过的线索，并将其余的写入
/.md。
- 一个手动工具，reddit_radar_run， 它会立即运行一次，而不是等待
定时计划。
- 六个转发工具 —— reddit_semantic_search、reddit_vector_search、
reddit_list_subreddits、reddit_get_subreddit、reddit_get_trends、
reddit_find_leads —— 它们是 reddapi.dev 自身 MCP 端点之上的薄壳，因此
agent 可以直接搜索 Reddit，而不只是看到定时的摘要。
- 一行通知，在下次会话开始时显示，当某次运行发现了新线索、撞到配额
上限，或 API 密钥被拒绝时。

安装

npm install @reddapi/dsh-reddit-radar

然后将其添加到你的 cordis.yml 中（参见下面的完整示例）。

⚠️ 配置此插件前你必须知道的三件事

1. days 必须与 schedule 保持一致，否则你会永远重复扫描同一周

默认值是 schedule: weekly 搭配 days: 7 —— 每次运行都会查看最近的
7 天的 Reddit 活动，而下一次运行大约在 7 天后，因此
扫描窗口会首尾相接、无缝衔接。

如果你把 schedule 收紧为 daily（或 hourly），就必须相应缩小 days
（daily 对应 days: 1）。如果你在按天运行的同时保留 days: 7，
每一次运行都会重新扫描同一个滚动周——你会看到的大部分线索
都是已经报告过的，并且白白消耗配额去重新抓取你已经看过的数据。
days 只接受 1 | 7 | 30 | 90（reddapi.dev 的白名单）；请选择
最接近你实际运行频率的值。

| schedule | 推荐的 days |
|---|---|
| hourly   | 1（没有 <1 的选项——这仍会过度扫描，请谨慎使用） |
| daily    | 1 |
| weekly   | 7（默认） |
| manual   | 在你触发 reddit_radar_run 时，任何合理的窗口都可以 |

2. 免费层配额与 MCP 工具调用共享——每 7 天 3 次，而不是每月

免费 reddapi.dev 账户现在拥有完整的 API 访问权限，与所有付费层级相同，
因此免费账户的密钥开箱即可用于 /api/v1/leads 和此插件——
无需订阅。

免费账户得到的不是一刀切的封锁，而是一个很小的共享
配额：每个固定 7 天窗口 3 次请求——该窗口每
周四 00:00 UTC 重置。这不是日历月，也不是滚动
窗口。这个配额池
在 reddapi.dev 网站搜索 UI、每个 /api/v1/ 端点、
/api/leads 以及 MCP tools/call 之间共享——也就是说，你用免费密钥所做的一切
都共用一个计数器。

在默认的 weekly / days: 7 频率下，radar 自身的计划扫描
每个窗口消耗 1 次请求。配额池剩下的部分如何使用
完全由你决定——计数器并不关心调用来自哪里。

⚠️ 这是最可能坑到你的地方：下面六个转发的 MCP 工具
也计入同一个配额池。* MCP 协议方法——
initialize、tools/list、resources/list、prompts/list——是免费的
握手调用，不消耗配额，但每一次实际的 tools/call
都会消耗——包括 reddit_semantic_search、reddit_find_leads 以及
此插件转发的另外四个工具。如果你的 agent 在一次对话中哪怕只调用其中两三个，
仅此一项就可能耗尽整个每周 3 次的
免费额度。该窗口内下一次计划 radar 运行届时将
以 429 失败（见故障排除），而不是写出报告。这是
机制，不是建议——这三次请求怎么花由你决定，只需知道计划扫描和
临时工具调用会消耗同一个计数器。付费方案
（Lite 及以上）拥有大得多的、按方案特定的每月/每日配额，没有
这种与 MCP 共享的冲突风险——见
reddapi.dev/pricing。

3. 没有“每周一上午 9 点”——只有频率层级 + 心跳

dsh 0.1.0-rc.6 没有为第三方插件提供 cron 功能。插件
唯一能使用的调度原语是固定间隔计时器——没有
cron 表达式，也没有挂钟目标时间。
（@deepseek-ai/dsh-schedule 看起来可能填补这个空白，但它实际上是一个agent 作用域、会话级的“提醒我”工具，绑定到特定根 agent 的事件日志——插件无法针对它注册后台任务。）

所以 schedule: weekly 并不意味着“每周一 09:00”——它意味着一个节奏层级加上持久化的心跳：每小时（或者如果层级短于一小时，则每个 tick），插件检查距离上次运行过了多久，只有当该时长 ≥ 层级的持续时间时才运行。后果：

- 重启宿主进程不会触发额外运行——上次运行时间会被持久化，并在重启后保留（在可用时存储在宿主自己的存储中，否则存储在 outDir 中的 .state.json 文件里）。
- 如果宿主关闭了一段时间，启动后的下一次心跳将恰好补上一次运行（而不是每个错过的 tick 补一次运行）。
- weekly 运行实际落在一天中的哪个时间会漂移，取决于当某个 tick 落在距上次运行 ≥7 天之后时宿主恰好正在运行——它不会固定到特定的某天或某个小时。

如果你需要在特定时间运行，请使用 schedule: manual 并自行触发 reddit_radar_run（例如，从你自己的外部 cron 命中该 agent，或通过 dsh-schedule 的会话级提醒）。

配置参考

| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| apiKey | string | —（必填） | reddapi.dev API 密钥。免费账户现在也可用——登录 reddapi.dev 并打开 /account；密钥会自动生成，无需订阅。免费层配额很小，且与 MCP 工具调用共享——在依赖它之前，请参阅上文“免费层配额与 MCP 工具调用共享”。 |
| icp | string | —（必填） | 一句话：你卖什么、卖给谁。原样用作搜索查询。 |
| schedule | 'weekly' \| 'daily' \| 'hourly' \| 'manual' | 'weekly' | 'manual' 不注册任何定时器——只有 reddit_radar_run 工具。 |
| days | 1 \| 7 \| 30 \| 90 | 7 | 只考虑最近 N 天的帖子。必须与 schedule 保持一致——见上文。 |
| outDir | string | .dsh/reddit-radar | markdown 报告（以及 .state.json 回退文件）的存放位置。相对路径相对于进程的工作目录解析。 |
| maxPerRun | number | 10 | 每份报告写入的最大线索数（1–50）。被此限制截断的线索仍可在后续运行中被拾取。 |

完整的 cordis.yml 示例

- id: reddit-radar
name: '@reddapi/dsh-reddit-radar'
config:
apiKey: rk_live_xxxxxxxxxxxxxxxx   # get one at https://reddapi.dev (Account → API Keys)
icp: We sell a Reddit lead-gen tool to B2B SaaS founders
schedule: weekly                  # weekly | daily | hourly | manual
days: 7                           # 1 | 7 | 30 | 90 — keep in sync with schedule
outDir: .dsh/reddit-radar
maxPerRun: 10

在 reddapi.dev 获取 API 密钥——登录并打开
/account；密钥会自动生成，免费账户也包含在内。关于免费密钥实际能支撑多少用量（3 次请求 / 7 天窗口，与六个转发的 MCP 工具共享），以及付费计划更大且不共享的配额，请参见上文“免费层配额与 MCP 工具调用共享”。

| 计划 | 价格 | 搜索次数 |
|---|---|---|
| Free | 永久 $0 | 3 / 7 天 |
| Lite | $19.9 /月 | 500 /月 |
| Starter | $49 /月 | 5,000 /月 |
| Pro | $99 /月 | 15,000 /月 |
| Team | $249 /月 | 50,000 /月 |

每周扫描每周消耗 1 次搜索，因此任何付费层级都会把当月剩余配额留给 agent 自己的临时搜索。当前数据见 reddapi.dev/pricing。

转发的 MCP 工具

这六个工具注册为轻量外壳，直接转发到 https://reddapi.dev/api/mcp 的 tools/call，并复用你配置中的同一个 apiKey。它们的参数 schema 在插件启动时从 reddapi.dev 自己的 tools/list 实时拉取——本插件不会硬编码或复制它们，因此不会与实时 API 脱节：

| 工具 | 作用 |
|---|---|
| reddit_semantic_search | 用自然语言提问。有一个 LLM 步骤会读取意图，因此它能像人提问那样处理问题。 |
| reddit_vector_search | 同一个 1024D 索引，但不经过 LLM 步骤：更快、更便宜，按含义而非措辞匹配。当 agent 已经知道自己要找什么时使用它。 |
| reddit_list_subreddits | 分页列出已跟踪的 subreddit。 |
| reddit_get_subreddit | 查询单个 subreddit 的详情。 |
| reddit_get_trends | 按热度排序的 Reddit 热门关键词。 |
| reddit_find_leads | 一次性线索搜索（与定时雷达使用的底层端点相同）。 |

对这六个工具中的每一个调用都是一次 tools/call，针对 reddapi.dev 的 MCP 端点；在免费账户上，它会从与定时雷达扫描本身相同的每 7 天 3 次池中扣除——请参见上文“免费层配额与 MCP 工具调用共享”。initialize/tools/list（插件启动时用于获取 schema，仅使用一次）是免费的协议握手，不计入配额。

如果启动时无法获取 reddapi.dev 的工具列表——网络抖动、apiKey 被拒绝（无效、输入错误或已撤销——这不再是计划层级问题，包括 Free 在内的每个计划都有 API 访问权限），或 reddapi.dev 短暂不可达——这六个工具在该会话中就是不会注册。除了一条警告之外，这是有意保持静默的：定时雷达（插件的实际职责）不依赖它们，无论哪种情况都会继续正常运行。如果你没有看到这些工具可用，请检查 apiKey 是否有效以及 reddapi.dev 是否可达，然后重新加载插件。

故障排除

401/403 和 429 对本插件来说含义非常不同，处理方式也非常不同——不要把它们当作同一种“出问题了”的信号。

“your reddapi.dev quota is used up”（429）——免费账户上常见的情况
现在所有方案（包括免费方案）都可以访问 API，因此配置正确的密钥通常根本不会遇到 401/403。免费账户更可能遇到的是 429：共享的每 7 天 3 次配额（参见上文“免费层配额与 MCP 工具调用共享”）用完了——通常是因为六个转发的 MCP 工具与定时雷达扫描在同一个 7 天窗口内被使用。

本插件将 429 视为配额问题，而非认证错误，并且不会因此停止计时器。定时雷达会继续运行；下一次运行（按照你的 schedule 节奏）会直接重试，而等到 weekly 运行再次轮到时，7 天配额窗口通常已经重置了。无需重新加载或重新配置。屏幕上的提示文本（“……Upgrade at reddapi.dev/pricing to resume”）是与付费方案超额情况共用的模板文案——在免费账户上，升级是可选的，并非必需：等待下一个 7 天窗口即可免费重置同样的 3 次请求。只有当你希望雷达扫描和六个 MCP 工具不再争抢同一小池配额时，才需要升级。

“the configured reddapi.dev API key was rejected”（401/403）——调度已停止

这是 reddit-radar 在收到来自 /api/v1/leads 的实际 401 或 403 后显示的提示。与 429 不同，本插件将两者视为同一种认证错误结果，并有意停止计时器，以免它在后台永远失败下去。由于现在每个方案层级都可以访问 API，这基本上始终是真正的凭据问题，而不是方案问题：

1. 检查是否有拼写错误、多余空白，或密钥已在账户仪表板中被轮换/撤销。
2. 确认密钥是从你预期的同一个 reddapi.dev 账户复制的——/account 每个账户只生成一个密钥。
3. 修复密钥后，重新加载插件——计时器已被拆除，不会自行恢复；重新加载配置会重新注册它。（429 从不需要这一步——只有 401/403 会拆除调度。）

开发

npm install
npm test          # vitest, 69 cases
npm run build      # tsc -p tsconfig.build.json → dist/

纯决策逻辑（哪些线索是新的、一次运行结果意味着什么、报告如何渲染）不依赖 dsh 或网络，并且单独进行了单元测试；另一套测试针对最小化的假宿主覆盖了调度/心跳/工具注册的接线；还有一套测试验证实际构建产物能在真实 Node ESM 下加载（而不仅仅是构建能干净退出）。