Cursor 插件，适用于 Hono v4（TypeScript 边缘 Web 框架）。包含 59 个 LLM 回归测试，配有 BAD/CORRECT 配对。固定使用 hono ^4.12.19（>= 4.9.7 以修复 CVE-2025-59139）。涵盖 Express 中间件泄漏、v3 时代已移除的 API、RPC 推断陷阱、Cloudflare Workers 注意事项、安全默认设置以及 JSX SSR 加固。
针对 Hono v4（TypeScript 边缘 Web 框架）+ TypeScript 的 Cursor 插件。固定版本为 hono ^4.12.19、@hono/zod-validator ^0.8.0、@hono/zod-openapi ^1.4.0（需配合 zod ^4.x）、@hono/node-server ^2.0.3（Node 20+）。教给那些训练数据基于 2024 年之前的 LLM 所不知道的 v4 API（c.json() 始终是类型化的、验证器抛出 HTTPException、来自 hono/cookie 的 getCookie/setCookie、c.env 作为属性、来自 hono/streaming 的 streamText、来自 hono/dev 的 showRoutes、来自 hono/adapter 的 getRuntimeKey、来自 hono/service-worker 的 fire(app)、替代已弃用 serveStatic 的 Workers Static Assets 绑定、用于 Deno 的 JSR @hono/hono）。通过错误/正确 TypeScript 对比对，捕获 50 多个 LLM 回归错误。
不存在 Hono v5。 最新稳定版是 v4.12.19。任何生成的代码中的 "v5" 都是幻觉。
Hono 的维护者自己提交了 issue #3906（"llm.txt 文件"）和 issue #4812（"Hono 的官方 AI Agent 技能"），明确因为 "LLM 基本上不了解最新 Hono 的工作方式。" 2025 年之前的训练数据是 v3 时代的。LLM 会生成：
c.jsonT() 而不是 c.json()（自 v4.0.0 起始终是类型化的）c.stream() / c.streamText() 作为 Context 方法（在 v4 中移到了 hono/streaming）c.env() 函数形式（现在是属性；通过 hono/adapter 中的 getRuntimeKey() 检测运行时）c.req.cookie()（已移除；使用 hono/cookie 中的 getCookie(c)）app.showRoutes()、app.routerName（移到了 hono/dev）c.json() 缺少 return（解析为 undefined；v4 抛出 "Context is not finalized"）res.json() / res.send() 而不是 c.json()（Hono 中没有 res）(req, res, next) 中间件签名（使用 (c, next)）(err, req, res, next) 错误中间件（使用 app.onError + HTTPException）app.use(express.json()) 请求体解析器（Hono 通过 c.req.json() 按需解析）import cors from 'cors' 来自 npm（使用 ）new Hono() 不带 Bindings / Variables 泛型（c.env 是 {}）app.get(...) 再 app.post(...)）—— 丢失 RPC 类型app.route() 调用作为语句—— 同样规则Context（丢失路径参数推断，违反 Hono 最佳实践）app.use('/path', zValidator(...)) 而不是作为路由参数（TS 错误：'json' 不能赋给 'never'）c.notFound()（无法在客户端进行类型化）new Response(JSON.stringify(...)) 在 RPC 路由中（客户端看到 ）process.env.X（undefined；使用 c.env.X 配合类型化的 Bindings）fs / path 导入 在 Workers 中（没有文件系统）compatibility_flags: ["node_compat"] 旧标志（使用 nodejs_compat）serveStatic 来自 hono/cloudflare-workers（自 v4.3.0；使用 asset binding）c.executionCtx.waitUntil() 用于 fire-and-forgetif (c.executionCtx)（在 Bun 和 Next.js App Router 上，getter 会抛出异常）.run() / .first() / （worker 终止时插入操作被取消）secureHeaders() 中间件csrf()cors({ origin: '*', credentials: true })（浏览器静默丢弃；AJAX 失败）bodyLimit()，且 hono 必须锁定在 >= 4.9.7 以修复 CVE-2025-59139httpOnly / secure / sameSite / pathsameSite: 'None' 没有 secure: true（静默丢弃）etag() / notFound 处理器（死代码；只有顶层才会触发）/users 和 /users/ 是不同路由）await next() 多次（重复执行下游工作）app.use(prefix, mw) + app.route(prefix, subApp) 重叠（中间件触发两次）app.basePath('/api') 作为语句（前缀从类型中丢失）serve(app) 在 @hono/node-server 上（使用 serve({ fetch: app.fetch })）export default app 在 Workers 上（使用 export default { fetch: app.fetch }）Bun.serve({ fetch: app })（使用 app.fetch）c.req.query() 不传参数时，期望得到单个值c.req.param('id')（当路径中没有 :id 时返回 undefined）@hono/zod-openapicors() 挂载在路由之后（永远不会匹配）少数的 Hono 规则已经存在于 cursor.directory 和 awesome-cursorrules（PR #152）：它们涵盖了 c.json() 返回、zValidator + Zod、Workers 的 c.env、链式路由的 RPC、以及 Workers 的 app.fetch 导出。它们有三个结构性问题，此插件已修复：
c.jsonT、c.stream、c.env()、c.req.cookie、app.showRoutes、hono/middleware 桶导入和 app.handleEvent——这些都在 v4.0.0（2024-02）中移除了。现有规则静默允许它们。(req, res, next)、(err, req, res, next)、npm 的 cors、app.use(express.json())、supertest、c.json 缺少 return——这些在 LLM 生成的 Hono 代码中持续出现。现有规则把它们当作一次性问题处理。此插件提供：
globs，使得路由/RPC 检查在 src/routes/** 上触发，Workers 检查在 wrangler.{toml,jsonc} + Worker 入口上触发，安全检查在中间件文件上触发等。/hono-new-route、/hono-rpc-setup、/hono-cloudflare-workers-setup、/hono-migrate-to-v4、/hono-validatecorrect-sample（黄金标准 Hono 4.12.19 + Workers + D1 + Drizzle + Zod）和 anti-pattern-sample（Hono v3 遗留问题，包含 25+ 个已跟踪的违规）将规则、技能和代理复制到你项目的 Cursor 配置中。先备份现有文件；cp -r 会覆盖同名规则。
git clone https://github.com/RoninForge/roninforge-hono.git
# 使用 -n 避免覆盖现有同名自定义规则。
cp -rn roninforge-hono/rules/* your-project/.cursor/rules/
cp -rn roninforge-hono/skills/* your-project/.cursor/skills/
cp -rn roninforge-hono/agents/* your-project/.cursor/agents/
或者将整个仓库作为 git 子模块放在 your-project/.cursor/plugins/ 下。请参考 Cursor 插件文档 了解当前 Cursor 版本的全局安装路径。
tests/fixtures/correct-sample/ 是一个精简的 Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod 项目，展示了黄金标准形状：链式路由、类型化 RPC、zValidator 作为路由参数、c.json({ ... } as const, status) 类型化响应、secureHeaders + cors + csrf + bodyLimit 栈、顶层 app.onError + app.notFound、export default { fetch: app.fetch } satisfies ExportedHandler<Env>。
tests/fixtures/anti-pattern-sample/ 则相反。每个文件违反了一个编号的反模式。package.json 特意将版本锁定为 hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0——v3 时代是大多数 2025 年之前模型的 LLM 训练数据基线，加上已弃用的同伴库（LLM 仍会推荐）。已跟踪的违规包括：c.json 缺少 return（#1）、(req, res) Express 处理器形状（#2）、(req, res, next) 中间件（#3）、(err, req, res, next)（#4）、npm cors（#6）、supertest（#12）、c.jsonT（#13）、addEventListener('fetch') + app.handleEvent（#15）、c.req.cookie（#16）、 函数调用（#17）、 桶导入（#20）、（#23）、没有 Bindings/Variables（#24）、RPC 路由中的 （#29）、Workers 中的 （#34）、 标志（#36）、 中的 （#37）、未 await 的 D1（#40）、cors + credentials（#43）、没有 的 cookie（#45）、 没有 （#46）、硬编码 JWT 密钥（#48）、子应用 （#50）、 作为语句（#53）、Workers 上的 （#55）、已弃用的 + 引用。
规则针对 hono ^4.12.19，需要 Node 20+（如果使用 Node）、Bun 最新版、Deno 最新版、Wrangler ^4.0.0。大多数模式向后兼容到 Hono 4.0.0（2024 年 2 月），差异已在文中注明。最低版本：
hono >= 4.9.7 必须——CVE-2025-59139 / GHSA-92vj-g62v-jqhh bodyLimit 绕过修复hono >= 4.12.18 如果使用 JSX SSR，则必须——标签名、属性名、CSS 注入强化@hono/node-server >= 2.0.0 需要 Node 20+@hono/zod-openapi >= 1.0.0 需要 zod ^4.0.0（对等依赖仅限 ^4.0.0，不是 ^3.x）compatibility_date >= "2024-09-23" 需要以使 nodejs_compat 隐含 nodejs_compat_v2如果规则引用了某个版本（c.json() 自 v4.0.0 开始始终类型化，c.text() 自 v4.3.0 类型化，用于 Deno 的 JSR 自 v4.4.0，secureHeaders Permissions-Policy 自 v4.6.0，Standard Schema 验证器自 v4.7.0，fire(app) 自 v4.8.0，JSR parseResponse 自 v4.9.0，hc 上的类型化基础 URL 自 v4.11.0，$path() 方法自 v4.12.0），请根据你已安装的版本核对 changelog 后再采用。
MIT——参见 LICENSE
RoninForge 为使用 AI 编码助手的开发者构建免费工具：
addEventListener('fetch') + app.handleEvent()（Service Worker 语法；使用 export default { fetch: app.fetch }）app.head(...) 路由（HEAD 在 v4 中自动从 GET 派生）hono/nextjs 导入（使用 hono/vercel）hono/middleware 桶导入（使用每个中间件的子路径）c.req.headers() / c.req.body() / c.req.signal() 访问器方法（使用 c.req.raw.*）FC 隐式 children（使用 PropsWithChildren<P>）app.fire()（自 v4.8.0 弃用；使用 hono/service-worker 中的 fire(app)）import { Hono } from 'https://deno.land/x/hono/mod.ts' 在 Deno 上（自 v4.4.0 已过时；使用 jsr:@hono/hono）hono/corssupertest 用于测试（使用 app.request() / testClient(app)）c.req.body 作为已解析的对象（它是一个 ReadableStream）c.req.parseBody() 用于 JSON（仅用于 form / multipart）c.req.text() 再 c.req.json()（请求体会被消费两次）c.userId = ... 内联赋值（使用 c.set('userId', ...) 配合类型化的 Variables）unknownhc<AppType>('/') 相对 URL（调用 $url() 时抛出异常）drizzle-orm、fs、原生依赖——RPC 包体积膨胀的头号陷阱）createMiddleware<Env>（Variables 类型不传播）.all()cache()streamText（Workers 128MB 限制）secureHeaders() / csrf()；没有提到 bodyLimit 的 CVE-2025-59139（在 v4.9.7 修复）；没有解决 RPC 客户端陷阱（相对 URL、值导入泄漏、c.notFound 类型化）。| 规则 | 范围（globs） | 作用 |
|---|
hono-anti-patterns | **/*.ts,**/*.js,**/*.tsx,**/*.jsx,wrangler.{toml,jsonc,json} | 59 个 LLM 回归错误的错误/正确对比对，按类别 A-H 组织（Express 泄漏、v3 时代 API、TypeScript / RPC、CF Workers、安全、路由、运行时、较小问题） |
hono-core | **/*.ts,**/*.tsx,**/*.js,**/*.jsx（始终应用） | 应用初始化（带类型化的 Bindings + Variables）、Context API、请求访问器、中间件签名、内置中间件列表、Cookie 辅助函数、运行时检测 |
hono-routing-and-rpc | src/**/*.ts,src/routes/**/*,src/api/**/*,src/server/**/*,src/client/**/*,routes/**/* | 链式路由、子应用组合、basePath 不可变性、双执行重叠修复、子应用 notFound 死代码、hc<AppType> 设置、import type 规则、类型化的基础 URL、$path()、TanStack Query / SWR 集成、factory.createHandlers、30+ 路由时的 RPC 缓解策略 |
hono-validators | src/**/*.ts,routes/**/*.ts,api/**/*.ts,handlers/**/*.ts | @hono/zod-validator 放置位置、c.req.valid() 访问器、验证器失败时抛出的特性、@hono/zod-openapi（zod ^4 对等依赖陷阱）、@hono/standard-validator、@hono/valibot-validator、内置 hono/validator、决策树 |
hono-cloudflare-workers | src/**/*.ts,worker/**/*.ts,workers/**/*.ts,wrangler.{toml,jsonc,json},**/cloudflare-env.d.ts,**/worker-configuration.d.ts | wrangler.jsonc 标准形状、兼容性标志规则、wrangler types、类型化的 Bindings、c.env vs process.env、c.executionCtx.waitUntil + 可移植性、Static Assets 绑定、D1 await、Drizzle + D1 栈、Hyperdrive + Prisma 适配器陷阱、用于 WebSockets 的 Durable Objects、自定义域名的 hono/cache 规则、ES Module Worker 导出 |
hono-security | src/**/*.ts,src/**/*.tsx,src/middleware/**/*.ts,src/auth/**/*.ts,src/index.ts,src/app.ts | secureHeaders()、csrf()、CORS 白名单、bodyLimit() + CVE-2025-59139 最低版本 4.9.7、Cookie 默认值、来自 c.env 的 JWT 密钥、无 PII 泄漏的日志记录、etag() + cache()、IP 限制、超时、请求 ID、认证库决策（Lucia 已弃用；推荐 Better Auth / Clerk）、优先使用 @sentry/hono 而非 @hono/sentry |
hono-error-handling | src/**/*.ts,routes/**/*.ts,api/**/*.ts,middleware/**/*.ts,src/index.ts,src/app.ts | HTTPException 标准抛出方式、app.onError 全局处理器、app.notFound 仅顶层有效、通过判别联合类型实现类型化的 RPC 错误、验证器抛出、通过 @sentry/hono 集成 Sentry、使用 pino 脱敏的结构化日志记录、错误响应形状约定 |
hono-jsx | **/*.tsx,**/*.jsx,**/jsx-runtime.ts,src/components/**/*,src/views/**/*,src/islands/**/*,app/islands/**/* | hono/jsx 服务端渲染、tsconfig 设置、FC 不包含 children、用于布局的 jsxRenderer 中间件、hono/jsx/streaming 配合 Suspense、hono/jsx/dom 客户端组件、HonoX islands、htmx 集成、JSX SSR 安全最低版本 4.12.18 |
hono-testing | **/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,vitest.config.{ts,js},**/test/**/*.ts,**/tests/**/*.ts,**/__tests__/**/*.ts | app.request() 通用模式、testClient(app) 类型化 RPC 测试、Vitest + @cloudflare/vitest-pool-workers 实现真实运行时的 D1、applyD1Migrations 测试夹具、Bun + bun:test、快照测试、中间件/验证器/waitUntil 测试、永远不使用 supertest |
hono-deployment | wrangler.{toml,jsonc,json},deno.json,deno.jsonc,package.json,Dockerfile,fly.toml,vercel.json,netlify.toml,**/serverless.yml,**/template.yaml | Cloudflare Workers（wrangler.jsonc + 兼容性标志）、Bun.serve、Deno + JSR、@hono/node-server v2（Node 20+）、AWS Lambda + Lambda@Edge、Vercel Edge、Netlify、构建流水线、最低版本固定、常见部署错误 |
| 技能 | 命令 | 作用 |
|---|
| 新路由 | /hono-new-route | 搭建链式子应用，带 zValidator 作为路由参数、c.req.valid() 类型化访问、c.json({ ... } as const, status) 用于类型化 RPC 响应、Bindings + Variables 泛型、子应用导出为 typeof users、通过链式 .route() 连接到父应用。拒绝 Rails 风格控制器、RPC 路由中的 c.notFound()、原始的 new Response()。 |
| RPC 设置 | /hono-rpc-setup | 搭建 hc<AppType> 客户端，带 import type（关键规则）、绝对基础 URL、类型化的共享 api 模块、通过 InferRequestType / InferResponseType 集成 TanStack Query / SWR、parseResponse 工具、$path() 方法、30+ 路由时的 IDE 变慢缓解策略。 |
| Workers 设置 | /hono-cloudflare-workers-setup | 搭建全新的 Hono + Workers 项目，带 wrangler.jsonc（不是 .toml）、nodejs_compat、从 wrangler types 生成的类型化 Bindings、D1 + Drizzle 中间件模式、secureHeaders + cors + csrf + bodyLimit 栈、用于 @cloudflare/vitest-pool-workers 的 Vitest 配置。 |
| 迁移到 v4 | /hono-migrate-to-v4 | 分阶段 v3 -> v4 迁移：提升最低版本（CVE-2025-59139 最低要求）、替换 c.jsonT / c.stream / c.env() / c.req.cookie / app.showRoutes / app.handleEvent、删除 hono/middleware 桶导入、切换 Deno 到 JSR、@hono/node-server v2 + Node 20+、为验证器抛出注册 app.onError。 |
| 验证 | /hono-validate | 运行 validate-plugin.sh + tsc --noEmit + 测试 + grep 审计，检测类型检查器无法捕获的语法反模式（c.jsonT、c.req.cookie、process.env、node_compat、hono/cloudflare-workers 中的 serveStatic、硬编码 JWT 密钥、缺少 secure 的 sameSite:'None'、缺少 bodyLimit、hc 客户端的值导入）。 |
| 代理 | 作用 |
|---|
hono-reviewer | 按严重性审查 Hono v4 + TypeScript 代码。CRITICAL：hono < 4.9.7（CVE）、v5 引用（幻觉）、cors 通配符 + credentials、sameSite:'None' 缺少 secure、硬编码 JWT 密钥、Workers 中的 process.env、缺少 bodyLimit、基于 cookie 认证时没有 csrf、已弃用的 serveStatic、JSX SSR 在 < 4.12.18 版本上。ERROR：c.json 缺少 return、Express 中间件形状、所有 v3 时代移除的 API、未链式化的路由/子应用、Rails 控制器、zValidator 放置位置、RPC 中的 c.notFound/原始 Response、相对 URL 的 hc()、服务器应用的值导入、未 await 的 D1、运行时导出形状。WARN：Cookie 默认值、secureHeaders、不带脱敏的请求体日志记录、app.onError、子应用 notFound、c.executionCtx 真值检查、缺少 Bindings 泛型、路由后的 cors、中间件重叠、basePath 作为语句、尾部斜杠、hono/middleware 桶导入、新项目中使用 wrangler.toml、Lucia、@hono/sentry。NIT：缺少 satisfies ExportedHandler<Env>、手写 OpenAPI、缺少 observability.enabled。 |
c.env()hono/middlewareapp.head()c.notFoundprocess.envnode_compathono/cloudflare-workersserveStatic*httpOnly/secure/sameSite/pathsameSite:'None'secure:truenotFoundbasePathexport default app@hono/sentrylucia