From e2a76ef54a5b1be7129ec312f4f05feba999e489 Mon Sep 17 00:00:00 2001 From: mlogclub Date: Fri, 24 Jul 2026 14:43:03 +0800 Subject: [PATCH] refactor: update build commands from make to task in documentation and add Taskfile for task management --- AGENTS.md | 8 +- README.md | 18 ++-- README_ZH.md | 32 ++----- Taskfile.yml | 244 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs | 2 +- 5 files changed, 267 insertions(+), 37 deletions(-) create mode 100644 Taskfile.yml diff --git a/AGENTS.md b/AGENTS.md index 0c599ff..aa525ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -259,7 +259,7 @@ func BuildXxx(item *models.Xxx) *response.Xxx { ### 7.1 Code Generation - Entry point: `cmd/generator/generator.go` -- Command: `make generator` +- Command: `task generator` - Generation library: `github.com/mlogclub/codegen` - Registration method: `codegen.GetGenerateStruct(&models.XXX{})` - Generated files should be placed in the `generated` directory and named `*_gen.go` @@ -269,7 +269,7 @@ Standard process: 1. Define or modify the model 2. Register it in the generator -3. Run `make generator` +3. Run `task generator` 4. Add business logic in the handwritten layers 5. Run tests and self-checks @@ -417,7 +417,7 @@ httpx.WriteJSON(ctx, &web.PageResult{Results: results, Page: paging}) - System constants should be defined uniformly under `/internal/pkg/enums` - Model statuses should preferably use `Status` from `/internal/pkg/enums/enums.go`; only add a new status enum when it does not meet the requirement - Enums shared by backend and frontend must follow [docs/design/specs/backend-frontend-enum-ast-spec.md](docs/design/specs/backend-frontend-enum-ast-spec.md) -- Shared backend/frontend enums may only be defined in the backend; the frontend must generate results with `make enums`, and handwritten duplicate business enums are forbidden +- Shared backend/frontend enums may only be defined in the backend; the frontend must generate results with `task enums`, and handwritten duplicate business enums are forbidden ## 9. Go Code Standards @@ -475,7 +475,7 @@ httpx.WriteJSON(ctx, &web.PageResult{Results: results, Page: paging}) ### 10.5 Enum Management - All frontend enums should be defined uniformly in `web/lib/enums.ts` -- Enums are defined by the backend; frontend enums are generated with `make enums` +- Enums are defined by the backend; frontend enums are generated with `task enums` ### 10.6 Dashboard List and Form Baseline diff --git a/README.md b/README.md index b8f50e8..3705a68 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,7 @@ cd .. Start backend and frontend development servers together: ```bash -make dev +task dev ``` Default development URLs: @@ -186,14 +186,14 @@ Default development URLs: ## Common Commands ```bash -make dev # start backend and frontend development servers -make build # build the frontend SPA and current-platform Go binary into dist/ -make build LANCEDB=1 # build the current-platform LanceDB binary into dist/ -make release # build linux/darwin/windows release binaries into dist/ -make release LANCEDB=1 # build LanceDB release binaries into dist/ -make generator # run code generation -make enums # generate frontend enums -make help # show available make targets +task dev # start backend and frontend development servers +task build # build the frontend SPA and current-platform Go binary into dist/ +task build LANCEDB=1 # build the current-platform LanceDB binary into dist/ +task release # build linux/darwin/windows release binaries into dist/ +task release LANCEDB=1 # build LanceDB release binaries into dist/ +task generator # run code generation +task enums # generate frontend enums +task --list # show available tasks ``` ## AI Agent Workflow diff --git a/README_ZH.md b/README_ZH.md index e4cc4df..f035eb1 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -138,14 +138,7 @@ cd .. 同时启动后端和前端开发服务： ```bash -make dev -``` - -或分别启动： - -```bash -make run-go -make web-dev +task dev ``` 开发环境默认入口： @@ -193,21 +186,14 @@ make web-dev ## 常用命令 ```bash -make dev # 同时启动后端和前端开发服务 -make run # 构建前端 SPA 后启动后端 -make run-go # 启动后端，自动确保 SPA 已构建 -make web-dev # 启动前端开发服务 -make build # 构建前端 SPA 和当前平台 Go 二进制 -make build-linux # 构建 linux/amd64 二进制 -make release # 构建常用平台二进制 -make web-build-spa # 构建 web 静态 SPA 和嵌入式 SDK -make test # 运行 Go 测试，自动确保 SPA 已构建 -make check # 运行 Go 测试、前端 typecheck 和 lint -make generator # 执行代码生成 -make enums # 生成前端枚举 -make migration # 执行 migration -make testdata # 初始化中文演示/测试数据 -make testdata TESTDATA_LANG=en # 初始化英文演示/测试数据 +task dev # 同时启动后端和前端开发服务 +task build # 构建前端 SPA 和当前平台 Go 二进制 +task build LANCEDB=1 # 构建当前平台 LanceDB 二进制 +task release # 构建常用平台二进制 +task release LANCEDB=1 # 构建 LanceDB 发布二进制 +task generator # 执行代码生成 +task enums # 生成前端枚举 +task --list # 查看可用任务 ``` ## AI Agent 工作流 diff --git a/Taskfile.yml b/Taskfile.yml new file mode 100644 index 0000000..834548e --- /dev/null +++ b/Taskfile.yml @@ -0,0 +1,244 @@ +version: '3' + +vars: + APP: agent-desk + MAIN: ./cmd/server + WEB_DIR: web + DIST_DIR: dist + GO: + sh: 'printf "%s" "${GO:-go}"' + PNPM: + sh: 'printf "%s" "${PNPM:-pnpm}"' + DEV_PORT: + sh: 'printf "%s" "${DEV_PORT:-8083}"' + DEV_API_BASE_URL: + sh: 'printf "%s" "${DEV_API_BASE_URL:-http://127.0.0.1:${DEV_PORT:-8083}}"' + LANCEDB_VERSION: + sh: 'printf "%s" "${LANCEDB_VERSION:-v0.1.2}"' + LANCEDB_DOWNLOAD_SCRIPT: + sh: 'printf "%s" "${LANCEDB_DOWNLOAD_SCRIPT:-https://raw.githubusercontent.com/lancedb/lancedb-go/main/scripts/download-artifacts.sh}"' + LANCEDB: + sh: 'printf "%s" "${LANCEDB:-0}"' + UNAME_S: + sh: uname -s + UNAME_M: + sh: uname -m + BUILD_OUTPUT: + sh: | + suffix="" + ext="" + if [ "{{.LANCEDB}}" = "1" ]; then + suffix="-lancedb" + fi + if [ "$(${GO:-go} env GOOS)" = "windows" ]; then + ext=".exe" + fi + printf "%s/%s%s%s" "{{.DIST_DIR}}" "{{.APP}}" "$suffix" "$ext" + LANCEDB_ARCH: + sh: | + case "$(uname -m)" in + x86_64|amd64) printf amd64 ;; + arm64|aarch64) printf arm64 ;; + *) printf unsupported ;; + esac + LANCEDB_PLATFORM: + sh: | + case "$(uname -s)" in + Darwin) printf darwin ;; + Linux) printf linux ;; + MINGW*|MSYS*|CYGWIN*) printf windows ;; + *) printf unsupported ;; + esac + LANCEDB_PLATFORM_ARCH: + sh: | + case "$(uname -s)" in + Darwin) platform=darwin ;; + Linux) platform=linux ;; + MINGW*|MSYS*|CYGWIN*) platform=windows ;; + *) platform=unsupported ;; + esac + case "$(uname -m)" in + x86_64|amd64) arch=amd64 ;; + arm64|aarch64) arch=arm64 ;; + *) arch=unsupported ;; + esac + printf "%s_%s" "$platform" "$arch" + LANCEDB_NATIVE_LIB: + sh: | + case "$(uname -s)" in + Darwin) platform=darwin ;; + Linux) platform=linux ;; + MINGW*|MSYS*|CYGWIN*) platform=windows ;; + *) platform=unsupported ;; + esac + case "$(uname -m)" in + x86_64|amd64) arch=amd64 ;; + arm64|aarch64) arch=arm64 ;; + *) arch=unsupported ;; + esac + printf "%s/lib/%s_%s/liblancedb_go.a" "{{.ROOT_DIR}}" "$platform" "$arch" + LANCEDB_CGO_CFLAGS: '-I{{.ROOT_DIR}}/include' + +tasks: + default: + desc: Show available tasks + cmds: + - task --list + + dev: + desc: Start backend and frontend development servers + deps: + - task: _go-dev + - task: _web-dev + + build: + desc: Build the current system into dist/; pass LANCEDB=1 for the current-platform LanceDB binary + cmds: + - | + if [ "{{.LANCEDB}}" = "1" ]; then + task _lancedb-check + fi + - task: _prepare-dist + - task: _web-build-spa + - | + echo "Building {{.BUILD_OUTPUT}}..." + if [ "{{.LANCEDB}}" = "1" ]; then + case "$(uname -s)" in + Darwin) system_ldflags="-framework Security -framework CoreFoundation" ;; + Linux) system_ldflags="-lm -ldl -lpthread" ;; + *) system_ldflags="" ;; + esac + CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.LANCEDB_NATIVE_LIB}} $system_ldflags" \ + {{.GO}} build -tags lancedb -v -o "{{.BUILD_OUTPUT}}" {{.MAIN}} + else + {{.GO}} build -v -o "{{.BUILD_OUTPUT}}" {{.MAIN}} + fi + + release: + desc: Build linux/darwin/windows release binaries into dist/; pass LANCEDB=1 for LanceDB release binaries + cmds: + - | + if [ "{{.LANCEDB}}" = "1" ]; then + task _lancedb-release-check + fi + - task: _prepare-dist + - task: _web-build-spa + - | + echo "Building release binaries in {{.DIST_DIR}}..." + if [ "{{.LANCEDB}}" = "1" ]; then + if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then + echo "Missing LanceDB header: {{.ROOT_DIR}}/include/lancedb.h" + exit 1 + fi + build_lancedb() { + platform="$1" + arch="$2" + ext="$3" + system_ldflags="$4" + native_lib="{{.ROOT_DIR}}/lib/${platform}_${arch}/liblancedb_go.a" + output="{{.DIST_DIR}}/{{.APP}}-lancedb-${platform}-${arch}${ext}" + if [ ! -f "$native_lib" ]; then + echo "Missing LanceDB native library for ${platform}/${arch}: $native_lib" + echo "LanceDB release builds require matching native artifacts and a CGO-capable toolchain for each target platform." + exit 1 + fi + echo "Building $output..." + CGO_ENABLED=1 CGO_CFLAGS="-I{{.ROOT_DIR}}/include" CGO_LDFLAGS="$native_lib $system_ldflags" \ + GOOS="$platform" GOARCH="$arch" {{.GO}} build -tags lancedb -v -o "$output" {{.MAIN}} + } + build_lancedb linux amd64 "" "-lm -ldl -lpthread" + build_lancedb linux arm64 "" "-lm -ldl -lpthread" + build_lancedb darwin amd64 "" "-framework Security -framework CoreFoundation" + build_lancedb darwin arm64 "" "-framework Security -framework CoreFoundation" + build_lancedb windows amd64 ".exe" "" + else + GOOS=linux GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-amd64" {{.MAIN}} + GOOS=linux GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-arm64" {{.MAIN}} + GOOS=darwin GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-amd64" {{.MAIN}} + GOOS=darwin GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-arm64" {{.MAIN}} + GOOS=windows GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-windows-amd64.exe" {{.MAIN}} + fi + + generator: + desc: Run code generation + cmds: + - '{{.GO}} run ./cmd/generator/generator.go' + + enums: + desc: Generate frontend enums + cmds: + - '{{.GO}} run ./cmd/enums/generator.go' + + _web-build-spa: + cmds: + - 'cd {{.WEB_DIR}} && {{.PNPM}} build:sdk && {{.PNPM}} build' + + _web-dev: + cmds: + - 'cd {{.WEB_DIR}} && NEXT_PUBLIC_API_BASE_URL="" NEXT_API_BASE_URL="{{.DEV_API_BASE_URL}}" {{.PNPM}} dev' + + _go-dev: + cmds: + - task: _lancedb-check + - | + case "$(uname -s)" in + Darwin) system_ldflags="-framework Security -framework CoreFoundation" ;; + Linux) system_ldflags="-lm -ldl -lpthread" ;; + *) system_ldflags="" ;; + esac + AGENT_DESK_SERVER_PORT="{{.DEV_PORT}}" CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.LANCEDB_NATIVE_LIB}} $system_ldflags" \ + {{.GO}} run -tags "dev lancedb" {{.MAIN}} + + _prepare-dist: + cmds: + - 'mkdir -p {{.DIST_DIR}}' + + _lancedb-artifacts: + cmds: + - | + if [ "{{.LANCEDB_PLATFORM}}" = "unsupported" ] || [ "{{.LANCEDB_ARCH}}" = "unsupported" ]; then + echo "Unsupported LanceDB platform: {{.UNAME_S}}/{{.UNAME_M}}" + exit 1 + fi + - | + if [ -f "{{.LANCEDB_NATIVE_LIB}}" ] && [ -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then + echo "LanceDB native artifacts already exist for {{.LANCEDB_PLATFORM_ARCH}}." + else + echo "Downloading LanceDB native artifacts {{.LANCEDB_VERSION}} for {{.LANCEDB_PLATFORM_ARCH}}..." + curl -sSL "{{.LANCEDB_DOWNLOAD_SCRIPT}}" | bash -s "{{.LANCEDB_VERSION}}" + fi + + _lancedb-check: + cmds: + - task: _lancedb-artifacts + - | + if [ ! -f "{{.LANCEDB_NATIVE_LIB}}" ]; then + echo "Missing LanceDB native library: {{.LANCEDB_NATIVE_LIB}}" + exit 1 + fi + - | + if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then + echo "Missing LanceDB header: {{.ROOT_DIR}}/include/lancedb.h" + exit 1 + fi + + _lancedb-release-check: + cmds: + - | + if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then + echo "Missing LanceDB header: {{.ROOT_DIR}}/include/lancedb.h" + exit 1 + fi + - | + missing=0 + for target in linux_amd64 linux_arm64 darwin_amd64 darwin_arm64 windows_amd64; do + native_lib="{{.ROOT_DIR}}/lib/${target}/liblancedb_go.a" + if [ ! -f "$native_lib" ]; then + echo "Missing LanceDB native library: $native_lib" + missing=1 + fi + done + if [ "$missing" = "1" ]; then + echo "LanceDB release builds require matching native artifacts and a CGO-capable toolchain for each target platform." + exit 1 + fi diff --git a/docs b/docs index b6d08c0..41418f4 160000 --- a/docs +++ b/docs @@ -1 +1 @@ -Subproject commit b6d08c0964853a795979c2a2be941254ac4ab39d +Subproject commit 41418f4adf7376340f7dec7551a3cb223221ccd5