slug: mozi name: mozi displayName: Mozi 模型驅動開發 version: 0.2.1 description: 使用 mozi CLI 進行模型驅動開發。當需要建立或修改業務模型、校驗或 lint ModelIR、檢查差異與 AI 變更計劃、管理錯誤碼或設計字典、匯入匯出 YAML 快照，以及生成受控的資料庫遷移、Bruno 合約、許可權骨架、i18n 目錄或 OpenAPI TypeScript SDK 時使用。

Mozi 模型驅動開發

通過 CLI 完成建模、校驗、變更分析、程式碼修改和契約產物生成。不要要求使用者切換到瀏覽器完成 Agent 可通過 CLI 完成的操作。

事實來源

• 將 PostgreSQL 設計資料庫視為模型定義的主儲存。
• 將 models/ YAML 視為 Git 快照和交換格式，不要預設把它當作日常編輯源。
• 使用 mozi model get/create/update 修改模型；不要直接寫設計資料庫，也不要用 HTTP 請求替代 CLI。
• 將 ModelIR 用於領域語義、資料結構和產品意圖，不要只描述資料庫表。
• 將 ProjectIR 錯誤碼登錄檔作為錯誤碼事實來源；模型 API 意圖只引用已註冊錯誤碼。
• 將生成的 docs/swagger.json 作為 HTTP 契約事實來源。Bruno 合約和 TypeScript SDK 必須從 OpenAPI 生成。
• 將 API Workbench 中的端點歸屬等資訊視為展示性維護資料，不要用它修改 HTTP 方法、路徑或 Schema。
• 將遷移、合約、許可權、翻譯目錄和 SDK 視為待審查產物；“成功生成”不代表“獲准執行”。
• 使用宿主應用的 make dev 啟動 Builder UI；Mozi 不提供獨立 HTTP 服務命令。

建模必答項

每個模型必須覆蓋以下五類問題。缺少資訊時先詢問，不要猜測後直接儲存。

關係規則

7w4.net小蔥技能。

每個 relations[] 必須包含業務謂詞 label。不要把 name、back_ref 或 ORM 型別當作業務謂詞。

常用關係表達：

從當前模型視角使用主動謂詞，並檢查反向關係能否講述一致的業務故事。例如：Deck 包含 Card，Card 歸屬 Deck。

欄位重新命名規則

欄位重新命名時設定 fields[].renamed_from。不要把重新命名表達成未標註的“刪除舊欄位＋新增欄位”；後者會被判定為破壞性變更。即使顯式標註重新命名，也必須人工審查條件型遷移。

結構化許可權規則

優先使用 semantics.permission_rules，保留 semantics.permissions 僅用於舊模型相容和自然語言補充。

permission_rules:
  - effect: allow
    principal: user
    resource: deck
    action: update
    scope: own
    owner_field: user_id

• 使用 deny-first、fail-closed 語義。
• own 必須提供 owner_field；tenant 必須提供 tenant_field。
• 只把前端許可權判斷用於介面展示；真正授權必須在服務端執行。
• 對生成器不支援的複雜 condition，保留在應用策略程式碼中，不要自動放寬。

錯誤碼與測試合約

先註冊錯誤碼，再從 api_intent.error_codes 或 test_contracts.expect.error_code 引用。

mozi error-code upsert DECK_NOT_FOUND \
  --domain content --status 404 --category resource \
  --message '牌組不存在' --consumer-facing

測試合約必須引用穩定的 OpenAPI operation_id：

test_contracts:
  - name: get_deck_not_found
    operation_id: getDeck
    request:
      path: { id: missing-id }
    expect:
      status: 404
      error_code: DECK_NOT_FOUND

安裝 Mozi CLI

先檢查本機是否已有執行檔：

command -v mozi && mozi --version

版本一致性檢查（必須執行）

每次開始使用本 Skill 時，讀取 frontmatter 中的 version，並與 mozi --version 輸出的版本號比較。

• 版本一致：繼續執行任務。
• CLI 未安裝：按下方平臺說明引導安裝。
• CLI 版本低於或不同於 Skill 版本：先明確提醒使用者升級 Mozi CLI，並提供 GitHub Releases 安裝方式。
• 未完成升級前，不要呼叫當前 CLI 可能尚未支援的新命令或新欄位；可以繼續執行與舊版本明確相容的只讀檢查。
• 升級後再次執行 mozi --version，確認與 Skill 版本一致，再繼續寫操作。

提醒示例：

當前 Mozi Skill 版本為 0.2.1，本機 CLI 版本為 <實際版本>，兩者不一致。建議先從 GitHub Releases 升級 CLI；升級並確認版本一致後再繼續模型寫入或產物生成。

未安裝時，從 GitHub Releases 下載當前平臺產物。不要從不明映象下載，也不要跳過校驗和檢查。

macOS / Linux

釋出產物支援 darwin、linux 的 amd64、arm64。使用以下命令自動識別平臺並安裝到使用者目錄：

set -euo pipefail
case "$(uname -s)" in
  Darwin) os=darwin ;;
  Linux) os=linux ;;
  *) echo "不支援的系統: $(uname -s)" >&2; exit 1 ;;
esac
case "$(uname -m)" in
  x86_64|amd64) arch=amd64 ;;
  arm64|aarch64) arch=arm64 ;;
  *) echo "不支援的架構: $(uname -m)" >&2; exit 1 ;;
esac
asset="mozi_${os}_${arch}.tar.gz"
base="https://github.com/pangu-studio/mozi-builder/releases/latest/download"
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
curl -fL "$base/$asset" -o "$tmp/$asset"
curl -fL "$base/checksums.txt" -o "$tmp/checksums.txt"
expected="$(awk -v file="$asset" '$2 == file {print $1}' "$tmp/checksums.txt")"
actual="$(shasum -a 256 "$tmp/$asset" | awk '{print $1}')"
test -n "$expected" && test "$actual" = "$expected"
tar -xzf "$tmp/$asset" -C "$tmp"
mkdir -p "$HOME/.local/bin"
install -m 0755 "$tmp/mozi_${os}_${arch}/mozi" "$HOME/.local/bin/mozi"
"$HOME/.local/bin/mozi" --version

確保 $HOME/.local/bin 已加入 PATH。沒有 curl 或無法訪問 GitHub 時，停止並讓使用者手動提供可信的 Release 產物；不要自行改用第三方下載站。

Windows PowerShell

$arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'amd64' }
$asset = "mozi_windows_${arch}.zip"
$base = 'https://github.com/pangu-studio/mozi-builder/releases/latest/download'
$tmp = Join-Path $env:TEMP "mozi-install-$PID"
New-Item -ItemType Directory -Force $tmp | Out-Null
Invoke-WebRequest "$base/$asset" -OutFile (Join-Path $tmp $asset)
Invoke-WebRequest "$base/checksums.txt" -OutFile (Join-Path $tmp 'checksums.txt')
$expected = ((Get-Content (Join-Path $tmp 'checksums.txt') | Where-Object { $_ -match "\s$([regex]::Escape($asset))$" }) -split '\s+')[0]
$actual = (Get-FileHash (Join-Path $tmp $asset) -Algorithm SHA256).Hash.ToLower()
if (-not $expected -or $actual -ne $expected.ToLower()) { throw 'Mozi CLI 校驗和不匹配' }
Expand-Archive (Join-Path $tmp $asset) -DestinationPath $tmp -Force
$bin = Join-Path $HOME 'bin'
New-Item -ItemType Directory -Force $bin | Out-Null
Copy-Item (Join-Path $tmp "mozi_windows_${arch}\mozi.exe") (Join-Path $bin 'mozi.exe') -Force
& (Join-Path $bin 'mozi.exe') --version

將 $HOME\bin 加入使用者 PATH。安裝後始終執行 mozi --version，確認 CLI 可執行且版本符合預期。

環境

export MOZI_DB='postgres://localhost:5432/memflow_design?sslmode=disable'
export MOZI_PROJECT_ROOT='/absolute/path/to/business-project'

未設定 MOZI_PROJECT_ROOT 時，CLI 會向上查詢 go.mod。資料庫連線被拒絕時，明確說明本地 PostgreSQL/設計資料庫不可用，不要偽造結果。

沙箱無法讀取使用者 Go 快取時使用：

GOCACHE=/private/tmp/memflow-go-build-cache go test ./...

命令速查

初始化與快照

mozi new myapp --module github.com/example/myapp --desktop --miniapp
mozi init
mozi import --dir models/
mozi import --file models/content/deck.yaml
mozi export --dir models/
mozi export --module content

校驗、差異與歷史

mozi validate
mozi validate --module content
mozi lint --strict
mozi lint --json
mozi diff --model content/Deck
mozi history --model content/Deck

模型 CRUD

mozi model get --model content/Deck --json
mozi model create --json '<完整 ModelIR>'
mozi model update --model content/Deck --json '<完整 ModelIR>'

model update 需要完整 ModelIR。始終先 get，修改完整 JSON 後再 update；不要提交區域性物件，否則遺漏欄位會被清空。

變更計劃與同步

mozi change-plan --model content/Deck
mozi change-plan --model content/Deck --json
mozi sync --model content/Deck
mozi sync --all

錯誤碼與設計字典

mozi error-code list --json
mozi error-code delete DEPRECATED_CODE

mozi dictionary list api_consumers --json
mozi dictionary upsert api_consumers desktop --label '桌面端' --alias tauri --json
mozi dictionary delete api_consumers legacy_consumer --json

Phase 2 契約產物

mozi artifacts migration --model content/Deck --out migrations
mozi artifacts bruno --model content/Deck --openapi docs/swagger.json --out contracts/bruno
mozi artifacts permissions --model content/Deck --out internal/permissions/generated.go
mozi artifacts i18n --locale zh-CN --out locales/source.json
mozi artifacts i18n-validate --locale en --input locales/en.json
mozi artifacts typescript-sdk --openapi docs/swagger.json --out sdk/typescript/client.ts

建立模型工作流

1. 按五類關注點了解需求，明確假設。
2. 展示完整 ModelIR，並在使用者確認後儲存：

mozi model create --json '<完整 ModelIR>'

1. 執行設計校驗：

mozi validate
mozi lint --strict
mozi diff --model <Module/Model>

1. 獲取 AI 變更計劃：

mozi change-plan --model <Module/Model>

1. 按計劃製作最小、可審查的普通程式碼補丁；保留現有業務邏輯和使用者改動。
2. 修改 Swagger 註解後重新生成 OpenAPI：

swag init -g cmd/server/main.go -o docs/

1. 根據模型內容生成必要的 Phase 2 產物，不要無條件全部生成。
2. 執行生成、型別檢查和測試：

make generate
cd admin && npx tsc --noEmit
cd .. && GOCACHE=/private/tmp/memflow-go-build-cache go test ./...
mozi export --module <Module>

1. 審查程式碼和快照差異後同步：

mozi sync --model <Module/Model>

修改模型工作流

1. 獲取完整模型：

mozi model get --model <Module/Model> --json > current.json

1. 修改完整 JSON，並明確 rename、許可權、錯誤碼和契約變化。
2. 更新設計資料庫：

mozi model update --model <Module/Model> --json "$(cat current.json)"

1. 依次執行 validate、lint --strict、diff、change-plan。
2. 先審查 breaking/conditional/dangerous 項，再修改程式碼。
3. 重新生成 OpenAPI 和必要的契約產物。
4. 完成型別檢查、測試和 YAML 匯出後再執行 sync。

批次模型變更

1. 一次性建立或更新所有相關模型。
2. 執行 mozi validate && mozi lint --strict。
3. 獲取每個變化模型的 change plan，跳過狀態為 applied 的模型。
4. 合併成一個覆蓋完整關係影響面的程式碼補丁。
5. 重新生成 OpenAPI 和相關契約產物。
6. 執行全量驗證並審查 YAML 快照。
7. 使用 mozi sync --all 同步已確認完成的模型。

契約產物規則

資料庫遷移

• 僅允許 mozi artifacts migration 自動生成全部為 safe 的遷移。
• 命令拒絕 conditional/dangerous 時立即停止；展示遷移建議並請求人工決策。
• 不要削弱門禁，不要自動執行 Change Plan 中展示的 SQL。
• 刪除欄位、型別收窄、複雜型別轉換和不可逆操作必須人工設計資料遷移。
• 審查 .up.sql 與 .down.sql，尤其關注鎖表、預設值、歷史資料和回滾資料損失。

Bruno 合約

• 僅在 api_intent.test_contracts 非空時生成。
• 先更新並審查 OpenAPI，確保 operation_id 穩定。
• 把 Bruno 當作黑盒 HTTP 契約，不用它替代領域單元測試。

許可權骨架

• 僅在 semantics.permission_rules 非空時生成。
• 生成常量和 Authorizer 介面後，在服務端顯式接入 enforcement point。
• 為 allow、deny、own、tenant 和預設拒絕編寫測試。

i18n

• 匯出 source catalog 後，將翻譯存為 key→string JSON 物件。
• 缺失 key 或佔位符不一致時視為失敗。
• 將 stale key 作為清理候選，不要未經確認直接刪除線上翻譯。
• 不要自動偽造未經稽核的翻譯。

TypeScript SDK

• 只從已審查的 OpenAPI 生成。
• 生成後檢查 diff，並在實際消費者中執行 TypeScript 型別檢查。
• 不要從自由文本 API Intent 猜測請求或響應結構。

常見影響路徑

• 後端：ent/schema/、internal/model/、internal/handler/、internal/service/
• 前端：admin/src/pages/、admin/src/api/、admin/src/stores/
• OpenAPI：docs/swagger.json、docs/swagger.yaml
• 遷移：migrations/*.up.sql、migrations/*.down.sql
• 合約：contracts/bruno/*.bru
• 許可權：internal/permissions/generated.go
• i18n：locales/source.json
• SDK：sdk/typescript/client.ts

將影響分析中的 certain、inferred、suggested 分開處理。不要把路徑推斷或 AI 建議描述成確定事實。

安全規則

• 不要使用舊的模板覆蓋工作流。
• 始終通過 mozi change-plan 獲取變更契約，不要用 curl 或瀏覽器代替。
• 不要修改與模型變更無關的檔案。
• 保留使用者未提交改動；失敗回滾只能覆蓋本次受控修改。
• 修改 ent Schema 後執行 make generate。
• 修改 Swagger 註解後執行 swag init -g cmd/server/main.go -o docs/。
• 修改前端後執行 TypeScript 型別檢查。
• 模型變更完成後匯出 YAML 快照並檢查 git diff models/。
• 只有完成程式碼、遷移、契約和驗證後才能執行 mozi sync。
• 如果資料庫或外部系統操作需要額外許可權，先請求授權，不要繞過審批。

最終報告

說明：

• 修改了哪些模型和契約。
• validate 與 lint --strict 是否通過。
• 是否使用了 Change Plan，是否存在 breaking/conditional/dangerous 項。
• 生成了哪些遷移、Bruno、許可權、i18n 或 SDK 產物。
• 執行了哪些型別檢查和測試。
• YAML 是否匯出、模型是否同步。
• 仍需人工完成或審批的事項。

這是一個專注於Mozi模型驅動開發的工具類Skill，內容覆蓋較全面，從建模規範到命令使用都有說明。優點是規則講解細緻、安全約束到位；不足是缺少實際案例演示和問題解答指引，對新手不夠友好。整體質量中上，適合有一定基礎的開發者使用。