本地优先、零依赖的 SERP 与关键词情报分析引擎
Local-first, zero-dependency SERP & keyword intelligence engine
SERPulse（搜索脉搏） 是一款完全运行在你本机的搜索结果情报分析工具。它不爬取搜索引擎、不依赖任何后端服务、零第三方运行时依赖，只分析你已经拥有的数据——Google Search Console、必应站长平台或任意排名工具导出的 CSV/JSON 文件，把它们转化为可执行的 SEO 决策：排名涨跌追踪、关键词主题聚类、搜索可见度（Visibility / Share-of-Voice）测算、竞品格局对比、内容缺口挖掘，以及一份单文件、可离线打开的可视化 HTML 报告。
- 💸 付费 SEO 套件太贵：Semrush、Ahrefs 等订阅价格高昂，且大量功能其实是"把你的导出文件算一遍"；
- 🔒 数据锁定与隐私焦虑：把关键词与排名数据上传到第三方 SaaS 存在合规与泄露风险；
- 🧩 导出文件散落各处：GSC、排名工具、自研脚本产出的 CSV 格式各不相同，手工合并极其耗时；
- 📉 只看单天排名没有方向感：缺少跨快照趋势、可见度评分与"第二页快速赢点"这类可执行视角。
| 维度 | 传统在线 SEO 套件 | SERPulse |
|---|---|---|
| 数据位置 | 数据上传云端 | 数据不出本机，完全离线 |
| 运行依赖 | 账号、订阅、网络、浏览器 | Python 标准库，0 依赖 |
| 数据接入 | 绑定平台授权 | 任意 CSV/JSON，中英文表头自动识别 |
| 结果形态 | 在线看板（不可归档） | 终端表格 + JSON + 单文件 HTML |
| 确定性 | 云端黑盒算法 | 同输入永远同输出，可复算、可审计 |
| 跨平台 | 依赖浏览器 | Windows / macOS / Linux 一致运行 |
💡 灵感来源：本项目受 GitHub Trending 热门项目
every-app/open-seo（"开源版 Semrush/Ahrefs"）所启发，认同其"让 SEO 工具链开放化"的理念，但选择了完全不同的技术路线——不做在线抓取与账号体系，而是做一个本地优先、可复现、可嵌入自动化流水线的离线分析引擎。全部代码为独立自研，未复制任何项目源码。
- 📥 多格式数据接入：CSV / JSON 直接读取，支持 glob 批量合并；内置中英文表头别名表（
关键词/query/搜索词、排名/rank/position等自动映射），Excel 导出的 BOM、1.2K/3M量级数字均可直接解析。 - 🧩 关键词主题聚类：基于词元 Jaccard 相似度 + 并查集单链聚类，中英文混合词表通用（拉丁文按词、中日韩按字），自动产出主题簇、簇搜索量与平均排名。
- 🧭 搜索意图分类：规则化、可解释地判别信息型 / 商业型 / 交易型 / 导航型四类意图，覆盖中英文线索词，输出置信度，不依赖任何模型。
- 📈 排名快照追踪：对比任意两个快照，自动列出上涨榜、下跌榜、新增词、丢失词，支持按自有域名过滤。
- 📊 可见度 / Share-of-Voice 模型：内置行业有机点击率（CTR）衰减曲线，按搜索量加权计算 0–100 可见度分、预估月点击量与 Top3/10/20/50 排名分层分布。
- 🏟️ 竞品格局分析：逐域名汇总关键词数、平均排名、可见度、各层占位与夺魁词数；支持自有站点对任一竞品的正面对决（win/lose/tie）。
- 🎯 内容缺口与快速赢点：自动找出"竞品有排名而你没有"的缺失词（附机会点击量估算）、双方共有词的排名差，以及落在第 11–20 位的第二页快速赢点清单。
- 📝 共享修饰词挖掘（n-gram）：跨关键词聚合高频共同词元与搜索量，快速发现"价格/推荐/品牌"等内容方向。
- 🖥️ 十种 CLI 子命令：
check / cluster / intent / ngrams / visibility / track / competitors / h2h / gap / report，外加demo一键生成示例数据；所有命令同时支持终端表格与--json机器可读输出。 - 📄 自包含 HTML 报告：内联 CSS + 手写 SVG 折线/柱状图，零 JavaScript、零外部请求、无 CDN，单文件可邮件转发、可离线归档。
- 🛡️ 工程质量内建：19 个单元测试全绿；数据质量问题分级告警（error/warn）与明确退出码；类型注解齐全；MIT 协议。
- Python 3.8 及以上（3.8 / 3.9 / 3.10 / 3.11 / 3.12 均验证通过）
- 操作系统：Windows / macOS / Linux 均可
- 无需联网、无需 pip 安装任何第三方库（运行期零依赖）
检查 Python 版本：
python3 --version# 克隆后在项目根目录执行
pip install .
# 验证安装
serpulse --version# 下载/克隆项目后，在项目根目录：
python3 -m serpulse --versionWindows 上若
python3不存在，请改用python。
# 1) 生成一份内置示例数据（2 个周度快照 × 15 个中英关键词 × 4 个域名）
python3 -m serpulse demo
# 2) 校验数据是否被正确识别
python3 -m serpulse check "examples/*.csv"
# 3) 生成可视化 HTML 报告（以 acmesport.com 为自有站点）
python3 -m serpulse report "examples/*.csv" --focal acmesport.com -o report.html用浏览器打开生成的 report.html 即可，全程不需要网络。
最精简的单快照 CSV 只需要两列（表头中英文均可）：
关键词,排名,域名,搜索量
跑步鞋,4,acmesport.com,900
跑鞋推荐,12,rival.io,1200做跨时间趋势/追踪时增加日期列（也可以每个快照一个文件，用 glob 合并）：
date,keyword,domain,position,volume,url
2026-08-17,running shoes,acmesport.com,6,900,https://acmesport.com/running
2026-08-24,running shoes,acmesport.com,3,900,https://acmesport.com/running完整的字段别名表（日期/day/snapshot、链接/url/landing_page 等）见
examples/README.md。文件没有日期列时可用
--date 2026-08-24 统一指定快照日期。
| 命令 | 作用 | 典型场景 |
|---|---|---|
check |
加载校验、输出记录数/词数/域名/快照日期与数据质量问题 | 导入前体检 |
cluster |
关键词主题聚类（--threshold 调节松紧） |
梳理词表结构 |
intent |
逐词搜索意图分类 | 落地页类型规划 |
ngrams |
高频共享词元与汇总搜索量 | 挖掘内容方向 |
visibility |
各快照可见度、预估点击、词数趋势 | 周期复盘 |
track |
快照间涨跌/新增/丢失榜单 | 周报排名异动 |
competitors |
全域名格局指标 | 识别主要对手 |
h2h |
自有站 vs 指定竞品逐词对决 | 找被压制的词 |
gap |
内容缺口 + 第二页快速赢点 | 选题与优化排期 |
report |
生成自包含 HTML 报告 | 汇报/归档 |
demo |
生成示例数据集 | 快速体验 |
① 数据体检
python3 -m serpulse check "data/*.csv"② 关键词聚类（阈值越高簇越紧凑，取值 0–1）
python3 -m serpulse cluster data.csv --threshold 0.3③ 两周排名异动追踪，只看自有域名
python3 -m serpulse track "snapshots/*.csv" --focal acmesport.com --top 15④ 可见度趋势（JSON 输出，便于接入流水线）
python3 -m serpulse visibility "snapshots/*.csv" --focal acmesport.com --json⑤ 竞品全景与正面对决
python3 -m serpulse competitors "snapshots/*.csv"
python3 -m serpulse h2h "snapshots/*.csv" --focal acmesport.com --against runnerpro.io⑥ 内容缺口分析：缺失词 + 第二页快速赢点
python3 -m serpulse gap "snapshots/*.csv" --focal acmesport.com --top 20⑦ 一份完整 HTML 报告
python3 -m serpulse report "snapshots/*.csv" \
--focal acmesport.com \
--title "8月第4周 SERP 情报" \
-o reports/week35.html| 参数 | 适用命令 | 说明 |
|---|---|---|
--date YYYY-MM-DD |
全部分析命令 | 文件无日期列时的兜底快照日期 |
--focal DOMAIN |
cluster/intent/track/gap/h2h/report 等 | 指定自有站点，自动匹配子域 |
--json |
全部分析命令 | 输出机器可读 JSON，方便脚本消费 |
--force |
全部分析命令 | 存在加载级 error 时仍继续执行 |
--threshold |
cluster | Jaccard 链接阈值，默认 0.3，越高越紧凑 |
--top N |
track/h2h/gap/ngrams | 每类榜单保留条数 |
-o, --output |
report | HTML 报告输出路径 |
- 每周从 GSC / 排名工具导出 CSV，按
YYYY-MM-DD.csv命名放入snapshots/； check体检 →track看异动 →gap找机会 →report出报告；- 用
--json把指标写入你自己的看板或定时任务，实现无人值守周报。
📌 终端运行截图与 HTML 报告演示动图将随后续版本补充于此：
docs/assets/terminal-demo.png（CLI 各命令输出）docs/assets/report-demo.gif（HTML 报告交互浏览）
- 本地优先（Local-first）：关键词与排名属于敏感经营数据。SERPulse 的所有计算都在本机完成，源码中不存在任何网络请求，可在内网/离线环境长期运行。
- 零依赖即韧性：只用 Python 标准库，意味着没有供应链风险、没有版本冲突、十年后的 Python 依然能跑今天的脚本。
- 确定性可审计：不调用黑盒模型，CTR 曲线、聚类阈值、意图规则全部写在明处，同一份输入永远得到同一份输出，结论可复算。
- 数据归用户，工具归用户：不绑定任何平台授权，任何能导出 CSV 的工具都是 SERPulse 的数据源。
- Python 3.8+ 标准库：
csv/json/dataclasses/argparse/urllib足以覆盖全部需求，保证零依赖与跨平台； - 并查集 + Jaccard 聚类：O(n²) 内对千级词表瞬时完成，结果可解释、无需向量模型；
- 手写内联 SVG：报告不引入图表库与 CDN，单文件即可完整呈现折线/柱状图；
- argparse 子命令架构：每个分析能力独立可组合，
--json输出天然适配 Unix 管道与自动化。
- v1.1：支持 Excel（.xlsx）读取（以可选依赖组方式提供，核心仍零依赖）
- v1.1：自定义 CTR 曲线配置文件，适配不同行业/设备
- v1.2：Markdown 报告导出与多报告对比（周环比/月环比）
- v1.2：关键词 SERP 特征字段（精选摘要/People Also Ask/视频框）统计
- v1.3：聚类标签自动命名优化（TF 加权 + 共现修饰词）
- v1.3：交互式报告筛选（按意图/簇/排名层过滤）
- v2.0：可选本地守护进程，监听目录自动出周报
多语言意图线索词扩充、更多导出格式的别名适配、行业 CTR 曲线数据集、报告主题与无障碍（a11y）优化——欢迎先开 Issue 讨论再提 PR，规范见 CONTRIBUTING.md。
SERPulse 属于命令行工具 / 可安装库（非桌面应用），因此不提供二进制 Release，以下三种方式覆盖全部使用场景。
pip install . # 安装后获得 serpulse 命令
serpulse demo # 等价于 python -m serpulse demo# 仅构建期需要 setuptools/build；产物本身零依赖
python3 -m pip wheel . --no-deps -w dist/
# 产出 dist/serpulse-1.0.0-py3-none-any.whl，可拷贝到任意
# Windows/macOS/Linux 机器安装：
pip install dist/serpulse-1.0.0-py3-none-any.whlwheel 为
py3-none-any，与操作系统无关，一份产物全平台通用。
# 直接把项目目录放入仓库或镜像，用模块方式调用：
python3 -m serpulse report "/data/snapshots/*.csv" \
--focal example.com -o /var/reports/serp.html兼容环境：Python 3.8–3.12；Windows / macOS / Linux；无需网络、无需编译。
常见问题：Windows 下 python3 不存在时改用 python；glob 通配符在 PowerShell 中需加引号（已在示例中统一加引号）。
- 🐛 Issue：提交 Bug 请附带
serpulse --version、运行命令、最小匿名化样例数据与实际报错； - 🔀 Pull Request：从
main切出feat/xxx、fix/xxx、docs/xxx分支，提交信息遵循 Angular 规范（feat:/fix:/docs:/refactor:/test:/chore:）； - ✅ 任何行为变更必须同步增改
tests/下的测试，且python -m unittest discover -s tests全部通过； - 🚫 不接受引入第三方运行时依赖的 PR（标准库零依赖是硬性约束，开发期工具除外）；
- 🌐 改动 CLI 或数据格式时，请同步更新三个语言版本的 README。
完整规范请阅读 CONTRIBUTING.md。
本项目基于 MIT License 开源，允许自由使用、修改、分发与商用，保留版权声明即可。SERPulse 不收集任何数据，亦不提供任何形式的担保。
如果 SERPulse 帮你省下了一笔订阅费，欢迎给个 ⭐ 让更多人看到它。
Made with 🐍 by gitstq · Local-first · Zero-dependency · MIT