@lark-apaas/coding-miaoda-sandbox-skills 0.1.43 → 0.1.45

package/miaoda/import-migration/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: import-migration
+description: Use when the workspace was created by importing an external project (Lovable / Replit / Gemini / zip) and the imported code still needs to be migrated into the Miaoda template. 触发词：导入项目, 项目迁移, 完成项目迁移, 我已导入项目代码, lovable, replit, gemini, zip 导入
+hook: SessionStart
+workspace-contains:
+  - .spark/import/MIGRATION_PENDING
+---
+
+# 导入项目迁移
+
+当前工程是「外部项目导入」创建的：平台先用妙搭模板初始化了工程（模板可正常运行），再把用户上传的项目按规则叠加进来。叠加只做了文件放置，**没有合并 package.json、没有安装依赖、没有改写任何代码**。你的任务是把用户项目迁移成能在妙搭模板上构建、运行的应用，保留用户项目的页面、交互与视觉风格。
+
+`.spark/import/MIGRATION_PENDING` 存在即表示迁移尚未完成。用户的首条消息通常是「我已导入项目代码，请帮我完成项目迁移」——直接开始迁移，不要再向用户确认是否需要迁移。迁移范围只包括前端代码，服务端代码不迁移。
+
+## 先读这些
+
+| 文件 | 内容 |
+| --- | --- |
+| `.spark/import/manifest.json` | 导入记录：`platform`、文件放置统计、`dependencies`（依赖对比）、`excludedPaths`、`protectedConflicts`、`replacedTemplateFiles` |
+| `source_package/` | 用户项目中未能直接放进 `client/`、`shared/` 的全部文件，原样保留：用户的 `package.json`、`vite.config.*`、`index.html`、入口 `App.tsx` / `main.tsx`、`index.css`、supabase 集成等 |
+| `client/src/` | 模板前端；用户的 `src/` 已按平台规则叠加到这里 |
+
+### 文件放在了哪里
+
+| 平台 | 已放进工程的 | 留在 `source_package/` 的 |
+| --- | --- | --- |
+| lovable / zip | `src/**` → `client/src/**`；`public/**` → `client/public/**` | `src/App.tsx`、`src/main.tsx`、`src/index.css`、`src/hooks/use-mobile.tsx`、supabase / `src/db`、`src/integrations` 等，以及根目录其他文件 |
+| replit | `client/src/**`、`shared/**` 原位；`attached_assets/**` → `client/public/assets/**` | `client/src/App.tsx`、`main.tsx`、`index.css`，以及 `server/` 等其他文件 |
+| gemini | `components/`、`services/`、`types.ts`、`constants.ts` → `client/src/` 下同名位置 | 其余全部（含 `App.tsx`、`index.html`） |
+
+- 会覆盖模板托管文件的导入文件（根 `package.json` / 构建配置 / `client/src/index.tsx` 等）一律改放 `source_package/`，见 manifest `protectedConflicts`。
+- 用户同名 UI 组件会覆盖模板 `client/src/components/ui/` 下的组件；zip 导入的同名 JS / JSX 版 UI 组件例外：保留模板 TS / TSX 版，源文件放在 `source_package/`，见 `protectedConflicts`。
+
+## 迁移流程
+
+用 TodoWrite 按以下步骤建立任务，逐项推进并如实更新状态。
+
+### Step 1：按平台与项目类型选指南
+
+按 manifest 的 `platform` 读对应指南（平台文件只写差异，必须与通用指南一起读）：
+
+| `platform` | 必读 |
+| --- | --- |
+| `lovable` | `references/react-migration.md` + `references/lovable.md` |
+| `replit` | `references/react-migration.md` + `references/replit.md` |
+| `gemini` | `references/react-migration.md` + `references/gemini.md` |
+| `zip` | 先识别项目类型（下表） |
+
+`zip` 的项目类型：
+
+| 条件 | 类型 | 必读 |
+| --- | --- | --- |
+| `source_package/package.json` 含 `react` 依赖，或 `client/src/` 下已有用户的 `.tsx` / `.jsx` | React | `references/react-migration.md` |
+| 存在 `source_package/*.html` 且无 React | HTML | `references/html-migration.md` |
+| 都不是 | 其他 | 参考 `source_package/` 内容，在模板中按需求重新实现，并向用户说明 |
+
+### Step 2：按 manifest 处理依赖
+
+依赖没有合并进工程 `package.json`。按 manifest `dependencies[].status` 处理：
+
+| status | 含义 | 处理 |
+| --- | --- | --- |
+| `missing` | 模板没有 | 迁移后的代码确实 import 了才安装，用 `package_manager` 工具安装；没用到的不装 |
+| `present` | 模板已有（`templateRange` 为模板版本） | 沿用模板版本，不装用户版本；API 不兼容时改用户代码 |
+| `build_chain` | 构建链 / 工具链（vite 插件、eslint、lovable-tagger 等） | 不装，模板有自己的构建体系；相关代码直接删除 |
+| `platform_managed` | 平台包 `@lark-apaas/*` | 不装，以模板为准 |
+
+安装遇到 peer dependency 冲突时：
+
+- 先尝试换用支持 React 19 的版本或替代库；仍失败就放弃该依赖，改写相关代码。
+- **禁止** `--force`、`--legacy-peer-deps`。
+- **禁止**降级模板核心依赖（React 19、Tailwind 4、vite 等）来迁就用户代码。
+- 妙搭不支持 Supabase：不要安装 `@supabase/*`，按迁移指南移除相关代码。
+
+### Step 3：按迁移指南迁移代码
+
+按 Step 1 选定的指南执行。共通要点：
+
+- 迁移后保留的业务代码统一使用 TS / TSX：将 `client/src/`、`shared/` 中的业务 JS / JSX 原地转换，从 `source_package/` 补入的代码也按此处理，见 `react-migration.md` 4.3。HTML 项目转换出的组件和逻辑同样使用 TS / TSX。
+- 主题：把源项目的 CSS 变量融合进 `client/src/tailwind-theme.css`（Tailwind 3 → 4 语法）。
+- 入口：参考源项目的 App 入口（实际路径和扩展名以导入结果为准）在 `client/src/pages/` 下创建 TSX 页面，并在 `client/src/app.tsx` 的路由中替换模板的 `Welcome` 首页。
+- 导入路径统一改为 `@/` 别名（指向 `client/src/`）。
+- `public` 资源路径拼接 `process.env.CLIENT_BASE_PATH`。
+- 环境变量 `import.meta.env.VITE_*` 改为 `process.env.*`。
+
+#### 保留源项目的资源引用
+
+迁移的目标是还原源项目，不是按新建应用的规范重做。以下内容原样保留：
+
+- 外链图片（`<img src="https://...">`、头像、配图）和 CSS 背景图（`url(...)`）。
+- 字体：字体族和字重都要保留，字体链接 URL 不删减。
+- emoji 和图标：不把 emoji 换成 lucide 等图标，不删减源项目已有的图标。
+
+具体规则：
+
+- 不替换成 `generate_image` 生成图、模板内置头像（`img-resources/avatar-placeholders`）或其他占位图；coding-guide 中的「图片资源优先级」只适用于迁移完成后新增的内容。
+- 外链资源即使已失效（404）或每次随机（如不带 seed 的 `picsum.photos/...?random=N`），也保持原状，不自行「修复」或补一个新效果——源页面在浏览器里就是这样显示的，替换反而会让页面与源项目不一致。在收尾说明里列出失效的资源，由用户决定是否替换。
+- 例外：CDN `<script src>` 引入的 JS 库和 Tailwind CDN 仍按迁移指南改为 npm 包 / 模板样式体系（预览 CSP 会拦截 CDN 脚本）。
+
+### Step 4：类型检查验证
+
+先实际运行文件残留检查：
+
+```bash
+find client/src shared -type f \( -name '*.js' -o -name '*.jsx' \)
+```
+
+这些源码目录中保留的业务 JS / JSX 必须全部转换，不能仅凭类型检查通过就认为转换完成。`source_package/` 中的参考文件和模板配置、脚本不在转换范围内。
+
+运行 `npm run type:check`，按报错修复，直到通过。常见错误见迁移指南末尾。不要为了让检查通过而修改 `tsconfig*.json` 等配置，也不要关闭 strict。
+
+预览由开发服务器实时提供，改完代码即生效，不需要构建。**禁止**在沙箱里运行 `npm run build`、`build:client`、`build:prod`、`vite build`：生产构建会覆盖预览页使用的 `dist/client/index.html`，导致预览白屏。
+
+### Step 5：收尾
+
+1. 收尾前逐项自查，确认首页样式已生效、不是无样式的单列布局：
+   - 源项目 `tailwind.config` 的自定义主题已迁移（含 `container` 宽度），见 `react-migration.md` 1.3。
+   - 字体已迁移，见 1.4。
+   - `App.tsx` 里的全部 Provider 和 Toaster 已迁移，见第 8 节。
+2. **必须实际运行**下面的残留检查，不能凭印象跳过：
+
+   ```bash
+   grep -rnE 'hsl\(var\(--|-opacity-[0-9]|-\[--' client/src
+   ```
+
+   每一处命中都按 `react-migration.md` 修掉（`hsl(var(--x))` 见 1.1，包括 SVG 的 `stroke` / `fill` 属性；`bg-opacity-*` 等见 4.2；`-[--x]` 见 4.1），改完重跑，直到没有命中。模板自带的 `components/ui/sidebar.tsx`、`toggle-group.tsx` 中的命中（没被用户文件覆盖时）可以忽略。这几类写法在 Tailwind 4 下不报错，但颜色或透明度会静默失效（如半透明白底变成不透明白块、盖住文字）。
+3. 删除 `.spark/import/MIGRATION_PENDING`（删除后本 skill 不再加载）。**只有业务 JS / JSX 已全部转换、类型检查通过、样式残留检查无命中、首页能展示迁移后的内容才删除**；迁移未完成时保留它，下次会话继续。
+4. 提交全部改动（包括删除标记），确认 `git status` 没有未提交的文件。
+5. 向用户简要说明：迁移了哪些页面与功能、未迁移或改为演示数据的部分（如 Supabase 数据、服务端逻辑）及原因、源项目中已失效的外链资源、仍需用户确认的事项。
+
+## 约束
+
+| 允许 | 禁止 |
+| --- | --- |
+| 修改 `client/src/`、`shared/` 下的代码与样式；在 `client/src/index.tsx` 的 `MainApp` 中补充源项目需要的 Provider | 修改 `vite.config.*`、`tsconfig*.json`、`eslint.config.*`、`postcss` / tailwind 配置 |
+| 通过 `package_manager` 工具安装 Step 2 判定需要的依赖 | 手工编辑根 `package.json` 合并用户依赖 |
+| 读取、参考 `source_package/` 中的任何文件 | 在 `source_package/` 里构建或运行，或把它作为运行时依赖 |
+| 按需从 `source_package/` 补齐缺失的 UI 组件 | 删除 `client/src/components/ui/` 中已有组件 |
+| | 删除或改写 `.spark/import/manifest.json`；自行执行 `miaoda app import` |
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+| --- | --- |
+| 照着 `source_package/package.json` 全量安装依赖 | 按 manifest status 逐个判断，只装代码真正用到的 `missing` 依赖 |
+| 把 vite / `@vitejs/plugin-react-swc` / lovable-tagger 装回来 | `build_chain` 一律不装，删掉相关引用 |
+| 用 `--legacy-peer-deps` 硬装 | 换兼容版本或放弃该依赖，改写代码 |
+| 只复制组件、没接路由，首页仍是模板 Welcome | 创建页面并在 `client/src/app.tsx` 注册首页路由 |
+| 跑 `npm run build` / `build:client` 验证 | 用 `npm run type:check`；生产构建会覆盖预览页导致白屏 |
+| 把源项目的外链图片换成生成图、内置头像或占位图 | 原样保留源项目的资源引用 |
+| 源项目的外链资源已失效，自己补一个效果（如另写噪点背景） | 保持原状，收尾时告诉用户 |
+| 业务 JS / JSX 未转完或类型检查没过就删 `MIGRATION_PENDING` | 完成转换、类型检查通过、首页可展示后再删除 |
+| 只迁了 `index.css`，漏了 `tailwind.config` 的 animation / colors / fontFamily | 按 `react-migration.md` 1.3 逐项迁到 `@theme` |
+| 变量包了 `hsl()`，代码里仍写 `hsl(var(--x))` | 改为 `var(--x)` |
+| 认为模板已有 Toaster，没挂 shadcn 的 `@/components/ui/toaster` | 模板只有 sonner，shadcn toaster 要另外挂载 |
+| JSX 项目页面无样式时扩大 tailwind 扫描范围 | 将业务 JS / JSX 转为 TS / TSX，修复引用并检查样式，见 `react-migration.md` 4.3 |
+| 把 emoji 换成图标、删减字体字重 | 原样保留 |
+| 删了标记却没提交，或留下未提交文件 | 提交全部改动，`git status` 干净 |
+| 迁移前反复向用户确认 | 直接开始迁移，完成后再说明结果 |

package/miaoda/import-migration/references/gemini.md

@@ -0,0 +1,60 @@
+# Gemini 平台差异
+
+与 `react-migration.md` 一起使用：通用步骤按该文件执行，本文件只列 Gemini 特有的部分。
+
+## 环境差异
+
+| 项 | Gemini | 妙搭模板 |
+| --- | --- | --- |
+| React | 19 | 19 |
+| Tailwind | CDN + `index.html` 内联 `tailwind.config` | 4 |
+| 目录结构 | 根目录平铺（无 `src/`） | `client/src/` |
+| AI 能力 | `@google/genai` | 妙搭 AI 插件 |
+
+## 文件位置
+
+| Gemini 源路径 | 当前位置 | 处理 |
+| --- | --- | --- |
+| `components/**` | `client/src/components/**` | 直接可用，不要重新创建 |
+| `services/**` | `client/src/services/**` | 含 `geminiService`，需迁移为 AI 插件 |
+| `types.ts`、`constants.ts` | `client/src/types.ts`、`client/src/constants.ts` | 直接可用 |
+| `App.tsx` | `source_package/App.tsx` | 参考创建页面 |
+| `index.tsx` | `source_package/index.tsx` | 不需要 |
+| `index.html` | `source_package/index.html` | 提取主题、字体、内联样式 |
+| 其他 | `source_package/` | 按需参考 |
+
+## 特有步骤
+
+1. **主题**：`source_package/index.html` 中 `<script>tailwind.config = {...}</script>` 的颜色、字体写进 `client/src/tailwind-theme.css`：
+
+   ```css
+   :root {
+     --brand-accent: #00dc82;
+   }
+
+   @theme inline {
+     --color-brand-accent: var(--brand-accent);
+   }
+   ```
+
+   `<head>` 中的 Google Fonts `<link>` 复制到 `client/index.html`；`<style>` 中的 CSS（字体、滚动条等）追加到 `client/src/index.css`。删除 Tailwind CDN script，`client/index.html` 中不能保留 `<script src="https://...">`。
+
+2. **入口**：参考 `source_package/App.tsx` 创建 `client/src/pages/Home/Home.tsx`，复制完整 JSX，**保留外层 div 及其类名**（如 `min-h-screen flex flex-col`，是布局必需的）；把 `App.tsx` 中的 state 一并迁过来。在 `client/src/app.tsx` 注册首页路由。
+
+3. **导入路径**：组件中的 `../constants`、`../types`、`../services/...` 改为 `@/constants`、`@/types`、`@/services/...`。
+
+4. **`@google/genai` → 妙搭 AI 插件（关键）**：不要安装 `@google/genai`。先读 `plugin-guide` skill，再按其流程：
+   1. 分析 `client/src/services/geminiService.ts` 中每个函数的用途，对应到 AI 智能生文 / 生图 / 图片理解等插件。
+   2. 复用 `available_plugin_instances` 中合适的实例；没有就用 `plugin_instance` 工具创建，禁止直接改 `server/capabilities/`。
+   3. 对实例调用 `get_plugin_ai_json` 拿到 actions、inputSchema、outputSchema、outputMode，严格按 schema 构造参数，不要猜。
+   4. 默认在 Client 侧调用：`unary` 用 `capabilityClient.load(id).call(actionKey, input)`，`stream` 用 `callStream`；在 `client/src/services/aiService.ts` 中实现并替换原调用。
+
+5. **环境变量**：`process.env.API_KEY` / `GEMINI_API_KEY` 随 `@google/genai` 一起移除，插件调用不需要用户自带 key。
+
+## 常见编译错误
+
+| 错误 | 修复 |
+| --- | --- |
+| `Cannot find module '@google/genai'` | 按第 4 步迁移为 AI 插件 |
+| `Cannot find module '../constants'` / `'../types'` | 改为 `@/constants` / `@/types` |
+| `bg-brand-accent` 等类无效 | 主题变量未写入 `tailwind-theme.css` |

package/miaoda/import-migration/references/html-migration.md

@@ -0,0 +1,147 @@
+# HTML 项目迁移指南
+
+适用于不含 React 的普通 zip 包：`*.html` + `css/` + `js/` + 静态资源。
+
+## 文件位置
+
+| 源路径 | 当前位置 | 说明 |
+| --- | --- | --- |
+| `*.html` | `source_package/*.html` | 转换为 React 页面 |
+| `css/**`、`js/**` | `source_package/` | 参考转换 |
+| `src/**`、`public/**` | `client/src/**`、`client/public/**` | 已放进工程 |
+| 其他（`images/`、`assets/`、`fonts/` 等） | `source_package/` | 需要的搬到 `client/public/` |
+
+## 迁移顺序
+
+1. H0：外部依赖扫描，CDN 改 npm（**必须最先做**）
+2. H1：分析 HTML 结构
+3. 主题与样式迁移
+4. H2：HTML 转 React 组件
+5. H3：CSS 迁移
+6. H4：JS 逻辑转 React state
+7. 静态资源与路径修正
+8. H5：创建页面并配置路由
+9. `npm run type:check` 类型检查验证（不要运行 `npm run build`，见 SKILL.md Step 4）
+
+## H0. 外部依赖扫描，CDN 改 npm
+
+CDN `<script src>` 引入的全局变量（`d3`、`gsap`、`am5` 等）在 React 组件里不存在。先转 React 会写出 `declare const xxx: any` 兜底，这是错误用法。先把 CDN 换成 npm 包。
+
+扫描：
+
+```bash
+grep -n -E 'src="https?://[^"]+\.(js|css)"' source_package/*.html
+```
+
+逐条按规则归类：
+
+| 来源 | 处理 |
+| --- | --- |
+| 模板 `package.json` 已有 | 改 ES `import`，删 CDN 引用 |
+| 有官方 npm 包 | 用 PackageManager 安装（dependencies，不是 dev），改 `import`，删 CDN 引用 |
+| 无 npm 等价（极少见） | 保持原状，并在收尾说明中列出 |
+| Tailwind / Bootstrap 等 CSS 框架 | 删 CDN，样式按「主题与样式迁移」处理 |
+
+示例（多数库 npm 包名就是库名）：
+
+| CDN 库 | 处理 |
+| --- | --- |
+| ECharts | 先查模板是否已有 `echarts` / `echarts-for-react`，有就不要重装 |
+| Chart.js | 优先改用 echarts；不可行再装 `chart.js` |
+| amCharts 5 | `@amcharts/amcharts5`，地图数据 `@amcharts/amcharts5-geodata` |
+| Three.js | `three`，React 集成 `@react-three/fiber` |
+
+H0 完成检查：
+
+- [ ] 扫描出的所有库都已处理。
+- [ ] 最终 `client/index.html` 中没有任何 `<script src="https://...">`（预览 CSP 会拦截 CDN，导致白屏）。
+- [ ] 没有 `declare const xxx: any` 这类全局变量兜底声明。
+
+## H1. 分析 HTML 结构
+
+分析 `source_package/*.html`，识别页面结构（header / main / footer）和可复用的部分（导航栏、卡片、表单等）。
+
+## 主题与样式迁移
+
+读取源 CSS（`source_package/css/*.css` 或 `<style>` 块）里的颜色、字体等设计 token，融合到 `client/src/tailwind-theme.css`。颜色变量统一写成 `hsl()` 形式，并在 `@theme inline` 中映射：
+
+```css
+:root {
+  --primary: hsl(210 100% 50%);
+}
+
+@theme inline {
+  --color-primary: var(--primary);
+}
+```
+
+## H2. HTML 转 React 组件
+
+| HTML | JSX |
+| --- | --- |
+| `class` | `className` |
+| `for` | `htmlFor` |
+| `onclick="..."` | `onClick={handler}` |
+| `style="color: red"` | `style={{ color: 'red' }}` |
+| `<img>`、`<input>`、`<br>` | 自闭合 `/>` |
+
+```tsx
+// client/src/components/HeroSection.tsx
+const BASE_PATH = process.env.CLIENT_BASE_PATH || '';
+
+export const HeroSection = () => {
+  const handleClick = () => {
+    /* 原 JS 逻辑 */
+  };
+  return (
+    <section className="hero">
+      <h1 className="title">Welcome</h1>
+      <button className="btn" onClick={handleClick}>Get Started</button>
+      <img src={`${BASE_PATH}/images/hero.png`} alt="Hero" />
+    </section>
+  );
+};
+```
+
+## H3. CSS 迁移
+
+- 推荐：转为 Tailwind 类（`padding: 16px` → `p-4`，`display:flex; justify-content:center` → `flex justify-center`）。
+- 复杂或量大的样式可保留原 CSS：放到 `client/src/styles/legacy.css`，在页面或 `client/src/index.css` 中引入。
+
+## H4. JS 逻辑转 React
+
+| 原生写法 | React 写法 |
+| --- | --- |
+| `document.getElementById('x').classList.toggle('hidden')` | `const [visible, setVisible] = useState(false)` + 条件 className |
+| 表单 `input.value` 读写 | 受控组件 `value` + `onChange` |
+| `setInterval` / 事件监听 | `useEffect` 中注册，并在 cleanup 中清除 |
+| jQuery | 移除，改 React state 与事件 |
+| Bootstrap JS | 移除，改用模板 `client/src/components/ui/` 中的组件 |
+
+## 静态资源与路径
+
+- 被引用的 `images/`、`fonts/` 等资源搬到 `client/public/` 下同名目录。
+- 引用时拼接 `process.env.CLIENT_BASE_PATH`；CSS 里的背景图改成内联 style 拼路径，或搬到 `client/src/assets/` 用 import。
+
+## H5. 页面与路由
+
+- 每个 HTML 文件对应一个 React 页面，放在 `client/src/pages/<Name>/<Name>.tsx`。
+- 首页（通常是 `index.html`）在 `client/src/app.tsx` 中替换模板的 `Welcome`；其他页面注册对应路由。
+- 内部链接 `<a href="about.html">` 改为 `<Link to="/about">`；外部链接保留 `<a target="_blank" rel="noopener noreferrer">`。
+
+## 常见编译错误
+
+| 错误 | 原因 | 修复 |
+| --- | --- | --- |
+| `class` / `for` 属性无效 | HTML 属性 | 改为 `className` / `htmlFor` |
+| JSX must have one parent | 多个根元素 | 用 `<>...</>` 包裹 |
+| `xxx is not defined` / 预览白屏 | CDN 全局变量 | 按 H0 改 npm |
+| 图片 404 | 未拼接路径 | 拼接 `CLIENT_BASE_PATH` |
+| `Parameter implicitly has an 'any' type` | 缺类型 | 补 TypeScript 类型 |
+
+## 验收
+
+1. `npm run type:check` 通过。
+2. 首页路由展示迁移后的内容，各 HTML 页面都有对应路由。
+3. `client/index.html` 中没有 CDN script。
+4. 主要交互可响应，样式与源页面基本一致。

package/miaoda/import-migration/references/lovable.md

@@ -0,0 +1,42 @@
+# Lovable 平台差异
+
+与 `react-migration.md` 一起使用：通用步骤按该文件执行，本文件只列 Lovable 特有的部分。
+
+## 环境差异
+
+| 项 | Lovable | 妙搭模板 |
+| --- | --- | --- |
+| React | 18 | 19 |
+| Tailwind | 3（裸 HSL 变量） | 4（`hsl()` + `@theme inline`） |
+| 后端 | Supabase | 不支持，需移除 |
+
+## 文件位置
+
+| Lovable 源路径 | 当前位置 | 处理 |
+| --- | --- | --- |
+| `src/components/**` | `client/src/components/**` | 直接可用；移除其中的 Supabase 依赖 |
+| `src/pages/**` | `client/src/pages/**` | 直接可用 |
+| `src/hooks/**` | `client/src/hooks/**` | 直接可用（`use-mobile.tsx` 已排除，用模板的 `use-mobile.ts`） |
+| `src/lib/**` | `client/src/lib/**` | 直接可用（`supabase.ts` 已排除） |
+| `src/integrations/**`、`src/lib/supabase.ts`、`supabase/**` | `source_package/` | 不迁移 |
+| `src/App.tsx` | `source_package/src/App.tsx` | 参考创建页面与路由 |
+| `src/main.tsx` | `source_package/src/main.tsx` | 不需要 |
+| `src/index.css` | `source_package/src/index.css` | 提取主题变量与自定义样式 |
+| `public/**` | `client/public/**` | 路径不变，引用需拼 `CLIENT_BASE_PATH` |
+
+## 特有步骤
+
+1. **主题**：`source_package/src/index.css` 是 Tailwind 3 写法，`:root` / `.dark` 中的裸 HSL 值（如 `--primary: 210 100% 50%`）全部包裹成 `hsl()` 后融合进 `client/src/tailwind-theme.css`；`@layer`、`@keyframes` 等自定义样式追加到 `client/src/index.css`。代码里的 `hsl(var(--x))` 同步改为 `var(--x)`；`tailwind.config.ts` 的 `keyframes` / `animation`（Lovable 常见 `fade-in`、`slide-up` 等）按 `react-migration.md` 1.3 迁到 `@theme`。
+2. **Tailwind 变量语法**：Lovable 组件大量使用 `w-[--sidebar-width]` 这类写法，必须全量改为 `w-[var(--sidebar-width)]`（grep `-[--`）。
+3. **Supabase**：Lovable 项目几乎都带 Supabase 认证与数据读写，按 `react-migration.md` 第 5 节逐项移除（`supabase.auth.*` → 演示登录态，`supabase.from()` → 本地 state + 静态数据）。
+4. **lovable-tagger**：删除 `componentTagger` / `ComponentTagger` 的 import 与使用；该依赖在 manifest 中为 `build_chain`，不要安装。
+5. **入口**：参考 `source_package/src/App.tsx` 创建 `client/src/pages/Home/Home.tsx`，复制 JSX 结构（去掉外层 Router / Provider），并在 `client/src/app.tsx` 注册路由。
+6. **Toaster**：Lovable 的 `App.tsx` 通常同时挂 `@/components/ui/toaster`（shadcn toast）和 `@/components/ui/sonner`。模板只挂了 sonner，shadcn 的 `Toaster` 要按 `react-migration.md` 第 8 节加到 `MainApp`。
+
+## 常见编译错误
+
+| 错误 | 修复 |
+| --- | --- |
+| `Cannot find module 'lovable-tagger'` | 删除相关代码 |
+| `Cannot find module '@/integrations/supabase/client'` | 按第 3 步移除 Supabase |
+| `bg-primary` 无效 | 变量值包裹 `hsl()` |

package/miaoda/import-migration/references/react-migration.md

@@ -0,0 +1,310 @@
+# React 项目迁移指南
+
+适用于 Lovable、Replit、Gemini 导出的 React 项目，以及含 React 的普通 zip 包。这里是各平台共通的步骤；来自 Lovable / Replit / Gemini 的项目还要同时读对应的平台文件（`lovable.md` / `replit.md` / `gemini.md`），两者冲突时以平台文件为准。
+
+## 环境差异
+
+| 项 | 源项目（常见） | 妙搭模板 |
+| --- | --- | --- |
+| React | 18 | 19 |
+| Tailwind | 3 | 4 |
+| 构建 | 自带 vite 配置 | 模板 vite 配置（不可改） |
+| 前端根目录 | `src/` | `client/src/`（`@/` 别名指向这里） |
+
+## 迁移顺序（严格遵守）
+
+源项目含 JS / JSX 时，先按 4.3 转为 TS / TSX，再执行以下步骤。
+
+1. 主题与样式迁移
+2. 修正导入路径
+3. 修正图片与静态资源引用
+4. 修复组件兼容问题（Tailwind 4 语法、缺失组件）
+5. 移除 Supabase / 服务端逻辑
+6. 删除平台特定代码（如 lovable-tagger）
+7. 环境变量适配
+8. 创建页面入口
+9. 更新路由
+10. `npm run type:check` 类型检查验证（不要运行 `npm run build`，见 SKILL.md Step 4）
+
+## 1. 主题与样式迁移
+
+### 1.1 CSS 颜色变量
+
+读取源项目样式入口（Lovable / zip：`source_package/src/index.css`；Replit：`source_package/client/src/index.css`）中 `:root`、`.dark` 的颜色变量，融合到 `client/src/tailwind-theme.css`。同名变量直接覆盖，不要为源项目新增一套平行变量。
+
+Tailwind 3 → 4 的 HSL 语法变化：
+
+```css
+/* 源：Tailwind 3 裸 HSL 值 */
+:root {
+  --primary: 210 100% 50%;
+  --background: 0 0% 100%;
+}
+
+/* 目标：必须包裹 hsl() */
+:root {
+  --primary: hsl(210 100% 50%);
+  --background: hsl(0 0% 100%);
+}
+
+@theme inline {
+  --color-primary: var(--primary);
+  --color-background: var(--background);
+}
+```
+
+变量值包上 `hsl()` 后，代码里原来的 `hsl(var(--x))` 就成了 `hsl(hsl(...))`，颜色失效（SVG 描边、图表配色消失）。全量 grep `hsl(var(--`，包括 TSX 里的 `stroke` / `fill` 属性（如 `stroke="hsl(var(--secondary))"`）、内联 style、图表配置和 Tailwind 任意值，统一改为 `var(--x)`；带透明度的 `hsl(var(--x) / 0.5)` 改为 `color-mix(in srgb, var(--x) 50%, transparent)`。
+
+### 1.2 自定义样式
+
+源样式入口里的自定义样式（`@layer`、`@keyframes`、全局类等）追加到 `client/src/index.css` 末尾。
+
+### 1.3 tailwind.config 中的自定义主题
+
+Tailwind 4 不读源项目的 `tailwind.config.*`。打开 `source_package/tailwind.config.*`，把 `theme.extend` 中每一项迁到 `client/src/tailwind-theme.css` 的 `@theme`：
+
+| 源配置 | 迁移为 |
+| --- | --- |
+| `keyframes` + `animation` | `@keyframes slide-up { ... }` 写进 `client/src/index.css`，`@theme` 中加 `--animate-slide-up: slide-up 0.5s ease-out forwards;` |
+| `colors` | `--color-<name>: ...;`（嵌套色阶展开为 `--color-<name>-<shade>`） |
+| `fontFamily` | `--font-<name>: ...;` |
+| `boxShadow` / `backgroundImage` / `borderRadius` | `--shadow-*` / 写成 `@utility` / `--radius-*` |
+| `theme.container`（如 `center: true, padding: '2rem', screens: { '2xl': '1400px' }`） | 在 `client/src/index.css` 用 `@utility container` 还原，见下方示例 |
+
+`container` 不迁移时，Tailwind 4 会按默认断点把宽度卡在 1280px，比源项目窄。Lovable 常见配置 `center: true, padding: '2rem', screens: { '2xl': '1400px' }` 对应：
+
+```css
+@utility container {
+  margin-inline: auto;
+  padding-inline: 2rem;
+  @media (width >= 40rem) { max-width: none; }
+  @media (width >= 1400px) { max-width: 1400px; }
+}
+```
+
+`max-width: none` 用来取消 Tailwind 4 默认的分档宽度，第二个 `@media` 写源项目 `screens` 里的值。
+
+遗漏的后果很隐蔽：`animate-*` 动画类不存在时，带 `opacity-0` 初始态的元素会一直不可见。迁移后 grep 代码里用到的 `animate-`、`font-` 和自定义颜色类，逐个确认都有定义。
+
+### 1.4 字体
+
+源项目的字体引入（`index.html` 里的 Google Fonts `<link>`、`index.css` 里的 `@import url(...)`）原样复制，不要删减 URL 中的字重和字体族：只剩一个字重时，正文会整体变细或变粗。复制到 `client/index.html` 的 `<head>`。再按源项目设置 `body` 或 `--font-sans` 的 `font-family`，不要让页面回落到模板默认字体。
+
+## 2. 修正导入路径
+
+组件已放进 `client/src/`，内部相对路径改为 `@/` 别名：
+
+```tsx
+// 源
+import { Button } from '../components/ui/button';
+import { cn } from '../lib/utils';
+
+// 目标
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+```
+
+Replit 项目里 `@shared/*` 指向的 `shared/` 已原位放置，按模板 `tsconfig` 的别名修正引用；不要改 tsconfig。
+
+## 3. 图片与静态资源引用
+
+外链资源（`https://...` 图片、背景图、字体）原样保留，不替换成生成图或占位图，失效的也不修，见 SKILL.md「保留源项目的资源引用」。下面只处理本地资源。
+
+应用可能部署在子路径下，引用 `client/public/` 下的资源必须拼接 `process.env.CLIENT_BASE_PATH`：
+
+```tsx
+const BASE_PATH = process.env.CLIENT_BASE_PATH || '';
+
+// ❌ 子路径部署时失效
+<img src="/logo.png" />
+
+// ✅
+<img src={`${BASE_PATH}/logo.png`} />
+<div style={{ backgroundImage: `url('${BASE_PATH}/images/bg.jpg')` }} />
+```
+
+`src/assets/` 下的图片已在 `client/src/assets/`，用 import 引用（构建工具自动处理路径）：
+
+```tsx
+import heroImage from '@/assets/hero.png';
+<img src={heroImage} />
+```
+
+运行时 `fetch` 加载 public 下的 JSON / CSV 也会因子路径错位，报 404 或 `Unexpected token '<'`：
+
+- 静态数据优先搬到 `client/src/data/` 改用 `import`（编译期内联）。
+- 体积大（> 100KB）或必须动态加载的，拼 `BASE_PATH` 再 `fetch`。
+
+检查清单：
+
+1. 搜索 `src="/`、`url('/`、`fetch('/`、`fetch('./`，改为拼接 `BASE_PATH` 或 import。
+2. 搜索 import 图片扩展名（`.png` `.jpg` `.svg` `.gif` `.webp`），改为 `@/assets/` 路径，并确认文件存在。
+
+## 4. 组件兼容修复
+
+### 4.1 Tailwind 4 CSS 变量语法（必须执行）
+
+Tailwind 3 允许直接写 CSS 变量名，Tailwind 4 要求 `var()` 包裹：
+
+```tsx
+// ❌ Tailwind 3
+className="w-[--sidebar-width] h-[--header-height]"
+
+// ✅ Tailwind 4
+className="w-[var(--sidebar-width)] h-[var(--header-height)]"
+```
+
+用 grep 搜索 `-[--` 找出全部旧写法，改完再搜一次确认没有遗漏。
+
+### 4.2 Tailwind 3 → 4 移除或改名的写法（必须执行）
+
+| Tailwind 3 | Tailwind 4 |
+| --- | --- |
+| `bg-opacity-50`、`text-opacity-*`、`border-opacity-*`、`ring-opacity-*` 等 | 已移除，改为颜色斜杠写法：`bg-black bg-opacity-50` → `bg-black/50` |
+| `border` 不带颜色（v3 默认 gray-200） | v4 默认 `currentColor`；源项目依赖默认色时补 `border-border` 或具体颜色 |
+| `ring`（v3 默认 3px 蓝色） | v4 默认 1px `currentColor`；改为 `ring-3 ring-blue-500/50` 等显式写法 |
+| `flex-shrink-*` / `flex-grow-*` | `shrink-*` / `grow-*` |
+| `outline-none` | `outline-hidden` |
+
+grep 每一行左列的写法，改完再 grep 一次确认。
+
+### 4.3 JS / JSX 项目
+
+源项目是 `.js` / `.jsx`（如 NoCode）时，将迁移后保留的业务代码统一转换为 TS / TSX，适配模板现有的 `ts,tsx,css` 扫描范围，不修改 tailwind 配置：
+
+- CLI 已直接放进 `client/src/`、`shared/` 的业务文件原地转换；从 `source_package/` 补入的代码也要转换，原始参考文件保留。
+- 含 JSX 的 `.jsx` 或 `.js` 改为 `.tsx`，不含 JSX 的业务 `.js` 改为 `.ts`。补齐必要的 Props、事件、ref、state 等类型；不要用 `@ts-nocheck` 或批量 `any` 绕过检查，也不要修改 tsconfig。
+- 同步修复带扩展名的 import / export、动态 import 和文件匹配规则；确认转换后的代码被实际引用，删除旧 JS / JSX 文件。已有同名 TS / TSX 文件时先核对用途，不能直接覆盖或留下两份实现。
+- zip 导入中与模板同名的 JS 版 UI 组件放在 `source_package/src/components/ui/`（manifest `protectedConflicts`），工程里保留的是模板 TS 版。业务代码直接用模板版本，props 不兼容时改调用方，不要把源组件转换后覆盖回去；模板缺失的组件按 4.4 补齐并转成 TS / TSX。
+- 只处理业务代码，不批量改名 `source_package/`、模板配置或运行脚本。用户放在 public 中参与运行的业务 JS 也应迁入源码目录转换，不能用静态脚本加载来绕过迁移。
+
+### 4.4 缺失组件
+
+报 `Cannot find module '@/components/ui/xxx'` 时：
+
+1. 先看 `client/src/components/ui/` 是否已有该组件（模板自带一套 shadcn 组件）。
+2. 没有再从 `source_package/` 中找到源组件迁移过来，内部路径改为 `@/`。
+3. 不要删除模板已有的 UI 组件。
+
+### 4.5 React 19 兼容
+
+- 删除 `React.FC` 隐式 `children` 依赖，显式声明 `children` 类型。
+- `ReactDOM.render` / `react-dom/test-utils` 等已移除的 API 不要再用（入口由模板 `client/src/index.tsx` 负责）。
+- 依赖库不支持 React 19 时，换支持的版本或替代库（见 SKILL.md Step 2）。
+
+## 5. 移除 Supabase 与服务端逻辑
+
+妙搭不支持 Supabase。supabase 集成文件已放在 `source_package/`，需要从业务代码中移除引用。
+
+| 搜索关键词 | 处理 |
+| --- | --- |
+| `@supabase`、`@/integrations/supabase`、`@/lib/supabase`、`@/db/` | 删除导入 |
+| `supabase.auth.` | 换成简化的演示登录态（本地 state） |
+| `supabase.from(` | 换成本地 state + 静态示例数据，增删改操作改本地 state |
+| `supabase.channel(`、`supabase.storage.` | 删除，或改用静态资源 |
+| `useAuth` | 确认与简化后的 AuthContext 兼容 |
+
+```tsx
+// ✅ 本地 state + 静态数据示例
+const [items, setItems] = useState([
+  { id: 1, name: '示例数据1', status: 'active' },
+  { id: 2, name: '示例数据2', status: 'pending' },
+]);
+const handleAdd = (item: Item) => setItems((prev) => [...prev, { ...item, id: Date.now() }]);
+const handleDelete = (id: number) => setItems((prev) => prev.filter((i) => i.id !== id));
+```
+
+Replit 的 `server/`、Gemini 的后端调用同理：不迁移服务端，前端调用改为静态数据或本地逻辑。用户需要真实数据能力时，在收尾说明里建议后续用妙搭的数据库与接口能力实现，不在本次迁移中自行搭建。
+
+## 6. 删除平台特定代码
+
+- Lovable：删除 `lovable-tagger` 的 import 与使用（`componentTagger` / `ComponentTagger`）。
+- Replit：删除 `@replit/*` 插件、`replit` 运行时 banner 等引用。
+- 其他平台的开发期插件同理，以 manifest 中 `build_chain` 的依赖为线索。
+
+## 7. 环境变量
+
+```tsx
+import.meta.env.VITE_API_URL  →  process.env.VITE_API_URL
+```
+
+源项目依赖的密钥类变量（如 Supabase key、第三方 API key）不要写进代码，删除相关逻辑或在收尾时提示用户在妙搭环境变量中配置。
+
+## 8. 创建页面入口
+
+参考源入口（Lovable / zip：`source_package/src/App.tsx`；Replit：`source_package/client/src/App.tsx`；Gemini：`source_package/App.tsx`；这些是 TS 示例路径，源入口也可能为 `.jsx` / `.js`，或已放在 `client/src/`，按 manifest 和实际文件定位）：
+
+1. 读懂源 `App.tsx` 的页面结构与路由。
+2. 首页创建为 `client/src/pages/Home/Home.tsx`，复制 JSX 结构，去掉外层 Router / Provider（模板入口已提供）。
+3. 源项目有多个页面的，已在 `client/src/pages/` 下的直接复用；只在 `App.tsx` 内联的拆成独立页面。
+
+```tsx
+// client/src/pages/Home/Home.tsx
+import { HeroSection } from '@/components/HeroSection';
+import { Features } from '@/components/Features';
+
+const Home = () => (
+  <>
+    <HeroSection />
+    <Features />
+  </>
+);
+
+export default Home;
+```
+
+源 `App.tsx` / `main.tsx` 里挂载的每个 Provider 和全局组件都要逐个对照处理，漏掉一个就会让相关功能静默失效：
+
+- 模板已有的不重复添加：`BrowserRouter`、`AppContainer`、`ErrorBoundary`，以及 **sonner** 的 `Toaster`（`@/components/ui/sonner`）。
+- shadcn 旧版 toast（`@/components/ui/toaster` + `useToast` / `@/hooks/use-toast`）是另一套，模板没有挂载。源项目用到它时，必须在 `MainApp` 里挂上 `@/components/ui/toaster` 的 `Toaster`（和 sonner 的同名，import 时起别名）。否则所有 `toast(...)` 都不显示。
+- 其余（`QueryClientProvider`、`TooltipProvider`、主题 / Auth Context 等）加到 `client/src/index.tsx` 的 `MainApp` 中，包在模板已有 Provider 的内层。
+
+`Layout.tsx` 只是 Outlet 容器，不放 Provider。
+
+## 9. 更新路由
+
+修改 `client/src/app.tsx`，用迁移后的首页替换模板的 `Welcome`，并补齐源项目的其他路由：
+
+```tsx
+import Home from './pages/Home/Home';
+
+const RoutesComponent = () => (
+  <Routes>
+    <Route element={<Layout />}>
+      <Route index element={<Home />} />
+      {/* 源项目的其他路由 */}
+    </Route>
+    <Route path="*" element={<NotFound />} />
+  </Routes>
+);
+```
+
+- 路由定义写在 `RoutesComponent` 中，`Layout.tsx` 只是 Outlet 容器。
+- 模板入口已用 `BrowserRouter basename={CLIENT_BASE_PATH}`，源项目里的 `BrowserRouter` / `HashRouter` 不要再包一层。
+
+## 10. 常见编译错误
+
+| 错误 | 原因 | 修复 |
+| --- | --- | --- |
+| `Cannot find module 'lovable-tagger'` | 平台特定依赖 | 删除相关代码 |
+| `Cannot find module '../lib/utils'` | 路径变化 | 改为 `@/lib/utils` |
+| `Cannot find module '@/...'` | 文件不在 `client/src/` | 检查是否留在 `source_package/`，按需迁移 |
+| `Cannot find module '@supabase/...'` | 未移除 Supabase | 按第 5 节移除 |
+| `bg-primary` 等颜色无效 | HSL 未包裹 | 变量值包裹 `hsl()` |
+| SVG 描边 / 图表颜色消失 | `hsl(var(--x))` 双重包裹 | 改为 `var(--x)`，见 1.1 |
+| 元素一直透明、动画不播放 | `tailwind.config` 的 animation 未迁移 | 见 1.3 |
+| 整页无样式、网格塌成单列 | 业务 JS / JSX 未完成转换，类名不在模板扫描范围中 | 按 4.3 转为 TS / TSX 并检查引用和样式 |
+| 半透明背景变成实色 | `bg-opacity-*` 已移除 | 见 4.2 |
+| `toast(...)` 无提示 | shadcn toaster 未挂载 | 见第 8 节 |
+| `Property 'VITE_*' does not exist` | 环境变量写法 | 改为 `process.env.*` |
+| `Unexpected token '<'` / JSON 404 | public 资源路径错位 | 改 import 或拼 `BASE_PATH` |
+| `Parameter implicitly has an 'any' type` | 缺类型 | 补 TypeScript 类型 |
+| 依赖的类型缺失 | 缺 `@types/*` | 安装对应 `@types/*`，不要关 strict |
+
+## 验收
+
+1. 按 SKILL.md Step 4 实际检查业务 JS / JSX 残留，完成 TS / TSX 转换，`npm run type:check` 通过。
+2. 首页路由展示迁移后的内容，不再是模板 Welcome。
+3. 主要交互可响应（数据可为演示数据）。
+4. 样式与源项目基本一致，Tailwind 颜色生效；源项目的外链图片、背景图未被替换。
+5. 源项目 `tailwind.config` 的自定义主题（含 `container`）、字体（字体族与字重）、Provider 均已迁移；`grep -rnE 'hsl\(var\(--|-opacity-[0-9]|-\[--' client/src` 无残留。

package/miaoda/import-migration/references/replit.md

@@ -0,0 +1,74 @@
+# Replit 平台差异
+
+与 `react-migration.md` 一起使用：通用步骤按该文件执行，本文件只列 Replit 特有的部分。
+
+## 环境差异
+
+| 项 | Replit | 妙搭模板 |
+| --- | --- | --- |
+| React | 18 | 19 |
+| Tailwind | 4 | 4 |
+| 路由库 | wouter | react-router-dom |
+| 后端 | `server/`（Express 等） | 不迁移 |
+
+## 文件位置
+
+| Replit 源路径 | 当前位置 | 处理 |
+| --- | --- | --- |
+| `client/src/components/**`、`pages/**`、`hooks/**`、`lib/**` | 原位 `client/src/**` | 直接可用（`hooks/use-mobile.tsx` 已排除，用模板的 `use-mobile.ts`） |
+| `client/src/App.tsx` | `source_package/client/src/App.tsx` | 参考迁移路由与 Provider |
+| `client/src/main.tsx` | `source_package/client/src/main.tsx` | 不需要 |
+| `client/src/index.css` | `source_package/client/src/index.css` | 提取主题 |
+| `shared/**` | 原位 `shared/**` | 直接可用 |
+| `attached_assets/**` | `client/public/assets/**` | 引用路径需转换（见下） |
+| `server/**` 及其他 | `source_package/` | 不迁移 |
+
+## 特有步骤
+
+1. **主题**：读取 `source_package/client/src/index.css`。Replit 已是 Tailwind 4，但常把颜色直接写在 `@theme inline` 里；改为先在 `client/src/tailwind-theme.css` 的 `:root` 定义 `--primary: hsl(...)` 等变量，再在 `@theme inline` 中 `--color-primary: var(--primary)` 映射。同名变量直接覆盖；自定义工具类（如 `.bg-grain`）放进 `@layer utilities`。
+
+2. **wouter → react-router-dom**：
+
+   ```tsx
+   // 源：wouter
+   import { Switch, Route } from 'wouter';
+   <Switch>
+     <Route path="/" component={Home} />
+     <Route component={NotFound} />
+   </Switch>;
+
+   // 目标：在 client/src/app.tsx 的 RoutesComponent 中
+   <Route element={<Layout />}>
+     <Route index element={<Home />} />
+   </Route>
+   <Route path="*" element={<NotFound />} />
+   ```
+
+   `Switch` → `Routes`，`component={X}` → `element={<X />}`，兜底路由加 `path="*"`；组件内 `useLocation` / `useRoute` / `Link` 也换成 react-router-dom 的对应 API，删除所有 wouter import。
+
+3. **Provider**：`source_package/client/src/App.tsx` 里的 Provider（`QueryClientProvider`、`TooltipProvider` 等）加到 `client/src/index.tsx` 的 `MainApp` 中，包在模板已有的 `BrowserRouter` / `AppContainer` 内层；模板只挂了 sonner 的 `Toaster`；源项目用 `@/components/ui/toaster`（shadcn toast）时要另外挂上，见 `react-migration.md` 第 8 节。`Layout.tsx` 只是 Outlet 容器，不放 Provider。
+
+4. **`@assets` 别名**：模板没有该别名。图片已在 `client/public/assets/`，把 import 改为 public 路径并拼接 `CLIENT_BASE_PATH`：
+
+   ```tsx
+   // 源
+   import heroBg from '@assets/generated_images/hero.png';
+   <img src={heroBg} />
+
+   // 目标（删除 import）
+   <img src={`${process.env.CLIENT_BASE_PATH || ''}/assets/generated_images/hero.png`} />
+   ```
+
+   `@/`、`@shared/` 两个别名模板已配置，保持不变。
+
+5. **字体**：Replit 常在 `index.html` 引入 Google Fonts，把对应 `<link>` 原样复制到 `client/index.html` 的 `<head>`，不要删减 URL 里的字重。再按源项目设置 `font-family`，见 `react-migration.md` 1.4。
+
+6. **依赖**：`framer-motion`、`lucide-react`、`@tanstack/react-query`、`react-router-dom`、`recharts`、`sonner`、`zod` 等模板已内置（manifest 中为 `present`），沿用模板版本；`wouter` 不要安装。
+
+## 常见编译错误
+
+| 错误 | 修复 |
+| --- | --- |
+| `Cannot find module 'wouter'` | 换成 react-router-dom |
+| `Cannot find module '@assets/...'` | 改为 public 路径并拼 `CLIENT_BASE_PATH` |
+| `Cannot find name 'Switch'` / `Property 'component' does not exist` | wouter 语法未转换，见第 2 步 |

package/miaoda/lark-apps-db/SKILL.md

@@ -26,6 +26,7 @@ gate-tools:
 - **app_id 走环境变量**：所有 `+db-*` 都必填 `--app-id "$app_id"`；应用已存在、id 在环境变量 `app_id` 里，不要自行获取、解析或选择。
 - **鉴权自动**：apps 域请求由运行环境自动打到 innerAPI 并注入鉴权头。**不要** `auth login` / `config init` / `--as`。
 - **不要裸连数据库**：不要从环境变量里取连接串直连数据库；本地调试同样走 `+db-execute`。
+- **首次用库前先确认已开通**：首次建表、写用库的后端代码、灌数据之前，先 `lark-cli apps +features --app-id "$app_id"`；`database` 为 `enabled=false` 时，先按 [lark-apps-ops](../lark-apps-ops/SKILL.md) 路由表「查询或开通应用数据库」一行开通，再继续。新应用会预建空库，`+db-table-list`、`+db-execute` 能成功**不代表已开通**——开关没开时运行时不注入数据库，预览和发布都会起不来。不要改平台环境文件、不要在代码里自行注册数据库模块或读连接串来绕过开关。
 - **失败处理**：命令失败时把 `error.hint` 转述给用户，别原样甩 envelope JSON。
 
 ### 高风险写操作审批（exit 10）
@@ -43,6 +44,7 @@ gate-tools:
 
 | 场景 | 首选命令 | 关键规则 |
 |---|---|---|
+| 首次用库前确认已开通 | `lark-cli apps +features --app-id "$app_id"` | `database` 为 `enabled=false` 时先 `+feature-enable --feature database --app-id "$app_id"`（见 [lark-apps-ops](../lark-apps-ops/SKILL.md)），再建表、写代码 |
 | 列表 / 查表结构 | `lark-cli apps +db-table-list --app-id "$app_id"` / `+db-table-get --app-id "$app_id" --table <table>` | 禁止用 `information_schema` / `pg_indexes` 模拟常规结构查询 |
 | 执行 DDL / DML / SELECT | `+db-execute --app-id "$app_id" --sql "<query>" --yes` | 不自动包事务，原子性自己写 `BEGIN…COMMIT` |
 | 批量导入 CSV / JSON | `+db-data-import --app-id "$app_id" --file ./<file> --table <table> --yes` | 目标表已存在；表头 / key 与列名完全一致；≤1 MB / ≤5000 行；无 upsert |

package/miaoda/lark-apps-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-apps-ops
-description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、导出应用源码为 zip（+export）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、应用 MCP 连接与凭证（+mcp-get/+mcp-key-create）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 导出源码, 源码快照, 下载源码, zip, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, MCP, MCP URL, MCP 凭证, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +export, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +mcp-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、导出应用源码为 zip（+export）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、应用 MCP 连接与凭证（+mcp-get/+mcp-key-create）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）、查询与开通应用数据库能力（+features/+feature-enable，首次建表或写用库代码前必查）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 导出源码, 源码快照, 下载源码, zip, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, MCP, MCP URL, MCP 凭证, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, 开通数据库, 开启数据库, 数据库未开通, 要存数据, DRIZZLE_DATABASE, +features, +feature-enable, +release-, +export, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +mcp-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -39,7 +39,8 @@ control-by-feature-ab: true
 | 管理应用环境变量（查看/设置/删除） | `+env-list`、`+env-set`、`+env-delete` | [env](references/lark-apps-env.md) |
 | 导出应用源码为 zip（要一份源码快照：读代码/审计/归档/静态分析；或取**别人分享给你的**创意应用源码，你对其仓库无权限）。仅取快照、不继续开发 | `+export`（下载 zip，只读；`--app-id` 与 `--meta-token` 恰传其一） | [export](references/lark-apps-export.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`、`+log-get`、`+trace-list`、`+trace-get`、`+metric-list`、`+analytics-list` | [observability](references/lark-apps-observability.md) |
-| 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量 | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
+| **查询或开通应用数据库**：要保存业务数据、**首次建表 / 写用库的后端代码 / 灌数据之前**必须先查；后端报 `DRIZZLE_DATABASE` 注入失败时也先查这里。库能查能建表不代表已开通，不要改环境文件或自行接连接串绕过开关 | `+features --app-id "$app_id"`；`database` 为 `enabled=false` 时 `+feature-enable --feature database --app-id "$app_id"` | [features](references/lark-apps-features.md) |
+| 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量（首次用库前先按上一行确认已开通） | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
 | 应用文件存储：上传/下载/列出/删除文件、临时分享链接、存储用量 | `+file-*` 命令族 | **→ [lark-apps-file](../lark-apps-file/SKILL.md)** |
 | 角色与权限：角色/角色成员管理、查用户命中角色、权限点位表维护 | `+role-*` 命令族 | **→ [lark-apps-authz](../lark-apps-authz/SKILL.md)** |
 | 设置或查看运行时可见范围（谁能打开应用） | `+access-scope-set`、`+access-scope-get` | [access-scope-set](references/lark-apps-access-scope-set.md)、[access-scope-get](references/lark-apps-access-scope-get.md) |

package/miaoda/lark-apps-ops/references/lark-apps-features.md

@@ -0,0 +1,50 @@
+# apps +features / +feature-enable
+
+查询和启用应用业务能力。本期只有 `database`（应用的数据库，PostgreSQL）。运行时命令事实以 `lark-cli apps +features --help`、`lark-cli apps +feature-enable --help` 为准。
+
+## 心智模型
+
+- `full_stack` 是工程与发布契约，**不等于已有数据库**。应用可以先没有数据库，需要保存业务数据时再显式启用。
+- `+features` 只读（`spark:app:read`）：每个能力只返回 `name` 和 `enabled`。不申请资源、不返回连接串。
+- `+feature-enable --feature database` 是服务端写操作（声明 `spark:app:read` + `spark:app:write`）：只需 `--app-id` 和 `--feature database`（本期只支持 `database`），CLI 自动生成 `idempotent_key` 并只提交它。成功只表示**服务端能力已开启**；在妙搭沙箱里由平台自动生效，之后要再做一次真实读写验证。
+- 它不改业务代码、不拆已有数据库、不推代码、不发布。
+
+## 何时用
+
+- 应用要开始保存业务数据：先 `+features`，`database` 为 `enabled=false` 时执行 `+feature-enable --feature database`。
+- `+features` 没列出 `database`、命令报错，或 `+feature-enable` 被服务端拒绝：该应用不走本入口，转述错误信息；需要数据库时引导用户在妙搭 web 端处理（不要替用户拼站点地址）。
+
+## 示例
+
+```bash
+lark-cli apps +features --app-id "$app_id"
+
+lark-cli apps +feature-enable --feature database --app-id "$app_id" --dry-run
+lark-cli apps +feature-enable --feature database --app-id "$app_id"
+
+# 上一次失败/超时后，用错误提示里的原 idempotent_key（示例值需替换）续同一次请求或查询
+lark-cli apps +feature-enable --feature database --app-id "$app_id" --idempotent-key b3d93913-e777-4968-a00c-afd0a1c7ce44
+lark-cli apps +features --app-id "$app_id" --operation-ref b3d93913-e777-4968-a00c-afd0a1c7ce44
+```
+
+## 结果判定
+
+| 结果 | 含义 | 下一步 |
+|---|---|---|
+| `ok:true`，`feature.enabled=true` | 服务端已开启数据库（含早已开启、无 `operation` 的情况） | 妙搭沙箱里平台自动生效，稍候即可；之后验证一次真实读写 |
+| exit 1，`subtype=failed_precondition`，提示应用不是新契约应用 | 该应用不能通过 CLI 开数据库 | 转述错误，引导用户在妙搭 web 端处理（不要替用户拼站点地址）；重试本命令没有用 |
+| exit 1，`subtype=failed_precondition`，提示 `idempotent_key` 已不可用 | 该 key 已作废：被后续操作取代、不属于当前调用者或不存在 | 先 `+features` 看当前状态，已开启就不用再开；仍需开启就不带 `--idempotent-key` 重新执行（CLI 生成新 key）；不要用同一个 key 重试 |
+| exit 1，`subtype=conflict` | 能力被并发修改、key 属于其他请求，或另一次开启仍在进行 | 转述 `error.message` / `hint`；重新 `+features` 看当前状态再决定，CLI 不会自动覆盖 |
+| exit 1，`subtype=rate_limit` | 被限流，本次请求未执行。首次请求被限流，或服务端已确认这个 key 没有操作时，没有可续跑的东西；网络重放或带原 key 续跑时被限流，这个 key 可能已有操作 | 稍等约一分钟后按 `hint` 处理：`hint` 要求不带 `--idempotent-key` 重新执行时就换新 key；`hint` 给出原 key 时，先用 `--operation-ref` 查询，再用原 `--idempotent-key` 续跑，不要换新 key |
+| exit 1，`subtype=feature_not_available`，提示服务端没有运行应用能力接口 | 当前服务端还不支持应用能力：网关内部错误 2200，或网关还没有这条路由、直接回 HTTP 404（`404 page not found`），只读复查结果相同；只有开通请求被回 404 时也按这一行处理 | 不要重试；转述错误，引导用户在妙搭 web 端处理，或等服务端升级 |
+| exit 3，身份或授权失效（如 `token_expired`；妙搭沙箱里用户凭证过期返回 221801，凭证无效时代理直接回 HTTP 401） | 当前用户凭证不可用，任何 key 都不会成功 | 转述 `hint`，本沙箱不需要也不要自行登录或初始化；不要用同一个 `--idempotent-key` 反复重试 |
+| exit 1 / 4 / 5，结果失败、未知或无法核实 | 请求可能已执行，也可能没有 | 按 `hint` 先用 `--operation-ref <idempotent_key>` 查询；要续同一次请求用原 `--idempotent-key`；结果未知时不要换新 key 重新申请 |
+
+带 `--idempotent-key` 时，CLI 先按同一 key 查询服务端保留的操作：已成功、结果未知或冲突直接报告，进行中则等待，只有可重试的失败才用同一 key 重发；只有服务端明确答复不保留该 key（`operation_unavailable`）时，才报错并提示先看 `+features`、确有需要再发起新操作；查询本身失败（权限、服务端错误、网络）时保留实际错误，结果按未知处理，只能用同一 key 重试或查询，不要换新 key。两种情况都不会自动重发或换 key。
+
+`running` 只在服务端确实异步接手时出现，CLI 最多等待 60 秒；`conflicted` 等终态立即返回，不会继续等待。超时或中断不会取消或回滚服务端操作。错误的 `hint` 会给出原 `idempotent_key` 与查询命令，不含连接信息。
+
+## 参考
+
+- [lark-apps-local-dev](lark-apps-local-dev.md) — 本地开发与部署流程
+- [lark-apps-db](../../lark-apps-db/SKILL.md) — 数据库命令与多环境

package/miaoda/lark-apps-ops/references/lark-apps-local-dev.md

@@ -1,6 +1,6 @@
 # lark-apps 本地开发
 
-适用：当前妙搭应用（full_stack 全栈或 frontend 纯前端）的源码已在工作区，用本地 code agent/IDE 开发、调试数据库（仅全栈应用有数据库），再部署上线。
+适用：当前妙搭应用（full_stack 全栈或 frontend 纯前端）的源码已在工作区，用本地 code agent/IDE 开发、调试数据库（只适用于全栈应用，且 `+features` 里 `database` 为 `enabled=true`；frontend 应用没有数据库），再部署上线。
 
 ## 改完代码后部署上线
 
@@ -20,6 +20,7 @@
 - pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
 - 环境变量由脚手架在本地启动时处理。
 - frontend（纯前端，vite-react）应用的开发与部署流程和全栈一致，只是没有数据库、跳过一切 `+db-*` 步骤。后续要加数据库/后端能力时，本地链路不提供类型升级：引导用户到妙搭 web 的云端会话里用自然语言提出（如「给这个应用加登录和数据存储」）即可触发升级，无需特殊指令，也不要替用户拼站点地址。
+- 全栈应用的数据库默认可能未开启。**首次建表、写用库代码之前**：`+features --app-id "$app_id"` 看 `database` → `enabled=false` 时 `+feature-enable --feature database --app-id "$app_id"`（见 [features](lark-apps-features.md)）→ 平台自动生效，不需要 `+env-pull`、不需要手动重启 → 建表并做一次真实读写验证。库能查能建表不代表已开通（以 `+features` 为准），不要改环境文件或自行接连接串绕过开关。
 - DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`（见 lark-apps-db skill）；不要裸连数据库或自行拼连接串。
 - DB 分 `dev` / `online`；日常调试优先 `--environment dev`。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
 - 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --environment dev`。这是不可逆 high-risk 操作。

package/miaoda/testing-guide/SKILL.md

@@ -44,11 +44,14 @@ Task({
 
 {% endif %}本轮跑哪些用例只认结构化字段，写在 `prompt` 里的自然语言范围不生效：刚写好或刚改过的计划首次验收带 `agent_options.retest_all: true`，跑全部用例；修复后复验带 `agent_options.retest_case_ids: [1, 2]`，只列失败或受这次修复影响的用例（编号取计划文件里的 `id`，必须是正整数，不是 `"case-1"` 这类字符串）。
 
+复验前必须重新读取磁盘上的计划文件：如果失败暴露的是用例本身有误（前置条件缺失、持久化数据重名、步骤或断言与当前产品不符），先编辑原计划并读回确认，再派发；**禁止只在 `prompt` 里写“已存在就不要新增”等补丁来覆盖错误计划**。计划改过后，本轮选择的每条 Case 必须能从当前应用状态独立完成；有依赖就把准备动作写进该 Case，或把依赖 Case 的完整闭包一并放进 `retest_case_ids`。
+
 ## 验收要求
 
 - 检查视觉的用例写清可观察结果，例如「首页标题完整可见、卡片两列排列、主图不是裂图」，不要只写「看起来正常」。
 - 功能验收必须走到终态：提交后记录出现、跳转后内容正确、删除后记录消失或 AI 输出出现；不要停在弹窗、按钮或表单字段出现。
 - 写操作和资源加载要核对网络结果；非 2xx、空结果、错误兜底或白屏都应报失败。
+- 涉及 localStorage、数据库或其他跨轮持久化状态的写操作必须可重复执行：使用本轮唯一数据，或在 Case 内先查找并复用 / 重置 / 清理同名数据；不能固定创建同名记录后把“已存在时跳过”只写在 `prompt` 里。
 - 派发前备齐每条用例依赖的数据、应用账号和角色，一次派发就测完，不靠跳过后再派：数据先经应用界面新建或调用应用接口准备，且对该用例的测试身份可见；应用自建账号体系的，把测试账号写进用例；{% if permissionIdentityEnabled %}需要特定角色或登录状态的，按上文给用例写 identity{% else %}需要特定角色的，先确认当前登录身份具备该角色{% endif %}。准备不了（或会违反数据相关规则）的用例不派（不写进计划，或不列入本轮 `retest_case_ids`）。
 - {% if permissionIdentityEnabled %}不测登录流程本身（登录页、注册、OAuth、CAPTCHA），也不测会造成真实外部副作用的行为；需要以某角色或未登录状态验证的用例用 identity 声明。{% else %}不测试登录、认证、CAPTCHA，或会造成真实外部副作用的行为。{% endif %}
 {% else %}
@@ -108,6 +111,7 @@ Task({
 1. **先看已有的**：`glob .spark/e2e-test/*.json` 和历史目录 `.spark/e2e-test/standard/*.json` → **读**可能覆盖本需求的那份（没读过不要传）
 2. **改还是新建**：已有计划沿用原路径（包括 standard/ 下的，不复制、不搬迁），同需求用例有变化 → 编辑那份；没有对应计划的新功能 / 页面 → 新建 `.spark/e2e-test/<语义名>.json`
 3. **派发**：跑哪些用例只认结构化字段，写在 `prompt` 里的自然语言范围不生效：刚写好或刚改过的卷首次验收带 `agent_options.retest_all: true`，跑全部用例；修复后复验带 `agent_options.retest_case_ids: [1, 2]`，只列失败或受这次修复影响的用例（编号取计划文件里的 `id`，必须是正整数，不是 `"case-1"` 这类字符串）
+4. **复验前修计划**：重新读取磁盘上的计划；若失败来自前置条件缺失、持久化数据重名、步骤或断言错误，先编辑原计划并读回确认，再派发。禁止只改 `prompt` 来覆盖计划语义
 
 格式（一条用例一行，优先级小写，每卷 ≤10 条）：
 
@@ -122,6 +126,8 @@ Task({
 
 {% endif %}- **用例正文只写在计划文件里**：本模式下 `prompt` 不写 `## 测试用例`（下面示例里的用例正文改为写进卷），只留应用结构与本次范围——两处都写会让计划外用例一条不跑、报告却全绿
 - **复测只选编号、不删用例**：「只传 failed + 未完成的 Case」指用 `retest_case_ids` 列出这些编号，不是从卷里删掉已通过的用例
+- **依赖必须闭包**：本轮选择的每条 Case 要能从当前应用状态独立执行；依赖其他 Case 造数时，把准备动作并入本 Case，或把全部依赖 Case 编号一并加入 `retest_case_ids`，不能只选下游 Case 后靠历史轮次遗留状态
+- **持久化写操作要幂等**：localStorage / 数据库中的记录会跨轮保留。创建类 Case 使用本轮唯一数据，或在 Case 内先查找并复用 / 重置 / 清理同名数据；禁止固定创建同名记录，再在 `prompt` 里补一句“已存在就不要新增”
 
 ### 调用结构
 
@@ -137,30 +143,28 @@ task({
     - <页面名> (<路由>) — <布局/职责>
     - ...
 
-    ## 测试用例
-    ### Case 1: <页面/模块> - <场景>
-    1. <动作步>
-    2. 断言：<可观察现象>
-    ...
+    ## 本次范围
+    - 执行计划文件中 agent_options 选中的 Case 编号
+    - 不新增、改写或跳过计划内步骤
   `,
   // ...其他参数：按 Task 工具的实际签名如实补全，别只填上面示例里的字段
 })
 ```
 
-### prompt 三段式
+### prompt 两段式
 
 | 段落 | 内容 | 作用 |
 |------|------|------|
 | 概述 | 一句话说明被测应用是什么 | 让 agent 建立全局认知 |
 | `## 应用结构` | 每个页面的路由 + 布局/职责 | 告诉 agent 去哪、看什么 |
-| `## 测试用例` | 多个 Case，每个含编号步骤 | agent 逐条执行并断言 |
 
 ### Case 编写规则
 
 - **标题**：`### Case N: <模块> - <场景>`，一个 Case 一个独立场景
 - **动作步 / 断言步交替**：动作步动词开头（访问 / 点击 / 输入 / 切换）；断言步以「断言：」开头
 - **可定位 + 二元判定**：动作指到具体对象（可见文本，如「发布新帖」按钮）；断言给非黑即白判据（出现 / 消失 / 等于 / ≥N / 含某文案），不写"正常""是否合理 / 美观"（见下方对照）
-- **独立可重入**：删除 / 提交等副作用操作走「取消」或验证后还原，不污染后续 Case
+- **独立可重入**：每条 Case 都从明确前置状态开始；有依赖就内置准备动作或在复测选择中包含依赖闭包。删除 / 提交等副作用操作验证后还原，不污染后续 Case
+- **持久化写操作幂等**：localStorage / 数据库记录会跨轮保留；创建类 Case 使用本轮唯一数据，或先查找并复用 / 重置 / 清理同名数据，重复执行不得因固定名称冲突而失败
 - **派发前备齐前置条件**：用例依赖的数据、应用账号和角色在派发前就绪，一次派发就测完，不靠跳过后再派——数据先经应用界面新建或调用应用接口准备，且对该用例的测试身份可见；应用自建账号体系的，把测试账号写进 Case；{% if permissionIdentityEnabled %}需要特定角色或登录状态的，按上文给用例写 identity{% else %}需要特定角色的，先确认当前登录身份具备该角色{% endif %}。准备不了（或会违反数据相关规则）就不写这条 Case
 
 ### Case 复杂度约束（必跑到终态）
@@ -245,7 +249,7 @@ E2E agent 只在离散时刻抓快照 / 截图，**看不到瞬时过程、不
 
 E2E 派遣是**昂贵操作**（每次消耗大量 token + 时间）。E2E agent 只负责暴露问题，**不负责定位根因**。
 
-**每次任务执行**的 E2E 总派遣上限 **3 轮**（同一应用内多次任务分别计算）：
+**每个用户任务**的 E2E 总派遣上限是绝对 **3 轮**。每次 `Task(subagent_type="E2E")` 调用都计 1 轮；修改计划、修改代码、超时、重启 agent，以及切换 `retest_all` / `retest_case_ids` 都不会重置计数。禁止把同一用户任务拆成多个描述或子任务规避上限：
 
 | 轮次 | testRequirements 内容 | 说明 |
 |------|----------------------|------|
@@ -255,6 +259,8 @@ E2E 派遣是**昂贵操作**（每次消耗大量 token + 时间）。E2E agent
 | 第 4 轮起 | 禁止再派遣 E2E | 转为根因分析模式 |
 
 **定向复测规则**：
+- 派发前重新读取计划；若失败原因是计划缺陷，必须先修改原计划并读回确认，再选择 Case。`prompt` 不能覆盖计划中的步骤、断言或数据语义
+- 每个被选 Case 必须独立可执行，或连同它依赖的全部 Case 一起选择；不要假设上轮一定留下了可用状态
 - 已通过的 Case 最多复测 1 次：担心修复引入回归时可纳入复测，同一 Case 累计通过 2 次后不再纳入
 - 如果上一轮因超时中断，E2E 会返回"已测通过/已测失败/未测"三组——已测通过的结果可信不需重测，只测"失败"和"未测"的
 

package/miaoda-modern/lark-apps-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-apps-ops
-description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、导出应用源码为 zip（+export）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、应用 MCP 连接与凭证（+mcp-get/+mcp-key-create）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 导出源码, 源码快照, 下载源码, zip, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, MCP, MCP URL, MCP 凭证, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +export, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +mcp-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、导出应用源码为 zip（+export）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、应用 MCP 连接与凭证（+mcp-get/+mcp-key-create）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）、查询与开通应用数据库能力（+features/+feature-enable，首次建表或写用库代码前必查）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 导出源码, 源码快照, 下载源码, zip, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, MCP, MCP URL, MCP 凭证, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, 开通数据库, 开启数据库, 数据库未开通, 要存数据, DRIZZLE_DATABASE, +features, +feature-enable, +release-, +export, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +mcp-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -39,7 +39,8 @@ control-by-feature-ab: true
 | 管理应用环境变量（查看/设置/删除） | `+env-list`、`+env-set`、`+env-delete` | [env](references/lark-apps-env.md) |
 | 导出应用源码为 zip（要一份源码快照：读代码/审计/归档/静态分析；或取**别人分享给你的**创意应用源码，你对其仓库无权限）。仅取快照、不继续开发 | `+export`（下载 zip，只读；`--app-id` 与 `--meta-token` 恰传其一） | [export](references/lark-apps-export.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`、`+log-get`、`+trace-list`、`+trace-get`、`+metric-list`、`+analytics-list` | [observability](references/lark-apps-observability.md) |
-| 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量 | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
+| **查询或开通应用数据库**：要保存业务数据、**首次建表 / 写用库的后端代码 / 灌数据之前**必须先查；后端报 `DRIZZLE_DATABASE` 注入失败时也先查这里。库能查能建表不代表已开通，不要改环境文件或自行接连接串绕过开关 | `+features --app-id "$app_id"`；`database` 为 `enabled=false` 时 `+feature-enable --feature database --app-id "$app_id"` | [features](references/lark-apps-features.md) |
+| 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量（首次用库前先按上一行确认已开通） | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
 | 应用文件存储：上传/下载/列出/删除文件、临时分享链接、存储用量 | `+file-*` 命令族 | **→ [lark-apps-file](../lark-apps-file/SKILL.md)** |
 | 角色与权限：角色/角色成员管理、查用户命中角色、权限点位表维护 | `+role-*` 命令族 | **→ [lark-apps-authz](../lark-apps-authz/SKILL.md)** |
 | 设置或查看运行时可见范围（谁能打开应用） | `+access-scope-set`、`+access-scope-get` | [access-scope-set](references/lark-apps-access-scope-set.md)、[access-scope-get](references/lark-apps-access-scope-get.md) |

package/miaoda-modern/lark-apps-ops/references/lark-apps-features.md

@@ -0,0 +1,50 @@
+# apps +features / +feature-enable
+
+查询和启用应用业务能力。本期只有 `database`（应用的数据库，PostgreSQL）。运行时命令事实以 `lark-cli apps +features --help`、`lark-cli apps +feature-enable --help` 为准。
+
+## 心智模型
+
+- `full_stack` 是工程与发布契约，**不等于已有数据库**。应用可以先没有数据库，需要保存业务数据时再显式启用。
+- `+features` 只读（`spark:app:read`）：每个能力只返回 `name` 和 `enabled`。不申请资源、不返回连接串。
+- `+feature-enable --feature database` 是服务端写操作（声明 `spark:app:read` + `spark:app:write`）：只需 `--app-id` 和 `--feature database`（本期只支持 `database`），CLI 自动生成 `idempotent_key` 并只提交它。成功只表示**服务端能力已开启**；在妙搭沙箱里由平台自动生效，之后要再做一次真实读写验证。
+- 它不改业务代码、不拆已有数据库、不推代码、不发布。
+
+## 何时用
+
+- 应用要开始保存业务数据：先 `+features`，`database` 为 `enabled=false` 时执行 `+feature-enable --feature database`。
+- `+features` 没列出 `database`、命令报错，或 `+feature-enable` 被服务端拒绝：该应用不走本入口，转述错误信息；需要数据库时引导用户在妙搭 web 端处理（不要替用户拼站点地址）。
+
+## 示例
+
+```bash
+lark-cli apps +features --app-id "$app_id"
+
+lark-cli apps +feature-enable --feature database --app-id "$app_id" --dry-run
+lark-cli apps +feature-enable --feature database --app-id "$app_id"
+
+# 上一次失败/超时后，用错误提示里的原 idempotent_key（示例值需替换）续同一次请求或查询
+lark-cli apps +feature-enable --feature database --app-id "$app_id" --idempotent-key b3d93913-e777-4968-a00c-afd0a1c7ce44
+lark-cli apps +features --app-id "$app_id" --operation-ref b3d93913-e777-4968-a00c-afd0a1c7ce44
+```
+
+## 结果判定
+
+| 结果 | 含义 | 下一步 |
+|---|---|---|
+| `ok:true`，`feature.enabled=true` | 服务端已开启数据库（含早已开启、无 `operation` 的情况） | 妙搭沙箱里平台自动生效，稍候即可；之后验证一次真实读写 |
+| exit 1，`subtype=failed_precondition`，提示应用不是新契约应用 | 该应用不能通过 CLI 开数据库 | 转述错误，引导用户在妙搭 web 端处理（不要替用户拼站点地址）；重试本命令没有用 |
+| exit 1，`subtype=failed_precondition`，提示 `idempotent_key` 已不可用 | 该 key 已作废：被后续操作取代、不属于当前调用者或不存在 | 先 `+features` 看当前状态，已开启就不用再开；仍需开启就不带 `--idempotent-key` 重新执行（CLI 生成新 key）；不要用同一个 key 重试 |
+| exit 1，`subtype=conflict` | 能力被并发修改、key 属于其他请求，或另一次开启仍在进行 | 转述 `error.message` / `hint`；重新 `+features` 看当前状态再决定，CLI 不会自动覆盖 |
+| exit 1，`subtype=rate_limit` | 被限流，本次请求未执行。首次请求被限流，或服务端已确认这个 key 没有操作时，没有可续跑的东西；网络重放或带原 key 续跑时被限流，这个 key 可能已有操作 | 稍等约一分钟后按 `hint` 处理：`hint` 要求不带 `--idempotent-key` 重新执行时就换新 key；`hint` 给出原 key 时，先用 `--operation-ref` 查询，再用原 `--idempotent-key` 续跑，不要换新 key |
+| exit 1，`subtype=feature_not_available`，提示服务端没有运行应用能力接口 | 当前服务端还不支持应用能力：网关内部错误 2200，或网关还没有这条路由、直接回 HTTP 404（`404 page not found`），只读复查结果相同；只有开通请求被回 404 时也按这一行处理 | 不要重试；转述错误，引导用户在妙搭 web 端处理，或等服务端升级 |
+| exit 3，身份或授权失效（如 `token_expired`；妙搭沙箱里用户凭证过期返回 221801，凭证无效时代理直接回 HTTP 401） | 当前用户凭证不可用，任何 key 都不会成功 | 转述 `hint`，本沙箱不需要也不要自行登录或初始化；不要用同一个 `--idempotent-key` 反复重试 |
+| exit 1 / 4 / 5，结果失败、未知或无法核实 | 请求可能已执行，也可能没有 | 按 `hint` 先用 `--operation-ref <idempotent_key>` 查询；要续同一次请求用原 `--idempotent-key`；结果未知时不要换新 key 重新申请 |
+
+带 `--idempotent-key` 时，CLI 先按同一 key 查询服务端保留的操作：已成功、结果未知或冲突直接报告，进行中则等待，只有可重试的失败才用同一 key 重发；只有服务端明确答复不保留该 key（`operation_unavailable`）时，才报错并提示先看 `+features`、确有需要再发起新操作；查询本身失败（权限、服务端错误、网络）时保留实际错误，结果按未知处理，只能用同一 key 重试或查询，不要换新 key。两种情况都不会自动重发或换 key。
+
+`running` 只在服务端确实异步接手时出现，CLI 最多等待 60 秒；`conflicted` 等终态立即返回，不会继续等待。超时或中断不会取消或回滚服务端操作。错误的 `hint` 会给出原 `idempotent_key` 与查询命令，不含连接信息。
+
+## 参考
+
+- [lark-apps-local-dev](lark-apps-local-dev.md) — 本地开发与部署流程
+- [lark-apps-db](../../lark-apps-db/SKILL.md) — 数据库命令与多环境

package/miaoda-modern/lark-apps-ops/references/lark-apps-local-dev.md

@@ -1,6 +1,6 @@
 # lark-apps 本地开发
 
-适用：当前妙搭应用（full_stack 全栈或 frontend 纯前端）的源码已在工作区，用本地 code agent/IDE 开发、调试数据库（仅全栈应用有数据库），再部署上线。
+适用：当前妙搭应用（full_stack 全栈或 frontend 纯前端）的源码已在工作区，用本地 code agent/IDE 开发、调试数据库（只适用于全栈应用，且 `+features` 里 `database` 为 `enabled=true`；frontend 应用没有数据库），再部署上线。
 
 ## 改完代码后部署上线
 
@@ -20,6 +20,7 @@
 - pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
 - 环境变量由脚手架在本地启动时处理。
 - frontend（纯前端，vite-react）应用的开发与部署流程和全栈一致，只是没有数据库、跳过一切 `+db-*` 步骤。后续要加数据库/后端能力时，本地链路不提供类型升级：引导用户到妙搭 web 的云端会话里用自然语言提出（如「给这个应用加登录和数据存储」）即可触发升级，无需特殊指令，也不要替用户拼站点地址。
+- 全栈应用的数据库默认可能未开启。**首次建表、写用库代码之前**：`+features --app-id "$app_id"` 看 `database` → `enabled=false` 时 `+feature-enable --feature database --app-id "$app_id"`（见 [features](lark-apps-features.md)）→ 平台自动生效，不需要 `+env-pull`、不需要手动重启 → 建表并做一次真实读写验证。库能查能建表不代表已开通（以 `+features` 为准），不要改环境文件或自行接连接串绕过开关。
 - DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`（见 lark-apps-db skill）；不要裸连数据库或自行拼连接串。
 - DB 分 `dev` / `online`；日常调试优先 `--environment dev`。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
 - 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --environment dev`。这是不可逆 high-risk 操作。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [