内容
# LUX 本地优先的服务器/MCP 游戏自动化证据环
## LUX 是什么
LUX 不是一个 Unity 软件包，也不是一个目标游戏项目。它是一个独立的本地服务器和命令行界面，位于 AI 助手和引擎项目之间。
LUX 的核心问题是 AI 编码工具了解源文件，但通常无法看到当前的引擎状态：选定的对象、PlayMode、编译日志、场景层次结构、坐标、相机状态、UI 布局、截图和运行结果。LUX 使这些表面可观察和可重复，以便 AI 代理在声称进度之前。
## LUX 节奏
LUX 以固定的循环移动：捕获本地真相，根据证据做出决定，通过网关采取行动，通过引擎或 `.lux/` 验证，然后将结果写回为持久上下文。该循环故意比直接代码编辑慢，因为它使 AI 代理不会根据过时的假设声称进度。
## 内容区域
| 区域 | 内容 | 所属内容 | 不属内容 |
| --- | --- | --- | --- |
| `.lux/` | 运行时真相 | 规格、能力状态、票据、事件、路线图、会话、运行证据 | 复制的缓存真相或手动维护的文档状态 |
| `gateway/` | 控制平面运行时 | Rust 命令行界面、Axum HTTP/WS 服务器、MCP 工具、端点路由、引擎命令编排 | Unity 编辑器窗口、仪表板、前端应用程序 |
| `crates/` | 共享 Rust 包 | 从网关职责中分离的可重用核心逻辑 | 服务器线路，应位于 `gateway/` 中 |
| `bridge/` | 仓库中的引擎桥接源代码 | Unity C# 桥接包、Godot 适配器文件、Three.js 适配器源代码 | Git 子模块、外部桥接仓库、目标 Unity 项目状态、供应商依赖目录 |
| `Skills/` | 代理工作流库 | 清单支持的技能、引用、目录和模板，投射到目标项目中 | 声称工作流是引擎验证的，没有匹配的网关/桥接证据 |
| `docs/` | 可读的投影 | 用例、ADRs、支持层级、路线图解释和设计约束 | 当 `.lux/` 不同意时的规范运行时状态 |
| `scripts/` | 本地验证和维护 | 结构检查、策略扫描、烟雾脚本、发布/测试助手 | 长期运行的产品表面或隐藏的运行时状态 |
## 引擎能力快照
引擎支持使用能力路由，而不是平等验证成熟度。Unity 是主要的验证路径。Godot 和 Three.js 条目仅公开实际支持的命令和证据级别。
## 架构
```mermaid
flowchart LR
subgraph AI["AI 助手"]
Claude["Claude Code"]
OpenCode["OpenCode"]
Codex["OpenAI Codex"]
Other["其他 AI 客户端"]
end
subgraph Local["本地机器 - 仅限 localhost"]
subgraph Gateway["LUX Rust 网关"]
CLI["lux 命令行界面"]
HTTP["Axum HTTP API"]
WS["WebSocket 事件"]
MCP["MCP 服务器"]
Tools["工具执行层"]
SkillAdapter["技能适配器"]
end
subgraph State[".lux 工作空间 - SSoT"]
Spec["规格"]
Tickets["票据 / 看板"]
Events["事件日志 / 会话"]
Builds["构建 / 验证"]
Roadmap["路线图"]
end
subgraph Engine["引擎项目"]
Bridge["桥接适配器"]
Runtime["引擎运行时 / 编辑器"]
Context["上下文 / 选择 / 日志"]
Play["Play 模式 / 输入 / 捕获"]
end
end
Claude --> CLI
OpenCode --> CLI
Codex --> CLI
Other --> HTTP
Other --> MCP
CLI --> HTTP
MCP --> Tools
HTTP --> Tools
Tools --> State
SkillAdapter --> Tools
Tools --> Bridge
Bridge --> Runtime
Runtime --> Context
Runtime --> Play
Bridge --> Tools
Tools --> WS
```
## 核心表面
### 游戏上下文适配器
LUX 以上下文为优先，而不是以视觉为优先。它标准化了 AI 代理在编辑或声称游戏行为之前所需的证据：
## 命令行界面
常见命令：
```bash
# 安装和运行网关
cargo install --path gateway
lux serve
# 初始化目标项目并安装 Unity 桥接器
cd /path/to/your/project
lux init
lux bridge install --project-path /path/to/your/unity-project
# Unity 状态和验证
lux unity status
lux unity context
lux unity compile
lux unity run-tests
lux unity play
lux unity screenshot
# 规格、路线图、票据和 GitHub 问题
lux spec
lux spec edit gdd
lux spec validate
lux roadmap status
lux kanban
lux verify
# 技能和日志
lux skill list
lux skill info my-skill
lux ai-log recent
lux ai-log tail
```
## HTTP、WebSocket 和 MCP
代表性 API 表面：
## `.lux/specs` 游戏规格系统
游戏意图和领域决策位于 `.lux/specs/` 下。README 文件和 `docs/` 是该状态的可读投影。实际的游戏需求更改应通过定义的 `.lux/specs/spec.json`、`.lux/specs/gdd.md`、`.lux/specs/domains/*.md` 和 `.lux/specs/decisions.jsonl` 编写路径记录。
## 存储库结构
```text
Lux/
├── gateway/ # Rust 命令行界面 + Axum HTTP/WS 服务器
│ ├── src/
│ │ ├── main.rs # 命令行界面入口点
│ │ ├── server.rs # Axum 路由器
│ │ ├── protocol.rs # 事件信封和桥接协议
│ │ ├── project.rs # Unity 项目检测
│ │ ├── project_godot.rs # Godot 项目检测
│ │ ├── bridge_types.rs # 桥接类型定义
│ │ ├── godot_bridge_install.rs # Godot 桥接安装路径
│ │ ├── lux_*.rs # Lux 核心模块
│ │ ├── uloop_*.rs # Unity 命令行界面直通
│ │ ├── skill_adapter/ # 技能加载和适配
│ │ └── templates/ # 网关管理的模板
│ ├── tests/
│ └── Cargo.toml
│
├── crates/ # 共享 Rust 核心包
├── bridge/ # 引擎桥接适配器，存储库源代码
│ ├── unity/ # Unity C# 桥接器
│ ├── godot/ # Godot 桥接器
│ └── threejs/ # Three.js 适配器文件
├── Skills/ # 技能源代码树
├── docs/ # 可读文档和 ADRs
├── scripts/ # 验证和维护脚本
├── Cargo.toml
├── Cargo.lock
└── LICENSE
```
## 路线图现实
最小运行时路线图和里程碑状态位于 `.lux/roadmap.json`。用户/游戏需求、执行票据和活动运行状态位于 ADR-003 域路径下，例如 `.lux/specs/spec.json`、`.lux/specs/domains/*.md`、`.lux/tickets/*.json` 和 `.lux/run-state.json`。
## 核心不变性
存储库遵循从 `alex-core-invariants` 适配的六个不变性：
## 验证
```bash
# Rust
cargo build --workspace
cargo test --workspace
# 项目检查
bash scripts/check-project-structure.sh
bash scripts/check-readme-bridge-contract.sh
bash scripts/test-all.sh --quick
# 命令行界面帮助
cd gateway && cargo run -- bridge install --help
cd gateway && cargo run -- serve --help
```
Unity 桥接器测试需要 Unity 编辑器，应该通过 Unity Test Runner 在桥接器包中运行。
## 版权
版权 (c) 2024-2026 Linalab。保留所有权利。
MCP 市场