@unmagic/vms 0.0.1 → 0.0.3-beta.0

package/README.md

@@ -1,152 +1,255 @@
-# Vue Mini SFC
+# VMS (Vue Mini SFC)
 
-基于 @vue-mini/core 的 Vue3 单文件组件构建工具，用于将 Vue SFC 编译为微信小程序代码。
+<p align="center">基于 Vue 3 的微信小程序单文件组件编译器，让你用 <code>&lt;script setup lang="ts"&gt;</code> 开发小程序。</p>
 
-## 📚 文档组织结构
+## 简介
 
-项目文档已按功能划分整理到 `docs/` 文件夹下：
+**VMS** (Vue Mini SFC) 是一个构建工具，允许你使用 Vue 3 单文件组件（SFC）语法开发微信小程序。它将 `.vue` 文件编译为微信小程序原生代码（WXML + JS + WXSS + JSON），在保持 Vue 开发体验的同时，输出高性能的小程序代码。
 
-### 📁 docs/implemented - 已实现的功能
+运行时依赖 [`@unmagic/vue-mini`](https://github.com/unmagic/vms-vue-mini) —— 一个专为 VMS 深度优化的 Vue 3 小程序框架。
 
-- `CACHE_STATISTICS_README.md` - 缓存统计系统使用指南
-- `CURRENT_SLOT_SOLUTION.md` - 当前插槽转译方案
-- `EVENT_PARAM_NAME_UNIFICATION.md` - 事件参数命名统一化
-- `INLINE_EVENT_HANDLER_README.md` - 内联事件处理器文档说明
-- `INLINE_EVENT_HANDLER_IMPLEMENTATION_GUIDE.md` - 内联事件处理器实现指南
-- `INLINE_EVENT_HANDLER_TEST_CASES.md` - 内联事件处理器测试用例
-- `P0_OPTIMIZATION_COMPLETED.md` - P0优化实施记录
-- `TEMPLATE_TRANSFORM_OPTIMIZATION_SUMMARY.md` - 模板转换优化总结
-- `TEST_SUMMARY.md` - 内联事件处理器测试总结
+## 功能特性
 
-### 📁 docs/planned - 未实现/计划中的功能
+- **Vue 3 SFC** - 完整的 `<script setup lang="ts">` + `<template>` + `<style>` 支持
+- **响应式绑定** - 自动收集 `ref` / `reactive` / `computed`，注入到小程序数据系统
+- **模板表达式** - 支持模板中的函数调用、方法访问、复杂表达式
+- **Class / Style 绑定** - 支持 `:class` 和 `:style` 的响应式绑定（通过 WXS）
+- **条件与列表渲染** - 支持 `v-if` / `v-else-if` / `v-else` 和 `v-for`
+- **事件处理** - 支持内联事件处理器、参数传递、修饰符（如.stop）
+- **插槽系统** - 支持默认插槽、具名插槽
+- **第三方组件** - 支持原生小程序组件和 npm 组件库
+- **分包支持** - 自动识别主包与独立分包，处理依赖复制
+- **开发体验** - 文件监听、增量编译、错误代码帧定位
+
+## 暂不支持（待完成）
+
+以下 Vue 特性目前尚未支持，将在后续版本中逐步实现：
+
+| 特性 | 说明 | 替代方案 |
+|------|------|---------|
+| `v-model` | 双向绑定 | 使用 `:value` + `@input` 手动实现 |
+| `defineModel` | 编译宏 | 使用 `props` + `emit` 手动实现 |
+| `useTemplateRef` | 组合式函数 | 使用小程序 `selectComponent` API |
+| `v-bind="obj"` | 整体绑定对象 | 暂无支持计划 |
+| `defineSlots` | 编译宏 | 不支持 |
+| 作用域插槽 | 插槽数据回传 | 难度大，排期优先级低 |
+| `<transition>` | 过渡组件 | 不支持 |
+| `<keep-alive>` | 缓存组件 | 不支持 |
+| `<Teleport>` | 传送组件 | 不支持 |
+| `<component :is>` | 动态组件 | 暂不支持 |
+| `v-html` | 原始 HTML | 不支持 |
+| `useSlots` | 组合式函数 | 不支持 |
+| `v-once` / `v-memo` | 渲染优化 | 不支持 |
 
-- `INLINE_EVENT_HANDLER_IMPROVEMENTS.md` - 内联事件处理器改进计划
-- `INLINE_EVENT_HANDLER_REFACTORING.md` - 内联事件处理器重构建议
-- `PERFORMANCE_OPTIMIZATION.md` - 编译速度优化分析报告
-- `SCOPED_SLOT_SOLUTION.md` - 作用域插槽转译方案
-- `TEMPLATE_TRANSFORM_OPTIMIZATION_PLAN.md` - 模板转换优化计划
-- `TRANSFORMER_DEPENDENCY_SOLUTION.md` - 转换器依赖关系解决方案
+## 安装
 
-### 📁 docs/architecture - 架构和设计文档
+```bash
+npm install -D @unmagic/vms
+# 或
+pnpm add -D @unmagic/vms
+```
 
-- `ARCHITECTURE.md` - 架构设计文档
-- `LOCAL_VAR_CONFLICT_HANDLING.md` - 局部变量冲突处理方案
+## CLI 命令
 
-## 功能特性
+安装后在项目目录下直接执行：
 
-- 将 Vue 3 单文件组件（SFC）编译为微信小程序代码
-- 支持模板中的函数表达式
-- 收集响应式变量和函数，并注入到 setup 函数的返回值中
-- 支持 class 和 style 的响应式绑定
-- 支持具名插槽和作用域插槽
+```bash
+# 开发模式（文件监听 + 增量编译）
+vms dev
 
-## 已知限制
+# 生产构建
+vms build
 
-### WXS 环境兼容性
+# 生产构建并上传小程序
+vms build --upload
+```
 
-VMS 生成的 WXS 代码运行在微信小程序的 WXS 环境中，该环境有以下限制：
+## 配置
 
-- **不支持 `?.` 可选链**：VMS 编译器会自动降级为条件表达式，无需手动处理
-- **不支持 `void 0`**：编译器自动替换为 `undefined`
-- **不支持 `$` 标识符**：编译器自动替换为 `_`
-- **不支持箭头函数、模板字符串**：编译器自动降级
+在项目根目录创建 `vms.config.js`
 
-### 首次渲染与 undefined
+```js
+export default {
+  // 微信小程序上传配置
+  wx: {
+    appid: 'your-appid',
+    privateKeyPath: '/path/to/private.key',
+    name: 'your-name',
+    email: 'your@email.com',
+    version: '1.0.0',
+    description: '项目描述',
+  },
 
-`@vue-mini/core` 框架在组件初始化时，部分响应式变量可能为 `undefined`。如果模板中使用了这些变量参与 WXS 计算（如 `:class`、`:style`、`v-if`），建议：
+  // 源码目录（默认 'src'）
+  sourceDir: 'src',
 
-- 在 `setup` 中为变量设置合理的初始值
-- 或在模板表达式中使用 `?.` 可选链（编译器会自动降级为安全的形式）
+  // 输出目录（默认 'dist'）
+  outputDir: 'dist',
 
-```vue
-<!-- 推荐：使用可选链，编译后不会因 undefined 报错 -->
-<div :class="{ active: user?.isAdmin }">
+  // 路径别名
+  alias: {
+    '@': './src',
+  },
 
-<!-- 不推荐：user 为 undefined 时 WXS 会抛出 TypeError -->
-<div :class="{ active: user.isAdmin }">
+  // 第三方组件匹配（可选）
+  component: {
+    prefix: 't-',
+    pathPrefix: 'tdesign-miniprogram',
+  },
+
+  // 跳过 Babel 编译直接复制的文件规则
+  copyOnly: [],
+}
 ```
 
-## 安装
+## 快速开始
 
-```bash
-npm install vue-mini-sfc
-```
+### 1. 创建应用入口
 
-## 使用方式
+```ts
+// src/app.ts
+import { createApp, onAppShow } from '@unmagic/vue-mini'
 
-### 作为 CLI 工具使用
+createApp({
+  setup(options) {
+    console.log('App Launched!', options)
 
-```bash
-vms
+    onAppShow((opts) => {
+      console.log('App Show!', opts)
+    })
+  },
+})
 ```
 
-### 配置
+### 2. 创建页面
 
-工具支持多种配置文件格式：`vms.config.js`、`vms.config.ts` 或 `vms.config.json`。
+```vue
+<!-- src/pages/index/Index.vue -->
+<script setup lang="ts">
+import { ref, computed } from '@unmagic/vue-mini'
 
-配置选项包括：
+const count = ref(0)
+const double = computed(() => count.value * 2)
 
-```javascript
-module.exports = {
-  // 源代码目录，默认为 'example'
-  sourceDir: 'example',
+const increment = () => {
+  count.value++
+}
+</script>
+
+<template>
+  <view class="container">
+    <text>Count: {{ count }}</text>
+    <text>Double: {{ double }}</text>
+    <button @click="increment">+1</button>
+  </view>
+</template>
+
+<style>
+.container {
+  padding: 20px;
+}
+</style>
+```
 
-  // 输出目录，默认为 'dist'
-  outputDir: 'dist',
+### 3. 注册页面
 
-  // 路径别名配置
-  alias: {
-    // 设置 @/ 路径对应的目录，默认为 './example'
-    // 如果你的源代码在 src 目录，可以设置为 './src'
-    '@': './example',
-  },
+```json
+// src/app.json
+{
+  "pages": [
+    "pages/index/Index"
+  ]
 }
 ```
 
-### 项目结构示例
+### 4. 启动开发
 
-```
-project/
-├── example/           # 源代码目录
-│   ├── app.json
-│   └── pages/
-├── dist/              # 编译输出目录
-└── vms.config.js      # 配置文件（可选）
+```bash
+vms dev
 ```
 
-## 开发
+编译输出到 `dist/` 目录，可直接使用微信开发者工具打开。
 
-```bash
-# 开发模式
-npm run dev
 
-# 构建
-npm run build
+## AI 开发助手（Agent Skill）
 
-# 代码格式化
-npm run lint
+VMS 项目内置了 AI Skill 文件，可配置到你的 AI 编程助手（如 Qoder、Cursor 等支持 Skill/Rule 的工具）中，让 AI 更准确地理解和生成 VMS 代码。
 
-# 链接全局命令，方便测试
-npm run link
-```
+### 获取 Skill
 
-在 example 目录中运行以下命令测试本地构建工具：
+Skill 文件位于 VMS 仓库的 [`skills/vms/SKILL.md`](https://github.com/unmagic/vms/blob/main/skills/vms/SKILL.md)。
 
 ```bash
-# 进入example目录
-cd example
+# 安装 vms skill
+npx skills add https://github.com/unmagic/vms/blob/main/skills/vms/SKILL.md
+
+```
+
+配置后，AI 助手在协助你在使用 VMS 编写微信小程序项目代码时，会自动遵循 Skill 中的语法规范和最佳实践。
+
+### Skill 内容涵盖
+
+- VMS 基础语法（`<script setup lang="ts">`、事件绑定、`v-for`、`v-show`）
+- 响应式数据（`ref`、`computed`、`watch`）
+- Class / Style 绑定规则
+- 插槽使用与限制
+- 组件通信（函数传递、页面跳转传参）
+- 生命周期对照表
+- 已知限制与替代方案
+- 常见问题和调试技巧
+
+
+## 已知限制
+
+### WXS 环境兼容性
 
-# 开发模式运行
-npm run dev
+VMS 生成的 WXS 代码运行在微信小程序的 WXS 环境中，该环境有以下限制，编译器会自动处理：
 
-# 构建模式运行
-npm run build
+| 特性 | 处理方式 |
+|------|---------|
+| `?.` 可选链 | 自动降级为条件表达式 |
+| `void 0` | 自动替换为 `undefined` |
+| `$` 标识符 | 自动替换为 `_` |
+| 箭头函数、模板字符串 | 自动降级 |
+
+### 首次渲染与 undefined
+
+组件初始化时部分响应式变量可能为 `undefined`。建议：
+
+- 在 `setup` 中设置合理的初始值
+- 或在模板中使用 `?.` 可选链
+
+```vue
+<!-- 推荐 -->
+<view :class="{ active: user?.isAdmin }">
+
+<!-- 不推荐：可能因 undefined 报错 -->
+<view :class="{ active: user.isAdmin }">
 ```
 
-### VS Code 配置
+## 项目结构示例
+
+```
+project/
+├── src/                   # 源代码目录
+│   ├── pages/             # 页面
+│   ├── components/        # 组件
+│   ├── subXXX/            # 分包
+│   ├── app.ts             # 应用入口
+│   ├── app.json           # 小程序配置
+│   └── app.wxss           # 全局样式
+├── dist/                  # 编译输出目录
+├── vms.config.js          # VMS 配置
+└── package.json
+```
+
+## 相关项目
+
+- [`@unmagic/vue-mini`](https://github.com/unmagic/vms-vue-mini) - VMS 配套的运行时框架
+- [Vue Mini](https://github.com/vue-mini/vue-mini) - 原版的 Vue 3 小程序框架
+
+## 许可证
 
-项目已配置 VS Code 在保存文件时自动进行 ESLint 格式化。推荐安装以下扩展：
+[MIT](https://opensource.org/licenses/MIT)
 
-- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
-- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
-- [Volar](https://marketplace.visualstudio.com/items?itemName=vue.volar)
+Copyright (c) 2026-present Liu Biao

package/bin/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander'
 import { createRequire } from 'module'
-import { runVMS } from '../dist/index.js'
+import { runBuildPackage, runVMS } from '../dist/index.js'
 const require = createRequire(import.meta.url)
 const pkg = require('../package.json')
 
@@ -24,4 +24,12 @@ program
     runVMS({ mode: 'development', upload: false })
   })
 
+// 组件包构建命令
+program
+  .command('package')
+  .description('构建组件包（在组件包根目录下执行，输出到 dist/）')
+  .action(() => {
+    runBuildPackage()
+  })
+
 program.parse()

package/dist/build-package-B3ztw0_M.js

@@ -0,0 +1,86 @@
+import { transformFileAsync, transformAsync } from '@babel/core';
+import { bold, green } from 'kolorist';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { performance } from 'perf_hooks';
+import { t as transformVueToMiniProgram, b as config } from './transformer-DjOYWuap.js';
+import '@vue/compiler-sfc';
+import 'node:fs';
+import 'node:fs/promises';
+import 'node:crypto';
+import '@babel/parser';
+import '@babel/types';
+import '@babel/generator';
+import '@babel/traverse';
+import '@babel/code-frame';
+import '@vue/compiler-dom';
+import 'node:url';
+import 'path';
+import 'url';
+import '@vue/compiler-core';
+
+async function buildPackage() {
+    const cwd = process.cwd();
+    const packageJsonPath = path.join(cwd, 'package.json');
+    if (!(await fs.pathExists(packageJsonPath))) {
+        console.error('❌ 当前目录下未找到 package.json，请在组件包根目录下执行此命令');
+        process.exit(1);
+    }
+    const packageJson = await fs.readJson(packageJsonPath);
+    const sourceDir = path.join(cwd, 'src');
+    const outputDir = path.join(cwd, 'dist');
+    if (!(await fs.pathExists(sourceDir))) {
+        console.error('❌ 当前目录下未找到 src/ 目录');
+        process.exit(1);
+    }
+    // 清空 dist
+    await fs.remove(outputDir);
+    await fs.ensureDir(outputDir);
+    console.log(bold(green(`开始构建组件包 ${packageJson.name}...`)));
+    // 递归编译
+    const compileDir = async (dir) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = path.relative(sourceDir, fullPath);
+            const outputPath = path.join(outputDir, relativePath);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules')
+                    continue;
+                await fs.ensureDir(outputPath);
+                await compileDir(fullPath);
+                continue;
+            }
+            if (entry.name.endsWith('.vue')) {
+                const t = performance.now();
+                await transformVueToMiniProgram(fullPath, outputDir, false, async (generatedCode) => {
+                    const result = await transformAsync(generatedCode, {
+                        filename: fullPath.replace('.vue', '.js'),
+                        ...config,
+                    });
+                    return result?.code ?? generatedCode;
+                }, sourceDir);
+                console.log(bold(green(`✓ ${relativePath} (${(performance.now() - t).toFixed(0)}ms)`)));
+            }
+            else if (entry.name.endsWith('.ts')) {
+                const result = await transformFileAsync(fullPath, { ast: false, ...config });
+                if (result?.code) {
+                    await fs.writeFile(outputPath.replace(/\.ts$/, '.js'), result.code);
+                }
+            }
+            else if (entry.name.endsWith('.js')) {
+                const result = await transformFileAsync(fullPath, { ast: false, ...config });
+                if (result?.code) {
+                    await fs.writeFile(outputPath, result.code);
+                }
+            }
+            else {
+                await fs.copy(fullPath, outputPath);
+            }
+        }
+    };
+    await compileDir(sourceDir);
+    console.log(bold(green(`构建完成，输出到 ${outputDir}`)));
+}
+
+export { buildPackage };