@arronqzy/blueprint-dsl 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/blueprint-dsl",
-  "version": "1.0.6",
+  "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",
@@ -189,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);
@@ -200,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

@@ -2,7 +2,9 @@ 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";
@@ -40,6 +42,24 @@ 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"
@@ -191,6 +211,94 @@ function resolveTemplateString(
   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();
@@ -233,10 +341,17 @@ export function parseFetchHeadersJson(
     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(trimmed));
+    const parsed = asHeaderRecord(JSON.parse(jsonText));
     if (!parsed) return undefined;
-    return applyScopeToHeaderRecord(parsed, scope);
+    if (jsonText === trimmed) {
+      return applyScopeToHeaderRecord(parsed, scope);
+    }
+    return parsed;
   } catch {
     return undefined;
   }
@@ -269,16 +384,17 @@ export function applyFetchConfigScope(
   config: FetchRequestConfig,
   scope: unknown
 ): FetchRequestConfig {
+  const headers = resolveFetchHeaders(config, scope);
+  const body = resolveFetchBody(config.body, scope);
   if (scope === undefined) {
-    const headers = resolveFetchHeaders(config);
-    return headers === config.headers ? config : { ...config, headers };
+    if (headers === config.headers && body === config.body) return config;
+    return { ...config, headers, body };
   }
-  const headers = resolveFetchHeaders(config, scope);
   return {
     ...config,
     url: resolveTemplateString(config.url, scope) ?? "",
     apiBaseUrl: resolveTemplateString(config.apiBaseUrl, scope),
-    body: resolveTemplateString(config.body, scope),
+    body,
     headers,
   };
 }

package/src/index.ts

@@ -8,10 +8,12 @@ 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,7 +4,12 @@ import {
   normalizeFetchRequestConfig,
   resolveFetchRequestUrl,
 } from "../fetch-config.js";
-import { applyFetchConfigScope, resolveFetchIncomingScope } from "../incoming-node-scope.js";
+import {
+  applyFetchConfigScope,
+  getFetchBodyValidationError,
+  getFetchHeadersValidationError,
+  resolveFetchIncomingScope,
+} from "../incoming-node-scope.js";
 import type { JsonNodeConfig } from "../json-config.js";
 import {
   DEFAULT_JSON_NODE_CONFIG,
@@ -23,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,
@@ -40,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";
@@ -58,6 +66,7 @@ import {
 import {
   BLUEPRINT_NODE_TYPE,
   CLOCK_NODE_TYPE,
+  EVENT_NODE_TYPE,
   getNodeDefinition,
   LIFECYCLE_NODE_TYPE,
   VIEW_NODE_TYPE,
@@ -91,6 +100,7 @@ export type RunnableGraphNode = {
   jsonConfig?: JsonNodeConfig;
   logicConfig?: LogicNodeConfig;
   clockConfig?: ClockNodeConfig;
+  eventConfig?: ViewEventNodeConfig;
 };
 
 export type RunnableGraphEdge = {
@@ -307,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,
@@ -1088,6 +1120,14 @@ export class BlueprintGraphRunner {
           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, {
@@ -1266,7 +1306,8 @@ export class BlueprintGraphRunner {
     nodeId: string,
     lifecycleSignal?: LifecycleSignal,
     parentScope?: Scope,
-    activationInput?: unknown
+    activationInput?: unknown,
+    viewEvent?: ViewEventSignal
   ) {
     const queue: ExecutionToken[] = [
       {
@@ -1287,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);
 
@@ -1362,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)
     );
   }
 

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

@@ -1,7 +1,9 @@
-const SCOPE_TEMPLATE_RE = /\{[^}]+\}/;
+/** 仅匹配 `{scope...}`，避免把 JSON 对象 `{ "a": 1 }` 误当成模板 */
+const SCOPE_TOKEN_RE = /\{(scope[^}]*)\}/g;
 
 export function hasScopeTemplate(value: string): boolean {
-  return SCOPE_TEMPLATE_RE.test(value);
+  SCOPE_TOKEN_RE.lastIndex = 0;
+  return SCOPE_TOKEN_RE.test(value);
 }
 
 export function evaluateScopeExpression(
@@ -31,10 +33,61 @@ export function stringifyScopeValue(value: unknown): string {
   }
 }
 
+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 template.replace(/\{([^}]+)\}/g, (_match, rawExpr: string) =>
-    stringifyScopeValue(evaluateScopeExpression(rawExpr, scope))
-  );
+  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("[");
 }