文档: 补充 DevContainer 详细用法并移除 runoc.sh

README.md

@@ -44,22 +44,122 @@ specs/          # speckit 功能规格
 
 ## 快速开始
 
-### 1. 环境准备
+### 1. 环境准备（必须）
+
+所有开发方式（VS Code Dev Containers、docker-compose、本地）共享同一套前置步骤：
 
 ```bash
 # 克隆项目
+git clone <仓库地址> workspace && cd workspace/.devcontainer
+
+# ① 创建环境配置（首次必须）
+cp .env.example .env
+
+# ② 编辑 .env，至少修改以下配置:
+#    - GIT_USER_NAME / GIT_USER_EMAIL  — Git 用户信息
+#    - API_KEY                          — 智谱 GLM API 密钥（可选，留空则跳过认证配置）
+#    - DOCKER_GID                       — 宿主机 docker 组 GID（getent group docker | cut -d: -f3）
+#    - CONTAINER_USER_UID / GID         — 与宿主机用户一致（id -u / id -g）
+
+# ③ 预下载构建资源（首次必须，后续按需增量更新）
+bash download-resources.sh
+```
+
+#### download-resources.sh 资源预下载
+
+[`download-resources.sh`](.devcontainer/download-resources.sh) 预下载所有网络资源到 `.devcontainer/.cache/`，Dockerfile 构建时通过 `--mount=type=bind` 直接使用本地缓存，**无需构建时访问外网**。支持增量更新和校验。
+
+```bash
+bash download-resources.sh                  # 下载全部资源（首次必须）
+bash download-resources.sh --skip-extensions # 跳过 VSCode 扩展（节省时间）
+bash download-resources.sh --force-update    # 强制更新所有包
+bash download-resources.sh --cleanup-only    # 仅清理旧版本包
+```
+
+预下载的资源包括：
+
+| 资源 | 用途 |
+|------|------|
+| uv + Python 3.12 | Python 包管理器和运行时 |
+| nvm + Node.js 22 | 前端运行时和包管理 |
+| npm 全局包 | Claude Code、Playwright MCP、TypeScript 等 |
+| Google Chrome | Playwright headed 模式和 chrome-devtools-mcp |
+| jj (Jujutsu) | 版本控制工具 |
+| VSCode 扩展 (.vsix) | 20+ 开发扩展离线包 |
+| spec-kit | speckit 规格工具 |
+| Claude 插件市场 | claude-plugins-official、Svelte、superpowers 等 |
+
+所有资源版本在 `.env` 中配置（`UV_VERSION`、`NODE_VERSION`、`CHROME_VERSION` 等），更新版本后重新运行脚本即可。
+
+#### .env 配置参考
+
+完整配置见 [`.devcontainer/.env.example`](.devcontainer/.env.example)，常用项：
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `GIT_USER_NAME` | `arno` | Git 用户名 |
+| `GIT_USER_EMAIL` | — | Git 邮箱 |
+| `API_KEY` | 空 | 智谱 GLM API 密钥 |
+| `DOCKER_ENABLED` | `false` | 是否启用容器内 Docker |
+| `DOCKER_GID` | `984` | 宿主机 docker 组 GID |
+| `CONTAINER_USER_UID` | `1000` | 容器用户 UID |
+| `CONTAINER_USER_GID` | `1000` | 容器用户 GID |
+| `DISPLAY_ON_HOST` | `false` | GUI 输出到宿主机（仅 Linux） |
+| `CONTAINER_CPUS` | `6` | CPU 核心数限制 |
+| `CONTAINER_MEMORY` | `16G` | 内存限制 |
+
+### 2. 启动开发环境
+
+资源下载完成后，选择以下任一方式启动：
+
+#### 方式 A: VS Code Dev Containers（推荐）
+
+1. 安装 VS Code 扩展 `ms-vscode-remote.remote-containers`
+2. 在 VS Code 中打开项目根目录
+3. `Ctrl+Shift+P` → `Dev Containers: Open Folder in Container...`
+4. VS Code 自动读取 [`.devcontainer/devcontainer.json`](.devcontainer/devcontainer.json) 构建、启动容器并安装扩展
+
+`devcontainer.json` 核心配置：
+
+| 配置 | 说明 |
+|------|------|
+| `dockerComposeFile` | 组合 `docker-compose.yml` + `docker-compose.display.yml`（X11 转发） |
+| `service: app` | 使用 `app` 服务 |
+| `postCreateCommand` | 容器创建后自动执行 `.devcontainer/post-create.sh`（配置 Git、jj、Claude Code、MCP、插件等） |
+| `customizations.vscode.extensions` | 预装 Claude Code、Ruff、Playwright、Mermaid 等 20+ 扩展 |
+
+#### 方式 B: docker-compose 命令行
+
+```bash
+cd .devcontainer
+docker compose up -d
+docker exec -it team bash
+```
+
+#### 方式 C: 本地开发（不使用容器）
+
+不使用容器时，需手动安装工具链（uv、nvm、jj 等）：
+
+```bash
 jj clone <仓库地址> workspace && cd workspace
-
-# Python 环境（需 uv）
 uv python install 3.12
-
-# 前端环境（需 nvm）
 nvm install --lts
 ```
 
-详细环境搭建见 [`docs/管理-开发环境搭建.md`](docs/管理-开发环境搭建.md)。
+详细步骤见 [`docs/管理-开发环境搭建.md`](docs/管理-开发环境搭建.md)。
 
-### 2. 启动 Agent 团队
+#### 数据持久化
+
+`.devcontainer/.volumes/` 目录映射以下数据，容器重建不丢失：
+
+| 目录 | 用途 |
+|------|------|
+| `.volumes/ssh/` | SSH 密钥和配置 |
+| `.volumes/claude/` | Claude Code 配置（settings.json） |
+| `.volumes/jj/` | jj 版本控制配置 |
+| `.volumes/bin/` | 运行时脚本（runcc.sh） |
+
+### 3. 启动 Agent 团队
 
 ```bash
 # 在 tmux 中启动 5 面板团队工作空间
@@ -86,7 +186,7 @@ nvm install --lts
 /isos-test        # 测试工程师
 ```
 
-### 3. 常用命令
+### 4. 常用命令
 
 ```bash
 # 提交并推送（jj 工作流）
@@ -105,7 +205,7 @@ nvm install --lts
 /isos-md-export      # Markdown 导出 docx/pdf
 ```
 
-### 4. 开发验证
+### 5. 开发验证
 
 ```bash
 # 服务端 (cd apps/server)