Searching AEM Documentation

用途

本技能用于高效搜索完整的 aem.live 文档（包括文档页面和博客文章），避免在无关页面上浪费上下文。它通过提供的搜索脚本查找相关文档页面，然后使用 WebFetch 读取最相关结果的完整内容。

何时使用

在以下情况使用本技能：

需要了解 aem.live 功能或概念的信息
已经查看过项目代码库以获取上下文
尝试过基本网络搜索但未找到相关的 aem.live 文档
需要关于实现 aem.live 功能的技术指导
正在寻找官方文档中的最佳实践或示例

在以下情况不要使用本技能：

需要可复用的代码片段或区块示例（改用 block-collection-and-party）
已经知道具体的文档 URL
正在寻找通用 Web 开发信息（非 aem.live 特定）

使用方式

第 1 步：确定关键词

确定 1-3 个与搜索内容相关的具体关键词。要具体而非宽泛。

好的关键词：

"block decoration"
"metadata"
"universal editor"
"sidekick plugin"

差的关键词：

"aem"（过于宽泛，会被作为停用词过滤）
"how to build website"（过于宽泛）
"the"（停用词）

第 2 步：运行搜索脚本

从项目根目录执行搜索脚本：

node .claude/skills/docs-search/scripts/search.js [--all] <keyword1> [keyword2] [...]

选项：

--all：返回所有匹配结果（默认：限制为 10 个最相关结果）
不使用 --all：返回前 10 个结果

示例：

# 搜索区块装饰信息
node .claude/skills/docs-search/scripts/search.js block decoration

# 搜索 metadata 并返回所有结果
node .claude/skills/docs-search/scripts/search.js --all metadata

# 多词搜索
node .claude/skills/docs-search/scripts/search.js universal editor blocks

第 3 步：查看搜索结果

脚本返回 JSON，结构如下：

[
  {
    "path": "/developer/markup-sections-blocks",
    "title": "Markup, Sections, Blocks, and Auto Blocking",
    "description": "To design websites and create functionality, developers use the markup and DOM...",
    "snippet": "Markup, Sections, Blocks, and Auto Blocking\n\nTo design websites...",
    "type": "doc",
    "deprecation": null,
    "relevanceScore": 141
  }
]

字段说明：

path：文档页面的 URL 路径
title：页面标题
description：简要摘要（通常约 150 字符）——用于快速了解上下文
snippet：页面内容中显示关键词上下文的相关摘录
type："doc" 或 "blog"
deprecation：功能已弃用时的警告消息（或 null）
relevanceScore：相关度分数（越高越相关）

重要说明：

结果按相关度排序（最高在前）
已弃用页面的相关度分数会降低，但仍会出现在结果中
description 字段提供最佳的快速摘要
snippet 显示关键词上下文，但可能不全面

第 4 步：使用 WebFetch 获取完整内容

搜索结果提供概览。要获取详细信息，使用 WebFetch 读取完整页面：

WebFetch: https://www.aem.live{path}

最佳实践：从最相关的前 2-3 个结果开始，用 WebFetch 完整阅读，然后决定是否需要更多。

第 5 步：向用户提示弃用信息

如果任何结果的 deprecation 字段有内容，告知用户该功能已弃用并包含弃用消息。建议他们查看排名更高（未弃用）的替代方案。

搜索行为细节

搜索范围

主要：完整文档（docpages-index.json）——150+ 页面，包含完整内容
次要：博客文章（query-index.json）——仅在找到少于 5 个文档结果时搜索

停用词（自动过滤）

以下常见词在搜索中被忽略：

冠词：the, a, an
连词：and, or, but
介词：in, on, at, to, for, of, with, by
AEM 特定：aem, cms, edge, delivery, services

缓存

索引文件在本地缓存 24 小时，位于 .claude/skills/docs-search/.cache/。这可以加速后续搜索。

示例

示例 1：查找区块文档

用户请求："How do I decorate blocks in aem.live?"

好的做法：

搜索：node .claude/skills/docs-search/scripts/search.js block decoration
查看前 3 个结果
WebFetch 最相关的：https://www.aem.live/developer/markup-sections-blocks
阅读完整内容并提供答案

差的做法：

改用 WebSearch（在无关结果上浪费时间）
不使用搜索脚本（可能错过最佳文档页面）

示例 2：了解 Metadata

用户请求："I need to add metadata to my pages"

好的做法：

搜索：node .claude/skills/docs-search/scripts/search.js metadata
注意顶部结果是 "/docs/bulk-metadata"（分数：63）
还看到 "/docs/metadata"（分数：30）
WebFetch 两者以了解页面级与批量 metadata
提供包含两种方法的全面答案

差的做法：

只阅读第一个结果而错过批量 metadata 选项
需要全面覆盖时不使用 --all

示例 3：弃用功能警告

用户请求："How do I use folder mapping?"

搜索结果：

[
  {
    "path": "/developer/authoring-path-mapping",
    "title": "Path mapping for AEM authoring",
    "relevanceScore": 51,
    "deprecation": null
  },
  {
    "path": "/developer/folder-mapping",
    "title": "Folder Mapping",
    "relevanceScore": 34.5,
    "deprecation": "Please contact us if you have a use case for folder mapping..."
  }
]

好的回应： "我找到了关于 folder mapping 的信息，但此功能已弃用。弃用通知说：'Please contact us if you have a use case for folder mapping...'。当前推荐的方法是 Path mapping for AEM authoring（顶部结果）。让我改为阅读该文档。"

差的回应：

忽略弃用警告并实现已弃用的功能
不提及更好的替代方案

重要提醒

始终检查弃用警告并提醒用户
使用 WebFetch 阅读完整页面——搜索结果仅用于找到正确的页面
从顶部 2-3 个结果开始，再扩展搜索
description 字段很有用——它通常写得很好且简洁
不要仅依赖 snippet——它们用于提供上下文，而非全面信息

技能介绍

用途