BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/agent-web-surfaces.mdx
View on GitHub---
title: "موقع الوكيل العام"
description: "اجعل المسارات العامة قابلة للزحف، وقابلة للقراءة، والاستشهاد بها، ويمكن استدعاؤها اختياريًا بواسطة الوكلاء — robots.txt، وllms.txt، ومرايا Markdown، وJSON-LD، وسطح MCP العام."
---
# موقع الوكيل العام
تجعل شبكة الوكيل العام مسارات Agent-Native العامة سهلة على الوكلاء للزحف إليها وقراءتها والاستشهاد بها والاتصال بها. الهدف ليس جعل نقطة نهاية كل تطبيق عامة. الهدف هو نشر سطح عام نظيف للصفحات العامة بالفعل، مع الاحتفاظ بالبيانات الخاصة والوصول إلى الأدوات خلف ضوابط واضحة.
موقع المستندات هو التنفيذ المرجعي. واليوم يتم شحنه:
- `/robots.txt` مع سياسة الزاحف التي تسمح بالاسترداد ولكنها لا تسمح بالتدريب بشكل افتراضي.
- `/sitemap.xml` كفهرس لخرائط الموقع يشير إلى ملف `/sitemap-<locale>.xml` واحد لكل لغة، مع URLs الأساسية المطلقة و`lastmod` عندما يعرضها الملف المصدر.
- `/llms.txt` و`/llms-full.txt` لاكتشاف المحتوى المناسب للوكلاء.
- مرايا Markdown مثل `/docs/getting-started.md`.
- استجابات `Accept: text/markdown` لصفحات المستندات العامة بعد إنشاء الإنتاج.
- JSON-LD للمؤسسة الأساسية وموقع الويب والبيانات الوصفية للصفحة.
- تدقيق CLI (`npx @agent-native/core@latest audit-agent-web`) يتحقق من كل ما سبق.
نشر هذه الملفات لا يكشف أي إجراء أبدًا. يصل الإجراء إلى الوكلاء الخارجيين فقط من خلال اشتراكه الخاص في `publicAgent`؛ راجع [التعريض للوكلاء العامين](/docs/actions-access-control#public-agent).
<Diagram id="doc-block-fx6d6w" title={"ما ينشر الطريق العام"} summary={"يتحول الطريق العام إلى تمثيلات صديقة للوكلاء. تعد قراءة المسار منفصلة عن أدوات الاتصال — ويظل الوصول إلى الأداة قيد الاشتراك."}>
```html
<div class="diagram-web">
<div class="diagram-box" data-rough>
الطريق العام<br /><small class="diagram-muted"
>من قائمة الصفحات التي تمررها</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-grid">
<span class="diagram-pill">robots.txt</span
><span class="diagram-pill">sitemap.xml</span
><span class="diagram-pill">llms.txt</span
><span class="diagram-pill">مرآة .MD</span
><span class="diagram-pill">JSON-LD</span
><span class="diagram-pill">text/markdown</span>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-col gate">
<span class="diagram-pill warn">تظل الأدوات خاصة</span
><small class="diagram-muted">مطلوب publicAgent.expose</small>
</div>
</div>
```
```css
.diagram-web {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.diagram-web .diagram-arrow {
font-size: 22px;
line-height: 1;
}
.diagram-web .diagram-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 8px;
}
.diagram-web .gate {
display: flex;
flex-direction: column;
gap: 4px;
align-items: flex-start;
}
```
</Diagram>
## التكوين {#config}
يكتب `createAgentWebVitePlugin` من `@agent-native/core/vite` هذه الملفات أثناء بناء الإنتاج. أضفه إلى إعدادات Vite مع الصفحات التي يجب أن يقرأها الوكلاء:
```ts
// vite.config.ts
import { defineConfig } from "vite";
import { createAgentWebVitePlugin } from "@agent-native/core/vite";
export default defineConfig({
plugins: [
// ...your existing plugins
createAgentWebVitePlugin({
siteName: "My Agent-Native App",
siteUrl: "https://example.com",
pages: [
{
path: "/pricing",
title: "Pricing",
description: "Plans and limits.",
markdown: "Plans and limits.\n",
},
],
agentWeb: { crawlerPolicy: "discoverable-no-training" },
}),
],
});
```
ينشر المكوّن الإضافي الصفحات التي تدرجها فقط، ولا شيء غيرها. لا يقرأ إعدادات الوصول إلى المسارات، ولا يقرأ `agentWeb` من `package.json` ما لم تمرره إليه. لإبقاء الإعدادات في `package.json` تحت `agent-native.workspaceApp.agentWeb`، مرّر `agentWeb: agentWebConfigFromPackageJson(pkg)` المستورد من `@agent-native/core/agent-web`.
| الخيار | الافتراضي | ما يفعله |
| --------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discoverable` | مفعّل عندما لا تكون `pages` فارغة | القيمة `false` لا تكتب أي ملفات. |
| `llmsTxt` | `true` | يكتب `/llms.txt` و`/llms-full.txt`. |
| `markdownTwins` | `true` | يكتب نسخة `.md` من كل صفحة لها `markdown`. |
| `crawlerPolicy` | `"discoverable-no-training"` | يحدد قواعد `robots.txt`: `"discoverable-no-training"` أو `"allow-all"` أو `"disallow-all"`. |
| `crawlers` | لا شيء | يتجاوز فئات الزواحف كلًّا على حدة: `training` أو `search` أو `userTriggered` أو `codingAgents` أو `autonomousAgents`، وكل منها `"allow"` أو `"disallow"`. |
سياسة الزواحف الافتراضية هي "قابل للاكتشاف، غير قابل للتدريب": يُسمح بالبحث والاسترجاع الذي يبدأه المستخدم ووكلاء البرمجة ووكلاء التصفح المستقلين؛ ولا يُسمح بزواحف التدريب.
يُقبل `jsonLd` و`publicAgentCard` و`publicMcp`، لكن لا شيء يقرؤها حتى الآن. للحصول على JSON-LD، اعرض `buildBaseJsonLd` و`buildPageJsonLd` من `@agent-native/core/agent-web` في صفحاتك بنفسك.
## توجيه مصدر الحقيقة {#route-source}
قائمة الصفحات هي مصدر الحقيقة: يحصل الوكلاء على الصفحات التي تمررها، وعليها فقط. ابنِها من صفحات عامة بالفعل:
- في التطبيق العام، كل مسار باستثناء `protectedPaths`.
- في التطبيق الداخلي، `publicPaths` فقط.
- صفحات المشاركة والنماذج العامة التي ينبغي أن يتمكن الوكلاء من قراءتها.
- لا تُدرج أبدًا البيانات الخاصة المرسلة أو لوحات المعلومات التي تتطلب مصادقة أو حالة المستخدم أو المؤسسة، حتى لو كانت صفحة قريبة عامة.
للبدء من إعدادات الوصول، يأخذ `deriveAgentWebPublicRoutes` من `@agent-native/core/agent-web` قيم `audience` و`publicPaths` و`protectedPaths` و`routes` لتطبيقك، ويعيد المسارات التي تجعلها تلك الإعدادات عامة. ولا تزال كل صفحة تحتاج إلى عنوانها الخاص وMarkdown الخاص بها.
يؤدي هذا إلى إبقاء التطبيقات المختلطة طبيعية. يمكن لتطبيق النماذج الكشف عن صفحة نموذج عامة والحفاظ على خصوصية عمليات الإرسال. يمكن لتطبيق المحتوى أن يكشف المنشورات المنشورة ويحافظ على خصوصية المحرر. يمكن لموقع المستندات أن يكشف كل شيء باستثناء أدوات الإدارة.
## الصفحات العامة ليست أدوات عامة {#public-tools}
الوصول إلى الصفحة العامة والوصول إلى الأداة العامة منفصلان. كون المسار عامًا فقط يعني أن الوكلاء يمكنهم قراءة هذا المسار مثل HTML، وMarkdown، وإدخالات خريطة الموقع، وإدخالات llms، والبيانات المنظمة.
<Callout id="doc-block-s50w8y" tone="warning">
**الصفحة العامة ليست أداة عامة.** جعل المسار قابلاً للزحف لا يكشف أي إجراء أبدًا. يتطلب الوصول إلى الأداة اشتراكًا صريحًا في `publicAgent.expose` على الإجراء.
</Callout>
للكشف عن إجراء من خلال بروتوكول الوكيل العام، يجب أن يتم تمكين الإجراء:
<AnnotatedCode
id="doc-block-1ykhj6s"
title={"اختيار إجراء آمن واحد على السطح العام"}
filename="actions/search-docs.ts"
language="ts"
code={
'export default defineAction({\n description: "Search published docs",\n readOnly: true,\n publicAgent: {\n expose: true,\n readOnly: true,\n requiresAuth: false,\n isConsequential: false,\n title: "Search published docs",\n },\n run: async (args) => {\n // ...\n },\n});'
}
annotations={[
{
lines: "4",
label: "الاشتراك الصريح",
note: "بدون `publicAgent.expose === true`، لن يظهر الإجراء أبدًا على أي سطح وكيل عام - بغض النظر عن مدى عمومية مساراته.",
},
{
lines: "5-7",
label: "وصف السلامة الذاتية",
note: "قم بوضع علامة عليها للقراءة فقط، وأعلن ما إذا كانت تحتاج إلى مصادقة، وحدد ما إذا كانت ذات أهمية. يستبعد MCP العام إجراءات consequential/write ما لم تسمح بها السياسة صراحةً.",
},
]}
/>
لا يوجد إعداد في `agentWeb` يكشف إجراءً، و`publicMcp` ليس له أي تأثير اليوم. راجع [التعريض للوكلاء العامين](/docs/actions-access-control#public-agent) لمعرفة ما يكشف `publicAgent` الإجراء له والفحوصات التي تظل سارية.
## ملفات وقت البناء {#build-time}
تقوم أدوات إطار العمل المساعدة في `@agent-native/core/agent-web` بإنشاء الملفات الشائعة من قائمة صفحات واحدة:
```ts
import {
buildAgentWebStaticFiles,
normalizeAgentWebConfig,
} from "@agent-native/core/agent-web";
const config = normalizeAgentWebConfig(
{ crawlerPolicy: "discoverable-no-training" },
{ hasPublicRoutes: true },
);
const files = buildAgentWebStaticFiles({
siteName: "My Agent-Native App",
siteUrl: "https://example.com",
description: "Public docs for my app.",
config,
pages: [
{
path: "/docs",
title: "Docs",
description: "Start here.",
markdown: "# المستندات\n\nابدأ هنا.\n",
markdownPath: "/docs/getting-started.md",
lastmod: new Date(),
},
],
});
```
يستدعي `createAgentWebVitePlugin` الدالة `buildAgentWebStaticFiles` نيابةً عنك ويكتب الملفات في المجلدات الموجودة من بين `public` و`dist` و`dist/client` و`dist/server/public` و`build/client`. مع أداة بناء أخرى، استدعِ الأدوات المساعدة مباشرة.
لا يستجيب أي منهما لـ `Accept: text/markdown` على عنوان URL الخاص بالصفحة: نسخة Markdown موجودة فقط على عنوان `.md` الخاص بها. للاستجابة لهذا الترويسة، أضف مسار خادم يعيد Markdown الصفحة مع الترويسات من `buildMarkdownResponseHeaders`، كما يفعل موقع التوثيق. من دون هذا المسار، يفشل التدقيق أدناه في فحص `Accept: text/markdown`.
مرِّر `sitemapGroup` إلى `buildAgentWebStaticFiles` أو `createAgentWebVitePlugin` لتقسيم خريطة موقع كبيرة. يربط الخيار كل صفحة بمفتاح مجموعة، مثل لغتها، فيصبح `sitemap.xml` فهرسًا لخرائط الموقع يضم ملف `sitemap-<group>.xml` واحدًا لكل مجموعة.
## تدقيق الموقع {#audit}
استخدم تدقيق CLI مقابل موقع منشور أو خادم إنتاج محلي:
```bash
npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
```
يقوم التدقيق بالتحقق من:
- SSR-HTML المرئي.
- URLs الأساسية.
- JSON-LD.
- سياسة `robots.txt` وخريطة الموقع المطلقة URL.
- إدخالات خريطة الموقع المطلقة.
- `/llms.txt` و`/llms-full.txt`.
- مرايا Markdown.
- `Accept: text/markdown`.
- لا توجد عمليات حظر غير مقصودة 401/403 لوكلاء مستخدم استرداد الوكيل المشترك.
تخرج عملية التدقيق من الصفر إذا كان السطح العام المطلوب مفقودًا.
## ما هي الخطوة التالية
- [**Actions**](/docs/actions-overview) — كيفية تفعيل actions في بروتوكول الوكيل العام
- [**MCP Protocol**](/docs/mcp-protocol) — خادم MCP الذي يتصل به الوكلاء الخارجيون
- [**Deployment**](/docs/deployment) — حيث تتم كتابة هذه الملفات الثابتة أثناء عمليات الإنشاء
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |