Arcadegent

Arcadegent 是一个面向音游机厅检索、Agent 问答和路线建议的全栈应用。当前公开仓库保留应用运行、Agent 编排、地图渲染和部署相关代码；数据采集、运行缓存和生产密钥不随仓库公开。注：数据源来自于全国音游地图：https://map.bemanicn.com/

QQ群：1091316877

功能概览

Agent 对话：支持机厅搜索、附近推荐、导航路线三类意图，前端默认使用异步会话派发和 SSE 实时事件流。
实时过程展示：会话会推送 session.started、subagent.changed、tool.*、navigation.route_ready、assistant.token、assistant.completed 等事件。
地图化结果：聊天路线和机厅浏览都能渲染高德地图点位、路线卡片，并提供 Web 高德查看和唤起高德导航链接。
机厅浏览器：支持机厅名称、地区级联、省市区筛选、只看有机台、更新时间/机种数/指定机种机台数排序、分页和门店详情。
会话管理：支持历史会话列表、详情加载、运行中重连和删除会话。
地理能力：支持浏览器定位缓存、高德逆地理编码、机厅坐标缓存、无坐标机厅的区域级地图回退。
Agent 工具系统：内置 DB 查询、地理解析、路线规划、总结工具，同时支持启动时发现 MCP 工具并投影为 mcp__*。

技术栈

Backend: Python 3.11+, FastAPI, Pydantic, httpx, FastMCP
Agent: OpenAI-compatible LLM provider, ReAct runtime, YAML subagent definitions, JSON Schema tool registry
Frontend: React 18, TypeScript, Vite, Zustand, marked, DOMPurify
Map: 高德 Web JS API, 高德 REST API, 高德 MCP endpoint
Data: JSONL 读模型、可选 Supabase 读模型、本地 JSON 会话存储
Tests: pytest, Playwright
Evaluation: Hit/Recall@K, MRR@K, MAP@K, nDCG@K, answer/citation scoring, quality gates

目录结构

backend/                         FastAPI 后端、Agent 运行时、工具系统和测试
backend/app/agent/context/       Agent prompts 与技能片段
backend/app/agent/nodes/         main agent / worker YAML 定义和 provider profile
backend/app/agent/tools/         builtin tools、MCP gateway、工具 schema 和 manifest
apps/web/                        React + Vite 前端
apps/web/src/components/map/     高德地图、路线卡片和地图操作组件
apps/web/tests/e2e/              Playwright 端到端测试
deploy/nginx/                    生产 Nginx 示例配置
docs/guidings/                   对外指南文档
docs/dev-details/                对外开发细节文档
docker-compose.yml               本地或服务器 compose 编排

data/、运行缓存、私有脚本、计划/issue 归档、数据库迁移草案和真实环境变量按敏感资料处理，不随公开仓库发布。需要本地运行完整数据链路时，请自行准备兼容的 JSONL 数据源或配置后端可访问的数据库。

文档入口

环境要求

Python >=3.11
Node.js >=18
npm >=9

仓库根目录没有统一的前端 workspace package.json，前端命令需要在 apps/web/ 下执行。

快速开始

以下命令默认从仓库根目录 Arcadegent/ 开始。

1. 安装后端依赖

macOS / Linux:

cd backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
cd ..

Windows PowerShell:

cd backend
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
cd ..

2. 安装前端依赖

cd apps/web
npm install
cd ../..

3. 配置后端环境变量

后端启动时会自动读取仓库根目录下的 .env。建议从示例文件复制：

macOS / Linux:

cp backend/.env.example .env

Windows PowerShell:

Copy-Item backend/.env.example .env

常用配置如下：

APP_ENV=dev
DEMO_MODE=false
LOG_LEVEL=INFO
HOST=0.0.0.0
PORT=8000
CORS_ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

ARCADE_DATA_SOURCE=jsonl
ARCADE_DATA_JSONL=data/local/arcades.jsonl
SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
SUPABASE_TIMEOUT_SECONDS=8

# Supabase Auth / JWT（默认关闭，配置完成后再开启）
AUTH_ENABLED=false
JWT_ISSUER=https://YOUR_PROJECT_REF.supabase.co/auth/v1
JWT_AUDIENCE=authenticated
JWT_JWKS_URL=https://YOUR_PROJECT_REF.supabase.co/auth/v1/.well-known/jwks.json
JWT_ALGORITHMS=RS256,ES256
# 仅旧版 HS256 项目需要；推荐使用上面的 JWKS
JWT_SECRET=
CHAT_SESSION_STORE_PATH=data/runtime/chat_sessions.json
CHAT_STREAM_EVENT_STORE_PATH=data/runtime/chat_stream_events.jsonl

LLM_API_KEY=
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
LLM_TIMEOUT_SECONDS=20
LLM_TEMPERATURE=0.2
LLM_MAX_TOKENS=500

RAG_ENABLED=false
RAG_SOURCE_PATH=data/local/knowledge
RAG_CHUNK_SIZE=700
RAG_CHUNK_OVERLAP=120
RAG_SEMANTIC_CHUNKING_ENABLED=false
RAG_TOP_K=4
RAG_EMBEDDING_API_KEY=
RAG_EMBEDDING_BASE_URL=
RAG_EMBEDDING_MODEL=local-hash-v1
RAG_EMBEDDING_TIMEOUT_SECONDS=20
RAG_VECTOR_BACKEND=memory
RAG_FAISS_INDEX_PATH=data/runtime/rag_index.faiss
RAG_FAISS_METADATA_PATH=data/runtime/rag_index_meta.json

# Hugging Face 本地模型；公开模型无需 Token
HF_TOKEN=
HUGGINGFACE_CACHE_DIR=data/runtime/huggingface
HF_HUB_OFFLINE=false
HUGGINGFACE_DEVICE=
HUGGINGFACE_TRUST_REMOTE_CODE=false
HUGGINGFACE_REVISION=

AGENT_MAX_STEPS=20
AGENT_CONTEXT_WINDOW=24
AGENT_PROVIDER_PROFILE=default

MCP_SERVERS_DIR=backend/app/agent/tools/mcp/servers
MCP_DEFAULT_TIMEOUT_SECONDS=10

AMAP_API_KEY=
AMAP_BASE_URL=https://restapi.amap.com
AMAP_TIMEOUT_SECONDS=8
ARCADE_GEO_CACHE_PATH=data/runtime/arcade_geo_cache.json
ARCADE_GEO_SYNC_LIMIT=8
ARCADE_GEO_MAX_WORKERS=4
ARCADE_GEO_REQUEST_TIMEOUT_SECONDS=1.2

说明：

ARCADE_DATA_SOURCE 可选 jsonl 或 supabase，默认 jsonl。
ARCADE_DATA_JSONL 是 JSONL 模式读取的机厅数据源；公开仓库不包含真实数据，请指向你本地准备的兼容文件。
ARCADE_DATA_SOURCE=supabase 时必须配置 SUPABASE_URL，以及 SUPABASE_ANON_KEY 或 SUPABASE_SERVICE_ROLE_KEY。缺少配置会启动失败，不会静默回退 JSONL。
SUPABASE_SERVICE_ROLE_KEY 仅用于后端或导入脚本，不要暴露给浏览器端。
DEMO_MODE=true 会忽略外部机厅数据源，加载 60 条确定性合成数据；即使 LLM_API_KEY 和 AMAP_API_KEY 均为空，也可演示搜索、地图、SSE 流式事件及离线路线降级。/health 会返回 demo_mode=true 和 degradation=deterministic_local_runtime。
DEMO_MODE=false 且 LLM_API_KEY 为空时，服务和机厅列表仍可启动，但 Agent 对话无法完成模型编排。API Key 需兼容 OpenAI 接口。
RAG_ENABLED=true 后会启用 LangChain-backed 知识检索工具 knowledge_search_tool。RAG_SOURCE_PATH 支持目录或单文件，目录下会扫描 .md、.txt、.json、.jsonl、.pdf、.docx、.doc。
RAG_SEMANTIC_CHUNKING_ENABLED=true 时会优先尝试 SemanticChunker 做语义分块；若依赖不可用或分块失败，会自动回退到当前固定长度分块。
RAG_EMBEDDING_MODEL=local-hash-v1 时会使用内置本地 embedding 回退，不依赖额外向量服务，适合先把 RAG 跑通。需要更好的语义效果时，再换成真实 embeddings API。
如果想用本地真实 Transformer embedding，可以把 RAG_EMBEDDING_MODEL 设成 sentence-transformers:<model-name>，例如 sentence-transformers:BAAI/bge-small-zh-v1.5。
sentence-transformers:* 默认从 Hugging Face Hub 下载到 HUGGINGFACE_CACHE_DIR。公共模型无需 HF_TOKEN；私有或 gated 模型才需要把只读 Token 写入本机 .env。
HF_HUB_OFFLINE=true 会禁止联网并只读取缓存，适合生产稳定启动；第一次准备模型时应保持为 false，下载完成后再切换离线模式。
HUGGINGFACE_DEVICE 可设为 cpu、cuda 或 mps，留空时由 PyTorch 自动选择。HUGGINGFACE_TRUST_REMOTE_CODE 默认关闭，只有确认模型仓库代码可信时才开启。
HUGGINGFACE_REVISION 可锁定模型 commit/tag；生产环境建议使用 commit SHA，避免同名模型更新导致评测和索引漂移。
若使用外部 embeddings API，RAG_EMBEDDING_BASE_URL、RAG_EMBEDDING_API_KEY 为空时会分别回退到 LLM_BASE_URL、LLM_API_KEY。
RAG_VECTOR_BACKEND 默认是 memory；设成 faiss 后会把知识库向量索引持久化到本地文件。
RAG_FAISS_INDEX_PATH 保存 .faiss 索引，RAG_FAISS_METADATA_PATH 保存 metadata sidecar。知识库上传/删除会进入后台增量索引队列，按文件状态追踪 pending / indexing / ready / failed，并复用未变化 Chunk 的 embedding。
.jsonl / .json 知识源建议至少包含 content 或 text 字段，可选 title、source_uri、source_type 元数据。
.pdf 知识源使用 pypdf 提取文本并按页索引；扫描版 PDF 若无内嵌文本，当前不会自动 OCR。
.docx 知识源会提取正文、表格、页眉页脚、批注和文本框中的文本后索引。
.doc 知识源会先自动转换为 .docx 再索引；优先使用 soffice/libreoffice，macOS 上可回退 textutil。
前端现在提供“知识库”管理页，可直接上传上述格式文件到 RAG_SOURCE_PATH，查看增量索引进度，并对失败文件单独重试。
CHAT_SESSION_STORE_PATH、CHAT_STREAM_EVENT_STORE_PATH、ARCADE_GEO_CACHE_PATH 会写入 data/runtime/，目录不存在时会自动创建；会话状态和 SSE 事件都会持久化，支持进程重启后的会话详情与流式事件续播。
AMAP_API_KEY 用于高德 REST 路线、逆地理编码和后端地理缓存；高德 Web JS API 的浏览器 key 需要单独配在前端。

4. 配置 MCP

默认会扫描 backend/app/agent/tools/mcp/servers/*.json。当前内置高德配置如下：

{
  "transport": "streamable-http",
  "url": "https://mcp.amap.com/mcp?key=${AMAP_API_KEY}"
}

文件名会成为 server name，例如 amap.json 会注册为 amap，远端工具会投影成类似 mcp__amap__maps_direction_walking 的本地工具名。

如果第三方 MCP 工具命名发生变化，可以在同一个 JSON 里显式指定路线工具：

{
  "transport": "streamable-http",
  "url": "https://mcp.amap.com/mcp?key=${AMAP_API_KEY}",
  "route_tool_name": "maps_direction_walking"
}

也支持标准 MCP config fragment：

{
  "mcpServers": {
    "fetch": {
      "transport": "sse",
      "url": "https://example.com/mcp"
    }
  }
}

5. 启动后端

macOS / Linux:

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 --access-log

Windows PowerShell:

cd backend
.venv\Scripts\Activate.ps1
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 --access-log

启动后可访问：

Health: http://localhost:8000/health
Swagger: http://localhost:8000/docs

/health 会返回数据加载状态、tool provider 状态和 MCP discovery 状态。高德 MCP 问题优先看 mcp.servers.amap.available_tools、selected_route_tool 和 last_error。

6. 配置并启动前端

复制前端环境变量：

macOS / Linux:

cp apps/web/.env.example apps/web/.env.local

Windows PowerShell:

Copy-Item apps/web/.env.example apps/web/.env.local

apps/web/.env.local：

VITE_API_BASE=http://127.0.0.1:8000
VITE_SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
VITE_SUPABASE_ANON_KEY=
VITE_AMAP_WEB_KEY=
VITE_AMAP_SECURITY_JS_CODE=
VITE_AMAP_URI_SRC=arcadegent_web

注意：VITE_AMAP_WEB_KEY 必须是高德 Web JS API 可用的浏览器 key，不能直接复用只给 REST / MCP 用的 key，否则页面会报 USERKEY_PLAT_NOMATCH 或类似鉴权错误。

JWT 登录配置

项目使用 Supabase Auth 签发 Access Token，FastAPI 通过 Supabase JWKS 验证 JWT。无需在本机额外安装数据库。

在 Supabase 控制台开启 Email 登录；根据需要决定是否要求邮箱确认。
将项目 URL 和 anon key 同时配置到 SUPABASE_* 与 VITE_SUPABASE_*。
确认 JWKS 地址可访问后，将 AUTH_ENABLED 改为 true。
重新启动后端并重新构建前端。只配置 VITE_SUPABASE_* 会显示登录页，但后端不会启用保护；APP_ENV=production 时后端会强制要求 AUTH_ENABLED=true，并校验 issuer、audience、算法及验签密钥配置，缺失任一项都会拒绝启动。

开启后，聊天和 SSE 接口必须携带 Authorization: Bearer <token>，会话归属以 JWT 的 sub 为准，客户端提交的 client_id 不参与授权。知识库读取仍可用，但上传、删除、重建索引要求 JWT 中的 app_metadata.role 为 admin。

管理员角色应通过可信后端或 Supabase 管理接口写入 app_metadata，不要使用用户可自行修改的 user_metadata。旧版 Supabase 项目如果只提供 HS256 secret，可设置 JWT_SECRET 和 JWT_ALGORITHMS=HS256；新项目优先使用 JWKS。

设置和修改用户角色

用户必须先在 Arcadegent 完成注册，使账号出现在 Supabase 的 auth.users 表中。然后进入 Supabase Dashboard 对应项目的 SQL Editor，通过邮箱将普通用户提升为管理员：

update auth.users
set raw_app_meta_data =
  coalesce(raw_app_meta_data, '{}'::jsonb)
  || '{"role":"admin"}'::jsonb
where email = 'admin@example.com'
returning id, email, raw_app_meta_data;

将管理员恢复为普通用户：

update auth.users
set raw_app_meta_data =
  coalesce(raw_app_meta_data, '{}'::jsonb)
  || '{"role":"user"}'::jsonb
where email = 'user@example.com'
returning id, email, raw_app_meta_data;

查询并确认当前角色：

select id, email, raw_app_meta_data
from auth.users
where email = 'admin@example.com';

角色修改后，用户必须在 Arcadegent 中退出并重新登录，Supabase 才会签发包含新 app_metadata.role 的 JWT。未设置角色的账号默认按 user 处理。

权限规则如下：

user：使用聊天和个人会话、查看正式知识库、提交文档、查看和撤回自己的待审核投稿。
admin：拥有普通用户能力，并可审核全部投稿、直接维护正式知识库、删除文档和重建索引。
角色必须保存在 raw_app_meta_data（JWT 中对应 app_metadata），不能保存在用户可修改的 raw_user_meta_data。
不要在浏览器端使用 service_role key 修改角色；该密钥只能保存在可信后端或安全的管理环境中。

知识文档投稿与审核

登录用户可以在知识库页面提交受支持的文档并查看自己的投稿记录。投稿首先保存在独立审核区，不会被 RAG 检索；用户可以撤回仍处于 pending 的投稿。管理员能查看全部投稿并进行通过或驳回，只有通过后的文件才会复制到正式知识目录并触发增量索引。

本地文件模式使用以下配置，默认值可直接用于单机部署：

KNOWLEDGE_SUBMISSION_STORE_PATH=data/runtime/knowledge_submissions.json
KNOWLEDGE_SUBMISSION_FILES_PATH=data/runtime/knowledge_submissions
KNOWLEDGE_SUBMISSION_MAX_BYTES=10485760
KNOWLEDGE_SUBMISSION_BLOCKED_KEYWORDS=色情,赌博网站,毒品交易,诈骗教程,暴力恐怖
KNOWLEDGE_SUBMISSION_REJECT_IMAGES=true
KNOWLEDGE_SUBMISSION_SCAN_MAX_CHARS=500000

投稿状态包括 pending、approved、rejected、withdrawn。审核接口要求 app_metadata.role=admin；投稿列表对普通用户自动按 JWT sub 隔离，管理员可以查看全部记录。

投稿进入人工审核前会先执行自动内容筛选：文件名、投稿标题、说明和正文都会扫描 KNOWLEDGE_SUBMISSION_BLOCKED_KEYWORDS 中以逗号分隔的关键词，匹配忽略大小写；命中后投稿直接标记为 rejected，原文件不会保存。启用 KNOWLEDGE_SUBMISSION_REJECT_IMAGES=true 时，包含嵌入图片的 PDF 或 DOCX 同样会自动驳回。损坏、无法可靠解析的文件以及旧版 .doc 会按失败关闭原则自动驳回，避免绕过扫描。自动驳回原因会写入投稿的审核意见，供投稿者和管理员查看。

关键词规则应根据实际运营要求维护；不要把该机制视为完整的恶意软件或违法内容检测。生产环境还应在文件存储入口增加病毒扫描、上传频率限制，并对自动驳回记录进行人工抽查。

启动：

cd apps/web
npm run dev

打开：

Chat: http://localhost:5173
Arcade Explorer: http://localhost:5173/arcades

Docker 启动

Docker 方式会启动两个容器：

backend：FastAPI 服务，容器内端口 8000
web：Nginx 托管前端静态产物，并把 /api/*、/api/stream/*、/health 反代到后端

1. 安装并启动 Docker

macOS / Windows 本地开发推荐安装 Docker Desktop。安装后需要先启动 Docker Desktop，再运行 compose 命令；只安装 Docker CLI 但 daemon 没启动时，会看到类似错误：

Cannot connect to the Docker daemon at unix:///Users/xxx/.docker/run/docker.sock. Is the docker daemon running?

macOS 可用：

open -a Docker
docker version

Windows PowerShell 可用：

Start-Process "Docker Desktop"
docker version

docker version 同时显示 Client 和 Server 信息，才说明 Docker daemon 已经可用。如果只显示 Client 后报 Cannot connect to the Docker daemon，请等待 Docker Desktop 完全启动，或在 Docker Desktop 里切到 Linux containers。

Linux / 阿里云服务器可安装 Docker Engine 和 Compose plugin：

docker version
docker compose version

2. 准备环境变量

首次启动前先准备根目录 .env：

macOS / Linux:

cp backend/.env.example .env

Windows PowerShell:

Copy-Item backend/.env.example .env

如果需要内嵌高德地图，把浏览器侧 key 放到根目录 .env。这些 VITE_* 变量会在前端镜像构建时写入静态包，修改后需要重新 build：

VITE_AMAP_WEB_KEY=
VITE_AMAP_SECURITY_JS_CODE=
VITE_AMAP_URI_SRC=arcadegent_web

真实数据和运行缓存仍放在宿主机 data/ 目录。该目录会挂载到后端容器内的 /app/data，但不会进入镜像。

3. 启动

启动：

docker compose up --build

后台启动：

docker compose up -d --build

打开：

Web: http://localhost:8080
Health: http://localhost:8080/health
Backend Swagger: http://localhost:8000/docs

默认端口只绑定到宿主机 127.0.0.1，便于后续由宿主机 Nginx 统一对外反代。如需临时从局域网访问，可以启动时覆盖绑定地址：

macOS / Linux:

WEB_BIND=0.0.0.0 BACKEND_BIND=0.0.0.0 docker compose up --build

Windows PowerShell:

$env:WEB_BIND="0.0.0.0"
$env:BACKEND_BIND="0.0.0.0"
docker compose up --build

Windows CMD:

set WEB_BIND=0.0.0.0
set BACKEND_BIND=0.0.0.0
docker compose up --build

4. 常用命令

docker compose ps
docker compose logs -f backend
docker compose logs -f web
docker compose down

如果 Windows / macOS 首次构建时拉取基础镜像较慢，可以先确认 Docker Desktop 已登录并能访问 Docker Hub；也可以配置镜像加速器后再执行 docker compose up --build。

服务器部署提示

推荐的迁移形态是：Docker Compose 在服务器本机启动前后端，宿主机 Nginx 对外监听 80/443，并把 API、SSE 和静态页面分别反代到本机端口。

浏览器定位在公网域名下要求 HTTPS 安全上下文；localhost 是开发例外。线上如果只用 http:// 访问，浏览器通常不会弹出定位授权框，前端也就不会把 client_location 注入会话。请给域名配置 TLS 证书，并让 80 端口跳转到 443。部署示例里的 Permissions-Policy: geolocation=(self) 用于明确允许本站调用定位能力。

在服务器安装 Docker、Docker Compose plugin 和 Nginx。
上传代码、根目录 .env，以及私有数据目录；如果使用数据库读模型，则确认 .env 中数据库变量可用。
在项目根目录执行 docker compose up -d --build。
参考 deploy/nginx/arcadegent.conf.example 配置站点，把 server_name example.com 改成实际域名。
执行 sudo nginx -t && sudo systemctl reload nginx。
安全组只需要开放 80/443；8000/8080 默认只监听 127.0.0.1，无需对公网开放。

SSE 事件流依赖长连接，Nginx 配置里 /api/stream/ 已关闭 buffering，并把 proxy_read_timeout 调高；如果再接一层负载均衡，也要保留同样的长连接设置。

API 概览

GET /health：健康检查、数据加载状态、tool provider 和 MCP discovery 状态
GET /api/arcades：机厅列表、筛选、排序和分页
GET /api/arcades/{source_id}：机厅详情
GET /api/regions/provinces：省份列表
GET /api/regions/cities：城市列表，参数 province_code
GET /api/regions/counties：区县列表，参数 city_code
POST /api/location/reverse-geocode：浏览器坐标逆地理编码
POST /api/chat：同步 Agent 对话入口
POST /api/chat/sessions：异步派发 Agent 会话，前端默认使用
GET /api/stream/{session_id}：SSE 实时事件流，支持 last_event_id 和 Last-Event-ID
GET /api/chat/sessions：历史会话列表
GET /api/chat/sessions/{session_id}：会话详情、历史 turns、地图 artifacts
DELETE /api/chat/sessions/{session_id}：删除会话

Agent 运行时

Agent 配置分为几层：

Subagent 定义：backend/app/agent/nodes/definitions/*.yaml
Provider profile：backend/app/agent/nodes/profiles/provider_profiles.yaml
Tool policy：backend/app/agent/nodes/profiles/tool_policies.yaml
Prompt：backend/app/agent/context/prompts/*.md
Skill：backend/app/agent/context/skills/*.md
Builtin tool manifest：backend/app/agent/tools/builtin/tools_manifest.json
Builtin tool schema：backend/app/agent/tools/builtin/schemas/*.json
MCP server 配置：backend/app/agent/tools/mcp/servers/*.json

当前主流程是 main_agent 识别意图并调度 worker。search_worker 负责机厅查询，navigation_worker 负责目标解析和路线规划，最终再由 summary 流程生成用户可见回复。

路线规划优先尝试可用的高德 MCP 路线工具；不可用时使用内置 route_plan_tool，该工具会先请求高德 REST 路线 API，失败后退化为离线直线距离和估算时间。

数据说明

公开仓库不包含真实机厅数据、抓取产物、运行缓存或生产数据库迁移。后端只要求运行时提供兼容的数据源：

JSONL 模式：设置 ARCADE_DATA_SOURCE=jsonl，并让 ARCADE_DATA_JSONL 指向本地私有 JSONL 文件。
数据库模式：设置 ARCADE_DATA_SOURCE=supabase，并配置对应数据库连接变量。
Docker 模式：宿主机 data/ 会挂载到后端容器的 /app/data，适合放置本地私有 JSONL 和运行缓存。

所有密钥只写入本机 .env 或部署环境变量，不提交到仓库。

常用开发命令

后端测试：

cd backend
python -m pytest -q

前端开发：

cd apps/web
npm run dev

前端打包：

cd apps/web
npm run build

前端 E2E：

cd apps/web
npm run test:e2e

Agent 回归与故障演练：

backend/.venv/bin/python backend/scripts/run_agent_regression.py
cd apps/web
npm run test:e2e:golden

详细说明见 docs/dev-details/agent-regression-and-drills.md。

RAG 测评与质量门禁：

backend/.venv/bin/python backend/scripts/evaluate_rag.py \
  --dataset backend/evaluation/datasets/arcadegent_demo_v2.json \
  --source-path backend/evaluation/fixtures/knowledge \
  --embedding-model local-hash-v1 \
  --top-k 5 \
  --cutoffs 1,3,5 \
  --fail-on-gate

评测系统支持检索、上下文事实、答案、引用、可选 LLM Judge、标签切片、延迟、基线对比和 CI 门禁。完整的数据集格式与实验方法见 backend/evaluation/README.md。

Hugging Face 中文模型、缓存和离线部署见 backend/docs/HUGGINGFACE_SETUP.md。

故障排查

后端启动但无数据：检查 ARCADE_DATA_JSONL 是否存在，或访问 /health 看 store 状态。
Agent 回复 provider 错误：检查 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL 和 AGENT_PROVIDER_PROFILE。
高德 MCP 没有路线：访问 /health，查看 mcp.servers.amap.available_tools、selected_route_tool、last_error，必要时配置 route_tool_name。
浏览器不弹定位授权：确认线上页面是 https:// 打开，外层 Nginx 或 CDN 没有设置禁止定位的 Permissions-Policy，并在浏览器地址栏站点设置里清除旧的定位拒绝记录。
前端地图不可用：检查 VITE_AMAP_WEB_KEY 是否是 Web JS API key，必要时配置 VITE_AMAP_SECURITY_JS_CODE。
路线只有直线估算：通常是高德 MCP 和 REST 都不可用，检查 AMAP_API_KEY、额度、网络和 /health。
前端跨域错误：确认 .env 里的 CORS_ALLOW_ORIGINS 包含当前 Vite 地址。

当前限制

JWT 认证、会话用户隔离和知识库管理员权限已接入；更细粒度的 RBAC 与组织级权限模型尚未实现。
公开仓库不附带真实数据集；本地体验完整检索能力需要自行准备兼容数据源。
MCP discovery 依赖第三方服务返回的 tool schema，远端命名变化时可能需要手动指定 route_tool_name。
没有高德 Web JS key 时，前端仍可列表检索并生成高德跳转 URI，但内嵌地图不可用。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apps/web		apps/web
backend		backend
deploy/nginx		deploy/nginx
docs		docs
shared/schemas		shared/schemas
supabase/migrations		supabase/migrations
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
INTERVIEW_PREP_ARCADEGENT.md		INTERVIEW_PREP_ARCADEGENT.md
RAG_OPTIMIZATION_COMPLETION_REPORT.md		RAG_OPTIMIZATION_COMPLETION_REPORT.md
README.md		README.md
docker-compose.yml		docker-compose.yml
pytest.ini		pytest.ini

Navigation Menu

Repository navigation

About

Repository files navigation

Arcadegent

功能概览

技术栈

目录结构

文档入口

环境要求

快速开始

1. 安装后端依赖

2. 安装前端依赖

3. 配置后端环境变量

4. 配置 MCP

5. 启动后端

6. 配置并启动前端

JWT 登录配置

设置和修改用户角色

知识文档投稿与审核

Docker 启动

1. 安装并启动 Docker

2. 准备环境变量

3. 启动

4. 常用命令

服务器部署提示

API 概览

Agent 运行时

数据说明

常用开发命令

故障排查

当前限制

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Arcadegent

功能概览

技术栈

目录结构

文档入口

环境要求

快速开始

1. 安装后端依赖

2. 安装前端依赖

3. 配置后端环境变量

4. 配置 MCP

5. 启动后端

6. 配置并启动前端

JWT 登录配置

设置和修改用户角色

知识文档投稿与审核

Docker 启动

1. 安装并启动 Docker

2. 准备环境变量

3. 启动

4. 常用命令

服务器部署提示

API 概览

Agent 运行时

数据说明

常用开发命令

故障排查

当前限制

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages