RoutePilot 是一个面向旅行问答与决策的 Artifact-first 多 Agent 工作台。普通问题先生成带来源的 TravelAnswer；用户需要完整方案时，再把问题、约束、检索证据、候选行程、校验报告和最终快照组织成严格版本化的 Artifact，而不是把一段模型文本当作产品真相。
仓库当前只有 V1 产品主线。旧前端、旧业务 API 和旧 Agent 运行时不属于运行时或兼容面；历史数据只能通过显式的离线迁移工具导入为只读归档。
第一次使用建议先阅读用户指南；参与开发请从本地开发指南和贡献指南开始。
- 响应式 Next.js 旅行工作台，以及同源 BFF 身份边界。
- 默认轻量问答：无需先填写日期和预算，RAG/Provider 证据不足时明确拒绝编造；回答可一键转为正式行程。
- FastAPI Trip、Run、Artifact、成员管理和公开事件 API。
- 基于正式 TripSnapshot 的结构化重规划、CAS 防过期覆盖和持久 typed-input 恢复。
- capability + 短期 HttpOnly session 的脱敏只读分享，支持即时轮换与撤销。
- Answering、Research、Planner、Validation、Semantic Verifier 五类 A2A 1.0 Agent 接口。
- PostgreSQL 持久化 Product Run、A2A Task、Artifact version、RAG 与事务 outbox。
- Redis Streams 外部执行队列；Run/A2A 数据库租约、attempt fencing、重投递和跨进程取消。
- PostgreSQL FTS + 可选 pgvector 的租户隔离 RAG，保留来源、版本、许可、时效与检索轨迹；仓库提供 checksum-bound 的内置旅行决策知识包和固定查询验收。
- 受控 Provider Gateway：高德地理编码、POI、路线矩阵、营业时间与天气事实。
- OIDC Authorization Code + PKCE Web 登录；API 独立校验 access JWT。
- JSON Schema、Python 与 TypeScript 共享契约，以及统一质量门禁。
Browser
|
v
Next.js Web / same-origin BFF ----> OIDC Provider
|
v
FastAPI /api/v1
| PostgreSQL (system of record)
+---- command ---> Run + outbox + Artifact + A2A Task + RAG
|
outbox-dispatcher
|
Redis Streams
|
run-worker
|
+----------+-----------+
| |
Answering Agent Research -> Planner -> Validation -> Verifier
| | |
TravelAnswer RAG search Provider Gateway
浏览器只接收白名单化的 public event 与结构化 Artifact，不接收模型私有推理、工具原始返回或服务端凭据。Redis 负责投递，不是 Run 状态的真相源。
trip.ask 与 trip.plan 是两个独立命令：问答只发布 TravelAnswer，不会替换 Trip 当前正式 TripSnapshot；转行程后才要求日期、同行人数和预算，并进入完整确定性校验链。
启动后打开 http://127.0.0.1:33003，直接输入一个真实问题：
带父母去北京 4 天，少走路，重点看历史文化，住哪里比较方便？
先阅读带来源的直接回答，再按需要点击“转成行程”并确认日期、人数和预算。完整的问答、重规划、版本、分享和归档操作见用户指南。
根目录只保留九个稳定产品域。本地缓存、日志、虚拟环境、构建结果和运行数据由
.gitignore 与提交的 VS Code 工作区规则隐藏，不属于产品结构。
| 路径 | 职责 |
|---|---|
apps/ |
用户可运行的应用；当前为 Next.js Web/BFF |
backend/moyuan_web/v1/ |
FastAPI V1 产品 API、控制平面、存储与 Worker |
agent/travel_agent/a2a/ |
A2A 1.0 协议边界与持久 Task |
agent/travel_agent/runtime_v2/ |
旅行编排、Research、规划与校验链路 |
agent/travel_agent/rag/ |
知识摄取、混合检索与 provenance |
agent/travel_agent/providers/ |
实时旅行事实 Provider Gateway |
packages/、schemas/ |
Python/TypeScript 契约与 JSON Schema |
deploy/ |
Alembic、Compose、容器与最小权限数据库配置 |
scripts/ |
开发清理、Worker、outbox、质量门禁和离线迁移工具 |
tests/ |
契约、单元、集成、恢复与垂直切片测试 |
docs/ |
当前 V1 架构决策与运行文档 |
需要清理本地可再生产物时，先预览再执行：
python scripts/clean_workspace.py
python scripts/clean_workspace.py --apply清理命令不会删除 .env、.venv、node_modules、PostgreSQL volume 或用户数据。
要求 Docker Engine、Docker Compose v2；如需本地运行质量门禁，还需要 Python 3.13、Node.js 24 和 npm。
cp deploy/compose/v1.env.example deploy/compose/.env.v1.local为 .env.v1.local 中每个密码和 BFF secret 生成独立随机值。示例中的必填 secret 留空时 Compose 会 fail closed；高德 Key 是可选项，未配置时系统保守降级，不会向浏览器注入任何地图密钥。
可调运行参数包括 Provider allowlist/timeout、Run lease/reclaim、日志级别、LLM token 上限和 embedding 配置；文档门禁会验证提交到示例 env 的变量确实被 Compose 使用。
-
在高德开放平台创建应用并添加 Key，服务平台必须选择“Web 服务”，不要选择 Web 端 JS API、Android 或 iOS Key。
-
打开本地且已被 Git 忽略的
deploy/compose/.env.v1.local，只填写下面这一项：ROUTEPILOT_AMAP_WEB_KEY=你的_Web_服务_Key
-
重新创建 API 和 Run Worker，使服务端读取新配置：
docker compose \ --env-file deploy/compose/.env.v1.local \ --file deploy/compose/v1.yaml \ up --build --detach api run-worker
-
通过服务端能力接口确认是否生效。配置状态只以
configured: true/false表示，响应不会返回 Key：curl http://127.0.0.1:33003/api/v1/providers/capabilities
安全边界：不要把真实 Key 写入 README、.env.example、Compose YAML、前端代码或任何 NEXT_PUBLIC_* 变量；不要使用已废弃的 AMAP_API_KEY 别名。真实 Key 只应存在于被忽略的本地 env 文件或生产 secret manager 中。若 Key 曾进入 Git 历史、日志、Issue 或聊天记录，应立即在高德控制台撤销并轮换。
在被 Git 忽略的 deploy/compose/.env.v1.local 中设置 ROUTEPILOT_LLM_API_KEY。模型只负责生成受 JSON Schema 约束的低 token 检索指令和基于已检索证据的答案组织；RAG/Provider 返回才是事实来源。ROUTEPILOT_LLM_MAX_OUTPUT_TOKENS 默认 96，ROUTEPILOT_ANSWER_MAX_OUTPUT_TOKENS 默认 320。未配置模型时，系统使用确定性证据摘要降级，不会伪造模型回答。
仓库提供 routepilot-travel-zh@2026.07.2，覆盖旅行问答决策、行程节奏、预算、住宿、老人/儿童/无障碍、证据时效，以及首批 12 个中国省级地区的旅行结构知识。它不包含票价、营业、班次、天气或库存等实时事实。
先在本地验证 manifest、正文哈希、上游官方来源、许可、审核记录和 36 个固定检索问题：
.venv/bin/python -m scripts.v1_knowledge_base validate
.venv/bin/python -m pytest -q tests/rag/test_curated_knowledge_bundle.pyAPI 启动后，使用具备 admin 的受限 OIDC 运维 token 发布公共知识并执行真实检索验收：
export ROUTEPILOT_KNOWLEDGE_API_URL=http://127.0.0.1:38083/api/v1
export ROUTEPILOT_ACCESS_TOKEN='受限运维会话中的 access token'
.venv/bin/python -m scripts.v1_knowledge_base apply --allow-public
.venv/bin/python -m scripts.v1_knowledge_base verify应用启动不会绕过权限自动写知识库。tenant 私有部署可使用 tenant_admin 和 --visibility tenant。新增目的地来源、复核周期、corpus 蓝绿切换、回滚和紧急下线见知识库建设与维护手册。
docker compose \
--env-file deploy/compose/.env.v1.local \
--file deploy/compose/v1.yaml \
config --quiet
docker compose \
--env-file deploy/compose/.env.v1.local \
--file deploy/compose/v1.yaml \
up --build --detach默认入口：
- Web：
http://127.0.0.1:33003 - API：
http://127.0.0.1:38083 - OpenAPI UI：
http://127.0.0.1:38083/docs - 健康检查：
http://127.0.0.1:38083/api/health
Compose 会先运行一次 Alembic migration 和数据库授权，再启动 API、Run Worker、Outbox Dispatcher 与 Web。详细配置见 V1 平台手册。
python -m pip install -r requirements-dev.txt
npm ci --prefix apps/web --ignore-scripts
python scripts/v1_quality_gate.py统一门禁覆盖契约、后端、A2A、Provider、RAG、Runtime、Web、文档、安全边界和 Alembic 离线 SQL。文档门禁检查必需文档、仓库内链接和 env/Compose 一致性。需要真实 PostgreSQL/Redis 的测试由 CI 的 stateful integration job 执行；本地也可提供对应的 ROUTEPILOT_*_TEST_* DSN 运行。
V1 schema 只通过 Alembic 管理：
docker compose \
--env-file deploy/compose/.env.v1.local \
--file deploy/compose/v1.yaml \
run --rm migration历史 session/share 数据不是产品兼容面，也不会被应用自动读取。需要保留时，由管理员显式运行 python -m scripts.migration_v1，完成 inventory、dry-run/backfill 与 verify；输出是只读 ImportedTripArchive@1，工具不会自动删除或改写源数据。操作步骤见 V1 数据迁移 Runbook。
- 文档索引
- 用户指南
- 本地开发指南
- API 与事件开发指南
- V1 已实现架构 RFC
- V1 平台与预发说明
- 故障排查手册
- 可观测性与告警基线
- 备份与恢复 Runbook
- V1 离线数据迁移 Runbook
- 贡献指南
- 变更记录
见 LICENSE。