DIEM Agent Workers

DIEM Agent Workers

以隐私为先、可供机器发现的微型工作服务，由 Venice 私有推理驱动，通过 x402 以 USDC 付费。

此仓库是一个 fail-closed、以 Agent 为先的 Base 主网商店。它通过纯 HTTP + x402 提供六项边界明确的工作服务，将其发布到 CDP Bazaar，并提供 A2A 1.0、MCP、OpenAPI、llms.txt 和可移植技能发现入口。

公开测试版：diem-agent-workers.vercel.app

Worker	边界明确的结果	测试版价格
extract_text_to_json	符合调用方架构的提取结果	$0.020 USDC
classify_text	恰好一个由调用方提供的标签	$0.010 USDC
summarize_text	结构化摘要和要点	$0.020 USDC
text_to_speech	最多 1,000 个字符，输出为 MP3	$0.010 USDC
generate_draft_image	一张安全模式下的 1024px WebP 图片	$0.020 USDC
transcribe_audio	最长 60 秒的经验证 PCM WAV 音频	$0.015 USDC

这些是每次成功授权尝试的固定价格，并非估价。公开部署是一个低容量的 Base 主网测试版：原子性 0.25 DIEM 软件预算限制每日推理启动次数；此外，Venice API 密钥还保留独立的 1.69 DIEM 提供方备用额度。

隐私设计

• 持久化指标不包含提示词、输出、付款方地址、交易哈希、IP 地址、用户代理和请求标识符。
• 不会主动记录或持久化请求正文和提供方响应正文。
• 公开可靠性统计仅为生命周期汇总数据；不含可能暴露活动模式的时间戳或时间段。
• Worker 使用 Venice 私有模型，并禁用网页搜索、抓取和模型工具调用。
• 交付保护仅存储 HMAC 指纹，以及兑换中断交付所需的有限状态。

可选的 USDC-to-DIEM 财库在生产环境中仍处于禁用状态，不属于商店运行时的一部分。Vercel 上未部署钱包签名器或私钥。

已实现功能

• 三项 Venice 结构化输出文本 Worker，并在响应后进行 JSON Schema 验证
• 有限额度的 Venice 语音、图像和转录 Worker
• Venice 原生 API 密钥计算额度上限：每 EPOCH 1.69 DIEM（每日额度，于 UTC 00:00 重置）
• 由 Upstash 支持的原子软件额度上限：每 UTC 日保守预留的工作额度为 0.25 DIEM
• 付款前检查由环境变量控制的商店紧急停用开关
• 付款前验证输入，包括精确的 PCM WAV 时长检查
• 付款前检查 Venice 时段访问权限、模型在线状态、私有模型状态和能力
• 免费的机器可读目录和每个 Worker 的固定价格报价
• OpenAPI 3.1、llms.txt、A2A 1.0 Agent Card、JSON-RPC SendMessage 和 Streamable HTTP MCP 发现入口
• 通过 CDP Facilitator 实现 x402 固定价格 USDC 付款门控
• 每个 Worker 均提供丰富的 x402 Bazaar 架构、服务名称、主题标签和服务图标
• 面向公开 Streamable HTTP 服务的官方 MCP Registry 元数据
• 保护隐私的运行时遥测，以及持久化的生命周期汇总可靠性、结算、收入、延迟分桶和 DIEM 计数器
• 由 Upstash Redis 原子状态支持的持久化、幂等付费交付额度
• 已发布的机器可读条款，并从每个响应和发现入口链接到这些条款
• 付款直接发送至专用财库地址
• 仅报价模式和实时 USDC-to-DIEM 财库模式
• 硬编码的 Base USDC、Venice DIEM、链 ID 和 0x AllowanceHolder
• 精确授权、每笔兑换限额、滑点上限、ETH Gas 储备、进程锁和仅限所有者访问的审计日志
• 可安装的 Agent 技能和本地/stdio MCP 适配器

此服务与 Venice.ai 无关联，也未获得其认可。

本地启动

要求：Node.js 22+ 和 pnpm。

cp .env.example .env
pnpm install
pnpm test
pnpm dev

在 .env 中添加服务端 Venice 密钥：

VENICE_API_KEY=...
VENICE_TEXT_MODEL=venice-uncensored-1-2
VENICE_IMAGE_MODEL=venice-sd35
VENICE_TTS_MODEL=tts-kokoro
VENICE_ASR_MODEL=openai/whisper-large-v3
VENICE_DIEM_EPOCH_CAP=1.69

VENICE_DIEM_EPOCH_CAP 会在服务发现中公布上限，且必须与 Venice API 密钥上配置的原生 EPOCH 消耗限制一致。Venice 会强制执行硬性限制。在返回 402 之前，服务还会检查当前 epoch 访问权限，以及指定模型的在线状态、私有状态和能力；绝不会根据 token 数量估算 DIEM 费用。

开发服务器绑定到 127.0.0.1:8402。

curl http://127.0.0.1:8402/health
curl http://127.0.0.1:8402/v1/catalog
curl -X POST http://127.0.0.1:8402/v1/quote/classify_text

设置 PAYMENTS_MODE=off 后，本地测试时无需付款即可调用此工作器：

curl -X POST http://127.0.0.1:8402/v1/jobs/extract-json \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "The Acme Trail Mug is drinkware and costs $18.50.",
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": ["string", "null"]},
        "category": {"type": ["string", "null"]},
        "price_usd": {"type": ["number", "null"]}
      },
      "required": ["name", "category", "price_usd"],
      "additionalProperties": false
    }
  }'

生产环境仅在 PAYMENTS_MODE=production、启用持久化交付额度强制机制、启用全局计算预算强制机制并启用仅聚合指标后才会启动。仓库中提交的默认值和本地默认值仍为 PAYMENTS_MODE=off、STOREFRONT_ENABLED=false、AGGREGATE_METRICS_MODE=off 和 TREASURY_MODE=disabled。

添加 x402 付款

导入已下载的 CDP Secret API Key，但不打印其值：

pnpm credentials:import-cdp /absolute/path/to/cdp_api_key.json

此命令会将下载的密钥文件和 .env 的权限收紧为仅所有者可访问。若凭据已配置，命令会拒绝覆盖，且不会启用付款。

在 Base Sepolia 上启动：

PAYMENTS_MODE=development
TREASURY_ADDRESS=0xYourDedicatedEvmAddress
CDP_API_KEY_ID=...
CDP_API_KEY_SECRET=...

服务器使用 CDP 配置中的地址形式，因此付款会直接结算至 TREASURY_ADDRESS；CDP 不会创建或控制该钱包。向工作器发送未付款请求时，应返回 HTTP 402 和 PAYMENT-REQUIRED 标头。

付费交付保护

除非启用了持久化交付额度强制机制，否则主网会默认拒绝服务。请通过 Vercel Marketplace 配置 Upstash Redis 数据库，然后设置：

DELIVERY_CREDITS_MODE=enforced
DELIVERY_CREDIT_HMAC_SECRET=<at-least-32-random-bytes>
DELIVERY_CREDIT_TTL_SECONDS=86400
DELIVERY_CREDIT_LEASE_SECONDS=180
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...

Agent 应为每个逻辑任务生成一个不可预测的 Idempotency-Key，且仅在请求和付款授权完全相同时重复使用。未带该标头的已签名付费请求会在结算前失败。Redis 记录仅包含 HMAC 指纹、工作器 ID、状态、租约和到期时间，不会包含请求正文、服务商响应、付款方地址、付款标头或交易哈希。

正常成功交付后，该密钥会被消耗。如果进程在结算后、交付完成前中断，则相同的付款授权、密钥、工作器和请求可重试一次，无需再次结算。重复使用时若内容冲突，则会被拒绝；存储服务不可用时，会在结算前返回 503。

主网计算预算和紧急停用开关

生产环境还需要一个原子级全局计算预算：

COMPUTE_BUDGET_MODE=enforced
COMPUTE_BUDGET_DIEM_PER_DAY=0.25
AGGREGATE_METRICS_MODE=enabled
STOREFRONT_ENABLED=true

x402 验证后、Venice 推理前，服务会预留一笔保守金额，等于任务的 USDC 价格。即使买家不会再次付费，交付重试仍会再次预留，因为它们可能消耗提供方容量。Redis 故障或预算耗尽会中止新的付款结算并阻止推理。设置 STOREFRONT_ENABLED=false 并重新部署，即可在付款前禁用所有付费任务。

使用以下命令运行受保护的本地 Base Sepolia 结算测试：

pnpm test:sepolia

这是一笔实际的测试网交易：它会创建一个临时的内存买家， 请求水龙头 USDC，在签名之前验证准确的报价，支付一次工作器 调用，并核对金库的测试 USDC 增量。只有在已保存的 PAYMENTS_MODE 为 off 且 TREASURY_MODE 为 disabled 时才会运行。 本地 HTTP 测试不会发布到 Bazaar；必须部署到公共 HTTPS 环境。

主网上线检查清单：

1. 使用专用的低余额金库钱包，而非个人钱包。
2. 验证地址和 Base 网络。
3. 部署在公共 HTTPS 之后。
4. 使用 CDP 验证 API 验证 x402 端点。
5. 发布并审阅 TERMS.md；每个 API 响应都会链接到 /terms。
6. 启用持久交付额度和 0.25 DIEM 原子级软件预算。
7. 设置 PAYMENTS_MODE=production，保持 TREASURY_MODE=disabled，然后部署。
8. 完成一笔真实的小额付款，以便 Bazaar 为 Base 主网资源编制索引。

主网验收测试工具使用一个保存在 macOS Keychain 中的独立、仅以美分计价的买家，在签名前验证每项付款要求，并拒绝总额超过 $0.095 USDC 的店面授权。使用 MAINNET_X402_TEST_WORKERS 选择单个工作器，或使用 pnpm test:mainnet:all；多工作器运行需要精确确认 PAY_UP_TO_0_095_USDC_WITH_DISTINCT_BUYER_ON_BASE。其输出会刻意省略钱包地址、交易哈希、请求正文和提供方响应。

将 USDC 再投资为 DIEM

该资金库是一个确定性的一次性运行器，而非由提示词驱动的钱包 Agent。

在 macOS 上创建一个专用新钱包：

pnpm wallet:create

此命令会将私钥存储在 macOS Keychain 中，并仅将公有地址和 Keychain 标签写入 .env。它不会覆盖现有钱包，并要求禁用支付和资金库执行功能。

若要通过助记词恢复，请在受信任的钱包应用中创建一个专用钱包，将助记词离线保存，仅导出其资金库账户私钥，然后通过隐藏的本地提示词导入该私钥：

pnpm wallet:import

切勿将助记词输入项目。导入命令会显示派生出的公有地址以供确认，将账户密钥存储在 macOS Keychain 中，并且仅在 Keychain 读回成功后替换之前已禁用的资金库配置。

验证所有权并读取 Base 余额，而不泄露密钥：

pnpm wallet:verify

有关通过 macOS 身份验证进行恢复和导入钱包的流程，请参阅 docs/WALLET_ACCESS.md。切勿通过聊天发送私钥；如果你已控制某个钱包，只需分享其公有 0x 地址。

仅报价模式会读取余额并请求 0x 参考价格，但绝不会签名：

TREASURY_MODE=quote
TREASURY_ADDRESS=0xYourDedicatedEvmAddress
BASE_RPC_URL=https://your-base-rpc.example
ZEROX_API_KEY=...
TREASURY_MIN_SWAP_USDC=5
TREASURY_MAX_SWAP_USDC=25
TREASURY_USDC_HOLDBACK=0
TREASURY_MAX_SLIPPAGE_BPS=100
TREASURY_MIN_ETH_RESERVE=0.0005

pnpm treasury:run

实盘模式还需要从 macOS Keychain（或生产级密钥管理器）获取匹配的专用密钥，并提供准确的确认信息：

TREASURY_MODE=live
TREASURY_LIVE_ACK=BUY_DIEM_ONLY_ON_BASE

部署时应使用生产级密钥管理器，而非明文 .env。实盘运行器会：

• 拒绝与 TREASURY_ADDRESS 不匹配的密钥
• 拒绝错误的代币对、链、授权目标、原生币金额或超额 Gas
• 仅批准预期的 USDC 金额
• 在批准后刷新 firm 报价
• 在广播前记录已签名的交易哈希，并在重启后核对
• 验证 USDC 减少量不超过授权金额，且 DIEM 余额增加
• 将 0600 JSONL 审计记录写入 data/

运行器不会出售 DIEM、提取 USDC、跨链桥接资产、选择任意代币或质押 DIEM。

机器发现

• GET /v1/catalog — 功能、架构、限制、价格
• GET /v1/stats — 生命周期累计的可靠性与结算计数，不包含调用方身份或时间序列
• GET /.well-known/agent-catalog.json — 便于爬虫使用的目录别名
• GET /openapi.json — OpenAPI 3.1 契约
• GET /llms.txt — 简明、便于 Agent 阅读的索引
• GET /.well-known/agent-card.json — A2A 1.0 Agent Card
• POST /a2a — 固定价格为 $0.020 USDC 的 A2A 1.0 JSON-RPC SendMessage 适配器
• POST /mcp — 无状态 Streamable HTTP MCP 服务，提供免费的目录、报价和调用准备工具
• skills/extract-text-to-json/ — 可移植的 Agent 技能
• GET /icon.svg — x402 Bazaar 元数据使用的稳定服务图标
• x402 Bazaar 元数据 — 启用支付后自动附加架构、服务名称、五个主题标签和图标

MCP 适配器有意不接受钱包密钥。Agent 可使用自身支持 x402 的客户端执行已准备的调用，也可使用 Coinbase 的 Bazaar MCP 服务发现已索引的 x402 资源。

远程 MCP 服务由 server.json 描述，并归属 io.github.coastmancoastman/diem-agent-workers 命名空间，以便发布到官方 MCP Registry。

私有店面遥测

生产环境会将单行 JSON 事件写入服务器运行时日志。架构采用明确的允许列表：路由类别、HTTP 状态、延迟、工作器、粗略错误类别、模型、确切结算价格，以及 DIEM 费用／利润率估算。费用估算使用 Venice 的公开模型定价目录，不会查询账户余额或账单历史记录。

遥测绝不包含提示词、输出、提示词长度、令牌数、原始 URL、请求 ID、IP 地址、用户代理、标头、付款方身份、交易哈希、提供商请求 ID 或凭据。遥测失败绝不会阻止工作器响应。

从已保存的 JSONL 文件创建本地汇总报告：

pnpm telemetry:report /absolute/path/to/runtime-logs.jsonl

或者，报告所关联 Vercel 项目的近期生产日志：

vercel logs --environment production --since 24h --no-branch --json --limit 1000 \
  | pnpm telemetry:report

报告包含请求数和付款数、已结算的 USDC 收入、DIEM 费用和毛利率估算、延迟百分位数，以及粗略的失败计数。它无法还原单个客户的内容或身份。

由于无服务器运行时日志并非持久的业务账本，生产环境还会向用于安全状态的同一个 Upstash 数据库写入原子性的累计计数器。GET /v1/stats 会公布已完成／失败的运行次数、粗略失败类别、固定延迟区间、结算额、收入，以及按工作器划分的 DIEM 估算值。计数器键不包含日期或时间戳，写入 API 也不接受任意客户或请求字段。

安全与法律说明

服务的使用受 TERMS.md 约束，该文件也发布于 /terms。接受第三方工作前，请阅读 SECURITY.md 和 docs/END_USER_TERMS_CHECKLIST.md。AI 输出符合某个架构，并不能证明其内容正确。请勿将此工作器用于高风险决策。

验证

当前生产验收证据（包括全部 6 笔 Base Sepolia 结算交易）记录于 docs/BASE_SEPOLIA_ACCEPTANCE.md。

pnpm check
pnpm test
pnpm build
pnpm generate:openapi
ALLOW_VENICE_EVAL=1 VENICE_EVAL_MODELS=venice-uncensored-1-2 pnpm eval:text

实时评估为可选，因为它会占用 Venice 容量。它只会输出准确率和延迟的汇总数据；不会持久化提示词或提供商响应。