tgstat

TGStat 研究

使用 scripts/tgstat.py 开展公开 TGStat 研究。它仅使用 Python 标准库。该脚本在幕后通过平台渲染服务（无头 Chromium）抓取 TGStat 页面，以绕过该网站的机器人防护，因此每次查询可能需要几秒钟。每次调用 Bash 时都要先解析脚本路径，因为每次调用都会在全新的 shell 中运行：

TGSTAT="$SKILL_DIR/scripts/tgstat.py"; [ -f "$TGSTAT" ] || TGSTAT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tgstat.py' 2>/dev/null | head -1)
[ -f "$TGSTAT" ] || { echo "tgstat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TGSTAT" profile

连接器会注入 $TGSTAT_USERNAME。它不是登录凭据，只是默认的公开频道／群组目标。切勿打印完整环境变量，也不要将用户名视为用户拥有该 Telegram 账号的证明。

按主题发现来源

先运行 search：

TGSTAT="$SKILL_DIR/scripts/tgstat.py"; [ -f "$TGSTAT" ] || TGSTAT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tgstat.py' 2>/dev/null | head -1)
[ -f "$TGSTAT" ] || { echo "tgstat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TGSTAT" search "Claude API" --type all --language English --country US

在公开模式下，该命令会返回 web_queries。对每条查询调用一次 web_search，然后：

1. 只保留公开的 tgstat.com 地区性主机和 t.me 结果。
2. 提取公开的 @username 值，并忽略大小写进行去重。
3. 优先选择标题／摘要与主题直接匹配的结果。
4. 在报告短名单中的每项之前，使用 info 或 stat 进行验证。
5. 附上来源 URL，并说明发现结果可能不完整，因为公开搜索引擎的索引并非 TGStat 的完整数据库。

TGStat 自身的关键词搜索结果端点需要登录。不要尝试绕过登录、重放私有 AJAX 端点，或声称公开模式搜索了 TGStat 的完整索引。

--language 和 --country 是针对网络索引的搜索词，并非有保证的 TGStat 数据库筛选条件。

浏览公开排名

当用户想要查找大型或活跃的公开来源，但没有明确关键词时，请使用排名：

TGSTAT="$SKILL_DIR/scripts/tgstat.py"; [ -f "$TGSTAT" ] || TGSTAT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tgstat.py' 2>/dev/null | head -1)
[ -f "$TGSTAT" ] || { echo "tgstat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TGSTAT" rankings --type channel --limit 20
python3 "$TGSTAT" rankings --type chat --limit 20
python3 "$TGSTAT" rankings --type channel --query crypto --limit 10

频道卡片可能显示订阅人数、单篇帖子触达量和引用指数。群聊卡片可能显示参与人数、近期消息数和 MAU。指标反映的是当前公开快照，而非历史序列。

公开 TGStat 页面可能间歇性地返回身份验证或速率限制拦截页。当 rankings 返回 status: unavailable 时，尝试访问生成的 web_fetch_url，然后通过 web_search 运行其 web_queries。应将这些结果标注为网络索引发现结果，而非权威的 TGStat 排名。

查看已知频道或群组

可接受公开的 @username、不带 @ 的用户名、t.me/<username> 链接或 TGStat 实体 URL。省略目标即可查看连接器中的 $TGSTAT_USERNAME：

TGSTAT="$SKILL_DIR/scripts/tgstat.py"; [ -f "$TGSTAT" ] || TGSTAT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tgstat.py' 2>/dev/null | head -1)
[ -f "$TGSTAT" ] || { echo "tgstat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TGSTAT" info
python3 "$TGSTAT" info @durov
python3 "$TGSTAT" stat https://t.me/example_public_chat

在公开模式下，info／stat 会解析目标是频道还是聊天，并返回其公开身份信息（标题、描述）以及可见的订阅人数／参与人数。更深入的互动指标（平均帖子触达量、引用指数、ER）由 TGStat 在客户端绘制图表，因此仅适用于出现在公开排行榜中的实体；对于这类实体，命令会从排名快照中补充结果。指标为空或缺失，表示 TGStat 未在公开页面上展示这些指标；不要将其称为完整统计数据。如果需要大型公开来源的触达量／引用指数，请使用 rankings。

与排名页面相比，单个频道／群聊页面的机器人防护更严格，因此 info／stat 查询偶尔可能返回 render blocked／could not render 错误。它会快速失败（远低于 Bash 超时），可以重试一次，或改用 rankings 和 search 来发现来源，这两者要可靠得多。

选择广告投放对象时，应根据相关触达量／活跃度排名，而不是只看订阅人数。订阅人数高但触达量或群聊 MAU 低，可能意味着受众不活跃或人数虚高。将指标作为参考依据，而非潜在客户质量的保证。

检查已连接的个人资料

TGSTAT="$SKILL_DIR/scripts/tgstat.py"; [ -f "$TGSTAT" ] || TGSTAT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tgstat.py' 2>/dev/null | head -1)
[ -f "$TGSTAT" ] || { echo "tgstat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TGSTAT" profile

profile 会报告供不带目标的 info 和 stat 使用的规范化公开用户名。它不会验证所有权，也不会向 Telegram／TGStat 进行身份验证。

外联调研工作流

用于潜在客户开发或合作调研：

1. 搜索多个范围较窄的问题／角色关键词，而不只搜索宽泛的 AI 词语。
2. 先按相关性筛选来源，再考虑受众规模／覆盖面／活跃度。
3. 核实每个公开来源，并保留证据链接。
4. 将每个来源标记为频道、群组／聊天，或不确定。
5. 生成待审核队列，并附上建议切入角度和匹配理由。
6. 通过其他连接器发送任何消息前，必须先获得人工批准。

安全与限制

• 只读。此技能不会加入频道／群组、导入邀请链接、发送消息、添加成员或下载成员列表。
• 拒绝私人邀请链接（t.me/+...、joinchat/...）和消息链接。
• 不要自动执行未经请求的批量外联，也不要规避 Telegram/TGStat 的限制。
• 公开页面和 HTML 可能会变化；如果解析失败，请使用 web_fetch 获取单个公开页面，并且只报告该页面上可见的值。
• 公开网络发现并不完整，区域版 TGStat 页面也可能有所不同。
• 将 $TGSTAT_USERNAME 视为公开个人资料上下文，而非身份验证信息。