用途:该技能面向已存在的 Vite + TanStack Router 项目,用于架构审查、实施指导与合规检查。触发场景包括路由目录结构、route-local 文件夹、loader、validateSearch、服务/查询层、自定义 hooks、Vite 插件配置、生成的路由树、env 与 alias 边界、共享嵌套目录组织等。
前置判断:先确认仓库是 Vite + TanStack Router 项目,例如 package.json 含 @tanstack/react-router 和 vite,或存在 vite.config.ts、src/routes/__root.tsx;若出现 @tanstack/react-start 或 app.config.ts,则返回 Start 边界说明,列出 createServerFn、useServerFn、Start 中间件 API、app.config.ts 等仅属 Start 的接口,而不套用 Vite 路由规则;不含 TanStack Router 的普通 Vite 项目不适用。
主要检查项(按门禁分组):1) 分层违规:路由或 hook 直接调用 fetch/axios、service 返回原始 Response、在 Vite 应用中出现 createServerFn 等均标记 BLOCKED,网络访问须经 services 层。2) 路由结构:拥有 UI/逻辑的页面必须使用文件夹路由,需有 -components/ 与 -hooks/,不允许 -functions/;Route 须为 export const Route;逻辑须抽到 -hooks/;带搜索参数须用 validateSearch(Zod 4 直接传 schema,Zod 3 用 @tanstack/zod-adapter 的 zodValidator);有 loader 无 pendingComponent 给 WARNING。3) 服务层:写操作须先经 Zod 校验;禁止 services/index.ts 桶导出;服务函数须显式返回类型;loader 预取若仍用 ensureQueryData、fetchQuery、prefetchQuery 在 TanStack Query 5.102+ 已弃用,建议 queryClient.query({ ...options, staleTime: 'static' }),标记 WARNING。4) Hooks:逻辑不得留在页面组件,hook 顺序为 State -> Global -> Query -> Handlers -> Memo -> Effect,须导出返回类型接口,文件名用 use-kebab-case.ts。5) 约定:文件名 kebab-case、使用 const 箭头函数、禁用 any 改用 unknown、显式返回类型、导入顺序 External -> @/ -> Relative -> Type、分组逻辑需韩语块注释、Zod 4 中用 z.email() 而非 z.string().email()。6) 执行模型:loader 对客户端可达,不得在其中放密钥、数据库、文件系统或特权 SDK;客户端可达代码不得访问非 VITE_ 环境变量;模块作用域避免仅浏览器 API。7) 平台配置:vite.config.ts 须含 tanstackRouter() 且位于 react() 之前;routeTree.gen.ts 视为生成产物不得手改;SSR/手动渲染场景下保持 src/router.tsx 显式并使用新 router 工厂(WARNING);Vite 8 基于 Oxc 与 Rolldown,plugin-react 6 声明 vite: ^8.0.0,新配置应使用 oxc、build.rolldownOptions 与 Rolldown 的 output.codeSplitting(WARNING)。
使用方式:先读 architecture-rules.md,再按触及面读取对应主题规则(conventions、routes、services、hooks、execution-model、platform、validation),涉及 API 漂移时参考带日期的官方文档快照,完成前运行 rules/validation.md 中的检查。流程为:确认项目类型、加载相关规则、对照门禁判定、对本地可逆问题自动修复(如补 validateSearch、把直连网络请求移入 services、补 pendingComponent/errorComponent、创建缺失的 -components//-hooks/、修正插件顺序与显式 env/alias 配置),对大规模重命名、整体路由重构、在 SPA 项目引入 SSR、大范围认证或 API 客户端重写等不做自动应用。每次请求只做一轮架构处理,最多两次验证-修复迭代,范围不扩大;技能文件夹本身改动时运行 bash scripts/validate-hyper-architecture-vite-skill.sh(需 bash 3.2+ 与 jq 1.6+),输出含 ok、行数与文件数的 JSON 摘要。
输出与语言:默认面向用户的交付物(报告、计划、文档、提交信息草稿、验证说明等)使用韩语,保留代码标识符、命令、路径、schema 键、JSON/YAML 字段、API 名、包名与引文原文,除非用户明确要求其他语言。
适用场景与限制:适用于既有 Vite + TanStack Router 项目的架构审查与小范围可逆修复;不适用于 TanStack Start 项目、无 TanStack Router 的普通 Vite 项目、纯文档总结,也禁止手改 routeTree.gen.ts、向 Vite 应用引入 Start 专有 API、在客户端可达代码中放置机密或特权访问。技能为自包含结构,含 architecture-rules.md、七个主题规则文件、官方参考、评估用例 assets/evals/hyper-architecture-vite-cases.jsonl 与校验脚本;具体收费、价格、平台支持与效果数据暂未提供。