ppxc-leads-mcp 0.1.11 → 0.1.12

package/dist/browser/platform-runner.js

@@ -63,6 +63,19 @@ function randomDelay(adapter) {
     const { perItemMinDelayMs, perItemMaxDelayMs } = adapter.risk;
     return perItemMinDelayMs + Math.floor(Math.random() * (perItemMaxDelayMs - perItemMinDelayMs));
 }
+async function emitSearchProgress(handler, event) {
+    if (!handler)
+        return;
+    try {
+        await handler(event);
+    }
+    catch (err) {
+        log.warn("search progress handler failed", {
+            stage: event.stage,
+            msg: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 async function ensureOnContentPage(session, contentId, contentUrl) {
     const current = session.currentUrl();
     if (current.includes(contentId)) {
@@ -142,7 +155,7 @@ async function fetchContentCommentsInner(adapter, contentUrlOrId, maxComments) {
         hasMore: fetched.hasMore,
     };
 }
-async function searchKeywordForLeads(platform, keyword, maxItems = 5, commentsPerItem = 30, slotId = SLOT_ID, shouldAbort) {
+async function searchKeywordForLeads(platform, keyword, maxItems = 5, commentsPerItem = 30, slotId = SLOT_ID, shouldAbort, onProgress) {
     const adapter = (0, registry_1.getPlatformAdapter)(platform);
     const kw = String(keyword ?? "").trim();
     if (!kw)
@@ -185,6 +198,7 @@ async function searchKeywordForLeads(platform, keyword, maxItems = 5, commentsPe
         throw new RunnerError("NO_SEARCH_RESULT", `「${kw}」搜到的内容评论都太少，换个词试试`);
     }
     const items = [];
+    const readAttempts = [];
     let totalComments = 0;
     for (const it of selected) {
         if (shouldAbort?.()) {
@@ -193,11 +207,33 @@ async function searchKeywordForLeads(platform, keyword, maxItems = 5, commentsPe
         }
         const contentId = String(it.contentId);
         const contentUrl = it.contentUrl || adapter.buildContentUrl(contentId);
+        const attempt = {
+            contentId,
+            contentUrl,
+            title: it.title ?? "",
+            authorName: it.authorName ?? "",
+            estimatedCommentCount: it.commentCount ?? 0,
+            status: "failed",
+            commentsFetched: 0,
+        };
+        readAttempts.push(attempt);
+        await emitSearchProgress(onProgress, {
+            stage: "content_selected",
+            platform,
+            keyword: kw,
+            contentId,
+            contentUrl,
+            title: attempt.title,
+            authorName: attempt.authorName,
+            estimatedCommentCount: attempt.estimatedCommentCount,
+        });
         try {
             await ensureOnContentPage(session, contentId, contentUrl);
             const fetched = await adapter.fetchComments(session, contentId, contentUrl, commentCount, DEFAULT_FETCH_WAIT_MS);
             if (fetched.json) {
                 const comments = adapter.parseComments(contentId, fetched.json);
+                attempt.status = "ok";
+                attempt.commentsFetched = comments.length;
                 totalComments += comments.length;
                 items.push({
                     contentId,
@@ -210,13 +246,28 @@ async function searchKeywordForLeads(platform, keyword, maxItems = 5, commentsPe
                     comments,
                 });
             }
+            else {
+                attempt.error = "评论接口没有返回数据";
+            }
         }
         catch (err) {
+            attempt.error = err instanceof Error ? err.message : String(err);
             log.warn("search item comment fetch failed", {
                 contentId,
-                msg: err instanceof Error ? err.message : String(err),
+                msg: attempt.error,
             });
         }
+        await emitSearchProgress(onProgress, {
+            stage: "content_read",
+            platform,
+            keyword: kw,
+            contentId,
+            contentUrl,
+            title: attempt.title,
+            status: attempt.status === "ok" ? "ok" : "failed",
+            commentsFetched: attempt.commentsFetched,
+            ...(attempt.error ? { error: attempt.error } : {}),
+        });
         await sleep(randomDelay(adapter));
     }
     return {
@@ -224,11 +275,12 @@ async function searchKeywordForLeads(platform, keyword, maxItems = 5, commentsPe
         itemsFound: ranked.length,
         itemsRead: items.length,
         items,
+        readAttempts,
         videos: items,
         totalComments,
     };
 }
-async function searchKeywordsBatch(platform, keywords, maxItemsPerKeyword = 5, commentsPerItem = 30) {
+async function searchKeywordsBatch(platform, keywords, maxItemsPerKeyword = 5, commentsPerItem = 30, onProgress) {
     const adapter = (0, registry_1.getPlatformAdapter)(platform);
     const cleaned = [];
     const seen = new Set();
@@ -250,6 +302,13 @@ async function searchKeywordsBatch(platform, keywords, maxItemsPerKeyword = 5, c
         }
         assertCrawlQuota(platform, cleaned.length);
         const perKeywordCap = Math.max(1, Math.min(Math.max(1, Math.min(adapter.risk.maxVideosPerKeyword, Math.floor(maxItemsPerKeyword) || 5)), Math.floor(adapter.risk.totalContentBudget / cleaned.length)));
+        await emitSearchProgress(onProgress, {
+            stage: "batch_start",
+            platform,
+            keywords: cleaned,
+            maxItemsPerKeyword: perKeywordCap,
+            commentsPerItem,
+        });
         const slotCount = Math.min(MAX_SLOTS, cleaned.length);
         const outcomes = [];
         let verificationHit = false;
@@ -263,8 +322,22 @@ async function searchKeywordsBatch(platform, keywords, maxItemsPerKeyword = 5, c
                     continue;
                 }
                 try {
-                    const result = await searchKeywordForLeads(platform, kw, perKeywordCap, commentsPerItem, slotId, () => verificationHit);
+                    await emitSearchProgress(onProgress, {
+                        stage: "keyword_start",
+                        platform,
+                        keyword: kw,
+                    });
+                    const result = await searchKeywordForLeads(platform, kw, perKeywordCap, commentsPerItem, slotId, () => verificationHit, onProgress);
                     outcomes.push({ keyword: kw, ok: true, result });
+                    await emitSearchProgress(onProgress, {
+                        stage: "keyword_done",
+                        platform,
+                        keyword: kw,
+                        itemsFound: result.itemsFound,
+                        itemsSelected: result.readAttempts?.length ?? result.items.length,
+                        itemsRead: result.itemsRead,
+                        commentsFetched: result.totalComments,
+                    });
                 }
                 catch (err) {
                     const code = err instanceof RunnerError ? err.code : "INTERNAL";
@@ -272,10 +345,23 @@ async function searchKeywordsBatch(platform, keywords, maxItemsPerKeyword = 5, c
                     outcomes.push({ keyword: kw, ok: false, errorCode: code });
                     if (code === "VERIFICATION_REQUIRED")
                         verificationHit = true;
+                    await emitSearchProgress(onProgress, {
+                        stage: "keyword_failed",
+                        platform,
+                        keyword: kw,
+                        errorCode: code,
+                    });
                 }
             }
         };
         await Promise.all(Array.from({ length: slotCount }, (_v, slotId) => runSlot(slotId)));
+        await emitSearchProgress(onProgress, {
+            stage: "batch_done",
+            platform,
+            keywords: cleaned,
+            completed: outcomes.filter((o) => o.ok).length,
+            failed: outcomes.filter((o) => !o.ok).length,
+        });
         return outcomes;
     });
 }

package/dist/mcp/server.js

@@ -97,6 +97,35 @@ function hasProductContext(ctx) {
 function productContextHint() {
     return "先告诉我你卖的产品/服务名称，最好再补一句适合谁、解决什么问题；我可以先试跑一轮，给你看前 2 条线索。";
 }
+function traceFromAttempt(attempt) {
+    return {
+        contentId: attempt.contentId,
+        url: attempt.contentUrl,
+        ...(attempt.title ? { title: attempt.title } : {}),
+        ...(attempt.authorName ? { authorName: attempt.authorName } : {}),
+        estimatedCommentCount: attempt.estimatedCommentCount,
+        commentsFetched: attempt.commentsFetched,
+        status: attempt.status === "ok" ? "read" : "failed",
+        ...(attempt.error ? { error: attempt.error } : {}),
+    };
+}
+function workflowTraceNarrative(input) {
+    const lines = [];
+    const kw = input.keywords?.length ? `，关键词：${input.keywords.join("、")}` : "";
+    lines.push(`本轮在${input.platformName}执行${input.keywords?.length ? "关键词搜索" : "单链接分析"}${kw}。`);
+    lines.push(`实际打开并读取了 ${input.itemsRead} 条内容，送 AI 分析 ${input.commentsAnalyzed} 条评论，识别出 ${input.demandsFound} 个潜在客户。`);
+    const visible = input.contents.slice(0, 8);
+    for (const item of visible) {
+        const title = item.title ? `《${item.title.slice(0, 40)}》` : item.contentId;
+        const demandText = typeof item.demandsFound === "number" ? `，识别 ${item.demandsFound} 个线索` : "";
+        const statusText = item.status === "read" ? `读了 ${item.commentsAnalyzed ?? item.commentsFetched} 条评论${demandText}` : `读取失败：${item.error ?? "未知原因"}`;
+        lines.push(`看过：${title}，${statusText}，链接：${item.url}`);
+    }
+    if (input.contents.length > visible.length) {
+        lines.push(`还有 ${input.contents.length - visible.length} 条内容已记录在 workflowTrace.contents 里。`);
+    }
+    return lines;
+}
 function topPickOf(reportLeads) {
     const sorted = [...reportLeads].sort((a, b) => (b.saleScore ?? 0) - (a.saleScore ?? 0));
     const top = sorted[0];
@@ -117,6 +146,63 @@ function formatCommitteeKeywords(keywords, cap = 40) {
         ...(k.reason ? { reason: k.reason } : {}),
     }));
 }
+function progressMessage(event, platformName) {
+    switch (event.stage) {
+        case "batch_start":
+            return `开始在${platformName}搜 ${event.keywords.length} 个关键词：${event.keywords.join("、")}`;
+        case "keyword_start":
+            return `开始搜「${event.keyword}」。`;
+        case "content_selected": {
+            const title = event.title ? `《${event.title.slice(0, 48)}》` : event.contentId;
+            return `打开候选内容 ${title}，预估评论 ${event.estimatedCommentCount} 条，链接：${event.contentUrl}`;
+        }
+        case "content_read": {
+            const title = event.title ? `《${event.title.slice(0, 48)}》` : event.contentId;
+            if (event.status === "ok") {
+                return `读完 ${title}，抓到 ${event.commentsFetched} 条评论。`;
+            }
+            return `这条内容读取失败：${title}，原因：${event.error ?? "未知原因"}`;
+        }
+        case "keyword_done":
+            return `「${event.keyword}」完成：候选 ${event.itemsFound} 条，打开 ${event.itemsSelected} 条，读到 ${event.commentsFetched} 条评论。`;
+        case "keyword_failed":
+            return `「${event.keyword}」没有完成，错误码：${event.errorCode}`;
+        case "batch_done":
+            return `本轮搜索结束：完成 ${event.completed} 个关键词，失败 ${event.failed} 个。`;
+    }
+}
+function createSearchProgressReporter(extra, platformName) {
+    let progress = 0;
+    return async (event) => {
+        progress += 1;
+        const message = progressMessage(event, platformName);
+        try {
+            if (extra._meta?.progressToken !== undefined) {
+                await extra.sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                        progressToken: extra._meta.progressToken,
+                        progress,
+                        message,
+                    },
+                });
+            }
+            await extra.sendNotification({
+                method: "notifications/message",
+                params: {
+                    level: event.stage.endsWith("failed") ? "warning" : "info",
+                    logger: "opc-comment-lead-radar",
+                    data: {
+                        message,
+                        event,
+                    },
+                },
+            });
+        }
+        catch {
+        }
+    };
+}
 const RUNNER_HINTS = {
     LOGIN_REQUIRED: "平台还没登录。请用 check_status_and_login 对应平台的登录动作扫码，再重试。OPC 账号可等用户要解锁或保存完整名单时再登录。",
     VERIFICATION_REQUIRED: "平台要求验证，已弹出窗口。请完成验证后再重试，不要换词硬刷。",
@@ -296,8 +382,8 @@ function createMcpServer() {
                 ok: true,
                 products,
                 hint: products.length === 0
-                    ? "这个账号下还没有产品，请先到 OPC 网页端创建一个产品。"
-                    : "把其中一个产品的 id 作为 productId 传给 analyze_video_comments。",
+                    ? "这个账号下还没有已保存产品。不要因此中断试用扫描；请让用户给产品/服务名称和搜索词，直接调用 search_keyword_for_leads 或 analyze_video_comments。只有用户要保存完整名单、查客户池或长期复盘时，再引导他到 OPC 创建产品。"
+                    : "只有用户明确要使用已保存产品时，才把其中一个产品的 id 作为 productId；普通试用扫描仍可直接传 productName/productDescription。",
             });
         }
         catch (err) {
@@ -305,7 +391,7 @@ function createMcpServer() {
                 return jsonText({
                     ok: false,
                     code: "PPXC_LOGIN_REQUIRED",
-                    userHint: "OPC 账号未登录或登录失效，请先用 check_status_and_login（action=login_ppxc）登录。",
+                    userHint: "产品列表只用于已登录完整模式。若用户只是试用扫描，不要先登录 OPC；请收集 productName/productDescription 和搜索词，直接调用 search_keyword_for_leads。",
                 });
             }
             return jsonText({
@@ -318,7 +404,7 @@ function createMcpServer() {
     });
     registerTool("analyze_video_comments", {
         description: "给一条抖音/小红书/快手内容链接 + productId 或 productName：读评论 → OPC AI 分析 → 客户战报。未登录用户可只传 productName 先试跑，返回前 2 条线索；登录后传 productId 才会落客户池。platform 可省略，会从链接自动识别。" +
-            "挖到客户时会在用户桌面生成一份战报网页文件（结果里的 reportFile），汇报时务必告诉用户文件位置和首推客户及理由（topPick）。" +
+            "工具会通过 MCP 通知实时汇报进度，并在结果里返回 workflowTrace/processNarrative。reportFile 只是本机临时战报备份，不是解锁入口；用户要看剩余线索或保存完整名单时，应引导登录 OPC 网页端客户池。" +
             "结果里的 contentAngles 是从这批评论提炼的内容选题方向（拍什么/为什么/客户原话），汇报后可主动提议「要不要根据这些评论写下一条视频脚本」。",
         inputSchema: {
             videoUrl: zod_1.z.string().describe("内容链接（抖音视频/小红书笔记/快手视频）或 ID。"),
@@ -334,12 +420,14 @@ function createMcpServer() {
             maxComments: zod_1.z.number().int().min(1).max(50).optional().describe("最多读多少条评论，默认 30。"),
             save: zod_1.z.boolean().optional().describe("是否落客户池，默认 true。"),
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         const videoUrl = args.videoUrl;
         const productContext = productContextFromArgs(args);
         const maxComments = args.maxComments;
         const save = args.save;
         const platform = (0, detect_platform_1.normalizePlatformId)(args.platform, videoUrl);
+        const adapter = (0, registry_1.getPlatformAdapter)(platform);
+        const reportProgress = createSearchProgressReporter(extra, adapter.displayName);
         if (!hasProductContext(productContext)) {
             return jsonText({
                 ok: false,
@@ -349,9 +437,40 @@ function createMcpServer() {
         }
         let fetched;
         try {
+            await reportProgress({
+                stage: "content_selected",
+                platform,
+                keyword: "单链接分析",
+                contentId: videoUrl,
+                contentUrl: videoUrl,
+                title: "",
+                authorName: "",
+                estimatedCommentCount: maxComments ?? 30,
+            });
             fetched = await (0, platform_runner_1.fetchContentComments)(platform, videoUrl, maxComments ?? 30);
+            await reportProgress({
+                stage: "content_read",
+                platform,
+                keyword: "单链接分析",
+                contentId: fetched.contentId,
+                contentUrl: fetched.contentUrl,
+                title: "",
+                status: "ok",
+                commentsFetched: fetched.comments.length,
+            });
         }
         catch (err) {
+            await reportProgress({
+                stage: "content_read",
+                platform,
+                keyword: "单链接分析",
+                contentId: videoUrl,
+                contentUrl: videoUrl,
+                title: "",
+                status: "failed",
+                commentsFetched: 0,
+                error: err instanceof Error ? err.message : String(err),
+            });
             if (err instanceof platform_runner_1.RunnerError) {
                 return jsonText(runnerErrorText(err, platform));
             }
@@ -385,7 +504,7 @@ function createMcpServer() {
             if (reportLeads.length > 0) {
                 const exported = (0, battle_report_1.exportBattleReport)({
                     kind: "link",
-                    platformName: (0, registry_1.getPlatformAdapter)(platform).displayName,
+                    platformName: adapter.displayName,
                     productName: productContext.productName || (productContext.productId ? await productNameOf(productContext.productId) : undefined),
                     contentUrl: fetched.contentUrl,
                     summary: analysis.summary,
@@ -409,10 +528,39 @@ function createMcpServer() {
             const lockedTail = paywallLocked
                 ? `你当前是体验版，只解锁了前 ${reportLeads.length} 个完整客户；${paywall.unlockHint}`
                 : "";
+            const contentTrace = {
+                contentId: fetched.contentId,
+                url: fetched.contentUrl,
+                commentsFetched: fetched.comments.length,
+                commentsAnalyzed: analysis.summary.commentsAnalyzed,
+                demandsFound: analysis.summary.demandsFound,
+                highIntentCount: analysis.summary.highIntentCount,
+                status: "read",
+            };
+            const processNarrative = workflowTraceNarrative({
+                platformName: adapter.displayName,
+                itemsRead: 1,
+                commentsAnalyzed: analysis.summary.commentsAnalyzed,
+                demandsFound: analysis.summary.demandsFound,
+                contents: [contentTrace],
+            });
             return jsonText({
                 ok: true,
                 platform,
                 content: { id: fetched.contentId, url: fetched.contentUrl },
+                workflowTrace: {
+                    mode: "single_content",
+                    platform,
+                    contents: [contentTrace],
+                    totals: {
+                        itemsRead: 1,
+                        commentsFetched: fetched.comments.length,
+                        commentsAnalyzed: analysis.summary.commentsAnalyzed,
+                        demandsFound: analysis.summary.demandsFound,
+                        highIntentCount: analysis.summary.highIntentCount,
+                    },
+                },
+                processNarrative,
                 summary: {
                     ...analysis.summary,
                     commentsFetched: fetched.comments.length,
@@ -430,8 +578,8 @@ function createMcpServer() {
                     ? {
                         reportFile: report.file,
                         reportHint: paywallLocked
-                            ? `已生成战报（网页文件），里面只展示了解锁的前 ${reportLeads.length} 个客户；其余已锁。开通套餐后，重新查询客户池或重新生成战报即可拿到完整结果。文件在：${report.file}`
-                            : `已生成一份客户战报（网页文件，含话术，可转发同事照着跟进），放在：${report.file}`,
+                            ? `已生成本机临时战报备份，只展示已解锁的前 ${reportLeads.length} 个客户；它不是解锁入口。要看剩余线索，请登录 OPC 网页端客户池并开通/解锁完整名单。备份文件在：${report.file}`
+                            : `已生成本机临时战报备份（含话术，可转发同事照着跟进），放在：${report.file}`,
                     }
                     : {}),
             });
@@ -480,7 +628,7 @@ function createMcpServer() {
     });
     registerTool("search_keyword_for_leads", {
         description: "关键词 + productId 或 productName + platform：搜内容 → 读评论 → AI 分析 → 汇总战报。未登录用户可只传 productName 先试跑，返回前 2 条线索；登录后传 productId 才会落客户池。支持 douyin/xiaohongshu/kuaishou。多关键词 2 窗口并行（抖音）；小红书/快手更保守。" +
-            "挖到客户时会在用户桌面生成一份战报网页文件（结果里的 reportFile），汇报时务必告诉用户文件位置和首推客户及理由（topPick）。" +
+            "工具会通过 MCP 通知实时汇报搜了哪些词、打开哪些内容、每条读了多少评论；最终结果也会返回 workflowTrace/processNarrative。reportFile 只是本机临时战报备份，不是解锁入口；用户要看剩余线索或保存完整名单时，应引导登录 OPC 网页端客户池。" +
             "结果里的 contentAngles 是从这批评论提炼的内容选题方向（拍什么/为什么/客户原话），汇报后可主动提议「要不要根据这些评论写下一条视频脚本」。",
         inputSchema: {
             platform: PLATFORM_ZOD.describe("在哪个平台搜：douyin | xiaohongshu | kuaishou。"),
@@ -504,7 +652,7 @@ function createMcpServer() {
                 .describe("每个关键词最多读几条内容；合计有平台上限（抖音 12、小红书/快手 8）。"),
             save: zod_1.z.boolean().optional().describe("是否落客户池，默认 true。"),
         },
-    }, async (args) => {
+    }, async (args, extra) => {
         const platform = (0, detect_platform_1.normalizePlatformId)(args.platform);
         const keywords = args.keywords ?? [];
         const productContext = productContextFromArgs(args);
@@ -519,7 +667,7 @@ function createMcpServer() {
         }
         let outcomes;
         try {
-            outcomes = await (0, platform_runner_1.searchKeywordsBatch)(platform, keywords, maxVideosPerKeyword ?? 5);
+            outcomes = await (0, platform_runner_1.searchKeywordsBatch)(platform, keywords, maxVideosPerKeyword ?? 5, 30, createSearchProgressReporter(extra, adapter.displayName));
         }
         catch (err) {
             if (err instanceof platform_runner_1.RunnerError) {
@@ -540,19 +688,48 @@ function createMcpServer() {
         let skippedDuplicates = 0;
         let saveFailedCount = 0;
         let itemsRead = 0;
+        let commentsFetched = 0;
         let lockedFromBackend = 0;
         let anyLocked = false;
         const perKeyword = [];
+        const workflowKeywords = [];
         for (const oc of outcomes) {
             if (!oc.ok || !oc.result) {
                 perKeyword.push({ keyword: oc.keyword, ok: false, code: oc.errorCode });
+                workflowKeywords.push({
+                    keyword: oc.keyword,
+                    ok: false,
+                    errorCode: oc.errorCode,
+                    contents: [],
+                });
                 continue;
             }
             let kwDemands = 0;
+            let kwCommentsAnalyzed = 0;
+            let kwHighIntentCount = 0;
             const contentItems = oc.result.items ?? oc.result.videos ?? [];
+            const contentTraceById = new Map();
+            for (const attempt of oc.result.readAttempts ?? []) {
+                contentTraceById.set(attempt.contentId, traceFromAttempt(attempt));
+            }
             for (const v of contentItems) {
                 itemsRead += 1;
                 const itemUrl = v.contentUrl ?? v.videoUrl ?? "";
+                commentsFetched += v.comments.length;
+                const contentTrace = contentTraceById.get(v.contentId) ??
+                    {
+                        contentId: v.contentId,
+                        url: itemUrl,
+                        title: v.title,
+                        authorName: v.authorName,
+                        estimatedCommentCount: v.commentCount,
+                        commentsFetched: v.comments.length,
+                        status: "read",
+                    };
+                contentTrace.status = "read";
+                contentTrace.commentsFetched = v.comments.length;
+                contentTrace.url = itemUrl || contentTrace.url;
+                contentTraceById.set(v.contentId, contentTrace);
                 try {
                     const analysis = await (0, ppxc_client_1.analyzeComments)({
                         ...productContext,
@@ -563,9 +740,14 @@ function createMcpServer() {
                         save: save !== false,
                     });
                     commentsAnalyzed += analysis.summary.commentsAnalyzed;
+                    kwCommentsAnalyzed += analysis.summary.commentsAnalyzed;
                     demandsFound += analysis.summary.demandsFound;
                     kwDemands += analysis.summary.demandsFound;
                     highIntentCount += analysis.summary.highIntentCount;
+                    kwHighIntentCount += analysis.summary.highIntentCount;
+                    contentTrace.commentsAnalyzed = analysis.summary.commentsAnalyzed;
+                    contentTrace.demandsFound = analysis.summary.demandsFound;
+                    contentTrace.highIntentCount = analysis.summary.highIntentCount;
                     savedToPool += analysis.saved;
                     skippedDuplicates += analysis.skippedDuplicates ?? 0;
                     if (analysis.saveFailed === true)
@@ -609,9 +791,24 @@ function createMcpServer() {
             perKeyword.push({
                 keyword: oc.keyword,
                 ok: true,
+                itemsFound: oc.result.itemsFound,
                 itemsRead: contentItems.length,
+                commentsFetched: oc.result.totalComments,
+                commentsAnalyzed: kwCommentsAnalyzed,
                 demands: kwDemands,
             });
+            workflowKeywords.push({
+                keyword: oc.keyword,
+                ok: true,
+                itemsFound: oc.result.itemsFound,
+                itemsSelected: oc.result.readAttempts?.length ?? contentItems.length,
+                itemsRead: contentItems.length,
+                commentsFetched: oc.result.totalComments,
+                commentsAnalyzed: kwCommentsAnalyzed,
+                demandsFound: kwDemands,
+                highIntentCount: kwHighIntentCount,
+                contents: [...contentTraceById.values()],
+            });
         }
         const hitVerification = outcomes.some((o) => !o.ok && o.errorCode === "VERIFICATION_REQUIRED");
         const hitLoginRequired = outcomes.some((o) => !o.ok && o.errorCode === "LOGIN_REQUIRED");
@@ -622,6 +819,7 @@ function createMcpServer() {
                     code: "VERIFICATION_REQUIRED",
                     userHint: `${adapter.displayName}要求验证，已弹出窗口，本次搜索已停止。请先完成验证，不要换词重试。`,
                     perKeyword,
+                    workflowTrace: { mode: "keyword_search", platform, keywords: workflowKeywords },
                 });
             }
             if (hitLoginRequired) {
@@ -630,6 +828,7 @@ function createMcpServer() {
                     code: "LOGIN_REQUIRED",
                     userHint: `${adapter.displayName}登录已失效，请先登录后再重试。`,
                     perKeyword,
+                    workflowTrace: { mode: "keyword_search", platform, keywords: workflowKeywords },
                 });
             }
             return jsonText({
@@ -637,6 +836,7 @@ function createMcpServer() {
                 code: "EMPTY_COMMENTS",
                 userHint: "搜到的内容没读到可分析的评论，换个词试试。",
                 perKeyword,
+                workflowTrace: { mode: "keyword_search", platform, keywords: workflowKeywords },
             });
         }
         allLeads.sort((a, b) => (b.saleScore ?? 0) - (a.saleScore ?? 0));
@@ -678,14 +878,38 @@ function createMcpServer() {
         const lockedTail = paywallLocked
             ? `你当前是体验版，只解锁了前 ${visibleAllLeads.length} 个完整客户；${unlockHint}`
             : "";
+        const allContentTrace = workflowKeywords.flatMap((kw) => kw.contents);
+        const processNarrative = workflowTraceNarrative({
+            platformName: adapter.displayName,
+            keywords: outcomes.map((o) => o.keyword),
+            itemsRead,
+            commentsAnalyzed,
+            demandsFound,
+            contents: allContentTrace,
+        });
         return jsonText({
             ok: true,
             platform,
             keywords: outcomes.map((o) => o.keyword),
             warning,
+            workflowTrace: {
+                mode: "keyword_search",
+                platform,
+                keywords: workflowKeywords,
+                totals: {
+                    keywordsSearched: outcomes.length,
+                    itemsRead,
+                    commentsFetched,
+                    commentsAnalyzed,
+                    demandsFound,
+                    highIntentCount,
+                },
+            },
+            processNarrative,
             summary: {
                 keywordsSearched: outcomes.length,
                 itemsRead,
+                commentsFetched,
                 commentsAnalyzed,
                 demandsFound,
                 highIntentCount,
@@ -704,19 +928,19 @@ function createMcpServer() {
                 ? {
                     reportFile: report.file,
                     reportHint: paywallLocked
-                        ? `已生成战报（网页文件），只展示了解锁的前 ${visibleAllLeads.length} 个客户；其余已锁。开通套餐后，重新查询客户池或重新生成战报即可拿到完整结果。文件在：${report.file}`
-                        : `已生成一份客户战报（网页文件，含每个词的成绩和话术，可转发同事照着跟进），放在：${report.file}`,
+                        ? `已生成本机临时战报备份，只展示已解锁的前 ${visibleAllLeads.length} 个客户；它不是解锁入口。要看剩余线索，请登录 OPC 网页端客户池并开通/解锁完整名单。备份文件在：${report.file}`
+                        : `已生成本机临时战报备份（含每个词的成绩和话术，可转发同事照着跟进），放在：${report.file}`,
                 }
                 : {}),
         });
     });
     registerTool("suggest_search_keywords", {
-        description: "给 productId，返回 OPC 想词委员会为该产品生成的精选搜索词（带词型分类和推荐理由）。" +
+        description: "完整模式专用：给已保存产品的 productId，返回 OPC 想词委员会为该产品生成的精选搜索词（带词型分类和推荐理由）。新用户/未登录试用/没有产品列表时不要调用本工具；应先向用户要产品/服务名称和 1-3 个朴素搜索词，或根据产品描述自己建议词，然后直接调用 search_keyword_for_leads 并传 productName/productDescription。" +
             "词单通常在产品创建/编辑时已自动生成，本工具默认直接读现成结果；没有现成词单时会触发一轮生成并等待（约 1 分钟）。" +
-            "开搜前先调它，从主力词里挑 3~6 个传给 search_keyword_for_leads，比现场编词命中率高得多。" +
+            "只有用户已登录且明确选择了已保存产品时，才在开搜前调它，从主力词里挑 3~6 个传给 search_keyword_for_leads。" +
             "regenerate=true 强制重新生成（消耗用户电力，仅当用户明确要求换一批词时使用）。",
         inputSchema: {
-            productId: zod_1.z.string().describe("产品 id，用 list_products 获取。"),
+            productId: zod_1.z.string().describe("已登录完整模式的产品 id，用 list_products 获取；试用扫描不要为了拿 productId 要求用户登录或创建产品。"),
             regenerate: zod_1.z
                 .boolean()
                 .optional()
@@ -726,7 +950,11 @@ function createMcpServer() {
         const productId = args.productId;
         const regenerate = args.regenerate === true;
         if (!productId || typeof productId !== "string") {
-            return jsonText({ ok: false, code: "NO_PRODUCT", userHint: "缺少 productId。请先用 list_products 选一个产品。" });
+            return jsonText({
+                ok: false,
+                code: "FULL_MODE_ONLY",
+                userHint: "想词委员会只用于已登录且已有产品的完整模式。新用户或试用扫描不要先建产品；请让用户给产品/服务名称和 1-3 个搜索词，然后直接调用 search_keyword_for_leads，传 productName/productDescription。",
+            });
         }
         try {
             let current = await (0, ppxc_client_1.getCommitteeKeywords)(productId);
@@ -777,7 +1005,7 @@ function createMcpServer() {
                 return jsonText({
                     ok: false,
                     code: "PPXC_LOGIN_REQUIRED",
-                    userHint: "OPC 账号未登录或登录失效，请先用 check_status_and_login（action=login_ppxc）登录。",
+                    userHint: "想词委员会需要 OPC 登录和已保存产品。若用户只是试用找客户，不要在这里卡住；请改为收集 productName/productDescription 和搜索词，直接调用 search_keyword_for_leads。只有用户明确要用已保存产品时，再登录 OPC。",
                 });
             }
             if (err instanceof ppxc_client_1.PpxcApiError && err.status === 403) {

package/package.json

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

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

@@ -15,6 +15,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 - 不要把它叫成「PPXC 后台」「PPXC 后端」「本机后台」。用户不需要、也不能自己启动一个 PPXC 后台。
 - MCP 工具不可用时，判断为「连接器没有启用 / MCP 配置没有生效 / 宿主还没重启」，不要说「后台没起来」。
 - 不要一上来要求用户登录 OPC。先让用户看到试用结果：用产品/服务描述 + 平台链接或关键词跑一次，展示前 2 条客户线索；用户要保存、看完整名单或解锁更多时，再引导登录 OPC。
+- **已登录不等于要走产品列表。** 即使 `check_status_and_login` 显示 OPC 已登录、`list_products` 能列出旧产品，也不要自动使用旧产品；用户只是“测试一下 / 找客户 / 扫描评论”时，仍然先按试用路径收产品/服务描述并直接搜索。只有用户明确说「用我保存的产品」「查客户池」「保存完整名单」「继续跟进历史客户」时，才进入产品列表/客户池路径。
 
 ## 第 0 步：自检与自动接线（工具不可用时才走）
 
@@ -66,6 +67,13 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 
 不要一上来调 `check_status_and_login(action=login_ppxc)`，也不要先调 `list_products`。OPC 登录只在用户要看剩余线索、保存完整名单或查询客户池时发生。
 
+禁止路径：
+
+- 不要因为用户说“测试一下”就先登录 OPC。
+- 不要因为用户已经登录就自动调用 `list_products`。
+- 不要因为没有产品列表就要求用户注册、建产品或补后台资料。
+- 不要为了调用 `suggest_search_keywords` 去要求 productId；试用阶段先用朴素搜索词跑出结果。
+
 ### 第 2 步：平台登录只在抓评论需要时处理
 
 试用扫描也需要借用户自己的平台登录态抓公开评论，但这不是 OPC 登录：
@@ -80,7 +88,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 优先让用户先看到结果：
 
 - 未登录或用户只是试试看 → 不调 `list_products`。请用户给一句产品/服务描述，至少要有 `productName`，能补 `productDescription / sellingPoints / targetPersona` 更好。
-- 已登录且用户明确要用已保存产品 → 调 `list_products`。只有一个产品直接用；有多个时把名字列给用户选，**不要替用户猜**。
+- 已登录且用户明确要用已保存产品/客户池 → 调 `list_products`。只有一个产品直接用；有多个时把名字列给用户选，**不要替用户猜**。
 
 ### 第 4 步：先要词，再开搜
 
@@ -98,7 +106,7 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 - 已登录完整模式：传 `keywords + productId + platform`，结果会落客户池。
 - 未登录试用模式：传 `keywords + productName/productDescription + platform`，结果只展示前 2 条线索，不落客户池。
 
-开搜前告诉用户：这一步要 2~3 分钟，会在后台用隐藏窗口干活。
+开搜前告诉用户：这一步要 2~3 分钟，会在后台用隐藏窗口干活。新版 MCP 会持续把进度事件发给智能体；如果宿主展示这些通知，要把“正在搜哪个词、打开了哪个链接、读到多少评论、哪条失败了”按事实转述给用户，不要只说“还在跑”。
 
 如果用户给的是具体的视频/笔记链接，跳过想词和搜索，直接调 `analyze_video_comments`：
 
@@ -110,11 +118,12 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 按这个顺序说，不要把原始 JSON 念出来：
 
 1. **一句总结**：直接用返回里的 `summary.verdict`（已含首推客户及理由）。
-2. **前 5 名**：每人一行——昵称、意向、需求类型、一句评论原话。
-3. **战报文件**：如果返回里有 `reportFile`，务必告诉用户「完整战报（含可复制的跟进话术）已放到桌面：文件路径」，提醒可以转发给同事照着跟进。
-4. **下一步提示**：提醒完整名单和历史记录在 OPC 网页端客户池。
-5. **转化动作（重要）**：如果返回里 `paywall.locked` 为真，说明已经先给用户看到了前几个完整客户。要**如实、不啰嗦**地转达：「这次挖到 N 个，先给你看前 2 个完整线索（含话术和主页入口），其余 X 个已锁。登录/开通后可以保存到客户池并解锁完整名单」。用 `paywall.unlockHint` 的话术，别夸大、别假装全给了。
-6. **登录时机**：用户说「看剩下的」「保存」「查客户池」「继续跟进」时，再调 `check_status_and_login`，参数 `action=login_ppxc`，让他登录 OPC。不要在试用扫描前做这一步。
+2. **过程透明**：如果返回里有 `processNarrative`，必须先用 2~5 行转述：搜了哪些词、实际看了哪些链接、每条读了多少评论、总共分析多少评论。不要用“应该/可能/还在跑”这种猜测词；只说工具返回的事实。需要更细时读取 `workflowTrace.keywords[].contents[]`。
+3. **前 5 名**：每人一行——昵称、意向、需求类型、一句评论原话。
+4. **战报文件**：如果返回里有 `reportFile`，只能把它说成「本机临时战报备份」，可用于转发同事照着跟进；不要把它说成解锁入口，也不要让用户误以为本地 HTML 能解锁全部客户。
+5. **下一步提示**：提醒完整名单、历史记录、解锁和保存动作在 OPC 网页端客户池完成。
+6. **转化动作（重要）**：如果返回里 `paywall.locked` 为真，说明已经先给用户看到了前几个完整客户。要**如实、不啰嗦**地转达：「这次挖到 N 个，先给你看前 2 个完整线索（含话术和主页入口），其余 X 个已锁。登录/开通后可以保存到客户池并解锁完整名单」。用 `paywall.unlockHint` 的话术，别夸大、别假装全给了。
+7. **登录时机**：用户说「看剩下的」「保存」「查客户池」「继续跟进」时，再调 `check_status_and_login`，参数 `action=login_ppxc`，让他登录 OPC。不要在试用扫描前做这一步。
 
 ### 第 6.1 步：收集用户判断（持续学习的关键）
 
@@ -190,4 +199,4 @@ description: OPC 评论线索雷达：找客户、销售线索、评论分析、
 > 2. Momo（高意向 · 竞品不满）：“用了某大牌的防晒整张脸闷痘……”
 > 3. ……
 >
-> 完整战报已放到你桌面（含每个人的跟进话术，可直接复制）：OPC客户战报-xxxx.html，可以转给同事照着跟进。全部 12 人已存入 OPC 客户池，网页端随时可看。
+> 本机临时战报备份已放到你桌面（含可复制话术）：OPC客户战报-xxxx.html，可以转给同事照着跟进。完整名单、解锁和历史记录在 OPC 网页端客户池里看。