⚡

Duende文档管理技能Skill duende-docs

这个技能是用于自动化管理Duende软件文档的工具，包括文档爬取、索引构建、搜索功能和元数据管理。它帮助用户高效查找、解析和维护文档，防止链接腐烂，优化资源使用。关键词：文档管理、自动化、爬取、索引、搜索、Duende软件、SEO优化、DevOps。

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

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

Duende文档技能

关键: 路径加倍预防 - 强制性

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

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

必需解决方案（选择一种）:

  1. 始终使用绝对路径（推荐）
  2. 使用单独命令（永远不要cd与&&）
  3. 从仓库根目录运行使用相对路径

永远不要这样做:

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

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

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

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

必需: 始终为任何index.yaml访问使用manage_index.py脚本:

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技能进行常见工作流:

  • /duende-ecosystem:docs-ops scrape - 从llms-full.txt爬取Duende文档
  • /duende-ecosystem:docs-ops refresh - 刷新本地索引和元数据，无需爬取
  • /duende-ecosystem:docs-ops validate - 验证索引和引用的一致性
  • /duende-ecosystem:docs-ops rebuild-index - 强制重建搜索索引
  • /duende-ecosystem:docs-ops clear-cache - 清除文档搜索缓存

概述

该技能为Duende软件文档管理提供自动化工具。它管理:

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

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

何时使用此技能

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

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

工作流执行模式

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

委托策略

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

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

如何调用:

使用任务工具，带有:

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

执行模式

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

当任务代理执行脚本时:

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

错误和警告报告

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

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

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

快速开始

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

当您想在不爬取的情况下重建和验证本地索引/元数据时使用:

python plugins/duende-ecosystem/skills/duende-docs/scripts/management/refresh_index.py

爬取所有文档

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

# 从llms-full.txt爬取（所有产品在一个文件中）
python plugins/duende-ecosystem/skills/duende-docs/scripts/core/scrape_docs.py

# 爬取后刷新索引
python plugins/duende-ecosystem/skills/duende-docs/scripts/management/refresh_index.py

查找文档

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

# 通过关键词搜索（默认: 25个结果）
python plugins/duende-ecosystem/skills/duende-docs/scripts/core/find_docs.py search oauth dpop

# 自然语言搜索
python plugins/duende-ecosystem/skills/duende-docs/scripts/core/find_docs.py query "how to configure DPoP"

# 按类别列出
python plugins/duende-ecosystem/skills/duende-docs/scripts/core/find_docs.py category identityserver

# 按标签列出
python plugins/duende-ecosystem/skills/duende-docs/scripts/core/find_docs.py tag bff

搜索选项:

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

配置系统

duende-docs技能使用统一配置系统。

配置文件:

  • config/defaults.yaml - 包含所有默认值的中央配置文件
  • config/filtering.yaml - 内容过滤规则
  • config/tag_detection.yaml - 标签检测模式

环境变量覆盖:

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

依赖

必需: pyyaml, requests, filelock 可选（推荐）: yake（用于关键词提取）

Python版本: Python 3.11+ 推荐

核心能力

1. 爬取文档

从Duende llms-full.txt获取文档（所有产品的预渲染Markdown）。

2. 提取子节

提取特定的Markdown部分，用于令牌优化的响应。

3. 变更检测

通过404检查和哈希比较检测文档漂移。

4. 查找和解析文档

使用doc_id、关键词或自然语言查询发现和解析文档引用。

5. 索引管理和维护

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

平台特定要求

Windows用户

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

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

示例:

MSYS_NO_PATHCONV=1 python scripts/core/scrape_docs.py --filter "/identityserver/"

故障排除

Unicode编码错误

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

爬取期间的404错误

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

公共API

duende-docs技能为外部工具提供干净的公共API:

from duende_docs_api import (
    find_document,
    resolve_doc_id,
    get_docs_by_tag,
    get_docs_by_category,
    search_by_keywords,
    get_document_section,
    refresh_index
)

# 自然语言搜索
docs = find_document("DPoP token binding")

# 解析doc_id到元数据
doc = resolve_doc_id("duende-identityserver-dpop")

# 按标签获取文档
bff_docs = get_docs_by_tag("bff")

# 提取特定部分
section = get_document_section("duende-identityserver-overview", "Installation")

开发模式

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

启用开发模式

PowerShell:

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

Bash/Zsh:

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

验证模式

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

开发模式:

[DEV MODE] 使用本地插件: D:\repos\gh\melodic\claude-code-plugins

生产模式:

[PROD MODE] 使用已安装技能目录

禁用开发模式

PowerShell:

Remove-Item Env:DUENDE_DOCS_DEV_ROOT

Bash/Zsh:

unset DUENDE_DOCS_DEV_ROOT

目录结构

duende-docs/
  SKILL.md                    # 此文件（公开）
  duende_docs_api.py          # 公共API
  canonical/                  # 文档存储（私有）
    index.yaml                # 元数据索引
    duendesoftware-com/       # 基于域的存储
      identityserver/         # IdentityServer文档
      bff/                    # BFF文档
      accesstokenmanagement/  # 访问令牌管理文档
      identitymodel/          # IdentityModel文档
      identitymodel-oidcclient/ # OidcClient文档
      general/                # 通用信息文档
  scripts/                    # 实现（私有）
    core/                     # 爬取、发现
    management/               # 索引管理
    maintenance/              # 清理、漂移检测
    utils/                    # 共享实用程序
  config/                     # 配置
    defaults.yaml             # 默认设置
    filtering.yaml            # 内容过滤
    tag_detection.yaml        # 标签模式
  references/                 # 技术文档（公开）
    sources.json              # 文档源
  .cache/                     # 缓存存储（倒排索引）
  logs/                       # 日志文件

源

文档从Duende的llms-full.txt在https://docs.duendesoftware.com/llms-full.txt爬取。

文档类别

Duende文档组织为以下类别:

类别 描述
identityserver IdentityServer OAuth 2.0/OIDC框架文档
bff 后端-前端安全框架
accesstokenmanagement 访问令牌生命周期管理库
identitymodel 协议操作库
identitymodel-oidcclient 原生OIDC客户端库
general 许可、支持、词汇表、共享概念

标签

用于Duende文档的常见标签:

  • oauth - OAuth 2.0协议
  • oidc - OpenID Connect协议
  • openid-connect - OpenID Connect（别名）
  • tokens - 令牌处理
  • access-token - 访问令牌管理
  • refresh-token - 刷新令牌处理
  • bff - 后端-前端模式
  • spa - 单页应用程序安全
  • blazor - Blazor集成
  • aspnetcore - ASP.NET Core集成
  • dotnet - .NET框架
  • authentication - 认证流
  • authorization - 授权策略
  • dpop - DPoP令牌绑定
  • mtls - 相互TLS认证
  • client-credentials - 客户端凭据流
  • quickstart - 入门指南
  • sample-code - 代码示例和例子

测试场景

场景1: 关键词搜索

查询: “搜索DPoP文档” 预期行为:

  • 技能在关键词"DPoP"上激活
  • 从索引返回相关文档 成功标准: 用户收到匹配的文档条目

场景2: 自然语言查询

查询: “如何为Blazor配置IdentityServer？” 预期行为:

  • 技能在"IdentityServer"和"Blazor"上激活
  • 使用find_docs.py查询命令 成功标准: 返回带有配置步骤的相关文档

场景3: Doc ID解析

查询: “解析duende-identityserver-quickstart” 预期行为:

  • 解析doc_id到文件路径
  • 返回文档元数据 成功标准: 用户收到完整路径和文档内容

版本历史

  • v1.0.0 (2025-12-16): 初始发布 - 完整技能结构

最后更新

日期: 2025-12-16 模型: claude-opus-4-5-20251101

状态: 初始发布 - 准备从https://docs.duendesoftware.com/llms-full.txt爬取。