Pi Packages

pi pode ajudá-lo a criar pacotes pi. Peça para agrupar suas extensões, habilidades, prompt templates ou temas.

Os pacotes Pi agrupam extensões, habilidades, prompt templates e temas para que você possa compartilhá-los por meio de npm ou git. Um pacote pode declarar recursos em package.json sob a chave pi ou usar diretórios convencionais.

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

Segurança: Pi pacotes são executados com acesso total ao sistema. Extensions executa código arbitrário e as habilidades podem instruir o modelo a executar qualquer ação, incluindo a execução de executáveis. Revise o código-fonte antes de instalar pacotes de terceiros.

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

Esses comandos gerenciam pacotes pi e pi update podem atualizar a instalação do pi CLI. Para desinstalar o próprio pi, consulte Quickstart.

Por padrão, install e remove gravam nas configurações do usuário (~/.pi/agent/settings.json). Use -l para gravar nas configurações do projeto (.pi/settings.json). As configurações do projeto podem ser compartilhadas com sua equipe e o pi instala todos os pacotes ausentes automaticamente na inicialização, após o projeto ser confiável.

Para testar um pacote sem instalá-lo, use --extension ou -e. Isso é instalado em um diretório temporário apenas para a execução atual:

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

Pi aceita três tipos de fontes nas configurações e pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• As especificações versionadas são fixadas e ignoradas pelas atualizações de pacotes (pi update --extensions, pi update --all).
• As instalações do usuário ficam abaixo de ~/.pi/agent/npm/.
• As instalações do projeto ficam abaixo de .pi/npm/.
• Defina npmCommand em settings.json para fixar a pesquisa de pacote npm e as operações de instalação em um comando wrapper específico, como mise ou asdf.

Exemplo:

{
  "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

• Sem o prefixo git:, apenas URLs de protocolo são aceitos (https://, http://, ssh://, git://).
• Com o prefixo git:, formatos abreviados são aceitos, incluindo github.com/user/repo e git@github.com:user/repo.
• URLs HTTPS e SSH são suportados.
• SSH URLs usam suas chaves SSH configuradas automaticamente (respeita ~/.ssh/config).
• Para execuções não interativas (por exemplo, CI), você pode definir GIT_TERMINAL_PROMPT=0 para desabilitar prompts de credenciais e definir GIT_SSH_COMMAND (por exemplo, ssh -o BatchMode=yes -o ConnectTimeout=5) para falhar rapidamente.
• Refs são tags fixadas ou commits. pi update --extensions e pi update --all não os movem para referências mais recentes, mas reconciliam um clone existente com a referência configurada.
• Use pi install git:host/user/repo@new-ref para atualizar as configurações e mover um pacote existente para uma nova referência fixada.
• Clonado para ~/.pi/agent/git/<host>/<path> (global) ou .pi/git/<host>/<path> (projeto).
• Quando a reconciliação altera o checkout, pi redefine e limpa o clone e, em seguida, executa npm install se package.json existir.

SSH exemplos:

# 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

Os caminhos locais apontam para arquivos ou diretórios no disco e são adicionados às configurações sem serem copiados. Os caminhos relativos são resolvidos em relação ao arquivo de configurações em que aparecem. Se o caminho for um arquivo, ele será carregado como uma única extensão. Se for um diretório, pi carrega recursos usando regras de pacote.

Adicione um manifesto pi a package.json ou use diretórios convencionais. Inclua a palavra-chave pi-package para descoberta.

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

Os caminhos são relativos à raiz do pacote. Matrizes suportam padrões glob e !exclusions.

O package gallery exibe pacotes marcados com pi-package. Adicione os campos video ou image para mostrar uma visualização:

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

• vídeo: somente MP4. No desktop, é reproduzido automaticamente ao passar o mouse. Clicar abre um player em tela cheia.
• imagem: PNG, JPEG, GIF ou WebP. Exibido como uma visualização estática.

Se ambos estiverem definidos, o vídeo terá precedência.

Se nenhum manifesto pi estiver presente, pi descobre automaticamente recursos destes diretórios:

• extensions/ carrega arquivos .ts e .js
• skills/ encontra recursivamente pastas SKILL.md e carrega arquivos .md de nível superior como habilidades
• prompts/ carrega .md arquivos
• themes/ carrega .json arquivos

As dependências de tempo de execução de terceiros pertencem a dependencies em package.json. Dependências que não registram extensões, habilidades, prompt templates ou temas também pertencem a dependencies. Quando pi instala um pacote de npm ou git, ele executa npm install, então essas dependências são instaladas automaticamente.

Pi agrupa pacotes principais para extensões e habilidades. Se você importar algum deles, liste-os em peerDependencies com um intervalo "*" e não os agrupe: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Outros pacotes pi devem ser incluídos no seu tarball. Adicione-os a dependencies e bundledDependencies e faça referência a seus recursos por meio de caminhos node_modules/. Pi carrega pacotes com raízes de módulo separadas, para que instalações separadas não colidam ou compartilhem módulos.

Exemplo:

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

Filtre o que um pacote carrega usando o formulário do objeto nas configurações:

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

+path e -path são caminhos exatos relativos à raiz do pacote.

• Omita uma chave para carregar todo esse tipo.
• Use [] para não carregar nada desse tipo.
• !pattern exclui correspondências.
• +path force-inclui um caminho exato.
• -path força-exclui um caminho exato.
• Camada de filtros na parte superior do manifesto. Eles restringem o que já é permitido.

Use pi config para ativar ou desativar extensões, habilidades, prompt templates e temas de pacotes instalados e diretórios locais. pi config inicia nas configurações globais (~/.pi/agent/settings.json); pressione Tab para alternar entre os modos global e local do projeto. Use pi config -l para iniciar substituições de projeto (.pi/settings.json) com recursos globais herdados esmaecidos.

Os pacotes podem aparecer nas configurações globais e do projeto. Se o mesmo pacote aparecer em ambos, a entrada do projeto vence, a menos que a entrada do projeto tenha autoload: false, caso em que é aplicado como um delta sobre a entrada global. A identidade é determinada por:

• npm: nome do pacote
• git: URL do repositório sem ref
• local: caminho absoluto resolvido