任务编排

任务模型

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

• 任务名称
• 绑定账号
• 执行模式
• 时间配置
• 目标聊天列表
• 每个聊天下的动作序列（线性 actions 或 DAG 工作流 steps + initial_step_id）

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

面板与 API 统一使用 sign-tasks（/api/sign-tasks）。旧版 ORM /api/tasks 已完全移除，详见 FAQ。

运行状态与可视

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

字段	说明
state	粗粒度运行状态：running / finished / timeout / cancelled 等
phase	细粒度生命周期阶段：starting → checking_account → waiting_lock → cooldown → running → finalizing
failure_category	失败原因分类标签（见下表）

失败分类一览 (failure_category)

系统根据错误特征与消息上下文自动归纳失败原因，并在面板历史与 Telegram Bot 通知中展示标准中文短标签：

内部标识	中文短标签	判定场景与说明
session_invalid	会话失效	账号授权被撤销、Session 过期或需要重新登录
flood_wait	频率限制	触发 Telegram 官方 FloodWait 限制或慢速模式
ai_timeout	AI 超时	AI 视觉模型调用超时或图片处理超时
ai_error	AI 错误	AI API Key 失效、余额不足或模型端报错
button_not_found	按钮未找到	在消息内未定位到与指定规则匹配的内联按钮
message_not_modified	消息内容未变化	Telegram 编辑消息时内容与原文本一致（良性状态）
target_not_found	目标未找到	目标群组/频道/机器人不存在、无访问权限或已被封禁
network_proxy	网络/代理	代理不可达、网络连接中断或 DNS 解析失败
timeout	超时	任务整体执行超时或协程等待超时
strong_failure	业务失败	消息文本明确包含签到失败、操作异常等业务错误语义
task_loop_exceeded	工作流循环熔断	工作流 DAG 步数达到全局上限、循环次数超限或触发非法环路
unknown	未知失败	未命中上述规则的其他异常

相关 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 指定执行时刻。

• 面板表单中 sign_at 填 HH:MM 或 HH:MM-HH:MM 时间段（如 08:00、08:00-19:00）
• 后端同时兼容 5/6 段 cron 表达式作为 API 级高级用法，面板表单不展示

适合：

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

2. range

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

• range_start
• range_end

适合：

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

3. listen

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

适合：

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

错峰与自适应调度

Jitter 错峰

jitter_seconds（0–3600，默认 0）为任务在 cron 触发时刻上叠加一个 0 ~ jitter_seconds 的随机偏移， 用于打散多账号同时执行造成的请求洪峰。偏移由调度触发器承担，任务体内不再重复延迟， 因此实际最大延迟等于 jitter_seconds 本身。

自适应动态冷却调度

开启 adaptive_schedule_enabled 后，任务执行完成时会解析机器人回复中的冷却倒计时 （如「冷却中，请等待 15 分钟」「Try again in 2h 30m」），并把该任务的下次运行时间动态 调整为 当前时间 + 冷却时长 + padding。

字段	说明
adaptive_schedule_enabled	是否开启，默认 false
adaptive_schedule_patterns	自定义正则列表，优先于内置多语言解析器；单条长度上限 200 字符
adaptive_schedule_padding_seconds	冷却时长之外额外延后的秒数，默认 30（0–86400）

• 内置解析器只接受 10 秒 ~ 72 小时区间的时长，避免把「获得 500 积分」这类数字误判为冷却。
• 调整只影响该任务的下一次运行，不修改 cron 定义；任务一旦执行即清除该覆盖。

聊天配置

每个目标聊天支持：

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

message_thread_id

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

面板的目标会话选择器会调用 GET /api/accounts/{account_name}/chats/{chat_id}/topics 自动识别论坛群组的话题列表（非论坛群组返回空列表，不会报错），也可手动填写话题 ID。

目标会话筛选

选择目标会话时可先用 Telegram 对话文件夹过滤列表（GET /api/accounts/{account_name}/folders）， 仅影响候选会话的展示范围，不会改变已选中的会话。

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 有风控/封禁风险）。详见 关键词监听
99	自定义插件	调用本地自定义 Action 插件执行扩展逻辑（如免 AI 算式秒答等）。详见 自定义插件

文本模板与素材字典

发送文本类动作的文案支持两种动态替换。

{{ }} 表达式

{{ expression }} 由安全 AST 求值器渲染，失败时保留原文，不会静默清空内容。

可用变量与函数：now、utcnow、today、random_int(min, max)、random_choice(seq)、uuid(short)、 dict_entry(name, mode)、str、int、len 等；禁止访问私有属性与 format / format_map。

{dict:name} 素材字典宏

系统设置中的「素材数据字典」维护动态文本池，任务文案可直接引用：

{dict:greetings}                  # 随机取一条
{dict:greetings:round_robin}      # 按游标顺序轮询取词

• 字典名仅允许字母、数字、下划线、短横线；空词条字典会被拒绝。
• 轮询游标会持久化，重启后继续按序取词。
• 字典不存在或取词失败时保留原宏文本，不影响任务执行。
• 表达式先渲染、字典宏后渲染，因此词条内容中的 {{ ... }} 不会被二次求值。

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 动作紧跟在按钮动作之后
• 范围执行适合多号，固定执行适合单号
• 监听任务与定时任务分开管理，便于排障