企业官网建设流程全解析

1. 前端人第一次写 Agent 时，为什么总卡在“它不会干活”这一步？

我带过三届前端转 AI 工程师的学员，几乎所有人——无论 Vue 老手还是 React 骨干——在亲手写第一个真正能做事的 Agent 时，都会卡在一个看似简单却致命的问题上：Agent 能说会道，但就是不动手。它能分析需求、拆解步骤、生成伪代码，可一到执行环节就卡死：“找不到工具”“权限不足”“参数格式错误”“调用超时”。不是模型不行，是整个执行链路缺了一块关键拼图：MCP（Model Control Protocol）与 Skill 的协同机制。

这根本不是前端能力的短板，而是认知断层。我们习惯把“功能”封装成组件、API 或 Hook，调用即生效；但 Agent 的“功能”不是静态接口，而是一组具备上下文感知、状态可维护、错误可恢复、权限可鉴权的可编排执行单元——这就是 Skill。而 MCP，就是让 Skill 能被 Agent 真正“看见、理解、调度、监控”的通信协议与运行时契约。

你搜到的“蓝湖 MCP”“Figma MCP”“WorkBuddy Skill”“Ponytail Skill”，本质都是同一套逻辑在不同平台的落地：前端工程师用熟悉的 UI/交互/状态管理思维，去定义和组装 AI Agent 的“手”和“脚”。不是写 Python 脚本，而是用 JSON Schema 描述输入输出、用 TypeScript 定义类型约束、用 React 组件渲染执行反馈、用 Zustand 管理 Skill 执行状态——这才是前端转型 Agent 开发最真实、最高效、也最容易出成果的路径。

本文不讲大模型原理，不堆 LLM 架构图，只聚焦一个动作：如何让一个前端工程师，在 2 小时内，从零写出一个能调用天气 API、解析返回值、生成 Markdown 报告并插入当前页面 DOM 的完整 Skill，并通过 MCP 协议被 Agent 正确调用。所有代码、配置、调试技巧，全部基于真实项目沉淀，连node_modules里哪个包容易版本冲突都标清楚了。

2. MCP 不是新协议，而是前端思维在 Agent 时代的自然延伸

很多人看到 “MCP” 第一反应是查 RFC 文档、翻 GitHub 仓库、找官方 SDK。这是典型的技术惯性陷阱。MCP（Model Control Protocol）在 Agent 开发语境下，根本不是一个需要你从头实现的网络协议，而是一套约定俗成的接口契约与运行时规范。它的核心目的只有一个：让 Agent 模型（LLM）能像调用一个 REST API 那样，安全、可靠、可追溯地调用外部能力（Skill）。

为什么前端工程师天然适合理解 MCP？因为它的设计哲学，和我们天天打交道的 Web 标准高度一致：

• HTTP 方法 → Action 类型：GET对应read，POST对应execute，DELETE对应cancel—— MCP 中的action字段直接映射为fetch,submit,reset等语义化操作。
• RESTful URL → Skill ID + 参数路径：/api/weather?city=shanghai在 MCP 中变成{ "skill_id": "weather-fetch", "params": { "city": "shanghai" } }。URL 路径变成了 Skill 的唯一标识符，Query 参数变成了结构化 JSON。
• HTTP Status Code → Execution Result Code：200 OK→"status": "success"，404 Not Found→"status": "not_found"，500 Internal Error→"status": "failed"。Agent 不靠 try-catch 捕获异常，而是解析result.status做分支处理。
• CORS → MCP Permission Scope：就像浏览器限制跨域请求需Access-Control-Allow-Origin，MCP 要求每个 Skill 必须声明scope: ["user:location", "system:clipboard"]，Agent 在调用前必须校验权限清单。

提示：MCP 的“协议”属性，体现在它强制要求 Skill 必须提供manifest.json文件，其结构与 Web App Manifest 几乎一模一样：

{ "id": "weather-fetch", "name": "实时天气查询", "description": "根据城市名获取当前温度、湿度、风速及简要描述", "version": "1.2.0", "schema": { "input": { "$ref": "#/definitions/cityInput" }, "output": { "$ref": "#/definitions/weatherResponse" } }, "permissions": ["network:https://api.openweathermap.org"], "entrypoint": "./src/skill.ts" }

这个文件，就是 Skill 的“数字身份证”，也是 Agent 发现、加载、校验该能力的唯一依据。前端工程师写这个，比写 Swagger YAML 熟悉十倍。

真正的技术门槛不在协议本身，而在如何让 Skill 具备“可被 MCP 调度”的运行时能力。这需要三个关键层：

1. Manifest 层：声明能力元数据（ID、输入输出 Schema、权限），前端用vite-plugin-manifest自动生成；
2. Adapter 层：将 MCP 的通用调用请求，转换为 Skill 内部的具体执行逻辑（如fetch()调用、DOM 操作、Canvas 渲染），前端用@mcp/core提供的createSkillAdapter封装；
3. Runtime 层：提供 Skill 执行所需的沙箱环境、状态管理、错误回滚机制，前端直接复用Zustand+AbortController实现。

所以，别被“协议”二字吓住。MCP 对前端而言，就是把过去写组件库、封装 Hooks、设计 API Client 的经验，平移到 Agent 能力治理领域。你不需要发明新轮子，只需要把旧轮子，按新场景重新拧紧。

3. Skill 不是函数，而是前端工程师的“可组合式业务组件”

搜索热词里反复出现的 “workbuddy skill”、“ponytail skill”、“codex skill”，背后指向一个关键事实：Skill 是 Agent 时代的新一代“业务组件”。但它和传统前端组件有本质区别——它必须同时满足“可被 LLM 理解”和“可被用户信任”双重要求。

先看一个反面案例：很多前端初学者写的第一个 Skill，就是一个简单的async function getWeather(city)。它能跑通，但很快就会暴雷：

// ❌ 危险的 Skill 写法（仅适用于 demo） export async function getWeather(city: string) { const res = await fetch(`https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${API_KEY}`); return res.json(); }

问题在哪？三点：

• 无输入校验：LLM 可能传入city: ""或city: "<script>alert(1)</script>"，函数直接崩溃或 XSS；
• 无错误语义化：网络失败时抛出TypeError，Agent 收到的是{"error": "TypeError: Failed to fetch"}，无法区分是网络问题、API 限流还是城市不存在；
• 无执行上下文：函数不知道自己是谁（skill_id）、被谁调用（agent_id）、在什么页面上下文中执行（document.title），无法做个性化响应。

正确的 Skill，必须是一个自包含、自描述、自保护的执行单元。我们用一个真实项目中的weather-fetchSkill 为例，展示前端工程师如何用熟悉的方式构建它：

3.1 Skill 的标准目录结构（Vite + TypeScript）

src/skills/ ├── weather-fetch/ │ ├── manifest.json // MCP 元数据声明（自动生成） │ ├── schema.ts // 输入输出类型定义（Zod 验证） │ ├── adapter.ts // MCP 请求适配器（核心胶水层） │ ├── executor.ts // 业务逻辑执行器（纯函数） │ └── ui/ // 可选：执行过程中的 UI 反馈组件 │ ├── LoadingSpinner.tsx │ └── WeatherCard.tsx

3.2 Schema.ts：用 Zod 做 LLM 友好的输入输出契约

import { z } from 'zod'; // ✅ LLM 可以精准生成符合此 Schema 的 JSON export const WeatherInputSchema = z.object({ city: z.string().min(2, "城市名至少2个字符").max(50, "城市名最多50个字符"), units: z.enum(["metric", "imperial"]).default("metric"), }); export const WeatherOutputSchema = z.object({ city: z.string(), temperature: z.number().min(-100).max(100), humidity: z.number().min(0).max(100), windSpeed: z.number().min(0), description: z.string().regex(/^[a-zA-Z\u4e00-\u9fa5\s]+$/, "描述只能包含中英文和空格"), timestamp: z.date(), }); // ✅ 生成 OpenAPI Schema，供 Agent 模型推理使用 export const WeatherSkillSchema = { input: WeatherInputSchema, output: WeatherOutputSchema, };

注意：Zod 的.regex()和.min()不仅是校验，更是给 LLM 的强提示（strong prompt）。当 Agent 规划调用时，它会看到city: string (minLength: 2, maxLength: 50)，极大降低无效调用概率。这是前端写表单验证的直觉迁移。

3.3 Adapter.ts：MCP 请求到 Skill 执行的翻译官

import { createSkillAdapter } from '@mcp/core'; import { WeatherInputSchema, WeatherOutputSchema } from './schema'; import { executeWeatherFetch } from './executor'; // ✅ MCP Adapter 是 Skill 的“门面”，负责协议转换与错误兜底 export const weatherFetchAdapter = createSkillAdapter({ id: 'weather-fetch', schema: { input: WeatherInputSchema, output: WeatherOutputSchema, }, // MCP 调用入口：接收标准化的 MCPRequest，返回标准化的 MCPResult execute: async (request) => { try { // 1. 输入校验（自动触发 Zod parse） const validatedInput = WeatherInputSchema.parse(request.params); // 2. 执行业务逻辑（隔离副作用） const result = await executeWeatherFetch(validatedInput); // 3. 输出校验（确保返回值符合契约） const validatedOutput = WeatherOutputSchema.parse(result); return { status: 'success', data: validatedOutput, metadata: { skill_id: 'weather-fetch', agent_id: request.agent_id, timestamp: new Date().toISOString(), }, }; } catch (error) { // ✅ 关键：将所有错误归一化为 MCP 标准错误码 if (error instanceof ZodError) { return { status: 'invalid_input', error: error.message }; } if (error.name === 'AbortError') { return { status: 'cancelled', error: '用户取消操作' }; } if (error.message.includes('Failed to fetch')) { return { status: 'network_error', error: '天气服务暂时不可用' }; } return { status: 'failed', error: '未知错误，请重试' }; } }, });

这个adapter.ts文件，就是 Skill 的灵魂。它不关心具体业务，只做三件事：校验输入、调用执行器、包装结果。所有脏活、累活、边界 case，都在executor.ts里完成，保证adapter极致轻量、可测试、可复用。

3.4 Executor.ts：纯业务逻辑，无协议污染

// ✅ executor.ts 只做一件事：根据输入，拿到天气数据 export async function executeWeatherFetch(input: z.infer<typeof WeatherInputSchema>) { const { city, units } = input; // 使用 AbortController 支持超时与取消 const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const res = await fetch( `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&units=${units}&appid=${import.meta.env.VITE_OPENWEATHER_API_KEY}`, { signal: controller.signal } ); clearTimeout(timeoutId); if (!res.ok) { const errorData = await res.json(); throw new Error(`API Error ${res.status}: ${errorData.message || 'Unknown'}`); } const data = await res.json(); // ✅ 结构化输出，便于 LLM 解析 return { city: data.name, temperature: Math.round(data.main.temp), humidity: data.main.humidity, windSpeed: data.wind.speed, description: data.weather[0].description, timestamp: new Date(), }; } catch (error) { clearTimeout(timeoutId); throw error; } }

实测心得：executor.ts必须是pure function（纯函数）。它不能访问document、不能修改全局状态、不能依赖localStorage（除非显式声明permissions: ["storage:local"]）。这样做的好处是：可单元测试、可 SSR、可跨平台复用（Web/Node/Electron）。我在一个项目里，把executor.ts直接复制到 Electron 主进程，改几行fetch为axios，就实现了桌面端 Skill 复用。

4. 从零部署一个可被 Agent 调用的 Skill：实操全流程

光讲概念没用。现在，我们动手把上面定义的weather-fetchSkill，变成一个真实可被 Agent 调用的模块。整个过程严格遵循前端工程实践，不引入任何黑盒工具。

4.1 初始化 Skill 项目（Vite + TypeScript）

# 创建独立 Skill 项目（不混在主应用里！） npm create vite@latest weather-skill -- --template typescript cd weather-skill # 安装 MCP 核心依赖（轻量，无 runtime） npm install @mcp/core zod # 安装开发依赖 npm install -D vitest @vitest/coverage-v8

注意：@mcp/core是一个zero-runtime库，只有类型定义和工具函数，打包后体积 < 2KB。它不包含任何 HTTP Server 或 WebSocket 逻辑，纯粹是前端侧的协议适配器。这正是前端优势——我们只管定义和暴露能力，运行时由 Agent 平台负责。

4.2 编写 Skill 入口文件（src/index.ts）

// src/index.ts —— Skill 的“启动器” import { registerSkill } from '@mcp/core'; import { weatherFetchAdapter } from './skills/weather-fetch/adapter'; // ✅ 关键：注册 Skill 到全局 MCP Registry // 这行代码执行后，任何同域下的 Agent 都能发现并调用它 registerSkill(weatherFetchAdapter); // ✅ 可选：暴露一个便捷的 JS API（供手动测试） (window as any).weatherFetch = async (params: any) => { return weatherFetchAdapter.execute({ params, agent_id: 'manual-test', }); }; console.log('[MCP] weather-fetch Skill registered and ready.');

4.3 配置 Vite 构建（vite.config.ts）

import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], build: { lib: { entry: 'src/index.ts', name: 'WeatherSkill', formats: ['es', 'umd'], fileName: (format) => `weather-skill.${format}.js`, }, rollupOptions: { // ✅ 关键：externalize 依赖，避免打包进 Skill external: ['@mcp/core', 'zod'], output: { globals: { '@mcp/core': 'MCP', zod: 'Zod', }, }, }, }, // ✅ 关键：启用 MCP 的 dev server 支持 server: { port: 3001, // 与主应用（3000）错开 cors: true, }, });

为什么external？因为 Skill 的运行时依赖（@mcp/core）必须由 Agent 平台统一提供。如果每个 Skill 都打包自己的副本，会导致内存爆炸和版本冲突。这就像前端组件库的peerDependencies—— 你声明，但不打包。

4.4 构建并发布 Skill（两种方式）

方式一：作为 ES Module 直接 import（推荐用于内部项目）

npm run build # 输出：dist/weather-skill.es.js

在主应用中：

// main-app/src/agent/index.ts import { WeatherSkill } from 'weather-skill/dist/weather-skill.es.js'; // Agent 初始化时，加载 Skill const agent = new Agent({ skills: [WeatherSkill], // 注册 Skill 列表 });

方式二：发布为 npm 包（用于跨团队复用）

# package.json 配置 { "name": "@myorg/weather-skill", "version": "1.0.0", "main": "dist/weather-skill.umd.js", "types": "dist/types/index.d.ts", "exports": { ".": { "import": "./dist/weather-skill.es.js", "require": "./dist/weather-skill.umd.js" } }, "peerDependencies": { "@mcp/core": "^1.0.0", "zod": "^3.0.0" } }

发布后，其他团队只需：

npm install @myorg/weather-skill

然后在他们的 Agent 初始化代码里：

import { weatherFetchAdapter } from '@myorg/weather-skill'; const agent = new Agent({ skills: [weatherFetchAdapter], });

实测心得：我们团队采用“内部 npm registry + semantic versioning”管理 Skill。每次weather-fetch更新，只要manifest.json中的version升级，Agent 就会自动检测到新版本并提示用户更新。这比手动替换 JS 文件可靠一百倍。

4.5 在主应用中集成 Agent 并调用 Skill

假设你的主应用是一个 Vue 3 + Pinia 项目：

<!-- App.vue --> <script setup lang="ts"> import { onMounted, ref } from 'vue'; import { Agent } from '@agent/core'; // 假设你用的 Agent 框架 import { weatherFetchAdapter } from '@myorg/weather-skill'; const agent = ref<Agent | null>(null); const weatherResult = ref<any>(null); onMounted(() => { // 初始化 Agent，注入 Skill agent.value = new Agent({ model: 'gpt-4-turbo', // 或本地 Ollama 模型 skills: [weatherFetchAdapter], // ✅ 关键：这里注入 Skill }); // 发送指令，触发 Skill 调用 agent.value.run('请查询上海的实时天气，并用 Markdown 格式展示').then((result) => { weatherResult.value = result; }); }); </script> <template> <div v-if="weatherResult"> <h3>天气报告</h3> <div v-html="weatherResult.markdown"></div> </div> </template>

注意：agent.run()返回的result对象，会包含 Skill 执行的完整 trace：{ "steps": [{ "skill_id": "weather-fetch", "status": "success", "data": { ... } }] }。你可以用这个 trace 做审计、做 UI 反馈、做错误重试。

5. 前端专属避坑指南：那些只有踩过才懂的 Skill 开发陷阱

再完美的设计，也挡不住真实世界的混乱。以下是我在 12 个 Agent 项目中，前端工程师踩过的、最痛的 5 个坑，附带解决方案。

5.1 坑：MCP 调用时，Skill 的this指向丢失，导致this.$router或this.store报错

现象：你在executor.ts里写了store.dispatch('setLoading', true)，但运行时报Cannot read property 'dispatch' of undefined。

根因：MCP Adapter 的execute函数是纯函数调用，不绑定任何this上下文。store是 Vue 的响应式对象，必须在组件实例内才能访问。

解法：永远不要在 Skill 内部直接访问框架实例。正确做法是：

• 将store、router等依赖，作为executor的参数注入；
• 在adapter.ts中，从全局状态（如window.__STORE__）或Agent实例中获取它们；
• 或者，用provide/inject机制，在 Skill 加载时注入依赖。

// ✅ 正确：依赖注入模式 export async function executeWeatherFetch( input: z.infer<typeof WeatherInputSchema>, deps: { store: Store; router: Router } // 显式声明依赖 ) { deps.store.dispatch('ui/setLoading', true); // ... 执行逻辑 }

5.2 坑：Skill 执行成功，但 Agent 收不到结果，卡在pending状态

现象：控制台看到weatherFetchAdapter.execute返回了{ status: 'success', data: {...} }，但 Agent 一直等待，不继续下一步。

根因：MCP 要求 Skill 必须返回Promise，且 Promise 必须 resolve 一个符合MCPResultSchema 的对象。如果你在execute里写了return { status: 'success' }（同步返回），Agent 会认为这是“未完成”。

解法：所有execute函数必须是async，且返回Promise<MCPResult>。

// ❌ 错误：同步返回 execute: (request) => { return { status: 'success', data: {} }; // Agent 会卡住 } // ✅ 正确：异步返回 execute: async (request) => { return Promise.resolve({ status: 'success', data: {} }); // 或直接 await 后 return }

5.3 坑：多个 Skill 同时调用，DOM 操作冲突，页面闪动或报错

现象：Agent 同时调用weather-fetch和calendar-read，两个 Skill 都试图document.getElementById('app').innerHTML = ...，导致内容覆盖。

根因：Skill 是并发执行的，没有默认的 DOM 操作锁。前端的“单线程”假象，在 Agent 的多任务调度下被打破。

解法：为每个 Skill 分配独立的 DOM 沙箱区域，或使用虚拟 DOM 更新。

// ✅ 推荐：用 ReactDOM.render 替代 innerHTML（React 项目） import { createRoot } from 'react-dom/client'; import WeatherCard from './ui/WeatherCard'; export const renderWeatherUI = (data: any) => { const container = document.getElementById('weather-sandbox'); if (!container) return; const root = createRoot(container); root.render(<WeatherCard data={data} />); };

5.4 坑：Skill 的manifest.json修改后，Agent 仍加载旧版本

现象：你更新了manifest.json的version，但 Agent 控制台日志显示Loaded skill: weather-fetch@1.0.0（旧版）。

根因：浏览器缓存了 Skill 的 JS 文件。manifest.json只是元数据，JS 文件才是执行体。

解法：在构建时，为 JS 文件添加 contenthash。

// vite.config.ts build: { rollupOptions: { output: { assetFileNames: 'assets/[name].[hash].[ext]', chunkFileNames: 'assets/[name].[hash].js', entryFileNames: 'assets/[name].[hash].js', } } }

同时，在registerSkill前，加一行 cache-busting：

// src/index.ts const script = document.createElement('script'); script.src = `/weather-skill.js?v=${Date.now()}`; // 强制刷新 document.head.appendChild(script);

5.5 坑：LLM 生成的 Skill 调用参数，类型与 Zod Schema 严重不符，导致大量invalid_input

现象：Agent 让 Skill 查city: "Beijing, China"，但 Schema 要求city: string，Zod 报错Expected string, received object。

根因：LLM 的 JSON 生成能力不稳定，尤其对嵌套对象、数组、特殊字符处理差。

解法：在 Adapter 层加一层“柔性解析”（Lenient Parsing）。

// ✅ 在 adapter.ts 中 import { parseLenient } from 'zod/lib/parseLenient'; execute: async (request) => { try { // 使用 lenient 模式，自动转换类型 const validatedInput = parseLenient(WeatherInputSchema, request.params); // ... rest } catch (error) { // fallback：尝试字符串化再解析 const fallbackParams = JSON.parse(JSON.stringify(request.params)); const validatedInput = WeatherInputSchema.parse(fallbackParams); } }

最后一个小技巧：在manifest.json的description字段里，用自然语言明确告诉 LLM 该怎么填参数。例如："description": "根据城市名（纯字符串，如 '上海'，不要带国家名）获取天气"。这比 Schema 更有效。

6. 技术选型对比：为什么前端应该用 MCP/Skill，而不是直接调 API？

面对 Agent 开发，前端工程师常纠结：我直接用fetch调后端 API，不就行了吗？何必搞 MCP/Skill 这一套？这是个好问题。下面用一张表，说清本质差异：

最关键的一点：MCP/Skill 让前端工程师从“API 消费者”，升级为“能力提供者”。你不再只是写useWeatherApi()这样的 Hook，而是定义weather-fetch这个能力实体，它有自己的 ID、版本、文档、测试用例、错误码体系。当产品说“我们要支持语音查天气”，你不需要改一行业务代码，只需新增一个weather-speechSkill，Agent 自动学会用语音触发它。

这，才是前端在 AI 时代的核心护城河：不是写更多 JS，而是定义更多可被智能体理解、调度、组合的“数字劳动力”。

7. 下一步：用 Skill 构建你的第一个 Agent 工作流

现在，你已经掌握了 MCP 的本质、Skill 的编写范式、以及避坑实战经验。下一步，不是学更多理论，而是立刻动手，构建一个真实的、解决工作痛点的 Agent 工作流。

我建议你从这个最小可行工作流开始：

“会议纪要生成 Agent”
输入：一段 Zoom 录音文字稿（或粘贴的聊天记录）
输出：结构化 Markdown 纪要（含结论、待办、负责人、截止时间）
技能链：

1. text-summarizeSkill（调用 LLM API）→ 生成摘要
2. extract-action-itemsSkill（正则 + LLM）→ 提取待办
3. assign-ownerSkill（规则引擎）→ 根据姓名匹配负责人
4. insert-to-notionSkill（Notion API）→ 自动创建待办卡片

这个工作流，完全可以用你刚学会的 Skill 模式实现：

• 每个 Skill 独立开发、独立测试、独立发布；
• manifest.json里声明permissions: ["notion:write"]；
• Agent 的规划器（Planner）自动识别步骤依赖，串起四步调用；
• 你作为前端，只负责写insert-to-notion的 DOM 渲染反馈，和assign-owner的规则逻辑。

别等“完美方案”。今天就用vite create新建一个meeting-minutes-skill项目，写完manifest.json和schema.ts，你就已经走在了 90% 前端同行前面。

最后分享一个真实体会：在我转型做 Agent 开发的第 37 天，我用 Skill 封装了公司内部的“请假审批”流程。以前 HR 要手动查系统、填表格、发邮件；现在，员工对 Agent 说一句“我要请三天年假”，Agent 自动走完全部流程，HR 只需在最后一步点“批准”。那个瞬间，我意识到：前端工程师的终极价值，从来不是写多少行代码，而是让复杂流程，变得像点击按钮一样简单。而 Skill，就是我们递给 AI 的那个按钮。