# 패키지 수명 주기, 호스트 및 권한 — AI Game Dev 앱 & CLI · AI Game Developer Wiki

AI Game Dev가 패키지를 실행하는 방식: Extension Host, 지연 활성화, 데스크톱과 CLI, 레벨과 업데이트, 오류와 로그, 권한, API 버전 관리.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/app/package-lifecycle).

이 페이지는 패키지가 설치되고 제거되기까지 무슨 일이 일어나는지 설명합니다: 코드가 어디서 실행되는지, 언제 시작하고 멈추는지, 무엇을 할 수 있는지, 오류가 어떻게 여러분에게 전달되는지, 그리고 패키지가 작성된 API가 어떻게 호환성을 유지하는지. 다른 사람이 설치할 패키지를 배포하기 전에 알아야 할 배경 지식입니다.

## 패키지가 실행되는 위치

앱은 VS Code가 확장을 실행하는 방식과 마찬가지로, 별도 프로세스인 **Extension Host**에서 패키지 코드를 실행합니다. 앱의 백그라운드 서비스(Kernel)는 열린 프로젝트마다 Extension Host를 하나씩 실행하며, 해당 프로젝트를 열고 있는 모든 데스크톱 창과 CLI가 이를 공유합니다. 여러분의 코드는 메시지 채널을 통해 `ctx.aigd`로만 앱과 통신합니다.

|  | 데스크톱 앱 | `gamedev` CLI |
| --- | --- | --- |
| 표시되는 UI | 전부: 메뉴, 패널, 뷰, 사용자 지정 편집기, 상태 표시줄, 튜토리얼, 웹뷰 | 슬래시 명령, Tools 행, 메시지, 빠른 선택, 입력 상자, 폼, 진행 표시줄 |
| 데스크톱 전용 호출 | 동작 | `undefined` 또는 아무 동작도 하지 않는 객체로 해석되며, 한 번 로그됨 |
| Extension Host 프로세스 | 프로젝트별 공유 | 프로젝트별 공유 |

프로젝트가 없는 창은 호스트를 실행하지 않습니다. 사용자 레벨에 설치된 패키지는 해당 프로젝트가 제외하지 않는 한 모든 열린 프로젝트에서 실행됩니다.

## 지연 활성화

1. **설치.** 앱이 매니페스트를 읽고 선언된 모든 기여 항목을 한꺼번에 등록합니다: 코드를 전혀 실행하지 않아도 슬래시 명령, Tools 스위치, 메뉴 항목과 뷰가 나타납니다.
2. **활성화.** 무언가가 코드를 필요로 하는 첫 순간(명령 실행, 뷰 열기, 기능 켜기, 일치하는 파일 열기, 엔진 프로젝트 발견)에 호스트가 `main`을 로드하고 `activate(ctx)`를 호출합니다. 의존성이 먼저 활성화됩니다. `activate`에는 30초가 주어집니다.
3. **실행.** 여러분의 핸들러가 앱의 호출에 응답합니다. 등록한 모든 것은 `ctx.subscriptions`에 있습니다.
4. **중지.** 제거, 패키지 비활성화, 업데이트 또는 호스트 재시작 시 호스트가 `deactivate()`(선택 사항)를 호출하고 `ctx.subscriptions`를 정리합니다.

`main`이 있고 이벤트가 전혀 없는 패키지는 첫 렌더링 후(`onStartupFinished`)에 시작됩니다. 전체 이벤트 목록은 [매니페스트 참조](https://ai-game.dev/ko/docs/wiki/app/package-manifest#activation-events)에 있습니다.

호스트는 활성 패키지 집합이 변경될 때, 그리고 크래시 후(1초, 5초, 30초 후) 재시작됩니다. 5분 내에 세 번 크래시하면 사용자가 Packages 창에서 **Reload**를 클릭할 때까지 중지된 상태로 유지됩니다.

## 레벨, 잠금 및 업데이트

사용자는 세 가지 레벨 중 하나로 패키지를 추가합니다:

| 레벨 | 선언 위치 | 공유 범위 |
| --- | --- | --- |
| 사용자 | `~/.ai-game-dev/packages.json` | 이 사용자의 모든 프로젝트 |
| 프로젝트 | `<project>/.ai-game-dev/packages.json` | 커밋됨: 모든 팀원이 받음 |
| 로컬 | `<project>/.ai-game-dev/packages.local.json` | 이 컴퓨터에만 적용되며 절대 커밋되지 않음 |

로컬이 프로젝트를, 프로젝트가 사용자를 이깁니다. 각 레벨 옆의 잠금 파일이 정확한 버전, tarball 및 해시를 고정하므로 팀원이 동일한 바이트를 설치합니다. 자동 업데이트는 기본으로 켜져 있으며(패키지별, 컴퓨터별): 4시간마다 앱이 각 패키지를 선언된 범위 내에서 앱이 실행할 수 있는 최신 버전으로 옮기고, 전체 실행에 대해 알림 하나를 표시합니다. `file:` 링크와 태그에 고정된 GitHub 소스는 절대 자동 업데이트되지 않습니다.

## 오류와 로그

호스트는 모든 실패를 해당 패키지에 귀속시킵니다: `activate`, `deactivate` 또는 핸들러에서 발생한 throw, 여러분의 파일에서 발생한 잡히지 않은 예외 또는 처리되지 않은 rejection, `ctx.reportError(err)` 및 `ctx.log.error(msg, err)`. Packages 창의 각 패키지 **Errors** 탭에는 "N errors · M crashes"와 스택이 포함된 최근 목록이 표시됩니다.

```bash
gamedev pkg logs acme.level-tools          # its last 100 lines
gamedev pkg logs acme.level-tools -f       # and every new one until Ctrl+C
```

로그는 모든 플랫폼에서 `~/.ai-game-dev/daemon/logs/`에 있습니다. 서드파티 패키지의 오류는 AI Game Dev의 크래시 리포팅으로 절대 전송되지 않습니다; AI Game Dev 자체 패키지만 보고하며, 그것도 사용자가 크래시 리포팅에 동의한 경우에만 그렇습니다.

## 권한과 신뢰

AI Game Dev는 VS Code 모델을 따릅니다: **샌드박스도, 권한 프롬프트도 없습니다**. 패키지의 코드는 사용자 자신의 권한으로 실행됩니다: 사용자가 설치하는 다른 프로그램처럼 파일을 읽고 쓰고, 프로세스를 시작하고, 네트워크를 사용할 수 있습니다. 대신 사용자에게 정보를 제공하는 방법은 다음과 같습니다:

- **모든 것이 먼저 표시됩니다.** 패키지가 보여주는 모든 것은 매니페스트에 선언되며 코드가 실행되기 전에 표시됩니다.
- **소유권이 강제됩니다.** 패키지는 자신이 소유한 id만 등록하거나 변경할 수 있습니다(`<package id>.<local>` 명령, 뷰, 컨텍스트 키, `<publisher>--<name>` 서버). 이는 로드 시점과 모든 호출 시점에 검사됩니다. 패키지는 자체 명령, 다른 패키지의 명령, 앱 명령 등 어떤 명령이든 실행할 수 있지만, webview 페이지는 자신이 속한 패키지의 명령과 앱 명령만 실행할 수 있습니다.
- **선언한 내용은 표시됩니다.** 설치 전에 Packages 창은 레지스트리 인덱스에 기록된 내용(네이티브 코드, Claude 플러그인, 의존성)을 보여 줍니다. 설치가 끝나면 패키지가 코드를 실행하는지, 도구 서버를 시작하는지, 게임 엔진을 제공하는지도 보여 줍니다. 이는 정보일 뿐, 결코 차단 장치가 아닙니다.
- **레지스트리 검사.** 커뮤니티 레지스트리의 모든 버전은 자격 증명, 에이전트를 겨냥한 프롬프트 인젝션, 멀웨어, 압축 파일 트릭에 대한 자동 검사를 통과했습니다. 자세한 내용은 [레지스트리 규칙과 검사](https://ai-game.dev/ko/docs/wiki/app/package-registry)를 참고하세요.
- **회수.** AI Game Dev는 악성 버전을 회수할 수 있으며, 모든 앱은 다음 인덱스 조회 시(약 30분 이내) 해당 버전을 비활성화합니다.
- **webview 페이지는 격리됩니다.** 페이지는 Node.js가 없는 샌드박스 프레임에서 실행되며, webview 창은 네트워크에 전혀 접근할 수 없습니다.

제작자라면: 비밀 정보를 포함해 배포하지 말고, 패키지가 하는 일을 README와 매니페스트에서 분명히 드러내며, 파괴적인 작업을 하기 전에는 사용자에게 확인을 받으세요.

## 버전 관리와 호환성

API의 버전을 결정하는 두 가지 숫자가 있으며, 둘 다 여러분 패키지의 `version`은 아닙니다.

- **패키지 API 버전**(현재 0.4.0)은 추가만으로 성장합니다. 새로운 멤버와 기여 지점이 더해질 뿐입니다. 여러분의 `aigd.d.ts`는 자신이 작성된 대상 버전을 명시합니다.
- **지원되는 가장 오래된 `engines.aigd`**(현재 0.18.0)는 앱이 여전히 로드하는 최저 하한입니다. 이 값을 올리는 것만이 안정 멤버를 제거하는 유일한 방법이며, 최소 두 번의 마이너 릴리스에 걸친 지원 중단 경고 이후에만 가능합니다.

여러분을 위한 규칙:

- `engines.aigd`는 테스트한 가장 오래된 앱 버전으로 설정하세요. 그보다 오래된 앱은 패키지를 거부하고 사용자에게 업데이트하라고 안내합니다.
- 해당 멤버보다 오래된 앱을 지원하려면 선택적 멤버(`aigd.gameEngines?`, `item.pulse?.()`)를 기능 검사하세요.
- 제안된 멤버는 이 모든 규칙의 적용을 받지 않습니다. [안정 API와 제안 API](https://ai-game.dev/ko/docs/wiki/app/package-api#stable-vs-proposed)를 참고하세요.
- 저장된 데이터는 여러분의 것입니다. `dataVersion`으로 버전을 매기고 `activate`에서 마이그레이션하세요.

## 관련 페이지

- 호출에 대해서는 [Package API](https://ai-game.dev/ko/docs/wiki/app/package-api)를 참고하세요.
- 사용자 관점의 레벨과 업데이트는 [Packages](https://ai-game.dev/ko/docs/wiki/app/packages)를 참고하세요.
- `pkg logs`, `link`, `dev`에 대해서는 [Package CLI 레퍼런스](https://ai-game.dev/ko/docs/wiki/app/package-cli)를 참고하세요.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/app/package-lifecycle

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/app/package-lifecycle
