@teamix-evo/skills 0.3.0 → 0.5.0

package/src/teamix-evo-manage/SKILL.md

@@ -0,0 +1,289 @@
+---
+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`.
+  TRIGGER 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`.
+  SKIP: 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`.
+  Coordinates 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.
+---
+
+# teamix-evo-manage
+
+Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenarios:
+
+1. Fuzzy init → ask user to pick a tokens variant.
+2. Named-variant init → infer variant from business name, run scaffold directly.
+3. AI coding install on existing repo (no scaffold step).
+4. Update detection — only refresh what's already installed.
+5. Uninstall.
+6. Placeholder → real UI migration loop (post-`npm create teamix-evo`).
+
+## 安装方式
+
+本 skill 是 **entry skill**(lifecycle orchestrator),manifest 里声明 `scope: "global"`。**推荐全局安装一次**:
+
+```bash
+npx teamix-evo skills add teamix-evo-manage --scope global
+```
+
+`skills add`(默认 project scope)与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过(ADR 0033)。如果用户在项目级显式 `skills add teamix-evo-manage --scope project`,CLI 给出"推荐 global"warning 但仍装入(用户自负责),代价是后续 IDE 会同时识别全局与项目两份副本。
+
+## 自助升级
+
+升级到最新版本(任何目录可跑 — 自动找全局 meta root):
+
+```bash
+npx teamix-evo@latest skills update                       # 全部已装
+npx teamix-evo@latest skills update teamix-evo-manage     # 只升 manage 一个
+npx teamix-evo@latest skills update --dry-run             # 预览,不写盘
+```
+
+`@latest` 让 npx 拉最新 CLI + 最新 `@teamix-evo/skills` 包。命令头部会打印 CLI 版本与 skills 包版本,方便排查 npx cache 与包不同步的问题。
+
+升级范围(ADR 0035 双闸):
+
+- 只更新 lock 里**已装**的 skill — 新 skill 用 `skills add <id>` 显式加入,不会被 update 自动装上
+- 只更新 scope 与当前 install scope 一致的 skill — 项目级 update 不会动全局 manage,反之亦然
+- 版本完全一致时短路,不重写源(managed 区域用户改动不被来回备份)
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## 决策树(动手前必看)
+
+```text
+用户的指令命中本 skill
+  ├── 目录里有 `.teamix-evo/`?
+  │     是 ──▶ 4 (更新) / 5 (卸载)
+  │     否 ──▶ 继续
+  ├── 用户说出业务名 / variant?
+  │     是 ──▶ 2 (具名变体初始化) — 用「业务名→variant 映射表」推断
+  │     否 ──▶ 继续
+  ├── 目录是空的(或只有 .git / README.md)?
+  │     是 ──▶ 1 (模糊初始化) — 询问 variant 后转 2
+  │     否 ──▶ 3 (AI coding 接入) — 跳过 scaffold,只跑 tokens/skills/ui init
+```
+
+## 业务名 → variant 映射
+
+> 用户表述业务时,按下表锁定 variant,**不再询问**。表外的关键词必须询问。
+
+| 用户原话(中/英)                                                               | variant       |
+| ----------------------------------------------------------------------------- | ------------- |
+| 云管 / 云管控制台 / 云管项目 / 云管工程 / uni-manager / unimanager / 统一管理 | `uni-manager` |
+| op / opentrek / OpenTrek / 探索者                                             | `opentrek`    |
+| _未提及业务,只说"做一个工程"_                                                 | **询问**      |
+
+校验:`npx teamix-evo tokens list-variants` 列出当前 `@teamix-evo/tokens` 包内所有变体;若上表中的关键词指向尚未发布的变体,先告知用户该 variant 还未上线。
+
+## CLI 命令面(完整)
+
+CLI 二进制名 `teamix-evo`,所有命令都从这里发起。命令名以 `tokens`、`skills`、`ui`、`biz-ui`、`templates`、`logs` 六个 group 组织。
+
+### Tokens(`@teamix-evo/tokens`)
+
+| 目标         | 命令                                                                |
+| ------------ | ------------------------------------------------------------------- |
+| 初始化       | `npx teamix-evo tokens init <variant>`(`<variant>` 必填,无默认)     |
+| 列出可选变体 | `npx teamix-evo tokens list-variants`                               |
+| 列出已装资源 | `npx teamix-evo tokens list`                                        |
+| 升级         | `npx teamix-evo tokens update`(stub — 见 [ADR 0019](docs/adr/0019)) |
+| 卸载         | `npx teamix-evo tokens uninstall [-y] [--keep-files]`               |
+
+- **`<variant>` 必填**。`tokens init` 之前必须先确定 variant(决策树或业务名映射)。
+- `tokens update` 当前是 stub;权宜方案:删除 `.teamix-evo/tokens-lock.json` 与根 `tokens/`,重跑 `tokens init <variant>`。
+- 资源分类(frozen / regenerable / managed)详见 [ADR 0003](docs/adr/0003-update-strategy-tri-state.md):`tokens.overrides.css` 是 `frozen`,用户改写永不被覆盖;`tokens.theme.css` / `tokens/base.tokens.json` 是 `regenerable`,每次 `update` 完整重写。ADR 0020 之后,`tokens init` 不再向工程根落 `AGENTS.md` / `DESIGN.md` 等 `managed` 文件 —— 设计纲领由 `teamix-evo-design-<variant>` skill 自包含。
+
+### Skills(`@teamix-evo/skills`)
+
+| 目标     | 命令                                                 |
+| -------- | ---------------------------------------------------- |
+| 自举     | `npx teamix-evo skills init`                         |
+| 增量装   | `npx teamix-evo skills add <name...>`                |
+| 列出全部 | `npx teamix-evo skills list`(alias `ls`)             |
+| 列出已装 | `npx teamix-evo skills list --installed`             |
+| 升级     | `npx teamix-evo skills update [name...] [--dry-run]` |
+| 卸载     | `npx teamix-evo skills uninstall [-y]`               |
+| 漂移检测 | `npx teamix-evo skills doctor`                       |
+| 重新镜像 | `npx teamix-evo skills sync [name...]`               |
+
+> 升级语义见 ADR 0035 双闸:仅升级 lock 已装且 scope 匹配的 skill;version 完全一致时短路;新 skill 用 `skills add <id>` 显式加入。
+
+verb 分工(ADR 0034):
+
+- **`skills init`**(无 ids):自举 — 按当前 tokens variant + install scope 装 manifest 里全部符合条件的 skill。已装的工程再跑会返回 `already-initialized`。
+- **`skills add <name...>`**(必填 ids):增量 — 只装列出的 skill;已装的跳过(用 `update` 刷新)。不传 id 会被 commander 拒绝并输出 help。
+
+首次交互式(无既有配置且无 flag 时):
+
+1. 多选 IDE:**Qoder** / **Claude Code**(默认两者,至少一个)。等价 `--ide qoder,claude`。
+2. Scope:**project**(默认,`.qoder/.claude` 在 cwd)/ **global**(`~/.qoder/~/.claude`)。等价 `--scope project|global`。
+
+源镜像模型([ADR 0013](docs/adr/0013)):规范副本在 `.teamix-evo/skills/`,IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。`doctor` 检测漂移,`sync` 重镜像(不升版本)。
+
+### UI 组件(`@teamix-evo/ui`)
+
+| 目标       | 命令                                   |
+| ---------- | -------------------------------------- |
+| 初始化     | `npx teamix-evo ui init [-y]`          |
+| 增加 entry | `npx teamix-evo ui add <id...>`        |
+| 列出 entry | `npx teamix-evo ui list [--installed]` |
+
+- `ui init` 写 `.teamix-evo/config.json` 的 `packages.ui`(aliases / iconLibrary / tsx / rsc)。可交互元素的 `cursor: pointer` 由组件源码内显式声明,不再有全局 `preferences.css` —— 见 [ADR 0023](docs/adr/0023-cursor-pointer-explicit-in-component-source.md)
+- `ui add` 自动解析 `registryDependencies`,组件源码写入 `src/components/ui/<id>.tsx`(frozen),并报告还需 `pnpm add` 的 npm 包。
+- 没有 `ui upgrade` 子命令 — 组件升级走 `ui add` 覆盖即可。
+
+### 业务组件(`@teamix-evo/biz-ui`)
+
+| 目标       | 命令                                                 |
+| ---------- | ---------------------------------------------------- |
+| 列出变体   | `npx teamix-evo biz-ui list-variants`                |
+| 增加 entry | `npx teamix-evo biz-ui add <id...> --variant <name>` |
+
+- `--variant <name>` 必填(没有 auto-detect)。
+- [ADR 0014](docs/adr/0014-ui-biz-ui-templates-tier.md):`tokens` / `biz-ui` / `templates` 共享 variant 名空间,与 `tokens init` 选定的 variant 一致。
+
+### 页面模板(`@teamix-evo/templates`)
+
+> ⚠️ **AI 默认不主动调用本 group**(见 [ADR 0031](docs/adr/0031-skill-templates-decoupling.md))。页面骨架由 `teamix-evo-design-<variant>` skill 的 `patterns/*.md` 驱动 ui + biz-ui 拼装;仅在用户**显式**说"用 templates 包装 frozen 骨架"时,才跳转本 group 命令。
+
+| 目标       | 命令                                                    |
+| ---------- | ------------------------------------------------------- |
+| 列出变体   | `npx teamix-evo templates list-variants`                |
+| 增加 entry | `npx teamix-evo templates add <id...> --variant <name>` |
+
+同 `biz-ui` 的变体规则。模板源码写入 `src/templates/<id>.tsx`(frozen)。
+
+### 日志(`@teamix-evo/logs`)
+
+| 目标       | 命令                                |
+| ---------- | ----------------------------------- |
+| 分析调用链 | `npx teamix-evo logs analyze [...]` |
+
+- 读 vibe-logger 输出 `.teamix-evo/logs/ai/**/*.jsonl`,做 AI 调用链可视化。诊断 `runTokensInit` / `runUiAdd` 等编排流程时用。
+
+## 场景 1 · 模糊初始化
+
+**触发**:用户说"初始化一个项目 / 工程",未指明 variant。
+
+**步骤**:
+
+1. 确认目录(默认 `./<project-name>`,可由用户改)。
+2. 列出 variants(`tokens list-variants` 的输出),让用户选(`AskUserQuestion`):
+   - OpenTrek(opentrek):AI 副驾驶 / 通用中后台
+   - Uni-Manager(uni-manager):云资源管理(大屏 / 拓扑 / 7 类 AI 场景)
+3. 转场景 2,带上选定 variant 直跑。
+
+## 场景 2 · 具名变体初始化(空目录 → 完整工程)
+
+**触发**:用户在「业务名 → variant 映射」中能锁定 variant,或场景 1 询问后得到答复。
+
+**唯一命令**:
+
+```bash
+npm create teamix-evo@latest <dir> --variant <name>
+# 或 pnpm create teamix-evo <dir> --variant <name>
+```
+
+`create-teamix-evo` 的 `console` preset(默认且当前唯一)会自动一站式落地:
+
+| 阶段 | 产物                                                                                                       |
+| ---- | ---------------------------------------------------------------------------------------------------------- |
+| 1    | Vite + React + TS scaffold(`src/`、`vite.config.ts` 等)                                                    |
+| 2    | `tokens init <variant>` → 根 `tokens/` 目录(`tokens.theme.css` / `tokens.overrides.css`)                   |
+| 3    | `skills add design-<variant> code-<variant>` → 项目级装 2 个 variant 内容 skill(manage 不在内,见 ADR 0033) |
+| 4    | `ui init` → `.teamix-evo/config.json`                                                                      |
+| 5    | `ui add` → 真组件源码(button / card / input / form / table 等)                                             |
+| 6    | `lint init` → ESLint + Stylelint 配置                                                                      |
+
+> 提示:`teamix-evo-manage` 是 entry skill,推荐**全局**装一次(`npx teamix-evo skills add teamix-evo-manage --scope global`)。create CLI 不会装它到 project,scaffold 完成后的 next-steps 会提示用户。
+
+**完成后告知用户**:
+
+```bash
+cd <dir>
+pnpm dev          # 立刻可跑
+pnpm typecheck    # 验证零类型错误
+```
+
+## 场景 3 · AI coding 接入(现有仓库)
+
+**触发**:用户已有 React/TS/Vite 仓库(已 `npm install` / 有 `package.json`),只想装 AI coding 体系。
+
+**关键判断**:
+
+- 跳过 scaffold(用户已有 `package.json`、`vite.config.ts`、`src/`)。
+- `npm create teamix-evo` 会拒绝非空目录(除非 `--force` 且不含 `.teamix-evo/`),所以这里改用单包 CLI。
+
+**步骤**:
+
+```bash
+# 1. 确定 variant(若用户未说,按映射表 / 询问)
+npx teamix-evo tokens list-variants
+npx teamix-evo tokens init <variant>          # 装 tokens(写 tokens/ 与 .teamix-evo/tokens-lock.json)
+
+# 2. 自举 skills(同源 Qoder + Claude;manage 是 global-only,自举自动跳过 — ADR 0033 + 0034)
+npx teamix-evo skills init                    # 项目级装 design-<variant> + code-<variant>,默认两个 IDE 镜像
+
+# 3. 装 ui 配置
+npx teamix-evo ui init -y
+npx teamix-evo ui add button                  # 可选:先装一个真组件验证
+```
+
+**结束时告诉用户**:
+
+- 已装的 skill 列表(从 `skills list --installed`)、tokens variant、ui aliases。
+- 接下来怎么用:写新页面就触发 `teamix-evo-design-opentrek` / `teamix-evo-code-opentrek`。
+- 若全局尚未安装 entry skill,补一句:`npx teamix-evo skills add teamix-evo-manage --scope global`(ADR 0033)。
+
+## 场景 4 · 更新检测
+
+**触发**:用户说"升级 / 看看哪些要升级 / update teamix-evo"。
+
+**步骤**:
+
+1. 读 `.teamix-evo/config.json` 的 `packages` 字段,看哪些已装(tokens / skills / ui / biz-ui / templates)。
+2. 对每个已装包,跑对应 `list --installed`(若有该子命令)与上游 manifest 比对版本。
+3. 仅对**已装**的包做 update:
+   - `npx teamix-evo tokens update`(stub — 仍提示用户清 + 重装)
+   - `npx teamix-evo skills update [name...] [--dry-run]` — 双闸 + version 短路 + 可选限定 id(ADR 0035)。先 `--dry-run` 给用户看清单,确认后再无 flag 跑一遍真升级
+   - 没有 `ui update`(组件升级走 `ui add` 覆盖即可)
+
+**不要**给未安装的包做 install — 那是场景 2/3 的事。
+
+## 场景 5 · 卸载
+
+**触发**:用户说"卸载 teamix-evo / remove the design system"。
+
+| 范围                                          | 命令                                                  |
+| --------------------------------------------- | ----------------------------------------------------- |
+| Tokens                                        | `npx teamix-evo tokens uninstall [-y] [--keep-files]` |
+| Skills                                        | `npx teamix-evo skills uninstall [-y]`                |
+| (UI 不提供卸载,组件源码用户拥有 → 用户手动删) |                                                       |
+
+`tokens uninstall` 默认保留 `managed` 文件以保护用户编辑;`--keep-files` 完全保留物理文件,只清 manifest。
+
+## 配置文件(信息性)
+
+| 路径                          | 所有者 | 说明                                    |
+| ----------------------------- | ------ | --------------------------------------- |
+| `.teamix-evo/config.json`     | CLI    | 已装包清单、版本、IDE / scope           |
+| `.teamix-evo/manifest.json`   | CLI    | 已装资源 ledger;diff / uninstall 的依据 |
+| `tokens/tokens.overrides.css` | 用户   | 业务自定义 token 覆盖(`frozen`)         |
+
+**不要**手编 `config.json` / `manifest.json`,用对应 CLI 子命令。
+
+## 常见错误与恢复路径(P8 — failures must be observable)
+
+| 症状                                               | 原因                                        | 恢复路径                                           |
+| -------------------------------------------------- | ------------------------------------------- | -------------------------------------------------- |
+| `Unknown tokens variant "..."`                     | 拼写错误或上游未发布该 variant              | `npx teamix-evo tokens list-variants` 列出当前可用 |
+| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录     | 改走场景 4(更新)或场景 3(增量装)                   |
+| `UI not initialized`(跑 `ui add` 时)               | 未先跑 `ui init`                            | `npx teamix-evo ui init -y` 然后再 `ui add`        |
+| Vite/Tailwind 跑起来没样式                         | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序             |
+| Skills 在 IDE 不触发                               | `.qoder/skills/` 或 `.claude/skills/` 漂移  | `npx teamix-evo skills doctor` 然后 `skills sync`  |
+
+<!-- teamix-evo:managed:end id="core" -->
+
+## Notes for the user
+
+> 这部分内容由你自由编辑。CLI 升级时只会替换 `id="core"` 区段,不会动这里的笔记。

package/skills/teamix-evo-coding-conventions/SKILL.md

@@ -1,92 +0,0 @@
----
-name: teamix-evo-coding-conventions
-description: |
-  Enforce teamix-evo coding conventions in consumer business 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-rules); 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-rules (run alongside when the change also creates a UI screen — design-rules handles the visual side, this skill handles file placement and reuse).
----
-
-# teamix-evo-coding-conventions
-
-This skill bundles the **AI-readable engineering conventions** for consumer business apps that consume `@teamix-evo/*` packages. It complements [`teamix-evo-design-rules`](../teamix-evo-design-rules/SKILL.md) — design-rules 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-rules`](../teamix-evo-design-rules/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-rules`](../teamix-evo-design-rules/SKILL.md) — visual / interaction rules for screen generation. Run **alongside** this skill when the task includes UI; this skill never overrides design-rules 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/skills/teamix-evo-coding-conventions/file-structure.md

@@ -1,273 +0,0 @@
-# 业务工程目录约定
-
-> 业内主流 React/Vite 业务工程的标准目录骨架。本文件是 AI 决定"新建文件应该放在哪"的唯一参考。
-
----
-
-## 顶层 `src/` 骨架
-
-```
-src/
-├── pages/            # 路由页面(每个目录对应一条路由)
-├── components/       # 跨页面复用的业务组件
-├── services/         # 后端通信(纯函数,见 api-layering.md)
-├── hooks/            # 自定义 Hook(包含数据 hook、UI hook)
-├── contexts/         # React Context(跨子树共享、低频更新的全局态)
-├── stores/           # 高频全局态(zustand / jotai / redux,首次需要时引入,只用一种)
-├── types/            # Domain / API 类型声明(.ts 仅类型,无运行时)
-├── utils/            # 纯函数工具(无 React、无副作用)
-├── lib/              # 三方 SDK 包装、http 实例、环境配置、monitor
-├── routes/           # 路由配置 + 守卫(若用 react-router 集中式声明)
-├── layouts/          # 应用级 / 区域级布局(ConsoleLayout、AuthLayout)
-├── test/             # 测试基础设施(setup.ts、handlers.ts、render.tsx、fixtures/)
-├── styles/           # 全局样式 / token 覆盖(尽量少)
-├── assets/           # 图片 / 字体 / 静态文件
-├── locales/          # i18n 资源(可选)
-├── main.tsx          # 应用入口
-└── App.tsx           # 根组件
-```
-
-> 没列出的目录按需补,但**不要**新增同义层(如同时有 `utils/` 和 `helpers/`、`api/` 和 `services/`、`views/` 和 `pages/`)。`*.test.ts(x)` 文件**就近**放在被测文件同目录,**不要**集中堆到顶层 `tests/`(见 [`testing.md`](testing.md))。
-
----
-
-## 各目录职责与边界
-
-### `src/pages/`
-
-**职责**:路由页面。一个目录 = 一条路由。
-
-```
-src/pages/
-├── orders/
-│   ├── index.tsx            # 列表页(/orders)
-│   ├── [id].tsx             # 详情页(/orders/:id),命名按路由方案
-│   ├── _components/         # 仅本页面用的子组件(下划线前缀,不导出给外部)
-│   │   └── OrderFilterBar.tsx
-│   └── _hooks/              # 仅本页面用的 hook
-│       └── useOrderFilter.ts
-└── users/
-    └── ...
-```
-
-约束:
-- 页面组件**默认 default export**,与文件名一致
-- `_components/` `_hooks/` 用下划线前缀标记**私有**,**禁止跨页面 import**
-- 跨页面用得到的组件/hook → 升到 `src/components/` `src/hooks/`
-
-### `src/components/`
-
-**职责**:跨页面复用的业务组件。
-
-```
-src/components/
-├── OrderStatusBadge.tsx
-├── UserAvatar.tsx
-└── filters/
-    ├── DateRangeFilter.tsx
-    └── StatusFilter.tsx
-```
-
-约束:
-- 命名 PascalCase,文件名 = 组件名
-- 单组件 = 单文件;复杂组件可建子目录 `<Name>/{index.tsx, types.ts, hooks.ts}`
-- **不要**重复 `@teamix-evo/ui` 已经提供的能力(见 [reuse-first.md](reuse-first.md))
-- **不要**写"小工具组件"如 `Wrapper`、`Container` —— 用 div + tailwind 即可
-
-### `src/services/`
-
-**职责**:后端通信纯函数。详见 [`api-layering.md`](api-layering.md)。
-
-### `src/hooks/`
-
-**职责**:跨页面复用的自定义 Hook。
-
-```
-src/hooks/
-├── useOrderList.ts          # 数据 hook(包 react-query)
-├── useCreateOrder.ts
-├── useDebounce.ts           # UI hook
-└── useMediaQuery.ts
-```
-
-约束:
-- 命名必须 `use` 开头
-- 单 hook = 单文件
-- 数据 hook 调 `src/services/`,**禁止**直接 fetch
-
-### 全局态选型决策
-
-**装机时默认不预装任何状态库**。按"最小够用"逐级升级,不要直接跳到 zustand:
-
-| 场景 | 用什么 |
-| --- | --- |
-| 组件内状态 | `useState` / `useReducer` |
-| 跨少量组件、低频更新(当前用户、主题、语言、租户) | React `Context` |
-| 跨域、多页面、**高频**更新的客户端态 | `src/stores/`(zustand / jotai / redux 选一) |
-| 服务端数据(列表、详情、表单提交) | `react-query` / `swr`,**永远不进 Context、也不进 store** |
-
-「高频」的粗略判定:一个状态被 10+ 处读取、且每秒可能变化一次以上 —— Context 会触发整子树重渲染,这时才有引 store 的收益。
-
-Context 文件位置:
-
-- 全应用级(UserContext、ThemeContext)→ `src/contexts/<Name>Context.tsx`
-- 仅一个页面/子树用 → `src/pages/<id>/_components/<Name>Context.tsx`
-
-> 如果项目自始至终只用 Context + react-query 就能解决,**不需要**建 `src/stores/`,也不需要引 zustand。等真出现跨域高频全局态再装。
-
-### `src/stores/`
-
-**职责**:跨域、高频更新的客户端全局态。**不是**全局态的默认入口,先看上方「全局态选型决策」。
-
-约束:
-
-- 一个项目**只用一种**状态库(zustand / jotai / redux 选一,首次需要时引入并固定)
-- 按 domain 拆 store:`useOrderStore.ts`、`useUserStore.ts`
-- **不要**把服务端数据放 store —— 用 `react-query` / `swr` 缓存(它们就是异步 store)
-- **不要**为了消除一处 props drilling 就建 store —— 那是 Context 的场景
-
-### `src/types/`
-
-**职责**:类型声明。
-
-约束:
-- 只放 `.ts` 类型文件,**不导出运行时代码**
-- 按 domain 拆:`order.ts`、`user.ts`
-- 通用类型放 `api.ts`、`common.ts`
-
-### `src/utils/`
-
-**职责**:纯函数工具。
-
-约束:
-- **不依赖 React**(用了 React 应该是 hook,放 `src/hooks/`)
-- **不依赖 DOM**(用了 DOM 应该是 lib 层包装)
-- **不发请求**(发请求是 service)
-- 一个文件一个主题:`format.ts`、`validate.ts`、`array.ts`
-
-### `src/lib/`
-
-**职责**:三方 SDK 包装、http 实例、env 读取。
-
-```
-src/lib/
-├── http.ts                  # axios / fetch 实例(全局唯一)
-├── env.ts                   # import.meta.env 的类型化封装
-├── analytics.ts             # 埋点 SDK 包装
-└── map.ts                   # 第三方地图 SDK 包装
-```
-
-约束:
-- 这一层**与 React 解耦**,可以在 Node / 测试中跑
-- **不放业务逻辑** —— 业务逻辑去 service / hook
-
-### `src/routes/`
-
-仅当使用集中式路由声明(react-router data router)时才有:
-
-```
-src/routes/
-├── index.tsx                # createBrowserRouter 声明
-└── guards.tsx               # 鉴权守卫
-```
-
-文件路由(file-based routing)项目不需要这个目录。
-
----
-
-## 命名约定
-
-| 类型 | 风格 | 例 |
-| --- | --- | --- |
-| 目录 | 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` |
-
----
-
-## 路径别名
-
-业务工程默认配 `@/*` 指向 `src/*`,所有跨目录 import 走别名:
-
-```ts
-// ✅
-import { Button } from '@teamix-evo/ui';
-import { listOrders } from '@/services/order';
-import { OrderStatusBadge } from '@/components/OrderStatusBadge';
-
-// ❌
-import { listOrders } from '../../../services/order';
-```
-
----
-
-## Import 边界(单向依赖)
-
-```
-pages   ──▶ components, hooks, services, types, utils, lib, stores
-components ──▶ hooks, services, types, utils, lib (NOT pages)
-hooks   ──▶ services, types, utils, lib, stores (NOT components, NOT pages)
-services ──▶ types, lib (NOT hooks, NOT components, NOT pages)
-stores  ──▶ types, utils, lib (NOT services, NOT hooks)
-types   ──▶ (no runtime imports)
-utils   ──▶ types only
-lib     ──▶ types only
-```
-
-要点:
-- **services 不依赖 React** —— 它是纯函数层
-- **types / utils / lib 是叶子层** —— 不依赖业务层,谁都能引
-- **反向依赖直接否决**(component 不能 import page,service 不能 import hook)
-
----
-
-## 反模式速查
-
-| 反模式 | 为什么禁 | 应该怎么做 |
-| --- | --- | --- |
-| `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)`(就近,不集中) |