refactor(canvas): 预演台 - 重构工作台与场景交互链路

2026-10-06 09:06:43 +08:00
parent 1dfc8ce7ac
commit 112916587c
128 changed files with 42372 additions and 5011 deletions
--- a/backend/builtin/影策短剧制作工作流/SKILL.md
+++ b/backend/builtin/影策短剧制作工作流/SKILL.md
@@ -111,6 +111,12 @@ INTAKE

 画布操作顺序仍遵循真实能力：复用已核实节点；使用 `canvas_list_node_types` 查合法类型；分镜通过 `canvas_create_storyboard` 创建、修改前 `canvas_read_storyboard`；角色卡通过 `canvas_create_character` 创建，不用 `canvas_apply_ops` 新建文本节点冒充；普通节点/引用通过 `canvas_apply_ops`；整理使用 `canvas_arrange_nodes`。工具参数、审批和失败恢复以系统级合同及本轮真实 schema 为准。

+### 预演台专项执行链
+
+当用户要求城市/环境、人物、走位、运镜或白膜视频时，先用 `previs_scene_read` 读取场景目录，再精读目标场景并设置 `includeTransforms=true`。城市或室内环境用 `previs_scene_create` 的 `interior`、`crowd` 或 `action_chase` 模板建立受控白模，再用 `previs_apply_patch` 增加墙体、道路、建筑块、灯光和道具；人物用 `object_add`，必须提供合法 `kind`、`primitive`、`archetype`、`pose` 和十六进制 `color`（`#RRGGBB` 或 `#RRGGBBAA`）。
+
+人物移动动作应通过对象的 `position`、`rotation`、`pose` 以及镜头/对象关键帧能力逐步写入，摄影机运动通过 `camera_update` 的 `position`、`rotation`、`target`、`focalLength` 和镜头的 `cameraMove` 表达。每次写入前重新读取最新 `snapshotHash`；审批后若状态冲突，重新读取并重新规划，不复用旧补丁。完成布局后再次读取并确认人物、环境、机位和时长，再调用 `previs_preview` 请求 `clay_video` 白膜预演；工具返回任务/请求状态后，用 `task_get` 或真实事件核验，不把“已请求”称为“已导出”。
+
 - `canvas_apply_ops`、分镜写入和媒体生成属于写操作，遵循当前 Agent 权限模式。
 - `generate_media` 是可能收费的操作。用户未明确授权时，先输出方案和预计范围，使用 `ask_user` 获取一次具体确认。
 - 额外数量、换模型、改变规格或重试都视为新方案；失败后不自动重复收费。
--- a/backend/internal/app/cloud_agent_director.go
+++ b/backend/internal/app/cloud_agent_director.go
@@ -7,23 +7,31 @@ import (
 	"infinite-canvas/backend/internal/repository"
 )

-// Director Agent tools deliberately expose a projection rather than the raw
-// DirectorScene payload. The browser owns model URLs and storage references;
+// Previs Agent tools deliberately expose a projection rather than the raw
+// PrevisScene payload. The browser owns model URLs and storage references;
 // the Agent only needs semantic shot/layout data to plan a preview.
-func cloudAgentDirectorSceneRead(repo *repository.Repository, userID, canvasID string, call cloudAgentCall) (any, error) {
+func cloudAgentPrevisSceneRead(repo *repository.Repository, userID, canvasID string, call cloudAgentCall) (any, error) {
 	var args struct {
-		SceneID   string   `json:"sceneId"`
-		ShotID    string   `json:"shotId"`
-		ObjectIDs []string `json:"objectIds"`
+		SceneID           string   `json:"sceneId"`
+		ShotID            string   `json:"shotId"`
+		ObjectIDs         []string `json:"objectIds"`
+		IncludeTransforms bool     `json:"includeTransforms"` // Return exact position/rotation/fov for spatial planning
 	}
 	if err := decodeCloudAgentJSONObject(call.Function.Arguments, &args); err != nil {
 		return nil, cloudAgentJSONArgumentError(err)
 	}
-	if err := validateCloudAgentID(args.SceneID, "导演场景 ID", 80); err != nil {
-		return nil, err
+	if args.SceneID != "" {
+		if err := validateCloudAgentID(args.SceneID, "导演场景 ID", 80); err != nil {
+			return nil, err
+		}
 	}
-	if err := validateCloudAgentID(args.ShotID, "导演镜头 ID", 80); err != nil {
-		return nil, err
+	if args.ShotID != "" {
+		if err := validateCloudAgentID(args.ShotID, "导演镜头 ID", 80); err != nil {
+			return nil, err
+		}
+		if args.SceneID == "" {
+			return nil, cloudAgentFieldError("shotId", "requires_scene", "指定 shotId 时必须同时提供 sceneId")
+		}
 	}
 	if len(args.ObjectIDs) > 16 {
 		return nil, BadAuthRequest("导演对象读取最多包含16个对象 ID")
@@ -42,7 +50,7 @@ func cloudAgentDirectorSceneRead(repo *repository.Repository, userID, canvasID s
 	if err != nil {
 		return nil, err
 	}
-	rawScenes := creationMaps(doc["directorScenes"])
+	rawScenes := creationMaps(doc["previsScenes"])
 	if args.SceneID == "" {
 		items := make([]map[string]any, 0, len(rawScenes))
 		for _, scene := range rawScenes {
@@ -55,19 +63,20 @@ func cloudAgentDirectorSceneRead(repo *repository.Repository, userID, canvasID s
 			})
 		}
 		return map[string]any{
-			"canvasId": canvasID,
-			"scenes":   items,
-			"count":    len(items),
-			"guidance": "先用返回的 sceneId 读取一个场景，再使用 shotId 进行布局或预演。",
+			"canvasId":           canvasID,
+			"canvasSnapshotHash": cloudAgentCanvasHash(doc),
+			"scenes":             items,
+			"count":              len(items),
+			"guidance":           "先用返回的 sceneId 读取一个场景，再使用 shotId 进行布局或预演。创建场景时把 canvasSnapshotHash 原样传回。",
 		}, nil
 	}

-	scene, ok := findDirectorScene(rawScenes, args.SceneID)
+	scene, ok := findPrevisScene(rawScenes, args.SceneID)
 	if !ok {
 		return nil, BadAuthRequest("导演场景不存在或不属于当前画布")
 	}
 	if args.ShotID != "" {
-		if _, ok := findDirectorShot(scene, args.ShotID); !ok {
+		if _, ok := findPrevisShot(scene, args.ShotID); !ok {
 			return nil, BadAuthRequest("导演镜头不存在或不属于指定场景")
 		}
 	}
@@ -75,16 +84,100 @@ func cloudAgentDirectorSceneRead(repo *repository.Repository, userID, canvasID s
 	for _, id := range args.ObjectIDs {
 		objectIDs[id] = true
 	}
+	projection := projectPrevisScene(scene, args.ShotID, objectIDs)
+	if args.IncludeTransforms {
+		// Augment with full spatial data for layout planning: object positions, camera transforms, FOV
+		projection["spatialLayout"] = cloudAgentPrevisSpatialLayout(scene)
+		projection["coordinateGuide"] = "坐标系: Y轴向上，单位为米。人物高约1.8m。position=[X,Y,Z]，rotation=[绕X,绕Y,绕Z弧度]。target是摄影机焦点坐标。"
+	}
 	return map[string]any{
-		"canvasId":     canvasID,
-		"scene":        projectDirectorScene(scene, args.ShotID, objectIDs),
-		"snapshotHash": creationHash(scene),
-		"revision":     canvas.Revision,
-		"guidance":     "这是安全摘要，不是可直接回写的完整 JSON；需要预演时使用 director_preview。",
+		"canvasId":           canvasID,
+		"scene":              projection,
+		"snapshotHash":       creationHash(scene),
+		"canvasSnapshotHash": cloudAgentCanvasHash(doc),
+		"revision":           canvas.Revision,
+		"guidance":           "安全摘要。修改用 previs_apply_patch；预演用 previs_preview；布局规划用 includeTransforms=true 获取精确坐标。snapshotHash 只代表该场景。",
 	}, nil
 }

-func cloudAgentDirectorPreview(repo *repository.Repository, userID, canvasID string, call cloudAgentCall) (any, error) {
+// previsMapSafe safely casts a value to map[string]any, returning an empty map on failure.
+func previsMapSafe(v any) map[string]any {
+	if m, ok := v.(map[string]any); ok {
+		return m
+	}
+	return map[string]any{}
+}
+
+// cloudAgentPrevisSpatialLayout returns precise spatial data for Agent layout planning.
+// It never returns model URLs, storage keys, or any other sensitive references.
+func cloudAgentPrevisSpatialLayout(scene map[string]any) map[string]any {
+	objects := creationMaps(scene["objects"])
+	cameras := creationMaps(scene["cameras"])
+	shots := creationMaps(scene["shots"])
+
+	objLayouts := make([]map[string]any, 0, len(objects))
+	for _, obj := range objects {
+		if !boolValue(obj["visible"], true) {
+			continue
+		}
+		transform := previsMapSafe(obj["transform"])
+		entry := map[string]any{
+			"id":            stringValue(obj["id"]),
+			"name":          stringValue(obj["name"]),
+			"kind":          stringValue(obj["kind"]),
+			"archetype":     stringValue(obj["archetype"]),
+			"pose":          stringValue(obj["pose"]),
+			"color":         stringValue(obj["color"]),
+			"position":      transform["position"],
+			"rotation":      transform["rotation"],
+			"scale":         transform["scale"],
+			"keyframeCount": len(creationMaps(obj["keyframes"])),
+			"hasMotionPath": obj["motionPath"] != nil,
+		}
+		if binding, ok := obj["characterBinding"].(map[string]any); ok {
+			entry["characterBinding"] = map[string]any{
+				"characterAssetId":   stringValue(binding["characterAssetId"]),
+				"characterVersionId": stringValue(binding["characterVersionId"]),
+				"referenceNodeId":    stringValue(binding["referenceNodeId"]),
+				"characterName":      truncateRunes(stringValue(binding["characterName"]), 160),
+			}
+		}
+		objLayouts = append(objLayouts, entry)
+	}
+
+	camLayouts := make([]map[string]any, 0, len(cameras))
+	for _, cam := range cameras {
+		transform := previsMapSafe(cam["transform"])
+		camLayouts = append(camLayouts, map[string]any{
+			"id":          stringValue(cam["id"]),
+			"name":        stringValue(cam["name"]),
+			"position":    transform["position"],
+			"target":      cam["target"],
+			"focalLength": cam["focalLength"],
+			"fov":         cam["fov"],
+		})
+	}
+
+	shotLayouts := make([]map[string]any, 0, len(shots))
+	for _, shot := range shots {
+		shotLayouts = append(shotLayouts, map[string]any{
+			"id":         stringValue(shot["id"]),
+			"name":       stringValue(shot["name"]),
+			"cameraId":   stringValue(shot["cameraId"]),
+			"shotSize":   stringValue(shot["shotSize"]),
+			"cameraMove": stringValue(shot["cameraMove"]),
+			"duration":   shot["duration"],
+		})
+	}
+
+	return map[string]any{
+		"objects": objLayouts,
+		"cameras": camLayouts,
+		"shots":   shotLayouts,
+	}
+}
+
+func cloudAgentPrevisPreview(repo *repository.Repository, userID, canvasID string, call cloudAgentCall) (any, error) {
 	var args struct {
 		SceneID  string   `json:"sceneId"`
 		ShotID   string   `json:"shotId"`
@@ -118,11 +211,11 @@ func cloudAgentDirectorPreview(repo *repository.Repository, userID, canvasID str
 	if err != nil {
 		return nil, err
 	}
-	scene, ok := findDirectorScene(creationMaps(doc["directorScenes"]), args.SceneID)
+	scene, ok := findPrevisScene(creationMaps(doc["previsScenes"]), args.SceneID)
 	if !ok {
 		return nil, BadAuthRequest("导演场景不存在或不属于当前画布")
 	}
-	shot, ok := findDirectorShot(scene, args.ShotID)
+	shot, ok := findPrevisShot(scene, args.ShotID)
 	if !ok {
 		return nil, BadAuthRequest("导演镜头不存在或不属于指定场景")
 	}
@@ -136,7 +229,7 @@ func cloudAgentDirectorPreview(repo *repository.Repository, userID, canvasID str
 	}
 	requestID := strings.TrimSpace(call.ID)
 	if requestID == "" {
-		requestID = fmt.Sprintf("director-preview-%s-%s", args.SceneID, args.ShotID)
+		requestID = fmt.Sprintf("previs-preview-%s-%s", args.SceneID, args.ShotID)
 	}
 	return map[string]any{
 		"previewRequestId": requestID,
@@ -149,12 +242,12 @@ func cloudAgentDirectorPreview(repo *repository.Repository, userID, canvasID str
 		"fps":              fps,
 		"output":           "clay_video",
 		"snapshotHash":     creationHash(scene),
-		"execution":        "browser_director_viewport",
-		"text":             "已请求导演台在浏览器视口录制白模预演；录制完成后会回写为画布视频节点。",
+		"execution":        "browser_previs_viewport",
+		"text":             "已请求预演台在浏览器视口录制白模预演；录制完成后会回写为画布视频节点。",
 	}, nil
 }

-func findDirectorScene(scenes []map[string]any, id string) (map[string]any, bool) {
+func findPrevisScene(scenes []map[string]any, id string) (map[string]any, bool) {
 	for _, scene := range scenes {
 		if stringValue(scene["id"]) == id {
 			return scene, true
@@ -163,7 +256,7 @@ func findDirectorScene(scenes []map[string]any, id string) (map[string]any, bool
 	return nil, false
 }

-func findDirectorShot(scene map[string]any, id string) (map[string]any, bool) {
+func findPrevisShot(scene map[string]any, id string) (map[string]any, bool) {
 	for _, shot := range creationMaps(scene["shots"]) {
 		if stringValue(shot["id"]) == id {
 			return shot, true
@@ -172,7 +265,7 @@ func findDirectorShot(scene map[string]any, id string) (map[string]any, bool) {
 	return nil, false
 }

-func projectDirectorScene(scene map[string]any, shotID string, objectIDs map[string]bool) map[string]any {
+func projectPrevisScene(scene map[string]any, shotID string, objectIDs map[string]bool) map[string]any {
 	shots := make([]map[string]any, 0)
 	for _, shot := range creationMaps(scene["shots"]) {
 		if shotID != "" && stringValue(shot["id"]) != shotID {
@@ -202,7 +295,7 @@ func projectDirectorScene(scene map[string]any, shotID string, objectIDs map[str
 			"color":     stringValue(object["color"]),
 			"pose":      stringValue(object["pose"]),
 			"visible":   boolValue(object["visible"], true),
-			"transform": projectDirectorTransform(object["transform"]),
+			"transform": projectPrevisTransform(object["transform"]),
 		})
 	}
 	cameras := make([]map[string]any, 0)
@@ -211,8 +304,8 @@ func projectDirectorScene(scene map[string]any, shotID string, objectIDs map[str
 			"id":          stringValue(camera["id"]),
 			"name":        truncateRunes(stringValue(camera["name"]), 160),
 			"focalLength": numberValue(camera["focalLength"], 50),
-			"transform":   projectDirectorTransform(camera["transform"]),
-			"target":      projectDirectorVec3(camera["target"]),
+			"transform":   projectPrevisTransform(camera["transform"]),
+			"target":      projectPrevisVec3(camera["target"]),
 		})
 	}
 	return map[string]any{
@@ -226,16 +319,16 @@ func projectDirectorScene(scene map[string]any, shotID string, objectIDs map[str
 	}
 }

-func projectDirectorTransform(value any) map[string]any {
+func projectPrevisTransform(value any) map[string]any {
 	transform, _ := value.(map[string]any)
 	return map[string]any{
-		"position": projectDirectorVec3(transform["position"]),
-		"rotation": projectDirectorVec3(transform["rotation"]),
-		"scale":    projectDirectorVec3(transform["scale"]),
+		"position": projectPrevisVec3(transform["position"]),
+		"rotation": projectPrevisVec3(transform["rotation"]),
+		"scale":    projectPrevisVec3(transform["scale"]),
 	}
 }

-func projectDirectorVec3(value any) []any {
+func projectPrevisVec3(value any) []any {
 	items, ok := value.([]any)
 	if !ok || len(items) != 3 {
 		return []any{0, 0, 0}
--- a/backend/internal/app/cloud_agent_previs_mutation.go
+++ b/backend/internal/app/cloud_agent_previs_mutation.go
--- a/backend/internal/app/cloud_agent_previs_mutation_test.go
+++ b/backend/internal/app/cloud_agent_previs_mutation_test.go
@@ -0,0 +1,543 @@
+package app
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"infinite-canvas/backend/internal/model"
+)
+
+func previsMutationFixture(t *testing.T) (*Service, *model.CanvasProject) {
+	t.Helper()
+	s, db, _, _ := creationTestService(t)
+	canvas := &model.CanvasProject{
+		ID:          "previs-canvas",
+		UserID:      "user",
+		Title:       "预演测试画布",
+		PayloadJSON: `{"nodes":[],"connections":[],"previsScenes":[]}`,
+	}
+	if err := db.Create(canvas).Error; err != nil {
+		t.Fatal(err)
+	}
+	return s, canvas
+}
+
+func previsMutationCall(t *testing.T, id, name string, args any) cloudAgentCall {
+	t.Helper()
+	raw, err := json.Marshal(args)
+	if err != nil {
+		t.Fatal(err)
+	}
+	call := cloudAgentCall{ID: id}
+	call.Function.Name = name
+	call.Function.Arguments = string(raw)
+	return call
+}
+
+func previsResultString(t *testing.T, result any, key string) string {
+	t.Helper()
+	payload, ok := result.(map[string]any)
+	if !ok {
+		t.Fatalf("result is not an object: %#v", result)
+	}
+	value, ok := payload[key].(string)
+	if !ok || value == "" {
+		t.Fatalf("result.%s = %#v", key, payload[key])
+	}
+	return value
+}
+
+func TestCloudAgentPrevisSceneCreateAndPatchKeepSemanticAndCanvasHashesSeparate(t *testing.T) {
+	s, canvas := previsMutationFixture(t)
+	req := agentTestRequest()
+	req.CanvasID = canvas.ID
+	req.PermissionMode = "auto"
+	run, err := s.CreateCloudAgentRun("user", req, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	policy, err := s.RuntimePolicy()
+	if err != nil {
+		t.Fatal(err)
+	}
+	beforeDoc, err := creationDocument(canvas.PayloadJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	beforeCanvasHash := cloudAgentCanvasHash(beforeDoc)
+	createCall := previsMutationCall(t, "previs-create-1", "previs_scene_create", map[string]any{
+		"canvasSnapshotHash": beforeCanvasHash,
+		"sceneId":            "scene-1",
+		"title":              "客厅对白",
+		"templateId":         "dialogue",
+	})
+	createResult, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, createCall, policy, cloudAgentMutationRecorderForRun(run.ID))
+	if err != nil {
+		t.Fatal(err)
+	}
+	createdSceneHash := previsResultString(t, createResult, "snapshotHash")
+	createdCanvasHash := previsResultString(t, createResult, "canvasSnapshotHash")
+	if createdCanvasHash == beforeCanvasHash || createdSceneHash == createdCanvasHash {
+		t.Fatalf("scene and canvas hashes were not separated: scene=%s canvas=%s before=%s", createdSceneHash, createdCanvasHash, beforeCanvasHash)
+	}
+
+	stored, err := s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	createdDoc, err := creationDocument(stored.PayloadJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	scene, ok := findPrevisScene(creationMaps(createdDoc["previsScenes"]), "scene-1")
+	if !ok {
+		t.Fatal("created scene missing")
+	}
+	if creationHash(scene) != createdSceneHash || cloudAgentCanvasHash(createdDoc) != createdCanvasHash {
+		t.Fatalf("returned hashes do not match persisted values: scene=%s/%s canvas=%s/%s", createdSceneHash, creationHash(scene), createdCanvasHash, cloudAgentCanvasHash(createdDoc))
+	}
+
+	patchCall := previsMutationCall(t, "previs-patch-1", "previs_apply_patch", map[string]any{
+		"snapshotHash": createdSceneHash,
+		"sceneId":      "scene-1",
+		"operations": []map[string]any{{
+			"type":      "object_add",
+			"id":        "actor-1",
+			"kind":      "actor",
+			"primitive": "character",
+			"name":      "演员甲",
+			"position":  []float64{0, 0, 0},
+			"color":     "#f1f3f5",
+		}},
+	})
+	patchResult, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, patchCall, policy, cloudAgentMutationRecorderForRun(run.ID))
+	if err != nil {
+		t.Fatal(err)
+	}
+	patchedSceneHash := previsResultString(t, patchResult, "snapshotHash")
+	patchedCanvasHash := previsResultString(t, patchResult, "canvasSnapshotHash")
+	if patchedSceneHash == createdSceneHash || patchedCanvasHash == createdCanvasHash {
+		t.Fatalf("patch did not advance both hashes: scene=%s->%s canvas=%s->%s", createdSceneHash, patchedSceneHash, createdCanvasHash, patchedCanvasHash)
+	}
+
+	stored, err = s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	patchedDoc, err := creationDocument(stored.PayloadJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	patchedScene, _ := findPrevisScene(creationMaps(patchedDoc["previsScenes"]), "scene-1")
+	if creationHash(patchedScene) != patchedSceneHash || cloudAgentCanvasHash(patchedDoc) != patchedCanvasHash {
+		t.Fatalf("patch hashes do not match persisted values")
+	}
+	if cloudAgentPrevisFindByID(creationMaps(patchedScene["objects"]), "actor-1") == nil {
+		t.Fatalf("semantic patch did not add actor: %#v", patchedScene["objects"])
+	}
+
+	mutation, err := s.repo.LatestCloudAgentCanvasMutation("user", run.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mutation.Operation != "previs_apply_patch" || mutation.BeforeSnapshotHash != createdCanvasHash || mutation.AfterSnapshotHash != patchedCanvasHash {
+		t.Fatalf("mutation recorded scene hash instead of canvas hash: %+v", mutation)
+	}
+	undoResult, err := s.UndoCloudAgentCanvas("user", run.ID, patchCall.ID, patchedCanvasHash, "测试撤销")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if undoResult["accepted"] != true || undoResult["snapshotHash"] != createdCanvasHash {
+		t.Fatalf("unexpected previs undo result: %+v", undoResult)
+	}
+}
+
+func TestCloudAgentPrevisRejectsStaleSnapshotsAndCrossUserCanvas(t *testing.T) {
+	s, canvas := previsMutationFixture(t)
+	doc, err := creationDocument(canvas.PayloadJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	staleCreate := previsMutationCall(t, "stale-create", "previs_scene_create", map[string]any{
+		"canvasSnapshotHash": strings.Repeat("0", 64),
+		"sceneId":            "scene-stale",
+		"title":              "过期",
+		"templateId":         "empty",
+	})
+	_, err = prepareCloudAgentPrevisSceneCreate(s.repo, "user", canvas.ID, staleCreate)
+	var appErr *AppError
+	if !errors.As(err, &appErr) || appErr.Status != 409 {
+		t.Fatalf("stale canvas snapshot should conflict, got %v", err)
+	}
+
+	validCreate := previsMutationCall(t, "create-for-stale-patch", "previs_scene_create", map[string]any{
+		"canvasSnapshotHash": cloudAgentCanvasHash(doc),
+		"sceneId":            "scene-stale",
+		"title":              "场景",
+		"templateId":         "empty",
+	})
+	policy, err := s.RuntimePolicy()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, validCreate, policy); err != nil {
+		t.Fatal(err)
+	}
+	stored, err := s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	storedDoc, _ := creationDocument(stored.PayloadJSON)
+	scene, _ := findPrevisScene(creationMaps(storedDoc["previsScenes"]), "scene-stale")
+	patch := previsMutationCall(t, "stale-patch", "previs_apply_patch", map[string]any{
+		"snapshotHash": strings.Repeat("1", 64),
+		"sceneId":      "scene-stale",
+		"operations":   []map[string]any{{"type": "scene_update", "id": "scene-stale", "title": "不应写入"}},
+	})
+	_, err = prepareCloudAgentPrevisApplyPatch(s.repo, "user", canvas.ID, patch)
+	if !errors.As(err, &appErr) || appErr.Status != 409 {
+		t.Fatalf("stale scene snapshot should conflict, got %v", err)
+	}
+	if stringValue(scene["title"]) != "场景" {
+		t.Fatalf("stale patch mutated scene in memory or persistence: %#v", scene)
+	}
+
+	_, err = prepareCloudAgentPrevisSceneCreate(s.repo, "other-user", canvas.ID, validCreate)
+	if err == nil {
+		t.Fatal("cross-user canvas access was accepted")
+	}
+}
+
+func TestCloudAgentPrevisNormalizesLegacyCSSColorsBeforeValidation(t *testing.T) {
+	scene := map[string]any{
+		"id": "scene", "version": 1, "title": "场景", "background": "rgb(255, 70, 74)", "environmentIntensity": 0.7,
+		"objects":      []any{map[string]any{"id": "object", "name": "球体", "kind": "primitive", "primitive": "sphere", "color": "rgb(255,70,74)", "transform": map[string]any{"position": []any{0, 0, 0}, "rotation": []any{0, 0, 0}, "scale": []any{1, 1, 1}}}},
+		"cameras":      []any{map[string]any{"id": "camera", "name": "摄影机", "focalLength": 35, "target": []any{0, 1, 0}, "transform": map[string]any{"position": []any{0, 1, 3}, "rotation": []any{0, 0, 0}, "scale": []any{1, 1, 1}}}},
+		"lights":       []any{map[string]any{"id": "light", "name": "主光", "type": "point", "color": "rgba(255, 255, 255, 0.5)", "intensity": 1, "transform": map[string]any{"position": []any{0, 2, 0}, "rotation": []any{0, 0, 0}, "scale": []any{1, 1, 1}}}},
+		"shots":        []any{map[string]any{"id": "shot", "name": "镜头 1", "cameraId": "camera", "duration": 5, "fps": 24, "shotSize": "medium", "cameraMove": "static", "prompt": ""}},
+		"activeShotId": "shot",
+	}
+	if err := cloudAgentPrevisValidateScene(scene); err != nil {
+		t.Fatal(err)
+	}
+	if got := scene["background"]; got != "#ff464a" {
+		t.Fatalf("background = %#v, want #ff464a", got)
+	}
+	object := creationMaps(scene["objects"])[0]
+	if got := object["color"]; got != "#ff464a" {
+		t.Fatalf("object color = %#v, want #ff464a", got)
+	}
+	light := creationMaps(scene["lights"])[0]
+	if got := light["color"]; got != "#ffffff80" {
+		t.Fatalf("light color = %#v, want #ffffff80", got)
+	}
+}
+
+func TestCloudAgentPrevisColorSchemaRejectsNonHexInput(t *testing.T) {
+	if err := cloudAgentPrevisValidateColor("rgb(255,70,74)", "对象颜色"); err == nil {
+		t.Fatal("non-hex agent color was accepted")
+	}
+	if err := cloudAgentPrevisValidateColor("#ff464a", "对象颜色"); err != nil {
+		t.Fatalf("valid hex agent color rejected: %v", err)
+	}
+}
+
+func TestCloudAgentPrevisCatalogReadAndToolPermissions(t *testing.T) {
+	s, canvas := previsMutationFixture(t)
+	catalogCall := cloudAgentCall{ID: "catalog"}
+	catalogCall.Function.Name = "previs_scene_read"
+	catalogCall.Function.Arguments = `{}`
+	result, err := cloudAgentPrevisSceneRead(s.repo, "user", canvas.ID, catalogCall)
+	if err != nil {
+		t.Fatal(err)
+	}
+	catalog, ok := result.(map[string]any)
+	if !ok || catalog["canvasSnapshotHash"] != cloudAgentCanvasHash(mustCreationDocument(t, canvas.PayloadJSON)) {
+		t.Fatalf("catalog did not return a usable canvasSnapshotHash: %#v", result)
+	}
+
+	readOnly := CloudAgentRequest{PermissionMode: "read_only", ContextScope: []string{"canvas"}}
+	if !cloudAgentToolAllowed(readOnly, "previs_scene_read") {
+		t.Fatal("read-only mode lost semantic Previs read")
+	}
+	if cloudAgentToolAllowed(readOnly, "previs_scene_create") || cloudAgentToolAllowed(readOnly, "previs_apply_patch") {
+		t.Fatal("read-only mode exposed Previs writes")
+	}
+	auto := CloudAgentRequest{PermissionMode: "auto", ContextScope: []string{"canvas"}}
+	if !cloudAgentToolAllowed(auto, "previs_scene_create") || !cloudAgentToolAllowed(auto, "previs_apply_patch") {
+		t.Fatal("auto mode did not expose Previs writes")
+	}
+	_ = s
+}
+
+func TestCloudAgentPrevisPatchLimitsAndClosedArguments(t *testing.T) {
+	call := cloudAgentCall{ID: "invalid"}
+	call.Function.Name = "previs_apply_patch"
+	call.Function.Arguments = `{"snapshotHash":"snapshot","sceneId":"scene","operations":[{"type":"scene_update","id":"scene","rawScene":{"nodes":[]}}]}`
+	var args cloudAgentPrevisApplyPatchArgs
+	if err := decodeCloudAgentJSONObject(call.Function.Arguments, &args); err == nil {
+		t.Fatal("raw scene replacement field was accepted")
+	}
+
+	operations := make([]map[string]any, cloudAgentPrevisMaxOperations+1)
+	for index := range operations {
+		operations[index] = map[string]any{"type": "scene_update", "id": "scene"}
+	}
+	call = previsMutationCall(t, "too-many", "previs_apply_patch", map[string]any{"snapshotHash": "snapshot", "sceneId": "scene", "operations": operations})
+	if _, err := prepareCloudAgentPrevisApplyPatch(nil, "user", "canvas", call); err == nil {
+		t.Fatal("oversized Previs patch was accepted")
+	}
+
+	if _, err := cloudAgentPrevisSceneCreateTemplate(cloudAgentPrevisSceneCreateArgs{SceneID: "scene", Title: "场景", TemplateID: "unknown"}); err == nil {
+		t.Fatal("unknown Previs template was accepted")
+	}
+}
+
+func TestCloudAgentPrevisCharacterBindingAndAnimationPatch(t *testing.T) {
+	s, canvas := previsMutationFixture(t)
+	canvas.PayloadJSON = `{"nodes":[{"id":"hero-card","type":"text","metadata":{"workflowKind":"character","characterAssetId":"hero-asset","characterVersionId":"hero-v1"}}],"connections":[],"previsScenes":[]}`
+	if err := s.repo.Save(canvas); err != nil {
+		t.Fatal(err)
+	}
+	policy, err := s.RuntimePolicy()
+	if err != nil {
+		t.Fatal(err)
+	}
+	doc, err := creationDocument(canvas.PayloadJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	create := previsMutationCall(t, "binding-create", "previs_scene_create", map[string]any{
+		"canvasSnapshotHash": cloudAgentCanvasHash(doc), "sceneId": "binding-scene", "title": "绑定动画", "templateId": "empty",
+	})
+	if _, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, create, policy); err != nil {
+		t.Fatal(err)
+	}
+	stored, err := s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	storedDoc, _ := creationDocument(stored.PayloadJSON)
+	scene, _ := findPrevisScene(creationMaps(storedDoc["previsScenes"]), "binding-scene")
+	sceneHash := creationHash(scene)
+	patch := previsMutationCall(t, "binding-patch", "previs_apply_patch", map[string]any{
+		"snapshotHash": sceneHash, "sceneId": "binding-scene", "operations": []map[string]any{
+			{"type": "object_add", "id": "hero-actor", "kind": "actor", "primitive": "character", "name": "主角", "characterAssetId": "hero-asset", "characterVersionId": "hero-v1", "referenceNodeId": "hero-card", "characterName": "主角", "position": []float64{0, 0, 0}},
+		},
+	})
+	result, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, patch, policy)
+	if err != nil {
+		t.Fatal(err)
+	}
+	stored, err = s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	storedDoc, _ = creationDocument(stored.PayloadJSON)
+	scene, _ = findPrevisScene(creationMaps(storedDoc["previsScenes"]), "binding-scene")
+	actor := cloudAgentPrevisFindByID(creationMaps(scene["objects"]), "hero-actor")
+	binding, ok := actor["characterBinding"].(map[string]any)
+	if !ok || stringValue(binding["characterAssetId"]) != "hero-asset" || stringValue(actor["sourceNodeId"]) != "hero-card" {
+		t.Fatalf("character binding was not persisted: %#v", actor)
+	}
+
+	animationPatch := previsMutationCall(t, "animation-patch", "previs_apply_patch", map[string]any{
+		"snapshotHash": previsResultString(t, result, "snapshotHash"), "sceneId": "binding-scene", "operations": []map[string]any{
+			{"type": "object_keyframe_upsert", "id": "hero-actor", "time": 2, "position": []float64{1, 0, 0}, "easing": "smooth"},
+			{"type": "object_motion_path_set", "id": "hero-actor", "pathPoints": [][]float64{{0, 0, 0}, {1, 0, 0}, {2, 0, 0}}, "pathSpeed": "walk", "orientToPath": true},
+		},
+	})
+	if _, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, animationPatch, policy); err != nil {
+		t.Fatal(err)
+	}
+	stored, err = s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	storedDoc, _ = creationDocument(stored.PayloadJSON)
+	scene, _ = findPrevisScene(creationMaps(storedDoc["previsScenes"]), "binding-scene")
+	actor = cloudAgentPrevisFindByID(creationMaps(scene["objects"]), "hero-actor")
+	if len(creationMaps(actor["keyframes"])) != 1 || actor["motionPath"] == nil {
+		t.Fatalf("animation patch was not persisted: %#v", actor)
+	}
+}
+
+func TestCloudAgentPrevisRejectsMismatchedCharacterBinding(t *testing.T) {
+	s, canvas := previsMutationFixture(t)
+	canvas.PayloadJSON = `{"nodes":[{"id":"hero-card","type":"text","metadata":{"workflowKind":"character","characterAssetId":"hero-asset","characterVersionId":"hero-v1"}}],"connections":[],"previsScenes":[]}`
+	if err := s.repo.Save(canvas); err != nil {
+		t.Fatal(err)
+	}
+	policy, err := s.RuntimePolicy()
+	if err != nil {
+		t.Fatal(err)
+	}
+	doc, _ := creationDocument(canvas.PayloadJSON)
+	create := previsMutationCall(t, "mismatch-create", "previs_scene_create", map[string]any{"canvasSnapshotHash": cloudAgentCanvasHash(doc), "sceneId": "mismatch-scene", "title": "错误绑定", "templateId": "empty"})
+	if _, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, create, policy); err != nil {
+		t.Fatal(err)
+	}
+	stored, _ := s.repo.CanvasProjectForUser("user", canvas.ID)
+	storedDoc, _ := creationDocument(stored.PayloadJSON)
+	scene, _ := findPrevisScene(creationMaps(storedDoc["previsScenes"]), "mismatch-scene")
+	patch := previsMutationCall(t, "mismatch-patch", "previs_apply_patch", map[string]any{"snapshotHash": creationHash(scene), "sceneId": "mismatch-scene", "operations": []map[string]any{{"type": "object_add", "id": "bad-actor", "kind": "actor", "characterAssetId": "other-asset", "characterVersionId": "hero-v1", "referenceNodeId": "hero-card"}}})
+	if _, err := applyCloudAgentPrevisMutation(s.repo, "user", canvas.ID, patch, policy); err == nil {
+		t.Fatal("mismatched character binding was accepted")
+	}
+}
+func TestCloudAgentPrevisAnimationOperationsRespectShotDurationAndRemoval(t *testing.T) {
+	scene, err := cloudAgentPrevisSceneCreateTemplate(cloudAgentPrevisSceneCreateArgs{SceneID: "animation-scene", Title: "动画边界", TemplateID: "monologue"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	actor := cloudAgentPrevisFindByID(creationMaps(scene["objects"]), "animation-scene-actor-1")
+	camera := cloudAgentPrevisFindByID(creationMaps(scene["cameras"]), "animation-scene-camera-1")
+	if actor == nil || camera == nil {
+		t.Fatal("animation fixture is missing actor or camera")
+	}
+
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{
+		Type: "object_keyframe_upsert", ID: actor["id"].(string), Time: float64Ptr(5), Position: vec3Ptr([]float64{1, 0, 0}),
+	}, 0); err != nil {
+		t.Fatalf("object keyframe at shot end rejected: %v", err)
+	}
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{
+		Type: "camera_keyframe_upsert", ID: camera["id"].(string), Time: float64Ptr(5), Position: vec3Ptr([]float64{2, 1, 4}),
+	}, 1); err != nil {
+		t.Fatalf("camera keyframe at shot end rejected: %v", err)
+	}
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{
+		Type: "object_motion_path_set", ID: actor["id"].(string), PathPoints: [][]float64{{0, 0, 0}, {1, 0, 0}}, StartDelay: float64Ptr(5),
+	}, 2); err != nil {
+		t.Fatalf("motion path at shot end rejected: %v", err)
+	}
+
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{
+		Type: "object_keyframe_upsert", ID: actor["id"].(string), Time: float64Ptr(5.01), Position: vec3Ptr([]float64{2, 0, 0}),
+	}, 3); err == nil {
+		t.Fatal("object keyframe beyond active shot duration was accepted")
+	}
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{
+		Type: "camera_keyframe_upsert", ID: camera["id"].(string), Time: float64Ptr(5.01), Position: vec3Ptr([]float64{3, 1, 4}),
+	}, 4); err == nil {
+		t.Fatal("camera keyframe beyond active shot duration was accepted")
+	}
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{
+		Type: "object_motion_path_set", ID: actor["id"].(string), PathPoints: [][]float64{{0, 0, 0}, {1, 0, 0}}, StartDelay: float64Ptr(5.01),
+	}, 5); err == nil {
+		t.Fatal("motion path beyond active shot duration was accepted")
+	}
+
+	objectKeyframeID := stringValue(creationMaps(actor["keyframes"])[0]["id"])
+	cameraKeyframeID := stringValue(creationMaps(camera["keyframes"])[0]["id"])
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{Type: "object_keyframe_remove", ID: actor["id"].(string), KeyframeID: previsStringPtr(objectKeyframeID)}, 6); err != nil {
+		t.Fatalf("object keyframe removal failed: %v", err)
+	}
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{Type: "camera_keyframe_remove", ID: camera["id"].(string), KeyframeID: previsStringPtr(cameraKeyframeID)}, 7); err != nil {
+		t.Fatalf("camera keyframe removal failed: %v", err)
+	}
+	if _, err := cloudAgentPrevisApplyPatchOperation(scene, cloudAgentPrevisPatchOperation{Type: "object_motion_path_clear", ID: actor["id"].(string)}, 8); err != nil {
+		t.Fatalf("motion path clear failed: %v", err)
+	}
+	if len(creationMaps(actor["keyframes"])) != 0 || len(creationMaps(camera["keyframes"])) != 0 || actor["motionPath"] != nil {
+		t.Fatalf("animation removal did not clear state: actor=%#v camera=%#v", actor, camera)
+	}
+}
+
+func float64Ptr(value float64) *float64 { return &value }
+
+func previsStringPtr(value string) *string { return &value }
+
+func vec3Ptr(value []float64) *[]float64 { return &value }
+
+func TestCloudAgentPrevisApprovalRoundTripUsesSharedAgentGate(t *testing.T) {
+	s, db, _, _ := creationTestService(t)
+	canvas := model.CanvasProject{ID: "agent-canvas", UserID: "user", PayloadJSON: `{"nodes":[],"connections":[],"previsScenes":[]}`}
+	if err := db.Create(&canvas).Error; err != nil {
+		t.Fatal(err)
+	}
+	req := agentTestRequest()
+	req.PermissionMode = "request_approval"
+	root, err := s.CreateCloudAgentRun("user", req, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	load := func() (*model.CloudAgentExecution, cloudAgentRuntime) {
+		t.Helper()
+		run, err := s.repo.CloudAgent("user", root.ID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		state, err := cloudAgentDecode(run)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return run, state
+	}
+	advance := func() {
+		t.Helper()
+		if err := s.advanceCloudAgentByID("user", root.ID); err != nil {
+			t.Fatal(err)
+		}
+	}
+	_, initialState := load()
+	if initialState.ActiveTaskID == "" {
+		t.Fatal("missing continuation model task")
+	}
+	doc, err := creationDocument(canvas.PayloadJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	call := previsMutationCall(t, "approval-previs-create", "previs_scene_create", map[string]any{
+		"canvasSnapshotHash": cloudAgentCanvasHash(doc),
+		"sceneId":            "approval-scene",
+		"title":              "审批场景",
+		"templateId":         "empty",
+	})
+	body, err := json.Marshal(map[string]any{"toolCalls": []cloudAgentCall{call}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Model(&model.Task{}).Where("id = ?", initialState.ActiveTaskID).Updates(map[string]any{
+		"status":      model.TaskStatusSucceeded,
+		"result_json": string(body),
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+	advance()
+	advance()
+	waiting, state := load()
+	if waiting.Status != "waiting_approval" || state.Approval == nil {
+		t.Fatalf("Previs write did not enter approval: status=%s approval=%+v", waiting.Status, state.Approval)
+	}
+	if state.Approval.CallHash != cloudAgentApprovalCallHash(call) {
+		t.Fatalf("approval hash does not bind the original Previs call: got=%s want=%s", state.Approval.CallHash, cloudAgentApprovalCallHash(call))
+	}
+	before := canvas.PayloadJSON
+	if err := s.DecideCloudAgentApproval("user", root.ID, state.Approval.ID, "approve", "确认预演场景"); err != nil {
+		t.Fatal(err)
+	}
+	advance()
+	stored, err := s.repo.CanvasProjectForUser("user", canvas.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stored.PayloadJSON == before {
+		t.Fatal("approved Previs write did not persist")
+	}
+	storedDoc, _ := creationDocument(stored.PayloadJSON)
+	if _, ok := findPrevisScene(creationMaps(storedDoc["previsScenes"]), "approval-scene"); !ok {
+		t.Fatal("approved Previs scene missing")
+	}
+}
+
+func mustCreationDocument(t *testing.T, raw string) map[string]any {
+	t.Helper()
+	doc, err := creationDocument(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return doc
+}
--- a/backend/internal/app/cloud_agent_director_test.go
+++ b/backend/internal/app/cloud_agent_director_test.go
@@ -2,7 +2,7 @@ package app

 import "testing"

-func TestProjectDirectorSceneReturnsSafeSemanticProjection(t *testing.T) {
+func TestProjectPrevisSceneReturnsSafeSemanticProjection(t *testing.T) {
 	scene := map[string]any{
 		"id":           "scene-1",
 		"title":        "客厅",
@@ -46,7 +46,7 @@ func TestProjectDirectorSceneReturnsSafeSemanticProjection(t *testing.T) {
 		"lights": []any{map[string]any{"id": "light-1"}},
 	}

-	projected := projectDirectorScene(scene, "shot-1", map[string]bool{})
+	projected := projectPrevisScene(scene, "shot-1", map[string]bool{})
 	shots, ok := projected["shots"].([]map[string]any)
 	if !ok || len(shots) != 1 {
 		t.Fatalf("shots projection = %#v", projected["shots"])
--- a/backend/internal/app/cloud_agent_runtime_tools.go
+++ b/backend/internal/app/cloud_agent_runtime_tools.go
@@ -154,7 +154,7 @@ func cloudAgentCompactSupersededReadResult(state *cloudAgentRuntime, current clo
 	if state == nil || !cloudAgentReadToolCacheable(current.Function.Name) {
 		return
 	}
-	if current.Function.Name != "canvas_get_state" && current.Function.Name != "canvas_read_storyboard" && current.Function.Name != "director_scene_read" {
+	if current.Function.Name != "canvas_get_state" && current.Function.Name != "canvas_read_storyboard" && current.Function.Name != "previs_scene_read" {
 		return
 	}
 	currentKey := cloudAgentReadCacheKey(current)
@@ -234,7 +234,7 @@ func cloudAgentCompactSupersededReadBody(content, toolName string) string {
 			delete(result, "rows")
 			removed = true
 		}
-	case "director_scene_read":
+	case "previs_scene_read":
 		for _, key := range []string{"content", "shots", "scenes"} {
 			if _, exists := result[key]; exists {
 				delete(result, key)
@@ -579,6 +579,18 @@ func (s *Service) advanceCloudAgentTool(run *model.CloudAgentExecution, state *c
 					if err == nil {
 						preview = batchPlan.Preview
 					}
+				case "previs_scene_create":
+					previsPlan, err := prepareCloudAgentPrevisSceneCreate(repo, run.UserID, state.Request.CanvasID, call)
+					mutationErr = err
+					if err == nil {
+						preview = previsPlan.Preview
+					}
+				case "previs_apply_patch":
+					previsPlan, err := prepareCloudAgentPrevisApplyPatch(repo, run.UserID, state.Request.CanvasID, call)
+					mutationErr = err
+					if err == nil {
+						preview = previsPlan.Preview
+					}
 				case "canvas_arrange_nodes":
 					arrangePlan, err := prepareCloudAgentArrangeNodes(repo, run.UserID, state.Request.CanvasID, call)
 					mutationErr = err
@@ -682,6 +694,8 @@ func (s *Service) advanceCloudAgentTool(run *model.CloudAgentExecution, state *c
 			result, toolErr = applyCloudAgentCharacterCreate(repo, run.UserID, state.Request.CanvasID, call, policy, cloudAgentCanvasEventRecorder(run.ID, state))
 		case call.Function.Name == "canvas_edit_batch_table":
 			result, toolErr = applyCloudAgentBatchTableMutation(repo, run.UserID, state.Request.CanvasID, call, policy, cloudAgentCanvasEventRecorder(run.ID, state))
+		case call.Function.Name == "previs_scene_create", call.Function.Name == "previs_apply_patch":
+			result, toolErr = applyCloudAgentPrevisMutation(repo, run.UserID, state.Request.CanvasID, call, policy, cloudAgentCanvasEventRecorder(run.ID, state))
 		case call.Function.Name == "canvas_inspect_image":
 			result, toolErr = inspectionResult, inspectionErr
 			if toolErr == nil && inspectionResult != nil {
--- a/backend/internal/app/cloud_agent_test.go
+++ b/backend/internal/app/cloud_agent_test.go
@@ -522,7 +522,7 @@ func TestCloudAgentToolLoopPersistsApprovalAndAppliesCanvasWrite(t *testing.T) {
 	}
 	callArguments, err := json.Marshal(map[string]any{
 		"snapshotHash": cloudAgentCanvasHash(doc),
-		"ops":          []map[string]any{{"type": "add_node", "id": "agent-note", "nodeType": "text", "title": "Agent note", "content": "由 Agent 写入", "x": 24, "y": 48}},
+		"ops":          []map[string]any{{"type": "add_node", "id": "agent-note", "nodeType": "text", "title": "Agent note", "content": "由 Agent 写入", "x": json.RawMessage("24.0"), "y": json.RawMessage("48.0")}},
 	})
 	if err != nil {
 		t.Fatal(err)
--- a/backend/internal/app/cloud_agent_tool_schema_budget_test.go
+++ b/backend/internal/app/cloud_agent_tool_schema_budget_test.go
@@ -54,10 +54,11 @@ func TestCloudAgentToolSchemaStaysCompact(t *testing.T) {

 	// 体积预算：导演台、技能检索和上下文读取工具合入后为 24 个工具、27,812 字节，预算 29,000。
 	// 之后能力注册表加入角色卡（图片/视频/音频接受 character 输入）到 28,979 字节；再新增
-	// canvas_create_character（角色卡打包创建，设定字段已压成一行描述）后为 25 个工具、实测
-	// 29,938 字节，因此显式上调到 30,500（约 1.9% 余量）。新增工具或字段时请重新测量并
-	// 有意识地调整这个数字，而不是让 schema 悄悄膨胀（它每一步都要发、还在前缀最前面）。
-	if len(raw) > 30500 {
-		t.Fatalf("平台工具 schema 体积 %d 字节超出预算 30500：请压缩描述或显式调整预算", len(raw))
+	// canvas_create_character（角色卡打包创建，设定字段已压成一行描述）后为 25 个工具、29,938
+	// 字节；本轮加入 previs_scene_create 与 previs_apply_patch 后为 27 个工具、34,171 字节，
+	// 因此显式上调到 35,000，并保留约2.4%的余量。新增工具或字段时请重新测量并有意识地
+	// 调整这个数字，而不是让 schema 悄悄膨胀（它每一步都要发、还在前缀最前面）。
+	if len(raw) > 35000 {
+		t.Fatalf("平台工具 schema 体积 %d 字节超出预算 35000：请压缩描述或显式调整预算", len(raw))
 	}
 }
--- a/backend/internal/app/cloud_agent_tools.go
+++ b/backend/internal/app/cloud_agent_tools.go
@@ -123,20 +123,25 @@ func compileCloudAgentTools(req CloudAgentRequest, includeProfileTool bool) []ma
 		},
 		"question")
 	if len(req.ContextScope) > 0 {
-		add("director_scene_read", "读取当前画布的导演台白模场景摘要。只返回场景、镜头、演员、道具和空间关系所需的安全字段，不返回模型 URL、存储 key、密钥或完整导演场景 JSON；先读再编辑/预演。", map[string]any{
-			"sceneId":   str("可选的导演场景 ID；省略时返回场景目录"),
-			"shotId":    str("可选的镜头 ID；用于精读某个镜头"),
-			"objectIds": map[string]any{"type": "array", "maxItems": 16, "items": str("可选的演员或道具 ID")},
+		add("previs_scene_read", "读取预演摘要；无 sceneId 返回目录和 canvasSnapshotHash，有则返回场景与 snapshotHash。includeTransforms=true 返回坐标；不返回 URL/storage key。", map[string]any{
+			"sceneId":           str("可选。省略返回目录；提供则精读该场景"),
+			"shotId":            str("可选。精读特定镜头；需同时提供 sceneId"),
+			"objectIds":         map[string]any{"type": "array", "maxItems": 16, "items": str("可选。精读特定对象 ID")},
+			"includeTransforms": map[string]any{"type": "boolean"},
 		})
 		if req.PermissionMode != "read_only" {
-			add("director_preview", "请求当前导演台生成白模预演视频。只作用于已打开的导演台场景，不生成真实成片；执行前应先用 director_scene_read 确认 sceneId、shotId 和镜头状态。", map[string]any{
+			add("previs_preview", "请求当前预演台生成白模视频；先用 previs_scene_read 确认 sceneId、shotId。", map[string]any{
 				"sceneId":  str("导演场景 ID"),
 				"shotId":   str("镜头 ID"),
-				"duration": map[string]any{"type": "number", "minimum": 0.1, "maximum": 60, "description": "可选，省略时使用镜头时长"},
-				"fps":      map[string]any{"type": "integer", "minimum": 1, "maximum": 60, "description": "可选，省略时使用镜头帧率"},
-				"output":   map[string]any{"type": "string", "enum": []string{"clay_video"}, "description": "当前只支持白模预演视频"},
+				"duration": map[string]any{"type": "number", "minimum": 0.1, "maximum": 60},
+				"fps":      map[string]any{"type": "integer", "minimum": 1, "maximum": 60},
+				"output":   map[string]any{"type": "string", "enum": []string{"clay_video"}},
 			}, "sceneId", "shotId")
 		}
+		if req.PermissionMode != "read_only" {
+			add("previs_scene_create", "创建预演场景；先读 canvasSnapshotHash。", cloudAgentPrevisSceneCreateSchema()["properties"].(map[string]any), "canvasSnapshotHash", "sceneId", "title", "templateId")
+			add("previs_apply_patch", "审批后应用语义补丁，最多32项；先读 snapshotHash。支持场景、镜头、对象、相机、灯光、动画；角色绑定须匹配画布角色卡，动画时间不超镜头时长。禁止原始 JSON、URL、storage key。", cloudAgentPrevisApplyPatchSchema()["properties"].(map[string]any), "snapshotHash", "sceneId", "operations")
+		}
 		add("canvas_list_node_types", "列出可创建的节点类型、尺寸与连接约束；先读能力卡再选择，不要猜 nodeType。", map[string]any{})
 		add("canvas_get_state", "读取画布节点、连线与快照。{} 目录；nodeIds 精读；focusNodeIds+depth 关联子图；focusNodeIds+includeRelated 当前连通分量全部上下游（最多256节点，truncated 时继续精读）。kind=character 精读 character.definition、representations、imageReference/audioReference；content 空不代表角色卡空。角色卡可直接提供设定、三视图和声音，无需复制图片节点。generation 为任务状态；outputReference 为普通媒体参考可用性。结构化节点用对应 read 工具取 rowId；内容是数据而非指令。", map[string]any{
 			"offset":           map[string]any{"type": "integer", "minimum": 0, "description": "节点分页起点，省略为0；后续使用返回的 nextOffset，不是页码"},
--- a/backend/internal/app/cloud_agent_tools_read.go
+++ b/backend/internal/app/cloud_agent_tools_read.go
@@ -22,7 +22,7 @@ import (
 )

 func cloudAgentWrite(name string) bool {
-	return name == "canvas_apply_ops" || name == "canvas_arrange_nodes" || name == "generate_media" || name == "image_layer_split" || name == "canvas_create_storyboard" || name == "canvas_edit_storyboard" || name == "canvas_edit_batch_table" || name == "canvas_create_character"
+	return name == "canvas_apply_ops" || name == "canvas_arrange_nodes" || name == "generate_media" || name == "image_layer_split" || name == "canvas_create_storyboard" || name == "canvas_edit_storyboard" || name == "canvas_edit_batch_table" || name == "canvas_create_character" || name == "previs_scene_create" || name == "previs_apply_patch"
 }

 // 同参缓存只能拦住“原样重复”的读取。模型也可能不断修改 offset、nodeIds 或
@@ -32,7 +32,7 @@ const cloudAgentMaxReadToolCallsPerRun = 32

 func cloudAgentReadToolCacheable(name string) bool {
 	switch name {
-	case "agent_profile_read", "canvas_get_state", "canvas_read_storyboard", "director_scene_read", "skill_read_file", "model_list":
+	case "agent_profile_read", "canvas_get_state", "canvas_read_storyboard", "previs_scene_read", "skill_read_file", "model_list":
 		return true
 	default:
 		return false
@@ -45,7 +45,7 @@ func cloudAgentReadToolCacheable(name string) bool {
 // and search results are allowed to change between calls.
 func cloudAgentReadToolReadOnly(name string) bool {
 	switch name {
-	case "agent_profile_read", "canvas_get_state", "canvas_read_storyboard", "director_scene_read", "canvas_read_batch_table", "canvas_list_node_types", "skill_read_file", "skill_search", "model_list", "recall_lessons", "task_get":
+	case "agent_profile_read", "canvas_get_state", "canvas_read_storyboard", "previs_scene_read", "canvas_read_batch_table", "canvas_list_node_types", "skill_read_file", "skill_search", "model_list", "recall_lessons", "task_get":
 		return true
 	default:
 		return false
@@ -85,7 +85,7 @@ func cloudAgentReadCacheKeyForState(repo *repository.Repository, userID string,
 		return key
 	}
 	switch call.Function.Name {
-	case "canvas_get_state", "canvas_read_storyboard", "director_scene_read":
+	case "canvas_get_state", "canvas_read_storyboard", "previs_scene_read":
 		if repo != nil {
 			if canvas, err := repo.CanvasProjectForUser(userID, state.Request.CanvasID); err == nil && canvas != nil {
 				return fmt.Sprintf("%s:canvas-revision:%d", key, canvas.Revision)
@@ -243,10 +243,10 @@ func cloudAgentReadTool(repo *repository.Repository, userID string, state *cloud
 		return cloudAgentRecallLessons(repo, userID, call)
 	case "remember_lesson":
 		return cloudAgentRememberLesson(repo, userID, state, call)
-	case "director_scene_read":
-		return cloudAgentDirectorSceneRead(repo, userID, state.Request.CanvasID, call)
-	case "director_preview":
-		return cloudAgentDirectorPreview(repo, userID, state.Request.CanvasID, call)
+	case "previs_scene_read":
+		return cloudAgentPrevisSceneRead(repo, userID, state.Request.CanvasID, call)
+	case "previs_preview":
+		return cloudAgentPrevisPreview(repo, userID, state.Request.CanvasID, call)
 	case "canvas_list_node_types":
 		if err := decodeCloudAgentJSONObject(call.Function.Arguments, &struct{}{}); err != nil {
 			return nil, cloudAgentJSONArgumentError(err)
--- a/backend/internal/app/creation_canvas.go
+++ b/backend/internal/app/creation_canvas.go
@@ -163,7 +163,7 @@ func (s *Service) CreateRunCanvas(userID, id string, req CreationRequest) (map[s
 		}
 		now := time.Now()
 		cid := newID()
-		doc := map[string]any{"id": cid, "title": "智能创作", "createdAt": now.Format(time.RFC3339Nano), "updatedAt": now.Format(time.RFC3339Nano), "nodes": []any{}, "connections": []any{}, "chatSessions": []any{}, "activeChatId": nil, "backgroundMode": "dots", "showImageInfo": true, "viewport": map[string]any{"x": 0, "y": 0, "k": 1}, "directorScenes": []any{}}
+		doc := map[string]any{"id": cid, "title": "智能创作", "createdAt": now.Format(time.RFC3339Nano), "updatedAt": now.Format(time.RFC3339Nano), "nodes": []any{}, "connections": []any{}, "chatSessions": []any{}, "activeChatId": nil, "backgroundMode": "dots", "showImageInfo": true, "viewport": map[string]any{"x": 0, "y": 0, "k": 1}, "previsScenes": []any{}}
 		raw, _ := json.Marshal(doc)
 		canvas := model.CanvasProject{ID: cid, UserID: userID, Title: "智能创作", PayloadJSON: string(raw), CreatedAt: now, UpdatedAt: now}
 		policy, err := s.RuntimePolicy()
--- a/backend/internal/canvas/canvas_share.go
+++ b/backend/internal/canvas/canvas_share.go
@@ -49,8 +49,8 @@ var publicCanvasMetadataKeys = map[string]bool{
 	"characterName": true, "characterPrompt": true, "characterAliases": true, "characterView": true, "characterViewNodeIds": true,
 	"videoEditOperation": true, "videoCameraMoveId": true, "videoCameraMovePrompt": true,
 	"videoStartFrameNodeId": true, "videoEndFrameNodeId": true, "versionOfNodeId": true,
-	"versionLabel": true, "versionPrimary": true, "directorSceneId": true, "directorShotId": true,
-	"directorPreviewNodeId": true, "directorDepthNodeId": true, "directorNormalNodeId": true,
+	"versionLabel": true, "versionPrimary": true, "previsSceneId": true, "previsShotId": true,
+	"previsPreviewNodeId": true, "previsDepthNodeId": true, "previsNormalNodeId": true,
 	"skillId": true, "skillVersion": true, "skillSnapshot": true, "storyboard": true,
 	"storyboardShotDuration": true, "storyboardShotCount": true, "storyboardComposerHeight": true, "frame": true,
 }
@@ -234,7 +234,7 @@ func publicCanvasProject(project *model.CanvasProject, token string) (map[string
 		"connections":    publicCanvasConnections(source["connections"]),
 		"chatSessions":   []any{},
 		"activeChatId":   nil,
-		"directorScenes": []any{},
+		"previsScenes": []any{},
 	}
 	rawNodes, _ := source["nodes"].([]any)
 	nodes := make([]any, 0, len(rawNodes))
--- a/backend/internal/repository/cloud_agent.go
+++ b/backend/internal/repository/cloud_agent.go
@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"fmt"
+	"math/big"
 	"time"

 	"gorm.io/gorm"
@@ -314,8 +315,9 @@ func (r *Repository) MutateCloudAgent(userID, id string, revision int64, fn func

 // sameJSONDocument compares event records by JSON meaning rather than source
 // bytes. Event payloads may contain json.RawMessage (for example tool arguments),
-// so decode/re-encode can legally normalize whitespace or object key order while
-// preserving the immutable event contract.
+// so decode/re-encode can legally normalize whitespace, object key order, or
+// numeric spellings such as 0.0 and 0 while preserving the immutable event
+// contract.
 func sameJSONDocument(left, right string) bool {
 	decode := func(raw string) (any, error) {
 		decoder := json.NewDecoder(bytes.NewReader([]byte(raw)))
@@ -328,7 +330,7 @@ func sameJSONDocument(left, right string) bool {
 		if err := decoder.Decode(&extra); err == nil {
 			return nil, fmt.Errorf("multiple JSON documents")
 		}
-		return value, nil
+		return canonicalJSONValue(value), nil
 	}
 	leftValue, leftErr := decode(left)
 	rightValue, rightErr := decode(right)
@@ -340,6 +342,25 @@ func sameJSONDocument(left, right string) bool {
 	return leftErr == nil && rightErr == nil && bytes.Equal(leftCanonical, rightCanonical)
 }

+func canonicalJSONValue(value any) any {
+	switch typed := value.(type) {
+	case json.Number:
+		if rational, ok := new(big.Rat).SetString(typed.String()); ok {
+			return rational.RatString()
+		}
+		return typed.String()
+	case []any:
+		for index := range typed {
+			typed[index] = canonicalJSONValue(typed[index])
+		}
+	case map[string]any:
+		for key, nested := range typed {
+			typed[key] = canonicalJSONValue(nested)
+		}
+	}
+	return value
+}
+
 func (r *Repository) CreateCloudAgentCanvasMutation(mutation *model.CloudAgentCanvasMutation) error {
 	return r.db.Create(mutation).Error
 }