mcdk-tracy-profiling

name	mcdk-tracy-profiling
description	用 mcdk-mcp-tracy 对运行中的网易我的世界基岩版 MOD 做函数级性能监测：经游戏内嵌原生 Tracy server（TCP 8086）采集每个函数的 CPU 耗时，定位热点，并用前后 diff 毫秒级量化优化收益。做性能 review、排查卡顿、验证优化效果时使用。

MCDK Tracy 性能监测工作流

mcdk-mcp-tracy 从游戏内嵌的原生 Tracy server（TCP 8086）抓一小段 trace，归约成每个函数的耗时排行（self / total / calls），配合前后 diff 量化优化收益。原始数据在服务端归约，agent 只看 top-N 与 diff。

前置条件

1. 游戏在运行，原生 Tracy server 监听 8086（通过MCDK/MCStudio启动的ModPC均可）。
2. bin/tracy-capture.exe、bin/tracy-csvexport.exe 存在，版本与游戏内嵌 Tracy 一致（当前 v0.11.1）。
3. 仅 tracy_jank_fps 需要游戏由 mcdk.exe 启动且 .mcdev.json 的 mcp_server_config.enabled=true；函数耗时抓取不经 MCDK。

核心原则

• 先探针后采样：tracy_status 确认 native_tracy.reachable=true、bin_present=true 再动手。
• 采样前先和用户对齐时长与场景：负载要用户亲自在游戏里触发，约定好了、用户就位了再开采（见推荐流程第 2 步）。
• 采样窗口内制造真实负载：让游戏跑代表性玩法；Tracy 只记录窗口内实际执行的 zone，静止难以抓取性能高消耗的部分。
• 用 name_contains 聚焦 MOD：函数显示为 "函数名 @ 源文件"，按脚本包前缀（如 MyModScripts）过滤；过滤只影响 inline 返回，全量仍存进 capture。
• 结论用 diff 说话：优化前后各采一次、打不同 label，tracy_diff_captures 量化收益，不凭感觉。
• 改代码前必须用户拍板：先交热点报告 + 优化计划（见下），用户选了哪条才改哪条，不要未经确认就动代码。

推荐流程

1. tracy_status() —— 失败看 reason/hint（8086 不可达 → 游戏没起/端口不对；bin_present=false → 缺 CLI）。
2. 询问用户本次采样时长与场景，等用户确认就位后再开采：
   • 时长：10 秒（瞬时逻辑：开 UI、放技能、单次交互）／30 秒（常规玩法循环、跑图）／60 秒（长周期系统：定时器波次、偶发卡顿复现）／自定义（上限 60）。
   • 场景：请用户描述准备触发什么（跑图、刷实体、开打、跑机器……），首次使用顺带确认脚本包前缀（供 name_contains）。
3. 用户就位 → tracy_native_capture(seconds=<约定时长>, name_contains="MyMod", label="before") —— 返回空看 warning（多半是窗口内没负载）。
4. 在对话正文完整输出热点报告（必做，格式见下节）：方案按 A/B/C（或 1/2/3）编号，结尾请用户直接在聊天框回复编号（如"A+C"）选定要做哪几条；禁止调用 AskUserQuestion 等选项弹窗工具收集选择。
5. 按用户选择改热点函数 → 必要时用 game-testing MCP 的 reload_addon_and_game 热重载 → 同样场景、同样时长再抓 label="after"。
6. tracy_diff_captures(base_id=<before>, new_id=<after>, metric="self") —— 目标函数应在 improved 且 delta_ms 为负；总体看 summary.pct，向用户回报实际省了多少毫秒。
7. 可选：tracy_jank_fps(action="sample_fps") 前后对比 FPS 百分位（此工具经 MCDK，MCStudio不可用）。

热点报告格式（第 4 步必做）

硬性要求：报告是对话正文，不用弹窗——下面 ①②③ 必须作为可读的正文消息完整输出（分析写在内部思考里不算输出）；不要调用 AskUserQuestion 之类的选项弹窗工具，选择环节就是正文末尾一句"回复编号即可"。

① 热点排行：top 5~10 表格 —— 函数名｜self_ms｜calls｜每帧均摊（self_ms÷frames）｜单次均摊（self_ms÷calls），注明窗口 frames 与总 self_ms。均摊值比总量更能说明严重程度（例：每帧 >1ms 的单个 MOD 函数已值得警惕）。

② 优化计划：先读排行对应的 MOD 源码再给方案，每条标注编号（A、B、C……），包含四项：

字段	内容
热点与根因	哪个函数、贵在哪：调用次数过多 / 单次太贵 / 这逻辑根本不该每帧跑
优化手段	具体怎么改：缓存、降频、事件化替代轮询、挪出主循环、批处理……优先套用下节参考库里的成熟模式
预期收益	估算省多少 ms／占本次采样的百分比（基于数据推算，标注"估算"）
风险与改动量	低/中/高 + 原因：改动范围、是否动底层接口或公共模块、是否影响向下兼容

③ 按性价比排序：改动小且收益高的排最前；改动大、要动底层、可能影响向下兼容而收益又小的排最后。列完即停，请用户回复编号（如"A+C"／"全做"）决定做哪几条。

优化模式参考库（写方案前按症状查阅）

具体实操模式放在本技能目录 references/ 下，写优化计划前按需读对应文件（不必全读）：

参考文件	内容	何时读
references/general-practice.md	通用优化模式：组件全局缓存、降频+加盐+质数间隔、事件化（含 ModAttr 同步 Molang）、分帧、单播替代广播、Python 微优化、批量方块原生接口（调色板）、配置内存与加载	任何 MOD 的 tick / 组件创建 / 通信类热点，以及批量摆方块尖峰 / 启动慢 / 内存高
references/advanced-practice.md	大型玩法类 MOD 实战模式（Tracy 实测验证）：负缓存、脏驱动 O(dirty)、值比对早退、句柄缓存、同 tick 快照短路、有序调度池（定时器二分插入）、lazyTick 分频、frame-drain 分帧、静止短路、超距休眠、dead-reckoning、SYNC_INTERVAL 节流广播	多实体联动 / 渲染同步 / 持久化 / 高频定时器类热点，需要可抄的成熟范式时
references/ui-practice.md	UI 实战模式（网易 JSON UI）：可视区格子池+分页虚拟化、控件句柄缓存、显隐替代增删、值比对刷新、轻重分离+防抖、搜索索引预建、懒加载+分帧注册、渲染 tick 限频	UI 打开慢 / 翻页搜索卡顿 / 界面常驻掉帧类热点
references/shader-practice.md	Shader 优化模式（渲染层）：step/mix 消分支、精度限定符（含 iOS/Android 真机差异）、计算下移顶点/CPU、减 inverse/纹理/噪声、全屏后处理与 Bloom 降载、GLSL ES 兼容写法、#ifdef 多档位、热重载+帧率验证	MOD 函数不贵但 FPS 低、引擎渲染 zone（inGameRender/UIScene 等）占大头时
references/render-assets-practice.md	渲染资源优化（模型/Mesh/特效/粒子）：特效 Mesh 减面、移动端模型分级、透明残影+overdraw 控制	特效/模型一多就掉帧、近距离看角色掉帧，几何与 overdraw 类

注意

• diff 要可比：两次 capture 用一致玩法 + 相同 seconds（上限 60）。
• Tracy 版本匹配：换游戏版本时同步替换 bin/ 的 CLI。
• capture 只保留最近 ~20 个；遇 unknown_capture 重新抓样即可。