gofer-job

name

gofer-job

description

Submit a task to a host gofer server with `gofer job` — to run a command in the HOST environment, do multi-service / integration / external-callback testing the container can't do alone, or invoke a host AI agent (codex/claude). Use when you are inside a dev container and need something executed on the host machine (outside the container), or when a workspace's CLAUDE.md points to gofer / an old codex-bridge for host tasks. Covers submit (--runner local), reading logs, sync vs async, agent/runner selection, project discovery, and troubleshooting.

gofer job：从容器向主机提交任务

你在 docker 容器里时，无法直接触达主机环境/主机网络/主机上的其他服务。主机上跑着 gofer server，你用 gofer job 把任务提交过去执行：--runner local 在主机跑，--runner <worker-id> 在某个 worker 跑。这取代了"写 tmp 通知外部 codex / curl host-bridge"这类旧机制。

0. 先判断能不能用（30 秒自检）

command -v gofer            # gofer 是否在 PATH(常见 /workspace/go/bin/gofer)
gofer job list 2>&1 | head  # 能列出 job 即说明: .env 已自动加载 + 连上了主机 server

• gofer 启动时会自动加载 $GOFER_CONFIG_DIR/.env，把 GOFER_SERVER_ADDR / GOFER_SERVER_TOKEN 注入；gofer job 的 --server/--token 默认就读这两个 env。正常情况零配置、无需手动 source、无需传 token。
• 若 gofer job list 报连不上/401 → 主机 server 没起或 .env 不对，见 §6；这种环境就别用本 skill。

1. 找到本工作空间的 project key

提交必须带 -p <project>（容器内通常无本地 config，无法按 cwd 自动探测）。按优先级发现：

1. 本工作空间的 CLAUDE.md：通常已写明 gofer 项目 key（最权威）。
2. gofer job list 输出的 PROJECT 列（看历史 job 用的哪个 key）。
3. gofer project list（仅当容器内有本地 gofer config 时有效）。

project key 因工作空间而异，不要硬编码。同一个 key 必须已在主机 server注册（否则 unknown project）。

2. 最常用：在主机执行命令并等结果

# --runner local=主机执行；--sync=server 等到终态返回；--cwd=项目内相对目录；--title=便于 list 辨识
gofer job run -p <project> -a exec --runner local --sync \
  --cwd <相对项目根的子目录> --title "<一句话任务名>" \
  -- bash -lc '<你的命令>'

返回里有 status 和 exit_code（exit_code != 0 即失败）。stdout/stderr 要单独取：

gofer job logs <job-id>

两条必守约定（最常见的坑）

① 工作目录用 --cwd（相对项目根），不要在命令里 cd 绝对路径。 job 在哪台机器执行，路径就按那台机器的项目根解析：同一 project 的容器路径（/d/work/...）与主机路径（D:\work\...）不同。命令里写死容器绝对路径，--runner local 在主机执行时目录不存在 → 报错。--cwd 由 gofer 按执行机的项目根安全拼接，天然跨主机/容器；默认 . 即项目根。

# ✗ 错：命令里 cd 容器绝对路径——runner=local 在主机跑时该路径不存在
... -- bash -lc 'cd /d/work/inhere/<ws>/java-biz-dev/xxx && git pull --rebase'
# ✓ 对：用 --cwd 相对项目根，命令只管业务逻辑
... --cwd java-biz-dev/xxx -- bash -lc 'git pull --rebase 2>&1 | tail -3'

② 每个任务带 --title "<一句话>"。 不带 title 的 job 在 gofer job list 里只有 id/agent/runner，难以辨识是什么任务。一句话标题让任务列表可读、便于回溯定位。

3. job 子命令速查

命令	用途
gofer job run（别名 add）	提交任务
gofer job logs <id>	读 stdout/stderr
gofer job show <id>	查状态/元数据
gofer job watch <id>	实时跟随状态+日志直到结束（异步任务用）
gofer job list（别名 ls）	列 job（-p / --tag / --agent / --runner / --since 过滤）
gofer job cancel <id>	取消运行中的 job
gofer job rerun <id>	用原请求重提（新幂等 key）

4. agent 与 runner

agent（-a，取决于该 project 在 server 配的 allowed_agents，常见 exec/codex/claude）：

• exec：直接跑命令，命令放 -- 之后：-a exec -- <cmd> <args...>。
• codex / claude：跑 AI agent，提示词用 --prompt "..." 或任务文件 -f task.md（YAML frontmatter + 正文）。

runner（--runner，默认 local）：

• local → 主机执行（需要主机环境/多服务联调时用它）。
• <worker-id> → 对应 worker 执行（容器自带的活你直接在 bash 跑即可，一般无需绕 worker）。

5. 同步 vs 异步

• 同步 --sync：server 阻塞到终态返回（默认上限 ~30s，可 --wait-timeout <秒>）。短任务、要立刻拿结果用它。
• 异步（不加 --sync）：立即返回 job id，再 gofer job watch <id> 跟随 / gofer job show <id> 轮询。长任务（构建、联调、FFmpeg 等）用它，并配 --timeout <秒> 限制执行时长。

6. 排障

现象	处理
unknown project "xxx"	project 没在主机 server 注册；用 §1 确认正确 key。
worker 执行报 project/agent/runner 不允许	同一 project 要在 server 和 worker 两边都注册；allowed_runners 两边相反：server 侧含 worker-runner 名，worker 侧含 local。gofer config validate worker 自检。
连不上 / 401	主机 gofer server 未起，或 $GOFER_CONFIG_DIR/.env 的 GOFER_SERVER_ADDR/TOKEN 与 server 不一致。
有 job 但看不到输出	--sync 只回状态；输出用 gofer job logs <id>。

备注

• 本 skill 是通用机制说明；本工作空间的具体 project key / 可用 agent 以该工作空间 CLAUDE.md 为准。
• gofer 自身（serve/worker/daemon 等）的部署细节属于运维范畴，不在本 skill；按需查对应工作空间的 gofer 文档或 bd 记忆。