surf

别再让你的 Agent 靠猜

在调用造成影响前先检查。 Gecko 是开源的，可在你的机器上运行：
一条命令即可将任何 API——混乱、设有付费墙或链上 API——映射为调用图，让你的 Agent
依据图检查，而不是靠猜；任何会产生支出的操作都会先模拟，并生成一份
收据。
无钱包、无支付通道、不持有密钥——64 笔主网交易中，49 笔在签名前预测了成本，其中 47 笔精确到最小单位（从链上重新读取，2026-09-19）。

快速开始 · 文档 · 架构 · 常见问题 · 安全

专为绝不能出错的 Agent 调用而打造。 满足以下任一方面即可：混乱的接口（设有付费墙、不断变化、缺少文档或在链上），或高风险操作（你的 Agent 使用凭据或资金无人值守地运行）。

Gecko 是什么

Gecko 是一个专为调用 API 的 AI Agent 构建的开源知识图谱。将 OpenAPI 规范、文档站点，或 Solana 程序的 IDL 和源代码交给它，它就会读取这些接口并构建图谱，供你的 Agent 遍历——每条事实都标记其来源，无法确认的内容则会标记出来，而不是靠猜测。

规范会告诉你的 Agent 一次调用看起来是什么样，却无法告诉它这次调用是否会成功。这个差距存在于每份规范中，即使规范完美无缺也一样；这正是 Agent 代价高昂地失败的地方：失败的不是报错的调用，而是被接受却执行错误的调用。Gecko 通过返回一个明确的调用来弥补这一差距；对于任何会产生支出的操作，它还会先基于真实状态模拟该调用，并返回一份收据。

它既不是 Agent，也不是编排器。它不持有密钥、不签名、不广播，也不存储响应载荷——它存储接口和正确性元数据，绝不存储你的数据。

快速开始

无需安装：

npx @geckovision/gecko doctor              # 1. check your environment
npx @geckovision/gecko add <spec-or-docs>  # 2. comprehend it — $0, no live call
npx @geckovision/gecko report <spec>       # 3. get the scorecard — grade + findings
npx @geckovision/gecko serve <spec>        # 4. your agent uses it over MCP

或者只需安装一次：

npm install -g @geckovision/gecko          # prebuilt binary — no Python needed
uv tool install "gecko-surf[serve]"        # or pip, if you want the Python package

gecko add <spec-or-docs>

接入你的 Agent：

# Claude Code
claude mcp add my-api -- npx -y @geckovision/gecko serve <spec> --stdio

# Cursor / VS Code / any MCP client — mcp.json
{ "mcpServers": { "my-api": { "command": "npx", "args": ["-y", "@geckovision/gecko", "serve", "<spec>", "--stdio"] } } }

上线是一个独立且需要审慎执行的步骤：

gecko auth set <provider>                  # key goes to your OS keychain — never mcp.json

然后，你的 Agent 询问的是问题，而不是端点：

Which fixtures kick off in the next hour, and what are the current odds?
What is the peg state of USDC right now?
Plan a swap of SOL for USDC on Meteora, bin_step 4.

为什么

OpenAPI 说明有哪些接口。IDL 描述程序是什么样的。两者都不足以支持实际操作：

• 文档会过时。2026 年，静默的布局变更导致正常工作的集成两次失效。
• IDL 会遗漏事实。必需的 Pump.fun 账户根本不会出现在 IDL 中。
• Agent 会猜测。错误的猜测会提交一笔扣款、导致交易回滚、白白烧掉手续费。

Gecko 用图谱取代猜测：

• 每条边都带有来源信息——从接口中提取（extracted）、从源代码中还原（recovered），或如实标记（flagged）为未知。绝不捏造。
• 每项操作都可以先验证——在 $0 主网分叉上模拟，并生成一份收据：在任何支出发生前，确认通过或归类回滚原因。
• 每次失败都有助于改进——结果会归入分类语料库；当提供方发布的变更破坏了原本正常工作的调用时，变更趋势序列会发出标记。
• Agent 不会感知认证过程——调用时从你的密钥链注入密钥。模型永远看不到凭据。

深入了解

大多数 Agent 工具层都只是薄封装。Gecko 是一种记忆底层，其三项设计选择刻意不同于教科书中的做法：

选择	重要性
确定性语义记忆——词法检索，不使用向量数据库	图谱不会“近似”记忆；BM25 和向量检索都设有证据门槛
自行生成的情景记忆——类别化结果 + 漂移序列	Gecko 会重新模拟以创建自己的情景记忆；不依赖你的数据平面，也不存储载荷
类型化程序性记忆——将计划表示为可执行 JSON	落地计划和派生顺序可供构建器执行；文本会丢失关联信息，而我们的方案不会

而且，我们用实测数据来衡量深度，而非仅作宣称：

• 覆盖层产物。 对于每个自动理解的程序，Gecko 都会输出无法从任何公共表面推导出的事实的精确列表 (overlays/)——按程序量化理解的价值。
• 七层安全机制，默认拒绝： 规范清理器 · 按工具隔离 · 图像 Skill Guard · SSRF 网络防护 · 带外身份验证锚定 · 判定签名门控 · 由 AST 强制执行的绝不签名边界。
• 数据： 5,043 项测试 · 64 笔主网交易，47/49 项预测完全准确 · 5 笔由费用中继支付，买方没有 SOL，最后四笔采用 USDG→USDC→购买路线 · 接入 8 个 Solana 程序，其中 4 个经过差分验证 · 2 组实时收据对 · 实测上下文减少 77%/89% · 列出 4,534 个程序的目录 · 在 14 份真实规范中，暴露的身份验证标头为 0 个。

查看图表：docs.geckovision.tech 上的架构图 （已渲染全部三个视图） · 此仓库中的架构图

证据胜于承诺

在主网分叉上实时运行，费用为 0 美元：

案例	朴素路径	Gecko
Pump.fun 买入	❌ 交易回滚——AccountNotInitialized (3012)	✅ 成功执行——86,669 CU
Pump.fun 卖出	❌ 转出代币后交易回滚——InvalidBondingCurveV2 (6074)	✅ 成功执行——50,783 CU
Meteora DLMM 兑换	❌ 交易回滚——仅派生地址，缺少 ATA/封装/bin-array 前置步骤	✅ 封装 → 兑换 → 解封装——81,964 CU
Meteora 池派生	❌ 过时的 3 种子方案 → 悄然得到错误的池	✅ 正确的 4 种子派生，已通过差分验证
仅有文档的 API（无规范）	Agent 臆造端点	✅ 找回草拟规范，并验证为 VERIFIED/REFUTED

这些成功案例背后的事实并未出现在任何表面信息中：SDK 于 2024 年添加的第 4 个 PDA 种子、IDL 只在说明文字中提及的账户，以及通过一项证伪模拟确定的费用字段。这就是你的 Agent 所遍历的图谱。

使用场景

TxLINE（付费体育赔率）——使用 Gecko 前后对比

· MP4

跨 API 关联——三个 API，一个问题

Pegana × Birdeye × Jupiter 按已声明的实体进行关联；Agent 首次尝试即可跨接口规划。试试看：gecko graph svg <spec> 可渲染任意接口的调用图。

Solana 程序——在主网上买杯咖啡

上面的一切都是零成本分叉版。这次不是：真实主网、真实 USDC、一杯真正的浓缩咖啡。

let_me_buy 是 Solana 上的店面程序。商家创建店铺，并列出以 USDC 定价的商品；买家扫描二维码并付款。每家店铺对应一个账户——PDA(["receipts", store_name])——用于存放菜单、收据、累计数量和商家的权限。

MP4 版本——未经剪辑的一镜到底。签署任何内容之前，收据就显示 24,956 CU；链上实际收取 24,956 CU (4X8dCyZU…，slot 439046190)。密钥从未离开其安全区。

uvx --from "gecko-surf[serve,solana]" gecko-orquestra --program let_me_buy --stdio

IDL 未包含的两个事实，而且两者都会导致调用失败：

• mark_as_delivered 将其 receipts 种子声明为 store_name，但该指令自己的参数是 _store_name 和 receipt_id。该种子引用了不存在的参数，因此按参数名称解析种子的派生器无法获取唯一一个用于选择店铺的种子值。Gecko 按种子值绑定。
• 在 make_purchase 中，店铺的 authority 是可写的，但不是签名者。买家从 ATA(signer, mint) 付款；店铺则记入 ATA(authority, mint)——mint 相同，所有者不同。如果从同一个所有者派生这两个地址，构造出的购买交易就会把钱付回给买家。Gecko 会在请求构建器之前拒绝该计划。

预测会跟踪状态，而非记忆固定常量。 在这家店面进行了三笔购买，收取的费用依次为 23,789 → 24,183 → 24,956 CU；后两笔是同一件商品。每笔销售都会向店铺账户追加一张收据，因此程序要做更多工作；每次查询时，收据都准确预测了新的数值。

Gecko 恢复接口中缺失的信息，Orquestra 构建指令，收据则会在签名之前说明交易能否成功。

架构

控制平面，绝非数据平面。 Gecko 存储接口和正确性元数据——从不存储响应载荷、用户数据或机密。

1. 摄取——OpenAPI / 文档 / IDL / 程序源码 → 清理并通过隔离区检查。
2. 理解——规范化操作、恢复 PDA 种子、生成配置和实测覆盖层。
3. 掌握——溯源图谱（接口、程序、跨 API 关联）。
4. 投影——通过 MCP 提供符合问题需求的工具；剥离身份验证；在两个真实规范上实测，减少 −77%/−89% 的上下文占用。
5. 验证——计划 → 外部构建器 → 模拟 → 收据 → 失败即关闭的签名关卡。Gecko 从不签名，也从不广播。
6. 学习——分类结果 → 漂移序列 → 回馈图谱。

交互式图表 · llms.txt · 收据语义

你将获得什么

功能	入口
通过 MCP 向 Agent 提供任意 API	gecko serve <spec>
评分卡：等级 + 可修复的问题 + Playground	gecko report <spec>
从人类编写的文档中还原草稿规范	gecko from-docs <url>
用于 CI 的首次调用正确性测试	gecko test <spec>
渲染后的表面图	gecko graph svg <spec>
Program Surface：还原出的种子 + 派生计划	gecko orquestra --program <name>
find_start：意图 → 正确的起始指令	gecko orquestra find-start "..."
模拟 → 为已构建的交易生成回执	gecko/simulate.py（引擎）
嵌入 SDK	from gecko import AgentApiClient
根据实际情况验证文档声明	gecko verify-docs <spec>
扫描技能图片中的隐藏载荷	gecko scan-image <path>

技能

引擎是产品；技能则教 Agent 如何驱动它。六项技能以一个插件的形式 发布——供 Agent 阅读的 Markdown 文件，不包含任何可执行逻辑。

/plugin marketplace add GeckoVision/gecko-surf
/plugin install gecko-surf@geckovision

技能	适用对象	功能
use-any-api	Agent 构建者	首次调用陌生 API 即正确——让 Gecko 读取 OpenAPI 或文档，生成符合意图的 MCP 工具，并隐藏身份验证信息
read-js-docs	Agent 构建者	从 JS 渲染的文档中提取 API 表面，适用于 curl 返回空壳的情况
anti-poisoning	Agent 构建者	防御被投毒的 规范——这类规范会诱导你的 Agent 传入特定参数，或窃取你的密钥
skill-guard	Agent 构建者	防御被投毒的 制品——图片或约定页面可能包含 Agent 会遵循、但审核者看不到的指令
api-agent-ready	API 提供方	让你自己的 API 的整个表面都可供 Agent 使用，并与 你已提供的任何 MCP 并存
x402-payai-setup	API 提供方	为你的 API 接入按次付费。你保留 100% 收入——Gecko 不是支付通道，也不会抽成

两项防御技能针对的是同一种威胁的两种形式：被投毒的 规范 针对 Agent 调用 的内容，被投毒的 制品 针对 Agent 执行 的操作。完整说明和状态见 skills/README.md。

模式

• 录制（默认）：$0，基于架构合成响应，完全离线。先验证所有内容，再进行任何实时调用。
• 实时：使用相同的代码路径；在边缘节点从你的密钥链注入凭据。 gecko auth set <provider> ——需明确执行，不会隐式进行。

托管服务

此仓库中的引擎也运行于 mcp.geckovision.tech ——通过 Streamable-HTTP MCP 提供已理解的表面，并在服务端注入密钥。 开发者无需付费；提供方按 API 支付固定费用。 Gecko 不抽成、不持有资金，也不签署任何内容。 → docs.geckovision.tech

仓库结构

路径	内容
gecko/	引擎——摄取、目录、工具、图、模拟、语料库
gecko/providers/	Program Surface（Meteora、Pump.fun、Jupiter、ORE、MetaDAO）+ 配置
scripts/、gecko/cli.py	轻量传输层——解析、调用程序包、格式化
skills/	面向 Agent 的插件——六项技能、Agent、命令
docs/	架构、回执语义、规范、基准测试
examples/	可分叉的入门示例

开发

uv run ruff format && uv run ruff check --fix
uv run mypy gecko
uv run pytest                # 5,043 passing
uv run python -m gecko.demo  # $0 recorded E2E

常见问题

这是一个工具生成封装器吗？ 不是。工具生成只是基本要求。产品的核心是经过验证的图谱（每条边都有来源信息）、回执（资金转移前先模拟），以及漂移序列（了解服务提供方何时让你陷入故障）。

它适合谁？ 有两个维度，满足其中一项即可：表面混乱（有付费墙、不断变化、缺少文档、在链上），或操作风险高（你的 Agent 使用凭证或资金在无人值守的情况下运行）。如果 API 清晰，而且有人审核差异？你可能不需要我们——这完全没问题。

Gecko 会签名或持有资金吗？ 绝不会。Gecko 从不签名、从不广播，也从不构建生产交易——仅用于模拟的未签名组装是文档中注明的例外，并通过 AST 在签名/发送边界强制执行。构建由构建者负责（例如 Orquestra），签名由签名者负责（钱包 / TEE / 你）。

Gecko 会存储什么？ 表面信息和正确性元数据。绝不存储载荷、余额、结果中的公钥或机密信息。语料库按类别划分，词汇表封闭，并经过审计。

向量数据库？ 不是——检索采用词法匹配且具有确定性（令牌重叠；BM25 和语义层都位于证据门控之后，只有在测得召回率不足时才会启用——其中也包括一次经过测量的嵌入负面结果）。

它免费吗？ 引擎采用 Apache-2.0 许可，功能完整且可自托管。托管层是 API 提供商购买的部分。开发者永远无需付费。

贡献

欢迎提交 PR。推送前请运行上述工具链。安全问题请参阅 SECURITY.md。

许可

Apache-2.0 —— 详见 LICENSE。