11 added, 0 removed. Audit B to B.
---
name: btc-radar
description: >-
安装、启动、诊断 BTC News Radar —— 一个跑在用户自己机器上的比特币影响事件雷达：
7×24 监听美国政策/监管/宏观新闻，用本机 Codex CLI 给每条消息打影响分
（方向 · 强度 · 确定性 · 时效），叠加 K 线技术面与蜡烛形态，命中用户自定义规则时
推送到手机与桌面。触发词：BTC 雷达、btc radar、比特币监控、radar setup、radar start、
radar status、装一下比特币雷达，或任何要求安装/启动/排查这个雷达的请求。
本技能不预测价格、不给买卖建议。
---
# ₿ BTC News Radar
一个**本地**比特币情报终端。数据、数据库、配置全部留在用户自己的机器上，
不上传任何地方。
## 你（Claude）该怎么用这个技能
所有操作都通过同一个零依赖脚本完成（就在本 SKILL.md 旁边的 `scripts/` 里）：
```bash
node <本技能目录>/scripts/radar.mjs <子命令>
```
| 子命令 | 什么时候用 |
|---|---|
| `setup` | 首次安装，或用户说"装坏了/修一下" |
| `start` | 启动采集与看板（后台常驻） |
| `stop` | 停止 |
| `restart` | 改完配置后 |
| `status` | 用户问"跑起来没""有数据吗" |
| `doctor` | 用户说"不工作""没数据""收不到推送" |
| `update` | 用户要新版本 |
| `where` | 需要知道安装路径时 |
+ | `autostart on\|off\|status` | 用户要开机自启，或问"重启后还在吗" |
+ | `ensure` | 计划任务内部调用，幂等，不用手动跑 |
**执行完把关键输出转述给用户，不要只说"已完成"。** 用户装这个是为了看数据，
他需要知道现在有多少条事件、评分后端通没通、看板地址是什么。
## 三条不能违反的边界
### 1. 不输出买卖建议
这个产品**刻意**不做"该做多还是做空"。原因有两条，转述给用户时两条都要说：
- 不是持牌投顾，不提供个性化投资建议
- **更重要**：没有任何系统能可靠给出这种信号，声称能做到的工具长期只会让用户亏钱
它给的是**市场结构描述** —— 事件影响分、确定性阶梯、技术面状态、蜡烛形态的几何与
位置。`Key Zone` 不是"入场点"，`失效位` 不是"止损"，`偏多` 不是"做多"。
用户问"我该买吗"，如实说这个工具不回答这个问题，然后把它能给的事实摆出来。
### 2. 会消耗用户自己的 ChatGPT 订阅额度
AI 评分通过**本机的 Codex CLI**（`codex exec`）跑。要把 `config/app.yaml` 里的
`llm.backend` 改成 `codex`（setup 会自动检测并提示）。这意味着：
- 不需要 API key，走用户已有的 ChatGPT 订阅
- **但消耗的是用户自己的额度**，而且是持续消耗（默认每 20 秒最多处理 5 条）
- 实测一天几十到几百条事件
**首次安装时必须主动告诉用户这件事**，不要等他自己发现。
嫌多可以改 `config/app.yaml` 里的评分频率。
### 3. 不替用户做外发动作
手机推送要用户自己在手机上装 ntfy App 并扫码订阅 —— 这一步无法代劳。
不要把用户的 `NTFY_TOPIC` 贴到任何公开地方：**那串就是唯一凭证**，
任何知道它的人都能收到他的推送。
+
+ ## 开机自启
+
+ `autostart on` 注册 Windows 计划任务：登录后 30 秒启动 + 每 5 分钟确保在运行。
+
+ **开启前必须告诉用户**：采集器会跟着自启，开机后就持续消耗他自己的
+ Claude / ChatGPT 额度。这一条不能省略。
+
+ 只实现了 Windows。非 Windows 会明确报错 —— **不要假装能用**。
## 平台支持
**只在 Windows 上验证过。** macOS / Linux 的代码路径写了但没实际跑过 ——
安装路径推导与进程启停未经验证。
用户在 macOS / Linux 上遇到问题时，**不要假装它应该能用**：如实说明这部分没测过，
把报错原样收集起来，建议他去仓库开 issue。桌面通知在非 Windows 平台会自动跳过，
这是预期行为，手机推送不受影响。
## 安装位置
应用装在用户数据目录，**不在插件目录里**：
| 系统 | 路径 |
|---|---|
| Windows | `%LOCALAPPDATA%\btc-news-radar` |
| macOS | `~/Library/Application Support/btc-news-radar` |
| Linux | `$XDG_DATA_HOME/btc-news-radar`（默认 `~/.local/share/…`） |
原因：插件缓存目录带版本号，升级时整个被替换 —— 数据库放里面会在某次更新后消失。
用户想换位置就设 `RADAR_HOME` 环境变量。
## 环境要求
| 项 | 要求 | 缺了会怎样 |
|---|---|---|
| Node.js | **≥ 22.5** | 装不上。存储层用 `node:sqlite`，22.5 才有 |
| git | 任意版本 | 下载不了应用 |
| pnpm | 任意 | `setup` 会尝试用 corepack 自动启用 |
| Codex CLI | 已登录（`codex login`） | 采集照常跑，但**评分会一直排队**。登录后自动补评，不用重启 |
`setup` 会逐项检查并给出人能看懂的修复指引。不要自己猜，跑 `doctor` 让脚本说。
## 装完之后
- 看板：<http://127.0.0.1:3777>
- 首次启动约 30 秒后开始出现数据；AI 评分要等 Claude Code 登录
- 手机推送：在安装目录跑 `pnpm ntfy:qr`，用 ntfy App 扫码
- 日志：安装目录下 `.run/collector.log` 与 `.run/web.log`
## 常见问题的排查顺序
**"没有数据"** → `doctor`。按这个顺序看：
1. 进程在不在（collector 没起来就什么都没有）
2. 数据源连通性（preflight 会列出哪些源不可达 —— 不同网络差别很大，
比如 Binance 主域名在某些地区不通，应用已内置官方公开镜像作为备选）
3. 评分后端（显示"待登录"就让用户跑 `codex login`）
**"收不到手机推送"** → 依次确认：
1. 手机 ntfy App 订阅的 topic 和 `.env` 里的是不是同一个
2. 看板侧栏 Alerts 面板里"今日推送额度"是不是满了（默认 1 小时 4 条、1 天 10 条，
这是**刻意**的上限，不是 bug —— 推送多到会被忽略就等于没有推送）
3. 命中记录里的"未推送原因"（冷却中 / 已静音 / 已达上限 / 未过安全闸门）
**"看板打不开"** → 端口 3777 可能被占。改 `config/app.yaml` 的 `server.port` 后 `restart`。
## 这个产品在做什么（用户问起时的说法）
它把美国政策、监管、宏观、加密行业的原始消息流，转成带结构的事件：
- **方向**（利好 / 利坏 / 中性）与**强度**（1–5）
- **确定性阶梯**（传闻 → 提议 → 已排期 → 已生效）—— 这是它和普通新闻聚合器
最大的区别。"特朗普说他支持某法案"和"该法案已签署生效"是完全不同量级的两件事
- **时效**（即时 / 数日 / 结构性），影响分随时间衰减
- 叠加技术面：RSI / MA / MACD / 布林 / ATR + 11 种可客观测量的市场状态
- 蜡烛形态识别，但**形态分只占 45%，位置与量能占 55%** ——
同一个形状出现在关键位和出现在半空中，含义完全不同
没有数据源的模块一律显示「待接入」，**不填假数字**。在金融终端里，
一个看起来合理的假数字比空状态危险得多。