OpenRobot.Litegraph.Cloud 1.0.0

OpenRobot.Litegraph.Cloud

Litegraph 云端对接（net8.0）：取云端流程 → 交给 OpenRobot.Litegraph.Core 装配 → 灌元数据 → 落本地备份， 以及把执行概要回存云端。传输层留一条缝，进程直连或经宿主通道转发都能用。

• 一条缝，两种传输：6 个云端接口的实现只写一遍（LitegraphCloudClientBase）， 传输由子类决定 —— HttpLitegraphCloudClient 直连，ForwardedLitegraphCloudClient 交给宿主的 ILitegraphApiForwarder。上层（加载器 / 回存器）不认识传输方式。
• 失败收敛成数据：任何一条云端流程失败都不抛，返回 GraphLoadResult（错误码 E009）， 与本地 LoadDirectory 的契约一致 —— 宿主把两边结果并进同一个列表即可。
• 引擎吃原始画布：GetContext 返回的字符串直接喂给 LitegraphService.Load，不做中间转换； 本地备份是旁路动作，不会被回读，删掉也不影响执行。
• 不绑传输栈：包内不引任何转发框架，ILitegraphApiForwarder 只描述 「方法 / 地址 / query / 请求体 → 原始响应」。Microsoft.Extensions.* 停在 8.0.x，与 .NET 8 宿主一致。

安装

<PackageReference Include="OpenRobot.Litegraph.Cloud" Version="1.0.0" />

包由本仓库产出：

dotnet pack Litegraph/OpenRobot.Litegraph.Cloud/OpenRobot.Litegraph.Cloud.csproj -c Release

依赖：

• OpenRobot.Litegraph.Common 1.0.0
• OpenRobot.Litegraph.Core 1.0.0（传递 OpenRobot.Framework.Modularity 1.0.0）
• Microsoft.Extensions.Logging.Abstractions 8.0.2（经 Modularity 传递）

本包不引 Microsoft.AspNetCore.SignalR.Client、OpenRobot.Framework.WebApiProxy 一类转发框架。 宿主若要经自己的 Web 代理出网，实现 ILitegraphApiForwarder 即可 —— 把这类依赖加在宿主上，别加在包里。

快速开始

配置写在宿主 appsettings.json 的顶层 LitegraphCloud 节：

{
  "LitegraphCloud": {
    "BaseUrl": "http://192.168.1.10:9900",
    "ProjectId": 1,
    "TimeoutMs": 15000,
    "BackupEnabled": true,
    "BackupDirectory": "assets/remote"
  }
}

直连：拉取并装配

using OpenRobot.Litegraph.Cloud;

var cloudOptions = LitegraphCloudOptions.Load();
if (!cloudOptions.IsConfigured)
    return;                                     // BaseUrl 为空 = 不启用云端对接

using ILitegraphCloudClient client = new HttpLitegraphCloudClient(cloudOptions, logger);
var loader = new CloudGraphLoader(client, cloudOptions, logger);

// service 是已装配的 LitegraphService；graphId 直接用 flowId，重新拉取不会产生第二张图
var results = loader.LoadMany(service, new[] { "3f2b9c41-…", "9c11d7a0-…" });

foreach (var result in results)
{
    if (!result.Success)
        logger.LogError("云端图 {File} 加载失败：{Code} {Message}",
            result.File, result.Error!.Code, result.Error.Message);
}

接进模块宿主时，把加载挂到 LitegraphModule.AdditionalGraphLoader —— 它在引擎 Start 之前执行， 这样云端图也能拿到主流程的周期 tick：

var module = new LitegraphModule(logger);
module.AdditionalGraphLoader = service => loader.LoadMany(service, flowIds);

转发：宿主提供出网通道

设备端只允许一个进程出网时，子应用不要自己开 HttpClient，实现传输缝即可：

public sealed class HostApiForwarder : ILitegraphApiForwarder
{
    public async Task<LitegraphApiForwardResult?> RequestAsync(
        string method,
        string url,
        IReadOnlyList<(string Key, string? Value)> query,
        object? body,
        CancellationToken cancellationToken)
    {
        // 交给宿主自己的出网通道；没拿到回传（超时 / 未连接）就返回 null，
        // 拿到了但服务端判失败 → Success = false，
        // 否则 Data 就是响应体原文（含 ABP 信封）
        return await _channel.SendAsync(method, url, query, body, cancellationToken).ConfigureAwait(false);
    }
}

using ILitegraphCloudClient client = new ForwardedLitegraphCloudClient(forwarder, cloudOptions, logger);

回存执行概要

var publisher = new CloudArtifactsPublisher(client, logger);

// ⚠️ 必须在模块 Shutdown 之前调用：Shutdown 会清空 Service 与 LoadResults
var pushResults = await publisher.PushAsync(service, flowIds, cancellationToken);

foreach (var r in pushResults.Where(r => !r.Ok))
    logger.LogWarning("流程 {FlowId} 回存失败：{Detail}", r.FlowId, r.Detail);

API 速查

客户端

编排器

配置

信封与 DTO

已知限制

1. LitegraphCloudOptions 不是凭据容器：AuthToken 对应的接口在云端已放开为匿名，正常不需要填； 确需填写时请走环境变量或本地未入库的配置，不要把 token 写进被提交的 appsettings.json。
2. GetContextAsync 返回空串不是错误：那表示「流程存在但还没画过画布」。CloudGraphLoader 会把它 转成 E009（"先去云端设计器保存一次"），以便与网络故障区分开；直接调客户端时要自己判空。
3. CloudGraphLoader 是同步阻塞的：它被设计成挂在 LitegraphModule.AdditionalGraphLoader 上， 而那个钩子的签名就是同步的 —— 网络抓取发生在模块初始化的同步路径上，只适合轻量宿主。
4. 参数名大小写是照抄云端的：Get 用 FlowId（大写 D），GetContext 用 flowId（小写 d）。不要统一。
5. 备份不是归档：默认写到 bin/…/assets/remote，dotnet clean 或重新发布就没了 —— 云端才是权威。
6. PushAsync 必须在 Shutdown() 之前：Shutdown 会置 Service = null 并清空 LoadResults，之后连概要都拿不到。

版本历史

1.0.0（首次发布）

• ILitegraphCloudClient 6 个云端接口 + ABP 信封解析与自动翻页
• HttpLitegraphCloudClient（直连）与 ForwardedLitegraphCloudClient（宿主转发），共用 ILitegraphApiForwarder 传输缝
• CloudGraphLoader：拉取 → 装配 → 灌元数据 → 落备份，逐条失败收敛为 GraphLoadResult
• CloudArtifactsPublisher：回存执行概要，逐条返回 ArtifactPushResult
• LitegraphCloudOptions（LitegraphCloud 顶层节）