构建界面操作AI助手：从架构设计到工程实现

1. 项目概述为什么你的产品需要一个“界面操作AI助手”最近和几个做SaaS和工具类产品的朋友聊天大家不约而同地提到了一个痛点用户上手成本高。功能越做越强大界面也变得越来越复杂新用户进来常常一脸懵不知道第一步该点哪里老用户想用个高级功能也得在菜单里找半天。传统的解决方案无非是做个引导教程视频、写份长长的帮助文档或者搞个新手引导气泡。但这些静态的、预设好的内容就像一本死板的说明书用户不看看了也记不住遇到具体问题还是得找客服。这让我开始思考有没有一种更“活”的解决方案能不能让产品自己“开口说话”像一个坐在用户身边的资深同事看到用户卡住了就主动指点一下“嘿你想导出数据是吗可以点击右上角这个‘报表’按钮然后选择‘导出为CSV’。” 甚至用户可以直接用自然语言下命令“帮我把上个月的销售数据整理成图表”AI助手就能理解意图并自动在界面上完成一系列点击、输入、选择操作。这就是“给你的产品嵌入一个「会操作界面的 AI 助手」”这个项目的核心价值。它不是一个简单的聊天机器人而是一个具备界面感知Interface Perception和操作执行Action Execution能力的智能体AI Agent。它通过理解当前屏幕上的UI元素按钮、输入框、下拉菜单和用户的语言指令自主规划并执行操作流程真正实现“所说即所得”的交互革命。对于开发者而言这意味着可以将复杂的业务流程封装成一句简单的自然语言指令极大降低用户的使用门槛提升产品粘性和自动化水平。2. 核心架构拆解一个界面AI助手是如何工作的要实现一个能操作界面的AI助手我们不能把它想象成一个黑盒魔法。其背后是一套分层、解耦的清晰架构。主流的设计思路通常遵循“感知-思考-行动”的循环结合当前AI Agent领域的最佳实践我们可以将其拆解为以下几个核心层级。2.1 基础设施层Harness为智能体提供稳定“战场”在讨论炫酷的AI能力之前我们必须先打好地基。Harness层正如其名马具是一套包裹在AI核心逻辑之外的基础设施它的核心职责不是替代Agent做决策而是为Agent提供一个稳定、可靠、可观测的运行环境。你可以把它理解为智能体的“操作系统”或“护航舰队”。为什么需要Harness直接让大语言模型LLM去操作界面是危险且低效的。LLM可能会“幻觉”出不存在的按钮或者执行顺序错误的操作。Harness层的作用就是建立规则和护栏。状态管理与上下文保持Harness需要实时维护一个“界面状态快照”。这个快照不仅包括当前屏幕上有哪些可交互元素通过下文将介绍的UI感知获得还包括当前操作所处的应用状态例如是否在编辑模式、弹窗是否打开、上一个操作的结果是什么。这个上下文是Agent进行决策的绝对依据。工具Tools/Skills封装与调用Agent不能直接“伸手”点击屏幕。Harness需要将底层操作如click(element_id),type(text),select_option(value)封装成一个个标准的、可供Agent调用的“工具”。当Agent决定要点击一个“提交”按钮时它实际上是发出一个调用click(“submit_button”)工具的指令由Harness来安全地执行。流程控制与异常处理Harness负责管理操作流程。例如它需要处理操作失败后的重试逻辑比如网络延迟导致点击无响应识别常见的错误弹窗并触发相应的处理流程以及在多步骤任务中确保步骤间的依赖关系。日志、监控与可观测性所有Agent的决策、发出的指令、执行的结果以及界面状态的变化都需要被Harness详细记录。这对于调试Agent的异常行为、优化提示词Prompt、分析用户交互模式至关重要。实操心得在项目初期千万不要轻视Harness层的建设。很多团队一上来就沉迷于调教LLM结果发现Agent行为极不稳定问题却很难定位。一个健壮的Harness层能帮你节省后期大量的调试时间。建议采用事件驱动架构将界面状态变化、用户输入、Agent决策都作为事件来处理方便追踪数据流。2.2 感知层Interface Perception“眼睛”看到的是什么Agent要操作界面首先得“看见”界面。这里的“看见”不是指计算机视觉识别屏幕截图那太重且不稳定。对于Web或桌面应用更高效的方式是直接获取底层的可访问性树Accessibility Tree或UI元素树UI Hierarchy。获取UI元素树对于Web应用可以通过浏览器提供的DevTools ProtocolCDP直接获取DOM树和计算样式。对于Electron、Flutter、Qt等桌面或跨端框架也有相应的API或工具如微软的Accessibility Insights、Appium可以获取到结构化的UI信息。这些信息包括每个元素的唯一标识符id、类型button, input、可读的名称name/label、状态enabled, visible以及位置和层级关系。结构化与语义化原始的UI树信息非常冗杂。感知层需要对其进行清洗和增强生成一份对Agent友好的“界面描述”。这个过程包括过滤无关元素移除纯粹用于布局的div、不可见的元素。元素重要性打分根据元素类型、尺寸、位置、是否可交互等因素判断其在当前视图中的重要性。补充语义信息将图标按钮的aria-label或图片的alt文本作为其语义标签。如果元素没有明确标签可能需要结合附近文本元素进行推断。生成自然语言描述最终将当前界面状态总结成一段简洁的文本描述例如“当前是一个数据列表页面顶部有一个搜索输入框id: search_input一个‘新增’按钮id: add_btn。列表中有10条项目每条项目后有‘编辑’和‘删除’按钮。”这个结构化的界面描述连同用户的历史操作记录共同构成了Agent进行决策的“观察”Observation。2.3 决策与规划核心LLM Agent智能体的“大脑”这是整个系统的智能核心通常由大语言模型LLM驱动。它的任务是根据“观察”当前界面描述和用户指令规划出一系列具体的操作步骤。指令理解与任务分解用户说“帮我找出上个月销售额超过10万的所有客户并把他们的联系方式导出。” Agent需要理解这是一个复合任务并将其分解为原子操作子任务1在筛选器中设置时间范围为“上个月”。子任务2在筛选器中设置销售额条件为“100000”。子任务3点击“应用筛选”或等待列表刷新。子任务4点击“导出”按钮。子任务5在导出对话框中选择“联系方式”字段和“CSV格式”。子任务6确认导出。工具选择与参数绑定对于每个原子操作Agent需要从Harness提供的“工具清单”中选择合适的工具并绑定具体参数。例如对于子任务1它需要调用select_filter_option(filter_name“时间”, option_value“上个月”)这个工具。思维链Chain-of-Thought与自我验证优秀的Agent不会直接输出动作序列。它应该展示其思考过程比如“用户要导出数据首先需要定位到数据列表页。根据当前界面描述我已经在列表页。接下来需要筛选数据界面顶部有一个筛选区域……” 这种内部独白通常通过LLM的系统提示词实现不仅能提高动作的准确性也为调试提供了便利。在输出动作前Agent还可以进行一步“可行性检查”比如判断要点击的按钮在当前状态下是否可用enabled。技术选型考量LLM选择对于此类需要严格遵循格式和逻辑的任务像GPT-4、Claude 3这类推理能力强的闭源模型初期效果更好。如果考虑成本和数据隐私可以微调开源的Llama 3、Qwen等模型但需要精心准备高质量的指令微调数据。提示词工程这是Agent的“编程”。提示词必须清晰定义Agent的角色、可用的工具、输出格式如严格的JSON并包含丰富的示例Few-shot Learning。例如在系统提示词中明确“你是一个专业的软件操作助手只能使用提供的工具与界面交互。你的输出必须是一个有效的JSON数组每个元素包含‘tool_name’和‘parameters’。”2.4 技能层Skills与检索增强RAG让助手更专业一个通用的界面操作助手可能能完成“点击”、“输入”等基础操作但面对特定领域如你的CRM、ERP系统的复杂业务逻辑时就会显得力不从心。这就需要引入技能Skills和检索增强生成RAG。领域技能封装将复杂的业务流封装成高阶技能。例如在电商后台系统中可以封装一个refund_order(order_id, reason)技能。当用户说“给订单12345退款理由是商品破损”时Agent不是去一步步找退款按钮、输入订单号而是直接调用这个封装好的技能。技能内部可能包含了十几步界面操作和逻辑判断但对用户和Agent核心来说它就是一个原子操作。RAG集成产品帮助文档、历史工单、公司内部的SOP标准作业程序文档都是宝贵的知识源。通过RAG技术可以将这些文档切片、向量化存储。当用户提出模糊指令或Agent不确定如何操作时可以先从知识库中检索相关片段将其作为上下文提供给LLM从而做出更准确的决策。例如用户问“如果客户要发票我该怎么操作” Agent可以检索出“发票申请流程”文档然后根据文档指引一步步操作界面。3. 技术实现路径从零搭建一个原型理论讲完了我们来点硬的。如何用代码实现一个最小可行产品MVP这里我们以一个基于TypeScript的Web应用为例勾勒出核心的实现路径。选择TypeScript是因为其强大的类型系统非常适合构建这种复杂、需要清晰接口定义的系统。3.1 环境准备与项目初始化首先我们创建一个新的Node.js项目并安装核心依赖。# 初始化项目 mkdir interface-ai-assistant cd interface-ai-assistant npm init -y # 安装核心依赖 npm install typescript ts-node types/node --save-dev npm install openai # 或其他LLM SDK如 anthropic-ai/sdk npm install puppeteer # 用于控制浏览器获取UI树和执行操作 npm install zod # 用于严格的输入输出验证对Agent输出至关重要 # 初始化TypeScript配置 npx tsc --init在tsconfig.json中确保设置target: ES2020,module: commonjs, 并启用严格模式。3.2 构建Harness层核心状态机与工具执行器我们首先实现Harness层最核心的部分一个管理界面状态和执行操作的状态机。// src/harness/StateManager.ts export interface UIElement { id: string; type: string; // button, input, dropdown name: string; // 可读的标签 enabled: boolean; visible: boolean; attributes: Recordstring, string; // 其他属性如 value, placeholder } export interface InterfaceState { timestamp: number; url: string; title: string; activeElements: UIElement[]; // 当前可视区域内的主要可交互元素 // 可以添加更多业务相关状态如 currentPage: dashboard | list | detail } export class StateManager { private currentState: InterfaceState; private stateHistory: InterfaceState[] []; constructor(initialState: InterfaceState) { this.currentState initialState; this.stateHistory.push({ ...initialState }); } updateState(newState: InterfaceState): void { this.stateHistory.push({ ...this.currentState }); // 保存历史 this.currentState newState; console.log(State updated to page: ${newState.title}); } getCurrentState(): InterfaceState { return { ...this.currentState }; // 返回副本 } findElement(predicate: (el: UIElement) boolean): UIElement | undefined { return this.currentState.activeElements.find(predicate); } }接下来实现一个基础的工具执行器。这里我们使用Puppeteer作为底层浏览器控制器。// src/harness/ToolExecutor.ts import puppeteer, { Page, ElementHandle } from puppeteer; import { StateManager, UIElement } from ./StateManager; export type ToolResult { success: boolean; message: string; data?: any; }; export class ToolExecutor { private page: Page; constructor(page: Page) { this.page page; } async click(elementId: string): PromiseToolResult { try { // 这里简化处理实际应根据elementId定位元素 await this.page.click([data-testid${elementId}]); // 假设元素有>// src/perception/UISnapshotter.ts import { Page } from puppeteer; import { InterfaceState, UIElement } from ../harness/StateManager; export class UISnapshotter { constructor(private page: Page) {} async captureState(): PromiseInterfaceState { // 获取当前页面基本信息 const url this.page.url(); const title await this.page.title(); // 执行JavaScript代码从页面中提取关键UI元素 const activeElements: UIElement[] await this.page.evaluate(() { const elements: UIElement[] []; // 选择所有可交互或重要的元素 const selectors button, input, select, [rolebutton], [data-testid]; const nodes document.querySelectorAll(selectors); nodes.forEach((node, index) { const rect node.getBoundingClientRect(); // 只收集在可视区域内且足够大的元素 if (rect.width 5 rect.height 5) { const id node.getAttribute(data-testid) || elem_${index}; const type node.tagName.toLowerCase(); const name node.getAttribute(aria-label) || (node as HTMLInputElement).placeholder || node.textContent?.trim().substring(0, 50) || Unlabeled ${type}; elements.push({ id, type, name, enabled: !(node as any).disabled, visible: !!(rect.width rect.height), attributes: { /* 可以提取更多属性 */ } }); } }); return elements; }); return { timestamp: Date.now(), url, title, activeElements: activeElements.slice(0, 20), // 限制数量避免上下文过长 }; } }3.4 构建Agent核心LLM驱动决策这是最激动人心的部分。我们将创建一个Agent类它接收状态和用户指令调用LLM并输出要执行的动作序列。// src/agent/InterfaceAgent.ts import OpenAI from openai; import { z } from zod; import { InterfaceState } from ../harness/StateManager; // 使用Zod定义严格的工具调用模式 const ToolCallSchema z.object({ tool_name: z.enum([click, type_text, select_option, navigate, complete]), parameters: z.record(z.string(), z.any()), reasoning: z.string().optional(), // 思维链 }); type ToolCall z.infertypeof ToolCallSchema; export class InterfaceAgent { private openai: OpenAI; private systemPrompt: string; constructor(apiKey: string) { this.openai new OpenAI({ apiKey }); this.systemPrompt 你是一个专业的软件界面操作助手。你的目标是根据用户指令和当前界面描述规划出一步步的操作步骤。 你只能使用以下工具 - click(element_id): 点击一个界面元素。 - type_text(element_id, text): 在输入框内输入文字。 - select_option(element_id, value): 在下拉框中选择一个选项。 - navigate(url): 跳转到一个新的页面。 - complete(): 当任务完成或无法继续时调用。 当前界面描述 {{current_interface}} 请严格按照以下JSON格式输出一个工具调用数组 [ {tool_name: click, parameters: {element_id: search_button}, reasoning: 用户需要搜索所以先点击搜索按钮}, ... ] 如果任务无法完成或指令不清晰输出一个空数组 []。 ; } async planNextActions(userInstruction: string, currentState: InterfaceState): PromiseToolCall[] { // 将界面状态格式化为文本描述 const interfaceDescription this.formatStateToText(currentState); const finalPrompt this.systemPrompt.replace({{current_interface}}, interfaceDescription) \n\n用户指令${userInstruction}; try { const completion await this.openai.chat.completions.create({ model: gpt-4-turbo-preview, // 或 gpt-3.5-turbo messages: [{ role: system, content: finalPrompt }, { role: user, content: userInstruction }], temperature: 0.1, // 低随机性保证输出稳定 response_format: { type: json_object }, // 强制JSON输出 }); const content completion.choices[0]?.message?.content; if (!content) return []; const parsed JSON.parse(content); // 假设LLM返回 { actions: ToolCall[] } const actions parsed.actions || []; // 验证每一个动作是否符合模式 const validatedActions: ToolCall[] []; for (const action of actions) { const result ToolCallSchema.safeParse(action); if (result.success) { validatedActions.push(result.data); } else { console.error(Invalid tool call format:, result.error); } } return validatedActions; } catch (error) { console.error(Error calling LLM:, error); return []; } } private formatStateToText(state: InterfaceState): string { let text 页面标题${state.title}\n; text 当前URL${state.url}\n; text 可交互元素\n; state.activeElements.forEach(el { text - [${el.type}] ${el.name} (id: ${el.id}) ${el.enabled ? : [已禁用]}\n; }); return text; } }3.5 主循环将所有部分连接起来最后我们创建一个主程序将Harness、感知、Agent和执行器串联起来形成一个完整的操作循环。// src/main.ts import puppeteer from puppeteer; import { StateManager } from ./harness/StateManager; import { ToolExecutor } from ./harness/ToolExecutor; import { UISnapshotter } from ./perception/UISnapshotter; import { InterfaceAgent } from ./agent/InterfaceAgent; import * as dotenv from dotenv; dotenv.config(); async function main() { // 1. 启动浏览器 const browser await puppeteer.launch({ headless: false }); // 非无头模式方便观察 const page await browser.newPage(); await page.goto(https://example.com/admin); // 替换为你的应用地址 // 2. 初始化各个组件 const snapshotter new UISnapshotter(page); const toolExecutor new ToolExecutor(page); const agent new InterfaceAgent(process.env.OPENAI_API_KEY!); // 3. 捕获初始状态 const initialState await snapshotter.captureState(); const stateManager new StateManager(initialState); // 4. 定义用户指令在实际应用中这来自聊天框或语音输入 const userInstruction 帮我在搜索框里输入“未付款订单”然后搜索; console.log(用户指令: ${userInstruction}); // 5. Agent决策循环 let maxSteps 10; while (maxSteps-- 0) { const currentState stateManager.getCurrentState(); const actions await agent.planNextActions(userInstruction, currentState); if (actions.length 0) { console.log(Agent认为任务已完成或无法继续。); break; } // 6. 按顺序执行动作 for (const action of actions) { console.log(执行: ${action.tool_name}, action.parameters, 理由: ${action.reasoning}); let result; switch (action.tool_name) { case click: result await toolExecutor.click(action.parameters.element_id); break; case type_text: result await toolExecutor.typeText(action.parameters.element_id, action.parameters.text); break; // ... 处理其他工具 case complete: console.log(任务标记完成。); await browser.close(); return; default: console.warn(未知工具: ${action.tool_name}); continue; } console.log(结果: ${result.message}); if (!result.success) { console.error(动作执行失败停止当前计划。); break; // 跳出动作执行循环重新规划 } // 7. 每个动作执行后等待并更新状态 await page.waitForTimeout(1000); // 等待UI更新 const newState await snapshotter.captureState(); stateManager.updateState(newState); } } await browser.close(); } main().catch(console.error);这个原型虽然简单但清晰地展示了从指令输入到界面操作的完整闭环。你可以在此基础上增加更复杂的工具、更强大的状态管理、错误恢复机制以及RAG集成。4. 实战避坑指南与进阶优化在实际开发中你会遇到许多在Demo中不会出现的问题。以下是我在构建类似系统时踩过的坑和总结的经验。4.1 稳定性与鲁棒性让AI助手“不犯错”问题1元素定位失效这是最常见的问题。Agent决定点击idsubmit_btn的按钮但页面重新加载或动态渲染后这个元素的ID可能变了或者还没加载出来。解决方案使用稳定的选择器与前端开发团队约定为关键交互元素添加永久的、语义化的>