Translate README to Chinese

2026-04-19 00:31:24 +08:00
parent 5c013e3abb
commit 44d9675867
1 changed files with 83 additions and 76 deletions
--- a/README.md
+++ b/README.md
@@ -1,54 +1,54 @@
 # TeleWatchdog

-TeleWatchdog is a `Cloudflare Workers` Telegram join-request watchdog for private groups.
+`TeleWatchdog` 是一个基于 `Cloudflare Workers` 的 Telegram 入群申请审核机器人项目，适用于需要“申请加入”模式的群组。

-It reviews join requests with a simple pipeline:
+它的核心流程很简单：

-1. Check whether the applicant has an avatar.
-2. Check whether the applicant has a bio.
-3. If either is missing, require verification.
-4. If both exist, ask an AI model for a binary decision.
-5. If the AI returns `approve`, accept the join request immediately.
-6. Otherwise, send a verification message with a Telegram Web App button.
+1. 检查申请人是否有头像。
+2. 检查申请人是否有 `bio`。
+3. 只要头像或 `bio` 缺失，直接进入验证。
+4. 如果两者都存在，则调用 AI 做二分类判断。
+5. AI 返回 `approve` 时，直接通过入群申请。
+6. AI 返回 `challenge` 时，发送验证消息，让用户完成验证。

-Users who need verification can choose either:
+需要验证的用户可以二选一：

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

-If verification is not completed within 10 minutes, a scheduled task declines the request and cleans up the stored state.
+如果 10 分钟内没有完成验证，定时任务会自动拒绝申请，并清理消息和 KV 记录。

-## Features
+## 功能特性

- Telegram `chat_join_request` webhook support
- Cloudflare Worker deployment model
- Telegram Web App verification page
- Turnstile verification
- Telegram biometric verification via `BiometricManager`
- AI-based binary profile review
- Automatic cleanup of expired verification records
- Automatic deletion of verification messages after success or timeout
+- 支持 Telegram `chat_join_request` webhook
+- 基于 `Cloudflare Worker` 部署
+- Telegram 小程序验证页
+- `Cloudflare Turnstile` 人机验证
+- Telegram 原生生物识别验证
+- AI 二分类审核
+- 验证超时自动清理
+- 验证成功或超时后自动删除验证消息

-## Stack
+## 技术栈

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

-## Project Structure
+## 项目结构

 ```text
-src/index.ts           Main Worker implementation
-package.json           Project metadata and scripts
-tsconfig.json          TypeScript config
-wrangler.toml.example  Example Wrangler config
+src/index.ts           Worker 主逻辑
+package.json           项目配置与脚本
+tsconfig.json          TypeScript 配置
+wrangler.toml.example  Wrangler 示例配置
 ```

-## Required Secrets
+## 需要的 Secrets

-Set these with `wrangler secret put`:
+使用 `wrangler secret put` 写入：

 - `BOT_TOKEN`
 - `TG_WEBHOOK_SECRET`
@@ -56,48 +56,48 @@ Set these with `wrangler secret put`:
 - `AI_API_KEY`
 - `TURNSTILE_SECRET`

-## Required Variables
+## 需要的变量

-Set these in `wrangler.toml`:
+在 `wrangler.toml` 中配置：

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

-## KV Setup
+## 创建 KV

-Create a KV namespace:
+先创建 KV namespace：

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

-Copy the returned namespace id into your `wrangler.toml`.
+然后把返回的 namespace id 填进你的 `wrangler.toml`。

-## Local Setup
+## 本地使用

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

-Then edit `wrangler.toml` and add your real values.
+然后编辑 `wrangler.toml`，填入你自己的真实配置。

-## Deploy
+## 部署

 ```bash
 npx wrangler deploy
 ```

-## Telegram Webhook
+## 配置 Telegram Webhook

-After deployment, configure the webhook to point to:
+部署完成后，把 webhook 指向：

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

-Example PowerShell:
+PowerShell 示例：

 ```powershell
 $botToken = "YOUR_BOT_TOKEN"
@@ -111,55 +111,62 @@ $body = @{
 Invoke-RestMethod -Method Post -Uri "https://api.telegram.org/bot$botToken/setWebhook" -ContentType "application/json" -Body $body
 ```

-## Telegram Permissions
+## Telegram 侧要求

-The bot must:
+机器人需要：

- be added to the target group
- be an administrator
- have permission to approve join requests
+- 被添加到目标群组
+- 是管理员
+- 拥有审批入群申请权限

-The group must be configured to require approval for join requests.
+同时群组需要开启“加入需要管理员审批”。

-## Verification Flow
+## 验证流程

-### Auto-approve path
+### 直接通过

- user has avatar
- user has bio
- AI returns `approve`
- request is approved immediately
- no message is sent to the user
+满足以下条件时会直接通过：

-### Verification path
+- 用户有头像
+- 用户有 `bio`
+- AI 返回 `approve`

- avatar missing, or
- bio missing, or
- AI returns `challenge`, or
- AI request fails
+这条路径下：

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

- a single verification message is sent
- user opens the Telegram Web App
- user completes Turnstile or biometric verification
- the bot approves the request
- the verification message is deleted
- KV records are deleted
+### 进入验证

-### Timeout path
+满足以下任意条件时会进入验证：

- request stays pending for 10 minutes
- scheduled Worker declines the join request
- verification message is deleted
- KV records are deleted
+- 没有头像
+- 没有 `bio`
+- AI 返回 `challenge`
+- AI 请求失败

-## Notes
+这条路径下：

- Telegram biometric verification here uses `Telegram.WebApp.BiometricManager`, not WebAuthn.
- Telegram Web App `initData` is verified server-side before accepting either verification method.
- Public repository users should create their own Worker domain, Turnstile site, KV namespace, and AI credentials.
+- 发送一条验证消息
+- 用户通过 Telegram 小程序打开验证页
+- 完成 Turnstile 或生物识别验证
+- 机器人批准入群
+- 自动删除验证消息
+- 自动删除 KV 记录
+
+### 超时处理
+
+- 申请保持待验证状态超过 10 分钟
+- 定时任务自动拒绝该申请
+- 自动删除验证消息
+- 自动删除 KV 记录
+
+## 说明
+
+- 这里的生物识别使用的是 `Telegram.WebApp.BiometricManager`，不是 WebAuthn。
+- Telegram 小程序的 `initData` 会在服务端校验后，才接受验证结果。
+- 公共仓库使用者需要自己准备 Worker 域名、Turnstile、KV namespace 和 AI 凭据。

 ## License

-Add your preferred license before publishing if needed.
+如果你要公开发布，建议自行补充许可证文件。