交易管理器 —— 自动化止损、止盈与追踪止损

使用本技能为您的 Polymarket 头寸创建自动化交易规则（止损、止盈、追踪止损）。交易管理器作为 Vincent 后端的一部分运行，当价格条件满足时自动执行交易。

所有命令均基于 @vincentai/cli 包。

工作原理

交易管理器是 Polymarket 技能的配套组件：

1. 使用 Polymarket 技能 浏览市场并下注
2. 使用 交易管理器 为这些头寸设置自动化退出规则
3. 交易管理器通过 WebSocket 实时监控价格（HTTP 轮询作为备用机制），并在触发条件满足时，通过同一套 Polymarket 基础设施执行交易

架构说明：

• 深度集成于 Vincent 后端（无需单独部署服务）
• API 接口路径为 /api/skills/polymarket/rules/...
• 复用 Polymarket 技能所使用的同一 API 密钥
• 规则与事件数据均存储于 Vincent 数据库中
• 交易执行流程复用经策略管控的 Polymarket 管道（policy-enforced Polymarket pipeline）
• Vincent 所有策略（如支出限额、人工审批要求）依然生效

快速上手

1. 检查后台工作进程状态

创建规则前，请先确认监控工作进程正在运行：

npx @vincentai/cli@latest trade-manager health
# 预期输出：{"status":"ok","version":"0.1.0"}

npx @vincentai/cli@latest trade-manager status --key-id 
# 返回：工作进程状态、当前激活规则数量、最近同步时间、断路器状态

2. 创建止损规则

当价格跌破阈值时，自动卖出头寸：

npx @vincentai/cli@latest trade-manager create-rule --key-id  
  --market-id 0x123... --token-id 456789 
  --rule-type STOP_LOSS --trigger-price 0.40

参数说明：

• --market-id：Polymarket 条件 ID（取自市场数据）
• --token-id：您所持有的结果代币 ID（取自市场数据 —— 请使用您实际买入的代币 ID）
• --rule-type：STOP_LOSS（价格 ≤ 触发价时卖出）、TAKE_PROFIT（价格 ≥ 触发价时卖出）或 TRAILING_STOP
• --trigger-price：价格阈值，范围为 0 到 1（例如 0.40 表示 40 美分）

CLI 将自动传入 {"type": "SELL_ALL"} 作为动作（MVP 版本唯一支持的动作类型）。

3. 创建止盈规则

当价格升破阈值时，自动卖出头寸：

npx @vincentai/cli@latest trade-manager create-rule --key-id  
  --market-id 0x123... --token-id 456789 
  --rule-type TAKE_PROFIT --trigger-price 0.75

实用技巧：对同一头寸同时设置止损与止盈规则，可形成交易区间保护（bracket your trade）。

4. 创建追踪止损规则

追踪止损以初始止损价启动，随后随价格上涨自动上调该止损价。

npx @vincentai/cli@latest trade-manager create-rule --key-id  
  --market-id 0x123... --token-id 456789 
  --rule-type TRAILING_STOP --trigger-price 0.45 --trailing-percent 5

追踪止损行为说明：

• --trailing-percent 单位为百分点（例如 5 表示 5%）
• 交易管理器计算 candidateStop = currentPrice * (1 - trailingPercent/100)
• 若 candidateStop 高于当前 triggerPrice，则更新 triggerPrice
• triggerPrice 永不向下调整
• 当 currentPrice <= triggerPrice 时，规则触发

5. 查看当前活跃规则

# 查看全部规则
npx @vincentai/cli@latest trade-manager list-rules --key-id 

# 仅查看活跃规则
npx @vincentai/cli@latest trade-manager list-rules --key-id  --status ACTIVE

# 仅查看已触发规则
npx @vincentai/cli@latest trade-manager list-rules --key-id  --status TRIGGERED

6. 更新规则的触发价格

npx @vincentai/cli@latest trade-manager update-rule --key-id  --rule-id  --trigger-price 0.45

7. 取消规则

npx @vincentai/cli@latest trade-manager delete-rule --key-id  --rule-id 

规则状态将变为 CANCELED，此后不再触发。

8. 查看被监控的头寸

查看交易管理器当前正在跟踪哪些头寸：

npx @vincentai/cli@latest trade-manager positions --key-id 

返回缓存的头寸数据及当前价格。该缓存通过 WebSocket 和周期性轮询更新。

9. 查看事件日志（审计追踪）

查看规则评估与执行的详细历史记录：

# 全部事件（按时间倒序排列，默认 limit=100）
npx @vincentai/cli@latest trade-manager events --key-id 

# 指定某条规则的事件
npx @vincentai/cli@latest trade-manager events --key-id  --rule-id 

# 分页查询
npx @vincentai/cli@latest trade-manager events --key-id  --rule-id  --limit 50 --offset 100

事件类型：

• RULE_CREATED — 规则已创建
• RULE_TRAILING_UPDATED — 追踪止损上调了 triggerPrice
• RULE_EVALUATED — 工作进程依据当前价格检查了该规则
• RULE_TRIGGERED — 触发条件已满足
• ACTION_PENDING_APPROVAL — 交易需人工审批，规则已暂停
• ACTION_EXECUTED — 交易成功执行
• ACTION_FAILED — 交易执行失败
• RULE_CANCELED — 规则已被手动取消

每条事件均包含一个 data 对象，其字段依事件类型而异：

• currentPrice — 评估发生时刻的价格
• triggerPrice — 规则设定的触发阈值
• shouldTrigger — 当前是否满足触发条件
• source — 若为 WebSocket 实时更新则值为 "websocket"；轮询方式评估则该字段不存在

完整工作流：Polymarket + 交易管理器协同使用

以下是如何联合使用这两项技能：

步骤 1：使用 Polymarket 技能下注

# 搜索市场
npx @vincentai/cli@latest polymarket markets --key-id  --query bitcoin

# 在“Yes”结果上下注
npx @vincentai/cli@latest polymarket bet --key-id  --token-id 123456789 --side BUY --amount 10 --price 0.55
# 您以 55 美分价格购入 18.18 份

步骤 2：使用交易管理器设置止损

# 使用 40 美分止损价保护您的头寸
npx @vincentai/cli@latest trade-manager create-rule --key-id  
  --market-id 0xabc... --token-id 123456789 
  --rule-type STOP_LOSS --trigger-price 0.40

步骤 3：使用交易管理器设置止盈

# 若价格上涨至 85 美分，则锁定利润
npx @vincentai/cli@latest trade-manager create-rule --key-id  
  --market-id 0xabc... --token-id 123456789 
  --rule-type TAKE_PROFIT --trigger-price 0.85

步骤 4：监控您的规则

# 检查状态
npx @vincentai/cli@latest trade-manager list-rules --key-id  --status ACTIVE

# 查看近期事件
npx @vincentai/cli@latest trade-manager events --key-id 

规则触发后会发生什么？

1. 工作进程检测到触发：后台工作进程通过 WebSocket 实时比对所有活跃规则与当前价格（HTTP 轮询作为备用机制）
2. 规则标记为已触发：状态从 ACTIVE 原子性地变更为 TRIGGERED（防止重复执行）
3. 执行交易：调用 Polymarket 下注管道，提交市价卖出订单（与手动交易共用同一管道，并完整应用策略管控）
4. 记录事件：生成 RULE_TRIGGERED 与 ACTION_EXECUTED 事件

重要提示：所有由交易管理器执行的交易仍需经过 Vincent 的策略校验。若您交易违反支出限额或需人工审批，交易管理器将严格遵守相应策略。

规则状态说明

• ACTIVE — 规则处于启用状态，正被持续监控
• TRIGGERED — 触发条件已满足，交易已执行（或已尝试执行）
• PENDING_APPROVAL — 交易需人工审批；规则在审批通过或拒绝前保持暂停状态
• CANCELED — 规则在触发前已被手动取消
• FAILED — 规则已触发但交易执行失败
• EXPIRED — （未来功能，支持基于时间的自动过期）

后台工作进程

交易管理器运行一个后台工作进程，其职责包括：

• 通过 Polymarket WebSocket 数据流实时监控价格
• 若 WebSocket 不可用，则按可配置的时间间隔降级为 HTTP 轮询
• 针对每个拥有活跃规则的代理（agent），从 Polymarket API 获取当前头寸
• 每次价格更新时，对每条规则进行当前价格评估
• 当条件满足时，执行对应交易
• 记录触发事件、追踪止损调整及执行结果

断路器（Circuit Breaker）：
若 Polymarket API 连续失败达 5 次及以上，工作进程将暂停运行，并在冷却期结束后自动恢复。可通过以下命令检查工作进程状态：

npx @vincentai/cli@latest trade-manager status --key-id 

关注返回结果中的 consecutiveFailures: 0（健康状态）或 circuitBreakerUntil 时间戳（因错误而暂停）。

错误处理

常见错误

400 Bad Request — 触发价格无效：
修复方法：请使用介于 0.01 至 0.99 之间的价格

400 Bad Request — 缺少必需字段：
修复方法：确保提供全部必需参数（--market-id、--token-id、--rule-type、--trigger-price）

404 Not Found — 规则不存在：
修复方法：请核对规则 ID 是否正确

规则执行失败：
规则状态将变为 FAILED，并附带 errorMessage 字段说明失败原因。常见原因包括：

• 余额不足
• 市场已关闭或已结算
• 策略违规（超出支出限额、需人工审批）

请查阅事件日志获取详情：

npx @vincentai/cli@latest trade-manager events --key-id  --rule-id 

最佳实践

1. 始终同时设置止损与止盈，以实现头寸区间保护
2. 避免将触发价设得过于接近当前价格 — 市场噪音可能导致误触发
3. 定期监控工作进程状态 — 若断路器处于 OPEN 状态，您的规则将无法触发
4. 规则触发后及时查阅事件日志，验证交易是否成功执行
5. 头寸平仓后及时取消旧规则，保持规则列表整洁
6. 目前仅支持 SELL_ALL — 部分卖出（SELL_PARTIAL）将在 v2 版本中支持

限制条件（MVP 版本）

• 仅支持 SELL_ALL 动作（暂不支持部分卖出）
• 暂不支持基于时间的触发机制（v2 版本引入）
• 暂不支持 Telegram 通知（需手动查阅事件日志）

用户指令示例

当用户输入以下语句时：

• “为我的 Bitcoin Yes 头寸设置 40 美分止损” → 创建 STOP_LOSS 规则
• “85 美分止盈” → 创建 TAKE_PROFIT 规则
• “为我的 Bitcoin Yes 头寸设置 5% 追踪止损” → 创建 TRAILING_STOP 规则
• “我当前有哪些活跃的止损？” → 使用 --status ACTIVE 列出规则
• “取消我在市场 XYZ 的止损” → 删除对应规则
• “我的止损触发了吗？” → 检查规则状态及事件日志
• “把我的止损上调至 50 美分” → 更新规则的触发价格

重要说明

• 授权要求：除健康检查接口外，所有接口均需使用与 Polymarket 技能相同的 Polymarket API 密钥
• 深度集成于 Vincent 后端：无需独立服务或 VPS —— 交易管理器直接以内嵌方式运行于 Vincent 后端进程中，API 接口位于 /api/skills/polymarket/rules/...
• 不接触私钥：交易管理器通过 Vincent API 执行全部交易 —— 您的私钥始终安全保存于 Vincent 服务器上
• 策略强制执行：交易管理器发起的所有交易均需通过 Vincent 的策略校验
• 幂等性保障：每条规则仅触发一次 —— 即使工作进程崩溃重启亦无影响
• 数据库：规则、头寸与事件均通过 Prisma 存储于 Vincent PostgreSQL 数据库中（与其他模块共用同一数据库）