xiaoli-cli/operit_py/hex_editor.py

# METADATA
# {
#     "name": "hex_editor",
#     "display_name": {
#         "zh": "十六进制编辑器",
#         "en": "Hex Editor"
#     },
#     "description": {
#         "zh": "一个面向二进制文件的轻量十六进制查看与修改工具包，支持查看指定偏移的 hex 窗口、按偏移写入字节序列，以及搜索指定 hex 模式。",
#         "en": "A lightweight binary hex inspection and patching toolkit. It can read hex windows at offsets, write byte sequences at offsets, and search for hex patterns."
#     },
#     "enabledByDefault": false,
#     "category": "File",
#     "tools": [
#         {
#             "name": "read_hex_window",
#             "description": {
#                 "zh": "读取二进制文件在指定偏移附近的十六进制窗口，并附带 ASCII 预览，便于快速定位和人工核对。",
#                 "en": "Read a hex window from a binary file at a specific offset, including an ASCII preview for quick inspection."
#             },
#             "parameters": [
#                 { "name": "file_path", "description": { "zh": "目标文件路径。", "en": "Target file path." }, "type": "string", "required": true },
#                 { "name": "offset", "description": { "zh": "起始偏移，可写十进制或 0x 开头的十六进制。", "en": "Start offset in decimal or 0x-prefixed hexadecimal." }, "type": "string", "required": true },
#                 { "name": "length", "description": { "zh": "读取字节数，默认 128，最大 4096。", "en": "Number of bytes to read. Default 128, max 4096." }, "type": "number", "required": false },
#                 { "name": "environment", "description": { "zh": "文件环境：android 或 linux，默认 android。", "en": "File environment: android or linux. Defaults to android." }, "type": "string", "required": false }
#             ]
#         },
#         {
#             "name": "write_hex_bytes",
#             "description": {
#                 "zh": "把给定的 hex 字节序列直接写入文件指定偏移。该工具会原地修改文件，不会自动生成回退文件。",
#                 "en": "Write a hex byte sequence directly into a file at the specified offset. This patches the file in place and does not create rollback files."
#             },
#             "parameters": [
#                 { "name": "file_path", "description": { "zh": "目标文件路径。", "en": "Target file path." }, "type": "string", "required": true },
#                 { "name": "offset", "description": { "zh": "写入起始偏移，可写十进制或 0x 开头的十六进制。", "en": "Write offset in decimal or 0x-prefixed hexadecimal." }, "type": "string", "required": true },
#                 { "name": "hex_bytes", "description": { "zh": "要写入的 hex 字节序列，例如 'DE AD BE EF' 或 'deadbeef'。", "en": "Hex bytes to write, for example 'DE AD BE EF' or 'deadbeef'." }, "type": "string", "required": true },
#                 { "name": "environment", "description": { "zh": "文件环境：android 或 linux，默认 android。", "en": "File environment: android or linux. Defaults to android." }, "type": "string", "required": false }
#             ]
#         },
#         {
#             "name": "find_hex_pattern",
#             "description": {
#                 "zh": "在二进制文件中搜索指定的 hex 模式，返回命中偏移以及每个命中点附近的十六进制窗口。",
#                 "en": "Search a binary file for a hex pattern and return matched offsets with nearby hex windows."
#             },
#             "parameters": [
#                 { "name": "file_path", "description": { "zh": "目标文件路径。", "en": "Target file path." }, "type": "string", "required": true },
#                 { "name": "hex_bytes", "description": { "zh": "要搜索的 hex 模式，例如 '50 4B 03 04'。", "en": "Hex pattern to search for, for example '50 4B 03 04'." }, "type": "string", "required": true },
#                 { "name": "max_results", "description": { "zh": "最多返回多少个命中，默认 20，最大 100。", "en": "Maximum number of matches to return. Default 20, max 100." }, "type": "number", "required": false },
#                 { "name": "environment", "description": { "zh": "文件环境：android 或 linux，默认 android。", "en": "File environment: android or linux. Defaults to android." }, "type": "string", "required": false }
#             ]
#         }
#     ]
# }

import base64
import math
import re
import traceback

DEFAULT_WINDOW_LENGTH = 128
MAX_WINDOW_LENGTH = 4096
DEFAULT_MAX_RESULTS = 20
MAX_RESULTS_LIMIT = 100
CONTEXT_BEFORE = 16
CONTEXT_TOTAL = 64
BYTES_PER_LINE = 16


def _is_finite(n):
    return isinstance(n, (int, float)) and not isinstance(n, bool) and math.isfinite(n)


def normalizeEnvironment(environment=None):
    value = str(environment or "android").strip().lower()
    if value != "android" and value != "linux":
        raise Exception("environment 只能是 android 或 linux。")
    return value


def normalizeBase64Input(value):
    cleaned = re.sub(r"\s+", "", str(value or ""))
    cleaned = cleaned.replace("-", "+").replace("_", "/")
    if not cleaned:
        return ""
    remainder = len(cleaned) % 4
    if remainder == 1:
        raise Exception("Invalid base64 string")
    if remainder == 0:
        return cleaned
    return cleaned + "=" * (4 - remainder)


def decodeBase64ToBytes(value):
    normalized = normalizeBase64Input(value)
    if not normalized:
        return []
    decoded = base64.b64decode(normalized)
    return list(decoded)


def encodeBytesToBase64(byte_list):
    raw = bytes((b & 0xFF) for b in byte_list)
    return base64.b64encode(raw).decode("ascii")


def parseOffset(value):
    trimmed = str(value or "").strip().lower()
    if not trimmed:
        raise Exception("offset 不能为空。")

    if re.match(r"^0x[0-9a-f]+$", trimmed):
        parsed = int(trimmed[2:], 16)
    elif re.match(r"^\d+$", trimmed):
        parsed = int(trimmed, 10)
    else:
        raise Exception("offset 必须是十进制数字或 0x 开头的十六进制。")

    if not _is_finite(parsed) or parsed < 0:
        raise Exception("offset 必须是大于等于 0 的整数。")
    return parsed


def clampPositiveInteger(value, defaultValue, maxValue, fieldName):
    actual = defaultValue if value is None else int(value)
    if not _is_finite(actual) or actual <= 0:
        raise Exception(f"{fieldName} 必须是大于 0 的整数。")
    return min(actual, maxValue)


def normalizeHexBytesInput(value):
    trimmed = str(value or "").strip()
    if not trimmed:
        raise Exception("hex_bytes 不能为空。")
    withoutPrefix = re.sub(r"^0x", "", trimmed, flags=re.IGNORECASE)
    normalized = re.sub(r"[^0-9a-fA-F]", "", withoutPrefix).lower()
    if not normalized:
        raise Exception("hex_bytes 中没有可用的十六进制字符。")
    if len(normalized) % 2 != 0:
        raise Exception("hex_bytes 必须包含偶数个十六进制字符。")
    return normalized


def parseHexBytes(value):
    normalized = normalizeHexBytesInput(value)
    bytes_list = []
    for i in range(0, len(normalized), 2):
        bytes_list.append(int(normalized[i:i + 2], 16))
    return bytes_list


def toHex(value, width):
    hex_str = format(max(0, int(value or 0)), "x").upper()
    while len(hex_str) < width:
        hex_str = "0" + hex_str
    return hex_str


def bytesToHexString(bytes_list):
    return " ".join(toHex(b, 2) for b in bytes_list)


def bytesToAscii(bytes_list):
    return "".join(chr(b) if 32 <= b <= 126 else "." for b in bytes_list)


def buildHexDump(bytes_list, startOffset):
    if len(bytes_list) == 0:
        return ""

    lines = []
    offsetWidth = max(8, len(format(startOffset + len(bytes_list), "x")))

    for index in range(0, len(bytes_list), BYTES_PER_LINE):
        slice_ = bytes_list[index:index + BYTES_PER_LINE]
        hexCells = [toHex(b, 2) for b in slice_]
        while len(hexCells) < BYTES_PER_LINE:
            hexCells.append("  ")
        left = " ".join(hexCells[:8])
        right = " ".join(hexCells[8:])
        ascii_str = bytesToAscii(slice_).ljust(BYTES_PER_LINE, " ")
        lines.append(f"{toHex(startOffset + index, offsetWidth)}  {left}  {right}  |{ascii_str}|")

    return "\n".join(lines)


async def ensureFileExists(path, environment):
    exists = await Tools.Files.exists(path, environment)
    if not exists.get("exists"):
        raise Exception(f"文件不存在: {path}")
    if exists.get("isDirectory"):
        raise Exception(f"目标路径是目录，不是文件: {path}")


async def readFileBytes(path, environment):
    await ensureFileExists(path, environment)
    result = await Tools.Files.readBinary(path, environment)
    base64_str = str(result.get("contentBase64") or "")
    return {
        "base64": base64_str,
        "bytes": decodeBase64ToBytes(base64_str),
        "size": int(result.get("size") or 0)
    }


async def writeFileBytes(path, bytes_list, environment):
    return await Tools.Files.writeBinary(path, encodeBytesToBase64(bytes_list), environment)


def collectWindow(bytes_list, offset, length):
    if offset > len(bytes_list):
        raise Exception(f"offset 超出文件范围。文件大小为 {len(bytes_list)} 字节。")
    end = min(len(bytes_list), offset + length)
    window = bytes_list[offset:end]
    return {
        "window": window,
        "actualLength": len(window)
    }


async def read_hex_window(params):
    environment = normalizeEnvironment(params.get("environment"))
    offset = parseOffset(params.get("offset"))
    length = clampPositiveInteger(params.get("length"), DEFAULT_WINDOW_LENGTH, MAX_WINDOW_LENGTH, "length")
    file = await readFileBytes(params["file_path"], environment)
    collected = collectWindow(file["bytes"], offset, length)
    window = collected["window"]
    actualLength = collected["actualLength"]

    return {
        "file_path": params["file_path"],
        "environment": environment,
        "file_size": file["size"],
        "offset_decimal": offset,
        "offset_hex": f"0x{toHex(offset, 8)}",
        "requested_length": length,
        "actual_length": actualLength,
        "end_offset_exclusive_decimal": offset + actualLength,
        "end_offset_exclusive_hex": f"0x{toHex(offset + actualLength, 8)}",
        "hex": bytesToHexString(window),
        "ascii_preview": bytesToAscii(window),
        "hex_dump": buildHexDump(window, offset)
    }


async def write_hex_bytes(params):
    environment = normalizeEnvironment(params.get("environment"))
    offset = parseOffset(params.get("offset"))
    patchBytes = parseHexBytes(params.get("hex_bytes"))
    file = await readFileBytes(params["file_path"], environment)

    if offset + len(patchBytes) > len(file["bytes"]):
        raise Exception(f"写入范围超出文件大小。文件大小 {len(file['bytes'])} 字节，尝试写入到 {offset + len(patchBytes)}。")

    beforeBytes = file["bytes"][offset:offset + len(patchBytes)]
    for i in range(len(patchBytes)):
        file["bytes"][offset + i] = patchBytes[i]

    writeResult = await writeFileBytes(params["file_path"], file["bytes"], environment)
    afterBytes = file["bytes"][offset:offset + len(patchBytes)]

    return {
        "file_path": params["file_path"],
        "environment": environment,
        "offset_decimal": offset,
        "offset_hex": f"0x{toHex(offset, 8)}",
        "bytes_written": len(patchBytes),
        "before_hex": bytesToHexString(beforeBytes),
        "after_hex": bytesToHexString(afterBytes),
        "write_result": writeResult
    }


async def find_hex_pattern(params):
    environment = normalizeEnvironment(params.get("environment"))
    patternBytes = parseHexBytes(params.get("hex_bytes"))
    maxResults = clampPositiveInteger(params.get("max_results"), DEFAULT_MAX_RESULTS, MAX_RESULTS_LIMIT, "max_results")
    file = await readFileBytes(params["file_path"], environment)
    matches = []

    if len(patternBytes) > len(file["bytes"]):
        return {
            "file_path": params["file_path"],
            "environment": environment,
            "file_size": file["size"],
            "pattern_hex": bytesToHexString(patternBytes),
            "match_count": 0,
            "matches": matches
        }

    for offset in range(0, len(file["bytes"]) - len(patternBytes) + 1):
        matched = True
        for index in range(len(patternBytes)):
            if file["bytes"][offset + index] != patternBytes[index]:
                matched = False
                break
        if not matched:
            continue

        contextStart = max(0, offset - CONTEXT_BEFORE)
        contextEnd = min(len(file["bytes"]), contextStart + CONTEXT_TOTAL)
        contextBytes = file["bytes"][contextStart:contextEnd]

        matches.append({
            "offset_decimal": offset,
            "offset_hex": f"0x{toHex(offset, 8)}",
            "matched_hex": bytesToHexString(patternBytes),
            "context_hex_dump": buildHexDump(contextBytes, contextStart)
        })

        if len(matches) >= maxResults:
            break

    return {
        "file_path": params["file_path"],
        "environment": environment,
        "file_size": file["size"],
        "pattern_hex": bytesToHexString(patternBytes),
        "match_count": len(matches),
        "matches": matches
    }


async def wrap(fn, params, successMessage, failureMessage):
    try:
        data = await fn(params)
        complete({
            "success": True,
            "message": successMessage,
            "data": data
        })
    except Exception as error:
        console.error(f"[hex_editor] {fn.__name__} failed:", error)
        complete({
            "success": False,
            "message": f"{failureMessage}: {str(error)}",
            "error_stack": traceback.format_exc()
        })


async def _exported_read_hex_window(params):
    await wrap(read_hex_window, params, "Hex 窗口读取成功。", "Hex 窗口读取失败")


async def _exported_write_hex_bytes(params):
    await wrap(write_hex_bytes, params, "Hex 字节写入成功。", "Hex 字节写入失败")


async def _exported_find_hex_pattern(params):
    await wrap(find_hex_pattern, params, "Hex 模式搜索成功。", "Hex 模式搜索失败")


exports.read_hex_window = _exported_read_hex_window
exports.write_hex_bytes = _exported_write_hex_bytes
exports.find_hex_pattern = _exported_find_hex_pattern