create-yss-spec 2.1.10 → 2.1.11

package/template/.cursor/skills/yss-ui/assets/docs/hooks/use-table-height.md

@@ -0,0 +1,101 @@
+---
+title: useTableHeight
+description: 动态计算表格高度的 Hook
+toc: content
+---
+
+# useTableHeight
+
+用于动态计算 `YTable` 或 `YEditTable` 的高度，使其在 Flex 容器中自适应。
+自动处理窗口缩放及容器尺寸变化，支持自动减去分页、工具栏等预设高度。
+
+## 核心思路
+
+Hook 通过 `ResizeObserver` 监听传入的父容器（`tableAreaRef`）高度，并根据配置减去内部固定元素（如分页、工具栏）的高度，从而计算出表格主体的精确 `height`。
+
+```
+容器 (固定高度/flex:1)
+├── 工具栏 (可选，Hook 可自动减去高度)
+├── 表格主体 (height = 容器高度 - 偏移量)
+└── 分页 (可选，Hook 可自动减去高度)
+```
+
+## 代码演示
+
+### 基础布局 (Flex)
+
+最常见的场景：页面整体采用 Flex 布局，表格占据中间剩余空间。
+使用 `withPagination` 和 `withToolbar` 自动扣除对应高度。
+
+<code id="flex-layout" src="./demos/useTableHeight/flex-layout/index.vue"></code>
+
+### 弹窗场景 (Modal)
+
+在 Modal 中固定内容高度，让表格撑满弹窗主体。
+
+<code id="in-modal" src="./demos/useTableHeight/in-modal/index.vue"></code>
+
+### 抽屉场景 (Drawer)
+
+在侧边抽屉中展示长列表，高度随抽屉高度自适应。
+
+<code id="in-drawer" src="./demos/useTableHeight/in-drawer/index.vue"></code>
+
+## API
+
+```typescript
+const { tableHeight, isReady, recalculateHeight } = useTableHeight(tableAreaRef, options?);
+```
+
+### Params
+
+| 参数         | 说明                                                                 | 类型                                                  | 默认值 |
+| ------------ | -------------------------------------------------------------------- | ----------------------------------------------------- | ------ |
+| tableAreaRef | 表格父容器引用，支持原生 DOM 或 Vue 组件实例（如 YCard） | `Ref<HTMLElement \| ComponentPublicInstance \| undefined>` | -      |
+| options      | 配置选项                                                             | `UseTableHeightOptions`                               | -      |
+
+> [!TIP]
+> 当 `ref` 绑定到 `YCard` 或 `AntCard` 组件时，Hook 会自动获取其内部的 `.ant-card-body` 元素进行高度计算，无需额外配置。
+
+### UseTableHeightOptions
+
+| 参数             | 说明                                                       | 类型      | 默认值  |
+| ---------------- | ---------------------------------------------------------- | --------- | ------- |
+| minHeight        | 最小高度限制                                               | `number`  | `200`   |
+| defaultHeight    | 初始默认高度                                               | `number`  | `400`   |
+| extraOffset      | 额外偏移量（用于边框、padding 等微调）                     | `number`  | `0`     |
+| withPagination   | 是否包含分页（减去 48px）                                  | `boolean` | `false` |
+| paginationHeight | 自定义分页高度，覆盖默认 48px                              | `number`  | -       |
+| withToolbar      | 是否包含工具栏（减去 48px）                                | `boolean` | `false` |
+| toolbarHeight    | 自定义工具栏高度，覆盖默认 48px                            | `number`  | -       |
+| withAddButton    | 是否包含添加按钮（减去 40px，仅 EditTable）                | `boolean` | `false` |
+| addButtonHeight  | 自定义添加按钮高度，覆盖默认 40px                          | `number`  | -       |
+
+### UseTableHeightReturn
+
+| 参数              | 说明                                                   | 类型            |
+| ----------------- | ------------------------------------------------------ | --------------- |
+| tableHeight       | 响应式的表格高度值                                     | `Ref<number>`   |
+| isReady           | 高度是否已计算完成，可用于条件渲染或加载状态判断       | `Ref<boolean>`  |
+| recalculateHeight | 手动重新计算高度（通常不需要，Hook 会自动监听）        | `() => void`    |
+
+## 最佳实践与注意事项
+
+1.  **容器样式**：`tableAreaRef` 指向的容器通常需要设置 `flex: 1` 和 `overflow: hidden`，以确保它能正确占据剩余空间且被 `ResizeObserver` 监听。
+
+2.  **支持组件 ref**：可以直接将 `ref` 绑定到 Vue 组件上，Hook 会自动获取其根 DOM 元素：
+    ```
+    <!-- 两种写法都支持 -->
+    <div ref="tableRef">...</div>
+    <YCard ref="tableRef">...</YCard>
+    ```
+
+3.  **高度传递**：计算出的 `tableHeight` 应直接传递给 `YTable` 或 `YEditTable` 的 `height` 属性。
+
+4.  **预设高度**：
+    - `withPagination`: 对应 `YTable` 内部的分页区域（默认 48px）
+    - `withToolbar`: 对应 `YTable` 顶部的工具栏（默认 48px）
+    - 如需自定义高度，使用 `paginationHeight` / `toolbarHeight` 覆盖默认值
+    - 如果使用非内置的自定义区域，建议将其放在 `tableAreaRef` 容器之外
+
+5.  **边界处理**：当容器高度极小时（如用户极端缩小窗口），Hook 会优先保证分页/工具栏可见，而非强制 `minHeight`，避免分页被遮挡。

package/template/.cursor/skills/yss-ui/assets/docs/hooks/use-tree-height.md

@@ -0,0 +1,115 @@
+---
+title: useTreeHeight
+description: 动态计算虚拟滚动树组件高度的 Hook
+toc: content
+---
+
+# useTreeHeight
+
+动态计算虚拟滚动树组件的可用高度，支持响应式监听容器尺寸变化。
+
+## 核心思路
+
+**使用 flex 布局让树区域自动填充剩余空间**，Hook 直接监听树区域高度，无需手动计算 offset：
+
+```
+容器 (固定高度 + flex 布局)
+├── 头部（搜索框、下拉框等）
+├── 树区域 (flex: 1, ref 传给 hook) ← Hook 监听这里
+└── 底部（操作按钮等）
+```
+
+## 代码演示
+
+### 基础用法
+
+使用 `ref` 指向树区域，Hook 自动监听其高度变化。
+
+<code id="demo1-basic" src="./demos/useTreeHeight/demo1-basic/index.vue"></code>
+
+### 头部 + 树区域
+
+展示带搜索框头部的常见布局，树区域使用 `flex: 1` 自动填充。
+
+<code id="demo2-ytree" src="./demos/useTreeHeight/demo2-ytree/index.vue"></code>
+
+### 头部 + 树区域 + 底部
+
+展示更复杂的三段式布局：头部下拉框 + 树区域 + 底部操作按钮。
+
+<code id="demo3-offset" src="./demos/useTreeHeight/demo3-offset/index.vue"></code>
+
+## API
+
+```typescript
+const { treeHeight, recalculateHeight } = useTreeHeight(treeAreaRef, options?);
+```
+
+### Params
+
+| 参数        | 说明                                      | 类型                               | 默认值 |
+| ----------- | ----------------------------------------- | ---------------------------------- | ------ |
+| treeAreaRef | 树区域 DOM 引用（建议使用 flex:1 自动填充） | `Ref<HTMLDivElement \| undefined>` | -      |
+| options     | 配置选项                                  | `UseTreeHeightOptions`             | -      |
+
+### UseTreeHeightOptions
+
+| 参数        | 说明                                   | 类型     | 默认值 |
+| ----------- | -------------------------------------- | -------- | ------ |
+| minHeight   | 最小高度限制                           | `number` | `200`  |
+| defaultHeight | 初始默认高度                         | `number` | `400`  |
+| extraOffset | 额外偏移量（用于边框、padding 等微调） | `number` | `0`    |
+
+### UseTreeHeightReturn
+
+| 参数              | 说明             | 类型          |
+| ----------------- | ---------------- | ------------- |
+| treeHeight        | 响应式的树高度值 | `Ref<number>` |
+| recalculateHeight | 手动重新计算高度 | `() => void`  |
+
+## 最佳实践
+
+### 推荐布局结构
+
+```
+<template>
+  <div class="container" style="height: 400px; display: flex; flex-direction: column;">
+    <!-- 头部区域：固定高度 -->
+    <div class="header">下拉框、搜索框</div>
+
+    <!-- 树区域：flex: 1 自动填充，ref 传给 hook -->
+    <div ref="treeAreaRef" style="flex: 1; overflow: hidden;">
+      <YTree :height="treeHeight" :filterable="false" :tree-data="treeData" />
+    </div>
+
+    <!-- 底部区域：固定高度（可选） -->
+    <div class="footer">操作按钮</div>
+  </div>
+</template>
+```
+
+### 注意事项
+
+1. **容器需要固定高度**：确保最外层容器有明确的高度（如 `height: 400px` 或 `height: 100%`）。
+
+2. **树区域使用 flex: 1**：让树区域自动填充剩余空间，Hook 监听这个区域的高度。
+
+3. **YTree 自带搜索框处理**：
+   - 如果自定义了头部搜索框，建议设置 `:filterable="false"` 禁用 YTree 内置搜索。
+   - 如果需要使用 YTree 内置搜索框，可使用 `extraOffset: YTREE_SEARCH_HEIGHT`（48px）扣除内部搜索框高度。
+
+4. **响应式监听**：Hook 内部使用 `ResizeObserver` 监听容器尺寸变化，无需手动触发。
+
+5. **手动触发**：特殊场景可调用 `recalculateHeight()` 手动触发计算。
+
+## 导出常量
+
+```typescript
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
+
+// YTREE_SEARCH_HEIGHT = 48，YTree 内置搜索框的固定高度
+const { treeHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT, // 当 YTree 启用 filterable 时使用
+});
+```
+

package/template/.cursor/skills/yss-ui/assets/docs/hooks/useFullscreen.md

@@ -0,0 +1,130 @@
+---
+title: useFullscreen
+description: 管理 DOM 全屏的 Hook
+toc: content
+---
+
+# useFullscreen
+
+管理 DOM 全屏的 Hook，支持真实全屏和页面全屏两种模式。
+
+## 代码演示
+
+### 基础用法
+
+使用 `ref` 设置需要全屏的元素。
+
+<code src="./demos/useFullscreen/demo1-basic.vue"></code>
+
+### 图片全屏
+
+使用函数形式传入目标元素，实现图片全屏效果。
+
+<code src="./demos/useFullscreen/demo2-image.vue"></code>
+
+### 页面全屏
+
+使用 `pageFullscreen` 配置启用页面全屏模式（伪全屏），通过 CSS fixed 定位实现，不使用浏览器全屏 API。
+
+<code src="./demos/useFullscreen/demo3-page.vue"></code>
+
+### 与其他全屏操作共存
+
+元素的全屏情况可能被其他脚本修改，useFullscreen 能正确追踪外部全屏状态变化。
+
+<code src="./demos/useFullscreen/demo4-coexist.vue"></code>
+
+## API
+
+```typescript
+const {
+  isFullscreen,
+  enterFullscreen,
+  exitFullscreen,
+  toggleFullscreen,
+  isEnabled,
+} = useFullscreen(target, options?);
+```
+
+### Params
+
+| 参数    | 说明             | 类型                                                                 | 默认值 |
+| ------- | ---------------- | -------------------------------------------------------------------- | ------ |
+| target  | 目标元素         | `HTMLElement` \| `Ref<HTMLElement>` \| `() => HTMLElement \| null` | -      |
+| options | 配置选项         | `UseFullscreenOptions`                                               | -      |
+
+### UseFullscreenOptions
+
+| 参数           | 说明                                                                   | 类型                                                   | 默认值  |
+| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ | ------- |
+| onEnter        | 进入全屏时的回调                                                       | `() => void`                                           | -       |
+| onExit         | 退出全屏时的回调                                                       | `() => void`                                           | -       |
+| pageFullscreen | 是否使用页面全屏模式。当参数类型为对象时，可以设置全屏元素的类名和 `z-index` | `boolean` \| `{ className?: string, zIndex?: number }` | `false` |
+| escTip         | Esc 键退出提示配置。`true` 显示默认提示，`string` 自定义文案，`false` 不显示 | `boolean` \| `string`                                  | `true`  |
+
+### UseFullscreenReturn
+
+| 参数             | 说明                 | 类型                  |
+| ---------------- | -------------------- | --------------------- |
+| isFullscreen     | 是否处于全屏状态     | `Readonly<Ref<boolean>>` |
+| enterFullscreen  | 进入全屏             | `() => void`          |
+| exitFullscreen   | 退出全屏             | `() => void`          |
+| toggleFullscreen | 切换全屏状态         | `() => void`          |
+| isEnabled        | 浏览器是否支持全屏   | `boolean`             |
+
+## 注意事项
+
+1. **浏览器兼容性**：Fullscreen API 在某些旧版浏览器中可能不支持，可以通过 `isEnabled` 属性检查支持状态。
+
+2. **用户手势要求**：浏览器要求全屏操作必须由用户手势触发（如点击事件），不能在页面加载时自动全屏。
+
+3. **页面全屏 vs 真实全屏**：
+   - **真实全屏**：使用浏览器 Fullscreen API，会隐藏浏览器界面，用户可以按 `ESC` 键退出
+   - **页面全屏**：通过 CSS 实现，只是让元素覆盖整个视口，不会隐藏浏览器界面
+
+4. **样式隔离**：页面全屏模式会动态创建 `<style>` 标签，默认类名为 `yss-page-fullscreen`，可以通过配置自定义。
+
+5. **Esc 键提示**：进入全屏时会自动显示"若要退出全屏模式，请按 esc"提示，3 秒后自动隐藏。可以通过 `escTip` 配置自定义提示文案或禁用提示。
+
+## 类型定义
+
+```typescript
+export interface PageFullscreenOptions {
+  /** 全屏元素的类名 */
+  className?: string;
+  /** 全屏元素的 z-index */
+  zIndex?: number;
+}
+
+export interface UseFullscreenOptions {
+  /** 退出全屏时的回调 */
+  onExit?: () => void;
+  /** 进入全屏时的回调 */
+  onEnter?: () => void;
+  /** 是否使用页面全屏模式（伪全屏），或传入配置对象 */
+  pageFullscreen?: boolean | PageFullscreenOptions;
+  /** 
+   * Esc 键退出提示配置
+   * - true: 显示默认提示"若要退出全屏模式，请按 esc"
+   * - string: 自定义提示文案
+   * - false: 不显示提示
+   * @default true
+   */
+  escTip?: boolean | string;
+}
+
+export type Target = HTMLElement | Ref<HTMLElement | undefined> | (() => HTMLElement | null);
+
+export interface UseFullscreenReturn {
+  /** 是否处于全屏状态 */
+  isFullscreen: Readonly<Ref<boolean>>;
+  /** 进入全屏 */
+  enterFullscreen: () => void;
+  /** 退出全屏 */
+  exitFullscreen: () => void;
+  /** 切换全屏状态 */
+  toggleFullscreen: () => void;
+  /** 浏览器是否支持全屏 */
+  isEnabled: boolean;
+}
+```

package/template/.cursor/skills/yss-ui/assets/docs/hooks/useLoading.md

@@ -0,0 +1,97 @@
+---
+title: useLoading
+description: 管理异步加载状态的 Hook
+toc: content
+---
+
+# useLoading
+
+管理异步请求的加载状态，支持自动控制和手动控制两种模式。
+
+## 代码演示
+
+### 基础用法
+
+使用 `withLoading` 包装异步函数，自动控制加载状态。
+
+<code src="./demos/useLoading/use-loading-basic.vue"></code>
+
+### 手动控制
+
+使用 `setLoading` 和 `toggleLoading` 手动控制加载状态。
+
+<code src="./demos/useLoading/use-loading-manual.vue"></code>
+
+## API
+
+```typescript
+const {
+  loading,
+  setLoading,
+  withLoading,
+  toggleLoading,
+} = useLoading(initialValue?);
+```
+
+### Params
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| initialValue | 初始加载状态 | `boolean` | `false` |
+
+### UseLoadingReturn
+
+| 参数 | 说明 | 类型 |
+| --- | --- | --- |
+| loading | 当前加载状态（响应式） | `Ref<boolean>` |
+| setLoading | 设置加载状态 | `(value: boolean) => void` |
+| withLoading | 包装异步函数，自动控制加载状态 | `<T>(fn: () => Promise<T>, options?: WithLoadingOptions) => Promise<T \| undefined>` |
+| toggleLoading | 切换加载状态 | `() => void` |
+
+### WithLoadingOptions
+
+`withLoading` 方法的配置选项：
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| onSuccess | 成功回调函数 | `(result: T) => void` | - |
+| onError | 错误回调函数 | `(error: Error) => void` | - |
+| onFinally | 完成回调（无论成功/失败都会触发） | `() => void` | - |
+| keepLoadingOnError | 发生错误时是否保持 loading 状态 | `boolean` | `false` |
+| rethrowError | 是否重新抛出错误（设为 false 可防止白屏） | `boolean` | `false` |
+
+:::info{title=命名说明}
+- **onSuccess**：异步函数成功执行后触发，可以获取返回值
+- **onError**：异步函数内部抛出错误（接口异常/JS 报错）时触发
+- **onFinally**：类似 try-catch-finally 的 finally，无论成功或失败都会触发
+- **rethrowError**：默认 `false`，错误会被捕获，通过 `onError` 通知，防止未捕获的 Promise rejection 导致白屏
+:::
+
+## 使用场景
+
+- ✅ 按钮点击触发异步请求
+- ✅ 表单提交时显示加载状态
+- ✅ 数据列表刷新时显示加载动画
+- ✅ 多个并发请求的统一加载状态管理
+
+## 类型定义
+
+```typescript
+interface WithLoadingOptions<T = any> {
+  onSuccess?: (result: T) => void;
+  onError?: (error: Error) => void;
+  onFinally?: () => void;
+  keepLoadingOnError?: boolean;
+  rethrowError?: boolean;
+}
+
+export function useLoading(initialValue?: boolean): {
+  loading: Ref<boolean>;
+  setLoading: (value: boolean) => void;
+  withLoading: <T>(
+    fn: () => Promise<T>,
+    options?: WithLoadingOptions<T>
+  ) => Promise<T | undefined>;
+  toggleLoading: () => void;
+}
+```

package/template/.cursor/skills/yss-ui/assets/docs/root/resources.md

@@ -0,0 +1,18 @@
+---
+title: 资源
+order: 99
+---
+
+# 资源
+
+本文收敛 Formily 生态与内部平台的常用入口，便于统一查阅与跳转。
+
+## Formily 生态
+
+- **Formily Core（内核 API）**：[`https://core.formilyjs.org/zh-CN/api/entry/create-form#iformprops`](https://core.formilyjs.org/zh-CN/api/entry/create-form#iformprops)
+- **Ant Design Vue Formily 文档**：[`https://antdv.formilyjs.org/guide/`](https://antdv.formilyjs.org/guide/)
+- **Formily Vue 组件 API**：[`https://vue.formilyjs.org/api/components/field.html`](https://vue.formilyjs.org/api/components/field.html)
+
+## 内部平台
+
+- **雨燕 · 生成微应用脚手架**：[`http://192.168.164.27:3100/`](http://192.168.164.27:3100/)

package/template/.cursor/skills/yss-ui/assets/keyword-index.json

@@ -0,0 +1,53 @@
+{
+  "keywords": [
+    {
+      "keyword": "审批流程列表",
+      "scenario": "列表管理页（查询 + 分页 + 操作）",
+      "docs": ["./docs/components/table.md"],
+      "demos": ["./demos/table/basic", "./demos/table/action"]
+    },
+    {
+      "keyword": "节点设计",
+      "scenario": "可编辑表格（行内编辑）",
+      "docs": ["./docs/components/editTable.md"],
+      "demos": ["./demos/edit-table/row-edit", "./demos/edit-table/slot-linkage"]
+    },
+    {
+      "keyword": "树表联动",
+      "scenario": "树表联动页面（左树右表）",
+      "docs": ["./docs/components/tree.md", "./docs/components/split-pane.md"],
+      "demos": ["./demos/split-pane/tree-table-layout"]
+    },
+    {
+      "keyword": "新增编辑查看",
+      "scenario": "JSON Schema 表单（新增/编辑/查看）",
+      "docs": ["./docs/components/formily.md"],
+      "demos": ["./demos/formily/modes.vue"]
+    },
+    {
+      "keyword": "文件导入",
+      "scenario": "文件导入两步流",
+      "docs": ["./docs/components/fileImport.md"],
+      "demos": ["./demos/file-import/basic.vue", "./demos/file-import/formily.vue"]
+    },
+    {
+      "keyword": "代码编辑器",
+      "scenario": "代码编辑与日志查看",
+      "docs": ["./docs/components/monaco.md"],
+      "demos": ["./demos/monaco/monaco.vue", "./demos/monaco/log-viewer.vue"]
+    },
+    {
+      "keyword": "图表分析",
+      "scenario": "图表分析页",
+      "docs": ["./docs/components/echarts.md"],
+      "demos": ["./demos/echarts/mix.vue", "./demos/echarts/line.vue"]
+    },
+    {
+      "keyword": "表格高度",
+      "scenario": "表格高度自适应",
+      "docs": ["./docs/hooks/use-table-height.md"],
+      "demos": ["./demos/table/basic"]
+    }
+  ],
+  "status": "validated"
+}

package/template/.cursor/skills/yss-ui/assets/keyword-index.md

@@ -0,0 +1,47 @@
+# yss-ui 关键词反查索引
+
+## 使用方式
+
+- 按关键词找到对应“场景 + 文档 + Demo”。
+- 同一关键词命中多个条目时，优先选择最贴近当前业务目标的场景。
+- 对复杂需求可组合多个关键词逐步定位。
+
+---
+
+## 关键词映射
+
+| 关键词       | 场景                               | 文档                                                           | Demo                                                             |
+| ------------ | ---------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
+| 审批流程列表 | 列表管理页（查询 + 分页 + 操作）   | `./docs/components/table.md`                                   | `./demos/table/basic`、`./demos/table/action`                    |
+| 待我审批     | 列表管理页（查询 + 分页 + 操作）   | `./docs/components/table.md`                                   | `./demos/table/pagination-remote`                                |
+| 抽屉详情     | 列表管理页（查询 + 分页 + 操作）   | `./docs/components/table.md`                                   | `./demos/table/action-slot`                                      |
+| 节点设计     | 可编辑表格（行内编辑）             | `./docs/components/editTable.md`                               | `./demos/edit-table/row-edit`、`./demos/edit-table/slot-linkage` |
+| 行内编辑     | 可编辑表格（行内编辑）             | `./docs/components/editTable.md`                               | `./demos/edit-table/row-edit`                                    |
+| 远程分页     | 列表管理页（查询 + 分页 + 操作）   | `./docs/components/table.md`                                   | `./demos/table/pagination-remote`                                |
+| 远程筛选     | 远程筛选列表页                     | `./docs/components/table.md`                                   | `./demos/table/filter-remote`                                    |
+| 树表联动     | 树表联动页面（左树右表）           | `./docs/components/tree.md`、`./docs/components/split-pane.md` | `./demos/split-pane/tree-table-layout`                           |
+| 左树右表     | 树表联动页面（左树右表）           | `./docs/components/split-pane.md`                              | `./demos/split-pane/tree-table`                                  |
+| 组织树选择   | 组织树/资源树选择                  | `./docs/components/tree.md`                                    | `./demos/tree/multiple-select`、`./demos/tree/multi-checkable`   |
+| 新增编辑查看 | JSON Schema 表单（新增/编辑/查看） | `./docs/components/formily.md`                                 | `./demos/formily/modes.vue`                                      |
+| 表单联动     | 表单联动与异步校验                 | `./docs/components/formily.md`                                 | `./demos/formily/linkage.vue`                                    |
+| 异步校验     | 表单联动与异步校验                 | `./docs/components/formily.md`                                 | `./demos/formily/async-validate.vue`                             |
+| 分步表单     | JSON Schema 表单（新增/编辑/查看） | `./docs/components/formily.md`                                 | `./demos/formily/steps.vue`                                      |
+| 文件导入     | 文件导入两步流                     | `./docs/components/fileImport.md`                              | `./demos/file-import/basic.vue`                                  |
+| 导入结果确认 | 文件导入两步流                     | `./docs/components/fileImport.md`                              | `./demos/file-import/formily.vue`                                |
+| 条件构造器   | 条件构造器                         | `./docs/components/conditionBuilder.md`                        | `./demos/condition-builder/basic`                                |
+| cron 表达式  | Cron 配置                          | `./docs/components/cron.md`                                    | `./demos/cron/basic`                                             |
+| 代码编辑器   | 代码编辑与日志查看                 | `./docs/components/monaco.md`                                  | `./demos/monaco/monaco.vue`                                      |
+| 日志查看     | 代码编辑与日志查看                 | `./docs/components/monaco.md`                                  | `./demos/monaco/log-viewer.vue`                                  |
+| 全屏预览     | 代码编辑与日志查看                 | `./docs/hooks/useFullscreen.md`                                | `./demos/monaco/fullscreen.vue`                                  |
+| 图表分析     | 图表分析页                         | `./docs/components/echarts.md`                                 | `./demos/echarts/mix.vue`、`./demos/echarts/line.vue`            |
+| 指标卡片     | 卡片化指标看板                     | `./docs/components/card.md`                                    | `./demos/card/layout-metrics`                                    |
+| 权限按钮     | 权限按钮与操作态                   | `./docs/components/button.md`                                  | `./demos/button/permission.vue`                                  |
+| 表格高度     | 表格高度自适应                     | `./docs/hooks/use-table-height.md`                             | `./demos/table/basic`                                            |
+| 树高度       | 树高度自适应                       | `./docs/hooks/use-tree-height.md`                              | `./demos/tree/search-toolbar`                                    |
+
+---
+
+## 快速建议
+
+- 若关键词无法唯一命中，先打开 `./scenario-index.md` 按场景二次筛选。
+- 若关键词未覆盖，优先补充到本文件并同步更新 `keyword-index.json`。

package/template/.cursor/skills/yss-ui/assets/reference-index.json

@@ -0,0 +1,55 @@
+{
+  "sourceFiles": [
+    "../SKILL.md",
+    "../references/quick-recipes.md",
+    "../references/checklist.md"
+  ],
+  "docsRoot": "./docs",
+  "demosRoot": "./demos",
+  "scenarioIndex": "./scenario-index.md",
+  "scenarioIndexJson": "./scenario-index.json",
+  "keywordIndex": "./keyword-index.md",
+  "keywordIndexJson": "./keyword-index.json",
+  "docReferences": [
+    "components/table.md",
+    "components/editTable.md",
+    "components/formily.md",
+    "components/tree.md",
+    "components/split-pane.md",
+    "components/monaco.md",
+    "components/echarts.md",
+    "components/fileImport.md",
+    "components/conditionBuilder.md",
+    "components/cron.md",
+    "components/card.md",
+    "components/button.md",
+    "components/sheet.md",
+    "hooks/use-table-height.md",
+    "hooks/use-tree-height.md",
+    "hooks/useFullscreen.md",
+    "hooks/useLoading.md",
+    "guide/index.md",
+    "guide/installation.md",
+    "guide/jsp.md",
+    "guide/llms.md",
+    "guide/release-workflow.md",
+    "guide/gitlab-ci-integration.md",
+    "guide/monorepo-versioning.md",
+    "root/resources.md"
+  ],
+  "demoReferences": [
+    "table/*",
+    "edit-table/*",
+    "formily/*",
+    "tree/*",
+    "split-pane/*",
+    "monaco/*",
+    "echarts/*",
+    "file-import/*",
+    "condition-builder/*",
+    "cron/*",
+    "card/*",
+    "button/*"
+  ],
+  "status": "validated"
+}