基于ClawdBot与GraphQL构建Polymarket预测市场查询机器人

1. 项目概述与核心价值

最近在折腾一个挺有意思的项目，叫“mvanhorn/clawdbot-skill-polymarket”。乍一看这个名字，又是“clawdbot”，又是“skill”，还带个“polymarket”，可能有点让人摸不着头脑。简单来说，这是一个为ClawdBot（一个开源的、可扩展的聊天机器人框架）开发的技能插件，专门用于与Polymarket这个预测市场平台进行交互。你可以把它想象成给你的聊天机器人装上一个“金融预测”或者“市场信息”的专属技能包，让它能帮你查询预测市场的行情、获取事件概率，甚至进行一些基础的分析。

这个项目的核心价值在于，它将去中心化预测市场这种相对前沿、专业的信息，以一种非常便捷、对话式的方式带给了普通用户。你不再需要去Polymarket的官网翻看复杂的界面，或者理解那些交易对和流动性池的概念，你只需要在Telegram、Discord或者任何集成了ClawdBot的地方，像和朋友聊天一样问一句：“嘿，拜登赢得2024年大选的预测概率现在是多少？”，机器人就能立刻给你一个基于市场共识的、实时更新的概率数字。这对于内容创作者、社群管理者、或者单纯对世界大事走向好奇的普通网友来说，是一个非常酷且实用的工具。

我自己在搭建和测试这个技能的过程中，发现它不仅仅是一个简单的API封装器。它涉及到如何在一个无状态的聊天机器人环境中，优雅地处理链上数据查询、格式化复杂信息、以及设计直观的用户指令。接下来，我会从项目设计思路、核心功能拆解、具体部署踩坑实录以及扩展可能性这几个方面，带你彻底搞懂这个项目，并手把手教你如何把它跑起来，甚至根据自己的需求进行定制。

2. 项目整体设计与架构拆解

2.1 技术栈与依赖关系解析

这个技能本质上是一个Node.js模块，它的运行严重依赖两个核心外部服务：ClawdBot框架和Polymarket的API（或更准确地说，是链上数据）。

首先看ClawdBot。ClawdBot是一个用TypeScript编写的模块化机器人框架，它的设计哲学是“技能即插件”。每个技能（Skill）都是一个独立的npm包，可以被主机器人动态加载。这意味着clawdbot-skill-polymarket这个项目必须遵循ClawdBot定义的技能接口规范，比如如何注册命令、如何处理消息、如何返回响应。理解这一点至关重要，因为它决定了我们代码的结构——我们必须导出一个符合Skill接口的对象，里面包含name、description、commands等关键属性。

其次是Polymarket数据源。Polymarket是一个建立在Polygon链上的预测市场平台。其市场数据本质上是链上数据，但通常我们不会直接让机器人去查询区块链（那样太慢且复杂）。项目会选择通过Polymarket提供的官方GraphQL API（托管在The Graph上）来获取信息。这是一种非常高效的方式，可以让我们用类似数据库查询的语句，精准地获取某个市场的标题、描述、当前是/否份额的价格（对应预测概率）、交易量等。因此，这个技能的核心实现，就是一个针对特定GraphQL端点的HTTP客户端，加上对返回数据的解析和美化。

此外，项目还会用到一些通用的工具库，比如axios或node-fetch用于发起网络请求，dotenv管理配置（如API端点），以及date-fns之类的库来格式化时间。整个项目的依赖关系清晰，职责单一，就是作为ClawdBot和Polymarket API之间的“翻译官”和“呈现器”。

2.2 核心功能模块设计

这个技能的功能可以归结为几个核心的查询指令。我们来看看它是如何设计的：

1. 市场搜索 (/polymarket search)：这是最常用的功能。用户输入一个关键词，比如“bitcoin”，技能就需要调用Polymarket的GraphQL API，查询所有标题或描述中包含该关键词的活跃市场。这里的设计难点在于结果的排序和呈现。是按交易量排序？还是按结束时间远近？项目通常会返回一个精简的列表，包含市场ID、标题和当前概率，让用户快速浏览。
2. 市场详情查询 (/polymarket market)：当用户通过搜索或直接输入市场ID（通常是类似“0x...”的合约地址或短ID）时，这个指令会获取该市场的详细信息。这包括完整的题目描述、两个结果选项（例如“是”和“否”）对应的当前价格、24小时交易量、总流动性、解析日期（市场结束时间）等。这里需要将“是”份额的价格（一个介于0-1之间的数字）转换为更直观的百分比概率，例如“价格0.65”意味着市场认为该事件发生的概率是65%。
3. 热门市场列表 (/polymarket trending或/polymarket list)：为了方便用户发现内容，技能通常会提供一个查看热门或最新市场的指令。这可能是查询交易量最大的市场，或者是即将截止的市场。这个功能直接调用API的排序查询即可实现。

注意：在设计指令时，需要充分考虑用户体验。例如，/polymarket后面跟的子命令（search,market）要简洁易记。对于market指令，除了接受市场ID，是否也应该支持部分标题的模糊匹配？这需要在功能的便捷性和实现的复杂性之间做权衡。原项目可能只支持ID查询以保证精确性。

3. 核心代码解析与实操要点

3.1 技能初始化与命令注册

让我们深入到代码层面。一个ClawdBot技能的核心是一个导出的对象。首先，我们需要在index.ts（或index.js）文件中定义这个技能。

// 示例结构，非完整代码 import { Skill } from '@clawdbot/core'; import { handleSearch, handleMarket, handleTrending } from './handlers'; const polymarketSkill: Skill = { name: 'polymarket', description: '查询Polymarket预测市场信息', commands: [ { name: 'search', description: '搜索Polymarket市场', usage: '<关键词>', handler: handleSearch // 指向处理函数 }, { name: 'market', description: '查看特定市场详情', usage: '<市场ID或关键词>', handler: handleMarket }, { name: 'trending', description: '获取热门市场', handler: handleTrending } ], // 可能还有初始化函数，用于加载配置 initialize: async (config) => { console.log('Polymarket技能加载完成！'); } }; export default polymarketSkill;

关键点解析：

• commands数组定义了用户可用的所有子命令。每个命令必须指定handler，这是一个异步函数，会接收到用户的消息内容、机器人实例等上下文信息。
• usage字段在用户输入错误时可以提供帮助提示，非常有用。
• initialize方法是可选的，你可以在这里进行一些异步初始化操作，比如测试API连接、预加载数据等。

3.2 GraphQL API查询封装

与Polymarket交互的核心是GraphQL查询。我们需要创建一个专用的服务模块（例如polymarket.service.ts）来封装这些操作。

import axios from 'axios'; // 通常Polyamrket的GraphQL端点 const POLYMARKET_API_URL = process.env.POLYMARKET_API_URL || 'https://api.thegraph.com/subgraphs/name/polymarket/matic-markets-2'; async function queryPolymarketGraphQL(query: string, variables: any = {}) { try { const response = await axios.post(POLYMARKET_API_URL, { query, variables }, { headers: { 'Content-Type': 'application/json' } }); if (response.data.errors) { throw new Error(`GraphQL Error: ${JSON.stringify(response.data.errors)}`); } return response.data.data; } catch (error) { console.error('查询Polymarket API失败:', error); throw new Error('无法获取市场数据，请稍后重试。'); } } // 搜索市场的GraphQL查询模板 const SEARCH_MARKETS_QUERY = ` query SearchMarkets($text: String!) { markets(where: { status: Active, title_contains: $text }, first: 10, orderBy: volume, orderDirection: desc) { id title outcomes { id price } volume } } `; // 获取市场详情的查询模板 const GET_MARKET_QUERY = ` query GetMarket($id: ID!) { market(id: $id) { id title description outcomes { id price title } volume liquidity endDate } } `; export async function searchMarkets(keyword: string) { const data = await queryPolymarketGraphQL(SEARCH_MARKETS_QUERY, { text: keyword }); return data.markets; } export async function getMarketById(marketId: string) { // 确保ID格式正确，有时前端显示的是短ID，API需要完整ID const id = marketId.startsWith('0x') ? marketId.toLowerCase() : marketId; const data = await queryPolymarketGraphQL(GET_MARKET_QUERY, { id }); return data.market; }

实操要点与避坑指南：

1. 端点地址：Polymarket的GraphQL端点可能会变更（例如从测试网切换到主网，或升级子图）。POLYMARKET_API_URL一定要做成可配置的，通过环境变量.env文件来管理。
2. 错误处理：GraphQL API即使返回200状态码，也可能在response.data.errors里包含错误信息。必须检查这个字段，而不是只看HTTP状态。
3. ID处理：市场ID大小写敏感。从Polymarket网页复制过来的ID，最好统一转换为小写再查询，避免“0xABC”和“0xabc”导致的查询失败。
4. 查询效率：在SEARCH_MARKETS_QUERY中，我们使用了first: 10和orderBy: volume。这能保证返回的是最相关的10个结果，且按交易量排序，用户体验更好。你可以根据需求调整first参数，但注意不要一次请求过多数据，以免影响响应速度。

3.3 消息处理与格式化呈现

收到用户指令后，handler函数被调用。它需要解析参数，调用相应的服务函数，然后将结果格式化成对用户友好的消息。这是技能体验好坏的关键。

// handlers.ts 中的 handleMarket 函数示例 import { getMarketById } from './polymarket.service'; import { CommandContext } from '@clawdbot/core'; export async function handleMarket(ctx: CommandContext) { const args = ctx.args; // ctx.args 是用户输入命令后的参数数组 if (args.length === 0) { return ctx.reply('请提供市场ID。例如：/polymarket market 0x123... 或 /polymarket market “比特币减半”'); } const identifier = args.join(' '); // 用户可能输入带空格的市场标题片段 try { // 这里先简单按ID查询。更复杂的实现可以先搜索，再取第一个结果。 const market = await getMarketById(identifier); if (!market) { return ctx.reply(`未找到ID为“${identifier}”的市场。`); } // 格式化消息 // 1. 计算概率：通常第一个结果项（outcomes[0]）代表“是”，其价格即概率 const yesPrice = parseFloat(market.outcomes[0].price); const probability = (yesPrice * 100).toFixed(1); // 2. 格式化日期 const endDate = new Date(parseInt(market.endDate) * 1000).toLocaleDateString(); // 3. 构建回复消息 const message = ` **${market.title}** ${market.description || '暂无详细描述。'} 📊 **当前预测概率**: ${probability}% 💰 **24小时交易量**: $${parseFloat(market.volume).toLocaleString()} 🏦 **总流动性**: $${parseFloat(market.liquidity).toLocaleString()} ⏰ **解析时间**: ${endDate} *数据来源: Polymarket | 市场ID: ${market.id}* `.trim(); await ctx.reply(message, { parse_mode: 'Markdown' }); // 使用Markdown格式使消息更美观 } catch (error) { console.error(`处理市场查询失败 [${identifier}]:`, error); await ctx.reply('查询市场详情时出错，可能是网络问题或市场ID无效。'); } }

格式化心得：

• Markdown/V2格式化：Telegram等平台支持简单的Markdown或HTML格式。使用**粗体**突出关键数据，用\n换行，能让消息清晰易读。
• 数字处理：价格和交易量从API返回的是字符串类型，需要parseFloat转换后再进行计算和格式化（如添加千位分隔符toLocaleString()）。
• 概率解释：一定要明确告诉用户“价格”和“概率”的对应关系。Polymarket中，“是”份额的价格直接等于市场认为事件发生的概率。
• 错误反馈：给用户的错误信息要友好且具有指导性。不要直接抛出“GraphQL error: ...”，而是说“查询失败，请检查市场ID或稍后重试”。

4. 完整部署与集成实战

4.1 环境准备与项目初始化

假设你已经有一个运行中的ClawdBot项目（如果还没有，需要先npm init并安装@clawdbot/core以及适配器如@clawdbot/adapter-telegram）。我们将把clawdbot-skill-polymarket作为本地技能进行开发和集成。

1. 获取技能代码：由于这是一个具体的GitHub仓库（mvanhorn/clawdbot-skill-polymarket），我们首先克隆它。

   git clone https://github.com/mvanhorn/clawdbot-skill-polymarket.git cd clawdbot-skill-polymarket npm install

2. 环境变量配置：在项目根目录创建.env文件。虽然核心的Polyamrket API端点可能已有默认值，但最佳实践是显式配置。

   # .env 文件 POLYMARKET_API_URL=https://api.thegraph.com/subgraphs/name/polymarket/matic-markets-2 # 如果你的ClawdBot需要其他配置，如Telegram Bot Token，也在这里设置 # TELEGRAM_BOT_TOKEN=your_token_here

3. 本地链接（用于开发）：在你的主ClawdBot项目目录下，使用npm link将技能链接过去。

   # 在技能目录下 npm link # 在你的主ClawdBot项目目录下 npm link clawdbot-skill-polymarket

   然后，在主项目的package.json中，像依赖其他包一样添加它（尽管实际上是通过软链接）：

   "dependencies": { "@clawdbot/core": "^1.0.0", "clawdbot-skill-polymarket": "file:../clawdbot-skill-polymarket" // 或使用链接 }

4.2 在主机器人中加载技能

在你的主ClawdBot应用文件（例如src/bot.ts）中，你需要导入并注册这个技能。

import { createBot } from '@clawdbot/core'; import telegramAdapter from '@clawdbot/adapter-telegram'; import polymarketSkill from 'clawdbot-skill-polymarket'; // 导入技能 async function main() { const bot = createBot({ adapter: telegramAdapter({ token: process.env.TELEGRAM_BOT_TOKEN!, }), skills: [polymarketSkill], // 将技能添加到技能数组 }); await bot.start(); console.log('Polymarket技能机器人已启动！'); } main().catch(console.error);

关键检查点：

• 确保技能包的package.json中的main字段指向正确的入口文件（如dist/index.js或src/index.ts）。
• 如果技能是用TypeScript编写且主项目也是TS，需要确保编译顺序。通常主项目会编译所有依赖，但链接的本地包可能需要先单独构建（npm run build）生成dist目录。

4.3 运行测试与调试

启动你的主机器人项目：

npm run dev # 或 node dist/bot.js

在Telegram中与你的机器人对话，尝试输入：

• /polymarket search bitcoin
• /polymarket market 0x...(替换为真实市场ID)
• /polymarket trending

调试过程中常见的坑：

1. “技能未找到”或“命令无效”：

   • 原因：技能没有正确注册。检查主bot的skills数组是否包含了技能实例。
   • 排查：在bot启动后，查看日志是否输出了技能的initialize函数内的日志（如果有的话）。
   • 解决：确保导入路径正确，技能模块导出格式符合ClawdBot要求。

2. GraphQL查询返回空或错误：

   • 原因：API端点错误、查询语法过时（子图可能已更新）、或查询变量格式不对。
   • 排查：在polymarket.service.ts的queryPolymarketGraphQL函数中，将出错的请求和响应体打印出来。
   • 解决：去Polymarket官方文档或The Graph playground验证你的GraphQL查询语句。检查市场状态（where: { status: Active }），可能有些市场已失效。

3. 时间戳解析错误：

   • 原因：API返回的endDate可能是字符串或整数，单位可能是秒或毫秒。
   • 排查：console.log一下原始的market.endDate值。
   • 解决：根据实际情况进行转换。示例中按秒处理（* 1000），如果不对，尝试直接new Date(market.endDate)。

5. 功能扩展与个性化定制思路

原版技能提供了核心的查询功能，但你可以基于此进行大量扩展，让它更强大、更贴合你的使用场景。

5.1 添加价格变化提醒功能

这是一个非常实用的扩展。用户可以订阅某个市场，当概率达到某个阈值或变化超过一定百分比时，机器人主动推送通知。

实现思路：

1. 数据存储：你需要一个简单的数据库（如SQLite、Redis）来存储用户的订阅关系（chatId, marketId, condition）。
2. 定时任务：在技能中启动一个定时器（使用setInterval或node-schedule），定期（如每5分钟）遍历所有订阅，查询对应市场的最新价格。
3. 条件判断：将最新价格与用户设置的条件（例如“概率 > 70%”或“价格比上次检查波动 > 5%”）进行比较。
4. 主动推送：如果条件满足，使用ClawdBot上下文或适配器提供的方法，向指定的chatId发送消息。注意：这需要你的技能能访问到bot实例的发送消息方法，可能在技能初始化时需要注入。

5.2 支持更多查询参数与过滤

原版的搜索可能比较简单。你可以增强它：

• 按类别过滤：Polymarket市场有分类（政治、加密货币、体育等）。修改GraphQL查询，添加category过滤。
• 按时间过滤：让用户搜索“本周内结束”或“一个月后结束”的市场。
• 多关键词搜索：支持AND/OR逻辑，或者更智能的全文搜索。

5.3 结果呈现优化

• 图表预览：对于高级群组或频道，可以尝试集成简单的图表库，生成市场概率随时间变化的趋势图图片并发送。这需要额外的图片生成服务（如chart.js+node-canvas）。
• 摘要模式：对于/polymarket trending，可以提供一个“摘要”模式，用一句话概括最热门的3-5个市场，适合快速播报。

6. 常见问题与故障排查实录

在实际部署和运行中，你可能会遇到以下问题。这里记录了我踩过的坑和解决方案。

问题1：机器人响应“查询超时”或完全无反应。

• 可能原因A：网络问题。机器人服务器无法访问The Graph的API端点（api.thegraph.com）。
  • 排查：在服务器上运行curl -X POST https://api.thegraph.com/subgraphs/name/polymarket/matic-markets-2 -H "Content-Type: application/json" -d '{"query":"{ markets(first: 1) { id } }"}'，看是否能收到响应。
  • 解决：检查服务器防火墙、安全组规则，确保允许对外HTTPS请求。考虑在请求中增加超时（timeout）设置和重试逻辑。
• 可能原因B：技能处理函数抛出未捕获的异常，导致整个机器人进程崩溃或该消息处理中断。
  • 排查：查看机器人运行日志，是否有明显的错误堆栈信息。
  • 解决：确保所有异步操作都有try...catch包裹，并在catch块中给用户一个友好的回复，同时将详细错误记录到日志。

问题2：搜索某些关键词返回结果很少或不对。

• 可能原因：GraphQL查询条件过于严格。原查询可能使用了title_contains，但用户可能用描述中的词搜索。
  • 排查：在The Graph的Playground上手动执行查询，尝试不同的过滤条件。
  • 解决：修改查询，使用更灵活的过滤，例如where: { _text: $text }（如果子图支持全文搜索），或者同时查询title和description字段。也可以考虑将first: 10调大，但要注意性能。

问题3：市场概率显示为0%或100%，但网站上显示不同。

• 可能原因：outcomes数组顺序误解。你代码中取outcomes[0]作为“是”份额，但API返回的数组顺序可能不固定。
  • 排查：打印出某个市场的完整outcomes数组，查看每个outcome的title字段。通常是['YES', 'NO']或['For', 'Against']。
  • 解决：不要依赖数组下标，而是遍历outcomes数组，找到title为“YES”或“是”的那一项，取其价格。

问题4：在群组中使用时，机器人不响应命令。

• 可能原因：ClawdBot适配器配置或权限问题。在Telegram群组中，默认情况下机器人需要被设置为“管理员”才能接收所有消息，或者需要以/command@bot_username的格式提及。
  • 排查：检查你的机器人是否在群组中拥有“消息权限”。尝试在私聊中是否工作正常。
  • 解决：确保你的命令处理逻辑正确。在ClawdBot的Telegram适配器配置中，可能需要明确设置polling参数或处理group消息。参考ClawdBot官方文档对群组支持的说明。

这个项目是一个绝佳的范例，展示了如何将专业的链上数据服务封装成普通人触手可及的聊天机器人功能。从技术上看，它涉及了Node.js模块化开发、GraphQL API调用、异步错误处理以及聊天机器人交互设计等多个环节。部署过程中，最关键的是理解ClawdBot的技能契约，并稳健地处理外部API的波动性和数据格式的不确定性。如果你对预测市场感兴趣，或者正想为你的社群机器人增加一个实时信息查询的亮点功能，亲手部署和定制这个clawdbot-skill-polymarket会是一个非常值得的实践。