# AI 基础概念案例教学分享

> **分享主题**：AI 原生应用开发基础
> **面向人群**：公司 AI 小组
> **时长**：约 60 分钟
> **更新日期**：2026-03-18

---

## 目录

- [一、什么是 AI 原生应用](#一什么是-ai-原生应用)
- [二、核心概念讲解](#二核心概念讲解)
  - [2.1 MCP - Model Context Protocol](#21-mcp---model-context-protocol)
  - [2.2 Agent - AI 智能代理](#22-agent---ai-智能代理)
  - [2.3 Skills - 技能系统](#23-skills---技能系统)
  - [2.4 Workflow - 工作流编排](#24-workflow---工作流编排)
- [三、实战案例](#三实战案例)
  - [3.1 案例一：天气查询技能](#31-案例一天气查询技能)
  - [3.2 案例二：文件处理工作流](#32-案例二文件处理工作流)
  - [3.3 案例三：多 Agent 协作系统](#33-案例三多-agent-协作系统)
- [四、最佳实践](#四最佳实践)
- [五、常见问题](#五常见问题)

---

## 一、什么是 AI 原生应用

### 1.1 传统应用 vs AI 原生应用

| 特性 | 传统应用 | AI 原生应用 |
|------|---------|-------------|
| **交互方式** | 固定表单、按钮 | 自然语言对话 |
| **逻辑控制** | 硬编码的 if/else | LLM 动态理解和决策 |
| **扩展能力** | 需要开发新功能 | 通过 Skills 动态扩展 |
| **数据处理** | 规则引擎 | AI 理解 + 工具调用 |
| **学习能力** | 无 | 持续学习和适应 |

### 1.2 AI 原生应用的三个层次

```
┌─────────────────────────────────────┐
│   用户层：自然语言交互               │
├─────────────────────────────────────┤
│   Agent 层：理解意图、规划任务       │
├─────────────────────────────────────┤
│   Tool 层：执行具体操作（MCP）       │
├─────────────────────────────────────┤
│   Resource 层：数据库、API、文件    │
└─────────────────────────────────────┘
```

---

## 二、核心概念讲解

### 2.1 MCP - Model Context Protocol

#### 概念定义

**MCP (Model Context Protocol)** 是连接 LLM 和外部资源（数据库、API、文件系统等）的标准化协议。

#### 核心价值

1. **标准化接口**：统一不同资源的访问方式
2. **能力声明**：AI 自动理解可用的工具
3. **安全隔离**：可控的权限范围
4. **动态发现**：运行时发现和调用工具

#### MCP 工具的类型

```typescript
// 工具定义示例
{
  "name": "weather_get",
  "description": "获取指定城市的天气信息",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称"
      },
      "days": {
        "type": "number",
        "description": "预报天数（1-7）"
      }
    },
    "required": ["city"]
  }
}
```

#### 实际案例：OpenClaw 中的 MCP 工具

在 OpenClaw 中，所有外部调用都通过 MCP 工具实现：

- `feishu_doc` - 飞书文档读写
- `feishu_bitable_list_records` - 飞书多维表格查询
- `web_search` - 网络搜索
- `exec` - Shell 命令执行
- `read`/`write` - 文件操作

#### MCP 工作流程

```
用户提问 → LLM 理解意图 → 选择 MCP 工具 → 调用工具 → 获取结果 → 组织回答
```

---

### 2.2 Agent - AI 智能代理

#### 概念定义

**Agent** 是具有自主决策能力的 AI 实体，能够理解任务、规划步骤、调用工具、持续迭代。

#### Agent 的核心能力

1. **任务理解**：将自然语言转化为可执行步骤
2. **步骤规划**：拆解复杂任务为子任务
3. **工具调用**：动态选择和组合 MCP 工具
4. **错误处理**：遇到问题自动重试或调整策略
5. **记忆管理**：记住上下文和关键信息

#### Agent vs 传统脚本

| 场景 | 传统脚本 | Agent |
|------|---------|-------|
| 任务：查询天气 | `weather("北京")` | "帮我查一下北京明天的天气" |
| 数据处理 | 固定的 ETL 流程 | "帮我分析这个 CSV 文件中的趋势" |
| 问题排查 | 预定义的检查项 | "为什么这个接口响应很慢？帮我排查一下" |

#### Agent 示例：OpenClaw 的角色分工

根据我们的 "1+2" 协作体系：

```
OC-Master (主控 Agent)
  ├── 任务接收和分发
  ├── 项目管理
  └── 结果汇总

OC-Dev (开发 Agent)
  ├── 代码分析
  ├── 技术评估
  └── 方案设计

OC-Media (内容 Agent)
  ├── 文案生成
  ├── 内容创作
  └── 格式转换
```

#### Agent 的系统提示词示例

```markdown
你是一个专业的代码审查 Agent。

职责：
1. 分析代码结构和设计模式
2. 识别潜在的性能问题和安全风险
3. 提供具体的改进建议
4. 保持客观、专业的语气

工作流程：
1. 阅读代码文件
2. 使用 read 工具检查相关依赖
3. 运行必要的测试
4. 输出详细的审查报告

注意事项：
- 不要执行删除或修改操作
- 建议要具体、可操作
- 考虑代码的可维护性
```

---

### 2.3 Skills - 技能系统

#### 概念定义

**Skills** 是预定义的、可复用的能力单元，让 Agent 快速掌握特定领域的专业知识。

#### Skills 的价值

1. **知识封装**：将领域知识打包成独立模块
2. **快速激活**：按需加载，节省上下文
3. **持续更新**：独立迭代，不影响系统核心
4. **社区共享**：从 ClawHub 获取现成技能

#### Skills 文件结构

```
skill-name/
├── SKILL.md              # 技能说明文档（必选）
├── USAGE.md              # 使用指南
├── references/           # 参考文档、代码片段
├── scripts/              # 辅助脚本
└── .clawhub/origin.json  # 技能来源信息
```

#### Skills 触发机制

OpenClaw 支持自动技能发现：

```typescript
// skills/tailwind-builder/_meta.json
{
  "triggers": [
    "tailwind cdn",
    "optimize html page",
    "tailwind build",
    "cdn.tailwindcss.com"
  ],
  "emoji": "🎨",
  "version": "1.0.0"
}
```

当用户提到触发词时，系统自动加载对应的 SKILL.md。

#### Skills 示例：Tailwind Builder

**场景**：用户发送一个使用 Tailwind CDN 的 HTML 文件

**用户提问**：
> "帮我优化这个页面，它加载很慢"

**自动触发**：
1. 检测到 `cdn.tailwindcss.com`
2. 加载 `skills/tailwind-builder/SKILL.md`
3. 执行构建流程：
   - 初始化 Node.js 项目
   - 安装 Tailwind CSS
   - 生成配置文件
   - 编译静态 CSS
   - 替换 HTML 中的 CDN 引用

**结果**：文件大小从 3.5MB 减少到 19KB，加载速度提升 98.5%

#### 如何创建自定义 Skills

**步骤 1：创建技能目录**
```bash
mkdir -p ~/.openclaw-master/workspace/skills/my-skill
cd ~/.openclaw-master/workspace/skills/my-skill
```

**步骤 2：编写 SKILL.md**
```markdown
# My Skill

## 触发条件
- 用户提到"数据分析"
- 需要处理 CSV 文件

## 工作流程
1. 读取文件
2. 分析数据结构
3. 生成可视化图表
4. 输出分析报告
```

**步骤 3：添加元数据**
```json
{
  "name": "my-skill",
  "emoji": "📊",
  "version": "1.0.0",
  "triggers": ["数据分析", "csv分析"]
}
```

---

### 2.4 Workflow - 工作流编排

#### 概念定义

**Workflow** 是将多个 Agent、Skills、MCP 工具组合起来，完成复杂业务流程的编排方式。

#### Workflow 的类型

**1. 顺序工作流**
```
任务 → 步骤1 → 步骤2 → 步骤3 → 结果
```

**2. 并行工作流**
```
任务
  ├→ 步骤1 ─┐
  ├→ 步骤2 ─┼→ 结果汇总
  └→ 步骤3 ─┘
```

**3. 条件分支**
```
任务 → 条件判断
       ├→ 分支A → 结果A
       └→ 分支B → 结果B
```

**4. 迭代循环**
```
任务 → 执行 → 评估
       ↑_____条件_____│
```

#### Workflow 实战案例

**场景**：小红书内容生产工作流

```
1. OC-Master 接收任务
   "帮我写一篇关于 AI 工具的小红书文案"

2. OC-Master 分解任务
   - 技术调研（交给 OC-Dev）
   - 内容创作（交给 OC-Media）

3. 并行执行
   OC-Dev: 搜索最新的 AI 工具，整理技术要点
   OC-Media: 结合技术点，创作吸引人的文案

4. 结果汇总
   - 技术要点列表
   - 小红书爆款文案
   - 建议配图方向

5. OC-Master 输出完整方案
```

#### Workflow 配置示例

```yaml
# workflow/content-production.yaml
name: "内容生产工作流"
steps:
  - name: "技术调研"
    agent: "oc-dev"
    skills: ["web-research", "code-analysis"]
    tools: ["web_search", "read"]

  - name: "内容创作"
    agent: "oc-media"
    skills: ["copywriting", "xiaohongshu-style"]
    tools: ["write"]

  - name: "质量检查"
    agent: "oc-master"
    skills: ["quality-review"]
    condition: "content.length > 500"
```

---

## 三、实战案例

### 3.1 案例一：天气查询技能

#### 需求描述

用户可以通过自然语言查询任意城市的天气信息。

#### 技术实现

**1. MCP 工具定义**
```typescript
// 工具：weather_get
{
  "name": "weather_get",
  "description": "通过 wttr.in API 获取天气信息",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" },
      "format": { "type": "string", "enum": ["json", "text"] }
    },
    "required": ["city"]
  }
}
```

**2. Skill 封装**
```markdown
# weather Skill

## 触发条件
- 用户提到"天气"
- 用户提到"温度"
- 用户提到"预报"

## 工作流程
1. 识别城市名称
2. 调用 wttr.in API
3. 解析响应数据
4. 格式化输出
```

**3. 实际调用**
```bash
# 用户提问
"北京今天天气怎么样？"

# Agent 理解
城市: 北京
时间: 今天

# 工具调用
curl wttr.in/Beijing?format=j1

# 返回结果
当前温度：15°C
天气状况：晴
湿度：45%
```

#### 关键点总结

- ✅ MCP 提供标准化的 API 访问
- ✅ Skill 封装了天气查询的专业逻辑
- ✅ Agent 负责理解用户意图
- ✅ 无需硬编码，支持自然语言交互

---

### 3.2 案例二：文件处理工作流

#### 需求描述

用户发送一个 Markdown 文件，Agent 需要分析文件内容、提取关键信息、生成总结。

#### 技术实现

**1. 文件接收（Feishu 通道）**
```
用户发送 MD 文件
  ↓
飞书 Webhook 接收
  ↓
下载文件到 /media/inbound/
  ↓
文件路径传递给 Agent
```

**2. Agent 处理流程**
```typescript
// 步骤 1：读取文件
const content = await read({ path: "/media/inbound/file.md" });

// 步骤 2：分析内容
const analysis = await analyzeDocument(content);

// 步骤 3：提取关键信息
const keyPoints = await extractKeyPoints(content);

// 步骤 4：生成总结
const summary = await generateSummary(keyPoints);

// 步骤 5：输出结果
return {
  summary,
  keyPoints,
  analysis
};
```

**3. 实际案例**

**用户发送**：`基于平台_MCP_问题排查案例分享.md`

**Agent 执行**：
```
1. 读取文件内容 ✓
2. 识别文档结构（目录、章节）✓
3. 提取核心案例 ✓
4. 生成 200 字总结 ✓
```

**输出结果**：
> 这份文档分享了基于平台 MCP 的内存排查案例，涵盖了工具链安装、权限配置、问题定位等关键环节，提供了完整的排查流程和最佳实践。

#### 关键点总结

- ✅ 文件自动下载到 `media/inbound/`
- ✅ Agent 自动理解文件类型和内容
- ✅ 支持多种文件格式（MD、PDF、DOCX）
- ✅ 智能提取和总结

---

### 3.3 案例三：多 Agent 协作系统

#### 需求描述

用户需要创建一个技术博客文章，包含代码示例、技术分析、SEO 优化内容。

#### 技术实现

**1. Agent 角色分工**

```typescript
// 主控 Agent (OC-Master)
职责：
- 接收用户需求
- 分解任务
- 协调子 Agent
- 汇总结果

// 开发 Agent (OC-Dev)
职责：
- 技术方案设计
- 代码示例编写
- 技术要点分析

// 内容 Agent (OC-Media)
职责：
- 文案创作
- SEO 优化
- 排版美化
```

**2. 协作流程**

```
用户: "帮我写一篇关于 MCP 的博客文章"

OC-Master:
  1. 理解需求
  2. 分解任务：
     - OC-Dev: 技术调研 + 代码示例
     - OC-Media: 文案 + SEO

[并行执行]
OC-Dev:
  - 搜索 MCP 相关资料
  - 编写代码示例
  - 技术要点总结

OC-Media:
  - 研究受众需求
  - 创作 SEO 友好的标题
  - 优化内容结构

[结果汇总]
OC-Master:
  - 整合技术内容
  - 融合文案
  - 输出完整博客
```

**3. 实际输出**

```markdown
# MCP：连接 LLM 和外部世界的桥梁

[技术内容 - OC-Dev 提供]
MCP (Model Context Protocol) 是一种标准化协议...

[代码示例 - OC-Dev 提供]
```json
{
  "name": "my_tool",
  "description": "..."
}
```

[SEO 内容 - OC-Media 提供]
关键词：AI、MCP、LLM、模型协议
建议标题长度：60 字符以内
```

#### 关键点总结

- ✅ 多 Agent 并行处理，提升效率
- ✅ 每个 Agent 专注自己的领域
- ✅ 主控 Agent 负责任务编排
- ✅ 支持动态调整分工

---

## 四、最佳实践

### 4.1 MCP 工具设计

**✅ 做对的事**
- 提供清晰的 `description`
- 定义精确的 `inputSchema`
- 处理错误和异常情况
- 遵循单一职责原则

**❌ 避免的事**
- 工具命名不清晰
- 参数定义模糊
- 忽略错误处理
- 一个工具做太多事

### 4.2 Agent 设计

**✅ 做对的事**
- 明确 Agent 的职责边界
- 提供详细的系统提示词
- 设计合理的记忆机制
- 测试多种输入场景

**❌ 避免的事**
- Agent 职责重叠
- 系统提示词过于复杂
- 没有记忆机制
- 只考虑理想情况

### 4.3 Skills 管理

**✅ 做对的事**
- 保持 Skills 独立性
- 编写清晰的 SKILL.md
- 设置合理的触发条件
- 定期更新和优化

**❌ 避免的事**
- Skills 之间强依赖
- 文档不完整
- 触发条件过于宽泛
- 长期不维护

### 4.4 Workflow 设计

**✅ 做对的事**
- 合理拆分任务
- 设计容错机制
- 支持人工干预
- 记录执行日志

**❌ 避免的事**
- Workflow 过于复杂
- 没有超时控制
- 忽略异常处理
- 无法调试和追踪

---

## 五、常见问题

### Q1: MCP 和 API 有什么区别？

**A**: MCP 是 LLM 调用 API 的标准化协议，包含：
- 能力声明（工具列表）
- 参数验证
- 错误处理
- 安全控制

API 是 MCP 的底层实现方式之一。

### Q2: 如何选择合适的 Agent 数量？

**A**: 取决于：
- 任务复杂度（简单任务 1 个 Agent）
- 服务器资源（内存、CPU）
- 并行需求（是否需要同时处理多个任务）

建议：从 1 个 Agent 开始，逐步拆分。

### Q3: Skills 什么时候需要更新？

**A**: 出现以下情况时：
- 领域知识发生变化
- 工具 API 更新
- 发现新的使用场景
- 用户反馈问题

### Q4: Workflow 失败了怎么办？

**A**: 设计 Workflow 时应包含：
- 每个步骤的超时控制
- 失败重试机制
- 人工干预入口
- 详细日志记录

### Q5: 如何评估 AI 原生应用的质量？

**A**: 关注以下指标：
- 任务完成率
- 响应时间
- 用户满意度
- 错误率
- 资源消耗

---

## 附录

### A. 推荐学习资源

- [OpenClaw 文档](https://docs.openclaw.ai)
- [MCP 协议规范](https://modelcontextprotocol.io)
- [ClawHub 技能市场](https://clawhub.com)

### B. 实战练习建议

1. **从简单开始**：创建一个天气查询 Skill
2. **逐步增加**：添加文件处理能力
3. **尝试协作**：设计多 Agent Workflow
4. **持续优化**：根据用户反馈改进

### C. 交流与分享

- 加入 OpenClaw 社区：https://discord.com/invite/clawd
- 提交你的 Skill 到 ClawHub
- 分享你的最佳实践

---

**祝分享顺利！如有问题，随时交流。** 🎉