devcontainer-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

devcontainer-bootstrap

使いどころ

适用场景

任意リポジトリに Dev Container を素早く導入したいとき
既存
```
.devcontainer/
```
を壊さず拡張したいとき（バックアップ必須）
Node/Python/Rust の代表的セットアップをテンプレで貼りたいとき

想要快速给任意仓库引入Dev Container的时候
想要不破坏现有
```
.devcontainer/
```
目录对其进行扩展的时候（必须备份）
想要用模板快速生成Node/Python/Rust的典型开发环境配置的时候

ワークフロー（(1) scan → (2) detect → (3) apply/update → (4) explain）

工作流（(1) 扫描 → (2) 判定 → (3) 应用/更新 → (4) 说明）

scan: リポジトリルートを確認し、スタック候補ファイルをチェック
detect:
```
scripts/detect_stack.sh
```
で
```
node|python|rust|unknown
```
を判定（複数命中や go.mod のみは unknown → stack を明示指定）

apply/update:

scripts/apply_devcontainer.sh

を実行し

.devcontainer/

を生成/更新

explain: 実行ログを読み、何がバックアップ/更新されたかをユーザーに伝える。競合や手動フォローが必要なら明示

scan: 检查仓库根目录，确认技术栈对应的候选文件
detect: 通过
```
scripts/detect_stack.sh
```
判定技术栈为
```
node|python|rust|unknown
```
（同时命中多个技术栈或者仅存在go.mod的情况判定为unknown → 需要显式指定stack）

apply/update: 执行

scripts/apply_devcontainer.sh

生成/更新

.devcontainer/

explain: 读取执行日志，告知用户哪些内容被备份/更新。如果存在冲突或者需要手动跟进的情况会明确提示

実行オプション（チャットで指定可能）

执行选项（可在对话中指定）

```
stack
```
:
```
auto|node|python|rust
```
（default auto, 複数命中や go.mod のみは unknown → stack 指定を促す）
```
packageManager
```
:
```
npm|pnpm|yarn
```
（node のみ、postCreate で install 実行）
```
mode
```
:
```
safe|overwrite
```
- safe: 既存
```
devcontainer.json
```
  をマージ（extensions/settings/features/postCreateCommand）。
```
jq
```
  無しでも最小追記（postCreate 実行を確実に追加）。既存 Dockerfile は保持。
- overwrite: stack テンプレートで
```
devcontainer.json
```
  と
```
Dockerfile
```
  を置換。
```
includeTools
```
:
```
true|false
```
（default false）
- true の場合、追加 feature として git / github-cli を組み込む（上書きではなくマージ）。
```
addCI
```
:
```
true|false
```
（default false）
- GitHub Actions 最小 workflow (
```
.github/workflows/devcontainer-bootstrap.yml
```
  ) を生成。safe で既存があればバックアップのみしてスキップ、overwrite なら置換。

```
stack
```
:
```
auto|node|python|rust
```
（默认auto，同时命中多个技术栈或者仅存在go.mod的情况判定为unknown → 提示指定stack）
```
packageManager
```
:
```
npm|pnpm|yarn
```
（仅针对node技术栈，会在postCreate阶段执行install命令）
```
mode
```
:
```
safe|overwrite
```
- safe: 合并现有
```
devcontainer.json
```
  配置（extensions/settings/features/postCreateCommand）。即使没有
```
jq
```
  也会进行最小追加（确保添加postCreate执行逻辑）。保留现有Dockerfile。
- overwrite: 用对应技术栈的模板替换
```
devcontainer.json
```
  和
```
Dockerfile
```
  。
```
includeTools
```
:
```
true|false
```
（默认false）
- 设为true时，会作为额外feature集成git / github-cli（采用合并逻辑而非覆盖）。
```
addCI
```
:
```
true|false
```
（默认false）
- 生成最小的GitHub Actions工作流配置（
```
.github/workflows/devcontainer-bootstrap.yml
```
  ）。safe模式下如果已有该文件则仅备份跳过生成，overwrite模式下直接替换。

手順（ローカル実行例）

使用步骤（本地执行示例）

bash

undefined

bash

undefined

1. スタック自動判定（複数命中なら unknown）

1. 自动判定技术栈（同时命中多个则返回unknown）

bash skills/devcontainer-bootstrap/scripts/detect_stack.sh .

2. safe モードで適用（自動判定 + 追記中心）

2. safe模式应用配置（自动判定 + 以追加配置为主）

bash skills/devcontainer-bootstrap/scripts/apply_devcontainer.sh --mode safe

3. node + pnpm で overwrite し CI も生成

3. 指定node + pnpm技术栈覆盖配置，同时生成CI配置

bash skills/devcontainer-bootstrap/scripts/apply_devcontainer.sh --stack node --package-manager pnpm --mode overwrite --include-tools true --add-ci true

undefined

bash skills/devcontainer-bootstrap/scripts/apply_devcontainer.sh --stack node --package-manager pnpm --mode overwrite --include-tools true --add-ci true

undefined

生成/更新内容

```
.devcontainer/
```
（devcontainer.json, Dockerfile, postCreate.sh）。既存があれば
```
.devcontainer.bak-<timestamp>/
```
にバックアップしてから更新。
VS Code 推奨設定と拡張は
```
customizations.vscode
```
に記述（参考: Dev Container supporting tools）。
postCreate は stack に応じて依存導入をベストエフォートで実行（失敗は非致命）。
```
addCI=true
```
の場合、
```
devcontainers/ci@v0.3.1900000417
```
を使う最小 workflow を生成。
Node テンプレートは
```
mcr.microsoft.com/devcontainers/typescript-node:<メジャー>
```
を使用（latest は避け、例:
```
24
```
）。LTS 更新時はメジャー番号タグを明示的に上げる。
Node イメージタグの選定はコードベースの情報を参照して行う
- 優先順:
```
.nvmrc
```
  →
```
.node-version
```
  →
```
package.json
```
  の
```
engines.node
```
- いずれも無い場合はレジストリ (
```
https://mcr.microsoft.com/v2/devcontainers/typescript-node/tags/list
```
  ) から最新メジャーを確認し、latest は避けてメジャー番号タグを使う
Python テンプレートは
```
mcr.microsoft.com/devcontainers/python:<バージョン>
```
を使用（latest は避け、デフォルト例:
```
3.14
```
）
- 優先順:
```
.python-version
```
  →
```
pyproject.toml
```
  の
```
requires-python
```
  または
```
tool.poetry.dependencies.python
```
  →
```
requirements.txt
```
  に併記された Python バージョン記述
- いずれも無い場合はレジストリ (
```
https://mcr.microsoft.com/v2/devcontainers/python/tags/list
```
  ) を参照して安定版メジャー/マイナーを選ぶ（latest は避ける）

```
.devcontainer/
```
（devcontainer.json, Dockerfile, postCreate.sh）。如果已有该目录，会先备份到
```
.devcontainer.bak-<timestamp>/
```
再执行更新。
VS Code推荐配置和扩展会写在
```
customizations.vscode
```
字段下（参考: Dev Container supporting tools）。
postCreate阶段会根据技术栈尽最大努力执行依赖安装（失败不视为致命错误）。
```
addCI=true
```
的情况下，会生成使用
```
devcontainers/ci@v0.3.1900000417
```
的最小工作流配置。
Node技术栈模板使用
```
mcr.microsoft.com/devcontainers/typescript-node:<主版本号>
```
镜像（避免使用latest，例如
```
24
```
）。LTS版本更新时会显式升级主版本号标签。
Node镜像标签的选择会参考代码库中的信息判定
- 优先级:
```
.nvmrc
```
  →
```
.node-version
```
  →
```
package.json
```
  的
```
engines.node
```
  字段
- 以上都不存在的话，会从镜像仓库（
```
https://mcr.microsoft.com/v2/devcontainers/typescript-node/tags/list
```
  ）查询最新主版本，避免使用latest，直接用主版本号标签
Python技术栈模板使用
```
mcr.microsoft.com/devcontainers/python:<版本号>
```
镜像（避免使用latest，默认例如
```
3.14
```
）
- 优先级:
```
.python-version
```
  →
```
pyproject.toml
```
  的
```
requires-python
```
  字段或者
```
tool.poetry.dependencies.python
```
  字段 →
```
requirements.txt
```
  中记录的Python版本描述
- 以上都不存在的话，会参考镜像仓库（
```
https://mcr.microsoft.com/v2/devcontainers/python/tags/list
```
  ）选择稳定的主版本/次版本（避免使用latest）

競合・注意

冲突与注意事项

複数スタックが同時に検出された場合や go.mod のみの場合は
```
stack
```
を明示する。
safe モードでマージできない部分があればログに警告を出す。壊したくない場合は safe を優先。
危険な
```
git config --global safe.directory '*'
```
は一切実行しない。
詳細な判断基準や safe/overwrite の使い分けは
```
docs/decision-guide.md
```
を参照。

同时检测到多个技术栈或者仅存在go.mod的情况需要显式指定
```
stack
```
。
safe模式下如果存在无法合并的配置会在日志中输出警告。不希望破坏现有配置的话优先使用safe模式。
完全不会执行
```
git config --global safe.directory '*'
```
这类高风险操作。
详细的判定标准以及safe/overwrite模式的使用区分请参考
```
docs/decision-guide.md
```
。

バンドル済みリソース

内置资源

```
scripts/detect_stack.sh
```
: スタック判定（node/python/go/unknown）
```
scripts/apply_devcontainer.sh
```
: テンプレ適用 & 安全更新 & CI 生成

templates/

: stack 別

devcontainer.json

Dockerfile

（node/python/rust） + 共通

postCreate.sh

```
docs/decision-guide.md
```
: 判定ルール・バックアップ方針・safe/overwrite の違い・よくある罠

```
scripts/detect_stack.sh
```
: 技术栈判定（node/python/go/unknown）
```
scripts/apply_devcontainer.sh
```
: 模板应用 & 安全更新 & CI生成
```
templates/
```
: 按技术栈分类的
```
devcontainer.json
```
/
```
Dockerfile
```
（node/python/rust） + 通用
```
postCreate.sh
```
```
docs/decision-guide.md
```
: 判定规则、备份策略、safe/overwrite模式差异、常见陷阱