导读

SE Ranking 扩展是 claude-seo 中负责AI 可见性（AI Visibility）实时追踪的独立技能（skill），它通过 SE Ranking 的 REST API，在单次查询内同时采样 ChatGPT、Gemini、Perplexity、Google AI Overviews 与 Google AI Mode 五个 AI 平台对指定品牌/关键词的提及情况，输出每个平台的 Share-of-Voice（声量份额）百分比。读完本文，你将掌握该扩展的安装前置条件、四个核心命令的路由方式、五个 SOV 输出字段的评分语义、基于 unit 计价的成本护栏，以及它与 seo-geo、seo-profound、seo-backlinks 等技能之间的协作边界，并深入到 claude-seo 仓库源码层面理解安装器的原子写入实现。

一、扩展定位：为什么 SE Ranking 是 v2 缺口分析中的高优先级扩展

在 claude-seo 的 25 个子技能 + 18 个子代理体系中，绝大多数技能围绕传统搜索引擎优化（SERP、技术 SEO、内容 E-E-A-T、Schema、外链）展开。而 SE Ranking 扩展承载了一个独特能力：在一套 API 表面覆盖全部 5 个主流 AI 问答平台。

这一点在 扩展安装脚本 的注释中被明确为选型依据：claude-seo 的 v2 gap analysis（能力缺口分析）认为，没有任何其他供应商能用单个 MCP/API 接口覆盖全部 5 个 AI 平台，因此该扩展被评为"影响力最高的新扩展"。它与 seo-profound（按需采样）不同，也和 DataForSEO 的 AI 优化工具（ai_optimization_chat_gpt_scraper、ai_opt_llm_ment_search 等）形成互补，但覆盖的平台集合最完整。

需要强调的是，SE Ranking 扩展不是通过/seo seranking之外的总控命令调度的。根据 seo 主技能 的说明，SE Ranking 与 Ahrefs、Bing、Profound、Unlighthouse 一样，安装为独立技能，由模型依据其 description 自动路由触发，而非通过/seo <name>子命令调用——这与 firecrawl、dataforseo、image-gen 三个扩展镜像（可经由/seo子命令访问）的接入方式不同。

二、安装前置条件

安装前需满足以下三个条件：

1. 运行安装器：Linux/macOS 执行extensions/seranking/install.sh，Windows 执行extensions/seranking/install.ps1。
2. 持有 SE Ranking API key：从 SE Ranking API 控制台获取。
3. 验证环境变量：在发起任何调用前，确认~/.claude/settings.json的env字段中存在SERANKING_API_KEY；若缺失，应提示用户重新运行安装器。

其中第 3 条是技能 SKILL.md 的硬性前置校验：Agent 不能默认 key 已配置，必须先检查再调用。

2.1 安装器的完整行为

阅读 install.sh 源码（约 50 行）可以发现，它在一次执行中完成了四件事：

1. 依赖与环境检查：set -euo pipefail严格模式；检查python3是否存在；检查基础插件~/.claude/skills/seo目录是否存在（不存在则报错退出，避免在未安装 claude-seo 基础插件时单独安装扩展）。
2. 隐藏式 API key 输入：使用read -rsp以不回显方式读取密钥，空输入直接退出。
3. 技能文件复制：将skills/seo-seranking/SKILL.md复制到~/.claude/skills/seo-seranking/SKILL.md，使技能对 Claude Code 可见。
4. 密钥的原子化写入：通过内嵌 Python 片段，把env.SERANKING_API_KEY写入~/.claude/settings.json。其关键实现是：

data.setdefault("env", {})["SERANKING_API_KEY"] = key fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path) or ".", prefix=".settings.", suffix=".json") with os.fdopen(fd, "w") as fh: json.dump(data, fh, indent=2) os.chmod(tmp, 0o600) os.replace(tmp, path)

这段代码体现了三个安全细节：

• 临时文件 +os.replace原子替换：先写入同目录下的临时文件（前缀.settings.），再原子替换目标文件。即使中途失败，也不会产生半个写坏的 settings.json；
• 文件权限 0o600：settings 文件仅允许当前用户读写，避免密钥被其他用户读取；
• 保留既有配置：先json.load已存在的文件（解析失败则回退为空 dict），再用setdefault("env", {})合并，只新增/覆盖SERANKING_API_KEY这一个键，不触碰其他 settings 内容。Windows 版 install.ps1 使用Read-Host -AsSecureString读取密钥并复用同一套 Python 合并逻辑，行为一致。

2.2 验证安装

安装完成后，可按 SERANKING-SETUP.md 的验证步骤执行：

/seo seranking ai-visibility "Claude SEO"

预期输出为按平台区分的百分比（ChatGPT、Gemini、Perplexity、AI Overviews、AI Mode），并附带基于采样量的置信度说明。

2.3 密钥轮换与卸载

• 轮换密钥：直接重新运行安装器即可。由于写入逻辑是"临时文件 +os.replace原子替换"，新 key 会覆盖旧值且不会触碰 settings.json 中的其他配置。
• 卸载：执行extensions/seranking/uninstall.sh。从 uninstall.sh 源码可见，它做了两件事：删除~/.claude/skills/seo-seranking/技能目录；用同样的 tempfile + replace 机制从~/.claude/settings.json的env中移除SERANKING_API_KEY（仅移除该键，保留其他设置）。注意：当前扩展目录下没有提供 uninstall.ps1，Windows 用户需要手动删除技能目录并从 settings.json 中移除对应键。

三、命令路由：四个核心调用

技能定义了一张路由表，将四个高频场景映射到对应命令：

其中ai-visibility是 SE Ranking 扩展的核心命令，也是下文评分的焦点；serp、backlinks、competitors三个命令则复用 SE Ranking 的传统 SEO 数据能力，在 DataForSEO / Ahrefs 等付费数据不可用时，可作为免费档的备选数据源。

四、AI Share-of-Voice 评分机制与五个输出字段

SE Ranking 的 AI 可见性评分流程是：针对可配置的提示词集（prompt set），分别向每个 AI 平台发起采样查询，统计品牌在响应中被提及的比例。技能文档特别指出，该评分逻辑与 Profound / Peec AI 使用的逻辑相同，但被捆绑进单一 MCP/API 接口，省去了多供应商集成的成本。

一次ai-visibility查询返回五个字段，全部以百分比呈现：

4.1 报告规范：百分比 + 置信度

技能文档要求，每个 SOV 字段都必须同时给出百分比与基于采样量的置信度说明。这是一条不可省略的报告纪律：SOV 本质上是抽样统计量，样本量小则置信度低。在实际汇报中应避免孤立地报一个百分比，而是类似"ChatGPT 声量 42%（基于 50 条采样提示词）"这样带边界的表述。

4.2 与 seo-geo 的评分语境呼应

理解这五个字段的行业语境，可以对照 seo-geo 技能 中引用的研究结论：品牌提及（brand mentions）与 AI 引用（AI citations）的相关性（约 3 倍于外链），且 YouTube/Reddit/Wikipedia 提及是最强信号；同时只有约 11% 的域名能同时被 ChatGPT 与 Google AI Overviews 针对同一查询引用，跨平台声量差异是常态而非异常。因此chatgpt_sov、ai_overviews_sov、ai_mode_sov之间出现明显分差是完全正常的，恰恰说明了需要逐平台优化（参见第六节的跨技能协作）。

另外注意，Google 的 AI Overviews 与 AI Mode 是两个独立的引用引擎：二者约 86% 的查询结论一致，但引用的 URL 仅约 13.7% 重合。SE Ranking 将两者拆成两个独立字段，正是为了分别打分、避免用一个笼统的"AI 可见性"掩盖两个表面的差异。

五、成本护栏：unit 计价与跨供应商记账

SE Ranking API 采用unit（单元）计价，成本与调用量直接挂钩。关键成本事实：

• 单次 AI 可见性查询约消耗5 units（每个平台 1 unit）；
• 定价按 unit 计费，具体费率以 SE Ranking 官网定价为准。

技能文档要求：使用 dataforseo_costs.py 跨供应商记录花费。虽然脚本名带有 dataforseo 字样，但它的定位是通用的 API 成本台账——阅读源码可见其记账链路与供应商无关：

• 配置与账本文件分别位于~/.config/claude-seo/dataforseo-costs.json与~/.config/claude-seo/dataforseo-ledger.json；
• 核心子命令：estimate <endpoint> [--count N]（估算单次调用成本）、check <endpoint> [--count N]（阈值/日限额审批）、log <endpoint> <cost> [--note TEXT]（记录已发生的花费）、summary [--days N]、today、config、reset --confirm；
• 默认配置为mode: threshold（阈值模式，单次调用超过 $0.50 需审批）、daily_limit: $10.00（每日上限）、内置warn_endpoints清单（如ai_optimization_chat_gpt_scraper、ai_opt_llm_ment_search等 AI 相关端点始终要求确认）；
• 账本读写使用fcntl文件锁（Windows 下回退为不加锁），并在reset时写入不可删除的_audit_reset审计条目。

也就是说，你可以用log seranking_ai_visibility 5 --note "ai-visibility query"之类的形式，把 SE Ranking 的 unit 消耗统一记入同一本账，从而在一个工具里看到所有付费数据源的总花费与每日配额。

六、跨技能协作边界

技能文档明确了三条协作路由，避免与其他技能职责重叠：

1. 传统外链 + 内容审计：回退到 seo-backlinks 与 seo-content。SE Ranking 的backlinks命令提供的是快速画像，深度审计（锚文本、毒性链接、DA/PA 维度）应交给专门的外链技能。
2. 单平台深挖：如果只需要 ChatGPT 或 Perplexity 单平台的深度分析，优先使用 seo-geo——它包含 Brand Mention Correlation 指导（品牌提及相关性分析），并覆盖平台特定的引用来源（如 ChatGPT 主要引用 Wikipedia/Reddit，Perplexity 高度依赖 Reddit 讨论）与 AI 爬虫可访问性、llms.txt、RSL 许可等维度。
3. 趋势对比：若需要时间序列而非按需采样，可以联动 seo-profound。Profound 持续轮询并发布周环比/月环比的趋势数据，而 SE Ranking 是按需采样——两者可形成三角验证：SE Ranking 负责五个平台的横截面声量，Profound 负责 ChatGPT/Perplexity 的纵向趋势，DataForSEO 的 AI 工具（如可用）再做交叉验证。

七、使用建议与限制说明

基于以上实现细节，给出几条实操建议：

• 先验证 key 再调用：技能内置了"调用前必须检查env.SERANKING_API_KEY"的规则，这是防止无效 API 调用的第一道闸门。
• 汇报 SOV 必带置信度：所有百分比都必须附上采样量说明，这是技能文档的硬性报告规范。
• 把成本记账当作流程的一部分：由于 AI 可见性查询按 unit 计费（约 5 units/次），在审计类工作流中应主动用 dataforseo_costs.py 的log/check命令管控跨供应商花费，避免失控。
• 理解适用范围：SE Ranking 扩展需要独立的 SE Ranking API 订阅，其数据口径（采样提示词集、平台版本、AI Mode 的语言范围）以 SE Ranking 服务端为准；本仓库不包含调用 SE Ranking REST API 的客户端源码，五个 SOV 字段的取值语义以 SKILL.md 与官方 API 文档为准。
• 按需卸载：确认不再使用后运行extensions/seranking/uninstall.sh，它会同时清理技能目录与环境变量（Windows 端当前无对应卸载脚本，需手动清理）。

整体来看，SE Ranking 扩展在 claude-seo 中扮演的是"AI 声量仪表盘"角色：它以最少的集成成本覆盖五个 AI 平台，用统一的 SOV 指标回答"AI 搜索中用户是否能看到我们"，并通过成本台账与跨技能路由，把这一指标有机地并入现有的技术 SEO、GEO 与外链分析工作流。