概述

本文详细阐述基于 AI Agent 的前端代码生成完整方案，涵盖 A、B、C 三类层层递进的核心工作流，以及配套的 RAG V2.0 检索优化系统。方案通过 DSL（领域特定语言）、模板系统及 RAG 检索技术，实现从业务需求（设计稿、PRD、GUI 配置等）到可直接复用代码的自动化生成，核心目标是提升前端开发效率、降低研发成本，同时保障代码规范性、可维护性与可扩展性。

三类核心工作流各有侧重、层层递进，适配不同复杂度的开发场景：

• C 类（基础方案）：实现“DSL 配置→模板映射→代码生成→工程校验”的基础闭环，是整个方案的核心底座，目前已融合至 B 类工作流，重点阐述其实现原理以支撑后续扩展方案的理解。
• B 类（扩展方案）：在 C 类基础上，新增 JSSlot 组件生成、Blocks 代码组合能力，适配更复杂的页面生码需求，解决基础方案无法覆盖的自定义组件、代码片段集成场景。
• A 类（高级方案）：无需预定义 DSL 模板，支持从 Figma 设计稿（Figma2DSL 转换）或纯文本 PRD 直接生成完整代码，实现“需求→结构→代码”的端到端生成，依赖项目规划师与 RAG_Agent 解决生码幻觉问题。

配套的 RAG V2.0 检索优化系统，作为全方案的支撑核心，将 RAG 从“黑盒能力”升级为“工程化系统”，解决生码过程中的上下文不足、检索不稳定等痛点，为三类工作流提供精准、稳定的检索支撑，进一步提升生码准确率。

一、C 类代码生成（基础方案）

C 类方案是整个 AI Agent 生码体系的基础，核心实现“DSL 配置→模板映射→代码生成→工程校验”的完整闭环，目前已无缝融合至 B 类工作流，此处重点拆解其核心实现原理，为理解后续扩展方案提供支撑。

1.1 工作流输入

输入为图形界面（GUI）生成的标准化 DSL 配置，该配置完整描述业务意图、组件依赖及代码结构，是代码生成的核心依据，无需额外手动补充信息，典型示例如下：

{
  "version": "1.1.0",
  "templateId": "1001",
  "componentRegistry": [
    {
      "package": "@slds/finance-template-market",
      "version": "1.0.0",
      "exportName": "TablePage",
      "main": "src/index.tsx",
      "isDestruct": true,
      "componentName": "TablePage"
    },
    {
      "devMode": "lowCode",
      "componentName": "Page"
    }
  ],
  "pageTree": [
    {
      "componentName": "Page",
      "id": "node_page_root",
      "props": {},
      "hidden": false,
      "isLocked": false,
      "condition": true,
      "children": [
        {
          "componentName": "TablePage",
          "id": "node_table_page",
          "props": {
            "searchFields": [
              { "type": "input", "label": "关键词", "required": false }
            ],
            "operation": [
              { "type": "primary", "name": "新增", "actionType": "button", "buttonType": "primary" }
            ],
            "tableColumns": [
              { "title": "关键词", "type": "input", "ellipsis": false, "sorter": false, "fixed": false },
              {
                "title": "操作",
                "type": "action",
                "ctrlProps": { "action": [{ "label": "查看" }, { "label": "编辑" }, { "label": "删除" }] },
                "fixed": "right"
              }
            ],
            "massTool": {
              "support": true,
              "text": "账单订单",
              "button": [{ "type": "default", "text": "导出", "name": "Export", "actionType": "button" }]
            },
            "enableSearch": true,
            "enableOperation": true,
            "enableRowSelection": false
          },
          "hidden": false,
          "isLocked": false,
          "condition": true
        }
      ]
    }
  ],
  "i18n": { "zh-CN": {}, "en-US": {} }
}

1.2 工作流实现

C 类方案核心分为三大环节：代码生成、工程化校验、错误修复，形成“生成-校验-修复”的完整链路，确保输出的代码可直接集成至项目中使用，无需额外手动修改。

1.2.1 代码生成核心逻辑

采用“样板间模板 + DSL 语义映射”的核心思路，通过标准化生码提示词，从项目模板树中提取最小可用文件集合，并注入 DSL 中定义的业务逻辑，具体流程如下：

其中，生码提示词定义了 AI Agent 的角色与操作规范，确保生码过程的一致性与规范性，核心提示词如下（精简核心规则，避免冗余）：

## 角色定位
资深 React 前端架构师 | 构建专家（Bundler Specialist）
核心能力：语义映射、智能剪枝（Tree-Shaking）、代码清洗（Linting）

## 核心任务
基于业务 DSL `<dsl_schema>`，从项目模板树 `<template_tree>` 中提取最小可用文件集合，并完成业务逻辑注入 + 代码深度清洗。

## 输入规范
1. `<dsl_schema>`：业务定义（页面、字段、逻辑开关）
2. `<template_tree>`：原始项目文件树（唯一合法代码数据源）

---

## 执行工作流
### Step 1 智能剪枝 | 依赖图谱构建（Tree-Shaking）
核心规则：严禁编造文件路径，仅使用模板树内现有文件
1. 标记唯一入口文件
   - 从 `<template_tree>` 中定位唯一业务入口（固定为层级内 `index.tsx`），标记为 Entry File
   - 扫描 `<dsl_schema>`，标记直接依赖的业务文件为 Active 文件
2. 递归依赖追踪
   - 遍历 Entry File + Active 文件的所有 import 依赖，逐层标记为 Active
   - 未标记文件 = 死代码，最终输出彻底剔除

### Step 2 语义映射 | 代码深度清洗（仅处理 Active 文件）
1. DSL 业务注入
   - 按 `<dsl_schema>` 填充表单字段、验证规则、业务逻辑
2. 无用功能智能清理
   - DSL 中 `support: false` / 未配置的功能：无外部引用 → 删除对应代码；有引用 → 保留空实现
3. Import 强制清洗（关键）
   - 逐行校验导入项：未使用 → 移除；整行无使用 → 删除整行
4. API 标准化处理
   - `api/` 目录所有导出函数，顶部添加 `// Mock` 注释
5. 表格 Mock 强制规则
   - 含表格组件 → 生成 4 条业务语义 Mock 数据
   - 字段完全匹配 DSL columns，禁用无意义占位符（test/xxx）
   - 数据上方添加 `// Mock Table Data` 注释
6. 完整性自检
   - 所有 import 路径必须指向本次输出文件，无无效引用

---

## 绝对约束（强制执行）
### 1. 输出格式
- 仅输出扁平化 JSON 数组，禁止树形结构/Markdown
- 固定结构：`{"path":"根目录完整路径","code":"代码字符串"}`
- 唯一入口文件必须添加 `"entry": true`，其余文件无此字段

### 2. 代码卫生红线
- 禁止未使用的 import 语句
- 禁止输出无依赖、无使用的僵尸文件
- 禁止破坏跨文件依赖（A 输出 → A 依赖的 B 必须输出）
- 禁止编造模板树中不存在的文件路径

---

## 输出示例（严格遵循格式）
[
  {
    "path": "src/pages/demo/table/index.tsx",
    "code": "import { Table } from 'spc-ui-react';\nconst Page = () => <Table />;\nexport default Page;",
    "entry": true
  },
  {
    "path": "src/api/table.ts",
    "code": "// Mock\nexport async function getTableList() {\n  // Mock Table Data\n  return Promise.resolve([{id:1,name:'Alice'},{id:2,name:'Bob'}]);\n}"
  }
]

1.2.2 工程化校验

代码生成后，通过多维度工程化校验杜绝基础错误，确保代码可正常构建与运行，校验流程如下：

1.2.3 修复节点实现

针对校验过程中出现的错误，采用 AI 前端代码修复专家提示词进行精准修复，仅执行一轮修复，严格遵循错误优先级，确保修复不破坏原有业务逻辑，核心提示词如下：

## 角色定位
AI 前端代码修复专家，专注运行时/构建/TS/ESLint 多维度错误精准修复，精通前端工程化与 SPC UI 组件库规范。

## 核心铁律（不可违反）
1. 优先级刚性：运行时错误(P 0) > 构建错误(P 1) > TS 错误(P 2) > ESLint(P 3)
2. 最小侵入原则：仅修复错误，禁止重构、禁止修改原有业务逻辑
3. 上下文诚实原则：缺类型/缺外部文件/缺依赖定义时，必须精准标注缺失信息，严禁猜测修复
4. SPC 专属约束：涉及 SPC UI 组件错误，仅参考输入的 error_repair_collection，严禁参照 Ant Design 等其他组件库

## 输入结构
接收 JSON 格式输入，包含：
- `source_files`：源码文件数组（`path`/`code`）
- `error_report`：四类错误（`runtime_err`/`build_err`/`typescript_err`/`eslint_err`）
- `error_repair_collection`：SPC UI 组件专修案例集

## 分级修复策略
### P 0 运行时错误（最高优先级）
1. 定位：优先通过 `mappedStack`/`stack` 定位源码行，信息模糊则按函数/组件名全局匹配
2. 标准修复：
   - `ReferenceError`：补全 import、校验作用域、增加空值检查
   - `null/undefined TypeError`：强制使用可选链 `?.`、空值合并 `??`
   - React Hook 违规：修正 Hook 执行位置、补全必要依赖项
3. 兜底：无法安全修复时，增加逻辑守卫或 Error Boundary 避免白屏

### P 1/P 2 构建 & TypeScript 错误
1. 路径错误：修正相对路径；引用文件不在 `source_files` 且无法推断 → 标记上下文缺失
2. SPC UI 专修流程：
   - 匹配修复集中组件名/属性名/错误信息一致的案例
   - 命中案例：严格按 `fix_pattern`/示例代码修复
   - 未命中案例：禁止臆测属性，归入无法修复，注明“修复集未覆盖该组件场景”
3. TS 兜底：非修复集范畴的泛型/类型冲突，可使用 `any` 或 `// @ts-ignore`，并标注原因

### P 3 ESLint 错误
- 仅修复 `severity: 2` 阻断性问题
- 未使用变量：添加 `_unused` 前缀
- 保留所有带业务注释的代码，禁止删除

## 执行任务流
1. 错误解析：按文件归类错误
2. 上下文校验：判断是否具备完整修复条件
3. 顺序修复：严格按 P 0→P 3 执行代码修改
4. 完整性校验：检查无新增语法错误，`import` 完整有效

## 输出强制规范（绝对禁令）
1. 禁止输出任何自然语言、解释、开场白、结尾，仅返回合法 JSON
2. 结构严格遵循下方格式

{
  "fixed_files": [
    {
      "path": "string",
      "entry": "true|false",
      "code": "string"
    }
  ],
  "fixed_report": {
    "summary": {
      "totalErrors": 0,
      "fixedErrors": 0,
      "unfixableErrors": 0,
      "filesModified": 0,
      "errorBreakdown": {
        "runtime": 0,
        "build": 0,
        "typescript": 0,
        "eslint": 0
      }
    },
    "fixedDetails": [
      {
        "filePath": "string",
        "errorType": "runtime|build|typescript|eslint",
        "errorSubType": "string",
        "originalError": { "line": 0, "message": "string" },
        "fixMethod": "string",
        "codeChange": { "before": "string", "after": "string" }
      }
    ],
    "unfixableDetails": [
      {
        "filePath": "string",
        "error": "string",
        "reason": "string",
        "missing_context": "string",
        "suggestion": "string",
        "priority": "high|medium|low"
      }
    ]
  }
}

1.3 工作流输出

输出为扁平化 JSON 数组，包含入口文件、API 接口文件、核心组件文件，贴合 DSL 配置的表格业务场景，包含规范的 Mock 数据与注释，可直接生成至插件目录集成使用，示例如下：

[
  {
    "path": "src/pages/table/index.tsx",
    "code": "import { TablePage } from '@slds/finance-template-market';\nimport { useState } from 'react';\n\n// Mock Table Data（贴合账单订单业务）\nconst mockTableData = [\n  { id: 1, 关键词: '账单001', 状态: '生效' },\n  { id: 2, 关键词: '账单002', 状态: '草稿' },\n  { id: 3, 关键词: '账单003', 状态: '停用' },\n  { id: 4, 关键词: '账单004', 状态: '生效' },\n  { id: 5, 关键词: '账单005', 状态: '草稿' }\n];\n\nconst TablePageIndex = () => {\n  return <TablePage tableData={mockTableData} />;\n};\n\nexport default TablePageIndex;",
    "entry": true
  },
  {
    "path": "src/api/bill.ts",
    "code": "// Mock 账单相关接口\nexport async function getBillList() {\n  return { code: 200, data: mockTableData, message: 'success' };\n}\nexport async function exportBillList() {\n  return { code: 200, message: '导出成功' };\n}"
  },
  {
    "path": "src/components/TablePage/index.tsx",
    "code": "// 表格页面组件（从模板树提取，注入 DSL 逻辑）\nexport const TablePage = (props) => {\n  const { tableData, searchFields, operation } = props;\n  return (\n    <div>\n      {/* 搜索表单 */}\n      <div>{searchFields.map(field => /* 渲染搜索字段 */)}</div>\n      {/* 操作按钮 */}\n      <div>{operation.map(btn => /* 渲染操作按钮 */)}</div>\n      {/* 表格渲染 */}\n      {/* 表格内容渲染，使用 mockTableData */}\n    </div>\n  );\n}"
  }
]

二、B 类代码生成（扩展方案）

B 类方案是 C 类基础方案的扩展升级，在“DSL+模板”的核心逻辑上，新增 JSSlot 组件从零生成、Blocks 代码片段集成能力，解决 C 类方案无法覆盖的复杂页面场景（如自定义组件、局部代码复用），同时完全继承 C 类的约束规则与工程化校验流程。

2.1 工作流输入

基于 C 类 DSL 配置进行扩展，分为三种核心应用场景，适配不同的复杂生码需求：

• case 1：C + Slots【GUI DSL】：新增 JSSlot 配置，支持自定义组件从零生成，适配页面局部自定义需求。
• case 2：C + Blocks【GUI DSL】：新增 Blocks 配置，支持已有代码片段的封装与集成，提升代码复用率。
• case 3：C + Slots + Blocks【GUI DSL】：兼顾 JSSlot 与 Blocks 能力，满足复杂页面的多场景生码需求。

输入除 C 类所需的 DSL 配置、项目模板树外，额外增加：JSSlot 场景需提供 <slot_sign>（组件类型签名），Blocks 场景需提供 <blocks_code>（待集成代码片段）。

2.2 工作流实现

核心逻辑为“C 类基础流程 + JSSlot/Blocks 扩展流程”，实现“模板生成 + 自定义组件 + 代码片段”的组合生成，确保扩展能力不破坏基础生码逻辑，流程如下：

对应三种场景，提供三套核心生码提示词，均继承 C 类的所有约束规则，新增组件生成、代码组合的专属规则，强制使用 spc-ui-react 组件库，杜绝原生表单、按钮等组件的使用，以下为三套提示词的核心差异与精简版本：

2.2.1 B1 类出码核心提示词（C + Slots）

核心新增 JSSlot 组件从零生成与局部替换能力，核心规则如下：

## 角色定位
资深 React 前端架构师 + Bundler 构建专家
核心能力：语义映射（Semantic Mapping）、智能剪枝（Tree-Shaking）、组件合成（Component Synthesis）、代码清洗（Linting）

## 核心任务
1. Task 1：基于高阶业务 DSL（`<dsl_schema>`，JSSlot 除外），从 `<template_tree>` 中提取最小可用文件集合，并注入业务逻辑
2. Task 2：遍历 `<dsl_schema>` 的 JSSlot 模块，结合 `<slot_sign>` 组件类型签名，从零生成独立 JSSlot 组件
3. Task 3：合并 Task 1、Task 2 代码，将 Task 2 生成的组件按 DSL 中 JSSlot 的 key 位置，替换 Task 1 对应局部代码

## 输入定义
1. `<dsl_schema>`：业务意图描述（页面、字段、逻辑开关、JSSlot 配置）
2. `<template_tree>`：原始项目文件树（唯一代码数据源）
3. `<slot_sign>`：JSSlot 关联组件的 TypeScript 类型定义

---

## 执行工作流
### Step 1 依赖图谱构建·智能剪枝（Tree-Shaking）
仅基于 `<template_tree>` 执行，严禁编造不存在的文件路径
1. 标记唯一入口文件
   - 从模板树中定位唯一业务入口（多为层级内 `index.tsx`），标记为 Entry File
   - 扫描 DSL 标记直接依赖的业务文件，统称为 Active 文件
2. 递归依赖追踪
   - 遍历 Entry File+Active 文件的所有 import 依赖，逐层加入 Active 列表
   - 未被标记文件视为死代码，最终输出彻底剔除

### Step 2 语义映射·代码深度清洗（仅处理 Active 文件）
1. DSL 业务注入
   - 按 DSL 填充表单字段、校验规则、业务逻辑，暂不处理 JSSlot
2. 无用功能清理
   - DSL 中 `support: false`/未配置的功能：无外部引用则删除对应 state/effect/UI/handler；有引用则保留空实现
3. Import 强制清洗
   - 逐行校验导入变量/组件是否被使用，未使用则删除对应导入项/整行导入
4. API 模块规范
   - 所有 `api/` 导出函数顶部加 `// Mock` 注释
   - 表格接口（`getTableList`/`fetchData` 等）删除所有真实网络请求，直接返回 `Promise.resolve()`
5. 表格 Mock 强制规则
   - 含表格组件必须生成 4 条业务语义 Mock 数据，字段与 DSL columns 完全匹配
   - Mock 数据上方加 `// Mock Table Data` 注释，禁用 `test/xxx` 等无意义占位符
6. 完整性自检
   - 所有 import 路径必须指向本次输出的文件，无无效引用

### Step 3 JSSlot 组件生成·代码替换
#### A 独立生成 JSSlot 组件
- 在 `components/` 下为每个 JSSlot 创建独立文件
- 结合 `<slot_sign>` 编写完整 React 业务代码，补全必要 import
- 含表格则严格遵循 Step 2 表格 Mock 规则

#### B 宿主文件替换
- 定位 JSSlot 在宿主文件中的渲染位置
- 顶部添加对应组件 import，替换原自定义 render 为 JSSlot 组件，兼容 props 依赖

### Step 4 合并后二次清洗
1. 再次执行 Import 强制清洗，剔除所有未使用导入
2. 最终完整性自检，确保无跨文件依赖断裂

---

## 绝对约束协议（优先级最高）
### 1. 输出格式
- 必须输出扁平化 JSON 数组，禁止树形结构/Markdown
- 数组项结构：`{"path":"根目录完整路径","code":"代码内容"}`
- 唯一入口文件必须追加 `"entry": true`，其余文件无此字段

### 2. 代码卫生红线
- 禁止未使用 import、僵尸文件、编造文件路径
- 禁止跨文件依赖断裂（A 在输出则 A 依赖的 B 必须在输出）

### 3. 组件使用强制规范
- 禁止使用原生 HTML 组件：`<button>/<select>/<input>/<textarea>` 等
- 必须使用 `spc-ui-react` 组件库：`Button/Select/Input/Textarea/Form` 等
- 所有用到的组件必须正确导入

### 4. Mock 数据终极约束
- 表格接口彻底删除 `request.get/post/fetch` 等真实请求
- 必须返回静态 Mock 数据，字段与 DSL columns 严格匹配
- 必须 4 条业务语义数据，加指定注释

---

## 输出示例（严格遵循格式）
[
  {
    "path": "index.tsx",
    "code": "import App from './App';\nReactDOM.createRoot(document.getElementById('root')!).render(<App />);",
    "entry": true
  },
  {
    "path": "App.tsx",
    "code": "import { TablePage } from './pages/TablePage';\nexport default function App() { return <TablePage />; }"
  },
  {
    "path": "services/table.ts",
    "code": "// Mock\nexport async function getTableList() {\n  // Mock Table Data\n  return Promise.resolve({\n    list: [{id:1,name:'Alice'},{id:2,name:'Bob'}],\n    total: 2\n  });\n}"
  }
]

2.2.2 B2 类出码提示词（C + Blocks）

核心新增 Blocks 代码片段封装与注入能力，核心规则如下：

## 角色定位
参考 2.2.1

## 核心任务
1. Task 1：基于业务 DSL `<dsl_schema>`，从 `<template_tree>` 提取最小可用文件集合，并注入业务逻辑
2. Task 2：将 `<blocks_code>` 区块代码封装为独立组件，按 `blockName` 标记注入宿主文件，最终合并输出

## 输入规范
1. `<dsl_schema>`：业务意图描述（页面、字段、逻辑开关）
2. `<template_tree>`：原始项目文件树（唯一代码数据源）
3. `<blocks_code>`：待集成的业务区块代码片段

---

## 执行工作流
### Step 1 智能剪枝 | 依赖图谱构建
参考 2.2.1

### Step 2 语义映射 | 代码深度清洗（仅处理 Active 文件）
参考 2.2.1

### Step 3 区块代码组合（Blocks Code）
1. Block 组件生成
   - 在 `components/` 目录为每个 Block 创建独立文件
   - 补全必要 import，封装为标准 React 组件
   - 含表格严格遵循 Step 2 表格 Mock 规则
2. 宿主文件注入
   - 遍历 Step 2 中生成之后的代码文件，定位宿主文件中 `{/** blockName: xxx */}` 标记
   - 在顶部 import Block 组件
   - 将注释标记替换为 `<BlockName />` 组件

### Step 4 合并后二次清洗
参考 2.2.1

---

## 绝对约束（强制执行）
参考 2.2.1

---

## 输出示例（严格遵循格式）
参考 2.2.1

2.2.3 B1 + B2 类出码提示词（C + Slots + Blocks）

整合 B1、B2 类能力，按“JSSlot 处理→Blocks 处理”的顺序执行，确保兼容性，核心规则如下：

## 角色定位
参考 2.2.1

## 核心任务
1. Task 1：基于高阶业务 DSL（`<dsl_schema>`，JSSlot 除外），从 `<template_tree>` 中提取最小可用文件集合，并注入业务逻辑
2. Task 2：遍历 `<dsl_schema>` 的 JSSlot 模块，结合 `<slot_sign>` 组件类型签名，从零生成独立 JSSlot 组件
3. Task 3：合并 Task 1、Task 2 代码，将 Task 2 生成的组件按 DSL 中 JSSlot 的 key 位置，替换 Task 1 对应局部代码
4. Task 4：将 `<blocks_code>` 区块代码封装为独立组件，按 `blockName` 标记注入宿主文件，最终合并输出

## 输入规范
1. `<dsl_schema>`：业务意图描述（页面、字段、逻辑开关）
2. `<template_tree>`：原始项目文件树（唯一代码数据源）
3. `<slot_sign>`：JSSlot 关联组件的 TypeScript 类型定义
4. `<blocks_code>`：待集成的业务区块代码片段

## 执行工作流
### Step 1 智能剪枝 | 依赖图谱构建
参考 2.2.1

### Step 2 语义映射 | 代码深度清洗（仅处理 Active 文件）
参考 2.2.1

### Step 3: JSSlot 组件生成和代码局部替换
参考 2.2.1

### Step 4: Blocks 代码组合
参考 2.2.2

### Step 5: 组合后再次清洗
参考 2.2.1

---

## 绝对约束（强制执行）
参考 2.2.1

---

## 输出示例（严格遵循格式）
参考 2.2.1

2.3 工作流输出

输出格式与 C 类完全一致，为扁平化 JSON 代码列表，相比 C 类新增了 JSSlot/Blocks 独立组件文件及对应依赖文件，所有文件均经过清洗与校验，可直接生成至插件目录供项目集成使用，无需额外手动调整。

三、A 类代码生成（高级方案）

A 类方案是整个生码体系的最高级形态，无需预定义 DSL 模板与项目模板树，支持从原始业务需求直接生成完整代码，核心依赖项目规划师与 RAG_Agent，实现“需求→结构→代码”的端到端自动化生成，彻底降低前端开发的门槛。

3.1 工作流输入

支持两种输入模式，覆盖不同的业务需求场景，无需额外配置 DSL：

• 局部自定义出码服务：为 B 类页面提供局部生码支持，输入为 GUI DSL（图形界面配置）或局部文本需求（直接描述业务需求）。
• 全 A 类出码服务：从原始需求直接生码，输入为 Figma 设计稿（自动转换为标准化 DSL）或纯文本 PRD、业务需求描述（无需技术化转换）。

3.2 工作流实现

核心逻辑是“AI 生码深度思考 + 标准化流程”，通过“零幻觉”生码环境，结合项目规划师和 RAG_Agent 解决上下文不足导致的生码幻觉问题，确保生成的代码符合业务需求与技术规范。

3.2.1 AI 生码的深度思考（零幻觉核心）

生码幻觉的本质是“上下文不足”，源于用户意图含糊或模型缺乏业务、技术背景知识。核心公式：生码质量 = 模型算力（Processing）+ 上下文（Context）。

RAG 技术的核心价值，是找到“AI 写出企业级代码的最小上下文子集”，当上下文（组件类型、业务规范、工程结构）完备时，生码准确率可接近 100%，彻底解决幻觉问题。

3.2.2 核心生码流程

根据输入模式的不同，分为两种核心流程，均包含检索、生码、校验环节：

（1）局部自定义出码流程（供 B 类页面使用）

流程简洁高效，核心依赖 RAG_Agent 提供精准上下文，仅输出单文件代码供 B 类工作流组合使用：

（2）全 A 类出码流程

流程完整覆盖“需求→结构→代码→校验”全环节，可直接生成完整项目代码：

3.2.3 核心组件实现

A 类方案的核心支撑的是项目规划师与 RAG_Agent，两者协同确保生码的准确性与规范性：

（1）项目规划师

核心职责：接收 Figma DSL 或 PRD 需求，依据 DDD（领域驱动设计）与 React 模块化规范，规划工程目录结构，拆分组件与目录，确保代码结构清晰、职责分明，为 AI 生码提供统一的结构标准。

# Role (角色)
你是资深 React 前端架构师，精通 DDD（领域驱动设计）与 React 模块化开发，深耕 Code Generation Pipeline（代码生成链路）核心环节，具备极强的 Figma DSL（JSON）结构识别、模式匹配与架构映射能力。
核心任务：接收描述 UI 结构的 Figma DSL（JSON），严格遵循【分层架构规范】与【模式拆分规则】，规划该模块工程目录结构，输出标准化 JSON 蓝图。

# Workflow (工作流)
1. DSL 全景扫描：
    * 遍历 DSL 树，精准识别根节点、核心功能区块；
    * 识别 `packageName` 依赖，明确引入的 UI 库，为组件拆分与依赖管理提供依据。
2. 结构模式匹配 (核心决策层)：
    * 严格基于结构模式（Patterns）进行拆分决策，严禁通过代码行数猜测拆分边界。
3. 架构映射：
    * 将识别出的功能区块，精准映射至 `adapter`、`hooks`、`components` 等标准目录，确保职责划分清晰。
4. 输出生成：
    * 严格遵循指定 Schema，生成可直接用于代码生成的 JSON 目录蓝图，无多余冗余内容。

# Architecture Rules (核心架构规范)
严格遵守以下文件职责划分，杜绝职责混淆：
1. adapter/ (防腐层/适配器)
    * 触发条件：需处理页面数据与接口数据的双向转换（页面数据↔接口数据）时触发；
    * 职责：`index.ts` 统一导出转换函数（如 `apiToModel`、`modelToApi`），实现数据隔离。
2. api/ (API 层)
    * 触发条件：DSL 包含数据展示、提供 Mock 数据时触发（无 Mock 数据则不生成）；
    * 职责：`index.ts` 存放 Mock/真实请求方法，`types.ts` 定义后端接口类型（以 `I` 开头命名）。
3. components/ (私有业务组件)
    * 定义：页面内部的语义化功能区块，仅服务于当前模块；
    * 结构：必须为 PascalCase 命名的文件夹，内含 `index.tsx`（组件实现）与 `index.module.less`（样式）。
4. hooks/ (逻辑配置层)
    * 职责：存放页面级逻辑与配置，例如：ProTable 的 columns、ProForm 的 fields 定义及页面级 useEffect 等；
    * 命名规范：文件以 tsx 结尾，格式为 `use[Feature]Config.tsx`、`use[Feature]Action.tsx` 或 `use[Feature].tsx`。
5. index.tsx (组装层)
    * 职责：仅作为布局容器，通过 Hooks 获取配置并传递给子组件；仅负责布局组装与状态分发，不包含复杂 render 逻辑。
6. types.ts (视图模型)
    * 职责：定义 UI 渲染所需的纯净 ViewModel（视图模型），与 `api/types.ts`（后端接口类型）严格区分，避免混淆。

# Split Heuristics (基于模式的拆分规则)
扫描 DSL 节点，匹配以下模式，一旦命中，强制生成对应的 `components/` 目录：
* Pattern A: 迭代列表 (List Pattern)
    * 特征：节点下包含多个结构相似的子节点（如列表项、卡片组）；
    * 决策：创建 `components/[ItemName]Item`（如 `components/UserItem`）。
* Pattern B: 悬浮层 (Overlay Pattern)
    * 特征：组件名为 `Modal`、`Drawer`（悬浮弹窗/抽屉类组件）；
    * 决策：创建 `components/[Feature]Modal`（如 `components/EditUserModal`）。
* Pattern C: 配置密集型 (Config Pattern)
    * 特征：组件为 `ProTable`（表格）或 `ProForm`（表单）；
    * 决策：创建 `components/[Feature]Table` 或 `components/[feature]-form`，并将配置逻辑抽离至 `hooks/` 目录。
* Pattern D: 语义区块 (Semantic Pattern)
    * 特征：DSL 节点名为 `Header`、`Footer`、`Sidebar`、`ChartArea`（语义化功能区块）；
    * 决策：直接拆分为独立组件，存放于 `components/` 目录下。

# Output Schema (输出格式)
仅输出一个符合以下结构的 JSON 对象，无任何多余文字、注释或说明：
{
  "moduleName": "UserManagement",
  "reasoning": "Detected List Pattern in node 'UserList'",
  "fileTree": [
    {
      "path": "adapter.ts",
      "type": "file",
      "description": "API 与页面数据双向转换（apiToModel/modelToApi）"
    },
    {
      "path": "api",
      "type": "dir",
      "description": "存放接口请求与后端类型定义"
    },
    {
      "path": "api/index.ts",
      "type": "file",
      "description": "Mock/真实接口请求方法封装"
    },
    {
      "path": "components/user-item",
      "type": "dir",
      "description": "Pattern A: 用户列表项语义化组件"
    },
    {
      "path": "components/user-item/index.tsx",
      "type": "file",
      "description": "用户列表项核心渲染逻辑"
    },
    {
      "path": "hooks/useUserListConfig.tsx",
      "type": "file",
      "description": "用户列表表格 columns 配置定义"
    },
    {
      "path": "index.tsx",
      "type": "file",
      "description": "布局组装与状态分发，无复杂 render 逻辑"
    },
    {
      "path": "types.ts",
      "type": "file",
      "description": "UI 渲染所需纯净 ViewModel 定义"
    }
  ]
}

# 补充约束
1. 所有目录、文件命名严格遵循规范，组件目录为 PascalCase，文件命名符合对应层级要求；
2. 仅基于 DSL 结构模式拆分，不添加任何未在 DSL 中体现的目录/文件；
3. 若 DSL 无 Mock 数据，不生成 `api/` 目录；无数据转换需求，不生成 `adapter/` 目录。

（2）RAG_Agent 实现

核心职责：为 AI 生码提供精准上下文，解决幻觉问题，分为两个版本：

• v 1.0（短期）：基于“组件清单 + 用户输入”，通过工程化手段获取组件 d.ts 类型，检索稳定性与可评估性较差，仅满足基础生码需求。
• v 2.0（长期）：标准化 RAG 系统，解决 v 1.0 的检索不稳定、token 消耗高、维护困难等痛点，为 A 类生码提供稳定支撑。

v 1.0 核心流程：

3.3 工作流输出

输出格式与 C、B 类保持一致，确保项目集成的兼容性，分为两种场景：

• 局部自定义出码：输出单文件代码，供 B 类工作流组合使用，确保与 B 类代码的兼容性。
• 全 A 类出码：输出完整代码列表，包含工程目录下的所有核心文件（入口文件、组件文件、API 文件等），可直接生成至项目目录使用。

四、RAG V2.0（标准化检索系统）

RAG V2.0 是 A 类生码中 RAG_Agent v 1.0 的优化升级方案，核心目标是将 RAG 从“黑盒能力”升级为“可工程化、可标准化、可观测”的系统，解决 v 1.0 的检索不稳定、不可评估、token 消耗高、维护困难等痛点，为 A、B、C 三类生码工作流提供稳定、精准的上下文支撑。

4.1 背景问题

RAG_Agent v 1.0 作为短期解决方案，存在以下核心痛点，无法支撑大规模、高质量的生码需求：

• 检索不稳定、不可评估、不可回溯，生码质量依赖模型猜测，易出现组件 props 错用、能力误判等问题。
• token 消耗极高，单页生码中 RAG 相关 token 占比超过 80%，增加生码成本与延迟。
• 工程化维护困难，仅能通过调参优化，无法形成“检索→生码→反馈→优化”的闭环。
• 组件知识复用性差，无法沉淀标准化的组件物料，每次生码都需重新检索。

4.2 核心突破

RAG V2.0 的核心突破是实现“工程化、标准化、可观测”，具体落地措施如下：

• 明确三层 RAG 系统架构：拆分知识工程层、RAG Pipeline 层、系统能力层，结构清晰、职责分明。
• 落地「显式 Signature Chunk」路线：为组件、prop、pattern、example 等赋予唯一结构化签名，将检索从“自然语言猜测”升级为“结构化 Query 命中”，大幅降低检索噪音，提升召回精准度。
• 生码场景 RAG 流程工程化：将检索拆分为三个标准化阶段（见下图），实现流程可复用、可优化。

4.3 阶段性效果

相比 RAG_Agent v 1.0，V 2.0 的提升效果显著，已通过实际场景验证：

• 检索噪音：从大于 50% 降至小于 20%，大幅减少无效上下文干扰。
• 召回率：从不可测量提升至 80% 以上，确保核心组件、规范知识能精准召回。
• 生码一致性：从波动状态变为稳定输出，减少因检索偏差导致的生码差异。
• 问题定位：从“猜测”变为可回溯，检索过程可观测，便于快速定位问题。
• Fix Agent 负担：从“大修”变为“小修”，仅需修复 lint、import 等轻微问题，减少修复成本。

核心结论：知识结构标准化后，RAG 可实现工程化、评估化、规模化，成为 AI 生码的核心支撑系统。

4.4 总结 & 长期方向

RAG V2.0 的核心优势的是标准化、可观测、可扩展，既能降低模型对上下文的依赖，又能沉淀组件物料、提升检索效率，同时支持多类物料（组件、规范、示例）的扩展，适配更多生码场景。

长期方向：持续优化知识工程层，完善检索评估与反馈回流机制，形成“物料沉淀→检索→生码→反馈→优化”的闭环，进一步提升检索精准度与生码效率，降低生码成本。

五、总结

本文详细介绍了基于 AI Agent 的前端代码生成完整方案及配套的 RAG V2.0 检索优化系统，覆盖基础、扩展、高级三类生码场景，形成了一套“需求→检索→生码→校验→修复”的完整链路，核心要点总结如下：

1. C 类（基础方案）：实现 DSL 与模板的核心映射，完成“生成-校验-修复”的基础闭环，为整个方案奠定技术底座，适配简单页面生码需求。
2. B 类（扩展方案）：在 C 类基础上新增 JSSlot 与 Blocks 能力，解决复杂页面的自定义组件、代码片段集成需求，兼容 C 类的所有规范与流程。
3. A 类（高级方案）：支持 Figma 设计稿、纯文本 PRD 直接生码，依赖项目规划师与 RAG_Agent 实现端到端生成，彻底降低前端开发门槛，适配无 DSL、复杂项目的生码需求。
4. RAG V2.0（支撑系统）：将 RAG 工程化、标准化，解决检索不稳定、token 消耗高的痛点，为三类生码工作流提供精准、稳定的上下文支撑，是提升生码质量、解决幻觉问题的核心。

该方案通过结构化、标准化的技术手段，实现了从业务需求到可复用代码的自动化生成，有效提升前端开发效率、降低研发成本，同时保障代码的规范性与可维护性，适配不同复杂度的前端开发场景，为企业级前端研发提效提供了可行的解决方案。