knowledge-explorer 是一个用于管理研究知识库的工具，知识库位于仓库根目录下的 research/ 目录，用于存放关于工具、库和框架的经过验证的研究条目。每个条目是分类子目录中的一个 .md 文件，例如 research/agent-frameworks/agno.md。主要的操作脚本为 research/knowledge-explorer.py，采用 PEP 723 格式，通过 uv run 运行。
基本信息
- 产品名称：knowledge-explorer
- 来源：jamie-bitflight/claude_skills
- 脚本路径：research/knowledge-explorer.py
- 运行方式：uv run research/knowledge-explorer.py [--verbose] <command> [args]
- 知识库根目录：research/（相对于仓库根目录）
主要能力与命令
list
浏览知识库中所有条目，按分类分组，并显示新鲜度元数据。
uv run research/knowledge-explorer.py list [--layer 0|1|2]
选项 --layer / -l 可按 SDLC 层级筛选（0=process、1=language、2=stack）。输出中每个条目显示文件名、版本、验证日期、下次审查日期，以及当 next_review 早于今天时的 [OVERDUE] 标记。分类会显示条目总数和逾期数量。不带子命令运行脚本也会调用 list。
show-template
打印旧版 skill-spec frontmatter 模板。
uv run research/knowledge-explorer.py show-template
fetch-github
通过 gh CLI 抓取 GitHub 仓库的 README 和 docs/ 内容，并生成知识库条目草稿。
uv run research/knowledge-explorer.py fetch-github <owner/repo> [--output <path>] [--category <cat>]
需要安装并认证 gh CLI（gh auth login）。选项 --output / -o 可将草稿写入文件；--category / -c 可覆盖推断的分类。抓取内容包括：通过 gh api repos/{slug} 获取仓库元数据、通过 gh api repos/{slug}/releases/latest 获取最新发布标签（404 表示无发布，静默跳过）、根目录列表以检测 docs/ 或 doc/ 子目录、通过 gh api repos/{slug}/readme 获取 README 内容（base64 解码）。若发现 docs 目录，会在草稿中的注释块内列出文件。分类推断会将 GitHub 仓库 topics 与有效分类匹配，无匹配时回退为 UNCATEGORIZED。使用后应检查草稿的分类、标签和描述，必要时编辑正文，再运行 add 命令。
add
将 frontmatter 条目文件归入正确的分类目录，并更新 README.md。
uv run research/knowledge-explorer.py add <file>
cat entry.md | uv run research/knowledge-explorer.py add
该命令会读取文件或 stdin，验证格式为 frontmatter、解析并校验所有必需字段；若描述为空会从正文首段自动生成（并发出警告）；校验 topic slug 与 category；检查目标路径是否存在 topic 冲突；将条目写入 research/<category>/<topic>.md，并更新 research/README.md 表格（更新失败只警告，不中止）。必需的 frontmatter 字段包括：name、description、metadata.topic、metadata.category、metadata.source_url、metadata.verified、metadata.next_review。退出码：0 成功，1 解析或写入错误，2 校验错误。
update-append
向现有知识库条目追加带日期的更新章节，会打开 $EDITOR 编辑更新内容。
uv run research/knowledge-explorer.py update-append <topic-slug>
该命令会搜索匹配 topic slug 的条目；若为 inline-header 格式则就地迁移为 frontmatter 格式；打开 $EDITOR 并显示占位符；若编辑器关闭时占位符未变或内容为空，则以退出码 0 中止；否则追加形如 ## Update: YYYY-MM-DD 的章节，将 verified 更新为今天、next_review 更新为今天加 90 天，并以原子方式写入。该命令需要交互式终端；在非交互场景下可设置 EDITOR 为可编程写入内容的脚本，或使用 VISUAL。若未找到 slug，会建议最多 3 个 Levenshtein 距离不超过 2 的备选。
generate-descriptions
为缺失、为空、被截断或由正文自动生成的知识库条目生成或修复 frontmatter description 字段。
uv run research/knowledge-explorer.py list-candidates
uv run research/knowledge-explorer.py list-candidates --all
uv run research/knowledge-explorer.py set-description <topic> "<description>"
list-candidates 输出为 JSON 数组，包含未通过描述质量启发式检查的条目，每项含 topic、file_path、name、category、tags、current_description、body。随后可为每个条目启动一个 Haiku 子代理并行生成描述，并通过 set-description 直接写入。set-description 退出码：0 成功（静默），1 topic 未找到，2 描述无效。--all 标志会包含所有条目，不论当前描述质量如何。描述规则：单行无换行、最多 1024 字符、前置说明知识库覆盖内容、包含具体触发关键词、格式为 {what it covers}. Use when {trigger scenarios}.、只输出描述字符串。写入后可用 uvx skilllint@latest check --fix <file> 校验。
migrate
在整个知识库范围内就地迁移旧格式条目到 skill-spec frontmatter。
uv run research/knowledge-explorer.py migrate [--dry-run]
选项 --dry-run 显示将要变更的内容而不写入，可随时安全运行。--all 迁移所有条目（默认）。处理的源格式包括：inline-header 格式、flat frontmatter 格式，以及已含 metadata.topic 的 skill-spec frontmatter（跳过）。输出汇总形如：Migrated: N Already done: M Failed: P。建议先以 --dry-run 预览。
Frontmatter 结构
旧版 skill-spec 格式如下：
---
name: kebab-case-tool-name
description: "..."
license: MIT
metadata:
topic: kebab-case-tool-name
category: developer-tools
source_url: https://...
github: owner/repo
version: "1.2.3"
verified: "2026-02-22"
next_review: "2026-05-23"
tags: "tag1,tag2"
---
关键约束：topic slug 为 1-64 字符，符合 [a-z0-9][a-z0-9-]*[a-z0-9] 或单字符，不能有连续连字符；描述最多 1024 字符；category 必须是有效分类的精确匹配；日期字段必须为带引号的字符串。
适用场景
- 维护工具、库和框架的验证研究知识库
- 浏览按分类组织的条目并跟踪审查逾期情况
- 从 GitHub 仓库自动生成研究条目草稿
- 批量生成或修复条目描述字段
- 将旧的条目格式迁移到统一的 frontmatter 格式
限制与说明
- 新增研究建议通过 /research-curator 流程进行；add、update-append 和 migrate 是旧路径，不会进行条目审查和交叉引用，仅用于其描述的机械操作。
- fetch-github 依赖已安装并认证的 gh CLI。
- update-append 需要交互式终端访问。
- 所有错误会以 Rich 面板形式输出到 stderr，使用 --verbose 可包含完整回溯。
- 错误类型包括：ExternalCommandError、TopicNotFoundError、TopicConflictError、ParseError、FrontmatterValidationError。