《Agent Runtime 工程化》第二章 TypeScript / Node Runtime 基础

2.2 async iterator：把运行过程变成事件流

Agent 产品喜欢流式输出，主要是为了降低用户等待的不确定性，也让 runtime 更早看见模型意图。炫技排在很后面。

模型流可能先返回解释文字，再返回工具调用片段。工具执行也可能先输出日志，再最终退出。统一处理这些事件，最自然的接口是 async iterator：

type RuntimeEvent =
  | { type: "model_delta"; text: string }
  | { type: "tool_call"; name: string; args: unknown }
  | { type: "tool_stdout"; text: string }
  | { type: "tool_stderr"; text: string }
  | { type: "step_done"; stepId: string };

async function* runAgent(input: string): AsyncGenerator<RuntimeEvent> {
  yield { type: "model_delta", text: "我先检查项目结构。" };
  yield { type: "tool_call", name: "list_files", args: { path: "." } };
  yield { type: "tool_stdout", text: "src/index.ts\npackage.json\n" };
  yield { type: "step_done", stepId: "step_1" };
}

事件流的好处是前端、CLI、trace、测试都能订阅同一套语义。不要让每个通道各写一套'半成品日志解析器'。如果 UI 解析一套日志、trace 解析另一套日志、eval 再解析第三套日志，系统迟早会出现'用户看到失败，trace 里却显示成功'的错位。

实战里建议把事件分成两层：

这两层可以来自同一个内部事件总线，但不要混成一个字段。用户不需要看见所有工程细节；工程系统也不能只保存用户可见文本。

2.3 AbortSignal：取消要能传到底

一个成熟 runtime 必须支持取消。取消不是'UI 不显示了'，而是从用户操作一路传播到模型请求、工具执行、子进程和资源清理。

async function withTimeout<T>(
  task: (signal: AbortSignal) => Promise<T>,
  ms: number
): Promise<T> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), ms);
  try {
    return await task(controller.signal);
  } finally {
    clearTimeout(timer);
  }
}

这段代码只是开始。上线后的 runtime 需要把 AbortSignal 传给 HTTP client、模型 SDK、工具 executor、子进程管理器。任何一层吞掉取消信号，都会让用户看到'已取消'，机器上却还有命令在跑。

取消传播最好有统一约定：

这个表也可以直接变成测试清单。测试不要只断言 Promise 被 reject，还要断言进程退出、计时器清理、trace 状态正确。

2.4 子进程执行器：Agent 的危险地带

coding agent 迟早会执行 shell 命令。读目录、跑测试、安装依赖、生成文件、调用 CLI，都会经过子进程。这里必须谨慎，因为 shell 是副作用入口。

一个最低限度的命令执行器应当具备：

• 明确的工作目录；
• 环境变量白名单或脱敏策略；
• stdout/stderr 流式输出；
• 超时；
• 取消；
• 退出码记录；
• 最大输出限制；
• 风险分类与审批前置。

示例骨架：

import { spawn } from "node:child_process";

export function runCommand(
  command: string,
  args: string[],
  options: { cwd: string; signal: AbortSignal; timeoutMs: number }
): AsyncIterable<{ stream: "stdout" | "stderr"; text: string }> {
  const child = spawn(command, args, {
    cwd: options.cwd,
    shell: false,
    stdio: ["ignore", "pipe", "pipe"],
  });

  const timer = setTimeout(() => {
    child.kill("SIGTERM");
  }, options.timeoutMs);

  options.signal.addEventListener("abort", () => {
    child.kill("SIGTERM");
  });

  return streamChild(child, timer);
}

生产实现还要处理 SIGTERM 后进程不退出的情况，必要时延迟发送 SIGKILL；还要处理进程树，避免子进程再创建孙进程后逃逸。

命令执行器建议返回结构化结果，而不是直接返回字符串：

type CommandResult = {
  exitCode: number | null;
  signal: NodeJS.Signals | null;
  durationMs: number;
  stdoutRef: string;
  stderrRef: string;
  modelObservation: string;
  truncated: boolean;
};

stdoutRef 和 stderrRef 指向完整日志，modelObservation 是给模型的摘要。这样既保留排障证据，又不把上下文塞爆。

2.5 背压：不要让日志淹没上下文

背压是很多 Agent Demo 不谈、生产系统绕不开的问题。工具输出可能非常大，例如 npm test 打出几万行日志，grep 搜索整个仓库，构建工具输出长堆栈。Runtime 不能把所有内容原样塞进模型上下文。

正确做法是分两层处理。

第一层是执行层限流。命令执行器记录完整日志到文件或 trace，但只向模型返回摘要、尾部片段和关键错误行。

第二层是上下文层降级。Context Builder 根据预算决定哪些工具结果进入下一轮，哪些只保留引用。

一个实用策略：

这里要警惕一个陷阱：截断不是简单切前 4000 个字符。对测试日志来说，尾部错误常常比头部安装日志重要；对搜索结果来说，文件路径和命中行比上下文噪声重要；对构建失败来说，第一个根因错误往往比后面几百行连锁报错重要。

2.6 资源清理比重试更重要

很多系统把重试当作可靠性的同义词。对 Agent Runtime 来说，重试之前先问一句：上一次有没有留下副作用？

如果模型请求超时，重试通常安全。如果读文件失败，重试也通常安全。如果写文件执行到一半，重试可能覆盖用户改动。如果 npm install 被中断，重试前要检查 lockfile 和目录状态。如果迁移数据库失败，绝不能盲目重试。

工程上应给每个工具声明副作用等级：

type SideEffect = "none" | "workspace-read" | "workspace-write" |
  "network" | "external-write" | "destructive";

type ToolDefinition = {
  name: string;
  inputSchema: unknown;
  sideEffect: SideEffect;
  execute(input: unknown, ctx: ToolContext): Promise<ToolResult>;
};

这不是形式主义。后面章节的权限、checkpoint、eval、成本治理都会依赖这些元数据。

清理策略建议写进 executor，而不是散落在每个工具里：

你会发现，可靠性很多时候不是更聪明，而是收拾干净。

2.7 实战练习：可取消命令执行器

实现一个可取消的命令执行器：

• 支持 cwd；
• 支持 stdout/stderr 流式事件；
• 支持 timeout；
• 支持 AbortSignal；
• 支持最大输出限制；
• 返回 exit code、signal、duration；
• 中断后清理子进程；
• 输出 modelObservation 和完整日志引用。

用三个命令测试它：

node -e "setInterval(()=>console.log(Date.now()), 100)"
node -e "console.error('boom'); process.exit(2)"
node -e "while(true){}"

测试时不要只看终端输出。你还要检查：

• 超时后进程是否真的退出；
• stderr 是否被保留；
• 长 stdout 是否被截断成 observation；
• trace 是否记录 duration、exit code、signal；
• 多次运行是否留下临时文件或 listener。

2.8 验收标准

读完本章，你不只是会 await，而是能解释异步任务如何取消、如何防泄漏、如何处理流式输出、如何把长日志变成模型可用的观察结果。做到这里，才有资格写第三章的最小 Agent Loop。

系列文章目录

• 《Agent Runtime 工程化》完整目录
• 《Agent Runtime 工程化》第一章 Agent Runtime 全景
• 《Agent Runtime 工程化》第二章 TypeScript / Node Runtime 基础
• 《Agent Runtime 工程化》第三章 最小 Agent Loop
• 《Agent Runtime 工程化》第四章 工具系统设计
• 《Agent Runtime 工程化》第五章 上下文工程
• 《Agent Runtime 工程化》第六章 MCP 与 Provider 抽象
• 《Agent Runtime 工程化》第七章 权限与安全边界
• 《Agent Runtime 工程化》第八章 Checkpoint、Resume、Rollback
• 《Agent Runtime 工程化》第九章 可观测与 Trace
• 《Agent Runtime 工程化》第十章 Eval Harness 与 CI 回归
• 《Agent Runtime 工程化》第十一章 Agent Runtime 进阶学习路线
• 《Agent Runtime 工程化》第十二章 hermes-agent 产品级实战
• 《Agent Runtime 工程化》附录