.pouch/skills/agent-runtime/SKILL.md

name, description

name	description
agent-runtime	维护项目通用 Agent 运行配置、环境绑定、Orca worktree 与跨 session terminal； 适用于 builder.android、builder.ios、tester.test、ack.dev 等可扩展绑定。 不负责具体构建、测试或 ACK 闭环。

Agent Runtime：统一环境、Agent 与工作区

本 skill 是 builder、tester、ACK 和 iOS tester 共用的配置层。每个 Git 项目在自己的 根目录维护 .pouch/agent.yaml；父仓库与 submodule 各自拥有配置，不跨仓库继承。机器 专属覆盖放 .pouch/agent.local.yaml，运行记录放 .pouch/agent/runs/，两者都不提交。

配置模型

• locations：执行环境、Orca project、目标机器上的绝对路径；不放模型和命令。
• profiles：CLI、模型、reasoning effort、权限和档位；不放路径和 secrets。
• bindings：任意安全的 namespace.name，绑定一个 adapter、location、profile 和 adapter 目标。builder.android、builder.ios、builder.harmony 不需要修改代码即可并存。
• adapter 目前允许 builder、tester、ack。adapter 的具体执行规则仍由对应 skill 负责；本层只提供解析、worktree 和 session 生命周期。
• reasoningEffort 是规范字段；不要新增 effect、自由 command、argv、shell、 env 或 token 字段。

完整字段、合并和安全规则见 references/config.md。需要实际解析或 创建工作区时使用 scripts/agent.py，不要手工拼接 Orca JSON：

python3 <skill-dir>/scripts/agent.py validate --root <project-root>
python3 <skill-dir>/scripts/agent.py show --root <project-root> --binding builder.android
python3 <skill-dir>/scripts/agent.py worktree resolve --root <project-root> --binding builder.ios
python3 <skill-dir>/scripts/agent.py worktree create --root <project-root> \
  --binding builder.ios --name writes-ios --base main

Session

builder 绑定可通过统一入口创建持久 terminal；返回的 run 记录包含 binding、profile hash、环境、worktree、terminal handle 和 source commit。跨 session 只能显式 status、 attach、stop 或 resume，不能自动复用不明 terminal。tester 的每轮 terminal 仍然 是临时的，ACK 仍然必须走其带 fingerprint/receipt 的 launcher。

python3 <skill-dir>/scripts/agent.py run start --root <project-root> --binding builder.android
python3 <skill-dir>/scripts/agent.py run status --root <project-root> --run <run-id>
python3 <skill-dir>/scripts/agent.py run attach --root <project-root> --run <run-id>
python3 <skill-dir>/scripts/agent.py run resume --root <project-root> --run <run-id>
python3 <skill-dir>/scripts/agent.py run stop --root <project-root> --run <run-id>

run start 只为 builder 生成受控的 make 命令；tester/ACK 的执行入口仍由对应 skill 适配器提供。环境、项目或精确 worktree 缺失时 fail closed，并报告需要补的字段。

tester 的 test-preflight 一次性节点入口使用 JSON stdin/stdout：

printf '%s\n' '{"binding":"tester.android","operation":"platform_probe","platform":"android","node":"local"}' \
  | python3 <skill-dir>/scripts/agent.py run exec --root <project-root>

入口只接受 platform_probe、network_probe、install、start 四种受控操作，命令 由 adapter 固定生成，不读取配置中的 command/argv/shell/env/token。local binding 可执行 固定的只读平台/网络探针和 test-preflight 已授权的 Android 安装/启动；非 local binding 先按 environment + host + project + path 解析 Orca worktree，再通过 Orca 的临时 terminal 执行固定的节点 runner，并从协议标记读取一个 JSON 结果，结束后关闭该 terminal。远程 iOS 的安装/启动要求调用方把产物放在 Mac 节点可读路径，并在 matrix 的 artifact.remote_path 中声明；协调机上的本地路径不会被错误地当成 Mac 路径。任何 transport、节点工具链或远端 产物缺失都返回结构化 environment-fail，绝不在协调节点执行平台命令或伪造 ready。

验证

• python3 <skill-dir>/scripts/agent.py validate --root <project-root> 通过。
• remote binding 必须能按 environment + host + path + project 精确找到 Orca worktree。
• 新 binding 只增加配置和对应 adapter 支持，不复制一套 skill 或修改固定枚举。