企业官网建设流程全解析

如何理解 Open Mercato Mutation Approval Gate：AI 写操作如何安全落地的 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-mercato

Open Mercato 是面向 CRM/ERP 与商务场景的开源 TypeScript 工程基础框架，其 AI 框架内置了Mutation Approval Gate（变更审批门禁）：任何由 AI 发起的写操作，都必须先被"暂存"为待确认动作，由用户逐字段审查差异并手动确认后，才会真正写入数据库。理解这条安全链路，是掌握 Open Mercato AI 能力的第一步。

一、什么是 Mutation Approval Gate？为什么需要它

传统脚本化写操作出错可控，而大模型的写操作失败方式完全不同：提示词注入、幻觉出错误的记录 ID、字段值只生成了一半……这些都可能发生。

Mutation Approval Gate 正是为此设计的"承重安全层"，它保证三件事：

官方文档对这条机制有完整描述：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），共三档，严格程度从高到低：

1. read-only：完全禁止写操作，AI 只能查询；
2. destructive-confirm-required：所有写操作（包括非破坏性的）都强制弹出确认；
3. 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
• 写待办动作（构建 diff）：prepare-mutation.ts
• 策略判定：agent-policy.ts
• 确认/取消 API 路由：api/ai/actions/
• 审批卡片组件：packages/ui/src/ai/parts/
• 官方机制文档：mutation-approvals.mdx

总结：一句话记住 Mutation Approval Gate

AI 只负责"提案"，人负责"拍板"。每一次写操作都经历 暂存 → 差异预览 → 版本复检 → 用户确认 → 事务执行 的完整闭环，配合三级策略、幂等键与 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