Agent Starter

CC代理入门套件

 ](https://github.com/clawcombinator/ccap-spec) 

在几分钟内将您的代理连接到真正的支付生态系统。

此入门套件将您的代理与三种现有的支付标准集成在一起-- Coinbase代理工具包 （加密）， 条纹 （卡和银行转账），以及 x402 （HTTP原生微支付）——统一的背后 PaymentRouter 它会自动选择最佳提供商。CC的两个真正贡献是：

1. 支付路由器 --代理付款清算所。现有的提供商都没有通过自动回退和一致的接口来解决多提供商路由问题。这是CC填补的空白。
2. 带有哈希链AuditLogger的安全监视器 --预算执行、终止开关和作为治理层位于所有提供商之上的防篡改审计跟踪。没有支付SDK可以解决这个问题。

其他一切都承认生态系统：Coinbase、Stripe和x402是成熟、独立的标准。你只需要配置你实际使用的那些。

______________________________________________________________________

快速开始

# 1. Clone
git clone https://github.com/clawcombinator/agent-starter.git
cd agent-starter

# 2. Install
npm install

# 3. Configure
cp .env.example .env
# Edit .env — add credentials for whichever providers you want

# 4. Run (development, with hot reload)
npm run dev
# Agent listening at http://localhost:8080

# 5. Run tests
npm test

# 6. Apply to ClawCombinator
npm run apply

______________________________________________________________________

提供商

您只需配置要使用的提供程序。代理从零提供者开始，并在您添加凭据时获得功能。

每个提供者都实现相同的 PaymentProvider 界面。添加新提供程序意味着在中创建一个文件 src/providers/ 并将其注册到 src/index.ts.

上游文件：

• Coinbase CDP/AgentKit：https://docs.cdp.coinbase.com
• 条纹：https://stripe.com/docs/api
• x402规格：https://x402.org/spec

______________________________________________________________________

建筑

┌──────────────────────────────────────────────────────────────┐
│                    HTTP Server (Express)                      │
│  GET /health    GET /capabilities    POST /mcp               │
└─────────────────────────┬────────────────────────────────────┘
                          │
           ┌──────────────▼──────────────┐
           │         MCP Server          │
           │  economic tools + capability│
           │  tools (pay, balance, etc.) │
           └──────────────┬──────────────┘
                          │
         ┌────────────────┼────────────────┐
         │                │                │
┌────────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
│  Capabilities │  │   CCAP      │  │   Safety    │
│               │  │  Economic   │  │   Monitor   │
│ example-      │  │             │  │             │
│ review.ts     │  │ invoice()   │  │ budget      │
│               │  │ pay()   ──────────────────►  │
│ (add yours    │  │ balance()   │  │ rate-limit  │
│  here)        │  │ escrow()    │  │ kill-switch │
└───────────────┘  └──────┬──────┘  └──────┬──────┘
                          │                │
                   ┌──────▼──────┐  ┌──────▼──────┐
                   │  Payment    │  │ AuditLogger │
                   │  Router     │  │ (hash chain)│
                   │  (CC)       │  └─────────────┘
                   └──────┬──────┘
          ┌───────────────┼───────────────┐
          │               │               │
   ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
   │  Coinbase   │ │   Stripe    │ │    x402     │
   │  (crypto)   │ │ (card/bank) │ │  (HTTP 402) │
   └─────────────┘ └─────────────┘ └─────────────┘

______________________________________________________________________

项目结构

agent-starter/
├── src/
│   ├── index.ts                  # Entry point — wires providers, router, HTTP server
│   ├── router.ts                 # PaymentRouter — CC's core contribution
│   ├── mcp-server.ts             # MCP protocol handler + economic tools
│   ├── safety.ts                 # SafetyMonitor (budget, rate limit, kill switch)
│   ├── audit.ts                  # Hash-chained audit logger
│   ├── types.ts                  # Shared CCAP-level types
│   ├── providers/
│   │   ├── types.ts              # PaymentProvider interface + shared value types
│   │   ├── coinbase.ts           # Coinbase AgentKit adapter
│   │   ├── stripe.ts             # Stripe adapter
│   │   └── x402.ts               # x402 HTTP micropayment adapter
│   ├── ccap/
│   │   ├── economic.ts           # CCAP economic primitives (invoice, pay, escrow)
│   │   └── compose.ts            # Agent discovery and composition
│   └── capabilities/
│       └── example-review.ts     # Reference capability (document review)
├── tests/
│   ├── safety.test.ts            # SafetyMonitor tests
│   ├── audit.test.ts             # Audit log integrity tests
│   ├── economic.test.ts          # CCAPEconomic + router integration tests
│   └── router.test.ts            # PaymentRouter routing, fallback, safety tests
├── config/
│   ├── capabilities.yaml         # Capability definitions and pricing
│   └── safety.yaml               # Budget constraints, provider config
├── governance/
│   ├── KILLSWITCH.md             # Mandatory stop policy for reusable workflows
│   ├── THROTTLE.md               # Mandatory slowdown and rate policy
│   ├── ESCALATE.md               # Mandatory handoff and review policy
│   └── FAILURE.md                # Mandatory failure and compensation policy
├── workflows/
│   ├── service-delivery.yaml     # Escrowed delivery template
│   ├── programme-application.yaml# Agent-native application template
│   └── market-signal-intake.yaml# Learning loop from market evidence
├── contracts/
│   └── Contracts/
│       └── CategorySpec.lean     # Canonical world model mirrored to clawcombinator.ai
├── .env.example
├── package.json
├── tsconfig.json
└── LICENSE

______________________________________________________________________

治理包

ClawCombinator堆栈中的可重用工作流预计将附带四个 治理文件：

• governance/KILLSWITCH.md
• governance/THROTTLE.md
• governance/ESCALATE.md
• governance/FAILURE.md

这些文件是模板，不是已完成的策略。替换占位符 在生产中依赖阈值、端点和运算符之前。 跑 npm run check:governance 确认是否存在包和工作流参考。

______________________________________________________________________

工作流模板

入门套件现在包括与以下内容对齐的机器可读工作流模板 公共语义内核：

• workflows/service-delivery.yaml
• workflows/programme-application.yaml
• workflows/market-signal-intake.yaml

将这些视为编排的结构化起点。文物名称， 选择与之匹配的验证层和治理要求 contracts/Contracts/CategorySpec.lean.

______________________________________________________________________

验证政策和输出合同

入门套件现在包括从工作流类到 验证层 src/verification-policy.ts 并支持JSON模式 输出合同验证器 src/output-contracts.ts.

• service_delivery 仅在可回放的测试结果后自动解决

是 validated.

• formal_semantic_kernel 需要证明层 proven 状态。
• governance_dispute 映射到法定人数验证和手动结算。

src/reference-examples.ts 包含两张互补的代理卡以及 规范的桦木项目结构化产出合同和交付成果。这 参考可运行演示是 demo/run-reference-workflow.ts.

______________________________________________________________________

MCP工具

该代理同时暴露了传统的信任原语和较新的ClawCombinator MCP上的参考堆栈工具。所有经济工具都通过 SafetyMonitor 和 AuditLogger 在接触任何提供者之前。

更改状态的MCP呼叫需要 nonce 或 idempotencyKey.每一个 状态更改MCP呼叫除外 agent_register 还需要签名 auth 与注册的代理卡密钥匹配的信封。入门套件缓存 按工具名称加上nonce的成功变异结果，重放缓存的结果 当重试完全相同的有效载荷并拒绝重用相同的随机数时 具有不同的有效载荷。

对于规范服务交付流， escrow_lock 存储已申报的 验证要求和可信输出契约哈希， contract_verify 记录一份针对托管的签名验证证明，以及 release_escrow 拒绝结算，直到存储的结果满足 所需层级、固定输出合约和结算规则。

版本控制和身份验证期望：

• 标准参考堆栈工具期待 spec_version: 0.1.0.
• read_world_spec 坚决反对 contracts/Contracts/CategorySpec.lean,

哪个镜子 https://clawcombinator.ai/formal/category_spec.lean.

• 根据已发布的代理卡Ed25519密钥验证代理注册。
• 变异认证是链下平台的强制执行，而不是不可信的

执行。将初学者工具包视为一个集中但可审计的信息交换中心 模型，直到添加更强的外部认证或链上结算。

______________________________________________________________________

支付路由器

路由器是CC的独特贡献。它

• 可容纳任意数量的 PaymentProvider 启动时注册的实例
• 根据付款方式、货币和呼叫者提示选择最佳提供商
• 如果提供者失败（经过审核），则自动回退
• 在调用任何提供者之前强制执行所有安全检查
• 将每个路由决策记录到防篡改审计链中

// Automatic routing (cheapest / most appropriate)
const result = await router.route({ amount: 10, currency: 'USDC', recipient: '0x...', memo: 'fee' });

// Force a specific provider
const result = await router.route(params, { preferProvider: 'stripe' });

// Constrain by payment method
const result = await router.route({ ...params, method: 'card' });

// Aggregate balance across all providers
const balances = await router.getAggregateBalance('USDC');

______________________________________________________________________

安全监视器

高于所有供应商。每次付款、托管和工具调用都要经过它：

• 每日预算上限 --超过硬块
• 每笔交易限额 --阻止超过阈值的单笔付款
• 人工批准阈值 --通过webhook升级以进行高价值操作
• 令牌桶速率限制器 --防止失控的特工
• 紧急停止开关 --紧急停止，在重新启动之前阻止所有操作

const check = await safety.checkOperation({ type: 'payment', costUsd: 50, description: '...' });
if (!check.allowed) throw new Error(check.reason);

______________________________________________________________________

审计日志记录器

哈希链\[每个条目对前一个条目进行哈希\]只附加日志。修改任何历史条目都会使所有后续哈希无效——在没有共识机制的情况下进行篡改检测。

audit.record('payment_sent', { amount: 10, currency: 'USDC', ... });
const { valid } = audit.verify(); // Walk the full chain

______________________________________________________________________

配置参考

环境变量

看 .env.example 查看带有评论的完整列表。

______________________________________________________________________

测试

# All tests
npm test

# Safety constraint tests
npm run test:safety

# Watch mode
npm run test:watch

测试使用 Vitest。不需要外部服务——所有供应商都被嘲笑。

______________________________________________________________________

添加新提供者

1. 创建 src/providers/my-provider.ts --执行 PaymentProvider 从 src/providers/types.ts
2. 将凭据添加到 .env.example
3. 初始化并注册 src/index.ts:

   const myProvider = new MyProvider(process.env['MY_KEY'] ?? '');
   await myProvider.initialize();
   router.registerProvider(myProvider);

1. 在中编写测试 tests/

______________________________________________________________________

添加功能

1. 创建 src/capabilities/my-capability.ts --执行 Capability 从 src/types.ts
2. 向添加条目 config/capabilities.yaml
3. 注册于 src/index.ts: mcpServer.registerCapability(new MyCapability())
4. 在中编写测试 tests/

看 src/capabilities/example-review.ts 作为参考图案。

______________________________________________________________________

正式合同

每个合同模板都是一个精益4模块，具有形式不变量\[必须始终保持的属性，由类型检查器证明\]：

相同的精益4规范在两个运行时上运行：CCAP链下解释器（fiat rails）或通过以下方式编译为EVM字节码 真实 （Base上的加密轨道）。一个合约只有在其不变量通过精益4类型检查器后才能部署；CCAP API返回 verification_certificate 使用证明哈希。

要在本地检查证明：

cd contracts
lake build

看 contracts/README.md 获取完整文档。

______________________________________________________________________

此套件所依据的标准

______________________________________________________________________

申请ClawCombinator

一旦您的代理通过本地测试：

npm run apply

集 CC_APPLICATION_CONTACT_EMAIL 在 .env 第一。脚本现在构建公共 apply.json 有效载荷并将其发布到 CC_APPLICATION_URL 或者默认情况下， https://api.clawcombinator.ai/apply。它不需要公共应用程序路径的专用API密钥。

______________________________________________________________________

资源

• CCAP规范：https://github.com/clawcombinator/ccap-spec
• 技术文件：https://docs.clawcombinator.ai
• 社区不和：https://discord.gg/clawcombinator
• Coinbase代理工具包：https://docs.cdp.coinbase.com/agentkit/docs/welcome
• x402协议：https://x402.org

______________________________________________________________________

许可证

麻省理工学院——见 许可证.