housaku

Housaku (豊作 「ほうさく」)

Housaku هو محرك بحث شخصي مبني على رأس FTS5 من SQLite والذي يتيح لك الاستعلام عن المستندات والكتب وأجهزة PDF والأعلاف المفضلة والمزيد في مكان واحد.

Housaku في التطوير المبكر ، لذلك يمكنك توقع بعض التغييرات غير المتوافقة وغيرها من المشكلات البسيطة عند التحديث. بمجرد الوصول إلى الإصدار v1.0.0 ، فإن هدفي هو التركيز على الاستقرار وتجنب كسر التغييرات قدر الإمكان.

سمات

• دعم لتنسيقات الملفات المتعددة مثل .txt و .md و .csv و .pdf و .epub و .docx و .xlsx و .pptx .
• دعم RSS/Atom Feeds تحليل وفهرسة.
• معالجة الملف الموازية.
• معالجة التغذية المتزامنة.
• ويب واجهة المستخدم.
• توي الحديثة بدعم للثقة.
• سهل الاستخدام CLI.
• النتائج ذات الصلة مدعوم من خوارزمية BM25.
• دعم التحديثات الإضافية.

يأتي دعم تنسيقات الملفات مثل .odt بالإضافة إلى إمكانية فهرسة المنشورات من Bluesky Feeds و Mastodon.

كومة

• امتداد SQLite's FTS5.
• sqlite.
• Starlette.
• aiohttp.
• انقر.
• Feedparser.
• Pydantic.
• pymupdf
• ثري.
• نص.

تحفيز

كان السبب الأول الذي جعلني أن أبدأ العمل في Housaku هو معرفة المزيد حول أساسيات البحث عن النص الكامل وكيفية عمل محركات البحث تحت الغطاء. في الواقع ، إذا نظرت إلى تاريخ الالتزام ، فيمكنك أن ترى أنه في البداية ، تم التعامل مع جميع حسابات التحليل والرمز المميز و TF/IDF "يدويًا" قبل أن أختار استخدام حل SQLite FTS5 بسبب الأداء.

السبب الثاني والأخير هو الحجم الكبير من المستندات التي كنت أديرها. لدي حوالي 5000 ملاحظات في Obsidian ، منسقة في Markdown ، بضع مئات من الكتب في مكتبة Caliber الخاصة بي ، وخاصة في .epub ، عدد كبير من PDFs ، وعروض PowerPoint من درجة علوم الكمبيوتر الخاصة بي في UNED. بالإضافة إلى ذلك ، لدي أيضًا مجموعة واسعة من خلاصات RSS التي اشتركت فيها لفترة طويلة. لذلك ، أردت/كنت بحاجة إلى طريقة فعالة وسهلة للبحث من خلال جميع هذه المستندات دون الحاجة إلى القلق بشأن تفاصيل مكان وجود كل واحد منها أو في أي شكل.

تثبيت

الطريقة الموصى بها لتثبيت Housaku هي باستخدام الأشعة فوق البنفسجية:

uv tool install --python 3.13 housaku

الآن ، أنت فقط يركض:

housaku --help

للترقية ، استخدم:

uv tool upgrade housaku

# Or

uv tool upgrade housaku --reinstall

باستخدام pipx

لتثبيت Housaku باستخدام pipx ، ما عليك سوى التشغيل:

pipx install housaku

فقط تذكر أن الحد الأدنى من Python المطلوب هو >=3.13 .

عبر pip

يمكنك أيضًا تثبيت Housaku باستخدام PIP ، لكن الأمر الدقيق يعتمد على كيفية إعداد بيئتك. في هذه الحالة ، يجب أن يبدو الأمر مثل هذا:

python3 -m pip install housaku

إعدادات

قبل البدء في استخدام Housaku ، تتمثل الخطوة الأولى في تحرير ملف config.toml الموجود في $XDG_CONFIG_HOME/housaku/config.toml . يتم إنشاء هذا الملف تلقائيًا في المرة الأولى التي تقوم فيها بتشغيل housaku وستبدو شيئًا من هذا القبيل:

 # Welcome! This is the configuration file for Housaku.

# Available themes include:
# - "dracula"
# - "textual-dark"
# - "textual-light"
# - "nord"
# - "gruvbox"
# - "catppuccin-mocha"
# - "textual-ansi"
# - "tokyo-night"
# - "monokai"
# - "flexoki"
# - "catppuccin-latte"
# - "solarized-light"

theme = " dracula "

[ files ]
# Directories to include for indexing.
# Example: include = ["/home/<user>/documents/notes"]
include = []

# Patterns to exclude from the indexing
# Example: exclude = ["*.tmp", "backup", "*.png"]
exclude = []

[ feeds ]
# List of RSS/Atom feeds to index
# Example: urls = ["https://example.com/feed", "https://anotherexample.com/rss"]
urls = []

يتم تحديد المجلد الذي يحتفظ بملف التكوين وكذلك قاعدة بيانات SQLite بواسطة الأداة المساعدة get_app_dir . يمكنك قراءة المزيد عنها هنا.

طريقة سهلة لفتح ملف config.toml هو تشغيل الأمر التالي:

housaku config

الاستخدام

يساعد

أفضل طريقة لمعرفة الأوامر المتوفرة هي تشغيل housaku مع علم --help .

housaku --help

يمكنك أيضًا معرفة المزيد حول ما يفعله أمر معين عن طريق التشغيل:

housaku [command] --help

# For example:

housaku index --help

تكوين

أمر config هو أمر بسيط للغاية يفتح ملف config.toml باستخدام المحرر الافتراضي.

housaku config

فِهرِس

بعد تكوين قائمة الدلائل التي تحتوي على المستندات التي تريد فهرستها ، بالإضافة إلى قائمة الخلاصات التي تريد جلب المنشورات منها ، يمكنك تشغيل:

housaku index

تصفية المحتوى

لفهرس ملفاتك فقط ، استخدم الأمر التالي:

housaku index --include files

لفهرسة الخلاصات الخاصة بك فقط:

housaku index --include feeds

يمكنك تحديد كلا الخيارين لفهرسة الملفات والتغذية معًا ، ولكن هذا يعادل ببساطة تشغيل أمر index دون أي خيارات.

التوازي

يمكنك أيضًا تغيير عدد مؤشرات الترابط المستخدمة عند فهرسة الملفات والمستندات الخاصة بك:

housaku index -t 8

توصيتي هي الالتزام بالعدد الافتراضي للمواضيع.

في الوقت الحالي ، تتم فهرسة الملفات بالتوازي باستخدام متعدد الخيوط ، مما يجعل العملية أسرع ولكنها تقدم أيضًا بعض المضاعفات. على سبيل المثال ، سيؤدي إلغاء الفهرسة في منتصف الطريق باستخدام ctrl+c إلى خروج بعض مؤشرات الترابط بينما سيستمر الآخرون في التشغيل في الخلفية ثم تفشل.

يبحث

أمر search

أبسط طريقة للبدء في البحث عن المستندات والمشاركات الخاصة بك هي استخدام أمر search :

houskau searh --query " Django AND Postgres "

يمكنك أيضًا الحد من عدد النتائج باستخدام الخيار --limit والذي ، افتراضيًا ، يتم تعيينه على 10:

housaku search --query " Django AND Postgres " --limit 20

إذا لم تحدد query باستخدام خيارات- --query/-q فسيتم مطالبتك بإدخال واحد.

يمكنك معرفة المزيد حول بناء جملة الاستعلام هنا.

باستخدام TUI

الطريقة المفضلة والموصى بها للبحث هي باستخدام TUI. لبدء ذلك ، فقط تشغيل:

housaku tui

للخروج من TUI ، اضغط فقط على ctrl + q ، ولتحقيق نتيجة بحث ، اضغط على Enter أثناء تمييز النتيجة.

باستخدام واجهة المستخدم على الويب

يحتوي Housaku أيضًا على واجهة مستخدم ويب بسيطة للغاية يمكنك الوصول إليها عن طريق التشغيل:

housaku web

المنفذ الافتراضي هو 4242 .

طريقة البحث هذه لها بعض القيود. على سبيل المثال ، لا يمكنك فتح النتائج التي ترتبط بمستنداتك المحلية.

vacuum purge

يتم استخدام أمر vacuum لتحسين قاعدة بيانات SQLite من خلال استعادة المساحة غير المستخدمة وتحسين الأداء. لتشغيل أمر الفراغ ، ما عليك سوى التنفيذ:

housaku vacuum

يتم استخدام أمر purge لمسح جميع البيانات تمامًا من قاعدة البيانات. يكون هذا الأمر مفيدًا عندما تريد إعادة تعيين قاعدة البيانات إلى حالتها الأولية.

housaku purge

كن حذرًا قبل استخدام كل من هذين الأمرين حيث سيكون لهما تأثير مباشر على البيانات التي تحتفظ بها في قاعدة البيانات الخاصة بك.

المساهمة

المساهمات موضع ترحيب! إذا كان لديك أي اقتراحات ، فلا تتردد في فتح مشكلة.