# mcdk-mcp-tracy

> 一个 MCP 服务器：对**运行中的**网易我的世界基岩版 MOD 做性能监测——采集**每个函数的
> CPU 耗时**与帧率数据，用来定位热点、review 代码、量化验证优化效果。

三类性能监测能力：

- **热点定位**：函数耗时排行（self / total / 调用次数），直接看到最贵的函数在哪
- **优化验证**：前后两次采样按函数 diff，用毫秒回答"改完真的变快了吗"
- **帧级健康**：FPS 百分位（p1 / p5 / p50）与 jank 日志，交叉验证体验改善

原始逐帧数据在服务端归约，AI 只接收 top-N 排行与 diff 结果，不占上下文。

---

## 工作原理

```text
# 函数耗时（主路径）—— 直连游戏内嵌的原生 Tracy server
AI (Claude) --MCP/stdio--> mcdk-mcp-tracy --TCP 8086--> 游戏内嵌原生 Tracy server
                                  └─ bin/tracy-capture.exe + tracy-csvexport.exe

# 帧率 / jank（辅助路径）—— 经 MCDK 注入 get_Fps()
AI --MCP/stdio--> mcdk-mcp-tracy --MCP/SSE--> MCDK(mcdk.exe) --execute_code--> 游戏(Python2)
```

- **函数耗时直连原生 ModPC Tracy（8086），不管是通过MCDK还是MC Studio启动的游戏**：只要游戏启动没关闭就能抓取性能消耗信息。
  采集覆盖窗口内全部已插桩 zone（含客户端 `MAIN_THREAD` 与 `MC_SERVER` 线程）。
- **采样时建议跑图/搭建场景测压**：Tracy 只记录窗口内实际执行的代码，不建议静止不动。

> `bin/` 的 CLI 取自 Tracy **v0.11.1** 官方 Windows 包，版本须与游戏内嵌的 Tracy client
> 一致（协议版本敏感）；换游戏版本时同步替换。

## 前置条件

1. 游戏在运行，内嵌原生 Tracy server 监听 8086（用 `tracy-profiler.exe` GUI 能连上即确认）。
2. `bin/tracy-capture.exe`、`bin/tracy-csvexport.exe` 存在（随仓库附带；可用 `TRACY_BIN_DIR` 指向别处）。
3. **（仅 `tracy_jank_fps` 需要）** 游戏由 MCDK（`mcdk.exe`）启动，工程 `.mcdev.json` 开了 MCP：

   ```json
   { "mcp_server_config": { "enabled": true, "server_ip": "localhost", "server_port": 19133 } }
   ```

4. Python 3.10+（开发用 3.13），推荐 [`uv`](https://docs.astral.sh/uv/)。

## 安装

```bash
uv --directory <path>/mcdk-mcp-tracy sync           # 装依赖 + 建 .venv
uv --directory <path>/mcdk-mcp-tracy run pytest -q  # 自检，应 36 passed（无需游戏）
```

## 注册到 Claude Code

```bash
claude mcp add mcdk-mcp-tracy --scope user -- \
  "<path>/mcdk-mcp-tracy/.venv/Scripts/python.exe" -m mcdk_mcp_tracy \
  --stdio --mcdk-url http://127.0.0.1:19133
```

- 直接用 venv 里的 `python.exe`，不依赖 PATH。
- `--mcdk-url` 仅 `tracy_jank_fps` 用得到；也可换成 `--project-dir <MOD工程>` 按其 `.mcdev.json`
  自动找端口（优先级：`--mcdk-url` > `--mcdev-json` > `--project-dir` > `$MCDK_MCDEV_JSON` > 从 CWD 向上找）。
- 注册后**新开会话**才会出现 `mcp__mcdk-mcp-tracy__*` 工具。
  卸载：`claude mcp remove mcdk-mcp-tracy --scope user`。
- **推荐一并安装配套技能**：把 `skills/mcdk-tracy-profiling/` 整个目录拷到 `~/.claude/skills/`，
  AI 会自动按下面的人机协作流程工作（先对齐采样计划，报告后由你拍板再改代码）。

## 注册到 Codex

```bash
codex mcp add mcdk-mcp-tracy -- \
  "<path>/mcdk-mcp-tracy/.venv/Scripts/python.exe" -m mcdk_mcp_tracy \
  --stdio --mcdk-url http://127.0.0.1:19133
```

- Codex 会将服务器写入用户级 `~/.codex/config.toml`，无需 `--scope user`。
- 参数含义和寻址优先级与上方 Claude Code 配置相同；不需帧率 / jank 采样时可省略
  `--mcdk-url`。
- 运行 `codex mcp list` 确认已注册；注册后新开 Codex 会话（IDE 扩展中需重启扩展）
  即可使用 `mcp__mcdk-mcp-tracy__*` 工具。
- 卸载：`codex mcp remove mcdk-mcp-tracy`。
- **推荐一并安装配套技能**：把 `skills/mcdk-tracy-profiling/` 整个目录拷到 `~/.codex/skills/`。

---

## 性能监测标准流程工作流

负载要你亲自在游戏里触发，改代码要你拍板——AI 驱动流程，关键节点等你：

1. **探针**：`tracy_status()`，确认 8086 可达 + CLI 齐全。
2. **对齐采样计划**：AI 先问你采样时长——**10 秒**（瞬时逻辑：开 UI、放技能）／**30 秒**（常规
   玩法、跑图）／**60 秒**（长周期系统、复现偶发卡顿）／自定义（≤60）——以及准备触发的场景
   （跑图、刷实体、开打、跑机器……），**你就位后才开采**。
3. **基线采样**：你在游戏里触发玩法，AI 执行
   `tracy_native_capture(seconds=<约定>, name_contains="YourMod", label="before")`。
4. **热点报告（对话正文输出）**：热点排行（self / calls / 每帧均摊 / 单次均摊，必要时
   `tracy_get_function_costs` 细查）+ 按性价比排序的优化计划——每条含根因、改法、预期收益
   （估算 ms）、风险与改动量；改动小收益高的在前，动底层影响向下兼容的在后。**你选定做哪几条**。
5. **改代码 + 复测**：AI 按你选的方案改热点，**同场景同时长**再抓 `label="after"`。
6. **diff 验收**：`tracy_diff_captures(base_id, new_id, metric="self")`，`delta_ms` 为负 = 变快，
   按毫秒和百分比回报实际收益。（可选：`tracy_jank_fps` FPS 百分位交叉验证，仅 MCDK）

采样返回（已按 self 耗时降序）：

```json
{ "ok": true, "capture_id": "cap-1", "frames": 2632, "zones": 645899, "unit": "ms",
  "total_self_ms": 327.0,
  "top": [ { "name": "onRenderTick @ YourMod.Client.Main",
             "self_ms": 134.2, "total_ms": 328.1, "calls": 2628 } ] }
```

diff 返回：

```json
{ "ok": true, "metric": "self",
  "summary": { "base_total_ms": 86.4, "new_total_ms": 61.0, "delta_ms": -25.4, "pct": -29.4 },
  "improved": [ { "name": "YourMod.combat.update", "delta_ms": -16.8, "base_ms": 21.3, "new_ms": 4.5 } ],
  "regressed": [], "added": [], "removed": [] }
```

目标函数出现在 `improved`、`summary.pct` 下降，即优化生效。

## 内置优化模式参考库

技能自带七份**按症状索引**的优化模式参考（AI 生成第 4 步优化计划时按需查阅；你也可以直接翻着看）。
所有模式按"采样症状 → 改法"组织、附可移植代码骨架，来自官方性能优化指南与已上线大型 MOD 的
实战验证——例如负缓存实测省 ~720ms/10s、配置存储改造内存 715MB → 224MB、客户端实体可见包围盒按档给 −2.77 ms/帧。

| 参考文件 | 覆盖模式 | 对应症状 |
| --- | --- | --- |
| [general-practice.md](skills/mcdk-tracy-profiling/references/general-practice.md) | 组件全局缓存、降频+加盐+质数间隔、事件化替代轮询、分帧、单播替代广播、Python 微优化、调色板批量放置方块、配置内存与加载 | tick / 组件创建 / 通信热点；批量摆方块尖峰、启动慢、内存高 |
| [advanced-practice.md](skills/mcdk-tracy-profiling/references/advanced-practice.md) | 负缓存、脏驱动 O(dirty)、值比对早退、同 tick 快照短路、有序调度池（定时器）、lazyTick 分频、frame-drain 分帧、静止短路、超距休眠、dead-reckoning、节流广播、落盘节流 | 多实体联动 / 渲染同步 / 持久化 / 高频定时器类热点 |
| [ui-practice.md](skills/mcdk-tracy-profiling/references/ui-practice.md) | 可视区格子池+分页虚拟化、控件句柄缓存、显隐替代增删、值比对刷新、轻重分离+防抖、搜索索引预建、懒加载+分帧注册 | UI 打开慢 / 翻页搜索卡顿 / 界面常驻掉帧 |
| [shader-practice.md](skills/mcdk-tracy-profiling/references/shader-practice.md) | step/mix 消分支、精度限定符（含 iOS/Android 真机差异）、计算下移顶点/CPU、减 inverse/纹理/噪声、全屏后处理与 Bloom 降载、GLSL ES 兼容写法、#ifdef 多档位、热重载+帧率验证 | MOD 函数不贵但 FPS 低、引擎渲染 zone 占大头 |
| [render-assets-practice.md](skills/mcdk-tracy-profiling/references/render-assets-practice.md) | 特效 Mesh 减面、移动端模型分级、透明残影+overdraw 控制 | 特效/模型一多就掉帧、近距离看角色掉帧 |
| [client-entity-practice.md](skills/mcdk-tracy-profiling/references/client-entity-practice.md) | 可见包围盒按档给、多单元打包减实体、按规模分档、资产生成器硬断言、锚点与光照采样 | MOD 自建的客户端实体一多就掉帧 |
| [render-measurement.md](skills/mcdk-tracy-profiling/references/render-measurement.md) | 天花板法、同场景 A/B monkey-patch、基线漂移、±5% 噪声底、成本模型回代验证 | Tracy 看不到的渲染类改动，下结论 / 报收益之前 |

## 工具速查表

| 工具 | 作用 | 关键参数 |
| --- | --- | --- |
| `tracy_status` | **先跑**。探测 8086 可达性、bundled CLI、MCDK 端点（信息性） | `address`, `port`(8086) |
| `tracy_native_capture` | **核心**。抓函数耗时 top-N，存为 `capture_id` | `seconds`(≤60), `name_contains`, `top_n`, `label` |
| `tracy_get_function_costs` | 从某次 capture 查函数成本（self/total/calls） | `capture_id`(必填), `names?`, `name_contains?`, `limit` |
| `tracy_diff_captures` | 前后两次 capture 按函数对比 | `base_id`, `new_id`(必填), `metric`(self/total), `top_n` |
| `tracy_jank_fps` | 帧级健康（仅 MCDK，MCStudio启动不可用）：FPS 百分位 / jank 日志 | `action`(sample_fps\|read_jank_logs), `duration_seconds` |
| `tracy_list_captures` | 列出已存 capture，方便挑 id 做 diff | 无 |

统一返回：成功 `{"ok": true, ...}`，失败 `{"ok": false, "reason": "...", "error": "..."}`。

## 性能监测要点

1. **采样期间制造真实负载**：站到卡顿场景、开打、刷实体、跑机器——要测什么就让游戏跑什么。
2. **用 `name_contains` 聚焦自己的 MOD**：函数显示为 `"函数名 @ 源文件"`，按脚本包前缀过滤；
   过滤只影响 inline 返回，全量数据仍存进 capture，事后可再查。
3. **diff 要可比**：前后两次用尽量一致的玩法 + 相同 `seconds`，否则 delta 不可信。
4. **结论用数字说话**：优化是否生效看 `improved` / `summary.pct`，不凭体感。
5. **Tracy 版本匹配**：换游戏版本时同步替换 `bin/` 的 CLI（当前 v0.11.1）。

## 排查表

| 现象 | 含义 | 怎么修 |
| --- | --- | --- |
| `native_tracy.reachable=false` | 连不上 8086 | 确认游戏在跑且内嵌 Tracy；用 tracy-profiler GUI 验证；查 `address`/`port` |
| `bin_present=false` | 缺 bundled CLI | 确认 `bin/` 两个 exe 存在，或设 `TRACY_BIN_DIR` |
| capture 返回空 + `warning` | 窗口内没负载 | 采样时让游戏真的跑要测的逻辑 |
| `mcdk_unreachable`（仅 jank_fps） | 连不上 MCDK | 确认游戏由 MCDK 启动、19133 在跑 |
| `unknown_capture` | capture 已淘汰（只留最近 ~20 个） | 重新抓样拿新 id |
| `bad_request` | 参数非法（如 `seconds>60`） | 按文档改参数 |

## 开发

```bash
uv --directory mcdk-mcp-tracy run pytest -q   # 36 passed，无需游戏
# 若 uv 在中文路径下报 trampoline 错误，改用：
./.venv/Scripts/python.exe -m pytest -q
```

AI 工作流策略见 [skills/mcdk-tracy-profiling/SKILL.md](skills/mcdk-tracy-profiling/SKILL.md)