@arronqzy/blueprint-dsl 0.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/blueprint-dsl",
-  "version": "0.0.1",
+  "version": "1.0.3",
   "description": "Abuilder blueprint DSL runtime",
   "license": "MIT",
   "files": [
@@ -17,7 +17,7 @@
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
     "@arronqzy/eslint-config": "0.0.0",
-    "@arronqzy/typescript-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/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,
@@ -275,6 +279,7 @@ export class BlueprintGraphRunner {
         return;
       }
       const token = queue.shift()!;
+      if (!this.syncTokenFromGraph(token)) continue;
       try {
         await executor.executeToken(token);
       } catch (error) {
@@ -357,6 +362,7 @@ export class BlueprintGraphRunner {
   /** 调试过程中同步最新蓝图拓扑与节点配置 */
   updateGraph(graph: RunnableGraph): void {
     this.graph = graph;
+    this.syncDebugQueueWithLatestGraph();
   }
 
   /**
@@ -367,14 +373,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 +422,9 @@ export class BlueprintGraphRunner {
         });
       }
     }
-    this.debugQueue = newQueue;
+    if (newQueue.length > 0 || this.debugQueue.length === 0) {
+      this.debugQueue = newQueue;
+    }
   }
 
   canDebugStepBack(): boolean {
@@ -479,7 +480,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 +545,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 +731,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 +957,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 +992,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 +1217,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 +1243,10 @@ export class BlueprintGraphRunner {
     }
   }
 
-  private createExecutor(queue: ExecutionToken[]) {
+  private createExecutor(
+    queue: ExecutionToken[],
+    options?: { emitToActiveDebugQueue?: boolean }
+  ) {
     return new Executor({
       getNodeDefinition,
       behaviors: this.behaviors,
@@ -1223,15 +1254,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 +1307,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(