@szc-ft/mcp-szcd-client 0.35.0 → 0.38.0

package/standard-skill/shadcn-design-to-code/references/tokens.md

@@ -0,0 +1,534 @@
+# shadcn 设计 Token 提取与落地
+
+> 从 .sketch 节点提取设计 token（颜色/字号/间距/圆角/阴影），落地到 tailwind.config.ts + globals.css
+
+## 核心原则
+
+**3 次出现法则**：
+- 出现 ≥ 3 次的颜色/字号/间距/圆角 → 抽到 `tailwind.config.ts` 主题
+- 出现 1-2 次的 → 用 Tailwind arbitrary value 写 className（`bg-[#f2f8fd]`）
+- 一次性色值（如品牌 logo 特殊色）→ 内联 style 或 CSS variable
+
+**HSL 通道优先**：
+- shadcn CSS variables 用 HSL 不带单位（如 `--primary: 222.2 47.4% 11.2%`）
+- 任意值用 HEX（如 `--primary: #0f172a`）也能工作，但失去 `bg-primary/50` 这种透明度调节
+
+---
+
+## 1. 颜色 token 提取
+
+### 1.1 从 Sketch 提取
+
+每个 `rectangle` / `group` / `text` 节点都有 `style.fills[i].color.hex` 字段。统计所有 hex 出现频次：
+
+```python
+# 伪代码：从 .sketch 解析结果统计
+from collections import Counter
+fills = Counter()
+for node in all_nodes:
+    for fill in node.get('style', {}).get('fills', []):
+        if fill.get('color', {}).get('hex'):
+            fills[fill['color']['hex']] += 1
+
+# 输出 top 20
+for hex, count in fills.most_common(20):
+    print(f"  {hex}: {count}次")
+```
+
+**示例输出**：
+```
+#ffffff: 47次  ← 背景主色
+#0f172a: 32次  ← 文字主色
+#64748b: 28次  ← 文字次色 (text-muted-foreground)
+#f1f5f9: 18次  ← 弱背景 (bg-muted)
+#e2e8f0: 15次  ← 边框 (border)
+#3b82f6: 12次  ← 品牌主色
+#f8fafc: 9次   ← 卡片背景
+```
+
+### 1.2 落地策略
+
+**shadcn 默认色板 vs Sketch 提取色**：
+
+| shadcn 默认 | 默认 HSL | 对应 Sketch | 落地 |
+|---|---|---|---|
+| `--background` | 0 0% 100% | `#ffffff` | 直接用，不改 |
+| `--foreground` | 222.2 47.4% 11.2% | `#0f172a` | 直接用，不改 |
+| `--primary` | 222.2 47.4% 11.2% | `#3b82f6`（品牌蓝） | 改 HSL |
+| `--primary-foreground` | 210 40% 98% | `#ffffff` | 直接用 |
+| `--muted` | 210 40% 96.1% | `#f1f5f9` | 直接用 |
+| `--muted-foreground` | 215.4 16.3% 46.9% | `#64748b` | 直接用 |
+| `--border` | 214.3 31.8% 91.4% | `#e2e8f0` | 直接用 |
+
+**如果 Sketch 颜色和 shadcn 默认色板接近**：直接用，不改（保留生态兼容性）。
+
+**如果 Sketch 用了品牌自定义色**（如 `#3b82f6` 而不是 `#0f172a`）：改 `globals.css` 的 HSL 值。
+
+### 1.3 落地代码
+
+#### 1.3.1 globals.css（CSS variables）
+
+```css
+@layer base {
+  :root {
+    --background: 0 0% 100%;            /* #ffffff */
+    --foreground: 222.2 47.4% 11.2%;   /* #0f172a */
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 47.4% 11.2%;
+    --primary: 217 91% 60%;            /* #3b82f6 → HSL 转换 */
+    --primary-foreground: 0 0% 100%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;            /* #f1f5f9 */
+    --muted-foreground: 215 16% 47%;   /* #64748b */
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214 32% 91%;             /* #e2e8f0 */
+    --input: 214 32% 91%;
+    --ring: 217 91% 60%;               /* 焦点环 = primary */
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222 47% 11%;
+    --foreground: 210 40% 98%;
+    /* ... 暗色版 */
+  }
+}
+```
+
+**HEX → HSL 转换工具**：
+```bash
+# Node.js
+node -e "const c=require('color');console.log(c('#3b82f6').hsl().string())"
+# 输出: hsl(217, 91%, 60%)
+
+# 提取 HSL 通道值（用于 CSS variable）
+node -e "const c=require('color')('#3b82f6');const hsl=c.hsl().object();console.log(`${hsl.h} ${hsl.s.toFixed(1)}% ${hsl.l.toFixed(1)}%`)"
+# 输出: 217 91% 60%
+```
+
+#### 1.3.2 tailwind.config.ts（业务色扩展）
+
+```ts
+import type { Config } from "tailwindcss"
+
+const config: Config = {
+  darkMode: ["class"],
+  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
+  theme: {
+    extend: {
+      colors: {
+        // shadcn HSL 通道（globals.css 改这里会同步生效）
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        // ... 其余 shadcn 默认色
+
+        // 业务扩展色（出现 ≥ 3 次的 token）
+        brand: {
+          50: "#eff6ff",
+          100: "#dbeafe",
+          500: "#3b82f6",  // ← 品牌主色
+          600: "#2563eb",
+          900: "#1e3a8a",
+        },
+        success: "#10b981",
+        warning: "#f59e0b",
+        danger: "#ef4444",
+        // Sketch 中出现 ≥ 3 次的色块
+        segment: {
+          blue: "#f2f8fd",
+          green: "#f5ffed",
+          yellow: "#fffbe6",
+          gray: "#f5f6f7",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+}
+export default config
+```
+
+#### 1.3.3 使用示例
+
+```tsx
+// 用 shadcn 语义色
+<Button className="bg-primary text-primary-foreground">主操作</Button>
+<Badge className="bg-destructive/10 text-destructive">错误</Badge>
+
+// 用业务色
+<div className="bg-brand-500 text-white">品牌主色</div>
+<div className="bg-segment-blue border border-blue-200">蓝色段码块</div>
+<div className="bg-segment-green border border-green-200">绿色段码块</div>
+
+// 用 arbitrary value（一次性色值）
+<div className="bg-[#abcdef]">特殊色</div>
+```
+
+---
+
+## 2. 字号/字重 token 提取
+
+### 2.1 从 Sketch 提取
+
+每个 `text` 节点都有 `text.attributes[0].attributes.{fontSize, fontFamily, color, lineHeight}`。
+
+字重从 `fontFamily` 末尾推断：
+- `PingFangSC-Regular` → 400
+- `PingFangSC-Medium` → 500
+- `PingFangSC-Semibold` → 600
+- `PingFangSC-Bold` → 700
+
+```python
+# 伪代码：统计字号频次
+sizes = Counter()
+for node in text_nodes:
+    for attr in node.get('text', {}).get('attributes', []):
+        size = attr.get('attributes', {}).get('fontSize')
+        if size:
+            sizes[size] += 1
+```
+
+**典型输出**：
+```
+12: 28次  → text-xs (12px)
+14: 47次  → text-sm (14px)
+16: 32次  → text-base (16px)
+18: 15次  → text-lg (18px)
+20: 9次   → text-xl (20px)
+24: 6次   → text-2xl (24px)
+30: 3次   → text-3xl (30px)
+```
+
+### 2.2 落地代码
+
+shadcn 默认 Tailwind 配置已含 text-xs 到 text-9xl。如果 Sketch 用了非标准字号（13px / 15px / 17px），在 `tailwind.config.ts` 扩展：
+
+```ts
+theme: {
+  extend: {
+    fontSize: {
+      // 非标字号
+      '2xs': ['11px', '16px'],
+      '13': ['13px', '20px'],
+      '15': ['15px', '22px'],
+      '17': ['17px', '26px'],
+    },
+  },
+}
+```
+
+**字重对应**：
+
+| Sketch fontFamily | font-weight | Tailwind class |
+|---|---|---|
+| `-Regular` / `-Book` | 400 | `font-normal` |
+| `-Medium` | 500 | `font-medium` |
+| `-Semibold` / `-Demibold` | 600 | `font-semibold` |
+| `-Bold` / `-Heavy` | 700 | `font-bold` |
+
+---
+
+## 3. 间距 token 提取
+
+### 3.1 从 Sketch 提取
+
+```python
+# 伪代码：统计元素 x/y 差值（即间距）
+spacings = Counter()
+for node in all_nodes:
+    for sibling in siblings(node):
+        gap = abs(sibling.x - (node.x + node.width))
+        if 0 < gap < 200:
+            spacings[gap] += 1
+```
+
+**典型输出**（Tailwind 标准 4px 栅格）：
+```
+4: 67次   → p-1, m-1, gap-1
+8: 89次   → p-2, m-2, gap-2 (最常用)
+12: 23次  → p-3, m-3
+16: 54次  → p-4, m-4
+20: 18次  → p-5
+24: 41次  → p-6
+32: 15次  → p-8
+40: 7次   → p-10
+48: 4次   → p-12
+```
+
+### 3.2 落地代码
+
+shadcn 默认 Tailwind 已含 4px 栅格的 spacing。**如果 Sketch 用了 8px 栅格外值**（如 6px / 10px / 14px），扩展：
+
+```ts
+theme: {
+  extend: {
+    spacing: {
+      '1.5': '6px',
+      '2.5': '10px',
+      '3.5': '14px',
+    },
+  },
+}
+```
+
+**容器最大宽度**（常被忽略）：
+
+```ts
+theme: {
+  extend: {
+    maxWidth: {
+      '8xl': '88rem',   // 1408px
+      '9xl': '96rem',   // 1536px
+      'screen-2xl': '1536px',
+    },
+  },
+}
+```
+
+---
+
+## 4. 圆角 token 提取
+
+### 4.1 从 Sketch 提取
+
+`shape.cornerRadius` 字段：
+
+```python
+radii = Counter()
+for node in rect_nodes:
+    r = node.get('shape', {}).get('cornerRadius')
+    if r:
+        radii[r] += 1
+```
+
+**典型输出**：
+```
+0: 89次   → rounded-none
+4: 12次   → rounded-sm
+6: 23次   → rounded-md
+8: 31次   → rounded-lg
+12: 18次  → rounded-xl
+16: 7次   → rounded-2xl
+9999: 4次 → rounded-full
+```
+
+### 4.2 落地代码
+
+shadcn 默认 CSS variable `--radius: 0.5rem`（即 8px）对应 `rounded-lg`。
+
+**修改全局圆角**（一次性影响所有 shadcn 组件）：
+
+```css
+/* globals.css */
+:root {
+  --radius: 0.75rem;  /* 12px → rounded-lg 变 12px */
+}
+```
+
+**单独覆盖某个组件**：
+
+```tsx
+<Button className="rounded-full">完全圆角按钮</Button>
+<Card className="rounded-none">直角卡片</Card>
+<Input className="rounded-md">中等圆角输入框</Input>
+```
+
+---
+
+## 5. 阴影 token 提取
+
+### 5.1 从 Sketch 提取
+
+每个节点的 `style.shadows[]` 数组：
+
+```python
+shadows = Counter()
+for node in all_nodes:
+    for sh in node.get('style', {}).get('shadows', []):
+        key = f"{sh.get('color',{}).get('hex','?')}|{sh.get('offsetX',0)},{sh.get('offsetY',0)},{sh.get('blurRadius',0)}"
+        shadows[key] += 1
+```
+
+**典型输出**：
+```
+#00000010|0,1,2: 18次   → shadow-sm
+#00000014|0,4,6: 9次    → shadow (default)
+#0000001f|0,10,15: 4次  → shadow-md
+#00000026|0,20,25: 2次  → shadow-lg
+```
+
+### 5.2 落地代码
+
+shadcn 默认含 `shadow-sm / shadow / shadow-md / shadow-lg / shadow-xl / shadow-2xl`。
+
+**Sketch 中的非标阴影**（如 `0,0,20 #0079f740` 蓝色光晕）：
+
+```ts
+theme: {
+  extend: {
+    boxShadow: {
+      'glow-blue': '0 0 20px rgba(0, 121, 247, 0.25)',
+      'card-hover': '0 8px 30px rgba(0, 0, 0, 0.12)',
+    },
+  },
+}
+```
+
+```tsx
+<Card className="shadow-glow-blue">发光卡片</Card>
+```
+
+---
+
+## 6. 渐变 token 提取
+
+### 6.1 从 Sketch 提取
+
+`style.fills[0].gradient.stops[]`：
+
+```python
+gradients = Counter()
+for node in all_nodes:
+    fill = node.get('style', {}).get('fills', [{}])[0]
+    grad = fill.get('gradient')
+    if grad:
+        key = '|'.join(f"{s['color']['hex']}@{s.get('position',0):.0%}" for s in grad.get('stops', []))
+        gradients[(grad.get('type'), key)] += 1
+```
+
+**典型输出**：
+```
+('linear', #f3faff@0%|#f8fdff@100%): 5次  → 卡片背景渐变
+('linear', #0ea5e9@0%|#3b82f6@100%): 3次 → 按钮渐变
+```
+
+### 6.2 落地代码
+
+```tsx
+{/* 单次使用：arbitrary value */}
+<div className="bg-gradient-to-b from-[#f3faff] to-[#f8fdff]" />
+
+{/* 多次使用：抽到 config */}
+<button className="bg-gradient-primary text-white" />
+```
+
+```ts
+// tailwind.config.ts
+theme: {
+  extend: {
+    backgroundImage: {
+      'gradient-primary': 'linear-gradient(135deg, #0ea5e9 0%, #3b82f6 100%)',
+      'gradient-card': 'linear-gradient(180deg, #f3faff 0%, #f8fdff 100%)',
+    },
+  },
+}
+```
+
+---
+
+## 7. 落地校验清单（写代码后必跑）
+
+```
+[ ] 所有出现 ≥ 3 次的颜色都在 tailwind.config.ts colors / globals.css --* 中
+[ ] 所有出现 ≥ 3 次的字号用 text-* 语义类（text-xs/sm/base/lg/xl/2xl）映射
+[ ] 所有出现 ≥ 3 次的圆角用 rounded-* 语义类（rounded-sm/md/lg/xl/full）映射
+[ ] 所有出现 ≥ 3 次的间距用 p-* / m-* / gap-* 映射
+[ ] Sketch 特殊字号（如 13px）已在 fontSize 扩展中
+[ ] Sketch 渐变已抽到 backgroundImage 或 CSS variable
+[ ] Sketch 阴影已抽到 boxShadow 扩展
+[ ] 暗色模式 .dark 段已写（如需要）
+```
+
+**反例（违反 = 重做）**：
+- ❌ 出现 8 次的 `#3b82f6` 还是 `bg-[#3b82f6]` 写 className（应抽到 brand.500）
+- ❌ 出现 5 次的 13px 还是 `text-[13px]`（应抽到 fontSize.13）
+- ❌ globals.css 的 `--primary` 还是默认蓝 `#0f172a`，但代码里到处 `bg-blue-500`
+
+---
+
+## 8. 工具函数：自动从 Sketch 提取
+
+把以下 Python 脚本保存到 `scripts/extract-design-tokens.py`：
+
+```python
+#!/usr/bin/env python3
+"""从 sketch-mcp-server 输出的节点 JSON 提取设计 token"""
+import json, sys
+from collections import Counter
+
+def extract_tokens(nodes):
+    colors = Counter()
+    sizes = Counter()
+    radii = Counter()
+    gradients = Counter()
+    
+    for n in nodes:
+        style = n.get('style', {})
+        # 颜色
+        for f in style.get('fills', []):
+            hex = f.get('color', {}).get('hex')
+            if hex:
+                colors[hex] += 1
+            if f.get('gradient'):
+                stops = f['gradient'].get('stops', [])
+                key = '|'.join(f"{s['color']['hex']}@{s.get('position',0):.0%}" for s in stops)
+                gradients[key] += 1
+        # 字号
+        for attr in n.get('text', {}).get('attributes', []):
+            size = attr.get('attributes', {}).get('fontSize')
+            if size:
+                sizes[size] += 1
+        # 圆角
+        r = n.get('shape', {}).get('cornerRadius')
+        if r is not None:
+            radii[r] += 1
+    
+    return {
+        'colors': colors.most_common(20),
+        'sizes': sizes.most_common(10),
+        'radii': radii.most_common(10),
+        'gradients': gradients.most_common(5),
+    }
+
+if __name__ == '__main__':
+    nodes = json.load(sys.stdin)
+    tokens = extract_tokens(nodes)
+    print(json.dumps(tokens, indent=2, ensure_ascii=False))
+```
+
+**用法**：
+```bash
+# 把 getMultipleNodeInfo 的输出保存到 nodes.json
+cat nodes.json | python3 extract-design-tokens.py > tokens.json
+```
+
+输出示例：
+```json
+{
+  "colors": [
+    ["#ffffff", 47],
+    ["#0f172a", 32],
+    ["#3b82f6", 12],
+    ...
+  ],
+  "sizes": [["14", 47], ["16", 32], ...],
+  "radii": [["8", 31], ["6", 23], ...],
+  "gradients": []
+}
+```

package/standard-skill/szcd-upload-zip/SKILL.md

@@ -52,6 +52,50 @@ cat ~/.szcd-mcp-config.json
 - 若 `MCP_API_KEY` 为空字符串，则上传时不带 `X-API-Key` header
 - 若 `MCP_SERVER_URL` 未配置，默认使用 `http://localhost:3456`
 
+### 第 1.5 步：打包目录为 ZIP（跨平台注意事项）
+
+> ⚠️ **关键：不要用 Windows PowerShell 的 `Compress-Archive`。**
+> 它生成的 ZIP 用反斜杠 `\` 作路径分隔符，Linux 服务器 `unzip` 会拒绝解压并报错
+> `appears to use backslashes as path sep`，导致子目录结构丢失。
+> （服务端已增加反斜杠归一化兜底，但仍应优先用正确方式打包，避免依赖兜底。）
+
+按平台选择打包方式（均产出正斜杠路径的标准 ZIP）：
+
+```bash
+# macOS / Linux / Git-Bash / WSL —— 系统 zip
+zip -r my-package.zip my-package/
+
+# 任意平台（含 Windows，只要有 Node）—— 用 tar 产出 zip 不可行，改用下面的 Node 兜底
+```
+
+**Windows 推荐**（按优先级）：
+
+1. **Git Bash / WSL 里的 `zip`**（最简单，路径分隔符正确）：
+   ```bash
+   zip -r my-package.zip my-package/
+   ```
+2. **若只有 PowerShell**，不要用 `Compress-Archive`；改用 Node.js 内置逻辑打包，强制正斜杠：
+   ```bash
+   node -e "
+   const fs=require('fs'),path=require('path'),zlib=require('zlib');
+   const root=process.argv[1], out=process.argv[2];
+   function crc32(b){let t=[];for(let n=0;n<256;n++){let c=n;for(let k=0;k<8;k++)c=c&1?0xEDB88320^(c>>>1):c>>>1;t[n]=c>>>0;}let crc=-1;for(let i=0;i<b.length;i++)crc=(crc>>>8)^t[(crc^b[i])&0xFF];return(crc^-1)>>>0;}
+   let locals=[],centrals=[],off=0;
+   (function walk(dir,pre){for(const e of fs.readdirSync(dir,{withFileTypes:true})){const rel=pre?pre+'/'+e.name:e.name;const abs=path.join(dir,e.name);
+     if(e.isDirectory())walk(abs,rel);else{
+       const data=fs.readFileSync(abs),name=Buffer.from(rel,'utf8'),comp=zlib.deflateRawSync(data),crc=crc32(data);
+       const lh=Buffer.alloc(30);lh.writeUInt32LE(0x04034b50,0);lh.writeUInt16LE(20,4);lh.writeUInt16LE(8,8);lh.writeUInt32LE(crc,14);lh.writeUInt32LE(comp.length,18);lh.writeUInt32LE(data.length,22);lh.writeUInt16LE(name.length,26);
+       locals.push(Buffer.concat([lh,name,comp]));
+       const ch=Buffer.alloc(46);ch.writeUInt32LE(0x02014b50,0);ch.writeUInt16LE(20,4);ch.writeUInt16LE(20,6);ch.writeUInt16LE(8,10);ch.writeUInt32LE(crc,16);ch.writeUInt32LE(comp.length,20);ch.writeUInt32LE(data.length,24);ch.writeUInt16LE(name.length,28);ch.writeUInt32LE(off,42);
+       centrals.push(Buffer.concat([ch,name]));off+=locals[locals.length-1].length;}}})(root,'');
+   const lb=Buffer.concat(locals),cb=Buffer.concat(centrals),eo=Buffer.alloc(22);
+   eo.writeUInt32LE(0x06054b50,0);eo.writeUInt16LE(centrals.length,8);eo.writeUInt16LE(centrals.length,10);eo.writeUInt32LE(cb.length,12);eo.writeUInt32LE(lb.length,16);
+   fs.writeFileSync(out,Buffer.concat([lb,cb,eo]));console.log('zip written:',out);
+   " my-package my-package.zip
+   ```
+
+打包后用 `unzip -l my-package.zip` 检查路径是否为正斜杠（若看到 `\` 则不可上传）。
+
 ### 第 2 步：上传 ZIP 文件
 
 ```bash
@@ -107,6 +151,7 @@ curl -s "$MCP_URL/api/download?path=/scity/zengzhijie/mcp/uploads/my-package/dat
 - 同名 zip 包名会覆盖服务器上已有的目录
 - 解压后文件持久存储，无自动过期
 - 上传路径始终为 `/upload-zip`（不含 `/api/` 前缀）
+- 服务端解压前会把条目名中的反斜杠 `\` 归一化为正斜杠 `/`（兼容 Windows `Compress-Archive` 产物），但应优先按「第 1.5 步」用正确方式打包
 
 ## 完整命令示例（一步完成）