feat: 初始化 Astryx React 应用模板HEADmain

基于 Vite 8、React 19、TypeScript 6、React Router 7 和 Astryx 0.7.2
搭建完整的中文应用起始模板，包含可直接运行的应用外壳与示例页面。

主要变更：
- 使用 Astryx 构建 AppShell、顶部导航、可折叠侧边栏和响应式移动端抽屉。
- 接入 Astryx neutral 主题与中文语言包，支持明暗主题切换并持久化偏好。
- 新增概览、组件、图标、关于和 404 页面，统一使用共享页面框架。
- 将页面路由、侧边栏名称、图标和active状态合并到 app-routes.tsx，
  路由与导航由同一份配置生成，避免重复维护。
- 新增根目录 app.config.ts，可在 browser/history 与 hash 路由模式之间切换；
  当前保留 hash 模式配置。
- 组件页提供 14 个可交互组合场景，覆盖全部 173 个 Astryx 组件，
  包含按钮、表单、表格、导航、聊天、对话框、菜单、命令面板和 Toast 等。
- 新增图标页面，支持浏览 29 个 Astryx 语义图标和 1903 个 Lucide 图标，
  提供搜索、分页、图标集切换和点击复制用法。
- 对组件页和图标页实施路由级懒加载，并按 React、React Router 拆分 vendor
  chunk，降低首屏入口体积并改善长期缓存。
- 接入 React Router 的 LinkProvider，保证 Astryx 链接、导航和按钮在两种
  路由模式下均使用客户端导航。
- 配置 pnpm 供应链策略例外与依赖构建许可，锁定可以正常安装的依赖版本。
- 补充 README，记录项目结构、脚本、组件展厅、图标页、路由模式与构建策略。

验证结果：
- pnpm build 通过
- pnpm lint 0 warnings
- browser 与 hash 两种路由模式的页面和侧边栏导航均已验证

1 files changed, 172 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5193384
--- /dev/null
+++ b/README.md
@@ -0,0 +1,172 @@
+# Astryx Starter
+
+A Vite + React + React Router + Astryx starter with a working app shell, client-side routing, light/dark theming, a Chinese UI, an interactive component gallery, and an icon browser.
+
+## Stack
+
+| Tool | Version |
+| --- | --- |
+| [Vite](https://vite.dev) | 8.x |
+| [React](https://react.dev) | 19.x |
+| [React Router](https://reactrouter.com) | 7.x |
+| [Astryx](https://astryx.atmeta.com) | 0.7.2 |
+| TypeScript | 6.0 |
+| Oxlint | 1.x |
+| pnpm | 11.x |
+
+Astryx requires React 19 or later. It ships pre-built CSS, so this project does **not** need a StyleX, PostCSS, or Babel plugin.
+
+## Requirements
+
+- Node.js 20.19 or newer
+- pnpm 11 or newer
+
+## Getting started
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Vite prints the local URL. Open it in a browser and edit any file under `src/`; HMR updates the page immediately.
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `pnpm dev` | Start the Vite dev server |
+| `pnpm build` | Type-check with TypeScript and build for production |
+| `pnpm lint` | Run Oxlint |
+| `pnpm preview` | Preview the production build locally |
+| `pnpm astryx <command>` | Run the project-local Astryx CLI |
+
+Useful Astryx commands:
+
+```bash
+pnpm astryx component Button      # full props, examples, and theming
+pnpm astryx component --list      # list every component
+pnpm astryx template --list       # browse page and block templates
+pnpm astryx docs theme            # theme reference
+```
+
+## Project structure
+
+```text
+app.config.ts        router mode (browser or hash)
+src/
+  app-routes.tsx     routes + sidebar labels/icons (single source of truth)
+  components/
+    AppLayout.tsx    app shell, top nav, side nav, route scroll reset
+    ComponentsRoute.tsx  lazy route for the component gallery
+    IconsRoute.tsx   lazy route for the icon browser
+    Page.tsx         shared page frame and page header
+  data/
+    astryxComponents.ts  all 173 components and their groups
+  demos/
+    ActionsDemo.tsx …    interactive examples by category
+  pages/
+    HomePage.tsx
+    ComponentsPage.tsx
+    IconsPage.tsx
+    AboutPage.tsx
+    NotFoundPage.tsx
+  theme/
+    ThemeMode.tsx    light/dark provider, persisted to localStorage
+  astryx-themes.ts   generated theme registry (CLI-managed)
+  router.tsx         React Router route table
+  App.tsx            providers and router
+  main.tsx           entry point
+```
+
+`src/app-routes.tsx` is the single source of truth for pages and navigation. Add a page there once; `src/router.tsx` derives the route tree from it and `src/components/AppLayout.tsx` derives the sidebar from the same list. Set `showInNav: false` for routes that should not appear in the sidebar.
+
+## Component gallery
+
+The components page renders 14 interactive scenes grouped into base, form, and overlay sections. The scenes cover buttons, typography, layout, data tables, feedback, navigation, chat, form inputs, selection controls, selectors, dialogs, menus, the command palette, and toasts. All 173 Astryx components are represented in the scene metadata, and the full component list is available in a collapsible section at the bottom. Use the search field or the group toggles to narrow the gallery.
+
+## Icons
+
+The icons page (`/icons`) browses 29 Astryx semantic icons and 1,903 Lucide icons. Click any icon to copy its usage, search by name, and page through the Lucide library. The Lucide catalog is lazy-loaded so it does not affect the initial route bundle.
+
+## Build and chunking
+
+- The component gallery (`/components`) and icon browser (`/icons`) are lazy-loaded routes.
+- [vite.config.ts](./vite.config.ts) splits React and React Router into stable `react-vendor` and `router-vendor` chunks.
+- In the current production build, the main `index` chunk is about 231 kB minified / 72 kB gzip, the lazy component gallery is about 385 kB / 118 kB gzip, and the lazy Lucide catalog is about 639 kB / 169 kB gzip.
+
+## Router mode
+
+The root [app.config.ts](./app.config.ts) controls which router React Router creates:
+
+```ts
+export const appConfig = {
+  routerMode: 'browser', // or 'hash'
+}
+```
+
+- `browser` uses normal URLs such as `/components`. The host must rewrite unknown paths to `index.html`.
+- `hash` uses URLs such as `/#/components`. It works on static hosting without a rewrite.
+- Restart the dev server after changing the mode.
+
+Astryx `LinkProvider` is wired to React Router's `Link`, so internal links, nav items, and buttons keep working in both modes.
+
+## Routing
+
+```tsx
+const pageRoutes: RouteObject[] = appRoutes.map((route) =>
+  route.path === '/'
+    ? { index: true, element: route.element }
+    : { path: route.path.slice(1), element: route.element },
+)
+
+const routes: RouteObject[] = [
+  {
+    path: '/',
+    element: <AppLayout />,
+    children: [...pageRoutes, { path: '*', element: <NotFoundPage /> }],
+  },
+]
+
+export const router =
+  appConfig.routerMode === 'hash'
+    ? createHashRouter(routes)
+    : createBrowserRouter(routes)
+```
+
+`LinkProvider` is wired to React Router's `Link`, so Astryx links, buttons with `href`, nav items, and list rows all participate in client-side navigation. Absolute URLs are handled as external links by React Router.
+
+When using `browser` mode on static hosting, configure the host to rewrite unknown paths to `index.html` so deep links such as `/components` reach the client router. `hash` mode does not need a rewrite.
+
+## Theming
+
+`src/astryx-themes.ts` is generated by the Astryx CLI and imports the production theme CSS plus font CSS. `ThemeModeProvider` wraps the app in `<Theme mode={...}>` and exposes a toggle to the app shell.
+
+To add another installed theme:
+
+```bash
+pnpm add @astryxdesign/theme-matcha
+pnpm astryx theme add matcha
+```
+
+Then select it in `src/theme/ThemeMode.tsx`. The mode toggle supports light and dark, starts from the OS preference, and remembers the choice in `localStorage`.
+
+The base styles are imported in `src/index.css`:
+
+```css
+@import '@astryxdesign/core/reset.css';
+@import '@astryxdesign/core/astryx.css';
+```
+
+## Localization
+
+All app copy is Chinese. Astryx's built-in strings (for example the required-field label, skip link, and navigation controls) are localized through `InternationalizationProvider` in `src/main.tsx`, which loads the shipped `zh-CN` catalog.
+
+## Package manager policy
+
+The project uses pnpm 11 and pins the versions in `pnpm-lock.yaml`. Astryx `0.7.2` and `lucide-react` `1.61.0` were published inside pnpm's minimum release age window, so `pnpm-workspace.yaml` explicitly excludes those exact versions from the policy and allows the Astryx postinstall scripts. If you bump these packages, update the exclusions or wait until the new versions age past the policy window.
+
+## Notes
+
+- `AGENTS.md` contains the Astryx agent guide generated by `astryx init`.
+- `theme.template.ts` is the editable template for authoring a custom theme.
+- The `@astryxdesign/cli` package is a dev dependency; use the project-local `pnpm astryx` script so the versions stay in sync.