baa-conductor

T-021-runtime-bootstrap.md

  1---
  2task_id: T-021
  3title: launchd 安装脚本与 Runtime Bootstrap
  4status: done
  5branch: feat/T-021-runtime-bootstrap
  6repo: /Users/george/code/baa-conductor
  7base_ref: main@458d7cf
  8depends_on:
  9  - T-011
 10  - T-013
 11  - T-015
 12  - T-017
 13write_scope:
 14  - ops/launchd/**
 15  - docs/runtime/**
 16  - scripts/runtime/**
 17updated_at: 2026-03-22T01:08:59+0800
 18---
 19
 20# T-021 launchd 安装脚本与 Runtime Bootstrap
 21
 22## 目标
 23
 24把现有 launchd 模板和 runtime 文档推进到“有实际 bootstrap/install/check 脚本可执行”的程度，减少手工部署步骤。
 25
 26## 本任务包含
 27
 28- 在 `scripts/runtime/**` 下补 runtime 目录初始化脚本
 29- 补 launchd 安装、重载、检查的辅助脚本
 30- 让 `docs/runtime/**` 与脚本行为保持一致
 31- 如有必要，小幅修正 `ops/launchd/**` 模板中的占位项说明
 32
 33## 本任务不包含
 34
 35- 修改 app 业务代码
 36- 实际在本机加载 launchd 服务
 37- 修改 Nginx 或 Cloudflare DNS
 38
 39## 建议起始文件
 40
 41- `docs/runtime/README.md`
 42- `docs/runtime/launchd.md`
 43- `docs/runtime/layout.md`
 44- `ops/launchd/*.plist`
 45- `scripts/runtime/`
 46
 47## 交付物
 48
 49- 可执行的 bootstrap/install/check 脚本
 50- 与脚本一致的 runtime / launchd 文档
 51- 更低摩擦的本地部署流程
 52
 53## 验收
 54
 55- `plutil -lint ops/launchd/so.makefile.baa-conductor.plist`
 56- `plutil -lint ops/launchd/so.makefile.baa-worker-runner.plist`
 57- `plutil -lint ops/launchd/so.makefile.baa-status-api.plist`
 58- 如果新增 shell 脚本：`bash -n scripts/runtime/*.sh`
 59
 60## 更新要求
 61
 62完成时更新 frontmatter 的：
 63
 64- `status`
 65- `base_ref`
 66- `updated_at`
 67
 68并补充下面这些内容：
 69
 70## files_changed
 71
 72- `coordination/tasks/T-021-runtime-bootstrap.md`
 73- `docs/runtime/README.md`
 74- `docs/runtime/environment.md`
 75- `docs/runtime/launchd.md`
 76- `docs/runtime/layout.md`
 77- `ops/launchd/so.makefile.baa-conductor.plist`
 78- `ops/launchd/so.makefile.baa-worker-runner.plist`
 79- `ops/launchd/so.makefile.baa-status-api.plist`
 80- `scripts/runtime/bootstrap.sh`
 81- `scripts/runtime/check-launchd.sh`
 82- `scripts/runtime/common.sh`
 83- `scripts/runtime/install-launchd.sh`
 84- `scripts/runtime/reload-launchd.sh`
 85
 86## commands_run
 87
 88- `npx --yes pnpm install`
 89- `chmod +x scripts/runtime/bootstrap.sh scripts/runtime/install-launchd.sh scripts/runtime/reload-launchd.sh scripts/runtime/check-launchd.sh`
 90- `bash -n scripts/runtime/*.sh`
 91- `plutil -lint ops/launchd/so.makefile.baa-conductor.plist ops/launchd/so.makefile.baa-worker-runner.plist ops/launchd/so.makefile.baa-status-api.plist`
 92- `git diff --check`
 93- `./scripts/runtime/bootstrap.sh --repo-dir "$TMP_REPO"`
 94- `./scripts/runtime/install-launchd.sh --repo-dir "$TMP_REPO" --home-dir "$TMP_HOME" --install-dir "$TMP_INSTALL" --node mini --all-services --shared-token test-token`
 95- `./scripts/runtime/check-launchd.sh --repo-dir "$TMP_REPO" --home-dir "$TMP_HOME" --install-dir "$TMP_INSTALL" --node mini --all-services --shared-token test-token`
 96- `./scripts/runtime/reload-launchd.sh --install-dir "$TMP_INSTALL" --all-services --dry-run`
 97
 98## result
 99
100- 已新增 `scripts/runtime/bootstrap.sh`、`install-launchd.sh`、`check-launchd.sh`、`reload-launchd.sh` 与共享 helper，使 runtime 目录初始化、plist 安装副本渲染、静态校验、`launchctl` 重载都有可执行脚本。
101- 已把 `docs/runtime/**` 改为以脚本驱动流程为准，补充 `--node`、`--repo-dir`、`--shared-token`、`--scope` 等输入约定，并明确默认只安装 `conductor`、其它模板需显式 opt-in。
102- 已小幅修正 `ops/launchd/*.plist` 说明并补入 `BAA_STATE_DIR`，同时在临时 repo 上完成 bootstrap -> install -> check -> reload(dry-run) 的整链验证。
103
104## risks
105
106- 本任务只验证了 plist 渲染、静态检查和 dry-run `launchctl` 命令，没有在本机真实 `bootstrap` 任何 launchd 服务；实际目标机上仍需再做一次权限和 domain 验证。
107- `worker-runner` 与 `status-api` 模板现在可以被脚本渲染和校验，但是否作为常驻服务启用仍取决于各自宿主进程接线进度；默认流程因此只安装 `conductor`。
108
109## next_handoff
110
111- 在真实 `mini` / `mac` 节点上按文档顺序执行 `bootstrap.sh`、`npx --yes pnpm -r build`、`install-launchd.sh`、`check-launchd.sh`，确认安装副本和 runtime 目录都落在预期路径。
112- 真正准备加载服务时，先运行 `reload-launchd.sh --dry-run` 复核命令；确认无误后再去掉 `--dry-run`。若后续 runner/status 宿主进程落地，可再显式加 `--service worker-runner` 或 `--service status-api`。
113
114开始时建议直接把 `status` 改为 `in_progress`。
115
116做完并推送后：
117
118- 如果等待整合，改为 `review`
119- 如果确认结束，改为 `done`