COMPETITOR_KEYWORDS
2026-10-03 更新:当前六语言/七市场研究与定时自反馈见 SEO_SIX_LOCALES.md 和 SEO_FEEDBACK_RUNBOOK.md;最新竞品产物为
sample-run-v4。以下保留首版研究的口径与历史记录,旧连接失败/未定时状态不能代替当前验收。
竞品关键词研究:本机导入与复核
Section titled “竞品关键词研究:本机导入与复核”本工具与 collect-web-growth.mjs 并列,负责竞品样本导入、主题汇总和证据校验。
它没有网络请求、账号登录、付费 API、定时任务或页面发布功能。免费报表由操作人
读取或导出;遇到升级、试用、付款入口停止。GA/GSC 的采集与权限继续使用原入口。
首批范围与状态
Section titled “首批范围与状态”研究市场固定为美国英语(US/en/Google)和台湾繁中(TW/zh-TW/Google),这是用户
选择的研究范围,不是已证明最优的增长市场。8 站配置在
data/competitor-keywords/competitors.json。英文页面使用默认语言无前缀路径,
不能将 /en/news 当作目标页面。
首批原始材料在 data/competitor-keywords/:
public-samples.json:Similarweb 公开估算词,保留原词与数据月。page-candidates.json:官方页面功能和表达推导的词,不是观测搜索词。account-access.json:账号读取状态与缺口,无报表行不表示零需求。research-input.json:合并输入,补上人工排除状态,不覆盖原始样本。production-page-evidence.json:7 个线上公开入口的 HTTP/SSR 标题、H1、description。own-web-context.json:本机已有 GA/GSC 快照状态;本任务没有刷新其 API。candidate-opportunities.json:人工审核的任务、中文含义、目标页面和待验证优先级。competitor-matrix.csv:8 站预定研究市场与实际采集口径并列。classification-review.json:人工主题分类复核,原始公开样本保持不变。
当前公开词为 worldwide/desktop,Google 引擎和 US/TW 筛选未核实。不同月份分别 计算;不能将公开全球样本改标为美国或台湾数据。详细实际覆盖见快照报告。
从 /Users/cc/Documents/root-remote/product/YomiyaProductAnalytics/engineering/yomiya-service-analytics
运行,要求 Node 22+,无需安装依赖:
node scripts/competitor-keywords.mjs import \ --input data/competitor-keywords/research-input.json \ --out reports/competitor-keywords/2026-10-03-v3node scripts/competitor-keywords.mjs validate --run reports/competitor-keywords/2026-10-03-v3node scripts/competitor-keywords.mjs report --run reports/competitor-keywords/2026-10-03-v3node --test scripts/lib/competitor-keywords.test.mjs已验收快照为 data/competitor-keywords/sample-run-v3;上面的示例为下次新输出目录。
重跑导入时须换一个新的输出目录。
工具拒绝覆盖已存在的目录。report 校验已有产物后输出到终端,不重写快照。
工程校验通过不等于地区需求数据齐全;查看 analytical_status 和来源覆盖。
CSV 输入
Section titled “CSV 输入”node scripts/competitor-keywords.mjs import \ --input /absolute/path/semrush-free-export.csv \ --meta /absolute/path/semrush-free-export.meta.json \ --out reports/competitor-keywords/new-runCSV 支持 Semrush 的 Keyword、Position、Volume、Traffic、URL、Intent
及工具的标准列名。JSON 旁路元数据必须指明实际条件;元数据模版在
data/competitor-keywords/semrush-meta.template.json。录入来源 URL 可以包含报表定位
查询串,但产物会移除查询串与 fragment;不要放凭据或账号 Cookie。
不确定数据日期就不导入估算词,先记录未采集状态。若只有账号读取日期,不能将它
伪装成关键词数据日期。用免费界面实际可见的数字;不要把美元金额填入搜索量。
输入与输出契约
Section titled “输入与输出契约”JSON 顶层为 schema_version: 1、sources、rows。每条来源包含 id、provider、
country、engine、device、period、captured_at、source_url、status 和
coverage;coverage.visible_rows 必须等于该来源实际输入行数(去重前)。来源可
携带 domain,用于没有关键词行的站点归属。
每行包含 source_id、domain、keyword、locale 和 origin,可提供 rank、
landing_page、search_volume、estimated_traffic、is_brand、topic、
research_status。数值未知填 null,已观测零保留 0;排名从 1 开始。标准主题为
kana、vocabulary_grammar、jlpt、news_reading、listening、
video_subtitles、learning_tools、unclassified。分类规则只是初筛,最终候选要复核。
三种 origin 必须分开:
competitor_estimate:SEO 工具估算关键词和排名,不是竞品 GA/GSC 实测。page_inferred:页面表达或功能推导词,不得带搜索量、估算流量或排名。own_gsc:自身真实查询,只允许 Search Console 来源,不使用 SEO 估算字段。 首批没有自身查询行;实际 GSC 报表仍由既有入口保存。
每个新目录生成 input.json、aggregate.json、keywords.csv、distributions.csv、
coverage.csv、candidates.csv、report.md、manifest.json、validation.json。
清单保存文件 SHA-256;校验不仅检查摘要,也按冻结输入重算结果。
分母、缺失与去重
Section titled “分母、缺失与去重”- 数量分布的分母是同工具、国家、引擎、设备、月份、语言、来源类型、站点中,
已收集的非品牌唯一词,不是全站词库。品牌词和
excluded_*的数量单列; 无关词仍在完整样本分布的 unclassified 中,不能悄悄删除以美化学习需求占比。 - 同一词的不同大小写和重复导入不会重复计数;繁简体和不同文字保留。语言标签 规范化,但不合并不同 locale。别名域名只按注册表中明确关系归并。
- 搜索量在同一条件下跨竞品按唯一词去重。不同工具、国家、月份不混加。 重复记录数字冲突时该字段置空并留下诊断,不取最大值或求和。
- 估算流量只在单站内部计算。量化主题占比需要分母内所有词的相应指标都可用; 缺失或部分覆盖时比例为空并保留状态,不能用已知部分冒充总量。
- 分母为零时占比为空。截断或不明覆盖标为
sample_only。 excluded_*保留在审计原词和原站样本中,不进入候选。 模糊品牌、明显无关词和不支持的功能不会自动升级为页面优化机会。品牌判定是 规则与人工审核结果,Satori 等含歧义词的数量分布须结合排除状态阅读。- CSV 转义公式前缀,URL 去完整查询串和 fragment;拒绝凭据字段与私钥。
后续手动流程
Section titled “后续手动流程”- 免费账号先做一个域名的自然排名查询,确认地区、设备、日期、剩余额度和行数。 未核实的条件保持 unknown;Semrush 官方当前无 SEO 订阅口径为 10 次/天、10 行/ 报表、无历史数据,实际界面限制优先,不能自动启动试用。
- 按用户已选 US/en 与 TW/zh-TW 分批读取,品牌词单列。免费导出可用时导出; 否则仅录入可见行和来源记录,不绕过限制。
- 用同任务表达比较本地结果页;必须确认国家、语言和位置,普通联网检索不记作 当地 SERP 排名。Trends 将同义词放进同一张图,统一过去 12 个月、网页搜索和 搜索字词;热度与搜索量分列。此版没有伪造这两项数据。
- 先查功能能否承接,再看需求证据和 SERP。缺少当地证据时优先级只表示研究顺序, 不写成预计流量、已经采用或已验证的主关键词。
- 页面实施另行进入产品流程;同意图词对应一个页面,保留语言主词锁定记录, 后续英文翻译不得覆盖已验证本地词。记录上线日期,再按同页面/国家/设备观察 GSC 和 GA;不尝试将关键词与个体用户关联。
首批工程与数据验收见 COMPETITOR_KEYWORDS_ACCEPTANCE.md。
六语言增量工作流
Section titled “六语言增量工作流”原首批 8 站样本属于美国/台湾研究起点。新增范围、72 个任务种子和本地验证门槛见 SEO_SIX_LOCALES.md。导入器已接受 CN/SG/JP/KR/VN 和 Baidu/Bing/Naver,并按市场+引擎分开计算;缺失目标条件不会显示完整覆盖。原全球桌面样本仍保持原口径。