Developer API

Locus Developer API 允许本地 Unreal Editor 工具使用 Locus 笔记、文档和标记点。它面向 C++ 编辑器插件、Editor Utility Blueprint 和 Widget、Unreal Python 脚本以及编辑器内的流水线自动化。

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Developer 操作使用与 Locus UI 相同的验证、修订版本、持久化、冲突保护、文档路径规则、版本控制路由和应用生命周期。请使用 API，不要直接编辑 Locus 文件。

选择 API

接口	适用场景	从这里开始
Native C++	编辑器插件、原生工具、高级集成	C++ Developer API
Blueprint	Editor Utility Blueprint、Editor Utility Widget	Blueprint Developer API
Unreal Python	编辑器脚本、验证、批处理和无人值守自动化	Python Developer API

MCP 集成是面向 AI/代理的独立外部客户端接口。C++、Blueprint 和 Python Developer 工具不会在内部使用 MCP。

Engine 兼容性

核心 Locus、C++、Blueprint 和 MCP 支持 Unreal Engine 5.4–5.8。交互式和无人值守 Python Developer API 需要 Unreal Engine 5.6 或更高版本。

接口	UE 5.4–5.5	UE 5.6–5.8
C++	支持	支持
Blueprint	支持	支持
Python	不支持	支持
MCP	支持	支持

当前操作范围

在受支持的 Engine 版本上，C++、Blueprint 和 Python 都可以使用全部 16 个精选操作：

内容	操作
笔记	List、Get、Search、Create、Update、Archive
文档	List、Get、Search、Create、Update
标记点	List、Get、Create、更新元数据、添加评论

API 有意不公开笔记文件夹变更、文档重命名/移动/删除、标记点位置变更或完整锚点替换、标记点视图/表面操作、自动化能力协商或变更事件以及请求截止时间。

身份

笔记： GUID 加明确的共享或私有范围。
标记点： GUID 加明确的共享或私有范围。
文档： 相对于 ProjectDocuments 的规范化 Markdown 路径。

文档的呈现根、呈现路径、/Game/... 上下文和绝对文件系统位置都不是替代身份。

文档呈现根

创建请求会选择一个具体根。提供的路径相对于该可见根：

呈现根	提供的路径	权威身份
Locus 文档	`Design/Combat.md`	`Design/Combat.md`
内容浏览器	`Characters/Hero.md`	`Content/Characters/Hero.md`

在内容浏览器下创建时不要添加 Content/ 前缀。Locus 会应用一次映射。

修订版本

读取和成功的变更会返回不透明的修订版本。更新或归档必须将当前值作为 ExpectedRevision 提交：

Get → Snapshot + Revision → Update with ExpectedRevision

不要解析或伪造修订版本。如果结果是 StaleRevision，请重新读取当前条目并重新考虑更改。Locus 不会通过自动重新读取或重试来隐藏过时写入。

错误

请根据类型化的错误代码分支，不要解析人类可读消息：

InvalidInput、NotFound、AlreadyExists、Conflict、StaleRevision、AccessDenied、Unsupported、Busy、Cancelled、Unavailable、ShuttingDown 和 OperationFailed。None 表示没有错误。

可重试的 Unavailable 查询可以在之后的正常 Editor tick 中重新提交。等待时不要阻塞 Game Thread。

成功和版本控制状态是分开的

一次成功的本地变更可能将本地持久化报告为 Committed，同时将版本控制报告为 Pending、NotConfigured、Unknown 或 NotRequired。这仍然是成功的 Locus 操作。操作状态是面向用户正常版本控制工作流的、与提供程序无关的附加信息。

Locus 不会提交更改，也不会管理变更列表。

信任边界

C++、Blueprint 和 Python 是受信任的本地 Editor 工具。明确请求 Private 范围的调用方会有意访问当前项目的本地 Private 内容。MCP 的允许更改和允许私有笔记和标记点设置管理的是独立的外部客户端 MCP 边界，不适用于进程内 Developer API 调用方。