.pouch/skills/agent-runtime/references/config.md

Agent Runtime 配置

文件与合并

提交 .pouch/agent.yaml。若存在 .pouch/agent.local.yaml，按 mapping 深度合并；local 文件只能覆盖同名字段，不能增加未声明的顶层结构。合并后的配置必须再次完整校验。

schemaVersion: 1
locations:
  local-app:
    environment: local
    host: local
    project: git:git.yumee.top/bloggarden/app
    path: /home/ace/code/draft2/blogger/app
  remote-ios:
    environment: macmini
    host: runtime:14b6d8ce-4528-49f4-8d46-56b266a5ad69
    project: git:git.yumee.top/bloggarden/app
    path: /Users/laily/workrepo/bloggarden-app
profiles:
  android-builder:
    role: build
    cli: codex
    tier: standard
    model: gpt-5
    reasoningEffort: medium
    permissionMode: workspace-write
  ios-builder:
    role: build
    cli: codex
    tier: strong
    model: gpt-5
    reasoningEffort: high
    permissionMode: workspace-write
bindings:
  builder.android:
    adapter: builder
    location: local-app
    profile: android-builder
    makefile: makefile.builder
    target: android
    session:
      lifecycle: persistent
  builder.ios:
    adapter: builder
    location: remote-ios
    profile: ios-builder
    makefile: makefile.builder
    target: ios
    session:
      lifecycle: persistent

字段原则

• binding、location、profile ID 只允许小写字母、数字和 -，binding 用一个或多个点 分隔；ID 是路由名，不是任意 shell 文本。
• environment: local 使用当前 Orca runtime；远程环境使用已保存的名称。host 必须 是 local 或 runtime:<environment-id>，由 Orca 查询结果证明，不能凭主机名猜测。
• project 必须是 Orca project id 或精确 display name；path 必须是目标机器上的绝对 路径。解析 worktree 时四者必须同时匹配，标题、分支和 basename 不能消歧。
• profile 的 CLI 只能来自 ACK/tester 共同 allowlist：codex、cursor-agent、grok、 omp、pi。model 为安全模型 ID 或 null；reasoningEffort 为 low|medium|high|xhigh 或 null；权限只允许 read-only|workspace-write。
• builder 的 target 只能是 make target 名；makefile 只能是项目内相对文件名。脚本、 远端命令、环境变量和凭据由 builder/Orca adapter 提供，不能写入此配置。
• session.lifecycle 为 persistent 或 ephemeral。persistent 只表示允许显式跨 session attach/resume，不表示自动复用旧 terminal。

旧版 .pouch/tester/local.yaml 和 .pouch/ack/agents.yaml 继续兼容。迁移时应让它们 由 adapter 从 common profile/location 生成或覆盖，不能删除旧 receipt、fingerprint 或 tester 的每轮 terminal 清理语义。