【免费下载链接】portal-ai-plugins
portal-ai-plugins 是 Spotify 官方的 AI 插件，把 Spotify Portal 的软件目录搜索、服务简报、Fleetshift 批量变更等工作流带入 Claude Code、Codex、Cursor、pi 等 AI 编程工具。但新手第一次使用 portal-ai-plugins 时，最常遇到"命令不出现""认证卡住""动作不敢跑"这类问题。本文按踩坑顺序整理了 8 个高频坑，每个都直接给出解决办法，帮你快速上手。
开始之前：先理解插件的两层结构
很多新手问题其实出在没分清插件和 CLI 的边界：
| 层次 | 是什么 | 谁负责 |
|---|---|---|
| portal 插件（skills） | 教 AI 何时、如何调用命令的工作流 | 本仓库 skills/ 目录 |
Portal CLI（@spotify/portal-cli） | 真正干活的上游命令行工具，通过 npx @spotify/portal-cli 调用 | npm 包，首次运行自动拉取 |
| shunt 插件（可选） | 把大文件读取等 I/O 重活转交给 AiKA 模式以省 token | plugins/shunt/README.md |
安装方式见根目录 README.md：Claude Code 用 claude plugin install portal@portal，Codex、Cursor、pi 各有对应入口。装完后开一个新会话再开始，这一点直接决定了第一个坑会不会踩到。
坑 1：装完插件却找不到 /portal:setup 命令
现象：安装成功，但会话里输入 /portal:setup 没有反应，或者看到的命令描述还是旧版本。
原因：AI 工具的插件命令需要新会话才会加载；Claude Code 中 skill 统一挂在 /portal: 命名空间下，旧会话不会热更新。
正确做法：
- 安装后开新会话再运行
/portal:setup（pi 上是/skill:setup） - 命令"看起来装好了但行为过期"时，Claude Code 里执行
/reload-plugins，或当前宿主里重开任务 - 用
claude plugin list --json确认portal已安装并启用
细节参考 skills/setup/SKILL.md。
坑 2：Portal CLI 没装好或版本过旧
现象：setup 走到一半报错，或者执行 npx @spotify/portal-cli --help 后看不到 auth、actions、owner、search、service 这几个子命令。
原因：这些工作流依赖 CLI 的五个核心命令，版本太旧时会缺失。插件本身不会帮你升级 CLI。
正确做法：
npx @spotify/portal-cli --help
npx @spotify/portal-cli auth --help
如果输出里缺命令，说明需要更新 Portal CLI 的已发布版本。另外注意：在 Portal 源码仓库内部运行时，npx 解析的是工作区本地构建；在别处运行则拉取 npm 上的正式包——两边版本可能不同，排障时先确认自己用的是哪份。
坑 3：认证（auth）卡住：多个实例、浏览器登录、token 安全
这是新手踩坑率最高的一节，官方在 skills/setup/SKILL.md 里写了四条铁律：
- 永远不要让用户把 token、授权码粘贴进聊天框——认证走
auth login，它可能打开浏览器，请在浏览器里完成登录；无浏览器环境用 login 自带的 no-browser 流程。 - 多个实例时不要猜默认值。先跑
npx @spotify/portal-cli auth list：- 只有一个实例 → 和用户确认后再继续
- 多个实例 → 逐个列出来让用户选，之后每次调用都带上
--instance <名称>
- 选定实例后必须
auth select+auth show验证通过，再往下走。 - 最后用
npx @spotify/portal-cli actions list --json做"认证 + 连通性 + 权限"三合一验证，成功才代表 Portal 真正就绪。
避坑口诀：list → login → select → show → actions list，五步走通才算认证完成。
坑 4：跳过 doctor 体检，出问题后反复排查
很多新手装完就直接开干，出了问题再东拼西凑排查。而 portal 插件自带一个只读的 doctor 工作流（见 skills/doctor/SKILL.md），会一次性检查四项：
| 检查项 | 说明 |
|---|---|
| 插件 | 是否安装、版本是否过期、是否需要 reload |
| CLI | Node/npm 运行时与五个核心命令是否齐全 |
| 认证 | 实例名与 backend URL，多实例时提示歧义而不是替你选 |
| Actions | actions list --json 是否可读 |
它不安装、不认证、不改任何状态，随时可安全运行。遇到"setup 失败 / 命令缺失 / 认证说不清"时，先跑一遍 doctor，看它给的表格定位是哪一项 blocked。
坑 5：搜索无结果，或担心 AI"编"出服务
现象：用 skills/search/SKILL.md 搜索软件目录，第一次没结果；或者结果稀疏时担心 AI 会"脑补"出不存在的服务和文档。
正确做法（工作流内置的保护规则）：
- 初始查询直接用你的原话，
--limit 10 --json控制结果量 - 只有明确只查目录或只查文档时才加
--type software-catalog/--type techdocs - 首次搜索为空时，换更宽的词重试一次，而不是直接下结论"没有"
- 官方规则明确写着：结果稀疏时不得编造服务和文档，只给你看真实结果的短列表
坑 6：跑 mutation 动作没走确认流程
actions 工作流（skills/actions/SKILL.md）里，"写操作"和"读操作"的安全规则完全不同：
- 读操作：直接加
--json，只传文档里有的参数 - 写操作：固定四步——查 help →
--dry-run --json预览精确输入 → 把要改什么展示给你 → 你明确授权后才真正执行 --yes是危险信号：它只用于标记为破坏性的动作（如stop-jobs、close-prs、delete-shift）。AI 不应该主动帮你加--yes- 特别注意：dry-run 成功 ≠ 执行成功，别把预览结果当成交付结果
坑 7：Fleetshift 工作流的 5 个高频陷阱
Fleetshift 是 portal 插件里最"重"的能力：创建 shift（可复用的 agent 变更定义）→ 触发运行 → 查看进度 → 开 PR。新手在 skills/fleetshift-create-shift/SKILL.md、skills/fleetshift-run-shift/SKILL.md 等文档里能看到大量护栏，对应 5 个常见陷阱：
陷阱 1：以为说一句"好"就创建了 shift。 create-shift 是 mutating 动作，AI 必须先 dry-run 校验 payload，再把 shift 名称、prompt、目标范围、PR 元数据一次性摆出来，等你给出明确的 "yes" 才执行。超过 10 个目标时还要单独确认大范围。
陷阱 2：重跑已完成的目标，旧结果被覆盖。 每个 target 只保留最新一次运行结果。重跑一个 jobComplete 的目标后，如果新运行失败，之前的成果将无法再开 PR——重跑前先让 AI 提醒你这一点。
陷阱 3：日志过期了还找原因。 Fleetshift 的 job 日志只保留 30 天。超过 30 天的失败任务，get-job-logs 会返回 "No archived logs available"，此时正确做法是重跑相关目标以获取新日志，而不是猜原因。
陷阱 4：以为 AI 会无限等待运行结束。 监控是有界的：最多 10 次轮询、每次间隔不少于 30 秒、总时长上限 15 分钟。到点仍在跑的任务，AI 会给你每个 job 的 portalJobUrl 让你自己继续看，不会傻等。
陷阱 5：想停就停，停不掉再慌。 运行中任何时候说 "stop"，AI 会立即执行 kill switch：停止继续触发 → 停止轮询 → 对未终态的 job 调 stop-jobs（这是唯一允许用 --yes 的地方）。如果某些 job 报 rejected，AI 会给你 Fleetshift UI 的入口手动停。注意：停止运行不会删 shift，也不会关已开的 PR，这两步是独立的破坏性操作。
查询和排障侧则很安全：fleetshift-check-shift 和 fleetshift-troubleshoot-shift 都是纯只读、幂等的，几天几周后再查也完全没问题。
坑 8：shunt 插件的前置条件没凑齐
plugins/shunt/ 是一个可选插件（目前仅支持 Claude Code），把大文件读取和样板代码生成转交给更便宜的 AiKA worker 模型，官方基准平均省约 90% token。新手装它时最常见的三个问题：
- 少了 jq：脚本依赖
jq解析输出，先brew install jq（或对应包管理器） - 没先装 portal 插件：shunt 的委托通过 Portal CLI 的 actions 注册表走，必须先装好 portal 并完成
/portal:setup认证 - AiKA 模式不存在：用
actions aika:list-modes查一下bulk-reader和code-writer两个模式是否已在你的实例上（很多实例默认公开提供）；没有就按 plugins/shunt/README.md 里的示例自建
另外记住它的设计边界：调试、精确编辑、小于 350 行的小文件不会（也不应该）被转交——hook 默认阈值 SHUNT_MIN_LINES=350 就是为此设置的。请求超大会收到明确的 payload 超限报错，此时拆分小批量即可，属于预期行为而非故障。
新手避坑清单（建议收藏）
- ✅ 装完插件开新会话，命令挂在
/portal:命名空间下 - ✅ setup 先验证 CLI 的
auth/actions/owner/search/service五个命令 - ✅ 认证走浏览器登录，token 永不进聊天框；多实例必须手动选
- ✅ 出问题先跑
doctor只读体检，按表格定位 - ✅ 写操作先
--dry-run --json，--yes只出现在你明确授权的破坏性场景 - ✅ Fleetshift：明确确认才创建/触发/开 PR；日志 30 天过期；监控 15 分钟封顶
- ✅ shunt：Claude Code only，先装 jq + portal 插件，再确认 AiKA 模式
更多工作流细节可以对照各 skill 的完整说明：skills/fleetshift-check-shift/SKILL.md、skills/fleetshift-troubleshoot-shift/SKILL.md、skills/service/SKILL.md，以及项目结构与设计约定 AGENTS.md。照着这份清单走，第一次使用 portal-ai-plugins 基本就不会再踩坑了。
【免费下载链接】portal-ai-plugins
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
