DaiChaoXiong
/
VizTyp
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
VizTyp/README.zh.md

6.0 KiB
Raw Permalink Blame History

VizTyp

"可本地优先的语雀" + "实时可视化的 MrDoc" 基于 Typst 的个人与团队知识管理系统,通过 typst.ts WASM 实时编译渲染,配合 Rust HTTP 后端。采用思源笔记风格 IDE 布局,面向 Web 和 Tauri 桌面双平台。

English

功能特性

📝 文档编辑

  • 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 随应用自动启动,退出时自动清理。

快速开始

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