問題排查

按"你看到的症狀"組織。快速定位到接近的一條，跟著"怎麼修"走一遍。修不了的再去「常見問題」或提工單。

執行相關

執行一直 PENDING，不變 RUNNING

先查：

1. 看「執行歷史」頂部有沒有「達到並行上限」的提示。Free 並行 1 / Pro 5 / Team 15 —— 你的同時執行數量有沒有達到上限？
2. 看這條 workflow 有沒有 manual_approval 步驟卡在最前面。
3. 讓它再等 30 秒 —— 偶發瞬時。超過 2 分鐘還 PENDING 的提工單。

執行失敗：credential_not_found

怎麼修：

1. 看 error_message 裡提示的憑據名。
2. 打開憑據中心 —— 這個名字的憑據真的存在嗎？大小寫、下劃線 / 短橫線都要一致。
3. 你是否在"團隊命名空間"裡建了憑據，但當前你是 Viewer 角色？Viewer 不能引用憑據。
4. 清單上有就是沒被解析到 —— 退出重新登錄一次刷新權限。

執行失敗：rate_limit_exceeded

原因：你或平臺的 LLM Provider 限流被觸發。

怎麼修：

1. 在失敗的 step 上加 retry 策略：

- id: call_llm
  type: single
  agent: writer
  retry:
    max_attempts: 3
    backoff: exponential
    initial_delay_ms: 2000
    retry_on: [rate_limit, http_5xx]

2. 如果經常 rate_limit，BYOK 升級 Provider 賬戶 Tier 是根本解法。
3. batch 跑很多任務時用 sub_workflow + max_parallel 控制併發。

執行失敗：timeout

原因：單個 step 超過它的 timeout 值，或整個 execution 超過 workflow 級 timeout。

怎麼修：

• code step：在 step 上顯式加 timeout 欄位（單位秒，預設 30）。
• LLM step：可能是模型生成太長；減小 max_tokens 或用更快的模型。
• 整個 workflow 慢：在頂部加 timeout 字段（單位秒，默認 3600）。

Agent 輸出空 / 不合理

先查：

1. 執行詳情 → 點這個 step → 看"Agent tool_call 歷史"，是不是被引導到了錯誤的工具。
2. 看 input 變量是不是空了 —— 上游 step 被 condition 跳過了？
3. 調整 temperature：推理 / 分類任務 0–0.3；創意 0.6–0.9。
4. task 描述加更具體的 few-shot 例子。
5. 試試換更強的 model（claude-opus-4-7 / gpt-5）。

code step 報 permission denied 或 network error

code step 在隔離沙箱裡跑，限制：

• 文件系統只讀 —— 只有 /tmp 可寫；
• 網絡只出不進（不能監聽端口）；
• CPU / 內存 / 運行時間有上限。

怎麼修：permission denied 通常是你嘗試寫 /tmp 之外的路徑 —— 改成 /tmp/something。network error 多數是沙箱封禁了你的目標 host（平臺有 egress 白名單），可提工單加白名單。

保存與編輯相關

保存時提示"YAML 與 DAG 不一致"

意味著你手改了 YAML 後不滿足 round-trip 規則。常見原因：

• 用了 camelCase 字段名（應該是 snake_case）
• 引用了已刪除的 preset 或 agent
• depends_on 指向了不存在的 step id

點"驗證"按鈕會給出精確行號 —— 按錯誤定位修。

編輯器打不開 / 一直轉圈

1. 刷新一下。通常瞬態。
2. 看狀態欄顯示"xxx 正在編輯" —— 別人拿著編輯鎖。等他 5 分鐘無操作自動釋放，或聯繫對方。
3. Admin 可以在團隊設置裡"強制解鎖"。
4. 清瀏覽器緩存 / 換瀏覽器測試。

AI 助手給的 diff 應用後驗證失敗

Ctrl / Cmd + Z 回復 —— 編輯器支援多級復原。然後把錯誤訊息 + 原 YAML 貼回給助理，它會修。

調度 / Webhook 相關

cron 到點沒觸發

1. 調度詳情頁「下次觸發時間」是否與預期一致？時區配錯是最常見原因。
2. 「最近 10 次觸發歷史」有沒有記錄？沒有的話可能是 workflow 被 Archive 或刪除了。
3. 看 workflow 的狀態 —— 是不是被 pause 了？pause 的調度仍然計數，但不會真觸發。
4. 用"立即觸發一次"按鈕手動驗證 workflow 本身沒問題。

Webhook 觸發返回 401 / 403

1. API Key 方式：Authorization: Bearer 或 X-API-Key 標頭帶的 key 對不對？key 是否已過期、是否有 WEBHOOK_TRIGGER 範圍？
2. HMAC 兼容方式：你是否用 HMAC-SHA256 对 raw body 算了签名，放 X-Webhook-Signature 头？格式是 sha256=<hex>。注意：绑定了 API Key 的 webhook 不再接受 HMAC 签名。
3. URL path 裡的 webhook ID 寫對了嗎？對應 workflow 是否被刪？

Webhook 觸發 200 但執行沒起來

200 只代表"請求被收下"，執行可能被拒絕：

• workflow 是否 pause；
• 本套餐是否達到併發 / 調度配額；
• body 映射到 variables 時校驗失敗（必填缺失 / 類型錯）。

Webhook 觸發日誌 —— 調度詳情頁「歷史」Tab，能看到平臺收到請求後解析的詳情。

審批相關

manual_approval 永遠不推通知

1. 「通知配置」頁有沒有綁定 Slack / 飛書 / 郵件任一 channel？
2. 審計日誌 → 過濾 approval_notify_failed —— 看通知為什麼發不出去（webhook url 失效？郵箱退信？）。
3. approvers 列表空時默認向"所有 Admin 及以上"通知 —— 你賬號是不是其中一個？

我批准了但工作流沒繼續

審批後工作流應該在 10 秒內繼續。超過 1 分鐘沒繼續：

1. 刷新一下執行詳情頁，是否已經是 RUNNING？
2. 系統正在忙可能排隊 30 秒 —— 等等。
3. 超過 5 分鐘提工單。

團隊 / 權限相關

切換團隊後看不到工作流

工作流是按團隊隔離的 —— 不會跨團隊顯示。確認你切對了團隊（右上角下拉）。如果是"個人"切到"團隊"，你需要在團隊裡重新建工作流或從個人移動過去。

同事說沒權限改某個工作流

他在這個團隊是 Viewer 角色嗎？Viewer 只讀。Admin 給他升到 Editor 即可。

我不是 Owner，但我想轉移我創建的 workflow

"移動到團隊"需要你在目標團隊有 Editor 以上。自己加入目標團隊即可。

支付 / 賬單

信用卡扣款失敗

1. 賬單頁 → 「重試扣款」。3 次失敗後套餐會暫時降級到 Free —— 只要你在 14 天內成功扣款會自動恢復。
2. 中國卡可能被 Stripe 風控，換支付寶 / 微信支付。

發票抬頭填錯了

次月開立發票前可以在帳單頁改抬頭。已開出的發票需要寄郵件到 billing@braidrun.com 申請作廢重開。

都試過還是不行

1. 右下角"幫助"→ 提工單。自動附上瀏覽器環境 + 最近 execution ID。
2. Enterprise 套餐 → 直接聯繫專屬 CSM。