mcpywrap-core 0.6.0__py3-none-any.whl

mcpywrap_core/__init__.py

@@ -0,0 +1,2 @@
+"""Shared mcpy engineering implementation."""
+from ._version import __version__

mcpywrap_core/__main__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""
+mcpywrap 命令行工具的入口点
+"""
+
+from .cli import cli
+
+def main():
+    """主函数，作为 CLI 入口点"""
+    import sys
+    # Keep the caller's text encoding; unsupported symbols must not abort an operation.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, 'reconfigure'):
+            stream.reconfigure(errors='backslashreplace')
+    cli()
+
+if __name__ == "__main__":
+    main()

mcpywrap_core/_script_worker.py

@@ -0,0 +1,278 @@
+"""Private finite-script supervisor. Invoked by absolute path; never a public CLI."""
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import time
+
+import psutil
+
+
+def identity(pid):
+    p = psutil.Process(pid)
+    return {'pid': pid, 'created_at': p.create_time(), 'executable': p.exe()}
+
+
+def alive(record):
+    try:
+        p = psutil.Process(record['pid'])
+        return abs(p.create_time() - record['created_at']) < .01 and p.status() != psutil.STATUS_ZOMBIE
+    except psutil.NoSuchProcess:
+        return False
+
+
+def save(path, data):
+    temporary = path.with_suffix('.writing')
+    temporary.write_text(json.dumps(data, ensure_ascii=True), encoding='utf-8')
+    for attempt in range(10):
+        try:
+            temporary.replace(path)
+            return
+        except PermissionError:
+            if os.name != 'nt' or attempt == 9: raise
+            time.sleep(.02)
+
+
+class WindowsJob:
+    """Closing the supervisor's handle terminates its assigned command tree."""
+    def __init__(self):
+        import ctypes as c
+        from ctypes import wintypes as w
+        class Basic(c.Structure):
+            _fields_ = [('PerProcessUserTimeLimit', c.c_longlong), ('PerJobUserTimeLimit', c.c_longlong),
+                        ('LimitFlags', w.DWORD), ('MinimumWorkingSetSize', c.c_size_t),
+                        ('MaximumWorkingSetSize', c.c_size_t), ('ActiveProcessLimit', w.DWORD),
+                        ('Affinity', c.c_size_t), ('PriorityClass', w.DWORD), ('SchedulingClass', w.DWORD)]
+        class IO(c.Structure):
+            _fields_ = [(name, c.c_ulonglong) for name in ('ReadOperationCount', 'WriteOperationCount',
+                       'OtherOperationCount', 'ReadTransferCount', 'WriteTransferCount', 'OtherTransferCount')]
+        class Extended(c.Structure):
+            _fields_ = [('BasicLimitInformation', Basic), ('IoInfo', IO),
+                        ('ProcessMemoryLimit', c.c_size_t), ('JobMemoryLimit', c.c_size_t),
+                        ('PeakProcessMemoryUsed', c.c_size_t), ('PeakJobMemoryUsed', c.c_size_t)]
+        self.kernel = c.WinDLL('kernel32', use_last_error=True)
+        self.kernel.CreateJobObjectW.argtypes = [c.c_void_p, w.LPCWSTR]
+        self.kernel.CreateJobObjectW.restype = w.HANDLE
+        self.kernel.SetInformationJobObject.argtypes = [w.HANDLE, c.c_int, c.c_void_p, w.DWORD]
+        self.kernel.AssignProcessToJobObject.argtypes = [w.HANDLE, w.HANDLE]
+        self.kernel.QueryInformationJobObject.argtypes = [w.HANDLE, c.c_int, c.c_void_p, w.DWORD, c.c_void_p]
+        self.kernel.TerminateJobObject.argtypes = [w.HANDLE, w.UINT]
+        self.kernel.OpenProcess.argtypes = [w.DWORD, w.BOOL, w.DWORD]
+        self.kernel.OpenProcess.restype = w.HANDLE
+        self.kernel.IsProcessInJob.argtypes = [w.HANDLE, w.HANDLE, c.POINTER(w.BOOL)]
+        self.kernel.WaitForSingleObject.argtypes = [w.HANDLE, w.DWORD]
+        self.kernel.WaitForSingleObject.restype = w.DWORD
+        self.kernel.CloseHandle.argtypes = [w.HANDLE]
+        self.kernel.OpenThread.argtypes = [w.DWORD, w.BOOL, w.DWORD]
+        self.kernel.OpenThread.restype = w.HANDLE
+        self.kernel.ResumeThread.argtypes = [w.HANDLE]
+        self.kernel.ResumeThread.restype = w.DWORD
+        self.handle = self.kernel.CreateJobObjectW(None, None)
+        if not self.handle: raise c.WinError(c.get_last_error())
+        info = Extended(); info.BasicLimitInformation.LimitFlags = 0x2000  # KILL_ON_JOB_CLOSE
+        if not self.kernel.SetInformationJobObject(self.handle, 9, c.byref(info), c.sizeof(info)):
+            error = c.WinError(c.get_last_error()); self.close(); raise error
+
+    def assign(self, process):
+        import ctypes as c
+        if not self.kernel.AssignProcessToJobObject(self.handle, int(process._handle)):
+            raise c.WinError(c.get_last_error())
+        # The command was created suspended: no child can escape before job assignment.
+        threads = psutil.Process(process.pid).threads()
+        if not threads:
+            raise RuntimeError('脚本主线程不存在')
+        thread = self.kernel.OpenThread(0x0002, False, threads[0].id)
+        if not thread:
+            raise c.WinError(c.get_last_error())
+        try:
+            if self.kernel.ResumeThread(thread) == 0xffffffff:
+                raise c.WinError(c.get_last_error())
+        finally:
+            self.kernel.CloseHandle(thread)
+
+    def close(self):
+        if self.handle:
+            self.kernel.CloseHandle(self.handle)
+            self.handle = None
+
+    def process_ids(self):
+        import ctypes as c
+        from ctypes import wintypes as w
+        capacity = 16
+        for _ in range(8):
+            class ProcessIds(c.Structure):
+                _fields_ = [('assigned', w.DWORD), ('listed', w.DWORD),
+                            ('ids', c.c_size_t * capacity)]
+            info = ProcessIds()
+            # JobObjectBasicProcessIdList retains descendants after their
+            # parent exits. A concurrent spawn may require a larger buffer.
+            if self.kernel.QueryInformationJobObject(self.handle, 3, c.byref(info), c.sizeof(info), None):
+                return list(info.ids[:info.listed])
+            error = c.get_last_error()
+            if error != 234:  # ERROR_MORE_DATA
+                raise c.WinError(error)
+            capacity = max(capacity * 2, info.assigned)
+        raise RuntimeError('脚本进程树持续增长，无法确认成员')
+
+    def active_count(self):
+        import ctypes as c
+        from ctypes import wintypes as w
+        count = 0
+        for pid in self.process_ids():
+            handle = self.kernel.OpenProcess(0x00100000 | 0x1000, False, pid)  # SYNCHRONIZE | QUERY_LIMITED_INFORMATION
+            if not handle:
+                error = c.get_last_error()
+                if error == 87:  # ERROR_INVALID_PARAMETER: process already gone
+                    continue
+                raise c.WinError(error)
+            try:
+                belongs = w.BOOL()
+                if not self.kernel.IsProcessInJob(handle, self.handle, c.byref(belongs)):
+                    raise c.WinError(c.get_last_error())
+                if not belongs.value:
+                    continue  # The PID may have been reused outside this job.
+                state = self.kernel.WaitForSingleObject(handle, 0)
+                if state == 258:  # WAIT_TIMEOUT: process is still running
+                    count += 1
+                elif state != 0:  # WAIT_OBJECT_0: process has exited
+                    raise c.WinError(c.get_last_error())
+            finally:
+                self.kernel.CloseHandle(handle)
+        return count
+
+    def terminate(self):
+        import ctypes as c
+        if not self.kernel.TerminateJobObject(self.handle, 1):
+            raise c.WinError(c.get_last_error())
+
+
+def members(process, known):
+    try:
+        for p in psutil.Process(process.pid).children(recursive=True):
+            known[p.pid] = identity(p.pid)
+    except psutil.NoSuchProcess:
+        pass
+    if os.name != 'nt':
+        for p in psutil.process_iter(['pid', 'status']):
+            try:
+                if p.info['status'] != psutil.STATUS_ZOMBIE and os.getpgid(p.pid) == process.pid:
+                    known[p.pid] = identity(p.pid)
+            except (ProcessLookupError, PermissionError, psutil.NoSuchProcess):
+                pass
+    return [r for r in known.values() if alive(r)]
+
+
+def finish_tree(process, known, job):
+    if job:
+        # Keep the job handle until exit is verified, including descendants
+        # never observed by psutil. Closing it alone only requests termination.
+        job.terminate()
+        if process.poll() is None:
+            process.kill()  # Also handles failure to assign a suspended child.
+        process.wait(timeout=3)
+        deadline = time.monotonic() + 2
+        while job.active_count():
+            if time.monotonic() >= deadline:
+                raise RuntimeError('脚本后代进程尚未确认退出')
+            time.sleep(.05)
+        return
+    if os.name != 'nt':
+        try: os.killpg(process.pid, signal.SIGTERM)
+        except ProcessLookupError: pass
+    pending = members(process, known)
+    for record in pending:
+        try: psutil.Process(record['pid']).terminate()
+        except psutil.NoSuchProcess: pass
+    deadline = time.monotonic() + 2
+    while time.monotonic() < deadline and any(alive(r) for r in pending):
+        process.poll()
+        time.sleep(.05)
+    remaining = members(process, known)
+    if not remaining:
+        process.wait(timeout=3)
+        return
+    if os.name != 'nt':
+        try: os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError: pass
+    for record in remaining:
+        if alive(record):
+            try: psutil.Process(record['pid']).kill()
+            except psutil.NoSuchProcess: pass
+    process.wait(timeout=3)
+    deadline = time.monotonic() + 2
+    while time.monotonic() < deadline:
+        if not any(alive(r) for r in known.values()): return
+        time.sleep(.05)
+    raise RuntimeError('脚本后代进程尚未确认退出')
+
+
+def main():
+    spec = json.loads(sys.stdin.buffer.read())
+    path = Path(spec.pop('result'))
+    command, timeout = spec.pop('command'), spec.pop('timeout')
+    cancel, parent = Path(spec.pop('cancel')), spec.pop('parent')
+    state = dict(spec, supervisor=identity(os.getpid()), state='starting')
+    process, job, known = None, None, {}
+    started = time.monotonic()
+    try:
+        save(path, state)
+        if not alive(parent) or cancel.exists():
+            state.update(state='cancelled', code='script_cancelled')
+            return
+        if os.name == 'nt': job = WindowsJob()
+        state['state'] = 'spawning'; save(path, state)
+        process = subprocess.Popen(command, stdin=subprocess.DEVNULL,
+                                   **({'creationflags': subprocess.CREATE_NO_WINDOW | subprocess.CREATE_NEW_PROCESS_GROUP | 0x00000004}
+                                      if os.name == 'nt' else {'start_new_session': True}))
+        try:
+            child = identity(process.pid)
+        except psutil.ZombieProcess:
+            child = {'pid': process.pid, 'created_at': psutil.Process(process.pid).create_time(), 'executable': command[0]}
+        state.update(child=child, group=process.pid if os.name != 'nt' else None, state='running')
+        known[process.pid] = child
+        save(path, state)
+        if job: job.assign(process)
+        while process.poll() is None:
+            if not job:
+                members(process, known)
+            if cancel.exists() or not alive(parent):
+                state.update(state='cancelled', code='script_cancelled', error='操作已取消或调用进程已退出')
+                break
+            if time.monotonic() - started >= timeout:
+                state.update(state='timed_out', code='script_timeout', error='执行超时')
+                break
+            time.sleep(.05)
+        else:
+            # Windows 的 Job 是所有权依据。父进程退出后再按 PID 查询树，
+            # 可能观察到复用该 PID 的无关进程；同时给短暂的退出收尾留出时间。
+            descendants = [] if job else [r for r in members(process, known) if r['pid'] != process.pid]
+            remaining = job.active_count() if job else 0
+            settle_deadline = time.monotonic() + .2
+            while remaining and time.monotonic() < settle_deadline:
+                time.sleep(.01)
+                remaining = job.active_count()
+            state.update(state='completed' if process.returncode == 0 else 'failed',
+                         code=None if process.returncode == 0 else 'script_failed', exit_code=process.returncode)
+            if descendants or remaining:
+                state.update(state='failed', code='script_background_process', error='有限任务不能遗留后台进程')
+    except BaseException as exc:
+        state.update(state='failed', code='script_start_failed', error=str(exc))
+    finally:
+        if process:
+            try:
+                finish_tree(process, known, job)
+            except BaseException as exc:
+                import traceback
+                traceback.print_exc()
+                state.update(state='recovery_required', code='script_recovery_required', error=str(exc))
+            state.setdefault('exit_code', process.returncode)
+        if job: job.close()
+        state['duration'] = time.monotonic() - started
+        state['finished_at'] = time.time()
+        save(path, state)
+
+
+if __name__ == '__main__':
+    main()

mcpywrap_core/_version.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

mcpywrap_core/api.py

@@ -0,0 +1,69 @@
+"""Versioned engineering API. All frontends call the same operation functions."""
+from pathlib import Path
+
+from . import __version__
+from .host import HOST_API, HostServices, host_scope, current_host
+
+CORE_API = 1
+OPERATIONS = ('resolve', 'build', 'package', 'sync')
+
+
+class Core:
+    def __init__(self, host=None):
+        self.host = host or current_host()
+
+    def describe(self):
+        return {'core_api': CORE_API, 'host_api': HOST_API, 'version': __version__,
+                'operations': list(OPERATIONS), 'capabilities': self.host.capabilities()}
+
+    def execute(self, operation, project, **options):
+        """Execute or raise the original structured error; never invoke another core."""
+        if operation not in OPERATIONS:
+            raise ValueError('未知工程操作：' + str(operation))
+        allowed = {'resolve': set(), 'build': {'merge'}, 'package': {'merge'},
+                   'sync': {'install', 'migrate_windows_lock'}}[operation]
+        if set(options) - allowed or any(type(value) is not bool for value in options.values()):
+            raise ValueError('无效的工程操作参数')
+        project = Path(project).expanduser().resolve()
+        if not project.is_dir() or not (project/'pyproject.toml').is_file():
+            raise ValueError('未找到项目 pyproject.toml：' + str(project))
+        from .command_context import project_scope
+        with host_scope(self.host), project_scope(project) as context:
+            if operation == 'resolve':
+                from .dependencies import DependencyService
+                manager = DependencyService(project).resolve()
+                result = {'project': str(project), 'dependencies': [
+                    {'name': pack.pkg_name, 'path': str(pack.path)}
+                    for pack in manager.get_all_dependencies().values()], 'warnings': manager.warnings}
+            elif operation == 'build':
+                from .operations.build import build_project
+                result = build_project(project, **options)
+            elif operation == 'package':
+                from .operations.package import package_project
+                result = package_project(project, **options)
+            else:
+                from .operations.sync import sync_project
+                result = sync_project(project, **options)
+            if context.warnings:
+                result['warnings'] = list(dict.fromkeys([*result.get('warnings', []), *context.warnings]))
+            return result
+
+    def request(self, request):
+        """Transport-neutral envelope. Authentication/path grants belong to the host.
+
+        The host resolves an authorized project ID to a path before calling this
+        method. Do not expose raw caller-supplied paths on an unauthenticated port.
+        """
+        try:
+            if not isinstance(request, dict) or request.get('core_api') != CORE_API:
+                raise ValueError('不兼容的核心协议')
+            if request.get('operation') == 'describe':
+                return {'ok': True, 'result': self.describe()}
+            options = request.get('options', {})
+            if not isinstance(options, dict) or not isinstance(request.get('project'), str):
+                raise ValueError('无效的工程请求')
+            result = self.execute(request.get('operation'), request['project'], **options)
+            return {'ok': True, 'result': result, 'core': self.describe()}
+        except (ValueError, OSError) as error:
+            return {'ok': False, 'error': str(error), 'code': getattr(error, 'code', 'operation_failed'),
+                    'hint': getattr(error, 'hint', None), 'details': getattr(error, 'details', {})}

mcpywrap_core/builders/AddonsPack.py

@@ -0,0 +1,310 @@
+# -*- coding: utf-8 -*-
+
+import os
+import shutil
+import click
+
+from ..utils.utils import ensure_dir
+from .file_merge import try_merge_file
+
+# Python 包管理和其他应该忽略的文件和目录
+EXCLUDED_PATTERNS = [
+    # Python 包管理
+    ".egg-info",
+    "__pycache__",
+    ".pyc",
+    ".pyo",
+    ".pyd",
+    ".so",
+    ".dll",
+    ".eggs",
+    ".pytest_cache",
+    ".tox",
+    ".coverage",
+    ".coverage.*",
+    "htmlcov",
+    # 版本控制
+    ".git",
+    ".hg",
+    ".svn",
+    ".bzr",
+    # 其他临时文件
+    ".DS_Store",
+    "Thumbs.db"
+]
+
+MANIFEST_FILES = [
+    "manifest.json",
+    "pack_manifest.json"
+]
+
+
+class AddonsPack(object):
+
+    pkg_name: str
+    path: str
+    is_origin: bool
+    behavior_pack_dir: str
+    resource_pack_dir: str
+
+    def __init__(self, pkg_name, path, is_origin=False):
+        self.pkg_name = pkg_name
+        self.path = os.path.abspath(path)
+        self.is_origin = is_origin
+        self.behavior_pack_dir = None
+        self.resource_pack_dir = None
+        # 进入此目录，查找内部的行为包和资源包的路径
+        for item in os.listdir(self.path):
+            item_path = os.path.join(self.path, item)
+            if os.path.isdir(item_path):
+                if item.startswith("behavior_pack") or item.startswith("BehaviorPack"):
+                    self.behavior_pack_dir = item_path
+                elif item.startswith("resource_pack") or item.startswith("ResourcePack"):
+                    self.resource_pack_dir = item_path
+        if not self.behavior_pack_dir:
+            self.behavior_pack_dir = os.path.join(self.path, "behavior_pack")
+        if not self.resource_pack_dir:
+            self.resource_pack_dir = os.path.join(self.path, "resource_pack")
+
+    def should_exclude(self, path):
+        """判断文件或目录是否应该被排除"""
+        # Only inspect components inside this pack. A checkout named demo.git-copy
+        # or a perfectly valid terrain.soil.json is not an excluded artifact.
+        from pathlib import Path
+        if os.name == 'nt':
+            # Python 3.9 treats C: and \\?\C: as different relpath mounts.
+            # Cache paths use the extended spelling; resolved files may not.
+            from ..source_files import long_path
+            relative = os.path.relpath(long_path(path), long_path(self.path))
+        else:
+            relative = os.path.relpath(path, self.path)
+        parts = Path(relative).parts
+        directories = {'.git', '.hg', '.svn', '.eggs', '.pytest_cache', '.tox',
+                       '.bzr', '__pycache__', 'htmlcov'}
+        if any(part in directories or part.endswith('.egg-info') for part in parts):
+            return True
+        name = parts[-1] if parts else ''
+        if (name in ('.DS_Store', 'Thumbs.db', '.coverage') or name.startswith('.coverage.')
+                or Path(name).suffix.lower() in ('.pyc', '.pyo', '.pyd', '.so', '.dll')):
+            return True
+        # 得到文件名
+        filename = os.path.basename(path)
+        if not self.is_origin and filename in MANIFEST_FILES:
+            return True
+        return False
+
+    def copy_behavior_to(self, target_dir: str, rename: str = None):
+        """
+        复制行为包和资源包到目标目录
+        target_dir为父目录
+        """
+        if self.behavior_pack_dir:
+            target_path = os.path.join(target_dir, os.path.basename(self.behavior_pack_dir) if not rename else rename)
+            os.makedirs(target_path, exist_ok=True)
+
+            # 使用自定义复制函数而不是shutil.copytree
+            for root, dirs, files in os.walk(self.behavior_pack_dir):
+                # 过滤掉应该排除的目录
+                dirs[:] = [d for d in dirs if not self.should_exclude(os.path.join(root, d))]
+
+                # 计算相对路径
+                rel_path = os.path.relpath(root, self.behavior_pack_dir)
+                # 计算目标目录
+                target_root = os.path.join(target_path, rel_path) if rel_path != '.' else target_path
+                ensure_dir(target_root)
+
+                # 复制文件
+                for file in files:
+                    src_file = os.path.join(root, file)
+                    if not self.should_exclude(src_file):
+                        dest_file = os.path.join(target_root, file)
+                        # 如果是Python文件，检查并添加编码声明
+                        if file.endswith('.py'):
+                            self._copy_with_encoding_check(src_file, dest_file)
+                        else:
+                            shutil.copy2(src_file, dest_file)
+
+    def copy_resource_to(self, target_dir: str, rename: str = None):
+        """
+        复制资源包到目标目录
+        target_dir为父目录
+        """
+        if self.resource_pack_dir:
+            target_path = os.path.join(target_dir, os.path.basename(self.resource_pack_dir) if not rename else rename)
+            os.makedirs(target_path, exist_ok=True)
+
+            # 使用自定义复制函数而不是shutil.copytree
+            for root, dirs, files in os.walk(self.resource_pack_dir):
+                # 过滤掉应该排除的目录
+                dirs[:] = [d for d in dirs if not self.should_exclude(os.path.join(root, d))]
+
+                # 计算相对路径
+                rel_path = os.path.relpath(root, self.resource_pack_dir)
+                # 计算目标目录
+                target_root = os.path.join(target_path, rel_path) if rel_path != '.' else target_path
+                ensure_dir(target_root)
+
+                # 复制文件
+                for file in files:
+                    src_file = os.path.join(root, file)
+                    if not self.should_exclude(src_file):
+                        dest_file = os.path.join(target_root, file)
+                        # 如果是Python文件，检查并添加编码声明
+                        if file.endswith('.py'):
+                            self._copy_with_encoding_check(src_file, dest_file)
+                        else:
+                            shutil.copy2(src_file, dest_file)
+
+    def merge_behavior_into(self, target_behavior_dir: str):
+        """合并行为包到目标行为包目录"""
+        if self.behavior_pack_dir:
+            for root, dirs, files in os.walk(self.behavior_pack_dir):
+                # 过滤掉应该排除的目录
+                dirs[:] = [d for d in dirs if not self.should_exclude(os.path.join(root, d))]
+
+                # 计算相对路径
+                rel_path = os.path.relpath(root, self.behavior_pack_dir)
+                # 计算目标目录
+                target_root = os.path.join(target_behavior_dir, rel_path) if rel_path != '.' else target_behavior_dir
+                ensure_dir(target_root)
+
+                # 复制文件
+                for file in files:
+                    src_file = os.path.join(root, file)
+                    if not self.should_exclude(src_file):
+                        # 计算源文件的相对路径
+                        src_rel_path = os.path.relpath(src_file, self.behavior_pack_dir)
+                        dest_file = os.path.join(target_root, file)
+                        self.merge_behavior_single_file_to(src_rel_path, dest_file)
+
+    def merge_resource_into(self, target_resource_dir: str):
+        """合并资源包到目标资源包目录"""
+        if self.resource_pack_dir:
+            for root, dirs, files in os.walk(self.resource_pack_dir):
+                # 过滤掉应该排除的目录
+                dirs[:] = [d for d in dirs if not self.should_exclude(os.path.join(root, d))]
+
+                # 计算相对路径
+                rel_path = os.path.relpath(root, self.resource_pack_dir)
+                # 计算目标目录
+                target_root = os.path.join(target_resource_dir, rel_path) if rel_path != '.' else target_resource_dir
+                ensure_dir(target_root)
+
+                # 复制文件
+                for file in files:
+                    src_file = os.path.join(root, file)
+                    if not self.should_exclude(src_file):
+                        # 计算源文件的相对路径
+                        src_rel_path = os.path.relpath(src_file, self.resource_pack_dir)
+                        dest_file = os.path.join(target_root, file)
+                        self.merge_resource_single_file_to(src_rel_path, dest_file)
+
+    def merge_behavior_single_file_to(self, src_rel_path: str, dest_abs_path: str):
+        """合并行为包单个文件，src为相对路径，dest为绝对路径"""
+        if self.behavior_pack_dir:
+            src_file = os.path.join(self.behavior_pack_dir, src_rel_path)
+            if os.path.exists(src_file):
+                self._merge_single_file(src_file, dest_abs_path)
+                return True
+        return False
+    
+    def merge_resource_single_file_to(self, src_rel_path: str, dest_abs_path: str):
+        """合并资源包单个文件，src为相对路径，dest为绝对路径"""
+        if self.resource_pack_dir:
+            src_file = os.path.join(self.resource_pack_dir, src_rel_path)
+            if os.path.exists(src_file):
+                self._merge_single_file(src_file, dest_abs_path)
+                return True
+        return False
+    
+    def _merge_single_file(self, src_file: str, dest_file: str):
+        """合并单个文件"""
+        if os.path.exists(dest_file):
+            if self.should_exclude(dest_file):
+                return
+            # 处理文件冲突
+            if src_file.endswith('.py'):
+                self._copy_with_encoding_check(src_file, dest_file)
+            elif os.path.exists(dest_file):
+                suc, reason = try_merge_file(src_file, dest_file)
+                if not suc:
+                    click.secho(f"⚠️ 警告: 文件合并异常 {src_file} -> {dest_file} {reason}", fg="yellow")
+        else:
+            shutil.copy2(src_file, dest_file)
+
+    def _copy_with_encoding_check(self, src_file, dest_file):
+        """复制Python文件，并检查添加编码声明"""
+        try:
+            import re
+            from pathlib import Path
+            content = Path(src_file).read_bytes()
+            # Preserve ASCII, BOM and valid PEP 263 declarations byte-for-byte.
+            # Only undeclared non-ASCII UTF-8 needs Python 2's encoding header.
+            declared = any(re.search(br'^[ \t\f]*#.*?coding[:=][ \t]*[-\w.]+', line)
+                           for line in content.splitlines()[:2])
+            if not declared and not content.startswith(b'\xef\xbb\xbf') and any(b >= 128 for b in content):
+                content.decode('utf-8')
+                newline = b'\r\n' if b'\r\n' in content else b'\n'
+                header = b'# -*- coding: utf-8 -*-' + newline
+                if content.startswith(b'#!') and b'\n' in content:
+                    first, rest = content.split(b'\n', 1)
+                    content = first + b'\n' + header + rest
+                else:
+                    content = header + content
+            Path(dest_file).write_bytes(content)
+
+            # 复制文件元数据
+            shutil.copystat(src_file, dest_file)
+        except Exception as e:
+            click.secho(f"⚠️ 添加编码声明时出错: {src_file} -> {dest_file}: {str(e)}", fg="yellow")
+            # 如果出错，则直接复制
+            shutil.copy2(src_file, dest_file)
+
+    def is_behavior_file(self, file_path):
+        """
+        判断文件是否为行为包文件
+        
+        Args:
+            file_path: 文件路径
+            
+        Returns:
+            bool: 如果是行为包文件返回True
+        """
+        return "behavior_pack" in file_path.lower() or "behaviorpack" in file_path.lower()
+    
+    def is_resource_file(self, file_path):
+        """
+        判断文件是否为资源包文件
+        
+        Args:
+            file_path: 文件路径
+            
+        Returns:
+            bool: 如果是资源包文件返回True
+        """
+        return "resource_pack" in file_path.lower() or "resourcepack" in file_path.lower()
+    
+    def get_relative_path_in_pack(self, file_path):
+        """
+        获取文件在包中的相对路径
+        
+        Args:
+            file_path: 文件的绝对路径
+            
+        Returns:
+            tuple: (是否为包文件, 包类型, 相对路径)
+                包类型: "behavior" 或 "resource"
+                相对路径: 在包中的相对路径，如果不在包中则为None
+        """
+        # Watchdog 可能返回短路径或目录链接路径；保留相对文件名大小写。
+        absolute = os.path.realpath(file_path)
+        for kind, folder in (("behavior", self.behavior_pack_dir), ("resource", self.resource_pack_dir)):
+            if not folder:
+                continue
+            folder = os.path.realpath(folder)
+            try:
+                if os.path.commonpath([os.path.normcase(absolute), os.path.normcase(folder)]) == os.path.normcase(folder):
+                    return True, kind, os.path.relpath(absolute, folder)
+            except ValueError:
+                continue
+        return False, None, None