夜雨聆风学习资料网

ARTICLE · 1037472

DSH插件之——定时/提醒工具

发布时间：2026-09-19 13:37:40 最近访问：2026-09-19 13:37:40
DSH插件之——定时/提醒工具

dsh-plugin-timer

定时/提醒插件（v0.1.0）：让模型能安排延迟任务并查看到期情况。定时器持久化到工作目录 .timers.json，跨会话可查。

安装

npm install dsh-plugin-timer

工具

set_timer

参数
类型
说明
duration
string
时长：秒数（"90"）或自然语言（"30s" / "5m" / "2h" / "1d" / "1h30m" 组合式，单位不可重复）
label
string
到期时的提醒内容

范围 1 秒 ~ 30 天；单工作目录上限 50 个。

list_timers

参数
类型
说明
include_done
boolean
默认 false；true 时附带已到期项（带【已到期】标记）
limit
number
默认 20，上限 50

待到期按剩余时间升序。已到期项应立即向用户转达提醒内容。

cancel_timer

参数
类型
说明
id
string
要取消的定时器 ID
all_done
boolean
true 时一次性清理全部已到期定时器

持久化设计

  • 状态文件：<工作目录>/.timers.json，纯 JSON，人工可直接查看编辑
  • 启动恢复：每次工具调用都从文件重新加载，无内存态，插件重启/换会话不丢数据
  • 损坏容错：文件损坏时返回空列表而不崩溃，下次写入自动重建
  • 到期检测是拉模式：list_timers 时对比当前时间标记到期项；定时器不主动推送通知

测试

npm test

覆盖时长解析（14 例）、设置/列表/到期检测/取消、参数校验、损坏文件恢复、50 上限等 38 项断言。

版本历史

0.2.0（2026-09-13）

  • set_timer 支持绝对时间 at（本地时区，过去时间拒绝）
  • 新增 repeat 重复间隔（≥60 秒），到期自动滚动到下一次并报告错过的到期点
  • all_done 清理保留重复定时器（避免误删循环任务）

典型场景

1. 会议/任务提醒

// 设置 30 分钟后提醒set_timer(”30m”, ”请准备项目进度汇报”)

2. 代码审查超时

// 2 小时后提醒代码审查任务set_timer(”2h”, ”审查 PR #123”)

3. 定期维护任务

// 24 小时后提醒数据库备份set_timer(”1d”, ”执行数据库自动备份”)

4. 长期项目节点

// 5 天后提醒里程碑检查set_timer(”5d”, ”检查 Q3 里程碑完成情况”)

5. 重复提醒任务

// 每天上午 9 点提醒（需宿主支持定时触发）set_timer(”24h”, ”每日站会提醒”)

安全边界

1. 资源限制

  • 时长范围：1 秒 ~ 30 天（防止极端耗时任务）
  • 定时器数量：单工作目录上限 50 个（避免内存/磁盘溢出）
  • 输入大小：duration 限制在合理长度，防止超长字符串

2. 输入验证

  • duration
     必须符合格式要求（单位不可重复）
  • label
     长度限制（防止恶意构造长文本）
  • id
     必须是字符串类型
  • at
     绝对时间拒绝过去时间（防止误操作）

3. 文件安全

  • 存储位置：<工作目录>/.timers.json（受工作目录隔离）
  • 权限控制：仅允许读取/写入自身目录的 JSON 文件
  • 损坏容错：文件损坏时返回空列表，不抛出异常
  • 并发安全：每次工具调用独立加载，避免竞态条件

4. 行为约束

  • 拉模式检测：定时器不主动推送，需调用 list_timers 查看到期项
  • 数据持久化：重启/换会话不丢数据，但需手动清理已到期项
  • 取消机制：支持单个取消和批量清理已到期项

FAQ

Q1: 定时器到期后会有通知吗？

A:目前采用拉模式。到期后需调用 list_timers 查看带有【已到期】标记的项，然后手动转达提醒内容。未来版本会支持主动推送（需宿主通知能力）。

Q2: 定时器重启后会丢失吗？

A:不会。所有定时器持久化到 <工作目录>/.timers.json，插件启动时自动恢复。重启/换会话不丢数据。

Q3: 可以设置重复的定时器吗？

A:v0.2.0+ 支持 repeat 参数，设置重复间隔（≥60 秒）。到期后自动滚动到下一次，并报告错过的到期点。宿主需支持定时触发才能实现真正的循环任务。

Q4: 如果 .timers.json 损坏了怎么办？

A:插件会自动检测文件损坏，返回空列表而不崩溃。下次写入时会自动重建文件。你可以手动备份或删除该文件来重置。

Q5: 为什么不支持绝对时间（如 "2026-10-01 10:00"）？

A:当前版本仅支持相对时长（duration）。绝对时间需要处理时区、闰秒、夏令时等复杂问题，已在 v0.2.0 支持绝对时间 at 参数。

Q6: 如何批量清理已到期的定时器？

A:使用 cancel_timer 的 all_done 参数：cancel_timer(null, true)。这会一次性清理所有已到期项，但保留重复定时器（避免误删循环任务）。

Q7: 定时器数量超过 50 个会怎样？

A:set_timer 会拒绝超过 50 个的请求。建议定期清理已到期或不再需要的定时器。

Roadmap（v0.3 候选）

  • 到期主动推送（需宿主通知能力）
  • 定时器备注与优先级
  • 到期历史记录查询
  • 定时器分组/标签
  • 跨工作目录同步（可选）
  • 导出/导入定时器配置

源码及发布地址

源码仓库

  • GitHub: https://github.com/geeklei/dsh-plugins/tree/main/dsh-plugin-timer

npm 发布地址

  • npm 包: https://www.npmjs.com/package/dsh-plugin-timer
  • 版本: v0.2.0
  • 发布时间: 2026-09-13

注意: GitHub 仓库地址可能需要根据实际部署情况调整。

安装方式

# 从 npm 安装npm install dsh-plugin-timer# 或从本地路径安装（开发调试）dsh plugin --profile web add ./dsh-plugin-timer-0.2.0.tgz

贡献指南

  1. Fork 源码仓库
  2. 创建功能分支：git checkout -b feature/amazing-feature
  3. 提交更改：git commit -m 'Add amazing feature'
  4. 推送到分支：git push origin feature/amazing-feature
  5. 提交 Pull Request

相关学习资料