lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/commands/migrate.plan.md

@@ -0,0 +1,169 @@
+---
+description: 基于 spec.md 行为真值，按 knowledge-base §id 映射转换策略，规划文件路径，逐条核对陷阱，产出含路径锁定与风险评估的迁移方案。⛔需用户审批。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+用户输入为资产名称（如 `cw_audio_view`）。若为空，展示 `specs/manifest.md` 中所有 spec-done 状态的资产供选择。
+
+## 必要知识（必须在执行前 Read，不可跳过）
+
+### 共通（所有资产类型）
+1. **`workflows/migrate/knowledge-base.md`** — Vue2→Vue3 迁移先验知识（全文）
+2. **`LEARNINGS.md`** — 先验/约束/checklist（若存在）
+
+### 按 manifest.类型 附加（步骤 0 读取类型后加载）
+
+**component** 额外 Read：
+- `references/lcap-extension-component/SKILL.md`
+- `references/lcap-extension-component/implementation-rules.md`
+
+**logic** 额外 Read：
+- `references/nasl-logic-authoring/SKILL.md`
+
+**shared-composable**：无 extension-component / nasl-logic-authoring
+
+> 转换与验收：component 以 KB + lcap-extension-component 为准；logic 以 KB §discipline + nasl-logic-authoring 为准。不得凭 AI 记忆。
+> 全文 Read KB 后，按 KB §asset-applicability 与本文「资产类型分支」跳过不适用章节。
+
+## 核心纪律
+
+> **每个转换决策必须引用 KB 章节或 references 文档。**
+> 不允许凭 AI 知识做决策。不确定时以 knowledge-base 为准。
+
+## 禁止条款
+
+- ❌ 凭 AI 知识做转换决策（必须引用 KB 章节或 references）
+- ❌ 跳过 §pitfalls 核对（§pitfalls 叙事列表逐条确认是否命中）
+- ❌ 使用 theme-variables 文档中不存在的 CSS 变量名
+- ❌ 在 plan 中写 TDD 步骤编排（那属于 migrate.tasks）
+- ❌ 在 plan 中重新提取 Vue2 行为（那属于 migrate.spec，已完成）
+
+---
+
+## 工作流程
+
+### 步骤 0：读取资产类型
+
+1. 从 `specs/manifest.md` 读取当前资产的「类型」列
+2. 打开本文「资产类型分支」，**仅**执行该分支步骤
+3. 禁止执行其他类型步骤（例：logic 禁止 E2E / ideusage / §alignment-checklist）
+
+### 1. 确认资产
+
+- 从 `specs/manifest.md` 确认资产存在且状态为 `🔍 spec-done`
+- 读取 `specs/<NN>-<资产名>/spec.md`（Vue2 行为真值）
+
+### 2. 映射转换策略
+
+逐项制定转换策略，**每项必须引用对应 knowledge-base 章节**：
+
+#### 2.1 架构转换
+
+按 `migration-plan-template.md`「转换策略表」填写；每项必须引用 KB 章节（§mixin-composable、§vue3-children-clone、§pitfalls 等），不得凭 AI 记忆。
+
+#### 2.2 Mixin → Composable（→ §mixin-composable）
+
+对照 spec.md 中的 Mixin 调用点分析：
+1. 列出所有方法 → spec.md 已标注是否有调用点
+2. 按业务边界拆 `composables/useXxx.ts`（非按生命周期）
+3. `defineExpose` 仅暴露原版已有 methods
+4. 副作用（定时器/监听器/SDK）→ `onUnmounted` 显式销毁
+5. 第三方 init → 放库的 `ready/onXxxReady` 回调
+
+#### 2.3 样式转换（→ §css-vars + theme-variables-element-plus.md）
+
+- 对照 §css-vars 映射表
+- **交叉核对** `platform/theme-variables-element-plus.md` 确认变量名存在
+- scoped style 强制
+
+#### 2.4 风险与陷阱（→ §pitfalls 逐条核对）
+
+逐条对照 §pitfalls 叙事列表（源 SKILL 17 条），标记本资产命中项：
+
+| # | 陷阱 | 是否命中 | 预防措施 |
+|---|------|---------|---------|
+| 1 | （从 KB §pitfalls 逐条填写） | ✓/✗ | … |
+| … | … | | |
+
+### 2.0 确定资产类型分支
+
+从 manifest 读取「类型」列：
+
+| 类型 | plan 输出 |
+|------|-----------|
+| component | 现有文件路径表（api/ide/stories/e2e） |
+| logic | 使用 `migration-plan-template.md` logic 文件表；ideusage/stories/css-vars 节标 N/A |
+| shared-composable | 使用 shared 文件表；api/ide/stories 节标 N/A |
+
+输出 plan.md 时必须含 `**资产类型**` 字段（与模板一致）。
+
+### 3. 规划文件结构（路径锁定）
+
+**文件路径规划表**：
+
+| 模块 | 职责 | 产出路径 | 测试层 | 操作 |
+|------|------|----------|--------|------|
+| api.ts | NASL 接口声明 | `src/components/<name>/api.ts` | — | 新增 |
+| ideusage.json | IDE 设计器配置 | `src/components/<name>/ideusage.json` | — | 新增 |
+| index.vue | UI 组装 | `src/components/<name>/index.vue` | Vitest(DOM) + E2E | 新增 |
+| useXxx.ts | 业务逻辑 | `src/components/<name>/composables/useXxx.ts` | Vitest(返回值) | 新增 |
+| index.ts | 桶文件导出 | `src/components/<name>/index.ts` | — | 新增 |
+| block.stories | 画布拖拽 | `src/components/<name>/stories/block.stories.js` | — | 新增 |
+| example.stories | 功能 demo | `src/components/<name>/stories/example.stories.js` | — | 新增 |
+| 单测 | Vitest | `src/components/<name>/__tests__/index.spec.ts` | — | 新增 |
+| E2E | Playwright | `e2e/<name>.spec.ts` | — | 新增 |
+
+**测试层说明**（→ `references/lcap-extension-component/workflow-guardrails.md`）：
+- `Vitest(返回值)` — 纯逻辑，直接断言返回
+- `Vitest(调用参数)` — 调用浏览器 API，仅 mock 验证调用参数
+- `Vitest(DOM) + E2E` — DOM 操作，Vitest 验证结构，E2E 验证渲染
+
+### 4. 复杂度评估
+
+根据 spec.md 内容评估：
+- **HIGH**：Mixin ≥ 3 或 Props ≥ 8 或第三方库 ≥ 2
+- **MEDIUM**：1-2 Mixin 或有第三方库
+- **LOW**：无 Mixin，Props ≤ 3，无第三方
+
+### 5. ⛔ 用户审批门禁
+
+展示方案摘要，等待用户确认后方可继续：
+- 转换策略概要（关键决策点表格）
+- 文件路径规划表
+- 已识别风险（命中的 §pitfalls 陷阱）
+- 复杂度评估 + 主要复杂点
+
+**隐式审批判定**：
+- 用户回复含 tasks/继续/开始/OK 等意图 → 视为审批通过
+- 用户回复 `/migrate.tasks <资产名>` → 直接视为审批 + 进入 tasks
+- 用户提出修改意见 → 按意见修改后重新展示
+
+### 6. 写入方案
+
+用户确认后：
+- 将方案按 **`templates/migration-plan-template.md`** 格式写入 `specs/<NN>-<资产名>/plan.md`
+- 更新 `specs/manifest.md`：状态 `🔍 spec-done` → `🔄 planned`
+
+### 7. 报告
+
+输出：
+- 资产名称与类型
+- 转换策略摘要（关键 3-5 项决策）
+- 复杂度评估
+- 下一步指引：`/migrate.tasks <资产名>` 编排 TDD 执行步骤
+
+## 关键规则
+
+- Vue2 源码是行为的唯一真值——本命令基于 spec.md 做映射，不重新解读源码
+- 每个转换决策必须引用 KB 章节或 references（不凭 AI 知识猜）
+- 文件路径规划表必须给出完整相对路径（禁止模糊描述）
+- 样式映射必须交叉验证 `platform/theme-variables-element-plus.md` 中变量确实存在
+- §pitfalls 叙事列表逐条核对不可跳过
+- 用户审批门禁不可跳过
+- plan.md 不包含 TDD 步骤编排（那是 tasks 的职责）
+- 必须使用中文进行编排与报告

package/packages/lcap-frontend-library/commands/migrate.red.md

@@ -0,0 +1,160 @@
+---
+description: Phase RED——将 spec.md 中的 Vue2 行为精确编码为 Vitest 单测 + Playwright E2E 测试，确认测试全部 FAIL，证明测试有意义且目标已定义。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+用户输入为资产名称（如 `cw_audio_view`）。若为空，展示 `specs/manifest.md` 中所有 tasks-ready 状态的资产供选择。
+
+## 必要知识（子集 Read）
+
+- **§process-e2e** — storyId、选择器、pageerror 规则（component E2E）
+- **`references/lcap-extension-component/workflow-guardrails.md`** — 测试分层
+
+位于 `workflows/migrate/knowledge-base.md`（§process-e2e）。
+
+## 核心纪律
+
+> **本阶段的唯一目标：将 Vue2 行为翻译为测试代码。**
+> 测试 = 行为的形式化编码 = 迁移的完成标准定义。
+> 测试 FAIL = 行为尚未实现（这是预期结果）。
+
+## 禁止条款
+
+- ❌ 写任何生产代码（哪怕一行 api.ts、一行 index.vue）
+- ❌ 跳过 spec.md 中记录的行为不写测试
+- ❌ 写"容易通过"的弱断言（如 `expect(wrapper.exists()).toBe(true)`）
+- ❌ 为了"好实现"而降低测试要求
+- ❌ 在测试中写死实现细节（测试应验证行为，不锁定实现方式）
+- ❌ 对 logic / shared-composable 资产编写 E2E 测试
+
+---
+
+## 工作流程
+
+### 步骤 0：读取资产类型
+
+1. 从 `specs/manifest.md` 读取当前资产的「类型」列
+2. 打开本文「资产类型分支」，**仅**执行该分支步骤
+3. 禁止执行其他类型步骤（例：logic 禁止 E2E / ideusage / §alignment-checklist）
+
+### 0. 前置确认
+
+1. 从 `specs/manifest.md` 确认资产状态为 `📋 tasks-ready`
+2. 读取 `specs/<NN>-<资产名>/spec.md`（Vue2 行为真值）
+3. 读取 `specs/<NN>-<资产名>/plan.md`（文件路径表 + 测试层标注）
+4. 读取 `specs/<NN>-<资产名>/tasks.md`（Phase RED 任务组 + 行为等价矩阵）
+5. 更新 `specs/manifest.md`：状态 → `🔴 red-in-progress`
+6. 从 manifest 读取资产「类型」，决定测试路径与是否编写 E2E
+
+### 测试路径（按资产类型）
+
+| 类型 | Vitest 路径 | E2E |
+|------|-------------|-----|
+| component | `src/components/<name>/__tests__/index.spec.ts` + `e2e/<name>.spec.ts` | 必需 |
+| logic | `src/logics/__tests__/<name>.spec.ts` | **禁止** |
+| shared-composable | plan 指定的 `src/composables/__tests__/...` | **禁止** |
+
+logic RED 优先级：P1 参数 nasl.* → P2 返回值边界 → P3 泛型/rest → P4 依赖 mock。
+
+### 1. 检查测试依赖
+
+```bash
+npm list @vue/test-utils jsdom
+```
+若未安装：`npm install -D @vue/test-utils jsdom`
+
+### 2. 编写 Vitest 单元/交互测试
+
+按 tasks.md Phase RED 任务组的顺序编写。
+
+**职责分层**（workflow-guardrails 第 8 条，严格遵守）：
+
+| Vitest 允许 | Vitest 禁止 |
+|-------------|-------------|
+| DOM 结构（节点存在/class/attribute/data-testid） | `getComputedStyle` 取值 |
+| Props 响应式（含动态 `element.style.xxx` 验证） | Canvas/SVG 渲染输出断言 |
+| 事件 emit（参数正确性、触发条件） | 元素尺寸/位置断言 |
+| 纯逻辑（composable 返回值） | 任何需要真实浏览器渲染的断言 |
+| Slot 渲染（作用域变量传递） | |
+| $attrs 透传 | |
+
+**测试编写规则**：
+- 每个 describe/it 名称可追溯到 spec.md 中的具体条目
+- 按 tasks.md 中矩阵行号注释溯源：`// 矩阵 #3: Events.onPlay`
+- 断言必须严格到能区分"正确实现"与"错误实现"
+
+**测试文件路径**：plan.md 中规划的 `src/components/<name>/__tests__/index.spec.ts`
+
+### 3. 编写 E2E 测试
+
+**storyId 确认**（→ §process-e2e）：
+1. stories 文件 `export default { title: '...' }` 使用纯 kebab-case
+2. storyId = `<title-kebab>--<export-name-kebab>`
+3. E2E 一律用 `/iframe.html?id=<storyId>&viewMode=story` 访问
+
+**E2E 必须包含的监听**：
+```typescript
+const errors: string[] = [];
+page.on('pageerror', (err) => errors.push(err.message));
+page.on('console', (msg) => {
+  if (msg.type() === 'error' && !msg.text().includes('404') && !msg.text().includes('net::ERR')) {
+    errors.push(msg.text());
+  }
+});
+// ... 访问 story 页面 + 功能验证 ...
+expect(errors).toEqual([]);
+```
+
+**E2E 编写规则**：
+- 每个 test 必须有明确 `expect()` 断言
+- 选择器策略按 §process-e2e 优先级
+- E2E 测试文件：plan.md 中规划的 `e2e/<name>.spec.ts`
+
+### 4. 运行测试确认 RED 状态
+
+```bash
+npm run test
+```
+
+**预期结果**：测试失败（exit ≠ 0），因为生产代码还未写。
+
+**异常处理**：
+- 若测试意外全部通过 → 断言太宽泛，必须加强断言
+- 若测试报"模块未找到" → 正常（组件文件不存在），记录为 RED 状态
+- 若测试报语法错误 → 修复测试代码本身的语法问题
+
+### 5. 填充行为等价矩阵
+
+更新 `specs/<NN>-<资产名>/tasks.md` 中的行为等价矩阵：
+- "RED 测试编码"列填充测试文件路径 + 行号
+- 确认每行都有对应测试（无空行）
+
+### 6. 标记完成
+
+- tasks.md Phase RED 任务组全部标记 [x]
+- 更新 `specs/manifest.md`：状态 → `🔴 red-done`
+
+### 7. 报告
+
+输出：
+- Vitest 测试用例数
+- E2E 测试用例数
+- 行为等价矩阵覆盖率（已编码/总数）
+- `npm run test` 输出摘要（多少个测试 FAIL）
+- 下一步指引：`/migrate.green <资产名>` 开始实现代码
+
+---
+
+## 关键规则
+
+- **RED 阶段不写生产代码**：这是 TDD 的数学保证基础——测试先于代码存在
+- **测试必须可追溯**：每个测试用例 → tasks.md 矩阵行 → spec.md 行为条目
+- **测试 FAIL 是成功**：RED 的成功标准是"测试存在且 FAIL"
+- **矩阵无空行**：spec.md 中每个有调用点的行为必须有对应测试
+- **职责分层严格执行**：Vitest 禁止做 E2E 的事（样式/尺寸），E2E 禁止做 Vitest 的事（逻辑断言）
+- 必须使用中文进行状态更新与报告

package/packages/lcap-frontend-library/commands/migrate.scan.md

@@ -0,0 +1,151 @@
+---
+description: 扫描 Vue2 源码库，识别所有待迁移资产（组件 + 逻辑），创建/检测 Vue3 目标工程，初始化迁移清单 manifest.md。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前**必须**充分考虑用户输入。用户输入通常包含：
+
+- Vue2 源码库路径（如 `/path/to/cw_audio_library`）
+- 输出目录（可选，默认 cwd）
+- 指定迁移范围（可选，如"只迁移 audio 相关组件"）
+
+**输入为空**时报错：「请提供 Vue2 依赖库源码路径」。
+
+## 必要知识（子集 Read，禁止 Read KB 全文）
+
+- **§process-scaffold** — 工程创建与 scaffold 脚本
+- **§process-asset-types** — 三资产类型与 depends_on
+- **§stories-truth** — Block/Example 溯源（component 扫描）
+- **§process-doc** — manifest 职责
+- **§logics-boundary** — 扫 logics/ 时；必要时 Read `references/nasl-logic-authoring/SKILL.md` 识别 @NaslLogic
+
+以上章节均位于 `workflows/migrate/knowledge-base.md`。
+
+> **scan 为库级命令**，无 per-asset 步骤 0；资产类型在扫描阶段写入 manifest，供后续资产级命令使用。
+
+## 工作流程
+
+### 1. 解析输入
+
+| 要素 | 提取规则 | 示例 |
+|------|----------|------|
+| **sourceDir** | Vue2 依赖库源码根目录（必填） | `/path/to/cw_audio_library` |
+| **outputDir** | 输出目录（默认 cwd） | `./output` |
+| **scope** | 指定迁移范围（默认全部） | `[cw_audio_view, cw_audio_record]` |
+| **库名** | 从 sourceDir 的 package.json 或目录名提取 | `cw_audio_library` |
+| **中文标题** | 从 package.json title/description 或用户指定 | `音频组件库` |
+
+**命名约束**：库名 `--name` 参数仅允许小写字母与下划线。
+
+### 2. 全景扫描（→ §stories-truth）
+
+扫描 `sourceDir`，识别：
+
+**视图组件**（含 `api.ts`/`api.yaml` + `index.vue` 的目录）：
+- 组件目录路径
+- Props / Events / Methods / Slots 数量（快速评估复杂度）
+- Mixin 依赖列表
+- 第三方库依赖
+
+**逻辑函数**（`logics/` 下具有 `@NaslLogic` 导出的文件）：
+- 函数名、参数签名
+- 依赖的工具函数
+
+**共享依赖**：
+- Mixin 全量方法清单 + 各方法被引用次数
+- 第三方 dependencies 及版本
+- 全局注册的组件/指令
+
+**Stories 真值定位**（→ §stories-truth）：
+- 判定源项目类型（Vite 工程 / 旧工程）
+- Vite 工程：`block.stories.js/.ts` + `example.stories.js/.ts`
+- 旧工程：`docs/blocks.md` + `docs/examples.md`
+
+**复杂度评估**（每资产）：
+- HIGH：Mixin ≥ 3 或 Props ≥ 8 或第三方库 ≥ 2
+- MEDIUM：1-2 Mixin 或有第三方库
+- LOW：无 Mixin，Props ≤ 3，无第三方
+
+### 2.5 识别 shared-composable（→ §process-asset-types）
+
+对每个 Mixin 文件统计被哪些组件 import：
+
+- 引用数 ≥ 2 → manifest 新增一行：类型 `shared-composable`，资产名 = mixin 基名，`depends_on` 空
+- 引用数 = 1 → 不新增资产；在该 component 的 Mixin 依赖列标注「内联 composable」
+
+对每个 component，若依赖 shared-composable 资产，填写 `depends_on` 列（逗号分隔资产名）。
+
+### 3. 环境预检
+
+| 检查项 | 命令 | 失败处理 |
+|---|---|---|
+| outputDir 可写 | `mkdir -p <outputDir>` | 自动创建 |
+| Node.js 版本 | `node --version`（≥18） | 报错提示 |
+
+### 4. 创建/检测目标 Vue3 工程（→ §process-scaffold）
+
+目标库 scaffold 与 create flow 的 library-only / library-and-asset 使用同一 `create-extension-project.sh` + `setup-extension-project.mjs`。
+
+**若目标工程不存在**：
+
+```bash
+bash <skill>/scripts/bash/create-extension-project.sh \
+  --name "<库名>" --title "<中文标题>" \
+  --target-dir "<outputDir>" \
+  --template vue3
+
+# stdout: libraryDir=<outputDir>/<库名>
+npm install --prefix "<outputDir>/<库名>"
+```
+
+**若目标工程已存在**：
+
+```bash
+node <skill>/scripts/node/setup-extension-project.mjs "<工程目录绝对路径>"
+npm install --prefix "<工程目录绝对路径>"
+```
+
+**验证**：`npm run dev` 可启动 Storybook。
+
+**Playwright 浏览器适配**：工程创建/setup 后，**必须**立即检查系统可用浏览器并配置 `playwright.config.ts` 的 `channel`：
+1. 检查系统浏览器（如 `which google-chrome`、检查 `/Applications/Google Chrome.app`、`which microsoft-edge` 等）
+2. 在 `playwright.config.ts` 的 `projects[0].use` 中取消注释并设置 `channel: '<检测到的浏览器>'`（如 `'chrome'`、`'msedge'`）
+3. **禁止** `npx playwright install`——必须使用系统已安装的浏览器
+
+### 5. 初始化迁移清单
+
+在 `<工程目录>/specs/` 下创建 `manifest.md`，按 `templates/migration-manifest-template.md` 格式：
+
+- 所有已识别资产填入表格（含 shared-composable 行）
+- 列含：类型、推荐序号、depends_on、状态均为 `⏳ pending`
+- 库级状态：`library_status: ⏳ in-progress`
+- 计算推荐迁移顺序（shared → logic → component，拓扑排序；环则报错终止）
+- 写入「推荐迁移顺序」节
+- 复杂度评估已标注
+- 当前阶段均为 `—`
+
+### 6. 报告
+
+输出：
+- 检测到的库信息（名称、类型、组件数、逻辑函数数）
+- 扫描发现的资产清单（表格：名称/类型/复杂度/Stories来源/Mixin依赖）
+- 目标工程状态（新建 / 已存在已补全）
+- 测试基础设施状态（vitest ✓ / playwright ✓ / storybook ✓）
+- 迁移清单路径
+- 推荐迁移顺序表 + **首个应迁移资产名**（推荐序号 1）
+- 下一步指引：`/migrate.spec <资产名>` 对第一个资产提取行为真值
+
+## 关键规则
+
+- 本阶段**只读不写代码**（仅创建工程骨架和迁移清单文件）
+- 组件名命名约束：仅允许小写字母与下划线
+- Stories 来源必须按 §stories-truth 规则确定，不可猜测
+- 工程创建必须使用指定脚本（→ §process-scaffold），不可手动 `npm init`
+- 若 scope 参数指定了范围，仅将范围内资产纳入清单
+- 所有文档落入工程内部 `specs/` 目录
+- 必须使用中文进行报告输出

package/packages/lcap-frontend-library/commands/migrate.spec.md

@@ -0,0 +1,144 @@
+---
+description: 从 Vue2 源码中完整提取单个资产的行为真值——Props/Events/Methods/Slots/响应式/生命周期/Mixin调用点/第三方集成/Stories，产出纯事实文档，禁止推断与转换建议。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+用户输入为资产名称（如 `cw_audio_view`）。若为空，展示 `specs/manifest.md` 中所有 pending 状态的资产供选择。
+
+## 必要知识（必须在执行前 Read，不可跳过）
+
+1. **`workflows/migrate/knowledge-base.md` 全文** — 仅用于提取 Vue2 行为真值与 stories 溯源
+2. **logic 资产额外**：`references/nasl-logic-authoring/SKILL.md` — 识别 @NaslLogic 元数据
+
+## 核心纪律
+
+> **只记录、不判断。"它现在做什么" ≠ "它应该怎么转"。**
+
+> 本命令的认知模式是"观察者"——完整、精确、客观地记录 Vue2 源码的行为事实。
+> 任何转换方案、质量评价、优化建议都属于 migrate.plan 的职责。
+
+## 禁止条款
+
+- ❌ 按 KB 编写 Vue3 转换方案、替换代码或 pitfalls 应对
+- ❌ 评价 Vue2 代码质量
+- ❌ 推断源码未写出的行为
+- ❌ 判断某个行为"不重要可以不迁移"
+- ❌ 遗漏 Mixin 方法（必须全量列出再标注是否有调用点）
+- ❌ 跳过 stories 真值提取
+- ✅ component：仅使用 KB 中 Instructions、Stories 溯源（§stories-truth）、Mixin 清单、第三方集成相关节
+- ✅ logic：仅提取 @NaslLogic 元数据、参数/rest/泛型、返回值与边界行为（参照 nasl-logic-authoring）
+- ✅ shared-composable：仅提取 Mixin 导出方法、副作用注册点、各组件调用契约
+
+> 全文 Read KB 后，按 KB §asset-applicability 跳过不适用章节（logic 跳过 §stories-truth 等）。
+
+---
+
+## 工作流程
+
+### 步骤 0：读取资产类型
+
+1. 从 `specs/manifest.md` 读取当前资产的「类型」列
+2. 打开本文「资产类型分支」，**仅**执行该分支步骤
+3. 禁止执行其他类型步骤（例：logic 禁止 E2E / ideusage / §alignment-checklist）
+
+### 1. 确认资产
+
+- 从 `specs/manifest.md` 确认资产存在且状态为 `⏳ pending`
+- 读取 manifest 该资产 `depends_on` 列；若非空，逐项检查依赖资产状态：
+  - 全部为 `✅ verified` → 继续
+  - 存在 `🚫 blocked` → 使用 AskUserQuestion 确认是否跳过阻塞依赖
+  - 存在未 verified 且非 blocked → **报错终止**，提示先迁移依赖资产
+- 读取 manifest「类型」列，后续 spec 结构按类型分支
+- 若未指定资产名：列出所有 pending 资产，使用 **AskUserQuestion** 让用户选择
+- 确定 Vue2 源码中该资产的完整路径
+
+### 2. 完整读取 Vue2 源码
+
+读取该资产在 Vue2 库中的**全部**源文件：
+
+**组件资产**：
+- `index.vue`（template + script + style 全部内容）
+- `api.ts` / `api.yaml`（接口定义）
+- `stories/block.stories.js`（或 .tsx/.jsx）
+- `stories/example.stories.*`（若存在）
+- 所有引用的 Mixin 文件（完整内容）
+- 关联的 CSS/SCSS/Less 文件
+- `index.ts`（桶文件导出）
+- `install.ts` / `plugin.ts`（全局注册，若存在）
+
+**逻辑资产**：
+- 逻辑函数文件（含 JSDoc 元数据）
+- 关联的类型定义文件
+- 依赖的工具函数
+
+### 3. 系统性提取行为规格
+
+从源码中提取以下维度，写入 spec.md（**必须按 `templates/migration-spec-template.md` 格式输出**）：
+
+**组件规格**：
+
+| 维度 | 提取内容 |
+|------|----------|
+| Props | 名称、类型（nasl.*）、默认值（以 api.yaml 为准）、是否双向绑定、验证规则 |
+| Events | 事件名（on+PascalCase）、参数签名（单一 event 对象）、触发条件 |
+| Methods | 方法名、参数、返回值、副作用描述 |
+| Slots | 插槽名、作用域变量（Current<T> 模式）、用途 |
+| 响应式状态 | data/computed 关键状态及其依赖关系链 |
+| 生命周期 | mounted/destroyed/watch 中的初始化与清理逻辑 |
+| Mixin 调用点 | 每个 Mixin 的每个方法在本组件中的实际调用位置 |
+| 第三方集成 | 库名、版本、初始化方式、配置项、销毁方式 |
+| 全局注册 | install 中注册的组件名与对应导出 |
+
+**逻辑规格**（参照 nasl-logic-authoring）：
+- 函数名 / JSDoc 元数据（@NaslLogic @title @description）
+- 参数列表（名称、类型 nasl.*、是否 rest）
+- 返回值类型
+- 泛型与 @typeParam
+- 依赖的工具函数
+
+**shared-composable 规格**：
+
+| 维度 | 提取内容 |
+|------|----------|
+| Exported 方法 | 方法名、参数、返回值、副作用 |
+| 调用点 | 哪些组件在何处调用（引用 manifest） |
+| 副作用 | listener / observer / timer 注册与预期 teardown |
+| 纯函数 | 无副作用的方法清单 |
+
+### 4. 记录 Stories 真值（→ §stories-truth）
+
+**完整记录**（非摘要）block.stories 和 example.stories 的源码内容：
+- 每个 export 的 name、render/template
+- 使用的 Vue2 平台标签（u-button 等，原样记录，不做替换建议）
+- 变量、事件绑定（原样记录）
+
+### 5. 输出 spec.md
+
+写入 `specs/<NN>-<资产名>/spec.md`（若目录不存在则创建）。
+
+### 6. 更新状态
+
+更新 `specs/manifest.md`：该资产状态 `⏳ pending` → `🔍 spec-done`
+
+### 7. 报告
+
+输出：
+- 资产名称与类型
+- spec.md 路径
+- 行为维度统计（N props / M events / K methods / ...）
+- 复杂度初判（高/中/低，基于 Mixin 数 + 第三方库 + Props 数量）
+- 下一步指引：`/migrate.plan <资产名>` 制定转换策略
+
+## 关键规则
+
+- Vue2 源码是行为的唯一真值——本命令只做"翻译"（代码→结构化文档），不做"创作"
+- Mixin 全量方法必须列出，即使看起来"不会用到"——判断调用点是客观事实，不是主观猜测
+- Prop 默认值以 api.yaml 为准（api.yaml 是 LCAP 平台的权威来源）
+- Stories 原样记录，包括 Vue2 特有标签——替换决策属于 plan 阶段
+- spec.md 中允许标注"注意事项"（如边界条件、已知 hack），但不允许写解决方案
+- 必须使用中文输出