قواعد توجيه تقلّل حوادث mojibake لـ Codex على Windows

عند تشغيل Codex على ملفّات تحوي يابانية في Windows، ما يؤثّر أوّلاً ليس مواءمة إعدادات المحرّر والـ shell كلّها، بل التصريح لـ Codex بـ «كيف يقرأ، وكيف يكتب، وأين يتوقّف».

ما يصعب خصوصاً مشاهد كهذه:

• اختلاط ملفّات UTF-8 وCP932 وUTF-16
• النصّ يبدو مقروءاً ظاهراً، لكن تفسير البايتات الفعلية منحرف
• نويت تعديلاً طفيفاً لملفّ قائم، فأُعيد حفظه عند الحفظ بترميز آخر
• التلف يقع في «ما ليس شيفرة»: CSV وTXT والسجلّات وMarkdown وملفّات الإعداد
• حفظ سكربت مؤقّت أو مخرجات shell كما هي فيثبّت الحادثة

Codex من OpenAI أثبت إن عومل أقرب إلى زميل فريق تُعطى له إعدادات وقواعد عمل ويُستخدَم باستمرار، لا محاور دردشة لمرّة واحدة. وإن وُجد تشغيل يُقرأ فيه AGENTS.md، فقواعد ترميز الأحرف أكثر أثراً إن ثُبِّتت دائماً من أن تُكرَّر شفهيّاً في كلّ مرّة.

تنظّم هذه المقالة، لصعيد عملي، التوجيه الذي يؤثّر أوّلاً إن أُعطي لـ Codex ليتعامل بأمان مع ملفّات يابانية على Windows.

flowchart TB
    accTitle: ثبّت التوجيه قبل الإعداد
    accDescr: مخطّط يبيّن أنّ ما يؤثّر أوّلاً عند تشغيل Codex على ملفّات يابانية في Windows ليس مواءمة إعدادات المحرّر والـ shell، بل التصريح كيف يقرأ وكيف يكتب وأين يتوقّف.
    a1["مواءمة إعدادات المحرّر والـ shell"] -.-> a2["ما يؤثّر أوّلاً ليس هنا"]
    a3["كيف يقرأ"] --> a6["صرّح لـ Codex"]
    a4["كيف يكتب"] --> a6
    a5["أين يتوقّف"] --> a6

الشكل 1: ما يؤثّر أوّلاً ليس إعداد البيئة بل التصريح بطريقة القراءة والكتابة والتوقّف.

الافتراض: Codex وAGENTS.md اللذان تفترضهما المقالة

لمن لا يستخدم Codex، الافتراض أوّلاً.

Codex وكيل برمجة يقرأ ملفّات المستودع ويكتبها فعلاً. له مداخل عدّة: CLI يعمل في الطرفية المحلّية، وامتداد محرّر، وما يعمل في السحابة. ما تفترضه هذه المقالة هو تشغيل يُحرَّر فيه ملفّات المستودع المحلّي مباشرة. حوادث mojibake تقع عند «التحرير ثمّ الحفظ»، لذا الجوهر ليس أيّ مدخل تستخدم، بل كيف تقيّد مسار الكتابة إلى الملفّ.

AGENTS.md ملفّ Markdown تُكتَب فيه توجيهات دائمة للعمل في ذلك المستودع. لطريقة التحميل خصائص يستحقّ تذكّرها.

• الموضع ليس واحداً. تُقرأ إعدادات عامّة مثل ~/.codex/AGENTS.md في الدليل الرئيسي، وAGENTS.md في جهة المستودع معاً.
• تُوصَل بالترتيب من جذر المستودع نحو دليل العمل. أي أنّ AGENTS.md الموضوع في دليل فرعي يُوصَل لاحقاً، فيفوق توجيهات الأعلى قوّة.
• للحجم الإجمالي سقف. يُقطَع افتراضيّاً عند نحو 32 KiB، فإن «كتبت كلّ شيء احتياطاً» سقط الذيل. قواعد الترميز أأمن إن وُضعت قصيرة في الأعلى.

لهذه الثلاث، العملي أن تُكتَب اتفاقية الترميز قصيرة وفي المقدّمة في AGENTS.md بجذر المستودع. إن وُجدت اتفاقية كتابة أخرى في دليل فرعي، تفوز تلك.

flowchart TB
    accTitle: كيف يُحمَّل AGENTS.md
    accDescr: مخطّط يبيّن أنّ AGENTS.md يُقرأ من جهة المنزل وجهة المستودع معاً، ويُوصَل من الجذر نحو دليل العمل فيقوى الأدنى، ويُقطَع الحجم الإجمالي افتراضيّاً عند نحو 32KiB، لذا تُكتَب اتفاقية الترميز قصيرة في مقدّمة الجذر.
    b1["AGENTS.md جهة المنزل"] --> b3["وصل من الجذر نحو دليل العمل"]
    b2["AGENTS.md جهة المستودع"] --> b3
    b3 --> b4["الأدنى الموصول لاحقاً أقوى"]
    b3 -.-> b5["قطع افتراضي عند نحو 32KiB"]
    b4 --> b6["الاتفاقية قصيرة في مقدّمة الجذر"]
    b5 -.-> b6

الشكل 2: لـ AGENTS.md ترتيب وصل وسقف حجم، لذا تُوضَع الاتفاقية قصيرة في أعلى الجذر.

1. الخلاصة أوّلاً

الأكثر أثراً لتقليل حوادث mojibake لـ Codex في بيئة Windows هو تثبيت إجراء عمل الترميز أوّلاً.

القواعد الأكثر أثراً تقريباً هذه.

• للملفّات القائمة التي تحوي يابانية، افحص مرشّح الترميز ووجود BOM ورمز نهاية السطر قبل القراءة
• للملفّ المشتبه بـ mojibake، لا تحفظ حتى تثق بالتفسير
• للملفّات القائمة، أبقِ الترميز وBOM ونهاية السطر الأصليّة
• للملفّات الجديدة، قرّبها إلى UTF-8 وفق اتفاقية المستودع
• للكتابة، استخدم طرقاً تستطيع التصريح بالترميز فقط
• بعد الحفظ، أعد الفتح وتحقّق من أسطر يابانية تمثيلية

بصياغة قصيرة للتشغيل، تقريباً هذا.

• افحص قبل القراءة
• إن اشتبهت فاحظر الحفظ
• أبقِ القائم، وUTF-8 للجديد فقط
• احظر مسارات الكتابة الغامضة
• أخيراً أعد الفتح وتحقّق

flowchart TB
    accTitle: خمسة إجراءات تمنع حوادث الترميز
    accDescr: مخطّط يعرض بالترتيب الصياغة القصيرة للتشغيل: افحص قبل القراءة، إن اشتبهت فاحظر الحفظ، أبقِ القائم وUTF-8 للجديد فقط، احظر مسارات الكتابة الغامضة، أخيراً أعد الفتح وتحقّق.
    c1["افحص قبل القراءة"] --> c2["إن اشتبهت فاحظر الحفظ"]
    c2 --> c3["أبقِ القائم، وUTF-8 للجديد فقط"]
    c3 --> c4["احظر مسارات الكتابة الغامضة"]
    c4 --> c5["أخيراً أعد الفتح وتحقّق"]

الشكل 3: إجراء العمل المراد تثبيته يُختصَر في هذا التدفّق الخماسي.

في المقابل، التوجيه الخطر كهذا.

• «أصلح mojibake»
• «حوّل الكلّ إلى UTF-8»
• «أخرج CSV»
• «وافِق كيفما اتّفق»
• «احفظ مؤقّتاً وانظر»

كلّها لا تكتب عند أيّ مرحلة يجب على Codex أن يتوقّف. في مواجهة mojibake لا يكفي ما يُفعَل؛ يلزم التوجيه حتى أين يُوقَف الحفظ.

في المخطّط، يشير الخطّ المتّصل إلى علاقة قائمة دائماً، ويشير الخطّ المتقطّع إلى علاقة مشروطة (شروط قيامها مذكورة في شرح كلّ علاقة في الصفحة التفصيليّة). القائمة الكاملة للعلاقات (المجموع 22، مع الأدلّة ودرجة اليقين) وتعريفات المفاهيم الرئيسة مجمّعة في صفحة تفاصيل خريطة المعرفة (باليابانية). البيانات: JSON-LD / Turtle

2. لماذا تكثر حوادث mojibake على Windows

المشكلة الحقيقية ليست ضعف Codex في اليابانية، بل تعايش عدّة ترميزات وعدّة مسارات كتابة على أصول Windows.

في التشغيل هذا الاختلاط ليس نادراً.

• المصدر الأحدث وMarkdown بـ UTF-8
• CSV وTXT والسجلّات والإعدادات القديمة من عائلة CP932
• بعض المخرجات وما تولّده الأدوات من عائلة UTF-16
• مسار الحفظ متفرّق عبر المحرّر والـ shell ومخرجات أصلها Excel
• رموز نهاية السطر أيضاً LF وCRLF مختلطة

في هذه الحال إن أخطأ Codex التفسير مرّة واحدة، قد يمضي إلى التعديل التالي معتبراً نصّاً لم يقرأه «مقروءاً». وإن حُفِظ كما هو، تثبّت المشكلة هذه المرّة تلفاً في الملفّ نفسه لا مشكلة عرض.

لذلك مواجهة mojibake، في الجوهر، مسألة كيف تدير إجراءات الإدخال والإخراج.

flowchart TB
    accTitle: حتى تثبّت الحادثة تلفاً
    accDescr: مخطّط يبيّن أنّ Codex إن أخطأ التفسير مرّة واحدة على أصول تتعايش فيها عدّة ترميزات ومسارات كتابة، يمضي إلى التعديل التالي معتبراً نصّاً لم يقرأه مقروءاً، وعند الحفظ تثبّت المشكلة تلفاً في الملفّ نفسه لا مشكلة عرض.
    d1["تعايش ترميزات ومسارات كتابة متعدّدة"] --> d2["تفسير خاطئ لمرّة"]
    d2 --> d3["المضيّ إلى التعديل دون قراءة صحيحة"]
    d3 --> d4["الحفظ يثبّتها تلفاً"]
    d4 -.-> d5["جوهر العلاج إدارة إجراءات I/O"]

الشكل 4: تبدأ mojibake مشكلة عرض، وتثبّت تلفاً في لحظة الحفظ.

2.1 أربعة مصطلحات أوّلاً

نوحّد هنا كلمات تتكرّر لاحقاً.

المهمّ أنّ CP932 وUTF-8 لا يُكتَبان على الملفّ نفسه. ما دام لا BOM، لا يعلن الملفّ بنفسه «كيف يجب أن يُقرأ». لذلك يلزم الفحص قبل القراءة.

flowchart TB
    accTitle: الملفّ لا يعلن ترميزه
    accDescr: مخطّط يبيّن أنّ كون الملفّ CP932 أو UTF-8 غير مكتوب على الملفّ نفسه، وما دام لا BOM لا يعلن كيف يجب أن يُقرأ، لذا يلزم الفحص قبل القراءة.
    e1["محتوى الملفّ تسلسل بايتات فقط"] --> e2{"هل يوجد BOM؟"}
    e2 -->|"يوجد"| e3["يُعرَف أنّه من عائلة Unicode"]
    e2 -->|"لا يوجد"| e4["UTF-8 أو CP932 يُحكَم من المحتوى"]
    e4 --> e5["لذلك يلزم الفحص قبل القراءة"]

الشكل 5: بلا BOM لا يخبرك الملفّ كيف يُقرأ.

3. القواعد المراد تثبيتها لـ Codex أوّلاً

3.1 افحص مرشّح الترميز وBOM ونهاية السطر قبل القراءة

القاعدة الأولى هذه.

قبل قراءة ملفّ قائم يحوي يابانية، افحص مرشّح الترميز الحالي ووجود BOM ورمز نهاية السطر، وإن اشتبهت فلا تمضِ إلى تفسير المحتوى كما هو.

النقطة تحويل الأمر إلى «قبل قراءة النصّ، انظر أوّلاً افتراضات الملفّ».

كيف تفحص تحديداً

إن كتبت «افحص» فقط، يتذبذب أسلوب Codex والإنسان. طمر إجراء الفحص في التوجيه أثبت. ما يلي يعمل على Windows PowerShell 5.1 وPowerShell 7.

أوّلاً انظر البايتات الأولى ست عشريّاً. وجود BOM يُحسَم هنا.

$path  = 'C:\work\orders.csv'
$bytes = [System.IO.File]::ReadAllBytes($path)

# 先頭 16 バイトを 16 進で表示する
$head = $bytes[0..([Math]::Min(15, $bytes.Length - 1))]
($head | ForEach-Object { $_.ToString('X2') }) -join ' '

الكتل التالية تستخدم $path و$bytes المنشأين هنا كما هما. القراءة هكذا.

ثمّ عُدّ رموز نهاية السطر. «اختلاط LF وCRLF» يظهر هنا.

$crlf = 0; $loneLf = 0; $loneCr = 0
for ($i = 0; $i -lt $bytes.Length; $i++) {
    if ($bytes[$i] -eq 0x0A) {
        if ($i -gt 0 -and $bytes[$i - 1] -eq 0x0D) { $crlf++ } else { $loneLf++ }
    }
    elseif ($bytes[$i] -eq 0x0D -and ($i -eq $bytes.Length - 1 -or $bytes[$i + 1] -ne 0x0A)) {
        $loneCr++
    }
}
"CRLF=$crlf  LF=$loneLf  CR=$loneCr"

أخيراً ضيّق مرشّحي الترميز. عند غياب BOM، إمكان فكّ الترميز صارماً بوصفه UTF-8 أسرع مادّة حكم. UTF-8 يقيّد تسلسل البايتات بقوّة، لذا قراءة ملفّ CP932 صارماً بوصفه UTF-8 تفشل في المنتصف في العادة.

# الوسيط الثاني $true يعني «ارمِ استثناء إن كان تسلسل البايت غير صالح»
$strictUtf8 = New-Object System.Text.UTF8Encoding($false, $true)
try {
    $null = $strictUtf8.GetString($bytes)
    'فُكّ الترميز كـ UTF-8 بلا تناقض'
}
catch {
    'ليس UTF-8. جرِّب مرشّحين مثل CP932'
}

عند القراءة بجهة CP932، صرّح برقم صفحة الرموز.

# من PowerShell 6.2 يمكن تحديد رقم صفحة الرموز كما هو
Get-Content -Path $path -Encoding 932 -TotalCount 3

# Windows PowerShell 5.1 では Default がシステムの ANSI コードページ。日本語 Windows なら CP932 です
Get-Content -Path $path -Encoding Default -TotalCount 3

نجاح الفكّ الصارم وحده لا يُثبِت «UTF-8 قطعاً». ملفّ ASCII فقط يمرّ في كليهما. في النهاية اجعل التحقّق بالعين أنّ سطراً يابانيّاً تمثيليّاً مقروء.

flowchart TB
    accTitle: إجراء الفحص قبل القراءة
    accDescr: مخطّط يعرض الإجراء: انظر البايتات الأولى ست عشريّاً واحكم بوجود BOM، وعُدّ رموز نهاية السطر، وضيّق المرشّحين بفكّ UTF-8 الصارم، وأخيراً تحقّق بالعين أنّ سطراً يابانيّاً تمثيليّاً مقروء.
    f1["انظر البايتات الأولى ست عشريّاً"] --> f2["احكم بوجود BOM"]
    f2 --> f3["عُدّ رموز نهاية السطر"]
    f3 --> f4["ضيّق المرشّحين بفكّ UTF-8 الصارم"]
    f4 --> f5["تحقّق بالعين من سطر ياباني تمثيلي"]
    f4 -.-> f6["ASCII فقط يمرّ في كليهما"]

الشكل 6: الفحص قبل القراءة يتقدّم بترتيب البايت ثمّ نهاية السطر ثمّ الفكّ ثمّ العين.

3.2 لا تحفظ الملفّ المشتبه بـ mojibake بالتخمين

هذه مهمّة خصوصاً.

عند الاشتباه بـ mojibake، اجعل مرحلة التحقيق للقراءة فقط، واحظر الكتابة فوق الملفّ حتى تثق بالتفسير.

ينطبق على الإنسان أيضاً: لا تحفظ ملفّاً لم تقرأه. إن حفظت بـ «يبدو تالفاً قليلاً لكنّه على الأرجح هذا»، صارت تلك النسخة المؤكَّدة للحادثة.

3.3 أبقِ الملفّات القائمة، واجعل UTF-8 أساساً للجديد فقط

في سياق مواجهة mojibake، «وحّد الكلّ على UTF-8» أخطر ممّا يُتوقَّع.

قرار تقريب المستودع كلّه إلى UTF-8 في النهاية ممكن، لكنّه أأمن مهمّة مستقلّة تُتابَع مع الفرق ونطاق التأثير. في التعديل اليومي هذا التشغيل أثبت.

• عند تعديل ملفّ قائم، أبقِ الترميز الأصلي
• عند إضافة ملفّ جديد، أنشئه من عائلة UTF-8 وفق اتفاقية المستودع
• إن لزم تحويل ملفّ قائم، افصله عن تصحيح الوظيفة العادي

3.4 لا تجعل مسارات الكتابة الغامضة افتراضيّة

ما يزيد الحوادث على Windows هو «كتابة عابرة في الـ shell لأنّها مخرجات بسيطة».

• الإخراج كما هو بإعادة توجيه
• الحفظ كما هو بأمر مريح
• ترقية مولود مؤقّت كما هو إلى ملفّ إنتاج

هذه المسارات غالباً لا يُصرَّح فيها بالترميز، فتصير مرتع حوادث. لذلك أأمن أن تثبّت لـ Codex أيضاً اختيار وسيلة الكتابة.

«الترميز الافتراضي» يختلف حسب إصدار PowerShell

هنا تخطو حتماً إن لم تعرف. PowerShell يختلف ترميز الكتابة الافتراضي حسب الإصدار.

أي أنّ السكربت نفسه ينتج ملفّاً مختلفاً حسب التشغيل على 5.1 أو على 7. هذا ضيف دائم لـ «كان سليماً على جهاز التطوير، وتلف على خادم الميدان».

وإضافة في جهة 5.1: تحديد ترميز من عائلة Unicode يُرفق BOM حتماً. -Encoding UTF8 هو UTF-8 مع BOM.

لذلك صرّح بالكتابة في كلّ مرّة.

# この節だけで完結するように、変数を定義しておきます
$path    = 'C:\work\orders.csv'
$newPath = 'C:\work\orders-new.csv'
$lines   = @('顧客コード,顧客名', 'C0001,株式会社サンプル')

# 既存が CP932 なら CP932 のまま書き戻す（PowerShell 6.2 以降）
Set-Content -Path $path -Value $lines -Encoding 932

# Windows PowerShell 5.1 でシステムの ANSI コードページに合わせる
Set-Content -Path $path -Value $lines -Encoding Default

# 新規ファイルを BOM なし UTF-8 で作る（PowerShell 7）
Set-Content -Path $newPath -Value $lines -Encoding utf8NoBOM

إن أردت تقريب الافتراضي للجلسة كلّها، يمكن استخدام $PSDefaultParameterValues. لكن هذا إعداد لتلك الجلسة فقط، فدليل إجراءات يفترض «مكتوب في ملفّنا الشخصي» ينكسر في بيئة غيره.

$PSDefaultParameterValues['*:Encoding'] = 'utf8NoBOM'

أسلوب استخدام > بدل Out-File، من 5.1 فصاعداً، يستدعي Out-File داخليّاً فقط، فيحمل مشكلة الترميز الافتراضي نفسها. الأضمن حظر إعادة التوجيه واستخدام cmdlet أو .NET API يستطيع كتابة الترميز فقط.

flowchart TB
    accTitle: السكربت نفسه ينتج ملفّاً مختلفاً
    accDescr: مخطّط يبيّن أنّ PowerShell يختلف ترميز الكتابة الافتراضي حسب الإصدار، فالسكربت نفسه ينتج ملفّاً مختلفاً حسب التشغيل على 5.1 أو على 7، والأضمن حظر إعادة التوجيه واستخدام cmdlet أو .NET API يستطيع كتابة الترميز فقط.
    g0["السكربت نفسه"] --> g1["تشغيل على Windows PowerShell 5.1"]
    g0 --> g2["تشغيل على PowerShell 7"]
    g1 --> g3["ينتج ملفّاً بترميز مختلف"]
    g2 --> g3
    g3 -.-> g4["استخدم مساراً يستطيع التصريح بالترميز فقط"]

الشكل 7: الترميز الافتراضي يختلف حسب الإصدار، لذا صرّح بالكتابة في كلّ مرّة.

3.5 بعد الحفظ أعد الفتح وتحقّق من أسطر يابانية تمثيلية

«تمكّن الحفظ» و«لم يتلف» ليسا الشيء نفسه.

المهمّ إعادة قراءة أسطر يابانية تمثيلية بعد الحفظ والتحقّق من نقاط كهذه.

• هل دخل حرف الاستبدال U+FFFD
• هل زاد ? بشكل غير طبيعي
• هل صار الفرق ضخماً بـ BOM أو نهاية سطر فقط
• هل بقيت اليابانية التي لم تغيّرها العمل كما هي

3.6 عند ظهور علامة شذوذ، أبلغ قبل التصحيح

في حوادث الترميز، التوقّف والإبلاغ يصغّر الضرر أكثر من الإصرار على التصحيح.

مثلاً إن ظهرت علامات كهذه، أأمن معاملتها شذوذاً مؤقّتاً.

• زيادة U+FFFD
• زيادة ?
• تغيّر BOM غير متوقَّع
• فرق ضخم بنهاية سطر فقط
• تغيّر غير طبيعي كبير في الأسطر اليابانية وحدها

flowchart TB
    accTitle: عند علامة شذوذ توقّف وأبلغ
    accDescr: مخطّط يبيّن أنّ ظهور علامات مثل زيادة حرف الاستبدال U+FFFD أو ? أو تغيّر BOM غير متوقَّع أو فرق ضخم بنهاية سطر فقط يجعل التوقّف والإبلاغ يصغّر الضرر أكثر من الإصرار على التصحيح.
    h1["زيادة U+FFFD أو ?"] --> h4["عاملها شذوذاً مؤقّتاً"]
    h2["تغيّر BOM غير متوقَّع"] --> h4
    h3["فرق ضخم بنهاية سطر فقط"] --> h4
    h4 --> h5["توقّف وأبلغ قبل التصحيح"]

الشكل 8: عند ظهور علامة شذوذ، لا تجعلها تُصحَّح بل أوقف وأبلغ.

4. إن مرّرتها توجيهاً قصيراً

نسخة قصيرة تُرفَق بكلّ مهمّة تكفي بهذا القدر.

في هذا العمل تجنّب حوادث الترميز بأولوية قصوى.

- للملفّات القائمة التي تحوي يابانية، افحص مرشّح الترميز ووجود BOM ورمز نهاية السطر قبل القراءة
- للملفّ المشتبه بـ mojibake، لا تحفظ بالتخمين
- أبقِ الترميز / BOM / نهاية السطر الأصليّة للملفّات القائمة
- أنشئ الملفّات الجديدة من عائلة UTF-8 وفق اتفاقية المستودع
- استخدم طرق كتابة تستطيع التصريح بالترميز فقط
- بعد الحفظ أعد الفتح وتحقّق من أنّ الأسطر اليابانية التمثيلية لم تتلف
- إن زاد `U+FFFD` أو `?`، أو وقع حادث BOM / نهاية سطر، أو فرق ضخم، أبلغه شذوذاً

إن كانت الملفّات المستهدفة محدَّدة، إضافة هذا السطر تثبّت الأمر كثيراً.

الملفّات المستهدفة: <paths> / السلاسل التمثيلية: "<examples>"

تمرير سلسلة تمثيلية ذو أثر كبير. لأنّه يمنح Codex نقطة رصد ملموسة: «هذه اليابانية يجب ألّا تتلف».

flowchart TB
    accTitle: تمرير نقطة رصد بسلسلة تمثيلية
    accDescr: مخطّط يبيّن أنّ تمرير الملفّ المستهدف وسلسلة تمثيلية يجب ألّا تتلف يمنح Codex نقطة رصد ملموسة أنّ هذه اليابانية يجب ألّا تتلف، فيثبّت التوجيه كثيراً.
    i1["حدّد الملفّ المستهدف"] --> i3["امنح نقطة رصد ملموسة"]
    i2["سلسلة تمثيلية يجب ألّا تتلف"] --> i3
    i3 --> i4["يثبّت التوجيه كثيراً"]

الشكل 9: سطر الملفّ المستهدف والسلسلة التمثيلية يثبّت موضع التحقّق.

5. قالب يُستحسَن تثبيته في AGENTS.md

إن كنت ستكرّر التنبيه نفسه مرّات، فالأفضل وضعه في AGENTS.md. فيما يلي قالب أميل إلى العملي لمستودع يتعامل مع ملفّات يابانية على Windows.

# Text Encoding Rules

## Scope
This repository may contain Japanese text and mixed legacy encodings.
Avoid mojibake and accidental re-encoding above all else.

## Mandatory Rules
- Before reading or editing an existing text file that may contain Japanese, first determine:
  - likely encoding
  - BOM presence
  - newline style
- If mojibake is suspected, do not save the file until the encoding interpretation is credible.
- Preserve the original encoding, BOM, and newline style for existing files.
- Treat "convert to UTF-8" as a separate, explicit task.
- New files should follow repository convention. If there is no clear rule, prefer UTF-8 and state whether BOM is used.
- Do not use ambiguous write paths by default, such as shell redirection or convenience commands without explicit encoding control.
- After writing, reopen the file and verify representative Japanese lines.
- If any of the following appears, stop and report:
  - replacement characters
  - unexpected `?`
  - unintended BOM change
  - unintended newline conversion
  - whole-file diffs without a business reason

## Reporting Format
For each changed text file, report:
- path
- detected or preserved encoding
- BOM presence
- newline style
- how verification was performed
- whether representative Japanese text remained intact

حسن هذا القالب أنّه يثبّت كيف لا تتلف لا كيف تُحرَّر. وخصوصاً السطران:

• If mojibake is suspected, do not save ...
• Treat "convert to UTF-8" as a separate, explicit task.

ذو أثر كبير.

5.1 القالب الياباني

إن دارت مراجعة الفريق باليابانية، قد يسهل تشغيل AGENTS.md باليابانية أيضاً. المحتوى هو نفسه.

# 文字コードの取り扱い規約

## 適用範囲
このリポジトリには日本語テキストと、レガシーな文字コードのファイルが混在します。
文字化けと、意図しない再エンコードを、他の何よりも優先して避けてください。

## 必ず守ること
- 日本語を含む可能性がある既存テキストファイルは、読む前に次を確認する。
  - encoding の候補
  - BOM の有無
  - 改行コード
- 文字化けが疑われる間は、解釈に確信が持てるまでそのファイルを保存しない。
- 既存ファイルは、元の encoding、BOM、改行コードを維持する。
- 「UTF-8 に変換する」は、機能修正とは別の独立したタスクとして扱う。
- 新規ファイルはリポジトリ規約に従う。規約がなければ UTF-8 を選び、BOM の有無を明記する。
- encoding を明示できない書き込み経路を既定で使わない。
  シェルのリダイレクトや、encoding を指定できない便利コマンドが該当する。
- 書き込んだあとは開き直し、日本語の代表行が壊れていないことを確認する。
- 次のいずれかが出たら、修正しようとせず、いったん止めて報告する。
  - 置換文字 U+FFFD の増加
  - 想定していない `?` の増加
  - 意図しない BOM の変化
  - 意図しない改行コードの変換
  - 業務上の理由がないファイル全体の差分

## 報告のしかた
変更したテキストファイルごとに、次を報告する。
- パス
- 検出した、または維持した encoding
- BOM の有無
- 改行コード
- どうやって検証したか
- 日本語の代表文字列が無事だったか

يكفي أحد القالبين الإنكليزي أو الياباني. وضعهما معاً يستهلك ضعف الحجم، فباعتبار سقف حجم تحميل AGENTS.md أأمن حسم الأمر لأحدهما.

6. توجيه مرفوض وتوجيه مقبول

في مواجهة mojibake، درجة تفصيل التوجيه تؤثّر في النتيجة كثيراً.

النقطة كتابة الفحص قبل التحرّك والتحقّق بعد الحفظ حتماً.

flowchart TB
    accTitle: قالب تحويل التوجيه المرفوض إلى مقبول
    accDescr: مخطّط يبيّن أنّ توجيهاً مثل «أصلح mojibake» لا يكتب أين يجب التوقّف، لذا تُضاف الفحص قبل التحرّك والتحقّق بعد الحفظ ليصير توجيهاً يشمل أين يُوقَف الحفظ.
    j1["«أصلح mojibake»"] --> j2["موضع التوقّف غير مكتوب"]
    j2 -.->|"أضِف"| j3["فحص قبل التحرّك"]
    j2 -.->|"أضِف"| j4["تحقّق بعد الحفظ"]
    j3 --> j5["توجيه يشمل أين يتوقّف"]
    j4 --> j5

الشكل 10: الفرق عن التوجيه المرفوض وجود الفحص والتحقّق وموضع التوقّف.

7. قائمة تحقّق عند المراجعة

بعد تشغيل Codex، تثبيت نقاط يراها الإنسان أيضاً يزيد الاستقرار.

• هل أُبلغ تعامل الترميز / BOM / نهاية السطر لكلّ ملفّ معدَّل
• هل تغيّرت الأسطر اليابانية وحدها تغيّراً كبيراً غير طبيعي
• هل خرج فرق ضخم بنهاية سطر فقط
• هل زاد U+FFFD أو ?
• هل يوجد فرق كلّي لا علاقة له بتغيير العمل
• هل انهار ترتيب الأعمدة أو علامات الاقتباس في CSV أو السجلّات

المهمّ في مواجهة mojibake إيقاف الفرق المريب مبكّراً أكثر من زيادة الفرق الناجح.

8. الخلاصة

عند تشغيل Codex على ملفّات يابانية في بيئة Windows، ما يؤثّر أوّلاً ليس إكمال جهاز الحاسوب تماماً، بل التصريح لـ Codex بإجراء عمل الترميز.

ما يستحقّ التذكّر خصوصاً خمس نقاط.

• افحص الترميز / BOM / نهاية السطر قبل القراءة
• إن اشتبهت بـ mojibake، لا تحفظ بالتخمين
• أبقِ الملفّات القائمة، وقرّب الجديد فقط إلى عائلة UTF-8
• احظر مسارات الكتابة الغامضة
• بعد الحفظ أعد الفتح وتحقّق من أسطر يابانية تمثيلية

ثمّ إن كنت ستقول ذلك في كلّ مرّة، ضعه في AGENTS.md. هذا الأكثر عمليّة.

جوهر مواجهة mojibake ليس طلب «تعامل مع اليابانية بشكل صحيح»، بل توثيق شروط جواز الحفظ وشروط وجوب التوقّف. إن كُتب ذلك، يصير Codex أسهل كثيراً في التعامل حتى على Windows.

flowchart TB
    accTitle: الجوهر توثيق الشروط
    accDescr: مخطّط يبيّن أنّ جوهر مواجهة mojibake ليس طلب التعامل الصحيح مع اليابانية، بل توثيق شروط جواز الحفظ وشروط وجوب التوقّف.
    k1["طلب «تعامل مع اليابانية بشكل صحيح»"] -.-> k2["هذا ليس الجوهر"]
    k3["توثيق شروط جواز الحفظ"] --> k5["يصير Codex أسهل حتى على Windows"]
    k4["توثيق شروط وجوب التوقّف"] --> k5

الشكل 11: الجوهر ليس أسلوب الطلب بل توثيق شروط الحفظ والتوقّف.

9. روابط مرجعية

• OpenAI Codex docs, Best practices
• OpenAI Codex docs, Custom instructions with AGENTS.md
• OpenAI Codex docs, Windows
• Microsoft Learn, about_Character_Encoding
• Microsoft Learn, Code Page Identifiers
• Microsoft Learn, Byte order mark

مقالات ذات صلة

أحدث المقالات التي تشترك في نفس الوسوم. عمّق فهمك بمواضيع مرتبطة.

أين يتصل هذا الموضوع

ترتبط هذه المقالة بشكل طبيعي بصفحات الخدمات التالية.

الأسئلة الشائعة

أسئلة شائعة حول موضوع هذه المقالة.

لماذا يحدث mojibake لليابانية عند استخدام Codex على Windows؟

السبب الحقيقي ليس ضعف Codex في اليابانية، بل تعايش عدّة ترميزات على أصول Windows مثل UTF-8 وCP932 وUTF-16، مع عدّة مسارات كتابة. في هذه الحال إن أخطأ Codex التفسير مرّة واحدة، قد يمضي إلى التعديل التالي معتبراً نصّاً لم يقرأه «مقروءاً». وإن حُفِظ كما هو تثبّت المشكلة تلفاً في الملفّ نفسه لا مشكلة عرض. لذلك مواجهة mojibake، في الجوهر، مسألة كيف تدير إجراءات الإدخال والإخراج.

أيّ توجيه يمنع mojibake مع Codex؟

تثبيت إجراء عمل الترميز أوّلاً هو الأكثر أثراً. تحديداً خمس نقاط: جعل Codex يفحص مرشّح الترميز ووجود BOM ورمز نهاية السطر قبل قراءة ملفّ قائم يحوي يابانية، ومنعه من الحفظ ما دام الملفّ مشتبهاً بـ mojibake حتى يثق بالتفسير، والإبقاء على الترميز الأصلي للملفّات القائمة وجعل الجديد فقط UTF-8، واستخدام طرق كتابة تستطيع التصريح بالترميز فقط، وإعادة فتح الملفّ بعد الحفظ والتحقّق من أسطر يابانية تمثيلية. إن مرّرت الملفّات المستهدفة و«سلاسل تمثيلية يجب ألّا تتلف»، يزداد الاستقرار.

ألا يجوز التوجيه بـ «أصلح mojibake» أو «حوّل الكلّ إلى UTF-8»؟

كلاهما توجيه خطر. لم يُكتَب عند أيّ مرحلة يجب على Codex أن يوقف الحفظ، فيسهل أن يُحفَظ بالتخمين وتتأكّد الحادثة. «حوّل الكلّ إلى UTF-8» أخطر خصوصاً؛ في تعديل الملفّات القائمة أبقِ الترميز وBOM ونهاية السطر الأصليّة، واجعل توحيد المستودع على UTF-8 مهمّة مستقلّة تُتابَع مع الفرق ونطاق التأثير. بدلاً من ذلك وجّه بما يشمل الفحص قبل التحرّك والتحقّق بعد الحفظ، مثل «افصل التلف عن مشكلة العرض، ولا تحفظ بالتخمين».

هل يُستحسَن كتابة قواعد الترميز في AGENTS.md؟

إن كنت ستكرّر التنبيه نفسه في كلّ مهمّة، فالتثبيت الدائم في AGENTS.md أكثر أثراً. اكتب مجتمعةً: فحص الترميز وBOM ونهاية السطر قبل القراءة، حظر الحفظ ما دام mojibake مشتبهاً، الإبقاء على الملفّات القائمة، جعل التحويل إلى UTF-8 مهمّة مستقلّة، حظر مسارات الكتابة الغامضة، التحقّق بإعادة القراءة بعد الحفظ، وقاعدة التوقّف والإبلاغ عند الشذوذ. وإن ثبّت أيضاً صيغة تُبلغ لكلّ ملفّ معدَّل الترميز وBOM ونهاية السطر وطريقة التحقّق، يستقرّ فحص جهة المراجعة أيضاً.

الملف الشخصي للمؤلف

صفحة الملف الشخصي لمؤلف المقالة.

غو كومورا

مؤسّس شركة كومورا سوفت ذ.م.م.

يركّز على تطوير برامج ويندوز، والاستشارات التقنية، والتحقيق في الأخطاء، ويتميّز في المشاريع التي تبقى فيها الأصول القديمة ناشطة، وفي تشخيص الأعطال التي يصعب تحديد سببها.