Execgocli Adapter

ExecGo execgocli Adapter Skill（详细 SOP）

本技能描述如何在本仓库根目录（execgo 模块根）构建并使用 execgocli，通过 模式 A（adapter 翻译并执行）或 模式 B（直传 TaskGraph）驱动 ExecGo。不要在 skill 内重复实现 HTTP；只配置环境、拼 JSON、调用 CLI 或等价 HTTP。

1. 你在本仓库里要认出的东西

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）

6. 稳定 JSON 外壳（所有子命令 stdout）

成功：

{ "ok": true, "data": { } }

失败：

{ "ok": false, "error": { "message": "…", "status_code": 400, "body": "…" } }

解析规则： 先判断 ok；false 时向用户展示 error.message 与 error.body（若有）。

7. 子命令与 HTTP 映射（必背）

act / translate / submit 的 JSON 从 stdin 读：管道或 here-doc 均可。

8. 模式 A：推荐流水线（给代理逐步执行）

1. export EXECGO_URL=http://127.0.0.1:8080（或实际地址）。
2. execgocli tools → 从 data.tools[] 取 action_kind / 名称，生成 AgentAction。
3. 构造 AgentActionRequest（见本目录 reference-json-contract.md），action_id 建议与任务 id 规则一致且唯一。
4. echo '<JSON>' \| execgocli act → 从 data.task_ids 取 id。
5. 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 可设置 EXECGO_URL 多跑一段 smoke
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. 故障排查速查

更细表见同目录 ../ 下可扩展的 troubleshooting（若你 fork 可自建）；当前以主文档与上表为准。

Maintainers: 更新 CLI 行为时请同步修改 reference-commands.md 与本 SKILL 的表格；并更新 docs/en|zh/reference/execgo-cli-contract.md。