TechMoon 科技月球
WordPress、SEO 與 AI 工具實測指南
Databox CLI 開源推出：把整個資料平台交給終端機與 AI 代理
Databox 在 2026 年 11 月 9 日把分析平台包成開源命令列工具 databox-cli 正式上市，隨附十個給 Claude Code、Cursor 與 Codex 的代理技能，但方案資格在三份官方文件寫法不一，冪等鍵、主鍵與入庫輪詢是交給代理前要先懂的三層規則。
用 AI 摘要這篇文章：
Databox 在 2026 年 11 月 9 日把自家的商業分析平台包成開源命令列工具，正式登上 Product Hunt。這個名為 databox-cli 的套件讓使用者用文字指令管理資料來源、資料集、自訂指標、儀表板、使用者與帳號，安裝條件是 Node.js 18 以上，以 MIT 授權開源，並隨附十個代理技能（agent skills），讓 Claude Code、Cursor 與 Codex 這類程式代理代為操作。
不過在動手安裝前，有兩件事值得先看清楚：官方自己的三份材料在「誰能用」與「有多少功能」上互相矛盾；而這套工具真正值得注意的地方，是把代理容易犯的錯誤（重複送資料、把送出當成完成、把舊數字當成最新）變成一條條寫在文件裡、可以逐項檢查的規則。
推出的是宣傳上線，程式碼在 npm 已經八個月
Product Hunt 頁面的標語是「Your agentic analytics platform in the terminal」，上線當日排名第 3。但從 npm 的發布紀錄看，databox-cli 不是新東西：第一版 0.1.0 早在 2026 年 3 月 6 日就上架，1.0.0 在 9 月 28 日發布，從 1.0 起改為對應 Databox V2 API，最新的 1.1.0 是 10 月 26 日。11 月 9 日這場推出屬於正式的行銷上市，今天執行 npm install -g databox-cli 裝到的是 1.1.0。
時間差對讀者有實際意義：Product Hunt 討論區裡官方成員留言稱「91 個指令、14 個分類」，那是發布當下的口頭數字，會隨版本漂移。我逐條數過現行 README 的指令清單，列出來的是 95 條；說明中心的命令參考表則只收 17 條。要看自己裝的版本到底有哪些指令，以 databox --help 的輸出為準。
三份官方文件，五個對不上的地方
把 Product Hunt 發布頁、說明中心文章與 GitHub 現行 README 並列，同一個產品出現五處規格分歧：
| 項目 | Product Hunt 發布頁 | 說明中心 | 現行 README |
|---|---|---|---|
| 適用方案 | 所有 Databox 方案 | 限特定訂閱方案、限管理員 | 方案需含 API 存取，金鑰僅管理員可建 |
| 代理技能數 | 10 個 | 5 個模組 | 10 個（列有名稱） |
| 指令數 | 90+，留言稱 91 個 | 參考表列 17 個 | 清單列 95 個 |
| ask-genie 自然語言查詢 | 列為賣點 | 附完整教學 | 註明 1.0 起暫時無法使用 |
| 建立資料來源的旗標 | 未展示 | --title | --name |
資格的矛盾最值得先處理。README 寫得最保守：金鑰只有管理員能建立，而且方案必須包含 API 存取，如果帳號管理頁的 Security 區塊根本沒有出現 API key 選項，就是方案不含這項功能，或者你本來就不是管理員。說明中心的可用性標章寫「管理員、限特定訂閱方案」。Product Hunt 頁面則寫所有方案都能用，討論區還有留言稱任何方案的使用者都能建金鑰，這點與兩份官方文件衝突，我無法在不登入的情況下驗證誰對。導入前先打開自己帳號的 Security 頁面確認，比讀任何一頁行銷文案都準。
反向看，只在瀏覽器裡看儀表板、不碰 API 的 Databox 使用者完全不受這次推出影響；要留意的是本來就用腳本搬資料、或打算把匯入工作交給代理的團隊。
重送不會做兩次：冪等鍵與主鍵分層把關
代理最典型的事故是逾時之後憑直覺重送，同一批訂單就進了兩次。這套 CLI 的回應是兩個作用層次不同的機制。
--idempotency-key 處理「這次請求」。建立類與入庫類共 10 個指令支援它（含 dataset ingest、data-source create、metric create 與 user invite 等），值必須是 UUID；同一個使用者、同一帳號、同一指令、同一資源、同一輸入，在 24 小時內重用同一把鑰匙，會拿回第一次的成功回應，而非再執行一次。有兩個但書：系統只保留成功的回應，第一次就出錯時重試仍然會再跑一遍；拿同一把鑰匙送不同內容會被拒絕，回 422 錯誤碼 idempotency_key_reused，什麼都不做。換新請求就要換新鑰匙。
主鍵（primary key）處理「這筆資料」。資料集建立時指定主鍵，送入相同鍵值的列會覆寫舊紀錄，這讓補送修正過的訂單很方便；沒有主鍵的資料集每次匯入都是附加，重送同一批等於整批重複。README 在 Limits 段給了對稱的提醒：主鍵選錯，後果是把本來該分開的紀錄互相蓋掉。所以主鍵是資料身分的設計決策，與請求重送屬於不同層次，兩者不能互相替代。
送出不等於入庫：狀態要輪詢到終態
資料入庫是非同步工作。指令回傳一個入庫編號（ingestionId）只代表系統收下了這批工作，官方流程要拿著編號輪詢狀態，直到 success、failed 或 purged 三個終態之一；failed 的回應會點名個別資料列的問題，不會整批安靜地消失。官方建議的等待上限是兩分鐘，輪詢本身失敗（例如網路瞬斷）就再查一次。
逾時的處理順序有講究。單次入庫的逾時上限是 5 分鐘，逾時不表示服務沒收到，README 明寫重送前先查 databox dataset ingestions 的歷史，確認那批工作真的不存在再重送，而且重送要帶同一把冪等鍵。批次大小也有限制：單次最多 500 列、JSON 上限 10 MB，超過時 CLI 會在送出前直接拒絕；每個資料集最多 100 欄。把整份年度匯出檔丟給代理期待服務自己拆批，並不會發生。
速率同樣有帳：每把金鑰每秒 10 次、每小時 10,000 次，讀取指標數值的 metric data 另有每帳號每分鐘 30 次的上限。工具本身不做任何自動重試，碰到 429 或 409 時回應會附 Retry-After 提示，等多久、要不要重送由呼叫端自己決定。409 還分兩種：modification_in_progress 是資料集修改正在套用，等幾秒重跑就好；modification_failed 代表修改套用失敗，重試無效，要回頭重存或清除修改定義。
讀回來的數字，先檢查完整與新鮮
兩個讀取端的陷阱都寫在文件裡。多數清單指令預設只回第一頁，一般是 25 項，資料列查詢與指標下鑽是 200 列；每頁上限 100 筆（這兩類指令放寬到 1,000 列），要拿全部必須加 --all，否則代理做資產盤點時會把第一頁當成全世界。表格模式會印「第 1 頁，共 N 頁」的頁尾，JSON 模式對多數清單卻沒有頁碼資訊，腳本更容易誤判已經拿全。
另一個是同步狀態。metric data 的回應附帶 syncInfo，狀態分 synced（本次同步完成）、skipped（無須同步，用的是上次保存的值）、inProgress（同步中，數值可能缺漏或過期）、neverSynced（尚未同步過）與 failed（上次同步失敗，數字是更早存的舊值）五種。換句話說，數字有回來與數字是最新的，是兩個獨立的問題；排程產日報時把 lastSyncedAt 一起存下來，才不會拿上週的快照寫出流暢的今日趨勢。同步也可能拖長：第一次同步沒做過的指標，首次呼叫要等大約兩分鐘；同步超過系統的 150 秒上限會回 504，但同步工作仍在後台繼續，稍後再查即可。
還有一個跨日統計的邊界：活動紀錄的日期參數若只給日期、不給時間，系統以 UTC 當天的零點起算，與台灣的日期範圍差八個小時，日報跨日切點時要先確認邊界落在哪個時區。
結束代碼分流，forbidden 沒有重試的意義
給代理讀的錯誤設計分成三層訊號：
| 結束代碼 | 意義 | 代理該做什麼 |
|---|---|---|
| 0 | 成功；在確認提示回答非 y 也算 | 讀 stdout 的結果 |
| 1 | API 拒絕：4xx 或 5xx，含限流與權限不足 | 看錯誤碼分流，forbidden 找人處理 |
| 2 | 請求沒送出：壞輸入、逾時、網路失敗 | 修輸入或查入庫歷史後再送 |
| 130 | 確認提示被中斷 | 停止，回報 |
錯誤訊息永遠是 stderr 上的純文字，即使要求 JSON 輸出也不例外，stdout 在失敗時是空的，代理管線不會把錯誤當資料讀走。每個錯誤都附請求識別碼（Request ID），連逾時這種沒有回應的失敗也有 CLI 自帶的識別碼可以回報給原廠支援；需要排查時加 --verbose，每個請求與回應都會印到 stderr，而且不會印出金鑰。
其中 forbidden 值得單獨記住：它表示這把金鑰的使用者角色或資源授權不夠，README 直說重試不會有幫助，要找管理員或資源建立者處理。把這條寫進代理的錯誤處理，排程才不會整夜空轉。
權限跟著人走，代理不會拿到你沒有的權限
金鑰以使用者的角色行事，角色規則沿用 Databox 應用本身：Viewer 只能讀；建立與更新資料來源需要 Admin、User 或 Editor；刪除資料來源與資料集要嘛是管理員，要嘛是當初的建立者；組織設定、使用者管理與帳號管理類指令只有管理員能跑。任何角色的人都能發邀請，但非管理員只能邀請一般 user 角色。
多帳戶的代理商組織另有 --account-id 旗標，把指令範圍縮到指定帳號，也能用環境變數 DATABOX_ACCOUNT_ID 全域指定。對代理來說這代表權限邊界可以再縮一層：讓它只看得到某個客戶帳號，出錯的爆炸半徑就限縮在那個帳號。
金鑰與刪除：能用不等於該讓代理自己按
金鑰以 pak_ 開頭，一人一把、永不過期、以使用者本人的角色行事，要輪替就是刪掉重建，也可以限定來源 IP，清單外的 IP 一律當未驗證拒絕。金鑰存在 ~/.config/databox-cli/config.json，檔案權限僅本人可讀。有個容易踩的細節：auth login 把金鑰存進設定檔後，即使驗證失敗也會以警告結束且結束代碼仍是 0，要再跑 auth validate 才算確認可用。代理場景的建議作法是走環境變數 DATABOX_API_KEY，不把金鑰寫進指令列或提示詞。
刪除與清空類指令（delete、purge、clear）預設要互動確認，自動化時用 --force 跳過。文件特別提醒這面旗標只是執行功能，授權的責任仍在人：讓代理有權呼叫刪除，與批准它何時真的刪，是兩個不同的決定。時區指令加 --purge-data 時更會不經確認直接刪資料，這類組合不該進代理的常規權限。資料圈把操作面交給代理的腳步也不只這一家：Databricks 讓 Claude Code 與 Codex 直跑查詢，同樣把保存規則列為前置，Supabase 的 MCP 筆記本則讓代理局部重跑查詢。
十個代理技能，裝哪些照工作切
隨套件附帶的十個技能各有分工：databox-auth 管驗證、databox-organization 管組織資訊與用量、databox-data-sources 與 databox-datasets 管資料來源和資料集、databox-metrics 管指標、databox-users 管使用者、databox-accounts 管多帳戶、databox-connections 管連線權限、databox-integrations 瀏覽整合目錄、databox-billing 管方案與發票。全部安裝是 npx skills add databox/databox-cli --skill '*'，也可以單裝其中幾個。
技能本質上是告訴代理怎麼正確使用這套工具的工作規則，數量會隨版本與分類調整（說明中心就還停在五個模組的舊描述）。把能力包成技能再交給代理的做法正在擴散，Notion 3.7 的 Agent Skills 也把團隊提示詞做成跨工具技能。採用時建議照工作範圍安裝：只做匯入的排程不需要 billing 技能，這與前一段縮小權限邊界是同一個原則。
現在做什麼：三種情況分流
帳號是管理員且方案含 API：先做唯讀盤點（data-source list --all、dataset get），再用少量測試資料建一個帶主鍵的資料集，把入庫輪詢跑完整一圈，確認驗收流程能判斷終態後，才談正式報表的自動寫入。不確定方案資格：先到帳號管理頁看 Security 區塊有沒有 API key 選項，沒有就是沒資格，安裝工具不會變出權限。想讓代理接手：技能裝好後，從唯讀技能開始試，寫入與刪除分開核准，並要求代理每次回報請求識別碼與入庫編號當驗收證據。
還沒確定的事與這篇的保存期限
免費方案能否建立 API 金鑰，官方文件與 Product Hunt 留言各說各話，本文以官方兩份文件為準標記為未確認，讀者用自己帳號的 Security 頁面幾分鐘內就能驗證。指令與技能的數量會隨版本變動，91、95、10、5 這些數字以本文查核日為準。ask-genie 自然語言查詢何時回到 CLI、代理技能對 Cursor 與 Codex 的相容細節，官方只列了工具名稱沒有細節。建議的回查時點是下一個版本發布或三份文件同步之後；超過兩週未回查，這篇的數字請當歷史資料看。
