跳转到内容
Flue

输入关键词开始搜索文档。

Node.js

最后更新 查看 Markdown 源文件

Node.js 目标将你的智能体构建为标准的 Node.js 服务器。构建后的服务器可以在 Node 运行的任何地方运行：本地机器、容器、虚拟机、CI 运行器或托管服务。Node 也是智能体可以通过 local() 直接操作主机文件系统和 shell 的唯一目标。

有关部署演练，请参阅在 Node.js 上部署智能体。要按 cron 计划运行智能体，请参阅计划任务。

构建后的服务器

部署 解释了 Vite 如何将你的应用——app.ts 路由映射加上每个扫描到的 'use agent' 模块——构建为一个自启动的服务器入口 dist/server.mjs（加上它导入的非监听 dist/app.mjs 块——vite preview 服务的内容，以及自定义主机可以导入以将应用嵌入自己服务器的内容）：

vite build
node dist/server.mjs

服务器拥有 app.ts 挂载的所有 HTTP、智能体调度和持久对话流。它默认监听端口 3000；设置 PORT 来更改。

构建过程将应用依赖外部化而非打包。将构建后的制品与其 node_modules 一起部署，或将其打包在一个先安装依赖的容器中。

本地开发

vite dev 通过 Vite 的模块图加载 app.ts，并在 Vite 自己的服务器上服务它（默认端口 5173）。Vite 提供的所有功能都适用：编辑时即时重载、--port、环境处理。Flue 额外提供：

  • 监视 'use agent 变化——添加或移除标记的模块，或添加和移除智能体导出，会更新注册的智能体集合，无需手动重启；
  • 当 flue.config.* 变化时重启开发服务器；
  • 将项目的 .env 文件集（.env、.env.local、.env.<mode>、.env.<mode>.local）加载到应用环境中，shell 导出的值优先——模型提供商密钥无需 shell 导出即可工作；
  • 应用宽松的开发 CORS 默认设置（带凭据的反射 origin，加上持久流协调头），这样单独服务的 SPA 可以与之通信。部署后的服务器将 CORS 作为应用层关注点。

vite preview 服务构建后的制品：它原生导入 dist/app.mjs——没有 Vite 转换——因此预览服务的内容正是 node dist/server.mjs 会服务的内容，包括生产持久化默认值和真实的进程环境。先运行 vite build；当制品不存在时，预览会失败并给出该指导。与原始制品的一个本地工具差异：预览默认使用与 vite dev 相同的宽松 CORS 策略（用 Vite 的 preview.cors 覆盖），因此不同源的本地客户端可以与之通信；node dist/server.mjs 完全没有 CORS 层。

状态和持久性

没有 db.ts 时，Node 服务器使用进程本地的内存 SQLite 来存储规范的智能体对话和已接受的提交。这为单个运行进程提供了有序的状态处理，但重启会丢失该状态。

有了持久适配器，直接提示和 dispatch(...) 输入进入相同的持久化每对话队列。一个智能体对话的输入按接受顺序处理，替换进程可以恢复规范的对话进度和中断的提交。

Node 要求一个活跃进程来拥有给定的智能体对话。共享数据库支持进程或主机替换，但不能使同一对话的主动 - 主动所有权或轮询路由变得安全。多副本部署必须将每个对话路由到一个所有者，并在替换期间避免重叠的所有者。

Node 没有 Cloudflare 的自动 Durable Object 唤醒或 Fiber 恢复。替换进程必须在启动协调运行之前成功启动，协调器会定期扫描过期租约，因此快速重启导致的搁置工作最终会被回收。

参见数据库了解 db.ts、SQLite、Postgres 和自定义适配器。参见持久性了解恢复行为。

local() 沙箱

Node 是唯一内置 local() 沙箱工厂的目标。它让智能体直接访问主机文件系统和 shell，使其适用于开发工具、CI 任务、编码智能体和主机环境已提供隔离的自托管自动化。

src/agents/repository-reviewer.ts
'use agent';
import { useModel, useSandbox } from '@flue/runtime';
import { local } from '@flue/runtime/node';

export function RepositoryReviewer() {
  useModel('anthropic/claude-sonnet-4-6');
  useSandbox(local());
}

local() 默认使用 process.cwd() 作为工作目录。Shell 命令通过 child_process 经由主机 shell 运行，文件操作读写真实的文件系统。

默认情况下，只有 shell 必需的环境变量会暴露给智能体的 shell。API 密钥、令牌和凭据被刻意排除。当命令需要时，通过 env 传递特定值：

export function RepositoryReviewer() {
  useModel('anthropic/claude-sonnet-4-6');
  useSandbox(
    local({
      env: { GH_TOKEN: process.env.GH_TOKEN },
    }),
  );
}

传递 env: { ...process.env } 会将完整的主机环境暴露给模型的 shell。仅在受信任的环境中这样做。

远程沙箱

当智能体工作需要每会话隔离、Linux 工具链或提供商管理的环境时，请使用远程沙箱适配器而非 local()。远程沙箱在外部基础设施上运行，并通过沙箱适配器 API 连接。

参见生态系统沙箱目录了解可用的集成，包括 Daytona、E2B 和 Modal。

环境和密钥

本地开发自动加载项目的 .env 文件，shell 导出的值优先：

  • flue run 加载项目根目录的 .env；使用 --env <path> 选择一个替代文件。
  • vite dev 从项目根目录加载 Vite 的标准文件集：.env、.env.local、.env.<mode> 和 .env.<mode>.local。

构建后的服务器不同：node dist/server.mjs 只读取启动时提供的环境，因为部署环境拥有自己的配置：

# Production
set -a; source .env; set +a
node dist/server.mjs

使用你的提供商期望的环境变量名，如 ANTHROPIC_API_KEY 或 OPENAI_API_KEY。不要提交 .env 文件。

参考

local(...)

import { local } from '@flue/runtime/node';

function local(options?: LocalSandboxOptions): SandboxFactory;

创建一个直接绑定到主机文件系统和 shell 的沙箱工厂。在智能体函数中使用 useSandbox(local()) 附加它。

LocalSandboxOptions：

  • cwd ——工作目录。默认为 process.cwd()。
  • env ——在默认的 shell 必需允许列表之上分层的额外环境变量。将键设置为 undefined 可移除默认值。Shell 调用中的每次执行 env 在此基础上分层。

环境快照在沙箱构造时取一次。之后对 process.env 的修改不会反映。

sqlite(...)

import { sqlite } from '@flue/runtime/node';

function sqlite(path?: string): PersistenceAdapter;

创建内置的 Node SQLite 持久适配器。省略 path 使用内存存储，或传递文件路径以在进程重启间持久化。