Flue路由机制解析app.ts如何把Agent映射为HTTP路由新手完整指南【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue是一个沙箱化的 Agent 框架sandbox agent framework它的核心设计只有一句话app.ts就是整个应用的路由表。写一个 Agent 函数再用一行createAgentRouter挂载到任意 HTTP 路径它立刻就有了发消息、读会话、中止任务的完整 HTTP 接口——全程不需要手写任何路由代码。本文带你从原理到实战看懂这套函数即路由的机制。一、为什么 app.ts 是唯一的路由入口Flue从不自动挂载Agent。你在文件里定义了一个 Agent它只是可寻址要不要暴露成 HTTP 接口、暴露到哪个路径完全由你决定而决定的地方只有一个src/app.ts的默认导出。import { createAgentRouter } from flue/runtime/routing; import { Hono } from hono; import { Hello } from ./agents/hello.ts; const app new Hono(); app.route(/agents/hello, createAgentRouter(Hello)); export default app;这个默认导出只需要一个fetch()方法Fetchable 接口Hono 应用天然满足任何 fetch 风格的框架都行。同一份app.ts既能跑在 Node.js 上也能原样部署为 Cloudflare Worker。二、一行挂载createAgentRouter 如何把 Agent 变成子路由createAgentRouter(agent)是一个纯工厂函数无副作用、无参数选项可以调用任意多次也可以一次都不调用。它做三件事源码见 registration.ts解析 Agent 的持久身份identity——按优先级取构建时注入的绑定 →agentName静态属性 → 函数名本身用 Hono 建一个子路由内部预置 5 条标准 HTTP 路由把子路由挂到你指定的路径下从此这个路径就服务这个 Agent 的所有会话。而 Agent 的身份绑定发生在构建期flue/vite插件会对带use agent指令的模块做转换把源级函数名以字符串字面量盖章上去所以代码被压缩混淆后Agent 的持久身份依然稳定转换逻辑见 use-agent-transform.ts。三、每个 Agent 自带哪 5 条标准 HTTP 路由以挂载在/agents/support为例每个会话的 URL 是「挂载路径 会话 id」如/agents/support/ticket-8472路由作用POST /:id发送一条消息202 收件即返回GET /:id读取会话快照 / 增量 / 实时流HEAD /:id读取会话流元数据POST /:id/abort中止进行中和排队中的工作GET /:id/attachments/:attachmentId下载附件字节发送是发射后不管服务端持久化收件后立即返回202和流地址回复落在会话里你再通过GET或官方 SDKcreateFlueClient读取——URL 就是全部契约。四、路由 ≠ 身份换 URL 不会丢会话这是新手最容易误解的一点挂载路径只是寻址会话永远用 Agent 的持久身份做键函数名或agentName覆盖值格式如IssueTriage或issue-triage。这带来两个实用好处你可以把 Agent 从/agents/hello搬到/api/v2/hello无需任何数据迁移同一个 Agent 挂到两个路径两端访问的是同一份会话数据。反过来身份全局唯一重复注册或一函数双绑Flue 会直接报错拒绝。五、给挂载的 Agent 加鉴权普通中间件就行挂载的 Agent没有内置认证——任何能访问会话 URL 的人都能发消息、读历史、中止任务。Flue 的做法是把它当普通敏感端点在app.ts里用标准 Hono 中间件在挂载点之前加校验app.use(/agents/support/*, async (c, next) { const user await verifySession(c.req.raw); if (!user) return c.json({ error: unauthorized }, 401); const [conversationId] c.req.path.slice(/agents/support/.length).split(/); if (!(await canAccessTicket(user, conversationId))) return c.json({ error: forbidden }, 403); return next(); }); app.route(/agents/support, createAgentRouter(Support));注意末尾的/*一条中间件就覆盖了提示、读取、中止、附件下载所有路由。会话 id 是调用方自选的路径段所以必须做归属校验否则任何人猜 id 就能读别人的会话。六、批量挂载一整个 Agent 目录Agent 多了也不想手敲每一行用 Vite 的import.meta.glob枚举agents/目录循环挂载——每次挂载依然是显式的只是由代码生成const modules import.meta.glob(./agents/*.ts, { eager: true }); for (const mod of Object.values(modules)) { for (const [name, agent] of Object.entries(mod)) { if (typeof agent ! function || !/^[A-Z]/.test(name)) continue; app.route(/agents/${agent.agentName ?? name}, createAgentRouter(agent)); } }另外记住一个关键区分注册 ≠ 暴露。没挂载的 Agent 只是 HTTP 不可达仍可通过服务端dispatch(...)、channel 或定时任务驱动——内部 Agent 完全可以保持dispatch-only不对外开口。七、相关文件速查官方路由指南routing.md路由工厂与身份注册源码registration.tsFetchable 接口契约routing.ts完整示例入口含中间件、批量挂载hello-world/src/app.ts被挂载的 Agent 函数示例hello.ts构建期身份绑定转换use-agent-transform.ts小结Flue 的路由哲学是显式即正确——app.ts写了什么路由应用就长什么样createAgentRouter一行搞定映射URL 随你选身份永不丢安全交给中间件。掌握这三点你就能把任意 Agent 变成生产级 HTTP 服务。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flue路由机制解析：app.ts如何把Agent映射为HTTP路由（新手完整指南）
Flue路由机制解析app.ts如何把Agent映射为HTTP路由新手完整指南【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue是一个沙箱化的 Agent 框架sandbox agent framework它的核心设计只有一句话app.ts就是整个应用的路由表。写一个 Agent 函数再用一行createAgentRouter挂载到任意 HTTP 路径它立刻就有了发消息、读会话、中止任务的完整 HTTP 接口——全程不需要手写任何路由代码。本文带你从原理到实战看懂这套函数即路由的机制。一、为什么 app.ts 是唯一的路由入口Flue从不自动挂载Agent。你在文件里定义了一个 Agent它只是可寻址要不要暴露成 HTTP 接口、暴露到哪个路径完全由你决定而决定的地方只有一个src/app.ts的默认导出。import { createAgentRouter } from flue/runtime/routing; import { Hono } from hono; import { Hello } from ./agents/hello.ts; const app new Hono(); app.route(/agents/hello, createAgentRouter(Hello)); export default app;这个默认导出只需要一个fetch()方法Fetchable 接口Hono 应用天然满足任何 fetch 风格的框架都行。同一份app.ts既能跑在 Node.js 上也能原样部署为 Cloudflare Worker。二、一行挂载createAgentRouter 如何把 Agent 变成子路由createAgentRouter(agent)是一个纯工厂函数无副作用、无参数选项可以调用任意多次也可以一次都不调用。它做三件事源码见 registration.ts解析 Agent 的持久身份identity——按优先级取构建时注入的绑定 →agentName静态属性 → 函数名本身用 Hono 建一个子路由内部预置 5 条标准 HTTP 路由把子路由挂到你指定的路径下从此这个路径就服务这个 Agent 的所有会话。而 Agent 的身份绑定发生在构建期flue/vite插件会对带use agent指令的模块做转换把源级函数名以字符串字面量盖章上去所以代码被压缩混淆后Agent 的持久身份依然稳定转换逻辑见 use-agent-transform.ts。三、每个 Agent 自带哪 5 条标准 HTTP 路由以挂载在/agents/support为例每个会话的 URL 是「挂载路径 会话 id」如/agents/support/ticket-8472路由作用POST /:id发送一条消息202 收件即返回GET /:id读取会话快照 / 增量 / 实时流HEAD /:id读取会话流元数据POST /:id/abort中止进行中和排队中的工作GET /:id/attachments/:attachmentId下载附件字节发送是发射后不管服务端持久化收件后立即返回202和流地址回复落在会话里你再通过GET或官方 SDKcreateFlueClient读取——URL 就是全部契约。四、路由 ≠ 身份换 URL 不会丢会话这是新手最容易误解的一点挂载路径只是寻址会话永远用 Agent 的持久身份做键函数名或agentName覆盖值格式如IssueTriage或issue-triage。这带来两个实用好处你可以把 Agent 从/agents/hello搬到/api/v2/hello无需任何数据迁移同一个 Agent 挂到两个路径两端访问的是同一份会话数据。反过来身份全局唯一重复注册或一函数双绑Flue 会直接报错拒绝。五、给挂载的 Agent 加鉴权普通中间件就行挂载的 Agent没有内置认证——任何能访问会话 URL 的人都能发消息、读历史、中止任务。Flue 的做法是把它当普通敏感端点在app.ts里用标准 Hono 中间件在挂载点之前加校验app.use(/agents/support/*, async (c, next) { const user await verifySession(c.req.raw); if (!user) return c.json({ error: unauthorized }, 401); const [conversationId] c.req.path.slice(/agents/support/.length).split(/); if (!(await canAccessTicket(user, conversationId))) return c.json({ error: forbidden }, 403); return next(); }); app.route(/agents/support, createAgentRouter(Support));注意末尾的/*一条中间件就覆盖了提示、读取、中止、附件下载所有路由。会话 id 是调用方自选的路径段所以必须做归属校验否则任何人猜 id 就能读别人的会话。六、批量挂载一整个 Agent 目录Agent 多了也不想手敲每一行用 Vite 的import.meta.glob枚举agents/目录循环挂载——每次挂载依然是显式的只是由代码生成const modules import.meta.glob(./agents/*.ts, { eager: true }); for (const mod of Object.values(modules)) { for (const [name, agent] of Object.entries(mod)) { if (typeof agent ! function || !/^[A-Z]/.test(name)) continue; app.route(/agents/${agent.agentName ?? name}, createAgentRouter(agent)); } }另外记住一个关键区分注册 ≠ 暴露。没挂载的 Agent 只是 HTTP 不可达仍可通过服务端dispatch(...)、channel 或定时任务驱动——内部 Agent 完全可以保持dispatch-only不对外开口。七、相关文件速查官方路由指南routing.md路由工厂与身份注册源码registration.tsFetchable 接口契约routing.ts完整示例入口含中间件、批量挂载hello-world/src/app.ts被挂载的 Agent 函数示例hello.ts构建期身份绑定转换use-agent-transform.ts小结Flue 的路由哲学是显式即正确——app.ts写了什么路由应用就长什么样createAgentRouter一行搞定映射URL 随你选身份永不丢安全交给中间件。掌握这三点你就能把任意 Agent 变成生产级 HTTP 服务。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考