**یک مهارت برای دستیار کدنویسی هوش مصنوعی.** `/graphify` را در Claude Code، Codex، OpenCode، Kilo Code، Cursor، Gemini CLI، GitHub Copilot CLI، VS Code Copilot Chat، Aider، Amp، OpenClaw، Factory Droid، Trae، Hermes، Kimi Code، Kiro، Pi، Devin CLI یا Google Antigravity تایپ کنید — تمام پروژه‌تان را می‌خواند، یک گراف دانش می‌سازد، و ساختاری که نمی‌دانستید وجود دارد را به شما بازمی‌گرداند. کدبیس را سریع‌تر درک کنید. «چرا»ی پشت تصمیمات معماری را کشف کنید. کاملاً چندوجهی. کد، PDF، مارک‌داون، اسکرین‌شات، نمودار، عکس وایت‌بورد، تصاویر به زبان‌های دیگر، یا فایل‌های ویدئو و صوتی بریزید — graphify مفاهیم و روابط را از همه آن‌ها استخراج کرده و در یک گراف به هم متصل می‌کند. ویدئوها به‌صورت محلی با Whisper رونویسی می‌شوند. ۳۶ زبان برنامه‌نویسی از طریق tree-sitter AST پشتیبانی می‌شوند. > Andrej Karpathy یک پوشه `/raw` نگه می‌دارد که در آن مقالات، توییت‌ها، اسکرین‌شات‌ها و یادداشت‌ها می‌ریزد. graphify پاسخ آن مشکل است — **۷۱.۵ برابر** کمتر توکن در هر پرس‌وجو در مقایسه با خواندن فایل‌های خام، در طول جلسات پایدار، و صادق در مورد آنچه پیدا شده در برابر آنچه استنباط شده است.

``` /graphify . ```

همین. سه فایل دریافت می‌کنید:

``` graphify-out/ ├── graph.html در هر مرورگری باز کنید — روی گره‌ها کلیک کنید، فیلتر کنید، جستجو کنید ├── GRAPH_REPORT.md نکات کلیدی: مفاهیم محوری، اتصالات شگفت‌انگیز، سؤالات پیشنهادی └── graph.json گراف کامل — هر زمان بدون نیاز به بازخوانی فایل‌ها پرس‌وجو کنید ```

برای یک صفحه معماری خوانا با نمودارهای جریان فراخوانی Mermaid، اجرا کنید:

```bash graphify export callflow-html ``` ---

## پیش‌نیازها

| پیش‌نیاز | حداقل | بررسی | نصب | |---|---|---|---| | Python | ۳.۱۰+ | `python --version` | [python.org](https://www.python.org/downloads/) | | uv *(پیشنهادی)* | هر نسخه | `uv --version` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | | pipx *(جایگزین)* | هر نسخه | `pipx --version` | `pip install pipx` |

**نصب سریع macOS (Homebrew):**

```bash brew install python@3.12 uv ```

**نصب سریع Windows:**

```powershell winget install astral-sh.uv ```

**Ubuntu/Debian:**

```bash sudo apt install python3.12 python3-pip pipx # یا نصب uv: curl -LsSf https://astral.sh/uv/install.sh | sh ``` ---

## نصب > **بسته رسمی:** بسته PyPI به نام `graphifyy` است (با دو y). سایر بسته‌های `graphify*` در PyPI وابسته به این پروژه نیستند. دستور CLI همچنان `graphify` است. **مرحله ۱ — نصب بسته:**

```bash # پیشنهادی (uv به‌طور خودکار graphify را در PATH قرار می‌دهد): uv tool install graphifyy # جایگزین‌ها: pipx install graphifyy pip install graphifyy # ممکن است نیاز به تنظیم PATH داشته باشد — یادداشت زیر را ببینید ```

**مرحله ۲ — ثبت مهارت در دستیار هوش مصنوعی:**

```bash graphify install ```

همین. دستیار هوش مصنوعی‌تان را باز کنید و `/graphify .` تایپ کنید. برای نصب مهارت دستیار در مخزن جاری به‌جای پروفایل کاربری، `--project` اضافه کنید:

```bash graphify install --project graphify install --project --platform codex ```

> **یادداشت PowerShell:** از `graphify .` استفاده کنید نه `/graphify .` — اسلش ابتدایی در PowerShell جداکننده مسیر است. > **`graphify: command not found`؟** از `uv tool install graphifyy` یا `pipx install graphifyy` استفاده کنید — هر دو CLI را به‌طور خودکار در PATH قرار می‌دهند. ### انتخاب پلتفرم

| پلتفرم | دستور نصب | |----------|----------------| | Claude Code (Linux/Mac) | `graphify install` | | Claude Code (Windows) | `graphify install` (تشخیص خودکار) یا `graphify install --platform windows` | | CodeBuddy | `graphify install --platform codebuddy` | | Codex | `graphify install --platform codex` | | OpenCode | `graphify install --platform opencode` | | Kilo Code | `graphify install --platform kilo` | | GitHub Copilot CLI | `graphify install --platform copilot` | | VS Code Copilot Chat | `graphify vscode install` | | Aider | `graphify install --platform aider` | | OpenClaw | `graphify install --platform claw` | | Factory Droid | `graphify install --platform droid` | | Trae | `graphify install --platform trae` | | Trae CN | `graphify install --platform trae-cn` | | Gemini CLI | `graphify install --platform gemini` | | Hermes | `graphify install --platform hermes` | | Kimi Code | `graphify install --platform kimi` | | Amp | `graphify amp install` | | Kiro IDE/CLI | `graphify kiro install` | | Pi coding agent | `graphify install --platform pi` | | Cursor | `graphify cursor install` | | Devin CLI | `graphify devin install` | | Google Antigravity | `graphify antigravity install` |

### افزونه‌های اختیاری فقط آنچه نیاز دارید نصب کنید:

| افزونه | چه چیزی اضافه می‌کند | نصب | |---|---|---| | `pdf` | استخراج PDF | `uv tool install "graphifyy[pdf]"` | | `office` | پشتیبانی از `.docx` و `.xlsx` | `uv tool install "graphifyy[office]"` | | `google` | رندرینگ Google Sheets | `uv tool install "graphifyy[google]"` | | `video` | رونویسی ویدئو/صوت | `uv tool install "graphifyy[video]"` | | `mcp` | سرور MCP stdio | `uv tool install "graphifyy[mcp]"` | | `neo4j` | پشتیبانی از Neo4j | `uv tool install "graphifyy[neo4j]"` | | `ollama` | استنتاج محلی Ollama | `uv tool install "graphifyy[ollama]"` | | `openai` | OpenAI / APIهای سازگار با OpenAI | `uv tool install "graphifyy[openai]"` | | `gemini` | Google Gemini API | `uv tool install "graphifyy[gemini]"` | | `anthropic` | Anthropic Claude API | `uv tool install "graphifyy[anthropic]"` | | `bedrock` | AWS Bedrock (از IAM استفاده می‌کند) | `uv tool install "graphifyy[bedrock]"` | | `sql` | استخراج طرح SQL | `uv tool install "graphifyy[sql]"` | | `all` | همه موارد بالا | `uv tool install "graphifyy[all]"` | ---

## دستیار را همیشه از گراف استفاده کنید پس از ساخت گراف، یک بار در پروژه‌تان اجرا کنید:

| پلتفرم | دستور | |----------|---------| | Claude Code | `graphify claude install` | | CodeBuddy | `graphify codebuddy install` | | Codex | `graphify codex install` | | OpenCode | `graphify opencode install` | | Kilo Code | `graphify kilo install` | | GitHub Copilot CLI | `graphify copilot install` | | VS Code Copilot Chat | `graphify vscode install` | | Aider | `graphify aider install` | | OpenClaw | `graphify claw install` | | Factory Droid | `graphify droid install` | | Trae | `graphify trae install` | | Cursor | `graphify cursor install` | | Gemini CLI | `graphify gemini install` | | Amp | `graphify amp install` | | Kiro IDE/CLI | `graphify kiro install` | | Devin CLI | `graphify devin install` | | Google Antigravity | `graphify antigravity install` |

این یک فایل پیکربندی کوچک می‌نویسد که به دستیارتان می‌گوید برای سؤالات مربوط به کدبیس، گراف دانش را مشورت بگیرد. برای حذف graphify از همه پلتفرم‌ها به یکباره: `graphify uninstall` (با `--purge` برای حذف `graphify-out/` نیز). --- ## محتوای گزارش - **گره‌های اصلی** — پرارتباط‌ترین مفاهیم پروژه. همه چیز از این‌ها عبور می‌کند. - **اتصالات شگفت‌انگیز** — پیوندهایی بین چیزهایی که در فایل‌ها یا ماژول‌های مختلف زندگی می‌کنند. بر اساس میزان غیرمنتظره بودن رتبه‌بندی شده. - **«چرا»** — نظرات درون‌خطی (`# NOTE:`، `# WHY:`، `# HACK:`)، داک‌استرینگ‌ها و منطق طراحی از اسناد به‌عنوان گره‌های جداگانه مرتبط با کدی که توضیح می‌دهند استخراج می‌شوند. - **سؤالات پیشنهادی** — ۴ تا ۵ سؤال که گراف به‌طور منحصربه‌فرد می‌تواند پاسخ دهد. - **برچسب‌های اطمینان** — هر رابطه استنباط‌شده با `EXTRACTED`، `INFERRED` یا `AMBIGUOUS` علامت‌گذاری می‌شود. همیشه می‌دانید چه چیزی پیدا شده در برابر چه چیزی حدس زده شده. --- ## فایل‌های پشتیبانی‌شده

| نوع | پسوندها | |------|-----------| | کد (۳۶ دستور زبان tree-sitter) | `.py .ts .js .jsx .tsx .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .exs .vue .svelte .dart` و بیشتر | | اسناد | `.md .mdx .html .txt .rst .yaml .yml` | | Office | `.docx .xlsx` (نیاز به `graphifyy[office]`) | | PDF | `.pdf` | | تصاویر | `.png .jpg .webp .gif` | | ویدئو / صوت | `.mp4 .mov .mp3 .wav` و بیشتر (نیاز به `graphifyy[video]`) | | YouTube / URLها | هر URL ویدئویی (نیاز به `graphifyy[video]`) |

کد به‌صورت محلی با tree-sitter بدون هیچ فراخوانی API استخراج می‌شود. بقیه از طریق API مدل دستیار هوش مصنوعی شما پردازش می‌شوند. --- ## دستورات رایج

```bash /graphify . # ساخت گراف برای پوشه جاری /graphify ./docs --update # فقط فایل‌های تغییریافته را مجدداً استخراج کن /graphify . --cluster-only # خوشه‌بندی مجدد بدون استخراج مجدد /graphify . --no-viz # فقط گزارش + JSON، بدون HTML /graphify . --wiki # ساخت ویکی مارک‌داون از گراف graphify export callflow-html # HTML معماری/جریان فراخوانی Mermaid /graphify query "چه چیزی auth را به پایگاه داده متصل می‌کند؟" /graphify path "UserService" "DatabasePool" /graphify explain "RateLimiter" /graphify add https://arxiv.org/abs/1706.03762 # یک مقاله را واکشی و اضافه کن /graphify add # رونویسی و اضافه کردن ویدئو graphify hook install # بازسازی خودکار پس از هر commit graphify merge-graphs a.json b.json # ترکیب دو گراف graphify prs # داشبورد PR: وضعیت CI، بررسی، تأثیر گراف graphify prs 42 # بررسی عمیق PR شماره ۴۲ graphify prs --triage # رتبه‌بندی صف بررسی با هوش مصنوعی ```

[مرجع کامل دستورات](#full-command-reference) را ببینید. --- ## نادیده گرفتن فایل‌ها یک `.graphifyignore` در ریشه پروژه بسازید — همان سینتکس `.gitignore`، از جمله نفی با `!`. **`.gitignore` به‌طور خودکار رعایت می‌شود.** اگر `.graphifyignore` در یک دایرکتوری وجود نداشته باشد، graphify به `.gitignore` آن دایرکتوری بازمی‌گردد.

``` # .graphifyignore node_modules/ dist/ *.generated.py # فقط src/ را ایندکس کن، بقیه را نادیده بگیر * !src/ !src/** ``` ---

## تنظیمات تیمی `graphify-out/` برای commit شدن در git طراحی شده تا همه در تیم با یک نقشه شروع کنند. **افزودن‌های پیشنهادی به `.gitignore`:**

``` graphify-out/cost.json # فقط محلی # graphify-out/cache/ # اختیاری: برای سرعت commit کنید، برای کوچک نگه داشتن repo حذف کنید ```

**جریان کار:** ۱. یک نفر `/graphify .` اجرا می‌کند و `graphify-out/` را commit می‌کند. ۲. همه pull می‌کنند — دستیارشان فوراً گراف را می‌خواند. ۳. `graphify hook install` را اجرا کنید تا پس از هر commit به‌طور خودکار بازسازی شود. ۴. وقتی اسناد یا مقالات تغییر کردند، `/graphify --update` اجرا کنید. --- ## استفاده مستقیم از گراف

```bash # پرس‌وجو از گراف در ترمینال graphify query "جریان احراز هویت را نشان بده" graphify query "چه چیزی DigestAuth را به Response متصل می‌کند؟" --graph graphify-out/graph.json # نمایش گراف به‌عنوان سرور MCP python -m graphify.serve graphify-out/graph.json # یا سرویس‌دهی از طریق HTTP برای دسترسی تیمی: python -m graphify.serve graphify-out/graph.json --transport http --port 8080 python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET" ```

سرور MCP دسترسی ساختاریافته می‌دهد: `query_graph`، `get_node`، `get_neighbors`، `shortest_path`، `list_prs`، `get_pr_impact`، `triage_prs`. --- ## متغیرهای محیطی اینها فقط برای **استخراج بدون نمایشگر / CI** (`graphify extract`) لازم هستند. هنگام اجرا از طریق مهارت `/graphify` داخل IDE، API مدل توسط جلسه IDE شما تأمین می‌شود.

| متغیر | استفاده | شرط لزوم | |---|---|---| | `ANTHROPIC_API_KEY` | بک‌اند Claude (Anthropic) | `--backend claude` | | `GEMINI_API_KEY` یا `GOOGLE_API_KEY` | بک‌اند Google Gemini | `--backend gemini` | | `OPENAI_API_KEY` | OpenAI یا APIهای سازگار | `--backend openai` | | `DEEPSEEK_API_KEY` | بک‌اند DeepSeek | `--backend deepseek` | | `MOONSHOT_API_KEY` | بک‌اند Kimi Code | `--backend kimi` | | `OLLAMA_BASE_URL` | URL استنتاج محلی Ollama | `--backend ollama` | | `AZURE_OPENAI_API_KEY` | بک‌اند Azure OpenAI | `--backend azure` | | `GRAPHIFY_MAX_WORKERS` | تعداد thread های موازی AST | اختیاری | | `GRAPHIFY_FORCE` | بازسازی اجباری گراف | اختیاری | | `GRAPHIFY_QUERY_LOG_DISABLE` | برای غیرفعال کردن ثبت پرس‌وجو `1` تنظیم کنید | اختیاری | ---

## حریم خصوصی - **فایل‌های کد** — به‌صورت محلی از طریق tree-sitter پردازش می‌شوند. هیچ چیزی دستگاه شما را ترک نمی‌کند. - **ویدئو / صوت** — به‌صورت محلی با faster-whisper رونویسی می‌شوند. هیچ چیزی دستگاه شما را ترک نمی‌کند. - **اسناد، PDF‌ها، تصاویر** — برای استخراج معنایی به API مدل دستیار هوش مصنوعی شما ارسال می‌شوند. - بدون تله‌متری، بدون ردیابی استفاده، بدون آنالیتیکس. --- ## عیب‌یابی **`graphify: command not found` پس از `pip install graphifyy`** pip اسکریپت‌ها را در دایرکتوری bin کاربر نصب می‌کند که ممکن است در PATH نباشد: - macOS: `~/Library/Python/3.x/bin` را به PATH در `~/.zshrc` اضافه کنید - Linux: `~/.local/bin` را به PATH در `~/.bashrc` اضافه کنید - یا از `uv tool install graphifyy` / `pipx install graphifyy` استفاده کنید. **`/graphify .` در PowerShell "path not recognized" نشان می‌دهد** PowerShell `/` ابتدایی را به‌عنوان جداکننده مسیر در نظر می‌گیرد. از `graphify .` (بدون اسلش) در Windows استفاده کنید. **گراف پس از `--update` یا بازسازی گره کمتری دارد** اگر یک refactor فایل‌ها را حذف کرده، گره‌های قدیمی باقی می‌مانند. `--force` (یا `GRAPHIFY_FORCE=1`) را پاس دهید:

```bash graphify extract . --force ```

**استخراج برای اسناد یا PDF‌ها گره/یال خالی برمی‌گرداند** اسناد، PDF‌ها و تصاویر به یک فراخوانی LLM نیاز دارند. بررسی کنید API key تنظیم شده و بک‌اند صحیح است:

```bash ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude ``` ---

## مرجع کامل دستورات

``` /graphify # اجرا روی دایرکتوری جاری /graphify ./raw # اجرا روی پوشه مشخص /graphify ./raw --mode deep # استخراج رابطه‌های عمیق‌تر /graphify ./raw --update # فقط فایل‌های تغییریافته را مجدداً استخراج کن /graphify ./raw --directed # حفظ جهت یال‌ها /graphify ./raw --cluster-only # خوشه‌بندی مجدد روی گراف موجود /graphify ./raw --no-viz # بدون HTML بصری‌سازی /graphify ./raw --obsidian # تولید Obsidian vault /graphify ./raw --wiki # ساخت ویکی مارک‌داون قابل خزیدن برای agent /graphify ./raw --svg # خروجی graph.svg /graphify ./raw --graphml # خروجی برای Gephi / yEd /graphify ./raw --neo4j # تولید cypher.txt برای Neo4j /graphify ./raw --watch # همگام‌سازی خودکار با تغییر فایل‌ها /graphify ./raw --mcp # شروع سرور MCP stdio /graphify add https://arxiv.org/abs/1706.03762 /graphify add /graphify query "چه چیزی attention را به optimizer متصل می‌کند؟" /graphify path "DigestAuth" "Response" /graphify explain "SwinTransformer" graphify uninstall # حذف از همه پلتفرم‌ها graphify uninstall --purge # همچنین graphify-out/ را حذف کن graphify hook install # hook های post-commit + post-checkout graphify hook uninstall graphify hook status graphify claude install # CLAUDE.md + PreToolUse hook (Claude Code) graphify codex install # AGENTS.md + PreToolUse hook (Codex) graphify cursor install # .cursor/rules/graphify.mdc (Cursor) graphify gemini install # GEMINI.md + BeforeTool hook (Gemini CLI) graphify amp install # فایل مهارت (Amp) graphify kiro install # .kiro/skills/ + .kiro/steering/ (Kiro) graphify devin install # فایل مهارت + .windsurf/rules/ (Devin CLI) graphify antigravity install # .agents/rules + .agents/workflows (Google Antigravity) graphify extract ./docs # استخراج بدون نمایشگر برای CI graphify extract ./docs --backend gemini # بک‌اند صریح graphify extract ./docs --backend ollama # Ollama محلی - بدون نیاز به API key graphify extract ./docs --backend bedrock # AWS Bedrock از طریق IAM graphify extract --postgres "postgresql://user:pass@host/db" # طرح PostgreSQL زنده graphify prs # داشبورد PR graphify prs 42 # بررسی عمیق PR شماره ۴۲ graphify prs --triage # رتبه‌بندی هوش مصنوعی graphify prs --conflicts # PR هایی که جوامع گراف را به اشتراک می‌گذارند graphify export callflow-html # HTML معماری/جریان فراخوانی graphify merge-graphs a.json b.json --out merged.json graphify --version ``` ---

## بیشتر بدانید - [نحوه عملکرد](../../docs/how-it-works.md) — پایپ‌لاین استخراج، تشخیص جامعه، امتیازدهی اطمینان، معیارها - [ARCHITECTURE.md](../../ARCHITECTURE.md) — تقسیم‌بندی ماژول‌ها، نحوه اضافه کردن زبان جدید - [یکپارچه‌سازی‌های اختیاری](../../docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite --- ## ساخته‌شده روی graphify — Penpax [**Penpax**](https://graphifylabs.ai) لایه همیشه‌روشن ساخته‌شده روی graphify است — همان رویکرد گراف را بر کل زندگی کاری شما اعمال می‌کند: جلسات، تاریخچه مرورگر، ایمیل‌ها، فایل‌ها و کد، به‌صورت مداوم در پس‌زمینه به‌روزرسانی می‌شود. ساخته‌شده برای کسانی که کارشان در صدها مکالمه و سند پراکنده است. بدون ابر، کاملاً روی دستگاه. **آزمایش رایگان به‌زودی راه‌اندازی می‌شود.** [به لیست انتظار بپیوندید ←](https://graphifylabs.ai) ---

مشارکت در پروژه

### راه‌اندازی محیط توسعه این پروژه از [uv](https://docs.astral.sh/uv/) برای جریان کار توسعه استفاده می‌کند. یک بار آن را نصب کنید، سپس:

```bash git clone https://github.com/safishamsi/graphify.git cd graphify git checkout v8 # شاخه توسعه فعال uv sync --all-extras ```

### اجرای تست‌ها

```bash uv run pytest tests/ -q # اجرای کل مجموعه uv run pytest tests/test_extract.py -q # یک ماژول ```

### جریان کار Git - توسعه فعال روی شاخه `v8` انجام می‌شود. - سبک commit: `fix: <توضیح>` / `feat: <توضیح>` / `docs: <توضیح>` - قبل از باز کردن PR، `uv run pytest tests/ -q` اجرا کنید و از موفقیت آن مطمئن شوید. ### چه چیزی مشارکت کنیم **نمونه‌های کاری** مفیدترین نوع مشارکت هستند. `/graphify` را روی یک corpus واقعی اجرا کنید، خروجی را در `worked/{slug}/` ذخیره کنید، یک `review.md` صادقانه بنویسید که چه چیزهایی درست و نادرست بوده، و یک PR باز کنید. **باگ‌های استخراج** — یک issue با فایل ورودی، آیتم کش (`graphify-out/cache/`) و آنچه اشتباه یا حذف شده باز کنید. برای مسئولیت‌های ماژول و نحوه اضافه کردن زبان جدید [ARCHITECTURE.md](../../ARCHITECTURE.md) را ببینید.