survey

调研

当任务是在制定计划之前了解整体情况时，请使用此技能。

survey 通过做好以下四件事来保持通用性：

1. 锁定一个范围明确的研究问题，
2. 每次都采用相同的 4 条研究路径，
3. 将可复用的成果保存到 .survey/{slug}/，并使用固定标题，
4. 在移交给规划或执行之前，验证成果是否符合约定。

开始不熟悉的调研工作前，请先阅读以下支持文档：

• references/evidence-recovery-ladder.md
• references/platform-adapter-and-artifact-contract.md
• references/output-templates-and-validator.md
• references/keyword-sweep-and-relevance-rescue.md
• references/gh-search-empty-lane-recovery-playbook.md

何时使用此技能

• 用户询问有哪些方案、人们实际使用什么，或当前的解决方案全貌如何。
• 某项功能、工作流、工具选择或运维痛点需要先了解背景，再制定计划或实施。
• 主题涉及多个平台或供应商，需要进行供应商中立的比较。
• 维护仓库时，需要先开展一次范围明确的调研，再重写技能、SOP 或可复用工作流。
• 下一步取决于了解变通方法、反复出现的抱怨和结构性缺口，而不是立即编写代码。

何时不使用此技能

• 解决方案已明确，用户希望立即实施 → 直接实施或转交给执行技能。
• 任务是小型 Bug 修复、范围狭窄的代码改动或单文件编辑 → 不要强行先做调研。
• 用户更需要架构方案、任务计划或不可变规范，而不是市场／工作流调研 → 使用 plan、jeo 或 ralph。
• 请求主要是实时浏览并点击操作 → 使用浏览器／操作员技能，而不要把这类工作误当成调研。

成果约定

保持输出包的结构稳定：

.survey/{slug}/
├── triage.md
├── context.md
├── solutions.md
└── platform-map.md    # required for agent/tooling/platform topics

必需文件的含义：

• triage.md = 问题、受众、为何是现在
• context.md = 工作流背景、受影响用户、变通方法、相关问题、用户声音
• solutions.md = 解决方案列表、类别、实际行为、频率、缺口、矛盾、关键洞见
• platform-map.md = 在相关时，将 Claude / Codex / Gemini 的差异归一到 settings、rules、hooks、platform gaps

除非用户明确要求，否则不要自行创建其他文件名或自由格式的成果。 如果调研输出需要复用，写入文件后请使用 python3 .agent-skills/survey/scripts/validate_survey_artifacts.py <path> 进行验证。

说明

第 1 步：确定一种主要调研模式

开始调研前，先规范化请求：

survey_run:
  primary_mode: market-landscape | workflow-landscape | repo-maintenance | platform-comparison
  scope: narrow | medium | broad
  evidence_floor: primary-pages-first | indexed-snippets-allowed | thin-evidence-ok
  output_language: repo-default | user-language
  needs_platform_map: true | false
  reuse_existing: true | false | unknown

模式指南：

• market-landscape → 产品、类别、竞争对手、包装方式、投诉
• workflow-landscape → 人们目前如何完成工作、变通方法、运维惯例
• repo-maintenance → 为改进现有技能、SOP 或可复用工作流而开展的范围明确的调研
• platform-comparison → 将 Claude / Codex / Gemini 的差异归一到 settings、rules、hooks

即使主题涉及多种模式，也请选择一种主要模式。

步骤 2：冻结证据约定

开始搜索前，明确规则：

• 除非用户要求使用其他语言，否则使用英文广泛搜索
• 使用仓库默认语言或用户指定的语言编写产物
• 所有主张都必须有来源支持
• 清楚标注降级证据：direct page retrieval、indexed snippet、browser-rendered indexed snippet、feed recovery 或 thin evidence
• 仅将任务保持在研究模式

使用 references/evidence-recovery-ladder.md 中的低成本优先恢复顺序：

1. 直接检索主要页面
2. 使用稳定的官方替代来源
3. 从 Feed 恢复
4. 通过浏览器渲染检索
5. 检索索引摘要
6. 证据薄弱时停止

步骤 3：分类请求并检查是否复用

解析：

• what — 要调研的痛点、想法或能力
• who — 感受到该问题或负责相关工作流的人
• why — 该问题为何现在很重要

然后检查 .survey/{slug}/triage.md 是否已存在。

• 如果文件已存在且用户在线，询问是复用还是覆盖。
• 在无人值守循环中，如果现有产物仍与同一问题匹配，则复用；只有范围明显变化时才覆盖。

将以下内容写入 triage.md：

• # Triage
• - Problem:
• - Audience:
• - Why now:

步骤 4：并行执行 4 条研究线

即使其中一条研究线的证据较少，也要保持各线彼此独立。

研究线 A — 背景

返回：

• ## Workflow Context
• ## Affected Users
• ## Current Workarounds
• ## Adjacent Problems
• ## User Voices

研究线 B — 解决方案

返回：

• ## Solutions
• ## Frequency Ranking
• ## Categories
• ## Curated Sources

研究线 C — 实际行为

返回：

• ## What People Actually Use
• ## Common Workarounds
• ## Pain Points With Current Solutions
• ## Sources

研究线 D — 替代方案或平台图谱

默认模式：

• JTBD 替代方案
• 间接替代品
• 跨行业类比

对于 Agent／工具／平台主题，将其替换为：

• ## Settings
• ## Rules
• ## Hooks
• ## Platform Gaps

只要 Claude／Codex／Gemini 之间的差异与主题相关，就将 settings / rules / hooks 作为通用层。

步骤 4.5：对仓库维护调研应用相关性门槛

当 primary_mode: repo-maintenance 时，不要仅凭关键词命中就轻信结果。

撰写最终建议前，先进行简要筛选：

• 正向信号（保留）： 与目标能力明确相关、近期有维护记录、许可证明确、文档／示例具体。
• 负向信号（剔除或标记风险）： 描述疑似垃圾内容、虽然关键词匹配但领域无关、仅用于评估／作业的仓库、缺乏充分理由的陈旧／归档仓库、缺少基本元数据，或许可证未知且无明确理由。
• 元数据最低要求： 为每个保留的候选项记录 license、pushed_at、archived、open_issues、forks，以及一行适配理由。如果首轮元数据返回许可证为 null／未知（例如 GraphQL licenseInfo），则通过 GitHub REST 重试一次（gh api repos/<owner>/<repo> --jq .license.spdx_id），再将其归类为许可证未知。回退后许可证仍未知／缺失的候选项默认应排除，除非记录了具体的例外理由。如果首轮无法获取 open_issues／forks，则通过 gh api repos/<owner>/<repo> --jq '{open_issues: .open_issues_count, forks: .forks_count}' 补充一次，并记录检索来源。
• 新鲜度底线（建议级保留列表）： 默认排除 pushed_at 距今超过 24 个月的候选项。仅在明确记录例外理由和风险说明时保留陈旧候选项。

如果搜索／提取工具不可用或性能下降，则回退到直接检索 GitHub API，并明确标注来源和风险，不要假装有把握。

步骤 4.6：每小时候选项扫描（仓库维护 cron 循环）

当调研属于定期技能维护循环的一部分时，在最终建议前执行一次明确的关键词扫描。 Required keyword families:

• agentic ai skill
• web frontend skill
• web backend skill
• cli open source skill
• game development skill

执行规则：

• 对于每小时运行，使用近期优先的查询时间窗口：默认查询最近 24h~7d 内的 pushed，然后仅通过有文档记录的恢复阶段逐步扩大范围。
• 将原始关键词扫描保留为发现证据（通常通过搜索页面进行时，标记为 browser-rendered retrieval）。
• 在保留任何候选项之前，应用 Step 4.5 相关性门槛。
• 对每个保留的候选项，至少记录：license、pushed_at/updated、archived、open_issues、forks，以及一行适配理由。
• 对推荐级保留项，应用默认新鲜度下限（pushed_at 在过去 24 个月内）。如果因过时仍予以保留，请记录例外理由和明确风险。
• 对推荐级保留项应用默认信号下限：至少需要一个热度信号（例如 stars >= 3，或有明确的维护者／社区采用证据并附理由）。即使推荐级列表采用更严格标准，也要保留广泛的发现证据。
• 对 agentic ai skill 方向，默认将仅命名为 */skills 的通用个人杂项仓库视为低适配度，除非有明确的工作流文档和热度信号；将其保留在原始证据中，但未经例外理由，不要将其提升为 TOP 推荐。
• 在提升至推荐级之前，应用考虑否定表达的意图防护：如果方向意图词的重叠仅出现在明确的否定短语中（例如 no cli、without cli、not a cli、non-cli），默认归类为 low-fit，保留在原始发现证据中，并要求提供明确的例外理由才能提升。
• 如果直接网页搜索／提取工具失败（身份验证／速率限制／传输问题），切换到 GitHub 原生检索（gh search + gh api 或 gh repo view），并清楚标注来源。
• 在无人值守循环中防范 GH CLI JSON 字段漂移：优先使用 gh search repos --json fullName,...（或通过 owner + name 组合标识），而非 nameWithOwner 等不受支持的字段；若字段不匹配，保留 stderr 作为证据，并在确定最终方向状态前使用受支持的字段重新运行。
• 在无人值守循环中防范 gh search repos 返回空但成功的载荷：如果退出代码为 0，但对于已知有结果的探测／查询，载荷意外地为 []（或实际上为空），则将其视为传输降级，并在确定最终方向状态前通过 GitHub REST 搜索重新运行。
• 对于 REST 回退路径，优先使用端点形式 gh api "search/repositories?q=<query>&per_page=<n>&sort=updated&order=desc"，并捕获 stderr 产物；避免依赖某些环境中可能导致 404 的不兼容形式。
• 对于使用 --require-provenance 验证的 Markdown 产物，将 GitHub 搜索结果证据映射到验证器支持的标签（搜索结果列表使用 indexed snippet，仓库／API 详情抓取使用 direct page retrieval），不要使用 github search api 等临时标签。
• 如果关键词命中嘈杂或稀少，在最终确定推荐之前，运行 references/keyword-sweep-and-relevance-rescue.md 中针对各方向的恢复模板。
• 在主查询后使用客观的恢复触发条件（raw_count < 8、kept_count == 0 或 zero_star_raw/raw_count >= 0.70），确保无人值守的 cron 循环中各方向的补救步骤可确定地执行。
• 指标完整性门槛（强制）： 每次选择恢复查询后，在写入产物之前，根据最终选定的结果集重新计算方向指标（raw_count、zero_star_raw、median_stars_raw、kept_count）。绝不输出不可能的组合，例如 kept_count > raw_count。
• 如果某方向在第一阶段恢复后仍为 raw_count == 0，则在确定 lane_status 前，针对该方向恰好运行一次有文档记录的第二阶段恢复查询。
• 对于命中嘈杂但原始结果存在、且第一阶段恢复后推荐级保留项仍为 kept_count == 0 的方向，在确定降级状态前，恰好运行一次有文档记录的第二阶段恢复查询。
• 如果某方向在有文档记录的恢复后仍以 raw_count == 0 收尾，请设置／报告 degraded_causes，并明确填写 no-results（不要留空）。
• 通过相关性门槛后，推荐数量目标为：在可行的情况下每个方向至少保留 1 项；cli open source skill 应以保留 3 项以上为目标，以满足重点推荐的质量要求。
• 在 Markdown 中明确给出各方向的状态（lane_status: pass|degraded）。如果未达到门槛，保留证据并使用简明分类（license、stale、low-fit、archived、low-signal、no-results）报告 degraded_causes，并附示例／数量。
• 如果某方向在有文档记录的第二阶段恢复查询后仍为 raw_count == 0，请设置并报告包含 no-results 的 degraded_causes（不要留空）。
• 除了 lane_status，还要包含简明的方向健康指标（kept_count、raw_count、median_stars_raw、zero_star_raw），以便审核人员追踪每小时运行的质量变化。
• 对推荐级保留项执行跨方向集中度检查：如果 recommended_lane_count < 2，将本次运行标记为 single_lane_concentration: true，明确保留已降级方向的证据，并避免声称覆盖面广泛且健康。
• 在最终排名前增加跨方向推荐去重门槛：原始发现证据保持不变，但按仓库标识（fullName 或 owner/name）计算去重后的推荐级集合，并同时报告原始覆盖度和去重后覆盖度指标。 参考：references/keyword-sweep-and-relevance-rescue.md

步骤 5：综合整理产出物

保持写入的文件简洁，且架构稳定。

• 使用 references/output-templates-and-validator.md 中的精确 Markdown 模板。
• 保持必需的文件名和标题不变。
• 证据薄弱时，保留如实的来源标签。
• 对于平台主题，应在 platform-map.md 中明确说明，而不是把平台差异藏在 solutions.md 中。
• 对于 repo-maintenance，说明每个保留的候选项为何通过相关性门槛（匹配度 + 元数据 + 风险）。

步骤 6：验证产物契约

写完文件后运行验证器：

python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug>
python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug> --platform-topic

需要 platform-map.md 时，使用 --platform-topic。 如果本次运行需要关注来源标签，也请使用：

python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug> --require-provenance

如果验证器未通过，请先修复产物文件，再交由规划或实施。

步骤 7：以事实性调查摘要收尾

只有在文件写入并通过验证后，才返回简短摘要：

• ## Survey complete: {slug}
• 1-2 条背景要点，包括主要变通方案
• 1-2 条解决方案全景要点，包括关键洞见和关键缺口
• 生成的产物文件列表

除非用户明确要求下一步，否则不要转入规划或实施。

输出规则

• 先陈述事实；仅在用户要求时再给出建议。
• 每份调查产物只提出一个范围明确的问题。
• 保持解决方案名称去重；在最终排名前，跨各路径去重达到推荐标准的仓库，同时保留原始证据。
• 来源较弱或间接时，保留证据标签。
• 各平台的产物架构保持一致。
• 调查完成后，将架构、规划或执行工作交由其他流程处理。

示例

示例 1：仓库维护调查

输入

调查此仓库中现有的技能，确定下一个最适合作为范围明确的维护目标的是哪一个

良好输出方向

• 模式：repo-maintenance
• 先检查是否已有 .survey/{slug}
• 使用仓库本地的图谱 / wiki 证据，以及必要的一手来源检索
• 写入分诊、背景和解决方案文件，并给出事实性摘要
• 在开始改写技能前，验证输出文件夹

示例 2：平台对比

输入

调查 Claude Code、Codex 和 Gemini CLI 在钩子、审批和研究工作者方面有何不同

良好输出方向

• 模式：platform-comparison
• 写入 platform-map.md
• 将差异规范为 settings、rules、hooks
• 使用 --platform-topic 进行验证
• 记录可移植性缺口，但不要将供应商特有功能视为产物契约

最佳实践

1. 保持入口精简：分类模式、固定证据规则、执行 4 个路径、验证并保存产物。
2. 将变化缓慢的检索 / 平台 / 模板细节放入参考资料，避免主技能过于臃肿。
3. 优先使用直接的一手来源，但要如实标注每次降级。
4. 在 Claude / Codex / Gemini 的运行中，保持产物文件名和标题一致。
5. 证据不足时，应缩小论断范围，而不是假装确定。
6. 将钩子系统视为验证器的加速器，而非已提交产物规则的替代品。

参考资料

• references/evidence-recovery-ladder.md — 弱搜索 / 提取环境下的备用阶梯和来源标签
• references/platform-adapter-and-artifact-contract.md — settings、rules、hooks 的可移植性规则，以及各平台一致的产物输出规则
• references/output-templates-and-validator.md — .survey/{slug}/ 的精确文件模板及验证器用法
• references/keyword-sweep-and-relevance-rescue.md — 循环执行仓库维护调查时必需的五关键词扫描和嘈杂查询补救门槛
• scripts/validate_survey_artifacts.py — 调查输出文件夹的产物契约验证器