customer-success-manager

监控 SaaS 客户健康、预测流失风险并识别扩展机会，使用加权评分模型。适用于分析客户账户、审查留存指标、评分风险客户，或用户提及流失、客户健康分、增购机会、扩展收入、留存分析或客户分析时。运行三个 Python CLI 工具，为企业、中端市场和 SMB 分群生成确定性健康分、流失风险等级和优先级扩展建议。

## 概述（中文）

监控 SaaS 客户健康、预测流失风险并识别扩展机会，使用加权评分模型。适用于分析客户账户、审查留存指标、评分风险客户，或用户提及流失、客户健康分、增购机会、扩展收入、留存分析或客户分析时。运行三个 Python CLI 工具，为企业、中端市场和 SMB 分群生成确定性健康分、流失风险等级和优先级扩展建议。

## 技能正文

# 客户成功经理

生产级客户成功分析，支持多维度健康评分、流失风险预测和扩展机会识别。三个 Python CLI 工具提供确定性、可重复的分析，仅使用标准库——无外部依赖、无 API 调用、无 ML 模型。

---

## 目录

- [输入要求](#输入要求)
- [输出格式](#输出格式)
- [使用方法](#使用方法)
- [脚本](#脚本)
- [参考指南](#参考指南)
- [模板](#模板)
- [最佳实践](#最佳实践)
- [限制](#限制)

---

## 输入要求

所有脚本接受 JSON 文件作为位置参数输入。完整模式示例见 `assets/sample_customer_data.json`。

### 健康评分计算器

每个客户对象必填字段：`customer_id`、`name`、`segment`、`arr`，以及嵌套对象 `usage`（login_frequency、feature_adoption、dau_mau_ratio）、`engagement`（support_ticket_volume、meeting_attendance、nps_score、csat_score）、`support`（open_tickets、escalation_rate、avg_resolution_hours）、`relationship`（executive_sponsor_engagement、multi_threading_depth、renewal_sentiment），以及 `previous_period` 分数用于趋势分析。

### 流失风险分析器

每个客户对象必填字段：`customer_id`、`name`、`segment`、`arr`、`contract_end_date`，以及嵌套对象 `usage_decline`、`engagement_drop`、`support_issues`、`relationship_signals`、`commercial_factors`。

### 扩展机会评分器

每个客户对象必填字段：`customer_id`、`name`、`segment`、`arr`，以及嵌套对象 `contract`（licensed_seats、active_seats、plan_tier、available_tiers）、`product_usage`（各模块采用标志和使用百分比）、`departments`（当前和潜在）。

---

## 输出格式

所有脚本通过 `--format` 标志支持两种输出格式：

- **`text`**（默认）：人类可读的格式化输出，用于终端查看
- **`json`**：机器可读的 JSON 输出，用于集成和流水线

---

## 使用方法

### 快速开始

```bash
# 健康评分
python scripts/health_score_calculator.py assets/sample_customer_data.json
python scripts/health_score_calculator.py assets/sample_customer_data.json --format json

# 流失风险分析
python scripts/churn_risk_analyzer.py assets/sample_customer_data.json
python scripts/churn_risk_analyzer.py assets/sample_customer_data.json --format json

# 扩展机会评分
python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json
python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json --format json
```

### 工作流集成

```bash
# 1. 对整个客户组合进行健康评分
python scripts/health_score_calculator.py customer_portfolio.json --format json > health_results.json
# 验证：确认 health_results.json 包含预期数量的客户记录后再继续

# 2. 识别风险账户
python scripts/churn_risk_analyzer.py customer_portfolio.json --format json > risk_results.json
# 验证：确认 risk_results.json 非空且每位客户都有风险等级

# 3. 在健康账户中寻找扩展机会
python scripts/expansion_opportunity_scorer.py customer_portfolio.json --format json > expansion_results.json
# 验证：确认 expansion_results.json 按优先级列出机会

# 4. 使用模板准备 QBR
# 参考：assets/qbr_template.md
```

**错误处理：** 若脚本以错误退出，请检查：
- 输入 JSON 是否符合该脚本的必填模式（见上方输入要求）
- 所有必填字段是否存在且类型正确
- 是否使用 Python 3.7+（`python --version`）
- 后续步骤前，上一步输出文件非空

---

## 脚本

### 1. health_score_calculator.py

**用途：** 多维度客户健康评分，含趋势分析和分群基准对比。

**维度与权重：**
| 维度 | 权重 | 指标 |
|------|------|------|
| 使用 | 30% | 登录频率、功能采用、DAU/MAU 比率 |
| 参与 | 25% | 支持工单量、会议出席、NPS/CSAT |
| 支持 | 20% | 未结工单、升级率、平均解决时间 |
| 关系 | 25% | 高管赞助人参与、多线程深度、续约情绪 |

**分类：**
- 绿色（75-100）：健康——客户正在获得价值
- 黄色（50-74）：需关注——密切监控
- 红色（0-49）：有风险——需立即干预

**用法：**
```bash
python scripts/health_score_calculator.py customer_data.json
python scripts/health_score_calculator.py customer_data.json --format json
```

### 2. churn_risk_analyzer.py

**用途：** 识别风险账户，进行行为信号检测和分级干预建议。

**风险信号权重：**
| 信号类别 | 权重 | 指标 |
|----------|------|------|
| 使用下降 | 30% | 登录趋势、功能采用变化、DAU/MAU 变化 |
| 参与下降 | 25% | 会议取消、响应时间、NPS 变化 |
| 支持问题 | 20% | 未解决升级、未解决关键问题、满意度趋势 |
| 关系信号 | 15% | 拥护者离职、赞助人变更、竞品提及 |
| 商业因素 | 10% | 合同类型、价格投诉、预算削减 |

**风险等级：**
- 严重（80-100）：立即高管升级
- 高（60-79）：紧急 CSM 干预
- 中（40-59）：主动外联
- 低（0-39）：标准监控

**用法：**
```bash
python scripts/churn_risk_analyzer.py customer_data.json
python scripts/churn_risk_analyzer.py customer_data.json --format json
```

### 3. expansion_opportunity_scorer.py

**用途：** 识别增购、交叉销售和扩展机会，含收入估算和优先级排序。

**扩展类型：**
- **增购（Upsell）**：升级到更高层级或增加现有产品用量
- **交叉销售（Cross-sell）**：添加新产品模块
- **扩展（Expansion）**：增加席位或部门

**用法：**
```bash
python scripts/expansion_opportunity_scorer.py customer_data.json
python scripts/expansion_opportunity_scorer.py customer_data.json --format json
```

---

## 参考指南

| 参考 | 说明 |
|------|------|
| `references/health-scoring-framework.md` | 完整健康评分方法论、维度定义、权重依据、阈值校准 |
| `references/cs-playbooks.md` | 各风险等级干预手册、入职、续约、扩展和升级流程 |
| `references/cs-metrics-benchmarks.md` | NRR、GRR、流失率、健康分、扩展率等行业基准（按分群和行业）|

---

## 模板

| 模板 | 用途 |
|------|------|
| `assets/qbr_template.md` | 季度业务回顾（QBR）演示结构 |
| `assets/success_plan_template.md` | 客户成功计划（目标、里程碑、指标）|
| `assets/onboarding_checklist_template.md` | 90 天入职清单（含阶段关卡）|
| `assets/executive_business_review_template.md` | 战略账户高管利益相关方回顾 |

---

## 最佳实践

1. **综合信号**：三个脚本一起使用，获得完整客户画像
2. **关注趋势而非快照**：下降的绿灯比稳定的黄灯更紧急
3. **校准阈值**：根据产品和行业调整分群基准（见 `references/health-scoring-framework.md`）
4. **数据先行**：每次 QBR 和高管会议前运行脚本；干预指导参考 `references/cs-playbooks.md`

---

## 限制

- **非实时数据**：脚本分析 JSON 输入文件的时点快照
- **无 CRM 集成**：需从 CRM/CS 平台手动导出数据
- **仅确定性**：无预测性 ML——评分基于加权信号的算法
- **阈值调优**：默认阈值为行业标准，可能需要针对业务校准
- **收入估算**：扩展收入估算基于使用模式的近似值

---

**最后更新：** 2026 年 2 月
**工具：** 3 个 Python CLI 工具
**依赖：** 仅 Python 3.7+ 标准库