empjs · popey · Mar 13, 2026
diff --git a/.trae/skills/emp-best-practices/SKILL.md b/.trae/skills/emp-best-practices/SKILL.md
@@ -1,47 +1,97 @@
 ---
 name: emp-best-practices
-description: Expert guidance for EMP CLI, Rspack, and module federation. Invoke when developing micro-frontends, configuring builds, or debugging EMP projects.
+description: Configure module federation Host/Remote apps, resolve shared dependency conflicts, develop custom plugins, and debug EMP CLI builds with Rspack. Use when setting up micro-frontends (MFE), creating emp.config.ts, connecting React/Vue remotes, writing EMP plugins, or troubleshooting federated module loading.
 license: MIT
 compatibility: opencode
 metadata:
   audience: developers
+  version: "1.1"
   workflow: module-federation, plugin-development, framework-interop
 ---
 
-# EMP CLI 专家技能
+# EMP CLI Best Practices
 
-你是一个 EMP CLI 专家。你的任务是基于 @empjs/cli 帮助用户构建高性能的微前端应用。
-你需要参考以下文档来回答用户关于 EMP 架构、配置、插件开发和多框架互调的问题。
+Guides agents through EMP CLI micro-frontend architecture, module federation configuration, plugin development, and multi-framework interop using @empjs/cli and Rspack.
 
-## 🎯 核心能力
+## Quick Start: Minimal EMP Project
 
-- **微前端架构**：配置模块联邦，管理 Host 与 Remote 应用
-- **多框架互调**：实现 React (16-18)、Vue 2 和 Vue 3 的无缝协作
-- **性能优化**：利用 Rspack 的持久缓存、并行构建和代码分割
-- **插件生态**：使用官方插件或开发自定义插件扩展功能
-- **现代开发**：集成 TypeScript、TailwindCSS 和各类开发工具
+```bash
+pnpm create emp my-app && cd my-app && pnpm install && pnpm dev
+```
 
-## 📚 文档索引
+Minimal `emp.config.ts`:
 
-### 核心指南
-- [EMP CLI 架构与基础使用](./references/core/README.md)
-- [故障排除与调试](./references/core/troubleshooting.md)
+```typescript
+import { defineConfig } from '@empjs/cli'
+import pluginReact from '@empjs/plugin-react'
 
-### 模块联邦与架构
-- [模块联邦与 CDN 集成](./references/architecture/module-federation-cdn.md)
-- [同项目多端口架构](./references/architecture/multi-port-runtime-sharing.md)
-- [多框架互调指南](./references/interop/framework-interop-guide.md)
-  - [互调实现原理](./references/interop/framework-interop-implementation.md)
-  - [React 互调详解](./references/interop/framework-interop-react.md)
-  - [Vue 互调详解](./references/interop/framework-interop-vue.md)
+export default defineConfig(store => ({
+  plugins: [pluginReact()],
+  server: { port: 8000 },
+}))
+```
 
-### 插件系统
-- [插件使用场景指南](./references/plugins/plugin-usage-guide.md)
-- [插件开发指南](./references/plugins/plugin-development.md)
-- [React 插件指南](./references/plugins/react-plugins.md)
-- [Vue 插件指南](./references/plugins/vue-plugins.md)
-- [CSS/样式插件清单](./references/plugins/css-plugins.md)
+## Module Federation Setup
 
-### 性能与优化
-- [构建性能优化](./references/performance/build-optimization.md)
-- [TailwindCSS 集成](./references/performance/tailwindcss-integration.md)
+### 1. Remote App (exposes components)
+
+```typescript
+import { pluginRspackEmpShare, externalReact } from '@empjs/share'
+
+pluginRspackEmpShare({
+  name: 'mfHost',
+  exposes: { './App': './src/App' },
+  manifest: true, // generates emp.json
+  empRuntime: {
+    framework: { global: 'EMP_ADAPTER_REACT', libs: [`https://unpkg.com/@empjs/cdn-react@0.19.1/dist/react.${store.mode}.umd.js`] },
+    runtime: { lib: `https://unpkg.com/@empjs/share@3.11.4/output/sdk.js` },
+    setExternals: externalReact,
+  },
+})
+```
+
+### 2. Host App (consumes remotes)
+
+```typescript
+remotes: { mfHost: `mfHost@http://${store.server.ip}:6001/emp.json` }
+```
+
+### 3. Verify Federation
+
+```bash
+curl http://localhost:6001/emp.json  # confirm remote is serving
+```
+
+## Troubleshooting
+
+| Symptom | Check | Fix |
+|---------|-------|-----|
+| Remote module not loading | `curl` the remote `emp.json` URL | Ensure `manifest: true` is set and remote app is running |
+| React multi-instance error | Check shared dependency config | Add `singleton: true` to shared React config |
+| Type mismatch across apps | Verify `requiredVersion` in shared config | Align React versions across Host and Remote |
+
+## Reference Index
+
+### Core
+- [Troubleshooting & Debugging](./references/core/troubleshooting.md)
+
+### Architecture
+- [Module Federation & CDN](./references/architecture/module-federation-cdn.md)
+- [Multi-Port Runtime Sharing](./references/architecture/multi-port-runtime-sharing.md)
+
+### Framework Interop
+- [Multi-Framework Guide](./references/interop/framework-interop-guide.md) — React (16-18), Vue 2/3
+  - [Implementation Details](./references/interop/framework-interop-implementation.md)
+  - [React Interop](./references/interop/framework-interop-react.md)
+  - [Vue Interop](./references/interop/framework-interop-vue.md)
+
+### Plugins
+- [Plugin Usage Guide](./references/plugins/plugin-usage-guide.md)
+- [Plugin Development](./references/plugins/plugin-development.md)
+- [React Plugins](./references/plugins/react-plugins.md)
+- [Vue Plugins](./references/plugins/vue-plugins.md)
+- [CSS/Style Plugins](./references/plugins/css-plugins.md)
+
+### Performance
+- [Build Optimization](./references/performance/build-optimization.md)
+- [TailwindCSS Integration](./references/performance/tailwindcss-integration.md)
diff --git a/skills/empjs/SKILL.md b/skills/empjs/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: empjs
-description: EMP 全栈技能：React 19 脚手架脚本、emp.config.ts 配置、Tailwind v4、微前端 empRuntime、@empjs/valtio 状态管理、React 性能优化。适用于创建 EMP 应用、配置模块联邦、状态管理、性能优化等场景。
+description: Scaffold React 19 projects, configure emp.config.ts, integrate Tailwind v4, set up empRuntime micro-frontends, and manage state with @empjs/valtio. Use when creating new EMP apps, configuring module federation remotes, setting up state management, or optimizing React performance.
 ---
 
 # EMP 全栈技能
@@ -22,7 +22,7 @@ node skills/empjs/scripts/create-emp-react19.js my-app
 node skills/empjs/scripts/create-emp-react19.js my-app ./projects
 ```
 
-生成后执行 `cd <项目名> && pnpm install && pnpm dev`。
+生成后执行 `cd <项目名> && pnpm install && pnpm dev`。验证：浏览器打开 `http://localhost:8000` 确认页面加载正常。
 
 生成结构：`package.json`、`emp.config.ts`、`tsconfig.json`、`src/index.html`、`src/index.tsx`、`src/bootstrap.tsx`、`src/App.tsx`、`src/style.css`、`src/global.d.ts`。
 
@@ -55,9 +55,9 @@ project/
 ### 启动命令
 
 ```bash
-pnpm dev      # 开发
-pnpm build    # 构建
-pnpm start    # 预览
+pnpm dev      # 开发 — 验证: 浏览器访问 localhost:端口号
+pnpm build    # 构建 — 验证: dist/ 目录生成且包含 index.html
+pnpm start    # 预览 — 验证: 生产构建在浏览器正常渲染
 ```
 
 ## 三、package.json scripts 补全