城市出行智能准备 APP

按 城市出行智能准备APP_Vibe_Coding_PRD.md 实现的 MVP。当前版本优先完成 P0 主路径：

• 一句话输入 / 场景卡片
• 出行上下文解析与补全
• 规则版三层清单生成
• SQLite 持久化清单资产
• 清单勾选、添加、删除、推荐理由详情
• 删除高影响物品反馈
• 历史清单与复用
• 24h 轻核对

本地运行（新电脑从零开始）

APP 真实链路依赖两类外部命令：flyai（机票 + 周边逛吃/纪念品）和 curl（天气，macOS/Linux 自带）。这两类命令必须在启动 pnpm dev 的终端所在 PATH 里能找到，否则对应功能会静默走兜底/空结果，不会报错崩溃。

1. 安装 FlyAI CLI（APP 运行时依赖，必需）

npm i -g @fly-ai/flyai-cli
hash -r
command -v flyai   # 应输出 flyai 的路径
flyai --help       # 应列出 search-flight / ai-search 等子命令

注意区分两件不同的事：

• npm i -g @fly-ai/flyai-cli 安装的是 APP 运行时用 child_process 调用的 flyai 命令；
• npx skills add alibaba-flyai/flyai-skill 安装的是给 Codex / Claude Code 等 Agent 识别的 Skill，与 APP 能否调用 flyai 无关。 即使 Agent 已经装了 Skill，只要 Node 进程的 PATH 里找不到 flyai 命令，APP 依然查不到真实机票和周边逛吃结果。

如果你在 Codex / Claude Code 里也想让 Agent 自己识别 FlyAI Skill（与 APP 无关，可选）：

npx skills add alibaba-flyai/flyai-skill

2. 安装依赖、初始化数据库

cp .env.example .env
pnpm install
pnpm prisma:generate
pnpm db:init
pnpm prisma:seed
pnpm rail-delta:import   # 导入火车/高铁站点知识库，会打印匹配到的 12306 站点数量

3. 启动（务必在装好 flyai 之后再启动，或重启）

pnpm dev

重要：如果你是先启动了 pnpm dev、再安装的 flyai，必须先停掉旧的 pnpm dev 进程再重新执行 pnpm dev。Node 进程的 PATH 是进程启动时就固定的，全局装完新 CLI 后不会被正在运行的旧进程感知到，热更新也不会刷新 PATH。

访问：

http://localhost:3000

（如果 3000 端口被占用，Next.js 会自动改用 3001，以终端打印的实际地址为准。）

4. 可选 fallback（不装也不影响主链路）

火车票默认走内部 12306 provider（internalRail，纯 fetch，不需要额外安装任何命令）。以下命令属于可选 fallback，仅在主链路查询失败时才会被尝试；不安装也不影响火车票、飞机票、周边逛吃、天气这几条主链路：

# ModelScope rail skill（火车票的可选备用 provider）
# 需要先安装 modelscope CLI 并按官方文档登录

# Fliggy MCP / Meituan MCP（结构化交通与地点查询的可选备用 provider）
pipx install uv   # 或 brew install uv，二选一，装好后 uvx 命令可用

5. 逐项验证真实链路（绕过 APP 直接测试底层命令）

flyai ai-search --query "帮我查一下济南泉城广场有啥好吃的吗？"
flyai search-flight --origin "北京" --destination "上海" --dep-date 2026-07-15
curl "https://wttr.in/济南?format=j1&m"
pnpm rail-delta:import   # 检查 matched_seed_count 是否等于 imported.rail_station，unmatched 是否为空

完整的模块调用链路图和每个能力的默认/可选状态表见 docs/SKILL_CALL_GRAPH.md。

说明

• 数据库使用 prisma/dev.db，配置见 .env.example。
• 首次 clone 后先复制环境变量模板：cp .env.example .env。模板不包含真实 API key。
• .env.example 默认启用真实查询链路：火车/高铁走内部 12306 provider，周边逛吃/纪念品/航班走 FlyAI，天气走 wttr.in skill。
• FlyAI 不会随仓库安装。新电脑需要先按飞猪 FlyAI 文档安装并登录 CLI，确认 flyai --help 可用后，PLACE_PROVIDER="fliggy" 和 TRAVEL_PROVIDER="fliggy" 才能返回真实结果。
• 如果只想离线验证产品主路径，可以把 WEATHER_PROVIDER、TRAVEL_PROVIDER、TRANSPORT_PROVIDER、PLACE_PROVIDER 改回 mock。
• 当前 AI 清单生成先用 src/lib/generation.ts 里的稳定规则实现，方便先验证产品主路径。
• 后续接真实 OpenAI/天气 API 时，优先替换生成链路，不需要重写页面和数据模型。
• 如果 prisma db push 在本机环境失败，可用 pnpm db:init 创建与 Prisma schema 对齐的 SQLite 表。
• 火车票查询已把 ModelScope @jinfanzheng/rail 的核心能力内部化为 internalRail provider：后端直接读取 12306 站点码并查询 12306 余票接口，订单和支付仍跳转 12306/携程。设置 TRANSPORT_PROVIDER="internalRail" 可显式启用；未指定 provider 时，火车查询默认优先走内部 12306，失败再兜底到外部 rail/美团/飞猪配置。
• 铁路城市到站点映射来自 china_rail_geo_kb_delta_only/。首次初始化后运行 pnpm rail-delta:import，会只新增 rail 表、导入 CSV，并从 12306 station_name.js 同步 telecode/pinyin/query_allowed；不会删除或重建机场/行政区划数据。
• 交通查询设置 TRANSPORT_PROVIDER="fliggy" 或 TRAVEL_PROVIDER="fliggy" 后，航班会走 FlyAI Skill CLI；默认命令为 flyai search-flight，可用 FLYAI_CLI_COMMAND 和 FLYAI_CLI_TIMEOUT_MS 调整。
• 周边逛吃/纪念品查询会把用户原始自然语言传给 FlyAI ai-search，并把自然语言回答直接展示为推荐内容卡；可用 FLYAI_PLACE_TIMEOUT_MS 调整等待时间。
• 天气查询设置 WEATHER_PROVIDER="skill" 后，会按 ModelScope / ClawHub @steipete/weather skill 的 primary 方案调用 curl https://wttr.in/<目的地>?format=j1&m，无需天气 API key；wttr.in 只返回当前和近几天预报。