پرسونا و لحن گفتمان

هر قالب می‌تواند هویت گفتاری و نوشتاری دستیار خود را تعریف کند: نام نمایشی، نقش، زبان و در صورت فعال بودن کانال، ویژگی‌های صوتی. این مقادیر توکن هستند، نه منطق: شکل بیان را تعیین می‌کنند و هرگز قصد، سیاست، مجوز یا پاسخ امنیتی را تغییر نمی‌دهند.

قرارداد در @tokapps/tokens/personaکپی کد است (بدون اثر جانبی، امن برای SSR و سرور ایجنت). هر قالب فایل theme/persona.tsکپی کد دارد و با definePersonaکپی کد تعریف می‌شود.

۱. پلی‌گراند

یک preset را انتخاب کنید؛ نمونهٔ پاسخ، مقادیر resolve شده و کد قابل‌کپی همراه با انتخاب شما تغییر می‌کنند.

import { definePersona } from '@tokapps/tokens/persona';export const persona = definePersona({  version: 1,  id: 'persona.playground',  preset: 'warm-supportive',  displayName: { fa: 'راهنما' },  role: 'assistant',  domain: 'general',});

۲. توکن‌های لحن

زبان (languageکپی کد): primaryکپی کد (faکپی کد · enکپی کد)، numeralsکپی کد (faکپی کد · latinکپی کد)، latinTermsکپی کد (keepکپی کد · translateکپی کد).

۳. presetهای استاندارد

presetها غیرقابل تغییرند؛ قالب فقط نام آن‌ها را می‌برد و override مجاز اعمال می‌کند.

۴. قیود ثابت

این قیدها در هر قالب و هر preset اعمال می‌شوند و قابل بازنویسی نیستند:

• افشای هوش مصنوعی: دستیار خود را انسان معرفی نمی‌کند.
• دامنه‌های حساس (healthکپی کد، financeکپی کد، legalکپی کد، crisisکپی کد): طنز و اموجی روی noneکپی کد قفل می‌شوند.
• صدا: پخش خودکار خاموش است، کاربر همیشه می‌تواند میان پاسخ صحبت کند، هر پاسخ صوتی متن معادل دارد و مارک‌داون یا URL خوانده نمی‌شود.
• کلیدهای ممنوع: جنسیت، سن، قومیت، لهجه و aiDisclosureکپی کد در پرسونا نمی‌آیند. voiceRefکپی کد نام معنایی است، نه شناسهٔ سرویس صدا.

۵. ترتیب اعمال

از کم‌اولویت به پراولویت: هستهٔ پیش‌فرض، preset، قالب، پیکربندی محصول، ترجیح ذخیره‌شدهٔ کاربر، درخواست همان گفتگو، و در آخر قیدهای ثابت. درخواستی مثل «کوتاه‌تر بگو» فقط برای همان گفتگو اعمال می‌شود و ذخیره نمی‌شود.

۶. تعریف در قالب

// theme/persona.tsimport { definePersona } from '@tokapps/tokens/persona';export const persona = definePersona({  version: 1,  id: 'persona.support-guide',  preset: 'warm-supportive',  displayName: { fa: 'راهنما' },  role: 'support',  domain: 'support',  tone: { verbosity: 'standard' },  language: { primary: 'fa', numerals: 'fa', latinTerms: 'keep' },});

دستیار صوتی همان قالب با یک بلوک voiceکپی کد (فقط voiceRefکپی کد الزامی است):

export const voicePersona = definePersona({  version: 1,  id: 'persona.voice-guide',  preset: 'voice-calm-guide',  displayName: { fa: 'راهنمای صوتی' },  role: 'guide',  domain: 'education',  voice: { voiceRef: 'voice.calm-guide', maxSentences: 2 },});

۷. استفاده در زمان اجرا

import { resolvePersona } from '@tokapps/tokens/persona';import { persona } from './theme/persona';const active = resolvePersona(persona, {  product: { voiceEnabled: true },  user: { voiceMuted: false },});// active.tone، active.voice و active.diagnostics را مصرف کنید

تعریف نامعتبر در زمان اجرا پرتاب نمی‌کند؛ به پیش‌فرض امن neutral-professionalکپی کد برمی‌گردد و خطاها در diagnosticsکپی کد دیده می‌شوند.

۸. ایجنت‌ها

ابزار get_persona_presetsکپی کد در سرور MCP همین presetها، قیود و نمونهٔ کد را برمی‌گرداند. گیت validate_agent_outputکپی کد قاعدهٔ persona-tone-contractکپی کد را اجرا می‌کند: کلیدهای ممنوع، نقض قیود صوتی، شناسهٔ سرویس صدا و طنز در دامنهٔ حساس را رد می‌کند.

۹. پرسش از کاربر در پروژهٔ جدید

در پروژهٔ جدید، ایجنت پیش از نوشتن theme/persona.tsکپی کد باید این موارد را از توسعه‌دهنده بپرسد و پاسخ را دقیقاً به مقادیر قرارداد نگاشت کند:

1. preset: یکی از نه preset فهرست get_persona_presetsکپی کد.
2. دامنه (domainکپی کد): generalکپی کد، educationکپی کد، communityکپی کد، supportکپی کد، healthکپی کد، financeکپی کد، legalکپی کد یا crisisکپی کد. دامنه‌های حساس طنز و اموجی ندارند.
3. نام نمایشی فارسی و نقش (roleکپی کد): assistantکپی کد، guideکپی کد، supportکپی کد یا narratorکپی کد.
4. زبان و اعداد: primaryکپی کد، numeralsکپی کد (faکپی کد یا latinکپی کد) و latinTermsکپی کد.
5. خطاب و لحن: addressکپی کد، warmthکپی کد، humorکپی کد و emojiکپی کد در محدودهٔ مجاز همان preset.
6. صدا: فعال بودن کانال صوتی و voiceRefکپی کد معنایی (مثل voice.calm-guideکپی کد).
7. رفتار گفتاری (توسعه‌دهنده تعیین می‌کند؛ در theme/persona.tsکپی کد ثابت می‌شود): سقف اموجی (emojiMaxکپی کد)، میزان تملق (sycophancyکپی کد: forbiddenکپی کد، acknowledge-onlyکپی کد یا allowedکپی کد)، فهرست واژگان ممنوع (forbiddenTermsکپی کد)، سقف کلمه در هر نوبت (maxWordsPerTurnکپی کد، ۴۰ تا ۶۰۰) و سقف پرسش در هر نوبت (maxQuestionsPerTurnکپی کد، ۱ تا ۳). در دامنه‌های حساس اموجی ۰ و تملق forbiddenکپی کد است.

بدون پاسخ کاربر پرسونا ساخته نمی‌شود. اگر کاربر دربارهٔ موردی نظری نداد، پیش‌فرض را پیشنهاد بده و تأیید بگیر.

۱۰. قفل در AGENTS.md پروژهٔ مقصد

پس از ثبت پاسخ‌ها، ابزار render_persona_agents_mdکپی کد بلوک «پرسونای پروژه (قفل‌شده)» را می‌سازد و بین نشانگرهای tds-personaکپی کد در AGENTS.mdکپی کد پروژه می‌نویسد. این بلوک شناسه، preset، لحن، زبان، صدا و رفتار گفتاری را دقیق نقل می‌کند. ایجنت رابط کاربری پیش از طراحی آن را می‌خواند و همان لحن و خطاب را در متن‌های رابط به کار می‌برد. با تغییر theme/persona.tsکپی کد بلوک بازتولید می‌شود و بقیهٔ AGENTS.mdکپی کد دست‌نخورده می‌ماند.

۱۱. چیدمان پویا (Generative UI)

ایجنت پروژهٔ مقصد قواعد چیدمان را از render_layout_agents_mdکپی کد می‌گیرد و در AGENTS.mdکپی کد خود می‌نویسد. ترتیب چهار اسلات ثابت است: خلاصه، ویجت اصلی، پاورقی و اقدام‌ها. تصمیم In-line، Side-Panel یا Full Canvas بر اساس اندازهٔ داده و viewport گرفته می‌شود و دلیلش ثبت می‌شود. پیش از نمایش هر خروجی کامپوننتی، ابزار validate_generative_layoutکپی کد ترتیب، حدود، چیدمان و دلیل را بررسی می‌کند.