מה זה phone-harness
phone-harness הוא פרויקט קוד פתוח קטן של Shawn Pana שנותן לסוכן AI לשלוט בטלפון אמיתי שלכם. לא סימולטור, לא אמולטור: הטלפון שיושב לכם על השולחן.
הוא עובד עם כל סוכן שיודע להריץ פקודות בטרמינל: Claude Code, Codex, וכל דבר אחר. אייפון דרך אפליקציית iPhone Mirroring של המק, אנדרואיד דרך adb.
והחלק המעניין: אין Jailbreak, אין Xcode, אין WebDriverAgent, ואין שום אפליקציה שצריך להתקין על הטלפון.
איך זה עובד
כל הרעיון נשען על חלון אחד. iPhone Mirroring כבר מציג לכם את הטלפון כחלון רגיל על מסך המק, ומעביר אליו עכבר ומקלדת בתור מגעים. phone-harness פשוט לוקח את החלון הזה ומתייחס אליו כאל ממשק:
| החלק | מה קורה בפועל |
|---|---|
| הגשר | iPhone Mirroring מציג את הטלפון כחלון על המק ומעביר אליו קלט |
| העיניים | צילום של החלון פלוס Vision OCR של אפל, כל טקסט חוזר עם קואורדינטה מוכנה ללחיצה |
| הידיים | אירועי HID ברמת המערכת: לחיצות, החלקות והקלדה, בדיוק כאילו אתם עושים את זה |
| הלולאה | הסוכן פועל, קורא שוב את המסך, ומחליט מה הלאה. אין DOM לבדוק מולו, אז הקריאה החוזרת היא הבדיקה |
מה צריך לפני שמתחילים
- מק עם macOS Sequoia ומעלה, עם אפליקציית iPhone Mirroring
- לזווג את iPhone Mirroring עם הטלפון פעם אחת, צריך את הטלפון פיזית ביד
- Python בגרסה 3.10 ומעלה
- Claude Code או Codex מותקן ועובד
הדרך הקצרה: תנו לסוכן להתקין
זו הדרך שהפרויקט עצמו ממליץ עליה. פותחים את Claude Code או Codex ומדביקים את הפרומפט הבא. הסוכן יוריד, יתקין, ירשום את עצמו כ-skill, ואז ילווה אתכם בשלבים שדורשים ידיים:
Set up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness
into ~/.phone-harness, read `install.md` first, install it so `phone-harness`
is a command on my PATH, and register it as an agent skill named phone-harness
using `phone-harness skill` as the body. Then read `onboarding.md` and walk me
through it.הסוכן ישאל אתכם שאלה אחת, אייפון או אנדרואיד, ואז יעצור בדיוק בשלבים שהוא לא יכול לעשות בעצמו: הזיווג של Mirroring ומתן ההרשאות.
התקנה ידנית
אם אתם מעדיפים לעשות את זה לבד, אלו הפקודות:
git clone https://github.com/ShawnPana/phone-harness ~/.phone-harness
cd ~/.phone-harness
pip install -e .ואז רושמים את זה כ-skill כדי שהסוכן ידע לפנות לזה לבד:
mkdir -p ~/.claude/skills/phone-harness
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.mdשימו לב: אחרי כל עדכון של הפרויקט כדאי להריץ שוב את השורה השנייה, כדי שהעותק של הסוכן יתאים לקוד.
שתי ההרשאות שחייבים לתת
זה השלב שהכי הרבה אנשים נתקעים בו. ההרשאות ניתנות לטרמינל שממנו אתם מריצים, לא לאפליקציה אחרת. System Settings ואז Privacy & Security:
| ההרשאה | בשביל מה | מתי נכנסת לתוקף |
|---|---|---|
| Accessibility | לחיצות והקלדות | מיד |
| Screen Recording | לראות את מסך הטלפון | רק אחרי הפעלה מחדש של הטרמינל |
שתי פקודות שפותחות ישירות את המסכים הנכונים:
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"ואז בודקים שהשרשרת שלמה:
phone-harness --doctor iosאיך משתמשים
הסוכן כותב סקריפט פייתון קצר ומריץ אותו. כל הפונקציות כבר מיובאות מראש. זו הדוגמה מה-README עצמו:
phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
type_text("hello from the harness")
print([o["text"] for o in ocr()][:10])
PYחמש שורות, והטלפון פתח פתק חדש וכתב בו טקסט.
הפונקציות שכדאי להכיר
| פונקציה | מה היא עושה |
|---|---|
ocr() | מחזירה כל מחרוזת שנראית על המסך, כל אחת עם נקודת מרכז מוכנה ללחיצה |
tap_text("Weather") | לוחצת על אלמנט לפי הטקסט שלו. אם היא נכשלת היא אומרת מה כן נראה על המסך |
screenshot() | צילום מסך. לאייקונים בלי טקסט, שם OCR לא עוזר |
open_app("Notes") | פותחת אפליקציה דרך ה-Spotlight של הטלפון |
type_text("...") | מקלידה טקסט לשדה הפעיל |
scroll("down") | גוללת. שימו לב לכיוונים בסעיף הבא |
home() / app_switcher() | ניווט בסיסי: מסך הבית ומחליף האפליקציות |
ensure_mirroring() | מוודאת שחלון ה-Mirroring פתוח ומחובר לפני שמתחילים |
המלכודת של הכיוונים
זו הנקודה שהכי קל להתבלבל בה, והפרויקט עשה את זה בכוונה כי ככה מדברים בעברית ובאנגלית:
- scroll אומר מה אתם רוצים לראות. scroll down פירושו הראה לי מה שנמצא למטה
- swipe אומר לאן האצבע זזה. swipe up זו התנועה שכולם עושים כדי לעבור לסרטון הבא
ועוד דבר חשוב: ב-macOS 26 גרירה אנכית באצבע פשוט נבלעת, אז swipe up ו-swipe down לא מזיזים כלום ברשימה או בפיד. לגלילה אנכית תמיד תשתמשו ב-scroll. אופקית swipe עדיין עובד, וזו הדרך להעביר דפים במסך הבית ובקרוסלות.
שלוש דוגמאות מעשיות
1. משימה קטנה על הטלפון
לפתוח אפליקציה, למלא שדה, לשלוח. כל מה שהיה דורש מכם להרים את הטלפון:
open_app("Notes")
tap_text("New Note")
type_text("רשימת קניות")2. Mobile QA: הכי מעניין
במקום לעבור ידנית על כל גרסה של האפליקציה שבניתם, נותנים לסוכן לעבור על ה-flow על מכשיר אמיתי ולדווח אם משהו נשבר. הוא רואה מה שמשתמש רואה, לא מה שסימולטור מראה.
השיטה שהפרויקט ממליץ עליה: לפני כל פעולה, לנסח מה אמור להשתנות. כותרת, שורה, תוכן של שדה. אם אי אפשר לנסח את זה, אי אפשר להבדיל בין הצלחה לבין כלום, ורוב הכשלים בטלפון הם כלום שקט.
3. דברים שקשורים למספר הטלפון
אפליקציות שקיימות רק ב-iOS, אימות דו-שלבי, כל דבר שקשור לחשבון שלכם בטלפון. הפרויקט עצמו ממליץ: אם המשימה אפשרית במק או בדפדפן, תעשו אותה שם. phone-harness הוא ליכולות שבאמת דורשות את הטלפון.
בונוס: אנדרואיד
אותן פונקציות בדיוק, רק שהתחבורה היא adb במקום חלון. במקום OCR הוא קורא את עץ הנגישות של הטלפון, וזה אפילו יותר מדויק. עובד ב-USB או ב-Wi-Fi.
brew install android-platform-tools
phone-harness config set platform android
phone-harness --doctor androidעל הטלפון: הגדרות ואז אודות הטלפון, ללחוץ שבע פעמים על מספר הבנייה, ואז להפעיל ניפוי USB באפשרויות המפתח.
טיפים
- תריצו phone-harness —doctor לפני כל דבר. הוא עובר על השרשרת לפי הסדר ואומר לכם איפה בדיוק נעצר
- אם הצילום יוצא שחור: נתתם Screen Recording אבל לא הפעלתם מחדש את הטרמינל
- אם הלחיצות לא עושות כלום, חסרה הרשאת Accessibility, או שחלון אחר חטף את הפוקוס
- עדיף ocr() על פני הסתכלות בצילומי מסך. הוא זול יותר ומחזיר קואורדינטות מוכנות
- אחרי שרצף פעולות הוכיח את עצמו, תנו לסוכן לאגד אותו לקריאה אחת. זה הרבה יותר מהיר מקריאה לכל צעד
- כשבדיקה נכשלת, תבודדו. להריץ שוב את הפעולה הבודדת ולהסתכל על המסך, במקום להריץ שוב את כל הרצף
- מה שהסוכן לומד אפשר לשמור בקובץ agent-workspace/agent_helpers.py, וכך המשימה הבאה מתחילה מנקודה מתקדמת יותר
- phone-harness config set telemetry false מכבה את הטלמטריה האנונימית
מגבלות: מה שהוא לא יכול
זה פרויקט של כמה מאות שורות, לא מוצר מסחרי. שווה לדעת מראש:
- אין Multi-Touch. כל מחווה שדורשת שתי אצבעות לא תעבוד
- אין Face ID ואין מצלמה. וידאו מוגן ב-DRM פשוט יוצא שחור
- OCR רואה טקסט, לא אייקונים. אייקון בלי תווית דורש צילום מסך ומודל Vision
- פתיחת נעילה של האייפון עוצרת את ה-Mirroring. את הטלפון תמיד אתם מחברים, וההארנס לעולם לא מקליד קוד PIN
- רק מק. אין גרסת Windows לאייפון, כי אין iPhone Mirroring ב-Windows
פתרון בעיות
| התסמין | מה לעשות |
|---|---|
| הצילום שחור או ריק | להפעיל מחדש את הטרמינל אחרי מתן Screen Recording, או לסגור הודעת ביניים בחלון ה-Mirroring |
| הלחיצות לא עושות כלום | חסרה הרשאת Accessibility, או שחלון אחר לקח את הפוקוס. לחפש חלונית הרשאה של macOS |
| doctor אומר שחסר pyobjc | רץ פייתון אחר מזה שהתקין. להשתמש באותו מפרש שאיתו הרצתם pip install -e . |
| אנדרואיד: unauthorized | לפתוח את נעילת הטלפון ולאשר את הבקשה לניפוי USB |
לינקים
- ה-repo: github.com/ShawnPana/phone-harness
- האתר הרשמי: phone-harness.com
- הוראות ההתקנה המלאות: install.md
- רשימת כל הפונקציות: SKILL.md
- רישיון MIT. הפרויקט חינמי ומתוחזק בזמן הפנוי של היוצר.
