@syllm/brickly-sdk 0.1.0 → 0.1.1

package/README.md

@@ -184,7 +184,7 @@ brickly-typegen
 普通 JS runtime 可以直接使用生成的 wrapper：
 
 ```js
-const { BricklyRuntime } = require('./_sdk')
+const { BricklyRuntime } = require('@syllm/brickly-sdk')
 const { textToolkit } = require('./_generated/deps')
 
 const brick = new BricklyRuntime({ brickId: 'com.example.composite' })
@@ -384,10 +384,10 @@ win.onNetwork((event) => {
 ```bash
 # 在 Brickly/ 目录下
 npm run sdk:build
-npm run sdk:sync:demo-window-lab     # Window API 实验室
 ```
 
-Brick runtime 通过 `require('./_sdk')` 加载，保持 Brick 自包含、可分发。
+Brick runtime 通过 `require('@syllm/brickly-sdk')` 加载，并在 `runtime/node/package.json`
+声明依赖。SDK 协议变更后发布新版 npm 包，Brick 升级依赖版本即可。
 
 ---
 

package/dist/api.d.ts

@@ -53,6 +53,8 @@ export interface CommandContext {
     invokeStream<TBrickId extends string = string, TCommandId extends string = string>(brickId: TBrickId, commandId: TCommandId, input?: InvokeInput<TBrickId, TCommandId>, options?: InvokeOptions): AsyncIterable<HostInvokeStreamEvent>;
     /** 打开跨 Brick 会话。会话关闭前，宿主保持目标 Brick 实例不被回收。 */
     openSession<TBrickId extends string = string>(brickId: TBrickId, options?: SessionOptions): Promise<BrickSession<TBrickId>>;
+    /** 结构化日志（SLF4J 风格），自动绑定当前调用链。 */
+    readonly log: LogApi;
     /** 子窗口与事件 API（与 brick.ui / brick.events 同源，便于在 handler 内调用）。 */
     readonly ui: UiApi;
     readonly events: EventsApi;
@@ -60,6 +62,13 @@ export interface CommandContext {
     /** 由 host.hello.config 注入的当前 Profile 配置快照。 */
     readonly config: Record<string, unknown>;
 }
+/** SLF4J 风格的结构化日志接口。 */
+export interface LogApi {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, error?: unknown, fields?: Record<string, unknown>): void;
+}
 export type CommandHandler = (ctx: CommandContext, input: unknown) => unknown | Promise<unknown>;
 export interface InvokeOptions {
     /** 目标 Brick Profile ID；不传则由宿主选择目标 Brick 默认 Profile。 */
@@ -176,6 +185,7 @@ export interface EventEnvelope {
     payload: unknown;
     sourceBrickId: string;
     publishedAt: number;
+    requestId?: string;
 }
 /** 子窗口句柄。close() 调 host.ui.closeWindow，其余方法走 host.ui.callWindow。 */
 export declare class WindowHandle extends EventEmitter {
@@ -385,6 +395,13 @@ export declare class BricklyRuntime {
     onReady(handler: () => unknown | Promise<unknown>): this;
     /** 注册 runtime.shutdown 处理逻辑；返回后 SDK 自动发送 runtime.bye 并退出。 */
     onShutdown(handler: () => unknown | Promise<unknown>): this;
+    /** 结构化日志：发送 runtime.log 到宿主，映射为当前 Trace 下的 Event。 */
+    readonly log: {
+        debug: (message: string, fields?: Record<string, unknown>) => void;
+        info: (message: string, fields?: Record<string, unknown>) => void;
+        warn: (message: string, fields?: Record<string, unknown>) => void;
+        error: (message: string, error?: unknown, fields?: Record<string, unknown>) => void;
+    };
     /** 子窗口 / UI API。 */
     readonly ui: UiApi;
     /** 事件订阅 API。 */

package/dist/api.js

@@ -7,9 +7,16 @@ const errors_1 = require("./errors");
 const runtime_1 = require("./runtime");
 const protocol_1 = require("./protocol");
 const commandScope = new node_async_hooks_1.AsyncLocalStorage();
+const eventScope = new node_async_hooks_1.AsyncLocalStorage();
 function currentCommandScope() {
     return commandScope.getStore();
 }
+function currentEventScope() {
+    return eventScope.getStore();
+}
+function currentTrace() {
+    return currentCommandScope()?.trace ?? currentEventScope()?.trace;
+}
 class BrickSession {
     transport;
     id;
@@ -78,9 +85,11 @@ class WindowHandle extends node_events_1.EventEmitter {
         if (this.closed) {
             return Promise.reject(new errors_1.BppError('INVALID_INPUT', `Window ${this.id} already closed`));
         }
-        const parentRequestId = currentCommandScope()?.requestId ?? explicitPayloadRequestId(args);
+        const parentRequestId = currentCommandScope()?.requestId ??
+            currentEventScope()?.requestId ??
+            explicitPayloadRequestId(args);
         if (!parentRequestId) {
-            return Promise.reject(new errors_1.BppError('PARENT_INVOCATION_REQUIRED', 'webContents.send() must run inside command handler or include payload.requestId'));
+            return Promise.reject(new errors_1.BppError('PARENT_INVOCATION_REQUIRED', 'webContents.send() must run inside command/event handler or include payload.requestId'));
         }
         return this.transport.hostCall({
             type: 'host.ui.callWindow',
@@ -458,7 +467,8 @@ class BricklyRuntime {
         this.brickId = opts.brickId;
         this.protocolVersion = opts.protocolVersion ?? protocol_1.PROTOCOL_VERSION;
         this.transport = new runtime_1.BppTransport(opts);
-        this.transport.on('error', (err) => this.transport.log('transport error:', String(err)));
+        this.transport.traceProvider = () => currentTrace();
+        this.transport.on('error', (err) => this.transport.logInternal('transport error:', String(err)));
         this.transport.on('message', (msg) => this.handleHello(msg));
         this.transport.on('command', (msg) => this.handleCommand(msg));
         this.transport.on('event', (msg) => this.handleEvent(msg));
@@ -480,6 +490,13 @@ class BricklyRuntime {
         this.shutdownHandler = handler;
         return this;
     }
+    /** 结构化日志：发送 runtime.log 到宿主，映射为当前 Trace 下的 Event。 */
+    log = {
+        debug: (message, fields) => this.transport.debug(message, fields),
+        info: (message, fields) => this.transport.info(message, fields),
+        warn: (message, fields) => this.transport.warn(message, fields),
+        error: (message, error, fields) => this.transport.error(message, error, fields)
+    };
     /** 子窗口 / UI API。 */
     ui = {
         createBrowserWindow: async (url, options) => {
@@ -769,6 +786,7 @@ class BricklyRuntime {
         transport.on('message', onMessage);
         transport.once('end', onEnd);
         transport.once('error', onError);
+        const trace = currentTrace();
         transport.send({
             type: 'host.invoke',
             id,
@@ -777,7 +795,8 @@ class BricklyRuntime {
             input,
             parentRequestId,
             stream: true,
-            ...(options?.profileId ? { profileId: options.profileId } : {})
+            ...(options?.profileId ? { profileId: options.profileId } : {}),
+            ...(trace ? { trace } : {})
         });
         return {
             [Symbol.asyncIterator]() {
@@ -820,7 +839,7 @@ class BricklyRuntime {
         if (this.readyHandler) {
             Promise.resolve()
                 .then(() => this.readyHandler?.())
-                .catch((err) => this.transport.log('onReady error:', errors_1.BppError.from(err).message));
+                .catch((err) => this.transport.logInternal('onReady error:', errors_1.BppError.from(err).message));
         }
     }
     handleCommand(msg) {
@@ -832,7 +851,7 @@ class BricklyRuntime {
                     fn();
                 }
                 catch (err) {
-                    this.transport.log('cancel handler error:', errors_1.BppError.from(err).message);
+                    this.transport.logInternal('cancel handler error:', errors_1.BppError.from(err).message);
                 }
             }
             return;
@@ -854,7 +873,7 @@ class BricklyRuntime {
         }
         const ctx = this.buildContext(reqId, msg.commandId, msg.invocation);
         Promise.resolve()
-            .then(() => commandScope.run({ requestId: reqId }, () => handler(ctx, msg.input)))
+            .then(() => commandScope.run({ requestId: reqId, trace: msg.trace }, () => handler(ctx, msg.input)))
             .then((result) => {
             this.transport.send({ type: 'command.result', id: reqId, result });
         })
@@ -874,30 +893,37 @@ class BricklyRuntime {
             event: msg.event,
             payload: msg.payload,
             sourceBrickId: msg.sourceBrickId,
-            publishedAt: msg.publishedAt
+            publishedAt: msg.publishedAt,
+            requestId: msg.requestId
         };
-        // 转发到 WindowHandle：window.* 事件如果 payload.windowId 命中已知窗口，路由到句柄。
-        if (msg.event.startsWith('window.')) {
-            const wid = msg.payload?.windowId;
-            if (typeof wid === 'number') {
-                const handle = this.windows.get(wid);
-                if (handle) {
-                    const subEvent = msg.event.slice('window.'.length);
-                    handle._emit(subEvent, msg.payload);
+        const dispatch = () => {
+            // 转发到 WindowHandle：window.* 事件如果 payload.windowId 命中已知窗口，路由到句柄。
+            if (msg.event.startsWith('window.')) {
+                const wid = msg.payload?.windowId;
+                if (typeof wid === 'number') {
+                    const handle = this.windows.get(wid);
+                    if (handle) {
+                        const subEvent = msg.event.slice('window.'.length);
+                        handle._emit(subEvent, msg.payload);
+                    }
                 }
             }
-        }
-        const set = this.eventListeners.get(msg.event);
-        if (set) {
-            for (const fn of set) {
-                try {
-                    fn(msg.payload, env);
-                }
-                catch (err) {
-                    this.transport.log('event handler error:', errors_1.BppError.from(err).message);
+            const set = this.eventListeners.get(msg.event);
+            if (set) {
+                for (const fn of set) {
+                    try {
+                        fn(msg.payload, env);
+                    }
+                    catch (err) {
+                        this.transport.logInternal('event handler error:', errors_1.BppError.from(err).message);
+                    }
                 }
             }
-        }
+        };
+        if (msg.requestId)
+            eventScope.run({ requestId: msg.requestId, trace: msg.trace }, dispatch);
+        else
+            dispatch();
     }
     async handleShutdown() {
         if (this.exiting)
@@ -908,7 +934,7 @@ class BricklyRuntime {
                 await this.shutdownHandler();
         }
         catch (err) {
-            this.transport.log('shutdown handler error:', errors_1.BppError.from(err).message);
+            this.transport.logInternal('shutdown handler error:', errors_1.BppError.from(err).message);
         }
         this.transport.send({ type: 'runtime.bye' });
         // 留一点时间把字节冲出去再退出
@@ -918,13 +944,13 @@ class BricklyRuntime {
         if (this.exiting)
             return;
         this.exiting = true;
-        this.transport.log('host disconnected; exiting brick runtime');
+        this.transport.logInternal('host disconnected; exiting brick runtime');
         try {
             if (this.shutdownHandler)
                 await this.shutdownHandler();
         }
         catch (err) {
-            this.transport.log('host disconnect cleanup error:', errors_1.BppError.from(err).message);
+            this.transport.logInternal('host disconnect cleanup error:', errors_1.BppError.from(err).message);
         }
         setTimeout(() => process.exit(0), 50).unref?.();
     }
@@ -985,6 +1011,7 @@ class BricklyRuntime {
             invoke,
             invokeStream,
             openSession,
+            log: this.log,
             ui: this.ui,
             events: this.events,
             platform: this.platform,

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { BricklyRuntime, BrickSession, WindowHandle } from './api';
-export type { BricklyRuntimeOptions, CommandMap, CommandContext, CommandHandler, EventEnvelope, EventsApi, InvokeOptions, PlatformApi, SessionOptions, UiApi } from './api';
+export type { BricklyRuntimeOptions, CommandMap, CommandContext, CommandHandler, EventEnvelope, EventsApi, InvokeOptions, LogApi, PlatformApi, SessionOptions, UiApi } from './api';
 export { BppTransport } from './runtime';
 export type { BppTransportOptions } from './runtime';
 export { BppError, payloadToError } from './errors';
-export { PROTOCOL_VERSION, type BppMessage, type BppMessageType, type BridgeErrorCode, type BridgeErrorPayload, type BrickUiWindowOptions, type BrickWindowMethod, type CommandInvocationContext, type HostResourceRegisterPayload, type PlatformSystemPathName } from './protocol';
+export { PROTOCOL_VERSION, type BppMessage, type BppMessageType, type BridgeErrorCode, type BridgeErrorPayload, type BrickUiWindowOptions, type BrickWindowMethod, type CommandInvocationContext, type HostResourceRegisterPayload, type PlatformSystemPathName, type TraceContext } from './protocol';
 export { generateDependencyTypes } from './typegen';
 export type { TypegenOptions, TypegenResult } from './typegen';

package/dist/protocol.d.ts

@@ -247,6 +247,10 @@ export interface BrickWindowNetworkEvent {
 }
 /** host.ui.callWindow 方法白名单。 */
 export type BrickWindowMethod = 'setBounds' | 'getBounds' | 'setPosition' | 'getPosition' | 'setSize' | 'getSize' | 'setOpacity' | 'getOpacity' | 'setAlwaysOnTop' | 'isAlwaysOnTop' | 'setIgnoreMouseEvents' | 'setSkipTaskbar' | 'setTitle' | 'getTitle' | 'setResizable' | 'setMovable' | 'setFocusable' | 'setHasShadow' | 'setBackgroundColor' | 'setVisibleOnAllWorkspaces' | 'minimize' | 'maximize' | 'unmaximize' | 'restore' | 'hide' | 'show' | 'showInactive' | 'focus' | 'blur' | 'close' | 'isDestroyed' | 'isVisible' | 'isFocused' | 'isMinimized' | 'isMaximized' | 'loadURL' | 'loadFile' | 'reload' | 'webContents.send' | 'webContents.executeJavaScript' | 'webContents.openDevTools' | 'webContents.closeDevTools' | 'setContentBounds' | 'getContentBounds' | 'setContentSize' | 'getContentSize' | 'setMinimumSize' | 'getMinimumSize' | 'setMaximumSize' | 'getMaximumSize' | 'setAspectRatio' | 'center' | 'moveTop' | 'moveAbove' | 'setFullScreen' | 'isFullScreen' | 'isNormal' | 'isModal' | 'destroy' | 'getNormalBounds' | 'isResizable' | 'isMovable' | 'isFocusable' | 'setMinimizable' | 'isMinimizable' | 'setMaximizable' | 'isMaximizable' | 'setClosable' | 'isClosable' | 'setFullScreenable' | 'isFullScreenable' | 'setEnabled' | 'isEnabled' | 'hasShadow' | 'isVisibleOnAllWorkspaces' | 'setKiosk' | 'isKiosk' | 'flashFrame' | 'setProgressBar' | 'setMenuBarVisibility' | 'isMenuBarVisible' | 'setAutoHideMenuBar' | 'isMenuBarAutoHide' | 'removeMenu' | 'invalidateShadow' | 'setRepresentedFilename' | 'getRepresentedFilename' | 'setDocumentEdited' | 'isDocumentEdited' | 'webContents.toggleDevTools' | 'webContents.isDevToolsOpened' | 'webContents.goBack' | 'webContents.goForward' | 'webContents.canGoBack' | 'webContents.canGoForward' | 'webContents.getURL' | 'webContents.getTitle' | 'webContents.setZoomFactor' | 'webContents.getZoomFactor' | 'webContents.setZoomLevel' | 'webContents.getZoomLevel' | 'webContents.copy' | 'webContents.paste' | 'webContents.cut' | 'webContents.selectAll' | 'webContents.undo' | 'webContents.redo';
+export interface TraceContext {
+    traceId: string;
+    parentSpanId?: string;
+}
 export type BppMessage = {
     type: 'host.hello';
     protocolVersion: string;
@@ -267,19 +271,24 @@ export type BppMessage = {
     payload?: unknown;
     sourceBrickId: string;
     publishedAt: number;
+    requestId?: string;
+    trace?: TraceContext;
 } | {
     type: 'host.event.publish';
     id: string;
     event: string;
     payload?: unknown;
+    trace?: TraceContext;
 } | {
     type: 'host.resource.register';
     id: string;
     resource: HostResourceRegisterPayload;
+    trace?: TraceContext;
 } | {
     type: 'host.resource.get';
     id: string;
     resourceId: string;
+    trace?: TraceContext;
 } | {
     type: 'host.invoke';
     id: string;
@@ -289,6 +298,7 @@ export type BppMessage = {
     parentRequestId: string;
     profileId?: string;
     stream?: boolean;
+    trace?: TraceContext;
 } | {
     type: 'host.invokeRoot';
     id: string;
@@ -296,6 +306,7 @@ export type BppMessage = {
     commandId: string;
     input: unknown;
     profileId?: string;
+    trace?: TraceContext;
 } | {
     type: 'host.invoke.progress';
     id: string;
@@ -316,6 +327,7 @@ export type BppMessage = {
     id: string;
     brickId: string;
     profileId?: string;
+    trace?: TraceContext;
 } | {
     type: 'host.session.invoke';
     id: string;
@@ -323,10 +335,12 @@ export type BppMessage = {
     commandId: string;
     input: unknown;
     parentRequestId: string;
+    trace?: TraceContext;
 } | {
     type: 'host.session.close';
     id: string;
     sessionId: string;
+    trace?: TraceContext;
 } | {
     type: 'host.result';
     id: string;
@@ -341,6 +355,7 @@ export type BppMessage = {
     commandId: string;
     input: unknown;
     invocation?: CommandInvocationContext;
+    trace?: TraceContext;
 } | {
     type: 'command.cancel';
     id: string;
@@ -373,6 +388,7 @@ export type BppMessage = {
     url: string;
     options?: BrickUiWindowOptions;
     parentWindowId?: number;
+    trace?: TraceContext;
 } | {
     type: 'host.ui.callWindow';
     id: string;
@@ -380,151 +396,198 @@ export type BppMessage = {
     method: BrickWindowMethod;
     args?: unknown[];
     parentRequestId?: string;
+    trace?: TraceContext;
 } | {
     type: 'host.ui.closeWindow';
     id: string;
     windowId: number;
+    trace?: TraceContext;
 } | {
     type: 'host.ui.listWindows';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.input.keyboardTap';
     id: string;
     payload: PlatformInputKeyboardTapPayload;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.input.mouseMove';
     id: string;
     payload: PlatformInputMousePointPayload;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.input.mouseClick';
     id: string;
     payload: PlatformInputMousePointPayload;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.input.mouseDoubleClick';
     id: string;
     payload: PlatformInputMousePointPayload;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.input.mouseRightClick';
     id: string;
     payload: PlatformInputMousePointPayload;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.clipboard.readContent';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.clipboard.setContent';
     id: string;
     content: PlatformClipboardContent;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screenshot.selectRegion';
     id: string;
     options?: PlatformScreenshotRegionOptions;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.captureRegion';
     id: string;
     options?: PlatformScreenCaptureOptions;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.pickColor';
     id: string;
     options?: PlatformScreenColorPickOptions;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.getPrimaryDisplay';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.getAllDisplays';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.getCursorScreenPoint';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.getDisplayNearestPoint';
     id: string;
     point: PlatformScreenPoint;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.getDisplayMatching';
     id: string;
     rect: PlatformScreenRect;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.screenToDipPoint';
     id: string;
     point: PlatformScreenPoint;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.dipToScreenPoint';
     id: string;
     point: PlatformScreenPoint;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.screenToDipRect';
     id: string;
     rect: PlatformScreenRect;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.dipToScreenRect';
     id: string;
     rect: PlatformScreenRect;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.screen.desktopCaptureSources';
     id: string;
     options: PlatformScreenDesktopCaptureOptions;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.showNotification';
     id: string;
     body: string;
     clickFeatureCode?: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.shellOpenPath';
     id: string;
     fullPath: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.shellTrashItem';
     id: string;
     fullPath: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.shellShowItemInFolder';
     id: string;
     fullPath: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.shellOpenExternal';
     id: string;
     url: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.shellBeep';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.getNativeId';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.getAppName';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.getAppVersion';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.getPath';
     id: string;
     name: PlatformSystemPathName;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.getFileIcon';
     id: string;
     filePath: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.readCurrentFolderPath';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.readCurrentBrowserUrl';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.isDev';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.isMacOS';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.isWindows';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'host.platform.system.isLinux';
     id: string;
+    trace?: TraceContext;
 } | {
     type: 'runtime.shutdown';
 } | {
     type: 'runtime.bye';
+} | {
+    type: 'runtime.log';
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    fields?: Record<string, unknown>;
+    error?: BridgeErrorPayload;
+    trace?: TraceContext;
 };
 export type BppMessageType = BppMessage['type'];

package/dist/runtime.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import type { Readable, Writable } from 'node:stream';
-import type { BppMessage } from './protocol';
+import type { BppMessage, TraceContext } from './protocol';
 export interface BppTransportOptions {
     /** Brick id，用于生成请求 id 前缀与 runtime.ready 身份。 */
     brickId: string;
@@ -37,6 +37,8 @@ export declare class BppTransport extends EventEmitter {
     private idCounter;
     private started;
     private pending;
+    /** 返回当前异步上下文中的 TraceContext，由上层 api.ts 设置。 */
+    traceProvider?: () => TraceContext | undefined;
     constructor(opts: BppTransportOptions);
     /** 启动 stdin 监听。重复调用安全。 */
     start(): void;
@@ -44,8 +46,20 @@ export declare class BppTransport extends EventEmitter {
     stop(reason?: string): void;
     /** 写一条 BPP 消息到 stdout。线程安全（Node 单线程，单次 write 是原子的）。 */
     send(message: BppMessage): void;
-    /** 写 stderr 日志。stdout 永远只写协议；Brick 身份由宿主日志中心附加。 */
-    log(...parts: unknown[]): void;
+    /**
+     * 结构化日志：发送 runtime.log BPP 消息到宿主，映射为当前 Trace 下的 Event。
+     * 有调用链上下文时自动绑定 trace；无上下文时宿主自建 noise Trace。
+     */
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, error?: unknown, fields?: Record<string, unknown>): void;
+    /**
+     * 内部诊断日志（SDK 自身错误），直接写 stderr。
+     * 供协议尚未建立或 transport 内部异常时使用。
+     */
+    logInternal(...parts: unknown[]): void;
+    private sendLog;
     /**
      * 发起一个需要等待 host.result/host.error 回复的 host.* 调用。
      * 入参省略 id（SDK 自动分配），返回 result 字段。

package/dist/runtime.js

@@ -24,6 +24,8 @@ class BppTransport extends node_events_1.EventEmitter {
     idCounter = 0;
     started = false;
     pending = new Map();
+    /** 返回当前异步上下文中的 TraceContext，由上层 api.ts 设置。 */
+    traceProvider;
     constructor(opts) {
         super();
         this.brickId = opts.brickId;
@@ -66,23 +68,60 @@ class BppTransport extends node_events_1.EventEmitter {
         const line = JSON.stringify(message) + '\n';
         this.stdout.write(line);
     }
-    /** 写 stderr 日志。stdout 永远只写协议；Brick 身份由宿主日志中心附加。 */
-    log(...parts) {
+    /**
+     * 结构化日志：发送 runtime.log BPP 消息到宿主，映射为当前 Trace 下的 Event。
+     * 有调用链上下文时自动绑定 trace；无上下文时宿主自建 noise Trace。
+     */
+    debug(message, fields) {
+        this.sendLog('debug', message, fields);
+    }
+    info(message, fields) {
+        this.sendLog('info', message, fields);
+    }
+    warn(message, fields) {
+        this.sendLog('warn', message, fields);
+    }
+    error(message, error, fields) {
+        this.sendLog('error', message, fields, error);
+    }
+    /**
+     * 内部诊断日志（SDK 自身错误），直接写 stderr。
+     * 供协议尚未建立或 transport 内部异常时使用。
+     */
+    logInternal(...parts) {
         const line = `${parts.map((p) => (typeof p === 'string' ? p : JSON.stringify(p))).join(' ')}\n`;
         this.stderr.write(line);
     }
+    sendLog(level, message, fields, error) {
+        const msg = { type: 'runtime.log', level, message };
+        const trace = this.traceProvider?.();
+        if (trace)
+            msg.trace = trace;
+        if (fields)
+            msg.fields = fields;
+        if (error) {
+            msg.error = error instanceof Error
+                ? { code: 'BRICK_ERROR', message: error.message, details: error.stack }
+                : { code: 'BRICK_ERROR', message: String(error) };
+        }
+        this.send(msg);
+    }
     /**
      * 发起一个需要等待 host.result/host.error 回复的 host.* 调用。
      * 入参省略 id（SDK 自动分配），返回 result 字段。
      */
     hostCall(msg) {
         const id = this.nextId();
+        const trace = this.traceProvider?.();
+        const merged = trace && !msg.trace
+            ? { ...msg, trace }
+            : msg;
         return new Promise((resolve, reject) => {
             this.pending.set(id, {
                 resolve: (v) => resolve(v),
                 reject
             });
-            this.send({ ...msg, id });
+            this.send({ ...merged, id });
         });
     }
     nextHostId() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syllm/brickly-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Brickly Brick Node runtime 官方 SDK",
   "license": "MIT",
   "main": "dist/index.js",
@@ -16,7 +16,6 @@
     "build": "tsc -p tsconfig.json",
     "test": "tsx --test tests/runtime.test.ts tests/api.test.ts tests/typegen.test.ts",
     "typegen": "tsx src/typegen-cli.ts",
-    "sync:demo-window-lab": "node scripts/sync-to-brick.mjs com.brickly.demo-window-lab",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {