devlab-web-engineering

Web / 前端工程化能力层。从工程化六域入手，覆盖项目初始化、构建、依赖、打包与交付、 运行环境与工程规范，按「语言 × 框架」路由到对应 Profile 执行，一站式交付可构建、 可打包、可部署的前端项目。

Capability Layer 定位：本技能是能力层，负责工程化原则、能力编排、Profile 与 工程质量要求；不承接完整用户需求，不重复造底层工具——优先复用社区 Skill / Reference / CLI / MCP 及现有 DevLab Capability（create-vue / create-vite / 框架官方文档等只引用不重写）。 UI/UX 品味、视觉操作、QA/测试、Contract、CI/CD 等独立领域能力不在此范围（见 Out of Scope 路由表）。

触发条件

需要输出 Web 技术、集成或安全架构图时，消费 base-diagram-ops 的 web、integration、security profile；本技能提供 Web 工程事实，不实现图布局或导出器。

• 用户说"初始化前端项目工程""配构建配置""帮我打包前端""工程化规范"
• 新项目需要工程化引导（识别语言×框架后路由到对应 profile）
• 现有项目构建/打包/容器化/微前端排障（构建失败、产物异常、镜像路径等）
• 从旧式打包（无锁文件 / CRA）迁移到现代模式（Vite / lockfile / pnpm）
• devlab-project-bootstrap Phase 4 编排路由（前端项目工程化初始化）

输入参数

参数	必填	说明	示例
workspace	否	项目工作目录（默认当前目录）	/workspace/my-web
framework	否	框架显式指定（默认自动识别）	vue / react
workflow	否	只跑指定流程（默认全流程）	bootstrap / build / packaging

语言 × 框架识别路由

路由键 = 语言 × 框架 双维。先识别语言（决定工程基线），再识别框架（决定加载哪个 Profile）。

语言维度

语言	处理
TypeScript（主线）	默认基线，所有 profile 按 TS 工程标准（tsconfig 严格模式、类型检查入 lint）
JavaScript（兼容）	profile 内降级差异：JSDoc 替代类型、跳过 tsc 类型检查
其他（扩展位）	references 层预留说明；WASM 等后续版本再建 profile

框架维度（识别信号）

识别信号	框架	Profile
package.json 含 vue / vue-router / @vue/cli-service / nuxt	vue	profiles/vue.md
package.json 含 react / react-dom / next	react	profiles/react.md
package.json 含 @angular/core / angular.json	angular	references 引用层
多种并存 / 识别不到	—	进 Phase 0 D0 卡片让用户确认

构建工具（Vite 主线 / Webpack 兼容 / Next.js 等）在 profile 内 toolchain 层识别，不作为路由键。

工作流

Phase 0: 决策确认（内建）  ← 关键分歧在此收敛（语言×框架/包管理器×工具链/端口/运行时/制品源/环境变量/编排）
    ↓ decisions
Phase 1: 工程化基线分析（内建）→ project_profile（框架、构建工具、依赖、容器现状）
    ↓ project_profile
Phase 2: 按路由键分发
    ├─ vue   → profiles/vue.md（实战级：六域完整工作流 + 微前端场景层）
    └─ react → profiles/react.md（模板级）
    ↓ 各 profile 执行 bootstrap / build / packaging 对应 workflow
Phase 3: 验证闭环（内建）→ verification_report（脚本验证 + 构建验证 + 启动探测）

核心原则：Phase 0 收敛所有工程决策后再动手修改。禁止在决策未确认的情况下 直接修改 package.json / vite.config.* 等工程文件。

Phase 0: 决策确认

目标：在进入任何配置修改之前，把关键分歧点一次性摆到用户面前，让用户拍板。

0.1 快速扫描（自动）

0. 识别语言与框架（最先做，见路由表）
1. 检测 package.json 是否存在 → 不存在则标记为「从零创建」
2. 扫描现有 scripts / 构建配置（vite.config.* / webpack.config.* / next.config.*）→ 判断当前构建模式
3. 扫描依赖目录（node_modules/）与锁文件（package-lock.json / pnpm-lock.yaml / yarn.lock）
4. 扫描仓库配置（.npmrc / .yarnrc）→ 是否已指向私有 registry
5. 扫描 Dockerfile / nginx.conf / docker-compose.yml → 判断交付方式
6. 探测运行时（顺序）：
   a. PATH 中的 node
   b. 回退常见版本管理器路径（nvm / fnm / volta）
   c. 都没有 → 标记缺失，进 D3 提示安装
7. 探测包管理器（npm / pnpm / yarn）与构建工具可执行性，缺失只告警不阻断

0.2 决策卡片（展示给用户确认）

## 📋 前端工程化决策确认

### 自动检测结果
| # | 检测项 | 结果 | 来源 |
|---|--------|------|------|
| 0 | 语言/框架 | {ts/vue / ts/react / js/vue ...} | package.json |
| 1 | 构建工具 | {vite / webpack / next / 未检测到} | 构建配置文件 |
| 2 | 包管理器 | {npm / pnpm / yarn} | packageManager + 锁文件 |
| 3 | 运行时版本 | {18 / 20 / 22} | .nvmrc / engines / 探测 |
| 4 | 制品源 | {私有 registry / 官方源} | .npmrc |
| 5 | 已有脚本 | {N 个 / 无} | scripts/ 目录 |
| 6 | 容器化交付 | {有 Dockerfile / 无 / 有 nginx.conf} | 文件系统扫描 |

### 需要你确认的决策

**D0. 语言×框架确认**（仅在识别不到或多种并存时询问）
  识别结果: {ts/vue / ts/react / 未识别}
  → 确认: ____

**D1. 包管理器×工具链选择**
  - 包管理器: npm（主线）/ pnpm（推荐 monorepo）/ yarn
  - 构建工具: Vite（主线）/ Webpack（存量兼容）
  → 你的选择: ____

**D2. 端口策略**（多开发者环境）
  A. 固定端口（单开发者）[推荐]
  B. 动态分配（多开发者）
  C. 用户名哈希（避免冲突）
  → 你的选择: ____

**D3. 运行时版本确认**（探测结果确认或修正）
  → 确认: ____

**D4. 制品源 registry 策略**
  A. 私有源 + 官方源降级 [推荐]
  B. 仅官方源
  → 你的选择: ____

**D5. API 地址**（默认从 devlab-infra-usage 读推荐值，非必问）
  → 确认: ____

**D6. 环境变量规范**
  A. .env.local（个人）+ .env.development（团队共享）[推荐]
  B. 只用 .env.local
  → 你的选择: ____

**D7. monorepo 编排 + 已有脚本冲突**（检测到时询问）
  - 生成 orchestrator.sh: [是/否]
  - 已有脚本处理: [保留并新目录 / 覆盖 / 合并函数 / 跳过]
  → 你的选择: ____

0.3 决策锁定

用户确认后，将决策固化为 decisions 对象，后续所有 Phase 以此为准（示例）：

decisions:
  language: ts              # D0: ts | js
  framework: vue            # D0: vue | react
  build_tool: vite          # D1
  package_manager: pnpm     # D1
  port_strategy: fixed      # D2
  runtime_version: "20"     # D3
  registry_strategy: fallback  # D4
  env_var_spec: layered     # D6
  orchestrator: true        # D7
  existing_scripts: merge   # D7

约束：language × framework 决定 Phase 2 加载哪个 profile；具体工具链逻辑 下沉到 profile 的 toolchain/reference，主体只做识别与路由。

Out of Scope 路由表

需求	路由到
UI/UX 品味、视觉精修、Design System	devlab-ui-taste-ops
浏览器操作/截图/视觉回归/视觉走查	devlab-web-visual-ops
QA 验收、质量门禁、上线前检查	devlab-qa-ops
测试体系搭建 / E2E 用例	devlab-test-onboard / devlab-web-test-e2e
Web↔Server 契约（接口/序列化一致性）	devlab-contract-web-server
CI/CD 管线编排	devlab-cicd-onboard
浏览器扩展（WebExtension/MV3）	devlab-web-extension-bootstrap
State Management 方案选型（业务架构决策）	业务架构/领域设计（暂无专有资产，不建实体）
基础设施信息查询（Nexus/registry/API 地址）	devlab-infra-usage

可观测性接入基线

本技能不直接部署监控后端或把业务 telemetry 发往任意硬编码地址。Web 项目统一由 devlab-observability-onboard 编排：基础设施 profile 由 devlab-infra-usage 提供，后端 OTLP 由 infra-otlp-ops 执行，前端错误/RUM/性能按项目路由到 infra-glitchtip-ops 或 devlab-web-skywalking-rum-usage。

前端交付前必须明确以下信号：

• 浏览器性能：记录 Web Vitals、资源/导航耗时和前端路由变化；标签和事件属性使用页面/路由模板等低基数值，不上传完整 query、用户输入或隐私字段。
• 前端错误：统一错误边界、未处理 Promise rejection 和资源加载错误；错误事件带 release、environment、route 和可关联 trace/request id，源码映射只由受控构建流程上传。
• 日志：生产不依赖 console.log 作为日志管道；调试日志默认关闭或受运行时开关控制，禁止在浏览器端输出 token、Cookie、Authorization 和完整 API 响应。
• 告警：前端错误率、关键交互失败和 Web Vitals 阈值由错误追踪/中心告警平台管理，业务代码只上报事件，不直接调用通知渠道。
• Trace/RUM：浏览器不得直连内部 OTLP Collector；通过批准的同源 tunnel、后端代理或 RUM 专用入口发送，并在 .platform/observability.yml 声明数据域和采样策略。

验收至少覆盖：生产构建不泄露 secret、一次真实页面访问产生性能/错误证据、敏感字段未进入事件、release 与 source map 可关联，以及后端 Trace（如启用）能通过 request/trace id 关联。

Integration Points

目标资产	类型	方向	契约（输入→输出）
devlab-infra-usage	skill	outbound	查询 registry 地址/凭据/API 推荐值 → 仓库与环境配置
devlab-web-context	skill	inbound/outbound	模式A：被委托按 profiles/ 规则扫描 → 画像；工程化改动前消费 context 画像
devlab-cicd-onboard	skill	outbound	构建配置完成后 → CI/CD 管线接入
devlab-project-bootstrap	skill	inbound	Phase 4 编排路由 → 本技能执行前端工程化初始化
devlab-qa-ops	skill	outbound	工程化交付后 QA 验收（横向 web/srv）
devlab-ui-taste-ops	skill	outbound	UI 精修/设计边界（组件工程结构归本技能，视觉/交互归 ui-taste-ops）
devlab-web-extension-bootstrap	skill	outbound	浏览器扩展场景路由

约束

• Phase 0 决策优先：所有工程配置修改必须基于 Phase 0 用户确认的 decisions，禁止跳过。
• 路由键不绑死：语言×框架识别与工具链具体逻辑一律下沉到 profiles/{framework}.md 及 其 toolchain/reference，主体只做识别与路由；新增框架按 profiles/ 目录骨架扩展。
• 不重复造轮子：社区成熟方案（create-vue / create-vite / 框架官方脚手架）优先引用， 不重新实现底层工具。
• 不自动修改业务代码：只生成/修改工程配置文件与脚本，不改 src/ 目录业务代码。
• 不覆盖已有脚本：检测到同名文件时提示用户选择。
• 不包含私有信息：生成的 .env.local.example 只有占位符；registry/API 地址从 devlab-infra-usage 获取，不硬编码。
• 增量生成：已有部分脚本时只补充缺失的。
• Bash 兼容性：要求 Bash 4.0+，兼容 Linux/macOS。
• 交互限制：最多 8 个决策点（D0-D7），不确定时用合理默认值。
• 验证强制：所有生成的 .sh 必须通过 bash -n 和 shellcheck。
• 不自动执行 npm publish / 部署命令，仅生成命令供用户确认。

配置上下文

本技能运行时配置通过 devlab-infra-usage 技能获取，包括：

• 私有 npm registry 地址与凭据（.npmrc 配置模板）
• 推荐 API 地址（devlab-infra-usage 查询）
• 部署目标信息

配置优先级：devlab-infra-usage 查询结果 > 项目已有配置 > 本技能默认值。

专题引用

框架 Profile（Phase 2 按框架加载）

• Vue（实战级，含 Vite 主线/Webpack 兼容 toolchain + 微前端场景层）： profiles/vue.md
• React（模板级）：profiles/react.md

流程（workflows/）

• bootstrap：项目初始化工程化流程
• build：构建流程
• packaging：打包与交付流程（容器化/静态部署/微前端）

原则（principles/）

• 构建可复现性
• 依赖治理
• 项目结构
• 环境一致性

知识库（references/）

• 索引
• 社区引用清单
• 构建工具配置（跨框架）
• Monorepo 管理
• Node 版本管理
• Registry 策略

库使用指南（usage 家族）

• ECharts 集成：tree-shaking、IntersectionObserver 按需加载、Astro Islands 数据传递
• @xyflow/react：核心概念、自定义节点、Astro Islands 集成、踩坑经验

示例

示例 1：新 Vue3 + Vite 项目工程化初始化（完整流程）

用户说："帮我初始化一个 Vue3 + Vite + TS 的前端工程，生成开发脚本。"

Phase 0: 识别 ts/vue → 输出决策卡片
  → D1=Vite+pnpm, D2=固定端口, D3=Node 20, D4=私有源降级, D5=API 默认值, D6=分层 .env
Phase 1: 扫描项目结构 → project_profile
Phase 2: 路由 profiles/vue.md → 六域配置（tsconfig/ESLint/Prettier/依赖/脚本）
Phase 3: 生成 scripts/*（dev/build/test/lint/doctor）→ bash -n + shellcheck → 验证报告

示例 2：存量 Vue 微前端项目构建排障

用户说："微前端子应用构建后主应用加载不到。"

Phase 0: 识别 vue + qiankun → 决策卡片
Phase 2: 路由 profiles/vue.md 微前端场景层 → 检查 base 配置/子应用注册/端口协调
Phase 3: 构建验证 → 输出报告

示例 3：React 项目迁移到 Vite

用户说："把 CRA 项目迁移到 Vite。"

Phase 0: 识别 react + CRA → 决策卡片（迁移确认）
Phase 2: 路由 profiles/react.md → vite 迁移 checklist（react-scripts → vite）
Phase 3: 构建验证 → 输出报告

Human Decisions

结构化同源见 decisions.yaml；以下为人类可读汇总。

#	决策点	触发条件	选项	默认行为
HD-1	工程配置修改确认（改造前）	Phase 0 分析现有工程配置后、修改 package.json/构建配置之前	用户确认架构判断后再改造 / 补充分析	必问
HD-2	工具版本卡片选择确认	展示 Node 多版本工具卡片、需选定版本时	用户确认版本选择 / 采用推荐默认	必问
HD-3	已有脚本冲突处理	D7 检测到已有 scripts 时	覆盖 / 合并 / 跳过	必问