企业官网建设流程全解析

1. 这不是一张“技术海报”，而是一份Agent产业落地的实操地图

如果你最近刷技术社区、招聘JD、投资人简报，甚至开源项目README，频繁看到Agent、MCP、A2A、LangGraph这些词扎堆出现，别急着点开“LangGraph教程”或搜“MCP协议是什么”，先停一下——你很可能正站在一个典型的信息断层上：上层是资本和媒体热炒的“AI Agent将重构所有软件”，下层却是开发者面对一堆新名词时的真实困惑：“我该从哪一行代码开始？哪个概念现在抄作业最稳？哪个框架下周就可能被弃用？”

这正是“2026 Agent 产业与技术全景图谱”要解决的核心问题。它不画虚线箭头讲“未来趋势”，也不堆砌术语做“概念展览”，而是把当前（2024下半年至2025上半年）真实跑在生产环境里的Agent系统，像拆一台精密仪器一样，一层层剥开外壳，露出五层物理可部署、逻辑可验证、团队可协作的架构实体。这五层不是理论分层，而是我在三个不同行业（金融智能投顾中台、SaaS客服工作流引擎、工业设备远程诊断平台）亲手落地Agent系统时，被反复验证、推翻、再重建的结构共识。

所谓“40+ 概念避坑指南”，也不是罗列名词解释，而是把每个高频热词背后真实的落地陷阱拎出来：比如“MCP”在Figma插件里调用的是本地文件协议，在通达信股票软件里走的是进程间内存共享，在Burp Suite里又变成HTTP反向代理桥接——同一套协议名，三种完全不同的实现路径，选错一种，整个Agent链路就卡死在第一步。再比如“LangGraph”常被当作“LangChain升级版”来学，但实际项目中，90%的团队踩坑不是因为不会写StateGraph，而是根本没意识到它的核心约束：所有节点必须是纯函数，且状态迁移不可逆——一旦你在某个节点里偷偷改了全局变量，或者想回退到上一步重试，系统就会静默失败，日志里只有一行“execution terminated due to error”。

这份图谱适合三类人直接抄作业：

• 技术负责人：用来快速评估团队当前Agent技术栈是否踩在主流演进路径上，避免在“LangChain v0.1 vs LangGraph v0.2”的细节里内耗，转而聚焦“MCP服务治理”和“A2A权限模型”这类真正在影响交付周期的问题；
• 一线开发者：拿到就能对照自查——你写的那个“PI Agent桌面端”是不是还在用硬编码的API Key轮询调用？你配置的“Codex联动Burp MCP”有没有漏掉host白名单校验？这些都不是“高级技巧”，而是上线前必须堵住的漏洞；
• 产品与架构师：看清哪些概念已进入稳定期（如A2A标准通信模式），哪些还在实验室阶段（如基于MCP的ObCloud工作流），从而把资源投向真正能缩短交付周期的技术点，而不是追逐下一个“扣子是不是LangGraph实现的”这类伪命题。

下面，我们就从这五层架构的物理边界开始，一层层拆解——每一层都附带我在真实项目中验证过的部署拓扑、参数阈值、以及那个让团队加班到凌晨三点才定位出来的关键Bug。

2. 五层架构不是分层图，而是Agent系统的“物理剖面图”

很多人把Agent架构画成OSI七层模型那样的抽象分层，结果一落地就发现：网络层和应用层根本分不开，安全策略横跨三层，监控埋点要插在四个位置。真正的Agent系统没有“逻辑分层”，只有“物理部署边界”。我们拆解的五层，全部基于2024年主流云厂商（AWS/Azure/GCP）和私有化部署（K8s+Docker）的实际拓扑，每一层都对应明确的基础设施单元、运维责任主体和故障域隔离范围。

2.1 第一层：终端交互层（The Edge Interaction Layer）

这是用户真正“摸得到”的部分，也是最容易被当成“前端”轻视的一层。但它承载着Agent系统最关键的意图保真度任务——把用户模糊的自然语言指令，转化为下游可执行的结构化动作。这一层不是简单的UI渲染，而是包含三个强耦合子模块：

• 多模态输入解析器：处理语音转文字（ASR）、截图OCR、手写笔迹识别等。重点不是准确率，而是上下文锚定能力。例如在Figma插件中，用户说“把这个按钮改成蓝色”，解析器必须同时输出：{action: "modify", target: "button_123", property: "fill", value: "#007bff"}，其中target必须精确到Figma文档的唯一node ID，否则后续MCP调用会失败。我们实测发现，直接调用OpenAI Whisper API的延迟波动太大（200ms~2s），最终改用Whisper.cpp编译为WebAssembly，在浏览器端本地运行，首字响应压到80ms以内，且完全规避了网络抖动导致的指令截断。

• 意图澄清对话引擎：当输入存在歧义时（如“查一下昨天的数据”——哪个系统？什么指标？），不依赖大模型实时生成追问话术，而是预置23个高频歧义场景的决策树。例如“时间范围模糊”触发规则：若用户历史操作中70%集中在近7天，则默认补全为“近7天”；若涉及财务报表，则强制弹出时间选择器。这套规则引擎用Rust编写，编译后仅127KB，嵌入任何前端框架无压力。

• 终端MCP客户端：这是本层最易被忽略的“物理接口”。MCP（Model Communication Protocol）在此层表现为一个轻量级SDK，负责将结构化动作指令序列化为HTTP/HTTPS请求，并处理三类关键事务：

  1. Token生命周期管理：Figma插件的MCP Token有效期仅1小时，且每次调用需携带X-Figma-Plugin-ID头；而通达信本地MCP Server则要求Token与进程PID绑定，重启软件即失效。我们封装了一个统一Token Broker，自动检测运行环境并调用对应刷新逻辑；
  2. 二进制载荷透传：当需要上传截图或PDF时，MCP要求base64编码后放入payload字段，但某些旧版Burp Proxy会因header过长拒绝请求，解决方案是改用multipart/form-data分块上传；
  3. 离线降级策略：在弱网环境下，缓存最近3次成功指令，用户点击“重试”时直接复用本地缓存的MCP请求体，而非重新走完整NLU流程。

提示：很多团队在终端层栽跟头，不是因为模型不行，而是MCP客户端没做环境自适应。我们曾遇到一个案例：某银行App的Agent功能在iOS上100%成功，Android上失败率47%，最后发现是Android WebView的fetch()API对Content-Length头的校验更严格，而MCP SDK默认未显式设置该头。

2.2 第二层：协议适配层（The Protocol Translation Layer）

如果说第一层是“用户说什么”，这一层就是“系统听懂什么”。它不处理业务逻辑，只做一件事：把五花八门的上游协议，翻译成下游统一的、可路由的、带元数据的动作包。这里没有“银弹框架”，只有针对每种协议的定制化胶水代码。

我们梳理出当前Agent生态中最常对接的6类协议源，每类都对应一套经过压测的适配器：

特别强调一个高频误区：“MCP协议”不是单一协议，而是协议元框架。它定义了动作描述格式（Action Schema）、错误码体系（Error Code Registry）、健康检查端点（/health），但具体传输层可以是HTTP、WebSocket、甚至串口AT指令。我们在Trae平台对接Figma时，发现官方MCP文档只写了HTTP方案，但实际Figma插件运行在受限沙箱中，必须改用chrome.runtime.sendMessage进行进程内通信——这时MCP的“协议”本质就体现为JSON Schema的严格校验，而非传输方式。

注意：这一层的代码绝不能写在LangChain或LangGraph里！我们曾重构一个客服Agent，原方案把Figma适配逻辑塞进LangChain Tool，结果每次Figma API变更都要重训整个LLM Chain。改为独立适配层后，Figma升级只需更新3个JS文件，发布耗时从4小时缩短到8分钟。

2.3 第三层：Agent执行层（The Agent Orchestration Layer）

这是五层中技术水最深、争议最大的一层。很多人以为“用LangGraph写个StateGraph就是Agent执行层”，但真实生产环境里，LangGraph只是这个层的调度器之一，它上面还压着资源治理、状态持久化、异常熔断三大重担。

我们定义的Agent执行层，必须满足四个硬性指标：

• 可中断性：任意节点执行中，能接收外部信号暂停并保存中间状态；
• 可追溯性：每个动作执行的输入、输出、耗时、资源消耗（CPU/内存）必须全链路记录；
• 可重放性：给定相同初始状态和输入，必须100%复现执行路径；
• 可降级性：当LLM服务不可用时，能自动切换到规则引擎或缓存策略。

为此，我们构建了三层执行栈：

• 底层：执行运行时（Runtime）
  不是直接跑Python进程，而是基于WebAssembly的沙箱环境（Wasmer）。所有Tool代码编译为WASM模块，由Runtime统一加载、内存隔离、超时杀进程。好处是：1）杜绝Python GIL导致的并发瓶颈；2）单个Tool崩溃不影响其他节点；3）资源占用可精确到MB级。我们实测，一个10节点的LangGraph流程，在Python中平均内存占用2.1GB，在WASM Runtime中降至386MB。

• 中层：状态协调器（State Coordinator）
  LangGraph的State对象在分布式环境下极易不一致。我们的方案是：所有State变更必须通过Redis Stream发布事件，由Coordinator消费后写入TiDB（支持强一致事务的NewSQL数据库）。每个State版本带全局递增版本号（Version Vector），当两个分支同时修改同一字段时，Coordinator按版本号自动合并（类似Git冲突解决），而非简单覆盖。

• 上层：调度控制器（Orchestrator）
  这才是LangGraph真正该待的位置。它只负责：1）根据State内容决定下一步调用哪个Tool；2）向Runtime提交WASM执行请求；3）监听Coordinator的状态变更事件。我们剥离了LangGraph中所有与持久化、重试、熔断相关的代码，这些由Controller统一管理。例如，当某个Tool连续3次超时，Controller会自动将其标记为“降级”，后续请求直接返回预设Fallback Response，同时告警通知运维。

实操心得：不要在LangGraph节点里写数据库操作！我们有个金融Agent，原设计在“查询持仓”节点里直接连MySQL，结果高峰期数据库连接池打满，整个Agent集群雪崩。改为所有DB操作走独立WASM Tool后，数据库故障只影响该Tool，其他节点照常运行。

2.4 第四层：模型服务层（The Model Serving Layer）

这是最常被“过度工程化”的一层。很多团队一上来就部署vLLM、Triton、DeepSpeed，结果发现80%的Agent请求根本用不上FP16推理——因为大部分是短文本分类、关键词提取、结构化抽取等轻量任务。

我们按任务类型将模型服务分为三级，每级对应不同SLA和成本模型：

• L0级：规则引擎（<10ms延迟）
  处理确定性任务：日期解析（“下周一”→2024-10-28）、金额标准化（“¥1.2万”→12000）、实体归一化（“iPhone15”→“Apple iPhone 15 Pro”）。全部用Rust编写，编译为静态链接二进制，单核QPS超12,000。这是Agent响应速度的“压舱石”，必须100%本地化部署，绝不走网络。

• L1级：小模型服务（<300ms延迟）
  部署7B以下量化模型（如Phi-3-mini、TinyLlama），专用于：意图分类（15个业务意图）、槽位填充（从句子中抽5类参数）、情感分析（客服对话满意度）。使用ollama+GPU直通，单卡A10可并发服务23个L1实例。关键优化：启用PagedAttention，显存占用降低41%；请求队列采用优先级调度，高优任务（如交易确认）永远插队。

• L2级：大模型网关（<2s延迟）
  这才是vLLM、TGI的主战场，但只承接三类任务：1）复杂推理（“对比三只基金的夏普比率”）；2）长文档摘要（>10页PDF）；3）多跳问答（需检索+推理+生成）。我们严格限制L2调用量：每个Agent会话中，L2调用不得超过2次，超过则触发“简化模式”——用L1模型组合模拟L2效果（如用3个L1模型分别做检索、摘要、生成，再拼接结果）。

关键参数：L2网关的max_batch_size必须设为1！我们测试过batch_size=4时吞吐提升2.3倍，但P99延迟从1.2s飙升至4.7s，导致Agent对话卡顿。用户体验宁可慢一点，也不能断。

2.5 第五层：数据与知识层（The Data & Knowledge Layer）

这是Agent系统的“记忆中枢”，但绝不是简单挂个向量库。真实场景中，知识数据有四种物理形态，必须分而治之：

• 实时业务数据（Hot Data）：订单状态、库存数量、用户余额等，毫秒级更新。接入方式：Debezium捕获MySQL binlog，实时写入Apache Pulsar，Agent执行层通过Pulsar Consumer订阅变更事件。绝不允许Agent直接查DB！因为DB查询会拖慢整个执行链路。

• 结构化知识库（Warm Data）：产品手册、API文档、合规条款等，更新频率低（周级）。存储方案：ChromaDB + Sentence-BERT嵌入，但关键改进是——为每个文档块添加业务标签（如tag: "payment"、tag: "compliance"），检索时强制按标签过滤，避免无关文档污染语义空间。

• 非结构化知识（Cold Data）：会议纪要、培训视频字幕、客服录音转文本。存储方案：MinIO对象存储 + LlamaIndex索引。重点优化：对视频字幕做时间戳分段（每30秒一段），检索时不仅返回文本，还返回原始视频时间戳，Agent可直接跳转播放。

• Agent自身经验（Self-Knowledge）：历史成功/失败案例、用户反馈评分、Tool调用统计。存储方案：专用PostgreSQL表，每条记录含agent_id、tool_name、input_hash、output_hash、success_rate_7d。这是实现“Agent越用越聪明”的基础——当新请求的input_hash匹配到历史高成功率案例时，直接复用结果，跳过所有模型调用。

警惕陷阱：“向量数据库”不是万能药。我们曾用Milvus存10万条产品FAQ，但用户问“怎么退款”时，向量检索返回的是“退货流程”，而非“退款时效”。根源在于语义鸿沟。最终方案：对所有FAQ人工标注3个关键词（如“退款”→["refunding", "money_back", "bank_account"]），检索时先做关键词匹配，再用向量排序，准确率从63%提升至92%。

3. 40+概念避坑指南：每个坑都是我们交过的真金白银学费

网络热词列表里那些高频出现的词，背后藏着大量未经验证的“伪共识”。我们把它们按风险等级归类，给出可立即执行的避坑方案。以下仅展示最具代表性的12个，其余28个在完整版图谱中展开。

3.1 “MCP协议”不是标准，而是“协议契约”

坑点：搜索“MCP协议”会看到大量文章把它当作类似HTTP的通用标准，导致团队投入资源开发“通用MCP网关”。

真相：MCP是接口契约（Interface Contract），不是传输协议。它只规定三件事：1）动作请求的JSON Schema；2）错误响应的Code/Message格式；3）/health端点的返回结构。至于这个JSON是通过HTTP POST、WebSocket Message还是串口AT指令发送，MCP不管。

避坑方案：

• 在项目初期，用JSON Schema Validator（如ajv）校验所有MCP请求/响应，确保符合契约；
• 为每种传输方式单独开发Client SDK（如mcp-http-client、mcp-websocket-client），但共用同一套Schema定义；
• 禁止在SDK里封装业务逻辑（如“自动重试”、“Token刷新”），这些应由上层协议适配层处理。

我们踩过的坑：曾为Figma和通达信开发同一套“MCP通用Client”，结果Figma要求Token放在Header，通达信要求Token写入共享内存，最后Client代码里堆满if (env === 'figma') {...} else if (env === 'tongdaxin') {...}，维护成本爆炸。

3.2 “A2A”不是技术，而是权限模型

坑点：A2A（Agent-to-Agent）常被理解为“Agent之间互相调用”，于是团队忙着开发Agent注册中心、服务发现机制。

真相：A2A的本质是最小权限原则（Principle of Least Privilege）在Agent世界的落地。它回答一个问题：“当Agent A需要调用Agent B的某个功能时，B如何确认A有资格调用，且只能调用指定功能？”

避坑方案：

• 每个Agent对外暴露的API，必须声明scope（作用域），如"scope": ["user:read", "order:write"]；
• A调用B时，必须携带JWT Token，其中aud（受众）字段指定B的Agent ID，scope字段声明本次请求所需权限；
• B的网关层强制校验Token，任何scope不匹配的请求直接403，不进入业务逻辑。

实操验证：在金融Agent中，风控Agent调用交易Agent的“下单”功能，但交易Agent的JWT校验发现Token scope只有"order:read"，立刻拒绝。这比在业务代码里写if user_role == 'risk'安全得多。

3.3 “LangGraph”不是LangChain替代品，而是状态机DSL

坑点：大量教程把LangGraph宣传为“LangChain 2.0”，导致开发者用LangGraph重写所有LangChain Chain，结果性能不升反降。

真相：LangGraph是状态机领域特定语言（DSL），它只解决一个问题：“如何定义、执行、调试一个有状态的、可中断的、可重放的工作流”。它不提供LLM调用、文档加载、工具集成等能力——这些仍需LangChain或自研组件。

避坑方案：

• LangGraph只用于编排“需要状态保持”的流程（如多轮对话、审批流、故障排查向导）；
• 纯单次调用的Agent（如“查天气”、“翻译句子”），直接用LangChain Runnable或自研轻量调度器；
• 在LangGraph State中，只存必要字段（如messages,current_step,retry_count），禁止存大对象（如原始PDF字节流），这些应存对象存储并传URL。

数据对比：一个“贷款申请审核”Agent，用LangChain Chain实现，平均耗时840ms；改用LangGraph后，因State序列化开销，耗时升至1120ms。最终方案：只用LangGraph编排审核步骤（初审→风控→终审），每个步骤内部用LangChain Runnable执行，总耗时降至690ms。

3.4 “Agent框架”不存在，只有“Agent能力矩阵”

坑点：招聘JD常写“精通Agent框架”，技术选型会议争论“选LangChain还是LlamaIndex”，仿佛存在一个叫“Agent框架”的标准软件。

真相：Agent是能力组合体，不是软件包。一个生产级Agent必须具备7种原子能力，每种能力有多个技术选项：

避坑方案：拒绝“全栈框架”诱惑。我们为每个新Agent项目创建《能力需求清单》，逐项勾选所需能力，再为每项选择最匹配的技术，而非强行套用某个“框架”。

3.5 “PI Agent”不是产品，而是部署形态

坑点：搜索“PI Agent桌面端”，大量文章教你怎么打包Electron应用，却没人告诉你PI（Personal Intelligence）的核心约束。

真相：PI Agent的本质是个人数据主权代理（Personal Data Sovereignty Agent），它必须满足三个物理约束：

• 数据不出设备：所有敏感数据（通讯录、位置、健康数据）必须本地处理，模型权重和知识库可预装，但运行时绝不上传；
• 资源零侵扰：CPU占用峰值<15%，内存<500MB，否则用户会手动Kill进程；
• 离线可用：网络中断时，至少保留70%核心功能（如本地笔记搜索、日程提醒）。

避坑方案：

• 模型选型：只用<1B参数的量化模型（如Phi-3-mini-4k-instruct-Q4_K_M），在Mac M1上实测推理速度18 tokens/s；
• 知识库：用SQLite FTS5全文检索替代向量库，建索引耗时<2秒，查询延迟<10ms；
• 权限控制：在macOS上用App Sandbox，在Windows上用Windows Defender Application Control（WDAC）策略锁定进程行为。

真实案例：某PI Agent在Windows上因未配置WDAC，被系统误判为挖矿程序，自动终止。解决方案：用Set-RuleOption -Driver命令添加签名白名单，耗时3分钟。

3.6 “LangChain和LangGraph的区别”是伪命题

坑点：技术社区热衷对比“LangChain vs LangGraph”，仿佛二者是竞品。

真相：LangChain是工具集（Toolset），LangGraph是编排语言（Orchestration Language）。就像React是UI组件库，而React Router是路由配置语言——你不会问“React和React Router哪个更好”，而是“这个页面要不要路由”。

避坑方案：

• LangChain提供LLM,Tool,Retriever等原子组件；
• LangGraph提供StateGraph,ConditionalEdge,checkpointer等编排原语；
• 正确用法：用LangChain组件构建Tool，用LangGraph StateGraph编排Tool调用流程。
• 错误用法：用LangGraph重写LangChain的Runnable，或用LangChain Chain强行模拟LangGraph的State。

我们重构的教训：曾用LangGraph的StateGraph包装LangChain的SequentialChain，结果每次invoke()都要序列化整个Chain对象，内存暴涨。改为LangChain负责Tool实现，LangGraph只管流程编排，内存占用下降68%。

3.7 “MCP Host和MCP Server”不是服务器，而是角色

坑点：文档里写“配置MCP Host”，新手以为要买服务器，折腾Nginx反向代理。

真相：MCP Host是请求发起方（如Figma插件），MCP Server是请求接收方（如你的Agent后端）。它们可以是同一进程的不同线程，也可以是跨机房的两个服务。

避坑方案：

• 在Figma插件中，Host是插件JS代码，Server是你部署在Vercel的API；
• 在通达信中，Host是注入的DLL，Server是通达信主进程的内存共享区；
• 在Burp Suite中，Host是Burp插件Java代码，Server是Burp内置的HTTP Server（http://127.0.0.1:8080/mcp）。

关键配置：MCP Server必须暴露/mcp端点，且支持POST /mcp/action和GET /mcp/health。我们用Express.js实现，核心代码仅12行，无需额外框架。

3.8 “CrewAI”不是框架，而是团队协作模式

坑点：CrewAI被包装成“多Agent框架”，导致团队盲目拆分Agent，结果沟通成本远超收益。

真相：CrewAI是角色分工模式（Role-Based Collaboration Pattern），它假设：1）任务可分解为固定角色（如Researcher、Writer、Reviewer）；2）角色间信息传递成本极低（如同一进程内）；3）所有角色共享同一知识库。

避坑方案：

• 仅当满足以上三点时，才用CrewAI。我们实测，跨服务部署的CrewAI，因网络延迟，角色间消息传递耗时占总耗时73%；
• 更优方案：用A2A协议 + 消息总线，每个Agent独立部署，通过Topic订阅协作；
• 若坚持用CrewAI，必须部署在同一K8s Pod内，用localhost通信，禁用任何网络跳转。

3.9 “Agent Evals”不是测试，而是生产监控

坑点：团队花大力气搞“Agent评测”，用Arena、RAGAS跑离线测试，结果线上故障频发。

真相：Agent Evals的核心价值不在“测准不准”，而在建立生产环境的黄金指标（Golden Signals）：

• Success Rate：用户目标达成率（非API成功率）；
• Latency Distribution：P50/P90/P99延迟，而非平均值；
• Fallback Rate：规则引擎/缓存兜底的调用占比；
• Tool Churn：单次会话中Tool调用次数，过高说明规划能力差。

避坑方案：

• 在Agent执行层埋点，每完成一次用户会话，上报4个黄金指标到Grafana；
• 设置P99延迟>1.5s自动告警，Success Rate<85%自动触发根因分析（RCA）流程；
• 禁止用离线测试集代替线上监控——线上用户永远问出训练数据里没有的问题。

3.10 “Hermes Agent”不是开源项目，而是参考实现

坑点：Hermes Agent官网宣称“企业级Agent框架”，新手下载源码试图魔改。

真相：Hermes是特定场景（工业设备远程诊断）的参考实现，其核心价值是展示了：1）如何用MCP对接PLC；2）如何用规则引擎处理设备告警；3）如何在边缘设备上部署轻量模型。它不是通用框架。

避坑方案：

• 学习Hermes的MCP适配器代码，但不要用它的调度器；
• 复用Hermes的设备知识图谱Schema，但不要用它的Neo4j存储——改用PostgreSQL JSONB更易运维；
• Hermes的“技能（Skill）”概念，本质是Tool的别名，无需单独建模。

3.11 “Skill和Agent的区别”是层级混淆

坑点：文档里区分“Skill”和“Agent”，导致团队建两个服务。

真相：Skill是原子能力单元，Agent是能力组合体。一个Agent必然包含多个Skill，但Skill不能独立对外提供服务。

避坑方案：

• Skill = Tool + MCP Adapter + 元数据（description, input_schema, output_schema）；
• Agent = Skill集合 + 规划器（Planner） + 记忆管理器（Memory Manager）；
• 部署时，Skill作为WASM模块注册到Runtime，Agent作为独立服务调用Runtime。

类比：Skill是汽车发动机，Agent是整车。你不会单独卖发动机给用户，但整车必须有发动机。

3.12 “AI替代传统GUI”不是技术，而是交互范式革命

坑点：看到“基于MCP的ObCloud工作流”，以为只要接入MCP就能替代GUI。

真相：GUI替代的关键不是技术，而是用户心智模型迁移。用户接受“用自然语言操作软件”，需满足三个条件：

• 确定性：说“删除第3行”，必须100%删第3行，不能概率性删错；
• 可预测性：用户能预判Agent下一步动作（如输入“导出报表”，Agent必先问格式再问路径）；
• 可撤销性：所有操作必须有Undo按钮，且Undo能精确回退到上一步状态。

避坑方案：

• 在Agent执行层强制实现“操作预览”（Preview Mode）：执行前显示“将执行：删除表格第3行，影响1条数据”，用户确认后才执行；
• 所有GUI操作必须映射到MCP Action，禁止在Agent里写“点击坐标(120,340)”这类像素级指令；
• Undo功能不是前端实现，而是执行层保存State快照，Undo时恢复到上一个快照。

用户反馈：某财务Agent上线后，用户投诉“不敢用”，因为怕删错数据。加入Preview Mode和Undo后，周活跃度提升3.2倍。

4. 实操过程：从零搭建一个Figma MCP Agent的完整链路

理论说完，现在带你走一遍真实项目——为Figma设计团队打造一个“一键生成设计规范文档”的Agent。全程基于五层架构，所有工具、配置、参数均来自我们已上线的生产环境。

4.1 环境准备与工具链

我们放弃“全栈框架”，按五层架构选型：

• 终端交互层：Figma Plugin（TypeScript） + Whisper.cpp WASM（语音输入）；
• 协议适配层：自研figma-mcp-adapter（Node.js，处理Figma SceneNode ID映射）；
• Agent执行层：LangGraph StateGraph（编排） + Wasmer Runtime（执行WASM Tool）；
• 模型服务层：L0规则引擎（Rust，提取颜色/字体/间距） + L1 Phi-3-mini（生成文档）；
• 数据与知识层：ChromaDB（设计规范向量库） + PostgreSQL（用户历史生成记录）。

注意：所有工具版本锁定，避免“npm install后Agent崩溃”。我们用pnpm lockfile固化依赖，关键版本：Figma Plugin API v2.12.0、Wasmer v4.3.0、Phi-3-mini-Q4_K_M（llama.cpp v0.22）。

4.2 终端层：Figma插件开发要点

Figma插件开发有两大陷阱：1）沙箱环境无法访问fetch；2）UI渲染与主线程阻塞。

解决方案：

• 用Figma官方figma.clientStorage替代localStorage，存Token和用户偏好；
• 所有网络请求走figma.currentPage的fetch方法