Sphere SDK：自主经济代理的 TypeScript 工具包
为自主经济代理提供身份、钱包、支付与消息功能的模块化 TypeScript SDK。
证据显示：SDK 采用模块化端口设计，密钥本地保存，服务器托管代币，但未提供用户确认机制（如发送前确认）。数据流透明性较好，文档明确说明支付走 wallet-api 而非 Nostr，并公开了测试网 API 密钥。敏感数据处理：支持密码加密（PBKDF2），但未详细说明密钥存储细节。依赖安全：依赖 noble 加密库，但未提供依赖审计或漏洞扫描证据。外部影响：支付和消息发送有明确的外部效果，但未提供撤销或回滚机制。来源归属：发布者未验证，但仓库有明确的作者和许可证。扣分原因：缺少用户确认、回滚机制，依赖安全证据不足。
证据显示：文档和代码示例一致，错误处理明确（如 CERTIFICATION_UNCONFIRMED 不可重发）。依赖可用性：依赖多个外部服务（网关、中继），但未提供离线或降级方案。失败消息：提供了详细的错误码和恢复指导。扣分原因：依赖外部服务可用性未充分说明。
证据显示：面向浏览器、Node.js、CLI 和 dApp 集成，场景覆盖支付、消息、群聊等。能力边界清晰：明确区分支付和消息通道。触发精度：事件驱动，如 transfer:incoming。环境适配：支持浏览器和 Node.js，但未提及移动端。扣分原因：未提供移动端支持。
证据显示：README 结构清晰，安装说明详细，命名稳定（如 createBrowserProviders）。示例丰富，包括快速入门和 E2E 测试。已知限制：文档提到 mainnet/dev 仍为 v1 协议，支付会失败。许可证为 MIT。版本化：有版本号，但未提供 CHANGELOG。维护责任：发布工作流存在，但未明确维护者。扣分原因：缺少 CHANGELOG 和明确的维护者信息。
证据显示：输出可用性高，提供清晰的 API 和事件。边际价值：为自主经济代理提供身份、钱包和支付能力，具有独特价值。成本效益：依赖多个外部服务，可能增加部署成本。扣分原因：成本效益证据不足。
证据显示：README 中的声明与代码示例一致，测试文件提供了 E2E 验证。交叉来源：文档和测试相互印证，但未提供独立第三方验证。事实与推断分离：文档明确区分事实（如网络配置）和推断（如安全性）。扣分原因：交叉来源证据有限。
- 发布者未验证，使用前需自行评估信任风险。
- 支付操作不可回滚，且 CERTIFICATION_UNCONFIRMED 错误不可重发，需谨慎处理。
- 依赖多个外部服务（网关、中继），需确保其可用性和安全性。
- 测试网 API 密钥公开，但主网密钥需保密。
这个 Agent 能做什么，适合哪些场景？
Sphere SDK 是一个模块化的 TypeScript 库，基于 Unicity 状态转换网络构建钱包功能。它提供 BIP39/BIP32 密钥派生、多重加密钱包、通过 wallet-api 的支付、支付请求、基于 NIP-29 的群聊、NIP-17 直消息、HD 多地址支持，以及用于 dApp 集成的 Connect 协议。支付由后端 wallet-api 进行服务端托管，密钥本地保留，Nostr 仅用于消息，付款则通过 wallet-api 渠道。其 API 围绕 Sphere.init、sphere.payments、sphere.communications 和 sphere.groupChat 等构成。CLI 以独立包形式提供。该 SDK 面向在 Unicity 网络上的自主经济代理，其 payment rail 依赖 Unicity 的 wallet-api 后端和 token engine。
该 SDK 让开发者能够创建和管理钱包，通过 BIP39/BIP32 派生密钥，可选 PBKDF2 加密，使用 sphere.payments.send、mint、receive 和 requests 执行支付，通过 NIP-17 直消息和 NIP-29 群聊使用 sphere.communications 和 sphere.groupChat 进行通信，并支持多地址管理 (switchToAddress) 和 dApp 连接 (ConnectClient/ConnectHost)。负责在引擎认证下将代币通过 wallet-api 汇入收款人的邮箱；使用 @nametag 地址解析身份。CLI (sphere) 支持自动补全的 shell 命令。其端到端流程从 createBrowserProviders 和 createWalletApiProviders 配置网络、存储和钱包传输，然后初始化 Sphere，并调用发送、接收或群组 API。
- 希望为代理增加链上身份、钱包和支付能力，并需要密钥本地保管的应用开发者。
- 需要自我托管支付能力，无需本地存储，依赖后端 wallet-api 作为代币托管的代理服务商。
- 在 Unicity 网络上要求私密、快速且引擎验证转账的自主商务代理。
- 通过 NIP-29 群聊、NIP-17 直消息和支付请求，为代理提供综合协作功能（如订单下单）。
- 希望使用该 SDK 与 Unicity 钱包交互的 dApp 开发者，借助浏览器扩展 (ConnectClient/ConnectHost) 实现连接。
- 使用 CLI 工具在服务器环境下运维钱包、执行脚本和自动化任务的运维团队。
这个 Agent 有哪些优点和局限？
- 密钥本地生成与存储（BIP39/BIP32），密钥永不离开客户端，仅代币托管在后端 wallet-api。
- 服务端为 crash-safe 的支付，通过 engine 认证代币、可恢复 transferId 语义，避免双重支付。
- 内置群聊（NIP-29）和加密私信（NIP-17），方便代理沟通。
- 可注入的 provider 架构（StoragePort、TransportPort、OracleProvider）和可替换的支付传输，适合各种平台。
- 多地址支持（HD 钱包）和 nametag（@username）映射，为每个地址提供身份。
- 支付结算深度绑定 Unicity 网络及其 wallet-api（平台锁定），mainnet/dev 网关暂不支持 v2 协议，发送/铸造会报错。
- 需要网络和 gateway 的 API 键；testnet2 公钥公开，但 mainnet 要求秘密管理。
- 服务端托管意味着后端钱包必须可信，可被视为与本地存储相对的管控风险。
- 文档有限，仅适用于 testnet/testnet2，尚未验证 mainnet 上线。
- 虽然 SDK 面向自主代理，但没有内置 LLM 集成；开发者需自行实现代理逻辑。
如何安装或部署这个 Agent？
安装 npm 包：npm install @unicitylabs/sphere-sdk，以及在 Node.js 环境中安装 ws。对于 CLI，则安装 npm install -g @unicity-sphere/cli。
如何使用这个 Agent？
在浏览器端，按以下方式初始化 Sphere：
import { Sphere } from '@unicitylabs/sphere-sdk';
import { createBrowserProviders } from '@unicitylabs/sphere-sdk/impl/browser';
import { createWalletApiProviders } from '@unicitylabs/sphere-sdk/impl/shared/wallet-api';
const base = createBrowserProviders({ network: 'testnet', oracle: { apiKey: 'sk_ddc3cfcc001e4a28ac3fad7407f99590' } });
const providers = createWalletApiProviders(base, { baseUrl: 'https://wallet-api.unicity.network', network: 'testnet2' });
const { sphere } = await Sphere.init({ ...providers, autoGenerate: true });
然后使用 sphere.payments.send({ recipient: '@alice', amount: '1000000', coinId: 'UCT' }) 发送付款，使用 sphere.groupChat.connect() 进入群聊。如需获取帮助，可在 CLI 中运行 sphere --help。