@arronqzy/blueprint-dsl 1.0.1 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/blueprint-dsl",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Abuilder blueprint DSL runtime",
   "license": "MIT",
   "files": [
@@ -16,8 +16,8 @@
   "devDependencies": {
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
-    "@arronqzy/typescript-config": "1.0.0",
-    "@arronqzy/eslint-config": "0.0.0"
+    "@arronqzy/eslint-config": "0.0.0",
+    "@arronqzy/typescript-config": "1.0.0"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -1,4 +1,31 @@
+# @arronqzy/blueprint-dsl
+
+Abuilder 蓝图的 **DSL 与运行时** 包，定义节点类型、行为注册与图执行逻辑，不依赖 React。
+
+## 功能概览
+
+- **节点定义**：Flow / Data 端口、节点元数据与默认行为
+- **行为注册表**：`BehaviorRegistry` 注册 JS / 内置行为
+- **执行器**：按 Token 驱动节点执行、Scope 传递
+- **图运行器**：整图调度、循环检测、执行轨迹
+- **内置节点**：逻辑判断、HTTP 请求、JSON 处理、时钟定时、Swagger 等
+- **时钟调度**：多 tick 输出、中止与活跃状态订阅
+
+## 安装
+
+```bash
+pnpm add @arronqzy/blueprint-dsl rxjs
+```
+
+## 快速开始
+
 ```ts
+import {
+  BehaviorRegistry,
+  Executor,
+  type NodeDefinition,
+} from "@arronqzy/blueprint-dsl";
+
 const behaviors = new BehaviorRegistry();
 
 behaviors.registerJS("print-js", async ({ io }) => {
@@ -6,27 +33,42 @@ behaviors.registerJS("print-js", async ({ io }) => {
   io.emitFlow("out");
 });
 
-behaviors.registerJS("sleep-js", async ({ io }) => {
-  const ms = await io.getInput("ms");
-  await new Promise((r) => setTimeout(r, ms));
-  io.emitFlow("out");
-});
-
-
 const PrintNode: NodeDefinition = {
   type: "Print",
   inputs: [{ name: "msg", kind: "data" }],
   outputs: [{ name: "out", kind: "flow" }],
-  behavior: { kind: "js", ref: "print-js" }
-}
+  behavior: { kind: "js", ref: "print-js" },
+};
 
+const executor = new Executor(behaviors);
 
 await executor.executeToken({
   tokenId: "t1",
   nodeId: "n1",
   nodeType: "Print",
   inPort: "in",
-  scope: { vars: new Map() }
-})
-
+  scope: { vars: new Map() },
+});
 ```
+
+## 核心模块
+
+| 路径 | 说明 |
+|------|------|
+| `core/behavior.js` | 行为接口与 IO |
+| `core/behavior-registry.js` | 行为注册 |
+| `core/executor.js` | 单节点执行 |
+| `runtime/graph-runner.js` | 整图运行 |
+| `runtime/execution-trace.js` | 执行轨迹 |
+| `runtime/clock-scheduler.js` | 时钟节点调度 |
+| `nodes/definitions.js` | 内置节点定义 |
+| `fetch-config.js` / `logic-config.js` 等 | 各类型节点配置结构 |
+
+## 与上层包的关系
+
+- **`@arronqzy/react-blueprint`**：React Flow 画布、调试 UI、蓝图库
+- **`@arronqzy/react-view`**：蓝图执行结果通过 Scope 驱动视图节点
+
+## 许可证
+
+MIT

package/src/behaviors/default.ts

@@ -9,6 +9,7 @@ import { BehaviorRegistry } from "../core/behavior-registry.js";
 
 const LIFECYCLE_SIGNAL_KEY = "__lifecycleSignal";
 const BLUEPRINT_ACTIVATION_INPUT_KEY = "__blueprintActivationInput";
+const UI_EVENT_PAYLOAD_KEY = "__uiEventPayload";
 
 export function registerDefaultBehaviors(registry: BehaviorRegistry) {
   registry.registerJS("logic-noop", async ({ io }) => {
@@ -41,4 +42,4 @@ export function registerDefaultBehaviors(registry: BehaviorRegistry) {
   });
 }
 
-export { LIFECYCLE_SIGNAL_KEY, BLUEPRINT_ACTIVATION_INPUT_KEY };
+export { LIFECYCLE_SIGNAL_KEY, BLUEPRINT_ACTIVATION_INPUT_KEY, UI_EVENT_PAYLOAD_KEY };

package/src/fetch-config.ts

@@ -67,6 +67,21 @@ export const DEFAULT_FETCH_REQUEST_CONFIG: FetchRequestConfig = {
   timeoutMs: 30000,
 };
 
+/** 合并默认项与节点上保存的 fetch 配置，供运行时发起请求 */
+export function normalizeFetchRequestConfig(
+  config?: FetchRequestConfig
+): FetchRequestConfig {
+  return {
+    ...DEFAULT_FETCH_REQUEST_CONFIG,
+    ...config,
+    headers: {
+      ...DEFAULT_FETCH_REQUEST_CONFIG.headers,
+      ...config?.headers,
+    },
+    swaggerEndpoints: config?.swaggerEndpoints,
+  };
+}
+
 export type FetchResultValue = {
   status: number;
   statusText: string;

package/src/runtime/graph-runner.ts

@@ -1,5 +1,9 @@
 import type { FetchRequestConfig } from "../fetch-config.js";
-import { executeFetch, DEFAULT_FETCH_REQUEST_CONFIG } from "../fetch-config.js";
+import {
+  executeFetch,
+  normalizeFetchRequestConfig,
+  resolveFetchRequestUrl,
+} from "../fetch-config.js";
 import type { JsonNodeConfig } from "../json-config.js";
 import {
   DEFAULT_JSON_NODE_CONFIG,
@@ -34,6 +38,7 @@ import {
   registerDefaultBehaviors,
   BLUEPRINT_ACTIVATION_INPUT_KEY,
   LIFECYCLE_SIGNAL_KEY,
+  UI_EVENT_PAYLOAD_KEY,
 } from "../behaviors/default.js";
 import { BehaviorRegistry } from "../core/behavior-registry.js";
 import { Executor } from "../core/executor.js";
@@ -203,6 +208,69 @@ export class BlueprintGraphRunner {
     this.cycleValidated = true;
   }
 
+  private injectedInputs = new Map<string, Value>();
+
+  /**
+   * 从视图交互触发指定蓝图节点：向该节点 in 口注入真信号并执行下游。
+   * payload 写入 scope（UI_EVENT_PAYLOAD_KEY）供 Logic 等节点读取。
+   */
+  async triggerNode(nodeId: string, inputValue?: unknown): Promise<void> {
+    await this.ensureNoBlueprintCycle();
+    this.requireNode(nodeId);
+    const key = `${nodeId}:in`;
+    this.injectedInputs.set(key, createTrueSignal(inputValue ?? true));
+    try {
+      await this.runFromNodeWithUiPayload(nodeId, inputValue);
+    } finally {
+      this.injectedInputs.delete(key);
+    }
+  }
+
+  private async runFromNodeWithUiPayload(
+    nodeId: string,
+    inputValue?: unknown
+  ) {
+    const queue: ExecutionToken[] = [
+      {
+        tokenId: createTokenId(),
+        nodeId,
+        nodeType: this.requireNode(nodeId).nodeType,
+        inPort: "in",
+        scope: cloneScope(),
+      },
+    ];
+    queue[0]!.scope.vars.set(UI_EVENT_PAYLOAD_KEY, inputValue);
+
+    const executor = this.createExecutor(queue);
+
+    while (queue.length > 0) {
+      const token = queue.shift()!;
+      if (!this.syncTokenFromGraph(token)) continue;
+      try {
+        await executor.executeToken(token);
+      } catch (error) {
+        this.setNodeOutput(
+          token.nodeId,
+          "out",
+          createFalseSignal(
+            error instanceof Error ? error.message : String(error)
+          )
+        );
+        const nextNodes = this.findSignalTargets(token.nodeId, "out");
+        for (const target of nextNodes) {
+          queue.push({
+            tokenId: createTokenId(),
+            nodeId: target.nodeId,
+            nodeType: target.nodeType,
+            inPort: target.inPort,
+            scope: token.scope,
+            correlationId: token.correlationId ?? token.tokenId,
+          });
+        }
+      }
+    }
+  }
+
   async emitLifecycle(phase: PageLifecyclePhase): Promise<void> {
     await this.ensureNoBlueprintCycle();
     const signal = createLifecycleSignal(phase);
@@ -275,6 +343,7 @@ export class BlueprintGraphRunner {
         return;
       }
       const token = queue.shift()!;
+      if (!this.syncTokenFromGraph(token)) continue;
       try {
         await executor.executeToken(token);
       } catch (error) {
@@ -357,6 +426,7 @@ export class BlueprintGraphRunner {
   /** 调试过程中同步最新蓝图拓扑与节点配置 */
   updateGraph(graph: RunnableGraph): void {
     this.graph = graph;
+    this.syncDebugQueueWithLatestGraph();
   }
 
   /**
@@ -367,14 +437,7 @@ export class BlueprintGraphRunner {
     if (!this.debugQueue) return;
 
     if (this.traceEntries.length === 0) {
-      const head = this.debugQueue[0];
-      if (!head) return;
-      const node = this.graph.nodes.find((n) => n.id === head.nodeId);
-      if (!node) {
-        this.debugQueue = [];
-        return;
-      }
-      head.nodeType = node.nodeType;
+      this.syncDebugQueueWithLatestGraph();
       return;
     }
 
@@ -423,7 +486,9 @@ export class BlueprintGraphRunner {
         });
       }
     }
-    this.debugQueue = newQueue;
+    if (newQueue.length > 0 || this.debugQueue.length === 0) {
+      this.debugQueue = newQueue;
+    }
   }
 
   canDebugStepBack(): boolean {
@@ -479,7 +544,9 @@ export class BlueprintGraphRunner {
 
     this.applyLifecycleScopeForNode(lifecycleNodeId);
 
-    this.debugExecutor = this.createExecutor(this.debugQueue);
+    this.debugExecutor = this.createExecutor(this.debugQueue, {
+      emitToActiveDebugQueue: true,
+    });
     this.debugHistory = [this.captureDebugSnapshot()];
   }
 
@@ -542,6 +609,13 @@ export class BlueprintGraphRunner {
     try {
       this.pushDebugSnapshot();
       const token = this.debugQueue.shift()!;
+      if (!this.syncTokenFromGraph(token)) {
+        this.pushDebugSnapshot();
+        return {
+          done: this.debugQueue.length === 0,
+          haltedByFalseSignal: false,
+        };
+      }
 
       if (token.nodeType === CLOCK_NODE_TYPE) {
         const node = this.requireNode(token.nodeId);
@@ -721,6 +795,12 @@ export class BlueprintGraphRunner {
       this.debugExecutor ??
       this.createExecutor(this.debugQueue ?? []);
 
+    if (!this.syncTokenFromGraph(token)) {
+      return this.appendDebugTraceEntry(token, nodeLabelById, startedAt, {
+        error: "节点已从蓝图中移除",
+      });
+    }
+
     try {
       await runExecutor.executeToken(token);
     } catch (err) {
@@ -941,6 +1021,7 @@ export class BlueprintGraphRunner {
           resolveLibraryBlueprint: runner.resolveLibraryBlueprint,
           rootLibraryBlueprintId: libraryId,
           resolveBlueprintName: runner.resolveBlueprintName,
+          onViewScopeUpdate: runner.onViewScopeUpdate,
         });
         await subRunner.emitBlueprintActivated(input.value, nestedScope);
         const nestedOutputs = await subRunner.runFromFlowEntries(nestedScope, {
@@ -975,22 +1056,32 @@ export class BlueprintGraphRunner {
       const node = runner.requireNode(token.nodeId);
 
       try {
-        const input = await io.getInput("in");
+        const inputPort = token.inPort || "in";
+        const input = await io.getInput(inputPort);
+        if (isFalseSignal(input)) {
+          io.setOutput("out", input);
+          io.emitFlow("out");
+          return;
+        }
         if (!isTrueSignal(input)) {
           io.setOutput(
             "out",
-            createFalseSignal("数据源节点需要收到真信号后才会发起请求")
+            createFalseSignal(
+              input === undefined
+                ? "数据源节点未收到上游输出，请确认连线与上游节点已执行"
+                : "数据源节点需要收到真信号后才会发起请求"
+            )
           );
           io.emitFlow("out");
           return;
         }
 
-        const config: FetchRequestConfig = {
-          ...DEFAULT_FETCH_REQUEST_CONFIG,
-          ...node.fetchConfig,
-        };
+        const config = normalizeFetchRequestConfig(node.fetchConfig);
+        resolveFetchRequestUrl(config);
 
-        const result = await executeFetch(config);
+        const result = await executeFetch(config, {
+          allowHttpError: runner.isDebugSessionActive(),
+        });
         io.setOutput("out", createTrueSignal(result));
       } catch (error) {
         io.setOutput(
@@ -1190,6 +1281,7 @@ export class BlueprintGraphRunner {
 
     while (queue.length > 0) {
       const token = queue.shift()!;
+      if (!this.syncTokenFromGraph(token)) continue;
       try {
         await executor.executeToken(token);
       } catch (error) {
@@ -1215,7 +1307,10 @@ export class BlueprintGraphRunner {
     }
   }
 
-  private createExecutor(queue: ExecutionToken[]) {
+  private createExecutor(
+    queue: ExecutionToken[],
+    options?: { emitToActiveDebugQueue?: boolean }
+  ) {
     return new Executor({
       getNodeDefinition,
       behaviors: this.behaviors,
@@ -1223,15 +1318,20 @@ export class BlueprintGraphRunner {
         // 由 blueprint-ref-run 行为处理
       },
       getInputValue: async (token, port) => {
-        return this.resolvePortInputValue(token.nodeId, port);
+        const resolvedPort = port || token.inPort || "in";
+        return this.resolvePortInputValue(token.nodeId, resolvedPort);
       },
       setNodeOutput: (token, port, value) => {
         this.setNodeOutput(token.nodeId, port, value);
       },
       emitFlow: (token, outPort) => {
+        const targetQueue =
+          options?.emitToActiveDebugQueue && this.debugQueue
+            ? this.debugQueue
+            : queue;
         const nextNodes = this.findSignalTargets(token.nodeId, outPort);
         for (const target of nextNodes) {
-          queue.push({
+          targetQueue.push({
             tokenId: createTokenId(),
             nodeId: target.nodeId,
             nodeType: target.nodeType,
@@ -1271,6 +1371,21 @@ export class BlueprintGraphRunner {
     return node;
   }
 
+  /** 队列中的 token 可能是在节点改类型（如视图绑定）之前入队的，执行前与最新图对齐 */
+  private syncTokenFromGraph(token: ExecutionToken): boolean {
+    const node = this.graph.nodes.find((n) => n.id === token.nodeId);
+    if (!node) return false;
+    token.nodeType = node.nodeType;
+    return true;
+  }
+
+  private syncDebugQueueWithLatestGraph(): void {
+    if (!this.debugQueue) return;
+    this.debugQueue = this.debugQueue.filter((token) =>
+      this.syncTokenFromGraph(token)
+    );
+  }
+
   private findSignalTargets(nodeId: string, outPort: string) {
     return this.graph.edges
       .filter(
@@ -1294,8 +1409,11 @@ export class BlueprintGraphRunner {
     );
   }
 
-  /** 单端口多连线：任一为真则视为真（或语义） */
+  /** 单端口多连线：任一为真则视为真（或语义）；支持 triggerNode 注入的入口信号 */
   private resolvePortInputValue(nodeId: string, port: string): Value | undefined {
+    const injected = this.injectedInputs.get(`${nodeId}:${port}`);
+    if (injected !== undefined) return injected;
+
     const inboundEdges = this.findInboundSignalEdges(nodeId, port);
     if (inboundEdges.length === 0) return undefined;