文档
文档是用于记录较长篇项目知识的项目所有 Markdown 文件。.md 文件始终是权威文件，并且与外部文本编辑器兼容。
所有权和存储
Section titled “所有权和存储”所有文档都位于 <Project>/ProjectDocuments/ 下。不存在共享或私有文档范围。/Game/... 下的内容浏览器文件夹映射到 ProjectDocuments/Content/... 下的对应路径；Developers 文件夹仍然是项目上下文，并不表示私有所有权。
文档不是 UAsset、软件包、重定向器、运行时对象或烘焙数据所有者。Locus 不会用其他权威格式包装 Markdown。
Locus 文档和内容浏览器根
Section titled “Locus 文档和内容浏览器根”文档树在同一个物理存储库上提供两个呈现根：
- Locus 文档包含存储在保留
Content/子树之外的普通项目所有文档。这些文档只存在于 Locus 中，不会投影到 Unreal 的内容浏览器。 - 内容浏览器只包含权威相对路径以
Content/开头的文档。Locus 会在树中隐藏内部存储前缀，因此ProjectDocuments/Content/Blueprints/AI/Behavior.md会显示为内容浏览器 > Blueprints > AI > Behavior，并投影到/Game/Blueprints/AI。
内容浏览器根是稀疏的、由文档驱动的。它只显示直接包含已投影 Locus 文档的文件夹，以及到达这些文件夹所需的祖先文件夹。它不会镜像不相关的 /Game 文件夹，删除派生的呈现文件夹也不会删除或修改对应的 Unreal 文件夹。
投影遵循权威相对路径，而不是创建文件时使用的 UI。在启动时发现的映射文档、在 Locus 中创建的文档、通过 Add > Locus > Locus 文档 创建的文档、导入的文档或通过 MCP 创建的文档，都具有相同的索引身份和投影行为。
创建和查找文档
Section titled “创建和查找文档”在Locus 文档下创建 Locus 专用文档。在内容浏览器下创建投影到对应 /Game 上下文的映射文档。在受支持的内容浏览器文件夹中使用 Add > Locus > Locus 文档 会创建相同的映射身份。Locus 创建真正的外部 .md 文件，在普通 UI 中隐藏扩展名，并打开专用编辑器选项卡。Markdown 导入和通过 MCP 创建的文档遵循相同的本地未跟踪创建策略。
在将新文档添加到版本控制之前先整理它：
创建 → 重命名、移动和编辑 → 路径确定后标记为添加。
工作区浏览物理文件夹，支持标题/路径搜索、状态筛选、刷新、打开、重命名、移动、删除、签出、标记为添加、导入和导出。可以同时打开多个文档选项卡；打开已经打开的路径会聚焦其现有选项卡。
要导入文档，请使用内容浏览器 Locus 操作并选择一个有效的 UTF-8 .md 文件。Locus 会保留源字节和换行符；如果目标已存在，则使用安全的编号名称。
文档 工具栏保留一排。较低优先级的操作逐渐进入 更多操作； 导出 和 刷新 保留在那里。当未配置提供程序时，源代码控制操作不存在。
新建或空文档会以编辑模式打开；已有内容的文档会以阅读模式打开。按 Ctrl+E 进入编辑模式，按 Ctrl+R 进入阅读模式，按 Ctrl+S 保存。文档使用显式保存，而不是笔记式自动保存。
源文本编辑器提供标题、强调、行内代码和围栏代码、有序和无序列表、任务列表、引用、链接、表格、水平线、资产引用和标记点引用命令。拆分预览会在短暂更新延迟后将当前未保存缓冲区显示在源文本旁边；打开或更新预览不会保存文件。
在编辑中，紧凑工具栏提供标题、粗体、斜体、行内代码、无序列表、有序列表、外部链接、资产引用和标记点引用；其他命令保留在格式中。 分屏预览 在短暂去抖后将当前缓冲区渲染在源旁边，而不保存；其分隔线、打开状态和比例均为个人喜好。
阅读模式和 Markdown 支持
Section titled “阅读模式和 Markdown 支持”阅读模式使用 Unreal 原生 UI。它支持编辑器工具栏所需的 Markdown 构造，包括标题、段落、强调、粗体文本、列表、仅显示的任务项、引用、代码、链接、带对齐方式的表格、水平线和删除线。
Locus 不宣称提供与浏览器等效或完整的 Markdown 渲染。原始 HTML 作为不执行的源文本保留，JavaScript 永远不会执行，不安全的 URL 协议不会激活，远程内容不会自动获取。HTTP 和 HTTPS 链接只有在操作系统浏览器中执行明确的用户操作后才会打开。
资产和标记点引用在呈现时使用可读标签。当前地图的标记点可以聚焦；跨地图标记点可以定位其所属关卡，而不会自动加载关卡。缺失的引用保持不活动且可诊断。
已解决资产、标记点、笔记、文档 和 Actor 参考使用可读标签。 Actor 参考仅通过在编辑模式下将一个符合条件的加载 World Outliner Actor 放入 文档 来创作； 插入引用 或 @ 不提供它们。原始 HTML 和 JavaScript 永远不会执行，也不会获取远程内容。
重命名、移动和删除
Section titled “重命名、移动和删除”重命名和移动只能在文档根内进行。对于符合条件的未跟踪文档，可以使用工具栏或上下文菜单中的重命名，按 F2，使用工具栏中的移动，或将其拖到有效的现有文件夹中。Locus 文档工作区是重命名或移动的权威位置；内容浏览器项目只是投影，不支持直接在内容浏览器中重命名。
标记为添加后，重命名和移动会被有意禁用。受控文档也同样禁用，因为 Locus 无法保证与提供程序无关的事务性版本控制移动。这个安全边界可以防止文件系统更改使文档和版本控制失去同步。已打开且有未保存更改或处于冲突状态的文档也会阻止工作区中的重命名、移动和删除。
删除是永久性的，需要确认，无法通过 Unreal 撤销。对于已跟踪文件，Locus 会验证状态，并在本地清理前通过活动提供程序执行删除。
路径更改仅适用于本地或 Untracked 文档。在 标记为添加 或提供商控制之后，重命名和移动被禁用，因为 Locus 不执行提供商中立的仓库移动或在路径之间传输开放状态。
可以导出选定的文档、文件夹、所有文档或编辑器副本。导出会保留当前源文本；导出副本时也可以包含未保存的编辑器缓冲区，并可保留文件夹结构。目标不能位于 ProjectDocuments 内；冲突选项包括覆盖、跳过或创建编号副本。导出不会更改源文档、其选项卡或版本控制状态。
恢复和外部编辑
Section titled “恢复和外部编辑”Locus 将文档恢复数据存储在 <Project>/Saved/Locus/Recovery/文档/ 下。保存成功后会删除对应快照。干净的外部更改会重新加载；如果外部更改与未保存的本地文本冲突，Locus 会阻止保存，直到你选择安全解决方案。
由于 .md 是权威文件，支持外部编辑器。如果外部文件操作后工作区没有及时更新，请刷新发现结果。重启 Unreal Editor 后编辑器选项卡不会自动恢复。
新的 Locus 文档 更喜欢活动或最近活动的 Locus 文档 选项卡堆栈；相同的标准化路径集中于其现有选项卡。选项卡仍可自由停靠，但在编辑器重新启动后不会恢复。
选中文档预览
Section titled “选中文档预览”选择文档时，工作区详情面板会显示只读 Markdown 预览。它展示已保存的权威文件；要阅读或编辑内容，请使用专用文档编辑器。在正常的短暂选择切换期间，预览会保持中性，直到选中的内容准备好。只有等待时间超过约一秒时，才会显示简洁的原生加载说明，而不是旧内容。
文档文件名和路径构成其工作区身份。Markdown 标题属于内容，因此重命名文件会更新显示的文件名，但不会改写 # My Title 这样的标题。
在 文档 编辑器 视图 菜单中，源文本字号 影响源编辑器，阅读字号 影响完整读取和分割预览。 Ctrl+mouse wheel 调整适用的视图。
文档归项目所有。新创建的文档在明确选择标记为添加前保持未跟踪，因此路径仍在变化时可以先整理。本地或未跟踪文档可以在本地模式中正常编辑。如果标记为添加失败，有效的 Markdown 仍会保留，可以重试。
已有仓库控制的文档仍可读取，但在明确签出成功前不能进入权威的编辑模式或执行保存。如果文档干净且未签出、已被其他用户或客户端签出、已过时，或与提供程序断开连接，Locus 会保持这些操作不可用。不提供强制写入的后门；适用时仍可使用阅读模式和导出副本。
重新连接版本控制后，刷新即可恢复受控状态。签出成功前文档仍为只读。Locus 不会提交、同步、管理变更列表或更改 typemap。请参阅版本控制、项目影响和依赖和故障排除。
如果没有配置提供程序，文档 不会显示特定于源代码管理的状态、指导、工具提示或操作。已配置但不可用的提供程序会保护已知的受控文件。