扩展 Takuto Core

你常常会需要一些没有内置在官方镜像里的工具 —— kubectl、terraform、某个内部厂商 CLI，或某个锁定版本的 claude。Takuto Core 有一套三层扩展模型，外加用于纯运行时微调的第四条路径。挑一条与你需求相符的。

你的需求	机制	写在哪里
添加单个二进制 CLI（kubectl、terraform、厂商 CLI）	Provisioning	`config.toml` 中的 `[provisioning].install_commands`
把某个内置工具锁定到特定版本	Provisioning（PATH 遮蔽）	`[provisioning].install_commands`
添加系统包（apt）或库	自定义 Dockerfile	新的 Dockerfile `FROM ghcr.io/takuto-team/takuto-core:latest`
在各处添加一个环境变量	Compose 覆盖	`docker-compose.override.yml`
挂载一个额外的宿主目录	Compose 覆盖	`docker-compose.override.yml`

指导原则：内置 = 已宣传功能所必需，Provisioning = 管理员偏好，自定义镜像 = 专门的操作系统层面需求。

机制 1 —— `[provisioning].install_commands`

最常见的情况。在每次 Takuto 启动时，入口点会运行一遍受 SHA 门控的安装流程：

它对 install_commands 列表做哈希。
如果哈希与上次成功运行匹配 → 跳过（快路径；没有变化时每次启动都走这条）。
如果不同 → 它会导出 MAESTRO_TOOLS_BIN=/opt/maestro-tools/bin，并以 root 身份通过 bash -c 运行每条命令。单条命令失败只记录警告，不会中止。只有在完全成功时才记录新的哈希，因此部分失败会在下次启动重试。

这些工具会落进 maestro-tools Docker 卷，以只读方式 bind-mount 进每个 worker、编辑器和 run-command container，且 /opt/maestro-tools/bin 排在 $PATH 最前 —— 于是你放进那里的任何东西在各处都可用，并且会遮蔽同名的内置工具。

幂等性是你的责任

只要列表变化就会重新运行 —— 包括你添加一条命令时（现有的那些也会重跑）。给每条命令加上存在性检查作为守卫：

[provisioning]
install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/kubectl" ] || (curl -fsSLo "$MAESTRO_TOOLS_BIN/kubectl" https://dl.k8s.io/release/v1.31.0/bin/linux/amd64/kubectl && chmod +x "$MAESTRO_TOOLS_BIN/kubectl")',
]

重启之后，每个 workflow 都能直接调用 kubectl。

把 `claude` 锁定到特定版本

[provisioning]
install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/claude" ] || (npm install -g --prefix "$MAESTRO_TOOLS_BIN/.npm" @anthropic-ai/claude-code@2.1.140 && ln -sf "$MAESTRO_TOOLS_BIN/.npm/bin/claude" "$MAESTRO_TOOLS_BIN/claude")',
]

PATH 优先级让锁定的版本胜过内置的 @latest。要回退：移除该行，重启，然后 rm /opt/maestro-tools/bin/claude。

安装一个私有厂商 CLI

install_commands = [
  '[ -f "$MAESTRO_TOOLS_BIN/mycli" ] || curl -fsSL -H "Authorization: token $MYCO_TOKEN" https://internal.example.com/cli/mycli-v2.tgz | tar -xz -C "$MAESTRO_TOOLS_BIN"',
]

在 takuto.env 中设置 MYCO_TOKEN，让安装命令能读到它。

不改配置也强制重装

SHA 门控会在列表未变时跳过重跑。要强制来一次（例如你怀疑某个二进制坏了）：

docker exec --user root maestro-core-maestro-1 \
    rm /opt/maestro-tools/.provisioning-sha
docker compose restart maestro

清空所有定制

docker compose down
docker volume rm maestro-core_maestro-tools
docker compose up -d

机制 2 —— 自定义 Dockerfile

把它用于系统包（apt 库、守护进程），或任何会触及多个操作系统目录的东西（/etc、/usr/share、/var/lib）。maestro-tools 卷只写一个 bin/ 目录，所以对于系统级安装，provisioning 是错误的工具。

# my-takuto.Dockerfile
FROM ghcr.io/takuto-team/takuto-core:latest
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
        awscli postgresql-client \
    && rm -rf /var/lib/apt/lists/*
USER maestro

把它接进 docker-compose.yml：

services:
  maestro:
    build:
      context: .
      dockerfile: my-takuto.Dockerfile

然后 docker compose build maestro && docker compose up -d。

机制 3 —— `docker-compose.override.yml`

Compose 会自动合并 docker-compose.override.yml。把它用于无需重新构建的纯运行时微调。

额外的环境变量：

services:
  maestro:
    environment:
      - GH_HOST=github.example.com   # internal GHE instance
      - MY_API_TOKEN=...

额外的 bind mount：

services:
  maestro:
    volumes:
      - /host/shared-cache:/home/maestro/.cache/shared:ro

Compose 覆盖只影响 maestro 服务。要把某个挂载或环境变量传播到衍生出的 worker container，引擎里的 worker 卷 / 透传环境变量列表必须包含它们 —— 参见 Takuto Core 源码中的 WORKER_VOLUMES 和 PASSTHROUGH_ENV。

工具清单一览

内置（已宣传功能所必需）：node、npm、Rust 工具链（cargo/rustfmt/clippy）、git、gh、acli、jq、docker CLI、iptables、 claude、cursor-agent、codex、opencode、openvscode-server、mise，以及 Playwright/Chromium 库。
Provisioning 默认项（管理员可锁定/替换/禁用）：单二进制工具，如 Figma 和 Lokalise 的 CLI。
已移除（通过自定义镜像处理）：像 AWS CLI v2 这类只有少数部署才需要的工具。

provisioning 故障排查

“我的命令重启时没运行。” SHA 门控会跳过未变的列表 —— 改点东西（哪怕一条注释）来改变哈希，或者 rm /opt/maestro-tools/.provisioning-sha 再重启。
“worker 看不到我的工具。” 检查它是否落进了卷（docker exec maestro-core-maestro-1 ls /opt/maestro-tools/bin/），以及 /opt/maestro-tools/bin 是否排在 worker $PATH 的最前。在启动日志里找 [maestro-provisioning] … WARN 行以排查安装失败。

更多内容参见故障排查。