132 lines
6.0 KiB
Markdown
132 lines
6.0 KiB
Markdown
# VizTyp
|
|
|
|
> **"可本地优先的语雀" + "实时可视化的 MrDoc"**
|
|
> 基于 [Typst](https://typst.app) 的个人与团队知识管理系统,通过 `typst.ts` WASM 实时编译渲染,配合 Rust HTTP 后端。采用思源笔记风格 IDE 布局,面向 Web 和 Tauri 桌面双平台。
|
|
|
|
[English](./README.md)
|
|
|
|
---
|
|
|
|
## 功能特性
|
|
|
|
### 📝 文档编辑
|
|
|
|
- **Typst 实时编辑** — CodeMirror 6 编辑器,思源风格主题,语法高亮
|
|
- **实时 SVG 预览** — typst.ts WASM 浏览器内编译,防抖渲染
|
|
- **多 Tab 管理** — 多文档并行编辑,未保存指示
|
|
- **查找替换** — CodeMirror 内置搜索面板(Ctrl+H)
|
|
- **文件 I/O** — 打开/保存 .typ 文件,导出 PDF/SVG(Web 下载 + Tauri 原生对话框)
|
|
|
|
### 📚 知识库管理
|
|
|
|
- **知识库 CRUD** — Workspace → KnowledgeBase → Document 三层结构
|
|
- **文档树导航** — KB 列表 → 文档两级树展开(类语雀)
|
|
- **草稿/发布分离** — `.typ.draft` sidecar 草稿,发布时提升 + 清除草稿
|
|
- **版本历史** — MrDoc 式完整快照,发布自动存档,一键恢复任意版本
|
|
- **文档标签** — 文档级标签,持久化存储
|
|
- **TOC 解耦** — 独立 TOC 树(借鉴语雀模式),不硬编码在文档内容中
|
|
|
|
### 🔍 搜索与发现
|
|
|
|
- **权限感知全文搜索** — 跨知识库搜索,预过滤用户可见 KB(借鉴 MrDoc)
|
|
- **跨标签搜索** — 在已打开 Tab 中即时搜索
|
|
- **可视化依赖图** — 手写 SVG,实时解析 `#include`/`#import`/`#image` 构建知识图谱
|
|
- **大纲导航** — Typst `#heading` 解析,点击跳转
|
|
- **编译诊断** — typst.ts 编译错误实时显示
|
|
|
|
### 👥 协作与权限
|
|
|
|
- **用户认证** — JWT 注册/登录,SHA-256 密码哈希
|
|
- **KB 可见性** — 4 级:public / private / specified / access_code
|
|
- **协作者角色** — reader(只读)/ writer(可写)/ admin(管理)
|
|
- **文档分享** — 独立于 KB 权限的单文档分享令牌(公开/访问码)
|
|
- **在线状态** — presence 轮询,状态栏显示在线协作者
|
|
|
|
### 🔌 系统扩展
|
|
|
|
- **插件系统** — 内置 TS 插件 + 钩子体系(onCompile/onSave/onPublish/onRender)
|
|
- **CSS/JS 片段** — CSS 动态注入页面样式,JS 配置型
|
|
- **命令面板** — Ctrl+K 模糊搜索所有命令
|
|
- **工作区导入导出** — JSON 含所有文档内容,一键备份/迁移
|
|
- **主题与设置** — light/dark/system 主题,字号/Tab/换行/防抖等可调
|
|
|
|
## 架构
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 前端 (Svelte 5 + Vite, Web + Tauri 共用) │
|
|
│ ├── 文档编辑: Editor (CM6) + Preview (typst.ts SVG) │
|
|
│ ├── 知识库: KB tree / Dependency graph / Search / History │
|
|
│ ├── 协作: Login / Collaborators / Share / Presence │
|
|
│ └── api/ (HTTP 客户端: JWT Bearer 认证) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│ HTTP (端口 7480)
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Rust 后端 (tokio + hyper) │
|
|
│ ├── 认证: JWT 注册/登录 + 权限校验 │
|
|
│ ├── KB/文档 CRUD + 草稿/发布 + 版本快照 │
|
|
│ ├── 标签 + 搜索 + 分享令牌 + 协作者 │
|
|
│ └── 存储: JSON 文件 (workspace/users/versions/...) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Web**:手动启动后端(`yarn server:dev`),前端通过 `VIZTYP_API_URL` 连接。
|
|
**桌面(Tauri)**:后端作为 sidecar 随应用自动启动,退出时自动清理。
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
yarn install
|
|
yarn workspace frontend install
|
|
|
|
# 桌面端 (推荐, 自动 sidecar)
|
|
yarn dev
|
|
|
|
# Web 端 (后端单独运行)
|
|
yarn server:dev # Rust 后端 (端口 7480)
|
|
yarn frontend:dev # 前端 (端口 5173)
|
|
|
|
yarn frontend:check # 类型检查 (0 错误)
|
|
yarn build # 桌面生产构建
|
|
```
|
|
|
|
**首次运行**:显示登录/注册界面。首个用户自动成为 **owner**(完全访问权限)。
|
|
|
|
## 技术栈
|
|
|
|
| 层 | 选型 |
|
|
|---|---|
|
|
| 前端 | Svelte 5 (runes) + Vite 8 + TypeScript ~6.0 |
|
|
| 编辑器 | CodeMirror 6(自定义思源主题) |
|
|
| Typst | typst.ts `0.7.0`(手动编译器 + 渲染器) |
|
|
| 后端 | Rust:tokio + hyper + serde + jsonwebtoken + sha2 |
|
|
| 桌面 | Tauri v2(自动 sidecar) |
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
viztyp/
|
|
├── packages/frontend/src/
|
|
│ ├── lib/ # 编辑器/IDE/知识库/协作/插件 50+ 模块
|
|
│ │ ├── api/ # Rust 后端 HTTP 客户端
|
|
│ │ └── plugins/ # 内置插件 (word-count-pro, auto-outline)
|
|
│ └── typst/ # 默认欢迎文档
|
|
├── server/ # Rust HTTP 后端 (认证/KB/版本/搜索/分享/协作者)
|
|
├── src-tauri/ # Tauri v2 桌面外壳 (sidecar 启动)
|
|
├── typst-pkg/ # 自研 Typst 库 (viztyp)
|
|
├── scripts/ # 构建辅助 (build-sidecar.sh)
|
|
└── AGENTS.md # 架构与设计文档(双语)
|
|
```
|
|
|
|
## ⚙️ 实现说明
|
|
|
|
1. **`@codemirror/basic-setup` 已废弃** → 改从 `codemirror` umbrella 导入 `basicSetup`。
|
|
2. **typst.svelte `<Typst>` 组件每次按键全量重编译** → 改用手动 compiler + renderer。
|
|
3. **Tauri v2 没有 `app.security.headers`** → COOP/COEP 由 Vite 设置;生产桌面端需自定义 protocol handler(见 `COOP_COEP_NOTES.md`)。
|
|
4. **Rust 后端**(用户决策)→ Web/Tauri 共用一套 HTTP API。
|
|
|
|
## 📜 许可证
|
|
|
|
MIT
|