企业官网建设流程全解析

724-office（7/24 Office）是一个纯 Python 编写的自进化 AI Agent 系统，其中的定时任务（Scheduled Tasks）能力让 Agent 像真人助理一样"记住时间"：你可以用一句自然语言创建一次性提醒或cron 周期任务，任务持久化存储、重启不丢失；更妙的是内置的3天不活跃守卫，当用户几天不说话时，Agent 会自动停止打扰，等你回来时再恢复。本文带你完整看懂这套定时任务系统的设计与实战用法。

一、定时任务在 724-office 中的位置

整个调度能力由三个文件协同完成：

启动时，入口 xiaowang.py 会执行scheduler.init(JOBS_FILE, llm.chat, ...)，任务统一持久化到jobs.json（默认位于AGENT_DATA环境变量指向的目录，见 xiaowang.py），后台线程每10 秒轮询一次到期任务。

💡 对新手来说，最重要的理解是：定时任务不是"到点发一条固定消息"，而是"到点把任务描述交给 LLM 处理"，LLM 决定调用什么工具、回复什么内容。

二、如何创建一次性定时提醒

LLM 通过schedule工具创建任务（定义见 tools_messaging.py），对一次性任务推荐使用target_time参数，格式为YYYY-MM-DD HH:MM（本地时间）。

实际效果示例：

• 🕘 「明天早上 9 点提醒我开会」→ 创建一次性任务，到点触发
• ⏱ 「20 分钟后提醒我喝水」→ 也可以用delay_seconds指定秒级延迟
• 📅 创建时系统会自动校验时间格式，已过去的时间会直接报[error] Target time ... has passed

一个很实用的细节：年份自动纠错。大模型有时会按训练数据写出过期的年份（比如 2024 年），scheduler.py 的add()逻辑会在检测到目标时间已过期时，自动把年份修正为今年或明年，并在返回消息里明确告知"已自动纠正年份"。这避免了"提醒永远不会触发"这类隐蔽 bug。

创建同名任务时，旧任务会被自动覆盖（按name去重），所以改提醒时间只需重新下发即可。

三、cron 周期任务配置教程

对于循环执行的任务，schedule工具接收标准cron 表达式（cron_expr），底层依赖croniter库解析：

• 0 9 * * *—— 每天早上 9 点（比如晨间日报）
• 0 */2 * * *—— 每 2 小时（比如巡检）
• once参数默认为true，即 cron 任务只执行一次（存为once_cron类型）；设为false才是真正的周期循环任务（cron类型）

时区处理上，调度器统一使用CST（东八区）时区解析 cron 表达式（见 scheduler.py、scheduler.py），从上次运行时间推算下一次触发点，不会像部分实现那样默认按 UTC 解析导致"差 8 小时"的坑。

几个值得注意的健壮性设计：

1. 原子写入：jobs.json先写临时文件再os.replace重命名，进程崩溃也不会损坏任务清单（scheduler.py）
2. 过期清理：已完成的一次性任务保留 24 小时后自动删除
3. 心跳日志：每 30 分钟打印一次任务心跳，包含每个 cron 任务的下次触发时间（scheduler.py），方便运维排查

用list_schedules可随时查看全部未完成任务，用remove_schedule按名字删除。

四、3天不活跃守卫：不打扰沉默的用户

这是 724-office 定时任务最出彩的设计。如果给每个用户都挂着"每天早 9 点发日报"的任务，而用户已经一周没上线了，Agent 继续推送就是骚扰。

守卫机制分为三步：

1️⃣ 记录用户活跃时间

每当用户发来私聊消息，xiaowang.py 就会把当前时间戳写入该用户工作区的.last_user_message标记文件。注意它不依赖会话文件 mtime——因为定时任务本身也会修改会话文件，容易造成"假活跃"。

2️⃣ 触发前检查沉默时长

调度器在触发每个 cron 任务前，先计算距上次用户活跃的秒数。阈值定义在 scheduler.py：

INACTIVITY_THRESHOLD = 3 * 86400（即3 天）

超过 3 天且任务不是内部维护任务时，直接跳过本次执行，并写入.dormant_since休眠标记（仅首次写入）。

3️⃣ 用户回归自动恢复

当沉默的用户重新发消息时，xiaowang.py 会删除.dormant_since标记，调度守卫随之失效，周期任务重新正常触发——整个休眠/唤醒周期无需人工干预。

哪些任务永不停跳？

内部维护类任务即使用户不活跃也必须执行，否则会破坏自进化闭环。scheduler.py 中定义了关键字清单：archive（归档）、diary（日记）、review（复盘）、self_check（自检）、digest（日报摘要）、compact（记忆压缩）、audit（审计）、patrol（巡检）等。只要任务名或任务描述包含这些关键字，就会被识别为内部任务而豁免守卫（判断逻辑见 scheduler.py）。

🧠 一句话总结：面向用户的推送任务"人走茶凉"，面向系统的维护任务"风雨无阻"。

五、触发执行的兜底保障

任务到点后，调度器把任务描述作为一条"用户消息"交给 LLM 处理（scheduler.py），围绕可靠性做了多层兜底：

• 日期锚点注入：触发消息会带上[Scheduled task triggered | Created: ... | Now: ...]，防止 LLM 按创建时的旧指令行事
• Fallback 发送：如果 LLM 只回了文本却忘了调message工具，系统检测会话记录后代为把回复发给用户（scheduler.py）
• 静默任务：任务名/描述含silent、no_notify等关键字时跳过 fallback，适合纯后台任务
• 失败通知：任务执行抛异常时，调度器会再调一次 LLM，要求其通过message工具把错误告知用户
• 群聊任务独立通道：带group_id的任务走独立的scheduler_group_*会话，互不干扰

此外，nudge.py 还内置了一条"行为纠正"规则：如果 LLM 在回复里说"提醒已设好"却没有真正调用schedule工具，系统会注入一条提示让它立即补调工具——"口头承诺不算执行"。这一层保证了你在聊天里创建的定时提醒必定落盘。

六、相关文件速查

总结

724-office 的定时任务系统用不到 700 行纯 Python，实现了生产级的三大能力：一次性提醒（含年份自动纠错）、cron 周期任务（时区正确、持久化、原子写）以及3天不活跃守卫（用户沉默自动静音、回归自动恢复）。配合 fallback 发送、静默关键字和 nudge 系统，整个链路不依赖"大模型自觉"，而是用结构化代码兜底——这正是该项目"不靠提示词约束行为，而靠结构让错误不可能发生"的设计哲学。如果你想给自己的 AI Agent 加一个靠谱的定时器，这套实现是非常好的参考范本。