dsh-timer

DSH PLUGIN工具与能力

仓库 xuan25/dsh-timer

工具与能力 L4 · 沙盒安装通过 安全审查:低风险 可信度:银 可安装插件
安装这个插件

dsh-timer 是 xuan25 维护的 工具与能力 类 DSH 可安装插件, 仓库为 xuan25/dsh-timer,许可证 MIT。 下面按「装什么、怎么装、验没验过、跑起来要注意什么」逐项列出。

一句话选型结论

按资料字段整理

dsh-timer 是工具与能力类的 DSH 可安装插件,验证等级 L4 · 沙盒安装通过,安全审查为低风险,有可直接复制的安装命令。验证通过不等于安全:插件会读写文件、执行命令或联网,装前先到仓库确认它做了什么;涉及密钥或系统权限的,建议先在隔离环境试装。

分类工具与能力 收录类型可安装插件 验证等级L4 · 沙盒安装通过 安全审查低风险
验证等级 L4 L4 · 沙盒安装通过
GitHub 星标 0 复刻 0 · 未关闭 issue 0
最近更新 2026-10-17 创建于 2026-09-29
README 17.4 KB 正文体量,越大说明说明书写得越细

安装

可安装插件
在 DSH 里执行,装完用 dsh plugin list 确认已挂上;标了 L4 / L5 的命令已在沙盒里真实跑通
dsh plugin --profile web add github:xuan25/dsh-timer
  1. 1
    确认版本与运行环境

    仓库没有标注兼容版本与 Node.js 要求,先确认你的 DSH 版本能装,再继续。

  2. 2
    执行安装命令

    在 DSH 里执行上面的命令;多包仓库要注意区分具体子包名,别装错包。

  3. 3
    确认已挂载

    用 dsh plugin list 查看列表里是否出现这个插件,出现即挂载成功。

  4. 4
    试跑并检查权限

    加载后跑一个最小用例,确认它能正常工作;同时看它申请了哪些文件、命令或网络权限。

兼容 DSH 版本未标注版本不匹配时安装会报错
Node.js 要求未标注来自仓库 package.json 的 engines 字段
前置依赖无需要同时安装的同级依赖
npm 包名未发布到 npm可用 npm view 查看包信息

能做什么

工具与能力
字段来自项目仓库与公开索引,中文说明由本站标注

适用场景

智能体编排

上游标签

dsh-plugin

验证等级与安全审查

L4 · 沙盒安装通过
自动化流程结论,不是人工审核
验证等级L4 · 沙盒安装通过安装命令在隔离沙盒内真实执行成功,无依赖错误
安全审查低风险静态分析结论,未标注不代表已通过审查
仓库健康度活跃按仓库活跃度与最近更新时间给出
可信度银综合仓库活跃度与验证结果

选择建议

装之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 验证等级 L4:在沙盒里真实装过,依赖能装上,不是纸面声明。
  • 静态安全审查为低风险,没有发现明显可疑行为。
  • 有可直接复制的安装命令,不用自己翻文档找入口。

先想清楚的地方

  • 没有声明 Node.js 版本要求,版本不匹配可能装不上。
  • 验证通过不等于安全:插件会读写文件、执行命令或联网,装前先到仓库确认它做了什么。

更适合

  • 需要在工具与能力场景里给 DSH 补能力的人。
  • 想装完就能用、不想自己排依赖的人。
  • 能接受在本地装依赖、愿意自己确认权限的人。

不太适合

  • 只使用 DSH 官方内置能力、不接受第三方插件的人。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
插件验证等级安全审查星标兼容版本安装命令
dsh-timer当前 L4 · 沙盒安装通过 低风险 0 未标注 有
huashu-design 未做沙盒验证 未标注 3.0 万 未标注 有
loopx 未做沙盒验证 未标注 6,233 未标注 无
agy-staff 未做沙盒验证 未标注 870 未标注 有
dsh-startup-screen 未做沙盒验证 未标注 633 未标注 有
minara-skills L4 · 沙盒安装通过 中风险 360 未标注 有

仓库档案

工具与能力
字段来自项目仓库与公开索引,中文说明由本站标注
作者 / 维护方xuan25仓库 dsh-timer · 默认分支 master
分类工具与能力agents
收录类型可安装插件声明了 dsh.bundle、可用 dsh plugin add 安装的条目
开发语言未标注仓库主语言
许可证MIT商用或二次分发前请确认条款原文
星标 / 复刻 / issue0 / 0 / 0收录时的数值,非实时
创建 / 更新2026-09-29 · 2026-10-17最后推送 2026-10-17
本站收录2026-10-30首次进入本站目录的时间

README 全文

17.4 KB
作者原文,中文版优先;只做安全转义,不改内容

dsh-timer

dsh-timer gives a dsh deployment a built-in job scheduler: when a trigger expires the plugin starts a fresh prompted session, so recurring work - daily reports, periodic checks, one-shot tasks - runs on schedule inside the dsh process.

  • Jobs live in a job directory, written by hand or with the nine-verb timer tool
  • Three trigger kinds: cron expressions and one-shot ISO times, intervals counted from the last run, and one-shot startup delays
  • Each run is a fresh prompted session with a configurable working directory, preset, model, file policy, and reasoning effort
  • A per-job state file tracks the next trigger and the 50 most recent run records
  • systemd.timer-style behavior: persistent catch-up after downtime, overlap policies (skip/stop/allow), run-time limits, timezone and clock-rewind handling
  • Live rescan: the job directory is watched with a 500 ms debounce, so job edits take effect in seconds
  • Session offload: a per-minute sweep archives settled run sessions that outlived the job's run.sessionRetention window, keeping the framework session store bounded

This README is the operations quick reference. The complete field reference with examples is schemas/job.schema.json; usage details, examples, and troubleshooting live in the in-package skill skill/dsh-timer/SKILL.md.

Installation

dsh-timer is an out-of-tree plugin for a dsh profile. Install it with the dsh plugin command:

dsh plugin --profile  add dsh-timer

No configuration is required: the plugin registers itself and reads jobs from the job directory described below. One optional plugin config field refines the deployment's layout: jobsDir (the job directory, below). Its only other on-disk state is the session offload's retention log and archive under $DSH_HOME/dsh-timer/ (see Session offload).

Jobs

Job directory

The plugin resolves the job directory in the following order:

  1. Explicit candidates, in this order: the jobsDir plugin config value, then the environment variable DSH_TIMER_JOBS_DIR. If a designated candidate is unavailable, the plugin start fails hard.
  2. The default directory /timers, used only when no candidate is designated, where profileDir is the dsh profile directory that hosts the plugin. The profile is detected from the plugin's install location, or - when the plugin lives outside any install tree - from the running process's harness home ($DSH_HOME, resolved through the framework-provided dshHomePath service) by the framework's dsh-profile- profile naming; exactly one profile must be found. If the resulting directory is unavailable, the plugin writes a log entry and starts degraded: no jobs are loaded and no state is persisted until the directory is fixed and reloaded.
  3. If no candidate is designated and no unique profile can be determined (zero or multiple profiles found, or the host does not provide the harness-home service), the plugin start throws; the error points at the explicit overrides from item 1, plus a jobsDir entry in the profile's cordis.patch.yml (a !!js loader expression, e.g. dshHomePath('profiles','','timers'), shown below). A development directory that lives outside the profile must be designated through candidate 1.

The last channel above can be written as a loader expression. A !!js value in a plugin config is a YAML scalar tagged with the loader-expression tag: when the plugin entry activates, the loader evaluates the expression in a scope where every framework service - including dshHomePath, the harness-home path resolver - is available as an identifier, and the expression's result replaces the value:

# /cordis.patch.yml - pin the job directory from the profile layer
- id: dsh-timer
config:
jobsDir: !!js dshHomePath('profiles', '', 'timers')

Here ` is the profile directory name under the harness home. A patch entry replaces the wholeconfig` key of the targeted entry; dsh-timer's default config is empty, so the example sets the field it needs.

Run root

A job's run root is the working directory its run session is created in, and - under the plugin's privilege model - the job's control scope: a session outside that root (and below full access) manages the job only through the approval channel. The run root is the spec's explicit run.cwd; an add without one inherits the creating session's workspace itself (`) and persists the inherited value into the job file, so a job created through the plugin always carries its run root in its own file. A job whose spec sets norun.cwdhas an undetermined run root: managing it fails closed through the approval channel, and its runs failcreate_failedwith the actionable remedy (setrun.cwd` in the job file).

The plugin ships no host-absolute run path of its own: every run root is either the caller's session fact or the spec's own explicit value.

The directory layout is as follows:

Path (relative to the job directory) Content
.json one job per file; the in-file enable field decides whether the job is active (absent or true = enabled, false = disabled; a disabled job keeps living in the same file)
state/.json the job's runtime state (see "State file" below); only the plugin writes it
a job file that fails to parse or fails validation the id is rejected and the reason is reported in status; the plugin keeps no last-good state
any other file name or subdirectory ignored and never rejected

A job id must match ^[a-z0-9][a-z0-9-]{0,63}$ - a lowercase letter or a digit first, then up to 63 lowercase letters, digits, or hyphens.

The plugin watches the job directory with a 500 ms debounce and rescans on any change; the reload verb of the timer tool forces the same rescan. A job that is disabled, or whose spec becomes invalid, while a run is in progress keeps its state file, so fixing the spec restores the job's run history.

Job file fields

The table below is a quick reference; see schemas/job.schema.json for the complete field descriptions with examples. The three trigger fields each accept a null value meaning that trigger is not used, and at least one trigger field must be non-null.

Field Type Default Semantics
enable boolean true When false, the job is stored disabled in the same file: it is never scheduled, but it can still be run manually and re-enabled by flipping the field.
onCalendar string[] or null - Each entry is a 5/6-field cron expression (strict cron parsing, recurring) or a full ISO instant (one-shot).
onActiveSec time span or null - Counted from the last activation, which is the most recent run's start moment.
onStartupSec time span or null - Counted from process start and fires once per process.
timeZone IANA timezone name the system timezone Overrides the system timezone for the job; applies only to calendar conditions. Ambiguous local times (DST folds) resolve to the first occurrence; a one-shot ISO instant inside a DST gap is rejected.
persistent boolean false When true, if a trigger was due while the process was down or the job disabled, the plugin fires exactly one catch-up run after recovery, rebased to the current moment, and re-arms from the actual trigger moment. The missed interval is not persisted.
deferReactivation boolean false Applies only to jobs that have onCalendar conditions (on other jobs the value is accepted and ignored). When true, a condition that starts a run is suspended for the duration of that run (its due moments are skipped without advancing the phase) and is re-armed from the run end moment. When false, the phase advances at every due moment even while a run is in progress.
runtimeMaxSec time span, 0, infinity, or null no limit A run that exceeds the limit is cancelled and recorded as failed with cause timeout.
overlap skip, stop, or allow skip Defines what happens when a trigger fires while a run is already in progress. skip consumes the trigger in place (the phase advances at the due moment and no catch-up fire happens after the run ends - a run longer than the interval swallows grid points); stop cancels the in-progress run first and then starts; allow starts a parallel run.
run object (required) - The run block. prompt is required and non-empty; cwd, preset, model, policy, sessionRetention, and reasoningEffort are optional - full field semantics in schemas/job.schema.json (run-cwd inheritance is covered in the Run-root section above; sessionRetention is covered in the Session-offload section below; reasoningEffort is a closed set off/minimal/low/medium/high/xhigh/max validated at load, absent or null = the framework's provider default).

Time spans use the systemd syntax: the units us/usec, ms/msec, s/sec/second(s), m/min/mins/minute(s), h/hour(s), d/day(s), w/week(s), M/month(s) (approx. 30 days), y/year(s) (approx. 365 days) - case-sensitive (m is minutes, M is months) - where a bare number means seconds and units may be combined (for example 30s, 5min, 1h30min, or 2d). The *Sec field names follow the systemd time directive names; a Sec field value is a span string (or null where the field tolerates it) - a JSON number is never accepted. A span shorter than half a millisecond rounds to 0 ms and makes the job fire on every tick; prefer values of at least 1 ms.

State file

The plugin persists each job's runtime state in /state/.json using atomic, best-effort writes with a stable key order; explicit null keys are preserved. The file format is schemas/state.schema.json:

{
"schemaVersion": 1,
"jobId": "example",
"lastActivationMs": 1727200000000,     // most recent run start moment (null when never run; the onActiveSec base then falls back to process start)
"lastTriggerMs": 1727100000000,        // job-level last on-calendar elapse (fire or overlap=skip consume; the phase anchor for the next elapse)
"calendars": {                            // indexed by onCalendar value
"0 9 * * 1-5": {
"value": "0 9 * * 1-5",
"kind": "cron",                       // cron | iso
"neverMatch": false,
"consumed": false,                     // true after a one-shot ISO has fired
"nextFireMs": 1727300000000
}
},
"runs": [ /* most recent 50, FIFO */ ]
}

A run record inside runs has the following keys:

Key Meaning
runId the unique identifier of the run
sessionId the dsh session that executed the run
trigger which condition fired: scheduled (a calendar condition), monotonic (onActiveSec), startup (onStartupSec), or manual (the run verb)
startedAt / finishedAt epoch milliseconds; the run's start and end moments
status running while the run is in progress, then finished or failed
cause null for a finished run; the value is set only on failure: timeout, cancelled, interrupted, create_failed, or turn_error
durationMs the run's elapsed duration in milliseconds
summary a summary of the run, truncated to 2000 characters
error the error text when the run failed

finished only records that the turn ended cleanly; it does not claim that the task succeeded - the outcome lives in summary and the session transcript. A job that has never run reports no run in status (recent run: none (no runs yet) in the detail, last run: none (no runs yet) on the overview line).

Managing timers

The plugin registers the timer tool, which exposes the following nine verbs, and the dsh-timer skill:

Verb Effect
reload rescans the job directory
status (id optional) shows an overview or a single job's detail
run triggers the job manually once (allowed for disabled jobs too; unconditional start)
enable sets the in-file enable field to true (the onStartupSec already-fired flag is preserved via in-process memory)
disable sets the in-file enable field to false, cancelling the job's in-progress runs first (= disable --now)
add creates a job; rejects if the id already exists (delete the job first to replace it) or if the spec is invalid
update replaces the spec of an existing job in place; rejects if the id is unknown (use add) or if the spec is invalid; the job's state file is preserved
delete deletes the job file and its state file (in-progress runs settle without writing state)
cancel cancels all in-progress runs of the job

Session offload

Job runs leave on-disk session logs in the framework session store; at run volume (frequent intervals, long prompts) the store grows without bound. The per-minute offload sweep archives settled run sessions once the job's effective retention window elapses, so the store stays bounded: the store is never deleted, only moved, a run that is still in flight is kept until it settles, and a job that vanishes from the job directory is offloaded immediately regardless of age.

  • Windows: run.sessionRetention is per-job (config layer: the job file's run block, hot-updated through the live rescan): a non-negative integer number of milliseconds, or a duration string of 1-2 digits+unit segments (units d/h/m/s/ms) in descending order (e.g. 24h, 4h30m, 90s, 5000ms; a bare numeric string is invalid). 0 / null / absent = the unit default (see below; no offload when it is 0); an invalid value warns and is treated as 0. A job without a run.cwd is never offloaded (its runs fail create_failed first).
  • Unit default window: TIMER_SESSION_RETENTION (env, read once at boot; a duration string like 24h - a bare numeric string is invalid; absent = 0, invalid warns and falls back to 0) sets the default retention window for every job without an explicit run.sessionRetention (absent or null); an explicit job value always takes precedence over it.
  • Budget: TIMER_OFFLOAD_BATCH (env, default 50) bounds the sessions one sweep may process; an invalid value warns and falls back to 50, never disabling the sweep. When consecutive sweeps observe new log lines arriving faster than the budget, the sweep logs a trend warning (raise the knob or lower the retention windows; the warning takes no action on its own).
  • Failure semantics: an unreachable persistence service, a missing store root, or an archive on a different mount disables the sweep for that round (a visible warning; log lines are never lost); a failed individual move keeps the entry for the next round.

Clock & timezone

During operation the plugin detects the following wall-clock events:

Event Detection Effect
clock rewind the wall clock lags the monotonic clock by more than 1 s between two consecutive ticks all trigger times are recomputed from the new current moment
system timezone change the mtime of /etc/localtime changes calendar conditions without a job-level timeZone are recomputed under the new timezone; if the new timezone cannot be decoded, the plugin keeps the old timezone and writes a log entry

Development

The package is written in TypeScript using only the erasable syntax subset (no enums, namespaces, parameter properties, or decorators), so Node 24 can run the output with plain type stripping. The tsc build compiles src/ into lib/ as ESM (NodeNext resolution, strict mode).

Layout

Path Content
src/ the TypeScript source
lib/ the compiled output, shipped with the package
schemas/ the machine-readable contracts: job.schema.json (job file) and state.schema.json (state file)
skill/ the in-package skill
test/selftest.mjs the pure-logic selftest
test/smoke.mjs the framework-path smoke (tool schema validation, skill provider); needs the peer packages installed
test/schema-gate.mjs the ajv-based schema gate (both schemas compiled as draft 2020-12, positive/negative cases including the structural trigger rule); uses an ajv 8 build that supports draft 2020-12, probed from the host toolchain (the DSH_HOME env, then the default host install location) rather than the package's own dependency tree

Plugin entry

The package entry is lib/index.js. Its default export DshTimerPlugin extends the cordis Service and follows the class-form plugin contract: static name, static inject, static Config (a schemastery schema that exposes ~standard.validate), and an instance async *[Service.init]() generator that yields the disposer first and then starts the scheduler.

Scripts

Command Purpose
npm run build compiles src/ into lib/ with tsc
npm run typecheck runs tsc --noEmit
npm run lint runs eslint src/ (flat config + @typescript-eslint, including the type-aware no-floating-promises rule)
npm run selftest runs the selftest described below

Selftest

The selftest asserts the pure logic (util, time, cron, rearm, validator, and state) plus the croner test vectors against the compiled lib/, covers the session-offload plane (window parsing, retention-log mechanics, the sweep's window/liveness/budget/trend semantics, the run-lifecycle write gate, and the layout pin), and cross-checks the timer tool schema's null branches against schemas/job.schema.json as a source-level sync guard.

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
dsh-timer 怎么安装?

在 DSH 里执行 `dsh plugin --profile web add github:xuan25/dsh-timer` 即可。

dsh-timer 的验证等级是什么意思?

L4 · 沙盒安装通过。安装命令在隔离沙盒内真实执行成功,无依赖错误

dsh-timer 安全吗?

低风险。

dsh-timer 装之前要先确认什么?

先看它会读写哪些文件、执行哪些命令、连接哪些网络地址;验证等级只说明装得上、跑得起来,不等于安全。涉及密钥或系统权限的,建议先在隔离环境试装。

dsh-timer 用的是什么许可证?

上游标注为 MIT。商用或二次分发前请到仓库确认许可证原文。

这条记录的数据可靠吗?

本站按仓库名去重后合并整理,字段以作者仓库与 npm 元数据为准;安装命令、仓库地址与 README 保持原文,带 L4 / L5 标记的安装命令已在隔离沙盒里真实跑通。

同名或近似条目

1 条
不同作者的仓库分开列,请确认你要装的是哪一个
工具与能力
按星标排序,可作替代方案

huashu-design

huashu-design

在 DeepSeek Harness 里说一句话,就能拿回可交付的设计:网页、App 原型、可编辑 PPTX、动画与信息图,自带 84 种风

未标注验证等级 3.0 万 星

loopx

loopx

LoopX 是面向长周期 Agent 的本地优先控制平面,作为 DSH plugin 为 DeepSeek Harness 提供持久目标、证

未标注验证等级 6,233 星

agy-staff

agy-staff

把 Google Antigravity CLI 作为快速 Gemini 员工接入 DSH,提供子代理侧边栏、编排模式与多种角色技能。

未标注验证等级 870 星

dsh-startup-screen

dsh-startup-screen

DeepSeek Harness 的启动界面与启动动画插件。

未标注验证等级 633 星

dsh-blender-plugin

dsh-blender-plugin

让 AI 模型通过直连 TCP 通道实时驱动 Blender 的 DSH plugin:15 个工具覆盖视口取帧、任意角度渲染、内循环搜索、

未标注验证等级 211 星

xuan25 的其它插件

6 个

插件的元信息来自作者仓库;分类、验证等级与安全结论的中文说明为中文整理,最近核验 —。