Memulai: dari nol ke harness yang berfungsi

Tutorial ini memandu Anda sepanjang penyiapan Apothem pertama Anda. Anda mulai tanpa apa pun yang terpasang dan selesai dengan konfigurasi harness yang nyata — dihasilkan dari profil yang Anda tulis, terverifikasi, dan dikonfirmasi berfungsi. Sediakan waktu sekitar lima belas menit. Setiap perintah di bawah ini nyata dan dapat dijalankan dengan salin-tempel.

Di akhir tutorial ini, Anda telah:

1. Memasang Apothem dari pemasang skrip.
2. Menyunting profil bersama yang menggerakkan setiap harness.
3. Mematerialisasikan konfigurasi native sebuah harness.
4. Memverifikasi konfigurasi itu dan mengonfirmasi eksekusi pertama yang berfungsi.

Kita akan menggunakan Claude Code sebagai contoh harness di sepanjang tutorial, karena ini adalah default pemasang. Langkah yang sama berlaku untuk harness apa pun yang didukung — ganti namanya saat Anda mencapai daftar harness.

Apa yang Anda perlukan terlebih dahuluCopy Anchor Link

• Shell mirip Unix (macOS, Linux, atau WSL). Pemasang PowerShell mencakup Windows; tutorial ini menunjukkan jalur bash.
• Python 3.10 atau lebih baru di PATH Anda. Periksa dengan python3 --version.
• Dua pustaka runtime yang diimpor mesin dari interpreter Anda: click dan rich. Sisa tumpukan (pyyaml, jsonschema) di-vendor ke dalam pohon, sehingga hanya kedua pustaka ini yang perlu dapat diimpor. Jika click atau rich hilang, pemasang berhenti dan mencetak perintah pemasangan. Perintah satu baris menyalurkan skrip ke bash, sehingga tidak dapat meminta konfirmasi; setel APOTHEM_AUTO_INSTALL_DEPS=1 (misalnya curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) atau pasang kedua paket terlebih dahulu.

Apothem dikirim sebagai pohon sumber terbundel alih-alih paket yang dipublikasikan — tidak ada langkah pip install. Pemasang mengkloning pohon tersebut dan menjalankan mesin langsung darinya.

Langkah 1 — Pasang ApothemCopy Anchor Link

Jalankan pemasang jaringan:

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

Pemasang menjalankan langkah-langkah berikut:

1. Pemeriksaan prasyarat. Pemasang menemukan interpreter Python 3.10+ yang sebenarnya dan memastikan kedua pustaka runtime (click dan rich) dapat diimpor. Jika salah satunya hilang, pemasang menyebutkannya, berhenti, dan mencetak perintah pemasangan; setel APOTHEM_AUTO_INSTALL_DEPS=1 untuk memasang tanpa meminta konfirmasi, karena eksekusi lewat pipa tidak dapat meminta konfirmasi.
2. Penempatan sumber. Pohon terbundel dikloning ke ~/.apothem (timpa dengan variabel lingkungan APOTHEM_HOME). Eksekusi ulang melakukan checkout tag rilis di klon yang ada alih-alih menggandakannya.
3. Bootstrap profil. Jika Anda belum memiliki profil, pemasang menyalin profil contoh ke ~/.config/apothem/profile.yaml, memasang dan memverifikasi Claude Code dari profil tersebut dalam eksekusi yang sama, serta memperingatkan bahwa bidang identitas hanyalah placeholder.

Anda dapat mengarahkan instalasi dengan variabel lingkungan. Yang paling mungkin Anda gunakan:

# 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

Pemasang hanya memasang harness cakupan pengguna. Pasang harness cakupan proyek setelahnya, dengan menyebutkan proyeknya:

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

Variabel lain yang dikenali adalah APOTHEM_REPO dan APOTHEM_REF (remote mana yang dikloning dan ref git mana yang di-checkout — jika tidak disetel, pemasang me-resolve dan memverifikasi tag rilis bertanda tangan terbaru; setel sebuah tag untuk mematoknya, atau main untuk branch yang bergerak (branch bukan tag bertanda tangan, sehingga juga memerlukan APOTHEM_ALLOW_UNVERIFIED=1)), APOTHEM_ALLOW_UNVERIFIED=1 (menurunkan kegagalan verifikasi tanda tangan tag menjadi peringatan, dan mengizinkan ref non-tag seperti main), APOTHEM_SOURCE (menggunakan checkout lokal yang sudah ada alih-alih mengkloning), dan APOTHEM_SKIP_VERIFY=1 (melewati verifikasi pasca-instalasi, yang ingin kita jalankan, jadi biarkan tidak disetel).

Saat pemasang menyelesaikan eksekusi penuh, pemasang mencetak banner yang menunjukkan cara memanggil mesin. Pemasang menempatkan shim apothem di PATH Anda (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), sehingga setelah direktori itu ada di PATH, Anda menjalankan mesin secara langsung:

apothem <command>

Jika shim tidak dapat ditempatkan — atau direktorinya belum ada di PATH — banner mencetak fallback mandiri yang tidak memerlukan shim:

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

Sisa tutorial ini menulis apothem <command>; jika Anda memakai bentuk fallback, tambahkan di depannya prefiks persis yang dicetak banner pemasang Anda.

Langkah 2 — Jadikan profil milik AndaCopy Anchor Link

Profil bersama di ~/.config/apothem/profile.yaml adalah satu-satunya sumber kebenaran. Setiap adapter harness membacanya dan menurunkan konfigurasi native harness tersebut darinya. Sunting sekali, dan setiap harness yang Anda pasang tetap konsisten.

Buka profil di editor mesin, atau di editor teks apa pun:

apothem profile edit

Profil minimal yang valid terlihat seperti ini:

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

Ganti name placeholder dengan nama Anda sendiri, dan tambahkan aturan apa pun yang Anda ingin ditegakkan oleh setiap harness. Pertahankan nilai contoh tetap palsu — profil ini dimaksudkan agar aman dibagikan.

Pastikan mesin membaca kembali suntingan Anda dengan bersih:

apothem profile show --json

Jika YAML cacat, di sinilah Anda akan melihatnya — perbaiki dan jalankan ulang sebelum melanjutkan.

Langkah 3 — Materialisasikan konfigurasi harnessCopy Anchor Link

Jika eksekusi Langkah 1 Anda membuat profil, pemasang sudah memasang Claude Code dari identitas placeholder. Sunting profil di Langkah 2, lalu terapkan identitas Anda dengan:

apothem update --harness claude-code

apothem install --harness claude-code

Ini membaca profil Anda dan menulis konfigurasi native Claude Code. Untuk melihat setiap harness yang dapat Anda targetkan:

apothem harnesses list

Beberapa harness bercakupan proyek alih-alih bercakupan pengguna, dan harness tersebut memerlukan jalur --project agar adapter mengetahui tempat menulis:

apothem install --harness cursor --project .

Langkah 4 — Verifikasi dan konfirmasi eksekusi pertamaCopy Anchor Link

Materialisasi hanyalah separuh cerita. Sekarang konfirmasikan bahwa konfigurasi mendarat dengan benar:

apothem verify --harness claude-code

verify memeriksa bahwa berkas konfigurasi terkelola harness ada dan dapat di-parse. Tambahkan --profile PATH dan perintah ini juga gagal ketika berkas yang terpasang telah menyimpang dari apa yang akan dihasilkan profil tersebut. Eksekusi yang bersih berarti materialisasi berhasil.

Untuk pemeriksaan kesehatan seluruh mesin di setiap adapter terdaftar, jalankan:

apothem doctor

doctor memeriksa setiap harness yang terpasang (harness itu harus lolos verifikasi, dan perintah hook yang didaftarkannya harus dapat dimulai) dan keluar dengan kode bukan-nol jika ada pemeriksaan yang gagal. Harness yang belum Anda pasang tercantum tetapi tidak membuatnya gagal, sehingga perintah ini adalah gerbang yang berguna dalam skrip penyiapan.

Eksekusi pertama Anda. Buka harness yang baru saja Anda konfigurasikan — Claude Code, dalam contoh kita — dan mulai sesi di proyek mana pun. Aturan dan preferensi yang Anda tulis ke profil kini menjadi bagian dari perilaku alat itu. Itulah eksekusi pertama yang berfungsi: profil yang Anda sunting di Langkah 2 sedang membentuk sesi nyata.

Apa yang Anda bangunCopy Anchor Link

Berawal dari mesin kosong, Anda memasang Apothem, menulis profil bersama, mematerialisasikan konfigurasi native sebuah harness darinya, memverifikasi hasilnya, dan mengonfirmasi bahwa hasilnya berfungsi. Profil adalah artefak yang bertahan — ubah sekali dan jalankan ulang apothem update --harness <name> untuk mendorong perubahan ke harness mana pun.

Ke mana selanjutnyaCopy Anchor Link

• Tambahkan alat lain. Daftar harness mencakup setiap platform yang didukung dan nama adapternya. Ulangi Langkah 3 dengan --harness baru.
• Dalami satu tugas. Resep cara-pakai mencakup penambahan harness, penyuntingan profil, dan pengoperasian pemasang. Panduan penggunaan mencakup penulisan aturan, penyusunan rencana, dan menjalankan gerbang konformitas.
• Cari detail spesifik. Referensi mendokumentasikan setiap kelas artefak dan skema profil, dan referensi CLI mencakup setiap perintah. Setiap adapter memiliki halamannya sendiri di bawah harness.
• Rencanakan pekerjaan yang melampaui satu sesi. Perencanaan yang dapat dilanjutkan menjelaskan cara Apothem mengeksternalkan pekerjaan jangka panjang ke suite .apothem/plans/ lokal-proyek sehingga sesi baru di mesin mana pun melanjutkannya di tempat.

Langkah Berikutnya yang DisarankanCopy Anchor Link

Jalankan apothem doctor untuk memeriksa penyiapan Anda — perintah ini melaporkan keadaan setiap adapter terdaftar, sehingga harness yang baru saja Anda pasang tampil sebagai sehat sementara sisanya tampil sebagai belum terpasang — sebelum Anda melanjutkan ke penambahan harness lain.