PolyScout 技术文档

版本：v1.0 更新日期：2026-02-25 作者：小周（GPT-5.3-Codex）审阅：露露（Claude Opus 4.6）

1. 目标与范围

PolyScout 是一个用于 Polymarket 机会扫描的轻量系统，目标是：

定时抓取市场数据
按规则筛选候选机会
记录全量扫描/信号/决策日志
在 Web 面板可视化给范总查看
通过 Discord 推送高价值信号

本阶段不做全自动下单，先做"扫描 + 决策支持 + 记录闭环"。

2. 系统架构（MVP）

Polymarket API → scanner → SQLite → signal-engine → SQLite(signals) → notifier + web-panel

组件	职责
`scanner`	定时抓取 Polymarket 市场数据（REST）
`signal-engine`	按阈值与规则计算信号
`notifier`	Discord 推送（仅高置信度）
`storage`	SQLite 持久化（后续可升 PostgreSQL）
`web-panel`	查看市场、信号、日志、日报
`decision-hook`	仅在需要时调用模型做一次决策建议（可开关）

3. 技术栈

层	技术
语言	Python 3.11+
HTTP	httpx
定时	APScheduler 或 cron
存储	sqlite3 / SQLAlchemy
Web API	FastAPI
前端面板	Next.js（可复用现有风格）
进程管理	PM2
反代	Caddy（80/443放通后）

4. Polymarket API 对接

4.1 拉取对象

市场列表（含状态、结束时间、流动性、价格）
单市场详情（必要时补拉）
历史成交/价格（可选，Phase 1增强）

4.2 采样策略

默认每 60 分钟全量扫描一次
临近结算窗口（<24h）可额外 15 分钟增量扫描

4.3 失败重试

单请求超时：8s
重试：指数退避最多3次
连续失败写入 run_logs 并告警 Discord

5. 信号规则（MVP）

候选进入条件（可配置）：

市场状态可交易
距离结算在配置窗口内（例如 6h~72h）
流动性 >= 最小阈值
盘口价格偏差/风险收益比达到阈值
过滤异常市场（极端低流动性、异常波动）

输出字段：

字段	说明
`signal_score`	0-100 综合评分
`expected_edge`	预期收益率
`risk_level`	low / med / high
`reason_tags`	命中规则标签（JSON）

6. 数据库 Schema（SQLite）

6.1 markets

字段	类型	说明
id	INTEGER PK	自增
market_id	TEXT UNIQUE	Polymarket市场ID
title	TEXT	市场标题
category	TEXT	分类
status	TEXT	状态
close_time	DATETIME	结算时间
liquidity	REAL	流动性
price_yes	REAL	YES价格
price_no	REAL	NO价格
volume_24h	REAL	24h交易量
fetched_at	DATETIME	抓取时间

6.2 scans

字段	类型	说明
id	INTEGER PK	自增
run_id	TEXT	运行批次ID
started_at	DATETIME	开始时间
finished_at	DATETIME	结束时间
total_markets	INTEGER	总市场数
qualified_markets	INTEGER	合格市场数
error_count	INTEGER	错误数
status	TEXT	状态

6.3 signals

字段	类型	说明
id	INTEGER PK	自增
run_id	TEXT	关联扫描批次
market_id	TEXT	关联市场
signal_score	REAL	信号评分
expected_edge	REAL	预期收益
risk_level	TEXT	风险等级
reason_tags	TEXT	规则标签(JSON)
decision_needed	BOOLEAN	是否需要决策
created_at	DATETIME	创建时间

6.4 decisions

字段	类型	说明
id	INTEGER PK	自增
signal_id	INTEGER	关联信号
decision_source	TEXT	rule/ai/manual
decision	TEXT	watch/enter/skip
note	TEXT	备注
created_at	DATETIME	创建时间

6.5 run_logs

字段	类型	说明
id	INTEGER PK	自增
run_id	TEXT	关联批次
level	TEXT	info/warn/error
message	TEXT	日志内容
created_at	DATETIME	创建时间

6.6 trades（预留）

字段	类型	说明
id	INTEGER PK	自增
market_id	TEXT	关联市场
side	TEXT	YES/NO
size	REAL	金额
entry_price	REAL	入场价
exit_price	REAL	出场价
pnl	REAL	盈亏
status	TEXT	状态
created_at	DATETIME	创建时间
closed_at	DATETIME	关闭时间

7. Cron 调度

任务	频率	cron表达式	说明
`scan_hourly`	每小时	`0 * * * *`	全量扫描
`daily_report`	每日	`10 0 * * *`	UTC 00:10 汇总日报
`health_check`	每5分钟	`/5 * * *`	检查最近运行状态，异常告警

8. Web 面板设计（范总可视）

页面	功能
Dashboard	今日扫描次数、信号数、异常数、最新运行状态
Markets	市场列表、筛选、临近结算标记
Signals	信号分数排序、原因标签、风险等级
Decisions	watch/enter/skip 记录与备注
Logs	运行日志、错误日志、重试状态
Reports	日报/周报（命中率、候选转化、风险事件）

9. 部署方案（34.84.9.167）

项	值
目标主机	34.84.9.167（GCP东京）
部署目录	`/home/fzq1228/polyscout`
域名	`polyscout.darkerilclaw.com`

PM2 进程规划

进程名	说明
`polyscout-api`	FastAPI后端
`polyscout-worker`	scanner + signal-engine
`polyscout-web`	Next.js 面板

端口规划

服务	端口
API	4310
Web	4311
Worker	无对外端口

反向代理（80/443放通后）

polyscout.darkerilclaw.com → web:4311
polyscout.darkerilclaw.com/api → api:4310

10. 80/443未放通时临时访问方案

SSH隧道：ssh -L 4311:127.0.0.1:4311 user@34.84.9.167
或临时开放高位端口（如4311）给白名单IP（短期）
所有公网暴露前不放敏感配置，不放写操作接口

11. 安全与密钥管理

API Key 不入库、不写文档正文，统一环境变量
.env 权限最小化（600）
生产日志脱敏（token、cookie、secret）
发现密钥疑似泄露：立即轮换并作废旧密钥
Web 面板默认只读，交易动作需二次确认（后续）

12. 里程碑与验收（技术侧）

T+6h（MVP-Alpha）

✅ 可拉取市场
✅ 可落库
✅ 可按规则产出信号
✅ 控制台可见结果

T+24h（MVP-Beta）

✅ Discord通知可用
✅ 去重与失败重试可用
✅ 日报自动生成

T+48h（MVP）

✅ Web面板核心页可用
✅ 日志链路完整
✅ 配置化阈值可调
✅ 可支撑2周观察期运行

13. 风险清单（技术）

风险	应对
API限流	加退避与缓存
数据不一致	增加run_id快照与重跑机制
内容与交易节奏冲突	解耦，先发观察日志
端口未放通	先走隧道/内网查看，不阻塞开发

14. 下一步（立即执行）

初始化仓库结构（api/worker/web/scripts/docs）
建立 SQLite schema + migration 脚本
接通第一条市场抓取链路
输出首批信号样本到Discord测试频道
同步Web面板最小Dashboard

PolyScout 技术文档

On this page