tools.mdx 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. ---
  2. title: الأدوات
  3. description: إدارة الأدوات التي يمكن لـ LLM استخدامها.
  4. ---
  5. تتيح الأدوات لـ LLM تنفيذ إجراءات داخل قاعدة الشفرة الخاصة بك. يأتي OpenCode مع مجموعة من الأدوات المدمجة، لكن يمكنك توسيعه عبر [أدوات مخصصة](/docs/custom-tools) أو [خوادم MCP](/docs/mcp-servers).
  6. افتراضيا، تكون جميع الأدوات **مفعلة** ولا تحتاج إلى إذن للتشغيل. يمكنك التحكم في سلوك الأدوات عبر [الأذونات](/docs/permissions).
  7. ---
  8. ## التهيئة
  9. استخدم الحقل `permission` للتحكم في سلوك الأدوات. يمكنك السماح أو الرفض أو طلب الموافقة لكل أداة.
  10. ```json title="opencode.json"
  11. {
  12. "$schema": "https://opencode.ai/config.json",
  13. "permission": {
  14. "edit": "deny",
  15. "bash": "ask",
  16. "webfetch": "allow"
  17. }
  18. }
  19. ```
  20. يمكنك أيضا استخدام أحرف البدل للتحكم في عدة أدوات دفعة واحدة. على سبيل المثال، لطلب الموافقة على جميع الأدوات القادمة من خادم MCP:
  21. ```json title="opencode.json"
  22. {
  23. "$schema": "https://opencode.ai/config.json",
  24. "permission": {
  25. "mymcp_*": "ask"
  26. }
  27. }
  28. ```
  29. [اعرف المزيد](/docs/permissions) حول تهيئة الأذونات.
  30. ---
  31. ## المدمجة
  32. فيما يلي جميع الأدوات المدمجة المتاحة في OpenCode.
  33. ---
  34. ### bash
  35. نفذ أوامر shell في بيئة مشروعك.
  36. ```json title="opencode.json" {4}
  37. {
  38. "$schema": "https://opencode.ai/config.json",
  39. "permission": {
  40. "bash": "allow"
  41. }
  42. }
  43. ```
  44. تتيح هذه الأداة لـ LLM تشغيل أوامر terminal مثل `npm install` و`git status` أو أي أمر shell آخر.
  45. ---
  46. ### edit
  47. عدّل الملفات الموجودة باستخدام استبدال نصي مطابق تماما.
  48. ```json title="opencode.json" {4}
  49. {
  50. "$schema": "https://opencode.ai/config.json",
  51. "permission": {
  52. "edit": "allow"
  53. }
  54. }
  55. ```
  56. تجري هذه الأداة تعديلات دقيقة على الملفات عبر استبدال مقاطع نصية متطابقة. وهي الطريقة الأساسية التي يعدّل بها LLM الشفرة.
  57. ---
  58. ### write
  59. أنشئ ملفات جديدة أو اكتب فوق الملفات الموجودة.
  60. ```json title="opencode.json" {4}
  61. {
  62. "$schema": "https://opencode.ai/config.json",
  63. "permission": {
  64. "edit": "allow"
  65. }
  66. }
  67. ```
  68. استخدم هذا للسماح لـ LLM بإنشاء ملفات جديدة. سيكتب فوق الملفات الموجودة إذا كانت موجودة بالفعل.
  69. :::note
  70. تُدار أداة `write` عبر إذن `edit`، والذي يشمل جميع تعديلات الملفات (`edit` و`write` و`patch`).
  71. :::
  72. ---
  73. ### read
  74. اقرأ محتويات الملفات من قاعدة الشفرة الخاصة بك.
  75. ```json title="opencode.json" {4}
  76. {
  77. "$schema": "https://opencode.ai/config.json",
  78. "permission": {
  79. "read": "allow"
  80. }
  81. }
  82. ```
  83. تقرأ هذه الأداة الملفات وتعيد محتوياتها. وتدعم قراءة نطاقات محددة من الأسطر للملفات الكبيرة.
  84. ---
  85. ### grep
  86. ابحث في محتوى الملفات باستخدام التعابير النمطية (Regex).
  87. ```json title="opencode.json" {4}
  88. {
  89. "$schema": "https://opencode.ai/config.json",
  90. "permission": {
  91. "grep": "allow"
  92. }
  93. }
  94. ```
  95. بحث سريع في المحتوى عبر قاعدة الشفرة الخاصة بك. يدعم صياغة Regex الكاملة وتصفية الملفات عبر أنماط المسارات.
  96. ---
  97. ### glob
  98. اعثر على الملفات عبر مطابقة الأنماط.
  99. ```json title="opencode.json" {4}
  100. {
  101. "$schema": "https://opencode.ai/config.json",
  102. "permission": {
  103. "glob": "allow"
  104. }
  105. }
  106. ```
  107. ابحث عن الملفات باستخدام أنماط glob مثل `**/*.js` أو `src/**/*.ts`. يعيد مسارات الملفات المطابقة مرتبة حسب وقت التعديل.
  108. ---
  109. ### lsp (experimental)
  110. تفاعل مع خوادم LSP التي قمت بتهيئتها للحصول على ميزات ذكاء الشفرة مثل التعاريف والمراجع ومعلومات التحويم وتسلسل الاستدعاءات.
  111. :::note
  112. هذه الأداة متاحة فقط عند ضبط `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (أو `OPENCODE_EXPERIMENTAL=true`).
  113. :::
  114. ```json title="opencode.json" {4}
  115. {
  116. "$schema": "https://opencode.ai/config.json",
  117. "permission": {
  118. "lsp": "allow"
  119. }
  120. }
  121. ```
  122. تتضمن العمليات المدعومة: `goToDefinition` و`findReferences` و`hover` و`documentSymbol` و`workspaceSymbol` و`goToImplementation` و`prepareCallHierarchy` و`incomingCalls` و`outgoingCalls`.
  123. لتهيئة خوادم LSP المتاحة لمشروعك، راجع [خوادم LSP](/docs/lsp).
  124. ---
  125. ### patch
  126. طبّق الرقع (Patches) على الملفات.
  127. ```json title="opencode.json" {4}
  128. {
  129. "$schema": "https://opencode.ai/config.json",
  130. "permission": {
  131. "edit": "allow"
  132. }
  133. }
  134. ```
  135. تطبق هذه الأداة ملفات الرقع على قاعدة الشفرة الخاصة بك. وهي مفيدة لتطبيق الفروقات (Diffs) والرقع من مصادر متعددة.
  136. :::note
  137. تُدار أداة `patch` عبر إذن `edit`، والذي يشمل جميع تعديلات الملفات (`edit` و`write` و`patch`).
  138. :::
  139. ---
  140. ### skill
  141. حمّل [مهارة](/docs/skills) (ملف `SKILL.md`) وأعد محتواها ضمن المحادثة.
  142. ```json title="opencode.json" {4}
  143. {
  144. "$schema": "https://opencode.ai/config.json",
  145. "permission": {
  146. "skill": "allow"
  147. }
  148. }
  149. ```
  150. ---
  151. ### todowrite
  152. أدِر قوائم المهام أثناء جلسات البرمجة.
  153. ```json title="opencode.json" {4}
  154. {
  155. "$schema": "https://opencode.ai/config.json",
  156. "permission": {
  157. "todowrite": "allow"
  158. }
  159. }
  160. ```
  161. تنشئ هذه الأداة قوائم المهام وتحدّثها لتتبع التقدم أثناء العمليات المعقدة. يستخدمها LLM لتنظيم المهام متعددة الخطوات.
  162. :::note
  163. هذه الأداة معطلة للوكلاء الفرعيين افتراضيا، لكن يمكنك تفعيلها يدويا. [اعرف المزيد](/docs/agents/#permissions)
  164. :::
  165. ---
  166. ### webfetch
  167. اجلب محتوى الويب.
  168. ```json title="opencode.json" {4}
  169. {
  170. "$schema": "https://opencode.ai/config.json",
  171. "permission": {
  172. "webfetch": "allow"
  173. }
  174. }
  175. ```
  176. تتيح هذه الأداة لـ LLM جلب صفحات الويب وقراءتها. وهي مفيدة للبحث عن التوثيق أو لاستكشاف موارد عبر الإنترنت.
  177. ---
  178. ### websearch
  179. ابحث في الويب عن معلومات.
  180. :::note
  181. هذه الأداة متاحة فقط عند استخدام مزود OpenCode أو عند ضبط متغير البيئة `OPENCODE_ENABLE_EXA` على أي قيمة منطقية صحيحة (مثل `true` أو `1`).
  182. للتفعيل عند تشغيل OpenCode:
  183. ```bash
  184. OPENCODE_ENABLE_EXA=1 opencode
  185. ```
  186. :::
  187. ```json title="opencode.json" {4}
  188. {
  189. "$schema": "https://opencode.ai/config.json",
  190. "permission": {
  191. "websearch": "allow"
  192. }
  193. }
  194. ```
  195. تجري عمليات بحث على الويب باستخدام Exa AI للعثور على معلومات ذات صلة عبر الإنترنت. وهي مفيدة للبحث في المواضيع، والعثور على أحداث جارية، أو جمع معلومات تتجاوز حد بيانات التدريب.
  196. لا يلزم مفتاح API - إذ تتصل الأداة مباشرة بخدمة MCP المستضافة لدى Exa AI دون مصادقة.
  197. :::tip
  198. استخدم `websearch` عندما تحتاج إلى العثور على معلومات (Discovery)، واستخدم `webfetch` عندما تحتاج إلى جلب محتوى من رابط محدد (Retrieval).
  199. :::
  200. ---
  201. ### question
  202. اطرح على المستخدم أسئلة أثناء التنفيذ.
  203. ```json title="opencode.json" {4}
  204. {
  205. "$schema": "https://opencode.ai/config.json",
  206. "permission": {
  207. "question": "allow"
  208. }
  209. }
  210. ```
  211. تتيح هذه الأداة لـ LLM طرح أسئلة على المستخدم أثناء المهمة. وهي مفيدة من أجل:
  212. - جمع تفضيلات المستخدم أو متطلباته
  213. - توضيح التعليمات غير الواضحة
  214. - الحصول على قرارات حول خيارات التنفيذ
  215. - تقديم خيارات حول الاتجاه الذي يجب اتباعه
  216. يتضمن كل سؤال عنوانا ونص السؤال وقائمة بالخيارات. يمكن للمستخدمين الاختيار من الخيارات المتاحة أو كتابة إجابة مخصصة. وعند وجود عدة أسئلة، يمكن للمستخدمين التنقل بينها قبل إرسال جميع الإجابات.
  217. ---
  218. ## أدوات مخصصة
  219. تتيح لك الأدوات المخصصة تعريف دوالك الخاصة التي يمكن لـ LLM استدعاؤها. تُعرّف هذه الأدوات في ملف التهيئة ويمكنها تنفيذ شفرة عشوائية.
  220. [اعرف المزيد](/docs/custom-tools) حول إنشاء أدوات مخصصة.
  221. ---
  222. ## خوادم MCP
  223. تتيح لك خوادم MCP (Model Context Protocol) دمج أدوات وخدمات خارجية. يشمل ذلك الوصول إلى قواعد البيانات وتكاملات API وخدمات الجهات الخارجية.
  224. [اعرف المزيد](/docs/mcp-servers) حول تهيئة خوادم MCP.
  225. ---
  226. ## التفاصيل الداخلية
  227. داخليا، تستخدم أدوات مثل `grep` و`glob` [ripgrep](https://github.com/BurntSushi/ripgrep) في الخلفية. افتراضيا، يحترم ripgrep أنماط `.gitignore`، ما يعني أن الملفات والمجلدات المدرجة في `.gitignore` ستُستبعد من عمليات البحث وعرض القوائم.
  228. ---
  229. ### أنماط التجاهل
  230. لتضمين ملفات يتم تجاهلها عادة، أنشئ ملف `.ignore` في جذر المشروع. يمكن لهذا الملف السماح صراحة بمسارات محددة.
  231. ```text title=".ignore"
  232. !node_modules/
  233. !dist/
  234. !build/
  235. ```
  236. على سبيل المثال، يسمح ملف `.ignore` هذا لـ ripgrep بالبحث داخل مجلدات `node_modules/` و`dist/` و`build/` حتى لو كانت مدرجة في `.gitignore`.