crypto-price

/crypto-price

加密货币价格和图表技能的路由器。

触发条件

需要查询代币价格、某段时间内的涨跌幅或图表（BTC、ETH、HYPE 等）时。

命令

/crypto-price <SYMBOL> [duration]

适用于任何受支持代币／资产的通用标准命令。

python3 {baseDir}/scripts/get_price_chart.py <SYMBOL> [duration]

实时永续合约交易对的来源路由优先使用 Hyperliquid 的 metaAndAssetCtxs，然后是加密代币的 CoinGecko，最后是传统行情代码／别名对应的 Yahoo Finance（SILVER→SI=F、GOLD→GC=F、SPX→^GSPC，以及在提供 Yahoo 行情代码时支持的外汇、股票／ETF）。

/price <SYMBOL> [duration]

面向 Telegram／网关的快捷命令封装。输出文本、验证信息和 MEDIA:<png>。

python3 {baseDir}/scripts/price_quick.py <SYMBOL> [duration]

/spaghetti <SYMBOL...> [duration]

多资产归一化折线图。用于比较同一时期的资产，例如比较 6 个月内的 SP500、GOLD 和 SILVER。它会将每条序列在第一根蜡烛处归一化为 0%，并绘制涨跌百分比，因此不同单位／价格的资产可以相互比较。

python3 {baseDir}/scripts/get_price_chart.py spaghetti SP500 GOLD SILVER 6mo
python3 {baseDir}/scripts/spaghetti_quick.py SP500 GOLD SILVER 6mo

别名：compare、multi、basket 可用作脚本命令的首项。也支持逗号分隔的输入：SP500,GOLD,SILVER 6mo。

/hype [duration]

由此技能自身提供的内置别名命令。必须保留在 crypto-price 中，不能拆分为单独的 hype 技能。

python3 {baseDir}/scripts/hype_quick.py [duration]

该别名会转交给：

python3 {baseDir}/scripts/get_price_chart.py HYPE [duration]

命令约定

每张生成的图表图片都必须在右下角包含公开署名水印：Telegram: @human20。标准蜡烛图／成交量图和 spaghetti 对比图都必须保留此水印。

时长：分钟／小时／天／周／月。紧凑格式为 <数字>[m|h|d|w|mo]，不带后缀时默认为小时。示例：30m、2h、3h、12h、24h、2d、1w、2weeks、1mo、2months；也支持 1 week、2 months、30 分钟、3 小时、1 个月 等分开书写的格式。一个月按 30 天计算。默认值：24h。

路由映射

• 来源／时长路由 → modules/source-routing/SKILL.md
• 数据获取和图表产物 → modules/price-chart/SKILL.md
• 故障／速率限制处理 → modules/ops-fallback/SKILL.md
• Hyperliquid 实时行情代码快照 → references/hyperliquid-symbol-map.md
• HIP-3／TradeXYZ 行情代码含义 → references/hip3-tradexyz-tickers.md
• 协议收入／稳定币收益率说法核验 → references/protocol-revenue-yield-checks.md

HIP-3 路由注意事项

仅检查默认永续合约市场（metaAndAssetCtxs）和现货市场（spotMetaAndAssetCtxs），不能据此断定 Hyperliquid 没有某项非加密资产。HIP-3 建设者部署的市场位于永续合约 DEX 名称下，并使用 xyz:SILVER 这类完全限定的交易对。

/price <symbol> 的正确查询顺序：

1. 检查 Hyperliquid 默认永续合约。
2. 查询 perpDexs，发现 HIP-3 DEX。
3. 对每个 DEX 使用 dex=<name> 查询 metaAndAssetCtxs，并匹配市场名称或别名。
4. 使用完整的 dex:ticker 币种字符串（例如 xyz:SILVER）查询蜡烛图，而不是仅使用 SILVER。
5. 只有完成上述步骤后，才回退到 CoinGecko／Yahoo。

TradeXYZ／HIP-3 别名示例：SILVER→xyz:SILVER、GOLD→xyz:GOLD、SPX／SP500→xyz:SP500、NASDAQ／NDX→xyz:XYZ100、WTI→xyz:CL、BRENT→xyz:BRENTOIL。更改来源路由前，请参阅 references/hip3-tradexyz-tickers.md。

协议收入／收益率说法核验

用户要求确认加密货币收入说法（+25% 年收入、储备收益分成、对代币基本面的影响）时，不要只参考网页搜索摘要。尽可能使用直接数据 API，然后明确重新计算相关说法：

• 协议收入年化运行率：DefiLlama fees API，通常按最近 30 天年化
• 稳定币供应量：按链／协议查询 DefiLlama stablecoins API
• 增幅：supply * reserve_yield * protocol_share / annualized_revenue

给出范围，并标注为粗略估算，除非团队已发布官方指引。详情以及 Hyperliquid／Coinbase／Circle 的计算示例，请参阅 references/protocol-revenue-yield-checks.md。

快速命令别名

如果特定代币的斜杠别名（例如 /hype）使用 Hermes quick_commands，且 type: exec，请将别名保留在此 crypto-price 技能中，并将快速命令指向此技能的包装脚本（scripts/hype_quick.py）。别名配置必须转发时长参数（append_args: true），或向包装脚本提供 HERMES_COMMAND_ARGS。否则，/alias 2h 可能会在不带 2h 的情况下调用此脚本，并返回默认周期的图表，看起来表面上运行成功。网关机制请参阅 hermes-agent → references/gateway-quick-commands.md。

输出约定（必需）

始终返回：

1. symbol 和 duration
2. price 和 change_period_percent（或错误）
3. chart_path（如果存在）
4. 不含多余格式的 text_plain
5. 简短的验证结果（基于 JSON/文件）

如果存在 chart_path，必须将 PNG 与 text_plain 一并附上。

发送规则（重要）

• 在 Telegram 和其他支持附件的聊天渠道中，使用 message 工具将图表作为文件发送（filePath/path = chart_path）。
• 执行 message action=send 后，只回复 NO_REPLY，避免重复。
• 不要依赖 Telegram 中 /tmp 文件的 MEDIA:，它可能无法附加。
• 如果可用的 Telegram 发送器只支持通过 MEDIA:<path> 发送文本（例如不支持单独 filePath 的 send_message），先将 PNG 从 /tmp 复制到类似 /home/hermes/workspace/artifacts/crypto_chart_<SYMBOL>_<ts>.png 的持久路径，检查 test -s/文件大小，然后发送 MEDIA:<persistent_path>。如果文本和媒体在同一条消息中发送超时，先发送简短的说明文字/验证结果，再单独发送媒体消息，最后仍然回复 NO_REPLY。
• 只有在不需要 message 工具的 web/local render 中，才将 MEDIA: 作为备用方案。

重复输出排查

如果用户展示了重复的说明文字（图表下方重复出现 HYPE... + verify...），不要一开始就重写价格脚本。先检查以下层面：

1. 运行 python3 scripts/get_price_chart.py HYPE <duration>，并确认 JSON 中只有一个 text_plain、一个 verify 和一个 chart_path。
2. 如果脚本输出没有重复，原因几乎肯定出在发送层：说明文字 + 后续文本、MEDIA: + 最终回复，或使用 message 工具后未回复 NO_REPLY。
3. 尽可能通过精确获取消息来验证 Telegram 的消息结构。如果消息 A 包含 has_media=true/照片，且价格文本作为说明文字；消息 B 包含 has_media=false，且文本相同，则这是 OpenClaw 发送去重机制将 text+media 和最终的 text-only 视为不同载荷所致。
4. 对于 OpenClaw，请检查 reply-delivery.ts、agent-runner-payloads.ts 和 block-reply-pipeline.ts；持久的修复方式是抑制后续仅文本的最终载荷（当相同文本已作为媒体说明文字发送时）。请参阅 references/openclaw-media-caption-dedupe.md。
5. 检查 transcript/session JSONL：如果 toolResult 只有一条，但 Telegram 发送记录/助手回复有两条，就应修复网关/技能的发送说明，而不是价格计算。
6. 对于 live Claw，还要检查用户消息附近的日志：内存压缩/工具允许列表失败可能会导致重复的诊断回复，但这是单独的网关/工具策略问题。

设置/依赖项检查

• 图表渲染会在 _build_chart 中导入 matplotlib。如果 JSON 返回 chart_path: null，但存在 candles，请先验证网关/快速命令所用的 Python 环境：

  /opt/hermes-agent/venv/bin/python3 - <<'PY'
  import matplotlib
  print(matplotlib.__version__)
  PY
  

• 如果该 venv 中缺少此依赖，请在该环境中安装，然后重新运行脚本：

  /opt/hermes-agent/venv/bin/python3 -m pip install matplotlib
  /opt/hermes-agent/venv/bin/python3 /home/hermes/.hermes/skills/crypto-price/scripts/get_price_chart.py HYPE 24h
  

• 将经验教训记录为“在网关使用的同一 Python 环境中安装图表依赖”，而不要声称图表功能已损坏。

快速测试清单

• /opt/hermes-agent/venv/bin/python3 /home/hermes/.hermes/skills/crypto-price/scripts/get_price_chart.py BTC
• python3 /home/hermes/.hermes/skills/crypto-price/scripts/get_price_chart.py HYPE 12h
• python3 /home/hermes/.hermes/skills/crypto-price/scripts/get_price_chart.py HYPE 2h 返回 duration: "2h"，text_plain 显示 over 2h，且 chart_path 指向一个已存在的 PNG 文件。
• python3 /home/hermes/.hermes/skills/crypto-price/scripts/get_price_chart.py HYPE 1w 返回 duration: "1w" 和一张以周为尺度的图表。
• python3 /home/hermes/.hermes/skills/crypto-price/scripts/get_price_chart.py HYPE 1mo 返回 duration: "1mo" 和一张以月为尺度的图表。
• HERMES_COMMAND_ARGS='1 week' /opt/hermes-agent/venv/bin/python3 /home/hermes/.hermes/skills/crypto-price/scripts/hype_quick.py 输出 over 1w 和 MEDIA:<png>。
• 成功时，JSON 包含 price|change_period_percent|text_plain
• 对于 2h 等较短时间窗口，请直观确认图表涵盖请求的时长，而非经过裁剪的子集。图表生成器不得为了“留白”而截断请求的 K 线窗口；计算涨跌幅和绘制 x 轴都应使用完整时长。
• 如果分形与绝对高点/低点落在同一根 K 线上，请确认图表只为该点显示一个价格标签；绝对高低点标记优先使用这些标签，以避免文字重复。
• 无效交易对返回易于理解的错误 JSON

手动审查清单

• skill 文件中没有密钥、令牌或 chat id
• text_plain 原样使用（不添加额外标记）
• fallback path 不会泄露内部 stack traces
• 命令与旧版用法 backward-compatible

完成标准

• SKILL.md 具有有效的 frontmatter 和命令契约。
• scripts/get_price_chart.py HYPE 12h 返回包含 symbol、duration、price、change_period_percent、text_plain 和可选 chart_path 的 JSON。
• 如果返回了 chart_path，则 PNG 文件存在，且可以附加到聊天渠道。
• 无效交易对返回结构化错误 JSON，且不包含 stack traces。

规范仓库 / 推送说明

• 安装在 ~/.hermes/skills/crypto-price 下的运行时文件可能不属于 git 工作树。规范的公开仓库是 https://github.com/evgyur/crypto-price.git。
• 推送运行时修复时，请克隆或同步到该仓库的干净临时检出目录；保留 .github/workflows、文档、.clawdhub、字体和发布文件等仓库元数据。
• 优先在干净检出目录中进行针对性补丁，而不是复制整个运行时文件；运行时文件可能包含空白字符或本地差异，污染规范差异。
• 除非用户要求使用其他分支，否则推送到默认远程分支（origin/HEAD；目前为 master）。
• 推送后，验证 git ls-remote 与远程 HEAD 一致；如果已配置 GitHub Actions，则轮询最新工作流运行，直到状态为 success，或明确报告失败。

向后兼容映射

• 保留旧版调用方式 python3 {baseDir}/scripts/get_price_chart.py <SYMBOL> [duration]
• 旧版说明已移至 references/legacy-SKILL.md
• 保留脚本代码的原名称，以确保兼容性
• JSON 必须同时包含 duration 和 duration_label；某些 OpenClaw 命令别名和聊天交付检查会显式查找 duration。
• scripts/price_quick.py：通用 /price <SYMBOL> [duration] 包装器；解析 argv 和 HERMES_COMMAND_ARGS，并输出 text_plain、验证行和 MEDIA:<png>。
• scripts/spaghetti_quick.py：用于规范化多资产对比图表的 /spaghetti <SYMBOL...> [duration] 包装器；默认值为 SP500 GOLD SILVER 6mo。
• OpenClaw/Hermes 中的 /hype 必须保留为同一 crypto-price 技能内的轻量别名命令，委托给 crypto-price/scripts/get_price_chart.py HYPE [duration]；不要创建或维护单独的 hype 技能。
• 周期别名必须端到端保留完整的请求时间范围。之前有个 bug：接受了 2h 并标注为 over 2h，却为了给图表“留出呼吸空间”而将 K 线裁剪至 80%，导致图表和变化值仅使用了约 96 分钟的数据。不要裁剪请求时长范围内的 K 线；如需视觉留白，只调整坐标轴边距，不要更改数据选择。