stock-signal-ledger

# Signal Ledger / 聪明钱观点账本

一个可直接运行的“观点与情报审计 Agent”。第一板块每 6 小时从指定 X 账号增量抓取帖子，用 Qwen 抽取个股、行业和市场判断，到期后以真实行情验证；第二板块聚合 Osiris、Third‑Eye 与美国财政部 OFAC 的重大公开事件，把事件拆成对股票、行业、领域和市场的利多/利空影响链。两部分统一在带登录保护的中文仪表盘中展示。

## 已实现

- 首次抓取最近 30 天，后续按 X `since_id` 增量抓取，不重复消费旧帖子。
- 一条帖子中的多条独立判断拆成多行；只有明确的前瞻判断或买卖/回避建议才入表。
- 必备字段全部覆盖：判断来源、判断类型、判断对象、判断趋势、原因原文摘录、到期验证时间、到期验证结果。
- 作者没给期限时使用可解释的默认口径：个股/行业 30 天、市场 7 天；页面会明确标注“系统默认”。
- 个股用自身价格；行业用映射 ETF；美股市场默认 SPY。涨/跌达到 ±3% 算命中，震荡落在 ±3% 内算命中。
- “波动加大/收窄”比较到期窗口与此前等长窗口的年化实现波动率，变化至少 15% 才算命中。
- 服务进程内每 6 小时自动调度，systemd 负责进程异常后的自动恢复。
- 页面手动刷新与定时任务调用完全相同的抓取、抽取、去重和验证流水线。
- 按作者汇总最近 3 天帖子；只有帖子集合变化时才重新调用模型，避免重复消耗额度。
- 判断账本支持按表头排序，并可按作者、类型、对象、趋势、原因、发布时间、到期时间和验证结果筛选。
- 账本同时展示判断产生时间、到期验证时间、验证口径、结果与原帖详情。
- 全球情报板块只读取能形成交易传导的重大离散事件：重大新闻、战争/GDELT 冲突、制裁、火山、较强地震、重大天气、网络漏洞和太空天气告警。
- 不抓取航空轨迹、船舶位置、港口、CCTV 或卫星位置等高体量遥测。Third-Eye 的普通火点也不进入流水线，`fires` 接口只提取火山事件。
- 重大制裁除新闻识别外，还轻量读取 OFAC 官方最新制裁更新及详情摘要；不会下载完整制裁数据库，也不会把个人 SDN 明细送入模型。
- 同一事件跨平台自动合并，保留平台、底层信息源和证据链接，避免重复情报制造虚假热度。
- 通过上述轻量规则进入候选池的重大事件会全部接受 Qwen 审查并进入事件视图；没有明确指数方向的事件保留并记 0 分，不再因为缺少行业结论而从页面消失。
- Qwen 将每个事件拆成多条资产影响链；同一事件可以同时对不同对象产生利多与利空，并显示期限、置信度和反向条件。
- 每个事件都对纳斯达克综合指数、富时中国A50、沪深300、恒生指数和日经225生成一组结构化评分因子；最终 -100 到 +100 分由代码统一复算，模型不能直接决定展示分数。
- 影响结果经过代码级质量防线：剔除抽象目标、未知或错配代码，灾害对保险业的短期方向按理赔逻辑校正；偏远地震和只有监测标记、没有产能中断证据的火山事件不会形成资产影响。
- 外部证据链接只接受 HTTP/HTTPS 协议；模型分析结果不会自动触发交易或外部操作。
- 全球情报支持按类别、方向、平台、期限、关键词和重要度筛选或排序。
- 全球情报提供事件视图与指数视图：事件卡片内展示五个指数的单项影响分；每个指数卡片汇总所有相关事件、单项分数、利多/利空复合压力和组合净分。
- 页面手动刷新只要求用户已经登录，不再额外询问刷新密钥。
- 支持全文搜索、详情查看和 UTF-8 CSV 导出。
- 未配置密钥时自动进入明确标注的演示模式，不会把模拟记录冒充真实判断。

## 工作方式

```text
X API 增量帖子
  ├─ Qwen 结构化抽取 → 判断账本 → 到期行情验证
  └─ 最近 3 天滚动缓存 → Qwen 博主简报

Osiris + Third-Eye 重大事件 + OFAC 制裁更新
  └─ 轻量事件过滤 → 跨来源去重 → Qwen 结构暴露/传导因子 → 代码复算五指数影响分

浏览器 → 登录保护 → 仪表盘 / CSV / 手动刷新
```

运行数据保存在 `data/store.json`。该文件、日志和 `.env` 均不会进入 Git；仓库只保留 `data/.gitkeep` 作为持久化目录占位。

## 默认追踪名单

| 账号 | 主要用途 | 备注 |
|---|---|---|
| `@aleabitoreddit` / Serenity | AI、半导体供应链、个股 | 用户指定，主题集中度较高 |
| `@BillBrooklyn10` / Bill Brooklyn | 明确买卖清单 | 用户指定；身份与履历未核验，页面有风险提示 |
| `@StockMarketNerd` | 个股基本面、财报 | 推荐加入，用来平衡纯题材/动量观点 |
| `@LizAnnSonders` | 宏观、风格与市场结构 | 推荐加入，用来覆盖整体市场判断 |

名单在 [`src/config.js`](./src/config.js) 的 `SOURCES` 数组里，增删账号不需要改抓取逻辑。

## 本地运行

要求 Node.js 20 或更高版本；本项目没有第三方 npm 依赖。

```bash
cp .env.example .env
# 编辑 .env，至少填 X_BEARER_TOKEN 和 DASHSCOPE_API_KEY
npm start
```

打开 <http://localhost:8787>。首次启动会在约 2 秒后自动跑一轮，也可以点击“立即刷新”。

### 密钥

- `X_BEARER_TOKEN`：X Developer Portal 创建 App 后获得的只读 Bearer Token。只读取公开帖子，不需要发帖权限。
- `DASHSCOPE_API_KEY`：阿里云百炼 API Key，供默认的 Qwen 抽取引擎使用。
- `AI_PROVIDER`：默认 `qwen`。如所在地区支持 OpenAI API，也可改为 `openai` 并配置 `OPENAI_API_KEY`。
- `OSIRIS_BASE_URL`、`THIRD_EYE_BASE_URL`：两个 OSINT 平台的 API 根地址；默认使用公开演示站。OFAC 使用固定的官方 Recent Actions 地址。
- `INTELLIGENCE_LOOKBACK_DAYS`：保留并展示的情报回看天数，默认 7 天。
- `INTELLIGENCE_MAX_ANALYZE`：每轮最多交给模型分析的新增事件数，默认 40；进入模型前已过滤遥测、弱地震、普通火点和过期事件。

密钥只从环境变量读取；`.env` 和运行时数据文件都已加入 `.gitignore`。

## 数据和验证口径

运行时状态保存在 `data/store.json`，写入时使用临时文件原子替换。生产部署需要把 `/app/data` 挂载到持久卷，否则容器重启会丢失历史。

价格验证使用 Yahoo Finance 图表接口返回的复权日线：

1. 起点取发帖当天或之后第一个可用交易日。
2. 终点取到期日当日或之前最后一个可用交易日。
3. 涨：区间收益 `>= +3%`；跌：`<= -3%`；震荡：绝对收益 `< 3%`。
4. 阈值可用 `VALIDATION_THRESHOLD_PCT` 修改。
5. 行情暂缺时标记“行情数据暂缺”，后续每轮自动重试，不会误判。

行业映射在 [`src/config.js`](./src/config.js) 的 `INDUSTRY_BENCHMARKS` 中。无法识别的行业当前用 SPY 兜底，并在页面明确标注。

## 五大指数影响分

每个重大事件都保留在事件视图中，并对五个指数分别生成一条记录。Qwen 只负责依据事件证据和指数结构选择标准化传导通道，并给出 `exposure`（指数暴露）、`transmission`（传导清晰度）、`confidence`（方向证据可靠性）、方向和期限；最终分数、因果链与反向条件均由代码生成，模型的自由文本指数解释不会直接展示：

```text
证据基础分 = 20% × 事件相关度
           + 20% × 事件严重度
           + 30% × 传导清晰度
           + 25% × 方向置信度
           +  5% × 独立来源广度

单事件指数影响分 = 方向符号 × 证据基础分 × (指数暴露/100) × 新鲜度因子 × 期限系数
```

- 方向符号：利多 `+1`、利空 `-1`、中性 `0`。
- 事件严重度：低 25、中 40、较高 60、高 80、极高 100。
- 独立来源广度：1 个底层来源 60、2 个 80、3 个及以上 100。
- 指数暴露是乘法闸门而不是加法项：直接暴露不足时，不能靠事件严重度或泛化的风险情绪把分数补高。80—100仅用于指数本国/地区经济或高权重成分群的直接暴露；50—79用于重要成分行业；20—49用于间接商品、利率、汇率或供应链渠道；泛化风险情绪低于20。
- 新鲜度：3.5 天半衰期；先算 20—100 的新鲜度分，再转换为 `0.55 + 0.45 × 新鲜度/100`，所以当前 7 天窗口中的事件不会只因时间衰减到零。
- 期限系数：即时 1.00、短期 0.90、中期 0.75、长期 0.60。
- 硬门槛：方向为中性、指数暴露 `<10`、传导清晰度 `<20` 或方向置信度 `<40`，一律记 0 分。
- 代码级暴露校准：单一 CVE/厂商漏洞、没有广泛贸易或行业传导的窄范围名单更新，以及既不触及指数本地经济、也没有系统性变量通道的域外局部冲突，指数暴露上限为 9，因此强制记 0；页面会显示模型原始暴露、校准后暴露和原因。
- 分数经四舍五入并限制在 `-100…+100`：负数表示利空，正数表示利多；`±80…100` 极强、`±60…79` 强、`±40…59` 中等、`±1…39` 弱、`0` 为中性或证据未过门槛。

指数视图的组合净分不直接相加：相同指数、同传导通道、同方向的第 `n` 条事件先乘 `1/√n`，避免同一风险机制被不同新闻类别重复堆高；利多与利空分别按 `100 × (1 − Π(1 − |有效分|/100))` 合成为两侧压力，组合净分等于利多压力减利空压力。这些分数是可审计的相对事件冲击，不是预计收益率、涨跌概率或仓位建议。

## 6 小时自动刷新

服务进程存活时，内置调度器会按 `REFRESH_INTERVAL_HOURS` 同时运行大 V 抓取、到期验证和全球重大事件刷新；在 VPS/systemd 或 Docker `restart: unless-stopped` 环境中不需要额外 cron。登录后的页面可以直接手动刷新，不再要求第二个刷新密钥。

只需要初始化或重跑全球情报板块、不想重复抓取全部 X 帖子时，可执行：

```bash
npm run refresh:intelligence
```

## API

- `GET /api/data`：仪表盘全部数据与运行状态
- `GET /api/export.csv`：导出账本
- `GET /api/health`：健康检查
- `POST /api/refresh`：运行一次完整刷新；网页环境需要有效登录会话

## 测试

```bash
npm test
```

测试覆盖抽取结果清洗、基准映射、方向阈值、波动率规则、区间收益验证，以及重大新闻、GDELT、火山、较强地震、OFAC 制裁更新、跨来源去重、多方向影响链清洗、代码映射白名单、置信度和页面契约。X、Qwen、行情和 OSINT 接口属于外部集成，真实密钥下的刷新用于最终端到端检查。

## 部署提示

可以直接使用仓库中的 `Dockerfile` 和 `compose.yaml`。容器仅绑定服务器回环地址 `127.0.0.1:8787`，公网必须通过 HTTPS 反向代理访问；裸机运行时设置 `HOST=127.0.0.1` 达到同样效果。生产环境至少需要：

- 持久化 `/app/data`
- 注入 `.env.example` 中的环境变量
- 配置 `APP_USERNAME`、`APP_PASSWORD_HASH` 和随机 `APP_SESSION_SECRET`；额外账号使用 `APP_USERS_JSON` 的“用户名 → scrypt 哈希”映射
- 配置 HTTPS；只用公网 IP 时，可用 Let’s Encrypt 短期 IP 证书并自动续期
- 安全组只开放公网 80/443；SSH 仅允许管理员固定 IP

推荐将应用作为独立服务运行，并用 Caddy 或 Nginx 反向代理到 `127.0.0.1:8787`。仓库的 [`deploy/nginx-ip.conf.template`](./deploy/nginx-ip.conf.template) 可作为 Nginx 起点；使用域名时，Caddy 可以自动管理 HTTPS 证书。

访问保护覆盖首页、数据 API、CSV 和手动刷新接口。密码使用 scrypt 哈希存储，登录 Cookie 带签名、`HttpOnly` 和 `SameSite=Strict`；同一来源 15 分钟内连续失败 5 次会被暂时锁定。生成密码哈希：

```bash
node scripts/hash-password.mjs '你的至少12位密码'
```

多账号示例（主账号仍使用上面的两个单值变量）：

```text
APP_USERS_JSON={"analyst":"scrypt$盐$派生值","reviewer":"scrypt$盐$派生值"}
```

本工具只做观点记录、公开情报拆解与可重复的事后检验，不会自动交易，也不构成投资建议。平台风险标记、模型传导分析与股票代码映射都可能出错，作出决策前必须回看原始证据。