Skip to content

Commit e955bb8

Browse files
committed
docs(vscode): 新增 dev container 标准模板
1 parent e6499c1 commit e955bb8

15 files changed

Lines changed: 622 additions & 1 deletion

File tree

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Dev Container Template Guidelines
2+
3+
> 适用于 `config/vscode/devcontainers/` 下的 Dev Container 标准模板、片段和配套文档。
4+
5+
## Scenario: Standard Dev Container Templates
6+
7+
### 1. Scope / Trigger
8+
9+
* Trigger: 新增或修改可复制到业务项目的 Dev Container 模板。
10+
* Scope: `config/vscode/devcontainers/**`、Dev Container 相关 cheatsheet、模板内初始化脚本。
11+
* Goal: 模板必须可复用、无项目专属路径、无真实 secrets,并明确宿主配置复用的安全边界。
12+
13+
### 2. Signatures
14+
15+
* 模板入口:`config/vscode/devcontainers/<template-name>/devcontainer.json`
16+
* 可组合片段:`config/vscode/devcontainers/<capability>/devcontainer.fragment.jsonc`
17+
* 配套脚本:`.devcontainer/scripts/*.sh`
18+
* 文档入口:`config/vscode/devcontainers/README.md`
19+
20+
### 3. Contracts
21+
22+
* `devcontainer.json` 必须是可解析 JSON;不要在正式模板 JSON 中使用注释。
23+
* 片段文件可使用 `.jsonc`,但必须在文档中说明需要人工合并。
24+
* 宿主配置默认采用“配置只读 + 缓存读写”:
25+
* 配置类文件和目录使用只读 bind mount。
26+
* 缓存类目录可使用读写 bind mount 或 Docker volume。
27+
* 容器运行态日志、session、临时文件优先保留在容器用户目录。
28+
* AI Agent CLI 默认在容器内安装,不直接挂载宿主可执行文件。
29+
* 模板不得写入真实 token、API key、个人项目路径、私有代理或项目专属服务地址。
30+
31+
### 4. Validation & Error Matrix
32+
33+
| Condition | Expected handling |
34+
|-----------|-------------------|
35+
| 宿主配置目录不存在 | `initializeCommand` 预创建空目录,避免 bind mount 失败 |
36+
| 宿主单文件配置不存在 | 预创建空文件或把文件挂载改为可选脚本逻辑,避免 Docker 把文件路径误建成目录 |
37+
| 容器内需要写日志或 session | 写入容器 home 下的运行态目录,不回写只读宿主配置 |
38+
| 需要在容器内重新登录 agent | 文档说明临时改读写挂载,完成后恢复只读 |
39+
| 模板需要私服或代理 | 通过本机配置、环境变量或项目私有配置注入,不写进标准模板 |
40+
41+
### 5. Good/Base/Bad Cases
42+
43+
* Good: Java 8 模板使用 Dev Container Feature 安装 JDK/Maven,Maven settings 只读链接,Maven repository 读写挂载。
44+
* Base: 仅提供 `base/devcontainer.json`,不包含语言工具链和宿主敏感配置挂载。
45+
* Bad: 在模板中硬编码某个本机项目路径、API key、私有 Maven 仓库认证,或直接挂载宿主 `codex` / `claude` 二进制。
46+
47+
### 6. Tests Required
48+
49+
* JSON 模板:运行 JSON parse 检查。
50+
* Shell 脚本:运行 `bash -n`
51+
* 文档/模板:搜索确认不含项目专属路径、真实 secret、一次性调试内容。
52+
* 仓库质量门禁:配置/文档变更完成后运行根目录 `pnpm qa`
53+
54+
### 7. Wrong vs Correct
55+
56+
#### Wrong
57+
58+
```json
59+
{
60+
"mounts": [
61+
"source=/home/user/company/project,target=/workspace,type=bind",
62+
"source=${localEnv:HOME}/.local/bin/claude,target=/usr/local/bin/claude,type=bind"
63+
]
64+
}
65+
```
66+
67+
#### Correct
68+
69+
```json
70+
{
71+
"mounts": [
72+
"source=${localEnv:HOME}/.claude,target=/mnt/host-configs/claude,type=bind,readonly"
73+
],
74+
"postCreateCommand": "npm install -g @anthropic-ai/claude-code"
75+
}
76+
```

.trellis/spec/infra/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@
1313
| [Node/Vitest Scripts](./node-vitest-scripts.md) | 根目录 Vitest 发现的 Node 脚本测试与 shebang 行尾约定 | Active |
1414
| [PostgreSQL Toolkit](./postgresql-toolkit.md) | PostgreSQL / pgBackRest 命令边界、env 解析和备份范围约定 | Active |
1515
| [rathole template](./rathole.md) | rathole 裸二进制、PM2 管理、`.local.toml` 与公网白名单转发模板约定 | Active |
16+
| [Dev Container Templates](./devcontainer-templates.md) | VS Code Dev Container 标准模板、宿主配置挂载与 Agent CLI 复用约定 | Active |
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{"file": ".trellis/tasks/05-18-java8-devcontainer-configs/research/devcontainer-template-notes.md", "reason": "核对模板是否符合 Java 8、Maven、Codex、Claude Code 配置复用要求"}
2+
{"file": ".trellis/spec/infra/devcontainer-templates.md", "reason": "核对 Dev Container 模板是否满足标准模板约定"}
3+
{"file": ".trellis/spec/infra/index.md", "reason": "核对基础设施配置文档与模板边界"}
4+
{"file": ".trellis/spec/guides/index.md", "reason": "核对新增模板是否保持可复用、无项目专属耦合"}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{"file": ".trellis/tasks/05-18-java8-devcontainer-configs/research/devcontainer-template-notes.md", "reason": "Dev Container 模板字段、Java Feature、Maven 与 AI Agent 配置复用策略"}
2+
{"file": ".trellis/spec/infra/devcontainer-templates.md", "reason": "Dev Container 标准模板、宿主配置挂载与 Agent CLI 复用约定"}
3+
{"file": ".trellis/spec/infra/index.md", "reason": "基础设施配置与本地工具链约定入口"}
4+
{"file": ".trellis/spec/guides/index.md", "reason": "配置模板变更前的复用与边界思考指南"}
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Dev Container 标准配置模板
2+
3+
## Goal
4+
5+
`config/vscode` 下沉淀一套可复制到其他项目的 Dev Container 标准配置模板和最佳实践文档,让后续项目可以快速获得一致的 VS Code 容器开发环境。其中至少包含一个 Java 8 项目模板,并说明如何在容器内复用本机 Codex 或 Claude Code 的配置与登录态。
6+
7+
## What I already know
8+
9+
* 目标目录应位于 `config/vscode` 下,作为 VS Code 相关配置资产的一部分。
10+
* 本次目标是标准模板、配置示例和最佳实践文档,不是只给某一个项目写专用 `.devcontainer`
11+
* 需要包含一个 Java 8 项目模板;文档中只描述为 Java 8 项目,不出现具体项目名称或本机项目路径。
12+
* 用户希望 Dev Container 能配合本机已有 Codex 或 Claude Code 开发。
13+
* 当前 `config/vscode` 已有 settings、snippets、neovim 配置,没有现成 Dev Container 模板目录。
14+
* 仓库已有 `docs/cheatsheet/vscode/remote/remote-guide.md` 简要提到 Dev Containers,可作为文档体系参考。
15+
16+
## Assumptions (temporary)
17+
18+
* 模板落点采用 `config/vscode/devcontainers/`,目录名直观且与现有 VS Code 配置分组一致。
19+
* Java 8 模板优先使用 Dev Container Feature 安装 Java 8 和 Maven,避免手写 JDK 安装脚本。
20+
* AI Agent 复用优先采用“容器内安装 CLI + 挂载宿主配置目录”的方式,而不是直接挂载宿主可执行文件。
21+
* 首版模板只覆盖 Linux 容器;Windows/macOS 作为宿主时通过 Docker Desktop/VS Code Dev Containers 自行接入。
22+
23+
## Open Questions
24+
25+
* 无。
26+
27+
## Requirements (evolving)
28+
29+
*`config/vscode` 下新增 Dev Container 模板目录。
30+
* 首版采用分层模板库结构,优先提供 base / Java 8 / AI Agent 配置复用的可组合模板。
31+
* 提供至少一个 Java 8 项目可复制模板。
32+
* Java 8 模板需要能复用宿主 Maven 配置,至少覆盖 `~/.m2/settings.xml` 与 Maven 本地仓库缓存的常见需求。
33+
* Java 8 模板需要能复用宿主 Claude Code 配置。
34+
* Java 8 模板需要能复用宿主 Codex 配置。
35+
* 宿主 Maven、Claude Code、Codex 配置默认采用“配置只读 + 缓存读写”的挂载策略。
36+
* 提供模板使用文档,说明复制到项目 `.devcontainer/` 的方式、可调整项和安全注意事项。
37+
* 文档不得出现用户提供的具体项目名称或本机项目路径。
38+
* 模板和文档需要说明 Codex / Claude Code 在容器内复用本机配置的推荐方式。
39+
* 模板不得写入真实 token、API key、私有路径或项目专属配置。
40+
41+
## Acceptance Criteria (evolving)
42+
43+
* [x] `config/vscode` 下存在清晰命名的 Dev Container 模板目录。
44+
* [x] 至少一个 Java 8 模板包含可用的 `devcontainer.json`
45+
* [x] Java 8 模板包含宿主 Maven 配置/缓存挂载方案。
46+
* [x] Java 8 模板包含宿主 Claude Code 配置挂载方案。
47+
* [x] Java 8 模板包含宿主 Codex 配置挂载方案。
48+
* [x] 默认挂载策略体现配置只读、缓存读写,并在文档中解释原因与调整方式。
49+
* [x] 文档能说明如何复制模板到任意项目的 `.devcontainer/`
50+
* [x] 文档包含 Codex / Claude Code 配置复用说明,并明确安全边界。
51+
* [x] 文档和模板中不出现具体项目名称或本机项目路径。
52+
* [x] 根目录 `pnpm qa` 通过,或如有环境限制则记录原因。
53+
54+
## Definition of Done (team quality bar)
55+
56+
* Tests added/updated only where business logic or reusable script behavior changes.
57+
* Lint / typecheck / CI green where applicable.
58+
* Docs/notes updated because this task主要产物是配置模板与文档。
59+
* Rollout/rollback considered: 模板是新增资产,可通过删除新增目录回滚。
60+
61+
## Out of Scope (explicit)
62+
63+
* 不为任何具体业务项目直接写入 `.devcontainer`
64+
* 不在模板中固化真实 API key、登录态、私有代理、私服地址或本机项目路径。
65+
* 不实现自动复制/安装脚本,除非后续收敛时明确纳入。
66+
* 不处理 Java 8 项目的私有 Maven 仓库、证书、数据库、中间件等项目专属依赖。
67+
68+
## Technical Notes
69+
70+
* 已检查 `config/vscode`,当前包含 settings、snippets、neovim 等配置资产。
71+
* 已检查 `docs/cheatsheet/vscode/remote/remote-guide.md`,已有远程开发概览,可补充链接或保持模板目录内自带 README。
72+
* 已通过 Context7 查询 Dev Container 官方资料,确认 `features``mounts``remoteEnv``customizations.vscode``remoteUser` 等字段适合本任务。
73+
* 用户提供的 `.sdkmanrc` 示例指向 Java 8;该信息只用于确定 Java 版本,不写入用户可读文档的项目身份信息。
74+
75+
## Research References
76+
77+
* [`research/devcontainer-template-notes.md`](research/devcontainer-template-notes.md) — Dev Container 模板字段、Java Feature 与 AI Agent 配置复用建议。
78+
79+
## Research Notes
80+
81+
### Feasible approaches here
82+
83+
**Approach A: 一个完整 Java 8 + AI Agent 模板**
84+
85+
* How it works: 只提供 `java8-ai-agents/` 一个可复制目录,内含 Java 8、Maven、Node、Codex/Claude 配置挂载建议。
86+
* Pros: 首版最简单,用户拿来即用。
87+
* Cons: 复用到非 Java 项目时需要删改,标准模板库的扩展性弱。
88+
89+
**Approach B: 分层模板库(已选择)**
90+
91+
* How it works: 提供 `base/``java8/``ai-agents/` 或一个 Java 8 组合模板加共享文档,明确哪些片段可合并。
92+
* Pros: 更像标准配置模板库,后续可扩展 Node、Python、Go 等项目模板。
93+
* Cons: 首版文件数略多,文档需要解释组合方式。
94+
95+
**Approach C: 只写文档和片段,不提供完整模板**
96+
97+
* How it works: 用 README 展示 JSONC 片段,用户按需拼装。
98+
* Pros: 最灵活,维护成本低。
99+
* Cons: 落地成本高,不能直接复制使用。
100+
101+
## Expansion Sweep
102+
103+
* Future evolution: 后续可能扩展 Node、Python、Go、数据库客户端、Docker-in-Docker 等模板;首版目录结构应允许新增语言模板。
104+
* Related scenarios: VS Code Remote 文档已有概览,新文档应能被发现,但不必改动所有远程开发文档。
105+
* Failure/edge cases: 需要提醒挂载宿主 Codex/Claude 配置只适合可信容器;宿主 CLI 二进制不一定能直接在容器内执行。
106+
107+
## Decision (ADR-lite)
108+
109+
**Context**: 本任务需要产出可复用的 Dev Container 标准配置,而不是某个项目的单点配置。后续可能继续增加更多语言和工具链模板。
110+
111+
**Decision**: 采用分层模板库结构,首版围绕 base、Java 8 与 AI Agent 配置复用组织模板;Java 8 示例模板必须覆盖宿主 Maven、Claude Code 与 Codex 配置复用。宿主配置默认采用“配置只读 + 缓存读写”的挂载策略。
112+
113+
**Consequences**: 首版文档需要说明不同模板片段的组合方式;换来的是后续扩展其他语言或工具链时不需要重写 Java 8 示例。配置只读能降低容器误改宿主登录态和敏感配置的风险,但用户若要在容器内重新登录或修改 agent 配置,需要按文档临时改成读写挂载。
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Dev Container 模板调研记录
2+
3+
## 调研目标
4+
5+
`config/vscode` 下的 Dev Container 标准配置模板确定基础写法、可复用边界和 AI Agent 配置复用策略。
6+
7+
## 官方配置要点
8+
9+
* `devcontainer.json` 支持 `image``build` 两种入口;模板库更适合保留可复制的 `devcontainer.json`,复杂环境再配套 `Dockerfile`
10+
* `features` 可组合安装通用工具、Java、Node.js 等能力,适合做标准模板的默认构建块。
11+
* `customizations.vscode` 可内置 VS Code 扩展与 settings,适合把 Remote - Containers、Java 开发插件、终端偏好沉淀在模板里。
12+
* `mounts` 可挂载宿主目录或 Docker volume,适合复用宿主侧的 agent 配置目录,避免把 token 和登录态写进模板。
13+
* `remoteEnv` 可追加 PATH 或声明容器内可见环境变量,适合给 CLI shim 或工具目录预留入口。
14+
* Java Feature 支持 `version: "8"`,并可安装 Maven/Gradle;Java 8 模板可以基于该 Feature,而不是手写安装脚本。
15+
* Node Feature 可安装 Node.js 与 pnpm/yarn;如果希望容器内运行 Node 生态 CLI,模板可以把它作为 agent 运行依赖。
16+
17+
## 本仓库约束
18+
19+
* 目标是模板库与最佳实践文档,不是只给单个项目生成 `.devcontainer`
20+
* 用户明确要求文档中不要出现具体项目名称和本机项目路径,只把示例描述为 Java 8 项目。
21+
* 用户希望 Dev Container 能使用本机已有 Codex 或 Claude Code 工作流;模板应优先复用宿主配置和登录态,避免把 secrets 写入模板。
22+
* 本机 `codex` 当前是 Node 入口脚本,`claude` 当前是本机二进制;因此“直接挂载宿主 CLI 可执行文件”跨容器不稳定,推荐在容器内安装/准备 CLI,再挂载宿主配置目录。
23+
24+
## 推荐方向
25+
26+
*`config/vscode/devcontainers/` 下维护模板目录,例如 `base/``java8/``with-ai-agents/` 或组合型示例。
27+
* Java 8 示例模板使用 Dev Container Java Feature 安装 Java 8,并安装 Maven;Gradle 先按可选项或注释说明处理。
28+
* AI Agent 复用采用“容器内安装 CLI + 只读/按需挂载宿主配置目录”的模式:
29+
* Codex: 挂载 `~/.codex` 到容器用户 home 下的 `.codex`
30+
* Claude Code: 挂载 `~/.claude` 到容器用户 home 下的 `.claude`
31+
* CLI 安装方式放在模板文档中说明,避免模板假定宿主二进制可在容器里运行。
32+
33+
## 风险与边界
34+
35+
* 挂载宿主配置目录会把登录态带入容器;文档需要提醒只用于可信项目和可信容器镜像。
36+
* 若用户使用自定义代理、router 或私有 CA,模板不应硬编码这些值;应通过本机配置或 `.env` 注入。
37+
* Java 8 生态可能涉及旧 Maven 仓库、TLS 或私服证书问题;首版模板只提供标准 JDK/Maven 基础,不处理公司私服和证书。
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"id": "java8-devcontainer-configs",
3+
"name": "java8-devcontainer-configs",
4+
"title": "brainstorm: Java8 dev container configs",
5+
"description": "",
6+
"status": "in_progress",
7+
"dev_type": null,
8+
"scope": null,
9+
"package": null,
10+
"priority": "P2",
11+
"creator": "mudssky",
12+
"assignee": "mudssky",
13+
"createdAt": "2026-05-18",
14+
"completedAt": null,
15+
"branch": null,
16+
"base_branch": "master",
17+
"worktree_path": null,
18+
"commit": null,
19+
"pr_url": null,
20+
"subtasks": [],
21+
"children": [],
22+
"parent": null,
23+
"relatedFiles": [],
24+
"notes": "",
25+
"meta": {}
26+
}
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Dev Container 标准模板
2+
3+
这个目录保存可复制到业务项目的 Dev Container 模板。模板以“先能直接用,再方便组合”为原则:完整模板放在语言目录下,通用片段放在能力目录下。
4+
5+
## 目录结构
6+
7+
```text
8+
config/vscode/devcontainers/
9+
├── base/
10+
│ └── devcontainer.json
11+
├── java8/
12+
│ ├── devcontainer.json
13+
│ └── scripts/
14+
│ └── bootstrap-host-configs.sh
15+
└── ai-agents/
16+
├── README.md
17+
└── devcontainer.fragment.jsonc
18+
```
19+
20+
## 快速使用 Java 8 模板
21+
22+
在目标 Java 8 项目根目录执行:
23+
24+
```bash
25+
mkdir -p .devcontainer
26+
cp -R /path/to/this-repo/config/vscode/devcontainers/java8/* .devcontainer/
27+
```
28+
29+
然后用 VS Code 执行 `Dev Containers: Reopen in Container`
30+
31+
## Java 8 模板包含什么
32+
33+
* Java 8 JDK,默认使用 Dev Containers Java Feature 安装。
34+
* Maven,默认安装最新版 Maven。
35+
* Node.js LTS,用于在容器内安装 Codex 和 Claude Code CLI。
36+
* Maven 本地仓库缓存读写挂载:容器复用宿主 `~/.m2/repository`
37+
* Maven 配置只读挂载:容器读取宿主 `~/.m2/settings.xml``settings-security.xml``toolchains.xml`
38+
* Codex 配置只读挂载:容器读取宿主 `~/.codex` 中的配置、登录态、规则和技能。
39+
* Claude Code 配置只读挂载:容器读取宿主 `~/.claude``~/.claude.json` 中的配置、技能、命令和插件。
40+
41+
## 配置挂载策略
42+
43+
默认策略是“配置只读 + 缓存读写”:
44+
45+
* 只读配置:Maven settings、Codex 配置、Claude Code 配置。
46+
* 读写缓存:Maven 本地仓库。
47+
* 容器运行态:Codex/Claude 的日志、会话、临时文件保留在容器用户目录,不回写宿主。
48+
49+
这样可以减少容器误改宿主登录态、密钥配置和个人偏好的风险。只有在你明确需要在容器内重新登录或修改全局配置时,才建议临时把对应挂载改成读写。
50+
51+
## Agent CLI 策略
52+
53+
模板不直接挂载宿主 `codex``claude` 可执行文件。原因是宿主 CLI 可能依赖宿主 Node、动态库或二进制格式,直接挂进 Linux 容器后不一定可执行。
54+
55+
推荐做法是:
56+
57+
1. 容器内安装 CLI:`@openai/codex``@anthropic-ai/claude-code`
58+
2. 通过只读挂载复用宿主配置和登录态。
59+
3. 把运行时写入保留在容器自己的 home 目录。
60+
61+
## 安全边界
62+
63+
只在可信项目和可信镜像中挂载宿主 Codex / Claude Code 配置。即使是只读挂载,容器内进程仍然可以读取登录态和配置文件。
64+
65+
不要把真实 token、API key、私有代理、公司私服地址或项目专属路径写入模板。需要这些内容时,优先放在本机配置、环境变量或项目自己的未提交配置文件中。
66+
67+
## 组合其他模板
68+
69+
`ai-agents/devcontainer.fragment.jsonc` 提供 Codex / Claude Code 复用片段。给其他语言模板添加 Agent 能力时,复制 fragment 中的 `features``mounts``postCreateCommand` 片段,再复制 `java8/scripts/bootstrap-host-configs.sh` 到目标项目的 `.devcontainer/scripts/`
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# AI Agent 配置复用片段
2+
3+
这个目录提供给其他 Dev Container 模板复用的 Codex / Claude Code 配置片段。
4+
5+
## 适用场景
6+
7+
* 希望容器里直接运行 `codex``claude`
8+
* 希望复用宿主已有登录态、模型配置、规则、skills 或插件。
9+
* 希望容器运行态不污染宿主配置目录。
10+
11+
## 使用方式
12+
13+
1.`devcontainer.fragment.jsonc` 里的片段合并到目标模板的 `devcontainer.json`
14+
2.`../java8/scripts/bootstrap-host-configs.sh` 复制到目标项目的 `.devcontainer/scripts/`
15+
3. 确认 `postCreateCommand` 会执行 `bash .devcontainer/scripts/bootstrap-host-configs.sh`
16+
17+
## 默认策略
18+
19+
* 宿主 `~/.codex` 只读挂载到 `/mnt/host-configs/codex`
20+
* 宿主 `~/.claude` 只读挂载到 `/mnt/host-configs/claude`
21+
* 宿主 `~/.claude.json` 只读挂载到 `/mnt/host-configs/claude.json`
22+
* 容器内安装 Codex / Claude Code CLI。
23+
* 容器内 `~/.codex``~/.claude` 保留日志、会话和临时文件的写入空间。
24+
25+
如果要在容器里重新登录或修改全局设置,请临时把对应挂载改成读写,操作完成后再恢复只读。

0 commit comments

Comments
 (0)