mcdk-tracy-profiling

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 函数已值得警惕）。