docs: add badges, quick start, prerequisites, AI CLI table, contributing guide, license

Author: Shuming-Yang

README.en.md

@@ -4,8 +4,33 @@
 
 # Dev Docker Image Packages
 
+![GitHub Release](https://img.shields.io/github/v/release/shumingyang-opencode/dev-docker-image-packages)
+![GHCR Pulls](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr.io%2Fv2%2Fshumingyang-opencode%2Fpy-devkit-image-base&label=GHCR%20pulls&query=%24.pull_count)
+![GitHub Actions Workflow](https://img.shields.io/github/actions/workflow/status/shumingyang-opencode/dev-docker-image-packages/build-image.yml)
+
 A collection of personal Docker images, automatically built and published to GHCR via GitHub Actions.
 
+## Quick Start
+
+```bash
+# 1. Pull the latest image
+docker pull ghcr.io/shumingyang-opencode/py-devkit-image-base:latest
+
+# 2. Start a dev container
+docker run --rm -it ghcr.io/shumingyang-opencode/py-devkit-image-base:latest bash
+
+# 3. Check the built-in AI CLIs
+opencode --version && copilot --help && lark-cli --version && trae-cli --version
+```
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) installed
+- GitHub account (to trigger CI builds and E2E tests)
+- API keys for each AI CLI (required for Advanced E2E tests)
+
+> To simply **pull and run** an image, you only need Docker — no GitHub account required.
+
 ## Available Images
 
 | Image | Latest Version | Base | Description | Docs |
@@ -14,6 +39,17 @@ A collection of personal Docker images, automatically built and published to GHC
 
 > For a full image index, see [images/README.md](./images/README.md).
 
+## Built-in AI CLI Tools
+
+| CLI | Package | Description | Needs API Key |
+|-----|---------|-------------|:-------------:|
+| `opencode` | npm (opencode-ai) | AI development assistant | ✅ |
+| `copilot` | npm (@github/copilot) | GitHub Copilot Agent | ✅ |
+| `lark-cli` | npm (@larksuite/cli) | Lark development CLI (internal network only) | ❌ |
+| `trae-cli` | pip (trae-agent) | AI Code Agent | ✅ |
+
+> API keys are passed via environment variables. See each image's README for details.
+
 ## Image Tags
 
 Each image is published to GHCR with the following tags:
@@ -198,6 +234,26 @@ bash skills/install.sh
 | "加 image" / "new image" / "create image" | Scaffold a new image (Dockerfile + README) |
 | "build image" / "建置 image" | Trigger GitHub Actions build for an image |
 
+## Contributing
+
+PRs and feature requests are welcome:
+
+1. **Add a new image** — Create `images/<name>/` with a Dockerfile + test scripts, then add the agent config in `tests/e2e/agents/`
+2. **Improve tests** — Strengthen E2E test coverage or add new test cases
+3. **Documentation** — Fix typos, clarify instructions, or improve docs quality
+
+How to contribute: Fork → Develop → Submit a PR → I'll review and merge.
+
+## Related Projects
+
+- [OpenCode](https://opencode.ai) — AI development assistant (built into this image)
+- [trae-agent](https://github.com/bytedance/trae-agent) — ByteDance open-source AI Agent
+- [GHCR](https://ghcr.io) — GitHub Container Registry
+
+## License
+
+MIT
+
 ## Project Structure
 
 ```

README.md

@@ -4,20 +4,51 @@
 
 # Dev Docker Image Packages
 
+![GitHub Release](https://img.shields.io/github/v/release/shumingyang-opencode/dev-docker-image-packages)
+![GHCR Pulls](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr.io%2Fv2%2Fshumingyang-opencode%2Fpy-devkit-image-base&label=GHCR%20pulls&query=%24.pull_count)
+![GitHub Actions Workflow](https://img.shields.io/github/actions/workflow/status/shumingyang-opencode/dev-docker-image-packages/build-image.yml)
+
 個人開發用 Docker Image 集合，透過 GitHub Actions 自動建置並發佈至 GHCR。
 
 ## 目錄
 
+- [Quick Start](#quick-start)
+- [需求](#需求)
 - [可用 Images](#可用-images)
+- [內建 AI CLI 工具](#內建-ai-cli-工具)
 - [Image Tags](#image-tags)
 - [使用方式](#使用方式)
 - [CI / GitHub Actions Workflows](#ci--github-actions-workflows)
 - [E2E 測試](#e2e-測試)
 - [Skills（OpenCode 整合）](#skillsopencode-整合)
+- [貢獻](#貢獻)
+- [相關專案](#相關專案)
+- [License](#license)
 - [專案目錄結構](#專案目錄結構)
 
 ---
 
+## Quick Start
+
+```bash
+# 1. 下載最新 Image
+docker pull ghcr.io/shumingyang-opencode/py-devkit-image-base:latest
+
+# 2. 啟動開發容器
+docker run --rm -it ghcr.io/shumingyang-opencode/py-devkit-image-base:latest bash
+
+# 3. 查看內建 AI CLI
+opencode --version && copilot --help && lark-cli --version && trae-cli --version
+```
+
+## 需求
+
+- [Docker](https://docs.docker.com/get-docker/) 已安裝
+- GitHub 帳號（用於觸發 CI 建置、E2E 測試）
+- 各 AI CLI 對應的 API Key（Advanced E2E 測試用）
+
+> 若只需要 **Pull & Run** Image，則只需要 Docker，不需要 GitHub 帳號。
+
 ## 可用 Images
 
 | Image | 最新版本 | Base | 用途 | 說明文件 |
@@ -26,6 +57,17 @@
 
 > 詳細 Image 索引請見 [images/README.md](./images/README.md)。
 
+## 內建 AI CLI 工具
+
+| CLI | 安裝方式 | 用途 | 需 API Key |
+|-----|---------|------|:----------:|
+| `opencode` | npm (opencode-ai) | AI 開發助手 | ✅ |
+| `copilot` | npm (@github/copilot) | GitHub Copilot Agent | ✅ |
+| `lark-cli` | npm (@larksuite/cli) | 飛書開發工具（內部網路專用） | ❌ |
+| `trae-cli` | pip (trae-agent) | AI Code Agent | ✅ |
+
+> API Key 透過環境變數傳遞，詳見各 Image 說明文件。
+
 ## Image Tags
 
 每個 Image 發佈至 GHCR 時會標記以下 tags：
@@ -214,6 +256,26 @@ bash skills/install.sh
 | 「加 image」 / 「new image」 / 「create image」 | 互動式新增 Image（Dockerfile + README） |
 | 「build image」 / 「建置 image」 | 觸發 GitHub Actions 建置指定 Image |
 
+## 貢獻
+
+歡迎提交 PR 或 Feature Request：
+
+1. **新增 Image** — 在 `images/<name>/` 下建立 Dockerfile + 測試腳本，並在 `tests/e2e/agents/` 新增對應的設定檔
+2. **改善測試** — 補強 E2E 測試案例或新增測試覆蓋範圍
+3. **文件修正** — 修正錯字、補齊說明、改善文件品質
+
+提交方式：Fork 此專案 → 開發 → 提交 PR → 我會審閱後合併
+
+## 相關專案
+
+- [OpenCode](https://opencode.ai) — AI 開發助手（本 Image 內建）
+- [trae-agent](https://github.com/bytedance/trae-agent) — ByteDance 開源 AI Agent
+- [GHCR](https://ghcr.io) — GitHub Container Registry
+
+## License
+
+MIT
+
 ## 專案目錄結構
 
 ```

README.zh-CN.md

@@ -4,8 +4,33 @@
 
 # Dev Docker Image Packages
 
+![GitHub Release](https://img.shields.io/github/v/release/shumingyang-opencode/dev-docker-image-packages)
+![GHCR Pulls](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr.io%2Fv2%2Fshumingyang-opencode%2Fpy-devkit-image-base&label=GHCR%20pulls&query=%24.pull_count)
+![GitHub Actions Workflow](https://img.shields.io/github/actions/workflow/status/shumingyang-opencode/dev-docker-image-packages/build-image.yml)
+
 个人开发用 Docker Image 集合，通过 GitHub Actions 自动构建并发布至 GHCR。
 
+## Quick Start
+
+```bash
+# 1. 下载最新 Image
+docker pull ghcr.io/shumingyang-opencode/py-devkit-image-base:latest
+
+# 2. 启动开发容器
+docker run --rm -it ghcr.io/shumingyang-opencode/py-devkit-image-base:latest bash
+
+# 3. 查看内置 AI CLI
+opencode --version && copilot --help && lark-cli --version && trae-cli --version
+```
+
+## 需求
+
+- [Docker](https://docs.docker.com/get-docker/) 已安装
+- GitHub 账号（用于触发 CI 构建、E2E 测试）
+- 各 AI CLI 对应的 API Key（Advanced E2E 测试用）
+
+> 若只需要 **Pull & Run** Image，则只需要 Docker，不需要 GitHub 账号。
+
 ## 可用 Images
 
 | Image | 最新版本 | Base | 用途 | 说明文档 |
@@ -14,6 +39,17 @@
 
 > 详细 Image 索引请见 [images/README.md](./images/README.md)。
 
+## 内置 AI CLI 工具
+
+| CLI | 安装方式 | 用途 | 需 API Key |
+|-----|---------|------|:----------:|
+| `opencode` | npm (opencode-ai) | AI 开发助手 | ✅ |
+| `copilot` | npm (@github/copilot) | GitHub Copilot Agent | ✅ |
+| `lark-cli` | npm (@larksuite/cli) | 飞书开发工具（内部网络专用） | ❌ |
+| `trae-cli` | pip (trae-agent) | AI Code Agent | ✅ |
+
+> API Key 通过环境变量传递，详见各 Image 说明文件。
+
 ## Image Tags
 
 每个 Image 发布至 GHCR 时会标记以下 tags：
@@ -198,6 +234,26 @@ bash skills/install.sh
 | 「加 image」 / 「new image」 / 「create image」 | 互动式新增 Image（Dockerfile + README） |
 | 「build image」 / 「建置 image」 | 触发 GitHub Actions 构建指定 Image |
 
+## 贡献
+
+欢迎提交 PR 或 Feature Request：
+
+1. **新增 Image** — 在 `images/<name>/` 下建立 Dockerfile + 测试脚本，并在 `tests/e2e/agents/` 新增对应的配置文件
+2. **改善测试** — 补强 E2E 测试案例或新增测试覆盖范围
+3. **文档修正** — 修正错字、补全说明、改善文档质量
+
+提交方式：Fork 此项目 → 开发 → 提交 PR → 我会审核后合并
+
+## 相关项目
+
+- [OpenCode](https://opencode.ai) — AI 开发助手（本 Image 内置）
+- [trae-agent](https://github.com/bytedance/trae-agent) — ByteDance 开源 AI Agent
+- [GHCR](https://ghcr.io) — GitHub Container Registry
+
+## License
+
+MIT
+
 ## 项目目录结构
 
 ```