Node.js API

简介

开发者会在 Scriptlet Block 中调用 SDK，与 OOCANA 工作流引擎交互。本文档主要介绍常用 API 及其使用方式。

提示

如果你的 block 需要调用 Fusion 托管能力，应该使用 oomol-fusion-sdk，并通过 token: await context.getOomolToken() 和 baseUrl: context.fusionApiUrl 初始化。

可继续参考 Fusion SDK 概览和 Fusion SDK TypeScript 文档。

快速开始

在 Scriptlet Block 中使用 SDK 时，需要导入 Context 对象，并通过该对象调用相关 API。

`Scriptlet` 模板

下面是 Scriptlet 的标准模板函数。你需要在函数体内编写执行代码，输入输出类型也可以按需自定义，并支持导入第三方库。如果要向后续 block 传递数据，像普通函数一样返回一个对象即可。OOCANA 会把第一层 key 视为对应的输出 handle，value 则是这个 handle 的输出值。

import type { Context } from "@oomol/types/oocana";

type Inputs = {
  input: unknown;
};
type Outputs = {
  output: unknown;
};

export default async function (
  params: Inputs,
  context: Context<Inputs, Outputs>
): Promise<Outputs> {
  // 你的代码写在这里
  // OOCANA 会向下游 block 传递一个 output，值为 null。
  // 注意：undefined 会在 JSON 序列化时被忽略，相当于这个 key 不会被传递。
  return { output: null };
}

常用 API

常用的 API 列表如下：

  /** 报告区块已完成，同时发送数据，或者错误信息。 */
  readonly finish: (
    arg?: { result?: any; error?: never } | { result?: never; error?: unknown }
  ) => Promise<void>;
  /** 报告单个数据 */
  readonly output: (handle: string, value: any) => Promise<void>;
  /** 一次性发送多个数据，参数结构为 key value，key 就是对应的输出数据名称 */
  readonly outputs: (map: Partial<TOutputs>) => Promise<void>;
  /** 启用预览 */
  readonly preview: (payload: PreviewPayload) => Promise<void>;
  /** 每次任务的临时目录， 用户可以用来存储临时文件 */
  readonly sessionDir: string;
  /** 报告进度，进度0~100，该函数有节流效果，每300ms触发一次。 */
  readonly reportProgress: (progress: number) => Promise<void>;
  /** 获取当前 OOMOL token，用于调用 Fusion 等 OOMOL 自有服务 */
  readonly getOomolToken: () => Promise<string>;
  /** 当前运行时的 Fusion API base URL */
  readonly fusionApiUrl: string;
  /** 获取 OOMOL 内置大模型，可以获取 base_url api-key model-list */
  readonly OOMOL_LLM_ENV: OOMOL_LLM_ENV;
  /** 获取本地设备的 GPU 信息，以便调用相应的硬件加速库 */
  readonly hostInfo: HostInfo;

`Context.preview` Types

context.preview 是核心 API 。它的主要功能是帮助开发人员预览数据。我们支持几乎所有常用数据的预览。

`PreviewPayload` Types

函数名称：context.preview

    readonly preview: (payload: PreviewPayload) => Promise<void>;

参数类型：PreviewPayload

type PreviewPayload =
  | {
      type: "video" | "audio" | "markdown" | "iframe" | "html";
      data: string;
    }
  | {
      type: "json" | "text" | `text/${string}`;
      data: any;
    }
  | {
      type: "image";
      data: string | string[];
    }
  | {
      type: "table";
      data: {
        columns: Array<string | number>;
        rows: Array<Array<string | number | boolean>>;
        row_count?: number;
      };
    };

`Preview` 例子

await context.preview({
  type: "video",
  data: "https://www.youtube.com/watch?v=6g4dkBF5anU",
});

`Context` 对象的详细类型

OOCANA SDK 提供了下面这些 API 类型定义，帮助开发者准确理解和使用接口。实际编写时，也可以直接借助编辑器里的类型提示。

interface Context<
  TInputs = Record<string, any>,
  TOutputs = Record<string, any>,
> {
  readonly sessionId: string;
    readonly jobId: string;
    readonly block_path: string;
    readonly stacks: readonly BlockJobStackLevel[];
    readonly inputs: TInputs;

    /** 报告单个区块输出数据 */
    readonly output: {
      /**
       * @param handle 输出数据名
       * @param output 输出值
       */
      <THandle extends Extract<keyof TOutputs, string>>(
        handle: THandle,
        output: TOutputs[THandle]
      ): Promise<void>;
    };

    /**
     * 报告区块输出，可以一次性报告多个输出。
     * @param map map 可以是 TOutputs 的部分对象
     * @returns
     */
    readonly outputs: (map: Partial<TOutputs>) => Promise<void>;

    /**
     * 报告区块完成，可以包含错误或结果。
     * 如果包含 error，则视为区块失败并忽略 result 参数；
     * 如果包含 result，则视为成功；
     * 否则视为成功但不报告结果。
     */
    readonly finish: (
      arg?: { result?: any; error?: never } | { result?: never; error?: unknown }
    ) => Promise<void>;

    /** 报告日志 */
    readonly logJSON: (jsonValue: unknown) => Promise<void>;

    /** 报告错误 */
    readonly error: (error: unknown) => Promise<void>;

    /** 报告额外的区块消息 */
    readonly sendMessage: (payload: unknown) => Promise<void>;

    /** 发送预览数据 */
    readonly preview: (payload: PreviewPayload) => Promise<void>;

    /** 报告区块的 stdio 和 stdout 消息 */
    readonly reportLog: (
      payload: string,
      stdio: "stdout" | "stderr"
    ) => Promise<void>;

    /** 整个会话的临时目录，所有区块共享同一个目录 */
    readonly sessionDir: string;

    /** 报告进度，进度范围 0 ~ 100，该函数有节流效果，每 300ms 触发一次 */
    readonly reportProgress: (progress: number) => Promise<void>;
    /** 获取当前 OOMOL token，用于调用 Fusion 等 OOMOL 自有服务 */
    readonly getOomolToken: () => Promise<string>;
    /** 当前运行时的 Fusion API base URL */
    readonly fusionApiUrl: string;
}

简介​

快速开始​

Scriptlet 模板​

常用 API​

Context.preview Types​

PreviewPayload Types​

Preview 例子​

Context 对象的详细类型​

更多用例​

简介