harveyz-skill 0.6.2 → 0.7.0

package/skills/design/sync-design-html/references/stack-nextjs.md

@@ -0,0 +1,101 @@
+# Next.js 技术栈指南
+
+适用于 Next.js 13+（App Router）和 Next.js 12 以下（Pages Router）。
+
+> **使用方式：** 同步时从 manifest 读取 `styleStrategy` 字段，只执行"源文件读取策略"中对应策略的那一节。若 `notes` 字段非空，以 `notes` 覆盖本文件中的冲突建议。样式方案细节参考 `stack-react.md`。
+
+---
+
+## 发现命令
+
+```bash
+# 判断 App Router 还是 Pages Router
+ls app/ src/app/ pages/ src/pages/ 2>/dev/null
+
+# App Router：发现页面和布局文件
+find app src/app -type f -name "page.tsx" -o -name "layout.tsx" -o -name "loading.tsx" -o -name "error.tsx" \
+  | grep -v node_modules | sort
+
+# Pages Router：发现页面文件
+find pages src/pages -type f \( -name "*.tsx" -o -name "*.jsx" \) \
+  | grep -v node_modules | grep -v "_app" | grep -v "_document" | grep -v "api" | sort
+
+# 发现共享组件
+find components src/components -type f \( -name "*.tsx" -o -name "*.jsx" \) \
+  | grep -v node_modules | sort
+
+# 设计系统文件候选
+ls tailwind.config.js tailwind.config.ts \
+   styles/globals.css src/styles/globals.css \
+   styles/tokens.css src/styles/tokens.css \
+   lib/theme.ts src/lib/theme.ts 2>/dev/null
+```
+
+---
+
+## 平台配置模板
+
+**App Router：**
+```json
+{
+  "web": {
+    "label": "Web",
+    "stackRef": "references/stack-nextjs.md",
+    "uiFilePatterns": [
+      "app/**/page.tsx",
+      "app/**/layout.tsx"
+    ],
+    "designSystemFile": "<token 文件或 null>"
+  }
+}
+```
+
+**Pages Router：**
+```json
+{
+  "web": {
+    "label": "Web",
+    "stackRef": "references/stack-nextjs.md",
+    "uiFilePatterns": [
+      "pages/**/*.tsx",
+      "src/pages/**/*.tsx"
+    ],
+    "designSystemFile": "<token 文件或 null>"
+  }
+}
+```
+
+---
+
+## 源文件读取策略
+
+### App Router 特有
+
+- **`page.tsx`**：页面主体，是主要的 UI 源文件
+- **`layout.tsx`**：包裹 page 的壳（导航栏、侧边栏等）。若 page 的外观依赖 layout，同时读取最近一层的 layout.tsx
+- **`loading.tsx`**：骨架屏或加载态，是一个独立的 `uiState`
+- **`error.tsx`**：错误态，也是独立的 `uiState`
+- **Server Components vs Client Components**：对 HTML 生成无影响，都读取 `return` 的 JSX 结构
+
+### 路由参数
+
+- `[id]`、`[slug]` 等动态段在 HTML 备份中用占位值替代（如 `123`、`example-post`）
+
+### Metadata
+
+- `export const metadata = { title: '...' }` → 设置 HTML `<title>`
+
+### 样式方案
+
+参考 `stack-react.md` 中对应样式方案的读取策略（Tailwind / CSS Modules / styled-components）。
+
+---
+
+## 常见 Gotchas
+
+- **API Routes**：`app/api/` 或 `pages/api/` 下的文件不是 UI，`uiFilePatterns` 中排除（用 `grep -v api` 过滤）
+- **`_app.tsx` / `_document.tsx`**：全局配置文件，不直接对应某个界面；若影响全局样式（如注入 CSS 变量），在生成 HTML 时纳入上下文
+- **Middleware**：`middleware.ts` 不是 UI 文件
+- **图片优化**：`<Image>` 组件 → HTML 中用 `<img>` 替代，设置对应的 `width`/`height`/`object-fit`
+- **Link 组件**：`<Link href="...">` → HTML 中用 `<a>` 替代
+- **`use client` / `use server`**：不影响 HTML 生成，忽略这些指令

package/skills/design/sync-design-html/references/stack-react.md

@@ -0,0 +1,117 @@
+# React 技术栈指南
+
+适用于 React + Vite / CRA / 纯 React 项目（不含 Next.js，见 stack-nextjs.md）。
+
+> **使用方式：** 同步时从 manifest 读取 `styleStrategy` 字段，只执行下方"源文件读取策略"中对应策略的那一节，忽略其他节。若 `styleStrategy` 为 `unknown`，则读取源文件内容后自行判断。若 `notes` 字段非空，以 `notes` 覆盖本文件中的冲突建议。
+
+---
+
+## 发现命令
+
+```bash
+# 发现页面/视图级组件（优先）
+find src -type f \( -name "*.tsx" -o -name "*.jsx" \) \
+  | grep -v node_modules | grep -v __tests__ | grep -v ".test." | grep -v ".spec." \
+  | grep -E "(pages|views|screens|Page|View|Screen)" | sort
+
+# 发现所有 React 组件（若上面结果太少）
+find src -type f \( -name "*.tsx" -o -name "*.jsx" \) \
+  | grep -v node_modules | grep -v __tests__ | grep -v ".test." | grep -v ".spec." | sort
+
+# 发现设计系统文件候选
+ls src/styles/tokens.css src/styles/variables.css src/styles/theme.ts src/theme.ts \
+   src/styles/design-tokens.ts tailwind.config.js tailwind.config.ts \
+   src/design-system/index.ts 2>/dev/null
+```
+
+---
+
+## 平台配置模板
+
+```json
+{
+  "web": {
+    "label": "Web",
+    "stackRef": "references/stack-react.md",
+    "uiFilePatterns": [
+      "src/pages/**/*.tsx",
+      "src/views/**/*.tsx"
+    ],
+    "designSystemFile": "<检测到的 token 文件，或 null>"
+  }
+}
+```
+
+`uiFilePatterns` 根据发现命令的实际结果推导目录层级，优先选择 `pages/`、`views/`、`screens/` 等语义目录，避免把整个 `src/components/**` 都纳入（太宽泛）。
+
+---
+
+## 样式方案识别
+
+初始化时检测项目使用的样式方案，记录到 manifest 的平台配置中（`styleStrategy` 字段）：
+
+```bash
+# 检测 Tailwind
+ls tailwind.config.js tailwind.config.ts 2>/dev/null
+grep -r "tailwindcss" package.json 2>/dev/null
+
+# 检测 CSS Modules
+find src -name "*.module.css" -o -name "*.module.scss" | head -3 2>/dev/null
+
+# 检测 styled-components / emotion
+grep -E '"styled-components"|"@emotion/react"' package.json 2>/dev/null
+
+# 检测 CSS-in-JS (vanilla-extract, stitches, etc.)
+grep -E '"@vanilla-extract"|"@stitches"' package.json 2>/dev/null
+```
+
+---
+
+## 源文件读取策略
+
+### Tailwind CSS
+
+- 读取 `tailwind.config.js` / `tailwind.config.ts` 中的 `theme.extend`，提取自定义颜色、字体、间距
+- class 名（如 `text-sm font-medium text-gray-700`）映射为实际 CSS 值，写入 HTML `<style>` 块中
+- 不要直接在 HTML 中使用 Tailwind class（离线时无法渲染）
+- 颜色：`text-gray-700` → `color: #374151`；布局：`flex flex-col gap-4` → `display:flex; flex-direction:column; gap:1rem`
+
+### CSS Modules
+
+- 同时读取与源文件同名的 `.module.css` / `.module.scss`
+- 将 class 中的样式声明提取到 HTML `<style>` 块中
+- `styles.container` → 对应 `.container` 选择器的内容
+
+### styled-components / emotion
+
+- CSS 定义内联在 JS 中，从组件定义处提取样式字符串
+- 动态样式（依赖 props 的）取默认态或最常见态的值
+
+### 普通 CSS / SCSS
+
+- 读取源文件 `import` 的 CSS 文件，提取相关规则
+
+### 内联 style prop
+
+- 直接转换为 HTML `style` 属性
+
+---
+
+## 组件 Props 与 UI 状态
+
+React 组件的 UI 状态通常来自：
+- `useState`：`const [isLoading, setIsLoading] = useState(false)`
+- Props：`interface Props { variant: 'primary' | 'ghost'; disabled?: boolean }`
+- 外部 store（Zustand/Redux）：查看组件订阅的 slice
+
+识别 UI 状态时，检查 TypeScript 类型定义和 `if/switch` 条件渲染分支，这些分支就是需要在 HTML 中体现的 `uiStates`。
+
+---
+
+## 常见 Gotchas
+
+- **Context / Provider**：`ThemeProvider`、`AuthContext` 等 wrapper 不需要在 HTML 中体现，只还原视觉层
+- **lazy import**：`React.lazy(() => import('./Page'))` 中的组件路径是真实源文件，正常处理
+- **动态 className**：`clsx(styles.btn, { [styles.active]: isActive })` → 生成所有可能的 class 组合，在 HTML 中用独立区块展示各状态
+- **图片 / SVG import**：`import logo from './logo.svg'` → HTML 中用占位矩形替代，标注尺寸和描述
+- **国际化字符串**：`t('key')` → 保留 key 名或使用中文描述性文字

package/skills/design/sync-design-html/references/stack-swiftui.md

@@ -0,0 +1,115 @@
+# SwiftUI 技术栈指南
+
+适用于 iOS / macOS / visionOS 的 SwiftUI 项目，支持单平台和多平台双目录结构。
+
+---
+
+## 发现命令
+
+```bash
+# 发现 iOS UI 文件
+find . -type f \( -name "*View.swift" -o -name "*Screen.swift" \) \
+  | grep -v ".build" | grep -v "Tests" | grep -v "Preview" | sort
+
+# 发现 macOS UI 文件（常在单独目录）
+find . -type f \( -name "*View.swift" -o -name "*Section.swift" -o -name "*Card.swift" \) \
+  | grep -v ".build" | grep -v "Tests" | sort
+
+# 发现设计系统文件
+find . -type f \( -name "*DesignSystem.swift" -o -name "*Theme.swift" -o -name "*Style.swift" \) \
+  | grep -v ".build" | grep -v "Tests" | head -5
+```
+
+将发现的文件按目录分组，推导出各平台的目录前缀，生成 patterns。
+
+---
+
+## 平台识别逻辑
+
+SwiftUI 项目通常有两种结构：
+
+**单 target（iOS/macOS 共用）：**
+```json
+{
+  "app": {
+    "label": "App",
+    "uiFilePatterns": ["<AppModule>/**/*View.swift", "<AppModule>/**/*Screen.swift"],
+    "designSystemFile": "<AppModule>/<Name>DesignSystem.swift"
+  }
+}
+```
+
+**双 target（iOS + macOS 分离目录）：**
+```json
+{
+  "ios": {
+    "label": "iOS",
+    "uiFilePatterns": ["<iOSModule>/**/*View.swift", "<iOSModule>/**/*Screen.swift"],
+    "designSystemFile": "<iOSModule>/<Name>DesignSystem.swift"
+  },
+  "macos": {
+    "label": "macOS",
+    "uiFilePatterns": ["<macOSModule>/**/*View.swift", "<macOSModule>/**/*Section.swift", "<macOSModule>/**/*Card.swift"],
+    "designSystemFile": "<macOSModule>/<Name>DesignSystem.swift"
+  }
+}
+```
+
+检测到 UI 文件后，通过目录路径判断是单 target 还是双 target，告知用户并按需拆分。
+
+---
+
+## 设计系统文件候选
+
+```bash
+find . -name "*DesignSystem.swift" -o -name "*Theme.swift" -o -name "*Tokens.swift" \
+  | grep -v ".build" | grep -v Tests
+```
+
+SwiftUI 的设计 token 通常以 `Color` 扩展、`Font` 扩展、`CGFloat` 常量的形式定义：
+
+```swift
+extension Color {
+    static let background = Color("Background")
+    static let accent = Color("AccentColor")
+}
+extension CGFloat {
+    static let cornerRadius: CGFloat = 12
+    static let spacing: CGFloat = 16
+}
+```
+
+---
+
+## 源文件读取策略
+
+SwiftUI 视图是声明式的，一个文件通常完整描述一个界面。读取时：
+
+1. **读主视图文件**：包含 `body` 的 `View` struct
+2. **识别 UI 状态来源**：
+   - `@State private var isLoading: Bool` → state 驱动
+   - `enum ViewState { case idle, loading, error }` → 枚举驱动
+   - 函数参数 / `@Binding` → 外部注入
+3. **处理子视图**：若文件中有 `SomeChildView()` 调用且子视图影响视觉，读取对应文件。优先处理项目内部自定义组件；系统组件（`Button`、`List`、`NavigationView`）凭知识推断。
+4. **读取设计系统文件**：提取颜色常量名、字体定义、间距值，用于生成 CSS 变量。
+
+---
+
+## HTML 生成注意事项
+
+- SwiftUI 的颜色常量名（如 `Color.accent`）直接映射为 CSS 变量名（`--accent`）
+- `cornerRadius`、`padding`、`spacing` 等 `CGFloat` 常量转换为对应 CSS 值（px）
+- `HStack`/`VStack`/`ZStack` → `display: flex` + `flex-direction`
+- `LazyVGrid`/`LazyHGrid` → `display: grid`
+- `.frame(width:height:)` → `width`/`height`，`.frame(maxWidth: .infinity)` → `width: 100%`
+- Dark mode（`.colorScheme`）→ `@media (prefers-color-scheme: dark)`
+- SF Symbols 用 Unicode 字符或 emoji 近似替代，不引用外部图标库
+
+---
+
+## 常见 Gotchas
+
+- **Preview 文件**：`*_Previews.swift` 或 `PreviewProvider` 不是 UI 源文件，检测时排除
+- **SwiftUI Representable**：`UIViewRepresentable` / `NSViewRepresentable` 包装的 UIKit/AppKit 视图，HTML 生成时只还原视觉外观，不还原底层实现
+- **条件编译**：`#if os(iOS)` 块注意按平台分别处理
+- **Assets Catalog**：颜色可能定义在 `.xcassets` 而非 Swift 代码，读设计系统文件时若颜色名以字符串引用（`Color("Background")`），需在 Assets 中查找实际值

package/skills/design/sync-design-html/references/stack-vue.md

@@ -0,0 +1,142 @@
+# Vue / Nuxt 技术栈指南
+
+适用于 Vue 3 + Vite、Vue 2、以及 Nuxt 3 / Nuxt 2 项目。
+
+> **使用方式：** 同步时从 manifest 读取 `styleStrategy` 字段，只执行"样式方案"中对应策略的那一节。若 `notes` 字段非空，以 `notes` 覆盖本文件中的冲突建议。
+
+---
+
+## 发现命令
+
+```bash
+# 判断是否为 Nuxt
+ls nuxt.config.ts nuxt.config.js 2>/dev/null
+
+# Nuxt 3：发现页面文件
+find pages -type f -name "*.vue" | grep -v node_modules | sort
+
+# Vue 通用：发现视图/页面组件
+find src -type f -name "*.vue" \
+  | grep -v node_modules | grep -v __tests__ | grep -v ".test." \
+  | grep -E "(views|pages|screens|layouts)" | sort
+
+# Vue 通用：发现所有组件
+find src -type f -name "*.vue" \
+  | grep -v node_modules | grep -v __tests__ | sort
+
+# 设计系统文件候选
+ls src/styles/variables.css src/styles/tokens.css \
+   src/styles/variables.scss src/assets/styles/variables.scss \
+   src/theme.ts src/plugins/theme.ts \
+   tailwind.config.js tailwind.config.ts \
+   uno.config.ts 2>/dev/null
+```
+
+---
+
+## 平台配置模板
+
+**Vue + Vite：**
+```json
+{
+  "web": {
+    "label": "Web",
+    "stackRef": "references/stack-vue.md",
+    "uiFilePatterns": [
+      "src/views/**/*.vue",
+      "src/pages/**/*.vue"
+    ],
+    "designSystemFile": "<token 文件或 null>"
+  }
+}
+```
+
+**Nuxt 3：**
+```json
+{
+  "web": {
+    "label": "Web",
+    "stackRef": "references/stack-vue.md",
+    "uiFilePatterns": [
+      "pages/**/*.vue",
+      "layouts/**/*.vue"
+    ],
+    "designSystemFile": "<token 文件或 null>"
+  }
+}
+```
+
+---
+
+## 源文件读取策略
+
+### 单文件组件（SFC）结构
+
+Vue SFC（`.vue`）把模板、脚本、样式放在同一文件：
+
+```vue
+<template>  ← UI 结构，重点读取
+<script setup lang="ts">  ← 状态定义
+<style scoped>  ← 局部样式，直接使用
+```
+
+读取顺序：
+1. 先读 `<template>` 确定 UI 结构和状态分支
+2. 读 `<script setup>` 中的 `ref`、`computed`、`defineProps` 确定状态来源
+3. 读 `<style scoped>` / `<style module>` 提取样式规则，直接内联到 HTML `<style>` 中
+
+### Composition API 状态识别
+
+```ts
+const isLoading = ref(false)           // → uiState: loading
+const error = ref<string | null>(null)  // → uiState: error
+const props = defineProps<{            // → 多态变体
+  variant: 'primary' | 'ghost'
+}>()
+```
+
+### Options API 状态识别
+
+```js
+data() {
+  return { isOpen: false, activeTab: 'general' }
+}
+computed: {
+  isEmpty() { return this.items.length === 0 }
+}
+```
+
+### 样式方案
+
+**`<style scoped>`（最常见）：**
+直接提取样式规则，添加到 HTML `<style>` 中（去掉 scoped 特性）。
+
+**`<style module>`：**
+通过 `$style.className` 引用，将 CSS Modules 的类名提取并内联。
+
+**Tailwind / UnoCSS：**
+参考 `stack-react.md` 中的 Tailwind 处理策略（class 映射为实际 CSS 值）。
+UnoCSS class 处理方式与 Tailwind 相同。
+
+**全局变量（SCSS variables）：**
+若 `<style>` 中有 `@use '~/styles/variables' as *`，需同时读取对应变量文件。
+
+---
+
+## Nuxt 特有
+
+- **`layouts/`**：类似 Next.js 的 layout，包裹页面的壳（导航、侧边栏）。当 page 依赖某个 layout 时，一并读取
+- **Nuxt auto-imports**：`useRoute()`、`useFetch()` 等不需要显式 import，读取时知道这些是 Nuxt 内置即可，不影响 HTML 生成
+- **`server/` 目录**：API 路由，不是 UI 文件，排除
+- **`composables/`**：状态逻辑，按需读取影响 UI 的部分
+
+---
+
+## 常见 Gotchas
+
+- **`v-if` / `v-show`**：条件渲染分支通常就是不同的 `uiState`，在 HTML 中分别展示
+- **`v-for`**：用 2-3 个典型数据项展示列表状态
+- **`<RouterView>` / `<NuxtPage>`**：在 HTML 中用占位区域替代，标注"子页面区域"
+- **`<Transition>`**：HTML 中只展示静态状态，不还原动画
+- **图片**：`<img :src="...">`、`<NuxtImg>` → `<img>` 占位，设置尺寸
+- **Slot**：`<slot>` 用有代表性的内容填充（参考组件的典型用法）

package/skills/design/sync-design-html/references/stacks.md

@@ -0,0 +1,45 @@
+# 技术栈检测索引
+
+初始化时读取此文件，确定项目技术栈并加载对应的 `stack-*.md`。
+
+---
+
+## 检测规则（按优先级从高到低）
+
+检测到信号后即停止，取优先级最高的匹配。多平台项目（如 SwiftUI iOS+macOS）在单个 stack 文件中处理。
+
+| 优先级 | 技术栈 | 检测信号 | Reference 文件 |
+|--------|--------|---------|----------------|
+| 1 | SwiftUI | 存在 `*.xcodeproj` 或 `Package.swift`，且项目中有 `*View.swift` | `stack-swiftui.md` |
+| 2 | Flutter | 存在 `pubspec.yaml`，且 `lib/` 下有 `*.dart` | （暂无，手动配置） |
+| 3 | Electron | `package.json` 含 `"electron"` 依赖，且存在 main/renderer 目录分离 | `stack-electron.md` |
+| 4 | Next.js | 存在 `next.config.js` 或 `next.config.ts`，或 `package.json` 含 `"next"` | `stack-nextjs.md` |
+| 5 | Nuxt | 存在 `nuxt.config.ts` / `nuxt.config.js`，或 `package.json` 含 `"nuxt"` | `stack-vue.md` |
+| 6 | SvelteKit | 存在 `svelte.config.js`，或 `package.json` 含 `"@sveltejs/kit"` | （暂无，手动配置） |
+| 7 | Vue | `package.json` 含 `"vue"`，且存在 `*.vue` 文件 | `stack-vue.md` |
+| 8 | React | `package.json` 含 `"react"`，且存在 `*.tsx` 或 `*.jsx` 文件 | `stack-react.md` |
+| 9 | Angular | 存在 `angular.json` | （暂无，手动配置） |
+| — | 未知 | 以上均不匹配 | 手动配置 |
+
+---
+
+## "暂无 Reference" 的处理
+
+若检测到的技术栈暂无对应 reference 文件，告知用户：
+
+> "检测到技术栈 `<栈名>`，但暂无对应的自动配置预设。将引导您手动填写 platforms 配置。如您日后希望为此栈添加预设，可创建 `references/stack-<name>.md` 并参照已有文件的格式。"
+
+然后手动引导用户填写：
+- `uiFilePatterns`：询问"您的 UI 组件/视图文件在哪些目录？常用什么文件扩展名？"
+- `designSystemFile`：询问"是否有集中定义颜色、字体等 token 的文件？"
+
+---
+
+## 新增栈的流程
+
+当遇到本索引未覆盖的技术栈时：
+1. 手动完成初始化
+2. 在此索引表中添加一行（优先级参考相近的栈）
+3. 创建 `references/stack-<name>.md`（参照已有格式）
+
+这样下次遇到相同栈时就能自动处理。