baa-conductor

commit

bbded8a

parent

e4e3f32

author

im_wower

date

2026-03-22 12:09:42 +0800 CST

Remove HA and historical artifacts

   1@@ -1,2738 +1,156 @@
   2 # BAA Conductor 实施设计说明
   3 
   4-## 0. 文档状态
   5+## 1. 当前目标
   6 
   7-本文档是新 conductor 系统的实施基线。
   8+`baa-conductor` 现在只维护一条最小可运行路径：
   9 
  10-## 0.1 当前有效部署决策
  11+- `mini` 是唯一长期运行节点
  12+- `mini` 负责 conductor、status-api、自启动与本地日志
  13+- `control-api.makefile.so` 负责 Cloudflare Worker + D1 控制面
  14+- `conductor.makefile.so` 作为公网入口，经 VPS Nginx 回源到 `mini`
  15+- 浏览器控制面来自 [`plugins/baa-firefox`](./plugins/baa-firefox)
  16 
  17-从 `2026-03-22` 起，当前有效目标已经简化为：
  18+历史的主备切换、failover、switchback、多节点公网入口已经从当前主线删除。需要回看旧设计时，使用 tag `ha-failover-archive-2026-03-22`。
  19 
  20-- 只保留 `mini` 作为唯一中控
  21-- 只保留 `mini` 的自启动、控制面、运行态检查与公网入口
  22-- 不再继续推进 `mac` 备主、planned failover、emergency failover、switchback
  23+## 2. 当前拓扑
  24 
  25-下面保留的主备/failover 内容，视为历史设计记录，不再是当前执行目标。
  26+### 控制面
  27 
  28-它的细节深度是按“多个 Codex worker 读完就能并行开工”来写的。
  29+- `control-api.makefile.so`
  30+- Cloudflare Worker
  31+- D1 作为控制平面数据库
  32 
  33-本文档定义了：
  34+控制面承担：
  35 
  36-- 系统目标
  37-- 拓扑结构
  38-- 域名与转发布局
  39-- 历史上的 `mini` / `mac` 主备切换行为
  40-- Cloudflare D1 控制平面设计
  41-- task 与 step 模型
  42-- `planner`、`conductor`、`worker` 的职责边界
  43-- Codex 执行约定
  44-- 日志、checkpoint 与恢复机制
  45-- Firefox 插件集成方式
  46-- 建议的仓库结构
  47-- 建议的并行开发拆分
  48+- 系统模式读写
  49+- controller heartbeat
  50+- 任务、step、run 的元数据存储
  51+- 浏览器面板和 CLI 的统一接口
  52 
  53-如果代码与本文档不一致，要么更新代码以符合本文档，要么明确修订本文档。
  54+### 执行面
  55 
  56-## 1. 总体目标
  57+- `mini`
  58+- Tailscale IP: `100.71.210.78`
  59+- 本地 conductor: `http://100.71.210.78:4317`
  60+- 本地 status-api: `http://100.71.210.78:4318`
  61 
  62-构建一个稳定的 AI 执行系统，具备以下特征：
  63+### 公网入口
  64 
  65-- `mini` 是唯一长期运行的 conductor。
  66-- `mini` 承担自启动、控制面、本地状态面和浏览器控制集成。
  67-- 如需额外开发机或临时 worker，视为辅助资源，不再纳入主备设计目标。
  68-- 人类只使用一个可见的 Claude `control` 对话。
  69-- 自动化使用一个隐藏的 Claude `dispatch` 通道。
  70-- task 真相存储在共享数据库中。
  71-- 进度恢复依赖 checkpoint，而不是试图复活已死亡的进程。
  72+- `https://conductor.makefile.so`
  73+- VPS Nginx 反向代理到 `100.71.210.78:4317`
  74 
  75-整个系统围绕一个简单原则展开：
  76+### 浏览器控制面
  77 
  78-**恢复 task 进度，而不是恢复 Codex 进程内存。**
  79+- Firefox 插件代码位于 [`plugins/baa-firefox`](./plugins/baa-firefox)
  80+- 浏览器通过 `control-api` 读取系统状态
  81+- 浏览器通过 `pause / resume / drain` 接口控制自动化
  82 
  83-## 2. 现有基础组件
  84+## 3. 组件职责
  85 
  86-当前环境已经有三个关键基础组件。
  87+### `apps/control-api-worker`
  88 
  89-### 2.1 `baa-hand`
  90+- Cloudflare Worker 入口
  91+- 负责 D1 读写
  92+- 对浏览器、CLI 和 conductor 暴露统一 HTTP API
  93 
  94-当前职责：
  95+### `apps/conductor-daemon`
  96 
  97-- AI 路由
  98-- `POST /ask`
  99-- `POST /chat`
 100-- `POST /plan`
 101+- `mini` 本地常驻进程
 102+- 负责 heartbeat、租约续约、最小调度循环和只读探针
 103+- 对外暴露：
 104+  - `/healthz`
 105+  - `/readyz`
 106+  - `/rolez`
 107+  - `/v1/runtime`
 108 
 109-当前优点：
 110+### `apps/status-api`
 111 
 112-- 能调 Claude
 113-- 能调 Codex
 114-- Codex 和 Claude 网页版都能用它
 115+- `mini` 本地状态读取面
 116+- 面向浏览器或人类查看
 117+- 默认监听本地或显式指定的 `100.x`
 118 
 119-当前限制：
 120+### `apps/worker-runner`
 121 
 122-- 现在的 Codex 集成是面向进程的，不是面向 task 的
 123-- 它会等到进程退出后再返回
 124-- 它还不是一个可持久恢复的 step worker runtime
 125+- 本地 step 执行器
 126+- 负责本地目录、日志、checkpoint 落盘
 127 
 128-结论：
 129+## 4. 部署约束
 130 
 131-- 继续用 `baa-hand` 走 planner 和 review 路径
 132-- 不要把当前 `baa-hand -> codex exec -> 等进程退出` 这条路径当成最终的 durable worker 模型
 133+- 只保留 `mini` 单节点
 134+- 不依赖 MagicDNS
 135+- 内网地址直接写 Tailscale `100.x`
 136+- 外网只暴露 `control-api.makefile.so` 与 `conductor.makefile.so`
 137+- 当前不要求 Cloudflare proxy；DNS-only 也可接受
 138 
 139-### 2.2 `baa-shell`
 140+## 5. Runtime 目录
 141 
 142-当前职责：
 143+默认仓库路径建议：
 144 
 145-- shell 命令执行
 146-- 文件读写
 147-- task 报告
 148+- `/Users/george/code/baa-conductor`
 149 
 150-结论：
 151+默认 runtime 目录：
 152 
 153-- 它仍然适合远程操作流和外部自动化
 154-- conductor 在 HTTP 执行比直连 SSH 或本地 exec 更方便时，可以调用它
 155+- `state/`
 156+- `runs/`
 157+- `worktrees/`
 158+- `logs/`
 159+- `tmp/`
 160 
 161-### 2.3 Firefox 插件
 162+这些目录由 [`scripts/runtime/bootstrap.sh`](./scripts/runtime/bootstrap.sh) 初始化。
 163 
 164-当前职责：
 165+## 6. 自启动
 166 
 167-- 拦截 Claude 网页流量
 168-- 已有常驻 controller 概念
 169-- 可以承载可见的自动化状态与控制按钮
 170-
 171-结论：
 172-
 173-- 用它接可见的 `control` 会话
 174-- 增加全局 `pause`、`resume`，可选 `drain`
 175-- 不要让浏览器状态成为真相来源
 176-- 浏览器按钮必须写入 conductor 控制平面
 177-
 178-## 3. 设计原则
 179-
 180-### 3.1 Durable 真相必须在 AI 进程之外
 181-
 182-真相不能放在：
 183-
 184-- 浏览器标签页
 185-- Codex 进程
 186-- 临时 Claude 会话
 187-- Node.js 进程内存中的 map
 188-
 189-真相必须放在：
 190-
 191-- Cloudflare D1
 192-- 本地 run 目录
 193-
 194-### 3.2 Codex 是 Worker，不是 Conductor
 195-
 196-Codex 可以：
 197-
 198-- 在被要求时参与规划任务
 199-- 执行某个 step
 200-- 总结结果
 201-
 202-Codex 不可以：
 203-
 204-- 持有 lease
 205-- 持有队列真相
 206-- 持有调度真相
 207-- 直接改全局状态
 208-
 209-### 3.3 Planner 是抽象角色
 210-
 211-`planner` 是角色，不是固定实现方。
 212-
 213-planner 可以是：
 214-
 215-- 确定性的模板
 216-- Claude dispatch
 217-- Codex
 218-- 未来单独的 planner 模块
 219-
 220-是否使用 planner、是否接受 planner 输出，由 conductor 决定。
 221-
 222-### 3.4 Conductor 必须是确定性基础设施
 223-
 224-conductor 是 daemon，不是聊天会话。
 225-
 226-conductor 必须负责：
 227-
 228-- task 创建归一化
 229-- step 拆分结果验收
 230-- lease 逻辑
 231-- worker 分配
 232-- heartbeat 检查
 233-- timeout 处理
 234-- checkpoint 写入
 235-- 恢复
 236-
 237-### 3.5 Step 边界就是恢复边界
 238-
 239-每个 task 都要拆成多个 step。
 240-
 241-每个 step 都必须：
 242-
 243-- 有边界
 244-- 可观察
 245-- 可 checkpoint
 246-- 可重试或可终止
 247-
 248-## 4. 系统角色
 249-
 250-## 4.1 Human
 251-
 252-人只需要做这些事：
 253-
 254-- 使用一个可见的 Claude `control` 对话
 255-- 查看当前状态
 256-- 暂停、恢复或 drain 自动化
 257-- 做高层决策
 258-
 259-人不应该需要盯着 Codex 终端界面。
 260-
 261-## 4.2 `control`
 262-
 263-这是人类交互使用的可见 Claude 对话。
 264-
 265-职责：
 266-
 267-- 讨论策略
 268-- 创建 task
 269-- 查看状态
 270-- 请求暂停或恢复
 271-- 审查进展
 272-
 273-规则：
 274-
 275-- `control` 是交互界面
 276-- `control` 不是任务队列
 277-- `control` 不是 durable 状态存储
 278-
 279-## 4.3 `dispatch`
 280-
 281-这是隐藏的 Claude 自动化通道。
 282-
 283-职责：
 284-
 285-- 提供 planning 支持
 286-- 提供 review 支持
 287-- 输出结构化结果
 288-
 289-规则：
 290-
 291-- `dispatch` 不面向用户
 292-- `dispatch` 不能做 durable 真相来源
 293-- `dispatch` 只能给 proposal，不能直接做最终状态迁移
 294-
 295-## 4.4 `planner`
 296-
 297-职责：
 298-
 299-- 把目标转换成一个建议的 step plan
 300-
 301-输入：
 302-
 303-- task 目标
 304-- repo
 305-- 约束
 306-- 验收条件
 307-- 可选的当前 repo 状态
 308-
 309-输出：
 310-
 311-- 结构化 plan JSON
 312-- 拆分理由
 313-- 风险标记
 314-
 315-规则：
 316-
 317-- planner 输出只是建议
 318-- conductor 在持久化之前必须校验 planner 输出
 319-
 320-## 4.5 `conductor`
 321-
 322-职责：
 323-
 324-- leader lease 管理
 325-- task 归一化
 326-- plan 验收
 327-- step 调度
 328-- worker 监管
 329-- timeout 执行
 330-- 日志索引
 331-- checkpoint
 332-- 故障切换与恢复
 333-
 334-## 4.6 `worker`
 335-
 336-职责：
 337-
 338-- 执行且只执行一个 step
 339-- 输出本地日志
 340-- 返回结果
 341-- 退出
 342-
 343-默认 AI worker 是 Codex。
 344-
 345-Shell 和 Git 类 step 可以由 shell runner 执行，而不是由 Codex 进程执行。
 346-
 347-## 5. 拓扑结构
 348-
 349-## 5.1 节点
 350-
 351-### `mini`
 352-
 353-角色：
 354-
 355-- 主 conductor
 356-- 本地 worker 宿主机
 357-
 358-运行：
 359-
 360-- conductor daemon
 361-- worker runner
 362-- 可选本地 status API
 363-- 可选 Firefox 自动化栈
 364-
 365-### `mac`
 366-
 367-角色：
 368-
 369-- 备用 conductor
 370-- 本地 worker 宿主机
 371-
 372-运行：
 373-
 374-- standby conductor daemon
 375-- worker runner
 376-- 可选本地 status API
 377-
 378-### `vps`
 379-
 380-角色：
 381-
 382-- 入口与反向代理
 383-
 384-运行：
 385-
 386-- Nginx
 387-- TLS 终止，或 Cloudflare origin 代理支持
 388-
 389-VPS 不持有 leader 真相。
 390-
 391-### `cloudflare`
 392-
 393-角色：
 394-
 395-- D1 数据库
 396-- 可选 Worker 形式的 control API
 397-- DNS 与自定义域名
 398-
 399-## 5.2 数据路径
 400-
 401-### 控制平面
 402-
 403-- human -> 可见 Claude `control`
 404-- `control` -> conductor control API
 405-- conductors -> D1
 406-- workers -> conductors
 407-
 408-### 执行平面
 409-
 410-- conductor -> 本地 worker 进程
 411-- conductor -> 本地 shell 与 git 命令
 412-- conductor -> `baa-hand` 做 planning 或 review
 413-- conductor -> `baa-shell` 在 HTTP 远程执行更方便时使用
 414-
 415-### 浏览器平面
 416-
 417-- Firefox 插件 -> control API 做 pause 与 resume
 418-- Firefox 插件 -> 可见状态 badge
 419-- Firefox 插件 -> 如有需要，访问隐藏 `dispatch`
 420-
 421-## 6. 域名、二级域名与内网地址布局
 422-
 423-本节定义推荐的双通道布局：
 424-
 425-- 公网流量走二级域名，经 VPS Nginx 转发
 426-- 内网与节点间流量直接走 Tailscale `100.x` 地址
 427-
 428-这里明确不依赖 MagicDNS 名称。
 429-
 430-原因：
 431-
 432-- 当前环境里 ClashX 会和 MagicDNS 产生 DNS 接管冲突
 433-- 即使 tailnet 已开启 MagicDNS，也不把 `*.ts.net` 作为生产配置依赖
 434-- 内网配置统一写死到 Tailscale IPv4 地址，避免本机 DNS 状态影响运行
 435-
 436-## 6.1 必需的公网域名
 437-
 438-### `conductor.makefile.so`
 439-
 440-用途：
 441-
 442-- conductor API 的统一公网入口
 443-- 指向 VPS Nginx
 444-- Nginx 再转发到 `mini` 主、`mac` 备
 445-
 446-使用方：
 447-
 448-- 人类工具
 449-- Firefox 插件控制动作
 450-- 诊断请求
 451-
 452-### `mini-conductor.makefile.so`
 453-
 454-用途：
 455-
 456-- 经 VPS 直达 mini，便于调试和维护
 457-
 458-### `mac-conductor.makefile.so`
 459-
 460-用途：
 461-
 462-- 经 VPS 直达 mac，便于调试和维护
 463-
 464-### `control-api.makefile.so`
 465-
 466-用途：
 467-
 468-- 绑定到 D1 的 Cloudflare Worker 自定义域
 469-- durable 控制状态的规范写入口
 470-
 471-名字可以不同，但设计上要求有一个稳定的、前置 D1 的 HTTP API 域名。
 472-
 473-## 6.2 必需的内网地址
 474-
 475-当前推荐直接使用这些 Tailscale 地址：
 476-
 477-- `mini` -> `100.71.210.78`
 478-- `mac` -> `100.112.239.13`
 479-- `racknerd-ff37952` -> `100.68.201.85`
 480-
 481-用途：
 482-
 483-- `mini <-> mac` 的节点间控制流量
 484-- conductor 到 peer conductor 的探活、状态读取、受保护节点 API
 485-- worker、status、运维脚本等内部调用
 486-- VPS Nginx 到 mini/mac 的 upstream 回源
 487-
 488-规则：
 489-
 490-- 生产配置中不写 `mini.tail0125d.ts.net`
 491-- 生产配置中不写 `mbp.tail0125d.ts.net`
 492-- 不要求业务机器开启 `accept-dns`
 493-- 只要求它们加入同一个 tailnet 且 `100.x` 地址可达
 494-
 495-如果未来 Tailscale 地址变化：
 496-
 497-- 先更新中央配置
 498-- 再更新 VPS Nginx upstream
 499-- 最后重载相关进程
 500-
 501-## 6.3 现有域名
 502-
 503-这些域名已经存在，继续沿用：
 504-
 505-- `led.makefile.so` -> `baa-hand`
 506-- `s.makefile.so` -> `baa-shell`
 507-
 508-## 6.4 推荐 DNS 策略
 509-
 510-- `conductor.makefile.so` -> VPS 公网 IP
 511-- `mini-conductor.makefile.so` -> VPS 公网 IP
 512-- `mac-conductor.makefile.so` -> VPS 公网 IP
 513-- `control-api.makefile.so` -> Cloudflare Worker 自定义域
 514-
 515-之后由 VPS 把节点专属域名再转发到 Tailscale `100.x` 地址。
 516-
 517-额外说明：
 518-
 519-- 公网 DNS 不承载 tailnet 内部寻址
 520-- tailnet 内部寻址直接用 `100.x`
 521-- 不使用 MagicDNS 名称做回源或服务发现
 522-
 523-## 6.5 建议的 DNS 记录
 524-
 525-推荐 DNS 记录如下：
 526-
 527-| Hostname | Type | Target | Purpose |
 528-| --- | --- | --- | --- |
 529-| `conductor.makefile.so` | `A` 或 `AAAA` | VPS 公网 IP | conductor 统一公网入口 |
 530-| `mini-conductor.makefile.so` | `A` 或 `AAAA` | VPS 公网 IP | 经 VPS 直达 mini |
 531-| `mac-conductor.makefile.so` | `A` 或 `AAAA` | VPS 公网 IP | 经 VPS 直达 mac |
 532-| `control-api.makefile.so` | Worker 自定义域 | Cloudflare Worker | durable 控制平面 API |
 533-| `led.makefile.so` | 现有 | 现有 origin | `baa-hand` |
 534-| `s.makefile.so` | 现有 | 现有 origin | `baa-shell` |
 535-
 536-说明：
 537-
 538-- 如果 VPS 走 Cloudflare 代理，所有相关 host 的代理模式要保持一致
 539-- `control-api.makefile.so` 最好留在 Cloudflare 内部，让 D1 访问保持本地化
 540-- mini 和 mac 不应该直接暴露在公网，节点专属域名仍然应该经过 VPS
 541-- tailnet 内部机器间调用不要再绕回这些公网域名
 542-
 543-## 6.6 TLS 策略
 544-
 545-推荐 TLS 模式：
 546-
 547-- 公网访问的域名尽量通过 Cloudflare 代理
 548-- VPS 上给 `conductor.makefile.so`、`mini-conductor.makefile.so`、`mac-conductor.makefile.so` 申请 Let’s Encrypt 证书
 549-- Worker 自定义域使用 Cloudflare 托管证书
 550-
 551-如果 conductor 域名启用了 Cloudflare 橙云：
 552-
 553-- VPS 上配置 origin certificate 或普通 Let’s Encrypt 证书
 554-- 尽量限制对 origin 的直接访问
 555-
 556-如果 conductor 域名不走 Cloudflare 代理：
 557-
 558-- 保持 VPS 上 Let’s Encrypt 自动续期
 559-- 对直连节点域名加鉴权保护
 560-
 561-## 7. VPS 与 Nginx 转发
 562-
 563-## 7.1 为什么需要 Nginx
 564-
 565-VPS 上的 Nginx 提供：
 566-
 567-- 稳定的公网入口
 568-- TCP 与 HTTP 层的机器切换
 569-- 到 mini 和 mac 的直连调试路由
 570-
 571-它不负责决定真实 leader。
 572-
 573-真实 leader 由 D1 lease 决定。
 574-
 575-它也不承载大部分内网控制流量。
 576-
 577-正确分工：
 578-
 579-- 浏览器、Claude 网页、管理页面 UI 走公网二级域名
 580-- mini/mac 之间的内部控制流量直接走 Tailscale `100.x`
 581-- VPS 只作为公网入口，不作为内网总线
 582-
 583-## 7.2 Nginx Upstream 设计
 584-
 585-推荐 upstream：
 586-
 587-```nginx
 588-upstream conductor_primary {
 589-    server 100.71.210.78:4317 max_fails=2 fail_timeout=5s;
 590-    server 100.112.239.13:4317 backup;
 591-    keepalive 32;
 592-}
 593-
 594-upstream mini_conductor_direct {
 595-    server 100.71.210.78:4317;
 596-    keepalive 16;
 597-}
 598-
 599-upstream mac_conductor_direct {
 600-    server 100.112.239.13:4317;
 601-    keepalive 16;
 602-}
 603-```
 604-
 605-本例中：
 606-
 607-- `100.71.210.78` 是 `mini`
 608-- `100.112.239.13` 是 `mac`
 609-- `4317` 是 conductor 本地 HTTP 端口
 610-- upstream 使用 Tailscale IPv4 地址，不使用 `*.ts.net` 名称
 611-- 这样可以绕开 ClashX 与 MagicDNS 的 DNS 接管冲突
 612-
 613-## 7.3 Nginx Server Block
 614-
 615-### 统一 conductor 入口
 616-
 617-```nginx
 618-server {
 619-    listen 443 ssl http2;
 620-    server_name conductor.makefile.so;
 621-
 622-    ssl_certificate     /etc/letsencrypt/live/conductor.makefile.so/fullchain.pem;
 623-    ssl_certificate_key /etc/letsencrypt/live/conductor.makefile.so/privkey.pem;
 624-
 625-    location / {
 626-        proxy_pass http://conductor_primary;
 627-        proxy_http_version 1.1;
 628-        proxy_set_header Host $host;
 629-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 630-        proxy_set_header X-Forwarded-Proto $scheme;
 631-        proxy_set_header X-Request-Id $request_id;
 632-        proxy_connect_timeout 3s;
 633-        proxy_read_timeout 60s;
 634-        proxy_send_timeout 60s;
 635-    }
 636-}
 637-```
 638-
 639-### 直达 mini 的路由
 640-
 641-```nginx
 642-server {
 643-    listen 443 ssl http2;
 644-    server_name mini-conductor.makefile.so;
 645-
 646-    ssl_certificate     /etc/letsencrypt/live/mini-conductor.makefile.so/fullchain.pem;
 647-    ssl_certificate_key /etc/letsencrypt/live/mini-conductor.makefile.so/privkey.pem;
 648-
 649-    location / {
 650-        proxy_pass http://mini_conductor_direct;
 651-        proxy_http_version 1.1;
 652-        proxy_set_header Host $host;
 653-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 654-        proxy_set_header X-Forwarded-Proto $scheme;
 655-        proxy_set_header X-Request-Id $request_id;
 656-    }
 657-}
 658-```
 659-
 660-### 直达 mac 的路由
 661-
 662-```nginx
 663-server {
 664-    listen 443 ssl http2;
 665-    server_name mac-conductor.makefile.so;
 666-
 667-    ssl_certificate     /etc/letsencrypt/live/mac-conductor.makefile.so/fullchain.pem;
 668-    ssl_certificate_key /etc/letsencrypt/live/mac-conductor.makefile.so/privkey.pem;
 669-
 670-    location / {
 671-        proxy_pass http://mac_conductor_direct;
 672-        proxy_http_version 1.1;
 673-        proxy_set_header Host $host;
 674-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 675-        proxy_set_header X-Forwarded-Proto $scheme;
 676-        proxy_set_header X-Request-Id $request_id;
 677-    }
 678-}
 679-```
 680-
 681-## 7.4 健康检查与就绪检查
 682-
 683-每个 conductor 都应暴露：
 684-
 685-- `GET /healthz`
 686-- `GET /readyz`
 687-- `GET /rolez`
 688-
 689-推荐语义：
 690-
 691-- `/healthz`: 进程活着
 692-- `/readyz`: 节点已准备好提供 conductor 服务
 693-- `/rolez`: 返回 `leader` 或 `standby`
 694-
 695-重要说明：
 696-
 697-- standby 可以健康，但不是 leader
 698-- 只要节点不是 leader，写 API 仍然必须拒绝调度类操作
 699-
 700-## 7.5 建议的端口暴露方式
 701-
 702-VPS 只应对公网暴露：
 703-
 704-- `80/tcp`
 705-- `443/tcp`
 706-
 707-mini 和 mac 不应该直接对公网开放 conductor 端口。
 708-
 709-推荐访问模型：
 710-
 711-- 浏览器、人类运维、Claude 网页、管理 UI -> 公网二级域名 -> VPS -> Tailscale upstream
 712-- mini 和 mac 的 daemon / worker / 脚本 -> 直接访问 Tailscale `100.x`
 713-- 只有需要公网暴露的入口才经过 VPS
 714-- 运维人员要访问 mini/mac 时，可通过 SSH、Tailscale `100.x`，或受保护的直连节点域名
 715-
 716-内网建议：
 717-
 718-- `mini` 本机调用本机 conductor：`http://127.0.0.1:4317`
 719-- `mini` 调 `mac`：`http://100.112.239.13:4317`
 720-- `mac` 调 `mini`：`http://100.71.210.78:4317`
 721-- VPS Nginx upstream 也直接写这两个 `100.x`
 722-
 723-## 7.6 完整的 Nginx 模式
 724-
 725-推荐整体模式：
 726-
 727-1. `:80` 全部跳转到 HTTPS
 728-2. `conductor.makefile.so` 走主加备 upstream
 729-3. `mini-conductor.makefile.so` 直转 mini upstream
 730-4. `mac-conductor.makefile.so` 直转 mac upstream
 731-5. 直连节点域名额外加鉴权
 732-
 733-### HTTP 跳转
 734-
 735-```nginx
 736-server {
 737-    listen 80;
 738-    listen [::]:80;
 739-    server_name conductor.makefile.so mini-conductor.makefile.so mac-conductor.makefile.so;
 740-    return 301 https://$host$request_uri;
 741-}
 742-```
 743-
 744-### 直连节点域名的 Basic Auth
 745-
 746-对 `mini-conductor.makefile.so` 与 `mac-conductor.makefile.so`，增加：
 747-
 748-```nginx
 749-auth_basic "Restricted";
 750-auth_basic_user_file /etc/nginx/.htpasswd-baa-conductor;
 751-```
 752-
 753-除非你希望整个系统都放在认证后面，否则不要把这段加到统一入口域名上。
 754-
 755-## 7.7 Nginx 加固建议
 756-
 757-建议在每个 TLS server block 中增加：
 758-
 759-```nginx
 760-proxy_set_header X-Real-IP $remote_addr;
 761-proxy_set_header X-Forwarded-Host $host;
 762-proxy_set_header X-Forwarded-Port $server_port;
 763-proxy_buffering off;
 764-client_max_body_size 10m;
 765-```
 766-
 767-如果你需要日志串联请求：
 768-
 769-```nginx
 770-add_header X-Request-Id $request_id always;
 771-```
 772-
 773-如果后续要走状态流或长连接：
 774-
 775-```nginx
 776-proxy_read_timeout 3600s;
 777-proxy_send_timeout 3600s;
 778-```
 779-
 780-## 7.8 Nginx Failover 的边界
 781-
 782-Nginx failover 只解决：
 783-
 784-- 网络路径故障
 785-- TCP 连接失败
 786-- 简单 upstream 不可达
 787-
 788-Nginx failover 不能解决：
 789-
 790-- split-brain
 791-- 过期 leader 继续写
 792-- task lease 冲突
 793-- 安全恢复逻辑
 794-
 795-因此所有写接口仍然必须校验 D1 lease 状态。
 796-
 797-## 7.9 建议的 Nginx 文件布局
 798-
 799-建议在 VPS 上使用：
 800-
 801-```text
 802-/etc/nginx/nginx.conf
 803-/etc/nginx/sites-available/baa-conductor.conf
 804-/etc/nginx/sites-enabled/baa-conductor.conf
 805-/etc/nginx/.htpasswd-baa-conductor
 806-```
 807-
 808-未来仓库中的文件应尽量镜像这个结构：
 809-
 810-```text
 811-ops/nginx/baa-conductor.conf
 812-ops/nginx/includes/common-proxy.conf
 813-ops/nginx/includes/direct-node-auth.conf
 814-```
 815-
 816-## 8. 主备与故障切换模型
 817-
 818-## 8.1 真相来源
 819-
 820-leader 真相在 D1，不在 Nginx。
 821-
 822-Nginx 只负责网络可达性和入口层 failover。
 823-
 824-## 8.2 推荐行为
 825-
 826-- `mini` 是首选 leader
 827-- `mac` 是 standby
 828-- 任意时刻只能有一个有效 leader lease
 829-
 830-推荐 lease 参数：
 831-
 832-- TTL: 30 秒
 833-- 续租周期: 每 5 秒一次
 834-- 连续 2 次续租失败后自我降级
 835-
 836-## 8.3 切换规则
 837-
 838-### 正常状态
 839-
 840-- mini 持有 lease
 841-- mac 只监听，不调度
 842-
 843-### Mini 故障
 844-
 845-- mini heartbeat 停止
 846-- lease 过期
 847-- mac 抢到 lease
 848-- mac 成为 active scheduler
 849-
 850-### Mini 恢复
 851-
 852-- mini 恢复上线
 853-- mini 注册为 standby
 854-- mini 不自动抢占
 855-
 856-### 手动切回
 857-
 858-管理员可以显式执行：
 859-
 860-- drain mac
 861-- promote mini
 862-- demote mac
 863-
 864-这样可以避免主备来回抖动。
 865-
 866-## 8.4 防止 Split-Brain
 867-
 868-规则：
 869-
 870-- 所有写动作都要求有效 lease
 871-- claim task 与 claim step 前都要检查 lease
 872-- 每条写路径都要校验当前 leader term
 873-- standby 节点必须拒绝调度类写入
 874-
 875-## 9. Cloudflare D1 控制平面
 876-
 877-## 9.1 为什么使用 D1
 878-
 879-使用 D1 作为共享 durable 协调存储，是因为它适合承载：
 880-
 881-- mini 与 mac 之间的共享真相
 882-- SQLite 事务语义
 883-- 队列、lease、元数据与索引
 884-
 885-D1 不适合存储：
 886-
 887-- 长期保存的完整原始日志
 888-- 大型二进制产物
 889-- 高频逐 token 流式数据
 890-
 891-## 9.2 访问模式
 892-
 893-推荐模式：
 894-
 895-- 机器本身不要直接写 D1
 896-- 全部通过统一的 HTTP control API
 897-- control API 跑在 Cloudflare Worker 上，并绑定 D1
 898-
 899-这样可以集中管理：
 900-
 901-- 鉴权
 902-- schema 访问
 903-- 事务约束
 904-- 版本演进
 905-
 906-## 9.3 读一致性
 907-
 908-控制路径上的读尽量使用主一致读。
 909-
 910-规则：
 911-
 912-- lease 获取与 task claim 必须保证主一致逻辑
 913-- 状态查看类页面可以容忍轻微陈旧
 914-
 915-## 10. 数据库 Schema
 916-
 917-本节定义最小 D1 schema。
 918-
 919-## 10.1 `leader_lease`
 920-
 921-用途：
 922-
 923-- 全局唯一 active leadership lease
 924-
 925-```sql
 926-CREATE TABLE IF NOT EXISTS leader_lease (
 927-  lease_name TEXT PRIMARY KEY,
 928-  holder_id TEXT NOT NULL,
 929-  holder_host TEXT NOT NULL,
 930-  term INTEGER NOT NULL,
 931-  lease_expires_at INTEGER NOT NULL,
 932-  renewed_at INTEGER NOT NULL,
 933-  preferred_holder_id TEXT,
 934-  metadata_json TEXT
 935-);
 936-```
 937-
 938-约定：
 939-
 940-- 只保留一行，`lease_name = 'global'`
 941-
 942-## 10.2 `controllers`
 943-
 944-用途：
 945-
 946-- 注册 conductors 及其 heartbeat
 947-
 948-```sql
 949-CREATE TABLE IF NOT EXISTS controllers (
 950-  controller_id TEXT PRIMARY KEY,
 951-  host TEXT NOT NULL,
 952-  role TEXT NOT NULL,
 953-  priority INTEGER NOT NULL,
 954-  status TEXT NOT NULL,
 955-  version TEXT,
 956-  last_heartbeat_at INTEGER NOT NULL,
 957-  last_started_at INTEGER,
 958-  metadata_json TEXT
 959-);
 960-```
 961-
 962-## 10.3 `workers`
 963-
 964-用途：
 965-
 966-- 注册 worker slot
 967-
 968-```sql
 969-CREATE TABLE IF NOT EXISTS workers (
 970-  worker_id TEXT PRIMARY KEY,
 971-  controller_id TEXT NOT NULL,
 972-  host TEXT NOT NULL,
 973-  worker_type TEXT NOT NULL,
 974-  status TEXT NOT NULL,
 975-  max_parallelism INTEGER NOT NULL DEFAULT 1,
 976-  current_load INTEGER NOT NULL DEFAULT 0,
 977-  last_heartbeat_at INTEGER NOT NULL,
 978-  capabilities_json TEXT,
 979-  metadata_json TEXT
 980-);
 981-```
 982-
 983-## 10.4 `tasks`
 984-
 985-用途：
 986-
 987-- durable task 队列
 988-
 989-```sql
 990-CREATE TABLE IF NOT EXISTS tasks (
 991-  task_id TEXT PRIMARY KEY,
 992-  repo TEXT NOT NULL,
 993-  task_type TEXT NOT NULL,
 994-  title TEXT NOT NULL,
 995-  goal TEXT NOT NULL,
 996-  source TEXT NOT NULL,
 997-  priority INTEGER NOT NULL DEFAULT 100,
 998-  status TEXT NOT NULL,
 999-  planning_strategy TEXT,
1000-  planner_provider TEXT,
1001-  branch_name TEXT,
1002-  base_ref TEXT,
1003-  target_host TEXT,
1004-  assigned_controller_id TEXT,
1005-  current_step_index INTEGER NOT NULL DEFAULT -1,
1006-  constraints_json TEXT,
1007-  acceptance_json TEXT,
1008-  metadata_json TEXT,
1009-  result_summary TEXT,
1010-  result_json TEXT,
1011-  error_text TEXT,
1012-  created_at INTEGER NOT NULL,
1013-  updated_at INTEGER NOT NULL,
1014-  started_at INTEGER,
1015-  finished_at INTEGER
1016-);
1017-```
1018-
1019-索引：
1020-
1021-```sql
1022-CREATE INDEX IF NOT EXISTS idx_tasks_status_priority
1023-ON tasks(status, priority, created_at);
1024-
1025-CREATE INDEX IF NOT EXISTS idx_tasks_repo
1026-ON tasks(repo, created_at);
1027-```
1028-
1029-## 10.5 `task_steps`
1030-
1031-用途：
1032-
1033-- 持久化恢复边界
1034-
1035-```sql
1036-CREATE TABLE IF NOT EXISTS task_steps (
1037-  step_id TEXT PRIMARY KEY,
1038-  task_id TEXT NOT NULL,
1039-  step_index INTEGER NOT NULL,
1040-  step_name TEXT NOT NULL,
1041-  step_kind TEXT NOT NULL,
1042-  status TEXT NOT NULL,
1043-  assigned_worker_id TEXT,
1044-  assigned_controller_id TEXT,
1045-  timeout_sec INTEGER NOT NULL,
1046-  retry_limit INTEGER NOT NULL DEFAULT 0,
1047-  retry_count INTEGER NOT NULL DEFAULT 0,
1048-  lease_expires_at INTEGER,
1049-  input_json TEXT,
1050-  output_json TEXT,
1051-  summary TEXT,
1052-  error_text TEXT,
1053-  created_at INTEGER NOT NULL,
1054-  updated_at INTEGER NOT NULL,
1055-  started_at INTEGER,
1056-  finished_at INTEGER,
1057-  UNIQUE(task_id, step_index)
1058-);
1059-```
1060-
1061-索引：
1062-
1063-```sql
1064-CREATE INDEX IF NOT EXISTS idx_task_steps_task_status
1065-ON task_steps(task_id, status, step_index);
1066-```
1067-
1068-## 10.6 `task_runs`
1069-
1070-用途：
1071-
1072-- 记录 step 的执行尝试
1073-
1074-```sql
1075-CREATE TABLE IF NOT EXISTS task_runs (
1076-  run_id TEXT PRIMARY KEY,
1077-  task_id TEXT NOT NULL,
1078-  step_id TEXT NOT NULL,
1079-  worker_id TEXT NOT NULL,
1080-  controller_id TEXT NOT NULL,
1081-  host TEXT NOT NULL,
1082-  pid INTEGER,
1083-  status TEXT NOT NULL,
1084-  lease_expires_at INTEGER,
1085-  heartbeat_at INTEGER,
1086-  log_dir TEXT NOT NULL,
1087-  stdout_path TEXT,
1088-  stderr_path TEXT,
1089-  worker_log_path TEXT,
1090-  checkpoint_seq INTEGER NOT NULL DEFAULT 0,
1091-  exit_code INTEGER,
1092-  result_json TEXT,
1093-  error_text TEXT,
1094-  created_at INTEGER NOT NULL,
1095-  started_at INTEGER,
1096-  finished_at INTEGER
1097-);
1098-```
1099-
1100-索引：
1101-
1102-```sql
1103-CREATE INDEX IF NOT EXISTS idx_task_runs_task
1104-ON task_runs(task_id, created_at);
1105-
1106-CREATE INDEX IF NOT EXISTS idx_task_runs_step
1107-ON task_runs(step_id, created_at);
1108-```
1109-
1110-## 10.7 `task_checkpoints`
1111-
1112-用途：
1113-
1114-- 恢复 step 中途进度的快照
1115-
1116-这一张表很关键，因为某些 Codex step 很长，在 step 完成前就可能已经产生了有价值的部分进度。
1117-
1118-```sql
1119-CREATE TABLE IF NOT EXISTS task_checkpoints (
1120-  checkpoint_id TEXT PRIMARY KEY,
1121-  task_id TEXT NOT NULL,
1122-  step_id TEXT NOT NULL,
1123-  run_id TEXT NOT NULL,
1124-  seq INTEGER NOT NULL,
1125-  checkpoint_type TEXT NOT NULL,
1126-  summary TEXT,
1127-  content_text TEXT,
1128-  content_json TEXT,
1129-  created_at INTEGER NOT NULL,
1130-  UNIQUE(run_id, seq)
1131-);
1132-```
1133-
1134-checkpoint 类型可以包括：
1135-
1136-- `heartbeat`
1137-- `log_tail`
1138-- `git_diff`
1139-- `summary`
1140-- `test_result`
1141-
1142-## 10.8 `task_logs`
1143-
1144-用途：
1145-
1146-- 存结构化日志尾部与生命周期事件
1147-
1148-```sql
1149-CREATE TABLE IF NOT EXISTS task_logs (
1150-  log_id INTEGER PRIMARY KEY AUTOINCREMENT,
1151-  task_id TEXT NOT NULL,
1152-  step_id TEXT,
1153-  run_id TEXT NOT NULL,
1154-  seq INTEGER NOT NULL,
1155-  stream TEXT NOT NULL,
1156-  level TEXT,
1157-  message TEXT NOT NULL,
1158-  created_at INTEGER NOT NULL
1159-);
1160-```
1161-
1162-## 10.9 `system_state`
1163-
1164-用途：
1165-
1166-- 全局自动化状态
1167-
1168-```sql
1169-CREATE TABLE IF NOT EXISTS system_state (
1170-  state_key TEXT PRIMARY KEY,
1171-  value_json TEXT NOT NULL,
1172-  updated_at INTEGER NOT NULL
1173-);
1174-```
1175-
1176-约定：
1177-
1178-- `state_key = 'automation'`
1179-- value 中包含 `mode = running | draining | paused`
1180-
1181-## 10.10 `task_artifacts`
1182-
1183-可选但推荐。
1184-
1185-用途：
1186-
1187-- 保存 durable 输出的结构化引用
1188-
1189-```sql
1190-CREATE TABLE IF NOT EXISTS task_artifacts (
1191-  artifact_id TEXT PRIMARY KEY,
1192-  task_id TEXT NOT NULL,
1193-  step_id TEXT,
1194-  run_id TEXT,
1195-  artifact_type TEXT NOT NULL,
1196-  path TEXT,
1197-  uri TEXT,
1198-  size_bytes INTEGER,
1199-  sha256 TEXT,
1200-  metadata_json TEXT,
1201-  created_at INTEGER NOT NULL
1202-);
1203-```
1204-
1205-## 11. Control API
1206-
1207-推荐的生产设计是：
1208-
1209-- 一个 Cloudflare Worker
1210-- 一个 D1 binding
1211-- 所有 durable 状态迁移都经过这个 Worker
1212-
1213-## 11.1 Base URL
1214-
1215-推荐：
1216-
1217-- `https://control-api.makefile.so`
1218-
1219-## 11.2 必需接口
1220-
1221-### `POST /v1/controllers/heartbeat`
1222-
1223-由 mini 和 mac conductor 调用。
1224-
1225-Body：
1226-
1227-```json
1228-{
1229-  "controller_id": "mini-main",
1230-  "host": "mini",
1231-  "role": "primary",
1232-  "priority": 100,
1233-  "status": "alive",
1234-  "version": "0.1.0"
1235-}
1236-```
1237-
1238-### `POST /v1/leader/acquire`
1239-
1240-由 conductors 用来获取或续租 lease。
1241-
1242-Body：
1243-
1244-```json
1245-{
1246-  "controller_id": "mini-main",
1247-  "host": "mini",
1248-  "preferred": true,
1249-  "ttl_sec": 30
1250-}
1251-```
1252-
1253-Response：
1254-
1255-```json
1256-{
1257-  "ok": true,
1258-  "holder_id": "mini-main",
1259-  "term": 7,
1260-  "lease_expires_at": 1760000000000,
1261-  "is_leader": true
1262-}
1263-```
1264-
1265-### `POST /v1/tasks`
1266-
1267-创建 task。
1268-
1269-Body：
1270-
1271-```json
1272-{
1273-  "repo": "/Users/george/code/event-fabric",
1274-  "task_type": "feature_impl",
1275-  "title": "Add conductor D1 schema",
1276-  "goal": "Implement the initial D1 schema and migration scripts.",
1277-  "priority": 50,
1278-  "constraints": {
1279-    "target_host": "mini"
1280-  },
1281-  "acceptance": [
1282-    "SQL schema committed",
1283-    "migration runner stub added"
1284-  ],
1285-  "metadata": {
1286-    "requested_by": "control",
1287-    "branch_prefix": "feat"
1288-  }
1289-}
1290-```
1291-
1292-### `POST /v1/tasks/:task_id/plan`
1293-
1294-持久化已通过校验的 step plan。
1295-
1296-该接口由 conductor 在完成 planner 输出校验后调用。
1297-
1298-### `POST /v1/tasks/claim`
1299-
1300-领取待规划 task 或下一个可运行 step。
1301-
1302-也可以拆成：
1303-
1304-- `POST /v1/tasks/claim-planning`
1305-- `POST /v1/steps/claim`
1306-
1307-只要事务语义清晰，这两种形式都可以。
1308-
1309-### `POST /v1/steps/:step_id/heartbeat`
1310-
1311-Body 包含：
1312-
1313-- `run_id`
1314-- `worker_id`
1315-- `lease_expires_at`
1316-- 可选 `checkpoint`
1317-
1318-### `POST /v1/steps/:step_id/checkpoint`
1319-
1320-Body：
1321-
1322-```json
1323-{
1324-  "run_id": "run_001",
1325-  "seq": 3,
1326-  "checkpoint_type": "git_diff",
1327-  "summary": "Current worktree diff after route refactor",
1328-  "content_text": "diff --git ..."
1329-}
1330-```
1331-
1332-### `POST /v1/steps/:step_id/complete`
1333-
1334-### `POST /v1/steps/:step_id/fail`
1335-
1336-### `POST /v1/system/pause`
1337-
1338-### `POST /v1/system/resume`
1339-
1340-### `POST /v1/system/drain`
1341-
1342-### `GET /v1/system/state`
1343-
1344-### `GET /v1/tasks/:task_id`
1345-
1346-### `GET /v1/tasks/:task_id/logs`
1347-
1348-### `GET /v1/runs/:run_id`
1349-
1350-## 11.3 鉴权
1351-
1352-最低要求：
1353-
1354-- conductor、worker 与 control API 之间使用 HMAC token 或共享密钥
1355-- 修改系统状态的操作使用单独的 admin token
1356-
1357-推荐后续演进：
1358-
1359-- 签名 service token
1360-- 按角色拆 scope
1361-
1362-## 11.4 Control API 授权模型
1363-
1364-推荐角色：
1365-
1366-- `controller`
1367-- `worker`
1368-- `browser_admin`
1369-- `ops_admin`
1370-- `readonly`
1371-
1372-推荐权限划分：
1373-
1374-| Role | Allowed Actions |
1375-| --- | --- |
1376-| `controller` | 获取与续租 lease、claim tasks、更新 run 状态 |
1377-| `worker` | heartbeat、checkpoint、完成已分配 step |
1378-| `browser_admin` | pause、resume、drain、查看队列 |
1379-| `ops_admin` | promote、demote、维护操作 |
1380-| `readonly` | 状态查看、日志、面板 |
1381-
1382-推荐实现：
1383-
1384-- `Authorization: Bearer <token>`
1385-- token 元数据包含角色与可选主机身份
1386-- 修改接口既校验角色，也校验资源归属
1387-
1388-## 11.5 Control API 运维约束
1389-
1390-Worker 应提供：
1391-
1392-- 尽量做到幂等写入
1393-- 对陈旧 term 明确返回冲突
1394-- 记录 request id
1395-- 输出结构化错误体
1396-
1397-推荐错误格式：
1398-
1399-```json
1400-{
1401-  "ok": false,
1402-  "error": "not_leader",
1403-  "message": "This node does not hold the active leadership lease.",
1404-  "request_id": "req_123"
1405-}
1406-```
1407-
1408-## 12. Task 模型
1409-
1410-## 12.1 Task 生命周期
1411-
1412-Task 状态：
1413-
1414-- `queued`
1415-- `planning`
1416-- `running`
1417-- `paused`
1418-- `done`
1419-- `failed`
1420-- `canceled`
1421-
1422-状态流转：
1423-
1424-- `queued -> planning`
1425-- `planning -> running`
1426-- `planning -> failed`
1427-- `running -> paused`
1428-- `paused -> running`
1429-- `running -> done`
1430-- `running -> failed`
1431-- `running -> canceled`
1432-
1433-## 12.2 Task 输入 Schema
1434-
1435-推荐归一化格式：
1436-
1437-```json
1438-{
1439-  "task_id": "task_001",
1440-  "repo": "/Users/george/code/event-fabric",
1441-  "task_type": "feature_impl",
1442-  "title": "Implement task scheduler",
1443-  "goal": "Add the initial scheduler and step claim logic.",
1444-  "priority": 50,
1445-  "constraints": {
1446-    "target_host": "mini",
1447-    "write_scope": [
1448-      "services/conductor-daemon/**",
1449-      "packages/db/**"
1450-    ]
1451-  },
1452-  "acceptance": [
1453-    "claim endpoint exists",
1454-    "scheduler handles one runnable step",
1455-    "tests added"
1456-  ],
1457-  "metadata": {
1458-    "branch_prefix": "feat",
1459-    "requested_by": "control"
1460-  }
1461-}
1462-```
1463-
1464-## 12.3 分支策略
1465-
1466-一个 task 对应一个分支。
1467-
1468-规则：
1469-
1470-- 分支由 conductor 创建
1471-- worker 不自己发明分支名
1472-- 分支命名应尽量确定性
1473-
1474-推荐命名：
1475-
1476-- `feat/T-001-d1-schema`
1477-- `feat/T-002-step-claim`
1478-- `fix/T-003-checkpoint-recovery`
1479-
1480-## 13. Step 模型
1481-
1482-## 13.1 Step 状态
1483-
1484-- `pending`
1485-- `running`
1486-- `done`
1487-- `failed`
1488-- `timeout`
1489-
1490-## 13.2 Step 类型
1491-
1492-推荐 step kind：
1493-
1494-- `planner`
1495-- `codex`
1496-- `shell`
1497-- `git`
1498-- `review`
1499-- `finalize`
1500-
1501-## 13.3 Step 合约
1502-
1503-每个 step 都必须具备：
1504-
1505-- 明确的目标边界
1506-- 输入 payload
1507-- timeout
1508-- retry 策略
1509-- 完成后的 summary
1510-
1511-## 13.4 恢复边界
1512-
1513-step 完成是主要恢复边界。
1514-
1515-但因为 Codex step 可能很长，所以系统还必须维护 step 中途的 checkpoint。
1516-
1517-## 14. Planning 模型
1518-
1519-## 14.1 Planner 所有权
1520-
1521-task 拆 step 的所有权属于 conductor。
1522-
1523-含义是：
1524-
1525-- planner 只负责提案
1526-- conductor 决定接受并持久化
1527-- worker 只负责执行
1528-
1529-## 14.2 规划策略选择
1530-
1531-conductor 需要决定：
1532-
1533-- `template_first`
1534-- `planner_assisted`
1535-- `manual`
1536-
1537-例如：
1538-
1539-- 标准 bugfix -> `template_first`
1540-- 模糊的大范围重构 -> `planner_assisted`
1541-- 紧急运维变更 -> `manual`
1542-
1543-## 14.3 Planner 输出 Schema
1544-
1545-推荐 planner 输出：
1546-
1547-```json
1548-{
1549-  "task_type": "feature_impl",
1550-  "strategy": "planner_assisted",
1551-  "reasoning": "The task touches scheduler, persistence, and recovery logic. Split into deterministic steps.",
1552-  "steps": [
1553-    {
1554-      "step_name": "prepare_branch",
1555-      "step_kind": "git",
1556-      "timeout_sec": 120,
1557-      "retry_limit": 0,
1558-      "input": {}
1559-    },
1560-    {
1561-      "step_name": "inspect_context",
1562-      "step_kind": "codex",
1563-      "timeout_sec": 600,
1564-      "retry_limit": 1,
1565-      "input": {
1566-        "goal": "Read the codebase and summarize where scheduler logic belongs."
1567-      }
1568-    },
1569-    {
1570-      "step_name": "implement_scheduler",
1571-      "step_kind": "codex",
1572-      "timeout_sec": 1800,
1573-      "retry_limit": 1,
1574-      "input": {
1575-        "goal": "Implement scheduler claim loop and state transition logic."
1576-      }
1577-    },
1578-    {
1579-      "step_name": "run_tests",
1580-      "step_kind": "shell",
1581-      "timeout_sec": 1200,
1582-      "retry_limit": 1,
1583-      "input": {
1584-        "command": "npm test"
1585-      }
1586-    },
1587-    {
1588-      "step_name": "commit_push",
1589-      "step_kind": "git",
1590-      "timeout_sec": 300,
1591-      "retry_limit": 0,
1592-      "input": {}
1593-    }
1594-  ]
1595-}
1596-```
1597-
1598-## 14.4 Planner 校验规则
1599-
1600-conductor 校验规则：
1601-
1602-- step 名称必须已知，或被明确允许
1603-- step 顺序必须合法
1604-- timeout 不能无上限
1605-- step 输入不能为空缺
1606-- 不允许 planner 指令直接做状态迁移
1607-
1608-## 15. 推荐的 Task 模板
1609-
1610-## 15.1 `feature_impl`
1611-
1612-推荐默认步骤：
1613-
1614-1. `prepare_branch`
1615-2. `inspect_context`
1616-3. `implement`
1617-4. `run_tests`
1618-5. `review_fix`
1619-6. `commit_push`
1620-7. `finalize`
1621-
1622-## 15.2 `bugfix`
1623-
1624-推荐默认步骤：
1625-
1626-1. `prepare_branch`
1627-2. `reproduce`
1628-3. `implement_fix`
1629-4. `run_targeted_tests`
1630-5. `commit_push`
1631-6. `finalize`
1632-
1633-## 15.3 `review_only`
1634-
1635-推荐默认步骤：
1636-
1637-1. `prepare_context`
1638-2. `analyze_diff`
1639-3. `write_review`
1640-4. `finalize`
1641-
1642-## 15.4 `ops_change`
1643-
1644-推荐默认步骤：
1645-
1646-1. `prepare_branch`
1647-2. `inspect_ops_context`
1648-3. `edit_ops_files`
1649-4. `validate_config`
1650-5. `commit_push`
1651-6. `finalize`
1652-
1653-## 15.5 `infra_bootstrap`
1654-
1655-推荐默认步骤：
1656-
1657-1. `prepare_branch`
1658-2. `inspect_current_ops_state`
1659-3. `edit_dns_or_nginx_docs`
1660-4. `validate_nginx_config`
1661-5. `commit_push`
1662-6. `finalize`
1663-
1664-## 16. Conductor 详细职责
1665-
1666-conductor 必须承担以下职责。
1667-
1668-### 16.1 启动时
1669-
1670-- 在 `controllers` 中注册自身
1671-- 启动 heartbeat 循环
1672-- 如果有资格则尝试获取 lease
1673-- 加载本地未完成 runs
1674-- 对本地过期 runs 做对账
1675-
1676-### 16.2 Leader Loop
1677-
1678-如果是 leader：
1679-
1680-- 规划 queued tasks
1681-- claim runnable steps
1682-- 分配 workers
1683-- 监管 runs
1684-- 持久化 checkpoints
1685-
1686-如果是 standby：
1687-
1688-- 只发 heartbeat
1689-- 不调度新工作
1690-- 随时准备在当前 leader 过期后接管 lease
1691-
1692-### 16.3 Worker 分配
1693-
1694-conductor 负责选择：
1695-
1696-- host
1697-- worker slot
1698-- worktree 路径
1699-- run 目录
1700-- timeout 预算
1701-
1702-### 16.4 Timeout 执行
1703-
1704-conductor 负责：
1705-
1706-- step timeout
1707-- lease 过期
1708-- 从 `SIGTERM` 升级到 `SIGKILL`
1709-
1710-### 16.5 恢复
1711-
1712-重启后：
1713-
1714-- 扫描本地 run 目录
1715-- 标记 orphaned runs
1716-- 对比本地状态与 D1 状态
1717-- 视情况重新入队或恢复
1718-
1719-## 17. Worker 模型
1720-
1721-## 17.1 为什么 Worker 要短生命周期
1722-
1723-短生命周期 worker 更容易：
1724-
1725-- 隔离故障
1726-- 收集日志
1727-- 管理资源
1728-- 在崩溃后恢复
1729-
1730-## 17.2 Step 执行合约
1731-
1732-worker 合约是：
1733-
1734-1. 接收一个 step
1735-2. 执行一个 step
1736-3. 输出本地日志
1737-4. 输出结构化结果
1738-5. 退出
1739-
1740-worker 不负责：
1741-
1742-- 管理队列
1743-- 持有 lease
1744-- 选择下一个 step
1745-
1746-## 17.3 Worker 类型
1747-
1748-### Codex Worker
1749-
1750-用于：
1751-
1752-- 阅读上下文
1753-- 修改代码
1754-- 输出总结
1755-
1756-### Shell Worker
1757-
1758-用于：
1759-
1760-- 测试
1761-- lint
1762-- 文件检查
1763-- build 命令
1764-
1765-### Git Worker
1766-
1767-用于：
1768-
1769-- 建分支
1770-- commit
1771-- push
1772-- 重置 per-task worktree
1773-
1774-## 18. Codex Worker 合约
1775-
1776-## 18.1 关键约束
1777-
1778-Codex 不以进程恢复为目标。
1779-
1780-系统恢复的是：
1781-
1782-- task
1783-- step
1784-- 最新 checkpoint
1785-
1786-系统不恢复：
1787-
1788-- 已死亡 Codex 进程内部的精确推理状态
1789-
1790-## 18.2 Codex Step 行为
1791-
1792-对于 Codex step：
1793-
1794-- conductor 准备 prompt 与上下文文件
1795-- conductor 启动 Codex
1796-- Codex 把输出写入本地日志
1797-- conductor 周期性抓取 checkpoint
1798-- step 完成后 Codex 退出
1799-
1800-## 18.3 为什么这比当前 `baa-hand` 的 Codex 模式更好
1801-
1802-当前 `baa-hand` 的 Codex 集成会一直等到进程退出，然后才返回输出。
1803-
1804-对于 durable worker 系统，这不够，因为：
1805-
1806-- 它不会把进度持续写成 durable 状态
1807-- 它不支持 checkpoint 恢复
1808-- 它没有把 task 状态和进程状态分离
1809-
1810-因此：
1811-
1812-- 当前 `baa-hand` 的 Codex 路径继续保留给临时用途
1813-- 生产自动化要走 conductor 自己持有的 Codex worker 路径
1814-
1815-## 18.4 Codex 结果 Schema
1816-
1817-推荐最终 step 输出：
1818-
1819-```json
1820-{
1821-  "ok": true,
1822-  "summary": "Implemented scheduler claim loop and added tests.",
1823-  "needs_human": false,
1824-  "blocked": false,
1825-  "artifacts": [],
1826-  "metrics": {
1827-    "duration_sec": 812
1828-  }
1829-}
1830-```
1831-
1832-可选 hint：
1833-
1834-```json
1835-{
1836-  "ok": false,
1837-  "summary": "Need failing test output from package runtime.",
1838-  "blocked": true,
1839-  "suggested_followup": [
1840-    {
1841-      "step_name": "collect_runtime_test_output",
1842-      "step_kind": "shell"
1843-    }
1844-  ]
1845-}
1846-```
1847-
1848-这些 hint 只是 proposal，不是直接状态修改。
1849-
1850-## 19. 日志模型
1851-
1852-## 19.1 本地完整日志
1853-
1854-每个 run 都有一个本地目录：
1855-
1856-```text
1857-<repo>/.baa-conductor/runs/<task-id>/<run-id>/
1858-  meta.json
1859-  worker.log
1860-  stdout.log
1861-  stderr.log
1862-  checkpoints/
1863-    0001-summary.json
1864-    0002-git-diff.patch
1865-```
1866-
1867-本地完整日志是详细取证记录。
1868-
1869-## 19.2 D1 日志索引
1870-
1871-D1 中只存：
1872-
1873-- run 元数据
1874-- 生命周期事件
1875-- 周期性 tail chunk
1876-- 最新 checkpoint 指针
1877-
1878-不应该把全部字节都长期塞进 D1。
1879-
1880-## 19.3 日志事件
1881-
1882-关键生命周期事件包括：
1883-
1884-- task created
1885-- planner selected
1886-- plan accepted
1887-- step claimed
1888-- worker started
1889-- checkpoint persisted
1890-- timeout
1891-- step done
1892-- task done
1893-- failover occurred
1894-
1895-## 20. Checkpoint 模型
1896-
1897-这是稳定性的关键部分。
1898-
1899-## 20.1 为什么需要 Checkpoint
1900-
1901-如果 Codex 改了 20 分钟代码，机器突然死掉，只按 step 边界恢复，就会丢掉所有未提交进度。
1902-
1903-因此，长 AI step 需要 step 中途 checkpoint。
1904-
1905-## 20.2 Checkpoint 类型
1906-
1907-推荐类型：
1908-
1909-- `summary`
1910-- `git_diff`
1911-- `log_tail`
1912-- `test_output`
1913-
1914-## 20.3 Git Diff Checkpoint
1915-
1916-对于 Codex 编辑类 step，conductor 应周期性快照：
1917-
1918-- `git status --short`
1919-- `git diff --binary`
1920-- 可选 `git diff --stat`
1921-
1922-推荐频率：
1923-
1924-- 每 30 到 60 秒一次
1925-- 或在检测到有意义的文件变化后执行
1926-
1927-## 20.4 Checkpoint 存储策略
1928-
1929-MVP 期的策略：
1930-
1931-- 最新 checkpoint summary 存入 D1
1932-- patch 文本大小合理时，一并写入 D1
1933-- 完整 checkpoint 文件保存在本地
1934-
1935-如果 patch 太大：
1936-
1937-- D1 里只保留截断 summary
1938-- 完整 patch 只保留在本地
1939-- 后续可选接入 R2
1940-
1941-## 20.5 从 Checkpoint 恢复
1942-
1943-如果 mini 在执行 Codex step 时宕机：
1944-
1945-1. mac 成为 leader
1946-2. mac 发现 run lease 已过期
1947-3. mac 创建新的 worktree
1948-4. mac checkout task branch 或 base ref
1949-5. 如果存在 checkpointed diff，则回放最新 diff
1950-6. 从最近一个可接受 checkpoint 继续，或直接重跑该 step
1951-
1952-这不是 bit-perfect 的进程恢复。
1953-
1954-这是 durable 的 task 恢复，并支持部分 patch 回放。
1955-
1956-## 21. Timeout 与 Retry 规则
1957-
1958-## 21.1 Timeout 所有权
1959-
1960-timeout 由 conductor 负责。
1961-
1962-worker 不对整个 task 自己做 timeout 判定。
1963-
1964-## 21.2 进程处理
1965-
1966-推荐升级顺序：
1967-
1968-1. 发送 `SIGTERM`
1969-2. 等待 5 秒
1970-3. 发送 `SIGKILL`
1971-4. 标记 run 为 `timeout`
1972-5. 根据策略决定 retry 或 fail
1973-
1974-## 21.3 Retry 规则
1975-
1976-推荐默认值：
1977-
1978-- planner steps: 1 次重试
1979-- codex inspect steps: 1 次重试
1980-- codex implement steps: 1 次重试
1981-- test steps: 基础设施失败时 1 次重试，确定性失败时 0 次
1982-- git commit/push: 默认 0 次，除非 push 因瞬时网络原因失败
1983-
1984-## 21.4 失败分类
1985-
1986-需要明确区分：
1987-
1988-- `timeout`
1989-- `worker_crash`
1990-- `infra_unreachable`
1991-- `deterministic_failure`
1992-- `blocked`
1993-
1994-这个分类会直接影响 retry 策略。
1995-
1996-## 22. Pause、Drain 与 Resume
1997-
1998-## 22.1 全局模式
1999-
2000-全局自动化模式：
2001-
2002-- `running`
2003-- `draining`
2004-- `paused`
2005-
2006-## 22.2 语义
2007-
2008-### `running`
2009-
2010-- 正常运行
2011-
2012-### `draining`
2013-
2014-- 不再启动新的 step
2015-- 已启动的 run 可以自然结束
2016-- 适合计划内切换或维护
2017-
2018-### `paused`
2019-
2020-- 不再启动新的 step
2021-- conductor 调度暂停
2022-- 已运行任务是否继续或终止，由策略决定
2023-
2024-## 22.3 真相来源
2025-
2026-全局模式存储在 D1 的 `system_state` 中。
2027-
2028-浏览器 UI 只是控制面板，不是真相来源。
2029-
2030-## 23. Firefox 插件集成
2031-
2032-## 23.1 浏览器职责
2033-
2034-Firefox 插件应负责：
2035-
2036-- 展示当前全局自动化模式
2037-- 提供 `pause`、`resume`，可选 `drain`
2038-- 展示当前 leader host
2039-- 如有需要，展示队列深度与 active task 数
2040-
2041-## 23.2 浏览器控制流
2042-
2043-可见的 `control` 对话仍然只用于人机交互。
2044-
2045-插件不应混用：
2046-
2047-- 你的交互式 `control` 对话
2048-- 自动化 task dispatch
2049-
2050-推荐模型：
2051-
2052-- 一个可见 `control` 对话
2053-- 一个隐藏 `dispatch` 通道
2054-
2055-## 23.3 浏览器按钮
2056-
2057-最少需要这些按钮：
2058-
2059-- `Pause`
2060-- `Resume`
2061-- 可选 `Drain`
2062-
2063-按钮应调用：
2064-
2065-- `POST /v1/system/pause`
2066-- `POST /v1/system/resume`
2067-- `POST /v1/system/drain`
2068-
2069-## 23.4 浏览器状态显示
2070-
2071-最低显示项：
2072-
2073-- 当前 mode
2074-- 当前 leader
2075-- active runs
2076-- queued tasks
2077-
2078-## 24. `baa-hand` 与 `baa-shell` 集成
2079-
2080-## 24.1 `baa-hand`
2081-
2082-`baa-hand` 适用于：
2083-
2084-- planner 调用
2085-- review 调用
2086-- 非 durable 的临时 AI 工作
2087-
2088-推荐：
2089-
2090-- planner 与 review steps 调 `led.makefile.so`
2091-- execution steps 不依赖当前 `baa-hand` 的 Codex 模式来保证 durability
2092-
2093-## 24.2 `baa-shell`
2094-
2095-`baa-shell` 适用于：
2096-
2097-- 当 HTTP 比 SSH 更方便时，执行远程 shell
2098-- 让外部自动化读写文件
2099-- 提供状态页面
2100-
2101-对于同机操作，本地 conductor 代码依然可以直接用 local exec。
2102-
2103-## 25. mini 与 mac 上的本地目录布局
2104-
2105-推荐根路径：
2106-
2107-```text
2108-/Users/george/code/baa-conductor
2109-```
2110-
2111-推荐 runtime 目录：
2112-
2113-```text
2114-/Users/george/code/baa-conductor/state/
2115-/Users/george/code/baa-conductor/runs/
2116-/Users/george/code/baa-conductor/worktrees/
2117-/Users/george/code/baa-conductor/logs/
2118-/Users/george/code/baa-conductor/tmp/
2119-```
2120-
2121-推荐的 per-run 目录：
2122-
2123-```text
2124-/Users/george/code/baa-conductor/runs/<task-id>/<run-id>/
2125-  meta.json
2126-  state.json
2127-  stdout.log
2128-  stderr.log
2129-  worker.log
2130-  checkpoints/
2131-  artifacts/
2132-```
2133-
2134-推荐的 worktree 目录：
2135-
2136-```text
2137-/Users/george/code/baa-conductor/worktrees/<task-id>/
2138-```
2139-
2140-规则：
2141-
2142-- 一个 task 恰好一个 worktree
2143-- worktree 路径应确定性
2144-- 陈旧 worktree 只能由 conductor 清理，worker 不得自行清理
2145-
2146-## 25.1 本地文件约定
2147-
2148-建议由 conductor 写入的文件：
2149-
2150-- `meta.json`: 不变的 run 元数据
2151-- `state.json`: 当前本地状态镜像
2152-- `worker.log`: 当前 run 的 conductor 生命周期消息
2153-- `stdout.log`: worker 原始 stdout
2154-- `stderr.log`: worker 原始 stderr
2155-
2156-建议作为 checkpoint 写入的文件：
2157-
2158-- `checkpoints/0001-summary.json`
2159-- `checkpoints/0002-git-diff.patch`
2160-- `checkpoints/0003-test-output.txt`
2161-
2162-## 26. 建议的仓库结构
2163-
2164-此仓库最终建议长成这样：
2165-
2166-```text
2167-apps/
2168-  control-api-worker/
2169-  conductor-daemon/
2170-  status-api/
2171-  worker-runner/
2172-packages/
2173-  db/
2174-  planner/
2175-  schemas/
2176-  step-templates/
2177-  logging/
2178-  git-tools/
2179-  checkpointing/
2180-ops/
2181-  nginx/
2182-  sql/
2183-  launchd/
2184-  scripts/
2185-docs/
2186-  decisions/
2187-```
2188-
2189-## 26.1 建议最先创建的文件
2190-
2191-为了方便并行开发，初始仓库至少应包含：
2192-
2193-```text
2194-README.md
2195-DESIGN.md
2196-ops/sql/schema.sql
2197-ops/sql/migrations/0001_init.sql
2198-ops/nginx/baa-conductor.conf
2199-ops/launchd/so.makefile.baa-conductor.plist
2200-ops/launchd/so.makefile.baa-worker-runner.plist
2201-apps/control-api-worker/src/index.ts
2202-apps/conductor-daemon/src/index.ts
2203-apps/worker-runner/src/index.ts
2204-packages/schemas/src/index.ts
2205-packages/db/src/index.ts
2206-packages/planner/src/index.ts
2207-packages/step-templates/src/index.ts
2208-packages/logging/src/index.ts
2209-packages/checkpointing/src/index.ts
2210-```
2211-
2212-## 27. mini 与 mac 上的 launchd
2213-
2214-因为 mini 和 mac 都是 macOS，推荐用 `launchd` 做进程守护。
2215-
2216-建议服务：
2217+当前只维护 `mini` 的 launchd 安装：
2218 
2219 - `so.makefile.baa-conductor`
2220-- `so.makefile.baa-worker-runner`
2221 - 可选 `so.makefile.baa-status-api`
2222+- 可选 `so.makefile.baa-worker-runner`
2223 
2224-建议行为：
2225-
2226-- 开机或登录自动启动
2227-- 失败自动拉起
2228-- 日志写文件
2229-
2230-conductor 的示例参数：
2231-
2232-```xml
2233-<array>
2234-  <string>/usr/bin/env</string>
2235-  <string>node</string>
2236-  <string>/Users/george/code/baa-conductor/apps/conductor-daemon/dist/index.js</string>
2237-  <string>--host</string>
2238-  <string>mini</string>
2239-  <string>--role</string>
2240-  <string>primary</string>
2241-</array>
2242-```
2243-
2244-## 27.1 建议的 launchd 路径
2245-
2246-推荐安装路径：
2247-
2248-- repo 中的 plist 源文件：`ops/launchd/*.plist`
2249-- 用户级安装路径：`~/Library/LaunchAgents/`
2250-- 如果需要开机登录前启动，可改用系统级 `/Library/LaunchDaemons/`
2251-
2252-推荐 label：
2253-
2254-- `so.makefile.baa-conductor`
2255-- `so.makefile.baa-worker-runner`
2256-- `so.makefile.baa-status-api`
2257-
2258-## 27.2 环境变量
2259-
2260-建议 conductor 与 worker 服务使用：
2261-
2262-```text
2263-BAA_CONDUCTOR_HOST=mini
2264-BAA_CONDUCTOR_ROLE=primary
2265-BAA_CONTROL_API_BASE=https://control-api.makefile.so
2266-BAA_CONDUCTOR_PUBLIC_BASE=https://conductor.makefile.so
2267-BAA_CONDUCTOR_LOCAL_API=http://127.0.0.1:4317
2268-BAA_CONDUCTOR_PRIVATE_BASE=http://100.71.210.78:4317
2269-BAA_CONDUCTOR_PEER_BASE=http://100.112.239.13:4317
2270-BAA_RUNS_DIR=/Users/george/code/baa-conductor/runs
2271-BAA_WORKTREES_DIR=/Users/george/code/baa-conductor/worktrees
2272-BAA_LOGS_DIR=/Users/george/code/baa-conductor/logs
2273-BAA_TMP_DIR=/Users/george/code/baa-conductor/tmp
2274-BAA_NODE_ID=mini-main
2275-BAA_SHARED_TOKEN=replace-me
2276-```
2277-
2278-mac 上至少需要不同的变量：
2279-
2280-- `BAA_CONDUCTOR_HOST`
2281-- `BAA_CONDUCTOR_ROLE`
2282-- `BAA_NODE_ID`
2283-- `BAA_CONDUCTOR_PRIVATE_BASE`
2284-- `BAA_CONDUCTOR_PEER_BASE`
2285-
2286-说明：
2287-
2288-- `BAA_CONTROL_API_BASE` 仍然指向 Cloudflare Worker，自身不走 Tailscale
2289-- 节点间与内网调用统一使用 `BAA_CONDUCTOR_PRIVATE_BASE` / `BAA_CONDUCTOR_PEER_BASE`
2290-- 不要把 `mini.tail0125d.ts.net` 或 `mbp.tail0125d.ts.net` 写进运行配置
2291-
2292-## 28. 安全模型
2293-
2294-## 28.1 Control API
2295-
2296-- conductor 和 worker 调用必须鉴权
2297-- pause、resume、drain、promote 等操作需要更强的 admin 鉴权
2298-
2299-## 28.2 直连节点域名
2300-
2301-- `mini-conductor.makefile.so` 和 `mac-conductor.makefile.so` 必须受保护
2302-- 使用 Basic Auth、IP allowlist 或两者同时使用
2303-
2304-## 28.3 日志
2305-
2306-日志中可能包含：
2307-
2308-- prompts
2309-- diffs
2310-- 文件路径
2311-- 测试输出
2312-
2313-规则：
2314-
2315-- 尽可能做 secrets 脱敏
2316-- 不公开暴露原始日志
2317-
2318-## 29. 可观测性
2319-
2320-每个 conductor 应暴露：
2321-
2322-- `/healthz`
2323-- `/readyz`
2324-- `/rolez`
2325-- 如果后续需要，可加 `/metrics`
2326-
2327-有用的状态字段：
2328-
2329-- controller id
2330-- role
2331-- lease holder
2332-- lease expiry
2333-- active runs
2334-- queue depth
2335-- paused mode
2336-
2337-## 30. 故障场景
2338-
2339-## 30.1 Mini 在空闲状态下死亡
2340-
2341-- lease 过期
2342-- mac 抢到 lease
2343-- 队列继续运行
2344-
2345-## 30.2 Mini 在 Codex Step 中死亡
2346-
2347-- run lease 过期
2348-- mac 成为 leader
2349-- mac 读取最新 checkpoint
2350-- mac 回放 checkpoint 或直接重跑该 step
2351-
2352-## 30.3 Mac 在 Standby 状态下死亡
2353-
2354-- 不影响服务
2355-
2356-## 30.4 D1 暂时不可用
2357-
2358-leader 应：
2359-
2360-- 停止 claim 新工作
2361-- 在安全前提下继续监管本地正在运行的 worker
2362-- 持续尝试重连
2363-- 在控制面未确认前，不进行不安全写入
2364-
2365-## 30.5 浏览器 UI 失效
2366-
2367-- 自动化仍然继续
2368-- 只是人类控制面临时不可用
2369-
2370-## 30.6 VPS 死亡
2371-
2372-如果 VPS 掉了：
2373-
2374-- 公网入口失效
2375-- 公网域名无法再直接做运维操作
2376-- 只要 mini 与 mac 还能访问 `control-api.makefile.so`，内部调度仍可继续
2377-- 只要 tailnet 还通，运维仍可通过 Tailscale `100.x` 直达节点
2378-
2379-推荐处理：
2380-
2381-- 不要因为公网入口消失就主动停掉 worker 集群
2382-- 单独修复 VPS
2383-
2384-## 30.7 Cloudflare Worker 或 D1 退化
2385-
2386-如果 control API 不可用：
2387-
2388-- leaders 停止 claim 新工作
2389-- 已在本地运行的 steps 可以在安全前提下继续
2390-- 不应盲目提交不可逆的调度状态
2391-
2392-恢复规则：
2393-
2394-- control API 恢复后，conductors 要把本地 run 状态与 D1 重新对账
2395-
2396-## 31. 建议的 API 返回码
2397-
2398-- `200` 正常读取
2399-- `202` 接受异步创建
2400-- `409` 节点健康但不是 leader，不能执行写操作
2401-- `423` task 或 step 被 lease 锁住
2402-- `503` 控制平面退化
2403-
2404-## 32. 建议的初始端口
2405-
2406-以下只是建议值：
2407-
2408-- conductor 本地 HTTP API: `4317`
2409-- status API: `4318`
2410-- 可选 metrics: `4319`
2411-
2412-## 33. 时序流程
2413-
2414-## 33.1 Task 创建流程
2415-
2416-1. human 在可见 Claude `control` 中下指令
2417-2. `control` 通过 control API 创建 task
2418-3. leader conductor 取到 task
2419-4. leader 选择模板或 planner
2420-5. 持久化 plan
2421-6. steps 进入 runnable
2422-
2423-## 33.2 Step 执行流程
2424-
2425-1. leader claim 下一个 runnable step
2426-2. leader 分配 worker 与 worktree
2427-3. worker 启动
2428-4. worker 把日志持续写到本地
2429-5. conductor 写 heartbeat 与 checkpoints
2430-6. worker 退出
2431-7. conductor 把 step 标记为 complete 或 failed
2432-
2433-## 33.3 Failover 流程
2434-
2435-1. mini lease 过期
2436-2. mac 获取 leadership
2437-3. mac 扫描未完成 steps
2438-4. mac 基于 checkpoints 恢复 runnable 工作
2439-
2440-## 33.4 人工 Pause 与接管流程
2441-
2442-1. 人在 Firefox 插件或状态页点击 `Pause`
2443-2. 浏览器调用 `POST /v1/system/pause`
2444-3. control API 更新 D1 中的 `system_state`
2445-4. 当前 leader 观察到 mode 变化
2446-5. leader 停止启动新的 steps
2447-6. 人开始和可见 Claude `control` 对话
2448-7. 人点击 `Resume`
2449-8. leader 恢复调度
2450-
2451-## 34. 建议的 MVP 范围
2452-
2453-第一阶段至少要包含：
2454-
2455-1. 仓库骨架
2456-2. D1 schema 与 migration scripts
2457-3. control API Worker
2458-4. conductor lease loop
2459-5. task 与 step 持久化
2460-6. 一个带本地日志流的 Codex step runner
2461-7. 一个 shell step runner
2462-8. pause、resume、drain
2463-9. mini -> mac 的基础 failover
2464-10. Firefox 插件按钮接到 control API
2465-
2466-## 35. 建议的并行开发拆分
2467-
2468-这一节的目的就是让多个 Codex worker 立刻开始并行干活。
2469-
2470-每个 task 只能有一个分支和一个 owner。
2471-
2472-## 35.0 协作规则
2473-
2474-这些规则在多 Codex 并行时必须遵守。
2475-
2476-### 分支规则
2477-
2478-- 一个 task 等于一个 branch
2479-- 一个 branch 同时只允许一个 owner
2480-- branch 名由 conductor 或 task 创建方分配
2481-
2482-### Worktree 规则
2483-
2484-- 一个 task 等于一个 worktree
2485-- 不允许两个 worker 共用一个活跃 worktree
2486-
2487-### Write Scope 规则
2488-
2489-每个 task 都必须声明 `write_scope`。
2490-
2491-如果需要修改超出 `write_scope` 的文件：
2492-
2493-- 要么新建 task
2494-- 要么显式修订 scope
2495-
2496-### 全局真相规则
2497-
2498-- task 真相在 D1
2499-- 本地真相在 run 目录
2500-- 对话记录不是 task 真相
2501-
2502-### 热点文件规则
2503-
2504-以下内容应视为协调敏感文件：
2505-
2506-- 根级 lockfile
2507-- 全局 CI 配置
2508-- 共享 schema 文件
2509-- 一旦开始实现后，这份 `DESIGN.md` 本身
2510-
2511-对热点文件的修改应串行化，或提前明确指派。
2512-
2513-## 35.0.1 Task Card 模板
2514-
2515-未来仓库中，每个并行 task 都应该有一个任务卡，例如：
2516-
2517-```md
2518----
2519-task_id: T-004
2520-title: Conductor lease and heartbeat loop
2521-owner: codex-mini-01
2522-branch: feat/T-004-conductor-lease
2523-repo: /Users/george/code/baa-conductor
2524-base_ref: main
2525-write_scope:
2526-  - apps/conductor-daemon/**
2527-  - packages/db/**
2528-depends_on:
2529-  - T-002
2530-  - T-003
2531-acceptance:
2532-  - leader lease acquisition works
2533-  - standby nodes do not schedule
2534-  - lease renewal tests added
2535-status: in_progress
2536----
2537-```
2538-
2539-## 35.0.2 完成报告模板
2540-
2541-task 完成后，worker 应至少回报：
2542-
2543-```md
2544-task_id: T-004
2545-branch: feat/T-004-conductor-lease
2546-base_ref: <commit>
2547-files_changed:
2548-  - apps/conductor-daemon/src/index.ts
2549-  - packages/db/src/lease.ts
2550-commands_run:
2551-  - pnpm test
2552-result:
2553-  - passed targeted tests
2554-risks:
2555-  - none
2556-```
2557-
2558-## 35.1 Task A: 仓库骨架
2559-
2560-Branch：
2561-
2562-- `feat/T-001-repo-scaffold`
2563-
2564-Scope：
2565-
2566-- 仓库目录结构
2567-- package manager 配置
2568-- 根配置
2569-- 初始 README
2570-
2571-不要改：
2572-
2573-- D1 SQL
2574-- Nginx 配置
2575-- Firefox 插件
2576-
2577-## 35.2 Task B: D1 Schema 与 Migrations
2578-
2579-Branch：
2580-
2581-- `feat/T-002-d1-schema`
2582-
2583-Scope：
2584-
2585-- `ops/sql/**`
2586-- `packages/db/**`
2587-
2588-不要改：
2589-
2590-- conductor runtime
2591-- worker runner
2592-
2593-## 35.3 Task C: Control API Worker
2594-
2595-Branch：
2596-
2597-- `feat/T-003-control-api`
2598-
2599-Scope：
2600-
2601-- `apps/control-api-worker/**`
2602-
2603-依赖：
2604-
2605-- Task B
2606-
2607-## 35.4 Task D: Conductor Lease 与 Heartbeat Loop
2608-
2609-Branch：
2610-
2611-- `feat/T-004-conductor-lease`
2612-
2613-Scope：
2614-
2615-- `apps/conductor-daemon/**`
2616-- `packages/db/**`
2617-
2618-依赖：
2619-
2620-- Task B
2621-- Task C
2622-
2623-## 35.5 Task E: Worker Runner 与本地日志流
2624-
2625-Branch：
2626-
2627-- `feat/T-005-worker-runner`
2628-
2629-Scope：
2630-
2631-- `apps/worker-runner/**`
2632-- `packages/logging/**`
2633-
2634-不要改：
2635-
2636-- Nginx
2637-- Firefox 插件
2638-
2639-## 35.6 Task F: Checkpoint 与 Git Diff Snapshots
2640-
2641-Branch：
2642-
2643-- `feat/T-006-checkpointing`
2644-
2645-Scope：
2646-
2647-- `packages/checkpointing/**`
2648-- worker-runner 集成
2649-
2650-依赖：
2651-
2652-- Task E
2653-
2654-## 35.7 Task G: Planner 抽象与模板
2655-
2656-Branch：
2657-
2658-- `feat/T-007-planner`
2659-
2660-Scope：
2661-
2662-- `packages/planner/**`
2663-- `packages/step-templates/**`
2664-
2665-## 35.8 Task H: Nginx 与 VPS 运维
2666-
2667-Branch：
2668-
2669-- `feat/T-008-ops-nginx`
2670-
2671-Scope：
2672-
2673-- `ops/nginx/**`
2674-- 部署文档
2675-
2676-## 35.9 Task I: Firefox 插件 Pause 与 Resume
2677-
2678-Branch：
2679-
2680-- `feat/T-009-firefox-pause`
2681-
2682-Scope：
2683-
2684-- Firefox 插件集成文档
2685-- 浏览器状态协议
2686-
2687-这部分现在统一收口在本仓库的 Firefox 插件子目录里，但协议仍然在这里定义清楚。
2688-
2689-## 35.10 Task J: Status API 与基础 UI
2690-
2691-Branch：
2692-
2693-- `feat/T-010-status-api`
2694-
2695-Scope：
2696-
2697-- `apps/status-api/**`
2698-
2699-## 35.11 Task K: launchd 与本地 Runtime 布局
2700-
2701-Branch：
2702-
2703-- `feat/T-011-launchd-runtime`
2704-
2705-Scope：
2706-
2707-- `ops/launchd/**`
2708-- 本地 runtime 路径文档
2709-
2710-## 35.12 Task L: 鉴权与 Token 模型
2711-
2712-Branch：
2713-
2714-- `feat/T-012-auth-model`
2715-
2716-Scope：
2717-
2718-- worker 鉴权设计
2719-- token 校验中间件
2720-- 角色定义
2721-
2722-## 36. Runbook
2723-
2724-这一节故意写成运维操作说明，是真正出问题时要照着用的。
2725-
2726-## 36.1 初始部署 Runbook
2727-
2728-1. 部署 Cloudflare Worker 与 D1
2729-2. 创建 D1 schema
2730-3. 部署 `control-api.makefile.so`
2731-4. 配置 DNS 记录
2732-5. 在 VPS 安装 Nginx 配置
2733-6. 验证 `mini-conductor.makefile.so` 与 `mac-conductor.makefile.so`
2734-7. 在 mini 安装 launchd 服务
2735-8. 在 mac 安装 launchd 服务
2736-9. 启动 mini conductor 并确认拿到 lease
2737-10. 启动 mac conductor 并确认处于 standby
2738-11. 验证浏览器 `Pause` 与 `Resume`
2739-
2740-## 36.2 计划内切换 Runbook
2741+脚本：
2742 
2743-从 mini 安全切到 mac：
2744+- [`scripts/runtime/install-launchd.sh`](./scripts/runtime/install-launchd.sh)
2745+- [`scripts/runtime/check-launchd.sh`](./scripts/runtime/check-launchd.sh)
2746+- [`scripts/runtime/check-node.sh`](./scripts/runtime/check-node.sh)
2747+- [`scripts/runtime/reload-launchd.sh`](./scripts/runtime/reload-launchd.sh)
2748 
2749-1. 把全局模式设为 `draining`
2750-2. 等活跃 runs 正常结束或至少完成 checkpoint
2751-3. 确认 mini 没有未收口的可变工作
2752-4. demote mini
2753-5. promote mac，或让 mac 自然获取 lease
2754-6. 确认 mac 的 `GET /rolez` 返回 `leader`
2755-7. 把全局模式改回 `running`
2756+## 7. Nginx 与 DNS
2757 
2758-## 36.3 紧急故障切换 Runbook
2759+当前只维护一个公网入口：
2760 
2761-如果 mini 突然挂掉：
2762+- `conductor.makefile.so`
2763 
2764-1. 确认 mini heartbeat 已过期
2765-2. 等 lease 超时
2766-3. 确认 mac 已获取 lease
2767-4. 查看未完成 runs
2768-5. 基于 checkpoints 恢复或重跑当前 steps
2769+回源关系：
2770 
2771-## 36.4 切回 Mini 的 Runbook
2772+- `conductor.makefile.so` -> VPS Nginx -> `100.71.210.78:4317`
2773 
2774-mini 恢复后：
2775+相关文件：
2776 
2777-1. 先让 mini 继续保持 standby
2778-2. 修复原始故障
2779-3. 选择一个低峰窗口
2780-4. 把系统设为 `draining`
2781-5. drain mac
2782-6. promote mini
2783-7. 确认 mini 成为 leader
2784-8. 把系统切回 `running`
2785+- [`ops/nginx/baa-conductor.conf`](./ops/nginx/baa-conductor.conf)
2786+- [`scripts/ops/baa-conductor.env.example`](./scripts/ops/baa-conductor.env.example)
2787+- [`scripts/ops/cloudflare-dns-plan.mjs`](./scripts/ops/cloudflare-dns-plan.mjs)
2788+- [`scripts/ops/nginx-sync-plan.mjs`](./scripts/ops/nginx-sync-plan.mjs)
2789 
2790-## 37. 接下来立刻要做的事
2791+## 8. 保留的内部复杂度
2792 
2793-下一波开发建议按这个顺序推进：
2794+当前主线仍保留一部分内部 `leader` / `lease` 语义，因为：
2795 
2796-1. 创建代码骨架
2797-2. 实现 D1 schema
2798-3. 实现 control API
2799-4. 实现 conductor lease
2800-5. 实现一个 worker runner
2801-6. 实现 checkpoints
2802-7. 接上 Firefox 的 pause 与 resume
2803-8. 补上 VPS Nginx 配置
2804+- control plane 已经围绕该模型实现
2805+- 单节点下它仍能正常工作
2806+- 现在不值得为替代项目到来前再做一次大规模重构
2807 
2808-做到这里，这套系统就能真正支撑多 Codex 并行执行。
2809+但这些内部语义不再代表“主备切换能力是当前目标”。
2810 
2811-## 38. 总结
2812+## 9. 当前真正关心的事情
2813 
2814-这份设计刻意把以下东西拆开：
2815+- `mini` 本地服务可持续启动
2816+- `control-api` 与 `conductor` 对外可达
2817+- 浏览器插件可以控制系统模式
2818+- `status-api` 的真相来源逐步收口
2819 
2820-- 人类对话
2821-- 自动化对话
2822-- 规划
2823-- 编排
2824-- 执行
2825+## 10. 历史回溯
2826 
2827-durable 核心是：
2828+需要查看旧的主备设计、切换脚本和历史文档时：
2829 
2830-- D1 存共享真相
2831-- conductor 做确定性编排
2832-- Codex 做短生命周期 step worker
2833-- 本地日志加周期性 checkpoint
2834-- mini 做首选 leader，mac 做 standby
2835+- git tag: `ha-failover-archive-2026-03-22`
2836 
2837-后续所有实现都应该以这个模型为准。
2838+当前主线不再保留这些内容。