tg-signer 0.9.0b1

Automated Telegram tasks (check-ins, sending messages, keyboard clicks, AI replies, etc.); monitoring, forwarding, and auto-replying to private, group, and channel messages.

Telegram每日自动签到/个人、群组、频道消息监控与自动回复

English

功能

• 每日定时和随机误差时间签到

• 根据配置的文本点击键盘

• 调用AI进行图片识别并点击键盘

• 个人、群组、频道消息监控、转发与自动回复

• 根据配置执行动作流

• 自动化规则引擎（message/timer/startup 触发 + handler 链）

  ...

安装

需要Python3.10及以上

pip install -U tg-signer

或者为了提升程序速度：

pip install "tg-signer[speedup]"

启用 YAML 配置支持：

pip install "tg-signer[yaml]"

WebUI

tg-signer附带了一个WebUI，安装命令:

pip install "tg-signer[gui]"

Docker

GitHub Container Registry

在 GitHub Container Registry 提供了两种预构建镜像：ghcr.io/amchii/tg-signer:<tag>（CLI）和 ghcr.io/amchii/tg-signer:<tag>-webui（CLI + WebUI）。

本地

如果需要自行构建镜像，本地 build 方式仍然保留，见 docker 目录下的 Dockerfile 和 README 。

使用方法

Usage: tg-signer [OPTIONS] COMMAND [ARGS]...

  使用<子命令> --help查看使用说明

子命令别名:
  run_once -> run-once
  send_text -> send-text

Options:
  -l, --log-level [debug|info|warn|error]
                                  日志等级, `debug`, `info`, `warn`, `error`
                                  [default: info]
  --log-file PATH                 日志文件路径, 可以是相对路径  [default: logs/tg-
                                  signer.log]
  --log-dir PATH                  日志文件目录, 可以是相对路径  [default: logs]
  -p, --proxy TEXT                代理地址, 例如: socks5://127.0.0.1:1080,
                                  会覆盖环境变量`TG_PROXY`的值  [env var: TG_PROXY]
  --session_dir PATH              存储TG Sessions的目录, 可以是相对路径  [default: .]
  -a, --account TEXT              自定义账号名称，对应session文件名为<account>.session  [env
                                  var: TG_ACCOUNT; default: my_account]
  -w, --workdir PATH              tg-signer工作目录，用于存储配置和签到记录等  [default:
                                  .signer]
  --session-string TEXT           Telegram Session String,
                                  会覆盖环境变量`TG_SESSION_STRING`的值  [env var:
                                  TG_SESSION_STRING]
  --in-memory                     是否将session存储在内存中，默认为False，存储在文件
  --help                          Show this message and exit.

Commands:
  export                  导出配置，默认为输出到终端。
  import                  导入配置，默认为从终端读取。
  list                    列出已有配置
  list-members            查询聊天（群或频道）的成员, 频道需要管理员权限
  list-sign-records       列出最近N条签到记录
  list-topics             列出群组话题ID（message_thread_id）
  list-schedule-messages  显示已配置的定时消息
  llm-config              配置大模型API
  login                   登录账号（用于获取session）
  migrate-sign-records    将签到记录从 JSON 迁移到 SQLite（默认保留原...
  logout                  登出账号并删除session文件
  automation              配置和运行自动化规则（推荐，覆盖monitor能力）
  monitor                 配置和运行监控
  multi-run               使用一套配置同时运行多个账号
  reconfig                重新配置
  run                     根据任务配置运行签到
  run-once                运行一次签到任务，即使该签到任务今日已执行过
  schedule-messages       批量配置Telegram自带的定时发送消息功能
  send-dice               发送一次DICE消息, 请确保当前会话已经"见过"该`chat_id`。...
  send-text               发送一次文本消息, 请确保当前会话已经"见过"该`chat_id`
  version                 Show version
  webgui                  启动一个WebGUI（需要通过`pip install "tg-signer[gui]"`安装相关依赖）

例如:

tg-signer run
tg-signer run my_sign  # 不询问，直接运行'my_sign'任务
tg-signer run-once my_sign  # 直接运行一次'my_sign'任务
tg-signer list-sign-records linuxdo -n 5  # 查看任务 linuxdo 最近 5 条签到记录
tg-signer migrate-sign-records  # 将.signer/signs 下的签到记录迁移到 SQLite
tg-signer send-text 8671234001 /test  # 向chat_id为'8671234001'的聊天发送'/test'文本
tg-signer send-text @neo /test  # 向username为'@neo'的聊天发送'/test'文本
tg-signer send-text --message-thread-id 1 -- -1003763902761 checkin  # 发送到群组话题(message_thread_id=1)
tg-signer send-text -- -10006758812 浇水  # 对于负数需要使用POSIX风格，在短横线'-'前方加上'--'
tg-signer send-text --delete-after 1 8671234001 /test  # 向chat_id为'8671234001'的聊天发送'/test'文本, 并在1秒后删除发送的消息
tg-signer list-members --chat_id -1001680975844 --admin  # 列出频道的管理员
tg-signer list-topics --chat_id -1003763902761 --limit 50  # 列出群组话题及message_thread_id
tg-signer schedule-messages --crontab '0 0 * * *' --next-times 10 -- -1001680975844 你好  # 在未来10天的每天0点向'-1001680975844'发送消息
tg-signer schedule-messages --crontab '0 0 * * *' --next-times 3 --message-thread-id 1 -- -1003763902761 你好  # 配置群组话题的定时消息
tg-signer automation init my_auto  # 初始化自动化模板
tg-signer automation run my_auto  # 运行自动化任务
tg-signer monitor run  # 配置个人、群组、频道消息监控与自动回复
tg-signer multi-run -a account_a -a account_b same_task  # 使用'same_task'的配置同时运行'account_a'和'account_b'两个账号
tg-signer webgui --auth-code averycomplexcode  # 启动一个WebGUI

自动化规则（automation）

推荐使用 tg-signer automation 统一管理自动化规则（覆盖 monitor 能力）。

tg-signer automation init my_auto
# 编辑 .signer/automations/my_auto/config.json
tg-signer automation run my_auto

更多详细使用说明与示例见：docs/automation_usage.md

配置代理（如有需要）

tg-signer不读取系统代理，可以使用环境变量 TG_PROXY或命令参数--proxy进行配置

例如：

export TG_PROXY=socks5://127.0.0.1:7890

登录

tg-signer login

根据提示输入手机号码和验证码进行登录并获取最近的聊天列表，确保你想要签到的聊天在列表内。 签到任务里的chat_id同时支持整数ID和以@开头的username，例如@neo。 对于论坛群组，登录输出中会额外打印每个话题的 message_thread_id，可直接用于 --message-thread-id。

时区

调度相关命令（如 run 和 schedule-messages）会按以下顺序解析时区：

1. 环境变量 TZ
2. Python 识别到的本地时区
3. 默认回退到 Asia/Shanghai

如果你需要按特定时区计算下次执行时间，直接在运行前设置 TZ 即可。

获取群组话题 ID

tg-signer list-topics --chat_id -1003763902761

会输出该论坛群组可见话题的 message_thread_id、标题及状态，便于配置签到到指定话题。

发送一次消息

tg-signer send-text 8671234001 hello  # 向chat_id为'8671234001'的聊天发送'hello'文本
tg-signer send-text @neo hello  # 向username为'@neo'的聊天发送'hello'文本

运行签到任务

tg-signer run

或预先执行任务名：

tg-signer run linuxdo

根据提示进行配置即可。

示例：

开始配置任务<linuxdo>
第1个签到
一. Chat ID（登录时最近对话输出中的ID或@username）: 7661096533
二. Chat名称（可选）: jerry bot
三. 是否发送到话题（message_thread_id）？(y/N)：y
四. message_thread_id: 1
五. 开始配置<动作>，请按照实际签到顺序配置。
  1: 发送普通文本
  2: 发送Dice类型的emoji
  3: 根据文本点击键盘
  4: 根据图片选择选项
  5: 回复计算题

第1个动作:
1. 输入对应的数字选择动作: 1
2. 输入要发送的文本: checkin
3. 是否继续添加动作？(y/N)：y
第2个动作:
1. 输入对应的数字选择动作: 3
2. 键盘中需要点击的按钮文本: 签到
3. 是否继续添加动作？(y/N)：y
第3个动作:
1. 输入对应的数字选择动作: 4
图片识别将使用大模型回答，请确保大模型支持图片识别。
2. 是否继续添加动作？(y/N)：y
第4个动作:
1. 输入对应的数字选择动作: 5
计算题将使用大模型回答。
2. 是否继续添加动作？(y/N)：y
第5个动作:
1. 输入对应的数字选择动作: 2
2. 输入要发送的骰子（如 🎲, 🎯）: 🎲
3. 是否继续添加动作？(y/N)：n
在运行前请通过环境变量正确设置`OPENAI_API_KEY`, `OPENAI_BASE_URL`。默认模型为"gpt-4o", 可通过环境变量`OPENAI_MODEL`更改。
六. 等待N秒后删除签到消息（发送消息后等待进行删除, '0'表示立即删除, 不需要删除直接回车）, N: 10
╔════════════════════════════════════════════════╗
║ Chat ID: 7661096533                            ║
║ Name: jerry bot                                ║
║ Message Thread ID: 1                           ║
║ Delete After: 10                               ║
╟────────────────────────────────────────────────╢
║ Actions Flow:                                  ║
║ 1. [发送普通文本] Text: checkin                ║
║ 2. [根据文本点击键盘] Click: 签到              ║
║ 3. [根据图片选择选项]                          ║
║ 4. [回复计算题]                                ║
║ 5. [发送Dice类型的emoji] Dice: 🎲              ║
╚════════════════════════════════════════════════╝
第1个签到配置成功

继续配置签到？(y/N)：n
每日签到时间（time或crontab表达式，如'06:00:00'或'0 6 * * *'）:
签到时间误差随机秒数（默认为0）: 300

配置与运行监控

说明：monitor 为 legacy 功能，推荐使用 tg-signer automation 统一管理自动化规则。

tg-signer monitor run my_monitor

根据提示进行配置。

示例：

开始配置任务<my_monitor>
聊天chat id和用户user id均同时支持整数id和字符串username, username必须以@开头，如@neo

配置第1个监控项
1. Chat ID（登录时最近对话输出中的ID）: -4573702599
2. 匹配规则('exact', 'contains', 'regex', 'all'): contains
3. 规则值（不可为空）: kfc
4. 只匹配来自特定用户ID的消息（多个用逗号隔开, 匹配所有用户直接回车）: @neo
5. 默认发送文本: V Me 50
6. 从消息中提取发送文本的正则表达式:
7. 等待N秒后删除签到消息（发送消息后等待进行删除, '0'表示立即删除, 不需要删除直接回车）, N:
继续配置？(y/N)：y

配置第2个监控项
1. Chat ID（登录时最近对话输出中的ID）: -4573702599
2. 匹配规则('exact', 'contains', 'regex'): regex
3. 规则值（不可为空）: 参与关键词：「.*?」
4. 只匹配来自特定用户ID的消息（多个用逗号隔开, 匹配所有用户直接回车）: 61244351
5. 默认发送文本:
6. 从消息中提取发送文本的正则表达式: 参与关键词：「(?P<keyword>(.*?))」\n
7. 发送文本模板（可用{extracted}/{group1}/命名分组；不需要则直接回车）: 我要参与 {keyword}
8. 等待N秒后删除签到消息（发送消息后等待进行删除, '0'表示立即删除, 不需要删除直接回车）, N: 5
继续配置？(y/N)：y

配置第3个监控项
1. Chat ID（登录时最近对话输出中的ID）: -4573702599
2. 匹配规则(exact, contains, regex, all): all
3. 只匹配来自特定用户ID的消息（多个用逗号隔开, 匹配所有用户直接回车）:
4. 总是忽略自己发送的消息（y/N）: y
5. 默认发送文本（不需要则回车）:
6. 是否使用AI进行回复(y/N): n
7. 从消息中提取发送文本的正则表达式（不需要则直接回车）:
8. 是否通过Server酱推送消息(y/N): n
9. 是否需要转发到外部（UDP, Http）(y/N): y
10. 是否需要转发到UDP(y/N): y
11. 请输入UDP服务器地址和端口（形如`127.0.0.1:1234`）: 127.0.0.1:9999
12. 是否需要转发到Http(y/N): y
13. 请输入Http地址（形如`http://127.0.0.1:1234`）: http://127.0.0.1:8000/tg/user1/messages
继续配置？(y/N)：n

示例解释：

1. 聊天chat id和用户user id均同时支持整数id和字符串username, username必须以@开头 如"neo"输入"@neo"，注意* username* 可能不存在，示例中chat id为-4573702599表示规则只对-4573702599对应的聊天有效。

2. 匹配规则，目前皆忽略大小写：

   1. exact 为精确匹配，消息必须精确等于该值。

   2. contains 为包含匹配，如contains="kfc"，那么只要收到的消息中包含"kfc"如"I like MacDonalds rather than KfC" 即匹配到（注意忽略了大小写）

   3. regex 为正则，参考 Python正则表达式 ，在消息中有**搜索到该正则即匹配 **，示例中的 "参与关键词：「.*?」" 可以匹配消息： "新的抽奖已经创建... 参与关键词：「我要抽奖」

      建议先私聊机器人"

   4. 可以只匹配来自特定用户的消息，如群管理员而不是随便什么人发布的抽奖消息

   5. 可以设置默认发布文本， 即只要匹配到消息即默认发送该文本

   6. 提取发布文本的正则，例如 "参与关键词：「(?P.*?)」\n" ，注意用括号(...) 捕获要提取的文本， 可以捕获第3点示例消息的关键词"我要抽奖"并自动发送。若配置了发送文本模板，可用 {extracted} 或 {group1} 引用第一个捕获组，也可用 {keyword} 引用命名分组，例如模板 我要参与 {keyword} 会发送 我要参与 我要抽奖。

3. 消息Message结构参考:

{
    "_": "Message",
    "id": 2950,
    "from_user": {
        "_": "User",
        "id": 123456789,
        "is_self": false,
        "is_contact": false,
        "is_mutual_contact": false,
        "is_deleted": false,
        "is_bot": false,
        "is_verified": false,
        "is_restricted": false,
        "is_scam": false,
        "is_fake": false,
        "is_support": false,
        "is_premium": false,
        "is_contact_require_premium": false,
        "is_close_friend": false,
        "is_stories_hidden": false,
        "is_stories_unavailable": true,
        "is_business_bot": false,
        "first_name": "linux",
        "status": "UserStatus.ONLINE",
        "next_offline_date": "2025-05-30 11:52:40",
        "username": "linuxdo",
        "dc_id": 5,
        "phone_number": "*********",
        "photo": {
            "_": "ChatPhoto",
            "small_file_id": "AQADBQADqqcxG6hqrTMAEAIAA6hqrTMABLkwVDcqzBjAAAQeBA",
            "small_photo_unique_id": "AgADqqcxG6hqrTM",
            "big_file_id": "AQADBQADqqcxG6hqrTMAEAMAA6hqrTMABLkwVDcqzBjAAAQeBA",
            "big_photo_unique_id": "AgADqqcxG6hqrTM",
            "has_animation": false,
            "is_personal": false
        },
        "added_to_attachment_menu": false,
        "inline_need_location": false,
        "can_be_edited": false,
        "can_be_added_to_attachment_menu": false,
        "can_join_groups": false,
        "can_read_all_group_messages": false,
        "has_main_web_app": false
    },
    "date": "2025-05-30 11:47:46",
    "chat": {
        "_": "Chat",
        "id": -52737131599,
        "type": "ChatType.GROUP",
        "is_creator": true,
        "is_deactivated": false,
        "is_call_active": false,
        "is_call_not_empty": false,
        "title": "测试组",
        "has_protected_content": false,
        "members_count": 4,
        "permissions": {
            "_": "ChatPermissions",
            "can_send_messages": true,
            "can_send_media_messages": true,
            "can_send_other_messages": true,
            "can_send_polls": true,
            "can_add_web_page_previews": true,
            "can_change_info": true,
            "can_invite_users": true,
            "can_pin_messages": true,
            "can_manage_topics": true
        }
    },
    "from_offline": false,
    "show_caption_above_media": false,
    "mentioned": false,
    "scheduled": false,
    "from_scheduled": false,
    "edit_hidden": false,
    "has_protected_content": false,
    "text": "test, 测试",
    "video_processing_pending": false,
    "outgoing": false
}

示例运行输出：

[INFO] [tg-signer] 2024-10-25 12:29:06,516 core.py 458 开始监控...
[INFO] [tg-signer] 2024-10-25 12:29:37,034 core.py 439 匹配到监控项：MatchConfig(chat_id=-4573702599, rule=contains, rule_value=kfc), default_send_text=V me 50, send_text_search_regex=None
[INFO] [tg-signer] 2024-10-25 12:29:37,035 core.py 442 发送文本：V me 50
[INFO] [tg-signer] 2024-10-25 12:30:02,726 core.py 439 匹配到监控项：MatchConfig(chat_id=-4573702599, rule=regex, rule_value=参与关键词：「.*?」), default_send_text=None, send_text_search_regex=参与关键词：「(?P<keyword>(.*?))」\n
[INFO] [tg-signer] 2024-10-25 12:30:02,727 core.py 442 发送文本：我要抽奖
[INFO] [tg-signer] 2024-10-25 12:30:03,001 core.py 226 Message「我要抽奖」 to -4573702599 will be deleted after 5 seconds.
[INFO] [tg-signer] 2024-10-25 12:30:03,001 core.py 229 Waiting...
[INFO] [tg-signer] 2024-10-25 12:30:08,260 core.py 232 Message「我要抽奖」 to -4573702599 deleted!

版本变动日志

0.9.0b1

• 监控配置支持 send_text_template，可将正则捕获结果或消息文本渲染到自动回复内容中
• 修复图片消息中的计算题无法识别 caption 的问题
• 回复计算题 动作在存在 InlineKeyboard 选项时，会将按钮选项传给大模型并点击匹配按钮
• 根据图片选择选项 动作会将消息文本或 caption 作为图片识别问题，并校验大模型返回的选项序号

0.8.6

• 支持 Telegram 论坛群组话题 message_thread_id
• 登录时可发现群组话题，新增 list-topics 用于查询话题 ID
• send-text、send-dice、schedule-messages、签到配置与 WebUI 支持发送到指定话题
• 签到记录迁移到 SQLite，新增 list-sign-records 与 migrate-sign-records
• 兼容读取旧版 sign_record.json，运行任务时可自动导入历史记录
• 发布官方 GHCR 镜像：ghcr.io/amchii/tg-signer:<tag> 与 ghcr.io/amchii/tg-signer:<tag>-webui
• 改进论坛群组、频道私信等场景下的话题发现与消息发送兼容性

0.8.5

• "kurigram>=2.2.19,<2.3.0"
• 单账户多任务时进行并发请求限流

0.8.4

• 新增 WebGUI
• 新增--log-dir选项，更改日志默认目录为logs，warning和error分为单独文件

0.8.2

• 支持持久化OpenAI API和模型配置
• Python最小版本要求：3.10
• 支持处理编辑后的消息（如键盘）

0.8.0

• 支持单个账号同一进程内同时运行多个任务

0.7.6

• fix: 监控多个聊天时消息转发至每个聊天 (#55)

0.7.5

• 捕获并记录执行任务期间的所有RPC错误
• bump kurigram version to 2.2.7

0.7.4

• 执行多个action时，支持固定时间间隔
• 通过crontab配置定时执行时不再限制每日执行一次

0.7.2

• 支持将消息转发至外部端点，通过：
  • UDP
  • HTTP
• 将kurirogram替换为kurigram

0.7.0

• 支持每个聊天会话按序执行多个动作，动作类型：
  • 发送文本
  • 发送骰子
  • 按文本点击键盘
  • 通过图片选择选项
  • 通过计算题回复

0.6.6

• 增加对发送DICE消息的支持

0.6.5

• 修复使用同一套配置运行多个账号时签到记录共用的问题

0.6.4

• 增加对简单计算题的支持
• 改进签到配置和消息处理

0.6.3

• 兼容kurigram 2.1.38版本的破坏性变更

Remove coroutine param from run method a7afa32

0.6.2

• 忽略签到时发送消息失败的聊天

0.6.1

• 支持点击按钮文本后继续进行图片识别

0.6.0

• Signer支持通过crontab定时
• Monitor匹配规则添加all支持所有消息
• Monitor支持匹配到消息后通过server酱推送
• Signer新增multi-run用于使用一套配置同时运行多个账号

0.5.2

• Monitor支持配置AI进行消息回复
• 增加批量配置「Telegram自带的定时发送消息功能」的功能

0.5.1

• 添加import和export命令用于导入导出配置

0.5.0

• 根据配置的文本点击键盘
• 调用AI识别图片点击键盘

配置与数据存储位置

数据和配置默认保存在 .signer 目录中。然后运行 tree .signer，你将看到：

.signer
├── .openai_config.json  # 可选，大模型配置
├── data.sqlite3  # SQLite 签到记录库
├── monitors  # 监控
│   ├── my_monitor  # 监控任务名
│       └── config.json  # 监控配置
├── users
│   └── 123456789
│       ├── latest_chats.json  # 获取的最近对话
│       └── me.json  # 个人信息
├── automations  # 自动化规则
│   ├── my_auto  # 自动化任务名
│       ├── config.json  # 自动化配置
│       └── state.json  # 运行状态
└── signs  # 签到任务
    └── linuxdo  # 签到任务名
        ├── config.json  # 签到配置
        ├── 123456789
        │   └── sign_record.json  # 旧版 JSON 签到记录（兼容迁移）
        └── sign_record.json  # 更旧版 JSON 路径（兼容迁移）

迁移到 SQLite 后，新的签到记录只写入 data.sqlite3，但仍兼容读取旧 sign_record.json。当运行任务时如果检测到旧 JSON，程序会输出提示并尝试将该任务 的历史记录自动导入 SQLite。