完结一个全栈项目的感觉就像跑完一场马拉松冲线那刻的轻松是真的但回头看路上一脚深一脚浅的坑也是真的。这个AI修图Agent从立项到交付我前后折腾了将近三个月横跨了模型接入、后端服务、前端交互和移动端适配属于典型的一个人活成一支队伍的全栈项目。今天把这套东西完整拆出来从架构设计到具体实现从选型逻辑到排坑链路一次性说清楚。如果你正打算做一个带AI能力的多端产品或者对Agent的工作机制感兴趣这篇应该能帮你少走不少弯路。1. 为什么做的是一个Agent而不是一个修图工具修图工具市面上太多了从Photoshop到美图秀秀从Canva到Figma每个都有庞大的用户群。那为什么还要做一个AI修图Agent说实话在最开始想这个项目的时候我反复问过自己这个问题直到后来想明白了一个关键的差异点。传统修图工具的核心交互逻辑是人找功能。你想抠图先找到抠图按钮你想调色先找到色阶、曲线、色相饱和度这些面板。这要求用户不仅知道自己要什么还得知道用什么功能、怎么操作才能达成目标。对专业设计师来说这没问题但对普通用户来说学习成本太高了—这就像一个只能靠菜单驱动的傻瓜相机功能再多不会用就等于没有。Agent不一样它的核心交互逻辑是功能找人。用户只需要说一句帮我把这张图调成夏日清新风格把背景里的人去掉或者把这张产品图变成白底Agent会自己去理解意图、拆解任务、选择工具、执行操作、返回结果。用户不需要知道背后调用了哪个算法、用了什么参数只需要用自然语言描述我想要什么。这次项目的技术架构就是围绕这个理念设计的前端负责自然交互和结果展示后端负责Agent的调度编排和工具执行底层接入了多模态大模型做意图识别和图像处理。整体分为四层每一层都有自己的职责边界。交互层面向用户的上传、预览、对话、操作确认界面覆盖Web端和移动端统一体验调度层Agent的核心大脑理解用户指令拆解为可执行步骤管理多工具调用顺序工具层封装修图算法和AI能力的工具集合包括基础处理和AI生成两类以标准接口注册到Agent模型层底层接入的大模型和图像算法服务包括对话理解模型、图像理解模型、图像生成模型等这个分层设计最大的好处是每层都可以独立替换和迭代。模型层今天用这家的大模型明天换另一家的只要接口兼容Agent的调度逻辑完全不用动工具层新增一个老照片修复能力只需要注册一个新的工具描述Agent立刻就能学会使用它。从商业价值角度看Agent化修图的意义在于降低了专业能力的门槛。普通人不会Photoshop但同样有修图需求专业设计师用传统工具效率高但重复性的抠图、调色、规格化操作同样可以用Agent来批量处理。这两种需求其实指向同一个结论自然语言将成为下一代图像处理的交互入口。2. 技术选型逻辑Vue Golang UniApp 大模型这套组合怎么定下来的技术选型这件事很多人喜欢追新哪个框架火用哪个最后做出来的东西性能和维护性一塌糊涂。我的选型原则很朴素团队能力范围内最稳的组合 生态最成熟的方案 对最终交付最有保障的路径。这个项目最终定了Vue 3 Golang UniApp 多模态大模型的组合都是经过了实际对比和验证的。2.1 前端为什么用Vue 3而不是React说实话React和Vue 3在能力上难分伯仲选哪个更多是看团队习惯和项目属性。这个项目我选择Vue 3核心原因有三个。第一是Composition API对复杂状态的组织能力。AI修图场景的前端状态是非常复杂的原图、中间过程图、多个版本的结果图、每一步操作的参数记录、Agent执行状态等待中、执行中、已完成、失败、对话历史……如果还用Options API那套data/methods/computed的组织方式代码很快就会乱成一团。而Composition API可以按业务逻辑域来组织代码比如把图像状态相关的东西封在一个composable里把Agent通信相关的封在另一个composable里互不干扰维护起来清晰得多。第二是生态的完整度。图像处理类前端项目离不开Canvas相关操作Vue 3生态里有vue-use带来的useEventListener也有社区比较成熟的图像处理组件可以参考。第三点是TypeScript的支持Vue 3本身就是用TS写的类型推导体验比Vue 2时代强了一个量级这对一个代码量大、状态复杂的全栈项目来说非常重要。2.2 后端为什么选Golang而不是Node.js后端服务的核心职责是接入大模型、调度Agent执行工具、处理图片上传下载、管理任务队列。按理说Node.js也能干这些活而且前后端统一用JavaScript还少一门语言的知识成本。但我最后选了Golang主要从四个维度做了比较。维度GolangNode.js选择理由并发模型goroutine轻量级并发原语单线程事件循环图片处理任务IO密集且并发量高Goroutine更直观高效内存占用编译型静态语言启动快内存可控高并发场景内存占用偏高Agent任务并发多内存控制很重要部署运维编译为单一二进制文件部署简单依赖Node环境npm依赖链较长项目交付部署要省心图像处理支持有成熟的imaging库有sharp但编译原生模块偶尔踩坑后端的图像处理能力是关键基础实际开发下来Golang在并发处理Agent任务时确实省心很多。每来一个修图请求我开一个goroutine去跑Agent调度逻辑相互之间不干扰资源消耗也低。如果换成Node.js高并发场景下的回调地狱和内存问题处理起来会多花不少功夫。2.3 多端统一选UniApp而不是纯原生UniApp被一些人诟病性能不如原生这个我不否认但它的核心价值在于一套代码多端运行。这个项目需要覆盖Web端、iOS端和Android端如果分别用Vue/RNC/Flutter写三套人力成本直接翻三倍对于一个个人全栈项目来说根本不可能。UniApp基于Vue语法和前端主栈Vue 3完美衔接这是个很舒服的点。根据Vue官方的说明Vue 3已经将响应式系统核心包vue/reactivity独立发布而UniApp的Vue 3版本也基于这个核心实现所以响应式机制的可靠性和性能有保障。我只需要写一套界面代码编译到H5、微信小程序和App端就都能跑起来。当然多端适配的代价一定有这个后面在坑的章节详细说。2.4 大模型选型的思路大模型是整个Agent大脑的核心这部分的选型我考虑了三个关键约束图像理解能力、工具调用的准确性、成本可控性。最终定下来的方案是对话理解用国内可直连的商用大模型API图像处理任务抠图、去背景、超分辨率、老照片修复用专门的开源模型服务而不是指望一个大模型什么都干。原因很简单术业有专攻。通用的多模态大模型做意图理解很强但让它真的去执行像素级的图像处理效率和效果都不如专门的模型。这种大模型当大脑、专业模型当手脚的组合是当前AI Agent落地比较成熟的模式。Agent判断用户意图后决定调用哪个专业工具或者模型真正的像素操作交给专业工具去完成。3. Agent的核心机制从一句自然语言到一张成片这个项目最核心的部分不是界面不是上传下载而是Agent如何把一句模糊的自然语言转化为一系列精确的修图操作。这里面的机制拆开来看分为意图理解、任务拆解、工具调用、结果校验四个环节每个环节都有值得细说的设计。3.1 意图理解的prompt工程设计Agent理解用户意图靠的就是大模型但同样一个大模型用不同的prompt给它效果天差地别。我在prompt工程上花了不少心思核心原则是给足上下文 明确输出格式 约束行为边界。我设计了一套结构化的System Prompt关键内容是这样的你是一个图像处理Agent负责理解用户的修图需求并生成操作计划。 你可以使用的工具包括 1. crop: 裁剪图片参数为x, y, width, height 2. resize: 调整图片尺寸参数为width, height 3. brightness: 调整亮度参数为-100到100 4. contrast: 调整对比度参数为-100到100 5. saturation: 调整饱和度参数为-100到100 6. remove_background: 去除背景无参数 7. blur_background: 背景虚化无参数 8. super_resolution: 图像超分辨率无参数 9. restore_old_photo: 老照片修复无参数 10. draw_text: 添加文字水印参数为text, x, y, font_size, color 你必须遵循以下规则 - 只能使用上述工具不能编造工具 - 如果用户的需求不明确必须向用户澄清 - 输出必须是无额外文字的JSON数组每个元素包含tool和params两个字段 - 如果需要多个操作按执行顺序排列这套Prompt设计最关键的地方是约束了输出格式。让大模型自由发挥产生自然语言描述Agent那边还要另写一段解析逻辑来理解容易出错。直接限定JSON数组输出解析就变成了一个简单的反序列化操作稳定可靠。当然约束也有代价就是模型偶尔会在输出里混入解释性文字比如好的我来帮你处理这张图片{...}所以我在后端做了容错解析先尝试标准JSON解析失败就尝试提取JSON片段再失败就走重试逻辑。3.2 任务执行链的编排与状态机用户的需求往往不是单一操作。比如帮我把这张照片调成日系清新风格然后加上一句夏日物语的水印这就包含了调色和加文字两个操作而且有先后顺序。Agent执行这类复合任务的机制本质是一个状态机。每个任务都会经历这几个状态Pending待执行任务创建等待调度Running执行中有一个工具正在执行ToolSuccess工具成功当前工具执行完毕且返回结果ToolFailed工具失败当前工具执行失败需要决定是重试、跳过还是中止WaitingUserInput等待用户输入遇到歧义等待用户澄清Completed完成所有操作执行完毕结果已返回Rejected已拒绝/失败任务整体失败后端我用Golang的channel实现了这个状态机的流转。每个任务有一个goroutine负责推进状态工具调用通过channel发消息状态变化后返回给前端做进度展示。这个设计让前端能实时看到正在识别意图→正在调色→正在加文字的完整过程用户体验比干等一个接口返回强得多。type TaskStatus string const ( TaskPending TaskStatus pending TaskRunning TaskStatus running TaskToolSuccess TaskStatus tool_success TaskToolFailed TaskStatus tool_failed TaskWaitUserInput TaskStatus waiting_user_input TaskCompleted TaskStatus completed TaskRejected TaskStatus rejected ) type Task struct { ID string UserID string ImageURL string Status TaskStatus Plan []ToolCall CurrentStep int Result *TaskResult CreatedAt time.Time }3.3 工具注册机制让Agent学会用新工具工具注册是Agent设计里非常核心的一个抽象。按照OpenAI函数调用Function Calling的成熟模式每个工具需要向Agent描述清楚我是谁我能干什么我需要什么参数。这个项目的工具注册表定义如下type ToolSchema struct { Name string json:name Description string json:description Parameters []ToolParam json:parameters Handler func(params map[string]interface{}, image []byte) ([]byte, error) } type ToolParam struct { Name string json:name Type string json:type Required bool json:required Desc string json:desc }实际调用阶段Agent生成JSON计划后后端调度器按顺序执行每个tool call。执行前从ImageURL下载图片执行中把工具调用结果可能是处理后的图片URL、参数信息、或者错误信息追加到上下文里再决定下一步动作。这个过程像一个厨师做菜大模型是点菜的人它知道菜谱告诉后厨要做哪几道菜后厨工具层动手做做完端上来给顾客看返回结果给前端。如果一道菜做得不满意用户看到结果后说还不够亮Agent根据反馈再调整直到满意为止。3.4 多轮对话与参数记忆真正用得顺手的Agent必须支持多轮对话。用户说把这张图调亮一点接着新上传一张图说这张也这样调Agent需要能理解这样指的是上一张图的调亮参数。这个机制的实现方式是在Agent的上下文里始终携带当前图片参数状态信息。每一次工具执行完就把最新的图片参数快照写回上下文后续对话时模型可以看到当前图片的参数配置从而理解这张也这样调的具体含义。同时我在Prompt工程里增加了记忆规则如果用户提到可以这张也等代词性表述优先参考上下文历史里的最近参数配置。这套设计让Agent具备了一定的记忆能力不会再出现用户说了和刚才一样却无从下手的尴尬。4. 全栈链路里的技术细节从上传到出图的完整生命周期Agent逻辑搞定之后真正的工程量其实在前后的全链路打通。一张图片从用户的手机相册出发到最后在屏幕上显示处理结果中间经过上传、存储、网络传输、任务调度、工具执行、结果回传等多个环节。任何一个环节出问题整体体验都会崩塌。4.1 图片上传的断点续传与压缩策略多端产品都会遇到一个问题用户手机上的照片动不动就是5MB、10MB甚至更大而服务端的接收能力和大模型处理的速度都是有限的。直接无脑上传大图轻则超级慢重则直接超时。我实现了一套三级上传策略前端压缩图片在本地先做一次压缩最长边压到2048pxJPEG质量设为0.85。对大部分修图场景调色、裁剪、加文字来说2048px足够用了但文件的体积能压缩掉60%-70%。这一步能省下大量的上传时间和服务端处理时间。断点续传对于超过10MB的图片比如用户选择了原图上传走分片上传。每片2MB失败自动重试上传完成后服务端合并。原图保留对于需要高质量输出的场景比如老照片修复、超分辨率前端保留原始图片URL后端在需要大图时通过URL二次拉取原图而不是一开始就上传全量原图。这套策略实现之后我的实测数据是一张12MB的智能手机照片常规修图场景下实际从用户开始选图到图片可编辑的等待时间从原来的8~10秒降到了2~3秒整个体验的流畅感提升非常明显。4.2 流式返回与进度感知传统后端API的做法是等所有处理完成后一次性返回结果但对AI修图Agent来说这不行。一次修图要经过模型推理、工具执行等多个耗时步骤总时间可能达到5~20秒。如果让用户对着一个转圈的loading等十几秒大概率会觉得产品坏了。我的方案是服务端SSEServer-Sent Events流式推送。每次Agent状态变化后端就主动向前端推送一条事件。前端收到事件后实时更新界面上的进度条和文案提示。事件推送格式如下{ type: status_change, data: { taskId: task_123456, status: tool_success, toolName: brightness, message: 亮度调整完成, previewUrl: https://xxx.com/preview/xxx.jpg } }前端实现SSE的方式不复杂const eventSource new EventSource(/api/v1/tasks/${taskId}/events); eventSource.onmessage (e) { const payload JSON.parse(e.data); // 更新任务状态 updateTaskStatus(payload.data); // 有新的预览图就刷新展示 if (payload.data.previewUrl) { previewImage.value payload.data.previewUrl; } };这里我用了Golang标准库自带的能力实现SSE重点是设置正确的响应头让连接保持长连接不断开。每一步工具执行完就推一条事件用户能实时看到正在处理亮度→正在加文字→正在导出,在心理上极大地缓解了等待焦虑。4.3 UniApp多端的适配代价与策略UniApp表面上一套代码跑多端实际操作起来条件编译#ifdef是家常便饭。不同端的差异主要集中在三块上传API的差异、Canvas绘制的差异、安全区域的差异。上传这块Web端用的是XMLHttpRequest方式App端用的是plus.uploader小程序端用的是wx.uploadFile。UniApp提供了uni.uploadFile统一封装但返回的数据结构在各个端上还有细小的差异。我通通包了一层uploadImage函数内部做差异兼容。Canvas调色的差异是最烦的。Web端和App端对Canvas的像素级操作API虽然都叫getImageData/putImageData但H5端受跨域问题限制App端对canvas类型2d vs webgl的支持又有所区别。我的处理策略是Canvas只用于用户预览和轻量级绘制真正服务端处理的图像操作不依赖前端Canvas能力这才彻底规避了不同端canvas兼容性的物理坑。4.4 数据模型与图片存储方案图片存储是AI修图项目的基础设施。如果自己搭对象存储服务得考虑扩缩容、数据冗余、CDN加速运维成本不低。我的方案是把图片放到云端对象存储兼容S3协议服务端生成预签名URL供前端上传和展示。数据表结构方面这个项目涉及的核心模型有用户表、图片资产表、任务表、工具执行日志表关键表的设计如下图片资产表image_assets记录原始图、中间图、成品图的URL列表、宽高信息、大小、所有者ID、上传时间任务表agent_tasks记录Agent任务的状态、计划JSON、当前执行步骤、错误信息、创建时间和完成时间工具日志表tool_logs记录每一次工具调用的入参、出参、耗时、错误信息用于排查问题和后续调优日志表的设计当时看起来有点多余但实际在排查线上问题的时候帮了大忙。有一次某个用户一直反馈调色后图片异常我通过工具日志表发现是特定的输入图片格式触发了一个色值转换的边界bug——没有日志表的话这种问题根本无从查起。5. 踩坑实录从能用到好用的三次关键排障一个项目从能跑通到真正好用中间隔着无数个坑。这个项目一路走来我记录了十几个值得分享的问题挑选三个最有代表性的展开来说它们分别涉及Agent逻辑、性能、多端交互三个层面。5.1 Agent幻觉模型生成了不存在的工具上线内测第一周我就遇到了一个让人抓狂的问题。用户上传了一张图片说帮我把背景换成的草坪Agent返回的计划里居然有一个change_background工具。问题是我压根没有注册这个工具原因在于我的工具清单里确实有一个remove_background模型似乎理解了换背景的需求但出于某种原因编造了一个自以为合理的工具名而没有选用remove_background组合后续操作。排查过程我先在日志里找到了这条错误记录然后复现了用户的输入用同样的Prompt去调大模型接口发现确实能稳定复现。接着我对比了正常的工具调用Request Body和这次的差异发现模型生成的函数名在语义上接近但名称不对也就是典型的幻觉。根源在于我Prompt里的工具描述还不够清晰严格模型在生成时存在一定的自由度。修复方案有两层第一层是在Prompt里加强约束明确写只能从工具列表中选取不允许自行创造工具名称如果用户需求不匹配任何工具请使用error工具反馈不支持的请求第二层是后端兜底在反序列化JSON时做白名单校验一旦发现未注册的工具名自动将任务标记为失败并返回友好错误提示这个操作目前还在开发中。双保险下来这个问题再没出现过。5.2 图片处理的内存溢出高清大图的死局有一个周末我收到一条服务告警后端进程内存飙升到80%然后直接OOM被操作系统杀掉。我一看监控发现是一个用户上传了一张超高清的扫描图像素达到了8000×6000直接触发了super_resolution超分模型处理。问题出在超分模型上。超分模型需要把输入图片的像素放大4倍8000×6000的原图放大4倍后是32000×24000换算下来是7.68亿像素内存占用直奔2GB以上直接把进程干崩了。排查链路内存突然飙升→盯日志发现是超分功能→用同样的尺寸的测试图复现→果然复现了OOM→阅读超分模型的源码发现没有做尺寸限制→确认根因是没有任何前置的尺寸检查。修复方案是两层第一入口做限制后端在调用超分工具之前检查图片尺寸超过4000×3000限制就直接拒绝并提示用户先用resize缩小第二模型层做分块处理把大图切成若干个1024×1024的小块分别超分再拼接回来。这两个修复落地后即使遇到超出限制的大图也不会再出现整进程挂掉的情况。5.3 小程序端的Canvas跨域污染小程序端有个奇怪的问题图片处理完成后结果图用Canvas绘制并导出时在某些Android机型上报canvas is tainted错误。查了半天发现是图片资源域名没有配置到小程序后台downloadFile合法域名导致的跨域问题。排查链路用户反馈结果图无法分享到朋友圈→我从小程序日志里发现canvas导出异常→检查代码发现Canvas绘制的Image元素src直接指向了对象存储的CDN域名→查微信小程序文档发现必须是downloadFile和uploadFile合法域名白名单内的资源才能正常绘制→比对后确认CDN域名确实没加。修复方案先把图片资源域名和API域名加到小程序的合法域名白名单同时代码层面做了兜底——在Canvas绘制前先调uni.downloadFile把图片下载到本地临时目录用本地路径做绘制彻底绕开跨域限制。这个坑给所有做UniApp多端的提了个醒域名白名单配置一定要最先搞定不然后续的图片类功能全会被卡住。6. 性能优化与并发控制一整套可复用的实战参数全栈项目不能只满足于能跑还得面对并发、延迟、成本这些问题。这个项目落地过程中我在性能优化上投入了不少精力很多参数是可以直接抄作业的。6.1 Agent任务队列与并发限流AI修图Agent和普通CRUD最不一样的地方在于每个任务都要调用外部大模型API和图像处理服务这些服务都是收费的而且都有速率限制。如果放任用户并发请求一方面费用会失控另一方面会触达上游API的QPS限制被限流反而拖垮整体体验。我实现了一个基于Golang Channel的任务队列设计参数如下var ( maxConcurrentTasks 8 // 最大同时执行任务数 maxQueueLen 200 // 队列最大长度 taskQueue make(chan *Task, maxQueueLen) )任务进来先入队worker goroutine从队列里取任务执行。超过队列长度后返回当前任务过多请稍后重试的友好提示。实测下来单机8并发的情况下既能保证单任务响应速度不至于机器资源耗尽又能控制单日大模型API的费用在一个合理范围。如果把并发改为16费用直接翻倍但用户体验几乎无差别性价比不高。6.2 SSE推送带宽与消息合并SSE解决了实时性问题也带来了新问题每个事件都是一次HTTP消息高频推送时网络开销不小。尤其当一个用户连续执行多个工具步骤时如果每一步都推送一次消息量很可观。我的策略是合并节流对状态查询类的低频信息比如排队中采用定时汇总推送对预览图更新类的高频信息采用100ms级别的节流只推送最新状态同时对于无需前端响应的中间过程日志比如模型推理完成耗时2.3秒,不推送到前端只记录到服务端日志表前端只接收真正需要展示的状态变化事件。这样SSE消息量减少了60%但用户感知上并没有太大区别。6.3 图片缓存的终极方案URL指纹图片处理的一个高频需求是同一张图反复用不同参数处理。如果每次处理都走完整链路效率和成本都很不划算。我的方案是在后端加了一个URL指纹缓存。核心逻辑是每个任务生成时根据图片内容哈希和工具参数列表生成一个唯一指纹缓存的key就是指纹。下一次用户用相同参数处理相同图片时直接命中缓存秒级返回结果连大模型都不用调用。这个策略在实际使用中命中率大概在15%~20%别小看这个比例对大模型API的费用节省非常可观。func generateCacheKey(userID string, imageURL string, toolCalls []ToolCall) string { h : sha256.New() h.Write([]byte(userID | imageURL)) for _, tc : range toolCalls { h.Write([]byte(tc.Tool | fmt.Sprint(tc.Params))) } return fmt.Sprintf(%x, h.Sum(nil)) }7. 这个项目做完我对全栈AI应用开发的四点体会项目交付那一刻我复盘了整个开发过程有两个感受特别强烈。一个是全栈这个词的分量——它不是会写几行前端、几个后端接口那么简单而是要从用户体验一直想到底层模型调用任何一个环节的知识短板都会成为整个链条的瓶颈。另一个是对Agent这件事的理解——真正的Agent不是套壳聊天机器人而是把大模型的能力和外部工具的能力编织在一起形成一个能闭环解决问题的系统。第一点体会是技术选型要为业务目标服务不要为技术本身服务。这套VueGolangUniApp的组合单独拆开看都不是最性感的技术但组合在一起就是这个项目的最优解。你不应该因为某个框架流行就追着用而应该问自己我的用户是谁我要交付什么体验哪个技术栈能最快守住这个体验第二点体会是Agent的质量上限一半取决于Prompt工程一半取决于工具链的设计。Prompt工程决定了大模型能不能准确理解意图并生成合理的计划工具链设计决定了计划能不能被稳定执行。两者缺一不可。如果工具没有做参数校验再好的计划也会执行失败如果Prompt没有约束输出格式整个Agent就像脱缰的野马根本不能控制。第三点是全栈AI应用调试的难度远超传统应用。传统应用出问题链路是清晰的前端→后端接口→数据库。AI应用出问题可能是模型理解错了可能是Prompt没写对可能是工具参数校验漏了可能是缓存命中了错误的结果排查链路长了不止一倍。所以我强烈建议在项目一开始就做好日志和追踪体系这个投资一定值得。第四点是前端体验决定了一个AI产品的口碑。模型能力再强如果前端的交互和进度提示做得不到位用户感知到的依然是卡慢不知道在干什么。这次项目里流式状态推送的那套交互虽然实现起来多花了一些时间但用户的反馈非常正面很多人说能看到每一步的执行过程感觉这个AI很聪明。如果你的下一步规划也在这个方向上我建议重点关注这几件事一是Agent工具的生态扩展把更多专业图像算法纳入进来比如风格化迁移、局部重绘、AI扩图这样的能力二是进一步优化推理成本尝试更小的蒸馏模型做意图识别降低对大型API的依赖三是往多用户协同方向延伸让一个团队可以共享修图流程模板和参数预设。全栈AI修图Agent这个品类还有很多空间可以挖市面上真正把交互体验和Agent机制结合得很完善的产品还不多做下去一定还有机会。