mcpywrap-core 0.6.4__tar.gz → 0.7.0__tar.gz

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/MANIFEST.in

@@ -1,5 +1,6 @@
 include README.md LICENSE THIRD_PARTY_NOTICES.md
 include mcpywrap_core/core-contract.json
+include mcpywrap_core/profiling/tools.json
 recursive-include mcpywrap_core/ui/assets *.svg *.png *.icns *.json
 prune mcpywrap_core/mcstudio/bridge_payload
 prune mcpywrap_core/mcstudio/window_capture

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpywrap-core
-Version: 0.6.4
+Version: 0.7.0
 Summary: Shared mcpy project dependency, build and runtime logic
 Author-email: boybook <boybook@easecation.net>
 License-Expression: MIT

mcpywrap_core-0.7.0/mcpywrap_core/_version.py

@@ -0,0 +1 @@
+__version__ = '0.7.0'

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/mcpywrap_core/cli.py

@@ -8,7 +8,8 @@ from .command_context import OperationGroup, configure_context
 COMMANDS = {
     name: (name + '_cmd', name + '_cmd') for name in
     ('host', 'skill', 'modsdk', 'init', 'add', 'remove', 'build', 'dev', 'package', 'publish',
-     'mod', 'run', 'deps', 'connect', 'edit', 'ui', 'doctor', 'engine', 'sync', 'serve', 'record', 'script', 'deployment')
+     'mod', 'run', 'deps', 'connect', 'edit', 'ui', 'doctor', 'engine', 'sync', 'serve', 'record', 'script', 'deployment',
+     'profile')
 }
 COMMANDS.update({name: ('session_cmd', name + '_cmd') for name in ('status', 'logs', 'stop', 'restart')})
 COMMANDS.update({name: ('runtime_cmd', name + '_cmd') for name in ('runtime', 'py', 'reload')})

mcpywrap_core-0.7.0/mcpywrap_core/commands/profile_cmd.py

@@ -0,0 +1,159 @@
+"""性能分析：基于游戏内置 Tracy 0.11.1（协议 69）的实时查看、采集、报告与对比。"""
+import datetime
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import click
+
+from ..command_context import OperationCommand, json_output, project_dir
+
+
+def _download_progress():
+    last = [0.0]
+
+    def update(done, total):
+        now = time.monotonic()
+        if now - last[0] >= 1 or done == total:
+            click.echo('下载 Tracy 工具：%.1f / %.1f MiB' % (done / 1048576, total / 1048576), err=True)
+            last[0] = now
+    return update
+
+
+def _target(session, port):
+    from ..profiling import endpoint, tools
+    if session and port:
+        raise click.UsageError('--session 与 --port 只能指定一个')
+    return endpoint.resolve(project_dir(), tools.manifest()['protocol'], session=session, port=port)
+
+
+def _launch(command):
+    from ..mcstudio.processes import background_options
+    process = subprocess.Popen(command, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                               stderr=subprocess.DEVNULL, **background_options())
+    return process.pid
+
+
+def _summary(trace, top, filter):
+    from ..profiling import analysis
+    summary = analysis.summarize(analysis.load(trace), project_dir(), top=top, filter=filter)
+    summary['trace'] = str(Path(trace).resolve())
+    summary['report'] = str(analysis.report_path(Path(trace).resolve()))
+    return summary
+
+
+def _show(summary):
+    """人类模式打印文本并返回简短结果；JSON 模式返回完整摘要。"""
+    if json_output():
+        return summary
+    from ..profiling.analysis import format_summary
+    click.echo(format_summary(summary))
+    click.echo('')
+    return {'trace': summary['trace']}
+
+
+@click.group(name='profile')
+def profile_cmd():
+    """性能分析：实时分析器、离线查看、采集、报告与前后对比（Tracy 0.11.1）。"""
+
+
+@profile_cmd.command(cls=OperationCommand, local_only=True, name='install')
+@click.option('--from', 'from_archive', type=click.Path(exists=True, dir_okay=False), help='导入已下载的工具包 ZIP（须与清单摘要一致）')
+@click.option('--force', is_flag=True, help='已安装时也重新解压')
+def profile_install(from_archive, force):
+    """下载并校验固定版本的 Tracy 工具；多镜像、可续传，可用 MCPY_TRACY_MIRROR 指定镜像。"""
+    from ..profiling import tools
+    return tools.install(from_archive, force, None if json_output() else _download_progress())
+
+
+@profile_cmd.command(cls=OperationCommand, local_only=True, name='status')
+def profile_status():
+    """工具安装状态与本机正在监听 Tracy 的游戏进程（只查连接表，不连接游戏）。"""
+    from ..profiling import endpoint, tools
+    return dict(tools.status(), endpoints=endpoint.discover())
+
+
+@profile_cmd.command(cls=OperationCommand, local_only=True, name='open')
+@click.argument('trace', required=False, type=click.Path(exists=True, dir_okay=False))
+@click.option('--session', help='连接此会话的游戏')
+@click.option('--port', type=click.IntRange(1, 65535), help='直接指定本机 Tracy 端口')
+def profile_open(trace, session, port):
+    """打开 Tracy 分析器：给出 .tracy 文件时离线查看，否则实时连接游戏。"""
+    from ..profiling import tools
+    profiler = str(tools.require('tracy-profiler'))
+    if trace:
+        if session or port:
+            raise click.UsageError('离线查看文件时不能同时指定 --session 或 --port')
+        path = Path(trace).resolve()
+        return {'mode': 'file', 'trace': str(path), 'pid': _launch([profiler, str(path)])}
+    target = _target(session, port)
+    pid = _launch([profiler, '-a', '127.0.0.1', '-p', str(target['port'])])
+    return dict(target, mode='live', pid=pid,
+                hint='分析器已连接；Tracy 同时只接受一个连接，关闭分析器窗口后才能再次采集。')
+
+
+@profile_cmd.command(cls=OperationCommand, local_only=True, name='capture')
+@click.option('--session', help='采集此会话的游戏')
+@click.option('--port', type=click.IntRange(1, 65535), help='直接指定本机 Tracy 端口')
+@click.option('--seconds', type=click.IntRange(1, 600), default=20, show_default=True, help='采集时长')
+@click.option('--output', type=click.Path(dir_okay=False), help='.tracy 输出路径，默认 .runtime/profiles/ 下按时间命名')
+@click.option('--top', type=click.IntRange(1, 200), default=15, show_default=True, help='报告中每类列出的条目数')
+@click.option('--filter', help='只列出名称或模块路径包含该文本的脚本函数')
+@click.option('--no-report', is_flag=True, help='只保存采集文件，不生成报告')
+def profile_capture(session, port, seconds, output, top, filter, no_report):
+    """无界面采集一段时间并生成报告；采集期间请让游戏处于要分析的场景。"""
+    from ..engines.host import EngineError
+    from ..profiling import tools
+    capture = str(tools.require('tracy-capture'))
+    if not no_report:
+        tools.require('mcpy-tracy-report')
+    if output:
+        path = Path(output).expanduser().resolve()
+        if path.suffix != '.tracy' or path.exists():
+            raise click.UsageError('输出必须是尚不存在的 .tracy 文件')
+    else:
+        stamp = datetime.datetime.now().strftime('%Y%m%d-%H%M%S')
+        path = project_dir() / '.runtime' / 'profiles' / ('%s-%s.tracy' % (stamp, (session or 'port')[:8]))
+    target = _target(session, port)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not json_output():
+        click.echo('采集 %d 秒（127.0.0.1:%d）…' % (seconds, target['port']), err=True)
+    command = [capture, '-o', str(path), '-a', '127.0.0.1', '-p', str(target['port']), '-s', str(seconds)]
+    try:
+        done = subprocess.run(command, capture_output=True, timeout=seconds + 60)
+    except subprocess.TimeoutExpired:
+        raise EngineError('采集超时：未能连接或结束', 'capture_failed',
+                          '确认没有其他分析器占用该端口后重试。', port=target['port']) from None
+    if done.returncode != 0 or not path.is_file():
+        tail = done.stdout.decode('utf-8', 'replace').replace('\r', '\n').strip().splitlines()[-3:]
+        raise EngineError('采集失败', 'capture_failed', details='\n'.join(tail), port=target['port'])
+    if no_report:
+        return dict(target, trace=str(path), size=path.stat().st_size)
+    return _show(dict(_summary(path, top, filter), target=target))
+
+
+@profile_cmd.command(cls=OperationCommand, local_only=True, name='report')
+@click.argument('trace', type=click.Path(exists=True, dir_okay=False))
+@click.option('--top', type=click.IntRange(1, 200), default=15, show_default=True)
+@click.option('--filter', help='只列出名称或模块路径包含该文本的脚本函数')
+def profile_report(trace, top, filter):
+    """汇总 .tracy 文件：主循环与 tick 分位数、脚本函数热点与尖峰、最慢帧归因。"""
+    return _show(_summary(trace, top, filter))
+
+
+@profile_cmd.command(cls=OperationCommand, local_only=True, name='diff')
+@click.argument('base', type=click.Path(exists=True, dir_okay=False))
+@click.argument('new', type=click.Path(exists=True, dir_okay=False))
+@click.option('--top', type=click.IntRange(1, 200), default=15, show_default=True)
+def profile_diff(base, new, top):
+    """对比两次采集（按每秒耗时，时长可不同）；用于验证优化前后的变化。"""
+    from ..profiling import analysis
+    before = analysis.summarize(analysis.load(base), project_dir(), top=200)
+    after = analysis.summarize(analysis.load(new), project_dir(), top=200)
+    result = dict(analysis.diff(before, after, top), base=str(Path(base).resolve()), new=str(Path(new).resolve()))
+    if json_output():
+        return result
+    click.echo(analysis.format_diff(result))
+    click.echo('')
+    return {'base': result['base'], 'new': result['new']}

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/mcpywrap_core/engines/install.py

@@ -24,7 +24,7 @@ from .host import EngineError, describe, require_macos
 
 CATALOG_ENV = 'MCPY_RUNTIME_CATALOG'
 DEFAULT_CATALOG = ('https://github.com/EaseCation/mcpelauncher-manifest/releases/download/'
-                   'mcpy-runtime-v0.4.7/catalog.json')
+                   'mcpy-runtime-v0.4.8/catalog.json')
 # Public constant from the official ApkDownload component, verified 2026-10-05.
 # https://mcdev.webapp.163.com/static/js/4.05713153ba17aea6db53.js
 CDN_CONSTANT = 'mEE7Cot48r9j2AvEL2N6jpXEc'

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/mcpywrap_core/engines/macos.py

@@ -75,6 +75,7 @@ def pinned_runtime(item):
     return {'runtime': str(app), 'application': str(application), 'game': str(game), 'profile': plan['profile'], 'runtime_id': plan['runtime_id'],
             'compat_report': compatibility, 'cppconfig_protocol': meta.get('cppconfig_protocol'),
             'network_connect_protocol': meta.get('network_connect_protocol'),
+            'network_plain_source_protocol': meta.get('network_plain_source_protocol'),
             'developer_identity_protocol': meta.get('developer_identity_protocol'),
             'background_window_protocol': meta.get('background_window_protocol')}
 

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/mcpywrap_core/engines/macos_network.py

@@ -51,7 +51,9 @@ def connect(target, *, project_dir=None, packs=(), engine_overrides=None, detach
         data = sessions.start(root, backend='macos-arm64', session_id=session, launch=plan,
                               group=group, role=role, background=background,
                               network={'target': asdict(target), 'engine': {'version': version},
-                                       'player': player})
+                                       'player': player,
+                                       # 运行包是否为开发服下发的纯明文源码包补充导入；.mcp 包始终由游戏加载
+                                       'plain_source_packs': state.get('network_plain_source_protocol') == 1})
     result = sessions.handoff(data)
     if detach:
         return result

{mcpywrap_core-0.6.4 → mcpywrap_core-0.7.0}/mcpywrap_core/mcstudio/sessions.py

@@ -212,6 +212,9 @@ def handoff(data):
                       identity_provided=data['mcs_auth'], authenticated=False,
                       connection_verified=data.get('connection_verified', False), addons_assembled=False,
                       engine_version=data['network']['engine']['version'])
+        if 'plain_source_packs' in data['network']:
+            # 仅报告运行包能力；是否有包按明文加载以游戏日志 [PlainSourcePack] 为准
+            result['plain_source_packs'] = data['network']['plain_source_packs']
     return result
 
 

mcpywrap_core-0.7.0/mcpywrap_core/profiling/__init__.py

@@ -0,0 +1 @@
+"""基于游戏内置 Tracy 0.11.1（协议 69）的性能分析：工具分发、端点发现、采集与报告。"""

mcpywrap_core-0.7.0/mcpywrap_core/profiling/analysis.py

@@ -0,0 +1,309 @@
+"""把 mcpy-tracy-report 的原始统计整理为面向开发者与 Agent 的摘要、对比与文本。
+
+游戏内置 Tracy 为每个 Python 函数生成区段：名称为函数名，文件为部署后的 .py 路径，行号为 def 行；
+Python 内置函数（如 time.time）也有区段，文件为模块名、行号为 0。
+"""
+import json
+import re
+import subprocess
+from pathlib import Path
+
+from ..engines.host import EngineError
+from . import tools
+
+MAIN_LOOP = 'Main Update'
+SERVER_TICK = 'serverUpdate'
+REPORT_SCHEMA = 1
+
+
+def report_path(trace):
+    trace = Path(trace)
+    return trace.with_name(trace.name + '.report.json')
+
+
+def load(trace):
+    """读取或生成原始报告；与采集文件同目录缓存，采集文件更新后重新生成。"""
+    trace = Path(trace).expanduser().resolve()
+    if not trace.is_file():
+        raise EngineError('采集文件不存在：' + str(trace), 'trace_missing')
+    cache = report_path(trace)
+    executable = tools.require('mcpy-tracy-report')
+    # 缓存绑定工具包摘要，工具更新后重新生成
+    identity = tools.installed_identity()
+    if cache.is_file() and cache.stat().st_mtime >= trace.stat().st_mtime:
+        try:
+            data = json.loads(cache.read_text(encoding='utf-8'))
+            if data.get('schema') == REPORT_SCHEMA and data.get('mcpy_tools') == identity:
+                return data
+        except ValueError:
+            pass
+    command = [str(executable), str(trace)]
+    try:
+        done = subprocess.run(command, capture_output=True, timeout=900)
+    except subprocess.TimeoutExpired:
+        raise EngineError('采集文件分析超时', 'report_failed') from None
+    if done.returncode != 0:
+        raise EngineError('采集文件分析失败：' + done.stderr.decode('utf-8', 'replace').strip()[-400:], 'report_failed')
+    try:
+        data = json.loads(done.stdout.decode('utf-8', 'replace'))
+    except ValueError:
+        raise EngineError('分析工具输出无效', 'report_failed') from None
+    data['mcpy_tools'] = identity
+    try:
+        cache.write_text(json.dumps(data, ensure_ascii=False), encoding='utf-8')
+    except OSError:
+        pass
+    return data
+
+
+def classify(zone):
+    file = zone.get('file') or ''
+    if file.lower().endswith('.py'):
+        return 'script'
+    if zone.get('line') == 0 and file != 'Engine' and not re.search(r'[\\/]', file):
+        return 'builtin'
+    return 'engine'
+
+
+def module_path(file):
+    """部署路径 .../behavior_packs/<包目录>/<模块路径> → 模块路径；不在包内时返回 None。"""
+    parts = [p for p in re.split(r'[\\/]', file or '') if p]
+    lowered = [p.lower() for p in parts]
+    for marker, skip in (('behavior_packs', 2), ('behavior_pack', 1)):
+        if marker in lowered:
+            index = len(lowered) - 1 - lowered[::-1].index(marker)
+            if index + skip < len(parts):
+                return '/'.join(parts[index + skip:])
+    return None
+
+
+def source_roots(project):
+    """项目与依赖的行为包目录；解析失败时退回项目内的常规目录，不安装或运行钩子。"""
+    if not project:
+        return []
+    project = Path(project).resolve()
+    roots = []
+    if (project / 'pyproject.toml').is_file():
+        try:
+            from ..dependencies import DependencyService, read_project
+            manager = DependencyService(project).resolve(read_project(project))
+            packs = [getattr(manager.root_node, 'addon_pack', None)] + list(manager.get_all_dependencies().values())
+            roots += [Path(p.behavior_pack_dir) for p in packs if p is not None and getattr(p, 'behavior_pack_dir', None)]
+        except Exception:
+            pass
+    roots += [project / 'behavior_pack']
+    parent = project / 'behavior_packs'
+    roots += sorted(p for p in parent.iterdir() if p.is_dir()) if parent.is_dir() else []
+    return [r for r in dict.fromkeys(roots) if r.is_dir()]
+
+
+class _Sources:
+    def __init__(self, project):
+        self.project = Path(project).resolve() if project else None
+        self.roots = None
+
+    def find(self, module):
+        if not module or not self.project:
+            return None
+        if self.roots is None:
+            self.roots = source_roots(self.project)
+        for root in self.roots:
+            candidate = root / module
+            if candidate.is_file():
+                try:
+                    return str(candidate.relative_to(self.project))
+                except ValueError:
+                    return str(candidate)
+        return None
+
+
+def _ms(value):
+    return round(value / 1e6, 3)
+
+
+def summarize(raw, project=None, top=15, filter=None):
+    zones = raw['zones']
+    span = max(raw['capture']['span_ns'], 1) / 1e9
+    thread_names = {t['id']: t['name'] for t in raw['threads']}
+    sources = _Sources(project)
+    kinds = [classify(z) for z in zones]
+    modules = [module_path(z['file']) if kind == 'script' else None for z, kind in zip(zones, kinds)]
+    callers = {}
+    builtin_from_script = 0
+    for edge in raw['edges']:
+        if edge['parent'] >= 0:
+            callers.setdefault(edge['child'], []).append(edge)
+            if kinds[edge['child']] == 'builtin' and kinds[edge['parent']] == 'script':
+                builtin_from_script += edge['total_ns']
+
+    def label(i):
+        z = zones[i]
+        if kinds[i] == 'script':
+            return '%s (%s:%d)' % (z['name'], modules[i] or z['file'], z['line'])
+        return z['name']
+
+    def view(i):
+        z = zones[i]
+        item = {'name': z['name'], 'kind': kinds[i], 'count': z['count'], 'per_second': round(z['count'] / span, 2),
+                'total_ms': _ms(z['total_ns']), 'self_ms': _ms(z['self_ns']),
+                'mean_ms': _ms(z['total_ns'] / z['count']) if z['count'] else 0,
+                'p50_ms': _ms(z['p50_ns']), 'p95_ms': _ms(z['p95_ns']), 'p99_ms': _ms(z['p99_ns']),
+                'max_ms': _ms(z['max_ns'])}
+        if kinds[i] == 'script':
+            item.update(module=modules[i], line=z['line'], source=sources.find(modules[i]))
+            if not modules[i]:
+                item['file'] = z['file']
+        item['threads'] = [thread_names.get(t['id'], str(t['id']))
+                           for t in sorted(z['threads'], key=lambda t: -t['self_ns'])][:3]
+        item['callers'] = [label(e['parent']) for e in sorted(callers.get(i, []), key=lambda e: -e['total_ns'])[:3]]
+        return item
+
+    def loop(name):
+        index = next((i for i, z in enumerate(zones) if z['name'] == name and kinds[i] == 'engine'), None)
+        if index is None:
+            return None
+        z = zones[index]
+        return {'zone': name, 'count': z['count'], 'per_second': round(z['count'] / span, 2),
+                'mean_ms': _ms(z['total_ns'] / max(z['count'], 1)), 'p50_ms': _ms(z['p50_ns']),
+                'p95_ms': _ms(z['p95_ns']), 'p99_ms': _ms(z['p99_ns']), 'max_ms': _ms(z['max_ns'])}
+
+    needle = (filter or '').lower()
+    script_ids = [i for i, kind in enumerate(kinds) if kind == 'script' and
+                  (not needle or needle in zones[i]['name'].lower() or needle in (modules[i] or zones[i]['file']).lower())]
+    script_self = sum(zones[i]['self_ns'] for i, kind in enumerate(kinds) if kind == 'script')
+    engine_ids = [i for i, kind in enumerate(kinds) if kind == 'engine']
+
+    windows = []
+    for window in raw.get('windows', []):
+        slowest = []
+        for instance in window['slowest']:
+            entries = []
+            # 窗口所在线程的条目优先，其他线程（可能只是等待）其次
+            ordered = sorted(instance['top_self'], key=lambda e: (e['thread'] != instance['thread'], -e['self_ns']))
+            for entry in ordered[:8]:
+                i = entry['zone']
+                entries.append({'zone': label(i), 'kind': kinds[i], 'thread': thread_names.get(entry['thread'], str(entry['thread'])),
+                                'self_ms': _ms(entry['self_ns'])})
+            slowest.append({'at_s': round(instance['start_ns'] / 1e9, 3), 'duration_ms': _ms(instance['duration_ns']),
+                            'thread': thread_names.get(instance['thread'], str(instance['thread'])), 'top_self': entries})
+        windows.append({'zone': window['zone'], 'slowest': slowest})
+
+    return {
+        'capture': {'program': raw['capture']['program'], 'span_s': round(span, 3), 'zone_count': raw['capture']['zone_count'],
+                    'tracy_version': raw.get('tracy_version')},
+        'main_loop': loop(MAIN_LOOP),
+        'server_tick': loop(SERVER_TICK),
+        'script': {'self_ms_per_s': round(script_self / 1e6 / span, 3),
+                   'builtin_from_script_ms_per_s': round(builtin_from_script / 1e6 / span, 3),
+                   'functions': sum(1 for kind in kinds if kind == 'script')},
+        'scripts': [view(i) for i in sorted(script_ids, key=lambda i: -zones[i]['total_ns'])[:top]],
+        'script_spikes': [view(i) for i in sorted(script_ids, key=lambda i: -zones[i]['max_ns'])[:min(top, 8)]],
+        'engine': [view(i) for i in sorted(engine_ids, key=lambda i: -zones[i]['self_ns'])[:top]],
+        'windows': windows,
+    }
+
+
+def _key(item):
+    return (item['kind'], item['name'], item.get('module') or item.get('file'), item.get('line'))
+
+
+def diff(base, new, top=15):
+    """按每秒耗时对比两次摘要（采集时长可以不同）。摘要需使用较大的 top 生成以覆盖足够函数。"""
+    def rate(item, summary):
+        return item['total_ms'] / max(summary['capture']['span_s'], 1e-9)
+
+    def compare(section):
+        before = {_key(item): item for item in base[section]}
+        after = {_key(item): item for item in new[section]}
+        rows = []
+        for key in dict.fromkeys(list(before) + list(after)):
+            a, b = before.get(key), after.get(key)
+            ref = b or a
+            row = {'name': ref['name'], 'kind': ref['kind'],
+                   'base_ms_per_s': round(rate(a, base), 3) if a else None,
+                   'new_ms_per_s': round(rate(b, new), 3) if b else None,
+                   'base_mean_ms': a['mean_ms'] if a else None, 'new_mean_ms': b['mean_ms'] if b else None,
+                   'base_max_ms': a['max_ms'] if a else None, 'new_max_ms': b['max_ms'] if b else None}
+            if ref.get('module') or ref.get('line') is not None:
+                row.update(module=ref.get('module'), line=ref.get('line'))
+            row['delta_ms_per_s'] = round((row['new_ms_per_s'] or 0) - (row['base_ms_per_s'] or 0), 3)
+            rows.append(row)
+        return sorted(rows, key=lambda r: -abs(r['delta_ms_per_s']))[:top]
+
+    def loop(name):
+        a, b = base.get(name), new.get(name)
+        if not a or not b:
+            return None
+        return {k: {'base': a[k], 'new': b[k], 'delta': round(b[k] - a[k], 3)}
+                for k in ('mean_ms', 'p50_ms', 'p95_ms', 'p99_ms', 'max_ms', 'per_second')}
+
+    return {'main_loop': loop('main_loop'), 'server_tick': loop('server_tick'),
+            'script_self_ms_per_s': {'base': base['script']['self_ms_per_s'], 'new': new['script']['self_ms_per_s'],
+                                     'delta': round(new['script']['self_ms_per_s'] - base['script']['self_ms_per_s'], 3)},
+            'scripts': compare('scripts'), 'engine': compare('engine')}
+
+
+def _where(item):
+    if item['kind'] != 'script':
+        return ''
+    return '%s:%s' % (item.get('source') or item.get('module') or item.get('file'), item.get('line'))
+
+
+def format_summary(summary):
+    lines = []
+    capture = summary['capture']
+    lines.append('采集 %.1f 秒 · %s 个区段 · %s' % (capture['span_s'], format(capture['zone_count'], ','), capture['program']))
+    for key, title in (('main_loop', '主循环'), ('server_tick', '服务端更新')):
+        loop = summary.get(key)
+        if loop:
+            lines.append('%s %s：p50 %.2fms  p95 %.2fms  p99 %.2fms  最大 %.2fms  （%.1f 次/秒）' % (
+                title, loop['zone'], loop['p50_ms'], loop['p95_ms'], loop['p99_ms'], loop['max_ms'], loop['per_second']))
+    script = summary['script']
+    lines.append('脚本：自身 %.2f ms/秒，脚本调用的内置函数 %.2f ms/秒，%d 个函数' % (
+        script['self_ms_per_s'], script['builtin_from_script_ms_per_s'], script['functions']))
+    span = max(capture['span_s'], 1e-9)
+
+    def table(title, items):
+        if not items:
+            return
+        lines.append('')
+        lines.append(title)
+        lines.append('  %9s %9s %8s %8s %8s %8s  %s' % ('总ms/秒', '自身ms/秒', '平均ms', 'p95ms', '最大ms', '次/秒', '函数'))
+        for item in items:
+            lines.append('  %9.2f %9.2f %8.3f %8.3f %8.2f %8.1f  %s %s' % (
+                item['total_ms'] / span, item['self_ms'] / span, item['mean_ms'], item['p95_ms'], item['max_ms'],
+                item['per_second'], item['name'], _where(item)))
+
+    table('脚本函数（按总耗时）', summary['scripts'])
+    table('脚本耗时尖峰（按单次最大）', summary['script_spikes'])
+    table('引擎区段（按自身耗时）', summary['engine'])
+    for window in summary['windows']:
+        if not window['slowest']:
+            continue
+        lines.append('')
+        lines.append('最慢的 %s：' % window['zone'])
+        for instance in window['slowest']:
+            parts = ['%s[%s] %.1f' % (e['zone'], e['thread'], e['self_ms']) for e in instance['top_self'][:5]]
+            lines.append('  %.2fms @%.2fs  %s' % (instance['duration_ms'], instance['at_s'], '；'.join(parts)))
+    return '\n'.join(lines)
+
+
+def format_diff(result):
+    lines = []
+    for key, title in (('main_loop', '主循环'), ('server_tick', '服务端更新')):
+        loop = result.get(key)
+        if loop:
+            lines.append('%s：p50 %.2f→%.2fms  p95 %.2f→%.2fms  最大 %.2f→%.2fms' % (
+                title, loop['p50_ms']['base'], loop['p50_ms']['new'], loop['p95_ms']['base'], loop['p95_ms']['new'],
+                loop['max_ms']['base'], loop['max_ms']['new']))
+    s = result['script_self_ms_per_s']
+    lines.append('脚本自身：%.2f → %.2f ms/秒（%+.2f）' % (s['base'], s['new'], s['delta']))
+    for section, title in (('scripts', '脚本函数变化'), ('engine', '引擎区段变化')):
+        lines.append('')
+        lines.append(title + '（按每秒耗时变化）：')
+        for row in result[section]:
+            where = ' %s:%s' % (row.get('module'), row.get('line')) if row.get('module') else ''
+            lines.append('  %+9.2f ms/秒  %s → %s  %s%s' % (
+                row['delta_ms_per_s'], '-' if row['base_ms_per_s'] is None else '%.2f' % row['base_ms_per_s'],
+                '-' if row['new_ms_per_s'] is None else '%.2f' % row['new_ms_per_s'], row['name'], where))
+    return '\n'.join(lines)

mcpywrap_core-0.7.0/mcpywrap_core/profiling/endpoint.py

@@ -0,0 +1,112 @@
+"""定位游戏内置 Tracy 端点并核对协议。
+
+游戏只监听 127.0.0.1，从 8086 起顺延到 8105（多实例）。Tracy 同时只接受一个分析器连接；
+握手成功会被视为一次短暂连接，随后断开，游戏回到等待状态。
+"""
+import socket
+import struct
+
+from ..engines.host import EngineError
+
+HOST = '127.0.0.1'
+PORTS = range(8086, 8106)
+SHIBBOLETH = b'TracyPrf'
+STATUS = {0: 'pending', 1: 'welcome', 2: 'protocol_mismatch', 3: 'not_available', 4: 'dropped'}
+GAME_PREFIXES = ('mcpelauncher', 'minecraft.windows')
+BUSY_HINT = 'Tracy 同时只接受一个连接；关闭已打开的分析器或正在进行的采集后重试。'
+
+
+def handshake(port, protocol, timeout=2.0, host=HOST):
+    """返回 welcome / protocol_mismatch / busy / closed 等状态；不读取分析数据。"""
+    try:
+        # Windows 对未监听的本机端口会重试 SYN 而非立即拒绝，连接阶段超时同样视为未监听
+        sock = socket.create_connection((host, port), timeout=timeout)
+    except OSError:
+        return 'closed'
+    try:
+        with sock:
+            sock.sendall(SHIBBOLETH + struct.pack('<I', protocol))
+            reply = sock.recv(1)
+    except socket.timeout:
+        # 连接已建立但没有应答：游戏已有分析器连接，不再处理新的握手
+        return 'busy'
+    except OSError:
+        return 'closed'
+    return STATUS.get(reply[0], 'unknown') if reply else 'dropped'
+
+
+def _connections(process):
+    getter = getattr(process, 'net_connections', None) or process.connections
+    return getter(kind='tcp')
+
+
+def listening_ports(process):
+    import psutil
+    try:
+        ports = {c.laddr.port for c in _connections(process)
+                 if c.status == psutil.CONN_LISTEN and c.laddr and c.laddr.port in PORTS}
+    except (psutil.AccessDenied, psutil.NoSuchProcess):
+        return []
+    return sorted(ports)
+
+
+def discover():
+    """列出本机游戏进程的 Tracy 监听端口；只查询系统连接表，不建立连接。"""
+    import psutil
+    found = []
+    for process in psutil.process_iter(['name', 'pid']):
+        name = (process.info.get('name') or '').lower()
+        if name.startswith(GAME_PREFIXES):
+            for port in listening_ports(process):
+                found.append({'pid': process.info['pid'], 'port': port, 'process': process.info.get('name')})
+    return sorted(found, key=lambda item: item['port'])
+
+
+def session_endpoint(project, session):
+    from ..mcstudio import sessions
+    from ..mcstudio.processes import checked_process
+    try:
+        data = sessions.read(project, session)
+    except ValueError:
+        from ..command_context import remote_url
+        if remote_url():
+            raise EngineError('本机没有该会话：' + session, 'session_unavailable',
+                              '暂不支持远程会话的性能采集；请在 Windows 测试机本机运行 mcpy profile。') from None
+        raise
+    if data.get('state') not in ('starting', 'running') or not data.get('game'):
+        raise EngineError('会话没有运行中的游戏进程', 'session_unavailable')
+    process = checked_process(data['game'])
+    if process is None:
+        raise EngineError('会话的游戏进程已退出', 'session_unavailable')
+    ports = listening_ports(process)
+    if not ports:
+        hint = '游戏启动后需要数秒才开始监听；稍后重试。'
+        if data.get('backend') == 'macos-arm64':
+            hint += 'macOS 需要运行包 0.4.7 及以上，旧实例请更新运行包后用 run --new 新建。'
+        raise EngineError('游戏进程没有监听 Tracy 端口', 'profiler_unavailable', hint, session=session)
+    return {'session': session, 'pid': process.pid, 'port': ports[0], 'backend': data.get('backend', 'windows')}
+
+
+def resolve(project, protocol, session=None, port=None):
+    """确定目标端口并用固定协议握手；协议不符时直接报错，不尝试其他版本。"""
+    if session:
+        target = session_endpoint(project, session)
+    elif port:
+        target = {'port': port}
+    else:
+        found = discover()
+        if not found:
+            raise EngineError('未发现监听 Tracy 的游戏进程', 'profiler_unavailable',
+                              '先启动游戏（mcpy run），或用 --session / --port 指定目标。')
+        if len(found) > 1:
+            raise EngineError('发现多个游戏实例，请用 --session 或 --port 指定', 'ambiguous_target', endpoints=found)
+        target = found[0]
+    state = handshake(target['port'], protocol)
+    if state == 'welcome':
+        return dict(target, protocol=protocol)
+    if state == 'protocol_mismatch':
+        raise EngineError('游戏内置 Tracy 协议与固定版本（协议 %d）不一致' % protocol, 'protocol_mismatch',
+                          '不要换用其他 Tracy 版本；请反馈游戏版本，等待 mcpywrap 更新固定的分析器版本。', port=target['port'])
+    if state == 'busy':
+        raise EngineError('Tracy 端口 %d 已有分析器连接' % target['port'], 'profiler_busy', BUSY_HINT, port=target['port'])
+    raise EngineError('Tracy 端口 %d 不可用（%s）' % (target['port'], state), 'profiler_unavailable', port=target['port'])