Ourai.WS共享

个人工作台一期

在浏览器的新标签页中对个人知识库进行管理。由于数据操作是基于本地文件的，相关说明详见《基于文件系统的数据管理一期》，这里只涉及与浏览器插件相关的部分。

需求分析

本项目有如下关键特性：

  • 屏蔽文件、Git、IDE 等概念，尽量纯 GUI 操作，让不太懂电脑的人也能无障碍使用；
  • 自动化提交文件变更；
  • 一键将本地知识库内容部署发布到在线网站。

技术架构大体为：

  • 本地 GUI 应用——Remix、Tailwind CSS、HeroUI（原名 NextUI）、Tiptap、Node.js；
  • 静态网站生成器——Hexo 或 Astro；
  • 本地文件操作——基于 KnoSys 的 SDK 与 CLI；
  • 文件自动化——结合 Git 与 GitHub 可编程基建。

设计

架构：

架构图
架构图

流程：

流程图
流程图

目录结构

项目的文件划分基本骨架为：

ROOT/
   ├── .knosys/         ## KnoSys 相关文件
   │   ├── scripts/     ## 用于 npm scripts 的脚本代码
   │   │   └── ...
   │   └── config.json  ## KnoSys 配置
   ├── public/
   │   └── ...
   ├── src/             ## GUI 应用源码
   │   ├── domain/      ## 按照 DDD 划分领域
   │   │   └── ...
   │   ├── entry/       ## 路由、页面布局等
   │   │   └── ...
   │   ├── shared/      ## 通用的类型定义、工具函数、UI 组件等
   │   │   └── ...
   │   └── ...
   ├── .env.example     ## 环境变量示例
   ├── package.json
   └── ...

其中，domain 文件夹下的文件划分模式为：

domain/
   └── [domain-specific-module]           ## 按照 DDD 划分的具体领域
       ├── views                          ## 各类视图部件（业务 UI 组件）
       │   ├── [detail-view]
       │   │   ├── [DetailView].tsx
       │   │   ├── ...
       │   │   └── index.ts
       │   ├── [form-view]
       │   │   ├── [FormView].tsx
       │   │   ├── ...
       │   │   └── index.ts
       │   └── [list-view]
       │       ├── [ListView].tsx
       │       ├── ...
       │       └── index.ts
       ├── widgets                        ## 可被复用的非视图类部件（业务 UI 组件）
       │   └── [domain-specific-widget]
       │       └── ...
       ├── helper.ts                      ## 领域特定的工具函数
       ├── index.ts
       ├── model.ts                       ## 模型定义
       ├── repository.ts                  ## 资源请求异步函数
       ├── typing.ts                      ## 领域特定的类型定义
       └── ...

上述表达方式中，用中括号包围起来的字符串表示需要根据具体领域以所示格式命名文件夹或文件。

运行环境

首先，请确保 Node.js 版本号符合项目根目录下 package.json 中 engines.node 字段所指定的，包管理器推荐使用 pnpm 且版本为 v9。

技术栈

以下依赖都使用固定版本：

  • Remix v2.16.8
  • tailwindcss@3.4.4
  • @nextui-org/react@2.6.11
  • @knosys/sdk@0.0.3

共享资源

功能模块

需要根据下面各个模块描述章节标题中的英文在 domain 下创建相应的文件夹，并按上文「目录结构」部分对 domain 的相关描述创建文件夹、文件。

应用（App）

存放符合 QiiDB 数据规范的 Git 仓库称作「应用」，且默认数据源是在 ./data 文件夹中。

模型字段
显示文本 数据标识 数据类型 必需 空值占位符 提示说明
名称 name string 是 只允许输入小写英文字母、数字和连字符「-」与下划线「_」
标题 title string 是
默认路径 path string 是 默认为 :category/:collection/:slug :category 部分可省略，:collection 不可缺少，之后的部分为记录的路径模式，详见：https://knosysio.github.io/apis/meta/
LOGO logo string 否
AppInitializer 视图部件

在应用尚未初始化时用来设置一些基本信息，是个分步表单：

  1. 选择本地知识库所在位置，相关逻辑在 AppDirForm 组件中，展示字段详见下方；
  2. 填写信息，相关逻辑在 AppConfigForm 组件中，展示所有模型字段；
  3. 点击「初始化」按钮，在操作系统用户文件夹下生成应用配置文件。

在 AppDirForm 中展示的字段：

显示文本 数据标识 数据类型 必需 空值占位符 提示说明
根文件夹 root string 是 数据源所在本地 Git 仓库的绝对路径 macOS 可打开终端，将目标文件夹拖进去后把完整路径复制出来
数据源 source string 否 在根文件夹内的相对路径，默认为 ./data
AppForm 视图部件

用来后续更新应用信息的表单，展示所有模型字段，其中「名称」和「标题」不可更改。

知识库（Collection）

CollectionList 视图部件
CollectionForm 视图部件

知识（Qii）

QiiList 视图部件
QiiForm 视图部件
QiiDetail 视图部件

系统设置（Settings）