# 패키지 API — AI Game Dev 앱 & CLI · AI Game Developer Wiki

AI Game Dev 패키지의 ctx.aigd API: 모든 네임스페이스, 안정 멤버와 제안 멤버, 데스크톱 전용 호출, 그리고 도구·UI·상태에 대한 실제 예제.

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

패키지의 코드는 `activate(ctx)`에 전달되는 하나의 객체인 `ctx.aigd`를 통해 앱에 접근합니다. 이 페이지는 그 네임스페이스를 나열하고, 어떤 멤버가 안정(stable)이고 어떤 멤버가 제안(proposed)인지 설명하며, 대부분의 패키지가 사용하는 호출의 실제 예제를 보여줍니다: 명령, 슬래시 명령, 에이전트 도구, 설정, 메시지, 웹뷰, 트리 뷰, 사용자 지정 편집기, 튜토리얼, 저장된 상태. 패키지 API의 버전은 0.4.0입니다.

## 타입

`gamedev pkg init`은 전체 API를 자체 포함된 하나의 파일인 `src/types/aigd.d.ts`로 작성합니다. 이 파일은 앱 자체의 계약에서 생성되며, 이를 작성한 앱 버전과 일치합니다. TypeScript는 이 파일을 import하고, JavaScript는 JSDoc에서 사용합니다:

```typescript
import type { PackageContext } from "./types/aigd";

export async function activate(ctx: PackageContext): Promise<void> {
  ctx.subscriptions.push(ctx.aigd.commands.registerCommand("acme.level-tools.hello", () => "hi"));
}

export function deactivate(): void {}
```

```javascript
/** @param {import("./types/aigd").PackageContext} ctx */
exports.activate = function activate(ctx) { /* … */ };
```

임시 폴더에서 최신 `gamedev pkg init`을 실행하면 더 새로운 버전의 타입 복사본을 얻을 수 있습니다. npm 타입 패키지(`@ai-game-dev/package-api`)는 준비되었지만 아직 게시되지 않았습니다.

모든 호출은 프로세스 경계를 넘습니다(코드는 앱의 Extension Host에서 실행됩니다). 따라서 인수와 결과는 JSON 값이어야 하며, 앱과 통신하는 모든 메서드는 비동기입니다. 몇 안 되는 동기 멤버(`env`, `project.path`, `settings.get`)는 패키지가 시작될 때 앱이 전달한 상태를 읽습니다.

## 컨텍스트

| 멤버 | 설명 |
| --- | --- |
| `ctx.aigd` | API(아래 참조) |
| `ctx.package` | 이 패키지: `id`, `publisher`, `name`, `version`, `displayName`, `dir`, `manifest` |
| `ctx.subscriptions` | 모든 `Disposable`을 여기에 추가하세요. 패키지가 중지되면 앱이 이를 정리합니다 |
| `ctx.globalState`, `ctx.projectState` | 이 컴퓨터용, 그리고 이 컴퓨터의 이 프로젝트용 소형 키-값 저장소 |
| `ctx.globalStoragePath`, `ctx.projectStoragePath` | 패키지가 쓸 수 있는 폴더 |
| `ctx.log` | `debug`, `info`, `warn`, `error`: 앱 로그에 `pkg:<id>` 태그로 기록되는 줄 |
| `ctx.asAbsolutePath(rel)` | 패키지 폴더 내부의 경로 |
| `ctx.reportError(err, subject?)` | Packages 창의 Errors 목록에 오류를 기록합니다 |

## 네임스페이스

| 네임스페이스 | 설명 | 상태 |
| --- | --- | --- |
| `env` | 호스트(`desktop` 또는 `cli`), 앱 버전, 플랫폼, `nodeCommand`, 시스템 프록시를 통한 `fetch`, `openExternal`, 클립보드(데스크톱) | 안정 |
| `commands` | 명령과 슬래시 명령을 등록하고 실행하며, `when` 컨텍스트 키를 설정합니다 | 안정 |
| `capabilities` | Tools 스위치의 상태, 활성화 및 채팅별 연결 | 안정 |
| `mcp` | 이 프로젝트용 MCP 서버를 등록합니다 | 안정 |
| `agent` | 메모리 내에서 에이전트 도구를 제공합니다(`registerProvider`) | 안정 |
| `gameEngines` | 게임 엔진을 구현합니다(`registerEngine`, `host`) | 0.4.0부터 안정 |
| `settings` | 설정을 읽고 쓰며 변경 사항을 감시합니다 | 안정 |
| `project` | 프로젝트 경로와 `getInfo()`(엔진, 엔진 버전, 폴더 내 엔진 프로젝트) | 안정 |
| `packages` | 다른 패키지와 그 export(`all`, `get`, `getExports`) | 안정 |
| `claude` | 이 프로젝트의 채팅에 Claude Code 플러그인 폴더를 추가합니다(`registerPlugin`) | 안정 |
| `editor` | 연결된 엔진 편집기의 도구로, 프로바이더가 연결된 채팅에서 사용합니다 | 안정 |
| `account` | 로그인한 계정의 기능 카탈로그(`getSnapshot`) | 안정 |
| `media` | `contributes.mediaProviders`에 선언된 로컬 미디어 생성기를 등록합니다(`registerProvider`) | 안정 |
| `window` | 메시지, 빠른 선택, 입력 상자, 진행률, 상태 표시줄, 웹뷰, 트리 뷰, 사용자 지정 편집기 | 안정, 데스크톱 |
| `tutorials` | 앱 내 팁을 요청하고 추적합니다 | 안정, 데스크톱 |
| `sessions` | `list()`, `active()` 및 라이브 이벤트는 안정이며, 트랜스크립트·프롬프트·채팅별 구성은 제안입니다 | 혼합 |
| `storage`, `downloads`, `hardware` | 앱의 blob 저장소, 검증된 다운로드, 하드웨어 프로브 | 제안 |
| `tasks`, `subscriptions`, `work` | 백그라운드 작업 관찰, 장기 실행 작업, 작업 홀드 | 제안 |

`aigd.d.ts`에서 `@desktop`으로 표시된 멤버는 CLI에서 아무 동작도 하지 않습니다. `undefined`로 해석되거나 아무 기능도 없는 객체를 반환하며, 호스트가 한 줄을 로그로 남깁니다. 터미널에서 패키지가 다르게 동작해야 한다면 `aigd.env.host`를 확인하세요.

## 안정 API와 제안 API

**안정** 멤버는 모든 앱 릴리스에서 그 의미를 유지합니다. 변경은 추가만 허용되며, 안정 멤버는 최소 두 번의 마이너 앱 릴리스 동안 지원 중단 경고(`gamedev pkg logs`에서 패키지별 세션당 한 줄)를 낸 뒤에만 제거되며, 이때 앱이 로드하는 가장 오래된 `engines.aigd` 버전도 함께 올라갑니다.

**제안** 멤버는 어느 릴리스에서든 변경되거나 사라질 수 있습니다. 이를 호출하려면 해당 제안을 선언해야 하며, 선언 없이 호출하면 제안 이름을 알려주는 메시지와 함께 실패합니다:

```json
{ "enabledApiProposals": ["forms"] }
```

| 제안 | 멤버 |
| --- | --- |
| `forms` | `window.showForm` |
| `alerts` | `window.showAlert` |
| `sessions` | `sessions.getTranscript`, `sendPrompt`, `create`, `focusComposer` |
| `sessionConfiguration` | 채팅별 패키지 구성 및 Tools 모듈(`sessions.getConfiguration`, `updateConfiguration`, `registerToolStateProvider`, …) |
| `appFocus` | `window.keepInFront` |
| `storage`, `downloads`, `hardware` | blob 저장소, 다운로드 관리자, 하드웨어 프로브 |
| `backgroundTasks`, `subscriptions`, `workHolds` | `tasks.*`, `subscriptions.open`, `work.hold` |
| `paidOperations`, `mockJobs` | 유료 서버 작업(AI Game Dev 자체 제공자 패키지에만 해당) 및 해당 개발 시뮬레이션 |

**경고**

커뮤니티 레지스트리는 proposal을 선언한 모든 패키지를 거부합니다. proposal이 필요한 패키지도 GitHub, npm 또는 폴더에서 공유할 수 있습니다. [패키지 게시](https://ai-game.dev/ko/docs/wiki/app/publishing-packages#other-sources)를 참조하세요.

## 명령 및 슬래시 명령

```typescript
const ID = "acme.level-tools";

ctx.subscriptions.push(
  aigd.commands.registerCommand(`${ID}.count`, async (...args) => {
    const n = await countCollectibles();
    await aigd.window.showInformationMessage(`${n} collectibles in this level`);
    return n;
  }),
  aigd.commands.registerSlashCommand("/collectibles", async (inv) => {
    inv.say("Counting…");                       // a system line in the chat, live
    const n = await countCollectibles(inv.args.trim());
    inv.say(`${n} collectibles.`);
  }),
);

await aigd.commands.setContext(`${ID}.hasLevel`, true);   // usable in when clauses
await aigd.commands.executeCommand("aigd.packages.open", { packageId: ID });
```

슬래시 명령은 이름 뒤의 텍스트(`inv.args`), 입력된 채팅(`inv.sessionId`), 실시간 라인을 위한 `say()`, 그리고 사용자가 Esc 또는 Stop을 누르면 완료되는 프로미스인 `cancelled`를 받습니다. 슬래시 명령은 데스크톱 채팅과 CLI에서 동일하게 동작합니다. 패키지가 실행할 수 있는 앱 명령에는 `aigd.packages.open`, `aigd.packages.reload`, `aigd.packages.checkForUpdates`, `aigd.session.focus`, `aigd.settings.open`, `aigd.tutorials.show`가 있습니다.

## 에이전트에게 도구 제공하기

**선언된 MCP 서버.** 가장 간단한 방법입니다. 서버와 채팅별로 이를 켜는 기능을 선언하세요. 코드가 필요 없습니다. 서버는 앱의 Node로 시작되는 여러분의 스크립트입니다:

```json
{
  "contributes": {
    "capabilities": [
      { "id": "acme.level-tools", "label": "Level tools", "description": "Counts collectibles in level files.", "mcpServer": "acme--level-tools" }
    ],
    "mcpServers": {
      "acme--level-tools": { "command": "${node}", "args": ["${packageDir}/server.js"] }
    }
  }
}
```

**런타임에 등록되는 MCP 서버.** 무언가가 시작된 후에야 주소를 알 수 있는 서버(외부 앱의 포트)의 경우:

```typescript
await aigd.mcp.registerServer("acme--level-tools", { type: "http", url: `http://127.0.0.1:${port}/mcp` });
```

**코드에서 제공하는 도구.** 에이전트 제공자를 사용하면 서버 프로세스 없이 패키지 안에 도구를 둘 수 있습니다. 해당 기능과 함께 선언한 다음 등록하세요:

```json
{
  "contributes": {
    "capabilities": [{ "id": "acme.helper", "label": "Helper", "description": "Helper tools", "defaultEnabled": true }],
    "agentProviders": [{ "id": "acme.helper.agent", "serverName": "acme--helper", "capabilityId": "acme.helper" }]
  }
}
```

```typescript
ctx.subscriptions.push(await aigd.agent.registerProvider("acme.helper.agent", {
  getTools: () => [{
    name: "status",
    description: "Read the helper's status",
    inputSchema: { type: "object", properties: {}, additionalProperties: false },
  }],
  getInstructions: () => "Use the helper's status tool when working in this project.",
  invokeTool: async (name, args, context) => ({ content: [{ type: "text", text: context.project.path }] }),
}));
```

도구의 입력 스키마는 객체 루트를 가져야 하며, 최상위 `oneOf`, `anyOf`, `allOf`가 없어야 합니다. 결과에는 텍스트와 이미지(`{ type: "image", data, mimeType }`, PNG, JPEG 또는 WebP)가 포함될 수 있습니다. 앱의 검사를 통과하지 못한 이미지는 오류가 아니라 안내 문구로 대체됩니다. 기본 도구 제한 시간은 60초입니다(`executionTimeoutMs`, 최대 1시간).

**상태가 있는 기능.** 켜는 데 작업이 필요한 경우(외부 앱 시작) 기능에 `statusful: true`를 설정하세요. 그러면 앱이 스위치에 상태를 표시하고 활성화 핸들러를 호출합니다:

```typescript
ctx.subscriptions.push(
  aigd.capabilities.registerStatusProvider("acme.level-tools", async () =>
    (await isRunning()) ? { phase: "connected", detail: "Editor 4.2" } : { phase: "idle" }),
  aigd.capabilities.registerActivationHandler("acme.level-tools", async (req) => {
    req.progress("Starting the level server…");
    try { await start(); return { ok: true }; }
    catch (e) { return { ok: false, failure: { code: "start-failed", text: String(e) } }; }
  }),
);
```

## 설정

```typescript
const quality = aigd.settings.get<string>("quality") ?? "draft";
await aigd.settings.update("quality", "final", "project");   // user, project or local
ctx.subscriptions.push(aigd.settings.onDidChange((e) => ctx.log.info(`${e.key} is now ${String(e.value)}`)));
```

키는 여러분의 것이며(패키지 접두사 제외) `contributes.settings`에 선언해야 합니다. 모든 쓰기는 선언에 대해 검증됩니다.

## 메시지, 선택기, 진행률

```typescript
const choice = await aigd.window.showWarningMessage("Overwrite the export?", { modal: true }, "Overwrite", "Keep");
const level = await aigd.window.showQuickPick(["forest", "cave", "castle"], { title: "Export which level?" });
const name = await aigd.window.showInputBox({ prompt: "File name", value: "level-1" });

await aigd.window.withProgress({ title: "Exporting", cancellable: true }, async (progress, cancelled) => {
  progress.report({ message: "Meshes", increment: 50 });
  progress.report({ message: "Textures", increment: 50 });
});

const item = aigd.window.createStatusBarItem("acme.level-tools.status", { alignment: "left" });
item.text = "3 levels";
item.command = "acme.level-tools.count";
item.show();
ctx.subscriptions.push(item);
```

CLI에서는 메시지가 시스템 라인으로 출력됩니다. 모달 메시지, 빠른 선택, 입력 상자는 슬래시 명령이 실행되는 동안 터미널 프롬프트가 됩니다. 슬래시 명령 외부에서 CLI는 `PromptRefusedError`(코드 `prompt_refused`)와 함께 프롬프트를 거부하므로, 질문을 하는 패키지는 슬래시 명령에서 질문하거나 `aigd.env.host`를 확인해야 합니다.

## 웹뷰: 패널, 사이드 뷰, 창

웹뷰는 앱(데스크톱) 내부의 여러분의 HTML 페이지입니다. 동일한 페이지가 팬, 사이드 패널 탭 또는 자체 창에서 동작합니다:

```typescript
const panel = aigd.window.createWebviewPanel("acme.level-tools.map", "Level map");
const script = panel.webview.asWebviewUri(ctx.asAbsolutePath("dist/map.js"));
panel.webview.html = `<!doctype html><html><body><canvas id="map"></canvas>
  <script type="module" src="${script}"></script></body></html>`;
panel.webview.onDidReceiveMessage((msg) => ctx.log.info(`page says ${JSON.stringify(msg)}`));
await panel.webview.postMessage({ type: "level", tiles });
```

```javascript
// dist/map.js, inside the page
const api = acquireAigdApi();
api.postMessage({ type: "ready" });
window.addEventListener("message", (e) => draw(e.data));
api.setState({ zoom: 2 });             // restored with the pane after a relaunch
```

- **사이드 패널 탭:** `contributes.views.right` 아래에 `{ "id": "acme.level-tools.side", "name": "Levels", "type": "webview" }`를 선언하고 `aigd.window.registerWebviewViewProvider("acme.level-tools.side", { resolveWebviewView(view) { view.webview.html = page(); } })`를 등록하세요. `"titleBar": "hidden"`을 사용하면 페이지가 자체 헤더를 그릴 수 있습니다.
- **자체 창:** `aigd.window.createWebviewWindow(viewType, title)`는 크기 조절이 가능한 네이티브 창을 엽니다(프로젝트당 뷰 타입별로 하나). 이 페이지는 엄격한 콘텐츠 보안 정책 아래에서 실행됩니다. 패키지 자체 파일만 사용하고, 네트워크와 `eval`은 허용되지 않습니다.
- **테마:** 페이지는 `<html data-theme="light|dark">`와 앱의 팔레트를 `--aigd-*` CSS 변수(`--aigd-bg`, `--aigd-surface`, `--aigd-text`, `--aigd-primary`, …)로 받으며, 테마가 바뀔 때마다 다시 전송됩니다.
- **페이지 API:** `acquireAigdApi()`는 `postMessage`, `getState`, `setState`, `executeCommand`(자체 명령 및 앱 명령), `getContext()`, `close()`를 제공합니다.

## 트리 뷰

```typescript
const tree = aigd.window.createTreeView("acme.level-tools.levels", {
  treeDataProvider: {
    getChildren: async (parent) => parent
      ? listObjects(parent.id).map((o) => ({ id: o.id, label: o.name, icon: "$(box)" }))
      : listLevels().map((l) => ({ id: l.id, label: l.name, collapsible: "collapsed", contextValue: "level" })),
  },
});
tree.message = "3 levels";
ctx.subscriptions.push(tree);
```

뷰는 `contributes.views`에서 `"type": "tree"`로 선언합니다. `contextValue`는 `view/item/context` 메뉴에서 `viewItem`이 됩니다. 항목에는 체크박스, 배지, 클릭 명령을 붙일 수 있습니다.

## 사용자 지정 편집기

```json
{ "contributes": { "customEditors": [{ "viewType": "acme.level-tools.level", "displayName": "Level preview", "selector": [{ "filenamePattern": "*.level.json" }], "priority": "default" }] } }
```

```typescript
ctx.subscriptions.push(aigd.window.registerCustomEditorProvider("acme.level-tools.level", {
  resolveCustomEditor(document, panel) {
    panel.webview.html = renderLevel(fs.readFileSync(document.path, "utf8"));
  },
}));
```

`default` 편집기는 일치하는 파일에 대해 앱 자체의 미리보기를 대체합니다. `option` 편집기는 Open With 아래에 표시됩니다. 문서는 앱 쪽에서 읽기 전용입니다. 패키지가 직접 파일을 쓰며, 파일이 디스크에서 변경되면 팬이 다시 로드됩니다. `aigd.window.openPreview(path)`는 탐색기에서 클릭한 것처럼 프로젝트 파일을 미리보기에 표시합니다.

## 튜토리얼

```json
{ "contributes": { "tutorials": [{ "id": "acme.level-tools.intro", "title": "Count collectibles", "anchor": "slashCommand:/collectibles", "markdown": "tutorials/intro.md" }] } }
```

```typescript
ctx.subscriptions.push(aigd.tutorials.request("acme.level-tools.intro"));
```

팁은 사용자마다 한 번, 조용한 시점에 표시되며, 앵커를 가리킵니다: `capability:`, `statusBar:`, `view:`, `slashCommand:`, `command:` 또는 `menu:` 뒤에 id가 오거나, `composer`, `none`입니다. `markdown`은 최대 8개의 `media` 파일과 함께, 또는 풍부한 콘텐츠용 `webview` 페이지와 함께 사용합니다. `request(id, { force: true })`는 팁을 다시 표시하고, `isSeen`과 `setSeen`은 확인 상태를 읽고 설정합니다.

## 저장된 상태

```typescript
const DATA = 2;
if ((ctx.globalState.dataVersion ?? 0) < DATA) {
  await migrate(ctx.globalState);
  await ctx.globalState.setDataVersion(DATA);
}
await ctx.projectState.update("lastExport", new Date().toISOString());
const last = ctx.projectState.get<string>("lastExport");
```

`globalState`는 이 컴퓨터의 모든 프로젝트가 공유하며, `projectState`는 이 컴퓨터의 이 프로젝트에 속합니다. 둘 다 업데이트와 제거 후에도 유지되며(패키지를 다시 추가하면 복원됩니다), Packages 창의 **Remove data**가 이들을 삭제합니다. 앱은 데이터를 절대 마이그레이션하지 않으므로, `dataVersion`은 직접 비교하고 올려야 합니다.

## 관련 페이지

- 이 호출들과 짝을 이루는 선언은 [Package manifest reference](https://ai-game.dev/ko/docs/wiki/app/package-manifest)를 참고하세요.
- 코드가 실행되는 시점과 코드가 할 수 있는 일은 [Lifecycle, hosts and permissions](https://ai-game.dev/ko/docs/wiki/app/package-lifecycle)를 참고하세요.
- `aigd.gameEngines` 관련 내용은 [Game engine packages](https://ai-game.dev/ko/docs/wiki/app/game-engine-packages)를 참고하세요.

---

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

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