🚀Skills First：重塑 AI 时代的 "上下文即代码" 前端架构1. 核心命题：跨越 "上下文鸿沟" (T

摘要：本文档旨在定义一套基于 "Context as Code" (上下文即代码) 的企业级前端架构方案。通过构建标准化的 Skills 知识图谱，弥合通用大模型 (LLM) 与私有领域知识 (Domain Knowledge) 之间的 "Context Gap"，实现从 "辅助编码" 到 "智能驱动" 的范式跃迁。

1. 核心命题：跨越 "上下文鸿沟" (The Context Gap)

在企业级应用开发中，通用 LLM (如 GPT-4, Gemini) 虽然具备极强的通用编程能力，但在落地时往往面临 "懂代码不懂业务" 的困境。

1.1 现状痛点

认知断层 (Cognitive Disconnect)：AI 不理解项目的原子设计系统 (Atomic Design)，导致生成的 UI 代码退化为原生 HTML/CSS，破坏视觉一致性。
架构熵增 (Architectural Entropy)：AI 倾向于生成孤立的工具函数，忽略项目中已存在的 Utils 或 Composables，导致代码库冗余度指数级上升。
规范漂移 (Standard Drift)：不同开发者使用不同的 Prompt 风格，导致 AI 生成的 API 接口定义风格迥异，破坏代码整洁架构 (Clean Architecture)。

1.2 解决方案：Context as Code (CaC)

我们将项目的 "隐性知识" (Tacit Knowledge) —— 包括目录结构、命名规范、设计原则、核心资产 —— 转化为机器可读的 "显性资产" (Explicit Assets)，即 Skills。

2. 顶层架构设计 (High-Level Architecture)

本方案采用 三层知识注入模型 (3-Layer Knowledge Injection Model)，通过 IDE Agent (如 Trae) 动态挂载上下文。

graph TB
    subgraph "User Interaction Layer"
        User["开发者"] -->|Intent & Prompt| Agent["AI Agent (Trae/Cursor)"]
    end

    subgraph "Context Orchestration Layer (The Brain)"
        Agent -->|Retrieve| SkillStore["Skills Knowledge Graph"]
        SkillStore -->|Inject Context| LLM["Large Language Model"]
    end

    subgraph "Skill Hierarchy (The Knowledge)"
        direction TB
        L1["Layer 1: Global Standards"]
        L2["Layer 2: Project Architecture"]
        L3["Layer 3: Domain Business"]

        L1 --> L2 --> L3
    end

    subgraph "Asset Layer (The Code)"
        LLM -->|Generate| Code["Production Code"]
        Code -->|Reflect| ProjectRepo["Project Repository"]
    end

    SkillStore -.-> L1
    SkillStore -.-> L2
    SkillStore -.-> L3

2.1 知识分层体系 (Skill Stack)

Layer 1: Global Standards (通用标准层)

定位：行业最佳实践，不可变基座。
资产：antfu/skills (Vue 3, TypeScript, Vitest, UnoCSS)。
作用：保证代码符合现代工程化标准（如使用 Composition API 而非 Options API）。

Layer 2: Project Architecture (项目架构层) —— 本方案核心

定位：项目级基础设施，可跨业务复用。
资产：
- cmc-components (UI Kit): 定义 CmcTable, CmcSelect 等高阶组件的契约。AI 必须通过调用组件而非手写 DOM 来构建界面。
- cmc-utils (Core Logic): 定义 useCrud, formatTime, validator 等核心逻辑。AI 必须复用现有 Hooks。
- cmc-api (Data Protocol): 定义 RESTful API 规范、Axios 拦截策略、Response 泛型包装。

Layer 3: Domain Business (业务领域层)

定位：特定业务域的规则与逻辑。
资产：业务实体定义 (Entity Definitions)、业务流程约束 (Business Rules)。
未来演进：通过 RAG (检索增强生成) 动态加载。

3. 核心机制与实施细节 (Implementation)

3.1 架构图：基于 Skills 的代码生成流

sequenceDiagram
    participant Dev as 开发者
    participant IDE as AI IDE (Trae)
    participant SK as Skill Manager
    participant LLM as Model

    Dev->>IDE: 生成一个出口订舱列表页，包含增删改查
    IDE->>SK: 语义分析 & 技能匹配
    SK-->>IDE: 激活 Skills: [cmc-components, cmc-utils, cmc-api]

    note right of IDE: Context Injection (上下文注入)
    IDE->>LLM: Prompt + <br/>Skill(CmcTable Props) + <br/>Skill(useCrud Usage) + <br/>Skill(API Modules)

    LLM-->>IDE: 生成代码

    rect rgb(240, 248, 255)
        note right of LLM: 产物特征<br/>1. Import { CmcTable } from '@/components'<br/>2. const { list, load } = useCrud(...)<br/>3. API 定义在 src/api/_modules/export-business/
    end

    IDE-->>Dev: 呈现代码 Diff

3.2 关键技术指标 (KPIs)

维度	传统 AI 辅助	基于 Skills 架构	提升幅度
UI 一致性	低 (频繁手写样式)	极高 (强制组件复用)	🚀 100%
代码冗余率	高 (重复生成 Utils)	低 (复用 Composables)	📉 -60%
Prompt 长度	长 (需反复强调规则)	短 (规则已内化)	📉 -40%
新人上手时间	2周+	2天 (AI 充当导师)	🚀 500%

4. 落地案例：CMC 项目实践 (Case Study)

4.1 UI 资产数字化 (`cmc-components`)

Before (AI 原生):

<el-table :data="tableData">...</el-table>
<!-- 原始 Element Plus，样式不统一 -->

After (Skill 驱动):

<CmcTable :columns="columns" :api="fetchData" use-selection />
<!-- 符合项目规范的高阶组件 -->

4.2 逻辑资产标准化 (`cmc-utils`)

Before: AI 手写 axios 调用，手动处理 try-catch 和 loading 状态。 After:

const { list, loading, refresh } = useCrud({
  api: queryBookingList // 自动引用定义好的 API
})

4.3 接口定义规范化 (`cmc-api`)

规范强制：所有新 API 必须落入 src/api/_modules/，并遵循 kebab-case 命名，自动集成重试与错误拦截。

5. 全栈实现演示 (Full-Stack Implementation Demo)

本节展示一个完整的业务场景："出口订舱列表" 的实现，展示 Skills 架构如何协同工作。

5.1 开发者意图 (User Intent)

"创建一个出口订舱列表页面，包含搜索、分页、新增和删除功能。"

5.2 AI 生成的最终代码 (Generated Code)

AI 在 cmc-components, cmc-utils, cmc-api 三个 Skill 的共同驱动下，生成的标准代码如下：

<script setup lang="ts">
import type { BookingItem, BookingParams } from '@/api/_modules/export-business/booking/types'
import type { TableColumnConfig } from '@/components/CmcTable'
/**
 * @file 出口订舱列表
 * @description 展示基于 Skills 架构的标准业务页面
 */
import { ref } from 'vue'
import { deleteBooking, queryBookingList } from '@/api/_modules/export-business/booking'
import { CmcTable } from '@/components/CmcTable'
import { useCrud } from '@/composables/business/useCrud'

// 1. 复用 useCrud 逻辑 (cmc-utils Skill)
const {
  list,
  loading,
  pagination,
  queryParams,
  handleSearch,
  handleReset,
  handleDelete
} = useCrud<BookingItem, BookingParams>({
  api: queryBookingList,
  deleteApi: deleteBooking,
  defaultParams: { status: 1 }
})

// 2. 配置 CmcTable 列定义 (cmc-components Skill)
const columns: TableColumnConfig<BookingItem>[] = [
  {
    prop: 'bookingNo',
    label: '订舱号',
    width: 180,
    fixed: 'left'
  },
  {
    prop: 'vesselName',
    label: '船名',
    minWidth: 150
  },
  {
    prop: 'voyageNo',
    label: '航次',
    width: 120
  },
  {
    prop: 'status',
    label: '状态',
    type: 'tag',
    width: 100
  }, // 自动使用 Tag 组件
  {
    type: 'operation',
    label: '操作',
    width: 150,
    buttons: [
      {
        text: '编辑',
        type: 'primary',
        link: true,
        onClick: row => navigateToEdit(row)
      },
      {
        text: '删除',
        type: 'danger',
        link: true,
        popconfirm: '确认删除?',
        onClick: row => handleDelete(row)
      }
    ]
  }
]
</script>

<template>
  <div class="page-container">
    <!-- 3. 使用 CmcTable 高阶组件 (cmc-components Skill) -->
    <CmcTable
      v-model:page="pagination.current"
      v-model:page-size="pagination.size"
      :data="list"
      :loading="loading"
      :columns="columns"
      :total="pagination.total"
      @refresh="handleSearch"
    >
      <!-- 搜索插槽 -->
      <template #search>
        <el-form inline>
          <el-form-item label="订舱号">
            <el-input v-model="queryParams.bookingNo" placeholder="请输入" />
          </el-form-item>
          <el-form-item>
            <el-button type="primary" @click="handleSearch">
              查询
            </el-button>
            <el-button @click="handleReset">
              重置
            </el-button>
          </el-form-item>
        </el-form>
      </template>
    </CmcTable>
  </div>
</template>

6. 企业级 Skill 标准定义规范 (Enterprise Skill Standard)

为了保证 Skills 的高质量和一致性，所有新增 Skill 必须遵循以下 Standard Operating Procedure (SOP)。

6.1 Skill 文件结构模板

每个 Skill 本质上是一个 Markdown 文件，建议存放在 .trae/skills/<skill-name>/SKILL.md。

---
name: <skill-kebab-name> (e.g., cmc-components)
description: <Short description for AI routing> (e.g., Core UI components for admin panel)
version: 1.0.0
---

# <Skill Title>

## 1. 核心原则 (Core Principles)

_简要阐述该 Skill 的设计哲学和不可违背的红线。_

- **原则一**：禁止使用内联样式，必须使用 UnoCSS。
- **原则二**：所有组件必须支持 TypeScript 类型提示。

## 2. 最佳实践 (Best Practices)

### 2.1 <Feature A>

_描述该特性的正确用法。_

**❌ 错误示例 (Don't):**

```html
<div class="card">...</div>
```

✅ 正确示例 (Do):

<CmcCard title="Title">...</CmcCard>

3. 常见陷阱 (Common Pitfalls)

列出 AI 容易犯错的点。

不要在 CmcTable 外部再包裹 el-card，组件内部已包含。
useCrud 的 api 参数必须返回 Promise。

4. 类型定义参考 (Type Reference)

提供关键的 TypeScript 接口定义，帮助 AI 理解参数结构。

export interface TableColumnConfig<T> {
  prop: keyof T
  label: string
  width?: number
  // ...
}

6.2 Skill 编写黄金法则

Context Density (上下文密度)：不要写废话。AI 的 Context Window 是昂贵的，只写"AI 不知道的"私有知识。
Negative Prompting (负向提示)：明确告诉 AI "不要做什么" 往往比告诉它 "要做什么" 更有效（例如："不要手动引入 Element Plus，已自动按需加载"）。
Code-First (代码优先)：AI 学习代码的能力远强于学习自然语言。多给 Code Snippet，少写长篇大论。

7. 未来规划与演进路线 (Future Roadmap)

作为架构师，我们不能止步于静态的 Markdown 文档。未来的 AI-Native DevOps 将包含以下演进：

Phase 1: 静态知识库 (Current)

人工编写 .trae/skills/*.md。
基于规则的上下文注入。

Phase 2: 动态知识图谱 (Q3 2026)

AST 自动提取：编写脚本自动扫描 src/components 和 src/composables，利用 TS 类型定义自动生成 Skill 文档。
CI/CD 集成：代码合并时自动更新 Skills，保证知识库与代码库的原子一致性 (Atomic Consistency)。

Phase 3: 语义检索增强 (Q4 2026)

Vector Database (向量数据库)：将海量业务代码 embedding 化。
RAG (Retrieval-Augmented Generation)：当用户问 "如何计算滞箱费" 时，系统自动检索相关业务规则代码块作为 Context，而不仅限于通用的 Skills。

Phase 4: 自进化架构 (2027+)

Feedback Loop：收集用户对 AI 生成代码的采纳/修改记录，反向微调 (Fine-tune) 私有小模型，让 AI 真正 "长出" 项目的特有基因。

8. 结语

软件工程的核心在于 控制复杂度。在 AI 时代，复杂度从 "代码实现" 转移到了 "上下文管理"。

通过构建这套 Context as Code 架构，我们不仅仅是在写代码，更是在构建一个 "数字孪生" (Digital Twin) 的开发环境，让 AI 成为真正理解项目灵魂的 Co-Pilot，而非仅仅是一个懂语法的打字机。

Architect's Note: 技术不应仅是工具的堆砌，更应是思想的结晶。本方案致敬 antfu 的极简主义哲学，并结合企业级开发的严谨性，致力于探索 AI 时代的最佳工程实践。

🚀Skills First：重塑 AI 时代的 "上下文即代码" 前端架构