lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/workflows/create/flow.md

@@ -0,0 +1,199 @@
+# create：从无到有（LCAP 扩展依赖库）
+
+---
+
+## 输入
+
+用户的**自然语言需求描述**（`requirement`），例如：
+> 新建一个 LCAP 扩展依赖库
+> 生成一个支持自定义尺寸、颜色、容错等级的二维码组件
+> 新建一个日期格式化逻辑函数
+
+Agent 从用户话术解析（详见 `commands/speckit.create.md`）：
+
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `targetDir` | 用户指定或当前目录 | 建库放置目录，**不含库名** |
+| `template` | `vue3` | `vue2` 可覆盖；**react 建库暂不支持** |
+| `libraryDir` | INIT stdout | 后续阶段工程根 |
+
+## 输出
+
+输出随**资产类型**而异：
+
+| 资产类型 | 交付标准 |
+|----------|----------|
+| **component** | 完整门禁：`npm run test`、`npm run build`、`npm run test:e2e` 均通过；`nasl.extension.json` 存在且 `frontends[0].viewComponents` 非空；五维自检报告全部 PASS |
+| **logic** | `npm run test`、`npm run build` 均通过；五维自检报告全部 PASS（**无** e2e；**不**要求 viewComponents） |
+| **library-only** | 依赖库工程已创建，依赖已安装，`npm run dev` 可正常启动（**不**进入 specify 及后续 speckit 阶段） |
+
+---
+
+## 资产类型
+
+| 资产 | 含义 | 检测规则 |
+|------|------|----------|
+| `library` | 仅建依赖库，不立即创建组件/逻辑 | 用户仅要求初始化工程 |
+| `component` | 新建扩展组件 | 目标 `src/components/<name>/` 尚不存在 |
+| `logic` | 新建 NASL 逻辑函数 | 目标 `src/logics/` 下 `@NaslLogic` 函数尚未导出 |
+
+检测逻辑在阶段 1（INIT）中执行，详见 `commands/speckit.create.md`。
+
+---
+
+## init-context
+
+阶段 1 完成后，`speckit.create` 输出 `init-context`，供后续阶段读取：
+
+| init-context | 触发条件 | 含义 |
+|--------------|----------|------|
+| **library-only** | 资产类型 = `library` | 只建库 + setup，INIT 后短路结束 |
+| **library-and-asset** | cwd 不是 LCAP 扩展项目，且资产类型为 component/logic | 新库 + 首个 component/logic 骨架 |
+| **asset-append** | 已在 LCAP 项目中，目标 component/logic 尚不存在 | 已有库 + 新 component/logic 骨架 |
+
+---
+
+## 执行规则
+
+- **严格顺序**：按 1→7 顺序执行，禁止跳过、乱序、合并阶段
+- **阶段 1 完成后**：从 init 报告读取 **`libraryDir`（绝对路径）**；后续 specify→build-verify 的工作目录均为该路径。脚本调用使用 `--library-dir "$libraryDir"` 或 `npm install --prefix "$libraryDir"`，**禁止**假设 Agent 已 `cd`。
+- **library-only 短路**：INIT 后若 `init-context=library-only`，报告 dev 可启后**立即结束**，不得进入阶段 2
+- **阶段 6 执行前**：遵循零信任验证协议——必须重新读取所有文件（禁止基于实现记忆判断），test/build（及 component 的 test:e2e）必须在本阶段重新执行
+- **失败处理**：修复后重试当前阶段，不回退到前一阶段
+- **不可恢复错误**：记录错误信息，报告给用户，终止流程
+- **每次变更独立 spec 目录**：无论 `library-and-asset` 还是 `asset-append`，每次操作都在 `specs/` 下创建独立编号目录
+
+---
+
+## 阶段 1：INIT
+
+执行 `commands/speckit.create.md`（传入 `requirement`，`paradigm=create`）
+
+**成功标准**（按 init-context）：
+- **library-only**：新项目目录已创建（含 `package.json`、`src/`、`node_modules/`），`npm run dev` 可启动
+- **library-and-asset**：新项目目录已创建，依赖已安装，首个 component/logic 骨架已生成；component 时 Playwright 基础设施已就绪
+- **asset-append**：基础设施完备（component 时含 `playwright.config.ts`、`e2e/`、`test:e2e` 脚本），新 component/logic 骨架已生成
+
+**library-only 短路**：若 `init-context=library-only` → 向用户报告「依赖库已就绪，`npm run dev` 可启动」→ **流程结束**（不进入阶段 2）
+
+---
+
+## 阶段 2：SPECIFY
+
+前置：已在工程目录内，且 `init-context` 不为 `library-only`。执行 `commands/speckit.specify.md`（传入 `requirement`，`paradigm=create`）
+
+**成功标准**：
+- `specs/NN-<name>/spec.md` 文件已创建
+- 包含完整的 Feature 列表（每个 Feature 含验收标准 checkbox）
+- component：复杂组件（展示类/容器类）包含「视觉与交互契约」章节
+- logic：使用 `logic-template.md` 结构，含函数签名、@NaslLogic 元数据、验收标准
+
+---
+
+## 阶段 3：PLAN
+
+前置：spec.md 已存在。执行 `commands/speckit.plan.md`（`paradigm=create`）
+
+**成功标准**：
+- `specs/NN-<name>/plan.md` 文件已创建
+- 包含「文件路径与模块化」表格（每个产出文件有确定性相对路径）
+- component：包含「样式变量映射表」（组件变量 → 平台主题变量）
+- 包含三大计划契约（功能内聚 / 逻辑抽取 / 路径锁定）
+- 包含实现顺序表
+
+---
+
+## 阶段 4：TASKS
+
+前置：plan.md 已存在。执行 `commands/speckit.tasks.md`（`paradigm=create`）
+
+**成功标准**：
+- `specs/NN-<name>/tasks.md` 文件已创建
+- 每条任务包含：标题、描述、依赖关系、输出路径（必填）、验收标准
+- 所有输出路径与 `plan.md` 的文件表逐行对齐
+- 任务按依赖拓扑排序
+
+---
+
+## 阶段 5：IMPLEMENT
+
+前置：tasks.md 已存在。执行 `commands/speckit.implement.md`（`paradigm=create`）
+
+**执行逻辑**：
+1. 按依赖顺序逐个执行 Task
+2. 每个 Task：写代码 → 验收检查 → 运行 `npm run test` → 标记完成
+3. 全部 Task 完成后：
+   - **component**：运行 `npm run build` + `npm run test:e2e`
+   - **logic**：运行 `npm run build`（跳过 stories/ideusage/e2e 相关任务）
+4. 失败时自动修复代码 → 重新运行 → 直到通过
+5. **全量运行测试**确保新增不引入回归
+
+**成功标准**：
+- `tasks.md` 中所有 Task 标记为 `[X]`
+- **component**：`npm run test`、`npm run build`、`npm run test:e2e` 退出码均为 0
+- **logic**：`npm run test`、`npm run build` 退出码均为 0
+
+---
+
+## 阶段 6：SELF-CHECK
+
+前置：implement 完成。执行 `commands/speckit.self-check.md`（`paradigm=create`）
+
+**五个审计维度**：
+1. **API vs 测试覆盖** — component：api.ts 中每个 Prop/Method/Event 是否都有测试；logic：@NaslLogic 函数签名与测试覆盖
+2. **逻辑-样式冲突** — component：JS 尺寸逻辑与 CSS 约束是否矛盾；logic：N/A 或跳过
+3. **平台合规扫描** — 硬编码颜色/间距、CSS 变量合法性；logic：nasl 类型系统合规
+4. **E2E 断言深度** — component：是否有浅层断言（仅 `toBeVisible`）；logic：跳过
+5. **生命周期清理** — component：Observer/Listener/实例是否在 `onUnmounted` 中释放；logic：N/A 或跳过
+
+**成功标准**：
+- `self-check-report.md` 已生成，适用维度结论均为 PASS
+- 所有发现的问题已修复并重新验证
+- **component**：`npm run test`、`npm run build`、`npm run test:e2e` 最终退出码均为 0
+- **logic**：`npm run test`、`npm run build` 最终退出码均为 0
+
+---
+
+## 阶段 7：BUILD-VERIFY
+
+前置：self-check 通过。按资产类型执行验证。
+
+### 按资产类型
+
+| 资产类型 | 验证内容 |
+|----------|----------|
+| **component** | 见下方「component 验证清单」+ `npm run test` + `npm run build` + `npm run test:e2e` |
+| **logic** | `npm run test` + `npm run build`（**跳过** viewComponents 检查与 e2e） |
+| **library-only** | N/A（已在阶段 1 短路结束） |
+
+### component 验证清单
+
+前置：self-check 通过。执行 `npm run build`，然后逐项验证产物完整性。
+
+1. `package.json` 中 `name` 和 `version` 字段存在且非空
+2. `nasl.extension.json` 文件存在
+3. `{packageName}@{version}.zip` 文件存在（packageName 中 `@` 去掉、`/` 替换为 `-`）
+4. `nasl.extension.json` 中 `frontends[0].viewComponents` 数组非空
+
+**失败处理**：
+```
+循环（最多 100 次）:
+  1. npm run build
+  2. 逐项检查上述验证清单
+  若全部通过 → 结束
+  若失败 → 将错误信息反馈给 Agent 修复代码 → 重新循环
+```
+
+**成功标准**：
+- **component**：验证清单 4 项全部通过，产物 ZIP 可用于平台注册；输出最终交付报告
+- **logic**：`npm run test`、`npm run build` 退出码均为 0；输出最终交付报告
+
+---
+
+## 核心约束
+
+- 所有文件路径使用相对于项目根目录的相对路径
+- 严格遵循 NASL 类型系统：仅允许 `nasl.core.*`、`nasl.collection.*`，禁止自定义 class
+- 组件必须使用 CSS 变量实现主题适配，禁止硬编码颜色/间距
+- 图标必须 SVG，禁止位图/base64/emoji
+- 测试零容忍：禁止删除/跳过失败用例，Timeout 按逻辑 Bug 排查修复

package/packages/lcap-frontend-library/workflows/evolve/flow.md

@@ -0,0 +1,249 @@
+# evolve：存量演进（LCAP 扩展依赖库）
+
+---
+
+## 输入
+
+用户的**自然语言需求描述**（`requirement`），例如：
+> 给二维码组件增加容错等级配置
+> 修改日期格式化逻辑，支持自定义 locale
+> 增强现有表格组件的排序能力
+
+**前提**：目标资产**已存在于当前仓库**。
+
+## 输出
+
+输出随**资产类型**而异：
+
+| 资产类型 | 交付标准 |
+|----------|----------|
+| **component** | 完整门禁：`npm run test`、`npm run build`、`npm run test:e2e` 均通过；`nasl.extension.json` 存在且 `frontends[0].viewComponents` 非空；五维自检报告全部 PASS；**已有行为未被破坏** |
+| **logic** | `npm run test`、`npm run build` 均通过；五维自检报告全部 PASS（**无** e2e；**不**要求 viewComponents）；**已有导出与行为未被破坏** |
+
+---
+
+## 前置门禁
+
+在进入阶段 1 之前，**必须**解析资产类型并验证目标资产已存在：
+
+| 资产 | 检测规则 | 不存在时 |
+|------|----------|----------|
+| **component** | `src/components/<name>/` 目录存在 | **报错终止**，提示用户改用 **create 流程**：`workflows/create/flow.md` |
+| **logic** | `src/logics/` 下目标 `@NaslLogic` 函数已导出 | **报错终止**，提示用户改用 **create 流程**：`workflows/create/flow.md` |
+
+> evolve 范式**不支持** `library` 资产类型。若用户仅要初始化工程，请路由至 `workflows/create/flow.md`。
+
+检测逻辑在阶段 1（INIT）中由 `commands/speckit.create.md` 再次校验；若 `paradigm=evolve` 且资产不存在，command 同样报错退出。
+
+---
+
+## 资产类型
+
+| 资产 | 含义 | 检测规则 |
+|------|------|----------|
+| `component` | 演进已有扩展组件 | `src/components/<name>/` **已存在** |
+| `logic` | 演进已有 NASL 逻辑函数 | 目标 `@NaslLogic` 函数已在 `src/logics/` 导出 |
+
+---
+
+## init-context
+
+阶段 1 完成后，`speckit.create` 输出 `init-context`，供后续阶段读取：
+
+| init-context | 触发条件 | 含义 |
+|--------------|----------|------|
+| **asset-evolve** | `paradigm=evolve` 且目标 component/logic **已存在** | 列出现有文件、setup 依赖；**不** scaffold |
+
+> evolve 流程**仅**产生 `init-context=asset-evolve`。若得到其他值，说明路由错误或 command 分支异常，应终止并排查。
+
+---
+
+## 禁止 scaffold
+
+`paradigm=evolve` 时，阶段 1 **明确禁止**调用以下脚手架脚本：
+
+- `scripts/bash/create-component-files.sh`
+- `scripts/bash/create-logic-files.sh`
+
+INIT 阶段仅执行 setup（`npm install` 等）并**列出现有实现文件**，不得生成新骨架或覆盖已有源码。
+
+---
+
+## 执行规则
+
+自 `workflows/create/flow.md` 继承以下纪律，并追加 evolve 专属约束：
+
+- **严格顺序**：按 1→7 顺序执行，禁止跳过、乱序、合并阶段
+- **阶段 1 完成后**：从 init 报告读取 **`libraryDir`（绝对路径）**；后续所有操作以该路径为准（`--library-dir` / `npm install --prefix`），**禁止**假设 Agent 已 `cd`。
+- **阶段 6 执行前**：遵循零信任验证协议——必须重新读取所有文件（禁止基于实现记忆判断），test/build（及 component 的 test:e2e）必须在本阶段重新执行
+- **失败处理**：修复后重试当前阶段，不回退到前一阶段
+- **不可恢复错误**：记录错误信息，报告给用户，终止流程
+- **每次变更独立 spec 目录**：每次 evolve 操作都在 `specs/` 下创建独立编号目录
+- **全量回归测试**：implement 与 self-check 阶段必须**全量**运行 `npm run test`（component 另加 `npm run test:e2e`）；evolve 变更**不得破坏已有行为**
+- **增量纪律**：spec/plan/tasks/self-check 均聚焦**本次增量**，但门禁与回归范围仍为**全量**
+
+---
+
+## 阶段 1：INIT
+
+执行 `commands/speckit.create.md`（传入 `requirement`，`paradigm=evolve`）
+
+**成功标准**：
+- `init-context=asset-evolve`
+- 工程目录内依赖已安装（setup 完成）；setup 使用 `node setup-extension-project.mjs "<libraryDir>"`（非 `$(pwd)`）
+- 现有 component/logic 源文件已列出（api.ts、index.vue、logics 导出等），**无** scaffold 产出
+- **禁止**调用 `create-component-files` / `create-logic-files`
+
+**失败处理**：若资产不存在 → 报错并提示用户改用 `workflows/create/flow.md`
+
+---
+
+## 阶段 2：SPECIFY
+
+前置：已在工程目录内，且 `init-context=asset-evolve`。执行 `commands/speckit.specify.md`（传入 `requirement`，`paradigm=evolve`）
+
+**evolve 模式纪律**（详见 `commands/speckit.specify.md` § evolve）：
+1. **先读取现有实现**再写 spec：
+   - component：`api.ts`、`index.vue`、最近 `specs/*/spec.md`
+   - logic：`src/logics/<name>.ts` 或 `src/logics/index.ts` 中对应导出
+2. spec 标题：`# [资产名] — 增量需求（基于现有实现）`
+3. 正文结构：`## 现状摘要（事实）` → `## 本次增量` → `## 验收标准（仅本次）`
+4. 接口表标注「新增 / 修改」
+5. 仍执行 `create-spec.sh` 创建独立 `specs/NN-<name>/` 目录
+
+**成功标准**：
+- `specs/NN-<name>/spec.md` 文件已创建
+- 含现状摘要与本次增量，验收标准仅覆盖本次变更
+- component：增量 Prop/Method/Event 标注清晰
+- logic：函数签名与 @NaslLogic 元数据变更标注清晰
+
+---
+
+## 阶段 3：PLAN
+
+前置：spec.md 已存在。执行 `commands/speckit.plan.md`（`paradigm=evolve`）
+
+**evolve 模式纪律**（详见 `commands/speckit.plan.md`）：
+- plan **仅规划变更文件**；文件表增加「操作」列（新增/修改）
+- 必须包含「回归测试范围」：列出现有 test/e2e 文件及需全量重跑的门禁
+- logic 资产：无 stories/e2e 规划节，测试仅 vitest
+
+**成功标准**：
+- `specs/NN-<name>/plan.md` 文件已创建
+- 文件表仅含变更项，每项标注操作类型
+- 含回归测试范围说明
+- component：变更涉及样式时含「样式变量映射表」
+- 包含实现顺序表
+
+---
+
+## 阶段 4：TASKS
+
+前置：plan.md 已存在。执行 `commands/speckit.tasks.md`（`paradigm=evolve`）
+
+**evolve 模式纪律**（详见 `commands/speckit.tasks.md` § evolve 模式补充）：
+- 每条变更任务后追加「回归验证」子任务：`npm run test`（component 另加 `test:e2e`）
+- 产出路径仍必填；**仅列变更相关路径**
+- logic：禁止生成 stories/e2e 任务
+
+**成功标准**：
+- `specs/NN-<name>/tasks.md` 文件已创建
+- 每条任务包含：标题、描述、依赖关系、输出路径（必填）、验收标准
+- 变更任务均附带回归验证子任务
+- 任务按依赖拓扑排序
+
+---
+
+## 阶段 5：IMPLEMENT
+
+前置：tasks.md 已存在。执行 `commands/speckit.implement.md`（`paradigm=evolve`）
+
+**evolve 模式纪律**（详见 `commands/speckit.implement.md`）：
+- implement 前读取 `LEARNINGS.md`（若存在）
+- 按依赖顺序逐个执行 Task；**聚焦变更**，但完成后**全量**运行测试
+- logic 资产：跳过 api.ts、ideusage、stories、block.stories、e2e 相关任务
+- evolve：**全量 vitest**（component 另加全量 test:e2e）确保不引入回归
+
+**执行逻辑**：
+1. 按依赖顺序逐个执行 Task
+2. 每个 Task：写代码 → 验收检查 → 运行 `npm run test` → 标记完成
+3. 全部 Task 完成后：
+   - **component**：运行 `npm run build` + **全量** `npm run test:e2e`
+   - **logic**：运行 `npm run build`（跳过 stories/ideusage/e2e 相关任务）
+4. 失败时自动修复代码 → 重新运行 → 直到通过
+5. **全量运行测试**确保增量不破坏已有行为
+
+**成功标准**：
+- `tasks.md` 中所有 Task 标记为 `[X]`
+- **component**：`npm run test`、`npm run build`、`npm run test:e2e` 退出码均为 0
+- **logic**：`npm run test`、`npm run build` 退出码均为 0
+
+---
+
+## 阶段 6：SELF-CHECK
+
+前置：implement 完成。执行 `commands/speckit.self-check.md`（`paradigm=evolve`）
+
+**evolve 模式纪律**（详见 `commands/speckit.self-check.md` § evolve）：
+- 五维审计**聚焦本次 spec 增量**；仍须**全量 regression test** 证据
+- 维度 1：增量 Prop/Event/Method 覆盖 + **未破坏原有导出**
+- logic：审计 @NaslLogic、import '@nasl/types'、nasl 类型、logics/index.ts 导出、泛型/rest 规则；跳过 E2E 维度 4
+
+**五个审计维度**：
+1. **API vs 测试覆盖** — component：增量 Prop/Method/Event 覆盖 + 原有项仍被测试；logic：函数签名与测试覆盖
+2. **逻辑-样式冲突** — component：JS 尺寸逻辑与 CSS 约束是否矛盾；logic：N/A 或跳过
+3. **平台合规扫描** — 硬编码颜色/间距、CSS 变量合法性；logic：nasl 类型系统合规
+4. **E2E 断言深度** — component：是否有浅层断言（仅 `toBeVisible`）；logic：跳过
+5. **生命周期清理** — component：Observer/Listener/实例是否在 `onUnmounted` 中释放；logic：N/A 或跳过
+
+**成功标准**：
+- `self-check-report.md` 已生成，适用维度结论均为 PASS
+- 所有发现的问题已修复并重新验证
+- **component**：`npm run test`、`npm run build`、`npm run test:e2e` 最终退出码均为 0
+- **logic**：`npm run test`、`npm run build` 最终退出码均为 0
+
+---
+
+## 阶段 7：BUILD-VERIFY
+
+前置：self-check 通过。按资产类型执行验证（同 create flow §2.6）。
+
+### 按资产类型
+
+| 资产类型 | 验证内容 |
+|----------|----------|
+| **component** | 见下方「component 验证清单」+ `npm run test` + `npm run build` + `npm run test:e2e` |
+| **logic** | `npm run test` + `npm run build`（**跳过** viewComponents 检查与 e2e） |
+
+### component 验证清单
+
+前置：self-check 通过。执行 `npm run build`，然后逐项验证产物完整性。
+
+1. `package.json` 中 `name` 和 `version` 字段存在且非空
+2. `nasl.extension.json` 文件存在
+3. `{packageName}@{version}.zip` 文件存在（packageName 中 `@` 去掉、`/` 替换为 `-`）
+4. `nasl.extension.json` 中 `frontends[0].viewComponents` 数组非空
+
+**失败处理**：
+```
+循环（最多 100 次）:
+  1. npm run build
+  2. 逐项检查上述验证清单
+  若全部通过 → 结束
+  若失败 → 将错误信息反馈给 Agent 修复代码 → 重新循环
+```
+
+**成功标准**：
+- **component**：验证清单 4 项全部通过，产物 ZIP 可用于平台注册；输出最终交付报告
+- **logic**：`npm run test`、`npm run build` 退出码均为 0；输出最终交付报告
+
+---
+
+## 核心约束
+
+- 所有文件路径使用相对于项目根目录的相对路径
+- 严格遵循 NASL 类型系统：仅允许 `nasl.core.*`、`nasl.collection.*`，禁止自定义 class
+- 组件必须使用 CSS 变量实现主题适配，禁止硬编码颜色/间距
+- 图标必须 SVG，禁止位图/base64/emoji
+- 测试零容忍：禁止删除/跳过失败用例，Timeout 按逻辑 Bug 排查修复
+- **evolve 专属**：任何增量变更不得破坏已有 API 契约与已通过测试的行为；修复时必须扩展测试而非削弱断言

package/packages/lcap-frontend-library/workflows/generate/flow.md

@@ -0,0 +1,10 @@
+# 已拆分：请勿直接执行本文件
+
+本 skill 已将「生成 / 修改」拆分为两个范式：
+
+| 意图 | 读取 |
+|------|------|
+| 新建 / 创建 / 添加（资产尚不存在） | `workflows/create/flow.md` |
+| 更新 / 修改 / 增强（资产已存在） | `workflows/evolve/flow.md` |
+
+**Agent 必须**根据 SKILL.md 路由读取上表对应 flow，严格按其中步骤执行。

package/packages/lcap-frontend-library/workflows/harness/flow.md

@@ -0,0 +1,82 @@
+# Harness（归因回流）
+
+skill 自增强机制——用户主动将 create / evolve / migrate 执行中遇到的非平凡问题精炼为一行经验，写入 `LEARNINGS.md`；下次 skill 使用时自动读取，作为先验知识、checklist 与流程约束。
+
+---
+
+## 触发方式
+
+**仅用户主动触发**。create / evolve / migrate 流程执行过程中不主动提示归因、不输出收尾回顾、不在 implement/green 中询问是否写入 LEARNINGS。
+
+用户说「归因回流」「回流」「记录教训」「总结经验」等 → SKILL.md 路由到此。
+
+Agent 执行：
+1. 回顾当前对话全部上下文
+2. 识别需要归因的问题：
+   - 修复 ≥2 轮才通过的
+   - 用户指出错误并指导修复的
+   - 方案发生重大调整的
+   - agent 之前判断被证明错误的
+3. 对每个问题执行精炼
+4. 写入 LEARNINGS.md
+
+---
+
+## 精炼与写入
+
+### 精炼规则
+
+每条写入 LEARNINGS.md 的内容格式：
+
+```markdown
+- **[场景关键词]**：[什么情况] + [什么坑/正确做法]
+```
+
+**要求**：
+- 一条一行，控制在 1-2 句话内
+- 必须包含：场景（什么时候碰到）+ 结论（正确做法或需避免的坑）
+- 不记录日期、证据链、文件路径、调试过程等细节
+- 目标读者是未来执行同类任务的 agent，需一眼就能理解并应用
+
+**示例**：
+```markdown
+- **v-model 约定**：LCAP 用 `value` + `emit('update:value')`，非 Vue3 标准的 modelValue
+- **桶文件导出**：`components/index.ts` 必须具名导出 `export { default as CwXxx }`，禁止 `export *`
+- **IDE 高度塌陷**：依赖容器尺寸的组件须在 isDesigner 时加固定高度，简单容器不加
+- **story title**：禁止中文/空格/斜杠，否则 storyId 解析失败导致 E2E 404
+```
+
+### 去重规则
+
+写入前扫描 LEARNINGS.md 已有内容：
+- 已有等价条目 → 不写入，告知用户"已有此经验"
+- 已有但可补充 → 修改已有条目（扩展适用场景）
+- 全新 → 追加到文件末尾
+
+### 写入确认
+
+写入完成后输出：
+- 新增了 N 条经验
+- 列出具体内容
+- 告知用户「后续 create / evolve / migrate 各阶段执行时将读取 LEARNINGS，纳入 plan 风险、checklist 审计与实现守护」
+
+---
+
+## 消费方式（下游阶段如何使用 LEARNINGS）
+
+LEARNINGS 是 skill 自增强的核心：**写入需用户主动，读取在下次 workflow 执行时自动发生**（不触发 harness，不自动写入）。
+
+| 用途 | create | evolve | migrate | 落地方式 |
+|------|--------|--------|---------|----------|
+| **先验知识** | speckit.plan | speckit.plan | migrate.plan | plan 风险节 |
+| **Checklist** | speckit.self-check | speckit.self-check | migrate.check | 额外审计项 |
+| **流程约束** | speckit.implement | speckit.implement | migrate.green | 实现前内部比对 |
+
+---
+
+## 核心原则
+
+- **精简优先**：LEARNINGS 是多阶段高频引用的文件，每条必须足够简短
+- **用户控制**：所有写入都需用户主动触发归因回流命令，不自动写入
+- **自动读取**：下游 plan / implement / self-check（及 migrate 对应阶段）执行时须读取 LEARNINGS，这是自增强的消费端，不等于自动归因
+- **去重**：避免重复条目，保持文件精炼