diff --git a/docs/README.md b/docs/README.md index 82701e5c2..f74486373 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,14 @@ 项目工程计划与技术文档索引。 +## 🚀 新方向（设计中）：One API to access all agents + +把 TakoAPI 从「OpenClaw Skills Marketplace」升级为「**agent 市集 + 统一调用 API**」的转型设计轨道，见 **[agent-marketplace/](agent-marketplace/README.md)**（调研 + 方案，**尚未动手实现**，等用户拍板 [待决策清单](agent-marketplace/06-open-questions.md)）。 + +下面 00–03 是**现有 skills 业务**的工程文档（均已上线），与新方向并行。 + +--- + ## 📋 当前路线图 按顺序执行： diff --git a/docs/agent-marketplace/00-vision-and-positioning.md b/docs/agent-marketplace/00-vision-and-positioning.md new file mode 100644 index 000000000..cdf708142 --- /dev/null +++ b/docs/agent-marketplace/00-vision-and-positioning.md @@ -0,0 +1,109 @@ +# 00 · 愿景与定位 + +> Slogan：**One API to access all agents** + +--- + +## 1. 一句话愿景 + +把 TakoAPI 从「给 coding agent 安装 **skill** 的内容目录」，升级为「用**一个 API** 发现并**调用**任意 **agent** 的市集 + 网关」。 + +- **现在**：用户/agent 来 TakoAPI **找静态内容**（skill = markdown/配置），装进自己的 Claude Code / Cursor。 +- **目标**：开发者用**一个 key**，把请求发给 TakoAPI，由我们**路由并调用**任意已注册的第三方 agent，统一鉴权、计费、可观测——并给 agent 作者分成。 + +## 2. 核心类比：OpenRouter for agents + +| | OpenRouter | TakoAPI（目标） | +|---|---|---| +| 一句话 | One API to access all **LLMs** | One API to access all **agents** | +| 被路由的单位 | 模型推理（token） | agent 任务（task / call） | +| 发现层 | 模型目录 | agent 市集（基于 AgentCard） | +| 调用层 | 统一 `/v1/chat/completions` | 统一 gateway（A2A 透传 + OpenAI 兼容 shim） | +| 变现 | 充值费 ~5.5% + BYOK toll（推理零加价） | 同款 + 给 publisher 分成 | +| 护城河 | 跨 provider 路由/fallback | 跨厂商 agent 路由/fallback + 统一账单 + 验证身份 | + +调研验证了两点（见 [01](01-landscape-and-standards.md)）：(1) 这个生态位**无人占据**；(2) OpenRouter 的「零加价 + 充值费 + BYOK toll」money model 已被整个网关品类反复验证。 + +## 3. 我们到底做什么——三层 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 3. Commercial 层 — credits / 计量 / 计费 / 给作者分成 │ +├─────────────────────────────────────────────────────────┤ +│ 2. Gateway 层 — 一个 API key，路由调用任意 agent │ +│ （A2A 透传 + OpenAI 兼容 shim） │ +├─────────────────────────────────────────────────────────┤ +│ 1. Registry 层 — agent 市集：发现 / 搜索 / 分类 / │ +│ 验证 / 评分（基于 A2A AgentCard） │ +└─────────────────────────────────────────────────────────┘ +``` + +1. **Registry / 市集（发现）**：列出所有 agent，用标准化的 **AgentCard** 描述（name、endpoint、能力 `skills[]`、定价、鉴权方式），提供搜索 / 分类 / 评分 / trending。**——这一层最大程度复用现有 skills 市集的 UX、auth、基础设施。** +2. **Gateway（调用）**：一个 base URL + 一个 API key，把调用路由到任意已注册 agent；处理鉴权、限流、超时/重试/断路、流式、计量。 +3. **Commercial（变现）**：预付 credits、用量计量、给 agent 作者分成与结算。 + +> 详细产品面见 [02-product-spec.md](02-product-spec.md)；技术实现见 [03-technical-architecture.md](03-technical-architecture.md)。 + +## 4. 目标用户（双边市场） + +| 边 | 是谁 | 痛点 | 我们给什么 | +|---|---|---|---| +| **需求方**（Consumers / Developers） | 想用多个 agent 拼业务的开发者、agent 编排者、其它平台 | 要对接 N 个 agent = N 个合同、N 个 key、N 套鉴权、N 张账单 | **一个 key、一张账单、任意 agent**；BYOK；无锁定 | +| **供给方**（Publishers / Builders） | 做了 agent 想触达用户并变现的人 | 自建分发、计费、鉴权太重；没有流量入口 | **一键上架**（提交 AgentCard URL）+ 现成计费/结算 + 市集流量 | + +冷启动顺序：**先把供给方（agent 供给）做厚**（registry-first），再放量需求方。详见 [05-roadmap.md](05-roadmap.md)。 + +## 5. 价值主张与品牌 + +- **核心承诺**：*"One API key, one bill, any agent."* +- **中立的瑞士**：我们不卖自家 agent、不绑自家云，没有偏向任何厂商的动机——这正是 OpenRouter 对各大模型厂的信任优势。把**厂商中立 + 无锁定 + BYOK** 写成显式的、可兑现的品牌承诺。 +- **透明定价**：所有 take-rate 公开（企业市集都藏着掖着——把透明当卖点）。 +- **品牌契合**：Tako（章鱼）多腕触达四方，天然呼应「一个 API、千百 agent」。Slogan 与现有品牌不冲突，可平滑过渡。 + +## 6. 与现有 skills 业务的关系 + +现有资产**不浪费**，但**主角换人**： + +| 现有资产 | 处置 | +|---|---| +| Next.js 16 + Prisma + Postgres + Cloud Run + cloudbuild | ✅ 直接复用 | +| NextAuth（邮箱/Google/Apple）+ API key | ✅ 复用并扩展（API key 升级为网关 key，见 [04](04-data-model.md)） | +| 市集 UX（分类 / 搜索 / 卡片 / 详情 / likes / ratings / bookmarks / trending） | ✅ 复用给 agent 列表（现有孤立表 Rating/Bookmark 正好激活） | +| `RequestLog` 表 | ✅ 演进为 usage 计量的雏形 | +| `/api/agent` 发现端点 | ✅ 升级为 agent 目录 + registry API | +| `AgentType` 枚举 / `src/lib/agents.ts` | ⚠️ 部分复用——但注意语义差异（见下） | +| **5,146 条 skill 数据 + 30 分类** | 🟡 作为 legacy 内容品类**保留并存**（不删，符合 2026-04-22「未搞清用途不删」决策） | + +> ⚠️ **关键语义澄清**：现有的 `AgentType`（CLAUDE_CODE / CURSOR…）描述的是「**消费 skill 的 coding agent**」——skill 是装进它们的静态内容。而新业务里的 **Agent** 是「**可被调用的服务实体**」（有 endpoint、有 AgentCard、能跑任务）。两者是不同的东西。所以新模型用全新的 `Agent` 实体，**不强行复用 `Skill`**（详见 [04-data-model.md](04-data-model.md)）。 + +**推荐定位**：skills 成为市集的一个子品类（"coding agent skills"），新主线是 invokable agents。首页与 slogan 以 agent 为英雄。 + +## 7. 战略形态：三个选项（需用户拍板，见 [06](06-open-questions.md)） + +| 选项 | 形态 | slogan 贴合度 | 护城河 | 基础设施重量 | 变现 | +|---|---|---|---|---|---| +| **A. Proxy Gateway**（推荐终局） | 调用流量**过我们的网关**，我们计量/计费/路由 | 🟢 最贴合 | 🟢 强（统一账单+路由+身份） | 🔴 重（流式代理、限流、计量） | 🟢 强（充值费 + 分成 + BYOK toll） | +| **B. Directory + Connect**（轻） | 只做发现 + 标准化连接（A2A/MCP），调用**直连**不过我们 | 🟡 中 | 🔴 弱（容易被绕过） | 🟢 轻 | 🔴 弱（只能广告/订阅） | +| **C. Agent Hosting**（最重） | 我们**托管运行** agent | 🟢 贴合 | 🟢 强 | ⛔ 最重（运行时/隔离/扩缩容） | 🟢 强（消耗计费） | + +**推荐**：以 **A 为终局**，但用 **B 作为冷启动**——即 **"registry-first, gateway-fast-follow"**： + +1. 先做 **Registry**（B 的轻量发现层）把 agent 供给做厚、把搜索/验证做好； +2. 紧接着加 **Gateway**（A 的调用层）把流量与计费收拢； +3. **C（hosting）先不做**——等有明确需求再说。 + +这样冷启动摩擦最低（无需先建重型网关就能有内容和流量），又不放弃 A 的终局护城河。 + +## 8. 北极星与早期指标 + +- **北极星**：通过网关**成功完成的 agent 任务数 / 周**（GMV 的前导）。 +- 供给侧：注册并**通过验证**的 agent 数；活跃 publisher 数。 +- 需求侧：持有 API key 并**本周有调用**的开发者数；开发者周留存。 +- 商业：credits 充值额；通过平台结算给 publisher 的金额；take-rate 收入。 + +## 9. 非目标（先不做，避免铺太大） + +- 不自建/托管运行第三方 agent（选项 C）。 +- 不做复杂多 metric 定价、不做企业 postpaid 发票（先 prepaid credits）。 +- 不自研支付协议；agentic payments（x402 / AP2 / ACP）**仅观察**，非 v1 依赖（见 [03 §计费](03-technical-architecture.md) 与 [01](01-landscape-and-standards.md)）。 +- 不做又一个「消费者浏览 agent」的 storefront——我们做**开发者基础设施**（storefront 底下的 Stripe）。 diff --git a/docs/agent-marketplace/01-landscape-and-standards.md b/docs/agent-marketplace/01-landscape-and-standards.md new file mode 100644 index 000000000..ea2958ac8 --- /dev/null +++ b/docs/agent-marketplace/01-landscape-and-standards.md @@ -0,0 +1,119 @@ +# 01 · 格局与标准调研 + +> 调研时间：2026-06-13。来源均附链接。标注「⚠️ 待核实」处为二手来源或推断，落地前需复核。 + +--- + +## TL;DR（先读这段） + +1. **标准已收敛**：2026 年中，agent 互操作已收敛为 **Linux Foundation 治理的两层栈**——**A2A**（agent↔agent）+ **MCP**（agent↔tool）。竞争协议（IBM-ACP、Cisco/AGNTCY-ACP）**都已并入 A2A**。 +2. **A2A 是我们的标准**：`AgentCard`（`/.well-known/agent-card.json`）是事实上的「机器可读 agent 描述符」，同时承载发现（`skills[]`）与调用（endpoint + 鉴权 + task 生命周期）。 +3. **市场空白真实存在**：「一个统一 API + SDK，跨厂商**发现并调用**任意 agent，一张账单」是**缺失的中间层**。企业市集是单厂商围墙，独立市集是消费者目的地，registry 只发现不计费。 +4. **money model 已验证**：OpenRouter 的「推理零加价 + 充值费 ~5.5% + BYOK toll」被整个网关品类反复采用。 +5. **护城河**：A2A 标准化了「卡片 + 传输」，但**没有跨域的全局发现 / 命名 / 解析层**——市集可以「**成为那个 registry**」。 + +--- + +# Part A · 开放标准 + +## A2A（Agent2Agent Protocol）— 我们的核心标准 + +- **来源与治理**：Google 2025-04 开源，2025-06 捐给 **Linux Foundation** 成立 A2A 项目；Apache-2.0。 + 来源：[Linux Foundation 公告](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents) +- **当前版本 v1.0**（2026 年初首个稳定生产版）。v1.0 四大要点： + 1. **Signed Agent Cards**——对卡片做密码学签名，客户端可验证卡片确由域名所有者签发（**市集信任的关键原语**）； + 2. **多租户**——单 endpoint 托管多个 agent； + 3. **多协议绑定**——同一逻辑 agent 同时暴露 **JSON-RPC + gRPC**； + 4. **版本协商**——v0.3 → v1 向后兼容迁移。 + 来源：[a2a-protocol.org v1.0 公告](https://a2a-protocol.org/latest/announcing-1.0/)、[GitHub a2aproject/A2A](https://github.com/a2aproject/A2A)（⚠️ patch 号 v1.0.1 / 2026-05-28 来自仓库页，未单独核实） +- **AgentCard 结构**：发布在 well-known URI（当前 **`/.well-known/agent-card.json`**，旧 v0.2 路径 `/.well-known/agent.json` 仍在野，网关应两者都兼容）。字段：`name`、`description`、`provider`、`url`（服务端点）、`version`、`capabilities`（`streaming`/`pushNotifications`）、安全 `schemes`（Bearer/OAuth2…）、`skills[]`（每个含 `id`/`name`/`description`/`inputModes`/`outputModes`/`examples`）。 + 来源：[A2A Agent Discovery 文档](https://a2a-protocol.org/latest/topics/agent-discovery/) +- **三种发现方式**：(1) well-known URI GET；(2) **curated registries**（按 skill/tag 查询，**协议明确祝福的模式——就是我们要做的**）；(3) 直接配置。另有需鉴权的 **extended AgentCard**。 +- **Task 生命周期**：`SUBMITTED → WORKING → (INPUT_REQUIRED / AUTH_REQUIRED) → COMPLETED / FAILED / CANCELED / REJECTED`。 + 来源：[A2A 规范](https://a2a-protocol.org/latest/specification/) +- **传输**：JSON-RPC 2.0 over HTTPS；流式走 **SSE**；异步走 **push notification（webhook）**；v1.0 增 gRPC。 +- **采用度（强）**：2026-04 一周年报告 **150+ 组织**（AWS、Cisco、Google、IBM、Microsoft、Salesforce、SAP、ServiceNow…），GitHub 22k+ star，5 种语言 SDK；已集成进 Azure AI Foundry、Amazon Bedrock AgentCore、Google Cloud。 + 来源：[Linux Foundation 一周年报告](https://www.linuxfoundation.org/press/a2a-protocol-surpasses-150-organizations-lands-in-major-cloud-platforms-and-sees-enterprise-production-use-in-first-year) + +**→ 对我们**：把每个 agent 的 `/.well-known/agent-card.json` 抓进来，索引 `skills[]` 做发现/搜索，校验 signed card 做信任；调用时读 `url` + `schemes` + `capabilities`，代理一个 JSON-RPC `message/send`（或 SSE 流），按 TaskState 跟踪。**我们本质上是「一堆 A2A server 前面的 A2A client + curated registry」。** + +## MCP（Model Context Protocol）— 工具层，不是 agent + +- **关键区分**：MCP 标准化的是「agent ↔ **工具/资源**」，**不是** agent ↔ agent。MCP server 是**能力/工具**，不是自主 agent。协议维护者自己也把 MCP 与 A2A 定位为**配合使用的不同层**。 + 来源：[A2A v1.0 公告（明确对比两层）](https://a2a-protocol.org/latest/announcing-1.0/) +- **治理**：2025-12 Anthropic 把 MCP 捐给新成立的 **Agentic AI Foundation（AAIF，Linux Foundation 旗下）**，由 **Anthropic、Block、OpenAI** 共同发起，白金成员含 AWS、Bloomberg、Cloudflare、Google、Microsoft。 + 来源：[MCP 博客](https://blog.modelcontextprotocol.io/posts/2025-12-09-mcp-joins-agentic-ai-foundation/)、[Linux Foundation AAIF 公告](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) +- **官方 MCP Registry**（`registry.modelcontextprotocol.io`）：公共 MCP server 的官方元数据库，**仍处 preview**（非 GA，可能 reset）。`server.json`（reverse-DNS 唯一名、包位置/远程 URL、能力），命名空间用 **DNS/GitHub 验证**，暴露 REST + OpenAPI，供**下游聚合市集**消费（Smithery、PulseMCP…）。 + 来源：[MCP Registry About](https://modelcontextprotocol.io/registry/about)、[GitHub modelcontextprotocol/registry](https://github.com/modelcontextprotocol/registry)（⚠️ ~9.6k server 数来自三方追踪器） + +**→ 对我们**：MCP **互补不竞争**。(1) 概念边界要清：**agent（A2A）≠ 工具（MCP）**；我们路由的是 *task* 给 A2A agent，可另外*列出* MCP 工具。(2) MCP Registry 的「**上游不带观点 + 下游市集做增强（评分/策展/安全）**」架构值得照抄到我们的 agent catalog。 + +## 其它互操作努力（了解即可） + +| 协议 | 现状 | 与我们的关系 | +|---|---|---| +| **IBM/BeeAI ACP** | **已并入 A2A**（2025-09），BeeAI 留作参考实现 | 收敛信号——别投资独立 ACP。来源：[agentcommunicationprotocol.dev](https://agentcommunicationprotocol.dev/introduction/welcome) | +| **Cisco/AGNTCY Agent Connect Protocol** | `acp-spec` 仓库 **2026-04-11 归档**（只读） | 同上收敛信号（⚠️ 「并入 A2A」为推断）。来源：[agntcy/acp-spec](https://github.com/agntcy/acp-spec) | +| **AG-UI（CopilotKit）** | agent ↔ **前端 UI** 的事件流标准；AWS/Oracle/MS 已集成 | **正交**——若我们做人机流式 UI 可选采纳。来源：[AG-UI 文档](https://docs.ag-ui.com/introduction) | +| **OpenAI-compatible `/v1/chat/completions`** | **模型推理**的事实标准 lingua franca，80%+ 新 provider 支持 | **低摩擦入口**：提供 OpenAI 兼容 shim，开发者改一行 base URL 即可接入。注意 OpenAI 正推 **Responses API**，别锁死老接口。来源：[TokenMix 指南](https://tokenmix.ai/blog/openai-compatible-api) | +| **agents.json（Wildcard）** | v0.1.0，基于 OpenAPI 描述 API 工作流；小众早期 | **不是** agent 路由标准，别当标准用。来源：[wild-card-ai/agents-json](https://github.com/wild-card-ai/agents-json) | + +## 标准层对我们的 6 条启示 + +1. **以 A2A AgentCard 为唯一标准的 agent 描述符**——生态已收敛，捡现成的发现+调用+生命周期。 +2. **做 A2A client + curated registry，不发明新协议**——差异化在策展/搜索/信任，不在 wire format。 +3. **用 Signed Cards + 命名空间验证做市集信任**——回答「如何安全列出任意第三方 agent」。 +4. **把 MCP 当工具层列出，别和 agent 混为一谈**——可选消费 MCP Registry（仍 preview）。 +5. **提供 OpenAI 兼容 shim 作为低摩擦 on-ramp**——同时为 OpenAI 转向 Responses API 留余地。 +6. **填补命名/解析空白 = 护城河**——A2A 不解决跨域全局发现，市集「成为 registry」正是解这个题。 + 来源：[Solo.io: A2A 的发现/命名/解析缺失](https://www.solo.io/blog/agent-discovery-naming-and-resolution---the-missing-pieces-to-a2a) + +--- + +# Part B · 竞争格局 + +## 对比总表 + +| 玩家 | 类别 | 定位 | 变现 | 来源 | +|---|---|---|---|---| +| **OpenRouter** | LLM 网关（模板） | One API for any model | **推理零加价**；充值 **5.5%+$0.80**（卡）/5%（加密）；BYOK 前 100 万次/月免费后 **5%** | [datastudios.org](https://www.datastudios.org/post/openrouter-pricing-byok-routing-costs-and-cost-optimization-strategies-how-openrouter-actually-c)、[OpenRouter FAQ](https://openrouter.ai/docs/faq) | +| LiteLLM | LLM 网关（OSS） | 100+ LLM 统一代理 | OSS 免费 + 企业版 ~$250/mo | [GitHub](https://github.com/BerriAI/litellm/) | +| Portkey | LLM 网关 | 企业网关 + guardrails | 按日志/可观测分层收费 | [TrueFoundry](https://www.truefoundry.com/blog/portkey-pricing-guide) | +| Cloudflare AI Gateway | LLM 网关 | 边缘观测/缓存/路由 | 核心免费；统一计费 **5% 充值费**；token 零加价 | [Cloudflare 文档](https://developers.cloudflare.com/ai-gateway/reference/pricing/) | +| Vercel AI Gateway | LLM 网关 | 一个端点，零加价 | token 零加价；靠 add-on 附加费 | [Vercel 文档](https://vercel.com/docs/ai-gateway/pricing) | +| Helicone | 网关 + 可观测 | 一个 key 到 100+ 模型 | 零加价；可观测订阅（$79/$799） | [Helicone 文档](https://docs.helicone.ai/gateway/overview) | +| **Salesforce AgentExchange** | 企业市集 | Agentforce 的可信市集 | 无 agent 专属 take-rate（⚠️ 套用 AppExchange ~15%） | [Salesforce PR](https://www.salesforce.com/news/press-releases/2025/03/04/agentexchange-announcement/) | +| **Google Agentspace → Gemini Enterprise** | 企业市集 | Agent Gallery 发现面 | 经 Google Cloud Marketplace，免费/订阅 | [Google Cloud blog](https://cloud.google.com/blog/products/ai-machine-learning/partner-built-agents-available-in-gemini-enterprise) | +| **AWS Bedrock AgentCore** | agent 基础设施 + 市集 | 托管运行时/记忆/网关/注册表 | 消耗计费 + AWS Marketplace 卖 agent（2025-10） | [AWS What's New](https://aws.amazon.com/about-aws/whats-new/2025/10/aws-marketplace-pricing-ai-agents-tools) | +| **Microsoft Copilot Agent Store** | 企业市集 | Copilot「超级 app」内市集 | **~70% 分给开发者**；transactable SaaS / BYOL | [MS Learn](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/submit-agent-partner-center) | +| **OpenAI Apps in ChatGPT / App Directory** | 消费者 agent/app 市集 | ChatGPT 内 Apps SDK + 目录 | 开发者自定价 + **Agentic Commerce Protocol** 结账 | [OpenAI Apps SDK](https://developers.openai.com/apps-sdk/build/monetization) | +| Sierra | 企业 agent 平台（单厂商） | 结果导向 CX agent | **按结果计费**（~$2–5/解决） | [Sierra blog](https://sierra.ai/blog/outcome-based-pricing-for-ai-agents) | +| **agent.ai** | 独立 agent 市集 | 「agent 的集市」+ 职业网络 | **目前免费、无变现**（~23 万用户） | [Boston Globe](https://www.bostonglobe.com/2025/01/31/business/hubspot-dharmesh-shah-ai-artificial-intelligence-agents/) | +| **MuleRun** | 独立 agent 市集 | 「AI agent 数字劳力市集」 | **创作者拿 ~100%** | [AiThority](https://aithority.com/machine-learning/mulerun-launches-creator-studio-the-worlds-first-platform-built-for-ai-agent-monetization/) | +| **Replit Agent Market** | 独立 agent 市集 | 最像 agent app store | 直接售卖 / 订阅 / 消耗 | [DigitalApplied](https://www.digitalapplied.com/blog/ai-agent-marketplaces-2026-discovery-distribution) | +| a2aregistry.org / MCP registries | 开放注册表 | 列出活的 A2A/MCP 端点 | 非商业 / 社区 | [a2aregistry.org](https://a2aregistry.org/) | + +## 三类玩家的共性（关键洞察） + +1. **LLM 网关（直接类比）**：几乎全部「**零/近零加价**」，靠**别的面**变现——充值费（OpenRouter 5.5% / Cloudflare 5% / Requesty 5% markup）、add-on（Vercel）、可观测订阅（Helicone/Portkey）。**网关层在 LLM 领域已商品化、卷向免费。** → 启示：agent 领域定价**远未标准化**，被路由的「单位」是 agent 而非 token，差异化空间更大。 + +2. **企业 / 平台市集**：Salesforce / Google / AWS / Microsoft / ServiceNow 每家都在建**funnel 进自家栈**的市集——**单厂商、垂直整合、企业 gated、无跨厂商调用**。买家**无法用一个 API、一张账单**同时调用 Salesforce 的 agent、Google 的 agent 和某创业公司的 agent。 + +3. **独立 / 开放**：agent.ai（免费无变现）、MuleRun（创作者友好）、Replit（最像 app store）、A2A/MCP registry（只发现无计费）。共性：**面向消费者「运行 agent」的目的地（UI 优先），不是开发者基础设施（「用一个 API/SDK 以编程方式调用任意 agent，一张账单」）。** + +## 市场空白 = 我们的楔子（8 条战略要点） + +1. **OpenRouter 类比真的没人占**：企业市集是单厂商围墙，独立市集是消费者目的地，registry 只发现不计费——「**一个统一 API + SDK，跨厂商发现并调用任意 agent，一张账单**」是缺失的中间层。**主打开发者 API，而非可浏览的 storefront。** +2. **几乎照抄 OpenRouter 的钱模型**：零加价 + 充值费(~5%) + BYOK toll。对 agent 更稳——作者各自定价，我们**不必给 agent 加价**，只在结算抽一层薄费。**公开 take-rate**（别人都藏，透明即差异化）。 +3. **跨厂商路由 / fallback 是技术护城河**：agent 没有「同模型多 provider」的等价物——把 *task* 路由到最适合的 agent（价格/延迟/成功率/能力），失败 fallback，**按成功计费**。Sierra 的「按结果计费」说明市场已在用 outcome 思考。 +4. **站在 A2A + MCP 上，别造运行时**：做「**开放协议之上的商业层**」——统一 key、计量、账单、限流、可观测。低自研、无锁定、搭顺风车。 +5. **统一账单是最尖锐的痛点**：今天对接多 agent = N 合同/N 账单/N 鉴权。**「一个 key、一张账单、任意 agent」可被直接演示**——这正是 OpenRouter 赢过裸 provider key 的原因。营销主打**整合**，而非**目录大小**。 +6. **先赢开发者，别打企业采购的仗**：企业市集都 gated 在 partner program + 销售流程后面。精益打法靠 **self-serve + credits + BYOK + docs-first** 自底向上（OpenRouter/Helicone 的剧本）。 +7. **做中立瑞士**：结构性优势是**不卖一方 agent、不绑一朵云**——和 OpenRouter 对各模型厂的中立信任位一样。把**中立 + 可移植 + BYOK** 当成承重的品牌承诺。 +8. **刻意选开发者基础设施 beachhead**：消费者 storefront 赛道（MuleRun/Replit/agent.ai）正在变挤。去做**每个市集、每个 agent builder 调用其它 agent 时都要打的那个 API/SDK**——像 Stripe 坐在所有 storefront 底下。面更小、嵌入后更难替换，也最贴 slogan。 + +## ⚠️ 下注前要复核的点 + +- Salesforce / Google / AWS / ServiceNow 的 **agent 专属分成比例**均**未公开**，本文用各自现有市集框架代理，已标注。 +- OpenRouter 费率（5.5%/$0.80、BYOK 100 万免费后 5%）来自其 JS 渲染页，已用二手来源三方交叉确认；落地前再核当前数字。 +- GPT Store 创作者收入「$100–500/月封顶」来自二手 2026 指南，方向性参考。 diff --git a/docs/agent-marketplace/02-product-spec.md b/docs/agent-marketplace/02-product-spec.md new file mode 100644 index 000000000..047705fa6 --- /dev/null +++ b/docs/agent-marketplace/02-product-spec.md @@ -0,0 +1,119 @@ +# 02 · 产品方案 + +> 三层产品面：**Registry**（发现）/ **Gateway**（调用）/ **Console**（控制台与变现）。 +> 实现的技术细节见 [03-technical-architecture.md](03-technical-architecture.md)；数据落地见 [04-data-model.md](04-data-model.md)。 + +--- + +## A. Agent Registry & 市集（发现层） + +### A.1 Agent 实体 + +每个 agent 由一张 **AgentCard** 派生（A2A 标准，见 [01](01-landscape-and-standards.md)）： + +- 身份：`name`、`slug`、`description`、`publisher`、`homepage`、`logo` +- 端点：`endpointUrl`、支持协议（`A2A` / `OPENAI_COMPAT` / `MCP`）、`capabilities`（streaming / push）、安全 `schemes` +- 能力：`skills[]`（每个含 id/name/description/inputModes/outputModes/examples）—— **这是搜索与能力匹配的核心** +- 商业：定价模型（per-call / per-task / per-token / free）、单价、是否支持 BYOK +- 策展：category、tags、featured、status（审核状态）、评分/likes/调用量 + +### A.2 入驻方式（让供给侧零摩擦——冷启动关键） + +1. **提交 AgentCard URL**（首选）：填一个 `/.well-known/agent-card.json` 地址，我们抓取 + 解析 + 验证，自动建档。 +2. **表单手填**：没有标准卡片的 agent，手动录入端点与能力。 +3. **从注册表导入**：批量从 A2A registry（如 a2aregistry.org）/ MCP Registry 拉取做种子。 + +### A.3 验证与信任（回答「如何安全列出第三方 agent」） + +- **Signed AgentCard 校验**（A2A v1.0）：验证卡片确由域名所有者签发。 +- **命名空间所有权验证**：DNS TXT / GitHub 挑战（照抄 MCP Registry 模式）。 +- **人工审核流**：**直接复用现有 `SkillStatus`（PENDING / APPROVED / REJECTED）+ admin 后台 + `reviewNote`**——已经建好的轮子。 +- **健康检查**：定期 ping 端点 + 拉卡片，标记失活/过时 agent（复用 `ghCheckedAt/ghStatus` 的模式）。 + +### A.4 浏览 UX（最大化复用现有 skills 市集） + +| 现有组件/页面 | 复用为 | +|---|---| +| `/skills` 列表 + filter sidebar | `/agents` agent 列表（分类 / 能力 / 协议 / 定价 过滤） | +| `SkillCard` | `AgentCard`（展示 publisher、能力标签、定价、评分） | +| `/skills/[slug]` 详情 | `/agents/[slug]`：AgentCard 全貌 + skills 列表 + 定价 + **调用示例（curl / SDK）** + 状态/SLA | +| `HomeSearch` / `/api/skills/search` | agent 搜索（按 name/description/skills） | +| `/trending`、likes、ratings、bookmarks | agent 的 trending / 收藏 / 评分（**现有孤立表 `Rating`/`Bookmark` 正好激活**） | + +### A.5 Agent-readable 发现（吃自己的狗粮） + +- 升级现有 `/api/agent`：从「返回 skill 目录」改为「返回 **agent 目录**」（md / json），供其它 agent 自助发现我们市集里的 agent。 +- 暴露 **A2A 风格的 registry API**：让 TakoAPI 自身成为一个可被查询的 curated registry（填补 [01](01-landscape-and-standards.md) 指出的「全局发现/解析」空白）。 + +--- + +## B. Unified Gateway API（调用层） + +> **核心卖点**：一个 base URL + 一个 API key，调用任意已注册 agent。 + +### B.1 三个协议面 + +| 面 | 形态 | 用途 | +|---|---|---| +| **A2A 透传**（主） | `POST {gw}/v1/agents/{slug}/message` → 我们按 AgentCard 路由到上游 A2A agent（JSON-RPC `message/send`，SSE 流，task 轮询/webhook） | 调用「真正的 agent」 | +| **OpenAI 兼容 shim**（on-ramp） | `POST {gw}/v1/chat/completions`，`model` = agent slug | 让现有 OpenAI SDK 改一行 base URL 即可接入，**最低摩擦获客** | +| **MCP**（可选/后置） | 暴露/聚合 MCP 工具 | 给 agent 提供工具，非 v1 重点 | + +### B.2 路由与弹性 + +- 同步调用 + **SSE 流式**；超时（~p95）、有界重试 + backoff+jitter（仅幂等）、**断路器**（剔除失活上游）。 +- **跨 agent fallback**：上游报错/超时时切到备选 agent（护城河功能，进阶）。 +- **智能路由**（进阶）：按价格 / 延迟 / 成功率 / 能力选 agent。 +- **异步长任务**：超过 Cloud Run 60 分钟硬顶的任务，返回 `taskId` + 轮询/webhook（见 [03](03-technical-architecture.md)）。 + +### B.3 鉴权 + +- API key（**存哈希 + 前缀**，创建时只显示一次），per-key scope / quota / 速率。 +- 替代现有 `User.apiKey` 单字段（升级为独立 `ApiKey` 表，见 [04](04-data-model.md)）。 + +--- + +## C. Developer Console & Publisher 体验（控制台层） + +### C.1 Developer（需求侧） + +注册 → 拿 API key → 充值 credits → 调用 → 看**用量 / 账单 / 调用日志** → 管理多个 key。 +复用现有 `/profile` 扩展。 + +### C.2 Publisher（供给侧） + +提交 agent → 验证 → 设定**定价 / 分成** → 看**调用量 / 收入** → **结算（payout）**。 +复用现有 `/profile`「My Submissions」+ admin 审核界面。 + +### C.3 Admin + +复用现有 `/admin/*`（skills/users/logs/stats）扩展为 agent 审核、publisher 管理、用量与收入看板。 + +--- + +## D. Billing & Credits（商业层） + +> 详见 [03 §计费与计量](03-technical-architecture.md)。产品侧规则： + +- **预付 credits**（Stripe 充值），调用按量扣减。 +- **充值费 ~5%**（OpenRouter 式，主要收入线）。 +- 计量单位：**per-call / per-task**（不透明第三方 agent）或 **per-token**（模型类 agent）。 +- **BYOK toll**：用户带自己的上游 key 时收薄费（进阶）。 +- **给 publisher 分成**：起谈 **~80/20（偏向创作者）**（对标 Perplexity Comet Plus / Microsoft 70%，⚠️ 无 agent 专属基准）。 +- **透明定价**：take-rate 公开。 + +--- + +## E. SDK 与自有 skill + +- 轻量 **TS / Python SDK**：3 行接入 gateway（`new Tako({apiKey}).agents.call(slug, input)`）。 +- 把现有 `takoapi_skill/`（Claude Code skill）从「搜索安装 skill」**改造为「发现并调用 agent」**——吃自己的狗粮，也是一个分发渠道。 + +--- + +## F. 产品边界（先不做） + +- ❌ 托管运行第三方 agent（[00](00-vision-and-positioning.md) 选项 C）。 +- ❌ 复杂多 metric 定价、企业 postpaid 发票（先 prepaid credits）。 +- ❌ 自研支付协议；agentic payments（x402 / AP2 / ACP）**仅观察**，非 v1 依赖。 +- ❌ 又一个「消费者浏览 agent」的 storefront——主线是开发者基础设施。 diff --git a/docs/agent-marketplace/03-technical-architecture.md b/docs/agent-marketplace/03-technical-architecture.md new file mode 100644 index 000000000..883586ecb --- /dev/null +++ b/docs/agent-marketplace/03-technical-architecture.md @@ -0,0 +1,117 @@ +# 03 · 技术架构 + +> 落地基线：复用现有 **Next.js 16 + Prisma + Cloud Run + Cloud SQL**。来源均附链接。 +> ⚠️ **实现前必读** `node_modules/next/dist/docs/`（本仓库 Next.js 16 有 breaking changes）。 + +--- + +## 1. 系统架构（文字图） + +``` + Client / SDK / OpenAI-SDK + │ (API key) + ▼ +┌──────────────────────────────────────────────┐ +│ Gateway（Cloud Run, Next.js route handlers） │ +│ ┌──────────┬───────────┬──────────┬────────┐ │ +│ │ Auth/Key │ RateLimit │ Router │ Meter │ │ +│ │ (hash) │ (Redis) │ +resil. │(log→agg)│ │ +│ └──────────┴───────────┴──────────┴────────┘ │ +│ │ 协议适配：A2A client / OpenAI shim / MCP │ +└───────┼──────────────────────────────────────┘ + ▼ (JSON-RPC / SSE / HTTP) ┌─ 旁路 ─────────────────┐ + 上游第三方 agents │ Postgres(经 PgBouncer) │ + (A2A servers / OpenAI-compat / MCP) │ Upstash Redis │ + │ Stripe（credits/账单） │ + │ 可观测(OTel/Langfuse) │ + └────────────────────────┘ +``` + +## 2. 协议适配层 + +- **A2A client**：解析 AgentCard（`/.well-known/agent-card.json`，兼容旧 `agent.json`）、发 JSON-RPC `message/send`、消费 SSE、按 TaskState 跟踪、处理 push webhook。 +- **OpenAI 兼容适配**：把 `/v1/chat/completions` 请求映射到选定 agent，再把 agent 输出包成 OpenAI 响应 shape。**最低摩擦入口**。 +- **MCP client**（后置）：聚合/转发 MCP 工具。 + +## 3. 鉴权与 API Key + +- **存哈希不存明文**：创建时**只显示一次**完整 key，库里存 **SHA-256 哈希 + 可见前缀**（前缀用于识别/查找）。每请求用快哈希校验（bcrypt/argon2 太慢，仅用于用户密码）。 + ⚠️ 哈希算法选择是行业惯例，非单一权威来源。网关鉴权模式参考：[DEV: Production-Ready API Gateway](https://dev.to/tim_derzhavets/building-a-production-ready-api-gateway-from-token-bucket-rate-limiting-to-jwt-validation-27l4) +- per-key：tenant scope、quota、速率、`lastUsedAt`。 +- **升级路径**：现有 `User.apiKey` 单字段 → 独立 `ApiKey` 表（见 [04](04-data-model.md)）。 + +## 4. 限流与配额 + +- **算法 token bucket**，网关集中执行。来源：[Redis rate-limiter](https://redis.io/docs/latest/develop/use-cases/rate-limiter/) +- **必须用 Redis（Upstash），不能用进程内内存**：Cloud Run 默认 autoscale 到 **多实例**，进程内计数会被绕过（打不同实例）。用 Redis 集中状态 + **Lua 脚本原子**「检查-补充-消费」，key 形如 `rl:{tenantId}:{endpoint}:{rule}` + **TTL**（空闲租户自动释放）。 + 来源：[Multi-Tenant Rate Limiting（2026-02）](https://medium.com/@khalilsayed/system-design-multi-tenant-rate-limiting-service-32c63ade5ec7) + +## 5. 计量（计费的写路径） + +- **log → aggregate** 范式：每请求 append **一条 usage event**（便宜的写），**异步聚合**用于计费。 +- 选型：**OpenMeter**（开源 Apache-2.0、自托管、原生 LLM-token 计量、内置 Stripe 开票）或 Stripe-native usage billing（Stripe 现把新用量计费导向 **Metronome**，旧 Billing Meters 进入维护）。 + 来源：[openmeter.io](https://openmeter.io/)、[Stripe recording-usage](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage) +- **演进现有 `RequestLog`**：它已经在记 path/method/status/duration——是 usage event 的雏形，扩字段即可（见 [04](04-data-model.md)）。 + +## 6. 计费 + +- **Stripe + 预付 credits + 充值费**（OpenRouter 验证过的模型，见 [01](01-landscape-and-standards.md)）。先**不做** postpaid 发票。 +- 余额账本：充值 → 调用扣减 → publisher 分成 → 结算（数据模型见 [04](04-data-model.md)）。 + +## 7. 弹性（对付不稳定的上游 agent） + +- **断路器**（最重要）：按错误率/慢响应跳闸，自动剔除失活上游，冷却后恢复。 +- **有界重试 + 指数退避 + jitter**（仅幂等操作）。 +- **超时**调到略高于 p95。 +- **fallback 链**：跨 provider/agent 兜底。 + 来源：[Portkey: retries/fallbacks/circuit breakers](https://portkey.ai/blog/retries-fallbacks-and-circuit-breakers-in-llm-apps/) + +## 8. 流式（SSE） + +- Cloud Run **支持 HTTP 流式 / SSE / gRPC server-streaming**。来源：[Cloud Run streaming](https://cloud.google.com/blog/products/serverless/cloud-run-now-supports-http-grpc-server-streaming) +- ⚠️ **坑**：有报告称 **Global HTTPS LB + serverless NEG** 后面 SSE 被节流，直连 Cloud Run URL 正常——流式代理要评估这一点。来源：[Google Dev 论坛](https://discuss.google.dev/t/cloud-run-serverless-neg-behind-global-https-lb-sse-streaming-connections-throttled-vs-direct-cloud-run-url/361659) + +## 9. GCP 落地的两个硬约束（必须 day-1 规划） + +### 9.1 Cloud Run 请求超时 60 分钟硬顶 + +- 默认 **5 分钟**，最大 **60 分钟（3600s）**。超时返回 **504**，但容器**不被杀**。 + 来源：[Cloud Run request-timeout](https://docs.cloud.google.com/run/docs/configuring/request-timeout) +- **含义**：超过 ~60 分钟的长 agent 任务**不能是单个同步请求** → 走 **async job + `taskId` 轮询/webhook**（正好对应 A2A 的 push notification）。 + +### 9.2 Cloud SQL 连接数（#1 扩展性翻车点） + +- Cloud Run 多实例各开 DB 连接；Postgres 连接数受实例规格限制，**每连接 ~5–10MB RAM**。 +- **必须上连接池**：**PgBouncer** 或 **Cloud SQL Auth Proxy** 夹在 Cloud Run 与 Cloud SQL 之间。 + 来源：[PgBouncer for Cloud SQL（2026-02）](https://oneuptime.com/blog/post/2026-02-17-how-to-set-up-pgbouncer-connection-pooling-for-cloud-sql-postgresql/view)、[Cloud SQL manage-connections](https://docs.cloud.google.com/sql/docs/postgres/manage-connections) +- ⚠️ **现状**：生产是 **db-f1-micro（1 shared CPU / 0.6GB）**（见 [docs/00-infrastructure.md](../00-infrastructure.md)）——做网关**必须升配** + 接 PgBouncer。 + +## 10. 可观测 + +- 采纳 **OpenTelemetry GenAI semantic conventions**（仍 experimental，但已是方向）——统一 LLM/agent span、token、cost。 +- 部署：自托管 **Langfuse**（OTel-native）或用 **Helicone** 式代理日志（cost/latency/token）。 + 来源：[Langfuse OTel](https://langfuse.com/integrations/native/opentelemetry) + +## 11. 信任与安全（OWASP LLM Top 10，2025） + +- **Prompt Injection 是 #1**；市集相关新增项：Excessive Agency、System Prompt Leakage、Unbounded Consumption。 +- 控制：**把上游 agent 响应当作不可信**（二阶注入）；least-privilege 工具权限 + 命令 allowlist + 敏感模式（`*.env`/`*.key`/`*.pem`）拦截；短时令牌 + 审批绑定具体参数；高危操作 **human-in-the-loop**；**日志默认脱敏**（redact secrets/PII）；租户隔离。 + 来源：[OWASP AI Agent Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html)、[OWASP LLM01](https://genai.owasp.org/llmrisk/llm01-prompt-injection/) + +## 12. 与现有架构的衔接 + +- **网关用 Next.js 16 route handlers 起步够用**（复用 `src/lib/api.ts` 错误约定、`ratelimit.ts`、`pagination.ts`、`requestLog.ts`）。 +- **规模化再考虑拆独立服务**：高并发流式代理 + 长连接对 serverless 有压力；若流量起来，把 gateway 数据面拆成独立 Cloud Run 服务（甚至非 Next.js）。 +- CI/CD 复用现有 `cloudbuild.yaml` → Cloud Build → Cloud Run；在 Dockerfile 启动前加 `prisma migrate deploy`。 + +## 13. 「先建 / 后置」一览（精益团队） + +| 先建（v1） | 后置（v2+ / 观察） | +|---|---| +| API key（哈希）+ 鉴权 | postpaid / 企业发票、复杂多 metric 定价（Orb/Metronome） | +| A2A 透传代理（同步 + SSE） | BYOK toll | +| Redis 限流 + log→agg 计量 | 智能路由（price/latency/success） | +| OpenAI 兼容 shim | 异步长任务（>60min, task+webhook） | +| Stripe + prepaid credits + 充值费 | MCP 工具聚合 | +| PgBouncer + 升配 Cloud SQL + Upstash | agentic payments（x402/AP2/ACP）——**仅观察** | +| 日志脱敏 + 基础 OTel/Langfuse | 沙箱化运行不可信 agent、内容审核、publisher 强验证 | diff --git a/docs/agent-marketplace/04-data-model.md b/docs/agent-marketplace/04-data-model.md new file mode 100644 index 000000000..b606963e5 --- /dev/null +++ b/docs/agent-marketplace/04-data-model.md @@ -0,0 +1,185 @@ +# 04 · 数据模型演进 + +> 从「Skill 中心」演进到「Agent 中心」。原则：**新增 `Agent` 等模型，不强行复用 `Skill`**（语义不同）；现有表按 2026-04-22「未搞清用途不删」决策**保留**。 +> 现状 schema 见 `prisma/schema.prisma`；迁移已 baseline `0_init`。下面是**草案**，落地前据 [02](02-product-spec.md)/[03](03-technical-architecture.md) 细化并跑 `prisma migrate dev`。 + +--- + +## 1. 复用 vs 新增 + +| 现有模型 | 处置 | +|---|---| +| `User` | ✅ 复用，加 `role`（已含 user/admin，扩 `publisher`）、关联 credits/keys | +| `Account` / `Session` / `VerificationToken` | ✅ 原样（NextAuth） | +| `Category` / `Tag` / `SkillTag` | ✅ 复用给 agent 分类/标签（`SkillTag` 旁加 `AgentTag`） | +| `Like` / `Bookmark` / `Rating` | ✅ **激活孤立表**给 agent（加 `agentId`，或新建平行表） | +| `RequestLog` | ✅ **演进为 usage 计量雏形**（见 §3） | +| `SkillStatus`（PENDING/APPROVED/REJECTED）+ admin 审核 + `reviewNote` | ✅ **直接复用**给 agent 审核流 | +| `Skill` + 5,146 条数据 + `AgentType` 枚举 + `src/lib/agents.ts` | 🟡 **保留为 legacy 内容品类**（coding-agent skills），**不**改造成 invokable agent | +| `AdCampaign` / `KolContact` / `KolOutreach` / `BlogPost` / `Subscriber` / `AuthorFollow` | ⬜ 不动（孤立表，保留） | + +> ⚠️ 再次强调语义：现有 `Skill.agentType` 描述「装 skill 的 coding agent」；新 `Agent` 是「可调用的服务」。**两者并存，互不覆盖。** + +## 2. 新增模型（草案） + +```prisma +// ── 发现层 ────────────────────────────────────────────── +enum AgentProtocol { A2A OPENAI_COMPAT MCP } +enum AgentStatus { PENDING APPROVED REJECTED DISABLED } // 复用 SkillStatus 思路 +enum PricingModel { FREE PER_CALL PER_TASK PER_TOKEN } + +model Agent { + id String @id @default(cuid()) + slug String @unique + name String + description String + publisherId String // → User(role=publisher) + categoryId String? + status AgentStatus @default(PENDING) + reviewNote String? + + // —— AgentCard 派生（A2A）—— + cardUrl String? // /.well-known/agent-card.json + endpointUrl String + protocols AgentProtocol[] + streaming Boolean @default(false) + pushNotify Boolean @default(false) + securitySchemes Json? // 上游鉴权方式 + cardSignatureVerified Boolean @default(false) // A2A v1.0 signed card + namespaceVerified Boolean @default(false) // DNS/GitHub 所有权 + cardFetchedAt DateTime? + healthStatus String? // ok / degraded / down + healthCheckedAt DateTime? + + // —— 商业 —— + pricingModel PricingModel @default(FREE) + unitPriceUsd Decimal? @db.Decimal(12, 6) // 每 call/task/1k token 的价 + byokSupported Boolean @default(false) + revShareBps Int? // 给 publisher 的分成(基点)，默认平台策略 + + // —— 策展/统计 —— + featured Boolean @default(false) + likesCount Int @default(0) + callsCount Int @default(0) + avgRating Float @default(0) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + publisher User @relation(fields: [publisherId], references: [id]) + category Category? @relation(fields: [categoryId], references: [id]) + skills AgentSkillDef[] + invocations Invocation[] + + @@index([status, categoryId]) + @@index([featured, callsCount(sort: Desc)]) + @@index([publisherId]) +} + +model AgentSkillDef { // A2A skill —— 发现/搜索/能力匹配 + id String @id @default(cuid()) + agentId String + skillKey String // AgentCard skill.id + name String + description String? + inputModes String[] + outputModes String[] + examples String[] + agent Agent @relation(fields: [agentId], references: [id], onDelete: Cascade) + @@index([agentId]) +} + +// ── 鉴权 ──────────────────────────────────────────────── +model ApiKey { // 替代 User.apiKey 单字段 + id String @id @default(cuid()) + userId String + name String? + hashedKey String @unique // SHA-256，不存明文 + prefix String // 识别用，如 "tako_live_AbC…" + scopes String[] + rateLimit Int? + monthlyQuota Int? + lastUsedAt DateTime? + revokedAt DateTime? + createdAt DateTime @default(now()) + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + @@index([userId]) + @@index([prefix]) +} + +// ── 计量 / 可观测（演进 RequestLog）──────────────────────── +model Invocation { // 每次 agent 调用一条 + id String @id @default(cuid()) + apiKeyId String? + userId String? + agentId String + protocol AgentProtocol + status Int // HTTP/任务状态 + taskState String? // A2A TaskState + latencyMs Int? + unitsBilled Decimal? @db.Decimal(14, 6) // calls/tasks/tokens + costUsd Decimal? @db.Decimal(14, 6) // 上游成本 + billedUsd Decimal? @db.Decimal(14, 6) // 向用户计费 + errorCode String? + createdAt DateTime @default(now()) + agent Agent @relation(fields: [agentId], references: [id]) + @@index([agentId, createdAt]) + @@index([apiKeyId, createdAt]) + @@index([userId, createdAt]) +} + +// ── 商业 / 账本 ───────────────────────────────────────── +enum LedgerType { TOPUP TOPUP_FEE DEBIT PAYOUT REFUND ADJUST } + +model CreditBalance { + userId String @id + balanceUsd Decimal @default(0) @db.Decimal(14, 6) + updatedAt DateTime @updatedAt + user User @relation(fields: [userId], references: [id], onDelete: Cascade) +} + +model LedgerEntry { // 不可变流水 + id String @id @default(cuid()) + userId String + type LedgerType + amountUsd Decimal @db.Decimal(14, 6) // +充值/-扣费 + invocationId String? // DEBIT 关联调用 + stripeRef String? // 充值/退款 + note String? + createdAt DateTime @default(now()) + @@index([userId, createdAt]) +} + +model Payout { // 给 publisher 结算 + id String @id @default(cuid()) + publisherId String + amountUsd Decimal @db.Decimal(14, 6) + periodStart DateTime + periodEnd DateTime + status String @default("pending") // pending/paid/failed + stripeRef String? + createdAt DateTime @default(now()) + @@index([publisherId, status]) +} +``` + +> 说明：`Decimal` 用于钱与用量（避免浮点误差）；`String[]`/`Json` 是 Postgres 原生支持。`Invocation` 与 `LedgerEntry` 是高写入表，注意索引与分区/归档（量大后考虑按月分区或冷热分离）。 + +## 3. `RequestLog` → `Invocation` 的关系 + +- `RequestLog`（现有，记所有 HTTP 请求）**保留**做通用请求日志。 +- `Invocation`（新）专记**计费相关的 agent 调用**——是 `RequestLog` 的「商业子集」，字段更丰富（成本/计费/taskState）。 +- 计量写路径（[03 §5](03-technical-architecture.md)）：网关每次调用 append 一条 `Invocation`（便宜），**异步聚合**到 `LedgerEntry`（DEBIT）+ 扣 `CreditBalance`。 + +## 4. 迁移策略 + +1. 沿用现有 Prisma 迁移流（已 baseline `0_init`）：每次 `prisma migrate dev --name ` 生成文件入库，生产 `prisma migrate deploy`（[docs/01 §迁移策略](../01-architecture-review.md)）。 +2. **分阶段加表**，对齐 [05-roadmap.md](05-roadmap.md)：Phase 1 加 `Agent`/`AgentSkillDef`/`AgentTag`；Phase 2 加 `ApiKey`/`Invocation`；Phase 3 加 `CreditBalance`/`LedgerEntry`；Phase 4 加 `Payout` + publisher 字段。 +3. **基础设施前置**：加 `Invocation` 等高写表前，**先升配 Cloud SQL + 接 PgBouncer**（[03 §9.2](03-technical-architecture.md)）——当前 db-f1-micro 扛不住。 +4. **零破坏**：新表与现有 `Skill` 业务无外键耦合，可安全并存上线。`User.apiKey` 单字段在 `ApiKey` 表上线并迁移后再废弃。 + +## 5. 索引要点 + +- `Agent`：`(status, categoryId)`、`(featured, callsCount desc)`、`(publisherId)`。 +- `Invocation`：`(agentId, createdAt)`、`(apiKeyId, createdAt)`、`(userId, createdAt)`——计费聚合与看板的高频查询。 +- `LedgerEntry`：`(userId, createdAt)`。 +- `ApiKey`：`(prefix)` 用于快速查找校验。 diff --git a/docs/agent-marketplace/05-roadmap.md b/docs/agent-marketplace/05-roadmap.md new file mode 100644 index 000000000..be237f7ee --- /dev/null +++ b/docs/agent-marketplace/05-roadmap.md @@ -0,0 +1,95 @@ +# 05 · 路线图 + +> 策略：**registry-first, gateway-fast-follow**（见 [00 §7](00-vision-and-positioning.md)）。 +> 沿用现有约定：**每个 Phase 分子阶段，完成后停下来等用户验收，不一次性交付**。 +> ⚠️ 每阶段动代码前必读 `node_modules/next/dist/docs/`；schema 变更走 `prisma migrate`。 + +--- + +## Phase 0 · 决策与对齐（当前） + +- **产出**：本 `docs/agent-marketplace/` 设计轨道 + 用户对 [06-open-questions.md](06-open-questions.md) 的拍板。 +- **验收**：战略形态（A/B/C）、变现模型、skills 去留、协议范围、品牌 已确认。 +- 🚦 **未确认前不进入 Phase 1。** + +--- + +## Phase 1 · Registry MVP（发现层，冷启动） + +> ✅ **已完成并本地验证（2026-06-13）**。三个测试 agent 走通「提交→审核→上架→发现」全链路；首页改版落地 slogan。生产应用迁移 `003` + 升配数据库待 Phase 2 前置。 + +把 agent 供给做厚、发现做好——**无需先建重型网关就能有内容和流量**。 + +| 子阶段 | 内容 | +|---|---| +| 1A | 数据模型：`Agent` / `AgentSkillDef` / `AgentTag`（[04](04-data-model.md)）+ 迁移 | +| 1B | 入驻：提交 AgentCard URL → 抓取/解析/验证；表单手填；admin 审核（复用 `SkillStatus` 流） | +| 1C | 市集 UI：`/agents` 列表 + 过滤、`/agents/[slug]` 详情（复用 skills UX）、搜索 | +| 1D | 发现 API：升级 `/api/agent` 返回 agent 目录；暴露 registry API；从 a2aregistry/MCP 导入种子 | + +- **验收**：≥ N 个**通过验证**的 agent 可被浏览/搜索/查看详情；`/api/agent` 返回 agent 目录。 +- **暂不**：任何调用/计费。 + +--- + +## Phase 2 · Gateway MVP（调用层） + +| 子阶段 | 内容 | +|---|---| +| 2A | 基础设施前置：**升配 Cloud SQL + PgBouncer + Upstash Redis**（[03 §9](03-technical-architecture.md)） | +| 2B | `ApiKey` 表（哈希）+ 鉴权中间件（替代 `User.apiKey`） | +| 2C | **A2A 透传代理**（单 agent，同步 + SSE）+ 超时/重试/断路器 | +| 2D | 限流（Redis）+ 用量计量（`Invocation`，log→agg） | +| 2E | **OpenAI 兼容 shim** `/v1/chat/completions` | +| 2F | 基础可观测（OTel/Langfuse）+ 日志脱敏 | + +- **验收**：用一个 API key，经网关**成功调用一个已注册 agent**（含流式），且调用被**正确计量**进 `Invocation`。 +- **暂不**：真实扣费。 + +--- + +## Phase 3 · Commercial 层（变现闭环） + +| 子阶段 | 内容 | +|---|---| +| 3A | `CreditBalance` / `LedgerEntry` + Stripe 充值 + **充值费** | +| 3B | 调用按量扣减余额（DEBIT）；余额不足拦截 | +| 3C | Developer Console：用量 / 账单 / 调用日志 / 多 key 管理（扩 `/profile`） | + +- **验收**：**充值 → 调用 → 扣费**闭环跑通，账本与余额一致。 + +--- + +## Phase 4 · 双边市集（publisher 变现） + +| 子阶段 | 内容 | +|---|---| +| 4A | Publisher onboarding + 命名空间验证 + 定价/分成设置 | +| 4B | `Payout` 结算 + publisher 收入看板 | +| 4C | 评分 / 排行 / trending（激活 `Rating`/`Like`/`Bookmark`） | + +- **验收**：第三方 publisher 自助上架 agent，产生调用并**获得分成结算**。 + +--- + +## Phase 5+ · 护城河与进阶（按需） + +- 智能路由（price/latency/success/capability）+ **跨 agent fallback** +- **BYOK toll** +- 异步长任务（`taskId` + webhook，绕开 Cloud Run 60min） +- MCP 工具聚合 +- 企业能力（postpaid、SSO、SLA） +- **观察项**：agentic payments（x402/AP2/ACP）——非依赖 + +--- + +## 风险与回滚 + +| 风险 | 缓解 | +|---|---| +| 冷启动两难（无 agent 则无用户，反之亦然） | registry-first 先单边做厚供给；自己/合作伙伴种子 agent；从 A2A/MCP registry 导入 | +| 基础设施不足（db-f1-micro） | Phase 2A 前置升配 + PgBouncer，**不达标不上调用层** | +| 第三方 agent 不可信 / 注入 | [03 §11](03-technical-architecture.md) 安全控制；上游响应当作 hostile；高危 human-in-loop | +| 合规/license | 审核流卡关；展示 license；数据/日志策略公开 | +| 破坏现有 skills 业务 | 新表与 `Skill` 无外键耦合，**并存上线**；每阶段独立迁移 + commit，可回滚 | +| Next.js 16 breaking changes | 每阶段实现前读 `node_modules/next/dist/docs/`（`AGENTS.md` 硬性要求） | diff --git a/docs/agent-marketplace/06-open-questions.md b/docs/agent-marketplace/06-open-questions.md new file mode 100644 index 000000000..940eac359 --- /dev/null +++ b/docs/agent-marketplace/06-open-questions.md @@ -0,0 +1,107 @@ +# 06 · 待决策清单 + +> 进入 Phase 1 实现前，需要用户拍板。每条附**推荐**与**影响**。 + +## ✅ 决策结果（2026-06-13） + +用户答复「全部按照推荐进行」——**D1–D8 全部采纳本文推荐**（见文末决策矩阵）。Phase 0 关闭，进入 [Phase 1](05-roadmap.md)。 + +--- + +## D1 · 战略形态 + +我们做哪种？（详见 [00 §7](00-vision-and-positioning.md)） + +- **A. Proxy Gateway**——流量过我们的网关，计量/计费/路由。 +- **B. Directory + Connect**——只发现 + 标准化连接，调用直连。 +- **C. Agent Hosting**——我们托管运行 agent。 + +**推荐**：**A 为终局，registry-first 冷启动**（先 B 的发现层，再 fast-follow A 的调用层）。 +**影响**：决定整个架构与护城河；选 B 则砍掉网关/计费大部分工作，但护城河与变现都弱。 + +--- + +## D2 · 现有 skills 业务去留 + +5,146 条 skill + 30 分类怎么办？ + +- 全部转为 agent / **并存为子品类** / 弃用归档。 + +**推荐**：**并存**——skills 作为「coding-agent skills」子品类保留（符合 2026-04-22「不删」决策），新主线是 invokable agents。 +**影响**：决定首页信息架构与导航；并存最省事且不丢现有 SEO/内容。 + +--- + +## D3 · 变现模型 + +- **OpenRouter 式**（推理/调用零加价 + 充值费 ~5% + BYOK toll + publisher 分成） +- 成本加价（cost × markup） +- 订阅制 + +**推荐**：**OpenRouter 式**（[01](01-landscape-and-standards.md) 验证过、信任友好、透明）。 +**影响**：决定账本/计费设计与品牌定价叙事。 + +--- + +## D4 · 目标用户优先级 + +- **开发者优先**（API/SDK，self-serve） +- 消费者优先（浏览/运行 agent 的 storefront） + +**推荐**：**开发者优先**——做基础设施（Stripe-under-storefronts），避开变挤的消费者赛道。 +**影响**：决定首屏、文档、SDK 投入与 GTM。 + +--- + +## D5 · v1 协议范围 + +- 只 A2A / **A2A + OpenAI 兼容 shim** / 再加 MCP + +**推荐**：**A2A（主）+ OpenAI 兼容 shim（on-ramp）**；MCP 后置。 +**影响**：决定协议适配层工作量；shim 是低摩擦获客的关键。 + +--- + +## D6 · 品牌与文案 + +- 保留 **TakoAPI** 名（章鱼隐喻契合 one-API-many-agents）？ +- Slogan「One API to access all agents」落地到首页/README/SKILL.md？ +- 是否需要首页改版方案？ + +**推荐**：**保留 TakoAPI**，slogan 全站落地，首页以 agent 为英雄（skills 降为子品类入口）。 +**影响**：决定品牌迁移与营销物料。 + +--- + +## D7 · 基础设施预算 + +- Cloud SQL 升配（脱离 db-f1-micro）、Upstash Redis、是否拆独立 gateway 服务。 + +**推荐**：Phase 2A 前置升配 + PgBouncer + Upstash；网关先用 Next.js route handlers，规模化再拆。 +**影响**：决定月度成本与 Phase 2 能否启动（[03 §9](03-technical-architecture.md) 是硬约束）。 + +--- + +## D8 · 合规与信任标准 + +- 第三方 agent 审核门槛（自动 + 人工到什么程度）？ +- 数据/日志策略（是否存 prompt/输出、保留期、脱敏默认）？ +- license 与内容合规展示？ + +**推荐**：人工审核 + Signed Card/命名空间验证；**日志默认脱敏、opt-in 存储**；详情页展示 license 与数据策略。 +**影响**：决定信任叙事与法务暴露面；[03 §11](03-technical-architecture.md) 给了控制清单。 + +--- + +## 决策矩阵（一页速览） + +| # | 问题 | 推荐 | +|---|---|---| +| D1 | 战略形态 | A 终局 + registry-first | +| D2 | skills 去留 | 并存为子品类 | +| D3 | 变现 | OpenRouter 式 | +| D4 | 用户优先级 | 开发者优先 | +| D5 | v1 协议 | A2A + OpenAI shim | +| D6 | 品牌 | 保留 TakoAPI，slogan 全站 | +| D7 | 基础设施 | 升配 + PgBouncer + Redis，先不拆服务 | +| D8 | 合规信任 | 人工审核 + 验证 + 默认脱敏 | diff --git a/docs/agent-marketplace/README.md b/docs/agent-marketplace/README.md new file mode 100644 index 000000000..374775b43 --- /dev/null +++ b/docs/agent-marketplace/README.md @@ -0,0 +1,47 @@ +# TakoAPI 转型设计：One API to access all agents + +> 设计文档轨道（**仅设计，未动手实现**）。 +> 目标：把 TakoAPI 从「OpenClaw Skills Marketplace」升级为「**agent 市集 + 统一调用 API**」。 +> Slogan：**One API to access all agents**。 +> 起草：2026-06-13。 + +--- + +## 一句话论点 + +把 OpenRouter 对 LLM 做的事，对 **agent** 再做一遍：用**一个 API key、一张账单**，发现并调用任意第三方 agent。站在已收敛的开放标准（**A2A** + **MCP**）之上，做它们刻意不做的那一层——**统一鉴权、计费、路由、可观测**。 + +调研结论：这个「OpenRouter for agents」的生态位在 2026 年中**仍然空着**（详见 [01-landscape-and-standards.md](01-landscape-and-standards.md)）。 + +--- + +## 文档索引 + +| # | 文档 | 内容 | +|---|---|---| +| 00 | [愿景与定位](00-vision-and-positioning.md) | 为什么转、转成什么、目标用户、战略选项与推荐、与现有 skills 业务的关系 | +| 01 | [格局与标准调研](01-landscape-and-standards.md) | A2A / MCP 等开放标准 + 竞争格局 + 市场空白（**带来源链接**） | +| 02 | [产品方案](02-product-spec.md) | 三层产品面：Registry（发现）/ Gateway（调用）/ Console（控制台与变现） | +| 03 | [技术架构](03-technical-architecture.md) | 网关架构、协议适配、鉴权/限流/计量、GCP 落地与坑、可观测、信任安全 | +| 04 | [数据模型演进](04-data-model.md) | 从 Skill 中心到 Agent 中心的 Prisma schema 演进、复用与新增、迁移策略 | +| 05 | [路线图](05-roadmap.md) | 分阶段执行计划（registry-first → gateway → 变现 → 双边市集），每阶段验收 | +| 06 | [待决策清单](06-open-questions.md) | 需要用户拍板的 8 个关键决策，每个附推荐与影响 | + +--- + +## 当前状态 + +- **Phase 0（决策）** ✅ — 2026-06-13 采纳**全部推荐**（见 [06](06-open-questions.md)）。 +- **Phase 1 · Registry MVP** ✅ **本地实现并验证完成**（见 [05-roadmap.md](05-roadmap.md)）：数据模型 + 入驻（AgentCard URL/手填）+ admin 审核 + 市集 UI（`/agents` + 详情）+ 发现/registry API + 首页改版（slogan 落地）。三个测试 agent 走通「提交→审核→上架→发现」全链路。 +- **下一步**：Phase 2 · Gateway MVP（需先升配 Cloud SQL + PgBouncer + Redis）。 + +## 与现有 docs 的关系 + +本轨道是**新业务方向**，与现有 [docs/00–03](../README.md)（基础设施 / 架构优化 / coding-agent skills / 密钥加固，均已上线）并行。现有 skills 业务的处理见 [00-vision §6](00-vision-and-positioning.md#6-与现有-skills-业务的关系)。 + +## 约定（沿用现有 docs 规范） + +- 每个任务分阶段（Phase 1A/1B…），**每阶段完成后停下来等用户验收，不一次性交付**。 +- 所有 schema 变更走 `prisma migrate dev --name ` 生成迁移文件入库（已 baseline `0_init`）。 +- **实现前必读** `node_modules/next/dist/docs/`——本仓库 Next.js 16 有 breaking changes，不能凭训练记忆写代码（见根目录 `AGENTS.md`）。 +- 破坏性 API 变更在 PR 描述注明前端影响点。