lousho. ينشئ مشاريع جديدة، ويفحص الإعداد الخاص بك، ويشغّل agent محليًا، ويقدّمه عبر MCP، ويشغّل evals، ويعرض traces محفوظة، ويبني artifact جاهزًا للنشر، ويفتح لوحة Agent Forge. شغّله بـ npx lousho <command> داخل مشروع مثبّت فيه الـ SDK.
أي أمر يستقبل
<spec> يقرأ ملف spec للـ agent (.yaml أو .yml أو .json، انظر الإعداد).
الاستخدام
parseArgs في Node، بالوضع strict): الصيغتان --flag value و--flag=value تعملان، وإذا تكرّر flag تُعتمد آخر قيمة (--tag يجمع القيم بدل ذلك)، و-- تنهي الـ flags، و-h / --help (أو lousho help <command>) يطبع الـ usage الخاص بالأمر والـ flags ويخرج بـ 0. الـ flag غير المعروف، أو الـ flag بدون قيمته (لا يأخذ الـ flag التالي قيمةً له أبدًا)، أو الـ argument الزائد، يفشل بـ LOUSHO_CONFIG_INVALID مع سطر الـ usage. القيمة التي تبدأ بـ - تحتاج صيغة =: --model=-x. --traces هو الـ flag الوحيد الذي قيمته اختيارية: يأخذها فقط بصيغة = (--traces=./t)، فـ--traces agent.yaml يبقى flag متبوعًا بمسار.
Exit codes. كل أمر يخرج بـ 0 عند النجاح، وبـ 1 إذا عمل وفشل (agent لا يمكن تحميله، أو خطأ في البناء، أو فشل بوابة lousho eval، أو عدم وجود trace مطابق، أو رفض lousho add لعنصر بدون --yes)، وبـ 2 لخطأ في الاستخدام: أمر غير معروف، أو flag غير معروف، أو قيمة ناقصة أو غير صالحة، أو argument زائد، أو غياب --target أو مسار الـ agent. وlousho build يطبع المكان الذي كتب فيه الـ build (الافتراضي .lousho/build/<target>) والأمر الذي تشغّله هناك.
.env. الأوامر التي تشغّل agent (dev وchat وacp وmcp)، وdoctor، وeval (الـ judge evals تحتاج مفاتيح الـ providers)، وbuild تحمّل ./.env من مجلد العمل إذا كان موجودًا، مثل node --env-file-if-exists=.env: المتغير المضبوط مسبقًا في البيئة يتغلّب على الملف. وعلامة ترتيب البايتات (BOM) الخاصة بـ UTF-8 في بداية الملف (التي يكتبها Set-Content -Encoding utf8 في PowerShell 5.1) تُتجاهل.
lousho init هو الاستثناء: يحلّل flags بنفسه، وأي flag أو قيمة غير صالحة يفشل بـ InitUsageError — تُطبع رسالته كما هي ويكون exit code هو 2 — لا بمسار LOUSHO_CONFIG_INVALID المشترك. الـ flags القصيرة الوحيدة غير -h هي -y بدل --yes، في init وفي add.
وlousho eval يقبل أيضًا --config <file> ليعمل على ملف إعداد vitest الخاص بك بدلًا من المولَّد؛ وعندها تعمل الـ globs كـ filters لـ vitest على ملفات ذلك الإعداد.
npm create lousho my-agent يشغّل lousho init بنفس الـ arguments. ولإنشاء مشروع على build غير منشور من الـ SDK، مرّر --sdk-path (انظر التثبيت من build محلي).
lousho dev
channels/ تحت /channels وتعمل schedules/ (وكلاهما يُستبدل عند الـ reload، بعد إيقاف الـ schedules القديمة أولًا)؛ ومع --no-schedules لا يعمل أي schedule. انظر Agent directories.
يقدّم chat UI على GET /، وGET /health، وGET /dev/status، وendpoints الـ chat أدناه (حد حجم الـ body هو 1MB). ومعنى <path> يُستنتج من المسار نفسه:
أي امتداد آخر، أو مسار غير موجود، أو module بلا export للـ agent، يفشل بخطأ له كود (
LOUSHO_SPEC_UNSUPPORTED_FORMAT أو LOUSHO_CONFIG_INVALID) مع الـ fix. ملف .ts يستورده Node نفسه وقت التشغيل (الإصدار 22.18 أو أحدث يزيل الـ types، لذا يجب أن تذكر الـ imports النسبية امتداد الملف)؛ استخدم .js للكود الذي يحتاج transpiler.
Chat sessions. واجهة الـ chat تحتفظ بـ session واحدة لكل تبويب في المتصفح (المعرّف في sessionStorage؛ وزر “New session” يبدأ واحدة أخرى) وتعرض الـ turn أثناء الـ streaming: النص فور وصوله، والـ tool calls مع arguments ونتائجها، والأخطاء، والـ tokens والتكلفة من run.done. الـ tool call الذي يحتاج approval يعرض زرّي Approve / Reject؛ والـ ask_question call يعرض خياراته كأزرار مع حقل نص حر. الـ endpoints نفسها تعمل من curl أو من صفحتك:
--traces (أو --traces=<dir>) يكتب كل run في ملفات traces محلية عبر fileTraceExporter()، في .lousho/traces إلا إذا سمّيت مجلدًا، فيعرض npx lousho traces ماذا فعل الـ agent. هو معطّل افتراضيًا لأن الملفات تحتوي محتوى الـ prompts وarguments ونتائج الـ tools، والـ flag يطبع المجلد الذي يكتب فيه. ينطبق على ملفات spec ومجلدات الـ agents والـ modules بالتساوي (الـ exporter الخاص بالـ module يُستبدل ما دام الـ flag مضبوطًا). انظر Local traces.
الـ sessions موجودة في memoryStore() داخل العملية (تختفي إذا أوقفت lousho dev)، أو في الـ store الخاص بالـ agent إذا ضبطته خيارات createAgent() في الـ module. تكملة الـ approval تُرسل streaming هي الأخرى: الـ endpoint يشغّلها بـ agent.approvals.streamResolve() (أو streamAnswer() إذا كان سؤالًا) ويرسل events الـ turn المكمّل — الـ tool call المبتوت فيه، والـ text deltas، وتوقفًا آخر محتملًا، وrun.done — فور حدوثها.
سيرفرات lousho build (node-server وdocker) تقدّم نفس الـ endpoints من نفس الكود، مع sessions في store تحدده LOUSHO_STORE وbearer auth اختيارية: انظر Deployment: HTTP API.
Hot reload. يُعاد بناء الـ agent بعد لحظة (100 ms) من تغيّر ملف، بدون إعادة تشغيل السيرفر وبدون خسارة الـ port:
- في حالة spec: ملف الـ spec نفسه؛
- في حالة مجلد: كل ما تحته (
instructions.md، وملف الإعداد، وtools/، وskills/، وsubagents/)، ما عداnode_modulesو.git؛ - في حالة module: الملف والملفات المحلية التي يستوردها (الـ specifiers النسبية في
import/require، تُكتشف مرة واحدة عند بدء التشغيل؛ بلا bundler).
?t=<time> يكسر الـ cache، فأي ملف tool أو agent عدّلته يُعاد تقييمه، وكذلك الملفات المحلية التي يستوردها بـ specifier نسبي (مثل ./lib/helper.ts مشترك): الـ query يُمرَّر إليها. أما الحزم تحت node_modules فتبقى في الـ cache؛ أعد تشغيل lousho dev بعد تغيير واحدة منها. الـ console يسجّل ما أُعيد تحميله. الـ agent الجديد يُبنى (وينتظر ready()، فتتصل سيرفرات MCP) قبل أن يحل محل القديم، ثم يُستدعى close() على القديم. إذا فشلت إعادة البناء، يظل آخر agent سليم يرد، والخطأ يُسجَّل ويظهر في banner على صفحة الـ chat (وفي error ضمن GET /dev/status)؛ وأول تعديل ناجح يزيله. الـ sessions تنجو من الـ reload: الـ store يعيش أكثر من تبديل الـ agent، فالرسالة التالية تكمل المحادثة على الـ agent الجديد. الـ approval الذي كان معلّقًا على الـ agent القديم لا يعرفه الجديد (404)؛ ابدأ session جديدة.
المجلدات والـ modules هي كودك وتعمل بصلاحياتك؛ لا تشغّل lousho dev إلا على ما تثق به.
--port- الافتراضي3737.--host- الافتراضي127.0.0.1(localhost فقط). مرّر مثلًا--host=0.0.0.0لتفعّل الوصول من الـ LAN؛ وlousho devبلا auth ويعرض أخطاء الـ provider الخام، فيطبع عندها تحذيرًا.--allowed-hosts a,b- أسماء hosts إضافية مسموح أن يحملها الـ headerHost. لمنع DNS rebinding (صفحة ويب تعيد توجيه نطاقها هي إلى جهازك)، كل route ما عدا/healthوالـ channels التي تعملverifyلطلباتها يرد بـ403(LOUSHO_REQUEST_FORBIDDEN) إلا إذا كانHostهوlocalhostأو عنوان127.x.x.xأو[::1]؛ وخارج الـ loopback تُقبل أيضًا عناوين IP واسم--host. القائمة تضيف إلى هذه القاعدة (اسم tunnel مثلًا)؛ و*تقبل أي host. الـ channel التي بلاverify(httpChannel()بدونverify) تُفحص مثل routes التطوير، فلا تصل إليها عبر tunnel إلا واسمه في القائمة.- يجب أن تكون أجسام طلبات POST
Content-Type: application/json(وإلا415)، وطلب POST من متصفح من origin آخر يُرد بـ403، كما على السيرفر المنشور (Cross-site requests).
lousho chat
<path> يُحمَّل كما يحمّله lousho dev (ملف spec، أو مجلد agent، أو module .ts/.js، انظر lousho dev)؛ والمسار غير الموجود أو الامتداد غير الصالح يفشل بنفس الخطأ الذي له كود (LOUSHO_CONFIG_INVALID أو LOUSHO_SPEC_UNSUPPORTED_FORMAT)، وكذلك معرّف --session غير الصالح (LOUSHO_SESSION_ID_INVALID).
- يُكتب النص فور أن ينتجه الـ model. كل tool call سطر واحد باهت،
[tool_name] {args}، يتبعه-> result(أو-> error: ...). - الـ tool call الذي يحتاج approval يسأل
Approve <tool>(args)? [y/N]:yأوyesتشغّله، وغيرهما يرفضه والـ model يكمل. الـask_questioncall (askQuestion: true) يطبع السؤال مع خيارات مرقّمة؛ أجب بالرقم أو بنص حر. - بعد كل turn يعرض
[usage]الـ tokens، والتكلفة أيضًا إذا كانت أسعار كل الـ models المستخدمة معروفة (~تعني أن الـ tokens مقدّرة). - أخطاء الـ SDK تُطبع مع الكود
[LOUSHO_...]والـ fix، والـ session تكمل. وفشل الـ provider يذكر أيضًا فئته وحالة HTTP، مثلerror: User not found. (auth-failure, HTTP 401)لمفتاح API خاطئ. --tracesأو--traces=<dir>يكتب runs الـ session في ملفات traces محلية، كما فيlousho dev؛ وسطر على stderr يوضح المكان.
الـ REPL نفسه هو
runChatRepl() في src/cli/chatRepl.ts؛ يأخذ أسطر الإدخال وoutput stream وfactory للـ agent، فيمكن اختباره بأسطر scripted وagent مبني على mockModel وبدون terminal.
lousho build
--out (الافتراضي .lousho/build/<target>) ويطبع أمر تشغيله أو نشره. البناء يحتاج tsup (npm install --save-dev tsup). الـ targets والـ HTTP API الذي تقدّمه وحدود Workers كلها في النشر.
lousho studio
.lousho/ في المجلد الحالي. في التطبيق قائمة تنقّل على اليسار: Agents (الـ builder) وPlayground، وبعدها Traces وThreads وMonitoring، وEvaluations (Scores وDatasets وEvaluators وAnnotation queues)، وPrompts وContext Hub وSettings؛ وكل ما بعد الـ Playground يقرأ من الـ daemon الخاص بـ lousho observe. انظر Agent Forge للشاشات وللـ walkthrough.
lousho observe
LOUSHO_OBSERVE مضبوطًا: الـ traces، ومراقبة الأسطول (fleet)، ونتائج الـ evals، وسجل الـ prompts، والـ context hub، كلها في ملف SQLite واحد (الافتراضي ~/.lousho/observe.db). شاشات الـ daemon في Studio تقرأ منه. الأمر start يأخذ --port (أو LOUSHO_OBSERVE_PORT) و--db و--host و--require-token، و--webhook الذي تستطيع تكراره لخطافات التنبيه. كل daemon يكتب ملف <db name>.pid خاصًا به بجانب الـ db (observe.db يعطي observe.pid)، فلا تتشارك قاعدتا بيانات في المجلد نفسه pidfile أبدًا. start يخرج بـ 1 عندما يكون الـ port يخدم db أخرى بالفعل، وstop يرفض إرسال signal عندما يبلّغ الـ daemon الموجود على port الـ pidfile عن db أخرى أو يرد الـ port كخدمة أخرى، ويعود إلى إرسال الـ signal عندما لا يستطيع التحقق (لا يصل إليه شيء، أو pidfile قديم من سطر واحد). /health يذكر أي db يخدمها الـ daemon للمستدعين على الجهاز نفسه فقط. انظر الـ observe daemon.
start --retention-days N يحدد مدة حفظ الـ runs المنتهية (الافتراضي 30؛ و0 يحفظ كل شيء). مرة في اليوم يحذف الـ daemon الـ traces التي انتهت كل الـ observations فيها قبل أكثر من N يومًا. الـ trace الذي فيه أي run لا يزال مفتوحًا، والـ session التي لا تزال active، تُحفظ مهما كان عمرها. الـ rollups والـ prompts ومدخلات الـ hub لا تُحذف أبدًا. prune --older-than <N>d (أيام كاملة، N >= 1) يجري المرور نفسه الآن، ويطبع عدد الـ observations والـ scores والـ sessions التي حذفها، ثم يشغّل VACUUM لكي يسترجع مساحة القرص (المرور اليومي لا يفعل ذلك أبدًا). إذا فشل VACUUM وحده (مثلًا لأن الـ db مشغولة)، يبقى الـ prune مثبّتًا، ويذهب الخطأ إلى stderr ويكون كود الخروج 0. تشغيله آمن والـ daemon قيد التشغيل. وقيمة N الخاطئة خطأ استخدام (exit 2). انظر الاحتفاظ.
start --session-idle-minutes N يحدد متى تُحسب المحادثة منتهية (الافتراضي 30؛ و0 يعطّله، فتظل الـ session active إلى أن يتعطّل الـ agent الخاص بها). يعلّم مرور الـ daemon الـ session كـ ended بمجرد ألا يكون فيها run مفتوح (الـ run المعلّم interrupted لا يُحسب) وألا يبدأ فيها شيء أو ينتهي لمدة N دقيقة؛ وended_at الخاص بها هو وقت آخر نشاط. الـ run الجديد في session ended (أو interrupted) يعيدها active. وتُحذف الـ sessions المنتهية لاحقًا بـ --retention-days مثل أي session منتهية أخرى. وقيمة N الخاطئة خطأ استخدام (exit 2). انظر الـ sessions الخاملة.
export يكتب الـ traces كـ JSONL: سطر لكل trace، { trace, observations, scores } (الصفوف نفسها التي يعيدها trace API)، الأقدم أولًا، دون حد للعدد. --since <N>d (أو <N>h و<N>m) يُبقي الـ traces التي بدأت داخل هذه النافذة؛ و--agent X يُبقي agent واحدًا، يتطابق بـ agent_id أو، عندما لا يوجد agent بهذا الـ id، بالاسم المسجّل الخاص به (الاسم الذي يتشاركه agentان خطأ استخدام، exit 2). دون --out تذهب الأسطر إلى stdout ولا يذهب إليه شيء آخر (يذهب العدد إلى stderr، فيظل الـ pipe نظيفًا)؛ و--out file ينشئ الملف أو يكتب فوقه ويطبع العدد على stdout. يقرأ الـ db مباشرة، فلا يحتاج إلى daemon قيد التشغيل. انظر التصدير.
lousho prompt
createAgent({ prompt: 'mira@latest' }) (أو بـ label، 'mira@prod') أو بـ LOUSHO_PROMPT.
pushينشر الملف (-يقرأ من stdin) كالإصدار التالي. الـ push الذي يطابق نصه و--variablesالخاصة به آخر إصدار لا ينشئ شيئًا ويطبعmira@2 is unchanged(exit 0). و--labels prod,canaryيوجّه هذه الـ labels إلى الإصدار الناتج، سواء كان الجديد أو آخر إصدار لم يتغيّر.get <name>[@ref]يطبع نص الإصدار؛ وrefرقم صحيح، أوlatest(الافتراضي)، أو label. و--jsonيطبع الصف، وlabelsفيه هي الـ labels التي تشير حاليًا إلى هذا الإصدار.label <name> <label> <version>ينقل label: الـ label يشير إلى إصدار واحد بالضبط، فهذا يزيله من الإصدار الذي كان عليه، ويطبعmira@prod -> 3 (was 2)(أو(was unset)لـ label جديد). الـ label اسم دون مسافات ولا@ولا/، وليسlatestولا أرقامًا فقط. انظر الـ observe daemon.
lousho improve
تجريبي، مثل improveAgent() الذي يشغّله.
~/.lousho/observe.db، أو --db)، ويعيد تشغيل كل input مسجَّل عبر الـ agent،
ويقيّم كل إجابة بالفحص الخاص بك، ثم يطبع بطاقة المراجعة الناتجة عن
formatImproveResult(). ولا يغيّر الـ agent أبدًا: لا يُكتب أي ملف في مجلد
الـ agent، ولا يوجد flag لتطبيق الاقتراح. راجع البطاقة وطبّق ما تقبله يدويًا.
<path>مجلد agent أو module للـ agent بامتداد.ts/.jsتعليماته نص عادي. ولا يجوز للمحرّرين (editors) تغيير شيء سوى التعليمات والـ skills.--check <module>إلزامي. الـ default export الخاص به هوCaseCheck، أي(input, answer) => boolean | null؛ وتعنيnullأن الإجابة لا يمكن تقييمها. وinputهو رسالة المستخدم في run ذي رسالة واحدة، وإلا فهو الرسائل المسجَّلة بصيغة نص JSON.- يحدّد
--sinceو--agentأيّ الـ runs الفاشلة تصبح حالات (cases)، كما فيlousho observe export. - يسمّي
--protect <traceId>run انتهى بنجاح. ولا ينضم إلى البوابة (gate) إلا بعد أن ينجح في 6 من 6 runs جديدة؛ وإلا يوضّح stderr سبب استبعاده. والـ trace الذي يكون أيضًا run فاشلًا يبقى حالةً يُتعلَّم منها. - تُحاكى الـ tools أثناء إعادة التشغيل، باستثناء
load_skillوread_skill_file. ويسمح--read-only <tool>لـ tool يمكن استدعاؤها مرة أخرى بأمان بأن تعمل فعلًا. ولا تُسجَّل traces لإعادة التشغيل: يكونLOUSHO_OBSERVEوexporterوonEventالخاصة بالـ agent معطّلة أثناء عمله، فلا تصل أبدًا إلى قاعدة بياناتك. - يشغّل
--modelالـ agent على model آخر؛ ويختار--editorالـ model الخاص بالمحرّرين (الافتراضي--model، وإلا فالـ model الخاص بالـ agent نفسه). - يكتب
--out fileالبطاقة أيضًا، أو نتيجة JSON إذا كان المسار.json. ويجب أن يكون ملفًا جديدًا، خارج ملفات الـ agent.
outage: أي حين
يتعذّر تقييم أي run، أو حين يفشل الـ provider الخاص بالمحرّرين. ويذهب خطأ كل run
إلى stderr. ولا يقرأ شيئًا سوى قاعدة بياناتك. راجع تحسين الـ agent.