# TeleWatchdog

`TeleWatchdog` 是一个基于 `Cloudflare Workers` 的 Telegram 入群申请审核机器人项目，适用于需要“申请加入”模式的群组。

它的核心流程很简单：

1. 检查申请人是否有头像。
2. 检查申请人是否有 `bio`。
3. 只要头像或 `bio` 缺失，直接进入验证。
4. 如果两者都存在，则调用 AI 做二分类判断。
5. AI 返回 `approve` 时，直接通过入群申请。
6. AI 返回 `challenge` 时，发送验证消息，让用户完成验证。

需要验证的用户可以二选一：

- `Cloudflare Turnstile`
- `Telegram WebApp BiometricManager` 生物识别

如果 10 分钟内没有完成验证，定时任务会自动拒绝申请，并清理消息和 KV 记录。

## 功能特性

- 支持 Telegram `chat_join_request` webhook
- 基于 `Cloudflare Worker` 部署
- Telegram 小程序验证页
- `Cloudflare Turnstile` 人机验证
- Telegram 原生生物识别验证
- AI 二分类审核
- 验证超时自动清理
- 验证成功或超时后自动删除验证消息

## 技术栈

- `Cloudflare Workers`
- `Cloudflare KV`
- `Telegram Bot API`
- `Cloudflare Turnstile`
- OpenAI 兼容聊天补全接口

## 项目结构

```text
src/index.ts           Worker 主逻辑
package.json           项目配置与脚本
tsconfig.json          TypeScript 配置
wrangler.toml.example  Wrangler 示例配置
```

## 需要的 Secrets

使用 `wrangler secret put` 写入：

- `BOT_TOKEN`
- `TG_WEBHOOK_SECRET`
- `AI_BASE_URL`
- `AI_API_KEY`
- `TURNSTILE_SECRET`

## 需要的变量

在 `wrangler.toml` 中配置：

- `AI_MODEL`
- `TURNSTILE_SITE_KEY`
- `VERIFICATION_ORIGIN`

## 创建 KV

先创建 KV namespace：

```bash
npx wrangler kv namespace create PENDING_JOINS
```

然后把返回的 namespace id 填进你的 `wrangler.toml`。

## 本地使用

```bash
npm install
copy wrangler.toml.example wrangler.toml
```

然后编辑 `wrangler.toml`，填入你自己的真实配置。

## 部署

```bash
npx wrangler deploy
```

## 配置 Telegram Webhook

部署完成后，把 webhook 指向：

```text
https://你的-worker-域名/telegram/webhook
```

PowerShell 示例：

```powershell
$botToken = "YOUR_BOT_TOKEN"
$secret = "YOUR_TG_WEBHOOK_SECRET"
$body = @{
  url = "https://your-worker-domain/telegram/webhook"
  secret_token = $secret
  allowed_updates = @("chat_join_request")
} | ConvertTo-Json -Compress

Invoke-RestMethod -Method Post -Uri "https://api.telegram.org/bot$botToken/setWebhook" -ContentType "application/json" -Body $body
```

## Telegram 侧要求

机器人需要：

- 被添加到目标群组
- 是管理员
- 拥有审批入群申请权限

同时群组需要开启“加入需要管理员审批”。

## 验证流程

### 直接通过

满足以下条件时会直接通过：

- 用户有头像
- 用户有 `bio`
- AI 返回 `approve`

这条路径下：

- 直接批准入群申请
- 不给用户发送任何消息

### 进入验证

满足以下任意条件时会进入验证：

- 没有头像
- 没有 `bio`
- AI 返回 `challenge`
- AI 请求失败

这条路径下：

- 发送一条验证消息
- 用户通过 Telegram 小程序打开验证页
- 完成 Turnstile 或生物识别验证
- 机器人批准入群
- 自动删除验证消息
- 自动删除 KV 记录

### 超时处理

- 申请保持待验证状态超过 10 分钟
- 定时任务自动拒绝该申请
- 自动删除验证消息
- 自动删除 KV 记录

## 说明

- 这里的生物识别使用的是 `Telegram.WebApp.BiometricManager`，不是 WebAuthn。
- Telegram 小程序的 `initData` 会在服务端校验后，才接受验证结果。
- 公共仓库使用者需要自己准备 Worker 域名、Turnstile、KV namespace 和 AI 凭据。

## License

如果你要公开发布，建议自行补充许可证文件。