Teardrop

████████╗███████╗ █████╗ ██████╗ ██████╗ ██████╗  ██████╗ ██████╗
╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔══██╗
   ██║   █████╗  ███████║██████╔╝██║  ██║██████╔╝██║   ██║██████╔╝
   ██║   ██╔══╝  ██╔══██║██╔══██╗██║  ██║██╔══██╗██║   ██║██╔═══╝
   ██║   ███████╗██║  ██║██║  ██║██████╔╝██║  ██║╚██████╔╝██║
   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝

Teardrop 是一个流式 API，供应用和软件 Agent 运行可调用工具的 AI 工作流。客户端提交消息或任务；Teardrop 协调配置好的 LLM（Anthropic、OpenAI、Google 或 OpenRouter）和可用工具，然后通过 Server-Sent Events（SSE）流式传输结构化结果和 UI 事件。它支持用于流式交互的 AG-UI、用于 Agent 发现和委派的 A2A、用于工具访问的 MCP，以及可选的基于 Base 的 x402 按请求 USDC 结算。

---

核心功能

Agent 间（A2A）委派

Agent 可以通过零成本的 discover_agents 工具发现选择加入的专用 Agent，包括当前已发布的工具名称，并通过 delegate_to_agent 安全地委派任务（两者均在 /agent/run 期间调用）。功能包括允许列表控制、JWT 转发、每次运行配额、目标成本上限、可选的公开原子 USDC 任务价格，以及可选的信用额度计费，并强制执行组织级和调用方主体级暂停／24 小时支出限额。价格高于有效允许列表上限时，会在出资前返回 error_type=advertised_price_exceeds_cap；低于上限的价格则会根据实时预算重新检查。对于新建立且使用信用额度出资的委派，如果确定未送达，系统会创建与退款关联的冲正记录，并在滚动支出上限计算中恢复退款金额；对于结果不明的 possibly_delivered 调用，则会保留款项，等待明确处理。迁移 103 前创建的退款记录可能没有关联冲正记录，因此虽可恢复余额，但不会恢复滚动支出上限的可用额度。

完整的协议规范、环境变量、允许列表和计费事件负载，请参阅 docs/a2a-delegation.md。

平台工具市场

Teardrop 通过市场目录提供 31 个面向调用方的内置计量工具。调用方可以：

• 通过 GET /tools/mcp 上的 MCP 网关调用（直接调用工具，按次计费）。
• 在 Agent 运行期间作为工具调用（当 Agent 决定使用它们时，通过 POST /agent/run 调用；费用计入本次运行的使用成本）。

完整工具列表、详细说明及每次调用的价格，请参阅 docs/tools-catalog.md。

使用 MARKETPLACE_ENABLED=true 启用。启用后，工具会显示在 GET /marketplace/catalog 中，且 qualified_name = "platform/{tool_name}"、tool_type = "platform"。目录发现支持按 category 筛选、使用 sort=popularity 排序、查看单个工具详情页、通过 GET /marketplace/authors 查看作者索引、查看作者资料、通过 GET /marketplace/llms.txt 进行 LLM 友好型发现，以及通过 GET /marketplace/quote?tool={qualified_name} 查看当前有效价格。公开目录是作者所有当前有效的已发布工具；经过身份验证的 Agent 可以通过 GET /agent/tools 查看其当前组织的工具清单。作者索引会列出当前有效的已发布作者及调用总数，然后引导客户端前往现有作者资料页查看工具详情；它并非远程 A2A 委派 URL 列表。汇总质量指标可通过 GET /.well-known/reputation.json 获取。市场作者可以注册外部 MCP 服务，并通过 POST /marketplace/import/preview 和 POST /marketplace/import/publish 将发现的工具发布为条目（组织管理员或绑定组织的机器凭证）。 当工具有调用历史时，MCP tools/list 会为 LLM 客户端提供观察到的质量描述，并为程序化客户端提供结构化的 _meta["teardrop/reputation"]。/tools/mcp 接口会列出平台工具（使用裸名称，可通过 x402 或积分付费）和已发布的组织工具（{org_slug}/{tool_name}，仅支持 Bearer 和积分付费，且只向 Bearer 调用方列出），每项都包含 _meta["teardrop/price"]；旧版 /mcp/v1 接口已弃用，并将于 2026-10-29 停止服务。目录中的 cost_usdc 在所有接口上始终等于实际扣费价格；未设置作者价格的社区工具使用平台默认价格，0 表示免费。元数据约定详见 docs/tools-catalog.md。

组织可选择通过 PUT /marketplace/agent-registration，使用组织管理员身份或绑定组织的客户端凭据令牌，在公共目录中发布一个远程 A2A 端点。Teardrop 仅接受 HTTPS 基础 URL，会对其进行 SSRF 检查、发现远程 Agent Card，并要求提供 A2A 客户端使用的 /message:send 端点。注册表与出站委托允许列表相互独立：发布会让端点可被发现，但不会授权对其发起调用。GET /marketplace/agents 会列出已选择加入的端点，但只有在至少有五个不同组织调用后才显示声誉指标。自调用、本地故障和结果不明确的 possibly_delivered 情况均不纳入统计。新增的 registered_at 字段仅用于表示新加入者的近期注册情况，不代表其质量或所有权。此机器凭据路径涵盖端点注册和 MCP 工具发布；提取收益则需要组织管理员，或机器创建组织的所有者 SIWE 钱包。

Agent 自有的 webhook 工具可通过 POST /tools 注册。机器创建的组织需使用其所有者 SIWE 钱包，通过 POST /marketplace/author-config 配置市场收益结算；除非组织管理员配置了资金库钱包，否则该钱包会固定绑定到此身份。记录作者收益不再要求配置结算方式；自调用仍不计入。发布新的市场工具和申请提现仍需配置结算钱包。收益记录仍为尽力而为，不保证与结算持久关联。

Agent 运行期间始终可以使用平台工具，且无法通过 POST /marketplace/subscriptions 订阅；使用这些工具会产生相应的市场价格（令牌费用之外）。可通过 POST /admin/pricing/tools 设置每个组织的定价覆盖；对于 Agent 运行，同一工具同时存在 tool_pricing_overrides 和市场目录价格时，前者优先。

市场订阅是 Agent 运行固定项，并非定期付费计划或直接 MCP 访问授权。固定某项社区工具会将其加入组织的 /agent/run 工具集；直接调用 /tools/mcp 无需固定工具，但仍须满足相应的身份验证和计费要求。在 /agent/tools 中，旧版 access_mode="subscribed" 表示已固定，而 "included" 表示无需固定市场工具，并不代表免费。固定项和库存均不保证工具会执行；请参阅Agent 运行固定项与直接工具调用。

Marketplace 结算与 USDC 归集

组织可以通过 Marketplace 将其 Agent 变现。提现时，系统会先领取待结算的作者收益，然后通过 Coinbase Developer Platform（CDP）将 USDC 转入已配置的结算钱包。已确认的转账会标记为 settled；已确认的链上回滚则会释放收益。提交错误和无法获取确认结果的提现会保持 in_flight 状态，并锁定收益以防自动返还。归集循环会结算或释放已记录交易哈希的 in_flight 提现，前提是该交易已最终确认，且与申领的 USDC 转账相符；对于其他存在歧义的提现，操作人员必须先确认链上结果，再进行重置。

自动归集通过 MARKETPLACE_AUTO_SWEEP_ENABLED 和相关的 MARKETPLACE_* 设置进行配置（参见 docs/configuration.md）。管理 API：POST /admin/marketplace/sweep（手动归集）和 GET /admin/marketplace/settlement-balance。

通过验证邮箱发放新手额度

Teardrop 可以为新近完成邮箱验证的组织发放少量预付额度，让其无需立即设置钱包或银行卡即可首次运行 Agent。此功能默认禁用（ONBOARDING_CREDIT_ENABLED=false），仅用于促进转化，不可作为可提现的 Marketplace 作者收益来源。

用户使用一次性邮箱验证令牌（GET /auth/verify-email）后即可获得赠送额度。令牌使用、将用户标记为已验证以及将资格任务加入队列会以原子方式提交；后台工作进程会以幂等方式重试发放促销额度，直到成功。促销额度可用于平台工具、组织 Webhook 工具、MCP 工具以及 Agent 运行的基础费用，但不能用于调用 Marketplace 作者工具。实际充值（Stripe、链上 USDC、管理员充值或退款）会将组织转为普通额度状态，并解除 Marketplace 限制。通过 x402 支付的 SIWE 调用不受影响。

验证后，查看 GET /billing/balance 以确认已发放的额度。有关 ONBOARDING_CREDIT_* 设置，请参见 docs/configuration.md。

无人值守（定时）Agent 运行

组织可以安排周期性、无人值守的 Agent 运行，并使用集成的仅限额度计费、已存储的执行历史记录和实时状态回调。通过 /agent/schedules API 管理（POST/GET/PATCH/DELETE，以及用于游标分页结果的 GET /agent/schedules/{id}/runs）。

到期运行通过行锁定查询（FOR UPDATE SKIP LOCKED）领取，并发执行且彼此隔离故障，因此多个工作实例可以水平扩展。结果归档在 scheduled_run_results 下，并可发送到经过 SSRF 检查、仅支持 HTTPS 的回调 URL。使用 callback_format=text 发送纯文本移动通知；默认格式为 JSON。通过 SCHEDULED_RUNS_* 设置进行配置（参见 docs/configuration.md）。

定时分析提示词可以调用内部 record_predictions 工具并传入精确的结构化负载，且只返回简洁的叙述性报告。Teardrop 会通过通用标注数据平面对这些预测进行异步标注，并与未来观测结果比对；因此，回调可以将报告发送到下游通知系统，同时保留结构化值供 ML 评估。参见 docs/architecture.md 和 docs/configuration.md 中的 LABELING_* 设置。

启用 VOR_ENABLED=true 后，外部 Agent 还可以通过 POST /labeling/predictions 提交由钱包签名的预测。Teardrop 会在服务器端为每条预测添加时间戳，将提交批量汇总为锚定在 Base 上的 Merkle 树，并通过 GET /labeling/predictions/{id}/proof 返回包含证明。参见 docs/configuration.md 中的 VOR_* 设置。

预先注册的公共任务（目前为 oracle_deviation@1，用于评估 Chainlink ETH/USD 与 Base 上 Uniswap v3 TWAP 的偏离程度）基于固定的、已最终确认的链上读取结果进行评分。GET /scorecards/... 无需身份验证即可发布经过覆盖率调整的 Brier 评分卡；预测负载保持私密。

事件触发（响应式）运行

除了固定间隔外，组织还可以注册事件触发器，让 Agent 响应传入的 Webhook 运行（例如链上事件、CRM 更新或 CI 信号）。事件触发器会存储提示词模板；分发时，传入的 JSON 负载会插入模板。事件触发器复用定时运行使用的同一执行核心、额度计费、结果历史记录和回调分发机制。

通过 /agent/event-triggers API 管理（CRUD、密钥轮换和运行轮询）。传入事件通过 POST /agent/events/{trigger_token} 分发，并使用每个触发器专属的密钥通过 X-Teardrop-Trigger-Secret 标头进行身份验证；此外，还支持可选的幂等键，以及仅允许标量、长度受限的提示词插值，以抵御注入攻击。Postgres 执行租约会强制实施全局和每组织并发限制（饱和时返回 429）。

将 next_trigger_id 设置为同一组织中的另一个事件触发器，即可在内部串联已完成的运行，无需回调身份验证。串联为线性结构；EVENT_CHAIN_MAX_HOPS 限制子级跳数（默认值：2，包含根运行在内最多允许 3 次运行；0 表示禁用子级分发）。结果会公开 chain_id 和从 0 开始的 hop_index。子级分发最多执行一次：目标不可用或已饱和时会记录审计信息，且不会重试。

提示词模板会插入不可信的负载数据，因此应将渲染后的提示词视为传递给 Agent 的不可信输入，并据此限制事件触发器可用的工具和额度上限。通过 EVENT_TRIGGERS_* 和 EVENT_CHAIN_MAX_HOPS 设置进行配置（参见 docs/configuration.md）。

X（Twitter）广播帖子

组织可以配置定时运行，直接向 X（Twitter）发布市场分析和机会判断。设置 callback_format=x 后，成功完成运行时，系统会通过使用 OAuth 1.0a 身份验证的 v2 API，将最终输出文本发布到 X，并将已发布的推文 ID 记录在不可变的 x_broadcasts 审计账本中。

广播运行要求设置 X_BROADCAST_ENABLED=true，并通过 X_BROADCAST_ORG_ID 指定操作员组织；任何其他组织的计划都会被拒绝，并返回 403。为防止按使用量付费的 API 成本过高及网络钓鱼，发布前会拒绝包含 URL 的输出文本。请通过 X_* 设置进行配置（参见 docs/configuration.md）。

---

要求

• Python 3.12+
• 所选 LLM 提供商的 API 密钥：Anthropic、OpenAI 或 Google AI（使用 BYOK 或可自托管服务时可选）
• Postgres 数据库（通过 Docker 在本地运行，或在生产环境中使用 Neon）
• Redis（可选，用于缓存 — 不可用时会回退到带 TTL 的内存缓存）

---

设置（PowerShell）

1. 克隆并进入项目

git clone https://github.com/teardrop-ai/teardrop.git
cd teardrop

2. 创建并激活虚拟环境

python -m venv venv
.\venv\Scripts\Activate.ps1

如果遇到脚本执行错误，请先运行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

3. 安装依赖项

pip install -r requirements.txt

4. 配置环境

Copy-Item .env.example .env

最低必需内容：

# Global LLM provider fallback: anthropic | openai | google | openrouter (default: openrouter)
# Note: Each org can override via PUT /llm-config
AGENT_PROVIDER=openrouter
# Default model is ~deepseek/deepseek-flash-latest.
# For OpenRouter DeepSeek models, Teardrop delegates provider eligibility to the API key's OpenRouter data policy.
OPENROUTER_API_KEY=sk-or-...      # required if AGENT_PROVIDER=openrouter
# ANTHROPIC_API_KEY=sk-ant-...     # required if AGENT_PROVIDER=anthropic
# OPENAI_API_KEY=sk-...           # required if AGENT_PROVIDER=openai
# GOOGLE_API_KEY=...              # required if AGENT_PROVIDER=google

DATABASE_URL=postgresql://teardrop:teardrop@localhost:5432/teardrop

# Optional: Redis for distributed caching
# REDIS_URL=redis://localhost:6379/0

5. 生成 RSA 密钥

应用启动时会自动生成 RSA 密钥对（存入 keys/）。 如需提前手动生成（可选），请运行：

python scripts/generate_keys.py

6. 运行数据库迁移

python -m migrations.runner

7. 初始化默认组织和管理员用户

python scripts/seed_users.py

8. 运行 API 服务

uvicorn teardrop.main:app --reload

服务将在 http://localhost:8000 启动。访问 http://localhost:8000/docs 可使用交互式 API 浏览器。

---

部署

Docker（本地完整堆栈）

docker compose build --pull
docker compose up

启动 Postgres 和 Teardrop API。启动时会自动运行迁移。密钥在构建时生成，并从 ./keys/ 挂载。重新构建前请使用 docker compose build --pull，以获取更新后的基础镜像；如需完全重新构建，请添加 --no-cache。

Render（生产环境）

仓库包含一个 render.yaml，用于配置单个 Standard（1c-2g）Web 服务实例，并连接到 Neon Postgres 和共享 Redis 服务。默认数据库连接预算为 7 个：每个实例最多 6 个应用程序连接池连接，另加 1 个 LangGraph 检查点连接。部署或增加实例数量前，请确认在已配置的 Neon 连接数限制内仍有余量。

环境变量、安全凭据、数据库配置和速率限制的完整列表，请参阅专门的 docs/configuration.md 参考指南。

---

身份验证

Teardrop 会签发 RS256 JWT。受保护的业务端点需要 Bearer 令牌。公开的身份验证、注册、账单定价、健康检查、文档、Agent 卡片，以及受支付门控的 POST /message:send A2A 接口均无需身份验证，详情如下。

1. 客户端凭据（机器到机器）

$resp = Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"client_id":"teardrop-client","client_secret":"<JWT_CLIENT_SECRET>"}'
$token = $resp.access_token

生成的 JWT 包含 auth_method: "client_credentials"。请在 .env 中设置 JWT_CLIENT_ID 和 JWT_CLIENT_SECRET。

2. 电子邮件 + 密码

$resp = Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"email":"[email protected]","secret":"<password>"}'

生成的 JWT 包含 auth_method: "email"。请通过 POST /admin/users 创建用户。

3. SIWE — 使用以太坊登录

SIWE 允许以太坊钱包持有者无需密码即可进行身份验证。签发的 JWT 包含 auth_method: "siwe" 和调用方的 address。

1. GET  /auth/siwe/nonce   → { "nonce": "abc123..." }
2. Construct an EIP-4361 SIWE message with that nonce
3. Sign with your wallet (EIP-191)
4. POST /token  { "siwe_message": "...", "siwe_signature": "0x..." }
   → { "access_token": "..." }

SIWE 令牌用于验证钱包身份；新的钱包地址会在首次登录时自动注册。通过机器配置的 SIWE 组织使用预付额度运行 Agent；请通过下方的 Agent 资金注入流程为该额度充值。

4. x402 付费优先引导

外部 Agent 无需邮箱、人工注册或预先获取 JWT，即可引导创建账户。从 /.well-known/agent-card.json 或 /.well-known/x402 中的 bootstrap 块（也可从 /.well-known/x402.json）发现此流程，然后发送 POST /token，并附上 {"grant_type":"x402"}。引导发现需要启用 BILLING_ENABLED、MACHINE_PROVISIONING_ENABLED 和 X402_ONBOARDING_ENABLED。其支付要求与顶层运行价格的 accepts 分开。发现信息中的价格仅供参考。首次令牌请求会返回 402 Payment Required，其中包含当前的 x402 要求，要求预付足够的额度，以满足客户端凭据运行的预留额。使用已签名的 Payment-Signature 标头（或旧版 X-Payment 标头）重试。

首次结算成功后，Teardrop 会返回一个短期有效的访问令牌，以及一次性 client_id 和 client_secret。请立即保存密钥；之后无法重新获取。后续计费运行请使用这些凭据，通过现有的客户端凭据 /token 流程获取令牌。机器配置的组织不会获得促销额度，并会按配置的 MACHINE_ORG_DAILY_SPEND_LIMIT_USDC 滚动上限开始使用（默认值：每 24 小时 $5.00）。对于受信任的组织，明确设置的操作员组织限额会予以保留；存储的限额为零时，则使用配置的默认值。

Agent 资金补充流程

完成一次引导后，使用返回的客户端凭据调用 GET /billing/topup/usdc/requirements?amount_usdc=...，并为返回的 x402 要求签名。在预付余额耗尽前，将已签名的标头提交到 POST /billing/topup/usdc。现有机器组织也可以重复通过 grant_type=x402 支付；此时会复用其客户端 ID，并省略 client_secret。如果原密钥丢失，请通过 SIWE 进行身份验证，并使用 POST /org/credentials/regenerate 重新生成凭据。

令牌过期与刷新令牌

邮箱、客户端凭据和 SIWE 身份验证方式会签发有效期为 30 分钟的访问令牌（令牌响应中的 expires_in: 1800 秒）。x402 引导也会返回一个有效期为 30 分钟的访问令牌，但不会签发刷新令牌。对于需要超过 30 分钟会话的应用，请使用邮箱或 SIWE 流程中的刷新令牌：

• 刷新令牌有效期为30 天，可兑换新的访问令牌和轮换后的刷新令牌。
• 刷新令牌轮换与幂等重放保护以原子方式执行——如果在重放窗口内两次提交同一刷新令牌，将收到相同的新令牌对，而不会创建重复令牌。
• 通过 POST /auth/logout 单点注销可撤销刷新令牌，立即结束会话。

# 1. Exchange refresh token for new access token + rotated refresh token
$resp = Invoke-RestMethod -Uri "http://localhost:8000/auth/refresh" `
    -Method Post -ContentType "application/json" `
    -Headers @{ "Cookie" = "refresh_token=<your-refresh-token>" }
    # OR pass as body: -Body '{"refresh_token":"<your-refresh-token>"}'

# New access token and rotated refresh token are in the response
$newAccessToken = $resp.access_token
$newRefreshToken = $resp.refresh_token  # Use this on your next refresh

# 2. Logout (revoke refresh token)
Invoke-RestMethod -Uri "http://localhost:8000/auth/logout" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $accessToken" }

---

LLM 配置（按组织）

组织可以配置首选的 LLM 提供商、模型、路由策略，还可以自带 API 密钥（BYOK）。这将支持：

• 多提供商选择：使用 Anthropic、OpenAI、Google，或指向可自托管的端点（vLLM、Ollama、OpenRouter）
• 自带密钥（BYOK）：加密并存储自己的 API 凭据——Teardrop 永远不会看到您的密钥。BYOK 组织只需支付平台编排费用（BYOK_TIER_PRICING_ENABLED=true 时按令牌计费，否则收取固定费用）；LLM 提供商直接向其自有密钥计费。
• 智能路由：根据成本、速度或质量自动选择模型
• 支持自托管：通过 api_base 参数使用任何兼容 OpenAI 的端点

组织 LLM 配置端点

方法	路径	身份验证	描述
GET	/llm-config	Bearer	获取组织的 LLM 配置（如未配置，则返回全局默认值）
PUT	/llm-config	Bearer	设置或更新组织的 LLM 配置
DELETE	/llm-config	Bearer	删除配置并恢复为全局默认值

示例：将组织的 LLM 设置为 GPT-4o，并按成本路由

$token = (Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"client_id":"teardrop-client","client_secret":"<secret>"}').access_token

Invoke-RestMethod -Uri "http://localhost:8000/llm-config" `
    -Method Put -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Body @{
        provider = "openai"
        model = "gpt-4o"
        routing_preference = "cost"  # or "speed", "quality", "default"
        max_tokens = 4096
        temperature = 0.7
    } | ConvertTo-Json

对于 BYOK，请添加自己的 api_key（静态加密）。对于自托管端点（vLLM、Ollama 或任何与 OpenAI 兼容的服务），请将 api_base 设置为端点 URL。

推理提示因提供商而异：Google 使用有文档说明的、按模型配置的思考级别或预算（在 Gemini 3.8 Flash 上，none 会变为 low）；对于未知的 Google 模型 ID，则保留提供商默认值。OpenRouter 接收 reasoning.effort，但受其模型支持的力度限制。原生 OpenAI 和 Anthropic BYOK 保留默认值。有关优先级和限制，请参阅推理力度兼容性。

路由偏好

将 routing_preference 设置为 "default" 以外的值时，Teardrop 会根据你的条件，从标准模型池中自动选择模型：

偏好	行为
default	使用你配置的提供商/模型
cost	选择最便宜的模型（按输入 Token 和输出 Token 的价格计算）
speed	选择速度最快的模型（依据实时基准测试的 p95 延迟；对于新部署，则回退到官方规格）
quality	选择质量最高的模型

注意：如果你设置了 BYOK（自定义 API 密钥），路由功能会被禁用——始终使用你配置的模型。

LLM 积分模式

Teardrop 预付积分（或链上 x402 结算）涵盖每次运行的全部成本，但具体收费项目取决于组织使用的是平台 LLM 密钥还是 BYOK：

模式	谁向 LLM 提供商付费	Teardrop 从组织扣除的费用
平台密钥（默认）	Teardrop	根据运行模型的 pricing_rules 行计算的模型 Token 费用，以及工具调用费用
BYOK	组织通过自己的密钥直接付费	平台编排费（固定 BYOK_PLATFORM_FEE_USDC，默认为每次运行 $0.001；或在 BYOK_TIER_PRICING_ENABLED=true 时按 Token 计费的编排费用，最低为该固定费用），以及工具调用费用。此费用在使用事件和 SSE 计费事件中显示为 platform_fee_usdc。

所有界面和所有模型的工具调用均按相同方式定价：依次采用管理员覆盖价格、作者或平台价格，以及全局 pricing_rules.tool_call_cost。模型专属规则仅对 Token 定价。没有单价费率的规则采用固定费率：其 run_price_usdc 每次运行收取一次 Token 费用（而非每次 LLM 对话轮次收取），工具调用费用则另行计收。

对于 Agent 运行，工具调用在成功时，或返回工具报告的业务错误（例如，协议或钱包未知）时计费。基础设施故障不计费：超时、上游中断或速率限制、无效的上游响应、无效参数，以及意外的执行器错误。

换言之，BYOK 并不会免除 Teardrop 积分或 x402 结算的需求——它只是从 Teardrop 账单中移除 LLM 模型费用。

---

模型基准测试

Teardrop 持续跟踪每个已部署 LLM 的运营指标。这些基准测试会为模型路由决策提供依据。

基准测试端点

方法	路径	身份验证	描述
GET	/models/benchmarks	—	公开：所有模型的目录元数据和实时指标
GET	/models/benchmarks/org	Bearer	按组织范围：仅包含你组织使用情况的指标

了解指标

每个模型条目都包含目录元数据（provider、model、display_name、context_window、supports_tools、quality_tier、pricing）以及实时 benchmarks：

• total_runs_7d：过去 7 天内使用此模型的运行次数（仅当运行次数 >= 10 时才会包含基准数据）
• avg_latency_ms：从开始到完成的平均耗时（毫秒）
• p95_latency_ms：第 95 百分位延迟，也就是最慢的 5% 运行的延迟
• avg_cost_usdc_per_run：每次运行的平均成本（输入 + 输出令牌 + 工具）
• avg_tokens_per_sec：流式传输吞吐量（适用于实时应用）
• quality_tier：静态等级（1 = 最佳，2 = 良好），用于基于质量的路由

---

计费与支付（x402）

Teardrop 实现了 x402 支付协议。当 BILLING_ENABLED=true 时，请求必须包含支付信息。设置 BILLING_ENABLED=false（默认值）即可在开发期间不启用计费。

工作原理

Teardrop 实现了 x402 支付协议。当 BILLING_ENABLED=true 时，请求必须包含支付信息。设置 BILLING_ENABLED=false（默认值）即可在开发期间不启用计费。

未支付的 POST /agent/run 请求会返回 402 Payment Required，其中包含 x402 v2 PaymentRequired 信封（PAYMENT-REQUIRED 标头，以及旧版 X-PAYMENT-REQUIRED）。客户端对支付进行签名后，使用 Payment-Signature 标头重试；Teardrop 会通过 facilitator 验证支付，流式传输 SSE 响应，并在运行结束后发出包含链上 tx_hash 的 BILLING_SETTLEMENT 事件。

不同认证类型的支付方式

认证方式	支付机制
siwe	由人类拥有的组织：使用 x402 链上支付（USDC，exact 或 upto 方案，按请求计费）；由机器创建的组织：仅使用预付额度，并受每日硬性上限约束
client_credentials	组织预付额度余额（链下扣款）
email	组织预付额度余额（链下扣款）

x402 支付优先的引导流程会收取一笔按预留额度计算的 x402 支付，在发放凭证前完成结算，并将对应的原子 USDC 金额充值到新组织。该流程不会使用已验证邮箱的促销赠额。经过认证的机器凭证可以使用 /billing/topup/usdc 余额充值接口（额度更大、频率更低），而非按次支付。

x402 支付方案

方案	工作原理	配置
exact（默认）	客户端对准确的运行价格签名；facilitator 结算该金额。	X402_SCHEME=exact
upto	客户端对一个上限（X402_UPTO_MAX_AMOUNT）签名；运行结束后，Teardrop 通过 Permit2 结算实际使用费用（≤ 上限）。	X402_SCHEME=upto

upto 客户端要求：使用 X402_SCHEME=upto 前，支付钱包必须先在目标链上为 USDC 授权 Permit2 一次： IERC20(USDC).approve(PERMIT2_ADDRESS, type(uint256).max)。每个钱包只需执行一次链上交易。尚未授权 Permit2 的客户端可以始终使用 402 响应中 accepts 数组里的 scheme: exact 作为备用方案。

定价

定价通过 pricing_rules 数据库表动态配置。当前费率（基于用量的 v1）：

指标	费率
输入令牌	$0.0015 / 1k 令牌
输出令牌	$0.0075 / 1k 令牌
工具调用	默认每次调用 $0.001；平台工具使用各自的工具价格（最低 $0.005，参见 docs/tools-catalog.md）
每次运行最低费用	$0.01

查看实时定价：GET /billing/pricing

作为 x402 客户端运行（SIWE 支付）

# 1. Get a SIWE JWT (see Authentication above)
# 2. Call /agent/run — you'll get a 402 with payment requirements
# 3. Construct and sign the x402 transferWithAuthorization (EIP-3009)
# 4. Retry with the signed payment header

Invoke-RestMethod -Uri "http://localhost:8000/agent/run" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token"; "Payment-Signature" = "<x402-header>" } `
    -Body '{"message":"What is the ETH balance of vitalik.eth?","thread_id":"session-1"}'

运行完成后，流中会包含一个带有链上 tx_hash 的 BILLING_SETTLEMENT 事件。

额度充值（机器调用方）

管理员可以向组织余额添加预付 USDC 额度：

Invoke-RestMethod -Uri "http://localhost:8000/admin/credits/topup" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $adminToken" } `
    -Body '{"org_id":"org-123","amount_usdc":1000000}'   # $1.00

完整的计费环境变量列表（BILLING_ENABLED、X402_*、BILLABLE_AUTH_METHODS 等），请参阅 docs/configuration.md。

---

A2A 委派与跨 Agent 收益路由

Teardrop Agent 可以将任务委派给符合 A2A 标准的远程 Agent，并将这些委派的费用计入发起请求的组织。这将实现去中心化的专业分工、内置的支出编排和自动收益路由。

机器可读的 /.well-known/registry-benefits.json 合约说明了组织如何注册 A2A 端点、可获得哪些发现和建议性声誉权益，以及哪些保障明确不予提供。

有关详细的协议规范、系统配置、允许列表和计费事件负载结构，请参阅 docs/a2a-delegation.md 指南。

---

发布到 Agentic Market

使用付费 A2A 接口的完整公开 URL，例如 https://api.teardrop.dev/message:send，并使用 POST 方法。不要注册不带路径的源站 https://api.teardrop.dev/（GET / 会重定向到 /docs，而 POST / 不是付费入口）。

Agentic Market 验证器可能会探测 /.well-known/x402、/.well-known/x402.json 和配置的端点 URL。Teardrop 会公开提供这些发现别名，并在未付费的匿名 POST /message:send 请求中，于请求正文验证前发出 x402 挑战。该挑战包含完整的 x402 v2 PaymentRequired 信封（PAYMENT-REQUIRED）、旧版 X-PAYMENT-REQUIRED 别名、描述付费接口的顶层 resource（包含 url、描述，以及 Teardrop 共用的 serviceName、tags 和 iconUrl），以及用于描述 A2A 请求／响应格式的 extensions.bazaar。

对于验证器，MCP 端点 POST https://api.teardrop.dev/tools/mcp 的行为相同：正文为空或不是 JSON-RPC 消息的匿名 POST，或 Accept 标头不含 text/event-stream 的匿名 GET，都会收到 HTTP 402；其 extensions.bazaar 会声明一个付费的 tools/call 示例（get_token_price），价格为该工具的费用。未付费的匿名 tools/call 请求会收到每个工具各自的 MCP Bazaar 元数据，其中包括工具的输出架构（如果完整架构会超出 402 标头大小限制，则只包含顶层字段）。每个 MCP 402 的 resource 还会携带 Bazaar 服务元数据（serviceName、tags，以及在 AGENT_CARD_ICON_URL 为绝对 http(s) URL 时取自该变量的 iconUrl），以便目录为条目添加标签。SSE GET、经过身份验证的请求、MCP 握手和 tools/list 均使用常规 MCP 传输。

Bazaar 会单独列出每个 MCP 工具，且只有在通过 CDP facilitator 完成该工具的付款结算后才会列出。python -m scripts.seed_bazaar_listings --base-url https://api.teardrop.dev 会为所有付费工具报价，但不会付款；设置 TEARDROP_SEED_PRIVATE_KEY 并添加 --execute，即可为每个工具发出一次已结算调用。该命令会在首次失败时停止；如果网关的 402 缺少 Bazaar 元数据或输出声明，则拒绝付款。CDP facilitator 会从 MCP 类型记录中移除 serviceName、tags 和 iconUrl，因此 Teardrop 品牌只有通过携带相同元数据的 HTTP /message:send 条目才能展示在 Agentic.Market 等目录中；使用 --a2a --execute 将其播种一次。

发布到 Smithery

Teardrop 会通过 /.well-known/mcp/server-card.json 自动发布其 MCP 工具。要在 Smithery 上分发：

1. 将 Teardrop 实例的公开基础 URL 复制到 Smithery 的 URL Deployment 向导中。
2. 在 Smithery CLI 或发布向导中提供以下 Configuration Schema（JSON），以启用 x402 匿名能力：

   {
     "type": "object",
     "properties": {
       "apiKey": {
         "type": "string",
         "title": "API Key",
         "x-from": { "header": "x-teardrop-key" },
         "x-to": { "header": "Authorization" }
       }
     }
   }
   

3. 在 Smithery 控制面板中设置显示名称、描述、主页和图标，以获得最高 100/100 的质量评分。

发布到 MCP 注册表

官方条目为 io.github.HASAVAGE/teardrop，地址是 https://api.teardrop.dev/tools/mcp（Streamable HTTP，无软件包）。元数据位于仓库根目录的 server.json 中，且 name 必须与已发布的命名空间一致。要发布新版本：更新 server.json 中的 version 和 remotes，然后在仓库根目录运行 mcp-publisher validate、mcp-publisher login github 和 mcp-publisher publish。

API 参考

Teardrop 通过 OpenAPI 提供交互式可视化 API 浏览器，地址分别为 /docs（Swagger UI）和 /redoc（ReDoc UI）。

如需查看涵盖 Core、Auth、Billing、Marketplace、Wallets、Admin、Custom Tools、Memory、MCP Federation 和 A2A Delegation 各模块的所有端点完整表格，请参阅 docs/api-reference.md 指南。

---

运行 MCP 工具服务（可选）

这些工具可通过 MCP 协议独立提供服务，以供 Claude Desktop、VS Code 或任何兼容 MCP 的客户端使用：

# stdio transport (default – for Claude Desktop / VS Code)
python tools/mcp_server.py

# HTTP SSE transport
python tools/mcp_server.py --transport=sse

---

工作原理

Teardrop 使用可移植的 Agent 节点，并通过 LangGraph 路由/检查点适配器进行管理，同时向其 Server-Sent Events（SSE）层发送与框架无关的运行时事件。

如需了解完整的架构设计、执行流程状态图、SSE 流事件说明和结构化 A2UI 组件架构，请参阅 docs/architecture.md 参考文档。

---

数据库

Teardrop 使用 Postgres（生产环境推荐 Neon，开发环境可通过 Docker 在本地运行）。

迁移

当前的架构变更位于 migrations/versions/ 中。当前的 102_squashed_baseline.sql 取代了 migrations/archive/ 中的历史文件。运行迁移：

python -m migrations.runner

如需了解当前基线、替换清单，以及架构迁移、种子条目和索引的历史目录，请参阅 docs/migrations.md 目录。

Neon（生产环境）

将 DATABASE_URL 设置为你的 Neon 连接字符串。推荐使用普通的 postgresql://；仍然接受旧版 postgresql+asyncpg:// 值。

---

项目结构

teardrop/
  app.py              # FastAPI app, lifespan, middleware, background workers, router registration
  main.py             # Compatibility entrypoint (re-exports teardrop.app)
  routers/            # APIRouter modules (agent.py, billing.py, marketplace.py, auth.py, admin/, org/, …)
  config.py           # Settings via pydantic-settings (reads .env)
  auth.py             # RS256 JWT & refresh tokens (email, client_credentials, SIWE)
  users/              # Org + User models, CRUD, PBKDF2-SHA256 password hashing
  billing/            # x402 billing layer, pricing, invoice queries, credit system
  marketplace/        # Marketplace catalog, earnings, reputation, subscriptions, withdrawals
  mcp_client/         # Per-org MCP client: CRUD, session pool, tool discovery
  org_tools/          # Per-org custom webhook tools: CRUD, caching, execution
  memory.py           # Per-org pgvector memory: LLM extraction, recall, CRUD
  agent/              # LangGraph graph, nodes, LLM factory, runtime context/events
  agent_runtime.py    # Agent run orchestration (scheduled/event-triggered runs)
  mcp_gateway.py      # MCP gateway middleware (direct tool invocation + billing)
tools/
  registry.py         # ToolRegistry: versioned, with deprecation lifecycle
  mcp_server.py       # Standalone MCPServer for MCP protocol clients
  definitions/        # One file per tool (calculate, get_datetime, web_search, …)
migrations/
  runner.py           # Applies active SQL migrations and squash baselines
  versions/           # Active SQL and .replaces manifests
  archive/            # Git-only historical migrations superseded by baselines
shared/               # Internal shared utilities: db pool registry, audit inserts, webhook caller
scripts/              # generate_keys.py, seed_users.py, audit_dependencies.py, export_api_spec.py, …

如需了解完整的架构设计、执行流程状态图、SSE 流事件说明和结构化 A2UI 组件架构，请参阅 docs/architecture.md 参考文档。

---

Coinbase Developer Platform 集成

Teardrop 可通过 Coinbase Developer Platform（CDP）为每个组织配置 USDC 钱包，用于接收委托付款和市场收益。此功能需要 CDP 账户（cdp.coinbase.com）以及具有 wallet:create 权限的 API 密钥（Key ID、Key Secret 和 Wallet Secret）。通过 AGENT_WALLET_* 和 CDP_* 环境变量进行配置（参见 docs/configuration.md）。CDP 每次操作收费 $0.005；免费套餐每月包含 5,000 次操作。

每个组织在每条链上可持有一个钱包（例如 Base Sepolia 测试网、Base 主网）。钱包会自动接收委托付款和 MCP 市场收益。

---

许可证

Teardrop 根据 Business Source License 1.1 授权。

• 可免费用于非生产环境的评估和开发。
• 商业生产用途需要从维护者处获取商业许可证。
• **变更日期：**2030 年 4 月 3 日——届时，代码将自动转换为 AGPL-3.0-only。

完整条款请参阅 LICENSE。有关商业许可的咨询，请查看 LICENSE 文件中的联系地址。

欢迎在同一许可证下贡献代码——请参阅 CONTRIBUTING.md。 如需报告安全漏洞，请参阅 SECURITY.md。