AICartographer 是一个嵌入 UE5 编辑器的 React 插件 + Python 后端，用 LLM 给整个项目的蓝图建一份"叙事地图"：

• 不是又一个蓝图浏览器 — 它写故事：每个 BP 的 markdown 页面会讲"OnDamageReceived 在 CurrentHP <= 0 时被 broadcast，被 GameMode.HandleDeath 消费"，而不是干巴巴列变量名。
• 不是又一个 AI 工具 — 它产出真正属于你项目的资产：所有 LLM 分析、笔记、tag 都落在 <project>/.aicartographer/vault/ 下的 .md 文件里，每位开发者本地一份，不进 git（原因和入职流程见下方）。
• 不是云端工具 — UE 编辑器和后端都跑在你本地，LLM key 由你输入并只活在 localStorage 里。

适合谁：处理过中大型 UE5 项目、想快速上手别人代码 / 自己旧项目的开发者。第一次拉到一个 50+ 蓝图的工程时，这玩意能让你少看 80% 的废墟。

graph TB
    subgraph UE["UE5 编辑器进程"]
        Editor[蓝图编辑器]
        Plugin[AICartographer C++ 插件]
        WebView[CEF WebView<br/>嵌入 React UI]
        Plugin -->|BindUObject| WebView
        Editor -.->|读取 UEdGraph| Plugin
    end

    subgraph Frontend["React 前端 (CEF 内)"]
        UI[四级视图<br/>+ Settings + AIChat]
        Stores[Zustand stores<br/>useLLMStore · useScanStore · useUIStore]
        Bridge[bridgeApi.ts<br/>JS ↔ UFUNCTION]
        HTTP[vaultApi.ts / scanApi.ts]
        UI --> Stores
        UI --> Bridge
        UI --> HTTP
    end

    subgraph Backend["Python FastAPI 后端"]
        Routes[main.py 路由]
        VW[vault_writer.py<br/>frontmatter + markdown]
        LP[llm_providers.py<br/>Volcengine + Claude]
        Redis[(Redis 任务队列)]
        Routes --> VW
        Routes --> LP
        Routes --> Redis
    end

    subgraph Vault["项目 vault (磁盘)"]
        MD["&lt;project&gt;/.aicartographer/vault/<br/>Blueprints/*.md · Systems/*.md · _meta/"]
    end

    subgraph LLM["LLM 服务"]
        VOL[Volcengine Ark]
        ANT[Anthropic API]
    end

    WebView <--> UI
    Bridge <--> Plugin
    HTTP -->|可选降级| Routes
    VW --> MD
    Bridge -.->|直读 markdown| MD
    LP --> VOL
    LP --> ANT

    style UE fill:#2d3748,stroke:#4a5568,color:#fff
    style Frontend fill:#1a365d,stroke:#2c5282,color:#fff
    style Backend fill:#22543d,stroke:#2f855a,color:#fff
    style Vault fill:#744210,stroke:#975a16,color:#fff
    style LLM fill:#553c9a,stroke:#6b46c1,color:#fff

桥优先级：C++ Bridge 可用就走 Bridge（无需启动 Python），缺失方法时降级到 localhost:8000 HTTP。LLM 调用永远走后端（Bridge 不持有 key）。

辅助：

• AIChat — 右下浮窗。基础模式做单轮 RAG 检索；Tools 模式打开后模型自主多轮调用 6 个工具（含 propose_edit 蓝图编辑建议），所有引用 / 提议中的目标资产都可点击直跳 Lv2
• QuickSwitcher — Cmd/Ctrl+P，按标题 / tag / intent 模糊匹配跳转
• Settings — 项目根 + LLM 厂商配置 + 语言开关 + Rebuild backlinks / Rebuild MOCs

截图位待上传 — 在 docs/images/ 下放 lv0-cardwall.png lv1-graph.png lv2-focus.png lv3-flow.png lv4-calltrace.png aichat-propose.png，再编辑此处的图片引用。

vault 内容（<project>/.aicartographer/vault/*.md）是 LLM 给每个蓝图写的叙事笔记 + 结构化 frontmatter，每位开发者本地一份。它不进 git，原因有两个：

• LLM 输出每次有差异 → 进 git 会让每次扫描产生巨大 diff、merge 冲突频繁
• vault 取决于本地的 LLM key、模型选择、扫描时机 → 不同开发者扫出来的 .md 不会一致

1. 拉代码（你的 UE 项目，不带 vault）
2. 启动 plugin，配置 LLM key 和模型（设置面板）
3. 点 Run framework scan（秒级，不调 LLM，写出骨架）
4. 顶栏 Run project scan（首次全量大约 15-30 分钟，取决于项目大小和模型）
5. 之后正常开发，AssetRegistry stale 监听会自动 mark 需要重扫的笔记（路线图阶段 A1）

你的 UE 项目 .gitignore 必须包含：

.aicartographer/

（如果你 fork 的是 AICartographer 仓库本身，本仓库的 .gitignore 已经包含此规则。）

两条路径：

给"只想用上"的同事 — 不需要克隆仓库、不需要装 Node、不需要装 Memurai。仓库自带的便携 Redis 直接打进 zip。

• Windows 10 / 11
• Unreal Engine 5.6+
• Visual Studio 2022（带"使用 C++ 的桌面开发"工作负载） — UE 第一次开项目时用它编插件
• Python 3.11+ — 安装时务必勾 "Add Python to PATH"（python.org/downloads）
• LLM API key：Volcengine endpoint id（ep-...）+ key，或 Anthropic API key
• 一个 UE C++ 项目作为测试床；没有可在 Epic Launcher → Marketplace 免费下载 Cropout sample

1. 拿到 zip — 从 GitHub Releases 下，或自己构建：

   git clone https://github.com/Liamour/UE-Mapping.git
   cd UE-Mapping
   .\dist\build-release.ps1
   # → release/AICartographer-Portable-<日期>.zip (1.6 MB)

2. 解压 + 启动后端 — 解压到任意目录（比如 D:\AICartographer\），双击 START.bat

   • 首次自动建 venv + pip install（1-3 分钟）
   • 看到 OK Backend healthy at http://127.0.0.1:8000/api/health 就成功了
   • 这个窗口别关 — 关了后端就停了。要停服务在窗口里按 Ctrl+C

3. 装插件到 UE 项目 — 双击 INSTALL-PLUGIN.bat

   • 自动列出 Documents\Unreal Projects\ 下的项目，选编号或粘贴 .uproject 路径
   • 脚本拷 plugin/AICartographer/ → <你项目>/Plugins/AICartographer/
   • 自动改 .uproject 把插件加到 Plugins[] 并启用

4. 第一次打开 .uproject — 双击 .uproject 文件

   • UE 弹 "Missing Modules" 对话框 → 点 Yes 让它编插件（VS 后台跑 1-2 分钟）
   • Blueprint-only 项目会先弹"Add C++ class"引导转 C++（一次性）
   • 编完 UE 自动打开

5. 打开面板 + 配置 — UE 菜单 Window → Developer Tools → Misc → AICartographer Web UI

   • 右上角齿轮 → Settings
   • Project root：填 .uproject 所在文件夹（比如 D:\MyGame）
   • Language：English / 简体中文
   • LLM Provider：选 Volcengine 或 Claude → 填 key → 点 Test connection 看绿灯
   • Settings → Run framework scan（秒级、不烧钱、写出骨架 .md）
   • 顶栏 → Run project scan（吃 LLM 配额，30 秒~几分钟）
   • 完成后进 Lv0 总览 → 点系统进 Lv1 → 点蓝图进 Lv2 → 点函数进 Lv3

扫完后 vault 落在 <你项目>/.aicartographer/vault/ 下，本地拥有，不进 git（团队协作章节 解释了原因）。详细排错见 INSTALL.md 和便携包内的 README-FIRST.txt。

AICartographer-Portable-<日期>/
├── START.bat                 ← 启动后端（双击）
├── STOP.bat                  ← 停止 / 清理残留
├── INSTALL-PLUGIN.bat        ← 拷插件到一个 UE 项目
├── README-FIRST.txt          ← 给终端用户的 5 分钟指南
├── backend/                  ← Python 后端源码（100 KB）
├── plugin/AICartographer/    ← UE 插件 + 预编译 React WebUI（580 KB）
├── runtime/redis/            ← 便携 Redis 二进制（2.9 MB）
└── tools/                    ← launcher.py / install_plugin.py / stop.py

首次启动后会多出 runtime/python-venv/（约 150-200 MB），存 fastapi/uvicorn/anthropic/openai 等依赖。

想 hack 代码 / 二次开发走这条。如果只是用，请走上面的便携包。

• UE 5.7+（构建好 AICartographer 插件）
• Python 3.11+（推荐 3.14；Win 用户注意 PATH 配 C:\Python<ver>\Scripts）
• Node 20+（开发前端用；UE webview 直接吃 build 好的单文件 bundle）
• Redis（任务队列；Win 自带的 3.0.504 已通过 pipeline-HSET 兼容）
• LLM API key：Volcengine ark.cn-beijing.volces.com endpoint id，或 Anthropic API key

git clone https://github.com/Liamour/UE-Mapping.git
cd UE-Mapping

# 后端
cd backend
pip install -r requirements.txt

# 前端
cd ../UE_mapping_plugin
npm install

# Redis
D:\path\to\Redis-x64-3.0.504\redis-server.exe

# FastAPI（新终端）
cd backend
python -m uvicorn main:app --reload --port 8000

cd UE_mapping_plugin
npm run build
# 自动写入 ../Plugins/AICartographer/Resources/WebUI/index.html (~508 kB single file)

• 把 Plugins/AICartographer/ 拷到你 UE 项目的 Plugins/
• VS / Rider 重新 build C++ 模块（Live Coding 不能注册新 UFUNCTION）
• 打开编辑器 → AICartographer 标签

1. Settings → Project root 填你的 UE 工程目录
2. Settings → LLM provider 配 key（Volcengine 或 Claude）→ Test connection
3. 选语言（English / 简体中文）
4. Settings → Run framework scan（无 LLM，秒级）→ 写出骨架 .md
5. 顶栏 Run project scan（L2 batch + L1 cluster，根据项目大小 30s ~ 几分钟）
6. 进 Lv0 看项目总览，点系统进 Lv1，点蓝图进 Lv2，点函数进 Lv3

.\dist\build-release.ps1                 # → release/AICartographer-Portable-<日期>.zip
.\dist\build-release.ps1 -Version 1.0.0  # 自定义版本号
.\dist\build-release.ps1 -NoZip          # 只生成目录，方便本地测

打包脚本只做拷贝，不修改源码。生成的 zip 是 1.6 MB，解压 3.6 MB。

密钥安全：

• 用户在前端填入，存 localStorage 的 aicartographer.llm.config
• 每次请求随 payload 带给后端，后端永不落盘
• 后端 .env 没有任何 LLM key 字段

可调参数（Settings → LLM provider）：

• 并发 1–64（默认 20，限流避免触发供应商 RPM 上限）
• 语言 EN / ZH（同时影响 UI 和 LLM 输出）
• 单次请求 90s 超时 + tenacity 重试 4 次（指数 1–30s）

切换 Settings → Language → 简体中文：

• ✅ 整个 UI（21 个组件）
• ✅ LLM 输出叙事（intent / 章节正文）
• ✅ Markdown 模板（## [ 简介 ] ## [ 成员 ] ## [ 反向链接 ]）
• ✅ 风险提示（> [!system_risk] 系统风险等级：**warning**）
• ❌ 受控词表保留英文（#system/combat #layer/gameplay 等，前端解析所用 key）
• ❌ asset_path / blueprint 名 / 函数标识符（资产唯一 ID）

已存在的 .md 不会自动回填语言 — 需要重扫（删 vault / 改 AST / 点 Rebuild backlinks 至少更新反链段）

UE-Mapping/
├── Plugins/AICartographer/              # UE5 C++ 插件
│   ├── Source/AICartographer/
│   │   ├── Public/AICartographerBridge.h     # UFUNCTION 暴露层
│   │   └── Private/AICartographerBridge.cpp  # ReadBlueprintFunctionFlow / RequestDeepScan / ListBlueprintAssets
│   └── Resources/WebUI/index.html       # vite-plugin-singlefile bundle 写入此处
│
├── UE_mapping_plugin/                   # React 前端
│   └── src/
│       ├── components/
│       │   ├── levels/                  # Lv0 / Lv1 / Lv2 / Lv3 视图
│       │   ├── shell/                   # ActivityBar / TopBar / Tabs / Breadcrumb
│       │   ├── settings/                # SettingsModal / LLMProviderPanel / ScanOrchestrator
│       │   ├── chat/AIChat.tsx
│       │   ├── search/QuickSwitcher.tsx
│       │   └── notes/NotesEditor.tsx
│       ├── services/
│       │   ├── bridgeApi.ts             # C++ Bridge wrapper
│       │   ├── vaultApi.ts              # vault HTTP/Bridge 双通路
│       │   ├── scanApi.ts               # batch scan
│       │   ├── frameworkScan.ts         # 骨架扫描（无 LLM）
│       │   └── projectScan.ts           # L1 项目聚类
│       ├── store/
│       │   ├── useLLMStore.ts           # 厂商 + 语言 + 并发
│       │   ├── useScanStore.ts          # 扫描进度 + 自动刷新
│       │   └── useUIStore.ts            # 视图模式 + 弹窗状态
│       └── utils/
│           ├── i18n.ts                  # useT() Hook + L10nMsg 类型
│           └── frontmatter.ts           # YAML 解析 + 嵌套→扁平规范化
│
├── backend/                             # Python FastAPI
│   ├── main.py                          # 路由 + L2 / L1 prompts
│   ├── llm_providers.py                 # LLMProvider ABC + Volcengine + Claude
│   ├── vault_writer.py                  # markdown 写入 + i18n 模板表
│   ├── tag_vocabulary_default.json      # 受控词表（system/layer/role）
│   └── requirements.txt
│
├── HANDOFF.md                           # 跨 session 完整工程交接文档（中文）
└── README.md                            # 本文件

cd UE_mapping_plugin
npx tsc --noEmit

npm run dev
# 仅在浏览器开发时用；UE webview 是吃 build 好的 bundle

cd backend
python -c "import ast; ast.parse(open('main.py', encoding='utf-8').read())"

每次在 AICartographerBridge.h 加新方法都需要关 UE → VS / Rider 重新 build → 重启编辑器。Live Coding 不能注册新 UCLASS / UPROPERTY / UFUNCTION。SettingsModal 的桥状态行会显示 partial（找到桥但缺方法）来提示需要 rebuild。

后端日志统一用 [SYS_LOG] [SYS_WARN] [SYS_ERR] [L1] [VAULT] 前缀，方便 grep。LLM key 在日志里走 mask_key() 脱敏。

• Redis 3.0.504（Win 自带）不支持多字段 HSET — 已用 pipeline + 单字段写入绕过。要升级建议换 Memurai 或 WSL2 + 官方 Redis 7.x。
• Live Coding 限制 — 见上文，新 UFUNCTION 必须冷重启。
• 切语言不回填旧 .md — is_unchanged() 跳过 AST 未变节点，需要 force rescan 才会用新语言重写模板。
• L3 函数流暂无 LLM 分析 — 当前 L3 只做可视化，文字解读由 L2 的 MEMBER INTERACTIONS 章节承担。
• propose_edit 仅出建议 — D0 阶段只输出结构化编辑卡片让你手动落地；D1 计划通过 C++ Bridge UFUNCTION 真正在 UE 编辑器里 compose 蓝图节点（暂未启动）。

• 真项目大规模实测（500+ BP 工程）
• AIChat 把当前打开的 Lv2/Lv3 节点喂给 LLM 当上下文 — Phase D0 已交付（RAG agent + 6 工具）
• propose_edit 蓝图编辑建议（输出 ProposalCard） — Phase D0 已交付
• Lv4 跨蓝图调用链 + reverse 方向 — 已交付
• D1：C++ Bridge UFUNCTION 真正在 UE 编辑器里落地 ProposalCard（一键 compose 节点）
• Notes 双向同步（编辑 → 触发 backlinks 重建）
• L3 加 LLM 函数级叙事（"这个函数的执行流是 ..."）
• CPP / Interface 类型的扫描器（当前以 BP 为主）
• 集成测试（pytest + Playwright）

MIT — 详见 LICENSE（如有）