ابزارهای توسعهدهندگان شخص ثالث، به کدنویسان این امکان را میدهند که فراتر از DOM، درخواستهای شبکه و گزارشهای کنسول را ببینند. با نمایش ابزارهای سفارشی مستقیماً از وبسایت یا فریمورک خود، به کدنویس خود اجازه میدهید تا با وضعیت و دادههای برنامه که در غیر این صورت غیرقابل دسترسی بودند، تعامل داشته باشد.
این ابزارها از طریق جاوا اسکریپت ایجاد میشوند و هنگام بارگذاری صفحه شما، بهطور خودکار توسط Chrome DevTools برای عوامل شناسایی میشوند.
ابزارهای توسعهدهندگان شخص ثالث را بشناسید
در زمینهی عاملهای کدنویسی، ابزارها توابع آمادهای هستند که عاملها میتوانند با استفاده از آنها اقدامات خاصی را انجام دهند. بهطور خاص، در DevTools برای عاملها، چنین ابزارهایی میتوانند وضعیت زمان اجرای داخلی خود را مستقیماً در اختیار عاملهای کدنویسی قرار دهند و شکاف بین خروجی رندر شده و منطق داخلی را پر کنند.
هنگام استفاده از ابزارهای شخص ثالث، موارد زیر را در نظر داشته باشید:
- کشف زمان اجرا. ابزارها به طور خودکار زمانی شناسایی میشوند که برنامه شما به رویداد
devtoolstooldiscoveryکه توسط Chrome DevTools برای عاملهای روی شیء سراسریwindowمنتشر میشود، پاسخ میدهد. - دامنه متن. ابزارها فقط در چارچوب صفحهای که آنها را تعریف میکند اجرا میشوند. آنها در مبداها و بارگذاری مجدد صفحه باقی نمیمانند.
- ویژگی ابزار . ابزارها فقط یک راه اضافی برای عامل شما برای انجام یک کار هستند. ممکن است ابزارهای داخلی یا قابلیتهای مدل ساده را برای انجام یک درخواست ترجیح دهد. بنابراین نامها و توضیحات ابزارها را تا حد امکان توصیفی بنویسید.
پیشنیازها
قبل از پیادهسازی ابزارهای شخص ثالث، مطمئن شوید که شرایط زیر را برآورده میکنید:
- ابزارهای توسعه کروم برای عاملها. از نسخه ۰.۲۵.۰ یا بالاتر استفاده کنید.
- جاوا اسکریپت را فعال کنید. جاوا اسکریپت را فعال و اجرا کنید.
پیادهسازی یک ابزار
برای پیادهسازی یک ابزار، شما به یک رویداد اکتشافی خاص گوش میدهید و با تعاریف ابزار خود پاسخ میدهید. کد زیر نشان دهنده پاسخی است که شامل تعاریف ابزار است:
window.addEventListener(
'devtoolstooldiscovery',
(event: DevtoolsToolDiscoveryEvent) => {
event.respondWith({
name: 'Page-specific DevTools',
description: 'Provide runtime info directly from the JavaScript in the page.',
tools: [
{
name: 'add',
description: 'Calculates the sum of two numbers.',
inputSchema: {
type: 'object',
properties: {
a: {type: 'number'},
b: {type: 'number'},
},
required: ['a', 'b'],
},
execute: async (input: {a: number; b: number}) => {
return input.a + input.b;
},
},
],
});
},
);
برای ثبت ابزارها در برنامه خود:
گروه ابزار خود را تعریف کنید. یک
ToolGroupایجاد کنید که شامل نام، توضیحات و آرایهای از تعاریف ابزارهای مجزا باشد.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }منتظر رویداد کشف باشید. Chrome DevTools برای عاملها، پس از هر پیمایش و هر زمان که به لیست بهروزرسانیشدهای از ابزارهای موجود نیاز داشته باشد، یک رویداد سفارشی
devtoolstooldiscoveryرا روی شیءwindowسراسری ارسال میکند.ابزارهای خود را ثبت کنید. متد
respondWith()رویداد را فراخوانی کنید تا گروه ابزار خود را در اختیار عامل قرار دهید.
اجزای ضروری برای ابزارهای تکی
هر تعریف ابزاری که پیادهسازی میکنید باید شامل سه بخش زیر باشد:
- نام و توضیحات. اینها دستورالعملهایی را ارائه میدهند که عامل برای تصمیمگیری در مورد زمان و نحوه فراخوانی ابزار شما از آنها استفاده میکند.
- طرح ورودی. یک طرح JSON که ساختار و انواع آرگومانهای مورد انتظار ابزار را تعریف میکند.
- تابع اجرا. کد جاوا اسکریپت واقعی که هنگام فراخوانی ابزار توسط عامل، روی صفحه اجرا میشود.
مثال زیر این سه جزء را در یک تعریف ابزار واحد نشان میدهد:
{
name: 'add',
description: 'Calculates the sum of two numbers.',
inputSchema: {
type: 'object',
properties: {
a: {type: 'number'},
b: {type: 'number'},
},
required: ['a', 'b'],
},
execute: async (input) => {
return input.a + input.b;
},
}
موارد استفاده از ابزارهای توسعهدهندگان شخص ثالث
به عامل خود دستور دهید که منطق عمیق برنامه را بررسی کند، نه فقط عناصر رابط کاربری سطحی. از این ابزارهای سفارشی برای سادهسازی اشکالزدایی برنامههای دارای وضعیت یا برنامههای سنگین مبتنی بر چارچوب استفاده کنید.
نکاتی برای کشف ابزار
نامها و توضیحات توصیفی برای ابزارها بنویسید. عاملها از این توضیحات به عنوان زمینهای برای تصمیمگیری در مورد اینکه از کدام ابزار استفاده کنند، استفاده میکنند. زبان واضح به عامل کمک میکند تا به طور مستقل تشخیص دهد که چه زمانی یک ابزار برای یک کار مناسب است.
اشکالزدایی معیارهای زمان اجرا مختص برنامه
مسائلی مانند خطاهای پنهان حافظه پنهان یا فراخوانیهای تکراری API اغلب برای بازرسی استاندارد قابل مشاهده نیستند. با افشای آمار داخلی، نماینده شما میتواند توضیح دهد که چرا یک رفتار خاص رخ داده است.
فرض کنید تابعی دارید که آمار داخلی را نمایش میدهد؛ ابتدا باید ابزاری مانند این ایجاد کنید:
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: 'My app',
description: 'Tools to debug my app',
tools: [
{
name: 'getCacheStatistics',
description: 'Exposes runtime cache hits and misses for the frontend API service.',
inputSchema: {},
execute: async () => {
// Assuming window.__apiCacheService exists in your app
return window.__apiCacheService.getStats();
}
}
]
});
});
اگر توضیحات ابزار شما واضح باشد، عامل شما میتواند در صورت لزوم از ابزار به صورت خودکار استفاده کند. میتوانید به عامل خود دستور دهید تا با استفاده از ابزار، کاری را مانند موارد زیر انجام دهد:
When I reassign a lead to a new sales rep, the dashboard takes a second to
update. Please verify if the frontend is correctly updating the local cache,
or if it is doing a full cache miss and refetching the entire pipeline from the
database.
اجرای نمونهای از عامل: عامل شما ابزار getCacheStatistics را که توسط برنامه شما در دسترس قرار گرفته است، تشخیص میدهد. این ابزار را فراخوانی میکند، نسبت موفقیت به شکست بازگشتی را تجزیه و تحلیل میکند و تشخیص میدهد که رابط کاربری به جای بهروزرسانی حافظه پنهان محلی، کل خط لوله را به طور غیرضروری بازیابی میکند.
بررسی پرچمهای ویژگی
نقاط داده سفارشی را برای نمایش متغیرهای محیطی فعلی یا پرچمهای ویژگی فعال برای یک جلسه کاربری خاص تعریف کنید. این به شما کمک میکند تا بفهمید چرا ویژگیهای خاصی برای کاربران خاص قابل مشاهده هستند یا نیستند. اگر کاربری اشکالی را گزارش کند، عامل میتواند تأیید کند که آیا او در یک گروه آزمایشی قرار دارد که ممکن است باعث ایجاد مشکل شود یا خیر.
برای مثال، ابزاری مانند این ایجاد کنید تا وضعیت پرچم ویژگی داخلی را برگرداند:
// Implementation for a website creator to expose feature flags
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: 'Application Configuration Tools',
description: 'Tools for inspecting runtime environment and feature toggles',
tools: [
{
name: 'getFeatureFlags',
description: 'Returns a list of all active feature flags and their current values for the session.',
inputSchema: {
type: 'object',
properties: {} // No input parameters required for this tool
},
execute: async () => {
// This should return your internal feature flag state
// Example: return window.AppConfig.getFlags();
return {
"new-ui-enabled": true,
"beta-search-v2": false,
"experiment-group": 'control',
"log-level": 'debug'
};
}
}
]
});
});
اگر توضیحات ابزار شما واضح باشد، عامل شما میتواند در صورت لزوم از ابزار به صورت خودکار استفاده کند. میتوانید به عامل خود دستور دهید تا با استفاده از ابزار، کاری را مانند موارد زیر انجام دهد:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
اجرای نمونهای از عامل : عامل شما ابزار getFeatureFlags فراخوانی میکند، تأیید میکند که پرچم new-ui-enabled فعال است و به اشکالزدایی اجزای مرتبط با رابط جدید ادامه میدهد.
بررسی وضعیت سراسری برنامه
درخت وضعیت زمان اجرای برنامه خود را نمایش دهید تا به عامل شما کمک کند منطق داخلی را بدون واکشی کل DOM درک کند.
شما میتوانید ابزاری مانند این ایجاد کنید تا مسیرهای خاصی را در درخت وضعیت خود جستجو کنید، مانند آنچه در زیر آمده است:
// Library-agnostic implementation for inspecting global application state
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: "Global State Inspector",
description: 'Tools to inspect the runtime state tree of the application',
tools: [
{
name: 'getGlobalState',
description: "Returns the current application state. Use the 'path' parameter to drill down into specific sections (for example, 'auth.user' or 'cart.items'). ",
inputSchema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'Optional dot-notation path to a specific property in the state tree.'
}
}
},
execute: async (input) => {
// Library-agnostic access:
// Website creators can point this to whatever global store they use.
const state = window.__APP_STATE__ ||
(window.store && typeof window.store.getState === 'function' ? window.store.getState() : null);
if (!state) {
return { error: 'Application state is not accessible via window.__APP_STATE__ or window.store.' };
}
if (!input.path) {
return state;
}
// Helper to resolve a dot-notated path against the state object
return input.path.split('.').reduce((acc, part) => {
return acc && acc[part] !== undefined ? acc[part] : undefined;
}, state);
}
}
]
});
});
اگر توضیحات ابزار شما واضح باشد، عامل شما میتواند در صورت لزوم از ابزار به صورت خودکار استفاده کند. میتوانید به عامل خود دستور دهید تا با استفاده از ابزار، کاری را مانند موارد زیر انجام دهد:
The number of items in my cart is not updating. Inspect the global state at the
path cart.items and list the current items and their quantities, see if they are
the same.
مثال اجرای عامل : عامل شما getGlobalState را با پارامتر path فراخوانی میکند. این تابع لیست اقلام را از سبد خرید بازیابی میکند و اختلاف بین وضعیت داخلی و اقلام رندر شده در صفحه را شناسایی میکند.
چند نکته مهم در مورد این مثال ابزار:
- منطق جدا شده : عامل هوش مصنوعی درخواست "وضعیت" میکند. شما، به عنوان توسعهدهنده، تصمیم میگیرید که چگونه آن درخواست را به ساختار داده واقعی خود در تابع
executeنگاشت کنید. - اشکالزدایی هدفمند : با گنجاندن پارامتر
path، عامل میتواند از استخراج کل درخت حالت (که ممکن است بسیار بزرگ باشد) اجتناب کند و فقط روی بخش مربوطه تمرکز کند، توکنها را ذخیره کند و عملکرد را بهبود بخشد. - رابط استاندارد : حتی اگر کتابخانههای مدیریت حالت را تغییر دهید، تا زمانی که این تابع
executeرا بهروزرسانی کنید، عامل اشکالزدایی هوش مصنوعی شما به هیچ دستورالعمل یا ابزار جدیدی نیاز نخواهد داشت.
بررسی محتوای پایگاه داده
با پرس و جو مستقیم از رکوردهای پایگاه داده از طریق یک نقطه پایانی اشکال زدایی فقط خواندنی، تأیید کنید که دادههای backend شما با وضعیت UI مطابقت دارند.
یک نقطه پایانی اشکالزدایی ایمن را در معرض نمایش قرار دهید و ابزاری مانند این را برای تأیید رکوردهای backend ایجاد کنید:
// Framework-agnostic implementation for inspecting database content
window.addEventListener('devtoolstooldiscovery', (event) => {
event.respondWith({
name: 'Database Inspection Tools',
description: 'Tools to query backend database records using existing browser session',
tools: [
{
name: 'queryDatabaseTable',
description: 'Retrieves a limited set of records from a specific table. Useful for verifying that backend data matches the UI state.',
inputSchema: {
type: 'object',
properties: {
tableName: {
type: 'string',
description: 'The name of the database table to inspect.'
},
limit: {
type: 'number',
default: 5,
description: 'Maximum number of rows to return.'
}
},
required: ['tableName']
},
execute: async (input) => {
// This calls a generic debug endpoint you've set up on your server.
// It's framework-agnostic because it just expects a JSON response.
try {
const response = await fetch(`/api/debug/db-inspect?table=${input.tableName}&limit=${input.limit}`);
if (!response.ok) {
return { error: `Backend returned ${response.status}: ${response.statusText}` };
}
return await response.json();
} catch (error) {
return { error: `Failed to connect to debug endpoint: ${error.message}` };
}
}
}
]
});
});
اگر توضیحات ابزار شما واضح باشد، عامل شما میتواند در صورت لزوم از ابزار به صورت خودکار استفاده کند. میتوانید به عامل خود دستور دهید تا با استفاده از ابزار، کاری را مانند موارد زیر انجام دهد:
The total price on the checkout page seems wrong. Query the orders table for my
last order to verify the subtotal and tax values and see what may be causing the
problem, if any.
مثال اجرای عامل : عامل شما queryDatabaseTable را برای جدول سفارشات فراخوانی میکند. این تابع رکورد JSON را بازیابی میکند، خطایی را در محاسبه مالیات backend شناسایی میکند و راهحلی برای منطق سرور پیشنهاد میدهد.
چند نکته مهم در مورد این مثال ابزار:
- امنیت و احراز هویت : نیازی به ارسال اطلاعات پایگاه داده به عامل هوش مصنوعی نیست. فراخوانی
fetchاز جلسه ورود فعلی مرورگر برای تأیید درخواست در backend شما استفاده میکند. - اشکالزدایی عملی : اگر یک عامل هوش مصنوعی یک اشکال در رابط کاربری را شناسایی کند، میتواند بلافاصله
queryDatabaseTableرا فراخوانی کند تا ببیند آیا خطا در دادههای منبع یا محاسبات frontend وجود دارد یا خیر. - راهاندازی حداقلی : شما فقط باید یک نقطه پایانی اشکالزدایی «امن» (فقط خواندنی) روی سرور خود قرار دهید که نام جدول را بپذیرد و JSON را برگرداند. چارچوبی که برای ساخت آن نقطه پایانی استفاده میکنید مهم نیست.