skill-web-research（网络研究技能）Skill 是什么？能自动完成 Web 调研吗？

网络研究技能：把 Web 开发调研变成一条可追踪、可提交的自动化流水线

• 它是什么：一个「薄包装层」技能，把网络开发研究任务委托给 web-research-agent 子代理，并在子代理返回后自动完成状态更新、工件链接与 git 提交。
• 解决什么问题：Web 开发调研（框架文档、样式方案、无障碍性要求）通常散落在多次搜索与手工整理中，结果难以归档、难以追踪；该技能把调研变成有状态、有产物、有提交记录的标准流程。
• 怎么用：以任务编号（task_number）为入口触发，可附带研究方向（focus_prompt），技能自动完成 11 个阶段的预检、委派、后处理与清理。
• 适合谁：使用代理式 AI 编程环境、维护 specs/state.json 任务清单与 TODO 清单、并希望研究结论可复用可回溯的 Web 开发团队。
• 一句话结论：它不是「更聪明的搜索框」，而是把「调研」接入工程流水线的编排器。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：网络研究技能 技能英文名：skill-web-research 技能ID：12868

这个技能要解决的问题很具体：当你需要为 Web 开发任务做调研时——比如查 Astro 的组件写法、Tailwind 的样式组织方式、Cloudflare 的部署约束，或者交互元素的无障碍性要求——信息往往来自「本地项目文件 + 官方文档 + 社区实践」三处，人工收集既慢又容易漏，而且调研结论通常只留在聊天记录里，下次要用时找不回来。

skill-web-research 的做法是把调研「包装」成一个受控流程：技能本身很薄，真正的检索与分析交给 web-research-agent 子代理，而技能负责前后两端的工程化动作——预飞行时把任务状态改为 researching、写入后处理标记文件，结束时解析元数据、链接研究工件、更新 TODO、执行 git 提交并清理临时文件。

一键安装的思路与步骤

由于该技能的安装入口与命令由平台方提供，以下为通用流程，具体命令、链接与版本信息以官方说明为准：

1. 确认安装前提：你需要一个支持 AI 技能（Skill）机制的代理式编程环境；项目内存在 specs/state.json 任务状态文件与 TODO.md；项目是一个 git 仓库（技能结尾会执行提交）；环境中可用的工具需覆盖 Task、Bash、Edit、Read、Write 以及 /tmp/*.json 读写与 rm 清理权限——这些正是技能声明的允许工具白名单。
2. 通过技能市场或技能ID添加：在平台的技能管理入口检索技能ID 12868 或英文名 skill-web-research，点击安装/启用；若平台提供手动方式，则按官方说明将技能目录放入项目的技能目录中并启用。
3. 确认上下文参考文件就位：技能以「按需加载」方式引用三份上下文文档——元数据文件架构、标记文件协议、jq 转义模式，路径在技能详情中已给出（.opencode/context/core/formats/return-metadata-file.md 等）。缺失时通常不影响主流程，但排错会更困难。
4. 验证是否生效：新建或选择一个 language 为 web 的任务，观察三个信号——任务状态是否被改为 researching；任务目录下是否出现 .postflight-pending 标记文件；结束后是否在 specs/{NNN}_{SLUG}/reports/ 下生成 research-{NNN}.md，且返回一段简短的中文摘要。

该技能的主要功能和特点

• 薄包装 + 子代理委派：技能自身不承担检索，而是通过 Task 工具（而非 Skill 工具）生成 web-research-agent 子代理，把上下文、聚焦提示、元数据文件路径一并传入，职责边界清晰。
• 技能内后处理模式：子代理返回后，技能自己完成状态更新、工件链接、git 提交三项后处理，再向上返回结果——调用方无需再写一套收尾逻辑。
• 预飞行状态机：调用前先把任务标记为 researching 并写入 last_updated、session_id，让「正在研究」这一中间态在状态文件中可见。
• 标记文件协议与恢复能力：通过 .postflight-pending 记录待完成的后处理原因；元数据文件缺失时保持 researching 状态以便恢复，而不是直接判失败。
• 工件去重与转义规避：链接研究工件时采用两步 jq 模式，先过滤旧的研究类工件再追加新的，并使用 select(... | not) 写法规避转义问题；细节参考 jq 转义模式文档。
• 分级错误处理：输入校验失败立即返回；元数据缺失保留中间态；git 提交失败视为非阻塞，记录后继续。
• 报告不只是「搜到」，而是「能落地」：子代理会扫描本地 src/、public/ 的项目模式，再结合网络上的框架文档，最后综合分析并给出实施建议，同时考虑无障碍性因素。

如何使用该技能？

1. 准备任务：在 specs/state.json 的 active_projects 中存在目标任务，至少包含 project_number、project_name、status、language、description 字段。
2. 触发技能：当任务语言为 web、需要为网络开发任务做研究、或需要收集 Astro / Tailwind / Cloudflare / 无障碍性文档时，技能自动激活；若上次为部分完成，可重新发起研究以继续（技能返回提示中会出现类似 /research 412 的续跑指引）。
3. 传入输入：必填 task_number（必须已存在于 state.json）；可选 focus_prompt 指定研究方向。示例：task_number = 412，focus_prompt = "Astro 组件模式与 Tailwind v4 样式做法，附带交互元素的无障碍性要求"。
4. 技能执行预检：读取任务数据并校验存在性，提取 language、status、project_name、description；随后把状态更新为 researching，并在 TODO.md 中标记为 [RESEARCHING]。
5. 创建标记与委托上下文：生成三位补零的任务目录（如 specs/412_add_blog_section）并写入 .postflight-pending；组装包含 session_id、delegation_depth、delegation_path、timeout（3600）、task_context、focus_prompt、metadata_file_path 的上下文。
6. 调用子代理：以 subagent_type: "web-research-agent" 启动子代理，描述写明「为任务 N 执行网络研究」。子代理负责搜索本地项目文件、联网检索框架文档、分析综合、撰写报告并写出元数据文件。
7. 解析返回：校验 .return-meta.json 是否为合法 JSON，提取 status 与第一个工件的 path、type、summary；文件缺失或非法时按失败处理。
8. 后处理：状态为 researched 时更新 state.json 与 TODO.md，用两步 jq 去重并追加研究工件，在 TODO 中写入形如 - **研究**: [research-{NNN}.md]({相对路径}) 的链接（需剥离 specs/ 前缀）。
9. 提交与清理：git add -A 并提交，提交信息包含任务号与会话信息；随后删除 .postflight-pending、.postflight-loop-guard、.return-meta.json。
10. 读取结果：成功时返回中文摘要，说明找到的框架文档与项目模式、识别出的实施方法与无障碍性考量、报告路径、状态已更新为 [RESEARCHED]、更改已提交。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
网络研究技能（skill-web-research）	把 Web 调研接入工程流水线的编排型技能	子代理委派、状态机推进、报告归档、工件链接、自动 git 提交	需支持技能的代理环境、state.json 任务清单、git 仓库；以官方说明为准	已有任务台账的 Web 项目做框架/无障碍性调研	优势是产物可追踪可回溯、收尾全自动；不足是强依赖项目既有目录与状态文件结构
通用联网搜索类插件	通用信息检索	关键词搜索、网页摘要	安装简单，几乎零配置	快速查一个概念、一次性问答	优势是门槛极低；不足是无项目上下文、无归档、结论难复用
人工查阅官方文档	传统方式	阅读文档、复制示例、手工整理	零成本但耗时最高	复杂 API 细节、需要逐条比对版本差异	优势是权威；不足是效率低、易遗漏跨文档关联
通用深度研究型子代理（无状态管理版）	一次性深度调研	多轮检索与综合报告	直接调用即可	预研新技术、做技术选型初稿	优势是灵活；不足是不更新任务状态、不链接工件、不提交，流程中容易「调研完就断线」

对比结论：如果你只需要「查一下」，通用搜索更快；但如果你需要「这次调研的结论在两周后还能被找到、并且能对应到具体任务」，skill-web-research 的状态与工件管理才是差异化价值所在。

该技能的典型应用场景与实际体验情况

场景一：前端工程师给博客站点新增文章区块 痛点：需要同时确认 Astro 的组件组织方式、Tailwind v4 的样式写法，以及列表与分页的无障碍性要求，三处信息分散。 使用方式：在任务 412 上以 focus_prompt 指定「Astro 组件模式 + Tailwind v4 样式 + 交互元素无障碍性」。 实际体验：技能会先扫本地 src/ 与 public/ 的既有模式，再去查框架文档，报告里给的是「结合你项目现状的实施方法」而不是泛泛的文档摘抄；同时全程有状态可查，中断后能续跑。

场景二：团队评估部署与边缘配置方案 痛点：Cloudflare 相关能力更新快，靠记忆容易踩坑，且结论需要沉淀给多人。 使用方式：为部署类任务发起研究，研究结论以 research-{NNN}.md 归档并链接进 TODO。 实际体验：报告天然进入版本库，评审时可以直接看 diff；注意 git 提交需要仓库已配置好身份信息，否则提交失败——技能对此是非阻塞的，只记录不中断。

场景三：无障碍性合规的自查与补充 痛点：交互组件上线前需要补充键盘可达、语义化标签等要求，容易被遗漏。 使用方式：以无障碍性为聚焦方向发起研究，子代理会返回针对交互元素的要求清单。 实际体验：清单式结论落地性较好；但要注意报告是「研究建议」，不是自动化审计结果，最终仍需人工复核。

场景四：多代理流水线中的批量研究 痛点：编排者需要把「调研」这一步标准化，避免每个任务各写一套收尾逻辑。 使用方式：由编排器按 delegation_depth / delegation_path 逐层委派。 实际体验：上下文与元数据文件路径在层间传递清晰，收尾动作统一；上手难点主要在于理解标记文件协议与 jq 两步更新模式。

整体上手评价：对熟悉 jq 与状态文件的人，上手成本中等偏低；对纯前端背景的用户，建议先通读元数据文件架构与标记文件协议两份文档。注意三点：task_number 必填且必须存在、元数据文件缺失会导致状态停留在 researching、以及部分完成（例如网络检索失败但本地扫描成功）时报告会标注为部分完成并提示续跑。

该技能能为用户带来的价值

• 把调研从「对话」变成「资产」：研究结论固定落在 specs/{NNN}_{SLUG}/reports/ 并链接进任务台账，几周后仍可检索、可引用、可对比。
• 减少流程断点：一次调用串起「本地扫描 → 联网检索 → 综合报告 → 状态更新 → 工件链接 → 提交」六件事，调用方无需另写收尾脚本。
• 降低协作门槛：新成员不需要掌握完整的调研方法论，只要给出任务号与研究焦点，就能得到格式统一、含无障碍性考量的报告。
• 可控可恢复：中间态 researching、标记文件、非阻塞的提交失败处理，让长流程在异常时不至于「无声丢失」。
• 成本友好的上下文策略：上下文参考文件「引用但不提前加载」，避免一次性灌入大量文档占用上下文预算。
• 长期价值：研究工件随 git 历史累积，逐步形成团队自己的技术决策记录，后续相似任务可直接复用既有结论，减少重复检索。

常见问题 FAQ

Q1：怎么安装这个技能？有没有一键入口？ 在支持 AI 技能机制的代理式编程环境中，通过技能管理入口检索技能ID 12868 或英文名 skill-web-research 添加并启用即可；若平台提供手动方式，按官方说明将技能放入技能目录。安装前请确认项目已有 specs/state.json、TODO.md 且是 git 仓库，否则后处理阶段会失效。具体命令与版本要求以官方说明为准。

Q2：它收费吗？ 技能详情中未涉及任何定价信息，费用取决于你所在平台与所用模型的计费策略，请以官方说明为准。可以确定的是，该技能会在一次调用中同时使用子代理与多轮检索，建议关注平台的调用配额。

Q3：适合谁用？ 最适合三类人：需要为 Web 开发任务做框架文档调研的前端工程师；希望调研结论可归档、可回溯的技术负责人；以及在多代理流水线中需要把「研究」这一步标准化的编排者。如果你只是想临时查一个语法问题，通用搜索会更轻。

Q4：和直接开一个联网搜索有什么区别？ 区别在「状态」与「产物」：通用搜索只给你一段回答；该技能会校验任务是否存在、把状态推进到 researching、生成报告文件、把工件链接进 state.json 与 TODO.md、再提交到 git。它把检索结果变成了工程流程中可追踪的一环。

Q5：任务失败或网络中断怎么办？ 分三种情况：找不到 task_number 会立即返回错误；元数据文件缺失或非法时状态保留在 researching 以便恢复；git 提交失败是非阻塞的，只记录不中断。若出现「部分完成」（例如网络检索失败但本地模式扫描成功），报告仍会生成，按返回提示重新发起研究即可续跑。