📦 Weave — 加密发票

Weave 是一个用于加密发票和跨链支付工作流的 CLI。当你需要创建 Bitcoin、Ethereum、Solana、USDC 或 USDT 发票、生成支付报价，并在 Base、Tron 和 Zcash 等受支持网络上监控结算以供代理工作流或运营使用时，请使用此工具。

概述

使用 weave 完成 Weave Cash 发票生命周期工作流：

• 创建发票（weave create）
• 生成支付指令（weave quote）
• 跟踪结算（weave status 或 weave status --watch）

护栏规则

• 仅限加密到加密。不得引入法币、法币转换或法币计价行为。
• 优先使用机器可读 JSON 输出。仅当明确要求时才使用 --human。
• 切勿在输出中暴露机密（私钥、token、JWT）。
• 将网络/API 调用视为可能失败，并显式处理非零退出。

何时不使用

• 不得将此技能用于法币发票或法币结算工作流。
• 不得将此技能用于编辑 Weave Web UI/前端代码。
• 不得将此技能用于与钱包托管或私钥管理无关的任务。
• 当用户需要非 Weave 支付通道时，不得使用此技能。

起飞前检查

• 确认 CLI 可用：

weave --help

• 在选择资产前发现运行时 token/网络支持：

weave tokens

• 如果缺少 weave，提供合规安装指导并先询问再运行：

go install github.com/AryanJ-NYC/weave-cash/apps/cli/cmd/weave@latest
weave --help

如果 Go 不可用，使用 npm 回退：

npm i -g weave-cash-cli
weave --help

如果 Go 和 npm 都不可用，报告缺少前置条件。

合规安装策略

• 优先使用 metadata.openclaw.install / metadata.clawdbot.install 包管理器安装。
• 切勿建议将远程下载命令直接管道到 shell 解释器。
• 检测并指导；未经用户明确批准不得自动安装依赖。

Token 与网络选择

• 始终信任运行时二进制文件输出的实时 weave tokens。
• 不得在推理中硬编码 token/网络列表。
• 仅当接收 token 支持多个网络时才需要 --receive-network。
• 接受网络别名（例如 Ethereum|ETH、Solana|SOL、Tron|TRX，前提是运行时输出支持）。

工作流

1）创建发票

收集：

• receive-token
• amount（正数字符串）
• wallet-address
• 仅在运行时 token/网络映射要求时提供 receive-network
• 可选买家字段（description、buyer-name、buyer-email、buyer-address）

命令：

weave create \
  --receive-token USDC \
  --receive-network Ethereum \
  --amount 25 \
  --wallet-address 0x1111111111111111111111111111111111111111

预期 JSON 形状：

{
  "id": "inv_123",
  "invoiceUrl": "https://www.weavecash.com/invoice/inv_123"
}

捕获 id 以供下游 quote/status 调用。

2）生成报价

收集：

• invoice-id
• pay-token
• pay-network
• refund-address

命令：

weave quote inv_123 \
  --pay-token USDT \
  --pay-network Ethereum \
  --refund-address 0x2222222222222222222222222222222222222222

预期字段：

• depositAddress
• depositMemo（可选）
• amountIn
• amountOut
• timeEstimate
• expiresAt

3）检查状态

单次：

weave status inv_123

观察模式：

weave status inv_123 --watch --interval-seconds 5 --timeout-seconds 900

解释：

• 退出 0：达到终端状态（COMPLETED、FAILED、REFUNDED、EXPIRED）
• 退出 2：观察超时（不是命令失败）
• 退出 1：命令/API/网络/验证失败

错误处理

当退出码为 1 时，如果存在结构化 stderr JSON，则将其呈现。常见的 API 返回形状：

{
  "error": "api message",
  "status": 409,
  "details": {
    "error": "Invoice is not in PENDING status"
  }
}

如果观察超时（退出 2），视为未完成而非致命失败。建议延长 --timeout-seconds 或重新运行单次 weave status 。

运行时漂移规则

已安装的二进制文件与源码树在 token 支持方面可能出现漂移。在决定有效 token/网络组合时，始终使用运行时发现（weave tokens）。