이 페이지는 영어에서 기계 번역되었습니다. 영어 원문 읽기.

패키지 만들기

나만의 AI Game Dev 패키지를 작성하세요: aigd-package.json 매니페스트, 명령, 슬래시 명령, MCP 도구, gamedev pkg dev를 이용한 로컬 개발, 공유하기.

2026년 11월 4일 업데이트 Markdown으로 보기

패키지는 자사 기능 전용이 아닙니다. 반복되는 작업을 팀과 공유하거나, 에이전트용 도구를 추가하거나, 사용자 지정 파일 형식을 미리 보기 위해 직접 작성할 수 있습니다. 이 페이지에서는 패키지 구조, 최소 동작 패키지, 주요 매니페스트 필드, MCP 도구 추가 방법, 실행 중인 앱을 대상으로 패키지를 개발하는 방법, 공유하는 방법을 설명합니다.

필요한 것

  • AI Game Dev 데스크톱 앱 또는 gamedev CLI, 버전 0.18.0 이상.
  • 텍스트 편집기. JavaScript는 선택 사항입니다. 패키지는 매니페스트만으로도 구성할 수 있습니다.

패키지는 VS Code 확장 모델을 따릅니다. 매니페스트 aigd-package.json이 있는 폴더와, 선택적으로 activate(ctx)와 deactivate()를 내보내는 코드로 이루어집니다. 코드는 ctx.aigd를 통해서만 앱에 접근합니다. 코드는 열린 프로젝트마다 하나씩 생성되는 별도의 확장 호스트 프로세스에서 실행되며, 필요할 때 지연 시작됩니다.

패키지 구조

my-first-package/
  aigd-package.json     the manifest (required)
  extension.js          the code named by "main" (optional)
  media/                icons and images (optional)
  LICENSE

패키지는 자체 완결적이어야 합니다. 앱은 패키지를 위해 npm install을 실행하지 않습니다. 코드에서 라이브러리를 사용한다면 main이 가리키는 파일에 번들로 포함하세요.

최소 패키지

이 패키지는 /my-first 슬래시 명령, 명령 팔레트 항목, 컴포저 툴바 버튼, 상태 표시줄 항목, 설정 하나를 추가합니다.

{
  "publisher": "you",
  "name": "my-first-package",
  "version": "0.1.0",
  "displayName": "My First Package",
  "description": "A /my-first slash command, a palette command, a toolbar button and a status bar item.",
  "license": "MIT",
  "main": "extension.js",
  "engines": { "aigd": ">=0.18.0" },
  "activationEvents": ["onSlashCommand:/my-first", "onCommand:you.my-first-package.hello"],
  "contributes": {
    "commands": [
      { "command": "you.my-first-package.hello", "title": "Say hello", "category": "My First Package", "icon": "$(smile)" }
    ],
    "slashCommands": [
      { "name": "/my-first", "description": "Say hello from my first package", "argumentHint": "[name]" }
    ],
    "menus": {
      "composer/toolbar": [{ "command": "you.my-first-package.hello", "group": "navigation" }]
    },
    "statusBar": [
      { "id": "you.my-first-package.status", "text": "My package", "command": "you.my-first-package.hello", "alignment": "left" }
    ],
    "settings": {
      "name": { "type": "string", "default": "game dev", "description": "Who /my-first greets", "scope": "project" }
    }
  }
}

그리고 코드, extension.js(CommonJS)입니다:

const ID = "you.my-first-package";

exports.activate = function activate(ctx) {
  const { aigd } = ctx;
  let count = 0;

  ctx.subscriptions.push(
    aigd.commands.registerCommand(`${ID}.hello`, async () => {
      count++;
      await aigd.window.showInformationMessage(`Hello #${count} from my first package!`);
      return count;
    }),
    // Works in the desktop chat and in the CLI.
    aigd.commands.registerSlashCommand("/my-first", (inv) => {
      const who = inv.args.trim() || aigd.settings.get("name") || "game dev";
      inv.say(`Hi ${who}!`);
    }),
  );

  ctx.log.info("activated");
};

exports.deactivate = function deactivate() {};

슬래시 명령, 툴바 버튼, 상태 표시줄 항목은 코드가 실행되기 전에 매니페스트에서부터 나타납니다. activate는 이들 중 하나가 처음 사용될 때 호출됩니다.

ID 및 이름 규칙

  • 패키지 id는 publisher.name 형식의 소문자입니다. 여기서는 you.my-first-package입니다. publisher는 2~40자(영문자, 숫자, 단일 하이픈)입니다. 자신의 publisher 이름을 사용하세요. aigd는 AI Game Dev의 것입니다.
  • 패키지가 기여하는 모든 id(명령, 뷰, 상태 표시줄 항목, 튜토리얼)는 패키지 id로 시작합니다: you.my-first-package.hello.
  • engines.aigd는 필수입니다: 패키지가 필요로 하는 최소 AI Game Dev 버전으로, 예를 들어 ">=0.18.0"입니다. 더 오래된 앱은 패키지를 거부하고 필요한 버전을 알려 줍니다.
  • version은 semver입니다. 설치는 id와 버전으로 캐시되므로, 게시하는 모든 변경에는 더 높은 버전이 필요합니다.

주요 매니페스트 필드

필드필수목적
publisher, name, version예id와 버전
engines.aigd예최소 앱 버전
displayName, description, icon, license, homepage, repository, keywords아니요Packages 창에 표시되는 내용
main아니요코드 진입점. 없으면 패키지는 기여 항목만 제공합니다
activationEvents아니요코드를 시작하는 추가 이벤트입니다(예: onStartupFinished).
hosts아니요desktop, cli 또는 둘 다
dependencies아니요다른 패키지, { "<id>": "<range>" }
claudePlugins아니요패키지가 필요로 하는 Claude 플러그인, { "<plugin>@<marketplace>": "<range>" }
contributes아니요패키지가 추가하는 모든 것(아래 참조)

contributes의 기여 지점에는 commands, slashCommands, capabilities(세션의 Tools 행에 있는 스위치), mcpServers, settings, panels, viewsContainers와 views(측면 패널의 트리 또는 웹뷰 뷰), menus와 submenus, keybindings, customEditors, statusBar, tutorials가 있습니다. 메뉴는 commandPalette, composer/toolbar, explorer/context, editor/title, view/item/context 같은 고정 id를 사용하며, 각각 선택적 when 절을 가집니다. CLI는 슬래시 명령, Tools 행, 메시지, 빠른 선택, 입력 상자, 폼을 표시하고, 메뉴와 패널은 데스크톱 전용입니다.

MCP 서버로 에이전트에 도구 제공하기

패키지를 작성하는 가장 흔한 이유는 에이전트에 새 도구를 제공하는 것입니다. MCP 서버와, 세션별로 이를 켜는 capability를 선언하세요:

{
  "publisher": "you",
  "name": "level-tools",
  "version": "0.1.0",
  "engines": { "aigd": ">=0.18.0" },
  "contributes": {
    "capabilities": [
      {
        "id": "you.level-tools",
        "label": "Level tools",
        "description": "Counts collectibles in the level files.",
        "defaultEnabled": false,
        "mcpServer": "you--level-tools"
      }
    ],
    "mcpServers": {
      "you--level-tools": {
        "command": "${node}",
        "args": ["${packageDir}/server.js"]
      }
    }
  }
}
  • 서버 이름은 패키지 id의 <publisher>--<name>(또는 <publisher>--<name>-<suffix>) 형식이어야 하며 최대 96자입니다. 그래야 서로 다른 작성자의 이름이 충돌하지 않습니다. 한정자 없는 이름은 오류입니다.
  • stdio 서버에서 사용할 수 있는 변수: ${node}, ${packageDir}, ${projectDir}, ${globalStorage}.
  • 같은 이름의 MCP 서버가 세션에 이미 구성되어 있으면 패키지의 서버는 추가되지 않고 세션에 알림이 표시됩니다.

실행 중인 앱을 대상으로 개발하기

게시된 버전 대신 프로젝트가 여러분의 폴더를 가리키도록 하세요. 폴더는 제자리에서 사용되며, 패키지가 포함한 파일이 변경되면 다시 로드되고, 자동 업데이트되지 않습니다. 기본 레벨은 Local이며, 커밋되지 않습니다.

cd <your project>
gamedev pkg link <path-to-your-package>      # use the folder (default --local)
gamedev pkg list                             # shows "(local dev)" and which level it overrides
gamedev pkg unlink you.my-first-package      # back to the published version

패키지에 빌드 단계가 있다면(src/가 dist/로 빌드됨) 대신 gamedev pkg dev를 사용하세요. 이 명령은 패키지의 dev 스크립트를 실행하거나 소스가 변경될 때마다 build를 다시 실행하고, 첫 빌드가 성공한 뒤 폴더를 링크하며, Ctrl+C를 누르면 시작한 모든 프로세스를 중지합니다:

gamedev pkg dev <path-to-your-package>

데스크톱 앱에서는 Packages 창에서 같은 작업을 할 수 있습니다: 패키지를 선택하고 **Use a local folder…**를 고른 뒤, 되돌리려면 Stop using local folder를 선택하세요. 매니페스트에 다른 id가 적힌 폴더는 거부됩니다.

패키지 공유하기

AI Game Dev 레지스트리에는 퍼스트파티 패키지가 있습니다. 직접 만든 패키지를 공유하려면 GitHub나 npm에 게시하세요. 그러면 누구나 링크로 추가할 수 있습니다:

gamedev pkg add github:you/my-first-package           # not pinned: receives updates
gamedev pkg add github:you/my-first-package@v0.1.0    # a tag (never auto-updated)
gamedev pkg add npm:my-first-package                  # an npm package
gamedev pkg add npm:my-first-package@^0.1.0           # with a version range

팀에서 사용한다면 Project 레벨로 추가해 .ai-game-dev/packages.json에 커밋되도록 하세요. 그러면 프로젝트 잠금 파일에 고정된 상태로 모든 팀원이 사용할 수 있습니다.

새 버전을 게시하기 전에 aigd-package.json의 version을 올리세요. 버전이 그대로인데 변경된 파일은 이미 해당 버전이 설치된 곳에는 전달되지 않습니다.

권장 사항

  • 도구는 목적에 집중하세요. 에이전트가 보는 모든 도구는 컨텍스트를 차지합니다. 작고 설명이 잘 된 도구일수록 올바르게 사용되는 경우가 많습니다.
  • 매니페스트에 가능한 한 모든 것을 선언해, 코드가 시작되기 전에 UI가 보이도록 하세요.
  • 팀이 공유해야 하는 설정에는 scope: "project"를, 한 컴퓨터의 경로에는 scope: "machine"을 사용하세요.
  • 패키지는 샌드박스 없이 사용자의 권한으로 실행됩니다. 패키지에 비밀 정보를 포함하지 말고, 패키지가 하는 일을 사용자에게 알리세요.

더 알아보기