Tài liệu ChatGPT
Tiếng Việt
Liên hệ goolvyouyou@gmail.com

Quản lý plugin

Nhập và đồng bộ plugin của không gian làm việc từ GitHub

Trước khi bắt đầu

Quản trị viên không gian làm việc có thể nhập một marketplace plugin từ GitHub và cập nhật các plugin trong đó từ kho lưu trữ. Marketplace là một danh mục JSON liệt kê các plugin cần nhập.

Trang này trình bày việc nhập và đồng bộ trong không gian làm việc. Để cấu hình các kho plugin trực tiếp trên ứng dụng khách cục bộ thông qua config.toml được quản lý qua đám mây hoặc ở cấp hệ thống, hãy xem Cấu hình kho plugin và các thiết lập mặc định. Để bật hoặc tắt plugin cho một dự án cụ thể, hãy xem Bật hoặc tắt plugin cho một kho mã.

Hãy sử dụng tài khoản GitHub có thể đọc kho lưu trữ marketplace và mọi kho lưu trữ khác được tham chiếu. Cả kho lưu trữ GitHub công khai và riêng tư đều được hỗ trợ. Hãy hoàn tất mọi phê duyệt của tổ chức GitHub cần thiết để truy cập kho lưu trữ trước khi nhập.

Xem xét nội dung kho lưu trữ trước khi nhập. Plugin mới bắt đầu với chính sách cài đặt Khả dụng và xác thực khi cài đặt. Marketplace mới được bật tính năng tự động đồng bộ hằng ngày. Quá trình nhập xử lý mọi mục hợp lệ và các lần đồng bộ sau này sẽ tự động thêm mọi plugin mới trong kho lưu trữ.

Cấu hình đồng bộ marketplace

  1. Mở Quản trị > Plugin rồi chọn Thêm > Nhập marketplace.
  2. Trong Nguồn, nhập URL của kho lưu trữ, chẳng hạn như https://github.com/example/team-plugins. Chỉ sử dụng URL kho lưu trữ, không dùng URL nhánh hoặc thư mục.
  3. Nếu marketplace nằm trong một thư mục con, hãy nhập thư mục đó vào Đường dẫn. Ví dụ: sử dụng team-tools cho team-tools/.agents/plugins/marketplace.json. Để trống Đường dẫn nếu marketplace nằm ở thư mục gốc của kho lưu trữ. Không nhập tên tệp manifest.
  4. Bạn có thể nhập Nhánh, thẻ hoặc commit. Để trống trường này để sử dụng nhánh mặc định của kho lưu trữ. Sử dụng một nhánh để nhận các commit trong tương lai; một commit cố định sẽ giữ nguyên ở bản sửa đổi đó.
  5. Chọn Nhập marketplace và ủy quyền truy cập GitHub khi được nhắc. Lần nhập đầu tiên có thể mất đến một giờ đối với marketplace rất lớn. Các lần đồng bộ hằng ngày sau đó thường mất vài phút.
  6. Xem lại Kết quả nhập, sau đó mở từng plugin đã nhập để cấu hình chính sách cài đặt và mọi ứng dụng bắt buộc.

Để yêu cầu cập nhật mà không cần chờ lần đồng bộ hằng ngày, hãy mở marketplace trong Quản trị > Plugin > Marketplace rồi chọn Đồng bộ ngay.

Định dạng được hỗ trợ

Thư mục đã chọn phải chứa một trong các tệp sau:

Tệp Định dạng
.agents/plugins/marketplace.json Marketplace Codex có một mảng plugins.
.claude-plugin/marketplace.json Marketplace tương thích với Claude có một mảng plugins.
.claude-plugin/plugin.json Plugin Claude độc lập khi không có manifest marketplace.

Trong marketplace, các mục có thể tham chiếu plugin gốc bằng .codex-plugin/plugin.json, plugin tương thích với Claude, gói Agent Plugins 1.0 hoặc gói kỹ năng được hỗ trợ.

Đối với marketplace Codex, hãy dùng đường dẫn cục bộ cho các plugin trong cùng kho lưu trữ:

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

Đường dẫn này tương đối so với thư mục gốc marketplace đã chọn, không phải so với .agents/plugins/.

Marketplace tương thích với Claude có thể sử dụng chuỗi đường dẫn cho từng plugin cục bộ:

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Các mục trong marketplace Codex cũng hỗ trợ source: "url" cho plugin ở thư mục gốc của kho lưu trữ GitHub và source: "git-subdir" cho plugin trong thư mục con của GitHub. Ví dụ:

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Nguồn Git có thể chọn một ref hoặc một commit sha đầy đủ gồm 40 ký tự. Tài khoản GitHub cấp quyền phải có khả năng đọc mọi kho lưu trữ được tham chiếu. Tính năng nhập vào không gian làm việc hiện chỉ hỗ trợ kho lưu trữ GitHub.

Cấu hình quyền truy cập của không gian làm việc

Quá trình nhập và đồng bộ GitHub không áp dụng các chính sách cài đặt hoặc xác thực của kho lưu trữ, bao gồm AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL và ON_USE. Quản trị viên không gian làm việc cấu hình các cài đặt này cho từng plugin. Việc đồng bộ một bản cập nhật hoặc chuyển một plugin hiện có sang chế độ quản lý bằng GitHub sẽ giữ nguyên các chính sách trong không gian làm việc của plugin đó.

Sử dụng Chính sách cài đặt để chọn Khả dụng hoặc Đã cài đặt cho từng vai trò đủ điều kiện. Các ứng dụng bắt buộc cũng phải được bật và thành viên phải có quyền truy cập dịch vụ được kết nối. Việc nhập plugin không cấp quyền truy cập ứng dụng hoặc kết nối tài khoản của thành viên. Hãy xem Biện pháp kiểm soát plugin để biết các biện pháp kiểm soát vai trò, ứng dụng và hành động.

Chuyển plugin hiện có sang chế độ quản lý bằng GitHub

Thêm pluginId vào mục marketplace của plugin hiện có:

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Mở plugin từ Quản trị > Plugin rồi sao chép ID nằm sau /admin/plugins/ trong URL của plugin. Đặt pluginId bên cạnh name và source trong mục marketplace. Plugin hiện có phải nằm trong cùng không gian làm việc.

Thao tác này chuyển một plugin đã tải lên hoặc plugin không được quản lý theo cách khác trong không gian làm việc sang chế độ quản lý bằng GitHub. Plugin giữ nguyên ID, chế độ chia sẻ và các chính sách trong không gian làm việc. Các bản cập nhật sau này sẽ đến từ GitHub; không thể dùng tệp lưu trữ tải lên để thay thế plugin được quản lý nữa. Không thể dùng cách này để tiếp quản một plugin đã được quản lý bởi một nguồn GitHub khác.

Plugin chỉ dành cho máy tính

Mọi plugin được nhập có khai báo MCP server trong mcp.json hoặc .mcp.json đều được đánh dấu Chỉ dành cho máy tính và chỉ hoạt động trong ứng dụng ChatGPT dành cho máy tính. Điều này bao gồm cả máy chủ sử dụng URL HTTPS từ xa. Hạn chế tương tự áp dụng cho các dạng cấu hình MCP được hỗ trợ khác, chẳng hạn như khai báo máy chủ nội tuyến.

Tham chiếu ứng dụng hiện có bằng .app.json

Thêm .app.json vào thư mục gốc của plugin. Tên tệp có dấu chấm ở đầu; app.json không có dấu chấm không được hỗ trợ.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Thay asdk_app_example bằng ID của ứng dụng hiện có. ID ứng dụng được hỗ trợ bắt đầu bằng asdk_app_, connector_ hoặc templated_apps_. Hãy dùng ID ứng dụng, không dùng ID plugin_.... Ví dụ: URL plugin chứa plugin_asdk_app_example đại diện cho ứng dụng asdk_app_example.

Khóa team-tools đặt tên cho tham chiếu trong tệp này. Đặt required thành true khi plugin phụ thuộc vào ứng dụng. Bạn có thể thêm nhiều mục hơn để tham chiếu các ứng dụng hiện có khác.

Đối với plugin gốc, hãy đặt apps thành ./.app.json trong .codex-plugin/plugin.json. Sau đây là manifest hoàn chỉnh cho ví dụ này:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Giữ các tệp theo bố cục sau:

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

Tham chiếu này không tạo ứng dụng hoặc cấp quyền. Quản trị viên phải cung cấp ứng dụng cho các vai trò dự kiến và thành viên phải hoàn tất mọi bước xác thực bắt buộc. Các quyền ứng dụng, biện pháp kiểm soát hành động và quyền truy cập dịch vụ hiện có vẫn được áp dụng.

Luôn cập nhật plugin

Marketplace mới kiểm tra bản cập nhật hằng ngày. Mở Quản trị > Plugin > Marketplace, chọn marketplace rồi chọn Đồng bộ ngay để yêu cầu cập nhật mà không cần chờ đồng bộ tự động.

Quá trình đồng bộ có thể thêm các mục marketplace mới và cập nhật plugin hiện có. Hãy xem xét các thay đổi trong kho lưu trữ trước khi hợp nhất vì tính năng đồng bộ tự động sẽ nhập mọi plugin mới.

Sau khi đồng bộ, hãy xem lại trạng thái và báo cáo đã lưu. Hoàn tất — N lỗi có nghĩa là lượt xử lý đã hoàn tất nhưng không thể xử lý một số plugin. Nếu bản cập nhật cho plugin hiện có không hợp lệ, phiên bản hoạt động gần nhất của plugin sẽ được giữ lại. Khắc phục vấn đề được báo cáo trong GitHub rồi chọn Đồng bộ ngay để thử lại.

Việc xóa một mục khỏi kho lưu trữ không xóa bản sao đã nhập của mục đó trong không gian làm việc. Mục này sẽ được đánh dấu Không còn trong nguồn. Việc xóa marketplace trong ChatGPT sẽ xóa mọi plugin được nhập từ marketplace đó.

Kết nối lại hoặc thay đổi quyền truy cập GitHub

Để kết nối lại quyền truy cập GitHub, trước tiên hãy xác nhận rằng tài khoản GitHub dùng để nhập vẫn có quyền truy cập kho lưu trữ và mọi kho lưu trữ được tham chiếu. Sau đó, quản trị viên ban đầu đã nhập marketplace phải mở plugin GitHub trong ChatGPT và kết nối lại tài khoản của họ vì quá trình đồng bộ marketplace sử dụng kết nối GitHub của quản trị viên đó.

Để chuyển cho chủ sở hữu mới, quản trị viên không gian làm việc mới cần mở Quản trị > Plugin > Thêm > Nhập marketplace rồi nhập cùng marketplace bằng các giá trị Nguồn, Đường dẫn và Nhánh, thẻ hoặc commit giống nhau. Các lần đồng bộ sau này sẽ sử dụng kết nối GitHub của họ.

Đừng xóa marketplace chỉ để kết nối lại hoặc thay đổi quyền sở hữu: thao tác xóa cũng loại bỏ các plugin đã được nhập từ marketplace đó.