补充 Cocos 内置编辑器能力说明

在 DirectProject 提示词中加入已核对的 Cocos 场景和资源操作示例

明确先查询真实 UUID 与状态再执行单项修改并回读

更新 Cocos 插件 README 的 Agent 能力与 JavaScript 用法

plugins/agc-cocos-editor/README.md

@@ -33,6 +33,24 @@ native/cocos-editor-bridge/      插件自带 native 模块（进程发现、pip
 `execute`、`inject`，与 native 适配器的 `COCOS_EDITOR_RPC_METHODS` 一一对应；
 `src/entry.test.mjs` 会校验两边不会漂移。
 
+## Agent 能力与 JavaScript 用法
+
+Agent 通过 `agc_cocos_execute` 注入 JavaScript 函数体；插件只负责把代码安全地送进
+已校验的 Creator 主进程，不在项目目录写入扩展。常用的 Creator 3.8.8 操作如下：
+
+| 目的 | 示例 |
+| --- | --- |
+| 读取场景树 | `return await Editor.Message.request('scene', 'query-node-tree');` |
+| 读取节点 | `return await Editor.Message.request('scene', 'query-node', uuid);` |
+| 修改属性 | `return await Editor.Message.request('scene', 'set-property', { uuid, path, value });` |
+| 添加组件 | `return await Editor.Message.request('scene', 'create-component', { uuid, component });` |
+| 执行场景脚本 | `return await Editor.Message.request('scene', 'execute-scene-script', { name, method, args });` |
+| 查询资源 | `return await Editor.Message.request('asset-db', 'query-asset-info', uuid);` |
+
+先执行只读查询取得真实节点 UUID、组件标识和属性路径，再执行单个修改并回读校验。
+不要猜 UUID、组件 CID 或属性路径；需要保存、删除或批量修改时，先确认对应 Creator
+消息协议，再通过同一入口逐步执行。
+
 execute 不接受并发积压。结果不确定时返回 `needs-reconciliation` 与
 `retryAllowed: false` 并阻止后续发送；native 适配器的阻断不会被 disconnect
 或插件进程重载清除。请先核对编辑器状态，再重启客户端恢复。