vite-plugin-react-router-routecraft 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,9 +2,13 @@
 
 本文件记录 Routecraft 的面向用户变更。
 
+## 0.1.1
+
+- 完善 AI 使用指南与 Skill 对已安装插件版本文档的定位说明，明确文档缺失或版本不匹配时的处理方式。
+
 ## 0.1.0
 
-- 实现 Next.js App Router 风格目录约定到 React Router Data Mode `RouteObject[]` 的编译。
+- 实现 Routecraft 目录约定到 React Router Data Mode `RouteObject[]` 的编译。
 - 支持多路由组与布局、动态段、末尾 splat、可选 loader/action、错误边界、HydrateFallback 和 middleware。
 - 支持按模块逐属性选择 eager/lazy，生成 `typed-router.d.ts` 和类型化 `href` 辅助接口。
 - 提供目录扫描诊断、Vite HMR、可选开发期 DevTools、中文使用指南和可构建示例。

package/README.md

@@ -8,7 +8,7 @@
 
 ## 特性
 
-- Next.js App Router 风格的目录与 `page.tsx`、`layout.tsx` 约定，但仅实现可对应到 React Router Data Mode 的语义；
+- 以目录表达路由层级，并通过 `page.tsx`、`layout.tsx` 等 Routecraft 约定文件生成路由对象；
 - 路由组 `(group)`、私有目录 `_private`、`[param]` 动态段及末尾 `[...parts]` splat；
 - 多分支、多布局；不同 route group 可各自拥有 layout；
 - 组件、loader、action、错误边界与 hydration fallback 逐属性选择 eager/lazy；
@@ -21,6 +21,7 @@
 - [灵机一动：项目起点与原始设计方案](docs/design/routecraft-design.md)
 - [配置指南](docs/guides/configuration.md)
 - [目录路由约定](docs/guides/routing-conventions.md)
+- [AI 编码助手](docs/guides/ai-assistants.md)
 - [DevTools 指南](docs/guides/devtools.md)
 
 ## 试用示例
@@ -92,10 +93,10 @@ npm run pack:check
 ## 已知边界
 
 - `loading.tsx` 不会自动建立导航 loading UI；应用可用 React Router 的 `useNavigation()` 实现。
-- `hydrate-fallback.tsx` 只用于 React Router 初始 hydration fallback，不等于 Next.js `loading.tsx`。
+- `hydrate-fallback.tsx` 映射为 React Router 的 `HydrateFallback`，用于 hydration fallback；它不是应用内导航状态组件。
 - 根 `middleware.ts` 位于共同合成路由根，影响所有分支。middleware 不是服务端安全边界。
-- `[...parts]` 使用 React Router splat 的 `params["*"]` 字符串语义，不等价于 Next.js catch-all 字符串数组；`[[...parts]]` 不支持。
-- 不提供 Next.js Server Components、Server Actions、HTTP Route Handler、Parallel/Intercepting Routes、Next metadata 或 Framework Mode typegen。
+- `[...parts]` 映射为 React Router splat，参数通过 `params["*"]` 获取；`[[...parts]]` 不支持。
+- 不提供服务端组件、服务端操作、HTTP 请求处理器、并行/拦截式路由、框架级 metadata 或 Framework Mode typegen。
 - `useLoaderData()` 的业务返回值类型不做跨文件自动推导。
 
 详见[目录规则与语义边界](docs/guides/routing-conventions.md)。

package/dist/core/scanner.js

@@ -50,11 +50,11 @@ function scanChildren(directory, rootPath, diagnostics) {
             continue;
         }
         const childPath = join(directory, entry.name);
-        if (isUnsupportedNextDirectory(entry.name)) {
+        if (isUnsupportedRouteDirectory(entry.name)) {
             diagnostics.push({
-                code: "RC_UNSUPPORTED_NEXT_CONVENTION",
+                code: "RC_UNSUPPORTED_ROUTE_CONVENTION",
                 level: "warning",
-                message: `目录“${entry.name}”使用 Next.js Parallel/Intercepting Route 约定；Routecraft 不模拟该运行时语义。`,
+                message: `目录“${entry.name}”使用了 Routecraft 当前不支持的目录约定；该目录不会生成路由。`,
                 file: relative(rootPath, childPath).split("\\").join("/"),
             });
             continue;
@@ -89,7 +89,7 @@ function scanChildren(directory, rootPath, diagnostics) {
     }
     return children;
 }
-function isUnsupportedNextDirectory(name) {
+function isUnsupportedRouteDirectory(name) {
     return name.startsWith("@") || /^\(\.{1,3}\)/u.test(name);
 }
 function scanFiles(directory, rootPath, diagnostics) {
@@ -105,9 +105,9 @@ function scanFiles(directory, rootPath, diagnostics) {
             const baseName = entry.name.replace(/\.[^.]+$/u, "");
             if (unsupportedConventions.has(baseName)) {
                 diagnostics.push({
-                    code: "RC_UNSUPPORTED_NEXT_CONVENTION",
+                    code: "RC_UNSUPPORTED_ROUTE_CONVENTION",
                     level: "warning",
-                    message: `“${entry.name}”是 Next.js 风格约定文件；Routecraft 不模拟其运行时语义。`,
+                    message: `“${entry.name}”使用了 Routecraft 当前不支持的文件约定；该文件不会生成路由功能。`,
                     file: relative(rootPath, join(directory, entry.name)).split("\\").join("/"),
                 });
             }
@@ -116,9 +116,9 @@ function scanFiles(directory, rootPath, diagnostics) {
         const stem = entry.name.slice(0, -extension.length);
         if (unsupportedConventions.has(stem)) {
             diagnostics.push({
-                code: "RC_UNSUPPORTED_NEXT_CONVENTION",
+                code: "RC_UNSUPPORTED_ROUTE_CONVENTION",
                 level: "warning",
-                message: `“${entry.name}”是 Next.js 风格约定文件；Routecraft 不模拟其运行时语义。`,
+                message: `“${entry.name}”使用了 Routecraft 当前不支持的文件约定；该文件不会生成路由功能。`,
                 file: relative(rootPath, join(directory, entry.name)).split("\\").join("/"),
             });
             continue;

package/docs/architecture/index.md

@@ -76,7 +76,7 @@ Routecraft 为路由根产生共同的 pathless 根对象；`(auth)`、`(workspa
 
 - 有 error 时插件不把有错误的 IR 编译成“成功”快照；生产构建报错并终止。
 - 开发服务器将诊断写入 Vite 日志，DevTools 快照可呈现错误原因。
-- unsupported Next 命名按当前实现产生 warning，并跳过其 Next 专属语义。
+- 未注册的保留文件名和特殊目录按当前实现产生 warning，并跳过，不生成路由节点。
 - 修复错误后重新扫描，重新生成路由和声明文件。
 
 ## 开发期变更和刷新

package/docs/examples/complete-app.md

@@ -818,7 +818,7 @@ export default function HydrationFallback() {
 }
 ```
 
-该文件生成根结构路由的 `HydrateFallback`，只对应 React Router 支持的 hydration fallback，不等同 Next.js `loading.tsx` 或应用内导航 loading UI。
+该文件生成根结构路由的 `HydrateFallback`，用于 hydration fallback；应用内导航提示应由应用根据 React Router 导航状态自行呈现。
 
 `src/routes/not-found.tsx`：
 
@@ -836,7 +836,7 @@ export default function NotFoundPage() {
 }
 ```
 
-当前实现只接受**根目录** `not-found.tsx`，并将它生成 React Router `/*` catch-all 叶子；不是 Next.js 的 `not-found` 边界继承模型。
+当前实现只接受**根目录** `not-found.tsx`，并将它生成 React Router `/*` catch-all 叶子。
 
 ## 10. 文件属性到 Route Object 对照
 
@@ -952,4 +952,4 @@ npm --prefix examples/complete-app run dev
 - 登录 action 不建立 session、不验证账号；生产身份校验必须在服务端完成。
 - 项目数组在前端内存中，刷新后重置；生产项目数据应经由经过授权的服务端 API 访问。
 - Routecraft 当前生成 URL、参数和 Route ID 类型，不推断业务 loader/action 返回类型。
-- Data Mode 的浏览器 loader/action 是路由应用代码，不是 Next Server Action 或后端 HTTP endpoint。
+- Data Mode 的浏览器 loader/action 是路由应用代码，不是后端 HTTP endpoint；敏感操作应由服务端接口验证。

package/docs/guides/ai-assistants.md

@@ -0,0 +1,61 @@
+# 使用 AI 编码助手
+
+Routecraft 提供一个可安装的 Agent Skill，帮助 AI 编码助手在现有 Vite 项目中正确规划和维护 Routecraft 文件路由。Skill 是面向 AI 的操作指引，不会修改 Vite 插件运行时，也不会代替 React Router。
+
+## 安装 `routecraft-file-routing`
+
+先进入使用 Routecraft 的应用项目，再运行：
+
+```sh
+npx skills add alon-wu/vite-plugin-react-router-routecraft --skill routecraft-file-routing
+```
+
+安装工具会引导选择可用的编码助手和安装方式。默认按项目安装，便于团队共享；安装完成后请检查它新增或更新的 Skill 文件、助手目录链接和 `skills-lock.json`，只提交你希望团队共享的项目级文件。若要安装到个人环境供多个项目使用，可以加 `--global`。也可指定目标助手，例如：
+
+```sh
+npx skills add alon-wu/vite-plugin-react-router-routecraft \
+  --skill routecraft-file-routing \
+  --agent codex
+```
+
+`skills` 命令行工具及各 AI 助手的支持范围可能变化；请以安装时工具提供的选项为准。该命令从 GitHub 获取 Skill，不会安装或更新 `vite-plugin-react-router-routecraft` npm 依赖，也不会改写应用的 Vite 配置。
+
+## 更新和移除
+
+在应用项目目录中更新：
+
+```sh
+npx skills update routecraft-file-routing
+```
+
+移除项目级安装：
+
+```sh
+npx skills remove routecraft-file-routing
+```
+
+如果之前使用了全局安装，按工具提示选择全局范围或为对应目标助手移除。
+
+## 使用示例
+
+安装后，可以用自然语言请求 AI：
+
+- “在当前 Routecraft 项目里，为工作区增加一个项目详情页，沿用已有布局，并使用动态项目 ID。”
+- “检查这组页面的 loader 和 lazy 设置，只调整项目详情路由，不要改其他布局。”
+- “根据当前 Routecraft 版本核对这个路由目录是否符合约定；遇到不支持的目录或文件约定时先解释，不要模拟实现。”
+
+Skill 会要求助手先检查项目中 Routecraft 的实际版本、Vite 配置、路由目录和现有入口。插件完整指南随 npm 包发布，通常可在应用项目的 `node_modules/vite-plugin-react-router-routecraft/docs/guides/` 中查阅；若包管理器未提供这一直接路径，助手应先解析实际安装位置，而不是假设用户本地存在插件源码仓库。若完整指南不可用，Skill 会要求助手说明资料缺口，不把文档站最新版误称为安装版本文档。它不会替用户安装插件、覆盖现有路由架构或假设所有 React Router 项目都使用 Routecraft。
+
+## 不使用 Skill CLI 时
+
+可以从仓库的 `skills/routecraft-file-routing/` 目录手动安装 `SKILL.md` 及整个目录到所用 AI 助手支持的项目级或个人级 Skills 目录。各产品的目录和刷新方式不同，请查看相应助手的当前文档。
+
+## 相关资料
+
+- [安装与快速开始](/getting-started)
+- [目录与文件约定](/guides/routing-conventions)
+- [Lazy、loader 与 action](/guides/lazy-and-data)
+- [配置参考](/guides/configuration)
+- [类型声明与 `href()`](/guides/type-generation)
+- [Agent Skills 格式规范](https://agentskills.io/specification)
+- [Skills CLI 命令参考](https://github.com/vercel-labs/skills/blob/main/docs/commands.md)

package/docs/guides/configuration.md

@@ -61,7 +61,7 @@ Routecraft 本身设置 `enforce: "pre"`。应用仍需按 Vite/React 的正常
 
 - 路由根目录不存在、特殊文件导出缺失、配置语法无效或公开 URL 冲突：生成错误诊断；生产构建失败，不输出有效外观的部分路由表。
 - `route.config.ts` 只读取静态对象字面量，不执行配置模块。
-- Next 风格但不支持的 `loading.tsx`、`template.tsx`、`route.tsx` 等会产生警告；并不会悄悄获得 Next.js 运行语义。
+- `loading.tsx`、`template.tsx`、`route.tsx`、`default.tsx` 等未实现的约定名称会产生警告并被跳过，不会自动转换为其他功能。
 - 支持项和“不支持”边界以[目录规则表](/guides/routing-conventions#routecraft-当前实现规则)为准。
 
 ## 当前 peer 范围

package/docs/guides/routing-conventions.md

@@ -1,191 +1,131 @@
 # 目录与文件约定
 
-本文先说明 Next.js App Router 本身的约定，再划出 Routecraft 实际借鉴的组织方式，最后按 Routecraft 的扫描器和编译器规则，逐项说明目录如何生成 React Router Data Mode 路由对象。三个层次不应混为一谈。
+Routecraft 扫描 Vite 项目中配置的路由根目录，将约定文件编译为 React Router Data Mode 的路由对象树。本文说明 Routecraft 实际识别的目录、文件、校验规则及生成结果；未列出的文件不会被当作路由约定处理。
 
-## 1. Next.js App Router 的目录模型
+## 路由根目录与扫描范围
 
-Next.js App Router 以 `app/` 下的目录段构成嵌套路由。页面入口 `page` 使该段可呈现页面；`layout` 在段及其子路由之间建立持续布局；特殊文件为 loading、error、not-found、metadata、HTTP route 等提供 Next 框架级语义。
+- `routesDir` 是路由文件扫描根目录，默认值为 `src/routes`，可在 Vite 插件配置中改为其他相对或绝对路径。
+- 根目录自身代表共同路由根；它的约定文件作用于所有路由分支。
+- 普通子目录按路径层级递归扫描。以下划线 `_` 或点 `.` 开头的目录及其全部后代会被跳过。
+- 未包含 Routecraft 约定文件、也没有包含有效路由后代的普通目录不会生成路由节点。
+- 扫描仅识别下表所列的 `.ts` / `.tsx` 文件；数据模块、中间件和目录配置只接受 `.ts`。
+- 扫描结果按目录名排序，以确保生成结果稳定。`.d.ts` 文件（包括自动生成的 `typed-router.d.ts`）会被忽略。
 
-```text
-app/
-├── layout.tsx                   # 根布局：Next 文档壳、html/body 等
-├── page.tsx                     # /
-├── dashboard/
-│   ├── layout.tsx               # /dashboard 子树共享布局
-│   ├── page.tsx                 # /dashboard
-│   └── projects/
-│       └── [projectId]/
-│           └── page.tsx         # /dashboard/projects/:projectId
-└── (marketing)/
-    └── about/
-        └── page.tsx             # /about；组名不出现在 URL
-```
-
-### 1.1 页面、布局与嵌套
-
-- **目录段**组织 URL 层级；目录名本身不是充分的页面声明。
-- **`page.tsx`** 使所在路由段有页面入口。
-- **`layout.tsx`** 按目录嵌套包围页面及后代；Next.js 根布局还有 HTML 文档职责，普通布局可保留跨导航状态。
-- **`template.tsx`** 与 layout 的重新挂载语义不同。
-- **`loading.tsx`**、**`error.tsx`** 和 **`not-found.tsx`** 在 Next.js 中是框架识别的边界文件，不只是普通 React 组件。
-
-### 1.2 路由组、私有目录和 URL 段
+## 目录段规则
 
-- `(group)` 是 route group，用于组织路由、分组布局等，组名不进入 URL。不同组如果形成相同 URL，仍然冲突。
-- `_private` 是 private folder，目录及其子树不参与路由。
-- `[slug]` 是动态段。
-- `[...slug]` 是 catch-all；`[[...slug]]` 是 optional catch-all。
-- `@slot` 是 Parallel Routes slot，`(.)`、`(..)`、`(...)` 等用于 Intercepting Routes。这些语法需要 Next.js 的并行/拦截渲染运行时，不是普通 URL 段别名。
+| 目录名 | Routecraft 解释 | 生成的路径 |
+| --- | --- | --- |
+| `workspace/` | 静态路径段 | `workspace` |
+| `[projectId]/` | 动态路径段；参数名须为合法 TypeScript 标识符 | `:projectId` |
+| `[...parts]/` | 末尾通配路径段；参数名须为合法 TypeScript 标识符 | `*` |
+| `(account)/` | 无 URL 路径的结构分组；名称仅用于组织目录 | 不生成 `path` |
+| `_private/`、`.hidden/` | 私有或隐藏实现目录；整个子树跳过 | 不生成路由 |
 
-### 1.3 Next.js 服务端与元数据能力
+### 静态段
 
-App Router 中的 `route.ts` 是 HTTP Route Handler；Server Components、Server Actions、`generateMetadata`/metadata 文件、`loading` 与 `error` 边界等由 Next.js 框架编译和运行。它们不是能仅凭目录结构转换成一个通用客户端路由对象的约定。
+静态目录名只允许 ASCII 字母、数字、下划线和连字符，即 `A-Z`、`a-z`、`0-9`、`_`、`-`。例如 `sign-in`、`workspace_v2` 合法；空格、点号和其他字符不符合当前校验规则。
 
-参考：Next.js 官方[项目结构](https://nextjs.org/docs/app/getting-started/project-structure)、[页面与布局](https://nextjs.org/docs/app/getting-started/layouts-and-pages)、[动态路由段](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes)。
+### 动态段
 
-## 2. Routecraft 借鉴什么，不移植什么
+以一对方括号包裹参数名，例如 `[projectId]`。参数名遵循 TypeScript 标识符格式。Routecraft 将其转换为 React Router 动态段；实际匹配参数由 React Router 提供给路由组件和数据函数。
 
-### 2.1 借鉴并重新定义为 Routecraft 规则
+### 通配段
 
-| 组织想法 | Routecraft 中的落地定义 |
-| --- | --- |
-| URL 段按目录嵌套 | 普通目录段拼接成 React Router `path`。 |
-| `page` 表示页面入口 | `page.tsx`/`page.ts` 生成 React Router index route，页面组件为默认导出。 |
-| 目录布局 | `layout.tsx`/`layout.ts` 附着在对应目录结构路由的 `Component`；布局组件必须渲染 `<Outlet />`。 |
-| 无 URL 的路由分组 | `(group)` 编译为无 `path` 的 pathless 父路由；组名保留在 ID/来源信息，但不进入 URL。 |
-| 私有实现子树 | `_private` 开头的子目录整棵跳过；点开头目录也跳过。 |
-| 方括号动态段 | `[projectId]` 编译为 `:projectId`。 |
-| 错误边界/fallback 模块 | `error.tsx` 映射 `ErrorBoundary`；`hydrate-fallback.tsx` 映射 `HydrateFallback`。 |
-| 路由数据模块 | 可选 `loader.ts`、`action.ts` 映射对应路由对象属性，实际函数契约由 React Router 规定。 |
+`[...parts]` 将生成 React Router 的 `*` 路径段，读取值时使用 `params["*"]`。该目录必须是路由路径的最后一段，不能包含有效路由后代。`[[...parts]]` 不属于支持的目录语法。
 
-### 2.2 不做语义仿真的 Next 功能
+### 结构分组
 
-| Next.js 特性 | Routecraft 处理 |
-| --- | --- |
-| 根布局输出 `<html>`/`<body>` | 不实现；文档壳仍由 Vite `index.html` 和 React 挂载入口负责。 |
-| `loading.tsx` | 不支持；不推断自动 Suspense/loading UI。应用可使用 React Router 导航状态 API 自行呈现导航提示。 |
-| `template.tsx` | 不支持。 |
-| `route.ts` Route Handler | 不支持；Routecraft 不提供服务端 HTTP 处理器。 |
-| Parallel/Intercepting Routes（`@slot`、`(.)` 等） | 不模拟多槽渲染或拦截路由；当前实现会跳过相关目录并产生警告。 |
-| Server Components/Server Actions | 不支持；不是 Vite + React Router Data Mode 的等价路由字段。 |
-| Next metadata、静态参数生成等 | 不支持；不生成 metadata 或 Next 构建工作流。 |
-| Optional catch-all `[[...parts]]` | 不支持。 |
+`(account)` 这样的目录会生成一个不含 `path` 的父路由节点。组名不出现在 URL 中，但节点可保留父子关系、目录级布局和中间件作用范围。不同分组若生成相同的可访问 URL，仍会发生路由冲突；分组名不会使 URL 唯一。
 
-## 3. Routecraft 当前实现规则
+### 私有和隐藏目录
 
-### 3.1 文件与目录表
+以下划线或点开头的目录会连同其后代一起排除在扫描之外。可用它们存放不会参与路由生成的实现文件。
 
-| 项目 | 匹配规则 | 扫描/校验要求 | 路由对象结果 |
-| --- | --- | --- | --- |
-| 路由根目录 | `routesDir` | 必须已存在且是目录。 | 所有扫描结果合入共同根路由对象。 |
-| 页面 | `page.tsx` 或 `page.ts` | 必须有默认导出。 | 同目录结构路由的 `children` 中新增 `{ index: true, ... }`。 |
-| 布局 | `layout.tsx` 或 `layout.ts` | 必须有默认导出；应渲染 `<Outlet />`。 | 当前目录结构路由的 `Component`。 |
-| route group | `(name)/` | 名称仅允许 ASCII 字母、数字、`_`、`-`。 | `{ id, children }` 无 `path`；保留父子与布局边界。 |
-| 私有目录 | `_name/` | 整棵子树不扫描。 | 不生成节点。 |
-| 隐藏目录 | `.name/` | 整棵子树不扫描。 | 不生成节点。 |
-| 静态段 | `workspace/`、`sign-in/` | 仅 ASCII 字母、数字、`_`、`-`。 | `{ path: "workspace", children: [...] }`。 |
-| 动态段 | `[projectId]/` | 参数名须是合法 TS 标识符。 | `{ path: ":projectId", children: [...] }`；React Router 将其放入匹配参数。 |
-| splat 段 | `[...parts]/` | 参数名须合法；必须是路由路径末尾，不能有后代段。 | `{ path: "*", children: [...] }`；匹配值按 React Router 的 `params["*"]` 字符串读取。 |
-| 错误边界 | `error.tsx`/`.ts` | 默认导出组件。 | 当前结构路由 `ErrorBoundary`。 |
-| Hydration fallback | `hydrate-fallback.tsx`/`.ts` | 默认导出组件。 | 当前结构路由 `HydrateFallback`。不是导航 loading 状态组件。 |
-| 404 页面 | 仅路由根 `not-found.tsx`/`.ts` | 默认导出组件；放在非根目录是错误。 | 根共同路由的 `*` catch-all 叶子；不是 Next `not-found` 冒泡模型。 |
-| 页面 loader/action | 同目录 `loader.ts`、`action.ts` | 分别需命名导出 `loader`/`action`；同目录必须有 `page`。 | 页面 index route 对应的属性。缺文件就省略该属性。 |
-| 布局 loader/action | 同目录 `layout.loader.ts`、`layout.action.ts` | 需要同目录 layout；分别命名导出 `loader`/`action`。 | 目录结构路由对应的属性。 |
-| middleware | `middleware.ts` | 必须命名导出 `middleware`；静态导入。 | 当前结构路由的 `middleware: [middleware]`；根文件放共同根。 |
-| 加载配置 | `route.config.ts` | 与 `page`、`layout`、`error`、`hydrate-fallback` 或根 `not-found` 共置。只能用允许的静态配置对象。 | 影响本目录模块的独立 eager/lazy 决策，不生成 route 属性。 |
-| 普通 colocated 文件 | 其他名称，如 `components.tsx`、`styles.css` | 不属于特殊文件约定。 | 不单独生成路由。 |
+## 约定文件与路由对象映射
 
-仅扫描 `.ts`/`.tsx` 约定文件；数据、middleware 与配置模块必须是 `.ts`，组件模块可用 `.ts` 或 `.tsx`。
+Routecraft 会将同一目录内的文件按职责放到对应的路由节点上。页面是当前路径的索引子路由；布局、边界组件和中间件附着在目录对应的结构路由上。
 
-### 3.2 命名约束与冲突
+| 文件 | 导出要求 | 对应结果 |
+| --- | --- | --- |
+| `page.tsx` / `page.ts` | 默认导出页面组件 | 在当前目录路径下生成 `{ index: true, ... }` 子路由，并将组件映射到 `Component` 或 `lazy`。 |
+| `layout.tsx` / `layout.ts` | 默认导出布局组件 | 映射为当前目录结构路由的 `Component` 或 `lazy`。布局需要渲染 `<Outlet />` 才能呈现子路由。 |
+| `error.tsx` / `error.ts` | 默认导出错误边界组件 | 映射为当前结构路由的 `ErrorBoundary` 或 `lazy`。 |
+| `hydrate-fallback.tsx` / `hydrate-fallback.ts` | 默认导出组件 | 映射为当前结构路由的 `HydrateFallback` 或 `lazy`，用于 hydration fallback。 |
+| 根目录 `not-found.tsx` / `not-found.ts` | 默认导出组件；仅允许置于路由根 | 在共同路由根下生成 `path: "*"` 的通配叶子路由。 |
+| `loader.ts` | 命名导出 `loader`；需同目录页面 | 映射为页面索引路由的 `loader`。 |
+| `action.ts` | 命名导出 `action`；需同目录页面 | 映射为页面索引路由的 `action`。 |
+| `layout.loader.ts` | 命名导出 `loader`；需同目录布局 | 映射为目录结构路由的 `loader`。 |
+| `layout.action.ts` | 命名导出 `action`；需同目录布局 | 映射为目录结构路由的 `action`。 |
+| `middleware.ts` | 命名导出 `middleware` | 映射为当前结构路由的 `middleware` 数组，始终静态导入。 |
+| `route.config.ts` | 默认导出静态配置对象 | 调整当前目录受支持模块属性的 eager/lazy 方式；本身不生成路由属性。 |
 
-- 静态段只接受 `A-Z`、`a-z`、`0-9`、`_`、`-`。空格、点号、Unicode 字母等不符合当前扫描器验证规则。
-- 动态段 `[id]` 内是 TS 标识符；动态参数重复名称会产生诊断。
-- 动态段名称不用于区分 URL 冲突：`[projectId]` 和 `[slug]` 在相同位置属于同一 URL 形状。
-- `(public)/about/page.tsx` 与 `about/page.tsx` 等若产生相同的可访问 URL，会发生冲突；组名不能防止冲突。
-- `[...parts]` 有后代目录时会失败；可选 catch-all `[[...parts]]` 不支持。
-- 根 `page.tsx` 生成 `/` index 页面；其他页面都生成其父路径的 index route。
-- 文件夹只有普通文件、没有路由约定文件且没有路由后代时，不生成节点。
+若约定组件文件或数据模块缺少必需导出、数据模块没有对应页面/布局、配置文件放置位置错误，Routecraft 会输出错误诊断。约定文件不能在同一目录重复出现 `.ts` 和 `.tsx` 两种版本。
 
-### 3.3 不支持文件警告
+### 页面、布局与多分支
 
-当前扫描器会对 Next 命名 `loading`、`template`、`route`、`default` 的 `.ts`/`.tsx` 文件显示“未模拟 Next 语义”的 warning。`@slot` 与以 `(.)`、`(..)`、`(...)` 开头的目录同样跳过并显示 warning。不要仅因文件名相似，就假设 Next.js 行为存在。
-
-## 4. 从目录到 React Router 对象：逐级映射
-
-React Router Data Mode 接收 `createBrowserRouter(routes)` 的 Route Object 树；path/index/children 表达匹配与嵌套，布局组件通过 `<Outlet />` 呈现子节点。索引路由是无 path 的 `{ index: true }` 子路由。见 React Router 官方[路由配置](https://reactrouter.com/start/data/routing)。
-
-例如：
+页面始终编译为其目录路径下的索引子路由。因此一个路径段可以同时拥有 `layout`、`page` 和更深层的路由后代。例如：
 
 ```text
 src/routes/
 ├── (auth)/
 │   └── auth/
 │       ├── layout.tsx
-│       └── sign-in/
-│           ├── page.tsx
-│           ├── loader.ts
-│           └── route.config.ts
+│       ├── sign-in/
+│       │   └── page.tsx
+│       └── sign-up/
+│           └── page.tsx
 └── (workspace)/
     └── workspace/
         ├── layout.tsx
+        ├── page.tsx
         └── projects/
             └── [projectId]/
                 └── page.tsx
 ```
 
-会形成如下逻辑树（省略自动生成 ID 和模块引用）：
-
-```ts
-[
-  {
-    // (auth) 是无 URL path 的结构父节点
-    children: [
-      {
-        path: "auth",
-        Component: AuthLayout,
-        children: [
-          {
-            path: "sign-in",
-            children: [
-              {
-                index: true,
-                loader: signInLoader,
-                lazy: { Component: /* 页面组件导入 */ },
-              },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-  {
-    // 第二个 route group 不与认证分支共用布局
-    children: [
-      {
-        path: "workspace",
-        Component: WorkspaceLayout,
-        children: [
-          {
-            path: "projects",
-            children: [
-              {
-                path: ":projectId",
-                children: [{ index: true, lazy: { Component: /* 页面组件导入 */ } }],
-              },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-]
+上例形成两个共享共同路由根的分支：认证分支由 `auth/layout.tsx` 包裹，工作区分支由 `workspace/layout.tsx` 包裹；各分支仍由应用创建的同一个 React Router 实例管理。`(auth)` 和 `(workspace)` 仅用于组织结构，不进入公开 URL。示意映射如下：
+
+```text
+共同路由根
+├── pathless group
+│   └── path: "auth"        Component: AuthLayout
+│       ├── path: "sign-in"  └── index: true, Component: SignIn
+│       └── path: "sign-up"  └── index: true, Component: SignUp
+└── pathless group
+    └── path: "workspace"  Component: WorkspaceLayout
+        ├── index: true, Component: WorkspaceHome
+        └── path: "projects"
+            └── path: ":projectId"
+                └── index: true, Component: ProjectDetails
 ```
 
-它代表两个不同布局分支，公开路径分别是 `/auth/sign-in` 与 `/workspace/projects/:projectId`。`(auth)`、`(workspace)` 不进入 URL。`lazy` 的具体规则见 [Lazy、loader 与 action](/guides/lazy-and-data)。
+对应的 URL 分别为 `/auth/sign-in`、`/auth/sign-up`、`/workspace` 和 `/workspace/projects/:projectId`。此图省略自动生成的 `id`、模块导入和数据属性；完整对象形状取决于每个模块的 lazy 配置。
+
+## 可选数据模块与逐属性懒加载
+
+`loader.ts`、`action.ts`、`layout.loader.ts` 和 `layout.action.ts` 都是可选的。文件不存在时，生成对象中不会出现对应属性，也不会创建空函数或占位导入。页面组件、布局、数据函数、错误边界和 hydration fallback 可分别选择 eager 或 lazy。
+
+- 插件选项 `defaultLazy`（默认 `true`）为未被目录配置覆盖的模块属性提供默认值。
+- 同目录 `route.config.ts` 的 `lazy` 对象可用 `true` / `false` 分别覆盖 `layout`、`layoutLoader`、`layoutAction`、`page`、`loader`、`action`、`error`、`hydrateFallback`。
+- 目录配置只影响该目录中实际存在的相应文件；不存在的模块不会产生属性。
+- `middleware.ts` 始终静态导入，不接受 lazy 配置。
+- 路由匹配需要的 `id`、`path`、`index` 和 `children` 保持在路由对象静态部分。
+
+配置只允许默认导出静态对象字面量，`lazy` 的每项必须是直接的布尔字面量；只允许 `import type`，不执行配置文件。完整例子和字段行为见 [Lazy、loader 与 action](/guides/lazy-and-data)。
+
+## 冲突与错误规则
+
+- 同一 URL 形状只能对应一条可访问路由。`users/[id]` 与 `users/[slug]` 会被视为相同路径形状并产生错误；动态参数名不同不构成区分。
+- 路由组不进入 URL，因此不同组下相同的 URL 也会冲突。
+- 同一路径中不能重复使用同一个动态参数名。
+- 通配段必须处于路径末尾。
+- `not-found` 约定文件仅允许放在路由根。
+- 不识别的普通文件不会创建路由。`loading`、`template`、`route`、`default` 等保留名称的文件，以及 `@` 或以 `(.)`、`(..)`、`(...)` 开头的目录，会作为不支持的约定跳过并产生警告；不会被转换成其他功能。
+
+有错误诊断时，插件不会将存在错误的部分结果伪装为有效路由表；请先处理 DevTools 或构建输出中的诊断。
 
-## 5. 当前实现边界摘要
+## 生成结果由谁负责
 
-Routecraft 输出数据路由配置；匹配、loader/action 调用、中间件调度和渲染由 React Router 执行。Routecraft 不实现 Framework Mode 路由模块导入/类型生成契约、不推断业务 loader 数据返回类型，也不把浏览器 middleware 当成可信服务端授权边界。
+Routecraft 负责扫描、校验并生成 React Router Data Mode 可消费的路由对象；URL 匹配、数据函数调用、中间件调度和 UI 渲染由 React Router 执行。`loader`/`action` 的业务返回值不会被跨文件推导为组件专属类型；Data Mode 中的业务代码也不因此获得服务端安全边界。
 
-如要查看逐文件的大型项目和实际代码，请读[项目管理台完整示例](/examples/complete-app)；如要查看扫描器、IR 和生成器的代码关系，请读[架构设计](/architecture/)。
+查看 [完整项目示例](/examples/complete-app) 了解一组端到端目录和业务代码；查看[架构设计](/architecture/)了解扫描器、路由中间表示与生成器的实现关系。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-react-router-routecraft",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "面向 React Router Data Mode 的 Vite 文件路由插件",
   "type": "module",
   "repository": {