名称: 文档管理描述: 所有Claude官方文档的单一事实来源和图书馆员。管理本地文档存储、爬取、发现和解析。用于查找、定位、搜索或解析Claude文档；通过关键词、类别、标签或自然语言查询发现文档；从站点地图或文档地图爬取；管理索引元数据（关键词、标签、别名）；或从文件系统重建索引。运行脚本来爬取、查找和解析文档。处理文档ID解析、关键词搜索、自然语言查询、类别/标签过滤、别名解析、sitemap.xml解析、文档地图处理、Markdown子节提取（内部使用）、基于哈希的漂移检测和全面索引维护。允许工具: 读取、全局搜索、Grep、Bash、技能

Claude文档管理

🚨🚨🚨 强制：混合并行模式 🚨🚨🚨

停止 - 在使用此技能处理任何Claude Code文档查询之前：

如果您是主代理，您必须在同一消息中同时调用两个来源：

此技能 (文档管理) - 本地缓存，令牌高效

claude-code-guide子代理 - 实时网络搜索
[技能工具: 文档管理]
"查找关于{主题}的文档"

[任务工具: claude-code-guide] (同一消息 - 使用此确切提示)
"首先WebFetch https://code.claude.com/docs/en/claude_code_docs_map.md 以查找
关于{主题}的相关文档页面。然后WebFetch这些特定页面。仅在需要额外上下文时使用WebSearch。
不要使用技能工具（不可用）。
返回关键发现和来源URL。"
⚠️ 关键： claude-code-guide没有技能工具访问权限。始终提示它使用 WebSearch/WebFetch 显式地。如果您看到“无此工具：技能”错误，您提示错误。

这是自动的。不要等待用户要求。

如果您是子代理：在您的响应中注明主代理也应查询claude-code-guide。

🚨 关键：路径加倍预防 - 强制

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

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

必需解决方案（选择一个）：

✅ 始终使用辅助脚本（推荐 - 它们自动处理路径解析）
✅ 使用绝对路径解析（如果不使用辅助脚本）
✅ 使用单独命令（永不使用cd与&&）

永远不要这样做：

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

对于所有脚本： 始终从仓库根目录使用相对路径运行，或使用自动处理路径解析的辅助脚本。

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

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

文件超过25,000个令牌，始终失败。您必须使用脚本。

✅ 必需：始终使用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 <文档ID>
python scripts/management/manage_index.py verify

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

可用斜杠命令

使用统一的docs-ops技能处理常见工作流：

/claude-ecosystem:docs-ops scrape - 爬取所有配置的Claude文档来源，然后刷新索引和验证
/claude-ecosystem:docs-ops refresh - 刷新本地索引和元数据，不从远程来源爬取
/claude-ecosystem:docs-ops validate - 验证索引和引用的一致性和漂移，不爬取
/claude-ecosystem:docs-ops rebuild-index - 强制从文件系统重建搜索索引
/claude-ecosystem:docs-ops clear-cache - 清除文档搜索缓存

概述

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

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

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

快速参考：使用哪个命令

我想要…	命令	示例
通过关键词查找文档	`search`	`search skills progressive`
通过自然语言查找文档	`query`	`query "how to create skills"`
获取完整文档内容	`content`	`content code-claude-com-docs-en-skills`
获取特定部分	`content --section`	`content <文档ID> --section "metadata"`
解析文档ID为路径	`resolve`	`resolve code-claude-com-docs-en-skills`
查找相关文档	`related`	`related code-claude-com-docs-en-skills`
按类别列出文档	`category`	`category api`
按标签列出文档	`tag`	`tag skills`

关键工作流： search通过关键词 → 从结果获取文档ID → content通过文档ID

重要区别：

search和query接受灵活关键词（无需完整文档ID）
content、resolve和related需要完整文档ID（例如code-claude-com-docs-en-skills）

何时使用此技能

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

爬取文档 - 从站点地图或文档地图获取文档
查找文档 - 通过关键词、类别或自然语言搜索文档
解析文档引用 - 转换文档ID为文件路径
管理索引元数据 - 添加关键词、标签、别名，更新元数据
重建索引 - 从文件系统重新生成索引（处理重命名/移动）

混合并行文档策略

关键：此部分是Claude Code文档访问模式的权威来源。

架构约束

技能不能生成子代理。 只有主对话线程可以使用任务工具。

这意味着：

当主代理加载此技能 → 主代理还必须并行调用claude-code-guide
当子代理加载此技能 → 子代理应在响应中注明主代理应调用claude-code-guide以获取实时覆盖
当命令调用此技能 → 与主代理相同（命令在主上下文中运行）

调用者感知指导

如果您是主代理：

您必须在同一消息中同时调用此技能和claude-code-guide子代理
这是获取全面Claude Code文档覆盖的唯一方式

如果您是子代理：

您无法自己调用claude-code-guide（架构约束）
在您的响应中包含：“为全面覆盖，主代理还应查询claude-code-guide子代理”
继续使用本地缓存结果

始终并行模式（仅主代理）

⚠️ 强制默认行为 - 非可选：

当检测到任何Claude Code文档查询时，主代理必须自动：

调用文档管理技能（本地缓存）
在同一消息中生成claude-code-guide子代理（实时网络）

这是自动的。用户不需要要求它。

检测触发器

当用户询问以下内容时，自动使用两个来源：

Claude Code功能（钩子、技能、内存、MCP、插件、设置等）
如何在Claude Code中做某事
Claude Code配置或故障排除
Claude Code文档中的任何主题

同一消息并行调用

# 主代理在单个消息中发送两者（自动）：

[技能工具: 文档管理]
"查找关于{主题}的文档"

[任务工具: claude-code-guide] (同一消息 = 并行执行)
"首先WebFetch https://code.claude.com/docs/en/claude_code_docs_map.md 以查找
关于{主题}的相关文档页面。然后WebFetch这些特定页面。仅在需要额外上下文时使用WebSearch。
不要使用技能工具（不可用）。
返回关键发现和来源URL。"

重要： claude-code-guide是一个内置子代理，具有工具：Glob, Grep, Read, WebFetch, WebSearch。它没有技能工具 - 它设计用于网络搜索，而不是本地技能调用。始终提示它显式使用WebSearch/WebFetch。

合成步骤

两者完成后：

合并两个来源的结果
本地缓存提供类别上下文和令牌效率
实时搜索提供货币和缺口填补
注意来源之间的任何差异

两个文档来源

来源	调用方式	优势
`文档管理`（此技能）	`技能`工具	快速、令牌高效（60-90%节省）、分层类别、离线
`claude-code-guide`	`任务`工具	始终最新、网络搜索、获取实时URL

回退行为

插件未安装：仅使用claude-code-guide
实时搜索不可用：此技能提供完整本地缓存
两个来源不一致：标记差异，优先官方文档，调查

自动行为摘要

用户查询	发生什么（自动）
“钩子如何工作？”	两个来源自动调用
“CLAUDE.md语法是什么？”	两个来源自动调用
“帮助我设置MCP”	两个来源自动调用
任何Claude Code主题	两个来源自动调用

没有手动触发器。 这是Claude Code文档查询的默认行为。

三源故障排除模式

当故障排除错误、漏洞或意外行为时，并行使用三个来源：

来源	代理/技能	目的
官方文档	`文档管理`技能	正确用法、配置
GitHub问题	`claude-code-issue-researcher`代理	已知漏洞、变通方案
实时网络	`claude-code-guide`子代理	当前讨论

故障排除触发器（由钩子自动检测）：

“error”, “bug”, “broken”, “not working”, “fails”, “crash”
“debug”, “troubleshoot”, “workaround”, “issue”, “problem”
“doesn’t work”, “won’t work”, “can’t”, “isn’t firing”

claude-code-issue-researcher的示例提示：

在anthropics/claude-code中搜索GitHub问题：[错误/问题描述]。
检查开放和关闭的问题。报告问题编号、状态和任何变通方案。

正确子代理模式

当生成docs-researcher（或任何使用此技能的子代理）时，主代理还应同一消息生成claude-code-guide以获取全面覆盖：

# 主代理在单个消息中生成两者：

[任务工具: docs-researcher子代理]
"研究Claude Code内存/CLAUDE.md文件"

[任务工具: claude-code-guide子代理] (同一消息 = 并行)
"使用WebSearch查找code.claude.com上关于内存和
CLAUDE.md文件的当前Claude Code文档。返回关键发现和URL。"

# 两者完成后，合成结果

为什么两者？ docs-researcher使用本地缓存（快速、令牌高效），而claude-code-guide搜索实时网络（始终最新）。它们一起提供全面覆盖。

分层类别（来自docs_map.md）

索引包含来自官方Claude Code文档地图的类别层次：

类别	主题
入门	overview, quickstart, common-workflows
使用Claude Code构建	sub-agents, plugins, skills, hooks, mcp, output-styles
部署	amazon-bedrock, google-vertex-ai, sandboxing
管理	setup, iam, security, costs
配置	settings, vs-code, jetbrains, memory
参考	cli-reference, slash-commands, hooks
资源	troubleshooting, legal-and-compliance

类别存储在doc_map_category字段中。按类别查询：

resolver.get_by_category("使用Claude Code构建")  # 返回类别中所有文档
resolver.list_categories()  # 返回所有类别和计数

类别丰富

爬取后，从官方文档地图更新类别：

python scripts/core/enrich_categories.py           # 更新类别
python scripts/core/enrich_categories.py --dry-run # 预览更改

工作流执行模式

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

委托策略

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

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

如何调用：

使用任务工具，参数：

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

执行模式

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

当任务代理执行脚本时：

✅ 直接运行：python .claude/skills/docs-management/scripts/core/scrape_all_sources.py --parallel --skip-existing
✅ 流式日志：脚本通过stdout自然发出进度
✅ 等待完成：脚本完成时退出并返回退出代码
❌ 永不使用run_in_background=true：脚本设计为前台执行
❌ 永不轮询输出：流式日志自动出现，无需BashOutput轮询
❌ 永不使用后台作业：无&，无nohup，无后台进程管理

反模式检测

指示错误执行的红旗：

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

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

任务代理完成后

关键：当任务代理报告“完成”时，读取其报告并总结给用户。不要使用BashOutput。

正确工作流：

任务代理报告“完成（X工具使用 · Y令牌 · Z时间）”
✅ 读取代理的最终报告消息
✅ 总结代理的发现给用户
❌ 永不使用BashOutput“检查真实结果”
❌ 永不轮询或验证代理已报告的内容

错误和警告报告

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

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

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

指示问题的红旗：

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

爬取的领域特定报告

关键： 报告爬取结果时，按领域区分行为。

领域特定.md URL行为：

docs.claude.com和code.claude.com：这些领域成功提供.md URL
anthropic.com：这些领域不提供.md URL（预期404，配置try_markdown: false）

准确报告：

✅ 好（领域特定）：“docs.claude.com：97个URL使用直接.md（97跳过/未更改）。anthropic.com：164个URL使用HTML转换（158跳过/未更改）。”

❌ 坏（误导）：“所有.md URL尝试返回404（预期 - 这些是HTML页面）” ← 这是误导的，因为Claude领域成功使用.md URL

快速开始

刷新索引端到端（不爬取）

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

⚠️ 重要：验证使用Python 3.13 - spaCy/Pydantic与Python 3.14+有兼容性问题

# 使用Python 3.13以与spaCy完全兼容
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py

可选标志：

# 重建前检查缺失文件
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py --check-missing-files

# 重建后检测漂移（404、缺失文件）
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py --check-drift

# 检测并自动清理漂移
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py --check-drift --cleanup-drift

此脚本运行完整管道：

✅ 检查依赖项
✅（可选）检查缺失文件
✅ 从文件系统重建索引
✅ 提取所有文档的关键词和元数据
✅ 验证元数据覆盖
✅ 生成摘要报告
✅（可选）检测和清理漂移

预期运行时间：约20-30秒，约500个文档

爬取所有来源（由`/scrape-official-docs`使用）

当用户明确想要命中网络并爬取文档时使用：

Python版本要求

Python 3.14默认工作用于爬取
Python 3.13需要用于spaCy操作（关键词提取、元数据提取）

# 步骤1：爬取文档（Python 3.14+工作）
python .claude/skills/docs-management/scripts/core/scrape_all_sources.py \
  --parallel \
  --skip-existing

# 步骤2：爬取完成后立即运行验证
# ⚠️ 验证使用Python 3.13（spaCy兼容性）
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py

# 步骤3：清理过期的Anthropic文章（从sources.json读取max_age）
python .claude/skills/docs-management/scripts/maintenance/cleanup_old_anthropic_docs.py --execute

爬取后需要验证和清理

由于--auto-validate现在默认：False（为了速度），您必须在爬取后立即单独运行验证和清理。

可选：爬取后检测和清理漂移：

# 自动清理工作流（一个标志中检测和清理）
python .claude/skills/docs-management/scripts/core/scrape_all_sources.py \
  --parallel \
  --skip-existing \
  --auto-cleanup

# 然后验证（使用Python 3.13）
py -3.13 .claude/skills/docs-management/scripts/management/refresh_index.py

查找文档

⚠️ 关键：全局标志必须在子命令之前：

# ✅ 正确 - 全局标志在子命令之前
python find_docs.py --json --limit 10 search skills frontmatter

# ❌ 错误 - 全局标志在子命令之后（将失败并显示“无法识别的参数”）
python find_docs.py search skills frontmatter --json

示例：

# 解析文档ID为文件路径
python .claude/skills/docs-management/scripts/core/find_docs.py resolve <文档ID>

# 通过关键词搜索（默认：25个结果）
python .claude/skills/docs-management/scripts/core/find_docs.py search skills progressive-disclosure

# 自定义限制搜索（全局选项在子命令之前）
python .claude/skills/docs-management/scripts/core/find_docs.py --limit 10 search skills

# 无限制搜索（返回所有匹配结果）
python .claude/skills/docs-management/scripts/core/find_docs.py --no-limit search skills

# 最小分数阈值搜索（过滤低相关性结果）
python .claude/skills/docs-management/scripts/core/find_docs.py --min-score 20 search skills

# 自然语言搜索
python .claude/skills/docs-management/scripts/core/find_docs.py query "how to create skills"

# 按类别列出
python .claude/skills/docs-management/scripts/core/find_docs.py category api

# 按标签列出
python .claude/skills/docs-management/scripts/core/find_docs.py tag skills

搜索接受灵活关键词（无需完整文档ID）：

单个关键词：search skills
多个关键词：search skills progressive disclosure
部分词通过标记匹配工作：search skill匹配“skills”
单数/复数自动处理：“skill”匹配“skills”
查询中自动删除停用词：“how”、“to”、“the”等

搜索选项：

选项	默认	描述
`--limit N`	25	返回的最大结果数
`--no-limit`	-	返回所有匹配结果（无限制）
`--min-score N`	-	仅返回相关性分数 >= N 的结果
`--fast`	-	仅索引搜索（跳过内容grep）
`--separate`	-	分开显示索引匹配和内容匹配
`--no-context`	-	在内容匹配中隐藏grep上下文行
`--clear-cache`	-	操作前重建搜索缓存
`--category`	-	按类别过滤结果
`--tags`	-	按标签过滤结果
`--json`	-	输出结果为JSON
`--verbose`	-	显示相关性分数用于调试

结果被截断时，输出显示“显示X个，共Y个”以指示更多结果可用。

混合搜索（默认行为）

默认情况下，search执行两者索引和内容搜索：

索引搜索 - 快速关键词匹配文档元数据（标题、描述、关键词、标签）
内容搜索 - Grep实际文件内容以查找不在索引中的匹配

结果标记：

[子节] - 在特定文档部分找到匹配（点击提取）
[内容] - 在文件内容中找到匹配（不在元数据索引中）
无标记 - 标准索引匹配

性能选项：

使用--fast进行仅索引搜索（更快，但可能错过仅内容匹配）
使用--separate在单独部分显示索引和内容匹配

搜索评分

结果通过多因素评分系统排名：

标题匹配（最高权重，14分）
描述匹配（10分）
关键词字段匹配（8-10分，带变体检测）
标签匹配（5-7分）
覆盖乘数（1.5-2.0x用于多术语匹配）
领域加权（Claude Code文档优先于一般Anthropic文档）

使用--verbose查看分数以调试相关性问题。

find_docs.py命令参考

命令	目的	子节支持
`resolve <文档ID>`	解析文档ID为文件路径	❌ 否
`content <文档ID>`	获取文档内容	✅ 是（`--section`）
`search <关键词>`	关键词搜索	❌ 否
`query "<文本>"`	自然语言搜索	❌ 否
`category <名称>`	按类别列出文档	❌ 否
`tag <名称>`	按标签列出文档	❌ 否
`related <文档ID>`	查找相关文档	❌ 否

相关文档示例：

# 查找与技能文档相关的文档
python .claude/skills/docs-management/scripts/core/find_docs.py related code-claude-com-docs-en-skills

# 限制结果
python .claude/skills/docs-management/scripts/core/find_docs.py --limit 5 related code-claude-com-docs-en-skills

相关文档通过共享标签（3x权重）和共享关键词（2x权重）评分。

子节提取（令牌优化）

从文档中提取特定部分（60-90%令牌节省）：

选项1：使用find_docs.py内容命令：

python scripts/core/find_docs.py content code-claude-com-docs-en-skills --section "可用元数据字段"

选项2：使用get_subsection_content.py（专用脚本）：

python scripts/core/get_subsection_content.py code-claude-com-docs-en-skills \
  --section "可用元数据字段"

发现可用部分（--list-sections）：

# 列出文档中的所有部分
python scripts/core/get_subsection_content.py code-claude-com-docs-en-skills --list-sections

# 输出显示带标题级别的分层结构
#   # 代理技能
#     ## 创建您的第一个技能
#     ## 技能如何工作
#       ### 技能存储位置

模糊部分匹配：

部分名称支持模糊匹配 - 部分或词重叠匹配工作：

# 精确：“可用元数据字段”
# 模糊：“metadata fields” -> 匹配“可用元数据字段”
# 模糊：“tool access” -> 匹配“使用allowed-tools限制工具访问”

python scripts/core/get_subsection_content.py code-claude-com-docs-en-skills   --section "metadata fields"
# 输出：模糊匹配：'metadata fields' -> '可用元数据字段'

注意： resolve命令仅返回文件路径。使用content获取实际文档内容，带可选部分提取。

配置系统

文档管理技能使用统一配置系统，具有单一事实来源。

配置文件：

config/defaults.yaml - 具有所有默认值的中央配置文件
config/config_registry.py - 具有环境变量支持的规范配置系统
references/sources.json - 文档来源配置（爬取所需）

路径配置：

所有路径配置在config/defaults.yaml的paths部分下。

环境变量覆盖：

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

完整详情： references/technical-details.md#configuration

依赖和环境

必需： pyyaml, requests, beautifulsoup4, markdownify 可选（推荐）： spacy, yake（用于增强关键词提取）

快速设置：

python .claude/skills/docs-management/scripts/setup/setup_dependencies.py --install-required

自动安装： extract-keywords命令如果缺少可选依赖项，自动安装它们。

完整详情： references/technical-details.md#dependencies

核心能力

1. 爬取文档

从官方来源获取文档并存储在规范存储中。功能：站点地图/文档地图解析、HTML→Markdown转换、直接.md URL获取（30-40%令牌节省）、自动元数据跟踪、基于领域的文件夹组织。

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

2. 提取子节（内部使用）

提取特定Markdown部分用于内部技能操作。功能：ATX风格标题结构解析、部分边界检测、来源frontmatter、令牌经济（典型60-90%节省）。

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

3. 变更检测

检测站点地图中的新文档和移除的文档页面，并通过哈希比较检测内容变更。功能：新/移除页面检测、内容哈希比较、自动陈旧标记、变更报告和审计日志。

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

4. 查找和解析文档

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

5. 索引管理和维护

维护索引元数据、关键词、标签，并从文件系统重建索引。脚本：manage_index.py, rebuild_index.py, generate_report.py, verify_index.py。

6. 基于年龄的清理

根据published_at日期移除过期的文档。Anthropic来源（工程、新闻、研究）在references/sources.json中配置了max_age_days阈值。超过此阈值的文章在爬取期间被跳过；此清理移除任何先前爬取但此后过期的文章。

# 清理过期的Anthropic文章（默认干运行）
# 自动从sources.json读取max_age_days
python scripts/maintenance/cleanup_old_anthropic_docs.py

# 执行清理（实际删除文件）
python scripts/maintenance/cleanup_old_anthropic_docs.py --execute

# 如果需要，用自定义年龄阈值覆盖
python scripts/maintenance/cleanup_old_anthropic_docs.py --max-age 90 --execute

这应在爬取和验证后运行，以确保规范目录保持清洁。

工作流

文档管理的常见维护和操作工作流：

添加新文档来源 - 从站点地图或文档地图载入新文档
爬取多个来源 - 验证检查点以防止浪费时间和令牌
令牌优化子节检索 - 提取子节而不是完整文档的工作流

详细工作流： references/workflows.md

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

轻量级审计：

py -3.13 .claude/skills/docs-management/scripts/validation/validate_index_vs_docs.py --summary-only

标签配置审计：

py -3.13 .claude/skills/docs-management/scripts/validation/audit_tag_config.py --summary-only

完整详情： references/workflows.md#metadata–keyword-audit

平台特定要求

Windows用户

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

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

参见： 故障排除指南

故障排除

spaCy安装问题

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

解决方案： 脚本自动检测并使用Python 3.13（如果可用）。无需手动干预！

如果Python 3.13不可用： 安装Python 3.13：

Windows：winget install --id Python.Python.3.13 -e --source winget
macOS：brew install python@3.13
Linux：sudo apt install python3.13

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

公共API

文档管理技能提供外部工具的干净公共API：

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

完整API文档： 参见原始SKILL.md中的公共API部分

插件维护

对于插件特定维护工作流（版本控制、发布更新、变更日志）：

参见： references/plugin-maintenance.md

快速参考：

更新工作流：爬取 → 验证 → 审查 → 提交 → 版本提升 → 推送
版本提升：文档刷新补丁，新来源/功能次版本，重大变更主版本
测试：推送前运行manage_index.py verify并测试搜索

开发模式

当本地开发此插件时，您可能希望更改到您的开发仓库，而不是安装的插件位置。此技能通过环境变量支持显式开发/生产模式分离。

工作原理

默认情况下，脚本写入插件安装的位置（通常~/.claude/plugins/marketplaces/...）。当OFFICIAL_DOCS_DEV_ROOT设置为有效的技能目录时，所有路径解析到该位置。

启用开发模式

一次性设置：

# 导航到您的开发仓库技能目录
cd /path/to/your/claude-code-plugins/plugins/claude-ecosystem/skills/docs-management

# 为您的shell生成shell命令
python scripts/setup/enable_dev_mode.py

PowerShell：

$env:OFFICIAL_DOCS_DEV_ROOT = "D:\repos\gh\claude-code-plugins\plugins\claude-ecosystem\skills\docs-management"

Bash/Zsh：

export OFFICIAL_DOCS_DEV_ROOT="/path/to/claude-code-plugins/plugins/claude-ecosystem/skills/docs-management"

验证模式

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

开发模式：

[开发模式] 使用开发技能目录：
  D:\repos\gh\claude-code-plugins\plugins\claude-ecosystem\skills\docs-management
  通过设置：OFFICIAL_DOCS_DEV_ROOT
规范目录：D:\...\canonical

生产模式：

[生产模式] 使用安装的技能目录
  （设置OFFICIAL_DOCS_DEV_ROOT以启用开发模式）

开发工作流

在终端中设置OFFICIAL_DOCS_DEV_ROOT
运行脚本 - 输出到开发仓库
跟踪更改：git diff canonical/
准备就绪时提交和推送

禁用开发模式