StockSentinel MCP Server

股哨兵 Stock Sentinel

美股投资进攻/防守信号判断与示警工具：四维数据驱动信号 + 公开 Track Record + 开放 API/MCP。

产品定位

股哨兵不做选股建议，只回答"现在是进攻时机还是防守时机"：

• 长线选股遵循奥地利经济学派（供需决定价格），交由用户自行按"优质国家/龙头产业/龙头企业"原则选定标的。
• 短线时机遵循政治经济学（政策扰乱市场价格），把 AI 供需与货币/财政/行政政策松紧转化为四档信号：🟢进攻 Attack / 🟡观望 Watch / 🟠减仓观望 Reduce / 🔴全面防守 Defense。
• 进攻 = 买在无人问津处；防守 = 卖在人声鼎沸时。
• 进攻信号采用非对称 AND 逻辑（详见下文），防守信号采用 OR 逻辑（宁可错杀）。

覆盖范围仅限美股（不含房产）。

信号计算

四维信号全部自动数据驱动（管理员可手动覆盖），每日美东 21:00 cron 合成最终信号（盘后财报、电话会报道、当日收盘价均已就绪，避开 FRED 凌晨维护窗口；北京时间次日 9:00/10:00）：

全局叠加（防守分级）：

• 进攻（非对称） = AI供需宽松（主动引擎发动）+ 货币/财政/行政均不收紧（中性即可，任一收紧即否决）+ 无锁 + 美债收益率曲线（10y−3m）未处倒挂确认期（近63个交易日中倒挂 ≥51 天否决进攻档准入，2026-08-04 窗口口径）+ 信用利差（BAA10Y）90日走阔 <+60bp（2026-07-30 采纳）+ 实际利率（政策利率−12M截尾PCE）<1.5%（2026-08-04 采纳）——三个否决器均只否决进攻、不触发防守，不在信用恐慌/深度限制性利率下开最激进档位。另有趋势地板（2026-08-04）：市场跌破 10 月 SMA 时最终档位至少为减仓观望。
• 仅单维收紧 = 减仓观望：停止加仓、提高警觉，不必减存量仓位（回测实证：单维收紧月份市场月均收益不低于其他月份）。
• 双维以上收紧或锁激活 = 全面防守。例外：纯"货币+财政"双维共振（无行政维、无锁）只到减仓观望。
• 锁机制：萨姆锁（SAHMREALTIME ≥0.5）与应对式调整锁（利率单次 ≥50bp）强制全面防守；解锁 = 利率降至 ≤0.25%（零利率区间无条件解锁），或锁龄满60天且触发条件已消失时出现 <50bp 小幅调整。
• 趋势再入场：市场处上升趋势（最新收盘 ≥ 10个月末收盘SMA）时，决策树与萨姆锁驱动的全面防守降级为减仓观望（应对式调整锁不受趋势否决）。
• 降档迟滞：升档（更防守方向）即时生效；降档（更宽松方向）需持续满30天确认期。

可信度工程：数据管道四层韧性（114号，2026-07-25）——①每日更新定在美东 21:00（盘后财报/电话会报道/当日收盘价就绪，避开 FRED 凌晨维护窗口，上午发布的失业率/萨姆/PCE 当晚入判定）；②FRED 瞬时故障（超时/429/5xx）自动退避重试；③参考指标组级 stale-keep——故障日整组沿用上一快照（值+数据参考期一起，参考期如实显示旧日期，不伪造新鲜度）；④新鲜度看门狗——指标参考期超预算（月度100天/日频10天）自动运维告警，防 stale-keep 静默掩盖序列停更；⑤快照补更新（118号，2026-07-31）——快照过点未生成（定时任务被错过/中途失败）时，小时级看门狗与前端访问都会自动触发后台补跑（30分钟冷却+互斥防打爆，绝不提前跑——美东21:45前期望的是昨日快照，不生成数据不完整的早产快照），前端显示补更新横幅并在新快照落库后自动刷新。信号级：单维度数据源故障时沿用上一次有效判定（stale-keep，前端标灰"数据延迟"），不降级为中性，避免故障日误发"解除防守"警报。行情多层回退（moomoo OpenD→Yahoo→Tiingo→TwelveData），EDGAR 数据带新鲜度校验与错季对齐。指引检测双护栏（115号，2026-07-30）——web 检索只采信财报发布后的报道（财报前预览稿/分析师预期不是管理层指引）；会计政策变更致指引名义数字变化但实际投资计划不变时按实际计划判（不误触发下修事件）。

示警：档位变化 / 任一维度转收紧 / 泡沫预警 / 锁触发与解除时，通过 Resend 邮件提醒订阅用户；进/出全面防守另发 S5 执行指令邮件（仅管理员）。

历史回测报告见 docs/backtest-report.md（6 场危机 5 场触发全面防守，2026 美伊战争未达 15% 危机线由减仓分级应对；2008 年精确到顶部前 11 天。数字为 2026-07-30 快照，以报告与实时接口为准）。S5 执行手册见 docs/s5-execution-playbook.md。

面向 AI 时代：开放API / MCP / Skill

任何 AI 客户端或第三方开发者都可以调用信号系统：

所有输出均附免责声明：仅供研究参考，不构成投资建议。

后台管理（/admin，仅管理员）：信号覆盖 / 锁应急清除 / 密钥签发 / 用户管理与API用量监控 （注册与订阅状态、剩余时间与配额、按用户端点统计与30天调用明细、全站功能热度——资源投放依据）， 详见 docs/admin-guide.md。

技术栈

• 后端：Node.js + Express + sql.js（WASM SQLite）+ node-cron + bcryptjs + JWT
• 前端：Vue 3 + Vite + vue-i18n（中/英/法/德/西/日/韩 七语言）
• 测试：Vitest 全量套件（后端+前端，具体用例数以 npm test 实跑为准）
• 数据源：FRED API（宏观/财政/行政/半导体产出/收益率曲线）、行情多层回退 moomoo OpenD（本机网关，美股LV3实时，可选）→Yahoo→Tiingo→TwelveData（+FMP估值；日线口径复权源 Yahoo/Tiingo 优先于生价源）、SEC EDGAR XBRL（云厂商capex，双口径）、OpenRouter（模型调用量）、Federal Register API（政策参考素材）
• 部署：Railway（后端）+ Vercel（前端）；数据库每日备份至 GitHub 私有仓库

目录结构

StockSentinel/
├── backend/
│   ├── server.js              # Express 入口，路由 + cron 任务
│   ├── config/                # signal.config / ai-chain.config / fomc-meetings
│   ├── api/                   # signal / fetch-macro / fetch-policy / fetch-ai-chain / market-data / payloads / mcp / public ...
│   ├── backtest/              # 历史回测引擎与变体守卫
│   ├── utils/                 # storage(sql.js 封装) / mailer(Resend) / backup(GitHub) / usage-log(调用明细埋点)
│   └── tests/
├── frontend/
│   ├── public/                # robots.txt / sitemap.xml / llms.txt / favicon（SEO/GEO 发现层）
│   └── src/
│       ├── components/        # SignalHero / MacroPanel / AiChainPanel / WatchlistPanel / SignalTimeline / AdminPanel / UserPanel ...
│       ├── views/             # HomeView / LoginView / AdminView / TrackRecordView
│       ├── i18n/locales/      # zh en fr de es ja ko
│       └── stores/auth.js
├── mcp/                       # MCP Server（stdio）
├── skills/stock-sentinel/     # Claude Skill
└── docs/                      # 回测报告 / S5手册 / 方法论评审（OpenAPI 规范在 backend/openapi.yaml，随 API 部署）

本地运行

环境变量

在 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 # 行情备用源（可选）
MOOMOO_WS_HOST=127.0.0.1               # moomoo OpenD 本机网关，美股LV3实时行情（可选，三项配齐才启用）
MOOMOO_WS_PORT=33333                   # OpenD 的 WebSocket 端口（与 TCP 11111 是两个开关）
MOOMOO_WS_KEY=your_opend_ws_key        # 对应 OpenD"WebSocket鉴权密钥"字段——勿填进"WebSocket私钥/证书"(SSL文件字段)，会致OpenD设置错误无法登录；排障见 docs/moomoo-cloud-setup.md
FMP_API_KEY=your_fmp_key               # P/E、P/S 估值补全（可选）
OPENROUTER_API_KEY=your_openrouter_key # 模型调用量监测 + AI日报（可选）
CLOUDFLARE_API_TOKEN=your_cf_token # AI需求第二源：Radar全网AI bot流量趋势，仅用于usage分歧核查邮件的独立佐证，不进判定（可选，免费申请仅需Radar读权限）
GITHUB_BACKUP_REPO=owner/private-repo  # 数据库每日备份（可选）
GITHUB_BACKUP_TOKEN=fine_grained_pat   # 仅需该仓库 Contents 读写（可选）
ADMIN_PASSWORD=strong_password         # 强烈建议：启动种子管理员账户并封锁 ADMIN_EMAIL 抢注（116号）
INSTANCE_ROLE=primary                  # primary(默认,云端)|replica(本机第二实例：不群发订阅邮件、不上传备份)
BACKUP_ENCRYPTION_KEY=64_hex_chars     # 备份 AES-256-GCM 加密（可选；两实例须同钥并在密码管理器留底）
BACKEND_PUBLIC_URL=https://your-api    # 邮件一键退订链接的基址（可选，默认 Railway 域名）
PORT=3001

启动后端

cd backend
npm install
npm run dev      # node --watch server.js
npm test         # vitest run

启动前端

cd frontend
npm install
npm run dev       # http://localhost:5173，代理 /api 到 localhost:3001
npm run build

当前状态

信号体系已过七轮专家复查与多轮方法论审查（判定逻辑 v2、防守分级、收益率曲线否决、趋势再入场、降档迟滞、capex 单季侦察兵与指引下修事件 N3、信用利差进攻否决均已实证定案），全量测试用例全过，每日云端自动运行并公开存档。capex 指引自动检测为双源（EDGAR 新闻稿 + web 检索电话会/媒体），财报后单公司 capex 快报（单季/TTM 额度同比、本财年/未来指引）自动入档。第七轮系统性审查（116号，2026-07-30）修复了 FOMC 决议日货币维闪变、N3 事件绕过降档迟滞、邮件发送库错误语义（失败被计成功）、双实例重复群发与备份互踩等 30 余处，详见 docs/systematic-review-2026-07-30.md。

后续迭代：付费订阅墙的实际启用、移动端原生 App/小程序、Google OAuth 登录接入。