retentioneering-tools · 协议与工具集成

Retentioneering Logo

Retentioneering 是一款开源 Python 工具包、MCP 服务器和 Agent Skills 集合，专为点击流数据和用户行为日志的可复现产品分析而设计。它帮助数据分析师、产品经理和 AI Agent 对用户路径、客户旅程、行为分群进行系统性探索，支持 A/B 测试评估和马尔可夫链模拟，让产品决策从凭直觉拍脑袋升级为有数据支撑的科学分析。

从一个真实痛点说起

想象你是一家电商公司的产品经理。某天老板问：为什么这个月下单转化率下降了3个百分点？你打开 Google Analytics，看到流量没变、跳出率没变——但就是不知道用户到底在哪里流失。传统的漏斗分析只能告诉你首页到支付这条主路径，而真实用户的路径远比这复杂：有人反复在支付页犹豫然后退出、有人把商品加了十次购物车最后却一个都没买、有人在 App 和网页之间来回切换……这些灰色地带的隐藏行为，传统工具根本抓不住。

Retentioneering 正是为解决这个痛点而生。 它从原始用户行为事件序列出发，用图论和统计学方法还原真实的用户旅程，告诉你转化路径上除了主路之外的岔路口、死循环和被忽视的高价值分支。

背景：产品分析领域的三代演进

产品分析工具经历了三个阶段：

第一代：页面级统计工具（Google Analytics、百度统计）。以页面 PV/UV 为核心指标，只能看多少人访问了某个页面，无法追踪跨页面的用户连续行为，分析深度极为有限。

第二代：漏斗分析工具（Mixpanel、Amplitude）。支持定义转化漏斗，追踪用户是否依次完成了预设的事件序列。但漏斗是预设的，只能看主路径，真实世界中大量用户走的是歪门邪道，这些偏离路径的行为被完全忽略。

第三代：用户路径分析工具（Retentioneering、Heap）。以用户完整行为序列为分析单元，不仅能还原用户实际走过的路径，还能进行分群对比、行为聚类、模拟干预。Retentioneering 正是第三代工具中的代表——它的核心理念是用户不是漏斗的被动参与者，而是有自主路径的决策者。

Retentioneering 起源于 2018 年左右的俄罗斯电商分析实践，团队在处理海量用户行为数据时发现传统工具无法回答用户在真实旅程中为什么会在这里流失这类问题，于是开发了这套工具。经过多年迭代，2024 年底发布的 v5.0 是一次彻底的重写：底层引擎从 pandas 迁移到 DuckDB（查询速度提升数十倍），前端从 CDN 加载的闭源 widgets 迁移到开源 anywidget 框架，并新增了 MCP 服务器支持，使 AI Agent 能够直接调用分析能力。

核心功能：从数据到洞察的四步工作流

Step 1：加载数据 — Eventstream 数据模型

用户只需准备一个包含三列的 DataFrame：用户 ID、事件名称、时间戳（不同列名可通过 schema 参数映射）。Retentioneering 会将其封装为一个 Eventstream 对象，后续所有分析都基于这个对象展开。数据来源可以是 CSV、Parquet、BigQuery 导出，或者任何 pandas DataFrame。

import pandas as pd
import retentioneering as rete

# 加载事件数据（user_id, event, timestamp）
df = pd.read_csv('events.csv')
stream = rete.Eventstream(df)

Step 2：数据清洗 — 链式数据处理器

原始点击流数据往往充满噪声：机器人请求、测试事件、不一致的命名等。Retentioneering 提供了一整套链式数据处理器（Data Processors），每个处理器返回一个全新的 Eventstream（原始数据永远不被修改），可以像 pandas 管道一样链式调用：

clean = (
    stream
    .filter_events(drop={'event': ['bot_ping', 'test_click']})  # 过滤机器人事件
    .collapse_events(consecutive=True)  # 合并连续重复事件
    .split_sessions(timeout='30m')  # 按30分钟超时切分会话
)

这些处理器覆盖了事件过滤、会话切分、路径折叠、合成事件注入（如流失标记）、URL 解析、日常生命周期状态映射等完整预处理流程。

Step 3：交互式可视化 — 六大分析 Widgets

清洗后的数据送入可视化分析模块。Retentioneering v5 提供了六个核心交互式 widgets，均基于开源 anywidget 框架开发，可以在 Jupyter、VS Code、Cursor、Google Colab 等任何 Python 环境中直接渲染：

Widget	功能	典型场景
Transition Graph	用户行为有向图，展示事件间的跳转概率	发现高频路径、死循环、异常分支
Step Matrix	每步转化矩阵，横向是事件步序，纵向是行为特征	精确定位流失最严重的步骤
Step Sankey	桑基图，横向展示用户流量在不同节点的分叉与汇合	直观展示从入口到转化的流量分布
Funnel	漏斗图，对比预设漏斗与实际路径的差异	评估预设转化路径的合理性
Segment Overview	行为分群概览，识别数据中的自然用户群体	发现未知的用户细分市场
Cluster Analysis	行为聚类分析，将用户按路径特征分组	精细化运营不同用户群

每个 widget 都支持 Diff 模式：叠加两个用户群体（如同比移动端 vs PC 端、本月 vs 上月、实验组 vs 对照组）在同一张图上，直观对比行为差异，而非仅看指标数字。

Step 4：可复现输出 — 报告与导出

分析完成后，可以导出为独立的 HTML 报告，包含所有图表和计算数据，可在团队内外部分享，无需安装 Python 环境或 Retentioneering。报告具有完整的可复现性——同一份原始数据，运行相同代码必然得到相同结果，满足审计和合规需求。

MCP 服务器：让 AI Agent 也能做数据分析

v5.0 最重要的新特性是内置的 MCP 服务器（基于 Anthropic 的 Model Context Protocol）。MCP 是一种标准化协议，让 AI 助手能够调用工具而非仅仅生成文本。Retentioneering 的 MCP 服务器将整套分析能力暴露为 AI 可调用的工具函数，AI Agent 可以在对话中直接对用户的点击流数据执行分析。

举例来说，一个 AI Agent 收到用户的请求——分析我们的用户流失原因——它可以调用 Retentioneering MCP 的工具，先加载数据、过滤会话、分析 transition graph，最后生成一份结构化报告。整个过程无需人工干预，用户也不需要懂 Python。

配合 Agent Skills（.agents/skills/ 目录下），Retentioneering 还提供了一套 prompt 模板，帮助 AI Agent 理解数据分析的最佳实践，降低生成错误分析结论的风险——这是 MCP 生态在数据分析领域的首个成熟落地案例。

技术架构：DuckDB 驱动的极速查询

v5.0 的底层引擎从 pandas 迁移到了 DuckDB，这是一个专为 OLAP 场景优化的嵌入式分析型数据库。相比 pandas，DuckDB 在处理百万级事件数据的聚合、分组、窗口函数时性能提升可达 10-100 倍，且内存占用更低。这意味着在真实规模的电商数据上，用户无需等待数分钟的计算，可以在秒级获得分析结果。

前端可视化基于 anywidget（开源），彻底摆脱了旧版本依赖 CDN 加载闭源 JS 组件的限制，任何人都可以审查和参与 widgets 的前端开发。

部署与安装：三分钟上手

Retentioneering 是一个纯 Python 库，通过 pip 一键安装：

pip install retentioneering

安装要求：Python 3.11+，无 GPU 需求，无外部服务依赖，完整数据分析流程在本地运行。数据分析结果不会上传到任何远程服务器（可选的匿名使用统计遥测可随时关闭）。从 pip 安装到跑出第一个 Transition Graph，熟练用户通常只需要 3 分钟。

需要注意的是，Retentioneering 没有 Docker 化部署，也不提供 web 服务界面——它是一个数据科学家和分析人员的本地分析工具包，不适合作为 SaaS 平台直接对外提供服务。

局限与争议：不完美的那些面

1. 学习曲线不可忽视。 虽然官方说不需要成为 Python 专家，但实际使用中，面对数据格式不规则、事件命名混乱、路径结构复杂的数据集时，用户仍需要理解 Eventstream 的概念模型和数据处理器的链式调用逻辑，这对完全不懂编程的产品经理来说仍有门槛。

2. v5 重写存在迁移成本。 v5.0 是一次从底层到前端的彻底重构，与 3.x 版本存在不兼容。已有 3.x 代码的用户需要进行迁移，虽然 3.x 引擎在 3.x 分支保留了维护，但两套代码并行增加了维护负担。

3. 大规模企业场景的局限。 Retentioneering 主要面向中等规模（百万到千万级事件）的单次分析场景。对于 PB 级实时流数据、需要多租户隔离的企业级分析平台，需要搭配外部数据仓库使用，此时 Retentioneering 只承担分析层而非存储层。

4. 无传统 Web UI。 与 Amplitude、Mixpanel 等商业工具不同，Retentioneering 没有图形化拖拽界面，所有操作通过 Python 代码完成，对非技术人员不够友好。

行业意义：开源力量正在重塑产品分析

Retentioneering 907 个 GitHub stars 的背后，是一个正在快速增长的开源产品分析细分赛道。传统商业产品分析工具（如 Amplitude、Mixpanel）以订阅制 SaaS 为主，数据上传到厂商服务器——这对于金融、医疗、政府等数据敏感行业是不可接受的合规风险。Retentioneering 的纯本地化架构填补了这一空白：数据不离开企业防火墙，满足 GDPR、数据主权等合规要求。

v5.0 引入 MCP 服务器是一个标志性事件：它意味着 AI Agent 不再只能谈论数据分析，而是能够真正执行数据分析。这种 AI 原生的分析工作流可能代表着产品分析工具的下一个演进方向——从人找数据，变成数据主动找人（通过 AI Agent）。

如果你正在寻找： 一款能够深入用户行为路径、发现隐藏流失点、进行行为分群对比，同时满足数据隐私合规要求的产品分析工具，Retentioneering 值得关注。

项目主页： https://retentioneering.com/docs/ GitHub： https://github.com/retentioneering/retentioneering-tools 许可证： Apache-2.0

Retentioneering Logo

从一个真实痛点说起

背景：产品分析领域的三代演进

产品分析工具经历了三个阶段：

核心功能：从数据到洞察的四步工作流

Step 1：加载数据 — Eventstream 数据模型

import pandas as pd
import retentioneering as rete

# 加载事件数据（user_id, event, timestamp）
df = pd.read_csv('events.csv')
stream = rete.Eventstream(df)

Step 2：数据清洗 — 链式数据处理器

clean = (
    stream
    .filter_events(drop={'event': ['bot_ping', 'test_click']})  # 过滤机器人事件
    .collapse_events(consecutive=True)  # 合并连续重复事件
    .split_sessions(timeout='30m')  # 按30分钟超时切分会话
)

这些处理器覆盖了事件过滤、会话切分、路径折叠、合成事件注入（如流失标记）、URL 解析、日常生命周期状态映射等完整预处理流程。

Step 3：交互式可视化 — 六大分析 Widgets

Widget	功能	典型场景
Transition Graph	用户行为有向图，展示事件间的跳转概率	发现高频路径、死循环、异常分支
Step Matrix	每步转化矩阵，横向是事件步序，纵向是行为特征	精确定位流失最严重的步骤
Step Sankey	桑基图，横向展示用户流量在不同节点的分叉与汇合	直观展示从入口到转化的流量分布
Funnel	漏斗图，对比预设漏斗与实际路径的差异	评估预设转化路径的合理性
Segment Overview	行为分群概览，识别数据中的自然用户群体	发现未知的用户细分市场
Cluster Analysis	行为聚类分析，将用户按路径特征分组	精细化运营不同用户群

Step 4：可复现输出 — 报告与导出

MCP 服务器：让 AI Agent 也能做数据分析

技术架构：DuckDB 驱动的极速查询

前端可视化基于 anywidget（开源），彻底摆脱了旧版本依赖 CDN 加载闭源 JS 组件的限制，任何人都可以审查和参与 widgets 的前端开发。

部署与安装：三分钟上手

Retentioneering 是一个纯 Python 库，通过 pip 一键安装：

pip install retentioneering

局限与争议：不完美的那些面

4. 无传统 Web UI。 与 Amplitude、Mixpanel 等商业工具不同，Retentioneering 没有图形化拖拽界面，所有操作通过 Python 代码完成，对非技术人员不够友好。

行业意义：开源力量正在重塑产品分析

项目主页： https://retentioneering.com/docs/ GitHub： https://github.com/retentioneering/retentioneering-tools 许可证： Apache-2.0