@teamix-evo/skills 0.4.0 → 0.6.0

package/src/teamix-evo-code-opentrek/testing.md

@@ -1,18 +1,20 @@
 # 测试规范
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 7 的读取项。纯函数和 zod schema 必测，其余按关键路径覆盖。
+
 > **核心约定**:`vitest` + `@testing-library/react` + `msw`,文件就近 `*.test.ts(x)`。**不追求覆盖率数字**,追求"关键路径必有测试 + 纯函数全测"。
 
 ---
 
 ## 选型(业界主流)
 
-| 类型 | 工具 | 理由 |
-| --- | --- | --- |
-| 测试 runner | `vitest` | 与 Vite 原生集成,ESM 友好,API 与 Jest 兼容 |
-| 组件测试 | `@testing-library/react` + `@testing-library/user-event` | 测行为不测实现,业界事实标准(Kent C. Dodds) |
-| API mock | `msw`(Mock Service Worker) | 拦截真实 fetch / axios,测试与生产共用 service 层 |
-| 断言 | `vitest` 内置 `expect`(兼容 Jest) | 无需 chai |
-| E2E(可选) | `playwright` | 关键流程冒烟,**不在本 skill 范围** |
+| 类型        | 工具                                                     | 理由                                             |
+| ----------- | -------------------------------------------------------- | ------------------------------------------------ |
+| 测试 runner | `vitest`                                                 | 与 Vite 原生集成,ESM 友好,API 与 Jest 兼容       |
+| 组件测试    | `@testing-library/react` + `@testing-library/user-event` | 测行为不测实现,业界事实标准(Kent C. Dodds)       |
+| API mock    | `msw`(Mock Service Worker)                               | 拦截真实 fetch / axios,测试与生产共用 service 层 |
+| 断言        | `vitest` 内置 `expect`(兼容 Jest)                        | 无需 chai                                        |
+| E2E(可选)   | `playwright`                                             | 关键流程冒烟,**不在本 skill 范围**               |
 
 **不要混用**:已经选 vitest 就不要再加 jest;已经用 msw 就不要再自己 mock axios。
 
@@ -57,16 +59,16 @@ src/test/
 
 按 ROI 排序:
 
-| 优先级 | 类型 | 例子 | 必测? |
-| --- | --- | --- | --- |
-| P0 | 纯函数(`src/utils/`、`src/services/`) | `formatMoney`、`isValidOrder` | ✅ **必测** |
-| P0 | zod schema | `CreateOrderInputSchema.parse(...)` | ✅ **必测** |
-| P0 | 关键业务路径(下单 / 支付 / 鉴权) | E2E-style 组件测 | ✅ **必测** |
-| P1 | Hook(数据 hook + 自定义 UI hook) | `useOrderList`、`useDebounce` | 推荐 |
-| P1 | 复用业务组件(`src/components/`) | `OrderStatusBadge` 各状态渲染 | 推荐 |
-| P2 | 页面组件 | 用 RTL 渲染 + msw mock | 可选 |
-| ❌ | ui 包源码 | 已在 `@teamix-evo/ui` 包内测过 | **不要重复测** |
-| ❌ | 三方库 | `react-router`、`react-query` | **不要测** |
+| 优先级 | 类型                                  | 例子                                | 必测?          |
+| ------ | ------------------------------------- | ----------------------------------- | -------------- |
+| P0     | 纯函数(`src/utils/`、`src/services/`) | `formatMoney`、`isValidOrder`       | ✅ **必测**    |
+| P0     | zod schema                            | `CreateOrderInputSchema.parse(...)` | ✅ **必测**    |
+| P0     | 关键业务路径(下单 / 支付 / 鉴权)      | E2E-style 组件测                    | ✅ **必测**    |
+| P1     | Hook(数据 hook + 自定义 UI hook)      | `useOrderList`、`useDebounce`       | 推荐           |
+| P1     | 复用业务组件(`src/components/`)       | `OrderStatusBadge` 各状态渲染       | 推荐           |
+| P2     | 页面组件                              | 用 RTL 渲染 + msw mock              | 可选           |
+| ❌     | ui 包源码                             | 已在 `@teamix-evo/ui` 包内测过      | **不要重复测** |
+| ❌     | 三方库                                | `react-router`、`react-query`       | **不要测**     |
 
 **红线**:不要为了凑覆盖率数字测 `Button` 能不能渲染、`React.useState` 能不能用。
 
@@ -158,7 +160,9 @@ function wrapper({ children }: { children: React.ReactNode }) {
 }
 
 it('加载订单列表', async () => {
-  const { result } = renderHook(() => useOrderList({ status: 'all' }), { wrapper });
+  const { result } = renderHook(() => useOrderList({ status: 'all' }), {
+    wrapper,
+  });
   await waitFor(() => expect(result.current.isSuccess).toBe(true));
   expect(result.current.data).toHaveLength(1);
 });
@@ -238,16 +242,16 @@ renderWithProviders(<OrderListPage />, { route: '/orders?status=pending' });
 
 ## §5 · 反模式速查
 
-| 反模式 | 为什么禁 | 应该 |
-| --- | --- | --- |
-| 测 `setState` 是否被调用 | 测了实现,重构即崩 | 测渲染结果 / 用户行为 |
-| `getByTestId` 当默认查询 | data-testid 跟可访问性绑不上 | `getByRole` / `getByLabelText` 优先 |
-| 一个 it 里 expect 10 次无关断言 | 失败定位难 | 拆多个 it |
-| mock 整个 hook(`vi.mock('@/hooks/...')`) | 失去集成价值 | msw mock 后端,hook 真跑 |
-| 自己 mock fetch / axios | 与生产代码路径不一致 | 用 msw |
-| 测试里写 `setTimeout(..., 1000)` 等异步 | 慢且不稳定 | `await waitFor` / `findBy*` |
-| 全局 mock console.error 静默 | 错过真实告警 | 让测试输出 console.error,但 setup 里 fail on it |
-| 追求 80% 覆盖率刷数字 | 测了没价值的代码 | 按"优先级表"测,不看覆盖率盲冲 |
+| 反模式                                   | 为什么禁                     | 应该                                            |
+| ---------------------------------------- | ---------------------------- | ----------------------------------------------- |
+| 测 `setState` 是否被调用                 | 测了实现,重构即崩            | 测渲染结果 / 用户行为                           |
+| `getByTestId` 当默认查询                 | data-testid 跟可访问性绑不上 | `getByRole` / `getByLabelText` 优先             |
+| 一个 it 里 expect 10 次无关断言          | 失败定位难                   | 拆多个 it                                       |
+| mock 整个 hook(`vi.mock('@/hooks/...')`) | 失去集成价值                 | msw mock 后端,hook 真跑                         |
+| 自己 mock fetch / axios                  | 与生产代码路径不一致         | 用 msw                                          |
+| 测试里写 `setTimeout(..., 1000)` 等异步  | 慢且不稳定                   | `await waitFor` / `findBy*`                     |
+| 全局 mock console.error 静默             | 错过真实告警                 | 让测试输出 console.error,但 setup 里 fail on it |
+| 追求 80% 覆盖率刷数字                    | 测了没价值的代码             | 按"优先级表"测,不看覆盖率盲冲                   |
 
 ---
 

package/src/teamix-evo-code-uni-manager/SKILL.md

@@ -29,16 +29,18 @@ If the task is purely about _visual design_ of a screen, use [`teamix-evo-design
 
 ## What this skill does
 
-Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-4 are baseline (always run); steps 5-7 are topic gates (run when the task touches that topic); step 8 is the final self-review.
+Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-4 are baseline (**必须执行，不得跳过**); steps 5-7 are topic gates (run when the task touches that topic); step 8 is the final self-review (**必须执行，不得跳过**).
 
-1. **Reuse-first check** — read [`reuse-first.md`](reuse-first.md). Before creating any new component, query the `@teamix-evo/ui` registry (via MCP `list_components` / `find_components`), the **biz-ui/uni-manager** layer (um-topbar / CloudBadge / ContextSwitcher placeholders), and grep the local project. Only write new code when no reuse path exists. **组件兜底铁律**：找不到时优先 ui 原子件组合，**禁止**自撸基础件。
-2. **Layering check** — read [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`; multi-tenant / multi-region / multi-cloud context (tenantId / regionId / cloudProvider) is **propagated through `lib/http.ts` interceptors**, not as ad-hoc params per call. Components never call `fetch` / `axios` directly. Data hooks live in `src/hooks/` and consume services.
-3. **Directory check** — read [`file-structure.md`](file-structure.md). Place the new file under the right top-level folder; uni-manager-specific shells (TenantContext / RegionContext / CloudBadge) have conventional locations.
-4. **Forms gate** — if the task involves a form, read [`forms-and-validation.md`](forms-and-validation.md). `react-hook-form` + `zod`; schema lives at `src/services/<domain>.schema.ts`. Dangerous operations (delete / release / destroy) **must** route through `useDangerConfirm` (input resource name).
-5. **Error/loading gate** — if the task adds a page or data hook, read [`error-and-loading.md`](error-and-loading.md). Ensure global ErrorBoundary, page-level fallback, and three-state handling (`isPending` / `isError` / data) are in place; mutations report success/error via `toast`. Cross-cloud resource-not-found has a dedicated fallback.
-6. **Routing gate** — if the task adds a route or page-entry, read [`routing-and-codesplit.md`](routing-and-codesplit.md). Pages use `React.lazy`; auth/role guards live in `src/routes/guards.tsx`; **list-page filters MUST sync `tenantId` / `regionId` / `cloudProvider` into URL search params**; um-topbar context switch rewrites the current URL.
-7. **Testing gate** — read [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; tenant-context-aware http handlers must be covered by msw.
-8. **Self-review** — run [`checklist.md`](checklist.md). Every item must pass before declaring the change done.
+1. **🚧 Reuse-first check** — **MUST READ** [`reuse-first.md`](reuse-first.md). Before creating any new component, query the `@teamix-evo/ui` registry (via MCP `list_components` / `find_components`), the **biz-ui/uni-manager** layer (um-topbar / CloudBadge / ContextSwitcher placeholders), and grep the local project. Only write new code when no reuse path exists. **组件兗底铁律**：找不到时优先 ui 原子件组合，**禁止**自撸基础件。
+2. **🚧 Layering check** — **MUST READ** [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`; multi-tenant / multi-region / multi-cloud context (tenantId / regionId / cloudProvider) is **propagated through `lib/http.ts` interceptors**, not as ad-hoc params per call. Components never call `fetch` / `axios` directly. Data hooks live in `src/hooks/` and consume services.
+3. **🚧 Directory check** — **MUST READ** [`file-structure.md`](file-structure.md). Place the new file under the right top-level folder; uni-manager-specific shells (TenantContext / RegionContext / CloudBadge) have conventional locations.
+4. **🚧 Forms gate** — if the task involves a form, **MUST READ** [`forms-and-validation.md`](forms-and-validation.md). `react-hook-form` + `zod`; schema lives at `src/services/<domain>.schema.ts`. Dangerous operations (delete / release / destroy) **must** route through `useDangerConfirm` (input resource name).
+5. **Error/loading gate** — if the task adds a page or data hook, **MUST READ** [`error-and-loading.md`](error-and-loading.md). Ensure global ErrorBoundary, page-level fallback, and three-state handling (`isPending` / `isError` / data) are in place; mutations report success/error via `toast`. Cross-cloud resource-not-found has a dedicated fallback.
+6. **Routing gate** — if the task adds a route or page-entry, **MUST READ** [`routing-and-codesplit.md`](routing-and-codesplit.md). Pages use `React.lazy`; auth/role guards live in `src/routes/guards.tsx`; **list-page filters MUST sync `tenantId` / `regionId` / `cloudProvider` into URL search params**; um-topbar context switch rewrites the current URL.
+7. **Testing gate** — **MUST READ** [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; tenant-context-aware http handlers must be covered by msw.
+8. **🚧 Self-review** — **MUST READ** [`checklist.md`](checklist.md). Every item must pass before declaring the change done.
+
+> ⚠️ **禁止行为**: 跳过 Step 1 (reuse-first) 直接写新组件、跳过 Step 8 (checklist) 不做自检、凭"已有知识"省略任何文件读取。
 
 ## Inputs the user provides
 
@@ -84,7 +86,7 @@ Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-
 
 - [`teamix-evo-design-uni-manager`](../teamix-evo-design-uni-manager/SKILL.md) — visual / interaction rules for uni-manager screen generation. Run **alongside** this skill when the task includes UI; this skill never overrides design on visual concerns.
 - [`teamix-evo-code-opentrek`](../teamix-evo-code-opentrek/SKILL.md) — sister code skill for OpenTrek variant. The two skills share 80% of conventions (file structure / layering / forms / testing); uni-manager-specific deltas are in this skill's SKILL/reuse-first/api-layering/routing/checklist.
-- [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) — lifecycle (`init` / `update` / `uninstall` / `skills add`). Out of scope here.
+- [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) — lifecycle (`init` / `update` / `uninstall` / `skills init` / `skills add`). Out of scope here.
 
 ## Why these conventions（uni-manager 视角）
 

package/src/teamix-evo-code-uni-manager/api-layering.md

@@ -1,5 +1,7 @@
 # API 数据层规范（uni-manager）
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 2 的强制读取项。任何涉及后端通信的代码必须先读本文件。
+
 > **核心原则**：组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`，通过 `src/hooks/` 暴露给组件。
 >
 > **uni-manager 增强**：多租户 / 多区域 / 跨云上下文（tenantId / regionId / cloudProvider）通过 **`src/lib/http.ts` 的 request interceptor 自动注入**，service 函数与 hook 不感知；只有"显式跨上下文"的少数 API 才在调用处显式覆盖。

package/src/teamix-evo-code-uni-manager/checklist.md

@@ -1,5 +1,7 @@
 # 编码自检清单（uni-manager）
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 8 的强制读取项。AI 写完/改完代码后必须读取并逐项核对。不得跳过。
+
 > AI 写完 / 改完代码后，**必须**逐项核对。任何一项未通过都不应交付，需要先修复或显式告诉用户哪条不通过、为什么。
 
 ---

package/src/teamix-evo-code-uni-manager/error-and-loading.md

@@ -1,6 +1,8 @@
 # 错误与加载态规范（uni-manager）
 
-> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兜底必须存在。**不允许**白屏 / 红屏直出给用户。**uni-manager 额外提供跨云资源专属 fallback。**
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 5 的条件读取项。任务涉及页面或数据 hook 时必须读取。
+
+> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兗底必须存在。**不允许**白屏 / 红屏直出给用户。**uni-manager 额外提供跨云资源专属 fallback。**
 
 ---
 

package/src/teamix-evo-code-uni-manager/file-structure.md

@@ -1,5 +1,7 @@
 # 业务工程目录约定（uni-manager）
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 3 的强制读取项。AI 确定新文件放置位置前必须读完本文件。
+
 > 业内主流 React/Vite 业务工程的标准目录骨架。本文件是 AI 决定"新建文件应该放在哪"的唯一参考。**uni-manager 在通用结构基础上，额外约定多租户/多区域/跨云上下文相关目录。**
 
 ---

package/src/teamix-evo-code-uni-manager/forms-and-validation.md

@@ -1,5 +1,7 @@
 # 表单与校验规范（uni-manager）
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 4 的条件读取项。任务涉及表单时必须读取。
+
 > **核心约定**:表单状态用 `react-hook-form`,schema 用 `zod`,**永远不要**用一堆 `useState` 拼表单。**uni-manager 额外约定:危险操作走 `useDangerConfirm`(输入资源完整名称才执行),切租户/区域时表单未保存内容必须二次确认。**
 
 ---

package/src/teamix-evo-code-uni-manager/reuse-first.md

@@ -1,8 +1,10 @@
 # Reuse-First · 组件 / 工具复用决策流（uni-manager）
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 1 的强制读取项。AI 写任何新代码前必须先读完本文件并执行复用查询。
+
 > 在写**任何**新组件 / Hook / 工具函数之前，AI 必须按本流程跑一遍。"没找到现成的"必须是查询的结论，不能是默认假设。
 >
-> uni-manager 在 OpenTrek 通用流程之上，叠加 **biz-ui/uni-manager** 实物层与"组件兜底铁律"。
+> uni-manager 在 OpenTrek 通用流程之上，叠加 **biz-ui/uni-manager** 实物层与"组件兗底铁律"。
 
 ---
 

package/src/teamix-evo-code-uni-manager/routing-and-codesplit.md

@@ -1,6 +1,8 @@
 # 路由与代码分包规范（uni-manager）
 
-> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兜底。**uni-manager 额外约定:tenantId / regionId / cloudProvider 同步到 URL search params,um-topbar 切换上下文时改写 URL。**
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 6 的条件读取项。任务涉及路由或页面入口时必须读取。
+
+> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兗底。**uni-manager 额外约定:tenantId / regionId / cloudProvider 同步到 URL search params,um-topbar 切换上下文时改写 URL。**
 
 ---
 

package/src/teamix-evo-code-uni-manager/testing.md

@@ -1,5 +1,7 @@
 # 测试规范（uni-manager）
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 7 的读取项。纯函数和 zod schema 必测，其余按关键路径覆盖。
+
 > **核心约定**:`vitest` + `@testing-library/react` + `msw`,文件就近 `*.test.ts(x)`。**不追求覆盖率数字**,追求"关键路径必有测试 + 纯函数全测"。**uni-manager 额外要求 msw handler 校验 X-Tenant-Id / X-Region-Id / X-Cloud-Provider 请求头。**
 
 ---

package/src/teamix-evo-design-opentrek/SKILL.md

@@ -7,65 +7,226 @@ description: |
   Coordinates with: teamix-evo-code-opentrek (run alongside when the screen also creates new files).
 ---
 
-# teamix-evo-design-opentrek
+# 页面规则系统 v7.8.4
 
-> OpenTrek 设计体系 — 面向云控制台与企业级 B2B 产品的现代设计语言。
-> 沉稳、克制、可预期，强调高密度信息下的清晰与效率。
->
-> 本技能是 **完整自包含** 的 OpenTrek 设计规则（非 overlay）。
-> Token 具体值请参照 `tokens/theme.css` 中的 CSS 变量，组件详细 API 通过 MCP `get_component_meta` 按需查询。
+> 本文件是**入口索引**：只负责意图路由 + 文件角色索引。
+> 生成 / 翻新 / 验证的详细执行步骤、GATE 门禁、MUST READ 清单一律在 [generation-flow.md](./generation-flow.md)。
+> 页面类型决策树、子类型识别在 [patterns/page-types.md](./patterns/page-types.md)。
 
-<!-- teamix-evo:managed:start id="core" -->
+路由分发架构 — 根技能负责意图识别和索引路由，详细规则在子技能和 `./rules/` 目录。
+三层参数化架构：元规则（固化）+ 产品配置（灵活）+ 模式细节。
 
-## 意图路由
+---
+
+## 1. 意图路由
+
+根据用户输入自动判断执行路径，无需用户指定：
+
+| 意图     | 识别关键词                                                           | 路由路径             | 详细流程                                                               |
+| -------- | -------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------- |
+| **翻新** | "改造"/"升级"/"替换"/"刷新规范"/"翻新"/"对齐规范"/"重新生成这个页面" | 翻新路径             | 详见 [generation-flow.md §2](./generation-flow.md)                     |
+| **生成** | "生成"/"创建"/"新建"/"设计一个"                                      | 生成路径（六步门控） | 详见 [generation-flow.md §1](./generation-flow.md)                     |
+| **验证** | "检查"/"验证"/"评估"/"合规"/"是否符合规范"                           | 验证路径             | 详见 [generation-flow.md §3](./generation-flow.md)                     |
+| **查询** | "token"/"色值"/"间距"/"字体"/"圆角"/"阴影"/"组件尺寸"                | 查询路径             | 直接读取 `./rules/design-tokens.json` / `./rules/component-specs.json` |
+| **规则** | 其他通用问题（"列表页怎么设计"/"弹窗宽度"/"用什么颜色"）             | 根技能               | 读取对应 `./rules/` 文件回答                                           |
+
+---
+
+## 2. 页面类型索引
+
+| 类型 ID                                                                                           | 中文名 | 核心特征                               | 子技能目录             | 状态   |
+| ------------------------------------------------------------------------------------------------- | ------ | -------------------------------------- | ---------------------- | ------ |
+| ListPage                                                                                          | 列表页 | 多条结构化数据 + 搜索/筛选 + 分页      | `./pages/list-page/`   | 已就绪 |
+| DetailPage                                                                                        | 详情页 | 单条记录只读展示 + 描述列表 + 操作按钮 | `./pages/detail-page/` | 已就绪 |
+| FormPage                                                                                          | 表单页 | 用户输入数据 + 字段校验 + 提交         | `./pages/form-page/`   | 已就绪 |
+| Dashboard                                                                                         | 仪表板 | 数据可视化 / 统计聚合                  | —                      | 待开发 |
+| WizardPage / ResultPage / ExceptionPage / WorkspacePage / KanbanPage / WelcomePage / OverviewPage | —      | 见 patterns/page-types.md              | —                      | 待开发 |
+
+> 决策树、Zone Map、易混点速查、子类型识别详见 [patterns/page-types.md](./patterns/page-types.md)。
+
+---
+
+## 3. 子技能索引
+
+> 📖 **读取顺序**：生成/翻新页面时，**主入口 = `./pages/{type}-page/`**（完整规范与布局硬约束）；`./patterns/{type}-page.md` 仅作为**索引概览**用于快速判断子类型。
+
+| 子技能 ID   | 名称       | 子类型数 | 入口文件                                                                                                                                      |
+| ----------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| list-page   | 列表页技能 | 6        | **生成入口**：[`./pages/list-page/`](./pages/list-page/) ← 完整规范 ｜ 索引概览：[`./patterns/list-page.md`](./patterns/list-page.md)         |
+| detail-page | 详情页技能 | 2        | **生成入口**：[`./pages/detail-page/`](./pages/detail-page/) ← 完整规范 ｜ 索引概览：[`./patterns/detail-page.md`](./patterns/detail-page.md) |
+| form-page   | 表单页技能 | 3        | **生成入口**：[`./pages/form-page/`](./pages/form-page/) ← 完整规范 ｜ 索引概览：[`./patterns/form-page.md`](./patterns/form-page.md)         |
+
+### 关键词 → 子技能路由
+
+| 关键词                                 | 路由到                                                                     |
+| -------------------------------------- | -------------------------------------------------------------------------- |
+| "列表"/"表格"/"查询"/"检索"/"数据列表" | → `./pages/list-page/`                                                     |
+| "详情"/"查看"/"信息"/"配置详情"        | → `./pages/detail-page/`                                                   |
+| "表单"/"创建"/"编辑"/"填写"/"新建"     | → `./pages/form-page/`                                                     |
+| "仪表板"/"统计"/"分析"/"指标"          | → [`./patterns/dashboard.md`](./patterns/dashboard.md)（完整子技能待开发） |
+| 其他通用问题                           | 根技能 + `./rules/` 索引                                                   |
+
+### 高频业务场景速查
+
+完整 16 种业务场景映射见 `./rules/business-mapping.json`。核心 6 类：
+
+| 业务场景 | 关键词              | 页面类型       | 返回行为       |
+| -------- | ------------------- | -------------- | -------------- |
+| 查看列表 | 列表/表格/查询/检索 | ListPage       | 带分页和筛选   |
+| 查看详情 | 详情/查看/信息      | DetailPage     | 可返回列表     |
+| 新建记录 | 新建/创建/新增      | FormPage(新建) | 保存后返回列表 |
+| 编辑记录 | 编辑/修改           | FormPage(编辑) | 保存后返回原页 |
+| 删除记录 | 删除/移除           | Dialog         | 确认后刷新列表 |
+| 复制新建 | 复制/克隆           | FormPage(复制) | 保存后返回列表 |
+
+> 完整 CRUD 流转规则见 [flows.md](./flows.md) §3。
+
+---
+
+## 4. 文件角色简表
+
+> 一句话说明每个文件的职责。详细 MUST READ 时机见 [generation-flow.md](./generation-flow.md) 各 Step。
+
+### 4.1 流程与认知文档
+
+| 文件                                       | 作用                                                                                                 |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| [generation-flow.md](./generation-flow.md) | 生成 / 翻新 / 验证三大路径的完整执行步骤与 GATE 门禁（**唯一执行路径**）                             |
+| [philosophy.md](./philosophy.md)           | 设计哲学四大原则（理解"为什么这么做"）                                                               |
+| [brand.md](./brand.md)                     | 视觉调性 + 文案语气基调 + 视觉五维（圆角/配色/密度/阴影/焦点）                                       |
+| [foundations.md](./foundations.md)         | Token 真值：色彩 / 间距 / 字号 / 圆角 / 阴影 / 动效                                                  |
+| [boundaries.md](./boundaries.md)           | 38 条硬规则：F1-F10 禁止项 + S1-S8 样式规则 + C1-C12 结构 + I1-I4 图标 + FF1-FF4 表单 + Overlay 选型 |
+| [components.md](./components.md)           | 组件双层架构 + 选型决策树 + 拼装配方                                                                 |
+| [checklist.md](./checklist.md)             | 10 项自检清单（Step 7 必读）                                                                         |
+| [flows.md](./flows.md)                     | **页间流转唯一真值源**：四条用户旅程 + 主流转图 + CRUD 速查 + 资源生命周期 + 流转设计规则            |
+
+### 4.2 模式文档（patterns/）
+
+| 文件                                                     | 作用                                                                                             |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [patterns/page-types.md](./patterns/page-types.md)       | 页面类型决策树 + Zone Map + 易混点判定                                                           |
+| [patterns/list-page.md](./patterns/list-page.md)         | 列表页 6 种子类型规格（standard / pure-card / standard-card / drawer / expandable / l2-sidebar） |
+| [patterns/detail-page.md](./patterns/detail-page.md)     | 详情页 2 种子类型规格（tabbed / single-section）                                                 |
+| [patterns/form-page.md](./patterns/form-page.md)         | 表单页 3 种子类型规格（single-page / wizard / drawer-form）                                      |
+| [patterns/dashboard.md](./patterns/dashboard.md)         | 仪表板模式（待开发）                                                                             |
+| [patterns/color-mapping.md](./patterns/color-mapping.md) | 语义色映射表（Step 6 必读）                                                                      |
+
+### 4.3 规则文件（rules/）
+
+按读取层次分组，需要时按需读取：
+
+**① 基础定义层**（"有什么"）
 
-收到页面相关请求时，按意图分流：
+| 文件                             | 作用                                                       |
+| -------------------------------- | ---------------------------------------------------------- |
+| `./rules/page-frame.json`        | L0/L1/L2 页面框架规范 + 框架组件继承 + 响应式规则          |
+| `./rules/page-types.json`        | 12 种页面类型 JSON 定义                                    |
+| `./rules/business-mapping.json`  | 16 个业务场景映射（含关键词数组 / 子技能目录 / CRUD 映射） |
+| `./rules/common-components.json` | 40 个业务组件索引（v4.0，以组件名为唯一标识）              |
 
-| 意图     | 识别关键词                                         | 执行路径                                    |
-| -------- | -------------------------------------------------- | ------------------------------------------- |
-| **生成** | "生成" / "创建" / "新建" / "设计一个" / "做一个"   | → generation-flow.md 六步流程               |
-| **翻新** | "改造" / "升级" / "翻新" / "对齐规范" / "重新生成" | → generation-flow.md §翻新路径              |
-| **验证** | "检查" / "验证" / "评估" / "是否符合规范"          | → checklist.md 逐项对照                     |
-| **查询** | "token" / "色值" / "间距" / "组件尺寸"             | → foundations.md(MCP `tokens_*` 工具规划中) |
+**② 布局规则层**（"怎么排"）
 
-## 三阶段 Dispatch
+| 文件                        | 作用                                            |
+| --------------------------- | ----------------------------------------------- |
+| `./rules/layout-rules.json` | 4 种布局模式（A/B/C/D）+ PageContainer 嵌套约束 |
+| `./rules/page-flow.json`    | CRUD 页面流转 + 导航 + 操作确认三级规范         |
+
+**③ 视觉规范层**（"长什么样"）
+
+| 文件                         | 作用                                                             |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `./rules/design-tokens.json` | 语义化色值 / 间距 / 字体 / 尺寸 / 断点（锚定 TrekClaw v4.1 CSS） |
+| `./rules/design-tokens.css`  | 完整 CSS 变量定义（:root 变量块），HTML 内联 / TSX `@import`     |
+
+**④ 实现约束层**（"怎么写"）
+
+| 文件                           | 作用                                                                                          |
+| ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `./rules/component-specs.json` | 26 条组件精确尺寸约束 C1-C26（Button / Input / Dialog / Table / Select / DescriptionList 等） |
+| `./rules/styling.json`         | S1-S8 样式规则 + F1-F10 禁止项                                                                |
+
+### 4.4 范例文档（examples/）
+
+| 文件                                  | 作用                                               |
+| ------------------------------------- | -------------------------------------------------- |
+| `./examples/standard-table-list.html` | 标准表格列表参考范例（表格列规范 / 操作列 / 分页） |
+| `./examples/standard-card-list.html`  | 卡片列表参考范例（CardGrid / ItemCard 结构）       |
+| `./examples/detail-page.html`         | 详情页参考范例（L2 框架 / Tabs / DescriptionList） |
+| `./examples/wizard-form-page.html`    | 向导表单参考范例（Steps / 动态底栏 / 校验）        |
+
+---
+
+## 5. 通用组件分层（速查）
+
+子技能通过**组件名**引用，通过 `shadcnComponent` 字段定位 @teamix-evo/ui 实现。完整索引见 `./rules/common-components.json` v4.0。
+
+- **核心业务组件**：TopNavigation / Sidebar / PageHeader / Breadcrumb / Pagination / Dialog / Sheet / Button / Tag / Badge / Select / Input / Tooltip / Separator / Empty / Spinner / Alert / Sonner
+- **业务扩展组件**：SearchCombo / ContextSwitcher / Steps / ItemCard / CardGrid / CardActionBar
+- **详情页组件**：DescriptionList / DescriptionItem / InfoCard（component-specs.json C26）
+
+---
+
+## 6. 全局执行约束
+
+> 所有路径共享的硬约束。生成代码时强制遵守，违反即不合规。Step 级 Token 用法详见 [generation-flow.md](./generation-flow.md) Step 6。
+
+### 6.1 组件选用优先级（不得跳级）
 
 ```
-阶段 ① 确定页面类型
-  → 读 patterns/page-types.md 决策树
-  → 读 components.md 确认组件集
-
-阶段 ② 匹配子类型 + 布局
-  - List / Detail / Form    → patterns/{list|detail|form}-page.md
-  - Dashboard               → patterns/dashboard.md
-  - Dialog/Sheet/Drawer     → 视为复合组件(非页面);走 components.md §3.1 选型
-                              + boundaries.md F8 / F9 / S7 / C2 / FF1-FF4
-  → 读 patterns/page-types.md §6 确认页间流转(主流转图 / 规则 / CRUD 速查)
-  → 涉及用户旅程时读 flows.md(A 资源查找 / B 创建 / C 异常 / D 批量)
-
-阶段 ③ 生成代码
-  → 读 foundations.md (Token 约束)
-  → 读 boundaries.md (硬规则)
-  → MCP get_component_meta(id) 查组件 Props
-  → 对照 checklist.md 自检
+优先级 1：./rules/ 中已定义的规范组件
+         → common-components.json / component-specs.json / boundaries.md
+优先级 2：@teamix-evo/ui 原子组件合理拼装
+         → 遵循 styling.json 的 S1-S8 + F1-F10
+优先级 3：自定义实现（仅当以上均无法满足）
+         → 必须 <!-- CUSTOM: 原因 --> 标注 + 在 common-components.json 注册 shadcnComponent
 ```
 
-## 文件索引
-
-| 文件                                                 | 职责                                                     |
-| ---------------------------------------------------- | -------------------------------------------------------- |
-| [philosophy.md](./philosophy.md)                     | 设计哲学 + 四大原则 + 方法论                             |
-| [generation-flow.md](./generation-flow.md)           | AI 六步生成/翻新/验证流程                                |
-| [boundaries.md](./boundaries.md)                     | 硬约束：F/FF/S/C/I 五组共 38 条规则([ERROR]/[WARN])      |
-| [checklist.md](./checklist.md)                       | 10 项自检清单                                            |
-| [foundations.md](./foundations.md)                   | Token 用法 + 排版 + 间距 + 色彩 + 圆角 + 阴影 + 动效     |
-| [components.md](./components.md)                     | 组件选型决策树 + 双层架构索引 + 组合规则                 |
-| [patterns/page-types.md](./patterns/page-types.md)   | 5 种页面类型 + 识别决策树 + Zone Map + 页间流转(§6)      |
-| [patterns/list-page.md](./patterns/list-page.md)     | 列表页模式 (6 种子类型)                                  |
-| [patterns/detail-page.md](./patterns/detail-page.md) | 详情页模式                                               |
-| [patterns/form-page.md](./patterns/form-page.md)     | 表单页模式 (含 wizard)                                   |
-| [patterns/dashboard.md](./patterns/dashboard.md)     | Dashboard 数据概览(StatCard / Chart 标准结构)            |
-| [flows.md](./flows.md)                               | 4 条核心用户旅程 + 流转自检                              |
-| [brand.md](./brand.md)                               | OpenTrek 品牌调性 + 文案语气 + 正反例                    |
-
-<!-- teamix-evo:managed:end -->
+### 6.2 Token 引用格式（速查）
+
+所有视觉属性必须引用 Token，禁止硬编码。完整 Token 定义见 [foundations.md](./foundations.md)。
+
+| 属性类别 | 正确写法                                    | 禁止写法                           |
+| -------- | ------------------------------------------- | ---------------------------------- |
+| 颜色     | `hsl(var(--token-name))`                    | `#0055EE`、`rgb(0,85,238)`、`blue` |
+| 间距     | Token 变量或 Tailwind spacing class         | 裸写 `16px`、`1rem`                |
+| 字号     | `var(--font-size-*)` 四级（base/lg/xl/2xl） | 裸写 `14px`、`0.875rem`            |
+| 圆角     | `var(--radius-*)` 层级（sm/md/lg）          | 裸写 `8px`、`0.5rem`               |
+| 阴影     | `var(--shadow-*)`                           | 裸写 `0 1px 3px rgba(...)`         |
+| 字体族   | `var(--font-sans)` / `var(--font-mono)`     | 裸写 `Inter, sans-serif`           |
+
+### 6.3 标准范例引用
+
+生成页面前**必须**参考对应类型的标准范例（见 §4.4 examples/），作为输出质量基准。
+
+### 6.4 设计语言一致性
+
+| 维度     | 约束                                                                 | 依据                                   |
+| -------- | -------------------------------------------------------------------- | -------------------------------------- |
+| 间距模型 | v7.5 分层 padding：Card.paddingX = 20px，Table 首末列 padding = 20px | `design-tokens.json` §componentSpacing |
+| 品牌主色 | #0055EE（HSL 218.6° 100% 46.7%），通过 `var(--primary)` 引用         | `design-tokens.css`                    |
+| 页面框架 | 遵循 `page-frame.json` 的 L0/L1/L2 层级继承                          | `./rules/page-frame.json`              |
+| 布局模式 | 遵循 `layout-rules.json` 的 A/B/C/D 四种模式 + 扩展模式              | `./rules/layout-rules.json`            |
+| 页面流转 | 遵循 `page-flow.json` 的 CRUD 路径与导航规范                         | `./rules/page-flow.json`               |
+| 表面规则 | v7.6 ContentCard：去 border，使用 shadow-sm                          | `styling.json`                         |
+| 设计原则 | 优先使用已有组件 → 组合而非重写 → 优先内置 variant → 使用语义色值    | `foundations.md`                       |
+
+### 6.5 降级拼装规则
+
+当规范中未定义某组件需求时，使用 @teamix-evo/ui 拼装须满足：
+
+1. **结构合规**：通过 `boundaries.md` C1-C12 校验
+2. **样式合规**：通过 `styling.json` F1-F10 自检
+3. **Token 合规**：所有视觉属性引用 Token，无硬编码
+4. **语义清晰**：使用 @teamix-evo/ui 的 variant 体系
+5. **可追溯**：HTML 注释中标注拼装来源和决策原因
+
+---
+
+## 7. 与 code-opentrek skill 协作
+
+页面级任务通常 design + code 两个 skill 同时触发。冲突时按 ADR 0018：
+
+- **design 决定"做什么"**：页面骨架 / Zone 划分 / 组件选型 / Token 绑定 / 视觉规则
+- **code 决定"怎么做"**：文件放置 / import 路径 / API 层 / 表单实现细节
+
+> 完整分工矩阵见 [generation-flow.md §5](./generation-flow.md)。

package/src/teamix-evo-design-opentrek/boundaries.md

@@ -1,6 +1,9 @@
 # 硬约束 · Boundaries
 
-> 本文件列出所有"AI 生成页面 / 组件代码时**不能做什么**"的硬规则。共 38 条规则分 5 组：
+> ⚠️ **何时读本文件**: [generation-flow.md](./generation-flow.md) Step 7（自检）、翻新路径、验证路径均强制要求完整读取本文件。
+> 本文件是硬规则的**唯一真值**，不得跳过。
+
+> 本文件列出所有“AI 生成页面 / 组件代码时**不能做什么**”的硬规则。共 38 条规则分 5 组：
 >
 > - **F1-F10**：禁止项（视觉与 token 层面）
 > - **FF1-FF4**：表单专属硬约束（错误信息、必填、状态色块、Card 嵌套）
@@ -41,6 +44,23 @@
 >
 > 检查: eslint `teamix-evo/no-arbitrary-tw-value` (Tailwind className) · stylelint `teamix-evo/no-hardcoded-dimension` (CSS gap/padding/margin/width/height/font-size 等)
 
+### [ERROR] F2.5 · 禁止使用原生 HTML form 控件
+
+```diff
+- <input value={v} onChange={(e) => setV(e.target.value)} />
+- <select value={v} onChange={(e) => setV(e.target.value)}>...</select>
+- <textarea ... />
++ <Input value={v} onChange={setV} />
++ <Select options={...} value={v} onChange={setV} />
++ <Textarea ... />
+```
+
+任何场景(业务页面 / 模板 demo / 示例代码 / story)**都禁止**直接使用原生 `<input>` / `<select>` / `<textarea>` / `<form>` 字段元素 — 必须用 ui 包的 `<Input>` / `<Select>` / `<Textarea>` / `<Switch>` / `<Checkbox>` / `<RadioGroup>` / `<DatePicker>` 等组件。原生控件不带 token 视觉、不联动 Field 校验态、不参与 `react-hook-form` Controller。
+
+**列表筛选区**用 `<FilterBarPreset>` / `<FilterBar>` + `<FormField>` + 原子组件;**表单页**用 `<Form>` + `<FieldGroup>` + `<FormField>` + 原子组件;**单字段输入**仍用 `<Input>` / `<Select>` 直传 value/onChange。
+
+> 检查: eslint(规划中:`teamix-evo/no-native-form-control`)+ 人工 review
+
 ### [ERROR] F3 · 禁止按组件新增重复语义变量
 
 新增 CSS 变量前**必须**先检索 `tokens/theme.css`：
@@ -155,7 +175,7 @@
 + </Card>
 ```
 
-白卡是表单页的**单例容器**(参 [list-page.md §9 嵌套约束](./patterns/list-page.md#9-嵌套约束) / [form-page.md §9](./patterns/form-page.md#9-嵌套约束))。分区表单确需嵌入子 Card 时,子 Card 必须有明确边框/阴影差异,且仅限**分区表单**用例(form-page.md §2.3)。
+白卡由 [`OpPageContainer`](../../biz-ui/variants/opentrek/op-page-container/op-page-container.meta.md) **内置**(`bg-card rounded-2xl p-6` 撑满主区),是 opentrek 任何页面类型的**单例容器**(参 [list-page.md §9 嵌套约束](./patterns/list-page.md#9-嵌套约束) / [form-page.md §9](./patterns/form-page.md#9-嵌套约束))。**不要再手写 `<Card>` 包整个 PageHeader / DataTable / Form**(违反白卡单例)。分区表单确需在白卡内嵌入子 Card 划分若干小节时,子 Card 必须有明确边框/阴影差异,且仅限**分区表单**用例(form-page.md §2.3)。
 
 > 检查: 无 lint (人工评审 / reviewer subagent)
 
@@ -259,7 +279,7 @@ CSS 变量已在 dark 模式下自动切换。手动 `dark:` 会绕过主题系
 + <Dialog><DialogContent>
 ```
 
-适用：`Dialog / Sheet / Drawer / Popover / Tooltip / DropdownMenu / HoverCard`。组件自带层级管理。
+适用：`Dialog / Sheet / Popover / Tooltip / DropdownMenu / HoverCard`。组件自带层级管理。
 
 > 检查: 无 lint (运行时 / 评审,可由 reviewer subagent 抽检)
 
@@ -306,7 +326,7 @@ CSS 变量已在 dark 模式下自动切换。手动 `dark:` 会绕过主题系
 
 > 检查: 无 lint (后续可加 ESLint JSX 结构规则,目前由 reviewer subagent 抽检)
 
-### [ERROR] C2 · Dialog / Sheet / Drawer 必须有 Title
+### [ERROR] C2 · Dialog / Sheet 必须有 Title
 
 ```diff
 - <DialogContent>...</DialogContent>
@@ -496,7 +516,7 @@ CSS 变量已在 dark 模式下自动切换。手动 `dark:` 会绕过主题系
 | 需要输入的任务         | `Dialog`                            |
 | 危险操作确认           | `AlertDialog variant="destructive"` |
 | 侧面板（详情 / 筛选）  | `Sheet`                             |
-| 移动端底部面板         | `Drawer`                            |
+| 移动端底部面板         | `Sheet side="bottom"`               |
 | 悬浮信息（hover 触发） | `HoverCard`                         |
 | 点击弹出小内容         | `Popover`                           |
 

package/src/teamix-evo-design-opentrek/brand.md

@@ -6,13 +6,13 @@
 
 ## 1. 视觉风格五维
 
-| 维度         | 定位     | 具体表现                                | 对立面（禁止）       |
-| ------------ | -------- | --------------------------------------- | -------------------- |
-| **色彩情绪** | 沉稳专业 | 深色底色为主基调 + 高对比度信息层级     | 花哨多彩、渐变堆叠   |
-| **信息密度** | 高效紧凑 | 单屏承载核心操作，减少翻页              | 大面积留白、装饰占位 |
-| **视觉层次** | 克制有序 | 间距、字重、色彩建立 3 级层级           | 多重强调、全部高亮   |
-| **交互反馈** | 即时确定 | 操作后 200ms 内明确反馈                 | 模糊状态、静默       |
-| **圆角风格** | 轻圆角   | `rounded-md` (6px) / `rounded-lg` (8px) | 全直角、超大圆角     |
+| 维度         | 定位     | 具体表现                                                                           | 对立面（禁止）       |
+| ------------ | -------- | ---------------------------------------------------------------------------------- | -------------------- |
+| **色彩情绪** | 沉稳专业 | 品牌主色 `#0055EE` (hsl(218.6 100% 46.7%)) + 高对比信息层级                        | 花哨多彩、渐变堆叠   |
+| **信息密度** | 高效紧凑 | 单屏承载核心操作，减少翻页                                                         | 大面积留白、装饰占位 |
+| **视觉层次** | 克制有序 | 间距、字重、色彩建立 3 级层级                                                      | 多重强调、全部高亮   |
+| **交互反馈** | 即时确定 | 操作后 200ms 内明确反馈                                                            | 模糊状态、静默       |
+| **圆角风格** | 中圆角   | OpenTrek v4.1：`rounded-md` (8px) / `rounded-lg` (12px)；legacy `rounded-sm` (4px) | 全直角、超大圆角     |
 
 ---