حسابداری با عوامل هوش مصنوعی

دو وظیفه دفترداری را به یک عامل هوش مصنوعی خارجی بسپارید و هر تغییر دفتر کل را تحت بررسی خود نگه دارید: وارد کردن CSV بانکی با بررسیِ اولیه پیش‌نمایش، سپس پاسخ به سوال مانده از خروجی پرس‌وجو و گزارش.

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

عامل چه می‌کند و bea چه می‌کند​

عامل دسته‌بندی‌ها را پیشنهاد می‌دهد و پرس‌وجوها را پیش‌نویس می‌کند. Bea ساختار دفتر کل را اعتبارسنجی می‌کند و مجموع‌ها را محاسبه می‌کند. شما هر دستور زیر را خودتان اجرا می‌کنید. عامل هرگز مستقیماً دفتر کل شما را نمی‌نویسد.

دستور ۱: وارد کردن صورت‌حساب با دسته‌بندی‌های پیشنهادی عامل​

یک خروجی بانک را به ورودی‌های اعتبارسنجی‌شده تبدیل کنید. عامل قوانین دسته‌بندی را پیشنهاد می‌دهد. بررسی پیش‌نمایش و تکراری تصمیم می‌گیرد چه چیزی نوشته شود.

پیش‌نیازها​

به bea و یک دایرکتوری تازه دمو نیاز دارید. بدون حساب و بدون ایمپورتر پایتون.

آماده‌سازی ورودی‌ها​

دایرکتوری و دفتر کل را ایجاد کنید. هدف‌های صریح --file هر دستور را به کتاب‌های دمو اشاره می‌دهند.

mkdir ai-agent-demo && cd ai-agent-demo
bea --no-input init books --currency USD --date 2026-08-01 --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USD

این نمونه را به عنوان statement.csv ذخیره کنید:

Date,Payee,Narration,Amount
2026-08-02,Whole Foods,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-9.99

این قوانین دسته‌بندی را به عنوان rules.toml ذخیره کنید:

[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
 
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"

کپی کردن فرمان وظیفه​

این فرمان را به همراه محتوای CSV به عامل خارجی خود بچسبانید:

قوانین دسته‌بندی Beancount را برای ردیف‌های CSV بانکی من پیشنهاد بده.
برای هر فروشنده یک قانون TOML با الگوی تطبیق و حساب هزینه مقصد پیشنهاد کن.
هرگز تاریخ‌ها، پرداخت‌کننده‌ها یا مبالغ را تغییر نده.
ردیف‌هایی را که نمی‌توانی با اطمینان دسته‌بندی کنی بدون تطبیق رها کن: آن‌ها با
پرچم ! به Expenses:Uncategorized ثبت می‌شوند برای بررسی من. من پیش‌نمایش
و اعمال bea import را به صورت محلی اجرا می‌کنم. تو دفتر کل من را نمی‌نویسی.

اجرای معادل‌های CLI​

ابتدا پیش‌نمایش، سپس اعمال ورودی‌های بررسی‌شده و تأیید نتیجه:

bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.toml
bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

بررسی خروجی مورد انتظار​

پیش‌نمایش 3 آماده، 0 تکراری دقیق، 0 تکراری احتمالی را گزارش می‌دهد و با کد 0 خارج می‌شود. چیزی نمی‌نویسد. اجرای اعمال 3 ورودی نوشته شد را گزارش می‌دهد. بررسی هیچ خطایی گزارش نمی‌دهد. صف ! یک ردیف بدون تطبیق از Unknown Shop به مبلغ -9.99 USD را فهرست می‌کند. پرس‌وجوی مانده 930.01 USD را در حساب جاری گزارش می‌دهد. تکرار اعمال 0 آماده، 3 تکراری دقیق را گزارش می‌دهد و 0 ورودی می‌نویسد.

بررسی و اصلاح​

ردیف ! را پس از خواندن آن به عمد در دفتر کل خود دوباره دسته‌بندی کنید. یک بررسی موفق فقط ثابت می‌کند دفتر کل متوازن است. درباره‌ی درست بودن یا نبودن Expenses:Uncategorized به عنوان حساب مناسب چیزی نمی‌گوید. برای سیاست تکراری، مدیریت تعارض و مسیر پیشرفته پایتون، از راهنمای کامل واردات CSV بانکی پیروی کنید.

دستور ۲: پاسخ به سوال مانده بدون نوشتن​

به یک سوال از کتاب‌های دمو پاسخ دهید: چقدر در آگوست 2026 به مواد غذایی و سوخت رفته است. عامل پرس‌وجو را پیش‌نویس می‌کند. دستورهای فقط‌خواندنی پاسخ را تولید می‌کنند.

پیش‌نیازها​

به دفتر کل دمو از دستور ۱ یا کتاب‌های خودتان نیاز دارید. هر دستور زیر فقط‌خواندنی است.

کپی کردن فرمان وظیفه​

این فرمان را به عامل خارجی خود بچسبانید:

یک پرس‌وجوی Beancount (BQL) پیش‌نویس کن که پاسخ دهد: چقدر در آگوست 2026
برای مواد غذایی و سوخت خرج کردم. از نام حساب‌های من دقیقاً همان‌طور که
توسط bea list open فهرست شده‌اند استفاده کن. فقط دستورهای فقط‌خواندنی
پیشنهاد بده: bea query یا bea report با هدف صریح --file. برای اصلاح یک
مجموع غیرمنتظره، ویرایش دفتر کل را پیشنهاد نده. یک مجموع غیرمنتظره یعنی
پرس‌وجو یا کتاب‌ها نیاز به بررسی دارند، نه یک ورودی جبرانی.

اجرای معادل‌های CLI​

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

bea --file books/main.bean query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"
bea --file books/main.bean report income-statement --time 2026-08

مصرف‌کنندگان ماشینی پرچم سراسری --json را قبل از زیردستور اضافه می‌کنند:

bea --file books/main.bean --json query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"

پاکت‌های JSON، کدهای خروج و محل قرارگیری پرچم سراسری از مرجع CLI پیروی می‌کنند. راهنمای زبان پرس‌وجو سطح کامل BQL را مستند می‌کند.

بررسی خروجی مورد انتظار​

پرس‌وجو 20.00 USD برای Expenses:Groceries، 40.00 USD برای Expenses:Transport:Fuel و 9.99 USD برای Expenses:Uncategorized گزارش می‌دهد. مواد غذایی به اضافه سوخت 60.00 USD است. صورت سود و زیان موافق است: 69.99 USD هزینه‌های آگوست با سود خالص -69.99 USD. نسخه JSON همان ردیف‌ها را داخل data.rows با فراداده ستون در data.columns برمی‌گرداند.

بررسی و اصلاح​

یک پرس‌وجو علیه نام حساب اشتباه (بدون ردیف) را روی stderr چاپ می‌کند و همچنان با کد 0 خارج می‌شود. نام را با خروجی bea list open مقایسه کنید و پرس‌وجو را دوباره اجرا کنید. هرگز یک مجموع غیرمنتظره را با ویرایش دفتر کل برای هماهنگی با پاسخ اصلاح نکنید. پرس‌وجو یا کتاب‌ها را اصلاح کنید، سپس bea check را دوباره اجرا کنید.

وقتی یک دستور به کار تکراری تبدیل می‌شود​

فرمان‌های بالا برای کارهای یک‌باره‌ای که با دست هدایت می‌شوند مناسب هستند. کارهایی که هفتگی تکرار می‌کنید برای مهارت‌های نسخه‌بندی‌شده در مخزن محصول مناسب‌اند. هر پیوند زیر منبع فعلی مهارت را باز می‌کند که دستورالعمل‌های راه‌اندازی و راه‌اندازی خودش را دارد. این CMS هیچ کپی از این فایل‌ها نگه نمی‌دارد.

• یک دفتر کل تازه از یک دایرکتوری خالی با beancount-init شروع کنید. فایل دفتر کل، یک اجراکننده Fava و یک پروژه پایتون ایجاد می‌کند.
• یک خروجی بانک را به ورودی‌های دسته‌بندی‌شده با beancount-import تبدیل کنید. هر ردیف را مرحله‌بندی می‌کند، دسته‌بندی‌ها را از تاریخچه دفتر کل پیشنهاد می‌دهد، ردیف‌های قبلاً واردشده را رد می‌کند و فقط پس از تأیید می‌نویسد. دستور ۱ بالا شکل دستی این کار است.
• ثابت کنید یک حساب با صورت‌حسابش مطابقت دارد با beancount-reconcile. دفتر کل را با صورت‌حساب مقایسه می‌کند و پس از تأیید یک تأیید مانده پایان دوره ثبت می‌کند.
• به یک سوال از کتاب‌ها با beancount-ask پاسخ دهید. پرس‌وجوهای فقط‌خواندنی اجرا می‌کند و هر پرس‌وجو را کنار رقمش نشان می‌دهد. دستور ۲ بالا شکل دستی این کار است.
• یک ماه را با beancount-close ببندید. هر حساب فعال را تطبیق می‌دهد، ورودی‌های تکراری و پرچم‌های بررسی را چک می‌کند و بسته شدن را به عنوان یک commit ثبت می‌کند.

مجموعه کامل در درخت مهارت‌های اصلی قرار دارد.

به یک عامل دارای پوسته bea بدهید، یا یک مهارت را در یک کلاینت بارگذاری کنید​

این دو مرحله جداگانه هستند. نصب bea هرگز مهارت‌ها را نصب یا پیکربندی نمی‌کند.

یک عامل دارای پوسته به دستور در مسیر خود نیاز دارد. آن را با شروع سریع CLI نصب کنید، سپس عامل همان دستورهای bea که دستورها نشان می‌دهند را اجرا می‌کند. عامل پیشنهاد می‌دهد، شما بررسی می‌کنید و bea اعتبارسنجی می‌کند.

یک مهارت در خود کلاینت عامل بارگذاری می‌شود، از طریق مکانیزم مهارت خود آن کلاینت. مخزن محصول یک درخت اصلی را به هر دو کلاینت پشتیبانی‌شده ارائه می‌دهد: Claude Code آن را زیر .claude/skills و Codex زیر .agents/skills می‌خواند، به عنوان دایرکتوری‌های پیوندی به همان منبع. محل مهارت کلاینت را به پوشه مهارتی که نیاز دارید اشاره دهید و برای عبارت‌های راه‌انداز و به‌روزرسانی‌ها منبع فعلی آن را بخوانید.

سوالات مشابه-به-ask بدون bea ask​

دستور ۲ به سوالات دفتر کل با یک عامل خارجی به علاوه دستورهای فقط‌خواندنی bea query و bea report پاسخ می‌دهد. آن مسیر محلی است. به هیچ حساب و نصب اضافی نیاز ندارد.

bea ask یک دستیار داخلی جداگانه است. نه دستور بالا است و نه مهارت beancount-ask. سوال را از طریق سرویس هوش مصنوعی میزبانی‌شده مسیریابی می‌کند، بنابراین به اضافه‌ی ask و اعتبارنامه‌های میزبانی‌شده نیاز دارد، همان‌طور که در مرجع CLI مستند شده است. ابتدا CLI پایه را نصب کنید، سپس اضافه را فقط زمانی که پاسخ‌های میزبانی‌شده می‌خواهید اضافه کنید.

خروجی‌های نقل‌قول‌شده و تأیید CLI​

هر دستور بالا علیه بسته منتشرشده bea 0.1.0 در یک دایرکتوری تازه اجرا شده است. شمارش‌ها، مانده‌ها و پیام‌های نقل‌قول‌شده تأیید CLI هستند. فرمان‌های وظیفه علیه هیچ مدلی اجرا نشده‌اند. رفتار مدل به طور جداگانه ارزیابی می‌شود.