baa-conductor

commit

0df67e3

parent

1f918b4

author

im_wower

date

2026-03-31 20:14:33 +0800 CST

docs: 浮层统一自动化控制需求 + 系统级暂停需求

 1@@ -0,0 +1,62 @@
 2+# 系统级暂停需求
 3+
 4+> 日期：2026-03-31
 5+> 状态：需求讨论
 6+
 7+## 背景
 8+
 9+当前 conductor 已有系统级 `automation.mode`（running/paused/draining），控制的是整个 BAA 指令处理链路。但续命系统没有全局暂停能力——只能逐个对话暂停。
10+
11+需要一个系统级暂停，一键暂停所有自动化行为。
12+
13+## 当前现状
14+
15+| 控制层级 | BAA 指令 | 续命系统 |
16+|---------|---------|---------|
17+| 系统级 | ✅ running/paused/draining | ❌ 没有全局开关 |
18+| 页面/对话级 | ✅ 暂停本页/恢复本页 | ✅ manual/auto/paused（仅 API） |
19+
20+## 目标
21+
22+增加系统级暂停能力，一键暂停/恢复所有自动化（BAA 指令 + 续命）。
23+
24+## 设计要点
25+
26+### 系统级暂停语义
27+
28+- **系统暂停**：所有 BAA 指令处理停止 + timed-jobs 停止 tick（projector 和 dispatcher 都不执行）
29+- **系统恢复**：BAA 指令处理恢复 + timed-jobs 恢复 tick
30+- 系统暂停不改变各对话的 automation_status，只是在更上层阻断执行
31+- 系统恢复后，各对话按自己的 automation_status 恢复原有行为
32+
33+### 与页面/对话级的关系
34+
35+```
36+系统级暂停 → 全局阻断，不管对话级状态
37+系统级恢复 → 恢复后，对话级状态生效
38+对话级暂停 → 只影响该对话，其他对话不受影响
39+```
40+
41+### 实现方向
42+
43+- 复用现有 `system_state` 表的 `automation` key
44+- timed-jobs runtime 的 `schedule` 回调里检查系统级状态
45+- 如果系统 paused，所有 runner 跳过（已有 `skipped_not_leader` 机制，可类似实现 `skipped_system_paused`）
46+
47+### 控制入口
48+
49+- 浮层里保留系统级控制按钮（当前已有）
50+- REST API：复用现有 `/v1/control/state` 或新增 `/v1/system/pause`、`/v1/system/resume`
51+- 后续可通过 BAA 指令 `@conductor::system::pause` 控制
52+
53+## 验收标准
54+
55+- 系统暂停后，BAA 指令处理和续命同时停止
56+- 系统恢复后，两者按各自状态恢复
57+- 系统暂停不影响各对话的 automation_status
58+- timed-jobs 日志中能看到 `skipped_system_paused` 记录
59+- 浮层能显示系统级暂停状态
60+
61+## 优先级
62+
63+中。当前页面/对话级控制合并是优先项，系统级暂停可以后做。

 1@@ -0,0 +1,92 @@
 2+# 浮层统一自动化控制需求
 3+
 4+> 日期：2026-03-31
 5+> 状态：需求讨论
 6+
 7+## 背景
 8+
 9+当前 Firefox 插件右下角浮层控制的是 BAA 指令处理的暂停/恢复。续命系统的对话自动化状态（manual/auto/paused）完全独立，只能通过 REST API 操作。用户无法从浮层上看到或控制续命行为。
10+
11+这两套自动化本质上都是"这个页面/对话是否允许 conductor 自动处理"，应该合并为一个统一的控制入口。
12+
13+## 当前现状
14+
15+### 浮层控制（content-script.js）
16+
17+- 系统级：`running` / `paused` / `draining`，通过 `control_plane_command` → conductor WS
18+- 页面级：`暂停本页` / `恢复本页`，通过 `page_control_command` → conductor WS
19+- 控制目标：BAA 指令提取和执行
20+
21+### 续命控制（renewal/）
22+
23+- 对话级：`manual` / `auto` / `paused`，通过 REST API `/v1/renewal/conversations/:id/auto`
24+- 控制目标：续命 projector 是否为该对话生成 renewal_job
25+
26+### 问题
27+
28+- 用户暂停本页后，BAA 指令停了，但续命还在跑（如果对话是 auto）
29+- 用户通过 API 设了 renewal auto，但浮层上看不到
30+- 两套"暂停"语义不同但用户无法区分
31+
32+## 目标
33+
34+将 BAA 指令处理和续命自动化合并为一个统一的页面/对话级控制，从浮层一个按钮控制。
35+
36+## 合并后的语义
37+
38+页面/对话级统一自动化状态：
39+
40+- **自动**（auto）：BAA 指令正常处理 + 续命系统正常运行
41+- **暂停**（paused）：BAA 指令暂停 + 续命系统暂停（不生成新任务，待执行任务不推进，执行中任务自然结束）
42+- **手动**（manual）：BAA 指令暂停 + 续命系统不生成任务
43+
44+## 控制入口
45+
46+### 浮层（首要入口）
47+
48+- 当前"暂停本页"/"恢复本页"按钮改为同时控制两套系统
49+- 浮层显示当前对话的统一状态（auto/paused/manual）
50+- 点击切换时，同时更新 page_control 和 renewal automation_status
51+
52+### REST API（保留）
53+
54+- `/v1/renewal/conversations/:id/auto` 等接口保留
55+- 但状态变更需要同步到 page_control，保持一致
56+
57+### BAA 指令（后续）
58+
59+- 后期可以通过 `@conductor::renewal::auto` 等指令控制，但不是当前任务
60+
61+## 实现要点
62+
63+### 插件侧
64+
65+- `content-script.js`：浮层按钮 action 同时发 `page_control_command` 和 renewal 状态切换
66+- `controller.js`：收到统一控制指令后，同时更新 page_control state 和向 conductor 发 renewal 状态变更请求
67+
68+### conductor 侧
69+
70+- `firefox-ws.ts`：收到页面控制指令时，同步更新 `local_conversations.automation_status`
71+- `local-api.ts`：renewal API 状态变更时，同步广播给对应的 WS 连接
72+
73+### 状态同步方向
74+
75+```
76+浮层按钮 → controller → conductor WS → 同时更新 page_control + renewal automation_status
77+REST API → conductor → 广播 WS → controller → 浮层刷新
78+```
79+
80+## 需要注意
81+
82+- 新对话默认 `manual`，用户必须主动设为 `auto` 才会续命
83+- "暂停本页"同时暂停两套系统，"恢复本页"恢复到暂停前的状态
84+- 如果对话还没有 local_conversation 记录（从没有 final-message），浮层只控制 page_control
85+- 系统级暂停（全局暂停所有自动化）不在本需求范围内，见 `SYSTEM_LEVEL_PAUSE_REQUIREMENTS.md`
86+
87+## 验收标准
88+
89+- 浮层点击"暂停本页"后，BAA 指令和续命同时暂停
90+- 浮层点击"恢复本页"后，两者同时恢复
91+- 浮层显示当前对话的统一状态
92+- REST API 修改状态后，浮层能实时反映
93+- 不影响现有 BAA 指令主链路