devcontainer-exec

Devcontainer 执行

解析容器一次，然后通过该容器运行项目命令。如果源代码通过绑定挂载映射，在主机上编辑，在容器中执行。.devcontainer/ 目录提示你检查项目的环境策略，而不是让你运行无关的容器任务。

主机：文件工具、git、gh、docker。容器：安装、构建、测试、lint、类型检查、代码生成、迁移、运行应用。

解析并验证

ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
docker ps --filter "label=devcontainer.local_folder=$ROOT" --format '{{.ID}}\t{{.Names}}'

VS Code 和 devcontainer CLI 会将此标签设置在 dev 容器上，而不是 compose 辅助容器上。如果没有完全匹配项，请阅读 resolution.md。如果有多个匹配项，必须询问，不能猜测；仅有共享绑定挂载并不能证明容器身份。

检查选定的容器：

docker inspect -f '{{index .Config.Labels "devcontainer.metadata"}}' <container>
docker inspect -f '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}}{{"\n"}}{{end}}' <container>

• 用户： 当前 devcontainer.json 中显式设置的 remoteUser/containerUser；否则使用元数据片段中最后出现的 remoteUser（若无则使用 containerUser）；否则使用 .Config.User；否则为 root。元数据是一个 JSON 数组，在较旧的容器中则是一个对象。不要认为 .Config.User 反映了编辑器使用的用户：以 root 身份运行可能会导致主机上的文件归 root 所有。
• 工作目录： 根据包含仓库的绑定挂载推导：Destination + (host_path − Source)。不要假设路径是 /workspaces/<repo>，也不要信任为空的 .Config.WorkingDir。使用 docker exec -u <user> -w <container_path> <container> ls 进行验证。
• 由卷提供的工作区： 停止并报告；主机副本不是容器中的真实源代码。

执行

docker exec -i -u <user> -w <container_path> <container> bash -lc '<command>'

在非 TTY 工具中使用 -i，绝不使用 -t。通过 -e KEY=value 传递环境变量，使用容器内的相对路径，并将整个管道作为一条 shell 命令引用。长时间运行的命令仍须通过 docker exec 执行。

如果 shell/PATH 解析失败，请阅读 resolution.md。仅当容器消失或停止时才重新解析，不必在每条命令执行前都重新解析。

生命周期与安全边界

如果没有正在运行的容器，或者需要启动、创建、停止或移除容器，请先阅读 lifecycle.md，然后再采取行动。不要回退到主机执行。进行环境变更或执行会产生持久影响的命令前，必须获得批准；在容器中执行并不能确保测试隔离，也不代表获准访问生产环境。

未经批准，绝不移除容器；批准必须明确指定该容器。agent 所有权标签不代表有权移除，也不能证明容器仅供当前使用；编辑器可能与其他服务共用一个 compose 容器。

输出

在首次运行项目命令前，先报告一次：

Devcontainer: <name> (<short-id>)
Workspace:    <host_path> → <container_path>
Exec:         docker exec -i -u <user> -w <container_path> <name> bash -lc '<cmd>'

完成标准

所有项目执行都使用经过验证的容器、用户和工作区；或者没有运行任何命令，并已说明阻碍。不得回退到主机执行、选择目标不明确、源代码与卷挂载不匹配，或未经批准移除容器。