用途
hono-ops 是一套围绕在 Cloudflare Workers 上使用 Hono 框架的开发技能资料，用于指导应用结构设计、中间件编排、错误处理、请求校验、RPC 客户端、流式响应以及测试等常见任务。资料中的模式提炼自一个生产级多租户 Worker（一个 Hono 应用、6 个以上挂载子应用、约 1350 个测试），并针对 Hono v4（2026）进行验证。
主要能力
- 应用组合：使用 Bindings（wrangler 提供的 env）与 Variables（每请求上下文，通过 c.set 写入）对应用做一次性类型标注；支持子应用挂载（app.route），一个 Worker 承载多个功能应用。
- 中间件纪律：Hono 中间件是洋葱模型，注册顺序即匹配顺序；资料强调“位置即安全边界”，并给出认证中间件先验证再构建请求上下文、不同认证模型的子应用挂载在会话边界之外的实践。
- 类型化错误边界：通过自定义 AppError 类与 app.onError 集中映射 HTTP 状态；跨作用域访问返回 404 而非 403；未匹配的 /api/* 返回 JSON 404，其余回退到 SPA。
- 边界校验：在 HTTP 边界进行校验，资料对比 zValidator 与手写断言的取舍。
- 测试：使用 app.request() / app.fetch() 在无服务器情况下运行真实应用；在 @cloudflare/vitest-pool-workers 下于 workerd 内使用真实 D1/KV/R2 绑定进行测试。
- 路由清单脚本：scripts/route-inventory.py 静态扫描 Hono TypeScript 源码树，列出每条路由、中间件注册与 app.route() 挂载及其 file:line，并提供 --check 做三种注册顺序检查（bypass、duplicate、shadowed）。
- Workers 特有陷阱：列出 fetch 的“Illegal invocation”、ASSETS.fetch 响应头不可变、caches 按 colo 而非全局、waitUntil 未注册会被取消、中间件注册顺序、wrangler dev 主机重写、可选密钥未设置等问题的原因与修复方式。
使用方式
资料以决策树引导：根据当前任务（应用结构、中间件、错误与校验、路由与请求、SPA 静态资源、Cron/队列、流式与实时、Durable Objects、OpenAPI、JSX SSR、运行时适配、RPC 客户端、测试、从零新建 Worker、审计现有应用）跳转到对应参考文档或脚本。
路由清单脚本用法示例：
# Inventory a Worker's HTTP surface (TSV: kind, method, path, file:line)
python skills/hono-ops/scripts/route-inventory.py src/
# JSON envelope for downstream tooling
python skills/hono-ops/scripts/route-inventory.py --json src/ | jq '.data[] | select(.kind=="mount")'
# Lint registration order: exit 10 = findings (each carries an `issue` field in --json)
python skills/hono-ops/scripts/route-inventory.py --check src/
退出码：0 表示干净，2 表示用法错误，3 表示路径不存在，10 表示 --check 发现问题。脚本基于正则，无需 TypeScript 编译器 API，可在任意检出上运行。
资料还提供起始资产：assets/worker-template.ts（带注释的组合根骨架，含类型化 env、安全头、认证中间件、bearer 子应用、404 拆分、onError、cron，并标注适配点）与 assets/vitest.config.template.ts（vitest-pool-workers 配置，含 D1 迁移到测试库、隔离、worktree 排除、兼容性日期固定）。
适用场景
- 在 Cloudflare Workers 上构建或重构 Hono 应用。
- 审计现有 Hono 应用的路由与中间件顺序。
- 从零新建 Worker。
- 需要类型化绑定、边界校验、RPC 客户端、流式/SSE/WebSocket、Durable Objects、OpenAPI 文档或 JSX SSR 的开发者。
- 需要将 Workers 应用迁移到 Node/Bun/Deno 的场景（见 references/runtime-adapters.md）。
限制
资料以 Workers 优先，Node/Bun/Deno 的差异与移植清单放在 references/runtime-adapters.md 中。路由清单脚本基于正则，不依赖 TypeScript 编译器 API。资料中未提供收费、价格或平台支持范围等信息。