Dentro del diseño del adaptador multi-entorno

Apothem materializa un único perfil compartido en diecisiete configuraciones nativas de entorno. Diecisiete objetivos, diecisiete formatos de proveedor, diecisiete ubicaciones de instalación — y una única interfaz uniforme de la que tanto el operador como la CLI dependen. Esta publicación explica cómo la capa de adaptadores mantiene unido ese contrato.

El protocolo HarnessAdapterCopy Anchor Link

Cada adaptador de entorno implementa un protocolo estructural HarnessAdapter. El protocolo es la costura entre la CLI y los detalles específicos del proveedor. Declara las operaciones que la CLI invoca y los metadatos que la CLI lee:

• name — el identificador registrado del adaptador.
• output_path — dónde termina en disco la configuración materializada.
• install — renderizar y escribir la configuración nativa del entorno.
• update — volver a renderizar la configuración nativa del entorno cuando cambia el perfil.
• uninstall — eliminar la configuración materializada, dejando intacto el perfil compartido.
• is_installed — informar si la configuración del entorno está presente.
• verify — detectar la deriva entre el perfil y la configuración en disco.

Como el contrato es un typing.Protocol, un adaptador lo satisface por su forma, no por herencia. En tiempo de ejecución la CLI resuelve cada adaptador a partir de un registro estático — la tabla HARNESS_REGISTRY de src/apothem/lib/harness_registry_data.py, que harness_registry.py declara autoritativa en tiempo de ejecución — de modo que un checkout simple carga todos los adaptadores sin metadatos de puntos de entrada instalados en sys.path. La tabla [project.entry-points."apothem.harnesses"] de pyproject.toml y el barrido discover_adapters() del sistema de archivos son una comprobación de paridad de conformidad, no el resolutor en tiempo de ejecución: una prueba afirma que el conjunto de adaptadores descubiertos iguala al registro estático, de modo que un adaptador correcto por convención pero no registrado aflora como una regresión de cobertura en lugar de resolverse en silencio. Por tanto, añadir un entorno significa registrarlo en los datos del registro (y reflejarlo en la tabla de puntos de entrada para mantener la paridad del empaquetado) — la prueba de paridad falla de forma evidente si se omite cualquiera de los dos.

Un subpaquete por adaptadorCopy Anchor Link

Cada adaptador vive en su propio subpaquete bajo src/apothem/harnesses/<name>/:

• __init__.py — la clase <Name>Adapter que implementa el protocolo y delega en los módulos de acción hermanos.
• install.py / uninstall.py / update.py / verify.py — las implementaciones por acción que la clase del adaptador importa y llama.
• materializer.py — un materialize_native_config(profile) -> str opcional que renderiza el perfil compartido en el texto de configuración nativo del entorno.

Dividir cada acción en su propio módulo mantiene delgada la clase del adaptador: es un despachador que conecta los métodos del protocolo con las funciones de acción. Un lector que abre verify.py ve exactamente la lógica de detección de deriva de ese único entorno, sin ruido de instalación o desinstalación que sortear.

Tres clases de adaptadorCopy Anchor Link

Los diecisiete entornos no consumen todos la configuración de la misma manera. Apothem los ordena en tres clases según cuánta transformación necesita el perfil antes de llegar al entorno.

Clase I — propagación crudaCopy Anchor Link

El entorno consume los mismos artefactos que Apothem ya escribe — reglas .md planas, agents, hooks — sin paso de renderizado. El adaptador copia las plantillas crudas en el árbol de configuración del entorno. No hay materializer.py, porque no se renderiza nada; los artefactos del perfil son la salida.

Clase II-A — crudo más plantillas de proveedorCopy Anchor Link

El entorno consume los artefactos crudos de Apothem Y un conjunto de archivos de plantilla específicos del proveedor (archivos de ajustes, manifiesto o andamiaje que el entorno requiere). El adaptador copia juntos los artefactos crudos y las plantillas de proveedor. Las plantillas de proveedor viven junto al adaptador en un directorio templates/.

Clase II-B — renderizado desde el perfilCopy Anchor Link

El entorno quiere un único archivo de configuración nativo renderizado a partir de los campos estructurados del perfil compartido. El materializer.py del adaptador lee el perfil y emite el texto nativo del entorno — un config.yaml de Hermes, un openclaw.json de Open-Claw, un opencode.json de OpenCode o un settings.json de Qwen Code. La Clase II-B es donde se concentra el trabajo de reconciliación de formatos; el análisis a fondo de la convergencia de convenciones lo cubre en detalle.

claude-code: el adaptador de superficie completaCopy Anchor Link

El adaptador claude-code tiene la superficie de configuración más amplia — reglas, agents, hooks, output-styles, ajustes y directorios de convención. Pertenece a la Clase II-A: propaga las plantillas crudas de Apothem y aplana los directorios de convención, y envía plantillas de ajustes de proveedor bajo src/apothem/harnesses/claude_code/templates/. No lleva materializer.py — no renderiza un archivo de configuración nativo a partir del perfil; propaga artefactos y directorios de convención directamente.

Un límite deliberado: el adaptador claude-code gestiona solo un bloque delimitado por centinelas dentro de CLAUDE.md; la prosa fuera de ese bloque se conserva. El resto de ese archivo es territorio propiedad del operador. Apothem materializa la superficie de configuración que lo rodea (las reglas, los hooks, los ajustes) y conserva la prosa del operador fuera de ese bloque tal cual. Un adaptador que reescribiera todo el archivo borraría las instrucciones escritas a mano en cada apothem install; este solo reescribe su bloque gestionado.

Por qué importa la uniformidadCopy Anchor Link

El protocolo le da al operador un único modelo mental a través de diecisiete herramientas. apothem install, apothem verify, apothem uninstall se comportan de la misma manera ya sea que el objetivo renderice un único archivo o aplane un árbol de directorios. Las diferencias de proveedor viven dentro de los subpaquetes de adaptador, detrás del protocolo, donde corresponde.

Lee la referencia orientada al operador en Entornos y el modelo de perfil en Conceptos.