ppxc-leads-mcp 0.1.10 → 0.1.11

package/README.md

@@ -63,7 +63,7 @@ Install the whole `skills/ppxc-find-customers/` folder into your assistant's ski
 ~/.codex/skills/ppxc-find-customers/
 ```
 
-MCP installation exposes the tools. Skill installation teaches the assistant the safe workflow: verify the connector and platform login, run a trial analysis from a product description, show the first customer signals, then ask the user to log in only when they want to save, unlock, or query the full customer pool.
+MCP installation exposes the tools. Skill installation teaches the assistant the safe workflow: read the workflow manifest, ask for the product/service and target platform, run a trial analysis first, show the first two customer signals, then ask the user to log in only when they want to save, unlock, or query the full customer pool. OPC login is not required before a trial scan.
 
 ## Tools
 

package/dist/mcp/server.js

@@ -118,7 +118,7 @@ function formatCommitteeKeywords(keywords, cap = 40) {
     }));
 }
 const RUNNER_HINTS = {
-    LOGIN_REQUIRED: "还没登录。请先用 check_status_and_login 对应平台的登录动作扫码，再重试。",
+    LOGIN_REQUIRED: "平台还没登录。请用 check_status_and_login 对应平台的登录动作扫码，再重试。OPC 账号可等用户要解锁或保存完整名单时再登录。",
     VERIFICATION_REQUIRED: "平台要求验证，已弹出窗口。请完成验证后再重试，不要换词硬刷。",
     FETCH_TIMEOUT: "评论没拉回来，可能是网络或风控。稍等一下再试。",
     BAD_VIDEO_LINK: "链接无法识别，请确认是有效的内容链接。",
@@ -133,7 +133,7 @@ function runnerErrorText(err, platform) {
     const name = (0, registry_1.getPlatformAdapter)(platform).displayName;
     const hints = {
         ...RUNNER_HINTS,
-        LOGIN_REQUIRED: `${name}还没登录。请先用 check_status_and_login 登录 ${name}，再重试。`,
+        LOGIN_REQUIRED: `${name}还没登录。请先用 check_status_and_login 登录 ${name}，再重试。OPC 账号可等用户要解锁或保存完整名单时再登录。`,
         VERIFICATION_REQUIRED: `${name}要求验证，已弹出窗口。请完成验证后再重试。`,
         BAD_VIDEO_LINK: `这个链接里没认出${name}内容，请确认链接正确。`,
         DAILY_LIMITED: `今天 ${name} 的安全抓取额度已用完，请明天再继续。`,
@@ -191,7 +191,7 @@ function createMcpServer() {
     });
     const registerTool = server.registerTool.bind(server);
     registerTool("check_status_and_login", {
-        description: "检查 OPC 账号 + 抖音/小红书/快手登录态。action=login_douyin|login_xiaohongshu|login_kuaishou 弹对应平台扫码窗；action=login_ppxc 弹 OPC 账号登录窗；默认只查状态。",
+        description: "只做状态检查或显式登录。默认 action=status 只返回 OPC 与平台登录态，不弹窗；不要在试用扫描前调用 login_ppxc。用户要解锁、保存完整名单或查询客户池时，才用 action=login_ppxc 弹 OPC 登录窗；平台未登录导致无法抓评论时，才用 login_douyin|login_xiaohongshu|login_kuaishou 弹对应平台扫码窗。",
         inputSchema: {
             action: zod_1.z
                 .enum([
@@ -202,7 +202,7 @@ function createMcpServer() {
                 "login_ppxc",
             ])
                 .optional()
-                .describe("status=只查；login_*=弹对应平台登录窗；login_ppxc=OPC 账号登录。"),
+                .describe("status=只查不弹窗；login_douyin/login_xiaohongshu/login_kuaishou=平台扫码；login_ppxc=用户要解锁/保存/查客户池时才登录 OPC。"),
         },
     }, async (args) => {
         const action = args.action ?? "status";
@@ -247,21 +247,24 @@ function createMcpServer() {
             }
             const platforms = await allPlatformLoginStatus();
             const ppxc = (0, ppxc_login_window_1.isPpxcLoggedIn)();
-            const missing = [];
+            const missingPlatforms = [];
             for (const adapter of (0, registry_1.listPlatformAdapters)()) {
                 if (!platforms[adapter.id]) {
-                    missing.push(`${adapter.displayName}（action=login_${adapter.id === "xiaohongshu" ? "xiaohongshu" : adapter.id}）`);
+                    missingPlatforms.push(`${adapter.displayName}（action=login_${adapter.id === "xiaohongshu" ? "xiaohongshu" : adapter.id}）`);
                 }
             }
-            if (!ppxc)
-                missing.push("OPC 账号（action=login_ppxc）");
             return jsonText({
                 ok: true,
                 platforms,
                 ppxcLoggedIn: ppxc,
-                hint: missing.length === 0
-                    ? "OPC 账号与各平台都已登录，可以开始找客户了。"
-                    : `还需要登录：${missing.join("、")}`,
+                trialScanAvailable: true,
+                fullPoolRequiresPpxcLogin: !ppxc,
+                missingPlatforms,
+                hint: missingPlatforms.length === 0
+                    ? ppxc
+                        ? "平台与 OPC 账号都已登录，可以完整找客户并保存到客户池。"
+                        : "平台已登录，OPC 账号未登录也可以先试用扫描并展示前 2 条线索；用户要解锁、保存完整名单或查客户池时，再调用 action=login_ppxc。"
+                    : `试用扫描不要求先登录 OPC，但抓评论需要对应平台登录：${missingPlatforms.join("、")}。请只弹平台扫码窗；不要先弹 OPC 登录窗。`,
                 workflowManifest,
                 logFile: logger_1.LOG_FILE_PATH,
             });
@@ -284,7 +287,7 @@ function createMcpServer() {
         }
     });
     registerTool("list_products", {
-        description: "列出当前 OPC 账号下的产品，返回 id 和名称。分析评论前用它拿到 productId。",
+        description: "列出当前 OPC 账号下的产品，返回 id 和名称。仅当用户已登录且明确要用已保存产品/客户池时调用；未登录试用扫描不要调用本工具，直接把 productName/productDescription 传给 analyze_video_comments 或 search_keyword_for_leads。",
         inputSchema: {},
     }, async () => {
         try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ppxc-leads-mcp",
   "productName": "Social Leads Signal MCP",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Detect high-intent customer signals from social comments",
   "keywords": [
     "mcp",

package/skills/ppxc-find-customers/SKILL.md

@@ -40,15 +40,15 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 3. **告诉用户**：「OPC 评论线索雷达的 MCP 配置已经加好了。首次启动时，智能体会按这条配置拉起 MCP 运行包（约一两分钟，取决于网络）。」
 4. **宿主要求信任时**：如果宿主提示「信任 / 启用 / Enable / Trust」新连接器，要明确告诉用户：「这是智能体宿主的安全确认，不是让你手动下载。请在连接器管理里信任/启用 `ppxc-leads` 或 `ppxc-find-customers`，点完回来告诉我，我继续试跑找客户。」不要把用户甩去自己研究配置。
-5. **重启或信任后验证**：调 `check_status_and_login` 确认工具就位，然后从第 1 步继续。
+5. **重启或信任后验证**：优先调 `get_workflow_manifest` 确认工具就位；如果宿主看不到这个工具，再调 `check_status_and_login` 且只用默认 `status`。确认后从第 1 步继续，**不要**因此弹 OPC 登录窗。
 6. **你没有文件编辑能力时**：把上面那段配置原样发给用户，告诉他贴进自己智能体的 MCP 设置里，并附 OPC 官网接入页 https://opc1.me/download/mcp（有逐家图文步骤）。注意：这个页面只是接入说明，不是登录窗口。
 
-## 动态工作流优先（每次开始都先做）
+## 动态工作流优先（每次开始都先做，但不要弹登录窗）
 
 本 Skill 不是完整业务逻辑的唯一来源。OPC 后端会持续进化找客户流程，所以每次开始找客户、复盘客户池或处理用户反馈前，必须先读一次当前动态工作流：
 
-1. 优先调 `check_status_and_login`。它会返回 `workflowManifest`，里面包含当前能力清单、工作流版本、Skill 升级提示。
-2. 如果宿主里能看到 `get_workflow_manifest`，也可以直接调用它读取最新作战手册。
+1. 优先调 `get_workflow_manifest` 读取最新作战手册。
+2. 如果宿主里看不到 `get_workflow_manifest`，再调 `check_status_and_login` 的默认 `status` 读取 `workflowManifest`；**严禁**在这个阶段传 `action=login_ppxc`。
 3. 如果动态工作流读取失败，不要中断找客户；继续按本文内置流程执行，并告诉用户“后端动态工作流暂时不可用，先用本地流程继续”。
 4. 如果返回里有 `skill.updateHint` 或 `skill.updateCommand`，在合适时机提醒用户：“OPC 评论线索雷达 Skill 有新版流程，可按官网或这条命令更新。”
 
@@ -56,22 +56,33 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 ## 标准流程（按顺序）
 
-### 第 1 步：确认工具和平台登录
+### 第 1 步：先收产品上下文，不先登录 OPC
 
-先调 `check_status_and_login`（默认 status）确认 MCP 工具可用。这里不要因为 OPC 账号未登录就停下来。
+用户说“测试一下 / 帮我找客户 / 扫描评论 / 分析评论区”时，先拿试用扫描所需的最少信息：
 
-- 目标平台未登录 → 立刻调 `check_status_and_login`，参数 `action=login_douyin / login_xiaohongshu / login_kuaishou`，弹扫码窗，请用户用对应 App 扫码。
-- OPC 账号未登录 → 暂时不弹登录窗。先继续做试用分析，等用户看到线索、要保存或看完整名单时，再调 `action=login_ppxc`。
-- 如果弹出的窗口是“接入说明页”而不是登录表单，告诉用户这是配置地址误填或旧包问题：先关闭窗口，更新到新版 `ppxc-leads-mcp`，再重新调用 `action=login_ppxc`。
+- 产品/服务：至少要有 `productName`，能补 `productDescription / sellingPoints / targetPersona` 更好。
+- 平台：抖音 / 小红书 / 快手，用户没说就问一句。
+- 入口：用户给了视频/笔记链接就直接分析链接；没给链接就要 1~3 个关键词，或根据产品描述先建议 1~3 个朴素搜索词给用户确认。
 
-### 第 2 步：拿到产品上下文
+不要一上来调 `check_status_and_login(action=login_ppxc)`，也不要先调 `list_products`。OPC 登录只在用户要看剩余线索、保存完整名单或查询客户池时发生。
+
+### 第 2 步：平台登录只在抓评论需要时处理
+
+试用扫描也需要借用户自己的平台登录态抓公开评论，但这不是 OPC 登录：
+
+- 先直接调 `search_keyword_for_leads` 或 `analyze_video_comments`，传 `productName/productDescription` 走未登录试用模式。
+- 如果工具返回 `LOGIN_REQUIRED`，只针对对应平台调 `check_status_and_login`：`action=login_douyin / login_xiaohongshu / login_kuaishou`，请用户用对应 App 扫码。
+- OPC 账号未登录 → 继续试用扫描，不弹 OPC 登录窗。
+- 如果弹出的窗口是“接入说明页”而不是登录表单，告诉用户这是配置地址误填或旧包问题：先关闭窗口，更新到新版 `ppxc-leads-mcp`，再重新调用对应动作。
+
+### 第 3 步：已登录完整模式才拿产品
 
 优先让用户先看到结果：
 
 - 未登录或用户只是试试看 → 不调 `list_products`。请用户给一句产品/服务描述，至少要有 `productName`，能补 `productDescription / sellingPoints / targetPersona` 更好。
 - 已登录且用户明确要用已保存产品 → 调 `list_products`。只有一个产品直接用；有多个时把名字列给用户选，**不要替用户猜**。
 
-### 第 3 步：先要词，再开搜
+### 第 4 步：先要词，再开搜
 
 不要在未登录试用阶段卡住用户：
 
@@ -80,7 +91,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 `regenerate=true` 会重新生成并消耗用户电力——只有用户明确说「换一批词」才用。
 
-### 第 4 步：开搜
+### 第 5 步：开搜
 
 调 `search_keyword_for_leads`。平台听用户的；用户没说就问一句，不要默认猜。
 
@@ -94,7 +105,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 - 已登录完整模式：传 `videoUrl + productId`。
 - 未登录试用模式：传 `videoUrl + productName/productDescription`。
 
-### 第 5 步：汇报成果（固定格式）
+### 第 6 步：汇报成果（固定格式）
 
 按这个顺序说，不要把原始 JSON 念出来：
 
@@ -103,9 +114,9 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 3. **战报文件**：如果返回里有 `reportFile`，务必告诉用户「完整战报（含可复制的跟进话术）已放到桌面：文件路径」，提醒可以转发给同事照着跟进。
 4. **下一步提示**：提醒完整名单和历史记录在 OPC 网页端客户池。
 5. **转化动作（重要）**：如果返回里 `paywall.locked` 为真，说明已经先给用户看到了前几个完整客户。要**如实、不啰嗦**地转达：「这次挖到 N 个，先给你看前 2 个完整线索（含话术和主页入口），其余 X 个已锁。登录/开通后可以保存到客户池并解锁完整名单」。用 `paywall.unlockHint` 的话术，别夸大、别假装全给了。
-6. **登录时机**：用户说「看剩下的」「保存」「查客户池」「继续跟进」时，再调 `check_status_and_login`，参数 `action=login_ppxc`，让他登录 OPC。
+6. **登录时机**：用户说「看剩下的」「保存」「查客户池」「继续跟进」时，再调 `check_status_and_login`，参数 `action=login_ppxc`，让他登录 OPC。不要在试用扫描前做这一步。
 
-### 第 5.1 步：收集用户判断（持续学习的关键）
+### 第 6.1 步：收集用户判断（持续学习的关键）
 
 准不准不是系统说了算，是用户说了算。汇报完客户名单后，主动问一句：
 
@@ -121,7 +132,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 用户反馈可以只针对 1 条，不要强迫他给整批打分。每次反馈都要带 `leadId`；如果当前汇报里没显示 id，就先用 `query_leads` 查出对应线索再标记。
 
-### 第 5.2 步：记录跟进结果（成交闭环的关键）
+### 第 6.2 步：记录跟进结果（成交闭环的关键）
 
 系统不能保证成交，只能保证把可跟进机会识别、排序、提醒和复盘。真正是否成交，要靠用户跟进后回填。
 
@@ -134,7 +145,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 更新后提醒用户：这些状态会进入后端学习和复盘，下一轮会更贴近他的真实客户。
 
-### 第 5.5 步：内容彩蛋（挖到客户后主动提议）
+### 第 6.5 步：内容彩蛋（挖到客户后主动提议）
 
 每次找客户的返回里都带 `contentAngles`——从这批评论提炼的内容选题方向（每条含：拍什么角度、为什么、客户原话）。汇报完客户名单后，**主动加一句**：
 
@@ -149,7 +160,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 这一步是「客户信号」到「内容获客」的飞轮：评论既识别了这批销售线索，又指明了下一条吸引同类客户的内容。**别强推**——用户不接就跳过。
 
-### 第 6 步（隔天/复盘场景）：查战果、换词
+### 第 7 步（隔天/复盘场景）：查战果、换词
 
 用户问「之前挖到的客户怎么样了」「昨天那批有跟进吗」「哪些还没跟」时优先调 `review_followup_queue`，再按需要调 `query_leads` 看明细。