portal-ai-plugins: đưa Spotify Portal vào AI code — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về spotify/portal-ai-plugins — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: portal-ai-plugins: đưa Spotify Portal vào Claude Code, Codex, Cursor — cài và dùng →

Tóm tắt nhanh
portal-ai-plugins là bộ plugin mã nguồn mở của Spotify, đưa Spotify Portal vào các trợ lý lập trình AI như Claude Code, Codex, Cursor và pi. Nó dùng Portal CLI để tìm trong catalog phần mềm, tóm tắt dịch vụ và gọi các action của Portal. Cài đặt chỉ vài lệnh, nhưng bạn cần có sẵn quyền truy cập Spotify Portal của tổ chức mình.
portal-ai-plugins là bộ plugin của Spotify, giúp trợ lý lập trình AI (Claude Code, Codex, Cursor, pi) làm việc được với Spotify Portal. Bên dưới, plugin gọi công cụ dòng lệnh Portal CLI để thực hiện các việc như đăng nhập, tìm kiếm trong catalog phần mềm, tóm tắt một dịch vụ hay chạy các action của Portal.
Nói đơn giản: thay vì mở trang Portal, tự tìm xem dịch vụ nào do đội nào quản lý, tài liệu nằm đâu, rồi quay lại cửa sổ code, bạn hỏi thẳng trợ lý AI bằng tiếng thường. Trợ lý sẽ dùng các quy trình (workflow) có sẵn trong plugin để đi lấy thông tin về cho bạn.
Repo hợp với người đã có Spotify Portal trong tổ chức và đang dùng một trong bốn trợ lý AI nói trên. Điểm đáng giá nhất là các thao tác có tác dụng thật (gọi action, mở PR) đều có lớp bảo vệ: xem trước, chạy thử (dry-run) và hỏi xác nhận. Hiện repo có khoảng 3216 sao và 254 fork, giấy phép Apache-2.0, viết chủ yếu bằng TypeScript và vẫn được cập nhật trong 3 tháng gần đây.
spotify/portal-ai-plugins
Plugin của Spotify đưa Portal vào Claude Code, Codex, Cursor và pi: tra catalog phần mềm, tóm tắt dịch vụ, chạy chẩn đoán và gọi action an toàn.
I.portal-ai-plugins làm được gì
Plugin chia thành các workflow nhỏ, mỗi workflow lo một việc. Bạn không cần nhớ hết, vì trợ lý sẽ chọn workflow phù hợp khi bạn nói điều mình cần.
A.Thiết lập và kiểm tra
- setupcấu hình đăng nhập cho Portal CLI trong môi trường trợ lý bạn đang dùng. Đây là việc đầu tiên phải làm.
- doctorchạy chẩn đoán chỉ-đọc để kiểm tra plugin, CLI, đăng nhập và khả năng gọi action đã sẵn sàng chưa. Vì chỉ đọc nên chạy bao nhiêu lần cũng không làm thay đổi gì.
B.Tra cứu
- searchtìm trong catalog phần mềm và tài liệu kỹ thuật bằng câu hỏi tự nhiên. Bạn không phải nhớ đúng tên dịch vụ hay từ khoá.
- servicetạo bản tóm tắt vận hành ngắn gọn cho một dịch vụ, gồm những gì có sẵn về chủ sở hữu, tình trạng, sự cố và tài liệu. Rất tiện khi bạn mới nhận một dịch vụ lạ.
C.Gọi action
- actionstìm, xem chi tiết, xem trước và gọi các action của Portal. Có sẵn trợ giúp, chạy thử và bước xác nhận, nên bạn ít lo bấm nhầm.
- feedbackgửi góp ý về Portal CLI cho đội Portal.
D.Fleetshift
Nhóm workflow này lo việc tạo và theo dõi các «shift» của Fleetshift:
- fleetshift-create-shiftsoạn và tạo shift từ một mục tiêu, có xem trước bằng dry-run.
- fleetshift-run-shiftkích hoạt shift, theo dõi với thời gian chờ có giới hạn, và dừng khi bạn yêu cầu.
- fleetshift-check-shiftbáo tiến độ, các đích (target) và PR của shift (chỉ đọc).
- fleetshift-troubleshoot-shiftchẩn đoán job bị lỗi từ trạng thái và log (chỉ đọc).
- fleetshift-create-prsmở PR cho các đích đã hoàn thành, sau khi bạn xác nhận.
E.Plugin shunt (tuỳ chọn)
Marketplace còn kèm plugin shunt, hiện chỉ dành cho Claude Code. Nó đẩy các việc nặng về đọc/ghi, như đọc hàng loạt file hay sinh code mẫu, sang các chế độ AiKA chạy mô hình rẻ hơn, thông qua danh sách action của Portal CLI. Mục đích là tiết kiệm token. Chi tiết nằm trong file plugins/shunt/README.md của repo.
II.Cần chuẩn bị gì
Tư liệu README nói khá ngắn gọn, nên mình chỉ liệt kê những gì có căn cứ:
- Một trong bốn công cụ: Claude Code, Codex, Cursor hoặc pi. Riêng plugin shunt hiện chỉ có cho Claude Code.
- Công cụ Portal CLI. Các workflow gọi nó qua lệnh
npx @spotify/portal-cli <command>, nghĩa là máy bạn cần cónpx(đi kèm Node.js). README không ghi phiên bản Node tối thiểu. - Quyền truy cập Spotify Portal của tổ chức bạn, vì bước setup sẽ cấu hình đăng nhập. README không mô tả chi tiết loại tài khoản hay cách cấp quyền, nên nếu chưa có, hãy hỏi người quản trị Portal ở chỗ bạn.
- Với Cursor: README nói bạn đăng ký repo vào marketplace của team Cursor, nên có thể cần quyền quản trị phần này.
README không nói gì về hệ điều hành hay phần cứng (GPU, RAM). Vì đây là plugin chạy qua dòng lệnh, bạn nên xem file package.json và các file AGENTS.md, CLAUDE.md trong repo nếu cần thêm thông tin.
III.Cài đặt từng bước
- Chọn công cụXác định bạn dùng Claude Code, Codex, Cursor hay pi
- Thêm marketplaceĐăng ký repo spotify/portal-ai-plugins với công cụ đó
- Cài pluginCài plugin Spotify Portal (portal) từ marketplace
- Mở phiên mớiBắt đầu một session hoặc task mới để plugin được nạp
- Chạy setupGọi workflow setup để cấu hình đăng nhập Portal CLI
Cách cài khác nhau theo từng công cụ. Bạn chỉ cần làm theo phần của công cụ mình đang dùng.
A.Cài cho Claude Code
Mở terminal (PowerShell, Terminal hay cửa sổ dòng lệnh bất kỳ), rồi chạy lần lượt:
claude plugin marketplace add spotify/portal-ai-plugins
claude plugin install portal@portal
claude plugin install shunt@portal # optional: token-saving AiKA delegationLệnh đầu thêm «chợ plugin» của Spotify vào Claude Code. Lệnh thứ hai cài plugin chính portal. Lệnh thứ ba cài thêm plugin shunt, không bắt buộc. Nếu chưa cần tiết kiệm token, bạn có thể bỏ qua dòng này. Phần sau dấu # chỉ là ghi chú.
Sau đó bắt đầu một session mới của Claude Code (chỗ này người mới hay quên, nên plugin không thấy) và gõ:
/portal:setupB.Cài cho Codex
codex plugin marketplace add spotify/portal-ai-plugins
codexLệnh đầu thêm marketplace, lệnh sau mở Codex. Trong Codex, mở /plugins, cài Spotify Portal, rồi bắt đầu một task mới và nhờ:
Set up Spotify Portal for me.C.Cài cho Cursor
README không đưa lệnh cho Cursor. Cách làm là đăng ký repo spotify/portal-ai-plugins vào marketplace của team Cursor, rồi vào Cursor Settings → Plugins và cài Spotify Portal. Nếu bạn không phải quản trị viên team, có thể cần nhờ người có quyền làm bước đăng ký.
D.Cài cho pi
pi install git:github.com/spotify/portal-ai-pluginsMột lệnh duy nhất, cài thẳng từ GitHub. Sau đó mở session mới và gõ:
/skill:setupE.Lưu ý về Portal CLI
Các workflow gọi Portal CLI qua lệnh sau. Bạn thường không cần tự gõ, vì trợ lý sẽ gọi giúp:
npx @spotify/portal-cli <command>Theo README, bước setup sẽ kiểm tra các lệnh auth, actions, owner, search và service có sẵn trước khi đi tiếp.
Bước setup liên quan đến đăng nhập vào Portal. Hãy làm đúng hướng dẫn hiện ra trên màn hình, và không dán token hay mật khẩu vào khung chat nếu không được yêu cầu rõ ràng.
IV.Kiểm tra đã chạy được chưa
Cách chắc nhất là dùng chính workflow doctor. Nó chạy chẩn đoán chỉ-đọc để xác nhận plugin, CLI, đăng nhập và khả năng gọi action đều sẵn sàng.
Trong Claude Code, bạn gọi theo cùng kiểu với setup (/portal: rồi tên workflow), hoặc đơn giản là nhờ bằng lời. Trong pi, kiểu gọi là /skill: rồi tên workflow. Ví dụ câu nhờ:
Chạy doctor để kiểm tra Spotify Portal đã sẵn sàng chưa.Nếu mọi mục báo ổn thì bạn đã xong. Nếu có mục nào lỗi, doctor sẽ cho biết thiếu ở khâu nào (plugin, CLI, đăng nhập hay action). README không mô tả chính xác giao diện kết quả, nên mình không khẳng định màn hình sẽ trông thế nào.
V.Dùng vào việc thật
Các tình huống dưới đây dựa trên những workflow có trong README. Câu lệnh mẫu mình viết là gợi ý để bạn nhờ trợ lý, không phải cú pháp cố định.
A.Dev mới vào đội, cần hiểu một dịch vụ lạ
Bạn vừa được giao sửa lỗi ở một dịch vụ mà mình chưa từng đụng tới. Thay vì hỏi từng người, bạn nhờ workflow service:
Tóm tắt cho mình dịch vụ <tên dịch vụ>: ai sở hữu, tình trạng, sự cố gần đây và tài liệu liên quan.Kết quả là một bản briefing ngắn với những thông tin Portal có sẵn: chủ sở hữu, sức khoẻ, sự cố, tài liệu. Nhờ vậy bạn biết nên hỏi ai và đọc gì trước. Nếu Portal chưa có mục nào đó, bản tóm tắt sẽ không có mục đó.
Hỏi trợ lý một câu bằng tiếng thường, thay vì lục ba tab Portal.
Ông T
B.Tìm tài liệu kỹ thuật mà không nhớ tên
Bạn nhớ mang máng có tài liệu về cách cấp quyền cho một dịch vụ nhưng quên mất nó nằm đâu. Dùng workflow search:
Tìm trong catalog và tài liệu kỹ thuật: hướng dẫn cấp quyền truy cập cho dịch vụ thanh toán.Search hỗ trợ truy vấn bằng ngôn ngữ tự nhiên, tìm cả trong catalog phần mềm lẫn tài liệu kỹ thuật. Bạn nhận về danh sách kết quả liên quan để mở đọc tiếp.
C.Gọi một action của Portal nhưng muốn chắc ăn
Đội bạn có một action trong Portal (ví dụ tạo một tài nguyên mới) và bạn muốn dùng thử. Workflow actions cho phép khám phá, xem chi tiết, xem trước rồi mới gọi:
Liệt kê các action Portal đang có, giải thích action <tên action> cần những tham số nào, rồi chạy thử (dry-run) trước khi gọi thật.Vì có trợ giúp, dry-run và bước xác nhận, bạn nhìn thấy trước điều sẽ xảy ra và chỉ đồng ý khi thấy đúng. Với người mới, đây là cách an toàn hơn nhiều so với tự ghép lệnh.
D.Chạy một thay đổi hàng loạt bằng Fleetshift
Nếu tổ chức bạn dùng Fleetshift để đổi code trên nhiều repo, workflow Fleetshift đi theo trình tự: tạo shift, chạy, kiểm tra, xử lý lỗi, mở PR.
Tạo một shift từ mục tiêu: <mô tả thay đổi>. Cho mình xem bản dry-run trước.Sau khi duyệt bản xem trước, bạn nhờ chạy shift (có thời gian chờ giới hạn, và bạn có thể yêu cầu dừng). Khi cần, dùng bước kiểm tra để xem tiến độ, đích và PR. Nếu có job lỗi, bước troubleshoot đọc trạng thái và log để chẩn đoán. Cuối cùng, fleetshift-create-prs chỉ mở PR cho các đích đã hoàn thành sau khi bạn xác nhận.
VI.Lỗi hay gặp và cách xử lý
README không có mục xử lý lỗi, nên các mục dưới đây là những tình huống rất dễ gặp với loại công cụ này.
A.Gõ lệnh nhưng trợ lý không nhận ra plugin
Thường do bạn chưa mở session hoặc task mới sau khi cài. README nhắc rõ phải bắt đầu session mới. Hãy thoát và mở lại, rồi thử /portal:setup (Claude Code) hay /skill:setup (pi). Với Codex, hãy kiểm tra trong /plugins xem Spotify Portal đã được cài chưa.
B.Lệnh claude, codex hoặc pi báo không tìm thấy
Nghĩa là công cụ đó chưa được cài hoặc chưa nằm trong PATH của terminal. Hãy cài công cụ trước theo hướng dẫn chính thức của nó, mở lại terminal, rồi chạy lại lệnh cài plugin.
C.npx không chạy được
Các workflow gọi npx @spotify/portal-cli, nên nếu máy chưa có Node.js (đi kèm npx) hoặc mạng chặn việc tải gói thì sẽ lỗi. Kiểm tra bằng cách gõ npx --version trong terminal. Nếu chưa có, hãy cài Node.js trước.
D.Đăng nhập Portal không thành công
Có thể tài khoản của bạn chưa được cấp quyền, hoặc phiên đăng nhập hết hạn. Chạy lại workflow setup, rồi doctor để biết lỗi nằm ở khâu đăng nhập hay ở khâu khác. Nếu vẫn không được, hãy hỏi người quản trị Portal ở tổ chức của bạn thay vì thử nhiều cách khác nhau.
E.Gọi action hoặc mở PR mà không chắc kết quả
Đừng bỏ qua bước xem trước. Luôn yêu cầu dry-run trước, đọc kỹ rồi mới xác nhận. Nếu đang chạy một shift mà thấy không ổn, hãy nhờ trợ lý dừng lại ngay.
VII.Có nên dùng không
Điểm mạnh:
- Gom nhiều việc hay làm trên Portal (tìm kiếm, tóm tắt dịch vụ, gọi action, Fleetshift) vào ngay công cụ lập trình bạn đang mở.
- Các thao tác thay đổi thật đều có xem trước và xác nhận. Các workflow chẩn đoán, kiểm tra tiến độ là chỉ-đọc.
- Hỗ trợ bốn công cụ phổ biến, giấy phép Apache-2.0, có người duy trì đều đặn.
Giới hạn:
- Repo chỉ có ích nếu tổ chức bạn đã có Spotify Portal. Nếu không, bạn chưa có gì để kết nối.
- README ngắn, không nói rõ phiên bản Node, hệ điều hành hay chi tiết đăng nhập. Bạn có thể phải tự dò hoặc hỏi quản trị viên.
- Plugin shunt hiện chỉ dành cho Claude Code.
- Kết quả phụ thuộc vào dữ liệu có trong Portal của bạn. Catalog thiếu thông tin thì bản tóm tắt cũng thiếu.
Nếu bạn không dùng Portal, hoặc chỉ cần hỏi đáp code thông thường, repo này không phải thứ bạn cần. Còn nếu tổ chức bạn đã dùng Portal và bạn thường xuyên phải nhảy qua lại giữa trình duyệt và trợ lý AI, thì đây là một cách cài nhanh, ít rủi ro để thử.
Câu hỏi thường gặp
portal-ai-plugins có miễn phí không?
Repo là mã nguồn mở theo giấy phép Apache-2.0 nên bạn tải và cài miễn phí. Tuy nhiên bạn cần có Spotify Portal của tổ chức và công cụ AI như Claude Code, Codex, Cursor hay pi. Tư liệu chưa nói về chi phí của các dịch vụ đó.
Plugin này chạy trên những công cụ nào?
README nêu Claude Code, Codex, Cursor và pi. Riêng plugin shunt hiện chỉ dành cho Claude Code. Mỗi công cụ có cách cài riêng, bạn xem phần cài đặt trong bài.
Có cần GPU không, chạy được trên Windows không?
README không nhắc đến GPU hay hệ điều hành cụ thể. Plugin chạy qua dòng lệnh và gọi Portal CLI bằng npx, nên bạn cần Node.js. Về Windows, tư liệu chưa có thông tin rõ ràng.
Cần tài khoản hay API key gì?
Bạn cần quyền truy cập Spotify Portal, vì bước setup sẽ cấu hình đăng nhập cho Portal CLI. README không ghi chi tiết cách cấp tài khoản hay API key, nên hãy hỏi người quản trị Portal ở chỗ bạn.
Plugin có tự ý thay đổi gì không?
Theo README, chẩn đoán và kiểm tra tiến độ là chỉ-đọc. Việc gọi action và mở PR có hướng dẫn, dry-run và bước xác nhận. Nhờ đó bạn thấy trước và đồng ý trước khi có thay đổi thật.
Plugin shunt dùng để làm gì?
Shunt chuyển các việc nặng về I/O, như đọc hàng loạt file và sinh code mẫu, sang các chế độ AiKA chạy mô hình rẻ hơn qua danh sách action của Portal CLI. Mục tiêu là tiết kiệm token. Hiện chỉ có cho Claude Code, chi tiết nằm trong plugins/shunt/README.md.
Làm sao biết đã cài thành công?
Chạy workflow doctor để kiểm tra plugin, CLI, đăng nhập và khả năng gọi action. README không mô tả chính xác giao diện kết quả. Nếu doctor báo lỗi, hãy chạy lại setup.


