PolyHermes/openspec/changes/add-leader-research-agent/design.md at 7c8761a049096282ec706bbc9623d2e126f2afeb

gavindiaz/PolyHermes

Fork 0

Files

T

codyhhchenandcodychen123 a3f74b8567 feat: add leader research agent

2026-05-05 18:17:51 +08:00

9.3 KiB

Raw Blame History

Context

PolyHermes 当前已有三层跟单工作流：

Leader 管理 保存可被跟单的钱包地址，对应 copy_trading_leaders。
Leader 池 管理人工候选、观察、小额试跟、冷却、淘汰，对应 copy_trading_leader_pool。
跟单配置 管理真实账户、leader 和风控参数，对应 copy_trading。

这个结构已经把“地址库”和“真钱跟单”拆开，但仍需要用户自己去找 leader、判断是否值得观察、跟踪表现、决定是否小额试跟。用户的目标不是手动维护池子，而是让系统自动发现优秀且可复制的 leader，先纸跟验证，再由用户授权真钱动作。

本设计把新增能力定位为 Leader Research Agent。它是研究代理，不是自动交易代理。它可以自动发现、自动纸跟、自动建议、自动冷却；它不能自动启用真钱跟单。

Goals / Non-Goals

Goals:

提供多源候选发现，第一阶段支持 watchlist、已有 Leader 管理记录和 activity-derived candidates。
为研究运行、候选、分数、事件、纸跟 session、纸跟交易、纸跟持仓建立独立数据模型。
持久化原始或规范化 activity event，使纸跟可以基于可重放事件运行，而不是复用真实订单表。
用透明规则计算 copyability score，并保存分项分数和 score version。
自动推进研究状态，但研究状态必须与 Leader 池状态分离。
在不锁定的情况下，自动化只能保守地增强 Leader 池记录，不能自动改成真实 TRIAL 或 ACTIVE。
提供操作台展示运行状态、候选详情、纸跟表现、待处理决策和源健康。
提供手动审批动作，创建保守的 enabled=false 真实跟单配置。
为源失败、quote 不可用、valuation unknown、重复事件、锁定候选、非法真钱启用等关键路径提供可见错误和测试。

Non-Goals:

不自动启用真钱跟单。
不自动加仓、不自动增加 fixed amount、不自动放宽风控参数。
不做黑盒 AI/ML 评分。
不在第一阶段依赖公开 leaderboard 端点。
不复用 copy_order_tracking 作为纸跟账本。
不把 unknown valuation 当成 confirmed zero。
不替换现有 Leader 池、Leader 管理、跟单配置和真实 PnL 统计。

Decisions

1. 研究状态独立于 Leader 池状态

研究状态回答“系统证明了什么”，Leader 池状态回答“用户当前怎么处理这个 leader”。两者不能合并。

研究状态：

DISCOVERED -> CANDIDATE -> PAPER -> TRIAL_READY
                         \-> COOLDOWN -> RETIRED

Leader 池状态：

CANDIDATE -> WATCH -> TRIAL -> ACTIVE
          \-> COOLDOWN -> RETIRED

映射规则：

research DISCOVERED
  -> 可以只存在于 leader_research_candidate，不强制创建 Leader 池项

research CANDIDATE
  -> 展示给用户时可创建或更新 Leader 池 CANDIDATE

research PAPER
  -> Leader 池保持 WATCH，或后续 UI 暴露 PAPER

research TRIAL_READY
  -> Leader 池保持 WATCH，并展示“建议小额试跟” badge
  -> 不能自动变成 Leader 池 TRIAL

research COOLDOWN
  -> 未锁定时可以同步 Leader 池 COOLDOWN

research RETIRED
  -> 只有 agent 拥有且未锁定的候选，才可同步 Leader 池 RETIRED

TRIAL_READY 只是建议。只有用户创建了真实禁用试跟配置后，Leader 池才可以进入 TRIAL。

2. 纸跟必须独立建账

enabled=false 的真实跟单配置不会产生模拟成交、模拟持仓、过滤原因、quote confidence 和纸跟 PnL。把它伪装成纸跟会让后续晋升建议没有证据链。

新增建议表：

leader_paper_session
leader_paper_trade
leader_paper_position

每笔纸跟交易至少记录：

leader_trade_id
leader_price
leader_size
simulated_price
simulated_size
simulated_amount
fill_assumption: LEADER_PRICE | BEST_ASK_AT_EVENT | MID_PRICE | UNKNOWN
quote_confidence: HIGH | MEDIUM | LOW | UNKNOWN
quote_source
quote_timestamp
filter_result: PASSED | FILTERED
filter_reason
valuation_status: AVAILABLE | NO_MATCH | UNAVAILABLE | CONFIRMED_ZERO

UNAVAILABLE 和 UNKNOWN 不得计为真实归零。这个约束必须沿用到纸跟 PnL 和前端展示。

3. 第一阶段先做可重放事件和内部来源

第一阶段候选来源：

watchlist
已有 Leader 管理记录
已持久化 activity event 中可归因的钱包

公开 leaderboard 保留为后续来源，不作为第一阶段 apply-ready 的依赖。原因是 leaderboard 端点可能不稳定或未文档化，不能让第一版核心闭环被外部端点卡住。

如果当前 app 没有持久化 raw activity event，需要新增 append-only 表：

leader_activity_event

推荐唯一键：

source + event_id

如果 event_id 缺失，必须生成稳定 fallback key，避免重启或重放时重复纸跟。

4. 评分必须可解释且可版本化

不要只保存一个总分。保存分项分数、总分、score version 和 reason。

分项：

profit_signal
repeatability
liquidity_fit
entry_price_fit
slippage_risk
holding_period_fit
market_type_risk
drawdown_risk
exit_liquidity_risk
data_freshness
filter_pass_rate

研究状态迁移必须记录 rule version，避免以后调整阈值后无法解释旧决策。

默认阈值：

DISCOVERED -> CANDIDATE
  条件：候选来自可信来源，地址格式有效

CANDIDATE -> PAPER
  条件：score >= 60，未锁定，未退休，source 48 小时内新鲜

PAPER -> TRIAL_READY
  条件：
    纸跟时间 >= 7 天
    模拟交易数 >= 10
    copyable PnL > 0
    最大回撤 >= -15%
    UNKNOWN quote 暴露占比 <= 20%
    filtered-trade ratio < 50%
    无 critical risk flag

PAPER -> COOLDOWN
  条件：
    最大回撤 < -20%
    或 10 笔后 copyable PnL < -5
    或 quote/source stale > 72 小时
    或存在 thin_liquidity_exit_risk

COOLDOWN -> CANDIDATE
  条件：cooldown_until 已过，source 重新新鲜，未锁定

COOLDOWN -> RETIRED
  条件：3 次冷却周期，或 30 天无新鲜来源

这些阈值是第一版保守默认值，不是金融真理；后续可配置。

5. 后端强制真钱边界

研究代理可以推荐小额试跟，但不能启用真钱。

手动审批流：

用户打开候选详情
  -> 点击“创建禁用试跟配置”
  -> 前端展示 fixed amount、max daily loss、max daily orders、price range、max position value
  -> 用户确认
  -> 后端组装 CopyTradingCreateRequest
  -> 后端强制 enabled=false
  -> 返回 created copyTrading
  -> 用户必须去 跟单配置 页面手动启用

后端必须忽略或拒绝任何客户端传入的 enabled=true、更大 fixed amount 或更松风控参数。安全边界在后端，不在弹窗。

6. 操作台先做“晨报式”决策界面

第一版页面不做复杂量化终端。优先回答：

今天有什么变化？
哪些候选需要我决策？
为什么推荐？
证据是什么？
风险是什么？
我能安全点击什么？

页面模块：

Run Status
Candidate Detail
Paper Sessions
Pending Decisions
Source Health

7. 调度必须有 overlap guard 和 run record

新增 LeaderResearchJobService 使用现有 Spring @Scheduled 模式，但默认关闭或可配置开启。

每次运行必须创建 leader_research_run，记录：

status
started_at
finished_at
duration
source counts
candidate counts
error class
error message
partial failure flag

如果上一次运行还未结束，新运行 MUST 跳过并记录 overlap 事件，不能并发推进状态。

Risks / Trade-offs

[纸跟精度看起来比实际更高] -> 每笔纸跟交易必须保存 fill assumption、quote confidence 和 valuation status；UI 必须展示 unknown/partial 状态。
[source 失败导致错误降级候选] -> source failure 只更新 source health，不得静默删除候选或降低 score。
[自动状态机误伤人工决策] -> locked=true 的候选和池子项不得被自动化改变状态、建议配置或 trial recommendation。
[通知系统 Telegram-first] -> 第一阶段先落 leader_research_event 和控制台提示，外部通知渠道在事件流稳定后再复用/扩展通知配置。
[表数量增加导致复杂度上升] -> 用里程碑拆分：先数据 spine，再纸跟，再评分状态机，再 UI/通知，再手动审批。
[数据量增长影响性能] -> 为 event、candidate、paper trade、paper position、run、event 表添加唯一键和查询索引，并对详情列表分页。

Migration Plan

新增研究与纸跟相关 Flyway 迁移，所有表为空表创建，不修改现有真实订单热表。
部署后端，但 research job 默认关闭。
部署前端操作台，若 job 未启用则展示禁用/空态。
在本地或测试环境手动运行 research job，验证 run record、source health、candidate、paper session 和 paper trade。
开启 watchlist + existing leaders 来源，不启用 public leaderboard。
确认内部 research events 稳定后再接外部通知渠道。
最后启用手动“创建禁用试跟配置”入口。

Rollback:

如果 job 出错，关闭 research job 配置并保留数据表。
如果 UI 出错，隐藏菜单或回滚前端路由。
如果迁移失败，在启用 job 前停止部署；不要在热回滚中删除已有研究数据。

9.3 KiB Raw Blame History Unescape Escape