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）只能传入 --cautiously-allow-production-pii（读取工具）；除非用户在本次会话中明确要求更改生产环境，否则应关闭 --dangerously-enable-production-deployments（启用会修改生产环境的工具）。默认情况下绝不要同时启用这两个标志——“查看生产环境”不应悄然授权“修改生产环境”。
5. 只读会话模式：用户说“只读”／“不要更改任何内容”时，在本次会话剩余时间内都必须绝对遵守——不得部署、设置／删除环境变量、通过 run 执行修改操作或导入；启动 MCP 时使用 --disable-tools run,envSet,envRemove。
6. 诊断部署目标错误：如果部署后“什么都没变”，不要加大力度重新部署。重新执行步骤 1——部署几乎肯定落在了与当前观察对象不同的部署上。
7. 存在歧义就停止：如果无法确定命令将作用于哪个部署，就先查明（使用 status 工具；比较 npx convex env list 的指纹）——绝不要猜测。

规则

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