Flue 框架演进全解析从 2.0 核心架构重构看 Sandbox Agent 框架的设计取舍【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue导读本文以仓库根目录 CHANGELOG.md 为主线梳理 FlueThe sandbox agent framework从 0.4.0 到 2.0.6 的关键版本演进重点剖析 2.0 系列带来的核心架构重构use agent指令 Hook 式 Agent 编写模型、Vite 插件化构建、app.ts显式路由、沙箱按需启用以及围绕持久化、事件流、可观测性做的大量可靠性加固。读完本文你将理解 Flue 当前版本2.0.x的完整技术面貌、各能力模块的真实调用关系并掌握从旧版迁移到 2.0 的实践路径。文章中的代码与结论均可在仓库的 packages/runtime、packages/vite 与 apps/docs/src/content/docs 中找到对应依据。一、2.0 主线构建体系从 CLI 全面转向 Vite 插件1.1flue dev/flue build退役Vite 接管一切CHANGELOG 2.0.0 的第一条 Breaking Change 就宣告了构建体系的更替Flue 不再拥有自己的dev/build命令而是变成一个 Vite 插件。新增的flue/vite包导出flue()插件将其加入vite.config.ts后vite dev与vite build成为唯一入口// vite.config.tsCloudflare 目标 import { cloudflare } from cloudflare/vite-plugin; import { flue } from flue/vite; import { defineConfig } from vite; export default defineConfig({ plugins: [flue(), cloudflare()], // flue() 必须位于 cloudflare() 之前 });几个关键设计点均可在 packages/vite 的插件实现与 apps/docs/src/content/docs/guide/migration.md 中印证Node 目标产出自启动的dist/server.mjs用node dist/server.mjs运行vite preview在 2.0.0 中即可工作且 preview 与node dist/server.mjs行为一致含生产持久化默认值与真实进程环境。Cloudflare 目标使用官方cloudflare/vite-plugin作为显式兄弟插件目标类型从cloudflare()的存在自动推断。wrangler.jsonc仍归用户所有Flue 的贡献生成的 Worker 入口virtual:flue/worker模块、每个 agent 的 Durable Object 绑定由flueWorkerConfig()定制器在内存中应用不会向项目树中生成任何文件。flue.config.ts保留为与宿主无关的项目配置defineConfig移到flue/runtime/configflue/cli/config导出被移除接受的字段为target、app、db、cloudflare、agents收窄use agent扫描的 glob、providers、tracingroot/output字段与命名vite导出被删除。配套的 CLI 也随之瘦身。flue run被重写为无传输的本地执行flue run path-to-agent-module --message ...在 Node 下编译并运行单个 agent 模块产品事件输出到 stderr最终回复或--json信封打印到 stdout并打印会话 id 以便--id跨调用续接同一会话。flue init在 2.0.0 中变为交互式脚手架除flue.config.ts外还会生成vite.config.ts、src/app.ts路由地图以及 Cloudflare 目标下的wrangler.jsonc含nodejs_compat、observability.traces。最终 CLI 只剩run/init/add/update/docs五个子命令。1.2 版本演进中的修复发布链路与依赖治理构建体系变革之外2.0 小版本也持续修复发布与依赖问题2.0.6恢复发布包中的捆绑文档——此前 2.0.4/2.0.5 遗漏了flue/cli、flue/runtime、flue/sdk的生成docs/目录导致flue docs read guide/sandboxes等命令失败发布前可用pnpm build:docs仓库根 package.json 中定义的脚本显式准备。2.0.5修复 2.0.4 误将裸workspace:依赖说明符发布出去、导致包在 workspace 外无法安装的问题#657。2.0.3Cloudflare Agents SDKagents成为flue/vite的依赖项目不再自行声明这同时修复了新安装因agents0.14.5内部aipeer 冲突而失败的问题脚手架wrangler范围同步移至^4.113.0。二、Agent 编写模型重写函数即 AgentHook 声明行为2.1use agent指令与渲染模型2.0.0 移除了defineAgent、createAgent等包装器Agent 的定义方式被彻底简化一个普通导出的、首字母大写的函数就是 Agent模块首行必须带use agent指令。构建扫描源文件中的指令将每个大写导出函数注册为 agent其持久化存储身份派生自导出函数名——或agentName静态属性——而与文件名无关重命名未 pin 的函数才是存储身份变更需用 wrangler 原生renamed_classes表达重命名文件不改变任何东西。这个函数在每次模型调用前都会重新执行一次即一次render渲染。函数的返回值字符串就是指令文档instruction document其余一切行为通过 render 期间调用 Hook 声明// src/agents/support.ts use agent; import { type AgentProps, useModel, useSandbox, useSkill, useSubagent, useTool, } from flue/runtime; export function Support({ id }: AgentProps) { useModel(anthropic/claude-sonnet-4-6, { thinkingLevel: medium }); useSandbox(myFactory, { cwd: /workspace }); useTool(lookupOrder); useSkill(refundsSkill); useSubagent({ name: reviewer, description: …, agent: Reviewer }); return Help with ticket ${id}.; } Support.durability { maxAttempts: 5 };完整 Hook 清单每个 Hook 的详细契约见 agent-hooks-api.md实现见 packages/runtime/src/hooksHook作用useModel(model, { thinkingLevel?, compaction? })声明模型必选且每次 render 恰好一次子 agent render 中调用会抛错useInstruction(text)追加原始指令文本低层逃逸口useTool(tool)挂载模型可调用工具useSkill(skill)挂载技能到披露目录progressive disclosureuseSubagent(subagent)为task工具声明委托 agentuseMcpConnection(definition)声明远程 MCP 服务器工具以mcp__server__tool挂载useSandbox(factory, { cwd? })附加执行环境每次 render 至多一次允许条件化usePersistentState(name, default?)实例级持久状态React 风格函数式更新useInitialData()读取实例创建数据配合initialData静态 schemauseDelivery()读取当前摆在模型面前的消息游标语义useDispatchMessage()绑定到本实例的 dispatcheruseDataWriter(name, { schema })声明命名、面向客户端的数据 partuseAgentStart(run)/useAgentFinish(run)生命周期回调intake / enforcement 缝useResponseStart(fn)/useResponseFinish(fn)响应元数据观察者同步2.2 Hook 的渲染契约与作用域从源码 use-model.ts 可以看到useModel的真实校验逻辑要求字符串模型说明符如anthropic/claude-sonnet-4-6、同一 render 内只能调用一次、选项对象只接受thinkingLevel与compaction两个字段未知字段直接抛错。这体现了整个 Hook 体系的共同规则只能在 agent 函数 render 期间调用在工具run函数、事件回调或模块作用域调用会抛出[flue] hook() was called outside an agent function.经requireRenderFrame检查。条件化与可重排useTool/useSkill/useSubagent/useMcpConnection/useSandbox的存在性可以随 render 变化变化会以resources/environment结构化信号叙述给模型usePersistentState按 name 键控存储四个事件 Hook 无持久身份每次 render 声明什么就运行什么。身份不变式useDataWriter的 name 必须在每次 render 中一致声明相邻 render 的差异会直接抛错。必选且恰好一次useModel的参数可以随 render 变化但调用不能消失。作用域useModel/useSandbox/useMcpConnection的值为 submission 级提交开始时读取一次资源集合与指令文本为 render 级子 agent render 中实例级与客户端面向的 HookuseModel、useSandbox、usePersistentState等会抛错委托方的模型与推理力度来自useSubagent定义。render 模型带来的直接收益是声明可条件化工具、技能、子 agent、MCP 连接、沙箱在不同 render 之间出现或消失会在下一个 turn 边界生效并以结构化增量信号叙述给模型——这是旧版配置包模型无法表达的动态能力。2.3 工具契约的演化结果信封、data字段与两个新标志2.0.0 重构了工具run()的上下文与返回值migration.mdToolContext变为{ toolCallId, log, signal? }加上声明inputschema 时的data原input改名、声明harness: true时的harness、声明durable: true时的step每个工具都有log用于结构化进度事件。返回值改为结果信封run()返回{ output?, terminate? }。output是工具结果值按声明的outputschema 校验后序列化给模型terminate: true在当前工具批次落定后结束 agent 回合——与内置finish/give_up相同的收尾契约。返回裸string仍是{ output: string }的简写其余裸值数字、布尔、数组、null或带output/terminate之外键的对象会抛错提示包裹。durable: true工具获得检查点步骤step.do(name, fn)每个 name 每次调用只执行一次并持久化记录结果中断后的恢复会重放已记录步骤值实现 exactly-once-recorded / at-least-once-executed 语义是框架内替代小型 workflow 编排的机制详细契约见 guide/tools.md。Harness 扁平化harness收窄为{ name, prompt(), compact(), sandbox }session()/sessions/shell()/fs全部移除harness.sandbox是活的SessionEnvexec、readFile、writeFile、stat、readdir、mkdir、rm等仅在 agent 声明沙箱时存在。六个内置工具bash/read/write/edit/grep/glob改为可组合的逐工具工厂createBashTool(env)、createReadTool(env)…SandboxFactory的tools()可以整体重组、扩展或替换。2.4 一个版本内的小步演进2.0.2 的缓存安全与重命名2.0.2条件式工具追加在支持延迟工具加载的模型上变得缓存安全——挂在已落定工具批次后的追加工具被锚定到该批次最终结果Anthropic 当前一代模型Claude 4.5 及以后不含 Haiku保持追加的工具定义不进入缓存 prompt 前缀锚点随运行持久化并在 rehydration 时恢复内部 reduced-state 格式计数器升至 2。沙箱类型按角色改名SessionEnv→Sandbox、SandboxApi→SandboxDriver、createSandboxSessionEnv()→sandboxFromDriver()、SessionToolFactory→SandboxToolFactory、SandboxFactory.createSessionEnv()→createSandbox()旧名字保留为带弃用警告的别名无需立即改动。三、路由app.ts成为唯一的 HTTP 路由地图2.0.0 移除了文件式路由与自动挂载的flue()路由器。src/agents/*、src/workflows/*、src/channels/*目录约定不再创建任何路由或注册。现在每个 Flue 应用有且仅有一个 HTTP 入口src/app.ts其默认导出就是服务器Node 端为 built serverCloudflare 端为 Worker 的 fetch handler// src/app.ts import { createAgentRouter } from flue/runtime/routing; import { Hono } from hono; import { Support } from ./agents/support.ts; import { Triage } from ./agents/triage.ts; const app new Hono(); app.route(/agents/support, createAgentRouter(Support)); app.route(/api/assistants/triage, createAgentRouter(Triage)); export default app;关键语义详见 routing.md注册来自扫描挂载只是暴露决策。use agent扫描让 agent 存在createAgentRouter(agent)是纯、无副作用的工厂只为已注册的 agent 构建 HTTP 表面。dispatch-only 的 agent 无需挂载也能工作。挂载路径不是身份。会话按 agent 的持久身份函数名或agentName静态键控与 URL 无关同一 agent 可挂载在两个路径服务同一批会话。URL 形态归你。/agents/name只是约定挂载路径之下每个会话位于mount/:id路由器相对挂载点提供POST /:id202 接纳、GET /:id、HEAD /:id、POST /:id/abort、GET /:id/attachments/:attachmentId五个路由。直连 HTTP 请求体是DeliveredMessagePOST /agents/:name/:id接受{ kind: user, body: ..., attachments?: [...] }聊天 turn或{ kind: signal, ... }结构化事件可选顶层initialData/uid/idempotencyKey。?waitresult同步模式被移除agent prompt 恒为 202 一次性接纳。保护挂载用普通 Hono 中间件认证 按会话 id 的授权两层检查叠加在挂载之前跨域 CORS 也是应用层关注点生产需自行配置并暴露Stream-Next-Offset等流协调头。四、沙箱按需启用与适配器体系4.1 不再有隐式环境2.0.0 之前每个 agent 默认获得带完整网络访问的隐式内存虚拟沙箱。现在沙箱是 opt-in未声明useSandbox()的 agent 没有任何执行环境——六个内置 shell/文件工具不会被添加harness.sandbox与 workspace 技能读取会抛出请先声明沙箱的错误workspace 发现对 prompt 无贡献。框架工具task、activate_skill、打包技能读取与环境无关因此技能与子 agent 在无沙箱时照常工作。CHANGELOG 给出的量化收益cloudflare 示例主 chunk 从 5,481 kB 降到 3,482 kB。useSandbox(factory, { cwd? })是附加环境的唯一途径local()flue/runtime/node在宿主机运行命令cloudflareSandbox(stub)flue/runtime/cloudflare在 Cloudflare Sandbox 容器中运行beta 默认行为的等价物是useSandbox(bash(() new Bash({ fs: new InMemoryFs() })))just-bash需自行加入依赖。声明是 submission 级且可条件化的存在性在每个 turn 边界重新读取翻转会在下一次模型调用前附加/分离环境并以一条完整environment信号新 cwd、完整工具清单、前环境文件可能不可访问的警告告知模型。4.2 类型改名与孤儿命令语义类型改名已在 2.0.2 完成SessionEnv→Sandbox等无操作要求。孤儿命令2.0.0 变更SessionEnv.exec在options.signal中止时立即以AbortError拒绝而不是等待远端命令结束——对 E2B、Daytona、Modal 等无中途取消能力的 provider这解除了整个 abort 路径的阻塞。仍在运行的远程命令成为显式的孤儿命令状态其最终落定被消费但不记录可通过新的createSandboxSessionEnv(api, cwd, { onOrphanSettled })回调与OrphanedExecSettlement类型观察。该保证在运行时包装器中实现一次createSandboxSessionEnv与bash()工厂适配器所有基于包装器的适配器自动获得该行为。沙箱死亡检测2.0.0 修复cloudflareSandbox()对每个进行中的 RPC 轮询容器状态每 5 秒一次 Durable Object storage 读容器停止时以SandboxDiedError拒绝——挂起的工具/尝试/中止得以落定而非永远等待。SandboxDiedError是 provider 中立的生态系统适配器可抛出以保持一致 shell 分类。4.3cloudflare-shell蓝图退役2.0.2 中cloudflare-shell蓝图被cloudflare-computer取代后者基于cloudflare/computer——cloudflare/shell的继任者在 agent 自己的 Durable Object 中托管持久的 SQLite 后端 workspace采用just-bashshell 后端必要时可升级到容器后端。适配器提供真正的exec()并保留框架标准工具集而非用 code 工具替代。flue add cloudflare-shell与旧文档 URL 均重定向到继任者。五、Workflows 移除与编排的替代方案2.0.0 彻底移除了 WorkflowsdefineWorkflow、invoke、run store、run 事件流、/runs/:runId与POST /workflows/:name路由含?waitresult、listRuns/getRun、SDK 的client.workflows/client.runs、React workflow hooks、dev-console run UI 全部删除无兼容桩。会话成为唯一的持久单元。一个 workflow 变成驱动 agent 的程序可选择单个模型操作 返回值init(agent, { id })返回耐久句柄handle.dispatch(message)走正常队列并在接纳时返回DispatchReceipthandle.read(receipt)等待落定并解析出AgentReply失败或中止的落定让read()以AgentRunError拒绝。回执与回复都是耐久会话记录跨崩溃持久化的回执例如作为 workflow 步骤的持久结果足以完成重试——任何进程、任何更晚时间都可重新附加。agent 内的检查点副作用序列durable: true工具 step.do(...)。多步编排应用自有的编排器。Cloudflare 上推荐 Cloudflare Workflows其步骤调用init()句柄——一步dispatch()记录的回执即该步结果下一步read(receipt)记录的回复即其重执行结果。schedules的迁移同理cron 触发器现在通过dispatch(Agent, { id, message: { kind: signal, ... } })向 agent 投递 signal 消息。start({ agents, db?, env?, providers? })flue/runtime/node可在任意 Node 进程中组装无传输的运行时供脚本、cron 与测试使用支持stop()/await using排空与释放。六、事件、消息与幂等投递6.1 统一的消息词汇表dispatch()接受结构化的message: DeliveredMessage替代不透明的input{ kind: user, body: string, attachments?: DeliveredAttachment[] }是真实聊天 turndispatch()现在可以携带图片附件{ kind: signal, type, body, attributes?, tagName? }是结构化事件/webhook 载荷。body恒为字符串——结构化载荷请自行JSON.stringify。signal 的tagName必须是合法 XML 标签名字母、数字、_、-、.不能以数字、-、.开头且非空否则在接纳时抛InvalidRequestError。频道包的约定body承载消息本身发送者身份、id、标题等结构化元数据作为扁平字符串放入attributes。6.2 幂等投递2.0.0 新增idempotencyKey≤256 字符两个携带相同 key 的接纳是同一个 submission——最多投递并回答一次每次接纳返回同一回执重放标记deduplicated: true并回显原始acceptedAt。key 命名投递而非结果settle 为failed的 submission 保持失败用新 key 重试。同一 key 配不同载荷会得到结构化 409SubmissionConflictErrortype: submission_conflict现有 submission id 在meta.submissionId。实现上 key 确定性地派生 submission idsub_ik_ 对 agent/instance/key 的 SHA-256零存储 schema 变更频道包保持无状态——把 provider 的 redelivery 稳定 id 透传即可Slack 用payload.event_id。6.3 事件词汇表补全observe()的 submission 词汇在 2.0.0 中补全为queued → running → settled三段submission_queued耐久接纳后立即发出at-least-once、submission_running每次 attempt 都从 attempt 自身上下文发出携带attemptCount/maxAttempts、submission_recovery暴露每次协调器恢复失败带operation/outcome判别器。另有submission_settled终局结果、toolcall_delta进程内流式工具参数增量仅实时、不持久、enforce_deadline强制期限信号窗口与强制落定2.0.1 新增。以submissionId对照queued/running与settled推导每个实例的忙/闲是文档化的稳定模式跨进程重启与 Durable Object 驱逐收敛一致。6.4 会话投影与消息形态一次响应投影为一条会话消息横跨多个模型步骤文本、工具调用、工具结果、更多文本的 assistant 响应折叠为一条消息parts 按记录顺序累积usage 跨步骤求和身份字段取第一步的——与 AI SDK 生态每条响应组装一个UIMessage的方式一致。公开会话消息暴露类型化purposeuser/assistant/dispatch/advisory与displayvisible/hidden/diagnostic外加可选的turnId分组与signal描述符#404。失败/中止的 turn 在时间线上可结构化检测终局 advisory 消息携带settlement: { outcome: failed | aborted }标记。2.0.1 的折叠优化读取不再重放实例的整条记录日志共享增量 fold 每 64 次 append 的耐久检查点冷加载从 ~2.6s 降至 ~0.8s30 MB delta-heavy 日志~3,000 批次#499。七、持久化格式版本契约与适配器演进格式版本戳2.0.0 起每个持久化 Flue store 记录format_versionSQL 后端的flue_meta表拒绝打开其他版本抛PersistedFormatVersionErrortype: persisted_format_version_unsupported。适配器作者通过flue/runtime/adapter的FLUE_FORMAT_VERSION与assertSupportedFlueFormatVersion()履行契约替代FLUE_SCHEMA_VERSION/PersistedSchemaVersionErrordefineStoreContractTests在每个后端上验证戳规则。2.0 线的持久化形状做过不兼容变更统一message输入、submission_id列命名、分块附件存储beta 时代的 store 必须清空无迁移。AgentSubmissionStore新增必选方法settleQueuedSubmission(submissionId, outcome, error)用于终局化永远无法被认领的排队 submission原子 queued-gated首个终态在竞争认领中胜出所有一方后端内置 SQLite flue/libsql/flue/postgres/flue/mysql/flue/mongodb/flue/redis同步提供。数据库适配器在 2.0.0 中改为接收你的 driver 而非连接串如postgres({ query, transaction, close })包裹自己的pg连接池db.ts移到源码根src/db.ts。2.0.0 中会话批次超过 Cloudflare Durable Object SQLite ~2 MB/value 上限不再以裸SQLITE_TOOBIG失败序列化批次超过 1 MB 会溢出到同一事务内的 512 KB chunk 行并在读取时校验重组12 MB 的 append 前上限把病态批次变成可操作的错误#289。八、可观测性与流健壮性8.1 追踪与遥测内容默认捕获flue/opentelemetry与原生 CloudflarecreateCloudflareTracing()默认发出会话内容gen_ai.input/output.messages、系统指令、工具定义/参数/结果除非传content: falsetransform是策略钩子。flue/opentelemetry的GenAIContentPolicy、limits等公共类型随之移除替换为content?: false | { transform }并新增truncateContent(content, { maxBytes })辅助packages/runtime/src/telemetry 的flue/runtime/telemetry子路径后端中立的 GenAI 内容机制无opentelemetry/api依赖。Cloudflare 部署零接线可追踪启用 Workers Traces 后每条响应都携带invoke_agent/chat/execute_toolspanstracing: false在flue.config.ts中退出。2.0.0 修复GEN_AI_SCHEMA_URL被移除该 URL 是编造的钉住的上游修订仍导出为GEN_AI_SEMCONV_REVISIONexception.type属性保留给异常类名两个 trace 后端都在execute_toolspans 上戳gen_ai.agent.nameGenAI 语义约定在 agent 已知时的条件必填。8.2 流与 SDK 客户端的韧性2.0.0 对flue/sdk的observe()/wait()/read()做了系统性加固packages/sdk/src 的实现与文档可印证存活性看门狗90 秒完全静默无 chunk、无活动即取消流并通过普通重试退避恢复另做一次全新 history 重新水合。416stream_offset_gone在流头部之外的偏移处恢复如 in-memory store 的 dev-server 重启现在结构化失败不再是无休止隐式重试的泛型 500。stream-checkpoint与 incarnation历史快照携带FlueConversationSnapshot.incarnationupdates视图每次 SSE 连接发出一次最小stream-checkpointchunkobserve()在 mismatch 时立即取消并重水合phase 短暂降至connecting无错误、无退避。认证失败不再永久致命401/403 走正常重连退避每请求重新解析 header连续三次无进展后落定error400 仍然立即致命。wait()/read()继承相同韧性read()是纯投影readSubmissionReply(conversation, submissionId)的 HTTP 对应物可从 admission 或 submissionId 附加、从流原点跟随已落定的 submission 立即解析。joined submission 的回复通过 settlement 的派生关联answeredBySubmissionId解析而非 recency——修复了 busy 会话上读到最后一条 assistant 消息可能静默返回更晚submission 答案的问题。九、SDK 与 React按 URL 寻址一个会话2.0.0 起 SDK 与 React hooks 按 URL 寻址单个会话。框架不再知道 agent 住在哪里——app.ts是地图——所以客户端收敛到它通信的资源import { createFlueClient } from flue/sdk; const conversation createFlueClient({ url: https://example.com/agents/support/ticket-8472, token: userToken, }); const admission await conversation.send({ message: { kind: user, body: Can you summarize the open issues in my case? }, }); await conversation.wait(admission); const { messages } await conversation.history();baseUrl agent-name/id 寻址、client.agents命名空间、listAgents()被移除新会话是调用方向挂载 URL 追加一个新 id。flue/react的useFlueAgent({ url })取代useFlueAgent({ name, id })新增refresh()#403与快照上的settlements。SDK 的prompt()移除改用send()fire-and-forgetwait()完成等待现为Promisevoidhistory()读取回复wait()不再解析结果失败/中止抛FlueExecutionError其failure字段为aborted时可区分远程中止与真实失败。错误信封新增error.ref字段与flue-error-ref响应头内部 500 时铸造err_前缀 ULIDflue/sdk的FlueApiError暴露为ref。十、频道与生态包2.0.0 中频道助手 API 统一改名所有频道包的conversationKey→instanceId、parseConversationKey→parseInstanceIdzendesk 的ticketKey/parseTicketKey同样错误类跟随为Invalid*InstanceIdError——干净断裂无别名。parseInstanceId从 showcase 降级为逃生口agent 通过创建数据useInitialData()接收结构化事实而非从 id 中解析。频道示例不再丢失发送者身份与事件元数据GitHubsender、issue ref、title、installationId恢复自回复循环防护、Teams、Google Chat、Linear、Telegram、Twilio、Messenger 都以扁平attributes恢复字段Telegram 纯媒体更新投递[photo message]占位符 body 而非空串。webhook 入口也做了加固subtle.verify等待、HMAC key 只导入一次、Discord 时间戳新鲜度窗口、Twilio 重复表单值签名等。数据库、沙箱、工具链的完整蓝图索引见仓库根 blueprints。十一、从 beta 迁移到 2.0 的实践要点apps/docs/src/content/docs/guide/migration.md 提供了逐节的 before/after 对照核心要点浓缩如下持久化重置先行beta 时代 schema 是 reset-only无迁移规划排空部署Cloudflare 上用deleted_classes退役旧类必要时先在 beta 应用中导出数据再重播种。构建写vite.config.tsflue()在cloudflare()之前flue.config.ts从flue/runtime/config导入defineConfig删掉root/output。路由app.ts显式挂载createAgentRouter替代自动路由器频道挂channel.route()。Agentinitializer 转为use agent模块中的大写导出函数 Hooks staticsagentName/initialData/durabilityctx.env改平台导入依赖隐式虚拟沙箱的 agent 显式声明useSandbox(bash(() new Bash({ fs: new InMemoryFs() })))。工具run({ input })→run({ data })需要会话级模型调用的用harness: true副作用序列考虑durable: true。Skills删除 import attributes让SKILL.md导入自打包其他 markdown 用defineSkill包裹。Workflows按最小适配替换为 awaitinit()句柄、durable 工具或自有的编排器。ProvidersregisterProvider()/registerApiProvider()换成 Pi 的createProvider()setProvider()依赖earendil-works/pi-aiCloudflare 绑定注册换成cloudflareBindingProvider()可用flue({ providers: [...] })收窄内置 providerproviders: [anthropic]的 cloudflare 示例从 9.6 MB 降到 5.8 MB#359。客户端SDK/React 收敛到会话级客户端run_*事件处理迁移到agent_start/agent_end/submission_settled与instanceId/submissionId关联字段。十二、小结一次彻底的重构从 CHANGELOG 的演进轨迹可以清晰看到 Flue 的设计方向少魔法、多显式、按需付费。2.0 移除自动路由、隐式沙箱、workflow 抽象与defineAgent包装器换来了函数即 agent Hook 声明 app.ts显式路由地图 Vite 单一构建链的简单心智模型同时用渲染模型换来了条件化声明能力用格式版本契约与defineStoreContractTests锁死了持久化稳定性用一批韧性修复流看门狗、孤儿命令、沙箱死亡检测、幂等投递、强制期限夯实了生产可靠性。对希望深入源码的读者建议从 packages/runtime/src/hooks渲染契约、packages/runtime/src/runtime协调器与提交生命周期、packages/vite/src/flue-plugin.ts构建集成三条路径入手配合 apps/docs/src/content/docs/guide 下的能力指南交叉阅读。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flue 框架演进全解析：从 2.0 核心架构重构看 Sandbox Agent 框架的设计取舍
Flue 框架演进全解析从 2.0 核心架构重构看 Sandbox Agent 框架的设计取舍【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue导读本文以仓库根目录 CHANGELOG.md 为主线梳理 FlueThe sandbox agent framework从 0.4.0 到 2.0.6 的关键版本演进重点剖析 2.0 系列带来的核心架构重构use agent指令 Hook 式 Agent 编写模型、Vite 插件化构建、app.ts显式路由、沙箱按需启用以及围绕持久化、事件流、可观测性做的大量可靠性加固。读完本文你将理解 Flue 当前版本2.0.x的完整技术面貌、各能力模块的真实调用关系并掌握从旧版迁移到 2.0 的实践路径。文章中的代码与结论均可在仓库的 packages/runtime、packages/vite 与 apps/docs/src/content/docs 中找到对应依据。一、2.0 主线构建体系从 CLI 全面转向 Vite 插件1.1flue dev/flue build退役Vite 接管一切CHANGELOG 2.0.0 的第一条 Breaking Change 就宣告了构建体系的更替Flue 不再拥有自己的dev/build命令而是变成一个 Vite 插件。新增的flue/vite包导出flue()插件将其加入vite.config.ts后vite dev与vite build成为唯一入口// vite.config.tsCloudflare 目标 import { cloudflare } from cloudflare/vite-plugin; import { flue } from flue/vite; import { defineConfig } from vite; export default defineConfig({ plugins: [flue(), cloudflare()], // flue() 必须位于 cloudflare() 之前 });几个关键设计点均可在 packages/vite 的插件实现与 apps/docs/src/content/docs/guide/migration.md 中印证Node 目标产出自启动的dist/server.mjs用node dist/server.mjs运行vite preview在 2.0.0 中即可工作且 preview 与node dist/server.mjs行为一致含生产持久化默认值与真实进程环境。Cloudflare 目标使用官方cloudflare/vite-plugin作为显式兄弟插件目标类型从cloudflare()的存在自动推断。wrangler.jsonc仍归用户所有Flue 的贡献生成的 Worker 入口virtual:flue/worker模块、每个 agent 的 Durable Object 绑定由flueWorkerConfig()定制器在内存中应用不会向项目树中生成任何文件。flue.config.ts保留为与宿主无关的项目配置defineConfig移到flue/runtime/configflue/cli/config导出被移除接受的字段为target、app、db、cloudflare、agents收窄use agent扫描的 glob、providers、tracingroot/output字段与命名vite导出被删除。配套的 CLI 也随之瘦身。flue run被重写为无传输的本地执行flue run path-to-agent-module --message ...在 Node 下编译并运行单个 agent 模块产品事件输出到 stderr最终回复或--json信封打印到 stdout并打印会话 id 以便--id跨调用续接同一会话。flue init在 2.0.0 中变为交互式脚手架除flue.config.ts外还会生成vite.config.ts、src/app.ts路由地图以及 Cloudflare 目标下的wrangler.jsonc含nodejs_compat、observability.traces。最终 CLI 只剩run/init/add/update/docs五个子命令。1.2 版本演进中的修复发布链路与依赖治理构建体系变革之外2.0 小版本也持续修复发布与依赖问题2.0.6恢复发布包中的捆绑文档——此前 2.0.4/2.0.5 遗漏了flue/cli、flue/runtime、flue/sdk的生成docs/目录导致flue docs read guide/sandboxes等命令失败发布前可用pnpm build:docs仓库根 package.json 中定义的脚本显式准备。2.0.5修复 2.0.4 误将裸workspace:依赖说明符发布出去、导致包在 workspace 外无法安装的问题#657。2.0.3Cloudflare Agents SDKagents成为flue/vite的依赖项目不再自行声明这同时修复了新安装因agents0.14.5内部aipeer 冲突而失败的问题脚手架wrangler范围同步移至^4.113.0。二、Agent 编写模型重写函数即 AgentHook 声明行为2.1use agent指令与渲染模型2.0.0 移除了defineAgent、createAgent等包装器Agent 的定义方式被彻底简化一个普通导出的、首字母大写的函数就是 Agent模块首行必须带use agent指令。构建扫描源文件中的指令将每个大写导出函数注册为 agent其持久化存储身份派生自导出函数名——或agentName静态属性——而与文件名无关重命名未 pin 的函数才是存储身份变更需用 wrangler 原生renamed_classes表达重命名文件不改变任何东西。这个函数在每次模型调用前都会重新执行一次即一次render渲染。函数的返回值字符串就是指令文档instruction document其余一切行为通过 render 期间调用 Hook 声明// src/agents/support.ts use agent; import { type AgentProps, useModel, useSandbox, useSkill, useSubagent, useTool, } from flue/runtime; export function Support({ id }: AgentProps) { useModel(anthropic/claude-sonnet-4-6, { thinkingLevel: medium }); useSandbox(myFactory, { cwd: /workspace }); useTool(lookupOrder); useSkill(refundsSkill); useSubagent({ name: reviewer, description: …, agent: Reviewer }); return Help with ticket ${id}.; } Support.durability { maxAttempts: 5 };完整 Hook 清单每个 Hook 的详细契约见 agent-hooks-api.md实现见 packages/runtime/src/hooksHook作用useModel(model, { thinkingLevel?, compaction? })声明模型必选且每次 render 恰好一次子 agent render 中调用会抛错useInstruction(text)追加原始指令文本低层逃逸口useTool(tool)挂载模型可调用工具useSkill(skill)挂载技能到披露目录progressive disclosureuseSubagent(subagent)为task工具声明委托 agentuseMcpConnection(definition)声明远程 MCP 服务器工具以mcp__server__tool挂载useSandbox(factory, { cwd? })附加执行环境每次 render 至多一次允许条件化usePersistentState(name, default?)实例级持久状态React 风格函数式更新useInitialData()读取实例创建数据配合initialData静态 schemauseDelivery()读取当前摆在模型面前的消息游标语义useDispatchMessage()绑定到本实例的 dispatcheruseDataWriter(name, { schema })声明命名、面向客户端的数据 partuseAgentStart(run)/useAgentFinish(run)生命周期回调intake / enforcement 缝useResponseStart(fn)/useResponseFinish(fn)响应元数据观察者同步2.2 Hook 的渲染契约与作用域从源码 use-model.ts 可以看到useModel的真实校验逻辑要求字符串模型说明符如anthropic/claude-sonnet-4-6、同一 render 内只能调用一次、选项对象只接受thinkingLevel与compaction两个字段未知字段直接抛错。这体现了整个 Hook 体系的共同规则只能在 agent 函数 render 期间调用在工具run函数、事件回调或模块作用域调用会抛出[flue] hook() was called outside an agent function.经requireRenderFrame检查。条件化与可重排useTool/useSkill/useSubagent/useMcpConnection/useSandbox的存在性可以随 render 变化变化会以resources/environment结构化信号叙述给模型usePersistentState按 name 键控存储四个事件 Hook 无持久身份每次 render 声明什么就运行什么。身份不变式useDataWriter的 name 必须在每次 render 中一致声明相邻 render 的差异会直接抛错。必选且恰好一次useModel的参数可以随 render 变化但调用不能消失。作用域useModel/useSandbox/useMcpConnection的值为 submission 级提交开始时读取一次资源集合与指令文本为 render 级子 agent render 中实例级与客户端面向的 HookuseModel、useSandbox、usePersistentState等会抛错委托方的模型与推理力度来自useSubagent定义。render 模型带来的直接收益是声明可条件化工具、技能、子 agent、MCP 连接、沙箱在不同 render 之间出现或消失会在下一个 turn 边界生效并以结构化增量信号叙述给模型——这是旧版配置包模型无法表达的动态能力。2.3 工具契约的演化结果信封、data字段与两个新标志2.0.0 重构了工具run()的上下文与返回值migration.mdToolContext变为{ toolCallId, log, signal? }加上声明inputschema 时的data原input改名、声明harness: true时的harness、声明durable: true时的step每个工具都有log用于结构化进度事件。返回值改为结果信封run()返回{ output?, terminate? }。output是工具结果值按声明的outputschema 校验后序列化给模型terminate: true在当前工具批次落定后结束 agent 回合——与内置finish/give_up相同的收尾契约。返回裸string仍是{ output: string }的简写其余裸值数字、布尔、数组、null或带output/terminate之外键的对象会抛错提示包裹。durable: true工具获得检查点步骤step.do(name, fn)每个 name 每次调用只执行一次并持久化记录结果中断后的恢复会重放已记录步骤值实现 exactly-once-recorded / at-least-once-executed 语义是框架内替代小型 workflow 编排的机制详细契约见 guide/tools.md。Harness 扁平化harness收窄为{ name, prompt(), compact(), sandbox }session()/sessions/shell()/fs全部移除harness.sandbox是活的SessionEnvexec、readFile、writeFile、stat、readdir、mkdir、rm等仅在 agent 声明沙箱时存在。六个内置工具bash/read/write/edit/grep/glob改为可组合的逐工具工厂createBashTool(env)、createReadTool(env)…SandboxFactory的tools()可以整体重组、扩展或替换。2.4 一个版本内的小步演进2.0.2 的缓存安全与重命名2.0.2条件式工具追加在支持延迟工具加载的模型上变得缓存安全——挂在已落定工具批次后的追加工具被锚定到该批次最终结果Anthropic 当前一代模型Claude 4.5 及以后不含 Haiku保持追加的工具定义不进入缓存 prompt 前缀锚点随运行持久化并在 rehydration 时恢复内部 reduced-state 格式计数器升至 2。沙箱类型按角色改名SessionEnv→Sandbox、SandboxApi→SandboxDriver、createSandboxSessionEnv()→sandboxFromDriver()、SessionToolFactory→SandboxToolFactory、SandboxFactory.createSessionEnv()→createSandbox()旧名字保留为带弃用警告的别名无需立即改动。三、路由app.ts成为唯一的 HTTP 路由地图2.0.0 移除了文件式路由与自动挂载的flue()路由器。src/agents/*、src/workflows/*、src/channels/*目录约定不再创建任何路由或注册。现在每个 Flue 应用有且仅有一个 HTTP 入口src/app.ts其默认导出就是服务器Node 端为 built serverCloudflare 端为 Worker 的 fetch handler// src/app.ts import { createAgentRouter } from flue/runtime/routing; import { Hono } from hono; import { Support } from ./agents/support.ts; import { Triage } from ./agents/triage.ts; const app new Hono(); app.route(/agents/support, createAgentRouter(Support)); app.route(/api/assistants/triage, createAgentRouter(Triage)); export default app;关键语义详见 routing.md注册来自扫描挂载只是暴露决策。use agent扫描让 agent 存在createAgentRouter(agent)是纯、无副作用的工厂只为已注册的 agent 构建 HTTP 表面。dispatch-only 的 agent 无需挂载也能工作。挂载路径不是身份。会话按 agent 的持久身份函数名或agentName静态键控与 URL 无关同一 agent 可挂载在两个路径服务同一批会话。URL 形态归你。/agents/name只是约定挂载路径之下每个会话位于mount/:id路由器相对挂载点提供POST /:id202 接纳、GET /:id、HEAD /:id、POST /:id/abort、GET /:id/attachments/:attachmentId五个路由。直连 HTTP 请求体是DeliveredMessagePOST /agents/:name/:id接受{ kind: user, body: ..., attachments?: [...] }聊天 turn或{ kind: signal, ... }结构化事件可选顶层initialData/uid/idempotencyKey。?waitresult同步模式被移除agent prompt 恒为 202 一次性接纳。保护挂载用普通 Hono 中间件认证 按会话 id 的授权两层检查叠加在挂载之前跨域 CORS 也是应用层关注点生产需自行配置并暴露Stream-Next-Offset等流协调头。四、沙箱按需启用与适配器体系4.1 不再有隐式环境2.0.0 之前每个 agent 默认获得带完整网络访问的隐式内存虚拟沙箱。现在沙箱是 opt-in未声明useSandbox()的 agent 没有任何执行环境——六个内置 shell/文件工具不会被添加harness.sandbox与 workspace 技能读取会抛出请先声明沙箱的错误workspace 发现对 prompt 无贡献。框架工具task、activate_skill、打包技能读取与环境无关因此技能与子 agent 在无沙箱时照常工作。CHANGELOG 给出的量化收益cloudflare 示例主 chunk 从 5,481 kB 降到 3,482 kB。useSandbox(factory, { cwd? })是附加环境的唯一途径local()flue/runtime/node在宿主机运行命令cloudflareSandbox(stub)flue/runtime/cloudflare在 Cloudflare Sandbox 容器中运行beta 默认行为的等价物是useSandbox(bash(() new Bash({ fs: new InMemoryFs() })))just-bash需自行加入依赖。声明是 submission 级且可条件化的存在性在每个 turn 边界重新读取翻转会在下一次模型调用前附加/分离环境并以一条完整environment信号新 cwd、完整工具清单、前环境文件可能不可访问的警告告知模型。4.2 类型改名与孤儿命令语义类型改名已在 2.0.2 完成SessionEnv→Sandbox等无操作要求。孤儿命令2.0.0 变更SessionEnv.exec在options.signal中止时立即以AbortError拒绝而不是等待远端命令结束——对 E2B、Daytona、Modal 等无中途取消能力的 provider这解除了整个 abort 路径的阻塞。仍在运行的远程命令成为显式的孤儿命令状态其最终落定被消费但不记录可通过新的createSandboxSessionEnv(api, cwd, { onOrphanSettled })回调与OrphanedExecSettlement类型观察。该保证在运行时包装器中实现一次createSandboxSessionEnv与bash()工厂适配器所有基于包装器的适配器自动获得该行为。沙箱死亡检测2.0.0 修复cloudflareSandbox()对每个进行中的 RPC 轮询容器状态每 5 秒一次 Durable Object storage 读容器停止时以SandboxDiedError拒绝——挂起的工具/尝试/中止得以落定而非永远等待。SandboxDiedError是 provider 中立的生态系统适配器可抛出以保持一致 shell 分类。4.3cloudflare-shell蓝图退役2.0.2 中cloudflare-shell蓝图被cloudflare-computer取代后者基于cloudflare/computer——cloudflare/shell的继任者在 agent 自己的 Durable Object 中托管持久的 SQLite 后端 workspace采用just-bashshell 后端必要时可升级到容器后端。适配器提供真正的exec()并保留框架标准工具集而非用 code 工具替代。flue add cloudflare-shell与旧文档 URL 均重定向到继任者。五、Workflows 移除与编排的替代方案2.0.0 彻底移除了 WorkflowsdefineWorkflow、invoke、run store、run 事件流、/runs/:runId与POST /workflows/:name路由含?waitresult、listRuns/getRun、SDK 的client.workflows/client.runs、React workflow hooks、dev-console run UI 全部删除无兼容桩。会话成为唯一的持久单元。一个 workflow 变成驱动 agent 的程序可选择单个模型操作 返回值init(agent, { id })返回耐久句柄handle.dispatch(message)走正常队列并在接纳时返回DispatchReceipthandle.read(receipt)等待落定并解析出AgentReply失败或中止的落定让read()以AgentRunError拒绝。回执与回复都是耐久会话记录跨崩溃持久化的回执例如作为 workflow 步骤的持久结果足以完成重试——任何进程、任何更晚时间都可重新附加。agent 内的检查点副作用序列durable: true工具 step.do(...)。多步编排应用自有的编排器。Cloudflare 上推荐 Cloudflare Workflows其步骤调用init()句柄——一步dispatch()记录的回执即该步结果下一步read(receipt)记录的回复即其重执行结果。schedules的迁移同理cron 触发器现在通过dispatch(Agent, { id, message: { kind: signal, ... } })向 agent 投递 signal 消息。start({ agents, db?, env?, providers? })flue/runtime/node可在任意 Node 进程中组装无传输的运行时供脚本、cron 与测试使用支持stop()/await using排空与释放。六、事件、消息与幂等投递6.1 统一的消息词汇表dispatch()接受结构化的message: DeliveredMessage替代不透明的input{ kind: user, body: string, attachments?: DeliveredAttachment[] }是真实聊天 turndispatch()现在可以携带图片附件{ kind: signal, type, body, attributes?, tagName? }是结构化事件/webhook 载荷。body恒为字符串——结构化载荷请自行JSON.stringify。signal 的tagName必须是合法 XML 标签名字母、数字、_、-、.不能以数字、-、.开头且非空否则在接纳时抛InvalidRequestError。频道包的约定body承载消息本身发送者身份、id、标题等结构化元数据作为扁平字符串放入attributes。6.2 幂等投递2.0.0 新增idempotencyKey≤256 字符两个携带相同 key 的接纳是同一个 submission——最多投递并回答一次每次接纳返回同一回执重放标记deduplicated: true并回显原始acceptedAt。key 命名投递而非结果settle 为failed的 submission 保持失败用新 key 重试。同一 key 配不同载荷会得到结构化 409SubmissionConflictErrortype: submission_conflict现有 submission id 在meta.submissionId。实现上 key 确定性地派生 submission idsub_ik_ 对 agent/instance/key 的 SHA-256零存储 schema 变更频道包保持无状态——把 provider 的 redelivery 稳定 id 透传即可Slack 用payload.event_id。6.3 事件词汇表补全observe()的 submission 词汇在 2.0.0 中补全为queued → running → settled三段submission_queued耐久接纳后立即发出at-least-once、submission_running每次 attempt 都从 attempt 自身上下文发出携带attemptCount/maxAttempts、submission_recovery暴露每次协调器恢复失败带operation/outcome判别器。另有submission_settled终局结果、toolcall_delta进程内流式工具参数增量仅实时、不持久、enforce_deadline强制期限信号窗口与强制落定2.0.1 新增。以submissionId对照queued/running与settled推导每个实例的忙/闲是文档化的稳定模式跨进程重启与 Durable Object 驱逐收敛一致。6.4 会话投影与消息形态一次响应投影为一条会话消息横跨多个模型步骤文本、工具调用、工具结果、更多文本的 assistant 响应折叠为一条消息parts 按记录顺序累积usage 跨步骤求和身份字段取第一步的——与 AI SDK 生态每条响应组装一个UIMessage的方式一致。公开会话消息暴露类型化purposeuser/assistant/dispatch/advisory与displayvisible/hidden/diagnostic外加可选的turnId分组与signal描述符#404。失败/中止的 turn 在时间线上可结构化检测终局 advisory 消息携带settlement: { outcome: failed | aborted }标记。2.0.1 的折叠优化读取不再重放实例的整条记录日志共享增量 fold 每 64 次 append 的耐久检查点冷加载从 ~2.6s 降至 ~0.8s30 MB delta-heavy 日志~3,000 批次#499。七、持久化格式版本契约与适配器演进格式版本戳2.0.0 起每个持久化 Flue store 记录format_versionSQL 后端的flue_meta表拒绝打开其他版本抛PersistedFormatVersionErrortype: persisted_format_version_unsupported。适配器作者通过flue/runtime/adapter的FLUE_FORMAT_VERSION与assertSupportedFlueFormatVersion()履行契约替代FLUE_SCHEMA_VERSION/PersistedSchemaVersionErrordefineStoreContractTests在每个后端上验证戳规则。2.0 线的持久化形状做过不兼容变更统一message输入、submission_id列命名、分块附件存储beta 时代的 store 必须清空无迁移。AgentSubmissionStore新增必选方法settleQueuedSubmission(submissionId, outcome, error)用于终局化永远无法被认领的排队 submission原子 queued-gated首个终态在竞争认领中胜出所有一方后端内置 SQLite flue/libsql/flue/postgres/flue/mysql/flue/mongodb/flue/redis同步提供。数据库适配器在 2.0.0 中改为接收你的 driver 而非连接串如postgres({ query, transaction, close })包裹自己的pg连接池db.ts移到源码根src/db.ts。2.0.0 中会话批次超过 Cloudflare Durable Object SQLite ~2 MB/value 上限不再以裸SQLITE_TOOBIG失败序列化批次超过 1 MB 会溢出到同一事务内的 512 KB chunk 行并在读取时校验重组12 MB 的 append 前上限把病态批次变成可操作的错误#289。八、可观测性与流健壮性8.1 追踪与遥测内容默认捕获flue/opentelemetry与原生 CloudflarecreateCloudflareTracing()默认发出会话内容gen_ai.input/output.messages、系统指令、工具定义/参数/结果除非传content: falsetransform是策略钩子。flue/opentelemetry的GenAIContentPolicy、limits等公共类型随之移除替换为content?: false | { transform }并新增truncateContent(content, { maxBytes })辅助packages/runtime/src/telemetry 的flue/runtime/telemetry子路径后端中立的 GenAI 内容机制无opentelemetry/api依赖。Cloudflare 部署零接线可追踪启用 Workers Traces 后每条响应都携带invoke_agent/chat/execute_toolspanstracing: false在flue.config.ts中退出。2.0.0 修复GEN_AI_SCHEMA_URL被移除该 URL 是编造的钉住的上游修订仍导出为GEN_AI_SEMCONV_REVISIONexception.type属性保留给异常类名两个 trace 后端都在execute_toolspans 上戳gen_ai.agent.nameGenAI 语义约定在 agent 已知时的条件必填。8.2 流与 SDK 客户端的韧性2.0.0 对flue/sdk的observe()/wait()/read()做了系统性加固packages/sdk/src 的实现与文档可印证存活性看门狗90 秒完全静默无 chunk、无活动即取消流并通过普通重试退避恢复另做一次全新 history 重新水合。416stream_offset_gone在流头部之外的偏移处恢复如 in-memory store 的 dev-server 重启现在结构化失败不再是无休止隐式重试的泛型 500。stream-checkpoint与 incarnation历史快照携带FlueConversationSnapshot.incarnationupdates视图每次 SSE 连接发出一次最小stream-checkpointchunkobserve()在 mismatch 时立即取消并重水合phase 短暂降至connecting无错误、无退避。认证失败不再永久致命401/403 走正常重连退避每请求重新解析 header连续三次无进展后落定error400 仍然立即致命。wait()/read()继承相同韧性read()是纯投影readSubmissionReply(conversation, submissionId)的 HTTP 对应物可从 admission 或 submissionId 附加、从流原点跟随已落定的 submission 立即解析。joined submission 的回复通过 settlement 的派生关联answeredBySubmissionId解析而非 recency——修复了 busy 会话上读到最后一条 assistant 消息可能静默返回更晚submission 答案的问题。九、SDK 与 React按 URL 寻址一个会话2.0.0 起 SDK 与 React hooks 按 URL 寻址单个会话。框架不再知道 agent 住在哪里——app.ts是地图——所以客户端收敛到它通信的资源import { createFlueClient } from flue/sdk; const conversation createFlueClient({ url: https://example.com/agents/support/ticket-8472, token: userToken, }); const admission await conversation.send({ message: { kind: user, body: Can you summarize the open issues in my case? }, }); await conversation.wait(admission); const { messages } await conversation.history();baseUrl agent-name/id 寻址、client.agents命名空间、listAgents()被移除新会话是调用方向挂载 URL 追加一个新 id。flue/react的useFlueAgent({ url })取代useFlueAgent({ name, id })新增refresh()#403与快照上的settlements。SDK 的prompt()移除改用send()fire-and-forgetwait()完成等待现为Promisevoidhistory()读取回复wait()不再解析结果失败/中止抛FlueExecutionError其failure字段为aborted时可区分远程中止与真实失败。错误信封新增error.ref字段与flue-error-ref响应头内部 500 时铸造err_前缀 ULIDflue/sdk的FlueApiError暴露为ref。十、频道与生态包2.0.0 中频道助手 API 统一改名所有频道包的conversationKey→instanceId、parseConversationKey→parseInstanceIdzendesk 的ticketKey/parseTicketKey同样错误类跟随为Invalid*InstanceIdError——干净断裂无别名。parseInstanceId从 showcase 降级为逃生口agent 通过创建数据useInitialData()接收结构化事实而非从 id 中解析。频道示例不再丢失发送者身份与事件元数据GitHubsender、issue ref、title、installationId恢复自回复循环防护、Teams、Google Chat、Linear、Telegram、Twilio、Messenger 都以扁平attributes恢复字段Telegram 纯媒体更新投递[photo message]占位符 body 而非空串。webhook 入口也做了加固subtle.verify等待、HMAC key 只导入一次、Discord 时间戳新鲜度窗口、Twilio 重复表单值签名等。数据库、沙箱、工具链的完整蓝图索引见仓库根 blueprints。十一、从 beta 迁移到 2.0 的实践要点apps/docs/src/content/docs/guide/migration.md 提供了逐节的 before/after 对照核心要点浓缩如下持久化重置先行beta 时代 schema 是 reset-only无迁移规划排空部署Cloudflare 上用deleted_classes退役旧类必要时先在 beta 应用中导出数据再重播种。构建写vite.config.tsflue()在cloudflare()之前flue.config.ts从flue/runtime/config导入defineConfig删掉root/output。路由app.ts显式挂载createAgentRouter替代自动路由器频道挂channel.route()。Agentinitializer 转为use agent模块中的大写导出函数 Hooks staticsagentName/initialData/durabilityctx.env改平台导入依赖隐式虚拟沙箱的 agent 显式声明useSandbox(bash(() new Bash({ fs: new InMemoryFs() })))。工具run({ input })→run({ data })需要会话级模型调用的用harness: true副作用序列考虑durable: true。Skills删除 import attributes让SKILL.md导入自打包其他 markdown 用defineSkill包裹。Workflows按最小适配替换为 awaitinit()句柄、durable 工具或自有的编排器。ProvidersregisterProvider()/registerApiProvider()换成 Pi 的createProvider()setProvider()依赖earendil-works/pi-aiCloudflare 绑定注册换成cloudflareBindingProvider()可用flue({ providers: [...] })收窄内置 providerproviders: [anthropic]的 cloudflare 示例从 9.6 MB 降到 5.8 MB#359。客户端SDK/React 收敛到会话级客户端run_*事件处理迁移到agent_start/agent_end/submission_settled与instanceId/submissionId关联字段。十二、小结一次彻底的重构从 CHANGELOG 的演进轨迹可以清晰看到 Flue 的设计方向少魔法、多显式、按需付费。2.0 移除自动路由、隐式沙箱、workflow 抽象与defineAgent包装器换来了函数即 agent Hook 声明 app.ts显式路由地图 Vite 单一构建链的简单心智模型同时用渲染模型换来了条件化声明能力用格式版本契约与defineStoreContractTests锁死了持久化稳定性用一批韧性修复流看门狗、孤儿命令、沙箱死亡检测、幂等投递、强制期限夯实了生产可靠性。对希望深入源码的读者建议从 packages/runtime/src/hooks渲染契约、packages/runtime/src/runtime协调器与提交生命周期、packages/vite/src/flue-plugin.ts构建集成三条路径入手配合 apps/docs/src/content/docs/guide 下的能力指南交叉阅读。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考