roninforge-hono

针对 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 会生成：

v3 -> v4 移除的 API

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）
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）

Express / Koa / Fastify 的泄漏（最严重的一类）

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（使用 hono/cors）
supertest 用于测试（使用 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）

TypeScript / RPC 推断错误

new Hono() 不带 Bindings / Variables 泛型（c.env 是 {}）
路由定义为语句（先 app.get(...) 再 app.post(...)）—— 丢失 RPC 类型
子应用 app.route() 调用作为语句—— 同样规则
Rails 风格的控制器 传递 Context（丢失路径参数推断，违反 Hono 最佳实践）
app.use('/path', zValidator(...)) 而不是作为路由参数（TS 错误：'json' 不能赋给 'never'）
在 RPC 消费的路由中使用 c.notFound()（无法在客户端进行类型化）
new Response(JSON.stringify(...)) 在 RPC 路由中（客户端看到 unknown）
hc<AppType>('/') 相对 URL（调用 $url() 时抛出异常）
将服务器应用的值导入到客户端 bundle（会拖入 drizzle-orm、fs、原生依赖——RPC 包体积膨胀的头号陷阱）
中间件不带 createMiddleware<Env>（Variables 类型不传播）

Cloudflare Workers 的陷阱

在 Workers 代码中使用 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-forget
真值检查 if (c.executionCtx)（在 Bun 和 Next.js App Router 上，getter 会抛出异常）
未 await 的 D1 .run() / .first() / .all()（worker 终止时插入操作被取消）
WebSocket 升级未通过 Durable Object 转发（状态丢失）

安全/生产环境缺口

缺少 secureHeaders() 中间件
在基于 Cookie 认证的突变上缺少 csrf()
cors({ origin: '*', credentials: true })（浏览器静默丢弃；AJAX 失败）
POST / PUT 路由上缺少 bodyLimit()，且 hono 必须锁定在 >= 4.9.7 以修复 CVE-2025-59139
Cookie 没有 httpOnly / secure / sameSite / path
sameSite: 'None' 没有 secure: true（静默丢弃）
请求体记录中间件不带脱敏（密码/令牌/PII 泄漏）
静态 GET 上没有 etag() / cache()
硬编码的 JWT 密钥（通过 bundle 泄漏）
在内存中构建大型 JSON 而不是使用 streamText（Workers 128MB 限制）

路由/结构错误

子应用 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）
手写 OpenAPI 而不使用 @hono/zod-openapi
cors() 挂载在路由之后（永远不会匹配）

为什么使用此插件（与现有的社区 Hono 规则对比）

少数的 Hono 规则已经存在于 cursor.directory 和 awesome-cursorrules（PR #152）：它们涵盖了 c.json() 返回、zValidator + Zod、Workers 的 c.env、链式路由的 RPC、以及 Workers 的 app.fetch 导出。它们有三个结构性问题，此插件已修复：

它们没有涵盖 v3 -> v4 移除的 API。 LLM 继续生成 c.jsonT、c.stream、c.env()、c.req.cookie、app.showRoutes、hono/middleware 桶导入和 app.handleEvent——这些都在 v4.0.0（2024-02）中移除了。现有规则静默允许它们。
它们遗漏了 Express 泄漏类。 (req, res, next)、(err, req, res, next)、npm 的 cors、app.use(express.json())、supertest、c.json 缺少 return——这些在 LLM 生成的 Hono 代码中持续出现。现有规则把它们当作一次性问题处理。
它们遗漏了安全默认值和 CVE 固定版本。 没有强制 secureHeaders() / csrf()；没有提到 bodyLimit 的 CVE-2025-59139（在 v4.9.7 修复）；没有解决 RPC 客户端陷阱（相对 URL、值导入泄漏、c.notFound 类型化）。

此插件提供：

10 个 MDC 规则，带有适当的 globs，使得路由/RPC 检查在 src/routes/** 上触发，Workers 检查在 wrangler.{toml,jsonc} + Worker 入口上触发，安全检查在中间件文件上触发等。
59 个文档化的反模式，带有错误/正确 TypeScript 对比对
5 个技能：/hono-new-route、/hono-rpc-setup、/hono-cloudflare-workers-setup、/hono-migrate-to-v4、/hono-validate
1 个审查代理，带有严重性分组（CRITICAL / ERROR / WARN / NIT）和按文件检查
2 个测试项目：correct-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 版本的全局安装路径。

最受欢迎

roninforge-hono

roninforge-hono

问题

v3 -> v4 移除的 API

Express / Koa / Fastify 的泄漏（最严重的一类）

TypeScript / RPC 推断错误

Cloudflare Workers 的陷阱

安全/生产环境缺口

路由/结构错误

运行时静默错误

较小但实际存在的问题

为什么使用此插件（与现有的社区 Hono 规则对比）

安装

包含的内容

规则（10 个文件）