dsh-schedule-tasks 定时任务插件

为 DeepSeek Harness（DSH）Web GUI 提供标准 cron 调度 + 任务管理面板的外部插件：

• 调度：自研 5 段式 cron 解析（分 时 日 月 周）+ ctx.timer 调度循环（base bundle 已装 cordis-plugin-timer），本地时间语义。
• 触发动作（第一版）：
  • shell：在宿主机器上执行一条 shell 命令（/bin/sh -c，可配超时与工作目录，输出截断记录）。
  • notify：站内通知（记录一条通知型执行日志，面板可见）。
• 持久化：storage-domain 域 schedule_tasks（storage-json → $DSH_HOME/storages/，原子写，崩溃安全）。
• UI：Web 侧边栏底部（Settings 旁）sidebar.footer.action 槽按钮 + 浮层面板，支持任务列表（名称/cron/状态/下次触发/上次结果）、新建/编辑/启停/删除/手动触发/执行日志（每任务环形缓冲）。
• 通信：宿主 ScheduleTasksGateway extends TypertRemoteService（scheduleTasks Remote 命名空间）；浏览器端手写 strict-codec 贡献经 ctx.remote.$mount 挂载；第一版 UI 轮询（面板打开时每 5s），不改仓库事件白名单。

目录结构

schedule-tasks/
├── package.json            # dsh.bundle.patch + dsh.client(web) + exports[./client]
├── cordis.patch.yml        # 组合层补丁：insert schedule-tasks 插件行（含部署配置）
├── tsconfig.json           # host 编译（排除 src/client）
├── tsconfig.client.json    # client 编译（jsx: react-jsx）
├── tsdown.config.ts        # client bundle 构建（复刻仓库 tsdown.client.ts 协议）
├── src/
│   ├── index.ts            # host 入口：默认导出 ScheduleTasksGateway 服务类
│   ├── gateway.ts          # ScheduleTasksGateway：Remote + 调度循环 + shell/notify 执行器
│   ├── cron.ts             # cron 解析与下次触发计算（纯函数、零依赖）
│   ├── spec.ts             # storage-domain 域声明（zod schema）
│   ├── types.ts            # 共享类型（host/client 双 program，零 import）
│   └── client/
│       ├── index.tsx       # 浏览器入口：挂载 Remote 贡献 + 注册 sidebar.footer.action
│       ├── remote.ts       # 手写 scheduleTasks Remote 贡献（strict zod codec + 类型化命名空间）
│       ├── store.ts        # 任务列表快照源（single-flight 轮询读）
│       ├── face.ts         # 槽注入面（hooks + on* 回调）
│       ├── ScheduleTasksPanel.tsx / .module.css   # 面板组件（--dsw-* tokens）
│       └── locales.ts      # 中英文案 + LocaleNamespaceMap 声明
└── scripts/
    ├── link-dsh.mjs        # 开发期把 DSH checkout 包符号链接进 node_modules（类型解析）
    └── verify.mjs          # 离线冒烟验证（cron/schema/bundle/清单）

环境要求

• Node ≥ 22、pnpm ≥ 10。
• @deepseek-ai/* 包不发布到公共 registry（pre-release），开发期构建需要
  DSH 源码 checkout（默认 /Volumes/aigo/work/deepseek-harness，可用环境变量
  DSH_CHECKOUT 覆盖）。构建工具链（tsdown/typescript/lightningcss/react/zod）
  来自公共 registry。

构建命令

pnpm install          # 安装工具链（.npmrc 关闭 peer 自动安装）
pnpm prepare:links    # 符号链接 DSH checkout 包（或 DSH_CHECKOUT=/path pnpm prepare:links）
pnpm typecheck        # 双 program 类型检查（host + client）
pnpm build            # tsc host → tsc client → tsdown（产出 lib/client.js）
pnpm verify           # 离线冒烟验证（无需 DSH 实例）

产物：lib/index.js（host 入口，default export 服务类）、lib/client.js
（浏览器 CJS closure-factory：window.__ModuleLoader__.load({ id: "dsh-schedule-tasks", ... })，react 等走模块表 external，zod 已内联）、
lib/types/（类型声明）。

安装到 profile（加载说明）

pnpm build
dsh plugin --profile web add /Volumes/aigo/work/dsh-vendor/schedule-tasks
# 重启该 profile（manifest/bundles/client 元数据进程内缓存，需重启生效）

dsh plugin add 把包 pnpm 装入 profile 并对账进 dsh.profile.bundles 层；
cordis.patch.yml 的 insert 行把插件挂进组合。重启后：

1. 侧边栏底部 Settings 旁出现「⏱ 定时任务」按钮（wide 显示文字与启用数，rail 只显示图标）。
2. 面板打开后每 5s 轮询宿主 scheduleTasks/list；新建/编辑/启停/删除/手动触发即时生效。
3. 数据落在 $DSH_HOME/storages/schedule_tasks/（storage-json 原子写）。

浏览器验证：DevTools 检查 /plugins/dsh-schedule-tasks/client.js 返回 200，
window.__DSH_BOOT__ 名册含 dsh-schedule-tasks。

部署配置（cordis.patch.yml → 插件 Config）

键	默认	说明
maxLogsPerTask	20	每任务保留的最近执行日志条数（环形缓冲）
shellTimeoutMs	60000	shell 命令执行超时（毫秒），超时按失败记录
allowShell	true	是否允许 shell 触发动作；false 时 shell 型任务创建/触发被拒绝（权限护栏）
tickIntervalMs	30000	调度循环检查间隔（毫秒，最小 1000）
workDir	''	shell 命令工作目录；空串继承宿主进程 cwd

设计要点

1. RPC 链路（外部插件无 typert 生成物）：宿主网关没有 typert-generator
   生成的 typert.host.js 时，Typert 网关对 scheduleTasks/* 走 src-claims
   回退（collectSrcClaims + src-json codec，参数名从方法源码解析）。因此：
   • Remote 方法签名必须是简单标识符（统一单一 request 对象参数）；
   • 浏览器端 $mount 强制 strict codec，故手写贡献带 zod schema（zod 纯库内联进 bundle）；
   • 两端的 namespace/method/wire 必须逐字一致（已用离线脚本核对编译产物）。
2. 调度：ctx.timer.interval 每 tickIntervalMs 检查一次；命中且未在运行即触发。
   重启后从当前时刻重算 nextRunAt，不补跑错过的触发（避免重启风暴）；手动触发可补跑。
3. 并发：每任务一把运行锁（running Set）防重叠触发；存储写路径全局串行
   （promise 链），与 message-feedback 的 enqueue 模式一致。
4. 持久化：storage-domain（storage-json backend）域表 tasks，值即完整任务
   记录（含日志环形缓冲），写入原子发布。
5. 前端：React 18 + CSS Modules（--dsw-* 语义 token，无字面色值）；数据经
   槽注入面 hooks（HostObservable 快照源）+ on* 回调，组件不碰 ctx；连接重置
   （connection/reset）清空重读；面板打开才轮询，避免空转。
6. 安全：shell 动作受 allowShell 配置闸门；命令执行在宿主机器上运行
   （t4 的确认/白名单流程是后续关注点，第一版以配置开关 + 日志留痕兜底）。

已知限制（第一版）

• cron 不支持 L / W / #（Quartz 扩展），遇到即报错；支持 * ? a a-b */n a-b/n a,b,c 与周字段英文名。
• 宿主→浏览器不推送事件（不改仓库 API_REMOTE_FORWARDED_EVENTS 白名单），面板轮询 5s。
• 无 settings 页（settings 暴露需改仓库 apiproxy allowlist），配置/数据都在侧边栏面板管理。
• 未做 shell 命令的二次确认/命令白名单（权限护栏后续任务）。
• 触发动作不含“唤起 DSH agent 会话”（headless prompt），那是后续版本方向。