@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-design-opentrek/generation-flow.md

@@ -0,0 +1,185 @@
+# 生成 / 翻新 / 验证流程
+
+> AI 在执行页面级任务时，按本文件的门控顺序执行。每一步都有明确的输入输出，跳步会导致结果不可控。
+
+---
+
+## 1. 生成路径（六步门控）
+
+适用关键词：**"生成 / 创建 / 新建 / 设计一个 / 做一个"**。
+
+```
+Step 1 需求确认 → Step 2 类型识别 → Step 3 子类型 + 布局
+                                            ↓
+Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
+```
+
+### Step 1 · 最小 quorum + 默认值
+
+**只有两个信息缺一不可**（最小 quorum，缺则反问）：
+
+- [ ] **页面类型**：ListPage / DetailPage / FormPage / Dashboard / Dialog（缺则按 Step 2 决策树推断）
+- [ ] **资源实体**：要操作的对象是什么（订单 / 实例 / 用户 / ……）
+
+**其他信息全部走默认值，先生成再细化**（避免连环反问让用户失去耐心）：
+
+| 维度       | 默认                                                  | 何时升级                              |
+| ---------- | ----------------------------------------------------- | ------------------------------------- |
+| 业务领域   | 资源管理                                              | 用户明确说"工作流 / 报表"等           |
+| 用户角色   | 业务管理员                                            | 涉及审计 / 审批 / 平台运维等敏感角色  |
+| 核心动作   | CRUD（增 / 删 / 改 / 查 + 列表）                      | 明确出现"批量 / 审批 / 导出"等关键词  |
+| 入口路径   | 从同名菜单进入，无外部跳转                            | 明确说"从 X 跳到 Y"                   |
+| 子类型     | ListPage→standard / FormPage→single-page / 其余各 1   | 用户提到 wizard / drawer / tabbed 等  |
+
+**反问触发条件**（只有以下情况反问，否则直接出方案）：
+
+1. 页面类型与资源实体均无法从需求中推断
+2. 用户描述与默认值明显冲突（如"我要做一个数据看板"但又说"列表"）
+
+**输出**：页面类型 + 资源实体 + 一句话场景假设（"假设是业务管理员的订单 CRUD 列表，如有偏差请指正"）。
+
+### Step 2 · 页面类型识别
+
+根据 [patterns/page-types.md](./patterns/page-types.md) §决策树匹配类型：
+
+```
+页面内容是什么？
+├─ 多条结构化数据 → ListPage
+├─ 单个记录详情 → DetailPage
+├─ 用户输入数据 → FormPage
+├─ 数据可视化/统计 → Dashboard
+└─ 二次确认 / 快速操作 → Dialog/Sheet
+```
+
+**输出**：页面类型 ID（`ListPage` / `DetailPage` / ...）。
+
+### Step 3 · 子类型识别 + 布局选择
+
+根据页面类型读取对应 `patterns/{type}-page.md`：
+
+- 列表页 6 种子类型：`standard / pure-card / standard-card / drawer / expandable / l2-sidebar / advanced-filter`
+- 详情页 2 种子类型：`tabbed / single-section`
+- 表单页 3 种子类型：`single-page / wizard / drawer-form`
+
+**输出**：子类型 ID + 区域骨架（参照 [patterns/page-types.md](./patterns/page-types.md) §Zone Map）。
+
+### Step 4 · 组件挑选
+
+读 [components.md](./components.md) §选型决策树确定组件集：
+
+1. 优先使用 `@teamix-evo/ui` 注册表中的稳定组件
+2. 通过 MCP `list_components(status: "stable")` 查可用列表
+3. 通过 MCP `get_component_meta(id)` 查具体 Props/Examples
+4. 复合场景按 [components.md](./components.md) §组合规则装配
+
+**输出**：组件清单 + 每个组件的关键 Props。
+
+### Step 5 · 视觉填充（Token 绑定）
+
+读 [foundations.md](./foundations.md)，所有色彩、间距、字号、圆角、阴影、动效**必须**使用 Token：
+
+| 维度 | Token 入口                                                                   |
+| ---- | ---------------------------------------------------------------------------- |
+| 色彩 | `bg-primary` / `text-foreground` / `border-border` / `text-muted-foreground` |
+| 间距 | Tailwind 4px 网格刻度（`gap-2`/`gap-4`/`p-6` 等）                            |
+| 字号 | `text-xs` / `text-sm` / `text-base` / `text-lg`                              |
+| 圆角 | `rounded-md` / `rounded-lg` / `rounded-full`                                 |
+| 阴影 | `shadow-sm` / `shadow-md` / `shadow-lg`                                      |
+| 动效 | `duration-150` / `duration-300` / `transition-colors`                        |
+
+**禁止**：硬编码 hex 色值、`#xxx` rgb()、内联 `style={{ ... }}`、`text-emerald-600` 等原始色。
+
+**输出**：含 Token 引用的可执行代码 / HTML。
+
+### Step 6 · 自检
+
+对照 [checklist.md](./checklist.md) 10 项逐项验证：
+
+- 通过 → 输出最终代码
+- 不通过 → 回到对应失败项的步骤修正后重新自检
+
+**输出**：合规代码 + 自检报告。
+
+---
+
+## 2. 翻新路径
+
+适用关键词：**"改造 / 升级 / 翻新 / 对齐规范 / 重新生成"**。
+
+```
+1. 读取目标页面源码
+2. 扫描违规项（按 boundaries.md F1-F10 + S1-S8）
+3. 生成 old → new 替换清单
+   - 硬编码色值 → CSS Token 变量
+   - space-y-* → flex + gap-*
+   - w-N h-N (等值) → size-N
+   - 自定义 dark: 覆盖 → 语义 token
+4. 对照 components.md 检查组件选型是否合理（如自定义 div 改 Empty / Skeleton / Badge）
+5. 应用替换 + 输出变更报告
+```
+
+**输出**：翻新后代码 + 变更报告（每项替换的 old → new + 引用的规则 ID）。
+
+---
+
+## 3. 验证路径
+
+适用关键词：**"检查 / 验证 / 评估 / 是否符合规范"**。
+
+```
+1. 读取目标页面源码
+2. 逐条对照 boundaries.md
+   - F1-F10（禁止项）
+   - S1-S8（样式规则）
+   - C1-C12（组件结构规则）
+3. 对照 checklist.md 10 项自检
+4. 输出验证报告
+```
+
+**报告格式**：
+
+```markdown
+## 验证报告
+
+### ❌ 违规项（N）
+
+- F1 第 12 行：硬编码 `#333333` → 应改为 `text-foreground`
+- S2 第 23 行：使用 `space-y-4` → 应改为 `flex flex-col gap-4`
+- C2 第 45 行：DialogContent 缺失 DialogTitle
+
+### ⚠️ 建议项（M）
+
+- ...
+
+### ✅ 合规项（K）
+
+- ...
+```
+
+---
+
+## 4. 子任务退出条件
+
+| 任务类型 | 何时停止生成                      |
+| -------- | --------------------------------- |
+| 生成     | Step 6 自检全部通过               |
+| 翻新     | 替换清单为空 + 重新对照无违规     |
+| 验证     | 报告完整列出所有违规项 + 修复建议 |
+
+---
+
+## 5. 与 code-opentrek skill 的协作
+
+页面级任务通常**两个 skill 同时触发**。Design skill 决定"长什么样"，Code skill 决定"怎么落地"：
+
+| 决策点                   | 由谁主导                                                                               |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| 页面骨架 / Zone 划分     | design                                                                                 |
+| 组件选型                 | design                                                                                 |
+| Token 绑定 / 视觉规则    | design                                                                                 |
+| 文件放置位置             | code（[file-structure.md](../teamix-evo-code-opentrek/file-structure.md)）             |
+| import 路径 / reuse 策略 | code（[reuse-first.md](../teamix-evo-code-opentrek/reuse-first.md)）                   |
+| API / services 层        | code（[api-layering.md](../teamix-evo-code-opentrek/api-layering.md)）                 |
+| 表单实现细节             | code（[forms-and-validation.md](../teamix-evo-code-opentrek/forms-and-validation.md)） |
+
+冲突时按 ADR 0018 AI 上下文路由约定：design 决定"做什么"，code 决定"怎么做"。

package/src/teamix-evo-design-opentrek/patterns/dashboard.md

@@ -0,0 +1,31 @@
+# Dashboard — 数据概览与监控页
+
+> AI 实操路径:Step 2(页面类型识别)判定为 Dashboard 后,本文档接管。生成频次低于 ListPage / FormPage / DetailPage,当前为最小规范,后续按 list-page.md / form-page.md 体例扩充。
+
+---
+
+## 1. 标准结构
+
+```text
+┌────────────────────────────────────────────┐
+│ PageHeader: 概览        [今日 ▼] [刷新]    │
+├────────────────────────────────────────────┤
+│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐        │
+│ │订单数│ │待办数│ │成交额│ │完成率│  ← StatCards
+│ │ 1024 │ │   3  │ │¥12.3K│ │ 68%  │        │
+│ └──────┘ └──────┘ └──────┘ └──────┘        │
+├────────────────────────────────────────────┤
+│ 业务趋势                   最近异常         │
+│ [Chart 折线图]            [Timeline]        │
+└────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 设计要点
+
+- 关键指标用 `text-3xl font-bold`,与上一周期对比用 `+/-` 配 `chart-*` 色
+- 时间范围切换持久化到 URL params
+- 图表色彩按 `chart-1` `chart-2` `chart-3` ... 顺序消费,**禁止**任意 hex
+- StatCard 数量:4 (1×4) / 6 (2×3) / 8 (2×4);超过 8 改用 ListPage
+- 不要在 Dashboard 内放可编辑表单 — 跳转 FormPage

package/src/teamix-evo-design-opentrek/patterns/detail-page.md

@@ -0,0 +1,202 @@
+# Detail Page — 详情页模式
+
+> **触发**：用户描述含"详情/查看/信息/概览"。
+> **核心特征**：单条记录的只读展示 + DescriptionList + 操作按钮。
+> **页面级别**：L2（面包屑模式 PageHeader，自动继承 Sidebar）。
+
+---
+
+## 1. 子类型识别
+
+| 子类型       | 关键词                   | 差异特征                                   |
+| ------------ | ------------------------ | ------------------------------------------ |
+| **标准详情** | "详情"/"基本信息"        | PageHeader + DescriptionList + 操作按钮    |
+| **资源详情** | "实例详情"/"资源"/"监控" | InfoCard + MonitorPanel + Tabs（关联资源） |
+| **概览型**   | "概览"/"总览"            | StatCard + Chart + DescriptionList         |
+| **流程型**   | "审批"/"流程"/"记录"     | Steps + Timeline + DescriptionList         |
+| **对比型**   | "对比"/"比较"            | 双栏/多栏 DescriptionList 对照             |
+
+---
+
+## 2. 标准结构（资源详情）
+
+```
+┌─────────────────────────────────────────────┐
+│ PageHeader（面包屑模式）                    │
+│ 实例与镜像 > 实例列表 > 实例详情 [创建镜像]│  ← Header
+│                                             │
+│ InfoCard ─ 基本信息                         │  ← 摘要区
+│ 组织 | 资源集 | 创建人 | 创建时间           │
+│                                             │
+│ InfoCard ─ 监控                             │
+│ [CPU 使用率] [内存使用率]（MonitorPanel）   │
+│                                             │
+│ Tabs                                        │  ← 分类
+│ [基本信息] [监控] [云盘] [安全组] [快照]    │
+│                                             │
+│ DescriptionList ─ 基本信息                  │  ← 主区
+│ 架构: X86       地域: cn-beijing            │
+│ 实例ID: i-xxx   状态: [Badge 运行中]        │
+│                                             │
+│ DescriptionList ─ 配置信息                  │
+│ vCPU: 2         内存: 4 GiB                 │
+└─────────────────────────────────────────────┘
+```
+
+## 简洁详情结构
+
+```
+┌─────────────────────────────────────────────┐
+│ PageHeader（面包屑模式）                    │
+│ 用户列表 > 用户详情      [编辑] [删除]      │
+│                                             │
+│ DescriptionList (column: 2)                 │
+│ 姓名: 张三       邮箱: zhangsan@example.com │
+│ 角色: 管理员     状态: [Badge 启用]         │
+│ 创建时间: 2026-01-15  更新: 2026-04-20     │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 必需组件
+
+| 组件                | 位置 | 说明                            |
+| ------------------- | ---- | ------------------------------- |
+| **PageHeader**      | top  | 面包屑模式(L2 页面)+ 操作按钮组 |
+| **DescriptionList** | main | 详情页核心展示组件              |
+| **DescriptionItem** | main | 描述项最小展示单元              |
+
+**框架级**(自动继承):Sidebar、PageHeader 由 page-frame 管控。
+
+### 可选组件
+
+- **InfoCard** — 顶部摘要(组织/创建人/创建时间)
+- **Tabs** — 信息分多类(基本/监控/关联资源)
+- **MonitorPanel** — CPU/内存/网络监控(仅资源详情)
+- **Badge** — 状态指示
+- **Tooltip** — 长 ID / 截断字段悬浮
+
+---
+
+## 4. DescriptionItem 字段交互
+
+| 类型           | 触发       | 反馈                              |
+| -------------- | ---------- | --------------------------------- |
+| 默认展示       | —          | 只读文本，空值 `-` 占位           |
+| 可复制         | 点 📋 图标 | 图标高亮 + Toast "已复制"         |
+| 可编辑（行内） | 点 ✎ 图标  | 切换为 Input                      |
+| 链接跳转       | 点字段值   | 链接样式（VPC、安全组等关联资源） |
+| 状态展示       | —          | Badge + 语义色                    |
+| 悬浮提示       | hover      | Tooltip 完整内容（截断时）        |
+
+---
+
+## 5. 操作按钮规则
+
+### 5.1 位置
+
+- **位置 A**：PageHeader 右侧（主操作 + 更多 Dropdown）
+- **位置 B**：DescriptionItem 内（行内编辑、复制）
+
+### 5.2 操作分级
+
+| 级别             | 适用            | 确认                  |
+| ---------------- | --------------- | --------------------- |
+| 一级（可逆）     | 编辑、续费/降配 | 直接执行              |
+| 二级（影响状态） | 释放、创建镜像  | Dialog 确认           |
+| 三级（不可逆）   | 删除            | Dialog + 输入确认文本 |
+
+### 5.3 异步反馈
+
+| 操作            | Toast        | 页面                  |
+| --------------- | ------------ | --------------------- |
+| 释放 / 创建镜像 | "操作已提交" | 轮询状态              |
+| 删除            | "删除已提交" | 返回 ListPage 并刷新  |
+| 编辑保存        | "保存成功"   | 停留详情页 + 局部刷新 |
+
+---
+
+## 6. Tab 切换交互
+
+| 场景       | 行为                          |
+| ---------- | ----------------------------- |
+| 首次加载   | 默认激活第一个 Tab            |
+| Tab 切换   | 懒加载数据 + Loading          |
+| 无数据 Tab | 展示 Empty                    |
+| Tab 内列表 | 含独立 Pagination             |
+| URL 同步   | 切换同步 URL hash，刷新可保持 |
+
+---
+
+## 7. 信息分组
+
+- DescriptionList 按 ListSection 分组（基本信息 / 配置信息 / 网络信息）
+- 每组可独立展开/收起（可选）
+- 分组间用 Divider 分隔
+- 每组内 DescriptionList 默认 `column: 2`，宽屏可至 4，移动端降为 1
+
+---
+
+## 8. 嵌套约束
+
+| 父子关系                                                                                     | 状态                             |
+| -------------------------------------------------------------------------------------------- | -------------------------------- |
+| PageContainer → ContentWrapper → Card(白卡) → PageHeader / InfoCard / Tabs / DescriptionList | ALLOW                            |
+| ContentWrapper → 业务组件（无 Card）                                                         | **FORBID**                       |
+| Card → Card                                                                                  | **FORBID**（白卡单例）           |
+| InfoCard → DescriptionList / MonitorPanel                                                    | ALLOW                            |
+| Tabs → TabPane → DescriptionList / DataTable                                                 | ALLOW（关联资源用 DataTable）    |
+| Sidebar → DescriptionList                                                                    | **FORBID**                       |
+| PageHeader → Tabs                                                                            | WARN（Tab 应在 PageHeader 下方） |
+
+---
+
+## 9. 禁止项
+
+| 禁项                       | 原因                                  |
+| -------------------------- | ------------------------------------- |
+| Form 直接在主内容区        | 编辑应通过 Drawer/Dialog/FormPage     |
+| DataTable 在主内容区       | 关联数据应用 Tabs 子面板              |
+| Chart 替代 DescriptionList | 图表属 Dashboard，监控用 MonitorPanel |
+| QueryFilter                | 详情页无筛选需求                      |
+| `hr` 分割线                | 用 Divider                            |
+
+---
+
+## 10. 边界情况
+
+| 场景       | 处理                    |
+| ---------- | ----------------------- |
+| 无数据     | Empty + 返回列表引导    |
+| 加载中     | Loading 骨架屏          |
+| 加载失败   | ErrorState + 重试按钮   |
+| 权限不足   | 操作按钮隐藏，只读展示  |
+| 资源不存在 | 跳转 404 ExceptionPage  |
+| 字段为空   | 展示 "-" 占位           |
+| 字段过长   | 截断 + Tooltip 完整内容 |
+
+---
+
+## 11. 详情 → 列表返回约定
+
+- 面包屑父级项点击返回 ListPage
+- PageHeader 右侧可选 × 关闭按钮
+- 返回后 ListPage 保持原筛选 + 分页
+- 详情页编辑成功后，按业务决策：
+  - 留在详情页（Toast「保存成功」+ 局部刷新）
+  - 或返回 ListPage（Toast「保存成功」+ 列表刷新）
+
+---
+
+## 12. 详情页特有自检
+
+- [ ] PageHeader 用面包屑模式（L2 页面）
+- [ ] DescriptionList 列数：默认 2，宽屏可 4，移动端 1
+- [ ] 关联资源用 Tabs 子面板（不在主区直接放 DataTable）
+- [ ] Badge 用语义色（不用原色）
+- [ ] 空字段用 "-" 占位
+- [ ] 长字段（ID/Hash）`font-mono` + 提供复制按钮
+- [ ] 操作分级正确（删除 = 输入确认）
+- [ ] Tab 切换 URL hash 同步
+- [ ] 边界状态完整：Empty / Loading / ErrorState / 权限不足 / 404