@teamix-evo/skills 0.5.0 → 0.6.0

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

@@ -1,10 +1,14 @@
-# Flows — 用户旅程
+# Flows — 页间流转与用户旅程
 
-> **页间流转视图见 [`patterns/page-types.md §6 页间流转`](./patterns/page-types.md#6-页间流转)** — 包含后台主流转图、流转设计规则、资源生命周期、CRUD 流转速查。本文档只承载"四条核心用户旅程"的编织视角。
+> 本文件是"页面间如何跳转"的**唯一真值源**：用户旅程、主流转图、CRUD 速查、资源生命周期、流转设计规则均集中于此。
+>
+> 结构化机读数据（含 URL 模板、Toast 文案、确认级别、反馈矩阵、快捷键等执行细节）见 [`rules/page-flow.json`](./rules/page-flow.json)。本文档与 JSON 互补：本文档面向 AI / 设计师阅读，JSON 面向程序消费。
 
 ---
 
-## 1. 四条核心旅程速查 + 设计要点
+## 1. 四条核心用户旅程
+
+四条旅程是"编织视角"——把页面、组件、反馈串成完整的用户路径。
 
 ### A · 资源查找与操作
 
@@ -17,10 +21,10 @@
 
 `ListPage → FormPage(分组 + 实时校验) → 提交 → 列表(顶部)`
 
-- blur 校验单字段,submit 校验全部
-- 失败**不清空表单**,错误定位到字段
-- 长表单(> 10 字段)必须有"保存草稿"
-- 创建成功落点优先返回列表,编辑成功优先停留原页
+- blur 校验单字段，submit 校验全部
+- 失败**不清空表单**，错误定位到字段
+- 长表单（> 10 字段）必须有"保存草稿"
+- 创建成功落点优先返回列表，编辑成功优先停留原页
 
 ### C · 异常处理
 
@@ -36,16 +40,85 @@
 
 - BulkActionBar 浮动在表格底部
 - AlertDialog 必须列出至少前 5 条受影响资源
-- 部分失败时,失败项显示"重试"按钮
+- 部分失败时，失败项显示"重试"按钮
+
+---
+
+## 2. 后台主流转图
+
+```text
+              ┌─────────────────┐
+              │  全局导航 / 首页 │
+              └────────┬────────┘
+                       │ 选择模块
+                       ▼
+┌──────────┐ 创建 ┌──────────┐ 查看  ┌────────────┐
+│ FormPage │◄────│ ListPage │──────►│ DetailPage │
+└────┬─────┘     └─────┬────┘       └─────┬──────┘
+     │ 成功            │                   │
+     └────────────────►│◄──────────────────┘
+                       │ 编辑                返回
+                       ▼
+              ┌──────────────┐
+              │   FormPage   │
+              └──────────────┘
+
+   Dashboard ──下钻──► ListPage(预筛选)
+```
+
+> AI 副驾驶（命令面板 / 对话主面板 / 告警诊断 / 操作编排 / 知识问答 / 拓扑感知）属于**变体专属**流转，不在中性基线内。
+
+---
+
+## 3. CRUD 流转速查
+
+| 意图     | 关键词            | 源页面              | 目标页                               | 完成后落点           |
+| -------- | ----------------- | ------------------- | ------------------------------------ | -------------------- |
+| 查看列表 | 列表/查询/检索    | Sidebar             | ListPage                             | —                    |
+| 查看详情 | 详情/查看/信息    | ListPage            | DetailPage                           | 可返回列表           |
+| 新建     | 新建/创建/新增    | ListPage            | FormPage（新建）                     | 保存后返回列表       |
+| 编辑     | 编辑/修改         | ListPage/DetailPage | FormPage（编辑）或 Sheet（抽屉编辑） | 保存后返回原页       |
+| 删除     | 删除/移除         | ListPage            | Dialog（输入确认）                   | 确认后刷新列表       |
+| 复制     | 复制/克隆         | ListPage            | FormPage（复制新建）                 | 保存后返回列表       |
+| 批量     | 批量启停/批量删除 | ListPage            | AlertDialog → 进度                   | Toast(成功 N/失败 M) |
+
+> URL 模板、Toast 文案、navType 等机读字段见 [`rules/page-flow.json` § crudFlow / pageNavigation](./rules/page-flow.json)。
+
+---
+
+## 4. 资源生命周期
+
+"资源" 泛指业务对象（订单 / 用户 / 商品 / 任务 / 工单 / 文档…）。
+
+| 阶段 | 发现     | 创建     | 配置       | 监控      | 变更     | 删除     |
+| ---- | -------- | -------- | ---------- | --------- | -------- | -------- |
+| 页面 | ListPage | FormPage | DetailPage | Dashboard | FormPage | Dialog   |
+| 动作 | 搜索定位 | 填写表单 | 查看明细   | 处置异常  | 编辑提交 | 二次确认 |
+
+---
+
+## 5. 流转设计规则
+
+1. **导航深度 ≤ 4 层** — 超过即是信息架构问题
+2. **每层都有返回路径** — 面包屑 / 返回按钮 / Esc 快捷键
+3. **主导航始终可见** — 仅"全屏编辑 / 大屏展示"模式可隐藏
+4. **状态保持** — 列表筛选条件、表单未提交内容必须保留
+5. **快捷路径** — 高频操作建议提供 `Cmd+K` 入口
+6. **不创建死胡同** — 任何成功 / 失败页面都必须有"下一步"按钮
+7. **操作确认分三级**（详见 [`rules/page-flow.json` § operationConfirmationLevels](./rules/page-flow.json)）：
+   - 一级（可逆，如查看 / 编辑跳转）：无确认，直接执行
+   - 二级（有未保存内容 / 启停重启）：Dialog 确认
+   - 三级（不可逆，如删除 / 资源释放）：Dialog + 输入确认文本（如 `DELETE`）
 
 ---
 
-## 2. 流转自检
+## 6. 流转自检
 
 - [ ] 任意页面都能通过面包屑 / Esc 返回上一级
-- [ ] ListPage 的筛选条件持久化到 URL Params(刷新 / 分享 / 返回保留)
+- [ ] ListPage 的筛选条件持久化到 URL Params（刷新 / 分享 / 返回保留）
 - [ ] FormPage 未保存离开有 Dialog 确认
 - [ ] 危险操作的 Dialog 列出影响范围与资源清单
-- [ ] 成功 / 失败页面都有"下一步"按钮(无死胡同)
+- [ ] 成功 / 失败页面都有"下一步"按钮（无死胡同）
 - [ ] 批量操作进度可见、部分失败可重试
-- [ ] 异常数字是可点击的钻取入口(Dashboard → ListPage 预筛选)
+- [ ] 异常数字是可点击的钻取入口（Dashboard → ListPage 预筛选）
+- [ ] 删除等不可逆操作要求输入确认文本（三级确认）

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

@@ -109,7 +109,7 @@
 | Standard | 20px | `gap-5`  | 同分组内多个 FormItem 之间    |
 | Section  | 32px | `gap-8`  | 表单分段（FormSection）之间   |
 
-> 例外：Drawer 内嵌简表单（≤ 5 字段）可整体收紧到 Tight + 16px section。**不要**自创 24px / 28px 等中间档。
+> 例外：Sheet（抽屉）内嵌简表单（≤ 5 字段）可整体收紧到 Tight + 16px section。**不要**自创 24px / 28px 等中间档。
 
 ### 3.6 Input 宽度五档（通用规范，反哺自 Teamix-UI 规范文档）
 
@@ -204,7 +204,7 @@
 | `shadow-sm`   | Card 静态                     | 10           |
 | `shadow`      | Hover 提升、Dropdown          | 20           |
 | `shadow-md`   | Popover、Tooltip              | 30           |
-| `shadow-lg`   | Sheet、Drawer                 | 40           |
+| `shadow-lg`   | Sheet                         | 40           |
 | `shadow-xl`   | Dialog、Modal、CommandPalette | 50           |
 
 ### 6.2 规则
@@ -231,12 +231,12 @@
 
 ### 7.1 时长四档
 
-| Token          | ms  | 用途                              |
-| -------------- | --- | --------------------------------- |
-| `duration-75`  | 75  | 微反馈（按钮按下、勾选）          |
-| `duration-150` | 150 | 默认过渡（hover、focus）          |
-| `duration-200` | 200 | 入场（Tooltip、Popover）          |
-| `duration-300` | 300 | 大型容器（Dialog、Sheet、Drawer） |
+| Token          | ms  | 用途                      |
+| -------------- | --- | ------------------------- |
+| `duration-75`  | 75  | 微反馈（按钮按下、勾选）  |
+| `duration-150` | 150 | 默认过渡（hover、focus）  |
+| `duration-200` | 200 | 入场（Tooltip、Popover）  |
+| `duration-300` | 300 | 大型容器（Dialog、Sheet） |
 
 ### 7.2 缓动
 
@@ -258,7 +258,7 @@
 
 - **L1 必备**：状态切换（hover / focus / active）— 全站统一 `duration-150`
 - **L2 推荐**：内容入场（列表项渐入、Skeleton 替换）— `duration-200`
-- **L3 增强**：场景转场（页面切换、Drawer 抽屉）— `duration-300`，可酌情增减
+- **L3 增强**：场景转场（页面切换、Sheet 抽屉）— `duration-300`，可酌情增减
 
 ### 7.5 规则
 

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

@@ -63,14 +63,24 @@ Step 7 自检    ← Step 6 视觉填充  ← Step 5 可用性校验 ← Step 4
 
 🚧 **GATE**: Step 2 必须已产出"页面类型 ID"
 
-📖 **MUST READ**: 对应的 `patterns/{type}-page.md` + [flows.md](./flows.md)（涉及用户旅程时）
+📖 **MUST READ**（按顺序读取）:
+1. `./pages/{type}-page/SKILL.md` — 子技能入口（子类型列表 + 属性模型）
+2. `./pages/{type}-page/patterns/{subtype}.md` — 对应子类型的**完整布局结构**（骨架、DOM 顺序、CSS 约束、间距硬值）
+3. `./pages/{type}-page/_shared/search-combo-spec.md` — SearchCombo 硬约束（20px 间距、容器式 border、禁止嵌套规则）
+4. `./pages/{type}-page/_shared/action-column-spec.md` — 操作列规范（≤3 直显、Dropdown 收纳）
+5. `./rules/page-frame.json` — L0/L1/L2 框架级别
+6. `./rules/layout-rules.json` — 布局模式
 
-根据页面类型读取对应 `patterns/{type}-page.md`：
+⚠️ **禁止**：不要仅读 `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`
 
+> 涉及用户旅程时追加阅读 [flows.md](./flows.md)。
+
 **输出**：子类型 ID + 区域骨架（参照 [patterns/page-types.md](./patterns/page-types.md) §Zone Map）。
 
 ### Step 4 · 组件挑选
@@ -84,9 +94,11 @@ Step 7 自检    ← Step 6 视觉填充  ← Step 5 可用性校验 ← Step 4
 1. 优先使用 `@teamix-evo/ui` 注册表中的稳定组件
 2. 通过 MCP `list_components(status: "stable")` 查可用列表
 3. 通过 MCP `get_component_meta(id)` 查具体 Props/Examples
+   - **Props**：确定必传 / 可选 / 默认值，明确接口契约
+   - **Examples**：作为实现参考（含组合用法、常见模式、边界处理），优先复用示例中的写法而非自由发挥
 4. 复合场景按 [components.md](./components.md) §组合规则装配
 
-**输出**：组件清单 + 每个组件的关键 Props。
+**输出**：组件清单 + 每个组件的关键 Props + 参考的 Example 片段（若有启发性写法）。
 
 ### Step 5 · 组件可用性校验（新增 gate）
 

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

@@ -0,0 +1,260 @@
+---
+name: page-rule-detail
+parent: page-rule-system
+description: >
+  详情页(PageType: DetailPage)路由规则。根据子类型识别关键词，路由到 patterns/ 目录下对应详细规则。
+  共享规则在 _shared/ 目录（PageHeader L2 面包屑强约束）。
+  包含通用属性模型、组件推荐、嵌套约束、交互补充、视觉规范同步。
+  触发：需要详情页规则、匹配详情页模板、生成详情页。
+  Version: 7.8.4
+---
+
+# 详情页路由规则
+
+## 1. 类型定义
+
+**页面类型**: DetailPage
+**核心特征**: 单条记录的只读展示 + DescriptionList + 操作按钮
+**识别条件**: 页面展示单个实体的完整信息 + 描述列表(DescriptionList) + Tab分类 + 操作按钮
+
+---
+
+## 2. 子类型路由表
+
+| 子类型ID | 识别关键词 | 路由到 | 核心组件 |
+|----------|-----------|--------|----------|
+| resource | "实例详情"/"资源"/"详情"/"查看"/"信息" | → `patterns/resource-detail.md` | InfoCard + DescriptionList + Tabs |
+| monitor | "监控"/"指标"/"性能"/"告警"/"Metrics" | → `patterns/monitor-detail.md` | MetricCard + ChartPanel + AlertList + TimeRangeSelector |
+| api-doc | "API"/"接口"/"端点"/"文档"/"接口文档"/"模型API" | → `patterns/api-doc-detail.md` | ApiEndpoint + ParameterTable + CodeBlock |
+| comparison | "对比"/"比较"/"差异"/"版本对比" | → `patterns/comparison-detail.md` | 双栏 DescriptionList |
+
+### 路由判定优先级
+
+1. 含"监控"/"指标"/"性能"/"告警"/"Metrics" → monitor
+2. 含"API"/"接口"/"端点"/"文档" → api-doc
+3. 含"对比"/"比较"/"差异" → comparison
+4. 其他详情场景 → resource（默认）
+
+---
+
+## 3. 通用属性模型
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| layout.type | TWO_COL / SINGLE_COL | 见 `rules/page-frame.json` layoutSelectionRules |
+| layout.frame | L2 | 详情页为 L2 级页面，自动继承 Sidebar + PageHeader 面包屑模式 |
+| responsive | 768px 侧边栏折叠为抽屉，DescriptionList 列数从 4 降为 2 |
+
+> **框架组件自动继承**：Sidebar、PageHeader 由 `rules/page-frame.json` 统一管理，L2 级页面自动继承。
+
+---
+
+## 4. 组件推荐
+
+### 必需组件
+
+| 组件 | 引用 | 层级 | 位置 | 说明 |
+|------|------|------|------|------|
+| PageHeader | — | ORGANISM | top | 面包屑模式 + 操作按钮组（详见 `../../rules/page-header-spec.md`） |
+| DescriptionList | — | ORGANISM | center | 核心展示组件，支持 2/3/4 列布局 |
+| DescriptionItem | — | ATOMIC | center | 单个键值对单元，6 种交互模式 |
+
+### 可选组件（跨子类型通用）
+
+| 组件 | 引用 | 条件 | 说明 |
+|------|------|------|------|
+| InfoCard | — | 需展示摘要信息 | 顶部摘要卡片 |
+| CopyableText | — | ID/IP/资源名 | 可复制原子 |
+| StatusBadge | — | 资源运行态 | 带前置圆点的状态徽章 |
+| Tabs | — | 信息分多类展示 | Tab 分组 |
+| Dialog | — | 需二次确认 | 删除/释放确认 |
+| Sheet | — | 需编辑详情 | 侧滑编辑 |
+| DropdownMenu | — | 操作多项 | "更多"下拉 |
+| Tag | — | 状态/标签 | — |
+| Badge | — | 运行状态 | — |
+| Tooltip | — | 悬浮提示 | — |
+| Separator | — | 信息分组 | — |
+| Alert | — | 操作提示 | — |
+| Empty | — | 无关联数据 | — |
+| Spinner | — | 加载中 | — |
+| Sonner | — | 操作反馈 | — |
+
+### 禁止组件
+
+| 组件 | 约束 | 原因 |
+|------|------|------|
+| Form (ORGANISM) | 禁止在主内容区 | 编辑应通过 Sheet/Dialog/FormPage |
+| DataTable | 禁止在主内容区 | 关联数据通过 Tabs 子面板展示 |
+| Chart (ORGANISM) | 禁止替代 DescriptionList | 监控通过 ChartPanel，详见 patterns/monitor-detail.md |
+| PageContainer | 禁止嵌套 | 见 layout-rules.json |
+| QueryFilter | 禁止出现 | 详情页无筛选需求 |
+
+---
+
+## 5. 嵌套约束（通用）
+
+| 父子关系 | 状态 | 说明 |
+|----------|------|------|
+| PageContainer → ContentWrapper | ALLOW | 右侧内容大容器（必需） |
+| ContentWrapper → Card(白卡容器) | ALLOW | 白色卡片容器（必需） |
+| Card(白卡容器) → PageHeader | ALLOW | 标准结构（面包屑模式） |
+| Card(白卡容器) → InfoCard | ALLOW | 摘要卡片 |
+| Card(白卡容器) → Tabs | ALLOW | 分类 Tab |
+| Card(白卡容器) → DescriptionList | ALLOW | 核心展示 |
+| ContentWrapper → PageHeader / DescriptionList / Tabs | FORBID | 必须经过白卡容器包裹 |
+| Card(白卡容器) → Card(白卡容器) | FORBID | 白卡容器为单例 |
+| DescriptionList → ListSection | ALLOW | 信息分组 |
+| ListSection → DescriptionItem | ALLOW | 分组详情项 |
+| Tabs → TabPane → DescriptionList | ALLOW | Tab 内展示详情 |
+| Tabs → TabPane → DataTable | ALLOW | Tab 内展示关联资源 |
+| PageHeader → ActionGroup | ALLOW | 操作按钮组 |
+| Sidebar → DescriptionList | FORBID | 描述列表不应在侧边栏 |
+
+> 子类型特有嵌套约束见对应 `patterns/*.md`。
+
+---
+
+## 6. 页面交互补充（跨子类型共享）
+
+### DescriptionItem 字段交互
+
+| 交互类型 | 触发 | 视觉反馈 |
+|----------|------|----------|
+| 默认展示 | — | 只读文本 |
+| 可复制 | 点击复制图标 | Sonner "已复制" |
+| 可编辑 | 点击编辑图标 | 行内切换为 Input |
+| 链接跳转 | 点击字段值 | 蓝色链接 |
+| 状态展示 | — | Badge 颜色 |
+| 悬浮提示 | hover | Tooltip 完整内容 |
+
+### 操作按钮行为
+
+| 操作 | 前置条件 | 二次确认 | 返回行为 |
+|------|---------|---------|----------|
+| 编辑 | 无 | 否 | 保存后返回详情页 |
+| 删除 | 实例已停止 | Dialog + 输入确认 | 返回列表页 |
+| 释放/创建镜像 | 实例已停止 | Dialog 确认 | 异步操作，返回列表 |
+| 续费/降配 | 运行中 | 否 | 完成后返回详情页 |
+| 返回/关闭 | 无 | 否 | 返回 ListPage |
+
+### Tab 切换交互
+
+- 首次加载默认激活第一个 Tab
+- Tab 切换懒加载，Loading 状态展示
+- 无数据 Tab 展示 Empty
+- URL hash 同步，支持刷新保持
+- Tab 内 DataTable 含独立 Pagination
+
+### 边界情况处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| 无数据 | Empty + 返回列表引导 |
+| 加载中 | Loading 骨架屏 |
+| 加载失败 | ErrorState + 重试 |
+| 权限不足 | 操作按钮隐藏 |
+| 资源不存在 | 404 ExceptionPage |
+| 字段为空 | 展示 "-" 占位 |
+| 字段过长 | 截断 + Tooltip |
+
+### 返回约定
+
+- 面包屑父级项可点击返回列表页
+- PageHeader 右侧关闭按钮(×)
+- 返回后列表页保持原筛选和分页
+
+---
+
+## 7. 视觉规范同步（v7.5 间距 + v7.6 表面）【硬约束】
+
+> 与列表页 `pages/list-page/SKILL.md` §5.1 / §5.2 形成对称。规则总源以 `rules/design-tokens.css` 为准。
+
+### 7.1 间距规则（v7.5 分层 padding 模型）
+
+| 层级 | Token | 值 | 含义 |
+|------|-------|----|------|
+| PageContainer 外层 | `--page-container-padding` | **16px** | 四周 padding |
+| Card 白卡容器内 | `--card-padding-x` | **20px** | 唯一对齐源 |
+| Card 内区块垂直间距 | `--card-gap` | 16px | 各区块纵向间距 |
+| DescriptionList 内 | C26-DescriptionList | 见 component-specs.json | 行高与列宽 |
+
+**派生约束**：
+- ContentCard 左右 padding 由 `--card-padding-x = 20px` 提供
+- 子组件（DescriptionList / InfoCard / Tabs / PageHeader）**不再重复设置左右 padding**
+
+### 7.2 ContentCard 表面规则（v7.6）
+
+| 属性 | **v7.6（当前）** |
+|------|----------------|
+| `border` | **`none`（去掉）** |
+| `box-shadow` | **`var(--shadow-sm)` = `0 1px 2px rgba(0,0,0,0.05)`** |
+| `border-radius` | `var(--radius-lg)` = 12px |
+| `background` | `hsl(var(--card))` |
+
+### 7.3 InfoCard surface 决议（v7.6）
+
+#### 模式 A：独立 Card 容器模式
+
+跟随主卡 ContentCard 应用 v7.6：`border: none` + `box-shadow: var(--shadow-sm)`
+
+#### 模式 B：嵌入主卡内的分组区块模式
+
+仅使用 `padding: 16px 0` + `border-bottom: 1px solid hsl(var(--gray-line))`（功能性分组分割线）
+
+### 7.4 功能性分割线保留清单
+
+| 元素 | 边框用途 | 保留 |
+|------|----------|------|
+| `.page-header` 的 `border-bottom` | 标题区与内容区分割 | ✅ 保留 |
+| `Tabs` 容器的 `border-bottom` | TabBar 与 TabContent 分割 | ✅ 保留 |
+| `Separator` | 信息分组 | ✅ 保留 |
+| ListSection 之间横线 | 描述列表分组 | ✅ 保留 |
+| 浮层类（Dropdown/Popover/Tooltip） | 浮层与背景区分 | ✅ 保留 border + 阴影 |
+
+### 7.5 禁止项
+
+- ❌ `.card / .info-card` 中残留 `border: 1px solid hsl(var(--gray-line))`
+- ❌ 硬编码阴影 `0 1px 2px rgba(0,0,0,0.04)`；一律走 `var(--shadow-sm)`
+- ❌ `--card-padding-x` 硬编码为 24px / 16px（v7.5 起统一 20px）
+- ❌ 子组件重复设置左右 padding
+
+---
+
+## 8. 共享规则引用
+
+| 共享规则 | 路径 | 被引用子类型 |
+|----------|------|-------------|
+| PageHeader L1 标题 / L2 面包屑强约束 | `../../rules/page-header-spec.md` | 全部 |
+
+---
+
+## 规范引用
+
+- **读取路径**：见根技能 `../../SKILL.md` §4.5 三阶段读取决策树
+  - 阶段①：`page-types.json` + `business-mapping.json`
+  - 阶段②：`page-frame.json` + `layout-rules.json` + `page-flow.json`；匹配子类型后追加 `patterns/{子类型}.md`
+  - 阶段③（生成 HTML 时）：`design-tokens.json` + `design-tokens.css` + `component-specs.json` + `styling.json` + `../../boundaries.md` + `../../foundations.md`
+
+> `rules/design-tokens.css` 是设计 Token 唯一真相源：生成 HTML 原型时需将 :root 变量块嵌入 `<style>`；React/TSX 需确保已 `@import` 引入。
+
+---
+
+## 验证清单 (Validation Checklist)
+
+> **通用检查项** 见 `../../docs/validation-workflow.md`。此处仅列出详情页特有检查项。
+
+| 检查项 | 检查点 | 目标 |
+|--------|--------|------|
+| 必需组件 | PageHeader、DescriptionList、DescriptionItem | 100% |
+| 嵌套约束 | PageContainer → ContentWrapper → Card → PageHeader + 内容 | 无违规 |
+| 禁止组件 | 无内联表单、DataTable 主内容区、QueryFilter | 0 个 |
+| PageHeader | 面包屑模式合规（`../../rules/page-header-spec.md` 15 项） | 全部通过 |
+| ContentCard 表面 (v7.6) | 无 1px border + shadow = var(--shadow-sm) | 0 违规 |
+| InfoCard 表面 (v7.6) | 模式 A 跟随主卡；模式 B 仅 padding + border-bottom | 0 违规 |
+| Card 间距 (v7.5) | padding = 0 var(--card-padding-x) = 20px | 正确 |
+| PageContainer 间距 | padding = var(--page-container-padding) = 16px | 正确 |
+| 功能性分割线 | PageHeader / Tabs / Separator 的 border 保留 | 不被误删 |
+| 操作按钮 | 前置条件、确认方式、异步处理 | 全部正确 |
+| Tab 切换 | 懒加载、URL hash、Empty | 正确 |
+| 返回约定 | 面包屑 + 关闭按钮(×) | 正确 |
+| 边界情况 | 无数据/加载中/失败/权限/404/空值 | 正确 |

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

@@ -0,0 +1,163 @@
+# API文档详情页 (api-doc-detail)
+
+> 路由自 `../SKILL.md`
+> 布局模式: 模式B + C 组合
+> 核心组件: ApiEndpoint + ParameterTable + CodeBlock + DescriptionList
+> PageHeader 规范: `../../../rules/page-header-spec.md`
+
+---
+
+## 1. 识别关键词
+
+`"API"` / `"接口"` / `"端点"` / `"文档"` / `"接口文档"` / `"模型API"`
+
+## 2. 核心特征
+
+- ApiEndpoint 端点信息（HTTP方法 + 路径 + 状态）
+- ParameterTable 参数表（请求/响应，支持嵌套展开）
+- CodeBlock 示例代码（多语言 Tab）
+- **代表场景**：模型 API 详情、服务接口文档、MCP Tool 文档
+
+## 3. 标准布局骨架
+
+```
+PageContainer
+  ↓
+ContentWrapper
+  ↓
+Card(白卡容器)
+  ├─ PageHeader (面包屑模式)
+  │  └─ 模型 API > API 列表 > 接口详情
+  │     [在线调试] [编辑] [×]
+  │
+  ├─ ApiEndpoint
+  │  └─ [POST] /v1/chat/completions  [已发布 ●]
+  │
+  ├─ DescriptionList — 基本信息
+  │  └─ 所属服务 | 关联模型 | 创建时间 | 调用次数 | 平均延迟
+  │
+  ├─ Tabs
+  │  ├─ 请求参数
+  │  │   └─ ParameterTable(type=request) — 可展开嵌套
+  │  ├─ 响应参数
+  │  │   └─ ParameterTable(type=response) — 可展开嵌套
+  │  ├─ 请求示例
+  │  │   └─ CodeBlock — 多语言 Tab(curl/Python/Node.js/Java)
+  │  └─ 响应示例
+  │      └─ CodeBlock — JSON 格式
+  │
+  └─ (无 Footer)
+```
+
+## 4. 必需组件
+
+| 组件 | 说明 |
+|------|------|
+| PageHeader | 面包屑模式 |
+| ApiEndpoint | API 端点概览卡 |
+| ParameterTable | 参数结构化展示 |
+| DescriptionList | 基本信息展示 |
+
+## 5. 条件组件
+
+| 组件 | 条件 | 说明 |
+|------|------|------|
+| CodeBlock | 有示例代码时 | 多语言代码块 |
+| Tabs | 参数分多类时 | 请求/响应/示例 |
+| Badge | 状态标识 | API 状态 |
+| Tooltip | 参数说明 | — |
+| Dialog | 操作确认 | — |
+
+## 6. 嵌套约束
+
+| 父子关系 | 状态 | 说明 |
+|----------|------|------|
+| Card → ApiEndpoint | ✅ ALLOW | 紧跟 PageHeader 之后 |
+| Tabs → ParameterTable | ✅ ALLOW | Tab 面板内展示参数 |
+| Tabs → CodeBlock | ✅ ALLOW | Tab 面板内展示示例 |
+| ParameterTable → ParameterTable | ✅ ALLOW | 嵌套参数展开 |
+| ApiEndpoint → Form | ❌ FORBID | Endpoint 为只读展示 |
+
+## 7. 交互规范
+
+| 操作 | 触发方式 | 行为 |
+|------|---------|------|
+| 复制端点 URL | 点击 ApiEndpoint 复制图标 | 复制完整 URL，Sonner "已复制" |
+| 展开嵌套参数 | 点击 ParameterTable 展开箭头 | 展开子参数行（缩进+连接线） |
+| 切换示例语言 | 点击 CodeBlock 内语言 Tab | 切换 curl/Python/Node.js/Java |
+| 在线调试 | 点击 PageHeader "在线调试" | 打开 Sheet(API Playground) 或跳转调试页 |
+| 复制示例代码 | 点击 CodeBlock 复制按钮 | 复制当前语言示例，Sonner "已复制" |
+
+## 8. 边界情况
+
+| 场景 | 处理方式 |
+|------|----------|
+| 无请求参数 | ParameterTable 展示"该接口无请求参数" |
+| 嵌套层级>3 | 最多展示 3 层，更深层显示 "..." + Tooltip |
+| 无示例代码 | CodeBlock 展示 "暂无示例" + "贡献示例" 链接 |
+| API 已下线 | ApiEndpoint 状态标红 + 顶部 Alert "该接口已下线" |
+| 参数过多(>30) | ParameterTable 默认折叠非必填参数 + "展示全部" |
+
+---
+
+## 9. 专用业务组件规格
+
+### CodeBlock — 代码/配置块
+
+| 属性 | 规格 |
+|------|------|
+| **用途** | 代码、配置文件(YAML/JSON/TOML)只读展示，支持语法高亮 |
+| **最小高度** | 120px |
+| **最大高度** | 480px（超出滚动） |
+| **内边距** | 16px |
+| **背景色** | `hsl(var(--gray-muted))` |
+| **圆角** | `var(--radius-md)` = 8px |
+| **字体** | `font-family: 'SF Mono', 'Fira Code', monospace; font-size: 13px; line-height: 1.6` |
+| **行号** | 左侧 40px 宽，颜色 `hsl(var(--muted-foreground))`，右侧 1px 分割线 |
+| **复制按钮** | 右上角固定，24×24px，hover 时显示 |
+| **折叠模式** | 超过 maxHeight 时底部渐变遮罩 + "展开全部(N行)" 按钮 |
+| **语言Tab** | 顶部内嵌 Tab（CodeBlock 内部），12px 字号，切换不同语言 |
+| **高亮** | 关键字=`hsl(var(--primary))`，字符串=`hsl(142 76% 36%)`，注释=`hsl(var(--muted-foreground))` |
+
+### ApiEndpoint — API 端点卡
+
+| 属性 | 规格 |
+|------|------|
+| **用途** | API 端点信息概览（HTTP方法 + 路径 + 状态） |
+| **容器高度** | 48px |
+| **容器背景** | `hsl(var(--gray-muted))` |
+| **容器圆角** | `var(--radius-md)` = 8px |
+| **容器内边距** | 0 16px |
+| **方法标签** | Badge 形式，圆角 4px，字号 12px/600，各方法颜色如下 |
+| **方法颜色** | GET=`hsl(218 100% 47%)`(蓝), POST=`hsl(142 76% 36%)`(绿), PUT=`hsl(40 88% 48%)`(橙), DELETE=`hsl(0 72% 51%)`(红), PATCH=`hsl(262 83% 58%)`(紫) |
+| **路径文字** | monospace, 14px/500, `hsl(var(--gray-primary))` |
+| **状态标识** | 右侧 Badge — 已发布=绿, 未发布=灰, 已下线=红 |
+| **复制图标** | 路径右侧，hover 显示，复制完整 URL |
+
+### ParameterTable — 参数表格
+
+| 属性 | 规格 |
+|------|------|
+| **用途** | API 请求/响应参数结构化展示 |
+| **表头** | 参数名 / 类型 / 必填 / 说明，高度 36px，背景 `hsl(var(--gray-muted))` |
+| **行高** | 40px |
+| **参数名字体** | monospace, 13px, `hsl(var(--gray-primary))` |
+| **类型标签** | Badge 形式, 12px, 背景浅色 — string=蓝, number=绿, boolean=橙, object=紫, array=青 |
+| **必填标识** | 红色星号 * 或 Badge "必填" |
+| **选填标识** | 灰色文字 "选填" |
+| **展开箭头** | 左侧 16px，有子参数时显示 ▶/▼ |
+| **子参数缩进** | 每层 24px，左侧 1px 竖线连接 |
+| **最大展开层级** | 3 层，更深显示 "..." |
+
+## 10. 验证清单
+
+> 通用检查项见 `../../../docs/validation-workflow.md`。此处仅列出 API 文档详情模式差异项。
+
+| 验证项 | 检查点 | 目标 |
+|--------|--------|------|
+| PageHeader | 面包屑模式合规（见 `rules/page-header-spec.md`） | 15 项全部通过 |
+| ApiEndpoint | 方法 Badge 颜色正确，容器高度 48px | 正确 |
+| ParameterTable | 嵌套缩进 24px/层，最多 3 层 | 正确 |
+| CodeBlock | 多语言 Tab 切换，复制功能正常 | 正确 |
+| 端点复制 | 复制完整 URL + Sonner | 正确 |
+| 下线状态 | ApiEndpoint 标红 + Alert 提示 | 正确 |