docs: optimize project rules with comprehensive coding standards
This commit is contained in:
火焰库拉
@@ -1,30 +1,273 @@
|
||||
---
|
||||
trigger: always_on
|
||||
description: "MCP Bridge 插件开发规则和编码规范"
|
||||
---
|
||||
|
||||
# MCP Bridge Development Rules
|
||||
|
||||
## 1. Critical Workflow
|
||||
- **Reload Required**: Any changes to `main.js`, `package.json`, `scene-script.js`, or `panel/` MUST be followed by reloading the plugin ("Reload Package") or restarting the editor. Hot reload does not apply to main process scripts.
|
||||
- **Test-Driven**: Always create a standalone test script in `test/` (e.g., `test/test_feature.js`) for new features. Tests must direct HTTP requests to verify functionality.
|
||||
## 1. 语言规范 (Language)
|
||||
|
||||
## 2. Architecture & IPC
|
||||
- **Process Isolation**:
|
||||
- `scene-script.js` (Renderer Process) CANNOT access `Editor.assetdb` or `Editor.FileSystem`.
|
||||
- `main.js` (Main Process) CANNOT access `cc` (Cocos Engine) directly.
|
||||
- **Rule**: Resolve asset paths (URL -> UUID) in `main.js` using `Editor.assetdb.urlToUuid()` BEFORE calling `callSceneScript`. Pass UUIDs to the scene script.
|
||||
- **Logging**:
|
||||
- Use `addLog(type, message)` in `main.js` instead of `console.log` to ensure logs are captured by the `read_console` tool and visible in the panel.
|
||||
* **强制中文**: 所有的对话回复、代码注释、以及生成的文档都必须使用**中文**。
|
||||
* **日志消息**: `addLog()` 的消息内容可以使用中英文混合，确保关键术语清晰。
|
||||
|
||||
## 3. Coding Standards
|
||||
- **Safe Editing**: Be extremely careful when editing `main.js` to avoid duplicate code blocks or closing braces. Use `view_file` to verify context.
|
||||
- **Undo/Redo**:
|
||||
- All scene-modifying actions (node transform, property changes) SHOULD support Undo/Redo.
|
||||
- Use `Editor.Ipc.sendToMain('scene:undo-record', ...)` if modifying via scene script, or wrap operations in `manage_undo` groups.
|
||||
---
|
||||
|
||||
## 4. Feature Specifics
|
||||
- **Particle Systems (VFX)**:
|
||||
- Always set `particleSystem.custom = true` when modifying properties via script.
|
||||
- Ensure a valid `texture` is set (or load a default one like `db://internal/image/default_sprite_splash.png`) to avoid invisible particles.
|
||||
- **Resource Loading**:
|
||||
- Built-in assets (`db://internal/...`) may need specific extensions (`.png`, `.jpg`) depending on the editor version. Try multiple paths if lookup fails.
|
||||
## 2. 关键工作流程 (Critical Workflow)
|
||||
|
||||
### 2.1 插件重载
|
||||
- **必须重载**: 修改 `main.js`, `package.json`, `scene-script.js`, 或 `panel/` 后，**必须**在编辑器中执行「扩展 → 刷新」或重启编辑器。
|
||||
- **热更新不适用**: Cocos Creator 2.x 的插件主进程脚本不支持热更新。
|
||||
|
||||
### 2.2 测试驱动
|
||||
- **测试脚本**: 每个新功能必须在 `test/` 目录下创建独立测试脚本 (如 `test/test_feature.js`)。
|
||||
- **HTTP 验证**: 测试脚本通过 HTTP 请求直接调用插件 API，验证功能正确性。
|
||||
- **运行前提**: 确保 Cocos Creator 编辑器已打开且 MCP Bridge 服务已启动。
|
||||
|
||||
---
|
||||
|
||||
## 3. 架构与进程隔离 (Architecture & IPC)
|
||||
|
||||
### 3.1 进程职责划分
|
||||
|
||||
| 文件 | 进程 | 可访问 | 不可访问 |
|
||||
|------|------|--------|----------|
|
||||
| `main.js` | 主进程 (Main) | `Editor.assetdb`, `Editor.Ipc`, `require()` | `cc.*` (Cocos 引擎) |
|
||||
| `scene-script.js` | 渲染进程 (Renderer) | `cc.*`, `cc.engine`, `cc.director` | `Editor.assetdb`, `Editor.FileSystem` |
|
||||
|
||||
### 3.2 跨进程通信规则
|
||||
|
||||
```
|
||||
主进程 (main.js) 渲染进程 (scene-script.js)
|
||||
│ │
|
||||
├─ 1. 接收 HTTP 请求 │
|
||||
├─ 2. 解析 db:// 路径为 UUID │
|
||||
│ Editor.assetdb.urlToUuid() │
|
||||
├─ 3. 调用场景脚本 ──────────────────────┤
|
||||
│ Editor.Scene.callSceneScript() │
|
||||
│ ├─ 4. 操作节点/组件
|
||||
│ │ cc.engine.getInstanceById()
|
||||
│ ├─ 5. 通知场景变脏
|
||||
│ │ Editor.Ipc.sendToMain("scene:dirty")
|
||||
└─ 6. 返回结果 ◀────────────────────────┘
|
||||
```
|
||||
|
||||
**核心规则**: 永远在 `main.js` 中将 `db://` 路径转换为 UUID，再传递给 `scene-script.js`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 编码规范 (Coding Standards)
|
||||
|
||||
### 4.1 命名规范
|
||||
|
||||
| 类型 | 规范 | 示例 |
|
||||
|------|------|------|
|
||||
| 函数名 | camelCase | `handleMcpCall`, `manageScript` |
|
||||
| 常量 | SCREAMING_SNAKE_CASE | `MAX_RESULTS`, `DEFAULT_PORT` |
|
||||
| 私有变量 | _camelCase | `_isMoving`, `_timer` |
|
||||
| 布尔变量 | is/has/can 前缀 | `isSceneBusy`, `hasComponent` |
|
||||
| MCP 工具名 | snake_case | `get_selected_node`, `manage_vfx` |
|
||||
| IPC 消息名 | kebab-case | `get-hierarchy`, `create-node` |
|
||||
|
||||
### 4.2 函数组织顺序
|
||||
|
||||
在 `module.exports` 中按以下顺序组织函数：
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
// 1. 配置属性
|
||||
"scene-script": "scene-script.js",
|
||||
|
||||
// 2. 生命周期函数
|
||||
load() { },
|
||||
unload() { },
|
||||
|
||||
// 3. 服务器管理
|
||||
startServer(port) { },
|
||||
stopServer() { },
|
||||
|
||||
// 4. 核心处理逻辑
|
||||
handleMcpCall(name, args, callback) { },
|
||||
|
||||
// 5. 工具函数 (按字母顺序)
|
||||
applyTextEdits(args, callback) { },
|
||||
batchExecute(args, callback) { },
|
||||
// ...
|
||||
|
||||
// 6. IPC 消息处理
|
||||
messages: {
|
||||
"open-test-panel"() { },
|
||||
// ...
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 4.3 避免重复定义
|
||||
|
||||
> ⚠️ **重要**: `main.js` 已存在重复函数问题，编辑前务必使用 `view_file` 确认上下文，避免创建重复定义。
|
||||
|
||||
**检查清单**:
|
||||
- [ ] 新增函数前，搜索是否已存在同名函数
|
||||
- [ ] 修改函数时，确认只有一个定义
|
||||
- [ ] `messages` 对象中避免重复的消息处理器
|
||||
|
||||
### 4.4 日志规范
|
||||
|
||||
使用 `addLog(type, message)` 替代 `console.log()`：
|
||||
|
||||
```javascript
|
||||
// ✅ 正确
|
||||
addLog("info", "服务启动成功");
|
||||
addLog("error", `操作失败: ${err.message}`);
|
||||
addLog("mcp", `REQ -> [${toolName}]`);
|
||||
addLog("success", `RES <- [${toolName}] 成功`);
|
||||
|
||||
// ❌ 错误
|
||||
console.log("服务启动成功"); // 不会被 read_console 捕获
|
||||
```
|
||||
|
||||
| type | 用途 | 颜色 |
|
||||
|------|------|------|
|
||||
| `info` | 一般信息 | 蓝色 |
|
||||
| `success` | 操作成功 | 绿色 |
|
||||
| `warn` | 警告信息 | 黄色 |
|
||||
| `error` | 错误信息 | 红色 |
|
||||
| `mcp` | MCP 请求/响应 | 紫色 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 撤销/重做支持 (Undo/Redo)
|
||||
|
||||
### 5.1 使用 scene:set-property
|
||||
|
||||
对于节点属性修改，优先使用 `scene:set-property` 以获得原生 Undo 支持：
|
||||
|
||||
```javascript
|
||||
// ✅ 支持 Undo
|
||||
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
|
||||
id: nodeId,
|
||||
path: "x",
|
||||
type: "Float",
|
||||
value: 100,
|
||||
isSubProp: false
|
||||
});
|
||||
|
||||
// ❌ 不支持 Undo (直接修改)
|
||||
node.x = 100;
|
||||
```
|
||||
|
||||
### 5.2 使用 Undo 组
|
||||
|
||||
对于复合操作，使用 Undo 组包装：
|
||||
|
||||
```javascript
|
||||
Editor.Ipc.sendToPanel("scene", "scene:undo-record", "Transform Update");
|
||||
try {
|
||||
// 执行多个属性修改
|
||||
Editor.Ipc.sendToPanel("scene", "scene:undo-commit");
|
||||
} catch (e) {
|
||||
Editor.Ipc.sendToPanel("scene", "scene:undo-cancel");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 功能特定规则 (Feature Specifics)
|
||||
|
||||
### 6.1 粒子系统 (VFX)
|
||||
|
||||
```javascript
|
||||
// 必须设置 custom = true，否则属性修改可能不生效
|
||||
particleSystem.custom = true;
|
||||
|
||||
// 确保纹理有效，否则粒子不可见
|
||||
if (!particleSystem.texture && !particleSystem.file) {
|
||||
// 加载默认纹理
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 资源路径解析
|
||||
|
||||
```javascript
|
||||
// 内置资源可能需要多个路径尝试
|
||||
const defaultPaths = [
|
||||
"db://internal/image/default_sprite_splash",
|
||||
"db://internal/image/default_sprite_splash.png",
|
||||
"db://internal/image/default_particle",
|
||||
"db://internal/image/default_particle.png"
|
||||
];
|
||||
|
||||
for (const path of defaultPaths) {
|
||||
const uuid = Editor.assetdb.urlToUuid(path);
|
||||
if (uuid) break;
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 场景操作时序
|
||||
|
||||
```javascript
|
||||
// 场景操作后需要延迟通知 UI 刷新
|
||||
newNode.parent = parent;
|
||||
Editor.Ipc.sendToMain("scene:dirty");
|
||||
|
||||
// 使用 setTimeout 让出主循环
|
||||
setTimeout(() => {
|
||||
Editor.Ipc.sendToAll("scene:node-created", {
|
||||
uuid: newNode.uuid,
|
||||
parentUuid: parent.uuid,
|
||||
});
|
||||
}, 10);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 错误处理规范 (Error Handling)
|
||||
|
||||
### 7.1 回调风格统一
|
||||
|
||||
```javascript
|
||||
// ✅ 标准风格
|
||||
callback(null, result); // 成功
|
||||
callback("Error message"); // 失败 (字符串)
|
||||
callback(new Error("message")); // 失败 (Error 对象)
|
||||
|
||||
// 避免混用
|
||||
callback(err, null); // 不推荐，保持一致性
|
||||
```
|
||||
|
||||
### 7.2 异步操作错误处理
|
||||
|
||||
```javascript
|
||||
Editor.assetdb.queryInfoByUrl(path, (err, info) => {
|
||||
if (err) {
|
||||
addLog("error", `查询资源失败: ${err.message}`);
|
||||
return callback(`Failed to get info: ${err.message}`);
|
||||
}
|
||||
// 继续处理...
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 提交规范 (Git Commit)
|
||||
|
||||
使用 [Conventional Commits](https://conventionalcommits.org/) 格式：
|
||||
|
||||
| 类型 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| `feat` | 新功能 | `feat: add manage_vfx tool` |
|
||||
| `fix` | 修复 bug | `fix: resolve duplicate function in main.js` |
|
||||
| `docs` | 文档更新 | `docs: add code review report` |
|
||||
| `refactor` | 重构 | `refactor: split main.js into modules` |
|
||||
| `test` | 测试 | `test: add material management tests` |
|
||||
| `chore` | 杂项 | `chore: update dependencies` |
|
||||
|
||||
---
|
||||
|
||||
## 9. 已知问题 (Known Issues)
|
||||
|
||||
| 问题 | 原因 | 解决方案 |
|
||||
|------|------|----------|
|
||||
| "Unknown object to record" 错误 | Cocos 2.4.x Undo 系统与 MCP 交互问题 | 可忽略，不影响功能 |
|
||||
| "sendToMain scene:stash-and-save failed" | 时序问题 | 手动 Ctrl+S 保存 |
|
||||
| 颜色修改不支持 Undo | 使用 scene-script 直接修改 | 待优化 |
|
||||
| execute_menu_item 仅支持部分菜单 | 缺乏通用菜单 IPC | 添加菜单映射表 |
|
||||
|
||||
Reference in New Issue
Block a user