Flue Agent Harness 框架深度实战可编程 TypeScript Harness 与 flue/cli 本地运行指南【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue 是一个以可编程 TypeScript Harness为核心的 Agent 框架你不再编写一串预设步骤而是用use agent指令导出一个普通 TypeScript 函数通过useModel、useSandbox、useSkill、useTool等钩子为模型组装出会话、工具、技能、文件系统与安全沙箱等完整执行环境。本文以flue/cli的命令体系为主线结合仓库源码讲解从编写第一个 Agent、用flue run本地运行、用flue init脚手架初始化项目到通过 Blueprint 扩展渠道/沙箱/数据库的完整链路。为什么需要 Harness从脚本化调用到真正的自主 Agent最早一批 Agent 直接调用 LLM API这只能支撑简单的聊天机器人和脚本化任务。而 Claude Code、Codex 这类产品打破了旧模式它们是真正的 Agent——你交给它们的是一个任务而不是一串预先定义好的步骤它们会利用你提供的上下文和工具自主完成目标。Flue 正是为了解锁这种新架构而设计。它的内置 TypeScript Harness 为任何模型提供自主工作所需的完整上下文与环境会话sessions、工具tools、技能skills、指令instructions、文件系统访问以及一个安全的沙箱来运行代码。你可以在本地通过 CLI 运行 Agent也可以部署到你选择的主机运行时Node.js、Cloudflare Workers 等。快速上手一个可运行的 Agent 模块packages/cli/README.md开篇给出了一个完整的 Triage Agent 示例这也是理解 Flue 编程模型的最小样例// agents/triage.ts use agent; import { useModel, useSandbox, useSkill, useTool } from flue/runtime; import { local } from flue/runtime/node; import triage from ../skills/triage/SKILL.md; import verify from ../skills/verify/SKILL.md; import { openIssue, searchCode } from ../tools/github.ts; // The agent IS the function. Compose the complete harness it needs to do // real work, complete with virtual, local, or remote container sandbox. export function Triage() { useModel(anthropic/claude-sonnet-4-6); useSandbox(local()); useSkill(triage); useSkill(verify); useTool(openIssue); useTool(searchCode); // Give agents the context and autonomy to solve complex tasks: return Triage a bug report end-to-end: reproduce the bug, diagnose the root cause, verify whether the behavior is intentional, and attempt a fix. ...; }理解这段代码的几个关键点use agent模块指令模块第一行声明该文件是 Agent 模块。flue/cli脚手架生成的注释明确说明Every exported capitalized function in a use agent module is an agent, and the functions name is its durable identity.——每个导出的大写开头函数都是一个 Agent函数名就是它的持久化身份标识。这一规则由构建扫描器统一执行见 init.ts 生成的HelloAgent 与 run-local.ts 中scanAgentModuleCode的调用因此flue run、vite dev、vite build对什么算 Agent的判断永远不会分叉。函数即 AgentAgent 不需要类、不需要服务对象一个普通函数即可。函数的返回值就是系统提示词system prompt。Hooks 组装 HarnessuseModel选择模型格式为provider-id/model-iduseSandbox提供沙箱这里用local()表示本地沙箱也可用虚拟、远程容器沙箱useSkill直接以import ... from ../skills/triage/SKILL.md的方式导入技能文档运行时通过 Vite 的markdownImportPlugin支持 Markdown 导入见 run-local.tsuseTool挂载类型化的工具函数。模型选择策略既可以在 Agent 函数内用useModel固定模型也可以在每次调用时通过prompt/skill/task上的{ model: ... }覆盖。CLI 的全局帮助尾部专门注明了这一点见 help.ts。核心特性全景Flue 让 Agent 能够安全地采取行动、保持连续性并接入真实工作发生的系统。packages/cli/README.md列举的特性如下此处结合仓库实际实现逐一说明AgentsAgent构建能够在对话和事件之间保持上下文、自主朝目标推进的 Agent。use agent模块 导出函数是它的统一形态会话状态由持久化层承接见下文 Durability。Sandboxes沙箱为 Agent 提供安全环境使其能使用工具、修改文件、自主完成真实工作。仓库 blueprints 目录收录了sandbox--daytona.md、sandbox--e2b.md、sandbox--modal.md、sandbox--cloudflare.md等一整套沙箱接入指南examples/cloudflare 和 examples/hello-world 中也有对应实现样例。Durability持久化通过持久化的会话存储Agent 在失败与重启后仍能恢复已接受的工作进度。运行时提供conversation-*系列模块与多套存储适配器SQLite、Postgres、libSQL、MongoDB、MySQL、Redis 等详见 packages/runtime/src 与 packages 下的flue/postgres等适配器包。Subagents子 Agent为不同任务定义专业化角色让主 Agent 把工作委派给合适的专家。Tools工具为 Agent 提供类型化动作用于调用 API、查询数据、通过你的应用做受控修改。类型系统见 tool-types.ts 与 tool.ts。Skills技能把可复用的专家知识和工作流打包Agent 在任务需要专门指导时按需加载。skill-definition.ts 等模块定义了技能解析与加载机制。MCP Servers通过开放的 Model Context Protocol 生态接入经过认证的工具与服务。运行时实现了 MCP 客户端支持mcp.ts。Observability可观测性监控 Agent 并导出遥测数据可接入 OpenTelemetrypackages/opentelemetry、Braintrustexamples/braintrust、Sentryexamples/sentry或自研 observer。Channels渠道接收来自 Slack、Teams、Discord、GitHub 等平台的已校验事件。仓库为每个渠道提供独立包packages/slack、packages/teams、packages/discord、packages/github 等与对应示例examples/slack-channel 等。部署到任何地方Flue 不绑定单一托管平台。README 列出的部署目标包括Node.js、Cloudflare Workers、GitHub Actions、GitLab CI/CD、Daytona远程沙箱、Render。在实际脚手架中flue init将部署形态收敛为两个构建目标node/cloudflare并用是否包含 HTTP 服务端Vite Hono app.ts区分纯本地运行与可部署服务两种形态详见下文。包生态一览packages/cli/README.md末尾给出了官方包的完整清单PackageDescriptionflue/runtimeRuntime: harness, sessions, tools, sandboxflue/viteVite plugin:vite dev/vite buildfor Node and Cloudflareflue/cliCLI (fluebinary): local runs, blueprints, offline docsflue/sdkClient SDK for consuming deployed agent conversationsflue/opentelemetryOpenTelemetry tracing adapterflue/postgresPostgres persistence adapter其中flue/cli的bin入口是flue命令见 package.json并要求 Node.js 22.19.0。除 Postgres 外仓库还提供了flue/libsql、flue/mongodb、flue/mysql、flue/redis等持久化适配器以及覆盖主流通信平台的 channel 包。flue/cli 命令体系源码级解析CLI 由 cli.ts 中的buildCli统一注册四个命令族flue run、flue init、flue add/flue updateblueprint 命令、flue docs外加-v/--version与help。入口 main.ts 负责顶层分发-v/--version输出纯版本号避免 cac 默认输出附带平台信息help直接输出帮助未匹配的命令会给出Did you meanflue ...?的纠错建议并以退出码 1 结束。flue init交互式初始化项目flue init [directory]用于脚手架一个新 Flue 项目。可用选项见 init.ts选项说明--target target构建目标node或cloudflare省略时交互式询问--deploy包含 HTTP 服务端脚手架vite.config.ts、src/app.ts、HonoCloudflare 目标隐含此选项--root path与位置参数同义的目标目录两者不可同时传入--force允许在非空目录中脚手架并覆盖已存在的flue.config.*交互流程中有两个选择Run locallyflue run本地运行、Deploydev server build 的 HTTP 服务、Both以及部署目标 CloudflareWorkers Durable Objects或 Node.js标准 Node 服务器可托管在任何地方。所有交互答案最终只映射到两个开关target 与 deploy见 init.ts。脚手架写入的文件由 planInitFiles 规划覆盖本地/部署两种形态通用flue.config.ts、package.json、tsconfig.json、.gitignore、.env、src/agents/hello.ts、AGENTS.md、README.md部署形态追加vite.config.ts、src/app.ts路由映射createAgentRouter(Hello)挂载到/agents/helloCloudflare 目标追加src/cloudflare.ts、wrangler.jsonc含 Durable Object 迁移条目如new_sqlite_classes: [FlueHelloAgent]Node 本地形态追加src/db.ts默认sqlite(./data/flue.db)持久化适配器生成的package.json会按检测到的包管理器npm/pnpm/yarn/bun与 CLI 版本自动对齐flue/*依赖范围并注入dev/build/deploy/check:types等脚本init.ts。文件写入采用 create-if-absent 策略--force才会覆盖且若旧配置是flue.config.mts/.js等非.ts变体会提示新文件优先级更高、建议删除旧文件init.ts。flue run无服务器的一次性本地运行flue run path --message text是无传输层transport-free的一次性本地 Agent 执行加载 Agent 模块、提交一条用户消息、打印回复后退出。这是体验 Flue 的最快路径无需启动任何服务。完整选项见 run.ts选项说明-m, --message text提交给 Agent 的用户消息必填--name agent模块导出多个 Agent 时指定运行哪一个--id id会话 ID用于创建或继续会话缺省时生成新 ID 并打印--data json创建数据JSON通过useInitialData()读取继续会话时忽略--uid uid仅继续指定 uid 的会话实例--new仅创建会话 ID 已存在时报错--json向 stdout 输出 JSON 结果信封而非纯文本消息--env path在运行前加载一个额外的.env格式文件参数校验逻辑值得注意run.ts--uid与--new互斥一个只继续、一个只创建--uid与--data互斥继续既有实例时创建数据无意义。另外CLI 的 flag 归一化层flags.ts处理了 cac/mri 解析器的两个坑数值型参数如--id 4821会被强制转成 number字符串选项会从原始 argv 恢复字面 token避免--id 007被解析成 7 这类精度丢失重复传参会被拒绝而不是静默变成数组。flue run的底层实现run-local.ts有几个关键设计非监听 Vite 服务器以 middleware 模式 关闭 HMR/WebSocket 的方式创建 Vite 实例appType: custom、server.middlewareMode: true、ws: false、watch: null从不绑定任何端口仅用于模块加载ssrLoadModule。单一运行时图Agent 模块、DB 模块与运行引导bootstrap都通过同一个 Vite 服务器加载保证flue/runtime在整张模块图中只存在一份。这是因为运行时维护模块级注册表providers、agent 注册、instrumentation出现第二份拷贝会静默分裂这些状态。earendil-works/pi-ai同样被强制 external 以避免 provider 注册表分裂run-local.ts。真正的持久化提交路径bootstraprun-bootstrap.ts走的是与 HTTP 部署完全相同的assembleNodeAgentRuntime组装链路注册、持久化 connect/migrate/validate、createNodeAgentCoordinator、运行时 seed再通过运行时观察缝观察规范会话流上的提交结算。不创建任何 HTTP 内容无 Hono、无监听器、无渠道。stdout 纪律flue run把 stdout 保留给最终消息可管道化输出运行期间 Agent 模块的console.log/info/debug会被重定向到 stderrrun-local.ts。信号排水只有flue run在执行期间安装 SIGINT/SIGTERM 处理器把运行排空到有界的关闭退出码 130/1435 秒上限避免中断写一半的状态其他命令保持 Node 默认行为run.ts。--json模式输出稳定、可机器解析的信封便于脚本消费{ id: conversationId, agent: agent identity, submissionId: submissionId, outcome: completed, message: agent reply, uid: uid, when present }失败或中止时也会输出对应的信封outcome: error/aborted与error载荷保证 stdout 恰好一个 JSON 对象run.ts。flue add / flue updateBlueprint 实现指南flue add [kind] [name|url]与flue update kind name|url从 Blueprint 注册中心获取面向 AI 编码 Agent 的实现指南——它不是 npm 包或运行时抽象而是一份 Markdown 指南CLI 负责抓取并打印编码 Agent 负责修改用户项目blueprints.ts。支持四种 kind对应 blueprints/README.mdKind产出物sandbox远程执行提供商的沙箱适配器channel已校验的提供商入口、客户端与应用侧工具database实现 FluePersistenceAdapter的数据库适配器tooling可观测性、评测等开发者工具集成典型用法# 列出所有可用 blueprint flue add # 获取指定 blueprint 并管道给编码 Agent flue add sandbox daytona | claude flue update channel slack | claude # 传入 URL 时选择 kind 根指南并把 URL 替换进 {{URL}} 占位符 flue add channel https://developers.notion.com/reference/webhooks | codex # --print 强制向 stdout 输出原始 Markdown即便调用者不是 Agent flue add sandbox daytona --print机制细节注册中心默认地址为https://flueframework.com/cli/blueprints/slug.md单次抓取超时 30 秒可用FLUE_REGISTRY_TIMEOUT_MS覆盖名称匹配大小写不敏感支持aliases。命令通过vercel/detect-agent检测调用者是否为编码 Agent如claude、codex、cursor-agent、opencode、pi是则直接向 stdout 输出指南正文否则打印人类可读的操作指引。kind 目录由构建期生成的索引scripts/generate-blueprint-index.ts提供。Blueprint 源文件以blueprints/kind--name.md命名双横线避免与提供商名中的单横线混淆通用 kind 指南用kind.md并标记root: true。每个指南以JSON frontmatter开头不是 YAML包含kind、version正整数、单调递增、website具名 blueprint 必填、aliases、root字段正文中// flue-blueprint: kind/slugversion标记主集成文件并以唯一的累积式## Upgrade Guide结尾从 V2 起每个版本必须附带完整 unified diff供编码 Agent 从上一版本机械升级。完整契约见 blueprints/README.md。flue docs离线文档浏览与检索flue docs让你无需浏览器即可浏览随 CLI 捆绑的文档flue docs # 列出所有页面 flue docs read guide/sandboxes # 以 Markdown 打印指定页面 flue docs search durable execution # 全文搜索JSON 结果搜索由 MiniSearch 驱动索引字段含 title、headings、description、content权重为 title 4 / headings 3 / description 2启用前缀匹配与 0.2 模糊度docs.ts。搜索结果输出为 JSON{ query, results }最多 8 条含 path/title/description/excerpt/score便于脚本或 Agent 消费flue docs read则直接输出# 标题 引言 正文的纯 Markdown可直接喂给编码 Agent。从脚手架到生产的完整工作流综合以上内容一个典型的 Flue 开发流程是# 1. 初始化项目交互式选择目标与形态或用 flags 静默指定 flue init ./my-agent-app --target node --deploy cd my-agent-app npm install # 2. 在 .env 中填入模型提供商 API Key任意 Pi 支持的提供商 # 3. 本地无服务器地运行 Agent npx flue run src/agents/hello.ts --message Say hello! # 4. 继续同一会话持久化 npx flue run src/agents/hello.ts --message And then? --id id # 5. 启动开发服务器 / 构建部署 npm run dev npm run build npm run start # Node 目标 npm run deploy # Cloudflare 目标 # 6. 用 blueprint 扩展渠道、沙箱与数据库 npx flue add | claude # 7. 随时离线查阅文档 npx flue docs search sandbox深入阅读指引packages/cli/README.mdCLI 包概述本文核心文档packages/cli/src/cli.ts 与 packages/cli/src/main.ts命令注册与顶层分发packages/cli/src/commands/run.ts 与 packages/cli/src/lib/run-local.tsflue run的 flag 校验与非监听 Vite 单一运行时图实现packages/cli/src/lib/run-bootstrap.ts与 HTTP 部署共享的持久化提交链路packages/cli/src/commands/init.ts 与 packages/cli/src/lib/init.ts脚手架规划与写入packages/cli/src/commands/blueprints.ts 与 blueprints/README.mdBlueprint 注册中心客户端与指南契约packages/cli/src/commands/docs.ts基于 MiniSearch 的离线文档检索packages/runtime/srcHarness、会话、工具、沙箱等运行时核心packages/vitevite dev/vite build插件Node 与 Cloudflareexampleshello-world、assistant、cloudflare、各类 channel 与沙箱的真实可运行示例【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考