Demo 服务

Demo 本地联调现在默认会带起六个表面：AI 服务、Socket.IO 后端、Demo 前端、Admin 前端、outlook-index 和 outlook-addin。当前 realtime 拓扑仍是 demo-frontend -> demo-backend -> ai-service：浏览器只和 demo-backend 建立 websocket，demo-backend 再桥接 ai-service 的公共会话 websocket。数据流如下：

sequenceDiagram
  participant UI as demo-frontend
  participant Backend as demo-backend
  participant AI as ai-service
  UI->>Backend: Socket.IO /api/socket.io + user_message
  Backend->>AI: WS /public/ws/{session_id}?role=customer
  AI-->>Backend: history, session, message, system, takeover_event
  Backend-->>UI: ai_response envelope relay

一键启动

just demo-up

该命令会按系统类型启动多个进程，适合本地联调。启动前会先注入仓库根目录 .env 与 .env.local，其中 .env.local 会覆盖 .env 中的同名键。若默认本地端口已被其他进程占用，just demo-up 会统一为本地 AI 服务、Demo 后端、Demo 前端、Studio Admin 与 Outlook Index 分配一组可用端口，并将结果写入 .claude/runtime/local-dev.env。每次重新执行 just demo-up 时，会先清理当前 worktree 记录过的遗留进程或本地 demo 端口，再刷新这份端口映射，避免复用已经失效的旧端口。在 Linux 与 macOS 上，just demo-up 会记录当前 worktree 启动出的本地进程 PID 到 .claude/runtime/local-dev.pids，并注册默认 480 分钟后自动执行 just demo-down 的 watchdog；下一次 demo-up 或 demo-down 会先清掉这批遗留进程和 watchdog，再读取 .claude/runtime/local-dev.env 并使用本机端口扫描清理对应监听端口。macOS 后台进程日志写入 .claude/runtime/logs/。如需调整自动清理时间，请将 DEMO_AUTO_STOP_MINUTES 写入仓库根目录 .env.local；设为 0 可禁用自动清理。临时覆盖时也可以在命令前设置该变量。当前启动链路还会在打开前端前等待本地 ai-service 与 demo-backend 就绪，避免 Vite 代理在首屏阶段命中未监听端口。现在 just demo-up 也会一并启动 outlook-index 和 outlook-addin。其中 outlook-index 的 URL 会写入 .claude/runtime/local-dev.env 中的 OUTLOOK_INDEX_URL；outlook-addin 默认使用固定开发地址 https://localhost:3100。

手动启动

如需保持与 just demo-up 一致的根目录 env 注入行为，可使用：

just run-ai-backend
just run-demo-backend
just run-demo-frontend
just run-admin-frontend
just run-outlook-index
just run-outlook-addin

如需完全手动启动，也可以直接运行：

uv run python main.py

cd demo-backend
uv run python app/main.py

cd demo-frontend
npm install
npm run dev

cd admin-frontend
npm install
npm run dev

关键说明

just demo-up 启动 AI 服务时会走 main.py 启动路径：在 APP_ENV=development 下默认自动执行数据库迁移（DB_MIGRATION_MODE=auto）。
demo-backend/app/main.py 默认请求 http://localhost:8000 的 AI 服务；可通过 AI_SERVICE_URL 覆盖，也可统一设置 AI_SERVICE_PORT 让本地后端和两个 Vite 前端一起跟随新端口。
Demo 前端通过同源 /api/socket.io 与 demo-backend 建立 Socket.IO 连接，同时通过其余 /api 路径访问 Demo 后端（http://localhost:3000）。
Demo 后端既承接同源 HTTP 代理，例如模型、Agent 和 demo job 接口，也承接 demo 聊天 realtime gateway，再向 ai-service 的 WS /public/ws/{session_id} 转发与回传会话事件。
demo-frontend 里的 AI Docs 工作台当前仍聚焦 Fusion workspace；document-recognition 自身的上传、review 与 admin history 继续由独立单证识别控制面承载。
outlook-index 现在通过 canonical /api/document-recognition/* 进入单证识别链路；Fusion 只保留为底层 runtime。该前端仍允许选择已注册的 Fusion runtime agent、查看 canonical workspace_output，并支持字段到 bbox 的联动高亮。just demo-up 会一并启动该前端；开发模式下 /api 默认代理到 demo-backend。
admin-frontend 的 Document Recognition 页面会同时展示 legacy extraction jobs 与符合条件的 Fusion runs。
outlook-addin 现在也会由 just demo-up 一并启动，默认开发地址是 https://localhost:3100；它会把 VITE_OUTLOOK_INDEX_URL 自动指向本地 outlook-index，用于从 Outlook 入口跳转到详细工作区。
Studio Admin 是独立 Vite 应用，默认监听 5175，并以根路径 / 作为 base path；它同样代理 /api 到 AI 服务。
just run-admin-frontend 是当前唯一受支持的本地 Admin 前端启动配方。ADMIN_FRONTEND_PORT 现已作为主端口命名；旧的 STUDIO_ADMIN_FRONTEND_* 仅保留兼容别名。
当前 Studio 已具备真实可写模块：Knowledge Sources、MCP Servers、Evaluation Datasets、Administrators、Agents 与 System Settings。Audit Logs、Conversations、Scheduled Tasks、Document Recognition 仍主要提供运营排查、筛选与诊断能力。
Docker / deployment 侧默认直接以根路径 / 提供 Studio；旧的 /studio/* 链接会自动重定向到对应根路径。
.claude/runtime/local-dev.env 仅用于本地进程协调，不参与 Docker Compose 容器部署；其中也会写入 Demo 前端 URL 与 Studio Admin URL，供本地前端链路共享同一组动态端口。

SSH 隧道访问说明

对外暴露 5173 和 5175 即可访问两个前端页面。