docs-search

搜索 AEM 文档

概述

此技能可帮助你高效搜索完整的 aem.live 文档（文档和博客文章），避免将上下文浪费在无关页面上。使用提供的搜索脚本查找相关文档页面，然后获取并阅读最相关结果的完整内容。

何时使用此技能

在以下情况下使用此技能：

• 你需要了解 aem.live 的某项功能或概念
• 你已查阅项目代码库以了解背景
• 你已尝试基本的网络搜索，但没有找到相关的 aem.live 文档
• 你需要关于如何实现 aem.live 功能的技术指导
• 你想查找官方文档中的最佳实践或示例

请勿在以下情况下使用此技能：

• 你需要可复用的代码片段或区块示例（请改用 block-collection-and-party）
• 你已知道具体的文档 URL
• 你在查找一般的 Web 开发信息（而非 aem.live 专属信息）

如何使用此技能

步骤 1：确定关键词

确定 1～3 个与你的搜索内容相关的具体关键词。尽量具体，避免使用泛泛的词语。

好的关键词：

• “区块装饰”
• “元数据”
• “通用编辑器”
• “sidekick 插件”

不好的关键词：

• “aem”（过于宽泛，会被过滤为停用词）
• “如何构建网站”（范围过广）
• “the”（停用词）

步骤 2：运行搜索脚本

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

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

选项：

• --all：返回所有匹配结果（默认限制为最相关的 10 条）
• 不带 --all：返回排名前 10 的结果

示例：

# Search for block decoration info
node .claude/skills/docs-search/scripts/search.js block decoration

# Search for metadata with all results
node .claude/skills/docs-search/scripts/search.js --all metadata

# Multi-word search
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：获取并阅读完整文档

搜索结果可帮助你了解概况。若要获取详细信息，你必须获取并阅读完整的页面内容。

目标 URL 格式：

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

**获取方式：**使用你可用的任意方式获取完整的 HTML/文本内容：

• 专用网页获取工具
• 终端命令（curl、wget 等）
• 网页浏览/抓取功能

**最佳实践：**先从最相关的 2～3 条结果开始，完整阅读后再决定是否需要更多内容。你也可以访问文档中引用的链接，或根据所学内容进行额外搜索。

步骤 5：提醒用户注意已弃用内容

如果任何结果的 deprecation 字段包含内容，请告知用户该功能已弃用，并附上弃用信息。建议用户查看排名更高且未弃用的替代方案。

搜索范围

搜索脚本会优先搜索文档（150 多个页面）。只有在找到的文档结果少于 5 条时，才会搜索博客文章。如需全面覆盖博客内容，请使用 --all 标志。

示例

示例 1：查找区块文档

用户请求：“如何在 aem.live 中装饰区块？”

推荐做法：

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

不推荐做法：

• 改用通用网页搜索（会浪费时间查看不相关的结果）
• 不使用搜索脚本（可能会错过最合适的文档页面）

示例 2：了解元数据

用户请求：“我需要为页面添加元数据”

推荐做法：

1. 搜索：node .claude/skills/docs-search/scripts/search.js metadata
2. 注意到排名第一的结果是“/docs/bulk-metadata”（分数：63）
3. 还会看到“/docs/metadata”（分数：30）
4. 获取并阅读这两个页面，了解页面级元数据和批量元数据的区别
5. 同时介绍这两种方法，提供全面的答案

不推荐做法：

• 只阅读第一个结果，错过批量元数据选项
• 需要全面了解时不使用 --all

示例 3：已弃用功能警告

用户请求：“如何使用文件夹映射？”

搜索结果：

[
  {
    "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..."
  }
]

推荐回复： “我找到了有关文件夹映射的信息，但此功能已弃用。弃用通知中写道：‘如果您有文件夹映射的使用场景，请联系我们……’。目前建议采用的方法是用于 AEM 创作的路径映射（排名第一的结果）。我来为您阅读相关文档。”

不推荐做法：

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

相关技能

• block-collection-and-party：需要可复用的代码示例或区块实现时使用
• building-blocks：从头开始创建新区块时使用
• content-modeling：为区块设计内容模型时使用

重要提醒

1. 始终检查弃用警告并提醒用户
2. 获取并阅读完整页面——搜索结果仅用于查找合适的页面
3. 先查看排名前 2～3 的结果，再扩大搜索范围
4. 描述字段很有用——通常写得清晰简洁
5. 不要只依赖摘要——摘要用于提供上下文，并不包含全面信息