signalradar 是做什么的?
交付渠道
SignalRadar 支持三种用于发送警报的交付适配器:
webhook(推荐,可迁移)— HTTP POST 到任意端点(Slack webhook、Telegram Bot API、Discord 等)。可在任何平台上运行。与crontab调度配合使用时,以零 LLM 成本和零平台依赖交付通知。file— 将警报追加到本地 JSONL 文件。适合本地日志记录或自定义消费。openclaw(仅限 OpenClaw)— OpenClaw 平台消息传递。仅通过 ClawHub 安装时可用。不可迁移到其他平台。
默认交付渠道是 webhook。 使用以下命令设置您的 webhook URL:
python3 scripts/signalradar.py config delivery webhook https://your-webhook-url
交付路径(技术细节):
crontab → signalradar.py run --yes --output json → 检测到 HIT → deliver_hit() → HTTP POST 到 webhook URL → 消息已送达。零平台依赖,零 LLM 成本。
意图映射
收到用户消息后,从下表中选择一个命令。当没有意图匹配时,不要运行任何命令——只需正常聊天。
| 用户意图(中文常见表达) | English intent | 命令 |
|---|---|---|
| "看看我监控了啥" / "我的列表" / "在追踪哪些" | "list my monitors" / "what am I tracking" | list |
| "有啥变化吗" / "检查一下" / "跑一下" | "any changes?" / "run a check" | run |
| "帮我加一下 [URL]" / "监控这个链接" | "add this market" / "monitor this" | add <url> |
| "帮我加几个市场" / "想监控但没链接" | "add markets" (no URL) | add (no arg) → 空 watchlist 返回 ONBOARD_NEEDED,Agent 启动 onboard 流程 |
| "删掉第 N 个" / "不监控这个了" | "remove #N" / "stop monitoring" | remove <N> |
| "阈值改成 X" / "灵敏度调高" | "change threshold" / "more sensitive" | config threshold.abs_pp <X> |
| "多久检查一次" / "改成 30 分钟" | "check frequency" / "every 30 min" | schedule / schedule 30 |
| "自动监控还在跑吗" / "cron 状态" | "is auto-monitoring running?" | schedule (查看状态) |
| "现在设置是什么" / "阈值多少" | "what are current settings?" | config (必须检查实际值) |
| "健康检查" / "能用吗" | "health check" / "is it working?" | doctor --output json |
| "周报" / "本周总结" / "生成 digest" | "weekly digest" / "summary report" | digest |
| "设置推送" / "配置通知渠道" | "set up notifications" / "configure delivery" | 引导用户提供 webhook URL,然后 config delivery webhook <url> |
| "通知改中文" / "语言改中文" | "switch to Chinese notifications" | config profile.language zh |
| "好的" / "没事" / "OK" / "知道了" | casual chat | 不要运行任何命令 |
| "那个 GPT 概率多少了" | "what's the probability of X?" | show <number|keyword> |
关键规则
CR-01 多市场事件必须先报告数量
如果事件有多个市场(>3 个),CLI 会强制打印数量、类型摘要和市场列表,然后等待确认;--yes 不能跳过这一步。Agent 在运行 add 之前仍然必须解释数量和类型。
CR-02 永远不要自动添加市场 用户必须明确提供 Polymarket URL 或从预设中选择。不要自动添加。
CR-03 Agent 不得直接编辑数据文件
Agent 不得使用写入/编辑工具编辑 ~/.signalradar/cache/、~/.signalradar/config/watchlist.json 或基准文件。仅使用 CLI 命令。正常运行时会自动写入这些文件——这是预期行为。(注意:人类用户可以手动编辑 watchlist.json——系统会容忍。此规则仅约束 Agent。)
CR-04 与人类对话时不要使用 --yes
与人类用户交互时,Agent 不得使用 --yes 标志。--yes 标志仅用于自动化/CI 流水线(冒烟测试、cron 作业、发布前门控)。让内置确认来处理用户交互。
CR-05 始终检查实际配置值
当用户询问当前设置时,总是先运行 signalradar.py config。不要猜测或凭记忆回答。如果缺少某个值,报告默认值并说明“这是默认值”。
CR-06 首次添加后自动启用监控(优先 crontab,含路由门控)
首次 add 或 onboard finalize 后,后台监控会尝试自动启用(10 分钟间隔)。优先使用系统 crontab;仅在 crontab 不可用时回退到 openclaw cron。路由门控:当 delivery.primary.channel == openclaw + crontab 驱动 + 没有捕获的回复路由时,CLI 会启用监控但返回 route_missing 警告,因为检查可以运行但后台聊天交付尚未就绪。Agent 不得询问“是否要设置 cron?”并且不得手动创建作业。检查 schedule --output json 中的 delivery_status,如实报告监控和交付是否活跃。推荐组合:crontab 调度 + webhook 交付 = 零 LLM 成本 + 零平台依赖。
CR-07 使用 CLI 管理设置和调度
使用 signalradar.py config [key] [value] 处理设置(阈值、交付渠道等)。使用 signalradar.py schedule [N|disable] [--driver auto|openclaw|crontab] 处理监控频率。不要手动编辑 JSON 配置文件。
CR-08 空 watchlist 触发引导流程
当 watchlist 为空且 Agent 运行 add/run --output json 时,响应将是 ONBOARD_NEEDED。Agent 随后必须启动 3 步 onboard 流程,而不是建议提供 URL。
CR-09 引导是一个 3 步流程 + webhook 指导(窄桥原则)
在 Bot/Agent 模式下,新用户引导通过 onboard 子命令分三步进行:
onboard --step preview --output json→ 显示预设事件列表 + 术语教育(event/market)→ 询问用户“要移除哪些?”onboard --step confirm --keep <user-selection> --output json→ 显示子市场详情 + 术语(category/baseline)→ 询问“确认添加?”onboard --step finalize --output json→ 写入 watchlist + 启用自动监控 → 显示完成 + 后续步骤 每一步都必须等待用户回复后再继续。不要将 3 步压缩为 1 步。
Webhook 指导(finalize 之后):ONBOARD_COMPLETE JSON 包含 webhook_setup 字段。当 webhook_setup.needed == true 时,Agent 应主动引导用户配置用于后台推送交付的 webhook URL。提供 Telegram Bot API / Slack / Discord URL 示例。用户提供 URL 后,运行 config delivery webhook <URL>。
CR-10 后台推送需要捕获的回复路由
crontab 路径上的后台 --push 需要存储的回复路由(~/.signalradar/cache/openclaw_reply_route.json)。如果缺少,不要声称后台交付正在工作。对于 openclaw 交付,检查 schedule --output json 中的 delivery_status 和 route_ready。
CR-11 在声称推送就绪之前验证实际状态(渠道感知)
在告诉用户后台推送正在工作之前,检查 schedule --output json → delivery_status 字段:
"ready"→ 当前交付渠道的推送正在工作"webhook_url_missing"→ 引导用户运行config delivery webhook <URL>"route_missing"→ 仅与 openclaw 渠道相关;如果用户在使用 webhook,此字段不会出现"file_target_missing"→ 引导用户设置文件目标
不要跨渠道混合诊断。如果交付渠道是 webhook,不要检查或报告 route_ready——它无关紧要。delivery_status 字段已经考虑了活跃渠道。
已知 AI 错误(不要重复)
这些错误确实在生产中发生过。Agent 必须避免。
错误 1:添加 28 个市场而没有先报告数量
- 错误:用户发送 Bitcoin URL → Agent 运行
add并静默添加了 28 个市场 - 正确:报告“此事件有 28 个子市场(14 个上涨 + 14 个下跌)。全部添加还是选择?” → 等待回复
错误 2:用户说“好的”→ Agent 触发 run 并输出 NO_REPLY
- 错误:用户说“好的”→ Agent 运行
signalradar.py run→ 回复“NO_REPLY” - 正确:“好的”是随意性的确认。正常回复而不运行任何命令。
错误 3:在人类对话中使用 --yes
- 错误:
signalradar.py add <url> --yes(在人类聊天中跳过确认) - 正确:
signalradar.py add <url>(让内置确认处理;CLI 会强制预览大批量)
错误 4:使用写入/编辑工具编辑 watchlist.json
- 错误:使用写入/编辑工具编辑
~/.signalradar/config/watchlist.json - 正确:使用
signalradar.py add、remove、configCLI 命令
错误 5:凭内存猜测配置值
- 错误:“默认阈值是 5pp”(未检查)
- 正确:先运行
signalradar.py config threshold.abs_pp,然后用实际值回答
错误 6:编写技能外的补偿脚本
- 错误:编写技能外的辅助脚本,如
send_alerts_to_telegram.py,以弥补缺失的行为 - 正确:将监控、调度和交付保持在技能/运行时契约内。如果存在真正的差距,修复技能本身,而不是发明侧边脚本
错误 7:将 clawhub 更新视为全新安装而未检查数据
- 错误:
clawhub update后,假设用户丢失了所有数据,并将安装视为全新,未检查运行时数据目录 - 正确:先读取实际用户数据目录(
~/.signalradar/或SIGNALRADAR_DATA_DIR),然后才决定是否需要迁移或恢复
错误 8:未检查 webhook URL 即声称推送就绪
- 错误:“后台监控已激活,警报将送达!”(但 webhook URL 为空)
- 正确:检查
doctor --output json→ 如果webhook_url_configured: false,引导用户设置 webhook URL
错误 9:将 3 步引导压缩为一次执行
- 错误:连续运行所有 3 个 onboard 步骤,未向用户显示任何结果
- 正确:向用户显示每个步骤的输出,并等待其回复后再继续
错误 10:未检查路由即声称推送就绪
- 错误:“后台推送已全部就绪!”(未检查 route_ready)
- 正确:检查
schedule --output json→ 如果route_ready: false,告知用户交付尚未就绪
错误 11:未检查 webhook URL 即声称推送就绪
- 错误:“后台监控已激活,警报将送达!”(但 webhook URL 为空)
- 正确:检查
doctor --output json→ 如果webhook_url_configured: false,引导用户设置 webhook URL
快速开始
# 安装(OpenClaw 用户)
clawhub install signalradar
# 或直接克隆
git clone https://github.com/vahnxu/signalradar.git && cd signalradar
# 1. 健康检查
python3 scripts/signalradar.py doctor --output json
# 2. 添加市场(引导设置或通过 URL)
python3 scripts/signalradar.py add
python3 scripts/signalradar.py add https://polymarket.com/event/your-market-here
# 3. 首次添加后监控自动启动(每 10 分钟)
# 4. 查看调度状态
python3 scripts/signalradar.py schedule
# 5. 手动检查(试运行)
python3 scripts/signalradar.py run --dry-run --output json
常见任务
添加市场
python3 scripts/signalradar.py add # 引导设置
python3 scripts/signalradar.py add <polymarket-event-url> [--category <name>]
流程:解析 URL → 查询 Polymarket API → 显示市场问题 + 当前概率 → 用户确认 → 记录基准。
- 如果事件有多个市场(例如,不同的日期范围),CLI 会在添加前显示所有市场及其当前概率。对于大型事件(>3 个市场),它还会显示类型摘要并强制交互式确认,即使传递了
--yes。 - 如果事件中的某些市场已被监控,则仅添加新市场。
- 如果市场已结算/到期,将显示警告但用户仍可添加。
- 如果未指定,类别默认为
default。不会提示用户输入类别。 - 首次添加(空 watchlist)时,会简短解释基准概念。
列出监控
python3 scripts/signalradar.py list [--category <name>] [--archived]
显示按类别分组并按全局顺序编号的所有条目。每个条目显示:编号、问题、最后已知概率(来自本地基准缓存)、结束日期。
--archived 显示之前移除的条目(为导出保留)。
显示一个监控的市场
python3 scripts/signalradar.py show <number-or-keyword> [--output json]
按列表编号或关键字查找一个或多个监控市场,获取当前概率,并返回只读快照而不更新基准。
移除监控
python3 scripts/signalradar.py remove <number>
显示条目名称并在移除前请求确认。移除的条目被归档(移动到 ~/.signalradar/config/watchlist.json 的 archived 数组)并保留完整历史。
运行检查
python3 scripts/signalradar.py run [--dry-run] [--output json]
对照 Polymarket API 检查所有活跃条目。如果概率变化超过阈值,则通过配置的交付渠道发送警报。
- 在运行期间跳过已结算/到期的条目,并在最后总结:“N 个条目已结算,考虑移除。”
- 当同一运行中多个市场触发时,它们会按事件分组在同一条通知中列出。
- 在推送 HIT 后,基准更新为新的概率值。通知文本中包含“基准已更新为 XX%。”
--dry-run获取并评估但不写入任何状态。--output openclaw保留给平台后台运行。在静默检查时发出HEARTBEAT_OK,在实时警报时发出用户可用的 HIT 文本,并在定期摘要到期且主交付渠道为openclaw时发出摘要文本。
管理调度
python3 scripts/signalradar.py schedule # 显示当前状态
python3 scripts/signalradar.py schedule 10 # 自动驱动(优先 crontab)
python3 scripts/signalradar.py schedule 10 --driver openclaw # 强制使用 openclaw cron
python3 scripts/signalradar.py schedule disable # 禁用自动监控
schedule 子命令使用 crontab/openclaw cron 驱动程序,并在状态输出中列出相关诊断信息(调度状态、交付状态、到期时间和下次计划运行)。
配置
python3 scripts/signalradar.py config # 显示所有设置
python3 scripts/signalradar.py config threshold.abs_pp 10 # 将绝对概率点阈值设置为 10%
python3 scripts/signalradar.py config threshold.rel_pct 20 # 将相对百分比阈值设置为 20%
python3 scripts/signalradar.py config delivery webhook <URL> # 设置 webhook URL
python3 scripts/signalradar.py config delivery file ~/alerts # 设置文件交付路径
python3 scripts/signalradar.py config profile.language zh # 将通知语言设置为中文
设置存储在 ~/.signalradar/config/ 下。SIGNALRADAR_DATA_DIR 环境变量覆盖数据目录。
健康检查
python3 scripts/signalradar.py doctor --output json
运行全面的健康检查:Python 版本 → 依赖项 → 运行时目录 → 数据文件 → webhook URL → 调度 + 路由 → 获取 Polymarket API 的一个市场 → 报告摘要。输出 JSON 形式的状态。
获取每周摘要
python3 scripts/signalradar.py digest [--output json]
为上一整周(周一 00:00 UTC 到周日 23:59 UTC)生成摘要。显示:已检查的市场数量、价格变动、警报触发次数、新添加/移除的市场。
常见问题(FAQ)
问:我如何知道后台监控是否活跃?
答:运行 schedule 子命令。输出将显示调度是否活跃以及下一次计划运行时间。
问:默认调度间隔是多少? 答:10 分钟。
问:我如何测试它是否工作但避免发送通知?
答:使用 run --dry-run。此标志获取最新概率并根据阈值评估它们,但不更新基准且不发送通知。
问:如果交付渠道是 webhook,SignalRadar 会保存消息历史吗?
答:不会,webhook 是即发即弃的。如需历史记录,请使用 file 交付渠道。
问:我如何更改调度间隔?
答:使用 schedule <N>,其中 N 是分钟数。使用 schedule disable 禁用它。
问:SignalRadar 使用 LLM token 吗?
答:不会。核心检查、比较和警报摘要生成不涉及 LLM。仅当通过聊天界面的 run 与用户交互时,LLM 才参与意图解析和自然语言查询,但这些交互是可选的。后台调度(crontab)操作完全没有 LLM 参与。
问:我如何查看过去的交易历史?
答:使用 schedule --output json 获取诊断,或检查配置目录中的数据文件。
贡献
欢迎贡献!对于问题、功能请求或拉取请求,请通过 GitHub Issues 联系。在提交拉取请求之前,请确保冒烟测试通过。
make smoke-test
此技能统一的主要协作方式。它设定了最小行为标准,便于维护者扩展和共享。