前言¶

DeepSeek Harness (dsh) 是一个基于插件的工作流框架。在开发智能体或管理自动化任务时，经常需要系统在后台、独立于当前会话地执行特定指令。dsh-cron 是一个针对 DeepSeek Harness 的无人值守定时作业插件，支持在 cron 表达式、固定间隔或一次性即时时刻触发任务。

与依赖会话的持久化提醒不同，dsh-cron 属于主机端调度：任务属于不与交互会话绑定的后台进程，只要 dsh 进程运行，任务就会自动触发。

核心功能¶

该插件提供了以下核心能力：

1. 三种触发方式

   • cron：支持 5 字段标准表达式及显式 IANA 时区。
   • everySeconds：基于锚点对齐的固定间隔，最小间隔为 60 秒。
   • at：支持 RFC3339 格式的单次触发时间。

2. 三种任务类型

   • agent：创建无头代理，通过完整 dsh 工具链执行提示词。
   • command：直接在主机上 spawn 子进程，记录退出码和输出尾部。
   • callback：调用已注册的插件回调函数。

3. 三种声明方式

   • 通过 Profile Config 进行声明性配置。
   • 通过 Runtime Overlay（侧边栏 + 或会话命令）声明。
   • 通过其他插件调用 cron 服务进行注册。

4. 可靠性保障

   • 状态持久化存储在 ctx.storage.domain（domain 名为 cron）。
   • 语义为 at-most-once，即在执行前持久化 lastFiredMs。
   • 支持时钟纪律：长等待会被分块处理，防止时钟跳跃导致触发异常。

5. 策略配置

   • overlap：当上一任务未结束时，选择 skip（跳过）、queue（排队）或 replace（替换）。
   • misfire：当进程挂起期间错过的触发，选择 skip（忽略）或 runOnce（仅执行一次）。

安装与启用¶

通过以下两种方式之一安装插件：

1. 使用命令行安装¶

dsh plugin --profile web add https://github.com/squirrel20/dsh-cron/releases/latest/download/dsh-cron.tgz

2. 使用插件市场¶

安装 dsh-market 后，进入 Settings → Plugin Market，搜索 dsh-cron 并安装。

安装后，需将 "dsh-cron" 添加到 dsh.profile.bundles 配置中才能生效。

任务声明方式¶

插件支持在配置文件中声明持久化任务，或在运行时动态创建。

通过 Profile Config 声明¶

在 Profile 的 cordis.patch.yml 中声明，适合声明性、版本化的常驻任务：

- id: dsh-cron
  config:
    historyLimit: 50
    jobs:
      - name: daily-log-review
        schedule: { cron: "0 7 * * *", timeZone: "Asia/Shanghai" }
        task:
          kind: agent
          prompt: Read yesterday's logs under logs/, summarize anomalies.
          cwd: /path/to/project
          timeoutSeconds: 1800
        policy: { overlap: skip, misfire: skip }
        delivery:
          argv: ["/usr/local/bin/notify", "--stdin"]
          onlyOnFailure: true
      - name: heartbeat
        schedule: { everySeconds: 3600 }
        task: { kind: command, argv: ["./scripts/heartbeat.sh"], cwd: /path/to/project }
    sessionGc:
      enabled: true
      graceMinutes: 30

注意：配置错误（如重复名称、无效表达式）会在挂载时立即报错，不会静默失败。

通过插件服务声明¶

在其他插件中，可以通过 ctx.cron.registerJob 动态注册任务。

安全与权限¶

重要：Cron 任务属于主机管理，不属于沙盒扩展。执行任务的工具需要 danger-full-access 权限策略和 never 审批策略。预设名称不能单独授权，未解析的权限策略会导致执行失败。

Web 写入控制¶

若需要通过 Web UI 操作，必须设置 webControlToken，且长度至少为 32 个字符。该 Token 用于 Authorization: Bearer <webControlToken> 头部验证。

生成 Token 示例：

openssl rand -hex 32

注意事项：
* Web 写入需要 HTTPS 连接。
* 配置声明和插件注册被视为受信任的主机声明，命令和交付命令在主机上执行。
* 现有手动作业如果没有匹配授权记录会被隔离（requiresApproval: true），需编辑并保存以授权。

适用场景与注意事项¶

• 适用场景：需要定期执行的日志分析、健康检查、定时通知推送、定时数据同步等后台任务。
• 依赖项：插件依赖 zod 及多个 DeepSeek Harness 相关库，安装时需注意版本兼容区间。
• 生态背景：该插件由社区维护，目录页位于 skillhub.cn。