صيغ الملفات — الوثائق

القواعد

ملفات عادية فقط. أكثر ما يفعله الملف هو النمو أثناء التسجيل — ملف records.jsonl الخاص بالتدفق، وملف الوسائط الخاص به، وملف members.jsonl الخاص بالتشغيل. لا توجد قواعد بيانات مخفية، ولا ملفات مؤشرات، ولا حزم.
المراجع مسارات ومعرّفات. يستخدم التشغيل الأصل الموجود في مساره الآن؛ ولا يثبّت أي تشغيل تجزئة (hash).
المجلد هو المشروع. لا يُكتب تخطيط المشروع في منضدة العمل.
المستويات. يمكن أن يوجد كل تعريف وعالم وإعداد في السحابة أو محلياً، على المستوى العام والمستخدم والمشروع، وتُدمج من العام إلى الخاص.

الأجهزة

devices/<id>/definition.tsx، مع أصولها بجانبه في devices/<id>/assets/ (مثل model.glb). التعريف شيفرة: تشغّله منضدة العمل وتقرأ الوسم <device> الذي يعلنه.

يحدد التعريف الآلة (name وmanufacturer وmodel_number وproduct_url …)، ونموذجها ثلاثي الأبعاد model، وchannels الخاصة بها:

tsx

export default () => (
  <device name="CNC 3018" manufacturer="…">
    <channel id="gcode" dir="duplex" medium="records" format="gcode-chat" dialect="grbl" transport="serial" baud={115200} />
  </device>
);

القيمة dir هي in أو out أو duplex؛ والقيمة medium هي records أو video أو audio أو bytes. يمكن لوحدة في عالم أن تتجاوز قناة.

العوالم

worlds/<id>/world.tsx، شيفرة تعلن وسماً واحداً <world>:

tsx

export default () => (
  <world name="Shop floor" kind="physical">
    <space origin_mm={[0, 0, 0]} size_mm={[6000, 4000, 3000]} />
    <unit uid="mill-1" name="Mill" device="../../devices/cnc-3018/definition.tsx" position={[1200, 800, 0]} rotation={0} />
  </world>
);

يُكتب كل تعديل في منضدة العمل مرة أخرى في الشيفرة كأصغر تغيير ممكن.

القيمة kind هي physical أو simulation. يجوز للعالم أن يسمّي مشهداً ثلاثي الأبعاد (model، وهو ملف .3d.tsx)، وإذا كان محاكاة فيمكنه تسمية ملف محاكاة (sim، وهو ملف .sim.json). العالم ليس نموذجاً ثلاثي الأبعاد، والتشغيل ليس عالماً.

التشغيلات والتدفقات

runs/<run>/ تشغيل واحد في عالم واحد:

الملف	يحتوي على
`run.json`	`id` و`world` و`kind` (`session` أو `recipe` أو `thread`) و`started` و`ended` و`from` (التشغيل والوقت اللذان تفرع منهما)
`members.jsonl`	من وما شارك، يُلحق عند الانضمام
`steps.jsonl`	خطوات الوصفة
`streams/<uid>.<channel>@<replica>/`	تدفق واحد: ملف `stream.json` مع بياناته — `records.jsonl`، أو ملف `video.webm`/`.mp4` واحد، أو `audio.webm`/`.mp4`، أو `data.bin`
`streams/chat@<replica>/`	حوار المحادثة
`streams/sim@<replica>/`، `streams/sim-input@<replica>/`	إطارات المحاكاة والمدخلات المطبقة عليها
`evidence/`	ملفات محفوظة كأدلة

السجل سطر واحد من JSON:

json

{ "t": 7.180, "seq": 41, "hlc": "001790561647180-00000", "src": "operator", "kind": "note", "text": "agent:night-shift: run_program", "by": "agent:night-shift" }

القيمة src هي device أو sim أو operator؛ والقيمة kind هي command أو event أو ack أو reply أو state أو evidence أو note؛ ويزداد seq دائماً. تُكتب الحالة غير المعروفة هكذا: { "kind": "state", "status": "unknown" }.

المستندات

كل مستند تحرير هو ملف JSON واحد — { "format": "commandagi-document", "kind", "title", "meta", "body" } — مع الأصول الكبيرة في مجلد <name>.assets/ بجانبه.

الامتداد	يُفتح في
`.3d.tsx`	التصميم ثلاثي الأبعاد (أجزاء وتجميعات ومشاهد)
`.cam.tsx`، `.slice.tsx`	التصميم ثلاثي الأبعاد في وضع CAM والتقطيع؛ تُحفظ البرامج بجانبها كملفات `.gcode`
`.nest.tsx`	وضع التعشيش في تطبيق المتجهات (مهام الليزر والألواح)، في الشيفرة
`.draw.tsx`، `.paint.tsx`، `.img.tsx`	الرسم والتلوين وتحرير الصور، في الشيفرة؛ تبقى البكسلات ملفات صور بجانبها
`.vid.tsx`	محرر الفيديو، في الشيفرة؛ تبقى الوسائط ملفات بجانبه
`.mus.tsx`	الموسيقى، في الشيفرة
`.geo.tsx`	مساحات الاقتصاد الجغرافي

صيغ أخرى

الملف	ما هو
`<name>.sch.tsx` + `<name>.pcb.tsx`	دارة في الشيفرة: المخطط، واللوحة التي تسمّيه
`<name>.sheet.tsx`، `<name>.page.tsx`، `<name>.deck.tsx`	دفتر عمل وصفحة وعرض شرائح، مكتوبة كشيفرة: الأوراق والمستندات والعروض التي تكتب فيها المحررات كل تعديل داخل الملف
`<name>.sim.json`	محاكاة
`<name>.trials.json`	تجربة: تشغيلات محاكاة كثيرة عبر مسح لمعاملات
`<name>.graph.json`	رسم بياني (معرفة وذاكرة)
`<name>.dashboard.tsx`	لوحة معلومات في الشيفرة: أجزاء والملفات التي تعرضها
`<name>.geo.tsx`	مشروع اقتصاد جغرافي في الشيفرة
`<name>.opgraph.tsx`	رسم عقد في الشيفرة
`<name>.task.tsx`، `<name>.project.tsx`	مهمة ومشروع، في الشيفرة
`<name>.market.jsonl`	شريط السوق ودفتر الطلبات والطلبات والمراكز
`calendar/<calendar>/<event>.ics`، `contacts/<email>.vcf`	التقويمات وجهات الاتصال
`.xlsx`، `.md`، `.pdf`، `.ipynb`، `.gcode`، `.step`، `.stl`، `.glb` …	تُفتح كما هي، في المحرر الخاص بنوعها

الإعدادات

الإعدادات ملفات settings.json بأسلوب VS Code (التعليقات مسموحة)، ملف واحد لكل مستوى، تُدمج من العام إلى الخاص: المستويات العامة السحابية والمحلية، ثم مؤسساتك، ثم حسابك، ثم هذا الحاسوب (~/.commandagi/settings.json) وهذا المشروع (.commandagi/settings.json).