자체 완결형 런타임Copy Anchor Link

Apothem의 엔진은 자체 완결형 런타임입니다. 서드파티 종속성이 엔진과 함께 이동하므로, 레지스트리 없이 어떤 체크아웃이나 배치된 소스 트리에서든 바로 실행됩니다. 이를 가능하게 하는 요소는 두 가지입니다. 벤더링된 종속성 트리와, 설치된 콘솔 스크립트가 필요 없는 python -m 호출 모델입니다.

벤더링된 종속성 트리Copy Anchor Link

검증 및 직렬화 스택은 순수 Python 소스로 src/apothem/_vendor/ 아래에 벤더링되어 있으며, 각 패키지 옆에는 업스트림 라이선스 파일이 함께 있습니다.

• yaml(순수 Python 파서/이미터이며, 선택적 libyaml C 확장은 포함하지 않습니다)
• jsonschema와 그 종속성 체인인 attrs(및 그 별칭 attr), referencing, jsonschema_specifications
• rpds — jsonschema와 referencing이 사용하는 HashTrieMap, HashTrieSet, List 표면을 내장 타입 기반으로 다시 구현한 순수 Python 심입니다. 덕분에 스택은 컴파일된 확장 없이 실행됩니다
• typing_extensions

벤더링된 사본은 시스템에 설치된 어떤 버전보다 우선합니다. 플러그인 부트스트랩, npm 심, 설치 프로그램, 그리고 python -m apothem 진입점 자체가 각각 벤더 디렉터리를 site-packages보다 앞서 sys.path에 넣습니다. 선택 정책, 즉 무엇을 벤더링하고 무엇을 벤더링하지 않으며 벤더링된 패키지를 어떻게 갱신하는지는 종속성 벤더링 전략에 문서화되어 있습니다.

두 종속성은 트리 밖에 남습니다. CLI가 임포트하는 터미널용 라이브러리 click, rich 두 가지입니다. 이 둘은 엔진을 실행하는 인터프리터에서 임포트할 수 있어야 합니다. 설치 프로그램은 둘 다 확인하고, 누락된 것의 이름을 밝히고, 대신 설치해 주겠다고 제안합니다. 설치는 여러분의 확인을 받거나, --yes / APOTHEM_AUTO_INSTALL_DEPS=1로 자동으로 진행됩니다. 그 밖의 모든 채널에서는 진입점이 CLI를 임포트하기 전에 표준 라이브러리로 둘 다 확인하며, 하나라도 누락되면 실행 중인 인터프리터에 맞는 정확한 pip 명령을 알려 주는 오류와 함께 중단됩니다(--json에서는 코드 runtime.dependency_missing을 담은 JSON 봉투).

python -m 호출 모델Copy Anchor Link

Apothem은 의도적으로 pyproject.toml에 콘솔 스크립트를 선언하지 않습니다. 콘솔 스크립트는 패키지 관리자가 PATH에 배치할 때에만 존재하며, 자체 완결형 런타임은 패키지 관리자를 절대 전제하지 않습니다. 그 대신 엔진에는 두 가지 호출 표면이 있습니다.

• python -m apothem은 src/apothem/__main__.py를 실행합니다. 이 파일은 src/apothem/_vendor를 sys.path에 넣고, click과 rich를 임포트할 수 있는지 확인한 다음, Click 명령 그룹인 apothem.cli:main을 호출합니다.
• 머티리얼라이즈된 settings.json / hooks.json의 훅 항목은 디스패처를 (Claude Code의 경우 <harness-root>/.apothem/support/conformity/gate.py의 적합성 게이트도) 절대 스크립트 경로로 호출합니다. 둘 다 자신의 sys.path를 스스로 부트스트랩하는 독립 표준 라이브러리 스크립트이며, 게이트의 스키마 픽스처는 게이트 옆 <harness-root>/.apothem/support/schemas/에 함께 놓입니다. 따라서 훅은 호스트에 임포트할 수 있는 apothem 패키지가 없어도 실행됩니다. 템플릿에는 ${HARNESS_ROOT} 토큰이 들어 있으며, apothem install이 이를 슬래시(/) 구분 형식의 실제 하니스 루트 경로로 렌더링합니다.
• 소스 체크아웃에서는 모듈 형식인 python -m apothem.hooks.dispatch와 python -m apothem.conformity.gate가 개발용으로 같은 코드를 실행합니다.

체크아웃의 src/ 디렉터리를 PYTHONPATH 앞에 추가하면 패키지 디렉터리를 임포트할 수 있게 됩니다.

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

apothem 런처가 PATH에 없으면, install.sh는 완료 시 이 형식을 출력합니다. 이 형식에서는 벤더링된 디렉터리가 src/보다 앞에 오며, python 대신 설치 프로그램이 해석한 CPython이 쓰입니다. install.ps1은 같은 두 설정을 PowerShell 형식으로 출력합니다. 그 형식은 벤더링된 디렉터리와 src/ 디렉터리를 ;로 잇는 $env:PYTHONPATH 할당과, 그다음 & '<CPython>' -m apothem <command>입니다.

플러그인 트리 부트스트랩Copy Anchor Link

Claude Code 플러그인은 PYTHONPATH에 의존하지 않고 엔진을 <plugin_root>/lib/apothem 아래에 번들합니다. 부트스트랩 모듈 apothem.lib.plugin_bootstrap은 bootstrap_syspath를 제공합니다. 이 함수는 <plugin_root>/lib와 벤더 디렉터리를 sys.path 앞에 멱등적으로 추가하여 import apothem과 벤더링된 모든 종속성이 플러그인 트리에서 해석되도록 합니다. 형식이 잘못된 트리(lib/ 누락)는 오래된 시스템 사본을 조용히 임포트하는 대신 PluginBootstrapError를 발생시킵니다.

설치 프로그램이 디스크에 배치하는 것Copy Anchor Link

스크립트 설치 프로그램은 소스 트리의 git 클론을 ~/.apothem에 배치하고(APOTHEM_HOME으로 재정의) 그 클론에서 엔진을 실행합니다. 선택적인 click / rich 전제 조건 설치 제안을 제외하면 site-packages에 설치되는 Python 패키지는 없습니다. 클론은 런타임이 절대 임포트하지 않는 테스트 스위트와 문서 사이트까지 포함한 전체 저장소이며, 여기에는 의도된 이유가 두 가지 있습니다. 첫째, 엔진은 규칙, 스킬, 명령, 템플릿 같은 코호트를 트리에서 각 하니스로 직접 머티리얼라이즈하므로, 트리는 단순한 런타임이 아니라 살아 있는 진실의 출처입니다. 둘째, .git 디렉터리가 그대로 남아 있으므로 apothem update가 다시 내려받는 대신 기존 클론에서 릴리스 태그를 체크아웃합니다.

이렇게 소스에서 실행하는 레이아웃은 nvm, pyenv, oh-my-zsh 같은 도구가 사용하는 것과 같은 패턴입니다. 몇 메가바이트의 소스와 이력이며, 제거 프로그램으로 한 번에 제거할 수 있습니다(되돌릴 시스템 상태가 없습니다). tests/와 site/를 생략하는 얕은 체크아웃이나 희소 체크아웃으로 더 작은 점유 공간을 만들 수도 있지만, 그러면 서명으로 검증되는 제자리 git 기반 업데이트 경로를 포기하게 됩니다. 현재 레이아웃은 최소 디스크 사용량보다 단순하고 검증 가능한 업데이트를 우선합니다.

런타임이 Python을 찾는 방법Copy Anchor Link

원샷 설치 프로그램과 npx 심은 서로 다른 이름을 탐색하지만 같은 규칙을 적용합니다. 설치 프로그램은 python3, python, 버전이 붙은 이름(python3.14부터 python3.10까지)을 탐색합니다. npx 심은 APOTHEM_PYTHON이 설정되어 있으면 이를 먼저 탐색한 다음 python3, python, py -3를 탐색하며, 버전이 붙은 이름은 없습니다. 둘 다 Microsoft Store 런처 심은 거부하고, 버전 3.10 이상을 보고하는 첫 번째 후보를 받아들입니다. 소스 트리에서 실행될 때 설치 프로그램은 번들된 hooks/lib/find-python 로케이터를 재사용하며, 이 로케이터도 같은 최저 버전을 적용합니다.

권장 다음 단계Copy Anchor Link

체크아웃의 src/ 디렉터리를 PYTHONPATH에 둔 상태에서 python -m apothem --help를 실행하여, 자체 완결형 CLI 경로가 여러분의 호스트에서 해석되는지 확인하세요.