name: experience-logger
description: 当解决问题或讨论得出结论时，自动将经验和结论按分类记录到对应的 Markdown 文档中。当用户说"记录一下"、"总结经验"、"保存结论"、"归档这个问题"或讨论结束需要保存时使用此 Skill。
license: MIT

经验记录 Skill

核心功能

1. 记录经验：将问题解决方案和结论保存到对应分类文件
2. 查找经验：遇到问题时优先从已有经验中检索相关内容
3. 网络搜索：已有经验未找到时，上网搜索相关资料
4. 动态更新：验证、补充、修正已有经验记录

何时使用

触发记录

• 成功解决了一个技术问题
• 讨论某个话题得出了有价值的结论
• 用户明确要求记录/保存/归档当前内容

触发查找

• 用户遇到技术问题时，优先检索 ~/.copilot/experiences/ 目录
• 用户说"之前是怎么解决的"、"有没有相关经验"、"查一下记录"

触发网络搜索

• 已有经验中未找到相关内容
• 需要获取最新的官方文档或解决方案
• 用户明确要求"上网查一下"、"搜索一下"

触发更新

• 发现已有记录需要补充新信息
• 已有记录的方案有更好的替代方案
• 需要添加新的参考链接或验证结果

触发验证与修正

• 用户反馈"这个方法不行"、"不对"、"有问题"、"过时了"
• 引用经验时发现版本/环境不匹配
• 新记录的经验与已有经验产生冲突
• 用户要求"检查/审查/验证这个经验"

记录存放位置

所有经验记录统一存放在：~/.copilot/experiences/

采用大类文件夹 + 细分文件的二级结构。

分类体系

unity/ - Unity 引擎

csharp/ - C# 语言

shader/ - Shader 开发

git/ - 版本控制

vscode/ - VS Code

python/ - Python

tools/ - 开发工具

general/ - 通用

记录格式

每条记录使用以下格式追加到对应文件：

---

## [简短标题]

**日期**：YYYY-MM-DD  
**更新**：YYYY-MM-DD（如有更新）  
**标签**：#标签1 #标签2  
**状态**：✅ 已验证 | ⚠️ 待验证 | 🔄 已过时 | ❌ 已废弃 | 🔬 实验性  
**适用版本**：[技术名称] X.X+（如适用）

**问题/场景**：

[描述遇到的问题或讨论的场景]

**解决方案/结论**：

[详细的解决方案或得出的结论]

**关键代码**（如有）：

\`\`\`语言
// 相关代码片段
\`\`\`

**参考链接**：

- [官方文档](URL) - 简要说明
- [相关文章](URL) - 简要说明

**验证记录**：

- [YYYY-MM-DD] 初次记录，来源：[实践总结/网络搜索/用户反馈]
- [YYYY-MM-DD] 验证通过/发现问题，补充说明

**相关经验**（如有）：

- [相关经验标题](./path-to-file.md#anchor) - 关联说明

**备注**：

[其他补充说明]

操作步骤

一、查找已有经验（优先执行）

当用户遇到问题时，首先执行以下步骤：

1. 判断问题领域：确定应该检索哪个分类目录
2. 读取相关文件：读取对应分类的 md 文件内容
3. 搜索匹配记录：根据关键词、标签查找相关经验
4. 呈现给用户：
5. 如果找到相关记录，展示内容并询问是否适用
6. 如果未找到，转入"网络搜索"步骤
7. 验证有效性：根据当前情况判断记录是否仍然有效

二、网络搜索（经验未找到时）

当已有经验中未找到相关内容时，执行以下步骤：

1. 告知用户："未在经验记录中找到相关内容，正在上网搜索..."
2. 构建搜索关键词：根据问题提取核心关键词
3. 执行网络搜索：使用 #fetch 工具搜索相关资料
4. 优先搜索来源（按优先级）：
5. 官方文档（Unity Docs、Microsoft Docs、MDN 等）
6. 官方论坛/讨论区
7. Stack Overflow
8. 知名技术博客
9. 整理搜索结果：
10. 提取关键信息和解决方案
11. 记录参考链接来源
12. 标注信息的时效性（发布日期/版本）
13. 呈现给用户：展示搜索到的解决方案
14. 询问是否记录：如果解决了问题，询问是否将此经验记录下来

三、记录新经验

1. 同步仓库：执行"仓库同步流程"中的"拉取最新"步骤
2. 识别内容：判断当前对话中是否有值得记录的经验或结论
3. 确定分类：根据内容主题选择对应的分类文件
4. 检查重复：查看目标文件中是否已有类似记录
5. 如有类似记录，转为"更新"操作
6. 如无类似记录，执行"新增"操作
7. 提取要点：
8. 简短标题（一句话概括）
9. 问题/场景描述
10. 解决方案/结论
11. 关键代码片段（如有）
12. 相关标签
13. 参考链接（尽量提供官方文档或可信来源）
14. 格式化内容：按照上述模板格式化
15. 追加写入：将内容追加到对应分类文件末尾
16. 推送更改：执行"仓库同步流程"中的"提交推送"步骤
17. 确认反馈：告知用户已记录到哪个文件，并确认已同步到远程仓库

四、更新已有经验

当发现已有记录需要更新时：

1. 同步仓库：执行"仓库同步流程"中的"拉取最新"步骤
2. 定位记录：找到需要更新的经验条目
3. 判断更新类型：
4. 补充：添加新的信息、代码示例、参考链接
5. 修正：纠正错误或过时的内容
6. 标记过时：将状态改为 🔄 已过时，并说明原因
7. 执行更新：
8. 更新"更新日期"字段
9. 在"验证记录"中添加本次验证/更新说明
10. 修改相应内容
11. 推送更改：执行"仓库同步流程"中的"提交推送"步骤
12. 反馈用户：说明更新了什么内容，并确认已同步到远程仓库

五、经验验证与修正

对已记录的经验进行正确性判断和修正，确保知识库的准确性和时效性。

触发验证的场景

判断经验正确性的流程

flowchart TB
    A[引用/审查经验] --> B{初步判断}
    B -->|明显过时| C[标记待验证]
    B -->|可能有问题| D[执行验证]
    B -->|看起来正确| E[正常使用]

    D --> F{验证方式}
    F -->|版本相关| G[检查官方文档/更新日志]
    F -->|代码相关| H[分析代码逻辑/运行测试]
    F -->|最佳实践| I[搜索最新社区讨论]

    G --> J{验证结果}
    H --> J
    I --> J

    J -->|正确有效| K[确认状态: ✅ 已验证]
    J -->|部分正确| L[执行修正流程]
    J -->|完全错误| M[执行废弃/重写流程]

    C --> D
    E --> N[继续使用]
    K --> N
    L --> O[更新记录]
    M --> P[标记过时/重写]

验证方法

1. 上下文对比验证
2. 检查经验记录的日期和适用版本
3. 对比用户当前使用的技术栈版本

4. 判断核心 API 或方法是否仍然存在

5. 官方文档验证

6. 查阅相关技术的官方文档
7. 检查是否有 Breaking Changes 或 Deprecation 警告

8. 确认推荐的最佳实践是否改变

9. 实践验证

10. 如果用户提供了具体错误信息，分析原因
11. 根据错误信息判断是经验本身的问题还是使用场景不同

12. 必要时建议用户进行简单测试验证

13. 社区验证

14. 搜索相关技术的最新讨论
15. 检查是否有更优的替代方案
16. 了解常见的踩坑点和注意事项

修正流程

根据验证结果，采取不同的修正策略：

1. 小幅修正（内容基本正确，需要补充或微调）

**操作步骤**：
1. 保留原有内容结构
2. 在需要修正的部分添加更正说明
3. 更新"更新日期"字段
4. 在"验证记录"中添加修正说明
5. 状态改为 ✅ 已验证

**示例**：
验证记录：
- [2024-01-29] 修正：原方案在 Unity 2022+ 需要额外配置 xxx，已补充说明

2. 重大修正（核心方案有误或有更好替代）

**操作步骤**：
1. 将原方案内容移至"历史记录"部分（不删除，保留参考）
2. 在正文添加新的正确方案
3. 明确标注新旧方案的区别和适用场景
4. 更新状态为 ✅ 已验证
5. 在"验证记录"中详细说明修正原因

**格式示例**：
---
**解决方案/结论**：

**[当前推荐方案]**
[新的正确方案内容]

<details>
<summary>📜 历史方案（已废弃）</summary>

**原方案**（适用于 Unity 2020 及之前版本）：
[原有内容]

**废弃原因**：Unity 2021 后 API 变更，原方法已被标记为 Obsolete

</details>

3. 完全废弃（经验完全错误或已无参考价值）

**操作步骤**：
1. 状态改为 🔄 已过时 或 ❌ 已废弃
2. 在标题后添加 [已废弃] 标记
3. 在开头添加醒目的废弃警告
4. 说明废弃原因和替代方案（如有）
5. 保留内容不删除，以供历史参考
6. 在"验证记录"中记录废弃决定

**格式示例**：
---
## [标题] [已废弃]

> ⚠️ **此经验已废弃**  
> 废弃原因：[具体原因]  
> 替代方案：参见 [新经验标题](#链接) 或 [官方文档](URL)

用户反馈处理

当用户表示经验有问题时的处理流程：

1. 收集信息：
2. 询问具体出了什么问题（错误信息、异常行为等）
3. 确认用户的技术环境（版本、平台等）

4. 了解用户的具体使用场景

5. 分析问题：

6. 判断是经验本身错误还是场景不适用
7. 检查是否是版本差异导致的问题

8. 确认是否有遗漏的前置条件

9. 采取行动：

10. 如果经验有误：执行相应的修正流程
11. 如果场景不适用：补充适用条件说明

12. 如果是版本问题：添加版本兼容性说明

13. 反馈确认：

14. 告知用户分析结果和处理方式
15. 提供正确的解决方案
16. 询问是否解决了用户的问题

经验质量标记

为了更好地管理经验的可信度，使用以下扩展标记：

冲突检测与处理

当新记录的经验与已有经验存在矛盾时：

1. 检测冲突：
2. 在记录前搜索相关主题的已有经验
3. 比较核心结论是否一致

4. 识别可能的版本差异或场景差异

5. 处理策略：

6. 场景不同：两条经验都保留，明确标注各自适用场景
7. 版本差异：标注版本适用范围，新版本方案作为推荐

8. 真正冲突：验证后保留正确的，修正或废弃错误的

9. 关联处理：

10. 在相关经验间添加互相引用链接
11. 说明不同方案的适用条件
12. 帮助后续查找时快速判断

六、处理大型内容 (Large Content Handling)

当经验内容非常丰富（如完整的设计文档、架构图解、长篇复盘）时，不应直接全部堆积在汇总文件中，而应采用摘要 + 独立文档的策略。

触发条件

• 内容长度超过 50 行
• 包含大量图表代码（如 Mermaid 流程图）
• 属于完整的技术方案、API 文档或架构设计
• 用户明确要求保存为独立文档

处理流程

1. 同步仓库：执行"仓库同步流程"中的"拉取最新"步骤
2. 创建独立文档：
3. 命名规范：[分类]/docs/[英文_下划线_命名].md
4. 例如：unity/docs/VR_Variant_Collector_Architecture.md
5. 内容：包含完整的所有细节、代码和图表
6. 编写摘要记录：
7. 在主分类文件（如 unity/shader.md）中添加一条标准记录
8. 内容：仅保留背景、核心结论和关键点
9. 关键步骤：在记录末尾添加详细文档链接，指向刚才创建的独立文档
10. 链接格式：- [文档标题](./docs/filename.md)
11. 推送更改：执行"仓库同步流程"中的"提交推送"步骤
12. 确认反馈：告知用户已同步到远程仓库

七、仓库同步流程

为确保多设备间经验记录的一致性，在执行记录或更新操作时，需要先同步仓库。

拉取最新（保存前执行）

在修改任何经验文件之前，先执行以下步骤：

1. 进入仓库目录：
   bash cd ~/.copilot
2. 检查工作区状态：
   bash git status
3. 如有未提交的本地更改：
   • 询问用户是否先提交当前更改
   • 或使用 git stash 临时保存更改
4. 拉取远程更新：
   bash git pull origin main
5. 如果遇到冲突，提示用户手动解决
6. 如果拉取失败（如网络问题），告知用户并询问是否继续本地操作
7. 确认同步结果：告知用户仓库同步状态（已更新到最新 / 本地已是最新）

提交推送（保存后执行）

在完成经验记录的编辑后，执行以下步骤：

1. 暂存更改：
   bash git add .
2. 提交更改：
   bash git commit -m "update: [简要描述本次记录的内容]"
3. 提交信息示例：update: 添加 Unity 协程优化经验
4. 推送到远程：
   bash git push origin main
5. 如果推送失败，尝试先拉取再推送
6. 如果持续失败，告知用户具体错误并建议手动处理
7. 确认推送结果：告知用户更改已同步到远程仓库

异常处理

示例

示例 1：查找已有经验

用户："Unity 协程怎么正确等待一帧？"

操作：
1. 判断为 Unity C# 相关 → 读取 unity/csharp.md
2. 搜索关键词"协程"、"yield"、"等待"
3. 找到相关记录 → 展示给用户
4. 反馈："在经验记录中找到相关内容，建议使用 yield return null..."

示例 2：经验未找到，上网搜索

用户："Unity DOTS 的 IJobEntity 怎么用？"

操作：
1. 判断为 Unity 相关 → 读取 unity/csharp.md
2. 搜索关键词"DOTS"、"IJobEntity"、"Job"
3. 未找到相关记录
4. 告知用户："未在经验记录中找到相关内容，正在上网搜索..."
5. 搜索 Unity 官方文档关于 DOTS/IJobEntity 的内容
6. 整理搜索结果并展示解决方案
7. 询问："问题解决了吗？需要将此经验记录下来吗？"

示例 3：记录新经验

用户："帮我记录一下刚才解决的 Unity 协程问题"

操作：
1. 执行 git pull origin main 拉取仓库最新内容
2. 识别为 Unity C# 脚本相关 → 归类到 unity/csharp.md
3. 检查是否有类似记录 → 无
4. 提取关键信息：
- 标题：Unity 协程中使用 yield return null 替代 yield return 0
- 问题：协程中使用 yield return 0 导致性能问题
- 解决：使用 yield return null 更高效
- 参考链接：Unity 官方文档链接
5. 追加到 ~/.copilot/experiences/unity/csharp.md
6. 执行 git add . && git commit -m "update: 添加 Unity 协程优化经验" && git push origin main
7. 反馈："已将协程优化经验记录到 unity/csharp.md，并已同步到远程仓库"

示例 4：更新已有经验

用户："刚才那个协程问题，我发现还有个注意点要补充"

操作：
1. 执行 git pull origin main 拉取仓库最新内容
2. 定位到 unity/csharp.md 中的协程相关记录
3. 判断为"补充"类型更新
4. 添加更新日期、新增内容
5. 在"验证记录"中添加说明
6. 执行 git add . && git commit -m "update: 补充协程经验的注意点" && git push origin main
7. 反馈："已更新 unity/csharp.md 中的协程经验记录，并已同步到远程仓库"

示例 5：处理大型架构文档

用户："把这个 VR 变体收集器的完整设计文档保存下来"

操作：
1. 执行 git pull origin main 拉取仓库最新内容
2. 识别为大型内容，同时也属于 Unity Shader 领域
3. 创建独立文件：~/.copilot/experiences/unity/docs/VR_Variant_Collector.md，写入完整内容
4. 在 unity/shader.md 中追加记录：
- 标题：VR Shader 变体收集器架构
- 结论：摘要核心的打包策略和编译坑点
- 链接：- [完整架构文档](./docs/VR_Variant_Collector.md)
5. 执行 git add . && git commit -m "update: 添加 VR 变体收集器架构文档" && git push origin main
6. 反馈："已将架构文档主要内容归档，完整细节保存于独立文档中，并已同步到远程仓库"

示例 6：验证并修正错误经验

用户："你之前记录的那个 Unity 协程用 yield return 0 的说法好像不对，我试了报错"

操作：
1. 定位到 unity/csharp.md 中的协程相关记录
2. 分析用户反馈：收集错误信息和 Unity 版本
3. 验证经验正确性：
- 查阅 Unity 官方文档确认 yield return 的正确用法
- 发现原记录确实有误，正确写法应该是 yield return null
4. 执行修正流程：
- 更新解决方案内容为正确写法
- 添加版本说明和注意事项
- 在"验证记录"中记录：[2024-01-29] 修正：yield return 0 在某些版本会有问题，统一改为 yield return null
- 状态保持 ✅ 已验证
5. 推送更改并反馈用户修正结果

示例 7：处理经验冲突

用户："我发现有两个地方说的不一样，一个说用 async/await 好，一个说用协程好"

操作：
1. 定位到相关的两条经验记录
2. 分析冲突原因：判断是场景不同还是信息错误
3. 发现是适用场景不同：
- 协程适合：需要等待帧、物理更新、UnityWebRequest 等 Unity 特有异步
- async/await 适合：纯计算、文件 IO、网络请求等不依赖 Unity 主线程的场景
4. 执行关联处理：
- 在两条经验中添加"相关经验"链接，互相引用
- 明确标注各自的适用场景
- 添加备注说明两者的选择依据
5. 推送更改并反馈用户分析结果

示例 8：废弃过时经验

用户："这个 WWW 类的用法是不是过时了？"

操作：
1. 定位到使用 WWW 类的经验记录
2. 验证：查阅 Unity 官方文档，确认 WWW 类已在 Unity 2018.3 后被标记为 Obsolete
3. 执行废弃流程：
- 标题后添加 [已废弃] 标记
- 状态改为 🔄 已过时
- 在开头添加警告提示
- 添加替代方案说明：推荐使用 UnityWebRequest
- 验证记录添加：[2024-01-29] 标记废弃：Unity 2018.3+ 应使用 UnityWebRequest 替代
4. 推送更改并反馈用户

注意事项

记录规范

• 如果目标文件不存在，先创建文件并添加标题头
• 每条记录之间用 --- 分隔
• 标签使用 # 前缀，便于后续搜索
• 日期使用 ISO 格式 (YYYY-MM-DD)
• 代码片段保持简洁，只记录关键部分
• 如果用户没有明确分类，根据内容自动判断

参考链接规范

• 优先官方文档：Unity 官方、Microsoft Docs、MDN 等
• 标注链接用途：简要说明该链接提供什么信息
• 验证链接有效性：如果发现链接失效，标记并尝试找替代
• 版本敏感内容：标注适用的版本范围（如 Unity 2021+）

状态标记说明

查找优先级

遇到问题时按以下顺序处理：
1. 优先搜索 ~/.copilot/experiences/ 中的已有经验
2. 如果未找到，上网搜索相关资料（官方文档优先）
3. 整理解决方案并呈现给用户
4. 解决后询问是否需要记录到经验库

网络搜索策略

• 搜索时机：已有经验未找到相关内容时自动触发
• 搜索优先级：官方文档 > 官方论坛 > Stack Overflow > 技术博客
• 结果处理：整理关键信息，保留参考链接，标注版本/日期
• 记录建议：搜索到有价值内容后，主动询问是否记录

文件头模板

新建分类文件时，使用以下头部：

# [分类名称] 经验记录

> 自动记录的问题解决经验和技术结论，便于后续参考。

---