内容
# 材料导航
### 一个用于Material Maker中可编辑的程序化材质的本地优先MCP桥接
[](https://github.com/SS-360/materialpilot/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/RodZill4/material-maker)
[](https://godotengine.org/)
[](https://nodejs.org/)
MaterialPilot 使MCP兼容的AI代理能够检查、创建、组织、验证、预览、保存和导出真正的Material Maker项目。它通过Material Maker的原生图表和撤销API工作，而不是UI坐标，并保持程序化图表对艺术家可编辑。
当前的`0.1.0`实现预览版公开了**143个类型化的MCP工具**，一个生成的**392个Material Maker 1.7节点定义**目录，修订安全的图表事务，确定性验证，有界渲染，命名恢复快照，原生撤销/重做和验证的Blender配置文件PBR导出。
> [!IMPORTANT]
> MaterialPilot是一个经过测试的实现预览版，而不是计划中描述的完整的`1.0`版本。不支持和风险较高的操作被能力门控，而不是被模拟。请参阅[当前限制](#当前限制)。
## 为什么选择MaterialPilot？
程序化材质图表是有价值的，因为它们保持可编辑、可重用和参数化。传统的文本到纹理工作流通常在扁平图像上停止，而一般的桌面自动化无法可靠地理解图表端口、项目修订、渲染器状态或撤销历史。
MaterialPilot为代理提供对底层创意系统的结构化访问：
- **可编辑的输出：** 主要工件是原生`.ptex`图表，而不仅仅是导出的图像。
- **原生集成：** 图表操作使用Material Maker和Godot API，而不是鼠标坐标。
- **观察后修改：** 代理在编辑前检查项目、修订、目录和功能。
- **原子更改：** 图表补丁要么作为一个撤销步骤提交，要么恢复到其确切的预状态。
- **确定性安全：** 模式、端口兼容性、路径策略、修订和验证在语言模型之外强制执行。
- **视觉证据：** 实时节点输出和球体/平面预览提供有界PNG证据。
- **验证交付：** Blender导出包括尺寸、文件大小和SHA-256哈希。
- **本地优先操作：** 原生通信是身份验证的，并绑定到环回。
## 它是如何工作的
```mermaid
flowchart LR
Host["MCP主机<br/>Codex · IDE · CLI"]
Server["MaterialPilot MCP服务器<br/>TypeScript"]
Bridge["原生桥<br/>GDScript"]
Maker["Material Maker 1.7<br/>Godot 4.7"]
Core["领域服务<br/>模式 · 图表引擎 · 验证器 · 安全"]
Host <-->|"MCP over STDIO or authenticated HTTP"| Server
Server <-->|"Authenticated loopback WebSocket JSON-RPC"| Bridge
Bridge <-->|"原生图表、渲染器、保存、导出、撤销"| Maker
Server --- Core
```
Material Maker在原生桥运行时写入身份验证发现记录。MCP服务器读取该记录，协商可用的功能并连接本地。如果没有可用的实时桥，服务器可以回退到离线参考引擎，用于目录、规划、模式和事务工作；仅限实时功能保持为假。
每个原生图表突变都遵循相同的边界：
```text
检查修订 -> 验证补丁 -> 快照 -> 应用操作
-> 结构验证 -> 提交一个撤销条目
-> 发出修订、差异、诊断和证据
任何环节失败 -> 恢复序列化快照 -> 返回结构化错误
```
有关设计原理，请参阅[架构概述](docs/architecture/overview.md)和[架构决策记录](docs/adr)。
## 功能
| 领域 | 当前支持 |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| 应用程序 | 健康、状态、版本、功能、限制和实时/离线模式发现 |
| 项目 | 列出、检查、创建原生材质选项卡、保存`.ptex`和创建命名恢复快照 |
| 目录 | 搜索和检查392个生成的Material Maker 1.7节点描述、端口、参数、别名和兼容性 |
| 图表 | 读取规范快照、计划补丁、试运行、原子应用、差异、验证、撤销和重做 |
| 编辑 | 创建、删除、连接、断开、移动、参数化、批量编辑、注释和公开远程控制 |
| 布局 | 语义阶段、注释、位置、选择、图表组织和输出保留修复工作流 |
| PBR | 反射率、粗糙度、金属度、法线、高度/深度、环境遮挡、发射和相关输出检查 |
| 预览 | 有界节点输出PNG和渲染器支持的球体/平面材质预览 |
| 导出 | 策略约束的Blender配置文件PNG/EXR映射，带有临时发布和哈希验证 |
| 诊断 | 确定性验证、事务历史、性能检查、结构化错误和关联证据 |
| 工作流 | 裂纹石、玄武岩、砂岩、熔岩、氧化金属和一个完整的废弃工业地板工作流 |
每个工具的权威模式和行为都在[工具参考](docs/tools/core-tools.md)中记录。
## 安全模型
MaterialPilot将用户项目、图表注释、下载的元数据、文件路径和模型输出视为不受信任的数据。
默认安全控件包括：
- 仅环回的原生和HTTP监听器；
- 短暂的身份验证桥接令牌；
- 工作区读取、写入和导出根目录；
- 规范路径检查和显式覆盖策略；
- 通过`expectedRevision`进行乐观并发控制；
- 变更和导出的幂等键；
- 快照优先的事务和回滚；
- 原生撤销/重做集成；
- 渲染器依赖的功能协商；
- 默认禁用自定义着色器写入和网络操作；
- STDIO MCP服务器仅输出stderr诊断。
选择适合工作流的最严格权限模式：
| 模式 | 行为 |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `observe` | 只读检查；需要批准令牌才能进行变更 |
| `assisted` | 默认；受保护的写入需要一次性批准 |
| `workspace-autonomous` | 允许在批准的工作区根目录内进行可逆图表编辑 |
| `developer` | 更广泛的本地开发访问；自定义代码和网络权限仍然是分开的 |
在敏感工作区启用自动化之前，请阅读[SECURITY.md](SECURITY.md)和[威胁模型](docs/security/threat-model.md)。
## 需求
| 组件 | 支持版本 | 目的 |
| -------------- | -------------------------- | ------------------------------------------------------- |
| Node.js | 22.13.0或更新版本 | MCP服务器、CLI、包和测试 |
| pnpm | 11.9.0 | 源构建和开发 |
| Material Maker | 1.7 | 实时程序化材质编辑 |
| Godot | 4.7稳定版 | 从源代码运行或导出Material Maker |
| MCP主机 | 当前兼容版本 | Codex Desktop、Codex CLI、IDE或另一个MCP客户端 |
TypeScript工作区和CI针对Windows、Linux和macOS。原生兼容性套件固定为Material Maker 1.7和Godot 4.7。渲染器支持的预览和导出操作需要真正的Godot渲染设备，并且在无头会话中故意不可用。
## 快速入门
### 1. 构建MaterialPilot
```bash
git clone https://github.com/SS-360/materialpilot.git
cd materialpilot
corepack enable
corepack prepare pnpm@11.9.0 --activate
pnpm install --frozen-lockfile
pnpm build
pnpm check
```
运行诊断CLI：
```bash
node packages/cli/dist/main.js doctor
```
### 2. 安装原生插件
在安装或更新插件之前，请关闭Material Maker。复制：
```text
apps/material-maker-bridge/addon/materialpilot
```
进入Material Maker 1.7源项目，如下：
```text
addons/materialpilot
```
例如，在PowerShell中：
```powershell
$materialPilot = 'D:\path\to\materialpilot'
$materialMaker = 'D:\path\to\material-maker-1.7'
$target = Join-Path $materialMaker 'addons\materialpilot'
New-Item -ItemType Directory -Force $target | Out-Null
Copy-Item -Path (Join-Path $materialPilot 'apps\material-maker-bridge\addon\materialpilot\*') `
-Destination $target -Recurse -Force
```
打开Material Maker项目并在Godot中启用**MaterialPilot Native Bridge**，位于
**Project → Project Settings → Plugins**。插件安装此自动加载：
```ini
[autoload]
MaterialPilotBridge="*res://addons/materialpilot/bridge/bridge_server.gd"
```
正常启动Material Maker。在运行时，默认发现记录为：
- Windows： `%USERPROFILE%\.materialpilot\bridge.json`
- Linux/macOS： `~/.materialpilot/bridge.json`
该记录包含一个短暂的令牌。不要发布、提交或分享它。
通过以下命令验证实时桥接：
```bash
node packages/cli/dist/main.js bridge status
```
### 3. 连接MCP客户端
STDIO是推荐的单个本地客户端的传输方式。通过绝对MCP服务器路径配置客户端以启动Node：
```text
node /absolute/path/to/materialpilot/apps/mcp-server/dist/main.js
```
适用于Windows上的Codex CLI：
```powershell
codex mcp add materialpilot `
--env MATERIALPILOT_PERMISSION_MODE=workspace-autonomous `
-- 'C:\Program Files\nodejs\node.exe' `
'D:\absolute\path\to\materialpilot\apps\mcp-server\dist\main.js'
```
或者，将源代码checkout直接添加到`~/.codex/config.toml`:
```toml
[mcp_servers.materialpilot]
enabled = true
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\absolute\path\to\materialpilot\apps\mcp-server\dist\main.js']
cwd = 'D:\absolute\path\to\materialpilot'
startup_timeout_sec = 10
tool_timeout_sec = 60
[mcp_servers.materialpilot.env]
MATERIALPILOT_PERMISSION_MODE = "workspace-autonomous"
```
在MCP客户端启动Material Maker之前。如果客户端启动并进入离线模式，请在桥接记录出现后重新启动。
有关打包发布、Linux/macOS配置、身份验证HTTP传输和运行时路径覆盖的完整安装和运行指南，请参阅[安装和运行指南](docs/user/installation.md)。
## 验证实时会话
要求MCP主机检查修改前状态：
```text
使用MaterialPilot的app_get_status和app_get_capabilities工具。报告原生Material Maker桥是否连接，离线模式是否激活，Material Maker和Godot版本，活动项目ID，以及graph.read，graph.write，graph.transactions，preview.material3d和export.write是否可用。不要更改图表。
```
渲染器支持的实时会话应报告等效的值：
```json
{
"bridgeConnected": true,
"offlineMode": false,
"materialMakerVersion": "1.7",
"godotVersion": "4.7-stable"
}
```
如果`offlineMode`为`true`，则不要期望可见的Material Maker更改。请参阅[故障排除](docs/user/troubleshooting.md)。
## 示例代理工作流
```text
使用MaterialPilot，检查活动的Material Maker项目和节点目录。创建一个可编辑、无缝拼接的工业地板，带有裂纹混凝土、暴露的金属板、锈迹、油渍、湿润、剥落的边缘和集中在裂纹中的污垢。
创建命名恢复快照。将图表组织成标记的源、掩码、PBR表面、反照率、控件和输出阶段。在应用之前规划和试运行完整的补丁。以一个修订安全事务的方式应用它。公开艺术家控件以控制比例、裂纹密度和深度、金属、锈迹、油渍、湿润、污垢、磨损和随机种子。运行严格验证、渲染通道和球体/平面预览，然后导出验证的Blender映射。停止并报告任何不可用的功能或警告。
```
MaterialPilot不会仅凭图表验证推断视觉成功。渲染器支持的预览和导出的工件仍然是单独的证据。
## 旗舰生产工作流
存储库包括一个完整的可执行**废弃工业地板**工作流，该工作流端到端地锻炼生产路径：
1. 目录检查和结构化规划；
2. 命名恢复快照；
3. 试运行和原子图表补丁；
4. 语义阶段、注释和公开控件；
5. 严格的确定性验证；
6. 原生可编辑`.ptex`保存；
7. 2048 × 2048 Blender通道导出；
8. 球体、平面和通道预览；
9. 三个受控变化；
10. 尺寸、像素方差、文件大小和SHA-256验证；以及
11. 生成的Markdown材质指南和工件清单。
启动带有桥接启用的Material Maker，选择一个新的工件目录，并运行：
```powershell
$env:MATERIALPILOT_ARTIFACT_ROOT = 'D:\exports\abandoned-industrial-floor-run-01'
node .\scripts\create-abandoned-industrial-floor.mjs'
```
工件目录必须是新的。工作流故意拒绝静默覆盖。
对于基于烟雾的512分辨率快速运行基准测试：
```powershell
$env:MATERIALPILOT_SMOKE = '1'
$env:MATERIALPILOT_ARTIFACT_ROOT = 'D:\exports\abandoned-industrial-floor-smoke-01'
node .\scripts\create-abandoned-industrial-floor.mjs'
```
## 开发和测试
### 标准存储库检查
```bash
pnpm format
pnpm typecheck
pnpm lint
pnpm test
pnpm build
```
组合的类型检查、lint和单元/集成门是：
```bash
pnpm check
```
该套件涵盖了模式、稳定ID、规范哈希、目录兼容性、确定性诊断、事务回滚、修订冲突、幂等性、撤销/重做、路径策略、桥接握手、PTEX/MMPP往返、CLI行为和MCP一致性。
### Godot桥接合约
将`GODOT_BIN`设置为官方Godot 4.7可执行文件：
```powershell
$env:GODOT_BIN = 'C:\path\to\Godot_v4.7-stable.exe'
pnpm test:godot
```
这验证了GDScript解析、身份验证的桥接初始化、稳定ID、握手和状态行为。
### 完整的Material Maker合约
将当前插件安装到Material Maker 1.7源代码checkout，然后运行：
```powershell
$env:GODOT_BIN = 'C:\path\to\Godot_v4.7-stable.exe'
$env:MATERIAL_MAKER_PROJECT = 'D:\path\to\material-maker-1.7'
pnpm test:material-maker
```
无头合约验证图表创建、原生参数、试运行恢复、提交、撤销、重做、保存和对渲染器依赖的操作的安全拒绝。
使用以下命令运行GPU支持的预览和导出合约：
```powershell
$env:MATERIALPILOT_WINDOWED_TEST = '1'
pnpm test:material-maker
```
窗口化合约渲染真实的节点输出，拒绝空白或洋红色缺失材质预览，测试球体和平面捕获，并验证Blender导出。测试窗口被定位到屏幕外。
要运行环境中可用的所有兼容合约：
```bash
pnpm compatibility
```
有关详细信息，请参阅[构建和测试](docs/development/building.md)。
## 存储库结构
```text
materialpilot/
├── apps/
│ ├── mcp-server/ MCP传输、工具模式、资源和翻译
│ └── material-maker-bridge/ 原生Godot/Material Maker插件和合约
├── packages/
│ ├── bridge-protocol/ 身份验证的原生JSON-RPC客户端和模式
│ ├── cli/ 医生、桥接健康、lint和规范命令
│ ├── domain/ 稳定公共图表、补丁、诊断和功能模型
│ ├── graph-engine/ 离线事务、修订、幂等性、撤销和重做
│ ├── mmpp/ Material Maker绘画项目适配器
│ ├── node-catalog/ 生成和稳定的节点描述符
│ ├── ptex/ 程序纹理项目解析和往返
│ ├── security/ 权限、审计、规范路径和工作区策略
│ └── validator/ 确定性结构和PBR验证
├── docs/ 架构、ADR、指南、安全性和工具参考
├── fixtures/ 兼容性和序列化fixtures
├── schemas/ 已发布的JSON兼容模式
└── scripts/ 兼容性、发布、SBOM和生产工作流
```
架构边界是故意的：
- `apps/mcp-server`仅拥有MCP传输和翻译。
- `apps/material-maker-bridge`仅拥有Godot和Material Maker集成。
- `packages/domain`从未公开Godot对象。
- `packages/graph-engine`拥有事务和修订语义。
- `packages/validator`保持确定性和与LLM无关。
- `packages/security`拥有路径和权限决策。
## 当前限制
以下功能在 `0.1.0` 版本中故意不可用或不完整：
- 原生项目打开和关闭的 mutations；
- 导出配置文件，支持 Blender 和特定于引擎的打包；
- 任意面板捕获，直方图自动化和自动感知比较；
- 资产库安装和社区网络操作；
- 任意子图 mutation 和生成的自定义着色器写入；
- 绘画 mutations 和自动笔画；以及
- 远程或多用户部署，支持认证的回环 HTTP。
绘画数据仅限检查，自定义着色器写入仍然禁用。在 Godot 的无头/虚拟渲染器下，渲染器支持的功能不可用。这些是明确的能力结果，而不是静默的回退。
请参阅 [实现状态](docs/development/implementation-status.md) 和
[生产实施计划](materialpilot-production-implementation-plan.md)，了解路线图和稳定的 `1.0` 版本定义。
## 使用 Codex 和 GPT-5.6 构建
由 GPT-5.6 驱动的 Codex 在 MaterialPilot 的开发过程中被用作主要的工程协作工具。
它帮助：
- 设计 MCP 服务器和原生 Godot 桥接架构；
- 实现类型化的工具、模式、事务、快照和回滚；
- 检查和组织 Material Maker 程序图；
- 诊断缺失的纹理、桥接失败和渲染问题；
- 创建确定性验证和自动测试；
- 构建废弃的工业楼层演示工作流；
- 验证 Blender 导出、预览、哈希和生成的工件；
- 审查存储库、文档、安全边界和发布准备情况。
人类开发人员指导产品愿景，做出架构和创意决策，在 Material Maker 中测试集成，审查生成的更改，并验证最终的用户体验。
Codex 被用作协作工程代理，而不仅仅是代码生成器。它检查现有系统，提出更改，编辑存储库，运行测试，诊断故障，并根据实际应用程序结果进行迭代。
## 文档
- [安装和运行指南](docs/user/installation.md)
- [第一个材质](docs/user/first-material.md)
- [故障排除](docs/user/troubleshooting.md)
- [工具参考](docs/tools/core-tools.md)
- [实现状态](docs/development/implementation-status.md)
- [架构概述](docs/architecture/overview.md)
- [事务模型](docs/architecture/transactions.md)
- [Material Maker 1.7 集成映射](docs/architecture/upstream-1.7-map.md)
- [构建和测试](docs/development/building.md)
- [安全威胁模型](docs/security/threat-model.md)
## 贡献
欢迎贡献。从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始，保留上述软件包边界，并包含测试和文档以实现行为更改。
在打开拉取请求之前：
```bash
pnpm install --frozen-lockfile
pnpm format
pnpm check
pnpm build
```
原生桥接更改还必须通过 `pnpm test:godot` 和受影响的 Material Maker 合同。
mutations 需要乐观并发、幂等键、事务/回滚支持、模式、文档、测试和威胁分类。
## 安全
私密地向维护人员报告漏洞。永远不要将私有项目、桥接令牌、HTTP 承载令牌、导出的专有纹理或包含敏感路径的日志附加到公共问题上。有关支持的披露过程，请参阅 [SECURITY.md](SECURITY.md)。
## 许可证
MaterialPilot 在 [Apache License 2.0](LICENSE) 下获得许可。Material Maker 仍然是一个独立的上游项目，根据其自己的许可证分发；保留在重新分发集成构建时保留上游通知。
## 致谢
MaterialPilot 建立在 [Material Maker](https://github.com/RodZill4/material-maker)、
[Godot Engine](https://godotengine.org/) 和
[模型上下文协议](https://modelcontextprotocol.io/) 的基础上。该项目旨在补充 Material Maker 面向艺术家的工作流程，同时保留可编辑的图表和人为控制。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器