Skip to content

استعادة البنية: إرجاع النص الخالص إلى Markdown ​

💡 خلاصة بسطر واحد: استخدم Jev لإتمام تحويل النص الخالص إلى Markdown — احكم على كسر الأسطر وأنواع الكتل، ودَع الشيفرة تُجري الوصل وتضيف علامات Markdown، ولا تدع ترتيب التنسيق يتحول بالمناسبة إلى إعادة كتابة للمتن.

ماذا ستستطيع أن تفعل بعد إتمام الدرس ​

  • العثور على الجمل المفصولة بكسر أسطر قسري داخل النص الخالص.
  • شرح السبب في أن هذا المثال يحتاج طلبتين: وصل الأسطر أولًا ثم التصنيف.
  • التمييز بين المتن والعناوين والقوائم والاقتباس والشيفرة وكتل التنبيه.
  • قبول النتيجة عبر المطابقة مع النص الأصلي وفحص الثقة المنخفضة، لا بمجرد النظر إلى جمال التنسيق.

لماذا نستخدم Jev بدلًا من ترك نموذج توليدي يعيد الكتابة مباشرة؟ ​

للمسارين هدفان مختلفان. يناقش هذا الدرس مثال autoformat الرسمي فقط، ولا يصنع بناء عليه ترتيبًا لأداء جميع النماذج.

بند الفحصمسار التوليد المباشر لـ Markdownمسار Jev في هذا المثال
مصدر المتن❌ يلزم فحص ما إذا كانت عملية التوليد قد غيّرت الصياغة✅ المصيّر يستخدم كتل النص المدخلة
مهمة النموذج❌ يقرر البنية ويُخرج النص في آن واحد✅ يجيب عن أسئلة ضيقة مثل كسر الأسطر وأنواع الكتل
توليد التنسيق❌ يُخرج النموذج Markdown✅ الشيفرة تضيف العلامات
اللايقين❌ يلزم تصميم طريقة فحص منفصلة✅ تُحفظ معلومات الاحتمال من نتائج الحكم

هذا ليس تحويلًا بلا فقدان بايتًا ببايت. المعالجة المسبقة الرسمية ترتب المسافات وتزيل الفراغات من بداية الأسطر ونهايتها، وتضيف مسافة عند وصل الأسطر؛ كما تضيف علامات Markdown جديدة عند التصيير.

معضلتك الآن ​

البريد المنسوخ حافظ على كسر الأسطر لكنه فقد العناوين والرموز النقطية. دمج جميع الأسطر المتجاورة مباشرة سيدفع القائمة إلى داخل الجملة السابقة؛ والاحتفاظ بكل سطر على حدة سيفتت فقرة طبيعية واحدة.

قلّص المشكلة أولًا: هل هذا السطر استمرار لجملة انقطعت في منتصف السطر السابق؟ هذا أقرب إلى القرار الذي ستتخذه فعلًا من الحكم على "هل هما الفقرة نفسها".

متى تستخدم هذه الحيلة ​

تناسب النصوص الخالصة التي ما يزال متنها موجودًا وفقدت علامات البنية. العرض الرسمي هو مذكرة ترحيل نظام بناء.

ليست أداة OCR ولا تصحيحًا للوقائع ولا إكمالًا للمحتوى. إذا كان المدخل نفسه ناقص الحروف أو مضطرب الترتيب أو تالفًا في مسافات بادئة للشيفرة، فينبغي أولًا الاحتفاظ بالأصل وترتيب فحص بشري، ولا يمكن الوعد باستعادة قصد المؤلف تلقائيًا.

🎒 التحضير قبل البدء ​

افهم أولًا نوع السؤال Choice و نوع السؤال Noul. شيفرة هذا الدرس مأخوذة حرفيًا من مثال Structure recovery الرسمي، ونسخها بالترتيب كما هي يكفي لتشغيلها.

أمر التثبيت الرسمي (cooksafe هي مكتبة الأدوات المرافقة الرسمية، وتوفر JsonCache الذاكرة المؤقتة ومساعدات روابط Playground المستخدمة في هذا الدرس):

bash
pip install ipython 'cooksafe>=0.2.0,<0.3.0'

نزّل الذاكرة المؤقتة من دليل مثال autoformat الرسمي إلى الدليل الذي تشغّل فيه السكربتات (إعادة تشغيل الأرقام الرسمية المسجلة تعتمد عليها بالكامل):

bash
curl -sL -o json_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/autoformat/json_cache.json

الشيفرة الرسمية تبني العميل باستخدام متغير البيئة TYPESAFE_API_KEY، فلا تكتب مفتاحًا حقيقيًا في الملاحظات أو المقالات؛ عند إعادة تشغيل الذاكرة المؤقتة فقط يكفي تعيين قيمة نائبة (انظر الخطوة 1). تستورد الشيفرة أيضًا وظائف العرض من IPython (تُستخدم عند توليد رابط Playground في نهاية المثال الرسمي)، وجميع خطوات هذا الدرس تعمل في سكربت Python عادي. إذا لم تضع ملف الذاكرة المؤقتة فستكون جميع الطلبات فورية وتتطلب اعتمادات صالحة.

الذاكرة المؤقتة لا تعني تشغيل أي مدخل مجانًا

الذاكرة المؤقتة الرسمية مخصصة لإعادة تشغيل استدعاءات المثال المطابقة. بعد تغيير المدخلات أو الأسئلة، لا تفترض استمرار الإصابة، ولا تسمِّ إعادة تشغيل ذاكرة مؤقتة واحدة نتيجة قياس فعلية لنموذج جديد. هذا الدرس لم يُجرِ أي استدعاءات فورية مدفوعة.

اتبع خطواتي ​

لنحدد أولًا طريقة التشغيل: أنشئ autoformat.py، والصق كتلة الشيفرة في كل خطوة تالية بالترتيب في الملف نفسه، وشغّل python autoformat.py مرة بعد إتمام كل خطوة. الشيفرة مأخوذة حرفيًا من المثال الرسمي، والتعديل الوحيد هو تعريف صيغة السؤال المقارن من الملحق الرسمي naive_join_question مسبقًا (سيستخدمها التجريب المقارن في الخطوة 3). عندما يكون json_cache.json في مكانه، تصيب جميع استدعاءات هذا الدرس الذاكرة المؤقتة وتعيد تشغيل الأجوبة وأرقام زمن الاستجابة المسجلة رسميًا حرفيًا، دون إرسال أي طلبات حقيقية.

الخطوة 1: تجهيز النص الأصلي وتحديد حدود تحويل النص الخالص إلى Markdown ​

لماذا: تثبيت الأصل أولًا هو ما يتيح لك معرفة ما إذا كنت في النهاية تستعيد التنسيق أم غيّرت المحتوى خلسة.

الصق شيفرة Setup الرسمية — العميل والذاكرة المؤقتة وإصدار النموذج:

python
import os
import re
import urllib.request
from pathlib import Path
from time import perf_counter

from cooksafe import JsonCache, make_playground_link
from IPython.display import Markdown, display
from typesafe_sdk import Choice, Noul, NoulCriteria, TypeSafeClient

TYPESAFE_MODEL = "jev-1.12"
client = TypeSafeClient(api_key=os.environ["TYPESAFE_API_KEY"], timeout=120.0)
json_cache = JsonCache(Path("json_cache.json"))

os.environ["TYPESAFE_API_KEY"] يرمي خطأ مباشرة إذا لم تُضبط المتغيرات. عند إعادة تشغيل الذاكرة المؤقتة فقط يكفي تعيين قيمة نائبة، مثل export TYPESAFE_API_KEY=cache-only — إصابة الذاكرة المؤقتة لا ترسل طلبات حقيقية.

ثم الصق شيفرة تنزيل النص الأصلي رسميًا (@json_cache تجعل هذا التنزيل قابلًا لإعادة التشغيل أيضًا):

python
DOCUMENT_URL = (
    "https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/autoformat/build-memo.txt"
)


@json_cache
def fetch_document(url: str) -> str:
    request = urllib.request.Request(url, headers={"User-Agent": "typesafe-cookbook/1.0"})
    with urllib.request.urlopen(request) as response:
        return response.read().decode()


RAW = fetch_document(DOCUMENT_URL)
print(RAW[:560])

شغّل python autoformat.py.

ينبغي أن ترى: بداية مذكرة بلا علامات عناوين أو قوائم في Markdown، وليست مقالًا منسقًا مسبقًا:

text
Migration to the new build system

Hi everyone, quick heads up about the build system migration that is
happening next week. We have been running the new pipeline in shadow
mode for three weeks and the results look solid, so it is time to
make the switch for real.

يوجد أيضًا لاحقًا: عنوان فرعي What changes for you، وسطر منفرد هو bun run build، وقائمتان بلا رموز، وفقرة تحذير بلا أي علامات — علامات العناوين والقوائم ضاعت جميعها، لكن الأسطر الفارغة ما تزال موجودة (الخطوة 2 ستستخدم هذا الدليل تحديدًا).

في التمرين الأول لا تستبدل المدخلات ولا تعدّل قواعد التصنيف، بل سر أولًا في المثال المنشور حتى النهاية. جميع الأحكام اللاحقة ستدور حول هذا النص الأصلي build-memo.txt.

الخطوة 2: الاحتفاظ بدليل الأسطر الفارغة وفحص كسر الأسطر ​

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

الصق شيفرة to_lines الرسمية وترقيم الأسطر. إنها ترتب المسافات، وتحتفظ بعلامة وجود سطر فارغ بين النصوص المتجاورة أو عدمه، وتخصص أرقامًا تبدأ بـ L للأسطر غير الفارغة:

python
def to_lines(text: str) -> list[dict]:
    lines, gap = [], False
    for raw in text.split("\n"):
        stripped = re.sub(r"[\t ]+", " ", raw).strip()
        if not stripped:
            gap = bool(lines)  # a leading blank is not a break
            continue
        lines.append({"text": stripped, "gap": gap})
        gap = False
    return lines


def tag(items: list[dict], prefix: str) -> str:
    return "\n".join(
        f"{chr(10) if item['gap'] else ''}{prefix}{i:03d}| {item['text']}"
        for i, item in enumerate(items)
    )


def line_id(i: int) -> str:
    return f"L{i:03d}"


def block_id(i: int) -> str:
    return f"B{i:03d}"


LINES = to_lines(RAW)
print(f"{len(LINES)} non-blank lines. The model sees, e.g.:")
print("\n".join(tag(LINES, "L").splitlines()[19:24]))

شغّل.

ينبغي أن ترى (مخرجات المثال الرسمي):

text
28 non-blank lines. The model sees, e.g.:
L013| The cutover touches three teams, so check whether you are on this
L014| list before you plan anything for Monday:
L015| The platform team
L016| The web client team
L017| Whoever still owns the release tooling

المثال الرسمي فيه 28 سطرًا غير فارغ — هذا مجرد نقطة تدقيق لهذا المدخل، وليس عددًا يجب أن يبلغه مستندك. ما يقرأه النموذج هو نص مرقّم بـ L، والأسئلة والأجوبة تشير إلى الأسطر بالأرقام.

الخطوة 3: استخدام Noul للحكم على ما إذا كانت الجملة مستمرة ​

لماذا: استعادة الجمل المفصولة بكسر أسطر قسري أولًا هي ما يجعل لتصنيف الكتل لاحقًا مدخلات صحيحة.

الصق شيفرة بناء الأسئلة من Pass 1 الرسمي. كل زوج من الأسطر المتجاورة غير المفصولة بسطر فارغ يقابله سؤال Noul واحد، وتوضع هذه الأسئلة في الطلب نفسه؛ naive_join_question هي صيغة السؤال المقارن من الملحق الرسمي، وسيستخدمها التجريب المقارن في نهاية هذه الخطوة:

python
def join_question(i: int) -> Noul:
    return Noul(
        instructions=f"Does line {line_id(i)} pick up mid-sentence, continuing a sentence left unfinished at the end of line {line_id(i - 1)}?",
        criteria=NoulCriteria(
            true="The line starts in the middle of a sentence that began on the previous line - the line break tore the sentence apart",
            false="The line begins a new sentence, item, heading, or thought of its own",
        ),
    )


def naive_join_question(i: int) -> Noul:
    return Noul(
        instructions=f"Are lines {line_id(i - 1)} and {line_id(i)} part of the same paragraph?",
        criteria=NoulCriteria(
            true="The two lines belong to the same paragraph of running text",
            false="The two lines belong to different paragraphs or different pieces of content",
        ),
    )

الصق شيفرة الطلب ووصل الأسطر الرسمية — stitch() تضع جميع أزواج الأسطر في طلب واحد، و merge() تصل الأسطر المتتابعة إلى كتل وفق العتبة:

python
@json_cache
def stitch(wording: str = "mid-sentence") -> dict:
    make = join_question if wording == "mid-sentence" else naive_join_question
    questions = {line_id(i): make(i) for i in range(1, len(LINES)) if not LINES[i]["gap"]}
    started = perf_counter()
    response = client.system_one(
        state=tag(LINES, "L"), questions=questions, model=TYPESAFE_MODEL
    )
    return {
        "joins": [
            response.answers[line_id(i)].noul if line_id(i) in response.answers else 0.0
            for i in range(len(LINES))
        ],
        "seconds": round(perf_counter() - started, 2),
        "usage": [response.usage.input_tokens, response.usage.output_tokens],
    }


result = stitch()
print(f"{sum(1 for l in LINES if not l['gap']) - 1} pair questions, one request, "
      f"{result['seconds']}s")
python
JOIN_AFTER_DANGLING, JOIN_AFTER_TERMINAL = 0.2, 0.5


def ends_terminal(text: str) -> bool:
    return re.search(r'[.!?:;…]["\')\]]*$', text) is not None


def merge(joins: list[float]) -> list[dict]:
    blocks = []
    for i, line in enumerate(LINES):
        bar = (
            JOIN_AFTER_TERMINAL
            if i and ends_terminal(LINES[i - 1]["text"])
            else JOIN_AFTER_DANGLING
        )
        if blocks and not line["gap"] and joins[i] >= bar:
            blocks[-1]["text"] += " " + line["text"]
            blocks[-1]["lines"].append(i)
        else:
            blocks.append({"text": line["text"], "lines": [i], "gap": line["gap"]})
    return blocks


blocks = merge(result["joins"])
healed = len(LINES) - len(blocks)
print(f"{len(LINES)} lines -> {len(blocks)} blocks ({healed} line breaks healed)")
for i, block in enumerate(blocks):
    n = len(block["lines"])
    print(f"{block_id(i)}  {n} line{'s' if n > 1 else ' '}  {block['text'][:62]}")

شغّل.

ينبغي أن ترى (المخرجات الرسمية المسجلة، مقتطفات؛ أرقام زمن الاستجابة عند إعادة تشغيل الذاكرة المؤقتة تأتي أيضًا من التسجيل):

text
16 pair questions, one request, 0.32s
28 lines -> 17 blocks (11 line breaks healed)
B000  1 line   Migration to the new build system
B001  4 lines  Hi everyone, quick heads up about the build system migration t
B002  1 line   What changes for you
B003  3 lines  The old make targets keep working until the end of the month. 
B004  1 line   bun run build
……
B014  3 lines  If the doctor script reports a red result on the toolchain che
B015  2 lines  As Dana put it in the kickoff, "a migration nobody notices is 
B016  1 line   Thanks, and shout if anything looks off.

مثال الذاكرة المؤقتة الرسمي يجمع 28 سطرًا في 17 كتلة. مخرجات الطلبات الفورية لا تُعهد بأن تكون مطابقة تمامًا للذاكرة المؤقتة؛ عند وجود تباين، تحقق أولًا من المدخلات وصيغة الأسئلة وطريقة استخدام الذاكرة المؤقتة، ولا تُغيّر الأرقام المتوقعة مباشرة.

لماذا نحتاج هنا قواعد برمجية أيضًا

منطق الدمج الرسمي يميّز ما إذا كان السطر السابق ينتهي بعلامة ترقيم نهائية، ويستخدم عتبات مختلفة (إذا لم يكن للسطر السابق علامة ترقيم نهائية تُستخدم 0.2، وإذا وُجدت ترتفع إلى 0.5)؛ لا يكفي النظر إلى «ترابط المحتوى» لوصل سطرين. هذه العتبات هي خيار ذلك المثال، وليست القيم المثلى العامة لجميع اللغات والمستندات.

تجربة مقارنة: لا تستبدل السؤال بـ «هل ينتميان إلى نفس الفقرة؟». الملحق الرسمي أعاد تشغيل دمج الأسطر باستخدام naive_join_question — بصياغة سؤال واسعة، حصلت عناصر القائمة ذات الموضوع نفسه على 0.77–0.91، ودُمجت القائمة في الجملة التمهيدية، وتقلّصت كتل 17 إلى 12 كتلة:

python
naive = stitch("same-paragraph")
print(f"{'':14}{'mid-sentence':>13}{'same paragraph':>16}")
for i in (15, 16, 17, 20, 21):
    print(f"{line_id(i)}{'':2}{LINES[i]['text'][:36]:<38}"
          f"{result['joins'][i]:>7.2f}{naive['joins'][i]:>13.2f}")
print(f"\nblocks after merge: {len(blocks)} (mid-sentence) vs "
      f"{len(merge(naive['joins']))} (same paragraph)")
text
               mid-sentence  same paragraph
L015  The platform team                        0.22         0.77
L016  The web client team                      0.11         0.81
L017  Whoever still owns the release tooli     0.12         0.78
L020  Delete the old build cache directory     0.08         0.88
L021  Run the doctor script and fix anythi     0.05         0.91

blocks after merge: 17 (mid-sentence) vs 12 (same paragraph)

«هل هما نفس الفقرة؟» يسأل عن استمرارية الموضوع، بينما «هل هي جملة تلي السطر السابق؟» يسأل عن النص نفسه. عندما يكون الحكم سيُغذّى إلى عتبة، يجب أن تسمّي الصياغة أضيق حقيقة ممكنة — هنا فرق الصياغة هو الفرق بين 17 كتلة و12 كتلة.

الخطوة 4: تصنيف الكتل المتكوّنة باستخدام Choice ​

السبب: الكتل لا توجد إلا بعد ظهور نتيجة دمج الأسطر، لذا لا يمكن دمج التصنيف مع التركيب الأول في نفس الطلب.

الصق معايير التصنيف من المرحلة الرسمية Pass 2. أنواع الكتل تشمل heading وparagraph وlist_item وquote وcode وcallout؛ الشرح الرسمي يقول إن هذه القواميس الثلاثة (مع حكم نعم/لا لسؤال الخطوة) هي المواصفة الكاملة للمصنّف — لتكييفه مع مستنداتك، ما تعدّله هو هذه الأوصاف:

python
TYPE_CRITERIA = {
    "heading": "A short label or title that names the document or the section that follows it - not a full sentence of content",
    "paragraph": "Running prose: one or more complete sentences of explanatory or narrative text",
    "list_item": "One entry in a list of parallel items - an ingredient, a feature, a task, an attendee; reads as one of several sibling entries",
    "quote": "Words attributed to a person or source - quoted speech, a citation, an excerpt someone else wrote",
    "code": "Computer code, a shell command, terminal output, or a config snippet meant to be read verbatim",
    "callout": "A warning, tip, or important note that interrupts the flow to flag something the reader must not miss",
}
HLEVEL_CRITERIA = {
    "title": "The title of the whole document",
    "section": "A major section heading within the document",
    "subsection": "A minor heading nested under a section",
}
CALLOUT_CRITERIA = {
    "note": "Neutral extra information the reader should be aware of",
    "tip": "A helpful suggestion or shortcut that makes things easier",
    "warning": "A caution about something that can go wrong or cause harm",
}

الصق كود بناء الأسئلة الرسمي. نفس طلب التصنيف يسأل مسبقًا أيضًا عن مستوى العنوان، وعن ترتيب الخطوات في القائمة، وعن فئة كتلة التنبيه — النوع غير معروف مسبقًا، وانتظاره يعني جولة ثالثة، لذا تُسأل الأسئلة المساعدة أولًا؛ العارض يعتمد فقط على الإجابات المساعدة المتعلقة بنوع الكتلة النهائي، ولا يعتبر كل الأحكام المساعدة وسومًا صالحة:

python
HEADING_MAX_CHARS = 90  # longer blocks can't render as headings, so don't ask


def classify_questions(texts: list[str]) -> dict:
    questions = {}
    for i, text in enumerate(texts):
        bid = block_id(i)
        questions[f"type_{bid}"] = Choice(
            instructions=f"What kind of content is block {bid}?", criteria=TYPE_CRITERIA
        )
        if len(text) <= HEADING_MAX_CHARS:
            questions[f"hlevel_{bid}"] = Choice(
                instructions=f"As a heading, what level would block {bid} occupy in this document's structure?",
                criteria=HLEVEL_CRITERIA,
            )
        questions[f"step_{bid}"] = Noul(
            instructions=f"Is block {bid} an instruction in a sequence where the order of the items matters?",
            criteria=NoulCriteria(
                true="It is one step of a procedure - the items around it must happen in order",
                false="Order is irrelevant - it is a loose collection, or not a list item at all",
            ),
        )
        questions[f"callout_{bid}"] = Choice(
            instructions=f"What kind of aside is block {bid}?", criteria=CALLOUT_CRITERIA
        )
    return questions

الصق كود طلب التصنيف والطباعة الرسمي:

python
@json_cache
def classify(texts: list[str], gaps: list[bool]) -> dict:
    tagged = tag([{"text": t, "gap": g} for t, g in zip(texts, gaps)], "B")
    questions = classify_questions(texts)
    started = perf_counter()
    response = client.system_one(state=tagged, questions=questions, model=TYPESAFE_MODEL)
    judgments = []
    for i in range(len(texts)):
        bid = block_id(i)
        type_answer = response.answers[f"type_{bid}"]
        hlevel = response.answers.get(f"hlevel_{bid}")
        judgments.append(
            {
                "type": type_answer.choice,
                "confidence": type_answer.confidence,
                "probabilities": type_answer.probabilities,
                "hlevel": hlevel.choice if hlevel else "section",
                "step": response.answers[f"step_{bid}"].noul,
                "callout": response.answers[f"callout_{bid}"].choice,
            }
        )
    return {
        "judgments": judgments,
        "n_questions": len(questions),
        "seconds": round(perf_counter() - started, 2),
        "usage": [response.usage.input_tokens, response.usage.output_tokens],
    }


classified = classify([b["text"] for b in blocks], [b["gap"] for b in blocks])
for block, judgment in zip(blocks, classified["judgments"]):
    block.update(judgment)
print(f"{classified['n_questions']} questions about {len(blocks)} blocks, one request, "
      f"{classified['seconds']}s\n")
print(f"{'block':<6}{'type':<11}{'conf':<6}{'companion used':<18}text")
for i, b in enumerate(blocks):
    companion = {
        "heading": f"level={b['hlevel']}",
        "list_item": f"step={b['step']:.2f}",
        "callout": f"kind={b['callout']}",
    }.get(b["type"], "-")
    print(f"{block_id(i):<6}{b['type']:<11}{b['confidence']:.2f}  {companion:<18}"
          f"{b['text'][:46]}")

شغّل.

يجب أن ترى (مخرجات مسجّلة رسميًا، مقتطفات):

text
62 questions about 17 blocks, one request, 0.51s

block type       conf  companion used    text
B000  heading    0.99  level=title       Migration to the new build system
B001  paragraph  0.98  -                 Hi everyone, quick heads up about the build sy
B002  heading    0.75  level=section     What changes for you
B003  paragraph  0.89  -                 The old make targets keep working until the en
B004  code       1.00  -                 bun run build
B005  paragraph  0.90  -                 Generated artifacts no longer need to be commi
……
B014  callout    0.65  kind=warning      If the doctor script reports a red result on t
B015  quote      0.99  -                 As Dana put it in the kickoff, "a migration no
B016  paragraph  0.92  -                 Thanks, and shout if anything looks off.

كل كتلة لها نوع وسجل الأحكام المقابلة، وكتل العناوين توفر المستوى، وكتل القوائم توفر حكم الترتيب. لاحظ احتمالات step في القائمتين: بنود المهام الثلاثة عند 0.86–0.90 (ستُعرض في الخطوة 5 كقائمة مرقّمة)، وبنود قائمة الفريق الثلاثة عند 0.12–0.16 (تُعرض كقائمة نقطية). لا تكرر استدعاء API لمحاولة إعادة إنتاج أرقام التأخير الواردة في المستند.

الخطوة 5: عرض Markdown ومقارنته بالنص الأصلي ​

السبب: صحة الحكم لا تعني أن العرض النهائي يلبي احتياجاتك بالضرورة، بل يجب أيضًا فحص العرض والمحتوى.

الصق كود العرض الرسمي. to_markdown(blocks) يجمع عناصر القائمة المتتالية في مجموعات، فإذا بلغ متوسط احتمال step داخل المجموعة 0.5 تُستخدم الترقيم، وإلا النقاط، ويضيف الوسوم للعناوين والكود والاقتباسات وكتل التنبيه (يحتوي الكود على سلاسل بثلاث علامات اقتباس خلفية، لذا تُحاط كتلة الكود هذه بسياج من أربع علامات اقتباس خلفية):

python
STEP_THRESHOLD = 0.5
HEADING_MARK = {"title": "#", "section": "##", "subsection": "###"}
CALLOUT_MARK = {"note": "NOTE", "tip": "TIP", "warning": "WARNING"}


def to_markdown(blocks: list[dict]) -> str:
    groups = []
    for b in blocks:
        if b["type"] in ("list_item", "code") and groups and groups[-1][0] == b["type"]:
            groups[-1][1].append(b)
        else:
            groups.append((b["type"], [b]))
    parts = []
    for kind, items in groups:
        if kind == "list_item":
            ordered = sum(b["step"] for b in items) / len(items) >= STEP_THRESHOLD
            parts.append("\n".join(
                f"{n + 1}. {b['text']}" if ordered else f"- {b['text']}"
                for n, b in enumerate(items)
            ))
        elif kind == "code":
            parts.append("```\n" + "\n".join(b["text"] for b in items) + "\n```")
        elif kind == "heading":
            parts.append(f"{HEADING_MARK[items[0]['hlevel']]} {items[0]['text']}")
        elif kind == "quote":
            parts.append(f"> {items[0]['text']}")
        elif kind == "callout":
            parts.append(f"> [!{CALLOUT_MARK[items[0]['callout']]}]\n> {items[0]['text']}")
        else:
            parts.append(items[0]["text"])
    return "\n\n".join(parts) + "\n"


markdown = to_markdown(blocks)
print(markdown)

شغّل، واقرأ أولًا Markdown المطبوع، ثم انظر إلى نتيجة العرض.

يجب أن ترى (مخرجات مسجّلة رسميًا، مقتطفات — الفقرة الافتتاحية ذات الأسطر الأربعة المكسورة يدويًا صارت فقرة واحدة، والأوامر دخلت سياج كود، والقائمتان واحدة مرقّمة وواحدة نقطية، والتحذير الخالي من أي وسم صار كتلة تنبيه):

text
# Migration to the new build system

Hi everyone, quick heads up about the build system migration that is happening next week. We have been running the new pipeline in shadow mode for three weeks and the results look solid, so it is time to make the switch for real.

……
```
bun run build
```
……
- The platform team
- The web client team
- Whoever still owns the release tooling

## Things to do before Monday

1. Update your local toolchain to version 2.4 or later
2. Delete the old build cache directory
3. Run the doctor script and fix anything it flags

> [!WARNING]
> If the doctor script reports a red result on the toolchain check, do not proceed with the migration. Ping the infra channel first and we will sort it out together.

> As Dana put it in the kickoff, "a migration nobody notices is the only kind worth shipping."

Thanks, and shout if anything looks off.

العناوين لم تعد ممتزجة بالفقرات العادية، والقوائم وخطوات العمليات معروضة كقوائم مناسبة، والأوامر في المثال معروضة كنص. الأوامر الواردة في المستند محتوى مطلوب تنسيقه، وليست عمليات نظام مطلوب منك تنفيذها.

تحقق كتلةً كتلةً من بقاء معلومات النص الأصلي؛ افحص خصوصًا النقطتين قبل القوائم، والجمل الممتدة عبر الأسطر، وحدود القوائم والكود. للكتل منخفضة الثقة أو التي يصعب تمييز نوعها بين خيارات متعددة، قدّم المراجعة البشرية — في المثال الرسمي كانت الكتلة الأدنى ثقة هي بالضبط الجملة التمهيدية للقائمة (0.43، مع احتمالات paragraph / list_item / callout موزعة عند 0.53 / 0.24 / 0.19)، والمثال الرسمي لخط المراجعة هو تمييز الكتل التي تقل ثقة نوعها عن 0.55 وإرسالها للمراجعة البشرية.

💡 هذه هي القيمة الفريدة لـ Jev

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

📋 Prompt سحري ​

الأولان هما قالبا أسئلة SDK قابلان للنسخ لخط سير هذا الدرس (العناصر النائبة تُكتب بين 【】، وما يحمل ? اختياري)، والآخران قالبان نصيان للتحقق البشري — وليس أي منها دليلًا على نتائج نموذج تم تشغيله.

📝 سؤال دمج الأسطر (نسخة Noul) ​

التأثير المتوقع: عند الحاجة لدمج أسطر مستندك، انسخ هذا السؤال لكل زوج من الأسطر المتجاورة وضعها كلها في طلب واحد؛ اكتب معيار الحكم كحقيقة نصية، لا كاستمرارية موضوع.

python
from typesafe_sdk import Noul, NoulCriteria

# 必填项:【i】是当前行号;true/false 是给模型看的判断标准
join_q = Noul(
    instructions=f"Does line {line_id(【i】)} pick up mid-sentence, continuing a "
                 f"sentence left unfinished at the end of line {line_id(【i - 1】)}?",
    criteria=NoulCriteria(
        true="【这一行从上一行没写完的句子中间开始——换行把句子拆断了】",
        false="【这一行自己开始新的句子、条目、标题或意思】",
    ),
)
# 选填项:官方 ends_terminal 只认英文标点,处理中文文档时把全角标点补进正则?
# 输出规范:answer.noul 是「接着上一行」的概率,拼不拼由代码按阈值决定
# 约束条件:
# ✅ 问「是否接续句子」这种窄事实——官方对照:换成「同一段落」,列表项得分 0.77–0.91,17 块并成 12 块
# ✅ 空行隔开的行对跳过不发;上一行结尾有无标点由代码读,两档阈值分开设
# ❌ 别让模型输出拼接后的文本——拼接由代码做,输出每个字都来自输入

✅ سؤال نوع الكتلة (نسخة Choice) ​

التأثير المتوقع: تحويل «ما محتوى هذه الكتلة» إلى سؤال اختيار من متعدد؛ لتكييفه مع مستنداتك، ما تعدّله هو نصوص الأوصاف — الشرح الرسمي يقول إن هذه القواميس الثلاثة هي المواصفة الكاملة للمصنّف.

python
from typesafe_sdk import Choice

# 必填项:criteria 的键是类型名,值是给模型看的判断标准
type_q = Choice(
    instructions=f"What kind of content is block {【块编号】}?",
    criteria={
        "heading": "【短标签或标题,命名文档或其后章节——不是完整句子】",
        "paragraph": "【成段散文:一句或多句完整的说明或叙述】",
        "list_item": "【平行条目列表中的一条,读起来是同类的兄弟条目】",
        # 官方还有 quote / code / callout 三类,按同样格式补齐
    },
)
# 选填项:辅助题(标题层级 / 步骤顺序 / 提示块类别)提前放进同一请求,答案只在类型相关时读?
# 输出规范:answer.choice 是类型名;answer.confidence 和 probabilities 接人工复核线
# 约束条件:
# ✅ 每块一题、全部块一次请求——块要等拼行完成才存在,这是第二请求的真实依赖
# ✅ 超过 90 字符的块不问标题层级(官方 HEADING_MAX_CHARS = 90)
# ❌ 别只看最高分标签——概率分散的块(官方示例最低 0.43)送人工复核

⚠️ التحقق مما إذا كان النص الأصلي قد أُعيدت صياغته ​

التأثير المتوقع: حصر نتيجة التحقق في مشكلات قابلة للتحديد.

text
الدور: مدقق مستندات.
المهمة: مقارنة النص الأصلي بـ Markdown المستعاد، والتحقق من عدم نقصان المتن أو إعادة صياغته.
معلومات الإدخال:
### الحقول المطلوبة
- النص الأصلي【الصق】
- Markdown المستعاد【الصق】
### الحقول الاختيارية
- قواعد تنظيف المسافات المسموح بها【املأ】? (مثل «توحيد المسافات داخل السطر، وإزالة المسافات من بداية السطر ونهايته، وإضافة مسافة واحدة عند دمج الأسطر»)
مواصفة الإخراج: سرد الفروق حسب الموقع، ونوع كل فرق، وسبب الحاجة إلى تأكيد بشري.
الشروط المقيدة:
✅ التمييز بين وسوم Markdown والمتن — الوسوم المضافة مثل # و- و> لا تُعد إعادة صياغة
✅ الاستشهاد بمقاطع فعلية لكل فرق، بحيث يمكن تحديد موقعه في النص الأصلي
❌ عدم استكمال المحتوى الناقص من تلقاء النفس
❌ عدم الادعاء بأن كل الفروق أخطاء

🔧 فحص كتلة بنية مشبوهة ​

التأثير المتوقع: معالجة حدٍّ واحد مثير للجدل فقط، وتجنب إعادة عمل المستند كله.

text
الدور: مفتش بنية.
المهمة: فحص نوع كتلة نصية واحدة وحدودها مع الكتل المجاورة.
معلومات الإدخال:
### الحقول المطلوبة
- الكتلة السابقة【الصق】
- الكتلة الحالية【الصق】
- الكتلة التالية【الصق】
### الحقول الاختيارية
- حالة الأسطر الفارغة الأصلية【اشرح】?
- توزيع احتمالات نوع هذه الكتلة【الصق】?
مواصفة الإخراج: تقديم أدلة مرئية، وتفسيرات بديلة، وتوصيات للفحص البشري.
الشروط المقيدة:
✅ الحفاظ على صياغة النص الأصلي والاستشهاد بمقاطع فعلية
✅ التمييز بين الوسوم المؤكدة والتخمينات الدلالية، ووسم كل منهما على حدة
❌ عدم اختلاق أرقام احتمالات أو ثقة
❌ عدم اعتبار محتوى كتل الكود تعليمات مطلوب تنفيذها

نقطة تحقق ✅ ​

  • إعادة تشغيل الذاكرة المؤقتة شغّلت المسار الكامل: 28 سطرًا غير فارغ → 16 سؤال دمج أسطر في طلب واحد → 17 كتلة → 62 سؤال تصنيف في طلب واحد → مخرجات معروضة، والأرقام مطابقة للتسجيل الرسمي.
  • يمكن مقارنة الأصل، وكتل النص المنظّمة، وMarkdown النهائي ببعضها البعض.
  • القدرة على تفسير تبعية ترتيب طلب دمج الأسطر وطلب التصنيف، دون ادعاء خاطئ بأن «طلبًا واحدًا ينجز كل شيء».
  • القوائم لم تُدمج خطأً في الجمل التمهيدية، والكود لم يُنفّذ خطأً، ومستويات العناوين فُحصت بشريًا.
  • التمييز الواضح بين نتائج الذاكرة المؤقتة والاختبار الفوري، دون اعتبار أرقام مثال المستند قياسات شخصية.

تنبيهات المزالق ​

الظاهرةما يُفحص أولًا
دمج عدة عناصر قائمة في فقرة واحدةهل غُيّر السؤال إلى «نفس الفقرة» الواسع؛ وهل حُفظت الأسطر الفارغة وقواعد الدمج
العناوين أو كتل التنبيه لا تطابق المتوقعمطابقة أوصاف التصنيف مع سياق النص الأصلي، لا الاكتفاء بالوسم الحاصل على أعلى درجة
أرقامك لا تطابق المثالما إذا كانت المدخلات والنموذج والأسئلة والذاكرة المؤقتة متطابقة؛ لا تطلب من أي مدخلات إعادة إنتاج نتائج المثال
كتلة تنبيه خاصة تظهر كاقتباس عاديهل يدعم قارئ Markdown الهدف الصيغة الموسعة المقابلة
فقدان مسافات بادئة الكودالمعالجة المسبقة الرسمية تنظّف المسافات؛ لا تعتبر هذا المثال أداة استعادة تنسيق بلا فقدان لأي ملف كود
عدم دقة حكم دمج الأسطر في المستندات الصينيةالتعبير النمطي الرسمي ends_terminal يطابق علامات الترقيم الإنجليزية فقط (. ! ? : ; و…)، وعلامات الترقيم كاملة العرض يجب إضافتها بنفسك إلى فئة المحارف

خلاصة هذا الدرس ​

في هذا المثال فُكّك تحويل النص الخالص إلى Markdown إلى ثلاث مهام: أولًا الحكم على كسور الأسطر، ثم الحكم على أنواع الكتل، وأخيرًا العرض بواسطة الكود. طلبا API نابعان من تبعيات مدخلات حقيقية، وليس من زيادة الجولات لجعل النتائج أكثر موثوقية تلقائيًا.

استناد هذه الصفحة: sources/jev/docs/cookbooks/autoformat.md؛ النسخ المحلية من مدخلات المثال الرسمي والذاكرة المؤقتة: sources/jev/extra/c2-autoformat-build-memo.txt، sources/jev/extra/c2-autoformat-json-cache.json. الأعداد المذكورة أعلاه جاءت من مطابقة المثال العام مع الذاكرة المؤقتة المحلية (تحتوي الذاكرة المؤقتة على إجابات مسجّلة لدمجين للأسطر وتصنيف واحد)، وليست اختبار أداء فوريًا جديدًا أُجري لهذا الدرس.

استعراض الدرس التالي ​

الدرس التالي ينظر في الطلب باللغة الطبيعية: التحويل إلى سلة شراء مهيكلة، مع مواصلة التدريب على تفكيك مشكلات العمل إلى أحكام صريحة ثم معالجة النتائج بالبرنامج. يمكنك أيضًا العودة إلى استخراج القيم لمقارنة الفرق بين «تحديد المعلومات» و«استعادة البنية».

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.