最小化云原生开发环境基础镜像，其他项目通过 FROM 继承。

基础镜像只包含所有项目都需要的、与语言/框架无关的内容：

• code-server（WebIDE 核心）
• 通用系统工具（git、curl、vim 等）
• Shell 环境（zsh + oh-my-zsh + starship + lsd）
• 视觉体验（Catppuccin 主题/图标 + 字体配置）
• CNB 平台集成（.cnb.yml Schema + cnb-openapi-skills）
• Git 增强（gitblame、git-graph、githistory）
• AI 编程助手（coding-copilot）

项目级专属配置（语言服务器、lint 规则、框架插件等）通过 fork 项目模板仓库 实现； 基础镜像已内置通用代码规范（EditorConfig + YAML 保存自动格式化），子项目开箱即用。

base-dev-env/
├── .ide/
│   ├── Dockerfile         ← 云原生基础镜像构建文件
│   └── settings.json      ← Machine 维度 COPY 源（主题/字体/终端/CNB Schema / YAML 格式化）
├── scripts/
│   ├── create-languagepackages.sh  ← 生成语言包配置
│   └── set-zsh-env.sh             ← 注入 VS Code Server PATH
├── .editorconfig          ← 全局 EditorConfig 配置（继承给所有子项目）
├── .cnb.yml               ← CNB 主配置（云原生开发 + 镜像构建流水线）
├── .cnb/
│   ├── settings.yml       ← 启动按钮配置
│   └── web_trigger.yml    ← 手动触发构建按钮配置
└── README.md              ← 你正在看的文件

类别	插件	用途
平台集成	cnbcool.cnb-welcome	CNB 欢迎页
平台集成	tencent-cloud.coding-copilot	AI 编程助手
平台集成	redhat.vscode-yaml	YAML 格式化 + CNB Schema
Git 增强	waderyan.gitblame	行内 Git 修改者
Git 增强	mhutchie.git-graph	Git 分支图
Git 增强	donjayamanne.githistory	文件修改历史
代码规范	editorconfig.editorconfig	EditorConfig 格式化支持
开发工具	cloudstudio.live-server	本地开发服务器
开发工具	ms-azuretools.vscode-containers	Docker 容器管理
视觉体验	Catppuccin.catppuccin-vsc	Catppuccin 颜色主题
视觉体验	Catppuccin.catppuccin-vsc-icons	Catppuccin 文件图标
语言支持	ms-ceintl.vscode-language-pack-zh-hans	中文语言包

cnb-openapi-skills 是 CNB 平台的 OpenAPI 技能包，安装到 ~/.codebuddy/skills/ 目录。

作用：为 AI 编程助手（CodeBuddy / Claude Code）提供完整的 CNB 平台 API 知识，使其能通过自然语言直接操作 CNB 平台，包括：

• 仓库管理（创建、查询、列表）
• Pull Request（创建、查看、合并）
• Issue（创建、查询、状态管理）
• 构建流水线（触发、查看状态、日志）
• 制品库（推送、拉取镜像）
• 分支与标签管理

使用方式：在云原生开发环境中，直接用自然语言向 AI 助手发出指令即可，例如：

• "帮我查看这个仓库的 PR 列表"
• "创建一个新分支 feature/xxx"
• "查看最近一次构建的状态"
• "帮我创建一个 Issue"

AI 助手会自动调用 CNB API 完成操作。需要配置 CNB_TOKEN 环境变量以获得 API 访问权限。

工具	用途	使用示例
ca-certificates	提供SSL证书支持	-
tzdata	时区数据	-
locales	多语言支持（中文环境）	-

工具	用途	使用示例
iputils-ping	网络连通性测试工具	ping google.com
net-tools	提供ifconfig等网络配置工具	ifconfig
dnsutils	提供nslookup等DNS查询工具	nslookup cnb.cool
telnet	网络连接测试工具	telnet host 80
netcat-openbsd	网络工具，用于端口测试等	nc -zv host 443

工具	用途	使用示例
wget	网络文件下载工具	wget https://example.com/file
curl	网络请求工具	curl -O https://example.com/file

工具	用途	使用示例
unzip	文件解压工具	unzip archive.zip
zip	文件压缩工具	zip -r archive.zip dir/
jq	JSON处理工具	echo '{"a":1}' | jq .
rsync	文件同步工具	rsync -avz src/ dest/
nano	轻量级文本编辑器	nano file.txt
vim	文本编辑器	vim file.txt
tree	目录结构树形显示，支持深度控制、模式过滤、排除规则	tree -L 2 -I "node_modules"
ripgrep	超高速代码搜索（rg），默认忽略 .gitignore，性能远超 grep	rg "TODO" --type js
fd-find	现代化文件查找（fdfind），语法简洁，自动忽略隐藏目录	fdfind "\\.ts$" src/
ncdu	交互式磁盘空间分析，快速定位大文件/目录占用	ncdu /workspace
bat	增强版 cat，自带语法高亮 + 行号 + Git 修改标记	bat Dockerfile

工具	用途	使用示例
htop	增强的系统监控工具	htop
lsof	查看打开的文件和网络连接	lsof -i :8080
bash-completion	命令自动补全	-
fzf	通用模糊搜索器，配合文件搜索、历史命令、git 分支等	Ctrl+R 模糊搜索命令历史；git branch | fzf 模糊选择分支
file	文件类型识别，排查未知文件必备	file unknown.bin
mtr-tiny	网络路由追踪，集 ping + traceroute 于一体	mtr google.com
duf	现代化磁盘使用查看，表格形式展示挂载点/设备/类型/用量	duf
tealdeer	简化版 man 手册（tldr），给出常用示例而非全量文档	tldr tar

工具	用途	使用示例
git	版本控制系统	git status
git-lfs	Git大文件支持	git lfs track "*.psd"
openssh-server	SSH服务器，支持远程连接	-
build-essential	基础编译工具	-
make	构建系统工具	make build
python3-pip	Python包管理工具	pip install <package>
openssl	SSL工具	openssl s_client -connect host:443
libssl-dev	SSL开发库	-
libltdl-dev	库依赖工具	-
zsh	增强的命令行环境	-
xxd	十六进制查看工具，分析二进制文件内容/文件头	xxd file.bin | head
man-db + manpages	标准命令手册系统，开发者查阅工具用法	man grep
shellcheck	Shell 脚本静态分析，检测语法错误和最佳实践	shellcheck deploy.sh
httpie	人性化 HTTP 客户端，JSON 高亮 + 语法简洁	http GET https://api.example.com/users

• zsh + oh-my-zsh + zsh-autosuggestions + zsh-syntax-highlighting
• starship 提示符（Git 状态、语言版本等富信息）
• lsd 增强版 ls（文件类型图标 + 颜色 + 树形视图）
• UTF-8 中文字符集支持

别名	命令	用途
cl	clear	清屏
dp	docker ps	查看运行中的容器
di	docker images	查看本地镜像
cdw	cd /workspace	快速切换到工作目录
dc	docker compose	Docker Compose 快捷命令
docker-compose	docker compose	兼容旧命令
src	source ~/.zshrc	重新加载 zsh 配置
bash	zsh	替换 bash 为 zsh
hs	history	查看命令历史
..	cd ..	上一级目录
...	cd ../..	上两级目录
openw	"$BROWSER" "$CNB_VSCODE_WEB_URL"	打开 WebIDE
openv	"$BROWSER" "$CNB_VSCODE_REMOTE_SSH_SCHEMA"	打开 VSCode 远程 SSH
open	"$BROWSER" "http://localhost:$1"	打开本地端口
openr	"$BROWSER" "$(echo "${CNB_VSCODE_PROXY_URI//\{\{port\}\}/$1}")"	打开 CNB 代理端口
ls	lsd	增强版 ls
ll	lsd -l	详细列表
la	lsd -a	显示隐藏文件
lla	lsd -la	详细列表 + 隐藏文件
lt	lsd --tree	树形视图

• 历史记录条数：10,000,000
• 历史记录格式：%Y-%m-%d %T（年-月-日 时:分:秒）
• 忽略的命令：ls, cd, pwd, exit 等
• 历史记录文件：/root/.cnb/system/zsh_history

• 颜色主题：Catppuccin Mocha
• 图标主题：Catppuccin Mocha（catppuccin-mocha）
• 编辑器字体：Maple Mono NF → JetBrains Mono → Fira Code → Consolas → monospace
• 终端字体：Maple Mono NF → JetBrains Mono → Fira Code → Consolas → monospace

字体渲染在浏览器端，需用户本地安装对应字体。

基础镜像将 .editorconfig COPY 到容器根目录 /，所有子项目自动继承，无需重复创建。

为什么放在 / 而非 /workspace？ /workspace 是项目代码的挂载点，COPY 到那里会被挂载覆盖。EditorConfig 会从项目目录向上查找，在 / 遇到 root = true 后停止，因此所有子项目都能命中此配置。

文件类型	缩进风格	缩进大小	换行符	说明
默认 [*]	Space	2	LF	通用规则
YAML [*.{yml,yaml}]	Space	2	LF	与默认一致
Dockerfile [Dockerfile]	Space	4	LF	Dockerfile 专用
Markdown [*.md]	Space	2	LF	不自动删除行尾空格

全局生效项：

• charset = utf-8
• trim_trailing_whitespace = true
• insert_final_newline = true

安装 editorconfig.editorconfig 插件后，VSCode 会在保存时自动按上述规则调整格式。

Machine 维度配置中已启用 YAML 文件的保存自动格式化：

"[yaml]": {
  "editor.defaultFormatter": "redhat.vscode-yaml",
  "editor.formatOnSave": true
}

配合已安装的 redhat.vscode-yaml 插件，编辑 .cnb.yml、.cnb/web_trigger.yml 等 YAML 文件时，保存即可自动完成缩进和对齐。

基础镜像将通用体验配置写入 Machine 维度，子项目通过 .vscode/settings.json 覆盖或追加：

仓库维度 (.vscode/settings.json)  ← 子项目增量配置
    ↓ 覆盖
机器维度 (Machine/settings.json) ← 基础镜像：主题/字体/终端/Schema/代码规范

Machine 维度已包含：

类别	配置项	说明
视觉体验	workbench.colorTheme / iconTheme	Catppuccin Mocha 主题与图标
字体	editor.fontFamily / fontLigatures	Maple Mono NF 优先，启用连字
终端	terminal.integrated.defaultProfile / fontFamily	默认 zsh，终端字体与大小
智能提示	terminal.integrated.suggest.enabled	终端命令自动补全
CNB 集成	yaml.schemas / yaml.customTags	.cnb.yml 自动补全与语法检查
Git 增强	gitblame.inlineMessageFormat	行内 blame 信息显示格式
代码规范	[yaml].editor.formatOnSave	YAML 保存时自动格式化

.cnb.yml 中 build.by 声明了 COPY 需要的文件，未声明的文件在构建时不可见：

docker:
  build:
    dockerfile: .ide/Dockerfile
    by:
      - .ide/settings.json
      - scripts/
      - .editorconfig

┌─────────────────────────────────────────────┐
│           子项目 Dockerfile                  │
│  （仅安装项目专属工具和配置）                  │
├─────────────────────────────────────────────┤
│           基础镜像（本仓库）                   │
│  debian:bookworm + code-server + 12 个插件       │
│  zsh + oh-my-zsh + starship + lsd            │
│  cnb-openapi-skills + Machine 维度配置        │
└─────────────────────────────────────────────┘