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 儲存事件、收件匣和介面內容，否則保持專案為「私有」：
- 私有：實作簽署的 Direct v2 通知、收件匣和介面端點；在使用者的真實資料庫中持久儲存裝置金鑰、一次性隨機數、不透明參照的寄件匣以及 24 小時的參照有效期。閱讀 direct-connections.md。
- 託管：使用
request-mode-change請求變更；在 Bellwire 中等待登入使用者核准。然後建立託管結構描述、介面和擷取令牌。
-
對於私有執行時期傳遞，建立一個僅用於喚醒的令牌，將其儲存在來源應用程式的真實密碼管理器中，並在來源交易和寄件匣記錄提交後，盡力呼叫
private-wakes。Bellwire 絕不能接收標題、內容、資料、標誌 URL、專案名稱或服務主機名稱。 -
選擇顯示原語：
- 介面：即時更新狀態。閱讀 surfaces.md。
- 收件匣事件：持久歷史記錄、完成、失敗、復原或決策邊界。在私有模式下，它保留在使用者的服務中；在託管模式下，使用 event-spec.md。
-
使用穩定的介面金鑰和不透明、隨機的參照。為相同喚醒或託管寫入的重試重複使用穩定的冪等金鑰。
-
修改最小的可靠觸發點。僅在底層業務操作提交後才發送。
- 當應用程式擁有業務操作時，優先使用直接提交後的 Bellwire 呼叫。
- 當金流、商務、部署或自動化提供者是真相來源時，閱讀 webhooks.md 並添加特定提供者的 Webhook 轉接器。
-
對簽章、時間戳記、未知金鑰、竄改目標和原子性隨機數重放執行單元測試；然後執行
conformance-direct.mjs。如果資料庫無法原子性地消耗隨機數，則停止並解釋安全性阻礙。 -
執行儲存庫現有測試，外加一個重點觸發測試。切勿為了讓 Bellwire 通過而削弱業務測試。
-
透過儲存庫真實的真相來源來持久化並部署來源端的轉接器及其密碼。
-
完成一個真實的來源操作，並使用 production-verification.md 驗證寄件匣、喚醒接受、傳遞、已簽署的電話擷取和顯示結果。手動喚醒不等於生產驗證。
整合狀態
在進度和最終報告中使用這些確切邊界：
- 已設定： Bellwire 專案、結構描述、令牌、介面或測試事件已存在。這並非生產整合。
- 已整合，等待生產驗證： 來源端轉接器程式碼、執行時期密碼、重點測試和部署已就緒，但尚無真實來源操作完成此路徑。
- 生產驗證通過： 一個真實的業務操作建立了預期的事件或介面，傳遞已檢查，且任何聲稱的裝置呈現已由使用者確認。
切勿將 send-test、手動插入的介面或密碼建立描述為實際的生產整合。
指令
使用 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 是永久性的，並會級聯刪除專案的結構描述、令牌、事件、傳遞和即時介面。在執行前，請確認確切的專案 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之前，先取得使用者的明確核准。
介面規則
- 重複使用有意義的穩定金鑰，例如
sales-today、prod-api或nightly-backup。 - 在例行更新期間保留已指派的
displayOrder。僅在使用者明確要求重新排序卡片時才更改它。 - 發送準備好顯示的值。例如，在來源系統中計算收入並發送
¥2,430；Bellwire 不會從原始事件推斷業務彙總。 - 對於私有或客戶衍生的指標，偏好使用已簽署的 Bellwire Direct 端點，使卡片酬載永遠不會進入 Bellwire 儲存。
- 選擇其中一種支援的原生類型。切勿嵌入 HTML、JavaScript、Swift、CSS 或任意渲染指令。
- 對於頻繁的進度和指標更新，偏好使用介面；避免淹沒事件收件匣。
- 僅在目的地對使用者來說是預期且安全時，才使用
open_url動作。 - 專案標誌必須是公開的 HTTPS 圖片，且大小不超過 5 MB。Bellwire 會 在本機頭像和展開的豐富通知中使用它們，如果圖片遺失或無法下載，則會 回退到專案字母組合。
驗證與復原
如果設定失敗，請閱讀 troubleshooting.md。按以下順序檢查：
- API 可達性和管理令牌範圍。
- 專案 ID 和活躍的結構描述版本。
- 實際執行時期中密碼的可用性。
- 酬載類型和必填欄位。
- 穩定的
Idempotency-Key行為。 - 來源轉接器是否存在於已部署版本中，以及一個真實的來源操作。
- 事件詳細資訊、介面狀態和傳遞狀態。
- iOS 通知權限、裝置註冊，以及沙盒與生產 APNs 環境。
除非使用者要求或懷疑遭到入侵，否則切勿輪換、撤銷或更換正常工作的令牌。