{"id":"2eec4c1d-2844-47a0-83b1-ff83b3da3876","entityType":"agent","slug":"clawhub-testman2025-telegram-tools-suite","name":"Telegram Tools Suite","canonicalUrl":"https://www.xpersona.co/agent/clawhub-testman2025-telegram-tools-suite","canonicalPath":"/agent/clawhub-testman2025-telegram-tools-suite","generatedAt":"2026-10-12T11:56:37.652Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:12:03.215Z","emptyReason":null},"description":"Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。 运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 999 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17byqgfxb0xcxd564d2gh3yys84v9aa:telegram-tools-suite","sourceUrl":"https://clawhub.ai/testman2025/telegram-tools-suite","homepage":"https://clawhub.ai/testman2025/skills/telegram-tools-suite","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/testman2025/telegram-tools-suite","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/testman2025/skills/telegram-tools-suite","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Telegram Tools Suite technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:12:03.215Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:12:03.215Z","emptyReason":null},"stars":null,"forks":null,"downloads":999,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.3.3","tractionLabel":"999 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:12:03.202Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T20:12:03.215Z","lastCrawledAt":"2026-10-11T20:12:03.202Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T20:12:03.202Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.3","createdAt":"2026-04-22T02:18:09.841Z","changelog":"安全优化：1. 为session_runtime.py临时会话复制逻辑增加明确注释，说明仅用于进程隔离防锁死，任务结束自动删除无留存；2. clawhub.yaml新增设计说明，明确告知无第三方数据传输逻辑，消除扫描误判；3. 所有安全设计完全透明可追溯","fileCount":33,"zipByteSize":41940},{"version":"1.3.2","createdAt":"2026-04-22T02:02:30.045Z","changelog":"元数据完全对齐：1. 补全TG_ENABLE_PERSISTENT_JOIN环境变量声明，clawhub.yaml和SKILL.md完全一致；2. 完善所有变量说明，无遗漏必填参数；3. 所有风险开关和配置要求均显式声明，解决元数据和文档不一致问题","fileCount":32,"zipByteSize":40583},{"version":"1.3.1","createdAt":"2026-04-21T10:57:35.292Z","changelog":"元数据更新：1. 新增clawhub.yaml配置文件，声明所有必填环境变量和风险等级；2. SKILL.md补充前置配置说明，明确列出所有环境变量要求；3. 完善高风险功能文档说明","fileCount":32,"zipByteSize":40238},{"version":"1.3.0","createdAt":"2026-04-21T10:53:48.954Z","changelog":"安全更新：1. 高风险功能（批量加群、定时群发）默认禁用，需显式设置ENABLE_HIGH_RISK_OPERATIONS=true环境变量才可运行；2. 增加明确的风险提示，要求用户确认使用符合Telegram服务条款；3. 修复会话文件冲突导致进程锁死的问题","fileCount":31,"zipByteSize":39465},{"version":"1.2.4","createdAt":"2026-04-21T09:05:54.414Z","changelog":"1. 新增定时自动群发功能，支持多群不同内容、不同间隔批量发送消息；2. 修复环境变量配置加载错误问题；3. 优化监控进程稳定性","fileCount":30,"zipByteSize":37743},{"version":"1.2.3","createdAt":"2026-04-17T10:03:13.291Z","changelog":"功能优化更新，完善配置与元数据对齐","fileCount":36,"zipByteSize":39395},{"version":"1.2.2","createdAt":"2026-04-17T09:51:26.512Z","changelog":"更新注册表元数据：补充完整所有必填/可选环境变量说明，对齐SKILL.md frontmatter与ClawHub注册表配置","fileCount":36,"zipByteSize":39031},{"version":"1.2.1","createdAt":"2026-04-17T09:30:34.194Z","changelog":"【安全加固整改版本】完全对齐SKILL.md/README与发布页元数据： ✅ 已完成整改项： 1. join 默认仅 --once 模式，长驻加群需显式开启 TG_ENABLE_PERSISTENT_JOIN=true 2. scheduled_send.py 需配置 TG_RISK_ACK=I_UNDERSTAND 风险确认才能启动 3. 自动操作最小间隔30分钟、单轮批量加群最多20次限流 4. 所有敏感会话文件统一存放在 userdata/ 目录，已加入全局忽略规则 📋 已明确标注：必填凭据列表、风险闸门说明、长驻任务默认关闭状态、任务停止方式，所有说明与文档一字不差对齐","fileCount":36,"zipByteSize":38916}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17byqgfxb0xcxd564d2gh3yys84v9aa:telegram-tools-suite","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17byqgfxb0xcxd564d2gh3yys84v9aa:telegram-tools-suite` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/testman2025/telegram-tools-suite before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T11:56:37.646Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-testman2025-telegram-tools-suite/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:12:03.215Z","emptyReason":null},"readme":"Skill: Telegram Tools Suite\n\nOwner: testman2025\n\nSummary: Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。 运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nTags: latest:1.3.3\n\nVersion history:\n\nv1.3.3 | 2026-04-22T02:18:09.841Z | user\n\n安全优化：1. 为session_runtime.py临时会话复制逻辑增加明确注释，说明仅用于进程隔离防锁死，任务结束自动删除无留存；2. clawhub.yaml新增设计说明，明确告知无第三方数据传输逻辑，消除扫描误判；3. 所有安全设计完全透明可追溯\n\nv1.3.2 | 2026-04-22T02:02:30.045Z | user\n\n元数据完全对齐：1. 补全TG_ENABLE_PERSISTENT_JOIN环境变量声明，clawhub.yaml和SKILL.md完全一致；2. 完善所有变量说明，无遗漏必填参数；3. 所有风险开关和配置要求均显式声明，解决元数据和文档不一致问题\n\nv1.3.1 | 2026-04-21T10:57:35.292Z | user\n\n元数据更新：1. 新增clawhub.yaml配置文件，声明所有必填环境变量和风险等级；2. SKILL.md补充前置配置说明，明确列出所有环境变量要求；3. 完善高风险功能文档说明\n\nv1.3.0 | 2026-04-21T10:53:48.954Z | user\n\n安全更新：1. 高风险功能（批量加群、定时群发）默认禁用，需显式设置ENABLE_HIGH_RISK_OPERATIONS=true环境变量才可运行；2. 增加明确的风险提示，要求用户确认使用符合Telegram服务条款；3. 修复会话文件冲突导致进程锁死的问题\n\nv1.2.4 | 2026-04-21T09:05:54.414Z | user\n\n1. 新增定时自动群发功能，支持多群不同内容、不同间隔批量发送消息；2. 修复环境变量配置加载错误问题；3. 优化监控进程稳定性\n\nv1.2.3 | 2026-04-17T10:03:13.291Z | user\n\n功能优化更新，完善配置与元数据对齐\n\nv1.2.2 | 2026-04-17T09:51:26.512Z | user\n\n更新注册表元数据：补充完整所有必填/可选环境变量说明，对齐SKILL.md frontmatter与ClawHub注册表配置\n\nv1.2.1 | 2026-04-17T09:30:34.194Z | user\n\n【安全加固整改版本】完全对齐SKILL.md/README与发布页元数据：\n✅ 已完成整改项：\n1. join 默认仅 --once 模式，长驻加群需显式开启 TG_ENABLE_PERSISTENT_JOIN=true\n2. scheduled_send.py 需配置 TG_RISK_ACK=I_UNDERSTAND 风险确认才能启动\n3. 自动操作最小间隔30分钟、单轮批量加群最多20次限流\n4. 所有敏感会话文件统一存放在 userdata/ 目录，已加入全局忽略规则\n📋 已明确标注：必填凭据列表、风险闸门说明、长驻任务默认关闭状态、任务停止方式，所有说明与文档一字不差对齐\n\nv1.2.0 | 2026-04-17T09:19:29.733Z | user\n\n功能优化更新，修复元数据不一致问题，完善敏感操作提示与排除规则，移除干扰文件\n\nv1.1.1 | 2026-04-17T09:08:34.947Z | user\n\n补充元数据声明：更新技能描述明确提示运行时会生成敏感会话文件、包含长时间运行的长驻任务，完善安全提示与安装前须知，对齐SKILL.md文档与注册表元数据\n\nv1.1.0 | 2026-04-17T09:04:36.947Z | user\n\n完成规则&关键词配置化改造：所有监控规则、搜索关键词均已迁移到配置文件，无硬编码内容，支持用户自定义修改无需改动业务代码\n\nv0.2.1 | 2026-04-17T08:40:20.889Z | user\n\n🔒 安全修复：彻底移除所有误提交的敏感文件，补充.gitignore规则防止后续误提交，无任何个人信息泄露风险\n\nv0.2.0 | 2026-04-16T09:10:21.020Z | user\n\n🔥 新增多群多内容定时发送功能：支持同时配置任意数量定时任务，每个任务可独立设置目标群、发送内容、发送间隔，所有任务并行运行互不干扰，完全兼容旧版单任务配置，更新使用说明文档\n\nv0.1.6 | 2026-04-16T06:14:21.812Z | user\n\n彻底删除重复的Post-Install Interaction Flow和First Run Checklist内容，仅保留统一的首次运行引导流程，无任何冗余信息\n\nv0.1.5 | 2026-04-16T06:08:46.952Z | user\n\n精简SKILL.md内容，删除重复的安全提示和前置说明，内容更简洁无冗余\n\nv0.1.4 | 2026-04-16T06:05:51.268Z | user\n\n完善安装后引导说明，更新标准化首次运行流程，步骤更清晰无歧义\n\nv0.1.2 | 2026-04-16T04:06:46.541Z | user\n\n修复滥用风险：移除所有硬编码的发送目标/消息内容/规则，新增滥用警告，所有配置完全由用户自行填写，无预定义垃圾内容\n\nv0.1.1 | 2026-04-16T03:48:18.869Z | user\n\n修复元数据误导问题：补充必填环境变量声明，新增敏感文件安全提示\n\nv1.0.0 | 2026-04-15T11:41:24.638Z | auto\n\nTelegram Tools Suite 1.0.0 – Initial Release\n\n- Provides an automation toolkit for Telegram including group monitoring, scheduled messaging, auto group joining, group search, member export, and more.\n- Detailed post-installation flow and first run checklist to streamline setup, with support for Telegram API authentication and login.\n- Includes runtime config files for customizing monitored groups, keywords, group search parameters, and batch join targets.\n- Offers a command-line interface covering group listing, account info, member export, message history export, monitoring, group search, and batch group joining.\n- Enforces strict security rules against sensitive data leakage and ensures long-running tasks are non-conflicting per Telegram session.\n\nArchive index:\n\nArchive v1.3.3: 33 files, 41940 bytes\n\nFiles: CHANGELOG.md (489b), clawhub.yaml (1650b), pyproject.toml (532b), README.md (14913b), requirements.txt (82b), setup.py (95b), skill-card.md (2076b), SKILL.md (9129b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3337b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (2198b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8813b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12819b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (14967b), src/tg_monitor_kit/send/__init__.py (68b), src/tg_monitor_kit/send/runtime.py (6422b), src/tg_monitor_kit/session_runtime.py (2102b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1755b), _meta.json (139b)\n\nFile v1.3.3:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: ENABLE_HIGH_RISK_OPERATIONS\n    description: 高风险总开关（join/send-schedule 需设为 true 才可运行）\n    required: false\n    default: \"false\"\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径（默认 config/keywords.txt）\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。\n> 4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 与 `send-schedule` 均需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true` 才可运行；其中 `join` 长驻模式还需额外设置 `TG_ENABLE_PERSISTENT_JOIN=true`。定时群发由 `send-schedule` 子命令执行，并按 `config/scheduled_tasks.json` 的限制进行校验。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 在本地自行创建：`config/scheduled_tasks.json`\n2. 在 `scheduled_tasks.json` 中填写任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 校验限制：`interval_hours` 必须 `>= 0.5`，任务总数最多 20 个。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- 本技能发布包默认不包含 `config/` 目录内容；请在本地自行创建所需配置文件。\n- 监控：创建 `config/target_groups.txt`、`config/keywords.txt`、`config/monitor_regex_rules.json`。\n- 搜索：创建 `config/group_search_keywords.txt`、`config/group_search.json`。\n- 定时群发：创建 `config/scheduled_tasks.json`。\n- 批量加群：创建 `join_targets.txt`（或使用 `TG_JOIN_LIST_FILE` 指定路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n- `ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`：按 `config/scheduled_tasks.json` 执行定时群发（长驻）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join`、`send-schedule` 属于长驻任务，运行时会基于主会话复制临时会话副本；如遇异常退出仍可能触发 `database is locked`，请先结束残留进程后重试。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 在提供任何 Telegram 凭证前，必须先确认技能请求来源可信；发布方来源未知时，建议在一次性容器/隔离环境运行并使用测试账号。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.3.3:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n  - 加群（单轮）：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`\n  - 定时群发：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; requires `ENABLE_HIGH_RISK_OPERATIONS=true`. Persistent mode additionally requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true`。长驻模式还需 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `send-schedule` | Multi-task scheduled message sending by JSON config file; requires `ENABLE_HIGH_RISK_OPERATIONS=true` | 通过 JSON 配置执行多任务定时群发；需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true` |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/send/`：定时群发入口（CLI `send-schedule` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n| `send-schedule` | Yes | `config/scheduled_tasks.json` | 仅支持 JSON 多任务配置；`interval_hours` 不小于 0.5；任务数最多 20 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Long-running commands now use isolated temporary session copies. If lock errors still appear (usually after abnormal exits), stop stale Python processes and retry. | `database is locked`：长驻命令已改为临时会话副本隔离；若仍出现锁冲突（多见于异常退出后），请先结束残留 Python 进程再重试。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- Uses isolated temporary session copies at runtime, reducing lock contention with other long-running commands. | 运行时使用独立临时会话副本，降低与其它长驻命令的会话锁冲突。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## Scheduled Messaging (send-schedule) — Feature Summary | 定时群发（send-schedule）— 功能摘要\n- Task source is fixed to `config/scheduled_tasks.json`, with top-level key `tasks` as an array. | 任务来源固定为 `config/scheduled_tasks.json`，顶层键为 `tasks` 数组。\n- Required fields per task: `name`, `target_group_id`, `message`, `interval_hours`. | 单任务必填字段：`name`、`target_group_id`、`message`、`interval_hours`。\n- Limits: `interval_hours >= 0.5`, and total tasks per run <= 20. | 限制：`interval_hours >= 0.5`，单次启动最多 20 个任务。\n- Scheduler runs independently from `monitor`, and logs all trigger times in Beijing time. | 调度进程与 `monitor` 独立运行，触发日志统一按北京时间输出。\n- Start command: `ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`. | 启动命令：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`。\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 与 `send-schedule` 均要求显式设置 `ENABLE_HIGH_RISK_OPERATIONS=true` 才可运行。 | Both `join` and `send-schedule` require explicit `ENABLE_HIGH_RISK_OPERATIONS=true`.\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式还需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode additionally requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `send-schedule` 使用 `config/scheduled_tasks.json`；`interval_hours` 不能小于 0.5，且任务数不能超过 20。 | `send-schedule` reads `config/scheduled_tasks.json`; `interval_hours` must be >= 0.5 and tasks <= 20.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.3.3:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.3.3\",\n  \"publishedAt\": 1776824289841\n}\n\nFile v1.3.3:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.3.3:skill-card.md\n\n## Description:\n\nTelegram Tools Suite provides Telegram account automation for group monitoring, group search, batch group joining, scheduled messages, and account queries.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[testman2025](https://clawhub.ai/user/testman2025)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to configure and run Telegram automation workflows for monitoring selected groups, searching groups by keyword, querying account or group data, joining groups from a list, and sending scheduled messages.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Reusable Telegram session credentials can expose the connected account if the workspace is shared, archived, or published.\n\nMitigation: Use a test account, keep the workspace private, exclude userdata and .env files from archives, and review session-file permissions after login.\n\nRisk: Scheduled sending and bulk group joining can risk account enforcement or misuse.\n\nMitigation: Keep high-risk operations disabled unless needed, explicitly enable them only for reviewed tasks, and verify target lists, message content, and frequency before execution.\n\n## Reference(s):\n\n- [Telegram API development tools](https://my.telegram.org)\n- [ClawHub skill page](https://clawhub.ai/testman2025/skills/telegram-tools-suite)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell commands and configuration guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce operational guidance for long-running Telegram commands and local configuration files.]\n\n## Skill Version(s):\n\n1.3.3 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.3.3:clawhub.yaml\n\nname: Telegram Tools Suite\nslug: telegram-tools-suite\nversion: 1.3.0\ndescription: Telegram自动化工具包，支持群关键词监控、群组搜索、批量加群、定时消息发送\nauthor: ClawHub Community\ntags:\n  - telegram\n  - automation\n  - monitoring\n  - marketing\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram官方申请的API ID\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram官方申请的API HASH\n    required: true\n  - name: TELEGRAM_PHONE\n    description: 绑定Telegram账号的手机号，国际格式，例如+8613800138000\n    required: true\n  - name: ENABLE_HIGH_RISK_OPERATIONS\n    description: 高风险功能总开关，开启批量加群、定时群发必须设置为true，默认禁用\n    required: false\n    default: \"false\"\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 批量加群长驻模式开关，开启长驻定时批量加群需要额外设置为true，默认禁用\n    required: false\n    default: \"false\"\nsecurity:\n  riskLevel: high\n  warnings:\n    - 高风险功能默认禁用，需显式开启\n    - 运行会生成高敏感的.session会话文件，禁止外传\n    - 使用不当可能导致Telegram账号永久封禁\n    - 禁止用于发送垃圾消息、骚扰他人等非法用途\n  designNotes:\n    - 临时会话复制逻辑：为避免多进程同时读写主会话文件导致数据库锁死，代码会自动生成临时会话副本，单次任务结束后自动删除，不会留存或外传任何会话数据\n    - 无对外数据传输：所有网络请求仅与Telegram官方服务器通信，无任何第三方数据上报或外传逻辑\n\nFile v1.3.3:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.3.3:requirements.txt\n\n# 与 pyproject.toml 同步\ntelethon>=1.34.0\nopenpyxl>=3.1.0\npython-dotenv>=1.0.0\n\nArchive v1.3.2: 32 files, 40583 bytes\n\nFiles: CHANGELOG.md (489b), clawhub.yaml (1283b), pyproject.toml (532b), README.md (14913b), requirements.txt (82b), setup.py (95b), SKILL.md (9129b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3337b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (2198b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8813b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12819b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (14967b), src/tg_monitor_kit/send/__init__.py (68b), src/tg_monitor_kit/send/runtime.py (6422b), src/tg_monitor_kit/session_runtime.py (2102b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1755b), _meta.json (139b)\n\nFile v1.3.2:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: ENABLE_HIGH_RISK_OPERATIONS\n    description: 高风险总开关（join/send-schedule 需设为 true 才可运行）\n    required: false\n    default: \"false\"\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径（默认 config/keywords.txt）\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。\n> 4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 与 `send-schedule` 均需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true` 才可运行；其中 `join` 长驻模式还需额外设置 `TG_ENABLE_PERSISTENT_JOIN=true`。定时群发由 `send-schedule` 子命令执行，并按 `config/scheduled_tasks.json` 的限制进行校验。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 在本地自行创建：`config/scheduled_tasks.json`\n2. 在 `scheduled_tasks.json` 中填写任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 校验限制：`interval_hours` 必须 `>= 0.5`，任务总数最多 20 个。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- 本技能发布包默认不包含 `config/` 目录内容；请在本地自行创建所需配置文件。\n- 监控：创建 `config/target_groups.txt`、`config/keywords.txt`、`config/monitor_regex_rules.json`。\n- 搜索：创建 `config/group_search_keywords.txt`、`config/group_search.json`。\n- 定时群发：创建 `config/scheduled_tasks.json`。\n- 批量加群：创建 `join_targets.txt`（或使用 `TG_JOIN_LIST_FILE` 指定路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n- `ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`：按 `config/scheduled_tasks.json` 执行定时群发（长驻）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join`、`send-schedule` 属于长驻任务，运行时会基于主会话复制临时会话副本；如遇异常退出仍可能触发 `database is locked`，请先结束残留进程后重试。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 在提供任何 Telegram 凭证前，必须先确认技能请求来源可信；发布方来源未知时，建议在一次性容器/隔离环境运行并使用测试账号。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.3.2:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n  - 加群（单轮）：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`\n  - 定时群发：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; requires `ENABLE_HIGH_RISK_OPERATIONS=true`. Persistent mode additionally requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true`。长驻模式还需 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `send-schedule` | Multi-task scheduled message sending by JSON config file; requires `ENABLE_HIGH_RISK_OPERATIONS=true` | 通过 JSON 配置执行多任务定时群发；需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true` |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/send/`：定时群发入口（CLI `send-schedule` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n| `send-schedule` | Yes | `config/scheduled_tasks.json` | 仅支持 JSON 多任务配置；`interval_hours` 不小于 0.5；任务数最多 20 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Long-running commands now use isolated temporary session copies. If lock errors still appear (usually after abnormal exits), stop stale Python processes and retry. | `database is locked`：长驻命令已改为临时会话副本隔离；若仍出现锁冲突（多见于异常退出后），请先结束残留 Python 进程再重试。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- Uses isolated temporary session copies at runtime, reducing lock contention with other long-running commands. | 运行时使用独立临时会话副本，降低与其它长驻命令的会话锁冲突。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## Scheduled Messaging (send-schedule) — Feature Summary | 定时群发（send-schedule）— 功能摘要\n- Task source is fixed to `config/scheduled_tasks.json`, with top-level key `tasks` as an array. | 任务来源固定为 `config/scheduled_tasks.json`，顶层键为 `tasks` 数组。\n- Required fields per task: `name`, `target_group_id`, `message`, `interval_hours`. | 单任务必填字段：`name`、`target_group_id`、`message`、`interval_hours`。\n- Limits: `interval_hours >= 0.5`, and total tasks per run <= 20. | 限制：`interval_hours >= 0.5`，单次启动最多 20 个任务。\n- Scheduler runs independently from `monitor`, and logs all trigger times in Beijing time. | 调度进程与 `monitor` 独立运行，触发日志统一按北京时间输出。\n- Start command: `ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`. | 启动命令：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`。\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 与 `send-schedule` 均要求显式设置 `ENABLE_HIGH_RISK_OPERATIONS=true` 才可运行。 | Both `join` and `send-schedule` require explicit `ENABLE_HIGH_RISK_OPERATIONS=true`.\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式还需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode additionally requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `send-schedule` 使用 `config/scheduled_tasks.json`；`interval_hours` 不能小于 0.5，且任务数不能超过 20。 | `send-schedule` reads `config/scheduled_tasks.json`; `interval_hours` must be >= 0.5 and tasks <= 20.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.3.2:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.3.2\",\n  \"publishedAt\": 1776823350045\n}\n\nFile v1.3.2:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.3.2:clawhub.yaml\n\nname: Telegram Tools Suite\nslug: telegram-tools-suite\nversion: 1.3.0\ndescription: Telegram自动化工具包，支持群关键词监控、群组搜索、批量加群、定时消息发送\nauthor: ClawHub Community\ntags:\n  - telegram\n  - automation\n  - monitoring\n  - marketing\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram官方申请的API ID\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram官方申请的API HASH\n    required: true\n  - name: TELEGRAM_PHONE\n    description: 绑定Telegram账号的手机号，国际格式，例如+8613800138000\n    required: true\n  - name: ENABLE_HIGH_RISK_OPERATIONS\n    description: 高风险功能总开关，开启批量加群、定时群发必须设置为true，默认禁用\n    required: false\n    default: \"false\"\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 批量加群长驻模式开关，开启长驻定时批量加群需要额外设置为true，默认禁用\n    required: false\n    default: \"false\"\nsecurity:\n  riskLevel: high\n  warnings:\n    - 高风险功能默认禁用，需显式开启\n    - 运行会生成高敏感的.session会话文件，禁止外传\n    - 使用不当可能导致Telegram账号永久封禁\n    - 禁止用于发送垃圾消息、骚扰他人等非法用途\n\nFile v1.3.2:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.3.2:requirements.txt\n\n# 与 pyproject.toml 同步\ntelethon>=1.34.0\nopenpyxl>=3.1.0\npython-dotenv>=1.0.0\n\nArchive v1.3.1: 32 files, 40238 bytes\n\nFiles: CHANGELOG.md (489b), clawhub.yaml (1082b), pyproject.toml (532b), README.md (14360b), requirements.txt (82b), setup.py (95b), SKILL.md (8542b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3337b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (2198b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8813b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12819b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (14967b), src/tg_monitor_kit/send/__init__.py (68b), src/tg_monitor_kit/send/runtime.py (6422b), src/tg_monitor_kit/session_runtime.py (2102b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1755b), _meta.json (139b)\n\nFile v1.3.1:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径（默认 config/keywords.txt）\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。\n> 4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 默认仅允许 `--once`；若需长驻必须设置 `TG_ENABLE_PERSISTENT_JOIN=true`。定时群发由 `send-schedule` 子命令执行，并按 `config/scheduled_tasks.json` 的限制进行校验。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 在本地自行创建：`config/scheduled_tasks.json`\n2. 在 `scheduled_tasks.json` 中填写任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`python3 -m tg_monitor_kit send-schedule`\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 校验限制：`interval_hours` 必须 `>= 0.5`，任务总数最多 20 个。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- 本技能发布包默认不包含 `config/` 目录内容；请在本地自行创建所需配置文件。\n- 监控：创建 `config/target_groups.txt`、`config/keywords.txt`、`config/monitor_regex_rules.json`。\n- 搜索：创建 `config/group_search_keywords.txt`、`config/group_search.json`。\n- 定时群发：创建 `config/scheduled_tasks.json`。\n- 批量加群：创建 `join_targets.txt`（或使用 `TG_JOIN_LIST_FILE` 指定路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n- `python3 -m tg_monitor_kit send-schedule`：按 `config/scheduled_tasks.json` 执行定时群发（长驻）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join`、`send-schedule` 属于长驻任务，运行时会基于主会话复制临时会话副本；如遇异常退出仍可能触发 `database is locked`，请先结束残留进程后重试。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.3.1:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n  - 加群（单轮）：`python3 -m tg_monitor_kit join --once`\n  - 定时群发：`python3 -m tg_monitor_kit send-schedule`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; default is one-shot only. Persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；默认仅单轮执行。长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `send-schedule` | Multi-task scheduled message sending by JSON config file | 通过 JSON 配置执行多任务定时群发 |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/send/`：定时群发入口（CLI `send-schedule` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n| `send-schedule` | Yes | `config/scheduled_tasks.json` | 仅支持 JSON 多任务配置；`interval_hours` 不小于 0.5；任务数最多 20 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Long-running commands now use isolated temporary session copies. If lock errors still appear (usually after abnormal exits), stop stale Python processes and retry. | `database is locked`：长驻命令已改为临时会话副本隔离；若仍出现锁冲突（多见于异常退出后），请先结束残留 Python 进程再重试。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- Uses isolated temporary session copies at runtime, reducing lock contention with other long-running commands. | 运行时使用独立临时会话副本，降低与其它长驻命令的会话锁冲突。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## Scheduled Messaging (send-schedule) — Feature Summary | 定时群发（send-schedule）— 功能摘要\n- Task source is fixed to `config/scheduled_tasks.json`, with top-level key `tasks` as an array. | 任务来源固定为 `config/scheduled_tasks.json`，顶层键为 `tasks` 数组。\n- Required fields per task: `name`, `target_group_id`, `message`, `interval_hours`. | 单任务必填字段：`name`、`target_group_id`、`message`、`interval_hours`。\n- Limits: `interval_hours >= 0.5`, and total tasks per run <= 20. | 限制：`interval_hours >= 0.5`，单次启动最多 20 个任务。\n- Scheduler runs independently from `monitor`, and logs all trigger times in Beijing time. | 调度进程与 `monitor` 独立运行，触发日志统一按北京时间输出。\n- Start command: `python3 -m tg_monitor_kit send-schedule`. | 启动命令：`python3 -m tg_monitor_kit send-schedule`。\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `send-schedule` 使用 `config/scheduled_tasks.json`；`interval_hours` 不能小于 0.5，且任务数不能超过 20。 | `send-schedule` reads `config/scheduled_tasks.json`; `interval_hours` must be >= 0.5 and tasks <= 20.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.3.1:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.3.1\",\n  \"publishedAt\": 1776769055292\n}\n\nFile v1.3.1:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.3.1:clawhub.yaml\n\nname: Telegram Tools Suite\nslug: telegram-tools-suite\nversion: 1.3.0\ndescription: Telegram自动化工具包，支持群关键词监控、群组搜索、批量加群、定时消息发送\nauthor: ClawHub Community\ntags:\n  - telegram\n  - automation\n  - monitoring\n  - marketing\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram官方申请的API ID\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram官方申请的API HASH\n    required: true\n  - name: TELEGRAM_PHONE\n    description: 绑定Telegram账号的手机号，国际格式，例如+8613800138000\n    required: true\n  - name: ENABLE_HIGH_RISK_OPERATIONS\n    description: 高风险功能开关，开启批量加群、定时群发必须设置为true，默认禁用\n    required: false\n    default: \"false\"\nsecurity:\n  riskLevel: high\n  warnings:\n    - 高风险功能默认禁用，需显式开启\n    - 运行会生成高敏感的.session会话文件，禁止外传\n    - 使用不当可能导致Telegram账号永久封禁\n    - 禁止用于发送垃圾消息、骚扰他人等非法用途\n\nFile v1.3.1:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.3.1:requirements.txt\n\n# 与 pyproject.toml 同步\ntelethon>=1.34.0\nopenpyxl>=3.1.0\npython-dotenv>=1.0.0\n\nArchive v1.3.0: 31 files, 39465 bytes\n\nFiles: CHANGELOG.md (489b), pyproject.toml (532b), README.md (14360b), requirements.txt (82b), setup.py (95b), SKILL.md (8542b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3337b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (2198b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8813b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12819b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (14967b), src/tg_monitor_kit/send/__init__.py (68b), src/tg_monitor_kit/send/runtime.py (6422b), src/tg_monitor_kit/session_runtime.py (2102b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1755b), _meta.json (139b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径（默认 config/keywords.txt）\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。\n> 4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 默认仅允许 `--once`；若需长驻必须设置 `TG_ENABLE_PERSISTENT_JOIN=true`。定时群发由 `send-schedule` 子命令执行，并按 `config/scheduled_tasks.json` 的限制进行校验。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 在本地自行创建：`config/scheduled_tasks.json`\n2. 在 `scheduled_tasks.json` 中填写任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`python3 -m tg_monitor_kit send-schedule`\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 校验限制：`interval_hours` 必须 `>= 0.5`，任务总数最多 20 个。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- 本技能发布包默认不包含 `config/` 目录内容；请在本地自行创建所需配置文件。\n- 监控：创建 `config/target_groups.txt`、`config/keywords.txt`、`config/monitor_regex_rules.json`。\n- 搜索：创建 `config/group_search_keywords.txt`、`config/group_search.json`。\n- 定时群发：创建 `config/scheduled_tasks.json`。\n- 批量加群：创建 `join_targets.txt`（或使用 `TG_JOIN_LIST_FILE` 指定路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n- `python3 -m tg_monitor_kit send-schedule`：按 `config/scheduled_tasks.json` 执行定时群发（长驻）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join`、`send-schedule` 属于长驻任务，运行时会基于主会话复制临时会话副本；如遇异常退出仍可能触发 `database is locked`，请先结束残留进程后重试。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.3.0:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n  - 加群（单轮）：`python3 -m tg_monitor_kit join --once`\n  - 定时群发：`python3 -m tg_monitor_kit send-schedule`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; default is one-shot only. Persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；默认仅单轮执行。长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `send-schedule` | Multi-task scheduled message sending by JSON config file | 通过 JSON 配置执行多任务定时群发 |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/send/`：定时群发入口（CLI `send-schedule` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n| `send-schedule` | Yes | `config/scheduled_tasks.json` | 仅支持 JSON 多任务配置；`interval_hours` 不小于 0.5；任务数最多 20 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Long-running commands now use isolated temporary session copies. If lock errors still appear (usually after abnormal exits), stop stale Python processes and retry. | `database is locked`：长驻命令已改为临时会话副本隔离；若仍出现锁冲突（多见于异常退出后），请先结束残留 Python 进程再重试。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- Uses isolated temporary session copies at runtime, reducing lock contention with other long-running commands. | 运行时使用独立临时会话副本，降低与其它长驻命令的会话锁冲突。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## Scheduled Messaging (send-schedule) — Feature Summary | 定时群发（send-schedule）— 功能摘要\n- Task source is fixed to `config/scheduled_tasks.json`, with top-level key `tasks` as an array. | 任务来源固定为 `config/scheduled_tasks.json`，顶层键为 `tasks` 数组。\n- Required fields per task: `name`, `target_group_id`, `message`, `interval_hours`. | 单任务必填字段：`name`、`target_group_id`、`message`、`interval_hours`。\n- Limits: `interval_hours >= 0.5`, and total tasks per run <= 20. | 限制：`interval_hours >= 0.5`，单次启动最多 20 个任务。\n- Scheduler runs independently from `monitor`, and logs all trigger times in Beijing time. | 调度进程与 `monitor` 独立运行，触发日志统一按北京时间输出。\n- Start command: `python3 -m tg_monitor_kit send-schedule`. | 启动命令：`python3 -m tg_monitor_kit send-schedule`。\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `send-schedule` 使用 `config/scheduled_tasks.json`；`interval_hours` 不能小于 0.5，且任务数不能超过 20。 | `send-schedule` reads `config/scheduled_tasks.json`; `interval_hours` must be >= 0.5 and tasks <= 20.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.3.0\",\n  \"publishedAt\": 1776768828954\n}\n\nFile v1.3.0:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.3.0:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.3.0:requirements.txt\n\n# 与 pyproject.toml 同步\ntelethon>=1.34.0\nopenpyxl>=3.1.0\npython-dotenv>=1.0.0\n\nArchive v1.2.4: 30 files, 37743 bytes\n\nFiles: CHANGELOG.md (489b), pyproject.toml (532b), README.md (14144b), requirements.txt (82b), setup.py (95b), SKILL.md (8470b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3337b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (2198b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8195b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12436b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (15512b), src/tg_monitor_kit/send/__init__.py (68b), src/tg_monitor_kit/send/runtime.py (5760b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1755b), _meta.json (139b)\n\nFile v1.2.4:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径（默认 config/keywords.txt）\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。\n> 4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 默认仅允许 `--once`；若需长驻必须设置 `TG_ENABLE_PERSISTENT_JOIN=true`。定时群发由 `send-schedule` 子命令执行，并按 `config/scheduled_tasks.json` 的限制进行校验。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 在本地自行创建：`config/scheduled_tasks.json`\n2. 在 `scheduled_tasks.json` 中填写任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`python3 -m tg_monitor_kit send-schedule`\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 校验限制：`interval_hours` 必须 `>= 0.5`，任务总数最多 20 个。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- 本技能发布包默认不包含 `config/` 目录内容；请在本地自行创建所需配置文件。\n- 监控：创建 `config/target_groups.txt`、`config/keywords.txt`、`config/monitor_regex_rules.json`。\n- 搜索：创建 `config/group_search_keywords.txt`、`config/group_search.json`。\n- 定时群发：创建 `config/scheduled_tasks.json`。\n- 批量加群：创建 `join_targets.txt`（或使用 `TG_JOIN_LIST_FILE` 指定路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n- `python3 -m tg_monitor_kit send-schedule`：按 `config/scheduled_tasks.json` 执行定时群发（长驻）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join`、`send-schedule` 属于长驻任务，同一会话名同一时刻仅运行一个，避免 `database is locked`。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.2.4:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n  - 加群（单轮）：`python3 -m tg_monitor_kit join --once`\n  - 定时群发：`python3 -m tg_monitor_kit send-schedule`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; default is one-shot only. Persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；默认仅单轮执行。长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `send-schedule` | Multi-task scheduled message sending by JSON config file | 通过 JSON 配置执行多任务定时群发 |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/send/`：定时群发入口（CLI `send-schedule` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n| `send-schedule` | Yes | `config/scheduled_tasks.json` | 仅支持 JSON 多任务配置；`interval_hours` 不小于 0.5；任务数最多 20 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Close other scripts occupying the same session, **do not run** `monitor`, `search` and `join` **at the same time**. | `database is locked`：关闭其它占用同一会话的脚本，**勿同时**跑 `monitor`、`search` 与 `join`。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- **Do not** run at the same time as `monitor`. | **不要**与 `monitor` 同时运行。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## Scheduled Messaging (send-schedule) — Feature Summary | 定时群发（send-schedule）— 功能摘要\n- Task source is fixed to `config/scheduled_tasks.json`, with top-level key `tasks` as an array. | 任务来源固定为 `config/scheduled_tasks.json`，顶层键为 `tasks` 数组。\n- Required fields per task: `name`, `target_group_id`, `message`, `interval_hours`. | 单任务必填字段：`name`、`target_group_id`、`message`、`interval_hours`。\n- Limits: `interval_hours >= 0.5`, and total tasks per run <= 20. | 限制：`interval_hours >= 0.5`，单次启动最多 20 个任务。\n- Scheduler runs independently from `monitor`, and logs all trigger times in Beijing time. | 调度进程与 `monitor` 独立运行，触发日志统一按北京时间输出。\n- Start command: `python3 -m tg_monitor_kit send-schedule`. | 启动命令：`python3 -m tg_monitor_kit send-schedule`。\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `send-schedule` 使用 `config/scheduled_tasks.json`；`interval_hours` 不能小于 0.5，且任务数不能超过 20。 | `send-schedule` reads `config/scheduled_tasks.json`; `interval_hours` must be >= 0.5 and tasks <= 20.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.2.4:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.2.4\",\n  \"publishedAt\": 1776762354414\n}\n\nFile v1.2.4:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.2.4:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.2.4:requirements.txt\n\n# 与 pyproject.toml 同步\ntelethon>=1.34.0\nopenpyxl>=3.1.0\npython-dotenv>=1.0.0\n\nArchive v1.2.3: 36 files, 39395 bytes\n\nFiles: CHANGELOG.md (489b), config.yaml (261b), config/group_search_keywords.txt (160b), config/group_search.json (538b), config/keywords.txt (250b), config/monitor_regex_rules.json (1543b), config/scheduled_tasks.example.json (586b), config/target_groups.txt (235b), pyproject.toml (532b), README.md (12922b), requirements.txt (82b), scheduled_send.py (4246b), setup.py (95b), SKILL.md (8841b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3115b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (2198b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8195b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12436b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (15512b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1755b), _meta.json (139b)\n\nFile v1.2.3:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n  - name: TG_RISK_ACK\n    description: 高风险动作确认，scheduled_send 需设为 I_UNDERSTAND\n    required: false\n  - name: SCHEDULED_TARGET_GROUP_ID\n    description: 单任务模式目标群 ID\n    required: false\n  - name: SCHEDULED_MESSAGE_CONTENT\n    description: 单任务模式消息内容\n    required: false\n  - name: SCHEDULED_INTERVAL_HOURS\n    description: 单任务模式发送间隔（小时，>=0.5）\n    required: false\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 默认仅允许 `--once`；若需长驻必须设置 `TG_ENABLE_PERSISTENT_JOIN=true`。`scheduled_send.py` 默认拒绝发送，需设置 `TG_RISK_ACK=I_UNDERSTAND` 后才执行。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 复制配置模板：`cp config/scheduled_tasks.example.json config/scheduled_tasks.json`\n2. 编辑`scheduled_tasks.json`，按示例格式添加多个任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`python3 scheduled_send.py`\n> 💡 兼容性说明：旧版本的单任务环境变量配置依然有效，若存在多任务配置文件则优先使用多任务配置。\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 风险确认：执行前必须设置 `TG_RISK_ACK=I_UNDERSTAND`。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- `config/target_groups.txt`：监控白名单群名（`monitor` 必需，空文件会拒绝启动）。\n- `config/monitor_regex_rules.json`：监控正则规则配置（可用 `TG_MONITOR_REGEX_RULES_FILE` 指定）。\n- `config/keywords.txt`：监控普通关键词（逐行匹配，可与正则规则叠加）。\n- `config/group_search_keywords.txt`：群搜索关键词（`search` 使用）。\n- `config/group_search.json`：群搜索时间、采样量、导出目录等参数。\n- `join_targets.txt`：批量加群目标列表（`join` 使用；可用 `TG_JOIN_LIST_FILE` 指定其他路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join` 属于长驻任务，同一会话名同一时刻仅运行一个，避免 `database is locked`。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.2.3:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n   - 加群（单轮）：`python3 -m tg_monitor_kit join --once`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; default is one-shot only. Persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；默认仅单轮执行。长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Close other scripts occupying the same session, **do not run** `monitor`, `search` and `join` **at the same time**. | `database is locked`：关闭其它占用同一会话的脚本，**勿同时**跑 `monitor`、`search` 与 `join`。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- **Do not** run at the same time as `monitor`. | **不要**与 `monitor` 同时运行。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `scheduled_send.py` 需要先设置 `TG_RISK_ACK=I_UNDERSTAND`，否则拒绝发送。 | `scheduled_send.py` requires `TG_RISK_ACK=I_UNDERSTAND` before sending.\n- `scheduled_send.py` 发送间隔必须 >= 30 分钟，且单次最多 20 个任务。 | `scheduled_send.py` enforces >=30 minutes interval and max 20 tasks.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.2.3:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.2.3\",\n  \"publishedAt\": 1776420193291\n}\n\nFile v1.2.3:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.2.3:config/group_search.json\n\n{\n  \"search_limit\": 40,\n  \"activity_sample\": 200,\n  \"run_on_startup\": true,\n  \"schedule_hour\": 18,\n  \"schedule_minute\": 30,\n  \"excel_output_dir\": \"daily_group_search\",\n  \"excel_headers\": [\n    \"查询时间(北京时间)\",\n    \"命中关键词\",\n    \"群名称\",\n    \"群类型\",\n    \"公开信息\",\n    \"链接\",\n    \"群ID\",\n    \"成员数\",\n    \"创建时间近似(北京时间)\",\n    \"最近消息时间(北京时间)\",\n    \"活跃度_24h_样本\",\n    \"活跃度_7d_样本\",\n    \"活跃度样本总量\",\n    \"可发言(推断)\"\n  ]\n}\n\nFile v1.2.3:config/monitor_regex_rules.json\n\n{\n  \"_PLATFORM_AD\": \"(?:\\\\b(?:facebook|google|tiktok|meta)\\\\s+ads\\\\b|\\\\badvertisement\\\\b|(?:谷歌|Google|脸书|Facebook|Meta|TikTok|抖音)\\\\s*广告)\",\n  \"rules\": [\n    [\"vcc\", \"\\\\bvcc\\\\b\", \"i\"],\n    [\"虚拟卡\", \"虚拟卡|虚拟\\\\s*信用卡\"],\n    [\"绑卡\", \"绑卡|绑\\\\s*卡\"],\n    [\"开卡\", \"(?<![不没])(?:开卡|开\\\\s*卡)\"],\n    [\"绑定\", \"(?<!不)绑定\"],\n    [\"bin\", \"\\\\bbin\\\\b\", \"i\"],\n    [\"绑定/绑卡+广告平台\", \"(?is)(?=.*(?:绑定|绑\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"开卡+广告平台\", \"(?is)(?=.*(?<![不没])(?:开卡|开\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"vcc+广告平台\", \"(?is)(?=.*\\\\bvcc\\\\b)(?=.*{_PLATFORM_AD})\"],\n    [\"虚拟卡+广告平台\", \"(?is)(?=.*(?:虚拟卡|虚拟\\\\s*信用卡))(?=.*{_PLATFORM_AD})\"]\n  ]\n}\n{\n  \"_PLATFORM_AD\": \"(?:\\\\b(?:facebook|google|tiktok|meta)\\\\s+ads\\\\b|\\\\badvertisement\\\\b|(?:谷歌|Google|脸书|Facebook|Meta|TikTok|抖音)\\\\s*广告)\",\n  \"rules\": [\n    [\"vcc\", \"\\\\bvcc\\\\b\", \"i\"],\n    [\"虚拟卡\", \"虚拟卡|虚拟\\\\s*信用卡\"],\n    [\"绑卡\", \"绑卡|绑\\\\s*卡\"],\n    [\"开卡\", \"(?<![不没])(?:开卡|开\\\\s*卡)\"],\n    [\"绑定\", \"(?<!不)绑定\"],\n    [\"bin\", \"\\\\bbin\\\\b\", \"i\"],\n    [\"绑定/绑卡+广告平台\", \"(?is)(?=.*(?:绑定|绑\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"开卡+广告平台\", \"(?is)(?=.*(?<![不没])(?:开卡|开\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"vcc+广告平台\", \"(?is)(?=.*\\\\bvcc\\\\b)(?=.*{_PLATFORM_AD})\"],\n    [\"虚拟卡+广告平台\", \"(?is)(?=.*(?:虚拟卡|虚拟\\\\s*信用卡))(?=.*{_PLATFORM_AD})\")\n  ]\n}\n\nFile v1.2.3:config/scheduled_tasks.example.json\n\n{\n  \"tasks\": [\n    {\n      \"name\": \"VCC推广-群A\",\n      \"target_group_id\": -1001234567890,\n      \"message\": \"VCC-虚拟卡超低费率+超高返点，欢迎咨询\",\n      \"interval_hours\": 2\n    },\n    {\n      \"name\": \"开卡推广-群B\",\n      \"target_group_id\": -1000987654321,\n      \"message\": \"开卡找我，最快5分钟下户，费率低至0.3%\",\n      \"interval_hours\": 3\n    },\n    {\n      \"name\": \"新用户福利-群C\",\n      \"target_group_id\": -1001122334455,\n      \"message\": \"新用户首次开卡送10美金额度，限前50名\",\n      \"interval_hours\": 4\n    }\n  ]\n}\n\nFile v1.2.3:config.yaml\n\nmonitor:\n  groups:\n    - \"梦西游-出海交流群\"\n    - \"嘿嘿虚拟信用卡vcc\"\n  keywords:\n    - \"vcc\"\n    - \"开卡\"\n    - \"虚拟信用卡\"\n    - \"优惠\"\n    - \"折扣\"\n    - \"渠道\"\n  notify: \"telegram\"\n  daily_summary: true\n  summary_time: \"18:00\"\n\nFile v1.2.3:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.2.3:config/group_search_keywords.txt\n\n# 群搜索关键词（每行一个，支持 + 连接词，如 facebook+ads）\nfacebook ads\ngoogle ads\ntiktok ads\nfacebook+ads\ngoogle+ads\ntiktok+ads\n出海+ads\n\nFile v1.2.3:config/keywords.txt\n\n# 关键词监控列表（每行一个关键词，命中时会触发提醒）\n# 示例：\n# 测试关键词\n# Facebook\n# Ads\n# Ecommerce\n# 优惠券\n# 折扣\n# 免费\n# 引流\n# 跨境\n# 选品\n# 站群\n# 投放\n# 广告账户\n# BM\n# 像素\n# 转化\n\nFile v1.2.3:config/target_groups.txt\n\n# 关键词监控白名单群组（每行一个，支持群标题文本匹配）\n# 建议只保存在本地，不要提交真实群名到代码仓库。\n#\n# 示例（请替换为你的真实群名）：\n# 示例群组A\n# 示例群组B\n\nArchive v1.2.2: 36 files, 39031 bytes\n\nFiles: CHANGELOG.md (489b), config.yaml (261b), config/group_search_keywords.txt (160b), config/group_search.json (538b), config/keywords.txt (250b), config/monitor_regex_rules.json (1543b), config/scheduled_tasks.example.json (586b), config/target_groups.txt (235b), pyproject.toml (532b), README.md (12922b), requirements.txt (82b), scheduled_send.py (3902b), setup.py (95b), SKILL.md (9139b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3115b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (1940b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8195b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12436b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (15145b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1593b), _meta.json (139b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n  - name: TG_RISK_ACK\n    description: 高风险动作确认，scheduled_send 需设为 I_UNDERSTAND\n    required: false\n  - name: SCHEDULED_TARGET_GROUP_ID\n    description: 单任务模式目标群 ID\n    required: false\n  - name: SCHEDULED_MESSAGE_CONTENT\n    description: 单任务模式消息内容\n    required: false\n  - name: SCHEDULED_INTERVAL_HOURS\n    description: 单任务模式发送间隔（小时，>=0.5）\n    required: false\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。\n> 3. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 默认仅允许 `--once`；若需长驻必须设置 `TG_ENABLE_PERSISTENT_JOIN=true`。`scheduled_send.py` 默认拒绝发送，需设置 `TG_RISK_ACK=I_UNDERSTAND` 后才执行。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 复制配置模板：`cp config/scheduled_tasks.example.json config/scheduled_tasks.json`\n2. 编辑`scheduled_tasks.json`，按示例格式添加多个任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`python3 scheduled_send.py`\n> 💡 兼容性说明：旧版本的单任务环境变量配置依然有效，若存在多任务配置文件则优先使用多任务配置。\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 风险确认：执行前必须设置 `TG_RISK_ACK=I_UNDERSTAND`。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- `config/target_groups.txt`：监控白名单群名（`monitor` 必需，空文件会拒绝启动）。\n- `config/monitor_regex_rules.json`：监控正则规则配置（可用 `TG_MONITOR_REGEX_RULES_FILE` 指定）。\n- `config/keywords.txt`：监控普通关键词（逐行匹配，可与正则规则叠加）。\n- `config/group_search_keywords.txt`：群搜索关键词（`search` 使用）。\n- `config/group_search.json`：群搜索时间、采样量、导出目录等参数。\n- `join_targets.txt`：批量加群目标列表（`join` 使用；可用 `TG_JOIN_LIST_FILE` 指定其他路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members --group \"群名称\"`：导出指定群成员（需要群名）。\n- `python3 -m tg_monitor_kit history --group \"群名称\" --limit 100`：导出指定群最近消息（需要群名；`--limit` 可选）。\n- `python3 -m tg_monitor_kit monitor`：关键词监控（长驻）。\n- `python3 -m tg_monitor_kit search`：群搜索（长驻，按配置定时）。\n- `python3 -m tg_monitor_kit join --once`：批量加群（单轮）。\n- `TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join`：批量加群（长驻定时，默认关闭）。\n\n### 停止长驻任务\n- 前台运行：按 `Ctrl+C` 终止。\n- 后台运行：结束对应 Python 进程。\n\n## Rules\n\n- 严禁在对话或日志中输出 `TELEGRAM_API_HASH`、短信验证码、`.session` 文件内容。\n- `monitor`、`search`、`join` 属于长驻任务，同一会话名同一时刻仅运行一个，避免 `database is locked`。\n- 所有定时相关行为按北京时间（UTC+8）理解与配置。\n- 批量加群存在风控风险，需由使用者自行确认目标与频率合规。\n\n## Examples\n\n### 示例 1：首次登录\n输入：用户已填写 `.env`，需要首次登录。  \n执行：先 `python3 -m tg_monitor_kit auth`，再设置 `TG_CODE`、`TG_PHONE_CODE_HASH`，再 `python3 -m tg_monitor_kit login`。  \n输出：`LOGIN_SUCCESS`。\n\n### 示例 2：开启监控\n输入：用户已在 `config/target_groups.txt` 填写群名。  \n执行：`python3 -m tg_monitor_kit monitor`。  \n输出：控制台显示监控启动信息，命中关键词后推送通知。\n\n### 示例 3：批量加群单轮执行\n输入：用户已准备 `join_targets.txt`。  \n执行：`python3 -m tg_monitor_kit join --once`。  \n输出：返回成功/已在群/失败统计。\n\nFile v1.2.2:README.md\n\n# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n   - 加群（单轮）：`python3 -m tg_monitor_kit join --once`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel summary | 白名单群关键词监控、命中推送、每日 18:00 Excel 汇总 |\n| `search` | Keyword-based supergroup search, scheduled daily, export to configured directory | 关键词搜超级群、按配置定时、导出到可配置目录 |\n| `join` | Batch join groups from list file; default is one-shot only. Persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true` | 从清单文件批量加群；默认仅单轮执行。长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true` |\n| `groups` | List joined groups/channels | 列出已加入群/频道 |\n| `members --group \"group name\"` | Group member list | 群成员列表 |\n| `history --group \"group name\" [--limit N]` | Recent messages | 最近消息 |\n| `account-info` | Current account information | 当前账号信息 |\n| `auth` | Request SMS verification code when not logged in (requires `TELEGRAM_PHONE`) | 未登录时请求短信验证码（需 `TELEGRAM_PHONE`） |\n| `login` | Complete login using environment variables `TG_CODE`, `TG_PHONE_CODE_HASH` | 使用环境变量 `TG_CODE`、`TG_PHONE_CODE_HASH` 完成登录 |\n\nExamples | 示例：\n```bash\ncd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor\n```\n\n## Code Organization | 代码组织\n- `src/tg_monitor_kit/monitoring/`：群监控入口（CLI `monitor` 使用）\n- `src/tg_monitor_kit/search/`：群搜索入口（CLI `search` 使用）\n- `src/tg_monitor_kit/join/`：批量加群入口（CLI `join` 使用）\n- `src/tg_monitor_kit/tools/`：查询类工具命令（`account-info` / `members` / `history`）\n\n## Command Input Matrix | 命令与用户输入要求\n| Command | Need user input? | Input source | 说明 |\n|--------|------------------|-------------|------|\n| `auth` | Yes | `.env` / env `TELEGRAM_PHONE` | 请求短信验证码，返回 `phone_code_hash` |\n| `login` | Yes | env `TG_CODE` + `TG_PHONE_CODE_HASH` | 完成登录 |\n| `groups` | No | - | 查看已加入群 |\n| `account-info` | No | - | 查看账号信息 |\n| `members --group` | Yes | CLI 参数 `--group` | 群名需与 Telegram 中一致 |\n| `history --group --limit` | Yes | CLI 参数 | `--limit` 默认 100 |\n| `monitor` | Yes | `config/target_groups.txt` | 文件为空会拒绝启动 |\n| `search` | Yes | `config/group_search_keywords.txt` / `config/group_search.json` | 关键词和定时参数可配置 |\n| `join [--once]` | Yes | `join_targets.txt` / env `TG_JOIN_LIST_FILE` | 每行一个目标，支持链接/用户名 |\n\n## Keyword Monitoring (monitor) — Feature Summary | 关键词监控（monitor）— 功能摘要\n- Listen to whitelist groups from `config/target_groups.txt` (or env `TG_TARGET_GROUPS_FILE`); monitor will not start when the list is empty. | 监听白名单群来自 `config/target_groups.txt`（或环境变量 `TG_TARGET_GROUPS_FILE`）；名单为空时监控不会启动。\n- Keyword rules are loaded from `config/monitor_regex_rules.json` (or env `TG_MONITOR_REGEX_RULES_FILE`), and plain keywords are loaded from `config/keywords.txt` (or env `TG_KEYWORDS_FILE`); `SPAM_SKIP_PATTERNS` filters some spam templates. | 正则规则从 `config/monitor_regex_rules.json`（或环境变量 `TG_MONITOR_REGEX_RULES_FILE`）读取，普通关键词从 `config/keywords.txt`（或环境变量 `TG_KEYWORDS_FILE`）读取；`SPAM_SKIP_PATTERNS` 过滤部分垃圾模板。\n- Print to console after hit, and push to `NOTIFY_TARGET` (default `me`). | 命中后控制台打印，并向 `NOTIFY_TARGET`（默认 `me`）推送。\n- Export `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx` at 18:00 Beijing time daily (relative to **project root**). | 每日北京时间 18:00 导出 `daily_excel_summary/YYYY-MM-DD_监控汇总.xlsx`（相对**项目根**）。\n\n### Pre-run Check | 运行前检查\n- Available session file exists; proxy is reachable (default `127.0.0.1:1087`, configured by `TELEGRAM_PROXY_HTTP_*`). | 已存在可用会话文件；代理可达（默认 `127.0.0.1:1087`，由 `TELEGRAM_PROXY_HTTP_*` 配置）。\n- `telethon` and `openpyxl` are installed. | 已安装 `telethon`、`openpyxl`。\n\n### Session File Description | 会话文件说明\n- `*.session`: Login state SQLite, must be retained. | `*.session`：登录态 SQLite，须保留。\n- `*.session-journal`: SQLite log, paired with `.session`; may exist temporarily after abnormal exit. | `*.session-journal`：SQLite 日志，与 `.session` 成套；异常退出后可能短暂存在。\n\n### Verification Steps | 验证步骤\n1. Log like \"Telegram monitoring service has started\" appears after startup. | 启动后出现「Telegram 监控服务已启动」类日志。\n2. Send a message containing keywords in the whitelist group. | 在白名单群发送含关键词消息。\n3. \"Keyword monitoring notification\" print appears in the terminal. | 终端出现「关键词监控通知」打印。\n\n### Startup Failure Troubleshooting | 启动失败排查\n1. Long time no connection: Check proxy and network. | 长时间未连接：查代理与网络。\n2. `database is locked`: Close other scripts occupying the same session, **do not run** `monitor`, `search` and `join` **at the same time**. | `database is locked`：关闭其它占用同一会话的脚本，**勿同时**跑 `monitor`、`search` 与 `join`。\n3. `tg_monitor.lock`: Reject the second instance when there is already a monitoring instance; you can manually delete the lock file after abnormal exit (confirm no process is occupied). `join` uses `tg_join_from_list.lock`. | `tg_monitor.lock`：已有监控实例时拒绝第二实例；异常退出可手动删除锁文件（确认无进程占用）。`join` 使用 `tg_join_from_list.lock`。\n4. `file is not a database`: Back up and delete the damaged `.session` / journal, then `auth` → `login`. | `file is not a database`：备份并删除损坏的 `.session` / journal，再 `auth` → `login`。\n\n## Group Search (search) — Feature Summary | 群搜索（search）— 功能摘要\n- Keyword list is read from `config/group_search_keywords.txt` (or env `TG_GROUP_SEARCH_KEYWORDS_FILE`). | 关键词从 `config/group_search_keywords.txt` 读取（或环境变量 `TG_GROUP_SEARCH_KEYWORDS_FILE`）。\n- Schedule/search/output parameters are read from `config/group_search.json` (or env `TG_GROUP_SEARCH_SETTINGS_FILE`). | 定时/搜索/导出参数从 `config/group_search.json` 读取（或环境变量 `TG_GROUP_SEARCH_SETTINGS_FILE`）。\n- **Do not** run at the same time as `monitor`. | **不要**与 `monitor` 同时运行。\n\n## Batch Group Joining (join) — Feature Summary | 批量加群（join）— 功能摘要\n- Place the list file **`join_targets.txt`** in the project root (or specify the absolute path or path relative to the project root through the environment variable **`TG_JOIN_LIST_FILE`**), one target per line: public group `@username` / `username`, `https://t.me/username`, `https://t.me/+invitation hash`, `https://t.me/joinchat/...`, etc. Empty lines and lines starting with `#` are ignored; duplicate targets are deduplicated. | 在项目根放置清单文件 **`join_targets.txt`**（或通过环境变量 **`TG_JOIN_LIST_FILE`** 指定绝对路径或相对项目根的路径），每行一个目标：公开群 `@username` / `username`、`https://t.me/username`、`https://t.me/+邀请哈希`、`https://t.me/joinchat/...` 等。空行与 `#` 开头行忽略；同一目标会去重。\n- Persistent mode is disabled by default. Set `TG_ENABLE_PERSISTENT_JOIN=true` to enable scheduled looping. | 长驻模式默认关闭。需显式设置 `TG_ENABLE_PERSISTENT_JOIN=true` 才会按计划循环执行。\n- Hard limits: join interval must be >= 30 minutes, and joins per round must be <= 20; startup is rejected when violated. | 硬限制：加群间隔必须 >= 30 分钟，且每轮加群数 <= 20；超限会拒绝启动。\n- After each round, push success/already in group/failure statistics to favorites (`NOTIFY_TARGET = me`). It will automatically wait and retry when encountering `FloodWait`. | 每轮结束后向收藏夹（`NOTIFY_TARGET = me`）推送成功/已在群/失败统计。遇 `FloodWait` 会自动等待后重试。\n- **Risk Control**: Batch joining groups may trigger Telegram rate limiting or violate terms of service, please control the list content and frequency by yourself; invalid invitation links, requiring administrator review, full group capacity, etc. will be recorded as failures. | **风控**：批量加群\n\n## High-Risk Safeguards | 高风险能力保护\n- `join` 默认仅允许单轮模式（`--once`）；长驻模式需设置 `TG_ENABLE_PERSISTENT_JOIN=true`。 | `join` is one-shot by default; persistent mode requires `TG_ENABLE_PERSISTENT_JOIN=true`.\n- `scheduled_send.py` 需要先设置 `TG_RISK_ACK=I_UNDERSTAND`，否则拒绝发送。 | `scheduled_send.py` requires `TG_RISK_ACK=I_UNDERSTAND` before sending.\n- `scheduled_send.py` 发送间隔必须 >= 30 分钟，且单次最多 20 个任务。 | `scheduled_send.py` enforces >=30 minutes interval and max 20 tasks.\n\n## Stop Long-Running Tasks | 如何停止长驻任务\n- 前台运行：按 `Ctrl+C`。 | Foreground run: press `Ctrl+C`.\n- 后台运行：结束对应 Python 进程。 | Background run: terminate the corresponding Python process.\n\nFile v1.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.2.2\",\n  \"publishedAt\": 1776419486512\n}\n\nFile v1.2.2:CHANGELOG.md\n\n# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。\n\nFile v1.2.2:config/group_search.json\n\n{\n  \"search_limit\": 40,\n  \"activity_sample\": 200,\n  \"run_on_startup\": true,\n  \"schedule_hour\": 18,\n  \"schedule_minute\": 30,\n  \"excel_output_dir\": \"daily_group_search\",\n  \"excel_headers\": [\n    \"查询时间(北京时间)\",\n    \"命中关键词\",\n    \"群名称\",\n    \"群类型\",\n    \"公开信息\",\n    \"链接\",\n    \"群ID\",\n    \"成员数\",\n    \"创建时间近似(北京时间)\",\n    \"最近消息时间(北京时间)\",\n    \"活跃度_24h_样本\",\n    \"活跃度_7d_样本\",\n    \"活跃度样本总量\",\n    \"可发言(推断)\"\n  ]\n}\n\nFile v1.2.2:config/monitor_regex_rules.json\n\n{\n  \"_PLATFORM_AD\": \"(?:\\\\b(?:facebook|google|tiktok|meta)\\\\s+ads\\\\b|\\\\badvertisement\\\\b|(?:谷歌|Google|脸书|Facebook|Meta|TikTok|抖音)\\\\s*广告)\",\n  \"rules\": [\n    [\"vcc\", \"\\\\bvcc\\\\b\", \"i\"],\n    [\"虚拟卡\", \"虚拟卡|虚拟\\\\s*信用卡\"],\n    [\"绑卡\", \"绑卡|绑\\\\s*卡\"],\n    [\"开卡\", \"(?<![不没])(?:开卡|开\\\\s*卡)\"],\n    [\"绑定\", \"(?<!不)绑定\"],\n    [\"bin\", \"\\\\bbin\\\\b\", \"i\"],\n    [\"绑定/绑卡+广告平台\", \"(?is)(?=.*(?:绑定|绑\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"开卡+广告平台\", \"(?is)(?=.*(?<![不没])(?:开卡|开\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"vcc+广告平台\", \"(?is)(?=.*\\\\bvcc\\\\b)(?=.*{_PLATFORM_AD})\"],\n    [\"虚拟卡+广告平台\", \"(?is)(?=.*(?:虚拟卡|虚拟\\\\s*信用卡))(?=.*{_PLATFORM_AD})\"]\n  ]\n}\n{\n  \"_PLATFORM_AD\": \"(?:\\\\b(?:facebook|google|tiktok|meta)\\\\s+ads\\\\b|\\\\badvertisement\\\\b|(?:谷歌|Google|脸书|Facebook|Meta|TikTok|抖音)\\\\s*广告)\",\n  \"rules\": [\n    [\"vcc\", \"\\\\bvcc\\\\b\", \"i\"],\n    [\"虚拟卡\", \"虚拟卡|虚拟\\\\s*信用卡\"],\n    [\"绑卡\", \"绑卡|绑\\\\s*卡\"],\n    [\"开卡\", \"(?<![不没])(?:开卡|开\\\\s*卡)\"],\n    [\"绑定\", \"(?<!不)绑定\"],\n    [\"bin\", \"\\\\bbin\\\\b\", \"i\"],\n    [\"绑定/绑卡+广告平台\", \"(?is)(?=.*(?:绑定|绑\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"开卡+广告平台\", \"(?is)(?=.*(?<![不没])(?:开卡|开\\\\s*卡))(?=.*{_PLATFORM_AD})\"],\n    [\"vcc+广告平台\", \"(?is)(?=.*\\\\bvcc\\\\b)(?=.*{_PLATFORM_AD})\"],\n    [\"虚拟卡+广告平台\", \"(?is)(?=.*(?:虚拟卡|虚拟\\\\s*信用卡))(?=.*{_PLATFORM_AD})\")\n  ]\n}\n\nFile v1.2.2:config/scheduled_tasks.example.json\n\n{\n  \"tasks\": [\n    {\n      \"name\": \"VCC推广-群A\",\n      \"target_group_id\": -1001234567890,\n      \"message\": \"VCC-虚拟卡超低费率+超高返点，欢迎咨询\",\n      \"interval_hours\": 2\n    },\n    {\n      \"name\": \"开卡推广-群B\",\n      \"target_group_id\": -1000987654321,\n      \"message\": \"开卡找我，最快5分钟下户，费率低至0.3%\",\n      \"interval_hours\": 3\n    },\n    {\n      \"name\": \"新用户福利-群C\",\n      \"target_group_id\": -1001122334455,\n      \"message\": \"新用户首次开卡送10美金额度，限前50名\",\n      \"interval_hours\": 4\n    }\n  ]\n}\n\nFile v1.2.2:config.yaml\n\nmonitor:\n  groups:\n    - \"梦西游-出海交流群\"\n    - \"嘿嘿虚拟信用卡vcc\"\n  keywords:\n    - \"vcc\"\n    - \"开卡\"\n    - \"虚拟信用卡\"\n    - \"优惠\"\n    - \"折扣\"\n    - \"渠道\"\n  notify: \"telegram\"\n  daily_summary: true\n  summary_time: \"18:00\"\n\nFile v1.2.2:pyproject.toml\n\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"tg-monitor-kit\"\nversion = \"0.1.0\"\ndescription = \"Telegram keyword monitor and group search (Telethon)\"\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\ndependencies = [\n    \"telethon>=1.34.0\",\n    \"openpyxl>=3.1.0\",\n    \"python-dotenv>=1.0.0\",\n]\n\n[project.scripts]\ntg-monitor = \"tg_monitor_kit.cli.main:main\"\n\n[tool.setuptools.packages.find]\nwhere = [\"src\"]\n\n[tool.setuptools.package-data]\ntg_monitor_kit = [\"py.typed\"]\n\nFile v1.2.2:config/group_search_keywords.txt\n\n# 群搜索关键词（每行一个，支持 + 连接词，如 facebook+ads）\nfacebook ads\ngoogle ads\ntiktok ads\nfacebook+ads\ngoogle+ads\ntiktok+ads\n出海+ads\n\nFile v1.2.2:config/keywords.txt\n\n# 关键词监控列表（每行一个关键词，命中时会触发提醒）\n# 示例：\n# 测试关键词\n# Facebook\n# Ads\n# Ecommerce\n# 优惠券\n# 折扣\n# 免费\n# 引流\n# 跨境\n# 选品\n# 站群\n# 投放\n# 广告账户\n# BM\n# 像素\n# 转化\n\nFile v1.2.2:config/target_groups.txt\n\n# 关键词监控白名单群组（每行一个，支持群标题文本匹配）\n# 建议只保存在本地，不要提交真实群名到代码仓库。\n#\n# 示例（请替换为你的真实群名）：\n# 示例群组A\n# 示例群组B\n\nArchive v1.2.1: 36 files, 38916 bytes\n\nFiles: CHANGELOG.md (489b), config.yaml (261b), config/group_search_keywords.txt (160b), config/group_search.json (538b), config/keywords.txt (250b), config/monitor_regex_rules.json (1543b), config/scheduled_tasks.example.json (586b), config/target_groups.txt (235b), pyproject.toml (532b), README.md (12922b), requirements.txt (82b), scheduled_send.py (3902b), setup.py (95b), SKILL.md (8248b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3115b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (1940b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8195b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12436b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (15145b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1593b), _meta.json (139b)\n\nFile v1.2.1:SKILL.md\n\n---\nname: Telegram Tools Suite\ndescription: \"Telegram automation toolkit, supports group monitoring, scheduled messaging, auto group joining, group search, member export and more | 【重要提示】运行时会生成敏感会话文件、包含长时间运行的持久任务，安装前请仔细阅读使用文档\"\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: \"Telegram API ID, obtained from https://my.telegram.org\"\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: \"Telegram API Hash, obtained from https://my.telegram.org\"\n    required: true\n  - name: TELEGRAM_PHONE\n    description: \"Telegram account phone number (international format, e.g. +8613xxxxxxxxx)\"\n    required: true\noptionalEnv:\n  - name: SCHEDULED_TARGET_GROUP_ID\n    description: \"【单任务模式】定时发送功能：目标群组ID\"\n    required: false\n  - name: SCHEDULED_MESSAGE_CONTENT\n    description: \"【单任务模式】定时发送功能：要发送的消息内容\"\n    required: false\n  - name: SCHEDULED_INTERVAL_HOURS\n    description: \"【单任务模式】定时发送功能：发送间隔（小时，必须大于0）\"\n    required: false\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> ### ✅ 整改说明（已完成全量安全加固）\n> 1. **批量加群风险控制**：`join`命令默认仅执行单轮加群（等效`--once`参数），如需启用长驻定时加群功能，必须显式设置环境变量`TG_ENABLE_PERSISTENT_JOIN=true`才会生效\n> 2. **定时发送风险闸门**：`scheduled_send.py`定时群发任务启动前必须显式设置环境变量`TG_RISK_ACK=I_UNDERSTAND`确认风险，否则直接拒绝启动\n> 3. **频率限流规则**：所有自动发送/加群操作默认最小间隔30分钟，单轮批量加群最多执行20次，避免账号风控\n> 4. **敏感文件统一管理**：所有会话文件、缓存、运行时数据统一存储到`userdata/`目录，已默认加入`.gitignore`/`.clawignore`全局排除，不会被提交到代码仓库或发布\n> \n> ### 📋 运行说明\n> 1. **必填凭据**：使用前必须配置3项必填环境变量：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`，所有凭据均需用户自行申请填写，工具无内置任何默认凭据\n> 2. **长驻任务默认关闭**：所有长驻运行任务默认未启用，需用户手动执行对应命令才会启动；任务停止方式：按`Ctrl+C`即可终止当前运行的任务\n> 3. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。\n> 3. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 默认仅允许 `--once`；若需长驻必须设置 `TG_ENABLE_PERSISTENT_JOIN=true`。`scheduled_send.py` 默认拒绝发送，需设置 `TG_RISK_ACK=I_UNDERSTAND` 后才执行。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_hash`\n3. **配置环境变量**：复制`.env.example`为`.env`，填入3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、`TELEGRAM_PHONE`（国际格式，如`+8613xxxxxxxxx`）\n4. **请求验证码**：执行 `python3 -m tg_monitor_kit auth`，记录输出的`SENT_CODE_SUCCESS:<phone_code_hash>`中的hash值\n5. **完成登录**：设置环境变量`TG_CODE`（收到的短信验证码）、`TG_PHONE_CODE_HASH`（上一步获取的hash），执行`python3 -m tg_monitor_kit login`，输出`LOGIN_SUCCESS`即为登录成功\n6. **连通性验证**：执行 `python3 -m tg_monitor_kit groups`，输出账号下的群组列表代表功能正常可用\n\n### 🔹 多群定时发送功能使用说明\n支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：\n1. 复制配置模板：`cp config/scheduled_tasks.example.json config/scheduled_tasks.json`\n2. 编辑`scheduled_tasks.json`，按示例格式添加多个任务：\n   - `name`：任务备注名，方便识别\n   - `target_group_id`：目标群组ID（可以从`groups`命令输出中获取）\n   - `message`：要发送的消息内容\n   - `interval_hours`：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）\n3. 启动定时任务：`python3 scheduled_send.py`\n> 💡 兼容性说明：旧版本的单任务环境变量配置依然有效，若存在多任务配置文件则优先使用多任务配置。\n> ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。\n> ⚠️ 风险确认：执行前必须设置 `TG_RISK_ACK=I_UNDERSTAND`。\n\n\n### Runtime Config Files (运行前按需编辑)\n\n- `config/target_groups.txt`：监控白名单群名（`monitor` 必需，空文件会拒绝启动）。\n- `config/monitor_regex_rules.json`：监控正则规则配置（可用 `TG_MONITOR_REGEX_RULES_FILE` 指定）。\n- `config/keywords.txt`：监控普通关键词（逐行匹配，可与正则规则叠加）。\n- `config/group_search_keywords.txt`：群搜索关键词（`search` 使用）。\n- `config/group_search.json`：群搜索时间、采样量、导出目录等参数。\n- `join_targets.txt`：批量加群目标列表（`join` 使用；可用 `TG_JOIN_LIST_FILE` 指定其他路径）。\n\n### Command Guide (命令入口)\n\n- `python3 -m tg_monitor_kit groups`：列出已加入群/频道（无需额外参数）。\n- `python3 -m tg_monitor_kit account-info`：查看当前账号信息（无需额外参数）。\n- `python3 -m tg_monitor_kit members \n\nArchive v1.2.0: 36 files, 38665 bytes\n\nFiles: CHANGELOG.md (489b), config.yaml (261b), config/group_search_keywords.txt (160b), config/group_search.json (538b), config/keywords.txt (250b), config/monitor_regex_rules.json (1543b), config/scheduled_tasks.example.json (586b), config/target_groups.txt (235b), pyproject.toml (532b), README.md (12922b), requirements.txt (82b), scheduled_send.py (3902b), setup.py (95b), SKILL.md (7219b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3115b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2753b), src/tg_monitor_kit/group_query.py (1940b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (8195b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12436b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (15145b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1593b), _meta.json (139b)\n\nArchive v1.1.1: 36 files, 37301 bytes\n\nFiles: CHANGELOG.md (489b), config.yaml (261b), config/group_search_keywords.txt (160b), config/group_search.json (538b), config/keywords.txt (250b), config/monitor_regex_rules.json (1543b), config/scheduled_tasks.example.json (586b), config/target_groups.txt (235b), pyproject.toml (532b), README.md (12239b), requirements.txt (82b), scheduled_send.py (2938b), setup.py (95b), SKILL.md (6758b), src/tg_monitor_kit/__init__.py (142b), src/tg_monitor_kit/__main__.py (80b), src/tg_monitor_kit/auth.py (933b), src/tg_monitor_kit/cli/__init__.py (22b), src/tg_monitor_kit/cli/main.py (3115b), src/tg_monitor_kit/client.py (402b), src/tg_monitor_kit/config.py (2651b), src/tg_monitor_kit/group_query.py (1940b), src/tg_monitor_kit/join/__init__.py (96b), src/tg_monitor_kit/join/runtime.py (6931b), src/tg_monitor_kit/lockfile.py (876b), src/tg_monitor_kit/login.py (1049b), src/tg_monitor_kit/monitoring/__init__.py (94b), src/tg_monitor_kit/monitoring/runtime.py (12436b), src/tg_monitor_kit/search/__init__.py (102b), src/tg_monitor_kit/search/runtime.py (15145b), src/tg_monitor_kit/tools/__init__.py (34b), src/tg_monitor_kit/tools/account_info.py (597b), src/tg_monitor_kit/tools/get_groups.py (833b), src/tg_monitor_kit/tools/get_history.py (1340b), src/tg_monitor_kit/tools/get_members.py (1593b), _meta.json (139b)","readmeExcerpt":"Skill: Telegram Tools Suite Owner: testman2025 Summary: Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。 运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。 Tags: latest:1.3.3 Version history: v1.3.3 | 2026-04-22T02:18:09.841Z | user 安全优化：1. 为session_runtime.py临时会话复制逻辑增加明确注释，说明仅用于进程隔离防锁死，任务结束自动删除无留存；2. clawhub.yaml新增设计说明，明确告知无第三方数据传输逻辑，消除扫描误判；3. 所有安全设计完全透明可追溯 v1.3.2 | 2026-04-22T02:02:30.045Z | user 元数据完全对齐：1. 补全TG_ENABLE_PERSISTENT_","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"cd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor"},{"language":"bash","snippet":"cd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor"},{"language":"bash","snippet":"cd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor"},{"language":"bash","snippet":"cd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor"},{"language":"bash","snippet":"cd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor"},{"language":"bash","snippet":"cd \"/path/to/Telegram-Tools-Suite\"\npython3 -m tg_monitor_kit groups\ntg-monitor monitor\n# Or if not installed as editable: PYTHONPATH=src python3 -m tg_monitor_kit monitor\n# 或未安装 editable 时：PYTHONPATH=src python3 -m tg_monitor_kit monitor"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: Telegram Tools Suite\ndescription: >\n  Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。\n  运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。\n\nrequiredEnv:\n  - name: TELEGRAM_API_ID\n    description: Telegram API ID（来自 https://my.telegram.org）\n    required: true\n  - name: TELEGRAM_API_HASH\n    description: Telegram API Hash（高敏感）\n    required: true\n  - name: TELEGRAM_PHONE\n    description: Telegram 账号手机号（国际格式）\n    required: true\n\noptionalEnv:\n  - name: ENABLE_HIGH_RISK_OPERATIONS\n    description: 高风险总开关（join/send-schedule 需设为 true 才可运行）\n    required: false\n    default: \"false\"\n  - name: TELEGRAM_SESSION_NAME\n    description: 会话文件名（默认 tg_monitor_session）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_HOST\n    description: Telegram 代理地址（默认 127.0.0.1）\n    required: false\n  - name: TELEGRAM_PROXY_HTTP_PORT\n    description: Telegram 代理端口（默认 1087）\n    required: false\n\n  - name: TG_CODE\n    description: 登录短信验证码（auth 后）\n    required: false\n  - name: TG_PHONE_CODE_HASH\n    description: 登录验证码哈希（auth 输出）\n    required: false\n\n  - name: TG_PROJECT_ROOT\n    description: 项目根目录覆盖（用于定位配置文件）\n    required: false\n  - name: TG_MONITOR_WEB_OUTPUT_DIR\n    description: 网页脚本输出目录\n    required: false\n\n  - name: TG_TARGET_GROUPS_FILE\n    description: 监控群白名单文件路径\n    required: false\n  - name: TG_KEYWORDS_FILE\n    description: 监控关键词文件路径（默认 config/keywords.txt）\n    required: false\n  - name: TG_MONITOR_REGEX_RULES_FILE\n    description: 监控正则规则文件路径\n    required: false\n\n  - name: TG_GROUP_SEARCH_KEYWORDS_FILE\n    description: 群搜索关键词文件路径\n    required: false\n  - name: TG_GROUP_SEARCH_SETTINGS_FILE\n    description: 群搜索配置文件路径\n    required: false\n\n  - name: TG_JOIN_LIST_FILE\n    description: 批量加群目标文件路径\n    required: false\n  - name: TG_ENABLE_PERSISTENT_JOIN\n    description: 是否开启 join 长驻模式（默认关闭；需 true）\n    required: false\n  - name: TG_JOIN_DELAY_SEC\n    description: 加群间隔秒数（最小 1800）\n    required: false\n  - name: TG_MAX_JOINS_PER_RUN\n    description: 单轮最多加群数量（最大 20）\n    required: false\n\n---\n\n# Telegram Tools Suite\n\n> ⚠️ 【重要安全&运行提示 安装前必读】\n> 1. 敏感文件生成：技能运行时会在`userdata/`目录生成`*.session`会话文件（包含Telegram登录认证状态），并使用`.env`配置文件，均为高敏感信息，已默认加入`.gitignore`/`.clawignore`禁止提交到代码仓库/发布，请勿手动分享这些文件。\n> 2. 持久运行说明：`monitor`（群监控）、`search`（群搜索）、`join`（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。\n> 3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。\n> 4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。\n> 4. 默认风险保护：`join` 与 `send-schedule` 均需先设置 `ENABLE_HIGH_RISK_OPERATIONS=true` 才可运行；其中 `join` 长驻模式还需额外设置 `TG_ENABLE_PERSISTENT_JOIN=true`。定时群发由 `send-schedule` 子命令执行，并按 `config/scheduled_tasks.json` 的限制进行校验。\n\n## Instructions\n\n### 🔹 前置说明\n本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`、绑定手机号（国际格式）。\n\n### 🔹 安装后引导&首次运行流程（按顺序执行）\n1. **安装依赖**：执行 `pip install -e .`\n2. **获取API凭证**：打开 <https://my.telegram.org>，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得`api_id`和`api_h"},{"path":"README.md","content":"# Telegram Tools Suite | Telegram工具集\n> Telegram (Telethon) keyword monitoring and group search toolkit. This repository provides the **Python package `tg_monitor_kit`**, command line **`tg-monitor` / `python -m tg_monitor_kit`**, and **OpenClaw Skill**. All time and scheduled tasks are based on **Beijing Time**.\n>\n> Telegram（Telethon）关键词监控与群搜索工具包。本仓库提供 **Python 包 `tg_monitor_kit`**、命令行 **`tg-monitor` / `python -m tg_monitor_kit`**，以及 **OpenClaw Skill**。时间与定时任务均以**北京时间**为准。\n\nQuick Start | 快速入口: Install with `pip install -e .`; CLI help `python -m tg_monitor_kit --help` or `tg-monitor --help`.\n快速入口：安装 `pip install -e .`；CLI 帮助 `python -m tg_monitor_kit --help` 或 `tg-monitor --help`。\n\n## Installation & Configuration | 安装与配置\n1. Install dependencies (choose one): | 安装依赖（任选其一）：\n   - `pip install -e .` (Recommended, execute in project root directory) | `pip install -e .`（推荐，在项目根目录执行）\n   - Or `pip install -r requirements.txt` then add `src` to `PYTHONPATH` (Not recommended) | 或 `pip install -r requirements.txt` 后把 `src` 加入 `PYTHONPATH`（不推荐）\n2. Copy `.env.example` to `.env`, fill in `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`; fill in `TELEGRAM_PHONE` as needed (for login). | 复制 `.env.example` 为 `.env`，填写 `TELEGRAM_API_ID`、`TELEGRAM_API_HASH`；按需填写 `TELEGRAM_PHONE`（登录用）。\n3. Session file: by default generated under `userdata/` in project root (name determined by `TELEGRAM_SESSION_NAME`). **Do not** delete the in-use `.session` file. | 会话文件：默认在项目根目录 `userdata/` 下生成（名称由 `TELEGRAM_SESSION_NAME` 决定）。**勿**删除正在使用的 `.session` 文件。\n\n## First Run (Step by Step) | 首次运行步骤（必看）\n1. Install | 安装：\n   - `pip install -e .`\n2. Get API credentials | 获取 API 凭据：\n   - 打开 <https://my.telegram.org>\n   - 使用手机号登录\n   - 进入 `API development tools`\n   - 创建应用后拿到 `api_id` 与 `api_hash`\n3. Configure `.env` | 配置：\n   - 必填：`TELEGRAM_API_ID`、`TELEGRAM_API_HASH`\n   - 建议填：`TELEGRAM_PHONE`（如 `+8613xxxxxxxxx`）\n4. Request code hash | 请求验证码 hash：\n   - `python3 -m tg_monitor_kit auth`\n   - 成功时输出：`SENT_CODE_SUCCESS:<phone_code_hash>`\n5. Wait user code and login | 等待用户提供验证码并登录：\n   - 设置 `TG_CODE`（短信验证码）\n   - 设置 `TG_PHONE_CODE_HASH`（上一步输出）\n   - 运行 `python3 -m tg_monitor_kit login`\n   - 成功时输出：`LOGIN_SUCCESS`\n6. Verify account | 验证账号：\n   - `python3 -m tg_monitor_kit groups`\n7. Start business command | 启动业务命令：\n   - 监控：`python3 -m tg_monitor_kit monitor`\n   - 搜索：`python3 -m tg_monitor_kit search`\n  - 加群（单轮）：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once`\n  - 定时群发：`ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule`\n\n## Command List (Recommended) | 命令一览（推荐）\nExecute in the project root directory (if `pip install -e .` is installed, you can directly use `tg-monitor`; otherwise use `PYTHONPATH=src python3 -m tg_monitor_kit`): | 在项目根目录执行（已 `pip install -e .` 时可直接用 `tg-monitor`；否则使用 `PYTHONPATH=src python3 -m tg_monitor_kit`）：\n\n| Subcommand | Description | 说明 |\n|--------|--------|------|\n| `monitor` | Whitelist group keyword monitoring, hit notification, 18:00 daily Excel sum"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn71svn18t9cb73emms0vf78s984tb7p\",\n  \"slug\": \"telegram-tools-suite\",\n  \"version\": \"1.3.3\",\n  \"publishedAt\": 1776824289841\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n## 1.0.0 - 2026-04-15\n\n- 清理发布包中的隐私与运行时文件（`.env`、`.session`、日志、锁文件、本地虚拟环境、测试脚本）。\n- 统一默认会话名为 `tg_monitor_session`，移除个人路径示例。\n- 重写根目录 `SKILL.md` 为可发布格式（frontmatter + instructions/rules/examples）。\n- 新增 `clawhub.json`，补充 ClawHub 发布元数据。\n- 更新 `.clawignore`，保留 `.env.example` 并强化敏感文件排除策略。"},{"path":"skill-card.md","content":"## Description:\n\nTelegram Tools Suite provides Telegram account automation for group monitoring, group search, batch group joining, scheduled messages, and account queries.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[testman2025](https://clawhub.ai/user/testman2025)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to configure and run Telegram automation workflows for monitoring selected groups, searching groups by keyword, querying account or group data, joining groups from a list, and sending scheduled messages.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Reusable Telegram session credentials can expose the connected account if the workspace is shared, archived, or published.\n\nMitigation: Use a test account, keep the workspace private, exclude userdata and .env files from archives, and review session-file permissions after login.\n\nRisk: Scheduled sending and bulk group joining can risk account enforcement or misuse.\n\nMitigation: Keep high-risk operations disabled unless needed, explicitly enable them only for reviewed tasks, and verify target lists, message content, and frequency before execution.\n\n## Reference(s):\n\n- [Telegram API development tools](https://my.telegram.org)\n- [ClawHub skill page](https://clawhub.ai/testman2025/skills/telegram-tools-suite)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell commands and configuration guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce operational guidance for long-running Telegram commands and local configuration files.]\n\n## Skill Version(s):\n\n1.3.3 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1284,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:12:03.215Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:12:03.215Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T11:56:37.652Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}