TeleBot / 定时委托 PRD
TeleBot / 项目文档

TeleBot 定时委托 PRD(功能迭代)

一次定时委托功能迭代的需求文档,记录迭代背景、目标与交互规则。

TeleBot「定时委托」PRD:任务定时触发与主动执行#

功能名称: 定时委托(Scheduled Delegation)
功能范围: TeleBot 任务定时触发
主要入口: 飞书自然语言消息、/schedule 命令
示例场景: 每天凌晨在 job_workspace 中调用 autumn-recruiment Skill,更新机器人 / 具身智能产品经理秋招岗位文档,并将新增与修改项汇总成表返回飞书


01 背景#

TeleBot 原有任务都由用户即时触发:

用户发消息 → Agent 执行 → 返回结果

这一模式可以完成文件查询、知识检索、报告生成等即时任务,但对于“以后再执行”或“周期重复执行”的任务,用户仍需要每次重新发起。

典型表达包括:

  • “明天晚上七点提醒我检查报告。”
  • “每天早上九点执行一次这个任务。”
  • “每周一帮我运行一次固定流程。”
  • “周五下午调用这个 Skill,把结果发给我。”

这类需求的核心并不是增加一个简单的计时器,而是建立一套完整的任务生命周期:

解析时间 → 创建任务 → 确认权限 → 持久化 → 到期调度 → 执行 → 结果反馈 → 进入下一周期

因此,本次迭代在 TeleBot 的即时任务体系之外增加“定时委托”能力,使用户可以将一个任务从“现在执行一次”转换成“未来按约定继续执行”。


02 产品目标#

定时委托需要解决五个问题:

  1. 用户能自然地说清“做什么、什么时候做”。
  2. 任务在程序重启后仍然存在,而不是依赖一次内存定时器。
  3. 创建任务与允许未来自动执行是两个不同的授权动作。
  4. 周期任务的一次失败不会让整个任务永久失效。
  5. 用户能够知道任务何时执行过、结果如何以及下一次何时执行。

核心体验从:

每次到时间,我还要重新告诉 TeleBot 做什么

转变为:

我只需要委托一次,TeleBot 按确认过的时间和权限继续执行。


03 功能模块图#

flowchart LR
    U[用户 / 飞书] --> F[消息入口]
    F --> A[Agent]
    A --> M[schedule_manage]
    M --> S[ScheduleService]

    S --> DB[(scheduled.sqlite)]
    S --> Q[调度与状态管理]
    Q --> E[执行器]

    E --> T[已授权 Tool / Skill]
    T --> R[执行结果]
    R --> N[飞书通知]
    N --> U

    S --> H[任务历史 / events]
    E --> H
    N --> H

模块职责#

模块主要职责
消息入口接收用户自然语言或 /schedule 指令
Agent判断用户是在创建、查询、修改或删除定时任务
schedule_manage将当前飞书消息和可信会话身份交给定时服务,不允许模型伪造用户身份
ScheduleService解析、校验、确认并持久化任务
调度与状态管理扫描到期任务、生成执行、处理错过时间、重复执行和下一周期
执行器在已授权工具和目录范围内执行任务
通知模块发送入队、开始、完成、失败、授权申请等消息
历史与事件保存任务变化、执行结果和重要事件,供查询与问题定位

04 功能树#

mindmap
  root((定时委托))
    创建任务
      自然语言创建
      /schedule create
      单次 once
      每日 daily
      每周 weekly
      执行时间
    权限
      仅提醒
      逐次授权执行
      预授权自动执行
      工具范围
      目录范围
    任务管理
      查询列表
      查看详情
      修改
      删除
      查看历史
    调度
      到期扫描
      执行排队
      下一周期计算
      missed policy
      防重复执行
    执行
      加载授权工具
      调用已有 Tool / Skill
      超时控制
      串行执行
    结果反馈
      入队通知
      开始通知
      成功结果
      失败结果
      授权申请
      通知重试
    记录
      任务状态
      执行状态
      events
      history

05 核心体验#

journey
    title TeleBot 定时委托核心体验
    section 创建
      用自然语言描述任务和时间: 5: 用户
      查看系统解析后的任务摘要: 4: 用户
      确认任务与执行权限: 4: 用户
    section 等待
      任务持久保存: 5: TeleBot
      到期自动进入调度: 5: TeleBot
    section 执行
      按权限提醒或执行: 5: TeleBot
      调用已有工具或 Skill: 5: TeleBot
    section 交付
      收到执行结果: 5: 用户
      查看历史与下一次执行: 4: 用户

本功能最重要的产品变化是:

用户离开当前会话后,任务仍然继续存在。

这意味着系统第一次需要对“未来的执行权”负责,因此任务确认、执行授权、状态记录和异常反馈都成为核心体验的一部分。


06 用户流程#

6.1 创建任务#

用户既可以直接说:

“每天凌晨,在 job_workspace 目录下用 Codex 调用 autumn-recruiment Skill,更新机器人 / 具身智能产品经理相关岗位,将新增和修改的部分汇总成表格发给我。”

也可以使用显式命令创建。

系统首先解析:

  • 任务内容;
  • 首次执行时间;
  • 周期规则;
  • 执行模式;
  • 需要调用的工具;
  • 工具需要访问的目录范围。

然后向用户展示任务摘要,而不是解析完成后立即生效。

flowchart TD
    A[用户提出定时请求] --> B[解析任务内容 / 时间 / 周期]
    B --> C{信息是否合法且完整}
    C -- 否 --> D[要求用户修正]
    D --> B
    C -- 是 --> E[生成待确认任务摘要]
    E --> F{用户确认}
    F -- 取消 --> G[终止创建]
    F -- 普通确认 --> H[保存任务]
    F -- 确认预授权 --> I[保存任务与授权范围]
    H --> J[进入等待调度状态]
    I --> J

创建摘要应让用户看清#

信息示例
任务内容更新机器人 / 具身智能产品经理秋招岗位文档,并返回新增与修改汇总表
首次执行下一次凌晨的具体执行时间,创建时确认
周期每天
执行模式预授权自动执行
工具范围codex_apply
目录范围job_workspace
错过策略skip / run_once / ask

创建、修改和删除都属于会改变未来行为的操作,因此必须先确认;查询任务和历史不需要确认。


6.2 到期执行#

任务到期后,系统根据执行模式进入不同流程。

flowchart TD
    A[任务到期] --> B{执行模式}
    B -- 仅提醒 --> C[向飞书发送提醒]
    B -- 逐次授权 --> D[发送本次执行授权请求]
    D --> E{用户是否授权}
    E -- 否 --> F[记录本次拒绝 / 跳过]
    E -- 是 --> G[进入执行队列]
    B -- 预授权自动执行 --> G
    G --> H[加载本次允许的工具与目录]
    H --> I[执行任务]
    I --> J{执行结果}
    J -- 成功 --> K[发送结果]
    J -- 失败 --> L[发送失败信息]
    J -- 超时 --> M[发送超时信息]
    K --> N[记录本次执行并计算下一周期]
    L --> N
    M --> N
    C --> N
    F --> N

用户不需要在每个周期重新创建任务,但系统也不会因为任务已经存在,就默认获得超出原授权范围的新权限。


6.3 查询与管理#

当前任务体系提供以下主要管理行为:

用户意图对应行为
“我有哪些定时任务?”查询任务列表
“看看这个任务的配置。”查看任务详情
“把它改成每周三晚上八点。”修改任务并重新确认
“这个任务以前执行得怎么样?”查询执行历史
“删掉这个任务。”删除并确认

显式命令包括 /schedule list、/schedule get、/schedule history、/schedule create、/schedule delete;修改也使用同一任务对象更新并进入确认流程。


07 功能规则#

7.1 时间与周期规则#

定时任务当前支持:

规则含义
once指定时间执行一次
daily按日重复
weekly按星期重复

首次执行时间必须明确。周期任务可以附加间隔、计划次数以及结束时间。

自然语言输入最终必须被转化为明确时间。例如用户说“周一早上九点”,确认阶段应展示解析后的实际日期和时间,让用户在保存任务前有机会发现误解。

已经过去的时间不能直接作为新任务首次时间;用户可以在同一聊天中补充新的时间,系统沿用原任务内容重新解析。


7.2 三种执行权限#

任务“何时触发”和“触发后允许做什么”是两个独立问题。

模式到期后的行为典型用途
仅提醒只发送提醒,不调用任务工具日程提醒、人工处理事项
逐次授权每次到期先申请本次执行权限用户希望保留逐次控制的任务
预授权自动执行在创建时确认固定权限,之后到期直接执行重复、低变化且权限边界清楚的任务

创建确认与执行授权分离#

普通的“确认创建任务”只表示:

同意保存这条任务。

若用户希望未来无需逐次确认自动执行,则需要明确进行:

预授权确认。

这样可以避免把“保存一个计划”隐式升级成“长期允许 Agent 自动操作电脑”。


7.3 工具和目录授权#

预授权不是对 Agent 的无限授权,而是对具体工具和具体作用域授权。

涉及文件工具时还必须指定允许目录。执行进程只加载本次获得授权的工具,并再次限制目录访问。

因此权限模型表达的是:

“未来可以重复做这件事”,而不是“未来可以随意做任何事”。


7.4 任务状态与执行状态分离#

长期任务和某一次执行不能使用同一个状态字段表达。

任务状态#

描述“这条任务本身还是否继续存在和等待未来调度”。

典型状态包括:

  • 待确认;
  • 活跃;
  • 已完成(单次任务执行结束);
  • 已删除。

执行状态#

描述“某一个计划周期发生了什么”。

典型状态包括:

  • 待授权;
  • 已入队;
  • 执行中;
  • 成功;
  • 失败;
  • 超时;
  • 跳过/拒绝。
stateDiagram-v2
    [*] --> PendingConfirm
    PendingConfirm --> Active: 用户确认
    PendingConfirm --> [*]: 用户取消

    Active --> Completed: once 执行结束
    Active --> Deleted: 用户删除

    state Active {
        [*] --> Waiting
        Waiting --> Queued: 到期且获得执行权
        Waiting --> NeedAuth: 到期需逐次授权
        NeedAuth --> Queued: 用户授权
        NeedAuth --> Waiting: 拒绝并进入下一周期
        Queued --> Running
        Running --> Success
        Running --> Failed
        Running --> Timeout
        Success --> Waiting: 周期任务
        Failed --> Waiting: 周期任务
        Timeout --> Waiting: 周期任务
    }

周期任务的一次失败只改变本次执行状态,不默认使长期任务失效。


7.5 错过执行时间#

到期时电脑关机、进程没有运行或调度器暂时不可用,都可能导致计划时间被错过。

系统提供三种 missed policy:

策略行为
skip本周期记为跳过,等待下一个周期
run_once服务恢复后补执行一次
ask服务恢复后询问用户是否补执行

默认情况下,超过计划时间一定窗口后视为错过。

若关机期间错过多个周期:

  • 历史中分别记录对应周期被跳过;
  • 不会在恢复后把所有遗漏周期连续执行一遍;
  • run_once 或 ask 最多补一次或申请一次授权。

这一规则避免用户开机后突然收到大量重复任务。


7.6 执行排队与并发#

定时系统启动后运行:

  • 一个扫描线程;
  • 一个串行执行线程;
  • 执行时最多启动一个受时限约束的子进程。

这意味着当一个定时任务正在执行时,其他到期任务进入排队,而不是无限并发占用本机资源。


7.7 执行时限#

定时执行具有明确的最长运行时间。超出时限后,本次执行进入“超时”,而不是持续占用执行队列。

超时属于本次执行结果,不会默认删除周期任务;系统仍按照周期规则计算后续计划。


7.8 通知与结果交付#

到期任务的关键阶段都通过飞书反馈,包括:

  • 任务进入队列;
  • 开始执行;
  • 需要用户授权;
  • 执行成功;
  • 执行失败;
  • 执行超时。

如果发送提醒、授权请求或执行结果时网络异常,通知不会因为一次发送失败直接丢失,而是保存在数据库通知队列中,在网络恢复后重试。


7.9 历史与事件记录#

重要动作统一记录在定时功能的数据体系中,不另建独立审计系统。

记录范围包括:

  • 任务创建和确认;
  • 权限授权;
  • 任务修改和删除;
  • 计划触发;
  • 入队和开始执行;
  • 成功、失败、超时、跳过;
  • 结果发送。

用户可通过任务历史查询某条任务过去的执行情况;系统也可以利用这些事件定位重复执行、漏执行等问题。


08 核心调用示例:每天凌晨更新秋招岗位文档#

用户提供的任务提示词:

在job_workspace目录下用codex调用里面的autumn-recruiment skill,更新机器人/具身智能产品经理 相关的岗位,将新增和修改的部分总结成一个表格发给我。

用户在首次委托时设定每天凌晨执行,并确认具体时间与工作区授权。后续每次触发由系统完成执行和结果交付。

sequenceDiagram
    participant U as 用户
    participant T as TeleBot
    participant S as Scheduler
    participant C as Codex / Skill Runtime
    participant K as autumn-recruiment Skill

    U->>T: 每天凌晨更新岗位文档并返回变更表
    T->>U: 展示周期、执行方式、工具和工作区
    U->>T: 确认预授权
    T->>S: 保存任务

    Note over S: 到达下一计划时间
    S->>C: 在 job_workspace 工作区执行
    C->>K: 更新机器人与具身智能产品经理岗位
    K-->>C: 返回岗位文档更新结果
    C->>C: 对比本次更新前后,汇总新增与修改项
    C-->>S: 返回文档更新结果与变更表
    S-->>U: 将变更表发送到原飞书会话

这个案例验证的是:

  • 能否把指定工作区中的已有 Skill 封装成未来任务;
  • 能否按周期正确触发;
  • 能否在预授权范围内自动执行;
  • 能否更新目标岗位文档,并区分新增和修改项;
  • 能否把变更表重新交付到原飞书会话。

变更表包含变更类型(新增或修改)、公司、岗位、变更内容和来源链接。修改项列出发生变化的字段及前后差异;没有新增或修改时,返回本次更新无变化的结果。


9 异常处理#

异常处理围绕定时系统真正可能破坏用户信任的三类问题设计。

9.1 超时#

场景#

任务已经正常触发并开始运行,但外部工具、模型、网络或子进程长时间没有返回,超过任务最长执行时间。

产品风险#

如果系统只保持“执行中”,用户无法判断任务究竟还在运行、已经卡死,还是最终会返回结果;同时它可能持续占用串行执行队列,影响后续任务。

处理规则#

  1. 到达执行时限后终止本次受控执行;
  2. 本次执行状态记为“超时”;
  3. 向用户明确发送超时结果,不使用模糊的“执行失败”替代;
  4. 保存本次执行记录和错误信息;
  5. 周期任务保持有效;
  6. 依据原周期计算下一次计划时间;
  7. 后续任务可以继续进入执行队列。

9.2 任务执行失败#

场景#

任务已经到期且获得执行权限,但在实际运行中失败。

产品风险#

如果一次失败直接终止整个周期任务,用户可能在没有察觉的情况下永久失去后续自动执行;如果失败又被当作“正常无结果”,用户则无法判断数据是否可信。

处理规则#

  1. 本次执行状态记为“失败”;
  2. 将可理解的失败原因发送给用户;
  3. 保存失败事件与执行历史;
  4. 不把失败伪装成正常业务结果;
  5. 周期任务继续保持活跃;
  6. 正常计算下一次执行时间;
  7. 下一周期仍按原权限规则执行。

9.3 未能正确重复任务#

场景#

周期任务应该按固定规则重复,但调度出现异常。

产品风险#

重复任务最重要的承诺是“在正确的时间执行一次”。
漏执行会使用户失去对自动化的依赖,重复执行则可能产生重复通知、重复文件甚至重复外部操作。

处理规则#

对漏执行:

  • 扫描器根据任务状态和计划时间识别错过周期;
  • 按 skip、run_once 或 ask 处理;
  • 每个遗漏周期都在历史中留下结果;
  • 恢复后最多补执行一次,不批量重放所有遗漏周期。

对重复执行:

  • 同一计划周期只能形成一个有效执行;
  • 多进程共享数据库时,只允许一个调度器工作;
  • 已存在对应执行记录时,不再次启动同一周期;
  • 通知重试只重发消息,不重新运行已经完成的任务。

对下一周期异常:

  • 每次执行结束后根据任务规则重新计算下一时间;
  • 单次失败、超时或拒绝不会破坏长期周期;
  • 历史记录保留计划时间与实际状态,用于发现周期漂移。

10 验收标准#

验收以任务能否按约定触发、在授权范围内执行并交付结果为准。

10.1 创建、确认与权限#

验收项通过标准
创建与解析自然语言和 /schedule create 均能生成含内容、时间和周期的任务摘要;过期或无法解析的时间不生效
周期规则支持 once、daily、weekly,正确计算首次与后续计划时间
操作确认创建、修改、删除均需确认;修改须重新展示摘要,未确认删除时保留原任务
执行授权普通确认只保存任务;逐次授权每次申请,预授权须明确确认后才能自动执行
权限边界只能调用白名单内且已授权的工具,文件或 Codex 操作不得超出授权目录与工作区

10.2 调度与执行#

验收项通过标准
到期与恢复活跃任务到期进入提醒、授权或执行流程,程序重启后仍能继续调度
周期延续成功、失败、超时或拒绝均记录本次结果,周期任务继续按原规则计算下一计划
错过处理按 skip、run_once 或 ask 处理;遗漏多个周期时最多补一次或申请一次授权
防重复扫描、重启或多进程不会造成同一计划周期重复执行
执行排队定时任务串行排队,运行中的任务不会无限占用资源
失败与超时失败返回明确原因;超时终止本次执行、释放资源,并保留记录

10.3 结果交付与场景验证#

验收项通过标准
关键通知授权申请、入队、开始、成功、失败及超时等状态能够反馈到飞书
通知重试发送失败进入通知队列,恢复后只重发消息,不重新执行任务
历史追溯可查询任务执行历史,创建、确认、授权、触发、执行和交付均有记录
示例闭环每天凌晨在 job_workspace 中调用 autumn-recruiment Skill:确认任务与权限后,无需重新发消息即可更新岗位文档,并返回新增与修改汇总表
连续周期次日生成新的执行;某日失败后任务仍保留,并在后续周期继续调度

11 核心产品取舍#

产品问题方案选择原因
是否用简单内存 Timer使用持久化任务 + 扫描调度任务需要跨程序重启长期存在
创建后是否默认自动执行创建确认与执行授权分离保存计划不应自动扩大未来权限
周期任务失败后是否停用只记录本次失败,长期任务继续单次外部错误不应破坏整个周期
是否允许任意工具自动执行使用白名单 + scope自动化发生在用户不在线时,需要更严格边界
错过多个周期是否全部补跑最多补一次或询问一次避免开机后批量执行过时任务
是否为审计另建系统统一写入任务 events / history任务生命周期和执行历史本身已经提供追溯上下文

12 技术实现与产品规则映射#

技术实现对应产品意义
schedule_manage MCP Tool让自然语言 Agent 可以管理任务,同时由可信会话身份约束用户
ScheduleService把解析、校验、确认和任务管理集中到统一规则
scheduled.sqlite任务跨重启持久存在,并保存执行与通知状态
扫描线程持续发现到期或遗漏任务
串行执行线程控制本机资源和并发风险
子进程执行时限防止单个任务长期卡住整个执行队列
工具白名单控制定时自动执行能力边界
scope.directories将未来自动文件操作限制在用户确认的目录
missed policy明确关机/服务中断后的产品行为
通知队列把“任务完成”和“结果是否成功送达”分开处理
events / history支撑用户查询、异常定位与执行追溯

13 本次迭代的产品价值#

定时委托并不是为 TeleBot 增加一个孤立的“闹钟功能”。

它完成的是产品交互模型的一次变化:

即时任务:
用户发起 → 执行 → 返回
定时委托:
用户一次委托
↓
任务持久存在
↓
未来按规则触发
↓
在确认过的权限内执行
↓
主动返回结果
↓
继续等待下一周期

因此,TeleBot 从一个只能在用户主动发消息时工作的本机助手,进一步变成一个可以承接未来任务和周期任务的本地任务执行入口。

对于后续任意搜索任务、报告任务或 Codex 工作流,定时模块只需要解决同一组问题:

什么时候执行、是否允许执行、可以调用什么、执行结果是什么、下一次怎么办。

这也是本次迭代最核心的产品边界。

© 2026 WindBorne