Community研究与数据分析github.com

steipete/hopper-debugger

使用 Hopper 动态反汇编器调试 macOS/iOS 二进制文件,解析 ObjC/Swift 符号,结合 dyld、LLDB 进行深度分析。

hopper-debugger 是什么?

该技能是一个基于 Hopper 反汇编器的 MCP 调试工具,专为 macOS/iOS 平台设计。它通过 `mcporter` 将 Hopper 作为可查询的反汇编器使用,并整合本地源码、LLDB 调试、日志和聚焦复现。技能支持打开框架二进制文件(如 AppKit、SwiftUI)、搜索符号/字符串/过程、查看伪代码和交叉引用。典型工作流程包括:从本地符号或运行时问题出发,逐步搜索并检查小范围目标代码,然后结合 LLDB 和日志验证假设。适用于 macOS 应用开发、逆向工程、菜单栏行为调试等场景,特别适合分析 AppKit 或 SwiftUI 内部的异常点击行为。支持平台为 macOS,需要 Hopper Disassembler 和 mcporter 运行。使用时应避免并发请求,注意导入状态的等待,并妥善处理超时和崩溃恢复。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/hopper-debugger

Installed? Explore more 研究与数据分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Hopper 调试器

目标:通过 mcporter 将 Hopper 用作可查询的反汇编器,然后将结果与本地源码、LLDB、日志和聚焦复现相结合。

快速开始

验证 MCP 服务器:

MCPORTER_LIST_TIMEOUT=15000 timeout 20 mcporter list hopper --brief

列出打开的 Hopper 文档:

MCPORTER_CALL_TIMEOUT=20000 timeout 30 mcporter call hopper.list_documents --output json

如果没有打开的文档,先在 Hopper 中打开二进制/框架文件:

open -a "Hopper Disassembler" /path/to/Binary

Hopper 可能会显示首次打开/导入对话框。让用户点击确认按钮,然后重试 MCP 调用。避免并发的 Hopper MCP 调用;在导入过程尚未稳定时,服务器可能会关闭传输或导致 Hopper 崩溃。

Apple 框架

优先使用已提取的 dyld 缓存框架二进制文件(当存在时):

/tmp/dsc-appkit/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit
/tmp/dsc-appkit/System/Library/Frameworks/SwiftUI.framework/Versions/A/SwiftUI

调试 SwiftUI/AppKit 边界问题时,一次打开一个:

open -a "Hopper Disassembler" /tmp/dsc-appkit/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit
mcporter call hopper.list_documents --output json

open -a "Hopper Disassembler" /tmp/dsc-appkit/System/Library/Frameworks/SwiftUI.framework/Versions/A/SwiftUI
mcporter call hopper.list_documents --output json

验证访问:

mcporter call hopper.list_documents --output json
mcporter call hopper.current_document --output json
mcporter call hopper.search_strings pattern=SwiftUI --output json
mcporter call hopper.search_strings pattern=NSStatusItem --output json

文档名称可能以 Untitled 开头;在 Hopper 完成导入后重试。使用 current_document、符号/字符串搜索以及窗口标题变化来区分 AppKit 和 SwiftUI。

查询工作流

  1. 从需要解释的本地源码路径或运行时符号开始。
  2. 搜索名称/过程/字符串:
mcporter call hopper.search_procedures pattern='NSStatusBar' --output json
mcporter call hopper.search_name pattern='NSStatusBarButtonCell' --output json
mcporter call hopper.search_strings pattern='NSStatusItem' --output json
  1. 一次检查一个小目标:
mcporter call hopper.procedure_info procedure='<symbol>' --output json
mcporter call hopper.procedure_assembly procedure='<symbol>' --output json
mcporter call hopper.procedure_pseudo_code procedure='<symbol>' --output json
mcporter call hopper.procedure_callers procedure='<symbol>' --output json
mcporter call hopper.procedure_callees procedure='<symbol>' --output json
mcporter call hopper.xrefs address=0x12345678 --output json
  1. 总结相关控制流;不要粘贴大量反编译代码。
  2. 在修改应用代码之前,使用 LLDB/日志/复现来验证假设。

状态项 / 菜单点击错误

有用的 AppKit/SwiftUI 搜索:

mcporter call hopper.search_strings pattern='NSStatusItem_Private_ForSwiftUI' --output json
mcporter call hopper.search_procedures pattern='popUpStatusBarMenu' --output json
mcporter call hopper.search_procedures pattern='trackMouse' --output json
mcporter call hopper.search_name pattern='NSStatusBarButtonCell' --output json
mcporter call hopper.search_name pattern='NSStatusItem' --output json

当菜单栏点击无响应时,值得检查的符号:

  • -[NSStatusBarButtonCell trackMouse:inRect:ofView:untilMouseUp:]
  • -[NSStatusBarButtonCell _sendActionFrom:]
  • -[NSStatusItem popUpStatusBarMenu:]
  • -[NSApplication sendAction:to:from:]
  • 引用 NSStatusItem_Private_ForSwiftUI 的 SwiftUI 状态/菜单符号

将反汇编结果与运行时状态对比:

pgrep -af "App.app/Contents/MacOS/App"
lldb /path/to/debug/Binary

对于加固签名的应用,若没有 get-task-allow 权限,附加可能会失败;必要时在 LLDB 下直接启动原始调试二进制文件。

失败处理

  • 使用 timeout 包装 Hopper 调用;模态框/导入或关闭的文档可能导致传输卡住。
  • 导入期间不要发送并发的 Hopper MCP 请求。如果某个查询代价较高,等待其完成后再发起下一个。
  • 如果调用报告 Connection closed,检查 Hopper 模态框,确认后重试。
  • 如果 Hopper 崩溃,重新打开单个文档,等待导入/分析完成,然后重新运行 list_documents 再进行深入搜索。
  • 如果 mcporter 卡住,先检查进程再杀死任何内容:
pgrep -af 'mcporter|HopperMCPServer|Hopper Disassembler'
  • 优先重启 mcporter 守护进程而不是大范围杀进程:
mcporter daemon stop
mcporter daemon start

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

steipete/nano-banana-pro

Nano Banana/Gemini image gen/edit: text/image input, 512-4K workflows.

相关技能