任务编排

任务模型

一个 TG-SignPulse 任务由这些部分组成：

• 任务名称
• 绑定账号
• 执行模式
• 时间配置
• 目标聊天列表
• 每个聊天下的动作序列

一个任务可以绑定单个账号，也可以绑定多个账号作为共享任务。

面板与 API 请使用 sign-tasks（/api/sign-tasks）。旧版 ORM /api/tasks 默认只读，仅作兼容。

运行状态与可观测

手动/定时触发后，运行状态保存在服务端内存，面板可实时查看：

字段	说明
state	粗粒度：running / finished / timeout / cancelled 等
phase	细粒度：starting → checking_account → waiting_lock → cooldown → running → finalizing
failure_category	失败分类（会话失效、超时、Flood 等）

相关 API：

• POST /api/sign-tasks/{name}/run/start — 异步启动
• GET /api/sign-tasks/{name}/run/status — 查询状态
• POST /api/sign-tasks/{name}/run/cancel — 取消进行中的运行
• GET /api/sign-tasks/runs/active — 当前全部进行中的 run

任务表单中的 重试次数 写入 config 后优先于系统设置「流程重试」；全局缺省仅在任务 config 未包含 retry_count 键时生效。

多账号共享任务

共享任务用于“一套流程，多号复用”。

典型场景：

• 多个号都要去同一个机器人签到
• 多个号执行完全相同的打卡流程
• 需要统一修改步骤，不想复制 N 份任务

你只需要维护一份任务配置，然后通过 account_names 绑定多个账号即可。

执行模式

1. fixed

固定时间执行，使用 sign_at 指定 Cron 时间。

适合：

• 每天固定时刻执行
• 对时间要求非常明确的打卡任务

2. range

在指定时间段内随机选择执行时刻，使用：

• range_start
• range_end

适合：

• 避免所有账号同时执行
• 降低机械化规律

3. listen

监听模式不会创建普通定时调度，而是等目标聊天出现关键词后再触发动作。

适合：

• 监听红包、通知、口令、抽奖、机器人回执
• 先命中消息，再执行后续 AI 或按钮动作

聊天配置

每个目标聊天支持：

• chat_id
• name
• message_thread_id
• action_interval
• delete_after
• actions

message_thread_id

如果目标是 Telegram 超级群话题，可以指定话题 ID。留空表示整聊有效。

action_interval

控制同一个聊天中相邻动作之间的等待秒数。

delete_after

控制发送出来的消息在多少秒后删除，适合一些不希望长期留痕的场景。

动作类型

ID	动作	说明
1	发送文本	发送普通文本，例如 /start、口令、验证码
2	发送骰子	发送骰子或类似随机表情动作
3	点击文字按钮	根据按钮文本匹配并点击
4	根据图片选择选项	AI 识图后决定该点哪个按钮
5	回复计算题	AI 计算后发送答案文本
6	AI 识图后回复文本	OCR 或识图后把结果发出
7	AI 计算后点击按钮	先算出结果，再去匹配按钮文本并点击
8	关键词监听	监听模式专用动作
9	触发 Bot 命令	向指定 Bot 发送命令；支持解析消息内多条 t.me/bot?start= 深链并批量触发（默认最多 5 条、间隔 2s；调高 max_batch 有风控/封禁风险）。详见 关键词监听

AI 提示词

动作 4、5、6、7 支持单独配置 ai_prompt。

规则：

• 留空时使用系统默认提示词
• 填写后只覆盖当前这一个 AI 动作
• 关键词监听里的后续动作同样支持自定义 ai_prompt

第一步动作建议

常规签到任务第一步通常应为：

• 发送文本
• 或 发送骰子

最常见的是先发 /start，然后再继续点“签到”“领取”“确认”等按钮。

监听模式下的动作

监听模式一般包含两段：

1. 关键词规则
2. 命中后的处理方式

命中后的处理方式可以是：

• 只推送通知
• 转发消息
• Bark 推送
• 自定义 URL 推送
• 继续执行动作序列

任务日志与历史

系统会记录：

• 最近一次执行时间
• 成功/失败状态
• 流程日志
• 最后目标消息
• 最后实际执行的账号

建议在调试任务时优先看流程日志，而不是只看“成功/失败”。

任务重试

每个任务可独立配置重试次数，控制执行失败后的重试行为。

配置方式： 创建或编辑任务时，在 重试次数 字段输入数值。

值	行为
0	不重试，失败即停止
1	失败后重试 1 次
3（默认）	失败后最多重试 3 次
99	最大重试次数

重试策略：

• 重试时从上次失败的步骤继续，而非从头开始
• 支持退避步数（SIGN_TASK_RETRY_BACKOFF_STEPS，默认 0），即回退若干步后重试（0 = 从失败步骤原地重试）
• 重试次数存储在任务配置 JSON 中，支持导入导出

API 字段： retry_count（CreateSignTaskRequest / UpdateSignTaskRequest），范围 0–99。

设计建议

• 多步骤机器人流程尽量拆成清晰顺序
• 带验证码的机器人，把 AI 动作紧跟在按钮动作之后
• 范围执行适合多号，固定执行适合单号
• 监听任务与定时任务分开管理，便于排障