凭据管理

凭据中心是所有外部系统密钥的统一存储 —— 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 权限是怎么划的