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

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

目錄

• 第 1 章：Multica 概述
  • 1.1 什麼是 Multica？
  • 1.2 核心設計理念
  • 1.3 與傳統工具的差異比較
  • 1.4 適用場景
  • 1.5 專案基本資訊
  • 1.6 授權模式說明
• 第 2 章：系統架構設計（Enterprise Architecture）
  • 2.1 整體架構概覽
  • 2.2 技術棧詳解
  • 2.3 元件說明
  • 2.4 企業整合架構
  • 2.5 資料流向與通訊模型
• 第 3 章：安裝與部署（Installation & Setup）
  • 3.1 部署模式選擇
  • 3.2 Self-Hosted 快速部署（推薦）
  • 3.3 Self-Hosted 手動部署（Step-by-Step）
  • 3.4 環境變數設定
  • 3.5 Production 部署（反向代理）
  • 3.6 不使用 Docker 的手動部署
  • 3.7 停止服務
  • 3.8 切換至 Multica Cloud
• 第 4 章：核心運作機制（Core Workflow）
  • 4.1 任務生命週期（Issue Lifecycle）
  • 4.2 Agent 自主執行流程
  • 4.3 任務排程與佇列機制
  • 4.4 WebSocket 通訊流程
  • 4.5 Execution History 查詢
• 第 5 章：AI Agent 整合（Claude Code / Codex）
  • 5.1 支援的 AI Agent
  • 5.2 Agent CLI 安裝
  • 5.3 CLI 自動偵測機制
  • 5.4 Agent 建立與設定
  • 5.5 Prompt 設計策略（Agent 專用）
  • 5.6 多 Agent 協作模式
• 第 6 章：開發流程（Development Workflow）
  • 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
• 第 9 章：系統維運（Operations）
  • 9.1 Log 管理
  • 9.2 Agent 狀態監控
  • 9.3 監控架構
  • 9.4 建議監控指標
  • 9.5 錯誤處理與復原
  • 9.6 效能優化
• 第 10 章：系統升級與擴展（Upgrade & Scaling）
  • 10.1 Multica 升級策略
  • 10.2 版本管理策略
  • 10.3 Agent 水平擴展
  • 10.4 高可用架構（HA）
  • 10.5 切換至 Multica Cloud
• 第 11 章：安全設計（Security）
  • 11.1 認證與授權
  • 11.2 Agent 權限隔離
  • 11.3 憑證管理
  • 11.4 網路安全
  • 11.5 SSDLC 整合
• 第 12 章：最佳實務（Best Practices）
  • 12.1 團隊導入策略
  • 12.2 Prompt Engineering 原則
  • 12.3 Agent 使用規範
  • 12.4 常見錯誤與避免方式
  • 12.5 開發環境最佳實務
• 第 13 章：實戰案例（Case Study）
  • 13.1 案例：建立企業 Web 系統
  • 13.2 案例總結
• 附錄 A：檢查清單（Checklist）
• 附錄 B：CLI 快速參考卡
• 附錄 C：術語表（Glossary）

第 1 章：Multica 概述

1.1 什麼是 Multica？

Multica 是一個開源的 AI Agent 管理平台，核心理念是將 AI 編碼代理（如 Claude Code、Codex、OpenClaw、OpenCode）轉化為團隊中的「虛擬同事」。

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

與傳統的 AI 對話工具不同，Multica 提供完整的任務管理 + Agent 自主執行基礎設施：

• Agent 擁有個人檔案，出現在看板上
• Agent 可以被指派 Issue、參與討論、建立任務
• Agent 遇到困難時主動回報 Blocker
• 每個解決方案自動轉化為可重用的「技能（Skill）」

1.2 核心設計理念

1.3 與傳統工具的差異比較

與 AI 工具（Copilot / ChatGPT）差異

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

1.4 適用場景

1.5 專案基本資訊

1.6 授權模式說明

Multica 採用 Multica Source Available License，具體規範如下：

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

實務建議： Multica 適合中大型團隊（5+ 人），且需要有至少一位熟悉 Docker + Go + Node.js 的工程師負責維運。

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

2.1 整體架構概覽

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

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

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

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

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

    subgraph "AI Agent 層"
        CLAUDE[Claude Code]
        CODEX[Codex]
        OPENCLAW[OpenClaw]
        OPENCODE[OpenCode]
    end

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

    DEV --> WEB
    PM --> WEB
    ADMIN --> WEB

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

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

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

    DAEMON1 --> CLAUDE
    DAEMON1 --> CODEX
    DAEMON2 --> OPENCLAW
    CLOUD_RT --> OPENCODE

    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）
• WebSocket Server： 即時雙向通訊，任務狀態串流
• sqlc： 編譯期 SQL Type Safety（非 ORM）
• Migration Engine： 資料庫遷移自動執行
• Health Check： GET /health → {"status":"ok"}

2.3.2 Agent Daemon

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

1. 啟動時自動偵測已安裝的 AI Agent CLI（claude、codex、openclaw、opencode）
2. 向 Server 註冊 Runtime
3. 定期輪詢（預設 3 秒）Server 是否有新任務
4. 收到任務後建立隔離的工作目錄，啟動 Agent CLI 執行
5. 透過 WebSocket 即時回傳執行結果
6. 定期發送心跳（預設 15 秒）
7. 關閉時自動取消註冊所有 Runtime

2.3.3 Web UI Dashboard

• 看板視圖（Board View）：Kanban 式任務管理
• Agent 檔案：每個 Agent 都有個人頁面
• Runtime 管理：查看所有連接的運行環境
• Skill Library：瀏覽與管理可重用技能
• 即時串流：WebSocket 即時顯示 Agent 執行進度

2.3.4 AI Agent 支援

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 "監控"
        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

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

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 快速部署（推薦）

前置條件

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

一鍵安裝

# 一鍵安裝：自動 clone repo、啟動 Docker Compose、安裝 CLI
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local

完成後：

• Frontend： http://localhost:3000
• Backend API： http://localhost:8080
• 登入驗證碼（非 Production）：888888

# 安裝完成後
multica login          # 開啟瀏覽器認證
multica daemon start   # 啟動本地 Agent Runtime

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

Step 1：啟動 Server

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

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

或手動操作：

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

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

# 啟動服務
docker compose -f docker-compose.selfhost.yml up -d

Step 2：登入系統

1. 開啟 http://localhost:3000
2. 輸入 Email
3. 驗證碼輸入 888888（非 Production 環境）

Step 3：安裝 CLI 與啟動 Daemon

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

# 或從源碼編譯
git clone https://github.com/multica-ai/multica.git
cd multica
make build
cp server/bin/multica /usr/local/bin/multica

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

# 自訂埠號（當預設埠號被佔用時）
multica setup --local --port 9090 --frontend-port 4000

# 或手動步驟
multica config local                # 設定連線至本地 Server
multica config local --port 9090 --frontend-port 4000  # 自訂埠號
multica login                       # 認證（開啟瀏覽器）
multica daemon start                # 啟動 Daemon

Step 4：驗證

# 檢查 Daemon 狀態
multica daemon status

# JSON 輸出
multica daemon status --output json

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

3.4 環境變數設定

Server 端必要變數

Email 認證（Production 必要）

Google OAuth（選用）

檔案儲存（選用）

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

Daemon 端設定

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

3.5 Production 部署（反向代理）

Caddy（推薦）

app.example.com {
    reverse_proxy localhost:3000
}

api.example.com {
    reverse_proxy localhost:8080
}

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.6 不使用 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 部署，以確保環境一致性。將 .env 存放在安全的 Secret Manager（如 HashiCorp Vault）中，不要提交至版本控制。

3.7 停止服務

使用安裝腳本停止

# 透過安裝腳本停止所有服務
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.8 切換至 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

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

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

第 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
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
• 超時機制： 預設 2 小時（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

實務建議： 在企業環境中，建議將 MULTICA_DAEMON_POLL_INTERVAL 設為 5s（降低 Server 負載），MULTICA_DAEMON_MAX_CONCURRENT_TASKS 根據機器資源設定（每個 Agent 約需 2-4GB RAM）。

第 5 章：AI Agent 整合（Claude Code / Codex）

5.1 支援的 AI Agent

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

注意： 根據 CLI and Daemon Guide，Claude Code 與 Codex 是核心支援的 Agent，提供完整的 CLI 路徑覆寫與模型覆寫功能。OpenClaw 與 OpenCode 為相容性支援，由社群維護。至少需安裝其中一個 Agent CLI 才能啟動 Daemon。

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

5.3 CLI 自動偵測機制

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

# 啟動 Daemon（自動偵測）
multica daemon start

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

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

自訂 CLI 路徑（當 Agent 不在 PATH 中時）：

# 環境變數設定
export MULTICA_CLAUDE_PATH=/opt/tools/claude
export MULTICA_CODEX_PATH=/opt/tools/codex

# 模型覆寫
export MULTICA_CLAUDE_MODEL=claude-sonnet-4-20250514
export MULTICA_CODEX_MODEL=o3-mini

# 也可透過 Daemon Flag 設定
multica daemon start --poll-interval 5s --heartbeat-interval 30s --agent-timeout 4h

Daemon 運作原理：

1. 啟動時偵測已安裝的 Agent CLI，為每個 Agent 在每個監控中的 Workspace 註冊 Runtime
2. 以設定的間隔（預設 3s）輪詢 Server 是否有已認領（claimed）的任務
3. 收到任務後，建立隔離的工作目錄，啟動 Agent CLI，串流結果回傳
4. 定期發送心跳（預設 15s），讓 Server 知道 Daemon 仍然存活
5. 關閉時自動取消註冊所有 Runtime

5.4 Agent 建立與設定

Web UI 方式

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

CLI 方式

# 查看現有 Agent
multica agent list

5.5 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.6 多 Agent 協作模式

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

    subgraph "Agent Team"
        A1[🤖 Claude-Backend
Claude Code]
        A2[🤖 Vue-Builder
Codex]
        A3[🤖 DB-Admin
Claude Code]
        A4[🤖 Reviewer
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
(描述需求 + 驗收條件)
    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 評論
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>

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 監控中

# 監控 / 取消監控工作空間
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 的存取權限。

第 9 章：系統維運（Operations）

9.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

9.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
curl http://localhost:8080/health
# 回傳：{"status":"ok"}

# 適合 Load Balancer 或 Prometheus 監控

9.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

9.4 建議監控指標

9.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 會同時刪除卷宗，此操作不可逆。

9.6 效能優化

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

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

10.1 Multica 升級策略

CLI 升級

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

# Homebrew 升級
brew upgrade multica

Server 升級

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

# 2. 重建並重啟（推薦，使用 make）
make selfhost

# 或手動重建
docker compose -f docker-compose.selfhost.yml up -d --build

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

10.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 小時]

10.3 Agent 水平擴展

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

    subgraph "Agent Daemon 叢集"
        D1[Daemon #1
Dev Machine A
Claude Code x2]
        D2[Daemon #2
Dev Machine B
Codex x2]
        D3[Daemon #3
Build Server
Claude Code x4]
        D4[Daemon #4
Cloud VM
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

10.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 架構。

10.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

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

遷移注意事項：

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

第 11 章：安全設計（Security）

11.1 認證與授權

JWT 安全設定

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

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

11.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 只能在指定目錄中操作

11.3 憑證管理

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

11.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 規則（只開放必要埠號）

11.5 SSDLC 整合

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

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

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

12.1 團隊導入策略

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

12.2 Prompt Engineering 原則

反面範例（避免）：

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

12.3 Agent 使用規範

12.4 常見錯誤與避免方式

12.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。

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

13.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
Spring Boot API]
        AF[🤖 Vue-Builder
Vue 3 Frontend]
        AR[🤖 Code-Reviewer
Code Review]
    end

    subgraph "開發產出"
        API[Spring Boot API
Clean Architecture]
        UI[Vue 3 SPA
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 --local

# 建立工作空間：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

13.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（停用 Master Code 888888）
• Email 認證已設定（Resend API Key）
• HTTPS/TLS 已設定（反向代理）
• CORS 已正確設定（CORS_ALLOWED_ORIGINS）
• WebSocket 代理已設定（/ws 路由 + proxy_read_timeout 86400）
• 資料庫備份已設定（定期排程）
• Log 集中管理已設定
• Health Check 監控已設定（/health）
• .env 不在版本控制中
• Firewall 規則已設定
• 檔案儲存已設定（S3 或確認使用 Local Fallback）

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 已設定（停用 Master Code）
• 所有通訊走 TLS/SSL
• Agent 在隔離工作目錄執行
• 敏感資訊不在 Git 中（.env、.pem、.key）
• RBAC 權限已正確設定
• 定期審計 Agent Operation Log
• Production 環境已關閉 Master Code（APP_ENV=production）
• 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 local                     # 設定連線至本地 Server（預設埠號）
multica config local --port 9090 --frontend-port 4000  # 自訂埠號
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 --local                    # 一鍵設定（Self-Hosted）
multica setup --local --port 9090 --frontend-port 4000  # 自訂埠號設定

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 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 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.1.26 撰寫。建議每次 Multica 重大版本更新後，重新 Review 並更新相關章節。
最後更新： 2026-04-12