首页 / 资料归档 / xcmskills 技能包

xcmskills 技能包

这个站点是给人看的，技能包是给 AI 看的—— 同一份知识的两种载体。
装上之后，任何一个 Claude 会话在这套工程里干活时会自动加载它， 不用每次重新解释「这个项目 compile 是怎么回事」。

已安装 SKILL.md + 7 篇 references 约 1200 行

1. 装在哪

C:\Users\zhaozibo\.claude\skills\xcmskills\
├─ SKILL.md                        ← 主文件，会话开始时被读进上下文
└─ references\
   ├─ architecture.md              分层 / 单例 / ECS / 事件 / Tick / 协议
   ├─ modules.md                   八大模块的链路与关键位置
   ├─ pitfalls.md                  18 条真实踩过的坑 + 排查方向速查
   ├─ debugging.md                 开局五问 / 日志 / 定位手法
   ├─ adding-features.md           加字段七步 / 加 UI / 重构判断 / 边界纪律
   ├─ build-and-commit.md          编译流水线 / lint 规则 / 提交自查 / 开分支
   └─ interview.md                 五个完整故事 + 关键数字速记
为什么拆成 SKILL.md + references Claude 加载技能时只把 SKILL.md 读进上下文， references/ 是按需读取的。
所以 SKILL.md 只放「必须先知道的规矩」和「去哪找细节」的索引， 细节全部下沉到 references，不占默认上下文。

2. 它管什么

SKILL.md 的 description 决定了它什么时候被激活：

---
name: xcmskills
description: UE5 + puerts 客户端八大模块的领域知识与工作纪律。
  当在 c:\zhaozibo_070\Source\Client\TypeScript 这套工程里排查 bug、加功能、
  重构、review 代码、准备面试讲项目时使用；也适用于任何 UE5 + TypeScript(puerts)
  + WorldPartition + MVC 架构的同类工程。
---

最后半句是故意加的——换工作 / 换项目之后， 架构类的知识（弱引用回调、Tick 阶段、隐藏类）还是通用的。

3. SKILL.md 正文结构

章内容为什么放在主文件
一、三条硬规矩自己跑 compile（含「0 错误 ≠ 真 emit」）、守需求边界、CRLF + 2 行注释 每次干活都要遵守，不能等它去翻 reference
二、架构速记三大单例 + Model 可空 / Controller 非空的原因、Tick、弱引用回调 写任何一行代码都用得上
三、开局五问必现/偶现、前置条件、固定时长、现象还是结论、能否缩小范围 拿到 bug 的第一动作，晚了就已经扎进代码了
四、八大模块索引每个模块一句话 + 对应的站点页 快速定位是哪个模块的事
五、十个反复咬人的坑按咬过几次排序，第 1 条是「grep 有没有第二套实现」 最高频的返工来源
六、加功能标准路径加字段七步、控件索引是位置不是名字、定时器越界静默 常用
七、提交前自查压缩到最容易漏的六条 收尾必做

4. 写进技能包的十条纪律

这些是从实际协作中反复纠正出来的，不是凭空定的规范：

改完自己跑 compile
tsc 不算。自定义编译器还会跑顶层声明、PascalCase、11 条自定义规则。 多文件先 npm run lint-fix——本地过了不等于自动测试过。
「0 错误」要 grep 产物确认
全项目诊断失败会在 emit 前退出，磁盘 .js 可能压根没更新。 卡住用 compile-skip-diagnostic。
永远 CRLF
Write 整文件时保留，禁止把已有文件改成 LF。否则 diff 全是噪声，review 没法看。
注释最多 2 行
少字、会总结。抽出来的命名常量必须有中文 JSDoc 说明含义和用途。
Log 带模块前缀
传送类必须带「传送」，结算类带「副本结算」。 复测时只按关键字过滤，没前缀等于没打。
守需求边界
开工前列 in-scope / out-of-scope 路径，每次 edit 对照。 说了「Y 不动」就别顺手改 Y。发现问题说出来但不动手。
Game 层禁止 import UniverseEditor
只能 UniverseEditor/Interface。 要数据让业务方查表后传参。
Scheme export 一个文件一个
共用一个 .ts 运行时 puerts 报 can not find XxxScheme。
p4 不加 lock
edit / resolve 不要顺手 lock，会挡住别人。 发现已锁立即 unlock。
编辑器代码走 gulp
Src/UniverseEditor/ 不走 npm compile，产物在 JavaScript_Raw。 导表工具是 ConfigTool.Gui.exe 不是 Excel 宏。

5. references/pitfalls.md 里的十八条

技能包里最有价值的一篇。每条都是真实发生过的，按「咬过几次」排序：

#坑沉淀出的铁律
1同一个 action 注册了 player / entity 两套实现 改任何 action 先 grep 有没有第二个注册点
2SetResultCallback 是覆盖语义，上游回调被下游冲掉 黑屏残留先查回调有没有被覆盖，别扎渲染帧
3WP IsStreamingCompleted 假阳性（Activated ≠ collision build 完） 等流送要有超时放行 + 贴地预检
4Once 监听被过场关卡的同名事件提前消费 Once 注册前问「我等的事件到来前还有别人发吗」
5IsStreamingLevel 漏复位，之后跨图传送必卡 每个新状态标志检查所有出口
6REVIVE 分支提前 return，漏发 LoadDone 提前 return 前看它跳过了哪些收尾
7同帧 Spawn 包围盒全零（不是 API 参数错） 假设被证伪要回到现象重推，别在错假设上加补丁
8RegisterAvatar 复用句柄不更新 characterId 「有则复用」的缓存，复用分支必须处理入参变化
9编辑用 dungeonScheme、校验用 levelPlayScheme 报字段非法先查两边 scheme 是否一致
10跨关卡复制实体只 SetFolderPath 没迁 ULevel —
11Seq 资产缺失静默失败，被误报成 SetActorVisible 失效 QA 报结论时翻回现象；资产接口失败常不报错
12遮罩 1 帧就关，但相机碰撞 2s 后才恢复 遮罩关闭时机对齐最后一个恢复项
13loadscene 关卡自带后处理盖全屏 loading 画面异常先查 loadscene 的后处理 actor
14新 entity 被 RemoveRoleEntities 连坐清掉 看到超时先确认它等的东西是不是被提前销毁了
15ProxyActors 站位序 vs UI 成员序共用下标 两个列表来源不同就不能共用下标
16死亡溶解 / VisibilityLock 在某条路径上漏清 引用计数式的 lock 要有「强制归零」兜底入口
17GetDisplayTime 无视 status 一律按墙钟推进 只有 Running 才加 timeDiff
18定时器 [20, 90000] 越界静默返回 undefined 拿到 handle 要判空

完整版（含现象 / 根因 / 修法）在 references/pitfalls.md，网页版在 Bug 案例大全。

6. 站点和技能包，什么时候用哪个

用站点
· 系统学习某个模块
· 面试前复习（问答库有分级和完整答案）
· 查协议号、查配置字段
· 需要图、表、流程图
· 给别人看 / 交接
优势：全站搜索、交叉链接、信息密度高
用技能包
· 让 AI 帮你改这套代码
· 让 AI 排查 bug（它会先走开局五问）
· 让 AI review 你的改动（它知道 CRLF、注释长度、边界纪律）
优势：自动加载，不用每次重新解释项目背景
两边要一起改 站点和技能包是同一份知识。发现新的坑、定下新的规矩，两边都要补—— 只补站点，AI 下次还会犯；只补技能包，自己复习时找不到。
建议：先补技能包的 references/pitfalls.md（快）， 再同步到 Bug 案例大全（详细）。

7. 怎么维护

1
修完一个非平凡的 bug，问自己「这是第几次栽在同一类问题上」
第一次就记下来。到第二次才记，中间那次返工就白费了
2
写进 references/pitfalls.md，格式固定
现象 → 根因 → 修法 → 沉淀出什么铁律。 「沉淀」那一行最重要——没有它就只是个 bug 记录，不是知识
3
如果它值得每次都提醒，才上提到 SKILL.md 第五章
主文件要克制。什么都往里塞等于什么都没强调
4
同步到站点的 Bug 案例大全，补 search-index 条目
网页版写详细：代码片段、日志证据、时序图
协议号会过时 技能包里写了具体协议号（15512、14716 等）。 这些**会随着代码变化而失效**。
定期核对，或者在数字旁边标注「以 协议总索引 为准」—— 就像 归档页处理旧文档那样， 维护一个单一事实源比到处更新便宜得多。

8. 换项目还能用什么

八大模块的细节带不走，但这些能：

可迁移的为什么通用
开局五问任何 bug 都适用，尤其「固定时长 → grep 那个数字」和「现象 vs 结论」
任何等待必须有超时 + 降级放行分布式 / 异步系统的普适规则
状态标志检查所有出口包括提前 return，这是最常见的漏
改前先 grep 有没有第二处实现任何有一定规模的代码库都会有重复注册
假设被证伪要回到现象重推调试方法论
覆盖语义 vs 叠加语义回调注册接口的通用设计问题
先划范围外再动手项目管理，不是技术
弱引用回调要写成稳定引用的实例属性任何有事件系统的框架
V8 隐藏类 / 内联缓存任何跑 JS 的地方
给非程序写文档要带「现象→原因→改哪」速查表协作方法
相关：重构与加功能指南 · Bug 案例大全 · 排查与调试手册 · 面试问答库 · 历史文档归档