黑石智算AI 助手
装在 Unreal Engine 编辑器里的 AI：读得懂当前工程，还能直接执行代码。
多数「AI 写代码」停在把代码贴给你：复制、切回编辑器、自己跑、报错再回来问。AI 助手把这条往返压回编辑器内部——它读得到当前工程，能调 19 个编辑器工具，也能把 Python 直接放到 GameThread 上执行；执行完可以截图回看，对不上就自己再改一轮。
UE5 编辑器内的 AI 助手插件：对话窗开在编辑器里，每一轮自动读当前工程（工程名、关卡、Actor 总数与类型分布、相机位置、选中对象），所以它答得上「这个场景里有什么」这类只有项目自己知道的问题。它还能调 19 个编辑器工具（场景对象、材质、资产、查询、执行），并把生成的 Python 代码点一次就在编辑器 Python 环境里跑起来——建 Actor、改材质、批量应用都直接落到场景里。跑完可以截图交给视觉模型回看，对不上就自己再改一轮；单次任务默认最多 10 轮，单步失败自动重试上限 3 次。模型端点不绑厂商：兼容 OpenAI 格式，插件内置 DeepSeek / OpenAI / Anthropic 三种协议实现。
- 19 个编辑器工具
- Agent 闭环：计划 → 执行 → 回看
- 3 个工作域
- 端点可换（兼容 OpenAI 格式）
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
一次对话到底发生了什么
按真实组件顺序，不是功能清单唤起
编辑器菜单打开对话窗，不切出工程；窗口是 UE Slate 面板，不是外挂网页。
取上下文
每轮注入工程名、当前关卡、Actor 总数与类型分布、相机位置；要细节再调查询工具。
计划
Agent 先把目标拆成步骤再执行，单次任务默认最多 10 轮。
调工具
19 个编辑器工具按「改什么」分组，参数按 JSON Schema 声明，填错当场报错。
执行
工具与 Python 都在 GameThread 上跑；Python 会话持久，变量跨代码块保留。
回看
可选：截图交给视觉模型判断有没有达成目标，不通过就修正再跑一轮。
19 个编辑器工具：按「改什么」分组，不是一张长清单
工具是模型能真正碰编辑器的手。这里没有把每个动作都做成工具——场景、材质、资产、查询分开，另留一个 execute_python 当通用口子，复杂操作一次写完。再加上一套效果配方：一句话就能复现一套布光或材质。
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
- 场景对象7
- 放 Actor、换网格、打光、加水体、镜头对焦与后处理，都在关卡里直接改。spawn_actor · set_static_mesh · delete_actor · create_light · create_water_body · focus_camera · set_post_process
- 材质5
- 建材质与实例、套到对象上、再调 BaseColor / Roughness / Metallic / Emissive；11 种常用预设一键起版。create_material · create_material_instance · create_material_preset · apply_material · set_material_property
- 资产4
- 项目 Content 与引擎内置资产分开列；先看清有什么再动手，避免模型凭空取一个不存在的路径。list_content · list_assets · get_asset_info · list_engine_assets
- 查询2
- 读关卡摘要、抓当前视口——这两条是「看得见」的来源，也是视觉回看的入口。get_scene_state · take_screenshot
- 执行1
- 通用口子：上面 18 个工具没覆盖的，用 Unreal Python API 一次写完。execute_python
- 环境布置5 条
- simple_room · grid_arrangement · circle_arrangement
- 布光5 条
- cinematic_lighting · sunset_golden_hour · night_scene
- 材质5 条
- metallic_weapon · glass_material · subsurface_skin
- 后处理3 条
- stylized_vintage · horror_atmosphere · bright_cartoon
配方 = 一串固定工具步骤：读场景 → 建对象 → 布光 → 调后处理，用一句话复现一套画面基调。
- Web 对话通道向模型声明的是 5 个工具（execute_python / list_assets / get_asset_info / create_material_preset / set_material_property）：编辑器里的 19 个工具注册表通过本地端口暴露，复杂动作走 execute_python 一次写完。
- 写操作没有撤销栈：delete_actor、改材质是立即生效的，只在编辑器自己的撤销历史里留一步。
- 配方是固定的英文步骤文案（工具名 + 参数），不随项目变化；套用前会先读一遍场景状态。
项目上下文：不用你先解释工程里有什么
模型不知道你的关卡里有什么，除非有人告诉它。「每轮自动取上下文」就是这个动作：不复制层级树、不先截图，它自己读。
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
- 工程名（FApp::GetProjectName）与当前关卡名
- Actor 总数 + 按类统计（例如 StaticMeshActor:128、DirectionalLight:3、Blueprint:24）
- 视口相机位置与视口尺寸
- 当前选中的对象路径（selected_actors）
- 要更细时：get_scene_state 读关卡摘要、list_content 列 Content 目录、list_engine_assets 列引擎资产
一次工具调用成功只说明代码没抛异常。开了视觉回看，Agent 在最后一步截一张图，交给视觉模型对照用户目标判断，结论作为一条消息回到对话，再决定要不要修正。
- 触发
- 工具全部成功、且已到最后一个步骤，同时设置里打开了 Enable Visual Feedback。
- 抓图
- take_screenshot 走 HighResShot，默认 1920×1080，返回 base64 PNG。
- 判断
- 视觉模型拿到「用户目标 + 已执行步骤 + 截图」，给出一段可直接执行的修正意见。
- 收敛
- 不通过进 Refine 阶段，最多 3 次自动重试；到顶就停下并报错，不空转。
- 上下文是每轮重新取，不是会话启动取一次：切了关卡、换了选中对象，下一句它就知道了。
- 注入的是文本摘要，不是整棵树：上千个 Actor 的场景也只是一行类型统计，不占满上下文窗口。
- 截图不进上下文，只有开启视觉回看时才抓一张，走视觉模型而不是主对话。
- 视觉回看默认关：截图 + 视觉推理是额外开销，按需打开。
- 抓的是当前视口，不是编辑器 UI：面板、属性栏、Content 浏览器都不在图里。
- 主模型不支持视觉时，回落到设置里单独填的视觉模型或 OpenAI 端点。
浏览器中继：编辑器端口不出本机
浏览器里的对话要指挥本机的编辑器，又不能把编辑器端口暴露到公网。做法是中继：模型要调工具时，服务端生成 relay_id、把调用推给浏览器，浏览器转发到本机插件，结果回传服务端后继续推理。
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
浏览器 Web UI
纯前端（React 19 + Vite）。流式渲染 + 中继：工具调用不带 JWT 打本机端口，避免令牌出现在编辑器一侧。
Go 服务
SSE 编排、工具定义注入、relay 等待 45s、知识库检索、会话与许可；模型只认这一侧。
本机插件 :9090
一个 TCP 端口双协议（HTTP + 行分隔 JSON）；HTTP 侧带 CORS 与 Private Network Access 头。
编辑器 GameThread
工具与 Python 都在编辑器主线程执行——改场景必须在这个线程上才安全。
- 浏览器和编辑器必须能互相访问：同一台机器，或同一个局域网（用 WebRTC 发现私有 IP，不用手填地址）。
- 单次工具等待 45s（服务端）/ 50s（浏览器）；超时按失败返回给模型，由模型决定重试还是换策略。
- 公网只到服务端：模型永远拿不到你编辑器的地址，插件端口也只在本地监听。
三个工作域：换的是提示词、工具与知识库
同一个窗口里切三个域。域不是「换个说话语气」——它决定模型拿哪套提示词、能不能碰编辑器工具、检索哪个知识库。
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
- UE 开发ue
- UE 专家提示词 + 全部编辑器工具 + UE 知识库；相邻问题（C++ 调试、日志分析、PBR 理论）按 UE 视角先答。
- 通用general
- 代码生成、架构设计与调试；不带编辑器工具，也不碰场景。
- 多媒体media
- 新闻写作、培训设计、游戏策划、动画脚本、VR/AR 方案与影视分镜。
- 意图路由（默认关）：UE 域首条消息由模型判断领域，非 UE 问题自动切到通用回答，页面提示「已自动切换」。
- 逃生通道（默认关）：明显偏离 UE 的消息在回答前给一张「切换到通用助手」，点击用新域重发，附件跟着走。
- 知识库：Markdown 按 ## 分段入库，中文用 bigram / trigram 切词打分，按域隔离；标了「共享」的文档只对通用域开放，跨域注入带来源标注。
- 召回最多 5 段、约 1500 token 预算；检索为空就静默降级，不拿空结果编答案。
- 教学域（genius）只对宿主一次性 handoff 换来的会话开放，其他来源请求该域一律 403，且不检索本地知识库。
- 知识库是管理员维护的 Markdown，不是自动爬取：写进去什么，检索才可能命中什么。
会话工作台：不是一次性脚本
长任务会跨很多轮、很多天。会话、标签、检索、导出与附件在同一个工作台里；布局按习惯切换，偏好记在本地。
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
会话
新建 / 重命名 / 删除；紧凑模式（侧滑面板）与展开模式（三栏）二选一，偏好存在本地。
检索
按标题或消息内容搜索历史会话，长会话不必靠翻。
标签
标签池按用户隔离、大小写不敏感唯一；给会话打多个标签，按标签筛。
导出
单会话导出一份 Markdown（最多 10000 条消息），交付或留档直接给文件。
附件
docx / pdf / txt / log / md / json / csv / xml / yaml；解析后进提示词，每人配额默认 500MB。
嵌入
可作为 iframe 进 Spark / Genius，用 SSO 换会话，不出现独立登录页。
- 会话与消息落 PostgreSQL；保留天数可配（0 = 不清理），到点按天清理并级联空会话。
- 附件访问查登记表：没有登记记录的路径直接 404，不靠「猜不到 URL」当权限。
许可、权限与审计：装在客户机器上的东西要有边界
插件装在客户自己的机器上，所以许可、权限与审计是一体的：没有有效许可助手不启动；管理面按权限键拆分；每一次许可签发都留台账。
把指针移到图上的模块（或点下面的标签）看它是什么 —— 配图上的动效表示数据往哪走。
许可绑定机器
RSA-2048（PKCS#1 v1.5 + SHA-256）签名的 .lic，绑定硬件指纹（MAC + 系统序列号）；过期即失效，支持吊销列表。
签发即审计
每次激活写一行台账（指纹 / IP / UA），写失败就拒绝签发；管理操作另有独立审计日志。
权限按域拆开
管理面分 users.* / system.* / knowledge.* 三组权限键；admin 恒放行，降权靠 token_version 即时失效。
限流与收敛
登录 10 次 / 5 分钟、注册 3 次 / 小时、许可激活 10 次 / 小时，超限 429 带 Retry-After。
外发地址受控
模型与 OAuth 的 base_url 只允许公网 host：127.0.0.1、10.x、云元数据地址一律拒绝；JSON 请求体 1MB 上限。
数据治理
消息保留天数可配；孤儿附件按登记表对账，磁盘上有文件但无记录由回填脚本处理。
- 引擎版本
- Unreal Engine 5.7+
- 依赖插件
- PythonScriptPlugin（UE 内置）
- 插件形态
- C++ 编辑器插件（AIAssistant.uplugin）+ 本地 TCP 服务 :9090（HTTP 与行分隔 JSON 双协议）
- Web 控制台（可选）
- Go 1.25 + PostgreSQL 16 + Nginx / systemd；不部署控制台时插件直连模型端点也能用
- 模型端点
- 兼容 OpenAI 格式；插件内置 DeepSeek / OpenAI / Anthropic 三种协议实现，端点、模型名与 Key 填在插件设置里
- 账号
- 控制台用 JWT（RSA 只验签）；可接 Spark / Genius SSO，也可独立账号
- 交付
- 插件目录 + 工程师协助接入配置（邮件申请，官网不提供安装包下载）
写信时把上表里对不上的项一并说明（引擎版本、是否需要 Web 控制台、模型端点在内网还是公网），我们回信能直接给方案。
申请 AI 助手 试用
官网不提供安装包下载，也没有自助注册或系统登录入口。所有产品一律邮件申请试用：说明使用场景，我们回复开通演示环境或安排演示。