名称: gemini-cli-docs 描述: Gemini CLI所有文档的唯一真实来源和图书管理员。管理本地文档存储、抓取、发现和解析。当查找、定位、搜索或解析Gemini CLI文档时使用；通过关键词、类别、标签或自然语言查询发现文档；从llms.txt抓取；管理索引元数据（关键词、标签、别名）；或从文件系统重建索引。运行脚本来抓取、查找和解析文档。处理doc_id解析、关键词搜索、自然语言查询、类别/标签过滤、别名解析、llms.txt解析、Markdown子部分提取（内部使用）、基于哈希的漂移检测和全面索引维护。允许工具: Read, Glob, Grep, Bash

Gemini CLI 文档技能

关键：路径翻倍预防 - 强制

绝对禁止：在从该技能运行脚本时，永远不要在PowerShell中使用cd与&&。

问题： 如果当前工作目录已经在技能目录内，使用相对路径会导致PowerShell相对于当前目录解析路径，而不是仓库根目录，从而导致路径翻倍。

要求解决方案（选择一个）：

总是使用绝对路径（推荐）
使用单独命令（永远不要cd与&&）
从仓库根目录运行使用相对路径

永远不要这样做：

链式cd与&&：cd <相对路径> && python <脚本> 导致路径翻倍
假设当前目录
当当前目录在技能目录内时使用相对路径

关键：大文件处理 - 强制使用脚本

绝对禁止：永远不要在index.yaml文件上使用read_file工具

文件超过上下文限制并会导致问题。你必须使用脚本。

要求：总是使用manage_index.py脚本来访问index.yaml：

python scripts/management/manage_index.py count
python scripts/management/manage_index.py list
python scripts/management/manage_index.py get <doc_id>
python scripts/management/manage_index.py verify

所有脚本通过index_manager.py自动处理大文件。

可用斜杠命令

使用集成的docs-ops技能进行常见工作流：

/google-ecosystem:docs-ops scrape - 从geminicli.com抓取Gemini CLI文档，然后刷新索引并验证
/google-ecosystem:docs-ops refresh - 刷新本地索引和元数据，不从远程源抓取
/google-ecosystem:docs-ops validate - 验证索引和引用的一致性和漂移，不抓取
/google-ecosystem:docs-ops rebuild-index - 强制重建搜索索引
/google-ecosystem:docs-ops clear-cache - 清除文档搜索缓存

概述

该技能提供Gemini CLI文档管理的自动化工具。它管理：

规范存储（封装在技能中）- 官方文档的唯一真实来源
子部分提取 - 令牌优化的提取（节省60-90%）
漂移检测 - 基于哈希的验证，针对上游源
同步工作流 - 维护自动化
文档发现 - 基于关键词的搜索和doc_id解析
索引管理 - 元数据、关键词、标签、别名，用于弹性引用

核心价值： 防止链接失效，启用离线访问，优化令牌成本，自动化维护，并提供基于doc_id的弹性引用。

何时使用此技能

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

抓取文档 - 从geminicli.com的llms.txt获取文档
查找文档 - 通过关键词、类别或自然语言搜索文档
解析文档引用 - 将doc_id转换为文件路径
管理索引元数据 - 添加关键词、标签、别名，更新元数据
重建索引 - 从文件系统重新生成索引（处理重命名/移动）

工作流执行模式

关键：此部分定义如何在此技能中执行操作。

委托策略

默认方法：委托给任务代理

对于所有抓取、验证和索引操作，委托执行给通用任务代理。

如何调用：

使用任务工具，带有：

subagent_type: “general-purpose”
description: 简短的3-5词描述
prompt: 完整任务描述，包括执行指令

执行模式

脚本默认在前台运行。不要后台运行它们。

当任务代理执行脚本时：

直接运行：python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py --llms-txt https://geminicli.com/llms.txt
流式日志：脚本通过stdout自然发出进度
等待完成：脚本完成时退出，带有退出代码
永远不要使用run_in_background=true：脚本设计用于前台执行
永远不要轮询输出：流式日志自动出现，不需要BashOutput轮询
永远不要使用后台作业：没有&，没有nohup，没有后台进程管理

反模式检测

指示不正确执行的红色标志：

在Bash工具中使用run_in_background=true
在循环中重复调用BashOutput
使用ps或pgrep检查进程状态
手动轮询脚本输出
后台作业管理（&, nohup, jobs）
在任务代理完成后使用BashOutput

如果你识别这些模式，立即停止并纠正。

错误和警告报告

关键：报告所有错误、警告和问题 - 永远不要压制或忽略它们。

当通过任务代理执行脚本时：

报告脚本错误：退出代码、异常、错误消息
报告警告：弃用警告、导入问题、配置问题
报告意外输出：404、超时、验证失败
包括上下文：错误发生时正在执行什么

指示问题的红色标志：

非零退出代码
包含“ERROR”、“FAILED”、“Exception”、“Traceback”的行
“WARNING”或“WARN”消息
“404 Not Found”、“500 Internal Server Error”

快速开始

端到端刷新索引（无抓取）

当你想要重建和验证本地索引/元数据而不抓取时使用：

使用Python 3.13进行验证 - spaCy/Pydantic与Python 3.14+有兼容性问题

# 使用Python 3.13以获得与spaCy的完全兼容性
py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/management/manage_index.py refresh

抓取所有文档

当用户明确想要访问网络并抓取文档时使用：

# 从llms.txt抓取
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py \
  --llms-txt https://geminicli.com/llms.txt

# 抓取后刷新索引（使用Python 3.13）
py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/management/manage_index.py refresh

带选项：

# 跳过现有文件（增量更新）
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py \
  --llms-txt https://geminicli.com/llms.txt \
  --skip-existing

# 过滤到特定部分
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/scrape_docs.py \
  --llms-txt https://geminicli.com/llms.txt \
  --filter "/docs/"

查找文档

# 解析doc_id到文件路径
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py resolve <doc_id>

# 通过关键词搜索（默认：25个结果）
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py search checkpointing session

# 带自定义限制的搜索
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py --limit 10 search tools

# 自然语言搜索
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py query "how to use checkpointing"

# 按类别列出
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py category docs

# 按标签列出
python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/core/find_docs.py tag cli

搜索选项：

选项	默认	描述
`--limit N`	25	返回的最大结果数
`--no-limit`	-	返回所有匹配结果（无限制）
`--min-score N`	-	仅返回相关性分数 >= N 的结果
`--fast`	-	仅索引搜索（跳过内容grep）
`--json`	-	以JSON格式输出结果
`--verbose`	-	显示相关性分数

配置系统

gemini-cli-docs技能使用统一配置系统，具有单一真实来源。

配置文件：

config/defaults.yaml - 包含所有默认值的中央配置文件
config/config_registry.py - 具有环境变量支持的规范配置系统
config/filtering.yaml - 内容过滤规则
config/tag_detection.yaml - 标签检测模式
references/sources.json - 文档源配置

环境变量覆盖：

所有配置值都可以使用环境变量覆盖：GEMINI_DOCS_<SECTION>_<KEY>

完整详情： references/configuration.md

依赖项

必需： pyyaml, requests, beautifulsoup4, markdownify, filelock 可选（推荐）： spacy 与 en_core_web_sm 模型（用于关键词提取）

检查依赖项：

python plugins/google-ecosystem/skills/gemini-cli-docs/scripts/setup/check_dependencies.py

Python版本： 推荐Python 3.13（spaCy操作必需）

完整详情： references/dependencies.md

核心能力

1. 抓取文档

使用llms.txt格式从geminicli.com获取文档。功能：llms.txt解析、HTML到Markdown转换、自动元数据跟踪、基于URL的文件夹组织。

指南： references/capabilities/scraping-guide.md

2. 提取子部分

提取特定Markdown部分以进行令牌优化响应。功能：ATX风格标题结构解析、部分边界检测、来源frontmatter、令牌经济（典型节省60-90%）。

指南： references/capabilities/extraction-guide.md

3. 变更检测

通过404检查和哈希比较检测文档漂移。功能：404 URL检测、缺失文件检测、内容哈希比较、孤立文件检测、清理自动化。

指南： references/capabilities/change-detection-guide.md

4. 查找和解析文档

使用doc_id、关键词或自然语言查询发现和解析文档引用。功能：doc_id解析、基于关键词的搜索、自然语言查询处理、类别和标签过滤。

指南： references/capabilities/discovery-guide.md

5. 索引管理和维护

维护索引元数据、关键词、标签，并从文件系统重建索引。

指南： references/capabilities/index-management-guide.md

工作流

常见维护和操作工作流：

抓取Gemini CLI文档 - 从geminicli.com获取文档
刷新索引 - 更改后重建元数据
检测和清理漂移 - 查找和删除过时文档
添加文档类别 - 新文档部分入职

详细工作流： references/workflows.md

元数据和关键词审计工作流

快速验证：

py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/validation/quick_validate.py

搜索审计：

py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/validation/run_search_audit.py
py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/validation/analyze_search_audit.py

标签配置审计：

py -3.13 plugins/google-ecosystem/skills/gemini-cli-docs/scripts/validation/audit_tag_config.py

平台特定要求

Windows用户

必须使用PowerShell（推荐）或在Git Bash命令前加MSYS_NO_PATHCONV=1

Windows上的Git Bash将Unix路径转换为Windows路径，破坏过滤模式。

示例：

MSYS_NO_PATHCONV=1 python scripts/core/scrape_docs.py \
    --llms-txt https://geminicli.com/llms.txt \
    --filter "/docs/"

参见： references/troubleshooting.md#git-bash-path-conversion

故障排除

spaCy安装问题

问题： spaCy安装失败，使用Python 3.14+。

解决方案： 使用Python 3.13：

py -3.13 -m pip install spacy
py -3.13 -m spacy download en_core_web_sm

Unicode编码错误

状态： 已修复 - 脚本自动检测Windows并配置UTF-8编码。

抓取期间的404错误

状态： 预期 - 一些llms.txt条目可能引用尚不存在的文档。脚本优雅处理并继续。

完整故障排除： references/troubleshooting.md

公共API

gemini-cli-docs技能为外部工具提供干净的公共API：

from gemini_docs_api import (
    find_document,
    resolve_doc_id,
    get_docs_by_tag,
    get_docs_by_category,
    search_by_keywords,
    get_document_section,
    detect_drift,
    cleanup_drift,
    refresh_index
)

# 自然语言搜索
docs = find_document("model routing configuration")

# 解析doc_id到元数据
doc = resolve_doc_id("geminicli-com-docs-checkpointing")

# 按标签获取文档
cli_docs = get_docs_by_tag("cli")

# 提取特定部分
section = get_document_section("geminicli-com-docs-commands", "Built-in Commands")

# 检测漂移
drift = detect_drift(check_404s=True, check_hashes=True)

# 清理漂移（先干运行）
result = cleanup_drift(clean_404s=True, dry_run=True)

# 使用漂移检测刷新索引
result = refresh_index(check_drift=True, cleanup_drift=False)

插件维护

对于插件特定维护工作流：

参见： references/plugin-maintenance.md

快速参考：

更新工作流：抓取 -> 验证 -> 审查 -> 提交 -> 版本升级 -> 推送
版本升级：文档刷新补丁，新功能次要，破坏性更改主要
测试：在推送前运行manage_index.py verify并测试搜索

开发模式

在本地开发此插件时，您可能希望更改进入您的开发仓库，而不是已安装的插件位置。

启用开发模式

PowerShell：

$env:GEMINI_DOCS_DEV_ROOT = "D:\repos\gh\melodic\claude-code-plugins"

Bash/Zsh：

export GEMINI_DOCS_DEV_ROOT="/path/to/claude-code-plugins"

验证模式

当您运行任何主要脚本（抓取、刷新、重建）时，将显示模式横幅：

开发模式：

[DEV MODE] Using local plugin: D:\repos\gh\melodic\claude-code-plugins

生产模式：

[PROD MODE] Using installed skill directory

禁用开发模式