devcontainer-setup

捆绑的上游支持

支持文件位于相对于技能的路径中。其固定来源、许可证、哈希值和导入变更，请参阅 UPSTREAM-NOTICE.md。

Devcontainer 设置技能

创建预配置的 devcontainer，包含 Claude Code 和特定语言的工具。

适用场景

• 用户要求“设置 devcontainer”或“添加 devcontainer 支持”
• 用户想要一个隔离的 Claude Code 开发环境
• 用户需要配置持久化的隔离开发环境

不适用场景

• 用户已有 devcontainer 配置，只需要修改
• 用户询问一般的 Docker 或容器问题
• 用户想要部署生产容器（此配置仅用于开发）

工作流

flowchart TB
    start([User requests devcontainer])
    recon[1. Project Reconnaissance]
    detect[2. Detect Languages]
    generate[3. Generate Configuration]
    write[4. Write files to .devcontainer/]
    done([Done])

    start --> recon
    recon --> detect
    detect --> generate
    generate --> write
    write --> done

阶段 1：项目勘察

推断项目名称

按顺序检查（使用第一个匹配项）：

1. package.json → name 字段
2. pyproject.toml → project.name
3. Cargo.toml → package.name
4. go.mod → 模块路径（/ 后的最后一段）
5. 回退使用目录名称

转换为 slug：改为小写，并将空格和下划线替换为连字符。

检测语言技术栈

语言	检测文件
Python	pyproject.toml、*.py
Node/TypeScript	package.json、tsconfig.json
Rust	Cargo.toml
Go	go.mod、go.sum

多语言项目

如果检测到多种语言，请按以下优先级顺序配置全部语言：

1. Python - 主要语言，使用 Dockerfile 安装 uv 和 Python
2. Node/TypeScript - 使用 devcontainer 功能
3. Rust - 使用 devcontainer 功能
4. Go - 使用 devcontainer 功能

对于多语言项目的 postCreateCommand，请串联所有设置命令：

uv run /opt/post_install.py && uv sync && npm ci

应将所有检测到的语言对应的扩展和设置合并到配置中。

基础模板功能

基础模板包含：

• Claude Code 和市场插件（anthropics/skills、trailofbits/skills、trailofbits/skills-curated）
• 通过 uv 安装 Python 3.13（快速下载二进制文件）
• 通过 fnm 安装 Node 22（Fast Node Manager）
• 用于基于 AST 的代码搜索的 ast-grep
• 网络隔离工具（iptables、ipset）及 NET_ADMIN 功能
• 现代命令行工具：ripgrep、fd、fzf、tmux、git-delta

---

特定语言的配置

Python 项目

检测方式： pyproject.toml、requirements.txt、setup.py 或 *.py 文件

Dockerfile 附加内容：

基础 Dockerfile 已通过 uv 包含 Python 3.13。如果需要其他版本（从 pyproject.toml 检测），请修改 Python 安装配置：

# Install Python via uv (fast binary download, not source compilation)
RUN uv python install <version> --default

devcontainer.json 扩展：

添加到 customizations.vscode.extensions：

"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff"

添加到 customizations.vscode.settings：

"python.defaultInterpreterPath": ".venv/bin/python",
"[python]": {
  "editor.defaultFormatter": "charliermarsh.ruff",
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

postCreateCommand： 如果存在 pyproject.toml，请串联以下命令：

rm -rf .venv && uv sync && uv run /opt/post_install.py

---

Node/TypeScript 项目

检测方式： package.json 或 tsconfig.json

无需添加 Dockerfile 内容： 基础模板已通过 fnm（Fast Node Manager）包含 Node 22。

devcontainer.json 扩展：

添加到 customizations.vscode.extensions：

"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"

添加到 customizations.vscode.settings：

"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
  "source.fixAll.eslint": "explicit"
}

postCreateCommand： 根据锁文件检测包管理器，并与基础命令串联：

• pnpm-lock.yaml → uv run /opt/post_install.py && pnpm install --frozen-lockfile
• yarn.lock → uv run /opt/post_install.py && yarn install --frozen-lockfile
• package-lock.json → uv run /opt/post_install.py && npm ci
• 没有锁文件 → uv run /opt/post_install.py && npm install

---

Rust 项目

检测： Cargo.toml

需要添加的功能：

"ghcr.io/devcontainers/features/rust:1": {}

devcontainer.json 扩展：

添加到 customizations.vscode.extensions：

"rust-lang.rust-analyzer",
"tamasfe.even-better-toml"

添加到 customizations.vscode.settings：

"[rust]": {
  "editor.defaultFormatter": "rust-lang.rust-analyzer"
}

postCreateCommand： 如果 Cargo.lock 存在，使用锁定构建：

uv run /opt/post_install.py && cargo build --locked

如果没有 lockfile，使用标准构建：

uv run /opt/post_install.py && cargo build

---

Go 项目

检测： go.mod

需要添加的功能：

"ghcr.io/devcontainers/features/go:1": {
  "version": "latest"
}

devcontainer.json 扩展：

添加到 customizations.vscode.extensions：

"golang.go"

添加到 customizations.vscode.settings：

"[go]": {
  "editor.defaultFormatter": "golang.go"
},
"go.useLanguageServer": true

postCreateCommand：

uv run /opt/post_install.py && go mod download

---

参考资料

如需更多指导，请参阅：

• references/dockerfile-best-practices.md - 层优化、多阶段构建、架构支持
• references/features-vs-dockerfile.md - 何时使用 devcontainer 功能与自定义 Dockerfile

---

添加持久卷

在 devcontainer.json 中添加新挂载的模板：

"mounts": [
  "source={{PROJECT_SLUG}}-<purpose>-${devcontainerId},target=<container-path>,type=volume"
]

常见添加项：

• source={{PROJECT_SLUG}}-cargo-${devcontainerId},target=/home/vscode/.cargo,type=volume（Rust）
• source={{PROJECT_SLUG}}-go-${devcontainerId},target=/home/vscode/go,type=volume（Go）

---

输出文件

在项目的 .devcontainer/ 目录中生成以下文件：

1. Dockerfile - 容器构建指令
2. devcontainer.json - VS Code/devcontainer 配置
3. post_install.py - 创建后设置脚本
4. .zshrc - Shell 配置
5. install.sh - 用于管理 devcontainer 的命令行辅助工具（devc 命令）

---

验证清单

在向用户展示文件之前，请核实：

1. 所有 {{PROJECT_NAME}} 占位符都已替换为人类可读的名称
2. 所有 {{PROJECT_SLUG}} 占位符都已替换为 slug 化的名称
3. devcontainer.json 中的 JSON 语法有效（无尾随逗号，嵌套正确）
4. 为所有检测到的语言添加了特定于语言的扩展
5. postCreateCommand 包含所有必需的设置命令（使用 && 链接）

---

用户说明

生成后，告知用户：

1. 如何启动：“在 VS Code 中打开并选择‘Reopen in Container’”
2. 替代方法：devcontainer up --workspace-folder .
3. 命令行辅助工具：运行 .devcontainer/install.sh self-install 将 devc 命令添加到 PATH

局限性

• 仅当任务明确符合上述范围时才使用此技能。
• 不要将输出视为特定于环境的验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。