lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: lcap-frontend-library
+description: LCAP 前端扩展组件库全生命周期工具。create/evolve：7 阶段 speckit 驱动；migrate：Vue2→Vue3 七命令流程；harness：LEARNINGS 归因回流。
+---
+
+# lcap-frontend-library
+
+LCAP 前端扩展组件库全生命周期工具，覆盖「create → evolve → migrate → harness」闭环。
+
+---
+
+## 路由分发
+
+识别用户意图后，**读取对应流程文件并严格按其中步骤执行**，不可跳过或自行编排。
+
+---
+
+### create
+
+**路由** → `workflows/create/flow.md`
+
+**触发场景**：
+- 新建、创建、生成、添加（资产尚不存在）
+- 初始化工程、新建库/组件/逻辑
+- 用户想在已有项目中**追加**一个新组件/逻辑（目标资产目录尚不存在）
+- 用户要求生成一个 Vue3 前端扩展组件（LCAP Extension Component）
+- 用户描述了一个组件需求，期望产出完整可构建的扩展依赖库项目
+- 用户说"生成扩展"、"生成组件库"、"新建组件"、"再加一个组件"
+
+**能力摘要**：7 阶段 init→spec→plan→tasks→implement→check→build-verify，speckit.* 命令驱动，产出完整可构建项目（含单测 + E2E + 五维审计 + 构建产物验证）。
+
+---
+
+### evolve
+
+**路由** → `workflows/evolve/flow.md`
+
+**触发场景**：
+- 更新、修改、增强（**目标资产已存在**）
+- 用户想修改已有组件/逻辑（增加功能 / 修改行为）
+- 用户说"给 XX 组件增加 XX 功能"、"优化 XX 逻辑"
+
+**能力摘要**：同上 7 阶段 init→spec→plan→tasks→implement→check→build-verify，speckit.* 文内 evolve 分支，在已有资产基础上迭代增强。
+
+---
+
+### migrate
+
+**路由** → `workflows/migrate/flow.md`
+
+**触发场景**：
+- 迁移、Vue2 转 Vue3、升级
+- 用户要求将 Vue2 依赖库迁移到 Vue3
+- 用户说"把这个库从 Vue2 转成 Vue3"、"迁移组件库"、"升级到 Vue3"
+
+**能力摘要**：scan→spec→plan→tasks→red→green→check，migrate.* 命令驱动；支持 component / logic / shared-composable 三资产类型；check 含等价审计 + 产物验证 + 库级收尾（§E）；Superpowers 哲学（Vue2=真值、RED/GREEN 分离、行为等价矩阵、断路器）。
+
+---
+
+### harness
+
+**路由** → `workflows/harness/flow.md`
+
+**触发场景**：
+- 归因回流、记录教训、总结经验
+- 用户说"归因回流"、"记录教训"、"总结经验"、"回流"
+
+**能力摘要**：回顾对话上下文 → 识别非平凡问题 → 精炼为一行经验 → 写入 LEARNINGS.md → 下次 create / evolve / migrate 执行时自动读取，作为先验知识（plan）、checklist（self-check/check）、流程约束（implement/green），实现 skill 自增强。不自动触发写入。
+
+---
+
+## 共享资源
+
+下游流程文件中引用的共享资源均位于本 skill 目录内：
+
+| 类型 | 路径 | 用途 |
+|------|------|------|
+| 命令 | `commands/speckit.*.md` | create + evolve 各阶段的详细执行指令 |
+| 命令 | `commands/migrate.*.md` | migrate 流程各阶段的详细执行指令 |
+| 知识库 | `references/lcap-extension-component/` | 视图组件规范（api.ts、ide、block、platform 等） |
+| 知识库 | `references/frontend-design/SKILL.md` | 前端设计与观感规范 |
+| 知识库 | `references/nasl-logic-authoring/SKILL.md` | 逻辑函数（@NaslLogic）规范 |
+| 知识库 | `workflows/migrate/knowledge-base.md` | 迁移领域知识（§section-id 索引） |
+| 脚本 | `scripts/bash/`、`scripts/node/` | 脚手架创建、工程初始化、Storybook 检测 |
+| 模板 | `templates/` | spec / plan / tasks / self-check / migration 各阶段模板 |
+| 经验库 | `LEARNINGS.md` | 用户主动 harness 写入；create/evolve/migrate 下次执行时只读引用（先验 + checklist + 流程约束） |

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

@@ -0,0 +1,287 @@
+---
+description: 等价性证明 + 产物验证——§A 三门禁、§B 等价审计、§C 产物验证、§D 跨资产回归、§E 库级收尾（条件触发）。支持 --finalize-library。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+- 资产名称（如 `cw_audio_view`）— 常规 per-asset check
+- `--finalize-library` — 仅执行库级 §E（要求 manifest 已全部 verified 或用户确认强制收尾）
+- 若为空且非 finalize：展示 manifest 中 green-done 资产供选择
+
+## 必要知识（必须在执行前 Read，不可跳过）
+
+### 共通（所有资产类型）
+1. **`workflows/migrate/knowledge-base.md`** — Vue2→Vue3 迁移先验知识（全文）
+2. **`LEARNINGS.md`** — 先验/约束/checklist（若存在）
+
+> 全文 Read KB 后，按 KB §asset-applicability 与本文「资产类型分支」跳过不适用章节。
+> component 维度 1 以 KB §alignment-checklist 为准；logic 以 migrate.check.md L1–L3 为准；shared 以 S1–S3 为准。
+
+## 核心纪律
+
+> **报告中每个 PASS/FAIL 声明必须引用实际终端执行输出。**
+> 不允许"应该通过"、"看起来正确"、"根据代码分析应该没问题"。
+> 终端退出码和结果摘要是唯一有效证据。
+
+> **发现问题必须修复并复检，直至该维度通过。**
+> 禁止将问题留作"后续处理"后结束。
+
+## 禁止条款
+
+- ❌ 未执行终端命令就声称通过
+- ❌ 将发现的问题标记"后续处理"
+- ❌ 删除/跳过测试来让门禁通过
+- ❌ 行为等价矩阵有 ❌ 行时标记 verified
+
+## 零信任验证协议（强制）
+
+> 审计的目标是**找到 bug**，不是确认正确。假设实现有遗漏，直到证据证明没有。
+
+### 三条铁律
+
+1. **强制重读**：审计开始前，必须重新从磁盘读取所有相关文件（spec.md、plan.md、tasks.md 行为等价矩阵、组件源码、测试文件）。禁止基于"我记得代码是这样写的"做任何判断——以 Read 到的磁盘内容为唯一事实。
+2. **终端为证**：三门禁（test/build/test:e2e）的结论**只能**来自本次审计中实际执行的终端命令输出（退出码 + 结果摘要）。禁止引用 GREEN 阶段的执行结果或声称"刚才已跑过"。
+3. **有据才判**：每个维度的"通过"结论必须附带至少一条**不可伪造的证据**：
+   - 静态检查：文件路径 + 行号 + 引用内容
+   - 动态验证：命令 + 退出码 + 关键输出行
+
+### 违规判定
+
+以下行为视为无效审计，报告不可信：
+- 结论中出现"根据 GREEN 阶段的实现"、"在上面的步骤中已确认"等回溯性表述
+- 三门禁结果无对应的终端执行记录
+- 维度结论为"通过"但无任何文件引用或命令输出
+- 未执行 Read 直接对文件内容做断言
+
+---
+
+## 执行段概览（顺序固定）
+
+| 段 | 名称 | component | logic | shared |
+|----|------|-----------|-------|--------|
+| §A | 三门禁 | test+build+e2e | test+build | test+build |
+| §B | 等价审计 | 五维 | L1–L3 | S1–S3 |
+| §C | 产物验证 | 4 项 | build only | build only |
+| §D | 跨资产回归 | 全量 test+e2e | 全量 test | 全量 test |
+| §E | 库级收尾 | 条件触发 | 同左 | 同左 |
+
+与 create/evolve 映射：§A+§B ≈ self-check；§C+§E ≈ build-verify。
+
+---
+
+## 工作流程
+
+### 步骤 0：读取资产类型
+
+1. 从 `specs/manifest.md` 读取当前资产的「类型」列
+2. 打开本文「资产类型分支」，**仅**执行该分支步骤
+3. 禁止执行其他类型步骤（例：logic 禁止 E2E / ideusage / §alignment-checklist）
+
+### 0. 前置定位
+
+1. 从 `specs/manifest.md` 确认资产状态为 `🟢 green-done`（`--finalize-library` 模式跳过此项，直接读 manifest）
+2. 读取 `specs/<NN>-<资产名>/spec.md`（Vue2 行为真值）
+3. 读取 `specs/<NN>-<资产名>/tasks.md`（行为等价矩阵）
+4. 从 manifest 读取「类型」与 `depends_on`（同 migrate.spec 门禁）：
+   - `depends_on` 非空时，逐项检查依赖资产状态：
+     - 全部为 `✅ verified` → 继续
+     - 存在 `🚫 blocked` → 使用 AskUserQuestion 确认是否跳过阻塞依赖
+     - 存在未 verified 且非 blocked → **报错终止**，提示先迁移依赖资产
+5. 加载输出模板：`templates/migration-report-template.md`
+6. 若 `--finalize-library`：跳至 §E（仍须零信任重读 manifest）
+
+---
+
+### 步骤 1：§A 三门禁（先跑通再审计）
+
+必须依次执行并记录终端输出：
+
+```bash
+npm run test
+```
+记录：退出码 + 通过/失败用例数
+
+```bash
+npm run build
+```
+记录：退出码
+
+```bash
+npm run test:e2e
+```
+记录：退出码 + 通过/失败用例数
+
+**logic / shared-composable**：跳过 e2e，报告标注 N/A。
+
+**任何门禁失败**：修复代码 → 重跑 → 直至全部 exit 0。
+**修复过程中禁止**修改测试来通过（零容忍）。
+
+---
+
+### 步骤 2：行为等价矩阵验证
+
+读取 tasks.md 中的行为等价矩阵，逐行验证：
+
+| 检查项 | 合格标准 |
+|--------|---------|
+| "RED 测试编码"列 | 每行有测试文件路径+行号（无空行） |
+| "GREEN 实现"列 | 每行有实现文件路径（无空行） |
+| 测试实际通过 | 该行为的测试在 `npm run test` 中 PASS |
+
+填充"等价状态"列：
+- **✅ 等价**：测试通过，实现与 spec 行为一致
+- **⚠️ 有意差异**：Vue3 框架限制导致的差异（须记录原因，归入维度 5 / 机制差异表）
+- **❌ 缺失**：无测试 / 测试未通过 / 实现遗漏（必须修复）
+
+**矩阵要求**：无 ❌ 行方可继续。
+
+---
+
+### 步骤 3：§B 等价审计（按资产类型分支）
+
+### §B logic 资产
+
+**禁止**使用 §alignment-checklist。执行 L1 签名对齐、L2 测试覆盖、L3 平台合规；跳过 Template/Storybook/api.ts 维。
+
+| 维 | 检查项 |
+|----|--------|
+| L1 签名对齐 | 参数名/类型/顺序、返回值、@NaslLogic JSDoc、泛型、rest 与 spec 1:1 |
+| L2 测试覆盖 | 矩阵无 ❌；logics/index.ts 导出；vitest 覆盖每个矩阵行 |
+| L3 平台合规 | import '@nasl/types'；仅 nasl.*；无 Object/any |
+
+每项标注：✅ 一致 / ⚠️ 机制差异 / ❌ 缺陷（必须修复）
+
+### §B shared-composable 资产
+
+- **S1 方法对齐**：spec 方法清单 ↔ composable export（方法名、参数、返回值 1:1）
+- **S2 副作用清理**：listener / observer / timer 注册与 teardown 对称
+- **S3 测试覆盖**：矩阵无 ❌；Vitest 覆盖每个 exported 方法
+
+每项标注：✅ 一致 / ⚠️ 机制差异 / ❌ 缺陷（必须修复）
+
+### §B component 资产
+
+#### 维度 1：对齐验证（→ KB §alignment-checklist）
+
+逐项执行 **`knowledge-base.md` §alignment-checklist**（24 条）；每条 PASS/FAIL + 证据写入 report.md。**禁止**在 report 中维护第二套 checklist。
+
+#### 维度 2：API 覆盖矩阵
+
+从 api.ts 提取所有 Props/Methods/Events，逐一核对测试覆盖：
+
+| API 项 | 类型 | Vitest 覆盖 | E2E 覆盖 | 状态 |
+|--------|------|-------------|----------|------|
+
+未覆盖项必须补充测试并重跑验证。
+
+#### 维度 3：平台合规扫描
+
+- 硬编码颜色/间距扫描
+- CSS 变量合法性（与 `references/lcap-extension-component/platform/theme-variables-element-plus.md` 交叉核对）
+- NASL 类型检查（禁止 Object/Function/any）
+- Vue2 残留检查（this.$emit / Options API / process.env / export *）
+- 样式隔离（scoped style 强制；见 `workflow-guardrails.md`）
+
+#### 维度 4：Storybook 运行时证据
+
+E2E 测试已包含 pageerror/console 监听（过滤网络资源 404：排除 `msg.text().includes('404')` 或 `net::ERR` 的条目，仅捕获组件自身 JS 错误）。记录 `npm run test:e2e` 的结果作为证据。
+
+若有新运行时错误（GREEN 阶段可能遗漏）：修复 → 重跑 → 记录迭代。
+
+#### 维度 5：机制差异标注
+
+记录 Vue3 实现与 Vue2 行为之间的有意差异：
+
+| 差异项 | 分类 | Vue2 行为 | Vue3 行为 | 原因 |
+|--------|------|----------|----------|------|
+
+分类：框架差异 / 优化 / 简化 / 限制
+
+---
+
+### 步骤 3.5：§C 产物验证
+
+**component**（build exit 0 后立即执行）：
+
+1. `package.json` 的 `name`、`version` 非空
+2. `nasl.extension.json` 存在
+3. `{packageName}@{version}.zip` 存在（name：`@` 去掉、`/` → `-`）
+4. `frontends[0].viewComponents` 含**本资产**组件名
+
+**logic / shared-composable**：§C 仅引用 §A 的 build exit 0，其余标 N/A。
+
+写入 report「产物验证」节（→ `templates/migration-report-template.md`）。
+
+---
+
+### 步骤 3.6：§D 跨资产回归
+
+当 manifest 中 `✅ verified` 数量 ≥ 1（含本次即将标记者）：
+
+```bash
+npm run test
+npm run test:e2e   # 仅当库含 component 且 playwright 已配置
+```
+
+写入 report「跨资产回归证据」节。
+
+---
+
+### 步骤 4：修复闭环
+
+对每项 ❌ 缺陷执行修复后：
+1. 重跑 §A 三门禁验证
+2. 将结果写入报告「测试运行证据」节
+3. 直至全部审计维 PASS
+
+**闭环要求**：全部 §B 审计维 PASS + 矩阵无 ❌ + §A 三门禁全过 + §C 通过（component）→ 方可结束 per-asset check。
+
+---
+
+### 步骤 5：§E 库级收尾（条件触发）
+
+**条件**：manifest 全部非 `🚫 blocked` 资产均为 `✅ verified`（含本次），或 `--finalize-library`。
+
+**动作**（→ KB §process-library-finalize）：
+
+1. 全量三门禁
+2. 产物验证 4 项（viewComponents **全量**非空）
+3. 按 `templates/library-report-template.md` 写入 `specs/library-report.md`
+4. 更新 manifest：`library_status → 🏁 library-verified`，`library_verified_at` = ISO 时间
+
+**blocked 资产**：仍计入统计；存在 blocked 且非全部 verified → 不触发 §E。
+
+---
+
+## 输出
+
+按 `templates/migration-report-template.md` 格式输出，写入：
+`specs/<NN>-<资产名>/report.md`
+
+报告必须包含：
+- §A 三门禁终端证据（退出码 + 用例数）
+- 行为等价矩阵最终状态
+- §B 审计维结论（component 五维 / logic L1–L3 / shared S1–S3，逐项 PASS/FAIL + 修复记录）
+- §C 产物验证（component 4 项 / logic·shared build only）
+- §D 跨资产回归证据
+- 机制差异表（component 维度 5 / logic·shared 等价 ⚠️ 行汇总）
+- 总体结论：**PASS** / **CONDITIONAL PASS** / **FAIL**
+
+更新 `specs/manifest.md`：
+- 通过 → 状态 `✅ verified`
+- 未通过 → 保持 `🟢 green-done`（需继续修复）
+- 库级：`library_status` / `library_verified_at` / `末次库级三门禁`（§E 时）
+
+## 关键规则
+
+- **审计视角**：假定实现有遗漏，不默认"已实现即正确"
+- **证据铁律**：每个 PASS 声明必须有终端执行证据
+- **修复闭环**：发现问题必须修复至通过
+- **矩阵完整性**：行为等价矩阵是最终判定依据——有 ❌ 行则 FAIL
+- **零容忍**：测试不可删除/跳过
+- **知识库优先**：对齐检查以 §alignment-checklist 为准
+- 必须使用中文输出报告

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

@@ -0,0 +1,190 @@
+---
+description: Phase GREEN——按 plan.md 路径表逐步实现代码，让测试从 FAIL 收敛至 PASS。目标已由 RED 定义，本阶段只做"让测试通过"，禁止多做。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+用户输入为资产名称（如 `cw_audio_view`）。若为空，展示 `specs/manifest.md` 中所有 red-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`
+- `references/lcap-extension-component/workflow-guardrails.md`
+
+**logic** 额外 Read：
+- `references/nasl-logic-authoring/SKILL.md`
+- `references/lcap-extension-component/workflow-guardrails.md`
+
+**shared-composable**：无 extension-component / nasl-logic-authoring；额外 Read `references/lcap-extension-component/workflow-guardrails.md`
+
+> 转换与验收：component 以 KB + lcap-extension-component 为准；logic 以 KB §discipline + nasl-logic-authoring 为准。不得凭 AI 记忆。
+> 全文 Read KB 后，按 KB §asset-applicability 与本文「资产类型分支」跳过不适用章节。
+
+## 核心纪律
+
+> **目标已定义（RED 的测试），我在收敛到目标。**
+> 不是在创作，是在证明。让测试从 FAIL 变 GREEN 就是等价性的构造性证明。
+
+### 断路器
+> **同一错误模式连续 3 次修复失败 → 停止 → 质疑当前迁移方案。**
+
+### 零容忍
+> **失败的测试不可删除、不可跳过、不可注释。必须修复至通过。**
+
+## 禁止条款
+
+- ❌ 修改测试文件让测试通过（除非测试本身有 bug，须在 tasks.md 中记录原因）
+- ❌ 删除/跳过/注释失败测试
+- ❌ 增加 spec.md 未记录的额外功能（不多做）
+- ❌ 重构代码结构追求"优雅"（只求测试通过）
+- ❌ 增加 plan.md 未规划的新文件（除修复过程中发现的必要工具文件）
+
+---
+
+## 工作流程
+
+### 步骤 0：读取资产类型
+
+1. 从 `specs/manifest.md` 读取当前资产的「类型」列
+2. 打开本文「资产类型分支」，**仅**执行该分支步骤
+3. 禁止执行其他类型步骤（例：logic 禁止 E2E / ideusage / §alignment-checklist）
+
+### 0. 前置确认
+
+1. 从 `specs/manifest.md` 确认资产状态为 `🔴 red-done`
+2. 读取 `specs/<NN>-<资产名>/plan.md`（文件路径表 + 转换策略）
+3. 读取 `specs/<NN>-<资产名>/tasks.md`（Phase GREEN 任务组 + 行为等价矩阵）
+4. 确认测试文件存在且处于 FAIL 状态
+5. 更新 `specs/manifest.md`：状态 → `🟢 green-in-progress`
+6. 从 manifest 读取「类型」，选择 scaffold 分支
+
+### 1. 创建骨架（按资产类型）
+
+**component**：
+
+```bash
+bash <skill>/scripts/bash/create-component-files.sh \
+  --library-dir "<工程目录绝对路径>" \
+  --name "<资产名>" --title "<标题>" --type pc
+```
+
+**logic**：
+
+```bash
+bash <skill>/scripts/bash/create-logic-files.sh \
+  --library-dir "<工程目录绝对路径>" \
+  --name "<函数名 snake_case>" --title "<标题>" --type pc
+```
+
+**shared-composable**：
+
+按 plan.md 路径表 Edit 创建 composable 与测试文件（无 scaffold 脚本）。
+
+> 后续只能 Edit 增量修改，禁止 Write 全量重写（→ KB §process-scaffold）
+
+> **类型跳过**：logic / shared-composable 跳过步骤 2 api.ts、步骤 3 ideusage、步骤 5 Stories、步骤 6 CSS；仅执行对应实现与步骤 7 测试迭代。
+
+### component 实现顺序
+
+按 KB **§implementation-order** 1–8 步对照执行；模式细节见 KB §mixin-composable、§vue3-children-clone、§css-vars、§plugin-barrel、§pitfalls。
+
+- api.ts / ideusage / block.stories：以 `references/lcap-extension-component/` 为准（不在 KB 扩写）
+- 测试迭代：遵守 `workflow-guardrails.md` 分层规则
+
+### logic 实现
+
+`create-logic-files.sh` 生成骨架 → 按 `nasl-logic-authoring/SKILL.md` 实现函数体 → vitest 迭代。**跳过** api/ide/stories/css 步骤。
+
+### shared-composable 实现
+
+按 plan 锁定路径 Edit composable + vitest。**跳过** scaffold/api/ide/stories。
+
+### 2–6. 按类型执行实现步骤
+
+**component** 按 §implementation-order 与 references 完成 api.ts → ideusage → composables → index.vue → stories → CSS。
+
+**logic / shared-composable** 按上文对应分支执行，跳过 component 专属步骤。
+
+### 7. 迭代直到测试通过
+
+```bash
+npm run test
+```
+
+- 逐个修复失败测试对应的实现代码
+- 每修复一个测试，确认其他测试未回归
+- **路径以 plan.md 为基准**——路径失败时优先核对是否放错目录
+
+**全量回归（强制）**：
+
+```bash
+npm run test   # 全量 vitest，非仅当前资产目录
+```
+
+**Advisory 预检（component 且 manifest 已有其他 verified 组件时，非阻断）**：
+
+```bash
+npm run build
+npm run test:e2e
+```
+
+记录 exit 码于 green 报告「Advisory 预检」节；失败不阻止 `green-done`，但须 warn 用户 check 可能失败。
+
+### 8. 填充行为等价矩阵
+
+更新 tasks.md 中矩阵的"GREEN 实现"列：
+- 填入实现文件路径 + 行号/函数名
+
+### 9. 标记完成
+
+- tasks.md Phase GREEN 任务组全部标记 [x]
+- 更新 `specs/manifest.md`：状态 → `🟢 green-done`
+
+### 10. 报告
+
+输出：
+- 已实现文件列表（与 plan 文件路径表对照）
+- `npm run test` 通过证据（退出码 + 用例数）
+- 断路器是否触发（若触发，记录详情）
+- Advisory 预检结果（如有）：build / e2e exit 码
+- 下一步指引：`/migrate.check <资产名>` 执行等价性审计
+
+---
+
+## 断路器处理
+
+**触发条件**：同一错误模式连续 3 次修复失败。
+
+**处理流程**：
+1. **立即停止**当前修复循环
+2. **根因调查**：迁移方案本身有问题？第三方库不兼容 Vue3？
+3. **报告**：输出错误模式 + 已尝试方案 + 失败分析
+4. **等待用户决策**：
+   - 调整方案 → 回到 `/migrate.plan` 修改
+   - 标记为已知差异 → 在 tasks.md 矩阵中标注 ⚠️
+   - 标记资产 blocked → `specs/manifest.md` 标 🚫
+
+---
+
+## 关键规则
+
+- **目标已锁定**：RED 的测试定义了"什么是正确"，GREEN 只负责到达目标
+- **测试不可篡改**：禁止修改测试来让它通过——这会摧毁等价性保证
+- **路径以 plan 为准**：失败时优先核对是否放错目录
+- **骨架 Edit only**：`create-component-files.sh` 创建的文件后续只能 Edit（→ KB §process-scaffold）
+- **知识库优先**：不确定时以 knowledge-base 为准
+- **回归安全**：`npm run test` 全量运行，确保新增不破坏已有
+- **断路器不可忽视**：3 次同错必须停止，禁止第 4 次尝试相同思路
+- 必须使用中文进行状态更新与报告