From f9af7c4f14739b4c28404b03ec4e26faef37650d Mon Sep 17 00:00:00 2001
From: bottlefish <781230111@qq.com>
Date: Thu, 26 Feb 2026 17:15:03 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B7=BB=E5=8A=A0=20Cursor=20?=
=?UTF-8?q?=E9=A1=B9=E7=9B=AE=E8=A7=84=E5=88=99=E5=92=8C=E6=8A=80=E8=83=BD?=
=?UTF-8?q?=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.cursor/rules/yarn-localization.mdc | 31 +++++++++
.../skills/yarn-dialogue-role-config/SKILL.md | 68 +++++++++++++++++++
2 files changed, 99 insertions(+)
create mode 100644 .cursor/rules/yarn-localization.mdc
create mode 100644 .cursor/skills/yarn-dialogue-role-config/SKILL.md
diff --git a/.cursor/rules/yarn-localization.mdc b/.cursor/rules/yarn-localization.mdc
new file mode 100644
index 000000000..e12efa070
--- /dev/null
+++ b/.cursor/rules/yarn-localization.mdc
@@ -0,0 +1,31 @@
+---
+description: YARN 修改时保留本地化信息 #line
+globs: "**/*.yarn"
+alwaysApply: false
+---
+
+# YARN 本地化标识符保护
+
+修改 YARN 对话文件时，**不要动任何 `#line:` 相关的内容**。
+
+## 说明
+
+`#line:` 后跟的哈希值（如 `#line:018dc78`）是 YARN Spinner 的本地化行标识符，用于与 `*_zh-Hans.asset` 等本地化资源文件关联。修改或删除会导致：
+
+- 已有翻译无法正确匹配
+- 本地化系统失效或错乱
+- 需要重新导出/重新翻译
+
+## 格式示例
+
+```
+me: 我需要看看情绪信号在【滤波器】处理时发生了什么 #line:046cf9e
+->开始追踪情绪信号 #line:0443e38
+Task: 检查滤波器处理链路 #line:018dc78
+```
+
+## 修改规则
+
+- **可修改**：对话内容、节点标题、命令、选项文本
+- **不可修改**：`#line:xxxxxxxx` 整段、其位置、哈希值
+- 新增行或节点：不要手动添加 `#line`，留给 YARN Spinner 工具自动生成
diff --git a/.cursor/skills/yarn-dialogue-role-config/SKILL.md b/.cursor/skills/yarn-dialogue-role-config/SKILL.md
new file mode 100644
index 000000000..8052d3b31
--- /dev/null
+++ b/.cursor/skills/yarn-dialogue-role-config/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: yarn-dialogue-role-config
+description: Use when 配置对话角色、新增 role、添加 Yarn 角色、character.csv、为模块配置角色、对话 speaker. Guides adding entries to character.csv and using the Key in Yarn dialogue files.
+---
+
+# Yarn 对话角色配置
+
+为项目新增对话角色时，需要同时配置 `character.csv` 和在 Yarn 文件中使用对应的 speaker。
+
+## 1. character.csv 新增一行
+
+路径：`Assets/StreamingAssets/Config/character.csv`
+
+CSV 列（从左到右）：
+
+| 列 | 说明 | 示例 |
+|----|------|------|
+| Key | **必填**，Yarn 中作为 speaker 的 key，需与 Yarn 内完全一致 | `SaleModule` |
+| Cn | 显示名，支持 `
` 换行 | `销售型
销售语言处理模块` |
+| (第3列) | 英文/备用名，可空 | |
+| DialogViewType | 显示位置：`Default`、`Screen`、`OldBox`、`CenterText`、`CenterOption` 等 | `Default` 或 `Screen` |
+| Role | 人物角色：`Player`、`MainActor`、`Aside` | `Aside` |
+| NameColor | 名称颜色，如 `#F56C6C`，可空 | |
+| HeadPicPath | 头像路径，可空 | |
+| VoicePath | 语音路径，如 `VO/voice_XX`，可空 | |
+| BubbleIdx | 气泡序号，默认 0 | |
+
+参考现有行格式，插入到合适位置（如与其他模块角色放一起）。
+
+## 2. Yarn 中使用
+
+对话行格式：`Key: 对话内容`
+
+```
+SaleModule: 已与销售模块建立连接！
+SaleModule: 信号接受正常，信号来源：
+```
+
+Key 必须与 character.csv 中的 Key 完全一致，否则会按 key 原样显示或找不到配置。
+
+## 3. 修改 Yarn 时的注意
+
+- 遵循 `.cursor/rules/yarn-localization.mdc`：**不要动 `#line:` 及哈希值**
+- 可改：对话内容、 speaker key、节点标题
+- 不可改：`#line:xxxxxxxx` 整段
+- 新增行：不手动写 `#line`，由 YARN Spinner 自动生成
+
+## 4. 完整示例
+
+为「销售模块」新增专用角色：
+
+**character.csv 新增：**
+```csv
+SaleModule,销售型
销售语言处理模块,Sales type sales language processing module,Screen,Aside,#F56C6C,,,
+```
+
+**Yarn 中替换/使用：**
+```
+SaleModule: 已与销售模块建立连接！
+SaleModule: 信号接受正常，信号来源：
+SaleModule: 情绪模块，逻辑模块
+```
+
+## 5. 本地化
+
+修改 speaker 后，`*_zh-Hans.asset` 等本地化文件中的旧 key 可能仍存在。可：
+- 在 Unity 中重新导入 Yarn 项目的 String Table
+- 或手动更新对应条目中的角色名