dsh-plugin-timer

v0.3.0

Published

17 days ago

Timer/reminder plugin for DeepSeek Harness: relative or absolute due times, repeat intervals, tags, grouped listing and expiry history.

0High
0Medium
0Low

geeklei

dsh plugin timer reminder

dsh-plugin-timer

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

安装

npm install dsh-plugin-timer

工具

`set_timer`

| 参数 | 类型 | 说明 | |------|------|------| | duration | string | 时长：秒数（"90"）或自然语言（"30s" / "5m" / "2h" / "1d" / "1h30m" 组合式，单位不可重复） | | label | string | 到期时的提醒内容 | | tags | string[] | 可选，标签（最多 5 个，单个 ≤20 字符），用于分组与筛选 |

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

`list_timers`

| 参数 | 类型 | 说明 | |------|------|------| | include_done | boolean | 默认 false；true 时附带已到期项（带【已到期】标记） | | limit | number | 默认 20，上限 50 | | tag | string | 可选，只列出带该标签的定时器（大小写不敏感，可带不带 #） | | group_by_tag | boolean | 可选，按首个标签分组展示（默认按到期时间平铺） |

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

`cancel_timer`

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

`timer_history`

到期历史查询。历史由 list_timers 在检测到到期时自动记录，同一到期点只记一次（重复定时器按滚动到的到期点逐次记录）。

| 参数 | 类型 | 说明 | |------|------|------| | limit | number | 可选，条数 1-100，默认 20（按通知时间倒序） | | days | number | 可选，只看最近 N 天，1-365，默认 7 | | label_filter | string | 可选，按提醒内容或标签子串过滤（大小写不敏感） | | clear | boolean | 可选，true 时清空全部历史（只清记录，不影响未到期定时器） |

配合 group_by_tag 与 tags，可以回答"上周哪些标签的提醒没处理"这类问题。

持久化设计

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

测试

npm test

覆盖时长解析（14 例）、设置/列表/到期检测/取消、标签归一化与过滤、分组视图、到期历史记录与去重、历史过滤与清空、参数校验、损坏文件恢复、50 上限等 65 项断言。

版本历史

0.3.0（2026-09-30）

新增 timer_history 工具：到期历史查询（天数范围、内容/标签过滤、条数限制、清空）
list_timers 检测到到期时自动记录历史（同一到期点只记一次，重复定时器逐次记录）
新增标签能力：set_timer 的 tags（最多 5 个），list_timers 的 tag 过滤与 group_by_tag 分组视图
测试扩展到 65 项断言

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（定时器）与 .timers-history.json（到期历史，上限 200 条，超出丢弃最旧）；均受工作目录隔离
权限控制：仅允许读取/写入自身目录的 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（如 "30m"），绝对时间用 at（如 "2026-10-01 09:00"，按本地时区解析），两者必须二选一。

Q6: 历史记录会无限增长吗？

A: 不会。历史文件 .timers-history.json 上限 200 条，超出后自动丢弃最早的记录；也可以随时用 timer_history(clear=true) 清空。

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

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

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

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

Roadmap（v0.4 候选）

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

源码及发布地址

源码仓库

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

npm 发布地址

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

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

安装方式

# 从 npm 安装
npm install dsh-plugin-timer

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

贡献指南

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

许可证

MIT License - 详见 LICENSE 文件

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-cron-toolkit（二期 D12） | cron 表达式解释用 cron-toolkit，本插件负责实际计时与到期触发 | | dsh-workspace-journal | 定时器到期事件可写入工作区日志，形成执行记录 | | dsh-plugin-todo | 到期后配合 todo 插件跟进待办事项 | | dsh-fs-inspector | 定时巡检场景：到期后触发目录体积/最近改动检查 | | dsh-session-exporter | 长任务结束后导出会话，留存执行过程 |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

dsh-plugin-timer

安装

工具

set_timer

list_timers

cancel_timer

timer_history

持久化设计

测试

版本历史

0.3.0（2026-09-30）

0.2.0（2026-09-13）

典型场景

1. 会议/任务提醒

2. 代码审查超时

3. 定期维护任务

4. 长期项目节点

5. 重复提醒任务

安全边界

1. 资源限制

2. 输入验证

3. 文件安全

4. 行为约束

FAQ

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

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

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

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

Q5: 如何设置绝对时间（如 "2026-10-01 10:00"）？

Q6: 历史记录会无限增长吗？

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

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

Roadmap（v0.4 候选）

源码及发布地址

源码仓库

npm 发布地址

安装方式

贡献指南

许可证

其他插件集成说明

`set_timer`

`list_timers`

`cancel_timer`

`timer_history`

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