Flow 代码现代化:用 unknown 取代 mixed —— 以 Flow AI Evals 的 modernize_008_mixed 评测为例
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';
}
改造要点:
- 仅修改函数签名的参数类型标注:
value: mixed→value: unknown; - 函数体完全不动——
typeof收窄、Array.isArray收窄、字符串拼接逻辑全部保持原样,因为unknown与mixed的收窄语义一致; - 保留
@flowpragma,确保文件仍以 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):
compile_swebench.py对input/与ideal/做 diff,生成该实例的金标准补丁,并为每个评分器组装 TAP 脚本;run_swebench.py在临时工作目录中应用补丁,运行评分器;- 两个
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 语法现代化练习集。