Skip to content
 
 

Latest commit

 

History

467 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

moyuan-travel-agent

Next.js React FastAPI LangGraph TypeScript Docs

moyuan-travel-agent 是一个面向真实旅行决策场景的 AI 旅行助手项目,覆盖“问问题 -> 生成方案 -> 调整预算/约束 -> 对比方案 -> 导出分享”的完整链路。

它不是只输出一段长文本,而是尽量把旅行建议整理成可继续操作的结构化结果:每日行程卡、预算联动、候选城市探索、对比模式、冲突检测、导出图片与分享链接。

目录

快速演示

Quick Demo

产品预览

1. 对话与流式执行

对话页

2. 城市探索与决策卡片

城市探索

3. 行程工具箱与结果整理

行程结果

当前核心能力

对话与 Agent

  • 三种对话模式:directreactplan
  • SSE 流式输出:阶段、工具调用、推理片段、最终答案、执行元数据
  • 会话管理:新建、清空、删除、重命名、切换模型
  • 高风险问题保护:时效校验、fallback 标记、可信度与风险提示

行程结果增强

  • 长文本自动拆成每日行程卡
  • 行程卡内置预算展示、路线信息、时间段结构化展示
  • 预算滑杆:省钱 / 均衡 / 舒适
  • 多方案对比:并排比较后继续细化
  • 冲突检测:时间冲突、路程过长、闭馆风险,并给出一键修复建议
  • Checklist、出发提醒、可信度条、风险提示
  • 结果导出:图片长图、分享短链

城市探索

  • 100+ 城市探索池(当前内置 150+)
  • 快速筛选:周末、预算、亲子、少走路、雨天、美食
  • 场景入口:周末快闪 / 亲子省心 / 预算吃好
  • 城市卡片决策信息:预算强度、步行强度、风格标签、推荐理由
  • shortlist、收藏池、对比池与详情抽屉:先收集候选,再进入并排对比
  • 一键以某座城市继续生成完整旅行方案

地图与路线

  • 支持真实路线距离预览
  • 行程卡中可触发“真实路线”与“按距离重排”
  • 当前路线能力基于高德方案接入

北京旅游数据 Demo

feature/hotel-data-demo-ready 合入后,仓库同时包含一个北京旅游数据工作台 demo。它基于本地 POI、酒店、餐饮、文化地点、UGC 评论特征、高德通勤补全数据和预生成路线库,提供可解释、可调整的北京本地路线规划能力。

核心入口:

  • 根目录 Next.js 工作台:src/app/
  • 旅游规划 API:src/app/api/v1/travel/
  • 数据平台页面:/data-platform
  • 旅游规划逻辑:src/lib/travel/
  • 本地数据:travel-data/processed/travel-data/wiki/
  • 数据库脚本:scripts/travel/sqls/

主要能力:

  • 自然语言解析成结构化区域、时长、预算、餐饮和偏好约束
  • 优先命中 PostgreSQL 中的 travel_precomputed_routes 预生成路线库
  • 支持从本地 POI、酒店、UGC 和 Wiki 数据兜底检索
  • 支持追加、删除、替换、保留地点等动态重规划
  • 支持通勤边补全与高德 API 离线回填

快速启动 demo:

npm install
cp .env.example .env
npm run db:up
npm run travel:db:seed
npm run travel:db:doctor
npm run dev

默认访问:

http://localhost:33003

技术栈

  • Frontend: Next.js 16 + React 19 + TypeScript + antd
  • Backend API: FastAPI
  • Agent: LangChain + LangGraph
  • Model: mimo-v2.5-pro(MiniMax Anthropic 兼容接口)
  • Data demo: PostgreSQL + Prisma + root Next.js workspace

Docker 数据库导入

docker-compose.yml 会启动一个 PostgreSQL 16 容器,默认配置来自 .env

DATABASE_URL="postgresql://travelpilot:<replace-with-local-password>@127.0.0.1:5432/travelpilot?schema=public"
POSTGRES_DB="travelpilot"
POSTGRES_USER="travelpilot"
POSTGRES_PASSWORD="<replace-with-local-password>"
POSTGRES_PORT=5432

完整导入流程:

# 1. 启动 PostgreSQL 容器
npm run db:up

# 2. 建旅游数据表,包括 POI、UGC、通勤边、语义日志、预生成路线库
npm run travel:db:init

# 3. 从 travel-data/processed 生成预计算路线库 JSON
npm run travel:routes:build

# 4. 将 POI、UGC、评论、区域和预生成路线导入 PostgreSQL
npm run travel:db:import

# 5. 检查表和数据量
npm run travel:db:doctor

也可以直接使用合并命令:

npm run travel:db:seed

导入完成后,关键数据会保存在 Docker PostgreSQL 的这些表中:

内容
travel_pois 北京 POI、餐厅、文化地点、基础评分、营业时间和标签
travel_poi_features UGC 聚合特征,例如排队风险、性价比、亲子友好度
travel_reviews 本地评论/证据文本
travel_areas 区域汇总
travel_commute_edges 景点和餐饮点之间的通勤边
travel_precomputed_routes 预生成旅行路线,运行时优先命中后直接返回前端

可以用下面的命令确认路线库已经入库:

docker compose exec postgres psql -U travelpilot -d travelpilot \
  -c "SELECT COUNT(*) FROM travel_precomputed_routes;"

当前路线链路是:

用户自然语言
  -> mimo-v2.5-pro 解析结构化 intent
  -> 后端将 intent 转成受控 SQL 查询
  -> 优先命中 travel_precomputed_routes
  -> 直接返回 planning_response.proposals 给前端渲染

大模型不直接生成 SQL 字符串,也不负责实时生成完整路线;SQL 查询由后端模板和参数控制。

项目结构

moyuan-travel-agent/
├── .github/              # GitHub workflows、仓库治理入口与平台识别文件
├── .editorconfig         # 编辑器编码、换行与缩进规范
├── .gitattributes        # Git 文本归一化与二进制文件策略
├── agent/                 # Agent 图、节点、工具、记忆、checkpoint
├── backend/               # FastAPI 路由、服务、仓储、配置
├── frontend/              # Next.js 前端
├── src/                   # 北京旅游数据 demo 的根目录 Next.js 工作台
├── extend/                # 观测可视化等扩展能力
├── deploy/                # Compose、Dockerfile、migration、安全扫描等发版资产
├── docs/                  # 文档中心
├── prisma/                # demo 数据库 ORM schema
├── sqls/                  # 北京旅游数据表与路线库 SQL
├── travel-data/           # 北京 POI、酒店、UGC、路线语料与 Wiki
├── tests/                 # 后端/集成测试
├── scripts/               # benchmark / replay / quality gate 等脚本和跨平台开发入口
├── data/                  # 本地运行数据
├── package.json           # 根目录 demo 工作台脚本
├── pyproject.toml         # 根目录 pytest / mypy / Ruff 统一工具配置
├── requirements-dev.txt   # 本地开发与静态检查依赖
└── requirements.txt       # 运行时依赖与安全审计输入

当前维护基线只需要先记住 5 条:

  • 前端主链已经收口成 workspace 结构:ChatArea.tsxMessageList.tsxTravelPlanToolkit.tsxCityExplorer.tsx 负责装配,细节分别下沉到 chat-area/message-list/travel-plan-toolkit/city-explorer/
  • 前端 API 入口已经收口成目录化 client:frontend/src/services/api.ts 只保留聚合导出,真实 endpoint client 位于 frontend/src/services/api/,artifact 历史读取走 artifactClient.ts
  • Backend 与脚本入口已经统一:backend/moyuan_web/bootstrap.pyscripts/bootstrap_paths.py 负责 repo root / backend/ 导入准备,scripts/dev.py 是本地开发、回归、容器和运维统一入口。
  • Agent 运行时主链已经固定:AgentRuntime -> runtime_driver -> runtime_flow -> runtime_sources / runtime_event_emitters;skills market、execution receipt、tool health diagnostics 都通过显式 contract 暴露。
  • 运维与治理已经收口:runtime_doctor / support bundle / release manifest / release harness scorecard 共用 typed ops contracts,默认门禁由 docstring / complexity / decision-records / skills-market / runtime-contracts 组成。

高频维护入口:

场景 最短入口
前端聊天与 artifact UI frontend/src/components/chat-area/frontend/src/components/message-list/frontend/src/components/travel-plan-toolkit/
Backend API 与持久化 backend/moyuan_web/routes/backend/moyuan_web/services/backend/moyuan_web/repositories/backend/config/
Agent runtime 与 graph agent/travel_agent/runtime/agent/travel_agent/graph/agent/travel_agent/contracts/
本地命令与运维脚本 scripts/dev.pyscripts/runtime_*scripts/export_*
发版与容器资产 deploy/compose/deploy/docker/deploy/migrations/deploy/security/

根目录规范也已经收口到当前布局:

  • Python 工具链统一放在 pyproject.toml
  • migration 配置下沉到 deploy/migrations/
  • 仓库治理资产放在 .github/
  • 发版与安全资产放在 deploy/
  • .venv 保留在根目录,pytest / mypy / Ruff 缓存统一放到 .cache/

更细的目录说明看 docs/reference/project-structure.md,运行与部署约束看 docs/architecture/infrastructure-foundations.md

本地访问地址

  • Frontend: http://localhost:33003
  • API: http://localhost:38083
  • API Docs: http://localhost:38083/rapidoc
  • Health: http://localhost:38083/api/health
  • Ready: http://localhost:38083/api/ready
  • Metrics: http://localhost:38083/api/metrics
  • Prometheus: http://localhost:39090 (observability profile)
  • Grafana: http://localhost:33002 (observability profile)

快速开始

1. 准备环境

  • Python 3.13+
  • Node.js 20+
  • uv
  • npm
  • Docker / Docker Compose(可选,但推荐用于联调)

2. 安装依赖

python scripts/bootstrap.py

安装完成后,建议先看一眼统一命令入口:

python scripts/dev.py help
python scripts/dev.py backend-dev
python scripts/dev.py frontend-dev

3. 准备配置

python scripts/bootstrap.py --skip-frontend

根据实际模型服务填写 api_keyapi_basemodel

server_config.yaml 负责统一:

  • web.host / web.port
  • frontend.port
  • cors_origins
  • request_timeout_seconds
  • rate_limit_max_requests
  • metrics_enabled / metrics_path
  • structured_logging
  • fail_fast_validation

如果只是运行服务、完全不做开发,也可以只安装:

uv pip install -r requirements.txt

4. 启动后端

python scripts/dev.py backend-dev

5. 启动前端

python scripts/dev.py frontend-dev

6. 开始体验

  1. 打开 http://localhost:33003
  2. 选择模型与对话模式
  3. 在“行程约束”里补充亲子/预算/无车等前置条件
  4. 输入旅行需求,等待流式生成
  5. 在结果区继续调整预算、查看多方案、检测冲突、导出图片或分享

更完整的启动说明见 docs/getting-started/quick-start.md

6.1 常用统一命令入口

python scripts/dev.py backend-dev
python scripts/dev.py frontend-dev
python scripts/dev.py test
python scripts/dev.py infra-check
python scripts/dev.py compose-config
python scripts/dev.py container-smoke

6.2 北京旅游数据 demo 常用命令

npm run dev
npm run build
npm run lint
npm run type-check

npm run db:up
npm run db:down
npm run db:init
npm run db:doctor
npm run db:psql

npm run travel:db:init
npm run travel:routes:build
npm run travel:db:seed
npm run travel:db:import
npm run travel:db:doctor
npm run travel:wiki:build
npm run travel:amap:backfill

说明:

  • test: 后端 unit/local + 前端 lint/test/build
  • infra-check: ruffmypydocstringcomplexity budgetdecision records、runtime doctor、契约快照、release harness scorecard、release manifest,以及在 Docker 可用时附带 compose 渲染校验 同时会执行 runtime_contract_audit --strict,固定 supervisor/runtime seam 的显式 contract 当前 runtime_doctor 遇到被占用的 runtime 文件会返回 degraded 检查项,而不是直接中断整条治理链
  • compose-config: 渲染默认和 observability profile 的 Compose 配置
  • container-smoke: 本地构建 backend / frontend 镜像

7. Docker Compose 启动

如果想以统一的前后端容器方式联调,优先使用根目录 Compose:

docker compose --file deploy/compose/compose.yaml up --build

如果想连同 Prometheus 和 Grafana 一起启动本地观测栈:

docker compose --file deploy/compose/compose.yaml --profile observability up --build

如果当前网络拉取 Docker Hub 基础镜像较慢,可以直接切到镜像站:

python scripts/dev.py compose-up \
  --python-base-image "5ykpmdvdg6to97.xuanyuan.run/library/python:3.13-slim" \
  --node-base-image "5ykpmdvdg6to97.xuanyuan.run/library/node:22-alpine"

如果只想验证本地镜像构建:

python scripts/dev.py container-smoke \
  --python-base-image "5ykpmdvdg6to97.xuanyuan.run/library/python:3.13-slim" \
  --node-base-image "5ykpmdvdg6to97.xuanyuan.run/library/node:22-alpine"

相关资产:

常用接口

Chat

  • POST /api/chat/stream

请求示例:

{
  "message": "请给我一个上海周末两日游建议,预算 1500 元以内",
  "session_id": "optional-session-id",
  "mode": "react"
}

Session

  • POST /api/session/new
  • GET /api/sessions
  • PUT /api/session/{session_id}/name
  • PUT /api/session/{session_id}/model
  • DELETE /api/session/{session_id}
  • POST /api/clear?session_id=...

Artifacts

  • GET /api/artifacts/{session_id}/latest
    • 前端 session restore 会优先用它补齐 persisted artifact,避免刷新后只能回退到纯文本恢复
  • GET /api/artifacts/{session_id}/history?limit=10
    • 返回当前 session 中 newest-first 的 artifact 快照列表;现在 compare/history UI 会直接消费这条 contract,不再继续扫描原始 session messages 来拼对比方案

Share Links

  • POST /api/share-links
    • 现在会同时持久化兼容字段 title / content / html_content 和结构化 delivery_bundle,把 artifact + executionReceipt + htmlContent + share 元数据一次性落盘
  • GET /api/share-links/{share_id}
    • 现在会优先把持久化 delivery_bundle 回放给前端 share/session hydration,使分享页继续走 artifact-first 渲染,而不是只剩 raw assistant text

City Explorer

  • GET /api/cities
  • GET /api/cities/{city_id}
  • GET /api/cities/{city_id}/attractions
  • GET /api/regions
  • GET /api/tags

Health

  • GET /api/health
  • GET /api/health/llm
  • GET /api/health/tools
  • GET /api/health/tools/intents
  • GET /api/ready
  • GET /api/live
  • GET /api/metrics

完整接口说明见 docs/reference/api-reference.md

部署与观测

readiness 与启动校验

后端启动时会执行真实 startup checks,并把结果暴露到 /api/ready。当前会检查:

  • server_config 是否可解析
  • data/ 是否可写
  • llm_config 是否存在且至少有一个 active model
  • 依赖容器能否 resolve
  • Chat runtime 是否能初始化

如果希望启动失败时直接退出,可设置:

set MOYUAN_FAIL_FAST_STARTUP_VALIDATION=true

request_id / trace_id

前端 REST 与 SSE 请求都会自动携带:

  • X-Request-ID
  • X-Trace-ID

后端会把它们写入:

  • 响应头
  • 结构化日志
  • SSE payload 的 request_id / trace_id

runtime doctor

运行维护时,推荐先跑一遍:

python scripts/dev.py runtime-doctor --runtime-doctor-json
python scripts/dev.py runtime-doctor --base-url http://localhost:38083 --runtime-doctor-strict
python scripts/export_runtime_doctor_snapshot.py

它会检查:

  • backend/config/server_config.yaml / backend/config/llm_config.yaml
  • data/ 可写性与运行态文件
  • 备份归档目录
  • OpenAPI / SSE 契约快照
  • 可选的 live /api/health/api/ready/api/metrics

Prometheus metrics

当前默认暴露:

  • GET /api/metrics

主要指标包括:

  • moyuan_http_requests_total
  • moyuan_http_request_duration_seconds
  • moyuan_http_in_flight_requests
  • moyuan_chat_stream_requests_total
  • moyuan_sse_events_total
  • moyuan_readiness_state

测试与质量

前端

cd frontend
npm run lint
npm run test:run
npm run build

当前前端默认验证入口已经做过跨平台稳定化处理:

  • npm run test:run 会通过 frontend/vitest.config.tsvitest worker 数限制为 2
  • npm run build 默认走 next build --webpack,避免当前 Next.js 16 默认构建路径在部分本地环境里出现 worker init 失败
  • python scripts/dev.py test / infra-check 现在会在 Windows 上自动解析 npm.cmd,不再因为 subprocess 直接找 npm 而中断

后端

python scripts/dev.py backend-test --pytest-slice unit
python scripts/dev.py backend-test --pytest-slice local
python scripts/dev.py backend-test --pytest-slice runtime
python scripts/dev.py backend-test --pytest-slice ops
python scripts/dev.py ruff
python scripts/dev.py mypy
python scripts/dev.py docstring
python scripts/dev.py complexity
python scripts/dev.py decision-records
python scripts/dev.py skills-market
python scripts/dev.py runtime-contracts
python scripts/dev.py snapshots

其中 python scripts/docstring_audit.py --strict 当前会同时检查两类问题:

  • 缺失 docstring
  • 新增低信息量 docstring(历史存量由 docs/reference/docstring-audit.low-info-baseline.json 管理)
  • 热点文件超出复杂度预算(由 python scripts/complexity_budget.py --strict 检查)
  • 治理记录缺失必填章节(由 python scripts/decision_record_audit.py --strict 检查)

推荐统一入口

  • python scripts/dev.py test
  • python scripts/dev.py backend-test --pytest-slice <unit|local|runtime|ops|all>
  • python scripts/dev.py infra-check
  • python scripts/dev.py snapshots
  • python scripts/dev.py benchmark-report
  • python scripts/dev.py golden-report
  • python scripts/dev.py benchmark-trend
  • python scripts/dev.py quality-gate
  • python scripts/dev.py runtime-backup
  • python scripts/dev.py runtime-restore --restore-archive <archive.zip>
  • python scripts/dev.py runtime-prune --prune-keep-latest-backups 10 --prune-max-backup-age-days 14
  • python scripts/dev.py agent-replay --replay-session-id <session_id> --replay-dry-run
  • python scripts/dev.py runtime-maintenance --prune-keep-latest-backups 10 --prune-max-backup-age-days 14
  • python scripts/dev.py checkpoint-maintenance --replay-session-id <session_id> --prune-checkpoint-backend postgres --prune-checkpoint-db 'postgresql://user:password@localhost:5432/moyuan'
  • python scripts/dev.py runtime-doctor --runtime-doctor-json
  • python scripts/dev.py release-manifest --git-sha <sha> --git-ref <ref> --owner <owner>
  • python scripts/dev.py support-bundle
  • python scripts/dev.py container-smoke

Agent 质量脚本

  • python scripts/dev.py benchmark-report
  • uv run --offline python scripts/agent_subagent_scorecard.py --output-dir docs/benchmarks
  • python scripts/dev.py release-scorecard
  • python scripts/dev.py golden-report
  • python scripts/dev.py benchmark-trend
  • python scripts/dev.py quality-gate

运行数据与契约维护脚本

  • python scripts/dev.py runtime-backup
  • python scripts/dev.py runtime-restore --restore-archive <archive.zip>
  • python scripts/dev.py runtime-prune --prune-keep-latest-backups 10 --prune-max-backup-age-days 14
  • python scripts/dev.py agent-replay --replay-session-id <session_id> --replay-dry-run
  • python scripts/dev.py runtime-maintenance --prune-keep-latest-backups 10 --prune-max-backup-age-days 14
  • python scripts/dev.py checkpoint-maintenance --replay-session-id <session_id> --prune-vacuum-checkpoints
  • python scripts/dev.py runtime-doctor --runtime-doctor-json
  • python scripts/export_openapi_snapshot.py
  • python scripts/export_sse_contract_snapshot.py
  • python scripts/export_runtime_doctor_snapshot.py
  • python scripts/export_frontend_chat_runtime_golden_fixture.py
  • python scripts/dev.py release-manifest --git-sha <sha> --git-ref <ref> --owner <owner>
  • python scripts/dev.py support-bundle --base-url http://localhost:38083

组合任务约定:

  • python scripts/dev.py runtime-maintenance
    • 固定顺序是 runtime-backup -> runtime-doctor --json -> runtime-prune
  • python scripts/dev.py checkpoint-maintenance
    • 固定顺序是 runtime-prune --vacuum-checkpoints -> optional agent-replay --dry-run -> runtime-doctor --json
    • 如果显式传 --replay-session-id,会自动把 replay 收敛为 dry-run,避免维护流程里误写运行态数据

契约与安全基线

发布与观测资产

仓库规范与容器校验

更多测试与回放说明见 docs/testing/testing-guide.md

文档导航

教学入口:按任务场景跳转

其他文档入口

适合继续优化的方向

  • 把地图预览继续升级为更完整的路线编辑体验
  • 补更多真实 provider 的酒店/门票/交通数据源
  • 为城市探索加入热度排序、季节排序和更多主题榜单
  • 为分享页增加更轻量的外部只读浏览体验

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages