声明该跑什么

每一条事实都从一份声明开始。oberth.yaml 说清这个 checkout 跑什么；清单由人确认，引擎不会从它碰巧看见的进程里推断启动命令。

从 worktree 开始

oberth init 从当前 checkout 生成一份可以直接审阅的起步清单。它听见的端口和项目文件里的声明只以注释出现，留给人的决定。监听扫描失败不会中断 init：注释写的是 listening unknown，带上观察错误码和下一步——因为“看不见”不是“没有东西在监听”。

生成与预览

oberth init
oberth init --dry-run

--dry-run 只预览不落盘；--json 是给机器的形状。扫描失败时，项目自己的声明和可复制的条目形状仍然保留。

agent 起草，人采纳

起草与采纳

oberth init draft claude
oberth init adopt --dry-run --diff

init draft [agent] 让配置好的本地 agent 起草清单。option-berth 不判断、不联网、不写盘：成功只产出一份草稿，默认归档在 ~/.option-berth/drafts/。init adopt 才是写入 oberth.yaml 的那一步。已有清单必须明确给 --replace 或 --merge；--dry-run 与 --diff 先展示结果。草稿不是授权。

最小的清单

oberth.yaml · hello-worktree

name: hello-worktree
services:
  - name: api
    cmd: python3 -u api.py
    port: auto
    health: /health
  - name: worker
    cmd: python3 -u worker.py
    depends_on: [api]
    env:
      API_URL: ${api.url}

最小清单里的字段
字段	它承诺什么
`name`	项目组名。同一个仓库的两个 worktree 发布为 `name` 与 `name@worktree`。
`services[].cmd`	长时间运行的命令，按 argv 拆分，不经过隐藏的 shell。
`port`	一个固定数字，或 `auto`：引擎为每次运行分配端口并注入 `PORT`。
`health`	HTTP 路径、TCP 端口或命令。端口先开、协议后好的服务用命令形式。
`depends_on`	启动顺序与就绪等待：依赖真的就绪后，后继服务才启动。
`env`	字面值，以及 `${api.url}` 这类从本 worktree 地址簿展开的引用。

会改变行为的字段

prepare: 与 prepare_inputs:: 在长时间运行的 cmd: 之前跑一条前置命令。声明的输入自上次成功后没有变化时，下一次 up 会跳过它，而不是重新装依赖。
sources:: 用来判断进程跑的是不是当前代码的文件。命中的变化由 status 发布为 code_changed_since_start；sources: [] 为自行热加载的服务关掉这项检查。
ready_timeout:: 服务自己的就绪预算（Go duration，默认 30s）。后继服务与 up --wait 都用它；prepare: 不计入其中。
env_file:: 启动时读取、从不回写的 dotenv 风格文件。相对路径从清单目录解析，所以多个 worktree 可以共享 checkout 外的同一份文件。
machine:: 本项目只观察、从不启动或停止的依赖：数据库、中间件、别人负责的服务。
workspace:: 指向另一个 checkout 中服务的地址引用。它提供 ${name.url}，不参与启动、停止或 depends_on。

清单不能做什么

编辑本页