| name | execgocli-adapter |
| description | Operate ExecGo's mature-agent adapter via the stdlib CLI execgocli: discover tools (GET /adapters/tools), submit actions (POST /adapters/actions), poll tasks, optional ensure-running for Docker/runtime. Use when the repo is github.com/iammm0/execgo or a fork containing cmd/execgocli and the user mentions Codex, Claude Code, EXECGO_URL, adapter.v1, or /adapters/actions. |
ExecGo execgocli Adapter Skill（详细 SOP）
本技能描述如何在本仓库根目录（execgo 模块根）构建并使用 execgocli，通过 模式 A（adapter 翻译并执行）或 模式 B（直传 TaskGraph）驱动 ExecGo。不要在 skill 内重复实现 HTTP；只配置环境、拼 JSON、调用 CLI 或等价 HTTP。
1. 你在本仓库里要认出的东西
| 路径 | 作用 |
|---|
cmd/execgo | 控制面 HTTP 服务（/adapters/*, /tasks, /health） |
cmd/execgocli | 给 Codex / CC 用的薄 CLI，仅标准库 |
internal/execgocli | CLI 的 HTTP/轮询/ensure 实现 |
pkg/adapter | adapter.v1 与 AgentActionRequest 结构 |
docs/zh/reference/execgo-cli-contract.md | CLI JSON 契约（中） |
docs/en/reference/execgo-cli-contract.md | 同上（英） |
docs/zh/integration/mode-a-cli.md | 模式 A 快速开始（中） |
docs/examples/execgocli-agent-wrappers.md | 薄封装思路 |
2. 前置条件
- Go 工具链可构建本仓库（见根目录
go.mod）。
- 运行
execgocli 前，通常需要已可访问的 ExecGo 进程，除非你只用 ensure-running 去尝试本机 docker compose 拉起（见第 7 节）。
3. 构建
在仓库根（含 go.mod）执行：
go build -o execgocli ./cmd/execgocli
go build -o execgo ./cmd/execgo
将 execgocli 放入 PATH 或技能里写绝对路径。
4. 启动控制面（execgo）
./execgo
./execgo -addr :8080
- 环境变量以
pkg/config 为准：常见 EXECGO_ADDR、数据目录 EXECGO_DATA_DIR 等。
- 使用
runtime.* 类 action 时，ExecGo 进程需能访问 execgo-runtime：在运行 execgo 的 shell 中设置 EXECGO_RUNTIME_URL（与下文 CLI 的 EXECGO_RUNTIME_URL 探活目标一致，常见本机为 http://127.0.0.1:18080 以免与 8080 控制面抢端口）。
5. 环境变量（execgocli）
| 变量 | 典型值 | 含义 |
|---|
EXECGO_URL | http://127.0.0.1:8080 | 控制面基址，必填语义上强烈建议显式设置 |
EXECGO_RUNTIME_URL | http://127.0.0.1:18080 | 仅 ensure-running -with-runtime 或文档默认；须与 execgo 进程内 runtime 地址一致 |
EXECGO_COMPOSE_DIR | 本仓库根绝对路径 | ensure-running 可尝试 docker compose -f docker-compose.yml up -d |
EXECGO_RUNTIME_IMAGE | 例如本地 build 的 tag | 非空时 ensure-running 或尝试 docker run 拉 runtime（见实现与文档） |
EXECGO_RUNTIME_SOURCE | execgo-runtime 克隆路径 | 失败提示中的 cargo 说明会引用 |
6. 稳定 JSON 外壳（所有子命令 stdout）
成功：
{ "ok": true, "data": { } }
失败：
{ "ok": false, "error": { "message": "…", "status_code": 400, "body": "…" } }
解析规则： 先判断 ok；false 时向用户展示 error.message 与 error.body（若有）。
7. 子命令与 HTTP 映射（必背）
| CLI | HTTP |
|---|
execgocli capabilities | GET /adapters/capabilities |
execgocli tools | GET /adapters/tools |
execgocli act | POST /adapters/actions；body 为 stdin 或 -file |
execgocli translate | POST /adapters/translate |
execgocli submit | POST /tasks（模式 B，TaskGraph JSON） |
execgocli wait -task-ids id1,id2 | 轮询 GET /tasks/{id} 直至终态 |
execgocli health | GET /health |
execgocli ensure-running | 本地探活/可选 docker；--with-runtime 时探 {EXECGO_RUNTIME_URL}/readyz |
act / translate / submit 的 JSON 从 stdin 读：管道或 here-doc 均可。
8. 模式 A：推荐流水线（给代理逐步执行）
export EXECGO_URL=http://127.0.0.1:8080（或实际地址）。execgocli tools → 从 data.tools[] 取 action_kind / 名称，生成 AgentAction。- 构造 AgentActionRequest（见本目录
reference-json-contract.md），action_id 建议与任务 id 规则一致且唯一。
echo '<JSON>' \| execgocli act → 从 data.task_ids 取 id。execgocli wait -task-ids <id> -timeout 2m → 确认 all_terminal 为 true 或查 data.tasks[].status（success / failed / skipped）。
9. 模式 B（简讯）
execgocli translate：只拿 task_graph，不执行。execgocli submit：直传 TaskGraph 到 POST /tasks。
10. 最小可运行 JSON 示例（act）
{
"adapter": "codex",
"agent_id": "agent-1",
"session_id": "sess-1",
"action_id": "demo-1",
"action": {
"kind": "os.noop",
"input": {}
},
"metadata": {
"source": "skill-example"
}
}
action_id 常映射为图内 task id，以便 wait 使用同一 id（与引擎行为一致，详见 adapter 与集成测试）。
11. 与 Codex / Claude Code 的接法（原则）
- 不要在 skill 里再写一版 REST 客户端。
- Skill 只做：设置
EXECGO_URL、把上述 JSON 交给 execgocli act 的 stdin、读 stdout 的 JSON、错误时回显、可选把 translation_trace 落盘。
- 具体命令行包装样本见同目录
integration-codex.md 与 integration-claude-code.md。
12. 验收脚本（本仓库）
./scripts/validate-execgo-cli.sh
EXECGO_URL=http://127.0.0.1:8080 ./scripts/validate-execgo-cli.sh
13. 安全与治理（推广期默认）
os.shell 使用白名单/允许列表为默认更安全的姿态；开放策略需显式环境开关（以仓库实现与 docs/zh/reference/promotion-security.md 为准）。- 请求中尽量带齐
agent_id / session_id / action_id / metadata 以便审计与 translation_trace 对齐。
- 需更强隔离时用
runtime.command / runtime.script 并保证 execgo-runtime 可达。
14. 退出码（execgocli）
0 成功。wait 在超时且未全终态时可能非 0（见 reference-commands.md）。2 用法/未知子命令。- 其他非零见参考页或
docs/.../execgo-cli-contract.md。
15. 故障排查速查
| 现象 | 处理 |
|---|
ok: false 且 4xx | 读 error.body；多为 JSON 字段或 action.kind 非法 |
connection refused | ExecGo 未起或 EXECGO_URL 错 |
runtime 类一直 pending / 失败 | 检查 EXECGO_RUNTIME_URL 在 execgo 进程 与 runtime 实际监听 一致；curl …/readyz |
ensure-running 失败 | 看返回 JSON 的 manual_hints；无 Docker/无权限/端口占用 |
更细表见同目录 ../ 下可扩展的 troubleshooting（若你 fork 可自建）；当前以主文档与上表为准。
Maintainers: 更新 CLI 行为时请同步修改 reference-commands.md 与本 SKILL 的表格；并更新 docs/en|zh/reference/execgo-cli-contract.md。
