憑據管理

憑證中心是所有外部系統金鑰的統一儲存 —— OpenAI API Key、Slack Webhook、Stripe Secret、內部 API 鑑權頭 … 都放在這裡。平台以 AES-256-GCM 加密落庫，從頭到尾都不會出現在 YAML 匯出、日誌、稽核事件。

為什麼必須走憑據中心

如果你圖方便直接把 key 寫在 YAML 裡，會有三類問題：

1. 洩露 — 導出 YAML、Git 提交、AI 助手 diff 預覽都會帶出明文 key。
2. 無法輪換 — Key 被吊銷時要手動改每一份 YAML，極易漏。
3. 無法審計 — 出問題時不知道是哪把 Key 在哪次 execution 用了。

憑據中心讓 YAML 裡只剩下"引用"，真實值在運行時才注入給對應 step。

創建一條憑據

1. 左側「憑據管理」→ 右上角「新建憑據」。
2. 填：
   • 名稱 — 全小寫 + 下劃線的短標識，YAML 裡會用它引用。例： openai_main、slack_webhook_url。
   • 類型 — api_key / oauth_token / bot_token / webhook_secret / generic。类型决定平台在 UI 上怎么展示它，对解析逻辑影响不大。
   • 值 — 寫完後不能再讀回。
   • 命名空間 — 個人 / 團隊（如果你在 Pro+ 套餐的團隊裡）。
   • 說明（可選） — 寫給自己或團隊成員看的，例："OpenAI project X 的 prod key"。
3. 保存。平臺立刻加密落庫，並在列表裡顯示為 ****abc3 這種末尾幾位的形式。

在 YAML 裡引用憑據

給 Agent 用：provider 字段

agents:
  writer:
    preset: writer
    overrides:
      model: gpt-4.1-mini
      provider: openai_main          # 凭据中心里的凭据名

provider: openai_main 告訴 Agent："調 LLM 時用憑據中心裡名為 openai_main 的這把 key"。平臺按命名空間順序解析，首次命中生效。

給 code 步驟用：credentials 列表

- id: charge_customer
  type: code
  language: node
  credentials:
    - stripe_secret                  # 声明需要这两个凭据
    - internal_api_token
  code: |
    const stripe = require('stripe')(process.env.STRIPE_SECRET);
    const internal = await fetch('https://api.mycompany.com/invoice', {
      headers: { Authorization: 'Bearer ' + process.env.INTERNAL_API_TOKEN }
    });
    // ...

說明：

• 只有在 credentials: 列表裡顯式聲明的才能讀到 —— 不會漏給其它 step。
• 解析後作為環境變量注入：憑據名 openai_main → env var OPENAI_MAIN（SCREAMING_SNAKE_CASE）。
• process.env 裡只能看到聲明的那幾個；憑據中心的其它憑據對這段 code 是不可見的。

在變量表達式裡引用

有些字段（比如 sub_workflow 的 inputs）可以直接 {{credentials.xxx}} 引用：

- id: notify
  type: sub_workflow
  module: dingyue-module-slack-deliver
  inputs:
    slack_webhook_url: "{{credentials.slack_webhook_url}}"
    message_text: "..."

同樣按命名空間順序解析。憑據值只在當前 step 的運行時生效，不會寫入 execution 快照。

命名空間與解析順序

同一個名字可以在不同命名空間裡分別存在。運行時按下面順序找，先命中先用：

1. 個人命名空間 — 你自己建的，只有你能引用。
2. 團隊命名空間 — 你所在團隊共享，所有成員能引用。僅 Team Admin 可新建 / 刪除。

Provider：把多把 Key 綁給不同業務

如果你在同一個 LLM provider（如 OpenAI）有多把 Key（test / prod / team / project X / project Y），你可以：

1. 每把 key 在憑據中心建一條（名字區分：openai_test / openai_prod_a / openai_prod_b）。
2. Agent 的 overrides.provider 字段指定用哪一把。
3. 不同 workflow 可以用不同 provider 但同一個 preset，無需複製 Agent 定義。

agents:
  expensive:
    preset: universal
    overrides:
      model: claude-opus-4-7
      provider: anthropic_team_budget     # 团队有预算的那把

  cheap:
    preset: universal
    overrides:
      model: deepseek-v3-5
      provider: deepseek_personal         # 个人账户的

Claude Code / Codex 訂閱憑證

如果 AI 助理或工作流程 Agent 使用訂閱額度模式，請在「我的憑證」中建立對應 provider：

• claude_code_oauth — Claude Code 登入所得到的 OAuth Token。
• codex_subscription — Codex CLI 登入產生的 auth.json 全文。

這些值不會儲存到 Agent/AI 助理配置裡，只在運行時暫時注入對應 CLI。

輪換與吊銷

正常輪換

1. 憑據中心 → 點某個憑據 → "更新值"。
2. 輸入新值保存。
3. 此後新發起的 execution 用新值；進行中的 execution 繼續用啟動時緩存的舊值。

緊急吊銷

懷疑憑據洩露，想立刻停用：

1. 憑據中心點該憑據 →「刪除」。
2. 所有引用它的 step 下次執行時立刻以 credential_not_found 失敗。
3. 然後去上游 provider（OpenAI / Anthropic …）revoke 真實 key。

審計

憑據的每次創建 / 更新 / 刪除 / 被引用解析失敗都會記一條審計日誌。管理員可以去「審計日誌」頁按 event_type 過濾 credential_* 查看。

引用解析成功不記日誌 —— 避免日誌爆炸。但每次 execution 詳情裡會顯示"這次 execution 解析了哪些憑據"的元數據。

常見問題

能用環境變量代替嗎？

技術上可以（通過團隊的自部署環境變量），但不推薦：

• 環境變量是進程級全局的，任何 code step 都能 process.env 讀到。憑據中心只把你聲明的幾個注入。
• 環境變量輪換要重啟服務，憑據中心即改即生效。
• 環境變量沒審計。

同事能看到我的個人命名空間憑據嗎？

不能。即使是 Team Admin 也只能看到憑據存在（列表裡），不能看值、不能在自己的 workflow 裡引用 —— 運行時解析會 miss。

OAuth 刷新怎麼辦？

對主流 OAuth provider（Google / GitHub / Slack / Notion）：refresh_token 放憑據中心，access_token 平臺自動刷新。對其它 provider 需要你在憑據裡放長期有效的 token 或自己寫刷新 code step。

下一步

• BYOK · 自帶 LLM Key — 最常見的憑據場景：配置你自己的 LLM Provider Key
• 變數與表達式 — {{credentials.xxx}} 表達式的其它細節
• 權限與角色 — 團隊命名空間的 Admin 權限是怎麼劃的