أشِر إلى تطبيقك وهو يعمل. قل ما الذي يجب أن يتغيّر. وسيصل طلبك إلى الـ coding agent.
English · తెలుగు · हिन्दी · தமிழ் · 简体中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português · Русский · العربية
هذه نسخة مترجمة؛ الـ README الإنجليزي هو المرجع المعتمد وقد يكون أحدث منها.
انقر على عنصر، قل ما يجب أن يتغيّر، والـ agent يستلمه. · الفيديو بالسرعة الكاملة
انقر على عنصر في موقع التطوير المحلي، واكتب ما يجب أن يتغيّر، فيصل ذلك إلى الـ coding agent ومعه كل ما يحتاجه للعثور على الكود: الـ selector، والـ DOM path، والـ computed styles، وسلسلة مكوّنات React/Vue (component chain)، وتلميح لملف المصدر (source-file hint)، ولقطة شاشة مقصوصة للعنصر. لا مزيد من لقطات الشاشة المتراكمة في مجلد Downloads، ولا مزيد من وصف "الزر الثالث على اليسار".
ويعمل مع السلوك وليس الشكل فقط. "عطّل هذا الزر إلى أن يصبح النموذج صالحًا" أو "احفظ المسودة قبل الإغلاق" ملاحظات مقبولة تمامًا: يعتبر الـ agent العنصر نقطة البداية، ثم يتتبّعه إلى الـ handlers والـ state واستدعاءات الـ API والـ backend التي تقف خلفه.
تبني تطبيقًا أصليًا (native)؟ الأمر نفسه يعمل على iOS Simulator وعلى Android emulator.
flowchart LR
subgraph you [" You point and type "]
direction TB
B["🌐 <b>Browser</b><br/>Pinpoint extension"]
S["📱 <b>iOS Simulator</b><br/>127.0.0.1:7331/ios"]
AN["🤖 <b>Android emulator</b><br/>127.0.0.1:7331/android"]
end
BR(["📍 <b>Pinpoint bridge</b><br/>127.0.0.1:7331"])
ST[("💾 ~/.pinpoint/<br/>annotations.json")]
F["📄 .pinpoint/pending.md<br/><i>in your repo, optional</i>"]
A["🤖 <b>Your coding agent</b><br/>Claude Code · Cursor · Codex"]
B -- "selector · styles · crop" --> BR
S -- "accessibility tree · crop" --> BR
AN -- "view tree · crop" --> BR
BR -- "MCP / hooks" --> A
A -- "resolve + reply" --> BR
BR -. "live pins & replies" .-> B
BR --- ST
BR -.-> F
classDef bridge fill:#c6f432,stroke:#121212,stroke-width:2px,color:#121212
classDef agent fill:#121212,stroke:#c6f432,stroke-width:2px,color:#ffffff
class BR bridge
class A agent
style you fill:transparent,stroke:#888,stroke-dasharray:5 4
- البدء السريع
- طريقة الاستخدام
- التحاور حول الملاحظة
- كيف يعرف الوكيل بملاحظاتك
- تطبيقات iOS الأصلية
- محاكي Android
- ربط وكلاء آخرين
- المرجع: الأوامر، أدوات MCP، ومحتوى الملاحظة
- حل المشكلات
- الأمان والخصوصية
| من يقود | ما الذي يحصل عليه الـ agent | |
|---|---|---|
| Pinpoint | أنت تُشير وتقول ما يجب أن يتغيّر | الـ selector، الـ styles، الـ component chain، تلميح المصدر، لقطة مقصوصة |
| Playwright MCP، computer-use | الـ agent يتنقّل وينقر بنفسه | ما يعثر عليه أثناء التصفّح |
| لقطة شاشة ملصوقة | أنت | بكسلات فقط، فيُخمّن أي عنصر تحكّم تقصد |
لا يلمس Pinpoint الصفحة نفسها أبدًا، لذا فهو يتكامل مع أدوات أتمتة المتصفح بدلًا من أن ينافسها: أشِر إلى الشيء، ودع الـ agent يعدّل الكود، ودع اختباراتك تقود المتصفح.
تحتاج إلى Node 18+ ومتصفح مبني على Chromium (Chrome، Edge، Brave، Arc، Opera، Vivaldi)، أو Firefox 140+.
1. التثبيت
git clone https://github.com/gowtham012/pinpoint
node pinpoint/bridge/cli.js setupيطرح setup بضعة أسئلة، ولكل منها قيمة افتراضية، لذا يكفي أن تضغط Enter حتى النهاية. يقوم بربط Claude
Code وCursor وCodex (أيّها كان مثبتًا لديك)، ويثبّت الـ hooks الخاصة بـ Claude Code، ثم يشغّل الـ bridge.
2. حمّل الـ extension. لا يسمح Chrome للـ terminal بتحميل extension في ملفك الشخصي، لذا يفتح setup صفحة الـ extensions وينسخ لك مسار المجلد: فعّل Developer mode (وضع المطوّر)، وانقر Load unpacked (تحميل غير مضغوط)، ثم الصق المسار. سيؤكّد الـ terminal من تلقاء نفسه برسالة ✓ Pinpoint is live in Chrome.
3. أعد تشغيل Claude Code مرة واحدة ليقرأ الـ MCP server والـ hooks الجديدة.
جرّبه: افتح موقع التطوير (أو صفحة العرض التجريبية)، واضغط ⌥⇧A / Alt+Shift+A، وانقر على عنصر، واكتب ما يجب أن يتغيّر، ثم ⌘↩ / Ctrl+Enter. اكتب أي شيء في Claude Code وستصل ملاحظتك معه.
[!TIP] تريد كل خطوة بالتفصيل؟ راجع docs/quick-install.md. تبني تطبيق iOS أو Android أصليًا فقط؟ لا داعي للـ clone:
npx -y pinpoint-bridge، ثمclaude mcp add pinpoint -s user -- npx -y pinpoint-bridge mcp.
الإعداد بالتفصيل، والإعداد يدويًا، وWindows وfile://
يسأل setup عن:
- أي مشروع تريد إضافة ملاحظات على واجهته: الـ repo الذي سيعدّله الـ agent
- تطبيق ويب، أم تطبيق iOS أصلي، أم تطبيق Android، أم كلاهما (الويب وiOS): الويب يحصل على الـ extension الخاصة بالمتصفح؛ وiOS يحصل على أداة الاختيار في الـ Simulator، وAndroid على أداة الاختيار في الـ emulator. يتحقّق setup من وجود Xcode وMaestro وJava (لـ iOS) أو adb (لـ Android) ويخبرك كيف تحصل على الناقص منها (لا يثبّت أيًّا منها بنفسه).
- أي agents يربطها:
claude mcp addلـ Claude Code، و<project>/.cursor/mcp.jsonلـ Cursor، و~/.codex/config.tomlلـ Codex. يتم دمج الإعدادات الموجودة ولا تُستبدل أبدًا، ويُنسخ ملف الـ TOML احتياطيًا أولًا. - هل يثبّت الـ hooks الخاصة بـ Claude Code، وهي التي تُدخل الملاحظات المعلّقة مع رسالتك التالية
- أي متصفح ستُحمَّل فيه الـ extension (المتصفحات المثبتة لديك فقط)
بعد ذلك يسجّل الـ launcher الذي يقف خلف زر Start bridge (تشغيل الـ bridge) في الـ popup، ويشغّل الـ bridge.
بدون أسئلة تفاعلية: node pinpoint/bridge/cli.js setup ~/code/my-app --yes (أضف --for ios أو
--for android أو --for both؛ الافتراضي هو web).
يدويًا. الترتيب مهم: قيمة $PWD تُثبَّت داخل إعداد الـ MCP، لذا تُنفَّذ الخطوة 2 من داخل
pinpoint/bridge قبل أن يستولي الـ bridge على الـ terminal.
# 1. get it
git clone https://github.com/gowtham012/pinpoint
cd pinpoint/bridge && npm install
# 2. wire up Claude Code (once, from this folder)
claude mcp add pinpoint -s user -- node "$PWD/cli.js" mcp
node cli.js install-hooks ~/code/my-app # notes arrive without being asked
node cli.js install-native-host --project ~/code/my-app # optional: the popup's "Start bridge" button
# 3. load extension/ unpacked at chrome://extensions (Developer mode on)
# 4. start the bridge, and leave it running
node cli.js --project ~/code/my-appالخيار --project اختياري: يُبقي <repo>/.pinpoint/pending.md محدّثًا للـ agents التي تقرأ ملفًا بدلًا
من MCP.
صفحات file://. يعطّلها Chrome افتراضيًا: chrome://extensions ← Pinpoint ← Details (التفاصيل) ←
Allow access to file URLs (السماح بالوصول إلى عناوين الملفات)، ثم أعد تحميل الصفحة.
Windows. يعمل $PWD في PowerShell وGit Bash لكن ليس في cmd.exe؛ شغّل node cli.js --help وانسخ
سطر claude mcp add … الذي يطبعه، ففيه المسار الكامل. الأمر install-native-host خاص بـ macOS وLinux
فقط؛ على Windows شغّل الـ bridge من terminal.
موجود أيضًا في MCP Registry الرسمي
(io.github.gowtham012/pinpoint)، وcursor.directory
(بنقرة واحدة عبر Add to Cursor)، وGlama. هذه
تثبّت الـ MCP server فقط؛ صفحات الويب ما زالت تحتاج إلى الـ extension والـ bridge.
أثناء عمل الـ bridge، يظهر شريط صغير في الزاوية العلوية اليمنى من صفحتك.
![]() |
![]() |
![]() |
| يعرض الاختصار، ويُضيء أثناء عمل الـ agent. | ينكمش إلى نقطة بعد بضع ثوانٍ. مرّر المؤشر فوقه ليعود. | وضع الاختيار. يسمح الشريط بمرور النقرات فلا يحجب العنصر المستهدف أبدًا. |
- انقر على الشريط (أو ⌥⇧A / Alt+Shift+A) لبدء التحديد.
- انقر على عنصر، أو اسحب مربعًا حول مجموعة عناصر ("اجعل هذه البطاقات اثنتين في كل صف على الجوال").
- اكتب ما يجب أن يتغيّر واضغط ⌘↩ / Ctrl+Enter. أصبحت جاهزًا للملاحظة التالية.
- Esc أو Stop (إيقاف) عند الانتهاء.
![]() |
![]() |
| تُسمّي النافذة المنبثقة بدقة ما اخترته، فلا يمكن الخلط بين زرّين شبه متطابقين. | يلتصق دبوس مرقّم بالعنصر. يبقى بعد إعادة التحميل، ويظهر في كل تبويب مفتوح على تلك الصفحة، ويختفي عندما ينتهي الـ agent. |
- حرّك الشريط بسحب مقبضه إلى أي مكان في الصفحة؛ وسيبقى هناك على ذلك الموقع.
- العدّاد على الشريط يعرض كل ما تم تحديده في هذه الصفحة. انقر على أي صف للانتقال إليه.
- علامة × تُخفي الشريط لذلك الموقع؛ والـ popup في شريط الأدوات يُعيده.
- الدبابيس تتبع عناصرها في التطبيقات التي تعيد بناء الـ DOM، وتختفي بدلًا من أن تستقر على عنصر خاطئ إذا زال عنصرها.
- لا يوجد bridge يعمل؟ زر Send (إرسال) ينسخ لك prompt جاهزًا للصق بدلًا من ذلك، فلا يضيع شيء.
- سجّل الخطوات. أثناء الاختيار، اضغط Record steps على الشريط وانقر عبر الخطأ كما تفعل عادةً. تظل النقرات تصل إلى الصفحة، وتصبح كل نقرة خطوة (العنصر، والـ label، والـ URL، ولقطة مقصوصة صغيرة)، حتى عبر التنقّل بين الصفحات في التبويب نفسه. يكتب Done ملاحظة واحدة (10 خطوات كحدّ أقصى)؛ ويتجاهل Esc التسجيل. يستلمها الـ agent تحت عنوان Steps to reproduce (خطوات إعادة إنتاج المشكلة).
- الإملاء الصوتي. اضغط على الميكروفون في مربع التعليق وتحدّث؛ يُضاف النص إلى ما كتبته. يعمل في Chrome وSafari على الصفحات الآمنة (وlocalhost منها)؛ وخدمة التعرّف على الكلام الخاصة بالمتصفح نفسه هي التي تقوم بالتحويل إلى نص. غير متاح في Firefox.
- ما الذي حدث من خطأ يأتي معها. تحمل كل ملاحظة الأخطاء غير الملتقطة (uncaught errors) في الصفحة والطلبات الفاشلة خلال الدقيقة السابقة لتحديدك لها، بعد تنقيحها (redaction) في المتصفح أولًا (تُزال الـ query strings والـ tokens والأسرار). ولا تُرفق إلا إذا حدث خطأ فعلًا.
أين يعمل. فقط على صفحات التطوير المحلية: localhost، و127.0.0.1، والـ hosts المنتهية بـ .local /
.test / .localhost، وfile:// بعد السماح بها. في أي مكان آخر (عنوان staging، أو عنوان على الشبكة
المحلية لاختبار الجوال) يمكنك تفعيله لتبويب واحد من الـ popup في شريط الأدوات.
الملاحظة محادثة، وليست تذكرة باتجاه واحد.
- يمكن للـ agent أن يسألك. إذا كان الطلب غامضًا فإنه يسأل بدلًا من أن يُخمّن. يظهر السؤال على الدبوس (علامة ?) وكإشعار منبثق (toast)؛ أجب في لوحة الملاحظات وستعود الملاحظة ومعها المحادثة كاملة.
- تقرأ الرد في المتصفح. تبقى الملاحظة المنجزة في اللوحة ومعها تعليق الـ agent نفسه عمّا غيّره. والـ agents ملزمة بكتابته: كلمة "تم" ليست إجابة.
- Accept / Not quite. عندما ينتهي الـ agent، تظهر بطاقة فيها رده مع Accept (قبول) وNot quite (ليس تمامًا). يعيد Not quite فتح الملاحظة لتقول ما الذي ما زال خطأً.
- ليس كما أردت تمامًا لاحقًا؟ كل ملاحظة منجزة في اللوحة فيها Reply… (رد). قل ما الذي ما زال خطأً وستُعاد فتحها.
- Before / After. بعد بضع ثوانٍ من إنجاز الملاحظة، يلتقط Pinpoint لقطة مقصوصة جديدة للعنصر. وتعرض الملاحظات المنجزة في اللوحة Before (قبل) وAfter (بعد) جنبًا إلى جنب.
- المسودات. Draft (مسودة) (أو ⇧⌘↩) تحدّد شيئًا دون إرساله. وSend على الشريط يسلّم كل المسودات دفعة واحدة.
- الصفحة كاملة. أثناء الاختيار، يتيح لك Whole page (الصفحة كاملة) كتابة ملاحظة عن الصفحة نفسها ("المسافات تبدو ضيقة في كل مكان")، مع لقطة شاشة.
عندما تتغيّر الصفحة تحت دبوس، يُبلَّغ الـ agent بأن العنصر قد يكون قديمًا (stale) بدلًا من أن يُعطى
selector لم يعد صالحًا. والأداة recheck_annotation تعيد البحث فورًا وتُرجع لقطة مقصوصة جديدة بجانب
الأصلية.
الملاحظتان نفسهما، مرتين. يُعاد بناء اللوحة من الصفر: الملاحظة 1 تعثر على عنصرها مجددًا بين nodes جديدة تمامًا، والملاحظة 2 تعترف بأنه غير موجود في هذا العرض.
تشغيل الـ bridge من المتصفح، وتشغيل عدة agents في الوقت نفسه
التشغيل وإعادة التشغيل من المتصفح. يسجّل install-native-host أداة launcher صغيرة لدى Chrome (وكذلك
Brave وEdge وArc وChromium وVivaldi وOpera) ولدى Firefox. بعدها يعمل زر Start bridge في الـ popup، ويعيد زر
↻ على الشريط تشغيل الـ bridge بعد أن تسحب build جديدًا. الـ launcher لا يستطيع إلا شيئًا واحدًا: تشغيل
cli.js الخاص بهذا الـ repo على رقم port مأخوذ من إعدادات الـ popup، وليس من الصفحة أبدًا.
عدة agents. تعرّف الـ agents بنفسها عبر MCP، لذا يُظهر الشريط اسم الـ agent الذي يعمل حاليًا
(claude-code، cursor-vscode، codex) ويُنسب كل رد إلى صاحبه. وتسلّم wait_for_annotation كل ملاحظة
جديدة إلى agent واحد فقط من المنتظرين، فيتقاسم الـ agents الطابور بدلًا من العمل على الملاحظة نفسها.
ثلاث طرق، من الأقوى إلى الأضعف. ولا مانع من استخدامها جميعًا.
| الطريقة | الإعداد | |
|---|---|---|
| Hooks (تلقائي) | الملاحظات المعلّقة ترافق رسالتك التالية. لا يُطبع شيء إذا لم يكن هناك ما هو معلّق. | node cli.js install-hooks <repo> (يقوم به setup) |
| MCP (عند الطلب) | يخبر الـ server الـ agent بأن يتحقّق كلما تحدثت عن تغيير في الواجهة أو في ميزة. | إعداد الـ MCP |
| Watch loop (بدون تدخّل) | قل "watch pinpoint and apply each change as it comes in" (راقب pinpoint وطبّق كل تغيير فور وصوله)؛ فتصل كل ملاحظة لحظة ضغطك على Send. | لا شيء |
التعليق هو التعليمات، ويمكن أن يكون عن شكل الشيء أو عمّا يفعله. وكلما وصفت النتيجة أكثر ("يجب أن"، "بدلًا من"، "عندما … فإن …")، قلّ تخمين الـ agent.
التطبيق الأصلي لا يملك DOM، لذا يقرأ هذا المسار شجرة إمكانية الوصول (accessibility tree). يعمل مع تطبيقات SwiftUI وUIKit وReact Native وFlutter، دون إضافة أي شيء إلى تطبيقك.
![]() |
![]() |
تحتاج إلى Xcode مع Simulator مُشغَّل، وMaestro (الذي يحتاج إلى Java؛ ويتم العثور على
openjdk المثبّت عبر Homebrew حتى لو لم يكن في الـ PATH).
مع تشغيل الـ bridge، افتح http://127.0.0.1:7331/ios (يفتحها setup لك). مرّر المؤشر لرؤية كل عنصر،
وانقر على أحدها، واكتب، ثم ⌘↩. يحصل الـ agent على accessibilityIdentifier (أي الـ testID لديك)،
والـ label، ومسار الشجرة، والـ frame، ولقطة مقصوصة. اضغط R بعد أن يتغيّر التطبيق.
لا يوجد تطبيق في متناولك؟ الأمر bash demo/ios/run.sh يبني Trailhead، وهو تطبيق SwiftUI تجريبي من
شاشة واحدة، باستخدام swiftc وحده، ثم يشغّله على الـ Simulator المُشغَّل.
القيود والتوقيت
لا يوجد تلميح لملف المصدر ولا component chain (الشجرة لا تحتوي على أي منهما؛ أعطِ العناصر معرّفًا
(identifier) وسيبحث الـ agent عنه بـ grep)، ولا styles، ولا recheck_annotation. التحميل الأول ينتظر نحو 10
ثوانٍ ريثما يشغّل Maestro الـ driver الخاص به على الجهاز؛ وبعد ذلك يستغرق كل تحديث نحو ثانية. كل نسخ Maestro
على جهاز الـ Mac تتشارك driver واحدًا، فإذا أعادت نسخة أخرى تشغيله، يبدأ الـ bridge نسخة Maestro جديدة
ويحاول مرة أخرى. إذا استغرق التحميل الأول دقائق، فأغلق جلسات Claude Code الخاملة التي تحتوي على Maestro MCP
server.
أداة الاختيار نفسها الموجودة في /ios، لكنها تقرأ شجرة العرض (view tree) في Android عبر adb. لا يُضاف
أي شيء إلى تطبيقك، ولا يوجد driver لتثبيته.
![]() |
![]() |
تحتاج إلى adb من Android SDK (يثبّته Android Studio) وemulator مُشغَّل.
مع تشغيل الـ bridge، افتح http://127.0.0.1:7331/android. مرّر المؤشر، وانقر، واكتب، ثم أرسل. يحصل الـ
agent على resource-id الخاص بالعنصر، والـ content-desc، والنص، والـ class، وموقعه في شجرة العرض، ولقطة
مقصوصة. ويتحقّق الأمر node bridge/cli.js setup --for android من وجود adb ويوجّهك إلى أداة الاختيار.
العثور على adb، وأي جهاز تتم قراءته
يبحث Pinpoint عن adb في $ANDROID_HOME و$ANDROID_SDK_ROOT ومجلد الـ SDK الافتراضي لـ Android Studio، ثم
في الـ PATH. إذا كان هناك emulator واحد يعمل، فهو المستخدَم. وإذا كان هناك أكثر من واحد، أو أردت قراءة جهاز
حقيقي، فاضبط ANDROID_SERIAL على الرقم التسلسلي الخاص به (كما يعرضه adb devices) وأعد تشغيل الـ bridge.
لا يُختار الهاتف أبدًا ما لم تسمِّه بنفسك. وكما في iOS، لا يوجد تلميح لملف المصدر، ولا styles، ولا
recheck_annotation: أعطِ الـ views معرّفًا (id) وسيبحث الـ agent عنه بـ grep.
أبسط إعداد يشغّل الحزمة المنشورة: npx -y pinpoint-bridge mcp. وهي تتواصل مع أي bridge يعمل حاليًا. أعد
تشغيل المحرّر بعدها.
Cursor: بنقرة واحدة من cursor.directory، أو عبر .cursor/mcp.json
{ "mcpServers": { "pinpoint": { "command": "npx", "args": ["-y", "pinpoint-bridge", "mcp"] } } }Codex CLI: ~/.codex/config.toml
[mcp_servers.pinpoint]
command = "npx"
args = ["-y", "pinpoint-bridge", "mcp"]أي MCP client عبر HTTP، أو بدون MCP إطلاقًا
HTTP: http://127.0.0.1:7331/mcp (Streamable HTTP، عديم الحالة stateless). كل من Windsurf وCline
وContinue وZed وGemini CLI يقبل عنوان URL.
بدون MCP: شغّل الـ bridge مع --project <repo> وسيُبقي <repo>/.pinpoint/pending.md محدّثًا. قل لأي
agent "read .pinpoint/pending.md and apply it" (اقرأ الملف وطبّقه)؛ وسيُنهي كل ملاحظة بـ
node cli.js resolve <id>. أو استخدم Copy prompt (نسخ الـ prompt) في النافذة المنبثقة والصقه في أي محادثة.
لربط agent بنسختك المحلية (clone) بدلًا من npm، استخدم المسار المطلق إلى cli.js (انسخ السطر الذي
يطبعه node cli.js --help).
| المتصفح | الحالة |
|---|---|
| Chrome، Brave، Arc، Opera، Vivaldi | ✅ عبر Load unpacked. تم التحقق منه في CI على Chromium بدون واجهة (headless). |
| Edge | ✅ عبر Load unpacked: الحزمة نفسها الخاصة بـ Chrome. |
| Firefox 140+ | ✅ حزمة لـ addons.mozilla.org يبنيها bash tools/make-firefox-zip.sh. الإدراج في المتجر قيد الانتظار. بدون إملاء صوتي. |
| Safari | ✅ يُبنى باستخدام bash tools/make-safari.sh (يحتاج إلى Xcode). بدون component chain ولا تلميح للمصدر ولا أخطاء الصفحة. |
Edge وFirefox
يقبل Edge حزمة Chrome كما هي. ولزر Start bridge، شغّل
node bridge/cli.js install-native-host --id <edge id> مرة واحدة (يعطي Edge الـ extension معرّفًا خاصًا بها).
Firefox 140+. إلى أن يصبح الإدراج في addons.mozilla.org متاحًا، حمّل الـ zip من
about:debugging ← This Firefox ← Load Temporary Add-on. إذا حجب Firefox الوصول إلى المواقع المحلية،
فاضغط Grant access to local sites في الـ popup. بعد ذلك شغّل node bridge/cli.js install-native-host
مرة واحدة لزر Start bridge، أو الصق ناتج node bridge/cli.js token في الـ popup.
ما الذي يختلف في Safari
لا يقبل Safari الـ extensions غير المضغوطة، لذا يغلّفها tools/make-safari.sh داخل تطبيق macOS صغير ويطبع
إعدادات Safari الأربعة التي يجب تغييرها (أهمها Develop ▸ Allow Unsigned Extensions، الذي يُعاد ضبطه في
كل مرة يُغلق فيها Safari). لا يدعم Safari الـ content scripts من نوع "world": "MAIN"، لذا لا يستطيع
inspector.js قراءة React fibers أو Vue instances: فتخسر الـ component chain وتلميح ملف المصدر،
وأخطاء الصفحة (فهي تحتاج إلى الـ MAIN world أيضًا). ولا تأتي الطلبات الفاشلة إلا حيث يدعم Safari
webRequest. كل ما عدا ذلك يعمل. ليس في Safari native host لتسليم الـ token الخاص بالـ bridge، لذا يطلبه الـ popup منك مرة
واحدة: شغّل node bridge/cli.js token والصق الناتج. وللنشر على Mac App Store، يُصدّر الأمر
TEAM=<your team id> bash tools/make-safari.sh --release نسخة build موقّعة.
الأوامر (تُشغَّل من pinpoint/bridge)
node cli.js [start] start the bridge (default command)
node cli.js mcp run as a stdio MCP server
node cli.js status is it running? how many pending?
node cli.js print pending annotations as markdown (--consume also resolves them)
node cli.js resolve <id...> --note "what you changed"
mark done — the pin disappears and your note is shown as the reply
node cli.js install-hooks [dir] wire up Claude Code
node cli.js install-native-host let the popup's "Start bridge" button start the bridge
(--uninstall removes it; --id <id> allows a second checkout)
node cli.js token print the extension token (Safari asks for it once)
node cli.js clear delete everything
node cli.js --help
http://127.0.0.1:7331/ios the iOS Simulator picker, served by the running bridge
http://127.0.0.1:7331/android the Android emulator picker (needs adb)
--port <n> default 7331, or $PINPOINT_PORT (set the same number in the popup)
--project <dir> mirror pending annotations into <dir>/.pinpoint/
--print echo each new annotation to stdout as it arrives
$PINPOINT_HOME where annotations are stored (default ~/.pinpoint)
$PINPOINT_AFTER_DELAY ms after a resolve before the After crop (default 3000, 0 turns it off)
$ANDROID_SERIAL which Android device to read, when it isn't the one running emulator
أدوات MCP
| الأداة | الغرض |
|---|---|
get_pending_annotations |
كل ما هو معلّق على شكل قائمة مهام markdown، ومع كل مهمة لقطة الشاشة الخاصة بها |
list_annotations |
سطر واحد لكل ملاحظة |
get_annotation |
التفاصيل الكاملة + لقطة الشاشة لـ id واحد أو رقم دبوس |
recheck_annotation |
إعادة العثور على العنصر في الصفحة الحية والإبلاغ عمّا تغيّر، مع لقطة مقصوصة جديدة بجانب الأصلية |
resolve_annotation |
تحديدها كمنجزة ← يختفي الدبوس في المتصفح خلال ثانية |
reply_annotation |
طرح سؤال على المطوّر بدلًا من التخمين؛ وتعود إجابته كملاحظة معلّقة، ومعها المحادثة |
wait_for_annotation |
الانتظار (blocking) إلى أن يرسل المطوّر الملاحظة التالية |
clear_annotations |
مسح كل شيء |
المورد (Resource): pinpoint://pending (markdown).
محتوى الملاحظة
comment "make this full-width on mobile" ← the only instruction
page url, title, viewport, scroll
element tag, id, classes, a CSS selector built from stable attributes where they exist
(`button[data-action="next"]` rather than `:nth-of-type(2)`; shadow DOM via
"host >>> inner"), DOM path, rendered text, trimmed outerHTML, role/aria/data-*
attributes, bounding box, ~25 computed style properties, and a fingerprint
(tag + text + key attributes) used to verify a pin is still on the right element
source framework (react/vue/svelte/angular/astro), component chain,
file:line where the dev build exposes it
screenshot PNG of just the element (+8px), long edge ≤1200px
context only when something went wrong: uncaught errors and failed requests from the
minute before, redacted in the browser
steps recorded notes only: up to 10 clicks, each with selector, label, URL and a crop
after on done notes: a fresh crop taken after the resolve
من iOS Simulator، يحمل element بدلًا من ذلك الـ accessibility identifier والـ label والنص والقيمة ومسار
الشجرة والـ frame؛ وتكون قيمة source هي ios-native، وقيمة page.url هي ios-simulator://<device name>.
ومن Android emulator، يحمل resource-id والـ content-desc والنص والـ class ومسار الشجرة والـ bounds؛ وتكون
قيمة source هي android-native، وقيمة page.url هي android-emulator://<avd>.
للحصول على file:line دقيق في React 19 أو Next، أضف inspector plugin للتطوير فقط
(vite-plugin-react-inspector، @react-dev-inspector). يقرأ Pinpoint الـ attributes data-source
الخاصة بها، وكذلك _debugSource/_debugStack في React و__file في Vue.
لا يظهر الشريط في الصفحة
لا يظهر الشريط إلا أثناء عمل الـ bridge. تحقّق بالأمر node cli.js status من داخل pinpoint/bridge. إذا كان
الـ bridge يعمل، فالأرجح أن الصفحة ليست من الصفحات التي يُحقن فيها Pinpoint تلقائيًا (راجع أين يعمل):
افتح الـ popup في شريط الأدوات وفعّله لذلك التبويب.
لا شيء إطلاقًا في صفحة file://
chrome://extensions ← Pinpoint ← Details ← Allow access to file URLs، ثم أعد تحميل الصفحة.
النقطة في شريط الأدوات لا تتحوّل إلى الأخضر أبدًا
الـ bridge لا يعمل، أو يعمل على port مختلف: يجب أن يتطابق Port في الـ popup مع --port في الـ bridge.
إذا قال node cli.js status إن الـ port answers, but it is NOT the pinpoint bridge (يستجيب، لكنه ليس
الـ bridge الخاص بـ pinpoint)، فهناك برنامج آخر يستخدمه: شغّل الـ bridge مع --port 7332 واضبط 7332 في
الـ popup.
port 7331 is already in use
عادةً يكون الـ bridge يعمل أصلًا في terminal آخر، وبذلك لا داعي لفعل شيء. وإلا فاختر port متاحًا كما سبق. لا تشغّل نسختين من الـ bridge في الوقت نفسه: فهما تتشاركان ملف تخزين واحدًا.
ملاحظة بدون لقطة شاشة
تُلتقط الصورة مباشرة بعد حفظ تعليقك، لذا لا يضيع التعليق أبدًا. إذا انتقلت الصفحة أو أُغلق التبويب في تلك اللحظة، تسجّل الملاحظة السبب. ويبقى التعليق والـ selector والـ styles كلها موجودة.
Claude Code لا يذكر ملاحظاتي
تُقرأ الـ hooks عند بدء الجلسة: أعد التشغيل مرة واحدة بعد install-hooks. تأكّد من أن
<your repo>/.claude/settings.json يحتوي على إدخالين يتضمّنان print --hook وأن مسارهما ما زال موجودًا
(نقل الـ clone يكسره؛ أعد تشغيل install-hooks). ويمكنك دائمًا أن تقول "apply my pinpoint annotations"
(طبّق ملاحظات pinpoint الخاصة بي).
زر "Start bridge" يقول إن الإعداد مطلوب، أو لا يجد Node
شغّل node cli.js install-native-host مرة واحدة (ومرة أخرى إذا نقلت الـ repo)، ثم أغلق المتصفح وأعد فتحه.
يحفظ الـ launcher مسارًا مطلقًا إلى node؛ فإذا تغيّر مكان node (إصدار nvm جديد، أو ترقية Homebrew)، أعد تشغيل
الأمر.
تريد البدء من الصفر
node cli.js clear. الملف ~/.pinpoint/annotations.json هو الحالة الوحيدة الموجودة خارج الـ repo الخاص بك.
- يستمع الـ bridge على
127.0.0.1فقط، ويرفض الطلبات التي تحملOriginلصفحة ويب. - يجب أن تقدّم الـ extension الـ token الموجود في
~/.pinpoint/token. - كل ما يُستخرج من الصفحة يُوسَم بأنه untrusted (غير موثوق) عند وصوله إلى الـ agent؛ وتعليقك الذي كتبته وحده يُقدَّم على أنه تعليمات.
- تُحفظ لقطات الشاشة داخل
~/.pinpoint/annotations.json، وليس كملفات متفرّقة.
يحتوي SECURITY.md على الملاحظات الكاملة حول حدود الثقة (بما في ذلك سبب الحاجة إلى
<all_urls>)، ويوضّح PRIVACY.md بالضبط ما الذي يُجمع، وأين يُخزَّن، والمكان الوحيد الذي
يذهب إليه: الـ coding agent الذي تربطه.
الملف demo/index.html موقع تجريبي مستقل (بدون build، وبدون شبكة) يحتوي على شبكات بطاقات لتجربة سحب
المناطق، وأزرار شبه متطابقة، ولوحة تبويبات تعيد بناء نفسها، وجدول كثيف، ونموذج.
cd demo && python3 -m http.server 8080 # then open http://localhost:8080cd test && npm install && npx playwright install chromium && npm test210 اختبارات. يغطّي bridge.test.mjs الـ daemon والـ CLI والـ hooks وأداة الاختيار في iOS وكل أداة MCP عبر
stdio وStreamable HTTP. ويحمّل e2e.test.mjs الـ extension في Chromium بدون واجهة (headless) ويقود صفحات
حقيقية: React، وVue، وshadow DOM، وiframes، وCSP صارم، وصفحة ضغط فيها 3,600 node، وDPR 2، والمزامنة بين
التبويبات، ونموذج يعيد بناء الـ DOM بالكامل.
مجموعات الاختبار الأخرى
| الملف | ما يغطّيه |
|---|---|
android-bridge.test.mjs |
العثور على adb، واختيار الجهاز، وتحليل شجرة العرض، ومسارات /android |
e2e-picker.test.mjs |
صفحات أداة الاختيار /ios و/android في Chromium بدون واجهة (headless) |
ui-bridge.test.mjs، ui-flow.test.mjs، ui-after.test.mjs |
Accept، وسياق الصفحة، والخطوات المسجّلة، وBefore / After |
ui-redact.test.mjs |
قواعد تنقيح سياق الصفحة |
ship-edge.test.mjs، ship-firefox.test.mjs، e2e-ship.test.mjs |
الرفع إلى Edge، وحزمة Firefox والـ native host الخاص به، والـ zip الخاص بالمتجر، ومسارات Firefox في الـ popup |
ship-windows.test.mjs |
كيف يضع setup علامات الاقتباس حول الأوامر لـ cmd.exe |
راجع CONTRIBUTING.md.
- تلميحات المصدر الأصلية لـ React Native وFlutter، عبر حزمة اختيارية للتطوير فقط
- ربط مصدر الـ CSS عبر
chrome.debugger(أي قاعدة حدّدت هذا اللون، وأين)
الـ issues والـ pull requests مرحّب بها؛ راجع CONTRIBUTING.md. لا توجد خطوة build:
اعمل clone، ثم npm install في bridge/، وحمّل extension/ عبر Load unpacked. كل تغيير في السلوك يأتي
معه اختبار.
MIT، راجع LICENSE. ملاحظات الإصدارات موجودة في CHANGELOG.md.










