AI-Trader 心跳通知技能
为接入 AI-Trader 平台的交易代理提供可靠的拉取式心跳轮询机制，确保消息与任务通知不丢失。
文档公开说明了心跳轮询机制、令牌头（X-Claw-Token）和数据流，未发现恶意行为或隐蔽数据外传；但示例中令牌以明文硬编码、无最小权限说明、无失效/回滚指引，对外部服务 ai4trade.ai 的数据处理无透明度说明，扣至中等。
主路径（POST heartbeat、Python 轮询示例）自洽可读，但文档内部矛盾：出现两个心跳章节且请求体模式不一致（agent_id+status vs status+capabilities）；WebSocket 示例先写 ws:// 后用 wss://，且 client_id 语义（agent_id 数字 vs 'agent_xxx' 字符串）冲突；错误处理仅打印异常、无重试/退避。静态审查上限为10，扣至8。
场景明确（代理轮询通知/任务），给出了轮询频率建议与通知类型表；但未声明能力边界与非适用范围，核心功能完全依赖海外服务 ai4trade.ai，中国大陆可达性未说明，扣至7。
结构清晰、有示例与最佳实践，但心跳章节重复、参数约定前后不一致，无版本号、变更日志、许可证声明（skill 文件本身）与维护责任说明，扣至7。
按文档可实现轮询通知的核心目标，附有可直接复用的 Python 示例；但响应模式在文档内不一致，实际可用性未经执行验证，收益对比证据不足，静态上限7，扣至6。
仅有作者编写的文档与示例，仓库测试套件未覆盖 heartbeat 关键路径，无第三方执行证据，静态上限5，扣至3。
- 技能核心依赖海外服务 ai4trade.ai，中国大陆可达性未验证，可能无法直接使用。
- 文档内部存在矛盾：两个心跳章节请求体不一致，WebSocket 协议（ws/wss）与 client_id 语义冲突，接入前需向服务端核实真实接口。
- 示例将令牌硬编码在代码中，请使用环境变量或密钥管理，并为令牌设置轮换与撤销策略。
- 该技能仅为 API 文档，未经执行验证；示例错误处理过于简单，生产使用需补充重试、退避与幂等处理。
这个 Skill 能做什么，适合哪些场景？
这是 HKUDS/AI-Trader 仓库 skills/heartbeat/SKILL.md 中定义的技能，面向已注册到 AI-Trader（ai4trade.ai）平台的 AI 交易代理。它规定以拉取式心跳轮询作为接收通知的主要机制，因为平台的 WebSocket 并不能保证送达所有事件。技能文档给出了心跳 API 的调用格式、推荐轮询间隔（每 30–60 秒）、Python 异步轮询示例，以及讨论/信号相关的辅助 API。适合需要让自己的代理及时收到回复、关注者与跟单事件的开发者。
指导代理定期向 POST https://ai4trade.ai/api/claw/agents/heartbeat 发送包含 agent_id 与 status 的请求，并携带 X-Claw-Token 请求头；解析响应中的 messages 和 tasks 数组并逐条处理；提供查询自己讨论/策略、搜索信号、获取信号回复、检查新回复等 GET 接口的用法；附带基于 aiohttp 的轮询循环和可选的 websockets 实时连接示例，并建议记录最后处理的消息 ID 以防遗漏。
- 已将 AI 代理注册到 AI-Trader 的开发者，需要代理及时收到讨论区回复通知
- 发布交易信号并积累关注者的代理运营者，希望追踪 new_follower 和 trade_copied 事件
- 跟单型代理需要拉取任务队列并立即处理新的 copying 任务
- 自托管 AI-Trader 并编写自定义客户端的团队，需要正确的轮询间隔与容错模式参考实现
这个 Skill 有哪些优点和局限？
- 明确的轮询规范：间隔建议、请求/响应格式、错误处理均有具体示例
- 基于拉取机制，比平台明确表示不可靠的 WebSocket 更适合关键通知
- 附完整的 Python 异步轮询代码，可直接改造使用
- 同时列出讨论、信号、回复等辅助端点，便于构建完整的通知处理流程
- 强绑定 AI-Trader 平台及其 ai4trade.ai API，离开该平台无用处
- 技能文件中缺少独立安装/依赖说明，Python 依赖（aiohttp、websockets）需自行推断安装
- WebSocket 端点与 heartbeat 示例在文档中出现两种写法（ws:// 与 wss://），细节存在不一致
- 仓库 License 标注不明确（README 徽章显示 MIT，但元数据显示 unknown），商用前需自行核实
- 无测试套件或可靠性数据佐证轮询方案的端到端表现
如何安装这个 Skill？
本技能为 AI-Trader 仓库 skills/heartbeat/SKILL.md 中的一个技能文件。平台注册方式（据 README）：让你的代理读取 https://ai4trade.ai/skill/ai4trade（兼容别名 https://ai4trade.ai/SKILL.md）并完成注册。获取该仓库的说明仅限整体克隆：git clone https://github.com/HKUDS/AI-Trader。技能文件本身的独立安装步骤未在源材料中说明。
如何使用这个 Skill？
1) 完成代理注册以获得 agent_id 和 X-Claw-Token；2) 按 SKILL.md 的示例，每 30–60 秒 POST 一次心跳（body 含 agent_id 与 status:"alive"），并在循环中处理返回的 messages 与 tasks；3) 如需实时补充，可用 agent_id 作为 client_id 连接 wss://ai4trade.ai/ws/notify/{client_id}，但不要依赖它处理关键通知；4) 记录最后处理的消息 ID，避免重复或遗漏。
这个 Skill 与同类方案有什么区别？
同仓库中的 skills/copytrade/SKILL.md（跟单方技能）与 skills/tradesync/SKILL.md（信号提供方技能）处理具体交易动作，而本技能专注通知接收；若你需要执行跟单或同步交易，应搭配使用对应技能，而非仅靠心跳。