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

package/src/commands/validate.js

@@ -0,0 +1,76 @@
+/**
+ * validate 命令 — 校验 manifest.json 格式
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { colors, printSeparator } from '../utils/colors.js'
+import { validateManifest } from '../utils/validator.js'
+
+/** 校验 manifest.json 格式 */
+export async function cmdValidate() {
+  console.log('')
+  console.log(colors.title('✅ 校验 manifest.json'))
+  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. 校验
+  const validation = validateManifest(manifest, projectDir)
+
+  // 3. 输出结果
+  console.log('')
+  console.log('📋 基本信息:')
+  console.log(`   ID: ${manifest.id || '(未设置)'}`)
+  console.log(`   名称: ${manifest.name || '(未设置)'}`)
+  console.log(`   版本: ${manifest.version || '(未设置)'}`)
+  console.log(`   作者: ${manifest.author?.name || '(未设置)'}`)
+  console.log(`   入口: ${manifest.entry || '(未设置)'}`)
+  console.log('')
+
+  if (validation.valid) {
+    console.log(colors.success('✅ manifest.json 校验通过'))
+  } else {
+    console.log(colors.error('❌ manifest.json 校验失败'))
+  }
+
+  if (validation.errors.length > 0) {
+    console.log('')
+    console.log('❌ 错误:')
+    for (const error of validation.errors) {
+      console.log(`   ${error}`)
+    }
+  }
+
+  if (validation.warnings.length > 0) {
+    console.log('')
+    console.log('⚠️  建议:')
+    for (const warning of validation.warnings) {
+      console.log(`   ${warning}`)
+    }
+  }
+
+  console.log('')
+
+  // 4. 退出码
+  if (!validation.valid) {
+    process.exit(1)
+  }
+}

package/src/index.js

@@ -0,0 +1,40 @@
+/**
+ * ════════════════════════════════════════════════════════════
+ * 🧩 初尘3D壁纸 — 插件 SDK 主入口
+ * ════════════════════════════════════════════════════════════
+ *
+ * 支持两种使用方式：
+ *   1. CLI 命令行：chuchen-plugin init/build/validate/example
+ *   2. 程序化调用：import { ... } from '@chuchen3d/wallpaper-plugin-sdk'
+ *
+ * @author Chuchen Team
+ * @version 1.0.0
+ */
+
+import { createRequire } from 'module'
+
+// ===== 命令函数（供程序化调用）=====
+export { cmdInit } from './commands/init.js'
+export { cmdBuild } from './commands/build.js'
+export { cmdValidate } from './commands/validate.js'
+export { cmdExample } from './commands/example.js'
+
+// ===== 模板生成器 =====
+export { generateManifest } from './templates/manifest.js'
+export { generateVueComponentTemplate } from './templates/vue-component.js'
+export { generateDevProjectFiles } from './templates/dev-project.js'
+
+// ===== 工具函数 =====
+export { validateManifest } from './utils/validator.js'
+export { packProject, packFromDist } from './utils/packager.js'
+export { convertParamsToAppFormat } from './utils/paramsConverter.js'
+export { buildPlugin } from './utils/viteBuilder.js'
+
+// ===== 构建模板 =====
+export { generatePluginEntry } from './templates/plugin-entry.js'
+
+// ===== 版本信息 =====
+const require = createRequire(import.meta.url)
+const pkg = require('../../package.json')
+export const VERSION = pkg.version
+export const PACKAGE_NAME = pkg.name

package/src/templates/dev-project.js

@@ -0,0 +1,357 @@
+/**
+ * 开发环境项目模板生成器
+ *
+ * 生成以下文件：
+ * - package.json（vite + vue + three 依赖）
+ * - vite.config.js（Vue 插件配置）
+ * - index.html（开发预览入口）
+ * - dev-preview.js（Mock props 注入脚本）
+ */
+
+/** 生成开发环境文件集合 */
+export function generateDevProjectFiles(componentName, manifest) {
+  const entry = manifest.entry || `${componentName}.vue`;
+  const params = manifest.params || {};
+  const hasThree =
+    manifest.category === "tech" ||
+    Object.keys(params).some((k) =>
+      ["particleCount", "rotationSpeed"].includes(k),
+    );
+
+  return {
+    "package.json": generatePackageJson(componentName, hasThree),
+    "vite.config.js": generateViteConfig(),
+    "index.html": generateIndexHtml(componentName, manifest),
+    "dev-preview.js": generateDevPreviewJs(componentName, manifest),
+  };
+}
+
+/** 生成 package.json */
+function generatePackageJson(projectName, hasThree) {
+  const deps = {
+    vue: "^3.4.0",
+    vite: "^5.2.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+  };
+
+  if (hasThree) {
+    deps.three = "^0.162.0";
+  }
+
+  return JSON.stringify(
+    {
+      name: projectName,
+      version: "1.0.0",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "vite",
+        build: "vite build",
+        preview: "vite preview",
+      },
+      dependencies: deps,
+    },
+    null,
+    2,
+  );
+}
+
+/** 生成 vite.config.js */
+function generateViteConfig() {
+  return `import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { fileURLToPath, URL } from 'node:url'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      // ★ 必须指向含运行时编译器的完整构建
+      // 因为 dev-preview.js 使用了 createApp({ template: ... }) 运行时模板，
+      // 默认的 vue.runtime-esm-bundler 不包含模板编译器，会报错：
+      // "Component provided template option but runtime compilation is not supported"
+      'vue': 'vue/dist/vue.esm-bundler.js',
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  server: {
+    port: 3000,
+    open: true,
+  },
+})
+`;
+}
+
+/** 生成 index.html */
+function generateIndexHtml(componentName, manifest) {
+  const entry = manifest.entry || `${componentName}.vue`;
+  const name = manifest.name || componentName;
+  const params = manifest.params || {};
+
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>🎨 ${name} — 初尘3D壁纸插件预览</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #0a0a0a;
+      color: #fff;
+      overflow: hidden;
+    }
+    #preview-container {
+      width: 100vw;
+      height: 100vh;
+      position: relative;
+    }
+    #param-panel {
+      position: fixed;
+      top: 16px;
+      right: 16px;
+      background: rgba(0, 0, 0, 0.75);
+      backdrop-filter: blur(12px);
+      border: 1px solid rgba(255, 255, 255, 0.15);
+      border-radius: 12px;
+      padding: 16px;
+      min-width: 220px;
+      z-index: 100;
+      font-size: 13px;
+    }
+    #param-panel h3 {
+      margin-bottom: 12px;
+      font-size: 14px;
+      color: #a78bfa;
+    }
+    #param-panel label {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 8px;
+      gap: 8px;
+    }
+    #param-panel input[type="range"] {
+      width: 100px;
+    }
+    #param-panel input[type="color"] {
+      width: 40px;
+      height: 24px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+    }
+    #param-panel input[type="checkbox"] {
+      width: 18px;
+      height: 18px;
+      cursor: pointer;
+    }
+    #param-panel select {
+      background: #1a1a2e;
+      color: #fff;
+      border: 1px solid #333;
+      border-radius: 4px;
+      padding: 4px 8px;
+      font-size: 12px;
+    }
+    #param-panel span {
+      min-width: 36px;
+      text-align: right;
+      color: #888;
+      font-family: monospace;
+    }
+    #toggle-btn {
+      position: fixed;
+      top: 16px;
+      right: 16px;
+      z-index: 101;
+      background: rgba(0, 0, 0, 0.6);
+      border: 1px solid rgba(255, 255, 255, 0.2);
+      color: #fff;
+      width: 32px;
+      height: 32px;
+      border-radius: 8px;
+      cursor: pointer;
+      font-size: 16px;
+      display: none;
+    }
+    #info-bar {
+      position: fixed;
+      bottom: 16px;
+      left: 50%;
+      transform: translateX(-50%);
+      background: rgba(0, 0, 0, 0.6);
+      backdrop-filter: blur(8px);
+      border: 1px solid rgba(255, 255, 255, 0.1);
+      border-radius: 8px;
+      padding: 8px 16px;
+      font-size: 12px;
+      color: #888;
+      z-index: 50;
+    }
+  </style>
+</head>
+<body>
+  <div id="preview-container">
+    <!-- 壁纸组件将挂载到这里 -->
+  </div>
+
+  <!-- 参数面板 -->
+  <div id="param-panel">
+    <h3>🎛️ 参数调节</h3>
+    ${generateParamPanelHTML(params)}
+  </div>
+
+  <!-- 底部信息栏 -->
+  <div id="info-bar">
+    🎨 ${name} v${manifest.version || "1.0.0"} — 初尘3D壁纸插件预览模式
+  </div>
+
+  <script type="module" src="/dev-preview.js"></script>
+</body>
+</html>
+`;
+}
+
+/** 生成参数面板 HTML */
+function generateParamPanelHTML(params) {
+  return Object.entries(params)
+    .map(([key, def]) => {
+      const label = def.label || key;
+      if (def.type === "number") {
+        return `<label>${label}: <input type="range" id="param-${key}" min="${def.min ?? 0}" max="${def.max ?? 100}" step="${def.step ?? 1}" value="${def.default}"> <span id="val-${key}">${def.default}</span></label>`;
+      }
+      if (def.type === "toggle") {
+        return `<label>${label}: <input type="checkbox" id="param-${key}" ${def.default ? "checked" : ""}></label>`;
+      }
+      if (def.type === "color") {
+        return `<label>${label}: <input type="color" id="param-${key}" value="${def.default}"></label>`;
+      }
+      if (def.type === "select") {
+        const options = (def.options || [])
+          .map((opt) => `<option value="${opt.value}">${opt.label}</option>`)
+          .join("");
+        return `<label>${label}: <select id="param-${key}">${options}</select></label>`;
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n    ");
+}
+
+/** 生成 dev-preview.js（Mock props 注入脚本） */
+function generateDevPreviewJs(componentName, manifest) {
+  const entry = manifest.entry || `${componentName}.vue`;
+  const params = manifest.params || {};
+
+  return `/**
+ * dev-preview.js — Mock props 注入脚本
+ *
+ * 模拟初尘3D壁纸的 props 注入，让开发者可以独立预览和调试壁纸组件。
+ * 打包时会自动排除此文件。
+ */
+
+import { createApp, ref, onMounted, onUnmounted, watch } from 'vue'
+import WallpaperComponent from './${entry}'
+
+// ===== 创建 Vue 应用 =====
+const app = createApp({
+  setup() {
+    // ★ 所有在模板中使用的 ref 必须在 setup() 中定义并通过 return 暴露
+    const containerRef = ref(null)
+
+    // Mock 参数值
+    const paramValues = ref({})
+    // 初始化参数默认值
+    ${Object.entries(params)
+      .map(([key, def]) => {
+        return `paramValues.value['${key}'] = ${JSON.stringify(def.default)}`;
+      })
+      .join("\n    ")}
+
+    // Mock 性能策略
+    const performancePolicy = ref({
+      fpsLimit: 60,
+      pixelRatioCap: 2.0,
+      mouseInteraction: true,
+    })
+
+    onMounted(() => {
+      containerRef.value = document.getElementById('preview-container')
+    })
+
+    // ★ 必须返回所有模板中使用的响应式变量
+    return { containerRef, paramValues, performancePolicy }
+  },
+  template: \`
+    <div id="preview-container" ref="containerRef">
+      <WallpaperComponent
+        :containerRef="containerRef"
+        :paramValues="paramValues"
+        :performancePolicy="performancePolicy"
+      />
+    </div>
+  \`,
+  components: { WallpaperComponent },
+})
+
+app.mount('#preview-container')
+
+// ===== 参数面板事件绑定 =====
+${Object.entries(params)
+  .map(([key, def]) => {
+    if (def.type === "number") {
+      return `
+// ${def.label || key} 滑块
+const ${key}Slider = document.getElementById('param-${key}')
+const ${key}Val = document.getElementById('val-${key}')
+if (${key}Slider) {
+  ${key}Slider.addEventListener('input', (e) => {
+    const val = parseFloat(e.target.value)
+    // ★ 通过 app._instance.setupState 访问 setup 中的 ref
+    app._instance.setupState.paramValues['${key}'] = val
+    if (${key}Val) ${key}Val.textContent = val.toFixed(2)
+  })
+}`;
+    }
+    if (def.type === "toggle") {
+      return `
+// ${def.label || key} 开关
+const ${key}Checkbox = document.getElementById('param-${key}')
+if (${key}Checkbox) {
+  ${key}Checkbox.addEventListener('change', (e) => {
+    app._instance.setupState.paramValues['${key}'] = e.target.checked
+  })
+}`;
+    }
+    if (def.type === "color") {
+      return `
+// ${def.label || key} 颜色选择器
+const ${key}Color = document.getElementById('param-${key}')
+if (${key}Color) {
+  ${key}Color.addEventListener('input', (e) => {
+    app._instance.setupState.paramValues['${key}'] = e.target.value
+  })
+}`;
+    }
+    if (def.type === "select") {
+      return `
+// ${def.label || key} 下拉选择
+const ${key}Select = document.getElementById('param-${key}')
+if (${key}Select) {
+  ${key}Select.addEventListener('change', (e) => {
+    app._instance.setupState.paramValues['${key}'] = e.target.value
+  })
+}`;
+    }
+    return "";
+  })
+  .filter(Boolean)
+  .join("\n")}
+
+console.log('🎨 初尘3D壁纸插件预览模式已启动')
+console.log('📦 组件:', '${entry}')
+console.log('🎛️ 参数:', Object.keys(app._instance.setupState.paramValues).length, '个')
+`;
+}

package/src/templates/manifest.js

@@ -0,0 +1,143 @@
+/**
+ * manifest.json 模板生成器
+ */
+
+/** 生成 manifest.json 对象 */
+export function generateManifest(projectName, options = {}) {
+  const id = projectName || 'my-wallpaper'
+  const name = options.name || toTitleCase(id)
+  const description = options.description || '一款精美的初尘3D壁纸插件'
+  const author = options.author || '开发者'
+  const category = options.category || 'abstract'
+  const three = options.three || false
+
+  return {
+    schemaVersion: '2.0',
+    id: id,
+    name: name,
+    version: '1.0.0',
+    author: {
+      name: author,
+    },
+    description: description,
+    tags: [category],
+    category: category,
+    entry: `${toPascalCase(id)}.vue`,
+    files: [`${toPascalCase(id)}.vue`],
+    params: generateDefaultParams(category, three),
+    previewBg: getDefaultPreviewBg(category),
+    emoji: getDefaultEmoji(category),
+    minAppVersion: '1.0.0',
+
+    // ★ 真隔离重构（2026-10-08）：沙箱运行时字段。
+    // network.domains 是沙箱 CSP connect-src/img-src 的唯一放行依据（默认全禁网），
+    // 上架审核时对审核员可见；访问未声明域名会被浏览器层拦截。
+    // 示例：network: { domains: ['https://devapi.qweather.com'] },
+    apiVersion: 1,
+    network: { domains: [] },
+
+    // ★ 预览视频/GIF（可选）。支持 mp4 / webm / mov / gif，video ≤10MB，gif ≤5MB。
+    // 路径相对于项目根；构建时由 SDK 打入 .yizirwp 的 preview/ 子目录。
+    // 服务端首次上传会自动抽取到独立存储；后续可由 admin 或 dev 通过预览管理 UI 替换。
+    // 示例：preview: 'preview/preview.mp4',
+
+    // 商业字段（默认免费，开发者可覆盖）
+    isPremium: false,
+    price: 0,
+    tier: 'free',
+  }
+}
+
+/** 生成默认参数 */
+function generateDefaultParams(category, three) {
+  const base = {
+    opacity: {
+      type: 'number',
+      default: 1.0,
+      min: 0,
+      max: 1,
+      step: 0.05,
+      label: '透明度',
+    },
+    speed: {
+      type: 'number',
+      default: 1.0,
+      min: 0.1,
+      max: 3,
+      step: 0.1,
+      label: '动画速度',
+    },
+  }
+
+  if (category === 'natural') {
+    return {
+      ...base,
+      intensity: {
+        type: 'number',
+        default: 0.5,
+        min: 0,
+        max: 1,
+        step: 0.05,
+        label: '效果强度',
+      },
+    }
+  }
+
+  if (category === 'tech' || three) {
+    return {
+      ...base,
+      particleCount: {
+        type: 'number',
+        default: 1000,
+        min: 100,
+        max: 10000,
+        step: 100,
+        label: '粒子数量',
+      },
+      rotationSpeed: {
+        type: 'number',
+        default: 0.5,
+        min: 0,
+        max: 2,
+        step: 0.1,
+        label: '旋转速度',
+      },
+    }
+  }
+
+  return base
+}
+
+/** 获取默认预览背景 */
+function getDefaultPreviewBg(category) {
+  const presets = {
+    natural: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+    tech: 'linear-gradient(135deg, #0f0c29 0%, #302b63 50%, #24243e 100%)',
+    abstract: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
+    festival: 'linear-gradient(135deg, #ffecd2 0%, #fcb69f 100%)',
+    utility: 'linear-gradient(135deg, #a1c4fd 0%, #c2e9fb 100%)',
+  }
+  return presets[category] || presets.abstract
+}
+
+/** 获取默认 Emoji */
+function getDefaultEmoji(category) {
+  const presets = {
+    natural: '🌿',
+    tech: '⚡',
+    abstract: '🎨',
+    festival: '🎉',
+    utility: '📊',
+  }
+  return presets[category] || presets.abstract
+}
+
+/** 工具函数：kebab-case → Title Case */
+function toTitleCase(str) {
+  return str.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+}
+
+/** 工具函数：kebab-case → PascalCase */
+function toPascalCase(str) {
+  return str.replace(/(?:^|-)(\w)/g, (_, c) => c.toUpperCase())
+}

package/src/templates/plugin-entry.js

@@ -0,0 +1,82 @@
+/**
+ * 插件入口模板（生成器）
+ *
+ * ★ 真隔离重构（2026-10-08）：适配沙箱运行时（opaque origin iframe）。
+ *   设计文档：docs/superpowers/specs/2026-10-08-plugin-sandbox-isolation-design.md
+ *
+ * 此模板在 build 阶段生成一个临时入口 .js 文件，作为 Vite 的 build.lib.entry。
+ * 它负责：
+ *   1. 导入开发者编写的 Vue SFC 组件（连同 Vue/Three 依赖全部打进自包含 IIFE）
+ *   2. 从沙箱 Shim（window.__YIZIRAN_PLUGIN_API__，srcdoc 内联）获取宿主 API
+ *   3. 创建 Vue 应用，传入 containerRef/paramValues/performancePolicy props
+ *      （★ 组件 props 契约与旧版完全一致 —— 包作者组件代码零改动）
+ *   4. 监听参数和性能策略变化，响应式更新组件
+ *   5. 通知宿主插件已就绪
+ *
+ * 与旧版（宿主注入时代）的差异：
+ *   - Vue 由包自带（不再 window.__YIZIRAN_VUE__）
+ *   - 挂载点是沙箱 iframe 自身的 document.body（iframe 即受约束的渲染根）
+ *   - 无 api._bindApp（宿主不捕获 app；iframe 移除即整体销毁）
+ *   - beforeunload 时 app.unmount() 触发包组件的 onUnmounted 清理（软清理兜底）
+ */
+
+/**
+ * 生成插件入口代码
+ *
+ * @param {string} componentImportPath — Vue SFC 组件的相对路径（如 './CodePlanet.vue'）
+ * @returns {string} 入口文件源码字符串
+ */
+export function generatePluginEntry(componentImportPath) {
+  return `// ⚠️ 此文件由 chuchen-plugin build 自动生成，请勿手动编辑
+import PluginComponent from '${componentImportPath}'
+import { createApp, reactive } from 'vue'
+
+const api = window.__YIZIRAN_PLUGIN_API__
+
+if (!api) {
+  console.error('[Chuchen Plugin] __YIZIRAN_PLUGIN_API__ 不可用：请在初尘3D壁纸（真隔离沙箱运行时）或 chuchen-plugin 环境中运行')
+  throw new Error('Sandbox Plugin API not available')
+}
+
+// 创建响应式参数和性能策略对象
+// ★ 初值已由宿主烘焙进沙箱（__YIZIRAN_INIT__），此处同步读取，无竞态
+const paramValues = reactive(api.getAllParams())
+const performancePolicy = reactive(api.getPerformancePolicy())
+
+// 挂载容器：沙箱 iframe 自身的 document.body 就是受约束的渲染根
+// （iframe 即"铺满即壁纸"，不存在旧版越界挂到宿主 body 的问题）
+const appRoot = document.createElement('div')
+appRoot.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;'
+document.body.appendChild(appRoot)
+
+// 创建并挂载 Vue 应用
+const app = createApp(PluginComponent, {
+  containerRef: appRoot,
+  paramValues: paramValues,
+  performancePolicy: performancePolicy,
+})
+
+app.mount(appRoot)
+
+// 沙箱销毁（宿主移除 iframe）前触发组件 onUnmounted 清理
+// （cancelAnimationFrame / renderer.dispose 等；上下文销毁本身已是兜底）
+window.addEventListener('beforeunload', function () {
+  try { app.unmount() } catch (_) {}
+})
+
+// 监听宿主参数变化，同步到响应式对象
+api.onParamChange(function (key, value) {
+  paramValues[key] = value
+})
+
+// 监听宿主性能策略变化
+api.onPolicyChange(function (newPolicy) {
+  Object.assign(performancePolicy, newPolicy)
+})
+
+// 通知宿主插件已就绪
+api._notifyReady()
+
+console.log('[Chuchen Plugin] 插件已就绪（沙箱运行时）')
+`
+}