Secrets、认证与运行路径

这一页集中说明几类在编写任务区块和可复用工作流时很容易漏掉的规则：如何声明第三方 secret、如何获取 OOMOL 认证、何时优先使用 Fusion，以及如何安全处理用户可选路径。

第三方 Secret

如果一个任务需要第三方 API Key，应把它建模为 secret 接口，而不是普通字符串。

inputs_def:
  - handle: api_key
    json_schema:
      contentMediaType: oomol/secret
      type: string
    value: ${{OO_SECRET:Third Part,Third Part,Third Part_API_KEY}}

这样做的好处是：

避免把凭据当作普通文本参数处理。
能直接接入 OOMOL Studio 的 secret 管理。
降低敏感信息暴露在普通输入中的风险。

关于 UI 里的 secret 使用方式，可以继续参考通用区块设置。

OOMOL 平台认证不同于第三方 Secret

OOMOL 平台自己的认证，不应该声明为 YAML secret 接口。

应当在运行时通过上下文获取 OOMOL token：

Python: await context.oomol_token()
TypeScript: await context.getOomolToken()

当任务需要调用 OOMOL 自有服务时，应优先使用这类运行时 API。

如果 Fusion 已覆盖能力，应优先使用 Fusion

在要求用户配置第三方 API Key 之前，先确认 OOMOL Fusion 是否已经提供了你需要的能力。

适合优先使用 Fusion 的情况：

所需模型或能力已经能通过 OOMOL 服务获得。
你希望尽量降低用户配置门槛。
你希望认证走 OOMOL token，而不是引入额外外部密钥。

只有在 Fusion 明确不覆盖该需求，或者任务确实依赖用户自己的外部账户时，才更适合要求第三方 secret。

如果你想看具体 SDK 写法，可以继续参考 Fusion SDK 概览、Fusion SDK TypeScript 文档和 Fusion SDK Python 文档。

面向用户的路径接口

路径类接口通常是面向用户的，尤其是输出目录、保存位置、可选工作目录这类场景。

更安全的默认模式通常是：

只有在它确实可选时，才把路径接口设计成可选。
不要使用虚假的占位路径。
当用户留空时，在运行时代码中回退到当前会话目录。

YAML 示例：

inputs_def:
  - handle: output_dir
    json_schema:
      type: string
      ui:widget: dir
    nullable: true

运行时路径回退

如果一个可选路径没有填写，可以在代码里回退到当前运行的 session 目录。

TypeScript 示例：

export default async function main(inputs: { output_dir?: string | null }, context: { sessionDir: string }) {
  const outputDir = inputs.output_dir || context.sessionDir;
  return { output_dir: outputDir };
}

Python 示例：

async def main(inputs, context):
    output_dir = inputs.get("output_dir") or context.session_dir
    return {"output_dir": output_dir}

这种模式可以让 YAML 契约保持简单，同时仍然允许高级用户显式覆盖输出位置。

常见错误

错误做法	更好的做法
明明 Fusion 已覆盖能力，却仍然要求用户配置外部模型 key	优先使用 Fusion 和 OOMOL 认证
把 OOMOL 平台认证声明为 YAML secret	在运行时从 context 获取 token
把第三方 API Key 建模为普通字符串接口	使用 `contentMediaType: oomol/secret`
每次运行都强制用户填写输出目录	把它做成可选，并回退到 session 目录
为了通过校验而写死一个假的默认目录	保持接口可选，在代码里解析实际路径

关于 YAML 结构本身的说明，可以继续参考 Flow YAML 编写。

第三方 Secret​

OOMOL 平台认证不同于第三方 Secret​

如果 Fusion 已覆盖能力，应优先使用 Fusion​

面向用户的路径接口​

运行时路径回退​

推荐决策规则​

常见错误​