为开发者产品做关键词研究：从一方搜索需求证据构建排优先级的关…

当需要知道开发者真正在搜什么、要为开发者工具/API/SDK/文档站产出哪些页面与错误条目时，用日志、工单、issue、遥测等一方证据而非关键词工具量来聚类、打分、排序并裁剪出一份可执行的关键词地图。

适用场景

解决思路

1. 先做访谈：一次只问一个问题，能多选就多选，能从对话中已有答案的就跳过，能开始行动就停止。问题包括：产品是什么、开发者第一小时用它做什么；你拥有哪些能排名的阵地（文档站、博客、仓库、changelog、社区论坛）；哪些能真正拉到数据（一方查询报表、文档站搜索日志、支持工单、issue tracker、社区存档、产品错误遥测）；追的是个人采用还是公司采用或两者；官方支持哪些语言/框架/运行时/部署模式（这些是扩张轴）；现在是谁在回答这些查询（技术自身文档、公开问答站、竞品、无人）；团队每季度真正能发布并保持更新的页面数（这个上限就是后面裁剪用的切线，太低时集成与迁移这类常驻维护族应直接删除而不是搁置）；首批页面必须在什么日期上线、是否已有发布/SDK/迁移承诺（本月内的日期会把错误族和参考示例族提前，更远的规划周期才开放迁移与对比）；是一次性收益还是复利资产（一次性推错误条目与参考示例，复利型推 how-to 与公司采用族）。某个数据源不可用时在输出中说明，并下调该证据层级，不要用猜测替代。
2. 框定范围：写下产品的阵地清单、支持的技术轴、以及访谈得到的采用模式，下游所有工作都从这些展开；无法诚实支持的轴不得进入矩阵。
3. 先筛已有自有资产：对每个候选主题检查自有阵地是否已为它获得曝光；已能排名的页面按更新目标处理而非新页面；自有两个页面争抢同一意图属于蚕食缺陷，先修它再新增第三个页面。
4. 按拉取效率顺序采集一方需求（按每小时证据产出排，而不是按证据强度层级顺序）：查询报表（筛出平均排名 5-20 的 striking-distance 集合）、文档站搜索中零结果或首位点击错误的查询、支持工单标题、标记为 question/support 的 issue、重复出现的社区帖子、产品错误码计数器。每条都要在解决者自己的措辞还在眼前时记录（KCS 的 solve loop），一周后再重建的问题会丢掉让它可被搜索到的确切字符串。
5. 归一化并聚类错误字符串：把路径、UUID、数字和带引号的值替换成占位符后再分组；一个原因就是一个簇，不管有多少种写法；十条工单一个簇对应一个页面。当两个幸存候选不确定是一页还是两页时，用结果重叠（合并测试）判定，不要看措辞。
6. 按模式扩张：把查询族与真实支持的技术轴交叉生成候选表述；自由生成，证据门在后面。
7. 给每个候选附证据：至少一条证据项（source、count、date），并给每个指标打标签——Measured（来自导出、日志或 API）、User-provided（用户陈述）、Estimated（你推断）；取不到的指标写 N/A 并指明未能触及的来源；没有证据的候选进 parking list 而不是地图；绝不让估算当作测量结果流传，否则审阅者分不清就得重做整轮拉取。
8. 逐簇判断可赢性：指出今天谁占据结果、以及你能具体打败他什么；对三类不可赢的类别直接拒绝而不是打低分。
9. 把每个簇路由到唯一阵地（一个簇一个 canonical 目标，其它阵地内链到它）：错误条目、how-to、教程、参考示例、对比页、迁移指南、集成指南、信任/限制页。
10. 打分、排序、裁剪：按每页工时的产出排序，价值 = 证据层级 × 业务接近度 × 可赢性，再除以撰写与保持更新的成本；从比例最高的开始，绝不从最便宜的簇开始（最便宜优先是另一种顺序，回答的是另一个问题）；平局先按证据层级、再按业务接近度打破。该公式是本技能自身的默认值而非定律，会随上下文和写页人而变，要用你已知的团队情况重排（某框架的内部专家、会直接给你归一化工单的支持负责人、法务已放行的对比页）。把清单裁到团队声明的发布能力能覆盖两个季度的量，其余进带日期的 backlog，对于被声明约束排除的内容直接删除并写明约束——停在底部的簇下个季度会变成未预算的范围。
11. 按固定输出形状交付关键词地图，然后跑通过阈值，迭代到每条都通过。
12. 如果运行环境有持久记忆，存下范围框架（技术轴、采用模式、自有阵地）、do-not-target 清单及其原因，下次直接重打分而不是重新争论。
13. 拉取 striking-distance 集合：在可用最长窗口上请求 query 维度，并把行数上限调到最大（这类导出默认截断；文档化案例是 Google Search Analytics API，接受 1–25,000 行，不特别要求时只返回 1,000 行，且声明「不保证返回所有数据行」，其它 console 预期有同等上限）；在客户端切出平均排名 5–20 的窗口——位置只作为 metric 返回、从不作为 filter，报告按点击数排序，所以这个窗口无法直接请求，只能宽拉后切；把每个存活的 query join 到它的落地页，这个 join 会暴露自有两个页面争抢同一 query 的情况。无法访问 console 时向用户索取同一报表的 CSV 导出，并在输出中说明它覆盖哪个窗口；把可见长尾当作下限（罕见查询因隐私被隐去），绝不把 query 行求和成站点总量。
14. 用合并测试决定聚类：当同一批结果已经能回答两个候选关键词时，它们属于同一页；只看结果不看措辞（读起来像的两个表述常常结果集不相交，读起来不像的常常结果相同）。能检视实时结果时，统计两个前 10 自然结果集共享多少 URL：7–10 个 → 一页，另一种措辞成为变体；4–6 个 → 同一簇、分开页面；2–3 个 → 不同簇、互相交叉链接；0–1 个 → 无关、不要分组。这些切点是已发布聚类技能的惯例而非测量标准；两两比较是二次复杂度，先按族预分组，只测处在边界上的对。
15. 按每页工时产出的效率顺序扩张与发布查询族：error string（逐字错误信息或错误码 → 错误条目，一小时，修复已在工单里，抓的是开发者失败中的最高意图时刻）> reference lookup（<library> <symbol> example → 带示例的参考页，一小时，从 API 表面抄录，补的是上游文档从不给示例的缺口）> task how-to（how to <task> in <framework> → how-to 指南，一天外加每次框架发布的复测，是地图的复利中段）> evaluation（X rate limits、self-host X、X pricing → 信任/限制页，一小时撰写加一次签核，解锁 champion 的内部论证，是最便宜又能触达采购的页面）> integration intent（<product> with <other product> → 集成指南，一天加一项常驻工作，因为对方产品一直在变）> migration（migrate from X to Y、X deprecated → 迁移指南，一周且大部分是要借的工程时间，直接赢下一次切换）> comparison（X vs Y、X alternative → 对比页，一天加对竞品的每条论断做审查，在决策点遇到评估者，竞品一发布就过期）> concept（what is X、why X → 解释页，一天，最弱的一环）。同时记住其它三种排序：努力（重到轻）为 migration > comparison > integration intent > task how-to > concept > evaluation == reference lookup > error string；价值（大到小）为 migration > comparison > integration intent > error string > task how-to > evaluation > reference lookup > concept；合规审查成本（重到轻）为 comparison > evaluation > migration > 其余五族并列（不涉他人产品、不引用客户）。个人采用由 error、how-to、concept、reference 族主导；公司采用由 evaluation、comparison、migration、integration intent 主导，由 champion 而非最终签字人键入。
16. 处理效率顺序会饿死公司采用族的问题：migration 与 comparison 价值最高、努力也最高，按比例排序会每季度把它们降级，地图就只服务流量而永远触达不到采购决策；对策是给地图单独设一个公司采用目标数，无论比例把它们排到哪里都要填满。当竞品发布弃用或破坏性大版本时，把 migration 直接提到最前——那是切换最便宜、且一个季度内窗口关闭的唯一时机。
17. 采取删除而非降级：没有发布能力保持集成指南更新，就从本次地图中删除集成族（页面腐烂成错误答案，代价高于它挣到的一切）；拿不到对竞品论断的签核，就删除对比族，该需求改用关于自家产品的迁移指南来承接。
18. 按证据层级使用需求来源：层级按证据强度编号（价值轴，不是拉取顺序，因为拉取成本相差百倍）——1 一方查询数据（尤其排名 5–20）；2 文档站搜索日志（尤其零结果查询）；3 支持工单与 issue tracker 的问题；4 产品错误遥测；5 公开问答与论坛问题计数；6 生态计数器（registry 下载量、依赖数）；7 自动补全与相关搜索采集；8 关键词工具的量与难度（只作平局打破）。效率顺序（每小时证据产出）为 tier 1 > tier 2 > tier 3 > tier 5 > tier 7 > tier 8 > tier 6 > tier 4；努力顺序（重到轻）为 tier 4 > tier 3 > tier 2 > tier 1 == tier 5 > tier 6 == tier 7 == tier 8；合规成本（重到轻）为 tier 3 > tier 4 > tier 2 > tier 5 > 其余并列。
19. 按上下文重排层级顺序：这份顺序是技能自身基线，会随上下文和执行者而变，用你已知的团队情况重排（已经会归一化工单标题的支持负责人把 tier 3 提到最前；已有遥测仪表盘的产品等于已经付过 tier 4 的成本）。当地图以错误族为主、或产品太年轻还没有支持队列产出量时，把产品错误遥测提到所有来源之前——那时便宜层级观察到的是一个还不存在的受众，而遥测是唯一能看到默默失败、从不提交工单的沉默多数的来源。
20. 严格遵守两条诚实规则：绝不因为某个工具报零量就删掉关键词（工具按月平均、合并近似变体并取整，零只是在陈述该工具的索引）；绝不编造数字（来源无返回就写 N/A，完全无法访问就把该层级标为不可用）。
21. 执行可赢性与拒绝规则：对每个簇指出在位结果和你能打败的具体弱点（过时答案、已不存在的版本、没有可用配置的列表、从不给示例的参考页）。技术查询靠完整性取胜：逐字复现精确字符串、写明版本、给出可运行的修复、覆盖失败条件。直接拒绝三类并在输出中列出：产品无法诚实回答的查询；真正的修复是产品改动或更好的错误信息而不是页面的查询；由技术自身文档占据的参考查找。
22. 按引用而非点击来打分：助手已经改变了点击预测的价值，页面可能被引用而没被点击，因此按「你的页面是否会成为答案组装的来源」评分，回报用引用与到达来预测，而不只看点击。对整条价值只是一行答案的簇打折但保留在地图上（助手仍从你发布的内容组装答案，即更少访问但同样的影响力），同时记住简单的那一端最先失去点击（Stack Overflow 2025 开发者调查：49,000+ 受访者中 84% 使用或计划使用 AI 工具，66% 把「几乎正确但不太对」的 AI 答案列为最大挫败，信任度从 2023 年约 40% 降到 2025 年 29%；JetBrains 2025 开发者生态调查：24,534 名受访者、2025 年 4–6 月采集，「在网上搜索开发相关信息」是开发者交给 AI 工具的第二常见任务，仅次于写样板代码）。
23. 按固定章节产出 Markdown 报告：Scope（技术轴、采用模式、自有阵地、可用与不可用的来源）；Ranked clusters（按每页工时产出从高到低排序，在表格上方说明排序方式，并列出被该比例降级的高价值簇以及各自的提升条件；列为 Cluster、Primary query、Variants、Family、Evidence（source、count、date）、Incumbent、Target surface、Existing URL 或 new、Priority）；Company-adoption set（同样表格，单独保留，避免被量或效率比例埋掉）；Fix first（蚕食与「更新而非新建」的案例）；Do not target（簇 + 原因：无法回答/产品修复/上游文档已占据）；Backlog（有证据但超出本季度能力，附停放日期）。请求更窄时只裁剪章节，绝不发明另一种形状。
24. 跑通过阈值（六条全满足才算完成，并显式说明结果）：1 每个被排名的关键词至少带一条含 source、count、date 以及 Measured/User-provided/Estimated 标签的证据；2 至少 70% 的排名簇的首选证据来自 tier 1–4（一方数据），低于此就是伪装成研究的猜测，回到第 3 步；3 没有簇仅凭关键词工具量排名；4 每个簇恰好有一个 canonical 目标阵地，且没有两个簇以不同意图指向同一页面；5 do-not-target 清单非空（一轮什么都没拒绝的研究等于没应用可赢性过滤）；6 排名表说明了自己的排序、列出了被比例降级的高价值簇及各自的提升条件，公司采用集有自己填满的目标数而不是继承比例顺序。70% 门槛是本技能自身基线而非已发布基准，要如此报告，并在产品有一方数据丰富时提高、在发布前产品几乎没有数据时在 Scope 中显式降低。
25. 事后度量这份清单：跟踪 coverage（有活跃目标的排名簇占比）、movement（跨入头部的 striking-distance 查询）、arrival（每个页面发布后精确字符串的一方查询数）；不要把已发布页面数当结果上报——那衡量的是写作团队而不是研究。
26. 避开已知失败模式：矩阵爆炸（把每个模板乘每个修饰词会产出成千上万个没人搜的格子，每个格子都要过证据门，否则矩阵就是 doorway page 生成器）；一工单一页（跳过错误归一化会把一个原因变成十个互相竞争的薄页面）；版本腐烂（绑定版本的关键词会静默过期，给这类簇盖上复核日期）；意图冲突（同一措辞可能是错误也可能是配置查找，分配阵地前先看当前结果实际回答的是什么）；把博客当垃圾场（文档形态的查询路由到博客，答案会被埋在没人从产品里链接的地方）；销售可见问题缺失（限制、权限、合规和迁移问题很少到公开渠道，去问回答它们的人）。
27. 与相邻技能衔接：本技能只产出关键词地图，不写页面；错误条目交给 developer-troubleshooting-docs，目标页面存在后交给 docs-seo 做页面内与技术 SEO，结构性缺口交给 developer-docs-structure-audit，把产出的主题排进季度交给 devrel-content-calendar，采用模式拆分所假设的受众分段交给 developer-segmentation。

适用边界 · 注意事项

• 只做页面内或文档站技术 SEO 时不适用——那属于 samber/developer-relations-skills@docs-seo。
• 需要直接写出页面内容（错误条目、教程、迁移指南）时不适用，本技能只产出关键词地图，写作交给对应技能。
• 产品完全没有一方数据源、也没有支持队列或遥测可借（如尚未发布）时，除非明确在 Scope 中下调 70% 一方证据门槛，否则结论只是猜测。
• 不要把关键词工具量当作排名依据（它只作平局打破），也不要因为工具报零量就删掉关键词。