@lingfan-engine/stories-build 0.0.0-stage → 0.1.2

package/src/compiler/story-compiler/translate/expr/expr.ts

@@ -0,0 +1,174 @@
+import * as ts from "typescript";
+import { diag, lookupBinding, lookupScope } from "../shared.ts";
+import type { BodyCtx } from "../shared.ts";
+import { probeExpression } from "./probe.ts";
+import { lowerExpr } from "./lower/index.ts";
+import { statePath } from "./state-path.ts";
+import { quoteEngineString } from "./engine-text.ts";
+
+export type Lowered =
+  | { kind: "lit"; value: string | number | boolean }
+  | { kind: "expr"; text: string }
+  | undefined;
+
+export function lowerCond(
+  ctx: BodyCtx,
+  expr: ts.Expression,
+): string | undefined {
+  const inner = lowerExpr(ctx, expr);
+  if (inner === undefined) return undefined;
+  if (!probeExpression(inner.text)) {
+    diag(ctx, expr, `表达式 \`${inner.text}\` 不符合引擎表达式文法`);
+    return undefined;
+  }
+  return `{${inner.text}}`;
+}
+
+export function lowerValue(ctx: BodyCtx, expr: ts.Expression): Lowered {
+  const root = ctx.shared.stateRoot;
+  if (ts.isNumericLiteral(expr)) {
+    const n = Number(expr.text);
+    if (!Number.isFinite(n)) {
+      diag(ctx, expr, `数字字面量 \`${expr.text}\` 不是有限数`);
+      return undefined;
+    }
+    return { kind: "lit", value: n };
+  }
+  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+    return { kind: "lit", value: expr.text };
+  }
+  if (expr.kind === ts.SyntaxKind.TrueKeyword)
+    return { kind: "lit", value: true };
+  if (expr.kind === ts.SyntaxKind.FalseKeyword)
+    return { kind: "lit", value: false };
+  if (expr.kind === ts.SyntaxKind.NullKeyword) {
+    diag(ctx, expr, "null 不可作为值");
+    return undefined;
+  }
+  if (ts.isParenthesizedExpression(expr))
+    return lowerValue(ctx, expr.expression);
+  if (ts.isTemplateExpression(expr)) {
+    const parts: string[] = [expr.head.text];
+    for (const span of expr.templateSpans) {
+      if (
+        ts.isStringLiteral(span.expression) ||
+        ts.isNoSubstitutionTemplateLiteral(span.expression)
+      ) {
+        parts.push(span.expression.text);
+      } else if (
+        span.expression.kind === ts.SyntaxKind.TrueKeyword ||
+        span.expression.kind === ts.SyntaxKind.FalseKeyword
+      ) {
+        parts.push(
+          span.expression.kind === ts.SyntaxKind.TrueKeyword ? "true" : "false",
+        );
+      } else if (ts.isNumericLiteral(span.expression)) {
+        parts.push(String(Number(span.expression.text)));
+      } else {
+        const lowered = lowerExpr(ctx, span.expression);
+        if (lowered === undefined) return undefined;
+        if (!probeExpression(lowered.text)) {
+          diag(
+            ctx,
+            span.expression,
+            `插值表达式 \`${lowered.text}\` 不符合引擎表达式文法`,
+          );
+          return undefined;
+        }
+        parts.push(`{${lowered.text}}`);
+      }
+      parts.push(span.literal.text);
+    }
+    return { kind: "lit", value: parts.join("") };
+  }
+  if (ts.isIdentifier(expr)) {
+    const name = expr.text;
+    if (name === root) {
+      diag(ctx, expr, `${root} 必须以成员路径使用：${root}.player.gold`);
+      return undefined;
+    }
+    const scoped = lookupScope(ctx, name);
+    if (scoped !== undefined) {
+      if (scoped.kind === "index")
+        return { kind: "lit", value: scoped.value ?? 0 };
+      return { kind: "expr", text: name };
+    }
+    const binding = lookupBinding(ctx, name);
+    if (binding === undefined) {
+      diag(ctx, expr, `未知标识符 \`${name}\``);
+      return undefined;
+    }
+    if (binding.kind === "const") {
+      if (binding.value === null) {
+        diag(ctx, expr, "常量值为 null，不可作为值");
+        return undefined;
+      }
+      return { kind: "lit", value: binding.value };
+    }
+    if (binding.kind === "enum") {
+      diag(ctx, expr, `枚举 \`${name}\` 必须以成员形式使用：${name}.成员`);
+      return undefined;
+    }
+    diag(ctx, expr, `\`${name}\` 不是值（${binding.kind} 绑定不能作为值）`);
+    return undefined;
+  }
+  if (ts.isPropertyAccessExpression(expr)) {
+    const object = expr.expression;
+    if (ts.isIdentifier(object) && object.text !== root) {
+      const binding = lookupBinding(ctx, object.text);
+      if (binding?.kind === "enum") {
+        const value = binding.members.get(expr.name.text);
+        if (value === undefined) {
+          diag(
+            ctx,
+            expr,
+            `枚举 ${binding.name} 没有成员 \`${expr.name.text}\``,
+          );
+          return undefined;
+        }
+        if (value === null) {
+          diag(ctx, expr, "枚举成员值为 null，不可作为值");
+          return undefined;
+        }
+        return { kind: "lit", value };
+      }
+    }
+    const target = statePath(ctx, expr);
+    if (target === undefined) return undefined;
+    // 可选段脱糖：state.player?.nick → optGet("player.nick")（路径缺失返回 null，配 ?? 兜底）
+    if (target.optional) {
+      return {
+        kind: "expr",
+        text: `optGet(${quoteEngineString(target.path)})`,
+      };
+    }
+    return { kind: "expr", text: target.path };
+  }
+  if (
+    ts.isBinaryExpression(expr) ||
+    ts.isPrefixUnaryExpression(expr) ||
+    ts.isConditionalExpression(expr) ||
+    ts.isCallExpression(expr) ||
+    ts.isElementAccessExpression(expr)
+  ) {
+    const lowered = lowerExpr(ctx, expr);
+    if (lowered === undefined) return undefined;
+    if (!probeExpression(lowered.text)) {
+      diag(ctx, expr, `表达式 \`${lowered.text}\` 不符合引擎表达式文法`);
+      return undefined;
+    }
+    return { kind: "expr", text: lowered.text };
+  }
+  diag(
+    ctx,
+    expr,
+    "值表达式不支持此形态（数组请用 newArray 词、对象请用 dict 词）",
+  );
+  return undefined;
+}
+
+export function loweredToScriptValue(
+  lowered: NonNullable<Lowered>,
+): string | number | boolean {
+  return lowered.kind === "lit" ? lowered.value : `{${lowered.text}}`;
+}

package/src/compiler/story-compiler/translate/expr/index.ts

@@ -0,0 +1,24 @@
+/**
+ * 表达式与赋值族出口：把 TS 表达式 / 赋值语句降成引擎命令与脚本值。
+ *
+ * 轴 = 值层四件——条件与取值降级（`expr.ts`）、表达式降级与路径归约
+ * （`lower/` + `state-path.ts` + `probe.ts` + `engine-text.ts`）、
+ * 词表调用与命令发射（`words/`）、赋值与自增（`assign.ts`）。
+ */
+export {
+  emitAssignment,
+  translateIncrement,
+  translateVariableStatement,
+} from "./assign.ts";
+export { lowerCond, loweredToScriptValue, lowerValue } from "./expr.ts";
+export type { Lowered } from "./expr.ts";
+export { lowerExpr } from "./lower/index.ts";
+export { probeExpression } from "./probe.ts";
+export { statePath } from "./state-path.ts";
+export type { StatePath } from "./state-path.ts";
+export {
+  callWord,
+  emitCallCommand,
+  emitCommand,
+  resolveFunctionCallee,
+} from "./words/index.ts";

package/src/compiler/story-compiler/translate/expr/lower/index.ts

@@ -0,0 +1,4 @@
+/**
+ * 表达式降级族出口：外部只从这里取 `lowerExpr`。
+ */
+export { lowerExpr } from "./lower.ts";

package/src/compiler/story-compiler/translate/expr/lower/lower.ts

@@ -0,0 +1,266 @@
+/**
+ * 表达式降级主分发：把 TS 表达式逐个形态降成引擎表达式文本 + 优先级。
+ *
+ * 白名单外的形态一律 `diag` 报诊断后返回 undefined（fail-closed，不做猜测性转换）；
+ * 值位置不支持函数调用（词函数只能作为命令）。递归自调用，所以必须在同一文件内。
+ */
+import * as ts from "typescript";
+import { diag, lookupBinding, lookupScope } from "../../shared.ts";
+import type { BodyCtx } from "../../shared.ts";
+import { quoteEngineString, engineValueText } from "../engine-text.ts";
+import { statePath } from "../state-path.ts";
+import { PRECEDENCE, wrapOperand, foldNumericBinary } from "./numeric.ts";
+
+const BUILTIN_EXPR_FNS = new Set([
+  "random",
+  "min",
+  "max",
+  "abs",
+  "clamp",
+  "arrayGet",
+  "dictGet",
+  "optGet",
+  "len",
+]);
+/** 路径型内建：首参必须是路径字符串字面量（路径在构建期定型，不接受变量） */
+const PATH_BUILTINS = new Set(["arrayGet", "dictGet", "optGet", "len"]);
+
+export function lowerExpr(
+  ctx: BodyCtx,
+  expr: ts.Expression,
+): { text: string; prec: number } | undefined {
+  const sf = ctx.shared.mod.sf;
+  const root = ctx.shared.stateRoot;
+  if (ts.isNumericLiteral(expr)) {
+    const n = Number(expr.text);
+    if (!Number.isFinite(n)) {
+      diag(ctx, expr, `数字字面量 \`${expr.text}\` 不是有限数`);
+      return undefined;
+    }
+    return { text: String(n), prec: 9 };
+  }
+  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+    return { text: quoteEngineString(expr.text), prec: 9 };
+  }
+  if (expr.kind === ts.SyntaxKind.TrueKeyword) return { text: "true", prec: 9 };
+  if (expr.kind === ts.SyntaxKind.FalseKeyword)
+    return { text: "false", prec: 9 };
+  if (ts.isParenthesizedExpression(expr)) {
+    const inner = lowerExpr(ctx, expr.expression);
+    return inner === undefined ? undefined : { text: inner.text, prec: 9 };
+  }
+  if (ts.isIdentifier(expr)) {
+    const name = expr.text;
+    if (name === root) {
+      diag(ctx, expr, `${root} 必须以成员路径使用：${root}.player.gold`);
+      return undefined;
+    }
+    const scoped = lookupScope(ctx, name);
+    if (scoped !== undefined) {
+      if (scoped.kind === "index") {
+        return { text: String(scoped.value), prec: 9 };
+      }
+      if (scoped.kind === "function") {
+        diag(ctx, expr, `函数 \`${name}\` 不能作为值`);
+        return undefined;
+      }
+      return { text: name, prec: 9 };
+    }
+    const binding = lookupBinding(ctx, name);
+    if (binding === undefined) {
+      diag(
+        ctx,
+        expr,
+        `未知标识符 \`${name}\`（未声明的 let、模块 const、枚举或词函数）`,
+      );
+      return undefined;
+    }
+    switch (binding.kind) {
+      case "const": {
+        const v = binding.value;
+        if (v === null) {
+          diag(ctx, expr, "常量值为 null，不可下沉到表达式");
+          return undefined;
+        }
+        return { text: engineValueText(v), prec: 9 };
+      }
+      case "enum":
+        diag(ctx, expr, `枚举 \`${name}\` 必须以成员形式使用：${name}.成员`);
+        return undefined;
+      default:
+        diag(
+          ctx,
+          expr,
+          `\`${name}\` 不能用于表达式（${binding.kind} 绑定不可求值）`,
+        );
+        return undefined;
+    }
+  }
+  if (ts.isPropertyAccessExpression(expr)) {
+    const object = expr.expression;
+    if (ts.isIdentifier(object) && object.text !== root) {
+      const binding = lookupBinding(ctx, object.text);
+      if (binding?.kind === "enum") {
+        const value = binding.members.get(expr.name.text);
+        if (value === undefined) {
+          diag(
+            ctx,
+            expr,
+            `枚举 ${binding.name} 没有成员 \`${expr.name.text}\``,
+          );
+          return undefined;
+        }
+        if (value === null) {
+          diag(ctx, expr, "枚举成员值为 null，不可下沉到表达式");
+          return undefined;
+        }
+        return { text: engineValueText(value), prec: 9 };
+      }
+    }
+    const target = statePath(ctx, expr);
+    if (target === undefined) return undefined;
+    // 可选段脱糖：state.player?.nick → optGet("player.nick")（路径缺失返回 null，配 ?? 兜底）
+    if (target.optional) {
+      return { text: `optGet(${quoteEngineString(target.path)})`, prec: 9 };
+    }
+    return { text: target.path, prec: 9 };
+  }
+  if (ts.isElementAccessExpression(expr)) {
+    const target = statePath(ctx, expr.expression);
+    if (target === undefined) return undefined;
+    // `?.[` 不支持：内建缺失语义（null）已覆盖可选需求，不再叠加可选层
+    if (expr.questionDotToken !== undefined || target.optional) {
+      diag(ctx, expr, `${root} 下标访问不支持可选链 ?.[]`);
+      return undefined;
+    }
+    const arg = expr.argumentExpression;
+    if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg)) {
+      return {
+        text: `dictGet(${quoteEngineString(target.path)}, ${quoteEngineString(arg.text)})`,
+        prec: 9,
+      };
+    }
+    const index = lowerExpr(ctx, arg);
+    if (index === undefined) return undefined;
+    return {
+      text: `arrayGet(${quoteEngineString(target.path)}, ${index.text})`,
+      prec: 9,
+    };
+  }
+  if (ts.isPrefixUnaryExpression(expr)) {
+    const opText =
+      expr.operator === ts.SyntaxKind.ExclamationToken
+        ? "!"
+        : expr.operator === ts.SyntaxKind.MinusToken
+          ? "-"
+          : undefined;
+    if (opText === undefined) {
+      diag(ctx, expr, "一元表达式只支持 ! 与 -（自增自减只能作为独立语句）");
+      return undefined;
+    }
+    const operand = lowerExpr(ctx, expr.operand);
+    if (operand === undefined) return undefined;
+    return {
+      text: opText + wrapOperand(operand.text, operand.prec, 8),
+      prec: 8,
+    };
+  }
+  if (ts.isBinaryExpression(expr)) {
+    const raw = expr.operatorToken.getText(sf);
+    const op = raw === "===" ? "==" : raw === "!==" ? "!=" : raw;
+    const prec = PRECEDENCE[op];
+    if (prec === undefined) {
+      diag(ctx, expr, `二元运算符 \`${raw}\` 不在引擎表达式文法内`);
+      return undefined;
+    }
+    const left = lowerExpr(ctx, expr.left);
+    const right = lowerExpr(ctx, expr.right);
+    if (left === undefined || right === undefined) return undefined;
+    const folded = foldNumericBinary(left.text, right.text, op);
+    if (folded !== undefined) return { text: folded, prec: 9 };
+    return {
+      text: `${wrapOperand(left.text, left.prec, prec)} ${op} ${wrapOperand(right.text, right.prec, prec + 1)}`,
+      prec,
+    };
+  }
+  if (ts.isConditionalExpression(expr)) {
+    const cond = lowerExpr(ctx, expr.condition);
+    const whenTrue = lowerExpr(ctx, expr.whenTrue);
+    const whenFalse = lowerExpr(ctx, expr.whenFalse);
+    if (cond === undefined || whenTrue === undefined || whenFalse === undefined)
+      return undefined;
+    return {
+      text: `${wrapOperand(cond.text, cond.prec, 1)} ? ${wrapOperand(whenTrue.text, whenTrue.prec, 2)} : ${wrapOperand(whenFalse.text, whenFalse.prec, 1)}`,
+      prec: 1,
+    };
+  }
+  if (ts.isCallExpression(expr)) {
+    if (
+      ts.isIdentifier(expr.expression) &&
+      lookupBinding(ctx, expr.expression.text) === undefined &&
+      BUILTIN_EXPR_FNS.has(expr.expression.text)
+    ) {
+      const fnName = expr.expression.text;
+      const args: string[] = [];
+      if (PATH_BUILTINS.has(fnName)) {
+        // 路径型内建首参在构建期定型：state 路径降级成路径串，或直接写字符串字面量；
+        // let 变量等运行期值当路径无法进快照 ⇒ fail-closed
+        const first = expr.arguments[0];
+        const asPath =
+          first !== undefined && ts.isPropertyAccessExpression(first)
+            ? statePath(ctx, first)
+            : undefined;
+        let firstText: string | undefined;
+        if (asPath !== undefined) {
+          if (asPath.optional) {
+            diag(ctx, first!, `${fnName} 路径不支持可选链`);
+            return undefined;
+          }
+          firstText = quoteEngineString(asPath.path);
+        } else if (
+          first !== undefined &&
+          (ts.isStringLiteral(first) ||
+            ts.isNoSubstitutionTemplateLiteral(first))
+        ) {
+          firstText = quoteEngineString(first.text);
+        } else {
+          diag(
+            ctx,
+            expr,
+            `${fnName} 首参必须是路径（${root} 路径或字符串字面量）`,
+          );
+          return undefined;
+        }
+        args.push(firstText);
+        for (const arg of expr.arguments.slice(1)) {
+          const lowered = lowerExpr(ctx, arg);
+          if (lowered === undefined) return undefined;
+          args.push(lowered.text);
+        }
+        return { text: `${fnName}(${args.join(", ")})`, prec: 9 };
+      }
+      for (const arg of expr.arguments) {
+        const lowered = lowerExpr(ctx, arg);
+        if (lowered === undefined) return undefined;
+        args.push(lowered.text);
+      }
+      return { text: `${fnName}(${args.join(", ")})`, prec: 9 };
+    }
+    diag(
+      ctx,
+      expr,
+      "值位置的函数调用不支持：词函数只能作为命令，子程序返回值请用语句级 `const x = f(1)`（call into 结果通道），表达式内建函数仅 random/min/max/abs/clamp/arrayGet/dictGet/optGet/len",
+    );
+    return undefined;
+  }
+  if (ts.isTemplateExpression(expr)) {
+    diag(
+      ctx,
+      expr,
+      "模板串只能作为字符串值（say 文本等），不能用于条件/算术表达式",
+    );
+    return undefined;
+  }
+  diag(ctx, expr, "表达式不在引擎文法白名单内（TS-only 结构不支持）");
+  return undefined;
+}

package/src/compiler/story-compiler/translate/expr/lower/numeric.ts

@@ -0,0 +1,56 @@
+/**
+ * 数字与优先级的构建期处理：运算符优先级表、按优先级加括号、数字字面量折叠。
+ *
+ * 折叠只处理「两侧都是数字字面量」的算术式；除/模零不折叠，留给运行期文法校验（fail-closed）。
+ */
+export const PRECEDENCE: Record<string, number> = {
+  "||": 2,
+  "??": 1,
+  "&&": 3,
+  "==": 4,
+  "!=": 4,
+  "<": 5,
+  ">": 5,
+  "<=": 5,
+  ">=": 5,
+  "+": 6,
+  "-": 6,
+  "*": 7,
+  "/": 7,
+  "%": 7,
+};
+
+export function wrapOperand(
+  child: string,
+  childPrec: number,
+  parentPrec: number,
+): string {
+  return childPrec < parentPrec ? `(${child})` : child;
+}
+
+const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
+
+/** 两侧均为数字字面量的算术二元式在构建期折叠成单值（除/模零不折叠，留给运行期文法校验）。 */
+export function foldNumericBinary(
+  left: string,
+  right: string,
+  op: string,
+): string | undefined {
+  if (!NUMERIC_TEXT.test(left) || !NUMERIC_TEXT.test(right)) return undefined;
+  const a = Number(left);
+  const b = Number(right);
+  switch (op) {
+    case "+":
+      return String(a + b);
+    case "-":
+      return String(a - b);
+    case "*":
+      return String(a * b);
+    case "/":
+      return b === 0 ? undefined : String(a / b);
+    case "%":
+      return b === 0 ? undefined : String(a % b);
+    default:
+      return undefined;
+  }
+}

package/src/compiler/story-compiler/translate/expr/probe.ts

@@ -0,0 +1,23 @@
+/**
+ * 引擎表达式文法探针：把候选文本交给引擎求值器试跑，判断是否落在引擎文法内。
+ *
+ * 探针只关心文法（`evaluateExpression` 抛错即不合法），结果按源串缓存——
+ * 同一表达式在构建期会被反复试探，缓存是必须的（模块级单例，不可复制成两份）。
+ */
+import { evaluateExpression } from "@lingfan-engine/core";
+
+const probeCache = new Set<string>();
+
+/** 探针免检前缀：路径型内建的实参由编译器构造性生成（文法必然合法），运行期语义不归探针管 */
+const PROBE_LENIENT = /^(arrayGet|dictGet|optGet|len)\(/;
+
+export function probeExpression(src: string): boolean {
+  if (probeCache.has(src) || PROBE_LENIENT.test(src)) return true;
+  try {
+    evaluateExpression(src, () => ({ found: true as const, value: 1 }));
+    probeCache.add(src);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/compiler/story-compiler/translate/expr/state-path.ts

@@ -0,0 +1,47 @@
+/**
+ * state 成员表达式的路径归约：把 `state.a.b?.c` 收成引擎侧的点路径 + 可选段标记。
+ *
+ * 为什么单独一层：值降级（`lower/lower.ts`）与命令族（`assign.ts` / `stmt/control-flow.ts`）
+ * 都要判「这是不是 state 路径」，判错就会把运行期值当构建期路径写进快照。
+ */
+import * as ts from "typescript";
+import { diag } from "../shared.ts";
+import type { BodyCtx } from "../shared.ts";
+
+export interface StatePath {
+  /** 根名剥离后的点路径（如 state.player.gold → "player.gold"） */
+  path: string;
+  /** 链上存在 `?.`（可选段）；值位置会脱糖为 optGet，写位置/for-of 集合不支持 */
+  optional: boolean;
+}
+
+export function statePath(
+  ctx: BodyCtx,
+  expr: ts.Expression,
+): StatePath | undefined {
+  const root = ctx.shared.stateRoot;
+  const parts: string[] = [];
+  let cur: ts.Expression = expr;
+  let optional = false;
+  for (;;) {
+    if (ts.isPropertyAccessExpression(cur)) {
+      if (cur.questionDotToken !== undefined) optional = true;
+      parts.unshift(cur.name.text);
+      cur = cur.expression;
+      continue;
+    }
+    if (ts.isIdentifier(cur) && cur.text === root) {
+      if (parts.length === 0) {
+        diag(ctx, expr, `${root} 必须以成员路径使用：${root}.player.gold`);
+        return undefined;
+      }
+      return { path: parts.join("."), optional };
+    }
+    diag(
+      ctx,
+      expr,
+      `成员表达式只支持 ${root} 路径（如 ${root}.player.gold）或枚举成员访问`,
+    );
+    return undefined;
+  }
+}

package/src/compiler/story-compiler/translate/expr/words/arg.ts

@@ -0,0 +1,87 @@
+import * as ts from "typescript";
+import { diag, lookupBinding } from "../../shared.ts";
+import type { BodyCtx } from "../../shared.ts";
+import { lowerValue, loweredToScriptValue } from "../expr.ts";
+import { wordCalleeName } from "./callee.ts";
+import type { WordDispatch } from "./dispatch.ts";
+
+// —— 词实参求值（静态求值 + 嵌套命令递归）——
+
+export function evaluateWordArg(
+  ctx: BodyCtx,
+  expr: ts.Expression,
+  dispatch: WordDispatch,
+): unknown {
+  if (ts.isIdentifier(expr) && expr.text === "undefined") return undefined;
+  if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) {
+    diag(ctx, expr, "函数实参仅 staticFor 支持");
+    return undefined;
+  }
+  if (ts.isIdentifier(expr)) {
+    const binding = lookupBinding(ctx, expr.text);
+    if (binding?.kind === "cell") {
+      return { name: binding.guard };
+    }
+  }
+  if (ts.isArrayLiteralExpression(expr)) {
+    const out: unknown[] = [];
+    for (const el of expr.elements) {
+      if (ts.isSpreadElement(el)) {
+        diag(ctx, el, "展开实参不支持");
+        return undefined;
+      }
+      const item = evaluateWordArg(ctx, el, dispatch);
+      const isExplicitUndefined =
+        ts.isIdentifier(el) && el.text === "undefined";
+      if (item === undefined && !isExplicitUndefined) return undefined;
+      out.push(item);
+    }
+    return out;
+  }
+  if (ts.isObjectLiteralExpression(expr)) {
+    const out: Record<string, unknown> = {};
+    for (const prop of expr.properties) {
+      if (!ts.isPropertyAssignment(prop)) {
+        diag(
+          ctx,
+          prop,
+          "对象实参只支持 key: value 形式（不支持展开/方法/计算键）",
+        );
+        return undefined;
+      }
+      const key =
+        ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+          ? prop.name.text
+          : undefined;
+      if (key === undefined) {
+        diag(ctx, prop, "对象实参键必须是标识符或字符串字面量");
+        return undefined;
+      }
+      const value = evaluateWordArg(ctx, prop.initializer, dispatch);
+      const isExplicitUndefined =
+        ts.isIdentifier(prop.initializer) &&
+        prop.initializer.text === "undefined";
+      if (value === undefined && !isExplicitUndefined) return undefined;
+      out[key] = value;
+    }
+    return out;
+  }
+  if (ts.isCallExpression(expr)) {
+    // 值位置的词调用也得分具名与 `script.` 命名空间两种写法——`option(...)` 能当菜单
+    // 选项、`script.option(...)` 同样是同一个词，落到 lowerValue 只会得到「值位置的函数
+    // 调用不支持」，而真正该报的是这个词自己的实参问题。
+    const wordName = wordCalleeName(ctx, expr);
+    if (wordName !== undefined) {
+      const ops = dispatch.command(ctx, expr);
+      if (ops.length === 0) return undefined;
+      if (ops.length !== 1) {
+        diag(ctx, expr, `值位置词调用 \`${wordName}\` 必须恰好产出一个命令`);
+        return undefined;
+      }
+      return ops[0];
+    }
+  }
+  const lowered = lowerValue(ctx, expr);
+  if (lowered === undefined) return undefined;
+  return loweredToScriptValue(lowered);
+}