企业官网建设流程全解析

如何让AI Agent安全执行高风险操作？portal-ai-plugins的actions五步dry-run防护机制完全指南

【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins

你是否担心AI Agent在"自由发挥"时误删数据、误改线上配置？portal-ai-plugins是一个为 Claude Code、Codex、Cursor 等 AI 编码助手提供 Spotify Portal 工作流的插件，其中actions技能内置了五步 dry-run 防护机制：AI 在真正执行任何高风险操作前，必须先检查帮助、预览输入、向你展示变更、等你明确授权，破坏性操作还需额外的--yes确认。本文将用通俗的方式带你完整理解这套安全设计，让 AI 干活既高效又"不敢乱来"。

为什么 AI Agent 需要"先预览再动手"？

想象你请一位新手助手操作生产系统，你敢让他不确认就直接敲下删除命令吗？

AI Agent 面临的处境类似：它能理解你的自然语言需求，也能自己拼出命令行，但它无法真正"感受"操作的后果。一个幻觉、一个参数写错，就可能导致不可逆的变更。

🛡️ 因此，安全的关键不是"禁止 AI 做事"，而是给它一套强制流程：每一步都有据可查、每一步都需要人确认。这就是 portal-ai-plugins 中 skills/actions/SKILL.md 所定义的防护机制。

先认识 portal-ai-plugins 插件包

这个插件仓库围绕 README.md 中定义的六条工作流组织：

可以看到，仓库在 AGENTS.md 中明确规定了两条设计红线：doctor必须保持只读、文档中必须保留 JSON 输出与 dry-run 防护措施。也就是说，"安全"不是事后补救，而是从插件层面写进规范的架构约束。

五步 dry-run 防护机制详解 🎯

当 Agent 需要执行一个**会修改数据的操作（mutation）**时，必须走完以下五步，一步都不能跳：

第一步：检查命令帮助，而不是凭记忆拼参数

Agent 在调用任何操作前，会先查看该操作自动生成的帮助信息（actions <action-id> --help）。

这一步的价值在于：参数以官方定义为准，杜绝 AI 凭"印象"编造不存在的标志位。

第二步：用--dry-run --json精确预览输入

这是整套机制的心脏。Agent 会把真实要提交的参数打包后，加上--dry-run --json运行：

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

--dry-run让操作只模拟、不落地；--json则让输出结构化，方便 Agent 准确读取"到底会发生什么"。相当于先打印一张"施工图纸"，而不是直接动锤子。

第三步：把将发生的变更展示给用户

Agent 不能只给自己看预览结果——它必须把即将变更的内容用人话讲清楚：改什么、影响什么、依据是什么。

这一步解决的是"信息不对称"：预览结果只有用户看懂了，授权才是有意义的授权。

第四步：仅在用户明确授权后才执行

🔑 没有你的"同意"，操作停在纸面。Agent 被要求等待明确授权，而不是把"没反对"当成"默认同意"。

第五步：破坏性操作追加--yes双重确认

如果该操作被标记为破坏性（destructive），即便你已经授权，Agent 也只有在再次确认后才追加--yes标志执行。

--yes在这里扮演的是"最后一道闸"：它把破坏性操作与普通操作在命令层面区隔开，日志与审计时一眼可见哪些是高危动作。

⚠️ 一个容易踩的坑：dry-run 成功 ≠ 执行成功

skills/actions/SKILL.md 的最后一句值得划重点：

Never infer successful execution from a dry run.（绝不能从 dry-run 推断执行成功。）

模拟通过只说明"参数格式没问题、路径可达"，不代表正式执行不会遇到权限、配额等运行时问题。新手最容易犯的错误，就是看到 dry-run 输出正常便向用户汇报"已经完成了"。正确的做法是：预览归预览，执行结果必须以真实执行后的输出为准。

配套安全设计：只读体检与最小凭证原则

五步防护并非孤立存在，它和另外两条安全规范互相咬合：

1.doctor只读体检

skills/doctor/SKILL.md 定义了一套四步健康检查：宿主插件是否就绪、CLI 命令面是否完整、认证实例是否明确、能否只读列举可用操作。整个过程禁止安装、禁止登录、禁止调用任何变更类操作，且任何一项被阻塞时不得虚报"整体就绪"。这是你在动手前的"安检门"。

2. 凭证最小化原则

skills/setup/SKILL.md 明确规定：永远不要让用户把令牌、授权码粘贴到聊天窗口；登录走浏览器流程；多实例时不许替用户"猜"默认实例，必须询问。

安全机制的边界画得非常清晰：AI 可以预览、可以建议、可以等待，唯独不可以替人拍板。

如何快速在自己的环境里启用

1. 在你的 AI 编码助手插件市场中添加 portal-ai-plugins 仓库，安装portal插件；
2. 开启新会话，运行/portal:setup，按提示完成认证与实例选择；
3. 遇到任何操作类需求时，Agent 会自然走"检查帮助 → dry-run 预览 → 展示变更 → 等待授权"的流程——你只需要关注最后一步：看清变更，再决定同不同意。

完整工作流说明见 skills/actions/SKILL.md 与仓库根目录的 README.md。

小结

📌 portal-ai-plugins 的 actions 技能给我们的启示是：驯服 AI Agent 的"手"，靠的不是禁令，而是一套可审计、可中断、可追溯的标准流程。五步走完，高风险操作从"听天由命"变成了"步步留痕"。

【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins