← 返回博客

雨舍：个人数字花园的设计与实现

介绍雨舍个人门户工作站的愿景、知识库博客架构、Obsidian 内容管线和当前 WebOS Shell 进展。

#project#portal#yushe#digital-garden

雨舍：个人数字花园的设计与实现

雨舍（Yushe）是我的个人门户工作站，在线地址为 yushe.ai。它从知识库博客开始，逐步向个人门户、工具站和 AI 应用扩展。

目前已经上线的是一个零后端知识库博客：文章直接来自 Obsidian 知识库，经过构建期解析后生成静态页面。

项目愿景

雨舍长期计划包含四个相互关联的模块：

模块定位
个人门户 / Dashboard聚合常用入口、搜索和日常信息
知识库博客 / Digital Garden从 Obsidian 笔记发布技术文章和项目内容
个人工具站收纳格式化、编解码等高频小工具
个人 AI 应用接入自有模型和自动化管线，处理对话与文本任务

这些模块共享同一套视觉语言和基础设施，但不会同时开发。当前优先把内容管线和基础界面做好，再逐步扩展其他能力。

已上线：知识库博客

雨舍博客采用“知识库即内容源”的方式，不在网站项目里维护一份 Markdown 副本。日常笔记仍然在 Obsidian 中编辑，是否发布由 Markdown 文件顶部的 frontmatter 控制：

yaml
publish: true
type: post
visibility: public
draft: false

实际使用时，公开博客还需要同时满足以下条件：

  • publish 为 true；
  • draft 不是 true；
  • type 为 post；
  • visibility 为 public；
  • 没有设置 password；
  • require_auth 不是 true。

构建系统扫描知识库后，会过滤不应公开的内容，解析 frontmatter 和正文，再生成文章页面、RSS、sitemap 和搜索索引。这样可以把写作、版本控制和发布放在同一个工作流中。

内容管线

内容处理代码位于 yushe/frontend/web/src/lib/content/，主要分为几层：

  1. 内容接入：从 Obsidian 知识库读取 Markdown 文件；
  2. Frontmatter 解析：校验字段并补充默认值；
  3. 发布判断：根据 publish、draft、type 和 visibility 决定内容边界；
  4. 路由与索引：生成 slug，检查冲突，并建立文章和搜索索引；
  5. Markdown 渲染：将 Obsidian Markdown 转换成页面可展示的 HTML。

文章 slug 冲突会直接中止构建，避免两篇文章意外使用同一个地址。断链和其他解析问题会生成构建诊断，方便在发布前处理。

Obsidian 语法支持

博客不是把 Markdown 当作普通纯文本处理，而是针对日常使用的 Obsidian 语法做了适配：

  • 笔记、别名：转换为站内文章链接；
  • 笔记 > 标题：链接到文章中的标题；
  • ![image.png](/kb-assets/image.png)：处理 Obsidian 图片嵌入；
  • > [!note]：渲染 Callout 提示块；
  • <mark>重点内容</mark>：转换为高亮文本；
  • ``：发布时移除；
  • 代码块：使用 Shiki 做语法高亮，并提供复制按钮。

目标笔记不存在或不允许公开时，不会生成指向私有内容的公开链接，构建过程会记录相应 warning。

当前界面

雨舍没有采用传统博客常见的“窄栏内容加大面积留白”布局，而是尝试做成更有空间感的个人工作站：

  • 暖色调暗色主题，避免使用纯黑背景；
  • 背景使用缓慢变化的渐变光斑；
  • 导航使用毛玻璃效果，并支持顶部、底部、左侧和右侧布局；
  • 搜索面板通过统一的层级管理系统显示；
  • 首页和文章列表中的卡片支持鼠标光效与轻微 3D 倾斜；
  • 页面提供响应式布局，并对不支持 backdrop-filter 的环境做降级处理。

WebOS Shell Phase 1

WebOS Shell 的第一阶段已经完成，主要包括：

  • 稀疏的 Z 轴层级常量；
  • LayerManager 和 LayerPortal；
  • 可配置位置的 HUD 导航；
  • StartPanel 命令浮层和全站搜索；
  • 移动端响应式布局；
  • 位置切换动效和 prefers-reduced-motion 降级；
  • 博客文章页的回到顶部按钮。

这里的“WebOS”目前主要指界面组织方式和层级系统，并不是一个完整的桌面窗口操作系统。早期设想中的窗口管理器、桌面网格和复杂应用状态机，目前没有纳入已实现架构。

技术栈与部署

  • Next.js App Router
  • React
  • TypeScript 严格模式
  • Tailwind CSS
  • motion
  • remark / rehype
  • Shiki
  • Vitest
  • pnpm
  • just

项目不依赖数据库。构建时读取知识库内容，生成 Next.js 页面和搜索索引，再通过自托管的 Gitea Actions 完成检查、构建和部署。

工程仓库中的 docs/ 负责记录需求、架构和开发流程；本文只介绍项目本身，不替代工程规格文档。

还没有实现的方向

以下内容仍处于规划阶段：

  • 独立的门户 / Dashboard；
  • 个人工具站；
  • 个人 AI 应用；
  • 数字人的 3D 模型和跨层交互；
  • 动态环境引擎；
  • StartPanel Dashboard Widget；
  • 更复杂的背景和空间层。

这些功能会在真正进入开发后单独记录，不把规划内容写成已经完成的功能。

相关仓库

两者的职责不同：yushe 负责网站如何运行，yushe-knowledge 负责网站展示什么内容。