如何理解 Open Mercato Mutation Approval GateAI 写操作如何安全落地的 5 个关键点【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercatoOpen Mercato 是面向 CRM/ERP 与商务场景的开源 TypeScript 工程基础框架其 AI 框架内置了Mutation Approval Gate变更审批门禁任何由 AI 发起的写操作都必须先被暂存为待确认动作由用户逐字段审查差异并手动确认后才会真正写入数据库。理解这条安全链路是掌握 Open Mercato AI 能力的第一步。一、什么是 Mutation Approval Gate为什么需要它传统脚本化写操作出错可控而大模型的写操作失败方式完全不同提示词注入、幻觉出错误的记录 ID、字段值只生成了一半……这些都可能发生。Mutation Approval Gate 正是为此设计的承重安全层它保证三件事保障说明 所见即所得用户在数据落库前能看到将要变更的完整字段差异diff️ 版本复检确认时重新比对目标记录版本两个并发会话不会互相覆盖 类型化事件每次确认/取消/过期都会发出事件前端列表可零轮询刷新官方文档对这条机制有完整描述mutation-approvals.mdx。二、待办动作的生命周期6 个状态一次看懂当 AI 调用了一个标记为isMutation: true的工具运行时会拦截这次调用写入一条pending状态的待办动作。此后它只能沿固定的状态机流转pending ──┬─▶ confirmed ──▶ executing ──▶ confirmed成功 │ └───────▶ failed失败 ├─▶ cancelled用户取消 └─▶ expired超时过期pending等待用户处理confirmed / cancelled / expired / failed终态不可再流转。任何非法跳转比如confirmed → pending都会抛出AiPendingActionStateError。这套状态机的唯一权威定义在 pending-action-types.ts 中。三、三级变更策略从只读到强制确认每个 AI 智能体都声明一个变更策略AiAgentMutationPolicy共三档严格程度从高到低read-only完全禁止写操作AI 只能查询destructive-confirm-required所有写操作包括非破坏性的都强制弹出确认confirm-required写操作经单次用户确认即可执行。多租户场景下租户可以为某个智能体下发策略覆盖但规则是只降不升——系统永远取代码声明与租户覆盖中更严格的那一个任何试图放宽策略的请求都会在路由层被直接拒绝400。策略合并逻辑见 agent-policy.ts。四、确认前的最后一道复检如何挡住过期数据用户点下确认按钮到真正执行之间数据可能已经变了比如另一位同事刚改了同一条记录。执行器在落库前会调用 pending-action-recheck.ts 做一组复检状态是否仍为pending、是否已过期智能体与工具是否仍在白名单内、权限是否仍然满足逐条比对记录版本已漂移的记录被移入failed_records其余记录继续批量执行。批量写操作因此支持部分成功结果卡片会清晰展示哪些记录成功、哪些因版本过时而失败。执行主流程实现在 pending-action-executor.ts。五、TTL 过期与后台清理不处理就自动作废待办动作默认15 分钟900 秒无人处理即过期可通过环境变量AI_PENDING_ACTION_TTL_SECONDS调整。后台清理 Workerai_assistant:pending-action-cleanup每 5 分钟扫描所有租户把超时的pending行安全地转为expired并且能正确处理用户取消与定时清理同时发生时的竞态。清理 Worker 源码位于 ai-pending-action-cleanup.ts。六、新手速查核心文件路径清单想深入源码时按以下顺序阅读即可完整理解这条安全链路生命周期与表结构AiPendingActionRepository.ts写待办动作构建 diffprepare-mutation.ts策略判定agent-policy.ts确认/取消 API 路由api/ai/actions/审批卡片组件packages/ui/src/ai/parts/官方机制文档mutation-approvals.mdx总结一句话记住 Mutation Approval GateAI 只负责提案人负责拍板。每一次写操作都经历 暂存 → 差异预览 → 版本复检 → 用户确认 → 事务执行 的完整闭环配合三级策略、幂等键与 TTL 过期让 AI 写操作在企业级 CRM/ERP 系统中可以放心落地。【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
