Yozu预检机制全解析:4种Preflight状态与5类风险码如何拦截高风险交接
Yozu预检机制全解析:4种Preflight状态与5类风险码如何拦截高风险交接
Yozu 是一个面向企业差旅的 AI 决策与执行层(AI Operating System for Enterprise Travel),它的 Preflight 预检机制会在行程方案"交接"(handoff)给执行环节前,用 4 种预检状态和 5 类风险码做最后一道校验。本文将用通俗的方式讲清楚:这 4 种状态各自代表什么、5 类风险码分别对应哪些风险,以及 Yozu 是如何用多层守卫把高风险交接拦在安全线之外的。
1️⃣ Preflight 预检在整个工作流中的位置
Yozu 的核心工作流是一条"渐进信任链",官方 README.md 中将其概括为:
intent -> decision-ready options -> source/disclosure -> approval -> preflight
也就是说,一个差旅请求要先经历:
| 阶段 | 做什么 |
|---|---|
| 意图收集 | 提交目的地、日期、预算、约束条件 |
| 决策就绪方案 | 产出可比较的 2~3 个行程方案 |
| 来源与披露 | 展示数据来源、新鲜度声明与使用边界 |
| 审批闸门 | 由明确的审批人批准后才允许继续 |
| Preflight 预检 | 在真正协调交接前做最终复查 |
同时 Yozu 在产品边界上做了明确限制(见 README.md 产品边界):不自动下单、不收取支付、不声称商户身份,只允许"审批门控下的协调",且每次结账协调前都必须执行 preflight 复查。预检机制正是这套安全承诺的落地核心。
2️⃣ 4种Preflight状态:一张表看懂每种状态的作用
Preflight 的状态被定义为一个只含 4 个取值的类型,源码在 app/lib/ops.ts:
| 状态值 | 界面显示名 | 通俗含义 | 对交接的影响 |
|---|---|---|---|
pass |
Pass | ✅ 预检全部通过 | 操作员可随时进入协调交接 |
warn |
Warn | ⚠️ 发现预警级问题 | 可以继续,但操作员必须确认已知晓风险 |
blocked |
Blocked | 🚫 发现硬性阻断问题 | 直接停止交接,问题解决前无法继续 |
reconfirm_required |
Reconfirm required | 🔄 关键信息已过时 | 必须先重新确认(重新核价/核库存)才能继续 |
显示名与中文语义映射定义在 preflightStatusLabels。
每个状态都自带"默认结论 + 下一步动作"两套文案,由 getDefaultPreflightSummary 和 getDefaultNextActionForPreflightStatus 生成,例如:
pass→ "Preflight passed. Case can move toward coordination handoff."blocked→ "Preflight blocked the handoff until the operator resolves the issue."reconfirm_required→ "Preflight requires reconfirmation before handoff can continue."
在运营面板(/ops/cases 案例详情页)中,这 4 种状态对应 4 个操作按钮:"Mark preflight pass / Mark preflight warn / Block preflight / Require reconfirmation",按钮定义位于 case-detail-client.tsx。一个细节值得注意:demo 中 warn 默认携带 price_inventory_stale_risk,blocked 默认携带 policy_evidence_missing,reconfirm_required 默认携带 source_freshness_stale——也就是说状态和风险码是绑定的,风险不能"无声存在"。
3️⃣ 5类风险码:每个码在拦截什么?
当预检不是 pass 时,Yozu 要求给出一个明确的风险码(Reason Code)。全部 5 类定义在 app/lib/ops.ts:
| 风险码 | 含义 | 拦截的是什么风险 |
|---|---|---|
source_freshness_stale |
数据来源新鲜度过期 | 用的是"旧数据"做决策,比如报价拉取时间太早 |
price_inventory_stale_risk |
价格或库存可能过时 | 机票票价、酒店房量在交接前可能已变化 |
policy_evidence_missing |
缺少政策依据 | 票价规则、退改政策没有展示给审批人 |
required_approval_missing |
缺少必需的审批证据 | 没有拿到明确批准就试图推进 |
traveler_details_missing |
缺少出行人或申请人关键信息 | 字段不全(如出行人未指定)导致执行时出错 |
风险码到人类可读文案的映射在 preflightReasonLabels,例如 source_freshness_stale 对应 "Source freshness is stale"。
这套设计的关键在于:风险必须被"点名"。每个 TripCase 数据模型都固定持有 preflightStatus、preflightReasonCode、preflightSummary、preflightCheckedAt 四个字段(见 TripCase 类型定义),对应数据库表 case_core 中的 preflight 相关列。任何一条预检记录都自带"结论 + 原因 + 时间戳",无法只写状态不写理由。
4️⃣ 三道守卫:Yozu 如何拦截高风险交接
预检的价值不只在于"打一个状态",而在于它被三道守卫串成了闭环。
第一道:入口守卫——没批准,不许预检
getPreflightGuardReason 规定:只有案例处于 approval_granted 或 ready_for_handoff(即已拿到明确审批)时,Preflight 才允许运行。若在早期阶段强行调用,API 会直接返回 400,并写入一条 preflight_guard_denied 审计事件(守卫逻辑见 route.ts)。
💡 这防止了"用未经验证的方案跳过审批直接预检放行"的越权路径。
第二道:交接守卫——5 个条件逐条校验
真正决定"能否交接"的是 getHandoffGuardReason,它按顺序检查 5 个条件:
- 是否已拿到明确审批(
approval_granted)? - 是否运行过 Preflight(
preflightStatus非空)? - 状态是否为
blocked?→ 是则拒绝:"Resolve the blocker before continuing." - 状态是否为
reconfirm_required?→ 是则要求重新确认 - 来源披露(Disclosure)是否已被确认?
任何一条不满足,交接都会被拒绝,并记录 preflight_handoff_denied 或 handoff_blocked_missing_disclosure_ack 等审计事件(事件类型清单见 AuditEvent 定义)。
第三道:状态回滚——高风险状态会"拽回"流程
这是最容易忽略但最关键的设计:如果一条已经推进到 ready_for_handoff(可交接)的案例,预检结果变为 blocked 或 reconfirm_required,后端会自动把审批状态回滚到 approval_granted,案例退回 awaiting_approval 工作流(回滚逻辑见 route.ts,状态映射见 getWorkflowStateFromApprovalState)。
也就是说:高风险预检结果不只是一个"红色标签",它会物理性地阻止案例停留在可交接位置——这正是"拦截"二字的实现方式。
5️⃣ 全链路审计:每一次预检都有据可查
每次预检状态变更都会被写入审计事件表 audit_event(表结构见 case-store.ts),记录内容包括:操作者类型(actorType)、动作(如 preflight_blocked)、变更前的状态(beforeState)、变更后的状态(afterState)、以及请求 ID(requestId)。
在案例详情页的 "Audit event log" 卡片中,操作员可以回放"谁、在哪个请求下、把哪个状态改成了什么"——包括所有被守卫拒绝的操作。被拒行为同样留痕(如 preflight_guard_denied、protected_mutation_denied),这使得预检机制本身也接受审计。
6️⃣ 快速上手:在项目中查看 Preflight 预检
如果你想亲眼看一遍完整流程:
- 克隆仓库:
git clone https://gitcode.com/gh_mirrors/yo/yozu-web - 安装依赖并启动:
npm install然后npm run dev - 打开
http://localhost:3000,进入/ops/cases案例队列 - 打开任意 demo 案例(如
YC-2401),观察 "Preflight status" 卡片:初始为 "Not run yet",交接问题显示 "Handoff stays blocked until the case is fresh, complete, and approval-safe." - 先通过审批动作把案例推到
approval_granted,再运行 4 个预检按钮,对照观察状态卡、Next Action 文案和审计日志的变化
核心文件清单,方便按图索骥:
- 预检状态与风险码定义:app/lib/ops.ts
- 守卫校验与 API 拦截:app/api/cases/[id]/route.ts
- 运营面板预检交互:app/ops/cases/[id]/case-detail-client.tsx
- 数据持久化与审计存储:app/lib/case-store.ts
- 产品边界说明:README.md
📌 小结
Yozu 的 Preflight 预检机制可以概括为一句话:用 4 种状态表达结论,用 5 类风险码点名原因,用三重守卫(审批前置、交接校验、状态回滚)保证高风险案例绝不可能"静默"进入执行环节。 对新手来说,理解这套"结论 + 原因 + 守卫 + 审计"的组合拳,就能掌握 Yozu 在差旅协调场景中构建信任边界的完整思路。