⚡

文档运维Skill docs-ops

这个技能用于管理Claude Code文档的生命周期，支持抓取、验证、刷新、重建索引和清除缓存等操作，确保文档索引的完整性和可用性。关键词：文档管理、Claude Code、抓取、索引、验证、SEO。

DevOps 0 次安装 0 次浏览 更新于 3/11/2026

name: docs-ops description: “管理Claude Code文档生命周期。动作：抓取、验证、刷新、重建索引、清除缓存。” argument-hint: <action> (scrape|validate|refresh|rebuild-index|clear-cache) [options] allowed-tools: Read, Write, Bash, Skill, Glob, Grep, Task, WebFetch, WebSearch

Claude Code 文档操作

通过单个整合技能管理Claude Code文档生命周期。

参数路由

动作 描述
scrape 从官方源抓取文档，然后刷新和验证
validate 验证索引完整性和检测漂移（只读）
refresh 从文件系统刷新索引，无需抓取
rebuild-index 清除并立即重建搜索索引
clear-cache 清除搜索缓存（在下一次搜索时懒重建）

解析 $ARGUMENTS 以确定动作。第一个令牌是动作关键字。剩余令牌作为选项传递给动作处理程序。

动作: scrape

从官方源抓取Claude文档并运行完整的抓取后工作流程（索引刷新和验证）。

语义

  • 此动作 始终执行至少一个文档源的实际抓取。
  • 默认行为：
    • 抓取 所有配置的官方源（Claude docs、Claude Code docs、Anthropic docs），跳过未更改的文档。
    • 刷新本地索引和元数据。
    • 验证一切看起来健康。

默认工作流程

当无限定符调用时：

  1. 调用 claude-ecosystem:docs-management 技能。

  2. 使用自然语言请求抓取：

    请抓取所有配置的Claude文档源。跳过未更改的文档，然后刷新本地索引和元数据并验证。验证后，清理过期的Anthropic文章（超过配置的max_age_days阈值）。在前台运行以便我们可以看到进度。

重要：使用Python 3.13进行验证（py -3.13）因为spaCy兼容性。Python 3.14可用于抓取。

  3. 让技能根据其SKILL.md指导决定运行哪些脚本。

范围标志（自然语言）

使用自然语言缩小范围：

  • 按域：“仅抓取docs.claude.com，然后刷新索引。”
  • 按类别：“仅抓取docs.claude.com的/en/api/。”
  • 抓取后行为：
    • scrape-only：跳过索引刷新和验证。
    • scrape+refresh：抓取并刷新索引（默认）。
    • scrape+detect-drift：抓取并检测漂移（404s、缺失文件）。
    • scrape+auto-cleanup：抓取并自动清理漂移。
    • scrape+age-cleanup：抓取、刷新并移除过期的Anthropic文章。

此动作不应执行的操作

  • 切勿运行仅验证或仅索引工作流程。
  • 切勿在后台运行抓取与轮询循环。
  • 切勿在抓取期间进行临时脚本编辑。

准确报告

按域区分：

准确报告每域统计。

动作: validate

验证Claude文档索引完整性和检测漂移。这是只读的 - 不进行更改。

执行的检查

  • 索引完整性（文件存在性）
  • 漂移检测（404s、哈希不匹配）
  • 元数据覆盖
  • 缺失文件

指令

调用 claude-ecosystem:docs-management 技能以验证文档索引。

请求验证报告包括任何检测到的问题或漂移。

动作: refresh

无需网络抓取刷新本地Claude文档索引。

目的

当您想要时使用此动作：

  • 从文件系统重建索引
  • 提取关键词和元数据
  • 验证元数据覆盖
  • 生成摘要报告

对于完整抓取 + 刷新，请使用 scrape 动作代替。

指令

调用 claude-ecosystem:docs-management 技能以刷新本地文档索引。

从技能请求索引重建和元数据验证。

注意： 由于spaCy兼容性，使用Python 3.13进行此动作：

请刷新本地文档索引并验证元数据。使用Python 3.13（py -3.13）因为spaCy兼容性。

动作: rebuild-index

清除并立即重建docs-management搜索索引。这比 clear-cache + 等待下一次搜索更快，因为它立即触发重建。

何时使用

  • 手动编辑 index.yaml 或文档文件后
  • 当搜索结果看起来陈旧或不正确时
  • 在 git pull 后文档更改后
  • 当您需要搜索立即工作时（不是在下一次查询）

与clear-cache的区别

动作 行为 搜索可用性
clear-cache 仅清除缓存 在下一次搜索时重建（懒）
rebuild-index 清除 + 重建 立即（急）

选项

  • 无选项：显示计划并请求确认
  • –force：跳过确认并立即重建

指令

此动作清除文档搜索缓存并立即重建索引。

检查当前状态

首先，通过运行缓存管理器信息命令检查当前缓存状态。报告缓存是否存在、是否有效以及上次构建时间。

请求确认

除非用户传递了 --force，否则显示重建计划与当前缓存状态，并在继续前请求确认。解释重建需要几秒钟，搜索在重建期间不可用。

清除和重建

一旦确认（或如果传递了 --force）：

  1. 使用缓存管理器脚本清除缓存
  2. 通过运行搜索查询通过find_docs.py触发立即重建
  3. 通过检查新缓存信息验证重建成功

报告结果

报告新索引统计包括文档数量、索引术语和构建时间。确认搜索现在可用。

## 索引已重建

成功重建Claude Code文档搜索索引。

**新索引统计：**
- 大小：1.8 MB
- 索引术语：6,020
- 文档：451
- 标签：33
- 类别：16
- 构建时间：45ms

**搜索现在可用。**

重建触发器

索引在以下情况下自动重建：

  • 向find_docs.py传递 --clear-cache 标志
  • cache_version.json 缺失或无效
  • index.yaml 内容哈希更改
  • 插件脚本更改（插件指纹哈希）

缓存验证

cache_manager.py 使用内容哈希（不仅是mtime）检测更改。这正确处理git操作，其中mtime更改但内容不变。

动作: clear-cache

清除docs-management搜索缓存（倒排索引）。这强制索引在下一次文档搜索时重建。

何时使用

  • 手动编辑 index.yaml 后
  • 当搜索结果看起来陈旧或不正确时
  • 在 git pull 后文档更改后
  • 释放磁盘空间（约1.8 MB）

选项

  • 无选项：显示将清除什么并请求确认
  • –force：跳过确认并立即清除

步骤1: 解析选项

检查是否出现 --force 标志。

force_mode = "--force" in arguments (case-insensitive)

步骤2: 定位缓存目录

docs-management缓存位于：

~/.claude/plugins/cache/<marketplace>/claude-ecosystem/<version>/skills/docs-management/.cache/

检测方法：

  1. 从 ~/.claude/plugins/installed_plugins.json 找到已安装的claude-ecosystem插件路径
  2. 导航到 skills/docs-management/.cache/

步骤3: 检查缓存状态

列出缓存文件及其大小：

文件 目的
inverted_index.json 搜索索引（约1.8 MB）
cache_version.json 基于哈希的有效性跟踪

如果缓存目录不存在或为空，报告：“缓存已清除。无事可做。”

步骤4: 确认（除非–force）

如果NOT force_mode，显示缓存清除计划：

## 缓存清除计划

**目标：** Claude Code文档搜索索引

| 文件 | 大小 |
|------|------|
| inverted_index.json | X.X MB |
| cache_version.json | 512字节 |

**总计：** X.X MB

> **注意：** 搜索索引将在下一次文档搜索时自动重建。
> 对于立即重建，请在清除后使用 `rebuild-index` 动作。

**继续？** 回复"yes"以继续，或使用 `--force` 跳过此确认。

等待用户确认。如果用户不确认，中止：“缓存清除取消。”

步骤5: 清除缓存

使用cache_manager.py脚本清除倒排索引：

python "<install_path>/skills/docs-management/scripts/utils/cache_manager.py" --clear

或手动删除缓存文件：

rm -f "<cache_dir>/inverted_index.json"
rm -f "<cache_dir>/cache_version.json"

步骤6: 报告成功

## 缓存已清除

成功清除Claude Code文档搜索缓存。

**清除：**
- inverted_index.json (X.X MB)
- cache_version.json

**下一步：**
- 搜索索引将在下一次搜索时自动重建
- 或使用 `rebuild-index` 动作立即重建

错误处理

  • 缓存未找到： 报告"缓存已清除或插件未安装。"
  • 权限拒绝： 报告"权限拒绝。尝试以提升权限运行。"
  • 插件未安装： 报告"claude-ecosystem插件未找到。使用 /plugin install claude-ecosystem@<marketplace> 安装。"

跨平台笔记

  • 使用正斜杠在路径中保持一致
  • Windows：~ 解析为 %USERPROFILE%
  • cache_manager.py脚本内部处理平台差异