AI Agent 插件

AI Agent 是一个智能对话插件，通过自然语言交互帮助用户完成页面构建、工作流配置等低代码平台操作。采用 ReAct（Reasoning + Acting）模式，结合任务规划和工具调用，实现复杂任务的自动化执行。

核心模块

robot/
├── src/
│   ├── agent/              # Agent 核心逻辑
│   │   ├── AgentCore.ts    # 状态管理与协调
│   │   ├── planner.ts      # 任务规划器
│   │   ├── executor.ts     # 任务执行器
│   │   └── prompts.ts      # 提示词构建
│   ├── components/         # UI 组件
│   ├── mcp/               # MCP 工具适配器

技术栈

• MCP（Model Context Protocol）：工具调用协议
• Server-Sent Events（SSE）：流式响应

执行流程

整体流程

用户输入
    ↓
加载提示词
    ↓
意图判断
    ├─ 普通问答 → 直接输出 Markdown
    └─ 需要操作 → 规划任务
                    ↓
              任务执行（ReAct 模式）
                    ↓
              生成最终答案

状态流转

IDLE（空闲）
    ↓
PLANNING（规划中）
    ↓
EXECUTING（执行中）
    ↓
FINAL_ANSWER（生成答案）
    ↓
IDLE（空闲）

执行模式

简单对话模式

• 触发条件：普通问答（如"什么是组件？"）
• 执行方式：直接输出 Markdown 文本
• 特点：不调用工具，不规划任务

任务执行模式（ReAct）

• 触发条件：需要操作页面或工作流
• 执行方式：ReAct 循环
• 流程：

  思考（Reasoning）→ 调用工具（Acting）→ 观察结果（Observation）→ 继续执行

任务规划

规划协议

任务规划输出结构化 JSON：

{
  "type": "plan",
  "plan_id": "plan_001",
  "steps": [
    {
      "step_id": 1,
      "type": "tool_call",
      "name": "步骤动作描述",
      "tool": "工具名称",
      "args": {},
      "depends_on": []
    }
  ]
}

规划原则

原则	说明
业务粒度	每个任务对应一个完整的业务操作
任务数量	控制在 2-5 个以内，复杂任务可扩展至 10-12 个
依赖顺序	有依赖关系的任务按顺序排列
简单优先	普通问答不规划任务

任务结构

interface Task {
  id: string              // 任务唯一标识
  name: string            // 任务名称
  description: string     // 任务详细描述
  tool?: string           // 调用工具
  args?: object           // 工具参数
  status: TaskStatus      // 任务状态
  rounds: ReActRound[]    // 执行轮次
  result?: string         // 执行结果
  error?: string          // 错误信息
}

任务状态

enum TaskStatus {
  PENDING = 'pending',      // 等待执行
  REASONING = 'reasoning',  // 推理中
  CALL_TOOL = 'call_tool',  // 调用工具
  OBSERVING = 'observing',  // 观察结果
  COMPLETED = 'completed',  // 已完成
  FAILED = 'failed'         // 失败
}

工具系统

工具分类

类别	工具	说明
页面操作	get_canvas_materials_page_schema	获取页面结构
页面操作	diff_update_page_dsl	批量修改页面
工作流操作	get_canvas_workflow_schema	获取工作流结构
工作流操作	add_canvas_workflow_node	添加工作流节点
技能调用	get_skill_detail	获取技能详细内容
...

工具调用规范

1. 先读后写：修改前必须调用只读工具获取当前状态
2. 批量修改：页面修改统一使用 diff_update_page_dsl
3. 单步执行：每次响应最多调用一个工具
4. 循环防护：同一工具失败两次后停止并分析原因

技能（Skills）

可用技能

技能名称	触发关键词	设计风格
frontend-design	前端设计、页面构建	通用前端设计指南
apple-design	Apple风格、极简黑白	极简主义、单一蓝色强调色
airbnb-design	Airbnb风格、温暖亲切	温暖摄影优先、红色品牌色
linear-design	Linear风格、暗色主题	暗色原生、靛蓝强调色
claude-design	Claude风格、文学气质	羊皮纸色调、陶土红品牌色
stripe-design	Stripe风格、金融科技	蓝紫色调、多层阴影
...

技能调用示例

// 获取 Apple 设计风格指导
get_skill_detail({ skillName: "apple-design" })

核心规则

执行规则

规则	说明
组件限制	仅使用「可用组件列表」中的组件
节点限制	仅使用「可用工作流节点类型」中的节点
写前必读	修改前必须调用只读工具获取当前状态
批量修改	页面修改统一使用 diff_update_page_dsl
单步执行	每次响应最多调用一个工具
循环防护	同一工具失败两次后停止并分析原因

扩展开发

添加新工具

1. 在 src/mcp/ 下创建工具文件
2. 实现工具定义和回调函数
3. 在 src/mcp/index.ts 中注册工具

工具定义示例：

export const MyTool = {
  name: 'my_tool',
  title: '我的工具',
  description: '工具描述',
  inputSchema: z.object({
    param1: z.string().describe('参数1说明')
  }).shape,
  annotations: {
    title: '我的工具',
    readOnlyHint: false,
    destructiveHint: false
  },
  callback: async (args: any) => {
    return {
      content: [{
        type: 'text',
        text: { status: 'success', data: {} }
      }]
    }
  }
}

添加新技能

1. 在 server/src/agent/skills/templates/ 下创建技能文件夹
2. 创建 SKILL.md 文件，添加 frontmatter：

---
name: skill-name
description: 技能描述，用于触发匹配
---

# 技能详细内容
...