استفاده از Hermes
TUI

TUI

TUI رابط مدرن Hermes است — یک رابط متنی مبتنی بر همان Runtime پایتونی که CLI کلاسیک از آن استفاده می‌کند. همان عامل، همان نشست‌ها، همان دستورات اسلش؛ رابطی تمیزتر و پاسخگوتر برای تعامل با آن‌ها.

CLI کلاسیک

روش پیشنهادی برای اجرای تعاملی Hermes است.

راه‌اندازی

# راه‌اندازی TUI
hermes --tui
# ادامه آخرین نشست TUI (به آخرین نشست کلاسیک بازمی‌گردد)
hermes --tui -c
hermes --tui --continue
# ادامه یک نشست خاص بر اساس ID یا عنوان
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"
# اجرای مستقیم از سورس — مرحله پیش‌ساخت را رد می‌کند (برای مشارکت‌کنندگان TUI)
hermes --tui --dev

همچنین می‌توانید آن را از طریق متغیر محیطی فعال کنید:

export HERMES_TUI=1
hermes          # حالا از TUI استفاده می‌کند
hermes chat     # یکسان

یا آن را به عنوان پیش‌فرض پایدار در ~/.hermes/config.yaml تنظیم کنید:

display:
  interface: tui   # "cli" (پیش‌فرض) یا "tui"

با display.interface: tui، یک hermes ساده (و hermes chat) TUI را راه‌اندازی می‌کند. پرچم‌های صریح همیشه اولویت دارند — hermes --cli را برای بازگشت به REPL کلاسیک در یک فراخوانی اجرا کنید، یا hermes --tui / HERMES_TUI=1 برای اجبار TUI وقتی پیش‌فرض تنظیمات cli است.

CLI کلاسیک همچنان پیش‌فرض ارسال شده است. هر چیزی که در رابط CLI مستند شده — دستورات اسلش، دستورات سریع، پیش‌بارگذاری مهارت‌ها، شخصیت‌ها، ورودی چندخطی، وقفه‌ها — به یک شکل در TUI کار می‌کند.

رابط CLI

چرا TUI

فریم اول فوری — بنر قبل از تکمیل بارگذاری برنامه رسم می‌شود، بنابراین ترمینال هرگز در حین راه‌اندازی Hermes یخ نمی‌زند.
ورودی غیرمسدود — پیام‌ها را تایپ و در صف قرار دهید قبل از آماده شدن نشست. اولین درخواست شما در لحظه آنلاین شدن عامل ارسال می‌شود.
پوشش‌های غنی — انتخابگر مدل، انتخابگر نشست، درخواست‌های تأیید و شفاف‌سازی همگی به جای جریان‌های درون‌خطی به صورت پنل‌های مودال رندر می‌شوند.
پنل نشست زنده — ابزارها و مهارت‌ها به تدریج در حین مقداردهی اولیه پر می‌شوند.
انتخاب دوستدار ماوس — با کشیدن متن را با پس‌زمینه انتخاب یکنواخت برجسته کنید به جای SGR معکوس. با حرکت کپی معمولی ترمینال خود کپی کنید.
رندر صفحه متناوب — به‌روزرسانی‌های تفاضلی به این معنی هستند که هنگام پخش هیچ سوسویی وجود ندارد و پس از خروج آشفتگی scrollback وجود ندارد.
امکانات آهنگساز — جمع‌بندی inline paste برای قطعات بلند، متن‌چسبان Cmd+V/Ctrl+V با fallback تصویر کلیپ‌بورد، ایمنی bracketed-paste، و عادی‌سازی پیوست تصویر/مسیر فایل.

skins و personalities یکسانی اعمال می‌شوند. در حین نشست با /skin ares، /personality pirate تعویض کنید و رابط کاربری فوراً بازرندر می‌شود. لیست کامل کلیدهای قابل تنظیم و اینکه کدام‌ها برای کلاسیک در مقابل TUI اعمال می‌شوند را در Skins & Themes ببینید — TUI پالت بنر، رنگ‌های رابط کاربری، گلیف/رنگ درخواست، نمایش نشست، منوی تکمیل خودکار، پس‌زمینه انتخاب، tool_prefix و help_header را رعایت می‌کند.

skins personalities Skins & Themes

بخش‌های قابل جمع‌بندی بنر

بنر راه‌اندازی TUI اطلاعات Runtime را در چهار بخش قابل جمع‌بندی گروه‌بندی می‌کند، هر کدام با یک ▸/▾ در کنار عنوان بخش رندر می‌شوند:

بخش	حالت پیش‌فرض
ابزارها	باز
مهارت‌ها	جمع‌شده
درخواست سیستم	جمع‌شده
سرورهای MCP	جمع‌شده

روی هر نقطه‌ای از عنوان بخش (یا ▸/▾ آن) کلیک کنید تا آن را تغییر دهید. لیست ابزارها به طور پیش‌فرض باز است زیرا بخشی است که بیشترین بررسی را در شروع نشست دارد؛ مهارت‌ها، درخواست سیستم و سرورهای MCP به طور پیش‌فرض جمع می‌شوند تا بنر حتی وقتی ده‌ها مهارت نصب کرده‌اید یا سرورهای MCP زیادی متصل کرده‌اید فشرده بماند. حالت مربوط به نمونه بنر محلی است، بنابراین راه‌اندازی بعدی به پیش‌فرض‌ها بازمی‌گردد.

پیش‌نیازها

Node.js ≥ 20 — TUI به عنوان یک فرآیند فرعی از CLI پایتونی اجرا می‌شود. hermes doctor این را تأیید می‌کند.
TTY — مانند CLI کلاسیک، لوله‌کشی stdin یا اجرا در محیط‌های غیرتعاملی به حالت query تکی بازمی‌گردد.

hermes doctor

در اولین راه‌اندازی Hermes وابستگی‌های Node TUI را در ui-tui/node_modules نصب می‌کند (یک‌باره، چند ثانیه). راه‌اندازی‌های بعدی سریع هستند. اگر نسخه جدید Hermes را بکشید، بسته TUI هنگامی که سورس‌ها جدیدتر از dist هستند به طور خودکار بازساخته می‌شود.

ui-tui/node_modules

پیش‌ساخت خارجی

توزیع‌هایی که بسته پیش‌ساخت شده ارائه می‌دهند (Nix، بسته‌های سیستم) می‌توانند Hermes را به آن اشاره دهند:

export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
hermes --tui

پوشه باید dist/entry.js را شامل شود.

میانبرهای صفحه‌کلید

میانبرهای صفحه‌کلید دقیقاً با CLI کلاسیک مطابقت دارند. تنها تفاوت‌های رفتاری:

کشیدن ماوس متن را با پس‌زمینه انتخاب یکنواخت برجسته می‌کند.
Cmd+V/Ctrl+V ابتدا چسباندن متن معمولی را امتحان می‌کند، سپس به OSC52/خواندن کلیپ‌بورد بومی بازمی‌گردد، و در نهایت پیوست تصویر وقتی کلیپ‌بورد یا پیکربندی چسبانده شده به یک تصویر حل می‌شود.
/terminal-setup اتصالات ترمینال محلی VS Code / Cursor / Windsurf را برای تطابق بهتر Cmd+Enter و undo/redo در macOS نصب می‌کند.
تکمیل خودکار اسلش به عنوان یک پنل شناور با توضیحات باز می‌شود، نه یک لیست کشویی درون‌خطی.
Ctrl+X سوئیچگر نشست زنده را باز می‌کند. وقتی یک پیام در صف برجسته شده (ارسال شده در حالی که عامل هنوز در حال اجرا بود)، همچنان آن پیام صف‌شده را حذف می‌کند. Esc ویرایش را لغو کرده و بدون حذف از حالت برجسته خارج می‌کند.
Ctrl+G/Ctrl+X Ctrl+E — بافر ورودی فعلی را در $EDITOR برای ترکیب چندخطی/درخواست طولانی باز کنید؛ ذخیره و خروج محتوا را به عنوان درخواست بازمی‌گرداند.

/terminal-setup

دستورات اسلش

همه دستورات اسلش بدون تغییر کار می‌کنند. چند مورد متعلق به TUI هستند — خروجی غنی‌تری تولید می‌کنند یا به جای پنل‌های درون‌خطی به صورت پوشش رندر می‌شوند:

دستور	رفتار TUI
/help	پوشش با دستورات دسته‌بندی شده، قابل پیمایش با کلیدهای جهت‌نما
/sessions (یا /switch)	سوئیچگر نشست زنده — لیست نشست‌های باز TUI، تعویض بین آن‌ها، بستن آن‌ها، یا شروع یکی دیگر
/model	انتخابگر مدل مودال گروه‌بندی شده بر اساس ارائه‌دهنده، با نکات هزینه
/skin	پیش‌نمایش زنده — تغییر موضوع در حین مرور اعمال می‌شود
/details	تغییر جزئیات verbose فراخوانی ابزار (سراسری یا به ازای هر بخش)
/usage	پنل غنی توکن / هزینه / زمینه
/agents (یا /tasks)	پوشش قابلیت مشاهده — درخت subagent زنده با کنترل‌های kill/pause، خلاصه هزینه / توکن / فایل به ازای هر شاخه، تاریخچه نوبت به نوبت
/reload	`~/.hermes/.env` را دوباره در فرآیند TUI در حال اجرا می‌خواند تا کلیدهای API جدید اضافه شده بدون راه‌اندازی مجدد اعمال شوند
/mouse [on\|off\|toggle\|wheel\|buttons\|all]	یک پیش‌تنظیم ردیابی ماوس را در زمان اجرا انتخاب کنید (همچنین در `display.mouse_tracking` `config.yaml` ذخیره می‌شود). `wheel` (1000+1006) اسکرول چرخ اسکرول را بدون رویدادهای hover که باعث می‌شود tmux “No image in clipboard” را روی ردیف درخواست اسپم کند، حفظ می‌کند؛ `buttons` کشیدن برای انتخاب را اضافه می‌کند؛ `all` پیش‌فرض با رابط کاربری مبتنی بر hover است.

هر دستور اسلش دیگری (شامل مهارت‌های نصب شده، دستورات سریع و تغییردهنده‌های شخصیت) دقیقاً مانند CLI کلاسیک کار می‌کند. مرجع دستورات اسلش را ببینید.

مرجع دستورات اسلش

سوئیچگر نشست زنده

از سوئیچگر نشست زنده استفاده کنید وقتی می‌خواهید یک ترمینال به عنوان ارسال‌کننده برای چندین نشست TUI عمل کند. فقط نشست‌هایی را فهرست می‌کند که در حال حاضر در این فرآیند TUI زنده هستند؛ نشست‌های بسته شده رونوشت‌های ذخیره شده باقی می‌مانند و همچنان قابل بازگشایی با /resume یا hermes --tui --resume <id-or-title> هستند.

آن را با هر یک از این روش‌ها باز کنید:

Ctrl+X از TUI.
/sessions یا /switch.
/sessions new برای ایجاد فوری یک نشست زنده جدید.
روی شمارش N live sessions در خط وضعیت کلیک کنید.

داخل سوئیچگر:

↑/↓ انتخاب را جابجا می‌کند؛ کلیک ماوس نیز ردیف‌ها را انتخاب می‌کند.
Enter به نشست زنده انتخاب شده تعویض می‌کند.
Ctrl+D نشست زنده انتخاب شده را می‌بندد.
Ctrl+N یک نشست زنده خالی شروع می‌کند.
Ctrl+R لیست نشست‌های زنده را تازه‌سازی می‌کند.
Esc سوئیچگر را می‌بندد.
+new را انتخاب کنید، یک درخواست تایپ کنید و Enter را فشار دهید تا یک نشست زنده جدید ارسال شود. ابتدا Tab را فشار دهید اگر می‌خواهید فقط برای آن نشست جدید مدلی انتخاب کنید.

رندر ریاضی LaTeX

پایپلاین markdown TUI ریاضیات LaTeX را به صورت inline رندر می‌کند: $E = mc^2$ و $$\frac{a}{b}$$ به جای منبع TeX خام به صورت ریاضیات قالب‌بندی شده Unicode رندر می‌شوند. برای ریاضیات inline و block کار می‌کند؛ نحو پشتیبانی نشده به نمایش TeX تحت کد wrap شده بازمی‌گردد تا قابل کپی باشد.

این همیشه فعال است — چیزی برای پیکربندی وجود ندارد. CLI کلاسیک TeX خام را حفظ می‌کند.

تشخیص ترمینال روشن

TUI به طور خودکار ترمینال‌های روشن را تشخیص می‌دهد و مطابقاً به موضوع روشن تعویض می‌کند. تشخیص در سه لایه کار می‌کند:

متغیر محیطی HERMES_TUI_THEME — بالاترین اولویت. مقادیر: light، dark، یا یک هگز پس‌زمینه ۶ کاراکتری خام (مثلاً ffffff، 1a1a2e).
متغیر محیطی COLORFGBG — نکته کلاسیک “رنگ پس‌زمینه من چیست؟” که توسط ترمینال‌های مشتق از xterm استفاده می‌شود.
کاوش پس‌زمینه ترمینال از طریق OSC 11 — روی ترمینال‌های مدرن (Ghostty، Warp، iTerm2، WezTerm، Kitty) کار می‌کند که COLORFGBG را تنظیم نمی‌کنند.

اگر می‌خواهید موضوع روشن را صرف نظر از ترمینال به طور دائم داشته باشید:

export HERMES_TUI_THEME=light

استایل‌های نشانگر اشغال

نشانگر اشغال خط وضعیت قابل اتصال است — پیش‌فرض پالت چهره کاوایی Hermes را هر ۲.۵ ثانیه در حین کار عامل می‌چرخاند. استایل متفاوتی را از طریق تنظیمات یا دستور /indicator انتخاب کنید:

display:
  tui_status_indicator: kaomoji   # kaomoji | emoji | unicode | ascii

یا در حین نشست: /indicator emoji و غیره. استایل‌ها با عرض گلیف‌های مطابق ارائه می‌شوند تا بقیه خط وضعیت هنگام چرخش تکان نخورد.

بازیابی خودکار

به طور پیش‌فرض، hermes --tui در هر راه‌اندازی یک نشست جدید شروع می‌کند. برای اتصال مجدد خودکار به آخرین نشست TUI (مفید وقتی ترمینال یا اتصال SSH شما به طور غیرمنتظره قطع می‌شود)، فعال کنید:

export HERMES_TUI_RESUME=1          # آخرین نشست TUI
# یا:
export HERMES_TUI_RESUME=<session-id>   # نشست خاص

متغیر را unset کنید یا به صورت صریح --resume <id> را برای override در هر راه‌اندازی ارسال کنید.

خط وضعیت

خط وضعیت TUI وضعیت عامل را به صورت بلادرنگ ردیابی می‌کند:

وضعیت	معنی
starting agent…	شناسه نشست زنده است؛ ابزارها و مهارت‌ها هنوز آنلاین می‌شوند. می‌توانید تایپ کنید — پیام‌ها در صف قرار می‌گیرند و هنگام آماده شدن ارسال می‌شوند.
ready	عامل بیکار است، ورودی می‌پذیرد.
thinking…/running…	عامل در حال استدلال یا اجرای یک ابزار است.
interrupted	نوبت فعلی لغو شد؛ دوباره Enter را فشار دهید تا ارسال شود.
forging session…/resuming…	اتصال اولیه یا handshake `--resume`.

رنگ‌ها و آستانه‌های خط وضعیت به ازای هر skin با CLI کلاسیک مشترک هستند — سفارشی‌سازی را در Skins ببینید.

Skins

خط وضعیت همچنین نمایش می‌دهد:

دایرکتوری کاری با شاخه git — ~/projects/hermes-agent (docs/two-week-gap-sweep). پسوند شاخه هنگامی که git checkout را در ترمینال جانبی اجرا می‌کنید (mtime-cached) به‌روز می‌شود تا TUI شاخه فعال واقعی شما را منعکس کند نه هر چیزی که در راه‌اندازی بود.
زمان سپری شده به ازای هر درخواست — ⏱ 12s/3m 45s در حین اجرای نوبت (زنده)، پس از تکمیل نوبت به ⏲ 32s / 3m 45s منجمد می‌شود. عدد اول زمان از آخرین پیام کاربر است؛ عدد دوم مدت کل نشست است. در هر درخواست جدید بازنشانی می‌شود.
🗜️ N — تعداد دفعاتی که نشست در حال اجرای خودکار فشرده شده است. پس از اولین فشرده‌سازی ظاهر می‌شود.
▶ N — تعداد وظایف /background در حال اجرای فعلی در این نشست. هنگامی که حداقل یک وظیفه در حال اجرا است ظاهر می‌شود.
⚠ YOLO — هشدار قابل مشاهده هنگامی که حالت YOLO فعال است (hermes --yolo، /yolo یا HERMES_YOLO_MODE=1). همان نشان نیز در بنر راه‌اندازی ظاهر می‌شود تا نتوانید یک نشست خودکار تأیید را بدون توجه راه‌اندازی کنید.

پیکربندی

TUI تمام پیکربندی استاندارد Hermes را رعایت می‌کند: ~/.hermes/config.yaml، پروفایل‌ها، شخصیت‌ها، اسکین‌ها، دستورات سریع، مجموعه اعتبارنامه‌ها، ارائه‌دهندگان حافظه، فعال‌سازی ابزار/مهارت. هیچ فایل پیکربندی مخصوص TUI وجود ندارد.

تعدادی کلید سطح TUI را به طور خاص تنظیم می‌کنند:

display:
  skin: default              # هر اسکین داخلی یا سفارشی
  personality: helpful
  details_mode: collapsed    # hidden | collapsed | expanded — پیش‌فرض آکاردئون سراسری
  sections:                  # اختیاری: override به ازای هر بخش (هر زیرمجموعه)
    thinking: expanded       # همیشه باز
    tools: expanded          # همیشه باز
    activity: collapsed      # مجدداً به پنل activity برگردید (پیش‌فرض: پنهان)
  mouse_tracking: all        # off | wheel | buttons | all (یا true/false برای سازگاری معکوس).
                             #   wheel   — 1000+1006 (اسکرول + کلیک؛ بدون کشیدن، بدون hover —
                             #             توصیه شده در داخل tmux برای ساکت کردن اسپم
                             #             "No image in clipboard" ردیف درخواست از رویدادهای hover)
                             #   buttons — 1002 برای انتخاب کشیدن سمت ترمینال اضافه می‌کند
                             #   all     — 1003 برای hover اضافه می‌کند (صفحه‌بندی اسکرول‌بار
                             #             با hover، link mouseenter و غیره)

تغییرات زمان اجرا:

/details [hidden|collapsed|expanded|cycle] — حالت سراسری را تنظیم کنید
/details <section> [hidden|collapsed|expanded|reset] — یک بخش را override کنید (بخش‌ها: thinking، tools، subagents، activity)

پیش‌فرض نمایان بودن

TUI با پیش‌فرض‌های نظری به ازای هر بخش ارائه می‌شود که نوبت را به جای دیواری از نشانگرها به عنوان رونوشت زنده پخش می‌کند:

thinking — باز. استدلال به صورت inline هنگامی که مدل آن را تولید می‌کند پخش می‌شود.
tools — باز. فراخوانی‌های ابزار و نتایج آن‌ها باز رندر می‌شوند.
subagents — به details_mode سراسری عبور می‌کند (پیش‌فرض: جمع‌شده زیر ▸ — تا زمانی که واگذاری واقعی رخ دهد ساکت می‌ماند).
activity — پنهان. فراداده محیطی (نکات gateway، nudge‌های تطابق ترمینال، اعلان‌های پس‌زمینه) برای اکثر استفاده‌های روزانه نویز است. خرابی‌های ابزار همچنان به صورت inline در ردیف ابزار خراب رندر می‌شوند؛ خطا/هشدارهای محیطی از طریق یک اعلان شناور وقتی همه پنل‌ها پنهان هستند نمایان می‌شوند.

override به ازای هر بخش بر هر دو پیش‌فرض بخش و details_mode سراسری اولویت دارد. برای بازسازی لایه‌بندی:

display.sections.thinking: collapsed — thinking را زیر ▸ برگردانید
display.sections.tools: collapsed — فراخوانی‌های ابزار را زیر ▸ برگردانید
display.sections.activity: collapsed — پنل activity را مجدداً فعال کنید
/details <section> <mode> در زمان اجرا

هر چیزی که به صورت صریح در display.sections تنظیم شود بر پیش‌فرض‌ها اولویت دارد، بنابراین تنظیمات موجود بدون تغییر کار می‌کنند.

نشست‌ها

نشست‌ها بین TUI و CLI کلاسیک مشترک هستند — هر دو در ~/.hermes/state.db می‌نویسند. می‌توانید یک نشست را در یکی شروع کنید و در دیگری ادامه دهید. انتخابگر نشست نشست‌ها را از هر دو منبع با یک برچسب منبع نمایش می‌دهد.

~/.hermes/state.db

چرخه حیات، جستجو، فشرده‌سازی و خروجی را در Sessions ببینید.

Sessions

نحوه ارتباط TUI با gateway

به طور پیش‌فرض TUI gateway درون‌پروسه خود را ایجاد می‌کند، بنابراین هر نمونه TUI مستقل است — چیزی برای پیکربندی وجود ندارد.

ممکن است متغیر محیطی HERMES_TUI_GATEWAY_URL را در پایگاه کد یا لاگ‌ها ببینید. این یک جزئیات سیم‌کشی داخلی رابط وب داشبورد است، نه یک دکمه اتصال از راه دور کاربرمحور. وقتی تب “Chat” داشبورد (hermes dashboard → /chat) را باز می‌کنید، سرور وب داشبورد یک فرآیند فرعی TUI تعبیه شده ایجاد می‌کند و HERMES_TUI_GATEWAY_URL را تزریق می‌کند تا آن فرآیند فرعی به tui_gateway درون‌پروسه خود داشبورد از طریق یک WebSocket حلقه‌ای (/api/ws) متصل شود. نقطه پایانی /api/ws فقط داخل سرور داشبورد (hermes_cli/web_server.py) وجود دارد و به طول عمر و احراز هویت آن فرآیند محدود شده است.

هیچ حالت عمومی “اشاره هر TUI به هر پورت standalone gateway” وجود ندارد. به طور خاص، سرور سازگار با OpenAI (hermes gateway / پلتفرم api_server) /api/ws را سرویس نمی‌دهد — این سطح backend مدل (/v1/chat/completions، /v1/models و غیره) است و عمداً کانال کنترل JSON-RPC TUI را افشا نمی‌کند. تنظیم HERMES_TUI_GATEWAY_URL به آن پورت 404 خواهد داد.

اگر می‌خواهید چندین سطح یک مجموعه نشست را به اشتراک بگذارند، از ~/.hermes/state.db مشترک ( Sessions را ببینید) یا چت تعبیه شده رابط وب داشبورد (Web Dashboard را ببینید) استفاده کنید — نه یک URL gateway دستی تنظیم شده.

~/.hermes/state.db Sessions Web Dashboard

بازگشت به CLI کلاسیک

راه‌اندازی hermes (بدون --tui) به طور پیش‌فرض در CLI کلاسیک باقی می‌ماند. برای ترجیح TUI در یک ماشین، display.interface: tui را در ~/.hermes/config.yaml (پایدار) یا HERMES_TUI=1 در پروفایل shell خود (به ازای هر shell) تنظیم کنید. برای بازگشت، interface: cli را تنظیم کنید / متغیر محیطی را unset کنید، یا hermes --cli را برای یک بار ارسال کنید.

اگر TUI موفق به راه‌اندازی نشود (بدون Node، بسته گمشده، مشکل TTY)، Hermes یک تشخیص چاپ می‌کند و بازمی‌گردد — به جای اینکه شما را گیر بیندازد.

همچنین ببینید

رابط CLI — مرجع کامل دستورات اسلش و میانبرهای صفحه‌کلید (مشترک)
Sessions — بازیابی، شاخه و تاریخچه
Skins & Themes — موضوع بنر، خط وضعیت و پوشش‌ها
Voice Mode — در هر دو رابط کار می‌کند
Configuration — تمام کلیدهای پیکربندی

رابط CLI Sessions Skins & Themes Voice Mode Configuration ویرایش این صفحه