技术接入

把“怎么接入”和“技术接口”放在同一条执行链里。

接入页不做后台控制台，也不做堆满参数的文档页。它解释从安全预览到增强读取、再到受控写入的路径，以及每个接口在成行包里的位置。

看 API 主链路回到商家价值

增强读取优先先规划，再确认，最后执行预览或受控写入。

用户说：今天下午带孩子在望京少走路，雨天室内，晚餐清淡，帮我搞定。

POST/api/plan只规划，不写入01

POST/api/confirm确认门禁02

POST/api/execute回执输出03

Access modes

接入分三档，不把未授权能力包装成真实履约。

旧文档里的安全预览、增强读取、受控执行边界重新写成官网里的接入路径：每一档都明确能读什么、能不能写、失败时怎么显示。

Preview

安全预览

用于演示、验收和没有外部授权的场景。

可以跑完整成行包，但预约、取号、支付、分享等写动作只生成安全回执，不产生外部副作用。

Enhanced read

增强读取

授权天气和已配置服务优先读取，缺口保持可解释预览。

适合商家试点：先看授权供给、排队、票券或路线读数，再决定哪些写动作进入受控测试。

Controlled write

受控执行

只在授权、密钥、商家 ID、幂等和健康检查齐备后开启。

写动作仍受用户确认和运行版本校验保护；供给变化导致方案变更时必须重新确认。

API X-ray board

鼠标移到原生成行包模块上，看背后的接口骨架。

这里直接放原生成行包模块：顶部、主卡、路线、商家、TimeBank 和底部动作都保持官网演示的样子。移动到任一模块上，右侧说明它对应的 API、服务和确认门禁。

北京望京今天下午

小雨 22°亲子少走路

Live package demo

下午这样走最省心

亲子友好 · 少走路 · 不久等 · 清淡晚餐

4.5 小时14:00-18:30

1.8 km距离

中风险可先取号

¥140人均预计

步行 8 分钟 · 600m地铁 6 分钟 · 1.2km

14:00 出发望京 SOHO · 童趣探索馆室内避雨

16:00小熊轻食研究所休息+餐饮

18:30 结束望京小街散步轻松收尾

望京 SOHO · 童趣探索馆

★ 4.83.2万条望京 SOHO

儿童友好少走路室内场馆可先取号

当前排队约 15 分钟

门票¥58起~~¥88~~

望京 SOHO · 小熊轻食研究所

★ 4.71.8万条望京 SOHO

儿童椅少等候清淡菜品团购可用

当前排队约 38 分钟

2-3 人套餐¥198起~~¥238~~

TimeBank · 等位 38 分钟可顺路做什么更多方案 ›

商场室内咖啡休息约 15 分钟

室内儿童乐园约 25 分钟

亲子书店约 20 分钟

甜品店小憩约 15 分钟

路线已合并写动作待确认分享卡可发送

.packageTopbar

城市、时间、天气、安全预览

对应顶部城市、时段、天气 chip 和亲子少走路安全预览。

API / tool: POST /api/plan + GET /api/plan-stream
服务: 城市上下文、天气服务、语义解析、运行时服务
Guardrail: 只生成 planning context；未接天气时显示待接或安全预览。

.packageHeroCard

标题和四个关键指标

总时长、距离、排队风险和人均预算来自同一个成行草稿。

API / tool: runPlanning() → arrangementDraftPackage + planFingerprint
服务: scoring-explain、budget compose、transport estimate、readiness
Guardrail: 指标是草稿摘要；供给变化会生成 runtime patch 并要求重新确认。

.packageRouteCard

路线 rail 和三段停靠

出发、活动、餐厅、收尾和转场距离被排成一条链。

API / tool: 统一服务接口 route + lib/timebank/transport-estimate
服务: 地图 / 路线服务、城市上下文、POI 坐标
Guardrail: 路线只作为约束参与排序；超时或绕路会触发 replan。

.packageMerchantCard

活动卡和餐厅卡

评分、评论、标签、排队、门票、套餐和按钮来自供给抽屉。

API / tool: 统一服务接口 POI / 可用性 / 排队 / 票券 / 优惠
服务: 安全预览服务或合作服务；平台健康检查暴露接入状态。
Guardrail: source、realness、callable 必须可见；预览按钮不能伪装成外部下单。

.packageTimebankCard

TimeBank 等位利用

把 38 分钟等位拆成咖啡、儿童乐园、书店、甜品等可顺路时间片。

API / tool: lib/timebank/timebank-allocation + plan_cascade
服务: queue forecast、addon search、nearby POI、walking buffer
Guardrail: 加购和替换只是待确认草稿；长队或售罄必须重新规划。

.packageBottomBar

换一版、帮我搞定、分享

底部按钮对应重排、确认执行和分享预览三类写动作。

API / tool: POST /api/confirm → POST /api/execute → POST /api/share-feedback
服务: 批量预订、分享发送、票券 / 加购 / 订座服务
Guardrail: confirmedArrangementId、fingerprint、幂等字段和服务回执缺一不可。

Developer path

真正接入时，开发者需要先搞懂三件事。

旧文档里的 API、运行模式、环境变量和健康检查被整理成开发者路径：先跑通计划链路，再接服务，最后只在门禁齐备时打开写动作。

跑通主链路

先用 /api/plan、/api/confirm、/api/execute 验证草稿、确认和回执形状。

规划接口不会预约或取号；execute 缺确认会返回 CONFIRMATION_REQUIRED。

替换服务

把安全预览服务换成授权 POI、库存、排队、票券、菜单或加购服务。

统一服务接口的输入输出保持同形，授权服务返回安全预览标记会被拒绝。

打开受控写入

只有 OAuth、商家标识、幂等字段、健康检查和确认凭证齐备后才允许写动作。

供给变化导致 package fingerprint 变化时，必须重新确认新的 runtime draft。

Required knobs

服务接入TIMEBANK_ADAPTER

安全预览 / HTTP / 平台接入，决定工具适配层。

ModeTIMEBANK_OPERATION_MODE

安全预览 / 增强读取 / 受控执行，默认从增强读取开始。

ConfirmTIMEBANK_CONFIRMATION_SECRET

签发无状态 confirmedArrangementId。

服务*_PROVIDER_URL

库存、票务、菜单、加购、分享等外部服务。

API chain

公开接口围绕成行包主链路组织，而不是散装工具列表。

这里适合给技术、BD 和试点商家共同看：每个接口都说明它在规划、确认、执行、分享和回执中的职责。

POST01

/api/plan

规划成行草稿

把自然语言目标解析成约束、候选、路线、评分、TimeBank 和待确认成行包。

只规划，不写入

POST02

/api/confirm

签发确认状态

校验 package、fingerprint、确认 token 和多人共识，签发可执行的确认凭证。

确认门禁

POST03

/api/execute

生成执行回执

确认后调用受控工具；未配置真实写端点时返回安全预览回执。

回执输出

POST04

/api/share-feedback

同行反馈局部重排

接收不想等、想换餐厅、延后、清淡等反馈，只更新受影响段落。

仍需再确认

GET05

/api/plan-stream

流式规划阶段

输出 parsed、searched、ranked、done 等阶段，用于前端展示规划过程。

只读流

Service boundary

技术接入重点是边界清楚，不是把所有工具都说成已生成。

平台开放能力、统一服务接口、健康检查和写动作门禁都可以放在同一页里；过深的参数表后续再拆 API reference。

Service v1

统一服务边界

POI、可用性、排队、路线、优惠、票券、菜单、加购等读取能力走统一服务形状。

安全预览服务和授权合作服务保持相同契约，未来替换 base URL 和授权即可复用产品链路。

Write guard

外部副作用必须受控

取号、预约、票券、加购、分享都要通过用户确认、幂等字段和服务回执。

受控写入需要明确配置开关、商家授权和必需标识；缺字段时健康检查报告缺配置。

Health

上线前先看健康状态

集成健康、平台服务健康、安全预览服务和模型健康分别说明当前能力边界。

健康检查不只是连通性，还要告诉页面哪些服务是授权读取、哪些仍是安全预览。

Readiness

试点前只看三件事。

授权商家 OAuth

确认 developerId、signKey、appAuthToken 或 partner token 的云端配置。

健康readyForLive

检查 /api/integration-health、/api/meituan/health 和服务探针。

写入确认门禁

没有用户确认、幂等字段和回执时，页面只能显示预览。