股哨兵 Stock Sentinel
美股投资进攻/防守信号判断与示警工具。
产品定位
股哨兵不做选股建议，只回答"现在是进攻时机还是防守时机"：
- 长线选股遵循奥地利经济学派（供需决定价格），交由用户自行按"优质国家/龙头产业/龙头企业"原则选定标的。
- 短线时机遵循政治经济学（政策扰乱市场价格），工具核心价值是把货币/财政/行政三方面政策松紧转化为清晰的 🟢进攻 / 🟡中性 / 🔴防守 三档信号。
- 进攻 = 买在无人问津处（政策松无可松）；
- 防守 = 卖在人声鼎沸时（政策开始收紧）。
- 进攻信号采用 AND 逻辑（三方面政策必须同时宽松），防守信号采用 OR 逻辑（宁可错杀）。
覆盖范围仅限美股（不含房产）。
信号计算
四维信号全部自动数据驱动（管理员可手动覆盖），每日通过决策树合成最终信号：
| 信号位 | 数据来源 | 判定规则 |
|---|
| AI供需（长线主线） | SMH−SPY 90天相对收益（三层行情回退）+ FRED IPG3344S 半导体产出同比 | 相对收益 ±8%、产出同比 >+5%/<0%，双源一致才定档；泡沫预警触发强制收紧 |
| 货币政策 | FRED DFEDTARU 利率 + WALCL 资产负债表（核心PCE/Trimmed PCE/失业率仅参考展示） | 单次调整 ≥50bp 应对式→收紧；QT只拦截宽松评级不单票定罪（回测实证QT是环境收紧非危机信号） |
| 财政政策 | FRED MTSO133FMS 联邦月度支出 | "大市场小政府"原则：滚动12月支出同比扩大 >5%→收紧（政府变大），收缩 >5%→宽松（政府瘦身）。用支出不用赤字：减税型赤字不应判收紧 |
| 行政政策 | FRED EPUTRADE（月度贸易专项）+ USEPUINDXD（日频EPU 7日均线）+ DCOILWTICO（WTI油价，战争冲击实时代理） | 油价30天涨跌 ≥±20% 事件层优先：飙升=战争/供给冲击→立即收紧；暴跌且EPU未处高位=战争结束/降级→立即宽松（EPU同时高企=危机需求型暴跌，不判宽松）；否则EPU双源10年百分位 >80→收紧，<50→宽松，一致才定档 |
全局叠加（防守分级）：进攻 = 四维全宽松（AND）；仅单维收紧 = 减仓观望（部分仓位）；双维以上收紧 = 全面防守；萨姆锁（SAHMREALTIME ≥0.5）与应对式调整锁（利率单次 ≥50bp）激活时强制全面防守，直到零利率或 <50bp 小幅调整解锁。
泡沫监测（按 AI 产业链现金流向排序）：模型调用量趋势（OpenRouter，7日/28日均量 <−10% 预警）→ 云厂商滚动4季资本开支（SEC EDGAR，同比 <0% 预警）→ 半导体产出同比。任一预警 → AI供需强制收紧。
可信度工程：单维度数据源故障时沿用上一次有效判定（stale-keep，前端标灰提示"数据延迟"），不降级为中性，避免故障日误发"解除防守"警报。
档位变化 / 任一维度转收紧 / 泡沫预警触发时，通过 Resend 邮件提醒订阅用户。
个股/ETF 维度展示自选标的的历史价格百分位位置，以及当前 P/E、P/S 快照（不做买卖建议）。
历史回测报告见 docs/backtest-report.md。详细设计见 docs/superpowers/specs/2026-07-05-stock-sentinel-design.md。
技术栈
- 后端：Node.js + Express + sql.js（WASM SQLite）+ node-cron + bcryptjs + JWT
- 前端：Vue 3 + Vite + vue-i18n（中/英/法/德/西/日/韩 七语言）
- 测试：Vitest
- 数据源：FRED API（宏观/财政/行政/半导体产出）、行情三层回退 Yahoo→Tiingo→TwelveData（+FMP估值）、SEC EDGAR XBRL（云厂商capex）、OpenRouter（模型调用量）、Federal Register API（政策参考素材）
目录结构
StockSentinel/
├── backend/
│ ├── server.js # Express 入口，路由 + cron 任务
│ ├── config/signal.config.js
│ ├── api/ # fetch-macro / fetch-stocks / fetch-federal-register / signal / admin / auth / watchlist
│ ├── utils/ # storage(sql.js 封装) / mailer(Resend)
│ └── tests/
└── frontend/
└── src/
├── components/ # SignalBadge / MacroPanel / WatchlistPanel / SignalTimeline / AdminPanel
├── views/ # HomeView / LoginView / AdminView
├── i18n/locales/ # zh en fr de es ja ko
└── stores/auth.js
本地运行
环境变量
在 backend/.env 中配置：
FRED_API_KEY=your_fred_api_key
JWT_SECRET=your_jwt_secret
ADMIN_EMAIL=your_admin_email
RESEND_API_KEY=your_resend_api_key
TIINGO_API_KEY=your_tiingo_key # 行情备用源（可选）
TWELVEDATA_API_KEY=your_twelvedata_key # 行情备用源（可选）
FMP_API_KEY=your_fmp_key # P/E、P/S 估值补全（可选）
OPENROUTER_API_KEY=your_openrouter_key # 模型调用量泡沫监测（可选）
PORT=3001
启动后端
cd backend
npm install
npm run dev
npm test
启动前端
cd frontend
npm install
npm run dev
npm run build
面向 AI 时代：开放API / MCP / Skill
本项目已全面 AI 化，任何 AI 客户端或第三方开发者都可以调用信号系统：
| 通道 | 位置 | 说明 |
|---|
| 开放 REST API | /v1/*（OpenAPI 规范） | X-API-Key 鉴权；免key试用 25次/日/IP，free 250/日，pro 10000/日；密钥在管理后台签发 |
| MCP Server | mcp/ | Claude Desktop/Cursor 等一行配置接入，6个工具（当前信号/历史/产业链/个股/回测/日报） |
| Claude Skill | skills/stock-sentinel/ | 教 AI 正确理解四维框架与解读规范 |
| AI 日报 | /v1/daily-report | 每日 cron 后 LLM 自动生成中英双语信号解读（经 OpenRouter，可配 AI_REPORT_MODEL） |
| 公开 Track Record | 网站 /track-record | 每日信号档位不可篡改存档 + 回测成绩，供任何人验证 |
所有输出均附免责声明：仅供研究参考，不构成投资建议。
当前状态
MVP 已完成：信号计算、鉴权、自选股、后台管理、邮件提醒、多语言 UI，27/27 测试通过。
MVP 范围之外（后续迭代）：付费订阅墙的实际启用、个股估值指标扩展、移动端原生 App/小程序、Google OAuth 登录接入。