内容
# TaxonRouter
**用于真实运营的双二进制 GitHub 自动化工具。**
TaxonRouter 是一个 Apache 2.0 开源工具包，它汇集了：
1. **`taxonrouter-mcp`** — 用于程序化 GitHub ProjectsV2 管理（卡片、字段、选项）的 MCP stdio 服务器
2. **`taxonrouter-auto-tagger`** — 对 PR 进行分类并自动应用标签 + 项目字段的 webhook 守护进程
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ TaxonRouter (go.mod) │
│ │
│ pkg/ │
│ domain/ — 共享纯类型（无 I/O） │
│ github/ — 共享 GraphQL 客户端（JWT+gh 回退） │
│ rules/ — 表驱动分类器（纯净、无 I/O） │
│ │
│ internal/ │
│ mcp/ — MCP 工具处理程序 + stdio 传输 │
│ classifier/ — PR 分类引擎（规则 + LLM） │
│ apply/ — GitHub 写回管道 │
│ webhook/ — 具有 HMAC 验证的 webhook 接收器 │
│ adapter/ — 规则 + 混合规则+LLM 引擎 │
│ llm/ — LLM 提供商（OpenAI / Anthropic） │
│ │
│ cmd/ │
│ taxonrouter-mcp/ — MCP 二进制文件 │
│ taxonrouter-auto-tagger/ — webhook 守护进程二进制文件 │
└─────────────────────────────────────────────────────────────┘
```
## 快速入门
### 二进制安装
```bash
go install github.com/LOUST-PRO/TaxonRouter/cmd/taxonrouter-mcp@latest
go install github.com/LOUST-PRO/TaxonRouter/cmd/taxonrouter-auto-tagger@latest
```
### MCP 服务器（taxonrouter-mcp）
```bash
# 配置项目 ID
mkdir -p ~/.config/taxonrouter-mcp
cat > ~/.config/taxonrouter-mcp/config.toml <<'EOF'
project_id = "PVT_your_project_id_here"
default_limit = 20
max_limit = 100
cache_ttl = "5m"
EOF
# 运行
taxonrouter-mcp
```
**环境变量：**
| 变量 | 描述 |
|---|---|
| `GITHUB_APP_ID` | GitHub 应用 ID（启用 JWT 认证） |
| `GITHUB_APP_INSTALLATION_ID` | GitHub 应用安装 ID |
| `GITHUB_APP_PRIVATE_KEY_FILE` | `.pem` 私钥文件路径 |
| `GITHUB_TOKEN` | PAT 回退（如果没有应用凭证） |
| `LZT_GITHUB_PROJECTS_CONFIG` | 重写配置文件路径 |
### 自动标签守护进程（taxonrouter-auto-tagger）
```bash
# 环境
export WEBHOOK_SECRET="your_hmac_secret"
export GITHUB_TOKEN="ghp_your_token"
export GITHUB_PROJECT_NUMBER="42"
export LLM_PROVIDER="anthropic" # 或 "openai" 或 "none"（仅限规则）
export LLM_API_KEY="sk-ant-..."
export PORT="3013"
# 运行
taxonrouter-auto-tagger
```
**健康检查端点：**
- `GET /healthz` — 存活检查
- `GET /readyz` — 准备就绪检查 + 分类器烟雾测试
- `GET /admin/suggestions?since=RFC3339` — 手动审查队列
## GitHub 应用 vs PAT
**GitHub 应用（生产环境推荐）：**
```bash
export GITHUB_APP_ID=123456
export GITHUB_APP_INSTALLATION_ID=987654
export GITHUB_APP_PRIVATE_KEY_FILE=/path/to/app.private-key.pem
```
JWT 认证比 PAT 快约 50ms，并且支持细粒度仓库权限。
**PAT（回退）：**
```bash
export GITHUB_TOKEN="ghp_..."
```
## MCP 工具（taxonrouter-mcp）
### 读取工具（意图：`read`）
| 工具 | 描述 |
|---|---|
| `cards_list` | 列出项目卡片及其字段值。`limit` 1-100。 |
| `field_options` | 获取字段元数据 + 选项列表。缓存 5 分钟。 |
### 写入工具（意图：`mutate`）
| 工具 | 描述 |
|---|---|
| `cards_add_existing` | 通过节点 ID 将 PR/问题添加到项目中。 |
| `current_fields` | 读取卡片上的当前字段值（漂移检测）。 |
| `cards_update_fields` | 更新字段。接受选项名称（"In Progress"）或 ID（"47fc9ee4"）。 |
### 字段名称映射（自动标签）
分类器输出（例如 `Effort: S-hours`）通过环境变量映射到项目字段名称：
```bash
GITHUB_PROJECT_FIELD_MAPPING="Effort:Size,Phase:Status"
GITHUB_PROJECT_FIELD_VALUE_MAPPING="Size:S-hours=S,Size:M-hours=M"
```
## GitHub Actions 集成
### 自托管运行器（持久化守护进程）
在自托管运行器上以 systemd 服务运行 `taxonrouter-auto-tagger`：
```bash
sudo systemctl enable taxonrouter-auto-tagger
```
守护进程监听来自 GitHub 的 webhook 事件，并自动应用分类。
### GitHub 托管（通过 Actions 的事件驱动）
对于不支持持久化进程的 GitHub 托管运行器，请使用 `taxonrouter-mcp` 和 GitHub Actions：
```yaml
# .github/workflows/taxonrouter.yml
on:
pull_request:
types: [opened, synchronize]
jobs:
classify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.25'
- run: go install github.com/LOUST-PRO/TaxonRouter/cmd/taxonrouter-mcp@latest
- env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
WEBHOOK_SECRET: ${{ secrets.WEBHOOK_SECRET }}
- run: taxonrouter-mcp
# 通过 Claude Code MCP 代理或直接 stdio 连接
```
## 部署
### Docker
```dockerfile
FROM gcr.io/distroless/static:nonroot
COPY taxonrouter-auto-tagger /taxonrouter-auto-tagger
COPY taxonrouter-mcp /taxonrouter-mcp
ENTRYPOINT ["/taxonrouter-auto-tagger"]
```
### systemd 服务
```ini
[Unit]
Description=TaxonRouter 自动标签
After=network.target
[Service]
ExecStart=/usr/local/bin/taxonrouter-auto-tagger
Environment="PORT=3013"
Environment="WEBHOOK_SECRET=..."
EnvironmentFile=/etc/taxonrouter/env
Restart=always
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
## 安全
- HMAC-SHA256 webhook 签名验证
- 启动时检查 PEM 密钥权限（需要 0600）
- 在任何 GraphQL 调用之前，通过允许列表正则表达式验证字段/项目 ID
- 只读 MCP 工具在 `read` 意图中不可见；写入工具需要 `mutate` 意图
- 日志中没有机密；所有凭证均来自环境
## 许可证
Apache 2.0 — 请参阅 [LICENSE](LICENSE)
