From 93427f26a6a0b30320eaef758e4c53636921d3de Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 11 Feb 2026 21:14:17 +0000
Subject: [PATCH] Add Google Cloud Build deployment configuration and AGENTS.md
 instructions

Co-authored-by: end8cl01g <122174271+end8cl01g@users.noreply.github.com>
---
 AGENTS.md       | 40 ++++++++++++++++++++++++++++++++++++++++
 Dockerfile      | 44 ++++++++++++++++++++++++++++++++++++++++++++
 cloudbuild.yaml | 28 ++++++++++++++++++++++++++++
 3 files changed, 112 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 Dockerfile
 create mode 100644 cloudbuild.yaml

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..65169c723
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,40 @@
+# AGENTS.md
+
+## 專案部署與自動化 (Project Deployment and Automation)
+
+本專案支持使用 Google Cloud Build 進行自動化部署。
+
+### 1. 關鍵部署文件 (Key Deployment Files)
+- `Dockerfile`: 使用多階段構建（Multi-stage build）的 Go 1.24 環境，最終鏡像基於 Alpine Linux。
+- `cloudbuild.yaml`: 配置了 Google Cloud Build 的步驟，包括構建鏡像並推送到 Google Artifact Registry。
+
+### 2. 代理人維護任務 (Agent Maintenance Tasks)
+身為開發代理人，在維護此專案時應遵守以下原則：
+
+- **同步更新**:
+  - 當修改 `Makefile` 中的編譯參數（如 `LDFLAGS`）時，必須同步更新 `Dockerfile` 中的 `go build` 命令。
+  - 當新增系統級依賴（如 C 庫）時，需在 `Dockerfile` 的構建或運行階段安裝對應的 `apk` 包。
+
+- **構建驗證**:
+  - 在提交涉及構建邏輯的代碼前，建議先在本地嘗試構建 Docker 鏡像：
+    ```bash
+    docker build -t picoclaw-local .
+    ```
+
+- **部署配置**:
+  - 如果部署環境發生變化（例如從 GCR 遷移到 Artifact Registry，或更改區域），請更新 `cloudbuild.yaml` 中的 `substitutions`。
+  - 默認配置：
+    - `_LOCATION`: `us-central1`
+    - `_REPOSITORY`: `picoclaw`
+    - `_IMAGE_NAME`: `picoclaw`
+
+### 3. 手動觸發構建 (Manual Build Trigger)
+如果自動觸發失效或需要即時部署，請執行：
+```bash
+gcloud builds submit --config cloudbuild.yaml .
+```
+
+### 4. 運行時注意事項 (Runtime Notes)
+- 鏡像默認工作目錄為 `/app`。
+- `PICOCLAW_HOME` 環境變量設為 `/app/.picoclaw`。
+- 內置 Skills 已打包進 `/app/skills`，但在運行時程序會優先查找工作目錄下的 `skills` 或 `WORKSPACE_DIR/skills`。
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 000000000..269430423
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,44 @@
+# Build stage
+FROM golang:1.24-alpine AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apk add --no-cache make git
+
+# Copy go mod and sum files
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the application
+# We manually set LDFLAGS to ensure they are correct in the container
+RUN VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "dev") && \
+    BUILD_TIME=$(date +%FT%T%z) && \
+    go build -ldflags "-X main.version=${VERSION} -X main.buildTime=${BUILD_TIME}" -o picoclaw ./cmd/picoclaw
+
+# Runtime stage
+FROM alpine:latest
+
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apk add --no-cache ca-certificates tzdata
+
+# Copy binary from builder
+COPY --from=builder /app/picoclaw /usr/local/bin/picoclaw
+
+# Copy builtin skills
+COPY --from=builder /app/skills /app/skills
+
+# Set environment variables
+ENV PICOCLAW_HOME=/app/.picoclaw
+
+# Create workspace directory
+RUN mkdir -p /app/.picoclaw/workspace
+
+# Set the entrypoint
+ENTRYPOINT ["picoclaw"]
+CMD ["gateway"]
diff --git a/cloudbuild.yaml b/cloudbuild.yaml
new file mode 100644
index 000000000..e75df12e4
--- /dev/null
+++ b/cloudbuild.yaml
@@ -0,0 +1,28 @@
+steps:
+  # Build the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: [
+      'build',
+      '-t', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE_NAME}:$COMMIT_SHA',
+      '-t', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE_NAME}:latest',
+      '.'
+    ]
+
+  # Push the container image to Artifact Registry
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE_NAME}:$COMMIT_SHA']
+
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE_NAME}:latest']
+
+images:
+  - '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE_NAME}:$COMMIT_SHA'
+  - '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE_NAME}:latest'
+
+substitutions:
+  _LOCATION: us-central1
+  _REPOSITORY: picoclaw
+  _IMAGE_NAME: picoclaw
+
+options:
+  logging: CLOUD_LOGGING_ONLY