unity-workflow

在调用本模块中的任何技能之前： 如果你准备根据技能名称或描述猜测参数后调用技能，请停下——先阅读本文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可直接执行 dryRun。

触发条件

• 撤销整个任务或会话
• 高危改动前创建快照
• 规划／预览批量操作
• 回滚
• 撤销整个任务或会话、高危改动前快照、规划／预览批量操作、回滚

工作流技能

用于 AI 操作的持久化历史记录与回滚系统（“时光机”）。 支持为任务添加标签、在修改对象前创建快照，以及在 Editor 重启后撤销指定任务。

新增：会话级撤销——将对话中的所有更改归为一组并一并撤销。

运行模式

• Approval：本模块大部分技能标记为 SkillMode.SemiAuto（bookmark / history / task / session 系列中的纯读查询，以及 workflow_plan；后者 ReadOnly=true，仅生成聚合计划），可直接执行。有副作用的技能（bookmark_set / bookmark_goto / workflow_snapshot_object / workflow_snapshot_created / batch_retry_failed）采用默认的 SkillMode.FullAuto，需要授权。
• Auto / Bypass：FullAuto 会直接执行。
• 包含 NeverInSemi 的高危技能：bookmark_delete / workflow_delete_task（标记为 Operation.Delete，会删除书签／任务记录）、workflow_clear_history（Operation.Delete + RiskLevel=high，会清空全部历史记录、redo 栈及文件存储，且不可逆）。这些技能在 Approval/Auto 模式下会返回 MODE_FORBIDDEN，只有在 Bypass 模式下或命中 Allowlist 时才能调用。

注意：workflow_undo_task / workflow_session_undo 不是 Delete operation（标记为 Modify/Execute），可在 Approval/Auto 模式下直接撤销已记录的任务。

Surface 配置： workflow_undo_task / workflow_redo_task / workflow_revert_task / workflow_session_undo 会检查目标任务将还原的每个快照。如果某个快照会创建当前配置排除的类别（场景 GameObject，或 .unity / .mat 资源），则整个调用会返回 SURFACE_EXCLUDED（顶层包含 surfaceProfile/category/operation/manualDoc/userControlled/hint，不在 details 下嵌套），而不会部分应用。脚本、预制件、纹理、ScriptableObjects 以及 Editor／项目设置的快照不受影响——在任何配置下都可撤销。

请勿（常见幻觉）：

• 不存在 workflow_save → 使用 workflow_task_end 结束并保存任务
• 不存在 workflow_rollback → 使用 workflow_undo_task（通过 taskId）或 workflow_session_undo（通过 sessionId）
• 不存在 workflow_create → 使用 workflow_task_start
• workflow_revert_task 已弃用 → 使用 workflow_undo_task

路由：

• 简单撤销／重做（1 步）→ editor_undo / editor_redo（editor 模块）
• 多步撤销 → 使用带 steps 参数的 history_undo（本模块）
• 对话级撤销 → workflow_session_undo（本模块）

书签技能

bookmark_set

将当前选择项和场景视图位置保存为书签。

参数	类型	必填	默认值	描述
bookmarkName	string	是	-	书签名称
note	string	否	null	书签备注（可选）

返回： { success, bookmark, selectedCount, hasSceneView, note }

bookmark_goto

从书签恢复选择项和场景视图。

参数	类型	必填	默认值	描述
bookmarkName	string	是	-	要恢复的书签名称

返回： { success, bookmark, restoredSelection, note }

bookmark_list

列出所有已保存的书签。

无参数。

返回： { success, count, bookmarks: [{ name, selectedCount, hasSceneView, note, createdAt }] }

bookmark_delete

删除书签。

参数	类型	必填	默认值	描述
bookmarkName	string	是	-	要删除的书签名称

返回： { success, deleted }

历史记录技能

history_undo

撤销上一步操作（或多个步骤）。

参数	类型	必填	默认值	描述
steps	int	否	1	要执行的撤销步数

返回： { success, undoneSteps }

history_redo

重做上一步已撤销的操作（或多个步骤）。

参数	类型	必填	默认值	描述
steps	int	否	1	要执行的重做步数

返回： { success, redoneSteps }

history_get_current

获取当前撤销组的名称。

无参数。

返回： { success, currentGroup, groupIndex }

规划与批处理治理

workflow_plan

在服务端为多个技能生成组合执行计划。

参数	类型	必填	默认值	描述
skillsJson	string	是	-	包含 { "name": "...", "params": { ... } } 条目的 JSON 数组

返回： { totalSteps, totalRisk, steps, dependencies, warnings, mayDisconnect }

batch_query_assets

使用适用于批量清理或迁移工作的筛选条件查询项目资源。

参数	类型	必填	默认值	描述
searchFilter	string	否	-	额外的 AssetDatabase.FindAssets 筛选文本
folder	string	否	Assets	搜索根目录
typeFilter	string	否	-	资源类型筛选条件，例如 t:Material 或 Prefab
namePattern	string	否	-	应用于不含扩展名的文件名的正则表达式
labelFilter	string	否	-	资源标签筛选条件，例如 l:Addressable
maxResults	int	否	200	返回的资源数量上限

返回： { count, totalMatched, summary, assets }

batch_retry_failed

仅重试先前批量执行报告中的失败项。现在会复用报告中存储的原始操作上下文。

参数	类型	必填	默认值	描述
reportId	string	是	-	来自 batch_report_get / batch_report_list 的源报告 ID
runAsync	bool	否	true	立即返回 jobId，或等待完成
chunkSize	int	否	100	重试执行的分块大小

返回： { status, jobId?, retryCount, originalReportId, reportId? }

会话管理（对话级撤销）

workflow_session_start

启动新会话（对话级）。所有更改都会被跟踪，并可一起撤销。 在每次对话开始时调用此工具。

参数	类型	必填	默认值	描述
tag	string	否	null	会话标签

返回： { success, sessionId, message }

workflow_session_end

结束当前会话并保存所有已跟踪的更改。 在每次对话结束时调用此工具。

无参数。

返回： { success, sessionId, message }

workflow_session_undo

撤销特定会话期间所做的所有更改（对话级撤销）。

参数	类型	必填	默认值	描述
sessionId	string	否	null	要撤销的会话 UUID。如果未提供，则撤销最近的会话

返回： { success, sessionId, message }

workflow_session_list

列出所有记录的会话（对话级历史记录）。

无参数。

返回： { success, count, currentSessionId, sessions: [{ sessionId, taskCount, totalChanges, startTime, endTime, tags }] }

workflow_session_status

获取当前会话状态。

无参数。

返回： { success, hasActiveSession, currentSessionId, isRecording, currentTaskId, currentTaskTag, currentTaskDescription, snapshotCount }

任务级技能

workflow_task_start

启动一个新的持久化工作流任务，以跟踪更改并支持撤销。完成后调用 workflow_task_end。

参数	类型	必填	默认值	描述
tag	string	是	-	任务的简短标签（例如，“创建 NPC”）
description	string	否	""	详细描述或提示词

返回： { success, taskId, message }

workflow_task_end

结束当前工作流任务并保存。需要有一个活动任务（请先调用 workflow_task_start）。

无参数。

返回： { success, taskId, snapshotCount, message }

workflow_snapshot_object

在修改对象状态之前手动创建快照。需要有一个活动任务（请先调用 workflow_task_start）。 请在调用 component_set_property、gameobject_set_transform 等操作之前调用。

参数	类型	必填	默认值	描述
name	string	否	null	Game Object 的名称
instanceId	int	否	0	对象的实例 ID（优先使用）

返回： { success, objectName, type }

workflow_snapshot_created

记录新创建的对象，以便跟踪撤销操作。需要有一个活动任务（请先调用 workflow_task_start）。 注意： component_add 和 gameobject_create 会自动记录创建的对象，因此通常无需手动调用此工具。

参数	类型	必填	默认值	描述
name	string	否	null	Game Object 的名称
instanceId	int	否	0	对象的实例 ID（优先使用）

返回： { success, objectName, type }

workflow_list

列出持久化工作流历史记录。

无参数。

返回： { success, count, history: [{ id, tag, description, time, changes }] }

workflow_undo_task

撤销特定任务中的更改（还原到之前的状态）。已撤销的任务会被保存，之后可以重做。

参数	类型	必填	默认值	描述
taskId	string	是	-	要撤销任务的 UUID

返回： { success, taskId }

workflow_redo_task

重做之前撤销的任务（还原更改）。

参数	类型	必填	默认值	描述
taskId	string	否	null	要重做任务的 UUID。如果未提供，则重做最近撤销的任务

返回： { success, taskId }

workflow_undone_list

列出所有可以重做的已撤销任务。

无参数。

返回： { success, count, undoneStack: [{ id, tag, description, time, changes }] }

workflow_revert_task

（已弃用） workflow_undo_task 的别名。请改用 workflow_undo_task。

参数	类型	必填	默认值	描述
taskId	string	是	-	要撤销任务的 UUID

返回： { success, taskId }

workflow_delete_task

从历史记录中删除任务（不会还原更改，只会移除记录）。

参数	类型	必填	默认值	描述
taskId	string	是	-	要删除任务的 UUID

返回： { success, deletedId }

workflow_clear_history

永久清除所有工作流历史：每个任务、重做（已撤销）堆栈，以及内容寻址存储中的所有备份文件 Blob。风险极高且不可逆。 这只会删除跟踪历史——不会撤销或还原已应用于项目资源、场景或设置的任何更改。 如需回滚更改，请在清除前使用 workflow_undo_task / workflow_session_undo。

标记为 SkillOperation.Delete + RiskLevel="high"，因此属于 NeverInSemi（在 Approval/Auto 模式下会返回 MODE_FORBIDDEN；只有 Bypass 或命中 Allowlist 时才能调用）。

参数： 无

返回值： { success, before, after, message }，其中 before / after 各自报告 { tasks, undoneStack, historyFileBytes, fileStoreBytes }。

快照机制

历史记录保存在 workflow_history.json 中（schemaVersion 5）。资源和 .meta 字节分别以内容寻址方式存储在 Library/UnitySkills/workflow_files/<sha1> 中；历史记录通过 fileHash / metaFileHash 引用它们。Schema 2/3 历史记录会以原子方式迁移：移除内联 base64 之前，先确保旧版 Blob 已持久化。

快照按 SnapshotType 分级：

类型	触发条件	存储内容	撤销行为
Created	新建资源/文件夹	仅路径 + GUID	删除已创建的资源/文件夹
Moved	asset_move	仅旧路径 + 新路径	移回旧路径
Deleted	asset_delete 等	文件 + .meta 移入存储	完整还原，包括 .cs 脚本（旧实现无法还原 .cs）
Modified	material / SO / scene / uss / uxml / shadergraph …	内容寻址备份 + 轻量级 originalJson	还原备份字节
Setting	编辑器/项目设置	由 WorkflowSettingRestorerRegistry 处理	注册表还原之前的值

撤销/重做会返回每个快照的详细信息（TaskUndoResult：total / succeeded / failed / details / error）。操作按逆序执行；首次失败时，失败的快照和未处理的快照会留在源堆栈中，以便重试。

自动清理

WorkflowAutoCleanConfig（EditorPrefs 键 UnitySkills.Workflow.*）会在 EndTask 之后以及 LoadHistory 之后清理历史记录和文件存储。默认值：MaxTasks=200、MaxHistoryMB=32、MaxTaskAgeDays=30、MaxStoreMB=512、StoreMaxAgeDays=7。按存储时效/大小清理时，绝不会删除仍被保留历史记录引用的 Blob。值为 0 时会禁用对应的单项限制。

设置现在可以真正还原

设置类技能过去是单向操作；现在它们会注册还原器，因此可以回滚：console_set_pause_on_error / console_set_collapse / console_set_clear_on_play、debug_set_defines、graphics_set_quality_level / graphics_set_default_render_pipeline / graphics_set_quality_render_pipeline / graphics_add_always_included_shader / graphics_remove_always_included_shader / graphics_set_shader_stripping、physics_set_gravity / physics_set_layer_collision、project_add_tag。

Cinemachine 的 28 个写入技能现在将 TracksWorkflow=true（快照代码原本就存在，但从未自动触发）。scene_save / scene_create 现在支持回滚（对现有场景执行 scene_save 时，会将旧文件备份为 Modified 快照）。

已知限制

• scene_save 撤销会还原磁盘上的 .unity 文件；如果场景当前处于打开状态，必须执行重新加载场景才能使还原生效。
• 在从未保存过的场景中创建的对象：其 GlobalObjectId 在编辑器重启后会失效，因此撤销结果详情会将其标记为失败。
• 外部副作用（如 Package Manager 操作）无法回滚。

最简示例

import unity_skills

# Session-level: wrap entire conversation for bulk undo
unity_skills.call_skill("workflow_session_start", tag="Build Player")
unity_skills.call_skill("gameobject_create", name="Player", primitiveType="Capsule")
unity_skills.call_skill("component_add", name="Player", componentType="Rigidbody")
unity_skills.call_skill("workflow_session_end")
# Later: undo entire session
sessions = unity_skills.call_skill("workflow_session_list")
unity_skills.call_skill("workflow_session_undo", sessionId=sessions["sessions"][0]["sessionId"])

自动跟踪的操作

当会话/任务处于活动状态时，以下操作会被自动跟踪，以便撤销：

• gameobject_create / gameobject_create_batch
• gameobject_duplicate / gameobject_duplicate_batch
• component_add / component_add_batch
• ui_create_*（画布、按钮、文本、图像等）
• light_create
• prefab_instantiate / prefab_instantiate_batch
• material_create / material_duplicate
• terrain_create
• cinemachine_create_vcam

对于修改操作，系统会在可能的情况下于更改前自动为目标对象创建快照。

精确签名

精确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文档定义。