शुरुआत: शून्य से एक कार्यशील हार्नेस तक

यह ट्यूटोरियल आपको आपके पहले Apothem सेटअप से शुरू से अंत तक ले जाता है। आप बिना कुछ इंस्टॉल किए शुरू करते हैं और एक वास्तविक हार्नेस कॉन्फ़िगरेशन के साथ समाप्त करते हैं — जो आपकी लिखी प्रोफ़ाइल से उत्पन्न है, सत्यापित है, और जिसके कार्यशील होने की पुष्टि हो चुकी है। लगभग पंद्रह मिनट का समय रखें। नीचे का हर कमांड वास्तविक है और कॉपी-पेस्ट करके चलाया जा सकता है।

अंत तक आप:

1. स्क्रिप्ट इंस्टॉलर से Apothem इंस्टॉल कर चुके होंगे।
2. वह साझा प्रोफ़ाइल संपादित कर चुके होंगे जो हर हार्नेस को संचालित करती है।
3. एक हार्नेस के नेटिव कॉन्फ़िगरेशन को मूर्त रूप दे चुके होंगे।
4. उस कॉन्फ़िगरेशन को सत्यापित कर चुके होंगे और एक कार्यशील पहले रन की पुष्टि कर चुके होंगे।

हम पूरे ट्यूटोरियल में उदाहरण हार्नेस के रूप में Claude Code का उपयोग करेंगे, क्योंकि यह इंस्टॉलर का डिफ़ॉल्ट है। वही चरण किसी भी समर्थित हार्नेस पर लागू होते हैं — जब आप हार्नेस सूची तक पहुँचें, तो नाम बदल दें।

आपको पहले क्या चाहिएCopy Anchor Link

• एक Unix-जैसा शेल (macOS, Linux, या WSL)। PowerShell इंस्टॉलर Windows को कवर करता है; यह ट्यूटोरियल bash पथ दिखाता है।
• आपके PATH पर Python 3.10 या नया। python3 --version से जाँचें।
• वे दो रनटाइम लाइब्रेरी जिन्हें इंजन आपके इंटरप्रेटर से आयात करता है: click और rich। बाकी स्टैक (pyyaml, jsonschema) ट्री में वेंडर किया गया है, इसलिए केवल ये दो आयात-योग्य होने चाहिए। यदि click या rich गायब है, तो इंस्टॉलर रुकता है और इंस्टॉल कमांड प्रिंट करता है। एक-पंक्ति वाली कमांड स्क्रिप्ट को bash में पाइप करती है, इसलिए वह प्रॉम्प्ट नहीं कर सकती; APOTHEM_AUTO_INSTALL_DEPS=1 सेट करें (उदाहरण के लिए curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) या पहले दोनों पैकेज इंस्टॉल करें।

Apothem एक प्रकाशित पैकेज के बजाय एक बंडल किए गए स्रोत ट्री के रूप में शिप होता है — कोई pip install चरण नहीं है। इंस्टॉलर ट्री को क्लोन करता है और इंजन को सीधे उसी से चलाता है।

चरण 1 — Apothem इंस्टॉल करेंCopy Anchor Link

नेटवर्क इंस्टॉलर चलाएँ:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

इंस्टॉलर ये चरण करता है:

1. पूर्वापेक्षा जाँच। इंस्टॉलर एक वास्तविक Python 3.10+ इंटरप्रेटर ढूँढता है और पुष्टि करता है कि दोनों रनटाइम लाइब्रेरी (click और rich) आयात-योग्य हैं। यदि कोई गायब है, तो वह उसका नाम बताता है, रुकता है, और इंस्टॉल कमांड प्रिंट करता है; बिना प्रॉम्प्ट के इंस्टॉल करने के लिए APOTHEM_AUTO_INSTALL_DEPS=1 सेट करें, क्योंकि पाइप किया गया रन प्रॉम्प्ट नहीं कर सकता।
2. स्रोत स्थापन। बंडल किया गया ट्री ~/.apothem में क्लोन किया जाता है (APOTHEM_HOME एनवायरनमेंट वेरिएबल से ओवरराइड करें)। दोबारा चलाने पर मौजूदा क्लोन की नकल बनाने के बजाय उसी क्लोन में रिलीज़ टैग चेक आउट किया जाता है।
3. प्रोफ़ाइल बूटस्ट्रैप। यदि आपके पास अभी कोई प्रोफ़ाइल नहीं है, तो इंस्टॉलर उदाहरण प्रोफ़ाइल को ~/.config/apothem/profile.yaml में कॉपी करता है, उसी रन में उससे Claude Code इंस्टॉल और सत्यापित करता है, और चेतावनी देता है कि पहचान फ़ील्ड प्लेसहोल्डर हैं।

आप पर्यावरण चरों से इंस्टॉल को निर्देशित कर सकते हैं। जिनका आप सबसे अधिक उपयोग करेंगे, वे ये हैं:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

इंस्टॉलर केवल उपयोगकर्ता-दायरे वाले हार्नेस इंस्टॉल करता है। परियोजना-दायरे वाले हार्नेस को बाद में, परियोजना का नाम देकर, इंस्टॉल करें:

apothem install --harness cursor --project /path/to/project

अन्य मान्यता-प्राप्त चर हैं APOTHEM_REPO और APOTHEM_REF (कौन-सा रिमोट क्लोन करना है और कौन-सा git ref चेक आउट करना है — अनसेट होने पर नवीनतम हस्ताक्षरित रिलीज़ टैग रिज़ॉल्व और सत्यापित होता है; उसे पिन करने के लिए टैग सेट करें, या चलती ब्रांच के लिए main (ब्रांच हस्ताक्षरित टैग नहीं होती, इसलिए उसे APOTHEM_ALLOW_UNVERIFIED=1 भी चाहिए)), APOTHEM_ALLOW_UNVERIFIED=1 (टैग-हस्ताक्षर-सत्यापन की विफलता को चेतावनी में घटाता है, और main जैसे गैर-टैग ref की अनुमति देता है), APOTHEM_SOURCE (क्लोन करने के बजाय किसी मौजूदा स्थानीय चेकआउट का उपयोग करता है), और APOTHEM_SKIP_VERIFY=1 (इंस्टॉल-पश्चात सत्यापन छोड़ता है, जिसे हम चलाना चाहते हैं, इसलिए इसे अनसेट छोड़ दें)।

जब इंस्टॉलर एक पूर्ण रन समाप्त करता है, तो वह एक बैनर प्रिंट करता है जो दिखाता है कि इंजन का आह्वान कैसे करें। वह आपके PATH पर एक apothem शिम रखता है (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), इसलिए जब वह डायरेक्टरी PATH पर हो, तब आप इंजन को सीधे चलाते हैं:

apothem <command>

यदि शिम नहीं रखा जा सका — या उसकी डायरेक्टरी अभी PATH पर नहीं है — तो बैनर एक स्व-निहित फ़ॉलबैक प्रिंट करता है जिसे किसी शिम की ज़रूरत नहीं होती:

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

इस ट्यूटोरियल का बाकी हिस्सा apothem <command> लिखता है; यदि आप फ़ॉलबैक रूप का उपयोग कर रहे हैं, तो आपके इंस्टॉलर बैनर ने जो सटीक उपसर्ग प्रिंट किया है, उसे आगे लगाएँ।

चरण 2 — प्रोफ़ाइल को अपना बनाएँCopy Anchor Link

~/.config/apothem/profile.yaml पर स्थित साझा प्रोफ़ाइल सत्य का एकमात्र स्रोत है। हर हार्नेस अडैप्टर इसे पढ़ता है और इससे उस हार्नेस का नेटिव कॉन्फ़िग व्युत्पन्न करता है। इसे एक बार संपादित करें, और आपके द्वारा इंस्टॉल किया गया हर हार्नेस संगत बना रहता है।

इसे इंजन के संपादक में, या किसी भी टेक्स्ट संपादक में खोलें:

apothem profile edit

एक न्यूनतम, वैध प्रोफ़ाइल ऐसी दिखती है:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

प्लेसहोल्डर name को अपने नाम से बदलें, और वे नियम जोड़ें जिन्हें आप हर हार्नेस से लागू करवाना चाहते हैं। उदाहरण मानों को नकली रखें — प्रोफ़ाइल साझा करने के लिए सुरक्षित होने के उद्देश्य से बनी है।

पुष्टि करें कि इंजन आपके संपादनों को बिना त्रुटि के वापस पढ़ता है:

apothem profile show --json

यदि YAML विकृत है, तो आप इसे यहीं देखेंगे — आगे बढ़ने से पहले उसे ठीक करें और फिर से चलाएँ।

चरण 3 — एक हार्नेस कॉन्फ़िगरेशन को मूर्त रूप देंCopy Anchor Link

यदि आपके चरण 1 के रन ने प्रोफ़ाइल बनाई थी, तो उसने प्लेसहोल्डर पहचान से Claude Code पहले ही इंस्टॉल कर दिया है। चरण 2 में प्रोफ़ाइल संपादित करें, फिर अपनी पहचान लागू करने के लिए यह चलाएँ:

apothem update --harness claude-code

apothem install --harness claude-code

यह आपकी प्रोफ़ाइल पढ़ता है और Claude Code का नेटिव कॉन्फ़िगरेशन लिखता है। वे सभी हार्नेस देखने के लिए जिन्हें आप लक्षित कर सकते हैं:

apothem harnesses list

कुछ हार्नेस उपयोगकर्ता-दायरे के बजाय परियोजना-दायरे के होते हैं, और उन्हें एक --project पथ चाहिए ताकि अडैप्टर जान सके कि कहाँ लिखना है:

apothem install --harness cursor --project .

चरण 4 — सत्यापित करें और पहले रन की पुष्टि करेंCopy Anchor Link

मूर्त रूप देना कहानी का केवल आधा हिस्सा है। अब पुष्टि करें कि कॉन्फ़िगरेशन सही ढंग से लिखा गया:

apothem verify --harness claude-code

verify जाँचता है कि हार्नेस की प्रबंधित कॉन्फ़िग फ़ाइलें मौजूद हैं और पार्स होती हैं। --profile PATH जोड़ने पर यह तब भी विफल होता है जब कोई इंस्टॉल की गई फ़ाइल उस प्रोफ़ाइल से बनने वाली सामग्री से भटक गई हो। एक स्वच्छ रन का अर्थ है कि मूर्त रूप देना सफल रहा।

हर पंजीकृत अडैप्टर पर पूरी मशीन की स्वास्थ्य जाँच के लिए, चलाएँ:

apothem doctor

doctor हर इंस्टॉल किए गए हार्नेस की जाँच करता है (उसका सत्यापन सफल होना चाहिए, और उसके पंजीकृत हुक कमांड शुरू होने चाहिए) और यदि कोई भी जाँच विफल होती है तो गैर-शून्य के साथ बाहर निकलता है। जो हार्नेस आपने इंस्टॉल नहीं किए हैं, वे सूचीबद्ध होते हैं पर उसे विफल नहीं करते, इसलिए यह किसी सेटअप स्क्रिप्ट में एक उपयोगी गेट है।

आपका पहला रन। वह हार्नेस खोलें जिसे आपने अभी कॉन्फ़िगर किया — हमारे उदाहरण में Claude Code — और किसी भी परियोजना में एक सत्र शुरू करें। आपने प्रोफ़ाइल में जो नियम और प्राथमिकताएँ लिखीं, वे अब उस टूल के व्यवहार का हिस्सा हैं। यही कार्यशील पहला रन है: चरण 2 में आपने जो प्रोफ़ाइल संपादित की, वह एक वास्तविक सत्र को आकार दे रही है।

आपने क्या बनायाCopy Anchor Link

एक खाली मशीन से शुरू करके, आपने Apothem इंस्टॉल किया, एक साझा प्रोफ़ाइल लिखी, उससे एक हार्नेस के नेटिव कॉन्फ़िगरेशन को मूर्त रूप दिया, परिणाम को सत्यापित किया, और उसके कार्यशील होने की पुष्टि की। प्रोफ़ाइल टिकाऊ आर्टिफ़ैक्ट है — उसे एक बार बदलें और परिवर्तन को किसी भी हार्नेस तक पहुँचाने के लिए apothem update --harness <name> फिर से चलाएँ।

आगे कहाँ जाएँCopy Anchor Link

• एक और टूल जोड़ें। हार्नेस सूची हर समर्थित प्लेटफ़ॉर्म और उसके अडैप्टर नाम को कवर करती है। एक नए --harness के साथ चरण 3 दोहराएँ।
• किसी एक कार्य में गहराई से उतरें। कैसे-करें नुस्खे एक हार्नेस जोड़ने, प्रोफ़ाइल संपादित करने, और इंस्टॉलर चलाने को कवर करते हैं। उपयोग गाइड नियम लिखने, योजनाएँ लिखने, और अनुरूपता गेट चलाने को कवर करते हैं।
• विशिष्ट विवरण देखें। संदर्भ हर आर्टिफ़ैक्ट वर्ग और प्रोफ़ाइल स्कीमा का दस्तावेज़ीकरण करता है, और CLI संदर्भ हर कमांड को कवर करता है। हर अडैप्टर का अपना पेज हार्नेस के अंतर्गत है।
• ऐसे कार्य की योजना बनाएँ जो एक सत्र से आगे चले। पुनरारंभ-योग्य योजना समझाती है कि Apothem लंबे समय तक चलने वाले कार्य को एक परियोजना-स्थानीय .apothem/plans/ सूट में कैसे बाहरी रूप देता है, ताकि किसी भी मशीन पर एक नया सत्र उसे यथास्थान फिर से शुरू कर सके।

अनुशंसित अगला कदमCopy Anchor Link

और हार्नेस जोड़ने की ओर बढ़ने से पहले, अपना सेटअप जाँचने के लिए apothem doctor चलाएँ — यह हर पंजीकृत अडैप्टर की स्थिति की रिपोर्ट करता है, इसलिए आपने अभी जो हार्नेस इंस्टॉल किया वह स्वस्थ दिखता है, जबकि बाकी अभी-तक-इंस्टॉल-नहीं के रूप में दिखते हैं।