@teamix-evo/skills 0.4.0 → 0.6.0

package/README.md

@@ -42,15 +42,19 @@ pnpm --filter @teamix-evo/skills scaffold:skill
 由 `teamix-evo skills` 子命令族管理（source-mirror 模型见 [ADR 0013](../../docs/adr/0013-skills-source-mirror.md)）：
 
 ```bash
-teamix-evo skills add                # 全量装入 manifest 内所有 skill
-teamix-evo skills add <name...>      # 增量：仅装入指定 skill（可多个）
+teamix-evo skills init               # 自举：按 variant + scope 全装符合条件的 skill（ADR 0034）
+teamix-evo skills add <name...>      # 增量：仅装入指定 skill（必填，至少一个）
 teamix-evo skills list               # 列出全部 skill（默认：已装✓ / 未装○）
-teamix-evo skills update             # 升级到最新版（managed 策略保留你的自定义）
+teamix-evo skills update [name...] [--dry-run]  # 升级已装 skill（ADR 0035 双闸 + version 短路）
 teamix-evo skills sync [name...]     # 源 → IDE 镜像（漂移恢复用）
 teamix-evo skills doctor             # 检测源 / 镜像漂移
 teamix-evo skills uninstall          # 卸载（源 + 镜像 + lock）
 ```
 
+> **verb 分工(ADR 0034)**:`init` 自举(无 ids)/ `add` 增量(必填 ids)。`skills add` 不传 id → commander 报错并输出 help。
+>
+> **scope 过滤(ADR 0033)**:`skills init` 跳过 manifest 里 `scope` 与当前 install scope 不匹配的 entry。entry skill `teamix-evo-manage` 标 `scope: "global"`,因此项目级 init 不会重复装入 —— 它由「全局装机」段一次性装到全局。`skills add` 显式指名 global-only skill 时仍可装入,但会得到 warning。
+
 ### 全局装机（`--scope global`）
 
 ```bash

package/manifest.json

@@ -10,7 +10,7 @@
     {
       "id": "teamix-evo-manage",
       "name": "teamix-evo-manage",
-      "description": "Single entry point for the teamix-evo lifecycle: scaffold a new project, install the AI coding system into an existing repo, run / update / inspect / remove any teamix-evo package, and drive the placeholder→real UI migration loop after `npm create teamix-evo`.\nTRIGGER when: (CLI) user runs or asks about `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo templates ...` / `teamix-evo logs ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) \"初始化一个项目\"、\"初始化一个工程\"、\"初始化一个 teamix-evo 工程\"、\"初始化一个 Teamix Evo 项目\"、\"create a teamix-evo project\"、\"set up teamix-evo from scratch\"、\"new teamix-evo app\"; (具名变体初始化) \"初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目\"、\"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程\"、\"new opentrek/uni-manager project\"; (AI coding 接入) \"给现有仓库装 teamix-evo\"、\"现有项目装一下 skills + ui\"、\"接入 AI coding 体系\"、\"装 teamix-evo 进这个项目\"、\"add teamix-evo to existing repo\"、\"install AI coding system\"、\"接入 opentrek 研发体系\"、\"接入 op 研发体系\"、\"接入 OpenTrek 研发体系\"、\"接入 opentrek 研发系统\"、\"接入 op 研发系统\"、\"接入云管研发体系\"、\"接入云管研发系统\"、\"接入 uni-manager 研发体系\"、\"接入 uni-manager 研发系统\"、\"接入统一管理研发体系\"; (更新检测) \"升级 teamix-evo\"、\"看看哪些要升级\"、\"update teamix-evo\"、\"check what needs updating\"、\"refresh installed teamix-evo packages\"; (卸载 / 清单) \"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"remove the design system\"、\"list installed\"; (placeholder→real 升级) \"升级 UI\"、\"接入真组件\"、\"替换 placeholder\"、\"upgrade UI\"、\"replace placeholders\"、\"swap in real components\"、\"make the UI real\", or user opens / edits `src/components/_placeholder/**`, project contains `.teamix-evo/create/pending-ui.json`, literal `@teamix-evo:placeholder` tag in code; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`、`.teamix-evo/create/pending-ui.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the migration loop, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.",
+      "description": "Single entry point for the teamix-evo lifecycle: scaffold a new project, install the AI coding system into an existing repo, run / update / inspect / remove any teamix-evo package, and drive the placeholder→real UI migration loop after `npm create teamix-evo`.\nTRIGGER when: (CLI) user runs or asks about `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo templates ...` / `teamix-evo lint ...` / `teamix-evo logs ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) \"初始化一个项目\"、\"初始化一个工程\"、\"初始化一个 teamix-evo 工程\"、\"初始化一个 Teamix Evo 项目\"、\"create a teamix-evo project\"、\"set up teamix-evo from scratch\"、\"new teamix-evo app\"; (具名变体初始化) \"初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目\"、\"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程\"、\"new opentrek/uni-manager project\"; (AI coding 接入) \"给现有仓库装 teamix-evo\"、\"现有项目装一下 skills + ui\"、\"接入 AI coding 体系\"、\"装 teamix-evo 进这个项目\"、\"add teamix-evo to existing repo\"、\"install AI coding system\"、\"接入 opentrek 研发体系\"、\"接入 op 研发体系\"、\"接入 OpenTrek 研发体系\"、\"接入 opentrek 研发系统\"、\"接入 op 研发系统\"、\"接入云管研发体系\"、\"接入云管研发系统\"、\"接入 uni-manager 研发体系\"、\"接入 uni-manager 研发系统\"、\"接入统一管理研发体系\"; (更新检测) \"升级 teamix-evo\"、\"看看哪些要升级\"、\"update teamix-evo\"、\"check what needs updating\"、\"refresh installed teamix-evo packages\"; (卸载 / 清单) \"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"remove the design system\"、\"list installed\"; (placeholder→real 升级) \"升级 UI\"、\"接入真组件\"、\"替换 placeholder\"、\"upgrade UI\"、\"replace placeholders\"、\"swap in real components\"、\"make the UI real\", or user opens / edits `src/components/_placeholder/**`, project contains `.teamix-evo/create/pending-ui.json`, literal `@teamix-evo:placeholder` tag in code; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`、`.teamix-evo/create/pending-ui.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the migration loop, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.",
       "version": "0.2.0",
       "source": "src/teamix-evo-manage",
       "ides": [
@@ -21,7 +21,8 @@
       "managedRegions": [
         "core"
       ],
-      "template": false
+      "template": false,
+      "scope": "global"
     },
     {
       "id": "teamix-evo-design-opentrek",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Skills (AI IDE capabilities) for Teamix Evo",
   "type": "module",
   "files": [
@@ -12,7 +12,7 @@
   "devDependencies": {
     "@clack/prompts": "^0.8.0",
     "tsx": "^4.0.0",
-    "@teamix-evo/registry": "0.3.0"
+    "@teamix-evo/registry": "0.7.0"
   },
   "publishConfig": {
     "access": "public",

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

@@ -29,16 +29,18 @@ If the task is purely about _visual design_ of a screen (layout / colors / spaci
 
 ## 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`) and grep the local project. Only write new code when no reuse path exists.
-2. **Layering check** — read [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`. 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 (pages / components / services / hooks / types / utils / lib / stores / contexts). Each folder has a single responsibility and an import boundary.
-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`. Never wire forms with raw `useState`.
-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`.
-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`; 404 / 403 / 500 fallbacks exist.
-7. **Testing gate** — read [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; hooks and reusable components are recommended. Test files sit next to the source as `*.test.ts(x)`; `vitest` + `@testing-library/react` + `msw`.
-8. **Self-review** — run [`checklist.md`](checklist.md). Every item must pass before declaring the change done. Anything failing must be fixed or surfaced to the user.
+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`) and grep the local project. Only write new code when no reuse path exists.
+2. **🚧 Layering check** — **MUST READ** [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`. 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 (pages / components / services / hooks / types / utils / lib / stores / contexts). Each folder has a single responsibility and an import boundary.
+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`. Never wire forms with raw `useState`.
+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`.
+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`; 404 / 403 / 500 fallbacks exist.
+7. **Testing gate** — **MUST READ** [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; hooks and reusable components are recommended. Test files sit next to the source as `*.test.ts(x)`; `vitest` + `@testing-library/react` + `msw`.
+8. **🚧 Self-review** — **MUST READ** [`checklist.md`](checklist.md). Every item must pass before declaring the change done. Anything failing must be fixed or surfaced to the user.
+
+> ⚠️ **禁止行为**: 跳过 Step 1 (reuse-first) 直接写新组件、跳过 Step 8 (checklist) 不做自检、凭"已有知识"省略任何文件读取。
 
 ## Inputs the user provides
 
@@ -81,7 +83,7 @@ Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-
 ## Relationship to other skills
 
 - [`teamix-evo-design-opentrek`](../teamix-evo-design-opentrek/SKILL.md) — visual / interaction rules for screen generation. Run **alongside** this skill when the task includes UI; this skill never overrides design on visual concerns.
-- [`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
 

package/src/teamix-evo-code-opentrek/api-layering.md

@@ -1,5 +1,7 @@
 # API 数据层规范
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 2 的强制读取项。任何涉及后端通信的代码必须先读本文件。
+
 > **核心原则**:组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`,通过 `src/hooks/` 暴露给组件。
 
 ---
@@ -80,6 +82,7 @@ export async function createOrder(input: CreateOrderInput): Promise<Order> {
 ```
 
 要点:
+
 - **纯函数**(不依赖 React 上下文,可以在 SSR / Node 测试中单独跑)
 - **类型来自 `src/types/`**,不要在 service 文件里就地定义 domain 类型
 - **错误不在 service 层处理** —— 抛出去给 hook / 全局 interceptor 处理(归一化在 `src/lib/http.ts`)
@@ -201,11 +204,11 @@ src/types/
 
 某些场景**允许**绕过本规范,但需要在代码注释里说明原因:
 
-| 场景 | 允许 |
-| --- | --- |
-| 静态资源 fetch(读 `public/` 下的 json) | 组件直接 `fetch` 可,不用进 service |
-| 第三方 SDK(地图、支付)有自己的客户端 | 包装层放 `src/lib/<sdk>.ts`,不强制走 services |
-| 一次性的诊断 / 调试代码 | 临时 fetch 可,但 PR 合并前必须清理或归位 |
+| 场景                                   | 允许                                          |
+| -------------------------------------- | --------------------------------------------- |
+| 静态资源 fetch(读 `public/` 下的 json) | 组件直接 `fetch` 可,不用进 service            |
+| 第三方 SDK(地图、支付)有自己的客户端   | 包装层放 `src/lib/<sdk>.ts`,不强制走 services |
+| 一次性的诊断 / 调试代码                | 临时 fetch 可,但 PR 合并前必须清理或归位      |
 
 ---
 

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

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

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

@@ -1,6 +1,8 @@
 # 错误与加载态规范
 
-> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兜底必须存在。**不允许**白屏 / 红屏直出给用户。
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 5 的条件读取项。任务涉及页面或数据 hook 时必须读取。
+
+> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兗底必须存在。**不允许**白屏 / 红屏直出给用户。
 
 ---
 
@@ -62,13 +64,21 @@ createRoot(document.getElementById('root')!).render(
 // src/components/GlobalErrorFallback.tsx
 import { Button } from '@teamix-evo/ui';
 
-export function GlobalErrorFallback({ resetErrorBoundary }: { resetErrorBoundary: () => void }) {
+export function GlobalErrorFallback({
+  resetErrorBoundary,
+}: {
+  resetErrorBoundary: () => void;
+}) {
   return (
     <div className="flex min-h-screen items-center justify-center">
       <div className="text-center">
         <h1 className="text-2xl font-semibold">页面出错了</h1>
-        <p className="text-muted-foreground mt-2">已记录,可尝试刷新或返回首页</p>
-        <Button className="mt-4" onClick={resetErrorBoundary}>重新加载</Button>
+        <p className="text-muted-foreground mt-2">
+          已记录,可尝试刷新或返回首页
+        </p>
+        <Button className="mt-4" onClick={resetErrorBoundary}>
+          重新加载
+        </Button>
       </div>
     </div>
   );
@@ -130,19 +140,19 @@ function OrderListPage() {
 
 ### 三种状态都要处理
 
-| 状态 | 必须输出 |
-| --- | --- |
-| `isPending`(首次加载) | Skeleton / Spinner,**不允许**显示空 div |
-| `isError` | 错误面板 + 重试按钮,**不允许**直接 `throw` |
-| `isFetching`(后台刷新) | 表格右上角小转圈即可,不要遮罩 |
+| 状态                   | 必须输出                                   |
+| ---------------------- | ------------------------------------------ |
+| `isPending`(首次加载)  | Skeleton / Spinner,**不允许**显示空 div    |
+| `isError`              | 错误面板 + 重试按钮,**不允许**直接 `throw` |
+| `isFetching`(后台刷新) | 表格右上角小转圈即可,不要遮罩              |
 
 ### Skeleton vs Spinner 怎么选
 
-| 场景 | 用 |
-| --- | --- |
-| 列表 / 卡片 / 详情 | Skeleton(撑住布局,避免 CLS) |
-| 短动作(按钮提交、< 500ms 加载) | Spinner |
-| 全屏切换 | PageSkeleton 或 logo loading |
+| 场景                           | 用                           |
+| ------------------------------ | ---------------------------- |
+| 列表 / 卡片 / 详情             | Skeleton(撑住布局,避免 CLS)  |
+| 短动作(按钮提交、< 500ms 加载) | Spinner                      |
+| 全屏切换                       | PageSkeleton 或 logo loading |
 
 ---
 
@@ -177,14 +187,17 @@ react-query v5 支持 `useSuspenseQuery`,可把 loading 转给 `<Suspense>`:
 
 ```tsx
 function OrderListPage() {
-  const { data } = useSuspenseQuery({ queryKey: ['orders'], queryFn: listOrders });
+  const { data } = useSuspenseQuery({
+    queryKey: ['orders'],
+    queryFn: listOrders,
+  });
   return <OrderTable data={data} />; // 不需要 isPending 分支
 }
 
 // 父级:
 <Suspense fallback={<TableSkeleton rows={10} />}>
   <OrderListPage />
-</Suspense>
+</Suspense>;
 ```
 
 **何时用**:
@@ -232,15 +245,15 @@ window.addEventListener('error', (e) => reportError(e.error));
 
 ## 反模式速查
 
-| 反模式 | 为什么禁 | 应该 |
-| --- | --- | --- |
-| 没有全局 ErrorBoundary | 异常直接白屏 | App 根挂一层 |
-| `useState(false)` + `useEffect` 管 loading | 重复造轮,易漏 cancel | 走 react-query / useSuspenseQuery |
-| 只判 `isLoading` 不判 `isError` | 错误态显示空白 | 三态都处理 |
-| `if (data) return <>...</> else return null` | 无 skeleton,布局抖动 + CLS | 加 Skeleton |
-| `alert('保存失败')` | 阻断用户、丑、不可样式化 | `toast.error()` |
-| ErrorBoundary 不上报 | 错过线上 bug | `onError` 接 `reportError` |
-| service 里 `try/catch` 吞错 | 上层失去判断依据 | 让 error 抛上来,hook / boundary 决定 |
+| 反模式                                       | 为什么禁                   | 应该                                 |
+| -------------------------------------------- | -------------------------- | ------------------------------------ |
+| 没有全局 ErrorBoundary                       | 异常直接白屏               | App 根挂一层                         |
+| `useState(false)` + `useEffect` 管 loading   | 重复造轮,易漏 cancel       | 走 react-query / useSuspenseQuery    |
+| 只判 `isLoading` 不判 `isError`              | 错误态显示空白             | 三态都处理                           |
+| `if (data) return <>...</> else return null` | 无 skeleton,布局抖动 + CLS | 加 Skeleton                          |
+| `alert('保存失败')`                          | 阻断用户、丑、不可样式化   | `toast.error()`                      |
+| ErrorBoundary 不上报                         | 错过线上 bug               | `onError` 接 `reportError`           |
+| service 里 `try/catch` 吞错                  | 上层失去判断依据           | 让 error 抛上来,hook / boundary 决定 |
 
 ---
 

package/src/teamix-evo-code-opentrek/file-structure.md

@@ -1,5 +1,7 @@
 # 业务工程目录约定
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 3 的强制读取项。AI 确定新文件放置位置前必须读完本文件。
+
 > 业内主流 React/Vite 业务工程的标准目录骨架。本文件是 AI 决定"新建文件应该放在哪"的唯一参考。
 
 ---
@@ -51,6 +53,7 @@ src/pages/
 ```
 
 约束:
+
 - 页面组件**默认 default export**,与文件名一致
 - `_components/` `_hooks/` 用下划线前缀标记**私有**,**禁止跨页面 import**
 - 跨页面用得到的组件/hook → 升到 `src/components/` `src/hooks/`
@@ -69,6 +72,7 @@ src/components/
 ```
 
 约束:
+
 - 命名 PascalCase,文件名 = 组件名
 - 单组件 = 单文件;复杂组件可建子目录 `<Name>/{index.tsx, types.ts, hooks.ts}`
 - **不要**重复 `@teamix-evo/ui` 已经提供的能力(见 [reuse-first.md](reuse-first.md))
@@ -91,6 +95,7 @@ src/hooks/
 ```
 
 约束:
+
 - 命名必须 `use` 开头
 - 单 hook = 单文件
 - 数据 hook 调 `src/services/`,**禁止**直接 fetch
@@ -99,12 +104,12 @@ src/hooks/
 
 **装机时默认不预装任何状态库**。按"最小够用"逐级升级,不要直接跳到 zustand:
 
-| 场景 | 用什么 |
-| --- | --- |
-| 组件内状态 | `useState` / `useReducer` |
-| 跨少量组件、低频更新(当前用户、主题、语言、租户) | React `Context` |
-| 跨域、多页面、**高频**更新的客户端态 | `src/stores/`(zustand / jotai / redux 选一) |
-| 服务端数据(列表、详情、表单提交) | `react-query` / `swr`,**永远不进 Context、也不进 store** |
+| 场景                                             | 用什么                                                   |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| 组件内状态                                       | `useState` / `useReducer`                                |
+| 跨少量组件、低频更新(当前用户、主题、语言、租户) | React `Context`                                          |
+| 跨域、多页面、**高频**更新的客户端态             | `src/stores/`(zustand / jotai / redux 选一)              |
+| 服务端数据(列表、详情、表单提交)                 | `react-query` / `swr`,**永远不进 Context、也不进 store** |
 
 「高频」的粗略判定:一个状态被 10+ 处读取、且每秒可能变化一次以上 —— Context 会触发整子树重渲染,这时才有引 store 的收益。
 
@@ -131,6 +136,7 @@ Context 文件位置:
 **职责**:类型声明。
 
 约束:
+
 - 只放 `.ts` 类型文件,**不导出运行时代码**
 - 按 domain 拆:`order.ts`、`user.ts`
 - 通用类型放 `api.ts`、`common.ts`
@@ -140,6 +146,7 @@ Context 文件位置:
 **职责**:纯函数工具。
 
 约束:
+
 - **不依赖 React**(用了 React 应该是 hook,放 `src/hooks/`)
 - **不依赖 DOM**(用了 DOM 应该是 lib 层包装)
 - **不发请求**(发请求是 service)
@@ -158,6 +165,7 @@ src/lib/
 ```
 
 约束:
+
 - 这一层**与 React 解耦**,可以在 Node / 测试中跑
 - **不放业务逻辑** —— 业务逻辑去 service / hook
 
@@ -177,16 +185,16 @@ src/routes/
 
 ## 命名约定
 
-| 类型 | 风格 | 例 |
-| --- | --- | --- |
-| 目录 | kebab-case | `src/pages/order-detail/` |
-| React 组件文件 | PascalCase.tsx | `OrderStatusBadge.tsx` |
-| Hook 文件 | camelCase.ts,`use` 前缀 | `useOrderList.ts` |
-| Service 文件 | camelCase.ts,domain 名 | `order.ts` |
-| 工具文件 | camelCase.ts | `formatDate.ts` |
-| 类型文件 | camelCase.ts,domain 名 | `order.ts` |
-| 常量文件 | camelCase.ts 或 SCREAMING_SNAKE 导出 | `constants.ts` |
-| 测试文件 | `*.test.ts(x)` 紧邻被测文件 | `formatDate.test.ts` |
+| 类型           | 风格                                 | 例                        |
+| -------------- | ------------------------------------ | ------------------------- |
+| 目录           | kebab-case                           | `src/pages/order-detail/` |
+| React 组件文件 | PascalCase.tsx                       | `OrderStatusBadge.tsx`    |
+| Hook 文件      | camelCase.ts,`use` 前缀              | `useOrderList.ts`         |
+| Service 文件   | camelCase.ts,domain 名               | `order.ts`                |
+| 工具文件       | camelCase.ts                         | `formatDate.ts`           |
+| 类型文件       | camelCase.ts,domain 名               | `order.ts`                |
+| 常量文件       | camelCase.ts 或 SCREAMING_SNAKE 导出 | `constants.ts`            |
+| 测试文件       | `*.test.ts(x)` 紧邻被测文件          | `formatDate.test.ts`      |
 
 ---
 
@@ -220,6 +228,7 @@ lib     ──▶ types only
 ```
 
 要点:
+
 - **services 不依赖 React** —— 它是纯函数层
 - **types / utils / lib 是叶子层** —— 不依赖业务层,谁都能引
 - **反向依赖直接否决**(component 不能 import page,service 不能 import hook)
@@ -228,46 +237,46 @@ lib     ──▶ types only
 
 ## 反模式速查
 
-| 反模式 | 为什么禁 | 应该怎么做 |
-| --- | --- | --- |
-| `src/views/`、`src/screens/` 与 `src/pages/` 并存 | 同义层,认知爆炸 | 二选一,统一叫 `pages/` |
-| `src/api/` 与 `src/services/` 并存 | 同义层 | 统一叫 `services/` |
-| `src/utils/` 与 `src/helpers/` 并存 | 同义层 | 统一叫 `utils/` |
-| 在 `src/components/` 里写 page-only 组件 | 抽象层级别错位 | 放 `src/pages/<id>/_components/` |
-| 在 `src/utils/` 里写 React Hook | 边界错位 | 放 `src/hooks/` |
-| 一个文件 export 5 个不相关的工具 | 命名失焦 | 拆成多文件,一个主题一个文件 |
-| `index.ts` 大量 `export *` 当 barrel | 影响 tree-shaking、循环依赖 | 显式 named export 需要的几个 |
-| 为消除一处 props drilling 直接引 zustand | 升级过度,徒增心智 | 用 React `Context` |
-| 服务端数据塞进 Context / store | 与 query 缓存形成双源,易漂移 | 一律走 `react-query` / `swr` |
-| 表单字段用一堆 `useState` 拼 | 字段越多越糟,校验散落 | `useForm` + `zodResolver`(见 [`forms-and-validation.md`](forms-and-validation.md)) |
-| 页面顶部 `import` 不 lazy + 无 Suspense | 首屏 bundle 爆炸 / 进入即崩 | `React.lazy` + Layout 挂 Suspense(见 [`routing-and-codesplit.md`](routing-and-codesplit.md)) |
-| 鉴权写在每个 page 顶部 | 散乱、易漏、UI 与 URL 两层不一致 | `src/routes/guards.tsx` 集中,URL 与 sidebar 两层都判 |
-| 全局没有 ErrorBoundary | 任何未捕获异常直接白屏 | App 根挂 `ErrorBoundary` + `reportError` |
-| 测试堆在顶层 `tests/` 目录 | 改文件忘记移动测试,易漂移 | `*.test.ts(x)` 就近紧邻被测文件 |
-| `alert()` / `window.location.href = ...` | 阻断、丑、丢状态 | `toast.error()` / `useNavigate()` |
+| 反模式                                            | 为什么禁                         | 应该怎么做                                                                                   |
+| ------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
+| `src/views/`、`src/screens/` 与 `src/pages/` 并存 | 同义层,认知爆炸                  | 二选一,统一叫 `pages/`                                                                       |
+| `src/api/` 与 `src/services/` 并存                | 同义层                           | 统一叫 `services/`                                                                           |
+| `src/utils/` 与 `src/helpers/` 并存               | 同义层                           | 统一叫 `utils/`                                                                              |
+| 在 `src/components/` 里写 page-only 组件          | 抽象层级别错位                   | 放 `src/pages/<id>/_components/`                                                             |
+| 在 `src/utils/` 里写 React Hook                   | 边界错位                         | 放 `src/hooks/`                                                                              |
+| 一个文件 export 5 个不相关的工具                  | 命名失焦                         | 拆成多文件,一个主题一个文件                                                                  |
+| `index.ts` 大量 `export *` 当 barrel              | 影响 tree-shaking、循环依赖      | 显式 named export 需要的几个                                                                 |
+| 为消除一处 props drilling 直接引 zustand          | 升级过度,徒增心智                | 用 React `Context`                                                                           |
+| 服务端数据塞进 Context / store                    | 与 query 缓存形成双源,易漂移     | 一律走 `react-query` / `swr`                                                                 |
+| 表单字段用一堆 `useState` 拼                      | 字段越多越糟,校验散落            | `useForm` + `zodResolver`(见 [`forms-and-validation.md`](forms-and-validation.md))           |
+| 页面顶部 `import` 不 lazy + 无 Suspense           | 首屏 bundle 爆炸 / 进入即崩      | `React.lazy` + Layout 挂 Suspense(见 [`routing-and-codesplit.md`](routing-and-codesplit.md)) |
+| 鉴权写在每个 page 顶部                            | 散乱、易漏、UI 与 URL 两层不一致 | `src/routes/guards.tsx` 集中,URL 与 sidebar 两层都判                                         |
+| 全局没有 ErrorBoundary                            | 任何未捕获异常直接白屏           | App 根挂 `ErrorBoundary` + `reportError`                                                     |
+| 测试堆在顶层 `tests/` 目录                        | 改文件忘记移动测试,易漂移        | `*.test.ts(x)` 就近紧邻被测文件                                                              |
+| `alert()` / `window.location.href = ...`          | 阻断、丑、丢状态                 | `toast.error()` / `useNavigate()`                                                            |
 
 ---
 
 ## 决策速查表
 
-| AI 收到的请求 | 文件应该放在 |
-| --- | --- |
-| 新增订单列表页 | `src/pages/orders/index.tsx` |
-| 新增订单状态徽章(跨页面用) | `src/components/OrderStatusBadge.tsx` |
-| 新增订单状态徽章(只在订单页用) | `src/pages/orders/_components/OrderStatusBadge.tsx` |
-| 新增"取消订单"接口调用 | `src/services/order.ts` 加 `cancelOrder` |
-| 新增"取消订单"的 mutation hook | `src/hooks/useCancelOrder.ts` |
-| 新增日期格式化函数 | `src/utils/format.ts`(先 grep 是否已存在) |
-| 新增鉴权拦截器 | `src/lib/http.ts` 加 interceptor |
-| 新增订单 domain 类型 | `src/types/order.ts` |
-| 跨少量组件分享当前用户 / 主题 | `src/contexts/UserContext.tsx`(用 React Context) |
-| 跨域高频全局态(首次需要) | `src/stores/useXxxStore.ts`(按需引 zustand,固定后只用一种) |
-| 列表 / 详情等服务端数据 | `src/hooks/useXxx.ts` 包 `react-query`,**不进** store / Context |
-| 新增"下单表单"(react-hook-form + zod) | `src/pages/orders/new/_components/CreateOrderForm.tsx` + `src/services/order.schema.ts` |
-| 跨页面复用表单(地址 / 客户搜索) | `src/components/forms/<Name>Form.tsx` + 对应 schema |
-| 新增路由 / 页面入口 | `src/routes/index.tsx` 注册 + `src/pages/<id>/index.tsx`(default export,被 `React.lazy` 引入) |
-| 新增鉴权 / 角色守卫 | `src/routes/guards.tsx` |
-| 全局 ErrorBoundary fallback 组件 | `src/components/GlobalErrorFallback.tsx` |
-| Sentry / 日志上报包装 | `src/lib/monitor.ts`(`reportError(err, extra?)`) |
-| 测试基础设施(msw handler / 自定义 render) | `src/test/handlers.ts` / `src/test/render.tsx` |
-| 纯函数 / service / hook 的测试 | 同目录 `<name>.test.ts(x)`(就近,不集中) |
+| AI 收到的请求                             | 文件应该放在                                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
+| 新增订单列表页                            | `src/pages/orders/index.tsx`                                                                  |
+| 新增订单状态徽章(跨页面用)                | `src/components/OrderStatusBadge.tsx`                                                         |
+| 新增订单状态徽章(只在订单页用)            | `src/pages/orders/_components/OrderStatusBadge.tsx`                                           |
+| 新增"取消订单"接口调用                    | `src/services/order.ts` 加 `cancelOrder`                                                      |
+| 新增"取消订单"的 mutation hook            | `src/hooks/useCancelOrder.ts`                                                                 |
+| 新增日期格式化函数                        | `src/utils/format.ts`(先 grep 是否已存在)                                                     |
+| 新增鉴权拦截器                            | `src/lib/http.ts` 加 interceptor                                                              |
+| 新增订单 domain 类型                      | `src/types/order.ts`                                                                          |
+| 跨少量组件分享当前用户 / 主题             | `src/contexts/UserContext.tsx`(用 React Context)                                              |
+| 跨域高频全局态(首次需要)                  | `src/stores/useXxxStore.ts`(按需引 zustand,固定后只用一种)                                    |
+| 列表 / 详情等服务端数据                   | `src/hooks/useXxx.ts` 包 `react-query`,**不进** store / Context                               |
+| 新增"下单表单"(react-hook-form + zod)     | `src/pages/orders/new/_components/CreateOrderForm.tsx` + `src/services/order.schema.ts`       |
+| 跨页面复用表单(地址 / 客户搜索)           | `src/components/forms/<Name>Form.tsx` + 对应 schema                                           |
+| 新增路由 / 页面入口                       | `src/routes/index.tsx` 注册 + `src/pages/<id>/index.tsx`(default export,被 `React.lazy` 引入) |
+| 新增鉴权 / 角色守卫                       | `src/routes/guards.tsx`                                                                       |
+| 全局 ErrorBoundary fallback 组件          | `src/components/GlobalErrorFallback.tsx`                                                      |
+| Sentry / 日志上报包装                     | `src/lib/monitor.ts`(`reportError(err, extra?)`)                                              |
+| 测试基础设施(msw handler / 自定义 render) | `src/test/handlers.ts` / `src/test/render.tsx`                                                |
+| 纯函数 / service / hook 的测试            | 同目录 `<name>.test.ts(x)`(就近,不集中)                                                       |

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

@@ -1,17 +1,19 @@
 # 表单与校验规范
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 4 的条件读取项。任务涉及表单时必须读取。
+
 > **核心约定**:表单状态用 `react-hook-form`,schema 用 `zod`,**永远不要**用一堆 `useState` 拼表单。
 
 ---
 
 ## 为什么选这个组合(业界事实标准)
 
-| 维度 | react-hook-form + zod | 多 `useState` 拼 |
-| --- | --- | --- |
-| 重渲染 | 字段级订阅,只渲染变化的字段 | 任意字段变化整个表单重渲染 |
-| 校验 | schema 驱动,前后端共用 | 散落在 onChange 里,易漏 |
-| 复杂表单 | resolver + watch + array fields 内建 | 自己实现一遍 |
-| TypeScript | 从 schema 自动推导类型 | 手写类型,易漂移 |
+| 维度       | react-hook-form + zod                | 多 `useState` 拼           |
+| ---------- | ------------------------------------ | -------------------------- |
+| 重渲染     | 字段级订阅,只渲染变化的字段          | 任意字段变化整个表单重渲染 |
+| 校验       | schema 驱动,前后端共用               | 散落在 onChange 里,易漏    |
+| 复杂表单   | resolver + watch + array fields 内建 | 自己实现一遍               |
+| TypeScript | 从 schema 自动推导类型               | 手写类型,易漂移            |
 
 参考:[React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) 是 2024+ React 生态默认组合,被 shadcn/ui、Vercel、Linear、Cal.com 等广泛采用。
 
@@ -141,12 +143,12 @@ export function CreateOrderForm() {
 
 ## 校验规则
 
-| 场景 | 写在哪 |
-| --- | --- |
-| 字段格式(邮箱 / 手机号 / URL) | zod schema(`z.string().email()`) |
-| 业务规则(库存检查 / 唯一性) | service 层,服务端返回错误 → hook 暴露 → UI 显示 |
-| 跨字段约束(开始日期 < 结束日期) | zod `.refine()` / `.superRefine()` |
-| 异步校验(用户名是否被占用) | `useQuery` + debounce,**不放 schema** |
+| 场景                            | 写在哪                                          |
+| ------------------------------- | ----------------------------------------------- |
+| 字段格式(邮箱 / 手机号 / URL)   | zod schema(`z.string().email()`)                |
+| 业务规则(库存检查 / 唯一性)     | service 层,服务端返回错误 → hook 暴露 → UI 显示 |
+| 跨字段约束(开始日期 < 结束日期) | zod `.refine()` / `.superRefine()`              |
+| 异步校验(用户名是否被占用)      | `useQuery` + debounce,**不放 schema**           |
 
 ### 反模式
 

package/src/teamix-evo-code-opentrek/reuse-first.md

@@ -1,5 +1,7 @@
 # Reuse-First · 组件 / 工具复用决策流
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 1 的强制读取项。AI 写任何新代码前必须先读完本文件并执行复用查询。
+
 > 在写**任何**新组件 / Hook / 工具函数之前,AI 必须按本流程跑一遍。"没找到现成的"必须是查询的结论,不能是默认假设。
 
 ---

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

@@ -1,6 +1,8 @@
 # 路由与代码分包规范
 
-> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兜底。
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 6 的条件读取项。任务涉及路由或页面入口时必须读取。
+
+> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兗底。
 
 ---
 
@@ -8,11 +10,11 @@
 
 teamix-evo console preset 默认 `react-router-dom@6`(Data Router 模式,业界主流)。
 
-| 候选 | 何时选 |
-| --- | --- |
-| `react-router-dom@6` Data Router | **默认**。中后台 / SPA / 多页应用 |
-| `@tanstack/react-router` | 类型安全要求极高、复杂 search params | (替换需在 ADR 记录)
-| 文件路由(Next.js / Remix) | 不在本 preset 范围 |
+| 候选                             | 何时选                               |
+| -------------------------------- | ------------------------------------ | ------------------- |
+| `react-router-dom@6` Data Router | **默认**。中后台 / SPA / 多页应用    |
+| `@tanstack/react-router`         | 类型安全要求极高、复杂 search params | (替换需在 ADR 记录) |
+| 文件路由(Next.js / Remix)        | 不在本 preset 范围                   |
 
 **一个项目只用一种**。已经用了 react-router 就不要混入 tanstack-router。
 
@@ -181,11 +183,11 @@ export function RoleGuard({
 
 每个项目**必须**有这三个页面,放在 `src/pages/_xxx/`(下划线前缀,表示非业务路由):
 
-| 路径 | 文件 | 触发场景 |
-| --- | --- | --- |
-| `*` (404) | `src/pages/_not-found/index.tsx` | 任何未匹配的 URL |
-| `/_forbidden` (403) | `src/pages/_forbidden/index.tsx` | 角色无权访问 |
-| `/_error` (500) | `src/pages/_error/index.tsx` | router `errorElement` 兜底 |
+| 路径                | 文件                             | 触发场景                   |
+| ------------------- | -------------------------------- | -------------------------- |
+| `*` (404)           | `src/pages/_not-found/index.tsx` | 任何未匹配的 URL           |
+| `/_forbidden` (403) | `src/pages/_forbidden/index.tsx` | 角色无权访问               |
+| `/_error` (500)     | `src/pages/_error/index.tsx`     | router `errorElement` 兜底 |
 
 未登录(401)由 `AuthGuard` 重定向到 `/login`,**不**单独建页面。
 
@@ -229,7 +231,7 @@ function OrderListPage() {
 import { useNavigate, Link } from 'react-router-dom';
 
 // 声明式(链接)
-<Link to={`/orders/${order.id}`}>查看</Link>
+<Link to={`/orders/${order.id}`}>查看</Link>;
 
 // 命令式(mutation success)
 const navigate = useNavigate();
@@ -249,15 +251,15 @@ mutation.mutate(values, {
 
 ## 反模式速查
 
-| 反模式 | 为什么禁 | 应该 |
-| --- | --- | --- |
-| 全部页面顶部 `import` 不 lazy | 首屏 bundle 爆炸 | `React.lazy` 每页 |
-| Lazy 但没 Suspense 兜底 | 进入页面报错 | Layout 挂一次 Suspense |
-| 鉴权写在每个 page 里 | 散乱、易漏 | 守卫组件 + 路由层 |
-| 路由声明分散在多处 | 难维护、易循环 | 唯一在 `src/routes/index.tsx` |
-| 列表筛选状态不进 URL | 刷新 / 分享 / 后退失效 | `useSearchParams` |
-| `window.location.href` 跳转 | 整页刷新 | `useNavigate` / `<Link>` |
-| 路由 path 写魔法字符串 | 改路径漏改 | 抽 `src/routes/paths.ts` 集中 |
+| 反模式                        | 为什么禁               | 应该                          |
+| ----------------------------- | ---------------------- | ----------------------------- |
+| 全部页面顶部 `import` 不 lazy | 首屏 bundle 爆炸       | `React.lazy` 每页             |
+| Lazy 但没 Suspense 兜底       | 进入页面报错           | Layout 挂一次 Suspense        |
+| 鉴权写在每个 page 里          | 散乱、易漏             | 守卫组件 + 路由层             |
+| 路由声明分散在多处            | 难维护、易循环         | 唯一在 `src/routes/index.tsx` |
+| 列表筛选状态不进 URL          | 刷新 / 分享 / 后退失效 | `useSearchParams`             |
+| `window.location.href` 跳转   | 整页刷新               | `useNavigate` / `<Link>`      |
+| 路由 path 写魔法字符串        | 改路径漏改             | 抽 `src/routes/paths.ts` 集中 |
 
 ---