convex-deploy-guard

部署目标防护

不同部署不能互换，大多数事故都始于命令指向了错误的部署。每个 Convex 项目都有多个部署（个人开发、预览、生产环境——通常一台机器上还会有多个项目）。这套防护是必须遵守的规范：先确认，再告知，然后操作——并且生产环境的每项操作、每个会话都必须经过明确授权。

工作流

1. 操作前先确认：读取 .env.local 中的 CONVEX_DEPLOYMENT、convex.json，并检查是否设置了 CONVEX_DEPLOY_KEY；或者调用官方 Convex MCP 的 status 工具。将目标归类为：local-anonymous | dev | preview | prod。如果两个来源的信息不一致，先查明原因再继续。
2. 执行任何会影响部署的命令前，先用一行告知目标：target: dev (joyful-capybara-123, personal dev)。切勿在发现目标的同时就运行命令——先告知。
3. 生产环境需要当场获得明确同意：在运行 npx convex deploy（当其指向生产环境时）、npx convex run --prod、对生产环境执行 env set、对生产环境执行快照 import/export，或启动可访问生产环境的 MCP 之前，准确说明将对哪个部署进行哪些更改，并在本会话中获得明确同意。先前给出的同意，或针对其他目标给出的同意，均不适用。
4. MCP 安全默认值：启动官方 MCP 时限定为非生产环境（--deployment dev）。两个生产环境标志的风险等级不同——应分别使用：只读的生产环境审计（读取 advisor/insights 数据/日志/insights）仅使用 --cautiously-allow-production-pii（读取工具）；除非用户在本会话中明确要求更改生产环境，否则必须关闭 --dangerously-enable-production-deployments（该标志会启用会修改生产环境的工具）。默认情况下绝不能同时使用这两个标志——“查看生产环境”不能在无提示的情况下变成“修改生产环境”。
5. 只读会话模式：用户说“只读”/“不要做任何更改”时，本会话剩余时间都必须绝对遵守——不部署、不设置/移除环境变量、不通过 run 执行更改、不导入；启动 MCP 时使用 --disable-tools run,envSet,envRemove。
6. 诊断错误部署：如果部署后“没有任何变化”，不要更用力地重新部署。重新执行第 1 步——几乎可以肯定是部署到了与当前观察对象不同的部署。
7. 有歧义就停止：如果无法确定命令会作用于哪个部署，就查明（使用 status 工具）——绝不猜测。

规则

• 每次执行会影响部署的命令前，都要先归类并告知目标——确认目标和采取操作是两个独立步骤。
• 生产环境授权按操作、目标和会话分别进行：说明要在哪里更改什么，并重新获得明确同意。
• 根据风险将两个生产环境 MCP 标志分开使用：审计时使用只读标志 --cautiously-allow-production-pii；仅当用户明确要求更改生产环境时才使用可修改生产环境的标志 --dangerously-enable-production-deployments。这两个标志都必须由用户明确提出；每次启动 MCP 时，默认都选择非生产环境部署。
• 一旦请求启用只读模式，该模式在整个会话中都必须绝对遵守——包括所谓“无害”的更改。
• 如果部署看起来毫无效果，说明更改的是错误的部署——诊断目标，不要重新运行。
• 此防护可与其他流程组合：ship、env、migrate 和 seed 将其作为第 0 步执行；它本身不是部署工具。