@zhushanwen/pi-scheduler 0.0.5 → 0.1.1

package/README.md

@@ -0,0 +1,175 @@
+# scheduler
+
+定时任务调度扩展：按 duration（`5m` / `2h` / `1d`）间隔或 cron 表达式，在指定时间向 agent 注入消息。支持一次性提醒（once）、强制触发（force）、过期策略（expires）与持久化（重启后任务保留）。
+
+## 简介与安装
+
+pi-scheduler 是 xyz-agent 的 **mandatory 扩展**（`packages/shared/src/mandatory-extensions.json`，tier: `feature`）——xyz-agent 启动时自动安装并启用，无需手动操作。
+
+独立 pi 环境手动安装：
+
+```bash
+npm install @zhushanwen/pi-scheduler
+```
+
+安装后扩展在 pi 会话启动时自动装配（见下节），无需额外配置。
+
+## 激活方式
+
+扩展 factory（`src/index.ts`）监听 pi 的 session 生命周期事件，在 `session_start` 时装配完整调用链：
+
+```
+session_start
+  └─ PiSchedulerBackend（FS 读写 + pi.sendMessage + 时间源）
+       └─ SchedulerRuntime（内存态 + 30s tick 调度 + 限流）
+            └─ SchedulerService（tool/command 唯一业务入口）
+  ├─ runtime.loadTasks(backend.loadTasks())  ← 从磁盘恢复任务
+  ├─ runtime.startScheduler()                ← 启动 tick
+  └─ 注册 scheduler widget（30s 刷新）
+```
+
+`session_shutdown` 时执行 `runtime.persistSync()`（立即写盘）并停止 tick。任务状态因此随 session 持久化：关闭重开 session 后任务仍存在、到期仍会触发。
+
+## /schedule 命令用法
+
+注册为 `/schedule` 命令。无参数时显示 usage；第一个参数匹配子命令关键词则走子命令分支，否则尝试创建任务。
+
+### 子命令
+
+| 子命令 | 行为 |
+|--------|------|
+| `/schedule list` | 列出所有任务（id、名称、调度、下次执行时间） |
+| `/schedule on <id>` | 启用任务 |
+| `/schedule off <id>` | 停用任务（推荐临时暂停用 off，不用 rm） |
+| `/schedule rm <id>` | 删除任务 |
+| `/schedule run <id>` | 立即执行任务 |
+| `/schedule once <schedule> <prompt>` | 创建一次性提醒（kind=once） |
+| `/schedule cron <expression> <prompt>` | 创建 cron 任务 |
+
+任务 id 由 8 位 hex 自动生成，`list` 后从输出中获取。
+
+### 引号转义
+
+参数用 shell 风格引号解析（`tokenizeQuoted`，`src/commands.ts`）：
+
+- 单引号 `'...'` 或双引号 `"..."` 内的内容作为一个 token，引号字符本身被剥离
+- 含空格的多词参数（cron 表达式、prompt）**必须加引号**，否则会被拆成多个 token
+
+例如 cron 表达式 `0 9 * * 1-5` 含空格，必须写成 `'/schedule cron '0 9 * * 1-5' standup'`；prompt `check build` 同理写成 `'/schedule 5m 'check build''`。
+
+### 子命令补全
+
+输入 `/schedule ` 后 Tab 补全子命令关键词（list/on/off/rm/run/once/cron）；`on`/`off`/`rm`/`run` 之后补全当前任务 id。
+
+## schedule 语法
+
+### duration（间隔调度）
+
+`<数字><单位>`，数字与单位间可有空格，**大小写不敏感**：
+
+| 单位 | 含义 | 乘数 |
+|------|------|------|
+| `s` / `sec` / `second` / `seconds` | 秒 | 1,000 ms |
+| `m` / `min` / `minute` / `minutes` | 分 | 60,000 ms |
+| `h` / `hr` / `hour` / `hours` | 时 | 3,600,000 ms |
+| `d` / `day` / `days` | 天 | 86,400,000 ms |
+
+例如：`5m`、`2h`、`1d`、`30seconds`、`2hours`。非法输入（裸数字、未知单位、空串、负值）解析失败 → 创建任务报 `INVALID_SCHEDULE`。
+
+### cron（时间点调度）
+
+标准 cron 表达式，支持 5 字段与 6 字段：
+
+- **5 字段**（分 时 日 月 周）：自动补 `0` 秒字段（如 `0 9 * * 1-5` → `0 0 9 * * 1-5`）
+- **6 字段**（秒 分 时 日 月 周）：原样使用
+
+**含空格自动走 cron 分支**：schedule 输入中不含空格 → 按 duration 解析；含空格 → 按 cron 解析。因此 cron 表达式必须包含空格（正常写法天然如此），duration 不得含空格。
+
+## 选项语义
+
+`schedule` tool 的 `kind` / `name` / `expires` / `force` 参数（`/schedule` 命令的 `once`/`cron` 前缀对应 kind）：
+
+| 选项 | 取值 | 语义 |
+|------|------|------|
+| `kind` | `recurring`（默认）/ `once` | recurring 每次触发后按 schedule 重算下次时间；once 触发一次后自动删除 |
+| `name` | 字符串 | 任务可读名称，缺省从 prompt 自动生成（≤30 字原样，超长截前 27 字加省略号） |
+| `expires` | duration 字符串 / `never` | recurring 任务的过期时间：`now + duration`；`never` 永不过期；缺省 7 天。**once 任务不设过期**（触发即删，expires 忽略） |
+| `force` | `true` / `false`（默认） | `true` 时即使 agent 忙（非 idle 或有 pending 消息）也强制 dispatch；`false` 时忙则延迟到下次 tick |
+
+## 示例
+
+**recurring 间隔任务**（每 5 分钟检查构建）：
+
+```
+/schedule 5m 'check build'
+```
+
+**一次性提醒**（10 秒后提醒）：
+
+```
+/schedule once 10s remind
+```
+
+**cron 任务**（工作日早 9 点站会）：
+
+```
+/schedule cron '0 9 * * 1-5' standup
+```
+
+**force 立即触发**（tool 调用：即使忙也执行）：
+
+```json
+{"prompt": "deploy staging", "schedule": "*/10 * * * *", "force": true}
+```
+
+**永不过期**（tool 调用：长期任务不设 7 天默认过期）：
+
+```json
+{"prompt": "monthly report", "schedule": "1d", "expires": "never"}
+```
+
+## 限制与运行时行为
+
+| 限制/行为 | 值 | 说明 |
+|-----------|-----|------|
+| 任务上限 | **50**（`MAX_TASKS`） | 超过抛 `Task limit reached (50)`，需先删除任务 |
+| 触发频率上限 | **6 次/分钟**（`RATE_LIMIT_PER_MINUTE`） | 滑动 60s 窗口。`/schedule run` 超限返回 `DISPATCH_SKIPPED`；tick 自动 dispatch 超限静默跳过 |
+| tick 间隔 | **30s**（`TICK_INTERVAL_MS`） | 到期任务在下一个 tick 被 dispatch；实际触发时间可能比计划晚最多 30s |
+| 默认过期 | **7 天**（`DEFAULT_EXPIRY_MS`） | recurring 任务缺省 `expires` 时；`expires: 'never'` 关闭 |
+| once 任务 | 触发后自动删除 | 不参与后续调度 |
+| cron 失效 | 任务停用 + `lastStatus=failed` + `lastError='cron expression invalid'` | 不会用 `now()` 兜底导致每 tick 重触发死循环 |
+| persist 失败 | `console.warn` + 内存态保留 + `lastError='persist failed'` | 不打断调度，下次 tick 继续尝试 |
+| 忙时 dispatch | 非 force 任务在 agent 忙（非 idle / 有 pending 消息）时跳过，延迟到下次 tick | force=true 可绕过 |
+| history | 保留最近 **20** 条执行记录 | 超出丢弃最旧 |
+| 持久化 | 每次变更写盘（session_shutdown 强制同步写） | 重启后任务保留 |
+
+错误语义：创建时 schedule 解析失败 → `INVALID_SCHEDULE`；`run`/`toggle`/`delete` 引用不存在的 id → `TASK_NOT_FOUND`；`run` 时任务 disabled / busy / rate-limited → `DISPATCH_SKIPPED`（message 含 `busy, disabled, or rate-limited`）。
+
+## 数据存储位置
+
+任务存储为单个 JSON 文件，按 workspace 路径隔离（不同 cwd 存不同文件）：
+
+```
+~/.pi/agent/scheduler/<root>/<segments>/scheduler.json
+```
+
+- `<root>`：路径根（如 `/` → `root`）
+- `<segments>`：cwd 相对根的路径段（如 `/Users/me/project` → `Users/me/project`）
+
+删除文件即清除全部任务；损坏的 JSON 自动降级为空 store 并 `console.warn`。
+
+## 开发
+
+```bash
+pnpm test          # 运行全部 vitest 测试（等价 npx vitest run）
+npx vitest run src/__tests__/<file>.test.ts   # 单个文件
+```
+
+测试策略：
+
+- **依赖反转**：`SchedulerRuntime` 只依赖 `SchedulerBackend` 接口（`sendMessage` / `persist` / `now`），不触碰 FS/pi。测试注入 `MockSchedulerBackend`（`src/backend.ts` 同文件 export）实现零副作用测试：`sentMessages` 记录发送、`persistedStores` 记录持久化、`persistError` 注入失败、`nowValue` 固定时间源
+- **纯函数**：`parseDuration` / `formatDuration` / `parseSchedule` / `computeNextRunAt` / `computeNextRuns`（`src/parsing.ts`）无副作用，可直接断言
+- **property-based**：`src/__tests__/property.test.ts` 用 fast-check 生成随机组合验证不变量（interval 精确、duration round-trip、format↔parse 一致性），生成器范围契约见该文件注释
+- **round-trip**：`store.test.ts`（mock fs）验证路径与 GC；`store-roundtrip.test.ts`（真实 fs，os.tmpdir 隔离）验证 load 白名单字段（lastError/lastStatus/lastRunAt/expiresAt/force/history）持久化往返
+
+扩展内部结构：`backend.ts`（后端抽象）→ `runtime.ts`（调度核心）→ `service.ts`（业务入口）→ `tool.ts`/`commands.ts`（tool 与 /schedule 命令适配层）→ `widget.ts`（状态栏 widget）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-scheduler",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "type": "module",
   "main": "index.ts",
   "pi": {
@@ -13,6 +13,7 @@
     "pi-package"
   ],
   "devDependencies": {
+    "fast-check": "^4.9.0",
     "vitest": "^4.1.8"
   },
   "files": [
@@ -22,14 +23,14 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@sinclair/typebox": "*",
-    "croner": "^9.0.0"
+    "croner": "^9.0.0",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
-    "@sinclair/typebox": {
+    "typebox": {
       "optional": true
     },
     "croner": {

package/src/__tests__/backend.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+
+import { MockSchedulerBackend } from '../backend.js'
+import { SchedulerRuntime } from '../runtime.js'
+import type { SchedulerStore } from '../types.js'
+
+const mockCtx = { isIdle: () => true, hasPendingMessages: () => false }
+
+describe('MockSchedulerBackend', () => {
+  it('records sendMessage calls', async () => {
+    const backend = new MockSchedulerBackend()
+    await backend.sendMessage(
+      { content: 'hi', customType: 'pi-scheduler:dispatched', display: true },
+      { deliverAs: 'followUp', triggerTurn: true },
+    )
+    expect(backend.sentMessages).toHaveLength(1)
+    expect(backend.sentMessages[0]!.msg).toEqual({
+      content: 'hi',
+      customType: 'pi-scheduler:dispatched',
+      display: true,
+    })
+    expect(backend.sentMessages[0]!.opts).toEqual({ deliverAs: 'followUp', triggerTurn: true })
+  })
+
+  it('records persist calls and throws injected persistError', async () => {
+    const backend = new MockSchedulerBackend()
+    const store: SchedulerStore = { version: 1, tasks: [] }
+
+    await backend.persist(store)
+    expect(backend.persistedStores).toHaveLength(1)
+    expect(backend.persistedStores[0]).toBe(store)
+
+    // persistError 注入：persist 抛该错（ERR-6 语义——错误必须能传到调用栈）
+    backend.persistError = new Error('disk full')
+    await expect(backend.persist(store)).rejects.toThrow('disk full')
+  })
+
+  it('now() returns injected nowValue or Date.now()', () => {
+    const backend = new MockSchedulerBackend()
+    expect(Math.abs(backend.now() - Date.now())).toBeLessThan(1000)
+    backend.nowValue = 123456
+    expect(backend.now()).toBe(123456)
+  })
+
+  // ── TC2：new SchedulerRuntime(mockBackend) 可注入单测，零 FS ──
+
+  it('TC2: SchedulerRuntime with MockSchedulerBackend constructs and dispatches via mock', async () => {
+    const backend = new MockSchedulerBackend()
+    // 构造不抛错（无需 cwd/pi/store mock）
+    const runtime = new SchedulerRuntime(backend, mockCtx)
+    const task = await runtime.addTask('probe', { mode: 'interval', intervalMs: 60000 })
+    expect(task).toBeDefined()
+    // addTask 的 persist 走了 mock backend（零 FS）
+    expect(backend.persistedStores).toHaveLength(1)
+
+    await runtime.dispatchTask(task)
+
+    // dispatch 消息走 mock backend，含 task.prompt
+    expect(backend.sentMessages).toHaveLength(1)
+    expect(backend.sentMessages[0]!.msg.content).toBe('probe')
+    expect(backend.sentMessages[0]!.msg.customType).toBe('pi-scheduler:dispatched')
+  })
+})

package/src/__tests__/commands.test.ts

@@ -1,17 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
+import { MockSchedulerBackend } from '../backend.js'
 import { executeScheduleCommand, registerScheduleCommand } from '../commands.js'
 import { SchedulerRuntime } from '../runtime.js'
+import { SchedulerService } from '../service.js'
 
-// Mock store 避免 FS 副作用（runtime constructor 调 createStore）。
-vi.mock('../store.js', () => ({
-  createStore: () => ({
-    load: () => ({ version: 1, tasks: [] }),
-    persist: vi.fn(),
-    persistSync: vi.fn(),
-    storePath: '/mocked.json',
-  }),
-}))
+// MockSchedulerBackend 零 FS 副作用，无需 mock store.js。
 
 interface CommandOpts {
   description: string
@@ -20,7 +14,7 @@ interface CommandOpts {
 }
 
 describe('/schedule command', () => {
-  let runtime: SchedulerRuntime
+  let service: SchedulerService
   let commandOpts: CommandOpts
 
   beforeEach(() => {
@@ -31,31 +25,29 @@ describe('/schedule command', () => {
         commandOpts = opts
       },
     }
-    runtime = new SchedulerRuntime(
-      '/test',
-      { sendMessage: vi.fn() } as never,
-      { isIdle: () => true, hasPendingMessages: () => false } as never,
+    service = new SchedulerService(
+      new SchedulerRuntime(new MockSchedulerBackend(), { isIdle: () => true, hasPendingMessages: () => false }),
     )
-    registerScheduleCommand(mockPi as never, () => runtime)
+    registerScheduleCommand(mockPi as never, () => service)
   })
 
   // ── 子命令路由：list ──
 
   it('list returns empty message when no tasks', async () => {
-    expect(await executeScheduleCommand(runtime, 'list')).toBe('No scheduled tasks.')
+    expect(await executeScheduleCommand(service, 'list')).toBe('No scheduled tasks.')
   })
 
   it('list returns formatted task lines', async () => {
-    await runtime.addTask('check build', { mode: 'interval', intervalMs: 60000 })
-    const result = await executeScheduleCommand(runtime, 'list')
+    await service.create('check build', '5m')
+    const result = await executeScheduleCommand(service, 'list')
     expect(result).toContain('check build')
-    expect(result).toContain('every 1m')
+    expect(result).toContain('every 5m')
   })
 
   it('list marks disabled tasks with ○', async () => {
-    const task = await runtime.addTask('paused task', { mode: 'interval', intervalMs: 60000 })
-    await runtime.toggleTask(task.id, false)
-    const result = await executeScheduleCommand(runtime, 'list')
+    const created = await service.create('paused task', '5m')
+    await service.toggle(created.data!.task.id, false)
+    const result = await executeScheduleCommand(service, 'list')
     expect(result).toContain('○')
     expect(result).toContain('paused task')
   })
@@ -63,110 +55,114 @@ describe('/schedule command', () => {
   // ── 子命令路由：on / off ──
 
   it('off toggles task enabled to false', async () => {
-    const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-    const result = await executeScheduleCommand(runtime, `off ${task.id}`)
+    const created = await service.create('test', '5m')
+    const result = await executeScheduleCommand(service, `off ${created.data!.task.id}`)
     expect(result).toContain('disabled')
-    expect(runtime.getTask(task.id)?.enabled).toBe(false)
+    expect(service.runtime.getTask(created.data!.task.id)?.enabled).toBe(false)
   })
 
   it('on toggles task enabled to true', async () => {
-    const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-    await runtime.toggleTask(task.id, false)
-    const result = await executeScheduleCommand(runtime, `on ${task.id}`)
+    const created = await service.create('test', '5m')
+    await service.toggle(created.data!.task.id, false)
+    const result = await executeScheduleCommand(service, `on ${created.data!.task.id}`)
     expect(result).toContain('enabled')
-    expect(runtime.getTask(task.id)?.enabled).toBe(true)
+    expect(service.runtime.getTask(created.data!.task.id)?.enabled).toBe(true)
   })
 
   it('off with missing id returns usage', async () => {
-    expect(await executeScheduleCommand(runtime, 'off')).toBe('Usage: /schedule off <id>')
+    expect(await executeScheduleCommand(service, 'off')).toBe('Usage: /schedule off <id>')
   })
 
   it('on with missing id returns usage', async () => {
-    expect(await executeScheduleCommand(runtime, 'on')).toBe('Usage: /schedule on <id>')
+    expect(await executeScheduleCommand(service, 'on')).toBe('Usage: /schedule on <id>')
   })
 
+  // TC5 command 侧：消息同源（service 产出 TASK_NOT_FOUND message）
   it('off with unknown id returns not found', async () => {
-    expect(await executeScheduleCommand(runtime, 'off deadbeef')).toBe('Task deadbeef not found.')
+    expect(await executeScheduleCommand(service, 'off deadbeef')).toBe('Task deadbeef not found.')
   })
 
   // ── 子命令路由：rm ──
 
   it('rm deletes task', async () => {
-    const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-    const result = await executeScheduleCommand(runtime, `rm ${task.id}`)
+    const created = await service.create('test', '5m')
+    const result = await executeScheduleCommand(service, `rm ${created.data!.task.id}`)
     expect(result).toContain('deleted')
-    expect(runtime.getTask(task.id)).toBeUndefined()
+    expect(service.runtime.getTask(created.data!.task.id)).toBeUndefined()
   })
 
   it('rm with missing id returns usage', async () => {
-    expect(await executeScheduleCommand(runtime, 'rm')).toBe('Usage: /schedule rm <id>')
+    expect(await executeScheduleCommand(service, 'rm')).toBe('Usage: /schedule rm <id>')
   })
 
   it('rm with unknown id returns not found', async () => {
-    expect(await executeScheduleCommand(runtime, 'rm deadbeef')).toBe('Task deadbeef not found.')
+    expect(await executeScheduleCommand(service, 'rm deadbeef')).toBe('Task deadbeef not found.')
   })
 
   // ── 子命令路由：run ──
 
   it('run executes task', async () => {
-    const task = await runtime.addTask('test', { mode: 'interval', intervalMs: 60000 })
-    const result = await executeScheduleCommand(runtime, `run ${task.id}`)
+    const created = await service.create('test', '5m')
+    const result = await executeScheduleCommand(service, `run ${created.data!.task.id}`)
     expect(result).toContain('executed')
     // dispatchTask 更新 task 对象（同一引用），runCount 自增到 1。
-    expect(runtime.getTask(task.id)?.runCount).toBe(1)
+    expect(service.runtime.getTask(created.data!.task.id)?.runCount).toBe(1)
   })
 
   it('run with missing id returns usage', async () => {
-    expect(await executeScheduleCommand(runtime, 'run')).toBe('Usage: /schedule run <id>')
+    expect(await executeScheduleCommand(service, 'run')).toBe('Usage: /schedule run <id>')
   })
 
   it('run with unknown id returns not found', async () => {
-    expect(await executeScheduleCommand(runtime, 'run deadbeef')).toBe('Task deadbeef not found.')
+    expect(await executeScheduleCommand(service, 'run deadbeef')).toBe('Task deadbeef not found.')
   })
 
   // ── 创建任务分支 ──
 
   it('creates interval task from /schedule 5m check build', async () => {
-    const result = await executeScheduleCommand(runtime, '5m check build')
+    const result = await executeScheduleCommand(service, '5m check build')
     expect(result).toContain('check build')
     expect(result).toContain('every 5m')
-    expect(runtime.listTasks()).toHaveLength(1)
+    expect(service.runtime.listTasks()).toHaveLength(1)
   })
 
   it('created interval task is recurring by default', async () => {
-    await executeScheduleCommand(runtime, '5m check build')
-    const task = runtime.listTasks()[0]!
+    await executeScheduleCommand(service, '5m check build')
+    const task = service.runtime.listTasks()[0]!
     expect(task.kind).toBe('recurring')
   })
 
   it('creates once task from /schedule once 10s remind', async () => {
-    const result = await executeScheduleCommand(runtime, 'once 10s remind me')
+    const result = await executeScheduleCommand(service, 'once 10s remind me')
     expect(result).toContain('remind me')
+    // once 显示为 'once in 10s'（非误导性的 'every 10s'）
+    expect(result).toContain('once in 10s')
+    expect(result).not.toContain('every 10s')
     // once 任务 dispatch 后会被删除，但创建时尚未 dispatch
-    expect(runtime.listTasks()).toHaveLength(1)
-    const task = runtime.listTasks()[0]!
+    expect(service.runtime.listTasks()).toHaveLength(1)
+    const task = service.runtime.listTasks()[0]!
     expect(task.kind).toBe('once')
   })
 
   // Quote-aware tokenizer 修复后，cron 'expr' 能正确提取整个表达式。
   it('creates cron task from quoted expression', async () => {
-    const result = await executeScheduleCommand(runtime, "cron '*/10 * * * *' prompt")
+    const result = await executeScheduleCommand(service, "cron '*/10 * * * *' prompt")
     expect(result).toContain('created')
     expect(result).toContain('*/10 * * * *')
-    expect(runtime.listTasks()).toHaveLength(1)
+    expect(service.runtime.listTasks()).toHaveLength(1)
   })
 
   it('creates cron task from double-quoted expression', async () => {
-    const result = await executeScheduleCommand(runtime, 'cron "0 9 * * 1-5" standup reminder')
+    const result = await executeScheduleCommand(service, 'cron "0 9 * * 1-5" standup reminder')
     expect(result).toContain('created')
     expect(result).toContain('0 9 * * 1-5')
-    expect(runtime.listTasks()).toHaveLength(1)
+    expect(service.runtime.listTasks()).toHaveLength(1)
   })
 
   // Unquoted multi-token cron still fails -- tokenizer cannot distinguish cron fields from prompt.
   // Users should quote the cron expression or use the schedule tool (JSON params are unambiguous).
   it('cron branch fails on unquoted multi-token expression (use quotes)', async () => {
-    const result = await executeScheduleCommand(runtime, 'cron */10 * * * * prompt')
+    const result = await executeScheduleCommand(service, 'cron */10 * * * * prompt')
     expect(result).toMatch(/^Invalid schedule:/)
     expect(result).toContain('*/10')
   })
@@ -174,21 +170,21 @@ describe('/schedule command', () => {
   // ── 错误分支 ──
 
   it('invalid schedule returns error message', async () => {
-    const result = await executeScheduleCommand(runtime, 'invalid-duration-str')
+    const result = await executeScheduleCommand(service, 'invalid-duration-str')
     expect(result).toMatch(/invalid|usage/i)
   })
 
   it('schedule with no prompt returns usage', async () => {
-    const result = await executeScheduleCommand(runtime, '5m')
+    const result = await executeScheduleCommand(service, '5m')
     expect(result).toBe('Usage: /schedule <schedule> <prompt>')
   })
 
   it('no args returns TUI not-implemented message', async () => {
-    const result = await executeScheduleCommand(runtime, '')
+    const result = await executeScheduleCommand(service, '')
     expect(result).toContain('not yet implemented')
   })
 
-  it('returns error when runtime is null', async () => {
+  it('returns error when service is null', async () => {
     expect(await executeScheduleCommand(null, 'list')).toBe('Scheduler not initialized: session not started.')
   })
 
@@ -215,7 +211,8 @@ describe('/schedule command', () => {
   })
 
   it('completes task ids after on/off/rm/run', async () => {
-    const task = await runtime.addTask('mytask', { mode: 'interval', intervalMs: 60000 })
+    const created = await service.create('mytask', '5m')
+    const task = created.data!.task
     // 注意：路由要求 parts.length >= 2 才进 task-id 分支（'on ' 单 token 进子命令分支）。
     // 当前实现对部分输入的 id 不做过滤，返回所有 task id。
     const completions = commandOpts.getArgumentCompletions(`on ${task.id.slice(0, 2)}`) as Array<{ label: string; description: string }>
@@ -224,7 +221,7 @@ describe('/schedule command', () => {
     expect(completions.find(c => c.label === task.id)?.description).toContain('mytask')
   })
 
-  it('returns null for completion when runtime missing and prefix has 2 tokens', () => {
+  it('returns null for completion when service missing and prefix has 2 tokens', () => {
     const mockPi = {
       registerCommand: (_name: string, opts: CommandOpts) => {
         commandOpts = opts

package/src/__tests__/cron.test.ts

@@ -58,11 +58,10 @@ describe('computeNextCronRuns', () => {
 })
 
 describe('parseSchedule (cron 分支)', () => {
-  it('5 字段 cron 表达式补秒字段并附带 note', async () => {
+  it('5 字段 cron 表达式补秒字段（note 不再透传到 parseSchedule 结果）', async () => {
     const result = await parseSchedule('*/10 * * * *')
     expect(result).toEqual({
       spec: { mode: 'cron', cronExpression: '0 */10 * * * *' },
-      note: 'Auto-prepended seconds field (0)',
     })
   })
 

package/src/__tests__/format.test.ts

@@ -9,6 +9,13 @@ describe('formatSchedule', () => {
     expect(formatSchedule({ mode: 'interval', intervalMs: 3_600_000 })).toBe('every 1h')
   })
 
+  it('formats once kind as "once in X" (not misleading "every X")', () => {
+    expect(formatSchedule({ mode: 'interval', intervalMs: 300_000 }, 'once')).toBe('once in 5m')
+    expect(formatSchedule({ mode: 'interval', intervalMs: 3_600_000 }, 'once')).toBe('once in 1h')
+    // recurring/缺省保持 every
+    expect(formatSchedule({ mode: 'interval', intervalMs: 300_000 }, 'recurring')).toBe('every 5m')
+  })
+
   it('formats cron spec', () => {
     expect(formatSchedule({ mode: 'cron', cronExpression: '*/10 * * * *' })).toBe('*/10 * * * *')
   })
@@ -83,6 +90,34 @@ describe('formatDuration', () => {
     expect(formatDuration(90_000)).toBe('90s')
     expect(formatDuration(1500)).toBe('2s')
   })
+
+  // TC7 边界值：最大单位整除优先（300000 → '5m' 而非 '300s'）
+  it('prefers largest unit when ms is evenly divisible', () => {
+    expect(formatDuration(300_000)).toBe('5m')
+    expect(formatDuration(3_600_000)).toBe('1h')
+    expect(formatDuration(86_400_000)).toBe('1d')
+    expect(formatDuration(60_000)).toBe('1m')
+    expect(formatDuration(1000)).toBe('1s')
+  })
+
+  it('handles zero and negative as 0s', () => {
+    expect(formatDuration(0)).toBe('0s')
+    expect(formatDuration(-1)).toBe('0s')
+    expect(formatDuration(-86_400_000)).toBe('0s')
+  })
+
+  // TC7 修正（design-review R1）：1500000 % 60000 === 0 → '25m'（最大单位优先），
+  // 而非 design 初稿误写的 '1500s'。非整除大单位落秒用例改用 1510000。
+  it('prefers even minute when ms is multiple of 60000 (1500000 → 25m)', () => {
+    expect(formatDuration(1_500_000)).toBe('25m')
+  })
+
+  it('falls back to seconds for large non-divisible values (1510000 → 1510s)', () => {
+    // 1510000 % 60000 = 10000 ≠ 0 → 不整除 m，落秒分支
+    expect(formatDuration(1_510_000)).toBe('1510s')
+    // 1500001 % 1000 ≠ 0 → Math.round 兜底
+    expect(formatDuration(1_500_001)).toBe('1500s')
+  })
 })
 
 describe('generateTaskId', () => {

package/src/__tests__/parsing.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest'
 
 import {
+  computeNextCronRunAt,
+  computeNextCronRuns,
+  computeNextRunAt,
   computeNextRuns,
   formatDuration,
   normalizeCronExpression,
@@ -130,6 +133,32 @@ describe('parseSchedule', () => {
   })
 })
 
+describe('computeNextRunAt', () => {
+  it('interval 模式 → from + intervalMs（精确相等）', async () => {
+    const from = Date.now()
+    const next = await computeNextRunAt({ mode: 'interval', intervalMs: 60_000 }, from)
+    expect(next).toBe(from + 60_000)
+  })
+
+  it('interval 模式 from 缺省用当前时间', async () => {
+    const before = Date.now()
+    const next = await computeNextRunAt({ mode: 'interval', intervalMs: 60_000 })
+    expect(next!).toBeGreaterThanOrEqual(before + 60_000)
+  })
+
+  it('cron 有效 → 返回未来时间戳（> from）', async () => {
+    const from = Date.now()
+    const next = await computeNextRunAt({ mode: 'cron', cronExpression: '*/10 * * * *' }, from)
+    expect(next).not.toBeUndefined()
+    expect(next!).toBeGreaterThan(from)
+  })
+
+  it('cron 无效 → undefined', async () => {
+    const next = await computeNextRunAt({ mode: 'cron', cronExpression: 'invalid * *' }, Date.now())
+    expect(next).toBeUndefined()
+  })
+})
+
 describe('computeNextRuns', () => {
   it('computes interval runs', async () => {
     const from = Date.now()