lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/workflows/migrate/knowledge-base.md

@@ -0,0 +1,564 @@
+# Vue2→Vue3 迁移先验知识
+
+> **用法**：plan / green / check → Read 全文 + 按 manifest.类型 选用章节；spec → Read 全文但仅提取；scan/tasks/red → 见「阶段索引表」
+> **component 详规**：`references/lcap-extension-component/`（plan/green 额外阅读，不在本文扩写）
+> **logic 详规**：`references/nasl-logic-authoring/SKILL.md`（plan/green/check 额外阅读，见 §logics-boundary）
+
+## 阶段索引表
+
+| 阶段 | Read 范围 |
+|------|-----------|
+| scan | §process-scaffold, §process-asset-types, §stories-truth, §process-doc, §logics-boundary |
+| spec | 全文（输出纪律见 migrate.spec 禁止条款） |
+| plan | 全文 + 按类型附加 references |
+| tasks | §process-matrix, §process-e2e |
+| red | §process-e2e |
+| green | 全文 + 按类型附加 references |
+| check | 全文 + 按类型选用 §alignment-checklist 或 migrate.check L1–L3/S1–S3 |
+
+## §asset-applicability · 章节类型适用表
+
+| KB 章节 | component | logic | shared-composable |
+|---------|-----------|-------|-------------------|
+| §alignment-checklist | ✅ check 主清单 | ❌ | ❌ |
+| §stories-truth | ✅ spec/plan | ❌ | ❌ |
+| §css-vars / §plugin-barrel | ✅ green/check | ❌ | ❌ |
+| §mixin-composable / §pitfalls | ✅ | 部分（纪律） | ✅ |
+| §implementation-order | ✅ green | ❌（用 create-logic-files） | 部分 |
+| §logics-boundary → nasl-logic-authoring | ❌ | ✅ plan/green/check | ❌ |
+| §process-e2e | ✅ red/tasks | ❌ | ❌ |
+
+## §discipline · 迁移纪律与核心原则
+
+## When to apply
+
+用户在迁移或实现 **LCAP 扩展组件**、提到 **Vue 2 / Vue 3**、**api.ts**、**NASL**、**Storybook**、**`block.stories` / `example.stories`**、**`docs/blocks.md` / `docs/examples.md`**、**Web Worker / Vite**、**`install` / `app.component` 全局注册**、**`src/components/index.ts` 桶导出**、**Mixins / Hooks**，或通过 **`.specify/scripts/bash/create-component-files.sh`** 生成组件骨架时，按本 Skill 执行；默认目标为 **1:1 逻辑与元数据对齐**，不做未经要求的产品改动。
+
+## Instructions（Agent 必须遵守）
+
+1. **禁止过度优化**：模板结构、报错文案、交互与 Vue 2 版一致；Hook 仅重组代码，不改对外行为与 API 面。
+2. **Mixin → Composable**：用 `useXxx.ts` 按职责拆分；`ref`/SDK 句柄通过参数传入或 return，避免隐式 `this`。
+3. **副作用与第三方实例**：定时器、监听、地图/SDK 等须在 `onUnmounted` / `reload` 等路径显式销毁，防止泄漏。
+4. **第三方库初始化时机**：凡是依赖“容器/DOM 已就绪”或库自身提供的 `ready/complete/onXxxReady` 回调才能正常工作的插件（如 tooltip、marker、事件绑定、样式/DOM 监听器），其初始化代码必须放在对应 ready 回调里；不得仅凭 `onMounted` 猜测时机。
+5. **依赖与构建一致性**：迁移后若出现 Rollup/Vite 解析失败（如 `Failed to resolve` / `Cannot find module`），优先核对 `package.json` 已安装依赖与 Vue2 源一致；若 Vue2 通过某依赖完成日期/格式/渲染逻辑，迁移时不得“省掉依赖”导致行为差异。
+6. **NASL**：`api.ts` 与原版一致（含多端、`ideusage`、`ExtensionComponent` type 等）；装饰器 `name` 与目录名一致。
+7. **验证**：对齐 Storybook（含 `demos` 复杂例）并跑 `npm run build`；处理控制台错误。
+8. **Web Worker**：在 Vite 下用 `?url` / `?worker` 等官方方式引用 worker，配置放在消费该能力的**模块顶部**、任何异步调用之前；见下文「Web Worker（Vite）」。
+9. **Block Story（溯源分源项目）**：Vue 2 **Vite 工程**以原仓库 **`block.stories.js` / `block.stories.ts`** 为真值做 **1:1**；**旧工程**以 **`docs/blocks.md`** 为真值。勿凭记忆重写；见下文「Block（block.stories）一一对齐」。
+10. **Example Story（溯源分源项目）**：Vue 2 **Vite 工程**以原仓库 **`example.stories.js` / `example.stories.ts`** 为真值做 **1:1**；**旧工程**以 **`docs/examples.md`**（及团队约定下的 `demos`）为真值。见下文「Example（example.stories）一一对齐」。
+11. **插件 `install` 与组件桶文件**：若入口通过 `import * as Components from './components'` 再 `Object.keys(Components).forEach` 注册，**`src/components/index.ts` 必须为每个组件提供与注册名一致的具名导出**，禁止仅靠「子目录 `export default` + `export *`」导致命名空间只有 `default` 或键名不符合预期；见下文「插件 install 与 components 桶导出」。
+
+## 核心原则
+
+| 原则 | 要求 |
+|------|------|
+| 1:1 逻辑 | 模板、文案、行为与 Vue 2 一致 |
+| 架构 | Mixins → Composition API（`useXxx`） |
+| 生命周期 | 第三方实例显式销毁 |
+| NASL | `api.ts` 与原版一致（含多端属性） |
+
+## §mixin-composable · Mixin → Hooks
+
+## Mixin → Hooks（要点）
+
+- **拆分**：按业务边界合并 `data` / `computed` / `methods` / `watch`，一边界一 `useXxx`。
+- **响应式**：`data` → `ref`/`reactive`；`computed` → `computed()`；`watch` 对齐 `deep`、`immediate`。
+- **生命周期**：`mounted` 等 → `onMounted` 等；副作用配套清理。
+- **对外方法**：原 Mixin 供模板/父组件调用的方法，经 Hook **return**；`defineExpose` 仅暴露原版已有能力（如 `reload`），勿随意加新导出。
+- **`$emitPrevent`**：Vue 2 Emitter mixin 提供的 `$emitPrevent(name, payload, senderVM)` 在 Vue 3 中无法直接使用，迁移为本地工具函数：
+
+```typescript
+function emitPrevent(name: string, payload: any): boolean {
+  let cancel = false;
+  emit(name as any, Object.assign(payload || {}, {
+    preventDefault: () => { cancel = true; },
+  }));
+  return cancel;
+}
+// 使用：if (emitPrevent('before-upload', { file: files[0] })) return;
+```
+
+## §vue3-children-clone · $children → cloneVNode
+
+## `$children` 操作 → `cloneVNode` 注入
+
+Vue 2 通过 `$children` 遍历 + `$set(vm, 'loading', true)` 直接修改 slot 子组件的 data/props，Vue 3 已废弃 `$children` 且禁止从外部 mutate 组件内部状态。
+
+**Vue 3 等效方案：`cloneVNode` + 功能组件**
+
+在渲染 slot 时用 `cloneVNode` 克隆 VNode 并注入额外 props，对目标子组件（可通过 `vnode.props?.flag` 等特征识别）自动补充状态，使用方**无需修改任何调用代码**：
+
+```typescript
+import { cloneVNode, useSlots } from 'vue';
+
+const uploadingCount = ref(0);
+const slots = useSlots();
+
+// 功能组件：渲染时自动向带有 flag="xxx-button" 的子组件注入 loading/disabled
+function SlotWithButtonState() {
+  const vnodes = slots.default?.() ?? [];
+  const isUploading = uploadingCount.value > 0;
+  return vnodes.map((vnode) => {
+    if (vnode.props?.flag === 'large-file-uploader-button') {
+      return cloneVNode(vnode, { loading: isUploading, disabled: isUploading });
+    }
+    return vnode;
+  });
+}
+```
+
+模板中以 `<SlotWithButtonState />` 替换原来的 `<slot></slot>`。`uploadingCount` 为响应式 ref，变化后功能组件自动重渲染、重新注入正确的 props，无需手动"reset"。
+
+> **适用场景**：任何 Vue 2 中通过 `$children` 查找特定子组件并设置其属性的模式，均可用此方案替换。
+
+## §alignment-checklist · 对齐清单
+
+## 对齐清单（迁移时逐项勾选）
+
+**Template**
+
+- [ ] 嵌套结构与 Vue 2 一致（注意 Fragment 导致样式差异）
+- [ ] 报错、空状态等文案 1:1
+- [ ] 作用域插槽：`#item="slotProps"`，变量名与原版一致
+
+**Logic**
+
+- [ ] 逐条核对 `watch`（如部分组件需 `clearSelectedItem`，海量点等可能不需要）
+- [ ] `defineExpose` 仅导出原版方法
+- [ ] 特殊清理（如某 Layer 样式）在组件内按需实现
+
+**第三方库集成**
+
+- [ ] 第三方库初始化放在其 `ready/complete/onXxxReady` 回调或对应挂载完成点（而非仅 `onMounted` 猜测）
+- [ ] DOM 监听器（`MutationObserver` / `ResizeObserver` / 鼠标事件 / tooltip DOM 事件）创建时机保证目标 DOM 存在；在 `onUnmounted` / `reload` 中执行 `disconnect/removeEventListener` 等清理
+- [ ] 布局高度语义与 Vue 2 保持一致：固定值保持固定；基于容器继承的 `height: 100%/flex` 保持链路（根节点与 IDE 父容器的高度继承关系验证）；若 Vue 2 有 `updateStyles/root.style.height`，Vue 3 需沿用同样触发时机
+- [ ] Vue 2 mixin/support 里“工具方法/数据预处理/格式化函数”的清单已全量迁移；迁移后不应只保留一部分工具导致数据/渲染缺失
+
+**LCAP / NASL**
+
+- [ ] 多端：`@ExtensionComponent({ type: 'both' })` 等配置正确
+- [ ] 组件名不含数字（如 `3d` → `three-dim`）
+- [ ] `ideusage`：`container` / `element` 等与原版一致
+- [ ] 设计器：`window.$uilibenv?.IDE_DESIGNER === true`；**仅**对依赖容器尺寸才能正常渲染的组件（图表、地图、PDF 等）加固定高度 + `overflow: hidden`，防止撑开画布；**简单容器（如触发按钮、下载包装器等）无需此处理**，强加反而会裁掉插槽内容
+
+```vue
+<template>
+  <div :class="[isDesigner && $style.designerRoot]">
+    <!-- 组件内容 -->
+  </div>
+</template>
+
+<script setup lang="ts">
+const isDesigner = (window as any).$uilibenv?.IDE_DESIGNER === true;
+</script>
+
+<style module>
+.designerRoot {
+  height: 300px;
+  overflow: hidden;
+  border: 1px solid #ccc;
+}
+</style>
+```
+
+**Storybook**
+
+- [ ] 还原原项目 `demos` / `examples` 复杂示例
+- [ ] 动态交互（如切换数据）用 `ref` 等在 Story 中模拟
+- [ ] `block.stories.*`：IDE 左侧预览；**Vite 源项目**对齐原 **`block.stories.js` / `block.stories.ts`**，**旧工程**对齐 **`docs/blocks.md`**（见下节「Block」）
+- [ ] `example.stories.*`：运行时 Demo；**Vite 源项目**对齐原 **`example.stories.js` / `example.stories.ts`**，**旧工程**对齐 **`docs/examples.md`** / `demos`（见下节「Example」）
+
+**api.ts**
+
+- [ ] `@nasl/types` 等约定；`Component` 等装饰器 `name` 与组件目录名一致
+- [ ] `EnumSelectSetter` 的 `options` 数组中**禁止写 `castFunction` 字段**（该字段不在类型定义中，会导致 `tsc` build error）；选项只需 `{ title, value }`：
+
+```typescript
+// ❌ 错误
+setter: { concept: 'EnumSelectSetter', options: [{ title: 'JSON', castFunction: '', value: 'json' }] }
+// ✅ 正确
+setter: { concept: 'EnumSelectSetter', options: [{ title: 'JSON', value: 'json' }] }
+```
+
+- [ ] **prop 默认值以 `api.yaml` / `api.ts` 为准**：若 Vue 2 组件代码漏写默认值但 `api.yaml` 已声明，Vue 3 迁移时按 `api.yaml` 补齐，不应照搬 Vue 2 组件代码的遗漏
+- [ ] **LCAP v-model 约定**：LCAP 平台使用 `value` prop + `emit('update:value', ...)` 的 sync 模式（而非 Vue 3 标准的 `modelValue` + `update:modelValue`）；模板中使用 `v-model:value="xxx"`
+
+**Plugin / 入口导出（`install`）**
+
+- [ ] 若存在 `install` 内 `import * as Components` + 按 key 遍历 `app.component(name, …)`：**`components/index.ts`** 已用 **`export { default as Xxx } from './…'`** 等形式，使 `Components` 的键为 **`CwDocPreview` 等真实组件名**，而非仅 `default`
+- [ ] 页面中自定义标签不解析 / 组件未按预期挂载时，核对 **`app.component` 注册名**与模板标签是否一致
+
+## §stories-truth · Stories 溯源
+
+## Block（block.stories）一一对齐
+
+迁移中最易偏离的是新区块 Story 与**溯源真值**不一致。先判断 **Vue 2 源仓库**是 **Vite 工程**还是 **旧工程**：
+
+| 源项目类型 | 真值来源 | 对齐方式 |
+|------------|----------|----------|
+| **Vue 2 + Vite** | 原组件目录下 **`block.stories.js`** 或 **`block.stories.ts`** | 迁移后的 `block.stories.*` 与源文件 **1:1**（template / 元数据 / 静态 `args` 等按团队约定逐项对照） |
+| **旧工程** | **`docs/blocks.md`**（或团队约定的等价路径） | Story 中 **`template`（或等价渲染结构）** 与文档内 HTML 片段 **逐段对齐** |
+
+**旧工程 · Template 注意**：允许为 Story API 包一层容器，但**不要为了「代码整洁」合并 DOM 层级、改写 `:class` / 类名**，以免与 IDE 区块预览或全局样式不一致。
+
+**Vue2 内置组件标签替换**：Vue2 block.stories 模板中常见 `u-button`、`van-button` 等 Cloud UI / Vant 专属标签，这些在 Vue3 项目中不存在。迁移时须替换为 Vue3 项目实际可用的组件，如 `el-button`（Element Plus）；若不确定，询问用户或查看 Vue3 项目已安装的 UI 库。
+
+## Example（example.stories）一一对齐
+
+运行时示例须与**溯源真值**一致，同样按源项目类型分支：
+
+| 源项目类型 | 真值来源 | 对齐方式 |
+|------------|----------|----------|
+| **Vue 2 + Vite** | 原组件目录下 **`example.stories.js`** 或 **`example.stories.ts`** | 迁移后的 `example.stories.*` 与源文件 **1:1**（交互、变量名、方法名、调用顺序） |
+| **旧工程** | **`docs/examples.md`**（及原 **`demos`** 中 Vue 示例，若文档与 demos 并存则以团队约定优先） | 与文档 / demos 中的示例 **1:1**，禁止凭印象重写后「差不多能用」 |
+
+## §css-vars · CSS 变量替换
+
+## CSS 变量替换（Cloud UI → Element Plus）
+
+Vue 2 cloud-ui 组件使用 `--uploader-*`、`--linear-progress-*`、`--cursor-pointer`、`--transition-duration-base` 等私有 CSS 变量，Vue 3 项目不引入 cloud-ui，需替换为 Element Plus 全局变量。
+
+**常用映射（参考，具体以语义匹配为准）：**
+
+| Cloud UI 变量 | Element Plus 替代 |
+|---|---|
+| `--cursor-pointer` | `pointer`（直接写死） |
+| `--transition-duration-base` | `var(--el-transition-duration) var(--el-transition-function-ease-in-out-bezier)` |
+| 背景填充（浅） | `var(--el-fill-color-lighter)` |
+| 背景填充（悬浮） | `var(--el-fill-color)` |
+| 主色 / 链接色 | `var(--el-color-primary)` |
+| 主色深（悬浮） | `var(--el-color-primary-dark-2)` |
+| 边框色 | `var(--el-border-color)` |
+| 边框圆角 | `var(--el-border-radius-base)` |
+| 次要文字色 | `var(--el-text-color-secondary)` |
+| 占位符/图标色 | `var(--el-text-color-placeholder)` |
+| 错误/危险色 | `var(--el-color-danger)` |
+| 成功色 | `var(--el-color-success)` |
+| 字体大小（小） | `var(--el-font-size-extra-small)` |
+
+**Storybook 配置步骤：**
+
+1. 创建 `.storybook/vars.css`，内容复制自 `lcap-extension-component/component/platform/theme-variables-element-plus.md`
+2. 在 `.storybook/preview.ts` 中注册 Element Plus 并导入变量文件：
+
+```typescript
+import ElementPlus from 'element-plus';
+import 'element-plus/dist/index.css';
+import './vars.css';
+
+setup((app) => {
+  app.use(ElementPlus);
+});
+```
+
+3. 将 `element-plus` 加入 `devDependencies`（`npm install element-plus --save-dev`）
+
+## §web-worker · Web Worker（Vite）
+
+在 Vite 中处理 **Web Worker**（含第三方库内置 worker）时，避免继续沿用「CDN 链接 / Webpack entry / 手写复制 `*.min.js`」等旧习惯，优先用构建器解析出的 **稳定 URL 或 Worker 构造**。
+
+**原则**
+
+- **统一由 Vite 解析 worker 资源**：使用 `?url` 得到 worker 脚本 URL，或按需使用 `?worker` / `new URL(..., import.meta.url)` 等 [Vite 文档](https://vitejs.dev/guide/features.html#web-workers) 推荐写法。
+- **前置初始化**：设置 `workerSrc`、`new Worker(...)` 等逻辑放在**实际消费方模块的顶部**（该文件内任何 `async` 业务逻辑执行之前），避免首次调用时 worker 尚未就绪。
+- **SSR**：若该模块会在 SSR 阶段执行，对 `Worker` / `window` 相关代码加环境守卫，仅在浏览器侧初始化。
+
+**第三方示例：`pdfjs-dist`**
+
+将 worker 脚本作为 URL 模块导入，并赋给官方全局配置（路径以当前安装的 `pdfjs-dist` 版本为准）：
+
+```typescript
+import * as pdfjsLib from 'pdfjs-dist';
+import pdfWorker from 'pdfjs-dist/build/pdf.worker.mjs?url';
+
+pdfjsLib.GlobalWorkerOptions.workerSrc = pdfWorker;
+```
+
+自研 worker 可类似使用 `import MyWorker from './my.worker?url'` 再 `new Worker(MyWorker, { type: 'module' })`（是否 `module` 以浏览器与打包目标为准）。
+
+## §plugin-barrel · 插件 install 与 components 桶导出
+
+## 插件 `install` 与 `components` 桶导出
+
+扩展包常在入口（如 `src/index.ts`）用 **Plugin** 做全局注册：
+
+```typescript
+import * as Components from './components';
+
+export const install: Plugin = (app, options) => {
+  Object.keys(Components).forEach((name) => {
+    app.component(name, (Components as Record<string, Component>)[name]);
+  });
+};
+```
+
+此处要求 **`import * as Components` 得到的命名空间以「组件名」为键**（如 `CwDocPreview`），否则 `app.component` 的**注册名**会错，页面表现为**标签未解析、组件不渲染**。
+
+**典型问题**：子目录仅 `export default`、桶文件写 **`export * from './cw-doc-preview'`** 等——在配合 `import *` 自动注册时，**无法为命名空间提供稳定的 PascalCase 键名**，易出现**仅存在 `default` 键**或与预期组件名不一致。
+
+**推荐写法**：在 **`src/components/index.ts`（或等价桶文件）** 使用**具名再导出**，显式指定键名：
+
+```typescript
+export { default as CwDocPreview } from './cw-doc-preview';
+export { default as CwPdfPreview } from './cw-pdf-preview';
+// …
+```
+
+这样 `Components` 为 `{ CwDocPreview: …, CwPdfPreview: … }`，与 `app.component('CwDocPreview', …)` 及模板中的标签名一致。
+
+**经验**：组件库入口**宁可手写具名导出多几行**，也不要依赖模糊的 `export *` 聚合 default；迁移后若组件「完全不显示」，**优先查注册名与导出键是否一致**。
+
+## §pitfalls · 常见坑
+
+## 常见坑
+
+- **`$children` 操控 slot 子组件**：Vue 3 无 `$children`，且不允许从外部 mutate 子组件 props/data；用 `cloneVNode` + 功能组件注入 props，见上文「`$children` 操作 → `cloneVNode` 注入」。
+- **CSS 属性选择器依赖的 prop 必须显式声明并绑定**：若 Vue 2 中某 prop（如 `display`）未在 `props` 里声明、靠 attr 透传到根节点触发 CSS 属性选择器（如 `.root[display="inline"]`），Vue 3 迁移时必须：① 在 `defineProps` 中声明该 prop；② 在根节点显式绑定 `:display="display"`——否则 `display` 值为 `undefined`，CSS 选择器永远不命中。
+- **`$emitPrevent`**：Vue 2 Emitter mixin 方法，Vue 3 迁移为本地工具函数，见上文「Mixin → Hooks」。
+- **地图类**：`await map.on('complete')` 后再初始化聚合/海量点等；慢网否则易错。
+- **插件/第三方初始化时机错误**：依赖库的 tooltip/marker/事件绑定若放在 `onMounted`，可能出现 tooltip 不显示、DOM 节点丢失或样式不同步等问题；应迁移到库的 `ready/complete/onXxxReady` 回调内初始化。
+- **构建/解析失败（依赖缺失）**：`moment`/日期格式化/渲染工具等如果在 Vue2 源中被使用，迁移时必须保证依赖已安装且导入路径一致；出现 `Failed to resolve` 时优先检查 `package.json`。
+- **布局高度语义丢失**：固定高度/`height:100%`/flex 继承链路在 Vue3 根节点或容器上若不一致，容易导致表格遮挡、内容高度塌陷或无法自适应；迁移后需对照 Vue2 高度策略验证。
+- **DOM 同步监听器未断开**：`MutationObserver`/`ResizeObserver`/事件监听若只在迁移中“创建了”但未在 `onUnmounted`/`reload` 中 `disconnect/removeEventListener`，会导致重复触发或渲染异常。
+- **Vue2 工具方法漏迁**：如果 Vue2 mixin/support 存在数据预处理/格式化/normalize 工具方法，迁移时只迁了部分函数会导致渲染缺失或 IDE 样式配置不生效。
+- **地图内存**：如 `destroyAMap`；`reload` 与 `onUnmounted` 先销毁再建新实例。
+- **构建**：`process.env`（Webpack）→ `import.meta.env`（Vite）。
+- **资源**：静态资源同步到 `src/assets` 并修正引用。
+- **Hooks 复用**：勿强行统一不同组件对同一事件（如 Zoom）的处理。
+- **依赖**：第三方库写入 `package.json`；大库（如 `pdf.js`）优先 npm + ESM，Worker 见上文「Web Worker（Vite）」。
+- **全局注册**：`install` + `import * as Components` 时，**桶文件须具名导出**，见上文「插件 install 与 components 桶导出」。
+- **LCAP `Current<T>` 作用域插槽传参**：`api.ts` 中 `slotDefault: (current: nasl.ui.Current<T>)` 时，组件内应 `<slot :item="row" :index="i">`，父模板 `#default="current"` 使用 `current.item`。**禁止**写成 `<slot :current="{ item: row, index: i }">`——会导致 props 嵌套为 `{ current: { item, index } }`，`current.item` 变成对象、画布空白。对齐 Vue2 源库的 `:item`/`:index` 写法。
+- **`vue-draggable-plus` 与循环 slot**：`VueDraggable` 内 `v-for` 渲染 scoped slot 时，**勿**在 `div` 内再包一层 `<template><slot/></template>`（Vue2 `vuedraggable@2` 可能可用，Vue3 下易出现空 `<template>`、插槽不渲染）。slot 应直接作为列表项 DOM 的子节点。
+- **block.stories 预览 IDE 容器**：组件靠 `inIDE` 分支 + `dataSource.display: 3` 展示占位项、block 文档又无 `dataSource` 时，Storybook 需在 story 内临时设置 `window.$uilibenv = { IDE_DESIGNER: true }`（`unmounted` 清理），否则运行时 `v-for` 遍历空数组、区块 Story 空白。
+
+## §implementation-order · 工作流
+
+## 工作流
+
+1. 读原版 `api.ts`、`index.vue`；判断 Vue 2 源工程是否为 **Vite**：若是，打开原 **`block.stories.js` / `block.stories.ts`**、**`example.stories.js` / `example.stories.ts`** 作为 Story 真值；若为**旧工程**，读 **`docs/blocks.md`**、**`docs/examples.md`**（及 `demos`，若存在）
+2. 在仓库根目录执行 `bash .specify/scripts/bash/create-component-files.sh` 生成骨架（参数以脚本说明或团队约定为准）
+3. 配 `api.ts`（type、props、events）
+4. 迁移前列出 Vue2 mixin/support 的“工具方法/数据预处理/格式化函数”全量清单；**先逐项确认该方法/属性在组件模板或 methods 中是否有实际调用点**——有调用才迁移为 composable，从未被调用的死代码无需创建 composable，只需保留对应的 prop 声明即可；逐项核对迁移结果不缺失（再接通用 Hooks + 组件特有逻辑）。若有 **`install` 全局注册**，核对 **`src/components/index.ts`** 具名导出与 `app.component` 注册名一致
+5. 第三方库初始化点对齐其 `ready/complete/onXxxReady` 回调；同步梳理 DOM 监听器/observer 的创建时机与 `onUnmounted` / `reload` 清理路径
+6. 分别还原 **`block.stories.*`** 与 **`example.stories.*`**：**Vite 源**对齐原 **`block.stories.js` / `block.stories.ts`**、**`example.stories.js` / `example.stories.ts`**；**旧工程**对齐 **`docs/blocks.md`** / **`docs/examples.md`**（及 `demos`）
+7. Storybook 预览 + `npm run build`；若出现解析失败，优先检查依赖安装是否与 Vue2 源一致
+8. 核对 `package.json` 的 `title`、`description`
+
+## §logics-boundary · 逻辑迁移边界
+
+**仅当**迁移涉及 `logics/` 下依赖库逻辑（`@NaslLogic`、`nasl` 类型、可变参数 / 泛型 / 高阶函数等）时，plan / green / check 额外遵循：
+
+**`references/nasl-logic-authoring/SKILL.md`**
+
+logic 资产**不适用**本 KB 的 §alignment-checklist、§stories-truth、§css-vars、§plugin-barrel、§process-e2e。
+
+check 审计维 L1–L3 定义在 `commands/migrate.check.md`，不在本文重复。
+
+## §process-doc · 迁移文档职责
+
+| 文件 | 模板 | 写什么 | 不写什么 | 由谁写 |
+|------|------|--------|----------|--------|
+| `manifest.md` | `migration-manifest-template.md` | 资产清单 + 状态流转 | 详细报告内容 | scan（创建）/ 各命令（更新状态行） |
+| `spec.md` | `migration-spec-template.md` | Vue2 行为真值（完整规格提取） | 转换方案、Vue3 实现细节 | spec |
+| `plan.md` | `migration-plan-template.md` | 转换策略、文件路径规划、风险评估 | TDD 步骤编排、状态记录 | plan |
+| `tasks.md` | `migration-tasks-template.md` | TDD 编排 + 行为等价矩阵 | 转换策略、源码分析 | tasks（创建）/ red+green+check（填充矩阵） |
+| `report.md` | `migration-report-template.md` | 5 维审计 + 矩阵验证 + 终端证据 + 机制差异 | 其他资产状态 | check |
+| `library-report.md` | `library-report-template.md` | 库级三门禁 + 产物验证 + 资产统计 | 单资产细节 | check §E |
+| `specs/manifest.md` | `migration-manifest-template.md` | 资产清单 + depends_on + library_status | 详细报告 | scan / 各命令 |
+
+**文档位置**：所有文档位于 `<Vue3工程>/specs/<NN>-<资产名>/` 目录内（manifest.md 在 `specs/` 根）。
+
+**矩阵填充规则**：
+- `tasks.md` 创建矩阵骨架（行为描述 + 维度）
+- `migrate.red` 填充"RED 测试编码"列
+- `migrate.green` 填充"GREEN 实现"列
+- `migrate.check` 填充"等价状态"列（最终判定）
+
+## §process-matrix · 行为等价矩阵
+
+行为等价矩阵是 Superpowers 迁移的核心追踪机制，记录 Vue2 行为从「定义 → 测试编码 → 实现 → 验证」的完整链路。
+
+### 矩阵结构
+
+| # | 行为描述 | 维度 | RED 测试编码 | GREEN 实现 | 等价状态 |
+|:--|:---|:---|:---|:---|:---|
+
+- **行为描述**：来自 spec.md，一行 = 一个可独立测试的 Vue2 行为
+- **维度**：Props / Events / Methods / Slots / State / Lifecycle
+- **RED 测试编码**：测试文件路径 + 行号（如 `__tests__/index.spec.ts:42`）
+- **GREEN 实现**：实现文件 + 函数名（如 `index.vue:handlePlay`）
+- **等价状态**：最终验证结论
+
+### 等价状态值
+
+| 状态 | 含义 | 处理方式 |
+|:---|:---|:---|
+| ✅ 等价 | 测试通过，实现与 spec 一致 | 无需处理 |
+| ⚠️ 有意差异 | Vue3 框架限制导致的差异 | 记录原因，归入 report 维度 5 |
+| ❌ 缺失 | 无测试 / 测试未通过 / 实现遗漏 | 必须修复至 ✅ 或 ⚠️ |
+| `—` | 尚未填充 | 等待对应阶段处理 |
+
+### 填充时机
+
+```
+tasks → 创建矩阵骨架（行为描述 + 维度列）
+red   → 填充"RED 测试编码"列（测试文件:行号）
+green → 填充"GREEN 实现"列（实现文件:函数名）
+check → 填充"等价状态"列 + 最终判定
+```
+
+### 完成标准
+
+- **RED 完成**：测试编码列无空行（每行为有测试）
+- **GREEN 完成**：实现列无空行（每行为有实现）
+- **CHECK 通过**：等价状态列无 ❌ 行
+
+### 三类型矩阵行差异
+
+| 类型 | 典型维度 | E2E |
+|------|----------|-----|
+| component | Props / Events / Methods / Slots / State / Lifecycle | 必需 |
+| logic | Params / Return / Generic / Edge | 禁止 |
+| shared-composable | Methods / SideEffect / Contract | 禁止 |
+
+## §process-scaffold · 项目创建约束
+
+### create-extension-project.sh
+
+```bash
+bash <skill-scripts>/create-extension-project.sh \
+  --name <name> --title <title> \
+  --target-dir <dir> \
+  [--template vue3|vue2]
+```
+
+- `--name`：仅 `[a-z_]+`
+- **`--target-dir`**：放置目录（**不含库名**）；脚本在其下创建 `<name>/`
+- **`--template`**：默认 `vue3`；**仅** `vue2` | `vue3`（react 暂不支持）
+- stdout：`libraryDir=...`、`template=...`
+- 验证：`npm install --prefix "<dir>/<name>" && npm run dev --prefix "<dir>/<name>"`
+- **不**在本脚本内执行 `lcap install`
+
+### create-component-files.sh
+
+```bash
+bash <skill-scripts>/create-component-files.sh \
+  --library-dir <libraryDir> \
+  --name <name> --title <title> [--type pc|h5|both]
+```
+
+- **`--library-dir`**：已存在库根（含 `package.json`、`@lcap/builder`）
+- 前置：`npm install --prefix "<libraryDir>"` 已完成
+- 产出：`src/components/<name>/`（或 CLI 决定的目录）
+- **后续只能 Edit，禁止 Write 全量重写**
+
+## §process-asset-types · 迁移资产类型
+
+| 类型 | scan 检测 | E2E | 单资产产物验证 |
+|------|-----------|-----|----------------|
+| `component` | 含 api.ts + index.vue 的目录 | 必需 | ZIP + viewComponents 含本组件 |
+| `logic` | logics/ 下 @NaslLogic 导出 | 跳过 | 仅 build exit 0 |
+| `shared-composable` | Mixin 被 ≥2 组件引用 | 跳过 | 仅 build exit 0 |
+
+各 migrate 命令必须读取 manifest 中该资产的「类型」列，走对应分支（→ 各 command 内「资产类型分支」节）。
+
+### 共享 Composable 升格规则（scan 执行）
+
+- Mixin 被 **≥2** 组件 import → manifest 新增 `shared-composable` 资产，资产名 = mixin 文件名去扩展名（如 `emitter.js` → `emitter`）
+- 仅 1 组件引用 → **不**单独建资产，在该 component 的 plan 内 composable 化
+
+### 产出路径（默认）
+
+- `src/composables/use<MixinPascal>.ts`
+- `src/composables/__tests__/use<MixinPascal>.spec.ts`
+
+plan 可改路径，但须在文件路径表锁定。
+
+### depends_on
+
+- shared-composable 行 `depends_on` 为空
+- 引用它的 component 行 `depends_on` 填 shared 资产名（多个逗号分隔）
+
+### 环检测
+
+scan 拓扑排序时若发现 depends_on 环 → 报告错误并终止，要求用户手动解环。
+
+推荐顺序：**shared-composable → logic → component**（manifest 拓扑排序；环则 scan 报错终止）。
+
+## §process-e2e · E2E 规则（仅 component）
+
+> **仅 component 资产**编写 E2E；logic / shared-composable **禁止** E2E 任务。
+
+> 与 create/evolve 工作流共享同一规范（来源：`references/lcap-extension-component/SKILL.md`）。
+
+### Story ID 生成规则
+
+storyId = `<title-kebab-case>--<export-name-kebab-case>`
+
+- **title**：`export default { title: 'xxx' }` 的值，Storybook 自动 kebab 化
+- **export name**：具名导出变量名（PascalCase → kebab-case）
+
+示例：
+```js
+export default { title: 'cw-audio-view-examples' };
+export const BasicUsage = { ... };
+// → storyId: "cw-audio-view-examples--basic-usage"
+```
+
+### E2E 访问方式
+
+**必须用 iframe 直链**：`/iframe.html?id=<storyId>&viewMode=story`
+
+**禁止**：`/?path=/story/...`、中文 title、路径分隔符（`/`）。
+
+### Story Title 命名约定
+
+| stories 文件 | title 格式 |
+|---|---|
+| block.stories | `<组件名-kebab>-blocks` |
+| example.stories | `<组件名-kebab>-examples` |
+
+### 验证 story ID
+
+编写 E2E 前**必须**确认 storyId：
+- `npm run build-storybook && grep <组件名> storybook-static/index.json`
+- 或运行时访问 `http://localhost:<port>/index.json`
+
+不可凭推测编写 storyId。
+
+### 选择器策略
+
+**优先级**：
+
+1. `data-testid`（最稳定）
+2. Accessibility role
+3. 语义 class（库产出的稳定 class）
+4. CSS 选择器
+
+**第三方库 DOM 改写**：重型第三方库会包裹/替换原始 DOM；选择器**须以库实际产出 DOM 为准**；编写 E2E 前在 DevTools 确认实际结构；禁止假设原始 HTML 标签直接可选。
+
+**规则**：
+
+- 禁止裸标签选择器不加限定（会匹配 Storybook 控件区）
+- 匹配多个时用 `.first()` / `.nth()`
+- 第三方库渲染有延迟：用 `waitForSelector` 而非固定 timeout
+
+**Storybook 运行时验证**：`npm run build` 不能替代 dev 运行时验证；E2E 须监听 `page.on('pageerror')` 和 `page.on('console')`（过滤网络 404：`msg.text().includes('404')` 或 `net::ERR`）。详细 guardrails 见 `workflow-guardrails.md`。
+
+## §process-library-finalize · 库级收尾
+
+### 触发条件（migrate.check §E）
+
+1. manifest 全部非 `🚫 blocked` 资产均为 `✅ verified`；或
+2. 用户传入 `--finalize-library`（仅跑库级段，不要求资产名）
+
+### 动作
+
+1. 全量 `npm run test` + `npm run build` + `npm run test:e2e`（无 component 时 e2e 标注 N/A）
+2. 产物验证 4 项（与 create flow BUILD-VERIFY 一致，viewComponents **全量**非空）
+3. 写入 `specs/library-report.md`
+4. manifest：`library_status → 🏁 library-verified`，记录 `library_verified_at`
+
+### library-report.md 结构
+
+见 `templates/library-report-template.md`。