spherico-agent_IT运维与安全 skill-PHP中文网

spherico-agent

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

端到端 Bitnow 网络 API 工作流，适用于 AI 代理。涵盖基于钱包签名的身份验证、链上充值监控、消费 API 密钥生命周期（...

Bitnow Control Plane (API- Driven) Skill. 此技能描述Bitnow网络的端到端操作工作流程,严格从API使用角度. .

功能概述

Bitnow Control Plane (API- Driven) Skill. 此技能描述Bitnow网络的端到端操作工作流程,严格从API使用角度. .是一项面向实际任务的技能，主要用于Wallet 认证(签名)。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

核心要点

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

使用与执行

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

Bitnow 控制平面（API 驱动）技能

本技能描述了 Bitnow 网络的端到端运维工作流，严格限定于API 使用视角。

基于钱包的身份认证（签名流程）
通过 API 进行链上余额充值与验证
消费者 API 密钥生命周期管理（创建、列出、撤销）
使用 API 密钥调用模型推理
通过 HTTP API 查询余额与用量

前提假设：

存在一个网关 HTTP API（例如：https://gateway-test.bitnow.ai）
所有工作流均面向 CLI、curl 或脚本，不依赖任何 UI 辅助
支持链为 base sepolia，链 ID 为 8453

请根据需要将所有替换为实际网关 URL。

1. 基于钱包的注册与会话（聚焦 API）

注意：消息签名必须由用户使用其 EVM 地址完成，仅可用于发起或验证，不可由系统代为生成签名。如尚无钱包地址，需自行创建并妥善保管。

典型 API 调用序列如下：

请求 SIWE 风格的登录挑战及消息：

curl -sS -X POST "/v1/auth/wallet/challenge" 
  -H "Content-Type: application/json" 
  -d '{
    "wallet_address": "",
    "chain_id": "8453"
  }'

响应（简化版）：

{
  "message": "Sign-In With Ethereum message...",
  "nonce": "random-nonce",
  "wallet_address": "0x...",
  "chain_id": "8453"
}

用户在链下使用其钱包对 message 进行签名。

将已签名的消息提交至网关以完成验证：

curl -sS -X POST "/v1/auth/wallet/verify" 
  -H "Content-Type: application/json" 
  -d '{
    "wallet_address": "",
    "nonce": "random-nonce",
    "signature": ""
  }'

成功响应（简化版）：

{
  "login_token": "sess-...",
  "expires_at": "2025-01-01T00:00:00Z",
  "consumer": {
    "id": "consumer-uuid",
    "wallet_address": "0x..."
  },
  "session": {
    "id": "session-uuid"
  }
}

login_token（以 sess- 开头）作为会话令牌使用：
- 在需会话认证的端点中，将其作为 Authorization: Bearer 请求头发送。

校验项：

后续所有需身份认证的调用中，均须携带 Authorization: Bearer sess-... 请求头，且其中会话令牌有效。

2. 链上充值流程（API 验证）

充值操作在链上执行（将 USDC 转入 ConsumerDeposit 合约），由链下索引器追踪状态。API 提供结果验证能力。
您可使用自有节点，亦可使用默认节点：https://sepolia.base.org

用户向 ConsumerDeposit 合约转账 USDC，并附带正确的 calldata。
后端在 L1/L2 交易确认后（由索引器驱动）为消费者账户增加余额。
USDC 合约地址为：0x10065E7b353371DD2e12348e7094cC774638EbEB
ConsumerDeposit 合约地址为：0xB0E9ebf19AB710d3353c7F637DC55329d9727dCc
- 充值前需先调用 approve 授权额度
- 充值 ABI 为：function deposit(uint256 amount)

通过 API 验证余额：

curl -sS -X GET "/v1/balance" 
 -H "Authorization: Bearer "

示例响应：

{
  "balance_usdc": "123.45",
  "total_spent": "10.00"
}

故障排查建议：

比对链上交易哈希与 API 返回的 balance_usdc 值，用于识别索引器异常或同步延迟问题。

3. 消费者 API 密钥生命周期（纯 API 方式）

消费者可通过 API 密钥访问模型，无需维持会话。

3.1 创建 API 密钥

需提供有效的会话令牌（来自第 1 节的 login_token）。

curl -sS -X POST "/v1/consumer/api-keys" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer " 
  -d '{
    "label": "my-key"
  }'

示例响应（请安全保存 api_key；该值仅返回一次！）：

{
  "id": "key-uuid",
  "api_key": "sk-consumer-...",
  "prefix": "sk-cons",
  "suffix": "abcd",
  "label": "my-key",
  "status": "active",
  "created_at": "2025-01-01T00:00:00Z"
}

3.2 列出 API 密钥

curl -sS -X GET "/v1/consumer/api-keys" 
  -H "Authorization: Bearer "

3.3 撤销 API 密钥

curl -sS -X DELETE "/v1/consumer/api-keys/" 
  -H "Authorization: Bearer "

密钥状态将被设为 revoked；此后使用该密钥的调用将因鉴权失败而报错。

3.4 声明上级账户（子账户 → 上级账户关系）

此接口用于让子账户声明其上级账户。该操作需对结构化消息进行钱包签名，且签名必须由子钱包生成。

接口地址：

curl -sS -X POST "/v1/consumers/me/parent" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer " 
  -d '{
    "parent_wallet": "",
    "issued_at": 1710000000,
    "signature": ""
  }'

注意事项：

issued_at 为Unix 秒时间戳，必须距当前时间不超过 5 分钟，且不得超前于当前时间超过 1 分钟。

待签名的消息内容必须完全一致：

Authorize parent for DePIN LLM
Parent wallet: 
Child wallet: 
Issued at:

成功响应（HTTP 201）：

{
  "parent_consumer_id": "consumer-uuid",
  "parent_wallet_address": "0x...",
  "created_at": "2025-01-01T00:00:00Z"
}

常见错误码：

400 INVALID_REQUEST：请求体格式无效
400 SIGNATURE_EXPIRED：issued_at 时间戳超出窗口范围
404 PARENT_NOT_FOUND：未找到指定上级账户
400 SELF_PARENT：禁止声明自身为上级
401 SIGNATURE_MISMATCH：签名非来自子钱包
409 ALREADY_SET：上级账户已声明

4. 模型推理 API 使用方式

持有有效的 CONSUMER_API_KEY 后，即可调用模型。

4.1 列出可用模型

curl -sS -X GET "/v1/models"

使用前务必校验：通过返回列表确认目标模型存在。

4.2 补全 / 对话端点

curl -sS -X POST "/v1/chat" 
 -H "Content-Type: application/json" 
 -H "Authorization: Bearer " 
 -d '{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Explain the Bitnow network in one paragraph." }
  ]
}'

API 错误处理：

401：密钥无效或已过期；请检查 Authorization 请求头
402：余额不足
404：模型未找到（检查 MODEL_NOT_FOUND 错误码）
请查阅响应 JSON 中的 error.code 和 error.message 字段获取详细信息

5. 查询余额与用量（API 方式）

5.1 余额查询

（参见第 2 节，/v1/balance 接口）

5.2 用量指标

用量数据通过消费者作用域的接口暴露：

curl -sS -X GET "/v1/usage?limit=100&offset=0" 
  -H "Authorization: Bearer "

响应由 Registry 代理返回，通常包含以下字段：

id —— 用量记录 ID
timestamp / created_at —— 调用被记录的时间
model —— 模型名称（例如：gpt-4o-mini）
promptTokens —— 提示词 token 数量
completionTokens —— 补全 token 数量
costUsdc —— 本次调用产生的 USDC 成本
apiKeyId —— 可选，本次调用所使用的消费者 API 密钥 ID

典型工作流可能按模型或时间段聚合用量，用于成本与 token 消耗分析。

6. 供应商 / 提供方 API 工作流（进阶）

仅限上游服务提供商使用：

注册 API 密钥提供方（上游密钥经 Key Vault 托管）：

curl -sS -X POST "/v1/suppliers/api-key" 
  -H "Content-Type: application/json" 
  -d '{
    "wallet_address": "",
    "provider": "openai",
    "api_key": "sk-upstream-...",
    "models": ["gpt-4o", "gpt-4o-mini"],
    "price_per_million_tokens": "2.50",
    "max_requests_per_hour": 3600
  }'

注册 GPU 节点（按钱包粒度的 GPU 供应商）：

curl -sS -X POST "/v1/suppliers/gpu" 
  -H "Content-Type: application/json" 
  -d '{
    "wallet_address": "",
    "models": ["gpt-4o", "claude-3-5-sonnet-20241022"],
    "price_per_million_tokens": "5.00",
    "max_requests_per_hour": 1000,
    "endpoint": {
      "base_url": "https://gpu-node.example.com",
      "backend_type": "openai_http",
      "timeout": 30000,
      "auth_type": "bearer",
      "auth_value": "upstream-node-token",
      "health_endpoint": "/healthz"
    }
  }'

更新 GPU 节点配置：

curl -sS -X PATCH "/v1/suppliers/gpu/" 
  -H "Content-Type: application/json" 
  -d '{
    "models": ["gpt-4o", "gpt-4o-mini"],
    "price_per_million_tokens": "4.50",
    "max_requests_per_hour": 2000,
    "endpoint": {
      "base_url": "https://gpu-node.example.com",
      "backend_type": "openai_http",
      "timeout": 45000,
      "auth_type": "bearer",
      "auth_value": "rotated-node-token",
      "health_endpoint": "/healthz"
    }
  }'

按需查询提供方 / 模型元数据：

curl -sS -X GET "/v1/metadata/providers"
curl -sS -X GET "/v1/metadata/models"

7. AI 代理使用指南

在处理 Bitnow 网络运维支持任务时，请遵循以下最佳实践：

将用户问题直接映射至对应的API 工作流，不参考任何 UI 元素。
- 典型意图示例：新用户接入、余额异常、API 密钥管理、配额/成本分析
提供具体可执行的 curl 命令，并适配用户实际配置（如、等）。
故障排查时：
- 要求用户提供完整的 API HTTP 响应（含状态码与 JSON 响应体）。
- 依据 error.code 及上下文选择修复步骤。
表述简洁，聚焦于可执行命令与下一步操作。
仅在用户明确要求时，才提供背景技术细节。