1. 上手 dsh 的第一周我满脑子都是“这破工具也能加定时任务”拿到 dsh 的头几天我干的第一件事就是找 Cron。做 agent 项目谁不需要定时触发定时巡检、定时发日报、定时去某个站点抓一次数据这些全是刚需。结果我把文档翻了个底朝天只找到三个工具一个能看当前时间一个能等一会儿另一个能循环执行。连 cron 表达式都不支持。当时我的第一反应和大多数同事一样这也太抠了。定时任务这种基础设施不应该是配一张时间表、到点自动触发吗三个原语能干什么直到我把几个真实需求跑完之后才意识到dsh 是在用这套“少得可怜”的工具传递一个很讲究的设计观agent 的定时任务本质不是“到点执行脚本”而是“让 agent 自己感知时间、自己决定接下来做什么”。Cron 把“时间”偷偷藏在了系统层agent 完全感知不到dsh 则把“时间”重新变成了 agent 可以读取、可以推理、可以用来做决策的上下文。这篇文章我就把这条链路彻底拆开dsh 给的那三个工具到底能干什么、为什么故意不做 Cron、以及我最后怎么用这三个工具拼出了一个能应对真实需求的轻量定时任务系统。如果你是刚接触 agent 开发或者正在自己的项目里纠结“定时任务到底怎么设计”这篇应该能帮你少走不少弯路。提醒一点不同 dsh 版本里这三个工具的叫法略有差异有的叫now、wait、loop有的叫get_current_time、sleep、repeat但底层能力都是同一套。你按思路对号入座就行。1.1 第一个工具时间感知把“现在”变成 agent 的输入这个工具极其朴素就是返回当前时间。可以是 ISO 格式的字符串也可以是 Unix 时间戳取决于你的 profile 配置。早期我根本没把它当回事直到写定时任务时才发现它是整套方案的地基agent 只有拿到了“现在”才能判断“到点了没”。关键点在于这个时间不是给外部调度器用的是给 agent 自己读的。传统 Cron 的工作方式是把时间藏在系统层到点了系统直接拉起命令命令本身没有“现在是几点”这个概念。而 dsh 的做法是让时间成为 agent 的输入信息agent 拿到之后可以自己比较、自己推理。我在实际使用中会把它放在主循环的第一步每次醒来先读一次时间再决定后续动作。这里有个我踩过的坑dsh 不同插件返回的时间格式不统一有的是带时区的 ISO 字符串有的是本地时间。如果后面要做差值计算建议先统一转成 UTC 时间戳否则早晚会算错。1.2 第二个工具主动等待让 agent 自己决定“什么时候再想这件事”第二个工具是等待参数通常是秒数或分钟数。调用之后agent 会在当前会话流里暂停一段时间暂停期间不产生新的推理输出但上下文和记忆都还挂着醒来之后能接着干。很多人会用错这个工具。最容易犯的错是把wait当成“后台定时器”调一个wait(3600)就以为系统会在一个小时后自动唤醒 agent 干活。不是这样的。wait是 agent 主动挂起自己的动作它需要 agent 在唤醒后继续执行后续逻辑。这更像一个人说“我先眯十分钟到点你叫我但叫醒之后我得知道自己接下来要干嘛”而不是闹钟到点自动播放音乐。我后来把它理解成“主动暂停”就好理解了。比如 agent 巡检一个接口第一次请求发现数据还没更新它可以自己决定“5 分钟后再来看一次”于是调wait(300)。这个决定是 agent 根据现场情况做的不是写死在配置文件里的。所以在设计调度逻辑时wait不应该单独出现它总是和“醒来之后干什么”绑定在一起。这一步绑定关系就是 dsh 定时任务的核心博弈点。1.3 第三个工具循环执行让任务在“清醒-执行-再等待”之间转起来第三个工具是循环。它让 agent 可以把一段逻辑反复执行直到条件满足、次数用尽、或者 agent 自己判断该停。注意loop不是独立进程它还是在同一个 agent 会话里使用同一份记忆和上下文。有了loop事情就通了循环里先now读时间检查任务列表里哪些任务已经到期到期的执行没到期的算好下一个最近任务的时间然后wait到那个时间点醒来再循环。这就是一个最简的定时任务调度器零件只有三个逻辑链却完整。我见过有人在循环里不写退出条件导致 agent 无休止转下去。所以我的习惯是给循环加两个保险一是最大循环次数上限二是每轮循环都要检查一次“任务列表是否为空、是否还有必要继续”。如果调度列表空了就让 agent 主动结束循环把控制权交回去而不是空转等待。用生活化的方式理解这三件套now是看表wait是“到点再叫我”loop是“一直重复这个流程”。dsh 不给你“自动执行器”它给你的是组装自动执行器所需的全部基础零件。2. 为什么 dsh 故意不做 Cron这不是偷懒是换了一套调度哲学很多人看到这里还会觉得就算有三个工具Cron 表达式不是更省事吗写一行0 9 * * *不就每天九点执行了我一开始也是这个心态直到真正把 agent 任务往前推才发现 Cron 这种静态调度和 agent 的决策逻辑根本是两套思维。Cron 擅长的事情非常明确固定时间触发固定命令。运维场景里它无可替代比如凌晨备份数据库、每小时清理日志。这些任务的问题是“内容固定、参数固定、无非到点执行”。但 agent 的任务不一样agent 的任务是多步决策先看状态、再定策略、然后执行、最后判断要不要重新来一遍。它需要一个“会思考的调度”而不是一个“只会报时的闹钟”。假设你要做一个每天早上九点生成日报的任务。用 Cron 挂一个命令命令内容通常是“调接口拿数据-套模板-发出去”模板是死的。但如果把这个任务交给 agent它会希望先看一眼昨天有没有异常数据、周末的流量走势是否正常、今天有没有值得重点关注的业务变化然后再决定日报的格式和详略。这些判断全都依赖上下文Cron 给不了。dsh 故意不做 Cron我理解是三层考量。第一层Cron 触发器是外部强制的agent 醒过来后对“为什么要执行”完全没有感知只能被动执行一个预先写死的动作第二层Cron 的任务状态在触发前后是割裂的“上次做到哪儿了”没有任何记录这对需要记忆的 agent 来说等于失忆第三层Cron 表达式能表达“什么时候”却表达不了“什么情况下才值得做”而后者恰恰是 agent 的核心价值。我后来找到一个还算准确的类比Cron 就像养在笼子里的鹦鹉到点叫一声声音是从外部来的而 dsh 希望你的 agent 成为有日程表的助理自己看时间、自己安排优先级、自己决定先做什么后做什么。前者适合固定指令后者适合真正意义上的智能任务。所以与其追着 dsh 要一个 Cron 实现不如顺着它的设计思路走把时间变成 agent 的上下文把触发决策权还给 agent。这样设计出来的定时任务不会在某个环节断掉。3. 实操用三个工具拼出轻量定时任务系统说完了理念该上硬货了。我在 dsh 里搭过一个能用的轻量定时任务 Skill结构不复杂但足够应对“每小时巡检一次”“每天下午五点生成小结”这类需求。下面把完整思路拆给你看。整体架构就三块任务表、主循环、持久化。任务表放在 dsh 的 memory 里字段包括task_id、action、next_run、interval、last_result。主循环负责不断读当前时间、检查到期任务、执行、更新下一次执行时间。持久化负责在会话结束后保存任务表让 agent 下次启动还能想起来“今天有活没干完”。伪代码长这样# dsh skill: schedule 主循环逻辑 load schedule from memory loop: now dsh.now() for task in schedule: if task.next_run now: result run_task(task.action) task.last_result result task.next_run compute_next(task.interval, now) # 每个任务执行完立刻把结果写回记忆 save task to memory save schedule to memory # 计算下一个最近任务的时间避免无意义空转 next_time min(task.next_run for task in schedule) sleep_sec max(next_time - now, 0) dsh.wait(sleep_sec)这个伪代码最关键的一行是最后的wait。它是整个调度器的节拍器每次醒来只处理到期任务处理完算好下一次要等多久然后继续睡。这样既能保证任务不早不晚又不会在空档期反复空转烧 token。在 profile 配置里对应的 skill 大概是下面这种形态{ skill: schedule, tools: [now, wait, loop], memory: { schedule_table: persistent } }我强烈建议把schedule_table声明成持久化。如果不声明dsh 的 memory 可能会采用短期记忆策略对话一长任务表就被冲掉到点 agent 两眼一抹黑。3.1 真实任务举例每 30 分钟巡检 下午 5 点写小结拿一个具体的例子走一遍流程。假设任务表里有两个任务任务动作首次执行间隔A巡检指定目录新增文件则汇总摘要09:0030 分钟B生成当日工作小结17:0024 小时agent 启动后进入主循环第一轮now读出来是 09:00任务 A 刚好到期于是执行文件扫描把摘要写进last_result然后把next_run更新为 09:30任务 B 还没到期跳过。接着程序算出下一个最近任务是 A 的 09:30当前时间是 09:00于是wait(1800)agent 挂起。第二轮醒来时时间约 09:30A 再次到期执行、更新、再算出下次 10:00继续wait(1800)。这个节奏会一直持续到下午五点B 到期触发写小结的动作。任务 B 执行完毕后因为间隔是 24 小时next_run会被推到第二天下午五点。你会发现整个调度逻辑里没有出现任何一个 Cron 表达式。所有时间判断都是 agent 在现场自行计算和执行的。这个方案的好处是如果你想临时跳过某次巡检、或者让 B 在 16:50 提前看一眼有没有遗漏agent 完全可以在执行动作的环节里加入自己的判断而不是死板地卡住时间。3.2 会话重启后的任务恢复任务恢复是定时任务最容易翻车的地方因为很多 agent 其实没真正把状态写进持久化。表现为agent 嘴上答应“好的我会在下午五点写小结”但会话一关全忘干净了。我的做法是每次任务执行完立刻调用 memory 写入接口保存最新状态。这个写入动作必须发生在对话输出之前也就是说先持久化、再回复用户顺序不能反。顺序反了的话如果会话在输出中途被打断任务状态就可能丢了。另外主循环启动时第一步不是直接跑任务而是先执行一次“恢复体检”从 memory 读取任务表检查所有next_run是否比当前时间早太多。如果发现某个任务原本定在昨天执行但 agent 一直没醒那就需要判断是补执行还是顺延。我一般会选择顺延因为 agent 任务往往讲究时效性补跑昨天的日报意义不大。这个判断逻辑放在主循环加载阶段最合适。不要指望着靠提示词里的“你记得下午五点写小结”来保住任务。那只是对话上下文不是持久化。真正的定时任务状态必须落盘否则随时可能失业。3.3 跨会话唤醒要不要引入外部 Cron这里有一个绕不开的问题如果 dsh 桌面端关了、会话完全结束agent 里的loop也就停了定时任务自然不会再跑。对于纯会话内的场景比如“接下来的两个小时内每半小时帮我检查一次邮件”三个工具足够。但如果你的任务是“每天早上九点生成日报”而你的 dsh agent 不可能全天挂着你就需要一个外部唤醒机制。所谓外部唤醒就是用一个最小化的外部触发器在目标时间把 agent 会话重新激活。注意这个外部触发只负责“叫醒”不负责“调度”。agent 醒过来之后自己从 memory 里加载任务表自己决定要干什么。这才是 dsh 设计哲学的正确延伸触发的动作可以来自外部但决策必须留在 agent 内部。我曾经犯过一个错误把完整的任务动作参数都塞在外部触发器里想着到点直接传给 agent。结果发现这等于把 agent 降级成了执行器一点智能优势都没用上。正确做法是只在外部记一个极简的信号比如“09:00 该醒了”剩下的全部交给 agent 读记忆、查任务、自主执行。所以我的结论是dsh 不做 Cron 不代表你不能用 Cron。你可以用系统级的定时器做外部唤醒但不要用 Cron 直接表达 agent 任务。把“唤醒”和“执行”剥离开才是这个设计哲学的正确玩法。4. 踩坑实录与排查技巧定时任务翻车现场这部分我整理了自己实际跑下来遇到最多的问题每一个都真实踩过不是网上随便抄来的。4.1 时区不一致任务“到点”的时候 agent 还在睡第一个大坑是时区。dsh 的now工具在不同环境下返回的时间格式不一样有的带08:00后缀有的是 UTC。一开始我没做统一结果任务表里写的 17:00 是本地时间而now返回的是 UTC两边一比永远差八个小时。排查方法很笨但有效在任务启动时故意打印一条当前时间 任务时间 差值的日志一眼就能看出单位是否一致。我的统一策略是内部计算一律使用 UTC 时间戳展示转本地任务表存next_run时也用 UTC 时间戳带时区标记。只要全链路都统一成 UTC 时间戳时区问题就基本绝迹了。4.2 循环风暴wait 太短token 烧得飞快另一个高频事故是wait参数设置不合理。我早期测试时把间隔写成 10 秒想着方便观察日志结果 agent 每隔 10 秒就醒一次每次都把全套上下文重新过一遍几分钟内 token 量暴涨费用肉眼可见地飙升。解决思路是分级设计开发调试时可以用短间隔但上线场景必须按真实业务频率来。如果任务本身是小时级的wait至少设到 300 秒以上如果是天级的直接睡到目标时间点。还有一招给loop设置最大循环次数比如最多循环 10 轮到了次数就自动把控制权交还给用户防止无人值守时发生死循环。4.3 任务丢了agent 点头不等于记住了这个坑前面提到过再重点强调一遍。dsh 里有记忆能力但记忆分长短期。如果任务表没有显式声明为持久化agent 的短期上下文一滚动旧任务就可能被冲掉。而且很多 agent 在对话里被用户提醒“别忘了下午五点写小结”它只会口头答应不会真的写入 memory。我后来养成了一个习惯任务注册接口里强制做一次“双向确认”既写任务表又要在回复里明确告诉用户“已写入持久化记忆任务 ID 为 xxx”。这样用户下次问起来agent 可以按 ID 去查而不是依赖对话上下文里的模糊印象。这个小习惯救了我好几次。4.4 多任务并发一个会话只有一个大脑最后一个问题是并发。dsh 的单个 agent 会话本质上是串行的同一时刻只能处理一件事。如果任务表里有三个任务同时到期而它们都需要较长的执行时间agent 只能排队一个个来。这不是 bug是架构使然一个 agent 实例就是一个“大脑”大脑不能同时思考两件事。要扛并发正确姿势是把并发放到外部。比如把任务表做成一个外部消息队列多个 agent worker 各自消费队列里的任务或者干脆在外部做负载分配把不同任务派给不同的 agent 会话。dsh 只负责单会话内的智能体决策别指望它在单会话里并行。这里放一张常见问题速查表方便你直接对照排查现象可能原因解决思路到时间没执行时区不一致任务表没持久化统一 UTC 时间戳检查 memory 写入循环里上下文爆炸wait太短循环反复塞入历史拉长等待间隔限制最大循环次数重启后任务忘记任务表没声明 persistent显式声明持久化先落盘再回复到点但 agent 不知道干嘛唤醒信号没携带任务上下文唤醒后从任务表读取不靠提示词多个任务同时卡住单会话串行处理外部队列 多 agent worker 分流5. 扩展玩法从“定时”到“条件触发”最后聊点进阶的。这套“三工具调度”真正的威力不在于复制 Cron 到点执行而在于你可以很自然地把它升级成条件触发。比如定时巡检某个数据源传统 Cron 的思路是“每天早上 9 点拉一次数据”。但 agent 可以做得更聪明每天早上 9 点检查一次如果发现异常才通知用户没异常就只在记忆里更新状态。这里的“9 点检查”是定时“有异常才通知”是条件两者组合起来才是 agent 场景下真正有价值的调度。类似玩法还有很多。配合 dsh 插件生态里读文档的工具可以做一个每天早上自动汇总指定目录里所有 Word/PDF 文档摘要的 agent跑完之后直接把摘要发到你的聊天窗口。配合浏览器插件可以做定时巡检指定网页改版的需求内容变了才提醒你。这些场景里定时只是触发层真正的价值全在 agent 的判断层。我自己的习惯是设计任何定时任务前先问一句这个任务到底需不需要 agent 的脑子如果只是固定动作扔给外部 Cron 就行如果涉及判断、记忆和多步决策才用三件套。这样分清之后整个系统反而清爽很多。