ppxc-leads-mcp 0.1.7 → 0.1.8

package/LICENSE.md

@@ -0,0 +1,11 @@
+# PPXC Leads MCP Proprietary License
+
+Copyright (c) PPXC. All rights reserved.
+
+This package is provided only for use with the PPXC service.
+
+You may install and run this package to connect an MCP-capable assistant to your own PPXC account.
+
+You may not copy, modify, decompile, reverse engineer, republish, redistribute, sublicense, sell, rent, host, or use this package or any substantial part of it to build a competing or derivative service without prior written permission from PPXC.
+
+This package is provided "as is" without warranties of any kind. PPXC may update, limit, suspend, or discontinue access to service-backed functionality according to PPXC account, billing, safety, and abuse-control rules.

package/README.md

@@ -1,20 +1,13 @@
 # PPXC Leads MCP
 
-把 PPXC「从评论区发现高意向客户」的能力，做成智能体可直接调用的 MCP 工具包。
+PPXC Leads MCP lets an MCP-capable assistant help a PPXC user find potential customers from public comments on supported social platforms.
 
-发布包：<https://www.npmjs.com/package/ppxc-leads-mcp>  
-官网接入页：<https://opc1.me/download/mcp>  
-公开仓库：<https://github.com/yuanjian068yuan/ppxc-leads-mcp>
+Package: <https://www.npmjs.com/package/ppxc-leads-mcp>  
+Setup guide: <https://opc1.me/download/mcp>
 
-> **先读这两份，再动手：**
-> 1. [`AGENTS.md`](./AGENTS.md) — 本仓库的硬性边界规则（AI 协作员必读第一文件）
-> 2. [`docs/开发手册.md`](./docs/开发手册.md) — 架构、工具契约、平台适配层、验收标准
->
-> 产品化（从本地半成品到正式可分发小组件）的路线：[`docs/产品化规划-2026-06-11.md`](./docs/产品化规划-2026-06-11.md)
+## Install MCP
 
-## 安装（一行配置）
-
-在支持 MCP 的智能体（Claude 桌面版 / Cursor / 其他）配置里加一段：
+Add this server to an MCP-capable host:
 
 ```json
 {
@@ -27,11 +20,7 @@
 }
 ```
 
-- 首次使用会自动下载运行环境（约 100MB）。如果下载失败，换网络重试；国内网络可在 `env` 里额外加 `ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/`。
-- 默认连 PPXC 生产站；开发联调时在 `env` 里加 `PPXC_API_BASE` 指向本地后端。
-- 装好后对智能体说「检查登录状态」，按提示完成 PPXC 登录和平台扫码即可使用。
-
-Windows 宿主如果不能直接执行 `npx`，用：
+If a Windows host cannot execute `npx` directly, use:
 
 ```json
 {
@@ -44,136 +33,55 @@ Windows 宿主如果不能直接执行 `npx`，用：
 }
 ```
 
-## 一句话定位
-
-用户在智能体里一行配置装好本工具包；首次登录 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 |
+First launch downloads the local browser runtime. Node.js 18 or newer is required.
 
-## 它不是什么
+## Install Skill
 
-- **不是**桌面客户端：没有产品界面，唯一允许出现的窗口是登录窗和验证码窗
-- **不是**浏览器插件：不依赖用户手动安装插件
-- **不是**爬虫平台：借用户本人登录态、保守频率、撞验证就请真人处理，不做任何过验证 / 共享账号的灰色手段
+The official workflow skill is distributed in:
 
-## 隐私与安全
-
-- 平台登录态和 PPXC 登录凭证只保存在用户本机。
-- 不上传平台 token / Cookie，不把它们写进日志或诊断包。
-- 评论文本会通过 HTTPS 发送到 PPXC 后端做 AI 意向判断和话术生成。
-- 分析出的客户结果会写入用户自己的 PPXC 客户池。
-- 遇到验证码或平台安全验证时，组件只会弹出窗口让用户本人处理，不做自动绕过。
-
-## 形态（方案 A：自带浏览器内核的 CDP MCP）
-
-```
-智能体（Claude / Cursor / ...）
-   │  MCP 协议（stdio）
-   ▼
-本工具包（无界面后台进程）
-   ├── MCP 协议层      ← 7 个 tool，platform 参数 / 链接自动识别
-   ├── 浏览器执行层    ← 平台插座 + 三平台方言件 + 隐藏窗口内核
-   └── 后端对接层      ← 调 PPXC 生产后端的同步分析接口
+```text
+skills/ppxc-find-customers/SKILL.md
 ```
 
-## 工具
-
-| 工具 | 用户场景 | 状态 |
-|---|---|---|
-| `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 加镜像环境变量。
+Install the whole `skills/ppxc-find-customers/` folder into your assistant's skill directory, or import the folder through the host's skill UI. For Codex Desktop / Codex CLI, the usual destination is:
 
-### 能不能自动私信客户？
-
-不做。工具只帮助识别潜在客户、生成跟进话术和主页/来源链接，具体触达由用户本人判断和执行。
-
-### 怎么反馈问题？
-
-对智能体说「导出诊断信息」，它会在桌面生成脱敏诊断文件，发给 PPXC 支持人员即可。
-
-## 桌面战报（0.2）
-
-两件分析工具挖到客户后，会在用户桌面自动生成一份**客户战报**（自包含网页文件，离线可开）：总览数字、行动清单（先跟谁 + 为什么）、客户卡片（评论原话 / 判断理由 / 一键复制话术 / 主页直达）、每个词的成绩单。可转发给同事直接照着跟进。
-
-## 官方技能说明书（教智能体怎么用）
-
-[`skills/ppxc-find-customers/SKILL.md`](./skills/ppxc-find-customers/SKILL.md) 是给智能体的标准工作流：先查登录 → 选产品 → 要词 → 开搜 → 固定格式汇报（含战报文件位置）→ 隔天复盘换词，并写死了额度 / 验证码 / 电力的应对话术。装进 Claude / Cursor 等宿主的技能目录即可，npm 包里也随包分发。
-
-## 风控（按平台分日额度 + 全局 30 秒间隔）
-
-详见 [`docs/开发手册.md` §8](./docs/开发手册.md)。小红书/快手初版比抖音更保守。
-
-## 网络代理
-
-平台网页登录窗口（抖音 / 小红书 / 快手）会单独设置 Electron 代理策略。抖音 / 小红书默认 `direct`，避免被系统 HTTP 代理或代理软件拖慢登录二维码加载；快手默认 `system`，因为实测快手在部分 Clash/TUN 网络下走 `direct` 会导航超时，而系统代理配合直连规则更稳定。该设置只影响平台 BrowserWindow，不影响 MCP stdio 或 PPXC 后端 API 调用。
-
-如需恢复系统代理：
-
-```bash
-PPXC_MCP_PLATFORM_PROXY=system npx -y ppxc-leads-mcp
+```text
+~/.codex/skills/ppxc-find-customers/
 ```
 
-可选值：`direct`（默认）、`system`、`auto_detect`。如果 VPN 是全局 TUN / 全局路由模式，应用内 `direct` 不能绕过 VPN，需要在 VPN 客户端里配置分流或临时关闭全局路由。
-
-也可以只覆盖单个平台：
+MCP installation exposes the tools. Skill installation teaches the assistant the safe workflow: check login, choose product, suggest keywords, search for leads, query the customer pool, and export diagnostics when needed.
 
-```bash
-PPXC_MCP_PLATFORM_PROXY_KUAISHOU=direct npx -y ppxc-leads-mcp
-PPXC_MCP_PLATFORM_PROXY_XIAOHONGSHU=system npx -y ppxc-leads-mcp
-PPXC_MCP_PLATFORM_PROXY_DOUYIN=system npx -y ppxc-leads-mcp
-```
+## Tools
 
-## 仓库关系（重要）
+The package exposes seven MCP tools:
 
-本仓库**独立**，不与 `/Users/jianshi/ppxc`（网页 + 后端）、`/Users/jianshi/ppxc-desktop`（桌面客户端稳定线）共享代码、分支、git 历史。
+- `check_status_and_login`
+- `list_products`
+- `suggest_search_keywords`
+- `search_keyword_for_leads`
+- `analyze_video_comments`
+- `query_leads`
+- `export_diagnostics`
 
-- 后端：本仓库作为 PPXC 后端的**客户端**调用；分析接口 `POST /api/v2/comments/analyze` 在 `ppxc` 仓库，支持 `userProfileUrl` 按平台传入主页链接。
-- 桌面客户端：从 `ppxc-desktop` 稳定线**单向搬运**执行内核，搬完解耦。
+## Privacy And Safety
 
-详细边界见 [`AGENTS.md`](./AGENTS.md)。
+- Platform login sessions and PPXC login credentials stay on the user's machine.
+- Platform tokens and cookies are not uploaded to PPXC and are not written to diagnostics.
+- Public comment text is sent to PPXC over HTTPS for customer-intent analysis, follow-up suggestions, and customer-pool storage.
+- Results are saved only to the user's own PPXC customer pool.
+- Captchas, QR-code login, and security checks are handled by the user in a local window. This package does not bypass verification.
+- The tool does not send private messages or automate outreach.
 
-## 开发状态
+## Troubleshooting
 
-✅ **抖音三期主链路均已真机验证**（链接分析 + 关键词搜索 + 入池）。
+If the assistant says the MCP tools are unavailable, restart or refresh the MCP host after adding the config.
 
-🟡 **多平台适配层（2026-06-11）**：
+If startup is slow, wait for the browser runtime download to finish. In mainland China networks, the setup guide includes a mirror configuration for Electron downloads.
 
-- 阶段 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 已更新。
+If a platform asks for QR-code login or verification, complete it manually in the local window, then retry the assistant request.
 
-验证命令：
+If something fails, ask the assistant to run `export_diagnostics` and send the generated diagnostic file to PPXC support.
 
-```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   # 小红书探路
-```
+## License
 
-运行与验证步骤：见 [`docs/第一期-运行与验证.md`](./docs/第一期-运行与验证.md)。
+This package is proprietary. It may be installed and used as part of the PPXC service, but copying, modifying, reverse engineering, republishing, or redistributing it is not allowed except with written permission from PPXC.

package/dist/backend/config.js

@@ -10,4 +10,3 @@ function getApiBase() {
 function isHttpUrl(value) {
     return /^https?:\/\//i.test(value);
 }
-//# sourceMappingURL=config.js.map

package/dist/backend/ppxc-client.js

@@ -154,4 +154,3 @@ async function queryLeads(opts) {
     const paywallLocked = res.headers.get("x-ppxc-paywall") === "locked";
     return { rows: Array.isArray(data) ? data : [], paywallLocked };
 }
-//# sourceMappingURL=ppxc-client.js.map

package/dist/backend/ppxc-login-window.js

@@ -165,4 +165,3 @@ async function logoutPpxc() {
         log.warn("clear login partition failed", err instanceof Error ? err.message : String(err));
     }
 }
-//# sourceMappingURL=ppxc-login-window.js.map

package/dist/backend/token-store.js

@@ -62,4 +62,3 @@ function clearToken() {
     catch {
     }
 }
-//# sourceMappingURL=token-store.js.map

package/dist/browser/comments.js

@@ -6,4 +6,3 @@ Object.defineProperty(exports, "buildCommentUrl", { enumerable: true, get: funct
 Object.defineProperty(exports, "commentsFromJson", { enumerable: true, get: function () { return comments_1.commentsFromJson; } });
 Object.defineProperty(exports, "extractAwemeId", { enumerable: true, get: function () { return comments_1.extractAwemeId; } });
 Object.defineProperty(exports, "isDouyinShortLink", { enumerable: true, get: function () { return comments_1.isDouyinShortLink; } });
-//# sourceMappingURL=comments.js.map

package/dist/browser/douyin-runner.js

@@ -12,4 +12,3 @@ Object.defineProperty(exports, "startDouyinLogin", { enumerable: true, get: func
 Object.defineProperty(exports, "startPlatformLogin", { enumerable: true, get: function () { return platform_runner_1.startPlatformLogin; } });
 Object.defineProperty(exports, "shutdownRunner", { enumerable: true, get: function () { return platform_runner_1.shutdownRunner; } });
 Object.defineProperty(exports, "mapSearchResultForDouyin", { enumerable: true, get: function () { return platform_runner_1.mapSearchResultForDouyin; } });
-//# sourceMappingURL=douyin-runner.js.map

package/dist/browser/kernel/electron-profile.js

@@ -29,4 +29,3 @@ function configureDesktopElectronProfile(app, options) {
     }
     return { profileName, userDataDir };
 }
-//# sourceMappingURL=electron-profile.js.map

package/dist/browser/kernel/logger.js

@@ -54,4 +54,3 @@ exports.logger = {
     scope: createScopedLogger,
 };
 exports.LOG_FILE_PATH = LOG_FILE;
-//# sourceMappingURL=logger.js.map

package/dist/browser/kernel/page-scripts/index.js

@@ -1419,4 +1419,3 @@ exports.DOUYIN_PRESCROLL_SCRIPT = `(async () => {
     return { ok: false, message: (err && err.message) || String(err) };
   }
 })();`;
-//# sourceMappingURL=index.js.map

package/dist/browser/kernel/runner-page-manager.js

@@ -142,4 +142,3 @@ class RunnerPageManager {
     }
 }
 exports.RunnerPageManager = RunnerPageManager;
-//# sourceMappingURL=runner-page-manager.js.map

package/dist/browser/kernel/runner-page-session.js

@@ -1536,4 +1536,3 @@ async function safeJson(wc, script, label, timeoutMs) {
         };
     }
 }
-//# sourceMappingURL=runner-page-session.js.map

package/dist/browser/kernel/runner-page-session.search-parser.js

@@ -184,4 +184,3 @@ function asNumber(value) {
     }
     return undefined;
 }
-//# sourceMappingURL=runner-page-session.search-parser.js.map

package/dist/browser/kernel/runner-page-session.user-agent.js

@@ -29,4 +29,3 @@ function resolveDouyinUserAgent(platform = process.platform, electronVersions =
             return buildUserAgent("Macintosh; Intel Mac OS X 10_15_7", chromeVersion);
     }
 }
-//# sourceMappingURL=runner-page-session.user-agent.js.map

package/dist/browser/platform-runner.js

@@ -309,4 +309,3 @@ function mapSearchResultForDouyin(result) {
         totalComments: result.totalComments,
     };
 }
-//# sourceMappingURL=platform-runner.js.map

package/dist/browser/platforms/detect-platform.js

@@ -30,4 +30,3 @@ function normalizePlatformId(explicit, contentUrl) {
     }
     return "douyin";
 }
-//# sourceMappingURL=detect-platform.js.map

package/dist/browser/platforms/douyin/adapter.js

@@ -159,4 +159,3 @@ function detectPlatformFromUrl(input) {
         return "douyin";
     return null;
 }
-//# sourceMappingURL=adapter.js.map

package/dist/browser/platforms/douyin/comments.js

@@ -127,4 +127,3 @@ function extractAwemeId(input) {
 function isDouyinShortLink(input) {
     return /v\.douyin\.com|\/share\//i.test(String(input ?? ""));
 }
-//# sourceMappingURL=comments.js.map

package/dist/browser/platforms/kuaishou/adapter.js

@@ -175,4 +175,3 @@ exports.kuaishouAdapter = {
         return null;
     },
 };
-//# sourceMappingURL=adapter.js.map

package/dist/browser/platforms/kuaishou/comments.js

@@ -167,4 +167,3 @@ exports.KS_SCROLL_SCRIPT = `(async () => {
   }
   return { ok: true };
 })();`;
-//# sourceMappingURL=comments.js.map

package/dist/browser/platforms/registry.js

@@ -20,4 +20,3 @@ function getPlatformAdapter(platform) {
 function listPlatformAdapters() {
     return Object.values(ADAPTERS);
 }
-//# sourceMappingURL=registry.js.map

package/dist/browser/platforms/shared/cdp-json-waiter.js

@@ -72,4 +72,3 @@ async function waitForJsonResponses(wc, urlMatcher, timeoutMs, maxResponses = 3)
         timer = setTimeout(finish, Math.max(500, timeoutMs));
     });
 }
-//# sourceMappingURL=cdp-json-waiter.js.map

package/dist/browser/platforms/types.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/browser/platforms/xiaohongshu/adapter.js

@@ -230,4 +230,3 @@ exports.xiaohongshuAdapter = {
         return null;
     },
 };
-//# sourceMappingURL=adapter.js.map

package/dist/browser/platforms/xiaohongshu/comments.js

@@ -210,4 +210,3 @@ exports.XHS_LOGIN_STATE_SCRIPT = `(() => {
     return { ok: false, loggedIn: false };
   }
 })();`;
-//# sourceMappingURL=comments.js.map

package/dist/browser/usage-throttle.js

@@ -69,4 +69,3 @@ function consumeCrawlQuota(platform, units, dailyLimit) {
     writeState(state);
     return { ok: true, usedToday: state.usedByPlatform[platform] ?? 0, limit: dailyLimit };
 }
-//# sourceMappingURL=usage-throttle.js.map

package/dist/main.js

@@ -63,4 +63,3 @@ else {
         electron_1.app.exit(1);
     });
 }
-//# sourceMappingURL=main.js.map

package/dist/mcp/battle-report.js

@@ -322,4 +322,3 @@ function exportBattleReport(input) {
         return { ok: false, error: msg };
     }
 }
-//# sourceMappingURL=battle-report.js.map

package/dist/mcp/content-insights.js

@@ -63,4 +63,3 @@ function deriveContentAngles(leads, topN = 3) {
     angles.sort((a, b) => b.count - a.count);
     return angles.slice(0, topN);
 }
-//# sourceMappingURL=content-insights.js.map

package/dist/mcp/diagnostics.js

@@ -79,4 +79,3 @@ function exportDiagnostics() {
         return { ok: false, error: msg };
     }
 }
-//# sourceMappingURL=diagnostics.js.map

package/dist/mcp/server.js

@@ -841,4 +841,3 @@ async function startMcpServer(onInputClosed) {
     const transport = new stdio_js_1.StdioServerTransport(mcpInputStream(onInputClosed), process.stdout);
     await server.connect(transport);
 }
-//# sourceMappingURL=server.js.map

package/dist/version.js

@@ -16,4 +16,3 @@ function readOwnVersion() {
     }
 }
 exports.OWN_VERSION = readOwnVersion();
-//# sourceMappingURL=version.js.map

package/package.json

@@ -1,17 +1,10 @@
 {
   "name": "ppxc-leads-mcp",
   "productName": "PPXC Leads MCP",
-  "version": "0.1.7",
-  "description": "PPXC 找客户能力的 MCP 工具包：智能体可调用的抖音/小红书/快手评论客户发现工具",
+  "version": "0.1.8",
+  "description": "PPXC 找客户能力的 MCP 本地连接器",
   "license": "UNLICENSED",
   "homepage": "https://opc1.me/download/mcp",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yuanjian068yuan/ppxc-leads-mcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/yuanjian068yuan/ppxc-leads-mcp/issues"
-  },
   "main": "dist/main.js",
   "type": "commonjs",
   "bin": {