18 代码走读实录

项目：vitest-playground ｜ 版本：v1.2 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析

本篇做一次"带码走读"：挑出两到三个核心文件，贴出真实代码片段，逐段解读，并在每段之后回答一个问题——"这段代码教会我们什么"。与《07-模块详解》的分工是：07 篇按模块给全景函数清单与机制综述（是"地图"），本篇选一条主链路逐行走（是"实测徒步"），两者引用同一些行号，可对照阅读。走读对象有三个：其一，vitestServerRunner.ts 的 handleRunVitest 主链路——一次请求从 HTTP 到结果回传的完整生命周期（沙箱装配 → spawn → 结果解析 → 清理）；其二，同文件的 buildLessonFiles 装配逻辑——防篡改契约的物理实现；其三，前端 TDD 自动批改链路——chapter.tsx 的 handleRunTest 加 runner.ts 加 CodeEditor.tsx 的 markers 回路。三段走读串起来恰好是一次"TDD 课时点击运行"的端到端旅程：前端提交 → 服务端校验装配 → 子进程执行 → 结果回传渲染。全部代码引用保持与源文件一致（行号以 2026-10-06 的源码为准，vitestServerRunner.ts 共 485 行）。

走读一：handleRunVitest 主链路——一条快速失败链的完整生命周期

1.1 入口：方法白名单与请求体读取

/** Vite 中间件处理函数 */
export async function handleRunVitest(req: IncomingMessage, res: ServerResponse): Promise<void> {
  if (req.method !== 'POST') {
    res.statusCode = 405;
    res.end('Method Not Allowed');
    return;
  }

  let body: RunBody;
  try {
    body = await readBody(req);
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    sendJson(res, 400, failResult(`请求无效: ${msg}`));
    return;
  }

（vitestServerRunner.ts 第 437-451 行）

入口只有两个动作，但每个都有讲究。方法检查放在最前面且返回纯文本 405——不带 JSON body，因为它甚至不值得被客户端程序化处理；readBody 的所有失败（非法 JSON、超过 5MB）都被归一成 400 加 failResult 构造的失败体，异常消息直接拼进 output，这就是《03-接口设计》§4 所说"错误文案即排障线索"约定的实现点。注意 e instanceof Error ? e.message : String(e) 这个三元的写法：Node 的事件回调可能抛出任意值，这段防御让 unknown 类型异常也能安全变成字符串，全文（包括第 479-481 行）出现两次，是同一作者手笔的一致性痕迹。

1.2 readBody：5MB 上限与防双重 settle

function readBody(req: IncomingMessage): Promise<RunBody> {
  return new Promise((resolve, reject) => {
    let data = '';
    let settled = false; // 防双重 settle；超限销毁后丢弃残余 chunk，不再拼接
    req.on('data', (chunk) => {
      if (settled) return;
      data += chunk;
      if (data.length > 5 * 1024 * 1024) {
        settled = true;
        req.destroy();
        reject(new Error('提交内容过大'));
      }
    });
    req.on('end', () => {
      if (settled) return;
      try {
        resolve(JSON.parse(data) as RunBody);
      } catch {
        reject(new Error('请求体不是合法 JSON'));
      }
    });
    req.on('error', (err) => {
      if (!settled) {
        settled = true;
        reject(err);
      }
    });
  });
}

（第 245-273 行）

这是教科书级的流式读取防御，三处细节值得放大。第一，settled 标志的存在理由：超限调用 req.destroy() 后，底层流可能还会吐出残余 chunk 或触发 end/error，若不挡住就会在 reject 之后再次 resolve/reject——Promise 只认第一次 settle，但第二次的 JSON.parse 仍会白做，而且语义上"已销毁的请求不应再产生任何结果"。第二，5MB 判定用 data.length（UTF-16 码元数）近似字节数，偏差方向是保守的（多字节字符实际允许的字节量更小），对 DoS 防御这个目的恰好无害——《08-安全与权限设计》§6 把它列为"无风险但值得知道"的实现细节。第三，JSON.parse 的 try/catch 只包在 end 分支里，非法 JSON 的错误消息"请求体不是合法 JSON"与超限的"提交内容过大"都能经 1.1 的 catch 变成 400 文案——错误分类在抛出点就完成了，HTTP 层不必再猜。

这段代码教会我们什么：处理不可信的流式输入时，"上限判定 + 主动断流 + settle 幂等"三件套应该成为肌肉记忆。很多同类实现会漏掉 destroy 后的残余事件处理，测试也很难覆盖这个时序——本仓的「超过 5MB 的请求体被 400 拒绝」用例专门"先挂监听再灌 5MB+1 字节"来踩这个时序（《08》§4），这个测试写法本身值得抄走。

1.3 快速失败链的中段：字段校验、课时寻址、并发闸门

  if (
    !body ||
    typeof body !== 'object' ||
    typeof body.chapterKey !== 'string' ||
    typeof body.lessonKey !== 'string' ||
    typeof body.code !== 'string'
  ) {
    sendJson(res, 400, failResult('请求无效: 需要 chapterKey / lessonKey / code 三个字符串字段'));
    return;
  }
  const lesson = findLesson(body.chapterKey, body.lessonKey);
  if (!lesson) {
    sendJson(res, 400, failResult(`未知课时: ${body.chapterKey}/${body.lessonKey}`));
    return;
  }

  try {
    await limiter.acquire();
  } catch {
    sendJson(res, 429, failResult('运行排队已满，请稍后再试'));
    return;
  }

（第 452-473 行）

这是"越廉价的检查越靠前"原则的现场。三个条件的排列有明确的成本梯度：类型校验是纯内存比较（纳秒级）；findLesson 要遍历 16 章 56 课时的数组（微秒级）；limiter.acquire() 最贵——它可能挂起请求占用一个排队位。把 429 放在 400 之后意味着：非法请求永远不消耗排队槽位，队列里全是"值得跑"的请求。字段校验的条件组合也有一个隐蔽的边界知识：typeof null === 'object'，所以光写 typeof body !== 'object' 拦不住 null，必须加上 !body || 前置；数组同样是 object，但没有字段会自然落到 400——这半行代码浓缩了 JS 类型系统的两个著名坑，且都有测试用例（「JSON null / 数组 body 返回 400 而非 500」）锁定。

1.4 执行与兜底：装配、运行、finally 释放

  try {
    const files = buildLessonFiles(lesson, body.code);
    const { coverage, benchmark } = resolveRunOptions(lesson);
    const result = await runInSandbox(files, { coverage, benchmark });
    sendJson(res, 200, result);
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    sendJson(res, 500, failResult(`服务端错误: ${msg}`));
  } finally {
    limiter.release();
  }
}

（第 474-485 行）

主链路的最后一跳只有四行有效代码，却完成了三重职责的委托：buildLessonFiles 负责装配（走读二）、runInSandbox 负责执行与清理（走读三的前半）、sendJson 统一响应出口。异常兜底的语义边界要看清：这个 catch 只能捕获"装配/执行阶段未被预期的异常"（如文件名校验抛错——它发生在 runInSandbox 入口），而运行本身的失败（超时、断言失败、解析失败）都已经在内层被转成 success:false 的 RunResult 正常 resolve 了，所以 500 的实际触发面非常窄——能漏到这里的基本是实现 bug，这与《07-模块详解》§2 对 .catch(next) 语义的分析互相印证。finally { limiter.release() } 是并发闸门的"必经释放点"：无论 200/500/异常，槽位都会归还或移交——它必须与 acquire 分开写在两个 try 块里，否则 acquire 抛 RUNNER_BUSY（未拿到槽位）也会触发 release，凭空制造幻影槽位。

这段代码教会我们什么：HTTP 门面函数的正确姿势是"快速失败链 + 单一执行区 + finally 对称释放"，错误分类尽量在抛出点完成，让门面保持"读起来就是请求的生命周期"的形态。acquire/release 的 try 边界划分是并发编程里最容易写错的一行——本仓把它写对了，并且靠「满载排队、队满拒绝、释放移交」的时序测试钉死。

1.5 执行器内核：runInSandbox 与 spawnVitest

export async function runInSandbox(
  files: Record<string, string>,
  options: RunInSandboxOptions = {},
): Promise<RunResult> {
  const { coverage = false, benchmark = false, timeoutMs = RUN_TIMEOUT } = options;
  // 防线纵深：运行超时即便被注入也不得超过生产默认 RUN_TIMEOUT
  const effectiveTimeoutMs = Math.min(timeoutMs, RUN_TIMEOUT);
  const names = Object.keys(files ?? {});
  if (names.length === 0) return failResult('缺少文件');
  if (names.length > MAX_FILES) return failResult(`文件数量超过上限（${MAX_FILES}）`);
  for (const name of names) sanitizeEntryName(name);

  const runDir = await makeRunDir();
  try {
    writeRunConfig(runDir, coverage, benchmark);
    for (const [name, contents] of Object.entries(files)) {
      await fs.promises.writeFile(path.join(runDir, name), contents);
    }
    return await spawnVitest(runDir, { coverage, benchmark, timeoutMs: effectiveTimeoutMs });
  } finally {
    await fs.promises.rm(runDir, { recursive: true, force: true });
  }
}

（第 292-314 行）

函数体是一个"校验头 + finally 三明治"。校验头的三道检查（空文件表、超 20 文件、逐名白名单）全部发生在建目录之前——非法请求连磁盘都不碰；Math.min(timeoutMs, RUN_TIMEOUT) 这一行是"参数可以注入、防线不可谈判"的宣言：测试可以注入 2000ms 来快速验证超时路径，但任何调用方都无法把超时放大到 60 秒以上，注释原话"防线纵深"点明这是有意为之。try/finally 的结构保证了目录生命周期与本次调用严格绑定——spawn 抛错、超时、正常返回，任何路径都会走到 fs.promises.rm；{ recursive: true, force: true } 让删除幂等且不因目录已消失而抛错。还有一个容易忽略的点：文件写入用了 await 逐个写而不是 Promise.all——顺序写保证了写盘的确定性（虽然对本场景并发写也无害），更重要的是保持代码与"文件表遍历"的简单心智模型一致。

1.6 子进程：spawn 选项与超时整杀

    const child = spawn('node', [VITEST_BIN, ...args], {
      cwd: runDir,
      env: buildChildEnv(runDir),
      detached: true, // 独立进程组：超时可整组 kill，避免 vitest worker 孤儿
      stdio: ['ignore', 'pipe', 'pipe'],
    });

    let out = '';
    // 尾部窗口：只累计前 1MB 输出，防用户海量 stdout 打爆宿主内存（解析主路径是 result.json，消费方只读尾部 slice(-2000)）
    child.stdout.on('data', (d) => {
      if (out.length < 1_000_000) out += d.toString();
    });
    child.stderr.on('data', (d) => {
      if (out.length < 1_000_000) out += d.toString();
    });

    let killed = false;
    const killGroup = () => {
      killed = true;
      try {
        if (child.pid) process.kill(-child.pid, 'SIGKILL');
      } catch {
        /* 进程组可能已退出 */
      }
    };

    const timer = setTimeout(() => {
      killGroup();
      resolve(failResult(`Vitest 运行超时（${opts.timeoutMs / 1000}s，可能有用例陷入死循环）:\n${out.slice(-2000)}`));
    }, opts.timeoutMs);

    child.on('close', () => {
      clearTimeout(timer);
      if (killed) return; // 超时分支已 resolve
      const coverageData = opts.coverage ? readCoverage(runDir) : undefined;
      resolve(finishRun(runDir, out, coverageData, opts.benchmark));
    });

（第 355-391 行，节选）

spawn 选项四件套各有出处：cwd 指向沙箱（vitest 的 --root 也指向它）；env 是白名单构造（buildChildEnv，绝不过 process.env）；detached: true 建立独立进程组，这是第 375 行 process.kill(-child.pid, 'SIGKILL') 能整组击杀的前提——负数 pid 表示"杀整个进程组"，vitest 内部 fork 的 worker 一个都跑不掉；stdio[0] 设为 ignore，因为测试进程不需要 stdin。stdout/stderr 汇入同一个 out 字符串，1MB 上限的判定写在追加条件里（out.length < 1_000_000 才追加），意味着超限后 chunk 仍被接收但直接丢弃——不暂停流、不背压，用最笨的方式保证内存有界。超时与 close 的竞争关系用 killed 标志仲裁：超时分支先 resolve，close 到来时 if (killed) return 直接退出——Promise 二次 resolve 虽然无害（幂等），但守卫避免了重复读文件的浪费，也让"resolve 责任归属"在代码上一目了然。一个已确认的小瑕疵顺带记录：close 回调没有捕获退出码参数，finishRun 硬编码 exitCode 为 0（第 410 行），导致 parseVitestJson 里"进程退出码非 0"的诊断分支不可达（《13-技术债务与演进建议》问题 10）。

1.7 结果分派：finishRun 的三级瀑布

function finishRun(runDir: string, out: string, coverageData: CoverageSummary | undefined, benchmark: boolean): RunResult {
  if (benchmark) {
    return parseBenchTable(out);
  }
  try {
    const resultPath = path.join(runDir, 'result.json');
    if (fs.existsSync(resultPath)) {
      const raw = fs.readFileSync(resultPath, 'utf-8');
      return parseVitestJson(raw, 0, coverageData);
    }
  } catch {
    /* 回退到 stdout 解析 */
  }
  const raw = extractJson(out);
  if (!raw) {
    return { ...failResult(`无法从输出解析测试结果，Vitest 输出:\n${out.slice(-2000)}`), coverage: coverageData };
  }
  return parseVitestJson(raw, 0, coverageData);
}

（第 402-420 行）

这是 ADR-004"结果走文件不走 stdout"的最终落点。分派优先级是：bench 走表格解析（Vitest 4.1.8 无 bench JSON reporter，源码注释有版本考古）→ 普通运行优先读 result.json 文件 → 文件不存在才从 stdout 截取 JSON 片段 → 都不行返回带尾部 2000 字符的失败结果。注意 catch 块是空的但注释写了用途——读取失败（文件损坏、权限问题）静默降级到 stdout 回退，这是"解析容错在读取侧"惯例（《04-数据模型》§9）的体现。out.slice(-2000) 的取尾操作解释了 1.6 里"只累计前 1MB"看似矛盾的设计：前 1MB 里最早的输出通常是启动日志，而排障最有价值的是崩溃前的最后输出——在 1MB 窗口内取尾部是对"内存有界"与"信息可用"的折中，极端场景（输出远超 1MB）下真正的错误尾部仍可能丢失（《08》§6 问题 7 已记录）。

这段代码教会我们什么（针对 1.5-1.7 三段）：执行器内核的三个品质——目录生命周期用 finally 绑定、进程超时用进程组整杀加标志仲裁、结果解析用文件优先的瀑布——合起来就是"单次调用自足"这个架构决策在代码层的全部代价与收益。防线（Math.min 钳制、1MB 截断、白名单校验）都不是独立函数而是内联在关键路径上，靠近它们保护的对象，这比集中式"安全模块"更难被绕过。

走读二：buildLessonFiles——防篡改装配的四行核心

export function buildLessonFiles(lesson: Lesson, userCode: string): Record<string, string> {
  const isJsdom = lesson.environment === 'jsdom';
  const ext = isJsdom ? 'tsx' : 'ts';
  const pragma = isJsdom ? '// @vitest-environment happy-dom\n\n' : '';
  const files: Record<string, string> = {};
  // 与旧前端 trim 守卫等价：纯空白的 grader/hiddenGrader 视为不存在
  if (lesson.grader?.trim()) {
    files[`lesson.${ext}`] = userCode;
    files[`lesson.spec.${ext}`] = pragma + lesson.grader;
    if (lesson.hiddenGrader?.trim()) files[`lesson.hidden.spec.${ext}`] = pragma + lesson.hiddenGrader;
  } else {
    files[`lesson.spec.${ext}`] = pragma + userCode;
    if (lesson.hiddenGrader?.trim()) files[`lesson.hidden.spec.${ext}`] = pragma + lesson.hiddenGrader;
  }
  if (lesson.extraFiles) Object.assign(files, lesson.extraFiles);
  return files;
}

（第 72-88 行）

整个防篡改体系的服务端心脏只有 17 行，信息密度极高，拆成四个观察点。观察一：形态分派用条件表达式而非策略对象。isJsdom/ext/pragma 三个 const 把"环境切换"压缩成两个变量：扩展名（.tsx 让 JSX 通过 esbuild 的 jsx: 'automatic' 编译）与文件头 pragma（// @vitest-environment happy-dom，文件级环境指令）。这里有个刻意的错位：数据字段叫 environment: 'jsdom'，pragma 注入的却是 happy-dom——语义上"课时声明的环境类别"与"实际执行环境"是两回事，真实执行的是 happy-dom（vitest 的 jsdom 兼容环境类别下选用 happy-dom 实现），第一次读这段代码的人几乎都会在这里停一下，《05-核心流程》流程三专门点破过。观察二：TDD 与普通模式的分叉只差一行。有 grader 时用户代码落 lesson.ts、grader 落 lesson.spec.ts（用户编辑"被测实现"，课程给定"测试"）；无 grader 时用户代码直接落 lesson.spec.ts（用户编辑的就是测试）。hiddenGrader 在两个分支里的行为完全一致——附加一个 lesson.hidden.spec.* 文件，且内容前拼 pragma。这种"不对称中的对称"正是模式推导（ADR-007）的体现：没有 mode 字段，装配顺序即语义。观察三：trim 守卫的语义考古。lesson.grader?.trim() 把纯空白的 grader 等同于不存在，注释原话"与旧前端 trim 守卫等价"——这是前端旧实现迁到服务端时有意保留的行为等价性，tests/runner-security.test.ts 的「纯空白的 grader/hiddenGrader 视为不存在」用例把这一语义升级成了契约：以后谁改这段代码，都不能破坏"空白字段不算数"的预期。观察四：extraFiles 的信任边界。Object.assign(files, lesson.extraFiles) 看似无条件信任课时数据，但别忘了外层：这些文件名会在 runInSandbox 第 302 行统一过 sanitizeEntryName 白名单——课时数据若写进非法名（如 ../evil.ts），运行会以 500 拒绝（校验抛错落入 handleRunVitest 的 500 分支，见《19》§3.5）。"数据可以信任内容、但不能绕过校验"的分层在这里很清楚：data.ts 是随代码发布的可信源，白名单防的是未来数据变更引入的意外。

这段代码教会我们什么：装配逻辑的正确写法是"把决策变成数据形状"。这段函数没有任何 if 之外的控制流、没有任何服务依赖、输入输出都是纯数据（Lesson + string → 文件表），因此它能被六个装配矩阵用例以 toEqual 精确锁定（《03-接口设计》§9 第一层契约测试）。防篡改不需要复杂的机制——只要"用户能影响的那份输入"（userCode）在输出里只占据预定的位置，其余内容全部来自服务端数据，篡改在结构上就不可能发生。

走读三：前端 TDD 自动批改链路——从点击到波浪线

3.1 提交侧：handleRunTest 的状态机

  const handleRunTest = useCallback(() => {
    if (!chapterKey || !effectiveLessonKey || !currentLesson) return;
    setResult({ status: 'running', output: '准备运行环境...\n' });

    const codeToRun = showSolution && currentLesson?.solution
      ? currentLesson.solution
      : code;

    // 测试装配在服务端按课时数据完成（防篡改）：客户端只提交课时 key 与当前代码
    const runOpts: RunOptions = {
      chapterKey,
      lessonKey: effectiveLessonKey,
      code: codeToRun,
    };

    runCode(runOpts)
      .then((runResult) => {
        if (runResult.success) {
          setResult({
            status: 'success',
            output: runResult.output,
            passed: runResult.passed,
            failed: runResult.failed,
            tests: runResult.tests,
            markers: runResult.markers,
            coverage: runResult.coverage,
          });
          setLessonProgress(chapterKey, effectiveLessonKey, {
            status: 'passed',
            lastRunAt: Date.now(),
          });
          message.success('测试全部通过！');

（src/pages/vitest-learn/chapter.tsx 第 124-155 行，节选）

这是《05-核心流程》流程二在代码层的原貌，三个点值得逐个看。第一，setResult({ status: 'running', ... }) 前置——乐观 UI 立即给反馈（按钮 loading、面板显示"准备运行环境..."），服务端没有会话概念，"运行中"完全是前端本地状态（《01-系统架构》§2 的第二个细节）。第二，codeToRun 的三元选择藏着"看答案跑通记通关"的种子：查看答案状态下提交的就是 solution 文本，成功后照样走 setLessonProgress({status:'passed'})——防刷缺失（backlog 未实现，《13》问题 5）在这段代码里看得很具体。第三，RunResult → TestResult 的显式展开（逐字段搬运而非 setResult(runResult)）就是《04-数据模型》§12 说的"两个模型之间的显式映射点"：status 是前端状态机的字段，在映射时被赋予 'success'/'error'，其余字段原样透传—— 类型层面的"传输事实"与"页面状态"在此完成交接。

3.2 传输侧：runVitest 把一切失败折叠成 RunResult

export async function runVitest(opts: RunOptions): Promise<RunResult> {
  try {
    const resp = await fetch('/api/run-vitest', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ chapterKey: opts.chapterKey, lessonKey: opts.lessonKey, code: opts.code }),
    });
    if (!resp.ok) {
      return {
        success: false,
        output: `服务端返回 ${resp.status}`,
        passed: 0,
        failed: 1,
      };
    }
    return (await resp.json()) as RunResult;
  } catch (e: unknown) {
    const msg = e instanceof Error ? e.message : String(e);
    return {
      success: false,
      output: `无法连接运行服务: ${msg}（请确认开发服务器已启动）`,
      passed: 0,
      failed: 1,
    };
  }
}

（src/pages/vitest-learn/runner.ts 第 21-46 行）

57 行文件里的核心函数，实现了一个"异常黑洞"：HTTP 非 2xx、fetch 网络异常、JSON 解析问题，全部折叠成 success:false 的 RunResult——调用方 handleRunTest 的 .catch 只需要兜"极端未捕获错误"，.then 里永远拿到可渲染的对象。这正是《03-接口设计》§4 的设计哲学（接口面向教学反馈建模）在前端的镜像：错误四象限（400/429/500/200+success:false）在传输层就被压平成一维的"成功/失败 + 文案"。body 只序列化三个字段——前端对防篡改契约的遵守不是靠服务端拦截出来的，而是靠这行 JSON.stringify({ chapterKey, lessonKey, code }) 从源头就没给其它字段留位置。

3.3 回路侧：markers 如何变成编辑器波浪线

  // 失败用例行内标记：把 markers 写到当前模型，Monaco 会显示红色波浪线与 hover 信息
  useEffect(() => {
    const editor = editorRef.current;
    const monaco = monacoRef.current;
    if (!editor || !monaco) return;
    const model = editor.getModel();
    if (!model) return;
    if (!errorMarkers || errorMarkers.length === 0) {
      monaco.editor.setModelMarkers(model, 'vitest', []);
      return;
    }
    monaco.editor.setModelMarkers(
      model,
      'vitest',
      errorMarkers.map((m) => ({
        startLineNumber: m.line,
        startColumn: 1,
        endLineNumber: m.line,
        endColumn: 1000,
        message: m.message,
        severity: monaco.MarkerSeverity.Error,
      })),
    );
  }, [errorMarkers]);

（src/pages/vitest-learn/CodeEditor.tsx 第 59-82 行）

链路的最后一米。三个细节：其一，editorRef/monacoRef 是在 onMount 回调（第 112-120 行）里捕获的实例引用——Monaco 是命令式 API，React 用 ref 桥接是标准姿势；if (!editor || !monaco) return 防的是 markers 在编辑器挂载前到达的时序。其二，空数组显式复位（setModelMarkers(model, 'vitest', [])）不是多余代码——Monaco 的 markers 按 owner（这里是 'vitest'）管理，不主动清空的话，上一次失败的波浪线会一直挂在编辑器上，用户改好了代码波浪线却不消失。《07-模块详解》§5.3 说的"空数组显式复位"就是这一行。其三，链条的终点前有一个 TDD 课时的重要减法，发生在 chapter.tsx 第 376 行：

                  errorMarkers={!isTDD ? result.markers : undefined}

TDD 课时把 markers 丢弃——因为失败行号来自 grader 文件（lesson.spec.ts），与用户编辑的 lesson.ts 行号体系完全不对应，若照常下发会把波浪线画到用户代码的错误位置上。这是一个"宁可少给信息、不可给错信息"的典型决策：TDD 课时的失败定位改由结果面板的逐用例列表承担。

3.4 闭环上的最后一环：runCode 与 isReady 垫片

export function useRealVitest() {
  const [isReady] = useState(true);

  const runCode = useCallback((opts: RunOptions): Promise<RunResult> => runVitest(opts), []);

  return { runCode, isReady };
}

（src/pages/vitest-learn/runner.ts 第 51-57 行）

Hook 很薄，但 isReady 恒真是 WebContainer 时代的活化石（ADR-002 的迁移残迹，《13》问题 6）：当年 isReady 表示"浏览器内 Node 运行时是否就绪"，迁移后运行引擎永远就绪，这个 state 变成 useState(true) 的常量，被 CodeEditor 的运行按钮 disabled={!isReady} 消费——永远不生效的禁用。保留它的原因是组件 props 契约不动（CodeEditorProps.isReady 有默认值 true），删除它需要连带改三个文件。把这段放进走读实录，是想让它作为"迁移决策残迹"的实物标本：读到 isReady 时不要以为是某个异步初始化的未完成实现。

这段代码教会我们什么（针对走读三整体）：前端 TDD 链路的实现哲学是"每个环节只做减法"。传输层把异常折叠成统一结果（减掉错误分支的状态机），映射层显式搬运字段（减掉模型混淆），渲染层对 TDD 丢弃 markers（减掉错误的行号暗示），进度层只在 success 写 passed（减掉对运行历史的记仇）。整条链上没有一处"聪明"的全局方案，全是局部清晰的小决策——这正是它能被三层测试（契约单测、PassThrough 假 HTTP、真实课时全链路）覆盖到每个环节的原因。防篡改在客户端的体现则是"没有可以篡改的东西"：RunOptions 只有三个字段，前端想作恶都没有输入口。

走读之后的复盘

把三段走读连起来看，有几个跨文件的品质值得总结为项目的"代码基因"。一，注释即设计文档：从 detached: true 后的行内注释到 parseBenchTable 上方六行的版本考古，几乎每个非显然决策都有就地注释，且注释说的是"为什么"而不是"是什么"——本套文档的很多结论能追溯到源码，靠的正是这个习惯。二，防御内联在关键路径：Math.min 钳制、1MB 截断、settled 标志、killed 仲裁都不抽成独立"安全层"，而是长在它们保护的逻辑旁边——防线离资产越近，越难被无意绕过。三，类型即契约：RunBody 三字段全 unknown（校验前不信任）、RunResult 前后端 import 同一类型、RunInSandboxOptions.timeoutMs 的注释直接写"不得调大"——类型声明承担了协议文档的职责。四，已知瑕疵留痕：close 回调不捕获退出码、isReady 恒真垫片、bench duration 单位问题，都在代码或测试里留下可辨认的痕迹并被《13》立项，而不是被静默遗忘。对要接手这个文件的人，最佳路径是：先读《07》拿到函数地图，再用本篇的三条路线走一遍真代码，最后按《08》§7 的安全清单过一遍常量区——三条材料覆盖了同一文件的三种读法。