bellwire 是做什么的？
将仓库状态和事件连接到用户的 Bellwire 卡片、收件箱和 iPhone。新项目默认使用私有模式：Bellwire 仅传输一个不透明的唤醒信号，而手机直接从用户的 HTTPS 服务获取内容。托管存储是可选的，并且需要在 App 中获得批准。
工作流程
-
检查仓库、其密钥管理约定、测试以及应触发事件的确切成功或失败状态。
-
仅澄清代码无法回答的产品决策：通知频率、敏感值，以及是否需要高优先级中断。
-
确保
BELLWIRE_AGENT_TOKEN在跟踪文件之外可用。如果缺失，请询问用户 iOS App 中显示的六位代码，然后运行：bellwire_secret_dir="$(mktemp -d)" node <skill-dir>/scripts/bellwire.mjs bind \ --code 123456 \ --name "Mac上的Codex" \ --secret-output "$bellwire_secret_dir/agent-token"CLI 会以模式
0600创建文件，并且永远不会打印 Token。将其导入用户批准的密钥存储中而不显示它，然后删除临时文件。切勿提交它。 -
运行
list-projects，然后创建或复用 Bellwire 项目。在创建另一个项目之前搜索现有配置。切勿仅仅为了更改投递模式而创建第二个项目。 -
除非用户明确希望 Bellwire Cloud 存储事件、收件箱和 Surface 内容，否则保持项目为私有：
- 私有：实现签名的 Direct v2 通知、收件箱和 Surfaces 端点；将设备密钥、一次性随机数、不透明引用发件箱以及 24 小时引用过期时间持久化到用户的真实数据库中。阅读 direct-connections.md。
- 托管：使用
request-mode-change请求更改；等待已登录用户在 Bellwire 中批准。然后创建托管模式下的模式、Surfaces 和摄取令牌。
-
对于私有模式的运行时投递，创建一个仅用于唤醒的令牌，将其存储在源应用的真实密钥管理器中，并在源事务和发件箱记录提交后尽最大努力调用
private-wakes。Bellwire 必须永远不会收到标题、正文、数据、Logo URL、项目名称或服务主机名。 -
选择合适的显示原语：
- Surface：原地更新的当前状态。阅读 surfaces.md。
- Inbox 事件：持久化历史记录、完成、失败、恢复或决策边界。在私有模式下，它保留在用户的服务中；在托管模式下使用 event-spec.md。
-
使用稳定的 Surface 键和不透明的随机引用。为同一唤醒或托管写入的重试复用一个稳定的幂等键。
-
修改最可靠的触发点。仅在底层业务操作提交后发送。
- 当应用程序拥有业务操作时，首选直接的后提交 Bellwire 调用。
- 当支付、商务、部署或自动化提供商是数据源时，阅读 webhooks.md 并添加特定于该提供商的 Webhook 适配器。
-
对签名、时间戳、未知密钥、篡改目标和原子随机数重放运行单元测试；然后运行
conformance-direct.mjs。如果数据库无法原子性地消耗随机数，请停止并解释安全障碍。 -
运行仓库现有的测试以及一个重点触发测试。切勿为了通过 Bellwire 而削弱业务测试。
-
通过仓库真实的配置来源持久化并部署源端适配器及其密钥。
-
完成一个真实的源操作，并使用 production-verification.md 验证发件箱、唤醒接受、投递、已签名的手机获取以及显示结果。手动唤醒不算生产验证。
集成状态
在进度和最终报告中使用以下精确界限：
- 已配置： Bellwire 项目、模式、令牌、Surface 或测试事件已存在。这不算是生产集成。
- 已集成，等待生产验证： 源端适配器代码、运行时密钥、重点测试和部署已就绪，但没有真实的源操作完成整个路径。
- 生产已验证： 一个真实的业务操作创建了预期的事件或 Surface，已检查投递状态，并且任何声称的设备展示已得到用户确认。
切勿将 send-test、手动更新的 Surface 或密钥创建描述为实际的生产集成。
命令
将 scripts/bellwire.mjs 用于 API 操作。它默认使用官方托管的 API，并接受 BELLWIRE_API_URL 用于自托管安装。
bellwire_secret_dir="$(mktemp -d)"
node <skill-dir>/scripts/bellwire.mjs list-projects
node <skill-dir>/scripts/bellwire.mjs create-project --name "VideoSays" --logo-url "https://videosays.com/logo.png"
node <skill-dir>/scripts/bellwire.mjs create-wake-token --project <id> --name production --secret-output "$bellwire_secret_dir/wake-token"
node <skill-dir>/scripts/bellwire.mjs generate-reference
node <skill-dir>/scripts/bellwire.mjs send-wake --project <id> --reference <opaque-ref> --idempotency-key <stable-key>
node <skill-dir>/scripts/bellwire.mjs request-mode-change --project <id> --to hosted
node <skill-dir>/scripts/bellwire.mjs update-project --project <id> --logo-url "https://cdn.example.com/logo.png"
node <skill-dir>/scripts/bellwire.mjs set-project-order --project <id> --order 10
node <skill-dir>/scripts/bellwire.mjs delete-project --project <id>
node <skill-dir>/scripts/bellwire.mjs create-schema --project <id> --file event-spec.json
node <skill-dir>/scripts/bellwire.mjs create-token --project <id> --name production --secret-output "$bellwire_secret_dir/ingest-token"
node <skill-dir>/scripts/bellwire.mjs upsert-surface --project <id> --key prod-api --file surface.json
node <skill-dir>/scripts/bellwire.mjs list-surfaces --project <id>
node <skill-dir>/scripts/bellwire.mjs list-direct-recoveries
node <skill-dir>/scripts/bellwire.mjs set-surface-order --project <id> --key prod-api --order 20
node <skill-dir>/scripts/bellwire.mjs send-test --project <id> --file test-event.json
node <skill-dir>/scripts/bellwire.mjs event --event <event-id>
node <skill-dir>/scripts/bellwire.mjs health --project <id>
node <skill-dir>/scripts/bellwire.mjs publish-direct-connection \
--device-key-id <id> \
--agreement-public-key <base64> \
--file direct-connection.json
node <skill-dir>/scripts/conformance-direct.mjs \
--manifest direct-connection.json \
--device-key-id <id> \
--reference <known-test-reference>
运行 node <skill-dir>/scripts/bellwire.mjs --help 查看验证、撤销、删除和加密命令。返回密钥的命令需要 --secret-output；切勿将 Token 读取到聊天或命令输出中。
delete-project 是永久性的，并将级联删除项目的模式、令牌、事件、投递和实时 Surfaces。在运行之前，请确认确切的项目 ID 并要求明确的用户意图。
对于机器可读的非密钥输出，使用 --json。当添加另一个操作或诊断错误响应时，请阅读 api.md。
适配器路由
- 阅读 adapters.md 了解 Node.js、Cloudflare Worker、Shell 和 GitHub Actions 的模式。
- 在更新 Bellwire 之前，当收到 Stripe 之类的支付事件或任何第三方回调时，请阅读 webhooks.md。
- 优先使用项目现有的 HTTP 客户端。不要为单个请求添加 SDK 依赖。
- 将事件发送视为有界的副作用：设置超时、避免记录负载，并明确决定通知失败是否会影响业务操作。默认在业务操作成功后尽最大努力发送。
- 保持令牌值不出现在生成的差异、测试快照、CI 日志和错误遥测中。
私有模式规则
- 为每个引用生成至少 128 个随机位，并将其编码为 22–200 个 URL 安全字符。切勿从订单、电子邮件、任务、客户或时间戳中派生它。
- 在发送唤醒之前，将通知详细信息写入数据库支持的发件箱。引用最多在 24 小时后过期。
- 唤醒调用是有限且有界的，在提交后尽最大努力。不要因为 Bellwire 不可用而回滚真实的业务操作。
MONTHLY_SIGNAL_LIMIT_REACHED是终结性的，直到返回的 UTC 重置时间或升级。不要循环或重试它。- 私有详细信息与收件箱响应来自用户的服务，可能会在手机上缓存最多 30 天；Bellwire Cloud 永远不会收到它们。
托管事件规则
- 使用小写点分割名称，例如
payment.success、deployment.failed或agent.waiting。 - 仅包含收件箱、通知、深层链接或诊断所需的字段。
- 切勿在通知模板中引用敏感字段；API 会拒绝它。
- 使用订单 ID、部署 ID、任务 ID 或运行 ID 作为托管模式的幂等键。不要将这些标识符暴露为私有引用。
- 避免高频率的进度事件。优先选择完成、失败、恢复和需要决策的边界。
- 在请求
priority: high之前，请询问用户明确的批准。
Surface 规则
- 复用有意义的稳定键，例如
sales-today、prod-api或nightly-backup。 - 在常规更新期间保留分配的
displayOrder。仅当用户明确要求重新排序卡片时才更改它。 - 发送可供显示的值。例如，在源系统中计算收入并发送
¥2,430；Bellwire 不会从原始事件中推断业务聚合。 - 对于私有或客户衍生的指标，首选已签名的 Bellwire Direct 端点，这样卡片负载就不会进入 Bellwire 存储。
- 选择一种支持的原生类型。切勿嵌入 HTML、JavaScript、Swift、CSS 或任意渲染指令。
- 对于频繁的进度和指标更新，优先使用 Surface；避免淹没事件收件箱。
- 仅当目的地是预期的并且对用户安全时，才使用
open_url操作。 - 项目 Logo 必须是大小不超过 5 MB 的公共 HTTPS 图片。Bellwire 会在原生头像和扩展的富通知中使用它们，如果图片缺失或无法下载，则会回退到项目首字母标志。
验证和恢复
如果设置失败，请阅读 troubleshooting.md。按此顺序检查：
- API 可达性和管理令牌的范围。
- 项目 ID 和活动模式版本。
- 密钥在实际运行时中的可用性。
- 负载类型和必填字段。
- 稳定的
Idempotency-Key行为。 - 源适配器在部署版本中的存在以及真实的源操作。
- 事件详细信息、Surface 状态和投递状态。
- iOS 通知权限、设备注册以及沙箱与生产 APNs 环境。
切勿旋转、撤销或替换正在工作的令牌，除非用户提出要求或怀疑有泄露风险。