{"title":"الأدوات المساعدة (الوقت، الحاسبة، عشوائي)","slug":"tools","category":"api","summary":"نقاط نهاية الأدوات العامة — وقت الخادم، حاسبة آمنة، مولّد قيم عشوائية. لا تتطلب مصادقة.","audience":["human","llm"],"tags":["api","tools","utility","public"],"difficulty":"beginner","updated":"2026-06-27","word_count":236,"read_minutes":1,"llm_context":"No auth required for any /tools/* endpoint.\nGET /tools/time → { time, timezone, offset }\nGET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)\nGET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)\nUse case: LLM agents that need current time, safe math, or random values.\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# الأدوات المساعدة\n\nنقاط النهاية `/tools` أدوات عامة — لا تتطلب مصادقة.\nمفيدة لوكلاء LLM الذين يحتاجون وقتًا من جانب الخادم، أو حسابات آمنة، أو قيمًا\nعشوائية.\n\n## GET /tools/time\n\nالحصول على وقت الخادم الحالي، والمنطقة الزمنية، وإزاحة UTC.\n\n```bash\ncurl https://synapse.schaefer.zone/tools/time\n```\n\nالاستجابة:\n\n```json\n{\n  \"time\": \"2026-06-27T14:30:00.000Z\",\n  \"timezone\": \"Europe/Berlin\",\n  \"offset\": 120\n}\n```\n\nحالة الاستخدام: وكلاء LLM الذين يحتاجون معرفة \"كم الساعة الآن\" للجدولة،\nأو الطوابع الزمنية، أو حسابات التاريخ النسبية.\n\n## GET /tools/calc\n\nحاسبة آمنة — حسابات حسابية فقط، دون `eval()`. تدعم `+`، `-`، `*`، `/`،\n`%`، `(`، `)`، والأرقام.\n\n```bash\ncurl \"https://synapse.schaefer.zone/tools/calc?expr=(10+5)*3\"\n```\n\nالاستجابة:\n\n```json\n{\n  \"result\": 45,\n  \"expr\": \"(10+5)*3\"\n}\n```\n\n> [!TIP]\n> استخدم هذا بدلاً من محاولة إجراء الحسابات ذهنيًا أو عبر تحليل السلاسل.\n> إنه آمن (لا يُمكن حقن كود) ودقيق.\n\n### المعاملات المدعومة\n\n- `+` جمع\n- `-` طرح\n- `*` ضرب\n- `/` قسمة\n- `%` باقي القسمة\n- `(` `)` أقواس\n- أرقام (صحيحة وعشرية)\n\n### أمثلة\n\n```bash\ncurl \".../tools/calc?expr=2+2\"          # → 4\ncurl \".../tools/calc?expr=3.14*100\"     # → 314\ncurl \".../tools/calc?expr=100%7\"        # → 2\ncurl \".../tools/calc?expr=(2+3)*4-1\"    # → 19\n```\n\n## GET /tools/random\n\nتوليد قيم عشوائية.\n\n```bash\n# UUID v4\ncurl \"https://synapse.schaefer.zone/tools/random?type=uuid\"\n# → { \"value\": \"a1b2c3d4-...\", \"type\": \"uuid\" }\n\n# عدد صحيح (النطاق الافتراضي 0-100)\ncurl \"https://synapse.schaefer.zone/tools/random?type=int&min=1&max=10\"\n# → { \"value\": 7, \"type\": \"int\" }\n\n# عدد عشري\ncurl \"https://synapse.schaefer.zone/tools/random?type=float&min=0&max=1\"\n# → { \"value\": 0.7234, \"type\": \"float\" }\n\n# سلسلة hex\ncurl \"https://synapse.schaefer.zone/tools/random?type=hex&min=8&max=16\"\n# → { \"value\": \"a3f7b2c1\", \"type\": \"hex\" }\n\n# سلسلة أبجدية\ncurl \"https://synapse.schaefer.zone/tools/random?type=alpha&min=8&max=12\"\n# → { \"value\": \"kQmzPwXn\", \"type\": \"alpha\" }\n```\n\n### معاملات النوع\n\n| النوع | المعاملات | المخرجات |\n|------|-----------|--------|\n| `uuid` | لا شيء | سلسلة UUID v4 |\n| `int` | `min`، `max` (افتراضي 0-100) | عدد صحيح |\n| `float` | `min`، `max` (افتراضي 0-100) | عدد عشري |\n| `hex` | `min`، `max` (نطاق الطول، افتراضي 8-16) | سلسلة hex |\n| `alpha` | `min`، `max` (نطاق الطول، افتراضي 8-16) | سلسلة أبجدية |\n\n## حالات الاستخدام لوكلاء LLM\n\n### توليد معرّفات فريدة\n\n```bash\nID=$(curl -s .../tools/random?type=uuid | jq -r .value)\ncurl -X POST .../memory -d \"{\\\"key\\\": \\\"task_$ID\\\", ...}\"\n```\n\n### حساب النسب المئوية\n\n```bash\nTOTAL=142\nDONE=87\nPERCENT=$(curl -s \".../tools/calc?expr=($DONE*100)/$TOTAL\" | jq -r .result)\necho \"Progress: $PERCENT%\"\n```\n\n### الحصول على الطابع الزمني الحالي\n\n```bash\nNOW=$(curl -s .../tools/time | jq -r .time)\ncurl -X POST .../var -d \"{\\\"key\\\": \\\"last_run\\\", \\\"value\\\": \\\"$NOW\\\"}\"\n```\n\n### توليد بيانات اختبار\n\n```bash\nfor i in {1..10}; do\n  NAME=$(curl -s \".../tools/random?type=alpha&min=5&max=10\" | jq -r .value)\n  curl -X POST .../memory -d \"{\\\"key\\\": \\\"test_$i\\\", \\\"content\\\": \\\"$NAME\\\"}\"\ndone\n```\n\n## الخطوات التالية\n\n- [نظرة عامة على الـ API](/docs/api/overview) — جميع مجموعات نقاط النهاية\n- [الأخطاء ومعالجتها](/docs/api/errors)\n","content_html":"<h1>الأدوات المساعدة</h1>\n<p>نقاط النهاية <code>/tools</code> أدوات عامة — لا تتطلب مصادقة.\nمفيدة لوكلاء LLM الذين يحتاجون وقتًا من جانب الخادم، أو حسابات آمنة، أو قيمًا\nعشوائية.</p>\n<h2>GET /tools/time</h2>\n<p>الحصول على وقت الخادم الحالي، والمنطقة الزمنية، وإزاحة UTC.</p>\n<pre><code class=\"hljs language-bash\">curl https://synapse.schaefer.zone/tools/time</code></pre><p>الاستجابة:</p>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;time&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;2026-06-27T14:30:00.000Z&quot;</span><span class=\"hljs-punctuation\">,</span>\n  <span class=\"hljs-attr\">&quot;timezone&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;Europe/Berlin&quot;</span><span class=\"hljs-punctuation\">,</span>\n  <span class=\"hljs-attr\">&quot;offset&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-number\">120</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><p>حالة الاستخدام: وكلاء LLM الذين يحتاجون معرفة &quot;كم الساعة الآن&quot; للجدولة،\nأو الطوابع الزمنية، أو حسابات التاريخ النسبية.</p>\n<h2>GET /tools/calc</h2>\n<p>حاسبة آمنة — حسابات حسابية فقط، دون <code>eval()</code>. تدعم <code>+</code>، <code>-</code>، <code>*</code>، <code>/</code>،\n<code>%</code>، <code>(</code>، <code>)</code>، والأرقام.</p>\n<pre><code class=\"hljs language-bash\">curl <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/tools/calc?expr=(10+5)*3&quot;</span></code></pre><p>الاستجابة:</p>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;result&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-number\">45</span><span class=\"hljs-punctuation\">,</span>\n  <span class=\"hljs-attr\">&quot;expr&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;(10+5)*3&quot;</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><div class=\"callout callout-ok\">استخدم هذا بدلاً من محاولة إجراء الحسابات ذهنيًا أو عبر تحليل السلاسل.\nإنه آمن (لا يُمكن حقن كود) ودقيق.</div><h3>المعاملات المدعومة</h3>\n<ul>\n<li><code>+</code> جمع</li>\n<li><code>-</code> طرح</li>\n<li><code>*</code> ضرب</li>\n<li><code>/</code> قسمة</li>\n<li><code>%</code> باقي القسمة</li>\n<li><code>(</code> <code>)</code> أقواس</li>\n<li>أرقام (صحيحة وعشرية)</li>\n</ul>\n<h3>أمثلة</h3>\n<pre><code class=\"hljs language-bash\">curl <span class=\"hljs-string\">&quot;.../tools/calc?expr=2+2&quot;</span>          <span class=\"hljs-comment\"># → 4</span>\ncurl <span class=\"hljs-string\">&quot;.../tools/calc?expr=3.14*100&quot;</span>     <span class=\"hljs-comment\"># → 314</span>\ncurl <span class=\"hljs-string\">&quot;.../tools/calc?expr=100%7&quot;</span>        <span class=\"hljs-comment\"># → 2</span>\ncurl <span class=\"hljs-string\">&quot;.../tools/calc?expr=(2+3)*4-1&quot;</span>    <span class=\"hljs-comment\"># → 19</span></code></pre><h2>GET /tools/random</h2>\n<p>توليد قيم عشوائية.</p>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># UUID v4</span>\ncurl <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/tools/random?type=uuid&quot;</span>\n<span class=\"hljs-comment\"># → { &quot;value&quot;: &quot;a1b2c3d4-...&quot;, &quot;type&quot;: &quot;uuid&quot; }</span>\n\n<span class=\"hljs-comment\"># عدد صحيح (النطاق الافتراضي 0-100)</span>\ncurl <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/tools/random?type=int&amp;min=1&amp;max=10&quot;</span>\n<span class=\"hljs-comment\"># → { &quot;value&quot;: 7, &quot;type&quot;: &quot;int&quot; }</span>\n\n<span class=\"hljs-comment\"># عدد عشري</span>\ncurl <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/tools/random?type=float&amp;min=0&amp;max=1&quot;</span>\n<span class=\"hljs-comment\"># → { &quot;value&quot;: 0.7234, &quot;type&quot;: &quot;float&quot; }</span>\n\n<span class=\"hljs-comment\"># سلسلة hex</span>\ncurl <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/tools/random?type=hex&amp;min=8&amp;max=16&quot;</span>\n<span class=\"hljs-comment\"># → { &quot;value&quot;: &quot;a3f7b2c1&quot;, &quot;type&quot;: &quot;hex&quot; }</span>\n\n<span class=\"hljs-comment\"># سلسلة أبجدية</span>\ncurl <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/tools/random?type=alpha&amp;min=8&amp;max=12&quot;</span>\n<span class=\"hljs-comment\"># → { &quot;value&quot;: &quot;kQmzPwXn&quot;, &quot;type&quot;: &quot;alpha&quot; }</span></code></pre><h3>معاملات النوع</h3>\n<table>\n<thead>\n<tr>\n<th>النوع</th>\n<th>المعاملات</th>\n<th>المخرجات</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>uuid</code></td>\n<td>لا شيء</td>\n<td>سلسلة UUID v4</td>\n</tr>\n<tr>\n<td><code>int</code></td>\n<td><code>min</code>، <code>max</code> (افتراضي 0-100)</td>\n<td>عدد صحيح</td>\n</tr>\n<tr>\n<td><code>float</code></td>\n<td><code>min</code>، <code>max</code> (افتراضي 0-100)</td>\n<td>عدد عشري</td>\n</tr>\n<tr>\n<td><code>hex</code></td>\n<td><code>min</code>، <code>max</code> (نطاق الطول، افتراضي 8-16)</td>\n<td>سلسلة hex</td>\n</tr>\n<tr>\n<td><code>alpha</code></td>\n<td><code>min</code>، <code>max</code> (نطاق الطول، افتراضي 8-16)</td>\n<td>سلسلة أبجدية</td>\n</tr>\n</tbody></table>\n<h2>حالات الاستخدام لوكلاء LLM</h2>\n<h3>توليد معرّفات فريدة</h3>\n<pre><code class=\"hljs language-bash\">ID=$(curl -s .../tools/random?<span class=\"hljs-built_in\">type</span>=uuid | jq -r .value)\ncurl -X POST .../memory -d <span class=\"hljs-string\">&quot;{\\&quot;key\\&quot;: \\&quot;task_<span class=\"hljs-variable\">$ID</span>\\&quot;, ...}&quot;</span></code></pre><h3>حساب النسب المئوية</h3>\n<pre><code class=\"hljs language-bash\">TOTAL=142\nDONE=87\nPERCENT=$(curl -s <span class=\"hljs-string\">&quot;.../tools/calc?expr=(<span class=\"hljs-variable\">$DONE</span>*100)/<span class=\"hljs-variable\">$TOTAL</span>&quot;</span> | jq -r .result)\n<span class=\"hljs-built_in\">echo</span> <span class=\"hljs-string\">&quot;Progress: <span class=\"hljs-variable\">$PERCENT</span>%&quot;</span></code></pre><h3>الحصول على الطابع الزمني الحالي</h3>\n<pre><code class=\"hljs language-bash\">NOW=$(curl -s .../tools/time | jq -r .<span class=\"hljs-keyword\">time</span>)\ncurl -X POST .../var -d <span class=\"hljs-string\">&quot;{\\&quot;key\\&quot;: \\&quot;last_run\\&quot;, \\&quot;value\\&quot;: \\&quot;<span class=\"hljs-variable\">$NOW</span>\\&quot;}&quot;</span></code></pre><h3>توليد بيانات اختبار</h3>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-keyword\">for</span> i <span class=\"hljs-keyword\">in</span> {1..10}; <span class=\"hljs-keyword\">do</span>\n  NAME=$(curl -s <span class=\"hljs-string\">&quot;.../tools/random?type=alpha&amp;min=5&amp;max=10&quot;</span> | jq -r .value)\n  curl -X POST .../memory -d <span class=\"hljs-string\">&quot;{\\&quot;key\\&quot;: \\&quot;test_<span class=\"hljs-variable\">$i</span>\\&quot;, \\&quot;content\\&quot;: \\&quot;<span class=\"hljs-variable\">$NAME</span>\\&quot;}&quot;</span>\n<span class=\"hljs-keyword\">done</span></code></pre><h2>الخطوات التالية</h2>\n<ul>\n<li><a href=\"/docs/api/overview\">نظرة عامة على الـ API</a> — جميع مجموعات نقاط النهاية</li>\n<li><a href=\"/docs/api/errors\">الأخطاء ومعالجتها</a></li>\n</ul>\n","urls":{"html":"/docs/api/tools","text":"/docs/api/tools?format=text","json":"/docs/api/tools?format=json","llm":"/docs/api/tools?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}