گسترش bea ask با مهارتها

یک فایل SKILL.md در کنار دفتر کل خود قرار دهید و bea ask از قراردادهای دفترداری خودتان پیروی میکند — نامهای دستهبندی شما، چیدمان گزارش شما، قواعد خانه شما — بدون اینکه آنها را در هر سؤال تکرار کنید.

یک skill یک فایل Markdown ساده با یک هدر کوچک YAML است. bea ask آن را هنگام راهاندازی پیدا میکند و به دستیار میزبان ارائه میدهد، که متن کامل را زمانی که سؤالی به آن نیاز داشته باشد بارگذاری میکند.

این صفحه فرض میکند که bea ask قبلاً برای شما کار میکند. به این ویژگی ask اضافی نیاز دارد (uv tool install 'beancount-io[ask]') و اعتبارنامههای Beancount.io از bea cloud login یا BEA_TOKEN. پرسوجوها بر روی دفترچه محلی شما اجرا میشوند، اما سؤال و زمینه مهارت به سرویس هوش مصنوعی میزبان Beancount.io ارسال میشوند. bea ask هیچ خروجی JSON ندارد. برای قرارداد کامل دستور به مرجع CLI مراجعه کنید.

مهارت کجا قرار میگیرد​

bea ask دو دایرکتوری را به ترتیب زیر میخواند:

دایرکتوری پروژه از دایرکتوری کاری که bea ask در آن اجرا میکنید تعیین میشود، نه از --file. وقتی هر دو دایرکتوری دارای یک مهارت با نام یکسان باشند، نسخه پروژه برنده میشود و نسخه کاربر نادیده گرفته میشود.

BEA_CONFIG_DIR دایرکتوری سطح کاربر را جابهجا میکند: با تنظیم آن، مهارتها از $BEA_CONFIG_DIR/skills/ خوانده میشوند. در غیر این صورت $XDG_CONFIG_HOME/bea/skills/ اعمال میشود، و در نهایت به ~/.config/bea/skills/ برمیگردد.

فایل مهارت را بنویسید​

برای هر مهارت یک دایرکتوری، که حاوی یک فایل به نام SKILL.md باشد:

.agents/skills/
└── monthly-report/
    └── SKILL.md

فایل یک هدر YAML است و سپس دستورالعملهای شما:

---
name: monthly-report
description: Generates monthly expense summaries grouped by category.
---
 
When the user asks for a spending summary or monthly report:
1. Group all expenses by the top-level account category.
2. Show totals for each category, sorted highest to lowest.
3. Include a grand total at the end.
4. Always specify the currency next to each amount.

دو فیلد الزامی است. فایلی که هرکدام را نداشته باشد بیصدا رد میشود، بنابراین یک مهارت غایب معمولاً مشکل هدر است.

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

allowed-tools محدودیت مجوز نیست. bea نسخه 0.1.0 این فیلد را تجزیه میکند و هیچ چیز دیگری آن را نمیخواند، بنابراین هیچ چیزی را محدود نمیکند. آن را به عنوان مستندسازی قصد رفتار کنید. کنترلها که واقعاً مؤثر هستند همانهایی هستند که خود فرمان هسته: نوشتنهای تعاملی قبل از دست زدن به فایل، پیشنمایش، تأیید و اعتبارسنجی میشوند، --yes سراسری به نوشتن مجوز بیان میدهد، و حالت --print هرگز یک نوشتن پیشنهادی را اعمال نمیکند.

بررسی اینکه بارگذاری شده است​

یک مهارت یکبارمصرف با دستورالعملی بسازید که از دست ندهید، سپس هر چیزی را بپرسید.

مهارت را ایجاد کنید:

mkdir -p .agents/skills/test-skill
cat > .agents/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Test skill to verify skill loading works.
---
 
IMPORTANT: Whenever the user asks any question, start your response with the exact phrase "SKILL LOADED".
EOF

یک سؤال در حالت تکآیتم پاسخ بپرسید:

bea ask "what accounts do I have?" --print

پاسخی که با SKILL LOADED شروع میشود به این معنی است که مهارت شناسایی شده و به دستیار ارائه شده است.

سپس ثابت کنید که عبارت از مهارت آمده است، با جابجا کردن دایرکتوری خارج از در میر مهارتها و دوباره پرسیدن:

mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skill

عبارت باید حذف میشود. دایرکتوری را از .agents/skills/ جابهجا کنید، نه اینکه در محل تغییر نام دهید: شناسایی بر اساس فیلد name در هدر انجام میشود، بنابراین دایرکتوری که به test-skill.bak تغییر نام داده میشود همچنان پیدا شده و بارگذاری میشود.

برای بررسی مهارت سطح کاربر، همان فایل را در ~/.config/bea/skills/test-skill/SKILL.md قرار دهید و تکرار کنید. برای بررسی اولویت، هر دو نسخه را با name یکسان و عبارات متفاوت نگه دارید: عبارت جمله پروژه را باید ببینید.

مهارت آزمایشی را وقتی تمام شد پاک کنید. این مهارت بر عبارتهایی که از آن دایرکتوری میپرسید اعمال میشود.

مهارتهای برای bea ask با مهارتهای عامل شما یکسان نیست​

این مهارتها فقط دستیار داخلی bea ask را گسترش میدهند. آنها از مهارتهای اصلی Beancount.io که در یک عامل کدنویس خارجی مانند Codex نصب میکنید، متفاوت هستند، که دستورات bea را از بیرون هدایت میکنند. اگر به دنبال همین هستید، به جای آن حسابگری با عوامل هوش مصنوعی را بخوانید — جایی که دستورالعملهای عامل خارجی به طور کامل پوشش داده شدهاند، و هیچ یک از آنها به ask اضافی یا حساب میزبان نیاز ندارند.