參與開發

Multica 是 Go backend 與 pnpm monorepo。最簡單的本地啟動方式是 make dev；它會為當前 checkout 準備環境、資料庫和 migration，再啟動 Web 與 API。

環境要求Copy Anchor Link

• Node.js 22；
• pnpm 10.28.2；
• Go 1.26.6；
• Docker Engine 或 Docker Desktop；
• Git 和 Make。

版本以根目錄 package.json、server/go.mod 和 CI workflow 為準。

第一次啟動Copy Anchor Link

git clone https://github.com/multica-ai/multica.git
cd multica
make dev

主 checkout 會使用 .env。檔案不存在時，make dev 會從 .env.example 建立；然後啟動共享 PostgreSQL、安裝依賴、執行 migration，並執行 API 與 Web。

預設地址：

Web: http://localhost:3000
API: http://localhost:8080

本地固定驗證碼來自開發環境配置。不要把本地 .env 用到公網部署。

在 worktree 中開發Copy Anchor Link

倉庫支援主 checkout 和多個 worktree 同時執行。它們共用一個 PostgreSQL 容器，但使用不同資料庫和連接埠。

git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make setup-worktree
make start-worktree

make setup-worktree 會生成 .env.worktree，資料庫名和連接埠根據路徑確定。再次啟動：

make start-worktree

停止當前 worktree 的 Web 與 API：

make stop-worktree

也可以直接執行 make dev，腳本會透過 .git 檔案識別 worktree 並選擇 .env.worktree。

常用命令Copy Anchor Link

整體流程Copy Anchor Link

make dev # 準備並啟動當前 checkout
make start # 使用已有環境啟動 API 與 Web
make stop # 停止當前 checkout 的程序
make check # 完整本地驗證流程
make build # 建構 server、CLI 和 migrate 二進位檔

前端Copy Anchor Link

pnpm install
pnpm dev:web
pnpm dev:desktop
pnpm build
pnpm typecheck
pnpm lint
pnpm test

根命令預設排除 Mobile。移動端有獨立腳本和 CI，修改前先閱讀 apps/mobile/AGENTS.md。

BackendCopy Anchor Link

make server
make daemon
make test
make migrate-up
make migrate-down
make sqlc

從源碼執行某條 CLI 命令：

make cli ARGS="issue list"

修改前端功能Copy Anchor Link

Web 與 Desktop 都需要的功能按職責放置：

1. API 類型、query、mutation 和平臺無關邏輯放在 packages/core/；
2. 基礎 UI 放在 packages/ui/，不能依賴業務程式碼；
3. 業務頁面和元件放在 packages/views/；
4. Next.js、Electron 和路由適配留在對應 app；
5. 共享頁面需要同時接入 Web 與 Desktop。

服務端資料由 TanStack Query 管理，篩選、草稿和佈局等客戶端狀態由 Zustand 管理。具體邊界見專案架構和根目錄 AGENTS.md。

新增或修改 API 時，要同步更新 packages/core/api/ 中的 zod schema，併為缺失欄位、未知枚舉或格式錯誤增加解析測試。

修改資料庫Copy Anchor Link

Migration 位於 server/migrations/，查詢位於 server/pkg/db/queries/。

1. 使用下一個未佔用的數字前綴，同時建立 .up.sql 和 .down.sql；
2. 不新增資料庫 foreign key、級聯刪除或級聯更新；關係檢查和清理由應用層完成；
3. 每個新索引都使用 CREATE INDEX CONCURRENTLY 或 CREATE UNIQUE INDEX CONCURRENTLY；
4. 一個 concurrent index 單獨放在只包含這一條語句的 migration 檔案中；
5. 修改查詢後執行 make sqlc，提交生成的 server/pkg/db/generated/ 變化；
6. 不直接編輯 sqlc 產生的檔案。

需要讓多項寫操作一起成功或回滾時，在 service 層使用應用事務。

測試位置Copy Anchor Link

先執行與改動最接近的檢查，再擴大範圍。例如只改 Docs：

pnpm --filter @multica/docs typecheck

共享前端改動：

pnpm typecheck
pnpm test

Backend 改動：

make test

提交前執行：

make check

make check 會執行 TypeScript typecheck 與單元測試、Go 測試和 Playwright E2E。CI 還會按改動範圍構建、lint，並執行平臺或安裝器專項測試。

重置當前開發資料庫Copy Anchor Link

需要乾淨資料時，可以重置當前 checkout 在環境檔案中指定的資料庫：

make stop
make db-reset
make start

make db-reset 會刪除並重建當前 POSTGRES_DB，且會拒絕連接遠程資料庫。操作前檢查 .env 或 .env.worktree，確認目標資料庫正確。

提交前檢查Copy Anchor Link

• 閱讀根目錄 AGENTS.md 和相關子目錄說明；
• 只修改當前 task 需要的範圍；
• 程式碼註釋使用英文；
• 不提交 .env、令牌、構建產物或本機路徑；
• 使用 feat(scope)、fix(scope)、docs 等 conventional commit；
• 在 PR 中寫清行為變化和實際執行的驗證命令。

接下來Copy Anchor Link

• 開發規範 — 命名、術語和中文文案的倉庫契約。
• 專案架構 — 分層、共享包和一次執行的程式碼路徑。