BroSettlement API
使用所选环境的当前 Swagger 作为事实来源。生产环境是默认环境：
- 生产环境 Swagger UI: https://brosettlement-api.brolabel.io/swagger-integration
- 生产环境 Swagger JSON: https://brosettlement-api.brolabel.io/swagger-integration-json
- 测试环境 Swagger UI: https://brosettlement-staging-api.brolabel.io/swagger-integration#/
- 测试环境 Swagger JSON: https://brosettlement-staging-api.brolabel.io/swagger-integration-json
除非用户明确选择了测试环境，或者调用的入门引导技能从 app-staging.brolabel.io 推导出了测试环境，否则使用生产环境。切勿在不同环境之间混用凭据、Swagger、REST 或 WebSocket 端点。
在设计或更改集成之前，请阅读 references/api.md。
凭据协议
优先使用现有的 API 密钥。仅询问以下信息：
- API 密钥 ID；
- 用户机器上已存储的匹配 Ed25519 私钥 PEM 文件的绝对路径；
- 确认该密钥具有所需的作用域，并且 API 密钥页面上显示的所有必需设置均已完成。
切勿要求用户将私钥、密码、JWT、TOTP 代码或会话令牌粘贴到聊天中。 请勿询问用户的外向公共 IP 或调用 IP 发现服务；请引导用户查看 API 密钥页面上显示的当前网络和允许列表说明。 切勿登录控制台或调用 API 密钥 CRUD 端点来创建、编辑、轮换或吊销密钥。 如果需要新密钥，仅在获得所需确认后生成本地 Ed25519 密钥对，仅显示公钥，并提供手动控制台说明。等待用户确认密钥创建、作用域、允许列表和激活状态均已就绪。
在运行时通过 BROSETTLEMENT_API_KEY_ID 和 BROSETTLEMENT_API_PRIVATE_KEY_FILE 加载现有凭据。使用 BROSETTLEMENT_ENVIRONMENT=production|staging 选择端点；未设置值表示生产环境。不要将凭据值复制到源文件、提示、生成的示例或 shell 历史记录中。
工作流程
- 准备捆绑的 CLI 并按如下所述运行其自动版本门控。此操作可能仅更新已编译的 CLI 可执行文件；切勿更新
SKILL.md、参考资料、脚本或同级技能。 - 默认为生产环境并明确说明。仅当显式选择或从测试环境控制台主机名推导出时，才使用测试环境。
- 在回答端点、命令、字段、枚举、作用域或错误模式问题之前，获取当前 Swagger JSON。
- 确定确切的操作、请求模式、响应模式、所需作用域、身份验证标头、正文哈希要求和幂等性要求。
- 通过凭据协议解析凭据并验证先决条件，同时不打印秘密信息。
- 准备一份经过编辑的请求计划：环境、方法、确切目标、作用域、正文来源、幂等性行为以及预期的成功响应。当调用技能定义了授权的教程流程时，将其保留在内部或用一句话总结；当用户请求或在其他变更操作之前，显示完整计划。
- 在存在适用的只读作用域时，在首次变更操作之前运行一次安全的只读身份验证探测。
- 序列化请求正文恰好一次，并对将要发送的确切字节进行哈希处理。
- 使用确切请求目标（包括原始查询字符串）构建规范字符串。
- 在状态更改请求之前立即请求确认，除非调用技能已捕获明确且范围狭窄的常设授权。特别是，
$brosettlement-onboarding可以授权一个测试环境/测试网账本账户和一个链接的测试环境/测试网钱包，作为所请求教程的一部分。此例外绝不涵盖 MPC 初始化、提现、签名、生产环境/主网活动、破坏性操作或其他资源。 - 使用所有必需的标头，对已确认的请求进行签名并发送一次。
- 验证 HTTP 状态并使用文档化的错误模式解析错误。
- 通过读取端点以及（相关时）WebSocket 事件验证生成的资源或生命周期。
- 对于不确定的结果，在重试之前读取资源或状态。仅对完全相同逻辑的请求重用相同的幂等键。
- 报告操作、目标环境、状态、经过净化的 API 响应、标识符和验证结果，而不暴露秘密信息。创建操作后，回读资源，并且仅在验证成功时才明确声明成功。
规范签名不变量
对于 REST，使用恰好六个以换行符分隔的字段：
METHOD、EXACT_REQUEST_TARGET、BODY_HASH、TIMESTAMP、NONCE 和 API_KEY_ID。
- 保留确切的原始查询字符串；切勿去掉
?之后的所有内容。 - 将
API_KEY_ID作为第六行；切勿使用已过时的五行格式。 - 对 HTTP 客户端发送的相同序列化正文字节进行签名。
- 将
X-Idempotency-Key保留在规范字符串之外。 - 切勿重复使用 nonce。
- 将
WS_CONNECT视为独立的四行 WebSocket 规范；切勿重用 REST 签名逻辑。
如果无法使用捆绑的 Go 客户端，请在用户使用的语言中实现这些相同的不变量，并在任何实时变更操作之前，使用固定的时间戳/nonce 测试向量进行本地验证。请勿从其他技能或文档复制签名算法，除非它与所选环境的当前 Swagger 以及此技能中当前特定于操作的要求相匹配。
使用捆绑的 CLI
使用统一的 Go CLI 作为默认执行接口。在首次请求或当二进制文件丢失时，从捆绑的源代码构建它：
./scripts/build-cli.sh
在激活此技能的每个请求开始时，在任何 BroSettlement API 操作之前，运行恰好一次自动更新检查：
./scripts/go/bin/brosettlement update --auto
./scripts/go/bin/brosettlement version
更新程序仅接受来自官方仓库的已发布 cli-vMAJOR.MINOR.PATCH 格式的 GitHub Release，选择当前操作系统/架构的二进制文件，验证 checksums.txt 和任何 GitHub SHA-256 资产摘要，验证下载的 CLI 报告的版本，并以原子方式替换当前可执行文件。它绝不能拉取、克隆、重写或更新技能内容。
如果 GitHub 不可用、尚未发布 CLI release、平台不受支持、校验和失败或可执行文件目录不可写，请简要报告跳过的更新，并在已安装的 CLI 支持所需命令的情况下继续使用。切勿削弱校验和或来源验证以完成更新。
仅将 cmd/list-commands、cmd/api-request 和 cmd/ws-listener 保留为向后兼容的入口点。当统一 CLI 可用时，请勿使用临时 Shell 命令组装签名。
向用户展示命令
在聊天中教授或返回可重用命令时，使用可移植的 @brosettlement 命令接口，而不是暴露技能的内部可执行路径。按以下形式展示命令：
# 完整命令列表
@brosettlement commands
# 按主题搜索
@brosettlement commands wallets
@brosettlement commands "ledger balance" --json
# 已签名的 REST 请求
@brosettlement api GET '/api/v1/wallets'
# MPC 状态
@brosettlement mpc status
# WebSocket
@brosettlement websocket listen --stop-after 30s
将 @brosettlement 视为由已安装技能处理的用户端调用。实际执行操作时，将其解析为捆绑的已验证 CLI 所在路径 ./scripts/go/bin/brosettlement（或等效的绝对安装路径）。仅在直接 Shell 故障排除、构建、更新或用户代理不支持 @brosettlement 命令接口时，才显示本机路径。
回答 API 命令问题
每当用户询问可用内容或按主题查找操作时，使用 Go 命令列表器。它每次运行时都会获取 Swagger。
./scripts/go/bin/brosettlement commands
./scripts/go/bin/brosettlement commands wallets
./scripts/go/bin/brosettlement commands "ledger balance" --json
返回匹配的 HTTP 方法、路径和 Swagger 摘要。然后在生成负载或代码之前，检查 Swagger JSON 中的选定操作。当实时测试环境 Swagger 可访问时，不要仅依据捆绑的端点快照作答。
发送已签名的 REST 请求
优先使用 Go 请求客户端：
export BROSETTLEMENT_API_KEY_ID="<uuid>"
export BROSETTLEMENT_API_PRIVATE_KEY_FILE="/secure/path/private.pem"
./scripts/go/bin/brosettlement api GET '/api/v1/wallets'
./scripts/go/bin/brosettlement api POST '/api/v1/wallets' \
--body-file /secure/path/create-wallet.json \
--confirm
该客户端对确切目标和正文字节进行签名，为 Swagger 当前文档化的操作添加所需的空正文哈希和幂等键，发送请求，并打印结构化响应。GET、HEAD 和 OPTIONS 直接运行。其他所有方法都需要 --confirm。仅在获得明确授权后提供：即立即的用户确认或由调用技能定义的常设授权。入门引导例外仅涵盖一个测试环境/测试网账本账户和一个链接的测试环境/测试网钱包；它不会移除 CLI 保护措施或授权任何其他变更操作。
对于 POST /api/v1/mpc/initialize，请完全遵循所选环境的当前操作合约。已验证的生产环境和测试环境合约当前要求：
- 发送确切的 JSON 正文
{}（两个字节），并带有Content-Type: application/json； - 将
X-Api-Body-Hash和规范字符串的BODY_HASH行设置为44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a； - 切勿发送长度为零的正文或重新格式化负载。
受保护的 mpc initialize 命令自动提供 {}。在不确定的结果之后，不要重试其他正文/哈希组合；首先检查 GET /api/v1/mpc/status，并且仅对相同的逻辑初始化重用相同的幂等键。
在入门引导期间使用受保护的便捷命令：
./scripts/go/bin/brosettlement mpc status
./scripts/go/bin/brosettlement mpc initialize \
--idempotency-key '<stable-key-for-this-initialization>' \
--confirm
当仅需要签名标头时，无依赖的 Node.js 标头生成器仍然可用：
使用 scripts/sign-request.mjs 从确切的方法、请求目标和可选的正交文件生成请求标头：
BROSETTLEMENT_API_KEY_ID="<uuid>" \
BROSETTLEMENT_API_PRIVATE_KEY_FILE="/secure/path/private.pem" \
node scripts/sign-request.mjs \
--method POST \
--target /api/v1/wallets \
--body-file /tmp/request.json \
--idempotency-key "<stable-key-for-this-logical-request>"
发送来自 --body-file 的相同字节；在签名后重新格式化 JSON 会使正文哈希和签名无效。
如果文档化的操作需要幂等性且省略了 --idempotency-key，则生成器会添加 req-<nonce>。在准备可能重试的请求时，传递显式的稳定键。
监听 WebSocket 事件
使用 Go 监听器：
export BROSETTLEMENT_API_KEY_ID="<uuid>"
export BROSETTLEMENT_API_PRIVATE_KEY_FILE="/secure/path/private.pem"
./scripts/go/bin/brosettlement websocket listen \
--log-path ./brosettlement_ws_listener.log
对于限时的冒烟测试：
./scripts/go/bin/brosettlement websocket listen --stop-after 30s
监听器使用独立的 WS_CONNECT 规范字符串，在失败后重连，并将结构化的 JSON 行写入标准输出和受保护的本地日志。切勿记录已签名的 WebSocket URL，因为其查询包含身份验证材料。
安全规则
- 切勿发明端点、字段、作用域、网络标识符或状态值。
- 切勿暴露或请求私钥，当公钥、密钥 ID、签名或经过净化的诊断信息足够时。
- 切勿请求密码、JWT、TOTP 代码或已验证的控制台会话来管理 API 密钥。
- 切勿为用户创建、编辑、轮换或吊销 API 密钥；API 密钥管理仅限用户操作。
- 切勿记录可能包含敏感查询参数的规范字符串。
- 将生产环境和测试环境视为不同的 API 环境，将测试网和主网视为不同的区块链目标。生产环境是默认的 API 环境，但主网活动仍需要明确授权。
- 将创建、提现、MPC 初始化和签名操作视为状态更改。在执行它们之前确认目标资源和环境。
- 在检查现有结果之前，不要使用新的幂等键重试未知结果后的变更操作。
- 不要仅凭 HTTP 请求就声称成功；验证生成的资源或最终生命周期状态。
WebSocket
REST 和 WebSocket 签名格式不同。在 API 参考中使用 WebSocket 规范格式，并要求 websockets:read。按事件 ID 幂等地消费事件，容忍重复和重连，在支持时持久化游标，并针对 REST 资源和账本记录调和事件。