دو کار دفترداری را به یک عامل هوش مصنوعی خارجی بسپارید و هر تغییر دفتر کل را تحت بررسی خود نگه دارید: وارد کردن CSV بانکی با بررسی اولیه پیشنمایش، سپس پاسخ به سؤال مانده از خروجی پرسوجو و گزارش.
bea را با شروع سریع CLI نصب کنید. دستورات محلی وارد کردن، پرسوجو و گزارش به حساب Beancount.io نیاز ندارند. عامل چت شما فقط به اشتراک یا کلید API خودش نیاز دارد. فقط راهنمای داخلی bea ask به اعتبارنامههای میزبانی شده نیاز دارد و این دستورالعملها از آن استفاده نمیکنند.
بین ابزارها انتخاب میکنید؟ پنج ابزار حسابداری برای عوامل هوش مصنوعی Beancount.io، hledger، Xero، QuickBooks Online و Puzzle را بر اساس معیارهای یکسان گردش کار عامل، با منابع تاریخدار مقایسه میکند.
عامل چه کاری انجام میدهد و bea چه کاری انجام میدهد
عامل دستهبندیها را پیشنهاد میدهد و پرسوجوها را پیشنویس میکند. Bea ساختار دفتر کل را اعتبارسنجی میکند و مجموعها را محاسبه میکند. شما هر دستور زیر را خودتان اجرا میکنید. عامل هرگز مستقیماً دفتر کل شما را نمینویسد.
دستورالعمل 1: وارد کردن صورتگزارش با دستهبندیهای پیشنهادی عامل
صادرات بانکی را به ورودیهای معتبر تبدیل کنید. عامل قوانین دستهبندی را پیشنهاد میدهد. بررسی پیشنمایش و تکرار، تعیین میکند چه چیزی نوشته شود.
پیشنیازها
به 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 به عامل خارجی خود بچسبانید:
Propose Beancount categorization rules for my bank CSV rows.
Suggest one TOML rule per merchant with a match pattern and a
destination expense account. Never change dates, payees, or amounts.
Leave rows you cannot categorize confidently unmatched: they post to
Expenses:Uncategorized with flag ! for my review. I run bea import
preview and apply locally. You do not write my ledger.اجرای معادلهای 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 بانکی را دنبال کنید.
دستورالعمل 2: پاسخ به سؤال مانده بدون نوشتن
به یک سؤال از دفتر کل نمایشی پاسخ دهید: چقدر در آگوست 2026 به خواربار و سوخت رفت. عامل پرسوجو را پیشنویس میکند. دستورات فقطخواندنی پاسخ را تولید میکنند.
پیشنیازها
به دفتر کل نمایشی از دستورالعمل 1 یا کتابهای خودتان نیاز دارید. هر دستور زیر فقطخواندنی است.
کپی کردن اعلان وظیفه
این اعلان را به عامل خارجی خود بچسبانید:
Draft a Beancount query (BQL) that answers: how much did I spend on
groceries and fuel in August 2026. Use my account names exactly as
listed by bea list open. Propose read-only commands only: bea query
or bea report with an explicit --file target. Do not propose ledger
edits to fix a surprising total. A surprising total means the query
or the books need review, not a compensating entry.اجرای معادلهای 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 برمیگرداند.
بررسی و اصلاح
پرسوجو در برابر نام حساب اشتباه (no rows) را روی stderr چاپ میکند و همچنان با کد 0 خارج میشود. نام را با خروجی bea list open مقایسه کنید و پرسوجو را دوباره اجرا کنید. هرگز مجموع غافلگیرکننده را با ویرایش دفتر کل برای مطابقت با پاسخ اصلاح نکنید. پرسوجو یا کتابها را اصلاح کنید، سپس bea check را دوباره اجرا کنید.
چالش اول: تراز کردن سه ردیف مصنوعی
یک چالش اول قابل حمل با ورودیهای صریح و پاسخی که بهطور مستقل مشتق شده است. سه فایل زیر را دانلود کنید، وارد کردن را اجرا کنید و دو مجموع را بررسی کنید. بدون حساب و بدون پرداخت محصول.
کتابها را در 2026-09-01 به دلار با 1000 دلار در حساب جاری باز کنید. سه ردیف سپتامبر ثبت کنید: پرداخت مشتری 2000.00 دلاری، قبض میزبانی 29.00 دلاری و بازدید کافه 12.50 دلاری. حساب جاری به 2958.50 USD میرسد، از 1000 + 2000 - 29 - 12.50. سود سپتامبر 1958.50 USD است، از 2000 - 29 - 12.50. هر دو انتظار از آن حسابسازی میآیند، نه از خروجی گزارش.
آمادهسازی ورودیها
دایرکتوری را ایجاد کنید و دو حسابی را که الگو حمل نمیکند باز کنید. Expenses:Dining قبلاً از الگوی CLI میآید.
mkdir agent-challenge && cd agent-challenge
bea --no-input init books --currency USD --date 2026-09-01 --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-09-01 --account Income:Consulting -c USD
bea --file books/main.bean add open --date 2026-09-01 --account Expenses:Software -c USDآن سه دستور دفتر کل زیر را تولید میکنند. آن را به جای تایپ کردن از main.bean دانلود کنید.
option "title" "Personal ledger"
option "operating_currency" "USD"
; Add more accounts with bea add open. Amounts on credit accounts are negative.
; bea import books rows it cannot categorize to Expenses:Uncategorized with flag '!'.
2026-09-01 open Assets:Checking USD
2026-09-01 open Assets:Savings USD
2026-09-01 open Assets:Cash USD
2026-09-01 open Liabilities:CreditCard USD
2026-09-01 open Income:Salary USD
2026-09-01 open Income:Interest USD
2026-09-01 open Expenses:Groceries USD
2026-09-01 open Expenses:Dining USD
2026-09-01 open Expenses:Rent USD
2026-09-01 open Expenses:Transport USD
2026-09-01 open Expenses:Utilities USD
2026-09-01 open Expenses:Fees USD
2026-09-01 open Expenses:Uncategorized USD
2026-09-01 open Equity:OpeningBalances USD
2026-09-01 * "Opening balances"
Assets:Checking 1000 USD
Equity:OpeningBalances -1000 USD
2026-09-01 open Income:Consulting USD
2026-09-01 open Expenses:Software USDاین صورتگزارش را به عنوان statement.csv ذخیره کنید، یا آن را از statement.csv دانلود کنید:
Date,Payee,Amount
2026-09-02,Client,2000.00
2026-09-03,Hosting,-29.00
2026-09-04,Cafe,-12.50این قوانین را به عنوان rules.toml ذخیره کنید، یا آن را از rules.toml دانلود کنید. هر قانون حسابی را نام میبرد که دفتر کل شروعکننده باز میکند.
[[rule]]
match = "client"
account = "Income:Consulting"
[[rule]]
match = "hosting"
account = "Expenses:Software"
[[rule]]
match = "cafe"
account = "Expenses:Dining"اجرای چالش
ابتدا پیشنمایش، سپس اعمال و تأیید کنید. مبالغ، تاریخها، نام فیلدها و نام حسابها در هر زبان یکسان هستند. فقط متن اطراف آنها ترجمه شده است.
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee --account Assets:Checking --rules rules.toml
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee --account Assets:Checking --rules rules.toml --apply
bea --file books/main.bean check
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"
bea --file books/main.bean report income-statement --time 2026-09بررسی خروجی مورد انتظار
پیشنمایش 3 آماده، 0 تکرار دقیق، 0 تکرار احتمالی را گزارش میدهد و با کد 0 خارج میشود. اجرای اعمال 3 ورودی نوشته شد را گزارش میدهد. بررسی هیچ خطایی گزارش نمیدهد. پرسوجوی مانده 2958.50 USD را در حساب جاری نگه میدارد. صورت سود و زیان 2000.00 USD درآمد مشاوره در برابر 41.50 USD هزینه، برای سود خالص 1958.50 USD نشان میدهد. تکرار اعمال 0 آماده، 3 تکرار دقیق را گزارش میدهد و 0 ورودی مینویسد.
وقتی یک دستورالعمل به کار تکراری تبدیل میشود
اعلانهای بالا برای کارهای یکباره که با دست هدایت میشوند مناسب هستند. کارهایی که هفتگی تکرار میکنید برای مهارتهای نسخهبندیشده در مخزن محصول مناسب هستند. هر پیوند زیر منبع فعلی مهارت را باز میکند که دستورالعملهای راهاندازی و راهاندازی خود را حمل میکند. این CMS هیچ کپی از این فایلها نگه نمیدارد.
- با beancount-init یک دفتر کل تازه از یک دایرکتوری خالی شروع کنید. فایل دفتر کل، یک اجراکننده Fava و یک پروژه پایتون ایجاد میکند.
- صادرات بانکی را با beancount-import به ورودیهای دستهبندیشده تبدیل کنید. هر ردیف را مرحلهبندی میکند، دستهبندیها را از تاریخچه دفتر کل پیشنهاد میدهد، ردیفهای قبلاً وارد شده را رد میکند و فقط پس از تأیید مینویسد. دستورالعمل 1 بالا شکل دستی این کار است.
- ثابت کنید یک حساب با صورتگزارش خود مطابقت دارد با beancount-reconcile. دفتر کل را با صورتگزارش مقایسه میکند و پس از تأیید، یک ادعای تعادل پایان دوره ثبت میکند.
- با beancount-ask به سؤالی از کتابها پاسخ دهید. پرسوجوهای فقطخواندنی اجرا میکند و هر پرسوجو را کنار رقم آن نشان میدهد. دستورالعمل 2 بالا شکل دستی این کار است.
- با beancount-close یک ماه را ببندید. هر حساب فعال را تطبیق میدهد، ورودیهای تکراری و پرچمهای بررسی را بررسی میکند و بستهشدن را به عنوان یک commit ثبت میکند.
مجموعه کامل در درخت مهارتهای متعارف زندگی میکند.
به عامل دارای پوسته bea بدهید، یا مهارتی را در یک کلاینت بارگذاری کنید
این دو گام جداگانه هستند. نصب bea هرگز مهارتها را نصب یا پیکربندی نمیکند.
عامل دارای پوسته به دستور در مسیر خود نیاز دارد. آن را با شروع سریع CLI نصب کنید، سپس عامل همان دستورات bea را که دستورالعملها نشان میدهند اجرا میکند. عامل پیشنهاد میدهد، شما بررسی میکنید و bea اعتبارسنجی میکند.
مهارت از طریق مکانیزم مهارت خود آن کلاینت، در خود کلاینت عامل بارگذاری میشود. مخزن محصول یک درخت متعارف را به هر دو کلاینت پشتیبانیشده نشان میدهد: Claude Code آن را تحت .claude/skills و Codex تحت .agents/skills، به عنوان دایرکتوریهای پیوندی به همان منبع میخواند. مکان مهارت کلاینت را به پوشه مهارتی که نیاز دارید نشان دهید و برای عبارات راهانداز و بهروزرسانیها، منبع فعلی آن را بخوانید.
bea ask مهارتهای خود را جداگانه، از یک SKILL.md در کنار دفتر کل شما بارگذاری میکند — گسترش bea ask با مهارتها را ببینید.
سؤالات شبیه ask بدون bea ask
دستورالعمل 2 به سؤالات دفتر کل با یک عامل خارجی به اضافه دستورات فقطخواندنی bea query و bea report پاسخ میدهد. آن مسیر محلی است. به حساب و نصب اضافی نیاز ندارد.
bea ask یک راهنمای داخلی جداگانه است. نه دستورالعمل بالا است و نه مهارت beancount-ask. سؤال را از طریق سرویس هوش مصنوعی میزبانیشده مسیریابی میکند، بنابراین به افزونه ask و اعتبارنامههای میزبانیشده نیاز دارد، همانطور که در مرجع CLI مستند شده است. ابتدا CLI پایه را نصب کنید، سپس فقط وقتی پاسخهای میزبانیشده میخواهید افزونه را اضافه کنید.
خروجیهای نقلقولشده و تأیید CLI
هر دستور بالا در برابر بسته منتشر شده bea 0.1.0 در یک دایرکتوری جدید اجرا شد. شمارشها، ماندهها و پیامهای نقلقولشده تأیید CLI هستند.
یک کلاینت چالش اول را در یک کپی تازه از دانلودها با هیچ قانونی که از قبل ارائه نشده بود تکمیل کرده است. Muse Code 1.1.1 (مدل muse-spark-1.3-contributor) دستهبندی خود را مشتق کرد، 3 آماده را با هیچ چیزی که نوشته نشده بود پیشنمایش کرد، 3 ورودی را اعمال کرد و 2958.50 USD حساب جاری با سود سپتامبر 1958.50 USD گزارش داد — مطابق با انتظارات بالا. تنها اعمال ناموفق آن (قفل کش sandbox شده، بازیابیشده از طریق XDG_CACHE_HOME) در پرونده نگهداری میشود. اعلان کامل، توالی ابزار و تأیید را در رونوشت اجرا بخوانید، یا مسیر کار را با اسکریپت نمایشی و خروجی ضبطشده آن دوباره پخش کنید.
آن اجرا تأیید خروجی CLI یک اجرای واحد است، نه معیار مدل. درباره سایر کلاینتها، دقت حسابداری به طور کلی یا استفاده تولیدی بدون نظارت هیچ ادعایی نمیکند.
داستان کامل اثبات — ورودیها، روششناسی، نتایج مشاهدهشده، شکستها، محدودیتها و دانلودها — به عنوان آیا عامل شما میتواند این کتابها را تراز کند؟ منتشر شده است.
پژوهش گستردهتر پشت این گردش کارها را در Bean Labs، مرکز پژوهش اتوماسیون حسابداری Beancount.io کاوش کنید.