Syllm.Brickly.Sdk 0.12.0

Syllm.Brickly.Sdk（.NET 8+）

Brickly Brick 原生 .NET runtime SDK。生产协议为 brickly.runtime.v1（loopback gRPC invoke / interact），语义与 Node / Go / Python SDK 对齐。

• 原生 Follower：C# 直接实现协议，不包装 Go DLL。
• 内嵌 gRPC server：Host 会主动拨入 Brick 进程的 BrickCommandService，SDK 用 Kestrel 在 127.0.0.1:0 起 HTTP/2 明文服务。
• framework-dependent：用户机器需要 .NET 8 运行时（含 ASP.NET Core），下载 https://dotnet.microsoft.com/download/dotnet/8.0（选 "ASP.NET Core Runtime"）。宿主要拉起 Brick 前可用 dotnet --list-runtimes 预检。

快速上手

using System.Text.Json;
using Syllm.Brickly.Sdk;

var runtime = new BricklyRuntime();

runtime.OnCommand("hello", (ctx, input) =>
{
    var name = input.TryGetProperty("name", out var value) ? value.GetString() : null;
    ctx.Info("hello", new Dictionary<string, object?> { ["name"] = name });
    return Task.FromResult<object?>(new Dictionary<string, object?>
    {
        ["message"] = "Hello, " + (name ?? "Brickly"),
    });
});

await runtime.StartAsync();        // 缺 BRICKLY_HOST_ENDPOINT 会抛 PROTOCOL_ERROR
await runtime.WaitForShutdownAsync();

StartAsync 完成注册后返回；WaitForShutdownAsync（或 DisposeAsync）负责进程存活与退出清理。

SDK 自动完成：

• 连接 BRICKLY_HOST_ENDPOINT 并注册 gRPC Runtime
• invoke / interact 命令分发
• Host 平台 / Resource / Event / Connector / Storage 客户端路由
• CancellationToken 取消信号
• OnShutdown 钩子

核心 API

BricklyRuntime（new BricklyRuntime()）

CommandContext

命令处理器签名：

public delegate Task<object?> CommandHandler(CommandContext context, JsonElement input);

返回结果或抛 BppException（保留 code 回传宿主）；其他异常映射为 INTERNAL。

跨 Brick 调用

调用方 manifest 必须在 dependencies 中声明目标 Brick 和允许调用的命令。业务代码只使用 alias，精确来源与版本由 Host 握手绑定：

runtime.OnCommand("ask", async (ctx, _) =>
{
    var openAi = ctx.Dependencies().Require("openai");
    var result = await openAi.InvokeAsync(
        "chat",
        new Dictionary<string, object?> { ["prompt"] = "hello" },
        new InvokeOptions { ProfileId = "work" });
    return result;
});

有状态交互用 InteractAsync（必须传 OnEvent），说完用 EndAsync；CallAsync 是 Interact + 半关闭的糖。

命令内长期占用：await ctx.Dependencies().Require(alias).StartAsync()，返回 StartedToolHandle（InvokeAsync / InteractAsync / CallAsync / DisposeAsync / StopAsync），跟这次 Call，return 自动放手。命令外 StartAsync 抛 PARENT_INVOCATION_REQUIRED。

资源

普通 InvokeAsync 结果保持 ResourceRef；读取先 OpenResource：

var handle = runtime.OpenResource(reference);
await using var stream = handle;             // ResourceHandle : Stream，按 gRPC 块读
var bytes = await handle.BytesAsync();       // 上限 200 MiB；更大用流式读取
await handle.SaveToAsync("out.bin");

创建：

var note = await runtime.CreateResourceAsync("hello", new ResourceCreateOptions { Name = "note.txt" });
var big = await runtime.CreateResourceFromAsync(sourceStream, new ResourceCreateOptions { Name = "large.bin" });

var writer = await runtime.CreateResourceWriterAsync();
await writer.WriteAsync(chunk);
var handle = await writer.FinishAsync();      // 幂等

单帧 1 MiB、gRPC 消息 12 MiB、整份读取 200 MiB、并发上传 8。string 默认 text/plain; charset=utf-8，byte[] 默认 application/octet-stream。

窗口

var win = await runtime.UI.CreateBrowserWindowAsync("ui/pet.html", new WindowOptions
{
    ["width"] = 480,
    ["height"] = 320,
});

var title = await win.GetTitleAsync();
await win.SetBoundsAsync(new Bounds { X = 10, Y = 20 });
var closeResult = await win.CloseAsync();     // closed | prevented | pending | not-found
unsub();                                      // IDisposable

• ctx.UI() 创建 Call 窗口（binding=call，随这次调用消失）；Runtime.UI 创建 Session 窗口（binding=session）。
• 105 个反射方法 + 2 个宿主合成方法（StartDragAsync/EndDragAsync，frameless 浮窗原生拖拽）按 specs/window-protocol.schema.json 对齐并强类型包装；win.CallAsync(method, args) 可兜底调用宿主新方法。
• win.WebContents() 提供 webContents.*；命令外发送必须带 parent（否则 PARENT_INVOCATION_REQUIRED）。
• win.On(event, handler) 订阅 closed / focus / blur / resize / ...；win.ExposeAsync(method, handler) 处理子窗 request。

快速搜索

Provider：manifest 中 commands[].provider: 'search' 标记的命令是快速搜索协议端点（只能被宿主搜索调用，不暴露普通入口），用 OnSearch 注册：

runtime.OnSearch("find-files", ctx =>
{
    IReadOnlyList<SearchResultItem> results =
    [
        new SearchResultItem
        {
            Id = "a.txt",
            Title = "a.txt",
            Activate = new SearchRouteRef
            {
                Command = "open-file",
                Input = new Dictionary<string, object?> { ["path"] = "a.txt" },
            },
        },
    ];
    return Task.FromResult(results);
});

ctx 是 SearchContext：固定入参 Query（宿主已 trim，空查询不会到达）/ Sequence / Limit / Caller，能力面复用 Platform() / Storage() / Dependencies() / CancellationToken。Activate / Actions[].Command 的路由载荷只存宿主路由表，不下发消费方。

Consumer：manifest 声明 quickSearch.consumer 后经 runtime.Platform.Search.* 调宿主搜索服务：

var resp = await runtime.Platform.Search.QueryAsync(new SearchQueryRequest { Query = "open", Limit = 8 });
var first = resp.Results.FirstOrDefault();
if (first?.Activatable == true)
{
    await runtime.Platform.Search.ActivateAsync(first.Id!);
    await runtime.Platform.Search.RunActionAsync(first.Id!, "reveal");
}

错误

throw new BppException("INVALID_INPUT", "text is required");

常见 code：INVALID_INPUT / PROTOCOL_ERROR / COMMAND_NOT_FOUND / PARENT_INVOCATION_REQUIRED / DEPENDENCY_NOT_DECLARED / CANCELLED / RESOURCE_UPLOAD_CLOSED / RESOURCE_MATERIALIZATION_TOO_LARGE / INTERNAL。错误码字符串与 Node / Go / Python 完全一致；gRPC status details 携带 brickly.runtime.v1.BrickError。

协议与版本

• 协议：brickly.runtime.v1（Protocol.ProtocolVersion）
• SDK 版本：0.12.0（Protocol.SdkVersion），与 Node / Go / Python 基线一致
• 生成绑定：buf.gen.yaml 的 csharp 插件输出到 src/Syllm.Brickly.Sdk/Grpc/Generated，由 npm run check:runtime-proto 做漂移检查（禁止手改）

构建与测试

dotnet build
dotnet test

测试自带 FakeHost（进程内假 Host：Registry / Platform / Resource / Event / Connector / BrickStorage），不依赖真实宿主。

发布

cd Brickly
node scripts/publish-dotnet-sdk.mjs 0.11.0            # 导出独立仓库 + dotnet pack + tag
node scripts/publish-dotnet-sdk.mjs 0.11.0 --dry-run  # 只校验
node scripts/publish-dotnet-sdk.mjs 0.11.0 --push-nuget --api-key <key>  # 可选推 NuGet