# 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