DeepTutor 伙伴 APP DEV DOC v1.0

01项目概述

把 Web 端「伙伴」体验浓缩进手机：打开即聊、流式输出、会话延续。

做什么：一个移动 APP，登录自部署的 DeepTutor 实例，列出学习伙伴，选择伙伴进入聊天界面，支持流式回复（含 thinking 过程展示）、多会话管理、会话内上下文延续。

不做什么（明确出界）：知识库管理、智能写作、书籍/学习空间、模型与插件配置——这些留在 Web 端。APP 专注「与伙伴对话」这一件事。

1.1北极星场景

• 孩子在平板/手机上直接找 Dina（英语老师） 要当天的阅读材料、报进度
• 临时想问 Histira（历史） 或 Geona（地理） 一个问题，不用开电脑
• 碎片时间翻看历史会话继续聊（Web 端的会话在 APP 内无缝接续）

1.2成功标准

02服务端现状（实测）

以下全部信息于 2026-09-15 用临时管理员账号对生产实例逐一探测验证，非文档想象。

2.1现有伙伴（3 个，全部 auto-start 运行中）

03系统架构

零后端改造方案：APP 作为纯客户端直接复用 DeepTutor 既有 REST + SSE 接口。

┌─────────────────────┐        ┌─────────────────────────── 43.161.202.95 ──────────────────────────┐
│   移动设备 (iOS/And) │        │                                                                    │
│                     │  TLS   │  ┌──────────┐      ┌──────────────────────────────────────┐     │
│  ┌───────────────┐  │ HTTPS  │  │  nginx   │─────▶│  DeepTutor 容器 (deeptutor:latest)   │     │
│  │ Flutter APP   │──┼───────▶│  │  :443    │ /api/*│  ┌────────────┐  ┌───────────────┐  │     │
│  │               │  │        │  │  LE证书  │─────▶│  │ Next 前端   │  │ FastAPI 后端  │  │     │
│  │ ·登录/JWT     │  │        │  └──────────┘ 反代  │  │  :3782      │─▶│  :8001 内部   │  │     │
│  │ ·伙伴列表     │  │        │         ▲           │  └────────────┘  └───────┬───────┘  │     │
│  │ ·SSE 流式聊天 │  │        │         │ SSE(长连接) │  数据卷 deeptutor-data    │     │
│  │ ·会话管理     │  │        │         └──────────────────────────────────│──▶ SQLite/JSON   │
│  │ ·SQLite 缓存  │  │        │                                                   │  data/partners/  │
│  └───────────────┘  │        │                                                   │  data/user/…     │
└─────────────────────┘        └────────────────────────────────────────────────────┴──────────┘

请求路径:  APP ──TLS──▶ nginx :443 ──▶ Next 中间件 /api/* 重写 ──▶ FastAPI :8001
SSE 路径:  POST /api/v1/partners/{id}/chat/execute-stream  (text/event-stream, 无 nginx 缓冲)

关键架构决策：

1. 纯客户端方案——不改 DeepTutor 任何代码，升级镜像不影响 APP
2. 所有请求走 /api/v1/* 真实前缀（Next 中间件负责转发到 FastAPI :8001），APP 不感知内部端口
3. 数据主权在服务端：APP 本地只做只读缓存，一切写操作（发消息/删会话）以服务端结果为准

04技术选型

单代码库覆盖 iOS + Android，一个人可维护。

4.1推荐技术栈（Flutter）

05认证设计

复用 DeepTutor 原生 JWT，APP 侧只做存储、注入与续期。

5.1登录时序

APP                        DeepTutor API
 │                              │
 │  POST /api/v1/auth/login     │
 │  {username, password}        │
 │─────────────────────────────▶│
 │                              │ 验证 bcrypt 哈希 (users.json)
 │◀─────────────────────────────│
 │  200 {ok:true, role:"admin"} │
 │  Set-Cookie: dt_token=JWT    │  ← HttpOnly · Secure · 30天
 │      (body 不含 token!)      │
 │                              │
 │  ── 提取 cookie 值存入 ──▶ Keychain/Keystore
 │                              │
 │  GET /api/v1/partners        │
 │  Cookie: dt_token=JWT        │  ← 或 Authorization: Bearer JWT
 │─────────────────────────────▶│
 │◀──── 200 [伙伴列表] ─────────│

5.2Token 生命周期

06API 参考（实测端点）

Base URL：https://deeptutor.hms.jude.pub · 全部 JSON · 鉴权：Authorization: Bearer <jwt>

6.1认证

// 登录（实测响应）
POST /api/v1/auth/login
{"username":"<管理员账号>","password":"<密码>"}

HTTP/1.1 200 OK
Set-Cookie: dt_token=eyJhbGciOiJIUzI1NiIs...; HttpOnly; Secure; Max-Age=2592000
{"ok":true,"user_id":"u_fdc6…","username":"…","role":"admin","is_admin":true}

6.2伙伴

// GET /api/v1/partners（实测，节选）
[{"partner_id":"dina","name":"Dina","description":"英语老师",
  "channels":[],
  "llm_selection":{"model_id":"llm-model-…","profile_id":"llm-profile-…"},
  "language":"zh","emoji":"🐶","color":"","avatar":"",
  "soul_origin":{"id":"","type":"custom"},
  "running":true,"started_at":"2026-09-15T02:33:45Z","last_reload_error":null},
 …]

6.3会话与历史

// GET /api/v1/partners/dina/sessions（实测，节选）
[{"session_key":"web-kdprapow",
  "title":"我正在学习这套教材，目前正在学习第一本的Unit9…",
  "message_count":16,"updated_at":"2026-09-12T06:47:17Z",
  "last_message":"第 7 期交付完毕 ✅ 进度已记录（下次 9 月 15 日 Unit 16）…",
  "archived":false},…]

// GET …/history?session_key=web-kdprapow（实测，节选）
[{"role":"assistant","content":"9 月 9 日，第 6 期准时送达 🎉 今天进入 **第 1 册 Unit 14…"},…]

6.4发消息（两种模式）

两种模式共享同一请求体（ChatMessageRequest）：

{
  "content":        "用一句话介绍你自己",   // 必填（或有附件）
  "session_key":    "web-kdprapow",        // 续接已有会话；新会话传自定义 key（如 "app-xxx"）或不传
  "session_id":     null,                  // 由 SSE session 事件返回的内部 id，续聊可回传
  "chat_id":        null,
  "attachments":    [],                    // 图片/文件附件结构
  "llmSelection":   null                   // 覆盖模型选择，一般不传
}
// 同步模式响应: {"partner_id":"dina","session_id":"5b5d…","content":"完整回复文本"}

07SSE 流式聊天实现

核心体验：thinking 逐字上屏 → 折叠 → 正文逐字上屏。协议已实测。

7.1事件序列（实测抓包）

event: session                    ← ① 第一帧: 建立会话
data: {"partner_id":"dina","session_id":"5b5d4b4a1e9b4e7c8a759ad3f035f474"}

event: thinking                   ← ② 推理过程, 多帧增量
data: {"content":"用户"}
data: {"content":"让我"}
data: {"content":"用一句话"}
…（几十帧, 每帧 2~6 字）

event: content                    ← ③ 正文（增量或整段, 以服务端为准累积）
data: {"content":"你好，我是 Dina——你的学习伙伴，擅长把复杂的知识拆成…"}

event: done                       ← ④ 结束帧: 持久化完成
data: {"partner_id":"dina","session_id":"5b5d…"}

7.2Flutter 解析器（参考实现）

final class SseClient {
  final dio.Response<ResponseBody> _resp;
  SseClient(this._resp);

  Stream<SseEvent> events() async* {
    final lines = _resp.data!.stream
        .cast<List<int>()          // 字节流
        .transform(utf8.decoder)
        .transform(const LineSplitter());
    String? event;
    await for (final line in lines) {
      if (line.startsWith("event:")) {
        event = line.substring(6).trim();
      } else if (line.startsWith("data:") && event != null) {
        yield SseEvent(event!, jsonDecode(line.substring(5).trim()));
        if (event == "done") return;      // 服务端 done 后流自然关闭
      }
    }
  }
}
// 请求侧: dio.post(url, options: Options(responseType: ResponseType.stream, headers: {"Accept":"text/event-stream"}))

7.3状态机与韧性

08数据模型与本地缓存

服务端是唯一事实源；本地 SQLite 只为秒开与离线回看。

/// 伙伴（映射 GET /partners）
class Partner {
  final String partnerId, name, description, language;
  final String? emoji, avatar;          // avatar=data-uri | null
  final String soulType;                 // custom | library
  final bool running;
}

/// 会话（映射 GET /{id}/sessions）
class ChatSession {
  final String partnerId, sessionKey, title, lastMessage;
  final int messageCount;
  final DateTime updatedAt;
  final bool archived;
}

/// 消息（本地扩展持久化字段）
class Message {
  final String partnerId, sessionKey;
  final String role;                    // user | assistant
  final String content;                  // Markdown
  final String status;                   // sending | done | failed  ← APP 私有
  final DateTime createdAt;
}

• 同步策略：进入会话先展示本地缓存，history 返回后 diff 更新（以服务端为胜）；伙伴/会话列表 pull-to-refresh + 5 分钟静默过期
• session_key 约定：APP 新建会话用 app-{uuid8} 前缀（与 Web 端 web-* 区分，排查问题一眼可辨）

09页面与交互设计

5 个页面，深浅色双主题，中文优先。

10安全清单

11里程碑计划

12测试要点

• 隔离原则：对着生产实例测试必须用专用 session_key（如 app-test-*），测完调 sessions/delete 清理——本文档实测即用此模式，用户库与真实会话零污染
• SSE 用例：正常全流程 / 中途断网 / 发送后立刻切后台 / done 未到流被关 / 服务器 5xx
• 会话竞态：APP 与 Web 端同会话交替发消息，history 对账一致
• 登录边界：错误密码（实测 401）、非 admin 账号（403）、过期 token（status 探针）
• 头像边界：emoji 伙伴 / data-uri SVG 伙伴 / 两者皆空（首字母兜底）

13已知限制与风险

附参考资料指针

• 服务端源码：/opt/web/deeptutor/deeptutor/api/routers/partners.py（端点权威定义）、auth.py（鉴权）、unified_ws.py（WS 备选通道）
• 部署细节：~/.hermes/skills/devops/nginx-site-setup/references/deeptutor-deployment.md
• 实例配置：auth.json（JWT 策略）、users.json（账号）路径见服务器文档
• 上游仓库：HKUDS/DeepTutor（多用户模式说明见 v1.3.8+ release notes）