自动搜索热门 Skills 工程

这是一个本地可运行的 Python CLI 工程，用来从 GitHub 搜索热门的 Codex / AI skills 仓库，评估安全风险，自动分类，并生成 Markdown 榜单和 JSON 数据。

功能概览

• 搜索 GitHub 上与 skill、codex、agent、ai 相关的仓库
• 过滤明显不相关的结果
• 计算热门度分数
• 扫描公开内容中的安全风险信号
• 按用途自动分类
• 生成总榜、分类榜和结构化 JSON 输出

环境要求

• Windows PowerShell
• Python 3.11 及以上
• 当前项目已验证可通过 py 启动器运行

检查 Python：

py --version

快速开始

1. 进入项目目录

cd D:\code\自动skills搜索

2. 配置 GitHub Token

复制示例文件并填写 token：

Copy-Item .env.example .env

然后编辑 .env，填入：

GITHUB_TOKEN=github_pat_xxxxxxxxxxxxxxxxxxxx

说明：

• 公开仓库场景建议使用 Fine-grained personal access token
• 当前项目只读 GitHub 数据，不需要写权限
• 没有 token 也能运行，但 GitHub 限流会让搜索覆盖变少

更详细的 token 说明见 TOKEN_SETUP.md。

3. 直接运行

这是最稳妥的运行方式，不依赖安装：

$env:PYTHONPATH='src'
py -m hot_skills_search --limit 20 --per-category-limit 5 --include-risk-details

运行成功后会在 output/ 目录生成：

• hot-skills.md
• hot-skills.json

常用命令

查看帮助

$env:PYTHONPATH='src'
py -m hot_skills_search --help

生成默认榜单

$env:PYTHONPATH='src'
py -m hot_skills_search

指定榜单数量

$env:PYTHONPATH='src'
py -m hot_skills_search --limit 30 --per-category-limit 8

输出详细风险原因

$env:PYTHONPATH='src'
py -m hot_skills_search --include-risk-details

自定义候选池大小

$env:PYTHONPATH='src'
py -m hot_skills_search --candidate-pool-size 60

指定输出目录

$env:PYTHONPATH='src'
py -m hot_skills_search --output-dir custom-output

可选：虚拟环境运行

如果你希望在独立环境里执行：

py -m venv .venv
.\.venv\Scripts\Activate.ps1
py --version

然后继续用上面的 py -m hot_skills_search 方式运行。

可选：可编辑安装

如果你希望使用脚本命令 search-skills：

py -m pip install -e .
search-skills --limit 20 --per-category-limit 5 --include-risk-details

如果本机没有启用 pip，可以继续使用 py -m hot_skills_search，不影响功能。

输出说明

Markdown 榜单

文件：output/hot-skills.md

包含：

• 生成时间
• 全局热门总榜
• 分类总览
• 各分类 Top 榜单
• 风险说明和评分说明

JSON 数据

文件：output/hot-skills.json

每条记录至少包含：

• 仓库名和链接
• Stars / Forks
• 更新时间
• 热门度分数
• 风险等级和风险原因
• 分类和分类依据
• 命中的相关性关键词

配置说明

默认配置文件位于：

config/default_profile.json

可以在这里调整：

• 搜索关键词
• 排除词
• 热门度权重
• 风险规则与阈值
• 分类关键词

如果你新增了其他配置文件，例如 config/custom.json，可以这样运行：

$env:PYTHONPATH='src'
py -m hot_skills_search --query-profile custom

运行测试

$env:PYTHONPATH='src'
py -m unittest discover -s tests -v

常见问题

1. 没有生成很多结果

常见原因：

• 没有配置 GITHUB_TOKEN
• GitHub 未认证限流
• 当前搜索词比较严格
• 候选池过小

可以尝试：

• 配置 .env 中的 GITHUB_TOKEN
• 增大 --candidate-pool-size
• 调整 config/default_profile.json

2. 分类不符合预期

当前分类采用关键词规则，不是模型推理。可以直接修改 config/default_profile.json 里的 categories。

3. 某些仓库风险被判得太高或太低

当前风险判断只基于公开文本中的静态信号。你可以在 config/default_profile.json 中调整：

• risk_rules
• risk_thresholds

4. 终端里中文显示乱码

这是 PowerShell 编码显示问题，通常不影响程序生成的文件内容。可以优先直接打开 output/hot-skills.md 查看结果。