@chuchen3d/wallpaper-plugin-sdk 0.0.0-stage → 1.1.0

package/src/commands/build.js

@@ -0,0 +1,135 @@
+/**
+ * build 命令 — 编译 Vue SFC 并打包为 .yizirwp 文件
+ *
+ * 流程：
+ *   1. 读取并校验 manifest.json
+ *   2. 调用 Vite 编译 SFC → dist/index.js (IIFE bundle)
+ *   3. 重写 manifest.json（entry=index.js, params 转换格式）
+ *   4. 打包 dist/ + manifest.json 为 .yizirwp
+ */
+
+import fs from 'fs'
+import path from 'path'
+import ora from 'ora'
+import { colors, printSeparator } from '../utils/colors.js'
+import { validateManifest } from '../utils/validator.js'
+import { packFromDist } from '../utils/packager.js'
+import { buildPlugin } from '../utils/viteBuilder.js'
+import { convertParamsToAppFormat } from '../utils/paramsConverter.js'
+
+/** 打包为 .yizirwp 文件 */
+export async function cmdBuild(options = {}) {
+  console.log('')
+  console.log(colors.title('📦 打包壁纸插件'))
+  printSeparator()
+
+  const projectDir = process.cwd()
+
+  // 1. 读取 manifest.json
+  const manifestPath = path.join(projectDir, 'manifest.json')
+  if (!fs.existsSync(manifestPath)) {
+    console.log(colors.error('未找到 manifest.json'))
+    console.log('   请在壁纸项目根目录下执行此命令')
+    process.exit(1)
+  }
+
+  let manifest
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf-8')
+    manifest = JSON.parse(content)
+  } catch (err) {
+    console.log(colors.error(`manifest.json 解析失败: ${err.message}`))
+    process.exit(1)
+  }
+
+  // 2. 校验 manifest
+  const validation = validateManifest(manifest, projectDir)
+  if (!validation.valid) {
+    console.log(colors.error('manifest.json 校验失败:'))
+    for (const error of validation.errors) {
+      console.log(`   ❌ ${error}`)
+    }
+    process.exit(1)
+  }
+
+  if (validation.warnings.length > 0) {
+    console.log(colors.warn('manifest.json 校验警告:'))
+    for (const warning of validation.warnings) {
+      console.log(`   ⚠️  ${warning}`)
+    }
+    console.log('')
+  }
+
+  // dry-run 模式只校验不构建
+  if (options.dryRun) {
+    console.log(colors.success('✅ manifest.json 校验通过（dry-run 模式，未生成文件）'))
+    console.log('')
+    console.log('📋 打包信息:')
+    console.log(`   ID: ${manifest.id}`)
+    console.log(`   名称: ${manifest.name}`)
+    console.log(`   版本: ${manifest.version}`)
+    console.log(`   入口: ${manifest.entry}`)
+    console.log(`   文件数: ${manifest.files?.length || 1} + manifest.json`)
+    console.log('')
+    return
+  }
+
+  // 3. Vite 编译 SFC → dist/index.js
+  const buildSpinner = ora('正在编译 Vue SFC (Vite)...').start()
+  let buildResult
+  try {
+    buildResult = await buildPlugin({ projectDir, manifest })
+    buildSpinner.succeed(`编译完成: dist/${buildResult.entryFileName}`)
+  } catch (err) {
+    buildSpinner.fail('编译失败')
+    console.log(colors.error(err.message))
+    if (err.stack) {
+      console.log(colors.warn(err.stack))
+    }
+    process.exit(1)
+  }
+
+  // 4. 重写 manifest：更新 entry 和 params 格式
+  const builtManifest = {
+    ...manifest,
+    entry: 'index.js',
+    files: ['index.js'],
+    params: convertParamsToAppFormat(manifest.params || {}),
+  }
+
+  // 5. 打包
+  const packSpinner = ora('正在打包 .yizirwp...').start()
+  try {
+    const outputName = options.output || `${manifest.id}-${manifest.version}.yizirwp`
+    const result = await packFromDist(projectDir, outputName, builtManifest, { preview: options.preview })
+
+    packSpinner.succeed('打包成功！')
+    console.log('')
+    console.log(colors.success(`已生成: ${colors.file(result.outputPath)}`))
+    console.log('')
+    console.log('📋 打包信息:')
+    console.log(`   ID: ${manifest.id}`)
+    console.log(`   名称: ${manifest.name}`)
+    console.log(`   版本: ${manifest.version}`)
+    console.log(`   原始入口: ${manifest.entry} (Vue SFC)`)
+    console.log(`   编译入口: index.js (IIFE bundle)`)
+    console.log(`   文件大小: ${result.fileSize}`)
+    console.log(`   文件数: ${result.fileCount}`)
+    console.log('')
+    console.log('📂 包含文件:')
+    console.log(`   ✅ manifest.json`)
+    console.log(`   ✅ index.js`)
+    console.log('')
+    console.log('🚀 下一步:')
+    console.log('   在初尘3D壁纸引擎中上传此插件:')
+    console.log(`   1. 打开初尘3D壁纸引擎 → 功能面板 → 开发者中心`)
+    console.log(`   2. 点击「上传插件」`)
+    console.log(`   3. 选择 ${colors.code(result.outputPath)} 文件`)
+    console.log('')
+
+  } catch (err) {
+    packSpinner.fail('打包失败')
+    console.log(colors.error(err.message))
+    process.exit(1)
+  }
+}

package/src/commands/example.js

@@ -0,0 +1,375 @@
+/**
+ * example 命令 — 生成完整示例项目（粒子之舞）
+ */
+
+import fs from 'fs'
+import path from 'path'
+import ora from 'ora'
+import { colors, printSeparator } from '../utils/colors.js'
+import { generateDevProjectFiles } from '../templates/dev-project.js'
+
+/** 生成完整示例项目 */
+export async function cmdExample(projectName) {
+  console.log('')
+  console.log(colors.title('🌰 生成示例项目：粒子之舞'))
+  printSeparator()
+
+  // 检查目录是否已存在
+  const projectDir = path.resolve(process.cwd(), projectName)
+  if (fs.existsSync(projectDir)) {
+    console.log(colors.error(`目录已存在: ${projectName}`))
+    console.log('   请删除或重命名现有目录后重试')
+    process.exit(1)
+  }
+
+  const spinner = ora('正在创建示例项目...').start()
+
+  try {
+    // 1. 创建目录
+    fs.mkdirSync(projectDir, { recursive: true })
+
+    // 2. 示例 manifest.json
+    const manifest = {
+      schemaVersion: '2.0',
+      id: projectName,
+      name: '粒子之舞',
+      version: '1.0.0',
+      author: { name: 'Chuchen Team' },
+      description: '粒子随音乐节奏舞动，鼠标交互产生涟漪效果',
+      tags: ['粒子', '动画', '交互'],
+      category: 'abstract',
+      entry: 'ParticleDance.vue',
+      files: ['ParticleDance.vue'],
+      params: {
+        particleCount: {
+          type: 'number',
+          default: 200,
+          min: 50,
+          max: 500,
+          step: 10,
+          label: '粒子数量',
+        },
+        speed: {
+          type: 'number',
+          default: 1.0,
+          min: 0.2,
+          max: 3.0,
+          step: 0.1,
+          label: '动画速度',
+        },
+        size: {
+          type: 'number',
+          default: 3.0,
+          min: 1.0,
+          max: 8.0,
+          step: 0.5,
+          label: '粒子大小',
+        },
+        colorPreset: {
+          type: 'select',
+          default: 'rainbow',
+          options: [
+            { value: 'rainbow', label: '彩虹' },
+            { value: 'ocean', label: '海洋蓝' },
+            { value: 'sunset', label: '日落橙' },
+            { value: 'neon', label: '霓虹紫' },
+          ],
+          label: '配色方案',
+        },
+        trailLength: {
+          type: 'number',
+          default: 0.85,
+          min: 0,
+          max: 0.98,
+          step: 0.01,
+          label: '拖尾长度',
+        },
+        mouseInteraction: {
+          type: 'toggle',
+          default: true,
+          label: '鼠标交互',
+        },
+      },
+      previewBg: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      emoji: '💃',
+      minAppVersion: '1.0.0',
+    }
+
+    // 3. 写入 manifest.json
+    fs.writeFileSync(
+      path.join(projectDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2)
+    )
+
+    // 4. 写入 ParticleDance.vue
+    const vueContent = generateExampleVueComponent()
+    fs.writeFileSync(
+      path.join(projectDir, 'ParticleDance.vue'),
+      vueContent
+    )
+
+    // 5. 生成开发环境文件
+    const devFiles = generateDevProjectFiles('ParticleDance', manifest)
+    for (const [filename, content] of Object.entries(devFiles)) {
+      fs.writeFileSync(
+        path.join(projectDir, filename),
+        content
+      )
+    }
+
+    spinner.succeed('示例项目创建成功！')
+    console.log('')
+    console.log(colors.success(`项目已创建: ${colors.file(projectName)}/`))
+    console.log('')
+    console.log('📂 项目结构:')
+    console.log(`   ${colors.file('manifest.json')}         — 插件元数据`)
+    console.log(`   ${colors.file('ParticleDance.vue')}     — 粒子之舞组件`)
+    console.log(`   ${colors.file('package.json')}           — 开发依赖`)
+    console.log(`   ${colors.file('vite.config.js')}         — Vite 配置`)
+    console.log(`   ${colors.file('index.html')}             — 预览入口`)
+    console.log(`   ${colors.file('dev-preview.js')}         — Mock props 注入`)
+    console.log('')
+    console.log('🚀 下一步:')
+    console.log(`   1. cd ${colors.code(projectName)}`)
+    console.log(`   2. npm install`)
+    console.log(`   3. npm run dev        # 启动预览服务器`)
+    console.log(`   4. 编辑 ParticleDance.vue 自定义效果`)
+    console.log(`   5. chuchen-plugin build  # 打包为 .yizirwp`)
+    console.log('')
+
+  } catch (err) {
+    spinner.fail('示例项目创建失败')
+    console.log(colors.error(err.message))
+    process.exit(1)
+  }
+}
+
+/** 生成示例 Vue 组件 */
+function generateExampleVueComponent() {
+  return `<template>
+  <canvas ref="canvasRef" class="wallpaper-canvas"></canvas>
+</template>
+
+<script setup>
+/**
+ * ════════════════════════════════════════════════════════════
+ * 💃 粒子之舞 (Particle Dance) — 初尘3D壁纸插件示例
+ * ════════════════════════════════════════════════════════════
+ *
+ * 特性：
+ * - 粒子系统 + 鼠标交互
+ * - 多种配色方案
+ * - 拖尾效果
+ * - 性能模式兼容
+ */
+
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const props = defineProps({
+  containerRef: { type: Object, default: null },
+  paramValues: { type: Object, default: () => ({}) },
+  performancePolicy: { type: Object, default: () => ({}) },
+})
+
+const canvasRef = ref(null)
+
+// ===== 参数读取 =====
+function getParam(key, defaultValue) {
+  return props.paramValues?.[key] !== undefined ? props.paramValues[key] : defaultValue
+}
+
+// ===== 核心变量 =====
+let animationId = null
+let lastFrameTime = 0
+let particles = []
+let mouseX = 0, mouseY = 0
+
+// ===== 颜色预设 =====
+const COLOR_PRESETS = {
+  rainbow: ['#ff6b6b', '#feca57', '#48dbfb', '#ff9ff3', '#54a0ff'],
+  ocean: ['#0077b6', '#00b4d8', '#90e0ef', '#caf0f8', '#48cae4'],
+  sunset: ['#ff7b00', '#ff8800', '#ffa200', '#ffc300', '#ffe600'],
+  neon: ['#9d4edd', '#c77dff', '#e0aaff', '#7b2cbf', '#5a189a'],
+}
+
+// ===== 粒子类 =====
+class Particle {
+  constructor(width, height) {
+    this.x = Math.random() * width
+    this.y = Math.random() * height
+    this.vx = (Math.random() - 0.5) * 2
+    this.vy = (Math.random() - 0.5) * 2
+    this.life = 1.0
+    this.decay = 0.002 + Math.random() * 0.01
+    this.size = 1 + Math.random() * 2
+    this.hue = Math.random() * 360
+  }
+
+  update(speed, width, height, mx, my, interaction) {
+    // 基础运动
+    this.x += this.vx * speed
+    this.y += this.vy * speed
+
+    // 鼠标交互：吸引/排斥
+    if (interaction && mx > 0 && my > 0) {
+      const dx = mx - this.x
+      const dy = my - this.y
+      const dist = Math.sqrt(dx * dx + dy * dy)
+      if (dist < 150) {
+        const force = (150 - dist) / 150
+        this.vx -= (dx / dist) * force * 0.5
+        this.vy -= (dy / dist) * force * 0.5
+      }
+    }
+
+    // 边界处理
+    if (this.x < 0 || this.x > width) this.vx *= -1
+    if (this.y < 0 || this.y > height) this.vy *= -1
+
+    // 生命衰减
+    this.life -= this.decay / speed
+    if (this.life <= 0) {
+      this.reset(width, height)
+    }
+  }
+
+  reset(width, height) {
+    this.x = Math.random() * width
+    this.y = Math.random() * height
+    this.vx = (Math.random() - 0.5) * 2
+    this.vy = (Math.random() - 0.5) * 2
+    this.life = 1.0
+    this.hue = Math.random() * 360
+  }
+}
+
+// ===== 初始化 =====
+function init() {
+  const canvas = canvasRef.value
+  const container = props.containerRef || canvas.parentElement
+
+  if (!canvas || !container) return
+
+  const ctx = canvas.getContext('2d')
+
+  function resize() {
+    const w = container.clientWidth || window.innerWidth
+    const h = container.clientHeight || window.innerHeight
+    canvas.width = w
+    canvas.height = h
+  }
+  resize()
+
+  // 初始化粒子
+  initParticles()
+
+  // 事件绑定
+  if (container) {
+    container.addEventListener('mousemove', onMouseMove)
+  }
+  window.addEventListener('resize', resize)
+
+  animate()
+}
+
+function initParticles() {
+  const count = getParam('particleCount', 200)
+  const canvas = canvasRef.value
+  particles = []
+  for (let i = 0; i < count; i++) {
+    particles.push(new Particle(canvas.width, canvas.height))
+  }
+}
+
+// ===== 动画循环 =====
+function animate(timestamp) {
+  animationId = requestAnimationFrame(animate)
+
+  const fpsLimit = props.performancePolicy?.fpsLimit || 60
+  if (fpsLimit > 0 && fpsLimit < 60) {
+    if (!lastFrameTime) lastFrameTime = timestamp
+    if (timestamp - lastFrameTime < 1000 / fpsLimit) return
+    lastFrameTime = timestamp
+  } else if (fpsLimit === 0) {
+    return
+  }
+
+  const canvas = canvasRef.value
+  if (!canvas) return
+  const ctx = canvas.getContext('2d')
+  const width = canvas.width
+  const height = canvas.height
+
+  // 读取参数
+  const speed = getParam('speed', 1.0)
+  const size = getParam('size', 3.0)
+  const colorPreset = getParam('colorPreset', 'rainbow')
+  const trailLength = getParam('trailLength', 0.85)
+  const interaction = getParam('mouseInteraction', true)
+
+  // 拖尾效果
+  ctx.fillStyle = \`rgba(10, 10, 20, \${1 - trailLength})\`
+  ctx.fillRect(0, 0, width, height)
+
+  // 获取颜色数组
+  const colors = COLOR_PRESETS[colorPreset] || COLOR_PRESETS.rainbow
+
+  // 更新和绘制粒子
+  for (const p of particles) {
+    p.update(speed, width, height, mouseX, mouseY, interaction)
+
+    const alpha = p.life
+    const colorIndex = Math.floor(p.hue / 72) % colors.length
+    const color = colors[colorIndex]
+
+    ctx.beginPath()
+    ctx.arc(p.x, p.y, p.size * size * alpha, 0, Math.PI * 2)
+    ctx.fillStyle = hexToRgba(color, alpha * 0.8)
+    ctx.fill()
+
+    // 发光效果
+    ctx.shadowBlur = size * 2
+    ctx.shadowColor = color
+  }
+
+  ctx.shadowBlur = 0
+}
+
+// ===== 工具函数 =====
+function hexToRgba(hex, alpha) {
+  const r = parseInt(hex.slice(1, 3), 16)
+  const g = parseInt(hex.slice(3, 5), 16)
+  const b = parseInt(hex.slice(5, 7), 16)
+  return \`rgba(\${r},\${g},\${b},\${alpha})\`
+}
+
+// ===== 事件处理 =====
+function onMouseMove(event) {
+  const rect = event.currentTarget.getBoundingClientRect()
+  mouseX = ((event.clientX - rect.left) / rect.width) * canvasRef.value.width
+  mouseY = ((event.clientY - rect.top) / rect.height) * canvasRef.value.height
+}
+
+// ===== 生命周期 =====
+onMounted(() => {
+  init()
+})
+
+onUnmounted(() => {
+  if (animationId) cancelAnimationFrame(animationId)
+  if (props.containerRef) {
+    props.containerRef.removeEventListener('mousemove', onMouseMove)
+  }
+  window.removeEventListener('resize', () => {})
+})
+</script>
+
+<style scoped>
+.wallpaper-canvas {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+</style>
+`
+}

package/src/commands/init.js

@@ -0,0 +1,200 @@
+/**
+ * init 命令 — 初始化壁纸插件项目
+ */
+
+import fs from 'fs'
+import path from 'path'
+import ora from 'ora'
+import { colors, printSeparator } from '../utils/colors.js'
+import { generateManifest } from '../templates/manifest.js'
+import { generateVueComponentTemplate } from '../templates/vue-component.js'
+import { generateDevProjectFiles } from '../templates/dev-project.js'
+
+/** 初始化壁纸插件项目 */
+export async function cmdInit(projectName, options = {}) {
+  console.log('')
+  console.log(colors.title('📁 初始化壁纸插件项目'))
+  printSeparator()
+
+  // 校验项目名称
+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(projectName)) {
+    console.log(colors.error('项目名称格式错误'))
+    console.log('   仅允许小写字母、数字、连字符（如: my-wallpaper）')
+    process.exit(1)
+  }
+
+  // 检查目录是否已存在
+  const projectDir = path.resolve(process.cwd(), projectName)
+  if (fs.existsSync(projectDir)) {
+    console.log(colors.error(`目录已存在: ${projectName}`))
+    console.log('   请删除或重命名现有目录后重试')
+    process.exit(1)
+  }
+
+  const spinner = ora('正在创建项目...').start()
+
+  try {
+    // 1. 生成 manifest.json
+    const manifest = generateManifest(projectName, options)
+
+    // 2. 创建目录
+    fs.mkdirSync(projectDir, { recursive: true })
+
+    // 3. 写入 manifest.json
+    fs.writeFileSync(
+      path.join(projectDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2)
+    )
+
+    // 4. 生成 Vue 组件
+    const componentName = toPascalCase(projectName)
+    const vueTemplate = generateVueComponentTemplate(componentName, manifest)
+    fs.writeFileSync(
+      path.join(projectDir, manifest.entry),
+      vueTemplate
+    )
+
+    // 5. 生成开发环境文件
+    const devFiles = generateDevProjectFiles(componentName, manifest)
+    for (const [filename, content] of Object.entries(devFiles)) {
+      fs.writeFileSync(
+        path.join(projectDir, filename),
+        content
+      )
+    }
+
+    // 6. 生成 README.md
+    const readme = generateReadme(manifest, componentName)
+    fs.writeFileSync(
+      path.join(projectDir, 'README.md'),
+      readme
+    )
+
+    // 7. 生成 ICON_GUIDE.md
+    const iconGuide = generateIconGuide()
+    fs.writeFileSync(
+      path.join(projectDir, 'ICON_GUIDE.md'),
+      iconGuide
+    )
+
+    spinner.succeed('项目创建成功！')
+    console.log('')
+    console.log(colors.success(`项目已创建: ${colors.file(projectName)}/`))
+    console.log('')
+    console.log('📂 项目结构:')
+    console.log(`   ${colors.file('manifest.json')}        — 插件元数据`)
+    console.log(`   ${colors.file(manifest.entry)}  — 壁纸组件（主要编辑文件）`)
+    console.log(`   ${colors.file('package.json')}         — 开发依赖`)
+    console.log(`   ${colors.file('vite.config.js')}       — Vite 配置`)
+    console.log(`   ${colors.file('index.html')}           — 预览入口`)
+    console.log(`   ${colors.file('dev-preview.js')}       — Mock props 注入`)
+    console.log(`   ${colors.file('README.md')}            — 开发说明`)
+    console.log(`   ${colors.file('ICON_GUIDE.md')}        — 图标制作指南`)
+    console.log('')
+    console.log('🚀 下一步:')
+    console.log(`   1. cd ${colors.code(projectName)}`)
+    console.log(`   2. npm install`)
+    console.log(`   3. npm run dev        # 启动预览服务器`)
+    console.log(`   4. 编辑 ${colors.code(manifest.entry)} 实现你的壁纸`)
+    console.log(`   5. chuchen-plugin build  # 打包为 .yizirwp`)
+    console.log('')
+
+  } catch (err) {
+    spinner.fail('项目创建失败')
+    console.log(colors.error(err.message))
+    process.exit(1)
+  }
+}
+
+/** 生成 README.md */
+function generateReadme(manifest, componentName) {
+  return `# ${manifest.name}
+
+一款精美的初尘3D壁纸插件
+
+**作者**: ${manifest.author?.name || '开发者'}
+**版本**: ${manifest.version}
+**分类**: ${manifest.category}
+
+## 开发指南
+
+### 1. 安装依赖
+
+\`\`\`bash
+npm install
+\`\`\`
+
+### 2. 启动预览
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+浏览器将自动打开预览页面，右侧有参数调节面板。
+
+### 3. 编辑壁纸
+
+打开 \`${manifest.entry}\`，在 \`init()\` 和 \`animate()\` 中实现你的动画逻辑。
+
+### 4. 调整参数
+
+在 \`manifest.json\` 的 \`params\` 字段中定义可调参数，预览页面的参数面板会自动更新。
+
+### 5. 打包发布
+
+\`\`\`bash
+chuchen-plugin build
+\`\`\`
+
+生成 \`${manifest.id}-${manifest.version}.yizirwp\` 文件，可在初尘3D壁纸中安装。
+
+## 参数说明
+
+${Object.entries(manifest.params || {}).map(([key, def]) => {
+  return `- **${def.label || key}** (\`${key}\`): ${def.type} 类型，默认值 \`${def.default}\`${def.min !== undefined ? `，范围 ${def.min}~${def.max}` : ''}`
+}).join('\n')}
+`
+}
+
+/** 生成 ICON_GUIDE.md */
+function generateIconGuide() {
+  return `# 缩略图制作指南
+
+为壁纸插件添加缩略图，让用户在商店中快速预览效果。
+
+## 要求
+
+- **格式**: PNG / JPG / SVG
+- **尺寸**: 256×256 像素（推荐）
+- **文件名**: \`thumbnail.png\`
+- **位置**: 项目根目录
+
+## 制作步骤
+
+### 方法 1: 从预览截图
+
+1. 运行 \`npm run dev\` 启动预览
+2. 调整参数到最佳效果
+3. 截图并裁剪为 256×256
+4. 保存为 \`thumbnail.png\`
+
+### 方法 2: 使用设计工具
+
+1. 打开 Figma / Photoshop / Sketch
+2. 创建 256×256 画布
+3. 设计缩略图（建议包含壁纸核心元素）
+4. 导出为 PNG
+
+## 注意事项
+
+- 避免文字过多（小尺寸下看不清）
+- 使用高对比度颜色
+- 突出壁纸的核心视觉效果
+- 文件大小建议 < 50KB
+`
+}
+
+/** 工具函数：kebab-case → PascalCase */
+function toPascalCase(str) {
+  return str.replace(/(?:^|-)(\w)/g, (_, c) => c.toUpperCase())
+}