Flue Vite插件深度解析use agent如何被扫描与转换【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue 是一款面向开发者的沙箱智能体Agent框架它的核心 Vite 插件flue/vite只需在 Vite 配置中写入flue()就能自动完成一件事扫描整个源码目录找出所有带use agent指令的模块并在构建时把它们转换成可注册、可持久化身份的 AI Agent。这篇文章带你完整看懂这套扫描与转换机制的运作流程 一、use agent 是什么一行指令的声明式魔法在 Flue 中定义一个 Agent 只需要两步在文件顶部写一行use agent;再导出一个首字母大写的函数。框架约定函数即 Agent——大写的导出函数就是组件化的智能体小写导出只是普通工具函数。这个约定和 React 中大写组件的思路一脉相承但它的背后并非简单的文本匹配而是一整套AST 级别的扫描与转换管线。理解它就理解了 Flue Vite 插件的精髓。二、扫描阶段从目录遍历到 AST 语义识别扫描逻辑集中在 packages/vite/src/agent-scan.ts整个流程可以拆成三层漏斗逐层过滤出真正的 Agent 模块 1. 第一层glob 目录遍历插件调用tinyglobby对源码根目录执行递归遍历默认模式**/*.{ts,mts,js,mjs}并自动排除node_modules/、dist/、.wrangler/等目录。这一步只负责圈定候选文件不读内容。你也可以在flue.config.ts的agents字段里用 glob 进一步收窄扫描范围。2. 第二层原始文本预过滤对每个候选文件先做一个极轻量的检查源码里是否出现了字符串use agent。这一步保证绝不误判漏报但可能误报——比如把use agent写在注释或提示词字符串里的文件也会进入下一层由 AST 解析来裁决。3. 第三层oxc 解析器做真正的语义判断这一步是关键Flue 直接复用 Vite 内置的 oxc 解析器parseAstAsync把文件解析成 AST然后检查指令序言directive prologue——即 ECMAScript 规范中use strict所在的位置。只有当use agent作为真正的指令出现在序言区时该文件才被认定为 Agent 模块。注释、字符串、转义序列统统不算数因此完全遵循标准 JS/TS 语义没有任何正则猜文本的脆弱启发式。确认是 Agent 模块后扫描器会遍历顶层语句收集所有大写字母开头的导出函数支持函数声明、const箭头函数、默认导出、export { X as Y }别名等所有形式并推导出每个 Agent 的三件身份装备属性示例IssueTriage用途identityIssueTriage持久化身份键可用agentName静态属性覆盖classNameFlueIssueTriageAgentCloudflare 目标下生成的 Durable Object 类名bindingNameFLUE_ISSUE_TRIAGE_AGENT生成的绑定名扫描结果还会经过四道校验身份格式合法、全局唯一、不与已折叠的持久化标识符冲突、同一函数不能被两个名字导出。任何违规都会抛出自带修复建议的结构化错误而不是让你面对一堆看不懂的构建报错。三、转换阶段注入身份绑定让压缩后也不丢身份扫描回答谁是 Agent转换则回答Agent 如何带着身份跑起来。转换逻辑在 packages/vite/src/use-agent-transform.ts它的思路非常巧妙不改写你写的任何一行代码只在文件末尾追加代码。追加的尾注长什么样对模块中的每个 Agent转换用magic-string在源码末尾追加这样几行从flue/runtime导入身份绑定函数__flueBindAgentModule通过自导入self-import拿到模块自身的命名空间对每个 Agent 调用一次绑定把{ identity: ... }作为字符串字面量写死进去。这里藏着两个精妙设计自导入规避改写无论你的 Agent 是函数声明、const 初始化还是默认导出追加代码都能通过模块命名空间拿到它无需碰原文字面量身份抗压缩身份是构建期就写死的字符串即使产物被压缩混淆Agent 的持久化身份也原封不动——这对 Cloudflare 目标下按身份生成 Durable Object 类名至关重要。绑定发生在模块求值时因此app.ts在自己求值阶段调用createAgentRouter(agent)时身份就已经就位了。四、热更新文件一变就合并式再扫描开发时增删 Agent 文件不能要求重启服务。packages/vite/src/flue-plugin.ts 中的transform钩子先做钩子级过滤文件扩展名 是否含use agent文本再对命中模块二次校验是否属于扫描集合才交给转换器——扫描与转换共享同一套判定函数保证两者永远不会互相打架。而文件监听则交给 packages/vite/src/watch-queue.ts 里的合并队列当保存风暴格式化整仓、切分支瞬间产生几十个事件时队列保证最多只有一次在飞、一次排队的再扫描而不是每个事件都全量跑一遍。再扫描若发现 Agent 集合变化会自动刷新virtual:flue/agents虚拟模块并热重载应用若只是函数体编辑则由 Vite 自身的模块失效机制处理扫描器不插手。五、扫描结果的三个去向扫描出的 Agent 集合不是白扫的它最终流入三处virtual:flue/agents虚拟模块——插件现场生成一个注册表模块每个 Agent 文件一条 import、每个 Agent 一条{ identity, agent }记录应用启动时自动注册Cloudflare Worker 入口——virtual:flue/worker按 Agent 生成每 Agent 一个 Durable Object 类与绑定配置见 packages/vite/src/cloudflare-entry.tsdev server 的 Agent 热重载——配合 packages/vite/src/node-dev.ts 中的控制器Node 目标下应用代码与配置变更即时生效。六、关键源码路径速查想了解什么去哪里看插件总入口、虚拟模块、transform 过滤packages/vite/src/flue-plugin.ts扫描算法、指令序言检测、身份推导packages/vite/src/agent-scan.ts尾部注入与自导入绑定packages/vite/src/use-agent-transform.ts合并式监听队列packages/vite/src/watch-queue.ts一个真实的 use agent 模块示例examples/hello-world/src/agents/hello.ts插件包定义与依赖packages/vite/package.json一句话总结Flue 的 Vite 插件用glob 圈定 → 文本预过滤 → AST 精判三级漏斗找出 Agent用只追加、不改写的尾注注入构建期身份绑定再靠合并队列让热更新又快又稳——声明式的一行use agent背后是一整条严谨的编译器管线。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考