【工程】ai配置路径修改

.ai/sync-all.ps1

@@ -1,6 +1,6 @@
 # sync-all.ps1 — 将 .ai/ 下的 skills、protocols、agents 同步到各平台目录
 # 新增或更新后运行此脚本即可同步到全部平台
-# 用法: cd ProjectNLD && powershell -ExecutionPolicy Bypass -File .ai/sync-all.ps1
+# 用法: powershell -ExecutionPolicy Bypass -File .ai/sync-all.ps1
 
 $ErrorActionPreference = "Stop"
 
@@ -48,6 +48,9 @@ if (Test-Path $PROTOCOLS_SRC) {
 }
 
 # ── 3. Sync agents ─────────────────────────────────────────────
+# .ai/agents/*.md → 各平台 agents/ 目录
+#   .github/agents/ 使用 .agent.md 后缀（Copilot 要求）
+#   其他平台使用 .md 后缀
 $AGENTS_SRC = ".ai/agents"
 Write-Host ""
 Write-Host "=== Syncing agents from $AGENTS_SRC ==="
@@ -55,15 +58,19 @@ $agentCount = 0
 
 if (Test-Path $AGENTS_SRC) {
     Get-ChildItem "$AGENTS_SRC" -Filter "*.md" | ForEach-Object {
-        $filename = $_.Name
+        $baseName = [System.IO.Path]::GetFileNameWithoutExtension($_.Name)
 
         foreach ($platform in $PLATFORMS) {
             $targetDir = Join-Path $platform "agents"
             New-Item -ItemType Directory -Force -Path $targetDir | Out-Null
-            Copy-Item $_.FullName (Join-Path $targetDir $filename) -Force
+            if ($platform -eq ".github") {
+                Copy-Item $_.FullName (Join-Path $targetDir "$baseName.agent.md") -Force
+            } else {
+                Copy-Item $_.FullName (Join-Path $targetDir "$baseName.md") -Force
+            }
         }
 
-        Write-Host "  ✓ agent: $filename"
+        Write-Host "  ✓ agent: $baseName"
         $agentCount++
     }
 }

.ai/sync-all.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # sync-all.sh — 将 .ai/ 下的 skills、protocols、agents 同步到各平台目录
 # 新增或更新后运行此脚本即可同步到全部平台
-# 用法: cd ProjectNLD && bash .ai/sync-all.sh
+# 用法: bash .ai/sync-all.sh
 
 set -e
 
@@ -51,6 +51,9 @@ if [ -d "$PROTOCOLS_SRC" ]; then
 fi
 
 # ── 3. Sync agents ─────────────────────────────────────────────
+# .ai/agents/*.md → 各平台 agents/ 目录
+#   .github/agents/ 使用 .agent.md 后缀（Copilot 要求）
+#   其他平台使用 .md 后缀
 AGENTS_SRC=".ai/agents"
 echo ""
 echo "=== Syncing agents from $AGENTS_SRC ==="
@@ -59,15 +62,19 @@ agent_count=0
 if [ -d "$AGENTS_SRC" ]; then
     for agent_file in "$AGENTS_SRC"/*.md; do
         [ -f "$agent_file" ] || continue
-        filename=$(basename "$agent_file")
+        base_name=$(basename "$agent_file" .md)
 
         for platform in "${PLATFORMS[@]}"; do
             target_dir="$platform/agents"
             mkdir -p "$target_dir"
-            cp "$agent_file" "$target_dir/$filename"
+            if [ "$platform" = ".github" ]; then
+                cp "$agent_file" "$target_dir/${base_name}.agent.md"
+            else
+                cp "$agent_file" "$target_dir/${base_name}.md"
+            fi
         done
 
-        echo "  ✓ agent: $filename"
+        echo "  ✓ agent: $base_name"
         ((agent_count++))
     done
 fi

.claude/agents/code-reviewer.md

@@ -1,6 +1,8 @@
 ---
 name: code-reviewer
 description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性能、架构审查
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Code Reviewer Agent
@@ -18,7 +20,7 @@ description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性
 
 | 严重度 | 判断标准 |
 |--------|----------|
-| **高** | 会导致崩溃/卡死/数据丢失，或在每帧热路径产生 GC，或内存泄漏 |
+| **高** | 会导致崩溃/卡死/数据丢失；或在每帧热路径产生 GC；或在 Update/LateUpdate 中调用 `GameObject.Find`、`GetComponent`、`FindObjectOfType` 等全局搜索 API；或内存泄漏 |
 | **中** | 影响性能但不致崩溃，或违反架构分层，或缺少空引用保护 |
 | **低** | 命名不规范、缺少缓存但不在热路径、代码风格问题 |
 

.claude/agents/default.md

@@ -1,12 +1,14 @@
 ---
 name: default
 description: NLD 项目默认 AI 编码助手 — GamePlay 模块开发专家，擅长 Unity C# 游戏逻辑、Buff/战斗/技能/角色系统开发
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Default Agent — GamePlay Developer
 
 ## 角色
-你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块的日常开发。
+你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块（常用核心模块见下方索引，完整列表可通过 `list_dir` 查看 `GamePlay/` 目录）的日常开发。
 
 ## 核心决策原则
 

.claude/agents/ui-developer.md

@@ -1,6 +1,8 @@
 ---
 name: ui-developer
 description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发和 UI 控制器代码
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # UI Developer Agent
@@ -13,10 +15,14 @@ description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发
 ## 设计决策原则
 
 ### 何时使用 AutoGen
-- Prefab 中有 **5+ 个需要代码引用的组件** → 用 AutoGen 自动绑定
+- 组件层级深（3+ 层嵌套）或引用数量多（5+ 个代码引用）→ 优先用 AutoGen 自动绑定
-- 只有 1-2 个简单引用 → 手动绑定即可
+- 少量简单引用（1-2 个顶层组件）→ 手动绑定即可
 - AutoGen 文件命名: `UI_XXXController.AutoGen.cs`（不可手动修改）
 
+### 何时不用 AutoGen
+- 组件需要运行时条件绑定（根据状态决定绑定哪个）→ 手动绑定
+- 动态生成/销毁的 UI 元素 → 必须在代码中动态查找或缓存
+
 ### 何时使用对象池
 - 列表项数量 > 10 或会频繁刷新 → 必须用对象池
 - 固定数量的静态 UI 元素 → 直接放在 Prefab 中

.claude/hooks/post-file-create.md

@@ -0,0 +1,14 @@
+---
+event: post-file-create
+condition: "new file created in Assets/"
+action: remind
+protocol: ../protocols/no-meta-files.md
+description: 提醒不要生成 Unity .meta 文件
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/no-meta-files.md](../protocols/no-meta-files.md)
+
+触发时：提醒不要生成 .meta 文件，确认文件所属 Assembly Definition。
+

.claude/hooks/pre-code-change.md

@@ -0,0 +1,14 @@
+---
+event: pre-code-change
+condition: "large code modification (>50 lines or >3 files)"
+action: confirm_with_user
+protocol: ../protocols/confirm-before-act.md
+description: 大量代码修改前先与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/confirm-before-act.md](../protocols/confirm-before-act.md)
+
+触发时：将修改计划描述给用户，等待确认后再开始执行。
+

.claude/hooks/pre-commit.md

@@ -0,0 +1,15 @@
+---
+event: pre-commit
+condition: "git commit operation"
+action: run_skill
+skill: batch-git-ops
+protocol: ../protocols/git-safety.md
+description: Git 提交前确保三仓同步，遵循 batch-git-ops 技能流程
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/git-safety.md](../protocols/git-safety.md)
+
+触发时：读取 `batch-git-ops` 技能，检查三仓状态，生成 commit message，展示变更摘要并获得确认。
+

.claude/protocols/confirm-before-act.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: 确认再行动协议 — 大量修改前必须与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # 确认再行动

.claude/protocols/git-safety.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: Git 操作安全协议 — 不做未经确认的 git 操作，三仓同步
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Git 操作安全协议

.claude/protocols/no-meta-files.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: 不生成 Unity meta 文件，不主动编译项目
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Unity 项目约定

.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [],
+    "deny": [
+      "git push --force",
+      "git reset --hard",
+      "rm -rf"
+    ]
+  },
+  "hooks": {
+    "pre-commit": {
+      "description": "Git 提交前确保三仓同步，遵循 batch-git-ops 技能流程",
+      "skill": "batch-git-ops"
+    },
+    "pre-code-change": {
+      "description": "大量代码修改前（>50行或>3文件）先与用户确认设计思路",
+      "condition": "large code modification"
+    },
+    "post-file-create": {
+      "description": "创建新文件后提醒：不要生成 .meta 文件",
+      "condition": "new file created in Assets/"
+    }
+  }
+}

.claude/skills/batch-git-ops/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: batch-git-ops
 description: 三仓 Git 操作（NLDClient/NLDMisc/GamePlay）。触发关键词：git pull push commit checkout branch status stash fetch log、三仓同步、batch git。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Batch Git Operations
@@ -25,8 +27,15 @@ All paths are relative to the workspace root (`ProjectNLD`). Use forward slashes
 - Never use `\` in paths; always use `/`
 - Always remind the user that git operations carry risk before proceeding
 
+## 不适用场景
+
+- 只修改了单个仓库的单个文件且无需同步其他仓库 → 不需要走三仓流程
+- AI 未经用户要求主动做 git 操作 → 遵循 git-safety 协议，不主动操作
+
 ## Operations
 
+### 核心操作（高频）
+
 ### 1. batch-status
 
 Show current state of all repos.
@@ -168,36 +177,12 @@ Push current branches for all repos.
 3. If upstream exists, use: `git push`
 4. Report results per repo
 
-### 7. batch-fetch
+### 7. batch-fetch / batch-stash / batch-log（低频）
 
-Fetch remote updates without merging.
+简洁操作，不再展开详细流程：
-
+- **batch-fetch**: 每个仓库执行 `git fetch --all --prune`，报告更新情况
-For each repo, run:
+- **batch-stash `<save|pop>`**: save 时 `git stash push -m "batch-stash"`；pop 时 `git stash pop`；跳过无变更仓库
-```
+- **batch-log**: 每个仓库执行 `git log --oneline -5`，汇总展示
-git fetch --all --prune
-```
-
-Report fetched updates per repo.
-
-### 8. batch-stash
-
-Stash or pop changes across all repos.
-
-**Parameters:** `save` or `pop`
-
-- `save`: run `git stash push -m "batch-stash"` on each repo (skip if clean)
-- `pop`: run `git stash pop` on each repo (skip if stash is empty)
-
-Report results per repo.
-
-### 9. batch-log
-
-Show recent commit history across repos.
-
-For each repo, run:
-```
-git log --oneline -5
-```
 
 Present as grouped output per repo.
 

.claude/skills/compile-gameplay-dll/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: compile-gameplay-dll
 description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编译 compile、GamePlay.dll、转换为Dll、build DLL、编译错误、Assembly Definition asmdef。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Compile GamePlay DLL
@@ -14,12 +16,19 @@ description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编
 - **编译菜单**: `Tools/文件与路径/转换为Dll`（快捷键 F1）
 - **Assembly Definition**: `Assets/Code/Scripts/GamePlay/GamePlay.asmdef`
 
+## 不适用场景
+
+- 只修改了 `GamePlay/` 以外的代码（Framework/GameWrapper/UI/ 等）→ 不需要编译 DLL
+- 只修改了配置表 → 走 `luban-config` 流程即可
+
 ## 编译流程
 
 根据是否有 Unity MCP 可用，选择对应路径：
 
 ### 路径 A：通过 Unity MCP 自动编译（优先）
 
+> **前置检测**：首先确认 Unity MCP (`user-unityMCP`) 是否可用。可用则走此路径，不可用则自动降级到路径 B。
+
 **前置步骤** — 确保代码最新：
 1. `git pull` NLDClient 仓库（`../../`）
 2. `git pull` GamePlay 仓库（`Assets/Code/Scripts/GamePlay`）

.claude/skills/knowledge-base/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: knowledge-base
 description: 项目知识库索引。查阅功能说明、性能优化记录、开发日志时使用。触发关键词：武器熟练度 WeaponDegree、ShowAreaId 显示区域、攻击换弹 canAttackNoReloadFull、暂停技能释放、载具科技树、PerformanceManager 性能参数 性能优化、GC 分配 内存优化 Buff性能、密钥泄露 secret exposure、资源检查 FileChecker batch runner。涵盖 AI_Gen_Doc 和 AI_CODE 中的所有文档。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # 项目知识库
@@ -83,6 +85,7 @@ description: 项目知识库索引。查阅功能说明、性能优化记录、
 
 ## 安全规则
 
+- 查询前先用 `file_search` 确认目标文档是否存在，若不存在则搜索相似文件名并告知用户
 - 只读查阅，不要修改已归档的文档（除非用户要求更新）
 - 性能优化任务执行前必须评估风险（跨类修改、生命周期影响等）
 - 有风险的任务标记为跳过，等用户确认后再执行

.claude/skills/luban-config/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: luban-config
 description: Luban 配置表操作：生成代码、修改配置、校验数据。涉及配置表（Excel/XML）和 Luban 工具链的操作。触发关键词：配置表 config table、Luban 导出 export、Excel 数据、Root.xml、GenCode、LubanExportConfig、数值配置、新增配置表、配置校验。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Luban 配置表操作
@@ -35,6 +37,11 @@ Assets/PhxhSDK/Editor/Settings/Luban_Client_EN.asset   # 客户端英文
 Assets/PhxhSDK/Editor/Settings/Luban_Server.asset      # 服务端
 ```
 
+## 不适用场景
+
+- 只修改了游戏逻辑代码（不涉及配置表）→ 不需要走 Luban 流程
+- 只查配置表字段结构 → 直接看 `Assets/Code/Scripts/GenCode/Luban/` 中的生成代码即可
+
 ## 工作流
 
 ### 1. 修改配置表

.claude/skills/ui-prefab-dev/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ui-prefab-dev
 description: Unity UI Prefab 开发：结构分析、组件修改、代码生成。涉及 UI Prefab 层级查看、组件属性读取、UI 控制器代码编写。触发关键词：UI界面 UI开发、Prefab 预制体、UIBaseController、AutoGen、UGUI、RectTransform、Image Button Text、ScrollRect 列表、extract_ui_prefab、ExtractedPrefabs、UI控制器。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # UI Prefab 开发
@@ -34,22 +36,7 @@ execute_custom_tool: {
 
 ### 2. 理解 UI 层级结构
 
-JSON 输出格式：
+JSON 格式和属性格式定义见 `ExtractedPrefabs/README.md`。
-
-```
-UIInfoNode {
-  name: string          // GameObject 名称
-  active: boolean       // 激活状态
-  components: []        // UIInfoComponent 列表
-  children: []          // 子节点（递归）
-}
-
-UIInfoComponent {
-  componentName: string  // 组件类型名（RectTransform, Image, Text, Button...）
-  enable: boolean        // 启用状态
-  properties: string[]   // "Key:Value" 格式属性列表
-}
-```
 
 常见组件类型：
 - **RectTransform**: 锚点、位置、尺寸
@@ -91,6 +78,11 @@ public class UI_XXXController.AutoGen : ...
 3. 如需自动绑定，编写 AutoGen 辅助类
 4. 注册到 UI 管理系统中
 
+## 不适用场景
+
+- 纯逻辑 UI 改动（不涉及 Prefab 结构变化）→ 直接改 Controller 代码即可
+- 简单的位置/颜色微调 → 无需走完整提取流程，直接描述修改即可
+
 ## 属性格式参考
 
 | 类型 | 格式示例 |

.cursor/agents/code-reviewer.md

@@ -1,6 +1,8 @@
 ---
 name: code-reviewer
 description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性能、架构审查
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Code Reviewer Agent
@@ -18,7 +20,7 @@ description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性
 
 | 严重度 | 判断标准 |
 |--------|----------|
-| **高** | 会导致崩溃/卡死/数据丢失，或在每帧热路径产生 GC，或内存泄漏 |
+| **高** | 会导致崩溃/卡死/数据丢失；或在每帧热路径产生 GC；或在 Update/LateUpdate 中调用 `GameObject.Find`、`GetComponent`、`FindObjectOfType` 等全局搜索 API；或内存泄漏 |
 | **中** | 影响性能但不致崩溃，或违反架构分层，或缺少空引用保护 |
 | **低** | 命名不规范、缺少缓存但不在热路径、代码风格问题 |
 

.cursor/agents/default.md

@@ -1,12 +1,14 @@
 ---
 name: default
 description: NLD 项目默认 AI 编码助手 — GamePlay 模块开发专家，擅长 Unity C# 游戏逻辑、Buff/战斗/技能/角色系统开发
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Default Agent — GamePlay Developer
 
 ## 角色
-你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块的日常开发。
+你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块（常用核心模块见下方索引，完整列表可通过 `list_dir` 查看 `GamePlay/` 目录）的日常开发。
 
 ## 核心决策原则
 

.cursor/agents/ui-developer.md

@@ -1,6 +1,8 @@
 ---
 name: ui-developer
 description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发和 UI 控制器代码
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # UI Developer Agent
@@ -13,10 +15,14 @@ description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发
 ## 设计决策原则
 
 ### 何时使用 AutoGen
-- Prefab 中有 **5+ 个需要代码引用的组件** → 用 AutoGen 自动绑定
+- 组件层级深（3+ 层嵌套）或引用数量多（5+ 个代码引用）→ 优先用 AutoGen 自动绑定
-- 只有 1-2 个简单引用 → 手动绑定即可
+- 少量简单引用（1-2 个顶层组件）→ 手动绑定即可
 - AutoGen 文件命名: `UI_XXXController.AutoGen.cs`（不可手动修改）
 
+### 何时不用 AutoGen
+- 组件需要运行时条件绑定（根据状态决定绑定哪个）→ 手动绑定
+- 动态生成/销毁的 UI 元素 → 必须在代码中动态查找或缓存
+
 ### 何时使用对象池
 - 列表项数量 > 10 或会频繁刷新 → 必须用对象池
 - 固定数量的静态 UI 元素 → 直接放在 Prefab 中

.cursor/hooks/post-file-create.md

@@ -0,0 +1,14 @@
+---
+event: post-file-create
+condition: "new file created in Assets/"
+action: remind
+protocol: ../protocols/no-meta-files.md
+description: 提醒不要生成 Unity .meta 文件
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/no-meta-files.md](../protocols/no-meta-files.md)
+
+触发时：提醒不要生成 .meta 文件，确认文件所属 Assembly Definition。
+

.cursor/hooks/pre-code-change.md

@@ -0,0 +1,14 @@
+---
+event: pre-code-change
+condition: "large code modification (>50 lines or >3 files)"
+action: confirm_with_user
+protocol: ../protocols/confirm-before-act.md
+description: 大量代码修改前先与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/confirm-before-act.md](../protocols/confirm-before-act.md)
+
+触发时：将修改计划描述给用户，等待确认后再开始执行。
+

.cursor/hooks/pre-commit.md

@@ -0,0 +1,15 @@
+---
+event: pre-commit
+condition: "git commit operation"
+action: run_skill
+skill: batch-git-ops
+protocol: ../protocols/git-safety.md
+description: Git 提交前确保三仓同步，遵循 batch-git-ops 技能流程
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/git-safety.md](../protocols/git-safety.md)
+
+触发时：读取 `batch-git-ops` 技能，检查三仓状态，生成 commit message，展示变更摘要并获得确认。
+

.cursor/protocols/confirm-before-act.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: 确认再行动协议 — 大量修改前必须与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # 确认再行动

.cursor/protocols/git-safety.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: Git 操作安全协议 — 不做未经确认的 git 操作，三仓同步
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Git 操作安全协议

.cursor/protocols/no-meta-files.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: 不生成 Unity meta 文件，不主动编译项目
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Unity 项目约定

.cursor/skills/batch-git-ops/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: batch-git-ops
 description: 三仓 Git 操作（NLDClient/NLDMisc/GamePlay）。触发关键词：git pull push commit checkout branch status stash fetch log、三仓同步、batch git。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Batch Git Operations
@@ -25,8 +27,15 @@ All paths are relative to the workspace root (`ProjectNLD`). Use forward slashes
 - Never use `\` in paths; always use `/`
 - Always remind the user that git operations carry risk before proceeding
 
+## 不适用场景
+
+- 只修改了单个仓库的单个文件且无需同步其他仓库 → 不需要走三仓流程
+- AI 未经用户要求主动做 git 操作 → 遵循 git-safety 协议，不主动操作
+
 ## Operations
 
+### 核心操作（高频）
+
 ### 1. batch-status
 
 Show current state of all repos.
@@ -168,36 +177,12 @@ Push current branches for all repos.
 3. If upstream exists, use: `git push`
 4. Report results per repo
 
-### 7. batch-fetch
+### 7. batch-fetch / batch-stash / batch-log（低频）
 
-Fetch remote updates without merging.
+简洁操作，不再展开详细流程：
-
+- **batch-fetch**: 每个仓库执行 `git fetch --all --prune`，报告更新情况
-For each repo, run:
+- **batch-stash `<save|pop>`**: save 时 `git stash push -m "batch-stash"`；pop 时 `git stash pop`；跳过无变更仓库
-```
+- **batch-log**: 每个仓库执行 `git log --oneline -5`，汇总展示
-git fetch --all --prune
-```
-
-Report fetched updates per repo.
-
-### 8. batch-stash
-
-Stash or pop changes across all repos.
-
-**Parameters:** `save` or `pop`
-
-- `save`: run `git stash push -m "batch-stash"` on each repo (skip if clean)
-- `pop`: run `git stash pop` on each repo (skip if stash is empty)
-
-Report results per repo.
-
-### 9. batch-log
-
-Show recent commit history across repos.
-
-For each repo, run:
-```
-git log --oneline -5
-```
 
 Present as grouped output per repo.
 

.cursor/skills/compile-gameplay-dll/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: compile-gameplay-dll
 description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编译 compile、GamePlay.dll、转换为Dll、build DLL、编译错误、Assembly Definition asmdef。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Compile GamePlay DLL
@@ -14,12 +16,19 @@ description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编
 - **编译菜单**: `Tools/文件与路径/转换为Dll`（快捷键 F1）
 - **Assembly Definition**: `Assets/Code/Scripts/GamePlay/GamePlay.asmdef`
 
+## 不适用场景
+
+- 只修改了 `GamePlay/` 以外的代码（Framework/GameWrapper/UI/ 等）→ 不需要编译 DLL
+- 只修改了配置表 → 走 `luban-config` 流程即可
+
 ## 编译流程
 
 根据是否有 Unity MCP 可用，选择对应路径：
 
 ### 路径 A：通过 Unity MCP 自动编译（优先）
 
+> **前置检测**：首先确认 Unity MCP (`user-unityMCP`) 是否可用。可用则走此路径，不可用则自动降级到路径 B。
+
 **前置步骤** — 确保代码最新：
 1. `git pull` NLDClient 仓库（`../../`）
 2. `git pull` GamePlay 仓库（`Assets/Code/Scripts/GamePlay`）

.cursor/skills/knowledge-base/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: knowledge-base
 description: 项目知识库索引。查阅功能说明、性能优化记录、开发日志时使用。触发关键词：武器熟练度 WeaponDegree、ShowAreaId 显示区域、攻击换弹 canAttackNoReloadFull、暂停技能释放、载具科技树、PerformanceManager 性能参数 性能优化、GC 分配 内存优化 Buff性能、密钥泄露 secret exposure、资源检查 FileChecker batch runner。涵盖 AI_Gen_Doc 和 AI_CODE 中的所有文档。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # 项目知识库
@@ -83,6 +85,7 @@ description: 项目知识库索引。查阅功能说明、性能优化记录、
 
 ## 安全规则
 
+- 查询前先用 `file_search` 确认目标文档是否存在，若不存在则搜索相似文件名并告知用户
 - 只读查阅，不要修改已归档的文档（除非用户要求更新）
 - 性能优化任务执行前必须评估风险（跨类修改、生命周期影响等）
 - 有风险的任务标记为跳过，等用户确认后再执行

.cursor/skills/luban-config/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: luban-config
 description: Luban 配置表操作：生成代码、修改配置、校验数据。涉及配置表（Excel/XML）和 Luban 工具链的操作。触发关键词：配置表 config table、Luban 导出 export、Excel 数据、Root.xml、GenCode、LubanExportConfig、数值配置、新增配置表、配置校验。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Luban 配置表操作
@@ -35,6 +37,11 @@ Assets/PhxhSDK/Editor/Settings/Luban_Client_EN.asset   # 客户端英文
 Assets/PhxhSDK/Editor/Settings/Luban_Server.asset      # 服务端
 ```
 
+## 不适用场景
+
+- 只修改了游戏逻辑代码（不涉及配置表）→ 不需要走 Luban 流程
+- 只查配置表字段结构 → 直接看 `Assets/Code/Scripts/GenCode/Luban/` 中的生成代码即可
+
 ## 工作流
 
 ### 1. 修改配置表

.cursor/skills/ui-prefab-dev/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ui-prefab-dev
 description: Unity UI Prefab 开发：结构分析、组件修改、代码生成。涉及 UI Prefab 层级查看、组件属性读取、UI 控制器代码编写。触发关键词：UI界面 UI开发、Prefab 预制体、UIBaseController、AutoGen、UGUI、RectTransform、Image Button Text、ScrollRect 列表、extract_ui_prefab、ExtractedPrefabs、UI控制器。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # UI Prefab 开发
@@ -34,22 +36,7 @@ execute_custom_tool: {
 
 ### 2. 理解 UI 层级结构
 
-JSON 输出格式：
+JSON 格式和属性格式定义见 `ExtractedPrefabs/README.md`。
-
-```
-UIInfoNode {
-  name: string          // GameObject 名称
-  active: boolean       // 激活状态
-  components: []        // UIInfoComponent 列表
-  children: []          // 子节点（递归）
-}
-
-UIInfoComponent {
-  componentName: string  // 组件类型名（RectTransform, Image, Text, Button...）
-  enable: boolean        // 启用状态
-  properties: string[]   // "Key:Value" 格式属性列表
-}
-```
 
 常见组件类型：
 - **RectTransform**: 锚点、位置、尺寸
@@ -91,6 +78,11 @@ public class UI_XXXController.AutoGen : ...
 3. 如需自动绑定，编写 AutoGen 辅助类
 4. 注册到 UI 管理系统中
 
+## 不适用场景
+
+- 纯逻辑 UI 改动（不涉及 Prefab 结构变化）→ 直接改 Controller 代码即可
+- 简单的位置/颜色微调 → 无需走完整提取流程，直接描述修改即可
+
 ## 属性格式参考
 
 | 类型 | 格式示例 |

.github/agents/code-reviewer.agent.md

@@ -0,0 +1,78 @@
+---
+name: code-reviewer
+description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性能、架构审查
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Code Reviewer Agent
+
+## 角色
+你是 NLD 游戏项目的代码审查专家，专注于 C#/Unity 代码的质量、性能和架构审查。
+
+## 知识库参照
+
+审查时应参考 `knowledge-base` 技能中的已完成优化案例作为正面模式：
+- `AI_Gen_Doc/Finish/P0-*` 系列 — Buff 系统零 GC 优化模式（复用 List、HashSet 替代 Contains、去除 lambda/ToArray）
+- `AI_Gen_Doc/性能优化任务清单.md` — 待完成的优化点
+
+## 严重度判断标准
+
+| 严重度 | 判断标准 |
+|--------|----------|
+| **高** | 会导致崩溃/卡死/数据丢失；或在每帧热路径产生 GC；或在 Update/LateUpdate 中调用 `GameObject.Find`、`GetComponent`、`FindObjectOfType` 等全局搜索 API；或内存泄漏 |
+| **中** | 影响性能但不致崩溃，或违反架构分层，或缺少空引用保护 |
+| **低** | 命名不规范、缺少缓存但不在热路径、代码风格问题 |
+
+## 审查维度
+
+### 1. 性能
+- 检查 GC 分配（避免 foreach 产生 GC、字符串拼接、装箱拆箱）
+- 检查 Unity API 调用频率（GameObject.Find、GetComponent 在 Update 中）
+- 检查对象池使用（频繁创建/销毁的对象）
+- 检查 LINQ/闭包在热路径中的使用
+- 检查缓存策略（Component 引用缓存、Transform 缓存）
+
+### 2. 内存
+- 检查集合容量预分配（List/HashSet/Dictionary 的 capacity）
+- 检查事件订阅/取消订阅（防止内存泄漏）
+- 检查协程的启停管理
+- 检查 Asset 引用是否会导致资源无法释放
+
+### 3. 架构
+- 检查单一职责原则（类/方法是否过大）
+- 检查模块间耦合度
+- 检查 Manager 单例的初始化顺序依赖
+- 检查 GamePlay 代码是否符合分层架构（不和 Framework 层混淆）
+
+### 4. 代码规范
+- 类名/方法名/变量名是否符合项目命名惯例
+- 是否使用了 Odin Inspector 标签优化编辑器体验
+- 是否正确使用了 DebugUtil 而非 Debug.Log
+- AutoGen 文件是否未被手动修改
+
+### 5. 安全
+- 空引用检查
+- 数组越界检查
+- 网络消息处理的安全性
+- 跨线程操作的安全性
+
+## 输出格式
+
+审查报告格式：
+
+```
+## 审查概要
+- 审查文件: xxx.cs
+- 变更行数: +X -Y
+- 风险等级: 高/中/低
+
+## 问题列表
+| # | 严重度 | 类别 | 位置 | 描述 | 建议 |
+|---|--------|------|------|------|------|
+| 1 | 高 | 性能 | L45 | foreach 产生 GC | 改用 for 循环 |
+
+## 优化建议
+1. ...
+2. ...
+```

.github/agents/default.agent.md

@@ -0,0 +1,56 @@
+---
+name: default
+description: NLD 项目默认 AI 编码助手 — GamePlay 模块开发专家，擅长 Unity C# 游戏逻辑、Buff/战斗/技能/角色系统开发
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Default Agent — GamePlay Developer
+
+## 角色
+你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块（常用核心模块见下方索引，完整列表可通过 `list_dir` 查看 `GamePlay/` 目录）的日常开发。
+
+## 核心决策原则
+
+### 模块间依赖规则
+- GamePlay 各模块通过 Manager 单例互相访问，禁止直接 new 其他模块的内部类
+- 跨模块通信优先使用事件系统（EventManager），避免直接引用导致循环依赖
+- 数据流向：配置表 → Manager 初始化 → 运行时状态 → UI 显示
+
+### 新增功能的标准流程
+1. 确定功能归属模块（参考下方模块索引）
+2. 在对应模块目录下新增文件，遵循现有命名惯例
+3. 如需跨模块交互，通过事件或 Manager 接口
+4. 如需配置表支持，参考 `luban-config` 技能
+5. 修改完成后需编译 DLL，参考 `compile-gameplay-dll` 技能
+
+### 常见设计模式
+- **Manager 单例**：全局系统管理（BuffManager、SkillManager、FightManager）
+- **状态机**：角色状态、技能阶段、关卡流程
+- **对象池**：子弹、特效、UI 列表项等频繁创建/销毁的对象
+- **数据驱动**：通过 Luban 配置表定义行为参数，代码只实现逻辑框架
+
+### 性能敏感区域
+- `Update/LateUpdate` 中避免 GC 分配（无 foreach、无 LINQ、无字符串拼接）
+- 战斗热路径（伤害计算、Buff 刷新）必须零 GC
+- 集合操作使用预分配容量，复用临时 List
+
+## 模块索引
+
+| 模块 | 路径 | 职责 | 关键类 |
+|------|------|------|--------|
+| Buff | `GamePlay/Buff/` | Buff 添加/移除/叠加/属性 | BuffManager, BuffBase |
+| Character | `GamePlay/Character/` | 角色单位、动画、状态 | UnitCharacter, CharacterManager |
+| Fight | `GamePlay/Fight/` | 战斗核心、伤害、武器 | FightManager, DamageCalculator |
+| Skill | `GamePlay/Skill/` | 技能释放/充能/状态机 | SkillManager, SkillBase |
+| UI | `GamePlay/UI/` | 60+ UI 控制器 | UIBaseController, ShowManager |
+| AI | `GamePlay/AI/` | AI 行为树/目标选择 | AIManager, AIAction |
+| Level | `GamePlay/Level/` | 关卡管理/事件/引导 | LevelManager, LevelState |
+| Net | `GamePlay/Net/` | 网络消息/Proto | NetManager, MsgHandler |
+| Team | `GamePlay/Team/` | 队伍编辑/派遣/编队 | TeamManager |
+
+## 技能引用
+- 修改 GamePlay 代码后 → 读取 `compile-gameplay-dll` 技能
+- 涉及配置表变更 → 读取 `luban-config` 技能
+- 需要提交代码 → 读取 `batch-git-ops` 技能
+- 性能优化相关 → 读取 `knowledge-base` 技能查看已完成的优化案例

.github/agents/ui-developer.agent.md

@@ -0,0 +1,52 @@
+---
+name: ui-developer
+description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发和 UI 控制器代码
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# UI Developer Agent
+
+## 角色
+你是 NLD 游戏项目的 UI 开发专家，专注于 Unity UGUI Prefab 开发和 UI 控制器代码编写。
+
+> **操作层细节**（Prefab 提取方式、JSON 格式、组件属性格式等）见 `ui-prefab-dev` 技能，本 Agent 专注于决策和设计层。
+
+## 设计决策原则
+
+### 何时使用 AutoGen
+- 组件层级深（3+ 层嵌套）或引用数量多（5+ 个代码引用）→ 优先用 AutoGen 自动绑定
+- 少量简单引用（1-2 个顶层组件）→ 手动绑定即可
+- AutoGen 文件命名: `UI_XXXController.AutoGen.cs`（不可手动修改）
+
+### 何时不用 AutoGen
+- 组件需要运行时条件绑定（根据状态决定绑定哪个）→ 手动绑定
+- 动态生成/销毁的 UI 元素 → 必须在代码中动态查找或缓存
+
+### 何时使用对象池
+- 列表项数量 > 10 或会频繁刷新 → 必须用对象池
+- 固定数量的静态 UI 元素 → 直接放在 Prefab 中
+
+### MVC 分层选择
+- **Controller**（`UI_XXXController`）：只负责 UI 交互逻辑和显示刷新
+- **数据层**：通过 Manager 获取，Controller 不持有业务数据
+- **视图层**：Prefab 定义布局，Controller 通过字段引用操控
+
+### 界面生命周期
+- 打开/关闭遵循 ShowManager 生命周期
+- 弹窗通过 PopUpManager 管理
+- 支持遮罩点击关闭
+- 进入/退出动画必须配对（DOTween）
+
+## 关键约定
+
+- UI 代码位于 `Assets/Code/Scripts/GamePlay/UI/`
+- Controller 继承 `UIBaseController`
+- 图片资源异步加载，不在主线程同步等待
+- 多语言文本通过配置表获取，不在代码中硬编码字符串
+- 列表使用 ScrollRect + 数据驱动刷新，避免全量重建
+
+## 技能引用
+- Prefab 结构分析和操作流程 → 读取 `ui-prefab-dev` 技能
+- 配置表字段查询 → 读取 `luban-config` 技能
+- 修改代码后编译 → 读取 `compile-gameplay-dll` 技能

.github/hooks/post-file-create.md

@@ -0,0 +1,14 @@
+---
+event: post-file-create
+condition: "new file created in Assets/"
+action: remind
+protocol: ../protocols/no-meta-files.md
+description: 提醒不要生成 Unity .meta 文件
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/no-meta-files.md](../protocols/no-meta-files.md)
+
+触发时：提醒不要生成 .meta 文件，确认文件所属 Assembly Definition。
+

.github/hooks/pre-code-change.md

@@ -0,0 +1,14 @@
+---
+event: pre-code-change
+condition: "large code modification (>50 lines or >3 files)"
+action: confirm_with_user
+protocol: ../protocols/confirm-before-act.md
+description: 大量代码修改前先与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/confirm-before-act.md](../protocols/confirm-before-act.md)
+
+触发时：将修改计划描述给用户，等待确认后再开始执行。
+

.github/hooks/pre-commit.md

@@ -0,0 +1,15 @@
+---
+event: pre-commit
+condition: "git commit operation"
+action: run_skill
+skill: batch-git-ops
+protocol: ../protocols/git-safety.md
+description: Git 提交前确保三仓同步，遵循 batch-git-ops 技能流程
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/git-safety.md](../protocols/git-safety.md)
+
+触发时：读取 `batch-git-ops` 技能，检查三仓状态，生成 commit message，展示变更摘要并获得确认。
+

.github/protocols/confirm-before-act.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: 确认再行动协议 — 大量修改前必须与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # 确认再行动

.github/protocols/git-safety.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: Git 操作安全协议 — 不做未经确认的 git 操作，三仓同步
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Git 操作安全协议

.github/protocols/no-meta-files.md

@@ -1,6 +1,8 @@
 ---
 scope: always
 description: 不生成 Unity meta 文件，不主动编译项目
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Unity 项目约定

.github/skills/batch-git-ops/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: batch-git-ops
 description: 三仓 Git 操作（NLDClient/NLDMisc/GamePlay）。触发关键词：git pull push commit checkout branch status stash fetch log、三仓同步、batch git。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Batch Git Operations
@@ -25,8 +27,15 @@ All paths are relative to the workspace root (`ProjectNLD`). Use forward slashes
 - Never use `\` in paths; always use `/`
 - Always remind the user that git operations carry risk before proceeding
 
+## 不适用场景
+
+- 只修改了单个仓库的单个文件且无需同步其他仓库 → 不需要走三仓流程
+- AI 未经用户要求主动做 git 操作 → 遵循 git-safety 协议，不主动操作
+
 ## Operations
 
+### 核心操作（高频）
+
 ### 1. batch-status
 
 Show current state of all repos.
@@ -168,36 +177,12 @@ Push current branches for all repos.
 3. If upstream exists, use: `git push`
 4. Report results per repo
 
-### 7. batch-fetch
+### 7. batch-fetch / batch-stash / batch-log（低频）
 
-Fetch remote updates without merging.
+简洁操作，不再展开详细流程：
-
+- **batch-fetch**: 每个仓库执行 `git fetch --all --prune`，报告更新情况
-For each repo, run:
+- **batch-stash `<save|pop>`**: save 时 `git stash push -m "batch-stash"`；pop 时 `git stash pop`；跳过无变更仓库
-```
+- **batch-log**: 每个仓库执行 `git log --oneline -5`，汇总展示
-git fetch --all --prune
-```
-
-Report fetched updates per repo.
-
-### 8. batch-stash
-
-Stash or pop changes across all repos.
-
-**Parameters:** `save` or `pop`
-
-- `save`: run `git stash push -m "batch-stash"` on each repo (skip if clean)
-- `pop`: run `git stash pop` on each repo (skip if stash is empty)
-
-Report results per repo.
-
-### 9. batch-log
-
-Show recent commit history across repos.
-
-For each repo, run:
-```
-git log --oneline -5
-```
 
 Present as grouped output per repo.
 

.github/skills/compile-gameplay-dll/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: compile-gameplay-dll
 description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编译 compile、GamePlay.dll、转换为Dll、build DLL、编译错误、Assembly Definition asmdef。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Compile GamePlay DLL
@@ -14,12 +16,19 @@ description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编
 - **编译菜单**: `Tools/文件与路径/转换为Dll`（快捷键 F1）
 - **Assembly Definition**: `Assets/Code/Scripts/GamePlay/GamePlay.asmdef`
 
+## 不适用场景
+
+- 只修改了 `GamePlay/` 以外的代码（Framework/GameWrapper/UI/ 等）→ 不需要编译 DLL
+- 只修改了配置表 → 走 `luban-config` 流程即可
+
 ## 编译流程
 
 根据是否有 Unity MCP 可用，选择对应路径：
 
 ### 路径 A：通过 Unity MCP 自动编译（优先）
 
+> **前置检测**：首先确认 Unity MCP (`user-unityMCP`) 是否可用。可用则走此路径，不可用则自动降级到路径 B。
+
 **前置步骤** — 确保代码最新：
 1. `git pull` NLDClient 仓库（`../../`）
 2. `git pull` GamePlay 仓库（`Assets/Code/Scripts/GamePlay`）

.github/skills/knowledge-base/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: knowledge-base
 description: 项目知识库索引。查阅功能说明、性能优化记录、开发日志时使用。触发关键词：武器熟练度 WeaponDegree、ShowAreaId 显示区域、攻击换弹 canAttackNoReloadFull、暂停技能释放、载具科技树、PerformanceManager 性能参数 性能优化、GC 分配 内存优化 Buff性能、密钥泄露 secret exposure、资源检查 FileChecker batch runner。涵盖 AI_Gen_Doc 和 AI_CODE 中的所有文档。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # 项目知识库
@@ -83,6 +85,7 @@ description: 项目知识库索引。查阅功能说明、性能优化记录、
 
 ## 安全规则
 
+- 查询前先用 `file_search` 确认目标文档是否存在，若不存在则搜索相似文件名并告知用户
 - 只读查阅，不要修改已归档的文档（除非用户要求更新）
 - 性能优化任务执行前必须评估风险（跨类修改、生命周期影响等）
 - 有风险的任务标记为跳过，等用户确认后再执行

.github/skills/luban-config/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: luban-config
 description: Luban 配置表操作：生成代码、修改配置、校验数据。涉及配置表（Excel/XML）和 Luban 工具链的操作。触发关键词：配置表 config table、Luban 导出 export、Excel 数据、Root.xml、GenCode、LubanExportConfig、数值配置、新增配置表、配置校验。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Luban 配置表操作
@@ -35,6 +37,11 @@ Assets/PhxhSDK/Editor/Settings/Luban_Client_EN.asset   # 客户端英文
 Assets/PhxhSDK/Editor/Settings/Luban_Server.asset      # 服务端
 ```
 
+## 不适用场景
+
+- 只修改了游戏逻辑代码（不涉及配置表）→ 不需要走 Luban 流程
+- 只查配置表字段结构 → 直接看 `Assets/Code/Scripts/GenCode/Luban/` 中的生成代码即可
+
 ## 工作流
 
 ### 1. 修改配置表

.github/skills/ui-prefab-dev/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ui-prefab-dev
 description: Unity UI Prefab 开发：结构分析、组件修改、代码生成。涉及 UI Prefab 层级查看、组件属性读取、UI 控制器代码编写。触发关键词：UI界面 UI开发、Prefab 预制体、UIBaseController、AutoGen、UGUI、RectTransform、Image Button Text、ScrollRect 列表、extract_ui_prefab、ExtractedPrefabs、UI控制器。
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # UI Prefab 开发
@@ -34,22 +36,7 @@ execute_custom_tool: {
 
 ### 2. 理解 UI 层级结构
 
-JSON 输出格式：
+JSON 格式和属性格式定义见 `ExtractedPrefabs/README.md`。
-
-```
-UIInfoNode {
-  name: string          // GameObject 名称
-  active: boolean       // 激活状态
-  components: []        // UIInfoComponent 列表
-  children: []          // 子节点（递归）
-}
-
-UIInfoComponent {
-  componentName: string  // 组件类型名（RectTransform, Image, Text, Button...）
-  enable: boolean        // 启用状态
-  properties: string[]   // "Key:Value" 格式属性列表
-}
-```
 
 常见组件类型：
 - **RectTransform**: 锚点、位置、尺寸
@@ -91,6 +78,11 @@ public class UI_XXXController.AutoGen : ...
 3. 如需自动绑定，编写 AutoGen 辅助类
 4. 注册到 UI 管理系统中
 
+## 不适用场景
+
+- 纯逻辑 UI 改动（不涉及 Prefab 结构变化）→ 直接改 Controller 代码即可
+- 简单的位置/颜色微调 → 无需走完整提取流程，直接描述修改即可
+
 ## 属性格式参考
 
 | 类型 | 格式示例 |

.kiro/agents/code-reviewer.md

@@ -1,6 +1,8 @@
 ---
 name: code-reviewer
 description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性能、架构审查
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Code Reviewer Agent
@@ -18,7 +20,7 @@ description: NLD 项目代码审查专用 Agent，专注 C# 代码质量、性
 
 | 严重度 | 判断标准 |
 |--------|----------|
-| **高** | 会导致崩溃/卡死/数据丢失，或在每帧热路径产生 GC，或内存泄漏 |
+| **高** | 会导致崩溃/卡死/数据丢失；或在每帧热路径产生 GC；或在 Update/LateUpdate 中调用 `GameObject.Find`、`GetComponent`、`FindObjectOfType` 等全局搜索 API；或内存泄漏 |
 | **中** | 影响性能但不致崩溃，或违反架构分层，或缺少空引用保护 |
 | **低** | 命名不规范、缺少缓存但不在热路径、代码风格问题 |
 

.kiro/agents/default.md

@@ -1,12 +1,14 @@
 ---
 name: default
 description: NLD 项目默认 AI 编码助手 — GamePlay 模块开发专家，擅长 Unity C# 游戏逻辑、Buff/战斗/技能/角色系统开发
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # Default Agent — GamePlay Developer
 
 ## 角色
-你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块的日常开发。
+你是 NLD 游戏项目的 GamePlay 开发专家，专注于 `Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块（常用核心模块见下方索引，完整列表可通过 `list_dir` 查看 `GamePlay/` 目录）的日常开发。
 
 ## 核心决策原则
 

.kiro/agents/ui-developer.md

@@ -1,6 +1,8 @@
 ---
 name: ui-developer
 description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发和 UI 控制器代码
+version: "1.0"
+updated: "2026-05-08"
 ---
 
 # UI Developer Agent
@@ -13,10 +15,14 @@ description: NLD 项目 UI 开发专用 Agent，专注 Unity UGUI Prefab 开发
 ## 设计决策原则
 
 ### 何时使用 AutoGen
-- Prefab 中有 **5+ 个需要代码引用的组件** → 用 AutoGen 自动绑定
+- 组件层级深（3+ 层嵌套）或引用数量多（5+ 个代码引用）→ 优先用 AutoGen 自动绑定
-- 只有 1-2 个简单引用 → 手动绑定即可
+- 少量简单引用（1-2 个顶层组件）→ 手动绑定即可
 - AutoGen 文件命名: `UI_XXXController.AutoGen.cs`（不可手动修改）
 
+### 何时不用 AutoGen
+- 组件需要运行时条件绑定（根据状态决定绑定哪个）→ 手动绑定
+- 动态生成/销毁的 UI 元素 → 必须在代码中动态查找或缓存
+
 ### 何时使用对象池
 - 列表项数量 > 10 或会频繁刷新 → 必须用对象池
 - 固定数量的静态 UI 元素 → 直接放在 Prefab 中

.kiro/hooks/post-file-create.md

@@ -0,0 +1,14 @@
+---
+event: post-file-create
+condition: "new file created in Assets/"
+action: remind
+protocol: ../protocols/no-meta-files.md
+description: 提醒不要生成 Unity .meta 文件
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/no-meta-files.md](../protocols/no-meta-files.md)
+
+触发时：提醒不要生成 .meta 文件，确认文件所属 Assembly Definition。
+

.kiro/hooks/pre-code-change.md

@@ -0,0 +1,14 @@
+---
+event: pre-code-change
+condition: "large code modification (>50 lines or >3 files)"
+action: confirm_with_user
+protocol: ../protocols/confirm-before-act.md
+description: 大量代码修改前先与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/confirm-before-act.md](../protocols/confirm-before-act.md)
+
+触发时：将修改计划描述给用户，等待确认后再开始执行。
+

.kiro/hooks/pre-commit.md

@@ -0,0 +1,15 @@
+---
+event: pre-commit
+condition: "git commit operation"
+action: run_skill
+skill: batch-git-ops
+protocol: ../protocols/git-safety.md
+description: Git 提交前确保三仓同步，遵循 batch-git-ops 技能流程
+version: "1.0"
+updated: "2026-05-08"
+---
+
+> 完整规则定义见 [../protocols/git-safety.md](../protocols/git-safety.md)
+
+触发时：读取 `batch-git-ops` 技能，检查三仓状态，生成 commit message，展示变更摘要并获得确认。
+

.kiro/protocols/confirm-before-act.md

@@ -0,0 +1,12 @@
+---
+scope: always
+description: 确认再行动协议 — 大量修改前必须与用户确认设计思路
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# 确认再行动
+
+- 除非用户要求特别清晰，开始编码行为之前，将你的计划描述给用户并获得用户确认后才开始行动
+- 收集信息、搜索代码、编写计划等操作不需要确认
+- 如果有疑问主动向用户确认

.kiro/protocols/git-safety.md

@@ -0,0 +1,13 @@
+---
+scope: always
+description: Git 操作安全协议 — 不做未经确认的 git 操作，三仓同步
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Git 操作安全协议
+
+- 除非用户要求，AI 不做任何 git 提交相关操作
+- 当用户让 AI 操作 git 时提醒用户 git 操作有风险
+- **重要**：本项目有三个关联的 Git 仓库，任何 git 操作都必须同时考虑三个仓库的同步对齐
+- 执行 git 操作时必须读取并遵循 `batch-git-ops` 技能的流程

.kiro/protocols/no-meta-files.md

@@ -0,0 +1,12 @@
+---
+scope: always
+description: 不生成 Unity meta 文件，不主动编译项目
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Unity 项目约定
+
+- 不要生成 Unity 的 .meta 文件，留给 Unity 自己生成
+- 不要主动编译项目，这是一个 Unity 项目，Unity 会自动进行编译
+- 如果有编译错误用户会自主拷贝给你，但你可以做自己的静态代码检查

.kiro/skills/batch-git-ops/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: batch-git-ops
+description: 三仓 Git 操作（NLDClient/NLDMisc/GamePlay）。触发关键词：git pull push commit checkout branch status stash fetch log、三仓同步、batch git。
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Batch Git Operations
+
+Perform git operations across three project repositories simultaneously.
+
+## Repository Definitions
+
+All paths are relative to the workspace root (`ProjectNLD`). Use forward slashes only.
+
+| Name | Relative Path | Description |
+|------|--------------|-------------|
+| NLDClient | `../../` | Main client repo |
+| NLDMisc | `../../../NLDMisc` | Config/data repo |
+| GamePlay | `Assets/Code/Scripts/GamePlay` | Core gameplay code repo |
+
+## Cross-Platform Rules
+
+- Execute git commands via the Shell tool with `working_directory` set to each repo's **absolute path** (resolve from workspace root + relative path)
+- Issue one Shell call per repo per command (parallelizable when independent)
+- Never use `&&` to chain commands (PowerShell incompatible)
+- Never use `\` in paths; always use `/`
+- Always remind the user that git operations carry risk before proceeding
+
+## 不适用场景
+
+- 只修改了单个仓库的单个文件且无需同步其他仓库 → 不需要走三仓流程
+- AI 未经用户要求主动做 git 操作 → 遵循 git-safety 协议，不主动操作
+
+## Operations
+
+### 核心操作（高频）
+
+### 1. batch-status
+
+Show current state of all repos.
+
+For each repo, run:
+```
+git status -sb
+```
+
+Present results in a summary table:
+
+```
+| Repo | Branch | Clean | Ahead/Behind |
+```
+
+### 2. batch-pull
+
+Pull latest changes for all repos.
+
+**Workflow:**
+1. Run `git status --porcelain` on each repo in parallel
+2. If any repo has uncommitted changes, warn the user and ask whether to continue (stash / skip / abort)
+3. Run `git pull` on each repo
+4. Report results:
+
+```
+| Repo | Result | Details |
+```
+
+Result values: updated / already up-to-date / conflict / error
+
+### 3. batch-create-branch
+
+Create a new branch with the same name in all repos and switch to it.
+
+**Parameters:** `<branch-name>` (required), `<base-branch>` (optional, default: current branch)
+
+**Workflow:**
+1. Check uncommitted changes in each repo (same as batch-pull step 1-2)
+2. For each repo, check if branch already exists:
+   ```
+   git branch --list <branch-name>
+   git branch -r --list "origin/<branch-name>"
+   ```
+3. If branch exists in some repos, ask user: switch to existing / skip / abort
+4. If base-branch specified, run `git checkout <base-branch>` then `git pull` first
+5. Create and switch: `git checkout -b <branch-name>`
+6. Report results per repo
+
+### 4. batch-checkout
+
+Switch all repos to a specified branch.
+
+**Parameters:** `<branch-name>` (required)
+
+**Workflow:**
+1. Check uncommitted changes (same as above)
+2. For each repo, verify branch exists:
+   ```
+   git branch -a
+   ```
+3. If a repo does NOT have the target branch:
+   - List all branches from `git branch -a` output
+   - Search for similar names using substring/prefix matching (e.g., user typed `featrue/x`, actual is `feature/x`)
+   - Present similar branch names to the user
+   - Skip this repo but continue switching others
+4. For repos where branch exists:
+   - If branch is remote-only (`remotes/origin/<name>` but no local), run `git checkout -b <branch-name> origin/<branch-name>`
+   - If branch is local, run `git checkout <branch-name>`
+5. Report results:
+
+```
+| Repo | Result | Current Branch |
+```
+
+**Fuzzy matching logic** (applied when exact branch not found):
+- Extract clean branch names from `git branch -a` output (strip whitespace, `*`, `remotes/origin/` prefix)
+- Check for: exact case-insensitive match, substring containment, common typo patterns (transposed chars)
+- Present top 5 closest matches to user
+
+### 5. batch-commit
+
+Commit changes in all repos with the same message.
+
+**Parameters:** `<commit-message>` (optional — if not provided, AI must auto-generate)
+
+**Commit Message Rules:**
+
+AI 必须自动检索所有仓库的变更内容（`git diff`、`git status`），分析修改涉及的模块和意图，自动生成合适的 commit message。用户也可以手动指定 message 来覆盖。
+
+格式规范：
+- **人工编码修改**（用户自己写的代码，AI 只是帮忙提交）：`【所属模块】描述内容`
+- **AI 编码修改**（AI 在本次会话中编写/修改的代码）：`【AI编码】【所属模块】描述内容`
+
+模块名称根据变更文件的路径和内容自动判断，例如：
+- `Buff/` 目录下的文件 → 模块为 `Buff`
+- `Character/State/` 目录下 → 模块为 `角色状态`
+- `UI/` 目录下 → 模块为 `UI`
+- 配置表相关 → 模块为 `配置表`
+- 多个模块同时修改时，列出主要模块，如 `【Buff/角色状态】`
+
+示例：
+- `【Buff】将普攻计数时机从攻击前移到攻击后`
+- `【AI编码】【UI】新增背包界面道具排序功能`
+- `【AI编码】【Buff/角色】修复buff叠加时属性未正确刷新的问题`
+
+**Workflow:**
+1. For each repo in parallel, run:
+   ```
+   git status --porcelain
+   git diff --stat
+   git diff
+   ```
+2. Analyze changes to determine affected modules and generate commit message
+3. Present a summary showing changed files per repo, the auto-generated commit message, and whether it's AI-authored code. If a repo has no changes, note it will be skipped
+4. Ask user to confirm (user may modify the message)
+5. For each repo with changes:
+   ```
+   git add .
+   git commit -m "<commit-message>"
+   ```
+6. Ask if user wants to push as well (see batch-push)
+7. Report results:
+
+```
+| Repo | Files Changed | Committed | Pushed |
+```
+
+### 6. batch-push
+
+Push current branches for all repos.
+
+**Workflow:**
+1. For each repo, check if remote tracking branch exists:
+   ```
+   git rev-parse --abbrev-ref --symbolic-full-name @{u}
+   ```
+2. If no upstream, use: `git push -u origin HEAD`
+3. If upstream exists, use: `git push`
+4. Report results per repo
+
+### 7. batch-fetch / batch-stash / batch-log（低频）
+
+简洁操作，不再展开详细流程：
+- **batch-fetch**: 每个仓库执行 `git fetch --all --prune`，报告更新情况
+- **batch-stash `<save|pop>`**: save 时 `git stash push -m "batch-stash"`；pop 时 `git stash pop`；跳过无变更仓库
+- **batch-log**: 每个仓库执行 `git log --oneline -5`，汇总展示
+
+Present as grouped output per repo.
+
+### 10. compile-gameplay-dll
+
+> **详细编译流程见 `compile-gameplay-dll` 技能的 SKILL.md**，此处仅说明与 batch-commit 的集成逻辑。
+
+当 `batch-commit` 检测到 GamePlay 有 `.cs` 文件变更时：
+
+1. **提交前**自动触发 `compile-gameplay-dll` 技能的编译流程
+2. 编译成功后 NLDClient 也会有变更（更新的 DLL 文件），一并纳入提交
+3. 编译失败 → 中止所有仓库的提交并报告错误
+
+## Safety Rules
+
+- NEVER run `--force`, `--hard`, `reset`, or any destructive git command
+- NEVER skip user confirmation before commits or branch operations
+- If any operation fails or produces a conflict, stop and report immediately — do not continue silently
+- Each repo operates independently: one repo's failure must not block others
+- Always show a summary report after batch operations complete
+
+## Output Format
+
+Always present results in a structured table for quick scanning. Example:
+
+```
+## Batch Operation Results
+
+| Repo | Operation | Result | Details |
+|------|-----------|--------|---------|
+| NLDClient | pull | updated | 3 files changed |
+| NLDMisc | pull | up-to-date | — |
+| GamePlay | pull | updated | 12 files changed |
+```

.kiro/skills/compile-gameplay-dll/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: compile-gameplay-dll
+description: 编译 GamePlay C# 源码为 GamePlay.dll。触发关键词：编译 compile、GamePlay.dll、转换为Dll、build DLL、编译错误、Assembly Definition asmdef。
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Compile GamePlay DLL
+
+将 GamePlay 源码编译为 `GamePlay.dll`。
+
+## 前置知识
+
+- **源码位置**: `Assets/Code/Scripts/GamePlay/`（独立 Git 仓库）
+- **产物位置**: `Assets/Code/Scripts/GamePlay_Dll/GamePlay.dll`（属于 NLDClient 仓库）
+- **编译菜单**: `Tools/文件与路径/转换为Dll`（快捷键 F1）
+- **Assembly Definition**: `Assets/Code/Scripts/GamePlay/GamePlay.asmdef`
+
+## 不适用场景
+
+- 只修改了 `GamePlay/` 以外的代码（Framework/GameWrapper/UI/ 等）→ 不需要编译 DLL
+- 只修改了配置表 → 走 `luban-config` 流程即可
+
+## 编译流程
+
+根据是否有 Unity MCP 可用，选择对应路径：
+
+### 路径 A：通过 Unity MCP 自动编译（优先）
+
+> **前置检测**：首先确认 Unity MCP (`user-unityMCP`) 是否可用。可用则走此路径，不可用则自动降级到路径 B。
+
+**前置步骤** — 确保代码最新：
+1. `git pull` NLDClient 仓库（`../../`）
+2. `git pull` GamePlay 仓库（`Assets/Code/Scripts/GamePlay`）
+3. 刷新 Unity：
+   ```
+   CallMcpTool: server="user-unityMCP", toolName="refresh_unity",
+     arguments={ "mode": "force", "scope": "all", "compile": "request", "wait_for_ready": true }
+   ```
+4. 检查编译错误，有错误则停止。
+
+**执行编译**：
+1. 调用菜单：
+   ```
+   CallMcpTool: server="user-unityMCP", toolName="execute_menu_item",
+     arguments={ "menu_path": "Tools/文件与路径/转换为Dll" }
+   ```
+2. 等待编译完成 — 轮询 `editor_state`，检查 `isCompiling` 为 `false`。
+3. 检查错误：
+   ```
+   CallMcpTool: server="user-unityMCP", toolName="read_console",
+     arguments={ "action": "get", "types": ["error"], "count": "20" }
+   ```
+4. 有错误 → 报告并停止；无错误 → 编译成功。
+
+### 路径 B：提示用户手动编译（无 MCP 时）
+
+> 请在 Unity Editor 中执行：
+> 1. 菜单 `Tools/文件与路径/转换为Dll`（或快捷键 F1）
+> 2. 等待编译完成
+> 3. 如有编译错误，将错误信息提供给 AI 修复
+
+## 编译后处理
+
+- 确认 `GamePlay_Dll/GamePlay.dll` 文件时间戳已更新
+- 编译成功后 NLDClient 仓库会有变更（更新的 DLL 文件）
+- 若需提交，走 `batch-git-ops` 流程（NLDClient + GamePlay 两个仓库）
+
+## 安全规则
+
+- 编译前确保所有 .cs 文件已保存
+- 不要在编译过程中修改源码文件
+- 编译失败时优先检查 Assembly Definition 引用是否完整
+- DLL 编译成功后如涉及三仓变更，必须走 batch-git-ops 流程

.kiro/skills/knowledge-base/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: knowledge-base
+description: 项目知识库索引。查阅功能说明、性能优化记录、开发日志时使用。触发关键词：武器熟练度 WeaponDegree、ShowAreaId 显示区域、攻击换弹 canAttackNoReloadFull、暂停技能释放、载具科技树、PerformanceManager 性能参数 性能优化、GC 分配 内存优化 Buff性能、密钥泄露 secret exposure、资源检查 FileChecker batch runner。涵盖 AI_Gen_Doc 和 AI_CODE 中的所有文档。
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# 项目知识库
+
+提供对项目 AI 生成文档和开发记录的索引和查阅能力。
+
+## 关键词 → 文档速查
+
+当用户提到以下关键词时，自动定位到对应文档：
+
+| 关键词 | 文档路径 |
+|--------|----------|
+| 武器熟练度, WeaponDegree | `AI_Gen_Doc/武器熟练度功能说明.md` |
+| ShowAreaId, 显示区域 | `AI_Gen_Doc/ShowAreaId相关逻辑说明.md` |
+| 攻击换弹, canAttackNoReloadFull, 不换弹 | `AI_Gen_Doc/canAttackNoReloadFull功能说明.md` |
+| 暂停技能, 暂停释放, pause skill | `AI_Gen_Doc/暂停状态下技能释放流程说明.md` |
+| 载具科技树, vehicle tech tree | `AI_Gen_Doc/载具科技树生成功能说明.md` |
+| 性能参数, PerformanceManager, 动态性能 | `AI_Gen_Doc/PerformanceManager动态性能参数接入指南.md` |
+| 性能优化, GC, 内存, Buff性能, 优化清单 | `AI_Gen_Doc/性能优化任务清单.md` + `AI_Gen_Doc/Finish/` |
+| 密钥泄露, secret, exposure, 安全扫描 | `AI_Gen_Doc/package_secret_exposure_report.md` |
+| 资源检查, FileChecker, batch runner | `AI_CODE/batch_resource_checker_*.md` |
+
+## 知识库目录
+
+### AI_Gen_Doc/ — 功能说明与任务清单
+
+| 文档 | 用途 |
+|------|------|
+| `武器熟练度功能说明.md` | WeaponDegree 属性设计与配置说明 |
+| `ShowAreaId相关逻辑说明.md` | 显示区域 ID 的逻辑说明 |
+| `canAttackNoReloadFull功能说明.md` | 攻击时不自动换弹的功能说明 |
+| `暂停状态下技能释放流程说明.md` | 暂停状态下技能释放的处理流程 |
+| `载具科技树生成功能说明.md` | 载具科技树的生成逻辑 |
+| `PerformanceManager动态性能参数接入指南.md` | 动态性能参数配置指南 |
+| `性能优化任务清单.md` | 按独立单元组织的性能优化任务（P0/P1 优先级） |
+| `package_secret_exposure_report.md` | 包体密钥泄露扫描报告 |
+
+**`Finish/` 子目录**（已完成任务详情）:
+| 文件 | 任务 |
+|------|------|
+| `P0-01_GetBuffsByType复用List.md` | Buff 系统 — GetBuffsByType 复用 List |
+| `P0-02_RemoveBuffById去除lambda.md` | Buff 系统 — RemoveBuffById 去除 lambda 分配 |
+| `P0-03_needRemoveList改用HashSet.md` | Buff 系统 — _needRemoveList 改用 HashSet |
+| `P0-04_totalBuffList_Contains改用HashSet.md` | Buff 系统 — totalBuffList.Contains 改用 HashSet |
+| `P0-06_BuffAddSearchValue去除KeysToList.md` | Buff 系统 — BuffAddSearchValue 去除 KeysToList |
+| `P0-07_UpdateBatchGroup复用List.md` | Buff 系统 — UpdateBatchGroup 复用 List |
+| `P0-11_DamageRecordor去除ToArray.md` | 伤害记录 — DamageRecordor 去除 ToArray |
+
+### AI_CODE/ — 开发日志与改进记录
+
+| 文档 | 用途 |
+|------|------|
+| `batch_resource_checker_debug_journal.md` | 批量资源检测工具问题定位全程记录 |
+| `batch_resource_checker_improvement_summary.md` | 批量资源检测工具改进总结 |
+
+## 使用方式
+
+### 查阅功能说明
+
+当需要了解某个游戏功能的设计和实现时：
+
+1. 先阅读对应功能说明文档了解设计意图
+2. 再根据文档中的文件引用定位源码
+3. 结合源码和文档进行修改
+
+### 查阅性能优化记录
+
+当进行性能相关工作时：
+
+1. 阅读 `性能优化任务清单.md` 了解已完成和待完成的任务
+2. 查看 `Finish/` 目录中的已完成任务了解优化模式和收益
+3. 参考已完成任务的模式执行新优化
+
+### 查阅开发日志
+
+当遇到类似问题或需要了解工具链时：
+
+1. 阅读 `AI_CODE/` 中的调试日志了解问题排查思路
+2. 阅读改进总结了解工具链演进
+
+## 安全规则
+
+- 查询前先用 `file_search` 确认目标文档是否存在，若不存在则搜索相似文件名并告知用户
+- 只读查阅，不要修改已归档的文档（除非用户要求更新）
+- 性能优化任务执行前必须评估风险（跨类修改、生命周期影响等）
+- 有风险的任务标记为跳过，等用户确认后再执行

.kiro/skills/luban-config/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: luban-config
+description: Luban 配置表操作：生成代码、修改配置、校验数据。涉及配置表（Excel/XML）和 Luban 工具链的操作。触发关键词：配置表 config table、Luban 导出 export、Excel 数据、Root.xml、GenCode、LubanExportConfig、数值配置、新增配置表、配置校验。
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# Luban 配置表操作
+
+操作游戏配置表系统，基于 Luban 工具链。
+
+## 前置知识
+
+- **Luban 工具位置**: `Assets/PhxhSDK/Phxh/ThirdParty/Luban/`
+- **导出配置**: `Assets/PhxhSDK/Editor/Settings/Luban_*.asset`（Client_CN/Client_EN/Server）
+- **生成代码**: `Assets/Code/Scripts/GenCode/Luban/`（Luban 生成的 C# 代码）
+- **配置表源文件**: 位于 NLDMisc 仓库（`../../../NLDMisc`），通常为 Excel 格式
+- **NLDMisc 典型结构**: `NLDMisc/Data/` 下按功能模块分目录存放 Excel 文件
+- **Editor 脚本**: `Assets/PhxhSDK/Phxh/ThirdParty/Luban/Editor/LubanExportConfig.cs`
+- **Root.xml 定义**: 在 NLDMisc 仓库中，注册所有表的字段和类型定义
+
+## 配置表导出配置说明
+
+Luban 使用 `LubanExportConfig` (ScriptableObject) 管理导出参数：
+
+- `which_dll`: 数据校验 DLL（Client&Server 共用）
+- `define_xml`: Root.xml 定义文件
+- `service`: 生成目标（server / client）
+- `-t`: 生成类型参数
+- `-c`: 其他命令行参数
+- `before_gen` / `after_gen`: 生命周期回调脚本
+
+配置文件路径模式:
+```
+Assets/PhxhSDK/Editor/Settings/Luban_Client_CN.asset   # 客户端中文
+Assets/PhxhSDK/Editor/Settings/Luban_Client_EN.asset   # 客户端英文
+Assets/PhxhSDK/Editor/Settings/Luban_Server.asset      # 服务端
+```
+
+## 不适用场景
+
+- 只修改了游戏逻辑代码（不涉及配置表）→ 不需要走 Luban 流程
+- 只查配置表字段结构 → 直接看 `Assets/Code/Scripts/GenCode/Luban/` 中的生成代码即可
+
+## 工作流
+
+### 1. 修改配置表
+
+当需要修改游戏配置参数时：
+
+1. **定位配置表**: 根据功能需求找到对应的 Excel/CSV 配置文件
+2. **理解字段含义**: 查看 `Assets/Code/Scripts/GenCode/Luban/` 中生成的 C# 类了解字段结构
+3. **修改数据**: 编辑配置表文件中的具体数值
+4. **重新导出**: 提示用户在 Unity Editor 中执行 Luban 导出（菜单路径: `Luban/Export` 或 `Phxh/Luban/Export`）
+
+### 2. 新增配置表
+
+1. 在 `Root.xml` 中注册新表定义
+2. 创建 Excel 源文件
+3. 执行 Luban 导出生成 C# 代码
+4. 验证生成的代码在 `Assets/Code/Scripts/GenCode/Luban/` 中
+
+### 3. 配置校验
+
+- 导出过程中 Luban 会自动根据 `which_dll` 指定的校验 DLL 进行数据校验
+- 校验失败会在 Unity Console 输出错误信息
+- 常见校验错误：字段类型不匹配、引用 ID 不存在、必填字段为空
+
+## 生成代码规范
+
+Luban 生成的代码位于 `Assets/Code/Scripts/GenCode/Luban/`：
+- 每个配置表对应一个 C# 类
+- 类名通常与配置表名一致
+- 包含字段属性、索引查找方法、验证逻辑
+- **不要手动修改生成代码**（重新导出会覆盖）
+
+## 安全规则
+
+- 修改配置表前确认当前编辑的是正确的 target（Client/Server）
+- 导出前备份重要配置数据
+- 配置表变更通常涉及三仓（NLDClient + NLDMisc），需走 batch-git-ops 流程
+- 多语言配置需同步更新 CN/EN 两个版本
+- 新增字段需同步更新服务端和客户端的 Root.xml 定义

.kiro/skills/ui-prefab-dev/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: ui-prefab-dev
+description: Unity UI Prefab 开发：结构分析、组件修改、代码生成。涉及 UI Prefab 层级查看、组件属性读取、UI 控制器代码编写。触发关键词：UI界面 UI开发、Prefab 预制体、UIBaseController、AutoGen、UGUI、RectTransform、Image Button Text、ScrollRect 列表、extract_ui_prefab、ExtractedPrefabs、UI控制器。
+version: "1.0"
+updated: "2026-05-08"
+---
+
+# UI Prefab 开发
+
+分析、修改和生成 Unity UI Prefab 及相关 C# 控制器代码。
+
+## 前置知识
+
+- **UI Prefab 位置**: `Assets/` 下的各 UI 模块目录
+- **UI 控制器代码**: `Assets/Code/Scripts/GamePlay/UI/`（60+ 控制器）
+- **生成代码标记**: `*Controller.AutoGen.cs` 文件（自动生成，勿手动修改）
+- **ExtractedPrefabs**: `ExtractedPrefabs/` 目录存放导出的 Prefab JSON 结构
+- **JSON 格式说明**: `ExtractedPrefabs/README.md`
+
+## 工作流
+
+### 1. 获取 UI Prefab 结构
+
+通过 Unity MCP 提取 Prefab 结构信息：
+
+```
+execute_custom_tool: {
+  tool_name: "extract_ui_prefab",
+  parameters: { prefab_path: "Assets/xxx/xxx.prefab" }
+}
+```
+
+读取返回的 JSON 文件，参考 `ExtractedPrefabs/README.md` 理解 JSON 格式。
+
+> **重要**: 每次分析前都需重新提取（避免读取旧数据）。
+
+### 2. 理解 UI 层级结构
+
+JSON 格式和属性格式定义见 `ExtractedPrefabs/README.md`。
+
+常见组件类型：
+- **RectTransform**: 锚点、位置、尺寸
+- **Image**: Sprite 引用、Color、ImageType、RaycastTarget
+- **Text/TMP_Text**: 文本内容、字体、字号、颜色
+- **Button**: Transition 类型、颜色状态
+- **CanvasRenderer**: 渲染参数
+
+### 3. 分析 UI 控制逻辑
+
+UI 控制器代码模式：
+
+```
+// 手动编写的控制器（可修改）
+public class UI_XXXController : UIBaseController
+{
+    // 绑定 UI 组件引用
+    // 业务逻辑方法
+}
+
+// 自动生成的控制器（不可手动修改）
+public class UI_XXXController.AutoGen : ... 
+{
+    // 自动生成的组件绑定代码
+}
+```
+
+### 4. 修改或创建 UI
+
+修改已有 UI：
+1. 提取 Prefab JSON 了解当前结构
+2. 查看对应的 `*Controller.cs` 了解代码逻辑
+3. 修改 Prefab（通过 Unity Editor）或代码
+4. 确保 AutoGen 和手动代码分工明确
+
+创建新 UI：
+1. 在 Unity 中创建 Prefab
+2. 编写对应的 Controller 类（继承 UIBaseController）
+3. 如需自动绑定，编写 AutoGen 辅助类
+4. 注册到 UI 管理系统中
+
+## 不适用场景
+
+- 纯逻辑 UI 改动（不涉及 Prefab 结构变化）→ 直接改 Controller 代码即可
+- 简单的位置/颜色微调 → 无需走完整提取流程，直接描述修改即可
+
+## 属性格式参考
+
+| 类型 | 格式示例 |
+|------|----------|
+| Vector2 | `AnchoredPosition:0,0` |
+| Vector3 | `LocalPosition:0,0,0` |
+| Color | `Color:#RRGGBBAA` |
+| Bool | `RaycastTarget:true` |
+| Enum | `ImageType:Sliced` |
+| 引用 | `Sprite:icon_name` |
+
+## UI 模块索引
+
+```
+GamePlay/UI/
+├── Activity/        # 活动界面
+├── BattlePass/      # 战令
+├── Camp/            # 营地
+├── Character/       # 角色界面
+├── Dispatch/        # 派遣
+├── Draw/            # 抽卡
+├── Legion/          # 军团
+├── LegionBattle/    # 军团战
+├── LegionPve/       # 军团PVE
+├── LevelFight/      # 关卡战斗
+├── Loading/         # 加载界面
+├── Login/           # 登录
+├── Mail/            # 邮件
+├── Package/         # 背包
+├── PVP/             # PVP
+├── Raffle/          # 抽奖
+├── Shop/            # 商店
+├── Story/           # 剧情
+├── Task/            # 任务
+└── Team/            # 编队
+```
+
+## 安全规则
+
+- AutoGen 文件（`*Controller.AutoGen.cs`）不可手动修改
+- Prefab 修改后需要在 Unity 中保存，.meta 文件由 Unity 自动生成
+- 图片资源引用确保路径正确，避免丢失引用
+- UI 变更可能影响多个界面，修改前确认影响范围

.qoderignore

@@ -0,0 +1,124 @@
+# Specify files or folders to ignore during indexing. The same as .gitignore rules, glob patterns like *.log，my-security/ are supported.
+
+
+/[Ll]ibrary/
+/[Tt]emp/
+/[Oo]bj/
+/[Bb]uild/
+/[Bb]uilds/
+/[Ll]ogs/
+/[Uu]ser[Ss]ettings/
+
+# MemoryCaptures can get excessive in size.
+# They also could contain extremely sensitive data
+/[Mm]emoryCaptures/
+
+# Recordings can get excessive in size
+/[Rr]ecordings/
+
+# Uncomment this line if you wish to ignore the asset store tools plugin
+# /[Aa]ssets/AssetStoreTools*
+
+# Autogenerated Jetbrains Rider plugin
+/[Aa]ssets/Plugins/Editor/JetBrains*
+
+# Visual Studio cache directory
+.vs/
+
+# Gradle cache directory
+.gradle/
+
+# Autogenerated VS/MD/Consulo solution and project files
+ExportedObj/
+.consulo/
+*.csproj
+*.unityproj
+*.sln
+*.suo
+*.tmp
+*.user
+*.userprefs
+*.pidb
+*.booproj
+*.svd
+*.pdb
+*.mdb
+*.opendb
+*.VC.db
+
+# Unity3D generated meta files
+*.pidb.meta
+*.pdb.meta
+*.mdb.meta
+
+*.meta
+
+
+
+/Assets/Art/
+/Assets/Art_Out/
+/Assets/Audio/
+/Assets/Video/
+
+
+# Unity3D generated file on crash reports
+sysinfo.txt
+
+# Builds
+*.apk
+*.aab
+*.unitypackage
+*.app
+
+# Crashlytics generated file
+crashlytics-build.properties
+
+# Packed Addressables
+/[Aa]ssets/[Aa]ddressable[Aa]ssets[Dd]ata/*/*.bin*
+
+# Temporary auto-generated Android Assets
+/[Aa]ssets/[Ss]treamingAssets/aa.meta
+/[Aa]ssets/[Ss]treamingAssets/aa/*
+
+#
+.idea/
+*.DS_Store
+
+#HotUpdate
+ProjectNLD/HybridCLRData/AssembliesPostIl2CppStrip/
+ProjectNLD/HybridCLRData/HotUpdateDlls/
+ProjectNLD/HybridCLRData/StrippedAOTDllsTempProj/
+ProjectNLD/HybridCLRData/LocalIl2CppData-WindowsEditor/
+ProjectNLD/Assets/HotUpdateDlls/HotUpdateDll
+ProjectNLD/Assets/HotUpdateDlls/MetaDataDll
+
+#Addressables
+ProjectNLD/ServerData/
+*.tgz
+/Tool/Luban/Datas
+/ProjectNLD/Assets/Editor/SkillEditor/Temp
+/ProjectNLD/Assets/Editor/SkillEditor/Temp.meta
+/ProjectNLD/.cache.meta
+ProjectNLD/Packages/packages-lock.json
+ProjectNLD/Bundles
+ProjectNLD/yoo
+/ProjectNLD/Yoo_Build_Cache
+/ServerConfig
+/ProjectNLD/Assets/Code/OnlyLocal
+/ProjectNLD/Assets/Code/OnlyLocal.meta
+ProjectNLD/HybridCLRData
+ProjectNLD/*.log
+CodeProj
+ProjectNLD/Assets/Code/Scripts/GamePlay
+ProjectNLD/Assets/Code/Scripts/GamePlay.meta
+ProjectNLD/Assets/Code/Scripts/GamePlay_Dll/GamePlay.dll.meta
+ProjectNLD/CLAUDE.md
+ProjectNLD/.claude
+
+# Obfuz/KedrExtension 动态拷入的文件（由 setup_obfuz.sh 管理）
+ProjectNLD/Assets/Editor/KedrExtension/
+ProjectNLD/Assets/Editor/KedrExtension.meta
+ProjectNLD/ProjectSettings/KedrExtensionSettings.asset
+/.qoder
+/OfficialDev
+

AGENTS.md

@@ -9,7 +9,7 @@
 | 引擎 | Unity | C# 脚本后端 |
 | 热更新 | **HybridCLR** | GamePlay 代码编译为独立 DLL（`GamePlay_Dll/GamePlay.dll`），支持运行时热更新 |
 | 配置表 | **Luban** | 游戏参数、数值配置的数据驱动方案，配置源位于 `NLDMisc` 仓库 |
-| 行为树/状态机 | **NodeCanvas** | 位于 `Assets/PhxhSDK/ThirdParty/ParadoxNotion/`，提供 BehaviourTree、FSM、DialogueTree |
+| 行为树/状态机 | **NodeCanvas** | 位于 `ProjectNLD/Assets/PhxhSDK/ThirdParty/ParadoxNotion/`，提供 BehaviourTree、FSM、DialogueTree |
 | 编辑器 | **Odin Inspector** | 用于开发自定义 Inspector 和 EditorWindow |
 | 动画 | **DOTween** | 补间动画库 |
 | 资源管理 | **YooAsset** | 资源打包、加载、热更新 |
@@ -18,7 +18,7 @@
 ## 核心目录速览
 
 ```
-Assets/
+ProjectNLD/Assets/
 ├── Code/Scripts/
 │   ├── GamePlay/          ← 核心战斗逻辑 (75+ 模块，编译为独立 DLL)
 │   ├── Framework/         ← 底层框架代码
@@ -76,6 +76,58 @@ Assets/
 ### 编辑器开发
 - 使用 Odin Inspector 开发自定义编辑器和 Inspector 面板
 
+### 文件落位约定
+新建代码时按以下规则选择落位路径：
+
+| 代码类型 | 落位路径 |
+|---------|---------|
+| 战斗/技能/Buff/AI/角色 | `ProjectNLD/Assets/Code/Scripts/GamePlay/<模块>/` |
+| UI 逻辑（GamePlay 相关） | `ProjectNLD/Assets/Code/Scripts/GamePlay/UI/` |
+| UI 框架层 | `ProjectNLD/Assets/Code/Scripts/UI/` |
+| 底层框架/工具 | `ProjectNLD/Assets/Code/Scripts/Framework/` |
+| 编辑器扩展 | `ProjectNLD/Assets/PhxhSDK/Editor/` |
+| 热更新相关 | `ProjectNLD/Assets/Code/Scripts/HotUpdate/` |
+
+- 不确定归属时优先询问用户
+- 不要修改 `GenCode/` 下 Luban 自动生成的文件
+
+### 性能黄金法则（热路径必查）
+以下规则在 `Update`、`LateUpdate`、`FixedUpdate` 及高频回调中强制要求：
+
+| 禁止 | 替代方案 |
+|------|---------|
+| `GameObject.Find` / `FindObjectOfType` | 预先缓存引用或通过 Manager 注册 |
+| `GetComponent`（每帧调用） | `Awake`/`Start` 中缓存 |
+| `foreach` 遍历集合 | `for (int i = 0; i < list.Count; i++)` |
+| LINQ（`.Where` `.First` `.ToArray`） | 手动循环或提前缓存结果 |
+| lambda / 闭包 | 提取为实例方法或静态方法 |
+| 字符串拼接（`+` 或 `$`） | `StringBuilder`（非每帧可酌情 `$`） |
+| 装箱拆箱 | 避免 `object` 类型转换，使用泛型 |
+| `Instantiate` / `Destroy` | 对象池复用 |
+
+- 声明 `List`/`Dictionary`/`HashSet` 时预分配 `capacity`
+- 事件订阅必须在 `OnDestroy`/`OnDisable` 中取消
+
+### 常见反模式（Agent 容易犯的错）
+
+- ❌ 在 GamePlay 代码中直接引用 `Framework` 层类型（架构越界）
+- ❌ 修改 `Assets/Code/Scripts/GenCode/` 下 Luban 自动生成的文件
+- ❌ 在非主线程访问 Unity API（`Transform`、`GameObject` 等）
+- ❌ 忘记在 `OnDestroy`/`OnDisable` 中取消事件订阅 → 内存泄漏
+- ❌ 在 `while` 循环中无 yield 导致主线程卡死
+- ❌ 协程启动后未管理生命周期（对象销毁后协程继续执行）
+- ❌ 对 Unity 资源使用 `new` 构造（应使用 `Instantiate` 或 `ScriptableObject.CreateInstance`）
+
+### HybridCLR 约束
+GamePlay 代码编译为独立 DLL，受以下限制：
+
+- **禁止** `System.Reflection.Emit` 相关 API
+- 不能依赖主工程中的非 AOT 类型
+- 新增外部库需检查 AOT 兼容性
+- 不要在 GamePlay 代码中引用 `Assembly-CSharp` 中的类型（除非已做 AOT 预留）
+- 使用 `ForceAOT.csproj` / `ScriptsAOT.csproj` 做 AOT 预留注册
+- 修改 GamePlay 代码后必须通过 Unity 菜单编译生成 DLL → 读取 `compile-gameplay-dll` 技能
+
 ## Git 操作
 - 除非用户要求，AI 不做任何 git 提交相关操作
 - 当用户让 AI 操作 git 时提醒用户 git 操作有风险
@@ -83,20 +135,20 @@ Assets/
 
 ## 项目仓库结构
 
-本项目包含三个独立的 Git 仓库，路径相对于 workspace 根目录（ProjectNLD）：
+本项目包含三个独立的 Git 仓库，路径相对于 workspace 根目录：
 
 | 仓库 | 相对路径 | 定位 |
 |------|---------|------|
-| **NLDClient** | `../../` | 游戏客户端主仓库，包含 Unity 项目配置、资源、框架代码等 |
+| **NLDClient** | `.` | 游戏客户端主仓库，包含 Unity 项目配置、资源、框架代码等 |
-| **NLDMisc** | `../../../NLDMisc` | 配置表相关仓库，存放游戏参数、数值配置等数据 |
+| **NLDMisc** | `../NLDMisc` | 配置表相关仓库，存放游戏参数、数值配置等数据 |
-| **GamePlay** | `Assets/Code/Scripts/GamePlay` | 核心游戏逻辑代码仓库，编译产物为 `GamePlay_Dll/GamePlay.dll` |
+| **GamePlay** | `ProjectNLD/Assets/Code/Scripts/GamePlay` | 核心游戏逻辑代码仓库，编译产物为 `GamePlay_Dll/GamePlay.dll` |
 
 - 执行 git 操作时必须明确区分当前操作的是哪个仓库，不要混淆仓库边界
 - 查找或修改代码时注意文件属于哪个仓库，避免在错误的仓库中操作
 
 ## GamePlay 模块速查
 
-`Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块。完整模块索引见 `.ai/agents/default.md`，常用模块：
+`ProjectNLD/Assets/Code/Scripts/GamePlay/` 下 75+ 功能模块。完整模块索引见 `.ai/agents/default.md`，常用模块：
 
 | 模块 | 路径 | 职责 |
 |------|------|------|

CLAUDE.md

@@ -0,0 +1,26 @@
+# NLD Project — Claude Code Instructions
+
+> **通用规则**：请同时遵循 `AGENTS.md`（项目核心规范，含仓库结构、编码要求、git 操作约定等）。
+> **规则协议**：行为规则以 `.ai/protocols/` 为权威定义，具体说明见各 protocol 文件。
+> 本文件仅包含 **Claude Code 专属** 的补充说明，不重复 `AGENTS.md` 中已有的内容。
+
+## 核心行为约束（嵌入自 .ai/protocols/）
+
+以下规则摘自 `.ai/protocols/`，嵌入此处确保 Claude Code 能直接加载：
+
+- **确认再行动**：除非用户要求特别清晰，开始编码前将计划描述给用户并获得确认（收集信息和编写计划不需要确认）
+- **Unity 约定**：不要生成 .meta 文件；不要主动编译项目；可以做静态代码检查
+- **Git 安全**：除非用户要求，不做任何 git 操作；git 操作有风险，须提醒用户；本项目有三个关联仓库，任何 git 操作须读取 `batch-git-ops` 技能后执行
+
+## 技能路径
+- 技能源位于 `.ai/skills/`（同步副本在 `.claude/skills/`）
+- 协议源位于 `.ai/protocols/`（同步副本在 `.claude/protocols/`）
+- 新增或更新后运行 `.ai/sync-all.sh` 同步到各平台
+
+## 编译约定（Claude 专属）
+- 修改 GamePlay 中的 .cs 代码后需通过 Unity 菜单编译生成 DLL
+- Claude 不主动触发 Unity 编译
+
+## 权限边界
+- 参见 `.claude/settings.json` 中的 permissions 配置
+- 禁止执行 `git push --force`、`rm -rf` 等破坏性命令