docs(mcp): CLAUDE.md 与 cocos-mcp 技能只保留 MCP 自身给不了的信息
原文档写着"164 个工具"并复述了一份按前缀分的工具清单, 对应的是已删除的旧扩展, 照着写会调不到工具。 改为不再复述工具用法: cocos-mcp-server 连上后会自注入 5.5K 字符的完整说明 (CRITICAL RULES + intent→tool 速查表 + 批量操作), 16 个工具的 description 也 各带 action 枚举与示例, 仓库里再维护一份副本必然随扩展版本腐化。 文档只保留 MCP 给不了的部分——服务离线时它的自带说明也一并消失, 而那正是最需要 "去编辑器点 Start Server"和"不要转而手改序列化文件"的时刻: - 前置条件、curl /health 探活、连不上时的排查顺序 - settings/mcp-server.json 的 autoStart:false, ECONNREFUSED 的常见成因 - 已知坑: cocos_asset.search 的 type 过滤失效; cocos_scene.hierarchy 的 includeComponents 失效; 编辑器里的 scene-2d 是 Creator 内置模板而非工程资产 (assets/ 下 0 个 .scene), 不必去仓库里找 技能里原本重复的"禁止手改 .scene/.prefab"规则改为引用 CLAUDE.md 单一来源, 依据 是仓库第二准则; 基线测试也表明未读该技能的 agent 仅凭 CLAUDE.md 即拒绝手改。 CLAUDE.md 里"动手前先读技能"改为条件式(正常操作不必读, 故障时才读), 此前该指令 与技能的排障定位冲突, 实测中不同 agent 对它的解读并不一致。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -78,14 +78,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Cocos Creator 新前端:优先使用 cocos-creator-mcp
|
||||
|
||||
新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**(场景、节点、组件、prefab、资源、预览/截图/录制等),都应**优先使用 `cocos-creator-mcp` 这组 MCP 工具**(命名空间 `mcp__cocos-creator-mcp__*`,共 164 个)直接驱动编辑器,而不是手改 `.scene` / `.prefab` / `.meta` 等序列化文件——手改极易破坏 UUID 引用与序列化结构。
|
||||
新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**(场景、节点、组件、prefab、资源、动画、预览/截图等),都必须走 `mcp__cocos-creator-mcp__cocos_*` 这组 MCP 工具驱动编辑器。
|
||||
|
||||
**前置条件(缺一不可,否则工具调用必然失败):**
|
||||
1. Cocos Creator 3.8+ 已打开 `YouleNexus` 工程;
|
||||
2. 扩展 `cocos-creator-mcp` 已启用,并在其面板里点了 **Start Server**(监听 `http://127.0.0.1:3000/mcp`)。
|
||||
**绝不允许手改** `.scene` / `.prefab` / `.anim` / `.meta`——它们是 UUID 引用的序列化资源,任何文本编辑都会破坏引用结构,导致「资源导入失败」且只能人工恢复。**MCP 连不上时也不例外**:应提示用户去编辑器启动服务,而不是退而求其次去手改文件。
|
||||
|
||||
**开工前先探活**:先调用 `mcp__cocos-creator-mcp__server_get_status`(或 `curl http://127.0.0.1:3000/health`,期望 `{"status":"ok","tools":164}`)。**连不上时,提示用户在编辑器里启动服务,不要盲目重试**——MCP 桥(`extensions/cocos-creator-mcp/client/stdio-bridge.js`)只转发,无法替你启动编辑器服务。
|
||||
具体工具用法不写在这里——MCP server 连上后会自注入完整说明(工具清单、action 速查、批量操作),以其为准,**正常操作不需要先读任何仓库文档**。
|
||||
|
||||
**工具分类(按前缀):** `scene_*`(场景生命周期/层级/查询/撤销)、`node_*`(增删改/变换/树)、`component_*`、`prefab_*`、`asset_*`、`project_*`、`builder_*`(预览/构建)、`debug_*`(截图、录制、game command、控制台日志)、`view_*`(gizmo/相机/网格)、`refimage_*`、`preferences_*`、`server_*`。
|
||||
|
||||
> MCP 的项目级安装方式与排障细节(扩展位置、`package.json` name 必须为 `cocos-creator-mcp`、镜像 404 等坑)记录在项目记忆 `cocos-creator-mcp-setup`。
|
||||
`cocos-mcp` 技能(`.claude/skills/cocos-mcp/SKILL.md`)只记录 MCP 自己给不了的部分:前置条件、探活、排障、已知坑。**工具正常时不必读它;一旦 `cocos_*` 工具没出现、调用报连接失败、或行为与预期不符,就去读。**
|
||||
|
||||
Reference in New Issue
Block a user