目录约定
ktr 的核心设计：目录即路由，模板、mock、样式、静态资源全部按固定位置自动发现
本页讲 ktr 的核心设计——约定大于配置：文件放到约定位置就自动生效，没有注册表要写、没有路由要配。
完整目录树
一个典型的 Karin 插件项目，ktr 相关的目录结构如下：
插件项目根目录/
├── src/ # 插件逻辑（karin 指令等）
│ ├── index.ts
│ └── apps/
│ └── card.ts
├── ktr/
│ ├── template/ # 模板根目录：目录即路由
│ │ ├── style.css # Tailwind 入口（缺失时首次启动自动补）
│ │ ├── hello/ # 板块（模板分组）
│ │ │ └── card/ # 模板 → 路由 hello/card
│ │ │ ├── index.tsx # 模板组件，默认导出 defineTemplate(...)
│ │ │ ├── mock.ts # TS mock（固定文件名，面板只读）
│ │ │ ├── components/ # 子组件与逻辑（可选，不参与路由）
│ │ │ │ ├── badge.tsx
│ │ │ │ └── use-status.ts
│ │ │ └── data/ # JSON mock（面板可编辑）
│ │ │ ├── default.json
│ │ │ ├── empty.json
│ │ │ └── captured.json # 真实渲染自动捕获的数据
│ │ ├── user/
│ │ │ └── profile/ # 第二个模板 → 路由 user/profile
│ │ │ ├── index.tsx
│ │ │ └── mock.ts
│ │ └── _shared/ # 下划线开头：共享代码，不扫成路由
│ │ ├── components/
│ │ │ └── avatar.tsx
│ │ └── format.ts
│ └── public/ # 静态资源（图片、字体）
│ ├── logo.png
│ └── fonts/
│ └── rubik-bold.woff2
├── .ktr/ # 框架生成的缓存（勿编辑、勿提交、勿 import）
│ ├── template-registry.ts
│ ├── mock-registry.ts
│ └── registry-types.d.ts
├── karin.template.ts # 配置文件（可选，只配工具链自身行为）
├── package.json
└── vite.config.ts各位置的约定说明见下表：
| 位置 | 说明 |
|---|---|
ktr/template/**/index.tsx | 模板组件，默认导出 defineTemplate(...)；目录路径即路由，深度不限（hello/card、demo/nested/deep 均可） |
.../mock.ts | 类型安全的 TS mock，具名导出，面板中只读，见 mock 数据 |
.../data/*.json | JSON mock，面板可筛选、编辑、保存；文件名即数据名 |
.../data/captured.json | 真实渲染时自动写入的本次数据（滚动覆盖单文件），面板收到推送自动刷新并选中 |
.../components/ | 模板内部子组件和逻辑文件的固定目录（可选），不会被扫成路由 |
ktr/template/style.css | 所有模板共用的 Tailwind 入口，固定三行，见 样式与主题 |
ktr/public/ | 静态资源：dev 时按根路径引用（/logo.png），构建时复制到产物 assets/ |
三条硬规则：
- 裸写
.tsx不注册——ktr/template/hello/card.tsx不是模板，必须是目录下的index.tsx；目录深度不限，<板块>/<模板>两级只是典型结构（官方示例里就有三级路由demo/nested/deep）。 _开头的目录不扫描——跨模板的共享代码放ktr/template/_shared/这类目录。- 组件根元素不要写
id="container"——截图边界由框架统一提供；圆角截图给根元素加rounded-*，需要裁剪内容时配overflow-hidden。
.ktr/ 是什么
ktr sync、ktr dev 和构建插件会扫描 ktr/template/，把三个文件写进项目根的 .ktr/（类似 Next.js 的 .next/）：
template-registry.ts：路由 → 组件的注册表。mock-registry.ts：TS mock 导出 + JSON 文件清单。registry-types.d.ts：模块增强声明，给renderImage注入逐路由精确类型。
.ktr/ 是框架产物：不要手动编辑、不要提交、源码不要 import 它。运行时加载用 @karinjs/template-react 的 loadTemplateRegistry() / loadMockRegistry()，类型由模块增强自动提供。
想换目录位置
karin.template.ts 的 dir 配置可改模板目录、静态资源目录和 CSS 入口；.ktr/ 位置、mock 与模板共置这两条固定不可改。全部配置项见 配置与 CLI。