SERP 域名排名追踪器 (SERP Domain Rank Tracker)
一键查清「某个域名」在「某个关键词」下，于各大搜索引擎排第几，并生成可交付的对比报告。
1. 触发词（命中即启用本 Skill）
- 中英文均可：
排名/ranking/排名查询/serp/搜索引擎排名/关键词排名/域名排名/rank tracker/seo 排名 - 典型用户指令示例：
- "查一下 temu.com 在关键词 temu 下 Google、Bing、DuckDuckGo 的排名"
- "帮我出一份 shein.com 在 'cheap clothing' 这个词上的全球搜索引擎排名报告"
- "对比一下 a.com 和 b.com 在百度、360、搜狗对 '在线教育' 的排名"
2. 输入参数
| 参数 | 必填 | 说明 | 示例 |
|---|---|---|---|
domain |
✅ | 要追踪的域名（不含 http / 末尾斜杠） | temu.com |
keyword |
✅ | 要查询的关键词（可含空格） | temu / cheap online shopping |
scope |
❌ | global（默认）/ cn / all |
global |
scope=global：Google, Bing(INT), DuckDuckGo, Yahoo, Yandex, Ecosia, Startpage, Brave, Mojeekscope=cn：百度, Bing(CN), 360, 搜狗, 微信, 头条scope=all：以上全部（默认行为之外的显式全集）
> 支持一次查多个域名 / 多个关键词：循环执行下方流程即可，报告按「域名 × 关键词」分行呈现。
3. 搜索引擎清单（URL 模板）
全球主流（global）
| 引擎 | 搜索 URL 模板 | 索引来源 | 直连可行性 |
|---|---|---|---|
https://www.google.com/search?q={KW}&num=10 |
自有 | 常被反爬拦截 → 推断 | |
| Bing(INT) | https://cn.bing.com/search?q={KW}&ensearch=1 |
自有 | ✅ 通常可直连 |
| DuckDuckGo | https://html.duckduckgo.com/html/?q={KW} |
Bing 提供 | 常被反爬拦截 → 推断（同 Bing） |
| Yahoo | https://search.yahoo.com/search?p={KW} |
Bing 提供 | 常被反爬拦截 → 推断（同 Bing） |
| Yandex | https://yandex.com/search/?text={KW}&numdoc=10 |
自有（俄） | ✅ 通常可直连 |
| Ecosia | https://www.ecosia.org/search?q={KW} |
Bing 提供 | ✅ 通常可直连（注意：非浏览器请求常被重定向到 Bing，需识别重定向并降级同源推断） |
| Startpage | https://www.startpage.com/sp/search?query={KW} |
Google 提供 | 常被反爬拦截 → 推断（同 Google） |
| Brave | https://search.brave.com/search?q={KW} |
独立索引 | 常被反爬拦截 → 推断 |
| Mojeek | https://www.mojeek.com/search?q={KW} |
独立索引 | 常 403 → 推断 |
国内（cn）
| 引擎 | 搜索 URL 模板 | 索引来源 | 直连可行性 |
|---|---|---|---|
| 百度 | https://www.baidu.com/s?wd={KW} |
自有 | ✅（但结果多为聚合卡） |
| Bing(CN) | https://cn.bing.com/search?q={KW}&ensearch=0 |
自有 | ✅ |
| 360 | https://www.so.com/s?q={KW} |
自有 | ⚠️ 结果 URL 被跳转封装 |
| 搜狗 | https://sogou.com/web?query={KW} |
自有 | ⚠️ 首条多为百科卡 |
| 微信 | https://wx.sogou.com/weixin?type=2&query={KW} |
公众号 | ❌ 不返回网站外链 |
| 头条 | https://so.toutiao.com/search?keyword={KW} |
抖音系 | ⚠️ 仅自有生态内容 |
> 注：微信 / 头条 / 集思录 / WolframAlpha 这类「非网站域名排名型」引擎不会把目标域名作为结果返回，报告中应标注为「不适用 / 不出现」而非给假排名。
4. 查询流程（逐步执行）
Step 1 · 解析输入
确认 domain、keyword、scope。若用户未指定 scope，默认 global。对 keyword 做 URL 编码后填入各引擎 URL 模板。
> API 模式开关：若检测到环境变量 SERP_API_KEY（配合 SERP_API_PROVIDER 指定 serpapi / serper / serpstack / brightdata），则启用 4.5 章的 API 直连增强模式，目标引擎直接返回 ✅ 直连验证结果；未设置则走免费模式（Step 2-4）。
Step 2 · 逐引擎抓取
对每个引擎，调用 WebFetch 抓取搜索页，使用下方「解析 Prompt 模板」：
> 解析 Prompt 模板（把 {ENGINE} {KEYWORD} {DOMAIN} 替换后传给 WebFetch 的 prompt 参数）：
> > 这是搜索引擎 "{ENGINE}" 对关键词 "{KEYWORD}" 的搜索结果页。
> 任务：找出自然结果中 URL 包含 "{DOMAIN}"（例如 www.{DOMAIN} 或其子域）的结果排第几。
> 请：
> 1. 按 1-based 顺序列出前 10 条结果的标题与 URL；
> 2. 明确说明 "{DOMAIN}" 首次出现在第几位；若前 10 条未出现，写明「前 10 名未出现」；
> 3. 若页面不是搜索结果页（反爬验证页 / 登录页 / 错误页 / 空白 / 被重定向到其它域名），直接说明「非搜索结果页 / 重定向到 {重定向目标}」。
> 只返回结构化结论。
>
Step 3 · 失败兜底（关键）
若某引擎 WebFetch 返回 fetch failed / 403 / 「非搜索结果页」 / 重定向到非目标域，按下列规则处理，不要卡死、不要造假：
- 同索引来源推断：DDG / Yahoo / Ecosia 失败 → 直接采用已成功抓取的 Bing 结论（它们由 Bing 驱动，品牌词排名一致）；Startpage 失败 → 采用 Google 结论。
- WebSearch 兜底：对 Google / Brave / Mojeek 等独立索引，调用 WebSearch(query="{KEYWORD}")，查看返回结果首条是否含
{DOMAIN}：
- 首条命中 → 记为#1（标注「WebSearch 推断」）；
- 首条未命中但后续出现 → 记为「前 N 含」（N 为出现位置，标注推断）；
- 完全未出现 → 记为「前 10 未出现 / 推断」。
> 重要：WebSearch 的返回结果不等于 Google 真实索引（实测首条常为百度百科等第三方页面）。因此 WebSearch 兜底仅作「品牌词是否在前排」的弱信号，置信度一律标 ⚠️，且备注须注明「WebSearch 非 Google 真实索引」。 - 仍失败 → 该引擎记为
N/A，置信度无法获取，备注写明原因（如「沙箱出口被反爬拦截」）。
Step 4 · 标注可信度
每个引擎结果必须带一个 confidence 字段：
- verified ✅ 直连 SERP 抓取验证（或 API 直连，见 4.5）
- inferred ⚠️ 基于索引来源归属 / WebSearch 交叉推断
- na ❌ 无法获取（标注原因）
Step 5 · 生成报告
- 用 Read 读取本 Skill 目录下的
assets/report_template.html。 - 把模板中的占位符替换为本次数据：
-{{DOMAIN}}{{KEYWORD}}{{GENERATED_AT}}
-{{BEST_RANK}}（最佳排名，如#1）、{{AVG_RANK}}（平均排名，仅统计 verified+inferred）、{{VERIFIED_COUNT}}{{TOTAL_COUNT}}
-{{TABLE_ROWS}}：每个引擎一行<tr>...（见下方行模板）
-{{BAR_ROWS}}：每个引擎一条条形<div class="bar-row">...（宽度 =max(6, (11-rank)/10*100)%，N/A 用灰色窄条） - 将填充后的完整 HTML 写入工作区：
{domain}_{keyword}_ranking_{YYYYMMDD_HHMM}.html
（时间戳用当前时间，例如temu_temu_ranking_20260914_0005.html） - 调用 present_files 打开该 HTML 供用户预览。
> 表格行模板（复制后填值）：
> html
> <tr>
> <td>Google</td>
> <td><span class="rank-badge">#1</span></td>
> <td><span class="conf conf-verified">✅ 直连验证</span></td>
> <td>自有索引</td>
> <td>WebSearch 交叉验证</td>
> </tr>
>
> 置信度 class：conf-verified / conf-inferred / conf-na；排名文本：#1…#10 或 N/A。
4.5 API 直连增强模式（v1.1.0 新增）
当用户环境提供 SERP API Key 时，本 Skill 可绕过免费模式的「反爬 / 直连失败」限制，将 Google / Brave / Mojeek 等引擎的「⚠️ 索引推断」升级为「✅ 直连验证」（备注标注 API:<provider>）。
启用检测（Step 1 后）：读取环境变量 SERP_API_KEY；若为空 → 走免费模式。读取 SERP_API_PROVIDER，取值 serpapi | serper | serpstack | brightdata（默认 serpapi）。
支持的 Provider：
| Provider | 端点 | 鉴权方式 |
|---|---|---|
| SerpApi | https://serpapi.com/search.json?engine=google&q={KW}&api_key={KEY} |
查询参数 api_key |
| Serper.dev | https://google.serper.dev/search (POST, body {"q":"{KW}"}) |
Header X-API-KEY: {KEY} |
| Serpstack | https://api.serpstack.com/search?access_key={KEY}&query={KW} |
查询参数 access_key |
| Bright Data | https://serpapi.brightdata.com/serp/search?engine=google&q={KW} |
Header Authorization: Bearer {KEY} |
解析规则：API 返回的 organic_results（或等价字段）数组中，首个 link 含 {DOMAIN} 的下标 +1 即排名；标注 confidence=verified，备注写 API:<provider> 直连。
失败降级：API 调用报错（Key 无效 / 额度耗尽 / 网络错误）时，立即回退到该引擎的免费模式逻辑（同源推断 / WebSearch / 标 N/A），备注标注「API 失败，已降级」。
> 实测：本环境沙箱出口已验证连通 serpapi / serpstack / brightdata（HTTP 200）及 serper（可达），填入 Key 后可在本环境真实跑通。
5. 数据口径与局限（必须写入报告）
在报告末尾固定输出以下说明，避免客户误读：
- 排名为动态快照：受地域、语言、登录状态、个性化影响，不同时间 / 地点结果会有差异。
- 可信度分级透明：✅ 直连抓取 SERP（或 API 直连）；⚠️ 索引推断（同源或 WebSearch 交叉）；❌ 无法获取。
- 品牌词必然霸屏：若
keyword就是domain的主体（如temuvstemu.com），官网几乎必然 #1，此结果无 SEO 诊断价值；真正有看点的是品类词（"cheap online shopping"）与竞品对比词（"temu vs shein"）。 - 精确 SERP 序号 / 历史曲线 / 批量监控：需接入专业 SERP API（Ahrefs / Semrush / Bright Data），本 Skill 基于免费公开页，适合快速诊断与交付，不适合规模化监控；v1.1.0 起内置 API 直连增强模式（见 4.5）。
6. 错误处理
| 现象 | 原因 | 处理 |
|---|---|---|
WebFetch fetch failed |
沙箱出口被目标站拦截 | 走 Step 3 兜底（同源推断 / WebSearch / 标 N/A） |
WebFetch 403 |
目标站反爬 | 同上 |
| 页面返回反爬验证页 | 需要 JS / 验证码 | 标 na，备注原因 |
| 被重定向到其它域名（如 Ecosia→Bing） | 引擎对非浏览器请求做重定向 | 识别后降级为同源推断（Ecosia→Bing），不再重试直连 |
| 结果 URL 被跳转封装（360 / 搜狗） | 引擎对结果做跳转 | 解析跳转后的真实域名；若无法解析，标注「大致前排（推断）」 |
| 用户未给 domain 或 keyword | 输入缺失 | 用 AskUserQuestion 补全，不要凭空假设 |
7. 发布到 SkillHub 上架指南（给作者）
本 Skill 已按 SkillHub 规范编写 SKILL.md（含 frontmatter：slug / name / version / displayName / summary / license / description / tags / tools / pricing_tier / pricing_model / suggested_price）。
上架步骤（需在 SkillHub 平台后台操作，本环境无发布接口）：
1. 打包本目录（serp-rank-tracker/ 含 SKILL.md 与 assets/report_template.html）。
2. 在 SkillHub 后台创建新 Skill，上传该目录；slug 建议保持 serp-rank-tracker。
3. 定价：frontmatter 已设 suggested_price: 19.9（per_use，L1）。可按平台档位微调；若强调「免 Key 即用 + 填 Key 升级全直连验证」卖点，可上探至 29.9~49.9。
4. 卖点文案要点：
- 「不用写代码、不用买 API，一句话查清域名在各搜索引擎的排名」
- 「带可信度评级，敢对客户透明，不像野鸡工具瞎编序号」
- 「自动出可交付 HTML 报告，接单即交付」
- 「免 Key 即用；填入 SERP API Key 后升级为 100% 直连验证报告」
5. 合规提示：排名数据来自公开搜索页，属合理使用；若做商业化批量监控，请改用合规 SERP API 并遵守各引擎 ToS。
8. 升级路线（可作为付费增值点）
- v1.1 定时监控：接入
automation_update，每日自动跑排名并 diff 变化，推送到邮箱 / 微信。 - v1.2 历史曲线：把每次结果落库（CSV / SQLite），自动画趋势图。
- v1.3 精确前 100 明细：API 模式下请求
num=100，输出完整排名分布。
> 注：4.5 章的 SERP API 直连增强模式（即原计划的「SERP API 模式」）已在 v1.1.0 正式纳入；填入 Key 可将 Google / Brave / Mojeek 等从「⚠️ 索引推断」升级为「✅ 直连验证」。
