内容
# GitHub 标签查找器
`github-tags` 是一个无依赖的 Python 命令行工具，用于查找 GitHub 上可接手的 issues。它默认搜索标记为 **good first issue** 或 **help wanted** 的开放 issues，然后允许您按编程语言、仓库、所有者、日期、分配状态或 GitHub 问题搜索 API 接受的任何原始限定符来缩小搜索结果。
尽管项目名称如此，但该工具搜索的是 issues 标签和元数据，而不是 Git 发布标签。
## 安装
需要 Python 3.10 或更新版本。
```bash
uv tool install .
github-tags --help
```
在不安装命令的情况下进行开发：
```bash
PYTHONPATH=src python -m github_tags_finder --help
```
## MCP 服务器
一个可选的 MCP 服务器向 MCP 客户端公开相同的搜索引擎。Codex 是目前已验证的客户端：
```bash
uv sync --extra mcp
uv run --extra mcp github-tags-mcp
```
它通过 STDIO 提供一个只读的 `search_github_issues` 工具，默认情况下还提供可流式传输的 HTTP 以便未来托管部署。参见通用的 [MCP 指南](docs/mcp/mcp.md) 和已验证的 [Codex 设置](docs/mcp/codex.md)。
## 示例
在 Python 仓库中找到默认的适合初学者的问题：
```bash
github-tags --language Python
```
搜索未分配的 Rust 解析器工作：
```bash
github-tags parser --language Rust --no-assignee
```
用项目特定的标签替换默认标签。重复 `--label` 匹配任何标签：
```bash
github-tags --language Go --label beginner --label mentorship
```
需要提供的每个标签：
```bash
github-tags --label bug --label confirmed --match-labels all
```
将搜索限制在仓库或组织：
```bash
github-tags --repo pallets/flask --repo pallets/click
github-tags --org apache --language Java
```
使用 GitHub 支持的任何限定符，但没有专用选项：
```bash
github-tags --qualifier 'comments:<5' --qualifier 'created:>=2026-01-01'
```
通过完整的查询绕过所有结构化默认值：
```bash
github-tags --raw-query 'is:issue is:open label:documentation no:assignee'
```
检查生成的查询而不发出请求：
```bash
github-tags --language TypeScript --no-assignee --query-only
```
生成机器可读的输出：
```bash
github-tags --language Python --limit 100 --json
```
## 身份验证
未经身份验证的搜索适用于公共仓库，但 API 请求限制较低。设置 `GITHUB_TOKEN` 或 `GH_TOKEN` 以进行身份验证请求：
```bash
cp .env.example .env
# 编辑 .env 并替换占位符。CLI 和 MCP 服务器加载它。
github-tags --language Python
```
令牌仅从环境中读取，因此它不会出现在 shell 进程参数中。`.env` 文件被 Git 忽略；只有占位符 `.env.example` 被跟踪。搜索公共资源不需要仓库权限。访问私有资源需要可以读取这些仓库的令牌。
可以通过 `GITHUB_API_URL` 或 `--api-url` 选择 GitHub Enterprise Server：
```bash
export GITHUB_API_URL=https://github.example.com/api/v3
github-tags --org my-company
```
## 搜索行为
生成的默认查询是：
```text
is:issue is:open archived:false label:"good first issue","help wanted"
```
标签之间的逗号是 GitHub 的 OR 语法。提供一个或多个 `--label` 选项会替换这两个默认值。使用 `--no-labels` 搜索时不使用标签过滤器。除非提供 `--include-archived`，否则排除存档仓库。
GitHub Search API 最多公开查询的第一个 1,000 个结果，因此 `--limit` 限制为 1,000。参见 GitHub 的 [问题搜索文档](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests)，了解支持的限定符。
## 开发
测试套件仅使用 Python 标准库：
```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```
## 许可证
Copyright 2026 thejonali. Licensed under the [Apache License 2.0](LICENSE).
