Pi Packages

pi có thể giúp bạn tạo các gói pi. Yêu cầu nó đóng gói các tiện ích mở rộng, kỹ năng, prompt templates hoặc chủ đề của bạn.

Pi gói các tiện ích mở rộng, kỹ năng, prompt templates và chủ đề để bạn có thể chia sẻ chúng thông qua npm hoặc git. Một gói có thể khai báo tài nguyên trong package.json dưới khóa pi hoặc sử dụng các thư mục thông thường.

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

Bảo mật: Pi gói chạy với quyền truy cập toàn bộ hệ thống. Extensions thực thi mã tùy ý và các kỹ năng có thể hướng dẫn mô hình thực hiện bất kỳ hành động nào bao gồm cả việc chạy các tệp thực thi. Xem lại mã nguồn trước khi cài đặt các gói của bên thứ ba.

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

Các lệnh này quản lý các gói pi và pi update có thể cập nhật cài đặt pi CLI. Để gỡ cài đặt pi, hãy xem Quickstart.

Theo mặc định, install và remove ghi vào cài đặt người dùng (~/.pi/agent/settings.json). Thay vào đó, hãy sử dụng -l để ghi vào cài đặt dự án (.pi/settings.json). Cài đặt dự án có thể được chia sẻ với nhóm của bạn và pi sẽ tự động cài đặt mọi gói bị thiếu khi khởi động sau khi dự án được tin cậy.

Để thử một gói mà không cần cài đặt, hãy sử dụng --extension hoặc -e. Điều này chỉ cài đặt vào một thư mục tạm thời cho lần chạy hiện tại:

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

Pi chấp nhận ba loại nguồn trong cài đặt và pi install.

npm:@scope/pkg@1.2.3
npm:pkg

• Thông số kỹ thuật được phiên bản được ghim và bỏ qua bởi các bản cập nhật gói (pi update --extensions, pi update --all).
• Số lượt cài đặt của người dùng đạt dưới ~/.pi/agent/npm/.
• Số lượt cài đặt dự án đạt dưới .pi/npm/.
• Đặt npmCommand trong settings.json để ghim các thao tác tra cứu và cài đặt gói npm vào một lệnh trình bao bọc cụ thể, chẳng hạn như mise hoặc asdf.

Ví dụ:

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

• Nếu không có tiền tố git:, chỉ các URL giao thức mới được chấp nhận (https://, http://, ssh://, git://).
• Với tiền tố git:, các định dạng tốc ký được chấp nhận, bao gồm github.com/user/repo và git@github.com:user/repo.
• URL HTTPS và SSH đều được hỗ trợ.
• SSH URL tự động sử dụng các khóa SSH đã định cấu hình của bạn (tôn trọng ~/.ssh/config).
• Đối với các lần chạy không tương tác (ví dụ: CI), bạn có thể đặt GIT_TERMINAL_PROMPT=0 để tắt lời nhắc thông tin xác thực và đặt GIT_SSH_COMMAND (ví dụ: ssh -o BatchMode=yes -o ConnectTimeout=5) để không thành công nhanh.
• Tham chiếu là thẻ được ghim hoặc cam kết. pi update --extensions và pi update --all không chuyển chúng sang các ref mới hơn, nhưng chúng điều chỉnh một bản sao hiện có với ref đã định cấu hình.
• Sử dụng pi install git:host/user/repo@new-ref để cập nhật cài đặt và di chuyển gói hiện có sang một tham chiếu được ghim mới.
• Được nhân bản thành ~/.pi/agent/git/<host>/<path> (toàn cầu) hoặc .pi/git/<host>/<path> (dự án).
• Khi đối chiếu thay đổi thanh toán, pi đặt lại và xóa bản sao, sau đó chạy npm install nếu package.json tồn tại.

SSH ví dụ:

# 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

Đường dẫn cục bộ trỏ đến tệp hoặc thư mục trên đĩa và được thêm vào cài đặt mà không cần sao chép. Các đường dẫn tương đối được giải quyết dựa trên tệp cài đặt mà chúng xuất hiện. Nếu đường dẫn là một tệp, nó sẽ tải dưới dạng một phần mở rộng duy nhất. Nếu là một thư mục, pi sẽ tải tài nguyên bằng các quy tắc gói.

Thêm tệp kê khai pi vào package.json hoặc sử dụng các thư mục thông thường. Bao gồm từ khóa pi-package để có thể khám phá.

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

Đường dẫn có liên quan đến gói gốc. Mảng hỗ trợ các mẫu hình cầu và !exclusions.

package gallery hiển thị các gói được gắn thẻ pi-package. Thêm các trường video hoặc image để hiển thị bản xem trước:

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

• video: Chỉ MP4. Trên máy tính để bàn, tự động phát khi di chuột. Nhấp vào sẽ mở trình phát toàn màn hình.
• hình ảnh: PNG, JPEG, GIF hoặc WebP. Được hiển thị dưới dạng bản xem trước tĩnh.

Nếu cả hai được đặt, video sẽ được ưu tiên.

Nếu không có tệp kê khai pi, pi sẽ tự động khám phá tài nguyên từ các thư mục này:

• extensions/ tải tệp .ts và .js
• skills/ tìm đệ quy các thư mục SKILL.md và tải các tệp .md cấp cao nhất dưới dạng kỹ năng
• prompts/ tải .md tệp
• themes/ tải .json tệp

Các phần phụ thuộc thời gian chạy của bên thứ ba thuộc về dependencies trong package.json. Các phần phụ thuộc không đăng ký tiện ích mở rộng, kỹ năng, prompt templates hoặc chủ đề cũng thuộc về dependencies. Khi pi cài đặt một gói từ npm hoặc git, nó sẽ chạy npm install, vì vậy những phần phụ thuộc đó sẽ được cài đặt tự động.

Pi gói các gói cốt lõi dành cho tiện ích mở rộng và kỹ năng. Nếu bạn nhập bất kỳ thứ nào trong số này, hãy liệt kê chúng trong peerDependencies với phạm vi "*" và không gộp chúng: @earendil-works/pi-ai, @earendil-works/pi-agent-core, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox.

Các gói pi khác phải được gói trong tarball của bạn. Thêm chúng vào dependencies và bundledDependencies, sau đó tham chiếu tài nguyên của chúng thông qua đường dẫn node_modules/. Pi tải các gói có gốc mô-đun riêng biệt, do đó các bản cài đặt riêng biệt không xung đột hoặc chia sẻ các mô-đun.

Ví dụ:

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

Lọc nội dung gói sẽ tải bằng cách sử dụng biểu mẫu đối tượng trong cài đặt:

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

+path và -path là các đường dẫn chính xác liên quan đến thư mục gốc của gói.

• Bỏ qua một phím để tải tất cả các loại đó.
• Sử dụng [] để không tải loại nào.
• !pattern không bao gồm kết quả trùng khớp.
• +path lực-bao gồm một đường dẫn chính xác.
• -path lực-loại trừ một đường dẫn chính xác.
• Lớp bộ lọc ở trên cùng của tệp kê khai. Họ thu hẹp những gì đã được cho phép.

Sử dụng pi config để bật hoặc tắt các tiện ích mở rộng, kỹ năng, prompt templates và chủ đề từ các gói đã cài đặt và thư mục cục bộ. pi config bắt đầu trong cài đặt chung (~/.pi/agent/settings.json); nhấn Tab để chuyển giữa chế độ toàn cầu và dự án cục bộ. Sử dụng pi config -l để bắt đầu ghi đè dự án (.pi/settings.json) với tài nguyên toàn cầu được kế thừa bị làm mờ.

Các gói có thể xuất hiện trong cả cài đặt chung và dự án. Nếu cùng một gói xuất hiện trong cả hai, thì mục nhập dự án sẽ thắng trừ khi mục nhập dự án có autoload: false, trong trường hợp đó, mục nhập đó được áp dụng dưới dạng delta trên mục nhập chung. Danh tính được xác định bởi:

• npm: tên gói
• git: URL kho lưu trữ không có ref
• local: đường dẫn tuyệt đối đã được giải quyết