Flow 代码现代化:用 unknown 取代 mixed —— 以 Flow AI Evals 的 modernize_008_mixed 评测为例

原创2026-09-21 22:38:001,708 阅读
文章标签:开发工具静态分析代码质量

Flow 代码现代化:用 unknown 取代 mixed —— 以 Flow AI Evals 的 modernize_008_mixed 评测为例

导读

在 Flow(JavaScript 的静态类型方言)中,mixed 与 unknown 是两个极易混淆的"顶层类型":它们都要求使用者在消费值之前先做类型收窄(refinement),但语义定位截然不同。本文以当前仓库 evals/evals/05_code_generation/modernize_008_mixed 这个 AI 代码生成评测任务为切入点,完整演示如何将一个使用 mixed 的函数现代化改造为使用 unknown,并借助 Flow 的 AST 检查机制验证改造结果。读完本文,你将掌握 mixed 与 unknown 的本质差异、现代化的迁移步骤,以及 Flow AI Evals 评测体系如何自动判定"是否真正完成了现代化"。

任务背景:AI Evals 评测目录结构

在开始改造之前,先理解这个评测任务在仓库中的组织方式。每个 eval 都遵循 SWE-bench 风格的结构,位于 evals/<category>/<name>/ 目录下:

  • prompt.md —— 展示给模型的任务描述,只说明"做什么",从不提示"用 Flow 怎么写";
  • config.json —— 元数据(名称、分类、标签、难度)与评测专用的评分器配置;
  • input/ —— 起始文件(本任务为 main.js);
  • ideal/ —— 参考解法,即"金标准"补丁,用于 dry-run 验证。

modernize_008_mixed 属于 evals/05_code_generation 分类,其 prompt.md 全文只有一句话:

Modernize the code in `main.js`.

从源码结构看,这是整个 modernize(现代化)系列评测的统一提示语——同一分类下还有 modernize_001_property_type、modernize_003_keys、modernize_006_nonmaybe 等 20 个评测,它们共享同一句 prompt,但各自测试一个不同的 Flow 语法现代化点(例如 $PropertyType → T['k']、$Keys<T> → keyof T、$NonMaybeType<T> → NonNullable<T>)。评测的核心约束在于:提示只描述行为目标,模型必须自己推断出应该使用的现代 Flow 语法,这正是对 LLM 代码生成能力的有效测试。

待改造代码:一个用 mixed 描述值的函数

input/main.js 的完整内容如下(@flow 严格模式已开启):

/**
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 * ...
 * @flow
 */

export function describeValue(value: mixed): string {
  if (typeof value === 'string') {
    return 'text(' + String(value.length) + ')';
  }
  if (typeof value === 'number') {
    return 'number(' + String(value) + ')';
  }
  if (Array.isArray(value)) {
    return 'array(' + String(value.length) + ')';
  }
  return 'unknown';
}

describeValue 接收一个任意类型的值,通过 typeof 与 Array.isArray 进行运行时类型收窄,分别生成 text(n)、number(n)、array(n) 的描述字符串,无法识别时返回 'unknown'。这段代码完全符合 mixed 的经典用法——只读取、不操作,在消费前必须收窄类型。

核心知识点:mixed 与 unknown 的区别

改造动作本身只有一个词:把参数类型从 mixed 换成 unknown。但理解"为什么这是一次现代化"是本文的重点。

在 Flow 中:

  • mixed 是历史悠久的"顶层类型",任何值都可以赋值给它;要使用它必须经过类型收窄。它是 Flow 特有的语法(MixedTypeAnnotation)。
  • unknown 是更现代的"顶层类型",语义上与 mixed 几乎等价——同样接收一切值、同样需要收窄后才能使用。但它来自 TypeScript 生态,是跨工具链通用的标准语法(UnknownTypeAnnotation)。

从 Flow 的角度看,unknown 并不是 mixed 的严格子集或超集,二者的可赋值性规则非常接近:除了 mixed 与 unknown 之间以及 any 之外,其他类型都不能直接赋值给它们。差别主要体现在生态系统与工具链互操作层面:

  • 跨语言一致性:TypeScript 3.0 引入 unknown 后,它成为社区事实标准。使用 unknown 可以让 Flow 代码与 TS 代码在类型层面无缝对齐,降低迁移与协作成本。
  • 语义清晰度:unknown 的名字更直白地传达"我对此一无所知"的含义;而 mixed 容易让人误以为"各种类型混在一起"。
  • 现代化方向:Flow 官方与社区正逐步推动从 mixed 走向 unknown,mixed 被标记为 deprecated 风格的旧式写法(本评测的 tags 即包含 deprecated、unknown、mixed)。

现代化改造:把 mixed 替换为 unknown

参考解法(ideal/main.js)如下:

export function describeValue(value: unknown): string {
  if (typeof value === 'string') {
    return 'text(' + String(value.length) + ')';
  }
  if (typeof value === 'number') {
    return 'number(' + String(value) + ')';
  }
  if (Array.isArray(value)) {
    return 'array(' + String(value.length) + ')';
  }
  return 'unknown';
}

改造要点:

  1. 仅修改函数签名的参数类型标注:value: mixed → value: unknown;
  2. 函数体完全不动——typeof 收窄、Array.isArray 收窄、字符串拼接逻辑全部保持原样,因为 unknown 与 mixed 的收窄语义一致;
  3. 保留 @flow pragma,确保文件仍以 Flow 严格模式被检查。

改造后函数行为不变,但类型层面已从"Flow 专用旧语法"切换到"跨生态通用现代语法"。

自动验证:AST 节点检查如何确认现代化完成

config.json 是理解"评测如何判定成功"的关键:

{
  "metadata": {
    "name": "modernize_008_mixed",
    "category": "code_generation",
    "tags": ["flow", "modernize", "code_generation", "deprecated", "unknown", "mixed"],
    "difficulty": "easy"
  },
  "grading": {
    "graders": [
      { "type": "contains_ast_node_type", "query": "UnknownTypeAnnotation" },
      { "type": "contains_ast_node_type", "query": "MixedTypeAnnotation", "negate": true }
    ]
  }
}

评分逻辑由两个 AST 检查器组成:

  • 正向检查:生成的代码 AST 中必须存在 UnknownTypeAnnotation 节点——证明 unknown 确实被使用了;
  • 反向检查:AST 中不得存在 MixedTypeAnnotation 节点(negate: true)——证明旧的 mixed 已彻底移除。

这种"必须出现新语法、必须消失旧语法"的双向断言,防止模型偷懒只做表面修改(例如把 mixed 换成 any 并通过类型检查,或同时保留两种写法)。

contains_ast_node_type 评分器实现在 evals/graders/contains_ast_node_type.sh,它是 ast_query 评分器的薄封装:对目标文件运行 flow ast 生成 JSON 形式的 AST,再用 jq 以 .type == "UnknownTypeAnnotation" 这类选择器查询节点是否存在。这也是评测体系中所有 AST 类评分器(ast_query、no_any、no_commonjs)的共同机制,详见 evals/README.md 的 Grading 一节。

此外,基线评分器会按分类自动附加,05_code_generation 分类下的任务默认还会执行 flow_check(要求 flow 类型检查零错误)与 file_modified(要求目标文件确实被修改)等检查,确保改造结果不仅是"语法正确",而且是"类型正确且真的发生了变更"。

如何运行与验证这个评测

在仓库的 evals/ 目录下,可以通过 Makefile 与 run_swebench.py 运行评测。由于本文只讲解查看与运行方式,不修改仓库,推荐使用 dry-run(金标准补丁验证)模式:

# 在 evals/ 目录下
npm install                       # 安装 flow-bin,提供 node_modules/.bin/flow

# 编译 + 应用金标准补丁 + 评分(不调用任何模型 API)
make validate ARGS="--eval modernize_008_mixed"

# 或指定本地构建的 Flow 二进制
python3 run_swebench.py --flow-bin /path/to/flow --dry-run --eval modernize_008_mixed

运行原理(见 evals/README.md):

  1. compile_swebench.py 对 input/ 与 ideal/ 做 diff,生成该实例的金标准补丁,并为每个评分器组装 TAP 脚本;
  2. run_swebench.py 在临时工作目录中应用补丁,运行评分器;
  3. 两个 contains_ast_node_type 检查器分别断言 UnknownTypeAnnotation 存在、MixedTypeAnnotation 不存在,全部通过即判为 pass。

make validate 别名 make dry-run,是确认评测格式正确性的最快路径——如果金标准补丁都无法通过评分器,说明评测本身有问题。

总结:从 mixed 到 unknown 的迁移清单

  • 对任意值只做"读取 + 收窄"的函数参数,mixed 与 unknown 可以无痛互换,函数体无需改动;
  • 迁移后应确认文件中不再出现 MixedTypeAnnotation,且出现 UnknownTypeAnnotation;
  • unknown 与 TypeScript 生态一致,是更现代的顶层类型选择;
  • 在 Flow AI Evals 中,这类现代化改造通过 AST 节点正反向断言自动验证,杜绝表面修改。

参考仓库中的其他 modernize 评测(如 modernize_001_property_type、modernize_003_keys、modernize_006_nonmaybe)可以举一反三:同样的"Modernize the code in main.js"提示,分别对应 $PropertyType → 索引访问、$Keys → keyof、$NonMaybeType → NonNullable 等迁移方向,构成了系统化的 Flow 语法现代化练习集。

登录后查看全文
flow