refactor: update Taskfile and documentation for LanceDB build commands

README.md

@@ -188,9 +188,9 @@ Default development URLs:
 ```bash
 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 build:lancedb  # 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 release:lancedb  # build LanceDB release binaries into dist/
 task generator  # run code generation
 task enums      # generate frontend enums
 task --list     # show available tasks

README_ZH.md

@@ -188,9 +188,9 @@ task dev
 ```bash
 task dev            # 同时启动后端和前端开发服务
 task build          # 构建前端 SPA 和当前平台 Go 二进制
-task build LANCEDB=1  # 构建当前平台 LanceDB 二进制
+task build:lancedb  # 构建当前平台 LanceDB 二进制
 task release        # 构建常用平台二进制
-task release LANCEDB=1  # 构建 LanceDB 发布二进制
+task release:lancedb  # 构建 LanceDB 发布二进制
 task generator      # 执行代码生成
 task enums          # 生成前端枚举
 task --list         # 查看可用任务

Taskfile.yml

@@ -1,5 +1,7 @@
 version: '3'
 
+silent: true
+
 vars:
   APP: agent-desk
   MAIN: ./cmd/server
@@ -17,31 +19,13 @@ vars:
     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:
+  HOST_OS:
-    sh: 'printf "%s" "${LANCEDB:-0}"'
-  UNAME_S:
     sh: uname -s
-  UNAME_M:
+  HOST_ARCH:
     sh: uname -m
-  BUILD_OUTPUT:
+  HOST_GOOS:
-    sh: |
+    sh: '${GO:-go} env GOOS'
-      suffix=""
+  HOST_LANCEDB_PLATFORM:
-      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 ;;
@@ -49,7 +33,14 @@ vars:
         MINGW*|MSYS*|CYGWIN*) printf windows ;;
         *) printf unsupported ;;
       esac
-  LANCEDB_PLATFORM_ARCH:
+  HOST_LANCEDB_ARCH:
+    sh: |
+      case "$(uname -m)" in
+        x86_64|amd64) printf amd64 ;;
+        arm64|aarch64) printf arm64 ;;
+        *) printf unsupported ;;
+      esac
+  HOST_LANCEDB_TARGET:
     sh: |
       case "$(uname -s)" in
         Darwin) platform=darwin ;;
@@ -63,7 +54,7 @@ vars:
         *) arch=unsupported ;;
       esac
       printf "%s_%s" "$platform" "$arch"
-  LANCEDB_NATIVE_LIB:
+  HOST_LANCEDB_LIB:
     sh: |
       case "$(uname -s)" in
         Darwin) platform=darwin ;;
@@ -88,48 +79,69 @@ tasks:
   dev:
     desc: Start backend and frontend development servers
     deps:
-      - task: _go-dev
+      - task: dev:backend
-      - task: _web-dev
+      - task: dev:frontend
 
   build:
-    desc: Build the current system into dist/; pass LANCEDB=1 for the current-platform LanceDB binary
+    desc: Build the frontend SPA and current-platform Go binary into dist/
+    deps:
+      - task: build:web
+      - task: build:dist
     cmds:
       - |
-        if [ "{{.LANCEDB}}" = "1" ]; then
+        ext=""
-          task _lancedb-check
+        if [ "{{.HOST_GOOS}}" = "windows" ]; then
+          ext=".exe"
         fi
-      - task: _prepare-dist
+        output="{{.DIST_DIR}}/{{.APP}}${ext}"
-      - task: _web-build-spa
+        echo "Building $output..."
+        {{.GO}} build -v -o "$output" {{.MAIN}}
+
+  build:lancedb:
+    desc: Build the current-platform LanceDB binary into dist/
+    deps:
+      - task: lancedb:ensure-current
+      - task: build:web
+      - task: build:dist
+    cmds:
       - |
-        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" \
+        ext=""
-            {{.GO}} build -tags lancedb -v -o "{{.BUILD_OUTPUT}}" {{.MAIN}}
+        if [ "{{.HOST_GOOS}}" = "windows" ]; then
-        else
+          ext=".exe"
-          {{.GO}} build -v -o "{{.BUILD_OUTPUT}}" {{.MAIN}}
         fi
+        output="{{.DIST_DIR}}/{{.APP}}-lancedb${ext}"
+        echo "Building $output..."
+        CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.HOST_LANCEDB_LIB}} $system_ldflags" \
+          {{.GO}} build -tags lancedb -v -o "$output" {{.MAIN}}
 
   release:
-    desc: Build linux/darwin/windows release binaries into dist/; pass LANCEDB=1 for LanceDB release binaries
+    desc: Build linux/darwin/windows release binaries into dist/
+    deps:
+      - task: build:web
+      - task: build:dist
     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
+        GOOS=linux GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-amd64" {{.MAIN}}
-          if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then
+        GOOS=linux GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-arm64" {{.MAIN}}
-            echo "Missing LanceDB header: {{.ROOT_DIR}}/include/lancedb.h"
+        GOOS=darwin GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-amd64" {{.MAIN}}
-            exit 1
+        GOOS=darwin GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-arm64" {{.MAIN}}
-          fi
+        GOOS=windows GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-windows-amd64.exe" {{.MAIN}}
+
+  release:lancedb:
+    desc: Build LanceDB release binaries into dist/
+    deps:
+      - task: lancedb:check-release
+      - task: build:web
+      - task: build:dist
+    cmds:
+      - |
+        echo "Building LanceDB release binaries in {{.DIST_DIR}}..."
         build_lancedb() {
           platform="$1"
           arch="$2"
@@ -137,11 +149,6 @@ tasks:
           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}}
@@ -151,13 +158,6 @@ tasks:
         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
@@ -169,51 +169,55 @@ tasks:
     cmds:
       - '{{.GO}} run ./cmd/enums/generator.go'
 
-  _web-build-spa:
+  dev:backend:
+    internal: true
     cmds:
-      - 'cd {{.WEB_DIR}} && {{.PNPM}} build:sdk && {{.PNPM}} build'
+      - task: lancedb:ensure-current
-
-  _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
       - |
+        echo "Starting backend on http://127.0.0.1:{{.DEV_PORT}} ..."
         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" \
+        AGENT_DESK_SERVER_PORT="{{.DEV_PORT}}" CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.HOST_LANCEDB_LIB}} $system_ldflags" \
           {{.GO}} run -tags "dev lancedb" {{.MAIN}}
 
-  _prepare-dist:
+  dev:frontend:
+    internal: true
+    cmds:
+      - |
+        echo "Starting frontend on http://localhost:3000 ..."
+        cd {{.WEB_DIR}} && NEXT_PUBLIC_API_BASE_URL="" NEXT_API_BASE_URL="{{.DEV_API_BASE_URL}}" {{.PNPM}} dev
+
+  build:web:
+    internal: true
+    cmds:
+      - 'cd {{.WEB_DIR}} && {{.PNPM}} build:sdk && {{.PNPM}} build'
+
+  build:dist:
+    internal: true
     cmds:
       - 'mkdir -p {{.DIST_DIR}}'
 
-  _lancedb-artifacts:
+  lancedb:ensure-current:
+    internal: true
     cmds:
       - |
-        if [ "{{.LANCEDB_PLATFORM}}" = "unsupported" ] || [ "{{.LANCEDB_ARCH}}" = "unsupported" ]; then
+        if [ "{{.HOST_LANCEDB_PLATFORM}}" = "unsupported" ] || [ "{{.HOST_LANCEDB_ARCH}}" = "unsupported" ]; then
-          echo "Unsupported LanceDB platform: {{.UNAME_S}}/{{.UNAME_M}}"
+          echo "Unsupported LanceDB platform: {{.HOST_OS}}/{{.HOST_ARCH}}"
           exit 1
         fi
       - |
-        if [ -f "{{.LANCEDB_NATIVE_LIB}}" ] && [ -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then
+        if [ -f "{{.HOST_LANCEDB_LIB}}" ] && [ -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then
-          echo "LanceDB native artifacts already exist for {{.LANCEDB_PLATFORM_ARCH}}."
+          echo "LanceDB native artifacts already exist for {{.HOST_LANCEDB_TARGET}}."
         else
-          echo "Downloading LanceDB native artifacts {{.LANCEDB_VERSION}} for {{.LANCEDB_PLATFORM_ARCH}}..."
+          echo "Downloading LanceDB native artifacts {{.LANCEDB_VERSION}} for {{.HOST_LANCEDB_TARGET}}..."
           curl -sSL "{{.LANCEDB_DOWNLOAD_SCRIPT}}" | bash -s "{{.LANCEDB_VERSION}}"
         fi
-
-  _lancedb-check:
-    cmds:
-      - task: _lancedb-artifacts
       - |
-        if [ ! -f "{{.LANCEDB_NATIVE_LIB}}" ]; then
+        if [ ! -f "{{.HOST_LANCEDB_LIB}}" ]; then
-          echo "Missing LanceDB native library: {{.LANCEDB_NATIVE_LIB}}"
+          echo "Missing LanceDB native library: {{.HOST_LANCEDB_LIB}}"
           exit 1
         fi
       - |
@@ -222,7 +226,8 @@ tasks:
           exit 1
         fi
 
-  _lancedb-release-check:
+  lancedb:check-release:
+    internal: true
     cmds:
       - |
         if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then