Skip to content
Apothem
आर्किटेक्चर

हार्नेस अडैप्टर अमूर्तन

HarnessAdapter प्रोटोकॉल — Apothem अडैप्टर साझा प्रोफ़ाइल का अनुवाद कैसे करते हैं।

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

अडैप्टर अमूर्तन क्यों

प्रत्येक हार्नेस एक भिन्न कॉन्फ़िगरेशन बोली बोलता है: एक को JSON सेटिंग्स फ़ाइल चाहिए, दूसरे को .mdc नियम फ़ाइलों की एक डायरेक्टरी, और तीसरे को एक एकल Markdown निर्देश फ़ाइल। यदि Apothem उस ज्ञान को CLI में हार्ड-कोड कर देता, तो प्रत्येक हार्नेस अपनी मान्यताओं को कोर में रिसा देता, और एक हार्नेस जोड़ने का अर्थ होता इंस्टॉल, अपडेट, अनइंस्टॉल, और सत्यापन तर्क को एक साथ छूना।

अडैप्टर पैटर्न इसे उलट देता है। कोर केवल HarnessAdapter प्रोटोकॉल को जानता है — जीवनचक्र विधियों का एक छोटा अनुबंध। प्रत्येक हार्नेस की बोली एक स्व-निहित उप-पैकेज के भीतर रहती है जो उस अनुबंध को लागू करता है। कोर किसी अडैप्टर से इंस्टॉल करने को कहता है, बिना यह जाने कि इसका अर्थ JSON फ़ाइल रेंडर करना है, नियम डायरेक्टरी लिखना है, या समर्थन वृक्ष बिछाना है। नए हार्नेस प्रोटोकॉल को संतुष्ट करके और src/apothem/lib/harness_registry_data.py में HARNESS_REGISTRY प्रविष्टि जोड़कर जुड़ते हैं (वहाँ SUPPORTED_HARNESS_COUNT बढ़ाते हुए), pyproject.toml में apothem.harnesses एंट्री पॉइंट में उसे प्रतिबिंबित करके, और src/apothem/schemas/profile.schema.json में harnessId enum में ID जोड़कर। यही वह संरचनात्मक कारण है जिससे Apothem होस्ट-अज्ञेयवादी बना रहता है — यह अमूर्तन वह सीमा है जो हार्नेस-विशिष्ट ज्ञान को फैलने से रोकती है।

एक अडैप्टर का आकार

अडैप्टर दो मूर्तीकरण आकारों में विभाजित होते हैं, दोनों रजिस्ट्री में दृश्यमान हैं:

  • एकल-फ़ाइल रेंडरर प्रोफ़ाइल फ़ील्ड्स को एक हार्नेस-मूल कॉन्फ़िग फ़ाइल में अनुवाद करते हैं। उदाहरण के लिए, OpenCode अडैप्टर साझा प्रोफ़ाइल से अपनी नेटिव कॉन्फ़िग फ़ाइल एक मूर्तीकारक के माध्यम से रेंडर करता है।
  • नियम-सतह और समर्थन-वृक्ष अडैप्टर Apothem पेलोड समूह को हार्नेस की प्रलेखित नियम-स्थान में प्रसारित करते हैं, जहाँ नेटिव प्रारूप मौजूद हो वहाँ समूह को उसमें बदलते हैं, और शेष को नेटिव एंकर से संदर्भित Apothem-स्वामित्व वाले समर्थन उप-वृक्ष के अंतर्गत रखते हैं। Cursor अडैप्टर आपूर्ति की गई प्रोजेक्ट रूट में एक एकल .cursor/rules/apothem-rules.mdc लिखता है। उस फ़ाइल से पहले वह यूज़र होम में दो साझा फ़ोल्डर लिखता है: स्किल, और स्किल के रूप में लपेटे गए कमांड, ~/.agents/skills/ में जाते हैं, और वे नियम और टेम्पलेट जिनका वे स्किल हवाला देते हैं, ~/.config/apothem/ में जाते हैं। Claude Code अडैप्टर प्रोफ़ाइल से settings.json रेंडर नहीं करता। वह बंडल्ड सेटिंग्स टेम्पलेट को हुक इंटरप्रेटर भरकर ~/.claude/settings.json में कॉपी करता है, उसके बगल में Apothem कन्वेंशन डायरेक्टरियों (agents/, rules/, skills/, …) को समतल करता है, और प्रोफ़ाइल को CLAUDE.md में एक सेंटिनल-सीमांकित प्रबंधित ब्लॉक में लिखता है।

कोई दिया गया अडैप्टर या तो उपयोगकर्ता-दायरे का होता है (होम डायरेक्टरी के नीचे लिखता है) या परियोजना-दायरे का (--project <path> अपेक्षित करता है और अपनी प्रोजेक्ट फ़ाइल उस वृक्ष के भीतर लिखता है); रजिस्ट्री यह दर्ज करती है कि कौन-सा। सात परियोजना-दायरे वाले अडैप्टर (cursor, github-copilot, windsurf, zed, codebuddy, kiro, और trae) यूज़र होम में साझा फ़ोल्डर भी लिखते हैं, जैसे ~/.agents/skills/ और ~/.config/apothem/, और --project यह नहीं बदलता कि वे कहाँ जाते हैं।

वर्तमान अडैप्टर टोपोलॉजी

%% provenance: hand-authored %%
%% verified: 2026-10-25 %%
%% cross-reference: src/apothem/harnesses/ (adapter sub-packages) %%
flowchart TD
    accTitle: Apothem adapter topology
    accDescr: The single shared profile at the center feeds the adapter layer, which fans out to one adapter per supported harness; each adapter writes to a user-scope or project-scope native surface, rendering a single config file or propagating a rules and support-tree cohort.
    P["Shared profile (YAML)<br/>~/.config/apothem/profile.yaml<br/>+ packaged payload cohorts"]
    P --> AL["Adapter layer<br/>HarnessAdapter protocol<br/>(17 registered adapters)"]

    AL --> CC["claude-code adapter<br/>(user scope)"]
    AL --> CX["codex adapter<br/>(user scope)"]
    AL --> CU["cursor adapter<br/>(project scope)"]
    AL --> CO["github-copilot adapter<br/>(project scope)"]
    AL --> WS["windsurf adapter<br/>(project scope)"]
    AL --> ETC["… 12 more registered adapters<br/>(antigravity, gemini-cli, glm, hermes,<br/>kimi-code, open-claw, opencode, qwen-code,<br/>codebuddy, kiro, trae, zed)"]

    CC --> CCN["~/.claude/settings.json<br/>+ flattened convention dirs<br/>(template copy)"]
    CX --> CXN["~/.codex/AGENTS.md + hooks.json<br/>+ converted TOML agents<br/>(render + support tree)"]
    CU --> CUN["&lt;project&gt;/.cursor/rules/apothem-rules.mdc<br/>+ ~/.agents/skills/ and ~/.config/apothem/<br/>(project rules file + user-home folders)"]
    CO --> CON["&lt;project&gt;/.github/copilot-instructions.md<br/>+ ~/.agents/skills/ and ~/.config/apothem/<br/>(project rules file + user-home folders)"]
    WS --> WSN["&lt;project&gt;/.devin/rules/apothem-rules.md<br/>+ ~/.agents/skills/ and ~/.config/apothem/<br/>(project rules file + user-home folders)"]
    ETC --> ETCN["each harness's documented<br/>native surface or Apothem-owned<br/>support subtree"]

केंद्र-से-किनारे का यह प्रसार वही वास्तुकला है जिसे परियोजना का नाम अंकित करता है: कोर में एक प्रोफ़ाइल, और प्रत्येक हार्नेस अपने स्वयं के अडैप्टर के साथ समान दूरी पर बाहर की ओर।

प्रोटोकॉल परिभाषा

from pathlib import Path
from typing import Protocol

class HarnessAdapter(Protocol):
    name: str
    output_path: Path

    def install(self, profile: dict[str, object]) -> object:
        ...

    def update(self, profile: dict[str, object]) -> object:
        ...

    def uninstall(self) -> None:
        ...

    def is_installed(self) -> bool:
        ...

    def verify(self) -> bool:
        ...

परियोजना-दायरे के अडैप्टर जीवनचक्र विधियों पर अतिरिक्त रूप से project: Path | None स्वीकार कर सकते हैं और resolve_output_path(project) को उजागर कर सकते हैं। CLI --project PATH को केवल उन्हीं अडैप्टरों को पास करता है जिनकी विधि हस्ताक्षर इसे स्वीकार करती है।

एंट्री-पॉइंट पंजीकरण

अडैप्टर apothem.harnesses setuptools एंट्री-पॉइंट समूह के माध्यम से पंजीकृत होते हैं:

[project.entry-points."apothem.harnesses"]
cursor = "apothem.harnesses.cursor:CursorAdapter"

src/apothem/lib/harness_registry.py पर स्थित केंद्रीय रजिस्ट्री ठीक सत्रह सार्वजनिक ID, एंट्री पॉइंट, डॉक्स पथ, लक्ष्य पथ, पैकेज-डेटा आवश्यकताएँ, क्षमता स्थितियाँ, और मानक कन्वेंशन पिन पथ दर्ज करती है। CLI प्रत्येक कमांड में उत्पाद तथ्यों को फिर से खोजने के बजाय उस रजिस्ट्री के माध्यम से अडैप्टर लोड करता है।

प्रोफ़ाइल-से-मूल मानचित्रण

प्रत्येक अडैप्टर अपने हार्नेस के लिए उपयुक्त अनुवाद तर्क को लागू करता है:

YAML profile + payload cohort    Harness-native surface
-----------------------------    ----------------------
identity / preferences       --> native config fields or rendered instruction context
commands/*.md                --> native commands or SKILL.md folders
rules/*.md                   --> native rules where supported, otherwise support trees
hooks/messages/*.md          --> native hooks where supported, otherwise support trees
agents/*.md                  --> native agent formats where supported
skills/*/SKILL.md            --> native skill folders where supported

असमर्थित और खोज-लंबित क्षमता कोशिकाएँ लिखने से पहले संरचित चेतावनियाँ बन जाती हैं। उन्हें चुपचाप गढ़ी गई विक्रेता सतहों में प्रक्षेपित नहीं किया जाता।

एक नया अडैप्टर जोड़ना

चरण-दर-चरण मार्गदर्शिका के लिए हार्नेस अडैप्टर लिखना देखें।

साझा प्रोफ़ाइल स्कीमा

Apothem साझा प्रोफ़ाइल YAML के लिए स्कीमा।

समूह पैकेजिंग अनुबंध

समूह पैकेजिंग और प्लगइन मैनिफ़ेस्ट के लिए स्थिर, डाउनस्ट्रीम-उपभोग्य अनुबंध — मैपिंग को फिर से व्युत्पन्न किए बिना समूह गिनें और उनके प्रति-हार्नेस नेटिव टारगेट हल करें।

On this page

अडैप्टर अमूर्तन क्योंएक अडैप्टर का आकारवर्तमान अडैप्टर टोपोलॉजीप्रोटोकॉल परिभाषाएंट्री-पॉइंट पंजीकरणप्रोफ़ाइल-से-मूल मानचित्रणएक नया अडैप्टर जोड़ना