Tool Card

فراخوانی یک ابزار و نتیجه‌اش را از روی نیتی اعلام‌شده رندر می‌کند، نه از روی نشانه‌گذاری.

کجا به کارش ببرید: وقتی نشان می‌دهید یک عامل یا یک کار واقعاً چه کرده است (فرمان شل، ویرایش فایل، یک جست‌وجو) و می‌خواهید ابزار فقط بگوید چه چیزی است و ظاهرش را سطح نمایش تعیین کند.

ابزاری که HTML برمی‌گرداند، به‌جای رابط کاربری، رندرکننده و پوسته و چیدمان را انتخاب کرده است — آن هم در تنها جایی (نتیجه‌ای که مدل می‌بیند) که دغدغه‌های رابط کاربری در آن جایی ندارند. اعلام نیت این دو را جدا نگه می‌دارد: همان فراخوانی می‌تواند اینجا بلوک ترمینال باشد، در یک رونوشت فشرده یک سطر، و در یک ویرایشگر مقصدِ پرش — بی‌آنکه ابزار از وجود هیچ‌کدام خبر داشته باشد.

شروع سریع

<r-tool-card open></r-tool-card>

const card = document.createElement('r-tool-card');

card.call = { card: 'terminal', title: 'pnpm test', cwd: '/repo' };
card.status = 'running';

// …وقتی فراخوانی برگشت
card.result = { card: 'terminal', output: '2351 passed', exitCode: 0 };
card.status = 'success';

conversation.append(card);

گونه‌های کارت

generic

هم پیش‌فرض است هم گزینهٔ پشتیبان. عنوان، جدول اختیاری کلید/مقدارِ آرگومان‌هایی که ارزش نشان‌دادن دارند، و محتوای نتیجهٔ اختیاری.

card.call = { card: 'generic', title: 'Read file', input: { path: 'src/a.ts', limit: '200' } };
card.result = { card: 'generic', content: 'export const a = 1;' };

terminal

خودِ فراخوانی یک فرمان شل است. title همان فرمان است و description و cwd بالای خروجی رندر می‌شوند. exitCodeِ ناصفر نمایش داده می‌شود، صفر نه.

card.call = { card: 'terminal', title: 'ls -la', description: 'List the tree', cwd: '/repo' };
card.result = { card: 'terminal', output: 'total 8\ndrwxr-xr-x …', exitCode: 0 };

diff

فراخوانی فایل می‌سازد یا تغییر می‌دهد. هر مدخل به‌شکل تکه‌های سبک unified با هر دو حاشیه رندر می‌شود که diffLines از ranuts/utils حسابشان می‌کند. oldTextِ تهی یعنی فایل در حال ساخته‌شدن است، و همین چیزی است که نمای زمان فراخوانی در اختیار دارد، چون فراخواننده محتوای پیشینی برای خواندن ندارد.

card.call = {
  card: 'diff',
  title: 'Edit config',
  diffs: [{ path: 'vite.config.ts', oldText: 'port: 3000\n', newText: 'port: 5173\n' }],
};

دو قاعده‌ای که گاز می‌گیرند

این نماها هم روی یک فراخوانی زنده حساب می‌شوند و هم دوباره وقتی یک گزارش بازپخش می‌شود. باقی همه‌چیز از همین برمی‌آید.

• هر نما تابعی ناب از آرگومان‌های فراخوانی است (و برای نمای نتیجه، به‌علاوهٔ خود نتیجه). نه I/O، نه ساعت، نه وضعیت نشست؛ وگرنه بازپخش با آنچه کاربر در ابتدا دید جور درنمی‌آید.
• کارت ناشناخته افت می‌کند، هرگز استثنا نمی‌اندازد. گونهٔ کارتی از یک تولیدکنندهٔ تازه‌تر، یا مقداری که در ذخیره‌سازی مخدوش شده، با هر عنوانی که دارد به‌شکل generic رندر می‌شود و نمای بدشکل خالی رندر می‌شود. نمایش نباید بتواند بازپخش را بشکند.

مکان‌ها

هر locations روی یک فراخوانی به‌شکل دکمه رندر می‌شود که رویداد locationclick می‌فرستد، تا یک ویرایشگر بتواند همراهی کند:

card.call = { card: 'generic', title: 'Read', locations: [{ path: 'src/a.ts', line: 42 }] };
card.addEventListener('locationclick', (e) => openInEditor(e.detail.location));

مرجع API

خصیصه‌ها

خصیصه	نوع	پیش‌فرض	توضیح
call	ToolCallView | null	null	نمای در جریان، برگرفته از آرگومان‌های فراخوانی.
result	ToolResultView | null	null	نمای تکمیل‌شده. جای نمای در جریان را می‌گیرد.
status	'running' | 'success' | 'error'	'running'	بازتاب می‌یابد، پس استایل می‌تواند به آن تکیه کند.
open	boolean	false	اینکه بدنه باز است یا نه.
sheet	string	''	CSS تزریق‌شده به shadow DOM عنصر.

مقدار ناشناختهٔ status هنگام خواندن running برمی‌گردد.

رویدادها

رویداد	Detail	چه زمانی
locationclick	{ location: ToolLocation }	ارجاعی به یک فایل فعال شود.

Part‌ها

card، header، status، title، toggle، body، description، exit، input، output، file، path، hunk، line، locations، location.

سطرهای diff مقدار data-kind برابر context، added یا removed دارند.

دسترس‌پذیری

سربرگ یک <button type="button"> واقعی با aria-expanded است، پس بدون سیم‌کشی اضافه با صفحه‌کلید در دسترس و قابل استفاده است.

استایل

<r-tool-card> ۲۴ ویژگی سفارشی CSS از آنِ خود و افزون بر آن توکن‌های معنایی‌ای که از پوسته می‌خواند در اختیار می‌گذارد. آن را هرجا که ارث می‌رسد تعیین کنید: :root، یک نگه‌دارنده، یا خود عنصر.

r-tool-card {
  --ran-tool-card-io-background: var(--ran-color-bg-subtle);
}

Part‌ها: body · exit · file · hunk · io · io-text · line · location · locations · path · row

فهرست کامل در توکن‌های استایل است و اینکه کدام توکن را برگزینید در سیستم طراحی آمده.

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

• Conversation: این را به‌عنوان مقصد mount برای نمای یک فراخوانی ابزار به کار ببرید
• ranuts/utils: تابع diffLines که کارت diff را می‌کشد