lcap-frontend-library 0.0.1

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

@@ -0,0 +1,179 @@
+---
+description: 将 plan.md 展开为 TDD 结构化执行步骤，初始化行为等价矩阵——确保 spec.md 中每个行为有对应的测试任务和实现任务，形成可追踪的等价性保证链。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+用户输入为资产名称（如 `cw_audio_view`）。若为空，展示 `specs/manifest.md` 中所有 planned 状态的资产供选择。
+
+## 必要知识（子集 Read）
+
+- **§process-matrix** — 行为等价矩阵结构与三类型行差异
+- **§process-e2e** — storyId/选择器（**仅 component** E2E 任务）
+
+位于 `workflows/migrate/knowledge-base.md`。
+
+## 核心职责
+
+本命令回答 **"How & When"**——具体步骤是什么？按什么顺序？每步怎么验收？
+
+这与 migrate.plan 的职责严格分离：
+- plan = "Why & What"（转换决策、技术路线）
+- tasks = "How & When"（执行调度、验收标准）
+
+---
+
+## 工作流程
+
+### 步骤 0：读取资产类型
+
+1. 从 `specs/manifest.md` 读取当前资产的「类型」列
+2. 打开本文「资产类型分支」，**仅**执行该分支步骤
+3. 禁止执行其他类型步骤（例：logic 禁止 E2E / ideusage / §alignment-checklist）
+
+### 1. 确认资产与前置
+
+- 从 `specs/manifest.md` 确认资产状态为 `🔄 planned`
+- 读取 `specs/<NN>-<资产名>/spec.md`（Vue2 行为真值）
+- 读取 `specs/<NN>-<资产名>/plan.md`（转换策略 + 文件路径表）
+
+### 2. 初始化行为等价矩阵
+
+从 spec.md 中提取**全部行为条目**，每个条目对应矩阵一行：
+
+**提取规则**：
+- 每个 Prop 的响应性行为 = 1 行
+- 每个 Event 的触发行为 = 1 行
+- 每个 Method 的暴露 = 1 行
+- 每个 Slot 的渲染 = 1 行
+- 每个有调用点的 Mixin 方法 = 1 行
+- 每个生命周期关键行为（初始化/销毁/watch）= 1 行
+- 第三方集成的初始化与销毁 = 各 1 行
+
+**logic 矩阵行**：每个参数行为、返回值、泛型/rest、边界用例、依赖工具函数行为各 1 行（维度 Params/Return/Generic/Edge）。
+
+**shared-composable 矩阵行**：每个 exported 方法、副作用注册/teardown、调用契约各 1 行。
+
+**矩阵初始状态**：
+
+| # | Vue2 行为（spec.md 条目） | RED 测试编码 | GREEN 实现 | 等价状态 |
+|---|--------------------------|-------------|-----------|---------|
+| 1 | [具体行为描述] | — | — | ⬜ |
+| 2 | ... | — | — | ⬜ |
+
+### 3. 编排 Phase RED 任务组
+
+**资产类型分支**（manifest.类型）：
+
+- **component**：现有 Vitest P1–P5 + E2E
+- **logic**：仅 Vitest（`src/logics/__tests__/`），**禁止** E2E 任务；优先级 P1 参数 → P2 返回值 → P3 泛型/rest → P4 依赖 mock
+- **shared-composable**：仅 Vitest 纯逻辑，**禁止** E2E
+
+根据 plan.md 的"文件路径与模块化规划"表中的**测试层**标注，安排测试编写顺序：
+
+**Vitest 单测**（按优先级）：
+- P1: Props 响应性（默认值、类型、双向绑定 update:value）
+- P2: Events 触发（emit 参数正确性、触发条件）
+- P3: Composable 纯逻辑（返回值验证）
+- P4: Slot 渲染（作用域变量传递）
+- P5: $attrs 透传
+
+**职责分层判定**（→ `references/lcap-extension-component/workflow-guardrails.md` 第 8 条）：
+- 标注 `Vitest(返回值)` → 纯逻辑，直接断言返回
+- 标注 `Vitest(调用参数)` → 调用浏览器 API，仅 mock 验证调用参数
+- 标注 `Vitest(DOM) + E2E` → DOM 操作，Vitest 验证结构，E2E 验证渲染
+
+**E2E 测试**：
+- 列出 plan.md 中规划的每个 example.stories export
+- 确定 storyId（→ §process-e2e）
+- 标注验证目标
+
+**RED 验收标准**：
+```bash
+npm run test → exit ≠ 0（测试存在且全部 FAIL）
+```
+
+### 4. 编排 Phase GREEN 任务组
+
+按 plan.md 文件路径表的模块顺序编排实现步骤：
+
+1. 创建骨架（按类型）：
+   - component：`create-component-files.sh --library-dir ... --name ... --title ... --type pc|h5|both`
+   - logic：`create-logic-files.sh`（同上参数）
+   - shared-composable：按 plan 路径 Edit 创建 composable + 测试（无 scaffold）
+2. component 继续 api.ts → ideusage → …；logic 仅实现函数体 + index 导出；shared 仅 composable 实现
+3. api.ts（→ references/lcap-extension-component，component only）
+4. ideusage.json（→ references/lcap-extension-component，component only）
+5. composables/useXxx.ts（→ KB §mixin-composable）
+6. index.vue template + logic（→ KB §implementation-order / §mixin-composable）
+7. stories/block.stories.js（→ KB §stories-truth）
+8. stories/example.stories.js
+9. CSS/主题适配（→ KB §css-vars）
+10. 迭代至测试通过
+
+**GREEN 验收标准**：
+```bash
+npm run test → exit 0（全部 PASS）
+```
+
+### 5. 编排 Phase CHECK 执行清单
+
+> migrate.check = 等价审计 + 产物验证。本节供 tasks 内追溯，不在 RED/GREEN 阶段执行。
+
+| 序号 | 验证项 | component | logic | shared-composable |
+|:--|:---|:---|:---|:---|
+| V1 | 单测门禁 | `npm run test` exit 0 | 同左 | 同左 |
+| V2 | 构建门禁 | `npm run build` exit 0 | 同左 | 同左 |
+| V3 | E2E 门禁 | `npm run test:e2e` exit 0 | N/A | N/A |
+| V4 | 行为等价矩阵 | 无 ❌ 行 | 同左 | 同左 |
+| V5 | 等价审计维 | 五维（对齐/API/合规/Storybook/机制差异） | 三维 L1–L3 | 三维 S1–S3 |
+| V6 | 产物验证 | 4 项清单（→ migrate.check §C） | build only | build only |
+| V7 | 跨资产回归 | 全量 test + e2e | 全量 test | 全量 test |
+
+### 6. 复杂度自适应
+
+根据 plan.md 中的复杂度评估调整任务粒度：
+
+**LOW**（Props ≤ 3，无 Mixin，无第三方）：
+- RED 合并为 1-2 个任务
+- GREEN 合并为 2-3 个任务
+
+**MEDIUM**（1-2 Mixin，有第三方库）：
+- RED 拆为 Vitest + E2E 两个独立任务
+- GREEN 按模块逐步
+
+**HIGH**（Mixin ≥ 3，Props ≥ 8，第三方库 ≥ 2）：
+- RED 按 P1-P2 / P3-P5 / E2E 拆为 3 个任务
+- GREEN 每个 composable 独立任务
+
+### 7. 输出 tasks.md
+
+写入 `specs/<NN>-<资产名>/tasks.md`（按 `templates/migration-tasks-template.md` 格式）。
+
+### 8. 更新状态
+
+更新 `specs/manifest.md`：该资产状态 `🔄 planned` → `📋 tasks-ready`
+
+### 9. 报告
+
+输出：
+- 行为等价矩阵行数（= spec 行为总数）
+- Phase RED 任务数
+- Phase GREEN 任务数
+- 预估 RED/GREEN 难度
+- 下一步指引：`/migrate.red <资产名>` 开始编写测试
+
+---
+
+## 关键规则
+
+- **矩阵完整性**：spec.md 中每个有调用点的行为必须在矩阵中有对应行（无遗漏）
+- **结构约束**：RED 组全部完成 → 才能进入 GREEN 组（铁律，非建议）
+- **职责分层**：按 workflow-guardrails 第 8 条严格判定 Vitest vs E2E 职责
+- **不做实现决策**：任务描述中引用 plan.md 的决策，不在此重新判断
+- **storyId 必须可确认**：E2E 任务中的 storyId 必须可从 stories title 推导（→ §process-e2e）
+- 必须使用中文输出

package/packages/lcap-frontend-library/commands/speckit.create.md

@@ -0,0 +1,201 @@
+---
+description: 初始化 LCAP 扩展依赖库工程环境（检测 paradigm/asset → init-context → 按需创建项目/组件/逻辑骨架或列出现有资产）。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+在继续之前**必须**充分考虑用户输入（若不为空）。用户输入为自然语言，通常包含以下信息的一项或多项：
+
+- 组件功能描述（如「水印组件，支持设置文字、旋转角度、透明度」）
+- 逻辑功能描述（如「日期格式化逻辑，支持多种输出格式」）
+- 依赖库名称（如「库名叫 watermark」）
+- 目标目录（如「在 /path/to/dir 下创建」）
+- 修改意图（如「给水印组件增加图片水印功能」——此类由 evolve flow 路由，本命令在 paradigm=evolve 时处理）
+
+Flow 传入的上下文（由 create/evolve flow 约定，写入 Agent 内部状态）：
+
+- `paradigm`: `create` | `evolve`
+- `asset`: `library` | `component` | `logic`（library 仅 create 且用户仅要建库时）
+
+## 工作流程
+
+### 1. 解析用户输入，确定要素
+
+从用户输入中提取：
+
+| 要素 | 提取规则 | 示例 |
+|------|----------|------|
+| **资产短名** | 用户明确指定时直接使用；否则从功能描述中提取核心词，转为小写下划线格式 | 「二维码组件」→ `qr_code`；「水印」→ `watermark` |
+| **资产中文标题** | 用户明确指定时直接使用；否则取功能描述中的核心中文名词 | `qr_code` → 「二维码」；`watermark` → 「水印」 |
+| **目标父目录（targetDir）** | 用户明确指定路径时使用；建库时**不含库名** | 「在 ~/projects 下」→ `~/projects` |
+| **template** | 无提及默认 vue3；vue2 可覆盖 | vue2 → `vue2`；**react → 报错（暂不支持）** |
+| **libraryDir** | 建库脚本 stdout `libraryDir=` 或 `targetDir/libraryName` | scaffold/setup 必填 |
+
+**命名约束**：资产短名（`--name`）**仅允许小写字母与下划线**（如 `qr_code`、`watermark`、`format_date`）。
+
+**输入为空**时报错：「请提供功能描述或依赖库名称」。
+
+若 flow 未传入 `asset`，按以下规则解析：
+
+| 用户意图 | asset |
+|----------|-------|
+| 仅初始化依赖库、不创建组件/逻辑 | `library` |
+| 明确要创建逻辑函数 | `logic` |
+| 其他（默认） | `component` |
+
+### 2. 资产与 init-context 检测
+
+在**当前工作目录**（或用户指定目录）按以下顺序检测：
+
+| 步骤 | 检查 | 结果 |
+|------|------|------|
+| ① 是否在 LCAP 项目中 | `package.json` 存在 且 `(dev)dependencies` 含 `@lcap/builder` | 是 / 否 |
+| ② 解析 `asset` | flow 传入或按 §1 规则推断 | `library` / `component` / `logic` |
+| ③ 资产是否存在 | component：`src/components/<短名>/` 目录存在；logic：`src/logics/` 下目标 `@NaslLogic` 导出已存在 | 是 / 否 |
+
+**分支判定**（输出 `init-context` 后按对应章节执行）：
+
+**若 `paradigm=evolve`：**
+
+| 资产存在 | init-context | 否则 |
+|----------|--------------|------|
+| 是 | `asset-evolve` | — |
+| 否 | — | **报错退出**：「目标资产不存在，请使用 create flow」 |
+
+**若 `paradigm=create`：**
+
+| LCAP 项目 | asset | 资产存在 | init-context | 否则 |
+|-----------|-------|----------|--------------|------|
+| 否 | `library` | — | `library-only` | — |
+| 否 | `component` / `logic` | — | `library-and-asset` | — |
+| 是 | `component` / `logic` | 否 | `asset-append` | — |
+| 是 | `component` / `logic` | 是 | — | **报错退出**：「资产已存在，请使用 evolve flow」 |
+| 是 | `library` | — | `library-only`（仅 setup，不 scaffold） | — |
+
+输出检测结果（`paradigm`、`asset`、`init-context`）后按 init-context 分支执行。
+
+### 3. init-context = `library-only`
+
+当前目录不是 LCAP 扩展项目（或已在 LCAP 项目中但用户仅要建库），只创建依赖库工程：
+
+```bash
+# 创建项目（含 setup-extension-project.mjs 自动执行）
+bash <skill-abs>/scripts/bash/create-extension-project.sh \
+  --name "<libraryName>" \
+  --title "<libraryTitle>" \
+  --target-dir "<targetDir>" \
+  --template vue3
+
+# 从 stdout 捕获 libraryDir=... 与 template=...
+npm install --prefix "<libraryDir>"
+```
+
+- **不**调用 `create-component-files.sh` 或 `create-logic-files.sh`
+- 创建完成后**必须**执行 Playwright 浏览器适配（见 §「Playwright 浏览器适配」）
+
+### 4. init-context = `library-and-asset`
+
+当前目录不是 LCAP 扩展项目，需从零创建库并追加首个 component 或 logic：
+
+```bash
+bash <skill-abs>/scripts/bash/create-extension-project.sh \
+  --name "<libraryName>" \
+  --title "<libraryTitle>" \
+  --target-dir "<targetDir>" \
+  --template vue3
+
+# libraryDir 来自 stdout；libraryName 可与 assetName 不同
+npm install --prefix "<libraryDir>"
+
+bash <skill-abs>/scripts/bash/create-component-files.sh \
+  --library-dir "<libraryDir>" --name "<assetName>" --title "<assetTitle>" --type pc
+
+# logic 资产：
+bash <skill-abs>/scripts/bash/create-logic-files.sh \
+  --library-dir "<libraryDir>" --name "<assetName>" --title "<assetTitle>" --type pc
+```
+
+> **资产短名默认与依赖库名称相同**（一个依赖库通常承载一个主组件或逻辑）。
+>
+> 创建完成后**必须**执行 Playwright 浏览器适配（见 §「Playwright 浏览器适配」；logic 资产可跳过 e2e 相关步骤）。
+
+### 5. init-context = `asset-append`
+
+当前目录已是 LCAP 项目，目标 component/logic 尚不存在：
+
+```bash
+node <skill-abs>/scripts/node/setup-extension-project.mjs "<libraryDir>"
+npm install --prefix "<libraryDir>"
+
+bash <skill-abs>/scripts/bash/create-component-files.sh \
+  --library-dir "<libraryDir>" --name "<assetName>" --title "<assetTitle>" --type pc
+# 或
+bash <skill-abs>/scripts/bash/create-logic-files.sh \
+  --library-dir "<libraryDir>" --name "<assetName>" --title "<assetTitle>" --type pc
+```
+
+**基础设施补全说明**：`setup-extension-project.mjs` 是幂等的——已存在的配置不会被覆盖。它确保：
+
+- `playwright.config.ts` 存在
+- `e2e/` 目录存在
+- `package.json` 含 `test:e2e` 脚本
+- `vite.config.mjs` 含 Vitest exclude 配置
+- `@vue/test-utils`、`jsdom` 已在 devDependencies
+
+setup 完成后**必须**立即执行 Playwright 浏览器适配（见下方；logic 资产可跳过 e2e 相关步骤）。
+
+### 6. init-context = `asset-evolve`
+
+当前目录已是 LCAP 项目，目标资产已存在（`paradigm=evolve`）：
+
+```bash
+node <skill-abs>/scripts/node/setup-extension-project.mjs "<libraryDir>"
+npm install --prefix "<libraryDir>"
+```
+
+- **不**调用 `create-component-files.sh` 或 `create-logic-files.sh`
+- **不**创建任何 scaffold 文件
+
+输出现有资产信息：
+
+- **component**：组件目录路径（如 `src/components/watermark/`）；已有文件列表（api.ts、index.vue、stories/、__tests__/ 等）
+- **logic**：逻辑文件路径（如 `src/logics/format_date.ts` 或 `src/logics/index.ts` 中对应导出）；已有测试文件
+- 已有 `specs/` 目录中与该资产相关的历史 spec（供后续阶段参考）
+
+### Playwright 浏览器适配（setup 后立即执行）
+
+在 `library-only`、`library-and-asset`、`asset-append` 分支中，执行 `setup-extension-project.mjs` 后**必须**立即检查系统可用浏览器并配置 `playwright.config.ts` 的 `channel`（component 资产；logic 可跳过）：
+
+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`——必须使用系统已安装的浏览器
+
+### 7. 报告
+
+输出：
+
+- `paradigm`（create / evolve）
+- `asset`（library / component / logic）
+- `init-context`（library-only / library-and-asset / asset-append / asset-evolve）
+- `targetDir`、`libraryDir`（绝对路径）、`template`（建库场景）
+- 资产短名与目录/文件路径
+- 基础设施状态（已完备 / 已补全）
+- **下一步指引**：
+  - `init-context=library-only` → 提示 create flow 在此结束（`npm run dev` 可启），**不**进入 `speckit.specify`
+  - 其他 init-context → 下一步：`/speckit.specify`
+
+## 关键规则
+
+- 资产短名（`--name`）**仅允许小写字母与下划线**，不符合则报错。
+- 所有 bash/node 脚本路径：使用 skill 目录绝对路径（`<skill-abs>/scripts/...`）。
+- **禁止**依赖 Agent 会话 `cd` 调用 scaffold；建库用 `--target-dir`，资产/setup 用 `--library-dir`。
+- **禁止**使用已删除参数 `--project-dir`。
+- 建库**不**调用 `lcap install`（组件库选择暂不在 skill 脚手架范围内）。
+- 用户要求 **react** 依赖库时：**报错**，说明暂不支持，请使用 vue2 或 vue3。
+- 创建完成后，后续 specify/plan/tasks/implement 均以 `libraryDir` 为工程目录。
+- `asset-evolve` 不创建任何 scaffold 文件，仅确认环境并输出现有资产信息。
+- `paradigm=create` 时若目标 component/logic 已存在，**必须**报错并提示走 evolve flow，不得继续 scaffold。

package/packages/lcap-frontend-library/commands/speckit.implement.md

@@ -0,0 +1,88 @@
+---
+description: 基于任务清单与 spec，按顺序实现前端 UI 组件代码。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前请充分考虑用户输入（若不为空）。执行任何操作前，先理解当前工程架构、spec、实现计划与任务清单。
+
+## 必要知识（必须执行，不可跳过）
+
+**实现前必须完整阅读**以下文档，否则易导致实现不符合平台规范、需返工：
+
+- **必读**：`references/lcap-extension-component/SKILL.md`（api.ts 结构、ideusage、block.stories、e2e 规范等）
+- **必读**：`references/lcap-extension-component/implementation-rules.md`（组件实现规则六条及详细说明、实现要点与验收清单）
+- **必读**：`references/lcap-extension-component/workflow-guardrails.md`（工作流护栏：脚本权限、CSS Modules 定位、浮点断言、E2E strict mode、Storybook 事件隔离等）
+- **必读**：`references/frontend-design/SKILL.md`（前端设计与观感：设计取向、版式与动效、配色与字体等，避免泛化 AI 审美；须在符合 LCAP/CodeWave 约束前提下落地）
+- **必读**：`references/lcap-extension-component/` 下的 api.md、ide/*.md（按 idetype 读对应文档）、block.md、platform/slot.md、platform/form.md（表单组件）等
+- **必读**：`LEARNINGS.md`（流程约束，只读）：开始任务前内部比对，遇到已记录场景时主动守护，避免重蹈覆辙
+
+严格按 api.ts、ideusage、block.stories、上述实现规则与 frontend-design 指引编写组件代码，不得违背 LCAP/CodeWave 扩展组件约定；**未阅读即动手写代码视为违规**。
+
+## 工作流程
+
+1. **定位任务**：在 `specs/<id>-<name>/` 下找到 `tasks.md`（或 `tasks/*.md`），按依赖顺序确定待办任务。
+
+2. **按序实现**：逐项执行任务，每项完成后自检验收列表。**路径以 `tasks.md` 与 `plan.md`「文件路径与模块化规划」为准**：每条任务的「产出」须落在约定路径；失败时优先核对是否**放错目录**，勿随意改路径迁就 import。**功能内聚**：优先实现 `plan.md`「内置 UI 控件清单」中的交互，勿默认省略再用 Method/插槽兜底。
+   - 创建/**修改**组件文件（Vue 单文件组件等）——evolve 时任务通常是修改已有文件而非创建新文件
+   - 实现 Props、Events、Slots 与 spec 接口定义一致
+   - 实现模板、样式、方法（如 exportPng）；复杂逻辑在 `composables/`、`utils/` 等 **plan.md 已规划路径**
+   - **example.stories**：在组件目录下 `stories/example.stories.{js|tsx|jsx}` 中为**每个功能**添加一个 demo story，与 spec 验收一一对应，供本地调试与 e2e 使用
+   - **测试**：每个功能任务完成后，使用 Vitest 编写单元/交互测试；**e2e**：扩展工程**须**具备 `package.json.scripts.test:e2e`（见 `setup-extension-project.mjs` 或等价配置）。须遵循**探测优先**：**必须先**执行 `npm run test:e2e`，**禁止**未执行就下结论。针对 **example.stories 中各功能 demo** 编写 e2e；**`npm run test` 与 `npm run test:e2e` 均须通过**；失败则修复代码、配置或测试后重跑直至通过，再标记任务完成
+   - 完成一项后再进入下一项，禁止跳过依赖
+
+3. **状态更新**：执行过程中**必须**同步更新 `tasks.md` 与 `plan.md` 中的任务状态：
+   - 开始执行某任务时：将该任务状态改为 `[>] 执行中`
+   - 任务完成并通过验收后：将该任务状态改为 `[X] 已完成`
+   - 未开始的任务保持 `[ ] 待执行`
+
+4. **验收**：每项任务完成后，对照 spec 与 plan.md 的验收标准逐条检查，未通过则修正后再继续；执行 `npm run build` 命令无异常则继续，反之根据报错修复问题。全部任务完成后、提交前可对照 `templates/component-self-check.md` 做最后一轮自检。
+
+5. **测试与自动修复**：每项功能任务完成后，必须完成以下测试并**在失败时自动修复**：
+   - **单元与交互测试（Vitest）**：
+     - **单测前检查基础依赖**：执行 `npm run test` 前，先检查项目是否已安装单测基础依赖 `@vue/test-utils`、`jsdom`（可通过 `npm list @vue/test-utils jsdom` 或查看 package.json 的 devDependencies）；若未安装或解析失败（如报 `Failed to resolve import “@vue/test-utils”`），须先执行 `npm install -D @vue/test-utils jsdom`，再执行单测。
+     - **职责边界**：Vitest 仅测试 DOM 结构（节点存在/class/attribute/data-testid）、Props 响应式（含动态内联样式可通过 `element.style.xxx` 验证）、事件 emit、纯逻辑、Slot 渲染、$attrs 透传、条件渲染。**禁止**在 Vitest 中使用 `getComputedStyle`、断言 Canvas/SVG 渲染输出、元素尺寸位置（offsetWidth/getBoundingClientRect 始终为 0）、CSS 渲染效果、滚动行为、动画完成状态。
+     - **Mock 决策原则**：mock jsdom 不支持的 API（Canvas/WebGL/ResizeObserver/IntersectionObserver/getBoundingClientRect/matchMedia/Clipboard 等）是为了**防崩溃 + 验证调用逻辑**。Vitest 仅验证 mock API 被调用时的**参数**是否与 props 对应。**禁止断言 mock 后的返回值**（如 toDataURL 的值）或由其驱动的渲染产出（如 background-image 包含 data:image）——这些在 E2E 中验证。
+     - **样式放置互锁**：静态样式写在 `<style scoped>`，**禁止**为迁就 Vitest 而将 position/pointer-events/z-index 等内联；Vitest 验证 class 存在（`classes().toContain`）和 props 直传的内联值（`element.style.xxx`），渲染效果归 E2E。
+     - **编写测试前必须查看 plan.md「文件路径与模块化规划」表的”测试层”列**：标注为 `Vitest(调用参数)` 的模块，Vitest 仅验证 API 调用参数（mock 后），禁止断言其返回值或渲染产出。
+     - 验证 Props、Methods、计算逻辑等；使用 @vue/test-utils 的 mount、trigger 等验证用户操作与事件
+     - 测试文件放在组件目录或 `__tests__/` 下，如 `qr-code/index.spec.ts`
+     - 执行 `npm run test`，用例需覆盖 spec 验收标准（DOM 结构与逻辑部分）
+   - **端到端测试（Playwright）—— 负责渲染结果与 CSS 效果验证**：
+     - **探测优先**：与 speckit.plan 一致——**必须先**在终端执行 `npm run test:e2e`，**禁止**未执行就下结论。**用例失败、断言失败须修复代码或测试**，不得以「环境」为由不修复。
+     - **E2E 职责**：验证渲染结果（Canvas/SVG 输出、**所有 CSS 样式效果**如 position/pointer-events/z-index/background-image 是否生效、元素尺寸位置）、用户交互完整流程、响应式行为。**样式验证全部归 E2E**。
+     - **脚手架与配置**：若工程由 `create-extension-project.sh` 创建，已含 `scripts/node/setup-extension-project.mjs` 写入的 `playwright.config.ts`、Vitest exclude 配置（e2e 目录不被 vitest 收集）、合并 `.gitignore`、固定 `test` / `test:e2e`及 `e2e/` 目录，执行 `npm install` 后编写 `e2e/` 用例直至通过。否则须完成 **(1) 添加依赖与基础配置**：安装 Playwright（`npm install -D @playwright/test`）；**禁止**使用 `npx playwright install` 安装浏览器。playwright.config.ts 根据系统浏览器配置`channel`为`chrome`、`msedge`等；将 `package.json` 的 `start` 与 `playwright.config.ts` 的 `webServer` 端口策略对齐；可参考 `setup-extension-project.mjs`；**(2) 编写 e2e 测试代码**（见下）；**(3) 配置 `package.json` 的 `test:e2e`**：与初始化一致时使用固定命令（清代理 + `playwright test`）。
+     - **须执行 e2e 时**：使用 Playwright 在真实浏览器中验收每个功能的完整流程（渲染、交互、事件、数据更新等）；**e2e 测试用例须与 spec 验收标准一一对应**
+     - **先有 example.stories**：在组件目录下 `stories/example.stories.{js|tsx|jsx}` 中为各功能添加 demo story，再**针对 example.stories 中的各功能 story** 编写 e2e 测试；访问时 **storyId 遵循 Storybook 规则**：`<kind（kebab-case）>--<story 导出名（kebab-case）>`，如 `funnel-chart-example--default`
+     - **必须监听控制台与页面报错**：在用例中通过 `page.on('pageerror')` 捕获 JS 运行时异常；通过 `page.on('console')` 监听 error 级别日志，**过滤网络资源 404**（如 `msg.text().includes('404')` 或 `msg.text().includes('net::ERR')` 的排除），仅捕获组件自身的 JS 错误
+     - **每个 test 必须有对应断言**：每条用例须包含明确的 `expect(...)` 断言，验证该条验收标准是否达成，禁止只执行操作、不断言结果或仅”确保不崩溃”
+     - e2e 测试文件建议放在 `e2e/` 或项目约定的 e2e 目录，与组件/功能一一对应
+     - 执行 e2e：须**探测执行** `npm run test:e2e`，并修复至通过。
+   - **运行时报错处理**：**`npm run test`、`npm run build` 与 `npm run test:e2e` 均须通过**；若出现错误须**自动修复**并重跑直至通过。禁止在任一项未通过时标记任务完成。
+
+6. **报告**：全部任务完成后，输出已实现任务列表、变更文件路径、测试覆盖情况，以及组件就绪状态。
+
+## 关键规则
+
+- 必须使用中文进行任务编排与回复。
+- 严格按照任务清单的依赖顺序执行，完成一项再进入下一项。
+- 实现内容须符合 spec 与 plan.md 的接口定义与验收标准。
+- 禁止在未阅读任务文件与规范的情况下修改代码。
+- 本项目仅处理前端 UI 组件，不涉及后端、数据库或 API 开发；e2e 须**探测优先**，与 speckit.plan 一致，**直至 `test:e2e` 通过**。
+- **回归安全**：测试全量运行（`npm run test` + `npm run test:e2e`），确保新增/修改不破坏已有功能。evolve（修改已有组件）时，修改后须先确认已有测试仍通过，再编写新增用例。
+
+## evolve
+
+- implement 完成后须全量 regression test（component：`npm run test` + `npm run test:e2e`；logic 仅全量 vitest）
+- implement 前读取 `LEARNINGS.md`；修改已有文件时先确认已有测试仍通过，再编写新增用例
+
+## asset=logic
+
+- 必读 `references/nasl-logic-authoring/SKILL.md`
+- 跳过：api.ts、ideusage、stories、block.stories、e2e
+- 完成条件：`npm run test` + `npm run build` 通过即可
+- evolve：implement 前读取 LEARNINGS；完成后全量 vitest

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

@@ -0,0 +1,79 @@
+---
+description: 基于 spec.md 生成前端 UI 组件的实现计划（plan.md）。
+---
+
+**产物与分工**：生成文件为规范目录下的 **`plan.md`**（与 [spec-kit](https://github.com/github/spec-kit/blob/main/templates/plan-template.md) 命名一致）。模板（`templates/plan-template.md`）负责**结构与章节**；**测试/e2e 的执行级要求**以本文「工作流程」与 SKILL 为准，避免在模板中重复长文。
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+执行前请充分考虑用户输入（若不为空）。执行任何操作前，先理解当前工程架构与规范需求目录中的 spec.md。
+
+## 必要知识
+
+扩展组件实现计划须符合 LCAP/CodeWave 规范。**必须先阅读**以下文档：
+
+- `references/lcap-extension-component/SKILL.md`（api.ts、ideusage、block.stories 等）
+- `references/lcap-extension-component/implementation-rules.md`（组件实现规则六条及详细说明，生成计划时须在实现顺序或验收标准中体现）
+- `references/lcap-extension-component/workflow-guardrails.md`（工作流护栏：样式映射、测试定位、浮点断言、E2E strict mode 等）
+- `references/lcap-extension-component/` 下的 api.md、ide/index.md、block.md 等
+- **`LEARNINGS.md`**（先验知识，只读）：筛选与本组件相关的条目，将可能命中的经验纳入实现计划的「风险与注意事项」中，起到预防作用
+
+生成计划时不得忽略上述规范与实现规则。
+
+## 计划契约（内聚 · 模块化 · 路径）
+
+生成 `plan.md` 时须同时满足下列准则（写入模板对应章节，勿仅用口头概括）：
+
+1. **功能内聚**：若 `spec.md` 定义了**可独立感知的交互能力**（如导入、删除、绘制、缩放、导出等），计划中须落实**组件内置 UI**（如工具栏按钮、内置操作区、遮罩与提示等）的实现说明，**禁止**把默认体验完全推给外部插槽、或仅以「调用方自己拼 UI + Method」替代组件自有交互面。若确需插槽/Method，须在计划中写明**边界**：哪些由内置 UI 覆盖、哪些由外部扩展。
+2. **逻辑抽离**：以**主组件文件**（`index.vue` / `index.tsx`）为计，若预估实现将超过 **约 100 行**（不含空行与仅 import，复杂组件宜从严），须在计划中列出 **Composable（Vue3）或 Hooks（React）** 等抽离方案及文件粒度假设，**禁止**在计划中默认可将全部逻辑堆在主文件。
+3. **路径锁定**：须完整填写模板中的 **「文件路径与模块化规划」** 表：每一行给出 **相对扩展工程根目录的完整路径**（如 `src/components/foo-bar/composables/useXxx.ts`），**禁止**仅用「某 composable」「api 文件」等模糊描述；并与「文档与源码产出」中的组件目录一致。**「测试层」列必填**：根据模块是否内部调用浏览器 API（Canvas/WebGL/getBoundingClientRect 等）标注 `Vitest(返回值)` 或 `Vitest(调用参数) + E2E(产出值)`，IMPLEMENT 阶段严格按此列决定测试范围。
+
+## 工作流程
+
+1. **定位规范**：在 `specs/` 下找到对应规范需求目录（通常为最近创建或用户指定的 `xx-<组件短名>/`），完整阅读其中的 `spec.md`。
+
+2. **evolve 上下文加载**（`paradigm=evolve` 时）：
+   - 读取目标组件已有的 `plan.md`（如 `specs/01-watermark/plan.md`）了解已有架构
+   - 读取目标组件当前的 `api.ts`、`index.vue` 了解现有实现
+   - 本次 plan 仅规划**增量变更**，不重复已有内容
+
+2b. **evolve 模式**（paradigm=evolve）：
+   - plan 仅规划**变更文件**；文件表增加「操作」列（新增/修改）
+   - 必须包含「回归测试范围」：列出现有 test/e2e 文件及需全量重跑的门禁
+   - logic 资产：无 stories/e2e 规划节，测试仅 vitest
+
+3. **加载模板**：读取 `templates/plan-template.md`，按其中 **摘要、技术上下文、规范门禁、文档与源码产出、文件路径与模块化规划、内置 UI 规划（见技术架构方案）** 与各编号章节完整填充（勿留占位符）。
+
+4. **生成实现计划**：基于 spec 中的「概述」「功能」「验收标准」「接口定义」等章节，按 plan-template 结构生成 `plan.md`，写入对应规范需求目录：
+   - 组件信息与 MVP 约定
+   - **开发前置检查 / 技术调研**（涉及三方库或复杂布局时必填）：在计划中输出当前依赖版本、该版本下 Props/Events 的确切列表（对照 node_modules 或文档）、默认布局方案（如工具栏在顶部）；见 plan-template「技术架构方案」。
+   - **内置 UI 与模块化**：按「计划契约」填写 **内置 UI 控件清单**、**文件路径与模块化规划** 表；复杂逻辑须落到已命名路径（composables/utils 等）。
+   - 接口设计（Props / Events / Slots / Methods）与 spec 对齐，并遵守模板中 **Methods** 前的内聚性说明；**若依赖的三方库存在必填参数未在 spec 中体现，须在接口设计中补充**。
+   - **样式与主题适配**：在编写样式相关部分时，**必须主动读取** `references/lcap-extension-component/platform/` 下对应技术栈的主题变量文档（如 Vue3 用 `theme-variables-element-plus.md`，React 用 `theme-variables-ant-design.md`），在计划中输出完整的「样式变量映射表」（plan-template 第三节），不得推迟至实现阶段再决定。
+   - 实现顺序按功能点拆分，每项任务对应 spec 验收标准
+   - **测试要求**（实现顺序中须包含并明确）：
+     - **对照验收列表**：测试须**对照 spec 与 plan.md（实现计划）的验收列表**逐条验证，确保所有功能均正常、无遗漏。
+     - **example.stories 功能 demo**：在**组件目录下** **`stories/example.stories.{js|tsx|jsx}`** 中为 spec 的**每个功能**各添加一个 demo story，与验收标准一一对应，供本地调试与 Playwright e2e 使用；实现顺序中须包含「编写 example.stories 各功能 demo」任务。
+     - **单元与交互测试（Vitest）**：对每个功能编写单元测试与交互测试（@vue/test-utils），验证 Props、Methods、计算逻辑及用户操作与事件，测试用例与 spec 验收标准一一对应；测试文件放在组件目录或 `__tests__/` 下。Vitest 仅测试 DOM 结构、Props 响应式、事件 emit、纯逻辑、Slot 渲染、$attrs 透传；**禁止**在 Vitest 中断言 Canvas/SVG 渲染输出、使用 getComputedStyle、断言元素尺寸/位置（jsdom 不支持）。对使用浏览器 API 的模块，mock 后仅验证调用参数，渲染产出由 E2E 验证。静态样式写 `<style scoped>` 或 `<style module>`，禁止为迁就 Vitest 内联。
+     - **端到端测试（Playwright）**：
+       - **探测优先**：若 `package.json` 已定义 `test:e2e`，**必须先**在终端**实际执行** `npm run test:e2e`，**禁止**未执行就下结论。**禁止**将用例断言失败、组件逻辑错误误称为「环境问题」逃避修复。
+       - **验收要求**：**`npm run test`**、**`npm run build`** 与 **`npm run test:e2e`**（当工程已配置该脚本时）**均须通过**；失败则根据报错修复并重跑，直至全部通过后再标记相关任务完成。e2e 须与 spec 验收一一对应；详见 SKILL.md「Playwright e2e 测试规范」。E2E 负责验证渲染结果（Canvas 输出、CSS 效果、元素尺寸位置）、用户交互完整流程。
+       - **通过 `create-extension-project.sh` 创建的工程**：初始化阶段已由 `scripts/node/setup-extension-project.mjs` 写入 `playwright.config.ts`（无头 Chromium、`webServer` 与 `E2E_PORT`）、合并 `.gitignore`（Playwright 报告目录）、`e2e/` 目录，以及固定的 `test` / `test:e2e`；实现计划可引用该文件。**禁止**使用 `npx playwright install` 安装浏览器。
+       - **脚手架若无上述产物**：实现顺序中须包含**完整的 e2e 安装与配置**，直至具备可执行的 `test:e2e` 与通过用例：
+          1. **添加依赖与基础配置**：安装 Playwright（`npm install -D @playwright/test`）；**禁止**使用 `npx playwright install` 安装浏览器。playwright.config.ts 根据系统浏览器配置`channel`为`chrome`、`msedge`等；**端口**：将 `package.json` 的 `start` 与 `playwright.config.ts` 的 `webServer` 使用同一端口策略；可参考仓库内 `setup-extension-project.mjs`。
+         2. **编写 e2e 测试代码**：针对**组件目录下** example.stories 中各功能 demo 编写 e2e 测试，通过 Storybook iframe 访问，**storyId 遵循 Storybook 规则**：`<kind（kebab-case）>--<story 导出名（kebab-case）>`，如 `funnel-chart-example--default`；须监听控制台与页面报错（`page.on('pageerror')` + `page.on('console')`，**过滤网络资源 404**：排除 `msg.text().includes('404')` 或 `net::ERR` 的条目，仅捕获组件自身 JS 错误），每个 test 必须有对应断言。详见 SKILL.md「Playwright e2e 测试规范」。
+         3. **package.json 配置 `test:e2e`**：与初始化脚本一致时使用固定命令：`HTTP_PROXY='' http_proxy='' HTTPS_PROXY='' https_proxy='' playwright test`（端口由 `playwright.config.ts` 内部自动分配）。
+     - **运行时报错与自动修复**：计划中须明确「**`npm run test`**、**`npm run build`** 与 **`npm run test:e2e`**（工程已配置时）**均须通过**；若失败则修复后重跑直至通过，再标记任务完成」。
+5. **报告**：输出 `plan.md` 路径，以及可进入下一阶段（`/speckit.tasks`）。
+
+## 关键规则
+
+- 必须使用中文进行任务编排与回复。
+- 实现计划与 spec 的接口定义、验收标准保持一致，不增删或改写需求；在**不删减 spec 功能**的前提下落实 **功能内聚**（内置 UI）与 **逻辑抽离**（模块化路径）。
+- 本项目仅处理前端 UI 组件，不涉及后端 API、数据模型；实现顺序聚焦组件实现、样式、导出、测试等功能。
+- 实现顺序须包含测试任务：使用 **Vitest + @vue/test-utils** 编写单元测试与交互测试；**Playwright e2e** 须配置 `test:e2e` 并**探测执行**直至通过；计划中须写明单测、构建与 e2e 失败时均需修复后重跑直至通过，再标记任务完成。
+- **evolve**（`paradigm=evolve`）：文件路径表须包含"操作"列（`新增` / `修改`），仅列本次变更涉及的文件；实现顺序中任务描述为"修改 xxx"而非"创建 xxx"；测试全量运行确保无回归。