Pi Packages

pi는 pi 패키지를 만드는 데 도움이 될 수 있습니다. 확장 프로그램, 기술, prompt templates 또는 테마를 번들로 묶어달라고 요청하세요.

Pi 패키지에는 확장 프로그램, 기술, prompt templates 및 테마가 번들로 포함되어 있어 npm 또는 git을 통해 공유할 수 있습니다. 패키지는 pi 키 아래의 package.json에서 리소스를 선언하거나 기존 디렉터리를 사용할 수 있습니다.

• Install and Manage
• Package Sources
• Creating a Pi Package
• Package Structure
• Dependencies
• Package Filtering
• Enable and Disable Resources
• Scope and Deduplication

보안: Pi 패키지는 전체 시스템 액세스 권한으로 실행됩니다. Extensions 임의의 코드를 실행하면 기술이 실행 파일 실행을 포함한 모든 작업을 수행하도록 모델에 지시할 수 있습니다. 타사 패키지를 설치하기 전에 소스 코드를 검토하세요.

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw URLs work too
pi install /absolute/path/to/package
pi install ./relative/path/to/package

pi remove npm:@foo/bar
pi list                     # show installed packages from settings
pi update                   # update pi only
pi update --all             # update pi, update packages, and reconcile pinned git refs
pi update --extensions      # update packages and reconcile pinned git refs only
pi update --models          # refresh model catalogs only
pi update --self            # update pi only
pi update --self --force    # reinstall pi even if current
pi update npm:@foo/bar      # update one package
pi update --extension npm:@foo/bar

이 명령은 pi 패키지를 관리하고 pi update는 pi CLI 설치를 업데이트할 수 있습니다. pi 자체를 제거하려면 Quickstart를 참조하세요.

기본적으로 install 및 remove는 사용자 설정(~/.pi/agent/settings.json)에 기록됩니다. 대신 -l를 사용하여 프로젝트 설정(.pi/settings.json)에 쓰세요. 프로젝트 설정은 팀과 공유할 수 있으며, pi는 프로젝트를 신뢰한 후 시작 시 누락된 패키지를 자동으로 설치합니다.

패키지를 설치하지 않고 사용해 보려면 --extension 또는 -e를 사용하세요. 이는 현재 실행을 위한 임시 디렉토리에만 설치됩니다.

pi -e npm:@foo/bar
pi -e git:github.com/user/repo

Pi는 설정에서 세 가지 소스 유형을 허용하고 pi install는 허용합니다.

npm:@scope/pkg@1.2.3
npm:pkg

• 버전이 지정된 사양은 패키지 업데이트(pi update --extensions, pi update --all)에 의해 고정되고 건너뜁니다.
• 사용자 설치는 ~/.pi/agent/npm/ 아래에 있습니다.
• 프로젝트 설치는 .pi/npm/ 아래에 있습니다.
• settings.json에서 npmCommand를 설정하여 npm 패키지 조회를 고정하고 작업을 mise 또는 asdf와 같은 특정 래퍼 명령에 설치합니다.

예:

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• git: 접두사가 없으면 프로토콜 URL만 허용됩니다(https://, http://, ssh://, git://).
• git: 접두사를 사용하면 github.com/user/repo 및 git@github.com:user/repo를 포함한 단축 형식이 허용됩니다.
• HTTPS 및 SSH URL이 모두 지원됩니다.
• SSH URL은 구성된 SSH 키를 자동으로 사용합니다(~/.ssh/config 참조).
• 비대화형 실행(예: CI)의 경우 GIT_TERMINAL_PROMPT=0를 설정하여 자격 증명 프롬프트를 비활성화하고 GIT_SSH_COMMAND(예: ssh -o BatchMode=yes -o ConnectTimeout=5)을 설정하여 빠르게 실패하도록 설정할 수 있습니다.
• 참조는 고정된 태그 또는 커밋입니다. pi update --extensions 및 pi update --all는 최신 참조로 이동하지 않지만 기존 복제본을 구성된 참조로 조정합니다.
• pi install git:host/user/repo@new-ref를 사용하여 설정을 업데이트하고 기존 패키지를 새로 고정된 참조로 이동하세요.
• ~/.pi/agent/git/<host>/<path>(글로벌) 또는 .pi/git/<host>/<path>(프로젝트)에 복제되었습니다.
• 조정으로 인해 체크아웃이 변경되면 pi는 복제본을 재설정하고 정리한 다음 package.json가 존재하는 경우 npm install를 실행합니다.

SSH 예:

# git@host:path shorthand (requires git: prefix)
pi install git:git@github.com:user/repo

# ssh:// protocol format
pi install ssh://git@github.com/user/repo

# With version ref
pi install git:git@github.com:user/repo@v1.0.0

/absolute/path/to/package
./relative/path/to/package

로컬 경로는 디스크의 파일이나 디렉터리를 가리키며 복사하지 않고 설정에 추가됩니다. 상대 경로는 해당 경로가 나타나는 설정 파일을 기준으로 확인됩니다. 경로가 파일인 경우 단일 확장자로 로드됩니다. 디렉터리인 경우 pi는 패키지 규칙을 사용하여 리소스를 로드합니다.

pi 매니페스트를 package.json에 추가하거나 기존 디렉터리를 사용하세요. 검색 가능성을 위해 pi-package 키워드를 포함하세요.

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

경로는 패키지 루트를 기준으로 합니다. 배열은 glob 패턴과 !exclusions을 지원합니다.

package gallery는 pi-package 태그가 붙은 패키지를 표시합니다. 미리보기를 표시하려면 video 또는 image 필드를 추가하세요.

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

• 동영상: MP4 전용. 데스크톱에서는 마우스를 올리면 자동 재생됩니다. 클릭하면 전체 화면 플레이어가 열립니다.
• 이미지: PNG, JPEG, GIF 또는 WebP. 정적 미리보기로 표시됩니다.

둘 다 설정된 경우 비디오가 우선 적용됩니다.

pi 매니페스트가 없으면 pi는 다음 디렉터리에서 리소스를 자동 검색합니다.

• extensions/ .ts 및 .js 파일을 로드합니다.
• skills/ SKILL.md 폴더를 반복적으로 찾아 최상위 .md 파일을 스킬로 로드합니다.
• prompts/ .md 파일 로드
• themes/ .json 파일 로드

타사 런타임 종속성은 package.json의 dependencies에 속합니다. 확장, 스킬, prompt templates 또는 테마를 등록하지 않는 종속성도 dependencies에 속합니다. pi가 npm 또는 git에서 패키지를 설치하면 npm install가 실행되므로 해당 종속성이 자동으로 설치됩니다.

Pi 확장 기능과 기술을 위한 핵심 패키지를 번들로 제공합니다. 이들 중 하나를 가져오는 경우 peerDependencies에 "*" 범위로 나열하고 묶지 마세요: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

다른 pi 패키지는 tarball에 번들로 포함되어야 합니다. dependencies 및 bundledDependencies에 추가한 다음 node_modules/ 경로를 통해 리소스를 참조합니다. Pi 별도의 모듈 루트로 패키지를 로드하므로 별도의 설치로 인해 모듈이 충돌하거나 공유되지 않습니다.

예:

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "pi": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

설정에서 개체 양식을 사용하여 패키지가 로드하는 항목을 필터링합니다.

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

+path 및 -path은 패키지 루트를 기준으로 한 정확한 경로입니다.

• 해당 유형을 모두 로드하려면 키를 생략하세요.
• 해당 유형을 로드하지 않으려면 []를 사용하세요.
• !pattern 일치하는 항목은 제외됩니다.
• +path 강제로 정확한 경로를 포함합니다.
• -path 정확한 경로를 강제로 제외합니다.
• 매니페스트 위에 필터 레이어가 있습니다. 이미 허용된 항목의 범위를 좁힙니다.

pi config를 사용하여 확장 프로그램, 기술, prompt templates 및 설치된 패키지와 로컬 디렉터리의 테마를 활성화하거나 비활성화합니다. pi config 전역 설정에서 시작합니다(~/.pi/agent/settings.json). 전역 모드와 프로젝트-로컬 모드 사이를 전환하려면 Tab 키를 누르세요. 상속된 전역 리소스가 흐리게 표시된 프로젝트 재정의(.pi/settings.json)를 시작하려면 pi config -l를 사용하세요.

패키지는 전역 설정과 프로젝트 설정 모두에 나타날 수 있습니다. 동일한 패키지가 둘 다에 나타나는 경우 프로젝트 항목에 autoload: false이 없으면 프로젝트 항목이 우선합니다. 이 경우 전역 항목에 대한 델타로 적용됩니다. 신원은 다음에 의해 결정됩니다.

• npm: 패키지 이름
• git: 참조가 없는 저장소 URL
• 로컬: 확인된 절대 경로