ربط وكيل

السجل نقطة وصول MCP واحدة: https://instruction.md/mcp. يقرأ الوكيل التعليمة بوصفها موردًا، والوكيل الذي يشترك فيها (agentd ومتابِعو حزم SDK) يُبلَّغ عندما تنشر فيعيد تحميلها دون إعادة تشغيل. أما Claude Code وCodex فلا يشتركان في الموارد: يتابعان التعليمة عبر خطافات يجهّزها أمر واحد (Claude Code، Codex، بالإنجليزية).

يتحدث الخادم MCP 2026-07-28، وهو البروتوكول عديم الحالة: لا يوجد معرّف جلسة، وكل طلب يحمل إصدار البروتوكول والعميل والقدرات، فتستطيع أي نسخة من الخادم أن تجيب عنه. الاشتراك هو تدفق subscriptions/listen. وعملاؤنا يتحدثونه: الاستوديو، وأداة CLI instruction، وبرامج المتابعة (followers) للغات TypeScript و Python و Go. وهو البروتوكول الوحيد الذي يدعمه instruction.md: يتصل التطبيق المضيف بالإصدار 2026-07-28.

التحديثات المباشرة والقراءة

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

القراءة غير محدودة أبدًا، في أي خطة: أي عدد من الوكلاء، وبالقدر الذي يريدونه.

التحديثات المباشرة تعتمد على خطة مساحة العمل. في خطة Community يتلقاها وكيل واحد أو تطبيق ذكاء اصطناعي واحد في المرة. ومن خطة Pro فما فوق، أي عدد. إذا طلب وكيل ثانٍ التحديثات المباشرة في مساحة عمل على خطة Community بينما يتلقاها وكيل آخر، يُخبَر بذلك وبالمدة التي عليه انتظارها قبل المحاولة مجددًا. ويظل يعمل: يقرأ أحدث إصدار وفق جدوله هو (برامج المتابعة لدينا تتحقق كل دقيقة ما لم تحدّد فترة أخرى)، ويأخذ مكان التحديث المباشر عندما يتوقف الأول. أما الاستوديو نفسه فلا يأخذ هذا المكان أبدًا.

لمن يكتبون عميلًا: التحديثات المباشرة هي subscriptions/listen على عنوان instruction:// وأحداث MCP Events md.instruction.activity وmd.instruction.releases (تدفق أو استطلاع دوري أو webhook). الرفض هو خطأ JSON-RPC رقم -32013، وفي حقله data خطؤنا: code: "limit_reached"، ورسالة، وdetails وفيه limit: "realtimeConsumers" وmax وplan وretryAfterSeconds وupgrade. التدفق الذي يفقد مكانه (يأخذه وكيل مساحة العمل نفسها من وكيل خارجها) ينتهي بالإشعار notifications/events/terminated حاملًا الخطأ نفسه. يُحسب الوكيل واحدًا مهما كان عدد التدفقات التي يفتحها. ويتحرر المكان عندما تُغلق تدفقاته، أو بعد دقيقتين من آخر مرة سُمع فيها من الوكيل.

عنوان التعليمة

لكل تعليمة عامة عنوان على الويب، https://instruction.md/{owner}/{name}، وهو نفسه للأشخاص وللوكلاء. المتصفح يحصل على صفحتها: التعليمة، ومعرّف URI الخاص بها instruction://، والإعدادات اللازمة لمتابعتها. والوكيل الذي يرسل Accept: text/markdown، أو لا يرسل ترويسة Accept إطلاقًا، كما يفعل curl ومعظم أدوات الجلب، يحصل على النص المنشور نفسه، حرفيًّا، مع إصداره في الترويسات. العنوان واحد في الحالتين: لا توجد صيغة تنتهي باللاحقة .md. إضافة @stable أو @v3 بعد الاسم تقرأ مرجعًا (ref) أو إصدارًا بعينه، وhttps://instruction.md/{owner} يسرد التعليمات العامة لمالك. ولمتابعة تعليمة وهي تتغيّر، اربط الوكيل عبر MCP كما هو مبيَّن أدناه. ملف الموقع /llms.txt يسرد الوثائق والقوالب للوكلاء.

Shell
curl -H 'Accept: text/markdown' https://instruction.md/instruction-md/code-review

Claude Code

Shell
claude mcp add instruction-md --transport http https://instruction.md/mcp
# then in a session: read instruction://acme/support-agent@stable

لتصبح التعليمة تعليمات المشروع وتبقى محدَّثة أثناء الجلسة، راجع Claude Code (بالإنجليزية).

Codex

يستخدم Codex إصدارًا أقدم من MCP مما يستخدمه هذا الخادم، لذا يتصل عبر خادم MCP الخاص بسطر الأوامر. راجع Codex (بالإنجليزية) لذلك، ولمتابعة تعليمة أثناء الجلسة.

Cursor وعملاء MCP الآخرون

JSON
{
  "mcpServers": {
    "instruction-md": {
      "command": "npx",
      "args": ["-y", "instruction.md", "mcp", "--follow", "instruction://acme/support-agent@stable", "--url", "https://instruction.md/mcp"]
    }
  }
}

كل قراءة تحتاج إلى طالب سجّل الدخول. يسجّل Claude و ChatGPT دخولك بأنفسهما. أما Cursor و VS Code والعملاء الآخرون الذين يتحدثون إصدارًا من MCP أقدم من إصدار instruction.md فيمرّون عبر خادم stdio الخاص بسطر الأوامر أعلاه (في VS Code: الإدخال نفسه ضمن servers في .vscode/mcp.json مع "type": "stdio")، الذي تسجّل دخولك إليه مرة واحدة بالأمر instruction login. والوكلاء يستخدمون بيانات اعتماد خاصة بهم.

اختيار ما يُسمح لتطبيق الذكاء الاصطناعي بفعله

عندما تربط تطبيق ذكاء اصطناعي مثل Claude أو ChatGPT أو محرر أكواد، يسألك instruction.md أولًا «ماذا يمكن أن يفعل التطبيق؟» (باسم التطبيق). تختار واحدًا من أربعة خيارات، كل منها يشمل ما قبله:

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

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

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

أدوات المؤسسة في تطبيق مضيف

إدارة مؤسسة تحتاج إلى نطاق OAuth (scope) إضافي، org:admin، وإلى الخيار «كل ما يمكنك فعله» عند ربط التطبيق. ومن دونه يسرد التطبيق المضيف أدوات كتابة التعليمات ومراجعتها ونشرها ومشاركتها ومتابعتها، لكن لا يسرد الأدوات التي عددها 28 والتي تدير مؤسسة: أعضاءها ودعواتها، ومساحات العمل، والسياسة، ومفاتيح التوقيع، والوكلاء، والفوترة، وسجل التدقيق. التطبيق المضيف الذي ليس لديه هذا النطاق لديه قائمة أدوات أقصر.

  • لا يسمّي الخادم هذا النطاق حيث يعرف التطبيق المضيف كيف يسجّل الدخول (بيانات الوصف الخاصة بالمورد المحمي والتحدي في رده 401)، فيسجّل التطبيق المضيف الدخول للأدوات اليومية ويسرد تلك الأدوات.
  • لا يحصل التطبيق المضيف على org:admin إلا إذا طلبه بالاسم وأنت تسجّل الدخول، حيث يتيح لك اختيار النطاقات التي يطلبها. عندئذ تسرد صفحة تسجيل الدخول "Administer your organizations on instruction.md" ضمن ما توافق عليه، ويسرد التطبيق المضيف أدوات المؤسسة.
  • التطبيق المضيف الذي يسمّي نطاقاته عند اتصاله أول مرة ليس لديه سواها: فإن أغفل org:admin حينها لا يستطيع طلبه في تسجيل دخول لاحق (يُرفض بوصفه نطاقًا غير صالح). أزل الموصّل وأضفه من جديد، مع تسمية org:admin هذه المرة.
  • الاستوديو وأداة CLI instruction لديهما هذا النطاق دائمًا. إذا لم يكن لدى تطبيقك المضيف، فأدِر المؤسسة من هناك: «الإعدادات» في الاستوديو، أو instruction agents وinstruction keys وinstruction audit في CLI.
  • الوكلاء لا يحصلون عليه أبدًا: بيانات اعتماد الوكيل لا تتيح إدارة مؤسسة.

النطاق يتيح للعميل فقط أن يرى هذه الأدوات ويستدعيها. وكل أداة تتحقق مع ذلك من دورك: لا يغيّر المؤسسة إلا مالكوها ومسؤولوها، ولا يغيّر فوترتها إلا أعضاؤها المكلّفون بالفوترة.

agentd

agentd من الإصدار 1.18 فما بعده يتحدث MCP 2026-07-28 و MCP Events. أعطِ الوكيل بيانات اعتماد خاصة به («الإعدادات» ▸ «الوكلاء» في الاستوديو، أو instruction agents create؛ لمؤسسة على خطة Pro أو أعلى)، ثم تابع التعليمة بمعرّفها عند مرجع:

YAML
# agentd 1.18 or later, as a daemon: the instruction is the policy every conversation follows
agent:
  name: support-desk
  instruction:
    mcp:
      server: instruction-md
      # the instruction's id at a ref: publishing moves the ref, and the server pushes the re-read
      resource: "instruction://ins_01M…@stable"
      events: [md.instruction.activity]
    unavailable: keep
    trust:
      - uri: "instruction://ins_01M…@stable"
        publisher: "https://instruction.md/pub/acme"
intelligence:
  endpoints: https://api.anthropic.com
  dialect: anthropic
  model: claude-sonnet-5
  token: "{{secret:ANTHROPIC_API_KEY}}"
mcp:
  servers:
    - name: instruction-md
      endpoint: https://instruction.md/mcp
      auth:
        kind: oauth2
        grant: client_credentials
        client_id: "<your agent's client id>"
        client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"
        # agents sign in on their own realm
        token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
store:
  kind: file
  file: { path: ./support-desk-state }
a2a:
  listen: http://127.0.0.1:8420
lifecycle:
  run_until: drained

النشر ينقل المرجع، فيدفع الخادم إعادة القراءة إلى اشتراك agentd، ويقرأ الدور التالي الإصدار الجديد: يسجّل agentd الحدث instruction.applied، من الإصدار القديم إلى الجديد، خلال ثانية. والعنوان بصيغة المالك/الاسم (instruction://acme/support-agent@stable) يعمل أيضًا؛ وعندئذ يعرف agentd بنشر إصدار عبر MCP Events، بعد ثوانٍ قليلة.

تثبيت publisher يجعل التحقق إلزاميًّا: يفحص agentd توقيع المؤلف بمجموعة مفاتيح الناشر عند كل قراءة، ويرفض إصدارًا موقّعًا بمفتاح مُبطَل، ويبقى على آخر تعليمة سليمة لديه بدلًا من تطبيق أي شيء لا يستطيع التحقق منه. توقيع الإصدار يسمّي التعليمة بمعرّفها، فثبّت العنوان الذي يحمل المعرّف. رمز الوصول الخاص بالوكيل يأتي من realm الوكلاء، الذي لا تسمّيه بيانات الوصف لخادم MCP: وtoken_url يبيّن مكانه.

الكود الخاص بك

حزمة instruction.md على npm تتضمن برنامج متابعة (follower) يطبّق نصف المستهلك من المواصفة: الاحتفاظ بآخر إصدار سليم، والتوقف الذي تفرضه السياسة، والتحقق من التوقيع مع اكتشاف المفاتيح، والإبلاغ بما طبّقه. وعميل MCP الخاص بها، instruction.md/client، يمنحه البروتوكول عديم الحالة؛ واشتراكه يُفتح من جديد بعد انقطاع ويقرأ التعليمة مرة أخرى. ولحزمتي SDK للغتي Python و Go برنامج المتابعة نفسه على البروتوكول نفسه (python -m instruction_md watch، NewHTTPClient).

Shell
npm install instruction.md
pip install instruction-md   # the Python SDK
TypeScript
import { asSdkClient, createClient } from "instruction.md/client";
import { InstructionFollower } from "instruction.md/consumer";

const follower = new InstructionFollower({
  // MCP 2026-07-28, stateless (or any MCP client with the SDK's Client shape)
  client: asSdkClient(createClient({ url: "https://instruction.md/mcp", token: () => token })),
  uri: "instruction://acme/support-agent@stable",
  mode: "follow",
  policy: { requireSignature: true, publisher: "https://instruction.md/pub/acme" },
  report: { consumer: { label: "support-bot (prod)", kind: "agent" } },
  onApply: (applied) => setSystemPrompt(applied.text),
  onHold: (reason) => log.warn({ reason }, "kept the last good instruction"),
});
await follower.start();

متابعة هدف متحرك بأمان

الخيارما يعنيه
@stableمرجع تنقله أنت عن قصد. يُنصح به لكل ما هو في بيئة التشغيل الفعلية.
@latestينتقل مع كل نشر. مناسب للتطوير.
@ver_…مثبَّت على إصدار واحد غير قابل للتغيير. لا يتغيّر أبدًا.

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

إخبار السجل بما طبّقته

يستطيع المستهلك أن يعلن ارتباطًا وأن يبلّغ بالإصدار الذي طبّقه. وهذا ما يملأ عرض المستهلكين (Consumers): أي الوكلاء يتابعون تعليمة، وما الذي يشغّله كل منهم، وكم يستغرق اعتماد الإصدار الجديد. وهو اختياري، ولا يرسل محتواك إلى أي مكان أبدًا.