@arronqzy/blueprint-dsl 1.0.5 → 1.0.7

package/package.json

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

package/src/behaviors/default.ts

@@ -5,11 +5,13 @@ import {
   isTrueSignal,
 } from "../node-signal.js";
 import type { LifecycleSignal } from "../lifecycle.js";
+import type { ViewEventSignal } from "../event-config.js";
 import { BehaviorRegistry } from "../core/behavior-registry.js";
 
 const LIFECYCLE_SIGNAL_KEY = "__lifecycleSignal";
 const BLUEPRINT_ACTIVATION_INPUT_KEY = "__blueprintActivationInput";
 const UI_EVENT_PAYLOAD_KEY = "__uiEventPayload";
+const VIEW_EVENT_SIGNAL_KEY = "__viewEventSignal";
 
 export function registerDefaultBehaviors(registry: BehaviorRegistry) {
   registry.registerJS("logic-noop", async ({ io }) => {
@@ -40,6 +42,23 @@ export function registerDefaultBehaviors(registry: BehaviorRegistry) {
     }
     io.emitFlow("out");
   });
+
+  registry.registerJS("event-emit", async ({ token, io }) => {
+    const payload = token.scope.vars.get(VIEW_EVENT_SIGNAL_KEY) as
+      | ViewEventSignal
+      | undefined;
+    if (!payload) {
+      // 生命周期输入只负责注册，不向下游发出信号
+      return;
+    }
+    io.setOutput("out", createTrueSignal(payload));
+    io.emitFlow("out");
+  });
 }
 
-export { LIFECYCLE_SIGNAL_KEY, BLUEPRINT_ACTIVATION_INPUT_KEY, UI_EVENT_PAYLOAD_KEY };
+export {
+  LIFECYCLE_SIGNAL_KEY,
+  BLUEPRINT_ACTIVATION_INPUT_KEY,
+  UI_EVENT_PAYLOAD_KEY,
+  VIEW_EVENT_SIGNAL_KEY,
+};

package/src/event-config.ts

@@ -0,0 +1,211 @@
+/** 视图事件节点可监听的常用 DOM 事件 */
+export const VIEW_EVENT_TYPES = [
+  "click",
+  "dblclick",
+  "contextmenu",
+  "mouseenter",
+  "mouseleave",
+] as const;
+
+export type ViewEventType = (typeof VIEW_EVENT_TYPES)[number];
+
+export type ViewEventNodeConfig = {
+  /** 监听的事件类型，至少一项；默认 click */
+  eventTypes: ViewEventType[];
+};
+
+export const DEFAULT_VIEW_EVENT_NODE_CONFIG: ViewEventNodeConfig = {
+  eventTypes: ["click"],
+};
+
+const VIEW_EVENT_TYPE_SET = new Set<string>(VIEW_EVENT_TYPES);
+
+export function isViewEventType(value: unknown): value is ViewEventType {
+  return typeof value === "string" && VIEW_EVENT_TYPE_SET.has(value);
+}
+
+export function normalizeViewEventConfig(
+  config?: Partial<ViewEventNodeConfig> | null
+): ViewEventNodeConfig {
+  const raw = Array.isArray(config?.eventTypes) ? config.eventTypes : [];
+  const eventTypes = [
+    ...new Set(raw.filter(isViewEventType)),
+  ];
+  return {
+    eventTypes:
+      eventTypes.length > 0
+        ? eventTypes
+        : [...DEFAULT_VIEW_EVENT_NODE_CONFIG.eventTypes],
+  };
+}
+
+/** 可序列化的 DOM 事件快照（原生 Event 无法作为蓝图信号传递） */
+export type ViewEventSnapshot = {
+  type: string;
+  timeStamp: number;
+  clientX?: number;
+  clientY?: number;
+  pageX?: number;
+  pageY?: number;
+  button?: number;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+};
+
+/** 触发该事件的视图节点摘要 */
+export type ViewEventNodeSnapshot = {
+  id: string;
+  name?: string;
+  materialType?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  layerId?: string;
+};
+
+/** 事件节点向下游发出的真信号 value */
+export type ViewEventSignal = {
+  /** 触发事件（可序列化快照） */
+  event: ViewEventSnapshot;
+  /** 触发节点 */
+  node: ViewEventNodeSnapshot;
+  /** 触发的事件类型 */
+  eventType: ViewEventType;
+};
+
+export function snapshotDomEvent(event: {
+  type: string;
+  timeStamp?: number;
+  clientX?: number;
+  clientY?: number;
+  pageX?: number;
+  pageY?: number;
+  button?: number;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+}): ViewEventSnapshot {
+  return {
+    type: event.type,
+    timeStamp: Number(event.timeStamp) || Date.now(),
+    clientX: event.clientX,
+    clientY: event.clientY,
+    pageX: event.pageX,
+    pageY: event.pageY,
+    button: event.button,
+    altKey: event.altKey,
+    ctrlKey: event.ctrlKey,
+    metaKey: event.metaKey,
+    shiftKey: event.shiftKey,
+  };
+}
+
+export function snapshotViewEventNode(
+  node: Partial<ViewEventNodeSnapshot> & { id: string }
+): ViewEventNodeSnapshot {
+  return {
+    id: node.id,
+    name: node.name,
+    materialType: node.materialType,
+    x: node.x,
+    y: node.y,
+    width: node.width,
+    height: node.height,
+    layerId: node.layerId,
+  };
+}
+
+export function createViewEventSignal(input: {
+  event: ViewEventSnapshot;
+  node: ViewEventNodeSnapshot;
+  eventType: ViewEventType;
+}): ViewEventSignal {
+  return {
+    event: input.event,
+    node: input.node,
+    eventType: input.eventType,
+  };
+}
+
+export function collectArmedViewEventNodeIds(
+  nodes: Array<{
+    id: string;
+    nodeType?: string;
+    lifecyclePhase?: string;
+  }>,
+  edges: Array<{ source: string; target: string }>,
+  eventNodeType: string,
+  lifecycleNodeType: string,
+  firedPhases: ReadonlySet<string>
+): Set<string> {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const armed = new Set<string>();
+  for (const node of nodes) {
+    if (node.nodeType !== eventNodeType) continue;
+    const registered = edges.some((edge) => {
+      if (edge.target !== node.id) return false;
+      const source = byId.get(edge.source);
+      if (!source || source.nodeType !== lifecycleNodeType) return false;
+      const phase = source.lifecyclePhase || "mounted";
+      return firedPhases.has(phase);
+    });
+    if (registered) armed.add(node.id);
+  }
+  return armed;
+}
+
+/** 仅收集已由生命周期注册的事件节点绑定 */
+export function collectArmedViewEventBindings(
+  nodes: Array<{
+    id: string;
+    nodeType?: string;
+    lifecyclePhase?: string;
+    viewElementIds?: string[];
+    eventConfig?: Partial<ViewEventNodeConfig> | null;
+  }>,
+  edges: Array<{ source: string; target: string }>,
+  eventNodeType: string,
+  lifecycleNodeType: string,
+  firedPhases: ReadonlySet<string>
+): Map<string, Set<ViewEventType>> {
+  const armed = collectArmedViewEventNodeIds(
+    nodes,
+    edges,
+    eventNodeType,
+    lifecycleNodeType,
+    firedPhases
+  );
+  return collectViewEventBindings(nodes, eventNodeType, armed);
+}
+
+export function collectViewEventBindings(
+  nodes: Array<{
+    id?: string;
+    nodeType?: string;
+    viewElementIds?: string[];
+    eventConfig?: Partial<ViewEventNodeConfig> | null;
+  }>,
+  eventNodeType: string,
+  armedNodeIds?: ReadonlySet<string>
+): Map<string, Set<ViewEventType>> {
+  const map = new Map<string, Set<ViewEventType>>();
+  for (const node of nodes) {
+    if (node.nodeType !== eventNodeType) continue;
+    if (armedNodeIds && (!node.id || !armedNodeIds.has(node.id))) continue;
+    const types = normalizeViewEventConfig(node.eventConfig).eventTypes;
+    for (const id of node.viewElementIds ?? []) {
+      if (!id) continue;
+      let set = map.get(id);
+      if (!set) {
+        set = new Set();
+        map.set(id, set);
+      }
+      for (const type of types) set.add(type);
+    }
+  }
+  return map;
+}

package/src/fetch-config.ts

@@ -1,4 +1,5 @@
 import type { SwaggerApiEndpoint } from "./swagger.js";
+import { looksLikeJsonText } from "./scope-template.js";
 
 export const FETCH_HTTP_METHODS = [
   "GET",
@@ -37,6 +38,11 @@ export type FetchRequestConfig = {
   url: string;
   method?: FetchHttpMethod;
   headers?: Record<string, string>;
+  /**
+   * 请求头编辑器原文。可写 JSON，也可整段写成 `{scope?...}`。
+   * 运行时优先按该字段解析，避免未加引号的模板在 JSON.parse 时被丢掉。
+   */
+  headersJson?: string;
   body?: string;
   credentials?: RequestCredentials;
   mode?: RequestMode;
@@ -78,6 +84,7 @@ export function normalizeFetchRequestConfig(
       ...DEFAULT_FETCH_REQUEST_CONFIG.headers,
       ...config?.headers,
     },
+    headersJson: config?.headersJson,
     swaggerEndpoints: config?.swaggerEndpoints,
   };
 }
@@ -183,6 +190,24 @@ export async function executeFetch(
   const body =
     hasBody && config.body?.trim() ? config.body : undefined;
 
+  if (body && looksLikeJsonText(body)) {
+    try {
+      JSON.parse(body);
+    } catch (error) {
+      throw new Error(
+        `请求体不是有效 JSON：${error instanceof Error ? error.message : "格式无效"}`
+      );
+    }
+  }
+
+  const headers: Record<string, string> = { ...(config.headers ?? {}) };
+  const hasContentType = Object.keys(headers).some(
+    (key) => key.toLowerCase() === "content-type"
+  );
+  if (body && looksLikeJsonText(body) && !hasContentType) {
+    headers["Content-Type"] = "application/json";
+  }
+
   const timeoutMs = config.timeoutMs ?? 30000;
   const controller = new AbortController();
   const unlinkExternal = linkAbortSignal(controller, options?.signal);
@@ -194,10 +219,7 @@ export async function executeFetch(
   try {
     const response = await fetch(url, {
       method,
-      headers:
-        config.headers && Object.keys(config.headers).length > 0
-          ? config.headers
-          : undefined,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
       body,
       credentials: config.credentials,
       mode: config.mode,

package/src/incoming-node-scope.ts

@@ -0,0 +1,411 @@
+import type { FetchRequestConfig } from "./fetch-config.js";
+import {
+  evaluateScopeExpression,
+  evaluateScopeTemplate,
+  evaluateScopeTemplateInJson,
+  hasScopeTemplate,
+  looksLikeJsonText,
+  stringifyScopeValue,
+} from "./scope-template.js";
+import { isFalseSignal, isTrueSignal } from "./node-signal.js";
+
+export type IncomingNodeSource = {
+  id: string;
+  label?: string;
+  name?: string;
+  nodeType?: string;
+  type?: string;
+  role?: string;
+};
+
+export type IncomingGraphEdge = {
+  source: string;
+  target: string;
+  sourceHandle?: string;
+  targetHandle?: string;
+};
+
+export type IncomingNodeScopeEntry = {
+  id: string;
+  name: string;
+  type: string;
+  role?: string;
+  port: string;
+  kind: "true" | "false" | "pending";
+  value?: unknown;
+  error?: string;
+  timestamp?: number;
+  isoTime?: string;
+};
+
+export type IncomingNodeScope =
+  | IncomingNodeScopeEntry
+  | Record<string, IncomingNodeScopeEntry>;
+
+/** 尚无上游数据时，仍可联想 scope 的固定字段 */
+export const FETCH_SCOPE_AUTOCOMPLETE_FALLBACK: IncomingNodeScopeEntry = {
+  id: "",
+  name: "",
+  type: "",
+  role: "",
+  port: "out",
+  kind: "pending",
+  value: {},
+  error: "",
+  timestamp: 0,
+  isoTime: "",
+};
+
+export function resolveFetchScopeAutocompleteRoot(scope: unknown): unknown {
+  return scope === undefined ? FETCH_SCOPE_AUTOCOMPLETE_FALLBACK : scope;
+}
+
+function readOutputSignal(output: unknown): Pick<
+  IncomingNodeScopeEntry,
+  "kind" | "value" | "error" | "timestamp" | "isoTime"
+> {
+  if (output === undefined) return { kind: "pending" };
+  if (isTrueSignal(output)) {
+    return {
+      kind: "true",
+      value: output.value,
+      timestamp: output.timestamp,
+      isoTime: output.isoTime,
+    };
+  }
+  if (isFalseSignal(output)) {
+    return {
+      kind: "false",
+      error: output.error,
+      timestamp: output.timestamp,
+      isoTime: output.isoTime,
+    };
+  }
+  if (output && typeof output === "object" && "kind" in output) {
+    const rec = output as {
+      kind?: string;
+      value?: unknown;
+      error?: string;
+      timestamp?: number;
+      isoTime?: string;
+    };
+    if (rec.kind === "true") {
+      return {
+        kind: "true",
+        value: rec.value,
+        timestamp: rec.timestamp,
+        isoTime: rec.isoTime,
+      };
+    }
+    if (rec.kind === "false") {
+      return {
+        kind: "false",
+        error: rec.error,
+        timestamp: rec.timestamp,
+        isoTime: rec.isoTime,
+      };
+    }
+  }
+  return { kind: "true", value: output };
+}
+
+export function createIncomingNodeScopeEntry(
+  node: IncomingNodeSource | undefined,
+  port: string,
+  output: unknown
+): IncomingNodeScopeEntry {
+  const id = node?.id ?? "in";
+  const signal = readOutputSignal(output);
+  return {
+    id,
+    name: node?.label?.trim() || node?.name?.trim() || id,
+    type: node?.nodeType || node?.type || "unknown",
+    role: node?.role,
+    port,
+    ...signal,
+  };
+}
+
+export function buildIncomingNodeScope(
+  entries: IncomingNodeScopeEntry[]
+): IncomingNodeScope | undefined {
+  if (entries.length === 0) return undefined;
+  if (entries.length === 1) return entries[0];
+  const scoped: Record<string, IncomingNodeScopeEntry> = {};
+  for (const entry of entries) {
+    scoped[entry.id] = entry;
+  }
+  return scoped;
+}
+
+export function collectIncomingNodeScopeEntries(options: {
+  targetNodeId: string;
+  targetPort?: string;
+  nodes: IncomingNodeSource[];
+  edges: IncomingGraphEdge[];
+  getOutput?: (nodeId: string, port: string) => unknown;
+}): IncomingNodeScopeEntry[] {
+  const targetPort = options.targetPort ?? "in";
+  const nodeById = new Map(options.nodes.map((node) => [node.id, node]));
+  const inbound = options.edges.filter(
+    (edge) =>
+      edge.target === options.targetNodeId &&
+      (edge.targetHandle ?? "in") === targetPort
+  );
+
+  const seen = new Set<string>();
+  const entries: IncomingNodeScopeEntry[] = [];
+  for (const edge of inbound) {
+    const port = edge.sourceHandle ?? "out";
+    const key = `${edge.source}:${port}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const output = options.getOutput?.(edge.source, port);
+    entries.push(
+      createIncomingNodeScopeEntry(nodeById.get(edge.source), port, output)
+    );
+  }
+  return entries;
+}
+
+export function resolveFetchIncomingScope(options: {
+  fetchNodeId: string;
+  inputPort?: string;
+  nodes: IncomingNodeSource[];
+  edges: IncomingGraphEdge[];
+  getOutput?: (nodeId: string, port: string) => unknown;
+  fallbackInput?: unknown;
+}): IncomingNodeScope | undefined {
+  const entries = collectIncomingNodeScopeEntries({
+    targetNodeId: options.fetchNodeId,
+    targetPort: options.inputPort,
+    nodes: options.nodes,
+    edges: options.edges,
+    getOutput: options.getOutput,
+  });
+  if (entries.length > 0) return buildIncomingNodeScope(entries);
+  if (options.fallbackInput === undefined) return undefined;
+  return createIncomingNodeScopeEntry(
+    { id: "in", label: "in", nodeType: "input" },
+    options.inputPort ?? "in",
+    options.fallbackInput
+  );
+}
+
+export function latestTraceOutputsByNode(
+  entries: Array<{ nodeId: string; outputs?: Record<string, unknown> }>
+): Record<string, Record<string, unknown>> {
+  const map: Record<string, Record<string, unknown>> = {};
+  for (const entry of entries) {
+    map[entry.nodeId] = entry.outputs ?? {};
+  }
+  return map;
+}
+
+function resolveTemplateString(
+  value: string | undefined,
+  scope: unknown
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (!hasScopeTemplate(value)) return value;
+  return evaluateScopeTemplate(value, scope);
+}
+
+export function parseJsonText(
+  text: string
+): { ok: true; value: unknown } | { ok: false; error: string } {
+  try {
+    return { ok: true, value: JSON.parse(text) as unknown };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : "JSON 格式无效",
+    };
+  }
+}
+
+export function validateFetchJsonText(
+  text: string,
+  options?: { allowEmpty?: boolean }
+): { ok: true } | { ok: false; error: string } {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    if (options?.allowEmpty === false) {
+      return { ok: false, error: "内容不能为空" };
+    }
+    return { ok: true };
+  }
+  if (isWholeScopeExpression(trimmed)) {
+    return { ok: true };
+  }
+  if (!looksLikeJsonText(trimmed)) {
+    return { ok: true };
+  }
+  const parsed = parseJsonText(trimmed);
+  return parsed.ok ? { ok: true } : parsed;
+}
+
+export function resolveFetchBody(
+  body: string | undefined,
+  scope?: unknown
+): string | undefined {
+  if (body === undefined) return undefined;
+  const trimmed = body.trim();
+  if (!trimmed) return body;
+  if (scope !== undefined && isWholeScopeExpression(trimmed)) {
+    const value = evaluateScopeExpression(trimmed.slice(1, -1), scope);
+    if (value === undefined) return "";
+    if (typeof value === "string") return value;
+    return stringifyScopeValue(value);
+  }
+  if (scope === undefined || !hasScopeTemplate(body)) return body;
+  if (looksLikeJsonText(trimmed)) {
+    return evaluateScopeTemplateInJson(body, scope);
+  }
+  return evaluateScopeTemplate(body, scope);
+}
+
+export function getFetchBodyValidationError(
+  body: string | undefined,
+  resolvedBody?: string
+): string | null {
+  const source = (resolvedBody ?? body ?? "").trim();
+  if (!source) return null;
+  if (isWholeScopeExpression(source)) return null;
+  if (!looksLikeJsonText(source)) return null;
+  const parsed = parseJsonText(source);
+  if (parsed.ok) return null;
+  // 仍含未求值的 {scope?...} 时，等上游数据再校验
+  if (hasScopeTemplate(source)) return null;
+  return parsed.error;
+}
+
+export function getFetchHeadersValidationError(
+  config: FetchRequestConfig,
+  scope?: unknown
+): string | null {
+  const raw = (config.headersJson ?? "").trim();
+  if (!raw) return null;
+  if (isWholeScopeExpression(raw) || hasScopeTemplate(raw)) {
+    if (scope === undefined) return null;
+    const parsed = parseFetchHeadersJson(raw, scope);
+    if (!parsed) return "请求头模板解析后不是有效的 JSON 对象";
+    return null;
+  }
+  const result = validateFetchJsonText(raw);
+  if (!result.ok) return result.error;
+  const parsed = parseFetchHeadersJson(raw, scope);
+  if (!parsed) return "请求头不是有效的 JSON 对象";
+  return null;
+}
+
+/** `{scope?...}` 整段表达式，区别于 JSON 对象 `{ "Authorization": "..." }` */
+export function isWholeScopeExpression(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return false;
+  return trimmed.slice(1, -1).trim().startsWith("scope");
+}
+
+function asHeaderRecord(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const headers: Record<string, string> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    if (raw === undefined || raw === null) continue;
+    headers[key] = typeof raw === "string" ? raw : stringifyScopeValue(raw);
+  }
+  return headers;
+}
+
+function applyScopeToHeaderRecord(
+  headers: Record<string, string>,
+  scope: unknown
+): Record<string, string> {
+  if (scope === undefined) return headers;
+  return Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [
+      evaluateScopeTemplate(String(key), scope),
+      evaluateScopeTemplate(value == null ? "" : String(value), scope),
+    ])
+  );
+}
+
+/** 将请求头编辑器原文解析为对象；支持 JSON 内模板，也支持整段 `{scope?...}` */
+export function parseFetchHeadersJson(
+  text: string,
+  scope?: unknown
+): Record<string, string> | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) return {};
+  if (isWholeScopeExpression(trimmed)) {
+    if (scope === undefined) return undefined;
+    const inner = trimmed.slice(1, -1);
+    return asHeaderRecord(evaluateScopeExpression(inner, scope));
+  }
+  let jsonText = trimmed;
+  if (scope !== undefined && hasScopeTemplate(trimmed) && looksLikeJsonText(trimmed)) {
+    jsonText = evaluateScopeTemplateInJson(trimmed, scope);
+  }
+  try {
+    const parsed = asHeaderRecord(JSON.parse(jsonText));
+    if (!parsed) return undefined;
+    if (jsonText === trimmed) {
+      return applyScopeToHeaderRecord(parsed, scope);
+    }
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+export function draftFetchHeadersText(config: FetchRequestConfig): string {
+  if (config.headersJson !== undefined) return config.headersJson;
+  try {
+    return JSON.stringify(config.headers ?? {}, null, 2);
+  } catch {
+    return "{}";
+  }
+}
+
+export function resolveFetchHeaders(
+  config: FetchRequestConfig,
+  scope?: unknown
+): Record<string, string> | undefined {
+  const rawJson = config.headersJson;
+  if (rawJson !== undefined && rawJson.trim() !== "") {
+    const parsed = parseFetchHeadersJson(rawJson, scope);
+    if (parsed) return parsed;
+  }
+  if (!config.headers) return config.headers;
+  return applyScopeToHeaderRecord(config.headers, scope);
+}
+
+/** 用上游 scope 解析 fetch 表单中的 URL / Base URL / headers / body */
+export function applyFetchConfigScope(
+  config: FetchRequestConfig,
+  scope: unknown
+): FetchRequestConfig {
+  const headers = resolveFetchHeaders(config, scope);
+  const body = resolveFetchBody(config.body, scope);
+  if (scope === undefined) {
+    if (headers === config.headers && body === config.body) return config;
+    return { ...config, headers, body };
+  }
+  return {
+    ...config,
+    url: resolveTemplateString(config.url, scope) ?? "",
+    apiBaseUrl: resolveTemplateString(config.apiBaseUrl, scope),
+    body,
+    headers,
+  };
+}
+
+export function fetchConfigHasScopeTemplate(config: FetchRequestConfig): boolean {
+  if (hasScopeTemplate(config.url ?? "")) return true;
+  if (hasScopeTemplate(config.apiBaseUrl ?? "")) return true;
+  if (hasScopeTemplate(config.body ?? "")) return true;
+  if (hasScopeTemplate(config.headersJson ?? "")) return true;
+  const headers = config.headers ?? {};
+  return Object.entries(headers).some(
+    ([key, value]) => hasScopeTemplate(key) || hasScopeTemplate(String(value ?? ""))
+  );
+}

package/src/index.ts

@@ -7,9 +7,13 @@ export * from "./core/behavior-registry.js";
 export * from "./core/executor.js";
 export * from "./behaviors/default.js";
 export * from "./fetch-config.js";
+export * from "./scope-template.js";
+export * from "./scope-autocomplete.js";
+export * from "./incoming-node-scope.js";
 export * from "./json-config.js";
 export * from "./logic-config.js";
 export * from "./clock-config.js";
+export * from "./event-config.js";
 export * from "./swagger.js";
 export * from "./runtime/execution-trace.js";
 export * from "./runtime/blueprint-cycle.js";

package/src/nodes/definitions.ts

@@ -8,6 +8,7 @@ export const JSON_NODE_TYPE = "JsonNode";
 export const CLOCK_NODE_TYPE = "Clock";
 export const AND_NODE_TYPE = "AndLogic";
 export const VIEW_NODE_TYPE = "ViewBind";
+export const EVENT_NODE_TYPE = "ViewEvent";
 
 /** 蓝图引用节点：单入单出，收到真信号后执行嵌套蓝图 */
 export const blueprintNodeDefinition: NodeDefinition = {
@@ -75,6 +76,14 @@ export const viewBindNodeDefinition: NodeDefinition = {
   behavior: { kind: "js", ref: "view-bind-run" },
 };
 
+/** 视图事件节点：输入必须来自生命周期节点，对应阶段触发后注册事件，视图事件发生时输出真信号 */
+export const viewEventNodeDefinition: NodeDefinition = {
+  type: EVENT_NODE_TYPE,
+  inputs: [{ name: "in", kind: "data" }],
+  outputs: [{ name: "out", kind: "data" }],
+  behavior: { kind: "js", ref: "event-emit" },
+};
+
 export const nodeDefinitionRegistry: Record<string, NodeDefinition> = {
   [BLUEPRINT_NODE_TYPE]: blueprintNodeDefinition,
   [DEFAULT_LOGIC_NODE_TYPE]: defaultLogicNodeDefinition,
@@ -84,6 +93,7 @@ export const nodeDefinitionRegistry: Record<string, NodeDefinition> = {
   [CLOCK_NODE_TYPE]: clockNodeDefinition,
   [AND_NODE_TYPE]: andLogicNodeDefinition,
   [VIEW_NODE_TYPE]: viewBindNodeDefinition,
+  [EVENT_NODE_TYPE]: viewEventNodeDefinition,
 };
 
 export function getNodeDefinition(type: string): NodeDefinition {

package/src/runtime/graph-runner.ts

@@ -4,6 +4,12 @@ import {
   normalizeFetchRequestConfig,
   resolveFetchRequestUrl,
 } from "../fetch-config.js";
+import {
+  applyFetchConfigScope,
+  getFetchBodyValidationError,
+  getFetchHeadersValidationError,
+  resolveFetchIncomingScope,
+} from "../incoming-node-scope.js";
 import type { JsonNodeConfig } from "../json-config.js";
 import {
   DEFAULT_JSON_NODE_CONFIG,
@@ -22,6 +28,8 @@ import {
   normalizeClockConfig,
   validateClockScheduleConfig,
 } from "../clock-config.js";
+import type { ViewEventNodeConfig, ViewEventSignal } from "../event-config.js";
+import { normalizeViewEventConfig } from "../event-config.js";
 import {
   buildClockSessionKey,
   scheduleClockOutputs,
@@ -39,6 +47,7 @@ import {
   BLUEPRINT_ACTIVATION_INPUT_KEY,
   LIFECYCLE_SIGNAL_KEY,
   UI_EVENT_PAYLOAD_KEY,
+  VIEW_EVENT_SIGNAL_KEY,
 } from "../behaviors/default.js";
 import { BehaviorRegistry } from "../core/behavior-registry.js";
 import { Executor } from "../core/executor.js";
@@ -57,6 +66,7 @@ import {
 import {
   BLUEPRINT_NODE_TYPE,
   CLOCK_NODE_TYPE,
+  EVENT_NODE_TYPE,
   getNodeDefinition,
   LIFECYCLE_NODE_TYPE,
   VIEW_NODE_TYPE,
@@ -78,6 +88,8 @@ import {
 export type RunnableGraphNode = {
   id: string;
   nodeType: string;
+  label?: string;
+  role?: string;
   lifecyclePhase?: PageLifecyclePhase;
   /** 蓝图库记录 id，Blueprint 节点引用嵌套蓝图时使用 */
   libraryBlueprintId?: string;
@@ -88,6 +100,7 @@ export type RunnableGraphNode = {
   jsonConfig?: JsonNodeConfig;
   logicConfig?: LogicNodeConfig;
   clockConfig?: ClockNodeConfig;
+  eventConfig?: ViewEventNodeConfig;
 };
 
 export type RunnableGraphEdge = {
@@ -304,6 +317,28 @@ export class BlueprintGraphRunner {
     }
   }
 
+  /**
+   * 视图节点触发事件时，匹配已注册（上游生命周期已触发）且绑定了该元素、事件类型的事件节点，发出真信号。
+   */
+  async emitViewEvent(
+    payload: ViewEventSignal,
+    armedNodeIds?: ReadonlySet<string>
+  ): Promise<void> {
+    await this.ensureNoBlueprintCycle();
+    const targets = this.graph.nodes.filter((node) => {
+      if (node.nodeType !== EVENT_NODE_TYPE) return false;
+      if (armedNodeIds && !armedNodeIds.has(node.id)) return false;
+      if (!(node.viewElementIds ?? []).includes(payload.node.id)) return false;
+      return normalizeViewEventConfig(node.eventConfig).eventTypes.includes(
+        payload.eventType
+      );
+    });
+
+    for (const node of targets) {
+      await this.runFromNode(node.id, undefined, undefined, undefined, payload);
+    }
+  }
+
   /** 时钟节点单次输出：向下游传播含当前时间的真信号 */
   async propagateClockOutput(
     nodeId: string,
@@ -1076,7 +1111,23 @@ export class BlueprintGraphRunner {
           return;
         }
 
-        const config = normalizeFetchRequestConfig(node.fetchConfig);
+        const incomingScope = runner.buildFetchIncomingScope(
+          token.nodeId,
+          inputPort,
+          input
+        );
+        const config = applyFetchConfigScope(
+          normalizeFetchRequestConfig(node.fetchConfig),
+          incomingScope
+        );
+        const headersError = getFetchHeadersValidationError(config, incomingScope);
+        if (headersError) {
+          throw new Error(headersError);
+        }
+        const bodyError = getFetchBodyValidationError(config.body, config.body);
+        if (bodyError) {
+          throw new Error(`请求体不是有效 JSON：${bodyError}`);
+        }
         resolveFetchRequestUrl(config);
 
         const result = await executeFetch(config, {
@@ -1255,7 +1306,8 @@ export class BlueprintGraphRunner {
     nodeId: string,
     lifecycleSignal?: LifecycleSignal,
     parentScope?: Scope,
-    activationInput?: unknown
+    activationInput?: unknown,
+    viewEvent?: ViewEventSignal
   ) {
     const queue: ExecutionToken[] = [
       {
@@ -1276,6 +1328,10 @@ export class BlueprintGraphRunner {
         activationInput
       );
     }
+    if (viewEvent) {
+      queue[0]!.scope.vars.set(VIEW_EVENT_SIGNAL_KEY, viewEvent);
+      queue[0]!.scope.vars.set(UI_EVENT_PAYLOAD_KEY, viewEvent);
+    }
 
     const executor = this.createExecutor(queue);
 
@@ -1351,7 +1407,9 @@ export class BlueprintGraphRunner {
     }
     return this.graph.nodes.filter(
       (node) =>
-        node.nodeType !== LIFECYCLE_NODE_TYPE && !hasIncoming.has(node.id)
+        node.nodeType !== LIFECYCLE_NODE_TYPE &&
+        node.nodeType !== EVENT_NODE_TYPE &&
+        !hasIncoming.has(node.id)
     );
   }
 
@@ -1409,6 +1467,27 @@ export class BlueprintGraphRunner {
     );
   }
 
+  private buildFetchIncomingScope(
+    nodeId: string,
+    port: string,
+    fallbackInput: Value | undefined
+  ) {
+    return resolveFetchIncomingScope({
+      fetchNodeId: nodeId,
+      inputPort: port,
+      nodes: this.graph.nodes.map((node) => ({
+        id: node.id,
+        label: node.label,
+        nodeType: node.nodeType,
+        role: node.role,
+      })),
+      edges: this.graph.edges,
+      getOutput: (sourceId, sourcePort) =>
+        this.getNodeOutput(sourceId, sourcePort),
+      fallbackInput,
+    });
+  }
+
   /** 单端口多连线：任一为真则视为真（或语义）；支持 triggerNode 注入的入口信号 */
   private resolvePortInputValue(nodeId: string, port: string): Value | undefined {
     const injected = this.injectedInputs.get(`${nodeId}:${port}`);

package/src/scope-autocomplete.ts

@@ -0,0 +1,114 @@
+export type ScopeAutocompleteState = {
+  templateStart: number;
+  cursor: number;
+  path: string[];
+  partialKey: string;
+};
+
+function getValueAtPath(scope: unknown, path: string[]): unknown {
+  let current: unknown = scope;
+  for (const part of path) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function listObjectKeys(value: unknown): string[] {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return [];
+  }
+  return Object.keys(value as Record<string, unknown>);
+}
+
+/** 解析光标处未闭合的 scope 模版表达式 */
+export function parseScopeAutocomplete(
+  text: string,
+  cursor: number,
+  scope: unknown
+): ScopeAutocompleteState | null {
+  const before = text.slice(0, cursor);
+  const templateStart = before.lastIndexOf("{");
+  if (templateStart < 0) return null;
+
+  const inner = before.slice(templateStart + 1);
+  if (inner.includes("}")) return null;
+  if (!inner.startsWith("scope")) return null;
+
+  let body = inner.slice("scope".length);
+  if (body === "" || body === "?") {
+    return { templateStart, cursor, path: [], partialKey: "" };
+  }
+  if (!body.startsWith("?.")) return null;
+
+  body = body.slice(2);
+  if (body === "") {
+    return { templateStart, cursor, path: [], partialKey: "" };
+  }
+
+  const segments = body.split("?.");
+  const endsWithSeparator = inner.endsWith("?.");
+
+  if (endsWithSeparator) {
+    const path = segments.filter((segment) => segment.length > 0);
+    return { templateStart, cursor, path, partialKey: "" };
+  }
+
+  const lastSegment = segments[segments.length - 1] ?? "";
+  const prefixSegments = segments.slice(0, -1).filter((segment) => segment.length > 0);
+  const parent = getValueAtPath(scope, prefixSegments);
+  const keys = listObjectKeys(parent);
+
+  if (lastSegment.length === 0) {
+    return { templateStart, cursor, path: prefixSegments, partialKey: "" };
+  }
+
+  if (keys.includes(lastSegment)) {
+    return {
+      templateStart,
+      cursor,
+      path: [...prefixSegments, lastSegment],
+      partialKey: "",
+    };
+  }
+
+  return {
+    templateStart,
+    cursor,
+    path: prefixSegments,
+    partialKey: lastSegment,
+  };
+}
+
+export function getScopeAutocompleteSuggestions(
+  scope: unknown,
+  state: ScopeAutocompleteState
+): string[] {
+  const parent =
+    state.partialKey.length > 0
+      ? getValueAtPath(scope, state.path)
+      : state.path.length > 0
+        ? getValueAtPath(scope, state.path)
+        : scope;
+
+  const keys = listObjectKeys(parent);
+  if (state.partialKey.length === 0) return keys;
+  return keys.filter((key) => key.startsWith(state.partialKey));
+}
+
+export function buildScopeExpression(path: string[], selectedKey: string): string {
+  return `scope?.${[...path, selectedKey].join("?.")}`;
+}
+
+export function applyScopeAutocompleteSelection(
+  text: string,
+  state: ScopeAutocompleteState,
+  selectedKey: string
+): { value: string; cursor: number } {
+  const expr = buildScopeExpression(state.path, selectedKey);
+  const before = text.slice(0, state.templateStart + 1);
+  const after = text.slice(state.cursor);
+  const value = `${before}${expr}${after}`;
+  const cursor = before.length + expr.length;
+  return { value, cursor };
+}

package/src/scope-template.ts

@@ -0,0 +1,93 @@
+/** 仅匹配 `{scope...}`，避免把 JSON 对象 `{ "a": 1 }` 误当成模板 */
+const SCOPE_TOKEN_RE = /\{(scope[^}]*)\}/g;
+
+export function hasScopeTemplate(value: string): boolean {
+  SCOPE_TOKEN_RE.lastIndex = 0;
+  return SCOPE_TOKEN_RE.test(value);
+}
+
+export function evaluateScopeExpression(
+  expression: string,
+  scope: unknown
+): unknown {
+  const trimmed = expression.trim();
+  if (!trimmed) return undefined;
+  try {
+    const fn = new Function("scope", `"use strict"; return (${trimmed});`);
+    return fn(scope);
+  } catch {
+    return undefined;
+  }
+}
+
+export function stringifyScopeValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function isInsideJsonString(before: string): boolean {
+  let inString = false;
+  let escape = false;
+  for (const ch of before) {
+    if (inString) {
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+  }
+  return inString;
+}
+
+function replaceScopeTokens(
+  template: string,
+  scope: unknown,
+  replacer: (value: unknown, offset: number) => string
+): string {
+  SCOPE_TOKEN_RE.lastIndex = 0;
+  return template.replace(SCOPE_TOKEN_RE, (_match, rawExpr: string, offset: number) =>
+    replacer(evaluateScopeExpression(rawExpr, scope), offset)
+  );
+}
+
+/** 将 `{scope?.a}` 替换为求值结果；无模板时原样返回 */
+export function evaluateScopeTemplate(template: string, scope: unknown): string {
+  if (!hasScopeTemplate(template)) return template;
+  return replaceScopeTokens(template, scope, (value) => stringifyScopeValue(value));
+}
+
+/**
+ * 在 JSON 文本中替换 `{scope?...}`：
+ * - 位于字符串内时写入转义后的内容
+ * - 位于值位置时写入 JSON 字面量（对象/数组/字符串/数字）
+ */
+export function evaluateScopeTemplateInJson(template: string, scope: unknown): string {
+  if (!hasScopeTemplate(template)) return template;
+  return replaceScopeTokens(template, scope, (value, offset) => {
+    if (isInsideJsonString(template.slice(0, offset))) {
+      return JSON.stringify(stringifyScopeValue(value)).slice(1, -1);
+    }
+    if (value === undefined) return "null";
+    return JSON.stringify(value);
+  });
+}
+
+export function looksLikeJsonText(text: string): boolean {
+  const trimmed = text.trim();
+  return trimmed.startsWith("{") || trimmed.startsWith("[");
+}