lapsewatch

lapsewatch：找出停止购买的客户

基于订单 CSV 进行客户留存和流失分析：了解哪些客户面临流失风险、哪些客户已经流失，以及有多少年度收入岌岌可危。适用于电商商店、服务型企业和小型 B2B 公司。

留住客户通常比开发新客户成本更低，但没人会注意到一位老客户悄然停止下单。lapsewatch 会将每位客户的订单情况与其自身的购买规律进行比较，因此每月下单的客户会比每年只下单两次的客户更早被标记。它是一个 MCP 服务，也是一个独立的 Go 二进制文件，无需账户、API 密钥，也无需网络访问。

可以向你的 Agent 提问

• “哪些客户已经停止购买？”
• “我应该先联系谁来挽回收入？”
• “有多少年度收入面临风险？”
• “我的回头客比例是多少？我对头部客户的依赖程度有多高？”

安装

作为 Claude Code 插件安装，它会添加 MCP 服务和一个用于告知 Claude 何时使用该服务的技能。你需要安装 Node，通过 npx 运行服务：

claude plugin marketplace add GillMacedo/lapsewatch
claude plugin install lapsewatch@lapsewatch-marketplace

对于其他 MCP 客户端：

{
  "mcpServers": {
    "lapsewatch": {
      "command": "npx",
      "args": ["-y", "lapsewatch", "serve"]
    }
  }
}

或者使用 Go 1.27 或更高版本构建二进制文件：

go install github.com/GillMacedo/lapsewatch@latest

用法

无需安装任何内容即可运行 npx lapsewatch check orders.csv。此示例使用 examples/ 中的虚构文件：

$ go run . check examples/orders.csv
截至 2026-09-27：8 位客户，75.0% 的客户购买过不止一次，收入 14598.00，前 10% 的客户贡献了 49.3%
有风险：优先联系以下客户（2 位）
  [email protected]  距上次下单 197 天，通常每 60 天下单一次  年价值 5475.00
  [email protected]  距上次下单 92 天，通常每 30 天下单一次  年价值 3771.67
已流失（1 位）
  [email protected]  距上次下单 297 天，通常每 20 天下单一次  年价值 1368.75
一次性客户（1 位）
  [email protected]  唯一下单距今 397 天  消费 60.00
3 位活跃客户，1 位新客户。
已跳过第 68 行：日期、客户或金额无效
2 位客户带来每年 9246.67 的风险收入。

添加 --as-of 2026-12-31 可按指定日期进行衡量，添加 --top 50 可列出更多客户，添加 --json 可生成机器可读的输出。

判定方式

状态	规则
活跃	最近下单时间在其通常间隔的两倍以内
有风险	超过其通常间隔的两倍，且距上次下单至少 30 天
已流失	超过其通常间隔的四倍，且距上次下单至少 30 天
新客户	最近 90 天内下单一次
一次性客户	下单一次，且距今已超过 90 天

通常间隔是客户各笔订单之间天数的中位数。年价值按平均订单金额乘以 365 再除以该间隔计算，因此只是估算值。同一天的多行记录算作一笔订单，退款会减少总额，但不计作订单。

MCP 工具

工具	功能
customers_check_lapsed	返回摘要和按优先级排列的客户列表，可为大型文件设置条目上限
customers_inspect_csv	显示检测到的列和行数，不显示行内容

这两个工具均为只读，且都无法联系任何人。customers_check_lapsed 会将客户姓名或邮箱返回给 MCP 客户端，因此这些信息会发送给你使用的 AI 模型。CLI 会将所有内容保留在你的设备上。

常见问题

如何查找不活跃的客户？ 将订单导出为 CSV，然后运行 npx lapsewatch check orders.csv。

它适用于 Shopify、WooCommerce 或 Stripe 导出文件吗？ 它会读取 CSV，并识别 Email、Total 和 Created at 等常见列名；你也可以通过 --columns date=When,customer=Who,amount=Sum 指定其他列名。它不会连接这些平台，目前也尚未使用各平台的真实导出文件进行测试。

应该使用姓名还是电子邮件？ 电子邮件效果最好，因为它会将每个不同的值视为一位客户。

限制

• 它能找出需要关注的客户，但无法判断客户停止购买的原因。一次性需求或季节性买家也可能被视为流失客户。
• 同一位客户使用两个姓名或电子邮件时，会被算作两位客户。samecontact 可以帮助你先清理名单。
• 它不会转换货币。
• 它只读取 CSV，文件大小上限为 50 MB。
• 如果你要给这些名单中的客户发送电子邮件，请遵守当地的营销和隐私法规。
• 目前只用虚构数据进行了测试，没有使用真实导出文件。如果你的文件无法处理，请提交 issue，并附上列标题，而不是数据。

参与贡献

欢迎个人和使用 AI Agent 的贡献者参与贡献。请参阅 CONTRIBUTING.md。适合新手的 issue：

• 添加更多平台和语言的列名
• 添加 --out，将挽回客户名单写入 CSV
• 添加季节性买家检测
• 添加群组留存率表
• 添加插件图标

Pull request 的处理流程

1. 提交 PR。 Fork 仓库，在分支上进行开发，并确保每个 PR 只包含一项更改。标题要说明用户会看到什么变化，因为标题会成为变更日志中的条目：feat: 归入 Added，fix: 归入 Fixed。
2. 自动检查。 代码更改必须包含测试，并且 make test 必须通过。超过 30 行的更改必须关联一个已打开的 issue（Closes #<number>），且 PR 的更改行数不得超过 800 行。如果缺少内容，系统会通过评论告知你需要修复什么。
3. 审核。 Claude 会自动审核每个 PR。代码 PR 还会经过安全审核，并在沙盒中测试。之后，审核流程会合并 PR 或要求进行更改。更改 CI、Agent 设置、npm 或 Python 依赖、vendored 代码或构建文件的 PR 无法通过此流程合并，系统会在评论中说明。安全审核未通过的更改也一样。
4. 发布。 影响用户安装内容的合并更改会在约两小时内发布为新版本，并附带 GitHub Release；如果项目有 npm 包，也会一并发布。文档和 CI 更改会等到下次发布。

AI 使用说明

本项目主要由 Claude Code 生成，并由项目维护者审核。

关于我

我是 Giulliano Macedo，在 GoTech Solutions 构建开发者工具。欢迎关注我或与我联系：

• GitHub：GillMacedo
• LinkedIn：giulliano
• X：@giumacedo

如果 lapsewatch 帮你挽回了一位客户，点个星标可以帮助其他人找到它。

---

采用 MIT 许可。

由 Giulliano Macedo、GoTech Solutions 构建 · LinkedIn · X