بناء Digital FTE: دورة مكثفة في 4 ساعات

15 مفهوماً، 80% من الاستخدام الحقيقي: المهارات، مصدر الحقيقة، وMCP

هذه هي الدورة الثانية في النمط 2: مسار التصنيع. الدورة السابقة، بناء وكلاء ذكاء اصطناعي، بنت وكيل محادثة مع جلسات وحواجز أمان ونشر sandbox. في نهايتها كان لديك agent. كان يعمل، لكنه ينسى كل شيء عند إغلاق terminal.

هذه الدورة تحول ذلك agent إلى Worker: وكيل يستطيع العيش داخل شركة. نفس SDK ونفس runtime، لكن نضيف ثلاث قطع:

1. Skills: مجلدات قدرات يحملها الوكيل عند الحاجة.
2. Neon Postgres: ذاكرة متينة يقرأ منها العامل ويكتب إليها.
3. MCP: السلك الذي يربط الوكيل بمصدر الحقيقة.

الجملة الواحدة: تحويل وكيل إلى Worker يعني سؤالين: أين تعيش قدراته؟ وأين تعيش ذاكرته؟ المهارات تجيب عن الأول. وقاعدة بيانات عبر MCP تجيب عن الثاني.

لماذا يهم هذا بالعربية المبسطة

وكيل المحادثة يعيش في عملية Python واحدة. قدراته مخبوزة في الكود. وذاكرته تختفي عند إعادة التشغيل. هذا مقبول للعرض التجريبي، لا لوكيل يحتاج أن يجيب: "ماذا قلنا لهذا العميل قبل ستة أسابيع؟" أو "هل رأينا هذه المشكلة من قبل؟"

الـ Worker يصلح ذلك: القدرات في مجلدات Skills، والذاكرة في قاعدة بيانات، وكل فعل مهم في audit log.

مكان هذه الدورة في أطروحة Agent Factory

الدورة السابقة بنت agent. هذه الدورة تبني Digital FTE. الدورة التالية ستلفه بغلاف إنتاجي باستخدام Inngest. لاحقاً سيدخل العامل في قوة عمل تُدار بـ Paperclip، ثم تتوسع بالتوظيف، ثم تفوض المالك.

بطاقة المفاهيم الخمسة عشر

#	المفهوم
1	Skill بوصفها قدرة محمولة
2	Progressive disclosure
3	عقد SKILL.md
4	تغليف المهارات ونقلها
5	تركيب المهارات
6	لماذا Neon Postgres
7	مخطط Worker
8	أساسيات pgvector
9	embedding pipeline
10	audit trail
11	ما MCP وما ليس هو
12	Neon MCP للتطوير
13	ربط MCP بـ Agents SDK
14	خادم MCP مخصص
15	MCP تحت الحمل

لمن هذه الدورة

للمهندس الذي يريد تحويل agent إلى عامل شركة، وللقائد الذي يريد فهم مكونات الثقة: قدرة، ذاكرة، موافقة، وسجل. لا تكفي قراءة المفاهيم لشحن الإنتاج، لكنها تكفي لفهم البنية.

المكسب السريع في خمس عشرة دقيقة

ابنِ أداة "سجل ملاحظة" بسيطة تجعل العامل يكتب إلى مخزن متين، ثم اقرأها في turn لاحق. الدرس: الذاكرة ليست history في المحادثة؛ الذاكرة مصدر حقيقة.

# notes_mcp.py
def log_note(customer_id: str, note: str) -> str:
    return "saved"

# cli.py - Quick Win shape
result = Runner.run_sync(agent, "Log a note for customer 42: prefers email.")

الجزء 1: Skills، القدرة كمجلدات محمولة

Concept 1: ما Agent Skill

Skill مجلد يحتوي SKILL.md وربما أمثلة ومراجع وسكربتات. هو قدرة قابلة للنقل، لا مجرد prompt. العامل يجد المهارة عند الحاجة، يقرأ تعليماتها، ثم يستخدمها.

# Hello skill

Use this skill when the user asks for a friendly greeting.
Keep it short and do not invent personal details.

Concept 2: Progressive disclosure

ثلاث مراحل: يرى الوكيل اسم المهارة ووصفها، ثم يقرأ SKILL.md عند التفعيل، ثم يقرأ الملفات الإضافية عند الحاجة. هذا يمنع تحميل كل المعرفة في كل turn.

Concept 3: كتابة SKILL.md

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

Concept 4: تغليف المهارات

المهارة يجب أن تسافر: داخل repo، في مجلد مستخدم، أو في حزمة فريق. حافظ على أسماء مستقرة وأمثلة صغيرة.

Concept 5: تركيب المهارات

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

الجزء 2: Neon Postgres وpgvector كمصدر حقيقة

Concept 6: لماذا managed Postgres، ولماذا Neon

Postgres مفهوم، متين، وقابل للتدقيق. Neon يضيف branching وserverless وسهولة تطوير. في هذه الدورة نستخدمه لأن العامل يحتاج مصدر حقيقة لا يختفي عند restart.

Concept 7: مخطط Worker

العامل يحتاج جداول للكيانات، الملاحظات، الأحداث، embeddings، والموافقات. لا تبدأ بجداول كثيرة؛ ابدأ بما يثبت السلوك.

create table audit_log (
  id bigserial primary key,
  actor text not null,
  action text not null,
  payload jsonb not null,
  created_at timestamptz default now()
);

Concept 8: أساسيات pgvector

pgvector يضيف نوع vector وعمليات مسافة. يسمح لقاعدة واحدة بحمل بيانات علائقية وبحث دلالي. استخدمه عندما تحتاج "حالات مشابهة" لا مجرد lookup بمفتاح.

Concept 9: embedding pipeline

النص يدخل، يتقسم إلى chunks، يتحول إلى embeddings، ثم يخزن مع metadata. جودة البحث تعتمد على chunking والmetadata بقدر اعتمادها على النموذج.

# src/chat_agent/embedding/chunker.py
def chunk_text(text: str, size: int = 800) -> list[str]:
    return [text[i:i+size] for i in range(0, len(text), size)]

سجل pgvector مع asyncpg

إذا لم تسجل نوع vector عند الاتصال، قد تفشل عمليات الإدخال أو التحويل بطرق مربكة. اجعل التسجيل جزءاً من init للpool.

Concept 10: Audit trail كانضباط

العامل يقرأ ويكتب نيابة عن شركة. كل فعل مهم يجب أن يظهر في سجل: من فعل؟ ماذا فعل؟ لماذا؟ على أي بيانات؟ وبأي نتيجة؟

# src/chat_agent/audit.py
async def record_action(conn, actor: str, action: str, payload: dict) -> None:
    await conn.execute(
        "insert into audit_log(actor, action, payload) values ($1, $2, $3)",
        actor, action, payload,
    )

الجزء 3: MCP، ربط الوكيل بمصدر الحقيقة

Concept 11: ما MCP وما ليس هو

MCP معيار يربط الوكلاء بالأدوات والموارد والprompts. ليس قاعدة بيانات ولا إطار عمل كامل. هو protocol يجعل قدرات خارجية تظهر للوكيل بطريقة منظمة.

Concept 12: Neon MCP server

Neon MCP مفيد في مستوى التطوير: إنشاء branch، تشغيل SQL، وفحص schema. لا تجعله runtime pathway لكل طلب مستخدم بلا تفكير؛ runtime يحتاج واجهات ضيقة وآمنة.

# في مشروعك
npx @neondatabase/mcp-server

Concept 13: ربط MCP بـ OpenAI Agents SDK

استخدم MCP client في SDK لعرض tools/resources. ابدأ بأداة read-only، ثم أضف write بعد audit وموافقة.

# tools/scratch_with_neon.py
# development utility, not production

Concept 14: خوادم MCP مخصصة

اكتب خادمك عندما تحتاج واجهة مجال ضيقة: find_similar_cases, create_ticket_note, require_approval. لا تعرض SQL عامة للوكيل في الإنتاج.

# servers/customer_data_mcp/server.py
def find_similar_cases(query: str) -> list[dict]:
    return []

Concept 15: MCP تحت الحمل

تحت الحمل، اهتم بالtransport، connection pooling، timeouts، backpressure، وحدود payload. MCP ليس عذراً لتجاهل هندسة الخدمات.

الجزء 4: المثال العملي، Worker دعم عملاء

الموجز

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

Decision 1: حدّث ملف القواعد بالبنية الجديدة

# chat-agent

## Architecture (NEW)
- Skills live in `.claude/skills/`.
- Neon is the system of record.
- MCP exposes narrow runtime tools.
- Audit log records every meaningful action.

Decision 2: خطط schema ومجموعة المهارات

ابدأ بثلاث مهارات: summarize-ticket, find-similar-cases, escalate-with-context. واجعل schema تخدم هذه المهارات، لا كل حلم مستقبلي.

Decision 3: وفّر Neon وشغّل migration

أنشئ قاعدة، فعّل pgvector، شغّل migrations/001_initial.sql، ثم تحقق باستعلام بسيط.

شكل migrations/001_initial.sql

create extension if not exists vector;
create table tickets (
  id text primary key,
  customer_email text not null,
  summary text not null
);

Decision 4: اكتب أول Skill، summarize-ticket

# Summarize ticket

## Example: short ticket
Input: customer asks about refund.
Output: issue, account context, requested action.

## Edge cases
- Missing customer id.
- Ambiguous refund amount.

Decision 5: ابن embedding pipeline وseed للمكتبة

ابدأ بملف CSV صغير لحالات محلولة، ثم شغّل chunk/embed/store. لا تحتاج آلاف الصفوف لتتعلم السلوك.

# data/seed/resolved-tickets.csv
id,customer_email,summary,resolution
T-1,a@example.com,refund request,approved small refund

Decision 6: اكتب خادم MCP مخصص للوصول runtime

اجعل الأدوات ضيقة ومصممة للوكيل. لا تفتح execute_sql عاماً في runtime.

ارفع timeout init إذا كان MCP server يستورد أشياء ثقيلة

بعض الخوادم تحتاج ثواني للبدء. اضبط timeout بدلاً من جعل الوكيل يعيد كتابة الخادم.

Decision 7: اربط audit logging في كل مكان

كل tool call مهم يكتب صفاً. إذا فشل audit، يجب أن تعرف هل فشل الفعل نفسه أم فشل التسجيل.

Decision 8: تحقق end-to-end

أرسل ticket، دع العامل يلخص، يبحث عن حالات مشابهة، يكتب اقتراحاً، ويطلب موافقة إن لزم. النجاح ليس "رد جميل"؛ النجاح أن كل خطوة قابلة للتتبع.

ما الذي حدث

حوّلت agent إلى Worker لأنه أصبح يملك قدرات خارج الكود، ذاكرة خارج الجلسة، وسجلاً خارج الانطباع. هذا هو الفارق بين demo وموظف رقمي.

الجزء 5: أين تتوقف هذه الدورة

شكل كلفة Worker

الكلفة تأتي من model calls، embeddings، قاعدة البيانات، MCP server، وaudit storage. قياسها أبكر من تحسينها.

دليل الاستبدال

Neon يمكن أن يستبدل بـ Postgres managed آخر. pgvector يمكن أن يستبدل بمخزن متجهات. MCP يمكن أن يعمل عبر stdio أو HTTP. البنية ثابتة: قدرات، ذاكرة، wire، audit.

ما لا تغطيه الدورة بعد

لا تغطي الإنتاج المتين، إدارة قوة العمل، أو التوظيف الديناميكي. تلك مراحل لاحقة.

كيف تتحسن فعلاً

بعد هذه الدورة، اقض وقتك في تصميم المهارات والschema وواجهات MCP، لا في كتابة prompts أطول. العامل الجيد هو عامل يملك حدوداً جيدة ومصدراً موثوقاً للحقيقة.

مرجع سريع

المفاهيم الخمسة عشر

1. Skill قدرة محمولة.
2. Progressive disclosure يحفظ السياق.
3. SKILL.md عقد تشغيل.
4. المهارات تسافر كمجلدات.
5. التركيب يحتاج حداً واضحاً.
6. Neon/Postgres مصدر حقيقة.
7. Worker يحتاج schema لا ذاكرة محادثة.
8. pgvector يضيف بحث التشابه.
9. embeddings pipeline هي نص -> chunks -> vectors.
10. audit trail يثبت الأفعال.
11. MCP wire لا database.
12. Neon MCP مستوى تطوير.
13. SDK يتصل بـ MCP كعميل.
14. MCP مخصص للواجهات الضيقة.
15. تحت الحمل، pooling وtimeouts وlimits مهمة.

شجرة قرار: @function_tool أم MCP؟

الحالة	الاختيار
منطق محلي بسيط	@function_tool
قدرة runtime خارج العملية	MCP مخصص
إدارة قاعدة Neon أثناء التطوير	Neon MCP
API مورّد جاهز ومحدود	Vendor MCP

مواقع الملفات

الشيء	المكان
المهارات	.claude/skills/<name>/SKILL.md أو ما يكافئها
migrations	migrations/
MCP server	servers/customer_data_mcp/
embedding code	src/chat_agent/embedding/
audit	src/chat_agent/audit.py

عندما يبدو شيء غير صحيح

العامل ينسى -> الذاكرة ليست في SoR.
البحث يعيد نتائج غريبة -> chunking أو metadata سيئ.
MCP بطيء -> pool/timeout/payload.
لا تعرف من فعل ماذا -> audit ناقص.
المهارة لا تستدعى -> الوصف غير واضح أو النموذج يحتاج اسمها صراحة.

ملحق: الجمهور والمتطلبات والمسرد

A.1 الجمهور والمتطلبات

تحتاج معرفة أساسية بـ Python وSQL وCLI. يمكن للقادة قراءة المفاهيم لفهم بنية Digital FTE من دون تنفيذ المختبر.

A.2 ما تفترضه الدورة السابقة

تفترض وجود agent محلي مع tools، sessions، guardrails، tracing، وCLI.

A.3 أساسيات Postgres

ستستخدم tables، indexes، JSONB، extensions، connection strings، وtransactions. لا تحتاج أن تكون DBA.

A.4 كيف تقرأ الصفحة أول مرة

اقرأ المفاهيم، نفذ quick win، ثم عد إلى المثال العملي. لا تحاول حفظ API من القراءة الأولى.

A.5 مسرد

• Skill: مجلد قدرة.
• SoR: مصدر الحقيقة.
• MCP: بروتوكول ربط الوكيل بالأدوات والموارد.
• Embedding: متجه يمثل معنى نص.
• Audit log: سجل أفعال قابل للتدقيق.

A.6 ما لا يستبدله الملحق

لا يستبدل وثائق Neon أو MCP أو SDK الحالية. استخدمه كخريطة، ثم تحقق من API الحالي قبل الإنتاج.