60 lines
3.2 KiB
Markdown
60 lines
3.2 KiB
Markdown
---
|
||
name: agent-runtime
|
||
description: >-
|
||
维护项目通用 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](references/config.md)。需要实际解析或
|
||
创建工作区时使用 `scripts/agent.py`，不要手工拼接 Orca JSON：
|
||
|
||
```bash
|
||
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。
|
||
|
||
```bash
|
||
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，并报告需要补的字段。
|
||
|
||
## 验证
|
||
|
||
- `python3 <skill-dir>/scripts/agent.py validate --root <project-root>` 通过。
|
||
- remote binding 必须能按 `environment + host + path + project` 精确找到 Orca worktree。
|
||
- 新 binding 只增加配置和对应 adapter 支持，不复制一套 skill 或修改固定枚举。
|