tiltup

用途

Tilt Up 用于在开发环境中启动 Tilt，并处理 Tiltfile 报错与开发环境 bootstrap 过程。它适用于需要启动 tilt、调试 Tiltfile 错误或引导开发环境的场景。

核心原则（始终生效）

凡是处理 Tiltfile、Tilt 错误或开发环境 bootstrap 时，均遵循以下原则：

修复 Tiltfile 本身，而非症状。
直接修复配置源：Tiltfile、Dockerfile、k8s manifest 或 helm values。
不添加 shell 变通方案：不使用包装脚本、|| true、try/except pass。
不硬编码本应动态的端口、路径、主机名、镜像标签或容器名。
不添加掩盖真实错误的回退：资源失败必须可见。
不针对不稳定依赖添加 sleep/retry 循环，而是通过 resource_deps() 或 k8s_resource(deps=) 修复依赖顺序。
不为 Tilt 已处理的就绪状态添加轮询，改用 k8s_resource(readiness_probe=) 或探针配置。
以声明方式表达依赖：端口冲突修复端口分配来源；资源顺序使用 resource_deps()；环境变量使用 silo.toml 或 gen-env 输出；镜像可用性使用 image_deps 或 deps。
利用 Tilt 的实时重载：编辑 Tiltfile、源码或 Kubernetes manifest 后，Tilt 会自动获取变更，不重启 tilt up。仅在 Tilt 版本升级、端口/主机配置变更、崩溃、集群上下文切换时重启。

使用方式（明确启动 Tilt 时的工作流）

第 1 步：评估当前状态

检查 tilt 是否已运行：

PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
zmx list --short 2>/dev/null | grep -q "^${PROJECT}-tilt$"

若已运行，通过 tilt get uiresources -o json 检查健康状态并跳到第 3 步。检查所需环境文件（.localnet.env、.env.local、silo.toml）：若存在 silo.toml，使用 silo up 路径；若存在 gen-env 脚本，先运行它；若都没有，查看项目 README 中的 bootstrap 说明。检查 k3d 集群或 Docker 前置条件。

第 2 步：在 zmx 中启动 Tilt

PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
SESSION="${PROJECT}-tilt"

if zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
  echo "Tilt session already exists: $SESSION"
else
  zmx run "$SESSION" 'tilt up'
  echo "Started tilt in zmx session: $SESSION"
fi

对于 silo 项目，使用 silo up 代替 tilt up。

第 3 步：监控 Bootstrap

轮询收敛：等待 10 秒进行初始资源注册；每 15 秒轮询一次，最多 20 次。包含 docker-compose 容器健康状态（composeResourceInfo.healthStatus）——一个 Up 但 unhealthy 的 compose 容器会保持 runtimeStatus=ok 而不可见，因此 bootstrap 看似“完成”，但 canton/splice/postgres 可能正在静默地未通过 HEALTHCHECK：

tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error" or .status.updateStatus == "pending" or .status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus) compose=\(.status.composeResourceInfo.healthStatus // "-")"'

跟踪资源状态：pending -> in_progress -> ok。成功条件：所有资源达到 runtime=ok、update=ok（或 not_applicable），且没有 docker-compose 资源的 composeResourceInfo.healthStatus == "unhealthy"。若资源稳定在 error，或有 compose 资源持续 unhealthy，进入第 4 步。对于 unhealthy 的 compose 探针，使用 docker inspect <compose-project>-<svc> --format '{{json .State.Health}}' 读取真实原因——常见情况是挂载的健康检查脚本调用了镜像中不存在的 CLI（服务本身是 up 的；修复探针脚本，不要禁用检查）。

第 4 步：诊断并修复错误

对每个处于 error 状态的资源：使用 tilt logs <resource> --since 2m 读取日志；阅读 Tiltfile 及相关 k8s manifest；在配置中（而非运行进程）定位根因；按上述原则应用修复；Tilt 实时重载——重新轮询状态验证。对同一资源进行 3 次修复迭代仍无进展后：报告错误并提供完整日志；判断是 Tiltfile bug、上游依赖问题还是基础设施问题；不要静默跳过或禁用资源。

第 5 步：报告

## Tilt Status: <healthy|degraded|errored>

**Resources**: X/Y ok
**Session**: zmx $SESSION

### Errors (if any)
- <resource>: <root cause> — <what was fixed or what remains>

适用场景

启动 Tilt 并引导本地开发环境。
调试 Tiltfile 报错并修复配置源。
监控 bootstrap 直到所有资源健康。
处理 docker-compose 资源健康检查失败。

限制

资料未说明该技能适用的平台范围、Tilt 版本要求、收费方式以及超出上述流程之外的额外能力，这些信息暂未提供。