@teamix-evo/skills 0.2.0 → 0.4.0

package/README.md

@@ -39,14 +39,24 @@ pnpm --filter @teamix-evo/skills scaffold:skill
 
 ## 消费态命令（CLI）
 
-由 `teamix-evo skills` 子命令族管理：
+由 `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 list        # 列出全部 skill（默认：已装✓ / 未装○）
-teamix-evo skills ls          # 别名
-teamix-evo skills list --installed  # 仅看已装
-teamix-evo skills update      # 升级到最新版（managed 策略保留你的自定义）
-teamix-evo skills uninstall   # 卸载
+teamix-evo skills add                # 全量装入 manifest 内所有 skill
+teamix-evo skills add <name...>      # 增量：仅装入指定 skill（可多个）
+teamix-evo skills list               # 列出全部 skill（默认：已装✓ / 未装○）
+teamix-evo skills update             # 升级到最新版（managed 策略保留你的自定义）
+teamix-evo skills sync [name...]     # 源 → IDE 镜像（漂移恢复用）
+teamix-evo skills doctor             # 检测源 / 镜像漂移
+teamix-evo skills uninstall          # 卸载（源 + 镜像 + lock）
+```
+
+### 全局装机（`--scope global`）
+
+```bash
+# 一行装到 ~/.qoder/skills/ 与 ~/.claude/skills/，元数据落到 ~/.teamix-evo-global/
+npx teamix-evo@latest skills add teamix-evo-manage --scope global --ide claude,qoder -y
+
+# 后续维护（update / uninstall 等）需 cd 到全局元数据根
+cd ~/.teamix-evo-global && npx teamix-evo skills update
 ```

package/_template/SKILL.md.hbs

@@ -1,6 +1,10 @@
 ---
 name: {{name}}
-description: {{description}}
+description: |
+  {{description}}
+  TRIGGER when: <列举正向触发场景 / 短语 / 文件路径模式;3-8 条;具体优于抽象>
+  SKIP: <显式列出**不该**自己上的相邻情形,至少 2 条;指明该走哪个 skill>
+  Coordinates with: <可选;声明同时激活的 sibling skill>
 ---
 
 # {{title}}
@@ -9,3 +13,12 @@ description: {{description}}
 <!-- teamix-evo:managed:end id="core" -->
 
 > 这部分内容由你（用户）自行编辑，CLI 升级时不会覆盖。
+
+<!--
+description 写法见 [ADR 0015](../../../docs/adr/0015-skill-description-trigger-contract.md):
+- 第一行:一句话能力声明,≤ 100 字符,以动词开头
+- TRIGGER when:正向枚举,具体优于抽象,中英文 + 文件 glob 三类信号都收
+- SKIP:负向边界,**强制**字段,显式让位给相邻 skill
+- Coordinates with:可选,声明协作而非抢活
+manifest.json 的 description 必须与本字段完全一致(单源)。
+-->

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://teamix-evo.dev/schema/skills-package/v1.json",
   "schemaVersion": 1,
   "package": "skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "engines": {
     "teamix-evo": ">=0.1.0"
   },
@@ -10,12 +10,85 @@
     {
       "id": "teamix-evo-manage",
       "name": "teamix-evo-manage",
-      "description": "Manage the teamix-evo toolkit (init / update / uninstall) inside the current project. Auto-trigger when the user mentions teamix-evo, design system installation, or related lifecycle tasks.",
-      "version": "0.1.0",
-      "source": "skills/teamix-evo-manage",
-      "ides": ["qoder", "claude"],
+      "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.",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-manage",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
       "updateStrategy": "managed",
-      "managedRegions": ["core"],
+      "managedRegions": [
+        "core"
+      ],
+      "template": false
+    },
+    {
+      "id": "teamix-evo-design-opentrek",
+      "name": "teamix-evo-design-opentrek",
+      "description": "Apply OpenTrek design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in an OpenTrek-variant project.\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘\"、\"create / review / refactor a page、screen、dashboard、template\"; intent involves layout structure, page-level information density, or multi-component composition; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-code-opentrek (run alongside when the screen also creates new files).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-design-opentrek",
+      "variant": "opentrek",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
+      "updateStrategy": "managed",
+      "managedRegions": [
+        "core"
+      ],
+      "template": false
+    },
+    {
+      "id": "teamix-evo-code-opentrek",
+      "name": "teamix-evo-code-opentrek",
+      "description": "Enforce teamix-evo coding conventions in OpenTrek-variant consumer apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-opentrek); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-code-opentrek",
+      "variant": "opentrek",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
+      "updateStrategy": "managed",
+      "managedRegions": [
+        "core"
+      ],
+      "template": false
+    },
+    {
+      "id": "teamix-evo-design-uni-manager",
+      "name": "teamix-evo-design-uni-manager",
+      "description": "Apply Uni-Manager design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in a Uni-Manager-variant project (专有云 / 混合云 / 云管平台 / hybrid cloud console).\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘 / 控制台首页\"、\"create / review / refactor a page、screen、dashboard、console、admin template\"; intent involves layout structure, page-level information density, or multi-component composition for hybrid-cloud / multi-tenant / multi-region scenarios; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-code-uni-manager (run alongside when the screen also creates new files).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-design-uni-manager",
+      "variant": "uni-manager",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
+      "updateStrategy": "managed",
+      "managedRegions": [
+        "core"
+      ],
+      "template": false
+    },
+    {
+      "id": "teamix-evo-code-uni-manager",
+      "name": "teamix-evo-code-uni-manager",
+      "description": "Enforce teamix-evo coding conventions in uni-manager (hybrid-cloud / multi-tenant console) consumer apps — reuse-first against `@teamix-evo/ui` registry + `biz-ui/uni-manager` (um-topbar / CloudBadge), API code under `src/services/` with tenant / region context propagation, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook in a hybrid-cloud / 专有云 / 多租户 / 多区域 console; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed uni-manager-variant project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-uni-manager); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-uni-manager (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).",
+      "version": "0.2.0",
+      "source": "src/teamix-evo-code-uni-manager",
+      "variant": "uni-manager",
+      "ides": [
+        "qoder",
+        "claude"
+      ],
+      "updateStrategy": "managed",
+      "managedRegions": [
+        "core"
+      ],
       "template": false
     }
   ]

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "@teamix-evo/skills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Skills (AI IDE capabilities) for Teamix Evo",
   "type": "module",
   "files": [
     "manifest.json",
     "_data.json",
-    "skills",
+    "src",
     "_template"
   ],
   "devDependencies": {
     "@clack/prompts": "^0.8.0",
     "tsx": "^4.0.0",
-    "@teamix-evo/registry": "0.2.0"
+    "@teamix-evo/registry": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
     "validate": "tsx scripts/validate-skills.ts",

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

@@ -0,0 +1,92 @@
+---
+name: teamix-evo-code-opentrek
+description: |
+  Enforce teamix-evo coding conventions in OpenTrek-variant consumer apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.
+  TRIGGER when: user asks to "新增 / 重构 / 写一个" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like "create a CRUD page"、"add an API call"、"extract a hook"、"refactor this fetch"、"调一下接口"、"加个组件"、"加个按钮"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.
+  SKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-opentrek); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.
+  Coordinates with: teamix-evo-design-opentrek (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).
+---
+
+# teamix-evo-code-opentrek
+
+This skill bundles the **AI-readable engineering conventions** for OpenTrek-variant consumer business apps that consume `@teamix-evo/*` packages. It complements [`teamix-evo-design-opentrek`](../teamix-evo-design-opentrek/SKILL.md) — design tells AI _what a screen should look like_; this skill tells AI _where the code should live and what to reuse before writing new code_.
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## When to use
+
+Activate this skill whenever AI is about to **write or refactor code** inside a consumer app that has installed teamix-evo. Common signals:
+
+- "新增一个 xxx 页面 / 列表页 / 详情页"
+- "加一个 xxx 接口 / 调用 xxx API"
+- "写一个 xxx 组件"
+- "把这段重构一下"
+- "create a CRUD page for orders"
+- "add an API call to fetch users"
+- Any time AI is about to create a new file under `src/pages/`、`src/components/`、`src/services/`、`src/hooks/`
+
+If the task is purely about _visual design_ of a screen (layout / colors / spacing), use [`teamix-evo-design`](../teamix-evo-design/SKILL.md) instead — or run both in tandem.
+
+## 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.
+
+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.
+
+## Inputs the user provides
+
+- Intent: "add a page", "add a service call", "refactor X", "extract a hook", etc.
+- Optional: domain entity (`order`、`user`、`tenant`、`workflow`)
+- Optional: existing file the change should land near
+
+## Outputs
+
+- Code placed under the conventional path (`src/pages/<id>/`、`src/services/<domain>.ts`、…)
+- Reuse decisions explicitly logged ("reused `Button` from `@teamix-evo/ui`" / "no match found, wrote a new `OrderCard` under `src/components/`")
+- Pass / fail status against [`checklist.md`](checklist.md)
+
+## How to invoke (typical flow)
+
+1. Parse user intent → identify which artifact is being created (page / component / service / hook / util / form / route)
+2. Read [`reuse-first.md`](reuse-first.md) and run the reuse query (MCP first, then local grep)
+3. Read [`file-structure.md`](file-structure.md) to pick the destination directory
+4. If the change touches network / backend, read [`api-layering.md`](api-layering.md)
+5. If the change involves a form, read [`forms-and-validation.md`](forms-and-validation.md)
+6. If the change adds a page / data hook, read [`error-and-loading.md`](error-and-loading.md) for fallback / Skeleton / toast wiring
+7. If the change adds a route or page entry, read [`routing-and-codesplit.md`](routing-and-codesplit.md)
+8. Decide test coverage per [`testing.md`](testing.md); write `*.test.ts(x)` next to source
+9. Write the code; cite each reuse / new-write decision in the response
+10. Run through [`checklist.md`](checklist.md); list pass / fail explicitly
+
+## Files in this skill
+
+| File                                                   | Purpose                                                                                                              |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`reuse-first.md`](reuse-first.md)                     | Decision flow for reusing existing components / utilities before writing new ones                                    |
+| [`file-structure.md`](file-structure.md)               | Top-level `src/` folder layout、ownership、import boundaries、naming、global-state tier (useState → Context → store) |
+| [`api-layering.md`](api-layering.md)                   | Where API code lives (`src/services/`)、how data flows from service → hook → component                               |
+| [`forms-and-validation.md`](forms-and-validation.md)   | `react-hook-form` + `zod` patterns、schema location、submit/error wiring                                             |
+| [`error-and-loading.md`](error-and-loading.md)         | Global / page ErrorBoundary、react-query three-state、Suspense、toast、reportError                                   |
+| [`routing-and-codesplit.md`](routing-and-codesplit.md) | `React.lazy` per page、guards、404/403/500 fallback、search-params state、Suspense placement                         |
+| [`testing.md`](testing.md)                             | `vitest` + RTL + msw、co-located tests、what is mandatory vs recommended                                             |
+| [`checklist.md`](checklist.md)                         | Multi-section self-review before declaring done                                                                      |
+
+## 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.
+
+## Why these conventions
+
+- **Single source for UI** — `@teamix-evo/ui` is a source-injected component library (89 entries). Re-implementing `Button`、`Dialog`、`DataTable` etc. inside the consumer app fragments the design system and breaks token discipline.
+- **Stable seams for change** — keeping API calls in `src/services/` means a backend rename only edits one file; keeping components free of fetch logic means they stay easy to test and reuse.
+- **Predictable file location** — when AI (or a new teammate) opens an unfamiliar consumer app, the directory shape is the same across all teamix-evo-bootstrapped projects.
+
+<!-- teamix-evo:managed:end -->

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

@@ -0,0 +1,225 @@
+# API 数据层规范
+
+> **核心原则**:组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`,通过 `src/hooks/` 暴露给组件。
+
+---
+
+## 三层结构
+
+```
+┌────────────────────────────────────┐
+│  src/pages/, src/components/       │  组件层:消费 hook,渲染 UI
+│  - 不调用 fetch / axios            │
+│  - 不直接读 process.env             │
+│  - 不拼 URL                        │
+└──────────────┬─────────────────────┘
+               │ 仅通过 hook
+               ▼
+┌────────────────────────────────────┐
+│  src/hooks/use<Domain>*.ts         │  Hook 层:状态管理 + 缓存(react-query 等)
+│  - 包装请求生命周期(loading/error) │
+│  - 处理缓存 / 重试 / 失效           │
+│  - 不写具体的 URL / payload 拼装    │
+└──────────────┬─────────────────────┘
+               │ 调用纯函数
+               ▼
+┌────────────────────────────────────┐
+│  src/services/<domain>.ts          │  Service 层:请求纯函数
+│  - 输入参数 → 输出 Promise<T>      │
+│  - 拼 URL / 序列化 / 反序列化       │
+│  - 不依赖 React                    │
+└──────────────┬─────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────┐
+│  src/lib/http.ts                   │  传输层:axios / fetch wrapper
+│  - 鉴权 / baseURL / 错误归一化      │
+│  - 全局 interceptor                │
+└────────────────────────────────────┘
+```
+
+---
+
+## §1 · `src/services/` 约定
+
+### 文件组织
+
+按**领域**(domain)拆,**不**按 HTTP 动词拆。
+
+```
+src/services/
+├── order.ts          # 订单领域:list / get / create / update / cancel
+├── user.ts           # 用户领域
+├── tenant.ts         # 租户领域
+└── index.ts          # 统一 re-export(可选)
+```
+
+❌ 不要按动词拆:`getOrders.ts` / `createOrder.ts` / `updateOrder.ts` —— 会爆文件数。
+
+### 函数签名约定
+
+```ts
+// src/services/order.ts
+import { http } from '@/lib/http';
+import type { Order, OrderListParams, CreateOrderInput } from '@/types/order';
+
+export async function listOrders(params: OrderListParams): Promise<Order[]> {
+  const { data } = await http.get('/api/orders', { params });
+  return data.list;
+}
+
+export async function getOrder(id: string): Promise<Order> {
+  const { data } = await http.get(`/api/orders/${id}`);
+  return data;
+}
+
+export async function createOrder(input: CreateOrderInput): Promise<Order> {
+  const { data } = await http.post('/api/orders', input);
+  return data;
+}
+```
+
+要点:
+- **纯函数**(不依赖 React 上下文,可以在 SSR / Node 测试中单独跑)
+- **类型来自 `src/types/`**,不要在 service 文件里就地定义 domain 类型
+- **错误不在 service 层处理** —— 抛出去给 hook / 全局 interceptor 处理(归一化在 `src/lib/http.ts`)
+- **不写 console.log / 业务弹窗** —— 是数据通道,不是 UI 通道
+
+### 反模式
+
+- ❌ `fetch('https://api.example.com/...')` 写死 host(应该用 `http` wrapper)
+- ❌ service 函数返回 `{ loading, data, error }`(那是 hook 该做的)
+- ❌ 在 service 里 `import { toast } from 'sonner'` 弹通知(归到 hook 或全局 interceptor)
+- ❌ 一个 service 函数同时拼 URL、做业务计算、改全局 store
+
+---
+
+## §2 · `src/hooks/` 约定
+
+### 命名
+
+- Query 类:`useOrderList`、`useOrder(id)`、`useUserProfile`
+- Mutation 类:`useCreateOrder`、`useCancelOrder`、`useUpdateUser`
+
+### 实现(以 `@tanstack/react-query` 为例)
+
+```ts
+// src/hooks/useOrderList.ts
+import { useQuery } from '@tanstack/react-query';
+import { listOrders } from '@/services/order';
+import type { OrderListParams } from '@/types/order';
+
+export function useOrderList(params: OrderListParams) {
+  return useQuery({
+    queryKey: ['orders', params],
+    queryFn: () => listOrders(params),
+    staleTime: 30_000,
+  });
+}
+```
+
+```ts
+// src/hooks/useCreateOrder.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { createOrder } from '@/services/order';
+
+export function useCreateOrder() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: createOrder,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['orders'] }),
+  });
+}
+```
+
+### 反模式
+
+- ❌ Hook 里再次拼 URL(违反"service 拼 URL"边界)
+- ❌ 一个 hook 调多个 service 把数据缝合 —— 缝合应该在 service 层(返回组合好的 DTO)
+- ❌ Hook 里写业务跳转 / 路由切换 —— 由组件接 `mutation.onSuccess` callback 处理
+
+---
+
+## §3 · `src/lib/http.ts` 约定
+
+**全局只能有一份 http 实例**。提供:
+
+- `baseURL`(从 env)
+- 鉴权 header 注入
+- 错误归一化(把后端 `{ code, message }` 变成 `Error` 抛出)
+- 请求 ID / trace header
+- (可选)mock 拦截
+
+```ts
+// src/lib/http.ts
+import axios from 'axios';
+
+export const http = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE,
+  timeout: 15_000,
+});
+
+http.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token');
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+http.interceptors.response.use(
+  (res) => res,
+  (err) => {
+    const message = err.response?.data?.message ?? err.message;
+    return Promise.reject(new Error(message));
+  },
+);
+```
+
+### 反模式
+
+- ❌ 在 service 里再 `import axios` 直接用(应该用 `http`)
+- ❌ 多份 `http` 实例(分包拆 fetch 应该用一个 instance + 不同 baseURL config)
+- ❌ 把鉴权放在每个 service 里手动加 header
+
+---
+
+## §4 · 类型分层
+
+```
+src/types/
+├── order.ts          # Order、OrderStatus、OrderListParams、CreateOrderInput
+├── user.ts
+└── api.ts            # 通用 ApiResponse<T>、Pagination<T>
+```
+
+- **Domain 类型**(如 `Order`)放 `src/types/<domain>.ts`,被 service / hook / component 共享
+- **API 入参 / 出参类型**:与 domain 类型分开命名(`OrderListParams` vs `Order`)
+- **不要**让组件 props 类型直接 `import` service 的内部类型 —— 走 `src/types/` 中转
+
+---
+
+## §5 · 何时可以打破
+
+某些场景**允许**绕过本规范,但需要在代码注释里说明原因:
+
+| 场景 | 允许 |
+| --- | --- |
+| 静态资源 fetch(读 `public/` 下的 json) | 组件直接 `fetch` 可,不用进 service |
+| 第三方 SDK(地图、支付)有自己的客户端 | 包装层放 `src/lib/<sdk>.ts`,不强制走 services |
+| 一次性的诊断 / 调试代码 | 临时 fetch 可,但 PR 合并前必须清理或归位 |
+
+---
+
+## AI 必须输出的层级日志
+
+完成涉及网络 / 后端的改动时,AI 必须在响应里写明:
+
+```
+## 数据层改动
+
+- src/types/order.ts: 新增 `OrderListParams`、`OrderStatus`
+- src/services/order.ts: 新增 `listOrders`、`cancelOrder`(纯函数,使用 `@/lib/http`)
+- src/hooks/useOrderList.ts: 包 `useQuery`,key=['orders', params]
+- src/pages/orders/index.tsx: 仅消费 `useOrderList`,不直接 fetch
+```
+
+每一层都点到名,才算合规。