企业官网建设流程全解析

• AI 插件
• AI 技能
• 开发工具
• 开发者门户
• 工作流自动化

还在猜测 Spotify Portal 到底能帮你干什么吗？开源项目portal-ai-plugins把 Spotify Portal 接入了 Claude Code、Codex、Cursor 和 pi，通过npx @spotify/portal-cli actions list一条命令即可列出你账号下所有可用动作，再配合--help逐个检视参数，新手也能 10 分钟摸清 Portal 的全部能力边界。本文就是一份「发现能力」的实用指南。

一、30秒认识 portal-ai-plugins

portal-ai-plugins 是一个插件市场（marketplace），核心是把 Portal CLI 包装成一组聚焦工作流，覆盖认证配置、软件目录搜索、服务简报、只读诊断与动作调用：

完整清单见 README.md。想知道「有哪些工作流」，直接看项目根的 AGENTS.md 中的 Repository structure 一节即可。

二、快速上手：三步装好插件

以 Claude Code 为例（Codex / Cursor / pi 的安装方式见 README）：

claude plugin marketplace add spotify/portal-ai-plugins claude plugin install portal@portal

新开一个会话，运行/portal:setup完成认证与实例选择。setup 流程会在继续前校验auth、actions、owner、search、service五个命令是否齐备，详见 skills/setup/SKILL.md。

💡 如果你还装了同市场的shunt插件（Claude Code 专属），它会把大文件读取、样板代码生成等 I/O 密集任务委托给 AiKA 模式，官方基准显示平均可节省 90% 的 token，原理见 plugins/shunt/README.md。

三、核心技巧 1：actions list一次列出所有可用动作

这是本文最重要的命令——只读、零风险，一条命令回答「Portal 能做什么」：

npx @spotify/portal-cli actions list --json

🔍 你会得到一份以 JSON 输出的动作清单，动作 ID 采用「命名空间:动作名」格式，例如：

• telemetry:submit-feedback—— 提交 CLI 反馈
• aika:list-modes/aika:create-mode—— AiKA 模式管理（shunt 插件的底层）
• fleetshift:list-shifts/fleetshift:get-shift—— Fleetshift 任务查询

这条命令还有隐藏用途：它同时是一次连通性测试。命令成功即证明 CLI 认证可用、能访问所选 Portal 实例、并能枚举你有权访问的动作。skills/doctor/SKILL.md 和 skills/setup/SKILL.md 都把它当作「认证就绪」的证据，而且刻意只列出、不调用，确保安全。

四、核心技巧 2：--help检视每个动作的参数

动作 ID 找到之后，别急着猜参数。项目规则明确要求：在使用任何 Portal CLI 或宿主命令、参数之前，先跑--help（见 setup 技能的 Critical rules 第 2 条）。

# 先看顶层命令面 npx @spotify/portal-cli --help npx @spotify/portal-cli auth --help # 再看具体动作的生成帮助（参数是服务端动态注册的） npx @spotify/portal-cli actions <action-id> --help

为什么必须每次检视？因为actions下的命令面取决于所选 Portal 实例注册了哪些动作，不同实例、不同版本暴露的参数可能不同。skills/service/SKILL.md 甚至特意提醒先跑npx @spotify/portal-cli service --help，原因就是 service 子工作流依赖实例侧注册的动作。

五、安全调用：--dry-run+--json防护三件套

发现动作只是第一步，「安全地用起来」才是关键。skills/actions/SKILL.md 定义了标准安全流程：

1. 检视生成帮助—— 跑--help，确认参数含义；
2. 干跑预览—— 用--dry-run --json预览将要提交的精确输入；
3. 向用户展示变更内容；
4. 获得授权后再真正执行；
5. 仅当动作被标记为破坏性且用户明确授权时，才追加--yes。

npx @spotify/portal-cli actions <action-id> --input '<json>' --dry-run --json

⚠️ 特别提醒：干跑成功 ≠ 执行成功，不要从 dry-run 推断真实执行结果。破坏性动作（如 Fleetshift 的stop-jobs、delete-shift）需要--yes，普通--yes切勿随手传参。

六、不会检视怎么办？让doctor帮你一键自检

如果环境状态不明（装没装、认证对不对、动作面全不全），直接运行doctor工作流。它是一条纯只读健康检查流水线：

它会输出一张「Ready / warning / blocked」诊断表，有任一项被阻塞就不谎报整体就绪——这对排障尤其友好。完整规则见 skills/doctor/SKILL.md。

七、延伸阅读：项目文件路径速查

八、小结

发现 Portal 能力只需两步：actions list --json列出全部动作，--help逐个检视参数；配合--dry-run --json预览与doctor只读诊断，你既看得清能力边界，又能安全地把动作真正用起来。把这两条命令记下来，Portal 就不再是一个黑盒。🚀

• AI 插件
• AI 技能
• 开发工具
• 开发者门户
• 工作流自动化