docs(core): 📝 完善项目文档并增强安全性

更新项目根目录 README.md 以更清晰地展示脚本集合架构，并为 Homebrew、Sub-Store 和 Telegram 模块新增详细的使用说明文档。同时移除了 brew-upgrade-manager.sh 中的硬编码 sudo 密码，改为空字符串占位符以提升代码安全性。 - 增强根目录文档的可读性与结构 - 为每个子模块添加独立的 README.md - 修复脚本中的敏感信息泄露问题 (SUDO_PWD)
2026-05-03 15:18:21 +08:00
parent ce6710724d
commit c3437ae163
5 changed files with 420 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,69 @@
-# script
+# Script Collection

+一个面向日常自动化的小型脚本集合，当前包含 Homebrew 升级管理、Sub-Store 节点重命名处理、Telegram Bot Worker 三类脚本。
+
+## 目录
+
+```text
+script/
+├── homebrew/
+│   ├── README.md
+│   └── brew-upgrade-manager.sh
+├── substore/
+│   ├── README.md
+│   └── sntp-rename.js
+├── telegram/
+│   ├── README.md
+│   └── tg-bot.js
+├── LICENSE
+└── README.md
+```
+
+## 脚本概览
+
+| 目录 | 脚本 | 用途 | 运行环境 |
+| --- | --- | --- | --- |
+| `homebrew/` | `brew-upgrade-manager.sh` | 自动更新 Homebrew、升级 Formula/Cask、清理缓存 | macOS、Bash、Homebrew |
+| `substore/` | `sntp-rename.js` | 在 Sub-Store 代理节点名称中注入线路标签 | Sub-Store 脚本处理器 |
+| `telegram/` | `tg-bot.js` | 基于 Cloudflare Workers 的 Telegram 私聊转发与管理后台 | Cloudflare Workers、D1、Telegram Bot |
+
+## 快速开始
+
+### Homebrew 升级
+
+```bash
+cd homebrew
+chmod +x brew-upgrade-manager.sh
+./brew-upgrade-manager.sh
+```
+
+如在非交互式终端运行，可指定输出宽度：
+
+```bash
+./brew-upgrade-manager.sh --width 130
+HB_TERMINAL_WIDTH=130 ./brew-upgrade-manager.sh
+```
+
+详细配置见 [homebrew/README.md](homebrew/README.md)。
+
+### Sub-Store 节点标签注入
+
+把 [substore/sntp-rename.js](substore/sntp-rename.js) 作为 Sub-Store 节点处理脚本使用。默认会识别 `GTM`、`S1`、`S2`、`S3`、`S4`、`BGP`、`Anytls` 等关键词，并把标签插入到节点名末尾或 `- SNTP` 后缀之前。
+
+详细规则见 [substore/README.md](substore/README.md)。
+
+### Telegram Bot Worker
+
+把 [telegram/tg-bot.js](telegram/tg-bot.js) 部署为 Cloudflare Worker，并绑定 Telegram Bot Token、管理员 ID、管理群 ID 和 D1 数据库。Worker 根路径用于健康检查，Telegram Webhook POST 到 Worker 地址。
+
+详细部署说明见 [telegram/README.md](telegram/README.md)。
+
+## 安全提示
+
+- 不要把 Bot Token、Cloudflare 密钥、Telegram 群组 ID、管理员 ID 或 sudo 密码提交到公开仓库。
+- `homebrew/brew-upgrade-manager.sh` 当前包含 `SUDO_PWD` 占位变量，若确需使用自动输入 sudo 密码，请只在本机私有副本中填写。
+- Telegram Worker 会保存用户状态、消息映射和配置项到 D1，请按实际隐私要求控制数据库访问权限。
+
+## 许可证
+
+本项目使用 GNU Affero General Public License v3.0，详见 [LICENSE](LICENSE)。
--- a/homebrew/README.md
+++ b/homebrew/README.md
@@ -0,0 +1,111 @@
+# Homebrew Upgrade Manager
+
+`brew-upgrade-manager.sh` 是一个 macOS Homebrew 升级脚本，用来按固定流程更新仓库、检查环境、升级命令行工具和 GUI 应用，并清理旧缓存。
+
+## 功能
+
+- 执行 `brew update -v` 更新 Homebrew 仓库。
+- 执行 `brew doctor` 做健康检查，发现问题时给出警告但不中断后续流程。
+- 自动检查并安装 `buo/cask-upgrade`，用于提供 `brew cu`。
+- 使用 `brew upgrade --formula` 升级命令行 Formula。
+- 使用 `brew cu -yaq` 升级 Cask GUI 应用。
+- 使用 Python PTY 包装 `brew cu`，用于处理 sudo 密码输入和终端尺寸问题。
+- 执行 `brew cleanup --prune=all` 清理旧版本与缓存。
+
+## 依赖
+
+- macOS
+- Homebrew
+- Bash
+- Python 3
+- 可访问 Homebrew tap 的网络环境
+
+可先检查：
+
+```bash
+brew --version
+python3 --version
+```
+
+## 使用方法
+
+进入目录并赋予执行权限：
+
+```bash
+cd homebrew
+chmod +x brew-upgrade-manager.sh
+```
+
+运行：
+
+```bash
+./brew-upgrade-manager.sh
+```
+
+指定终端宽度：
+
+```bash
+./brew-upgrade-manager.sh --width 130
+./brew-upgrade-manager.sh --width=130
+```
+
+也可以通过环境变量指定：
+
+```bash
+HB_TERMINAL_WIDTH=130 ./brew-upgrade-manager.sh
+```
+
+优先级为：命令行 `--width` 高于 `HB_TERMINAL_WIDTH`，再高于自动检测值。
+
+## sudo 密码
+
+脚本中有一个 `SUDO_PWD` 占位变量：
+
+```bash
+SUDO_PWD=""
+```
+
+如果你的 `brew cu` 流程会触发 sudo，脚本会把这个变量传给内置 Python PTY 逻辑。请注意：
+
+- 不要把真实密码提交到仓库。
+- 更建议在私有副本、本机自动化环境或临时运行前填写。
+- 如果不需要自动输入 sudo，保持空字符串即可。
+
+## 执行流程
+
+1. 打印分隔线并更新 Homebrew 仓库。
+2. 执行 `brew doctor`。
+3. 检查 `buo/cask-upgrade` tap。
+4. 升级 Formula。
+5. 升级 Cask。
+6. 清理 Homebrew 缓存。
+
+## 常见问题
+
+### `brew cu` 不存在
+
+脚本会自动执行：
+
+```bash
+brew tap buo/cask-upgrade
+```
+
+如果失败，通常是网络、Homebrew tap 或权限问题。
+
+### 表格渲染或 Ruby 报终端宽度错误
+
+使用固定宽度运行：
+
+```bash
+./brew-upgrade-manager.sh --width 130
+```
+
+### sudo 卡住
+
+确认 `SUDO_PWD` 是否为空，以及当前命令是否确实需要 sudo。出于安全考虑，不建议把密码长期保存在仓库文件里。
+
+## 注意事项
+
+- 脚本启用了 `set -e` 和 `set -o pipefail`，关键命令失败会终止流程。
+- 升级 GUI 应用可能关闭或替换已安装应用，建议在重要工作保存后执行。
+- 如果你使用公司设备或受管 macOS，先确认 Homebrew、Cask 和 sudo 策略是否允许自动升级。
--- a/homebrew/brew-upgrade-manager.sh
+++ b/homebrew/brew-upgrade-manager.sh
@@ -105,7 +105,7 @@ print_header "Step 4: Executing comprehensive upgrades (Formulae & Casks)"
 echo -e "${NC}"

 # 使用前请先修改这里的密码！！
-SUDO_PWD="caiao1226"
+SUDO_PWD=""

 # 1. 升级命令行工具 (Formulae)
 echo -e "\n${CYAN}>>> [1/2] Upgrading CLI Formulae (brew upgrade --formula)...${NC}"
--- a/substore/README.md
+++ b/substore/README.md
@@ -0,0 +1,96 @@
+# Sub-Store SNTP Rename
+
+`sntp-rename.js` 是一个 Sub-Store 节点处理脚本，用于根据节点名中的关键词自动注入线路属性标签。
+
+## 作用
+
+脚本会遍历传入的 `proxies` 数组，检查每个代理节点的 `name` 字段。命中关键词后，会把对应标签追加到节点名中：
+
+- 如果节点名带有 `- SNTP...` 后缀，标签会插入到 `- SNTP` 之前。
+- 如果节点名没有该后缀，标签会追加到名称末尾。
+- 如果已经包含同样标签，不会重复注入。
+
+## 默认规则
+
+| 命中关键词 | 注入标签 |
+| --- | --- |
+| `GTM 0.5x` | `[三网]` |
+| `GTM` | `[三网]` |
+| `S1` | `[广移]` |
+| `S2` | `[广电]` |
+| `S3` | `[广移]` |
+| `S4` | `[广联]` |
+| `BGP` | `[cn2\|5x]` |
+| `Anytls` | `[直连]` |
+
+## 示例
+
+输入：
+
+```text
+香港 GTM 0.5x - SNTP 01
+广州 S1 - SNTP 02
+日本 BGP 01
+普通节点 01
+```
+
+输出：
+
+```text
+香港 GTM 0.5x [三网] - SNTP 01
+广州 S1 [广移] - SNTP 02
+日本 BGP 01 [cn2|5x]
+普通节点 01
+```
+
+## 在 Sub-Store 中使用
+
+1. 打开 Sub-Store。
+2. 进入订阅或节点处理配置。
+3. 添加 JavaScript 脚本处理器。
+4. 粘贴 [sntp-rename.js](sntp-rename.js) 内容。
+5. 保存并刷新订阅。
+
+脚本暴露的入口函数为：
+
+```javascript
+function operator(proxies) {
+  // ...
+}
+```
+
+## 修改规则
+
+只需要编辑脚本顶部的 `featureMap`：
+
+```javascript
+const featureMap = {
+    "GTM 0.5x": "三网",
+    "GTM":      "三网",
+    "S1":       "广移",
+    "S2":       "广电",
+    "S3":       "广移",
+    "S4":       "广联",
+    "BGP":      "cn2|5x",
+    "Anytls":   "直连"
+};
+```
+
+新增规则示例：
+
+```javascript
+"IEPL": "专线"
+```
+
+## 匹配逻辑
+
+- 关键词匹配不区分大小写。
+- 关键词会按长度从长到短生成正则，避免 `GTM` 先抢走 `GTM 0.5x` 的匹配。
+- 纯字母数字关键词会自动加单词边界，避免 `S1` 错误匹配到 `US1`。
+- 映射时会忽略关键词中的空格，例如 `GTM 0.5x` 与 `GTM0.5X` 会映射到同一个标签。
+
+## 注意事项
+
+- 该脚本只修改节点名称，不修改节点协议、地址、端口或其他连接参数。
+- 如果节点命中多个关键词，只会按当前正则排序匹配第一个。
+- 如需支持更多后缀位置，可修改脚本中的 `suffixRegex`。
--- a/telegram/README.md
+++ b/telegram/README.md
@@ -0,0 +1,144 @@
+# Telegram Bot Worker
+
+`tg-bot.js` 是一个部署在 Cloudflare Workers 上的 Telegram Bot。它把用户私聊消息转发到管理员论坛群的独立话题中，并提供验证、过滤、封禁、备注、自动回复、备份和配置面板。
+
+## 核心功能
+
+- 私聊用户消息转发到管理员群论坛话题。
+- 每个用户自动创建独立 topic，并推送用户身份卡片。
+- 管理员在对应 topic 内回复，即可把消息复制回用户私聊。
+- 支持 Cloudflare Turnstile 或 Google reCAPTCHA 人机验证。
+- 支持二次问答验证。
+- 支持文本、媒体、链接、转发、频道转发、音频、贴纸/GIF 等类型过滤。
+- 支持关键词自动回复和屏蔽词计数封禁。
+- 支持黑名单 topic、用户解封、备注、资料卡置顶。
+- 支持消息编辑记录同步。
+- 支持消息备份到指定群或频道。
+- 内置 Telegram 管理面板，管理员通过 `/start` 打开。
+
+## 运行环境
+
+- Cloudflare Workers
+- Cloudflare D1 数据库绑定
+- Telegram Bot Token
+- 启用话题的 Telegram 管理群
+- 可选：Cloudflare Turnstile 或 Google reCAPTCHA 密钥
+
+## 必需环境变量
+
+| 名称 | 说明 |
+| --- | --- |
+| `BOT_TOKEN` | Telegram Bot Token |
+| `ADMIN_IDS` | 管理员 Telegram user id，多个用英文或中文逗号分隔 |
+| `ADMIN_GROUP_ID` | 管理员论坛群 ID，通常是 `-100...` |
+| `WORKER_URL` | Worker 公开访问地址，不要带结尾斜杠 |
+
+## D1 绑定
+
+Worker 需要绑定一个 D1 数据库，绑定名必须是：
+
+```text
+TG_BOT_DB
+```
+
+脚本会自动创建和维护以下表：
+
+- `config`：配置项。
+- `users`：用户状态、封禁状态、topic 映射、用户资料。
+- `messages`：用户消息与管理员群 topic 消息的映射。
+
+## 可选环境变量
+
+| 名称 | 说明 |
+| --- | --- |
+| `TURNSTILE_SITE_KEY` | Cloudflare Turnstile site key |
+| `TURNSTILE_SECRET_KEY` | Cloudflare Turnstile secret key |
+| `RECAPTCHA_SITE_KEY` | Google reCAPTCHA site key |
+| `RECAPTCHA_SECRET_KEY` | Google reCAPTCHA secret key |
+| `WELCOME_MESSAGE` | 默认欢迎语，对应配置项 `welcome_msg` |
+| `VERIF_QUESTION` | 默认问答验证问题，对应 `verif_q` |
+| `VERIF_ANSWER` | 默认问答验证答案，对应 `verif_a` |
+
+大多数运行时配置也可以在管理员面板中调整，并优先保存到 D1。
+
+## 默认配置
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `welcome_msg` | `欢迎 {name}！使用前请先完成验证。` | 欢迎语，支持 `{name}` 或 `{user}` |
+| `enable_verify` | `true` | 是否启用网页人机验证 |
+| `enable_qa_verify` | `true` | 是否启用问答验证 |
+| `captcha_mode` | `turnstile` | 验证模式：`turnstile` 或 `recaptcha` |
+| `verif_q` | `1+1=?` | 问题验证题目 |
+| `verif_a` | `3` | 问题验证答案 |
+| `block_threshold` | `5` | 命中屏蔽词多少次后封禁 |
+| `busy_mode` | `false` | 是否启用非营业自动回复 |
+| `enable_admin_receipt` | `false` | 管理员回执开关 |
+
+## 部署流程
+
+1. 在 Telegram 中创建 Bot，拿到 `BOT_TOKEN`。
+2. 创建一个启用 Topics 的 Telegram 群，把 Bot 拉入群。
+3. 给 Bot 管理员权限，至少需要发消息、管理话题、置顶消息等能力。
+4. 在 Cloudflare 创建 D1 数据库并绑定为 `TG_BOT_DB`。
+5. 创建 Worker，把 [tg-bot.js](tg-bot.js) 作为 Worker 代码。
+6. 配置环境变量 `BOT_TOKEN`、`ADMIN_IDS`、`ADMIN_GROUP_ID`、`WORKER_URL`。
+7. 设置 Telegram Webhook：
+
+```bash
+curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>"
+```
+
+8. 访问 Worker 根路径，若返回 `Bot v3.67 Active`，说明 Worker 基本可用。
+9. 管理员私聊 Bot 发送 `/start`，打开控制面板。
+
+## Webhook 路由
+
+| 路径 | 方法 | 用途 |
+| --- | --- | --- |
+| `/` | `GET` | 健康检查 |
+| `/verify` | `GET` | Telegram Web App 验证页面 |
+| `/submit_token` | `POST` | 验证 token 提交 |
+| `/` | `POST` | Telegram Webhook 更新入口 |
+
+## 管理员面板
+
+管理员私聊 Bot 发送 `/start` 后会打开配置面板，包含：
+
+- 基础：欢迎语、验证问题、验证答案、验证码模式、问题验证开关。
+- 自动回复：添加或删除关键词自动回复。
+- 屏蔽词：添加或删除正则关键词，命中后累计封禁。
+- 过滤：控制转发、媒体、语音、贴纸、链接、频道、文本等类型。
+- 协管：维护额外授权管理员。
+- 备份/通知：设置备份群、重置黑名单 topic。
+- 营业状态：切换忙碌模式并修改自动回复语。
+
+自动回复新增格式：
+
+```text
+关键词===回复内容
+```
+
+授权管理员可输入多个 ID：
+
+```text
+123456,789012
+```
+
+## 用户流程
+
+1. 用户私聊 Bot 发送 `/start`。
+2. Bot 发送欢迎语。
+3. 如果启用网页验证，用户点击按钮完成 Turnstile 或 reCAPTCHA。
+4. 如果启用问答验证，用户继续回答问题。
+5. 验证通过后，用户消息会转发到管理员群中的个人 topic。
+6. 管理员在 topic 中回复，Bot 会把回复发送给该用户。
+
+## 注意事项
+
+- `ADMIN_IDS` 使用字符串包含判断，建议使用完整 ID 并用逗号分隔，避免 ID 片段误匹配。
+- 管理员群必须开启 Topics，否则自动创建用户话题会失败。
+- `WORKER_URL` 要使用 HTTPS 公开地址，否则 Telegram Web App 验证页面无法正常工作。
+- Turnstile 和 reCAPTCHA 至少配置一种；如果关闭网页验证，可只使用问答验证。
+- Worker 使用内存缓存减少 D1 读取，配置修改后脚本会主动清缓存。
+- 请妥善保护 `BOT_TOKEN`、验证码 secret、D1 数据库和 Cloudflare 账号权限。