baa-conductor

T-S057.md

  1# Task T-S057：定时任务框架与执行日志
  2
  3## 状态
  4
  5- 当前状态：`已完成`
  6- 规模预估：`M`
  7- 依赖任务：`T-S055`
  8- 建议执行者：`Codex`
  9
 10## 直接给对话的提示词
 11
 12读 `/Users/george/code/baa-conductor/tasks/T-S057.md` 任务文档，完成开发任务。
 13
 14如需补背景，再读：
 15
 16- `/Users/george/code/baa-conductor/plans/discuss/DISCUSS-TIMED-JOBS-RENEWAL-REQUIREMENTS.md`
 17- `/Users/george/code/baa-conductor/tasks/T-S055.md`
 18
 19## 当前基线
 20
 21- 仓库：`/Users/george/code/baa-conductor`
 22- 分支基线：`main`
 23- 提交：`071abbf`
 24
 25## 分支与 worktree（强制）
 26
 27- 分支名：`feat/timed-jobs-framework`
 28- worktree 路径：`/Users/george/code/baa-conductor-timed-jobs-framework`
 29
 30开工步骤：
 31
 321. `cd /Users/george/code/baa-conductor`
 332. `git worktree add ../baa-conductor-timed-jobs-framework -b feat/timed-jobs-framework main`
 343. `cd ../baa-conductor-timed-jobs-framework`
 354. 在这个 worktree 目录里开发，不要回到主仓库目录
 36
 37完成后提交与推送：
 38
 391. 在 worktree 里提交所有变更（包括更新后的任务文档）
 402. `git push -u origin feat/timed-jobs-framework`
 41
 42合并步骤（由合并者执行）：
 43
 441. `cd /Users/george/code/baa-conductor`
 452. `git fetch origin`
 463. `git merge origin/feat/timed-jobs-framework`
 474. `git push`
 485. `git worktree remove ../baa-conductor-timed-jobs-framework`（如果 worktree 还在）
 49
 50合并冲突处理：
 51
 521. 如果 `git merge` 报冲突，先 `git diff` 查看冲突文件
 532. 手动解决冲突后 `git add` 冲突文件
 543. `git merge --continue` 完成合并
 554. 不要用 `git merge --abort` 然后 force 覆盖
 56
 57命名规则：
 58
 59- 功能任务分支名以 `feat/` 开头
 60- 缺陷任务分支名以 `bug/` 开头
 61
 62## 目标
 63
 64为续命系统建立独立的定时任务框架，提供 leader-only 周期调度、批量扫描配置和统一外部日志写入能力。
 65
 66## 背景
 67
 68当前 `ConductorDaemon` 有 lease / heartbeat loop，但没有正式的后台定时任务模块。续命实现已经明确不直接复用现有 `tasks/runs`，而是要有一个轻量的 timed-jobs 模块。
 69
 70## 涉及仓库
 71
 72- `/Users/george/code/baa-conductor`
 73
 74## 范围
 75
 76- 新建 timed-jobs 模块
 77- 接入 leader-only 调度
 78- 支持可配置扫描周期、批量限制、settle delay
 79- 为后续 projector / dispatcher 提供共享日志能力
 80
 81## 路径约束
 82
 83- 这一步不实现具体业务扫描逻辑，只搭框架和日志基建
 84- 尽量将新代码放在独立目录，不要把 loop 逻辑散落到 `index.ts`
 85- 执行日志必须写外部文件，不只打 stderr
 86
 87## 推荐实现边界
 88
 89建议优先做：
 90
 91- 新建 `apps/conductor-daemon/src/timed-jobs/`
 92- `apps/conductor-daemon/src/index.ts` 只做最小接线
 93
 94## 允许修改的目录
 95
 96- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
 97- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/timed-jobs/`
 98- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 99
100## 尽量不要修改
101
102- `/Users/george/code/baa-conductor/packages/`
103- `/Users/george/code/baa-conductor/plugins/`
104- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
105
106## 必须完成
107
108### 1. timed-jobs 框架
109
110- 提供独立模块来注册和执行后台定时任务
111- 只允许 leader 节点执行周期扫描
112- 支持统一 tick 上下文和 runner 命名
113
114### 2. 配置项
115
116- 支持扫描周期可配置
117- 支持每轮最大消息数、最大任务数可配置
118- 支持消息 settle delay 可配置
119- 默认值对齐当前讨论稿：周期 `5-10 秒`、每轮约 `10` 条
120
121### 3. 外部日志
122
123- 定时任务执行过程写入外部 JSONL 日志
124- 至少记录时间、runner、批次标识、阶段、结果、耗时、错误
125- 日志目录在 conductor 启动时创建
126
127## 需要特别注意
128
129- 这一步不要把 projector / dispatcher 业务规则写死
130- 日志写入失败不能影响主流程
131- loop 需要有 start/stop 生命周期，不能泄漏定时器
132- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
133
134## 验收标准
135
136- conductor 启动后 timed-jobs 框架可初始化
137- standby 节点不会执行 runner
138- 能生成外部 JSONL 日志文件
139- 后续任务可以在这个框架上挂 projector / dispatcher
140
141## 推荐验证命令
142
143- `cd /Users/george/code/baa-conductor-timed-jobs-framework && pnpm build`
144- `cd /Users/george/code/baa-conductor-timed-jobs-framework && pnpm -C apps/conductor-daemon test`
145
146## 执行记录
147
148> 以下内容由执行任务的 AI 填写，创建任务时留空。
149
150### 开始执行
151
152- 执行者：`Codex`
153- 开始时间：`2026-03-30 15:39:12 CST`
154- 状态变更：`待开始` → `进行中`
155
156### 完成摘要
157
158- 完成时间：`2026-03-30 15:55:05 CST`
159- 状态变更：`进行中` → `已完成`
160- 修改了哪些文件：
161  - `apps/conductor-daemon/src/timed-jobs/runtime.ts`
162  - `apps/conductor-daemon/src/timed-jobs/index.ts`
163  - `apps/conductor-daemon/src/index.ts`
164  - `apps/conductor-daemon/src/index.test.js`
165  - `tasks/T-S057.md`
166- 核心实现思路：
167  - 新建 `timed-jobs/` 独立模块，提供 runner 注册、leader-only 调度门禁、统一 tick context、start/stop 生命周期和防重入 tick 执行
168  - 为 timed-jobs 增加可配置的扫描周期、消息/任务批量限制、settle delay，并接入 `conductor` 现有 CLI/env 配置解析与日志目录初始化
169  - 增加外部 JSONL 日志写入能力，统一记录 framework/runner 的 batch、阶段、结果、耗时和错误，日志失败只做 stderr 告警不影响主流程
170  - 在 `ConductorRuntime` 中做最小接线，启动时创建 timed-jobs 日志目录并初始化模块，关闭时先停 timed-jobs 再停 daemon/local API，避免定时器泄漏
171  - 用测试覆盖 leader 执行、standby 跳过、日志落盘、定时器清理、CLI 配置解析和 runtime 启动初始化
172- 跑了哪些测试：
173  - `cd /Users/george/code/baa-conductor-timed-jobs-framework && pnpm install`
174  - `cd /Users/george/code/baa-conductor-timed-jobs-framework && pnpm -C apps/conductor-daemon test`
175  - `cd /Users/george/code/baa-conductor-timed-jobs-framework && pnpm build`
176
177### 执行过程中遇到的问题
178
179- 新 worktree 初始没有安装依赖，第一次 `pnpm -C apps/conductor-daemon test` 失败于 `pnpm exec tsc` 找不到；补跑一次 `pnpm install` 后恢复正常构建和测试流程
180
181### 剩余风险
182
183- 当前框架只提供基础调度和共享日志能力，还没有默认挂载 projector / dispatcher runner；后续 `T-S058` / `T-S059` 需要在这个模块里注册具体业务 runner