add(workshop): introduce UCAgent workshop demonstration environment

feat: introduce UCAgent workshop demonstration environment

Author: SFangYy

.github/workflows/envbase.yaml

@@ -6,6 +6,9 @@ on:
     paths:
       - "docker/Dockerfile"
       - "docker/Dockerfile.full"
+      - "docker/Dockerfile.workshop"
+      - "docker/start_demo.sh"
+      - "workshop/data/**"
       - ".github/workflows/envbase.yaml"
   workflow_run:
     workflows: [ "envbase" ]
@@ -84,4 +87,39 @@ jobs:
             ${{ env.REGISTRY }}/${{ env.FULL_IMAGE_NAME }}:${{ env.IMAGE_TAG }}
             ${{ env.REGISTRY }}/${{ env.FULL_IMAGE_NAME }}:latest
           cache-from: type=local,src=/tmp/.buildx-cache
-          cache-to: type=local,dest=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache
+
+  build-and-push-workshop:
+    runs-on: ubuntu-latest
+    # Optional: depends on full image if we use it as base, 
+    # but here we use ucagent:latest which is built from main repo.
+    # To be safe, we can run it after build-and-push-full if we want to ensure base layers are available
+    needs: build-and-push-full
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Workshop image
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: ./docker/Dockerfile.workshop
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/xs-mlvp/workshop:latest
+            ${{ env.REGISTRY }}/xs-mlvp/workshop:${{ github.sha }}

docker/Dockerfile.workshop

@@ -0,0 +1,24 @@
+# UCAgent Workshop Docker Image
+ARG BASE_IMAGE=localhost/lucagent:latest
+FROM ${BASE_IMAGE}
+
+# Set environment variables
+ENV SUMMIT_DATA_DIR=/workspace/UCAgent/summit_examples
+
+# Copy workshop data to the expected location
+# Context should be the root of the tutorial-records repository
+COPY workshop/data/ ${SUMMIT_DATA_DIR}/
+
+# Copy and setup startup script
+COPY workshop/start_demo.sh /workspace/UCAgent/start_demo.sh
+RUN chmod +x /workspace/UCAgent/start_demo.sh
+
+# Expose ports for Web UI and Agents
+# 8800: Master Web UI
+# 8000, 8001: Agent Web Consoles
+# 8765, 8766: Agent CMD APIs
+# 8818, 8819: Agent Web Terminals
+EXPOSE 8800 8000 8001 8765 8766 8818 8819
+
+# Set the startup script as the default command
+CMD ["/workspace/UCAgent/start_demo.sh"]

workshop/.env.template

@@ -0,0 +1 @@
+OPENAI_API_KEY=your_api_key_here\nOPENAI_API_BASE=your_api_base_here\nOPENAI_MODEL=your_model_name_here

workshop/README.md

@@ -0,0 +1,69 @@
+# UCAgent Workshop Quick Start Guide
+
+Welcome to the UCAgent Workshop! The code and environment for this workshop demonstration are available at the official repository: [https://github.com/XS-MLVP/tutorial-records](https://github.com/XS-MLVP/tutorial-records).
+
+This guide will walk you through pulling the pre-built environment, launching the Web UI, and exploring the pre-configured digital circuit verification cases.
+
+## 📦 Repository Overview
+
+In this repository, you will find:
+
+- **Pre-prepared Cases**: Classic verification examples along with their historical verification records.
+- **Docker Scripts**: The `Dockerfile` and `start_demo.sh` scripts, which our CI uses to automatically build and publish the workshop image.
+- **Environment Template**: A `.env.template` file for optional API configuration.
+
+---
+
+## 🚀 Quick Start (Viewing the Demo)
+
+You **do not** need to build the Docker image yourself. The tutorial repository's CI has automatically built and published the image for you.
+
+### 1. Pull the Docker Image
+
+First, pull the latest workshop image to your local machine:
+
+```bash
+docker pull ghcr.io/xs-mlvp/workshop:latest
+```
+
+### 2. Launch the Demo Environment
+
+Start the container using the following command. This will spin up the Master API server and load the pre-configured background agents:
+
+```bash
+docker run -it --rm --network host ghcr.io/xs-mlvp/ucagent:workshop_demo
+```
+
+_(Note: We use `--network host` so the container can easily map to your local ports and share your host's network settings.)_
+
+### 3. Explore the Web UI
+
+Once the terminal indicates that all services have started, open your web browser and navigate to:
+👉 **http://localhost:8800**
+
+In this unified Master Web Interface, you can:
+
+- **View Pre-loaded Tasks**: On the left-hand task panel, you will see the cases. Both should have a green **Online** status indicator.
+- **Review History**: Click the **API** connection button next to any task to jump into its real-time control center. Here, you can review previously generated code, stage verification logs, and Diff files without needing any LLM API keys.
+
+---
+
+## 🛠️ Advanced: Running Verifications Yourself (Optional)
+
+The quick start above is perfect for exploring the UI and viewing the pre-generated results. However, if you wish to write custom prompts and have UCAgent actively generate new code and run verifications in real-time, you must configure your Large Language Model (LLM) credentials.
+
+1. **Prepare your `.env` file**  
+   Copy the provided template and fill in your API credentials (e.g., OpenAI or a compatible interface):
+
+   ```bash
+   cp .env.template .env
+   # Edit .env to add your OPENAI_API_KEY, OPENAI_API_BASE, and OPENAI_MODEL
+   ```
+
+2. **Launch with API Access**  
+   Run the container again, this time attaching your `.env` file so the agents can connect to the LLM:
+   ```bash
+   docker run -it --rm --network host --env-file .env ghcr.io/xs-mlvp/workshop:latest
+   ```
+
+With your API keys successfully loaded, the Agents are now fully empowered to execute new automated verification workflows based on your commands!

workshop/README.zh.md

@@ -0,0 +1,69 @@
+# UCAgent Workshop 快速上手指南
+
+欢迎来到 UCAgent Workshop！本次 Workshop 演示的代码和环境已经全部开源在官方仓库中：[https://github.com/XS-MLVP/tutorial-records](https://github.com/XS-MLVP/tutorial-records)。
+
+本指南将带你拉取预先构建好的环境、启动 Web UI，并探索我们为你准备好的数字电路芯片验证案例。
+
+## 📦 仓库内容简介
+
+在这个仓库中，包含了以下内容：
+
+- **预置验证案例**：经典的数字电路验证案例（如exu_alu和 ifu_bpu），以及它们离线跑完的历史验证记录。
+- **Docker 脚本**：`Dockerfile` 和 `start_demo.sh`，我们的 CI 流水线会自动使用它们来构建和发布本次 Workshop 的镜像。
+- **环境配置模板**：`.env.template` 文件，用于你在后续环节配置自己的大模型 API。
+
+---
+
+## 🚀 快速开始（体验演示案例）
+
+你**不需要**从头开始构建 Docker 镜像，tutorial 仓库的 CI 已经自动帮你打包并发布好了。
+
+### 1. 拉取镜像
+
+首先，将最新的 Workshop 镜像拉取到你的本地电脑：
+
+```bash
+docker pull ghcr.io/xs-mlvp/workshop:latest
+```
+
+### 2. 启动演示环境
+
+运行以下命令来启动容器。这会自动启动 Master API 服务，并在后台加载好我们为你准备的预置任务：
+
+```bash
+docker run -it --rm --network host ghcr.io/xs-mlvp/workshop:latest
+```
+
+_(注意：我们使用了 `--network host` 参数，这样容器可以直接映射并使用你宿主机的网络和端口。)_
+
+### 3. 探索 Web UI
+
+当终端提示服务启动完毕后，打开你的浏览器并访问：
+👉 **http://localhost:8800**
+
+在这个统一管理的 Master Web 界面中，你可以：
+
+- **查看预置任务**：在左侧的任务面板中，你会看到 `Adder` 和 `ALU754` 两个案例，它们应该都已经亮起了绿色的 **Online** 状态灯。
+- **复盘历史记录**：点击任意任务旁边的 **API** 按钮，即可进入该任务的实时控制台。在这里，你不需要配置任何大模型 Key，就可以直接查看 AI 之前生成的验证代码、日志以及阶段比对（Diff）。
+
+---
+
+## 🛠️ 进阶操作：亲自运行大模型验证（可选）
+
+上述的基础体验步骤非常适合浏览 UI 和查看预生成的验证结果。但是，如果你想亲自向 AI 下发 Prompt，让 UCAgent 实时为你生成新的验证代码并执行测试，你就需要配置自己的大模型（LLM）API 凭证了。
+
+1. **准备 `.env` 配置文件**  
+   复制我们提供的模板文件，填入你的 API Key 等信息（支持 OpenAI 或兼容接口）：
+
+   ```bash
+   cp .env.template .env
+   # 编辑 .env 文件，补全 OPENAI_API_KEY, OPENAI_API_BASE 和 OPENAI_MODEL
+   ```
+
+2. **携带 API 权限启动**  
+   使用挂载了环境变量的命令重新运行容器，让内部的 Agent 连接到大模型网络：
+   ```bash
+   docker run -it --rm --network host --env-file .env ghcr.io/xs-mlvp/ucagent:workshop_demo
+   ```
+
+配置成功后，各个 Agent 就拥有了完整的执行能力，你可以开始下达新的指令，开启真正的自动化验证之旅了！

workshop/data/.ucagent/history

@@ -0,0 +1 @@
+Subproject commit 70e1f0bb23aabc541490f219c250875c2e97544c