AEX-X/telescout

媒体买手通常需要付费使用如 TGStat/Telemetr 这样的目录服务来寻找广告频道。**TeleScout 通过一个 self-hosted 的 pipeline 替代了这一过程**：它根据细分领域发现公开的俄语频道，抓取它们的公开指标，**按 0–100 的标准评估每个频道的广告适用性**，并通过 Streamlit 界面、headless CLI 或 FastAPI 服务导出排序好的表格。 它通过两种方式运行：**Telethon** 模式通过 API 密钥在 Telegram 内部进行搜索，而 **Web Discovery** 模式则**完全不需要 API 密钥**即可发现并筛选频道——它直接抓取公开的目录、搜索引擎以及帖子中提及频道的图谱关系。 ## ✨ 核心亮点 - **可解释的 0–100 评分** + 每个频道的**参与度 (ERR)**——这是媒体采买真实的 KPI，包含各项指标（覆盖率 · 参与度 · 发帖频率 · 新鲜度 · 广告负载）的详细拆解，而不是一个“神秘数字”。详见[评分机制](#-как-считается-оценка)。 - **双引擎搜索** — 同时支持官方 Telegram API (Telethon) *和* 免登录模式，后者甚至包含基于帖子中频道提及关系的**图谱波次扩散**技术。 - **柔性漏斗** — 指标难以读取的频道不会被静默丢弃，而是会被归入**存疑**列表，以确保不会遗漏任何有价值的内容。 - **三种接口，同一个 pipeline** — Streamlit UI、CLI `telescout` 和 FastAPI 服务均调用同一个服务层，并返回完全一致的排序结果。 - **数据分析** — 提供评分分布、“参与度-规模”散点图，以及按层级和细分领域切分的分析视图。 - **全面审计** — 每次运行都会记录运行参数、详细的步骤事件日志、发现的 username、各频道的结果并自动保存为 Excel 文件，外加一个包含所有已发现频道的 SQLite 缓存。 - **质量标杆** — 分层架构、全面的类型注解、**88 个测试**、`ruff` + `mypy` 零报错、支持 Python 3.11 和 3.12 的 CI 流水线、Docker 支持，以及一行命令启动的 Demo。 ## 📸 效果展示 **“数据分析”标签页** — 基于本次运行中发现的频道计算得出： **CLI** — `telescout demo`（离线示例，无需联网）： ## 🚀 快速开始 ``` git clone https://github.com/AEX-X/telescout cd telescout pip install -e ".[ui,api]" # добавьте ,telegram для режима Telethon telescout demo # офлайн-пример — без сети и API-ключа telescout niches # 70+ встроенных пресетов ниш telescout discover --niche beauty --niche fitness --min-subs 5000 --limit 30 --out beauty.xlsx telescout analyze @durov @telegram --json out.json ``` **Streamlit UI:** `streamlit run app.py`（或 `make ui`）→ http://localhost:8501 **API:** `uvicorn telescout.api:app`（或 `make api`）→ http://localhost:8000/docs **Docker (UI + API):** `docker compose up --build` **Web Discovery**、**CLI** 和 **API** 模式不需要任何凭证。只有 Telethon 模式需要 Telegram 的 `api_id`/`api_hash`（获取地址：[my.telegram.org](https://my.telegram.org)）——只需将 `.env.example` 复制为 `.env` 并填入相关信息即可。 ## 🧠 运行原理 ``` flowchart LR A["Ключи-семена
config/presets.yaml"] --> B{Режим} B -->|Telethon| C["contacts.search
внутри Telegram"] B -->|"Web Discovery
(без API)"| D["Каталоги + поисковики
+ волны по ссылкам в постах"] C --> E["Скрейп публичных метрик
со страниц t.me"] D --> E E --> F["Оценка 0–100
+ вовлечённость"] F --> G["Классификация
подошли · спорные · нет"] G --> H["Ранжирование и экспорт
XLSX · JSON · SQLite"] ``` 最有趣的部分在于 **Web Discovery**。由于 Telegram 并没有公开的频道目录，TeleScout 会自行构建一个：它从特定领域的关键词出发，从公开目录和搜索引擎中提取候选频道，随后进行**图谱波次扩散**——读取已发现频道的公开帖子页面，收集它们*引用或提及的*所有频道，并重复几个波次。每一个新增的 username 都会被去重、过滤掉无效信息（如客服账号、机器人、名称过短的账号），并进行来源平衡，以防止某个充满噪音的单一来源占据主导地位。 ## 📊 评分计算方式 `telescout.scoring` 会将原始指标转化为买手实际会使用的两个数字： - **参与度 (ERR)** = `平均阅读量 / 订阅者数` — 衡量频道健康度的主要指标。健康的频道 ERR 通常 ≈10–40%；极低的 ERR 暗示存在死号/机器人，而异常偏高的 ERR 则暗示阅读量存在造假。 - **质量评分 (0–100)** = 包含重新归一化的五个维度的加权组合： | 维度 | 权重 | 评估标准 | | --- | --- | --- | | 参与度 | 30% | 健康的 ERR（对异常偏高的数据进行惩罚） | | 覆盖率 | 25% | 受众规模（对数标度） | | 活跃度 | 20% | 稳定的发帖频率（约 3–21 帖/周；对停更和刷屏进行惩罚） | | 新鲜度 | 15% | 近期的发帖记录 | | 纯净度 | 10% | 较低的广告负载 | 每一项维度的具体得分都会与总分一同返回，这使得 UI、Excel 和 API 能够展示频道获得该评分的**具体原因**。未知的指标会被剔除并对权重进行重新归一化——抓取过程中的数据缺失虽然会降低置信度，但不会不公平地将评分清零。评级分为：**A / B / C / D** 级。 ## 🏗️ 架构设计 采用分层 pipeline 设计 —— UI/CLI/API 都只是同一个服务层的轻量级封装。详情请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。 ``` app.py Streamlit UI (тонкий) telescout/pipeline.py сервисный слой (общий для UI/CLI/API) telescout/cli.py Typer CLI telescout/scoring.py вовлечённость + оценка качества telescout/api.py FastAPI-сервис telescout/web_discovery.py поиск без API + волновое расширение telescout/charts.py Plotly-аналитика telescout/public_web.py скрейп t.me + парсинг метрик telescout/http.py общий HTTP-клиент telescout/runner.py движок поиска Telethon telescout/storage.py SQLite-кэш + история telescout/classifier.py мягкая воронка подошли/спорные/нет ``` ## ⚖️ 负责任的使用声明 TeleScout 仅读取**公开数据** —— 包括公开的 `t.me` 页面和公开的搜索引擎结果——专用于合法的广告与营销调研。默认采用温和的运行模式，不带激进的并发请求，**不进行账号轮换**，不发送消息，不主动加入频道，并严格遵守 `FloodWait` 限制。使用 Telethon 模式时，请使用独立账号，并遵守 Telegram 的服务条款及数据来源的 robots 政策。请勿将此工具用于垃圾信息轰炸、抓取私密内容或恶意骚扰。 ## 🧫 开发指南 ``` pip install -e ".[dev,ui,api,telegram]" make check # ruff + mypy + pytest (то же, что в CI) make test # pytest с покрытием ``` 包含 88 个测试，`ruff` + `mypy` 零报错，CI 支持 Python 3.11 和 3.12。 ## 🛠️ 技术栈 Python 3.11+ · Streamlit · FastAPI · Typer · Telethon · BeautifulSoup + requests · pandas + openpyxl · Plotly · SQLite · pytest · ruff · mypy · Docker. ## 📄 许可证 [MIT](LICENSE) © 2026 AEX-X

标签：AV绕过, BeEF, FastAPI, Kubernetes, Python, Splunk, Streamlit, Telegram, 代码示例, 命令控制, 安全规则引擎, 数据分析, 数据采集, 无后门, 爬虫, 访问控制, 请求拦截, 逆向工具