目录

• 功能特性
• 系统架构
• 技术栈
• 项目结构
• 环境要求
• 快速开始
  • 1. 配置后端
  • 2. 初始化数据库
  • 3. 启动两个本地模型服务
  • 4. 构建向量数据库
  • 5. 启动后端
  • 6. 启动前端
• 真机调试
• 使用指南
• 微调自己的模型
• 配置项说明
• 常见问题 FAQ
• 数据说明
• License

功能特性

🗺️ 地图点亮足迹

• 全国城市边界 GeoJSON（后台 isolate 解析）+ 射线法命中检测
• 长按城市即可点亮 / 取消点亮 / 去规划 / 去记录，点亮的城市渲染为高亮多边形
• 点亮自动建立旅行档案，账单、笔记、行程按城市归档

🧭 AI 行程规划

• 小模型槽位填充：一句话提取出发地 / 目的地 / 天数 / 预算（RAG 少样本示例增强）
• 确定性 DFS 规划引擎：时间驱动状态机 + 回溯剪枝 + 动态预算拆分，
  基于真实景点 / 车次 / 航班数据规划，杜绝大模型"编车次、算错账"
• 输出按天分组的时间轴行程卡片：交通 / 餐饮 / 住宿 / 景点 + 逐项费用 + 超支预警

💬 智能记账

• 自然语言一句话记账："北京住宿200" 自动归类入账
• 按城市查账单明细、消费统计与预算对照

📚 攻略问答

• 本地攻略知识库向量检索回答，支持 txt / pdf / csv 文档导入，按文件增量更新

🛡️ 对话稳定（Harness 架构）

• 确定性 Python 代码对模型输出验收重试：合格直出、失败摘除子智能体重开对话
• 0.8B 小模型也能提供较为出色的对话服务

系统架构

flowchart LR
    A[Flutter App] -->|HTTP / SSE| B[FastAPI 后端]
    B --> C{Supervisor 意图路由}
    C -->|旅行| D[travel 子智能体]
    C -->|软件操作| E[operation 子智能体]
    C -->|闲聊| F[chat 子智能体]
    D -->|规划请求| D1[槽位填充 LLM+RAG]
    D1 --> D2[DFS 规划引擎]
    D -->|攻略问题| D3[RAG 攻略问答]
    E --> E1[记账 / 城市 / 账单]
    D2 & D3 & E1 --> G[harness 验收]
    G -->|合格| H[返回用户]
    G -->|失败| C

一次规划请求的完整链路：

用户: "上海去杭州玩4天，预算3000"
  → supervisor 选 travel 子智能体
  → 槽位填充: {出发:上海, 目的:杭州, 天数:4, 预算:3000}
  → DFS 引擎: (去程×回程×酒店) 组合搜索 + 按天填槽
  → 返回时间轴行程卡片

技术栈

项目结构

tracord/
├── backend/                        # FastAPI 后端
│   ├── main.py                     # 应用入口(uvicorn main:app)
│   ├── alembic/                    # 数据库迁移
│   ├── app/
│   │   ├── routers/                # 接口层(user/cities/trips/bills/agent...)
│   │   ├── services/               # 业务服务层
│   │   ├── crud/                   # 数据访问层
│   │   ├── models/                 # ORM 模型
│   │   ├── config/                 # 数据库/邮箱/JWT 配置(读 .env)
│   │   ├── core/                   # token/邮件等核心工具
│   │   ├── data/                   # 运行时数据缓存
│   │   └── agent/                  # AI 多智能体
│   │       ├── tracord_agent.py    # supervisor + harness 主循环
│   │       ├── config/             # yml 配置(模型/向量库/提示词)
│   │       ├── prompts/            # 各角色提示词
│   │       ├── data/               # 槽位示例 + 攻略文档(china_city_guide.txt)
│   │       ├── model/              # 模型工厂(llama.cpp 接入)
│   │       ├── chat/               # 闲聊子智能体
│   │       └── travel/             # 旅行子智能体
│   │           ├── services/       # 规划引擎(planner_engine)/RAG/槽位填充
│   │           ├── tools/          # travel_plan / rag 工具
│   │           └── data_source/    # 高德/12306/RollingGo 数据源
│   ├── operation/                  # 软件操作子智能体
│   ├── train_data/                 # 微调训练数据(tool_calling_train.jsonl)
│   ├── scripts/                    # 工具脚本(向量库构建/微调数据生成/回归测试)
│   └── docs/                       # 工程文档
├── frontend/                       # Flutter 前端
│   └── lib/features/               # map / agent / trips / plans / records / auth...

环境要求

快速开始

以下命令默认在项目根目录执行，涉及后端的先 cd backend。

1. 配置后端

cd backend
uv sync
cp .env.example .env    # 将内置占位符换成个人的

全部配置项说明见 配置项说明。

2. 初始化数据库

MySQL 中创建 tracord 库（字符集 utf8mb4），然后执行迁移：

alembic upgrade head

3. 启动两个本地模型服务

程序依赖两个本地模型服务，缺一不可：

# 终端 1: 对话模型(端口 8080) — 负责槽位填充、意图路由、对话生成
llama-server -m qwen3.5-0.8b.gguf --port 8080

# 终端 2: 向量模型(端口 8081) — 负责攻略/槽位示例的向量化, 必须带 --embedding
llama-server -m m3e-small.gguf --port 8081 --embedding

模型与端口的对应关系配置在 backend/app/agent/config/model.yml。

4. 构建向量数据库

首次运行前必须构建，否则攻略问答和槽位填充没有素材：

# ① 灌入槽位填充的少样本示例
python scripts/_load_slots.py

# ② 灌入攻略文档(backend/app/agent/data/ 下的 txt/pdf/csv)
python -c "from app.agent.travel.services.vector_store import VectorStoreService; VectorStoreService().load_document()"

• 向量库生成在 backend/chroma_db/，支持增量更新（按文件 md5 去重），重复执行安全
• 扩充攻略知识库：往 backend/app/agent/data/ 新增 .txt（按城市组织）或 .pdf/.csv，
  再次进行操作 ② 即可

5. 启动后端

uvicorn main:app --host 127.0.0.1 --port 8000

启动日志应能看到数据库连接成功、无报错。

6. 启动前端

cd frontend
flutter pub get
flutter run

真机调试（USB 连接手机）

1. 手机开启 USB 调试，数据线连接电脑（首次连接需在手机上确认授权）
2. 执行端口转发，把手机的 8000 端口映射到电脑（adb 在 Android SDK 的 platform-tools 目录）：

D:\Android\SDK\platform-tools\adb.exe reverse tcp:8000 tcp:8000

1. 前端 lib/core/network/api_config.dart 的 baseUrl 保持 http://127.0.0.1:8000 即可

⚠️ 每次重新插拔数据线 / 重启 adb 后，需要重新执行一遍 adb reverse。

局域网调试：后端加 --host 0.0.0.0 启动，
baseUrl 改成 http://你电脑的局域网IP:8000，手机与电脑连接同一 Wi-Fi。

模拟器调试

Android 模拟器中 baseUrl 使用 http://10.0.2.2:8000（10.0.2.2 是模拟器访问宿主机的专用地址）。

使用指南

规划一次旅行

对 AI 助手说："上海去杭州玩4天，预算3000" → 生成 4 天时间轴行程卡片，
包含每天几点坐哪趟车、在哪吃饭、住哪家酒店、逐项费用与总花费、超支预警。

记一笔账

旅行中说一句："南宁住宿200" → 自动记账归类；随时问"我在南宁花了多少"查账单。

点亮城市

去过某地后，在地图长按该城市 → 点亮 → 自动建立旅行档案，
账单/笔记/行程按城市归档，点亮的城市在地图上高亮。

微调自己的模型

本项目的前端交互与提示词体系可以配合任何基座模型复现微调：

1. 训练数据：backend/train_data/tool_calling_train.jsonl
   （可用 backend/scripts/gen_finetune_data.py 追加生成样本，注意先阅读脚本顶部说明）
2. 使用 LLaMA-Factory 对 Qwen3.5-0.8B
   做 LoRA 微调（数据格式：LLaMA-Factory 的 sharegpt/tool-calling 格式）
3. 训练完成后合并 LoRA 权重并导出 GGUF，交给 llama.cpp 部署（见第 3 步）
4. 替换后建议跑 backend/scripts/batch_test_budget.py 做回归验证

配置项说明

backend/.env 全部配置项：

模型与向量库配置在 backend/app/agent/config/ 下的 yml 文件
（model.yml / chroma.yml / prompts.yml），一般无需改动。

常见问题 FAQ

依次检查：MySQL 是否启动、tracord 库是否已建、alembic upgrade head 是否执行、
.env 里邮箱配置是否正确（QQ 邮箱使用 SMTP 授权码而非登录密码，
需在 QQ 邮箱设置 → 账户 → 开启 SMTP 服务后生成）。

8081 端口的 m3e 向量模型服务没启动，或者第 4 步"构建向量数据库"没执行。
确认 backend/chroma_db/ 目录已生成、两个模型服务都在运行。

确认 8080 / 8081 两个 llama.cpp 服务都在运行；Windows 下若使用 httpx 直连出现 502，
本项目已内置 RequestsTransport 绕过（见 backend/app/agent/model/factory.py）。

USB 方式：确认 adb reverse 已执行且设备已授权（adb devices 能看到设备），
重新插拔数据线后需重新执行 reverse。
局域网方式：后端需以 --host 0.0.0.0 启动，手机与电脑同一 Wi-Fi，防火墙放行 8000 端口。

预算过低会触发预算剪枝导致无解（引擎允许 20% 浮动），可适当提高预算；
另请查看后端日志确认景点/餐厅/交通数据是否拉取成功（API key 是否有效）。

天地图 key（TIANDITU_KEYS）未配置或额度用尽；key 在 .env 中逗号分隔可填多个轮询。

数据说明

本仓库不包含任何业务数据。首次运行时，程序会用你在 .env 里配置的
高德 / 12306 / RollingGo key 自动拉取景点、餐厅、交通数据，
并缓存到本地 backend/app/data/（该目录已被 .gitignore 排除，不会被提交）。

数据来自第三方服务，请遵守其服务条款，拉取到的数据请勿直接再分发。

License

本项目采用 PolyForm Noncommercial 1.0.0 许可：仅允许个人学习、研究等非商业用途，禁止一切商业使用，详见 LICENSE。

如需商业授权，请联系作者取得书面许可。

分发时请保留本协议、原作者署名与仓库地址；使用第三方 API 拉取的数据请遵守数据源服务条款，不得再分发。

致谢

• llama.cpp — 本地大模型推理
• LLaMA-Factory — 模型微调
• LangChain / LangGraph — 智能体框架
• Flutter / flutter_map — 移动端与地图
• Chroma — 向量数据库