طريقة إعداد أداة التدقيق النحوي المحلية Harper بدون تسرب للبيانات الخارجية
TuBrief 편집팀
2026년 7월 25일
0
Computing/Software원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
عندما تحظر سياسات الأمان الداخلية الأدوات الخارجية المدعومة بالذكاء الاصطناعي مثل Grammarly، يجد المطورون أنفسهم في موقف صعب. فترك أخطاء إملائية في المستندات التقنية أو تعليقات الشفرة البرمجية قبل النشر يقلل من موثوقية العمل، ولكن تدقيق كل شيء بالعين المجردة يستغرق وقتاً طويلاً جداً.
تحل أداة Harper هذه المشكلة بشكل رائع. وباعتبارها محرك تدقيق نحوي مخصص للعمل بدون اتصال بالإنترنت ومطور بلغة Rust، فهو يمنع الاتصال بالخوادم الخارجية تماماً. وعلى عكس LanguageTool القائم على لغة Java والذي يستهلك مئات الميجابايتات من الذاكرة، فإن استهلاك Harper لذاكرة الوصول العشوائي (RAM) لا يتجاوز بضع عشرات من الميجابايتات. ونظراً لأنه يعمل بسرعة استجابة تقل عن 10 مللي ثانية، فلن تتعرض لأي بطء في المحرر الخاص بك.
يقوم harper-ls بتحليل البنية داخل الجهاز باستخدام موارد وحدة المعالجة المركزية (CPU) المحلية فقط. ما عليك سوى تثبيت الملف الثنائي باستخدام مدير الحزم المناسب لنظام التشغيل الخاص بك وتسجيله كـ LSP قياسي في المحرر.
قم بتنفيذ الأوامر في الطرفية (Terminal) لتثبيت الملف الثنائي:
brew install harpercargo install harper-ls --lockedscoop install harperفي Neovim، يمكنك تعيين أنواع الملفات المستهدفة وقواعد المدقق (Linter) باستخدام nvim-lspconfig:
`lua
local lspconfig = require('lspconfig')
lspconfig.harper_ls.setup({
filetypes = { 'markdown', 'gitcommit', 'rust', 'go', 'typescript', 'python' },
settings = {
["harper-ls"] = {
userDictPath = "~/config/harper/user_dict.txt",
workspaceDictPath = ".harper-dictionary.txt",
linters = {
SpellCheck = true,
SpelledNumbers = false,
AnA = true,
SentenceCapitalization = false,
UnclosedQuotes = true,
WrongApostrophe = false,
LongSentences = true,
RepeatedWords = true,
Spaces = true,
CorrectNumberSuffix = true
}
}
}
})
`
عند استخدام واجهة برمجة تطبيقات LSP الأصلية في Neovim 0.11 أو الأحدث، قم بتكوين vim.lsp.config['harper'] واستدعاء vim.lsp.enable('harper'). أما مستخدمو VS Code، فيمكنهم تثبيت امتداد elijah-potter.harper ثم تحديد المسار "harper.path": "/usr/local/bin/harper-ls" في ملف .vscode/settings.json وانتهى الأمر.
تأتي أداة Harper مزودة بمحلل Tree-sitter AST مدمج، لذا فهي تتجاوز الشفرة البرمجية الفعلية وتفحص فقط النصوص الإنجليزية داخل كتل التعليقات. إذا كنت تريد استبعاد تعليقات دالة معينّة تماماً من الفحص، يمكنك إضافة توجيه ضمني (Inline directive):
`javascript
// harper:ignore
function processInternalSecurityToken() {
// spellcheck:ignore
// 내부 보안 토큰 로직
}
`
عند تشغيل القاموس الإنجليزي الأساسي فقط، سيتم اعتبار المصطلحات التقنية مثل gRPC و OAuth2 و Prometheus كأخطاء. ومن خلال الاستفادة من هيكل القاموس الهرمي، يمكنك إزالة ضوضاء التحذيرات بسرعة.
تقوم أداة Harper التحقق من الكلمات عبر 4 مستويات:
| طبقة القاموس | موضع الحفظ | الغرض |
|---|---|---|
| Static Dictionary | مدمج داخل الملف الثنائي لـ harper-ls |
قاعدة بيانات الكلمات الإنجليزية الأساسية غير القابلة للتعديل |
| User Dictionary | ~/.config/harper-ls/dictionary.txt |
قاموس عام لبيئة التطوير الشخصية |
| Workspace Dictionary | جذر المشروع .harper-dictionary.txt |
قاموس المصطلحات الخاص بالمشروع (مُدار بواسطة Git) |
| File-Local Dictionary | محفوظ داخل مسار بيانات نظام التشغيل | تخزين المعرفات الخاصة بملف واحد |
.harper-dictionary.txt في الدليل الجذر للمشروع.`text
Kubernetes
gRPC
OAuth2
OpenTelemetry
Prometheus
mTLS
Netty
Etcd
`
Ctrl + .، وفي Neovim: ربط مفتاح Code Action) لإضافة الكلمة المحددة مباشرة إلى .harper-dictionary.txt.بمجرد رفع هذا الملف وحده إلى مستودع Git، سيشارك جميع أعضاء الفريق نفس قائمة الكلمات.
قم بإيقاف القواعد المزعجة عند كتابة التعليقات:
SentenceCapitalization: اضبطها على false لإيقاف قاعدة فرض الحرف الكبيرة في بداية التعليق.LongSentences: اضبطها على false لإيقاف تحذيرات الجمل الطويلة نظراً لطبيعة المستندات التقنية.SpellCheck و UnclosedQuotes: اتركها على true لفحص الأخطاء الإملائية وعلامات التنصيص غير المغلقة.يجب حظر الأخطاء الإملائية التي يفوتها المطور في المحرر خلال مرحلة طلب السحب (PR). من خلال ربط أداة سطر الأوامر (CLI) المسمى harper-cli بخط الأنابيب، يتم تصفية أخطاء القواعد تلقائياً قبل دمج الفرع الرئيسي (Main branch).
عرّف مهمة فحص ملفات Markdown المعدلة فقط في ملف .github/workflows/harper-lint.yml:
`yaml
name: Technical Documentation Linting
on:
pull_request:
paths:
- 'docs/'
- '.md'
jobs:
harper-grammar-check:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust Toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache Harper CLI Binary
uses: actions/cache@v3
with:
path: ~/.cargo/bin/harper-cli
key: ${{ runner.os }}-harper-cli-${{ hashFiles('**/Cargo.lock') }}
- name: Install Harper CLI
run: |
if ! command -v harper-cli &> /dev/null; then
cargo install harper-cli --locked
fi
- name: Get Changed Markdown Files
id: changed-files
run: |
git fetch origin ${{ github.base_ref }}
FILES=$(git diff --name-only --diff-filter=AM origin/${{ github.base_ref }} HEAD | grep '\.md$' || true)
echo "files=$FILES" >> $GITHUB_OUTPUT
- name: Run Harper Lint Check
if: steps.changed-files.outputs.files != ''
run: |
ERRORS=0
for file in ${{ steps.changed-files.outputs.files }}; do
echo "Linting $file with Harper..."
harper-cli lint "$file" || ERRORS=$((ERRORS+1))
done
if [ $ERRORS -gt 0 ]; then
echo "Harper validation failed with $ERRORS error(s)."
exit 1
fi
`
إذا قمت بعمل Commit لملف .harper-dictionary.txt الموجود في جذر المشروع أيضاً، سيقوم مشغل CI (CI runner) بإجراء الفحص بناءً على نفس قائمة الكلمات الموجودة في المحرر. أما إذا كنت تستخدم مولد مواقع ثابتة (SSG) مثل MkDocs أو Docusaurus، فمن الأفضل تعيين الأمر harper-cli lint docs/ ليتم تنفيذه مباشرة قبل تشغيل سكريبت البناء (Build script).