Locus协作页深度解析：为Unity项目打造的图形化Git工作区

Locus 是一款开源的 Unity Dev Agent（AI 开发助手），而它的「协作」页面就是内置的图形化 Git 工作区：查看提交历史、管理分支、暂存与提交、审查差异、解决冲突，全部在同一页面完成。Agent 的代码修改和你的手工改动，在这里统一走版本控制流程，无需在编辑器与命令行之间来回切换。

协作页四大分区：一屏完成版本控制

打开「协作」页面，界面被清晰地划分为四个区域，这也是图形化 Git 工具常见的布局思路，但 Locus 针对 Unity 项目做了不少定制：

• 左侧边栏：LOCAL（本地分支）、REMOTE（远程分支）、STASHES（暂存栈）、TAGS（标签）与SUBMODULES（子模块）分组，当前分支带HEAD标记，一目了然。
• 历史图谱：提交历史的图形视图。顶部的// WIP行代表工作区尚未提交的变更；向下滚动到底部会自动加载更多提交，无需手动翻页。
• 修改列表：分为Unstaged（未暂存）与Staged（已暂存）两区，右侧还有提交按钮与详情面板。
• 底部命令行：可以直接输入标准 Git 指令（如git pull），也可以用自然语言向 AI 下达指令，例如「帮我提交所有更改」。

相关实现分布在 src/components/collab/ 目录下，页面主逻辑见 CollabView.vue。

首次使用：一键完成 Git 初始化

如果项目还不是 Git 仓库，页面会显示初始化入口：

1. 点击Git 初始化一键创建仓库，并自动写入针对 Unity 项目优化的 .gitignore 与 Git LFS 配置——省去手工挑选忽略规则的麻烦。
2. 若user.name或user.email未配置，会弹出补录窗口，补录之前无法提交。
3. Perforce (P4) 初始化暂不支持，SVN 支持已在计划中。

初始化完成前，建议先阅读 安装与配置 了解整体引导流程。

Git 图谱与分支管理：双击切换，右键即达

历史图谱是协作页的核心。分支以彩色曲线呈现，本地、远程分支与 Tag 并行显示，交叉点清晰可辨：

分支操作：

• 双击非当前分支直接切换；双击尚无本地分支的远程分支，会自动创建本地跟踪分支并检出。
• 右键分支可执行Merge into Current（合并入当前分支）、Rebase Current onto This（变基）、Rename Branch…、Delete Branch等。
• Stash 右键提供Apply Stash、Pop Stash、Drop Stash；基准提交尚未载入图谱的 stash 会标记Unanchored，加载历史后会自动回到图中。

提交操作（右键图谱中的提交）：

• Create Branch…：从该提交创建新分支。
• Soft Reset/Mixed Reset/Hard Reset：将当前分支重置到该提交；Hard Reset会丢弃所有未提交更改，执行前需二次确认。
• Revert Commit：生成一笔反向提交安全撤销。
• Checkout Branch/Checkout Detached HEAD：切换到该提交所在分支，或以分离 HEAD 方式检出。

图谱与右键菜单的实现分别见 GitGraph.vue 与 gitContextMenu.ts。

暂存与提交：.meta 自动配对，提交信息可让 AI 代写

修改列表分为Unstaged（工作区改动）与Staged（将进入下一次提交的内容）。单个文件点击Stage/Unstage移动，多选后Stage Selected (N)批量处理，Stage All一键暂存全部。

这里有两个 Unity 场景下的贴心设计：

• .meta配对：Unity 为每个资产生成 .meta 文件，开启.meta隐藏后，配对文件不再刷屏，数量以「已隐藏 N 个 .meta」提示；暂存/放弃操作会自动带上配对的 .meta，主文件行上有.meta徽标提示。找不到主文件的 .meta 会被标记为孤立并置顶警告——这通常意味着资产被删除或移动时遗漏了 .meta，值得检查。
• Locus徽标标记：带Locus/Design、Locus/Memory等徽标的文件是 Agent 自身的知识与配置文件，放弃其改动时会额外警告。若不想将其纳入版本控制，建议加入 .gitignore。

暂存区实现见 StagingArea.vue，布局持久化逻辑见 stagingLayout.ts。

Staged 区有文件后，Commit按钮出现：填写标题（可补充详细说明），或点击标题输入框旁的AI 按钮根据已暂存内容自动生成提交信息。提交后图谱即时刷新；想撤销提交，可在图谱中右键该提交使用Soft Reset或Revert Commit。

语义差异：让 Unity 资产改动一眼可读

Unity 的 Scene、Prefab 等资产以 YAML 文本序列化，编辑器里一次简单操作（比如把某个物体抬高 2.5 米）往往对应成片的行级改动，传统文本 diff 很难看出"到底改了什么"。

Locus 的解法是把 YAML 解析成 Unity 对象树，按对象和字段对比，以接近 Inspector 的方式展示：

点击任意文件（提交、Stash、Unstaged/Staged 中的都可以）预览差异，Unity 资产会自动进入语义与文本双视图：

• 语义视图：左侧层级树列出发生变化的对象（新增、删除、修改分色标注），右侧按组件分组显示字段级前后值。例如把 Prefab 中物体位置从 (0, 0, 0) 移到 (0, 2.5, 0)，语义 diff 直接显示 Transform 位置字段的前后值，一眼可读。
• 文本视图：传统行级 diff，对照按钮切换上下排列与并排显示，适合核对 YAML 原文。

支持 .unity、.prefab、.mat、.anim、.controller 等 YAML 序列化的资产类型；非 YAML 资产回退为文本 diff。详细说明见 语义差异文档。

冲突解决：字段级三路合并，告别<<<<<<<手工比对

merge、rebase、cherry-pick、revert 或应用 stash 产生冲突时，协作页进入冲突处理状态，直到全部文件解决完毕：其他 Git 操作会被禁用并提示「存在未解决冲突，操作已禁用」，右侧切换为待解决文件列表，底部提供继续/跳过/中止（中止会恢复工作区到操作开始前）。

在文本编辑器里处理 Unity YAML 冲突，要在<<<<<<<标记之间比对大段序列化数据，误删一行就可能破坏文件结构。Locus 的结构化视图把粒度从「这几行用谁的」换成「这个字段用谁的值」：

• 三方对照：当前版本（你所在分支的改动）、传入版本（对方的改动）、共同基线（可开关显示）。
• 点选即定：点击来源列中的字段值即完成该字段的选边；也可用当前对象都用 X、当前分组都用 X、所有字段都用 X批量处理。
• 只处理必要项：只有双方都改动同一字段才需要选择，仅一侧修改的字段自动解决；仅显示冲突可过滤无关内容。
• 安全写回：底部实时显示待选字段数，选择先暂存，点击应用结构化结果才真正写入文件；写回由 Locus 完成，避免错切字段边界、残留冲突标记。

原始文本标签页保留传统逐块选边，适合非结构化文件或需要手工改写的情况；复杂冲突还可以让底部命令行的 AI 参与分析。合并界面实现见 MergeSemanticView.vue，状态管理见 conflictResolutionState.ts。

历史搜索与命令行：把不顺手的事交给它

两个常被忽略但很实用的能力：

1. Git 历史搜索：图谱工具栏的搜索历史打开「Git 搜索」窗口，可按文件（支持正则）、作者与日期范围筛选，结果覆盖提交与 stash（上限 1000 条），点击结果即在图谱中定位。
2. 底部命令行：既是标准 Git 终端，也是 AI 入口——输入自然语言即可完成常规 Git 操作，对不熟悉命令行的用户尤其友好。

写在最后

Locus 协作页的价值，在于它没有把 Unity 开发者从熟悉的工具链里拽出来：图形化图谱处理分支与提交，.meta 配对与语义 diff 消化了 Unity 资产的特殊性，字段级合并则把最容易出错的冲突解决变成了"点两下"的事。Agent 改动的可审查性，正是这套图形化 Git 工作区带给 AI 辅助开发的最大底气。

想继续深入了解，可阅读 协作页总览文档、修改管理与提交 与 冲突解决。