> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# AI 集成路线图

retaintive 产品的 AI 能力升级路线图。本文回答三个问题：我们有什么 AI 能力可用、该优先做什么（ROI 排序）、具体怎么做（架构 + Workflow）。

**读者**：产品负责人、后端工程师、Tech Lead。读完后能判断每个集成机会的优先级和技术可行性。

**前置阅读**：[AI 工具体系指南](/ai/product/ai-tooling-guide.md) — 理解 Built-in Tools / MCP / Skills / CLI 的分层模型和 Host/Client/Server 架构。

***

## 一、出发点：能不能在产品里嵌入 Claude Code？

读完 [AI 工具体系指南](/ai/product/ai-tooling-guide.md) 后，自然会想：

> "能不能在我们的产品里跑一个类似 Claude Code 的 Host，连上我们自己的 MCP Server（DynamoDB、Neon、RingCentral），自动拥有 tool-calling + MCP + context management 的全套能力？"

**方向对，但 Claude Code 本身不是正确的载体。**

::: details 为什么不嵌入 Claude Code（点击展开）

**Claude Code 不开源。** 它是 Anthropic 的商业产品（CLI 工具），代码不公开。

更重要的是，Claude Code 的 Built-in Tools 是给**程序员写代码**用的，不是给健身房老板用的：

| Claude Code 的 Built-in Tools  | retaintive 需要的 Tools               |
| ----------------------------- | ---------------------------------- |
| Read / Write / Edit — 编辑源代码文件 | `search_leads` — 按状态/温度查 PhoneBook |
| Grep / Glob — 搜索代码库           | `get_call_analysis` — 查通话 AI 分析结果  |
| LSP — 跳转定义、查引用                | `get_sms_thread` — 查 SMS 对话历史      |
| Bash — 跑 git、npm、aws cli      | `create_campaign` — 创建营销活动         |
| Task / Team — 多 agent 协作      | `diagnose_churn` — 流失诊断            |

Claude Code 的 Read/Write/Grep 对 gym owner 毫无用处。我们需要的是**健身房业务领域的 tools**。

**Anthropic Agent SDK**（TypeScript + Python）是开源的，但定位是给开发者做内部工具（SRE 机器人、代码审查、oncall 助手）。对客户产品来说，直接用 Claude API tool-calling 更简单、更可控。

## :::

## 二、我们实际拥有什么能力

Claude Code 里让人觉得"很厉害"的能力——tool-calling、多轮推理、自动选择工具——**不是 Claude Code 的能力，是 Claude API 的能力。** 直接调 API 就有。

Claude Code 的架构可以拆解为 6 层（参见 [AI 工具体系指南 §3.2](/ai/product/ai-tooling-guide.md#32-三层架构host--client--server)）。每一层我们都能自己实现：

| Claude Code 的层     | 做什么      | retaintive 的对应实现                        |
| ------------------ | -------- | --------------------------------------- |
| System Prompt      | 教 AI 怎么做 | 健身房领域 prompt（Skills 内容编译进来）             |
| Tool-calling       | AI 选工具执行 | 6 个业务 tools（见[§四](#roi-top-10)）         |
| Agentic Loop       | 多轮自动调用   | `while (stop_reason === "tool_use")` 循环 |
| MCP Client         | 连外部系统    | **不需要**。直接在代码里写 tool 函数更简单              |
| Context Management | 防止超长     | 对话历史裁剪                                  |
| Permission         | 人类确认     | 审批工作流（Campaign 发送前确认）                   |

核心 loop 代码只有 30 行：

```typescript
async function agenticChat(userMessage: string, tenantId: string) {
  const messages = [{ role: "user", content: userMessage }];

  let response = await anthropic.messages.create({
    model: "claude-opus-4-6",
    system: GYM_SYSTEM_PROMPT,  // Skills 内容编译进来
    tools: GYM_TOOLS,           // 业务 tools
    messages,
  });

  // Agentic loop: AI 自己决定调几次 tool
  while (response.stop_reason === "tool_use") {
    const toolCall = response.content.find(b => b.type === "tool_use");
    const result = await executeTool(toolCall.name, toolCall.input, tenantId);

    messages.push({ role: "assistant", content: response.content });
    messages.push({ role: "user", content: [{
      type: "tool_result", tool_use_id: toolCall.id, content: result
    }]});

    response = await anthropic.messages.create({
      model: "claude-opus-4-6",
      system: GYM_SYSTEM_PROMPT,
      tools: GYM_TOOLS,
      messages,
    });
  }

  return response.content.filter(b => b.type === "text");
}
```

这个 `while` 循环就是 Claude Code 的核心。AI 工具体系指南 [§3.7](/ai/product/ai-tooling-guide.md#37-一次-mcp-调用的完整流程) 描述的 7 步流程，在这段代码里全部体现。

***

## 三、正确的产品架构 \{#architecture}

不需要 MCP、不需要 Agent SDK、不需要嵌入 Claude Code。我们要的是在 Vue 前端加一个 AI Chat 面板，背后是 Hono API 调 Claude API。

```
┌─────────────────────────────────────────────────────────────┐
│  apps/web (Vue 3)                                            │
│  ├── Dashboard（已有）                                       │
│  ├── AI Chat Panel（新）← 老板在这里跟 AI 对话               │
│  └── Campaign Wizard（新）← AI 推荐 + 人工审批               │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP
┌──────────────────────▼──────────────────────────────────────┐
│  apps/api (Hono + Lambda)                                    │
│  ├── /api/ai/chat     ← 接收用户消息                         │
│  ├── agenticLoop()    ← while(tool_use) 循环                 │
│  ├── GYM_TOOLS:                                              │
│  │   ├── search_leads()        → DynamoDB PhoneBook          │
│  │   ├── get_call_analysis()   → DynamoDB call-analysis      │
│  │   ├── get_sms_thread()      → DynamoDB MessageStore       │
│  │   ├── query_metrics()       → Neon PostgreSQL             │
│  │   ├── create_task()         → DynamoDB Tasks              │
│  │   └── generate_campaign()   → 模板验证 + 返回预览          │
│  └── GYM_SYSTEM_PROMPT:                                      │
│      ← docs/skills/gym-domain/*.md 的内容编译进来             │
└─────────────────────────────────────────────────────────────┘
                       │
              Anthropic API (Claude Opus 4.6)
```

### 为什么不需要 MCP

MCP 是给"多个不同 AI client 连同一个 server"的场景设计的（参见 [AI 工具体系指南 §3.1](/ai/product/ai-tooling-guide.md#31-mcp-解决什么问题)）。我们的产品只有一个 AI backend（Hono API），直接在代码里写 tool 函数就行。

Tool-calling 本身就是结构化的（JSON schema）、安全的（tenant 隔离）、可扩展的。

### 为什么不需要 Agent SDK

我们的 agentic loop 就是一个 `while` 循环 + 6 个 tool 函数。Agent SDK 解决的是更复杂的场景（多 agent 编排、文件系统操作、长时间会话）。

### Skills 怎么用

不是给客户用的产品功能，而是**两用**：

1. **开发时** — Claude Code 加载 Skills，理解健身房业务逻辑
2. **生产环境** — Markdown 内容编译进 `GYM_SYSTEM_PROMPT`

```typescript
// 构建时把 Skill 内容注入 system prompt
import { readFileSync } from "fs";

const OBJECTION_SKILL = readFileSync(
  "docs/skills/gym-domain/objection-framework.md", "utf8"
);

const GYM_SYSTEM_PROMPT = `你是一个健身房销售和客户留存 AI 助手。

## 异议分类框架
${OBJECTION_SKILL}
`;
```

知识随代码库演进。更新 Markdown，所有 AI 分析自动使用新版本。

***

## 四、ROI 排序：TOP 10 集成机会 \{#roi-top-10}

知道了能力边界后，按 ROI 排优先级。

| 排名     | 集成项                              | ROI   | 难度 | 周期      | 技术方案                            |
| ------ | -------------------------------- | ----- | -- | ------- | ------------------------------- |
| **1**  | [AI 诊断对话](#w1-diagnose)          | ⭐⭐⭐⭐⭐ | 中  | 4-6 周   | Claude API tool-calling         |
| **2**  | [Dashboard 文字洞察](#w2-dashboard)  | ⭐⭐⭐⭐⭐ | 低  | 2-4 周   | Claude API + Neon SQL           |
| **3**  | [Campaign Engine](#w3-campaign)  | ⭐⭐⭐⭐⭐ | 高  | 8-12 周  | Orchestrator/Specialist 多 agent |
| **4**  | [Staff Coaching](#w4-coaching)   | ⭐⭐⭐⭐  | 中  | 4-6 周   | Per-Call AI 增强（已设计）             |
| **5**  | [内部 Skills](#w5-skills)          | ⭐⭐⭐⭐  | 低  | 1-2 周   | Markdown Skills 文件              |
| **6**  | [Churn 预测模型](#w6-churn)          | ⭐⭐⭐⭐  | 高  | 8-12 周  | ML 模型 + Claude 解读               |
| **7**  | [自动 Task 生成](#w7-task)           | ⭐⭐⭐   | 中  | 4-6 周   | Tool-calling + 模板验证             |
| **8**  | [MCP Server（合作伙伴）](#w8-mcp)      | ⭐⭐⭐   | 中  | 3-5 周   | Streamable HTTP MCP             |
| **9**  | [自动 SMS 发送](#w9-sms)             | ⭐⭐    | 很高 | 12-16 周 | 审批工作流 + TCPA 合规                 |
| **10** | [Agent SDK 内部工具](#w10-agent-sdk) | ⭐⭐    | 低  | 2-3 周   | TypeScript Agent SDK            |

***

## 五、详细 Workflow

### #1 AI 诊断对话 \{#w1-diagnose}

**ROI 最高，改变用户体验。**

老板在 Dashboard 点击一个 lead/member，问 "为什么这个人流失了？"。AI 自动拉取通话记录、SMS 历史、付款记录、到访频率，综合诊断原因并推荐行动。

```
老板点击 "Diagnose" 按钮
→ 前端发送 { member_id, question } 到 Hono API
→ API 调用 Claude Opus 4.6 + 4 个 tools:
    ├─ get_member_history (PhoneBook)
    ├─ get_call_analysis (call-analysis 表)
    ├─ get_sms_thread (MessageStore)
    └─ get_payment_history (外部/DDB)
→ Claude 自动选择需要的 tools，多轮调用
→ 返回结构化诊断: 根因 + 贡献因子 + 推荐行动
→ 前端展示卡片式结果
```

**为什么 ROI 最高：** 直接回答老板最核心的问题——"我的钱去哪了？"。目前老板要自己翻 3 个不同的页面去拼凑答案，AI 把这变成一次点击。

**技术选型：** Claude API tool-calling。不是 Bedrock Agents，不是 Agent SDK。

- 所有数据已在 DynamoDB + Neon
- 每次请求约 $0.003，成本极低
- 延迟 2-5 秒，可接受

**核心挑战：** 定义好 4-5 个 tools 的 JSON schema，做好 tenant 隔离（每个 query 必须带 `tenantId`）。

***

### #2 Dashboard 文字洞察 \{#w2-dashboard}

**最快见效。**

Dashboard 顶部加一段 AI 生成的文字总结：

> "本周转化率下降 5%，主要原因是周三的 3 个高意向 lead 爽约。建议：给这 3 人发 SMS 重新预约。"

```
Daily Batch Job (06:00 UTC，已设计好)
→ 查询 Neon: 关键指标 vs 上周/上月对比
→ Claude 生成 3-5 句自然语言总结
→ 存入 DDB summary 表
→ 前端 Dashboard 加载时显示
```

**为什么 ROI 高：** 实现最简单（2-4 周），但对老板感知价值巨大。从看数字变成看"AI 在说话"。这是 Level 1 Describe，也是产品从"工具"变成"顾问"的第一步。

**技术选型：** 复用已有的 Daily Batch 架构（AI 分析插入点设计 Layer 2），加一个 summary generation 步骤。

***

### #3 Campaign Engine \{#w3-campaign}

**最大的产品差异化。** 详见 [Campaign Engine 设计](../product-design/future-plans/campaign-engine.md)。

关键技术决策：**自研 tool-calling，不用 Bedrock Agent。**

| 维度   | Bedrock Agents         | Claude API Tool-Calling |
| ---- | ---------------------- | ----------------------- |
| 模型版本 | 落后 Anthropic API 2-4 周 | 始终最新                    |
| 复杂度  | IAM / VPC / Quota 配置   | API key + 代码            |
| 控制力  | Agent 框架控制循环           | 我们控制整个循环                |
| 适用场景 | 需要 VPC 隔离              | 客户产品（我们的场景）             |

Workflow 使用 Orchestrator/Specialist 模式：

```
老板: "给这个月到期的会员做个召回活动"

Campaign Orchestrator (Claude Opus 4.6)
├── 调用 tool: search_expiring_members → 找到 47 人
├── 调用 tool: analyze_churn_risk → 筛出 12 个高风险
├── 调用 tool: get_interaction_history → 了解每人情况
├── 生成个性化 SMS 文案（基于通话记录中的兴趣点）
├── 调用 tool: validate_campaign → 模板合规检查
└── 返回: 活动方案 + 12 条个性化 SMS 预览

老板审核 → 点击确认 → 批量发送
```

**竞品对标：** Keepme（健身房 AI）用 Random Forest 预测流失，准确率 95%。但 Keepme 是**事后预测**（predict churn），我们是**事中干预**（influence outcome during call + proactive outreach）。这是核心差异。

***

### #4 Staff Coaching \{#w4-coaching}

**已设计好，直接落地。**

Per-Call AI 分析出 coaching 建议，告诉 manager "这个员工在处理价格异议时错过了 3 个机会"。

已有能力：

- Deepgram 转录 ✅
- Bedrock AI 分析 ✅（AI 分析插入点设计 Layer 1）
- call-analysis 表 ✅

缺什么：结构化的 coaching 输出 schema（异议类型分类、评分、改进建议）。

Workflow：复用 Per-Call 管道，在 Prompt A 里增加 coaching 输出字段。

***

### #5 内部 Skills \{#w5-skills}

**投入最小，持续回报。**

不是客户产品功能，而是给团队用的领域知识库。

```
docs/skills/
├── gym-call-analysis/
│   ├── objection-framework.md    # 异议分类: 价格/时间/健身水平/承诺
│   ├── coaching-patterns.md      # 销售技巧模板
│   └── churn-risk-signals.md     # 流失信号定义
├── campaign-engine/
│   ├── campaign-templates.md     # 活动模板库
│   └── compliance-rules.md       # TCPA 合规规则
└── data-pipeline/
    └── troubleshooting.md        # 管道故障排查
```

双重用途：

1. **Claude Code 加载** — 开发时自动理解业务逻辑
2. **注入 system prompt** — 生产环境把 Markdown 内容嵌入 AI 的系统提示词（见[§三](#architecture)代码示例）

ROI：投入 1-2 周整理现有知识 → 永久提升所有 AI 分析的质量。

***

### #6 Churn 预测模型 \{#w6-churn}

**需要 ML 基础设施。**

Claude 不是统计预测器，它是推理引擎。需要**混合架构**：

```
ML 模型（RandomForest / XGBoost）
→ 每日 batch 对所有活跃会员评分
→ 输出: (member_id, churn_probability, top_3_factors)

Claude
→ 接收预测结果 + 会员历史
→ 生成自然语言解读 + 推荐行动
```

前提条件：2 年以上历史数据 + 模型训练。Neon PostgreSQL 可以存储特征数据，Lambda 跑 batch scoring。

***

### #7 自动 Task 生成 \{#w7-task}

AI 根据通话结果自动创建跟进任务。

```
Per-Call AI 分析完成
→ 判断: 需要跟进吗？什么类型？
→ 调用 tool: create_task
    ├─ lead_id
    ├─ employee_id
    ├─ task_type: "call" | "sms" | "appointment"
    ├─ description: "客户表达价格顾虑，建议 3 天内跟进提供分期方案"
    └─ due_date: 3 天后
→ Tasks 表写入
→ 员工端看到待办
```

关键：使用**模板验证**。AI 推荐的 task 必须匹配预定义模板，不允许自由发挥。

***

### #8 MCP Server \{#w8-mcp}

**面向生态，不面向终端用户。**

MCP 不是给 gym owner 用的。Gym owner 不会装 Claude Desktop。

正确定位：MCP Server 是面向**合作伙伴、顾问、集成商**的 AI-native API。

场景示例：

- 健身房顾问在 Claude.ai 里问 "Show me gym ABC's conversion funnel this month" → Claude 通过 MCP server 查询
- 竞品分析师用 AI 工具对比多家健身房数据

**现在值得做吗？** 不急。等有 10+ 合作伙伴客户再考虑。优先做 #1-#4。

***

### #9 自动 SMS 发送 \{#w9-sms}

Level 5 自动化。**暂不建议。**

| 风险   | 说明                           |
| ---- | ---------------------------- |
| 治理风险 | 100 条 SMS 未经审批 → 垃圾短信 + 品牌损害 |
| 合规风险 | TCPA（美国电话营销法）要求可追溯的决策依据      |
| 无回滚  | SMS 发出去就收不回来                 |

前提条件：实时监控、Kill-switch（5 秒内暂停）、审计日志、A/B 测试框架、法律审查。

过渡方案（Level 4.5）：AI 生成推荐 → 批量审批 → 人工确认后执行。

***

### #10 Agent SDK 内部工具 \{#w10-agent-sdk}

用 Claude Agent SDK（TypeScript）给团队做内部辅助工具。

适用场景：

- 数据管道故障诊断
- 跨仓库代码影响分析
- 自动化 on-call runbook

不适用于客户产品。优先级低。

***

## 六、5 级自动化金字塔

| Level            | 能力               | 现在能做？    | 前提条件                  | 定价参考         |
| ---------------- | ---------------- | -------- | --------------------- | ------------ |
| **L1 Describe**  | AI 文字总结、趋势描述     | ✅ 今天就能   | Neon SQL + Claude API | $50-100/月    |
| **L2 Diagnose**  | 根因分析、异常诊断        | ✅ 今天就能   | Tool-calling + 多表查询   | $150-250/月   |
| **L3 Predict**   | 流失预测、转化预测        | ⚠️ 需要 ML | 2 年历史数据 + 模型训练        | $300-500/月   |
| **L4 Recommend** | AI 推荐行动方案        | ✅ 今天就能   | 模板验证 + 审批工作流          | $500-800/月   |
| **L5 Execute**   | 自动发 SMS、自动建 Task | ❌ 暂不建议   | TCPA 合规 + 监控 + 回滚     | $800-1000+/月 |

不需要按顺序走。可以跳过 L3 先做 L4（用规则代替预测模型）。

详见 [产品本质 / North Star](/product-design/north-star.md) 与五层能力金字塔(L1 Describe → L5 Execute)。

***

## 七、关键技术决策

| 决策                          | 推荐                             | 原因                              |
| --------------------------- | ------------------------------ | ------------------------------- |
| Bedrock Agent vs Claude API | **Claude API**                 | 更简单、模型更新、不需要 VPC 隔离             |
| Agent SDK vs Tool-calling   | **Tool-calling**               | Agent SDK 是给开发工具用的，不是客户产品       |
| MCP vs REST API             | **先 REST**                     | 客户是 gym owner 不是开发者             |
| 单 agent vs 多 agent          | **单 agent + 多 tools**          | 先简单做，Campaign Engine 再升级多 agent |
| Skills 嵌入方式                 | **Markdown → System Prompt**   | 最务实，团队 + 生产环境双重受益               |
| 模型选择                        | **Opus 4.6 推理 + Haiku 4.5 分类** | Opus 做复杂诊断，Haiku 做简单标签（成本低 10x） |

***

## 八、推荐执行顺序

```
Phase 1 (当前 → 4 周):   L1 Dashboard 洞察 + 内部 Skills 整理
Phase 2 (4-10 周):       L2 AI 诊断对话 + Staff Coaching 增强
Phase 3 (10-20 周):      L4 Campaign Engine MVP (AI 推荐 + 人工审批)
Phase 4 (20-32 周):      L3 Churn 预测模型 + L4.5 半自动执行
Phase 5 (32 周+):        L5 全自动化 + MCP 生态开放
```

### 成本估算

| Phase   | 核心工作                    | 团队               | 估算成本   |
| ------- | ----------------------- | ---------------- | ------ |
| Phase 1 | Dashboard 文字洞察 + Skills | 1 后端，4 周         | \~$5K  |
| Phase 2 | AI 诊断对话 + Coaching      | 1 后端 + 1 QA，6 周  | \~$15K |
| Phase 3 | Campaign Engine MVP     | 1 后端 + 1 前端，10 周 | \~$30K |
| Phase 4 | Churn 预测 + 半自动化         | + 1 数据科学家        | \~$40K |
| Phase 5 | 全自动化 + MCP              | + 法律顾问           | \~$50K |

Claude API 使用成本：每月约 500K-2M tokens，$15-60/月。在总成本中可忽略。

***

## 附录：竞品 AI 能力对标

::: details 健身房 AI 竞品（点击展开）

**Keepme**（健身房 AI 留存）

- Keepme Score：Random Forest 算法，100 万+ 决策树，流失预测准确率 95%
- 追踪指标：到访频率、课程多样性、续费行为、会员互动
- 自动化：对分群后的高风险会员自动触达

**retaintive vs Keepme**：

| 维度   | Keepme           | retaintive                |
| ---- | ---------------- | ------------------------- |
| 数据信号 | 到访 + 行为          | 通话 + SMS + 到访 + 跟进        |
| 分析时机 | 事后预测（churn risk） | 事中干预（通话中 coaching + 主动触达） |
| 行动方式 | 自动邮件/SMS         | AI 推荐 + 人工审批 + 个性化文案      |

**通话中心 AI Coaching 竞品**

| 产品       | 能力                               |
| -------- | -------------------------------- |
| AmplifAI | 语音 + 情感分析 + 自动 QA + coaching 工作流 |
| Convin   | 对话智能 → 模式检测 → 自动 coaching 建议     |
| Level AI | 实时情感 + 合规检查 + coaching           |

这些产品验证了 AI coaching 的市场需求。retaintive 的差异在于垂直行业（健身房）+ 全链路数据（通话 + Lead + SMS + 到访）。
:::