کد ملی را در جاوااسکریپت چطور اعتبارسنجی کنیم؟

از تابع verifyIranianNationalId در بستهٔ npm به نام @persian-tools/persian-tools استفاده کنید. ورودی را اول با autoConvertDigitsToEN به رقم لاتین برگردانید، چون رقم فارسی بیصدا false میگیرد، و نتیجه را با === true بسنجید، چون برای ورودی خالی undefined برمیگردد. مهارت nationalId همینها را به دستیار کدنویسی یاد میدهد.

تابع verifySheba در persian-tools کجاست؟

چنین تابعی وجود ندارد. طبق متن مهارت sheba، تابع درست isShebaValid است و اطلاعات بانک را getShebaInfo میدهد. نام فارسی بانک در فیلد persianName است و فیلدی به نام bankName ندارد. فاصلههای داخل شبا هم خودکار حذف نمیشوند، پس قبل از بررسی آنها را بردارید.

این مهارتها برای کدام دستیارها کار میکنند؟

برای دستیارهایی که Agent Skills میخوانند، از جمله Claude Code، Cursor، Codex، GitHub Copilot و Gemini CLI. ابزار نصب (skills) دستیارهای نصبشده روی سیستم را خودش پیدا میکند. کاربرد اصلی پروژههای JavaScript و TypeScript است، نه گفتگوی معمولی.

چرا دستور نصب persian-tools الان کار نمیکند؟

دستور npx skills add مهارتها را از مخزن GitHub سازنده برمیدارد و این مخزن در ۱۳ آبان ۱۴۰۵ پاسخ 404 میداد. تا وقتی مخزن برنگشته، نصب شکست میخورد. خود کتابخانه از npm نصب میشود و نام تابعها و دامهای این نوشته را میتوانید مستقیم به دستیار بدهید.

تابع درست کد ملی یعنی این کد ملی واقعاً وجود دارد؟

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

اعتبارسنجی کد ملی در جاوااسکریپت با مهارت‌های persian-tools

فرم ثبت‌نام یا تسویه‌حساب یک فروشگاه را می‌سازید و از Claude Code یا Cursor می‌خواهید «کد ملی، شماره کارت و شبا را اعتبارسنجی کن». دستیار یا الگوریتم رقم کنترل را از حافظه می‌نویسد، یا سراغ کتابخانهٔ persian-tools می‌رود و تابعی صدا می‌زند که اصلاً وجود ندارد. تست‌ها با رقم لاتین سبز می‌شوند و روز اول، کاربری که کد ملی‌اش را با کیبورد فارسی تایپ کرده، خطای «کد ملی نامعتبر» می‌گیرد.

جواب کوتاه: برای اعتبارسنجی کد ملی در جاوااسکریپت از verifyIranianNationalId در بستهٔ @persian-tools/persian-tools استفاده کنید، ورودی را اول با autoConvertDigitsToEN به رقم لاتین برگردانید و نتیجه را با === true بسنجید. مهارت‌های «ابزارهای فارسی (persian-tools)» همین را به دستیار کدنویسی یاد می‌دهند: برای هر کار ایرانی، تابع درست کتابخانه و دام‌های آن.

اعتبارسنجی کد ملی در جاوااسکریپت: دستیار بدون راهنما چه می‌نویسد؟

مشکل معمولاً از جایی است که دیده نمی‌شود. تابع کد ملی رقم فارسی را خودش تبدیل نمی‌کند و برای ورودی خالی به‌جای false مقدار undefined می‌دهد. برای شبا هم دستیارها به verifySheba عادت دارند، در حالی که مهارت sheba صریح می‌نویسد این تابع وجود ندارد و نام بانک در persianName است، نه bankName. کدی از این دست در نگاه اول درست است:

import { verifySheba, verifyIranianNationalId } from "@persian-tools/persian-tools";

if (!verifyIranianNationalId(form.nationalId)) showError("nationalId"); // "۰۴۹۹۳۷۰۸۹۹" fails
const ok = verifySheba(form.sheba);                                      // no such export

با راهنمای مهارت‌ها، همان فرم این شکل را پیدا می‌کند:

import {
  autoConvertDigitsToEN, verifyIranianNationalId, isShebaValid, getShebaInfo,
} from "@persian-tools/persian-tools";

const nid = autoConvertDigitsToEN(form.nationalId.trim());
const nidOk = verifyIranianNationalId(nid) === true;

const sheba = autoConvertDigitsToEN(form.sheba).replace(/\s/g, "").toUpperCase();
const info = isShebaValid(sheba) ? getShebaInfo(sheba) : null;
const bankName = info?.persianName; // there is no bankName field

در مثال خود مهارت، getShebaInfo("IR820540102680020817909002") بانک پارسیان را با کد 054 برمی‌گرداند و چون این بانک شمارهٔ حساب را در شبا دارد، accountNumber هم در نتیجه هست. برای بانک‌هایی که این‌طور نیستند، accountNumberAvailable برابر false است و فقط نام بانک می‌آید.

دام‌هایی که در متن مهارت‌ها آمده است

هر مهارت یک فایل SKILL.md است با خط import (هم ESM و هم CommonJS)، امضای توابع، مثال، الگوریتم و بخشی برای خطاهای رایج. بخش آخر از همه به‌دردبخورتر است:

کار	تابع درست	دامی که مهارت گوشزد می‌کند
کد ملی	`verifyIranianNationalId`	رقم فارسی بی‌صدا رد می‌شود؛ خروجی `boolean \| undefined` است؛ پیشوند سه‌رقمی شهر هم بررسی می‌شود مگر با `{ checkPrefix: false }`
شبا	`isShebaValid` و `getShebaInfo`	تابع `verifySheba` وجود ندارد؛ فاصله حذف نمی‌شود؛ نام بانک در `persianName` است
شماره کارت	`verifyCardNumber`	کارت غیرایرانی حتی با الگوریتم Luhn درست هم رد می‌شود؛ رقم فارسی تبدیل نمی‌شود
قبض	`Bill`	قبضی که نوعش «unknown» دربیاید رد می‌شود، حتی اگر حسابش درست باشد
نیم‌فاصله	`halfSpace`	فقط نیم‌فاصله اضافه می‌کند و هیچ‌وقت حذف نمی‌کند؛ «ي» و «ك» عربی را درست نمی‌کند

نکتهٔ مشترک همهٔ این ردیف‌ها رقم فارسی است. کاربر ایرانی با کیبورد فارسی تایپ می‌کند و بیشتر توابع، طبق متن مهارت‌ها، ورودی را تبدیل نمی‌کنند. پس اولین خط هر اعتبارسنجی autoConvertDigitsToEN است. مهارت کد ملی یک نکتهٔ دیگر هم دارد: توابع ساخت کد ملی (createIranianNationalId) برای تست و داده‌های آزمایشی‌اند، نه برای چیز دیگر.

اعتبارسنجی شبا در جاوااسکریپت و تشخیص بانک از شماره کارت در کد

شبا یعنی «IR» و پس از آن ۲۴ رقم، و درستی‌اش با باقی‌ماندهٔ تقسیم بر ۹۷ سنجیده می‌شود. عدد ۲۶ رقمی در Number جا نمی‌شود و کتابخانه آن را تکه‌تکه حساب می‌کند. مهارت sheba صریح می‌گوید این کد را به BigInt «ساده» نکنید، چون عمداً برای مرورگرهای قدیمی‌تر این‌طور نوشته شده است. این همان جایی است که دستیار بدون راهنما دوست دارد «بهترش» کند.

برای کارت بانکی سه مهارت جدا هست. verifyCardNumber هم Luhn را حساب می‌کند و هم شش رقم اول (BIN) را با فهرست بانک‌های ایرانی می‌سنجد. getBankNameFromCardNumber از همان شش رقم نام بانک را درمی‌آورد و اگر پیدا نکند null می‌دهد. سومی، extractCardNumber، شماره کارت را از وسط یک متن آزاد پیدا می‌کند، حتی با رقم فارسی و خط تیره. برای داده‌های تست هم مهارت می‌گوید شماره کارت واقعی در کد نگذارید و از ترکیب یک BIN معتبر با ادامهٔ درست Luhn بسازید.

مهارت‌های persian-tools در چهار دسته

سایت skills.sh، فهرست عمومی مهارت‌ها، ۲۶ مهارت از این مجموعه را نشان می‌دهد و ممیزی‌های امنیتی‌اش (Gen Agent Trust Hub، Socket و Snyk) برای این مجموعه «Pass» است:

هویت و بانک: کد ملی (بررسی و ساخت کد آزمایشی)، شناسهٔ ملی شرکت‌ها (legalId)، شهر و استان از سه رقم اول کد ملی، شبا، شماره کارت، نام بانک از شماره کارت، پیدا کردن شماره کارت در متن، قبض آب و برق و گاز و تلفن و جریمهٔ رانندگی از شناسهٔ قبض و پرداخت، و پلاک خودرو و موتورسیکلت.
عدد و پول: تبدیل رقم فارسی، عربی و لاتین، جداکنندهٔ هزارگان، عدد به حروف و حروف به عدد، تبدیل عبارت‌هایی مثل «دو میلیون تومن» به عدد، و پسوند ترتیبی (مثلاً «سه» به «سوم»).
متن و نیم‌فاصله: گذاشتن نیم‌فاصله با halfSpace (مثلاً «می خواهم بروم» می‌شود «می‌خواهم بروم» و «کتاب ها» می‌شود «کتاب‌ها»)، یکدست کردن «ي» و «ك» عربی، تشخیص متن عربی، ساخت slug فارسی، باز کردن نشانی‌های درصدکدشده و تحلیل متن.
زمان و مکان: «۵ دقیقه قبل» از تاریخ شمسی، زمان باقی‌مانده، مرکز هر استان و پیدا کردن استان از مختصات GPS.

اگر کار شما نیم‌فاصله در جاوااسکریپت است، ترتیب درست را هم مهارت می‌گوید: اول «ي» و «ك» را با toPersianChars یا autoArabicToPersian درست کنید و بعد halfSpace را بزنید. halfSpace فقط بین کلمه‌هایی کار می‌کند که با فاصله جدا شده‌اند. برای ویرایش متن فارسی (نه کد)، مهارت فارسی‌نویسی ابزار مناسب‌تری است.

نصب مهارت‌ها و وضعیت امروز مخزن

دستور نصب همهٔ مهارت‌ها، به نقل از سازنده، این است:

npx skills add persian-tools/persian-tools

برای نصب فقط یک مهارت، skills.sh این شکل را می‌دهد:

npx skills add https://github.com/persian-tools/persian-tools --skill nationalId

هشدار: در ۱۳ آبان ۱۴۰۵ مخزن GitHub سازنده (github.com/persian-tools/persian-tools) پاسخ 404 می‌داد و این دستورها مهارت‌ها را از همان‌جا برمی‌دارند. پس تا وقتی مخزن برنگردد، نصب شکست می‌خورد. پیش از نصب، صفحهٔ مهارت را ببینید یا نشانی مخزن را باز کنید.

خود کتابخانه در npm هست (npm install @persian-tools/persian-tools) و در این فاصله می‌توانید نام توابع و دام‌های جدول بالا را مستقیم در درخواستتان به دستیار بدهید. جای مهارت را کامل نمی‌گیرد، ولی جلوی بیشتر خطاهای بالا را می‌گیرد.

چند نکتهٔ ابزار نصب (بستهٔ npm به نام skills):

به Node.js نسخهٔ 22.20 یا بالاتر نیاز دارد و باید در پوشهٔ پروژه اجرا شود. پیش‌فرض نصب برای همان پروژه است و با -g برای همهٔ پروژه‌ها.
دستیارهای نصب‌شده را خودش پیدا می‌کند. برای نصب فقط برای یک دستیار گزینهٔ -a را دارد.
آمار ناشناس جمع می‌کند. برای خاموش کردنش متغیر DISABLE_TELEMETRY=1 یا DO_NOT_TRACK=1 را بگذارید.

مثل هر مهارتی از منبع ناشناس، فایل‌های SKILL.md را قبل از نصب بخوانید. چرا این کار مهم است و مهارت با سرور MCP چه فرقی دارد، در تفاوت Skill و MCP آمده است.

مهارت برای Claude Code و دستیارهای دیگر

ابزار نصب مهارت را در پوشهٔ هر دستیار می‌گذارد. برای Claude Code این پوشه .claude/skills/ در پروژه یا ~/.claude/skills/ برای همهٔ پروژه‌هاست. فهرست دستیارهایی که این ابزار می‌شناسد بلند است: Cursor، Codex، GitHub Copilot، Gemini CLI، Goose، Cline، OpenCode، Roo Code، Kiro CLI، Qwen Code، Zed، Warp و Continue از آن جمله‌اند.

مخاطب این مهارت‌ها برنامه‌نویسی است که روی پروژهٔ JavaScript یا TypeScript با یکی از این دستیارها کار می‌کند. کتابخانهٔ persian-tools نسخه‌هایی برای پایتون، Go، PHP و زبان‌های دیگر هم دارد، اما این مهارت‌ها فقط کتابخانهٔ جاوااسکریپت را پوشش می‌دهند.

اگر برنامه‌نویس نیستید و فقط می‌خواهید درستی یک کد ملی یا شبا را در گفتگو با ChatGPT یا Claude ببینید، مهارت به کارتان نمی‌آید. سرور جعبه‌ابزار ایرانی همین بررسی‌ها را در خود گفتگو انجام می‌دهد و از مسیر اتصال دستیار وصل می‌شود. اگر هم کار شما کامپوننت فرم در React است (ورودی کد ملی، کارت و تقویم شمسی)، shadcn فارسی سراغ رابط کاربری می‌رود و persian-tools سراغ منطق پشت آن.

کد ملی معتبر یعنی شخص واقعی؟

نه، و این مهم‌ترین مرز این مهارت‌هاست:

چک‌سام وجود را ثابت نمی‌کند. رقم کنترل درست یعنی عدد خوش‌ساخت است، نه اینکه چنین شخص، حساب یا کارتی وجود دارد. بررسی سمت سرور و استعلام رسمی را جای خودش نگه دارید.
مهارت خودش چیزی را بررسی نمی‌کند. فقط به دستیار می‌گوید کدام تابع را صدا بزند، پس پروژه باید بستهٔ npm را داشته باشد.
بخشی از متن مهارت‌ها جلوتر از نسخهٔ پایدار است. آخرین نسخهٔ پایدار در npm نسخهٔ 4.0.4 است و moneyWordsToNumber (تبدیل «دو میلیون تومن» به عدد) و analyzeText (تحلیل متن) فقط در نسخهٔ آزمایشی 5.0.0-beta.0 هستند. اگر دستیار یکی از این دو تابع را پیشنهاد داد، نسخهٔ نصب‌شده را چک کنید.
سازنده مستقل است. مهارت‌ها و کتابخانه را یک تیم متن‌باز با مجوز MIT نوشته و بازارچه آن‌ها را نساخته است.

اگر فرم بعدی‌تان تاریخ شمسی هم دارد، مهارت تاریخ شمسی در کد کنار این مجموعه خوب کار می‌کند. برای این‌که ببینید مدل‌ها بدون کمک در کارهای ایرانی کجا اشتباه می‌کنند، آزمایش دقت هوش مصنوعی در تاریخ شمسی را بخوانید. وضعیت نصب و دستور به‌روز همیشه در صفحهٔ مهارت persian-tools است.