Nodejs API

简介

开发者需要在 Scriptlet Block 中调用 SDK 与 OOCANA 工作流引擎进行交互。本文档详细介绍了相关 API 的使用方法。

快速开始

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

Scriptlet 模板

下面是 Scriptlet 的模板函数，需要在函数体内编写执行代码。函数的输入和输出类型可自定义，并且支持导入第三方库。 向后续 block 传递数据，可以像普通函数一样 return 一个字典即可。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 内置大模型，可以获取 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 类型描述，帮助用户了解如何准确使用这些 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>;
}

更多用例

请参考项目Node.js 用例。

你可以将该项目克隆到本地使用 OOMOL Studio 打开，该项目的流中包含了大多数 Context API 的使用方法。