# Tester Agent 执行目标

只在用户要运行测试时读取本文件。测试目录仍由发起运行的项目决定；`execution`
不再单独作为终端配置。`agent` 统一决定使用哪个 Agent、在哪个 Orca 环境、哪个
项目/目录中执行。

## 配置

推荐在项目根统一配置：

```yaml
bindings:
  tester.test:
    adapter: tester
    location: local-app
    profile: test-agent
```

`locations` 和 `profiles` 的定义见共享 `agent-runtime`。tester adapter 只把它 materialize
到本轮兼容配置；每轮 terminal 仍然新建并在结束时关闭，不能因为 binding 是 persistent
就复用测试 terminal。

`catalog.yaml` 提供可提交的默认值，`.pouch/tester/local.yaml` 可以覆盖同名字段。
机器名、远程环境、项目路径和 Agent 选择优先写在 `local.yaml`，不要把个人机器路径
或临时 Agent 选择提交到项目。

```yaml
agent:
  environment: ""       # Orca 保存的远程环境；空值表示当前环境
  host: local            # 该环境中的目标 host
  project: ""            # Orca project id 或名称；可由 terminal id 反查填入
  path: ""               # 目标机器上的项目绝对路径；为空表示当前项目
  role: test              # tester 固定为 test
  cli: codex              # codex/cursor-agent/grok/omp/pi
  tier: standard         # standard/strong
  model: null             # 精确模型 ID；null 表示使用该 CLI 的默认模型
  reasoningEffort: medium # low/medium/high/xhigh 或 null
  permissionMode: workspace-write # read-only/workspace-write
```

`HOST` 仍然是被测服务地址，不能用来表示执行机器。执行目标没有配置时，使用当前
项目根目录和默认 test Agent，但仍然创建一个全新的 terminal；不查找、不复用已有
terminal。

旧版 `execution` 配置仍可读取并迁移为 `agent` 的环境、host、path 字段，但新配置
不再保存自由 `command` 或 `wait`。Agent CLI 的启动参数由 tester/Orca 的可信映射
生成，不能从项目文本中拼接 shell 命令。

## 解析 Agent、项目和目录

用户可以直接给 tester 以下任一种定位信息：

- Orca project id 或项目名称；
- Orca terminal id，例如 `term_...`；
- 不提供定位信息，使用当前项目。

有定位信息时优先使用解析脚本，避免手工拼接 Orca JSON：

```bash
python3 <skill-dir>/scripts/resolve_agent.py \
  --root <project-root> --terminal <terminal-handle> [--environment <name>] --write

python3 <skill-dir>/scripts/resolve_agent.py \
  --root <project-root> --project <project-id-or-name> [--environment <name>] --write

python3 <skill-dir>/scripts/resolve_agent.py \
  --root <project-root> --project <project-id-or-name> \
  --environment <name> --path <absolute-target-path> --write
```

脚本会跨已保存的 environment 查询 terminal/project，写入
`.pouch/tester/local.yaml` 的 `agent` mapping，并打印配置更新列表。没有 `--write` 时只解析
和预览，适合先检查结果。

1. 如果给出 terminal id，枚举当前和已保存的 Orca environment，调用
   `orca terminal show --environment <env> --terminal <handle> --json`。从结果读取
   `executionHostId`、`worktreeId`、`worktreePath`、`agentIdentity`，terminal id 只
   用于定位，不能作为本轮执行 terminal 复用。
2. 如果给出 project id/名称，枚举对应 environment 的 project 和 worktree，先精确匹配
   project id/name，再精确匹配 worktree id/name/path。一个项目有多个 worktree 时，
   展示候选并停下；用户可以补充 `--path` 或改用 terminal id，不按分支或路径猜测。
3. 将解析结果写入 `local.yaml.agent`。保留用户已有的 `HOST`、授权和其它字段；只
   更新 agent 配置。terminal 推导出的 `cli` 只在 metadata 明确提供
   `agentIdentity` 时覆盖已有值。模型、reasoning、权限等无法从 Orca 证明的字段，
   优先保留已有配置，否则使用 tester 模板默认值，并在更新列表中明确展示；不能把它们
   伪装成 terminal 的真实 metadata。
4. `path` 为空时解析为发起运行的项目根目录；配置了远程 environment 时，必须解析
   为该远程环境上的绝对路径。
5. 用 Orca 查询目标项目/worktree 是否已注册，匹配必须是
   `environment + host + 规范化 path` 的精确匹配，不得按标题、分支或模糊路径猜测。
6. 找不到 Orca 项目记录时，直接为该已有目录建立项目记录：

   - 当前环境的 Git 目录：`orca repo add --path <path> --json`
   - 保存的远程环境：在命令上加 `--environment <agent.environment>`。

   `host` 不是当前环境的 local 时，先用 `orca host list --json` 确认目标主机；如果
   该目录只能通过已有 project setup 导入，则使用 `orca project setup-existing-folder`
   为该 project/host 建立 setup，再重新查询 worktree。不能把一个 local worktree
   当成远程 host 的项目使用。

   之后重新查询并取得 `worktree` selector。项目准备失败要记为
   `environment-fail`，不要继续创建 terminal。

这里的“没有项目就创建”指创建/登记 Orca 的项目记录，不是删除或重建用户目录，
也不是创建新的 Git worktree。目标目录必须已经存在且包含待测项目；如果目录本身
不存在，停止并说明需要先在目标机器准备项目。

## 配置更新结果

完成解析和 `local.yaml.agent` 初始化后，立即向用户展示更新后的生效配置列表。
这是配置更新结果，不是测试启动前的人工确认门槛。列表至少包含：

```text
## tester Agent 配置更新结果

来源: terminal:<handle> | project:<selector> | current-project
Agent: <cli>
角色 / 档位: test / standard
模型: <model 或 n/a>
推理强度: <reasoningEffort 或 n/a>
权限: <read-only | workspace-write>
Orca 环境: <environment>
执行节点: <host>
项目: <project id>（<项目名称>）
目录: <absolute path>
Worktree: <worktree id>
Terminal: 每轮新建，结束后关闭，不复用当前 terminal

以上是本次更新后的 Agent 生效配置；如需调整，直接修改 `local.yaml.agent` 后重新运行 tester。
```

只有项目或目录存在多个候选时才标记 `待确认` 并停下，要求补充 `--path` 或 terminal
id，不能按分支或路径猜测。配置更新本身不创建 terminal，也不产生测试副作用。

## Terminal 生命周期

每次 tester 运行只创建一个新的 terminal，整轮用完后关闭。不能为了方便复用已有
terminal，也不能关闭运行开始前已经存在的 terminal。

创建命令的形状如下。`<worktree-selector>` 必须是上一步按环境、主机和路径精确解析
出的 worktree selector；不要直接用可能跨机器冲突的 `path:<target-path>` 猜测。
Agent 的 CLI、模型、推理强度和权限必须来自 `agent` 的结构化字段，由 Orca/Agent
启动映射转换为实际启动参数；不要把自由 `command`、argv 或 shell 片段写入配置。
如果当前 Orca 版本只有 `orca terminal create --command` 接口，也只能使用 skill
维护的 CLI allowlist 映射生成这个参数，不能把配置中的任意字符串直接作为命令执行。
从 JSON 读取返回的 `handle`，后续只使用这个 handle；不要重新 list 后凭预览选择
terminal。

- 脚本、浏览器、移动模拟器都交给新建的 test Agent；发送简短的用例范围和执行要求，
  目标 Agent 在目标目录读取 tester catalog。不要把完整 `cases/` 塞进 prompt。
- `permissionMode=read-only` 只能执行不产生测试产物的用例；需要写运行快照、构建或
  设备状态变更时使用 `workspace-write`，但仍受 tester 的风险授权约束。
- terminal 创建成功后，无论测试通过、失败、超时、用户中断还是读取输出失败，
  都必须执行清理：

  ```text
  orca terminal close --terminal <created-handle> --json
  ```

  `close` 是删除本次临时 terminal 的操作，不是删除项目或 worktree。清理失败时
  保留 handle，向用户报告 `cleanup-fail`，不得换一个 handle 再关闭。

如果创建失败，没有 terminal 需要清理，直接报告 `environment-fail`。如果创建成功
但中途出现异常，把清理放在 finally 语义的收尾步骤中，再生成运行记录。

## 运行记录

在运行快照顶层保存本次 Agent 执行目标，至少包含：

```yaml
agent:
  environment: ""
  host: local
  project: "..."
  path: /absolute/project/path
  role: test
  cli: codex
  tier: standard
  model: null
  reasoningEffort: medium
  permissionMode: workspace-write
  worktree_id: "..."
  terminal_handle: "..."
  terminal_created: true
  terminal_closed: true
```

不要把 token、配对码或完整环境变量写入快照。terminal 输出只保留能支持结果判定
的摘要；测试结果仍按主运行规范使用 `pass`、`fail`、`environment-fail`、`skipped`
和 `not-run`。