17同游 · 旅行智能体（Travel Browser Agent）

个人旅行规划平台：用户用自然语言提需求，Agent 驱动真实 Chrome 浏览器 （Chrome DevTools MCP）浏览小红书/携程/地图等页面，抽取结构化信息， 生成带预算的完整攻略，并支持多人协同编辑行程。

线上：https://17tongyou.com（服务器规模有限，目前邀请制）

当前版本与功能（2026-10-20）

平台	当前状态	说明
Web	已部署 2026-10-20 修复	React + TypeScript；手机与桌面布局；前端说明
Android	0.8.2 (13)	独立签名 APK，打包前端资源快照；下载 APK · 构建说明
iOS	1.0.11 (12)	原生 SwiftUI，已安装验证；当前个人签名测试，尚未通过 App Store / TestFlight 分发；构建说明

主导航收敛为 旅行 / 记账 / 我的，独立“问 AI”入口支持收起恢复草稿与会话。同游圈已从主入口移除，历史数据保留。

• 旅行：旅行册首页、导入与创建、多人协作；地图与可拖动行程面板同屏，地点卡展示缩略图、时间和简短说明，点击查看实景图、地址与攻略摘录。没有图片时使用地点占位；路线连线表示顺序，不等于道路导航。
• 记账：独立账本可关联行程，成员权限独立；编辑/只读邀请与分享加入、多币种支出、自选汇总币种、最新参考汇率。说明选填，金额与分类即可记一笔。
• 我的：历史、公告、帮助、记忆、技能、连接；管理员可管理用户。已修复 Web/Android 工具弹层被账户页面遮挡的问题。
• AI 外观：Web 已修复夜间标题、输入文字与辅助提示对比度，明暗切换保持草稿和布局；Android 共享源码同步，现有 0.8.2 安装包尚未包含此修复。
• 客户端更新：Android 0.6.0 起前台检查新版，提示后浏览器下载，由用户确认覆盖安装；系统深浅主题与启动动画保留。网页部署不会更新 APK 内资源，iOS 需单独构建签名。

三端共享账号与后端数据，版本和发布流程独立。详见三端发布管理。本轮验收记录：主界面、景点详情、卡片与地图比例、我的工具弹层。

主要复杂度不在「调一次 LLM」，而在编排、上下文治理、可观测与安全边界。

第一次来？ 如果你想看的是「一个真在跑的 Agent 系统长什么样」，建议这个顺序： 技术亮点（5 分钟知道它解决了什么）→ docs/pitfalls/（开发踩坑记录， 记的全是不报错的 bug，大概是这个仓库最有价值的部分）→ 想跑起来再看 快速开始。

---

快速开始

需要 Python 3.12 / Node 23 / Chrome / PostgreSQL 16。

cp backend/.env.example backend/.env           # 见下方「你需要自己准备什么」
cp frontend/.env.example frontend/.env.local   # 高德 Web端(JS API) key + 安全密钥
(cd backend && python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt)
(cd frontend && npm ci)

backend/scripts/start_chrome.sh                          # Agent 专用调试 Chrome（:9223）
(cd backend && .venv/bin/uvicorn app.main:app --reload --port 8000)
# 在另一个终端，从仓库根目录启动前端：
cd frontend && npm run dev                               # → http://localhost:5173

⚠️ backend/scripts/dev.sh 是本项目自己部署环境的一键脚本，它会先开一条到生产库的 SSH 隧道。你自己跑请用上面的分步命令 + 本地 PostgreSQL。

你需要自己准备什么

运行凭据由本地环境配置提供（.env / .env.local 均已 gitignore，前端测试禁止把 key 写回源码）。下面这些需要自行准备：

项	必需	从哪来
DEEPSEEK_API_KEY	✅	platform.deepseek.com，按量付费
DATABASE_URL	✅	本地起一个 PostgreSQL 16 就行，表在启动时自动建
ADMIN_PASSWORD	✅	你自己定。留空会拒绝启动——本项目刻意不提供默认管理员口令
AMAP_KEY / AMAP_SECRET	✅	高德开放平台，服务平台选 Web服务，开启数字签名
VITE_AMAP_JS_KEY + 安全密钥	✅	同上，但服务平台选 Web端(JS API)，是另一对，别混用
小红书来源	❌	需自建 xiaohongshu-mcp 容器并用自己的账号扫码；不配则该来源自动跳过
Langfuse	❌	不填则埋点整体 no-op，不影响功能

携程不需要 key —— 它是在浏览器里扫码登录，登录态只存在你自己机器的 Chrome profile 里。

.env / .env.local 都不进版本库，任何密钥都不要写进代码或文档。 前端有测试钉住这条（frontend/tests/no-inline-keys.test.mjs）——因为把 key 写回源码 不会让任何功能坏掉，没有征兆的问题只能靠护栏。

关于高德的两个凭据（frontend/.env.local，两个值性质完全不同）：

变量	类型	性质
VITE_AMAP_JS_KEY	Web端(JS API) key	本质公开——必须下发到浏览器才能加载地图，F12 就看得到。防护靠高德控制台的域名白名单，不是靠藏
VITE_AMAP_JS_SECURITY_CODE	安全密钥	真密钥。只有本地开发用它明文直连；生产走 nginx _AMapService 反代由服务端注入 jscode（高德官方「代理服务器」模式），前端那段在 import.meta.env.DEV 分支里，构建时被摇树剔除

自己去高德开放平台申请一对，别用别人的。 后端的 AMAP_KEY/AMAP_SECRET 是另一套（Web服务 + 数字签名），互不相干。

分步启动、断点调试（不能用 dev.sh，shell 套子进程挂不上断点）见 CLAUDE.md。

cd backend && .venv/bin/python -m pytest tests/ -q      # 1400+ 全离线单测（前端另有 99 条：cd frontend && npm test）

本地无外网 DNS 时 test_research_context.py / test_context_security.py 有几个失败—— 那是沙箱把 example.com 解析到保留地址触发了 SSRF 防护，不是代码问题。

---

技术亮点

1. 三路路由分流（agent/deep_research.py: resolve_route / decide_route）

一条用户消息进来先分流，不同问题走完全不同的成本曲线：

路	判定	链路	线上耗时
direct	常识/建议/追问/闲聊	无浏览器无搜索，三元组记忆 + 近 5 轮历史 → 单次流式生成	首字 6s / 全程 17s
guide	规划/攻略/查酒店	LangGraph 采集→生成→反思流水线	~130s
research	多城对比/预算测算/签证/帮我选	deepagents 自主研究	4-6min

分类用快模型单次调用（~1s），失败/未知/空消息一律回落 guide——宁慢勿错。 改造前同类问题一律走完整流水线，要 2-4 分钟。有专门的评估集守着（见 §6）。

2. 深度研究模式（agent/deep_research.py + research_tools.py）

开放式问题主流水线接不住（单目的地 Preference、产出模子固定），路由到自主 agent：

• 资源分工：浏览器工具只在主 agent；subagent api-researcher 只有纯 API 工具
• actor 模式的浏览器会话：专职 worker task 独占 ChromeMCP 生命周期，工具经队列提交 —— MCP 的 stdio_client 是 task-affine 的，跨 task 进出会炸 cancel scope 并泄漏池槽位
• 工具硬配额：prompt 写的纪律在长上下文会漂移（实测一轮搜 5 次、读 18 个来源把 600s 烧光），所以在工具层强制封顶，超限返回引导文案让 agent 转入产出
• 重复调用守卫（agent/repeat_guard.py）：配额治「总量超标」，这个治「同一查询反复调」 —— 连续 3/6/10 次注入升级式提醒，不阻断（阻断会让 agent 卡死在无路可走的状态）

3. 上下文治理

长任务最大的敌人是上下文膨胀。五层机制：

• 留存换引用（research_tools.py）：抓来的长正文全文存 source_store，工具只回 ~1500 字预览 + 一个 source_id；模型要细节时调 read_source(id, offset) 分页取

• microcompaction（deep_research.py: _context_trim_middleware）：上下文超阈值时把 最旧的工具结果替换成占位摘要，保留最近 N 个完整结果——压缩历史而不打断当前推理

• surface 投影（orchestrator.py: derive_surface，借鉴 DeepSeek Harness）： 历史压缩从「就地覆盖摘要字段」改成往只追加日志里追加一条 replace 消息遮蔽旧区间。

  travel_message 表（日志，只增不减）── derive_surface() 投影 ──> 进模型的 messages
  

  压缩因此不删除任何东西：原文一条不少地留在表里可完整回放，而投影出来的上下文是短的。 「追加」是往日志追加，不是往上下文追加——这两件事不矛盾（账本 vs 余额）。

• 幂等中段截断（agent/truncate.py）：head + marker + tail <= threshold 在配置期 就用数学约束保证，从根上杜绝「截过的再截一次又短一截」

• 边界只由日志推动（2026-08-22）：装配期那个「超限就取近 N 轮」的滑动窗口已删除。 它与 surface 投影是两套互不知情的压缩，而且它砍掉的消息没有摘要覆盖、无任何记录、 边界还每轮左移一格（前缀缓存随之作废）。现在唯一能改变模型可见边界的动作是折叠， 而折叠一定在日志里留下一条 replace。超限时就地补一次折叠，而不是静默丢。

配套 上下文清单（agent/context_manifest.py）：每条终稿记下「这轮由什么装配而成」 （历史用了全文还是摘要+近窗、记忆几条、来源几篇），事后能回答「那轮到底喂了什么进模型」。

This is the beginning of the README. Read the rest at the original. Read the full README ↗