# PPXC Leads MCP

把 PPXC「从评论区发现高意向客户」的能力，做成智能体可直接调用的 MCP 工具包。

发布包：<https://www.npmjs.com/package/ppxc-leads-mcp>  
官网接入页：<https://opc1.me/download/mcp>  
公开仓库：<https://github.com/yuanjian068yuan/ppxc-leads-mcp>

> **先读这两份，再动手：**
> 1. [`AGENTS.md`](./AGENTS.md) — 本仓库的硬性边界规则（AI 协作员必读第一文件）
> 2. [`docs/开发手册.md`](./docs/开发手册.md) — 架构、工具契约、平台适配层、验收标准
>
> 产品化（从本地半成品到正式可分发小组件）的路线：[`docs/产品化规划-2026-06-11.md`](./docs/产品化规划-2026-06-11.md)

## 安装（一行配置）

在支持 MCP 的智能体（Claude 桌面版 / Cursor / 其他）配置里加一段：

```json
{
  "mcpServers": {
    "ppxc-leads": {
      "command": "npx",
      "args": ["-y", "ppxc-leads-mcp"]
    }
  }
}
```

- 首次使用会自动下载运行环境（约 100MB）。如果下载失败，换网络重试；国内网络可在 `env` 里额外加 `ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/`。
- 默认连 PPXC 生产站；开发联调时在 `env` 里加 `PPXC_API_BASE` 指向本地后端。
- 装好后对智能体说「检查登录状态」，按提示完成 PPXC 登录和平台扫码即可使用。

Windows 宿主如果不能直接执行 `npx`，用：

```json
{
  "mcpServers": {
    "ppxc-leads": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "ppxc-leads-mcp"]
    }
  }
}
```

## 一句话定位

用户在智能体里一行配置装好本工具包；首次登录 PPXC 账号 + 按需扫各平台二维码；之后对智能体说「分析这条内容 / 用这个词在小红书找客户」，工具包用自带的隐藏浏览器内核抓取数据、送 PPXC 后端分析，把「总体判断 + 高意向客户 + 跟进话术 + 内容选题」直接返回给智能体。

## 支持的平台

| 平台 | 链接分析评论 | 关键词搜索 | 数据获取方式 |
|---|---|---|---|
| 抖音 | ✅ | ✅ | 页内 fetch + 搜索 sniffer（已真机验证） |
| 小红书 | ✅ 真机验证通过（2026-06-11） | ✅ 真机验证通过（2026-06-11） | CDP 监听 + 滚动；笔记页需带 xsec_token 签名链接 |
| 快手 | ✅ 真机验证通过（2026-06-11） | ✅ 真机验证通过（2026-06-11） | CDP 监听 graphql（rootCommentsV2）；搜索走 /rest/v/search/feed |

## 它不是什么

- **不是**桌面客户端：没有产品界面，唯一允许出现的窗口是登录窗和验证码窗
- **不是**浏览器插件：不依赖用户手动安装插件
- **不是**爬虫平台：借用户本人登录态、保守频率、撞验证就请真人处理，不做任何过验证 / 共享账号的灰色手段

## 隐私与安全

- 平台登录态和 PPXC 登录凭证只保存在用户本机。
- 不上传平台 token / Cookie，不把它们写进日志或诊断包。
- 评论文本会通过 HTTPS 发送到 PPXC 后端做 AI 意向判断和话术生成。
- 分析出的客户结果会写入用户自己的 PPXC 客户池。
- 遇到验证码或平台安全验证时，组件只会弹出窗口让用户本人处理，不做自动绕过。

## 形态（方案 A：自带浏览器内核的 CDP MCP）

```
智能体（Claude / Cursor / ...）
   │  MCP 协议（stdio）
   ▼
本工具包（无界面后台进程）
   ├── MCP 协议层      ← 7 个 tool，platform 参数 / 链接自动识别
   ├── 浏览器执行层    ← 平台插座 + 三平台方言件 + 隐藏窗口内核
   └── 后端对接层      ← 调 PPXC 生产后端的同步分析接口
```

## 工具

| 工具 | 用户场景 | 状态 |
|---|---|---|
| `check_status_and_login` | 检查 PPXC + 抖音/小红书/快手登录；`login_*` 弹对应扫码窗 | 已接入三平台 |
| `list_products` | 列出账号下产品，拿 productId | 第二期 |
| `analyze_video_comments` | 给内容链接 + 产品 → 读评论 → AI 分析 → 战报 + 入池；platform 可省略 | 抖音已验；小红书/快手待真机 |
| `search_keyword_for_leads` | 给关键词 + **platform** → 搜内容 → 读评论 → 分析 → 汇总战报 | 抖音已验；小红书/快手待真机 |
| `suggest_search_keywords` | 开搜前先要词：读后端想词委员会为产品生成的精选搜索词（带词型+理由） | 0.2 新增 |
| `query_leads` | 问「之前挖到的客户 / 高意向有哪些」→ 只读查客户池，支持按词/天数/状态筛 | 0.2 新增 |
| `export_diagnostics` | 用户说「不好用 / 要反馈」→ 把运行日志打包成桌面上的诊断文件 | 已实测 |

## FAQ

### 需要什么环境？

macOS 或 Windows，Node.js 18+，以及一个 PPXC 账号。目标平台账号由用户本人扫码登录。

### 为什么不能云托管？

本工具依赖用户本机的平台登录态和扫码/验证码窗口，必须在用户自己的电脑上运行。市场上架时请选择 Local / stdio 模式。

### 第一次启动慢怎么办？

首次会下载 Electron 浏览器内核，约 100MB。下载失败通常是网络问题，换网络重试即可；国内网络可按官网 FAQ 加镜像环境变量。

### 能不能自动私信客户？

不做。工具只帮助识别潜在客户、生成跟进话术和主页/来源链接，具体触达由用户本人判断和执行。

### 怎么反馈问题？

对智能体说「导出诊断信息」，它会在桌面生成脱敏诊断文件，发给 PPXC 支持人员即可。

## 桌面战报（0.2）

两件分析工具挖到客户后，会在用户桌面自动生成一份**客户战报**（自包含网页文件，离线可开）：总览数字、行动清单（先跟谁 + 为什么）、客户卡片（评论原话 / 判断理由 / 一键复制话术 / 主页直达）、每个词的成绩单。可转发给同事直接照着跟进。

## 官方技能说明书（教智能体怎么用）

[`skills/ppxc-find-customers/SKILL.md`](./skills/ppxc-find-customers/SKILL.md) 是给智能体的标准工作流：先查登录 → 选产品 → 要词 → 开搜 → 固定格式汇报（含战报文件位置）→ 隔天复盘换词，并写死了额度 / 验证码 / 电力的应对话术。装进 Claude / Cursor 等宿主的技能目录即可，npm 包里也随包分发。

## 风控（按平台分日额度 + 全局 30 秒间隔）

详见 [`docs/开发手册.md` §8](./docs/开发手册.md)。小红书/快手初版比抖音更保守。

## 仓库关系（重要）

本仓库**独立**，不与 `/Users/jianshi/ppxc`（网页 + 后端）、`/Users/jianshi/ppxc-desktop`（桌面客户端稳定线）共享代码、分支、git 历史。

- 后端：本仓库作为 PPXC 后端的**客户端**调用；分析接口 `POST /api/v2/comments/analyze` 在 `ppxc` 仓库，支持 `userProfileUrl` 按平台传入主页链接。
- 桌面客户端：从 `ppxc-desktop` 稳定线**单向搬运**执行内核，搬完解耦。

详细边界见 [`AGENTS.md`](./AGENTS.md)。

## 开发状态

✅ **抖音三期主链路均已真机验证**（链接分析 + 关键词搜索 + 入池）。

🟡 **多平台适配层（2026-06-11）**：

- 阶段 A：`platform-runner` + `platforms/*` 插座架构；抖音逻辑平移；`typecheck` + `build` + `regression:static` 通过。
- 阶段 B：**小红书真机验证通过**——扫码登录、关键词搜索（17 笔记/20 评论）、短链笔记拉评论（10 评论 + 主页链接）三链路实测 OK。探路结论：① 访客也有 web_session cookie，登录态必须读页面状态；② 笔记页必须带 xsec_token 签名链接，裸链接会被「暂时无法浏览」拦截；③ 短链跳转在慢网络下需轮询等待。MCP 工具层端到端（含后端分析+入池）待联调。
- 阶段 C：**快手真机验证通过**——扫码登录、关键词搜索（20 视频/18 评论）、单视频链接拉评论（13 评论 + 主页链接）三链路实测 OK。探路结论：① 扫码先发 passToken（id.kuaishou.com），主站会话票叫 `kuaishou.server.webday7_st`（带灰度后缀且 httpOnly），userId/did 都不能当登录凭证；② 搜索接口是 `/rest/v/search/feed`（作者在 feed 级、评论数字段不可靠）；③ 视频页评论走 graphql `visionCommentList`，真数据在 `rootCommentsV2`（老字段是空壳）。MCP 工具层端到端（含后端分析+入池）待联调。
- 阶段 D：后端 `userProfileUrl` 优先使用 MCP 传入的主页链接；开发手册/README 已更新。

验证命令：

```bash
npm run regression:static          # 静态回归（无需登录）
npm run smoke:comments             # 抖音 smoke（需登录 + PPXC_MCP_VIDEO_URL）
PPXC_MCP_PLATFORM=xiaohongshu PPXC_MCP_LOGIN=1 npm run spike:probe   # 小红书探路
```

运行与验证步骤：见 [`docs/第一期-运行与验证.md`](./docs/第一期-运行与验证.md)。