# 浏览与检索
Source: https://unity.farlocus.com/assets/browse-and-inspect

在资产页中搜索、预览资产，并通过 Locus Inspector 查看磁盘数据与 Unity 实时数据

「资产」页面提供项目资产的浏览、检索与预览能力，不需要切换到 Unity 编辑器。

## 布局

页面默认为双栏布局：左侧`目录`树，右侧`当前目录`列表加预览区。点击目录面板右上角的布局按钮可切换单双栏（`切换到单栏布局` / `切换到双栏布局`）：

* **双栏**：适合按目录逐层浏览，搜索范围可在`当前文件夹搜索`与`全局搜索`之间切换。
* **单栏**：目录树直接配合预览区，搜索固定为全局范围。

## 搜索

顶部搜索框支持按文件名、路径或类型检索，并支持 ScriptableObject 类型与基类检索：输入某个 ScriptableObject 的类型名（或它的基类名），可以找到该类型的全部数据资产。

* 结果数量有上限，超出时会提示`已截断到前 200 条`，此时应细化关键词继续缩小范围。
* 索引尚未就绪时会提示`索引未就绪，结果可能不全`，等[扫描](/assets/index)完成后结果才完整。

## 预览

选中资产后，预览区按文件类型展示不同内容：

* **文本资产**：脚本、Shader、JSON 等直接显示文本内容；大文件只加载开头部分，并提示已截断。
* **图片**：支持缩放查看，工具栏提供`适应`、`原始大小`与`重置缩放`；`通道`可在`颜色`与 `Alpha` 之间切换，便于单独检查透明通道，同时标注 `.meta` 中 `alphaIsTransparency` 的开关状态。PSD 文件同样可以预览。
* **场景 / Prefab 等序列化资产**：以层级树加 Inspector 的结构化视图展示，点选任意对象查看组件与字段，右上角可切换`简化视图`与`完整视图`。
* **其它二进制文件**：无法预览时显示信息卡，包含 `GUID`、`大小`、`扩展名`与`路径`。

## Locus Inspector

Locus Inspector 是一个独立的资产检查窗口。在会话中右键任意资产引用，选择`在 Locus Inspector 中打开`（或`在独立 Inspector 窗口中打开`）即可唤出。

窗口角标标明当前数据来源：

* **`磁盘`**：数据来自序列化文件本身，Unity 不在运行也能查看。
* **`Live`**：Unity 已连接时自动加载编辑器内的实时数据，此时可以直接编辑属性并写回 Unity。

未连接 Unity 时仅有磁盘数据可用；需要实时数据的操作会提示`需要 Unity 连接`。

## 与 Unity 联动

* **`在 Unity 中选中`**：预览区标题栏的这个按钮（以及资产引用右键菜单中的同名项）会让 Unity 在 Project 窗口中选中并定位该资产，需要 Unity 已连接。
* **`在默认编辑器中打开` / `在文件资源管理器中打开` / `复制路径`**：资产引用右键菜单中的常规操作，用于跳出到外部工具。
* **从 Unity 发回 Locus**：在 Unity 中选中资产或场景对象后，通过菜单 `Assets > Send to Locus` 或 `GameObject > Send to Locus` 可以把它作为引用发送到 Locus 输入框，详见[连接与插件](/unity/index)。


# 资产健康
Source: https://unity.farlocus.com/assets/health

识别失效引用、Missing Script、解析失败与 GUID 重复，并给出排查与修复思路

资产扫描完成后，「资产」页面的`资产风险`卡片会汇总项目中的四类问题。没有问题时显示`正常`；发现问题时显示`需处理`，并逐项列出数量。点击任意一项的`查看详情`会生成一份文本报告并用默认编辑器打开，其中列出受影响的资产路径。

## 四类问题

* **`失效引用`**：某个资产引用的 GUID 在项目中已不存在，常见于资产被删除、改名后 `.meta` 丢失，或协作时文件没有一起提交。表现为 Inspector 中的字段变为 Missing、运行时引用为空。
* **`Missing Script`**：GameObject 上挂载的脚本组件找不到对应脚本，原因与失效引用类似（脚本被删除、`.meta` 变化、所在包未安装）。带着 Missing Script 的对象在运行时会丢失行为。
* **`解析失败`**：文件无法按 Unity 序列化格式解析，常见于损坏的文件或残留合并冲突标记的文件。这些资产无法进入索引，它们的引用关系在搜索与分析中会缺失。
* **`GUID 重复`**：两个文件使用了同一个 GUID，通常来自带着 `.meta` 一起复制文件夹，或把包内容直接拷贝进 `Assets`。

## 为什么跨根目录的 GUID 重复最危险

GUID 是资产在项目中的唯一身份：所有引用都指向 GUID，而不是文件路径。当同一个 GUID 出现在两条路径上时，只有一条路径能生效，另一条会被覆盖。此时项目里所有指向这个 GUID 的引用，实际解析到哪个文件取决于哪条路径「赢了」。

重复发生在 `Assets` 与 `Packages` 之间时风险最高：两个根目录的导入行为相互独立，包升级、重新导入或换机器打开项目都可能让生效的一方发生变化。引用看起来没改，实际指向的却换成了另一份文件，而且往往没有任何报错。同在 `Assets` 内的重复相对容易发现，跨根目录的重复则可能潜伏很久。

## 排查与修复

1. 点击对应问题的`查看详情`，拿到受影响资产的完整清单。
2. 逐项处理：
   * 失效引用与 Missing Script：在引用处重新指定目标，或恢复被删除的资产（版本控制里通常能找回，见[协作](/collaboration/index)）。
   * 解析失败：检查文件是否损坏或残留冲突标记，修复后重新导入。
   * GUID 重复：保留一份，删除多余副本；如果两份都需要保留，删除其中一份的 `.meta` 让 Unity 重新生成 GUID，再手动把引用指回正确的目标。
3. 处理完成后点击`重新扫描`，确认对应计数归零。

也可以把报告直接交给 Agent 处理，例如在会话中要求「读取重复 GUID 报告，分析每一组的来源并修复」。Agent 能结合引用关系判断哪一份是被实际使用的。


# 资产数据库
Source: https://unity.farlocus.com/assets/index

Locus 直接读取磁盘上的序列化文件为项目建立资产索引，支持增量监听与扫描调优

「资产」页面的核心是`资产数据库`。Locus 不通过 Unity 编辑器解析资产引用关系，而是直接读取磁盘上的 Unity 序列化文件，扫描 `Assets` 与 `Packages` 两个根目录，为每个资产建立节点，并记录资产之间的引用关系。资产搜索、引用分析、[资产健康检查](/assets/health)都建立在这份索引之上。

## 工作原理

Unity 为每个资产生成一个 `.meta` 文件，其中的 GUID 是该资产在项目中的唯一身份；场景、Prefab、材质等序列化文件内部通过 GUID 引用其它资产。Locus 解析这些文件，就能还原出「谁引用了谁」的完整关系网。

因为只读磁盘文件，扫描不需要 Unity 编辑器在运行，也不会占用编辑器性能。扫描结果持久化保存在本地：下次打开项目时直接加载已有索引（显示为`由持久化索引加载`），只对变化部分做校验，无需重新全量扫描。

## 扫描阶段与进度

首次选择项目时会触发一次全量扫描（[安装与配置](/overview/install-and-setup)引导流程中的一步），之后也可随时在「资产」页面点击`重新扫描`。扫描按五个阶段推进：

1. `目录扫描`：遍历 `Assets` 与 `Packages` 下的文件。
2. `.meta 解析`：读取每个资产的 GUID 与导入设置。
3. `YAML 解析`：解析场景、Prefab、ScriptableObject 等序列化内容，提取引用关系。
4. `索引写入`：把节点与引用写入本地数据库。
5. `索引校验`：核对索引与磁盘的一致性，补齐差异。

进度可以在两处查看：「资产」页面`扫描状态`卡片显示当前阶段与已完成/总量；会话输入框上方的`资产数据库`状态指示也会同步显示阶段进度。数据库整体状态分为`未索引`、`扫描中`、`已索引`、`扫描失败`与`需要重新扫描`几档；出现`需要重新扫描`时（例如索引文件失效），页面会提示重扫后才能恢复资产搜索与引用分析。

## 实时监听

`实时监听`卡片对应一个文件系统监听器，负责让索引跟上项目变化：

* **`运行中`**：检测到 `.meta` / `.asset` 等文件改动会自动增量重扫，只处理变化的文件。在 Unity 里导入资源、改引用、挪目录，索引会在几秒内跟上。
* **`已停止`**：仅在手动重扫后刷新。

卡片同时显示`待处理队列`长度与`正在处理`的文件。队列偶尔堆积属于正常现象（例如批量导入后），处理完即清空。

## 扫描强度与工作线程

`实时监听`卡片下方提供两个调节项：

* **`扫描强度`**：一个从`节能`到`全速`的滑杆，控制增量扫描的节流间隔（0 到 1000 毫秒，滑杆右侧读数实时显示当前档位与毫秒数）。`全速`响应最快但占用更多 CPU，`节能`适合在意后台开销的大型项目。
* **`工作线程`**：扫描与解析使用的并行线程数。

## 统计卡片

* **`索引规模`**：`资产数量`、`引用关系数量`、`数据库大小`与`资产大小`，反映索引覆盖的整体范围。
* **`扫描状态`**：当前状态徽标、上次扫描时间与耗时，以及上次扫描统计（`目录数`、`YAML 资产`、`新增节点`、`新增引用`、`解析失败`）。`重新扫描`按钮也在这里。
* **`实时监听`**：监听器状态、待处理队列与调节项。
* **`资产风险`**：失效引用、Missing Script、解析失败与 GUID 重复的汇总入口，详见[资产健康与风险](/assets/health)。


# 修改管理与提交
Source: https://unity.farlocus.com/collaboration/changes-and-commit

暂存区管理、.meta 配对、Locus 文件标记与提交流程

## Unstaged 与 Staged

修改列表分为两区：Unstaged 是工作区的改动，Staged 是将进入下一次提交的内容。单个文件点击 `Stage` / `Unstage` 移动，多选后用 `Stage Selected (N)` 批量处理，`Stage All` 一键暂存全部。合并冲突发生时，右侧面板会切换为待解决文件列表，见[冲突解决](/collaboration/merge-conflicts)。

## .meta 配对

Unity 为每个资产生成 .meta 文件，逐一显示会淹没真正的改动。开启 `.meta` 隐藏后：

* 配对的 .meta 从列表中隐藏，数量以`已隐藏 N 个 .meta`提示。
* 暂存、取消暂存与放弃改动会自动带上配对的 .meta，主文件行上以 `.meta` 徽标提示。
* 找不到对应主文件的 .meta 标记为`孤立`并始终显示，列表顶部同时给出警告。孤立 .meta 通常意味着资产被删除或移动时 .meta 没有同步处理，值得检查一下。

## Locus 标记文件

带有 `Locus` 徽标（`Locus/Design`、`Locus/Memory`、`Locus/Skill`、`Locus/Reference`）的文件是 Agent 本身的知识或配置文件。默认情况下，除了 `user_preference` 外的记忆与理解在项目层级上共享；如无需将其纳入项目的版本控制，建议将其加入 .gitignore 文件中。

放弃这类文件的改动时会额外警告：放弃后会丢失对应的知识库、Memory 或配置改动。

## 平台限制跳过

Windows 上部分路径无法暂存（保留设备名、以句点或空格结尾的路径段等，多见于从其他系统同步来的仓库）。这类文件会单独列出并注明原因；`Stage All` 自动跳过它们、继续处理其余改动，跳过数量在结果中提示。

## 提交

Staged 区有文件后出现 `Commit` 按钮，点击打开提交窗口：

1. 窗口标题显示提交目标分支。
2. 填写提交标题，可补充可选的详细说明。
3. 也可以点击标题输入框旁的 AI 按钮，根据已暂存内容生成提交信息。生成结果建议人工过目：AI 概括的是「改了什么」，「为什么改」往往需要你补充。

提交后图谱即时刷新。要撤销一笔提交，可在图谱中右键该提交使用 `Soft Reset` 或 `Revert Commit`，见[协作页总览](/collaboration/index)；会话内 Agent 修改的撤回见[修改与撤销](/sessions/changes-and-undo)。

## 放弃改动

右键文件选择 `Discard Changes` 放弃改动：已跟踪文件恢复到上次提交的状态，未跟踪文件被直接删除。操作不可撤销，确认弹窗会说明影响范围。


# 协作
Source: https://unity.farlocus.com/collaboration/index

面向 Unity 项目的图形化 Git 工作区

「协作」页面是内置的图形化 Git 工作区：查看历史、管理分支、暂存提交、审查差异与解决冲突都在同一页面完成。Agent 的修改与你的手工修改在这里统一走版本控制流程。

<img alt="img" />

## 首次使用：Git 初始化

当前项目还不是 Git 仓库时，页面显示初始化入口。`Git 初始化`一键完成仓库创建，自动写入针对 Unity 项目的 .gitignore 与 Git LFS 配置；`Perforce (P4) 初始化`暂不支持，SVN 同样在计划中。Git 的 user.name 或 user.email 未配置时会弹出补录窗口，补录前无法提交。

## 页面分区

* **左侧边栏**：`LOCAL`（本地分支）、`REMOTE`（远程分支）、`STASHES`、`TAGS` 与 `SUBMODULES` 分组。
* **历史图谱**：提交历史的图形视图。`// WIP` 行代表工作区尚未提交的变更；滚动到底部自动加载更多提交。
* **修改列表**：Unstaged 与 Staged 两区，见[修改管理与提交](/collaboration/changes-and-commit)。
* **diff 区**：点击任意文件（提交、Stash、Unstaged/Staged 中的都可以）预览差异，Unity 资产自动进入语义视图，见[语义差异](/collaboration/semantic-diff)。
* **底部命令行**：支持直接输入标准 Git 指令，或用自然语言向 AI 下达指令。

<img alt="img" />

## 提交右键操作

右键图谱中的提交：

* **`Create Branch…`**：从该提交创建分支。
* **`Soft Reset` / `Mixed Reset` / `Hard Reset`**：将当前分支重置到该提交。`Hard Reset` 会丢失所有未提交的更改，执行前需要确认。
* **`Revert Commit`**：生成一笔反向提交来撤销该提交的变更。
* **`Checkout Branch` / `Checkout Detached HEAD`**：切换到该提交上的分支，或以分离 HEAD 方式检出。

## 分支与 Stash

* 双击非当前分支直接切换；双击尚无本地分支的远程分支，会创建本地跟踪分支并检出。
* 分支右键提供 `Merge into Current`、`Rebase Current onto This`、`Rename Branch…`、`Delete Branch`、`Copy Branch Name`。
* Stash 右键提供 `Apply Stash`、`Pop Stash`、`Drop Stash`。基准提交尚未加载进图谱的 stash 会标记 `Unanchored`，仅显示在左侧列表中，继续加载历史后回到图中。

## 布局与显示模式

修改列表右上角的三个按钮：`列表视图` / `层级视图`切换、`.meta` 文件隐藏开关、`横向布局` / `纵向布局`切换。

## Git 历史搜索

图谱工具栏的`搜索历史`打开「Git 搜索」窗口：按`文件`（文件名匹配，可`启用正则表达式`）、`作者`与日期范围筛选。结果覆盖提交与 stash，上限 1000 条，超出时提示只显示前面的匹配结果。点击结果在图谱中定位；目标不在已加载范围内时会提示位于当前图范围之外。


# 冲突解决
Source: https://unity.farlocus.com/collaboration/merge-conflicts

冲突状态下的操作限制与字段级三路合并

merge、rebase、cherry-pick、revert 或应用 stash 产生冲突时，协作页进入冲突处理状态，直到全部文件解决完毕。

<img alt="img" />

## 冲突期间的限制

存在未解决冲突时，右键菜单中的其他 Git 操作（分支、提交、Stash 等）被禁用，并提示`存在未解决冲突，操作已禁用`。右侧面板切换为待解决文件列表：.meta 冲突默认隐藏（可展开显示），底部提供`继续` / `跳过` / `中止`。`中止`会丢弃当前冲突处理进度，把工作区恢复到操作开始前的状态。

## 字段级三路合并

点击冲突文件进入解决界面，Unity YAML 资产提供`结构化`视图：

* 三方对照：`当前版本`（你所在分支的改动）、`传入版本`（对方的改动）、`共同基线`（两边的共同起点，`显示基线`可开关）。应用 stash 产生的冲突中，对侧一列为`暂存改动`。
* 点击来源列中的字段值即完成该字段的选边；也可以用`当前对象都用 X`、`当前分组都用 X`、`所有字段都用 X` 批量选边。
* 只有双方都改动了同一字段才需要选择，仅一侧修改的字段自动解决；`仅显示冲突`可以过滤掉无关内容。
* 底部实时显示还需选择的字段数。选择在写回前只是暂存，点击`应用结构化结果`才真正写入文件；未应用就离开会丢弃这些选择。

`原始文本`标签页保留传统的按冲突块逐块选边，适合非结构化文件或需要手工改写的情况。文件在 Locus 外部被修改后，块选择会被禁用，需在下方直接手动编辑结果。

## 与手工编辑冲突标记相比

在文本编辑器里处理 Unity YAML 冲突，要在 `<<<<<<<` 标记之间比对大段序列化数据：一个字段的取舍夹在几十行上下文中，误删一行就可能破坏文件结构。字段级合并把选择粒度从「这几行用谁的」换成「这个字段用谁的值」，写回由 Locus 完成，避免了错切字段边界、残留冲突标记这类手工风险；对象层级与组件归属在界面中保持可见，判断「该用谁的」也更有依据。

需要基于全部代码上下文做判断的复杂冲突（例如双方重构了同一段逻辑的 C# 文件），仍然可以在底部命令行让 AI 参与分析，或回退到`原始文本`视图手工处理。


# 语义差异
Source: https://unity.farlocus.com/collaboration/semantic-diff

Unity 资产的对象级差异视图与文本视图

Scene、Prefab 这类 Unity 资产以 YAML 文本序列化，编辑器里一次简单操作往往对应成片的行级改动，直接读文本 diff 很难看出到底改了什么。语义差异把 YAML 解析成 Unity 对象树，按对象和字段对比，以接近 Inspector 的方式展示结果。

<img alt="img" />

## 双视图

Unity 资产的差异预览提供`语义`与`文本`两个标签页：

* **`语义`视图**：左侧层级树列出发生变化的对象（新增、删除、修改分色标注），右侧按组件分组显示字段级的前后值。默认只显示有变化的字段，`显示未变化字段`可展开全部。
* **`文本`视图**：传统行级 diff，`对照`按钮切换上下排列与并排显示。核对 YAML 原文，或处理语义视图未覆盖的场景时使用。

大文件解析需要一点时间，加载进度按获取文件内容、计算差异、解析资源、构建语义模型四个阶段显示。

## 支持的资产类型

Scene（.unity）、Prefab（.prefab）、Material（.mat）、动画与动画控制器（.anim / .controller）、ScriptableObject 等 .asset 文件，以及物理材质、渲染纹理等其他以 YAML 序列化的资产。组件字段按 Inspector 中的分组展示，例如 Transform 的变换、ParticleSystem 的主模块 / 发射 / 形状。非 YAML 资产与二进制文件回退为文本 diff 或不提供预览。

## 一个对照例子

把 Prefab 里某个物体的位置从 (0, 0, 0) 移到 (0, 2.5, 0)：

* 文本 diff：先在十几行 `m_LocalPosition`、`m_LocalRotation` 相关的 YAML 上下文里找到 `y: 0` 变成 `y: 2.5` 的那一行，再顺着文块向上确认这段数据属于哪个物体。
* 语义 diff：直接显示该物体 Transform 组件位置字段的前后值，一眼可读。

## 原理

Locus 将差异两侧的 YAML 各自解析为 Unity 对象树，按对象在文件中的持久标识配对，再对配对的对象逐字段比较。展示的因此是「哪个对象的哪个字段从 A 变成 B」，而不是「第几行文本不同」：改动规模不影响可读性，GameObject 层级与组件归属也始终可见。

会话聊天中的文件变更预览、[资产页](/assets/browse-and-inspect)的资产检查使用同一套解析展示，三处看到的字段结构一致。


# 插件与视图
Source: https://unity.farlocus.com/extensions/plugins-and-views

插件的安装、管理与自定义视图面板

插件把 Agent 定义、规则（Rule）、技能（Skill）、视图（View）和项目依赖打包成可安装扩展，安装后在 Locus 中统一使用和更新。「插件」与「视图」两个顶部标签页分别管理它们。

## 插件能装什么

* **Agent 定义**：新的 Agent 角色及其系统提示词。
* **Rule**：注入 Agent 上下文的行为规则。
* **Skill**：沉淀稳定工作流、检查项和工具使用规则的执行组件，Agent 在特定任务中按固定流程执行，详见[技能与参考](/knowledge/skills-and-references)。
* **View**：在 Locus 中运行的自定义面板，见下文。
* **项目依赖**：声明插件所需的 Unity Package、程序集或资产，安装时可对照检查。

## 安装的三种途径

* **`插件 Hub`**：浏览注册表中的插件，支持搜索、`安装`、`更新`、`Star`。`GitHub 登录`用于提高 release 元数据请求额度，并支持私有 GitHub 仓库。
* **`从链接导入插件`**：粘贴仓库、release 或 zip 链接直接安装。
* **`导入本地插件`**：选择本地的插件 zip 或目录。

## 作用域：App 级与项目级

安装时选择`安装位置`：

* **`安装到 App`**：对本机所有项目生效，适合通用工作流。
* **`安装到项目`**：只对当前项目生效（需要先选择项目），适合与特定项目强绑定的技能和视图，可随项目仓库分发给团队。

## 更新、禁用与卸载

在`已安装`列表或插件详情中操作：有新版本时显示`更新`；`停用`临时移除插件的组件而保留文件；`卸载`彻底删除。插件详情页显示其`组件`构成、`位置`与兼容性要求（最低 Locus 版本）。

## 自定义注册表

插件 Hub 默认使用官方注册表，团队可以自建：在 Hub 的`注册表`配置中`新增`条目，填写`名称`、`地址`（owner/repo 或完整地址）、`分支`与`路径`。适合在组织内部分发未公开的插件。

## 视图

视图（View）是通过 Locus 自身前端运行的自定义项目编辑器面板：Agent 可以把 Vue 界面、运行脚本和 Unity 属性数据组合为一个 View package，作为独立工具运行，例如关卡配置表编辑器、技能数值面板。

* **查看**：顶部「视图」页列出当前工作区的全部视图，点击名称即可打开；部分视图需要 Unity 编辑器连接。
* **创建**：在会话中输入 `/view` 并描述需求，Agent 会进入 View 工作流创建或更新视图。
* **整理**：拖拽条目调整顺序或移入文件夹，右键条目可新建文件夹、重命名、移动或删除。由插件安装的视图随插件管理，需卸载插件后才能删除。
* **列表入口**：「设置 → 显示」的`会话列表中显示视图`可让视图入口出现在会话页左侧。

## 从会话创建与发布插件

在会话中输入 `/plugin` 加上需求，Agent 会进入插件工作流，创建或更新插件清单、组件目录和发布材料。发布到注册表：先在插件页面完成 `GitHub 登录`，再让 Agent 创建插件仓库并向注册表发起 Pull Request，合并后其他用户刷新插件页即可安装。


# Locus for Unity
Source: https://unity.farlocus.com/index

规模化地提升游戏开发的效率，将创作者从繁琐的事务性工作中解放出来

## 概览

`Locus for Unity`是一个面向Unity项目的**开源**AI Agent。

* **编辑器内操作**：编写C#代码、读入并修改Unity对象与资产，完成完整功能开发流程
* **运行时分析与调试**：自主操作并捕获运行时状态，协助你修复BUG、优化性能
* **自动化知识系统**：自动将对话需求总结成设计文档，并将项目理解保存在长期记忆中
* **可视化版本管理**：提供可视化的版本管理界面，支持Unity YAML资产的语义化差异分析与冲突处理
* **多种模型支持**：支持订阅帐号登录，并兼容多种LLM API能力

<br />

<div>
  <a href="overview/install-and-setup">
    <span>
      <svg>
        <path />

        <path />

        <path />
      </svg>
    </span>

    <span>快速开始</span>
    <span>快速安装Locus，在几分钟内完整配置</span>
  </a>

  <a href="overview/roadmap">
    <span>
      <svg>
        <path />

        <path />
      </svg>
    </span>

    <span>路线图</span>
    <span>查看我们正在实施以及计划中的功能</span>
  </a>

  <a href="overview/advantages-over-generic-agents">
    <span>
      <svg>
        <path />

        <path />

        <path />

        <path />

        <path />

        <path />
      </svg>
    </span>

    <span>从技术上讲，Locus有什么独特之处？</span>
    <span>了解Locus独立进程架构带来的技术能力</span>
  </a>
</div>

## 示例展示

<div>
  <div>
    <span>
      <img alt="文件变更" />
    </span>

    <p>在会话界面中审阅文件修改</p>
  </div>

  <div>
    <span>
      <img alt="Git 图谱" />
    </span>

    <p>通过图形化界面进行版本管理</p>
  </div>

  <div>
    <span>
      <img alt="知识工作区" />
    </span>

    <p>编辑知识文档，配置上下文注入方式</p>
  </div>

  <div>
    <span>
      <img alt="差异对比" />
    </span>

    <p>语义化地分析YAML文件的修改</p>
  </div>

  <div>
    <span>
      <img alt="合并处理" />
    </span>

    <p>语义化地处理合并时冲突</p>
  </div>

  <div>
    <span>
      <img alt="检索设置" />
    </span>

    <p>词法与语法检索配置</p>
  </div>
</div>


# 知识
Source: https://unity.farlocus.com/knowledge/index

四类知识各自的分工、目录树徽标与总览统计的读法

「知识」页面管理 Agent 的项目知识库。所有知识以 Markdown 文档形式存放，按用途分为四类，统一参与检索与注入。Agent 依赖这些内容理解项目背景，不需要在每次会话里重新解释。

<img alt="img" />

## 四类知识

* **Design（项目设计）**：记录项目设计需求与事实基准，解决「Agent 不知道你要什么」的问题。AI 可从会话中总结更新（需审批），后续任务会把其中内容视为需求依据。
* **Memory（长期记忆）**：由 AI 自动维护的经验性信息，解决「每次会话都从零开始」的问题。默认预设`项目理解`、`错题本`、`用户偏好`三个模块。
* **Skill（标准流程）**：把高频工作流固化为文档，解决「同类任务每次都要重新交代」的问题。可通过 / 指令或自动召回触发。
* **Reference（参考资料）**：外部只读资料库，解决「Agent 需要项目之外的资料」的问题。支持导入本地文件夹、Unity 官方文档与飞书文档。

前两类的维护方式见 [Design 与 Memory](/knowledge/memory-and-design)，后两类见 [Skill 与 Reference](/knowledge/skills-and-references)。

## 目录树与徽标

左侧目录树按类型组织文档，支持右键新建、重命名、移动与删除。条目上的徽标标记文档状态，树顶部的`徽标说明`可随时查阅：

* **`AUTO`**：文档由 AI 自动维护。
* **`LX` / `SM`**：该目录已开启全文 / 语义检索，见[检索与索引](/knowledge/retrieval)。
* **`外部`**：内容来自外部导入（本地文件夹 / 飞书 / Unity 文档等），只读。
* **/ 指令徽标**：可在会话中通过 / 指令触发（Skill 文档）。
* **插件徽标**：内容由插件提供，无法重命名、移动或删除，见[插件与视图](/extensions/plugins-and-views)。
* **Skill 包徽标**：内容由 Skill 包提供，只读。

## 总览统计

选中某个知识类型时，右侧显示该类型的总览卡片：

* **`检索索引`**：合并展示全文与语义两条检索通道。全文侧显示覆盖率与`最新` / `需刷新` / `待处理`状态，语义侧显示覆盖率与索引健康度，用于确认 Agent 能不能检索到这些文档。
* **`知识内容新鲜度`**：统计已索引文档中最新、需刷新与状态未知的比例。需刷新的文档在下次索引后恢复最新。
* **`上下文负担`**：估算常驻注入的上下文压力（CJK 按 1 字 ≈ 1 token、其余按 4 字符 ≈ 1 token），分为知识概览、Memory、Auto Skill 与检索语料几部分，用于判断知识体系给每次请求增加的 token 成本。

前两张卡片回答「找不找得到」，第三张回答「代价有多大」。知识文档并非越多越好：常驻注入直接占用上下文窗口，检索覆盖则几乎免费。控制注入总量、把大部分内容交给检索，是维护知识库的基本原则，具体档位见[注入方式](/knowledge/injection)。


# 注入方式
Source: https://unity.farlocus.com/knowledge/injection

五档注入的取舍、摘要的作用、目录级继承与注入状态

Agent 获取知识有两条路：常驻注入与检索。常驻注入的内容进入每一次请求的上下文窗口，Agent 不需要检索就能看到，但注入越多 token 成本越高；检索按需读取，几乎不增加常驻成本。`注入方式`用来为每份文档在两者之间选择档位。

<img alt="img" />

## 五个档位

在文档的`配置`侧栏中设置`注入方式`：

* **`仅搜索`**：只参与检索与召回，不主动进入 Agent 上下文。适合数量大、只在特定任务用到的资料。
* **`L0 - 路径注入`**：向 Agent 提供文档标题与路径，正文按需读取。适合让 Agent 知道「存在这份文档、在哪里」。
* **`L1 - 摘要注入`**：向 Agent 提供摘要；没有摘要时使用正文前段。适合希望 Agent 时刻记得要点、细节按需展开的文档。
* **`L2 - 全文注入`**：将维护规则与正文作为常驻知识注入。适合篇幅可控、几乎每个任务都要参照的内容。
* **`L3 - 全文规则注入`**：将维护规则与正文完整注入为规则，适合高优先级的长期约束，例如必须遵守的项目规范。

Skill 文档是例外：模型只能通过注入的结构行发现 Skill，因此这一档在 Skill 上显示为`不注入`——等于关闭自动召回，只能通过指令触发使用。

默认档位按类型区分：Design 文档默认 `L0 - 路径注入`，Skill 文档默认 `L1 - 摘要注入`，Memory 与 Reference 文档默认`仅搜索`。Memory 的三个预设模块出厂时已按用途调好档位（错题本 L2、用户偏好 L3、项目理解 L0），见 [Design 与 Memory](/knowledge/memory-and-design)。

## 摘要

`L1 - 摘要注入`实际注入的是文档的`摘要`字段，未填写时退回正文前段。正文前段往往是背景铺垫而非结论，对常驻注入的关键文档建议手写摘要：用两三句话说清这份文档覆盖什么、什么情况下应该展开读全文。摘要同时用于搜索结果预览。

## 目录级配置与继承

右键目录选择`目录配置`，可以为整个目录设置注入方式（`仅搜索` / `L0` / `L1`，L1 会在目录路径后附带目录说明）。文档与子目录默认`继承父目录`，顶层目录沿用分类默认配置；配置面板中的`当前生效`会标明实际生效的配置来自本地配置、父目录还是分类默认配置。整理成批文档时，优先在目录层级设置，再对个别文档单独覆盖。

## 注入状态

两处可以核对实际注入情况：

* 目录检查页的`注入状态`：显示子树内的`注入文档`篇数与`注入体积`。常驻注入没有硬性上限，体积增长会直接推高每次请求的成本，明显膨胀时应下调部分文档的档位或精简内容。
* 顶部的`注入预览`：展示当前 Agent 实际注入的 Knowledge 内容块与`预估 Token 消耗`。想确认会话里 Agent 到底带了什么，以这里为准。

档位没有标准答案，只有取舍：L2/L3 换来的是 Agent 每次都看得见，付出的是每次请求都要为它付费。一个实用的检查习惯是定期打开[知识总览](/knowledge/index)的`上下文负担`卡片，常驻部分明显膨胀时，把低频文档降回 `L1` 或`仅搜索`。


# Design 与 Memory
Source: https://unity.farlocus.com/knowledge/memory-and-design

需求基准与长期记忆的维护流程、预设模块与编辑模式

Design 与 Memory 是知识库中由 AI 参与维护的两类文档：Design 记录「你要什么」，Memory 记录「AI 在这个项目里学到了什么」。

## Design：需求基准

Design 文档记录项目设计需求与事实基准。AI 会在会话中识别可沉淀的设计结论，以`知识维护建议`卡片发起提案，列出检测到的条目与置信度；点击`查看草稿`核对内容，`确认并应用`后才会写入文档，`忽略`则丢弃。你也可以随时手动编辑。

Design 代表 AI 对你需求的总结与归纳，后续任务中会把这些内容视为需求依据。因此，确保其中信息准确，属于使用者的重要责任。审批提案时逐条核对，发现过时结论及时删改，见[使用建议](/overview/usage-guidance)。

## Memory：长期记忆

Memory 由 AI 自动维护，默认预设三个模块：

* **`项目理解`**：AI 对项目结构与技术方案的持续总结，项目级共享。
* **`错题本`**：踩过的坑与修正后的结论，避免重复犯错，项目级共享。
* **`用户偏好`**：你的个人习惯（沟通语言、代码风格偏好等），作用域为用户级，跨项目生效。

Memory 文档与其他类型使用同一套[注入档位](/knowledge/injection)，预设模块出厂时已按用途调好：`错题本`全文注入（L2），`用户偏好`作为规则注入（L3），`项目理解`仅注入路径（L0）、正文按需读取；自定义 Memory 文档默认`仅搜索`，可在配置侧栏自行调档。常驻注入的文件越多、内容越长，每次请求的负担越高。`Memory 仪表盘`显示`常驻上下文负担`与维护 token 估算，条目膨胀时应及时精简。Memory 是 AI 的经验性总结，建议定期检查，手动修改或删除不准确的条目；也可以用 `/dream` 指令发起一次专门的记忆整理会话，按维护规则合并重复、删除过期条目，并对照当前工程抽查结论是否仍然成立。

## 自定义 Memory 文档

右键 Memory 分类可`新建记忆`（项目级）或`新建用户记忆`（用户级），把某一类经验独立成文档管理。自定义文档配合`维护规则`使用：规则约束 AI 自动更新时能改什么、必须保留什么。写法可以参考预设模块的默认规则：

* 只保留长期稳定、可复用的信息
* 将重复或冲突内容整理为最新结论
* 删除临时上下文、一次性任务和无依据推测

规则越具体，自动维护越可控。例如给「性能优化记录」文档加一条「每条结论必须附带出现场景与验证方式」，可以避免积累无法复查的模糊经验；给「第三方插件坑位」文档加一条「插件版本升级后重新核对相关条目」，能让过期信息有明确的清理时机。

## 编辑模式

每份文档的 `AI编辑模式`决定 AI 的修改权限：

* **`不可编辑`**：仅允许查看，AI 不能修改。
* **`提案后修改`**：AI 先提交提案，你确认后才写入。非 Memory 文档的默认档。
* **`自动编辑`**：AI 按维护规则直接更新，必须填写维护规则。Memory 预设模块的默认档。
* **`继承父目录`**：沿用父目录的 AI 编辑配置，顶层文档沿用分类默认配置。

重要文档（如核心 Design）建议保持`提案后修改`；高频、低风险的记录类文档再放开`自动编辑`。


# 检索与索引
Source: https://unity.farlocus.com/knowledge/retrieval

全文与语义两条检索通道的配置、目录级开关与索引维护

知识库支持两条检索通道。全文检索按词匹配，适合类名、资产名、报错文本这类精确词；语义检索按含义匹配，适合「角色受击后的无敌帧逻辑」这类模糊描述。两条通道可以同时启用：搜索时分别召回、合并排序，结果会标注命中来源（`全文匹配` / `语义匹配` / `混合匹配`）。

<img alt="img" />

## 全文检索

顶部`检索设置`面板中的`全文检索`开关控制是否维护倒排索引，默认关闭。关闭时搜索栏使用逐文档文本扫描，小规模知识库够用；文档多了以后建议开启，检索更快，Agent 侧的词法召回也更完整。

## 语义检索

语义检索默认关闭，需要先配置 embedding 模型，两种方式：

* **本地运行时**：在`检索设置`中选择预设模型（列表按参数规模从小到大排列，附带显存与内存估算）并`下载模型`，下载源可选`官方`或 `HF-Mirror`；下载完成后点击`激活向量`启动本地运行时。也可以直接输入包含 ONNX 与 tokenizer 文件的 Hugging Face 仓库 ID，或选择本地模型目录。
* **远端接口**：在「设置」页面的`嵌入设置`中切换到`远端`模式，填写兼容 OpenAI 的 `/v1/embeddings` 接口地址、`API Key` 与模型名，`测试连接`通过即可使用。

本地方式无网络依赖，但占用本机资源（运行后端可选 CPU 或 GPU）；远端方式没有本机开销，索引与查询会产生接口调用费用。

## 目录级开关

并非所有目录都值得进索引。`目录配置`的`检索规则`按目录控制`全文检索`与`语义检索`的参与状态，取值为`继承` / `开启` / `关闭`：默认沿用最近一级父目录的规则，没有上级规则时保持开启。目录树中的 `LX` / `SM` 徽标表示该目录已开启对应检索方式。体积大、价值密度低的目录（例如整包导入的原始资料）可以关闭语义检索，省下索引成本。

## 索引状态与刷新

* [知识总览](/knowledge/index)的`检索索引`卡片显示两条通道的覆盖率与`最新` / `需刷新` / `待处理`状态。文档修改后索引自动跟进，`需刷新`是正常的过渡状态。
* 状态长期异常时，用仪表盘中的`重建索引`整体重建，重建进度在独立窗口中显示。
* 语义运行时的模型、当前设备与显存占用在`检索设置`面板查看，`停用向量`可随时释放资源。

## 怎么选

词法与语义不是二选一。实践中常见的组合：全文检索开启作为基础通道；项目术语多、命名不规范、或者团队成员经常用自然语言描述需求时，再补开语义检索。搜索时把精确词交给词法、把意图描述交给语义，两边同时命中的文档排序更靠前。


# Skill 与 Reference
Source: https://unity.farlocus.com/knowledge/skills-and-references

工作流的固化与触发配置，外部资料的导入与同步

## Skill：固化流程

Skill 把高频工作流写成文档：步骤、检查项、产出格式。遇到同类任务时，Agent 按 Skill 规范执行，不需要每次重新交代。策划等非程序成员按程序预先写好的 Skill 开发功能，也是推荐的协作方式，见[使用建议](/overview/usage-guidance)。

右键 Skill 分类`新建技能`创建。正文写流程本身，`配置`侧栏控制触发行为：

* **`描述`**：简短描述，用于检索和匹配。自动触发依赖它判断当前任务是否命中，应写清适用与不适用的场景。
* **`参数提示`**：/ 指令的参数占位说明，输入指令时显示。
* **`触发方式`**：四档。`不启用`（不出现在 / 命令面板，也不允许自动召回）、`仅指令`（只通过 / 指令手动触发）、`仅自动`（只由模型语义召回，不进命令面板）、`两者`。
* **`指令触发`**：/ 指令名，如 `/commit-batch`。与内置命令重复、或已被其他 Skill 占用时会提示冲突，需要换名。

## 技能包

Skill 可以打包分发。右键菜单提供三个操作：

* **`导入 Package`**：导入他人分享的技能包。包内文档只读，无法重命名、移动或删除。
* **`导出 Package`**：把自己的 Skill 导出为包文件，分享给团队。
* **`删除 Package`**：整包移除。

包内容需要修改时，由包作者更新版本后重新导入；插件提供的 Skill 同样只读，随插件更新，见[插件与视图](/extensions/plugins-and-views)。

## Reference：外部资料

Reference 存放项目之外的只读资料，导入后与项目知识一起参与检索。三种来源：

* **本地文件夹**：`导入外部文件夹`，选择目录后内容进入 Reference。
* **Unity 官方文档**：按当前项目的 Unity 版本下载官方离线文档，并转换为可检索的 Markdown。导入时选择`文档语言`（`中文` / `English`），独立窗口显示下载、解压、转换与索引进度；项目升级 Unity 版本后，页面会提示`重新导入`对应版本。
* **飞书文档**：配置飞书应用（应用身份，或经用户身份授权），选择知识空间与目录后托管导入其中的文档。

## 外部内容只读

外部导入的文档保持只读：修改需要回到原始来源（本地文件、飞书文档），再重新导入或同步。这保证 Reference 始终与来源一致，不会出现两边各改一份的分叉。导入 Unity 官方文档后，Agent 查 API 用法时可直接检索本地副本，配合[资产数据库](/assets/index)的引用分析，回答会更贴近当前项目版本。


# 从技术上讲，Locus有什么独特之处？
Source: https://unity.farlocus.com/overview/advantages-over-generic-agents

Locus独立进程架构带来的技术能力

Locus是一个Rust + Tauri + Vue.js的独立进程应用程序。

* 我们设计了专有的中间表示，以让Agent渐进地读入大型场景与资产，并相应设计了检索工具，让agent能够快速定位目标对象
* 我们通过Roslyn库，实现了在Unity编辑器内JIT编译并执行C#代码，以此实现对资产的语义化修改；并在agent侧的版本管理做了特定处理，能够review/revert agent在对话中的资产/代码修改
* 我们基于Rust优秀并行生态系统，实现了高度并行化的资产数据库扫描，以此实现了对大型场景的高速语义解析与任意资产的引用关系查询（Unity Editor API仅提供依赖关系查询）
* 我们实现了自动化的知识系统，agent会把每次接到的零散对话需求总结成设计文档，并把工作中的理解保存到memory中，无需重复大量explore项目
* 知识系统内的文档支持配置AI维护模式、维护规则，并且支持调整在上下文内部的L0/L1/L2的注入方式，用户可以高度定制化渐进式展开的方式，并且原生支持大量文档的词法/语法检索，支持选择并下载嵌入运行时
* 我们通过编写C#状态机工具，Agent得以在运行时对某些特定帧数/事件上通过反射采样内部状态，并输出成逐帧表格，进行多帧行为的动态调试
* 我们提供图形化的版本管理界面，并且支持对Unity YAML文件语义化的修改查看与冲突解决
* 我们基于Vue.js实现了用户体验更好的现代前端界面，而非基于Unity Editor API的有限控件，并且通过Windows API将其嵌入到Unity窗口中

如果选择在 Unity 编辑器内部实现 Locus，或将 Locus 设计为一个 MCP 服务器，上述多数特性将难以落地，甚至在技术上几乎不可实现。


# 安装与配置
Source: https://unity.farlocus.com/overview/install-and-setup

快速安装与配置Locus

<br />

<div>
  **在开始使用 Locus 执行任何修改操作之前，请确保您已备份项目文件。**<br />
  **AI Agent 在执行任务时可能存在不确定性，请审慎使用。**
</div>

<br />

## 配置模型服务

Locus 须配置远程 AI 服务作为其推理引擎。**远程大模型的性能将直接影响 Locus 的工作效果。**

> **Locus 当前支持的订阅服务及消息格式**
>
> * OpenAI 订阅
> * OpenAI Response API
> * Anthropic Messages API
> * OpenAI Chat Completions API

除所配置的远程模型服务调用外，Locus 为纯客户端软件，其余任何信息均不会上传至互联网。

建议使用官方安装包安装。安装完成后，首次启动软件时将自动进入引导流程。

## 选择项目并安装插件

<img alt="img" />

Locus 通过 Unity 插件与 Unity 编辑器进行通信，以实现编辑器状态检测、C# 代码执行等功能。

插件默认安装路径为 `Packages/com.farlocus.locus`。检测到旧版 `Assets/Locus` 安装时，点击更新会自动迁移到新的包路径。

## 版本管理/Git配置

<img alt="img" />

Locus 依赖版本管理工具实现「撤销」及「变更分析」等功能。

此外，Locus 针对 Git 提供了图形化操作界面。

> 未来计划支持 Perforce（P4）及 SVN 等版本管理工具，当前版本仅支持 Git。

## 扫描资产数据库

<img alt="img" />

Locus 不通过 Unity 编辑器解析资产引用关系，而是直接读取磁盘上的 Unity 序列化文件，以分析资产间的引用关系。

## 尝试第一次对话

<br />

<div>
  **在开始使用 Locus 执行任何修改操作之前，请确保您已备份项目文件。**<br />
  **AI Agent 在执行任务时可能存在不确定性，请审慎使用。**
</div>

Locus 的基础配置已完成，后续可在「设置」页面中调整上述配置。

**也可以在 Unity 编辑器中通过 `Window > Locus` 打开编辑器内置窗口。**

现可尝试以下示例对话：

* 分析项目代码结构，指出可优化之处。
* 创建一个横版跳跃游戏：编写一个简单的 2D 横版跳跃控制器，并在当前场景中放置若干测试平台。
* 将当前修改分批提交至 Git。
* 创建卡通风格的自定义渲染管线：制定实施方案，经审阅后执行。
* 为项目中所有 `Item` 资产下的描述字符串生成对应的多语言文本，并填入表格。


# 当前版本
Source: https://unity.farlocus.com/overview/latest-version

Locus v0.6.0 (2026-07-17)

## 下载

* [Windows x64](https://github.com/r1n7aro/Locus/releases/download/v0.6.0/locus_0.6.0_x64-setup.exe)
* [Windows x64（系统 Python/Git）](https://github.com/r1n7aro/Locus/releases/download/v0.6.0/locus_0.6.0_x64-without_embed_python_git-setup.exe)
* [GitHub Releases](https://github.com/r1n7aro/Locus/releases)

## 变更列表

### v0.6.0（新增）

* **MCP 服务器接入。** 支持通过 stdio 或 HTTP 连接外部 MCP 服务器，并在 Agent 会话中使用其工具。新增 MCP 设置页管理服务器及其工具；MCP 工具调用在聊天中有确认卡片与状态展示。可从 Claude Desktop、Claude Code、Cursor 的配置导入服务器条目（导入后默认停用）。新增 `/connect` 命令：引导式接入外部软件，在 MCP / CLI / HTTP 三种通道中选型并实测连通。
* **多模型供应商与内置 models.dev 目录。** 自定义模型改为按供应商组织，一个供应商可配置多个模型，取代原来的单端点条目。可从内置的 models.dev 目录一键添加供应商（70 余家服务商、预填官方端点），也可在新的两步弹窗中手动配置，支持逐字段校验。推理参数（如 `enable_thinking`、思考类型）可按模型设置；模型选择器按供应商分组展示自定义模型。已有配置自动迁移，旧模型 id 继续有效。
* **外部技能发现。** 可选发现来自 Claude Code、Codex 与 `.agents` 目录（用户级与工作区级）以及已安装 Claude Code 插件的技能，只读接入、默认关闭。技能激活拆分为「自动注入」与「命令」两条独立通道，可按技能分别控制；外部命令技能支持 `$ARGUMENTS` 与 `$1`–`$9` 参数替换。
* **附加工作目录。** 工作区可通过右键菜单附加额外目录，文件工具可以在这些目录内读写，工作区选择器会内联展示附加路径。
* **Unity 对象预览直接读盘。** Unity 不序列化的文件（Markdown、纯文本、源码、二进制）改为直接从磁盘预览，Unity 尚未导入的资产（例如符号链接目录下 AI 生成的文件）也能正常预览。预览折叠改为可选，资产检视器中保持展开。(#114)
* **聊天选中复制。** 在消息中选中文本后右键，菜单首项为「复制选中内容」。
* **视图日志栏开关。** 视图窗口的日志栏默认隐藏，可在显示设置中开启，设置跨窗口同步。

### v0.6.0（修复）

* Windows 命令行工具体验：托管 Python 的环境变量只作用于 Python 调用，不再影响整个命令环境；命令输出按系统 ANSI 代码页解码，修复中文（GBK）输出乱码；超长输出截断改为保留开头和结尾，不再只留开头。
* 延迟加载的工具改用 Anthropic 原生 tool reference 与 Codex 原生 tool search 装载，取代原有的 meta-tool 激活方式。
* 内置的 Unity Profiler 采样技能默认改为摘要注入，Agent 现在能自动发现并按需加载；此前默认不注入。
* 辅助窗口（计划审阅、diff 审查、各导入窗口等）改走预热的窗口池，打开更快。
* 界面语言包按需加载。
* 会话与知识库数据库在空闲页占比过高时自动 VACUUM，回收磁盘空间。
* 右键菜单统一加上图标并对齐布局。
* 插件开关即时生效于列表，不再等待后端往返。
* 设置页中聚焦的数字输入不再被滚轮误改。

### v0.6.0（移除）

* 移除单端点的自定义模型配置方式，由多模型供应商弹窗取代；已有自定义端点自动迁移。

### v0.5.8（新增）

* **独立计划审阅窗口。** 可在显示设置中选择将计划审批呈现在审批卡或独立窗口；选择独立窗口后会自动打开计划审阅窗口，可审阅 Markdown 计划、批准并开始实现，或附带说明退回修改。

### v0.5.8（修复）

* **已解决 Windows 上 DeepSeek 请求间歇性 HTTP 400。** 将 `schannel` 从 0.1.28 升级到 0.1.29，避免 TLS 1.3 重新协商期间重复发送待处理请求数据并破坏较大的 JSON 请求体，解决 [issue #48](https://github.com/r1n7aro/Locus/issues/48) 集中记录的 `400 Bad Request: Failed to parse the request body as JSON` 问题。([PR #110](https://github.com/r1n7aro/Locus/pull/110))
* **计划审批流程。** 审批卡现在以 Markdown 展示计划，退回说明会随“退回修改”一并发送，批准后的计划与退回反馈会以正确状态保留在会话记录中。空闲会话选择 `/plan` 后会立即进入持续性规划模式。
* 启用 Fast 模式时，支持 Fast 的 Codex 模型会在模型标签中显示 `Fast` 状态。
* **精确编辑工具契约。** `edit` 与 `knowledge_edit` 的公开工具定义现按每次一处精确替换执行。`knowledge_read` 可原样返回 `summary`、`body` 或 `maintenanceRules` 分区，保留空白与空内容，供后续编辑逐字匹配目标分区；已有的历史批量文件编辑调用继续兼容。

### v0.5.7（新增）

* **GPT-5.6 系列与 Fast 模式。** ChatGPT 订阅新增 GPT-5.6 Sol、Terra、Luna，支持 353,400 token 的 Codex 运行时上下文与最高 Max 推理级别；模型选择器新增 Fast 模式，可提高响应速度，同时增加订阅用量。
* **手动重置 Codex 使用限制。** ChatGPT 订阅设置会列出可用的使用限制重置额度与到期日期；确认后可消耗一次额度，手动重置当前符合条件的 Codex 用量周期，并自动刷新配额。
* **聊天输入历史。** 聊天输入框支持通过上下方向键恢复历史用户消息，同时恢复附件与输入意图，并在返回末尾时还原当前草稿。
* **双击快捷键中止响应。** 新增可配置的双击中止响应快捷键，默认使用 Esc；第一次按下会提示，再次按下才会中止当前响应。

### v0.5.7（修复）

* Unity 文档导入支持当前的 `cloudmedia-docs.unity3d.com` 下载域名，并兼容旧 Google Storage 地址。
* Esc 会优先关闭当前预览、弹层和 diff 窗口，再处理全局响应中止快捷键。

### v0.5.6（新增）

* **本地文件导入知识库。** 外部源支持把本地文件或文件夹导入为引用文件夹，两种模式：**实时链接**通过操作系统链接（junction/symlink）直接挂载本地路径，内容始终是磁盘上的最新状态、文档保持只读；**快照导入**一次性复制当前内容，可选择允许 AI 编辑，并支持手动同步源路径变化。其中 Markdown / 文本文档（`.md` / `.markdown` / `.txt`）会进入知识检索。删除实时链接引用只解除链接，不改动源文件。(#85)
* **聊天 LaTeX 公式渲染。** 消息中的 LaTeX 公式以 KaTeX 渲染，识别 `$…$`、`$$…$$`、`\(…\)`、`\[…\]` 定界符。

### v0.5.6（修复）

* chat-completions 请求按序列化后的字节原样发送，请求日志记录的也是同一份字节；当服务商以 JSON 解析错误拒绝请求时，报错会说明请求体很可能在传输途中被损坏（代理、VPN、安全软件或网关），并建议用 curl 重放确认。(#106)
* 长流式回复不再随内容增长越来越卡：正文、思考过程与打字机改为增量追加新内容，不再整段重渲染。
* 流式回复结束的瞬间消息列表不再闪烁。

### v0.5.5（新增）

* **按文件撤回。** 变更面板、diff 审查窗口及新增的行右键菜单支持把单个文件恢复到本轮修改前的快照，不影响撤销栈；若该文件之后还有编辑，会先询问再回滚。(#100)
* **模型请求自动重试。** 连接错误、超时、HTTP 5xx 与 429 限流自动重试，429 遵循 `Retry-After`；仅在尚未流式产出任何内容前重试；次数可在通用设置调整（默认 3，设 0 关闭）。(#101)
* **内联 `<think>` 标签转入思考通道。** chat-completions 与 OpenRouter 路径上，流式正文中的 `<think>…</think>` 片段会从消息正文剥离并作为思考过程展示（默认开启）。
* **子代理限制。** 通用设置提供 `subagent` 最大嵌套深度与单会话最大并发（默认深度 1）；超限调用会返回错误并说明当前限制。
* **`/dream` 记忆整理技能。** 内置技能：合并重复记忆、修正过期事实、精简记忆索引。

### v0.5.5（修复）

* 自动压缩的保留与请求预算按模型上下文窗口缩放，并识别更多供应商的「prompt 过长」报错，小上下文模型上的压缩现在能收敛。
* 回放历史工具调用时规范化 arguments：空或非法 JSON 变为 `{}` 再发给 chat-completions/OpenRouter 供应商；Codex 路径保持逐字不变。(#94)
* 工作区文件路径改为词法解析，符号链接文件现在能正常打开与定位。(#100)
* 更流畅的长回复流式渲染：已完成的 markdown 块被冻结，流式期间仅重解析尾部。
* 上下文 token 估算不再低估中日韩文本。
* 登录态复查不再重建已打开的标签页；视图预加载，消除首次切换时的闪烁。

### v0.5.4（新增）

* **粘性计划模式。** 计划模式现在是按会话持续的只读模式：Agent 可调研并撰写计划，但在你于对话卡片上批准前不能编辑文件或调用非只读工具。顶部状态栏显示计划模式已启用并提供一键退出；计划期间派生的子代理同样继承只读限制。
* **主日志落盘。** Locus 会把日志（含前端控制台）同时写入滚动文件 `%APPDATA%\locus\logs\locus.log`，崩溃时刷盘。控制台设置新增「定位日志文件」按钮。
* **模型目录更新。** 新增 Fable 5 与 Sonnet 5（1M 上下文），并将 Opus 4.8 设为默认；移除较旧的 Sonnet 4.6、Haiku 4.5 与 Opus 4.7。

### v0.5.4（修复）

* 模型选择器不再显示内部的 `[1m]` 上下文窗口标记。
* 解析 Unity YAML 时，GUID 后紧跟多字节字符不再触发 panic；单引号包裹的标量名称现在能被正确去引号。
* 场景 diff 现在能识别预制体换源与重新挂父级（不再误判为未变化），并跳过逐字节相同的场景目标重建。
* 更快的资产重扫：watcher 对账时不再重新解析未变化的文件；更新后首次启动会重建一次资产数据库（schema v13）。
* 更顺畅的流式输出：缓存诊断/trace 判定、改用更浅的工具调用 watch、批量应用工具结果、稳定消息分组，减少 transcript 的冗余计算。
* 热更新对不安全的改动改为 fail-closed：ref struct 的实例成员、在表达式树内引用的成员、命名空间级 `using` 变更，以及冷 diff 回退。
* 加固 Unity 热更新桥接：应用失败时回滚已下的 detour；重编译完成以编译 epoch 门控，避免请求前的编译误判完成；对正在销毁的 GameObject 跳过组件；并修复收敛竞态与 monitor 停止时的账本交接。

### v0.5.4（移除）

* 移除旧的一次性「计划 → 继续实现」确认卡片；由上述粘性、需批准的计划模式取代。

### v0.5.3（新增）

* **团结引擎（Unity 中国版）支持**：Locus 现在能像识别标准 Unity 一样发现、启动并连接团结引擎编辑器（`Tuanjie.exe`），覆盖进程匹配、原生引擎模块及其 PDB、窗口标题识别。标准 Unity 安装不受影响。
* **新增 Claude 订阅支持**：可登录 Claude 订阅账号，或导入已有的 Claude Code / Codex CLI 登录态（含自定义端点），并在 Anthropic 面板查看订阅剩余额度。
* **网关截断诊断**：Anthropic 请求失败时会记录传输层信息与上游 JSON 解析偏移；当 400 错误疑似为传输中途截断时，Locus 会保存完整的请求字节和一条可直接运行的 `curl`，便于复现并反馈问题。(#48)

### v0.5.3（移除）

* 移除「Claude 订阅已暂停」的提示弹窗及其说明；订阅登录流程已将其取代。

### v0.5.2（新增）

* `unity_code_usages` 的成员查询改为读取资产扫描阶段建立的序列化成员绑定索引：现在能捕获仅按类型串命名（`m_Target: {fileID: 0}`、无 GUID）的断裂/未绑定 UnityEvent 调用，并在整个项目范围内解析 AnimationEvent 函数名，而不再每次查询都重新扫描引用它的场景/预制件以及每个 `.anim` 片段。更新后首次启动会重建一次资产数据库（schema v12）。
* Unity 编辑器解析新增回退到 Unity Hub 安装缓存（`editors-v2.json`），安装在非默认盘符（例如 `D:\` 或 `F:\`）的编辑器现在也能被正确识别。

### v0.5.2（修复）

* Unity 6.5（6000.5）兼容：`GetInstanceID()` 与 `IsLoadingAssetPreview(int)` 变为错误，32 位 InstanceID 被 64 位 EntityId 取代。新增 `LocusObjectIdentity` 垫片，将 EntityId 折叠回低 32 位（保留原有 InstanceID 与通信协议），并按编辑器版本门控已弃用的 build-target API。旧版本编辑器不受影响。(#95)
* 修复中文（CJK）输入导致的资产数据库锁中毒：当搜索词为纯中文，或 `.meta` 文件在 `guid:` 后含中文时，按字节偏移切分会落在多字节字符内部并触发 panic，而该 panic 发生在持有资产数据库锁期间，导致此后所有资产查询失效直至重启。现已改为按字符边界切分。(#97)

### v0.5.2（移除）

* `unity_code_usages` 成员模式不再上报序列化类型串指向其他类的 UnityEvent 调用；现在仅匹配精确的类短名或绑定的脚本 GUID。

### v0.5.1（修复）

* grep 工具改为流式搜索，不再将整个文件读入内存，仅按路径顺序保留前若干个匹配；模式过于宽泛时会提前停止，并说明返回的是不完整、不确定的结果子集。
* 修复在 Unity 嵌入式窗口中点击输入框时的焦点闪烁：仅在目标窗口尚未持有前台时才强制前置，避免覆盖层在失焦与聚焦之间反复跳动。
* 修复 Native Plugin 覆盖层因控制管道名未规范化为完整管道路径而无法连接、覆盖层始终无法挂载的问题。

### v0.5.0（新增）

* 编辑器热更新已实现：Agent 现在能在运行时修改 C# 脚本并实时应用逻辑，能力覆盖主流商业热更新插件。
* Unity IPC 连接已从 C# 插件迁移到使用 Rust 编写的 Native Plugin，可在域重载、Unity 主线程阻塞期间保持连接稳定，并实时上报 Unity 状态。
* C# 编译已从 Unity 进程内迁移到独立的 CoreCLR 进程，旧编译路径暂时保留以作兼容。
* Rust 后端的内存分配器切换为 mimalloc。
* 设置中新增「测试」页面：本版本架构改动较大，可能存在兼容性损失，遇到问题时可运行测试作为参考。
* 向 View Package 暴露了更多 API。

### v0.5.0（修复）

* 资产数据库的性能与正确性优化。
* 修复消息记录在某些情况下隐藏最后一条工具调用的问题。
* grep 工具的路径现按工作区目录解析。


# 页面提示
Source: https://unity.farlocus.com/overview/page-tour

各个页面的简要使用提示

## 会话

<img alt="img" />

发送消息前，请确认输入框左上角的`资产数据库`与`Unity编辑器连接`正常运作。

* **多模态输入**：输入框支持图片上传与解析，可以使用`CTRL+V`粘贴。
* **新建会话**：点击左上角的`+`图标或使用快捷键`CTRL+N`（快捷键可在设置页面自定义）
* **执行权限控制**：位于右下角。开启自动模式时，Agent 的工具调用将免审批执行；关闭后，Agent 的任何修改操作均会向用户请求权限，此模式安全性更高但需手动确认。
* **模型切换**：位于右下角，用于切换当前会话所使用的 AI 模型。
* **发送消息**：默认快捷键为`ENTER`，可在设置页面修改为`CTRL+ENTER`。
* **会话列表管理**：点击左侧列表项旁的`>`可展开查看 Subagent 的详细执行过程。列表项支持右键菜单（归档、删除等操作）以及按住`SHIFT`键进行批量多选。

## 协作

<img alt="img" />

* **版本控制交互**：底部命令行区域支持直接输入标准的 Git 指令或使用自然语言向 AI 下达指令。
* **修改列表显示模式切换**：修改列表右上角的三个按钮可以切换显示模式。
* **上下文菜单**：右键点击 Commit 记录或已修改的文件可唤出扩展功能菜单。
* **变更预览与解析**：点击右侧文件列表（涵盖 Commit、Stash、Unstaged/Staged 区域）可预览文件差异。系统原生支持 Unity YAML 资产文件（如 Scene、Prefab、ScriptableObject 等）的可视化解析。
* **冲突解决**：在合并发生冲突时，系统支持基于上下文的逐字段语义合并。
* **Locus 相关文件标记**：带有 Locus 标记的文件为 Agent 本身的知识或配置文件（默认情况下，除了 `user_preference` 外的记忆与理解在项目层级上共享）。如无需将其纳入项目的版本控制，建议将其加入 .gitignore 文件中

## 知识

<img alt="img" />

### 知识类别

知识库是 Agent 获取项目上下文的核心来源。当前知识体系划分为以下四种类别：

* **Design（设计规范）**：记录项目设计需求与事实基准。AI 可在会话中根据业务需求自动更新此文档（需用户审批介入），用户也支持随时手动编辑维护。
* **Memory（记忆库）**：由 AI 自动维护的动态上下文。系统默认预设三个基础模块（用户偏好、错题本、项目理解）。用户可新建文档并定义专属的维护规则，AI 将按规则进行自动迭代。
* **Skill（技能库）**：用于固化标准化的高频工作流。用户可通过自然语言描述特定流程，指示 Agent 在遇到同类场景时按此 Skill 规范执行。
* **Reference（参考资料）**：外部只读文档库。目前支持导入 Unity API Reference 等本地文档或接入外部协作平台（如飞书文档）。

### 检索策略

系统支持以下两种文档检索机制：

* **词法索引（默认关闭）**：基于关键词提取进行精确文本匹配。
* **语义索引（需在下方检索设置中开启）**：基于文本向量化技术。系统会根据 AI 侧输出的语义片段，检索文档库中含义相近的段落，适用于文档的模糊查询。

<img alt="img" />

## 设置

设置页面用于管理全局系统配置。

### 模型配置

支持自定义模型参数、配置第三方 API 端点（Endpoint）以及管理订阅账号的登录与授权状态。

<img alt="img" />


# 路线图
Source: https://unity.farlocus.com/overview/roadmap

Locus 后续开发规划

## 正在实施

* **更多Unity领域知识SKILL**：PSD To UI、创建粒子系统、编写自定义渲染管线
* **更多数据格式**：支持将项目中的配置以表格形式保存，可以进行 CSV-Unity 的数据同步、动态读入作为项目中唯一事实来源
* **更多专用工具**：3D 资产预览工具；前端显示增强工具（绘制流程图、曲线图、聚合数据视图等）；更多数据编辑工具（CSV、Excel）

## 队列中

* **端到端模式增强**：通过启动独立Unity编辑器进程测试游戏、编辑器内截图、编写测试输入脚本、单独上下文评估，增强模型对实现功能的测试、评估能力
* **即时通讯软件**：支持通讯软件收发会话消息
* **Unity编辑器拓展**：在Unity控制台上加入Locus操作；向C# API暴露Locus的搜索、解析能力等

## 讨论中

* **更多版本管理软件支持**：P4、SVN支持
* **安全性增强**：使用小模型审核工具调用安全性
* **本地语言模型部署**：在Locus中提供可选的本地模型运行时，用于explorer等相对简单并且花很多token的任务
* **外部工具导入**：支持MCP、CLI等方式导入外部工具


# 使用建议
Source: https://unity.farlocus.com/overview/usage-guidance



## 以动态的视角理解 AI 能力

在一定程度上，可以将 AI 视为一位技术能力较强、但缺乏游戏审美与体验判断能力的技术策划或客户端开发同事。

目前的前沿模型在具体、明确的编程任务以及数学问题求解上，已经展现出超过大多数程序员的能力。然而，作为语言模型，它仍然缺乏对 Game Feel 的真实理解，也无法天然判断何种 UI 布局更合理、何种交互反馈更符合玩家预期。

在短期项目中，团队可以在不完全理解其实现细节的前提下，以较高速度完成原型开发与迭代，即通常所说的`Vibe Coding`。

但在严肃的长期项目中，开发者应当审阅 AI 作出的技术决策，并理解其具体实现方式。只有这样，问题出现时，团队才具备持续维护与修复的能力。若对其实现原理缺乏基本理解，后续排障与修复过程将高度依赖反复尝试；一旦 AI 无法继续修复，项目的可维护性与延续性都会受到直接影响。

对于大型项目，我们建议由程序开发者主要使用 Agent 进行框架层开发，由不具备技术背景的策划通过程序预先提供的 `Skill`（或某些具体限制）开发具体玩法功能。策划侧应避免直接提出框架层面的工程变更需求——例如“我想要玩家在雪上踩出脚印”这类听起来朴素的需求，可能会直接让 Agent 写出一个涉及底层架构设计的「虚拟纹理」系统。

同时，基础模型能力仍在快速演进。前沿模型的发布周期已经从过去的一年、半年，缩短至两个月左右。与之相应，Agent 的使用范式也会持续变化。一年多以前，受限于上下文长度与工具能力，模型尚难以独立完成今天常见的 Agent 任务。因此，本页提出的规范具有阶段性特征，未来数月内便可能需要调整。

现阶段，AI 在开发过程中出现错误属于正常现象。你可以在 Unity 中进行测试，并将结果反馈给它继续修正，很多问题经过数轮迭代后都可以得到解决。若某一问题长期无法修复，重新开启一个新对话，并让新的 AI 基于既有功能进行分析与排查，通常会更加有效。

后续我们还将通过两篇技术博客，更系统地阐述我们对游戏开发 Agent 的使用理解：

* Harness Engineering for Game Projects
* Building Dev Agent for Game Engines

## 具体且正确的指令优于模糊指令，模糊指令优于具体但错误的指令

应尽可能向 AI 提供充分且准确的上下文信息，使其明确理解需求目标。

例如：

* 当你希望实现某个功能时，应说明该功能的用途，以及预期的设计细节。
* 当你希望实现某种玩法时，应描述该玩法应呈现出的体验感受、可能的参考对象，以及关键设计细节。
* 当你希望修改项目中的既有功能时，应说明该功能当前的状态、修改原因，以及你设想中的可能调整方向。

对于不熟悉代码的策划、美术，或尚未对当前需求的技术实现形成清晰判断的成员，建议避免向 AI 描述过于具体且确定的技术路线。因为在技术前提判断存在偏差时，过度明确的实现路径往往会将 AI 引导到错误方向，并持续在该方向上投入实现细节。

## 复杂任务应先产出方案并完成 Review，再进入执行阶段

许多表面上看似简单的游戏逻辑，实现起来往往非常复杂。对于游戏策划与程序开发者而言，对此应该都有深有体会。

以横版跳跃游戏中的“跳跃”功能为例，其背后可能涉及很多复杂的技术决策，例如：角色动作逻辑是否需要采用状态机或状态树结构维护、是否需要加入“土狼时间”、起跳与落地过程中的速度变化参数如何设计以控制曲线等。

在传统开发流程中，客户端程序通常需要承担与策划反复沟通、将未明确写入策划案的隐含需求补足并落实为代码的职责。而默认状态下的 AI，更倾向于以最快速度完成表面需求。若仅用一句简短描述直接要求其实现功能，AI无法掌握项目的基本设计目标与长期演进方向，最终效果很可能与预期存在偏差。

因此，对于复杂需求，更推荐先要求 AI 不修改任何文件，而是先输出实现方案，与使用者通过对话充分确认需求、边界条件和关键设计，再进入实际编码阶段。

尽管 AI 无法真正理解 Game Feel，但它熟悉大量既有游戏的典型实现方式。对于已有成熟范式的内容，也可以主动向它询问“如何优化手感”。例如，一位缺乏横版跳跃游戏经验的开发者，未必会自然想到“土狼时间”这类设计；而 AI 往往能够给出具备参考价值的建议。

另一方面，过去策划希望推动某项功能落地，往往需要与程序进行充分沟通，因为开发成本较高。如今，功能实现与迭代速度已经显著提升，策划也可以用更低成本快速验证想法。因此，在很多场景下，策划无需像过去那样花费大量时间打磨完整方案、反复说服程序资源投入后再开始尝试，而是可以更快进入原型验证与玩法迭代阶段。Locus中AI从会话中总结设计文档的功能，也是基于这种想法产生的。

## 定期维护知识库

我们为 Locus 提供自动维护知识库的能力，是希望它能够在持续与你交流和参与项目的过程中，逐步形成对项目的更深入理解。

其中，`Design` 部分需要重点关注。它代表 AI 对你需求的总结与归纳，并会在后续任务中将这些内容视为需求依据。因此，确保其中信息准确，属于使用者的重要责任。

`Memory` 则是 AI 基于项目工程与上下文自行总结出的经验性信息。你也可以定期检查其内容是否准确，并根据实际情况手动修改或删除相关条目。

后续我们会提供一个专门的 Skill，用于帮助 AI 更系统地维护项目知识库。

## 独立的任务应该在独立的上下文（新会话）中完成

界面右下角会显示一个进度条，用于表示当前会话上下文的使用情况。

当前语言模型虽然可以处理较长文本，但上下文容量仍然有限。当下文混入很多不相关的工具调用结果与判断时，模型能力会显著下降。因此，针对相互独立的任务，仍然应尽量开启新的会话，在独立上下文中处理。除此之外，更长的上下文也意味着更高的 cache read 开销，以及每次工具调用时更高的成本。

为了提升模型效果并控制使用成本，建议尽可能将可拆分的任务进行拆分，并在独立上下文中分别处理。


# 文件变更与撤回
Source: https://unity.farlocus.com/sessions/changes-and-undo

变更面板、差异查看与单文件或整轮撤回

Agent 的每一处文件改动都会被记录。你可以随时查看差异，也可以按单个文件或整轮对话撤回。

## 变更面板

点击输入框上方的`文件修改`按钮展开面板：

* **范围切换**：`当前轮次`只看本轮改动，`全部修改`列出本次对话以来的所有改动。
* **状态分类**：每个文件标注 `Modified`、`Added`、`Deleted` 或 `Renamed`。
* **自动弹出**：默认在产生文件修改时自动打开面板。「设置 → 显示」的`面板行为`中可关闭自动打开，或开启发送新消息时自动关闭。

## 查看差异

* **内嵌查看**：点击文件或在文件的`文件操作`菜单中选择`查看差异`，在当前窗口查看改动前后的对比。
* **独立窗口**：选择`独立窗口`把差异审查开到单独的窗口中，适合双屏或长差异。默认打开位置可在「设置 → 显示」的`文件修改审查`中指定。

## 撤回

### 单文件撤回

在变更面板中打开某个文件的`文件操作`菜单，选择`撤回此文件`，将该文件恢复到本轮修改前的状态。其他文件和对话记录保持不变。

### 整轮撤回

* **变更面板**：`当前轮次`模式下点击`撤销本轮修改`，`全部修改`模式下点击`撤销全部修改`。整轮撤销会同时回退对应的对话记录。
* **`/undo` 命令**：弹出`撤回一轮对话`对话框，提供两种模式：
  * **`仅撤回会话`**：只回退对话记录，磁盘上的文件保持现状。适合文件改动想保留、但希望对话回到上一轮重新指挥的情况。
  * **`撤回文件 + 会话`**：文件与对话一并回退。

消息菜单中的`撤回到这条消息`可直接回退到任意历史消息处，见[会话页面](/sessions/index)。

## 脏写警告

撤回点之后文件又被改过时，Locus 会先提示再执行：

* **本会话的后续修改**：提示`该轮结束后这些文件又有新的修改，撤销时会一并回退`，并列出受影响的文件。确认后这些额外修改会随撤销一起消失。
* **其他会话的修改**：本次撤销会覆盖其他会话里更新的文件时，需要先检查列出的冲突文件，再决定是否点击`强制撤销`。
* **单文件撤回**：同样有对应提示，确认按钮为`仍要撤回`。

## 原理：基于 Git 快照

Locus 依赖版本管理实现「撤销」与「变更分析」：每轮开始前记录文件快照，撤回即把文件恢复到对应快照。因此撤回能力要求项目已完成 [Git 配置](/overview/install-and-setup)，Locus 使用的 Git 版本可在「设置 → 通用」的`Git 运行时`中选择。撤回只作用于 Agent 会话记录的改动范围；跨会话、跨提交的版本操作请使用「协作」页面，见[协作与提交](/collaboration/changes-and-commit)。


# 上下文与成本
Source: https://unity.farlocus.com/sessions/context

上下文用量指示、自动压缩与原始上下文导出

语言模型能处理的上下文有限，且上下文越长，效果越差、成本越高。Locus 在界面上持续显示用量，并在接近上限时自动压缩。

## 用量指示

输入框下方有一个环形进度指示，悬停显示明细：

* **`上下文 X / Y (Z%)`**：当前会话占用的上下文 token 数、模型上下文窗口上限与占比。占比超过 60% 时指示变黄，超过 80% 变红。
* **`Cost $N`**：本会话累计的模型调用费用估算，仅在所用模型有定价数据时显示（订阅类供应商通常不显示）。

自定义端点的上下文窗口大小可在端点配置中设置，见[模型配置](/settings/models)。

## 自动压缩

会话占用接近上下文窗口上限（约九成）时，Locus 自动触发压缩，对话区显示`正在压缩上下文…`与`上下文已压缩`。

压缩保留什么、丢什么：

* **保留**：最近的消息往来原文；关键技术决策、代码变更、未完成任务等重要上下文，被整理成一份交接摘要。
* **丢弃**：较早的完整往来与冗余的中间过程，例如已经过时的工具调用输出。
* **恢复**：压缩后自动把最近读过的少量关键文件内容重新带回上下文，减少 Agent 重新读文件的往返。

若某次请求直接超出模型上下文窗口，Locus 也会兜底压缩并提示`上一请求超出模型上下文窗口，已自动压缩对话历史`。

压缩是有损的：摘要不可避免会丢失细节。长会话多次压缩后，Agent 对早期讨论的把握会下降。

## 手动 /compact 的时机

不必等自动触发，以下时点主动输入 `/compact` 更有利：

* 一个阶段性任务刚完成、下一个任务即将开始，此时中间过程最适合被总结掉。
* 上下文占比进入黄色区间，而你预计接下来还有大量工具调用。
* 对话里堆积了大量报错输出与重试过程，这些内容对后续工作没有参考价值。

## 上下文导出

排查 Agent 行为异常时，可以导出会话的原始上下文：在会话列表右键目标会话，选择`保存上下文（带系统提示词）`或`保存上下文（不带系统提示词）`。导出内容为每轮 API 请求与响应的原文，可以确认模型实际收到了什么、注入了哪些规则与知识。向他人提供复现材料时，注意导出文件可能包含项目代码与文档内容。

## 独立任务开新会话

上下文里混入大量不相关的工具调用结果时，模型能力会显著下降，同时带来更高的 cache read 开销。相互独立的任务应尽量开启新会话处理，这也是控制成本最有效的手段。完整讨论见[使用建议](/overview/usage-guidance)中「独立的任务应该在独立的上下文中完成」一节。


# 会话页面
Source: https://unity.farlocus.com/sessions/index

会话界面分区、输入框用法与会话列表管理

「会话」页面是与 Agent 交互的主入口。

<img alt="img" />

## 界面分区

* **会话列表**：左侧列表管理所有会话，支持右键菜单与多选。
* **对话区**：中间区域显示消息往来、工具调用过程与各类审批卡片。
* **侧边面板**：对话区右侧可展开`任务列表`与`文件修改`面板，跟踪 Agent 当前的待办与文件改动，详见[文件变更与撤回](/sessions/changes-and-undo)。
* **输入框**：底部输入区。上方一排状态指示（`资产数据库`、`Unity编辑器已连接`等），发送消息前请确认它们正常运作；下方是模型选择器与上下文用量指示。

## 输入框

* **多行输入与发送**：默认快捷键为`ENTER`，可在「设置 → 快捷键」修改为`CTRL+ENTER`，此时`ENTER`用于换行。
* **@ 引用**：输入 `@` 可搜索并引用项目资产、文件、文件夹或知识文档，也可以直接把文件拖入输入框。引用工作区外的文件时，若已开启文件工具边界会收到提示，见[执行权限](/sessions/permissions)。
* **图片粘贴**：输入框支持图片上传与解析，可以使用`CTRL+V`粘贴。
* **斜杠命令**：输入 `/` 查看命令列表。

| 命令               | 作用                       |
| ---------------- | ------------------------ |
| `/clear`         | 清空当前会话并开始新对话             |
| `/compact`       | 压缩当前上下文并总结历史消息           |
| `/fork`          | 复制当前会话并切换到副本             |
| `/undo`          | 撤回上一轮对话                  |
| `/unity-console` | 附加当前 Unity Console 消息    |
| `/console-error` | 仅附加当前 Unity Console 错误消息 |
| `/plan`          | 进入规划模式（仅 Dev 会话可用）       |

安装的技能也可以注册自己的斜杠命令，例如 `/view` 与 `/plugin`。

## 模型与 effort 切换

输入框下方的模型选择器按供应商分组：`OpenRouter`、`Claude 订阅账户`、`Claude Code CLI`、`ChatGPT 订阅账户`、`自定义`。模型支持推理强度时，旁边会出现 `effort` 档位选择，从`不思考`到`最高推理`，档位越高推理越深入、耗时与费用也越高。默认模型可在「设置 → 默认模型」按场景指定，见[模型配置](/settings/models)。

## 运行中发送消息

Agent 正在执行时仍可继续输入，发送时有两种处理方式：

* **`加入队列`**：本轮结束后作为下一条消息发送，输入框上方显示`待发送`。
* **`插入`**：在下一次工具调用后插入当前对话，Agent 立即参考新信息继续工作，显示`待插入`。

默认行为在「设置 → 快捷键」的`运行中发送`中选择（`排为下一条`或`插入当前会话`）。

## 会话列表管理

* **新建会话**：点击列表上方的`+`图标或使用快捷键`CTRL+N`（快捷键可在设置页面自定义）。
* **右键菜单**：`重命名`、`在 Unity 中打开`、`保存上下文（带系统提示词）`、`保存上下文（不带系统提示词）`、`归档会话`、`删除会话`。归档的会话可在「设置 → 归档会话」中查看或恢复。
* **多选**：按住`CTRL`逐个加选、按住`SHIFT`范围多选，随后可批量归档或删除。
* **子代理展开**：点击列表项旁的`>`可展开查看 Subagent 的详细执行过程。
* **复制会话**：使用 `/fork` 复制当前会话并切换到副本。子会话（Subagent 会话）不能复制。

## 消息菜单

右键单条消息可唤出菜单：

* **`复制这条消息`**：复制消息文本。
* **`重新编辑`**：把这条用户消息填回输入框修改后重发。
* **`撤回到这条消息`**：回退对话到该消息之前的状态。
* **`从这条消息 Fork`**：以该消息为分叉点复制出新会话，原会话保持不变。


# 执行权限
Source: https://unity.farlocus.com/sessions/permissions

工具执行模式、审批卡片与文件工具边界

Agent 通过调用工具来读取和修改项目。「设置 → 工具权限」控制哪些调用可以直接执行、哪些需要先经过确认。

## 自动模式与逐一审批的取舍

`工具执行模式`有两档：

* **`Auto`**：自动执行所有工具，免审批，效率高。适合原型验证或已充分信任的仓库（并配合版本管理）。
* **`Ask`**：按单项工具规则确认。Agent 的修改操作会向你请求权限，此模式安全性更高但需手动确认。

## 权限的层级

* **全局模式**：`Auto` 直接放行全部工具调用；`Ask` 时才逐项检查下方规则。
* **单项工具权限**：`Ask` 模式下，每个工具可以单独设为 `Auto` 或 `Ask`。未单独设置时使用默认值：读取类工具（`read`、`grep`、各类查询与搜索）默认自动执行；修改与执行类工具（`write`、`edit`、`bash`、`web_fetch`、`unity_execute`、`unity_run_states`、`subagent`）默认需要确认。
* **行为确认**：独立于全局模式的额外确认闸门，见下文。

## 审批卡片

需要确认的工具调用会在对话区弹出`工具执行确认`卡片：

* **单条审批**：查看工具参数（文件修改会显示差异预览），点击`允许`或`拒绝`。
* **批量审批**：多项调用同时等待时合并为一张卡片，可`全部允许`、`全部拒绝`，或展开逐条处理。
* **附反馈**：不满意提案时，在`评价修改方案`中描述需要调整的地方再提交，Agent 会据此重写方案后重新请求确认；批量卡片支持`批量提交意见`，整批一起退回修改。

## 行为确认

「设置 → 工具权限」的`行为确认`一节控制工具执行过程中额外等待确认的行为。这类确认独立于全局模式：即使全局为 `Auto`，设为 `Ask` 的行为仍会弹出确认。两项默认均为自动放行：

* **`切换 Unity 编辑器状态`**：进入或退出运行态、暂停运行态、编辑态。设为 `Ask` 后，Agent 请求切换 Play Mode 时会弹出`请求进入运行状态`确认框，显示当前状态与目标状态。
* **`修改受保护知识`**：修改 Design、Skill、Reference 或需要审批的知识目录时先经确认，确认卡片会展示内容或结构的变更预览。知识库分类见[知识库](/knowledge/index)。

## 文件工具边界

`文件工具边界`控制文件类工具的路径范围：

* **`全部`**（默认）：允许访问工作区外的路径。
* **`工作区`**：文件工具仅在当前项目目录内使用。开启后在输入框引用外部文件时会提示`文件工具边界已开启，模型只能读取工作区内路径`。

## 为什么修改类工具默认需要确认

读取类调用不改变项目状态，出错的代价只是浪费一次查询；而写文件、执行命令、切换 Unity 运行状态都会产生实际影响，一旦方向错误，修复成本远高于确认一次的成本。默认规则把确认集中在有副作用的操作上：既保留了 Agent 自主搜索、分析的流畅度，又保证每一次实际改动都经过你的判断。当你与 Agent 在某类任务上建立信任后，再逐项放宽到 `Auto`。

文件改动另有一层保障：确认与否，每轮修改都被记录，可随时查看差异并撤回，见[文件变更与撤回](/sessions/changes-and-undo)。


# 计划模式
Source: https://unity.farlocus.com/sessions/plan-mode

先产出实现方案，批准后再开始改动

计划模式（Plan mode）让 Agent 在只读状态下调研项目并产出实现方案，方案经你批准后才开始实际改动。

## 什么时候用

许多表面简单的游戏逻辑实现起来非常复杂，直接下达一句话指令，Agent 倾向于以最快速度满足表面需求，结果容易偏离预期。对于复杂需求，更推荐先让 Agent 输出实现方案，通过对话确认需求、边界条件和关键设计，再进入编码阶段。这一工作方式的完整讨论见[使用建议](/overview/usage-guidance)中「复杂任务应先产出方案并完成 Review」一节。

适合计划模式的典型场景：

* 涉及多个系统的功能开发，例如新的玩法模块、自定义渲染管线。
* 对既有架构的调整，需要先确认影响范围。
* 你自己尚未想清楚技术路线，希望先看几种可选方案。

## 进入与退出

在输入框输入 `/plan` 并描述任务即可进入（仅 Dev 会话可用）。进入后对话区顶部会出现粘性横幅：`规划模式（只读）— 计划批准后才会开始改动`，随时可点击横幅上的`退出规划`手动退出。

「设置 → 默认模型」中可为计划模式单独指定`Plan 模式模型`，进入计划模式时自动切换，例如用推理更强的模型做方案、用更快的模型做执行。

## 只读状态的含义

计划模式下 Agent 可以读文件、搜索代码与资产、查询知识库、抓取网页文档，也可以派生子代理做调研（子代理同样被限制为只读）。所有修改类工具被拦截：写文件、执行命令、操作 Unity 都不可用。唯一的例外是计划文件本身，Agent 会把方案写入其中并持续完善。

## 计划文件的写入范围

计划内容写入 Locus 本地数据目录下按项目和会话划分的 Markdown 文件，不会写进你的项目目录。规划过程不会在工作区产生任何文件改动，也不会污染版本管理状态。

## 计划审批

方案成形后，对话区会弹出`计划待批准`卡片，展示完整计划内容：

* **`批准并开始实现`**：退出规划模式并立即开始实现。
* **`继续规划`**：拒绝当前方案，可附带反馈说明需要调整的方向，Agent 会继续完善计划后再次提交。

批准后进入正常执行阶段，工具调用回到[执行权限](/sessions/permissions)所配置的审批规则之下，文件改动照常被记录，可随时[查看与撤回](/sessions/changes-and-undo)。


# 代码分析
Source: https://unity.farlocus.com/settings/code-analysis

C# 语言服务与代码工具的开关配置

「设置 → 代码分析」控制 Agent 的 C# 语义分析能力。开启后，Agent 查找引用、跳转定义时得到的是编译器级别的准确结果，而不是文本搜索的近似匹配。

## C# 代码分析总开关

基于 Roslyn 语言服务的 C# 语义分析：组件按需下载，并加载 Unity 生成的解决方案。所有 `code_*` 工具都依赖此开关。

开关旁实时显示服务状态：`准备组件中` → `下载组件` → `调用 Unity 生成工程文件中` → `启动分析服务中` → `加载项目中` → `代码分析就绪`；出错时显示具体错误信息。分析结果异常或项目结构大改后，可点击`重启`重启分析服务并重新加载项目。会话页输入框上方的 `C# 代码分析`状态指示同样能查看状态并重启。

## 简单原理

Unity 项目的 C# 代码里，同名方法、字段随处可见，纯文本搜索无法区分 `Player.Reset()` 与 `Enemy.Reset()`。语言服务把整个解决方案真正编译一遍，理解每个符号的类型与归属，因此 Agent 能拿到语义级精确的引用列表和签名信息，改代码前后也能立即得到编译器诊断，减少凭记忆猜 API 造成的错误。代价是首次启动需要下载组件并加载项目，大项目加载需要一些时间。

## Roslyn 工具

逐项开关，关闭的工具会从 Agent 的工具列表中完全移除。总开关关闭时，以下工具无论开关状态如何都不会提供给 Agent：

* **`code_symbol_search`**：在整个工作区内搜索 C# 符号（类、方法、字段）。
* **`code_goto_definition`**：解析符号的声明位置，包括其他程序集与 package。
* **`code_find_references`**：语义级精确查找符号的全部代码引用。
* **`edit/write 诊断`**：Agent 修改 Unity C# 文件后，自动返回有上限的文件级错误、警告与项目字符串引用检查，构成"改完即验证"的回路。
* **`code_diagnostics`**：不切到 Unity 即可获取编译器与分析器的错误和警告；file 模式同时校验 tag、layer、场景、Resources、Input 字符串是否存在于项目配置。
* **`code_hover`**：查询符号的精确签名、类型与文档（IDE 悬停信息），避免 Agent 凭记忆猜 API。
* **`Unity 分析器（UNT*）`**：注入 Microsoft.Unity.Analyzers，为 `code_diagnostics` 提供 Unity 特化诊断，并压制对 Unity 代码具有误导性的通用 C# 提示。切换后会自动重启分析服务。

## 资产侧工具

把 C# 符号桥接到 Unity 资产数据与项目配置，不依赖 Roslyn 服务：

* **`unity_code_usages`**：查询脚本或成员在场景、预制体、资产中的序列化使用，包括挂载点、UnityEvent 绑定、序列化字段与 AnimationEvent。代码侧的"查找引用"看不到这些资产里的使用点，删改脚本前让 Agent 先查一遍，可以避免破坏场景中的绑定。该工具依赖资产数据库，见[资产页面](/assets/index)。

同属`代码与 Unity` 分组的`热更新与编译`、`Unity 连接`、`测试`标签，见 [Unity 执行与编译](/unity/execute-and-compile)与[热更新](/unity/hot-reload)。


# 通用设置
Source: https://unity.farlocus.com/settings/general

界面、通知、快捷键、代理、日志与运行时环境

「设置」左侧`通用`分组集中了界面与运行环境相关的配置，本页按标签逐个介绍。

## 通用

* **`界面语言`**：切换界面显示语言。
* **`调试模式`**：开启后每次大模型 HTTP 请求会被保存到调试目录（开发构建为 `debug/llm/`，发布构建为 `data/debug/llm/`），`Authorization` 等敏感请求头会被自动脱敏。排查请求内容时开启，平时保持关闭。
* **`模型请求自动重试`**：模型请求失败（连接错误、超时、HTTP 5xx 与 429 限流）时的自动重试次数，默认 3 次，可设 0 到 10；仅在尚未产生任何输出前重试，429 会遵循服务器的 Retry-After 建议，设为 0 关闭。
* **`Unity 后台加速`**：修复 Unity 窗口在后台时的编辑器循环降速，让 Agent 的编译与命令不必等你切回 Unity。
* **`关闭行为`**：点击关闭主窗口后`直接退出应用`或`最小化到托盘`。
* **`本地数据存储`**：会话与记忆文件的存放位置（Knowledge 保留在项目目录中），可`打开目录`或`更改位置`，迁移在重启后完成。
* **`临时文件`**：工具大输出与运行临时文件的存放处，`清理`可释放空间。清理后历史会话仍可打开，已清理的大工具输出会显示为`完整输出已删除`。
* **`Git 运行时`**：Locus 使用这里选择的 Git 执行版本控制、撤销和变更分析，可选托管 Git 或系统已安装的 Git。
* **`Python 运行时`**：bash 工具调用 `python` / `pip` 时使用的解释器，托管 Python 的依赖安装到数据目录，不污染系统环境。
* **`重置所有设置`**：清除当前配置并重新进入初始引导。

## 显示

* **`主题`**：主窗口与 Unity 嵌入窗口分别选择`跟随系统`、`亮色`或`暗色`。
* **`主界面`**：控制顶部导航入口的显隐，可分别开关`知识`、`协作`、`资产`、`视图`、`插件`、`Agent` 标签页。
* **`面板行为`**：任务列表与文件修改面板的自动打开与关闭，见[文件变更与撤回](/sessions/changes-and-undo)。
* **`字体`**：分别自定义界面、正文、行内代码、代码块与编辑器区域的字体。

## 通知

* **`系统通知`**：窗口未聚焦时为关键对话事件发送系统通知，可分别开关对话完成、Subagent 完成、需要输入、对话出错、需要确认五类事件。
* **`提示音`**：同样五类事件可播放提示音，支持内置音源（`柔和`、`清脆`、`警示`三种模式）或自定义音频文件，可调音量并预览。

## 快捷键

* **`发送方式`**：`Enter 发送`（修饰键+Enter 换行）或修饰键+`Enter 发送`（Enter 换行）。
* **`运行中发送`**：会话运行中发送消息的默认处理，`排为下一条`或`插入当前会话`，见[会话页面](/sessions/index)。
* **`新建会话`**：自定义组合键。点击`录制`后按下组合键，至少包含一个修饰键。

## 代理

`代理模式`决定 Locus 后端请求的网络路径：

* **`自动代理发现`**（默认）：读取环境变量和系统代理配置。
* **`系统代理`**：后端请求读取系统代理配置。
* **`手动配置代理`**：使用手动填写的`代理地址`，如 `http://127.0.0.1:7890`。
* **`禁用代理`**：后端请求直连。

页面下方的`请求路由`实时显示每类请求实际走的路径，便于确认代理是否生效。

## 控制台

查看前端与后端的统一调试输出。支持按级别（`Trace` 到 `Error`）与来源（`前端`/`后端`）过滤，按模块名或日志内容搜索。后端 debug 与 trace 级别日志受`通用 → 调试模式`控制。日志同步写入本地文件，崩溃后仍可查看；`导出日志`打包当前输出，`定位日志文件`直接打开日志所在目录，反馈问题时附上导出结果最有效。

## 归档会话

查看已归档的会话记录。归档后不会出现在会话列表中，但仍可在这里打开查看内容或`取消归档`恢复。

## 关于

显示当前版本与联络方式。`更新通道`可选`稳定版`或`实验性`：实验性通道更早拿到新功能，稳定性相对较弱。`检查更新`手动拉取最新版本信息。


# 模型配置
Source: https://unity.farlocus.com/settings/models

订阅登录、自定义端点与默认模型

Locus 须配置远程 AI 服务作为其推理引擎，远程大模型的性能将直接影响 Locus 的工作效果。「设置」左侧`模型`分组下有两个标签：`模型管理`负责接入供应商，`默认模型`负责按场景指定模型。

<img alt="img" />

## 订阅账户登录

* **`Claude 订阅账户`**：点击`登录`后在浏览器中登录 Claude 账号，授权后复制页面上显示的授权码并粘贴回 Locus。已安装 Claude Code 时可选择`从 Claude Code 导入`直接复用登录态。登录后显示`剩余额度`（`5 小时`与`1 周`两档限额）。
* **`ChatGPT 订阅账户（设备授权）`**：点击`使用 ChatGPT 账户登录`，在浏览器中访问链接并输入验证码完成授权，兼容 ChatGPT Pro / Plus 订阅。也支持`从 Codex CLI 导入`。登录后显示`短窗口`与`长窗口`的剩余额度。`扩展上下文`默认关闭；开启后 GPT-5.6 使用 372K 原始窗口，自动压缩阈值与 Codex 保持一致。`生成会话标题`默认关闭；开启后，新会话通过当前 ChatGPT 登录使用 GPT-5.6 Luna（low）生成简短标题。
* **`Claude Code CLI`**：Locus 只调用系统 `claude` 命令，登录状态由 Claude Code 自身管理。检测到未登录时，请在终端运行 `claude` 并完成 `/login`。`测试连接`会通过 CLI 发送一个单词探针，按真实运行的方式验证端点、凭据与代理是否可用。该来源的模型默认不出现在模型列表中，需在`默认模型`标签开启`启用 Claude Code CLI 模型`（实验性）。
* **`OpenRouter`**：填入 API Key 即可，统一网关聚合 Claude / GPT / Gemini 等主流模型。

## 自定义模型端点

`自定义模型端点`用于接入任意兼容的 API 服务，包括本地部署的模型。支持三种消息格式：

* **`Anthropic Messages`**：Claude 系 API 及其兼容服务。
* **`OpenAI Chat Completions`**：最广泛兼容的格式，多数第三方与本地推理服务可用。
* **`OpenAI Responses`**：OpenAI 新一代接口格式。

点击`添加自定义端点`填写：

1. `显示名称`：在模型列表中展示的名字。
2. `API 模型代号`：发送给 API 的 model 字段值，如 `gpt-4o`。
3. `请求端点`：含 `/v1` 的 base URL，程序会自动拼接 `/chat/completions` 等路径。
4. `API 格式`与 `API Key`（可选，部分本地模型无需 Key）。

高级选项包括`上下文窗口`（超过此 token 数触发上下文压缩）、`推理强度`（在模型选择器中显示 effort 档位）、`图像理解`（端点可接收截图和图片附件时启用）等。保存后可用`测试`验证连通性；端点支持多个，随时`编辑`或`删除`。

## 默认模型

`默认模型`标签为不同使用场景指定模型，未设置时跟随当前手动选择：

* **`主对话模型`**：主会话默认使用的模型。
* **`Plan 模式模型`**：切换到计划模式时自动使用的模型，可以为方案设计单独指定推理更强的模型，见[计划模式](/sessions/plan-mode)。
* **`子代理模型`**：Agent 派生子任务时各类子代理使用的模型覆盖，未设置时继承当前会话模型。子任务通常更机械，用更快的模型可以明显降低成本。

## 隐私边界

除所配置的远程模型服务调用外，Locus 为纯客户端软件，其余任何信息均不会上传至互联网。会话记录、知识库与配置全部保存在本地，存放位置见[通用设置](/settings/general)中的`本地数据存储`。


# 代码执行与编译
Source: https://unity.farlocus.com/unity/execute-and-compile

Agent 在编辑器内直接执行 C#，配合重编译等待与独立进程的编译服务器

## 在编辑器里执行 C\#

连接 Unity 后，Agent 可以直接在编辑器进程内执行 C# 代码：查询场景对象与组件属性、修改序列化字段、调用编辑器 API、批量处理资产。这类操作在会话中显示为「执行 Unity 命令」等工具调用，与文件修改一样受[权限控制](/sessions/permissions)约束。

这让很多任务不再需要"生成脚本、手动放进项目、点菜单执行、再删掉"的绕行：Agent 想知道场景里有多少个带某组件的对象，直接查询即可；想验证一段逻辑的实际行为，执行一次就有结果。

## 重编译与域重载

修改项目中的脚本文件后，Unity 需要重新编译脚本并执行域重载（domain reload）才能让改动生效。Locus 会在改完代码后主动请求重编译，并等待整个过程结束，期间状态指示显示`Unity 重编译中，等待重连`。

从使用者角度，关于域重载只需要知道一件事：它会重置脚本的内存状态，静态变量回到初始值，编辑器短暂无响应属于正常现象。Locus 会自动等到重载完成、连接恢复后再继续任务，不需要手动切回 Unity 确认（后台等待的加速机制见[运行时状态与后台运行](/unity/runtime-state)）。

## 为什么这条链路重要

真实的 Unity 任务很少止步于"把文件改对"。一次改动要真正落地，通常要走完一条链：修改脚本或资源，让 Unity 感知这些变化，等待编译或域重载完成，回到编辑器验证行为。

Locus 把这条链作为一个整体执行。Agent 改完代码后能立刻拿到编译结果：编译报错会直接回到会话里驱动下一轮修复，编译通过则继续在编辑器里执行验证。"改了但没编译"或"编译失败没人发现"这类断点被消除了，你看到任务完成时，改动已经在编辑器里生效过。

## 编译服务器

Agent 执行的代码片段（以及 View 脚本）需要先编译。默认情况下，这些编译在一个独立进程的编译服务器中完成，而不占用 Unity 编辑器进程：

* **编译更快**：使用现代编译器工具链，不受编辑器负载影响。
* **Play Mode 不掉帧**：运行游戏时执行代码，编辑器不会因编译卡顿。
* **错误直接返回**：编译错误无需经过 Unity 即可回到会话。

编译服务器只负责 Agent 的代码片段；项目脚本的重编译仍由 Unity 自身完成。

开关位于「设置」→「热更新与编译」→ `使用 CoreCLR sidecar 编译`，默认开启。编译服务器出现任何故障都会自动回退到 Unity 内编译，不会中断任务；若怀疑它引起问题，也可以手动关闭此开关，回退到编辑器内编译。[热更新](/unity/hot-reload)依赖此开关。

面板中`编译器`一行显示其状态：`运行中`、`空闲`、`回退 Unity 内置`或`未启用`。


# 热更新
Source: https://unity.farlocus.com/unity/hot-reload

方法体级 C# 改动 1-2 秒内在运行中的编辑器生效，结构性改动自动回退重编译

热更新（实验性功能，默认关闭）把方法体级的 C# 改动编译成补丁，在 1 到 2 秒内应用到运行中的编辑器，跳过 Unity 重编译与域重载。在 Play Mode 里调手感、改数值、修逻辑时，游戏不会被打断，内存状态原样保留。

开启方式：「设置」→「热更新与编译」→ `Unity 热更新（实验性）`，需要先启用同页的[编译服务器](/unity/execute-and-compile#编译服务器)。

## 哪些改动走热更新

* **走热更新**：方法体内部的逻辑改动。改条件、改公式、调参数、换调用顺序，这类改动占日常迭代的大多数。
* **回退重编译**：结构性改动，包括新增或删除字段、修改方法签名、调整继承关系、新增类型等。这些改动会进入`需编译`队列，由一次正常的 Unity 重编译收敛，行为与不开热更新时一致。

判定是自动的，不需要提前声明改动类型。

## 状态面板怎么读

开启后，会话输入框上方出现`Unity 热更新`指示器，展开可见：

* **`未应用修改`**：已检测到、尚未在编辑器中生效的改动数。正常情况下会在一两秒内清零。
* **`Hot patch 代码`**：当前以热补丁形式运行的代码数量。域重载或重编译后归零，此后运行的是正常编译产物。
* **`需编译`**：无法热更、等待重编译收敛的改动数。不为零时可点击面板上的`重编译`一次性收敛。
* **`失败`**：热更失败的次数。失败的改动会自动转入重编译，不会丢失。
* **`程序集内存`**：热补丁程序集占用的内存。
* **`编译器`**：编译服务器状态（`运行中` / `空闲` / `回退 Unity 内置`）。

## Debug 与 Release

面板中的`编辑器模式`控制 Unity 脚本的优化级别，直接影响热更成功率：

* **`Debug`**：不内联代码，所有方法体改动都能热更新；编辑器略慢。
* **`Release`**：编辑器更快，但部分方法会被内联，被内联方法的改动无法热更，需要一次重编译。

Release 下热更新照常工作：被内联的少数改动会自动触发重编译收敛，无需手动处理。追求最高热更成功率时切换到 `Debug`；编辑器处于 Release 时，设置页也会给出提示与`切换到 Debug`按钮。

面板中的`进入 Play 重载`控制进入 Play Mode 时是否执行域重载：`重载`为 Unity 默认行为，static 状态干净，但已应用的热补丁会被丢弃并重编；`不重载`保留热补丁与内存状态，代价是 static 状态跨播放保留。

## 自检

怀疑热更新工作不正常时，先跑一次自检：「设置」→「热更新与编译」→ `热重载自检`，在编辑器已连接且处于编辑模式时点击`运行自检`。自检会写入一组测试脚本、进入 Play Mode 逐项验证各类改动的热更行为，结束后自动清理，输出通过与失败项数及完整日志。

## 边界与安全

热更新不改变改动落盘的方式：Agent 的修改始终先写进源文件，补丁只是让运行中的编辑器提前用上新逻辑。任何无法热更或热更失败的改动都会安全回退到标准重编译，最终状态与从未开启热更新完全一致。它不会把工程改坏，最坏情况只是多等一次编译。


# 连接与插件
Source: https://unity.farlocus.com/unity/index

安装 Unity 插件、理解连接状态与状态面板，以及编辑器内嵌窗口

Locus 通过 Unity 插件与编辑器通信，实现状态检测、C# 代码执行、资产定位等能力。插件装好后，Locus 会自动发现并连接当前项目对应的 Unity 编辑器进程。

## 插件安装与更新

<img alt="img" />

插件默认安装路径为 `Packages/com.farlocus.locus`。检测到旧版 `Assets/Locus` 安装时，点击更新会自动迁移到新的包路径。首次使用在引导流程中安装，之后也可以在会话页面随时安装。

Locus 升级后，若项目中的插件版本落后，Unity 状态指示会显示`插件需更新`，点击即可更新（未安装时显示`插件未安装`与`点击安装`）。更新需要替换 Unity 已加载的 DLL 时，Locus 会弹出`关闭 Unity 后更新插件`确认：先关闭当前 Unity 项目，更新完成后自动重新打开。

## 连接状态

会话输入框上方的 Unity 状态指示显示当前连接情况：

* **`Unity编辑器未连接`**：未检测到运行中的编辑器。此时文件级操作（读写代码、资产分析）不受影响，但无法执行编辑器内的操作。
* **`Unity编辑器已打开，等待连接`**：编辑器进程在运行，插件握手尚未完成；刚装完插件时 Unity 需要先完成一次编译。
* **`Unity编辑器启动中` / `Unity编辑器已启动，等待连接`**：通过 Locus 启动 Unity 后的过渡状态。
* **已连接**：指示切换为语义状态，显示 Unity 正在做什么：`Unity 编辑态`、`Unity 运行态`、`Unity 暂停`、`Unity 重载中`等。

各状态下的能力差异：`编辑态`下全部能力可用；`运行态`与`暂停`下 Agent 依然可以执行代码、读取[运行时状态](/unity/runtime-state)，适合边玩边调；`重载中`、`编译中`表示编辑器暂时无法响应命令，Locus 会自动等待恢复，无需手动干预。脚本改动触发重编译时显示`Unity 重编译中，等待重连`。

## 状态面板

点击状态指示展开详情面板，包含进程信息、当前`场景`、通信`延迟`，以及`原生桥接`、`状态探针`、`后台 Hook`等子系统状态（含义见[运行时状态与后台运行](/unity/runtime-state)）。面板中的`操作安全`行提示当前时机是否适合调用 Unity。

快捷操作：

* **`启动`**：Unity 未运行时，直接从 Locus 启动当前项目。
* **`重编译`**：位于`Unity 热更新`面板，手动触发一次 Unity 重编译并等待编辑器重连，见[热更新](/unity/hot-reload)。

## 编辑器内嵌窗口

在 Unity 菜单选择 `Window > Locus` 可以打开编辑器内嵌窗口，在 Unity 里直接与 Locus 对话，适合不想切换窗口的工作流。

配套的两个菜单项用于把编辑器中的内容发给 Locus：选中资产后使用 `Assets > Send to Locus`，选中场景对象后使用 `GameObject > Send to Locus`，所选内容会作为引用出现在 Locus 输入框中。

## 团结引擎（Tuanjie）

Locus 自动识别团结引擎（Unity 中国版）编辑器：启动发现、进程检测与连接流程与 Unity 完全一致，无需任何额外配置。


# 运行时状态与后台运行
Source: https://unity.farlocus.com/unity/runtime-state

状态探针持续感知编辑器状态，原生桥接与后台加速让 Agent 不依赖前台窗口

Locus 持续追踪 Unity 编辑器的实际状态：`编辑态`、`运行态`、`暂停`、`重载中`、`编译中`、`导入中`，乃至`无响应`。这份状态同时服务两端：你在状态面板上能看到 Unity 正在做什么，是卡死还是在正常重载；Agent 依据同样的信息决定何时调用 Unity、何时等待，面板中的`操作安全`行显示的就是这个判断结果。排障时这尤其有用：Agent 能确认游戏正处于运行态、编辑器是否正在重载，而不是对着一个黑盒盲试。

以下三个子系统都默认开启，开关集中在「设置」→「Unity 连接」。

## 状态探针

常规状态检测依赖编辑器内插件的应答，但恰恰在最需要状态的时刻（域重载中、编辑器卡死时）通信管道是静默的。状态探针从 Unity 进程外部读取编辑器状态，让状态在这些时刻仍能持续更新，Locus 因此能区分"正常重载中"与"真的卡死了"。

探针采用分层回退：拿不到深层信息时自动降级为较粗略的检测方式，最差退回"管道加进程推断"，状态显示始终可用，只是精度下降。状态面板的`状态探针`行显示当前工作层级。

开关为`进程外状态探针`；同区域的`实机连接测试`会连接运行中的编辑器，依次覆盖域重载、播放、暂停、恢复与退出播放，验证探针能观察到每次状态变化。

## 原生桥接

原生桥接为 Locus 与 Unity 之间的命令通道提供原生层实现，最关键的价值是让连接在域重载期间保持不断开：重载结束后命令继续执行，不需要重新握手。

开关为 `Native Plugin Bridge`。关闭后回退为普通管道连接，域重载期间的连接保持与状态融合能力随之失效，每次重载后需要重新建立连接。状态面板的`原生桥接`行显示 `就绪`、`未连接`或`已关闭`。

## Unity 后台加速

Unity 编辑器在失焦或位于后台时会推迟处理外部命令，直到你把它切回前台。这意味着没有后台加速时，Agent 每触发一次重编译，你都得手动点一下 Unity 窗口。

后台加速（`后台 Hook`）为编辑器打补丁，使其在后台仍持续处理 Locus 命令，包括重编译。开启后 Agent 可以在你专注于 Locus 或其它窗口时独立完成"改代码、编译、验证"的循环。

开关为`后台保持编辑器响应`。它基于原生符号实现，不可用时自动回退，回退后把 Unity 切到前台即可正常执行。状态面板的`后台 Hook`行显示 `已生效`、`等待进程`、`失败`、`不可用`或`已关闭`。

「设置」→「测试」中的`后台重编译探针`可以验证效果：它写入一个无害的临时脚本并触发一次真实重编译，完成后自动清理；若后台 Hook 生效，整个过程无需把 Unity 切到前台。