baa-conductor

T-S009.md

  1# Task T-S009：把 conductor upstream/public API base 从 legacy 名字里解耦
  2
  3## 直接给对话的提示词
  4
  5读 `/Users/george/code/baa-conductor/tasks/archive/T-S009.md` 任务文档，完成开发任务。
  6
  7如需补背景，再读：
  8
  9- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
 10- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 11- `/Users/george/code/baa-conductor/scripts/runtime/install-launchd.sh`
 12- `/Users/george/code/baa-conductor/scripts/runtime/check-launchd.sh`
 13- `/Users/george/code/baa-conductor/scripts/runtime/check-node.sh`
 14- `/Users/george/code/baa-conductor/docs/runtime/environment.md`
 15- `/Users/george/code/baa-conductor/docs/runtime/launchd.md`
 16
 17## 当前基线
 18
 19- 仓库：`/Users/george/code/baa-conductor`
 20- 分支：`main`
 21- 提交：`d1c9090`
 22- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
 23
 24## 建议分支名
 25
 26- `chore/rename-conductor-public-api-base`
 27
 28## 目标
 29
 30把 conductor upstream/public API base 的配置入口从 legacy `control-api` 命名里解耦，同时保留兼容别名，不破坏现有安装副本和脚本。
 31
 32## 背景
 33
 34- 当前主线已经不再把 `control-api.makefile.so` 当默认控制面。
 35- 但 `conductor-daemon`、`install-launchd.sh`、`check-launchd.sh`、`check-node.sh` 仍用 `BAA_CONTROL_API_BASE` / `--control-api-base` 这套历史名字表示 conductor 自己的 upstream/public API base。
 36- 这会继续误导协作者，把“legacy 名字残留”误读成“系统仍依赖 legacy control plane”。
 37
 38## 涉及仓库
 39
 40- `/Users/george/code/baa-conductor`
 41
 42## 范围
 43
 44- 给 conductor 增加 dedicated 的 env / CLI 名字
 45- 把运行脚本、帮助文本、测试和文档切到新名字
 46- 保留 `BAA_CONTROL_API_BASE` / `--control-api-base` 作为兼容别名，并明确优先级和弃用语义
 47
 48## 路径约束
 49
 50- 这个任务只处理 conductor upstream/public API base 的命名收口
 51- 不要顺手改 `status-api` 的 truth-source 逻辑
 52- 不要扩展成新的部署设计或域名迁移任务
 53
 54## 推荐实现边界
 55
 56建议优先做：
 57
 58- 为 `conductor-daemon` 引入 dedicated 名字，例如 `BAA_CONDUCTOR_PUBLIC_API_BASE` 和 `--public-api-base`
 59- 让旧名字继续可用，但只作为兼容别名，并在帮助文本/文档里标明 legacy
 60- 同步更新 launchd 安装/检查脚本与测试
 61
 62## 允许修改的目录
 63
 64- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
 65- `/Users/george/code/baa-conductor/scripts/runtime/`
 66- `/Users/george/code/baa-conductor/docs/runtime/`
 67- `/Users/george/code/baa-conductor/docs/api/README.md`
 68
 69## 尽量不要修改
 70
 71- `/Users/george/code/baa-conductor/apps/status-api/`
 72- `/Users/george/code/baa-conductor/apps/codexd/`
 73- `/Users/george/code/baa-conductor/tasks/`
 74
 75## 必须完成
 76
 77### 1. 引入 dedicated 配置名字
 78
 79- conductor 运行时代码应支持 dedicated env / CLI 名字
 80- 旧名字继续兼容，但不能再被描述为 canonical 配置名
 81
 82### 2. 保持兼容行为可解释
 83
 84- 明确新旧名字同时存在时谁优先
 85- 帮助文本、脚本 usage、runtime 文档都要写清兼容关系
 86
 87### 3. 补测试和验证
 88
 89- 至少覆盖 CLI / env 解析和脚本预期
 90- 验证安装/检查脚本没有被这次改名打坏
 91
 92## 需要特别注意
 93
 94- 不要破坏现有 launchd 安装副本读取旧环境变量的兼容性
 95- 不要顺手改 service 名字或 plist label
 96- 与根脚本任务并行时，尽量不要修改同一批总览文档
 97
 98## 验收标准
 99
100- conductor 代码和脚本已有 dedicated 配置名
101- `BAA_CONTROL_API_BASE` / `--control-api-base` 只剩兼容别名语义
102- conductor 测试和 runtime 脚本检查通过
103- `git diff --check` 通过
104
105## 推荐验证命令
106
107- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon test`
108- `bash -n /Users/george/code/baa-conductor/scripts/runtime/install-launchd.sh`
109- `bash -n /Users/george/code/baa-conductor/scripts/runtime/check-launchd.sh`
110- `bash -n /Users/george/code/baa-conductor/scripts/runtime/check-node.sh`
111- `git -C /Users/george/code/baa-conductor diff --check`
112
113## 交付要求
114
115完成后请说明：
116
117- 修改了哪些文件
118- 新旧配置名分别是什么，兼容优先级如何
119- 跑了哪些测试
120- 还有哪些剩余风险