# netscope

اقرأ الإنترنت لصالح وكلاء الذكاء الاصطناعي — بدون أي مفتاح API مدفوع.

مستوحى من فكرة "طبقة قدرات موحّدة" لكن بإعادة تصميم كاملة، مع تحسينات:

- **كاش تلقائي على القرص** (`~/.netscope/cache`) — أي طلب متكرر لنفس الرابط/الاستعلام لا يعيد الجلب من الشبكة
- **إعادة محاولة بتصاعد أسي** لأي خطأ شبكة عابر
- **حالات صحة أدق** بدل ok/warn/off فقط: `ok / warn / off / error / rate_limited`
- **بحث ويب مجاني بالكامل** (DuckDuckGo HTML) بدل الاعتماد على أي API بحث مدفوع
- **GitHub عبر REST API مباشرة** بدون الحاجة لتثبيت CLI منفصل
- كل الأسرار (كوكيز) تُخزَّن محليًا فقط بصلاحية `600`، ولا تُطبع أبدًا كاملة (`config show` يخفيها تلقائيًا)

## طريقة 1: تثبيت كحزمة (CLI)

```bash
pip install -e .                 # الأساسيات فقط
pip install -e ".[full]"         # كل شيء: يوتيوب + متصفح حقيقي + PDF + جودة استخراج أعلى + MCP
playwright install chromium      # مرة وحدة بعد تثبيت [browser] أو [full]

netscope doctor                  # يفحص كل القنوات
netscope read https://github.com/torvalds/linux
netscope read https://some-js-heavy-site.com     # يصعّد تلقائيًا لمتصفح حقيقي لو المحتوى فاضي/ناقص
netscope read url1 url2 url3     # قراءة دفعة واحدة
netscope search "أفضل أدوات فايبكودنق 2026"
netscope search "rust async" --channel github
```

## طريقة 2: سكربتات مباشرة بدون تثبيت

مجلد `scripts/` فيه ملفات مستقلة، كل وحد فيها كافي بذاته:

```bash
pip install requests
python3 scripts/read_url.py https://example.com
python3 scripts/search_web.py "استعلام البحث"
python3 scripts/read_github.py https://github.com/owner/repo

pip install yt-dlp
python3 scripts/read_youtube.py https://youtu.be/VIDEO_ID
```

## طريقة 3: كأداة MCP داخل أي وكيل مباشرة (الأقوى)

هذا يخلي netscope "مثبّت" فعليًا داخل الوكيل، مو مجرد CLI يشغّله عبر bash:

```bash
pip install -e ".[mcp]"
```

سجّله في Claude Code:
```bash
claude mcp add netscope -- python -m netscope.integrations.mcp_server
```

أو أي عميل MCP آخر (Claude Desktop، Cursor...) بنفس أمر التشغيل:
```
python -m netscope.integrations.mcp_server
```

الوكيل بيشوف أربع أدوات جاهزة: `netscope_read`، `netscope_read_many`، `netscope_search`، `netscope_doctor` — بدون ما يحتاج يكتب سطر أوامر أبدًا.

فيه أيضًا `netscope/skill/SKILL.md` جاهز لأي إطار عمل يدعم "Skills" (زي Claude Code) — يعلّم الوكيل متى يستخدم الأداة تلقائيًا.

## التصعيد التلقائي للمتصفح الحقيقي (Browser Escalation)

أكبر تحسين حقيقي على التغطية: لما قناة `web` العادية ترجع محتوى فاضي أو ناقص (صفحة JS-heavy ما تحمّلت)، النظام يصعّد تلقائيًا لمتصفح Chromium حقيقي (Playwright) بدون أي تدخل. تقدر تجبره من البداية بـ `--browser` أو توقفه بـ `--no-escalate`.

## القنوات المدعومة الآن (كلها مجانية)

| القناة | يحتاج إعداد؟ | ملاحظة |
|---|---|---|
| web (أي رابط) | لا | Jina Reader + trafilatura اختياري + fallback محلي |
| github | لا | REST API عام، توكن اختياري لرفع الحد |
| rss | لا | feedparser |
| search | لا | DuckDuckGo HTML |
| pdf | يحتاج `pip install pypdf` | يشتغل على أي رابط ينتهي بـ pdf أو Content-Type مطابق |
| browser | يحتاج `playwright install chromium` | متصفح حقيقي، يشتغل تلقائيًا كتصعيد لقناة web |
| youtube | يحتاج `yt-dlp` مثبت فقط | لا مفتاح API |
| reddit | أحيانًا يحتاج بروكسي | JSON العام، يفشل أحيانًا على IP سيرفرات |
| bilibili | أحيانًا يحتاج بروكسي CN | API عام |
| twitter/x | تغريدة مفردة: لا شيء / بحث: كوكيز | endpoint المضمّن الحر لتغريدة واحدة |

## إضافة قناة جديدة

كل قناة ملف واحد في `netscope/channels/`، يرث من `Channel` وينفّذ `can_handle()` على الأقل. سجّلها في `netscope/channels/__init__.py` — الترتيب مهم (الأكثر تحديدًا أولاً، `web` دايمًا آخر واحد).

## اختبارات

```bash
pip install pytest
pytest tests/
```