چطور با allow_large فایل بزرگ را در یک بار Read کلاد کد بخوانیم؟

نسخه‌ی 2.1.296 کلاد کد یک ورودی تازه به ابزار Read اضافه کرد: allow_large. تا پیش از این نسخه، خواندن یک فایل از سقف توکن رد می‌شد و باید با offset و limit فایل را تکه‌تکه می‌خواندی. این ورودی در بسته‌ی رسمی npm با شمارش صفر به یک رسید و با یک اسکریپت قابل بازتولید سنجیده می‌شود.

این ورودی از کجا آمد و چه چیزی را ثابت می‌کند

تاریخچه‌ی رسمی کلاد کد در نسخه‌ی 2.1.296 این تغییر را ثبت کرده است: گزینه‌ای به نام allow_large به ابزار Read اضافه شد تا کلاد یک فایل متنی بزرگ‌تر از حد معمول را در یک فراخوانی بخواند، آن هم وقتی که واقعاً کل فایل را لازم دارد و پنجره‌ی زمینه جا دارد.

همان نسخه سقف توصیف ابزارهای MCP را از 2,048 به 4,096 نویسه برد و خواندن با اشاره‌ی @ دیگر فایل بزرگ را بی‌صدا کنار نمی‌گذارد.

نکته‌ای که این پست را از بقیه‌ی خبرها جدا می‌کند این است که allow_large یک کلید تنظیمات نیست. در مرجع رسمی تنظیمات که 244 کلید را فهرست می‌کند، هیچ کلیدی با نام allow_large یا readAllowLarge وجود ندارد. این ورودی در سمت مدل است، نه در settings.json.

#!/usr/bin/env bash
# اثبات وجود یک ورودی تازه از بسته‌ی رسمی سازنده، نه از وبلاگ
# بسته‌ی claude-code تعریف TypeScript ابزارها را در sdk-tools.d.ts منتشر می‌کند،
# پس وجود فیلد یک واقعیت درباره‌ی انتشار انthropیک است و آفلاین بازتولید می‌شود.
#
# هر دو نسخه را کنار هم نصب کن تا تعریف ابزارشان قابل مقایسه باشد:
$ npm install -g @anthropic-ai/claude-code@2.1.296
set -eu
probe() {
  local v="$1"; local t="$W/v$v"; cd "$W"
  local tarball
  tarball=$(npm pack "@anthropic-ai/claude-code@$v" --silent 2>/dev/null | tail -1)
  [ -n "$tarball" ] || { echo "$v: npm pack failed"; return 1; }
  mkdir -p "$t" && tar xzf "$tarball" -C "$t"
  local d="$t/package/sdk-tools.d.ts"
  local declared count
  declared=$(python3 -c "import json;print(json.load(open('$t/package/package.json'))['version'])")
  count=$(grep -c 'allow_large' "$d" 2>/dev/null || true)
  [ -n "$count" ] || count=0
  printf '%s: declared=%s  allow_large_occurrences=%s\n' "$v" "$declared" "$count"
  awk '/^export interface FileReadInput/,/^}/' "$d" | grep -A1 'allow_large' || true
}
W=$(mktemp -d); trap 'rm -rf "$W"' EXIT
for v in 2.1.295 2.1.296; do probe "$v"; echo; done

خروجی واقعی این اسکریپت روی همین ماشین:

$ diff-read-schema.sh 2.1.295 2.1.296
2.1.295: declared=2.1.295  allow_large_occurrences=0

2.1.296: declared=2.1.296  allow_large_occurrences=1
   */
  allow_large?: boolean;
}

این خروجی دو چیز را ثابت می‌کند. اول اینکه نسخه‌ی دانلودشده با همان شماره‌ای که بسته ادعا می‌کند برچسب خورده، پس اختلاف صفر و یک تفاوت مستند است نه آرتیفکت دانلود ناقص. دوم اینکه فیلد دقیقاً روی FileReadInput نشسته، یعنی همان ورودی‌ای که کلاد برای خواندن فایل پر می‌کند.

چرا یک عدد ثابت برای خواندن جواب نمی‌دهد

پیش از سراغ allow_large رفتن، باید بدانیم فایل از کدام دسته است. مشکل از جایی شروع می‌شود که عدد 2,000 خط که در توضیح ابزار Read نقل می‌شد، واحد درستی نیست. سقف واقعی توکن است، و بایت‌به‌خط در فایل‌های مختلف تا هفت برابر فرق می‌کند.

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

#!/usr/bin/env bash
# تصمیم بگیر فایل را با ابزار Read کلاد کد چطور بخوانی
# سقف Read توکن است، نه «۲۰۰۰ خط». پس اول بایت‌به‌خط خودِ فایل را اندازه بگیر.
# استفاده: read-plan.sh <file> [budget_bytes]
set -euo pipefail

f="${1:?usage: read-plan.sh <file> [budget_bytes]}"
budget="${2:-40000}"
long_line=500

[ -f "$f" ] || { echo "NOT_FOUND $f"; exit 1; }

bytes=$(wc -c < "$f" | tr -d ' ')
lines=$(wc -l < "$f" | tr -d ' ')
[ "$lines" -eq 0 ] && lines=1
maxlen=$(awk '{ if (length($0) > m) m = length($0) } END { print m+0 }' "$f")
bpl=$(awk -v b="$bytes" -v l="$lines" 'BEGIN { printf "%d", (b/l)+1 }')
kind=text
[ "$(head -c 4096 "$f" | wc -c)" != "$(head -c 4096 "$f" | tr -d '\000' | wc -c)" ] && kind=binary

echo "file=$f bytes=$bytes lines=$lines bytes_per_line=$bpl max_line=$maxlen kind=$kind"

if [ "$kind" = binary ]; then
  echo "PLAN=BASH_ONLY   reason=binary"
elif [ "$maxlen" -gt "$long_line" ]; then
  echo "PLAN=BASH_ONLY   reason=longest line is ${maxlen} B (even limit=1 overshoots)"
elif [ "$bytes" -le "$budget" ]; then
  echo "PLAN=READ_DIRECT reason=${bytes} B fits the ${budget} B budget"
  echo "  allow_large: true if Read still truncates."
else
  chunk=$(( budget / bpl )); [ "$chunk" -lt 1 ] && chunk=1
  blocks=$(( (lines + chunk - 1) / chunk ))
  echo "PLAN=READ_RANGED reason=${bytes} B > budget ${budget} B"
  echo "  limit=${chunk} lines x ${blocks} blocks (derived from ~${bpl} B per line)"
  echo "  allow_large: true beats ${blocks} round trips."
fi

$ bash read-plan.sh access.log
file=access.log bytes=10724247 lines=120000 bytes_per_line=90 max_line=90 kind=text
PLAN=READ_RANGED reason=10724247 B > budget 40000 B
  limit=444 lines x 271 blocks (derived from ~90 B per line)
  allow_large: true beats 271 round trips.

$ bash read-plan.sh export.json
file=export.json bytes=9057782 lines=720001 bytes_per_line=13 max_line=25 kind=text
PLAN=READ_RANGED reason=9057782 B > budget 40000 B
  limit=3076 lines x 235 blocks (derived from ~13 B per line)
  allow_large: true beats 235 round trips.

$ bash read-plan.sh bundle.min.js
file=bundle.min.js bytes=968007 lines=1 bytes_per_line=968008 max_line=968007 kind=text
PLAN=BASH_ONLY   reason=longest line is 968007 B (even limit=1 overshoots)

$ bash read-plan.sh small.py
file=small.py bytes=3913 lines=362 bytes_per_line=11 max_line=26 kind=text
PLAN=READ_DIRECT reason=3913 B fits the 40000 B budget
  allow_large: true if Read still truncates.

پراکندگی را در همین چهار خروجی ببین. با 90 بایت بر خط، 2,000 خط یعنی حدود 180 کیلوبایت؛ همان 2,000 خط با 13 بایت بر خط فقط 26 کیلوبایت است. یک عدد ثابت برای هر دو، یکی را چهار و نیم برابر از بودجه می‌برد و دیگری را نصف بودجه مصرف می‌کند.

فایل سوم از این هم بدتر است: یک خط به طول 968,007 بایت. حتی limit=1 هم آن را نمی‌خواند، چون کل خط یک‌جا می‌آید. اینجا allow_large هم نجاتت نمی‌دهد و هیچ ورودی‌ای نمی‌دهد؛ راه درست یک ابزار خط فرمان است که خروجی‌اش را خلاصه کند.

عددها را از خودِ فایل بساز

اندازه‌ی هر بلاک از تقسیم بودجه بر بایت‌به‌خط خودِ فایل آمد: 40,000 تقسیم بر 90 می‌شود 444 خط، و تقسیم بر 13 می‌شود 3,076 خط. تعداد بلاک هم از تقسیم تعداد کل خط بر اندازه‌ی بلاک می‌آید: 120,000 تقسیم بر 444 می‌شود 271 بلاک، و 720,001 تقسیم بر 3,076 می‌شود 235 بلاک.

کش پرامپت هزینه‌ی ورودی تکراری را می‌پوشاند، ولی جای نخواندن را نمی‌گیرد. این‌جا باید تعداد فراخوانی را کم کنی، و allow_large دقیقا همان کار را می‌کند.

# ۲۷۱ فراخوانی جدا برای لاگ، در برابر یک فراخوانی:
{
  "tool": "Read",
  "input": {
    "file_path": "/var/log/nginx/access.log",
    "allow_large": true
  }
}

# ولی برای فایلی که ۹۶۸ کیلوبایت در یک خط است، allow_large غلط است:
{
  "tool": "Bash",
  "input": {
    "command": "node -e \"const s=require('fs').readFileSync('bundle.min.js','utf8');console.log(s.length,'bytes')\""
  }
}

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

آن‌ها زیاد درباره‌ی این نسخه گفتند که اشتباه می‌شود

نسخه‌ی 2.1.296 یک چیز دیگر هم عوض کرد که در فهرست‌های خبری کمتر دیده می‌شود: قیمت خواندن کش‌شده‌ی Sonnet 5.5 در /cost، خط وضعیت، --max-budget-usd و اعداد SDK از 0.20 به 0.10 دلار به ازای هر میلیون توکن رسید. اگر بودجه‌ی ایجنت‌هایت را با خط فرمان کنترل می‌کنی، این عدد مستقیم روی سقفی که تعیین می‌کنی اثر می‌گذارد.

اما یک گزارش کاربر درست پس از انتشار این نسخه باز شده که به آن می‌پردازیم. یک کاربر گزارش داده نشست‌های تعاملی روی claude-opus-5-5 از 2026-10-10 ناگهان خیلی زودتر از حد مستند فشرده‌سازی خودکار می‌شوند. گزارش او دو ردیف دارد: پیش از 2.1.296 در 47 فشرده‌سازی، عدد توکن بین 966,331 تا 980,835 بوده، و در 2.1.296 در 8 فشرده‌سازی، بین 281,107 تا 844,686.

آن گزارش با برچسب regression باز شده و هنوز بسته نشده است. مهم این است که تاریخچه‌ی رسمی 2.1.296 هیچ تغییری در نقطه‌ی فشرده‌سازی گفتگوی اصلی اعلام نکرده. پس این یک ادعای باز است، نه واقعیتی اثبات‌شده. اگر روی مدل‌های پنجره‌ی یک‌میلیونی کار می‌کنی و فشرده‌سازی زودهنگام می‌بینی، همین شماره جای درستی برای دنبال کردن وضعیت است.

تست کار: از کجا شروع کنم

اول نسخه‌ی نصب‌شده‌ی خودت را ببین. روی همین ماشین، نصب سراسری روی 2.1.295 بود در حالی که آخرین نسخه‌ی npm روی 2.1.296. یعنی اگر بدون به‌روزرسانی کار می‌کنی، این ورودی برای تو اصلا وجود ندارد.

$ npm view @anthropic-ai/claude-code version
2.1.296

$ grep -c allow_large $(npm root -g)/@anthropic-ai/claude-code/sdk-tools.d.ts
0

$ npm install -g @anthropic-ai/claude-code@2.1.296
# بعد از نصب، همان شمارش باید یک شود
$ grep -c allow_large $(npm root -g)/@anthropic-ai/claude-code/sdk-tools.d.ts
1

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

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

قدم سوم، قبل از هر خواندن، فایل را به اسکریپت بده. طرحی که برمی‌گرداند یا READ_DIRECT است، یا READ_RANGED، یا BASH_ONLY. این سه پاسخ یعنی به ترتیب: یک‌بار بخوان، تکه‌تکه بخوان، یا اصلا نخوان و در خط فرمان خلاصه‌اش کن. هزینه‌ی اشتباه در دو حالت آخر، همان تعداد فراخوانی است.

منابع

1. تاریخچه‌ی رسمی کلاد کد در گیت‌هاب — ثبت allow_large در نسخه‌ی 2.1.296
2. بسته‌ی @anthropic-ai/claude-code در npm — منبع تعریف FileReadInput و زمان انتشار
3. مرجع ابزارهای کلاد کد — رفتار ابزار Read و پارامترهای آن
4. صفحه‌ی تاریخچه‌ی کلاد کد در مستندات رسمی
5. مرجع کامل تنظیمات کلاد کد — برای بررسی نبود کلید allow_large
6. مسئله‌ی 6910 در ریپوی رسمی — اختلاف رفتار واقعی Read با توضیح 2,000 خط
7. مسئله‌ی 101067 — گزارش باز فشرده‌سازی خودکار زودهنگام در 2.1.296
8. مستندات پنجره‌ی زمینه — سقف فشرده‌سازی خودکار مدل‌های با پنجره‌ی یک‌میلیونی