# 浏览与检索
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](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/collaboration.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=d3c64ca24b10cb6df9c6e9e95b33281f)

## 首次使用：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](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/showcases/git-graph.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=71cbfb1cc094b2adccd47b663fabe10a)

## 提交右键操作

右键图谱中的提交：

* **`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](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/showcases/merge.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=48848cf11d33d99561d64d7e98195853)

## 冲突期间的限制

存在未解决冲突时，右键菜单中的其他 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](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/showcases/diff.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=6252cfa10439fe1e4f2a287c61920f7d)

## 双视图

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 使用一个 Vue 文件组合现有画布、图编辑器、表格和 Unity 控件；不填配置时直接使用文件名，需要自定义名称、图标或 Unity 连接要求时写在文件内。SDK 可按需初始化目录结构。
* **整理**：拖拽条目调整顺序或移入文件夹，右键条目可新建文件夹、重命名、移动或删除。由插件安装的视图随插件管理，需卸载插件后才能删除。
* **列表入口**：「设置 → 显示」的`会话列表中显示视图`可让视图入口出现在会话页左侧。

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

在会话中输入 `/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能力

[快速开始
快速安装Locus，在几分钟内完整配置](overview/install-and-setup)

[路线图
查看我们正在实施以及计划中的功能](overview/roadmap)

[从技术上讲，Locus有什么独特之处？
了解Locus独立进程架构带来的技术能力](overview/advantages-over-generic-agents)

## 示例展示

![文件变更](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/showcases/file-change.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=e8194a67899a98043788539c2c405a51)

在会话界面中审阅文件修改

![Git 图谱](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/showcases/git-graph.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=71cbfb1cc094b2adccd47b663fabe10a)

通过图形化界面进行版本管理

![知识工作区](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/showcases/knowledge.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=231d1c19bf1727ec2fa2cac2448e5034)

编辑知识文档，配置上下文注入方式

![差异对比](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/showcases/diff.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=6252cfa10439fe1e4f2a287c61920f7d)

语义化地分析YAML文件的修改

![合并处理](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/showcases/merge.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=48848cf11d33d99561d64d7e98195853)

语义化地处理合并时冲突

![检索设置](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/showcases/search.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=d5f6b445982da75ae402e670f44a489d)

词法与语法检索配置


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

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

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

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/knowledge-types.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=326337ae9abcdcf94c389d70502d618a)

## 五类知识

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

Design 与 Memory 的维护方式见 [Design 与 Memory](/knowledge/memory-and-design)，Skill 与 Reference 见 [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](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/showcases/knowledge.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=231d1c19bf1727ec2fa2cac2448e5034)

## 五个档位

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

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

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

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

## 摘要

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

## 注入 Agent

`L2 - 全文注入`与`L3 - 全文规则注入`只进入勾选的 Agent。在注入方式菜单旁的`注入 Agent`面板中勾选，对应 frontmatter 的 `injectAgents` 字段：

* 新建文档默认为`所有 Agent`，保存为 `injectAgents: ["*"]`，之后新增的 Agent 也会收到。
* `*` 是通配符，可匹配任意字符：`"*"` 表示所有 Agent，`"team-*"` 表示 id 以 `team-` 开头的 Agent。YAML 中的 `*` 需要加引号，也可以直接写成 `injectAgents: "*"`。
* 没有 `injectAgents` 字段的文档保持原有行为，只注入 Unity Agent；已写明列表的文档按列表生效，`[]` 表示不注入任何 Agent。
* CSV 表格没有 frontmatter，始终按无字段处理。

路径、摘要和仅搜索档位不受 `injectAgents` 限制。

## 目录级配置与继承

右键目录选择`目录配置`，可以为整个目录设置注入方式（`仅搜索` / `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、计划、Skill 和 Design。Agent 会判断哪些内容对后续实现有复用价值，再按现有权限和维护规则决定精简、更新、保留或不作改动；计划完成不意味着一定要写入 Memory。进入 Memory 的内容会压缩为简洁的结论、经验或约束，避免重复记录容易从代码检索到的工程细节。

## 自定义 Memory 文档

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

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

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

## 编辑模式

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

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

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


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

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

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

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/knowledge-search.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=a381adcbc1ed9a6255fb07d091914822)

## 全文检索

顶部`检索设置`面板中的`全文检索`开关控制是否维护倒排索引，默认关闭。关闭时搜索栏使用逐文档文本扫描，小规模知识库够用；文档多了以后建议开启，检索更快，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

**在开始使用 Locus 执行任何修改操作之前，请确保您已备份项目文件。**\

**AI Agent 在执行任务时可能存在不确定性，请审慎使用。**

## 配置模型服务

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

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

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

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

## 选择项目并安装插件

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/install-and-setup/unity-plugin-2.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=4336cbd64e153b14abae167932394095)

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

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

## 版本管理/Git配置

![img](https://mintcdn.com/farlocus/LInifaS2d9XrwzAW/images/overview/install-and-setup/git-config.png?fit=max\&auto=format\&n=LInifaS2d9XrwzAW\&q=85\&s=a5acf95385f16defad6a0e3aff79153d)

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

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

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

## 扫描资产数据库

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/install-and-setup/asset-scan.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=394e67463d3ed6c81b56b6c955c59438)

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

## 尝试第一次对话

**在开始使用 Locus 执行任何修改操作之前，请确保您已备份项目文件。**\

**AI Agent 在执行任务时可能存在不确定性，请审慎使用。**

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

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

现可尝试以下示例对话：

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


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

Locus v0.9.1 (2026-10-21)

## 下载

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

## 变更列表

### v0.9.1（新增）

* 可以在设置中指定新 worktree 的存放位置，默认放在仓库旁边；也可以用启动参数 `--locus-worktree-root` 或环境变量 `LOCUS_WORKTREE_ROOT` 临时指定。
* 包含子模块的仓库，以及使用仓库内本地包（`file:` 依赖）的项目，现在可以创建 worktree。
* 创建 worktree 时显示已检出的文件数。关闭选择面板后创建会在后台继续，所有窗口的后台任务列表中都能看到。
* 在 worktree 中进行的会话保留在所属工作区的布局里，标签上会标出所在的 worktree。新会话默认使用该项目上次选择的 worktree，输入框底部会显示当前分支。
* Locus 创建的 worktree 不再作为单独的工作区出现在最近列表中，而是从源工作区进入。
* 文件管理可以新建和删除文件夹。用 Ctrl/Shift 多选后，可以批量复制路径、删除、隐藏或拖动移动。
* 编辑器标签可以打开工作区以外的本地文件（例如从聊天中的文件引用打开），标签上标注“工作区外”。
* 尚未开始的新会话中，聊天输入框会把当前文档里选中的文本作为附件带上（路径、行号和内容），可以手动移除。
* 聊天输入框可以 `@` 提及本地和远程 Git 分支。
* 协作页面和 Agent 页面改为覆盖在列表和编辑器标签上方打开，关闭后恢复原布局。协作页面较窄时只保留提交历史。
* 资产搜索可以找到 glTF 模型、Shader Graph，以及常见的文本、UI Toolkit 和程序集定义文件。首次打开项目时会重建一次资产索引。
* 合并分支时，代码和纯文本文件按行三方合并，冲突处用 diff3 标记显示，Agent 可以直接写入合并结果。
* 预制体覆盖、实例中新增或移除的对象、托管引用等列表在合并时按元素合并。
* 应用合并后，Unity 会重新导入写入的资产，并从磁盘重新加载打开的场景和预制体；有未保存修改的资产只会被报告，不会被覆盖。
* OpenRouter 端点可以开启服务端网页搜索并选择搜索引擎（自动、native、Exa、Parallel、Firecrawl、Perplexity）。搜索来源显示为引用，后续轮次无需重新搜索。
* 使用 Codex 订阅登录时，Codex 模型可以使用 Codex 自带的网页工具，包括搜索、打开网页和页内查找。
* Agent 可以一次提出多个问题，支持多选、自定义回答和逐题切换，全部回答后一起提交。Python SDK 的 `run.answer` 可以提交问卷答案。
* Claude Code 会话会在对话中显示当前阶段，例如准备中、思考、调用工具、生成回复。
* Claude Code 后台启动失败的原因会显示在状态栏中；连接断开后会自动重连并恢复对话。
* Claude Code 可以设置自动压缩阈值；Claude 原生任务工具的结果显示为待办列表。
* 上下文统计按每次请求检查提示缓存是否被复用，并显示检测覆盖情况。
* 费用只显示提供方报告的数值，没有报告时显示“未报告”。
* 会话数据库会在后台清理旧的请求抓取记录、压缩数据库文件，并显示进度；磁盘空间不足时会给出提示。
* Claude 订阅模型列表更新为 Opus 5.5（默认）、Fable 5.1、Sonnet 5.5、Haiku 5.5。
* Python SDK 新增 `worktrees.defaults()`，创建 worktree 时可以省略目录；合并任务新增 `all_changes()` 和 `set_text()`。

### v0.9.1（修复）

* 运行中新打开的工作区窗口和工作台窗口，现在也能从电脑拖入文件。
* 知识文档在后台自动保存，保存时不再锁住标题和属性按钮，页面布局也不会跳动。
* 只有 CSV 知识文档会显示未保存标记；文件编辑器自动保存时不再闪现磁盘冲突提示。
* 重命名 Markdown 文档标题时，输入框保持焦点。
* Markdown 表格的长单元格在可用宽度内换行；横向滚动时首列固定，并显示边缘阴影。
* `@` 提及和全局搜索中，文件名匹配排在路径匹配前面，分散在长路径中的零散匹配不再出现。
* 排队消息和中途插入的消息在确认送达前不会丢失，也不会重复发送。未送达的消息会保留并标记为“未送达”，可以编辑或重新发送。
* Codex 服务拒绝插入消息时，本会话会停用插入并重试请求。
* 使用 Anthropic 格式端点进行网页搜索时，之前的搜索结果按原始格式回传给模型，模型不再把搜索结果当作自己写的内容并编造结果。
* `web_fetch` 能识别没有声明编码的网页，每次重定向都会检查目标地址，转换大型 HTML 页面更稳定。
* Grep 和 Claude Code 的 Grep 改用同一个搜索引擎，大型工作区中搜索更快。
* Locus 的 Unity 插件可以在更早的 Unity 版本中编译。不支持的功能（帧时间统计、空间截图）会说明所需的 Unity 版本。
* Unity 测试开始时报告的是筛选后实际运行的测试数量。
* Unity 资产中的列表保留原有格式，只写入改动的元素。
* 会话导出和分叉不再复制整个数据库，大型数据库也能顺利完成。
* 模型请求的完整抓取只在调试模式下记录，避免会话数据库快速增长。
* 数据目录被另一个 Locus 进程占用时，启动会弹窗说明原因，而不是直接崩溃。
* Git 分支列表能正确处理已在其他 worktree 中检出的分支和分离的 HEAD。
* 工作区树中的“删除工作区”改为“移除工作区”，这个操作只从树中移除，不删除文件。

### v0.9.1（移除）

* 设置中的资源页不再限制同时运行的会话、Unity Editor、工作区服务、代码语言服务和编译任务的数量，只保留空闲超时。旧配置中的这些数量设置会被忽略。
* Claude Code 和 Codex 会话不再提供 Locus 的 `web_fetch` 工具，改用各自内置的网页工具。其他模型仍然可以使用 `web_fetch`。

### v0.9.0（新增）

* 在工作区选择器上右键工作区，可以在独立窗口内打开该工作区。
* View 可以设置自己的名称和图标（内置图标或自己的 SVG），并可选择每个 View 在标签页还是新窗口中打开。
* 右键 View 即可修改设置、导出、在 Unity 中打开等。插件自带的 View 会标明来源，避免被误删。
* 聊天输入框可以 `@` 提及 View，全局搜索也能找到 View。
* View 可以读取和修改 Markdown 文档的属性和正文，方便基于文档制作表格、看板等工具。
* 在 View 中制作 Unity 配置页面更简单：放上字段组件，就能显示并编辑对应的属性；预制体字段会标出数值是继承的还是被覆盖的。
* View 可以作为窗口在 Unity 中打开，也可以嵌入 Inspector；还能在 Locus 面板中显示 Unity 的实时渲染画面。
* 属性编辑器中的 Unity 列表支持翻页、搜索、拖动排序、插入、复制和设置数量，并支持 Odin 常用的列表与分组设置。
* Claude Code 可以在本机或通过 SSH 在远程服务器上运行，工具仍在本机执行。可在“实验性设置”中配置。
* 任意文件夹都可以添加为工作区，知识库和 Unity 测试工具可按工作区开关；新增适合非 Unity 项目的 General Agent。新会话会记住你在每个工作区上次使用的 Agent 和模型。
* 可以选择知识文档要提供给哪些 Agent，新文档默认提供给所有 Agent。
* 聊天输入框可以 `@` 引用之前的会话或已打开场景中的物体，也可以切换会话、查看并停止后台任务。
* 文件管理支持拖动排序和移动、新建、重命名、从电脑拖入文件和隐藏文件；可以查看文件的 Git 历史并恢复旧版本。
* 文档编辑器新增属性面板、`@` 提及、粘贴图片和草稿自动恢复；输入时会自动补全引号和括号。
* `Ctrl+F` 可以在当前文档或列表中查找，全局搜索可以找到文件和 View。
* Unity 无响应 30 秒后，Locus 会自动分析卡在哪里、为什么卡住，并可一键重启 Unity。
* 新增 `/capture-scene` 和 `/capture-game`，截图时一并记录物体和位置信息，Agent 能知道画面里有哪些物体、它们在哪里。
* Unity 测试运行时会显示进度，并可排除指定的测试。
* 采集 Unity 性能数据时开销更小。
* 自定义提供方可以接入兼容 Codex 的服务，Locus 也可以自动跟随最新的 Codex 版本。
* CSV 表格新增右键菜单和 `Ctrl+F` 查找。

### v0.9.0（修复）

* 编辑 Unity 属性更可靠：撤销能准确恢复修改前的值，在字段中连续输入不会重新加载整个页面，只刷新改动的字段。
* View 和属性面板加载更快，大型项目中读取 Unity 资产也更快。
* Unity 中的属性发生变化时，View 会自动更新；播放模式下物体移动不会导致频繁刷新。
* 重启后恢复的 View 标签能正确显示图标和标题；修改 View 名称或图标后，标签会立即更新。
* Unity 中的 Locus 窗口更可靠：Unity 重新编译脚本后内容保持不变，崩溃后会自动恢复并保留草稿，加载太久时可以重试，打开拾色器等 Unity 弹窗时会自动让开。
* 使用 Claude Code 时，同一个工具不再重复出现；工具结果无法被 Claude 使用时会显示为失败，而不是成功。
* 项目中的 Skill 包可以正常选用，不再提示找不到 Skill。
* Agent 工具使用的文件路径统一以当前工作区为准。
* Skill 的脚本在当前工作区目录中运行。
* 运行 Unity 测试前会自动保存修改过的场景。
* 工作区树中的“重命名”和“更多”按钮恢复正常显示。
* 打开多个窗口时，右键菜单和下拉框显示在正确的位置。
* 切换会话时，对话导航条不再重新淡入。
* 图片预览会填满可用区域。

### v0.9.0（移除）

* Unity 中显示 Locus 的旧方式已由新的原生窗口取代。
* Claude Code 的旧连接方式已由新的内置运行方式取代，Claude Code 开关从“模型默认值”移到了“实验性设置”。

### v0.8.4（新增）

* `unity_yaml_read` 支持在资产根路径指定 `reader: "default"`，跳过匹配的 Skill 读取器；子路径可从实时 Editor 定位 Inspector 未显示的序列化字段。
* Codex 订阅信息的手动刷新同时更新额度和可用模型列表。

### v0.8.4（修复）

* Skill YAML 读取器对齐当前字段深度和数组数量限制；返回空内容或执行失败时回退到 Property Tree，并保留默认读取的来源与结果状态。
* 关闭会话撤回时，Unity Editor 操作不再持续占用工作区文件锁，其他 Agent 可继续编辑源文件。
* Unity Test 排队期间支持取消和超时；Test Framework 报错后会结束活动测试并记录错误。
* 编译服务刷新 DLL 时保留旧编译所需引用；调用关系扫描期间可替换 DLL，并正确读取替换前后的结果。
* Codex 模型刷新失败时保留现有模型列表；更新订阅模型请求的客户端版本。
* 工作区会话中的模型默认值设置保持显示应用级 Agent 和子 Agent 定义。
* 知识文档跨文件夹拖拽及悬停展开时，目标行保持稳定。
* worktree 选择面板在分支加载期间保持稳定高度。

### v0.8.4（移除）

* 本版本没有移除面向用户的工作流或兼容路径。

### v0.8.3（新增）

* 新增知识文档与会话全局搜索。在开发界面按 `Ctrl+F`，可搜索工作区中所显示项目的知识标题、正文，以及活动或已归档会话；支持内容预览、修改时间、键盘选择与搜索范围设置。
* 新增受管 Git worktree 与可复用 Unity 项目池。Python SDK 可创建、导入、申请、释放并指定 checkout，管理对应 Unity Editor 的启动与关闭，支持无界面运行。
* 新增 Unity 资源选择性整合流程。通过 merge SDK 按提交、文件、对象或字段制定计划，预览冻结快照中的改动，应用并验证结果后再提交。
* Python、TypeScript View 与合并计划共用 Unity 资源 API；可显式选择 YAML 或实时 Editor 后端，支持版本校验、批量修改和序列化数组操作。
* 新增 CSV 工作表编辑器，支持单元格编辑、排序、筛选、格式与布局保存。Python SDK 可使用 openpyxl 的工作表和样式对象，CSV 值继续按文本保存。
* View 改为在工作台内复用 Locus 组件、主题与服务。单文件 Vue View 支持随应用分发的编译器、文件监听、热更新与共享 TypeScript SDK。
* 新增结构化 Unity 性能采集，共用 Profiler API 提供指标发现、捕获、统计、基线对比与 CSV 导出。
* 新增会话执行耗时与上游模型记录，扩展历史搜索和上下文导出；Python SDK 可读取、修改和启停工作区 Agent 规则。
* 新增本地 `/garbage-collection` 命令，在保留数据记录的前提下回收会话库和当前项目数据库的空闲空间。

### v0.8.3（修复）

* 为内存快照和托管引用 API 补充版本条件编译，修复 Unity 2022.2 之前版本中的插件编译错误。
* 加固 Codex 传输、思考内容回放与上下文压缩。受支持的 Astra 请求可在运行中接收追加输入，远程压缩使用更长的响应空闲超时。
* 工作台分屏、预览、Git 操作、知识操作与 View 回调保持绑定原 checkout 及其运行代次。
* 统一文档编辑会话，使 Markdown 控件、草稿和编辑器状态在不同工作台界面之间保持一致。
* 已加载且获得焦点的会话标签会直接标为已读，无需滚动到最新消息；未激活的分屏继续保留未读状态。
* 修复 Windows 缩放同步干预 Tauri 缩放边框，导致窗口最大化后残留边框拦截输入的问题。
* 为控制台和 View 日志处理增加容量限制，并补充保留消息顺序与上下文导出结果的数据库维护检查。

### v0.8.3（移除）

* 移除工作台 View 的独立内容 WebView 路径；Unity 外部 View 窗口保留连接共享运行时的适配层。
* 移除 View 模板及旧 `view_*` 工具注册，创建与操作统一由 `execute_typescript` 和共享 SDK 承担；已有 View 包仍可读取。

### v0.8.2（新增）

* ChatGPT 订阅模型新增 GPT-6 Astra，支持思考强度与 Fast 模式；配置的上下文窗口现适用于全部订阅模型。
* 模型选择器新增会话级 Multi-Agent 控制，选择状态会随会话重载、分屏、独立窗口和会话分叉保留。
* Python SDK 支持任务列表、查询、等待与取消，父子及同级 Agent 间消息通信，以及在原会话内续跑失败或取消的子 Agent。任务支持短名称和完整输出日志。升级后默认启用后台执行，可在实验性设置中关闭。
* Explorer 可通过有界、只读的 C# 查询调查实时 Unity 数据，并结合代码与资产搜索返回结果。
* 归档会话与 Unity Inspector 内容统一在工作台编辑器标签中打开；Unity 选中对象和文件附件会发送到对应工作区最近聚焦的输入框。

### v0.8.2（修复）

* 对齐 Codex 订阅的 Responses 协议，支持工具命名空间、WebSocket 预热、HTTP 回退及请求压缩。会话重新打开或重连后保留原始响应项与加密推理内容；失败或不完整的响应会在执行工具前停止。
* 修正远程压缩对文本和图片的保留预算，并统一前后端对订阅模型上下文配置的应用。
* 子 Agent 使用自身配置的模型、提供方、凭据、思考强度和速度设置，修复模型名称已切换但请求仍走父 Agent 提供方的问题。
* 后台结果和 Agent 消息在投递前持久化，重试不会重复通知，前台轮次结束也不会覆盖后台结果。会话迁移保留旧上下文导出能力，历史缺失字段显式写为 empty。
* Agent 页面、工作台编辑器、会话操作和独立窗口保持绑定所选工作区；磁盘文件变化后重新校验预览，同时保留未保存的编辑。
* 修复大量日志下控制台虚拟列表的行高测量、滚动和窗口缩放，并补充运行时卡顿与桥接诊断。
* Unity 重编译结果在重试后仍可读取，并与发起操作正确关联。Plan 模式禁止重编译、测试执行和 Editor 状态变更，同时保留只读调查。
* 收敛 Unity 操作规则，明确已验证的编辑目标、Prefab 实例范围、通过 Unity API 修改结构化资产，以及沿用任务中已有授权。

### v0.8.2（移除）

* 移除独立的 get\_task\_status 和 cancel\_task 工具，任务控制统一使用 Python SDK 内置接口。
* Inspector 与归档会话工作流迁入工作台后，移除旧独立 Inspector 界面和设置中的归档会话页。
* 移除已合并的内置 Unity 规则文件；升级安装时清理旧内置副本，保留用户 Agent 定义与项目覆盖规则。
* 移除旧 dev Agent 兼容路径，其定义、规则和模型偏好不再加载或合并到 Unity；升级安装时清理内置 agent/dev 目录。

### v0.8.1（新增）

* **文本缩放与 Markdown 编辑。** Markdown 编辑器与预览、文本查看器、Diff 和 Merge 支持 Ctrl+滚轮缩放；工作区 Markdown 文件默认使用 CodeMirror 渲染态编辑。

### v0.8.1（修复）

* 修复工作台会话编辑器的功能缺失，恢复上下文压缩、中断续跑、Plan 模式、整会话与指定消息分叉、历史导航、上下文导出与审查，以及归属当前分屏的思考和文件修改面板。
* 分屏会话在编辑器重新挂载后继续保留草稿、执行配置、Todo、后台任务状态、撤回与 Diff 状态、滚动历史和会话操作。
* 文件、知识、Unity 和原生拖放操作始终绑定其来源工作区与会话。
* 知识文档大纲会对齐正文起点，并按可用视口计算高度。
* 重新显示的系统资源会回到工作区根节点首位。
* ONNX Runtime 准备流程支持断点续传，并校验下载包与运行时文件完整性。
* 文件修改面板缩放、撤回选择、命令列表和关闭控件补齐键盘操作能力。

### v0.8.1（移除）

* 本版本没有移除面向用户的工作流或兼容路径。

### v0.8.0（新增）

* **多工作区同时运行。** 可在同一 Locus 实例中打开多个项目与 Git worktree，并行运行会话、Unity、知识索引、资产数据库及工作区服务。每个工作区保持独立的执行上下文、运行状态与资源缓存。
* **VS Code 式分屏工作台。** 会话、文件、知识文档、Unity 资产和 View 统一以编辑器标签打开；标签可拖动排序、四向分屏、跨分屏移动或拖出原生窗口。窗口、分屏、标签、草稿、滚动位置及未保存内容支持恢复。
* **开发工作区树。** 会话、知识、协作与文件统一进入一棵工作区树，支持单工作区与多工作区显示、树预设、虚拟文件夹、目录挂载及节点显隐。
* **持久化 Markdown 编辑。** 知识文档迁移到 CodeMirror 6，实时预览与源码模式共享同一编辑器；文档切换和分屏期间保留选区、撤销历史、滚动位置、草稿与未保存修改。
* **知识工作流扩展。** 新增第五类知识 `Plan`；项目可在 `Locus/skills` 下维护可写 Skill Package；文件变化后自动刷新 Skill；同时加入文档大纲、正文缓存和冲突感知的协同编辑。
* **工作区与 Unity 引用搜索。** Chat 的 `@` 搜索覆盖工作区文件、文件夹及实时 Unity 场景对象，并提供排序后的结果和明确对象引用。
* **更完整的 Unity 检查。** `unity_yaml_read` 可选择显示激活状态、Prefab 来源、世界变换、RectTransform 范围、Tag、Layer 和组件等层级字段；SubScene 可继续读取其 Authoring Scene；可调序列化字段可渲染为内联属性控件。
* **Unity 协作与增量同步。** Workspace Change Journal 根据可验证的文件事件选择定向导入、全量刷新或跳过重编译；实验性 `unity_lock` 与 `unity_release` 可协调多个 Agent 共用一个 Editor。
* **运行时与供应商控制。** 子 Agent 默认值扩展为模型、思考强度和响应速度；自定义 Responses 供应商可启用 Codex V2 远程压缩；支持的 DeepSeek V4 路由会规范化推理内容回放。
* **会话 SDK 与诊断。** Python SDK 可列出运行中的会话，并向另一个活动运行发送带来源信息的输入。调试模式加入 DevTools 控制、CDP 端口发现、WebView Bridge 诊断和有界日志批处理。

### v0.8.0（修复）

* 加强多工作区之间的会话事件、Unity 服务、MCP、C# 分析、资产数据库、知识、Diff/Merge、View 和缓存隔离。
* 切换工作区作用域后会刷新 Unity 插件的安装或更新提示；较晚完成的状态检查与临时失败不会覆盖较新的事件状态。
* 标签移动、窗口交接及编辑器重新挂载期间，会保留流式会话、输入草稿、待确认操作、排队附件、图片预览和未保存文件。
* 发送失败、取消或被后端撤回的乐观消息会把完整本地文件附件与绝对路径恢复到输入框。
* 目标窗口创建失败或交接超时时，标签及编辑状态会安全保留在原窗口。
* 手动上下文压缩可在当前运行后排队，并优先于后续排队输入执行；子 Agent 会话可独立控制。
* Responses API 的引用会写入会话存储及上下文导出；增量 UTF-8 解码会保留跨流式分块的多字节字符。
* 流式 Markdown、语法高亮、折叠工具交互和工具文件预览在内容增长及流结束时保持稳定。
* 中断或失败的子 Agent 会返回已经持久化的部分输出；延迟工具按精确 wire name 加载；图片工具会在执行前检查模型的图像理解能力。
* Unity 恢复流程会显示 Safe Mode 与 Editor 日志路径，等待弹窗状态切换，并通过 Test Framework 生命周期取消中断的 Unity Test。
* 折叠工具调用使用简洁界面标签，展开后继续显示精确的等宽工具标识符。

### v0.8.0（移除）

* 移除旧一级“项目”入口与第二层工作区栏，统一由“开发”工作台和工作区树承载。
* CodeMirror 迁移完成后，移除 Vditor 编辑器及其旧渲染和兼容路径。
* 移除手动 `skill_reload` 工具，Skill 文件变化后由 Locus 自动刷新清单。

### v0.7.4（新增）

* **可配置的 Codex 上下文窗口。** ChatGPT 订阅模型支持 16K 至 1M Tokens，默认 272K；有效上下文与自动压缩阈值随配置同步调整，旧版“扩展上下文”设置会迁移为 372K。
* **提示词缓存诊断。** 会话上下文用量会根据服务端统计记录缓存失效，包括模型或提供方切换、异常未缓存输入增长；诊断记录会写入上下文导出，并可在通知设置中启用应用内警告。
* **Prefab 感知的 Unity Property Tree。** `unity_yaml_read` 会标明实时 Editor 或磁盘 YAML 来源，支持配置数组展开数量，合并 Prefab 源与 Variant 数据，标记覆盖属性，折叠相同的重复 Prefab 实例，并返回可读的子资源语义路径。
* **更安全的 `unity_execute` 结构化输出。** `printJson` 支持匿名对象、存储字段、字典、已物化集合、共享与循环引用及嵌套 Unity 对象；延迟枚举器与目标属性 getter 保持未执行状态。
* **快速开发安装包。** `bun run build:installers` 可生成采用增量编译和 zlib 压缩的开发安装包；发布安装包继续使用 ThinLTO，并生成两种运行时版本。

### v0.7.4（修复）

* **Unity 重编译生命周期。** 重编译请求会等待 Unity 发出编译开始事件，在 Domain Reload 期间持久化中间状态，连接恢复后继续核对结果，并提供完整的超时诊断。
* **知识查询输出。** 摘要模式每篇文档占一行，详细模式使用紧凑的路径与行号标题；Frontmatter 命中仅返回相关摘要或维护规则。应用 Skill 包会归入真实应用目录，知识或插件变化后会立即刷新 Skill 缓存。
* **工具调用交接。** Provider 预告后未出现在最终响应中的工具调用，不再显示为空的已完成调用。
* **渲染态 Markdown 编辑。** 从渲染内容进入编辑时会保留滚动位置、文档高度和点击位置对应的光标。
* **View 运行时导入。** TypeScript 6 CommonJS 互操作下的 `.vue` 默认导入保持稳定。
* **文件读取上下文。** 绝对行号改用紧凑前缀，减少上下文占用，并与压缩摘录格式保持一致。

### v0.7.4（移除）

* 本版本没有移除面向用户的工作流或兼容路径。

### v0.7.3（新增）

* **Codex 自动审批审查。** Codex 用户可选择启用待批准操作的结构化审查。审查仅使用最近一条用户请求与受限的本地检查信息；安全操作可自动继续，需要人工判断时会显示风险级别与审查理由。
* **危险命令拦截。** Bash、PowerShell 和 CMD 中的强制删除命令默认请求批准。
* **知识文档四态编辑。** 知识文档支持继承、禁止 AI 编辑、用户确认后编辑和自动编辑，并迁移旧元数据，在知识工具与文件工具中统一执行约束。
* **本地模拟模型。** Debug 模式提供确定性的流式回复、工具调用与错误回复预设，全程本地运行。
* **原子批量编辑。** `edit` 可基于同一份原始文件快照执行多处独立替换，全部校验成功后一次写入。
* **Unity Test 联合发现。** Unity Test 工具默认同时发现 Edit 和 Play Mode 测试，并按模式、程序集、套件和测试输出树状结构。
* **上下文审查附件。** 会话回顾会创建独立聊天、异步导出上下文，并将导出文件放入输入区供发送前检查。
* **测试工作流。** 新增隔离实例跳过首次引导，以及聊天流式渲染、会话切换和实时工具调用的 WebView 压力测试。
* **Unity Property Tree。** `unity_yaml_read` 和 `unity_yaml_search` 统一使用可逐层展开、可按路径续读的属性树，覆盖场景层级、组件、子资源与序列化字段，并在超出输出预算时返回可继续读取的子路径。
* **Agent 定制。** 支持从 `user-agents` 加载用户 Agent 与工具描述覆盖，在 Agent 面板中控制环境、规则、知识上下文及延迟工具清单等提示词注入项，并在配置变化后即时重载。
* **会话上下文用量。** 新增上下文用量窗口，按系统提示、运行时注入、会话消息和工具结果拆分 token 占用，并显示工具调用分布与模型有效输出速度。
* **每 Agent 模型默认值。** 模型和推理强度可按 Agent 独立保存；Codex 与自定义供应商可设置提示词前缀缓存有效期。

### v0.7.3（修复）

* **Web 搜索异常续轮。** 修复 Codex 托管 `web_search` 结果被重复回放为本地工具调用、进而触发异常重复续轮的问题。
* **Windows 句柄泄漏。** 更新到包含上游修复的 Tauri/Wry 运行时，避免窗口边框 DPI 查询持续泄漏 Windows 设备上下文句柄。
* **Windows Rust 测试启动。** 为 Rust 单元测试二进制嵌入 Common Controls v6 清单，修复加载 `TaskDialogIndirect` 时触发 `STATUS_ENTRYPOINT_NOT_FOUND` 的问题。
* **子进程生命周期。** Shell、Skill、开发服务器及其他子进程按会话、工作区和应用生命周期统一管理；取消会话、切换工作区或退出应用时会终止对应进程树。
* **只读附加目录。** 文件写入、Shell 工作目录和命令路径统一遵守附加工作目录的只读约束。
* **消息界面布局稳定性。** 增强消息界面的布局稳定性，修复了大部分会话流式渲染造成的闪烁问题，覆盖 Markdown 高度对账、流结束滚动、工具状态收敛与展开状态保留。
* **并行工具执行。** 工作区写入按路径协调，同文件编辑安全合并，独立写入可并行执行，只读子 Agent 可与兼容工具同时运行。
* **托管工具与后台任务。** 服务端托管工具不会作为本地函数历史重复回放；托管轮次可正确结束；异步启动失败会直接返回；notify 结果会自动送达。
* **纯图片聊天轮次。** 上下文压缩、历史分页与轮次导航会保留图片提示，并排除内部提醒轮次。
* **Shell 与搜索环境。** 搜索路径统一按工作区解析，PowerShell 提示与实际运行时保持一致，Bash 环境可直接调用 `pwsh`。
* **Unity 热重载反馈。** 编辑状态仅在热重载管线启用时显示。
* **知识元数据刷新。** 保存响应与后续刷新交接期间，文档文件元数据保持可见。
* **历史图布局。** 工作区 WIP 主线会优先连接 HEAD，避免被后代分支占用。

### v0.7.3（移除）

* 本版本未移除面向用户的工作流或兼容路径。

### v0.7.2（新增）

* **后台任务实时状态。** `async` 和 `notify` 工具调用会在原工具块中持续更新执行状态。Shell 输出可实时显示，最终结果会写入会话历史；后台 Shell 与 Unity Test 任务会持续运行至完成或取消，不再应用同步执行超时。
* **内置 Unity 项目文件生成器。** Locus Unity 插件可直接根据 Unity `CompilationPipeline` 生成完整的 `.sln` 和 `.csproj`，无需安装 Visual Studio、Rider 或 VS Code 集成包；生成结果保留项目引用、编译定义、分析器和 Unity 项目生成回调。

### v0.7.2（修复）

* **减少会话提前异常中断。** 服务端工具轮次完成后，以及 Codex/Responses 返回 `end_turn: false` 时，Agent 会继续生成后续回复，减少会话在最终答复前提前结束的情况。
* **Codex 请求兼容性。** 移除 Codex 服务端不支持的 `max_output_tokens` 参数，避免 checkpoint 上下文压缩请求被服务端拒绝。
* **Codex 上下文压缩。** Codex 会话改用 Remote Compaction V2 流式协议，并携带完整会话标识与路由信息；服务端压缩失败时保留原上下文并停止当前运行，避免写入不兼容的压缩状态。
* **压缩会话分叉。** 从压缩前的历史位置创建分叉时，Locus 会重建对应的活动上下文窗口；从工具调用组分叉时同时保留其工具输出，修复分叉后上下文为空、压缩失败或选择定位错误。
* **subagent 栈溢出。** 子 Agent 的完整运行循环改为使用独立 Tokio 任务，使父工具循环、工具执行与子 LLM 循环拥有分离的任务栈；父任务结束时会同步终止子任务。
* **并发 Agent 调度卡住。** 同一工具轮次中的前台 subagent 会先完成，再执行本地同级工具。工作区变更按规范化文件路径协调：不同文件可并行写入，同一路径按顺序执行，读取类工具无需等待；长时间等待会显示占用会话与工具。
* **Unity 并行编辑死锁。** 任一重叠编辑会话结束时，已经完成的资源变更会立即导入，其余会话继续运行，避免完成文件因同级长任务持续停留在 AssetDatabase 之外。
* **中断工具历史。** 恢复、分叉或继续中断会话时，缺失的本地工具结果会从已记录输出恢复，无法恢复时写入明确的中断结果；旧会话会通过迁移补齐终止工具轮次，保持模型请求与上下文导出的工具调用序列完整。
* **错误通知保留。** 错误通知会持续显示，直到用户主动关闭；成功状态替换、按操作清理与全局清理会保留尚未处理的错误。
* **Unity C# 动态代码编译。** `unity_execute` 和 `unity_run_states` 使用显式别名提供常用 `System.IO` 类型，避免启用非公开访问时 Unity Mono 内部 `MonoLinqHelper.ToArray` 与 LINQ `ToArray` 冲突。
* **Unity YAML 检查引导。** 直接读取 Unity YAML 资源被重定向时，Locus 会同时推荐语义化 YAML 工具和通过 `unity_execute` 在 Editor 内运行 C# 检查，并保留明确的原始内容重试入口。

### v0.7.1（新增）

* **后台任务实时状态。** `async` 和 `notify` 工具调用会在原工具块中持续更新执行状态。Shell 输出可实时显示，最终结果会写入会话历史；后台 Shell 与 Unity Test 任务会持续运行至完成或取消，不再应用同步执行超时。
* **内置 Unity 项目文件生成器。** Locus Unity 插件可直接根据 Unity `CompilationPipeline` 生成完整的 `.sln` 和 `.csproj`，无需安装 Visual Studio、Rider 或 VS Code 集成包；生成结果保留项目引用、编译定义、分析器和 Unity 项目生成回调。

### v0.7.1（修复）

* **subagent 栈溢出。** 子 Agent 的完整运行循环改为使用独立 Tokio 任务，使父工具循环、工具执行与子 LLM 循环拥有分离的任务栈；父任务结束时会同步终止子任务。
* **并发 Agent 调度卡住。** 同一工具轮次中的前台 subagent 会先完成，再执行本地同级工具。工作区锁按规范化项目路径隔离，不同项目可独立运行；长时间锁等待会显示等待工具与占用会话。
* **Unity 并行编辑死锁。** 任一重叠编辑会话结束时，已经完成的资源变更会立即导入，其余会话继续运行，避免完成文件因同级长任务持续停留在 AssetDatabase 之外。
* **中断工具历史。** 恢复或继续中断会话时，未完成的本地工具调用会写入明确的中断结果，保持工具调用序列完整。
* **Unity C# 动态代码编译。** `unity_execute` 和 `unity_run_states` 使用显式别名提供常用 `System.IO` 类型，避免启用非公开访问时 Unity Mono 内部 `MonoLinqHelper.ToArray` 与 LINQ `ToArray` 冲突。
* **Unity YAML 检查引导。** 直接读取 Unity YAML 资源被重定向时，Locus 会同时推荐语义化 YAML 工具和通过 `unity_execute` 在 Editor 内运行 C# 检查，并保留明确的原始内容重试入口。

### v0.7.0（新增）

* **Python Agent SDK。** 内置仅依赖标准库的 `locus` 包，覆盖模型、Agent、工具、工作区、会话、自定义 Python 回调、异步运行、事件、取消、问答及可复用 workflow 编排。
* **Unity 自动化扩展。** 新增运行态切换、Console 多级筛选、Unity Test Framework 测试发现与执行、外部脚本编辑器接入、更完整的 YAML 检查、视口捕获及 CLI 一致性测试。
* **图形与 UI 调试工作流。** 新增 RenderDoc、Unity Frame Debugger、纹理分析，以及用于检查、查询、交互和序列化实时面板的 UI Toolkit API。
* **运行时调试。** 新增 PlayerLoop 协作调试，可跨帧等待条件、暂停、逐帧执行和检查状态；同时支持发现 CDB、WinDbg 等 Windows 原生调试器。
* **会话与工作区导航。** 页面和会话可在独立窗口打开。新增用户轮次导航、分页历史、中断续接、上下文导出与回顾、压缩上下文查看、文件预览和模型调用统计。
* **Agent 执行控制。** 新增带工作区锁的并行工具调度、同文件编辑合并、标准化 `subagent`、可选后台任务及状态/取消接口、会话内 Todo 和本地工具失败日志。
* **文件驱动的知识工作流。** Design、Memory、Reference、Skill 统一采用文件驱动的 Markdown 操作，并加入统一知识面板、Markdown 预览、规范化 Skill Package、`/grill` 与 `/review-context`。
* **Codex 与供应商控制。** 新增 Codex 扩展上下文、可选 GPT-5.6 会话标题生成、兼容供应商的原生延迟工具加载，以及按供应商生效的压缩输出限制。
* **Checkpoint 上下文压缩。** 长会话压缩为锚定摘要与近期完整上下文，迁移和导出保留结构化数据，压缩查看器可直接展示 checkpoint 内容。

### v0.7.0（修复）

* 强化 Codex WebSocket 恢复、代理连接、压缩与续帧处理、失效请求清理、会话续接状态和上下文压缩同步。
* Unity 执行请求可在 Native Bridge 断线或域重载后重新附着，并通过幂等执行避免已接受请求重复运行。
* 改进 Unity YAML 解析、序列化值还原、Prefab 与引用处理、视口捕获和冷路径检查安全性。
* C# 诊断限定为 Unity 托管源码，并在 hot reload 或 recompile 结果中追加当前编辑批次的语义警告。
* Markdown 文件引用缓存路径状态，正确处理文件夹，并减少渲染期间的重复文件系统查询。
* UI Toolkit 面板快照支持显式刷新并拒绝失效面板；JSON 序列化限制深度、成员、集合、字符串及总输出长度。
* 原生选择器统一迁移到公共下拉控件，新手引导复用供应商配置流程。

### v0.7.0（移除）

* 移除旧 Agent Graph、`graph_view` 与 `sheet` 工作流。Agent 委托统一使用 `subagent`，自定义交互输出由 View 和 Skill Package 承载。
* 移除独立 `knowledge_*` CRUD 工具和旧 Todo 面板。知识修改统一走文件驱动操作，Todo 直接显示在会话中。

### 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](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/overview/page-tour/session.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=40d10fac25d25ef322adde99077ffa4e)

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

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

## 协作

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/collaboration.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=d3c64ca24b10cb6df9c6e9e95b33281f)

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

## 知识

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/knowledge-types.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=326337ae9abcdcf94c389d70502d618a)

### 知识类别

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

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

### 检索策略

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

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

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/knowledge-search.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=a381adcbc1ed9a6255fb07d091914822)

## 设置

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

### 模型配置

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

![img](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/settings.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=321a6bd1ce4c62759748bb54ce2fc7c2)


# 路线图
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](https://mintcdn.com/farlocus/ZlI-W8lx6_9x2i0K/images/overview/page-tour/session.png?fit=max\&auto=format\&n=ZlI-W8lx6_9x2i0K\&q=85\&s=40d10fac25d25ef322adde99077ffa4e)

## 界面分区

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

## 输入框

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

| 命令 | 作用 |
| - | - |
| `/clear` | 清空当前会话并开始新对话 |
| `/compact` | 压缩当前上下文并总结历史消息 |
| `/garbage-collection` | 回收会话库和当前项目库的多余空间，保留全部数据 |
| `/fork` | 复制当前会话并切换到副本 |
| `/undo` | 撤回上一轮对话 |
| `/unity-console` | 附加当前 Unity Console 消息 |
| `/console-error` | 仅附加当前 Unity Console 错误消息 |
| `/plan` | 进入规划模式（仅 Unity 会话可用） |

安装的技能也可以注册自己的斜杠命令，例如 `/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` 并描述任务即可进入（仅 Unity 会话可用）。进入后对话区顶部会出现粘性横幅：`规划模式（只读）— 计划批准后才会开始改动`，随时可点击横幅上的`退出规划`手动退出。

「设置 → 默认模型」中可为计划模式单独指定`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 保留在项目目录中），可`打开目录`或`更改位置`，迁移在重启后完成。
* **`临时文件`**：工具大输出与运行临时文件的存放处，`清理`可释放空间。清理后历史会话仍可打开，已清理的大工具输出会显示为`完整输出已删除`。
* **`会话文件撤回`**：记录 Agent 每轮文件修改，支持在会话中查看和撤回。关闭后不再创建自动 Git 快照；明确文件路径的写入仍保持同文件互斥，Unity 执行仍保持必要的串行协调。
* **`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](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/page-tour/settings.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=321a6bd1ce4c62759748bb54ce2fc7c2)

## 订阅账户登录

* **`Claude 订阅账户`**：点击`登录`后在浏览器中登录 Claude 账号，授权后复制页面上显示的授权码并粘贴回 Locus。已安装 Claude Code 时可选择`从 Claude Code 导入`直接复用登录态。登录后显示`剩余额度`（`5 小时`与`1 周`两档限额）。
* **`ChatGPT 订阅账户（设备授权）`**：点击`使用 ChatGPT 账户登录`，在浏览器中访问链接并输入验证码完成授权，兼容 ChatGPT Pro / Plus 订阅。也支持`从 Codex CLI 导入`。登录后显示`短窗口`与`长窗口`的剩余额度。`上下文窗口`默认 272K，可在 16K–1M 范围内调整；自动压缩阈值随窗口同步变化。`生成会话标题`默认关闭；开启后，新会话通过当前 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 派生子任务时各类子代理使用的模型、思考强度与响应速度覆盖。单项未设置时继承当前会话；速度可显式选择标准或 Fast。

## 隐私边界

除所配置的远程模型服务调用外，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](https://mintcdn.com/farlocus/OfAb3Fo_I43YNcC0/images/overview/install-and-setup/unity-plugin-2.png?fit=max\&auto=format\&n=OfAb3Fo_I43YNcC0\&q=85\&s=4336cbd64e153b14abae167932394095)

插件默认安装路径为 `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 输入框中。

编辑器扩展也可以调用公开接口，并指定引用进入焦点会话或新会话：

```csharp theme={null}
using Locus;

LocusEditorWindow.SendToLocus(SendToLocusMode.FocusedSession);
LocusEditorWindow.SendToLocus(SendToLocusMode.NewSession);
```

省略参数时使用 `FocusedSession`。`NewSession` 会切换到一个新会话草稿后附加当前 Unity 选择；当前已存在的会话保持不变。

本地文件和文件夹使用 `LocusFileAttachment` 显式传入：

```csharp theme={null}
LocusEditorWindow.SendToLocus(
    new[]
    {
        new LocusFileAttachment(
            replayPath,
            typeLabel: "Replay",
            source: "replay-timeline")
    },
    SendToLocusMode.NewSession);
```

路径必须在调用时存在。无效路径会被忽略；全部路径无效时接口返回 `false`。

## 团结引擎（Tuanjie）

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


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

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

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

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

## 状态探针

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

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

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

### 卡死诊断

编辑器主线程超过 30 秒没有回到编辑器循环时，状态变为`无响应`，Locus 随即自动分析主线程停在哪里：原生桥接在 Unity 进程内对主线程做几次极短的采样，沿调用栈一直走到托管（C#）代码，并给出方法名与源码行号；Unity 自身的原生帧用随编辑器附带的符号文件解析。结论显示在状态面板的 Unity 详情中：

* `卡死诊断`：主线程是在持续执行代码（CPU 占用高，多半是死循环或耗时过长的操作）还是在等待（阻塞调用、等待另一个线程，或死锁），以及卡住的代码属于项目代码、Agent 执行的代码还是 Unity 编辑器。
* `卡死位置`：最可能的出问题位置，优先选项目代码或 Agent 执行的代码中的那一帧。
* 完整的主线程调用栈、采样来源与备注收在`诊断信息`中。

Agent 同样会拿到这份诊断：卡死期间返回的 Unity 工具错误会附带诊断结论；如果你点击`重启 Unity`时仍有 Agent 的 Unity 调用在等待，这些调用会立即结束，并把"用户已重启 Unity"和卡死位置一并返回给 Agent，不会挂起，也不会接到重启后的新编辑器上。

插件版本较旧时，诊断退化为从进程外扫描调用栈，只能看到原生帧；更新 Locus Unity 插件即可看到 C# 帧。

## 原生桥接

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

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

## Unity 后台加速

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

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

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

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