RoutePilot

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #android #deep-learning #linux #nodejs #windows #awesome #cli #security

(★ 16)

Artifact-first multi-agent travel assistant for evidence-backed Q&A, itinerary planning, validation, and versioned replanning.

RoutePilot 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# RoutePilot V1

RoutePilot 是一个面向旅行问答与决策的 Artifact-first 多 Agent 工作台。普通问题先生成带来源的 `TravelAnswer`；用户需要完整方案时，再把问题、约束、检索证据、候选行程、校验报告和最终快照组织成严格版本化的 Artifact，而不是把一段模型文本当作产品真相。

仓库当前只有 V1 产品主线。旧前端、旧业务 API 和旧 Agent 运行时不属于运行时或兼容面；历史数据只能通过显式的离线迁移工具导入为只读归档。

第一次使用建议先阅读[用户指南](docs/product/user-guide.md)；参与开发请从[本地开发指南](docs/development/local-development.md)和[贡献指南](CONTRIBUTING.md)开始。

## 核心能力

- 响应式 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 共享契约，以及统一质量门禁。

## 架构

浏览器只接收白名单化的 public event 与结构化 Artifact，不接收模型私有推理、工具原始返回或服务端凭据。Redis 负责投递，不是 Run 状态的真相源。

`trip.ask` 与 `trip.plan` 是两个独立命令：问答只发布 `TravelAnswer`，不会替换 Trip 当前正式 `TripSnapshot`；转行程后才要求日期、同行人数和预算，并进入完整确定性校验链。

## 最快体验路径

启动后打开 `http://127.0.0.1:33003`，直接输入一个真实问题：

```text
带父母去北京 4 天，少走路，重点看历史文化，住哪里比较方便？
```

先阅读带来源的直接回答，再按需要点击“转成行程”并确认日期、人数和预算。完整的问答、重规划、版本、分享和归档操作见[用户指南](docs/product/user-guide.md)。

## 目录

根目录只保留九个稳定产品域。本地缓存、日志、虚拟环境、构建结果和运行数据由
`.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 架构决策与运行文档 |

需要清理本地可再生产物时，先预览再执行：

```bash
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。

```bash
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 使用。

### 配置高德 Web Service Key

1. 在[高德开放平台](https://lbs.amap.com/api/webservice/create-project-and-key)创建应用并添加 Key，服务平台必须选择“Web 服务”，不要选择 Web 端 JS API、Android 或 iOS Key。
2. 打开本地且已被 Git 忽略的 `deploy/compose/.env.v1.local`，只填写下面这一项：

```dotenv
   ROUTEPILOT_AMAP_WEB_KEY=你的_Web_服务_Key
   ```

3. 重新创建 API 和 Run Worker，使服务端读取新配置：

```bash
   docker compose \
     --env-file deploy/compose/.env.v1.local \
     --file deploy/compose/v1.yaml \
     up --build --detach api run-worker
   ```

4. 通过服务端能力接口确认是否生效。配置状态只以 `configured: true/false` 表示，响应不会返回 Key：

```bash
   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 或聊天记录，应立即在高德控制台撤销并轮换。

### 配置 DeepSeek V4 Flash（可选）

在被 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 个固定检索问题：

```bash
.venv/bin/python -m scripts.v1_knowledge_base validate
.venv/bin/python -m pytest -q tests/rag/test_curated_knowledge_bundle.py
```

API 启动后，使用具备 `admin` 的受限 OIDC 运维 token 发布公共知识并执行真实检索验收：

```bash
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 蓝绿切换、回滚和紧急下线见[知识库建设与维护手册](docs/operations/knowledge-base-maintenance.md)。

```bash
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 平台手册](docs/operations/v1-platform.md)。

## 验证

```bash
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 管理：

```bash
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](docs/operations/v1-migration-runbook.md)。

## 文档

- [文档索引](docs/README.md)
- [用户指南](docs/product/user-guide.md)
- [本地开发指南](docs/development/local-development.md)
- [API 与事件开发指南](docs/development/api-guide.md)
- [V1 已实现架构 RFC](docs/governance/rfcs/RFC-0003-routepilot-full-rebuild-v1.md)
- [V1 平台与预发说明](docs/operations/v1-platform.md)
- [故障排查手册](docs/operations/troubleshooting.md)
- [可观测性与告警基线](docs/operations/observability.md)
- [备份与恢复 Runbook](docs/operations/backup-restore.md)
- [V1 离线数据迁移 Runbook](docs/operations/v1-migration-runbook.md)
- [贡献指南](CONTRIBUTING.md)
- [变更记录](CHANGELOG.md)

## License

见 [LICENSE](LICENSE)。

RoutePilot

RoutePilot 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

RoutePilot

RoutePilot 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README