feat: implement GET /api/v1/agents/<agent_id>/versions/<version_id> API (#15640)

## Summary

Implement the `GET /api/v1/agents/<agent_id>/versions/<version_id>`
endpoint in Go, returning full version details including DSL.

Depends on #15629 which introduced the version list endpoint and
`UserCanvasVersionDAO` infrastructure.

### Changes

- **Modified**: `internal/handler/agent.go` — Added `GetAgentVersion`
handler with auth check and ownership verification
- **Modified**: `internal/router/router.go` — Registered `GET
/:agent_id/versions/:version_id` route
- **New/Modified tests**: Service and handler tests for the version
detail endpoint

### Testing

```
=== RUN   TestGetVersion_Success       --- PASS
=== RUN   TestGetVersion_WrongCanvas   --- PASS
=== RUN   TestGetVersion_NotFound      --- PASS
=== RUN   TestGetAgentVersionHandler_Success      --- PASS
=== RUN   TestGetAgentVersionHandler_VersionNotFound --- PASS
```

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

internal/handler/agent.go

@@ -17,6 +17,7 @@
 package handler
 
 import (
+	"errors"
 	"fmt"
 	"mime/multipart"
 	"net/http"
@@ -24,6 +25,8 @@ import (
 	"strings"
 
 	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
 
 	"ragflow/internal/common"
 	"ragflow/internal/service"
@@ -182,6 +185,71 @@ func (h *AgentHandler) ListAgentVersions(c *gin.Context) {
 // UploadAgentFile uploads one or more files associated with an agent.
 // @Summary Upload Agent File
 // @Description Upload one or more files for an agent canvas.
+
+// GetAgentVersion returns a specific version for an agent.
+// @Summary Get Agent Version
+// @Description Returns a specific version by ID, verifying it belongs to the given agent.
+// @Tags agents
+// @Produce json
+// @Param agent_id path string true "Agent ID"
+// @Param version_id path string true "Version ID"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/agents/{agent_id}/versions/{version_id} [get]
+func (h *AgentHandler) GetAgentVersion(c *gin.Context) {
+	user, errorCode, errorMessage := GetUser(c)
+	if errorCode != common.CodeSuccess {
+		jsonError(c, errorCode, errorMessage)
+		return
+	}
+
+	agentID := c.Param("agent_id")
+	versionID := c.Param("version_id")
+	if agentID == "" || versionID == "" {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeArgumentError,
+			"data":    nil,
+			"message": "agent_id and version_id are required",
+		})
+		return
+	}
+
+	ok, err := h.agentService.CheckCanvasAccess(user.ID, agentID)
+	if err != nil || !ok {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeOperatingError,
+			"data":    nil,
+			"message": "Agent not found or no permission.",
+		})
+		return
+	}
+
+	version, err := h.agentService.GetVersion(agentID, versionID)
+	if err != nil {
+		isNotFound := errors.Is(err, gorm.ErrRecordNotFound) || err.Error() == "version not found"
+		if !isNotFound {
+			common.Warn("get agent version failed", zap.String("error", err.Error()))
+			c.JSON(http.StatusOK, gin.H{
+				"code":    common.CodeServerError,
+				"data":    nil,
+				"message": "Internal server error",
+			})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"code":    common.CodeNotFound,
+			"data":    nil,
+			"message": "Version not found.",
+		})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"data":    version,
+		"message": "",
+	})
+}
+
 // @Tags agents
 // @Accept multipart/form-data
 // @Produce json

internal/handler/agent_test.go

@@ -195,6 +195,73 @@ func TestListAgentVersionsHandler_CanvasNotFound(t *testing.T) {
 		t.Errorf("expected operating error code %d, got %v", common.CodeOperatingError, code)
 	}
 }
+// TestGetAgentVersionHandler_Success verifies getting a specific version.
+func TestGetAgentVersionHandler_Success(t *testing.T) {
+	c, w, db := setupGinContextWithUserAndDB(t, "GET", "/api/v1/agents/canvas-1/versions/v1")
+	c.Params = gin.Params{{Key: "agent_id", Value: "canvas-1"}, {Key: "version_id", Value: "v1"}}
+
+	db.Create(&entity.UserCanvas{
+		ID:     "canvas-1",
+		UserID: "user-1",
+		Title:  sptr("Test Agent"),
+	})
+	db.Create(&entity.UserCanvasVersion{
+		ID:           "v1",
+		UserCanvasID: "canvas-1",
+		Title:        sptr("version-1"),
+		DSL:          entity.JSONMap{"key": "value"},
+	})
+
+	h := NewAgentHandler(service.NewAgentService(), nil)
+	h.GetAgentVersion(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp map[string]interface{}
+	json.Unmarshal(w.Body.Bytes(), &resp)
+	code, _ := resp["code"].(float64)
+	if code != float64(common.CodeSuccess) {
+		t.Fatalf("expected code 0, got %v: %v", code, resp["message"])
+	}
+
+	data, ok := resp["data"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected data object, got %T", resp["data"])
+	}
+	if data["title"] != "version-1" {
+		t.Errorf("expected title 'version-1', got %v", data["title"])
+	}
+	if _, ok := data["dsl"]; !ok {
+		t.Errorf("expected dsl field in version detail response")
+	}
+}
+
+// TestGetAgentVersionHandler_VersionNotFound verifies 404 for missing version.
+func TestGetAgentVersionHandler_VersionNotFound(t *testing.T) {
+	c, w, db := setupGinContextWithUserAndDB(t, "GET", "/api/v1/agents/canvas-1/versions/non-existent")
+	c.Params = gin.Params{{Key: "agent_id", Value: "canvas-1"}, {Key: "version_id", Value: "non-existent"}}
+
+	db.Create(&entity.UserCanvas{
+		ID:     "canvas-1",
+		UserID: "user-1",
+		Title:  sptr("Test Agent"),
+	})
+
+	h := NewAgentHandler(service.NewAgentService(), nil)
+	h.GetAgentVersion(c)
+
+	var resp map[string]interface{}
+	json.Unmarshal(w.Body.Bytes(), &resp)
+	code, _ := resp["code"].(float64)
+	if code != float64(common.CodeNotFound) {
+		t.Errorf("expected not found code %d, got %v", common.CodeNotFound, code)
+	}
+}
+
+
+
 // sptr returns a pointer to the given string.
 // ptr returns a pointer to the given int64.
 func ptr(v int64) *int64 { return &v }