Multica 教學手冊（企業級實戰版）

版本： v0.3.33（2026-06-30）
適用對象： 資深工程師、架構師、DevOps 工程師、技術主管
技術棧： Go Backend + Next.js 16 Frontend + PostgreSQL 17 + pgvector + Redis（選用）+ Agent Daemon
授權： Multica Source Available License（非 SaaS/轉售可自由使用）
文件等級： 企業標準技術白皮書

目錄

• 第 1 章：Multica 概述
  • 1.1 什麼是 Multica？
  • 1.2 名稱由來
  • 1.3 核心設計理念
  • 1.4 與傳統工具的差異比較
  • 1.5 適用場景
  • 1.6 專案基本資訊
  • 1.7 授權模式說明
• 第 2 章：系統架構設計
  • 2.1 整體架構概覽
  • 2.2 技術棧詳解
  • 2.3 元件說明
  • 2.4 企業整合架構
  • 2.5 資料流向與通訊模型
• 第 3 章：安裝與部署
  • 3.1 部署模式選擇
  • 3.2 Self-Hosted 快速部署（推薦）
  • 3.3 Self-Hosted 手動部署（Step-by-Step）
  • 3.4 Kubernetes 部署（Helm Chart）
  • 3.5 環境變數設定
  • 3.6 Production 部署（反向代理）
  • 3.7 不使用 Docker 的手動部署
  • 3.8 Usage Dashboard Rollup 設定
  • 3.9 停止服務
  • 3.10 切換至 Multica Cloud
• 第 4 章：核心運作機制
  • 4.1 任務生命週期（Issue Lifecycle）
  • 4.2 Agent 自主執行流程
  • 4.3 任務排程與佇列機制
  • 4.4 WebSocket 通訊流程
  • 4.5 Execution History 查詢
  • 4.6 Issue Metadata（結構化屬性）
  • 4.7 Subscribers（訂閱機制）
  • 4.8 Thread-aware Comments（串接式評論）
• 第 5 章：AI Agent 整合
  • 5.1 支援的 AI Agent
  • 5.2 Agent CLI 安裝
  • 5.3 CLI 自動偵測機制
  • 5.4 Agent 環境變數（Per-Agent 設定）
  • 5.5 Agent 建立與設定
  • 5.6 Prompt 設計策略（Agent 專用）
  • 5.7 多 Agent 協作模式
• 第 6 章：開發流程
  • 6.1 完整開發流程
  • 6.2 Issue 管理
  • 6.3 範例：Spring Boot API 開發流程
  • 6.4 範例：Vue 前端功能開發流程
  • 6.5 與 Git Flow 整合
• 第 7 章：Skill（技能）機制設計
  • 7.1 Skill 概念
  • 7.2 Skill 類型
  • 7.3 Skill 定義與儲存
  • 7.4 範例：自動部署 Skill
  • 7.5 範例：Code Review Skill
  • 7.6 範例：DB Migration Skill
  • 7.7 建立企業級 Skill Library
• 第 8 章：多工作空間（Workspace）設計
  • 8.1 Workspace 概念
  • 8.2 Workspace CLI 管理
  • 8.3 團隊隔離策略
  • 8.4 權限控管（RBAC）
  • 8.5 多 Daemon Profile
  • 8.6 工作空間垃圾回收（Workspace GC）
• 第 9 章：Squads（團隊編組）
  • 9.1 Squads 概念
  • 9.2 Squad 的價值
  • 9.3 企業應用場景
• 第 10 章：Autopilots（自動化排程）
  • 10.1 Autopilots 概念
  • 10.2 Autopilot CLI 管理
  • 10.3 企業應用範例
• 第 11 章：Projects（專案管理）
  • 11.1 Projects 概念
  • 11.2 Project CLI 管理
  • 11.3 Project 與 Issue 整合
  • 11.4 企業應用場景
• 第 12 章：MCP 整合（Model Context Protocol）
  • 12.1 MCP 概述
  • 12.2 MCP 整合場景
• 第 13 章：系統維運（Operations）
  • 13.1 Log 管理
  • 13.2 Agent 狀態監控
  • 13.3 監控架構
  • 13.4 建議監控指標
  • 13.5 錯誤處理與復原
  • 13.6 效能優化
• 第 14 章：系統升級與擴展（Upgrade & Scaling）
  • 14.1 Multica 升級策略
  • 14.2 版本管理策略
  • 14.3 Agent 水平擴展
  • 14.4 高可用架構（HA）
  • 14.5 切換至 Multica Cloud
• 第 15 章：安全設計（Security）
  • 15.1 認證與授權
  • 15.2 Agent 權限隔離
  • 15.3 憑證管理
  • 15.4 網路安全
  • 15.5 SSDLC 整合
• 第 16 章：最佳實務（Best Practices）
  • 16.1 團隊導入策略
  • 16.2 Prompt Engineering 原則
  • 16.3 Agent 使用規範
  • 16.4 常見錯誤與避免方式
  • 16.5 開發環境最佳實務
• 第 17 章：實戰案例（Case Study）
  • 17.1 案例：建立企業 Web 系統
  • 17.2 案例總結
• 附錄 A：檢查清單（Checklist）
• 附錄 B：CLI 快速參考卡
• 附錄 C：術語表（Glossary）

第 1 章：Multica 概述

1.1 什麼是 Multica？

Multica 是一個開源的 Managed AI Agent 平台，致力於將 AI 編碼代理轉化為團隊中真正的「虛擬隊友」。有別於傳統 AI 對話工具的被動互動模式，Multica 提供完整的任務管理與 Agent 自主執行基礎設施，使 AI Agent 成為開發流程中不可或缺的一等公民（First-Class Citizen）。

“Your next 10 hires won’t be human.” — Multica 官方標語

Multica 的核心能力涵蓋以下面向：

• Agent as Teammate： Agent 擁有個人檔案與看板呈現，如同人類同事般被指派 Issue、參與討論對話、主動回報 Blocker
• Squads（團隊編組）： 將多個 Agent（與人類）組成由 Leader Agent 領導的團隊，透過 @FrontendTeam 等方式指派工作，由 Leader 自動分派至適當成員
• Autonomous Execution： 完整的任務生命週期管理（enqueue → claim → start → complete/fail），搭配 WebSocket 即時進度串流
• Autopilots（自動化排程）： 支援 Cron 排程、Webhook 觸發或手動執行，自動建立 Issue 並路由至指定 Agent，適用於每日站立會議、週報、定期稽核等場景
• Reusable Skills： 每個解決方案自動轉化為可重用的技能，部署、遷移、審查等技能隨時間複利成長
• Unified Runtimes： 統一管理本地 Daemon 與雲端 Runtime，自動偵測可用 CLI，即時監控執行環境
• Vendor-Neutral： 支援 13 種以上 AI Agent CLI（Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi、Kiro CLI、Antigravity、Qoder CLI）
• Self-Hosted First： 可完全自部署於企業基礎設施，資料不離開企業環境

1.2 名稱由來

Multica — Multiplexed Information and Computing Agent（多工資訊與計算代理）。

此命名致敬 1960 年代的先驅作業系統 Multics，該系統首創了分時共享（Time-Sharing）概念——讓多位使用者共享一台機器，彷彿各自擁有獨立運算資源。Unix 作為 Multics 的精簡化衍生，奠定了「單一使用者、單一任務」的設計哲學。

Multica 認為相同的典範轉移正在發生。數十年來，軟體團隊本質上是單執行緒運作——一位工程師、一個任務、一次上下文切換。AI Agent 改變了這個方程式。Multica 將分時共享的理念帶回，但服務對象擴展為人類與自主代理並行的時代。

正如 Multics 的願景，Multica 的核心假設是多工複用：一個小團隊不應該感覺小。有了正確的系統，兩位工程師加上一支 Agent 艦隊，可以發揮如同二十人團隊的戰力。

1.3 核心設計理念

1.4 與傳統工具的差異比較

與 AI 工具（Copilot / ChatGPT）差異

與任務管理工具（Jira / Linear）差異

1.5 適用場景

1.6 專案基本資訊

1.7 授權模式說明

Multica 採用 Multica Source Available License，商業限制精準鎖定 SaaS 與轉售場景，具體規範如下：

法務建議： 企業導入前，建議法務團隊審閱完整 LICENSE 文件，確認商業使用不涉及 SaaS 或轉售行為。

實務建議： Multica 適合中大型團隊（5+ 人），且需要有至少一位熟悉 Docker + Go + Node.js 的工程師負責維運。Kubernetes 部署另需具備 Helm 與 K8s 經驗。

第 2 章：系統架構設計（Enterprise Architecture）

2.1 整體架構概覽

graph TB
    subgraph "使用者層 (User Layer)"
        DEV[👨‍💻 開發人員]
        PM[📋 專案經理]
        ADMIN[🔧 系統管理員]
        MOBILE[📱 iOS 行動端]
    end

    subgraph "前端層 (Frontend Layer)"
        WEB[Next.js 16 Web App<br/>App Router]
    end

    subgraph "後端層 (Backend Layer)"
        API[Go Backend<br/>Chi Router + sqlc]
        WS[WebSocket Server<br/>gorilla/websocket]
        AUTH[認證模組<br/>JWT + Magic Link + Google OAuth]
        MIGRATE[Migration Engine<br/>自動遷移]
        ROLLUP[Usage Rollup<br/>task_usage_hourly]
    end

    subgraph "資料層 (Data Layer)"
        DB[(PostgreSQL 17<br/>+ pgvector)]
        S3[S3 / Local Storage<br/>檔案儲存]
    end

    subgraph "Agent 運行層 (Agent Runtime Layer)"
        DAEMON1[Agent Daemon #1<br/>開發機 A]
        DAEMON2[Agent Daemon #2<br/>開發機 B]
        CLOUD_RT[Cloud Runtime<br/>雲端運行環境]
    end

    subgraph "AI Agent 層（13+ 種支援）"
        CLAUDE[Claude Code]
        CODEX[Codex]
        COPILOT[GitHub Copilot CLI]
        HERMES[Hermes]
        GEMINI[Gemini]
        OTHERS[Pi / Cursor Agent / Kimi<br/>Kiro CLI / OpenClaw / OpenCode<br/>Antigravity / Qoder CLI]
    end

    subgraph "外部整合 (External Integration)"
        GITHUB[GitHub / GitLab]
        CICD[CI/CD Pipeline]
        MONITOR[Monitoring System]
    end

    DEV --> WEB
    PM --> WEB
    ADMIN --> WEB
    MOBILE --> API

    WEB -->|REST API| API
    WEB -->|Real-time| WS

    API --> AUTH
    API --> DB
    API --> S3
    API --> MIGRATE
    API --> ROLLUP

    WS -->|任務分派| DAEMON1
    WS -->|任務分派| DAEMON2
    WS -->|任務分派| CLOUD_RT

    DAEMON1 --> CLAUDE
    DAEMON1 --> CODEX
    DAEMON1 --> COPILOT
    DAEMON2 --> HERMES
    DAEMON2 --> GEMINI
    CLOUD_RT --> OTHERS

    DAEMON1 -->|Git Push| GITHUB
    GITHUB --> CICD
    API --> MONITOR

2.2 技術棧詳解

2.3 元件說明

2.3.1 Multica Server（Go Backend）

• REST API： 處理所有 CRUD 操作（Issue / Agent / Workspace / Skill / Project / Autopilot / Squad）
• WebSocket Server： 即時雙向通訊，任務狀態串流
• sqlc： 編譯期 SQL Type Safety（非 ORM）
• Migration Engine： 資料庫遷移自動執行（冪等設計，重複執行安全）
• Health Check： GET /healthz → {"status":"ok","checks":{"db":"ok","migrations":"ok"}}
• Usage Rollup： task_usage_hourly 聚合表，驅動 Usage Dashboard
• Config API： GET /api/config 動態回傳 ALLOW_SIGNUP、DISABLE_WORKSPACE_CREATION、GOOGLE_CLIENT_ID 設定

2.3.2 Agent Daemon

Daemon 是在開發者本機執行的背景程序：

1. 啟動時自動偵測已安裝的 AI Agent CLI（claude、codex、copilot、openclaw、opencode、hermes、gemini、pi、cursor-agent、kimi、kiro-cli、agy、qodercli）
2. 為每個偵測到的 Agent 在每個被監控的 Workspace 中註冊 Runtime
3. 以設定的間隔（預設 3 秒）輪詢 Server 是否有已認領（claimed）的任務
4. 收到任務後建立隔離的工作目錄，啟動 Agent CLI 執行
5. 透過 WebSocket 即時回傳執行結果
6. 定期發送心跳（預設 15 秒）
7. 關閉時自動取消註冊所有 Runtime
8. 內建工作空間垃圾回收（GC）機制，自動清理已完成任務的工作目錄

2.3.3 Web UI Dashboard

• 看板視圖（Board View）： Kanban 式任務管理，Agent 與人類並列顯示
• Agent 檔案： 每個 Agent 都有個人頁面
• Runtime 管理： 查看所有連接的運行環境
• Skill Library： 瀏覽與管理可重用技能
• 即時串流： WebSocket 即時顯示 Agent 執行進度
• Projects 管理： 群組式 Issue 管理（Sprint / Epic）
• Autopilots 管理： 排程自動化任務
• Squads 管理： 團隊編組與路由設定
• Usage Dashboard： 基於 task_usage_hourly 的使用量統計

2.3.4 AI Agent 支援

Multica 支援 13 種以上 AI Agent CLI，Daemon 啟動時自動偵測 PATH 中已安裝的 CLI：

2.4 企業整合架構

graph LR
    subgraph "Multica Platform"
        MS[Multica Server]
        MD[Multica Daemon]
    end

    subgraph "版本控制"
        GH[GitHub Enterprise]
        GL[GitLab]
    end

    subgraph "CI/CD"
        GA[GitHub Actions]
        JK[Jenkins]
    end

    subgraph "資料庫"
        PG[(PostgreSQL)]
        ORA[(Oracle)]
        DB2[(DB2)]
    end

    subgraph "容器與編排"
        GHCR[GHCR Registry]
        K8S[Kubernetes / k3s]
        HELM[Helm Chart]
    end

    subgraph "監控"
        PROM[Prometheus]
        GRAF[Grafana]
        ELK[ELK Stack]
    end

    MS -->|Webhook| GH
    MS -->|Webhook| GL
    GH -->|Trigger| GA
    GL -->|Trigger| JK
    MD -->|Git Push/PR| GH
    MS -->|Metrics| PROM
    PROM --> GRAF
    MS -->|Logs| ELK
    MS --> PG
    GHCR --> K8S
    HELM --> K8S

實務建議： 在銀行或金融業環境中，Multica Server 應部署在內部網路，Daemon 執行在開發者本機或專屬 Build Server，所有對外連線需經過企業 Proxy。Kubernetes 部署可使用 OCI Helm Chart 搭配企業內部 Ingress Controller。

2.5 資料流向與通訊模型

flowchart LR
    subgraph "同步通訊"
        A[Web UI] -->|REST API / HTTP| B[Go Backend]
        B -->|SQL| C[(PostgreSQL)]
    end

    subgraph "非同步通訊"
        D[Agent Daemon] <-->|WebSocket| E[Go Backend]
        F[Web Browser] <-->|WebSocket| E
    end

    subgraph "檔案儲存"
        B -->|S3 SDK| G[S3 / CloudFront]
        B -->|OS File IO| H[Local Storage]
    end

通訊協議說明：

實務建議： 企業環境建議所有對外通訊走 TLS 加密。WebSocket 連線在使用反向代理時需特別設定 Upgrade 標頭，否則會導致即時功能失效。

第 3 章：安裝與部署（Installation & Setup）

3.1 部署模式選擇

3.2 Self-Hosted 快速部署（推薦）

兩道指令即可完成 Server + CLI + 設定的完整部署：

前置條件

• Docker 及 Docker Compose
• 至少一個 AI Agent CLI（claude / codex / copilot 等）

一鍵安裝

# 1. 安裝 CLI 並啟動 Self-Host Server
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server

# 2. 設定 CLI、認證並啟動 Daemon
multica setup self-host

此指令會自動：

• 從 GHCR 拉取最新穩定版本映像
• 建立 .env 並產生隨機 JWT_SECRET
• 啟動 Docker Compose（PostgreSQL + Backend + Frontend）
• 設定 CLI 連線至 localhost（8080/3000）
• 開啟瀏覽器進行認證
• 偵測並註冊所有工作空間
• 啟動 Daemon

完成後：

• Frontend： http://localhost:3000
• Backend API： http://localhost:8080

CLI 單獨安裝（Server 已部署時）

# macOS / Linux — Homebrew（推薦）
brew install multica-ai/tap/multica

# macOS / Linux — Install Script
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

# Windows — PowerShell
irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex

3.3 Self-Hosted 手動部署（Step-by-Step）

Step 1：啟動 Server

# Clone Repository
git clone https://github.com/multica-ai/multica.git
cd multica

# 使用 make 自動部署（推薦）
make selfhost
# 自動完成：
# - 從 .env.example 建立 .env
# - 產生隨機 JWT_SECRET
# - 從 GHCR 拉取最新映像
# - 啟動 Docker Compose（PostgreSQL + Backend + Frontend）

注意： 預設從 GHCR 拉取最新穩定映像。若指定的 GHCR Tag 尚未發布，make selfhost 會提示改用 make selfhost-build 從原始碼編譯。make selfhost-build 使用本地 multica-backend:dev / multica-web:dev 標籤，不會覆蓋已拉取的 :latest 映像。

或手動操作：

# 手動部署
cp .env.example .env

# 修改 .env：至少設定 JWT_SECRET
JWT_SECRET=$(openssl rand -hex 32)
# 將產生的 secret 寫入 .env

# 拉取映像並啟動服務
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

Step 2：登入系統

Docker Self-Host 堆疊預設使用 APP_ENV=production，沒有固定驗證碼。登入方式有三種：

⚠️ 安全警告： 切勿在公開可達的實例上設定 MULTICA_DEV_VERIFICATION_CODE——任何知道 Email 地址的人都可以使用該固定碼登入。

Step 3：安裝 CLI 與啟動 Daemon

# macOS / Linux — Homebrew 安裝
brew install multica-ai/tap/multica

# 一鍵設定（推薦）
multica setup self-host
# 自動完成：
# 1. 設定 CLI 連線至 localhost（8080/3000）
# 2. 開啟瀏覽器認證
# 3. 發現所有工作空間
# 4. 啟動 Daemon

# 自訂域名（企業內部部署時）
multica setup self-host --server-url https://api.example.com --app-url https://app.example.com

Step 4：驗證

# 檢查 Daemon 狀態
multica daemon status

# JSON 輸出
multica daemon status --output json

開啟 Web App → Settings → Runtimes，確認看到你的機器。

3.4 Kubernetes 部署（Helm Chart）

Multica 提供 OCI Helm Chart，適用於已有 Kubernetes 叢集的企業環境。Chart 目標為典型的 k3s/k8s 設定，搭配 Ingress Controller 與預設 ReadWriteOnce StorageClass。

Chart 建立的資源：

• multica-postgres — pgvector/pgvector:pg17，10Gi PVC
• multica-backend — Go API/WS Server，5Gi uploads PVC
• multica-frontend — Next.js standalone server
• 兩個 Ingress 資源：Web 與 Backend
• multica-config ConfigMap

Step 1：設定主機名稱

# 在 /etc/hosts 或 DNS 中設定
# 替換為叢集 Ingress IP
192.168.1.206  multica.dev.lan api.multica.dev.lan

Step 2：建立 Namespace 與 Secret

kubectl create namespace multica

kubectl -n multica create secret generic multica-secrets \
  --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \
  --from-literal=POSTGRES_PASSWORD="$(openssl rand -hex 16)" \
  --from-literal=RESEND_API_KEY="" \
  --from-literal=GOOGLE_CLIENT_SECRET="" \
  --from-literal=CLOUDFRONT_PRIVATE_KEY="" \
  --from-literal=MULTICA_DEV_VERIFICATION_CODE=""

Step 3：安裝 Chart

helm install multica oci://ghcr.io/multica-ai/charts/multica \
  --version <chart-version> \
  -n multica

# 查看預設值
helm show values oci://ghcr.io/multica-ai/charts/multica \
  --version <chart-version> > my-values.yaml
# 編輯後安裝
helm install multica oci://ghcr.io/multica-ai/charts/multica \
  --version <chart-version> \
  -n multica \
  -f my-values.yaml

# 監控 Pod 啟動
kubectl -n multica get pods -w

# 驗證
curl -H "Host: api.multica.dev.lan" http://<ingress-ip>/healthz
# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}

注意： 已發布的 Chart Version 會去掉 Git Tag 的前綴 v。例如 v0.3.5 對應 Chart Version 0.3.5。每個 Namespace 只能安裝一個 Multica Release。

Step 4：安裝 CLI 與啟動 Daemon

multica setup self-host \
  --server-url http://api.multica.dev.lan \
  --app-url http://multica.dev.lan

Kubernetes 升級

# 升級到特定版本
helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \
  --version <chart-version> \
  -n multica \
  -f my-values.yaml

# 回滾
helm -n multica rollback multica

3.5 環境變數設定

Server 端必要變數

Email 認證（Production 必要）

Multica 亦支援 SMTP Relay 作為替代方案，支援 implicit TLS（SMTPS/465）：

Google OAuth（選用）

檔案儲存（選用）

注意： 若未設定 S3 相關變數，Multica 會自動回退使用本地檔案系統（Local File Storage Fallback）儲存上傳檔案。此功能適用於開發環境或不需要分散式儲存的場景。

開發環境專用

Redis（選用，Session / Rate Limiting 快取）

注意： Redis 為選用元件。未設定時 Multica 使用 in-memory 快取，適合單節點部署。多節點 HA 建議啟用 Redis。

資料庫連線池（選用）

可觀測性（選用）

註冊與存取控制

HTTP 與 Cookie

Daemon 端設定

注意： Daemon 端變數也可透過 CLI Flag 設定，例如 multica daemon start --poll-interval 5s --max-concurrent-tasks 10。完整 Flag 清單請參考 CLI and Daemon Guide。

3.6 Production 部署（反向代理）

Caddy（推薦）

方式一：雙域名佈局（推薦）

app.example.com {
    reverse_proxy localhost:3000
}

api.example.com {
    reverse_proxy localhost:8080
}

方式二：單域名佈局（路徑式）

適用於只有一個域名、或內網部署的場景：

multica.example.com {
    handle /api/* {
        reverse_proxy localhost:8080
    }
    handle /ws {
        reverse_proxy localhost:8080
    }
    handle {
        reverse_proxy localhost:3000
    }
}

對應環境變數：

FRONTEND_ORIGIN=https://multica.example.com
REMOTE_API_URL=https://multica.example.com/api
NEXT_PUBLIC_API_URL=https://multica.example.com/api
NEXT_PUBLIC_WS_URL=wss://multica.example.com/ws

方式三：LAN 內網存取（無 TLS）

適用於開發或信任內網環境，Caddy 提供 HTTP 反代無自動 HTTPS：

:80 {
    handle /api/* {
        reverse_proxy localhost:8080
    }
    handle /ws {
        reverse_proxy localhost:8080
    }
    handle {
        reverse_proxy localhost:3000
    }
}

# LAN 環境變數
FRONTEND_ORIGIN=http://192.168.1.100
REMOTE_API_URL=http://192.168.1.100/api
NEXT_PUBLIC_API_URL=http://192.168.1.100/api
NEXT_PUBLIC_WS_URL=ws://192.168.1.100/ws
COOKIE_SECURE=false

Nginx

# Frontend
server {
    listen 443 ssl;
    server_name app.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Backend API + WebSocket
server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket 支援（關鍵！）
    location /ws {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

環境變數設定（分離域名）

# Backend
FRONTEND_ORIGIN=https://app.example.com
CORS_ALLOWED_ORIGINS=https://app.example.com

# Frontend（Build 時設定）
REMOTE_API_URL=https://api.example.com
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_WS_URL=wss://api.example.com/ws

3.7 不使用 Docker 的手動部署

前置條件： Go 1.26+, Node.js 20+, pnpm 10.28+, PostgreSQL 17 + pgvector

# 1. 確保 PostgreSQL 已安裝 pgvector 擴充
psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 2. 編譯後端
make build

# 3. 執行資料庫遷移（冪等，可重複執行）
DATABASE_URL="postgres://multica:multica@localhost:5432/multica?sslmode=disable" \
  ./server/bin/migrate up

# 4. 啟動後端
DATABASE_URL="postgres://multica:multica@localhost:5432/multica?sslmode=disable" \
  PORT=8080 \
  JWT_SECRET="your-secret-here" \
  ./server/bin/server

# 5. 編譯並啟動前端
pnpm install
pnpm build
cd apps/web
REMOTE_API_URL=http://localhost:8080 pnpm start

實務建議： 企業環境強烈建議使用 Docker Compose 或 Kubernetes 部署，以確保環境一致性。將 .env 存放在安全的 Secret Manager（如 HashiCorp Vault）中，不要提交至版本控制。

3.8 Usage Dashboard Rollup 設定

Multica 的 Usage Dashboard 依賴 task_usage_hourly 聚合表來提供使用量統計。

自 v0.3.20 起：DB-backed In-Process Scheduler（MUL-2957）

自 v0.3.20 起，Multica 後端內建 DB-backed in-process scheduler，無需外部 cron 或 pg_cron。後端啟動時自動依據資料庫排程表執行 Rollup，預設每小時觸發一次 rollup_task_usage_hourly()。

優點：

• 零外部依賴，部署即啟用
• 排程狀態持久化於資料庫，重啟後自動恢復
• 支援叢集環境下的 leader election，避免重複執行

環境變數控制：

舊版替代方案（v0.3.19 及更早）

若使用舊版 Multica，仍可透過外部排程方式觸發：

選項一：系統 Cron Job

# 每小時執行一次聚合
0 * * * * psql "$DATABASE_URL" -c "SELECT rollup_task_usage_hourly();"

選項二：PostgreSQL pg_cron 擴充

-- 安裝 pg_cron（需 superuser 權限）
CREATE EXTENSION IF NOT EXISTS pg_cron;

-- 每小時執行聚合
SELECT cron.schedule(
  'multica-rollup',
  '0 * * * *',
  $$SELECT rollup_task_usage_hourly()$$
);

手動回填歷史資料

-- 回填特定時間範圍的歷史資料
SELECT backfill_task_usage_hourly(
  '2025-01-01 00:00:00+00',
  '2025-06-01 00:00:00+00'
);

實務建議： v0.3.20+ 使用者無需額外設定，內建 scheduler 已自動處理。舊版 Production 環境建議使用 pg_cron 方式，可避免外部 cron 依賴。

3.9 停止服務

使用安裝腳本停止

# 透過安裝腳本停止所有服務
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --stop

使用 Make 停止

# 停止 Docker Compose 服務（Backend + Frontend + PostgreSQL）
make selfhost-stop

# 停止本地 Daemon
multica daemon stop

手動停止

# 停止 Docker Compose 服務
docker compose -f docker-compose.selfhost.yml down

# 停止 Daemon
multica daemon stop

注意： docker compose down 僅停止容器，不會刪除資料庫卷宗。若需完全清除資料，使用 docker compose down -v（此操作不可逆）。

3.10 切換至 Multica Cloud

若已在使用 Self-Hosted 部署，希望切換至 Multica Cloud：

# 方式一：手動設定
multica config set server_url https://api.multica.ai
multica config set app_url https://multica.ai
multica login

# 方式二：透過安裝腳本（不帶 --with-server 參數會自動設定 Cloud）
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

注意： 切換至 Cloud 後，本地的 Docker 服務不會自動停止。如不再需要，請手動停止，參考 3.9 停止服務。

第 4 章：核心運作機制（Core Workflow）

4.1 任務生命週期（Issue Lifecycle）

Multica 的任務狀態機定義如下：

stateDiagram-v2
    [*] --> backlog : 建立 Issue
    backlog --> todo : 移入待辦
    todo --> in_progress : Agent 領取 / 人工開始
    in_progress --> in_review : 提交 PR
    in_review --> done : Review 通過
    in_review --> in_progress : 需修改
    in_progress --> blocked : 遇到阻礙
    blocked --> in_progress : 解除阻礙
    in_progress --> cancelled : 取消
    todo --> cancelled : 取消
    backlog --> cancelled : 取消
    done --> [*]
    cancelled --> [*]

4.2 Agent 自主執行流程

sequenceDiagram
    participant PM as 專案經理
    participant Web as Multica Web UI
    participant Server as Multica Server
    participant Daemon as Agent Daemon
    participant Agent as AI Agent (Claude Code)
    participant GitHub as GitHub

    PM->>Web: 建立 Issue 並指派給 Agent
    Web->>Server: POST /api/issues (assignee: agent-id)
    Server->>Server: 將任務加入佇列 (enqueue)

    loop 每 3 秒輪詢
        Daemon->>Server: GET /api/tasks/poll
    end

    Server-->>Daemon: 返回任務詳情
    Daemon->>Daemon: 建立隔離工作目錄
    Daemon->>Agent: 啟動 CLI + 傳入任務 Prompt

    loop Agent 執行中
        Agent->>Daemon: 輸出進度（stdout/stderr）
        Daemon->>Server: WebSocket 即時串流
        Server->>Web: 即時更新 UI
    end

    Agent->>Daemon: 執行完成
    Daemon->>GitHub: git push + 建立 PR
    Daemon->>Server: 任務完成 (status: in_review)
    Server->>Web: 更新看板
    Web-->>PM: 通知：PR 已建立

4.3 任務排程與佇列機制

flowchart LR
    subgraph "任務佇列 (Task Queue)"
        Q1[Priority: Urgent]
        Q2[Priority: High]
        Q3[Priority: Normal]
        Q4[Priority: Low]
    end

    subgraph "Daemon 排程器"
        SCHED[Scheduler<br/>max_concurrent: 20]
    end

    subgraph "Agent Workers"
        W1[Claude Code #1]
        W2[Claude Code #2]
        W3[Codex #1]
    end

    Q1 --> SCHED
    Q2 --> SCHED
    Q3 --> SCHED
    Q4 --> SCHED

    SCHED --> W1
    SCHED --> W2
    SCHED --> W3

• 輪詢間隔： 預設每 3 秒（可配置 MULTICA_DAEMON_POLL_INTERVAL）
• 最大併行數： 預設 20 個任務（可配置 MULTICA_DAEMON_MAX_CONCURRENT_TASKS）
• Priority： urgent > high > normal > low
• Agent 超時： 預設無上限（受 watchdog 約束，可透過 MULTICA_AGENT_TIMEOUT 設定具體時限）

4.4 WebSocket 通訊流程

sequenceDiagram
    participant Browser as Web Browser
    participant Server as Multica Server
    participant Daemon as Agent Daemon

    Browser->>Server: WS Connect (/ws)
    Server-->>Browser: Connected (Auth via JWT)

    Daemon->>Server: WS Connect (/ws)
    Server-->>Daemon: Connected (Auth via PAT)

    Note over Daemon: Agent 開始執行任務

    Daemon->>Server: message: { type: "progress", content: "正在分析需求..." }
    Server->>Browser: message: { type: "progress", content: "正在分析需求..." }

    Daemon->>Server: message: { type: "tool_call", tool: "file_write", path: "src/api.go" }
    Server->>Browser: message: { type: "tool_call", tool: "file_write" }

    Daemon->>Server: message: { type: "complete", status: "success" }
    Server->>Browser: message: { type: "complete", status: "success" }

    Note over Daemon: 每 15 秒心跳
    loop Heartbeat
        Daemon->>Server: ping
        Server-->>Daemon: pong
    end

4.5 Execution History 查詢

# 查看 Issue 的所有執行記錄
multica issue runs <issue-id>
multica issue runs <issue-id> --output json

# 查看特定執行的訊息日誌（工具呼叫、思考過程、錯誤）
multica issue run-messages <task-id>
multica issue run-messages <task-id> --output json

# 增量取得（只取序號 42 之後的訊息）
multica issue run-messages <task-id> --since 42 --output json

4.6 Issue Metadata（結構化屬性）

Multica 支援為 Issue 附加任意鍵值對的結構化 Metadata，可用於標記分類、自動化路由或 CI/CD 整合：

# 設定 Metadata（單一鍵值對）
multica issue metadata set <issue-id> --key environment --value production
multica issue metadata set <issue-id> --key team --value backend
multica issue metadata set <issue-id> --key sprint --value "2026-S12"

# 查詢 Metadata
multica issue metadata get <issue-id>
multica issue metadata get <issue-id> --key environment

# 刪除 Metadata
multica issue metadata delete <issue-id> --key environment

企業應用場景：

4.7 Subscribers（訂閱機制）

Subscribers 允許使用者訂閱特定 Issue 的狀態變更通知，無需成為 Assignee：

# 訂閱 Issue
multica issue subscriber add <issue-id> --user <user-id>

# 取消訂閱
multica issue subscriber remove <issue-id> --user <user-id>

# 列出訂閱者
multica issue subscriber list <issue-id>

適用場景：

• 專案經理訂閱所有高優先級 Issue
• Tech Lead 訂閱架構相關任務
• 安全團隊訂閱含安全標記的 Issue

4.8 Thread-aware Comments（串接式評論）

Issue 評論支援 --parent 參數，可建立巢狀的回覆串（Thread），適用於深入討論與決策記錄：

# 新增評論
multica issue comment add <issue-id> --content "需要加入 Rate Limiting"

# 回覆特定評論（Thread）
multica issue comment add <issue-id> --parent <comment-id> --content "收到，已處理"

# 列出評論
multica issue comment list <issue-id>

# 刪除評論
multica issue comment delete <comment-id>

實務建議： 在企業環境中，建議將 MULTICA_DAEMON_POLL_INTERVAL 設為 5s（降低 Server 負載），MULTICA_DAEMON_MAX_CONCURRENT_TASKS 根據機器資源設定（每個 Agent 約需 2-4GB RAM）。善用 Metadata 與 Subscribers 機制可大幅提升跨團隊協作效率。

第 5 章：AI Agent 整合（Agent Integration）

5.1 支援的 AI Agent

Multica 官方支援 13 種以上 AI Agent CLI，Daemon 啟動時會自動偵測 PATH 中已安裝的 CLI：

注意： 至少需安裝其中一個 Agent CLI 才能啟動 Daemon。Claude Code 與 Codex 是核心支援的 Agent，提供完整的 CLI 路徑覆寫、模型覆寫與額外參數功能。其他 Agent 均為官方支援，具備路徑覆寫能力。

5.2 Agent CLI 安裝

# Claude Code（核心支援）
npm install -g @anthropic-ai/claude-code
which claude && claude --version

# Codex（核心支援）
npm install -g @openai/codex
which codex && codex --version

# GitHub Copilot CLI
# 需 GitHub Copilot 訂閱
gh extension install github/gh-copilot
which copilot && copilot --version

# Gemini
pip install google-generativeai
which gemini && gemini --version

# 其他 Agent 請參考各自官方文件安裝

5.3 CLI 自動偵測機制

Daemon 啟動時自動掃描 PATH 中的 Agent CLI，並為每個偵測到的 Agent 在每個被監控的 Workspace 中註冊 Runtime：

# 啟動 Daemon（自動偵測所有已安裝的 Agent）
multica daemon start

# 查看偵測到的 Agent
multica daemon status
# 輸出範例：
# Status:     running
# PID:        12345
# Uptime:     2h30m
# Agents:     claude (v1.5.0), codex (v0.3.0), copilot, gemini
# Workspaces: 3 watched

# JSON 格式（適合自動化腳本）
multica daemon status --output json

5.4 Agent 環境變數（Per-Agent 設定）

每個 Agent 都支援獨立的路徑覆寫、模型覆寫與額外啟動參數。環境變數命名遵循統一模式：

MULTICA_<AGENT>_PATH    — CLI 執行檔路徑（當不在 PATH 中時）
MULTICA_<AGENT>_MODEL   — 模型覆寫
MULTICA_<AGENT>_ARGS    — 額外 CLI 啟動參數

完整環境變數對照表：

使用範例：

# 自訂 Claude Code 路徑與模型
export MULTICA_CLAUDE_PATH=/opt/tools/claude
export MULTICA_CLAUDE_MODEL=claude-sonnet-4-20250514

# 自訂 Codex 路徑、模型與額外參數
export MULTICA_CODEX_PATH=/opt/tools/codex
export MULTICA_CODEX_MODEL=o3-mini
export MULTICA_CODEX_ARGS="--full-auto"

# 設定 Codex 語義不活動超時（防止 Codex 停滯）
export MULTICA_CODEX_SEMANTIC_INACTIVITY_TIMEOUT=10m

# Daemon 啟動參數覆寫
multica daemon start \
  --poll-interval 5s \
  --heartbeat-interval 30s \
  --agent-timeout 4h \
  --max-concurrent-tasks 10

5.5 Agent 建立與設定

Web UI 方式

1. 開啟 Settings → Agents
2. 點擊 New Agent
3. 選擇 Runtime（你的機器）
4. 選擇 Provider（Claude Code / Codex / Copilot / Gemini / …）
5. 命名 Agent（將顯示在看板上）

CLI 方式

# 查看現有 Agent
multica agent list

5.6 Prompt 設計策略（Agent 專用）

為 Agent 設計高品質 Prompt 的原則：

## Issue 建立範例（最佳 Prompt 格式）

### 標題
實作使用者登入 API（JWT 認證）

### 描述
#### 目標
實作 POST /api/v1/auth/login 端點，支援 Email + 密碼認證。

#### 技術要求
- 使用 Spring Boot 3.x + Spring Security
- JWT Token 有效期：24 小時
- Refresh Token 有效期：7 天
- 密碼使用 BCrypt 雜湊
- 輸入驗證（Email 格式、密碼長度 8+）

#### 預期交付物
1. LoginController.java
2. AuthService.java
3. JwtTokenProvider.java
4. 單元測試（覆蓋率 > 80%）
5. API 文件更新

#### 限制條件
- 不使用 Session，純 Stateless
- 遵循 Clean Architecture 分層
- 符合 OWASP 安全規範

#### 參考
- 現有程式碼：src/main/java/com/example/auth/
- API 規格：docs/api-spec.yaml

5.7 多 Agent 協作模式

flowchart TB
    subgraph "Multica Board"
        I1[Issue: 後端 API 開發]
        I2[Issue: 前端頁面開發]
        I3[Issue: 資料庫遷移]
        I4[Issue: Code Review]
    end

    subgraph "Agent Team"
        A1[🤖 Claude-Backend<br/>Claude Code]
        A2[🤖 Vue-Builder<br/>Codex]
        A3[🤖 DB-Admin<br/>Claude Code]
        A4[🤖 Reviewer<br/>Claude Code]
    end

    I1 -->|assign| A1
    I2 -->|assign| A2
    I3 -->|assign| A3
    I4 -->|assign| A4

    A1 -->|完成後| I4
    A2 -->|完成後| I4
    A3 -->|完成後| I1

協作模式建議：

實務建議： 初期建議每個團隊使用 2-3 個 Agent，一個負責後端、一個負責前端、一個負責 Review。隨著 Skill 累積，再逐步增加 Agent 數量。

第 6 章：開發流程（Development Workflow）

6.1 完整開發流程

sequenceDiagram
    participant PM as 專案經理
    participant DEV as 開發人員
    participant Board as Multica Board
    participant Agent as AI Agent
    participant GH as GitHub
    participant CI as CI/CD

    PM->>Board: 建立 Issue<br/>(描述需求 + 驗收條件)
    PM->>Board: 指派給 Agent

    Board->>Agent: 自動分派任務
    Agent->>Agent: 分析需求
    Agent->>Agent: 撰寫程式碼
    Agent->>Agent: 執行測試
    Agent->>GH: git push + 建立 PR
    Agent->>Board: 狀態更新：in_review

    GH->>CI: 觸發 CI Pipeline
    CI->>CI: Build + Test + Scan
    CI-->>GH: 回報結果

    DEV->>GH: Code Review
    DEV->>GH: Approve + Merge
    GH->>CI: 觸發 Deploy
    DEV->>Board: 狀態更新：done

6.2 Issue 管理

# 建立 Issue
multica issue create \
  --title "實作使用者登入 API" \
  --description "使用 Spring Security + JWT 實作登入端點..." \
  --priority high \
  --assignee "Claude-Backend"

# 列出 Issue
multica issue list
multica issue list --status in_progress
multica issue list --priority urgent --assignee "Claude-Backend"
multica issue list --limit 20 --output json

# 查看 Issue 詳情
multica issue get <id>

# 更新 Issue
multica issue update <id> --title "新標題" --priority urgent

# 指派 / 取消指派
multica issue assign <id> --to "Claude-Backend"
multica issue assign <id> --unassign

# 變更狀態
multica issue status <id> in_progress

# Issue 評論（支援 Thread）
multica issue comment list <issue-id>
multica issue comment add <issue-id> --content "需要加入 Rate Limiting"
multica issue comment add <issue-id> --parent <comment-id> --content "收到，已處理"
multica issue comment delete <comment-id>

# Issue Metadata
multica issue metadata set <id> --key team --value backend
multica issue metadata get <id>

# Issue 訂閱
multica issue subscriber add <id> --user <user-id>
multica issue subscriber list <id>

6.3 範例：Spring Boot API 開發流程

Step 1：建立 Issue

multica issue create \
  --title "實作 GET /api/v1/users/{id} 端點" \
  --description "$(cat <<'EOF'
## 需求
實作查詢單一使用者的 RESTful API。

## 技術規格
- Framework: Spring Boot 3.x
- Architecture: Clean Architecture
- 驗證: JWT Bearer Token
- Response Format: JSON (UserDTO)

## 驗收條件
1. 回傳正確的 UserDTO（不含密碼欄位）
2. 找不到時回傳 404
3. 未授權時回傳 401
4. 單元測試覆蓋率 > 80%
5. API 文件已更新

## 參考
- Entity: src/main/java/com/example/domain/User.java
- Repository: src/main/java/com/example/repository/UserRepository.java
EOF
)" \
  --priority high \
  --assignee "Claude-Backend"

Step 2：Agent 自動執行

Agent 收到任務後會自動：

1. Clone / Pull 最新程式碼
2. 分析現有程式碼結構
3. 建立以下檔案：
   • UserController.java
   • GetUserUseCase.java
   • UserDTO.java
   • UserNotFoundException.java
   • UserControllerTest.java
4. 執行 mvn test 驗證
5. 提交 PR

Step 3：Review 與合併

# 查看執行結果
multica issue runs <issue-id>
multica issue run-messages <task-id>

6.4 範例：Vue 前端功能開發流程

multica issue create \
  --title "實作使用者個人資料頁面" \
  --description "$(cat <<'EOF'
## 需求
建立使用者個人資料頁面，顯示並編輯個人資訊。

## 技術規格
- Framework: Vue 3 + TypeScript + Composition API
- UI: Tailwind CSS
- State: Pinia
- HTTP: Axios

## 頁面元件
1. UserProfile.vue - 主頁面
2. UserAvatar.vue - 頭像區塊
3. UserInfoForm.vue - 資訊編輯表單

## 路由
- /profile - 個人資料頁
- /profile/edit - 編輯模式

## 驗收條件
1. 元件正確渲染
2. 表單驗證（Email、手機格式）
3. 成功/失敗通知
4. 響應式設計（RWD）
5. 單元測試
EOF
)" \
  --priority normal \
  --assignee "Vue-Builder"

6.5 與 Git Flow 整合

gitGraph
    commit id: "main"
    branch develop
    checkout develop
    commit id: "dev-base"
    branch "feature/user-api"
    checkout "feature/user-api"
    commit id: "Agent: implement user API"
    commit id: "Agent: add tests"
    checkout develop
    merge "feature/user-api"
    branch "feature/user-ui"
    checkout "feature/user-ui"
    commit id: "Agent: implement profile page"
    commit id: "Agent: add RWD support"
    checkout develop
    merge "feature/user-ui"
    checkout main
    merge develop tag: "v1.0.0"

實務建議： 建議使用 Trunk-Based Development 搭配 Feature Flag，Agent 的 PR 直接進入 main 分支。如果團隊使用 Git Flow，確保 Agent 知道該從 develop 分支建立 Feature Branch。

第 7 章：Skill（技能）機制設計

7.1 Skill 概念

Skill 是 Multica 的核心差異化功能：

• 每次 Agent 成功解決問題，其解法會被封裝為可重用的 Skill
• Skill 在整個團隊中共享
• 隨著時間推移，團隊的 Skill Library 不斷壯大
• 新的 Agent 可以直接使用已有的 Skill，無需從頭學習

flowchart LR
    subgraph "Skill 生命週期"
        CREATE[🆕 Agent 解決問題] --> EXTRACT[📦 自動萃取 Skill]
        EXTRACT --> STORE[💾 儲存至 Skill Library]
        STORE --> REUSE[♻️ 其他 Agent 重用]
        REUSE --> IMPROVE[📈 持續優化]
        IMPROVE --> STORE
    end

7.2 Skill 類型

7.3 Skill 定義與儲存

Multica 使用 skills-lock.json 管理 Skill 定義：

{
  "skills": [
    {
      "name": "spring-boot-crud-api",
      "version": "1.0.0",
      "description": "建立 Spring Boot CRUD API（Clean Architecture）",
      "agent": "claude-code",
      "tags": ["spring-boot", "api", "crud"],
      "prompt_template": "...",
      "files_generated": [
        "Controller.java",
        "UseCase.java",
        "Repository.java",
        "DTO.java",
        "Test.java"
      ]
    }
  ]
}

7.4 範例：自動部署 Skill

# Skill: auto-deploy-docker
name: auto-deploy-docker
description: 自動建置 Docker Image 並推送至 Registry
triggers:
  - issue_label: "deploy"
  - branch_pattern: "release/*"
steps:
  1. 檢查 Dockerfile 是否存在
  2. 執行 docker build
  3. 執行安全掃描（Trivy）
  4. 推送至 Container Registry
  5. 更新 K8s Deployment

7.5 範例：Code Review Skill

# Skill: code-review-enterprise
name: code-review-enterprise
description: 企業級 Code Review 檢查
checklist:
  - security: OWASP Top 10 檢查
  - performance: N+1 查詢、記憶體洩漏
  - architecture: Clean Architecture 分層遵循
  - testing: 測試覆蓋率 > 80%
  - naming: 命名規範一致性
  - documentation: Javadoc / JSDoc 完整性
  - error_handling: 例外處理是否完善

7.6 範例：DB Migration Skill

# Skill: db-migration
name: db-migration
description: 資料庫遷移腳本生成與執行
steps:
  1. 分析 Entity 變更
  2. 生成 Flyway/Liquibase Migration 腳本
  3. 本地執行遷移測試
  4. 驗證資料完整性
  5. 生成回滾腳本

7.7 建立企業級 Skill Library

graph TB
    subgraph "Skill Library 架構"
        subgraph "基礎層 (Foundation)"
            S1[CRUD API Generator]
            S2[DTO Mapper]
            S3[Exception Handler]
        end

        subgraph "業務層 (Business)"
            S4[金融交易 API]
            S5[報表生成器]
            S6[批次處理框架]
        end

        subgraph "維運層 (Operations)"
            S7[Docker Deploy]
            S8[DB Migration]
            S9[Log Analyzer]
        end

        subgraph "品質層 (Quality)"
            S10[Code Review]
            S11[Security Scan]
            S12[Performance Test]
        end
    end

    S1 --> S4
    S2 --> S4
    S3 --> S4
    S7 --> S8

實務建議： 初期不要急著建立 Skill Library，讓 Agent 自然累積。經過 2-3 個 Sprint 後，再由資深工程師 Review 並標準化 Skill。定期清理低品質或過時的 Skill。

第 8 章：多工作空間（Workspace）設計

8.1 Workspace 概念

graph TB
    subgraph "企業 Multica 部署"
        subgraph "Workspace: 核心銀行系統"
            A1[Agent: Core-Backend]
            A2[Agent: Core-Frontend]
            I1[Issues & Board]
            SK1[Skill Library]
        end

        subgraph "Workspace: 行動銀行 App"
            A3[Agent: Mobile-API]
            A4[Agent: Mobile-UI]
            I2[Issues & Board]
            SK2[Skill Library]
        end

        subgraph "Workspace: 內部工具平台"
            A5[Agent: Tools-Dev]
            I3[Issues & Board]
            SK3[Skill Library]
        end
    end

每個 Workspace 擁有完全獨立的：

• Agent 配置
• Issue 看板
• Skill Library
• 設定
• 成員權限

8.2 Workspace CLI 管理

# 列出所有工作空間
multica workspace list
# 有 * 標記的為 Daemon 監控中

# 切換工作空間（設定預設 Workspace）
multica workspace switch <workspace-id>

# 監控 / 取消監控工作空間
multica workspace watch <workspace-id>
multica workspace unwatch <workspace-id>

# 查看工作空間詳情
multica workspace get <workspace-id>
multica workspace get <workspace-id> --output json

# 列出成員
multica workspace members <workspace-id>

8.3 團隊隔離策略

8.4 權限控管（RBAC）

8.5 多 Daemon Profile

當需要連接多個 Workspace 或多個 Server 時：

# 建立 staging profile
multica --profile staging login
multica --profile staging daemon start

# 預設 profile 獨立運作
multica daemon start

# 每個 profile 有獨立的：
# ~/.multica/profiles/<name>/config
# ~/.multica/profiles/<name>/daemon.log
# ~/multica_workspaces/<name>/

實務建議： 銀行環境建議按「專案 + 環境」建立 Workspace（如 core-banking-dev、core-banking-staging），並嚴格控管 Production Workspace 的存取權限。使用 DISABLE_WORKSPACE_CREATION=true 可防止未經授權的 Workspace 建立。

8.6 工作空間垃圾回收（Workspace GC）

Daemon 內建自動垃圾回收機制，定期清理已完成任務的工作目錄，避免磁碟空間耗盡：

GC 清理層級：

flowchart TB
    GC[GC 觸發<br/>每 1h 掃描] --> CHECK{檢查工作目錄}
    CHECK -->|Issue 已完成/取消 > 24h| CLEAN1[清除工作目錄]
    CHECK -->|無對應 Issue > 72h| CLEAN2[清除孤立目錄]
    CHECK -->|建置產物 > 12h| CLEAN3[清除 node_modules/.next/.turbo]
    CHECK -->|Issue 仍在進行中| KEEP[保留]

實務建議：

• 磁碟空間有限的 CI/CD Build Server 建議設定較短的 TTL（如 MULTICA_GC_TTL=6h）
• 需要保留執行結果供事後分析的環境，建議延長 TTL（如 MULTICA_GC_TTL=168h）
• 設定 MULTICA_GC_ARTIFACT_TTL=0 可停用建置產物清理（適用於頻繁重建的場景）

第 9 章：Squads（團隊編組）

9.1 Squads 概念

Squads 是 Multica 的團隊編組機制，可將多個 Agent 與人類成員組成小隊，實現智慧任務路由與協作：

flowchart TB
    subgraph "Squad: Backend Team"
        SQ1_LEAD[🧑‍💻 Tech Lead（人類）]
        SQ1_A1[🤖 Claude-API<br/>Claude Code]
        SQ1_A2[🤖 Claude-DB<br/>Claude Code]
        SQ1_A3[🤖 Codex-Test<br/>Codex]
    end

    subgraph "Squad: Frontend Team"
        SQ2_LEAD[🧑‍💻 UI Lead（人類）]
        SQ2_A1[🤖 Vue-Builder<br/>Codex]
        SQ2_A2[🤖 CSS-Expert<br/>Claude Code]
    end

    subgraph "Squad: DevOps Team"
        SQ3_A1[🤖 Infra-Bot<br/>Claude Code]
        SQ3_A2[🤖 CI-Bot<br/>Codex]
    end

    ISSUE[新 Issue] -->|Metadata: team=backend| SQ1_LEAD
    ISSUE -->|Metadata: team=frontend| SQ2_LEAD
    ISSUE -->|Metadata: team=devops| SQ3_A1

9.2 Squad 的價值

9.3 企業應用場景

實務建議： 初期建議從 2-3 個 Squad 開始，一個負責核心業務邏輯、一個負責基礎設施、一個負責品質保證。Squad 的路由規則應搭配 Issue Metadata 使用，實現自動化分配。

第 10 章：Autopilots（自動化排程）

10.1 Autopilots 概念

Autopilots 是 Multica 的排程自動化機制，可依據時間排程或事件觸發，自動建立 Issue 並指派給 Agent 執行：

flowchart LR
    subgraph "觸發器"
        CRON[⏰ Cron 排程<br/>每日/每週]
        EVENT[🔔 事件觸發<br/>Webhook / PR]
        MANUAL[👆 手動觸發]
    end

    subgraph "Autopilot Engine"
        ENGINE[Autopilot<br/>規則引擎]
    end

    subgraph "執行"
        ISSUE_CREATE[自動建立 Issue]
        ASSIGN[指派給 Agent/Squad]
        EXEC[Agent 執行任務]
    end

    CRON --> ENGINE
    EVENT --> ENGINE
    MANUAL --> ENGINE
    ENGINE --> ISSUE_CREATE
    ISSUE_CREATE --> ASSIGN
    ASSIGN --> EXEC

10.2 Autopilot CLI 管理

# 列出所有 Autopilots
multica autopilot list

# 查看 Autopilot 詳情
multica autopilot get <id>

# 建立 Autopilot
multica autopilot create \
  --name "Daily Security Scan" \
  --schedule "0 2 * * *" \
  --action "建立 Issue: 執行每日安全掃描報告"

# 啟用 / 停用
multica autopilot enable <id>
multica autopilot disable <id>

# 更新
multica autopilot update <id> --schedule "0 6 * * 1"

# 刪除
multica autopilot delete <id>

10.3 企業應用範例

實務建議： Autopilot 特別適合重複性高但需要 Agent 智慧判斷的任務（如安全掃描結果分析、程式碼品質報告解讀）。純機械式操作（如備份）建議使用傳統 cron，將 Autopilot 留給需要 AI 分析能力的場景。

第 11 章：Projects（專案管理）

11.1 Projects 概念

Projects 提供群組式 Issue 管理，類似 Sprint 或 Epic 的概念，可將多個相關 Issue 組織在同一 Project 下追蹤進度：

graph TB
    subgraph "Project: 用戶管理模組 v2.0"
        P_META[📋 Project Metadata<br/>開始: 2026-06-01<br/>結束: 2026-06-30]
        I1[Issue: 用戶 API CRUD]
        I2[Issue: 用戶前端頁面]
        I3[Issue: 權限管理 API]
        I4[Issue: 單元測試補充]
        I5[Issue: E2E 測試]
        I6[Issue: API 文件更新]
    end

    I1 -->|依賴| I2
    I1 -->|依賴| I3
    I1 --> I4
    I2 --> I5
    I3 --> I4
    I4 --> I6
    I5 --> I6

11.2 Project CLI 管理

# 列出 Projects
multica project list

# 建立 Project
multica project create \
  --name "用戶管理模組 v2.0" \
  --description "完整重構用戶管理模組，支援 RBAC 與 SSO"

# 查看 Project 詳情
multica project get <id>

# 更新 Project
multica project update <id> --name "用戶管理模組 v2.1"

# 刪除 Project
multica project delete <id>

11.3 Project 與 Issue 整合

# 建立 Issue 時指定 Project
multica issue create \
  --title "實作用戶 CRUD API" \
  --project <project-id> \
  --priority high \
  --assignee "Claude-Backend"

# 將既有 Issue 加入 Project
multica issue update <id> --project <project-id>

11.4 企業應用場景

實務建議： 搭配 Metadata 使用可實現更精細的追蹤。例如為 Project 中的 Issue 設定 sprint=2026-S12 Metadata，再透過 Squad 路由規則自動分配。

第 12 章：MCP 整合（Model Context Protocol）

12.1 MCP 概述

Multica 支援作為 MCP（Model Context Protocol）Provider，允許外部 AI 工具與 IDE 透過標準化協議與 Multica 平台互動。這使得其他 AI Agent 或工具能直接查詢 Issue、觸發任務、讀取 Skill 等，無需自行實作 Multica API 整合。

flowchart LR
    subgraph "MCP Clients"
        IDE[VS Code / Cursor]
        CLI_EXT[外部 CLI 工具]
        AGENT_EXT[第三方 AI Agent]
    end

    subgraph "Multica MCP Provider"
        MCP_SERVER[MCP Server]
        API[Multica API]
    end

    subgraph "Multica Platform"
        ISSUES[Issues]
        SKILLS[Skills]
        AGENTS[Agents]
        PROJECTS[Projects]
    end

    IDE -->|MCP Protocol| MCP_SERVER
    CLI_EXT -->|MCP Protocol| MCP_SERVER
    AGENT_EXT -->|MCP Protocol| MCP_SERVER

    MCP_SERVER --> API
    API --> ISSUES
    API --> SKILLS
    API --> AGENTS
    API --> PROJECTS

12.2 MCP 整合場景

實務建議： MCP 整合特別適合已有多種 AI 工具的企業環境。透過統一的 MCP 協議，可避免為每個工具維護獨立的 API 整合。

第 13 章：系統維運（Operations）

13.1 Log 管理

Daemon Log

# 查看最近 50 行日誌
multica daemon logs

# 即時跟蹤（tail -f）
multica daemon logs -f

# 查看最近 100 行
multica daemon logs -n 100

# 日誌檔案位置
# ~/.multica/daemon.log
# Profile 模式：~/.multica/profiles/<name>/daemon.log

Server Log

# Docker Compose 日誌
docker compose -f docker-compose.selfhost.yml logs -f

# 只看後端日誌
docker compose -f docker-compose.selfhost.yml logs -f backend

# 設定日誌等級（.env）
LOG_LEVEL=debug  # debug, info, warn, error

13.2 Agent 狀態監控

# 查看 Daemon 狀態
multica daemon status
# 輸出：
# Status:     running
# PID:        12345
# Uptime:     3d 2h 15m
# Agents:     claude (v1.5.0), codex (v0.3.0)
# Workspaces: 3 watched
# Tasks:      2 running, 0 queued

# JSON 格式（適合自動化監控）
multica daemon status --output json

Health Check

# Server Health Check（Liveness）
curl http://localhost:8080/healthz
# 回傳：{"status":"ok","checks":{"db":"ok","migrations":"ok"}}

# Readiness Check（含 DB 連線狀態）
curl http://localhost:8080/readyz
# 回傳：{"status":"ok","checks":{"db":"ok","migrations":"ok","redis":"ok"}}

# 適合 Load Balancer 、Kubernetes Liveness/Readiness Probe 或 Prometheus 監控

Prometheus Metrics

當設定環境變數 METRICS_ADDR（例：:9090）時，後端會在該埠暴露 Prometheus 格式的 metrics：

# 啟用 metrics
export METRICS_ADDR=:9090

# 驗證 metrics 端點
curl http://localhost:9090/metrics

主要暴露指標：

Grafana Dashboard 範例：

# 使用社群 Dashboard（ID: 待社群發布）
# 或自建 Dashboard，推薦 Panel：
# - HTTP 請求 QPS 與 p99 延遲
# - 活躍 WebSocket 連線數
# - 任務執行狀態分佈
# - Daemon 心跳健康度
# - DB 連線池使用率

13.3 監控架構

graph LR
    subgraph "Multica"
        SERVER[Go Backend]
        DAEMON[Agent Daemon]
    end

    subgraph "監控系統"
        PROM[Prometheus]
        GRAF[Grafana]
        ALERT[AlertManager]
    end

    subgraph "日誌系統"
        FLUENTD[Fluentd]
        ES[Elasticsearch]
        KIBANA[Kibana]
    end

    SERVER -->|/health + metrics| PROM
    DAEMON -->|daemon.log| FLUENTD
    SERVER -->|application.log| FLUENTD

    PROM --> GRAF
    PROM --> ALERT
    FLUENTD --> ES
    ES --> KIBANA

13.4 建議監控指標

13.5 錯誤處理與復原

常見錯誤處理

災難復原

# 停止所有服務（使用 make）
multica daemon stop
make selfhost-stop

# 或手動停止
multica daemon stop
docker compose -f docker-compose.selfhost.yml down

# 備份資料庫
docker compose -f docker-compose.selfhost.yml exec postgres pg_dump -U multica multica > backup.sql

# 重新啟動
make selfhost
multica daemon start

# 或手動重啟
docker compose -f docker-compose.selfhost.yml up -d
multica daemon start

# 還原資料庫（如需要）
cat backup.sql | docker compose -f docker-compose.selfhost.yml exec -T postgres psql -U multica multica

注意： docker compose down 僅停止容器並移除容器，但保留資料庫卷宗。使用 docker compose down -v 會同時刪除卷宗，此操作不可逆。

13.6 效能優化

實務建議： 建議每週進行一次 DB 備份，每月進行一次完整的災難復原演練。Agent 日誌建議保留 30 天，超過的自動歸檔至 Object Storage。

第 14 章：系統升級與擴展（Upgrade & Scaling）

14.1 Multica 升級策略

CLI 升級

# 自動升級（偵測安裝方式：Homebrew 或手動）
multica update

# Homebrew 升級
brew upgrade multica

Server 升級（Docker Compose）

# 1. Pull 最新程式碼
cd multica
git pull

# 2. 重建並重啟（推薦，使用 make）
make selfhost
# 自動從 GHCR 拉取最新穩定映像
# 若指定 Tag 尚未發布，會提示改用 make selfhost-build

# 或手動拉取映像重啟
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

# Migration 是冪等的，重複執行不會有副作用
# Migration 在 Backend 啟動時自動執行

Server 升級（Kubernetes / Helm）

# 升級到特定版本
helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \
  --version <chart-version> \
  -n multica \
  -f my-values.yaml

# 查看升級歷史
helm -n multica history multica

# 回滾至上一版本
helm -n multica rollback multica

# 回滾至指定版本
helm -n multica rollback multica <revision>

# 監控升級後的 Pod 狀態
kubectl -n multica get pods -w

# 驗證 Health Check
curl -H "Host: api.multica.dev.lan" http://<ingress-ip>/healthz

注意： Helm Chart Version 去掉 Git Tag 的前綴 v（例如 v0.3.5 → 0.3.5）。升級前建議先用 helm diff Plugin 比對變更。

14.2 版本管理策略

flowchart TD
    A[監控 GitHub Releases] --> B{是否為重大版本？}
    B -->|是| C[在 Staging 環境測試]
    B -->|否| D[直接在 Dev 環境升級]
    C --> E[執行回歸測試]
    D --> E
    E --> F{測試通過？}
    F -->|是| G[排程 Production 升級]
    F -->|否| H[回報 Issue / 等待修復]
    G --> I[執行升級]
    I --> J[驗證 Health Check]
    J --> K[監控 24 小時]

14.3 Agent 水平擴展

graph TB
    subgraph "Multica Server (單一)"
        SERVER[Go Backend + PostgreSQL]
    end

    subgraph "Agent Daemon 叢集"
        D1[Daemon #1<br/>Dev Machine A<br/>Claude Code x2]
        D2[Daemon #2<br/>Dev Machine B<br/>Codex x2]
        D3[Daemon #3<br/>Build Server<br/>Claude Code x4]
        D4[Daemon #4<br/>Cloud VM<br/>All Agents]
    end

    SERVER <-->|WebSocket| D1
    SERVER <-->|WebSocket| D2
    SERVER <-->|WebSocket| D3
    SERVER <-->|WebSocket| D4

擴展方式：

1. 增加 Daemon 數量： 在更多機器上安裝 Daemon
2. 增加 Agent 數量： 每個 Daemon 可以執行多個 Agent
3. 調整併行數： 增加 MULTICA_DAEMON_MAX_CONCURRENT_TASKS
4. 專屬 Build Server： 在高規格機器上部署專用 Daemon

14.4 高可用架構（HA）

graph TB
    subgraph "Load Balancer"
        LB[Nginx / HAProxy]
    end

    subgraph "Application Layer"
        WEB1[Frontend #1]
        WEB2[Frontend #2]
        API1[Backend #1]
        API2[Backend #2]
    end

    subgraph "Database Layer"
        PG_PRIMARY[(PostgreSQL Primary)]
        PG_REPLICA[(PostgreSQL Replica)]
    end

    subgraph "Agent Layer"
        D1[Daemon #1]
        D2[Daemon #2]
        D3[Daemon #3]
    end

    LB --> WEB1
    LB --> WEB2
    LB --> API1
    LB --> API2

    API1 --> PG_PRIMARY
    API2 --> PG_PRIMARY
    PG_PRIMARY -->|Streaming Replication| PG_REPLICA

    API1 <--> D1
    API1 <--> D2
    API2 <--> D3

實務建議： 小團隊（< 10 人）單機部署即可。中型團隊（10-50 人）建議分離前後端和資料庫。大型團隊（50+ 人）才需要考慮完整 HA 架構。

14.5 切換至 Multica Cloud

若團隊決定從 Self-Hosted 遷移至 Multica Cloud 託管服務：

# 重新設定 CLI 指向 Cloud
multica config set server_url https://api.multica.ai
multica config set app_url https://multica.ai
multica login

# 或使用安裝腳本（不帶 --with-server 會自動設定 Cloud）
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

遷移注意事項：

實務建議： 建議先在 Cloud 環境中完成基本設定與驗證後，再停止本地 Self-Hosted 服務，以確保無縫切換。

第 15 章：安全設計（Security）

15.1 認證與授權

⚠️ 安全警告： Docker Self-Host 堆疊預設 APP_ENV=production，沒有固定驗證碼。舊版使用的 888888 Master Code 已廢除。切勿在公開可達的實例上設定 MULTICA_DEV_VERIFICATION_CODE。

JWT 安全設定

# 產生強健的 JWT Secret（必須！）
JWT_SECRET=$(openssl rand -hex 32)

# 切勿使用預設值或簡單字串
# 切勿將 JWT_SECRET 提交至版本控制

15.2 Agent 權限隔離

flowchart TB
    subgraph "權限模型"
        WS[Workspace 隔離]
        AGENT[Agent 限定 Workspace]
        RUNTIME[Runtime 隔離執行]
        WORKDIR[隔離工作目錄]
    end

    WS --> AGENT
    AGENT --> RUNTIME
    RUNTIME --> WORKDIR

隔離機制：

1. Workspace Level： Agent 只能存取所屬 Workspace 的 Issue 與 Skill
2. Runtime Level： 每個任務在隔離的工作目錄中執行
3. 工作目錄： ~/multica_workspaces/<workspace>/<task>/
4. CLI 權限： Agent CLI 只能在指定目錄中操作

15.3 憑證管理

# .gitignore 中必須包含
.env
.env.local
.env.worktree
*.pem
*.key

15.4 網路安全

# Production 必須配置
# 1. TLS/SSL（透過反向代理）
# 2. CORS 限制
CORS_ALLOWED_ORIGINS=https://app.example.com

# 3. WebSocket 安全
# Nginx 配置 wss:// 而非 ws://
NEXT_PUBLIC_WS_URL=wss://api.example.com/ws

# 4. Rate Limiting（Nginx 層級）
# 5. Firewall 規則（只開放必要埠號）

15.5 SSDLC 整合

flowchart LR
    REQ[需求分析] --> DESIGN[安全設計]
    DESIGN --> CODE[安全編碼<br/>Agent + Review]
    CODE --> TEST[安全測試<br/>SAST + DAST]
    TEST --> DEPLOY[安全部署<br/>容器掃描]
    DEPLOY --> MONITOR[安全監控<br/>日誌分析]
    MONITOR --> REQ

實務建議： 金融業環境中，Multica Server 必須部署在 DMZ 內網，所有對外連線經過企業 Proxy。Agent 的 API Key（如 Anthropic API Key）不應在 Server 端存放，而是保留在各開發者本機的 Daemon 設定中。

第 16 章：最佳實務（Best Practices）

16.1 團隊導入策略

flowchart LR
    P1[Phase 1<br/>試點<br/>2-3 人] --> P2[Phase 2<br/>擴展<br/>一個團隊]
    P2 --> P3[Phase 3<br/>全面導入<br/>多團隊]
    P3 --> P4[Phase 4<br/>優化<br/>Skill 標準化]

16.2 Prompt Engineering 原則

反面範例（避免）：

❌ "幫我寫一個使用者模組"  → 太模糊
❌ "重構整個後端架構"      → 太大
❌ "修個 Bug"             → 無上下文

16.3 Agent 使用規範

16.4 常見錯誤與避免方式

16.5 開發環境最佳實務

一鍵開發環境

# 使用 make dev 一鍵啟動開發環境
make dev
# 自動完成：
# - 偵測環境（主目錄或 Worktree）
# - 建立 .env / .env.worktree
# - 檢查前置條件（Node.js、pnpm、Go、Docker）
# - 安裝 JavaScript 依賴
# - 確保共用 PostgreSQL 容器運行中
# - 建立應用程式資料庫（若不存在）
# - 執行所有 Migration
# - 啟動前後端服務

開發模式架構

Multica 本地開發使用共享 PostgreSQL 容器 + 資料庫級隔離模型：

# 功能分支開發（Git Worktree）
git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make dev

# 日常指令
make start-worktree    # 啟動
make stop-worktree     # 停止
make check-worktree    # 驗證

Make 指令參考

重要規則

# ⚠️ 重要：主目錄使用 .env，Worktree 使用 .env.worktree
# 切勿將 .env 複製到 Worktree 目錄——會意外指向主資料庫

# 提交前驗證
make check-main       # 主目錄
make check-worktree   # Worktree

# 完全清除（⚠️ 慎用，不可逆）
docker compose down -v  # 刪除所有本地 PostgreSQL 資料

實務建議： 每個 Sprint 結束後安排 15 分鐘 “Agent Retrospective”，回顧 Agent 的表現、改善 Prompt 品質、更新 Skill Library。

第 17 章：實戰案例（Case Study）

17.1 案例：建立企業 Web 系統

系統概要

• 後端： Spring Boot 3.x（Clean Architecture）
• 前端： Vue 3 + TypeScript + Tailwind CSS
• 資料庫： PostgreSQL 17
• CI/CD： GitHub Actions
• Agent 配置： 3 個 Agent

架構圖

graph TB
    subgraph "Multica Board"
        B[Issue Board]
    end

    subgraph "Agent Team"
        AB[🤖 Claude-Backend<br/>Spring Boot API]
        AF[🤖 Vue-Builder<br/>Vue 3 Frontend]
        AR[🤖 Code-Reviewer<br/>Code Review]
    end

    subgraph "開發產出"
        API[Spring Boot API<br/>Clean Architecture]
        UI[Vue 3 SPA<br/>Tailwind CSS]
        DB[(PostgreSQL 17)]
        TEST[Unit + E2E Tests]
    end

    subgraph "CI/CD"
        GHA[GitHub Actions]
        DOCKER[Docker Build]
        DEPLOY[Deploy to Staging]
    end

    B -->|指派| AB
    B -->|指派| AF
    B -->|指派| AR

    AB --> API
    AF --> UI
    AB --> TEST
    AF --> TEST

    API --> DB
    API -->|PR| GHA
    UI -->|PR| GHA
    GHA --> DOCKER
    DOCKER --> DEPLOY

Step 1：設定 Multica 環境

# 安裝 Multica CLI
brew install multica-ai/tap/multica

# 設定（使用 Self-Hosted）
multica setup self-host

# 建立工作空間：enterprise-web-app
# 透過 Web UI: Settings → Workspaces → New

Step 2：建立 Agent 團隊

在 Settings → Agents 中建立：

Step 3：建立 Issue（後端 API）

multica issue create \
  --title "實作用戶管理 CRUD API" \
  --description "$(cat <<'EOF'
## 目標
實作用戶管理的 RESTful API。

## 端點
| Method | Path | 描述 |
|--------|------|------|
| POST | /api/v1/users | 建立用戶 |
| GET | /api/v1/users/{id} | 查詢單一用戶 |
| GET | /api/v1/users | 查詢用戶列表（分頁） |
| PUT | /api/v1/users/{id} | 更新用戶 |
| DELETE | /api/v1/users/{id} | 刪除用戶 |

## 技術要求
- Spring Boot 3.x + Clean Architecture
- Spring Security JWT 認證
- Bean Validation
- PostgreSQL + JPA
- Flyway Migration
- Swagger / OpenAPI 文件

## 驗收條件
1. 所有端點正常運作
2. JWT 認證生效
3. 輸入驗證完整
4. 單元測試覆蓋率 > 80%
5. API 文件已生成
6. Flyway Migration 腳本已建立
EOF
)" \
  --priority high \
  --assignee "Claude-Backend"

Step 4：建立 Issue（前端頁面）

multica issue create \
  --title "實作用戶管理前端頁面" \
  --description "$(cat <<'EOF'
## 目標
建立用戶管理的前端頁面。

## 頁面
1. 用戶列表頁（/users）：表格 + 搜尋 + 分頁
2. 用戶詳情頁（/users/:id）：檢視用戶資訊
3. 新增用戶表單（/users/new）：建立新用戶
4. 編輯用戶表單（/users/:id/edit）：修改用戶資訊

## 技術要求
- Vue 3 + TypeScript + Composition API
- Tailwind CSS
- Pinia State Management
- Vue Router
- Axios HTTP Client
- Vee-Validate 表單驗證

## 驗收條件
1. 所有頁面正確渲染
2. 表單驗證完整
3. 成功/錯誤通知
4. RWD 支援
5. Loading 狀態
6. 元件測試
EOF
)" \
  --priority high \
  --assignee "Vue-Builder"

Step 5：建立 Issue（DB Migration）

multica issue create \
  --title "建立 Users 資料表 Migration" \
  --description "$(cat <<'EOF'
## 目標
建立 PostgreSQL users 資料表的 Flyway Migration。

## Schema
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    name VARCHAR(100) NOT NULL,
    role VARCHAR(20) NOT NULL DEFAULT 'USER',
    status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

## 索引
- email (UNIQUE)
- status
- created_at

## 驗收條件
1. Migration 可成功執行
2. Rollback 腳本可用
3. 測試資料種子（Seed Data）已建立
EOF
)" \
  --priority urgent \
  --assignee "Claude-Backend"

Step 6：監控 Agent 執行

# 查看所有 Issue 執行狀態
multica issue list --status in_progress

# 查看特定 Issue 的執行記錄
multica issue runs <issue-id>

# 即時查看 Agent 輸出
multica issue run-messages <task-id>

# 增量查看（只看最新訊息）
multica issue run-messages <task-id> --since 100

Step 7：Code Review

# 建立 Review Issue
multica issue create \
  --title "Review: 用戶管理 API PR #42" \
  --description "請 Review PR #42 的程式碼品質、安全性、測試覆蓋率" \
  --priority high \
  --assignee "Code-Reviewer"

Step 8：CI/CD 整合

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main, develop]

jobs:
  backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - run: mvn clean verify
      - run: mvn jacoco:report

  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - run: npm run build

17.2 案例總結

實務建議： 第一個專案不要期望 Agent 能完成所有工作。將 Agent 定位為「加速器」而非「替代品」。複雜的架構決策、業務邏輯確認仍需人類工程師主導。

附錄 A：檢查清單（Checklist）

A.1 初次安裝清單

• Docker 與 Docker Compose 已安裝
• 至少一個 AI Agent CLI 已安裝（claude / codex）
• Multica Server 已啟動（docker compose up -d）
• 可存取 Web UI（http://localhost:3000）
• Multica CLI 已安裝（brew install multica-ai/tap/multica）
• 已完成認證（multica login）
• Daemon 已啟動（multica daemon start）
• Daemon 狀態正常（multica daemon status）
• Runtime 在 Web UI 中可見（Settings → Runtimes）

A.2 Production 部署清單

• JWT_SECRET 已更改為強隨機值（openssl rand -hex 32）
• APP_ENV 已設定為 production（停用固定驗證碼）
• Email 認證已設定（Resend API Key 或 SMTP Relay）
• HTTPS/TLS 已設定（反向代理）
• CORS 已正確設定（CORS_ALLOWED_ORIGINS）
• WebSocket 代理已設定（/ws 路由 + proxy_read_timeout 86400）
• 資料庫備份已設定（定期排程）
• DB 連線池參數已調整（DB_POOL_MAX_CONNS）
• Log 集中管理已設定
• Health Check 監控已設定（/healthz + /readyz）
• Prometheus metrics 已啟用（METRICS_ADDR，選用）
• .env 不在版本控制中
• Firewall 規則已設定
• 檔案儲存已設定（S3 或確認使用 Local Fallback）
• Redis 已設定（多節點 HA 時建議，選用）
• 註冊控制已設定（ALLOW_SIGNUP / ALLOWED_EMAIL_DOMAINS）

A.3 Agent 配置清單

• Agent 已在 Web UI 中建立
• Agent 已指定 Runtime 與 Provider
• Agent 命名清楚反映職責
• Agent API Key 已在本機設定（不在 Server 端）
• Agent 測試任務已完成（建立一個測試 Issue 驗證）

A.4 日常維運清單

• Daemon 狀態正常（每日）
• Server Health Check 正常（持續監控）
• 佇列無積壓（每日）
• 無超時或失敗任務（每日）
• 資料庫備份正常（每週）
• Multica 版本更新（每月評估）
• Skill Library Review（每 Sprint）

A.5 安全檢查清單

• JWT Secret 為隨機強密碼（32+ bytes）
• APP_ENV=production 已設定（停用固定驗證碼）
• 所有通訊走 TLS/SSL
• Agent 在隔離工作目錄執行
• 敏感資訊不在 Git 中（.env、.pem、.key）
• RBAC 權限已正確設定
• 定期審計 Agent Operation Log
• Production 環境已停用固定驗證碼（APP_ENV=production，未設定 MULTICA_DEV_VERIFICATION_CODE）
• CORS 僅允許受信任的域名
• WebSocket 使用 WSS（非 WS）
• Agent API Key 保留在本機 Daemon，不在 Server 端存放

附錄 B：CLI 快速參考卡

認證與設定

multica login                            # 瀏覽器認證
multica login --token                    # Token 認證（無頭環境）
multica auth status                      # 檢查認證狀態
multica auth logout                      # 登出
multica config show                      # 顯示設定（路徑、Server URL、App URL）
multica config set server_url <url>      # 設定 Server URL
multica config set app_url <url>         # 設定 App URL
multica config set workspace_id <id>     # 設定預設 Workspace
multica setup                            # 一鍵設定（Cloud）
multica setup self-host                  # 一鍵設定（Self-Hosted）
multica setup self-host --server-url <url> --app-url <url>  # 自訂域名

Daemon 管理

multica daemon start                     # 啟動 Daemon（背景執行）
multica daemon start --foreground        # 前台啟動（除錯用）
multica daemon start --poll-interval 5s  # 自訂輪詢間隔
multica daemon start --max-concurrent-tasks 10  # 自訂併行數
multica daemon start --agent-timeout 4h  # 自訂超時時間
multica daemon start --heartbeat-interval 30s  # 自訂心跳間隔
multica daemon stop                      # 停止 Daemon
multica daemon status                    # 查看狀態（PID、Agent、Workspace）
multica daemon status --output json      # JSON 格式狀態
multica daemon logs                      # 查看日誌（最近 50 行）
multica daemon logs -f                   # 即時跟蹤日誌
multica daemon logs -n 100               # 最近 100 行

Workspace 管理

multica workspace list                   # 列出工作空間
multica workspace switch <id>            # 切換預設工作空間
multica workspace watch <id>             # 監控工作空間
multica workspace unwatch <id>           # 取消監控
multica workspace get <id>               # 查看詳情
multica workspace members <id>           # 列出成員

Issue 管理

multica issue list                       # 列出 Issue
multica issue list --status in_progress  # 依狀態篩選
multica issue list --priority high       # 依優先級篩選
multica issue list --assignee "Name"     # 依指派人篩選
multica issue get <id>                   # 查看詳情
multica issue create --title "..." --description "..." --priority high --assignee "Agent"
multica issue update <id> --title "..."  # 更新
multica issue assign <id> --to "Agent"   # 指派
multica issue assign <id> --unassign     # 取消指派
multica issue status <id> in_progress    # 變更狀態
multica issue runs <id>                  # 執行記錄
multica issue run-messages <task-id>     # 執行訊息
multica issue run-messages <task-id> --since 42  # 增量取得

Issue Metadata

multica issue metadata set <id> --key <key> --value <value>  # 設定 Metadata
multica issue metadata get <id>                               # 查詢所有 Metadata
multica issue metadata get <id> --key <key>                   # 查詢特定 Key
multica issue metadata delete <id> --key <key>                # 刪除 Metadata

Issue 訂閱

multica issue subscriber add <id> --user <user-id>    # 訂閱 Issue
multica issue subscriber remove <id> --user <user-id> # 取消訂閱
multica issue subscriber list <id>                     # 列出訂閱者

Issue 評論（Thread-aware）

multica issue comment list <issue-id>                  # 列出評論
multica issue comment add <issue-id> --content "..."   # 新增評論
multica issue comment add <issue-id> --parent <cid> --content "..."  # 回覆評論（Thread）
multica issue comment delete <comment-id>              # 刪除評論

Projects 管理

multica project list                     # 列出 Projects
multica project get <id>                 # 查看 Project 詳情
multica project create --name "Sprint 2026-S12" --description "..."  # 建立 Project
multica project update <id> --name "..."  # 更新 Project
multica project delete <id>              # 刪除 Project

Autopilots 管理

multica autopilot list                   # 列出 Autopilots
multica autopilot get <id>               # 查看 Autopilot 詳情
multica autopilot create --name "..." --schedule "..." --action "..."  # 建立 Autopilot
multica autopilot update <id>            # 更新 Autopilot
multica autopilot delete <id>            # 刪除 Autopilot
multica autopilot enable <id>            # 啟用 Autopilot
multica autopilot disable <id>           # 停用 Autopilot

其他

multica version                          # 版本資訊（含 commit hash）
multica version --output json            # JSON 格式版本資訊
multica update                           # 更新 CLI（自動偵測 Homebrew 或手動安裝）
multica agent list                       # 列出 Agent
multica --profile staging login          # 使用 Profile
multica --profile staging daemon start   # 以 Profile 啟動 Daemon

輸出格式

大多數指令支援 --output 參數：

multica issue list --output json         # JSON 格式（適合腳本自動化）
multica issue list --output table        # 表格格式（預設）
multica daemon status --output json      # JSON 格式狀態
multica workspace get <id> --output json # JSON 格式 Workspace 詳情

附錄 C：術語表（Glossary）

參考資源

文件維護： 本手冊基於 Multica v0.3.33 撰寫。建議每次 Multica 重大版本更新後，重新 Review 並更新相關章節。
最後更新： 2026-06-30