feat(agent-runtime): unify agent bindings and sessions

2026-10-12 13:22:47 +08:00
parent 32da57d19b
commit 558c6facc2
15 changed files with 759 additions and 8 deletions
@@ -0,0 +1,73 @@
+# Agent Runtime 配置
+
+## 文件与合并
+
+提交 `.pouch/agent.yaml`。若存在 `.pouch/agent.local.yaml`，按 mapping 深度合并；local
+文件只能覆盖同名字段，不能增加未声明的顶层结构。合并后的配置必须再次完整校验。
+
+```yaml
+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 清理语义。