导读：在 AI 辅助编程（AIGC / Copilot）盛行的当下，许多初学者习惯给 AI 发一句“帮我做个客户管理系统”，然后直接复制粘贴生成的页面和代码。然而，在腾讯云微搭（WeDa）与 CloudBase 云开发这类低代码平台中，这种无序的代码生成极易导致数据模型脱节、逻辑混乱、难以维护。本文基于项目实战经验，提炼出了一套标准的 AI Agent 研发执行规范，帮助团队将 AI 从“代码生成器”升级为“架构级研发协作者”。

---

💡 核心理念：AI 是协作者，不是“写码机器”

很多初学者在使用 AI 参与开发时，最常犯的错误就是跳过设计，直奔代码。

❌ 错误链路：客户一句话需求 ──> AI 直接生成页面 ──> AI 直接生成代码 ──> 结构崩塌、无法维护

✅ 标准链路：业务需求 ──> 需求分析 ──> 业务建模 ──> 功能/数据架构 ──> 技术方案 ──> 代码实现 ──> 验证迭代

在微搭低代码生态中，页面不是系统，代码不是产品，业务模型才是核心。任何 AI 工具（ChatGPT、Claude、Cursor、DeepSeek 等）参与项目前，都必须遵守统一的研发管线。

---

🤖 AI 内部角色体系：模拟标准研发团队

为了防止 AI 产生幻觉或直接吐出不合时宜的代码，我们在 Prompt / Agent 设定中，要求 AI 严格按照角色顺序分阶段思考与输出，禁止跳跃。

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  产品经理 Agent  │  ───> │   架构师 Agent  │  ───> │  工程开发 Agent │
└─────────────────┘       └─────────────────┘       └─────────────────┘
   理解业务/定流程            功能模块/数据建模           JSX组件/方法/云函数

💬 角色一：产品经理 Agent（明确“做什么”）

• 职责：将模糊的客户语言转化为结构化需求说明书。
• 输出：业务目标、用户角色与权限边界、标准业务流程（起始/审批/结束节点）、功能验收标准（含异常处理边界）。
• 🚫 严禁事项：设计页面布局、设计数据库表结构、编写代码。

🏗️ 角色二：架构师 Agent（明确“怎么构筑”）

• 第一阶段（功能架构）：拆解业务模块（如：客户档案、商机、跟进记录），规划页面清单与流转路径（列表 ──> 新增 ──> 保存 ──> 刷新）。
• 第二阶段（数据架构）：识别业务实体，建立页面与数据表（Data Model）的硬映射，定义表结构、字段类型、关联关系。
• 🚫 核心原则：严禁页面上出现数据库未定义的“悬空字段”。

---

🛠️ 腾讯云微搭 & CloudBase 实施技术规范

当系统完成需求与架构设计后，进入具体的代码实施阶段。针对微搭平台的特性，需严格遵循以下三类技术规范：

1. JSX 自定义组件规范（UI 与交互）

当微搭原生组件无法满足复杂交互需求时，使用 JSX 进行扩展。

• 开发原则：高复用、参数化、样式隔离、独立封装。
• 职责边界：组件只负责展示和交互，严禁在组件内部堆砌大量复杂业务逻辑。
• 标准结构：必须清晰定义 props（输入参数）和 EventEmitter（输出事件）。

2. 自定义方法与云函数规范（业务逻辑处理）

我们将业务逻辑严格划分为前端方法与后端云函数：

分类	适用场景	示例
前端自定义方法	页面级交互、数据格式转换、 UI 逻辑控制	formatAmount(), calculateStatus()
CloudBase 云函数	复杂业务逻辑、多表关联操作、权限校验、第三方 API 调优	createOrder(), checkPermission()

• 单一职责：一个方法只干一件事（严禁出现 handleEverything() 式的方法）。
• 防御性编程：所有方法必须包含入参校验、try-catch 捕获以及关键业务日志记录（记录用户、时间、操作、结果）。

3. FX 表达式规范（轻量绑定）

FX 表达式是微搭中的轻量级表达式引擎，只能用于简单的控制：

• 允许：显隐控制（如 status === 'APPROVED'）、简单的条件展示。
• 禁止：复杂计算、多层嵌套逻辑、循环处理、数据查询。复杂逻辑必须收拢到“自定义方法”中，由 FX 进行调用。

---

📋 规范化输出格式模板

要求 AI 在生成具体方案时，必须分阶段输出，避免“对齐颗粒度”过程中的信息缺失。

阶段一：架构方案设计输出

# 1. 需求理解
- 业务目标与服务对象...

# 2. 功能设计
- 模块拆解与页面流转关系...

# 3. 数据设计 (Data Mapping)
| 页面 | 数据表/模型 | 对应操作 | 字段说明 |
|---|---|---|---|
| 客户列表 | customer | 查询 (Query) | id, name, status... |

# 4. 技术选型
- 组件（JSX）/ 方法（前端）/ 云函数（CloudBase）划分...

阶段二：代码实现输出

在输出具体代码时，AI 必须指定文件路径与上下文依赖：

/**
 * 文件位置: /components/CustomerCard/index.jsx
 * 功能说明: 客户信息展示卡片
 * 输入参数: { CustomerItem } data, { Function } onClick
 * 注意事项: 依赖 CloudBase customer 数据模型中的 status 状态字段
 */

import React from 'react';
import { View, Text } from '@cloudbase/weda-ui-components';

export default function CustomerCard({ data, onClick }) {
  if (!data) return null;
  return (
    <View className="customer-card" onClick={onClick}>
      <Text className="title">{data.name}</Text>
      <Text className="status">{data.status}</Text>
    </View>
  );
}

---

❓ 异常处理机制：需求不完整时怎么办？

如果输入的业务描述模糊、权限边界缺失或流程存在漏洞，规范中要求 AI 必须主动提出质询，拒绝“瞎猜”。

AI 质询格式标准：
⚠️ 需要确认事项：[明确指出逻辑不清晰或缺失的点]
💡 风险原因：[解释为什么不能直接猜测，避免引发后续架构重构]

---

🏁 总结与 AI 执行口诀

想要真正发挥低代码平台与 AI Agent 的合力，关键在于用规范约束 AI 的输出边界，用架构引导代码生成。

最后，分享这套规范的核心口诀：

先理解业务，再设计系统；
先建立数据，最后写代码。
页面不是系统，代码不是产品，业务模型才是核心！