出去玩旅游攻略 Agent 技术方案
| 项目 | 内容 |
|---|---|
| 文档版本 | 1.1 |
| 初稿与更新 | 初稿 2026 年 10 月 12 日;更新 2026 年 10 月 13 日,Asia/Shanghai |
| 状态 | 技术方案草案,未实施 |
| 适用项目 | chuchuwan-mvp 微信小程序、chuchuwan-server 微信云托管服务 |
| 核查基线 | 前端 36d838d;后端 6c1ab01 |
| 第一条验收场景 | 西安出发,成都,周末两天一晚,两人合计 2000 元,轻松游 |
| 文档范围 | 对话交互、架构、资源查询、规划校验、结构化存档、攻略详情、微信分享和验收 |
本方案以对话为主要入口,卡片和表单作为可选辅助,让用户通过自然语言完成需求补充、攻略生成和持续修改。生成结果以结构化攻略保存到现有 MySQL,驱动个人攻略详情与微信只读分享。第一阶段保留前端规划引擎与后端模型、资源及存档服务的分工,补齐资料查询、完整费用与路线校验,明确参考安排、已核验信息和待核实项。
文中的新接口、类型、表、文件和配置均为拟议设计。v1.1 纳入用户已明确的交互与攻略交付方向;本轮只更新方案和清单,不修改业务代码、密钥、环境配置、现有规格或任务完成状态。正式实施先通过 GT-001 将对应变更纳入 007 的 spec、plan、tasks 和前端产品说明。
1 产品目标与能力边界
1.1 目标
用户可以自然地提出需求,Agent 在必要时集中澄清日期和预算口径,查询与本次旅行相关的资料,提出路线与费用方案,校验后生成攻略。用户修改预算、人数、日期、地点或节奏时,系统保留未改变的条件,重算受影响的部分。无需打开表单即可完成这条流程;生成结果支持结构化入库、个人列表与详情、恢复继续编辑,以及微信固定版本只读分享。
一份完整攻略应包含:需求摘要、往返交通建议、住宿建议、按天安排、用餐与体验建议、费用账本、推荐理由、必要的预约信息、替代安排以及数据来源和未核实项。
1.2 交付等级
| 等级 | 条件 | 对用户的表述 |
|---|---|---|
| 参考攻略 provisional | 结构完整,部分价格、开放、路线或库存未知或仅有参考依据 | 按当前信息生成的参考安排;明确估算和缺项 |
| 核验通过 verified | 当前需求下所有适用硬约束通过,关键证据有效,费用口径完整 | 按当前查询结果核验通过;价格和库存仍可能变化 |
| 条件不可满足 infeasible | 已知事实证明硬约束冲突,且限定搜索范围内无可行候选 | 说明冲突与可调整条件 |
verified 表示对当前数据和规则完成核验,不表示已经预订、锁定库存或保证旅行当天的交通耗时。未知数据不得推断为可行,也不得仅因查询失败就宣称客观上不可行。限定搜索未找到结果时,说明搜索范围;不能宣称整个市场没有可行方案。
1.3 第一阶段范围
| 纳入 | 暂缓 |
|---|---|
| 国内旅行自然语言需求与必要澄清 | 海外旅行 |
| 公开目录资料和即时查询资料 | 全国所有地点完整核验的承诺 |
| 火车、住宿、地点、关键路线查询 | 自营支付、出票、改签和代下单 |
| 景点营业预约依据与天气覆盖判断 | 全天候监控、后台定时查价 |
| 完整预算与轻松程度校验 | 实时等位和全程 GPS 导航 |
| 完整参考攻略及核验状态 | 自由执行任意工具的开放 Agent |
| 修改、重算、保存、恢复 | 首版引入 Redis、消息队列或第二套服务 |
| 对话主流程、可选条件卡和单项编辑 | 强制填写完整表单或逐步点击才能生成 |
| 结构化攻略详情、固定版本只读分享及撤销 | 攻略公开搜索、社交广场、分享复制与多人共同编辑 |
首条核验场景使用成都现有内容作为候选增强,但通用数据契约不限定成都。未适配城市可以继续探索或提供参考攻略,不能套用另一座城市的路线规则。餐饮首版允许推荐类型和额度,不以缺少分店菜单阻断全部参考生成。
首版重点验证不超过 3 天、一个目的地、一个住宿区域的精细规划。更长或多城市需求仍保留既有参考草案能力,并说明尚未完整核验;不能将用户天数静默缩短到首版范围。核验范围通过能力接口表达,不作为全国对话入口白名单。
1.4 对话为主与辅助交互
| 环节 | 默认路径 | 可选辅助 | 统一规则 |
|---|---|---|---|
| 开始与探索 | 输入想法、询问或比较 | 示例问题、地点卡 | 探索不自动生成,也不强制填写查价字段 |
| 关键澄清 | 集中问日期、预算口径等 | 日期选择、人数选项 | 只问影响当前动作的问题,不重复询问已有明确条件 |
| 核对条件 | 对话内简短摘要 | 点击摘要打开单项编辑 | 无强制独立确认页;默认值和未知值可见 |
| 生成 | 说“帮我生成攻略” | 生成按钮 | 条件足够就查询;缺关键条件先澄清,已表达的生成意图保留 |
| 调整 | “加大熊猫基地”“酒店便宜点” | 活动替换、预算和日期编辑 | 同一条件、选择与攻略状态,同一失效和提交规则 |
| 保存 | 说“保存这份攻略” | 保存按钮 | 两种方式调用同一保存动作,以后端回执判定成功 |
| 分享 | 说“分享这份攻略”以准备链接 | 分享按钮与预览 | 保存固定版本后,由用户触发微信转发;不自动向他人发送 |
自然语言由模型产生受控意图;表单和卡片产生同契约的类型化命令。两者都进入同一预检查、影响分析、必要确认和原子提交入口,不维护另一份表单业务状态。表单中未提交的输入仅为临时草稿,取消不修改旅行。卡片操作不为了同步状态额外调用模型;需要查询或重新规划时才进入对应工作流。
“确认”只用于日期或口径消歧、替换已有攻略、改变受保护节点等具体动作。提供自然语言与按钮两种确认方式,绑定 pendingActionId、目标动作和 baseRevision。普通“可以”只在紧邻且未失效的明确问题下承接对应动作;修改了条件后旧确认失效,不能跨问题复用。首次明确生成且无需额外取舍时不重复增加总条件确认。
现有 docs/PRD_BETA.md 有“独立完整确认页”的历史要求,旧流程也有逐项条件入口。本次方向以用户最新要求为准;GT-001 记录差异并更新实施产品说明,GT-035 调整新能力入口。旧流程保留在旧能力或降级模式中,不在本轮删除正常功能。新能力模式不暴露“先选隐藏方案”“先填完所有表单”的前置门槛。
1.5 攻略作品与交付闭环
聊需求 → 必要澄清 → 查询与规划 → 结构化攻略
├→ 对话摘要卡 → 继续修改
└→ 云保存成功 → 我的攻略/个人详情
└→ 分享预览 → 固定版本分享 → 接收者只读详情
聊天是输入和修改入口,攻略是独立业务作品。正文、时间轴、预算表和地图由结构化事实渲染;不从聊天 Markdown 反向解析正式行程。资料缺项时仍可保存和分享完整参考攻略;只有冲突说明、没有有效攻略的结果不创建攻略分享。
生成、保存、分享各有状态:生成成功不等于云保存成功;保存成功不等于分享已经发出。未确认保存身份或离线时保留本地结果和“未保存”提示。保存到云端并取得 serverVersion 后才可创建分享;保存失败时不能发出指向不存在内容的卡片。已建立自动保存生命周期的旅行沿用既有规则,首次未保存旅行由明确保存/分享意图进入身份与保存动作。
2 当前能力与复用方式
2.1 两条现有链路
真实 AI 链:输入 → 条件与偏好 → 模型 → 按天时段草案 → 修改与保存恢复
规则规划链:条件与偏好 → 城市候选路线 → Demo 费用 → 详细行程 → 编辑
AI 草案目前未接通完整费用和逐段交通校验。规则行程的费用、交通与步行主要来自配置或演示估算。两条链应通过新的结构化攻略结果连接,不能把 AI 自由文本直接转换成已核验的正式行程。
2.2 能力矩阵
| 能力 | 当前情况 | 复用方式 | 必要扩展 |
|---|---|---|---|
| 对话理解 | 真实千问,answer、clarify、条件修改、草案、行程编辑 | 沿用现有入口和解释器 | 新规划协商及分阶段结果 |
| 需求 | 城市、人数、天数、预算、日期、节奏等 | 扩展现有字段语义 | 预算口径、时区、住宿条件、时间偏好 |
| 地点选择 | wanted、must、excluded、backup 等影响生成 | 沿用稳定 ID 和选择校验 | 即时地点实体、目录与地图匹配 |
| 原子修改 | 条件、偏好、草案整体校验与提交 | 沿用确认、版本、失效保护 | 将费用、路线和报告纳入一次提交 |
| 模型输出 | JSON Schema、运行时校验和有界增量展示 | 沿用传输和公开文本边界 | 新候选结构及资源引用 |
| 全国草案 | NationalTravelDraft 按天时段建议 | 作为探索展示和兼容投影 | 结构化费用、活动和交通边 |
| 地点资料 | 公开目录、人工采用、有效期与来源 | 精选资料证据源 | 与即时查询结果分开 |
| 供应商执行 | FlyAI 单点查询进程、超时和响应处理 | 提取通用执行能力 | 火车、酒店等独立解析器 |
| 推荐 | 偏好匹配和方案对比 | 保留评分与解释结构 | 用实际增量费用和路线代替 Demo 值 |
| 详细行程 | 活动、餐饮、酒店、交通与输入指纹 | 复用展示、编辑和失效原则 | grounded 模式和真实输入 |
| 费用 | 交通、酒店、门票三项及日期估算 | 保留差异展示 | 完整账本、整数分、价格状态 |
| 时间保护 | 固定场景预约、最晚出发等 | 抽象为通用约束 | 地图时间、营业和完整接驳 |
| 云保存 | Aggregate 快照、云端适配器及恢复 | 沿用整份快照保存 | 新版本契约和旧客户端保护 |
| 条件编辑 | 对话、摘要、单项编辑已有基础 | 复用现有组件与受校验修改链 | 对话全流程可完成,辅助入口不独立维护条件 |
| 页面展示 | 对话内草案与行程卡 | 复用卡片、列表和预算展示 | 统一结构化展示契约、独立个人攻略详情 |
| 分享 | 当前为同行人投票邀请 | 仅复用微信分享钩子经验 | 攻略快照、令牌、撤销与独立只读页,不复用投票授权 |
| 运行基础 | 幂等、单用户在途、短查询、超时和用量 | 直接复用 | 工具阶段的期限、成本和进度 |
| 评测 | 离线回归、真实模型和多轮工具 | 扩充已有 runner | 预算、路线、事实与失败原因测试 |
最近的验收记录验证了开发者工具中的真实模型草案生成及云保存恢复;没有证明手机完整流程、实时路线和价格已经接通。旧 README 的早期阶段描述不能替代当前源码和最新记录。
3 架构决策
3.1 前后端职责
| 前端 chuchuwan-mvp | 后端 chuchuwan-server |
|---|---|
| 需求和偏好的展示与修改 | 微信身份、归属、模型与工具调用权限 |
| 条件预执行、确认和原子提交 | 模型适配与结构化响应边界 |
| 候选评分、路线顺序及时间编排 | 固定供应商接口与结果标准化 |
| 预算、强度和时间校验 | 资源快照、有效期、来源和查询条件 |
| 确定性修复及方案比较 | 请求去重、固定截止、用量和错误归类 |
| 攻略展示、编辑、存档内容及恢复重验 | 云端快照存档及版本支持检查 |
| 个人/分享详情组件与同源展示 | 存档结构验证、白名单展示投影、分享快照与访问控制 |
后端资源编排只决定允许查询什么、如何有界执行和返回证据,不选择最终玩法或修改 Trip。前端计算结果用于产品安排,不作为支付、库存或身份的服务端证明。若未来需要服务端权威规划,需要另行调整架构规格。
3.2 关键选择
| 决策 | 选择 | 原因 |
|---|---|---|
| 模型 | 沿用现有千问适配器 | 先补数据和校验,避免同时改变模型基线 |
| Agent 形式 | 有限状态工作流 | 查询和失败边界可测,避免无界执行 |
| 首版工具选择 | 程序按已确认需求生成查询清单 | 不依赖模型执行任意函数 |
| 输出 | 模型提出结构化候选,程序计算结果 | 减少文字中的价格和时间无法核对的问题 |
| 事实来源 | 服务端资源快照 | 客户端和模型不能自报已核实数据 |
| 数据库 | 现有 MySQL,必要的资源运行表 | 不拆现有 Trip 为需求、日程等关系表 |
| RAG | 结构化资料检索先行 | 当前不需要向量数据库才能落地 |
| 发布 | 能力协商和独立开关 | 旧协议、资料管理和 Demo 能力保持可识别 |
| 交互 | 对话默认、卡片与单项表单可选 | 无需表单完成生成,精确编辑仍可快捷操作 |
| 作品 | V2 结构化事实、统一展示投影 | 保存、个人详情与分享使用同一份事实 |
| 分享 | 保存版本的不可变只读快照 | 作者后续修改不改变已发分享;新版本创建新分享 |
现有模型适配器会拒绝非空 tool_calls。首版保持这一边界,通过受控资源接口查询后再调用模型。不能仅在提示词中要求“联网查询”就宣称已经接通。
3.3 组件关系
4 需求解析与规范化
4.1 本次需求
| 字段 | 值 | 状态 |
|---|---|---|
| 出发地、目的地 | 西安、成都 | 用户明确 |
| 人数 | 2 人 | 用户明确;年龄构成未说明 |
| 日期 | 2026-10-17 至 2026-10-18 | 由本次对话确认 |
| 预算 | 两人合计 2000 元 | 用户确认 |
| 预算范围 | 往返交通、住宿、餐饮、当地交通及计划体验 | 本次提问中说明并确认 |
| 节奏 | 轻松 | 用户明确 |
| 住宿 | 一晚、一间房 | 方案假设,房型待明确 |
| 必去项 | 无 | 不自行补为硬要求 |
“2 人”不能直接推断为情侣或两个成年人。参考预算可暂按普通成人价格,但必须记录假设;只有影响资源报价时才补问对应年龄或房型。
4.2 补充字段
| 字段 | 含义 | 默认处理 |
|---|---|---|
| planningNow、timezone | 规划时刻、用户时区 | 用服务端时刻与显式时区,回放时冻结 |
| budgetScope | group_total、per_person、unknown | unknown 不直接用于声称全程预算符合 |
| budgetIncludes | 预算包含类别 | 生成完整费用前确认 |
| roomCount、roomType | 房间数与房型 | 未指定保留未知或显式假设 |
| hotelDates | 入住、退房 | 从已确认方案推导,不直接把天数当晚数 |
| departureWindow、returnWindow | 希望出发与返程时段 | 区分偏好与不可改变条件 |
| latestArrivalHome | 最晚回到出发城市时间 | 用户要求才作为硬约束 |
| assumptions | 假设值、依据、确认状态 | 所有补充默认值集中记录 |
| constraintOrigin | user、profile、derived | 用户条件优先于产品默认值 |
原有 budget 字段继续表示规范化后的整次旅行金额。人均金额另存原始口径,人数改变时重算;不能只改人数而保留由旧人数推导的总额。金额入口保留元,费用计算统一转换为整数分。
4.3 相对日期规则
- 使用显式时区的日历日期,不依赖无时区字符串或设备年份猜测。
- “本周末”先形成候选日期,并在需要查价时确认。周六、周日发起时应确认是当前剩余周末还是下个周末。
- 仅探索玩法不强制补齐日期;交通与住宿的日期报价必须有对应日期。
- 非法日期拒绝,不自动修补为另一天。
- 日历天数、酒店晚数和跨午夜交通分别计算。
4.4 澄清与假设
预算口径、具体查价日期和必须满足的条件是关键澄清项。兴趣、茶馆、餐型等可采用可见默认值。一次优先问最影响可行性的问题,避免把完整表单作为所有回答的前置条件。
用户明确要求生成攻略时直接进入生成流程,不强迫先完成所有探索按钮。普通比较或询问仍只回答,不自动改选择或生成整份攻略。
只提供预算金额但口径不明时可展示概略建议,不能据此启动完整报价并宣称满足预算。用户已明确生成,随后补齐当前澄清项时继续本次生成,不要求再点按钮。用户改口为“先不生成”则清除待生成意图。保存、分享等无规划计算的显式按钮动作不领取资源工作流或消耗模型调用次数。
5 状态与执行流程
5.1 工作流状态
idle → interpreting → clarifying 或 collecting_resources
collecting_resources → composing_candidate → checking_routes
checking_routes → validating → awaiting_confirmation 或 ready
ready → committed → saved
任意在途状态 → failed、cancelled 或 stale
工作流进度不改变旅行内容版本。只有用户修改或最终提交才改变内容版本,防止查询进度和目录加载误使本轮结果失效。当前已有等待 AI 时暂停目录定时清空的保护应保留。
5.2 两阶段模型协议
拟增加显式 planningSupport=grounded-v1 协商,旧客户端不接收扩展分支。
| 阶段 | 模型职责 | 返回 | 不允许 |
|---|---|---|---|
| intent | 解释本轮条件和生成意图 | planning_intent 或原 answer/clarify | 宣称查询完成、写入费用和最终攻略 |
| compose | 使用服务端资源生成候选 | plan_candidate | 编造资源 ID、来源、库存或最终核验状态 |
planning_intent 携带稀疏条件补丁、偏好和选择变化。前端先通过已有预执行校验,形成暂存需求;此时不修改正式条件或旧攻略。资源查询和候选生成都使用暂存需求。最终校验与必要确认完成后,一次提交条件、偏好、选择、攻略和校验报告。
用户只要求修改条件、不要求生成时,继续原有 trip_change 路径。已明确的条件下点击生成按钮,可省略 intent 阶段;这不是省略关键需求校验。
5.3 查询顺序
| 批次 | 查询 | 依赖 |
|---|---|---|
| A | 往返火车、住宿候选、地点资料 | 暂存的城市、日期、人数和住宿条件 |
| B | 地区解析与地图实体匹配 | A 的地点、车站、住宿候选 |
| C | 候选路线的关键交通边、适用天气与营业预约依据 | 已匹配实体和候选组合 |
同批独立请求可有限并发,必须逐项读取失败和缺项。依赖请求顺序执行。先发现交通和住宿已知成本不可承担时,不继续大量查询可选体验。
模型首次候选可以使用已有片区资料提出顺序;程序取得真实路线边后重算。所谓“轻松”和“少绕路”必须由路线检查确认,不能用模型理由代替。
若没有任何可用实体候选,沿用已有 NationalTravelDraft 参考模式,保持条件和偏好一致,并说明地点尚未匹配。不得让新候选结构通过编造实体 ID 来完成;该结果不进入 verified 分支,也不伪装成有精确路线的 grounded 行程。
5.4 有界执行
下列为首版拟议参数,需在离线和真实样本中调整,不代表当前配置已经改变。
| 参数 | 建议值 | 处理 |
|---|---|---|
| 整次生成截止 | 200 秒 | 所有阶段共享绝对截止,不因轮询或重试延长 |
| 模型调用数 | 最多 2 次 | intent 与 compose;条件已明确时最多 1 次 |
| 单次云请求 | 沿用最多 15 秒的客户端约束 | 启动与只读查询,不长连接阻塞 |
| 工具执行并发 | 每次工作流最多 3 个 | 全局并发另由服务能力控制 |
| 外部请求总数 | 每次工作流最多 32 个 | 包括实体匹配与路线,不接受模型扩大 |
| 候选实体 | 总计最多 30 个 | 过滤后优先送入模型 |
| 路线边查询 | 最多 12 条 | 重复边复用;超限减少候选或标记部分核验 |
| 组合比较 | 最多 24 个组合 | 输出搜索范围,避免声称全局最优 |
| 确定性修复 | 最多 2 轮 | 不自动增加付费模型调用 |
| 输入输出大小 | 保留已有 90 KiB 与模型边界 | 新资源投影另设总量上限 |
现有客户端预算是 200000ms,后端模型持续生成上限是 180000ms;本方案不把这两个值直接相加。各调用只能领取工作流剩余时间。模型空闲超时与整个流程的绝对截止分别检查。
新工作流运行记录固定 owner、operationId、baseRevision、截止和阶段。阶段重复启动重放同一结果;旧任务失败、未知或过期不会自动再次付费执行。用户再次请求生成是新操作,但仍受单用户在途和阶段边界保护。不恢复任意个人或全站每日聊天次数封顶。
6 资源和证据模型
6.1 两种资料来源
| 来源 | 语义 | 是否自动进入精选目录 |
|---|---|---|
| catalog_adopted | 当前公开可见且已采用的基础资料 | 已有管理核验结果 |
| provider_query | 当前工作流的供应商即时查询结果 | 否 |
即时查询不能绕过管理权限自动成为已审核地点。普通聊天查询新资源也不能重新开启旧 FlyAI 访问刷新入口,或改变 006 管理员显式刷新语义。
6.2 核心契约
以下为拟议 TypeScript 领域接口,尚未创建对应业务文件。
type CheckState = 'pass' | 'fail' | 'unknown' | 'not_applicable'
type PlanStatus = 'provisional' | 'verified' | 'infeasible'
type PriceStatus = 'quoted' | 'reference' | 'estimated' | 'target' | 'unknown'
type ResourceStatus = 'available' | 'partial' | 'none' | 'unavailable'
interface ResourceEvidence {
evidenceId: string
entityId: string
field: string
sourceKind: 'catalog_adopted' | 'provider_query'
provider: string
sourceUrl: string | null
fetchedAt: string
sourceUpdatedAt: string | null
usableUntil: string
applicableDates: string[]
context: Record<string, string | number | boolean | null>
value: unknown
limitations: string[]
}
interface GeoEntity {
entityId: string
kind: 'place' | 'hotel' | 'restaurant' | 'station' | 'entrance'
name: string
cityName: string
catalogPlaceId: string | null
providerEntityId: string | null
mapPoiId: string | null
coordinates: { longitude: number; latitude: number; crs: 'GCJ-02' | 'WGS84' } | null
identityStatus: 'matched' | 'ambiguous' | 'unmatched'
evidenceIds: string[]
}
interface ResourceBundle {
schemaVersion: 1
bundleId: string
operationId: string
inputHash: string
status: ResourceStatus
checkedAt: string
usableUntil: string
entities: GeoEntity[]
options: ResourceOption[]
evidence: ResourceEvidence[]
missingFields: string[]
}
interface ResourceOption {
resourceId: string
kind: 'train' | 'hotel' | 'ticket' | 'experience'
entityIds: string[]
applicableDates: string[]
availability: 'known_available' | 'known_unavailable' | 'unknown'
availableQuantity: number | null
price: {
amountFen: number | null
status: PriceStatus
scope: 'person_leg' | 'room_night' | 'stay_total' | 'person' | 'unknown'
taxesIncluded: boolean | null
}
conditions: Record<string, string | number | boolean | null>
evidenceIds: string[]
}
interface PlanCandidate {
candidateId: string
title: string
outboundResourceId: string | null
inboundResourceId: string | null
hotelResourceId: string | null
days: {
dayNumber: number
slots: {
period: 'morning' | 'afternoon' | 'evening'
entityIds: string[]
durationHintMinutes: number | null
suggestion: string
}[]
}[]
omittedWanted: { entityId: string; reason: string }[]
tradeoffs: string[]
}
interface CostItem {
id: string
category: 'intercity' | 'lodging' | 'food' | 'local' | 'ticket' | 'experience' | 'other'
label: string
unit: 'person_leg' | 'room_night' | 'person' | 'group'
quantity: number
unitPriceFen: number | null
priceStatus: PriceStatus
includedInBudget: boolean
resourceRef: string | null
evidenceIds: string[]
}
interface ValidationCheck {
code: string
state: CheckState
hard: boolean
entityIds: string[]
evidenceIds: string[]
expected: unknown
actual: unknown
message: string
}
interface GroundedTravelPlan {
schemaVersion: 1
planId: string
operationId: string
inputHash: string
status: PlanStatus
title: string
timezone: string
overview: {
summary: string
recommendationReasons: string[]
tradeoffs: string[]
alternatives: string[]
bookingNotices: string[]
}
transportAndStay: {
adviceId: string
kind: 'outbound' | 'inbound' | 'lodging'
title: string
resourceId: string | null
entityIds: string[]
startAt: string | null
endAt: string | null
roomCount: number | null
roomType: string | null
occupancy: number | null
costItemIds: string[]
evidenceIds: string[]
limitations: string[]
}[]
days: PlannedDay[]
costItems: CostItem[]
reserveFen: number
calculatedTotalFen: number | null
resourceBundleIds: string[]
checks: ValidationCheck[]
assumptions: { field: string; value: unknown; confirmed: boolean }[]
missingFields: string[]
generatedAt: string
validatedAt: string
policyVersion: string
}
value、context、expected 和 actual 在完整运行时契约中按资源类型进一步限制,不能把任意对象作为可信数据通道。以上接口用于界定责任,不用 TypeScript 类型断言替代运行时校验。
PlanCandidate 是 compose 阶段的模型输出,资源引用必须来自本操作已取得的 options,地点必须来自 entities。模型只选择候选、提出时长建议与体验说明;quoted 金额、来源、最终交通耗时和核验状态由程序从资源事实构造。空资源引用表示尚未选定或没有可用资源,不表示免费。多方案数量由候选覆盖决定,不强制输出三份。
6.3 资源报价字段
| 资源 | 必须表达的条件 | 保持未知的字段 |
|---|---|---|
| 火车 | 发到车站、日期时刻、车次、席别、单价口径、人数 | 缺失的余量、儿童价、无单位且无法确认的时长 |
| 酒店 | 入离日期、房型、房间数、人数、晚数、含税总价口径 | 裸展示价未说明的税费、库存和政策 |
| 地点门票 | 地点、票种、人数、适用日期、附加费用 | 无票价或只有详情入口时不得填零 |
| 餐饮 | 分店、适用餐型、人数、菜单或估算依据 | 没有实时等位数据时不得声称不用排队 |
| 路线 | 起终实体、方式、查询时刻、距离、耗时、步行和换乘 | 未来拥堵、内部步行、缺失票费 |
| 营业预约 | 场所、适用日、开闭时间、最晚入场、预约窗 | 仅历史攻略中的开放信息 |
| 天气 | 城市、报告时刻、预报覆盖日期 | 未覆盖旅行日期的天气 |
库存应分别记录 known_available、known_unavailable、unknown,数量为空不代表有票或售罄。quoted 需要匹配完整报价条件;供应商返回展示价但缺房型或计费范围时只能记 reference。
6.4 实体匹配
先以城市和行政区限定范围,再结合名称、地址、官方或供应商 ID 以及坐标匹配。多个同名候选不能自动取第一条。地区中心点、酒店商圈中心点不能作为景点入口使用。
保留目录 ID、供应商 ID 和地图 ID 的映射。只有唯一匹配才可以查询实际交通;别名归并后计数,防止同一地点换名字逃避必去或排除规则。不同坐标系经明确转换或重新获取同源地图实体后才用于算路。
即时地点使用独立实体引用,不把未经匹配的供应商 ID 塞进旧 ExperienceId 或 catalog-v1 校验器。V2 选择状态同时支持目录和即时实体,已有目录选择含义不变。
6.5 来源与有效期
usableUntil 是本系统允许使用的截止,不等于供应商保证成交的截止。查询时间、页面发布时间和内容适用日期分别保留。缺少 sourceUrl 时显示提供方和查询时间,不编造链接。
初始缓存策略:地点实体最长 24 小时;交通和住宿结果最长 5 分钟;路线和天气最长 10 分钟;营业预约依据按来源适用期并在准备出行时复核。实际缓存截止取策略、供应商有效期和内容使用限制中的最早值。未明确的商业权益或保存期限必须在供应商接入验收中落实。
缓存命中不能把 fetchedAt 改成当前时间。超过使用截止的结果仅作历史参考,恢复旧行程时不能保持 verified 状态。
7 工具与供应商接入
7.1 内部工具契约
| 工具 | 必要输入 | 输出 | 首版来源 |
|---|---|---|---|
| searchPlaces | 城市、主题或关键词 | 有界地点及来源 | FlyAI、公开目录 |
| searchTrains | 发到城市或车站、日期、席别 | 班次与报价条件 | FlyAI 分类查询 |
| searchHotels | 目的地、入离日期、住宿条件 | 酒店与价格口径 | FlyAI 分类查询 |
| resolveRegion | 地区名称 | 行政编码、城市编码 | 高德 |
| matchMapEntity | 城市、名称、地址 | 地图实体与坐标 | 高德 |
| queryRoute | 起终点、方式、时间条件 | 距离、耗时、换乘 | 高德 |
| queryWeather | 地区 | 报告时间和覆盖日期 | 高德 |
| getVenueRules | 地点和日期 | 营业、门票和预约依据 | 官方或授权资料,未覆盖则未知 |
首版不把 getVenueRules 假定为 FlyAI 已完整提供的能力。供应商字段不足时需要官方资料补充或降级,不能由大模型记忆补齐为已核实。
7.2 FlyAI
复用现有服务端环境注入、固定包版本、无 shell 子进程、取消信号、超时、输出上限与错误归类。分别实现 search-poi、search-train、search-hotel 的参数投影与响应解析,不接受客户端给定命令或额外任意参数。
公开文档给出了火车与酒店查询入口,但具体计费条件和可用字段仍需用当前账号真实响应验证。火车文档、酒店文档
已有历史样本的价格字段与文档示例不同,应作为离线解析回归保留。字符串金额要严格解析币种和单位;空值、非法值或未知格式保留缺项。不要将 AI 搜索返回的 Markdown 攻略作为结构化规划引擎。
7.3 高德
使用服务端 Web 服务 Key 和固定主机。POI 匹配先于路线,按接口要求分别使用行政编码和城市编码。距离和耗时标准化为米与秒,不能缺值转零。路线数据用于当前查询条件下的预估,不保证未来实际耗时。路线官方文档
天气按实际返回日期判断是否覆盖旅行日期,不能因调用成功就声称知道任意未来日期天气。天气官方文档
API 权限、密钥类型、额度和商业使用条件属于接入前置检查。文档可查或 SDK 中存在命令名,不等于当前账号调用已经成功。
2026-10-13 用户截图提供了 Web 服务与微信小程序两种 Key。路线和 POI 查询采用 Web 服务 Key,由后端拟议配置 TRAVEL_AMAP_WEB_KEY 注入;前端不携带该 Key。微信小程序 Key 仅在后续明确使用对应端能力时接入。本次不保存 Key 正文、不配置云服务、不调用接口;已有 Key 截图不等于权限、额度或商用条件验证完成。生成攻略不要求手机实时定位,手动出发城市可用;未知家庭位置保留接驳估算。
7.4 查询错误
| 错误 | 语义 | 处理 |
|---|---|---|
| NOT_CONFIGURED | 未配置能力 | 返回缺项,不发请求 |
| AUTH_OR_ENTITLEMENT | 供应商认证或权益不足 | 安全文案,保留内部枚举诊断 |
| NO_RESULTS | 当前查询无候选 | 标明范围,必要时询问取舍 |
| PARTIAL_DATA | 有候选但字段不齐 | 使用可用字段,降低核验状态 |
| INVALID_PROVIDER_DATA | 响应结构或单位不支持 | 不猜测修补 |
| AMBIGUOUS_ENTITY | 实体不能唯一匹配 | 澄清或保持参考建议 |
| TIMEOUT | 已超过阶段截止 | 停止当前阶段,不自动付费重试 |
| RESULT_EXPIRED | 快照已过期 | 标记待刷新,不自动恢复有效 |
供应商正文、stderr、HTML、systemMessage 和未知字段不得进入系统提示或公开错误。只将白名单事实投影作为不可信来源数据送入模型。
8 推荐与比较
8.1 筛选与评分
先排除确定失败的硬约束,再排序。关键事实未知的候选可以进入参考方案,但不得进入已核验候选集合。
候选得分 = 0.30 × 偏好匹配
+ 0.25 × 舒适程度
+ 0.20 × 预算适配
+ 0.15 × 路线适配
+ 0.10 × 证据质量
各分项归一化到 0 至 1,权重是初始配置,需要评测调整。未知数据不按优质数据评分。用户必须条件不参与以高分抵消失败。
| 分项 | 可计算输入 |
|---|---|
| 偏好匹配 | must、wanted、excluded、主题和人群标签 |
| 舒适程度 | 步行、换乘、休息、已知排队与行程余量 |
| 预算适配 | 加入候选后的费用、剩余预算和价格完整度 |
| 路线适配 | 新增交通时间、片区变化和回酒店负担 |
| 证据质量 | 来源、时效、实体匹配和字段覆盖 |
方案级评分额外扣除重复体验、过多跨区交通、时间过紧和关键缺项。酒店用整趟接驳时间评价,不只看距离某个景点最近。
8.2 三方案
推荐、更省钱、更省事应来自不同可行组合和明确取舍,不能通过固定增减金额制造差异。候选不足时允许只显示一个方案并说明原因,不硬凑三份。预算固定且明确要求不超时,更贵组合可作超预算对照,但不能标为可直接满足需求的推荐方案。
比较展示完整费用差异、交通和步行差异、保留与牺牲的体验,以及各方案的核验状态。普通比较保持当前选择,不自动替换主方案;家人票数仍只提供态度,不直接改变 selectedPlanId。
9 完整预算计算
9.1 本例预算夹具
以下是上一份攻略的预算目标,用于离线回归,不是 10 月 17 至 18 日的实时报价。
| 类别 | 单价与数量 | 金额 |
|---|---|---|
| 往返高铁 | 285 元 × 4 人次 | 1140 元 |
| 住宿 | 240 元 × 1 房晚 | 240 元 |
| 餐饮饮水 | 两人全程 | 380 元 |
| 喝茶体验 | 两人一次 | 60 元 |
| 本地交通 | 两人全程,含西安到站与成都出行 | 80 元 |
| 机动额度 | 单独预留 | 100 元 |
| 合计 | 支出 1900 元,预留 100 元 | 2000 元 |
9.2 不变量
项目金额 = 单价分 × 数量
已知支出分 = 所有 includedInBudget 项目的金额之和
预算占用分 = 已知支出分 + 机动额度分
预算通过 = 无未知必要费用 且 预算占用分 ≤ 规范化预算分
只针对目标额度加总通过时,检查代码应是 BUDGET_TARGET_SUM,不能替代有依据的 BUDGET_COST_SUM。总金额不得由模型给出的 total 直接覆盖程序计算值。
金额、数量、乘积和累计值均检查 Number.isSafeInteger 及契约上限。超限拒绝,不通过浮点舍入或截断隐藏异常金额。费用项数量也应有界,避免单项合法但全账本溢出。
住宿数量使用房间数乘晚数,交通使用人次,不重复乘人数。已包含的餐食、门票或接驳设置 inclusion 引用,防止重复计费;缺价不能按零处理。预算范围之外的可选支出单独列出,不能藏进备注。
9.3 价格与预留
target 是计划额度,estimated 是有依据的估算,reference 是参考展示价,quoted 是条件匹配的报价。四者不能仅通过修改状态字段互相升级。
使用价格区间时分别计算低值和保守高值;未明确上限不能宣称最高不超预算。机动额度按明确金额或策略计算,用户同意消耗时同步更新剩余额度。不能用同一份机动资金同时覆盖多个未计入项目。
9.4 超预算调整
优先换合适时段内的交通或住宿候选,再减少可选付费体验和非必要打车,最后调整预留并显示余额。未获确认不删除必去、不改变固定日期、不缩短住宿或改为高强度赶路。
本例票价全变为 300 元时增加 60 元;保留预留则总额 2060 元。酒店改为 350 元时增加 110 元,总额 2110 元。两项同时变化时总额 2170 元,不能只展示其中一项差额。
10 路线和轻松程度校验
10.1 活动与交通契约
interface PlannedActivity {
activityId: string
entityId: string | null
kind: 'attraction' | 'meal' | 'rest' | 'hotel' | 'luggage' | 'station'
title: string
startAt: string | null
endAt: string | null
durationMinutes: number | null
internalWalkingMeters: number | null
fixedWindow: { startAt: string; endAt: string } | null
latestEntryAt: string | null
required: boolean
evidenceIds: string[]
}
interface TravelLeg {
legId: string
fromActivityId: string
toActivityId: string
mode: 'walk' | 'transit' | 'taxi' | 'rail'
durationSeconds: number | null
plannedBufferSeconds: number
walkingMeters: number | null
transferCount: number | null
costItemId: string | null
evidenceIds: string[]
}
interface PlannedDay {
dayNumber: number
date: string
activities: PlannedActivity[]
legs: TravelLeg[]
majorAreaCount: number | null
totalWalkingMeters: number | null
destinationTransitMinutes: number | null
seatedRestMinutes: number
}
日期时间统一带时区偏移,日历日期按 Asia/Shanghai 划分。软活动显示时间范围,硬交通和预约保留精确时间。时间未知允许生成参考时段,不允许填精确值制造确定性。
10.2 必须包含的节点
出发端接驳、到达车站、酒店入住或寄存、退房、取行李、返程车站与回家接驳进入计划。用户没有提供出发端位置时,可记录一个显式交通预算和待核实耗时,不伪造从家出发的路线。
10.3 时间计算
到达下一活动 = 当前活动结束 + 交通耗时 + 交通缓冲
下一活动开始 = max(到达时间, 开始开放时间, 预约起点)
下一活动结束 = 开始时间 + 活动时长
检查:开始不晚于最晚入场;结束不晚于闭馆或窗口终点
检查:返程到站满足提前量;入住退房与取行李可完成
初始保守交通可采用 ceil(供应商耗时 × 1.2) + 5 分钟。该公式是策略缓冲,没有统计依据时不能称为 P90。返程提前到站默认 60 分钟,可根据车站条件调整;取行李作为独立时长计入。
10.4 轻松默认参数
| 指标 | 默认值 | 含义 |
|---|---|---|
| 每天主要片区 | 不超过 2 个 | 连续相邻街区可归同片区,但需统一算法 |
| 每天目的地总步行 | 不超过 5 公里 | 含接驳与景点内部 |
| 连续步行 | 不超过 30 分钟 | 插入休息或交通 |
| 每天目的地本地交通 | 不超过 120 分钟 | 含当地车站接驳,不含跨城列车 |
| 每天坐下休息 | 至少 90 分钟 | 用餐和喝茶可计入 |
| 非必要长排队 | 尽量不超过 30 分钟 | 无数据则未知,不推断为零 |
这些为 profile 默认值,用户明确要求优先。只有用户要求“最多两个地点”时才使用地点数硬上限,不能和“两个片区”混为一谈。内部步行缺失时轻松程度检查可能为 unknown,不能仅凭低步行标签通过。
10.5 路线顺序与修复
少量活动枚举可行顺序,较多活动使用有界搜索。取行李和固定预约节点不能为了减少距离被删除。记录比较过的组合及时间代价,避免宣称全局最短。
修复优先调整弹性活动顺序和时间,再替换同类候选或删除最低优先的可选活动。must 和固定交通冲突时提出取舍,不静默放松。两轮确定性修复仍不能满足时,保留参考结果或输出明确冲突。
11 校验与公开内容
11.1 校验分层
| 层 | 检查 |
|---|---|
| 结构 | 字段、枚举、日期、整数、大小、连续天号与唯一 ID |
| 资源 | ID 属于本操作资源,来源和适用条件匹配,未过期 |
| 选择 | 必去包含、排除与备选不安排、想去遗漏有理由 |
| 预算 | 数量口径、必要费用、预留、合计和差异 |
| 时间 | 活动冲突、营业预约、跨午夜、入住和返程 |
| 强度 | 片区、步行、换乘、交通与休息 |
| 版本 | 当前需求和偏好仍匹配本轮 inputHash |
| 文字 | 价格、日期、地点、状态与结构化结果一致 |
11.2 状态派生
已知必要硬约束失败且限定范围无可行修复 → infeasible
无必要硬约束失败,但存在关键 unknown 或仅目标额度 → provisional
所有适用硬检查 pass,关键证据有效且报价口径完整 → verified
not_applicable 需要记录理由,不能用它绕过本应适用的检查。核验状态由程序派生,模型或存档中的状态字段不是权威来源。
推荐理由只解释用户偏好、费用和体验的取舍。页面展示“正在查询交通”“正在检查路线”等真实阶段;不展示隐藏推理、系统规则、Schema 或伪装成真实调用的进度。表格和卡片里的金额由结构化数据渲染,减少自由文本与账本不一致。
11.3 细分拒绝原因
新增内部业务诊断代码,例如 MISSING_MUST、EXCLUDED_PLACE_INCLUDED、UNKNOWN_RESOURCE_ID、QUOTE_CONTEXT_MISMATCH、ROUTE_TIME_CONFLICT、BUDGET_EXCEEDED、LUGGAGE_NODE_MISSING。公开回复使用简短可行动描述,日志只留枚举和计数,不打印旅行正文。
现有部分实测只暴露 INVALID_RESPONSE,后续应保留运输错误与业务约束失败的区别,便于判断是模型质量还是资料缺项,不能靠放松必去和排除规则提升成功率。
12 接口设计
12.1 既有接口
继续使用 /v1/ai/trip/interpret/start 及结果 GET、/v1/trips、公开目录和资料接口。新客户端显式协商新规划能力;原同步、travel_assistant、atomic 和 catalog-v1 协议保持各自边界。
12.2 拟新增接口
| 接口 | 职责 | 是否调用外部供应商 |
|---|---|---|
| GET /v1/travel/capabilities | 返回可用资源类型、协议和存档版本 | 否 |
| POST /v1/travel/planning/operations | 建立固定期限的操作和阶段凭据 | 否 |
| POST /v1/travel/resources/start | 启动有界查询,返回 requestId 和 pending | 是,按显式查询清单 |
| GET /v1/travel/resources/requests/:requestId | 读取状态或资源结果 | 否 |
| GET /v1/trips/:tripId/presentation | 已确认身份的作者读取攻略展示投影 | 否 |
| POST /v1/trips/:tripId/shares | 作者对当前已保存版本创建只读快照,支持幂等 | 否 |
| GET /v1/trips/:tripId/shares | 作者查看分享状态与可恢复链接 | 否 |
| DELETE /v1/trips/:tripId/shares/:shareId | 作者撤销该分享,重复撤销幂等 | 否 |
| GET /v1/trip-shares/:shareToken | 凭有效令牌读取白名单只读攻略 | 否 |
operations 只登记执行元数据和固定截止,不承载路线评分或 Trip 修改。AI 既有接口增加 operationId、planningPhase 和 resourceBundleIds 的协商字段。服务端检查阶段凭据、归属、输入指纹和调用次数;不能因为客户端传了同名 ID 就接纳。
资源接口使用类型化 query union,只接受固定资源类型和有界参数,不接受 URL、CLI、SQL 或任意工具名。日期未确认不能启动日期报价。
12.3 示例请求
以下是离线契约示例,operationId 和 requestId 为测试标识,不是已有接口响应。
{
"schemaVersion": 1,
"operationId": "fixture-op-xian-chengdu",
"requestId": "fixture-resources-a",
"inputHash": "fixture-input-hash",
"queries": [
{
"kind": "train",
"origin": "西安北",
"destination": "成都东",
"departureDate": "2026-10-17",
"seatClass": "second_class",
"travelerCount": 2
},
{
"kind": "train",
"origin": "成都东",
"destination": "西安北",
"departureDate": "2026-10-18",
"seatClass": "second_class",
"travelerCount": 2
},
{
"kind": "hotel",
"destination": "成都",
"checkInDate": "2026-10-17",
"checkOutDate": "2026-10-18",
"roomCount": 1,
"occupancy": 2,
"roomType": null
}
]
}
roomType=null 时结果不能自动升级为房型已满足。输入 inputHash 用于绑定快照,不是安全凭据;真实归属和阶段授权由服务端记录决定。
pending 保留固定轮询间隔和请求 ID。资源 unavailable 是可处理的数据结果,身份失败、结构非法和阶段冲突是接口错误,不能混在空数组中。
12.4 攻略展示与分享接口规则
个人展示接口沿用已确认微信身份和 owner 校验;不向其他用户开放 /v1/trips/:tripId。分享读取是新的独立能力授权入口:无有效令牌不能读取,令牌只授予白名单快照的读取能力,不授予作者 Trip、对话、编辑、投票或资源仓储访问权限。接收者首版无需加入投票或确认个人身份即可查看;GT-001 将这个匿名只读例外纳入 007 规格,不放宽其他路由。
创建请求包含 schemaVersion=1、requestId、sourceServerVersion 和有界 expiresInDays。作者先成功保存,再使用回执中的版本创建分享;服务端在同一事务中读取作者当前存档、检查目标版本与未删除状态、验证展示结构、生成快照并写入分享。当前版本已变化时返回 SOURCE_VERSION_CHANGED,让作者查看后再分享,不静默分享另一个设备的新内容。该版本匹配只用于选择分享内容,不改变 Trip 保存的最后成功写入策略。
同 owner、trip、requestId、请求内容重复创建返回同一分享和令牌,异内容冲突;不额外查询模型或供应商。令牌为至少 256 位随机值的 URL 安全编码,数据库持久化 tokenHash 与加密 tokenCiphertext,供受鉴权的重放和链接恢复;加密 Key 只在后端环境提供。正文和日志不记录完整令牌、含令牌 URL 或加密 Key。令牌通过独立路径读取,响应与应用日志均脱敏,并禁止公共/CDN缓存。
首版链接默认有效 30 天,允许 1—30 天;不续期、不后台刷新。未找到、过期、撤销、原 Trip 软删除统一返回 SHARE_UNAVAILABLE/404。撤销提交后开始的新读取必须失败;每次读取检查分享和原 Trip 状态,不能只依赖缓存。已经发出的响应、截图或用户手动复制的内容无法收回。
分享读取仅根据服务端时钟、存档版本和证据有效期更新展示新鲜度,不执行规划算法或付费查询。分享创建时的状态作为历史信息;当前有效展示状态另算,证据过期后显示参考/待更新,不能仍展示“当前核验通过”。快照内容不会跟随作者编辑变化,作者分享新版时创建新快照,可主动撤销旧链接。
13 存储与兼容
13.1 存储落点
| 数据 | 落点 | 原则 |
|---|---|---|
| 用户攻略、条件与选择 | 现有 trips.aggregate JSON | 整份快照保存,不拆日程关系表 |
| AI 临时回复与用量 | 现有 ai_conversation_requests 等 | 保留幂等和到期禁止读取 |
| 管理员采用资料 | 现有 place_data_observations 等 | 不改变审核、启停、采用与清理语义 |
| 规划运行元数据 | 拟 travel_planning_runs | owner、inputHash、阶段、截止和计数;无隐藏推理 |
| 资源任务 | 拟 travel_resource_requests | 请求哈希、状态、租约、错误和有界查询参数 |
| 资源快照 | 拟 travel_resource_snapshots | 标准化白名单数据、有效期、内容哈希及归属 |
| 攻略分享 | 拟 trip_share_snapshots | 固定保存版本的白名单 JSON、内容哈希、令牌哈希与密文、有效期和撤销状态 |
新增运行表是资源调用控制,不是把前端规划引擎搬到后端。迁移编号在实施时根据实际已占用编号分配。MySQL 5.7 兼容性需保留,不依赖未验证的数据库新特性。
首版无需跨请求共享用户资源快照。若后续共享公开实体缓存,要将个人查询条件和 owner 访问控制分开。跨实例的同请求去重和单操作计数通过持久记录实现,不能只依赖进程内 Map。
13.2 存档版本
建议新增 TripAggregateV2,保留 V1 既有业务字段,增加 planningRequest、groundedPlan、entitySelections 和证据摘要。新客户端读取 V1 保持旧语义,用户开始新规划并保存时才升级;旧 Demo 行程不自动变成 grounded 行程。
新服务端支持 V1 与 V2,能力接口公布支持版本。旧客户端遇到 V2 不能先丢掉未知字段再用 V1 全量覆盖。应使用已验证的版本拒绝或升级提示路径保护数据;不能只依靠“字段可选”声称旧客户端兼容。
V2 以新的结果作为唯一规划事实来源。NationalTravelDraft 只作为兼容展示投影,费用摘要与详细行程由 groundedPlan 派生,不能各自独立更新形成多份主状态。
服务端保留整份快照最后成功写入覆盖的策略,不把 serverVersion 改成行程存档的乐观锁前置条件。存档格式检查、身份、归属和软删除保护仍生效;投票的版本规则保持独立。
13.3 恢复
- 解码并校验存档版本与结构。
- 保留用户原始条件、选择和原攻略。
- 重算输入指纹、预算和结构检查。
- 检查证据有效期和策略版本。
- 已过期或不支持的证据使状态降为 provisional,并列出待更新项。
- 用户明确重新核验时启动新查询,不因打开旧行程自动付费刷新。
资源原始供应商正文不进入 Trip。持久化必要的标准化摘要和引用,保存范围与期限遵守供应商条件。若某类正文不能长期保留,恢复后保留依据元数据,并将依赖正文的检查标记待核验。
13.4 结构化攻略与展示契约
V2 保存规范化条件、选择、groundedPlan,以及用于离线展示的最小实体和证据摘要。资源快照过期或清理后,已保存攻略仍能显示名称、安排和历史费用,但不能把历史值当当前报价。聊天是可恢复的私人上下文;正式攻略不依赖重新运行模型或解析聊天才能显示。
| 存档事实 | 内容 | 展示用途 |
|---|---|---|
| planningRequest | 城市、日期、人数、预算口径、节奏、明确条件及假设 | 条件摘要;分享只含城市级和必要人数信息 |
| groundedPlan.overview | 标题、摘要、推荐理由、取舍、替代安排和预约提示 | 对话摘要卡、详情概览与分享文案 |
| groundedPlan.transportAndStay | 往返交通与住宿建议,关联资源、实体和费用项 | 交通住宿卡;未确定项保持 null 或参考区域 |
| groundedPlan.days | 活动、接驳、时间窗、休息与强度 | 每日时间轴和路线概要 |
| groundedPlan.costItems/reserveFen | 单价、数量、价格类型、引用及机动额度 | 预算表和费用差异 |
| entitySummaries | 名称、公开地址、地图 ID、坐标系、匹配状态和可用媒体 | 地点卡和地图标记;未知位置不放到城市中心 |
| evidenceSummaries | 依据字段、提供方、可公开链接、采集与适用时间、限制 | 来源、历史价格提示与恢复新鲜度 |
| groundedPlan.checks/assumptions | 检查、缺项、策略版本与假设 | 核验说明,分享仅给公开结论与待核实项 |
overview 和 transportAndStay 已列入第6.2节拟议类型,完整运行时契约在 GT-002 定稿。交通日期和住宿入离时间保留带时区字段,房型或起终时间未知为null;住宿计费晚数由确认的入住退房日历日期派生。模型提供体验说明和取舍,程序按资源 ID 形成交通住宿及费用事实;所有数量、金额、状态由结构化值渲染。存档入口 GT-005 校验完整 V2 结构、有界大小、字段及引用闭合,不能只收合法信封就接纳任意对象。服务端校验存档一致性与访问边界,不重跑路线搜索或替代前端推荐引擎。
拟增加 TravelPlanPresentationV1:把已保存事实转换成概览、交通住宿、每日安排、预算、地点地图、来源和新鲜度的白名单展示模型。前端已生成但未保存的卡片用同一纯投影;个人详情通过后端读取保存投影;分享快照是同一展示模型的更小公开投影。标题、价格与顺序没有独立可写副本。投影包含 presentationVersion、sourceServerVersion、generatedAt、viewedAt、validatedAt、usableUntil 和有效展示状态;内部请求编号不进入分享响应。
分享采用显式字段允许清单:只含城市级条件、攻略标题与公开说明、计划日期人数、活动、可公开地点、费用、来源和缺项。私人聊天、自由备注、OpenID/userId、家庭成员信息、精确家庭位置、未公开供应商字段、审计和原始检查对象均不复制;去除私人节点时同时去除相关坐标和路线端点。来源 URL 去掉 Key/令牌等参数并限定可公开链接;无使用权的图片或供应商内容不输出。分享前显示实际公开投影预览,允许回到作者攻略修改再保存,不承诺自动识别自由文本中所有隐私。
13.5 分享快照与持久化
拟 trip_share_snapshots 记录 share_id、trip_id、owner_user_id、source_server_version、presentation_version、content_hash、snapshot_json、token_hash、token_ciphertext、request_id、request_hash、created_at、expires_at、revoked_at。建立 token_hash 唯一索引、owner/trip/request_id 幂等约束及状态查询索引。编号迁移按实施时实际情况分配,兼容 MySQL 5.7。
快照只复制已保存的允许展示数据,不长期引用会清理的资源任务正文;证据保存与对外分享权利在 GT-030 验证。已过期快照不能创建新读取授权;过期或撤销后的正文清理按供应商保留限制与产品策略落实,幂等去重元数据按必要期限保留。关分享开关也保留作者数据,不能以清库回滚。
当前家庭投票仍是独立会话,不用 vote inviteToken 读取完整攻略,也不借分享令牌加入投票。收藏、复制为自己的攻略、多作者编辑及 H5 分享页暂缓。
13.6 页面与交互状态
| 页面/组件 | 输入 | 主要行为 |
|---|---|---|
现有 pages/trip/index |
当前旅行状态 | 对话、轻量条件卡、生成进度、攻略摘要、继续修改 |
| 现有首页个人行程入口 | trips 列表摘要 | 展示标题、目的地、日期、保存时间,进入详情或继续聊天 |
拟 pages/travel-plan/index |
已保存 tripId;或本地当前结果引用 | 概览、日程、预算、交通住宿、地图概要、来源;作者可继续编辑、保存、分享 |
拟 pages/travel-plan-share/index |
shareToken | 独立只读攻略;无作者编辑、私人聊天或投票操作 |
| 拟共享详情组件 | TravelPlanPresentationV1 与只读标志 | 个人和分享共用渲染,能力按钮由页面角色控制 |
“查看完整攻略”不调用模型;地图首版展示匹配地点标记、编号与交通摘要,已有路线几何且具备展示条件时再画实际线路。无几何时不以直线冒充导航路线;微信地图展示与高德查询的坐标系明确处理。无需用户定位权限即可查看;导航跳转由用户单独触发。
个人页区分加载、未保存、已保存、有本地修改、保存失败、已删除及暂时不可用。有本地修改的攻略分享前先保存并使用新回执;不能拿旧保存版本配上新标题。详情与对话切换共用旅行快照,避免两份编辑状态竞争;打开已保存详情不自动恢复旧对话并覆盖正在编辑的另一旅行。
分享页区分加载、可读、历史参考、链接失效、网络失败和客户端版本不支持。网络失败支持重读 GET,不变成查价;失效不给私人数据兜底。转发只在有效快照取得后通过 useShareAppMessage 配置标题与小程序路径,由用户触发微信分享,不调用发消息工具。无授权封面时用产品默认图,不用 AI 实景或抓取图片冒充授权素材。
14 修改与失效
| 修改 | 失效范围 | 尽量复用 |
|---|---|---|
| 日期 | 交通、住宿、开放预约、适用天气与相关路线 | 地点实体与文化介绍 |
| 人数或年龄 | 报价口径、房型、票种和费用 | 可用地点和地理关系 |
| 预算 | 推荐组合、账本与可选体验 | 仍有效的资源价格 |
| 酒店 | 房价、接驳、行李节点与路线 | 未受影响的景点资料 |
| 地点 | 当天活动、交通边、费用和强度 | 其他天有效节点 |
| 节奏 | 活动密度、休息、时间和步行 | 资源实体与价格 |
| 目的地 | 原城市候选、资源引用和路线 | 用户普适偏好 |
失效是标记数据不能继续支持当前方案,不必清空所有历史资料。改变会使已有安排失效时复用现有影响说明和确认路径;取消、校验失败或迟到回复不留下半笔条件修改。
已购或固定预约的节点受保护。解除保护或更换日期需要用户明确确认,系统不取消订单。局部调整后必须重算相关交通和返程余量,不能只把时间字符串顺延。
15 RAG 与内容管理
已有服务端按目的地和地点读取已采用资料的能力可以作为第一版结构化 RAG。继续使用可见性、身份匹配和有效期过滤,保留 partial、none 和 unavailable。
| 适合知识库 | 必须通过当前资源查询或明确降级 |
|---|---|
| 片区特点、文化背景、体验标签 | 当日车票余量和当前酒店库存 |
| 人群适配、典型停留时间 | 指定房型的当次完整报价 |
| 有来源的历史经验与踩坑 | 当前营业公告及预约名额 |
| 种子路线和内部步行经验 | 当前交通时间和天气覆盖 |
知识库字段带实体、来源、时间和使用范围。历史平均费用只能作为估算依据。未来增加向量检索时仍先过滤目的地、有效期和实体,不让相似文本绕过事实边界。图片仅展示真实来源且具备使用条件的素材,不用 AI 图冒充实景。
16 可观测性与运行保护
16.1 运行记录
记录 operationId、requestId、阶段、输入哈希、模型和提示版本、工具类型、耗时、缓存命中、数据缺项、拒绝代码、token 用量和最终校验统计。日志不保存旅行正文、身份原文、密钥、完整含 Key URL 或原始隐藏推理。
费用区分模型 token、供应商请求及缓存命中;供应商未返回用量或收费规则不明时标记未知,不用历史单价冒充当次账单。外部调用上限是成本与运行边界,不重新引入任意每日聊天次数封顶。
16.2 权限与取消
沿用当前微信身份和内部 userId,资源 operation、request 与 bundle 均绑定 owner。客户端传入资源 ID 不授予跨 owner 读取权限。公开目录继续其匿名读取边界,新的付费查询沿用已确认的 AI 身份路径;未登录可以继续已有公开探索。
固定供应商主机、命令和参数防止任意请求执行。用户资料、供应商资料均视为数据,不可升级为 system 或工具指令。正则污染检测是补充措施,不能被视为完整注入防护。
离页或取消立即停止客户端轮询和提交;已经发出的供应商请求仍可能产生费用。后端取消信号尽力中止执行,固定截止及租约保证终止边界,不能承诺取消等于零费用。
进程崩溃后不自动恢复付费执行;任务按固定截止成为失败或结果未知,保留去重元数据。单用户在途和阶段计数需覆盖跨实例,而非仅单机并发。
17 代码落点建议
以下仅为后续任务拆分依据,本轮不创建这些业务文件。
| 项目 | 拟议文件或模块 | 职责 |
|---|---|---|
| 后端 | domain/travelResources.ts | 资源、证据、报价和错误契约 |
| 后端 | application/ports/travelResources.ts | 供应商和资源仓储端口 |
| 后端 | infra/flyai/commandRunner.ts | 通用固定命令执行器 |
| 后端 | infra/flyai/travelResourceProvider.ts | POI、火车、住宿解析 |
| 后端 | infra/amap/travelResourceProvider.ts | 行政区、实体、路线、天气 |
| 后端 | modules/travelResources | 查询、期限、去重、快照、HTTP |
| 后端 | modules/travelPlanningRuns | 操作阶段元数据,不含规划算法 |
| 后端 | config/travelResources.ts | 独立开关与查询策略 |
| 后端 | 既有 tripConversation 与 composition | 协商、证据加载和实际模型接线 |
| 前端 | contracts/groundedTravel.ts | 两端同步的纯协议 |
| 前端 | services/backends/travelResources.ts | 本服务资源调用与轮询 |
| 前端 | services/groundedPlanningCoordinator.ts | 暂存、阶段、版本及最终提交 |
| 前端 | services/travelBudget.ts | 完整账本和差异计算 |
| 前端 | services/travelConstraints.ts | 时间、强度、资源和选择校验 |
| 前端 | services/groundedRoutePlanner.ts | 有界组合和确定性修复 |
| 前端 | 既有 useTripSession、tripSessionState | 单事件提交、确认和失效 |
| 前端 | 既有 detailedItinerary、tripAggregate | grounded 展示和 V2 存档 |
| 前端 | services/travelInteraction.ts、既有 RequirementEditor | 对话、卡片、表单的统一命令与确认入口 |
| 两端纯契约 | contracts/travelPlanPresentation.ts、domain/travelPlanPresentation.ts | V2 到展示模型的纯投影和允许字段;一致性检查 |
| 前端 | pages/travel-plan、components/TravelPlanDetail | 作者详情、时间轴、预算和地图概要;注册分包 |
| 前端 | services/backends/tripShare.ts、pages/travel-plan-share | 创建、列表、撤销与独立只读页,微信分享路径 |
| 后端 | application/ports/tripShareRepository.ts、infra/db/tripShareRepository.ts | 分享快照、令牌密文、幂等和事务 |
| 后端 | modules/tripShares、既有 trips 和 composition | owner 分享管理、单独令牌读取、展示投影与配置 |
页面不直接调用供应商,供应商 SDK 不进入 src 小程序运行包。前端仓库 server/ai 的评测镜像不能成为第二套生产实现;共用契约须有一致性检查,真实评测使用当前后端适配器。
18 实施阶段与交付门槛
本节将方案映射到现有 007,不创建已完成任务或替代其授权记录。细分编号在落实 plan/tasks 时确定。
| 阶段 | 对应主线 | 工作 | 门槛 |
|---|---|---|---|
| A 契约与需求 | T002/T003 前置 | 需求口径、资源、候选、账本、报告、协商与存档设计 | 两端纯契约及非法输入测试一致 |
| B 查询接入 | T002 | FlyAI 三类查询、高德实体路线与天气、官方资料缺项 | 离线解析通过;逐供应商真实验证 |
| C 实际接线 | T003 | 操作阶段、查询结果进入模型、候选关联资源 | 实际请求中有本轮服务端证据,不信客户端伪造 |
| D 规划核验 | T003 | 完整预算、时间、强度、选择、修复和比较 | 本例及负面测试通过,无假 verified |
| E 产品与存档 | T003/T004 | 对话主流程、可选编辑、卡片、个人详情、V2 保存恢复 | 不填表可生成和修改,各入口同源,存档完整不降级覆盖 |
| E2 攻略分享 | T003/T004 | 展示投影、固定版本快照、微信只读页、撤销及过期 | 接收者可读且无编辑权限;私人字段不外泄,无 GET 付费查询 |
| F 真实验收 | T004 | 当前候选 CI、真实供应商、模型、云保存、双账号分享和手机 | 生成、保存、分享分别有证据,不用某一层替代其他层 |
第一条完整链路优先查询两程火车、一晚住宿、成都核心地点和关键接驳。若供应商只能给展示价,仍可交付完整参考攻略,但不能将该阶段写成“已核实可预订”。没有高德 Key 时可完成其他适配器及离线回归,路线能力保持未配置。
开关建议包括 TRAVEL_RESOURCES_ENABLED、TRAVEL_FLYAI_ENABLED、TRAVEL_AMAP_ENABLED、TARO_APP_GROUNDED_TRAVEL_ENABLED、TRIP_SHARE_CREATE_ENABLED 和 TRIP_SHARE_READ_ENABLED。名称在实施规格中定稿,默认关闭;已有 FlyAI 旧开关不用于新入口。分享创建与读取分别控制:停新创建时可继续读未撤销的合法快照;紧急关闭读取时统一显示不可用,作者仍可撤销。能力接口公布资源类型、存档/展示版本、创建与读取能力及最近验证记录,configured 本身不证明供应商健康。
新增查询与新客户端先受控验证,再逐步开放。回滚首先停止新资源工作流,保留既有对话和旧攻略读取。新 V2 数据存在后,不直接回退到不识别 V2 的服务版本;准备支持新数据读取但关闭新生成的兼容回滚候选。不得通过清库回退。
19 测试与评估
19.1 测试层次
| 层次 | 内容 | 不能替代 |
|---|---|---|
| 纯规则 | Schema、金额、日期、路线、选择和状态派生 | 供应商可用性 |
| 适配器 | 固定脱敏样本、错字段、空值、单位与错误 | 当前账号真实响应 |
| 接线 | 生产 composition 到模型请求与资源仓储 | 模型推荐效果 |
| 数据库 | 真 MySQL 幂等、跨实例领取、租约和清理 | 微信身份与手机体验 |
| 前端执行 | 实际 hook、reducer、codec 和存档恢复 | 真实云保存 |
| 模型评测 | 人工场景、独立验收集和真实输出 | 路线事实正确性 |
| 端到端 | 开发者工具、手机、云端与供应商 | 长期用户满意度 |
19.2 核心用例
| 编号 | 场景 | 预期 |
|---|---|---|
| Q01 | 周末、两人、2000,口径不明 | 澄清日期与预算范围,不假定已确认 |
| Q02 | 冻结 2026-10-12 与时区 | 候选周末为 10 月 17 至 18 日,确认后查价 |
| Q03 | 两人变三人,人均预算 | 总预算随人数重算,保留原始口径 |
| Q04 | 房型未知或两间房 | 不误用单间低价证明住宿满足 |
| B01 | 1900 支出加100预留 | 2000,目标额度检查通过但不自动 verified |
| B02 | 四票变300 | 总额2060,差额60 |
| B03 | 酒店变350 | 总额2110,差额110 |
| B04 | 两项同时变化 | 总额2170,差额170 |
| B05 | 门票缺价或币种不符 | 不按零,不直接混币相加 |
| B06 | 住宿按房晚、交通按人次 | 不重复乘人数 |
| R01 | 周日离开景点后需取行李 | 显式酒店节点,检查到站提前量 |
| R02 | 同名景点或餐厅分店 | 不自动匹配第一条 |
| R03 | 坐标系不同或地区中心点 | 阻止伪精确路线 |
| R04 | 到达晚于最晚入场 | 冲突、修复或取舍 |
| R05 | 跨午夜列车和日历 | 时间顺序正确,不按同日减时 |
| R06 | 内部步行缺失 | 强度未知,不因接驳短而通过 |
| P01 | 必去、排除和想去遗漏 | 与目录及即时实体统一检查 |
| P02 | 必去超过每日明确上限 | 追问,不放松用户约束 |
| E01 | 错日期票价、错房型报价 | 不作为本次已核实费用 |
| E02 | quantity=null | 库存未知 |
| E03 | 供应商查询成功但字段不全 | partial,保留有效字段 |
| E04 | 请求或快照跨 owner | 拒绝,不泄露是否存在 |
| E05 | 供应商文本含指令 | 不执行、不改变系统权限 |
| E06 | 缓存命中或过期 | 不改采集时间;过期降级 |
| S01 | 修改条件且生成,中途取消 | 原条件与攻略均保持 |
| S02 | 等待中改变地点或离页 | 旧结果不提交 |
| S03 | 资源进度、无关目录刷新 | 不把进度当内容修改 |
| S04 | V1 读取与 V2 保存恢复 | 用户条件、选择与新结果一致 |
| S05 | 旧客户端处理 V2 | 不丢弃新字段后覆盖 |
| S06 | 双设备最后写入 | 沿用最后成功写入策略,状态可解释 |
| O01 | 同请求重复 POST 和 GET | 不重复付费查询 |
| O02 | 崩溃、过期、结果未知 | 不自动重新执行 |
| O03 | 32 次请求或截止耗尽 | 有界停止、保留缺项 |
| O04 | 供应商未配置 | 零外部请求 |
| T01 | 文案数字与结构不一致 | 阻止提交或用结构化渲染修正 |
| T02 | 无可行组合但搜索范围有限 | 说明范围,不断言全市场无结果 |
| I01 | 仅自然语言完成需求、澄清、生成和修改 | 不打开表单,不要求隐藏方案或独立确认页 |
| I02 | 条件已完整且用户明确生成 | 直接进入生成,不重复总条件确认 |
| I03 | 同一修改分别用聊天、条件卡、表单表达 | 规范化条件、失效范围、费用和最终攻略等价;表单取消不改状态 |
| I04 | 普通“可以”、旧确认、修改后确认 | 只承接紧邻且版本匹配的具体动作,不误生成或替换 |
| I05 | 生成意图后补齐澄清;随后说先不生成 | 前者继续生成,后者清除待生成意图 |
| D01 | 已保存攻略关闭聊天后进入详情 | 不解析聊天、不调模型即可完整展示 |
| D02 | 卡片、个人详情、分享投影比较 | 同保存版本的日期、顺序、预算和缺项一致;隐私裁剪明确 |
| D03 | 未保存、本地修改和保存失败 | 明确状态;不创建对应新内容的分享 |
| D04 | 无坐标、坐标系不一致或无路线几何 | 地图缺项可见,不伪造点位或导航线 |
| H01 | 保存回执后创建分享,作者随后修改 | 分享固定旧版本,新版创建新快照,不静默改旧内容 |
| H02 | 创建前另一设备保存、同请求重复创建 | 版本不匹配明确拒绝;幂等重放同一快照与令牌 |
| H03 | 另一账号或匿名接收者读取分享 | 仅有效令牌可读白名单,不授予私人 Trip 或写权限 |
| H04 | 撤销、到期、软删除、关读取开关 | 新读取统一不可用,缓存不复活内容 |
| H05 | 证据到期但分享链接仍有效 | 历史金额保留,当前状态降级,零自动查询 |
| H06 | 快照夹带聊天、身份、家庭坐标、Key URL | 允许清单移除并校验,日志无完整分享令牌 |
| H07 | 保存/创建失败、缺封面、冷启动和重新转发 | 不发未就绪卡片;有默认封面;有效路径能打开 |
| H08 | 只读分享 GET 被重复刷新 | 不写旅行、不加入投票、不续期、不调用模型或供应商 |
19.3 指标
| 指标 | 定义 | 发布门槛 |
|---|---|---|
| 核心需求正确率 | 城市、日期、人数与预算口径正确 | 固定核心集100% |
| 预算算术正确率 | 单位、数量、合计与差额正确 | 100% |
| 假 verified 比例 | 存在关键未知或失败仍标已核验 | 0 |
| 必去排除违反率 | 未遵守明确选择 | 0 |
| 关键证据追溯率 | 核验事实能关联有效依据 | verified 结果100% |
| 状态误改率 | 失败、取消、迟到留下修改 | 0 |
| 重复付费执行率 | 同阶段同请求重复启动 | 0 |
| 保存恢复一致率 | 条件、选择、攻略和状态恢复一致 | 固定核心集100% |
| 对话独立完成率 | 核心生成与修改用例全程无表单参与 | 固定 I 核心集100% |
| 输入等价一致率 | 聊天/卡片/表单得到同一规范化结果 | 固定等价集100% |
| 展示事实一致率 | 卡片、个人详情和分享的共同字段一致 | 固定核心集100% |
| 分享版本正确率 | 快照匹配所选成功保存版本 | 100%,竞态不得静默换版本 |
| 分享隐私与撤销 | 禁止字段泄露、撤销后新读取成功 | 两项均为0 |
| 浏览外部调用数 | 详情/分享只读访问引起模型或供应商执行 | 0 |
| 任务完成率 | 无人工指导完成一份可理解攻略 | 真实用户试用后确定基线 |
| 延迟与费用 | P50/P95、调用数、token及供应商成本 | 实测报告,超截止率单列 |
固定集通过不等于全国旅行推荐准确率。开发集与独立验收集分开,不能把历史成功案例反复计入当前质量。拒绝应细分理解、结构、资料、规划和保存原因。
20 工作流伪代码
async def generate_plan(user_message, current_state, services, policy):
base_revision = current_state.content_revision
operation = await services.create_operation(base_revision, policy.deadline)
# 本轮补丁先暂存,不对正式状态留下部分修改。
intent = await interpret_if_needed(user_message, current_state, operation)
if intent.needs_clarification:
return clarification_without_mutation(intent.question)
staged = prepare_existing_change_rules(current_state, intent)
if not staged.valid:
return reject_without_mutation(staged.reason)
request = normalize_request(staged, operation.server_clock)
queries = build_bounded_queries(request, policy)
resources = await services.query_resources(operation, queries)
validate_bundle_origin_dates_and_expiry(resources, request)
if not resources.entities:
return await reference_draft_with_same_atomic_commit_rules(
operation, staged, request, resources
)
# 服务端按归属取 bundle;不接受客户端伪造的事实。
candidate = await services.compose_candidate(
operation, request, resources.bundle_ids
)
validate_candidate_ids_and_selections(candidate, request, resources)
plans = bounded_candidate_combinations(candidate, request, policy)
if not plans:
return explain_missing_data_or_bounded_search_conflict(resources)
reports = []
for plan in plans:
edges = await services.query_missing_route_edges(
operation, plan, policy.remaining_query_budget
)
resources = merge_validated_resource_bundles(resources, edges)
schedule = schedule_with_buffers(plan, resources, edges, policy)
ledger = compute_integer_cost_ledger(schedule, resources, request)
report = validate_all(schedule, ledger, request, resources, policy)
reports.append((schedule, ledger, report))
result = rank_with_stable_tie_breaker(reports)
for _ in range(policy.max_deterministic_repairs):
if not result.has_repairable_failure:
break
result = repair_without_extra_model_call(result)
result = revalidate(result)
result.status = derive_status_from_checks(result)
rendered = render_from_structured_result(result)
verify_public_text_against_result(rendered, result)
if state_changed_or_operation_expired(base_revision, operation):
return stale_without_mutation()
if existing_rules_require_confirmation(staged, result):
if not await get_existing_confirmation(staged, result):
return cancelled_without_mutation()
if state_changed_or_operation_expired(base_revision, operation):
return stale_without_mutation()
# 条件、偏好、选择、攻略、费用及报告只提交一次。
dispatch_one_commit_event(staged, result)
if existing_persistence_lifecycle_allows_auto_save():
await cloud_save_and_mark_from_ack_only()
else:
mark_generated_but_not_cloud_saved()
return result
搜索可行性与结果未知分别处理。没有候选时返回资源缺项或限定范围的冲突说明,不能调用 rank 空列表。真实实现须在每个 I/O 前后检查剩余预算,并逐项保留查询错误。
async def handle_interaction(action, state):
# 表单/卡片直接提交类型化动作;聊天由模型解释为同一动作。
command = await interpret_or_use_typed_command(action, state)
pending = validate_and_stage_with_existing_rules(command, state)
if pending.needs_clarification:
return show_question_and_remember_explicit_generate_intent(pending)
if pending.needs_confirmation:
return confirm_same_action_by_reply_or_button(pending)
return await execute_same_commit_path(pending)
async def prepare_share(current_trip):
await ensure_existing_save_identity()
saved = await save_current_snapshot_and_require_success_ack(current_trip)
preview = build_share_allowlist_preview(saved)
if not await user_accepts_share_preview(preview):
return keep_saved_trip_without_share()
share = await create_share_snapshot_once(
saved.trip_id, saved.server_version, stable_share_request_id()
)
# 只配置可转发卡片,最终转发由用户在微信完成。
return configure_wechat_share_card(share)
def read_share(share_token, server_now):
snapshot = load_active_share_and_check_source_trip(share_token, server_now)
if not snapshot:
return share_unavailable()
view = derive_time_freshness_only(snapshot, server_now)
return allowlisted_readonly_response_with_no_store(view)
自然语言“分享”准备预览和链接,不代表允许自动向联系人发送;有未提交的规划修改先完成或取消修改再保存。分享预览只确认对外内容,不重新增加生成前表单。服务端从事务内存档形成最终快照,不接受客户端直接上传预览作为可信正文;预览与所选源版本不一致时重新显示预览。
21 JSON Schema 示例
以下 Schema 为离线契约设计示例,不是现有生产协议。完整业务校验仍由程序承担。Draft 2020-12 的 format 应由验证器显式启用;Schema 无法独自完成跨字段金额和时间计算。规范
21.1 规范化规划请求
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "NormalizedPlanningRequest",
"type": "object",
"additionalProperties": false,
"required": ["origin", "destination", "timezone", "startDate", "endDate", "travelerCount", "budget", "pace", "roomCount"],
"properties": {
"origin": { "type": "string", "minLength": 1, "maxLength": 80 },
"destination": { "type": "string", "minLength": 1, "maxLength": 80 },
"timezone": { "const": "Asia/Shanghai" },
"startDate": { "type": "string", "format": "date" },
"endDate": { "type": "string", "format": "date" },
"travelerCount": { "type": "integer", "minimum": 1, "maximum": 99 },
"budget": {
"type": "object",
"additionalProperties": false,
"required": ["groupTotalFen", "currency", "originalScope", "includes"],
"properties": {
"groupTotalFen": { "type": "integer", "minimum": 1 },
"currency": { "const": "CNY" },
"originalScope": { "enum": ["group_total", "per_person"] },
"includes": {
"type": "array", "minItems": 1, "uniqueItems": true,
"items": { "enum": ["intercity", "lodging", "food", "local", "ticket", "experience", "other"] }
}
}
},
"pace": { "enum": ["relaxed", "balanced", "intensive"] },
"roomCount": { "type": "integer", "minimum": 1, "maximum": 99 }
}
}
该请求是查价准备完成后的投影,不要求探索阶段也有全部 required 字段。房型、时间偏好和假设属于完整请求的补充契约;roomCount 不代表房型已明确。
21.2 费用项
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "CostItem",
"type": "object",
"additionalProperties": false,
"required": ["id", "category", "label", "unit", "quantity", "unitPriceFen", "priceStatus", "includedInBudget", "resourceRef", "evidenceIds"],
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 160 },
"category": { "enum": ["intercity", "lodging", "food", "local", "ticket", "experience", "other"] },
"label": { "type": "string", "minLength": 1, "maxLength": 200 },
"unit": { "enum": ["person_leg", "room_night", "person", "group"] },
"quantity": { "type": "integer", "minimum": 1, "maximum": 10000 },
"unitPriceFen": { "type": ["integer", "null"], "minimum": 0, "maximum": 1000000000 },
"priceStatus": { "enum": ["quoted", "reference", "estimated", "target", "unknown"] },
"includedInBudget": { "type": "boolean" },
"resourceRef": { "type": ["string", "null"] },
"evidenceIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
},
"allOf": [
{
"if": { "properties": { "priceStatus": { "const": "quoted" } } },
"then": { "properties": {
"unitPriceFen": { "type": "integer" },
"resourceRef": { "type": "string", "minLength": 1 },
"evidenceIds": { "minItems": 1 }
} }
},
{
"if": { "properties": { "priceStatus": { "const": "unknown" } } },
"then": { "properties": { "unitPriceFen": { "type": "null" } } }
},
{
"if": { "properties": { "priceStatus": { "enum": ["reference", "estimated", "target"] } } },
"then": { "properties": { "unitPriceFen": { "type": "integer" } } }
}
]
}
资源和证据引用是否存在、是否匹配日期与人数、是否过期,由运行时校验。目标金额即使全部结构合法,仍不能证明真实费用已核实。
21.3 分享创建请求
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "CreateTripShareRequestV1",
"type": "object",
"additionalProperties": false,
"required": ["schemaVersion", "requestId", "sourceServerVersion", "expiresInDays"],
"properties": {
"schemaVersion": { "const": 1 },
"requestId": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" },
"sourceServerVersion": { "type": "integer", "minimum": 1 },
"expiresInDays": { "type": "integer", "minimum": 1, "maximum": 30 }
}
}
请求不接受 owner、snapshot、核验状态或 shareToken;正文由服务端按归属读取存档生成。版本比较、幂等冲突、软删除及证据新鲜度由服务端规则处理。
21.4 展示契约的元数据 Schema
下面是 TravelPlanPresentationV1 的独立元数据子契约,供版本、新鲜度与只读模式测试;不是整份攻略 Schema。完整 overview、transportAndStay、days、budget、entities、sourceSummaries 与 notices 的有界 Schema 在 GT-002 定义,并由 GT-036 做跨端一致性检查。
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TravelPlanPresentationMetadataV1",
"type": "object",
"additionalProperties": false,
"required": ["presentationVersion", "sourceServerVersion", "mode", "generatedAt", "viewedAt", "validatedAt", "usableUntil", "statusAtValidation", "effectiveStatus"],
"properties": {
"presentationVersion": { "const": 1 },
"sourceServerVersion": { "type": "integer", "minimum": 1 },
"mode": { "enum": ["owner", "shared_readonly"] },
"generatedAt": { "type": "string", "format": "date-time" },
"viewedAt": { "type": "string", "format": "date-time" },
"validatedAt": { "type": "string", "format": "date-time" },
"usableUntil": { "type": ["string", "null"], "format": "date-time" },
"statusAtValidation": { "enum": ["provisional", "verified"] },
"effectiveStatus": { "enum": ["provisional", "verified"] }
}
}
有效期、必要证据和结构校验决定 effectiveStatus,不能由请求自报;当前时刻超过有效期时不能保持 verified。infeasible 属于冲突解释而非可分享攻略。未保存预览使用单独本地信封,sourceServerVersion=null,不满足上述已保存展示子契约,也不能提交分享创建。
22 回放与文档验证
22.1 回放清单
每次验收保存去标识的输入、需求确认结果、资源快照、模型响应和执行结果,并记录版本。生产默认日志不自动采集这些正文;评测快照使用人工场景或具有授权的数据。
{
"schemaVersion": 1,
"mode": "offline_fixture",
"requestHash": "fixture-input-hash",
"planningNow": "2026-10-12T12:00:00+08:00",
"timezone": "Asia/Shanghai",
"resourceSnapshotIds": ["fixture-transport", "fixture-hotel", "fixture-routes"],
"plannerVersion": "grounded-v1",
"policyVersion": "relaxed-v1",
"promptVersion": "grounded-compose-v1",
"modelVersion": "recorded-response",
"tieBreaker": "stable_entity_and_candidate_ids"
}
示例时刻是测试冻结时刻,不是实际查询时间。离线回放固定模型响应和资源快照,确定性规划结果应一致。相同模型和 temperature 不能保证文本逐字相同;逐字回放应使用保存的输出。
22.2 最小可执行预算回归
此代码仅验证文档中的日期和预算夹具,不调用供应商,不代表完整业务已经实现。
from datetime import date
budget_fen = 200_000
reserve_fen = 10_000
items = {
"rail": (28_500, 4),
"hotel": (24_000, 1),
"food": (38_000, 1),
"tea": (6_000, 1),
"local": (8_000, 1),
}
def occupied_fen(costs):
return sum(price * quantity for price, quantity in costs.values()) + reserve_fen
assert occupied_fen(items) == budget_fen
assert date(2026, 10, 17).weekday() == 5
assert date(2026, 10, 18).weekday() == 6
assert occupied_fen({**items, "rail": (30_000, 4)}) == 206_000
assert occupied_fen({**items, "hotel": (35_000, 1)}) == 211_000
assert occupied_fen({**items, "rail": (30_000, 4), "hotel": (35_000, 1)}) == 217_000
print("文档日期与预算夹具通过")
完整验收还需要前述资源、路线、协议、数据库、模型和手机各层测试,不能以这段预算回归代替。
23 实施前需要落实的条件
| 条件 | 当前处理 | 对首条链路的影响 |
|---|---|---|
| FlyAI 当前 Key 和权益 | 沿用现有注入路径,实施时验证 | 未证实不能声称真实查询接通 |
| 高德 Web Key 和权益 | 后端独立配置,实施时验证 | 缺失时路线和天气未配置 |
| 用户提供的高德两类 Key | 截图类型已辨认,正文不入文档;未配置和未调用 | Web 服务 Key 对接后端,小程序 Key 不替代 Web 服务权限 |
| 酒店完整报价、房型和库存 | 校验实际返回,缺项降级 | 裸展示价只能支持参考攻略 |
| 营业预约覆盖 | 官方或授权来源逐点验证 | 未覆盖地点保持待核实 |
| 资源保存与使用条件 | 供应商接入时确认并落实清理 | 决定快照留存和恢复能力 |
| 分享内容保存与展示权利 | 逐供应商确认,白名单裁剪和默认封面 | 无权对外展示的字段或素材不进入快照 |
| 分享令牌加密与匿名只读例外 | 由 GT-001/GT-038 落实规格及后端环境 | 不修改现有身份接口,不把投票邀请当攻略授权 |
| V2 兼容与回滚 | 双版本测试后再发布 | 防止旧客户端覆盖新数据 |
| 轻松参数 | 先按本文默认值评测 | 参数是产品策略,不是事实 |
| 真实评测批次 | 每次明确测试数量及费用范围 | 本文不增加付费测试授权 |
这些条件不妨碍先落实契约和离线测试,但必须与真实接通及发布结论分开。
24 项目依据
24.1 架构与当前规格
24.2 当前源码与验收
- 需求模型
- 对话及草案契约
- 费用类型
- 现有方案生成
- 现有详细行程生成
- Aggregate 存档类型
- 前端对话调用
- 后端现有证据结构
- 后端模型适配器
- 后端运行组装
- 条件与草案一致性验收
- 地点选择及生成保存验收
- 当前辅助条件编辑
- 当前对话快捷卡
- 现有投票邀请分享
- 现有行程 JSON 存储
当前源码是能力存在的依据,验收记录仅支持其明确测试过的范围。历史阶段记录和供应商文档不证明本方案已经实施或上线。