dsh-schedule-tasks

Readme

# 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。

## 构建命令

```sh
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（加载说明）

```sh
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），那是后续版本方向。