本页内容同步自
CLAUDE.md,请在该源文件修改后运行python Tools/gen_docs.py。
CLAUDE.md — UAL 开发与自检规范¶
本文件是 AI 编程代理在 UEAssetLens 仓库内工作的强制约束。优先级高于任何生成式习惯。
1. 先读契约,再写代码¶
修改任何涉及数据字段的代码前,必须按顺序阅读:
Server/schema/PROTOCOL.md— 三层格式与 JSONL 交换契约Server/schema/init.sql— DuckDB 表结构Source/UEAssetLens/Public/UALTypes.h— C++ 侧结构Server/ual_common/db.py— Python 侧读写
字段变更必须四处同步并递增 schema_meta.schema_version。禁止单侧改字段。
2. 不可违反的红线¶
- 禁止引入 VLM / 云端推理 / 外部 GPU。所有语义必须来自 UE 反射属性、确定性数学或引用图谱。
- 禁止把整库或全量 JSON 返回给 LLM。批量路径只能走
ual_common/toon.py;单资产精读只能走ual_common/yamlspec.py。 - 禁止手写 TOON / YAML 字符串拼接。必须调用唯一实现,保证转义、精度与 Diff 稳定。
- 禁止用
content_hash做查重。它只用于增量变更检测(.uasset重存会改变二进制哈希)。查重只用fingerprint_vec余弦相似度。 - 禁止加载贴图 / 网格进显存。UE 侧优先
FAssetDataTag-Value;领域提取器若必须加载,须显式标注并受 Commandlet 的无头模式约束。 - 禁止在 YAML / TOON 输出本地绝对路径、时间戳、随机 ID —— 否则 CI Diff 永远脏。
- DuckDB FTS 索引是快照,批量灌库后必须执行
rebuild_fts.sql。
3. 编码约定¶
跨语言¶
taxonomy规则唯一事实源是Server/ual_common/taxonomy.json:Python 侧ual_common/taxonomy.py直接读取,C++ 侧读Tools/gen_taxonomy.py生成的UALTaxonomyRules.h。禁止在任一侧另写一套类名 → 族名映射;改 JSON 后必须重跑生成器,--check会阻止生成物漂移。- 索引不设
AssetClass白名单:扫描、提取、灌库三层都不得按类型过滤或拒收。新资产类型应能被通用兜底提取器产出记录;命令行默认只扫/Game,需要插件内容时显式传-Roots=或-IncludePlugins。 logical_id在库内有 UNIQUE 约束;同名同类跨目录冲突由ual_common/db.py追加确定性路径哈希,禁止改成随机 ID 或直接丢弃记录。
C++(UE5)¶
- UE 命名法:
F结构、U对象、I接口、E枚举;头文件#pragma once。 fingerprint_vec固定 16 个float;缺失写NULL,不要写全零向量(会导致余弦退化)。- 所有除法必须做零除保护,禁止 NaN / Inf 进入索引。
- 新增提取器:实现
IAssetExtractor,Priority()返回 100,CanExtract()必须精确判定AssetClass,不得吞掉其他类型的资产。 - 不直接
#include <duckdb.h>;生产写入走IUALIndexSink抽象,Appender 实现由 ThirdParty 提供。
Python(Server/)¶
- Python ≥ 3.10;类型注解完整;只用
duckdb/PyYAML/mcp三个运行时依赖。 - MCP Server 只读连接 DuckDB(
read_only=True),绝不写索引。 - SQL 一律参数化,禁止 f-string 拼接用户输入(尤其是
domain_scope、filters)。 - 工具函数返回
str(TOON 或 YAML 文本),不返回 dict —— 这是 MCP 客户端上下文优化的前提。
4. 自检清单(提交前必跑)¶
python -m pytest Server/tests -q
python Server/ual_cli/ual_cli.py self-test
python Tools/gen_taxonomy.py --check # taxonomy 规则表无漂移
python Tools/gen_docs.py # 同步生成参考页
python Tools/gen_docs.py --check # 漂移门禁
python -m mkdocs build --strict --site-dir _site
必须全部通过,且覆盖:
- DDL 可在空库执行,重复执行幂等
- JSONL 灌库后
assets/asset_edges行数正确,FTS 可检索 - 4 个 MCP 工具输出符合
PROTOCOL.md的 section / 字段顺序 - 含逗号的值在 TOON 中被正确引用与还原
- 余弦自连接能命中阈值并返回非零退出码
-
verify-references能识别不存在的资产路径与错误的材质参数名 - YAML 输出不含时间戳与绝对本地路径
-
Tools/gen_docs.py --check无文档漂移,mkdocs build --strict零警告 -
python Server/ual_mcp/engine_bridge.py --self-test四项通过
4.1 文档站约定¶
- 站点配置在
mkdocs.yml,源文件在docs/;发布工作流是.github/workflows/docs.yml(main分支 + 官方 Pages 部署),Pages Source 必须设为GitHub Actions。 docs/reference/*.md与docs/agent-guide.md由Tools/gen_docs.py生成,禁止手工编辑。修改init.sql/PROTOCOL.md/TOOL_DEFS/ argparse /CLAUDE.md后必须重跑生成器并提交结果,否则 CI 的--check会失败。- 新增页面必须挂进
mkdocs.yml的nav,且所有相对链接要能通过--strict(断链会直接让发布失败)。 - 生成器只能用 Python 标准库 —— 文档工作流只安装
requirements-docs.txt,不装 DuckDB / PyYAML / MCP 运行时依赖。 _site/与site/不入库。
4.2 引擎内官方 MCP 约定¶
Source/UEAssetLensMCP/只在 UE6 且启用 EpicModelContextProtocol插件时生效。模块在PostEngineInit检查模块是否已加载,未启用则只打一条 Warning,不影响ual-cli与独立 Python MCP。- 禁止改用
UToolsetDefinition:ToolsetRegistry 会把工具名限定成<Toolset>.<Tool>,破坏与 Python 侧共享的 1:1 契约。用IModelContextProtocolModule::AddTool。 Server/ual_mcp/tool_schemas.json是工具名 / 描述 /inputSchema的唯一事实源,由Tools/gen_docs.py从tools.py的TOOL_DEFS生成,禁止手工编辑。改工具签名必须同步TOOL_DEFS、server.py的@sdk.tool()签名与生成器输出;gen_docs.py --check会比对两者并拦截漂移。- Python MCP Server 只支持官方 MCP SDK 2.x(
mcp>=2,<3,v2 中FastMCP已更名MCPServer)。禁止重新引入手写 JSON-RPC 协议层;SDK 缺失或不兼容时明确报错退出,不静默降级。 - C++ 侧不引入 DuckDB C API;工具调用委托给
engine_bridge.py子进程,通过 UTF-8 请求/响应文件传参(不要用 stdout,Windows 上会破坏中文注释编码)。 - 4 个工具全部只读,
GetAnnotations()必须返回accessMode=read/readOnlyHint=true。新增写操作前必须重新评估。 - 耗时调用走
RunAsync+ 线程池,禁止在 game thread 上同步等 Python 进程。 - 每次调用启动一个 Python 进程是已知成本,不要偷偷改成常驻进程而不更新
docs/known-limitations.md。 - 官方 server 是 HTTP loopback 且无认证,禁止把它暴露到非 loopback 地址。
UE 侧另需 UnrealEditor-Cmd.exe 编译并运行 UEAssetLensTests 自动化用例;本仓库 CI 不假定存在 UE SDK。
5. 提交与协作¶
- 提交信息用英文祈使句,例如
feat(mcp): add TOON bundle serializer。 .ual/、.workbuddy/、Binaries/、Intermediate/不入库。- 不要自动
git push。本地提交与外部推送需用户显式确认。 - 本仓库嵌在宿主工程
Ann/Plugins/UEAssetLens,是独立 git 仓库;不要在父仓库Ann中git add本目录(会产生 gitlink)。
6. 遇到不确定时¶
优先查 docs/architecture.md 与 docs/known-limitations.md。若仍不确定,先说明假设再实现,不要静默猜测字段语义或资产类型。