baa-conductor

WATCHDOG_LOGGING_ENHANCEMENT.md

 1# 看门狗日志增强需求
 2
 3> 日期：2026-03-31
 4> 优先级：`低`（当前续命主力已切到 API 代理方式，watchdog 仅作兜底脚手架）
 5> 状态：`需求记录`
 6> 来源：原 `T-S060`，降级为需求文档
 7
 8## 背景
 9
10仓库 `tools/watchdog/` 下有两个脚本：
11
12- `watchdog.sh`：轮询心跳文件，判断是否需要续命
13- `a11y_msg.sh`：通过 macOS 辅助功能 API（osascript）操控 Safari 发消息
14
15这是早期的 GUI 续命方案（V1），依赖 Claude 手动设心跳状态。当前续命主力已切到 conductor renewal（API 代理方式：projector + dispatcher + Firefox proxyDelivery），watchdog 降为兜底脚手架。
16
17## 当前问题
18
19### `a11y_msg.sh`
20
211. 没有调用开始日志
222. 标签页未找到时不报错，直接继续执行无效的粘贴+回车
233. osascript 失败被 `2>/dev/null` 静默吞掉，退出码始终为 0
244. 无法区分失败原因（参数缺失 / 标签页未命中 / 按键失败 / TCC 权限拒绝）
25
26### `watchdog.sh`
27
281. Python 解析心跳文件失败时（`ST="error"`），主循环没有显式 FAIL 日志
292. CHECK 日志已比较完整，续命后也记录了 `a11y_rc`，这部分基本到位
30
31## 需求
32
33### 1. `a11y_msg.sh` 日志增强
34
35- 记录 START 日志（标签页名 + 消息摘要）
36- 检查 osascript 切标签页的返回值，区分"matched"和"not found"
37- 标签页未命中时 exit 非零，不继续执行粘贴
38- osascript 按键操作失败时记录错误并 exit 非零
39- 保持成功路径的退出码为 0
40
41### 2. `watchdog.sh` 错误日志
42
43- Python 解析失败（`ST="error"`）时写显式 FAIL 日志行
44- 其余 CHECK/RENEWAL 日志已到位，无需大改
45
46### 3. 不改变 v4 状态机语义
47
48- 保留 `renewed` 超时重试逻辑
49- 不清空 `wake_at` / `max_wake_at`
50- 不引入旧版 `origin/feat/watchdog-logging` 分支的状态机回退
51
52## 允许修改的目录
53
54- `tools/watchdog/`
55
56## 为什么优先级低
57
58- 续命主力已切到 conductor renewal（API 代理），不依赖 watchdog
59- watchdog 仅在 conductor 链路完全断裂时作为最后保险
60- 当前 watchdog 功能正常，只是出错时排障困难
61- 不阻塞任何主线功能
62
63## 关联
64
65- 原任务卡：`T-S060`（已撤回）
66- watchdog V1 代码：`tools/watchdog/watchdog.sh`、`tools/watchdog/a11y_msg.sh`
67- watchdog V2 设计：[`WATCHDOG_V2_CONDUCTOR_INTEGRATED.md`](./WATCHDOG_V2_CONDUCTOR_INTEGRATED.md)（事件驱动方案，同样搁置）
68- 续命主力：`apps/conductor-daemon/src/renewal/`（projector + dispatcher）