---
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` | 需要知道安装路径时 |

**执行完把关键输出转述给用户，不要只说"已完成"。** 用户装这个是为了看数据，
他需要知道现在有多少条事件、评分后端通没通、看板地址是什么。

## 三条不能违反的边界

### 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` 贴到任何公开地方：**那串就是唯一凭证**，
任何知道它的人都能收到他的推送。

## 平台支持

**只在 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%** ——
  同一个形状出现在关键位和出现在半空中，含义完全不同

没有数据源的模块一律显示「待接入」，**不填假数字**。在金融终端里，
一个看起来合理的假数字比空状态危险得多。