{"id":50945976,"url":"https://github.com/dxiongya/debug-kit","last_synced_at":"2026-06-17T20:06:20.588Z","repository":{"id":364302927,"uuid":"1267322057","full_name":"dxiongya/debug-kit","owner":"dxiongya","description":"🧩 Agent Skill: drive, inspect \u0026 test apps across 9 platforms (macOS/iOS/Android/Web/Electron/Flutter/RN/Tauri/Chrome-ext) — background, no cursor hijack, with a virtual pointer. Install: npx skills add dxiongya/debug-kit","archived":false,"fork":false,"pushed_at":"2026-06-12T12:53:01.000Z","size":149,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T14:23:57.080Z","etag":null,"topics":["accessibility","agent-skill","agent-skills","ai-agent","app-testing","claude-code","claude-skill","computer-use","cross-platform","skills"],"latest_commit_sha":null,"homepage":"https://skills.sh/dxiongya/debug-kit","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dxiongya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T12:38:44.000Z","updated_at":"2026-06-12T12:53:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dxiongya/debug-kit","commit_stats":null,"previous_names":["dxiongya/debug-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dxiongya/debug-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxiongya%2Fdebug-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxiongya%2Fdebug-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxiongya%2Fdebug-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxiongya%2Fdebug-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dxiongya","download_url":"https://codeload.github.com/dxiongya/debug-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxiongya%2Fdebug-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34463572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","agent-skill","agent-skills","ai-agent","app-testing","claude-code","claude-skill","computer-use","cross-platform","skills"],"created_at":"2026-06-17T20:06:19.831Z","updated_at":"2026-06-17T20:06:20.583Z","avatar_url":"https://github.com/dxiongya.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e🧩 debug-kit\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cb\u003eAn \u003ca href=\"https://docs.claude.com/en/docs/claude-code/skills\"\u003eAgent Skill\u003c/a\u003e for Claude Code (and Cursor · Codex · Cline · Gemini CLI …)\u003c/b\u003e\u003cbr/\u003e\nInstall it once and your AI gains hands \u0026amp; eyes to \u003cb\u003edrive, inspect, and test real apps across 9 platforms\u003c/b\u003e —\u003cbr/\u003e\nin the background, \u003cb\u003ewithout ever touching your real cursor\u003c/b\u003e, with a virtual pointer you can watch.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://skills.sh/dxiongya/debug-kit\"\u003e\u003cimg alt=\"Agent Skill\" src=\"https://img.shields.io/badge/Agent-Skill-7c3aed\"\u003e\u003c/a\u003e\n\u003ca href=\"https://skills.sh/dxiongya/debug-kit\"\u003e\u003cimg alt=\"install: npx skills add\" src=\"https://img.shields.io/badge/install-npx_skills_add-black?logo=npm\"\u003e\u003c/a\u003e\n\u003ca href=\"https://docs.claude.com/en/docs/claude-code/skills\"\u003e\u003cimg alt=\"Claude Code Skill\" src=\"https://img.shields.io/badge/Claude_Code-Skill-d97757\"\u003e\u003c/a\u003e\n\u003ca href=\"https://skills.sh/dxiongya/debug-kit\"\u003e\u003cimg alt=\"skills.sh\" src=\"https://skills.sh/b/dxiongya/debug-kit\"\u003e\u003c/a\u003e\n\u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\"\u003e\u003c/a\u003e\n\u003cimg alt=\"platforms 9\" src=\"https://img.shields.io/badge/platforms-9-blue\"\u003e\n\u003cimg alt=\"host macOS\" src=\"https://img.shields.io/badge/host-macOS-black\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cb\u003e\u003ca href=\"#english\"\u003eEnglish\u003c/a\u003e · \u003ca href=\"#简体中文\"\u003e简体中文\u003c/a\u003e\u003c/b\u003e\u003c/p\u003e\n\n```bash\nnpx skills add dxiongya/debug-kit        # ← one-line install (it's a skill, not a library)\n```\n\n\u003e [!NOTE]\n\u003e **This is an _Agent Skill_, not an app or a library.** You don't run or `import` it — you\n\u003e **install** it into your AI coding agent. After that, the agent automatically uses it whenever\n\u003e you say things like *\"run the app\", \"tap the button\", \"take a screenshot\", \"test this\"*. Under\n\u003e the hood it's a `SKILL.md` manifest plus the scripts the agent calls. Manage it with\n\u003e [skills.sh](https://skills.sh).\n\n---\n\n\u003ca name=\"english\"\u003e\u003c/a\u003e\n\n## English\n\n**debug-kit** gives an AI agent — like [Claude Code](https://claude.com/claude-code) — *hands and eyes* on real applications across **macOS, iOS, Android, Web, Electron, Flutter, React Native, Tauri, and Chrome Extensions**. Build, launch, screenshot, read the UI tree, tap, type, drag, scroll, inspect, and stream logs — through **one unified interface** that auto‑detects the project type.\n\nIts defining principle: **never hijack the human's machine.** Every interaction is delivered in the background (Accessibility actions, `CGEventPostToPid`, CDP, `simctl`/`adb`, the Dart VM Service), so your real cursor never moves and focus is never stolen — while a **resident \"software cursor\" glides to each action**, so you can *see* exactly where the AI is working.\n\n### Install\n\n**Recommended — via [skills.sh](https://skills.sh):**\n\n```bash\nnpx skills add dxiongya/debug-kit        # into ./.claude/skills (project scope)\nnpx skills add -g dxiongya/debug-kit     # into ~/.claude/skills (global)\n```\n\n**Manual — git clone:**\n\n```bash\ngit clone git@github.com:dxiongya/debug-kit.git\nbash debug-kit/install.sh                # symlink → ~/.claude/skills/debug-kit\nbash debug-kit/install.sh --copy         # or copy instead of symlink\n```\n\nThen in Claude Code the `debug-kit` skill auto‑triggers on \"run the app\", \"test the app\",\n\"take screenshot\", \"tap button\", \"debug\", etc. The scripts under `scripts/` also work standalone.\n\n\u003e **macOS setup:** grant **Accessibility** + **Screen Recording** to your terminal\n\u003e (System Settings → Privacy \u0026 Security), then fully quit and relaunch it.\n\n### Why it's different\n\n- 🖱️ **Background by default — your cursor is sacred.** Clicks/keys/scrolls go straight to the target app; the system pointer stays exactly where you left it, focus never jumps. Real HID (which moves the cursor) is a manual, opt‑in escape hatch only.\n- 👻 **A virtual pointer on every platform.** A gliding, click‑through software cursor (Codex/Operator‑style) shows where the AI taps — screen overlay on macOS/Tauri/Web/Electron, sim overlay on iOS, native touch feedback on Android.\n- 🧠 **Semantic‑first, not pixel‑guessing.** Reads structured UI via the Accessibility tree (macOS/iOS), CDP DOM (Web/Electron), uiautomator (Android), and the Flutter VM Service — then acts by element, not coordinates, when possible.\n- 🧩 **One router, nine platforms.** `pilot.sh auto \u003ccommand\u003e` detects the project (`package.json`, `pubspec.yaml`, `*.xcodeproj`, `build.gradle`, `src-tauri/`, `manifest.json` MV3…) and dispatches to the right controller.\n- ⚡ **Zero heavyweight deps.** Plain bash + Node built‑ins + a little Swift/JXA. No Selenium, no Playwright runtime.\n\n### Supported platforms\n\n| Platform | Driven via | Virtual pointer |\n|----------|-----------|-----------------|\n| macOS | Accessibility + `CGEventPostToPid` | software cursor (screen) |\n| iOS | `xcrun simctl` + XCUITest | sim overlay indicator |\n| Android | `adb` + uiautomator | native `show_touches` |\n| Web | Chrome + CDP | software cursor (CSS→screen) |\n| Electron | CDP | software cursor (CSS→screen) |\n| Flutter | Dart VM Service + mobile/desktop targets | mobile native / desktop screen |\n| React Native | Metro + delegates to iOS | via iOS |\n| Tauri | Accessibility through WKWebView | software cursor (via macOS) |\n| Chrome Extension | CDP against extension pages | software cursor (via Web) |\n\n### Quick example\n\n```bash\nP=~/.claude/skills/debug-kit/scripts\n\n# auto-detect the project and drive it\nbash $P/pilot.sh auto run                    # build + launch\nbash $P/pilot.sh auto tree                   # dump the semantic UI tree\nbash $P/pilot.sh auto tap label \"Login\"      # background AXPress — your cursor untouched\nbash $P/pilot.sh auto type \"hello@example.com\"\nbash $P/pilot.sh auto screenshot\n\n# or target a platform explicitly\nMAC_APP=MyApp bash $P/mac-ctl.sh tap label incrementButton\nbash $P/android-ctl.sh tap 540 1000          # native touch feedback shown on device\nbash $P/flutter-ctl.sh vm widgets            # semantic widget tree over the Dart VM Service\n```\n\n### Best testing recipe per platform\n\nCollection is always native/semantic; interaction stays background.\n\n| Platform | collect → interact → verify |\n|----------|------------------------------|\n| **macOS** | `tree`/`read` → `tap label`/`type`/`drag`/`scroll` → `read` + `screenshot` |\n| **iOS** | `tree` (XCUITest) → `tap identifier`/`type` (simctl) → `screenshot` |\n| **Android** | `tree` (uiautomator) → `tap`/`swipe`/`type` (adb) → `screenshot` |\n| **Web / Electron** | `dom`/`eval` → `click \"sel\"`/`type` → `screenshot` |\n| **Flutter** | `vm widgets` → mobile‑target `tap` / `vm call` → `vm widgets` |\n| **React Native** | `run` (auto Metro port) → `tree`/`tap`/`type` (via iOS) → `screenshot` |\n| **Tauri** | `tree`/`read` (WKWebView AX) → `tap-bg label`/`type-bg` → `screenshot` |\n| **Chrome Extension** | CDP via `web-ctl` against the extension page |\n\nSee `references/\u003cplatform\u003e.md` for each platform's full command set.\n\n### How it works\n\ndebug-kit runs on a **macOS host** and drives each platform with its *native, professional*\nprotocol — never screen‑scraping when a real API exists. A small shared service\n(`dk-pointer.sh` + a Swift overlay daemon) renders the virtual cursor in screen space, fed by\neach controller after it maps the action to absolute screen coordinates. An\n**interaction‑fidelity ladder** keeps everything in the background unless you explicitly ask\nfor a real‑cursor click:\n\n- **T1 semantic** (default) — AX actions, CDP `click`, uiautomator, VM Service. No cursor.\n- **T2 synthetic** — `CGEventPostToPid` / `simctl io` / `adb input` at coordinates. No cursor.\n- **Escape hatch** — `MAC_INPUT=hid` is the *only* path that moves your real cursor; manual opt‑in.\n\n**Knobs:** `DK_POINTER=off` (hide the virtual pointer), `DK_FIDELITY=semantic|synthetic|real`,\n`MAC_INPUT=bg|hid`, `MAC_POINTER=on|off`.\n\n### Requirements\n\n- **macOS** host with Accessibility + Screen Recording granted to the terminal.\n- Per‑platform toolchains as needed: Xcode (iOS/macOS), Android SDK + emulator,\n  Node + Chrome (Web/Electron), Flutter SDK, Rust + Tauri CLI.\n- Optional: Swift toolchain (`swiftc`) for the virtual‑pointer overlay — degrades gracefully if absent.\n\n### Credits\n\n- Virtual‑cursor glyph \u0026 motion referenced from the **open‑computer‑use** project\n  (a reverse‑engineering of Codex Computer Use's software cursor); see `scripts/assets/NOTICE.md`.\n- The interaction action model aligns with **OpenAI's computer‑use** tool spec.\n\n---\n\n\u003ca name=\"简体中文\"\u003e\u003c/a\u003e\n\n## 简体中文\n\n\u003e [!NOTE]\n\u003e **这是一个 _Agent Skill(智能体技能)_,不是 App、也不是库。** 你不需要\"运行\"或 `import` 它 —— 你把它**安装**进你的 AI 编程助手(Claude Code / Cursor / Codex …)。装好后,当你说\"运行 app\"\"点这个按钮\"\"截个图\"\"测一下\"时,助手会**自动调用**它。底层就是一个 `SKILL.md` 清单 + 一组助手调用的脚本。用 [skills.sh](https://skills.sh) 管理。一行安装:`npx skills add dxiongya/debug-kit`\n\n**debug-kit** 让 AI 智能体(如 [Claude Code](https://claude.com/claude-code))在 **macOS、iOS、Android、Web、Electron、Flutter、React Native、Tauri、Chrome 扩展**这 9 个平台上长出\"手和眼\":构建、启动、截图、读取 UI 树、点击、输入、拖拽、滚动、检视、看日志——全部通过**一套统一接口**,自动识别项目类型。\n\n核心原则:**绝不接管你的机器。** 所有交互都在**后台**送达(Accessibility 动作、`CGEventPostToPid`、CDP、`simctl`/`adb`、Dart VM Service),**你的真实光标从不移动、焦点从不被抢**;同时一个**常驻\"软光标\"滑向每个操作点**,让你能*看见* AI 正在哪里操作。\n\n### 安装\n\n**推荐 —— 通过 [skills.sh](https://skills.sh):**\n\n```bash\nnpx skills add dxiongya/debug-kit        # 安装到 ./.claude/skills(项目级)\nnpx skills add -g dxiongya/debug-kit     # 安装到 ~/.claude/skills(全局)\n```\n\n**手动 —— git clone:**\n\n```bash\ngit clone git@github.com:dxiongya/debug-kit.git\nbash debug-kit/install.sh                # 软链 → ~/.claude/skills/debug-kit\nbash debug-kit/install.sh --copy         # 或拷贝(而非软链)\n```\n\n之后在 Claude Code 里,`debug-kit` skill 会在你说\"运行 app\"\"测试\"\"截图\"\"点按钮\"\"调试\"等时自动触发。`scripts/` 下的脚本也能独立使用。\n\n\u003e **macOS 配置:** 在「系统设置 → 隐私与安全性」给你的终端授予 **辅助功能** + **屏幕录制**,然后**完全退出并重启**终端。\n\n### 它有何不同\n\n- 🖱️ **默认后台 —— 你的光标神圣不可侵犯。** 点击/按键/滚动直达目标 App;系统光标停在原处、焦点不跳。会动真实光标的真实 HID 仅作**手动逃生口**。\n- 👻 **每个平台都有虚拟指针。** 一个滑行、点击穿透的软光标(Codex/Operator 风格)显示 AI 点在哪 —— macOS/Tauri/Web/Electron 用屏幕叠加,iOS 用沙窗叠加,Android 用设备原生触摸反馈。\n- 🧠 **语义优先,而非猜像素。** 通过 Accessibility 树(macOS/iOS)、CDP DOM(Web/Electron)、uiautomator(Android)、Flutter VM Service 读取结构化 UI,尽量**按元素**而非坐标操作。\n- 🧩 **一个路由,九个平台。** `pilot.sh auto \u003c命令\u003e` 自动识别项目并分发到对应控制器。\n- ⚡ **零重依赖。** 纯 bash + Node 内置模块 + 少量 Swift/JXA。不需要 Selenium、不需要 Playwright 运行时。\n\n### 支持平台\n\n| 平台 | 驱动方式 | 虚拟指针 |\n|------|----------|----------|\n| macOS | Accessibility + `CGEventPostToPid` | 软光标(屏幕) |\n| iOS | `xcrun simctl` + XCUITest | 沙窗叠加指示器 |\n| Android | `adb` + uiautomator | 原生 `show_touches` |\n| Web | Chrome + CDP | 软光标(CSS→屏幕) |\n| Electron | CDP | 软光标(CSS→屏幕) |\n| Flutter | Dart VM Service + 移动/桌面目标 | 移动端原生 / 桌面屏幕 |\n| React Native | Metro + 委托 iOS | 经 iOS |\n| Tauri | 经 WKWebView 的 Accessibility | 软光标(经 macOS) |\n| Chrome 扩展 | 对扩展页面用 CDP | 软光标(经 Web) |\n\n### 快速示例\n\n```bash\nP=~/.claude/skills/debug-kit/scripts\n\n# 自动识别项目并驱动\nbash $P/pilot.sh auto run                    # 构建 + 启动\nbash $P/pilot.sh auto tree                   # 导出语义 UI 树\nbash $P/pilot.sh auto tap label \"登录\"        # 后台 AXPress —— 不动你的光标\nbash $P/pilot.sh auto type \"hello@example.com\"\nbash $P/pilot.sh auto screenshot\n\n# 或显式指定平台\nMAC_APP=MyApp bash $P/mac-ctl.sh tap label incrementButton\nbash $P/android-ctl.sh tap 540 1000          # 设备上显示原生触摸反馈\nbash $P/flutter-ctl.sh vm widgets            # 经 Dart VM Service 拿语义 widget 树\n```\n\n### 每端最佳测试配方\n\n采集永远走原生/语义;交互保持后台。\n\n| 平台 | 采集 → 交互 → 验证 |\n|------|---------------------|\n| **macOS** | `tree`/`read` → `tap label`/`type`/`drag`/`scroll` → `read` + `screenshot` |\n| **iOS** | `tree`(XCUITest)→ `tap identifier`/`type`(simctl)→ `screenshot` |\n| **Android** | `tree`(uiautomator)→ `tap`/`swipe`/`type`(adb)→ `screenshot` |\n| **Web / Electron** | `dom`/`eval` → `click \"选择器\"`/`type` → `screenshot` |\n| **Flutter** | `vm widgets` → 移动端 `tap` / `vm call` → `vm widgets` |\n| **React Native** | `run`(自动 Metro 端口)→ `tree`/`tap`/`type`(经 iOS)→ `screenshot` |\n| **Tauri** | `tree`/`read`(WKWebView AX)→ `tap-bg label`/`type-bg` → `screenshot` |\n| **Chrome 扩展** | 经 `web-ctl` 对扩展页面用 CDP |\n\n各平台完整命令见 `references/\u003c平台\u003e.md`。\n\n### 工作原理\n\ndebug-kit 跑在 **macOS 宿主**上,用每个平台**原生、专业**的协议驱动它 —— 有真实 API 时绝不截屏猜像素。一个轻量共享服务(`dk-pointer.sh` + Swift 叠加守护)在屏幕空间渲染虚拟光标,由各控制器把动作映射成绝对屏幕坐标后喂给它。**交互保真阶梯**保证一切默认在后台,除非你显式要求真实点击:\n\n- **T1 语义**(默认)—— AX 动作、CDP `click`、uiautomator、VM Service,不动光标。\n- **T2 合成** —— `CGEventPostToPid` / `simctl io` / `adb input` 按坐标,不动光标。\n- **逃生口** —— `MAC_INPUT=hid` 是**唯一**会移动你真实光标的路径,手动开启。\n\n**开关:** `DK_POINTER=off`(隐藏虚拟指针)、`DK_FIDELITY=semantic|synthetic|real`、`MAC_INPUT=bg|hid`、`MAC_POINTER=on|off`。\n\n### 环境要求\n\n- **macOS** 宿主,终端已授予辅助功能 + 屏幕录制。\n- 按需的各平台工具链:Xcode(iOS/macOS)、Android SDK + 模拟器、Node + Chrome(Web/Electron)、Flutter SDK、Rust + Tauri CLI。\n- 可选:Swift 工具链(`swiftc`)用于虚拟指针叠加 —— 缺失时优雅降级。\n\n### 致谢\n\n- 虚拟光标的图形与运动参考自 **open‑computer‑use** 项目(对 Codex Computer Use 软光标的逆向),见 `scripts/assets/NOTICE.md`。\n- 交互动作模型对齐 **OpenAI computer‑use** 工具规范。\n\n## License\n\nMIT — 见 [LICENSE](./LICENSE)。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdxiongya%2Fdebug-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdxiongya%2Fdebug-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdxiongya%2Fdebug-kit/lists"}