# tutor

**Repository Path**: wkrain/tutor

## Basic Information

- **Project Name**: tutor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tutor-DSH

> AI 教学桌面软件 — 基于 DeepAgents + Electron + Vue 3。
> 五大功能模块:资料管理 / 互动课堂 / AI 助教 / 模拟考试 / 错题本。
> 文档:[docs/README.md](./docs/README.md)(设计文档 + 需求清单索引)

---

## 当前进度:M0 骨架 + AI 助教单角色 PoC

✅ 已完成:
- 项目脚手架(Electron + Vue 3 + Vite + Pinia)
- LLM Provider 抽象(支持任意 OpenAI 兼容协议)
- 配置存储(`~/.tutor/config.json`)
- 教学版 DeepAgent 封装(`TeachingAgentService`)
- AI 助教 IPC(`ta:send-message` / `ta:stop` / `ta:stream`)
- Vue AI 助教页面(对话 + 流式 + 工具调用展示)
- 设置页(LLM 配置 + 连通测试)
- 教学 Skill 文件(`skills/ta/SKILL.md` + `shared/quiz-block-format` + `shared/material-search`)

🚧 M0 待办:
- 在 Windows 实机跑一次端到端(下面有命令)
- 修复启动后可能的环境报错

---

## 环境要求

| 工具 | 版本 |
|---|---|
| Node.js | ≥ 18(实测 20/22 最佳) |
| npm | ≥ 9 |
| Electron | 28+(自动装) |
| Python | 3.8+(仅后续加密技能需要) |

---

## 快速启动

### 1. 安装依赖

```bash
# 根目录(装 Electron + DeepAgents)
npm install

# 前端(Vue 3)
cd web && npm install && cd ..
```

### 2. 配置 LLM(必做)

启动后点击右上角 ⚙ 设置,填:
- **Base URL**: `https://api.deepseek.com/v1`(或任意 OpenAI 兼容端点)
- **API Key**: `sk-...`
- **Model**: `deepseek-chat`(或你的模型名)

支持任何 OpenAI 兼容协议:DeepSeek、通义千问、GLM、Ollama、OpenAI 等。

### 3. 开发模式

```bash
# 终端 1:Vite 开发服务器(端口 5174)
cd web && npm run dev

# 终端 2:Electron 主进程(自动加载 Vite + HMR)
npm run dev:electron
```

### 4. 生产构建

```bash
npm run build  # 同时编译 electron + web
```

---

## 项目结构

```
tutor-dsh/
├── docs/                      # 文档中心:README.md(索引)+ design/(设计)+ requirements/(需求清单)
├── electron/                  # 主进程
│   ├── main.ts               # Electron 入口
│   ├── preload.ts            # contextBridge
│   ├── ipc/
│   │   ├── ta.ipc.ts         # AI 助教 IPC
│   │   └── system.ipc.ts     # 系统设置 IPC
│   ├── services/
│   │   ├── agents/
│   │   │   └── teaching-agent.service.ts  # 教学版 DeepAgent(M0 核心)
│   │   ├── llm/
│   │   │   └── provider.ts   # OpenAI 兼容 LLM 抽象
│   │   ├── config-store.ts   # 配置持久化
│   │   └── paths.ts          # 用户数据目录 ~/.tutor/
│   └── types/index.ts
├── web/                       # 渲染进程(Vue 3)
│   ├── src/
│   │   ├── App.vue
│   │   ├── views/
│   │   │   └── TaView.vue    # AI 助教页面
│   │   ├── components/
│   │   │   ├── ChatMessages.vue
│   │   │   ├── ChatInput.vue
│   │   │   └── SettingsPanel.vue
│   │   ├── stores/
│   │   │   └── ta.store.ts   # Pinia
│   │   ├── types/
│   │   │   └── tutor-api.d.ts
│   │   └── main.ts
│   ├── index.html
│   ├── vite.config.ts
│   └── package.json
├── skills/                    # 教学技能(SKILL.md 规范)
│   ├── ta/SKILL.md
│   └── shared/
│       ├── quiz-block-format/SKILL.md
│       └── material-search/SKILL.md
├── package.json
├── tsconfig.json
└── README.md
```

---

## M0 验收清单

| # | 验收点 | 命令 / 操作 |
|---|---|---|
| 1 | 项目能装依赖 | `npm install && cd web && npm install` |
| 2 | Electron 主进程编译通过 | `npm run build:electron` |
| 3 | Vite 前端启动 | `cd web && npm run dev` → 访问 http://localhost:5174 |
| 4 | Electron 启动加载 Vue | `npm run dev:electron` |
| 5 | 设置页可保存 LLM 配置 | 点 ⚙ → 填 baseURL/apiKey/model → 保存 |
| 6 | AI 助教对话流式输出 | 在助教页面输入"什么是 Transformer",看流式回复 |
| 7 | Skill 自动加载 | `~/.tutor/skills/ta/SKILL.md` 被 DeepAgent 注入 systemPrompt |
| 8 | 工具调用可视化 | 后续阶段(M1+)才能验证 |
| 9 | AG-UI 事件流 | 在 DevTools 看 `ta:stream` 事件 |

---

## 借鉴自 Cowork

本项目核心设计借鉴自 `D:\codes\cowork`(MIT):
- DeepAgent 生命周期管理(createDeepAgent + MemorySaver + thread_id)
- AG-UI 流式事件适配(LangChain chunk → 前端事件)
- Skill 中间件(SKILL.md 扫描 + frontmatter 注入)
- LocalSandbox 文件隔离
- IPC Layer Pattern(`<topic>.ipc.ts` + preload contextBridge)

教学版**独有**:
- 5 角色 DeepAgent(讲师/助教/学伴/设计官/出题官)
- Supervisor 多 Agent 编排
- 教学版 CompositeBackend(`/materials/` `/course/` `/wrongbook/`)
- 互动块事件(`quiz` / `dsh-page` / `dsh-model`)
- 加密 `.skillx` 教学版权保护

详见 [docs/design/设计-00-总体设计.md](./docs/design/设计-00-总体设计.md) 及 [docs/README.md](./docs/README.md) 文档索引。

---

## 路线图

| 阶段 | 内容 | 状态 |
|---|---|---|
| **M0** | 项目骨架 + TaAgent 端到端 PoC | ✅ 完成 |
| **M1** | Supervisor + 5 角色 + Agent 池 | ✅ 完成 |
| **M2** | 资料管理(参照 pageindexplus + LanceDB) | ✅ 完成 |
| **M3** | 互动课堂(大纲+课件生成,Anthropic Skills + Tool) | ✅ 完成 |
| **M4** | 模拟考试(出卷/判分,左导航) | ✅ 完成 |
| **M5** | AI 助教(RAG + 错题讲解) | 🚧 下一步 |
| **M6** | electron-builder 打包 | 📋 |

合计工期:11-13 周。

---

## M2 已落地内容(资料管理,完全参照 pageindexplus + LanceDB 替换 Milvus)

- **架构对齐 pageindexplus**:Parser → DIBuilder → PIBuilder → LogicTableBuilder → Embedder → VectorStore → Pipeline.build()(BM25 稀疏通道在检索层实时构建,索引期不生成)
- **目录布局** (`~/.tutor/data/`):
  ```
  default/<docId>/
    ├── original.<ext>     ← 原文件备份
    ├── source.md          ← 解析后的 markdown
    ├── page_index.json    ← PageIndex 嵌套树
    └── embed.json         ← 含向量的逻辑表
  indices/
    ├── vectors.lancedb/   ← LanceDB 嵌入式(替换 Milvus vectors.db)
    └── (BM25 为检索层内存倒排,随向量表版本重建,不落盘)
  manifest.json           ← 全局资料清单
  ```
- **LanceDB 实现**(替换 pageindexplus 的 MilvusDB):
  - 同接口契约 `VectorDB Protocol`,可未来切换其他后端
  - 稠密向量字段固定为 `FixedSizeList<Float32>`(否则建不了 ANN 索引)
  - 混合检索:Retriever 层 RRF 融合 dense 向量 + BM25 内存倒排(extract/bm25.ts,中文 CJK 二元组分词;docId/docIds 过滤下推)
- **M2 后端文件**(全部通过 tsc 编译):
  ```
  electron/services/materials/
    ├── model/        (file-item, pi-model, build-model, config-key)
    ├── config/       (properties)
    ├── parser/       (base, pdf, docx, pptx, text, factory)
    ├── builder/      (di-builder, pi-builder, logic-table-builder)
    ├── embed/        (base, embedding - DeepSeek 兼容远程)
    ├── store/        (base, lancedb, vector-store)
    ├── extract/      (bm25)
    ├── retriever/    (retriever)
    ├── task/         (pipeline, manifest)
    └── service.ts    (MaterialService 总入口)
  electron/ipc/material.ipc.ts          ← IPC handler
  ```
- **M2 前端**:
  ```
  web/src/
    ├── stores/material.store.ts        ← Pinia
    └── views/MaterialsView.vue         ← 列表 + 拖拽 + 搜索 + 详情
  ```
- **IPC 接口**:`material:pick-file` / `upload` / `list` / `get` / `search` / `delete` / `on-changed`

---

## 许可

待定(项目开源前请确认 MIT 是否合适)。